manager-for-ynab 1.0.0__tar.gz

manager_for_ynab-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

manager_for_ynab-1.0.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: manager_for_ynab
+Version: 1.0.0
+Summary: Manager for YNAB
+Home-page: https://github.com/mxr/manager-for-ynab
+Author: Max R
+Author-email: mxr@users.noreply.github.com
+License: MIT
+Keywords: ynab,budget,plan,cli,reconcile,automation,manager
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Babel
+Requires-Dist: aiohttp
+Requires-Dist: rich
+Requires-Dist: sqlite-export-for-ynab>=2
+Requires-Dist: tldm
+Requires-Dist: ynab>=4
+Dynamic: license-file
+
+# manager-for-ynab
+
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/mxr/manager-for-ynab/main.svg)](https://results.pre-commit.ci/latest/github/mxr/manager-for-ynab/main)
+
+Manager for YNAB.
+
+## What This Does
+
+This repo is a single CLI for YNAB-focused tools.
+
+- `reconciler`: find and automatically reconciles unreconciled transactions
+- `pending-income`: move pending income transactions to today
+- `zero-out`: set a category's planned amount to zero across a month range
+
+Tool-specific docs:
+
+- [Reconciler](tools/reconciler/README.md)
+- [Pending Income](tools/pending-income/README.md)
+- [Zero Out](tools/zero-out/README.md)
+
+## Installation
+
+```console
+$ pip install manager-for-ynab
+```
+
+## Usage
+
+```console
+$ manager-for-ynab --help
+$ manager-for-ynab reconciler --help
+$ manager-for-ynab pending-income --help
+$ manager-for-ynab zero-out --help
+```

manager_for_ynab-1.0.0/README.md

@@ -0,0 +1,34 @@
+# manager-for-ynab
+
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/mxr/manager-for-ynab/main.svg)](https://results.pre-commit.ci/latest/github/mxr/manager-for-ynab/main)
+
+Manager for YNAB.
+
+## What This Does
+
+This repo is a single CLI for YNAB-focused tools.
+
+- `reconciler`: find and automatically reconciles unreconciled transactions
+- `pending-income`: move pending income transactions to today
+- `zero-out`: set a category's planned amount to zero across a month range
+
+Tool-specific docs:
+
+- [Reconciler](tools/reconciler/README.md)
+- [Pending Income](tools/pending-income/README.md)
+- [Zero Out](tools/zero-out/README.md)
+
+## Installation
+
+```console
+$ pip install manager-for-ynab
+```
+
+## Usage
+
+```console
+$ manager-for-ynab --help
+$ manager-for-ynab reconciler --help
+$ manager-for-ynab pending-income --help
+$ manager-for-ynab zero-out --help
+```

manager_for_ynab-1.0.0/manager_for_ynab/__init__.py

@@ -0,0 +1,3 @@
+from manager_for_ynab._main import main
+
+__all__ = [main.__name__]

manager_for_ynab-1.0.0/manager_for_ynab/__main__.py

@@ -0,0 +1,4 @@
+from manager_for_ynab._main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

manager_for_ynab-1.0.0/manager_for_ynab/_auth.py

@@ -0,0 +1,17 @@
+import os
+
+
+_ENV_TOKEN = "YNAB_PERSONAL_ACCESS_TOKEN"
+
+
+def resolve_token(token_override: str | None = None) -> str:
+    token = token_override or os.environ.get(_ENV_TOKEN)
+    if token:
+        return token
+
+    raise ValueError(
+        f"Must set YNAB access token as {_ENV_TOKEN!r} environment variable or pass token_override directly. See https://api.ynab.com/#personal-access-tokens"
+    )
+
+
+__all__ = [resolve_token.__name__, _ENV_TOKEN]

manager_for_ynab-1.0.0/manager_for_ynab/_main.py

@@ -0,0 +1,71 @@
+import argparse
+import sys
+from typing import TYPE_CHECKING
+
+import manager_for_ynab.pending_income as pending_income
+import manager_for_ynab.reconciler as reconciler
+import manager_for_ynab.zero_out as zero_out
+from manager_for_ynab._version import get_version
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+_RECONCILER_HELP = "Find and automatically reconciles unreconciled transactions."
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="manager-for-ynab")
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {get_version()}"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    reconciler_parser = subparsers.add_parser(
+        "reconciler",
+        help=_RECONCILER_HELP,
+        description=_RECONCILER_HELP,
+    )
+    reconciler_parser.set_defaults(func=_run_reconciler)
+
+    pending_income_parser = subparsers.add_parser(
+        "pending-income", help="Move pending income transactions to today."
+    )
+    pending_income_parser.set_defaults(func=_run_pending_income)
+
+    zero_out_parser = subparsers.add_parser(
+        "zero-out",
+        help="Set a category's budgeted amount to zero across a month range.",
+    )
+    zero_out_parser.set_defaults(func=_run_zero_out)
+    return parser
+
+
+def _run_reconciler(argv: Sequence[str]) -> int:
+    return reconciler.run(argv)
+
+
+def _run_pending_income(argv: Sequence[str]) -> int:
+    return pending_income.run(argv)
+
+
+def _run_zero_out(argv: Sequence[str]) -> int:
+    return zero_out.run(argv)
+
+
+def main(argv: Sequence[str] = ()) -> int:
+    argv = argv or sys.argv[1:]
+    if not argv:
+        build_parser().print_help()
+        return 0
+    match argv[0]:
+        case "reconciler":
+            return _run_reconciler(argv[1:])
+        case "pending-income":
+            return _run_pending_income(argv[1:])
+        case "zero-out":
+            return _run_zero_out(argv[1:])
+
+    parser = build_parser()
+    parser.parse_args(argv)
+    raise AssertionError("subcommand parser should have exited")

