eth-portfolio 1.1.0__py3-none-any.whl

eth_portfolio/_decimal.py

@@ -0,0 +1,122 @@
+import decimal
+import logging
+from typing import Union
+
+from evmspec.data import Wei
+
+
+logger = logging.getLogger(__name__)
+
+
+class Decimal(decimal.Decimal):
+    """
+    A subclass of :class:`decimal.Decimal` with additional functionality for JSON serialization.
+
+    This class extends the :class:`decimal.Decimal` class to provide an additional
+    method for JSON serialization. It also overrides arithmetic operations to ensure
+    that the result is of type :class:`Decimal`.
+
+    See Also:
+        - :class:`decimal.Decimal`
+    """
+
+    def jsonify(self) -> Union[str, int]:
+        """
+        Converts the :class:`Decimal` to a JSON-friendly format.
+
+        This method attempts to represent the :class:`Decimal` in the most compact form
+        possible for JSON serialization. It returns an integer if the :class:`Decimal`
+        is exactly equal to an integer, otherwise it returns a string in either
+        standard or scientific notation, depending on which is shorter.
+
+        If the integer representation is exactly equal to the :class:`Decimal`,
+        the integer is returned. Otherwise, the method returns the shorter of the
+        standard string representation or the scientific notation.
+
+        Examples:
+            >>> Decimal('123.4500').jsonify()
+            '123.45'
+            >>> Decimal('123000').jsonify()
+            123000
+            >>> Decimal('0.000123').jsonify()
+            '1.23E-4'
+            >>> Decimal('1000000').jsonify()
+            1000000
+        """
+        string = str(self)
+        integer = int(self)
+
+        if integer == self:
+            scientific_notation = "%E" % self
+            return (
+                integer
+                if len(str(integer)) <= len(scientific_notation) + 2
+                else scientific_notation
+            )
+
+        if "E" in string:
+            return string
+
+        scientific_notation = "%E" % self
+        while string[-1] == "0":
+            string = string[:-1]
+
+        if type(self)(scientific_notation) == self and len(scientific_notation) < len(string):
+            return scientific_notation
+
+        return string
+
+    def __add__(self, other):
+        return type(self)(super().__add__(other))
+
+    def __radd__(self, other):
+        return type(self)(super().__radd__(other))
+
+    def __sub__(self, other):
+        return type(self)(super().__sub__(other))
+
+    def __rsub__(self, other):
+        return type(self)(super().__rsub__(other))
+
+    def __mul__(self, other):
+        return type(self)(super().__mul__(other))
+
+    def __rmul__(self, other):
+        return type(self)(super().__rmul__(other))
+
+    def __truediv__(self, other):
+        return type(self)(super().__truediv__(other))
+
+    def __rtruediv__(self, other):
+        return type(self)(super().__rtruediv__(other))
+
+    def __floordiv__(self, other):
+        return type(self)(super().__floordiv__(other))
+
+    def __rfloordiv__(self, other):
+        return type(self)(super().__rfloordiv__(other))
+
+
+class Gwei(Decimal):
+    """
+    A subclass of :class:`Decimal` representing Gwei values.
+
+    This class provides a property to convert Gwei to Wei.
+
+    See Also:
+        - :class:`Decimal`
+        - :class:`evmspec.data.Wei`
+    """
+
+    @property
+    def as_wei(self) -> Wei:
+        """
+        Converts the Gwei value to Wei.
+
+        This property multiplies the Gwei value by 10^9 to convert it to Wei.
+
+        Examples:
+            >>> Gwei('1').as_wei
+            Wei(1000000000)
+        """
+        return Wei(self * 10**9)

eth_portfolio/_decorators.py

