faster-eth-abi 5.2.1__cp313-cp313-macosx_11_0_arm64.whl → 5.2.20__cp313-cp313-macosx_11_0_arm64.whl

faster_eth_abi/exceptions.py

@@ -1,20 +1,30 @@
-import parsimonious
+# mypy: disable-error-code="misc"
+# cannot subclass `Any`
 
+"""
+Exception classes for error handling during ABI encoding and decoding operations.
 
-class EncodingError(Exception):
+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):
+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):
+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.
@@ -26,7 +36,7 @@ class IllegalValue(EncodingError):
     """
 
 
-class ValueOutOfBounds(IllegalValue):
+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
@@ -39,31 +49,31 @@ class ValueOutOfBounds(IllegalValue):
     """
 
 
-class DecodingError(Exception):
+class DecodingError(eth_abi.exceptions.DecodingError):
     """
     Base exception for any error that occurs during decoding.
     """
 
 
-class InsufficientDataBytes(DecodingError):
+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):
+class NonEmptyPaddingBytes(DecodingError, eth_abi.exceptions.NonEmptyPaddingBytes):
     """
     Raised when the padding bytes of an ABI value are malformed.
     """
 
 
-class InvalidPointer(DecodingError):
+class InvalidPointer(DecodingError, eth_abi.exceptions.InvalidPointer):
     """
     Raised when the pointer to a value in the ABI encoding is invalid.
     """
 
 
-class ParseError(parsimonious.ParseError):  # type: ignore[misc] # subclasses Any
+class ParseError(eth_abi.exceptions.ParseError):
     """
     Raised when an ABI type string cannot be parsed.
     """
@@ -75,7 +85,7 @@ class ParseError(parsimonious.ParseError):  # type: ignore[misc] # subclasses An
         )
 
 
-class ABITypeError(ValueError):
+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
@@ -83,13 +93,13 @@ class ABITypeError(ValueError):
     """
 
 
-class PredicateMappingError(Exception):
+class PredicateMappingError(eth_abi.exceptions.PredicateMappingError):
     """
     Raised when an error occurs in a registry's internal mapping.
     """
 
 
-class NoEntriesFound(ValueError, PredicateMappingError):
+class NoEntriesFound(PredicateMappingError, eth_abi.exceptions.NoEntriesFound):
     """
     Raised when no registration is found for a type string in a registry's
     internal mapping.
@@ -101,7 +111,9 @@ class NoEntriesFound(ValueError, PredicateMappingError):
     """
 
 
-class MultipleEntriesFound(ValueError, PredicateMappingError):
+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

faster_eth_abi/from_type_str.py

