Numeric & Array Types

Table of Contents

Introduction

Integer and array types which are used by—but not unique to—Ethereum.

Module Contents

Classes

`Uint`	Unsigned positive integer.
`FixedUInt`	Superclass for fixed size unsigned integers. Not intended to be used
`U256`	Unsigned positive integer, which can represent 0 to 2 ** 256 - 1,
`U32`	Unsigned positive integer, which can represent 0 to 2 ** 32 - 1,
`U64`	Unsigned positive integer, which can represent 0 to 2 ** 64 - 1,
`FixedBytes`	Superclass for fixed sized byte arrays. Not intended to be used directly,
`Bytes0`	Byte array of exactly zero elements.
`Bytes4`	Byte array of exactly four elements.
`Bytes8`	Byte array of exactly eight elements.
`Bytes20`	Byte array of exactly 20 elements.
`Bytes32`	Byte array of exactly 32 elements.
`Bytes64`	Byte array of exactly 64 elements.
`Bytes256`	Byte array of exactly 256 elements.

Functions

`_setattr_function`
`_delattr_function`
`_make_init_function`
`slotted_freezable`	Monkey patches a dataclass so it can be frozen by setting _frozen to
`modify`	Create a mutable copy of obj (which must be @slotted_freezable) and

Attributes

`U8_MAX_VALUE`
`U32_MAX_VALUE`
`U32_CEIL_VALUE`
`U64_MAX_VALUE`
`U255_MAX_VALUE`
`U255_CEIL_VALUE`
`U256_MAX_VALUE`
`U256_CEIL_VALUE`
`T`
`B`
`Bytes`
`S`

Module Details

U8_MAX_VALUE

U8_MAX_VALUE

U8_MAX_VALUE = (2**8) - 1

U32_MAX_VALUE

U32_MAX_VALUE

U32_MAX_VALUE = (2**32) - 1

U32_CEIL_VALUE

U32_CEIL_VALUE

U32_CEIL_VALUE = 2**32

U64_MAX_VALUE

U64_MAX_VALUE

U64_MAX_VALUE = (2**64) - 1

U255_MAX_VALUE

U255_MAX_VALUE

U255_MAX_VALUE = (2**255) - 1

U255_CEIL_VALUE

U255_CEIL_VALUE

U255_CEIL_VALUE = 2**255

U256_MAX_VALUE

U256_MAX_VALUE

U256_MAX_VALUE = (2**256) - 1

U256_CEIL_VALUE

U256_CEIL_VALUE

U256_CEIL_VALUE = 2**256

Uint

Unsigned positive integer.

class Uint(value: int)

Bases: int

__slots__ = []

classmethod from_be_bytes(buffer: Bytes) → Uint 

Converts a sequence of bytes into an arbitrarily sized unsigned integer from its big endian representation. :param buffer: Bytes to decode.

Returns: self – Unsigned integer decoded from buffer.
Return type: Uint

classmethod from_le_bytes(buffer: Bytes) → Uint : Convert a series of little endian bytes to an unsigned integer.

__radd__(left: int) → Uint : Return value+self.

__add__(right: int) → Uint : Return self+value.

__iadd__(right: int) → Uint 

__sub__(right: int) → Uint : Return self-value.

__rsub__(left: int) → Uint : Return value-self.

__isub__(right: int) → Uint 

__mul__(right: int) → Uint : Return self*value.

__rmul__(left: int) → Uint : Return value*self.

__imul__(right: int) → Uint 

__floordiv__(right: int) → Uint : Return self//value.

__rfloordiv__(left: int) → Uint : Return value//self.

__ifloordiv__(right: int) → Uint 

__mod__(right: int) → Uint : Return self%value.

__rmod__(left: int) → Uint : Return value%self.

__imod__(right: int) → Uint 

__divmod__(right: int) → Tuple[Uint, Uint]: Return divmod(self, value).

__rdivmod__(left: int) → Tuple[Uint, Uint]: Return divmod(value, self).

__pow__(right: int, modulo: Optional[int] = None) → Uint : Return pow(self, value, mod).

__rpow__(left: int, modulo: Optional[int] = None) → Uint : Return pow(value, self, mod).

__ipow__(right: int, modulo: Optional[int] = None) → Uint 

__xor__(right: int) → Uint : Return self^value.

__rxor__(left: int) → Uint : Return value^self.

__ixor__(right: int) → Uint 

to_be_bytes32() → Bytes32 : Converts this arbitrarily sized unsigned integer into its big endian representation with exactly 32 bytes. :returns: big_endian – Big endian (most significant bits first) representation. :rtype: Bytes32

to_be_bytes() → Bytes : Converts this arbitrarily sized unsigned integer into its big endian representation. :returns: big_endian – Big endian (most significant bits first) representation. :rtype: Bytes

to_le_bytes(number_bytes: int = None) → Bytes 

