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

faster_eth_abi/_codec.py

@@ -1,3 +1,9 @@
+"""Internal codec helpers for encoding and decoding sequences of values using the head-tail mechanism.
+
+Provides encode_c and decode_c functions for binary serialization and deserialization of values
+according to ABI type specifications.
+"""
+
 from typing import (
     TYPE_CHECKING,
     Any,

faster_eth_abi/_decoding.py

@@ -1,3 +1,8 @@
+"""Private helpers for decoding logic, intended for C compilation.
+
+This file exists because the original decoding.py is not ready to be fully compiled to C.
+This module contains functions and logic that we wish to compile.
+"""
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -19,6 +24,9 @@ from faster_eth_abi.io import (
     BytesIO,
     ContextFramesBytesIO,
 )
+from faster_eth_abi.typing import (
+    T,
+)
 
 if TYPE_CHECKING:
     from .decoding import (
@@ -35,7 +43,7 @@ if TYPE_CHECKING:
 # Helpers
 def decode_uint_256(stream: ContextFramesBytesIO) -> int:
     """
-    This function is a faster version of decode_uint_256 in decoding.py.
+    A faster version of :func:`~decoding.decode_uint_256` in decoding.py.
 
     It recreates the logic from the UnsignedIntegerDecoder, but we can
     skip a lot because we know the value of many vars.
@@ -51,7 +59,7 @@ def get_value_byte_size(decoder: "FixedByteSizeDecoder") -> int:
 
 
 # HeadTailDecoder
-def decode_head_tail(self: "HeadTailDecoder", stream: ContextFramesBytesIO) -> Any:
+def decode_head_tail(self: "HeadTailDecoder[T]", stream: ContextFramesBytesIO) -> T:
     # Decode the offset and move the stream cursor forward 32 bytes
     start_pos = decode_uint_256(stream)
     # Jump ahead to the start of the value
@@ -62,7 +70,7 @@ def decode_head_tail(self: "HeadTailDecoder", stream: ContextFramesBytesIO) -> A
     if tail_decoder is None:
         raise AssertionError("`tail_decoder` is None")
     # Decode the value
-    value = tail_decoder(stream)
+    value: T = tail_decoder(stream)
     # Return the cursor
     stream.pop_frame()
 
@@ -70,7 +78,9 @@ def decode_head_tail(self: "HeadTailDecoder", stream: ContextFramesBytesIO) -> A
 
 
 # TupleDecoder
-def decode_tuple(self: "TupleDecoder", stream: ContextFramesBytesIO) -> Tuple[Any, ...]:
+def decode_tuple(
+    self: "TupleDecoder[T]", stream: ContextFramesBytesIO
+) -> Tuple[T, ...]:
     # NOTE: the original implementation would do this but it's
     # kinda wasteful, so we rebuilt the logic within this function
     # validate_pointers_tuple(self, stream)
@@ -129,7 +139,8 @@ def validate_pointers_tuple(
         total_stream_length = len(stream.getbuffer())
         for decoder, is_head_tail in zip(self.decoders, self._is_head_tail):
             if not is_head_tail:
-                # the next 32 bytes are not a pointer, so progress the stream per the decoder
+                # the next 32 bytes are not a pointer,
+                # so progress the stream per the decoder
                 decoder(stream)
             else:
                 # the next 32 bytes are a pointer
@@ -176,8 +187,8 @@ def validate_pointers_array(
 
 # SizedArrayDecoder
 def decode_sized_array(
-    self: "SizedArrayDecoder", stream: ContextFramesBytesIO
-) -> Tuple[Any, ...]:
+    self: "SizedArrayDecoder[T]", stream: ContextFramesBytesIO
+) -> Tuple[T, ...]:
     item_decoder = self.item_decoder
     if item_decoder is None:
         raise AssertionError("`item_decoder` is None")
@@ -189,8 +200,8 @@ def decode_sized_array(
 
 # DynamicArrayDecoder
 def decode_dynamic_array(
-    self: "DynamicArrayDecoder", stream: ContextFramesBytesIO
-) -> Tuple[Any, ...]:
+    self: "DynamicArrayDecoder[T]", stream: ContextFramesBytesIO
+) -> Tuple[T, ...]:
     array_size = decode_uint_256(stream)
     stream.push_frame(32)
     if self.item_decoder is None:
@@ -206,7 +217,7 @@ def decode_dynamic_array(
 
 # FixedByteSizeDecoder
 def read_fixed_byte_size_data_from_stream(
-    self: "FixedByteSizeDecoder",
+    self: "FixedByteSizeDecoder[Any]",
     # NOTE: use BytesIO here so mypyc doesn't type-check
     # `stream` once we compile ContextFramesBytesIO.
     stream: BytesIO,
@@ -220,7 +231,7 @@ def read_fixed_byte_size_data_from_stream(
 
 
 def split_data_and_padding_fixed_byte_size(
-    self: "FixedByteSizeDecoder",
+    self: "FixedByteSizeDecoder[Any]",
     raw_data: bytes,
 ) -> Tuple[bytes, bytes]:
     value_byte_size = get_value_byte_size(self)
@@ -239,8 +250,8 @@ def split_data_and_padding_fixed_byte_size(
 
 
 def validate_padding_bytes_fixed_byte_size(
-    self: "FixedByteSizeDecoder",
-    value: Any,
+    self: "FixedByteSizeDecoder[T]",
+    value: T,
     padding_bytes: bytes,
 ) -> None:
     if padding_bytes != get_expected_padding_bytes(self, b"\x00"):
@@ -248,11 +259,13 @@ def validate_padding_bytes_fixed_byte_size(
 
 
 _expected_padding_bytes_cache: Final[
-    Dict["FixedByteSizeDecoder", Dict[bytes, bytes]]
+    Dict["FixedByteSizeDecoder[Any]", Dict[bytes, bytes]]
 ] = {}
 
 
-def get_expected_padding_bytes(self: "FixedByteSizeDecoder", chunk: bytes) -> bytes:
+def get_expected_padding_bytes(
+    self: "FixedByteSizeDecoder[Any]", chunk: bytes
+) -> bytes:
     instance_cache = _expected_padding_bytes_cache.setdefault(self, {})
     expected_padding_bytes = instance_cache.get(chunk)
     if expected_padding_bytes is None:

faster_eth_abi/_encoding.py

@@ -1,3 +1,8 @@
+"""Private helpers for encoding logic, intended for C compilation.
+
+This file exists because the original encoding.py is not ready to be fully compiled to C.
+This module contains functions and logic that we do wish to compile.
+"""
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -80,7 +85,7 @@ def encode_tuple_all_dynamic(self: "TupleEncoder", values: Sequence[Any]) -> byt
     validate_tuple(self, values)
     encoders = self.encoders
     tail_chunks = [encoder(value) for encoder, value in zip(encoders, values)]
-    
+
     total_offset = 0
     head_length = 32 * len(encoders)
     head_chunks = [encode_uint_256(head_length)]
@@ -165,6 +170,7 @@ def encode_tuple_no_dynamic10(self: "TupleEncoder", values: Sequence[Any]) -> by
     # encoders: Tuple["BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder", "BaseEncoder"] = self.encoders
     return b"".join(encoders[i](values[i]) for i in range(10))
 
+
 encode_tuple_no_dynamic_funcs: Dict[
     int, Callable[["TupleEncoder", Sequence[Any]], bytes]
 ] = {

faster_eth_abi/_grammar.py

@@ -1,3 +1,8 @@
+"""Private helpers for ABI type string grammar and parsing, intended for C compilation.
+
+This file exists because the original grammar.py is not ready to be fully compiled to C.
+This module contains functions and logic that we do wish to compile.
+"""
 import re
 from typing import (
     Any,

faster_eth_abi/base.py

@@ -1,3 +1,7 @@
+"""Base classes for encoder and decoder implementations.
+
+Defines the foundational interface and validation logic for all coder classes.
+"""
 from typing import (
     Any,
 )