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

faster_eth_abi/encoding.py

@@ -1,13 +1,29 @@
+"""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,
+)
 from typing import (
     Any,
+    Callable,
+    ClassVar,
+    Final,
     NoReturn,
     Optional,
     Sequence,
     Tuple,
     Type,
+    final,
 )
 
 from faster_eth_utils import (
@@ -20,6 +36,9 @@ from faster_eth_utils import (
     is_text,
     to_canonical_address,
 )
+from typing_extensions import (
+    Self,
+)
 
 from faster_eth_abi._encoding import (
     encode_elements,
@@ -27,7 +46,11 @@ from faster_eth_abi._encoding import (
     encode_fixed,
     encode_signed,
     encode_tuple,
+    encode_tuple_all_dynamic,
+    encode_tuple_no_dynamic,
+    encode_tuple_no_dynamic_funcs,
     int_to_big_endian,
+    validate_tuple,
 )
 from faster_eth_abi.base import (
     BaseCoder,
@@ -73,7 +96,7 @@ class BaseEncoder(BaseCoder, metaclass=abc.ABCMeta):
         """
 
     @abc.abstractmethod
-    def validate_value(self, value: Any) -> None:  # pragma: no cover
+    def validate_value(self, 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
@@ -106,38 +129,51 @@ class TupleEncoder(BaseEncoder):
     def __init__(self, encoders: Tuple[BaseEncoder, ...], **kwargs: Any) -> None:
         super().__init__(encoders=encoders, **kwargs)
 
-        self.is_dynamic = any(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 = []
+        for encoder in self.encoders:
+            try:
+                validator = encoder.validate_value
+            except AttributeError:
+                validators.append(encoder)
+            else:
+                validators.append(validator)
+
+        self.validators: Final[Callable[[Any], None]] = tuple(validators)
+
+        if type(self).encode is TupleEncoder.encode:
+            encode_func = (
+                encode_tuple_all_dynamic
+                if all(self._is_dynamic)
+                else encode_tuple_no_dynamic_funcs.get(
+                    len(self.encoders),
+                    encode_tuple_no_dynamic,
+                )
+                if not self.is_dynamic
+                else encode_tuple
+            )
+
+            self.encode = MethodType(encode_func, self)
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
         if self.encoders is None:
             raise ValueError("`encoders` may not be none")
 
-    def validate_value(self, value):
-        if not is_list_like(value):
-            self.invalidate_value(
-                value,
-                msg="must be list-like object such as array or tuple",
-            )
+    @final
+    def validate_value(self, value: Sequence[Any]) -> None:
+        validate_tuple(self, value)
 
-        if len(value) != len(self.encoders):
-            self.invalidate_value(
-                value,
-                exc=ValueOutOfBounds,
-                msg=f"value has {len(value)} items when {len(self.encoders)} "
-                "were expected",
-            )
+    def encode(self, values: Sequence[Any]) -> bytes:
+        return encode_tuple(self, values)
 
-        for item, encoder in zip(value, self.encoders):
-            try:
-                encoder.validate_value(item)
-            except AttributeError:
-                encoder(item)
-
-    def encode(self, values):
-        self.validate_value(values)
-        return encode_tuple(values, self.encoders)
+    def __call__(self, values: Sequence[Any]) -> bytes:
+        return self.encode(values)
 
     @parse_tuple_type_str
     def from_type_str(cls, abi_type, registry):
@@ -155,37 +191,39 @@ class FixedSizeEncoder(BaseEncoder):
     type_check_fn = None
     is_big_endian = None
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
-        if self.value_bit_size is None:
+        value_bit_size = self.value_bit_size
+        if value_bit_size is None:
             raise ValueError("`value_bit_size` may not be none")
-        if self.data_byte_size is None:
+        data_byte_size = self.data_byte_size
+        if data_byte_size is None:
             raise ValueError("`data_byte_size` may not be none")
         if self.encode_fn is None:
             raise ValueError("`encode_fn` may not be none")
         if self.is_big_endian is None:
             raise ValueError("`is_big_endian` may not be none")
 
-        if self.value_bit_size % 8 != 0:
+        if value_bit_size % 8 != 0:
             raise ValueError(
-                f"Invalid value bit size: {self.value_bit_size}. "
-                "Must be a multiple of 8"
+                f"Invalid value bit size: {value_bit_size}. Must be a multiple of 8"
             )
 
-        if self.value_bit_size > self.data_byte_size * 8:
+        if value_bit_size > data_byte_size * 8:
             raise ValueError("Value byte size exceeds data size")
 
-    def validate_value(self, value):
+    def validate_value(self, value: Any) -> None:
         raise NotImplementedError("Must be implemented by subclasses")
 
     def encode(self, value: Any) -> bytes:
         self.validate_value(value)
-        if self.encode_fn is None:
+        encode_fn = self.encode_fn
+        if encode_fn is None:
             raise AssertionError("`encode_fn` is None")
-        return encode_fixed(
-            value, self.encode_fn, self.is_big_endian, self.data_byte_size
-        )
+        return encode_fixed(value, encode_fn, self.is_big_endian, self.data_byte_size)
+
+    __call__ = encode
 
 
 class Fixed32ByteSizeEncoder(FixedSizeEncoder):
@@ -202,7 +240,7 @@ class BooleanEncoder(Fixed32ByteSizeEncoder):
             cls.invalidate_value(value)
 
     @classmethod
-    def encode_fn(cls, value):
+    def encode_fn(cls, value: bool) -> bytes:
         if value is True:
             return b"\x01"
         elif value is False:
@@ -225,7 +263,7 @@ class NumberEncoder(Fixed32ByteSizeEncoder):
     illegal_value_fn = None
     type_check_fn = None
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
         if self.bounds_fn is None:
@@ -233,15 +271,15 @@ class NumberEncoder(Fixed32ByteSizeEncoder):
         if self.type_check_fn is None:
             raise ValueError("`type_check_fn` cannot be null")
 
-    def validate_value(self, value):
-        if self.type_check_fn is None:
+    def validate_value(self, value: Any) -> None:
+        type_check_fn = self.type_check_fn
+        if type_check_fn is None:
             raise AssertionError("`type_check_fn` is None")
-        if not self.type_check_fn(value):
+        if not type_check_fn(value):
             self.invalidate_value(value)
 
-        illegal_value = self.illegal_value_fn is not None and self.illegal_value_fn(
-            value
-        )
+        illegal_value_fn = self.illegal_value_fn
+        illegal_value = illegal_value_fn is not None and illegal_value_fn(value)
         if illegal_value:
             self.invalidate_value(value, exc=IllegalValue)
 
@@ -265,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)
 
 
@@ -277,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)
@@ -284,15 +342,27 @@ class SignedIntegerEncoder(NumberEncoder):
     def encode_fn(self, value: int) -> bytes:
         return int_to_big_endian(value % (2**self.value_bit_size))
 
