API¶

eth_abi.abi module¶

eth_abi.base module¶

class eth_abi.base.BaseCoder(**kwargs)¶

Bases: object

Base class for all encoder and decoder classes.

classmethod from_type_str(type_str: str, registry) → eth_abi.base.BaseCoder¶: Used by ABIRegistry to get an appropriate encoder or decoder instance for the given type string and type registry.

eth_abi.codec module¶

class eth_abi.codec.ABICodec(registry: eth_abi.registry.ABIRegistry)¶: Bases: eth_abi.codec.ABIEncoder, eth_abi.codec.ABIDecoder

class eth_abi.codec.ABIDecoder(registry: eth_abi.registry.ABIRegistry)¶

Bases: eth_abi.codec.BaseABICoder

Wraps a registry to provide last-mile decoding functionality.

decode(types, data)¶

decode_abi(types: Iterable[str], data: Union[bytes, bytearray]) → Tuple[Any, ...]¶

Decodes the binary value data as a sequence of values of the ABI types in types via the head-tail mechanism into a tuple of equivalent python values.

Parameters:	types – An iterable of string representations of the ABI types that will be used for decoding e.g. `('uint256', 'bytes[]', '(int,int)')` data – The binary value to be decoded.
Returns:	A tuple of equivalent python values for the ABI values represented in `data`.

decode_single(typ: str, data: Union[bytes, bytearray]) → Any¶

Decodes the binary value data of the ABI type typ into its equivalent python value.

Parameters:	typ – The string representation of the ABI type that will be used for decoding e.g. `'uint256'`, `'bytes[]'`, `'(int,int)'`, etc. data – The binary value to be decoded.
Returns:	The equivalent python value of the ABI value represented in `data`.

stream_class¶: alias of eth_abi.decoding.ContextFramesBytesIO

class eth_abi.codec.ABIEncoder(registry: eth_abi.registry.ABIRegistry)¶

Bases: eth_abi.codec.BaseABICoder

Wraps a registry to provide last-mile encoding functionality.

encode(types, args)¶

encode_abi(types: Iterable[str], args: Iterable[Any]) → bytes¶

Encodes the python values in args as a sequence of binary values of the ABI types in types via the head-tail mechanism.

Parameters:	types – An iterable of string representations of the ABI types that will be used for encoding e.g. `('uint256', 'bytes[]', '(int,int)')` args – An iterable of python values to be encoded.
Returns:	The head-tail encoded binary representation of the python values in `args` as values of the ABI types in `types`.

encode_single(typ: str, arg: Any) → bytes¶

Encodes the python value arg as a binary value of the ABI type typ.

Parameters:	typ – The string representation of the ABI type that will be used for encoding e.g. `'uint256'`, `'bytes[]'`, `'(int,int)'`, etc. arg – The python value to be encoded.
Returns:	The binary representation of the python value `arg` as a value of the ABI type `typ`.

is_encodable(typ: str, arg: Any) → bool¶

Determines if the python value arg is encodable as a value of the ABI type typ.

Parameters:	typ – A string representation for the ABI type against which the python value `arg` will be checked e.g. `'uint256'`, `'bytes[]'`, `'(int,int)'`, etc. arg – The python value whose encodability should be checked.
Returns:	`True` if `arg` is encodable as a value of the ABI type `typ`. Otherwise, `False`.

is_encodable_type(typ: str) → bool¶

Returns True if values for the ABI type typ can be encoded by this codec.

Parameters:	typ – A string representation for the ABI type that will be checked for encodability e.g. `'uint256'`, `'bytes[]'`, `'(int,int)'`, etc.
Returns:	`True` if values for `typ` can be encoded by this codec. Otherwise, `False`.

class eth_abi.codec.BaseABICoder(registry: eth_abi.registry.ABIRegistry)¶

Bases: object

Base class for porcelain coding APIs. These are classes which wrap instances of ABIRegistry to provide last-mile coding functionality.

eth_abi.decoding module¶

class eth_abi.decoding.BaseDecoder(**kwargs)¶

Bases: eth_abi.base.BaseCoder

Base class for all decoder classes. Subclass this if you want to define a custom decoder class. Subclasses must also implement BaseCoder.from_type_str.

decode(stream: eth_abi.decoding.ContextFramesBytesIO) → Any¶: Decodes the given stream of bytes into a python value. Should raise exceptions.DecodingError if a python value cannot be decoded from the given byte stream.

eth_abi.encoding module¶

class eth_abi.encoding.BaseEncoder(**kwargs)¶

Bases: eth_abi.base.BaseCoder

Base class for all encoder classes. Subclass this if you want to define a custom encoder class. Subclasses must also implement BaseCoder.from_type_str.

encode(value: Any) → bytes¶: Encodes the given value as a sequence of bytes. Should raise exceptions.EncodingError if value cannot be encoded.

