runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/forecast/doctype.py

@@ -0,0 +1,228 @@
+"""The Cash Forecast doctype, and writing a computed forecast into it.
+
+Each run writes a new document and never edits an earlier one: the capital call
+is money people wired against, so the record of what a past run said must not
+change underneath them. A custom doctype (`custom: 1`) needs no developer mode
+on the site, which is why every definition here carries it.
+
+Installing needs an administrator, for the same reason `install_custom_fields`
+does: the books bot may write forecasts, not reshape doctypes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from decimal import Decimal
+from typing import Any
+
+from icedcoffee_sync.frappe.errors import DoesNotExistError, PermissionError_
+
+from runningtab.forecast.compute import Forecast
+from runningtab.forecast.names import CASH_FORECAST
+from runningtab.mercury.posting import Ledger, Outcome
+
+MONTH_TABLE = "Cash Forecast Month"
+MEMBER_TABLE = "Cash Forecast Member"
+LINE_TABLE = "Cash Forecast Line"
+
+_DOCTYPE = "DocType"
+_STATUS_OPTIONS = "owed\nseen paid"
+
+
+def _field(fieldname: str, fieldtype: str, options: str | None = None, *, in_list: bool = False) -> dict[str, Any]:
+    field: dict[str, Any] = {
+        "fieldname": fieldname,
+        "label": fieldname.replace("_", " ").title(),
+        "fieldtype": fieldtype,
+        "in_list_view": int(in_list),
+    }
+    if options is not None:
+        field["options"] = options
+    return field
+
+
+def _table(name: str, fields: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "doctype": _DOCTYPE,
+        "name": name,
+        "module": "Accounts",
+        "custom": 1,
+        "istable": 1,
+        "fields": fields,
+    }
+
+
+def doctype_documents() -> list[dict[str, Any]]:
+    """The four DocType definitions, child tables first so the parent can name them."""
+    month = _table(
+        MONTH_TABLE,
+        [
+            _field("month", "Date", in_list=True),
+            _field("opening", "Currency", in_list=True),
+            _field("outflows", "Currency", in_list=True),
+            _field("inflows", "Currency", in_list=True),
+            _field("closing", "Currency", in_list=True),
+        ],
+    )
+    member = _table(
+        MEMBER_TABLE,
+        [
+            _field("account", "Link", "Account", in_list=True),
+            _field("amount", "Currency", in_list=True),
+        ],
+    )
+    line = _table(
+        LINE_TABLE,
+        [
+            _field("month", "Date", in_list=True),
+            _field("due", "Date", in_list=True),
+            _field("line", "Data", in_list=True),
+            _field("account", "Link", "Account"),
+            _field("amount", "Currency", in_list=True),
+            _field("status", "Select", _STATUS_OPTIONS, in_list=True),
+        ],
+    )
+    parent = {
+        "doctype": _DOCTYPE,
+        "name": CASH_FORECAST,
+        "module": "Accounts",
+        "custom": 1,
+        "istable": 0,
+        "is_submittable": 0,
+        "track_changes": 0,
+        "autoname": "CF-.#####",
+        "sort_field": "creation",
+        "sort_order": "DESC",
+        "fields": [
+            # Data, not Datetime: Frappe reads a Datetime as site-local and would
+            # silently shift an instant that carries its own UTC offset.
+            _field("computed_at", "Data", in_list=True),
+            _field("ledger_through", "Date"),
+            _field("window_start", "Date"),
+            _field("window_end", "Date"),
+            _field("scenario", "Data"),
+            _field("opening_cash", "Currency"),
+            _field("floor", "Currency"),
+            _field("floor_from", "Data"),
+            _field("total_call", "Currency", in_list=True),
+            _field("months", "Table", MONTH_TABLE),
+            _field("members", "Table", MEMBER_TABLE),
+            _field("lines", "Table", LINE_TABLE),
+        ],
+        "permissions": [
+            {"role": "System Manager", "read": 1, "write": 1, "create": 1, "delete": 1, "report": 1, "export": 1},
+            {"role": "Accounts Manager", "read": 1},
+        ],
+    }
+    return [month, member, line, parent]
+
+
+def _shape(fields: list[dict[str, Any]]) -> dict[str, tuple[str, str]]:
+    """What makes a field the right field, by name: Frappe fills the rest in itself.
+
+    Keyed by fieldname so a different field order from Frappe is not a
+    difference.
+    """
+    return {str(f["fieldname"]): (str(f["fieldtype"]), str(f.get("options") or "")) for f in fields}
+
+
+def install_doctypes(admin: Ledger) -> list[tuple[str, Outcome]]:
+    """Create each doctype if absent; replace its field list if it differs.
+
+    Repair covers fields only. It does not touch permissions or `is_submittable`
+    on an existing doctype.
+
+    A doctype that exists with a field of the wrong type would accept the
+    forecast write and then store the wrong thing, so presence is not enough.
+    Repair replaces the whole field list with the desired one, so a field added
+    by hand to the doctype is dropped from the definition (its column stays).
+    It never deletes the doctype, which would take every stored forecast with
+    it.
+    """
+    results: list[tuple[str, Outcome]] = []
+    for document in doctype_documents():
+        name = document["name"]
+        body = {k: v for k, v in document.items() if k != "doctype"}
+        if not admin.list(_DOCTYPE, fields=["name"], filters=[["name", "=", name]], limit=1):
+            admin.insert(_DOCTYPE, body)
+            results.append((name, Outcome.CREATED))
+            continue
+        existing = admin.get(_DOCTYPE, name)
+        if _shape(existing.get("fields") or []) == _shape(body["fields"]):
+            results.append((name, Outcome.UNCHANGED))
+            continue
+        admin.update(_DOCTYPE, name, {"fields": body["fields"]})
+        results.append((name, Outcome.UPDATED))
+    return results
+
+
+def is_installed(ledger: Ledger) -> bool:
+    """Whether the site has the Cash Forecast doctype, asked with the caller's own credential.
+
+    Listing the doctype needs no permission on `DocType` itself, which the bot
+    lacks. A site without the doctype answers DoesNotExist; a credential not
+    yet granted read answers PermissionError, which only a site that has the
+    doctype can say.
+    """
+    try:
+        ledger.list(CASH_FORECAST, fields=["name"], limit=1)
+    except DoesNotExistError:
+        return False
+    except PermissionError_:
+        return True
+    return True
+
+
+def _money(value: Decimal) -> float:
+    """A currency amount as JSON, converted once after all arithmetic is done in `Decimal`."""
+    return float(value)
+
+
+def forecast_document(forecast: Forecast, *, link: Callable[[str], str]) -> dict[str, Any]:
+    """The Cash Forecast document for a computed forecast.
+
+    `link` maps a chart account number to the company-suffixed name ERPNext
+    links by.
+    """
+    if forecast.computed_at.utcoffset() is None:
+        raise ValueError("computed_at must carry a time zone; a naive time is ambiguous once stored")
+    return {
+        "doctype": CASH_FORECAST,
+        "computed_at": forecast.computed_at.isoformat(timespec="seconds"),
+        "ledger_through": forecast.ledger_through.isoformat(),
+        "window_start": forecast.window_start.isoformat(),
+        "window_end": forecast.window_end.isoformat(),
+        "scenario": forecast.scenario,
+        "opening_cash": _money(forecast.opening_cash),
+        "floor": _money(forecast.floor),
+        "floor_from": forecast.floor_from,
+        "total_call": _money(forecast.total_call),
+        "months": [
+            {
+                "month": m.month.isoformat(),
+                "opening": _money(m.opening),
+                "outflows": _money(m.outflows),
+                "inflows": _money(m.inflows),
+                "closing": _money(m.closing),
+            }
+            for m in forecast.months
+        ],
+        "members": [{"account": link(number), "amount": _money(amount)} for number, amount in forecast.members],
+        "lines": [
+            {
+                "month": d.due.replace(day=1).isoformat(),
+                "due": d.due.isoformat(),
+                "line": d.line.name,
+                "account": link(d.line.account),
+                "amount": _money(d.amount),
+                "status": d.status,
+            }
+            for d in forecast.dues
+        ],
+    }
+
+
+def write_forecast(ledger: Ledger, forecast: Forecast, *, link: Callable[[str], str]) -> str:
+    """Insert the forecast as a new document and return its name."""
+    created = ledger.insert(CASH_FORECAST, forecast_document(forecast, link=link))
+    return str(created["name"])

runningtab/forecast/model.py

@@ -0,0 +1,251 @@
+"""The forecast file: expected cash movements, as checked-in data.
+
+`forecast.toml` sits beside the chart in the books directory. A `[call]` table
+names the member capital accounts and an optional floor; each `[[line]]` table
+is one recurring cost. The file is validated against the chart on load so a
+typo in an account number is refused here rather than surfacing as a wrong
+capital call later.
+
+`lag_days` and `confidence` are reserved for income and payroll lines. They are
+accepted and ignored so that adding them later does not invalidate the file.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+import pathlib
+import tomllib
+from collections.abc import Mapping
+from decimal import Decimal
+from typing import Any, Literal, cast
+
+from runningtab.mercury.vouchers import EXPENSE_PREFIX, MEMBER_CAPITAL_PREFIX, Chart
+
+_RESERVED = frozenset({"lag_days", "confidence"})
+_KNOWN = (
+    frozenset({
+        "name",
+        "kind",
+        "account",
+        "match",
+        "cadence",
+        "day",
+        "on",
+        "amount",
+        "low",
+        "high",
+        "paid",
+        "starts",
+        "ends",
+    })
+    | _RESERVED
+)
+
+
+class ForecastFileError(ValueError):
+    """`forecast.toml` is not a forecast we can compute from."""
+
+
+@dataclasses.dataclass(frozen=True)
+class Amount:
+    """What a line costs in a month. A fixed cost has `low == high`."""
+
+    low: Decimal
+    high: Decimal
+
+
+@dataclasses.dataclass(frozen=True)
+class Line:
+    """One recurring expense.
+
+    `day` is set for monthly lines; `on` for yearly ones, where only its month
+    and day recur. `match` names the Mercury counterparties whose charge is this
+    line; for a reimbursed line that is the member Mercury pays back, one
+    transfer per charge. A line without `match` is always counted owed.
+    """
+
+    name: str
+    account: str
+    match: tuple[str, ...]
+    cadence: Literal["monthly", "yearly"]
+    day: int | None
+    on: dt.date | None
+    amount: Amount
+    paid: Literal["mercury", "reimbursed"]
+    starts: dt.date | None
+    ends: dt.date | None
+
+
+@dataclasses.dataclass(frozen=True)
+class CallPolicy:
+    """Who is called for capital, and an optional fixed floor overriding the computed one."""
+
+    members: tuple[str, ...]
+    floor: Decimal | None
+
+
+@dataclasses.dataclass(frozen=True)
+class ForecastFile:
+    """The whole parsed file."""
+
+    lines: tuple[Line, ...]
+    call: CallPolicy
+
+
+def _money(value: Any, where: str) -> Decimal:
+    """A TOML number as Decimal, via its text so 29.16 stays 29.16."""
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise ForecastFileError(f"{where} must be a number, got {value!r}")
+    return Decimal(str(value))
+
+
+def _date(value: Any, where: str) -> dt.date:
+    if not isinstance(value, dt.date) or isinstance(value, dt.datetime):
+        raise ForecastFileError(f"{where} must be a TOML date (YYYY-MM-DD), got {value!r}")
+    return value
+
+
+def _optional_date(table: Mapping[str, Any], key: str, where: str) -> dt.date | None:
+    return _date(table[key], f"{where}: {key}") if key in table else None
+
+
+def _parse_account(table: Mapping[str, Any], where: str, postable: Mapping[str, str]) -> str:
+    account = table.get("account")
+    if not isinstance(account, str) or account not in postable:
+        raise ForecastFileError(f"{where}: account {account!r} is not a postable account in chart.coa")
+    if not account.startswith(EXPENSE_PREFIX):
+        raise ForecastFileError(f"{where}: account {account} is not an expense account")
+    return account
+
+
+def _parse_match(table: Mapping[str, Any], where: str, paid: str) -> tuple[str, ...]:
+    match = table.get("match", [])
+    if not isinstance(match, list) or not all(isinstance(m, str) and m for m in match):
+        raise ForecastFileError(f"{where}: match must be a list of counterparty names")
+    if paid == "mercury" and not match:
+        raise ForecastFileError(f"{where}: match is required for a mercury line; the paid-this-month check needs it")
+    return tuple(match)
+
+
+def _parse_when(
+    table: Mapping[str, Any], where: str
+) -> tuple[Literal["monthly", "yearly"], int | None, dt.date | None]:
+    """The cadence with its `day` (monthly) or `on` (yearly)."""
+    cadence = table.get("cadence")
+    if cadence == "monthly":
+        day = table.get("day")
+        if isinstance(day, bool) or not isinstance(day, int) or not 1 <= day <= 31:
+            raise ForecastFileError(f"{where}: a monthly line needs day = 1..31, got {day!r}")
+        if "on" in table:
+            raise ForecastFileError(f"{where}: a monthly line takes day, not on")
+        return "monthly", day, None
+    if cadence == "yearly":
+        if "on" not in table:
+            raise ForecastFileError(f"{where}: a yearly line needs on = a date; its month and day recur")
+        if "day" in table:
+            raise ForecastFileError(f"{where}: a yearly line takes on, not day")
+        on = _date(table["on"], f"{where}: on")
+        if (on.month, on.day) == (2, 29):
+            raise ForecastFileError(f"{where}: on {on} (Feb 29) does not recur every year; use Feb 28 or Mar 1")
+        return "yearly", None, on
+    raise ForecastFileError(f"{where}: cadence must be 'monthly' or 'yearly', got {cadence!r}")
+
+
+def _parse_amount(table: Mapping[str, Any], where: str) -> Amount:
+    if "amount" in table:
+        if "low" in table or "high" in table:
+            raise ForecastFileError(f"{where}: give amount or low and high, not both")
+        fixed = _money(table["amount"], f"{where}: amount")
+        amount = Amount(fixed, fixed)
+    elif "low" in table and "high" in table:
+        amount = Amount(_money(table["low"], f"{where}: low"), _money(table["high"], f"{where}: high"))
+        if amount.low > amount.high:
+            raise ForecastFileError(f"{where}: low {amount.low} is above high {amount.high}")
+    else:
+        raise ForecastFileError(f"{where}: needs amount, or both low and high")
+    if amount.low < 0:
+        raise ForecastFileError(f"{where}: amounts must not be negative")
+    return amount
+
+
+def _parse_line(table: Mapping[str, Any], index: int, postable: Mapping[str, str]) -> Line:
+    name = table.get("name")
+    if not isinstance(name, str) or not name:
+        raise ForecastFileError(f"line #{index + 1}: name is required")
+    where = f"line {name!r}"
+    unknown = sorted(set(table) - _KNOWN)
+    if unknown:
+        raise ForecastFileError(f"{where}: unknown field(s) {', '.join(unknown)}")
+    kind = table.get("kind")
+    if kind != "expense":
+        raise ForecastFileError(f"{where}: kind {kind!r} is not supported yet; only 'expense' is")
+    paid = table.get("paid")
+    if paid not in ("mercury", "reimbursed"):
+        raise ForecastFileError(f"{where}: paid must be 'mercury' or 'reimbursed', got {paid!r}")
+    cadence, day, on = _parse_when(table, where)
+    starts = _optional_date(table, "starts", where)
+    ends = _optional_date(table, "ends", where)
+    if starts and ends and starts > ends:
+        raise ForecastFileError(f"{where}: starts {starts} is later than ends {ends}")
+    return Line(
+        name=name,
+        account=_parse_account(table, where, postable),
+        match=_parse_match(table, where, paid),
+        cadence=cadence,
+        day=day,
+        on=on,
+        amount=_parse_amount(table, where),
+        paid=paid,
+        starts=starts,
+        ends=ends,
+    )
+
+
+def _parse_call(table: Mapping[str, Any], postable: Mapping[str, str]) -> CallPolicy:
+    members = table.get("members")
+    if not isinstance(members, list) or not members:
+        raise ForecastFileError("call: members must be a non-empty list of member capital accounts")
+    for member in members:
+        if not isinstance(member, str) or member not in postable or not member.startswith(MEMBER_CAPITAL_PREFIX):
+            raise ForecastFileError(
+                f"call: member {member!r} is not a member capital account ({MEMBER_CAPITAL_PREFIX}xx)"
+            )
+    duplicates = sorted({m for m in members if members.count(m) > 1})
+    if duplicates:
+        raise ForecastFileError(f"call: member(s) {', '.join(duplicates)} listed more than once; the split would skew")
+    floor = _money(table["floor"], "call: floor") if "floor" in table else None
+    if floor is not None and floor < 0:
+        raise ForecastFileError(f"call: floor {floor} must not be negative")
+    return CallPolicy(members=tuple(members), floor=floor)
+
+
+def parse_forecast(text: str, *, postable: Mapping[str, str]) -> ForecastFile:
+    """Parse and validate forecast TOML against the chart's postable accounts.
+
+    Raises:
+        ForecastFileError: naming the line and field that is wrong.
+    """
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ForecastFileError(f"forecast file is not valid TOML: {error}") from error
+    call = data.get("call")
+    if not isinstance(call, dict):
+        raise ForecastFileError("forecast file needs a [call] table")
+    raw_lines = data.get("line", [])
+    if not isinstance(raw_lines, list) or not all(isinstance(t, dict) for t in raw_lines):
+        raise ForecastFileError("forecast file: line must be an array of [[line]] tables")
+    lines = tuple(
+        _parse_line(table, index, postable) for index, table in enumerate(cast("list[Mapping[str, Any]]", raw_lines))
+    )
+    names = [line.name for line in lines]
+    duplicate_names = sorted({n for n in names if names.count(n) > 1})
+    if duplicate_names:
+        raise ForecastFileError(f"forecast file: duplicate line name(s) {', '.join(duplicate_names)}")
+    return ForecastFile(lines=lines, call=_parse_call(call, postable))
+
+
+def load_forecast(path: pathlib.Path, chart: Chart) -> ForecastFile:
+    """Read `forecast.toml` and validate it against the chart beside it."""
+    return parse_forecast(path.read_text(encoding="utf-8"), postable=chart.postable)

