faster-eth-utils 5.3.20__cp314-cp314-win32.whl

faster_eth_utils/address.py

@@ -0,0 +1,145 @@
+import re
+from typing import (
+    Any,
+    Final,
+    Union,
+)
+
+import cchecksum
+from eth_typing import (
+    Address,
+    AnyAddress,
+    ChecksumAddress,
+    HexAddress,
+    HexStr,
+)
+from typing_extensions import (
+    TypeGuard,
+)
+
+from .conversions import (
+    hexstr_if_str,
+    to_hex,
+)
+from .crypto import (
+    keccak,
+)
+from .hexadecimal import (
+    add_0x_prefix,
+    decode_hex,
+    encode_hex,
+    remove_0x_prefix,
+)
+from .types import (
+    is_bytes,
+    is_text,
+)
+
+_HEX_ADDRESS_REGEXP: Final = re.compile("(0x)?[0-9a-f]{40}", re.IGNORECASE | re.ASCII)
+
+
+to_checksum_address: Final = cchecksum.to_checksum_address
+"""
+Makes a checksum address given a supported format.
+We use the `cchecksum` implementation for max speed.
+"""
+
+
+def is_hex_address(value: Any) -> TypeGuard[HexAddress]:
+    """
+    Checks if the given string of text type is an address in hexadecimal encoded form.
+    """
+    if not is_text(value):
+        return False
+    return _HEX_ADDRESS_REGEXP.fullmatch(value) is not None
+
+
+def is_binary_address(value: Any) -> TypeGuard[bytes]:
+    """
+    Checks if the given string is an address in raw bytes form.
+    """
+    if not is_bytes(value):
+        return False
+    elif len(value) != 20:
+        return False
+    else:
+        return True
+
+
+def is_address(value: Any) -> bool:
+    """
+    Is the given string an address in any of the known formats?
+    """
+    if is_hex_address(value) or is_binary_address(value):
+        return True
+
+    return False
+
+
+def to_normalized_address(value: Union[AnyAddress, str, bytes]) -> HexAddress:
+    """
+    Converts an address to its normalized hexadecimal representation.
+    """
+    try:
+        hex_address = hexstr_if_str(to_hex, value).lower()
+    except AttributeError:
+        raise TypeError(f"Value must be any string, instead got type {type(value)}")
+    if is_address(hex_address):
+        return HexAddress(HexStr(hex_address))
+    else:
+        raise ValueError(
+            f"Unknown format {repr(value)}, attempted to normalize to "
+            f"{repr(hex_address)}"
+        )
+
+
+def is_normalized_address(value: Any) -> TypeGuard[HexAddress]:
+    """
+    Returns whether the provided value is an address in its normalized form.
+    """
+    return is_address(value) and value == to_normalized_address(value)
+
+
+def to_canonical_address(address: Union[AnyAddress, str, bytes]) -> Address:
+    """
+    Convert a valid address to its canonical form (20-length bytes).
+    """
+    return Address(decode_hex(to_normalized_address(address)))
+
+
+def is_canonical_address(address: Any) -> TypeGuard[Address]:
+    """
+    Returns `True` if the `value` is an address in its canonical form.
+    """
+    return is_binary_address(address) and address == to_canonical_address(address)
+8
+
+def is_same_address(
+    left: Union[AnyAddress, str, bytes], right: Union[AnyAddress, str, bytes]
+) -> bool:
+    """
+    Checks if both addresses are same or not.
+    """
+    if not is_address(left) or not is_address(right):
+        raise ValueError("Both values must be valid addresses")
+    else:
+        return to_normalized_address(left) == to_normalized_address(right)
+
+
+def is_checksum_address(value: Any) -> TypeGuard[ChecksumAddress]:
+    if not is_hex_address(value):
+        return False
+    return value == to_checksum_address(value)
+
+
+def _is_checksum_formatted(value: Any) -> bool:
+    unprefixed_value = remove_0x_prefix(value)
+    return (
+        not unprefixed_value.islower()
+        and not unprefixed_value.isupper()
+        and not unprefixed_value.isnumeric()
+    )
+
+
+def is_checksum_formatted_address(value: Any) -> bool:
+    return is_hex_address(value) and _is_checksum_formatted(value)

faster_eth_utils/applicators.py

