faster-eth-abi 5.2.25__cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl

faster_eth_abi/exceptions.py

@@ -0,0 +1,127 @@
+# mypy: disable-error-code="misc"
+# cannot subclass `Any`
+
+"""
+Exception classes for error handling during ABI encoding and decoding operations.
+
+faster-eth-abi exceptions always inherit from eth-abi exceptions, so porting to faster-eth-abi
+does not require any change to your existing exception handlers. They will continue to work.
+"""
+
+import eth_abi.exceptions
+
+
+class EncodingError(eth_abi.exceptions.EncodingError):
+    """
+    Base exception for any error that occurs during encoding.
+    """
+
+
+class EncodingTypeError(EncodingError, eth_abi.exceptions.EncodingTypeError):
+    """
+    Raised when trying to encode a python value whose type is not supported for
+    the output ABI type.
+    """
+
+
+class IllegalValue(EncodingError, eth_abi.exceptions.IllegalValue):
+    """
+    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.
+
+    .. code-block:: python
+
+        fixed128x19_encoder(Decimal('NaN'))  # cannot encode NaN
+
+    """
+
+
+class ValueOutOfBounds(IllegalValue, eth_abi.exceptions.ValueOutOfBounds):
+    """
+    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.
+
+    .. code-block:: python
+
+        ufixed8x1_encoder(Decimal('25.6'))  # out of bounds
+
+    """
+
+
+class DecodingError(eth_abi.exceptions.DecodingError):
+    """
+    Base exception for any error that occurs during decoding.
+    """
+
+
+class InsufficientDataBytes(DecodingError, eth_abi.exceptions.InsufficientDataBytes):
+    """
+    Raised when there are insufficient data to decode a value for a given ABI type.
+    """
+
+
+class NonEmptyPaddingBytes(DecodingError, eth_abi.exceptions.NonEmptyPaddingBytes):
+    """
+    Raised when the padding bytes of an ABI value are malformed.
+    """
+
+
+class InvalidPointer(DecodingError, eth_abi.exceptions.InvalidPointer):
+    """
+    Raised when the pointer to a value in the ABI encoding is invalid.
+    """
+
+
+class ParseError(eth_abi.exceptions.ParseError):
+    """
+    Raised when an ABI type string cannot be parsed.
+    """
+
+    def __str__(self) -> str:
+        return (
+            f"Parse error at '{self.text[self.pos : self.pos + 5]}' "
+            f"(column {self.column()}) in type string '{self.text}'"
+        )
+
+
+class ABITypeError(eth_abi.exceptions.ABITypeError):
+    """
+    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).
+    """
+
+
+class PredicateMappingError(eth_abi.exceptions.PredicateMappingError):
+    """
+    Raised when an error occurs in a registry's internal mapping.
+    """
+
+
+class NoEntriesFound(PredicateMappingError, eth_abi.exceptions.NoEntriesFound):
+    """
+    Raised when no registration is found for a type string in a registry's
+    internal mapping.
+
+    .. warning::
+
+        In a future version of ``faster-eth-abi``, this error class will no longer
+        inherit from ``ValueError``.
+    """
+
+
+class MultipleEntriesFound(
+    PredicateMappingError, eth_abi.exceptions.MultipleEntriesFound
+):
+    """
+    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 ``faster-eth-abi``, this error class will no longer
+        inherit from ``ValueError``.
+    """

faster_eth_abi/from_type_str.py

