faster-eth-abi 5.2.15__cp314-cp314t-win32.whl → 5.2.16__cp314-cp314t-win32.whl

faster_eth_abi/decoding.py

@@ -1,7 +1,13 @@
+"""Classes for ABI decoding logic.
+
+Implements classes and functions for deserializing binary data into Python values
+according to ABI type specifications.
+"""
 import abc
 import decimal
 from functools import (
     cached_property,
+    lru_cache,
 )
 from types import (
     MethodType,
@@ -10,12 +16,17 @@ from typing import (
     Any,
     Callable,
     Final,
+    Generic,
     Optional,
     Tuple,
+    TypeVar,
     Union,
     final,
 )
 
+from eth_typing import (
+    HexAddress,
+)
 from faster_eth_utils import (
     big_endian_to_int,
     to_normalized_address,
@@ -48,18 +59,19 @@ from faster_eth_abi.from_type_str import (
 from faster_eth_abi.io import (
     ContextFramesBytesIO,
 )
+from faster_eth_abi.typing import (
+    T,
+)
 from faster_eth_abi.utils.numeric import (
     TEN,
     abi_decimal_context,
     ceil32,
 )
 
-DynamicDecoder = Union[
-    "HeadTailDecoder", "SizedArrayDecoder", "DynamicArrayDecoder", "ByteStringDecoder"
-]
+TByteStr = TypeVar("TByteStr", bytes, str)
 
 
-class BaseDecoder(BaseCoder, metaclass=abc.ABCMeta):
+class BaseDecoder(BaseCoder, Generic[T], metaclass=abc.ABCMeta):
     """
     Base class for all decoder classes.  Subclass this if you want to define a
     custom decoder class.  Subclasses must also implement
@@ -69,18 +81,18 @@ class BaseDecoder(BaseCoder, metaclass=abc.ABCMeta):
     strict = True
 
     @abc.abstractmethod
-    def decode(self, stream: ContextFramesBytesIO) -> Any:  # pragma: no cover
+    def decode(self, stream: ContextFramesBytesIO) -> T:  # pragma: no cover
         """
         Decodes the given stream of bytes into a python value.  Should raise
         :any:`exceptions.DecodingError` if a python value cannot be decoded
         from the given byte stream.
         """
 
-    def __call__(self, stream: ContextFramesBytesIO) -> Any:
+    def __call__(self, stream: ContextFramesBytesIO) -> T:
         return self.decode(stream)
 
 
-class HeadTailDecoder(BaseDecoder):
+class HeadTailDecoder(BaseDecoder[T]):
     """
     Decoder for a dynamic element of a dynamic container (a dynamic array, or a sized
     array or tuple that contains dynamic elements). A dynamic element consists of a
@@ -90,24 +102,33 @@ class HeadTailDecoder(BaseDecoder):
 
     is_dynamic = True
 
-    tail_decoder: Optional[DynamicDecoder] = None
-
-    def validate(self) -> None:
-        super().validate()
+    def __init__(
+        self,
+        tail_decoder: Union[  # type: ignore [type-var]
+            "HeadTailDecoder[T]",
+            "SizedArrayDecoder[T]",
+            "DynamicArrayDecoder[T]",
+            "ByteStringDecoder[T]",
+        ],
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
 
-        if self.tail_decoder is None:
+        if tail_decoder is None:
             raise ValueError("No `tail_decoder` set")
 
-    def decode(self, stream: ContextFramesBytesIO) -> Any:
+        self.tail_decoder: Final = tail_decoder
+
+    def decode(self, stream: ContextFramesBytesIO) -> T:
         return decode_head_tail(self, stream)
 
     __call__ = decode
 
 
-class TupleDecoder(BaseDecoder):
-    decoders: Tuple[BaseDecoder, ...] = ()
+class TupleDecoder(BaseDecoder[Tuple[T, ...]]):
+    decoders: Tuple[BaseDecoder[T], ...] = ()
 
-    def __init__(self, decoders: Tuple[BaseDecoder, ...], **kwargs: Any) -> None:
+    def __init__(self, decoders: Tuple[BaseDecoder[T], ...], **kwargs: Any) -> None:
         super().__init__(**kwargs)
 
         self.decoders = decoders = tuple(
@@ -134,7 +155,7 @@ class TupleDecoder(BaseDecoder):
     def validate_pointers(self, stream: ContextFramesBytesIO) -> None:
         raise NotImplementedError("didnt call __init__")
 
-    def decode(self, stream: ContextFramesBytesIO) -> Tuple[Any, ...]:
+    def decode(self, stream: ContextFramesBytesIO) -> Tuple[T, ...]:
         return decode_tuple(self, stream)
 
     __call__ = decode
@@ -148,7 +169,7 @@ class TupleDecoder(BaseDecoder):
         return cls(decoders=decoders)
 
 
-class SingleDecoder(BaseDecoder):
+class SingleDecoder(BaseDecoder[T]):
     decoder_fn = None
 
     def validate(self) -> None:
@@ -160,7 +181,7 @@ class SingleDecoder(BaseDecoder):
     def validate_padding_bytes(self, value: Any, padding_bytes: bytes) -> None:
         raise NotImplementedError("Must be implemented by subclasses")
 
-    def decode(self, stream: ContextFramesBytesIO) -> Any:
+    def decode(self, stream: ContextFramesBytesIO) -> T:
         raw_data = self.read_data_from_stream(stream)
         data, padding_bytes = self.split_data_and_padding(raw_data)
         value = self.decoder_fn(data)  # type: ignore [misc]
@@ -177,7 +198,7 @@ class SingleDecoder(BaseDecoder):
         return raw_data, b""
 
 
-class BaseArrayDecoder(BaseDecoder):
+class BaseArrayDecoder(BaseDecoder[Tuple[T, ...]]):
     item_decoder: BaseDecoder = None
 
     def __init__(self, **kwargs: Any) -> None:
@@ -195,7 +216,7 @@ class BaseArrayDecoder(BaseDecoder):
 
             self.validate_pointers = noop
 
-    def decode(self, stream: ContextFramesBytesIO) -> Tuple[Any, ...]:
+    def decode(self, stream: ContextFramesBytesIO) -> Tuple[T, ...]:
         raise NotImplementedError  # this is a type stub
 
     def validate(self) -> None:
@@ -226,7 +247,7 @@ class BaseArrayDecoder(BaseDecoder):
         validate_pointers_array(self, stream, array_size)
 
 
-class SizedArrayDecoder(BaseArrayDecoder):
+class SizedArrayDecoder(BaseArrayDecoder[T]):
     array_size: int = None
 
     def __init__(self, **kwargs):
@@ -234,30 +255,30 @@ class SizedArrayDecoder(BaseArrayDecoder):
 
         self.is_dynamic = self.item_decoder.is_dynamic
 
-    def decode(self, stream):
+    def decode(self, stream: ContextFramesBytesIO) -> Tuple[T, ...]:
         return decode_sized_array(self, stream)
 
     __call__ = decode
 
 
-class DynamicArrayDecoder(BaseArrayDecoder):
+class DynamicArrayDecoder(BaseArrayDecoder[T]):
     # Dynamic arrays are always dynamic, regardless of their elements
     is_dynamic = True
 
-    def decode(self, stream: ContextFramesBytesIO) -> Tuple[Any, ...]:
+    def decode(self, stream: ContextFramesBytesIO) -> Tuple[T, ...]:
         return decode_dynamic_array(self, stream)
 
     __call__ = decode
 
 
-class FixedByteSizeDecoder(SingleDecoder):
-    decoder_fn: Callable[[bytes], Any] = None
+class FixedByteSizeDecoder(SingleDecoder[T]):
+    decoder_fn: Callable[[bytes], T] = None
     value_bit_size: int = None
     data_byte_size: int = None
     is_big_endian: bool = None
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
 
         self.read_data_from_stream = MethodType(
             read_fixed_byte_size_data_from_stream, self
@@ -306,11 +327,11 @@ class FixedByteSizeDecoder(SingleDecoder):
         raise NotImplementedError("didnt call __init__")
 
 
-class Fixed32ByteSizeDecoder(FixedByteSizeDecoder):
+class Fixed32ByteSizeDecoder(FixedByteSizeDecoder[T]):
     data_byte_size = 32
 
 
-class BooleanDecoder(Fixed32ByteSizeDecoder):
+class BooleanDecoder(Fixed32ByteSizeDecoder[bool]):
     value_bit_size = 8
     is_big_endian = True
 
@@ -321,7 +342,7 @@ class BooleanDecoder(Fixed32ByteSizeDecoder):
         return cls()
 
 
-class AddressDecoder(Fixed32ByteSizeDecoder):
+class AddressDecoder(Fixed32ByteSizeDecoder[HexAddress]):
     value_bit_size = 20 * 8
     is_big_endian = True
     decoder_fn = staticmethod(to_normalized_address)
@@ -334,8 +355,8 @@ class AddressDecoder(Fixed32ByteSizeDecoder):
 #
 # Unsigned Integer Decoders
 #
-class UnsignedIntegerDecoder(Fixed32ByteSizeDecoder):
-    decoder_fn = staticmethod(big_endian_to_int)
+class UnsignedIntegerDecoder(Fixed32ByteSizeDecoder[int]):
+    decoder_fn: "staticmethod[[bytes], int]" = staticmethod(big_endian_to_int)
     is_big_endian = True
 
     @parse_type_str("uint")
@@ -346,18 +367,33 @@ class UnsignedIntegerDecoder(Fixed32ByteSizeDecoder):
 decode_uint_256 = UnsignedIntegerDecoder(value_bit_size=256)
 
 
+class UnsignedIntegerDecoderCached(UnsignedIntegerDecoder):
+    decoder_fn: Callable[[bytes], int]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.decoder_fn = lru_cache(maxsize=maxsize)(self.decoder_fn)
+
+
 #
 # Signed Integer Decoders
 #
-class SignedIntegerDecoder(Fixed32ByteSizeDecoder):
+class SignedIntegerDecoder(Fixed32ByteSizeDecoder[int]):
     is_big_endian = True
 
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        super().__init__(*args, **kwargs)
-    
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+
         # Only assign validate_padding_bytes if not overridden in subclass
-        if type(self).validate_padding_bytes is SignedIntegerDecoder.validate_padding_bytes:
-            self.validate_padding_bytes = MethodType(validate_padding_bytes_signed_integer, self)
+        if (
+            type(self).validate_padding_bytes
+            is SignedIntegerDecoder.validate_padding_bytes
+        ):
+            self.validate_padding_bytes = MethodType(
+                validate_padding_bytes_signed_integer, self
+            )
 
     @cached_property
     def neg_threshold(self) -> int:
@@ -381,10 +417,20 @@ class SignedIntegerDecoder(Fixed32ByteSizeDecoder):
         return cls(value_bit_size=abi_type.sub)
 
 
+class SignedIntegerDecoderCached(SignedIntegerDecoder):
+    decoder_fn: Callable[[bytes], int]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.decoder_fn = lru_cache(maxsize=maxsize)(self.decoder_fn)
+
+
 #
 # Bytes1..32
 #
-class BytesDecoder(Fixed32ByteSizeDecoder):
+class BytesDecoder(Fixed32ByteSizeDecoder[bytes]):
     is_big_endian = False
 
     @staticmethod
@@ -396,10 +442,10 @@ class BytesDecoder(Fixed32ByteSizeDecoder):
         return cls(value_bit_size=abi_type.sub * 8)
 
 
-class BaseFixedDecoder(Fixed32ByteSizeDecoder):
+class BaseFixedDecoder(Fixed32ByteSizeDecoder[decimal.Decimal]):
     frac_places: int = None
     is_big_endian = True
-    
+
     @cached_property
     def denominator(self) -> decimal.Decimal:
         return TEN**self.frac_places
@@ -416,7 +462,6 @@ class BaseFixedDecoder(Fixed32ByteSizeDecoder):
 
 
 class UnsignedFixedDecoder(BaseFixedDecoder):
-    
     def decoder_fn(self, data: bytes) -> decimal.Decimal:
         value = big_endian_to_int(data)
 
@@ -433,7 +478,6 @@ class UnsignedFixedDecoder(BaseFixedDecoder):
 
 
 class SignedFixedDecoder(BaseFixedDecoder):
-    
     @cached_property
     def neg_threshold(self) -> int:
         return int(2 ** (self.value_bit_size - 1))
@@ -485,7 +529,7 @@ class SignedFixedDecoder(BaseFixedDecoder):
 #
 # String and Bytes
 #
-class ByteStringDecoder(SingleDecoder):
+class ByteStringDecoder(SingleDecoder[TByteStr]):
     is_dynamic = True
 
     @staticmethod
@@ -520,7 +564,7 @@ class ByteStringDecoder(SingleDecoder):
         return cls()
 
 
-class StringDecoder(ByteStringDecoder):
+class StringDecoder(ByteStringDecoder[str]):
     def __init__(self, handle_string_errors: str = "strict") -> None:
         self.bytes_errors: Final = handle_string_errors
         super().__init__()

faster_eth_abi/encoding.py

@@ -1,8 +1,14 @@
+"""Classes for ABI encoding logic.
+
+Implements classes and functions for serializing Python values into binary data
+according to ABI type specifications.
+"""
 import abc
 import codecs
 import decimal
 from functools import (
     cached_property,
+    lru_cache,
 )
 from types import (
     MethodType,
@@ -123,7 +129,9 @@ class TupleEncoder(BaseEncoder):
     def __init__(self, encoders: Tuple[BaseEncoder, ...], **kwargs: Any) -> None:
         super().__init__(encoders=encoders, **kwargs)
 
-        self._is_dynamic: Final = tuple(getattr(e, "is_dynamic", False) for e in self.encoders)
+        self._is_dynamic: Final = tuple(
+            getattr(e, "is_dynamic", False) for e in self.encoders
+        )
         self.is_dynamic = any(self._is_dynamic)
 
         validators = []
@@ -134,7 +142,7 @@ class TupleEncoder(BaseEncoder):
                 validators.append(encoder)
             else:
                 validators.append(validator)
-        
+
         self.validators: Final[Callable[[Any], None]] = tuple(validators)
 
         if type(self).encode is TupleEncoder.encode:
@@ -148,7 +156,7 @@ class TupleEncoder(BaseEncoder):
                 if not self.is_dynamic
                 else encode_tuple
             )
-                
+
             self.encode = MethodType(encode_func, self)
 
     def validate(self) -> None:
@@ -295,6 +303,16 @@ class UnsignedIntegerEncoder(NumberEncoder):
         return cls(value_bit_size=abi_type.sub)
 
 
+class UnsignedIntegerEncoderCached(UnsignedIntegerEncoder):
+    encode: Final[Callable[[int], bytes]]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.encode = lru_cache(maxsize=maxsize)(self.encode)
+
+
 encode_uint_256 = UnsignedIntegerEncoder(value_bit_size=256, data_byte_size=32)
 
 
@@ -307,6 +325,16 @@ class PackedUnsignedIntegerEncoder(UnsignedIntegerEncoder):
         )
 
 
+class PackedUnsignedIntegerEncoderCached(PackedUnsignedIntegerEncoder):
+    encode: Final[Callable[[int], bytes]]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.encode = lru_cache(maxsize=maxsize)(self.encode)
+
+
 class SignedIntegerEncoder(NumberEncoder):
     bounds_fn = staticmethod(compute_signed_integer_bounds)
     type_check_fn = staticmethod(is_integer)
@@ -325,6 +353,16 @@ class SignedIntegerEncoder(NumberEncoder):
         return cls(value_bit_size=abi_type.sub)
 
 
+class SignedIntegerEncoderCached(SignedIntegerEncoder):
+    encode: Final[Callable[[int], bytes]]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.encode = lru_cache(maxsize=maxsize)(self.encode)
+
+
 class PackedSignedIntegerEncoder(SignedIntegerEncoder):
     @parse_type_str("int")
     def from_type_str(cls, abi_type, registry):
@@ -334,6 +372,16 @@ class PackedSignedIntegerEncoder(SignedIntegerEncoder):
         )
 
 
+class PackedSignedIntegerEncoderCached(PackedSignedIntegerEncoder):
+    encode: Final[Callable[[int], bytes]]
+    maxsize: Final[Optional[int]]
+
+    def __init__(self, maxsize: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.maxsize = maxsize
+        self.encode = lru_cache(maxsize=maxsize)(self.encode)
+
+
 class BaseFixedEncoder(NumberEncoder):
     frac_places = None
 

faster_eth_abi/exceptions.py

@@ -2,12 +2,13 @@
 # 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
-import parsimonious
 
 
 class EncodingError(eth_abi.exceptions.EncodingError):
@@ -110,7 +111,9 @@ class NoEntriesFound(PredicateMappingError, eth_abi.exceptions.NoEntriesFound):
     """
 
 
-class MultipleEntriesFound(PredicateMappingError, eth_abi.exceptions.MultipleEntriesFound):
+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,

faster_eth_abi/grammar.py

@@ -1,40 +1,27 @@
+"""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,
 )
 
-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_ALIASES,
     TYPE_ALIAS_RE,
+    TYPE_ALIASES,
     ABIType,
     BasicType,
     TupleType,
     normalize,
 )
 from faster_eth_abi.exceptions import (
-    ABITypeError,
     ParseError,
 )
 
@@ -167,4 +154,15 @@ visitor: Final = NodeVisitor()
 parse: Final = visitor.parse
 
 
-__all__ = ["NodeVisitor", "ABIType", "TupleType", "BasicType", "grammar", "parse", "normalize", "visitor", "TYPE_ALIASES", "TYPE_ALIAS_RE"]
+__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,
 )

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,
 )