-    def encode(self, value):
+    def encode(self, value: int) -> bytes:
         self.validate_value(value)
         return encode_signed(value, self.encode_fn, self.data_byte_size)
 
+    __call__ = encode
+
     @parse_type_str("int")
     def from_type_str(cls, abi_type, registry):
         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):
@@ -302,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
 
@@ -316,11 +396,19 @@ class BaseFixedEncoder(NumberEncoder):
 
         return False
 
+    @cached_property
+    def denominator(self) -> decimal.Decimal:
+        return TEN**self.frac_places
+
+    @cached_property
+    def precision(self) -> int:
+        return TEN**-self.frac_places
+
     def validate_value(self, value):
         super().validate_value(value)
 
         with decimal.localcontext(abi_decimal_context):
-            residue = value % (TEN**-self.frac_places)
+            residue = value % self.precision
 
         if residue > 0:
             self.invalidate_value(
@@ -330,13 +418,14 @@ class BaseFixedEncoder(NumberEncoder):
                 f"{self.frac_places}",
             )
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
-        if self.frac_places is None:
+        frac_places = self.frac_places
+        if frac_places is None:
             raise ValueError("must specify `frac_places`")
 
-        if self.frac_places <= 0 or self.frac_places > 80:
+        if frac_places <= 0 or frac_places > 80:
             raise ValueError("`frac_places` must be in range (0, 80]")
 
 
@@ -344,9 +433,9 @@ class UnsignedFixedEncoder(BaseFixedEncoder):
     def bounds_fn(self, value_bit_size):
         return compute_unsigned_fixed_bounds(self.value_bit_size, self.frac_places)
 
-    def encode_fn(self, value):
+    def encode_fn(self, value: decimal.Decimal) -> bytes:
         with decimal.localcontext(abi_decimal_context):
-            scaled_value = value * TEN**self.frac_places
+            scaled_value = value * self.denominator
             integer_value = int(scaled_value)
 
         return int_to_big_endian(integer_value)
@@ -377,19 +466,21 @@ class SignedFixedEncoder(BaseFixedEncoder):
     def bounds_fn(self, value_bit_size):
         return compute_signed_fixed_bounds(self.value_bit_size, self.frac_places)
 
-    def encode_fn(self, value):
+    def encode_fn(self, value: decimal.Decimal) -> bytes:
         with decimal.localcontext(abi_decimal_context):
-            scaled_value = value * TEN**self.frac_places
+            scaled_value = value * self.denominator
             integer_value = int(scaled_value)
 
         unsigned_integer_value = integer_value % (2**self.value_bit_size)
 
         return int_to_big_endian(unsigned_integer_value)
 
-    def encode(self, value):
+    def encode(self, value: decimal.Decimal) -> bytes:
         self.validate_value(value)
         return encode_signed(value, self.encode_fn, self.data_byte_size)
 
