runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/period/__init__.py

@@ -0,0 +1,9 @@
+"""A quarter's books as a package an accountant or auditor can work from.
+
+Built from one read of the ledger by pure functions, so every file agrees with
+every other and a rebuild of the same quarter reproduces the same bytes.
+"""
+
+
+class PeriodError(ValueError):
+    """The package cannot be built as asked. The message names every offending item."""

runningtab/period/balances.py

@@ -0,0 +1,283 @@
+"""The trial balance, and the statements and listings derived from the same rows.
+
+Opening balances follow ERPNext's own Trial Balance report so the two can be
+compared account by account: a balance-sheet account opens with everything
+before the quarter, a P&L account with everything since the fiscal year
+began. P&L from earlier years that no Period Closing Voucher closed is carried
+as one line, so the trial balance and balance sheet balance without one.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from collections import defaultdict
+from collections.abc import Sequence
+from decimal import Decimal
+
+from icedcoffee_sync.apply.model import DesiredAccount
+
+from runningtab.period import PeriodError
+from runningtab.period.csvfmt import money, render_csv
+from runningtab.period.ledger import AccountIndex, GLRow, require_known_accounts
+from runningtab.period.quarter import FiscalYear, Quarter
+
+PRIOR_YEAR_LABEL = "Prior-year earnings, unclosed"
+CURRENT_YEAR_LABEL = "Current-year earnings"
+_ZERO = Decimal(0)
+
+
+def is_profit_and_loss(account: DesiredAccount) -> bool:
+    return account.root_type in ("Income", "Expense")
+
+
+@dataclasses.dataclass(frozen=True)
+class AccountBalance:
+    """One postable account's figures for the quarter. Every figure is debit minus credit."""
+
+    account: DesiredAccount
+    opening: Decimal
+    period_debit: Decimal
+    period_credit: Decimal
+
+    @property
+    def closing(self) -> Decimal:
+        return self.opening + self.period_debit - self.period_credit
+
+
+@dataclasses.dataclass(frozen=True)
+class TrialBalance:
+    quarter: Quarter
+    fiscal_year: FiscalYear
+    lines: tuple[AccountBalance, ...]
+    prior_year_unclosed: Decimal
+
+    def _line(self, number: str) -> AccountBalance:
+        for line in self.lines:
+            if line.account.number == number:
+                return line
+        raise KeyError(number)
+
+    def closing(self, number: str) -> Decimal:
+        return self._line(number).closing
+
+    def opening(self, number: str) -> Decimal:
+        return self._line(number).opening
+
+
+def _refuse_out_of_scope(rows: Sequence[GLRow], index: AccountIndex, quarter: Quarter, fy: FiscalYear) -> None:
+    """Refuse rows this trial balance cannot place without double-counting or reading past the quarter."""
+    pcv = sorted({r.voucher_no for r in rows if r.voucher_type == "Period Closing Voucher"})
+    if pcv:
+        raise PeriodError(f"Period Closing Vouchers are not handled yet: {', '.join(pcv)}")
+    odd = sorted(
+        r.name for r in rows if r.is_opening and is_profit_and_loss(index[r.account]) and r.posting_date >= fy.start
+    )
+    if odd:
+        raise PeriodError(f"P&L entries marked as opening inside the fiscal year are not handled: {', '.join(odd)}")
+    # A balance-sheet account's `is_opening` row dated inside the quarter is
+    # ERPNext's own opening-balance convention (see the module docstring),
+    # but `journal_entries` and `general_ledger_csv` both take every voucher
+    # dated in the quarter as period activity regardless of `is_opening` --
+    # so this row would land in both the opening balance here and the
+    # period's general ledger and QBO kit. Refuse rather than silently
+    # double-count it.
+    double_counted = sorted(
+        (
+            r
+            for r in rows
+            if r.is_opening
+            and not is_profit_and_loss(index[r.account])
+            and quarter.start <= r.posting_date <= quarter.end
+        ),
+        key=lambda r: r.name,
+    )
+    if double_counted:
+        names = ", ".join(r.name for r in double_counted)
+        vouchers = ", ".join(sorted({r.voucher_no for r in double_counted}))
+        day_before = quarter.start - dt.timedelta(days=1)
+        raise PeriodError(
+            f"opening entries dated inside {quarter.label} would be counted both as an opening balance and "
+            f"as period activity: GL Entries {names} (voucher(s) {vouchers}); opening entries must be dated "
+            f"on or before {day_before.isoformat()}, the day before {quarter.label} starts"
+        )
+    future = [r for r in rows if r.posting_date > quarter.end]
+    if future:
+        latest = max(r.posting_date for r in future)
+        raise PeriodError(
+            f"{len(future)} GL Entries are dated after {quarter.label} ends ({quarter.end.isoformat()}); "
+            f"the latest is dated {latest.isoformat()}. A caller must filter its read to the quarter's end; "
+            "this refusal does not depend on it."
+        )
+
+
+def trial_balance(
+    rows: Sequence[GLRow], index: AccountIndex, quarter: Quarter, fiscal_year: FiscalYear
+) -> TrialBalance:
+    require_known_accounts(rows, index)
+    _refuse_out_of_scope(rows, index, quarter, fiscal_year)
+    opening: dict[str, Decimal] = defaultdict(Decimal)
+    debit: dict[str, Decimal] = defaultdict(Decimal)
+    credit: dict[str, Decimal] = defaultdict(Decimal)
+    prior = _ZERO
+    for row in rows:
+        account = index[row.account]
+        in_quarter = quarter.start <= row.posting_date <= quarter.end
+        if is_profit_and_loss(account):
+            if row.posting_date < fiscal_year.start:
+                prior += row.net
+            elif in_quarter:
+                debit[account.number] += row.debit
+                credit[account.number] += row.credit
+            else:
+                opening[account.number] += row.net
+        elif in_quarter and not row.is_opening:
+            debit[account.number] += row.debit
+            credit[account.number] += row.credit
+        else:
+            opening[account.number] += row.net
+    postable = sorted((a for a in index.values() if not a.is_group), key=lambda a: a.number)
+    lines = tuple(AccountBalance(a, opening[a.number], debit[a.number], credit[a.number]) for a in postable)
+    total = sum((line.closing for line in lines), _ZERO) + prior
+    if total != 0:
+        raise PeriodError(
+            f"the ledger read does not balance: debits exceed credits by {total}; "
+            "the read was short or a voucher is one-sided"
+        )
+    return TrialBalance(quarter, fiscal_year, lines, prior)
+
+
+def _split(net: Decimal) -> tuple[str, str]:
+    return (money(net), money(_ZERO)) if net >= 0 else (money(_ZERO), money(-net))
+
+
+def trial_balance_csv(tb: TrialBalance) -> bytes:
+    """One row per postable account by number, then the prior-year line. Net presentation."""
+    header = [
+        "number",
+        "name",
+        "root_type",
+        "opening_debit",
+        "opening_credit",
+        "period_debit",
+        "period_credit",
+        "closing_debit",
+        "closing_credit",
+    ]
+    rows = [
+        [
+            line.account.number,
+            line.account.name,
+            line.account.root_type,
+            *_split(line.opening),
+            money(line.period_debit),
+            money(line.period_credit),
+            *_split(line.closing),
+        ]
+        for line in tb.lines
+    ]
+    rows.append([
+        "",
+        PRIOR_YEAR_LABEL,
+        "Equity",
+        *_split(tb.prior_year_unclosed),
+        money(_ZERO),
+        money(_ZERO),
+        *_split(tb.prior_year_unclosed),
+    ])
+    return render_csv(header, rows)
+
+
+def profit_and_loss_csv(tb: TrialBalance) -> bytes:
+    """Income then expense accounts by number; amounts in their natural sign (income and expense both positive)."""
+    header = ["number", "name", "root_type", "quarter", "year_to_date"]
+    rows: list[list[str]] = []
+    totals = {"Income": [_ZERO, _ZERO], "Expense": [_ZERO, _ZERO]}
+    for root in ("Income", "Expense"):
+        sign = -1 if root == "Income" else 1
+        for line in tb.lines:
+            if line.account.root_type != root:
+                continue
+            quarter = sign * (line.period_debit - line.period_credit)
+            ytd = sign * line.closing
+            totals[root][0] += quarter
+            totals[root][1] += ytd
+            rows.append([line.account.number, line.account.name, root, money(quarter), money(ytd)])
+        rows.append(["", f"Total {root.lower()}", root, money(totals[root][0]), money(totals[root][1])])
+    net_q = totals["Income"][0] - totals["Expense"][0]
+    net_y = totals["Income"][1] - totals["Expense"][1]
+    rows.append(["", "Net income", "", money(net_q), money(net_y)])
+    return render_csv(header, rows)
+
+
+def balance_sheet_csv(tb: TrialBalance) -> bytes:
+    """As of the quarter's end. Assets debit-positive; liabilities and equity credit-positive."""
+    header = ["number", "name", "root_type", "amount"]
+    rows: list[list[str]] = []
+    assets = sum((line.closing for line in tb.lines if line.account.root_type == "Asset"), _ZERO)
+    for line in tb.lines:
+        if line.account.root_type == "Asset":
+            rows.append([line.account.number, line.account.name, "Asset", money(line.closing)])
+    rows.append(["", "Total assets", "Asset", money(assets)])
+    other = _ZERO
+    for root in ("Liability", "Equity"):
+        for line in tb.lines:
+            if line.account.root_type == root:
+                other += -line.closing
+                rows.append([line.account.number, line.account.name, root, money(-line.closing)])
+    current = -sum((line.closing for line in tb.lines if is_profit_and_loss(line.account)), _ZERO)
+    prior = -tb.prior_year_unclosed
+    rows.append(["", CURRENT_YEAR_LABEL, "Equity", money(current)])
+    rows.append(["", PRIOR_YEAR_LABEL, "Equity", money(prior)])
+    other += current + prior
+    rows.append(["", "Total liabilities and equity", "", money(other)])
+    if assets != other:
+        raise PeriodError(f"the balance sheet does not balance: assets {assets}, liabilities and equity {other}")
+    return render_csv(header, rows)
+
+
+def chart_of_accounts_csv(chart: Sequence[DesiredAccount]) -> bytes:
+    """Every account in chart.coa file order: number, name, parent, root type, account type, group."""
+    header = ["number", "name", "parent", "root_type", "account_type", "is_group"]
+    rows = [
+        [a.number, a.name, a.parent_number or "", a.root_type, a.account_type or "", "1" if a.is_group else "0"]
+        for a in chart
+    ]
+    return render_csv(header, rows)
+
+
+def general_ledger_csv(rows: Sequence[GLRow], index: AccountIndex, quarter: Quarter) -> bytes:
+    """Every GL Entry dated in the quarter, in ledger read order."""
+    header = [
+        "posting_date",
+        "voucher_type",
+        "voucher_no",
+        "number",
+        "account",
+        "party_type",
+        "party",
+        "debit",
+        "credit",
+        "against_voucher",
+        "remarks",
+        "gl_entry",
+    ]
+    out = [
+        [
+            r.posting_date.isoformat(),
+            r.voucher_type,
+            r.voucher_no,
+            index[r.account].number,
+            index[r.account].name,
+            r.party_type or "",
+            r.party or "",
+            money(r.debit),
+            money(r.credit),
+            r.against_voucher or "",
+            r.remarks,
+            r.name,
+        ]
+        for r in rows
+        if quarter.start <= r.posting_date <= quarter.end
+    ]
+    return render_csv(header, out)