@@ -0,0 +1,209 @@
+import sys
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Generator,
+    List,
+    Mapping,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+import warnings
+
+from typing_extensions import (
+    TypeGuard,
+)
+
+from .decorators import (
+    return_arg_type,
+)
+from .pydantic import (
+    CamelModel,
+)
+from .toolz import (
+    compose,
+    curry,
+)
+
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 9):
+        from _typeshed import SupportsBool
+    # We have to sacrifice a little bit of specificity on dinosaur Python3.8
+    else:
+        SupportsBool = Any
+
+TArg = TypeVar("TArg")
+TReturn = TypeVar("TReturn")
+TOther = TypeVar("TOther")
+
+Formatters = Callable[[List[Any]], List[Any]]
+
+
+@return_arg_type(2)
+def apply_formatter_at_index(
+    formatter: Callable[[TArg], TReturn],
+    at_index: int,
+    value: Sequence[Union[TArg, TOther]],
+) -> Generator[Union[TOther, TReturn], None, None]:
+    try:
+        item = value[at_index]
+    except IndexError:
+        raise IndexError(
+            f"Not enough values in iterable to apply formatter. Got: {len(value)}. "
+            f"Need: {at_index + 1}"
+        ) from None
+
+    yield from cast(Sequence[TOther], value[:at_index])
+    yield formatter(cast(TArg, item))
+    yield from cast(Sequence[TOther], value[at_index + 1 :])
+
+
+def combine_argument_formatters(*formatters: Callable[..., Any]) -> Formatters:
+    warnings.warn(
+        DeprecationWarning(
+            "combine_argument_formatters(formatter1, formatter2)([item1, item2])"
+            "has been deprecated and will be removed in a subsequent major version "
+            "release of the eth-utils library. Update your calls to use "
+            "apply_formatters_to_sequence([formatter1, formatter2], [item1, item2]) "
+            "instead."
+        ),
+        stacklevel=2,
+    )
+
+    _formatter_at_index = curry(apply_formatter_at_index)
+    return compose(  # type: ignore [no-any-return]
+        *(
+            _formatter_at_index(formatter, index)
+            for index, formatter in enumerate(formatters)
+        )
+    )
+
+
+@return_arg_type(1)
+def apply_formatters_to_sequence(
+    formatters: List[Callable[[Any], TReturn]], sequence: Sequence[Any]
+) -> Generator[TReturn, None, None]:
+    num_formatters = len(formatters)
+    num_items = len(sequence)
+    if num_formatters == num_items:
+        for formatter, item in zip(formatters, sequence):
+            yield formatter(item)
+    elif num_formatters > num_items:
+        raise IndexError(
+            f"Too many formatters for sequence: {num_formatters} formatters for "
+            f"{sequence!r}"
+        )
+    else:
+        raise IndexError(
+            f"Too few formatters for sequence: {num_formatters} formatters for "
+            f"{sequence!r}"
+        )
+
+
+@overload
+def apply_formatter_if(
+    condition: Callable[[TArg], TypeGuard[TOther]],
+    formatter: Callable[[TOther], TReturn],
+    value: TArg,
+) -> Union[TArg, TReturn]: ...
+
+
+@overload
+def apply_formatter_if(
+    condition: Callable[[TArg], bool], formatter: Callable[[TArg], TReturn], value: TArg
+) -> Union[TArg, TReturn]: ...
+
+
+def apply_formatter_if(  # type: ignore [misc]
+    condition: Union[Callable[[TArg], TypeGuard[TOther]], Callable[[TArg], bool]],
+    formatter: Union[Callable[[TOther], TReturn], Callable[[TArg], TReturn]],
+    value: TArg,
+) -> Union[TArg, TReturn]:
+    if condition(value):
+        return formatter(value)  # type: ignore [arg-type]
+    else:
+        return value
+
+
+def apply_formatters_to_dict(
+    formatters: Dict[Any, Any],
+    value: Union[Dict[Any, Any], CamelModel],
+    unaliased: bool = False,
+) -> Dict[Any, Any]:
+    """
+    Apply formatters to a dictionary of values. If the value is a pydantic model,
+    it will be serialized to a dictionary first, taking into account the
+    ``unaliased`` parameter.
+
+    :param formatters: The formatters to apply to the dictionary.
+    :param value: The dictionary-like object to apply the formatters to.
+    :param unaliased: If the model is a ``CamelModel``, whether to turn off
+        serialization by alias (camelCase).
+    :return: A generator that yields the formatted key-value pairs.
+    """
+    if isinstance(value, CamelModel):
+        value = value.model_dump(by_alias=not unaliased)
+
+    def get_value(key: Any, val: Any) -> Any:
+        if key not in formatters:
+            return val
+        try:
+            return formatters[key](val)
+        except ValueError as exc:
+            raise ValueError(
+                f"Could not format invalid value {val!r} as field {key!r}"
+            ) from exc
+        except TypeError as exc:
+            raise TypeError(
+                f"Could not format invalid type {val!r} as field {key!r}"
+            ) from exc
+
+    return {key: get_value(key, val) for key, val in value.items()}
+
+
+@return_arg_type(1)
+def apply_formatter_to_array(
+    formatter: Callable[[TArg], TReturn], value: Sequence[TArg]
+) -> Generator[TReturn, None, None]:
+    for item in value:
+        yield formatter(item)
+
+
+def apply_one_of_formatters(
+    formatter_condition_pairs: Tuple[
+        Tuple[Callable[[TArg], "SupportsBool"], Callable[[TArg], TReturn]], ...
+    ],
+    value: TArg,
+) -> TReturn:
+    for condition, formatter in formatter_condition_pairs:
+        if condition(value):
+            return formatter(value)
+    else:
+        raise ValueError(
+            "The provided value did not satisfy any of the formatter conditions"
+        )
+
+
+def apply_key_map(
+    key_mappings: Dict[Any, Any], value: Mapping[Any, Any]
+) -> Dict[Any, Any]:
+    key_conflicts = (
+        set(value.keys())
+        .difference(key_mappings.keys())
+        .intersection(v for k, v in key_mappings.items() if v in value)
+    )
+    if key_conflicts:
+        raise KeyError(
+            f"Could not apply key map due to conflicting key(s): {key_conflicts}"
+        )
+
+    def get_key(key: Any) -> Any:
+        return key_mappings[key] if key in key_mappings else key
+
+    return {get_key(key): item for key, item in value.items()}