Converts this arbitrarily sized unsigned integer into its little endian representation.

Parameters: number_bytes – Exact number of bytes to return (defaults to the fewest that can represent this number.)
Returns: little_endian – Little endian (most significant bits last) representation.
Return type: Bytes

T

T

T = TypeVar("T", bound="FixedUInt")

FixedUInt

Superclass for fixed size unsigned integers. Not intended to be used directly, but rather to be subclassed.

class FixedUInt(value: int)

Bases: int

MAX_VALUE :ClassVar[FixedUInt]

__slots__ = []

__radd__(left: int) → T : Return value+self.

__add__(right: int) → T : Return self+value.

wrapping_add(right: int) → T 

Return a new instance containing self + right (mod N).

Parameters: right – Other operand for addition.
Returns: sum – The result of adding self and right, wrapped.
Return type: T

__iadd__(right: int) → T 

__sub__(right: int) → T : Return self-value.

wrapping_sub(right: int) → T 

Return a new instance containing self - right (mod N).

Parameters: right – Subtrahend operand for subtraction.
Returns: difference – The result of subtracting right from self, wrapped.
Return type: T

__rsub__(left: int) → T : Return value-self.

__isub__(right: int) → T 

__mul__(right: int) → T : Return self*value.

wrapping_mul(right: int) → T 

Return a new instance containing self * right (mod N).

Parameters: right – Other operand for multiplication.
Returns: product – The result of multiplying self by right, wrapped.
Return type: T

__rmul__(left: int) → T : Return value*self.

__imul__(right: int) → T 

__floordiv__(right: int) → T : Return self//value.

__rfloordiv__(left: int) → T : Return value//self.

__ifloordiv__(right: int) → T 

__mod__(right: int) → T : Return self%value.

__rmod__(left: int) → T : Return value%self.

__imod__(right: int) → T 

__divmod__(right: int) → Tuple[T, T]: Return divmod(self, value).

__rdivmod__(left: int) → Tuple[T, T]: Return divmod(value, self).

__pow__(right: int, modulo: Optional[int] = None) → T : Return pow(self, value, mod).

wrapping_pow(right: int, modulo: Optional[int] = None) → T 

Return a new instance containing self ** right (mod modulo).

Parameters

right – Exponent operand.
modulo – Optional modulus (defaults to MAX_VALUE + 1.)

Returns

power – The result of raising self to the power of right, wrapped.

Return type

T

__rpow__(left: int, modulo: Optional[int] = None) → T : Return pow(value, self, mod).

__ipow__(right: int, modulo: Optional[int] = None) → T 

__and__(right: int) → T : Return self&value.

__or__(right: int) → T : Return self|value.

__xor__(right: int) → T : Return self^value.

__rxor__(left: int) → T : Return value^self.

__ixor__(right: int) → T 

__invert__() → T : ~self

__rshift__(shift_by: int) → T : Return self>>value.

to_be_bytes() → Bytes 

Converts this unsigned integer into its big endian representation, omitting leading zero bytes.

Returns: big_endian – Big endian (most significant bits first) representation.
Return type: Bytes

U256

Unsigned positive integer, which can represent 0 to 2 ** 256 - 1, inclusive.

class U256(value: int)

Bases: FixedUInt

MAX_VALUE :ClassVar[U256]

__slots__ = []

classmethod from_be_bytes(buffer: Bytes) → U256 

Converts a sequence of bytes into an arbitrarily sized unsigned integer from its big endian representation. :param buffer: Bytes to decode.

Returns: self – Unsigned integer decoded from buffer.
Return type: U256

classmethod from_signed(value: int) → U256 

Converts a signed number into a 256-bit unsigned integer. :param value: Signed number

Returns: self – Unsigned integer obtained from value.
Return type: U256

to_be_bytes32() → Bytes32 : Converts this 256-bit unsigned integer into its big endian representation with exactly 32 bytes. :returns: big_endian – Big endian (most significant bits first) representation. :rtype: Bytes32

to_signed() → int: Converts this 256-bit unsigned integer into a signed integer. :returns: signed_int – Signed integer obtained from 256-bit unsigned integer. :rtype: int

MAX_VALUE

U256.MAX_VALUE

U256.MAX_VALUE = int.__new__(U256, U256_MAX_VALUE)

U32

Unsigned positive integer, which can represent 0 to 2 ** 32 - 1, inclusive.

class U32(value: int)

Bases: FixedUInt

MAX_VALUE :ClassVar[U32]

__slots__ = []

classmethod from_le_bytes(buffer: Bytes) → U32 : Converts a sequence of bytes into an arbitrarily sized unsigned integer from its little endian representation.

to_le_bytes4() → Bytes4 

Converts this fixed sized unsigned integer into its little endian representation, with exactly 4 bytes.

Returns: little_endian – Little endian (most significant bits last) representation.
Return type: Bytes4