@@ -0,0 +1,71 @@
+import asyncio
+import functools
+import inspect
+import logging
+from typing import Callable, Optional
+
+from brownie import chain
+from typing_extensions import Concatenate
+from y.datatypes import Block
+
+from eth_portfolio import _config
+from eth_portfolio._utils import get_buffered_chain_height
+from eth_portfolio.typing import _I, _P, _T
+
+logger = logging.getLogger(__name__)
+
+
+def set_end_block_if_none(
+    func: Callable[Concatenate[_I, Block, Block, _P], _T],
+) -> Callable[Concatenate[_I, Block, Optional[Block], _P], _T]:
+    """
+    Used to set `end_block` = `chain.height - _config.REORG_BUFFER` if `end_block` is None.
+    Only works with a class function that takes args (self, start_block, end_block, *args, **kwargs).
+    """
+    if inspect.isasyncgenfunction(func):
+
+        @functools.wraps(func)
+        async def wrap(
+            obj: _I,
+            start_block: Block,
+            end_block: Optional[Block],
+            *args: _P.args,
+            **kwargs: _P.kwargs,
+        ) -> _T:
+            if end_block is None:
+                end_block = await get_buffered_chain_height()
+                logger.debug("end_block not provided, using %s", end_block)
+            async for thing in func(obj, start_block, end_block, *args, **kwargs):
+                yield thing
+
+    elif asyncio.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def wrap(
+            obj: _I,
+            start_block: Block,
+            end_block: Block,
+            *args: _P.args,
+            **kwargs: _P.kwargs,
+        ) -> _T:
+            if end_block is None:
+                end_block = await get_buffered_chain_height()
+                logger.debug("end_block not provided, using %s", end_block)
+            return await func(obj, start_block, end_block, *args, **kwargs)
+
+    else:
+
+        @functools.wraps(func)
+        def wrap(
+            obj: _I,
+            start_block: Block,
+            end_block: Block,
+            *args: _P.args,
+            **kwargs: _P.kwargs,
+        ) -> _T:
+            if end_block is None:
+                end_block = chain.height - _config.REORG_BUFFER
+                logger.debug("end_block not provided, using %s", end_block)
+            return func(obj, start_block, end_block, *args, **kwargs)
+
+    return wrap

eth_portfolio/_exceptions.py

@@ -0,0 +1,67 @@
+from asyncio import gather
+from typing import TYPE_CHECKING
+
+from y.datatypes import Block
+
+if TYPE_CHECKING:
+    from eth_portfolio._ledgers.address import AddressLedgerBase
+
+
+class BlockRangeIsCached(Exception):
+    """
+    Exception raised when a block range is already cached.
+
+    This exception indicates that the requested block range
+    has already been loaded into memory and does not need to be fetched again.
+
+    Examples:
+        >>> raise BlockRangeIsCached("Block range is already cached.")
+    """
+
+    pass
+
+
+class BlockRangeOutOfBounds(Exception):
+    """
+    Exception raised when a block range is out of bounds.
+
+    This exception indicates that the requested block range
+    is outside the bounds of the cached data. It provides a method to
+    handle the loading of the remaining ledger entries that are out of bounds
+    by invoking the appropriate method in the associated ledger.
+
+    Args:
+        start_block: The starting block number of the out-of-bounds range.
+        end_block: The ending block number of the out-of-bounds range.
+        ledger: The ledger associated with the block range.
+
+    Examples:
+        >>> raise BlockRangeOutOfBounds(100, 200, ledger)
+
+    See Also:
+        - :class:`~eth_portfolio._ledgers.address.AddressLedgerBase`: The base class for address ledgers.
+    """
+
+    def __init__(self, start_block: Block, end_block: Block, ledger: "AddressLedgerBase") -> None:
+        self.ledger = ledger
+        self.start_block = start_block
+        self.end_block = end_block
+
+    async def load_remaining(self) -> None:
+        """
+        Asynchronously handles the loading of the remaining ledger entries that are out of bounds.
+
+        This method invokes the :meth:`~eth_portfolio._ledgers.address.AddressLedgerBase._load_new_objects`
+        method of the associated ledger to fetch the ledger entries for the blocks that are outside
+        the cached range, ensuring that the entire requested block range is covered.
+
+        Examples:
+            >>> await exception.load_remaining()
+
+        See Also:
+            - :meth:`~eth_portfolio._ledgers.address.AddressLedgerBase._load_new_objects`: Method to load new ledger entries.
+        """
+        return await gather(
+            self.ledger._load_new_objects(self.start_block, self.ledger.cached_thru - 1),
+            self.ledger._load_new_objects(self.ledger.cached_from + 1, self.end_block),
+        )