akt-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{akt_cli-0.6.0 → akt_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -256,7 +256,7 @@ akt coa sync --prune         # also DISABLE accounts/categories absent from the
 # code a transaction by GL account — akt auto-fills the mirror category:
 akt payment create --type expense --bank 1 --amount 120 --account 628
 # ...or by category name — akt reverse-fills the matching GL account:
-akt payment create --type expense --bank 1 --amount 120 --category "Market Data Feeds"
+akt payment create --type expense --bank 1 --amount 120 --category "Cloud Hosting"
 ```
 
 `--account`/`--category` are two ends of the same coin: give either and akt fills
@@ -280,6 +280,24 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## Financial reports (needs the akt-api module)
+
+Akaunting's trial balance, P&L, and balance sheet aren't in its JSON API. With
+the companion module installed, akt computes them from the ledger:
+
+```bash
+akt trial-balance --to 2025-12-31                 # every account, debits = credits
+akt report profit-loss --from 2025-01-01 --to 2025-12-31
+akt report balance-sheet --to 2025-12-31
+akt balance --account 105 --to 2025-12-31         # one account's balance
+akt balance --account 200 --to 2025-12-31 --expected 0   # reconcile: exit 1 on mismatch
+```
+
+`--expected` turns `akt balance` into a reconciliation primitive (compare an
+account to an external figure, non-zero exit on a mismatch). Balances aggregate
+through Akaunting's ledger relation, so soft-deleted transactions are excluded
+just as its own reports do.
+
 ## Reading the ledger: the `akt-api` companion module
 
 Akaunting's Double-Entry app exposes only `journal-entry` and `chart-of-accounts`

{akt_cli-0.6.0 → akt_cli-0.7.0}/README.md

@@ -235,7 +235,7 @@ akt coa sync --prune         # also DISABLE accounts/categories absent from the
 # code a transaction by GL account — akt auto-fills the mirror category:
 akt payment create --type expense --bank 1 --amount 120 --account 628
 # ...or by category name — akt reverse-fills the matching GL account:
-akt payment create --type expense --bank 1 --amount 120 --category "Market Data Feeds"
+akt payment create --type expense --bank 1 --amount 120 --category "Cloud Hosting"
 ```
 
 `--account`/`--category` are two ends of the same coin: give either and akt fills
@@ -259,6 +259,24 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## Financial reports (needs the akt-api module)
+
+Akaunting's trial balance, P&L, and balance sheet aren't in its JSON API. With
+the companion module installed, akt computes them from the ledger:
+
+```bash
+akt trial-balance --to 2025-12-31                 # every account, debits = credits
+akt report profit-loss --from 2025-01-01 --to 2025-12-31
+akt report balance-sheet --to 2025-12-31
+akt balance --account 105 --to 2025-12-31         # one account's balance
+akt balance --account 200 --to 2025-12-31 --expected 0   # reconcile: exit 1 on mismatch
+```
+
+`--expected` turns `akt balance` into a reconciliation primitive (compare an
+account to an external figure, non-zero exit on a mismatch). Balances aggregate
+through Akaunting's ledger relation, so soft-deleted transactions are excluded
+just as its own reports do.
+
 ## Reading the ledger: the `akt-api` companion module
 
 Akaunting's Double-Entry app exposes only `journal-entry` and `chart-of-accounts`

{akt_cli-0.6.0 → akt_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "akt-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "akt — a CLI toolbox to fully drive an Akaunting accounting instance"
 readme = "README.md"
 license = "MIT"

{akt_cli-0.6.0 → akt_cli-0.7.0}/src/akt/cli.py

@@ -24,6 +24,7 @@ from .resources import Resource, load_data_arg
 from .coa import load_coa, plan_sync, render_plan, apply_plan
 from .ledger import resolve_account_id
 from .verify import find_miscodings, build_recode_plan
+from . import reports
 
 
 def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
@@ -202,9 +203,51 @@ def _build_parser() -> argparse.ArgumentParser:
                      help="show the plan without writing anything")
     rcp.set_defaults(_special="recode")
 
+    bp = sub.add_parser("balance", parents=[common],
+                        help="Show one account's balance (needs the akt-api module)")
+    bp.add_argument("--account", required=True, metavar="CODE|NAME")
+    bp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+    bp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+    bp.add_argument("--expected", type=float, metavar="AMOUNT",
+                    help="reconcile: compare to this figure, exit 1 on mismatch")
+    bp.set_defaults(_special="balance")
+
+    tp = sub.add_parser("trial-balance", parents=[common],
+                        help="Trial balance (needs the akt-api module)")
+    tp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+    tp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+    tp.set_defaults(_special="trial_balance")
+
+    rpp = sub.add_parser("report", parents=[common], help="Financial reports (needs the akt-api module)")
+    rpv = rpp.add_subparsers(dest="report_verb", metavar="<report>")
+    for verb, sp in (("profit-loss", "report_pnl"), ("balance-sheet", "report_bs")):
+        p = rpv.add_parser(verb, parents=[common])
+        p.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+        p.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+        p.set_defaults(_special=sp)
+
     return parser
 
 
+def _need_akt_api(client: Client, cmd: str) -> None:
+    if not client.has_ledger_api():
+        raise ValueError(f"`akt {cmd}` needs the akt-api companion module — "
+                         "install it into your Akaunting modules/ directory (see akt-api/README.md)")
+
+
+def _fetch_balances(client: Client, ns: Any):
+    accounts = client.list("chart-of-accounts", all_pages=True)
+    accts_by_id = {a["id"]: {"code": a.get("code"), "name": a.get("name"),
+                             "type_id": a.get("type_id")} for a in accounts}
+    params: dict[str, Any] = {}
+    if getattr(ns, "date_from", None):
+        params["date_from"] = ns.date_from
+    if getattr(ns, "date_to", None):
+        params["date_to"] = ns.date_to
+    rows = client.list("akt-api/balances", all_pages=True, params=params or None)
+    return reports.balances_by_id(rows), accts_by_id, accounts
+
+
 def _run_special(name: str, client: Client, ns: Any) -> int:
     if name == "ping":
         emit(client.get("ping"), as_json=True)
@@ -344,6 +387,63 @@ def _run_special(name: str, client: Client, ns: Any) -> int:
             done += 1
         print(f"recoded {done} transaction(s).")
         return 0
+    if name == "balance":
+        _need_akt_api(client, "balance")
+        balances, accts_by_id, accounts = _fetch_balances(client, ns)
+        account_id = resolve_account_id(accounts, ns.account)
+        bal = balances.get(account_id, 0.0)
+        if ns.expected is not None:
+            r = reports.reconcile(bal, ns.expected)
+            emit(r, as_json=ns.json,
+                 columns=None if ns.json else ["actual", "expected", "diff", "ok"],
+                 headers=["Balance", "Expected", "Diff", "OK"])
+            return 0 if r["ok"] else 1
+        emit({"account_id": account_id, "balance": round(bal, 2)}, as_json=ns.json,
+             columns=None if ns.json else ["account_id", "balance"],
+             headers=["Account", "Balance"])
+        return 0
+    if name == "trial_balance":
+        _need_akt_api(client, "trial-balance")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        tb = reports.build_trial_balance(balances, accts_by_id)
+        if ns.json:
+            emit(tb, as_json=True)
+        else:
+            emit(tb["rows"], as_json=False, columns=["code", "name", "debit", "credit"],
+                 headers=["Code", "Account", "Debit", "Credit"])
+            print(f"  {'TOTAL':>34}  {tb['total_debit']:>12,.2f}  {tb['total_credit']:>12,.2f}")
+            print("  BALANCED" if tb["balanced"] else "  *** OUT OF BALANCE")
+        return 0 if tb["balanced"] else 1
+    if name == "report_pnl":
+        _need_akt_api(client, "report profit-loss")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        pl = reports.build_profit_loss(balances, accts_by_id)
+        if ns.json:
+            emit(pl, as_json=True)
+        else:
+            print("INCOME")
+            emit(pl["income"], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+            print(f"  {'Total income':>40}  {pl['total_income']:>12,.2f}\n\nEXPENSES")
+            emit(pl["expense"], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+            print(f"  {'Total expenses':>40}  {pl['total_expense']:>12,.2f}")
+            print(f"  {'NET PROFIT':>40}  {pl['net_profit']:>12,.2f}")
+        return 0
+    if name == "report_bs":
+        _need_akt_api(client, "report balance-sheet")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        bs = reports.build_balance_sheet(balances, accts_by_id)
+        if ns.json:
+            emit(bs, as_json=True)
+        else:
+            for title, key, tot in (("ASSETS", "assets", "total_assets"),
+                                    ("LIABILITIES", "liabilities", "total_liabilities"),
+                                    ("EQUITY", "equity", "total_equity")):
+                print(title)
+                emit(bs[key], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+                print(f"  {'Total ' + title.lower():>40}  {bs[tot]:>12,.2f}\n")
+            print(f"  {'Net income to date':>40}  {bs['net_income']:>12,.2f}")
+            print("  BALANCED" if bs["balanced"] else "  *** DOES NOT BALANCE")
+        return 0 if bs["balanced"] else 1
     raise ValueError(name)
 
 

akt_cli-0.7.0/src/akt/reports.py

@@ -0,0 +1,99 @@
+"""Financial report builders — pure functions over per-account balances.
+
+A `balances` map is {account_id: debit - credit}. `accounts_by_id` is
+{id: {"code":..., "name":..., "type_id":...}} from the chart of accounts.
+"""
+from __future__ import annotations
+
+import sys
+
+# DoubleEntry standard seeds (Database/Seeds/Types.php): type_id -> class_id.
+CLASS_NAMES = {1: "Assets", 2: "Liabilities", 3: "Expenses", 4: "Income", 5: "Equity"}
+TYPE_ID_CLASS = {1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1, 10: 1,   # assets (incl. depreciation)
+                 7: 2, 8: 2, 9: 2, 17: 2,                      # liabilities (incl. tax)
+                 11: 3, 12: 3,                                 # expenses (incl. direct costs)
+                 13: 4, 14: 4, 15: 4,                          # income
+                 16: 5}                                        # equity
+
+
+def account_class(type_id) -> "int | None":
+    c = TYPE_ID_CLASS.get(type_id)
+    if c is None:
+        print(f"warning: unknown account type_id {type_id}; excluded from "
+              f"class-grouped reports", file=sys.stderr)
+    return c
+
+
+def balances_by_id(rows: list[dict]) -> dict[int, float]:
+    return {int(r["account_id"]): round(float(r.get("debit") or 0)
+                                        - float(r.get("credit") or 0), 2)
+            for r in rows}
+
+
+def _line(a: dict, amount: float) -> dict:
+    return {"code": a.get("code"), "name": a.get("name"), "amount": round(amount, 2)}
+
+
+def build_trial_balance(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    rows = []
+    for aid, bal in balances.items():
+        if abs(bal) < 0.005:
+            continue
+        a = accounts_by_id.get(aid, {})
+        rows.append({"code": a.get("code"), "name": a.get("name"),
+                     "debit": round(bal, 2) if bal > 0 else 0.0,
+                     "credit": round(-bal, 2) if bal < 0 else 0.0})
+    rows.sort(key=lambda r: (r["code"] is None, str(r["code"])))
+    total_debit = round(sum(r["debit"] for r in rows), 2)
+    total_credit = round(sum(r["credit"] for r in rows), 2)
+    return {"rows": rows, "total_debit": total_debit, "total_credit": total_credit,
+            "balanced": abs(total_debit - total_credit) < 0.02}
+
+
+def build_profit_loss(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    income, expense = [], []
+    for aid, bal in balances.items():
+        a = accounts_by_id.get(aid, {})
+        cls = account_class(a.get("type_id"))
+        if cls == 4 and abs(bal) >= 0.005:
+            income.append(_line(a, -bal))          # income is credit-positive
+        elif cls == 3 and abs(bal) >= 0.005:
+            expense.append(_line(a, bal))          # expense is debit-positive
+    income.sort(key=lambda r: str(r["code"]))
+    expense.sort(key=lambda r: str(r["code"]))
+    total_income = round(sum(i["amount"] for i in income), 2)
+    total_expense = round(sum(e["amount"] for e in expense), 2)
+    return {"income": income, "expense": expense, "total_income": total_income,
+            "total_expense": total_expense, "net_profit": round(total_income - total_expense, 2)}
+
+
+def build_balance_sheet(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    assets, liabilities, equity = [], [], []
+    net_income = 0.0
+    for aid, bal in balances.items():
+        a = accounts_by_id.get(aid, {})
+        cls = account_class(a.get("type_id"))
+        if cls == 1 and abs(bal) >= 0.005:
+            assets.append(_line(a, bal))           # asset debit-positive
+        elif cls == 2 and abs(bal) >= 0.005:
+            liabilities.append(_line(a, -bal))     # liability credit-positive
+        elif cls == 5 and abs(bal) >= 0.005:
+            equity.append(_line(a, -bal))          # equity credit-positive
+        elif cls in (3, 4):
+            net_income += -bal                     # income(+) and expense(-) both -bal
+    for s in (assets, liabilities, equity):
+        s.sort(key=lambda r: str(r["code"]))
+    total_assets = round(sum(x["amount"] for x in assets), 2)
+    total_liabilities = round(sum(x["amount"] for x in liabilities), 2)
+    total_equity = round(sum(x["amount"] for x in equity), 2)
+    net_income = round(net_income, 2)
+    return {"assets": assets, "liabilities": liabilities, "equity": equity,
+            "net_income": net_income, "total_assets": total_assets,
+            "total_liabilities": total_liabilities, "total_equity": total_equity,
+            "balanced": abs(total_assets - (total_liabilities + total_equity + net_income)) < 0.02}
+
+
+def reconcile(actual: float, expected: float, tol: float = 0.005) -> dict:
+    diff = round(actual - expected, 2)
+    return {"actual": round(actual, 2), "expected": round(expected, 2),
+            "diff": diff, "ok": abs(actual - expected) < tol}