classmethod invalidate_value(value: Any, exc: Type[Exception] = <class 'eth_abi.exceptions.EncodingTypeError'>, msg: Optional[str] = None) → None¶: Throws a standard exception for when a value is not encodable by an encoder.

validate_value(value: Any) → None¶: Checks whether or not the given value can be encoded by this encoder. If the given value cannot be encoded, must raise exceptions.EncodingError.

eth_abi.exceptions module¶

exception eth_abi.exceptions.ABITypeError¶

Bases: ValueError

Raised when a parsed ABI type has inconsistent properties; for example, when trying to parse the type string 'uint7' (which has a bit-width that is not congruent with zero modulo eight).

exception eth_abi.exceptions.DecodingError¶

Bases: Exception

Base exception for any error that occurs during decoding.

exception eth_abi.exceptions.EncodingError¶

Bases: Exception

Base exception for any error that occurs during encoding.

exception eth_abi.exceptions.EncodingTypeError¶

Bases: eth_abi.exceptions.EncodingError

Raised when trying to encode a python value whose type is not supported for the output ABI type.

exception eth_abi.exceptions.IllegalValue¶

Bases: eth_abi.exceptions.EncodingError

Raised when trying to encode a python value with the correct type but with a value that is not considered legal for the output ABI type.

Example:

fixed128x19_encoder(Decimal('NaN'))  # cannot encode NaN

exception eth_abi.exceptions.InsufficientDataBytes¶

Bases: eth_abi.exceptions.DecodingError

Raised when there are insufficient data to decode a value for a given ABI type.

exception eth_abi.exceptions.MultipleEntriesFound¶

Bases: ValueError, eth_abi.exceptions.PredicateMappingError

Raised when multiple registrations are found for a type string in a registry’s internal mapping. This error is non-recoverable and indicates that a registry was configured incorrectly. Registrations are expected to cover completely distinct ranges of type strings.

Warning

In a future version of eth-abi, this error class will no longer inherit from ValueError.

exception eth_abi.exceptions.NoEntriesFound¶

Bases: ValueError, eth_abi.exceptions.PredicateMappingError

Raised when no registration is found for a type string in a registry’s internal mapping.

Warning

In a future version of eth-abi, this error class will no longer inherit from ValueError.

exception eth_abi.exceptions.NonEmptyPaddingBytes¶

Bases: eth_abi.exceptions.DecodingError

Raised when the padding bytes of an ABI value are malformed.

exception eth_abi.exceptions.ParseError(text, pos=-1, expr=None)¶

Bases: parsimonious.exceptions.ParseError

Raised when an ABI type string cannot be parsed.

exception eth_abi.exceptions.PredicateMappingError¶

Bases: Exception

Raised when an error occurs in a registry’s internal mapping.

exception eth_abi.exceptions.ValueOutOfBounds¶

Bases: eth_abi.exceptions.IllegalValue

Raised when trying to encode a python value with the correct type but with a value that appears outside the range of valid values for the output ABI type.

Example:

ufixed8x1_encoder(Decimal('25.6'))  # out of bounds

eth_abi.registry module¶

class eth_abi.registry.ABIRegistry¶

copy()¶: Copies a registry such that new registrations can be made or existing registrations can be unregistered without affecting any instance from which a copy was obtained. This is useful if an existing registry fulfills most of a user’s needs but requires one or two modifications. In that case, a copy of that registry can be obtained and the necessary changes made without affecting the original registry.

has_encoder(type_str: str) → bool¶: Returns True if an encoder is found for the given type string type_str. Otherwise, returns False. Raises MultipleEntriesFound if multiple encoders are found.

register(lookup: Union[str, Callable[[str], bool]], encoder: Union[Callable[[Any], bytes], Type[eth_abi.encoding.BaseEncoder]], decoder: Union[Callable[[eth_abi.decoding.ContextFramesBytesIO], Any], Type[eth_abi.decoding.BaseDecoder]], label: str = None) → None¶

Registers the given encoder and decoder under the given lookup. A unique string label may be optionally provided that can be used to refer to the registration by name.

Parameters:

lookup – A type string or type string matcher function (predicate). When the registry is queried with a type string query to determine which encoder or decoder to use, query will be checked against every registration in the registry. If a registration was created with a type string for lookup, it will be considered a match if lookup == query. If a registration was created with a matcher function for lookup, it will be considered a match if lookup(query) is True. If more than one registration is found to be a match, then an exception is raised.
encoder – An encoder callable or class to use if lookup matches a query. If encoder is a callable, it must accept a python value and return a bytes value. If encoder is a class, it must be a valid subclass of encoding.BaseEncoder and must also implement the from_type_str method on base.BaseCoder.
decoder – A decoder callable or class to use if lookup matches a query. If decoder is a callable, it must accept a stream-like object of bytes and return a python value. If decoder is a class, it must be a valid subclass of decoding.BaseDecoder and must also implement the from_type_str method on base.BaseCoder.
label – An optional label that can be used to refer to this registration by name. This label can be used to unregister an entry in the registry via the unregister method and its variants.