@@ -0,0 +1,141 @@
+"""Helpers for parsing and normalizing ABI type strings.
+
+Provides decorators and utilities for implementing from_type_str methods on coder classes.
+"""
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Optional,
+    Type,
+    TypeVar,
+)
+
+from eth_typing import (
+    TypeStr,
+)
+
+from ._grammar import (
+    ABIType,
+    BasicType,
+    TupleType,
+    normalize,
+)
+from .grammar import (
+    parse,
+)
+
+if TYPE_CHECKING:
+    from .base import (
+        BaseCoder,
+    )
+
+
+TType = TypeVar("TType", bound=Type["BaseCoder"])
+OldFromTypeStr = Callable[["BaseCoder", ABIType, Any], TType]
+if TYPE_CHECKING:
+    NewFromTypeStr = classmethod[TType, [TypeStr, Any], TType]
+
+
+def parse_type_str(
+    expected_base: Optional[str] = None,
+    with_arrlist: bool = False,
+) -> Callable[[OldFromTypeStr[TType]], "NewFromTypeStr[TType]"]:
+    """
+    Used by BaseCoder subclasses as a convenience for implementing the
+    ``from_type_str`` method required by ``ABIRegistry``.  Useful if normalizing
+    then parsing a type string with an (optional) expected base is required in
+    that method.
+    """
+
+    def decorator(old_from_type_str: OldFromTypeStr[TType]) -> "NewFromTypeStr[TType]":
+        @functools.wraps(old_from_type_str)
+        def new_from_type_str(cls: TType, type_str: TypeStr, registry: Any) -> TType:
+            normalized_type_str = normalize(type_str)
+            abi_type = parse(normalized_type_str)
+
+            type_str_repr = repr(type_str)
+            if type_str != normalized_type_str:
+                type_str_repr = (
+                    f"{type_str_repr} (normalized to {normalized_type_str!r})"
+                )
+
+            if expected_base is not None:
+                if not isinstance(abi_type, BasicType):
+                    raise ValueError(
+                        "Cannot create {} for non-basic type {}".format(
+                            cls.__name__,
+                            type_str_repr,
+                        )
+                    )
+                if abi_type.base != expected_base:
+                    raise ValueError(
+                        "Cannot create {} for type {}: expected type with "
+                        "base '{}'".format(
+                            cls.__name__,
+                            type_str_repr,
+                            expected_base,
+                        )
+                    )
+
+            if not with_arrlist and abi_type.arrlist is not None:
+                raise ValueError(
+                    "Cannot create {} for type {}: expected type with "
+                    "no array dimension list".format(
+                        cls.__name__,
+                        type_str_repr,
+                    )
+                )
+            if with_arrlist and abi_type.arrlist is None:
+                raise ValueError(
+                    "Cannot create {} for type {}: expected type with "
+                    "array dimension list".format(
+                        cls.__name__,
+                        type_str_repr,
+                    )
+                )
+
+            # Perform general validation of default solidity types
+            abi_type.validate()
+
+            return old_from_type_str(cls, abi_type, registry)
+
+        return classmethod(new_from_type_str)
+
+    return decorator
+
+
+def parse_tuple_type_str(
+    old_from_type_str: OldFromTypeStr[TType],
+) -> "NewFromTypeStr[TType]":
+    """
+    Used by BaseCoder subclasses as a convenience for implementing the
+    ``from_type_str`` method required by ``ABIRegistry``.  Useful if normalizing
+    then parsing a tuple type string is required in that method.
+    """
+
+    @functools.wraps(old_from_type_str)
+    def new_from_type_str(cls: TType, type_str: TypeStr, registry: Any) -> TType:
+        normalized_type_str = normalize(type_str)
+        abi_type = parse(normalized_type_str)
+
+        if not isinstance(abi_type, TupleType):
+            type_str_repr = repr(type_str)
+            if type_str != normalized_type_str:
+                type_str_repr = "{} (normalized to {})".format(
+                    type_str_repr,
+                    repr(normalized_type_str),
+                )
+            raise ValueError(
+                "Cannot create {} for non-tuple type {}".format(
+                    cls.__name__,
+                    type_str_repr,
+                )
+            )
+
+        abi_type.validate()
+
+        return old_from_type_str(cls, abi_type, registry)
+
+    return classmethod(new_from_type_str)

faster_eth_abi/grammar.py