faster_eth_utils/conversions.py

@@ -0,0 +1,191 @@
+from typing import (
+    Callable,
+    Optional,
+    TypeVar,
+    Union,
+)
+
+from eth_typing import (
+    HexStr,
+    Primitives,
+)
+
+from .encoding import (
+    big_endian_to_int,
+    int_to_big_endian,
+)
+from .hexadecimal import (
+    add_0x_prefix,
+    decode_hex,
+    encode_hex,
+    is_hexstr,
+    remove_0x_prefix,
+)
+from .types import (
+    is_string,
+)
+
+T = TypeVar("T")
+
+BytesLike = Union[Primitives, bytearray, memoryview]
+
+
+def to_hex(
+    primitive: Optional[BytesLike] = None,
+    hexstr: Optional[HexStr] = None,
+    text: Optional[str] = None,
+) -> HexStr:
+    """
+    Auto converts any supported value into its hex representation.
+    Trims leading zeros, as defined in:
+    https://github.com/ethereum/wiki/wiki/JSON-RPC#hex-value-encoding
+    """
+    if hexstr is not None:
+        return add_0x_prefix(HexStr(hexstr.lower()))
+
+    if text is not None:
+        return encode_hex(text.encode("utf-8"))
+
+    if isinstance(primitive, bool):
+        return HexStr("0x1") if primitive else HexStr("0x0")
+
+    if isinstance(primitive, (bytes, bytearray)):
+        return encode_hex(primitive)
+
+    if isinstance(primitive, memoryview):
+        return encode_hex(bytes(primitive))
+
+    elif is_string(primitive):
+        raise TypeError(
+            "Unsupported type: The primitive argument must be one of: bytes,"
+            "bytearray, int or bool and not str"
+        )
+
+    if isinstance(primitive, int):
+        return HexStr(hex(primitive))
+
+    raise TypeError(
+        f"Unsupported type: '{repr(type(primitive))}'. Must be one of: bool, str, "
+        "bytes, bytearray or int."
+    )
+
+
+def to_int(
+    primitive: Optional[BytesLike] = None,
+    hexstr: Optional[HexStr] = None,
+    text: Optional[str] = None,
+) -> int:
+    """
+    Converts value to its integer representation.
+    Values are converted this way:
+
+     * primitive:
+
+       * bytes, bytearray, memoryview: big-endian integer
+       * bool: True => 1, False => 0
+       * int: unchanged
+     * hexstr: interpret hex as integer
+     * text: interpret as string of digits, like '12' => 12
+    """
+    if hexstr is not None:
+        return int(hexstr, 16)
+    elif text is not None:
+        return int(text)
+    elif isinstance(primitive, (bytes, bytearray)):
+        return big_endian_to_int(primitive)
+    elif isinstance(primitive, memoryview):
+        return big_endian_to_int(bytes(primitive))
+    elif isinstance(primitive, str):
+        raise TypeError("Pass in strings with keyword hexstr or text")
+    elif isinstance(primitive, (int, bool)):
+        return int(primitive)
+    else:
+        raise TypeError(
+            "Invalid type. Expected one of int/bool/str/bytes/bytearray. Got "
+            f"{type(primitive)}"
+        )
+
+
+def to_bytes(
+    primitive: Optional[BytesLike] = None,
+    hexstr: Optional[HexStr] = None,
+    text: Optional[str] = None,
+) -> bytes:
+    if isinstance(primitive, bool):
+        return b"\x01" if primitive else b"\x00"
+    elif isinstance(primitive, (bytearray, memoryview)):
+        return bytes(primitive)
+    elif isinstance(primitive, bytes):
+        return primitive
+    elif isinstance(primitive, int):
+        return to_bytes(hexstr=to_hex(primitive))
+    elif hexstr is not None:
+        if len(hexstr) % 2:
+            hexstr = "0x0" + remove_0x_prefix(hexstr)  # type: ignore [assignment]
+        return decode_hex(hexstr)
+    elif text is not None:
+        return text.encode("utf-8")
+    raise TypeError(
+        "expected a bool, int, byte or bytearray in first arg, "
+        "or keyword of hexstr or text"
+    )
+
+
+def to_text(
+    primitive: Optional[BytesLike] = None,
+    hexstr: Optional[HexStr] = None,
+    text: Optional[str] = None,
+) -> str:
+    if hexstr is not None:
+        return to_bytes(hexstr=hexstr).decode("utf-8")
+    elif text is not None:
+        return text
+    elif isinstance(primitive, str):
+        return to_text(hexstr=primitive)
+    elif isinstance(primitive, (bytes, bytearray)):
+        return primitive.decode("utf-8")
+    elif isinstance(primitive, memoryview):
+        return bytes(primitive).decode("utf-8")
+    elif isinstance(primitive, int):
+        byte_encoding = int_to_big_endian(primitive)
+        return to_text(byte_encoding)
+    raise TypeError("Expected an int, bytes, bytearray or hexstr.")
+
+
+def text_if_str(
+    to_type: Callable[..., T], text_or_primitive: Union[bytes, int, str]
+) -> T:
+    """
+    Convert to a type, assuming that strings can be only unicode text (not a hexstr).
+
+    :param to_type function: takes the arguments (primitive, hexstr=hexstr, text=text),
+        eg~ to_bytes, to_text, to_hex, to_int, etc
+    :param text_or_primitive bytes, str, int: value to convert
+    """
+    if isinstance(text_or_primitive, str):
+        return to_type(text=text_or_primitive)
+    else:
+        return to_type(text_or_primitive)
+
+
+def hexstr_if_str(
+    to_type: Callable[..., T], hexstr_or_primitive: Union[bytes, int, str]
+) -> T:
+    """
+    Convert to a type, assuming that strings can be only hexstr (not unicode text).
+
+    :param to_type function: takes the arguments (primitive, hexstr=hexstr, text=text),
+        eg~ to_bytes, to_text, to_hex, to_int, etc
+    :param hexstr_or_primitive bytes, str, int: value to convert
+    """
+    if isinstance(hexstr_or_primitive, str):
+        if remove_0x_prefix(HexStr(hexstr_or_primitive)) and not is_hexstr(
+            hexstr_or_primitive
+        ):
+            raise ValueError(
+                "when sending a str, it must be a hex string. "
+                f"Got: {repr(hexstr_or_primitive)}"
+            )
+        return to_type(hexstr=hexstr_or_primitive)
+    else:
+        return to_type(hexstr_or_primitive)

faster_eth_utils/crypto.py

@@ -0,0 +1,21 @@
+from typing import (
+    Optional,
+    Union,
+)
+
+from eth_hash.auto import (
+    keccak as keccak_256,
+)
+from eth_typing import HexStr
+
+from .conversions import (
+    to_bytes,
+)
+
+
+def keccak(
+    primitive: Optional[Union[bytes, int, bool]] = None,
+    hexstr: Optional[HexStr] = None,
+    text: Optional[str] = None,
+) -> bytes:
+    return bytes(keccak_256(to_bytes(primitive, hexstr, text)))