manager_for_ynab-1.0.0/manager_for_ynab/_version.py

@@ -0,0 +1,13 @@
+from configparser import ConfigParser
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version
+from pathlib import Path
+
+
+def get_version(distribution: str = "manager_for_ynab") -> str:
+    try:
+        return version(distribution)
+    except PackageNotFoundError:
+        config = ConfigParser()
+        config.read(Path(__file__).resolve().parent.parent / "setup.cfg")
+        return config["metadata"]["version"]

manager_for_ynab-1.0.0/manager_for_ynab/pending_income/__init__.py

@@ -0,0 +1,141 @@
+import argparse
+import asyncio
+import sqlite3
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date
+from importlib.resources import files
+from pathlib import Path
+from typing import Never
+from typing import TYPE_CHECKING
+
+import rich
+import ynab
+from rich.table import Table
+from sqlite_export_for_ynab import default_db_path
+from sqlite_export_for_ynab import sync
+from tldm import tldm
+
+from manager_for_ynab._auth import resolve_token
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+_PACKAGE = "manager-for-ynab pending-income"
+_PENDING_INCOME_SQL = (
+    files("manager_for_ynab.pending_income").joinpath("pending_income.sql").read_text()
+)
+
+
+@dataclass(frozen=True)
+class Transaction:
+    id: str
+    plan_id: str
+    account_name: str
+    payee_name: str
+    amount_formatted: str
+    date: str
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=_PACKAGE)
+    parser.add_argument(
+        "--sqlite-export-for-ynab-db", type=Path, default=default_db_path()
+    )
+    parser.add_argument("--sqlite-export-for-ynab-full-refresh", action="store_true")
+    parser.add_argument("--for-real", action="store_true")
+    return parser
+
+
+def run(argv: Sequence[str] | None = None, *, token_override: str | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    db: Path = args.sqlite_export_for_ynab_db
+    full_refresh: bool = args.sqlite_export_for_ynab_full_refresh
+    for_real: bool = args.for_real
+
+    token = resolve_token(token_override)
+
+    print("** Refreshing SQLite DB **")
+    asyncio.run(sync(token, db, full_refresh))
+    print("** Done **")
+
+    with sqlite3.connect(db) as con:
+        con.row_factory = sqlite3.Row
+        txns_by_plan = fetch_pending_income(con.cursor())
+
+    total_txns = sum(len(txns) for txns in txns_by_plan.values())
+    print(f"Found {total_txns} income transaction(s) to update.")
+    if total_txns == 0:
+        return 0
+
+    print_found_txns([txn for txns in txns_by_plan.values() for txn in txns])
+
+    grouped = build_updates(txns_by_plan, date.today())
+
+    if not for_real:
+        print("Use --for-real to actually update transactions.")
+        return 0
+
+    api_client = ynab.TransactionsApi(
+        ynab.ApiClient(ynab.Configuration(access_token=token))
+    )
+
+    with tldm[Never](
+        total=total_txns, desc=f"Updating {total_txns} transaction(s)"
+    ) as progress:
+        for plan_id, txns in grouped.items():
+            api_client.update_transactions(
+                plan_id, ynab.PatchTransactionsWrapper(transactions=txns)
+            )
+            progress.update(len(txns))
+
+    return 0
+
+
+def build_updates(
+    txns_by_plan: dict[str, list[Transaction]], today: date
+) -> dict[str, list[ynab.SaveTransactionWithIdOrImportId]]:
+    grouped: dict[str, list[ynab.SaveTransactionWithIdOrImportId]] = defaultdict(list)
+    for plan_id, txns in txns_by_plan.items():
+        grouped[plan_id].extend(
+            ynab.SaveTransactionWithIdOrImportId(id=txn.id, date=today) for txn in txns
+        )
+    return grouped
+
+
+def fetch_pending_income(cur: sqlite3.Cursor) -> dict[str, list[Transaction]]:
+    txns = cur.execute(_PENDING_INCOME_SQL).fetchall()
+
+    txns_by_plan: dict[str, list[Transaction]] = defaultdict(list)
+    for txn in txns:
+        txns_by_plan[txn["plan_id"]].append(
+            Transaction(
+                id=txn["id"],
+                plan_id=txn["plan_id"],
+                account_name=txn["account_name"],
+                payee_name=txn["payee_name"],
+                amount_formatted=txn["amount_formatted"],
+                date=txn["date"],
+            )
+        )
+
+    return txns_by_plan
+
+
+def print_found_txns(found_txns: list[Transaction]) -> None:
+    table = Table(title="Pending Income Transactions")
+    table.add_column("Date")
+    table.add_column("Account")
+    table.add_column("Payee")
+    table.add_column("Amount", justify="right")
+
+    for txn in found_txns:
+        table.add_row(
+            txn.date, txn.account_name, txn.payee_name or "", txn.amount_formatted
+        )
+
+    rich.print(table)
+
+
+__all__ = [run.__name__]

manager_for_ynab-1.0.0/manager_for_ynab/pending_income/pending_income.sql

@@ -0,0 +1,24 @@
+SELECT
+    transactions.id
+    , transactions.plan_id
+    , transactions.account_name
+    , transactions.payee_name
+    , transactions.amount_formatted
+    , transactions."date"
+FROM transactions
+WHERE
+    TRUE
+    AND transactions.cleared = 'uncleared'
+    AND transactions."date" < DATE('now', 'localtime')
+    AND transactions.amount > 0
+    AND NOT transactions.deleted
+    AND SUBSTR(transactions."date", 6, 2) = SUBSTR(DATE(), 6, 2)
+    AND transactions.id NOT IN (
+        SELECT subtransactions.transfer_transaction_id
+        FROM subtransactions
+        WHERE
+            subtransactions.transfer_transaction_id IS NOT NULL
+            AND NOT subtransactions.deleted
+    )
+ORDER BY transactions."date", transactions.account_name, transactions.payee_name
+;