rustfava 0.1.0__py3-none-any.whl

rustfava/core/charts.py

@@ -0,0 +1,301 @@
+"""Provide data suitable for rustfava's charts."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from dataclasses import fields
+from dataclasses import is_dataclass
+from datetime import date
+from decimal import Decimal
+from re import Pattern
+from typing import Any
+from typing import TYPE_CHECKING
+
+import json
+
+from flask.json.provider import JSONProvider
+
+from rustfava.beans.abc import Position
+from rustfava.rustledger.constants import Booking
+from rustfava.rustledger.constants import MISSING
+from rustfava.beans.abc import Transaction
+from rustfava.beans.account import account_tester
+from rustfava.beans.flags import FLAG_UNREALIZED
+from rustfava.beans.helpers import slice_entry_dates
+from rustfava.core.conversion import conversion_from_str
+from rustfava.core.inventory import CounterInventory
+from rustfava.core.module_base import FavaModule
+from rustfava.util import listify
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Iterable
+    from collections.abc import Mapping
+
+    from rustfava.core import FilteredLedger
+    from rustfava.core.conversion import Conversion
+    from rustfava.core.inventory import SimpleCounterInventory
+    from rustfava.core.tree import SerialisedTreeNode
+    from rustfava.util.date import Interval
+
+
+ZERO = Decimal()
+
+
+def _json_default(o: Any) -> Any:
+    """Specific serialisation for some data types."""
+    if isinstance(o, Decimal):
+        return float(o)
+    if isinstance(o, (date, Booking, Position)):
+        return str(o)
+    if isinstance(o, (set, frozenset)):
+        return list(o)
+    if isinstance(o, Pattern):
+        return o.pattern
+    if is_dataclass(o):
+        return {field.name: getattr(o, field.name) for field in fields(o)}
+    if o is MISSING:  # pragma: no cover
+        return None
+    raise TypeError  # pragma: no cover
+
+
+def dumps(obj: Any, **_kwargs: Any) -> str:
+    """Dump as a JSON string."""
+    return json.dumps(
+        obj, sort_keys=True, separators=(",", ":"), default=_json_default
+    )
+
+
+def loads(s: str | bytes) -> Any:
+    """Load a JSON string."""
+    return json.loads(s)
+
+
+class RustfavaJSONProvider(JSONProvider):
+    """Use custom JSON encoder and decoder."""
+
+    def dumps(self, obj: Any, **_kwargs: Any) -> str:  # noqa: D102
+        return json.dumps(
+            obj, sort_keys=True, separators=(",", ":"), default=_json_default
+        )
+
+    def loads(self, s: str | bytes, **_kwargs: Any) -> Any:  # noqa: D102
+        return json.loads(s)
+
+
+@dataclass(frozen=True)
+class DateAndBalance:
+    """Balance at a date."""
+
+    date: date
+    balance: SimpleCounterInventory
+
+
+@dataclass(frozen=True)
+class DateAndBalanceWithBudget:
+    """Balance at a date with a budget."""
+
+    date: date
+    balance: SimpleCounterInventory
+    account_balances: Mapping[str, SimpleCounterInventory]
+    budgets: Mapping[str, Decimal]
+
+
+class ChartModule(FavaModule):
+    """Return data for the various charts in rustfava."""
+
+    def hierarchy(
+        self,
+        filtered: FilteredLedger,
+        account_name: str,
+        conversion: Conversion,
+    ) -> SerialisedTreeNode:
+        """Render an account tree."""
+        tree = filtered.root_tree
+        return tree.get(account_name).serialise(
+            conversion, self.ledger.prices, filtered.end_date
+        )
+
+    @listify
+    def interval_totals(
+        self,
+        filtered: FilteredLedger,
+        interval: Interval,
+        accounts: str | tuple[str, ...],
+        conversion: str | Conversion,
+        *,
+        invert: bool = False,
+    ) -> Iterable[DateAndBalanceWithBudget]:
+        """Render totals for account (or accounts) in the intervals.
+
+        Args:
+            filtered: The filtered ledger.
+            interval: An interval.
+            accounts: A single account (str) or a tuple of accounts.
+            conversion: The conversion to use.
+            invert: invert all numbers.
+
+        Yields:
+            The balances and budgets for the intervals.
+        """
+        conv = conversion_from_str(conversion)
+        prices = self.ledger.prices
+
+        # limit the bar charts to 100 intervals
+        intervals = filtered.interval_ranges(interval)[-100:]
+
+        for date_range in intervals:
+            inventory = CounterInventory()
+            entries = slice_entry_dates(
+                filtered.entries, date_range.begin, date_range.end
+            )
+            account_inventories: dict[str, CounterInventory] = defaultdict(
+                CounterInventory,
+            )
+            for entry in entries:
+                for posting in getattr(entry, "postings", []):
+                    if posting.account.startswith(accounts):
+                        account_inventories[posting.account].add_position(
+                            posting,
+                        )
+                        inventory.add_position(posting)
+            balance = conv.apply(
+                inventory,
+                prices,
+                date_range.end_inclusive,
+            )
+            account_balances = {
+                account: conv.apply(
+                    acct_value,
+                    prices,
+                    date_range.end_inclusive,
+                )
+                for account, acct_value in account_inventories.items()
+            }
+            budgets = (
+                self.ledger.budgets.calculate_children(
+                    accounts,
+                    date_range.begin,
+                    date_range.end,
+                )
+                if isinstance(accounts, str)
+                else {}
+            )
+
+            if invert:
+                balance = -balance
+                budgets = {k: -v for k, v in budgets.items()}
+                account_balances = {k: -v for k, v in account_balances.items()}
+
+            yield DateAndBalanceWithBudget(
+                date_range.end_inclusive,
+                balance,
+                account_balances,
+                budgets,
+            )
+
+    @listify
+    def linechart(
+        self,
+        filtered: FilteredLedger,
+        account_name: str,
+        conversion: str | Conversion,
+    ) -> Iterable[DateAndBalance]:
+        """Get the balance of an account as a line chart.
+
+        Args:
+            filtered: The filtered ledger.
+            account_name: A string.
+            conversion: The conversion to use.
+
+        Yields:
+            Dicts for all dates on which the balance of the given
+            account has changed containing the balance (in units) of the
+            account at that date.
+        """
+        conv = conversion_from_str(conversion)
+
+        def _balances() -> Iterable[tuple[date, CounterInventory]]:
+            last_date = None
+            running_balance = CounterInventory()
+            is_child_account = account_tester(account_name, with_children=True)
+
+            for entry in filtered.entries:
+                for posting in getattr(entry, "postings", []):
+                    if is_child_account(posting.account):
+                        new_date = entry.date
+                        if last_date is not None and new_date > last_date:
+                            yield (last_date, running_balance)
+                        running_balance.add_position(posting)
+                        last_date = new_date
+
+            if last_date is not None:
+                yield (last_date, running_balance)
+
+        # When the balance for a commodity just went to zero, it will be
+        # missing from the 'balance' so keep track of currencies that last had
+        # a balance.
+        last_currencies = None
+        prices = self.ledger.prices
+
+        for d, running_bal in _balances():
+            balance = conv.apply(running_bal, prices, d)
+            currencies = set(balance.keys())
+            if last_currencies:
+                for currency in last_currencies - currencies:
+                    balance[currency] = ZERO
+            last_currencies = currencies
+            yield DateAndBalance(d, balance)
+
+    @listify
+    def net_worth(
+        self,
+        filtered: FilteredLedger,
+        interval: Interval,
+        conversion: str | Conversion,
+    ) -> Iterable[DateAndBalance]:
+        """Compute net worth.
+
+        Args:
+            filtered: The filtered ledger.
+            interval: A string for the interval.
+            conversion: The conversion to use.
+
+        Yields:
+            Dicts for all ends of the given interval containing the
+            net worth (Assets + Liabilities) separately converted to all
+            operating currencies.
+        """
+        conv = conversion_from_str(conversion)
+        transactions = (
+            entry
+            for entry in filtered.entries
+            if (
+                isinstance(entry, Transaction)
+                and entry.flag != FLAG_UNREALIZED
+            )
+        )
+
+        types = (
+            self.ledger.options["name_assets"],
+            self.ledger.options["name_liabilities"],
+        )
+
+        txn = next(transactions, None)
+        inventory = CounterInventory()
+
+        prices = self.ledger.prices
+        for date_range in filtered.interval_ranges(interval):
+            while txn and txn.date < date_range.end:
+                for posting in txn.postings:
+                    if posting.account.startswith(types):
+                        inventory.add_position(posting)
+                txn = next(transactions, None)
+            yield DateAndBalance(
+                date_range.end_inclusive,
+                conv.apply(
+                    inventory,
+                    prices,
+                    date_range.end_inclusive,
+                ),
+            )

rustfava/core/commodities.py

@@ -0,0 +1,37 @@
+"""Attributes for auto-completion."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from decimal import Decimal
+from typing import TYPE_CHECKING
+
+from rustfava.core.module_base import FavaModule
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.core import RustfavaLedger
+
+
+class CommoditiesModule(FavaModule):
+    """Details about the currencies and commodities."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        self.names: dict[str, str] = {}
+        self.precisions: dict[str, int] = {}
+
+    def load_file(self) -> None:  # noqa: D102
+        self.names = {}
+        self.precisions = {}
+        for commodity in self.ledger.all_entries_by_type.Commodity:
+            name = commodity.meta.get("name")
+            if name:
+                self.names[commodity.currency] = str(name)
+            precision = commodity.meta.get("precision")
+            if isinstance(precision, (str, int, Decimal)):
+                with suppress(ValueError):
+                    self.precisions[commodity.currency] = int(precision)
+
+    def name(self, commodity: str) -> str:
+        """Get the name of a commodity (or the commodity itself if not set)."""
+        return self.names.get(commodity, commodity)

rustfava/core/conversion.py

@@ -0,0 +1,229 @@
+"""Commodity conversion helpers for Fava.
+
+All functions in this module will be automatically added as template filters.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from typing import TYPE_CHECKING
+
+from rustfava.core.inventory import _Amount
+from rustfava.core.inventory import SimpleCounterInventory
+
+try:
+    from typing import override
+except ImportError:  # pragma: no cover
+    from typing import override
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+
+    from beancount.core.inventory import Inventory
+
+    from rustfava.beans.prices import RustfavaPriceMap
+    from rustfava.beans.protocols import Amount
+    from rustfava.beans.protocols import Position
+    from rustfava.core.inventory import CounterInventory
+
+
+def get_cost(pos: Position) -> Amount:
+    """Return the total cost of a Position."""
+    cost_ = pos.cost
+    return (
+        _Amount(cost_.number * pos.units.number, cost_.currency)
+        if cost_ is not None
+        else pos.units
+    )
+
+
+def get_market_value(
+    pos: Position,
+    prices: RustfavaPriceMap,
+    date: datetime.date | None = None,
+) -> Amount:
+    """Get the market value of a Position.
+
+    This differs from the convert.get_value function in Beancount by returning
+    the cost value if no price can be found.
+
+    Args:
+        pos: A Position.
+        prices: A rustfavaPriceMap
+        date: A datetime.date instance to evaluate the value at, or None.
+
+    Returns:
+        An Amount, with value converted or if the conversion failed just the
+        cost value (or the units if the position has no cost).
+    """
+    units_ = pos.units
+    cost_ = pos.cost
+
+    if cost_ is not None:
+        value_currency = cost_.currency
+        base_quote = (units_.currency, value_currency)
+        price_number = prices.get_price(base_quote, date)
+        if price_number is not None:
+            return _Amount(
+                units_.number * price_number,
+                value_currency,
+            )
+        return _Amount(units_.number * cost_.number, value_currency)
+    return units_
+
+
+def convert_position(
+    pos: Position,
+    target_currency: str,
+    prices: RustfavaPriceMap,
+    date: datetime.date | None = None,
+) -> Amount:
+    """Get the value of a Position in a particular currency.
+
+    Args:
+        pos: A Position.
+        target_currency: The target currency to convert to.
+        prices: A rustfavaPriceMap
+        date: A datetime.date instance to evaluate the value at, or None.
+
+    Returns:
+        An Amount, with value converted or if the conversion failed just the
+        cost value (or the units if the position has no cost).
+    """
+    units_ = pos.units
+
+    # try the direct conversion
+    base_quote = (units_.currency, target_currency)
+    price_number = prices.get_price(base_quote, date)
+    if price_number is not None:
+        return _Amount(units_.number * price_number, target_currency)
+
+    cost_ = pos.cost
+    if cost_ is not None:
+        cost_currency = cost_.currency
+        if cost_currency != target_currency:
+            base_quote1 = (units_.currency, cost_currency)
+            rate1 = prices.get_price(base_quote1, date)
+            if rate1 is not None:
+                base_quote2 = (cost_currency, target_currency)
+                rate2 = prices.get_price(base_quote2, date)
+                if rate2 is not None:
+                    return _Amount(
+                        units_.number * rate1 * rate2,
+                        target_currency,
+                    )
+    return units_
+
+
+class Conversion(ABC):
+    """A conversion."""
+
+    @abstractmethod
+    def apply(
+        self,
+        inventory: CounterInventory,
+        prices: RustfavaPriceMap,
+        date: datetime.date | None = None,
+    ) -> SimpleCounterInventory:
+        """Apply the conversion to an inventory (CounterInventory)."""
+
+
+class _AtCostConversion(Conversion):
+    @override
+    def apply(
+        self,
+        inventory: CounterInventory,
+        prices: RustfavaPriceMap | None = None,
+        date: datetime.date | None = None,
+    ) -> SimpleCounterInventory:
+        return inventory.reduce(get_cost)
+
+
+class _AtValueConversion(Conversion):
+    @override
+    def apply(
+        self,
+        inventory: CounterInventory,
+        prices: RustfavaPriceMap,
+        date: datetime.date | None = None,
+    ) -> SimpleCounterInventory:
+        return inventory.reduce(get_market_value, prices, date)
+
+
+class _UnitsConversion(Conversion):
+    @override
+    def apply(
+        self,
+        inventory: CounterInventory,
+        prices: RustfavaPriceMap | None = None,
+        date: datetime.date | None = None,
+    ) -> SimpleCounterInventory:
+        counter = SimpleCounterInventory()
+        for (currency, _cost), number in inventory.items():
+            counter.add(currency, number)
+        return counter
+
+    def apply_inventory(
+        self,
+        inventory: Inventory,
+    ) -> SimpleCounterInventory:
+        """Apply the conversion to an Beancount Inventory."""
+        counter = SimpleCounterInventory()
+        for pos in inventory:
+            counter.add(pos.units.currency, pos.units.number)
+        return counter
+
+
+class _CurrencyConversion(Conversion):
+    """Conversion to a list of currencies."""
+
+    def __init__(self, value: str) -> None:
+        self._currencies = tuple(value.split(","))
+
+    @override
+    def apply(
+        self,
+        inventory: CounterInventory,
+        prices: RustfavaPriceMap,
+        date: datetime.date | None = None,
+    ) -> SimpleCounterInventory:
+        currencies = iter(self._currencies)
+        currency = next(currencies)
+        res = inventory.reduce(convert_position, currency, prices, date)
+        for currency in currencies:
+            res = res.reduce(convert_position, currency, prices, date)
+        return res
+
+
+#: Convert position to its total cost.
+AT_COST = _AtCostConversion()
+#: Convert position to its market value.
+AT_VALUE = _AtValueConversion()
+#: Convert position to its units.
+UNITS = _UnitsConversion()
+
+
+def conversion_from_str(value: str | Conversion) -> Conversion:
+    """Parse a conversion string."""
+    if not isinstance(value, str):
+        return value
+    if value == "at_cost":
+        return AT_COST
+    if value == "at_value":
+        return AT_VALUE
+    if value == "units":
+        return UNITS
+
+    return _CurrencyConversion(value)
+
+
+def cost_or_value(
+    inventory: CounterInventory,
+    conversion: str | Conversion,
+    prices: RustfavaPriceMap,
+    date: datetime.date | None = None,
+) -> SimpleCounterInventory:
+    """Get the cost or value of an inventory."""
+    conversion = conversion_from_str(conversion)
+    return conversion.apply(inventory, prices, date)