+    __call__ = encode
+
     @parse_type_str("fixed")
     def from_type_str(cls, abi_type, registry):
         value_bit_size, frac_places = abi_type.sub
@@ -422,7 +513,7 @@ class AddressEncoder(Fixed32ByteSizeEncoder):
         if not is_address(value):
             cls.invalidate_value(value)
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
         if self.value_bit_size != 20 * 8:
@@ -453,7 +544,7 @@ class BytesEncoder(Fixed32ByteSizeEncoder):
             )
 
     @staticmethod
-    def encode_fn(value):
+    def encode_fn(value: bytes) -> bytes:
         return value
 
     @parse_type_str("bytes")
@@ -479,7 +570,7 @@ class ByteStringEncoder(BaseEncoder):
             cls.invalidate_value(value)
 
     @classmethod
-    def encode(cls, value):
+    def encode(cls, value: bytes) -> bytes:
         cls.validate_value(value)
         value_length = len(value)
 
@@ -488,19 +579,23 @@ class ByteStringEncoder(BaseEncoder):
 
         return encoded_size + padded_value
 
+    __call__: ClassVar[Callable[[Type[Self], bytes], bytes]] = encode
+
     @parse_type_str("bytes")
     def from_type_str(cls, abi_type, registry):
-        return cls()
+        return cls()  # type: ignore [misc]
 
 
 class PackedByteStringEncoder(ByteStringEncoder):
     is_dynamic = False
 
     @classmethod
-    def encode(cls, value):
+    def encode(cls, value: bytes) -> bytes:
         cls.validate_value(value)
         return value
 
+    __call__ = encode
+
 
 class TextStringEncoder(BaseEncoder):
     is_dynamic = True
@@ -511,7 +606,7 @@ class TextStringEncoder(BaseEncoder):
             cls.invalidate_value(value)
 
     @classmethod
-    def encode(cls, value):
+    def encode(cls, value: str) -> bytes:
         cls.validate_value(value)
 
         value_as_bytes = codecs.encode(value, "utf8")
@@ -522,24 +617,28 @@ class TextStringEncoder(BaseEncoder):
 
         return encoded_size + padded_value
 
+    __call__: ClassVar[Callable[[Type[Self], str], bytes]] = encode
+
     @parse_type_str("string")
     def from_type_str(cls, abi_type, registry):
-        return cls()
+        return cls()  # type: ignore [misc]
 
 
 class PackedTextStringEncoder(TextStringEncoder):
     is_dynamic = False
 
     @classmethod
-    def encode(cls, value):
+    def encode(cls, value: str) -> bytes:
         cls.validate_value(value)
         return codecs.encode(value, "utf8")
 
+    __call__ = encode
+
 
 class BaseArrayEncoder(BaseEncoder):
-    item_encoder = None
+    item_encoder: BaseEncoder = None
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
         if self.item_encoder is None:
@@ -552,8 +651,9 @@ class BaseArrayEncoder(BaseEncoder):
                 msg="must be list-like such as array or tuple",
             )
 
+        item_encoder = self.item_encoder
         for item in value:
-            self.item_encoder.validate_value(item)
+            item_encoder.validate_value(item)
 
     def encode_elements(self, value: Sequence[Any]) -> bytes:
         self.validate_value(value)
@@ -581,17 +681,19 @@ class PackedArrayEncoder(BaseArrayEncoder):
     def validate_value(self, value: Any) -> None:
         super().validate_value(value)
 
-        if self.array_size is not None and len(value) != self.array_size:
+        array_size = self.array_size
+        if array_size is not None and len(value) != array_size:
             self.invalidate_value(
                 value,
                 exc=ValueOutOfBounds,
-                msg=f"value has {len(value)} items when {self.array_size} were "
-                "expected",
+                msg=f"value has {len(value)} items when {array_size} were expected",
             )
 
     def encode(self, value: Sequence[Any]) -> bytes:
         return encode_elements(self.item_encoder, value)
 
+    __call__ = encode
+
     @parse_type_str(with_arrlist=True)
     def from_type_str(cls, abi_type, registry):
         item_encoder = registry.get_encoder(abi_type.item_type.to_type_str())
@@ -609,12 +711,12 @@ class PackedArrayEncoder(BaseArrayEncoder):
 class SizedArrayEncoder(BaseArrayEncoder):
     array_size = None
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         super().__init__(**kwargs)
 
         self.is_dynamic = self.item_encoder.is_dynamic
 
-    def validate(self):
+    def validate(self) -> None:
         super().validate()
 
         if self.array_size is None:
@@ -634,6 +736,8 @@ class SizedArrayEncoder(BaseArrayEncoder):
     def encode(self, value: Sequence[Any]) -> bytes:
         return encode_elements(self.item_encoder, value)
 
+    __call__ = encode
+
 
 class DynamicArrayEncoder(BaseArrayEncoder):
     is_dynamic = True

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