runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/period/lock.py

@@ -0,0 +1,294 @@
+"""Books Closed Through: read it, read who moved it and when, and move it forward only.
+
+Frappe records every field change to a document as a `Version`
+(`frappe/core/doctype/version/version.py`): its `data` field is a JSON string
+whose `"changed"` key lists `[fieldname, old, new]` triples for every field
+that save touched. `lock_history` filters that down to `accounts_frozen_till_date`
+alone -- the field the fence in `runningtab.period.fence` protects -- and ignores
+every other change a Company save might carry, `role_allowed_for_frozen_entries`
+included.
+
+`get_diff` (same file) writes a changed Date field's old/new through
+`get_formatted()` -> `formatdate()` (`frappe/utils/data.py`) before it ever
+reaches `data` -- i.e. in the *site's* `date_format` system setting, not ISO.
+A live site can be, and by default is, set to `yyyy-mm-dd`, but nothing
+guarantees it stays that way, so `_parse_version_date` tries ISO first and
+falls back to every other format System Settings' `date_format` select
+offers (`frappe/core/doctype/system_settings/system_settings.json`), reading
+the site's actual setting only if two of those formats disagree on the same
+text. `Company` itself is not affected: an ordinary document read returns
+the raw stored field value, never a formatted one, so `read_lock` still
+parses it as plain ISO.
+
+The Version doctype ships permission to `System Manager` and `Administrator`
+only (`frappe/core/doctype/version/version.json`); neither is a role the books
+reader inherits, so `runningtab.access.READER_GRANTS` carries an explicit read
+grant on `Version` to let `status`/`health` show who reopened a quarter.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import json
+from typing import Any, Protocol
+
+from runningtab.period import PeriodError
+from runningtab.period.fence import LOCK_FIELDS
+from runningtab.site import Profile
+
+COMPANY = "Company"
+_SYSTEM_SETTINGS = "System Settings"
+
+# System Settings' own `date_format` options (system_settings.json), less
+# `yyyy-mm-dd` -- that one is ISO, and `_iso_date` already covers it.
+_OTHER_DATE_FORMATS: dict[str, str] = {
+    "dd-mm-yyyy": "%d-%m-%Y",
+    "mm-dd-yyyy": "%m-%d-%Y",
+    "dd/mm/yyyy": "%d/%m/%Y",
+    "mm/dd/yyyy": "%m/%d/%Y",
+    "dd.mm.yyyy": "%d.%m.%Y",
+}
+
+
+class _Reader(Protocol):
+    """What `read_lock` and `lock_history` need: read Company, read its Version history."""
+
+    def get(self, doctype: str, name: str) -> Any: ...
+    def iter_all(self, doctype: str, **kwargs: Any) -> Any: ...
+
+
+class _Admin(Protocol):
+    """What `set_closed_through` needs: the reader's slice, plus writing Company."""
+
+    def get(self, doctype: str, name: str) -> Any: ...
+    def update(self, doctype: str, name: str, doc: dict[str, Any]) -> Any: ...
+    def iter_all(self, doctype: str, **kwargs: Any) -> Any: ...
+
+
+@dataclasses.dataclass(frozen=True)
+class LockState:
+    """Company's close lock, as it stands right now."""
+
+    closed_through: dt.date | None
+    bypass_role: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class LockChange:
+    """One Version's edit to `accounts_frozen_till_date`, decoded.
+
+    `old`/`new` are the decoded dates; `old_text`/`new_text` are exactly what
+    Frappe recorded, unparsed -- so a person can always see the raw text
+    behind a decode, whether or not it parsed cleanly.
+    """
+
+    version: str
+    at: dt.datetime
+    by: str
+    old: dt.date | None
+    new: dt.date | None
+    old_text: str
+    new_text: str
+
+
+def _parse_date(value: Any) -> dt.date | None:
+    """A Company field value as Frappe's JSON client hands it back: a date string, empty string, or null.
+
+    An ordinary document read is never passed through `get_formatted()` --
+    that only happens inside `Version.get_diff` -- so this is plain ISO,
+    unlike `_parse_version_date` below.
+    """
+    if not value:
+        return None
+    return dt.date.fromisoformat(str(value))
+
+
+def read_lock(client: _Reader, company: str) -> LockState:
+    """Company's current `accounts_frozen_till_date` and `role_allowed_for_frozen_entries`."""
+    doc = client.get(COMPANY, company)
+    return LockState(closed_through=_parse_date(doc.get(LOCK_FIELDS[0])), bypass_role=doc.get(LOCK_FIELDS[1]) or None)
+
+
+_LOCK_FIELD_LABELS: dict[str, str] = {
+    LOCK_FIELDS[0]: "Books Closed Through",
+    LOCK_FIELDS[1]: "the frozen-entries role",
+}
+
+
+def read_visible_lock(client: _Reader, company: str, profile: Profile) -> LockState:
+    """`read_lock`, but refuses by name instead of reporting a false "unset" when this credential cannot see a
+    lock field at all.
+
+    Both `LOCK_FIELDS` sit at Company permlevel 1 (`runningtab.period.fence.install_fence`). Frappe's
+    `apply_fieldlevel_read_permissions` *deletes* a permlevel-1 field from a document response the
+    credential cannot read rather than returning it as null, so a credential never (re-)provisioned since
+    its grant was added -- or one whose `access provision` installed the fence and then failed -- gets a
+    doc with no `accounts_frozen_till_date`/`role_allowed_for_frozen_entries` key at all, indistinguishable,
+    to plain `dict.get`, from Company legitimately having neither set yet. `missing_grants_report` cannot
+    catch this either: it explicitly skips every grant above permlevel 0 (`runningtab.access.missing_grants_report`'s
+    own docstring), since `frappe.client.has_permission` has no permlevel of its own to ask about. Presence of
+    the key is the only thing that tells the two cases apart.
+
+    `profile` is the identity the caller reads as -- the reader for `period status`/`health`, the bot for the
+    Mercury ingest -- and names whose re-provision fixes it.
+    """
+    doc = client.get(COMPANY, company)
+    missing = [field for field in LOCK_FIELDS if field not in doc]
+    if missing:
+        labels = " and ".join(_LOCK_FIELD_LABELS[field] for field in missing)
+        raise PeriodError(
+            f"the {profile.value} credential cannot see {labels} on {company} (Company, permlevel 1); run "
+            f"`runningtab access provision --profile {profile.value}` with RUNNINGTAB_ADMIN_TOKEN set"
+        )
+    return LockState(closed_through=_parse_date(doc.get(LOCK_FIELDS[0])), bypass_role=doc.get(LOCK_FIELDS[1]) or None)
+
+
+def _raw_text(value: Any) -> str:
+    return str(value) if value else ""
+
+
+def _iso_date(text: str) -> dt.date | None:
+    try:
+        return dt.date.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def _formatted_dates(text: str) -> dict[str, dt.date]:
+    """{format name: parsed date} for every one of Frappe's other date_format options that matches `text`."""
+    matches: dict[str, dt.date] = {}
+    for name, pattern in _OTHER_DATE_FORMATS.items():
+        try:
+            matches[name] = dt.datetime.strptime(text, pattern).date()
+        except ValueError:
+            continue
+    return matches
+
+
+def _site_date_format(client: _Reader) -> str | None:
+    """The site's configured `date_format`, or None if it cannot be read.
+
+    Best-effort only, and only consulted to disambiguate a Version's
+    formatted text when more than one of Frappe's date formats parses it to
+    a different date. A reader credential may hold no grant on System
+    Settings at all; that failure (or any other) just means the format
+    could not be determined, not that reading history fails outright.
+    """
+    try:
+        settings = client.get(_SYSTEM_SETTINGS, _SYSTEM_SETTINGS)
+    except Exception:
+        return None
+    value = settings.get("date_format") if isinstance(settings, dict) else None
+    return str(value) if value else None
+
+
+def _parse_version_date(client: _Reader, version: str, label: str, text: str) -> dt.date | None:
+    """One raw old/new value from a Version's `data`, parsed defensively.
+
+    ISO is tried first -- the common case, and a live site's default. When
+    that fails, every other format System Settings' `date_format` offers is
+    tried; if exactly one produces a date, or several agree, that date wins.
+    If more than one disagrees, the site's actual `date_format` (read fresh,
+    not cached) breaks the tie; if that cannot be read either, or the text
+    matches nothing at all, this refuses by name rather than guess.
+    """
+    if not text:
+        return None
+    iso = _iso_date(text)
+    if iso is not None:
+        return iso
+    matches = _formatted_dates(text)
+    distinct = set(matches.values())
+    if len(distinct) == 1:
+        return distinct.pop()
+    if not distinct:
+        raise PeriodError(f"Version {version}: {label} {text!r} could not be parsed as a date")
+    site_format = _site_date_format(client)
+    if site_format in matches:
+        return matches[site_format]
+    raise PeriodError(
+        f"Version {version}: {label} {text!r} is ambiguous ({', '.join(sorted(matches))}) "
+        "and the site's date_format could not be determined"
+    )
+
+
+def _date_change(row: dict[str, Any]) -> tuple[Any, Any] | None:
+    """The `[old, new]` pair for the lock date field in one Version row's `data`, or None if it was not touched."""
+    data = json.loads(row["data"])
+    for fieldname, old, new in data.get("changed", []):
+        if fieldname == LOCK_FIELDS[0]:
+            return old, new
+    return None
+
+
+def lock_history(client: _Reader, company: str) -> list[LockChange]:
+    """Every Version of `company` that touched `accounts_frozen_till_date`, newest first.
+
+    Ordering is the server's: requested via `order_by`, not re-sorted here.
+    """
+    rows = client.iter_all(
+        "Version",
+        fields=["name", "owner", "creation", "data"],
+        filters=[["ref_doctype", "=", COMPANY], ["docname", "=", company]],
+        order_by="creation desc, name desc",
+    )
+    history: list[LockChange] = []
+    for row in rows:
+        change = _date_change(row)
+        if change is None:
+            continue
+        old_raw, new_raw = change
+        version = str(row["name"])
+        old_text, new_text = _raw_text(old_raw), _raw_text(new_raw)
+        history.append(
+            LockChange(
+                version=version,
+                at=dt.datetime.fromisoformat(str(row["creation"])),
+                by=str(row["owner"]),
+                old=_parse_version_date(client, version, "old value", old_text),
+                new=_parse_version_date(client, version, "new value", new_text),
+                old_text=old_text,
+                new_text=new_text,
+            )
+        )
+    return history
+
+
+def set_closed_through(admin: _Admin, company: str, date: dt.date) -> LockChange:
+    """Move Books Closed Through forward to `date`, refusing to move it backwards.
+
+    Reads the current value first, so a backwards request is refused before
+    anything is written. Confirmation never depends on parsing a Version's
+    formatted text back to a date -- that text is in the site's
+    `date_format`, not necessarily ISO, and comparing it to `date` is exactly
+    the bug this guards against. Instead: `read_lock` afterwards must show
+    `date` in Company's own (always-ISO) field, and a Version that did not
+    exist before this call must now touch `accounts_frozen_till_date` --
+    that Version, identified by name, is the one returned. Either check
+    failing refuses rather than report a change that cannot be shown to have
+    happened.
+    """
+    current = read_lock(admin, company)
+    if current.closed_through is not None and date < current.closed_through:
+        raise PeriodError(
+            f"Books Closed Through cannot move backwards: {company} is closed through "
+            f"{current.closed_through.isoformat()}, refusing {date.isoformat()}"
+        )
+    before = {change.version for change in lock_history(admin, company)}
+    admin.update(COMPANY, company, {LOCK_FIELDS[0]: date.isoformat()})
+
+    after = read_lock(admin, company)
+    if after.closed_through != date:
+        shown = after.closed_through.isoformat() if after.closed_through else "unset"
+        raise PeriodError(
+            f"{company}'s Books Closed Through was set to {date.isoformat()} but reading it back shows "
+            f"{shown} -- refusing to report success"
+        )
+
+    for change in lock_history(admin, company):
+        if change.version not in before:
+            return change
+    raise PeriodError(
+        f"{company}'s Books Closed Through was updated to {date.isoformat()} but left no Version audit trail"
+    )