register_decoder(lookup: Union[str, Callable[[str], bool]], decoder: Union[Callable[[eth_abi.decoding.ContextFramesBytesIO], Any], Type[eth_abi.decoding.BaseDecoder]], label: str = None) → None¶: Registers the given decoder under the given lookup. A unique string label may be optionally provided that can be used to refer to the registration by name. For more information about arguments, refer to register.

register_encoder(lookup: Union[str, Callable[[str], bool]], encoder: Union[Callable[[Any], bytes], Type[eth_abi.encoding.BaseEncoder]], label: str = None) → None¶: Registers the given encoder under the given lookup. A unique string label may be optionally provided that can be used to refer to the registration by name. For more information about arguments, refer to register.

unregister(label: str) → None¶: Unregisters the entries in the encoder and decoder registries which have the label label.

unregister_decoder(lookup_or_label: Union[str, Callable[[str], bool]]) → None¶: Unregisters a decoder in the registry with the given lookup or label. If lookup_or_label is a string, the decoder with the label lookup_or_label will be unregistered. If it is an function, the decoder with the lookup function lookup_or_label will be unregistered.

unregister_encoder(lookup_or_label: Union[str, Callable[[str], bool]]) → None¶: Unregisters an encoder in the registry with the given lookup or label. If lookup_or_label is a string, the encoder with the label lookup_or_label will be unregistered. If it is an function, the encoder with the lookup function lookup_or_label will be unregistered.

eth_abi.grammar module¶

class eth_abi.grammar.ABIType(arrlist=None, node=None)¶

Base class for results of type string parsing operations.

arrlist¶: The list of array dimensions for a parsed type. Equal to None if type string has no array dimensions.

is_array¶: Equal to True if a type is an array type (i.e. if it has an array dimension list). Otherwise, equal to False.

is_dynamic¶: Equal to True if a type has a dynamically sized encoding. Otherwise, equal to False.

item_type¶: If this type is an array type, equal to an appropriate ABIType instance for the array’s items.

node¶: The parsimonious Node instance associated with this parsed type. Used to generate error messages for invalid types.

to_type_str()¶: Returns the string representation of an ABI type. This will be equal to the type string from which it was created.

validate()¶

Validates the properties of an ABI type against the solidity ABI spec:

https://solidity.readthedocs.io/en/develop/abi-spec.html

Raises ABITypeError if validation fails.

class eth_abi.grammar.TupleType(components, arrlist=None, *, node=None)¶

Represents the result of parsing a tuple type string e.g. “(int,bool)”.

components¶: A tuple of ABIType instances for each of the tuple type’s components.

is_dynamic¶: Equal to True if a type has a dynamically sized encoding. Otherwise, equal to False.

item_type¶: If this type is an array type, equal to an appropriate ABIType instance for the array’s items.

to_type_str()¶: Returns the string representation of an ABI type. This will be equal to the type string from which it was created.

validate()¶

Validates the properties of an ABI type against the solidity ABI spec:

https://solidity.readthedocs.io/en/develop/abi-spec.html

Raises ABITypeError if validation fails.

class eth_abi.grammar.BasicType(base, sub=None, arrlist=None, *, node=None)¶

Represents the result of parsing a basic type string e.g. “uint”, “address”, “ufixed128x19[][2]”.

base¶: The base of a basic type e.g. “uint” for “uint256” etc.

is_dynamic¶: Equal to True if a type has a dynamically sized encoding. Otherwise, equal to False.

item_type¶: If this type is an array type, equal to an appropriate ABIType instance for the array’s items.

sub¶: The sub type of a basic type e.g. 256 for “uint256” or (128, 18) for “ufixed128x18” etc. Equal to None if type string has no sub type.

to_type_str()¶: Returns the string representation of an ABI type. This will be equal to the type string from which it was created.

validate()¶

Validates the properties of an ABI type against the solidity ABI spec:

https://solidity.readthedocs.io/en/develop/abi-spec.html

Raises ABITypeError if validation fails.

eth_abi.grammar.normalize(type_str)¶

Normalizes a type string into its canonical version e.g. the type string ‘int’ becomes ‘int256’, etc.

Parameters:	type_str – The type string to be normalized.
Returns:	The canonical version of the input type string.

eth_abi.grammar.parse(type_str)¶

Parses a type string into an appropriate instance of ABIType. If a type string cannot be parsed, throws ParseError.

Parameters:	type_str – The type string to be parsed.
Returns:	An instance of `ABIType` containing information about the parsed type string.

API¶

eth_abi.abi module¶

eth_abi.base module¶

eth_abi.codec module¶

eth_abi.decoding module¶

eth_abi.encoding module¶

eth_abi.exceptions module¶

eth_abi.registry module¶

eth_abi.grammar module¶

eth_abi.tools module¶