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/encoding.py

@@ -1,18 +1,32 @@
+"""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 itertools import (
-    accumulate,
+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 (
-    int_to_big_endian,
     is_address,
     is_boolean,
     is_bytes,
@@ -22,7 +36,22 @@ from faster_eth_utils import (
     is_text,
     to_canonical_address,
 )
+from typing_extensions import (
+    Self,
+)
 
+from faster_eth_abi._encoding import (
+    encode_elements,
+    encode_elements_dynamic,
+    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,
 )
@@ -45,8 +74,6 @@ from faster_eth_abi.utils.numeric import (
     compute_unsigned_integer_bounds,
 )
 from faster_eth_abi.utils.padding import (
-    fpad,
-    zpad,
     zpad_right,
 )
 from faster_eth_abi.utils.string import (
@@ -69,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
@@ -82,7 +109,7 @@ class BaseEncoder(BaseCoder, metaclass=abc.ABCMeta):
         value: Any,
         exc: Type[Exception] = EncodingTypeError,
         msg: Optional[str] = None,
-    ) -> None:
+    ) -> NoReturn:
         """
         Throws a standard exception for when a value is not encodable by an
         encoder.
@@ -102,57 +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)
 
-    def validate(self):
+        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) -> 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",
-            )
-
-        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",
-            )
-
-        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)
+    @final
+    def validate_value(self, value: Sequence[Any]) -> None:
+        validate_tuple(self, value)
 
-        raw_head_chunks = []
-        tail_chunks = []
-        for value, encoder in zip(values, self.encoders):
-            if getattr(encoder, "is_dynamic", False):
-                raw_head_chunks.append(None)
-                tail_chunks.append(encoder(value))
-            else:
-                raw_head_chunks.append(encoder(value))
-                tail_chunks.append(b"")
-
-        head_length = sum(32 if item is None else len(item) for item in raw_head_chunks)
-        tail_offsets = (0,) + tuple(accumulate(map(len, tail_chunks[:-1])))
-        head_chunks = tuple(
-            encode_uint_256(head_length + offset) if chunk is None else chunk
-            for chunk, offset in zip(raw_head_chunks, tail_offsets)
-        )
+    def encode(self, values: Sequence[Any]) -> bytes:
+        return encode_tuple(self, values)
 
-        encoded_value = b"".join(head_chunks + tuple(tail_chunks))
-        return encoded_value
+    def __call__(self, values: Sequence[Any]) -> bytes:
+        return self.encode(values)
 
     @parse_tuple_type_str
     def from_type_str(cls, abi_type, registry):
@@ -170,42 +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):
+    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")
-        base_encoded_value = self.encode_fn(value)
+        return encode_fixed(value, encode_fn, self.is_big_endian, self.data_byte_size)
 
-        if self.is_big_endian:
-            padded_encoded_value = zpad(base_encoded_value, self.data_byte_size)
-        else:
-            padded_encoded_value = zpad_right(base_encoded_value, self.data_byte_size)
-
-        return padded_encoded_value
+    __call__ = encode
 
 
 class Fixed32ByteSizeEncoder(FixedSizeEncoder):
@@ -217,12 +235,12 @@ class BooleanEncoder(Fixed32ByteSizeEncoder):
     is_big_endian = True
 
     @classmethod
-    def validate_value(cls, value):
+    def validate_value(cls, value: Any) -> None:
         if not is_boolean(value):
             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:
@@ -245,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:
@@ -253,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)
 
@@ -285,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)
 
 
@@ -297,29 +325,44 @@ 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)
 
-    def encode_fn(self, value):
+    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)
-        base_encoded_value = self.encode_fn(value)
-
-        if value >= 0:
-            padded_encoded_value = zpad(base_encoded_value, self.data_byte_size)
-        else:
-            padded_encoded_value = fpad(base_encoded_value, self.data_byte_size)
+        return encode_signed(value, self.encode_fn, self.data_byte_size)
 
-        return padded_encoded_value
+    __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):
@@ -329,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
 
@@ -343,27 +396,36 @@ 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(
                 value,
                 exc=IllegalValue,
-                msg=f"residue {repr(residue)} outside allowed fractional precision of "
+                msg=f"residue {residue!r} outside allowed fractional precision of "
                 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]")
 
 
@@ -371,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)
@@ -404,25 +466,20 @@ 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)
-        base_encoded_value = self.encode_fn(value)
+        return encode_signed(value, self.encode_fn, self.data_byte_size)
 