runningtab/period/manifest.py

@@ -0,0 +1,259 @@
+"""`MANIFEST.md`: the one file in the package written for a person, not a program.
+
+Nothing parses it (`SHA256SUMS` and `period status` carry the machine-readable
+facts). The reader is an outside accountant or auditor who has never touched
+these books, so every section says what it means in plain sentences rather than
+pointing back at our own vocabulary.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from collections.abc import Sequence
+
+from runningtab.period import PeriodError
+from runningtab.period.bank import BankLine
+from runningtab.period.csvfmt import money
+from runningtab.period.qbo_map import QboMap
+from runningtab.period.quarter import FiscalYear, Quarter
+
+# One sentence per file, keyed by its exact path, or by a prefix for a family
+# of files (`qbo/journal-entries-NN.csv`, `documents/...`). Keeping this a
+# plain dict rather than a rule on the path means a new file with no entry
+# here raises `KeyError` in `_describe` instead of shipping undescribed.
+FILE_DESCRIPTIONS: dict[str, str] = {
+    "chart-of-accounts.csv": (
+        "Every account in the chart, with its number, name, parent, and type, as of this export."
+    ),
+    "trial-balance.csv": "Each account's opening balance, this quarter's debits and credits, and its closing balance.",
+    "general-ledger.csv": "Every transaction posted in the quarter, one line per debit or credit.",
+    "profit-and-loss.csv": "Income and expenses for the quarter and for the year to date.",
+    "balance-sheet.csv": "Assets, liabilities, and equity as of the quarter's end.",
+    "bank-reconciliation.csv": (
+        "Each bank account's balance next to its matching chart account's balance, and the difference between them."
+    ),
+    "open-receivables.csv": "What each customer owed as of the quarter's end.",
+    "open-payables.csv": "What we owed each vendor as of the quarter's end.",
+    "qbo/accounts.csv": (
+        "The chart accounts to create in QuickBooks Online, each with the Type and Detail Type QuickBooks requires."
+    ),
+    "qbo/customers.csv": "Every customer QuickBooks needs before the opening balances and journal entries import.",
+    "qbo/vendors.csv": "Every vendor QuickBooks needs before the opening balances and journal entries import.",
+    "qbo/opening-balances.csv": (
+        "Every account's balance the day before the quarter began, written as journal entries. "
+        "Import this file once only."
+    ),
+    "qbo/journal-entries-": (
+        "One QuickBooks journal entry per transaction posted in the quarter, split into files of at most "
+        "1,000 rows apiece."
+    ),
+    "documents/": "A receipt, invoice, or other file attached to a transaction or bank record dated in the quarter.",
+}
+
+
+# The final manifest's line naming the Company Version that locked the
+# quarter. `lock_version_of` reads it back; one constant keeps the two from
+# drifting apart.
+LOCK_RECORD_PREFIX = "- **Lock record:** Company Version `"
+
+
+def lock_version_of(manifest: str) -> str | None:
+    """The Company Version a final manifest says locked its quarter, or None when it records none (a draft)."""
+    for line in manifest.splitlines():
+        if line.startswith(LOCK_RECORD_PREFIX) and line.endswith("`"):
+            return line[len(LOCK_RECORD_PREFIX) : -1]
+    return None
+
+
+def _describe(path: str) -> str:
+    if path in FILE_DESCRIPTIONS:
+        return FILE_DESCRIPTIONS[path]
+    for prefix in ("qbo/journal-entries-", "documents/"):
+        if path.startswith(prefix):
+            return FILE_DESCRIPTIONS[prefix]
+    raise KeyError(path)
+
+
+@dataclasses.dataclass(frozen=True)
+class ManifestFacts:
+    quarter: Quarter
+    fiscal_year: FiscalYear
+    company: str
+    # `books.toml`'s name: the title says whose books these are.
+    books_name: str
+    site_url: str
+    chart_sha256: str
+    qmap: QboMap
+    generated_at: dt.datetime
+    generated_by: str
+    draft: bool
+    today: dt.date
+    bank: tuple[BankLine, ...]
+    split_vouchers: tuple[str, ...]
+    has_journals: bool
+    closed_by: str | None = None
+    lock_version: str | None = None
+    revision: int = 1
+
+
+def _title(facts: ManifestFacts) -> str:
+    suffix = " — DRAFT" if facts.draft else ""
+    return f"# {facts.books_name} books — {facts.quarter.label}{suffix}"
+
+
+def _facts_section(facts: ManifestFacts) -> str:
+    lines = [
+        f"- **Quarter:** {facts.quarter.label}, {facts.quarter.start.isoformat()} through "
+        f"{facts.quarter.end.isoformat()}",
+        f"- **Fiscal year:** {facts.fiscal_year.name}, {facts.fiscal_year.start.isoformat()} through "
+        f"{facts.fiscal_year.end.isoformat()}",
+        f"- **Company:** {facts.company}",
+        f"- **Site:** {facts.site_url}",
+        f"- **Chart of accounts:** `chart.coa`, SHA-256 `{facts.chart_sha256}`",
+        f"- **Generated:** {facts.generated_at.astimezone(dt.UTC).strftime('%Y-%m-%d %H:%M UTC')} "
+        f"by {facts.generated_by}",
+    ]
+    if not facts.draft:
+        lines.append(f"- **Closed by:** {facts.closed_by}")
+        lines.append(f"{LOCK_RECORD_PREFIX}{facts.lock_version}`")
+        lines.append(f"- **Revision:** {facts.revision}")
+    if facts.today <= facts.quarter.end:
+        lines.append("- **Note:** this quarter not yet ended; these figures will change before the quarter closes.")
+    return "\n".join(lines)
+
+
+def _files_section(files: dict[str, bytes]) -> str:
+    lines = [
+        "- **`MANIFEST.md`** — this document.",
+        "- **`SHA256SUMS`** — a checksum for every other file, to prove nothing in the package changed.",
+    ]
+    lines.extend(f"- **`{path}`** — {_describe(path)}" for path in sorted(files))
+    return "## Files\n\n" + "\n".join(lines)
+
+
+_SIGN_CONVENTIONS = (
+    "## Sign conventions\n\n"
+    "The trial balance and the general ledger split each account's net balance into separate debit and credit "
+    "columns: a debit balance appears in the debit column, a credit balance in the credit column. The profit and "
+    "loss statement shows income and expenses both as positive numbers. The balance sheet shows assets, "
+    "liabilities, and equity each as a positive number. A text cell in these CSVs that begins with a formula "
+    "character (`=`, `+`, `@`, or `-` unless it is a plain negative number) is prefixed with an apostrophe so a "
+    "spreadsheet shows it as text instead of running it as a formula. In the `qbo/` files, description text is "
+    "escaped the same way; an account or party name that begins with a formula character is refused instead, "
+    "since QuickBooks matches those by exact text and an added apostrophe would break the match."
+)
+
+
+def _bank_section(bank: Sequence[BankLine]) -> str:
+    if not bank:
+        return "## Bank reconciliation\n\nNo Mercury account was reconciled this quarter."
+    if all(line.difference == 0 for line in bank):
+        summary = "All accounts reconcile: the difference is zero for every Mercury account."
+    else:
+        summary = "Not every account reconciles. The differences below that are not zero appear in **bold**."
+    rows = [
+        "| Account | Mercury account | Bank balance | Ledger balance | Difference |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for line in bank:
+        diff = money(line.difference)
+        cell = f"**{diff}**" if line.difference != 0 else diff
+        rows.append(f"| {line.number} | {line.label} | {money(line.bank)} | {money(line.ledger)} | {cell} |")
+    return "## Bank reconciliation\n\n" + summary + "\n\n" + "\n".join(rows)
+
+
+def _qbo_section(facts: ManifestFacts) -> str:
+    qmap = facts.qmap
+    builtin_lines = "\n".join(
+        f"- Our account `{number}` maps onto QuickBooks's built-in `{entry.name}`."
+        for number, entry in sorted(qmap.builtin.items(), key=lambda pair: int(pair[0]))
+    )
+    account_count = len(qmap.accounts)
+    if facts.has_journals:
+        journal_note = "Every `qbo/journal-entries-NN.csv` file listed above belongs in this step."
+    else:
+        journal_note = "There is nothing to import here: no journal entries this quarter."
+    if facts.split_vouchers:
+        split_note = (
+            "The following vouchers touched more than one customer or vendor and were split into more than one "
+            "journal entry, balanced through the `QBO Import Clearing` account so the split nets to zero: "
+            + ", ".join(facts.split_vouchers)
+            + "."
+        )
+    else:
+        split_note = "No voucher needed splitting this quarter."
+    return (
+        "## Importing into QuickBooks Online\n\n"
+        "Import the files in this order:\n\n"
+        "1. `qbo/accounts.csv`\n"
+        "2. `qbo/customers.csv` and `qbo/vendors.csv`\n"
+        "3. Turn account numbers off in QuickBooks. Both `qbo/opening-balances.csv` and "
+        "`qbo/journal-entries-NN.csv` use the same journal import, so numbers must stay off through both steps "
+        "below; turn them back on only once step 5 finishes, as Intuit's own instructions say to.\n"
+        "4. `qbo/opening-balances.csv` — **first import only: importing it twice doubles every balance.**\n"
+        "5. `qbo/journal-entries-NN.csv`\n\n"
+        f"{journal_note}\n\n"
+        f"{split_note}\n\n"
+        f"This kit does not create new QuickBooks accounts for {len(qmap.builtin)} of ours. It posts to the "
+        "accounts QuickBooks already provides on every company:\n\n"
+        f"{builtin_lines}\n\n"
+        "Several details of this format are unverified against a real QuickBooks import. Check each on the "
+        "first import:\n\n"
+        "- The journal date is written as `YYYY-MM-DD` (ISO 8601).\n"
+        "- The unused side of each journal line — the Debits or Credits cell that does not apply to that "
+        "line — is left blank rather than filled with a zero.\n"
+        "- A split voucher's Journal No. can run to 21 characters (for example `ACC-PINV-2026-00001/2`); "
+        "check that QuickBooks accepts a Journal No. that long.\n"
+        "- Whether a party that is both a customer and a vendor imports under one name or two.\n\n"
+        f"`qbo/accounts.csv` assigns each account a QuickBooks Type and Detail Type chosen account by account "
+        f"in `qbo.toml`; nobody has yet checked the {account_count} choices against a live QuickBooks company. "
+        "Check them on the first import, and correct `qbo.toml` if any are wrong."
+    )
+
+
+_WHAT_THE_KIT_LEAVES_OUT = (
+    "## What the QBO kit leaves out\n\n"
+    "It carries every amount, account, date and party, and reproduces our trial balance. It does not carry: "
+    "the chart's hierarchy (group accounts and their nesting), ERPNext's voucher types (every voucher becomes "
+    "a QBO journal entry, not an invoice or bill), cost centres, the invoice-to-payment links, the split "
+    "vouchers' original single-entry shape, or attachments. Those stay in ERPNext and in the rest of the "
+    "package, which remain the record."
+)
+
+
+_VERIFYING_THIS_PACKAGE = (
+    "## Verifying this package\n\n"
+    "From inside this directory, run `sha256sum -c SHA256SUMS`. Every file it lists should print `OK`. "
+    "`SHA256SUMS` covers every file in the package except this one: `MANIFEST.md` records the moment it was "
+    "generated, so a checksum that covered it would never match between two otherwise identical builds. "
+    "After a close, `runningtab period status` rebuilds this quarter's package from the ledger and compares it "
+    "against this one; a bank transaction that settles later but is dated inside this quarter will show up "
+    "there as a change to `bank-reconciliation.csv`."
+)
+
+
+def render_manifest(facts: ManifestFacts, files: dict[str, bytes]) -> bytes:
+    """`MANIFEST.md`, as UTF-8 Markdown ending in a newline.
+
+    A final manifest (`draft=False`) with `closed_by` or `lock_version`
+    still `None` would print "Closed by: None" or a backtick-quoted `None`
+    as the lock's own Version -- a confident wrong answer about who closed
+    the quarter, printed into the one record an outside accountant is
+    handed. Refusing here means that can never reach a package.
+    """
+    if not facts.draft and (facts.closed_by is None or facts.lock_version is None):
+        raise PeriodError(
+            "a final manifest needs closed_by and lock_version; render_manifest was given draft=False without them"
+        )
+    sections = [
+        _title(facts),
+        _facts_section(facts),
+        _files_section(files),
+        _SIGN_CONVENTIONS,
+        _bank_section(facts.bank),
+        _qbo_section(facts),
+        _WHAT_THE_KIT_LEAVES_OUT,
+        _VERIFYING_THIS_PACKAGE,
+    ]
+    return ("\n\n".join(sections) + "\n").encode("utf-8")

runningtab/period/open_items.py

@@ -0,0 +1,84 @@
+"""Open receivables and payables at a date, by party and by the document each entry settles.
+
+A trial balance carries one balance per account; a person working from it --
+or QBO, which demands a customer or vendor on every AR and AP line -- needs
+that balance split by who owes it and for what.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from collections import defaultdict
+from collections.abc import Sequence
+from decimal import Decimal
+from typing import Literal
+
+from runningtab.period import PeriodError
+from runningtab.period.balances import TrialBalance
+from runningtab.period.csvfmt import money, render_csv
+from runningtab.period.ledger import AccountIndex, GLRow
+
+Kind = Literal["Receivable", "Payable"]
+
+
+@dataclasses.dataclass(frozen=True)
+class OpenItem:
+    party_type: str
+    party: str
+    document_type: str
+    document: str
+    document_date: dt.date
+    due_date: dt.date | None
+    amount: Decimal
+    advance: bool
+
+
+def open_items(rows: Sequence[GLRow], index: AccountIndex, kind: Kind, as_of: dt.date) -> list[OpenItem]:
+    relevant = [r for r in rows if r.posting_date <= as_of and index[r.account].account_type == kind]
+    orphans = sorted(r.name for r in relevant if not r.party)
+    if orphans:
+        raise PeriodError(f"{kind} entries with no party cannot be placed: {', '.join(orphans)}")
+    groups: dict[tuple[str, str, str, str], list[GLRow]] = defaultdict(list)
+    for r in relevant:
+        doc_type = r.against_voucher_type or r.voucher_type
+        doc = r.against_voucher or r.voucher_no
+        groups[(r.party_type or "", r.party or "", doc_type, doc)].append(r)
+    sign = 1 if kind == "Receivable" else -1
+    items: list[OpenItem] = []
+    for (party_type, party, doc_type, doc), members in groups.items():
+        amount = sign * sum((m.net for m in members), Decimal(0))
+        if amount == 0:
+            continue
+        own = [m for m in members if m.voucher_no == doc] or members
+        first = min(own, key=lambda m: (m.posting_date, m.name))
+        due = next((m.due_date for m in own if m.due_date), None)
+        items.append(OpenItem(party_type, party, doc_type, doc, first.posting_date, due, amount, amount < 0))
+    return sorted(items, key=lambda i: (i.party, i.document_date, i.document))
+
+
+def open_items_csv(items: Sequence[OpenItem]) -> bytes:
+    header = ["party_type", "party", "document_type", "document", "document_date", "due_date", "amount", "advance"]
+    rows = [
+        [
+            i.party_type,
+            i.party,
+            i.document_type,
+            i.document,
+            i.document_date.isoformat(),
+            i.due_date.isoformat() if i.due_date else "",
+            money(i.amount),
+            "yes" if i.advance else "",
+        ]
+        for i in items
+    ]
+    return render_csv(header, rows)
+
+
+def check_open_items_against(items: Sequence[OpenItem], tb: TrialBalance, index: AccountIndex, kind: Kind) -> None:
+    """The open items must add up to the closing balance of every account of this kind."""
+    sign = 1 if kind == "Receivable" else -1
+    ledger = sign * sum((line.closing for line in tb.lines if line.account.account_type == kind), Decimal(0))
+    listed = sum((i.amount for i in items), Decimal(0))
+    if ledger != listed:
+        raise PeriodError(f"open {kind.lower()}s total {listed} but the {kind} accounts close at {ledger}")