runningtab/forecast/names.py

@@ -0,0 +1,8 @@
+"""Doctype names the access policy needs, kept import-free.
+
+`runningtab.access` must name the Cash Forecast doctype, but `runningtab.forecast.doctype`
+imports the ledger code, which imports `runningtab.access`. Holding the name here
+breaks that cycle; `runningtab.forecast.doctype` re-exports it.
+"""
+
+CASH_FORECAST = "Cash Forecast"

runningtab/forecast/sources.py

@@ -0,0 +1,85 @@
+"""Where the forecast's opening numbers come from.
+
+Opening cash is Mercury's own balance, and the ledger's reconciliation frontier
+is the last day ERPNext agrees with the bank. Both refuse plainly when they
+cannot be trusted: a capital call computed from a balance that does not
+reconcile is a confident wrong number that members then wire money against.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from collections.abc import Sequence
+from decimal import Decimal
+from typing import Any, Protocol
+
+from icedcoffee_sync.frappe.errors import FrappeError
+
+from runningtab.mercury.ingest import BalanceCheck
+
+MAINTENANCE = "SessionStopped"
+"""The `error_type` a Frappe site answers with while an update is running."""
+
+
+class SourceError(RuntimeError):
+    """An input the forecast cannot trust. The message is the sentence a person reads."""
+
+
+class _Reader(Protocol):
+    def iter_all(self, doctype: str, **kwargs: Any) -> Any: ...
+
+
+def opening_cash(balances: Sequence[BalanceCheck]) -> Decimal:
+    """Cash on hand: the sum of every account's reported balance, net of cards.
+
+    A credit account reports a negative balance when it owes money, so a plain
+    sum is already net of what the card owes.
+
+    Raises:
+        SourceError: Naming every account whose reported balance differs from
+            the sum of the transactions read for it, since that means the read
+            was incomplete and the balance cannot anchor a forecast.
+    """
+    if not balances:
+        raise SourceError("Mercury returned no accounts, so there is no balance to forecast from")
+    bad = [check.label for check in balances if not check.ok]
+    if bad:
+        raise SourceError(
+            "Mercury's balance does not match its transactions for "
+            + ", ".join(bad)
+            + "; the read was incomplete, so no forecast"
+        )
+    return sum((check.reported for check in balances), Decimal(0))
+
+
+def ledger_through(ledger: _Reader, today: dt.date) -> dt.date:
+    """The last day the ledger is known to agree with the bank.
+
+    That is the day before the oldest submitted Bank Transaction still
+    unreconciled, or `today` when none is.
+    """
+    rows = ledger.iter_all(
+        "Bank Transaction",
+        fields=["name", "date"],
+        filters=[["status", "=", "Unreconciled"], ["docstatus", "=", 1]],
+    )
+    dates = [_row_date(row) for row in rows]
+    return min(dates) - dt.timedelta(days=1) if dates else today
+
+
+def _row_date(row: Any) -> dt.date:
+    """A Bank Transaction's date, or a SourceError naming the row when it has none we can read."""
+    raw = row.get("date")
+    try:
+        return dt.date.fromisoformat(str(raw))
+    except ValueError:
+        raise SourceError(
+            f"Bank Transaction {row.get('name')} has no readable date ({raw!r}), so the reconciliation frontier is unknown"
+        ) from None
+
+
+def maintenance_message(exc: FrappeError) -> str | None:
+    """The sentence for a site mid-update, or None when the error is something else."""
+    if exc.error_type == MAINTENANCE:
+        return "the site is in maintenance mode (an update is running); run this again when it finishes"
+    return None