@@ -0,0 +1,179 @@
+"""Parsing and normalization logic for ABI type strings.
+
+Implements grammar, parsing, and type validation for ABI type strings.
+"""
+import functools
+from typing import (
+    Any,
+    Final,
+    TYPE_CHECKING,
+    final,
+)
+
+import parsimonious
+from eth_typing import (
+    TypeStr,
+)
+from parsimonious import (
+    expressions,
+)
+
+from faster_eth_abi._grammar import (
+    TYPE_ALIAS_RE,
+    TYPE_ALIASES,
+    ABIType,
+    BasicType,
+    TupleType,
+    normalize,
+)
+from faster_eth_abi.exceptions import (
+    ParseError,
+)
+
+grammar: Final = parsimonious.Grammar(
+    r"""
+    type = tuple_type / basic_type
+
+    tuple_type = components arrlist?
+    components = non_zero_tuple
+
+    non_zero_tuple = "(" type next_type* ")"
+    next_type = "," type
+
+    basic_type = base sub? arrlist?
+
+    base = alphas
+
+    sub = two_size / digits
+    two_size = (digits "x" digits)
+
+    arrlist = (const_arr / dynam_arr)+
+    const_arr = "[" digits "]"
+    dynam_arr = "[]"
+
+    alphas = ~"[A-Za-z]+"
+    digits = ~"[1-9][0-9]*"
+    """
+)
+
+
+if TYPE_CHECKING:
+    _NodeVisitorBase = parsimonious.NodeVisitor[ABIType]
+else:
+    _NodeVisitorBase = parsimonious.NodeVisitor
+
+
+@final
+class NodeVisitor(_NodeVisitorBase):
+    """
+    Parsimonious node visitor which performs both parsing of type strings and
+    post-processing of parse trees.  Parsing operations are cached.
+    """
+
+    def __init__(self) -> None:
+        self.parse: Final = functools.lru_cache(maxsize=None)(self._parse_uncached)
+
+    grammar = grammar
+
+    def visit_non_zero_tuple(self, node, visited_children):
+        # Ignore left and right parens
+        _, first, rest, _ = visited_children
+
+        return (first,) + rest
+
+    def visit_tuple_type(self, node, visited_children):
+        components, arrlist = visited_children
+
+        return TupleType(components, arrlist, node=node)
+
+    def visit_next_type(self, node, visited_children):
+        # Ignore comma
+        _, abi_type = visited_children
+
+        return abi_type
+
+    def visit_basic_type(self, node, visited_children):
+        base, sub, arrlist = visited_children
+
+        return BasicType(base, sub, arrlist, node=node)
+
+    def visit_two_size(self, node, visited_children):
+        # Ignore "x"
+        first, _, second = visited_children
+
+        return first, second
+
+    def visit_const_arr(self, node, visited_children):
+        # Ignore left and right brackets
+        _, int_value, _ = visited_children
+
+        return (int_value,)
+
+    def visit_dynam_arr(self, node, visited_children):
+        return ()
+
+    def visit_alphas(self, node, visited_children):
+        return node.text
+
+    def visit_digits(self, node, visited_children):
+        return int(node.text)
+
+    def generic_visit(self, node, visited_children):
+        expr = node.expr
+        if isinstance(expr, expressions.OneOf):
+            # Unwrap value chosen from alternatives
+            return visited_children[0]
+
+        if isinstance(expr, expressions.Quantifier) and expr.min == 0 and expr.max == 1:
+            # Unwrap optional value or return `None`
+            if len(visited_children) != 0:
+                return visited_children[0]
+
+            return None
+
+        return tuple(visited_children)
+
+    def _parse_uncached(self, type_str: TypeStr, **kwargs: Any) -> ABIType:
+        """
+        Parses a type string into an appropriate instance of
+        :class:`~faster_eth_abi.grammar.ABIType`.  If a type string cannot be parsed,
+        throws :class:`~faster_eth_abi.exceptions.ParseError`.
+
+        :param type_str: The type string to be parsed.
+        :returns: An instance of :class:`~faster_eth_abi.grammar.ABIType` containing
+            information about the parsed type string.
+        """
+        if not isinstance(type_str, str):
+            raise TypeError(f"Can only parse string values: got {type(type_str)}")
+
+        try:
+            return super().parse(type_str, **kwargs)
+        except parsimonious.ParseError as e:
+            # This is a good place to add some better messaging around the type string.
+            # If this logic grows any bigger, we should abstract it to its own function.
+            if "()" in type_str:
+                # validate against zero-sized tuple types
+                raise ValueError(
+                    'Zero-sized tuple types "()" are not supported.'
+                ) from None
+
+            raise ParseError(e.text, e.pos, e.expr) from e
+
+
+visitor: Final = NodeVisitor()
+
+parse: Final = visitor.parse
+
+
+__all__ = [
+    "NodeVisitor",
+    "ABIType",
+    "TupleType",
+    "BasicType",
+    "grammar",
+    "parse",
+    "normalize",
+    "visitor",
+    "TYPE_ALIASES",
+    "TYPE_ALIAS_RE",
+]

faster_eth_abi/io.py

