rustfava 0.1.0__py3-none-any.whl

rustfava/core/accounts.py

@@ -0,0 +1,161 @@
+"""Account close date and metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import TYPE_CHECKING
+
+from rustfava.beans.abc import Balance
+from rustfava.beans.abc import Close
+from rustfava.beans.flags import FLAG_UNREALIZED
+from rustfava.beans.funcs import hash_entry
+from rustfava.core.conversion import UNITS
+from rustfava.core.group_entries import group_entries_by_account
+from rustfava.core.group_entries import TransactionPosting
+from rustfava.core.module_base import FavaModule
+from rustfava.core.tree import Tree
+from rustfava.util.date import local_today
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+    from collections.abc import Sequence
+    from typing import Literal
+
+    from rustfava.beans.abc import Directive
+    from rustfava.beans.abc import Meta
+    from rustfava.core.tree import TreeNode
+
+
+def get_last_entry(
+    txn_postings: Sequence[Directive | TransactionPosting],
+) -> Directive | None:
+    """Last entry."""
+    for txn_posting in reversed(txn_postings):
+        if isinstance(txn_posting, TransactionPosting):
+            transaction = txn_posting.transaction
+            if transaction.flag != FLAG_UNREALIZED:
+                return transaction
+        else:
+            return txn_posting
+    return None
+
+
+def uptodate_status(
+    txn_postings: Sequence[Directive | TransactionPosting],
+) -> Literal["green", "yellow", "red"] | None:
+    """Status of the last balance or transaction.
+
+    Args:
+        txn_postings: The TransactionPosting for the account.
+
+    Returns:
+        A status string for the last balance or transaction of the account.
+
+        - 'green':  A balance check that passed.
+        - 'red':    A balance check that failed.
+        - 'yellow': Not a balance check.
+    """
+    for txn_posting in reversed(txn_postings):
+        if isinstance(txn_posting, Balance):
+            return "red" if txn_posting.diff_amount else "green"
+        if (
+            isinstance(txn_posting, TransactionPosting)
+            and txn_posting.transaction.flag != FLAG_UNREALIZED
+        ):
+            return "yellow"
+    return None
+
+
+def balance_string(tree_node: TreeNode) -> str:
+    """Balance directive for the given account for today."""
+    account = tree_node.name
+    today = str(local_today())
+    res = ""
+    for currency, number in UNITS.apply(tree_node.balance).items():
+        res += f"{today} balance {account:<28} {number:>15} {currency}\n"
+    return res
+
+
+@dataclass(frozen=True)
+class LastEntry:
+    """Date and hash of the last entry for an account."""
+
+    #: The entry date.
+    date: datetime.date
+
+    #: The entry hash.
+    entry_hash: str
+
+
+@dataclass
+class AccountData:
+    """Holds information about an account."""
+
+    #: The date on which this account is closed (or datetime.date.max).
+    close_date: datetime.date | None = None
+
+    #: The metadata of the Open entry of this account.
+    meta: Meta = field(default_factory=dict)
+
+    #: Uptodate status. Is only computed if the account has a
+    #: "fava-uptodate-indication" meta attribute.
+    uptodate_status: Literal["green", "yellow", "red"] | None = None
+
+    #: Balance directive if this account has an uptodate status.
+    balance_string: str | None = None
+
+    #: The last entry of the account (unless it is a close Entry)
+    last_entry: LastEntry | None = None
+
+
+class AccountDict(FavaModule, dict[str, AccountData]):
+    """Account info dictionary."""
+
+    EMPTY = AccountData()
+
+    def __missing__(self, key: str) -> AccountData:
+        return self.EMPTY
+
+    def setdefault(
+        self,
+        key: str,
+        _: AccountData | None = None,
+    ) -> AccountData:
+        """Get the account of the given name, insert one if it is missing."""
+        if key not in self:
+            self[key] = AccountData()
+        return self[key]
+
+    def load_file(self) -> None:  # noqa: D102
+        self.clear()
+        entries_by_account = group_entries_by_account(self.ledger.all_entries)
+        tree = Tree(self.ledger.all_entries)
+        for open_entry in self.ledger.all_entries_by_type.Open:
+            meta = open_entry.meta
+            account_data = self.setdefault(open_entry.account)
+            account_data.meta = meta
+
+            txn_postings = entries_by_account[open_entry.account]
+            last = get_last_entry(txn_postings)
+            if last is not None and not isinstance(last, Close):
+                account_data.last_entry = LastEntry(
+                    date=last.date,
+                    entry_hash=hash_entry(last),
+                )
+            if meta.get("fava-uptodate-indication"):
+                account_data.uptodate_status = uptodate_status(txn_postings)
+                if account_data.uptodate_status != "green":
+                    account_data.balance_string = balance_string(
+                        tree.get(open_entry.account),
+                    )
+        for close in self.ledger.all_entries_by_type.Close:
+            self.setdefault(close.account).close_date = close.date
+
+    def all_balance_directives(self) -> str:
+        """Balance directives for all accounts."""
+        return "".join(
+            account_details.balance_string
+            for account_details in self.values()
+            if account_details.balance_string
+        )

rustfava/core/attributes.py

@@ -0,0 +1,145 @@
+"""Attributes for auto-completion."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rustfava.core.module_base import FavaModule
+from rustfava.util.date import END_OF_YEAR
+from rustfava.util.ranking import ExponentialDecayRanker
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Directive
+    from rustfava.beans.abc import Transaction
+    from rustfava.core import RustfavaLedger
+    from rustfava.util.date import FiscalYearEnd
+
+
+def get_active_years(
+    entries: Sequence[Directive],
+    fye: FiscalYearEnd,
+) -> list[str]:
+    """Return active years, with support for fiscal years.
+
+    Args:
+        entries: Beancount entries
+        fye: fiscal year end
+
+    Returns:
+        A reverse sorted list of years or fiscal years that occur in the
+        entries.
+    """
+    years = []
+    if fye == END_OF_YEAR:
+        prev_year = None
+        for entry in entries:
+            year = entry.date.year
+            if year != prev_year:
+                prev_year = year
+                years.append(year)
+        return [f"{year}" for year in reversed(years)]
+    month = fye.month
+    day = fye.day
+    prev_year = None
+    for entry in entries:
+        date = entry.date
+        year = (
+            entry.date.year + 1
+            if date.month > month or (date.month == month and date.day > day)
+            else entry.date.year
+        )
+        if year != prev_year:
+            prev_year = year
+            years.append(year)
+    return [f"FY{year}" for year in reversed(years)]
+
+
+class AttributesModule(FavaModule):
+    """Some attributes of the ledger (mostly for auto-completion)."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        self.accounts: Sequence[str] = []
+        self.currencies: Sequence[str] = []
+        self.payees: Sequence[str] = []
+        self.links: Sequence[str] = []
+        self.tags: Sequence[str] = []
+        self.years: Sequence[str] = []
+
+    def load_file(self) -> None:  # noqa: D102
+        all_entries = self.ledger.all_entries
+
+        all_links = set()
+        all_tags = set()
+        for entry in all_entries:
+            links = getattr(entry, "links", None)
+            if links is not None:
+                all_links.update(links)
+            tags = getattr(entry, "tags", None)
+            if tags is not None:
+                all_tags.update(tags)
+        self.links = sorted(all_links)
+        self.tags = sorted(all_tags)
+
+        self.years = get_active_years(
+            all_entries,
+            self.ledger.fava_options.fiscal_year_end,
+        )
+
+        account_ranker = ExponentialDecayRanker(
+            sorted(self.ledger.accounts.keys()),
+        )
+        currency_ranker = ExponentialDecayRanker()
+        payee_ranker = ExponentialDecayRanker()
+
+        for txn in self.ledger.all_entries_by_type.Transaction:
+            if txn.payee:
+                payee_ranker.update(txn.payee, txn.date)
+            for posting in txn.postings:
+                account_ranker.update(posting.account, txn.date)
+                # Skip postings with missing units (can happen with parse errors)
+                if posting.units is not None:
+                    currency_ranker.update(posting.units.currency, txn.date)
+                if posting.cost and posting.cost.currency is not None:
+                    currency_ranker.update(posting.cost.currency, txn.date)
+
+        self.accounts = account_ranker.sort()
+        self.currencies = currency_ranker.sort()
+        self.payees = payee_ranker.sort()
+
+    def payee_accounts(self, payee: str) -> Sequence[str]:
+        """Rank accounts for the given payee."""
+        account_ranker = ExponentialDecayRanker(self.accounts)
+        transactions = self.ledger.all_entries_by_type.Transaction
+        for txn in transactions:
+            if txn.payee == payee:
+                for posting in txn.postings:
+                    account_ranker.update(posting.account, txn.date)
+        return account_ranker.sort()
+
+    def payee_transaction(self, payee: str) -> Transaction | None:
+        """Get the last transaction for a payee."""
+        transactions = self.ledger.all_entries_by_type.Transaction
+        for txn in reversed(transactions):
+            if txn.payee == payee:
+                return txn
+        return None
+
+    def narration_transaction(self, narration: str) -> Transaction | None:
+        """Get the last transaction for a narration."""
+        transactions = self.ledger.all_entries_by_type.Transaction
+        for txn in reversed(transactions):
+            if txn.narration == narration:
+                return txn
+        return None
+
+    @property
+    def narrations(self) -> Sequence[str]:
+        """Get the narrations of all transactions."""
+        narration_ranker = ExponentialDecayRanker()
+        for txn in self.ledger.all_entries_by_type.Transaction:
+            if txn.narration:
+                narration_ranker.update(txn.narration, txn.date)
+        return narration_ranker.sort()

rustfava/core/budgets.py

@@ -0,0 +1,207 @@
+"""Parsing and computing budgets."""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections import defaultdict
+from decimal import Decimal
+from typing import NamedTuple
+from typing import TYPE_CHECKING
+
+from rustfava.core.module_base import FavaModule
+from rustfava.helpers import BeancountError
+from rustfava.util.date import days_in_daterange
+from rustfava.util.date import INTERVALS
+
+if TYPE_CHECKING:  # pragma: no cover
+    import datetime
+    from collections.abc import Mapping
+    from collections.abc import Sequence
+
+    from rustfava.beans.abc import Custom
+    from rustfava.core import RustfavaLedger
+    from rustfava.util.date import Interval
+
+
+class Budget(NamedTuple):
+    """A budget entry."""
+
+    account: str
+    date_start: datetime.date
+    period: Interval
+    number: Decimal
+    currency: str
+
+
+BudgetDict = dict[str, list[Budget]]
+"""A map of account names to lists of budget entries."""
+
+
+class BudgetError(BeancountError):
+    """Error with a budget."""
+
+
+class BudgetModule(FavaModule):
+    """Parses budget entries."""
+
+    def __init__(self, ledger: RustfavaLedger) -> None:
+        super().__init__(ledger)
+        self._budget_entries: BudgetDict = {}
+        self.errors: Sequence[BudgetError] = []
+
+    def load_file(self) -> None:  # noqa: D102
+        self._budget_entries, self.errors = parse_budgets(
+            self.ledger.all_entries_by_type.Custom,
+        )
+
+    def calculate(
+        self,
+        account: str,
+        begin_date: datetime.date,
+        end_date: datetime.date,
+    ) -> Mapping[str, Decimal]:
+        """Calculate the budget for an account in an interval."""
+        return calculate_budget(
+            self._budget_entries,
+            account,
+            begin_date,
+            end_date,
+        )
+
+    def calculate_children(
+        self,
+        account: str,
+        begin_date: datetime.date,
+        end_date: datetime.date,
+    ) -> Mapping[str, Decimal]:
+        """Calculate the budget for an account including its children."""
+        return calculate_budget_children(
+            self._budget_entries,
+            account,
+            begin_date,
+            end_date,
+        )
+
+
+def parse_budgets(
+    custom_entries: Sequence[Custom],
+) -> tuple[BudgetDict, Sequence[BudgetError]]:
+    """Parse budget directives from custom entries.
+
+    Args:
+        custom_entries: the Custom entries to parse budgets from.
+
+    Returns:
+        A dict of accounts to lists of budgets.
+
+    Example:
+        2015-04-09 custom "budget" Expenses:Books "monthly" 20.00 EUR
+    """
+    budgets: BudgetDict = defaultdict(list)
+    errors = []
+
+    for entry in (entry for entry in custom_entries if entry.type == "budget"):
+        try:
+            interval = INTERVALS.get(str(entry.values[1].value).lower())
+            if not interval:
+                errors.append(
+                    BudgetError(
+                        entry.meta,
+                        "Invalid interval for budget entry",
+                        entry,
+                    ),
+                )
+                continue
+            budget = Budget(
+                entry.values[0].value,
+                entry.date,
+                interval,
+                entry.values[2].value.number,
+                entry.values[2].value.currency,
+            )
+            budgets[budget.account].append(budget)
+        except (IndexError, TypeError):
+            errors.append(
+                BudgetError(entry.meta, "Failed to parse budget entry", entry),
+            )
+
+    return budgets, errors
+
+
+def _matching_budgets(
+    budgets: Sequence[Budget],
+    date_active: datetime.date,
+) -> Mapping[str, Budget]:
+    """Find matching budgets.
+
+    Returns:
+        The budget that is active on the specified date for the
+        specified account.
+    """
+    last_seen_budgets = {}
+    for budget in budgets:
+        if budget.date_start <= date_active:
+            last_seen_budgets[budget.currency] = budget
+        else:
+            break
+    return last_seen_budgets
+
+
+def calculate_budget(
+    budgets: BudgetDict,
+    account: str,
+    date_from: datetime.date,
+    date_to: datetime.date,
+) -> Mapping[str, Decimal]:
+    """Calculate budget for an account.
+
+    Args:
+        budgets: A list of :class:`Budget` entries.
+        account: An account name.
+        date_from: Starting date.
+        date_to: End date (exclusive).
+
+    Returns:
+        A dictionary of currency to Decimal with the budget for the
+        specified account and period.
+    """
+    budget_list = budgets.get(account, None)
+    if budget_list is None:
+        return {}
+
+    currency_dict: dict[str, Decimal] = defaultdict(Decimal)
+
+    for day in days_in_daterange(date_from, date_to):
+        matches = _matching_budgets(budget_list, day)
+        for budget in matches.values():
+            days_in_period = budget.period.number_of_days(day)
+            currency_dict[budget.currency] += budget.number / days_in_period
+    return dict(currency_dict)
+
+
+def calculate_budget_children(
+    budgets: BudgetDict,
+    account: str,
+    date_from: datetime.date,
+    date_to: datetime.date,
+) -> Mapping[str, Decimal]:
+    """Calculate budget for an account including budgets of its children.
+
+    Args:
+        budgets: A list of :class:`Budget` entries.
+        account: An account name.
+        date_from: Starting date.
+        date_to: End date (exclusive).
+
+    Returns:
+        A dictionary of currency to Decimal with the budget for the
+        specified account and period.
+    """
+    currency_dict: dict[str, Decimal] = Counter()  # type: ignore[assignment]
+
+    for child in budgets:
+        if child.startswith(account):
+            currency_dict.update(
+                calculate_budget(budgets, child, date_from, date_to),
+            )
+    return dict(currency_dict)