faster-eth-abi 5.2.23__cp314-cp314-musllinux_1_2_x86_64.whl

faster_eth_abi/registry.py

@@ -0,0 +1,758 @@
+"""Registry and predicate logic for ABI encoders and decoders.
+
+Implements registration, lookup, and matching of encoders and decoders for ABI type strings.
+"""
+import abc
+from copy import (
+    copy,
+)
+import functools
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Final,
+    Generic,
+    Iterator,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    final,
+)
+
+from eth_typing import (
+    TypeStr,
+)
+from typing_extensions import (
+    Concatenate,
+    ParamSpec,
+    Self,
+)
+
+from . import (
+    decoding,
+    encoding,
+    exceptions,
+    grammar,
+)
+from .base import (
+    BaseCoder,
+)
+from .exceptions import (
+    MultipleEntriesFound,
+    NoEntriesFound,
+)
+from .io import (
+    ContextFramesBytesIO,
+)
+
+T = TypeVar("T")
+P = ParamSpec("P")
+
+Lookup = Union[TypeStr, Callable[[TypeStr], bool]]
+
+EncoderCallable = Callable[[Any], bytes]
+DecoderCallable = Callable[[ContextFramesBytesIO], Any]
+
+Encoder = Union[EncoderCallable, Type[encoding.BaseEncoder]]
+Decoder = Union[DecoderCallable, Type[decoding.BaseDecoder]]
+
+
+class Copyable(abc.ABC):
+    @abc.abstractmethod
+    def copy(self) -> Self:
+        pass
+
+    def __copy__(self) -> Self:
+        return self.copy()
+
+    def __deepcopy__(self, *args: Any) -> Self:
+        return self.copy()
+
+
+class PredicateMapping(Copyable, Generic[T]):
+    """
+    Acts as a mapping from predicate functions to values.  Values are retrieved
+    when their corresponding predicate matches a given input.  Predicates can
+    also be labeled to facilitate removal from the mapping.
+    """
+
+    def __init__(self, name: str):
+        self._name: Final = name
+        self._values: Dict[Lookup, T] = {}
+        self._labeled_predicates: Dict[str, Lookup] = {}
+
+    def add(self, predicate: Lookup, value: T, label: Optional[str] = None) -> None:
+        if predicate in self._values:
+            raise ValueError(f"Matcher {predicate!r} already exists in {self._name}")
+
+        if label is not None:
+            labeled_predicates = self._labeled_predicates
+            if label in labeled_predicates:
+                raise ValueError(
+                    f"Matcher {predicate!r} with label '{label}' "
+                    f"already exists in {self._name}"
+                )
+
+            labeled_predicates[label] = predicate
+
+        self._values[predicate] = value
+
+    def find(self, type_str: TypeStr) -> T:
+        results = tuple(
+            (predicate, value)
+            for predicate, value in self._values.items()
+            if predicate(type_str)
+        )
+
+        if len(results) == 0:
+            raise NoEntriesFound(
+                f"No matching entries for '{type_str}' in {self._name}"
+            )
+
+        predicates, values = tuple(zip(*results))
+
+        if len(results) > 1:
+            predicate_reprs = ", ".join(map(repr, predicates))
+            raise MultipleEntriesFound(
+                f"Multiple matching entries for '{type_str}' in {self._name}: "
+                f"{predicate_reprs}. This occurs when two registrations match the "
+                "same type string. You may need to delete one of the "
+                "registrations or modify its matching behavior to ensure it "
+                'doesn\'t collide with other registrations. See the "Registry" '
+                "documentation for more information."
+            )
+
+        return values[0]  # type: ignore [no-any-return]
+
+    def remove_by_equality(self, predicate: Lookup) -> None:
+        # Delete the predicate mapping to the previously stored value
+        try:
+            del self._values[predicate]
+        except KeyError:
+            raise KeyError(f"Matcher {predicate!r} not found in {self._name}")
+
+        # Delete any label which refers to this predicate
+        try:
+            label = self._label_for_predicate(predicate)
+        except ValueError:
+            pass
+        else:
+            del self._labeled_predicates[label]
+
+    def _label_for_predicate(self, predicate: Lookup) -> str:
+        # Both keys and values in `_labeled_predicates` are unique since the
+        # `add` method enforces this
+        for key, value in self._labeled_predicates.items():
+            if value is predicate:
+                return key
+
+        raise ValueError(
+            f"Matcher {predicate!r} not referred to by any label in {self._name}"
+        )
+
+    def remove_by_label(self, label: str) -> None:
+        labeled_predicates = self._labeled_predicates
+        try:
+            predicate = labeled_predicates[label]
+        except KeyError:
+            raise KeyError(f"Label '{label}' not found in {self._name}")
+
+        del labeled_predicates[label]
+        del self._values[predicate]
+
+    def remove(self, predicate_or_label: Union[Lookup, str]) -> None:
+        if callable(predicate_or_label):
+            self.remove_by_equality(predicate_or_label)
+        elif isinstance(predicate_or_label, str):
+            self.remove_by_label(predicate_or_label)
+        else:
+            raise TypeError(
+                "Key to be removed must be callable or string: got "
+                f"{type(predicate_or_label)}"
+            )
+
+    def copy(self) -> Self:
+        cpy = type(self)(self._name)
+
+        cpy._values = copy(self._values)
+        cpy._labeled_predicates = copy(self._labeled_predicates)
+
+        return cpy
+
+
+class Predicate(Generic[T]):
+    """
+    Represents a predicate function to be used for type matching in
+    ``ABIRegistry``.
+    """
+
+    __slots__ = ("_string", "__hash")
+
+    _string: Optional[str]
+
+    def __init__(self) -> None:
+        self._string = None
+        self.__hash = None
+
+    def __call__(self, arg: TypeStr) -> None:
+        raise NotImplementedError("Must implement `__call__`")
+
+    def __str__(self) -> str:
+        raise NotImplementedError("Must implement `__str__`")
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self}>"
+
+    def __iter__(self) -> Iterator[T]:
+        raise NotImplementedError("must be implemented by subclass")
+
+    def __hash__(self) -> int:
+        hashval = self.__hash
+        if hashval is None:
+            self.__hash = hashval = hash(tuple(self))
+        return hashval
+
+    def __eq__(self, other: "Predicate") -> bool:
+        return type(self) is type(other) and tuple(self) == tuple(other)
+
+
+@final
+class Equals(Predicate[str]):
+    """
+    A predicate that matches any input equal to `value`.
+    """
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: str) -> None:
+        super().__init__()
+        self.value: Final = value
+
+    def __call__(self, other: TypeStr) -> bool:
+        return self.value == other
+
+    def __str__(self) -> str:
+        # NOTE should this just be done at init time? is it always called?
+        string = self._string
+        if string is None:
+            self._string = string = f"(== {self.value!r})"
+        return string
+
+    def __iter__(self) -> Iterator[str]:
+        yield self.value
+
+
+@final
+class BaseEquals(Predicate[Union[str, bool, None]]):
+    """
+    A predicate that matches a basic type string with a base component equal to
+    `value` and no array component.  If `with_sub` is `True`, the type string
+    must have a sub component to match.  If `with_sub` is `False`, the type
+    string must *not* have a sub component to match.  If `with_sub` is None,
+    the type string's sub component is ignored.
+    """
+
+    __slots__ = ("base", "with_sub")
+
+    def __init__(self, base: TypeStr, *, with_sub: Optional[bool] = None):
+        super().__init__()
+        self.base: Final = base
+        self.with_sub: Final = with_sub
+
+    def __call__(self, type_str: TypeStr) -> bool:
+        try:
+            abi_type = grammar.parse(type_str)
+        except (exceptions.ParseError, ValueError):
+            return False
+
+        if isinstance(abi_type, grammar.BasicType):
+            if abi_type.arrlist is not None:
+                return False
+
+            with_sub = self.with_sub
+            if with_sub is not None:
+                abi_subtype = abi_type.sub
+                if with_sub and abi_subtype is None:
+                    return False
+                if not with_sub and abi_subtype is not None:
+                    return False
+
+            return abi_type.base == self.base
+
+        # We'd reach this point if `type_str` did not contain a basic type
+        # e.g. if it contained a tuple type
+        return False
+
+    def __str__(self) -> str:
+        # NOTE should this just be done at init time? is it always called?
+        string = self._string
+        if string is None:
+            if self.with_sub is None:
+                string = f"(base == {self.base!r})"
+            elif self.with_sub:
+                string = f"(base == {self.base!r} and sub is not None)"
+            else:
+                string = f"(base == {self.base!r} and sub is None)"
+            self._string = string
+        return string
+
+    def __iter__(self) -> Iterator[Union[str, bool, None]]:
+        yield self.base
+        yield self.with_sub
+
+
+def has_arrlist(type_str: TypeStr) -> bool:
+    """
+    A predicate that matches a type string with an array dimension list.
+    """
+    try:
+        abi_type = grammar.parse(type_str)
+    except (exceptions.ParseError, ValueError):
+        return False
+
+    return abi_type.arrlist is not None
+
+
+def is_base_tuple(type_str: TypeStr) -> bool:
+    """
+    A predicate that matches a tuple type with no array dimension list.
+    """
+    try:
+        abi_type = grammar.parse(type_str)
+    except (exceptions.ParseError, ValueError):
+        return False
+
+    return isinstance(abi_type, grammar.TupleType) and abi_type.arrlist is None
+
+
+def _clear_encoder_cache(
+    old_method: Callable[Concatenate["ABIRegistry", P], T]
+) -> Callable[Concatenate["ABIRegistry", P], T]:
+    @functools.wraps(old_method)
+    def new_method(self: "ABIRegistry", *args: P.args, **kwargs: P.kwargs) -> T:
+        self.get_encoder.cache_clear()
+        self.get_tuple_encoder.cache_clear()
+        return old_method(self, *args, **kwargs)
+
+    return new_method
+
+
+def _clear_decoder_cache(
+    old_method: Callable[Concatenate["ABIRegistry", P], T]
+) -> Callable[Concatenate["ABIRegistry", P], T]:
+    @functools.wraps(old_method)
+    def new_method(self: "ABIRegistry", *args: P.args, **kwargs: P.kwargs) -> T:
+        self.get_decoder.cache_clear()
+        self.get_tuple_decoder.cache_clear()
+        return old_method(self, *args, **kwargs)
+
+    return new_method
+
+
+class BaseRegistry:
+    @staticmethod
+    def _register(
+        mapping: PredicateMapping[T],
+        lookup: Lookup,
+        value: T,
+        label: Optional[str] = None,
+    ) -> None:
+        if callable(lookup):
+            mapping.add(lookup, value, label)
+            return
+
+        if isinstance(lookup, str):
+            mapping.add(Equals(lookup), value, lookup)
+            return
+
+        raise TypeError(
+            f"Lookup must be a callable or a value of type `str`: got {lookup!r}"
+        )
+
+    @staticmethod
+    def _unregister(mapping: PredicateMapping[Any], lookup_or_label: Lookup) -> None:
+        if callable(lookup_or_label):
+            mapping.remove_by_equality(lookup_or_label)
+            return
+
+        if isinstance(lookup_or_label, str):
+            mapping.remove_by_label(lookup_or_label)
+            return
+
+        raise TypeError(
+            f"Lookup/label must be a callable or a value of type `str`: "
+            f"got {lookup_or_label!r}"
+        )
+
+    @staticmethod
+    def _get_registration(mapping: PredicateMapping[T], type_str: TypeStr) -> T:
+        try:
+            value = mapping.find(type_str)
+        except ValueError as e:
+            if "No matching" in e.args[0]:
+                # If no matches found, attempt to parse in case lack of matches
+                # was due to unparsability
+                grammar.parse(type_str)
+
+            raise
+
+        return value
+
+
+class ABIRegistry(Copyable, BaseRegistry):
+    def __init__(self) -> None:
+        self._encoders: PredicateMapping[Encoder] = PredicateMapping("encoder registry")
+        self._decoders: PredicateMapping[Decoder] = PredicateMapping("decoder registry")
+        self.get_encoder = functools.lru_cache(maxsize=None)(self._get_encoder_uncached)
+        self.get_decoder = functools.lru_cache(maxsize=None)(self._get_decoder_uncached)
+        self.get_tuple_encoder = functools.lru_cache(maxsize=None)(
+            self._get_tuple_encoder_uncached
+        )
+        self.get_tuple_decoder = functools.lru_cache(maxsize=None)(
+            self._get_tuple_decoder_uncached
+        )
+
+    def _get_registration(self, mapping: PredicateMapping[T], type_str: TypeStr) -> T:
+        coder = super()._get_registration(mapping, type_str)
+
+        if isinstance(coder, type) and issubclass(coder, BaseCoder):
+            return coder.from_type_str(type_str, self)
+
+        return cast(T, coder)
+
+    @_clear_encoder_cache
+    def register_encoder(
+        self, lookup: Lookup, encoder: Encoder, label: Optional[str] = None
+    ) -> None:
+        """
+        Registers the given ``encoder`` under the given ``lookup``.  A unique
+        string label may be optionally provided that can be used to refer to
+        the registration by name.  For more information about arguments, refer
+        to :any:`register`.
+        """
+        self._register(self._encoders, lookup, encoder, label=label)
+
+    @_clear_encoder_cache
+    def unregister_encoder(self, lookup_or_label: Lookup) -> None:
+        """
+        Unregisters an encoder in the registry with the given lookup or label.
+        If ``lookup_or_label`` is a string, the encoder with the label
+        ``lookup_or_label`` will be unregistered.  If it is an function, the
+        encoder with the lookup function ``lookup_or_label`` will be
+        unregistered.
+        """
+        self._unregister(self._encoders, lookup_or_label)
+
+    @_clear_decoder_cache
+    def register_decoder(
+        self, lookup: Lookup, decoder: Decoder, label: Optional[str] = None
+    ) -> None:
+        """
+        Registers the given ``decoder`` under the given ``lookup``.  A unique
+        string label may be optionally provided that can be used to refer to
+        the registration by name.  For more information about arguments, refer
+        to :any:`register`.
+        """
+        self._register(self._decoders, lookup, decoder, label=label)
+
+    @_clear_decoder_cache
+    def unregister_decoder(self, lookup_or_label: Lookup) -> None:
+        """
+        Unregisters a decoder in the registry with the given lookup or label.
+        If ``lookup_or_label`` is a string, the decoder with the label
+        ``lookup_or_label`` will be unregistered.  If it is an function, the
+        decoder with the lookup function ``lookup_or_label`` will be
+        unregistered.
+        """
+        self._unregister(self._decoders, lookup_or_label)
+
+    def register(
+        self,
+        lookup: Lookup,
+        encoder: Encoder,
+        decoder: Decoder,
+        label: Optional[str] = None,
+    ) -> None:
+        """
+        Registers the given ``encoder`` and ``decoder`` under the given
+        ``lookup``.  A unique string label may be optionally provided that can
+        be used to refer to the registration by name.
+
+        :param lookup: A type string or type string matcher function
+            (predicate).  When the registry is queried with a type string
+            ``query`` to determine which encoder or decoder to use, ``query``
+            will be checked against every registration in the registry.  If a
+            registration was created with a type string for ``lookup``, it will
+            be considered a match if ``lookup == query``.  If a registration
+            was created with a matcher function for ``lookup``, it will be
+            considered a match if ``lookup(query) is True``.  If more than one
+            registration is found to be a match, then an exception is raised.
+
+        :param encoder: An encoder callable or class to use if ``lookup``
+            matches a query.  If ``encoder`` is a callable, it must accept a
+            python value and return a ``bytes`` value.  If ``encoder`` is a
+            class, it must be a valid subclass of :any:`encoding.BaseEncoder`
+            and must also implement the :any:`from_type_str` method on
+            :any:`base.BaseCoder`.
+
+        :param decoder: A decoder callable or class to use if ``lookup``
+            matches a query.  If ``decoder`` is a callable, it must accept a
+            stream-like object of bytes and return a python value.  If
+            ``decoder`` is a class, it must be a valid subclass of
+            :any:`decoding.BaseDecoder` and must also implement the
+            :any:`from_type_str` method on :any:`base.BaseCoder`.
+
+        :param label: An optional label that can be used to refer to this
+            registration by name.  This label can be used to unregister an
+            entry in the registry via the :any:`unregister` method and its
+            variants.
+        """
+        self.register_encoder(lookup, encoder, label=label)
+        self.register_decoder(lookup, decoder, label=label)
+
+    def unregister(self, label: Optional[str]) -> None:
+        """
+        Unregisters the entries in the encoder and decoder registries which
+        have the label ``label``.
+        """
+        self.unregister_encoder(label)
+        self.unregister_decoder(label)
+
+    def _get_encoder_uncached(self, type_str: TypeStr) -> Encoder:
+        return self._get_registration(self._encoders, type_str)
+
+    def _get_tuple_encoder_uncached(
+        self,
+        *type_strs: TypeStr,
+    ) -> encoding.TupleEncoder:
+        encoders = tuple(map(self.get_encoder, type_strs))
+        return encoding.TupleEncoder(encoders=encoders)
+
+    def has_encoder(self, type_str: TypeStr) -> bool:
+        """
+        Returns ``True`` if an encoder is found for the given type string
+        ``type_str``.  Otherwise, returns ``False``.  Raises
+        :class:`~faster_eth_abi.exceptions.MultipleEntriesFound` if multiple encoders
+        are found.
+        """
+        try:
+            self.get_encoder(type_str)
+        except Exception as e:
+            if isinstance(e, MultipleEntriesFound):
+                raise e
+            return False
+
+        return True
+
+    def _get_decoder_uncached(self, type_str: TypeStr, strict: bool = True) -> Decoder:
+        decoder = self._get_registration(self._decoders, type_str)
+
+        if hasattr(decoder, "is_dynamic") and decoder.is_dynamic:
+            # Set a transient flag each time a call is made to ``get_decoder()``.
+            # Only dynamic decoders should be allowed these looser constraints. All
+            # other decoders should keep the default value of ``True``.
+            decoder.strict = strict
+
+        return decoder
+
+    def _get_tuple_decoder_uncached(
+        self,
+        *type_strs: TypeStr,
+        strict: bool = True,
+    ) -> decoding.TupleDecoder:
+        decoders = tuple(
+            self.get_decoder(type_str, strict)
+            for type_str in type_strs
+        )
+        return decoding.TupleDecoder(decoders=decoders)
+
+    def copy(self) -> Self:
+        """
+        Copies a registry such that new registrations can be made or existing
+        registrations can be unregistered without affecting any instance from
+        which a copy was obtained.  This is useful if an existing registry
+        fulfills most of a user's needs but requires one or two modifications.
+        In that case, a copy of that registry can be obtained and the necessary
+        changes made without affecting the original registry.
+        """
+        cpy = type(self)()
+
+        cpy._encoders = copy(self._encoders)
+        cpy._decoders = copy(self._decoders)
+
+        return cpy
+
+
+registry = ABIRegistry()
+
+is_int = BaseEquals("int")
+is_int8 = Equals("int8")
+is_int16 = Equals("int16")
+is_uint = BaseEquals("uint")
+is_uint8 = Equals("uint8")
+is_uint16 = Equals("uint16")
+
+for size in (8, 16):
+    registry.register(
+        Equals(f"uint{size}"),
+        encoding.UnsignedIntegerEncoder,
+        decoding.UnsignedIntegerDecoder,
+        label=f"uint{size}",
+    )
+    registry.register(
+        Equals(f"int{size}"),
+        encoding.SignedIntegerEncoder,
+        decoding.SignedIntegerDecoder,
+        label=f"int{size}",
+    )
+
+registry.register(
+    lambda s: is_uint(s) and not is_uint8(s) and not is_uint16(s),
+    encoding.UnsignedIntegerEncoder,
+    decoding.UnsignedIntegerDecoder,
+    label="uint",
+)
+registry.register(
+    lambda s: is_int(s) and not is_int8(s) and not is_int16(s),
+    encoding.SignedIntegerEncoder,
+    decoding.SignedIntegerDecoder,
+    label="int",
+)
+registry.register(
+    BaseEquals("address"),
+    encoding.AddressEncoder,
+    decoding.AddressDecoder,
+    label="address",
+)
+registry.register(
+    BaseEquals("bool"),
+    encoding.BooleanEncoder,
+    decoding.BooleanDecoder,
+    label="bool",
+)
+registry.register(
+    BaseEquals("ufixed"),
+    encoding.UnsignedFixedEncoder,
+    decoding.UnsignedFixedDecoder,
+    label="ufixed",
+)
+registry.register(
+    BaseEquals("fixed"),
+    encoding.SignedFixedEncoder,
+    decoding.SignedFixedDecoder,
+    label="fixed",
+)
+registry.register(
+    BaseEquals("bytes", with_sub=True),
+    encoding.BytesEncoder,
+    decoding.BytesDecoder,
+    label="bytes<M>",
+)
+registry.register(
+    BaseEquals("bytes", with_sub=False),
+    encoding.ByteStringEncoder,
+    decoding.ByteStringDecoder,
+    label="bytes",
+)
+registry.register(
+    BaseEquals("function"),
+    encoding.BytesEncoder,
+    decoding.BytesDecoder,
+    label="function",
+)
+registry.register(
+    BaseEquals("string"),
+    encoding.TextStringEncoder,
+    decoding.StringDecoder,
+    label="string",
+)
+registry.register(
+    has_arrlist,
+    encoding.BaseArrayEncoder,
+    decoding.BaseArrayDecoder,
+    label="has_arrlist",
+)
+registry.register(
+    is_base_tuple,
+    encoding.TupleEncoder,
+    decoding.TupleDecoder,
+    label="is_base_tuple",
+)
+
+registry_packed = ABIRegistry()
+
+for size in (8, 16):
+    registry_packed.register_encoder(
+        Equals(f"uint{size}"),
+        encoding.PackedUnsignedIntegerEncoderCached,
+        label=f"uint{size}",
+    )
+    registry_packed.register_encoder(
+        Equals(f"int{size}"),
+        encoding.PackedSignedIntegerEncoderCached,
+        label=f"int{size}",
+    )
+
+registry_packed.register_encoder(
+    lambda s: is_uint(s) and not is_uint8(s) and not is_uint16(s),
+    encoding.PackedUnsignedIntegerEncoder,
+    label="uint",
+)
+registry_packed.register_encoder(
+    lambda s: is_int(s) and not is_int8(s) and not is_int16(s),
+    encoding.PackedSignedIntegerEncoder,
+    label="int",
+)
+registry_packed.register_encoder(
+    BaseEquals("address"),
+    encoding.PackedAddressEncoder,
+    label="address",
+)
+registry_packed.register_encoder(
+    BaseEquals("bool"),
+    encoding.PackedBooleanEncoder,
+    label="bool",
+)
+registry_packed.register_encoder(
+    BaseEquals("ufixed"),
+    encoding.PackedUnsignedFixedEncoder,
+    label="ufixed",
+)
+registry_packed.register_encoder(
+    BaseEquals("fixed"),
+    encoding.PackedSignedFixedEncoder,
+    label="fixed",
+)
+registry_packed.register_encoder(
+    BaseEquals("bytes", with_sub=True),
+    encoding.PackedBytesEncoder,
+    label="bytes<M>",
+)
+registry_packed.register_encoder(
+    BaseEquals("bytes", with_sub=False),
+    encoding.PackedByteStringEncoder,
+    label="bytes",
+)
+registry_packed.register_encoder(
+    BaseEquals("function"),
+    encoding.PackedBytesEncoder,
+    label="function",
+)
+registry_packed.register_encoder(
+    BaseEquals("string"),
+    encoding.PackedTextStringEncoder,
+    label="string",
+)
+registry_packed.register_encoder(
+    has_arrlist,
+    encoding.PackedArrayEncoder,
+    label="has_arrlist",
+)
+registry_packed.register_encoder(
+    is_base_tuple,
+    encoding.TupleEncoder,
+    label="is_base_tuple",
+)