rustfava/core/documents.py

@@ -0,0 +1,87 @@
+"""Document path related helpers."""
+
+from __future__ import annotations
+
+from os import altsep
+from os import sep
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rustfava.helpers import RustfavaAPIError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from rustfava.core import RustfavaLedger
+
+
+class NotADocumentsFolderError(RustfavaAPIError):
+    """Not a documents folder."""
+
+    def __init__(self, folder: str) -> None:
+        super().__init__(f"Not a documents folder: {folder}.")
+
+
+class NotAValidAccountError(RustfavaAPIError):
+    """Not a valid account."""
+
+    def __init__(self, account: str) -> None:
+        super().__init__(f"Not a valid account: '{account}'")
+
+
+def is_document_or_import_file(filename: str, ledger: RustfavaLedger) -> bool:
+    """Check whether the filename is a document or in an import directory.
+
+    This is a security validation function that prevents path traversal.
+
+    Args:
+        filename: The filename to check.
+        ledger: The RustfavaLedger.
+
+    Returns:
+        Whether this is one of the documents or a path in an import dir.
+    """
+    # Check if it's an exact match for a known document
+    if any(
+        filename == d.filename for d in ledger.all_entries_by_type.Document
+    ):
+        return True
+    # Check if resolved path is within an import directory (prevents path traversal)
+    file_path = Path(filename).resolve()
+    for import_dir in ledger.fava_options.import_dirs:
+        resolved_dir = ledger.join_path(import_dir).resolve()
+        if file_path.is_relative_to(resolved_dir):
+            return True
+    return False
+
+
+def filepath_in_document_folder(
+    documents_folder: str,
+    account: str,
+    filename: str,
+    ledger: RustfavaLedger,
+) -> Path:
+    """File path for a document in the folder for an account.
+
+    Args:
+        documents_folder: The documents folder.
+        account: The account to choose the subfolder for.
+        filename: The filename of the document.
+        ledger: The RustfavaLedger.
+
+    Returns:
+        The path that the document should be saved at.
+    """
+    if documents_folder not in ledger.options["documents"]:
+        raise NotADocumentsFolderError(documents_folder)
+
+    if account not in ledger.attributes.accounts:
+        raise NotAValidAccountError(account)
+
+    filename = filename.replace(sep, " ")
+    if altsep:  # pragma: no cover
+        filename = filename.replace(altsep, " ")
+
+    return ledger.join_path(
+        documents_folder,
+        *account.split(":"),
+        filename,
+    )