faster-eth-utils 5.3.22__cp312-cp312-musllinux_1_2_x86_64.whl

faster_eth_utils/address.py

@@ -0,0 +1,138 @@
+import re
+from typing import (
+    Any,
+    Final,
+    TypeGuard,
+)
+
+import cchecksum
+from eth_typing import (
+    Address,
+    AnyAddress,
+    ChecksumAddress,
+    HexAddress,
+    HexStr,
+)
+
+from .conversions import (
+    hexstr_if_str,
+    to_hex,
+)
+from .hexadecimal import (
+    decode_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: 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: 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: AnyAddress | str | bytes, right: 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")
+    if left == right:
+        return True
+    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,196 @@
+from collections.abc import Callable, Generator, Mapping, Sequence
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeGuard,
+    TypeVar,
+    cast,
+    overload,
+)
+
+import warnings
+
+from .decorators import (
+    return_arg_type,
+)
+from .pydantic import (
+    CamelModel,
+)
+from .toolz import (
+    compose,
+    curry,
+)
+
+if TYPE_CHECKING:
+    from _typeshed import SupportsBool
+    # We have to sacrifice a little bit of specificity on dinosaur Python3.8
+
+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[TArg | TOther],
+) -> Generator[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,
+) -> TArg | TReturn: ...
+
+
+@overload
+def apply_formatter_if(
+    condition: Callable[[TArg], bool], formatter: Callable[[TArg], TReturn], value: TArg
+) -> TArg | TReturn: ...
+
+
+def apply_formatter_if(  # type: ignore [misc]
+    condition: Callable[[TArg], TypeGuard[TOther]] | Callable[[TArg], bool],
+    formatter: Callable[[TOther], TReturn] | Callable[[TArg], TReturn],
+    value: TArg,
+) -> 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: 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,189 @@
+from typing import (
+    TypeVar,
+    Union,
+)
+from collections.abc import Callable
+
+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: BytesLike | None = None,
+    hexstr: HexStr | None = None,
+    text: str | None = 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: BytesLike | None = None,
+    hexstr: HexStr | None = None,
+    text: str | None = 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: BytesLike | None = None,
+    hexstr: HexStr | None = None,
+    text: str | None = 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 int_to_big_endian(primitive)
+    elif hexstr is not None:
+        if len(hexstr) % 2:
+            hexstr = HexStr(f"0x0{remove_0x_prefix(hexstr)}")
+        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: BytesLike | None = None,
+    hexstr: HexStr | None = None,
+    text: str | None = 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):
+        return int_to_big_endian(primitive).decode("utf-8")
+    raise TypeError("Expected an int, bytes, bytearray or hexstr.")
+
+
+def text_if_str(
+    to_type: Callable[..., T], text_or_primitive: 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: 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,16 @@
+from eth_hash.auto import (
+    keccak as keccak_256,
+)
+from eth_typing import HexStr
+
+from .conversions import (
+    to_bytes,
+)
+
+
+def keccak(
+    primitive: bytes | int | bool | None = None,
+    hexstr: HexStr | None = None,
+    text: str | None = None,
+) -> bytes:
+    return bytes(keccak_256(to_bytes(primitive, hexstr, text)))

faster_eth_utils/currency.py

@@ -0,0 +1,144 @@
+import decimal
+from decimal import (
+    localcontext,
+)
+from typing import (
+    Final,
+    Union,
+    final,
+)
+
+from .types import (
+    is_integer,
+    is_string,
+)
+from .units import (
+    units,
+)
+
+
+@final
+class denoms:
+    wei: Final = int(units["wei"])
+    kwei: Final = int(units["kwei"])
+    babbage: Final = int(units["babbage"])
+    femtoether: Final = int(units["femtoether"])
+    mwei: Final = int(units["mwei"])
+    lovelace: Final = int(units["lovelace"])
+    picoether: Final = int(units["picoether"])
+    gwei: Final = int(units["gwei"])
+    shannon: Final = int(units["shannon"])
+    nanoether: Final = int(units["nanoether"])
+    nano: Final = int(units["nano"])
+    szabo: Final = int(units["szabo"])
+    microether: Final = int(units["microether"])
+    micro: Final = int(units["micro"])
+    finney: Final = int(units["finney"])
+    milliether: Final = int(units["milliether"])
+    milli: Final = int(units["milli"])
+    ether: Final = int(units["ether"])
+    kether: Final = int(units["kether"])
+    grand: Final = int(units["grand"])
+    mether: Final = int(units["mether"])
+    gether: Final = int(units["gether"])
+    tether: Final = int(units["tether"])
+
+
+MIN_WEI: Final = 0
+MAX_WEI: Final = 2**256 - 1
+DECIMAL_ZERO: Final = decimal.Decimal(0)
+
+_NumberType = Union[int, float, str, decimal.Decimal]
+
+
+def _from_wei(number: int, unit_value: decimal.Decimal) -> int | decimal.Decimal:
+    if number == 0:
+        return 0
+
+    if number < MIN_WEI or number > MAX_WEI:
+        raise ValueError("value must be between 0 and 2**256 - 1")
+
+    with localcontext() as ctx:
+        ctx.prec = 999
+        d_number = decimal.Decimal(value=number, context=ctx)
+        result_value = d_number / unit_value
+
+    return result_value
+
+
+def _to_wei(number: _NumberType, unit_value: decimal.Decimal) -> int:
+    if is_integer(number) or is_string(number):
+        d_number = decimal.Decimal(value=number)  # type: ignore [arg-type]
+    elif isinstance(number, float):
+        d_number = decimal.Decimal(value=str(number))
+    elif isinstance(number, decimal.Decimal):
+        d_number = number
+    else:
+        raise TypeError("Unsupported type. Must be one of integer, float, or string")
+
+    if d_number == DECIMAL_ZERO:
+        return 0
+
+    s_number = str(number)
+
+    if d_number < 1 and "." in s_number:
+        with localcontext() as ctx:
+            multiplier = len(s_number) - s_number.index(".") - 1
+            ctx.prec = multiplier
+            d_number = decimal.Decimal(value=number, context=ctx) * 10**multiplier  # type: ignore [arg-type]
+        unit_value /= 10**multiplier
+
+    with localcontext() as ctx:
+        ctx.prec = 999
+        result_value = decimal.Decimal(value=d_number, context=ctx) * unit_value
+
+    if result_value < MIN_WEI or result_value > MAX_WEI:
+        raise ValueError("Resulting wei value must be between 0 and 2**256 - 1")
+
+    return int(result_value)
+
+
+def from_wei(number: int, unit: str) -> int | decimal.Decimal:
+    """
+    Takes a number of wei and converts it to any other ether unit.
+    """
+    unit_key = unit.lower()
+    if unit_key not in units:
+        raise ValueError(f"Unknown unit. Must be one of {'/'.join(units.keys())}")
+
+    unit_value = units[unit_key]
+
+    return _from_wei(number, unit_value)
+
+
+def to_wei(number: _NumberType, unit: str) -> int:
+    """
+    Takes a number of a unit and converts it to wei.
+    """
+    unit_key = unit.lower()
+    if unit_key not in units:
+        raise ValueError(f"Unknown unit. Must be one of {'/'.join(units.keys())}")
+
+    unit_value = units[unit_key]
+
+    return _to_wei(number, unit_value)
+
+
+def from_wei_decimals(number: int, decimals: int) -> int | decimal.Decimal:
+    """
+    Takes a number of wei and converts it to a decimal with the specified
+    number of decimals.
+    """
+    unit_value = decimal.Decimal(10) ** decimal.Decimal(value=decimals)
+
+    return _from_wei(number, unit_value)
+
+
+def to_wei_decimals(number: _NumberType, decimals: int) -> int:
+    """
+    Takes a number of a unit and converts it to wei with the specified
+    number of decimals.
+    """
+    unit_value = decimal.Decimal(10) ** decimal.Decimal(value=decimals)
+
+    return _to_wei(number, unit_value)