Numeric & Array Types

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,

Uint32

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

Uint64

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

UINT32_MAX_VALUE

UINT32_CEIL_VALUE

UINT64_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

UINT32_MAX_VALUE

UINT32_MAX_VALUE
UINT32_MAX_VALUE = (2**32) - 1

UINT32_CEIL_VALUE

UINT32_CEIL_VALUE
UINT32_CEIL_VALUE = 2**32

UINT64_MAX_VALUE

UINT64_MAX_VALUE
UINT64_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.

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_be_bytes()Bytes

Converts this 256-bit unsigned integer into its big endian representation, omitting leading zero bytes. :returns: big_endian – Big endian (most significant bits first) representation. :rtype: Bytes

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)

Uint32

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

class Uint32(value: int)

Bases: FixedUInt

MAX_VALUE :ClassVar[Uint32]
__slots__ = []
classmethod from_le_bytes(buffer: Bytes)Uint32

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

Uint32.MAX_VALUE
Uint32.MAX_VALUE = int.__new__(Uint32, UINT32_MAX_VALUE)

Uint64

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

class Uint64(value: int)

Bases: FixedUInt

MAX_VALUE :ClassVar[Uint64]
__slots__ = []
classmethod from_le_bytes(buffer: Bytes)Uint64

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

to_be_bytes()Bytes

Converts this unsigned 64 bit integer into its big endian representation.

Returns

big_endian – Big endian (most significant bits first) representation.

Return type

Bytes

classmethod from_be_bytes(buffer: Bytes)Uint64

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

Uint64

MAX_VALUE

Uint64.MAX_VALUE
Uint64.MAX_VALUE = int.__new__(Uint64, UINT64_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