to_le_bytes() → Bytes 

Converts this fixed sized unsigned integer into its little endian representation, in the fewest bytes possible.

Returns: little_endian – Little endian (most significant bits last) representation.
Return type: Bytes

MAX_VALUE

U32.MAX_VALUE

U32.MAX_VALUE = int.__new__(U32, U32_MAX_VALUE)

U64

Unsigned positive integer, which can represent 0 to 2 ** 64 - 1, inclusive.

class U64(value: int)

Bases: FixedUInt

MAX_VALUE :ClassVar[U64]

__slots__ = []

classmethod from_le_bytes(buffer: Bytes) → U64 : Converts a sequence of bytes into an arbitrarily sized unsigned integer from its little endian representation.

to_le_bytes8() → Bytes8 

Converts this fixed sized unsigned integer into its little endian representation, with exactly 8 bytes.

Returns: little_endian – Little endian (most significant bits last) representation.
Return type: Bytes8

to_le_bytes() → Bytes 

Converts this fixed sized unsigned integer into its little endian representation, in the fewest bytes possible.

Returns: little_endian – Little endian (most significant bits last) representation.
Return type: Bytes

classmethod from_be_bytes(buffer: Bytes) → U64 

Converts a sequence of bytes into an unsigned 64 bit integer from its big endian representation.

Parameters: buffer – Bytes to decode.
Returns: self – Unsigned integer decoded from buffer.
Return type: U64

MAX_VALUE

U64.MAX_VALUE

U64.MAX_VALUE = int.__new__(U64, U64_MAX_VALUE)

B

B

B = TypeVar("B", bound="FixedBytes")

FixedBytes

Superclass for fixed sized byte arrays. Not intended to be used directly, but should be subclassed.

class FixedBytes

Bases: bytes

LENGTH :int

__slots__ = []

Bytes0

Byte array of exactly zero elements.

class Bytes0

Bases: FixedBytes

LENGTH = 0

Bytes4

Byte array of exactly four elements.

class Bytes4

Bases: FixedBytes

LENGTH = 4

Bytes8

Byte array of exactly eight elements.

class Bytes8

Bases: FixedBytes

LENGTH = 8

Bytes20

Byte array of exactly 20 elements.

class Bytes20

Bases: FixedBytes

LENGTH = 20

Bytes32

Byte array of exactly 32 elements.

class Bytes32

Bases: FixedBytes

LENGTH = 32

Bytes64

Byte array of exactly 64 elements.

class Bytes64

Bases: FixedBytes

LENGTH = 64

Bytes256

Byte array of exactly 256 elements.

class Bytes256

Bases: FixedBytes

LENGTH = 256

Bytes

Bytes

Bytes = bytes

_setattr_function

_setattr_function(self: Any, attr: str, value: Any) → None

def _setattr_function(self: Any, attr: str, value: Any) -> None:
    if getattr(self, "_frozen", None):
        raise Exception("Mutating frozen dataclasses is not allowed.")
    else:
        object.__setattr__(self, attr, value)

_delattr_function

_delattr_function(self: Any, attr: str) → None

def _delattr_function(self: Any, attr: str) -> None:
    if self._frozen:
        raise Exception("Mutating frozen dataclasses is not allowed.")
    else:
        object.__delattr__(self, attr)

_make_init_function

_make_init_function(f: Callable) → Callable

def _make_init_function(f: Callable) -> Callable:
    def init_function(self: Any, *args: Any, **kwargs: Any) -> None:
        will_be_frozen = kwargs.pop("_frozen", True)
        object.__setattr__(self, "_frozen", False)
        f(self, *args, **kwargs)
        self._frozen = will_be_frozen

    return init_function

slotted_freezable

slotted_freezable(cls: Any) → Any

Monkey patches a dataclass so it can be frozen by setting _frozen to True and uses __slots__ for efficiency.

Instances will be created frozen by default unless you pass _frozen=False to __init__.

def slotted_freezable(cls: Any) -> Any:
    cls.__slots__ = ("_frozen",) + tuple(cls.__annotations__)
    cls.__init__ = _make_init_function(cls.__init__)
    cls.__setattr__ = _setattr_function
    cls.__delattr__ = _delattr_function
    return type(cls)(cls.__name__, cls.__bases__, dict(cls.__dict__))

S

S

S = TypeVar("S")

modify

modify(obj: S, f: Callable[[S], None]) → S 

Create a mutable copy of obj (which must be @slotted_freezable) and apply f to the copy before freezing it.

Parameters

obj (S) – Object to copy.
f (Callable[[S], None]) – Function to apply to obj.

Returns

new_obj – Compact byte array.

Return type

S

def modify(obj: S, f: Callable[[S], None]) -> S:
    new_obj = replace(obj, _frozen=False)
    f(new_obj)
    new_obj._frozen = True  # type: ignore
    return new_obj