-        if value >= 0:
-            padded_encoded_value = zpad(base_encoded_value, self.data_byte_size)
-        else:
-            padded_encoded_value = fpad(base_encoded_value, self.data_byte_size)
-
-        return padded_encoded_value
+    __call__ = encode
 
     @parse_type_str("fixed")
     def from_type_str(cls, abi_type, registry):
@@ -452,11 +509,11 @@ class AddressEncoder(Fixed32ByteSizeEncoder):
     is_big_endian = True
 
     @classmethod
-    def validate_value(cls, value):
+    def validate_value(cls, value: Any) -> None:
         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:
@@ -474,7 +531,7 @@ class PackedAddressEncoder(AddressEncoder):
 class BytesEncoder(Fixed32ByteSizeEncoder):
     is_big_endian = False
 
-    def validate_value(self, value):
+    def validate_value(self, value: Any) -> None:
         if not is_bytes(value):
             self.invalidate_value(value)
 
@@ -487,7 +544,7 @@ class BytesEncoder(Fixed32ByteSizeEncoder):
             )
 
     @staticmethod
-    def encode_fn(value):
+    def encode_fn(value: bytes) -> bytes:
         return value
 
     @parse_type_str("bytes")
@@ -508,12 +565,12 @@ class ByteStringEncoder(BaseEncoder):
     is_dynamic = True
 
     @classmethod
-    def validate_value(cls, value):
+    def validate_value(cls, value: Any) -> None:
         if not is_bytes(value):
             cls.invalidate_value(value)
 
     @classmethod
-    def encode(cls, value):
+    def encode(cls, value: bytes) -> bytes:
         cls.validate_value(value)
         value_length = len(value)
 
@@ -522,30 +579,34 @@ 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
 
     @classmethod
-    def validate_value(cls, value):
+    def validate_value(cls, value: Any) -> None:
         if not is_text(value):
             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")
@@ -556,57 +617,47 @@ 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:
             raise ValueError("`item_encoder` may not be none")
 
-    def validate_value(self, value):
+    def validate_value(self, value: Any) -> None:
         if not is_list_like(value):
             self.invalidate_value(
                 value,
                 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):
+    def encode_elements(self, value: Sequence[Any]) -> bytes:
         self.validate_value(value)
-
-        item_encoder = self.item_encoder
-        if item_encoder is None:
-            raise AssertionError("`item_encoder` is None")
-        tail_chunks = tuple(item_encoder(i) for i in value)
-
-        items_are_dynamic = getattr(item_encoder, "is_dynamic", False)
-        if not items_are_dynamic or len(value) == 0:
-            return b"".join(tail_chunks)
-
-        head_length = 32 * len(value)
-        tail_offsets = (0,) + tuple(accumulate(map(len, tail_chunks[:-1])))
-        head_chunks = tuple(
-            encode_uint_256(head_length + offset) for offset in tail_offsets
-        )
-        return b"".join(head_chunks + tail_chunks)
+        return encode_elements(self.item_encoder, value)
 
     @parse_type_str(with_arrlist=True)
     def from_type_str(cls, abi_type, registry):
@@ -627,21 +678,21 @@ class BaseArrayEncoder(BaseEncoder):
 class PackedArrayEncoder(BaseArrayEncoder):
     array_size = None
 
-    def validate_value(self, value):
+    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):
-        encoded_elements = self.encode_elements(value)
+    def encode(self, value: Sequence[Any]) -> bytes:
+        return encode_elements(self.item_encoder, value)
 
-        return encoded_elements
+    __call__ = encode
 
     @parse_type_str(with_arrlist=True)
     def from_type_str(cls, abi_type, registry):
@@ -660,18 +711,18 @@ 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:
             raise ValueError("`array_size` may not be none")
 
-    def validate_value(self, value):
+    def validate_value(self, value: Any) -> None:
         super().validate_value(value)
 
         if len(value) != self.array_size:
@@ -682,18 +733,14 @@ class SizedArrayEncoder(BaseArrayEncoder):
                 "expected",
             )
 
-    def encode(self, value):
-        encoded_elements = self.encode_elements(value)
+    def encode(self, value: Sequence[Any]) -> bytes:
+        return encode_elements(self.item_encoder, value)
 
-        return encoded_elements
+    __call__ = encode
 
 
 class DynamicArrayEncoder(BaseArrayEncoder):
     is_dynamic = True
 
-    def encode(self, value):
-        encoded_size = encode_uint_256(len(value))
-        encoded_elements = self.encode_elements(value)
-        encoded_value = encoded_size + encoded_elements
-
-        return encoded_value
+    def encode(self, value: Sequence[Any]) -> bytes:
+        return encode_elements_dynamic(self.item_encoder, value)