manager-for-ynab 1.0.0__py2.py3-none-any.whl

manager_for_ynab/__init__.py

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

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/_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/_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/_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/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/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
+;

manager_for_ynab/reconciler/__init__.py

@@ -0,0 +1,433 @@
+import argparse
+import asyncio
+import itertools
+import os
+import re
+import sqlite3
+from dataclasses import dataclass
+from dataclasses import field
+from decimal import Decimal
+from pathlib import Path
+from typing import Never
+from typing import TYPE_CHECKING
+
+import aiohttp
+from babel.numbers import format_currency
+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 Callable
+    from collections.abc import Iterable
+    from collections.abc import Sequence
+
+
+_PACKAGE = "manager-for-ynab reconciler"
+
+_NEG_BAL_ACCT_TYPES = frozenset(("checking", "savings", "cash"))
+
+_LOCALE_EN_US = "en_US"
+_DESCRIPTION = "Find and automatically reconciles unreconciled transactions."
+
+
+@dataclass(frozen=True)
+class Transaction:
+    plan_id: str
+    id: str
+    amount: Decimal
+    amount_formatted: str
+    payee: str
+    cleared: str
+
+    def pretty(self) -> str:
+        return f"{self.amount_formatted:>10} - {self.payee}"
+
+
+@dataclass(frozen=True)
+class PlanAccount:
+    plan_id: str
+    account_name: str
+    account_id: str
+    account_type: str
+    cleared_balance: Decimal
+    currency: str
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=_PACKAGE, description=_DESCRIPTION)
+    parser.add_argument(
+        "--mode",
+        choices=("single", "batch"),
+        default="single",
+        help="Reconciliation mode. `single` uses --account-like/--target. `batch` uses --account-target-pairs.",
+    )
+    parser.add_argument(
+        "--account-like",
+        help="SQL LIKE pattern to match account name (must match exactly one account)",
+    )
+    parser.add_argument(
+        "--target",
+        type=lambda s: Decimal(re.sub("[,$]", "", s)),
+        help="Target balance to match towards for reconciliation",
+    )
+    parser.add_argument(
+        "--account-target-pairs",
+        nargs="+",
+        help="Batch mode only. Account pattern/target pairs in `ACCOUNT_LIKE=TARGET` format (example: `Checking%%=500.30`).",
+    )
+    parser.add_argument(
+        "--for-real",
+        action="store_true",
+        help="Whether to actually perform the reconciliation. If unset, this tool only prints the transactions that would be reconciled.",
+    )
+    parser.add_argument(
+        "--sqlite-export-for-ynab-db",
+        type=Path,
+        default=default_db_path(),
+        help="Path to sqlite-export-for-ynab SQLite DB file (respects sqlite-export-for-ynab configuration; if unset, will be %(default)s)",
+    )
+    parser.add_argument(
+        "--sqlite-export-for-ynab-full-refresh",
+        action="store_true",
+        help="Whether to **DROP ALL TABLES** and fetch all plan data again. If unset, this tool only does an incremental refresh",
+    )
+    return parser
+
+
+async def async_run(
+    argv: Sequence[str] | None = None, *, token_override: str | None = None
+) -> int:
+    args = build_parser().parse_args(argv)
+    mode: str = args.mode
+    account_like: str | None = args.account_like
+    raw_target: Decimal | None = args.target
+    account_target_pairs: list[str] | None = args.account_target_pairs
+    for_real: bool = args.for_real
+    db: Path = args.sqlite_export_for_ynab_db
+    full_refresh: bool = args.sqlite_export_for_ynab_full_refresh
+
+    if mode == "single":
+        if account_target_pairs:
+            raise ValueError(
+                "`--account-target-pairs` is only valid when `--mode batch` is selected."
+            )
+        if account_like is None or raw_target is None:
+            raise ValueError(
+                "`--mode single` requires both `--account-like` and `--target`."
+            )
+        account_likes = [_normalize_account_like(account_like)]
+        raw_targets = [raw_target]
+    else:
+        assert mode == "batch"
+        if account_like is not None or raw_target is not None:
+            raise ValueError(
+                "`--mode batch` cannot be used with `--account-like` or `--target`; use `--account-target-pairs` instead."
+            )
+        if not account_target_pairs:
+            raise ValueError("`--mode batch` requires `--account-target-pairs`.")
+        account_likes, raw_targets = _parse_account_targets(account_target_pairs)
+
+    token = resolve_token(token_override)
+
+    print("** Refreshing SQLite DB **")
+    await sync(token, db, full_refresh)
+    print("** Done **")
+
+    with sqlite3.connect(db) as con:
+        con.row_factory = sqlite3.Row
+
+        cur = con.cursor()
+
+        plan_accts = fetch_plan_accts(cur, account_likes)
+        transactions = fetch_transactions(cur, plan_accts)
+
+    rets = list(
+        await asyncio.gather(
+            *(
+                asyncio.create_task(
+                    _reconcile_account(
+                        token,
+                        acct,
+                        txns,
+                        rt * (-1 if acct.account_type in _NEG_BAL_ACCT_TYPES else 1),
+                        for_real,
+                    )
+                )
+                for rt, acct, txns in zip(
+                    raw_targets, plan_accts, transactions, strict=True
+                )
+            )
+        )
+    )
+
+    print("Done.")
+
+    return max(rets)
+
+
+def _parse_account_targets(
+    account_target_pairs: list[str],
+) -> tuple[list[str], list[Decimal]]:
+    account_likes: list[str] = []
+    raw_targets: list[Decimal] = []
+    for pair in account_target_pairs:
+        account_like, _, target = pair.partition("=")
+        account_likes.append(_normalize_account_like(account_like))
+        raw_targets.append(Decimal(re.sub("[,$]", "", target)))
+    return account_likes, raw_targets
+
+
+def _normalize_account_like(account_like: str) -> str:
+    if "%" in account_like or "_" in account_like:
+        return account_like
+
+    return f"%{account_like}%"
+
+
+async def _reconcile_account(
+    token: str,
+    plan_acct: PlanAccount,
+    transactions: list[Transaction],
+    target: Decimal,
+    for_real: bool,
+) -> int:
+    prefix = f"[{plan_acct.account_name}]"
+
+    to_reconcile, balance_met = find_to_reconcile(
+        transactions,
+        plan_acct.cleared_balance,
+        target,
+        progress_desc=f"{prefix} Testing combinations",
+    )
+
+    if not to_reconcile:
+        if balance_met:
+            print(f"{prefix} Balance already reconciled to target")
+            return 0
+        pretty_target = format_currency(
+            target, currency=plan_acct.currency, locale=_LOCALE_EN_US
+        )
+        print(f"{prefix} No match found for target {pretty_target}")
+        return 1
+
+    print(
+        f"{prefix} Match found:",
+        *(
+            f"{prefix} * {t.pretty()}"
+            for t in sorted(to_reconcile, key=lambda t: t.amount)
+        ),
+        sep=os.linesep,
+    )
+
+    if for_real:
+        await do_reconcile(
+            token,
+            plan_acct.plan_id,
+            to_reconcile,
+            progress_desc=f"{prefix} Reconciling",
+        )
+
+    return 0
+
+
+def fetch_plan_accts(
+    cur: sqlite3.Cursor, account_likes: list[str]
+) -> list[PlanAccount]:
+    plan_accts = cur.execute(
+        f"""
+            SELECT
+                plans.id as plan_id
+                , plans.name as plan_name
+                , accounts.name as account_name
+                , accounts.type as account_type
+                , accounts.id as account_id
+                , accounts.type as account_type
+                , accounts.cleared_balance
+                , plans.currency_format_iso_code
+            FROM accounts
+            JOIN plans
+                ON accounts.plan_id = plans.id
+            WHERE
+                TRUE
+                AND NOT deleted
+                AND NOT closed
+                AND ({" OR ".join("accounts.name LIKE ?" for _ in account_likes)})
+            ORDER BY
+                CASE
+                    {" ".join(f"WHEN accounts.name LIKE ? THEN {i}" for i, _ in enumerate(account_likes))}
+                END
+            """,
+        (*account_likes, *account_likes),
+    ).fetchall()
+
+    if len(plan_accts) != len(account_likes):
+        raise ValueError(
+            f"\n❌ Must have {len(account_likes)} total account matches for the supplied pairs, but instead found: {_pretty(plan_accts)}\nChange account LIKE patterns to be more precise and try again."
+        )
+
+    return [
+        PlanAccount(
+            plan_id=pl["plan_id"],
+            account_name=pl["account_name"],
+            account_id=pl["account_id"],
+            cleared_balance=Decimal(-pl["cleared_balance"]) / 1000,
+            account_type=pl["account_type"],
+            currency=pl["currency_format_iso_code"],
+        )
+        for pl in plan_accts
+    ]
+
+
+def _pretty(plan_accts: list[sqlite3.Row]) -> str:
+    if not plan_accts:
+        return "nothing!"
+
+    return "\n" + "\n".join(
+        sorted(f" * {pl['plan_name']} - {pl['account_name']}" for pl in plan_accts)
+    )
+
+
+def fetch_transactions(
+    cur: sqlite3.Cursor, plan_accts: list[PlanAccount]
+) -> list[list[Transaction]]:
+    assert plan_accts
+
+    unreconciled = cur.execute(
+        f"""
+            SELECT
+                id
+                , plan_id
+                , account_id
+                , amount
+                , amount_formatted
+                , payee_name
+                , cleared
+            FROM transactions
+            WHERE
+                TRUE
+                AND cleared != 'reconciled'
+                AND NOT deleted
+                AND ({" OR ".join("account_id = ?" for _ in plan_accts)})
+            ORDER BY date
+            """,
+        tuple(pl.account_id for pl in plan_accts),
+    ).fetchall()
+
+    grouped: dict[str, list[Transaction]] = {pl.account_id: [] for pl in plan_accts}
+    for u in unreconciled:
+        grouped[u["account_id"]].append(
+            Transaction(
+                u["plan_id"],
+                u["id"],
+                Decimal(-u["amount"]) / 1000,
+                u["amount_formatted"],
+                u["payee_name"],
+                u["cleared"],
+            )
+        )
+
+    return list(grouped.values())
+
+
+def find_to_reconcile(
+    transactions: list[Transaction],
+    account_balance: Decimal,
+    target: Decimal,
+    progress_desc: str,
+) -> tuple[tuple[Transaction, ...], bool]:
+    cleared, uncleared = partition(transactions, lambda t: t.cleared == "cleared")
+
+    reconciled_balance = account_balance - sum(t.amount for t in cleared)
+    if reconciled_balance == target and not cleared:
+        return (), True
+
+    with tldm[Never](
+        total=2 ** len(uncleared), desc=progress_desc, complete_bar_on_early_finish=True
+    ) as pbar:
+        for n in range(len(uncleared) + 1):
+            for combo in itertools.combinations(uncleared, n):
+                if (
+                    reconciled_balance
+                    + sum(t.amount for t in itertools.chain(cleared, combo))
+                    == target
+                ):
+                    return tuple(itertools.chain(cleared, combo)), True
+                pbar.update()
+
+    return (), False
+
+
+async def do_reconcile(
+    token: str, plan_id: str, to_reconcile: Sequence[Transaction], progress_desc: str
+) -> None:
+    yc = YnabClient(token)
+    with tldm[Never](total=len(to_reconcile), desc=progress_desc) as pbar:
+        async with aiohttp.ClientSession() as session:
+            try:
+                await yc.reconcile(session, pbar, plan_id, [t.id for t in to_reconcile])
+            except Error4034:
+                await asyncio.gather(
+                    *(
+                        yc.reconcile(session, pbar, to_reconcile[0].plan_id, [t.id])
+                        for t in to_reconcile
+                    )
+                )
+
+
+def partition[T](
+    items: Iterable[T], func: Callable[[T], bool]
+) -> tuple[list[T], list[T]]:
+    trues, falses = [], []
+    for i in items:
+        if func(i):
+            trues.append(i)
+        else:
+            falses.append(i)
+    return trues, falses
+
+
+class Error4034(Exception):
+    """Raised when an internal YNAB rate-limit is reached. A workaround is to reconcile one-at-a-time."""
+
+
+@dataclass
+class YnabClient:
+    token: str
+    headers: dict[str, str] = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.headers = {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    async def reconcile(
+        self,
+        session: aiohttp.ClientSession,
+        pbar: tldm[Never],
+        plan_id: str,
+        transaction_ids: list[str],
+    ) -> None:
+        reconciled = [{"id": t, "cleared": "reconciled"} for t in transaction_ids]
+
+        url = f"https://api.ynab.com/v1/plans/{plan_id}/transactions"
+
+        async with session.request(
+            "PATCH", url, headers=self.headers, json={"transactions": reconciled}
+        ) as resp:
+            body = await resp.json()
+
+        if body.get("error", {}).get("id") == "403.4":
+            raise Error4034()
+
+        pbar.update(len(transaction_ids))
+
+
+def run(argv: Sequence[str] | None = None, *, token_override: str | None = None) -> int:
+    return asyncio.run(async_run(argv, token_override=token_override))
+
+
+__all__ = [default_db_path.__name__, run.__name__, sync.__name__]

manager_for_ynab/zero_out/__init__.py

@@ -0,0 +1,213 @@
+import argparse
+import asyncio
+import datetime
+import re
+from concurrent.futures import ThreadPoolExecutor
+from typing import TYPE_CHECKING
+
+import ynab
+
+from manager_for_ynab._auth import resolve_token
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from collections.abc import Sequence
+
+
+_PACKAGE = "manager-for-ynab zero-out"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=_PACKAGE,
+        description="Zero out planned amount for a category from a start year-month through the end month.",
+    )
+    parser.add_argument(
+        "--plan-id",
+        help="YNAB plan ID. If omitted, uses the most recently updated one.",
+    )
+    parser.add_argument(
+        "--category-name",
+        required=True,
+        help="Category name to update (matched with a regex but must match uniquely).",
+    )
+    parser.add_argument(
+        "--start",
+        type=parse_year_month,
+        required=True,
+        help="Start year-month (e.g. 2025-01).",
+    )
+    parser.add_argument(
+        "--end",
+        type=parse_year_month,
+        help="End year-month inclusive (e.g. 2025-06). Defaults to current month.",
+    )
+    parser.add_argument(
+        "--for-real",
+        action="store_true",
+        help="Apply the updates instead of only previewing them.",
+    )
+    return parser
+
+
+def parse_year_month(raw: str) -> tuple[int, int]:
+    year, month = tuple(map(int, raw.split("-")))
+    if month < 1 or month > 12:
+        raise argparse.ArgumentTypeError(f"Invalid month in {raw!r}. Expected YYYY-MM.")
+    return year, month
+
+
+def month_range(
+    start_year: int, start_month: int, end_year: int, end_month: int
+) -> Generator[tuple[int, int]]:
+    return (
+        (year, month0 + 1)
+        for year, month0 in (
+            divmod(i, 12)
+            for i in range(start_year * 12 + start_month - 1, end_year * 12 + end_month)
+        )
+    )
+
+
+def format_months(months: tuple[tuple[int, int], ...]) -> list[str]:
+    return [f"{year}-{month:02d}" for year, month in months]
+
+
+def _update_month_category(
+    categories_api: ynab.CategoriesApi,
+    plan_id: str,
+    category_id: str,
+    year: int,
+    month: int,
+) -> tuple[str, str | None]:
+    month_str = f"{year}-{month:02d}"
+    try:
+        categories_api.update_month_category(
+            plan_id=plan_id,
+            month=datetime.date(year, month, 1),
+            category_id=category_id,
+            data=ynab.PatchMonthCategoryWrapper(
+                category=ynab.SaveMonthCategory(budgeted=0)
+            ),
+        )
+        return month_str, None
+    except ynab.ApiException as e:
+        return month_str, f"{e}"
+
+
+def _get_plan_id(plans_api: ynab.PlansApi, plan_id: str | None) -> str:
+    if plan_id:
+        return plan_id
+
+    try:
+        plans_response = plans_api.get_plans()
+    except ynab.ApiException as e:
+        raise RuntimeError(f"Failed to fetch plans: {e}") from e
+
+    plans = plans_response.data.plans
+    if not plans:
+        raise RuntimeError("No plans found in this YNAB account.")
+
+    plan = max(plans, key=lambda b: b.last_modified_on or datetime.datetime.min)
+    print(f"Using plan: {plan.name} ({plan.id})")
+    return str(plan.id)
+
+
+def _get_category_id(
+    categories_api: ynab.CategoriesApi, plan_id: str, category_name: str
+) -> tuple[str, str]:
+    try:
+        cats_resp = categories_api.get_categories(plan_id)
+    except ynab.ApiException as e:
+        raise RuntimeError(f"Failed to fetch categories: {e}") from e
+
+    matching = [
+        category
+        for group in cats_resp.data.category_groups
+        for category in group.categories
+        if re.search(category_name, category.name, re.IGNORECASE)
+    ]
+    if len(matching) != 1:
+        names = ", ".join(category.name for category in matching)
+        raise RuntimeError(
+            f"Found {len(matching)} categories matching '{category_name}' - {names}."
+        )
+
+    category = matching[0]
+    return str(category.id), category.name
+
+
+async def _run_updates(
+    categories_api: ynab.CategoriesApi,
+    plan_id: str,
+    category_id: str,
+    months: tuple[tuple[int, int], ...],
+) -> None:
+    with ThreadPoolExecutor(max_workers=5) as executor:
+        tasks = tuple(
+            asyncio.get_running_loop().run_in_executor(
+                executor,
+                _update_month_category,
+                categories_api,
+                plan_id,
+                category_id,
+                year,
+                month,
+            )
+            for year, month in months
+        )
+        for task in tasks:
+            month_str, err = await task
+            if err is None:
+                print(f"{month_str}: set planned to 0.")
+            else:
+                print(f"Failed to update month {month_str}: {err}")
+
+
+def run(argv: Sequence[str] | None = None, *, token_override: str | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    token = resolve_token(token_override)
+
+    configuration = ynab.Configuration(access_token=token)
+
+    with ynab.ApiClient(configuration) as api_client:
+        plans_api = ynab.PlansApi(api_client)
+        categories_api = ynab.CategoriesApi(api_client)
+
+        try:
+            plan_id = _get_plan_id(plans_api, args.plan_id)
+            category_id, category_name = _get_category_id(
+                categories_api, plan_id, args.category_name
+            )
+        except RuntimeError as e:
+            print(e)
+            return 1
+
+        print(f"Using category: {category_name} ({category_id})")
+
+        start_year, start_month = args.start
+        if args.end:
+            end_year, end_month = args.end
+        else:
+            today = datetime.date.today()
+            end_year, end_month = today.year, today.month
+
+        months = tuple(month_range(start_year, start_month, end_year, end_month))
+        month_labels = format_months(months)
+        if not month_labels:
+            print("No months selected.")
+            return 0
+
+        print("Months to update:", ", ".join(month_labels))
+        if not args.for_real:
+            print("Use --for-real to actually update categories.")
+            return 0
+
+        asyncio.run(_run_updates(categories_api, plan_id, category_id, months))
+
+    print("Done.")
+    return 0
+
+
+__all__ = [run.__name__]

manager_for_ynab-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+manager_for_ynab/__init__.py,sha256=u_Xt3XTEMY0grnPdERhQE9HxEacvcFZeqSphl7XvTms,67
+manager_for_ynab/__main__.py,sha256=W3d-XhwSgHNGVcSGPjovgjxPa-n8yJ70k0ks0i0PY7Q,97
+manager_for_ynab/_auth.py,sha256=ztlEiW3xTFb6AqqgTcv0TXtagr8HFcsuAZ3avajZcJU,446
+manager_for_ynab/_main.py,sha256=FnnZz85D_4_UcOkdZDNt0nyUL5Mnx8OeefH-r4FtABI,2077
+manager_for_ynab/_version.py,sha256=lui3ULP0QBEzdZmmM38ta2joZi0jU3E65_A87rv1VGw,450
+manager_for_ynab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+manager_for_ynab/pending_income/__init__.py,sha256=A7Ow60WchGdVqxBxMYMxL72DCfxScB8w2U3l2NXc1FI,4143
+manager_for_ynab/pending_income/pending_income.sql,sha256=Hy-LR2L1z1mam8QvJoiNlrUmfWUPB4g77wzpnzx10aI,767
+manager_for_ynab/reconciler/__init__.py,sha256=gDQvdr8iiRi2o8mq77F8zdjRW4aAQsDPdg8AkWKsTkA,13236
+manager_for_ynab/zero_out/__init__.py,sha256=bR84GLXiv0EyDNB4SuE-yZL9BQNKqR43YfqKUpbjLuE,6292
+manager_for_ynab-1.0.0.dist-info/licenses/LICENSE,sha256=gQqRlt6eZUGXElH2Nxcy3fBX2_d1tmvo7cWfxFbVjI4,1062
+testing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+testing/fixtures.py,sha256=HNKbOuwvv60C-6EFHzTCefFUrQjdZKx53mOY0aCc-1M,566
+testing/seed.sql,sha256=CNOTw7T6y8XgonlCUu-0SbvR3CtzGf8QOZvAvzA2Sv8,4737
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+manager_for_ynab-1.0.0.dist-info/METADATA,sha256=A8a6OOcEstxQKgjK5KOnL8IKy_NeUcqHaF-Ru4SFoQQ,1647
+manager_for_ynab-1.0.0.dist-info/WHEEL,sha256=TdQ5LtNwLuxTCjgxN51AgdU5w-KkB9ttmLbzjTH02pg,109
+manager_for_ynab-1.0.0.dist-info/entry_points.txt,sha256=JMIqSKGvhZgjIdLhGqO5X6ktWQcEk0hlXx9n8wGfIm8,65
+manager_for_ynab-1.0.0.dist-info/top_level.txt,sha256=JzksQ-wlpJODt0PfAOlIQ_bgSl26CLEtBrmFcck6eQc,31
+manager_for_ynab-1.0.0.dist-info/RECORD,,

manager_for_ynab-1.0.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

manager_for_ynab-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+manager-for-ynab = manager_for_ynab._main:main

manager_for_ynab-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+manager_for_ynab
+testing
+tests

testing/fixtures.py

@@ -0,0 +1,31 @@
+import os.path
+import sqlite3
+from uuid import uuid4
+
+import pytest
+from aioresponses import aioresponses
+
+
+PLAN_ID_1 = str(uuid4())
+
+
+@pytest.fixture()
+def db(tmpdir):
+    with open(os.path.join(os.path.dirname(__file__), "seed.sql")) as f:
+        contents = f.read()
+
+    path = tmpdir / "db.sqlite"
+    with sqlite3.connect(path) as con:
+        con.executescript(contents)
+    yield str(path)
+
+
+@pytest.fixture
+def mock_aioresponses():
+    with aioresponses() as m:
+        yield m
+
+
+TOKEN = f"token-{uuid4()}"
+
+PLAN_ID = "a20542ae-bb3e-4282-8b3e-df3bdea4be10"

testing/seed.sql

@@ -0,0 +1,289 @@
+CREATE TABLE plans (
+    id TEXT PRIMARY KEY
+    , name TEXT
+    , currency_format_currency_symbol TEXT
+    , currency_format_iso_code TEXT
+)
+;
+
+INSERT INTO plans VALUES (
+    'a20542ae-bb3e-4282-8b3e-df3bdea4be10'
+    , 'My Plan'
+    , '$'
+    , 'USD'
+)
+;
+
+CREATE TABLE accounts (
+    id TEXT PRIMARY KEY
+    , plan_id TEXT
+    , cleared_balance INT
+    , closed BOOLEAN
+    , deleted BOOLEAN
+    , name TEXT
+    , type TEXT
+)
+;
+
+INSERT INTO accounts VALUES (
+    '8fe2a49b-17b9-47a1-8aaa-c60d661e7f25'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , 430000
+    , 0
+    , 0
+    , 'Checking'
+    , 'checking'
+)
+;
+
+INSERT INTO accounts VALUES (
+    'ab56a1c8-439e-4eaf-931b-37f2d68d1cf5'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , -200000
+    , 0
+    , 0
+    , 'Credit Card'
+    , 'creditCard'
+)
+;
+
+CREATE TABLE transactions (
+    id TEXT PRIMARY KEY
+    , plan_id TEXT
+    , account_id TEXT
+    , "date" TEXT
+    , amount INT
+    , amount_formatted TEXT
+    , payee_name TEXT
+    , cleared TEXT
+    , deleted BOOLEAN
+)
+;
+
+INSERT INTO transactions VALUES (
+    'ae3d9f6b-07f1-4c49-9137-5133c8bf0500'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Checking'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , 400000
+    , '-$400.00'
+    , 'Payee'
+    , 'reconciled'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    '9a97f337-28db-4c2d-990f-d9ec0e9bc765'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Checking'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , 30000
+    , '-$30.00'
+    , 'Payee'
+    , 'cleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    'c479c335-b54f-48b9-8b74-49a907f1b3f2'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Checking'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , 60000
+    , '-$60.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    '96817e5f-d272-4012-9790-38f8a8e2be90'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Checking'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , 20000
+    , '-$20.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    'eeef0922-b226-4f8a-bf00-66d4d98e348c'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Checking'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , 10000
+    , '-$10.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    '21c45599-4113-4888-9969-66d42553d870'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Credit Card'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , -400000
+    , '$400.00'
+    , 'Payee'
+    , 'reconciled'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    '956ff61f-b0e4-4f36-bf7d-f31d008ff7e4'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Credit Card'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , -30000
+    , '$30.00'
+    , 'Payee'
+    , 'cleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    'c9ca467d-e89d-4d0d-8356-f37d4f798c5f'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Credit Card'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , -60000
+    , '$60.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    '258b33fb-a2b2-4833-9274-05697c68ff1d'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Credit Card'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , -20000
+    , '$20.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;
+
+INSERT INTO transactions VALUES (
+    'd9faa297-f59e-4516-bcbf-664b298ff09e'
+    , (
+        SELECT id
+        FROM plans
+        ORDER BY id LIMIT 1
+    )
+    , (
+        SELECT id
+        FROM accounts
+        WHERE name = 'Credit Card'
+        ORDER BY id LIMIT 1
+    )
+    , '2025-08-01'
+    , -10000
+    , '$10.00'
+    , 'Payee'
+    , 'uncleared'
+    , 0
+)
+;