runningtab/gl_codes.py

@@ -0,0 +1,50 @@
+"""The GL code list Mercury shows on every transaction: our postable accounts, as a CSV.
+
+The code a person picks in the bank rides along on the Bank Transaction as a
+hint for whoever reconciles it, so the vocabulary they pick from has to be the
+ledger's. There is no upload API; a person uploads it.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+
+from icedcoffee_sync.apply.model import DesiredAccount
+
+_THOUSANDS_SEPARATOR = re.compile(r"(?<=\d),(?=\d)")
+_LIST_SEPARATOR = re.compile(r",\s*")
+
+
+def postable_accounts(chart: list[DesiredAccount]) -> list[DesiredAccount]:
+    """Accounts a transaction can actually post to. Groups cannot."""
+    return [a for a in chart if not a.is_group]
+
+
+def gl_code_name(account: DesiredAccount) -> str:
+    """One entry of the list: `{number} - {name}` with every comma spent.
+
+    Mercury's GL-code importer splits each line at the first comma no matter how
+    the CSV quotes it, so a label carrying one reaches the bank truncated and
+    every transaction coded with it names an account that does not exist. A
+    comma between two digits is a thousands separator and simply goes; any other
+    comma separates list items and becomes ` / `. The ERPNext account name is
+    left alone, so a label can differ from the account it stands for.
+    """
+    name = _LIST_SEPARATOR.sub(" / ", _THOUSANDS_SEPARATOR.sub("", account.name))
+    return f"{account.number} - {name}"
+
+
+def gl_code_csv(chart: list[DesiredAccount]) -> str:
+    """A single column of `gl_code_name`, no header, and no comma or quote on any line.
+
+    Quoting would be the RFC 4180 answer to a comma in a field, and Mercury's
+    importer does not honour it — so the labels carry no commas to quote and no
+    line here is ever quoted.
+    """
+    out = io.StringIO()
+    writer = csv.writer(out, lineterminator="\n")
+    for account in postable_accounts(chart):
+        writer.writerow([gl_code_name(account)])
+    return out.getvalue()