runningtab/period/bank.py

@@ -0,0 +1,154 @@
+"""The bank's balance at the quarter's end, next to the ledger's, per Mercury account."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from collections.abc import Sequence
+from decimal import Decimal
+from typing import Protocol
+
+from runningtab import health
+from runningtab.health import AccountLedger, MercuryReader, reconcile, unclassified_statuses
+from runningtab.mercury.mapping import Mapping
+from runningtab.period import PeriodError
+from runningtab.period.csvfmt import money, render_csv
+
+
+class _Closings(Protocol):
+    def closing(self, number: str) -> Decimal: ...
+
+
+@dataclasses.dataclass(frozen=True)
+class BankLine:
+    label: str
+    account_id: str
+    number: str
+    bank: Decimal
+    ledger: Decimal
+
+    @property
+    def difference(self) -> Decimal:
+        return self.bank - self.ledger
+
+
+def read_ledgers(client: MercuryReader) -> list[AccountLedger]:
+    """Every Mercury ledger, refusing an account with no inception date on record.
+
+    `health.read_ledgers` passes `start=account.created_at` to the per-account
+    transaction read; when that is `None`, Mercury's own endpoint default --
+    the last 30 days -- silently stands in, so an account open longer than
+    that reads short. `runningtab.health`'s balance invariant does not catch it:
+    it only proves the settled sum equals `currentBalance`, never that every
+    transaction was actually read, and a short read whose missing rows net to
+    zero passes it clean. The quarter-end balance `bank_reconciliation` builds
+    from that short ledger would then be wrong with nothing to say so.
+
+    A period-side wrapper around `health.read_ledgers` rather than a change to
+    it: `runningtab health`'s own report is unaffected by this refusal on purpose
+    -- there is nothing wrong with running health against an account still
+    missing its inception date, only with building a quarter's historical
+    balance from one.
+
+    `client.accounts()`/`client.credit_accounts()` are fetched once, here,
+    and passed straight into `health.read_ledgers` rather than read again --
+    the inception-date check and the ledger build need the same two lists.
+    """
+    accounts = client.accounts()
+    credit_accounts = client.credit_accounts()
+    missing = sorted(
+        f"{account.label} ({account.id})" for account in (*accounts, *credit_accounts) if account.created_at is None
+    )
+    if missing:
+        raise PeriodError(
+            "Mercury account(s) with no inception date on record: "
+            + ", ".join(missing)
+            + "; the transaction read would silently default to the last 30 days"
+        )
+    return health.read_ledgers(client, accounts=accounts, credit_accounts=credit_accounts)
+
+
+def bank_balance_through(ledger: AccountLedger, end: dt.date) -> Decimal:
+    """Settled transactions dated on or before `end`, by the date the ingest books them."""
+    return sum((t.amount for t in ledger.transactions if t.is_postable and t.accounting_date <= end), Decimal(0))
+
+
+def bank_reconciliation(
+    ledgers: Sequence[AccountLedger], mapping: Mapping, tb: _Closings, end: dt.date
+) -> list[BankLine]:
+    """Each Mercury account's balance at `end` next to the chart account's closing balance.
+
+    Refuses unless the balance invariant holds for every account: a balance
+    at a past date built from a short read cannot be trusted, and an account
+    `mercury.toml` does not map has nowhere in the chart to compare against.
+    Also refuses when a transaction carries a status nobody has classified
+    (`runningtab.health.unclassified`): such a row would be silently excluded from
+    `bank_balance_through` with no established accounting treatment, and a
+    quiet exclusion is a wrong balance nobody can see. Also refuses when two
+    Mercury accounts map to the same chart account: each would be compared
+    against that one account's whole closing balance rather than its own
+    share of it, producing a false difference for at least one of them. Also
+    refuses when `mercury.toml` maps an account to a number that is not a
+    postable account in `tb` (a group account, say): `TrialBalance.closing`
+    has no line for it and would otherwise fail with a bare `KeyError`. Every
+    refusal names the offending account rather than failing silently.
+    """
+    if not ledgers:
+        raise PeriodError("Mercury returned no accounts; a short read, not an empty bank")
+    failing = [r.label for r in reconcile(ledgers) if not r.reconciles]
+    if failing:
+        raise PeriodError(
+            "the balance invariant fails for "
+            + ", ".join(sorted(failing))
+            + "; a balance at a past date cannot be trusted until `runningtab health` passes"
+        )
+    unclassified_by_account = {
+        ledger.label: statuses for ledger in ledgers if (statuses := unclassified_statuses([ledger]))
+    }
+    if unclassified_by_account:
+        named = ", ".join(
+            f"{label} ({', '.join(f'{count} {status}' for status, count in statuses.items())})"
+            for label, statuses in sorted(unclassified_by_account.items())
+        )
+        raise PeriodError(
+            "transaction status(es) nobody has classified would be silently excluded from the historical "
+            f"balance with unknown accounting treatment: {named}"
+        )
+    maybe_numbers = {
+        ledger.account_id: mapping.account_for_mercury_account(ledger.account_id, ledger.label) for ledger in ledgers
+    }
+    unmapped = sorted(account_id for account_id, number in maybe_numbers.items() if number is None)
+    if unmapped:
+        raise PeriodError(f"mercury.toml maps no chart account for Mercury account(s): {', '.join(unmapped)}")
+    numbers: dict[str, str] = {account_id: number for account_id, number in maybe_numbers.items() if number is not None}
+    accounts_by_number: dict[str, list[AccountLedger]] = {}
+    for ledger in ledgers:
+        accounts_by_number.setdefault(numbers[ledger.account_id], []).append(ledger)
+    duplicated = sorted(number for number, accounts in accounts_by_number.items() if len(accounts) > 1)
+    if duplicated:
+        named = "; ".join(
+            f"{number} ({', '.join(f'{a.label} ({a.account_id})' for a in accounts_by_number[number])})"
+            for number in duplicated
+        )
+        raise PeriodError(f"mercury.toml maps more than one Mercury account to chart account: {named}")
+    lines = []
+    for ledger in ledgers:
+        number = numbers[ledger.account_id]
+        try:
+            closing = tb.closing(number)
+        except KeyError:
+            raise PeriodError(
+                f"mercury.toml maps Mercury account {ledger.label} ({ledger.account_id}) to {number}, "
+                "which is not a postable account in the trial balance"
+            ) from None
+        lines.append(BankLine(ledger.label, ledger.account_id, number, bank_balance_through(ledger, end), closing))
+    return sorted(lines, key=lambda line: line.number)
+
+
+def bank_reconciliation_csv(lines: Sequence[BankLine]) -> bytes:
+    header = ["number", "account", "mercury_account", "bank_balance", "ledger_balance", "difference"]
+    rows = [
+        [line.number, line.label, line.account_id, money(line.bank), money(line.ledger), money(line.difference)]
+        for line in lines
+    ]
+    return render_csv(header, rows)