"""
This module defines a set of classes to represent and manipulate various levels of balance structures
within an Ethereum portfolio. The focus of these classes is on reading, aggregating, and summarizing
balances, including the value in both tokens and their equivalent in USD.
The main classes and their purposes are as follows:
- :class:`~eth_portfolio.typing.Balance`: Represents the balance of a single token, including its token amount and equivalent USD value.
- :class:`~eth_portfolio.typing.TokenBalances`: Manages a collection of :class:`~eth_portfolio.typing.Balance` objects for multiple tokens, providing operations
such as summing balances across tokens.
- :class:`~eth_portfolio.typing.RemoteTokenBalances`: Extends :class:`~eth_portfolio.typing.TokenBalances` to manage balances across different protocols, enabling
aggregation and analysis of balances by protocol.
- :class:`~eth_portfolio.typing.WalletBalances`: Organizes token balances into categories such as assets, debts, and external balances
for a single wallet. It combines :class:`~eth_portfolio.typing.TokenBalances` and :class:`~eth_portfolio.typing.RemoteTokenBalances` to provide a complete view
of a wallet's balances.
- :class:`~eth_portfolio.typing.PortfolioBalances`: Aggregates :class:`~eth_portfolio.typing.WalletBalances` for multiple wallets, providing operations to sum
balances across an entire portfolio.
- :class:`~eth_portfolio.typing.WalletBalancesRaw`: Similar to :class:`~eth_portfolio.typing.WalletBalances`, but with a key structure optimized for accessing
balances directly by wallet and token.
- :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`: Provides an inverted view of :class:`~eth_portfolio.typing.PortfolioBalances`, allowing access
by category first, then by wallet and token.
These classes are designed for efficient parsing, manipulation, and summarization of portfolio data,
without managing or altering any underlying assets.
"""
from functools import cached_property
from typing import (
Any,
Callable,
DefaultDict,
Dict,
Final,
Iterable,
List,
Literal,
Optional,
Tuple,
TypedDict,
TypeVar,
Union,
final,
)
from checksum_dict import DefaultChecksumDict
from eth_typing import BlockNumber
from pandas import DataFrame, concat
from typing_extensions import ParamSpec, Self
from y import ERC20
from y.datatypes import Address
from eth_portfolio._decimal import Decimal
from eth_portfolio.typing.balance.single import Balance
_T = TypeVar("_T")
_I = TypeVar("_I")
_P = ParamSpec("_P")
Fn = Callable[_P, _T]
ProtocolLabel = str
Addresses = Union[Address, Iterable[Address]]
TokenAddress = TypeVar("TokenAddress", bound=Address)
[docs]
class _SummableNonNumericMixin:
"""
Mixin class for non-numeric summable objects.
This class provides an interface for objects that can be used with `sum` but are not necessarily numeric.
"""
def __add__(self, other: Self) -> Self:
"""
Abstract method for adding two objects of the same type.
Args:
other: Another object of the same type.
Raises:
NotImplementedError: If no `__add__` method was defined on the subclass.
Returns:
A new object representing the sum.
"""
raise NotImplementedError
def __radd__(self, other: Union[Self, Literal[0]]) -> Self:
"""
Supports the addition operation from the right side to enable use of `sum`.
Args:
other: Another object of the same type or zero.
Returns:
A new object representing the sum.
Example:
>>> class Summable(_SummableNonNumeric):
... def __init__(self, value: int):
... self.value = value
... def __add__(self, other):
... return Summable(self.value + other.value)
... def __radd__(self, other):
... return self.__add__(other)
>>> a = Summable(10)
>>> b = Summable(20)
>>> sum_result = a + b
>>> sum_result.value
30
"""
return self if other == 0 else self.__add__(other) # type: ignore
_TBSeed = Union[Dict[Address, Balance], Iterable[Tuple[Address, Balance]]]
[docs]
@final
class TokenBalances(DefaultChecksumDict[Balance], _SummableNonNumericMixin): # type: ignore [misc]
"""
A specialized defaultdict subclass made for holding a mapping of ``token -> balance``.
Manages a collection of :class:`~eth_portfolio.typing.Balance` objects for multiple tokens, allowing for operations
such as summing balances across tokens.
The class uses token addresses as keys and :class:`~eth_portfolio.typing.Balance` objects as values. It supports
arithmetic operations like addition and subtraction of token balances.
Token addresses are checksummed automatically when adding items to the dict, and the default value for a token not present is an empty :class:`~eth_portfolio.typing.Balance` object.
Args:
seed: An initial seed of token balances, either as a dictionary or an iterable of tuples.
Example:
>>> token_balances = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> token_balances['0x123'].balance
Decimal('100')
"""
[docs]
def __init__(
self, seed: Optional[_TBSeed] = None, *, block: Optional[BlockNumber] = None
) -> None:
super().__init__(Balance)
self.block: Final = block
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items()
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for TokenBalances")
for token, balance in seed: # type: ignore [misc]
try:
self[token] += balance
except AttributeError:
if not isinstance(token, (ERC20, Contract)):
raise
self[token.address] += balance
[docs]
def __getitem__(self, key) -> Balance:
return super().__getitem__(key) if key in self else Balance(token=key, block=self.block)
def __setitem__(self, key, value):
"""
Sets the balance for a given token address.
Args:
key: The token address.
value: The balance to set for the token.
Raises:
TypeError: If the value is not a :class:`~eth_portfolio.typing.Balance` object.
Example:
>>> token_balances = TokenBalances()
>>> token_balances['0x123'] = Balance(Decimal('100'), Decimal('2000'))
>>> token_balances['0x123'].balance
Decimal('100')
"""
if not isinstance(value, Balance):
raise TypeError(f"value must be a `Balance` object. You passed {value}") from None
return super().__setitem__(key, value)
@property
def dataframe(self) -> DataFrame:
"""
Converts the token balances into a pandas DataFrame.
Returns:
A DataFrame representation of the token balances.
"""
df = DataFrame(
{
token: {"balance": balance.balance, "usd_value": balance.usd_value}
for token, balance in dict.items(self)
}
).T
df.reset_index(inplace=True)
df.rename(columns={"index": "token"}, inplace=True)
return df
[docs]
def sum_usd(self) -> Decimal:
"""
Sums the USD values of all token balances.
Returns:
The total USD value of all token balances.
Example:
>>> token_balances = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> total_usd = token_balances.sum_usd()
>>> total_usd
Decimal('2000')
"""
return Decimal(sum(balance.usd for balance in dict.values(self)))
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.TokenBalances` object.
Returns:
True if any token has a non-zero balance, otherwise False.
Example:
>>> token_balances = TokenBalances()
>>> bool(token_balances)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.TokenBalances` object.
Returns:
The string representation of the token balances.
"""
return f"TokenBalances{dict(self)}"
def __add__(self, other: "TokenBalances") -> "TokenBalances":
"""
Adds another :class:`~eth_portfolio.typing.TokenBalances` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.TokenBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.TokenBalances` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.TokenBalances`.
Example:
>>> tb1 = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> tb2 = TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})
>>> combined_tb = tb1 + tb2
>>> combined_tb['0x123'].balance
Decimal('150')
"""
if not isinstance(other, TokenBalances):
raise TypeError(f"{other} is not a TokenBalances object")
block = self.block
if block != other.block:
raise ValueError(
f"These TokenBalances objects are not from the same block ({block} and {other.block})"
)
combined: TokenBalances = TokenBalances(block=block)
for token, balance in dict.items(self):
if balance:
DefaultChecksumDict._setitem_nochecksum(
combined,
token,
Balance(balance.balance, balance.usd_value, token=token, block=block),
)
for token, balance in dict.items(other):
if balance:
if token in combined:
DefaultChecksumDict._setitem_nochecksum(
combined, token, combined._getitem_nochecksum(token) + balance
)
else:
DefaultChecksumDict._setitem_nochecksum(
combined,
token,
Balance(balance.balance, balance.usd_value, token=token, block=block),
)
return combined
def __iadd__(self, other: "TokenBalances") -> "TokenBalances":
if not isinstance(other, TokenBalances):
raise TypeError(f"{other} is not a TokenBalances object")
block = self.block
if block != other.block:
raise ValueError(
f"These TokenBalances objects are not from the same block ({block} and {other.block})"
)
for token, balance in dict.items(other):
if not balance:
continue
if token in self:
DefaultChecksumDict._setitem_nochecksum(
self,
token,
self._getitem_nochecksum(token) + balance,
)
else:
balance = Balance(balance.balance, balance.usd_value, token=token, block=block)
DefaultChecksumDict._setitem_nochecksum(self, token, balance)
return self
def __sub__(self, other: "TokenBalances") -> "TokenBalances":
"""
Subtracts another :class:`~eth_portfolio.typing.TokenBalances` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.TokenBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.TokenBalances` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.TokenBalances`.
Example:
>>> tb1 = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> tb2 = TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})
>>> result_tb = tb1 - tb2
>>> result_tb['0x123'].balance
Decimal('50')
"""
if not isinstance(other, TokenBalances):
raise TypeError(f"{other} is not a TokenBalances object")
if self.block != other.block:
raise ValueError(
f"These TokenBalances objects are not from the same block ({self.block} and {other.block})"
)
# NOTE We need a new object to avoid mutating the inputs
subtracted: TokenBalances = TokenBalances(self, block=self.block)
for token, balance in dict.items(other):
subtracted[token] -= balance
for token, balance in dict(subtracted).items():
if not balance:
del subtracted[token]
return subtracted
__slots__ = ("block",)
_RTBSeed = Dict[ProtocolLabel, TokenBalances]
[docs]
@final
class RemoteTokenBalances(DefaultDict[ProtocolLabel, TokenBalances], _SummableNonNumericMixin):
"""
Manages token balances across different protocols, extending the :class:`~eth_portfolio.typing.TokenBalances` functionality
to multiple protocols.
The class uses protocol labels as keys and :class:`~eth_portfolio.typing.TokenBalances` objects as values.
Args:
seed: An initial seed of remote token balances, either as a dictionary
or an iterable of tuples.
Example:
>>> remote_balances = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> remote_balances['protocol1']['0x123'].balance
Decimal('100')
"""
__slots__ = ("block",)
[docs]
def __init__(
self, seed: Optional[_RTBSeed] = None, *, block: Optional[BlockNumber] = None
) -> None:
super().__init__(lambda: TokenBalances(block=block))
self.block: Final = block
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items() # type: ignore [assignment]
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for TokenBalances")
for remote, token_balances in seed: # type: ignore [misc]
if self.block != token_balances.block:
raise ValueError(
f"These objects are not from the same block ({self.block} and {token_balances.block})"
)
self[remote] += token_balances # type: ignore [has-type]
def __setitem__(self, protocol: str, value: TokenBalances):
"""
Sets the token balances for a given protocol.
Args:
key: The protocol label.
value: The token balances to set for the protocol.
Raises:
TypeError: If the value is not a :class:`~eth_portfolio.typing.TokenBalances` object.
Example:
>>> remote_balances = RemoteTokenBalances()
>>> remote_balances['protocol1'] = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> remote_balances['protocol1']['0x123'].balance
Decimal('100')
"""
if not isinstance(value, TokenBalances):
raise TypeError(f"value must be a `TokenBalances` object. You passed {value}") from None
return super().__setitem__(protocol, value)
@property
def dataframe(self) -> DataFrame:
"""
Converts the remote token balances into a pandas DataFrame.
Returns:
A DataFrame representation of the remote token balances.
"""
dfs: List[DataFrame] = []
for protocol, balances in dict.items(self):
df = balances.dataframe
df["protocol"] = protocol
dfs.append(df)
return concat(dfs).reset_index(drop=True) if dfs else DataFrame()
[docs]
def sum_usd(self) -> Decimal:
"""
Sums the USD values of all token balances across all protocols.
Returns:
The total USD value of all remote token balances.
Example:
>>> remote_balances = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> total_usd = remote_balances.sum_usd()
>>> total_usd
Decimal('2000')
"""
return Decimal(sum(balance.sum_usd() for balance in dict.values(self)))
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
Returns:
True if any protocol has a non-zero balance, otherwise False.
Example:
>>> remote_balances = RemoteTokenBalances()
>>> bool(remote_balances)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
Returns:
The string representation of the remote token balances.
"""
return f"RemoteTokenBalances{dict(self)}"
def __add__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
"""
Adds another :class:`~eth_portfolio.typing.RemoteTokenBalances` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.RemoteTokenBalances` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.RemoteTokenBalances`.
Example:
>>> rb1 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> rb2 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> combined_rb = rb1 + rb2
>>> combined_rb['protocol1']['0x123'].balance
Decimal('150')
"""
if not isinstance(other, RemoteTokenBalances):
raise TypeError(f"{other} is not a RemoteTokenBalances object")
block = self.block
if block != other.block:
raise ValueError(
f"These RemoteTokenBalances objects are not from the same block ({block} and {other.block})"
)
combined: RemoteTokenBalances = RemoteTokenBalances(block=block)
for protocol, token_balances in dict.items(self):
if token_balances:
combined[protocol] += token_balances
for protocol, token_balances in dict.items(other):
if token_balances:
combined[protocol] += token_balances
return combined
def __iadd__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
if not isinstance(other, RemoteTokenBalances):
raise TypeError(f"{other} is not a RemoteTokenBalances object")
if self.block != other.block:
raise ValueError(
f"These RemoteTokenBalances objects are not from the same block ({self.block} and {other.block})"
)
for protocol, token_balances in dict.items(other):
if token_balances:
self[protocol] += token_balances
return self
def __sub__(self, other: "RemoteTokenBalances") -> "RemoteTokenBalances":
"""
Subtracts another :class:`~eth_portfolio.typing.RemoteTokenBalances` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.RemoteTokenBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.RemoteTokenBalances` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.RemoteTokenBalances`.
Example:
>>> rb1 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> rb2 = RemoteTokenBalances({'protocol1': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> result_rb = rb1 - rb2
>>> result_rb['protocol1']['0x123'].balance
Decimal('50')
"""
if not isinstance(other, RemoteTokenBalances):
raise TypeError(f"{other} is not a RemoteTokenBalances object")
if self.block != other.block:
raise ValueError(
f"These RemoteTokenBalances objects are not from the same block ({self.block} and {other.block})"
)
# NOTE We need a new object to avoid mutating the inputs
subtracted: RemoteTokenBalances = RemoteTokenBalances(self, block=self.block)
for protocol, token_balances in dict.items(other):
subtracted[protocol] -= token_balances
for protocol, token_balances in dict(subtracted).items():
if not token_balances:
del subtracted[protocol]
return subtracted
CategoryLabel = Literal["assets", "debt", "external"]
_WalletBalancesTD = TypedDict(
"_WalletBalancesTD",
{
"assets": TokenBalances,
"debt": TokenBalances,
"external": RemoteTokenBalances,
},
)
_WBSeed = Union[_WalletBalancesTD, Iterable[Tuple[CategoryLabel, TokenBalances]]]
[docs]
@final
class WalletBalances(
Dict[CategoryLabel, Union[TokenBalances, RemoteTokenBalances]], _SummableNonNumericMixin
):
"""
Organizes token balances into categories such as assets, debts, and external balances for a single wallet.
The class uses categories as keys (`assets`, `debt`, `external`) and :class:`~eth_portfolio.typing.TokenBalances` or :class:`~eth_portfolio.typing.RemoteTokenBalances`
objects as values.
Args:
seed: An initial seed of wallet balances, either as a dictionary or an iterable of tuples.
Example:
>>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> wallet_balances['assets']['0x123'].balance
Decimal('100')
"""
[docs]
def __init__(
self,
seed: Optional[Union["WalletBalances", _WBSeed]] = None,
*,
block: Optional[BlockNumber] = None,
) -> None:
self.block: Final = block
self._keys = "assets", "debt", "external"
self["assets"] = TokenBalances(block=block)
self["debt"] = RemoteTokenBalances(block=block)
self["external"] = RemoteTokenBalances(block=block)
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items() # type: ignore
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for WalletBalances")
for key, balances in seed: # type: ignore
if self.block != balances.block:
raise ValueError(
f"These objects are not from the same block ({self.block} and {balances.block})"
)
self.__validateitem(key, balances)
self[key] += balances # type: ignore [operator]
@property
def assets(self) -> TokenBalances:
"""
Returns the assets held by the wallet.
Returns:
:class:`~eth_portfolio.typing.TokenBalances`: The :class:`~eth_portfolio.typing.TokenBalances` object representing the wallet's assets.
"""
return self["assets"] # type: ignore
@property
def debt(self) -> RemoteTokenBalances:
"""
Returns the debts associated with the wallet.
Returns:
:class:`~eth_portfolio.typing.RemoteTokenBalances`: The :class:`~eth_portfolio.typing.RemoteTokenBalances` object representing the wallet's debts.
"""
return self["debt"]
@property
def external(self) -> RemoteTokenBalances:
"""
Returns the external balances associated with the wallet.
Returns:
:class:`~eth_portfolio.typing.RemoteTokenBalances`: The :class:`~eth_portfolio.typing.RemoteTokenBalances` object representing the wallet's external balances.
"""
return self["external"]
@property
def dataframe(self) -> DataFrame:
"""
Converts the wallet balances into a pandas DataFrame.
Returns:
A DataFrame representation of the wallet balances.
"""
dfs: List[DataFrame] = []
for category, category_bals in dict.items(self):
df = category_bals.dataframe
df["category"] = category
dfs.append(df)
return concat(dfs).reset_index(drop=True) if dfs else DataFrame()
[docs]
def sum_usd(self) -> Decimal:
"""
Sums the USD values of the wallet's assets, debts, and external balances.
Returns:
The total USD value of the wallet's net assets (assets - debt + external).
Example:
>>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> total_usd = wallet_balances.sum_usd()
>>> total_usd
Decimal('2000')
"""
return self.assets.sum_usd() - self.debt.sum_usd() + self.external.sum_usd()
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.WalletBalances` object.
Returns:
True if any category has a non-zero balance, otherwise False.
Example:
>>> wallet_balances = WalletBalances()
>>> bool(wallet_balances)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.WalletBalances` object.
Returns:
The string representation of the wallet balances.
"""
return f"WalletBalances {dict(self)}"
def __add__(self, other: "WalletBalances") -> "WalletBalances":
"""
Adds another :class:`~eth_portfolio.typing.WalletBalances` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.WalletBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.WalletBalances` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalances`.
Example:
>>> wb1 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> wb2 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> combined_wb = wb1 + wb2
>>> combined_wb['assets']['0x123'].balance
Decimal('150')
"""
if not isinstance(other, WalletBalances):
raise TypeError(f"{other} is not a WalletBalances object")
block = self.block
if block != other.block:
raise ValueError(
f"These WalletBalances objects are not from the same block ({block} and {other.block})"
)
combined: WalletBalances = WalletBalances(block=block)
for category, balances in dict.items(self):
if balances:
combined[category] += balances # type: ignore [operator]
for category, balances in dict.items(other):
if balances:
combined[category] += balances # type: ignore [operator]
return combined
def __iadd__(self, other: "WalletBalances") -> "WalletBalances":
if not isinstance(other, WalletBalances):
raise TypeError(f"{other} is not a WalletBalances object")
if self.block != other.block:
raise ValueError(
f"These WalletBalances objects are not from the same block ({self.block} and {other.block})"
)
for category, balances in dict.items(other):
if balances:
self[category] += balances # type: ignore [operator]
return self
def __sub__(self, other: "WalletBalances") -> "WalletBalances":
"""
Subtracts another :class:`~eth_portfolio.typing.WalletBalances` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.WalletBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.WalletBalances` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalances`.
Example:
>>> wb1 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> wb2 = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> result_wb = wb1 - wb2
>>> result_wb['assets']['0x123'].balance
Decimal('50')
"""
if not isinstance(other, WalletBalances):
raise TypeError(f"{other} is not a WalletBalances object")
if self.block != other.block:
raise ValueError(
f"These WalletBalances objects are not from the same block ({self.block} and {other.block})"
)
# We need a new object to avoid mutating the inputs
subtracted: WalletBalances = WalletBalances(self, block=self.block)
for category, balances in dict.items(other):
subtracted[category] -= balances # type: ignore
for category, balances in dict(subtracted).items():
if not balances:
del subtracted[category]
return subtracted
[docs]
def __getitem__(self, key: CategoryLabel) -> Union[TokenBalances, RemoteTokenBalances]:
"""
Retrieves the balance associated with the given category key.
Args:
key: The category label (`assets`, `debt`, or `external`).
Returns:
The balances associated with the category.
Raises:
KeyError: If the key is not a valid category.
Example:
>>> wallet_balances = WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> assets_balances = wallet_balances['assets']
>>> assets_balances['0x123'].balance
Decimal('100')
"""
self.__validatekey(key)
return super().__getitem__(key)
def __setitem__(
self, key: CategoryLabel, value: Union[TokenBalances, RemoteTokenBalances]
) -> None:
"""
Sets the balance associated with the given category key.
Args:
key: The category label (`assets`, `debt`, or `external`).
value: The balance to associate with the category.
Raises:
KeyError: If the key is not a valid category.
TypeError: If the value is not a valid balance type for the category.
Example:
>>> wallet_balances = WalletBalances()
>>> wallet_balances['assets'] = TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})
>>> wallet_balances['assets']['0x123'].balance
Decimal('100')
"""
self.__validateitem(key, value)
return super().__setitem__(key, value)
def __validatekey(self, key: CategoryLabel) -> None:
"""
Validates that the given key is a valid category.
Valid keys: "assets", "debt", "external"
Args:
key: The category label to validate.
Raises:
KeyError: If the key is not a valid category.
"""
if key not in self._keys:
raise KeyError(
f"{key} is not a valid key for WalletBalances. Valid keys are: {self._keys}"
)
def __validateitem(self, key: CategoryLabel, item: Any) -> None:
"""
Validates that the given item is a valid balance type for the category.
Args:
key: The category label.
item: The balance item to validate.
Raises:
KeyError: If the key is not a valid category.
TypeError: If the item is not a valid balance type for the category.
"""
self.__validatekey(key)
if key == "assets":
if not isinstance(item, TokenBalances):
raise TypeError(
f'{item} is not a valid value for "{key}". Must be a TokenBalances object.'
)
elif key in {"debt", "external"}:
if not isinstance(item, RemoteTokenBalances):
raise TypeError(
f'{item} is not a valid value for "{key}". Must be a RemoteTokenBalances object.'
)
else:
raise NotImplementedError(f"key {key} is not yet implemented.")
_PBSeed = Union[Dict[Address, WalletBalances], Iterable[Tuple[Address, WalletBalances]]]
[docs]
@final
class PortfolioBalances(DefaultChecksumDict[WalletBalances], _SummableNonNumericMixin): # type: ignore [misc]
"""
Aggregates :class:`~eth_portfolio.typing.WalletBalances` for multiple wallets, providing operations to sum
balances across an entire portfolio.
The class uses wallet addresses as keys and :class:`~eth_portfolio.typing.WalletBalances` objects as values.
Args:
seed: An initial seed of portfolio balances, either as a dictionary or an iterable of tuples.
Example:
>>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})})
>>> portfolio_balances['0x123']['assets']['0x456'].balance
Decimal('100')
"""
[docs]
def __init__(
self, seed: Optional[_PBSeed] = None, *, block: Optional[BlockNumber] = None
) -> None:
super().__init__(lambda: WalletBalances(block=block))
self.block: Final = block
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items()
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for PortfolioBalances")
for wallet, balances in seed:
if self.block != balances.block:
raise ValueError(
f"These objects are not from the same block ({self.block} and {balances.block})"
)
self[wallet] += balances
def __setitem__(self, key, value):
if not isinstance(value, WalletBalances):
raise TypeError(
f"value must be a `WalletBalances` object. You passed {value}"
) from None
return super().__setitem__(key, value)
@property
def dataframe(self) -> DataFrame:
"""
Converts the portfolio balances into a pandas DataFrame.
Returns:
A DataFrame representation of the portfolio balances.
"""
dfs: List[DataFrame] = []
for wallet, balances in dict.items(self):
df = balances.dataframe
df["wallet"] = wallet
dfs.append(df)
return concat(dfs).reset_index(drop=True) if dfs else DataFrame()
[docs]
def sum_usd(self) -> Decimal:
"""
Sums the USD values of all wallet balances in the portfolio.
Returns:
The total USD value of all wallet balances in the portfolio.
Example:
>>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> total_usd = portfolio_balances.sum_usd()
>>> total_usd
Decimal('2000')
"""
return sum(balances.sum_usd() for balances in dict.values(self)) # type: ignore
@cached_property
def inverted(self) -> "PortfolioBalancesByCategory":
"""
Returns an inverted view of the portfolio balances, grouped by category first.
Returns:
:class:`~eth_portfolio.typing.PortfolioBalancesByCategory`: The inverted portfolio balances, grouped by category.
Example:
>>> portfolio_balances = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> inverted_pb = portfolio_balances.inverted
>>> inverted_pb['assets']['0x123'].balance
Decimal('100')
"""
inverted = PortfolioBalancesByCategory()
for wallet, wbalances in dict.items(self):
for label, tbalances in wbalances.items():
if tbalances:
inverted[label][wallet] += tbalances # type: ignore [operator]
return inverted
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.PortfolioBalances` object.
Returns:
True if any wallet has a non-zero balance of any token, otherwise False.
Example:
>>> portfolio_balances = PortfolioBalances()
>>> bool(portfolio_balances)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.PortfolioBalances` object.
Returns:
The string representation of the portfolio balances.
"""
return f"WalletBalances{dict(self)}"
def __add__(self, other: "PortfolioBalances") -> "PortfolioBalances":
"""
Adds another :class:`~eth_portfolio.typing.PortfolioBalances` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.PortfolioBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.PortfolioBalances` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalances`.
Example:
>>> pb1 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> pb2 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
>>> combined_pb = pb1 + pb2
>>> combined_pb['0x123']['assets']['0x123'].balance
Decimal('150')
"""
if not isinstance(other, PortfolioBalances):
raise TypeError(f"{other} is not a PortfolioBalances object")
block = self.block
if block != other.block:
raise ValueError(
f"These PortfolioBalances objects are not from the same block ({block} and {other.block})"
)
# NOTE We need a new object to avoid mutating the inputs
combined: PortfolioBalances = PortfolioBalances(block=block)
for wallet, balance in dict.items(self):
if balance:
DefaultChecksumDict._setitem_nochecksum(
combined, wallet, combined._getitem_nochecksum(wallet) + balance
)
for wallet, balance in dict.items(other):
if balance:
DefaultChecksumDict._setitem_nochecksum(
combined, wallet, combined._getitem_nochecksum(wallet) + balance
)
return combined
def __iadd__(self, other: "PortfolioBalances") -> "PortfolioBalances":
if not isinstance(other, PortfolioBalances):
raise TypeError(f"{other} is not a PortfolioBalances object")
if self.block != other.block:
raise ValueError(
f"These PortfolioBalances objects are not from the same block ({self.block} and {other.block})"
)
for wallet, balance in dict.items(other):
if balance:
DefaultChecksumDict._setitem_nochecksum(
self, wallet, self._getitem_nochecksum(wallet) + balance
)
return self
def __sub__(self, other: "PortfolioBalances") -> "PortfolioBalances":
"""
Subtracts another :class:`~eth_portfolio.typing.PortfolioBalances` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.PortfolioBalances` object.
Returns:
A new :class:`~eth_portfolio.typing.PortfolioBalances` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalances`.
Example:
>>> pb1 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> pb2 = PortfolioBalances({'0x123': WalletBalances({'assets': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
>>> result_pb = pb1 - pb2
>>> result_pb['0x123']['assets']['0x123'].balance
Decimal('50')
"""
if not isinstance(other, PortfolioBalances):
raise TypeError(f"{other} is not a PortfolioBalances object")
if self.block != other.block:
raise ValueError(
f"These PortfolioBalances objects are not from the same block ({self.block} and {other.block})"
)
# We need a new object to avoid mutating the inputs
subtracted: PortfolioBalances = PortfolioBalances(self, block=self.block)
for protocol, balances in dict.items(other):
subtracted[protocol] -= balances
for protocol, balances in subtracted.items():
if not balances:
del subtracted[protocol]
return subtracted
__slots__ = ("block",)
_WTBInput = Union[Dict[Address, TokenBalances], Iterable[Tuple[Address, TokenBalances]]]
[docs]
@final
class WalletBalancesRaw(DefaultChecksumDict[TokenBalances], _SummableNonNumericMixin): # type: ignore [misc]
# Since PortfolioBalances key lookup is: ``wallet -> category -> token -> balance``
# We need a new structure for key pattern: ``wallet -> token -> balance``
# WalletBalancesRaw fills this role.
"""
A structure for key pattern `wallet -> token -> balance`.
This class is similar to :class:`~eth_portfolio.typing.WalletBalances` but optimized for key lookups by wallet and token directly.
It manages :class:`~eth_portfolio.typing.TokenBalances` objects for multiple wallets.
Args:
seed: An initial seed of wallet balances, either as a dictionary or an iterable of tuples.
Example:
>>> raw_balances = WalletBalancesRaw({'0x123': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})
>>> raw_balances['0x123']['0x456'].balance
Decimal('100')
"""
[docs]
def __init__(
self, seed: Optional[_WTBInput] = None, *, block: Optional[BlockNumber] = None
) -> None:
super().__init__(lambda: TokenBalances(block=block))
self.block: Final = block
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items()
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for WalletBalancesRaw")
for wallet, balances in seed:
if self.block != balances.block:
raise ValueError(
f"These objects are not from the same block ({self.block} and {balances.block})"
)
self[wallet] += balances
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.WalletBalancesRaw` object.
Returns:
True if any wallet has a non-zero balance, otherwise False.
Example:
>>> raw_balances = WalletBalancesRaw()
>>> bool(raw_balances)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.WalletBalancesRaw` object.
Returns:
The string representation of the raw wallet balances.
"""
return f"WalletBalances{dict(self)}"
def __add__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
"""
Adds another :class:`~eth_portfolio.typing.WalletBalancesRaw` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.WalletBalancesRaw` object.
Returns:
A new :class:`~eth_portfolio.typing.WalletBalancesRaw` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalancesRaw`.
Example:
>>> raw_balances1 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> raw_balances2 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> combined_raw = raw_balances1 + raw_balances2
>>> combined_raw['0x123']['0x123'].balance
Decimal('150')
"""
if not isinstance(other, WalletBalancesRaw):
raise TypeError(f"{other} is not a WalletBalancesRaw object")
block = self.block
if block != other.block:
raise ValueError(
f"These WalletBalancesRaw objects are not from the same block ({block} and {other.block})"
)
combined: WalletBalancesRaw = WalletBalancesRaw(block=block)
for wallet, balance in dict.items(self):
if balance:
DefaultChecksumDict._setitem_nochecksum(
combined, wallet, combined._getitem_nochecksum(wallet) + balance
)
for wallet, balance in dict.items(other):
if balance:
DefaultChecksumDict._setitem_nochecksum(
combined, wallet, combined._getitem_nochecksum(wallet) + balance
)
return combined
def __iadd__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
if not isinstance(other, WalletBalancesRaw):
raise TypeError(f"{other} is not a WalletBalancesRaw object")
if self.block != other.block:
raise ValueError(
f"These WalletBalancesRaw objects are not from the same block ({self.block} and {other.block})"
)
for wallet, balance in dict.items(other):
if balance:
DefaultChecksumDict._setitem_nochecksum(
self, wallet, self._getitem_nochecksum(wallet) + balance
)
return self
def __sub__(self, other: "WalletBalancesRaw") -> "WalletBalancesRaw":
"""
Subtracts another :class:`~eth_portfolio.typing.WalletBalancesRaw` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.WalletBalancesRaw` object.
Returns:
A new :class:`~eth_portfolio.typing.WalletBalancesRaw` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.WalletBalancesRaw`.
Example:
>>> raw_balances1 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})
>>> raw_balances2 = WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})
>>> result_raw = raw_balances1 - raw_balances2
>>> result_raw['0x123']['0x123'].balance
Decimal('50')
"""
if not isinstance(other, WalletBalancesRaw):
raise TypeError(f"{other} is not a WalletBalancesRaw object")
if self.block != other.block:
raise ValueError(
f"These WalletBalancesRaw objects are not from the same block ({self.block} and {other.block})"
)
# NOTE We need a new object to avoid mutating the inputs
subtracted: WalletBalancesRaw = WalletBalancesRaw(self, block=other.block)
for wallet, balances in dict.items(other):
if balances:
subtracted[wallet] -= balances
for wallet, balances in subtracted.items():
if not balances:
del subtracted[wallet]
return subtracted
__slots__ = ("block",)
_CBInput = Union[
Dict[CategoryLabel, WalletBalancesRaw], Iterable[Tuple[CategoryLabel, WalletBalancesRaw]]
]
[docs]
@final
class PortfolioBalancesByCategory(
DefaultDict[CategoryLabel, WalletBalancesRaw], _SummableNonNumericMixin
):
"""
Provides an inverted view of :class:`~eth_portfolio.typing.PortfolioBalances`, allowing access by category first,
then by wallet and token.
The class uses category labels as keys (`assets`, `debt`, `external`) and :class:`~eth_portfolio.typing.WalletBalancesRaw`
objects as values.
Args:
seed: An initial seed of portfolio balances by category, either as a dictionary or an iterable of tuples.
Example:
>>> pb_by_category = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x456': Balance(Decimal('100'), Decimal('2000'))})})})
>>> pb_by_category['assets']['0x123']['0x456'].balance
Decimal('100')
"""
[docs]
def __init__(
self, seed: Optional[_CBInput] = None, *, block: Optional[BlockNumber] = None
) -> None:
super().__init__(lambda: WalletBalancesRaw(block=block))
self.block: Final = block
if seed is None:
return
if isinstance(seed, dict):
seed = seed.items()
if not isinstance(seed, Iterable):
raise TypeError(f"{seed} is not a valid input for PortfolioBalancesByCategory")
for label, balances in seed: # type: ignore
if self.block != balances.block:
raise ValueError(
f"These objects are not from the same block ({self.block} and {balances.block})"
)
self[label] += balances
@property
def assets(self) -> WalletBalancesRaw:
"""
Returns the asset balances across all wallets.
Returns:
:class:`~eth_portfolio.typing.WalletBalancesRaw`: The :class:`~eth_portfolio.typing.WalletBalancesRaw` object representing the asset balances.
"""
return self["assets"]
@property
def debt(self) -> WalletBalancesRaw:
"""
Returns the debt balances across all wallets.
Returns:
:class:`~eth_portfolio.typing.WalletBalancesRaw`: The :class:`~eth_portfolio.typing.WalletBalancesRaw` object representing the debt balances.
"""
return self["debt"]
[docs]
def invert(self) -> "PortfolioBalances":
"""
Inverts the portfolio balances by category to group by wallet first.
Returns:
:class:`~eth_portfolio.typing.PortfolioBalances`: The inverted portfolio balances, grouped by wallet first.
Example:
>>> pb_by_category = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> inverted_pb = pb_by_category.invert()
>>> inverted_pb['0x123']['assets']['0x123'].balance
Decimal('100')
"""
inverted = PortfolioBalances()
for label, wtbalances in dict.items(self):
for wallet, tbalances in wtbalances.items():
if tbalances:
inverted[wallet][label] += tbalances # type: ignore [operator]
return inverted
def __bool__(self) -> bool:
"""
Evaluates the truth value of the :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.
Returns:
True if any category has a non-zero balance, otherwise False.
Example:
>>> pb_by_category = PortfolioBalancesByCategory()
>>> bool(pb_by_category)
False
"""
return any(dict.values(self))
def __repr__(self) -> str:
"""
Returns a string representation of the :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.
Returns:
The string representation of the portfolio balances by category.
"""
return f"PortfolioBalancesByCategory{dict(self)}"
def __add__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":
"""
Adds another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object to this one.
Args:
other: Another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.
Returns:
A new :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object with the combined balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`.
Example:
>>> pb_by_category1 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> pb_by_category2 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
>>> combined_pb_by_category = pb_by_category1 + pb_by_category2
>>> combined_pb_by_category['assets']['0x123']['0x123'].balance
Decimal('150')
"""
if not isinstance(other, PortfolioBalancesByCategory):
raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")
block = self.block
if block != other.block:
raise ValueError(
f"These PortfolioBalancesByCategory objects are not from the same block ({block} and {other.block})"
)
combined: PortfolioBalancesByCategory = PortfolioBalancesByCategory(block=block)
for protocol, balances in dict.items(self):
if balances:
combined[protocol] += balances
for protocol, balances in dict.items(other):
if balances:
combined[protocol] += balances
return combined
def __iadd__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":
if not isinstance(other, PortfolioBalancesByCategory):
raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")
if self.block != other.block:
raise ValueError(
f"These PortfolioBalancesByCategory objects are not from the same block ({self.block} and {other.block})"
)
for protocol, balances in dict.items(other):
if balances:
self[protocol] += balances
return self
def __sub__(self, other: "PortfolioBalancesByCategory") -> "PortfolioBalancesByCategory":
"""
Subtracts another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object from this one.
Args:
other: Another :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object.
Returns:
A new :class:`~eth_portfolio.typing.PortfolioBalancesByCategory` object with the subtracted balances.
Raises:
TypeError: If the other object is not a :class:`~eth_portfolio.typing.PortfolioBalancesByCategory`.
Example:
>>> pb_by_category1 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('100'), Decimal('2000'))})})})
>>> pb_by_category2 = PortfolioBalancesByCategory({'assets': WalletBalancesRaw({'0x123': TokenBalances({'0x123': Balance(Decimal('50'), Decimal('1000'))})})})
>>> result_pb_by_category = pb_by_category1 - pb_by_category2
>>> result_pb_by_category['assets']['0x123']['0x123'].balance
Decimal('50')
"""
if not isinstance(other, PortfolioBalancesByCategory):
raise TypeError(f"{other} is not a PortfolioBalancesByCategory object")
if self.block != other.block:
raise ValueError(
f"These PortfolioBalancesByCategory objects are not from the same block ({self.block} and {other.block})"
)
# NOTE We need a new object to avoid mutating the inputs
subtracted: PortfolioBalancesByCategory = PortfolioBalancesByCategory(
self, block=self.block
)
for protocol, balances in dict.items(other):
subtracted[protocol] -= balances
for protocol, balances in subtracted.items():
if not balances:
del subtracted[protocol]
return subtracted