faster-eth-utils 5.3.21__cp310-cp310-musllinux_1_2_x86_64.whl

faster_eth_utils/humanize.py

@@ -0,0 +1,201 @@
+from collections.abc import (
+    Iterable,
+    Iterator,
+)
+from typing import (
+    Any,
+    Final,
+)
+from urllib import (
+    parse,
+)
+
+from eth_typing import (
+    URI,
+    Hash32,
+)
+
+from faster_eth_utils.currency import (
+    denoms,
+    from_wei,
+)
+
+from . import toolz
+
+
+def humanize_seconds(seconds: float | int) -> str:
+    seconds_int = int(seconds)
+    if seconds_int == 0:
+        return "0s"
+
+    unit_values = _consume_leading_zero_units(_humanize_seconds(seconds_int))
+
+    return "".join(f"{amount}{unit}" for amount, unit in toolz.take(3, unit_values))
+
+
+SECOND: Final = 1
+MINUTE: Final = 60
+HOUR: Final = 60 * 60
+DAY: Final = 24 * HOUR
+YEAR: Final = 365 * DAY
+MONTH: Final = YEAR // 12
+WEEK: Final = 7 * DAY
+
+
+UNITS: Final = (
+    (YEAR, "y"),
+    (MONTH, "m"),
+    (WEEK, "w"),
+    (DAY, "d"),
+    (HOUR, "h"),
+    (MINUTE, "m"),
+    (SECOND, "s"),
+)
+
+
+def _consume_leading_zero_units(
+    units_iter: Iterator[tuple[int, str]]
+) -> Iterator[tuple[int, str]]:
+    for amount, unit in units_iter:
+        if amount == 0:
+            continue
+        else:
+            yield (amount, unit)
+            break
+
+    yield from units_iter
+
+
+def _humanize_seconds(seconds: int) -> Iterator[tuple[int, str]]:
+    remainder = seconds
+
+    for duration, unit in UNITS:
+        if not remainder:
+            break
+
+        num = remainder // duration
+        yield num, unit
+
+        remainder %= duration
+
+
+DISPLAY_HASH_CHARS: Final = 4
+
+
+def humanize_bytes(value: bytes) -> str:
+    if len(value) <= DISPLAY_HASH_CHARS + 1:
+        return value.hex()
+    value_as_hex = value.hex()
+    head = value_as_hex[:DISPLAY_HASH_CHARS]
+    tail = value_as_hex[-1 * DISPLAY_HASH_CHARS :]
+    return f"{head}..{tail}"
+
+
+def humanize_hexstr(value: str) -> str:
+    tail = value[-1 * DISPLAY_HASH_CHARS :]
+
+    if value[:2] == "0x":
+        if len(value[2:]) <= DISPLAY_HASH_CHARS * 2:
+            return value
+        head = value[2 : DISPLAY_HASH_CHARS + 2]
+        return f"0x{head}..{tail}"
+    else:
+        if len(value) <= DISPLAY_HASH_CHARS * 2:
+            return value
+        head = value[:DISPLAY_HASH_CHARS]
+        return f"{head}..{tail}"
+
+
+def humanize_hash(value: Hash32) -> str:
+    return humanize_bytes(value)
+
+
+def humanize_ipfs_uri(uri: URI) -> str:
+    if not is_ipfs_uri(uri):
+        raise TypeError(
+            f"{uri} does not look like a valid IPFS uri. Currently, "
+            "only CIDv0 hash schemes are supported."
+        )
+
+    parsed = parse.urlparse(uri)
+    ipfs_hash = parsed.netloc
+    head = ipfs_hash[:DISPLAY_HASH_CHARS]
+    tail = ipfs_hash[-1 * DISPLAY_HASH_CHARS :]
+    return f"ipfs://{head}..{tail}"
+
+
+def is_ipfs_uri(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+
+    parsed = parse.urlparse(value)
+    if parsed.scheme != "ipfs" or not parsed.netloc:
+        return False
+
+    return _is_CIDv0_ipfs_hash(parsed.netloc)
+
+
+def _is_CIDv0_ipfs_hash(ipfs_hash: str) -> bool:
+    if ipfs_hash.startswith("Qm") and len(ipfs_hash) == 46:
+        return True
+    return False
+
+
+def _find_breakpoints(values: tuple[int, ...]) -> Iterator[int]:
+    yield 0
+    for index, (left, right) in enumerate(toolz.sliding_window(2, values), 1):
+        if left + 1 == right:
+            continue
+        else:
+            yield index
+    yield len(values)
+
+
+def _extract_integer_ranges(values: tuple[int, ...]) -> Iterator[tuple[int, int]]:
+    """
+    Return a tuple of consecutive ranges of integers.
+
+    :param values: a sequence of ordered integers
+
+    - fn(1, 2, 3) -> ((1, 3),)
+    - fn(1, 2, 3, 7, 8, 9) -> ((1, 3), (7, 9))
+    - fn(1, 7, 8, 9) -> ((1, 1), (7, 9))
+    """
+    for left, right in toolz.sliding_window(2, _find_breakpoints(values)):
+        chunk = values[left:right]
+        yield chunk[0], chunk[-1]
+
+
+def _humanize_range(bounds: tuple[int, int]) -> str:
+    left, right = bounds
+    if left == right:
+        return str(left)
+    else:
+        return f"{left}-{right}"
+
+
+def humanize_integer_sequence(values_iter: Iterable[int]) -> str:
+    """
+    Return a concise, human-readable string representing a sequence of integers.
+
+    - fn((1, 2, 3)) -> '1-3'
+    - fn((1, 2, 3, 7, 8, 9)) -> '1-3|7-9'
+    - fn((1, 2, 3, 5, 7, 8, 9)) -> '1-3|5|7-9'
+    - fn((1, 7, 8, 9)) -> '1|7-9'
+    """
+    values = tuple(values_iter)
+    if not values:
+        return "(empty)"
+    else:
+        return "|".join(_humanize_range(range) for range in _extract_integer_ranges(values))
+
+
+def humanize_wei(number: int) -> str:
+    if number >= denoms.finney:
+        unit = "ether"
+    elif number >= denoms.mwei:
+        unit = "gwei"
+    else:
+        unit = "wei"
+    amount = from_wei(number, unit)
+    return f"{str(amount)} {unit}"

faster_eth_utils/logging.py

@@ -0,0 +1,152 @@
+import logging
+from collections.abc import (
+    Iterator,
+)
+from contextlib import (
+    contextmanager,
+)
+from functools import (
+    cached_property,
+)
+from typing import (
+    Any,
+    Final,
+    TypeVar,
+    cast,
+    overload,
+)
+
+from .toolz import (
+    assoc,
+)
+
+DEBUG2_LEVEL_NUM = 8
+
+TLogger = TypeVar("TLogger", bound=logging.Logger)
+
+Logger: Final = logging.Logger
+getLogger: Final = logging.getLogger
+getLoggerClass: Final = logging.getLoggerClass
+setLoggerClass: Final = logging.setLoggerClass
+
+
+class ExtendedDebugLogger(logging.Logger):
+    """
+    Logging class that can be used for lower level debug logging.
+    """
+
+    @cached_property
+    def show_debug2(self) -> bool:
+        return self.isEnabledFor(DEBUG2_LEVEL_NUM)
+
+    def debug2(self, message: str, *args: Any, **kwargs: Any) -> None:
+        if self.show_debug2:
+            self.log(DEBUG2_LEVEL_NUM, message, *args, **kwargs)
+        else:
+            # When we find that `DEBUG2` isn't enabled we completely replace
+            # the `debug2` function in this instance of the logger with a noop
+            # lambda to further speed up
+            self.__dict__["debug2"] = lambda message, *args, **kwargs: None
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # This is needed because our parent's implementation could
+        # cause us to become a regular Logger on unpickling.
+        return get_extended_debug_logger, (self.name,)
+
+
+def setup_DEBUG2_logging() -> None:
+    """
+    Installs the `DEBUG2` level logging levels to the main logging module.
+    """
+    if not hasattr(logging, "DEBUG2"):
+        logging.addLevelName(DEBUG2_LEVEL_NUM, "DEBUG2")
+        logging.DEBUG2 = DEBUG2_LEVEL_NUM  # type: ignore [attr-defined]
+
+@contextmanager
+def _use_logger_class(logger_class: type[logging.Logger]) -> Iterator[None]:
+    original_logger_class = getLoggerClass()
+    setLoggerClass(logger_class)
+    try:
+        yield
+    finally:
+        setLoggerClass(original_logger_class)
+
+
+@overload
+def get_logger(name: str, logger_class: type[TLogger]) -> TLogger: ...
+@overload
+def get_logger(name: str, logger_class: None = None) -> logging.Logger: ...
+def get_logger(name: str, logger_class: type[TLogger] | None = None) -> TLogger | logging.Logger:
+    if logger_class is None:
+        return getLogger(name)
+
+    with _use_logger_class(logger_class):
+        # The logging module caches logger instances. The following code
+        # ensures that if there is a cached instance that we don't
+        # accidentally return the incorrect logger type because the logging
+        # module does not *update* the cached instance in the event that
+        # the global logging class changes.
+        manager = Logger.manager
+        logger_dict = manager.loggerDict
+        cached_logger = logger_dict.get(name)
+        if cached_logger is not None and type(cached_logger) is not logger_class:
+            del logger_dict[name]
+        return cast(TLogger, getLogger(name))
+
+
+def get_extended_debug_logger(name: str) -> ExtendedDebugLogger:
+    return get_logger(name, ExtendedDebugLogger)
+
+
+THasLoggerMeta = TypeVar("THasLoggerMeta", bound="HasLoggerMeta")
+
+
+class HasLoggerMeta(type):
+    """
+    Assigns a logger instance to a class, derived from the import path and name.
+
+    This metaclass uses `__qualname__` to identify a unique and meaningful name
+    to use when creating the associated logger for a given class.
+    """
+
+    logger_class = Logger
+
+    def __new__(
+        mcls: type[THasLoggerMeta],
+        name: str,
+        bases: tuple[type[Any]],
+        namespace: dict[str, Any],
+    ) -> THasLoggerMeta:
+        if "logger" in namespace:
+            # If a logger was explicitly declared we shouldn't do anything to
+            # replace it.
+            return super().__new__(mcls, name, bases, namespace)
+        if "__qualname__" not in namespace:
+            raise AttributeError("Missing __qualname__")
+    
+        logger = get_logger(namespace["__qualname__"], mcls.logger_class)
+
+        return super().__new__(mcls, name, bases, assoc(namespace, "logger", logger))
+
+    @classmethod
+    def replace_logger_class(
+        mcls: type[THasLoggerMeta], value: type[logging.Logger]
+    ) -> type[THasLoggerMeta]:
+        return type(mcls.__name__, (mcls,), {"logger_class": value})
+
+    @classmethod
+    def meta_compat(
+        mcls: type[THasLoggerMeta], other: type[type]
+    ) -> type[THasLoggerMeta]:
+        return type(mcls.__name__, (mcls, other), {})
+
+
+class HasLogger(metaclass=HasLoggerMeta):
+    logger: logging.Logger
+
+
+HasExtendedDebugLoggerMeta = HasLoggerMeta.replace_logger_class(ExtendedDebugLogger)
+
+
+class HasExtendedDebugLogger(metaclass=HasExtendedDebugLoggerMeta):  # type: ignore[metaclass]
+    logger: ExtendedDebugLogger

faster_eth_utils/module_loading.py

@@ -0,0 +1,31 @@
+from importlib import (
+    import_module,
+)
+from typing import (
+    Any,
+)
+
+
+def import_string(dotted_path: str) -> Any:
+    """
+    Import a variable using its path and name.
+
+    :param dotted_path: dotted module path and variable/class name
+    :return: the attribute/class designated by the last name in the path
+    :raise: ImportError, if the import failed
+
+    Source: django.utils.module_loading
+    """
+    try:
+        module_path, class_name = dotted_path.rsplit(".", 1)
+    except ValueError:
+        msg = f"{dotted_path} doesn't look like a module path"
+        raise ImportError(msg)
+
+    module = import_module(module_path)
+
+    try:
+        return getattr(module, class_name)
+    except AttributeError:
+        msg = f'Module "{module_path}" does not define a "{class_name}" attribute/class'
+        raise ImportError(msg)

faster_eth_utils/network.py

@@ -0,0 +1,91 @@
+from dataclasses import (
+    dataclass,
+)
+import json
+import os
+import sys
+from pathlib import (
+    Path,
+)
+from typing import (
+    Final,
+)
+
+from eth_typing import (
+    ChainId,
+)
+
+from faster_eth_utils.exceptions import (
+    ValidationError,
+)
+
+
+FASTER_ETH_UTILS_FOLDER: Final = Path(sys.modules["faster_eth_utils"].__file__).parent  # type: ignore [arg-type]
+
+
+@dataclass
+class Network:
+    chain_id: int
+    name: str
+    shortName: str
+    symbol: ChainId
+
+
+def initialize_network_objects() -> list[Network]:
+    networks_obj = []
+
+    networks_json_path = os.path.abspath(
+        os.path.join(str(FASTER_ETH_UTILS_FOLDER), "__json")
+    )
+    with open(
+        os.path.join(networks_json_path, "eth_networks.json"),
+        encoding="UTF-8",
+    ) as open_file:
+        network_data = json.load(open_file)
+
+    for entry in network_data:
+        try:
+            network = Network(
+                chain_id=entry["chainId"],
+                name=entry["name"],
+                shortName=entry["shortName"],
+                symbol=ChainId(entry["chainId"]),
+            )
+            networks_obj.append(network)
+        except ValueError:
+            # Chain does not have a valid ChainId, network files in eth-utils and
+            # eth-typing should to be updated. Run `python update_networks.py` in the
+            # project root.
+            pass
+
+    return networks_obj
+
+
+networks = initialize_network_objects()
+
+networks_by_id = {network.chain_id: network for network in networks}
+network_names_by_id = {network.chain_id: network.name for network in networks}
+network_short_names_by_id = {
+    network.chain_id: network.shortName for network in networks
+}
+
+
+def network_from_chain_id(chain_id: int) -> Network:
+    try:
+        return networks_by_id[chain_id]
+    except KeyError:
+        raise ValidationError(f"chain_id is not recognized: {chain_id}")
+
+
+def name_from_chain_id(chain_id: int) -> str:
+    try:
+        return network_names_by_id[chain_id]
+    except KeyError:
+        raise ValidationError(f"chain_id is not recognized: {chain_id}")
+
+
+def short_name_from_chain_id(chain_id: int) -> str:
+    try:
+        return network_short_names_by_id[chain_id]
+    except KeyError:
+        raise ValidationError(f"chain_id is not recognized: {chain_id}")

faster_eth_utils/numeric.py

@@ -0,0 +1,43 @@
+from abc import (
+    ABC,
+    abstractmethod,
+)
+import decimal
+import numbers
+from typing import (
+    Any,
+    TypeVar,
+    Union,
+)
+
+
+class Comparable(ABC):
+    @abstractmethod
+    def __lt__(self, other: Any) -> bool:
+        ...
+
+    @abstractmethod
+    def __gt__(self, other: Any) -> bool:
+        ...
+
+
+TComparable = Union[Comparable, numbers.Real, int, float, decimal.Decimal]
+
+
+TValue = TypeVar("TValue", bound=TComparable)
+
+
+def clamp(lower_bound: TValue, upper_bound: TValue, value: TValue) -> TValue:
+    # The `mypy` ignore statements here are due to doing a comparison of
+    # `Union` types which isn't allowed. (per cburgdorf). This approach was
+    # chosen over using `typing.overload` to define multiple signatures for
+    # each comparison type here since the added value of "proper" typing
+    # doesn't seem to justify the complexity of having a bunch of different
+    # signatures defined. The external library perspective on this function
+    # should still be adequate under this approach
+    if value < lower_bound:  # type: ignore
+        return lower_bound
+    elif value > upper_bound:  # type: ignore
+        return upper_bound
+    else:
+        return value

faster_eth_utils/pydantic.py

@@ -0,0 +1,103 @@
+from typing import (
+    Any,
+    cast,
+)
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+)
+from pydantic._internal._core_utils import (
+    CoreSchemaField,
+)
+from pydantic.alias_generators import (
+    to_camel,
+)
+from pydantic.json_schema import (
+    DEFAULT_REF_TEMPLATE,
+    GenerateJsonSchema,
+    JsonSchemaMode,
+)
+
+
+class OmitJsonSchema(GenerateJsonSchema):  # type: ignore[misc]
+    """
+    Custom JSON schema generator that omits the schema generation for fields that are
+    invalid. Excluded fields (``Field(exclude=True)``) are generally useful as
+    properties of the model but are not meant to be serialized to JSON.
+    """
+
+    def field_is_present(self, field: CoreSchemaField) -> bool:
+        # override ``field_is_present`` and omit excluded fields from the schema
+        if field.get("serialization_exclude", False):
+            return False
+        return cast(bool, super().field_is_present(field))
+
+
+class CamelModel(BaseModel):  # type: ignore[misc]
+    """
+    Camel-case pydantic model. This model is used to ensure serialization in a
+    consistent manner, aliasing as camelCase serialization. This is useful for models
+    that are used in JSON-RPC requests and responses, marking useful fields for the
+    model, but that are not part of the JSON-RPC object, with ``Field(exclude=True)``.
+    To serialize a model to the expected JSON-RPC format, or camelCase, use
+    ``model_dump(by_alias=True)``.
+
+    .. code-block:: python
+
+        >>> from eth_utils.pydantic import CamelModel
+        >>> from pydantic import Field
+
+        >>> class SignedSetCodeAuthorization(CamelModel):
+        ...     chain_id: int
+        ...     address: bytes
+        ...     nonce: int
+        ...
+        ...     # useful fields for the object but excluded from serialization
+        ...     # (not part of the JSON-RPC object)
+        ...     authorization_hash: bytes = Field(exclude=True)
+        ...     signature: bytes = Field(exclude=True)
+
+        >>> auth = SignedSetCodeAuthorization(
+        ...     chain_id=1,
+        ...     address=b"0x0000000000000000000000000000000000000000",
+        ...     nonce=0,
+        ...     authorization_hash=generated_hash,
+        ...     signature=generated_signature,
+        ... )
+        >>> auth.model_dump(by_alias=True)
+        {'chainId': 1, 'address': '0x000000000000000000000000000000000000', 'nonce': 0}
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        # populate by snake_case (python) args
+        populate_by_name=True,
+        # serialize by camelCase (json-rpc) keys
+        alias_generator=to_camel,
+        # validate default values
+        validate_default=True,
+    )
+
+    @classmethod
+    def model_json_schema(  # type: ignore [override]
+        cls,
+        by_alias: bool = True,
+        ref_template: str = DEFAULT_REF_TEMPLATE,
+        # default to ``OmitJsonSchema`` to prevent errors from excluded fields
+        schema_generator: type[GenerateJsonSchema] = OmitJsonSchema,
+        mode: JsonSchemaMode = "validation",
+    ) -> dict[str, Any]:
+        """
+        Omits excluded fields from the JSON schema, preventing errors that would
+        otherwise be raised by the default schema generator.
+        """
+        return cast(
+            dict[str, Any],
+            super().model_json_schema(
+                by_alias=by_alias,
+                ref_template=ref_template,
+                schema_generator=schema_generator,
+                mode=mode,
+            ),
+        )