@@ -0,0 +1,137 @@
+"""
+Context-aware byte stream for ABI decoding.
+
+Implements a lightweight frame-aware reader that avoids BytesIO overhead in hot decoding paths.
+"""
+from typing import (
+    Any,
+    Final,
+    final,
+)
+
+
+@final
+class ContextFramesBytesIO:
+    """
+    A byte stream which can track a series of contextual frames in a stack. This
+    data structure is necessary to perform nested decodings using the
+    :py:class:``HeadTailDecoder`` since offsets present in head sections are
+    relative only to a particular encoded object.  These offsets can only be
+    used to locate a position in a decoding stream if they are paired with a
+    contextual offset that establishes the position of the object in which they
+    are found.
+
+    For example, consider the encoding of a value for the following type::
+
+        type: (int,(int,int[]))
+        value: (1,(2,[3,3]))
+
+    There are two tuples in this type: one inner and one outer.  The inner tuple
+    type contains a dynamic type ``int[]`` and, therefore, is itself dynamic.
+    This means that its value encoding will be placed in the tail section of the
+    outer tuple's encoding.  Furthermore, the inner tuple's encoding will,
+    itself, contain a tail section with the encoding for ``[3,3]``.  All
+    together, the encoded value of ``(1,(2,[3,3]))`` would look like this (the
+    data values are normally 32 bytes wide but have been truncated to remove the
+    redundant zeros at the beginnings of their encodings)::
+
+                       offset data
+        --------------------------
+             ^              0 0x01
+             |             32 0x40 <-- Offset of object A in global frame (64)
+        -----|--------------------
+        Global frame ^     64 0x02 <-- Beginning of object A (64 w/offset 0 = 64)
+             |       |     96 0x40 <-- Offset of object B in frame of object A (64)
+        -----|-Object A's frame---
+             |       |    128 0x02 <-- Beginning of object B (64 w/offset 64 = 128)
+             |       |    160 0x03
+             v       v    192 0x03
+        --------------------------
+
+    Note that the offset of object B is encoded as 64 which only specifies the
+    beginning of its encoded value relative to the beginning of object A's
+    encoding.  Globally, object B is located at offset 128.  In order to make
+    sense out of object B's offset, it needs to be positioned in the context of
+    its enclosing object's frame (object A).
+    """
+
+    def __init__(self, initial_bytes: bytes | bytearray):
+        # NOTE: Non-contiguous buffers are intentionally unsupported (regression from
+        # BytesIO) because they are rare in our decode flow and we want to keep the
+        # compiled hot path fast. Callers with sliced memoryviews should wrap with
+        # bytes(...) if needed.
+        self._buffer = memoryview(initial_bytes)
+        self._position = 0
+        self._frames: Final[list[tuple[int, int]]] = []
+        self._total_offset = 0
+
+    def read(self, size: int = -1) -> bytes:
+        """
+        Read up to ``size`` bytes from the stream. If ``size`` is negative,
+        read until EOF.
+        """
+        remaining = len(self._buffer) - self._position
+        if size is None or size < 0:
+            size = remaining
+        elif size > remaining:
+            size = remaining
+
+        if size <= 0:
+            return b""
+
+        start = self._position
+        end = start + size
+        self._position = end
+        return self._buffer[start:end].tobytes()
+
+    def tell(self) -> int:
+        return self._position
+
+    def seek(self, pos: int, whence: int = 0) -> int:
+        if whence == 0:
+            new_pos = pos
+        elif whence == 1:
+            new_pos = self._position + pos
+        elif whence == 2:
+            new_pos = len(self._buffer) + pos
+        else:
+            raise ValueError(f"invalid whence ({whence}, should be 0, 1 or 2)")
+
+        if new_pos < 0:
+            raise ValueError("negative seek position")
+
+        self._position = new_pos
+        return new_pos
+
+    def getbuffer(self) -> memoryview:
+        return self._buffer
+
+    def seek_in_frame(self, pos: int, *args: Any, **kwargs: Any) -> None:
+        """
+        Seeks relative to the total offset of the current contextual frames.
+        """
+        self.seek(self._total_offset + pos, *args, **kwargs)
+
+    def push_frame(self, offset: int) -> None:
+        """
+        Pushes a new contextual frame onto the stack with the given offset and a
+        return position at the current cursor position then seeks to the new
+        total offset.
+        """
+        self._frames.append((offset, self.tell()))
+        self._total_offset += offset
+
+        self.seek_in_frame(0)
+
+    def pop_frame(self) -> None:
+        """
+        Pops the current contextual frame off of the stack and returns the
+        cursor to the frame's return position.
+        """
+        try:
+            offset, return_pos = self._frames.pop()
+        except IndexError:
+            raise IndexError("no frames to pop")
+        self._total_offset -= offset
+
+        self.seek(return_pos)

faster_eth_abi/packed.py

@@ -0,0 +1,19 @@
+"""Helpers for packed ABI encoding.
+
+Defines functions and registry for packed encoding and encodability checks.
+"""
+from typing import (
+    Final,
+)
+
+from .codec import (
+    ABIEncoder,
+)
+from .registry import (
+    registry_packed,
+)
+
+default_encoder_packed: Final = ABIEncoder(registry_packed)
+
+encode_packed: Final = default_encoder_packed.encode
+is_encodable_packed: Final = default_encoder_packed.is_encodable