@@ -1,3 +1,7 @@
+"""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,
@@ -12,11 +16,13 @@ from eth_typing import (
     TypeStr,
 )
 
-from .grammar import (
+from ._grammar import (
     ABIType,
     BasicType,
     TupleType,
     normalize,
+)
+from .grammar import (
     parse,
 )
 

faster_eth_abi/grammar.py

@@ -1,32 +1,31 @@
+"""Parsing and normalization logic for ABI type strings.
+
+Implements grammar, parsing, and type validation for ABI type strings.
+"""
 import functools
-import re
 from typing import (
     Any,
     Final,
-    NoReturn,
-    Optional,
-    Sequence,
-    Tuple,
-    TypeVar,
     final,
 )
 
+import parsimonious
 from eth_typing import (
     TypeStr,
 )
-import parsimonious
 from parsimonious import (
     expressions,
 )
-from parsimonious.nodes import (
-    Node,
-)
-from typing_extensions import (
-    Self,
-)
 
+from faster_eth_abi._grammar import (
+    TYPE_ALIAS_RE,
+    TYPE_ALIASES,
+    ABIType,
+    BasicType,
+    TupleType,
+    normalize,
+)
 from faster_eth_abi.exceptions import (
-    ABITypeError,
     ParseError,
 )
 
@@ -58,14 +57,14 @@ grammar: Final = parsimonious.Grammar(
 
 
 @final
-class NodeVisitor(parsimonious.NodeVisitor):  # type: ignore [misc]
+class NodeVisitor(parsimonious.NodeVisitor):
     """
     Parsimonious node visitor which performs both parsing of type strings and
     post-processing of parse trees.  Parsing operations are cached.
     """
 
-    def __init__(self):
-        self.parse = functools.lru_cache(maxsize=None)(self._parse_uncached)
+    def __init__(self) -> None:
+        self.parse: Final = functools.lru_cache(maxsize=None)(self._parse_uncached)
 
     grammar = grammar
 
@@ -127,7 +126,7 @@ class NodeVisitor(parsimonious.NodeVisitor):  # type: ignore [misc]
 
         return tuple(visited_children)
 
-    def _parse_uncached(self, type_str, **kwargs):
+    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,
@@ -156,312 +155,18 @@ class NodeVisitor(parsimonious.NodeVisitor):  # type: ignore [misc]
 
 visitor: Final = NodeVisitor()
 
-
-class ABIType:
-    """
-    Base class for results of type string parsing operations.
-    """
-
-    __slots__ = ("arrlist", "node")
-
-    def __init__(
-        self, arrlist: Optional[Sequence] = None, node: Optional[Node] = None
-    ) -> None:
-        self.arrlist: Final = arrlist
-        """
-        The list of array dimensions for a parsed type.  Equal to ``None`` if
-        type string has no array dimensions.
-        """
-
-        self.node: Final = node
-        """
-        The parsimonious ``Node`` instance associated with this parsed type.
-        Used to generate error messages for invalid types.
-        """
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return f"<{type(self).__qualname__} {self.to_type_str()!r}>"
-
-    def __eq__(self, other: Any) -> bool:
-        # Two ABI types are equal if their string representations are equal
-        return type(self) is type(other) and self.to_type_str() == other.to_type_str()
-
-    def to_type_str(self) -> TypeStr:  # pragma: no cover
-        """
-        Returns the string representation of an ABI type.  This will be equal to
-        the type string from which it was created.
-        """
-        raise NotImplementedError("Must implement `to_type_str`")
-
-    @property
-    def item_type(self) -> Self:
-        """
-        If this type is an array type, equal to an appropriate
-        :class:`~faster_eth_abi.grammar.ABIType` instance for the array's items.
-        """
-        raise NotImplementedError("Must implement `item_type`")
-
-    def validate(self) -> None:  # pragma: no cover
-        """
-        Validates the properties of an ABI type against the solidity ABI spec:
-
-        https://solidity.readthedocs.io/en/develop/abi-spec.html
-
-        Raises :class:`~faster_eth_abi.exceptions.ABITypeError` if validation fails.
-        """
-        raise NotImplementedError("Must implement `validate`")
-
-    def invalidate(self, error_msg: str) -> NoReturn:
-        # Invalidates an ABI type with the given error message.  Expects that a
-        # parsimonious node was provided from the original parsing operation
-        # that yielded this type.
-        node = self.node
-
-        raise ABITypeError(
-            f"For '{node.text}' type at column {node.start + 1} "
-            f"in '{node.full_text}': {error_msg}"
-        )
-
-    @property
-    def is_array(self) -> bool:
-        """
-        Equal to ``True`` if a type is an array type (i.e. if it has an array
-        dimension list).  Otherwise, equal to ``False``.
-        """
-        return self.arrlist is not None
-
-    @property
-    def is_dynamic(self) -> bool:
-        """
-        Equal to ``True`` if a type has a dynamically sized encoding.
-        Otherwise, equal to ``False``.
-        """
-        raise NotImplementedError("Must implement `is_dynamic`")
-
-    @property
-    def _has_dynamic_arrlist(self) -> bool:
-        return self.is_array and any(len(dim) == 0 for dim in self.arrlist)
-
-
-TComp = TypeVar("TComp", bound=ABIType)
-
-
-@final
-class TupleType(ABIType):
-    """
-    Represents the result of parsing a tuple type string e.g. "(int,bool)".
-    """
-
-    __slots__ = ("components",)
-
-    def __init__(
-        self,
-        components: Tuple[TComp, ...],
-        arrlist: Optional[Sequence] = None,
-        *,
-        node: Optional[Node] = None,
-    ) -> None:
-        super().__init__(arrlist, node)
-
-        self.components: Final = components
-        """
-        A tuple of :class:`~faster_eth_abi.grammar.ABIType` instances for each of the
-        tuple type's components.
-        """
-
-    def to_type_str(self) -> TypeStr:
-        arrlist = self.arrlist
-
-        if isinstance(arrlist, tuple):
-            arrlist = "".join(repr(list(a)) for a in arrlist)
-        else:
-            arrlist = ""
-
-        return f"({','.join(c.to_type_str() for c in self.components)}){arrlist}"
-
-    @property
-    def item_type(self) -> Self:
-        if not self.is_array:
-            raise ValueError(
-                f"Cannot determine item type for non-array type '{self.to_type_str()}'"
-            )
-
-        return type(self)(
-            self.components,
-            self.arrlist[:-1] or None,  # type: ignore [index]
-            node=self.node,
-        )
-
-    def validate(self) -> None:
-        for c in self.components:
-            c.validate()
-
-    @property
-    def is_dynamic(self) -> bool:
-        if self._has_dynamic_arrlist:
-            return True
-
-        return any(c.is_dynamic for c in self.components)
-
-
-@final
-class BasicType(ABIType):
-    """
-    Represents the result of parsing a basic type string e.g. "uint", "address",
-    "ufixed128x19[][2]".
-    """
-
-    __slots__ = ("base", "sub")
-
-    def __init__(
-        self,
-        base: str,
-        sub: Any = None,
-        arrlist: Optional[Sequence] = None,
-        *,
-        node: Optional[Node] = None,
-    ) -> None:
-        super().__init__(arrlist, node)
-
-        self.base: Final = base
-        """The base of a basic type e.g. "uint" for "uint256" etc."""
-
-        self.sub: Final = 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.
-        """
-
-    def to_type_str(self) -> TypeStr:
-        sub, arrlist = self.sub, self.arrlist
-
-        if isinstance(sub, int):
-            substr = str(sub)
-        elif isinstance(sub, tuple):
-            substr = "x".join(str(s) for s in sub)
-        else:
-            substr = ""
-
-        if isinstance(arrlist, tuple):
-            return self.base + substr + "".join(repr(list(a)) for a in arrlist)
-        else:
-            return self.base + substr
-
-    @property
-    def item_type(self) -> Self:
-        if not self.is_array:
-            raise ValueError(
-                f"Cannot determine item type for non-array type '{self.to_type_str()}'"
-            )
-
-        return type(self)(
-            self.base,
-            self.sub,
-            self.arrlist[:-1] or None,  # type: ignore [index]
-            node=self.node,
-        )
-
-    @property
-    def is_dynamic(self) -> bool:
-        if self._has_dynamic_arrlist:
-            return True
-
-        if self.base == "string":
-            return True
-
-        if self.base == "bytes" and self.sub is None:
-            return True
-
-        return False
-
-    def validate(self) -> None:
-        base, sub = self.base, self.sub
-
-        # Check validity of string type
-        if base == "string":
-            if sub is not None:
-                self.invalidate("string type cannot have suffix")
-
-        # Check validity of bytes type
-        elif base == "bytes":
-            if not (sub is None or isinstance(sub, int)):
-                self.invalidate(
-                    "bytes type must have either no suffix or a numerical suffix"
-                )
-
-            if isinstance(sub, int) and sub > 32:
-                self.invalidate("maximum 32 bytes for fixed-length bytes")
-
-        # Check validity of integer type
-        elif base in ("int", "uint"):
-            if not isinstance(sub, int):
-                self.invalidate("integer type must have numerical suffix")
-
-            if sub < 8 or sub > 256:
-                self.invalidate("integer size out of bounds (max 256 bits)")
-
-            if sub % 8 != 0:
-                self.invalidate("integer size must be multiple of 8")
-
-        # Check validity of fixed type
-        elif base in ("fixed", "ufixed"):
-            if not isinstance(sub, tuple):
-                self.invalidate(
-                    "fixed type must have suffix of form <bits>x<exponent>, "
-                    "e.g. 128x19",
-                )
-
-            bits, minus_e = sub
-
-            if bits < 8 or bits > 256:
-                self.invalidate("fixed size out of bounds (max 256 bits)")
-
-            if bits % 8 != 0:
-                self.invalidate("fixed size must be multiple of 8")
-
-            if minus_e < 1 or minus_e > 80:
-                self.invalidate(
-                    f"fixed exponent size out of bounds, {minus_e} must be in 1-80"
-                )
-
-        # Check validity of hash type
-        elif base == "hash":
-            if not isinstance(sub, int):
-                self.invalidate("hash type must have numerical suffix")
-
-        # Check validity of address type
-        elif base == "address":
-            if sub is not None:
-                self.invalidate("address cannot have suffix")
-
-
-TYPE_ALIASES: Final = {
-    "int": "int256",
-    "uint": "uint256",
-    "fixed": "fixed128x18",
-    "ufixed": "ufixed128x18",
-    "function": "bytes24",
-    "byte": "bytes1",
-}
-
-TYPE_ALIAS_RE: Final = re.compile(
-    rf"\b({'|'.join(re.escape(a) for a in TYPE_ALIASES.keys())})\b"
-)
-
-
-def normalize(type_str: TypeStr) -> TypeStr:
-    """
-    Normalizes a type string into its canonical version e.g. the type string
-    'int' becomes 'int256', etc.
-
-    :param type_str: The type string to be normalized.
-    :returns: The canonical version of the input type string.
-    """
-    return TYPE_ALIAS_RE.sub(
-        lambda match: TYPE_ALIASES[match.group(0)],
-        type_str,
-    )
+parse: Final = visitor.parse
 
 
-parse: Final = visitor.parse
+__all__ = [
+    "NodeVisitor",
+    "ABIType",
+    "TupleType",
+    "BasicType",
+    "grammar",
+    "parse",
+    "normalize",
+    "visitor",
+    "TYPE_ALIASES",
+    "TYPE_ALIAS_RE",
+]

faster_eth_abi/io.py

@@ -1,3 +1,7 @@
+"""Context-aware byte stream for ABI decoding.
+
+Implements a BytesIO subclass that supports contextual frame management for nested ABI decoding.
+"""
 from io import (
     BytesIO,
 )
@@ -89,7 +93,7 @@ class ContextFramesBytesIO(BytesIO):
 
         self.seek_in_frame(0)
 
-    def pop_frame(self):
+    def pop_frame(self) -> None:
         """
         Pops the current contextual frame off of the stack and returns the
         cursor to the frame's return position.

faster_eth_abi/packed.py

@@ -1,3 +1,7 @@
+"""Helpers for packed ABI encoding.
+
+Defines functions and registry for packed encoding and encodability checks.
+"""
 from typing import (
     Final,
 )