ynab-cli 0.3.0__py3-none-any.whl

ynab_cli/domain/use_cases/categories.py

@@ -0,0 +1,105 @@
+from collections.abc import AsyncIterator
+from typing import TypedDict
+
+from ynab_cli.adapters import ynab
+from ynab_cli.adapters.ynab import models, util
+from ynab_cli.adapters.ynab.api.categories import get_categories
+from ynab_cli.adapters.ynab.api.transactions import get_transactions_by_category
+from ynab_cli.domain import ports
+from ynab_cli.domain.constants import YNAB_API_URL
+from ynab_cli.domain.settings import Settings
+
+
+def _should_skip_category_or_group(category_or_group: models.Category | models.CategoryGroupWithCategories) -> bool:
+    if category_or_group.deleted:
+        return True
+    return False
+
+
+class ListUnusedParams(TypedDict):
+    pass
+
+
+async def list_unused(settings: Settings, io: ports.IO, params: ListUnusedParams) -> AsyncIterator[models.Category]:
+    async with ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token) as client:
+        try:
+            category_groups = (
+                await util.get_asyncio_detailed(
+                    io, get_categories.asyncio_detailed, settings.ynab.budget_id, client=client
+                )
+            ).data.category_groups
+            category_groups.sort(key=lambda cg: cg.name)
+
+            progress_total = len(category_groups)
+            for category_group in category_groups:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_category_or_group(category_or_group=category_group):
+                    continue
+
+                progress_total += len(category_group.categories)
+                category_group.categories.sort(key=lambda c: c.name)
+                for category in category_group.categories:
+                    await io.progress.update(total=progress_total, advance=1)
+
+                    if _should_skip_category_or_group(category_or_group=category):
+                        continue
+
+                    transactions = (
+                        await util.get_asyncio_detailed(
+                            io,
+                            get_transactions_by_category.asyncio_detailed,
+                            settings.ynab.budget_id,
+                            str(category.id),
+                            client=client,
+                        )
+                    ).data.transactions
+                    num_transactions = len(transactions)
+
+                    # List unused category if no transactions
+                    if not num_transactions:
+                        yield category
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")
+
+
+class ListAllParams(TypedDict):
+    pass
+
+
+async def list_all(settings: Settings, io: ports.IO, params: ListAllParams) -> AsyncIterator[models.Category]:
+    async with ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token) as client:
+        try:
+            category_groups = (
+                await util.get_asyncio_detailed(
+                    io, get_categories.asyncio_detailed, settings.ynab.budget_id, client=client
+                )
+            ).data.category_groups
+            category_groups.sort(key=lambda cg: cg.name)
+
+            progress_total = len(category_groups)
+            for category_group in category_groups:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_category_or_group(category_or_group=category_group):
+                    continue
+
+                progress_total += len(category_group.categories)
+                category_group.categories.sort(key=lambda c: c.name)
+                for category in category_group.categories:
+                    await io.progress.update(total=progress_total, advance=1)
+
+                    if _should_skip_category_or_group(category_or_group=category):
+                        continue
+
+                    yield category
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")

ynab_cli/domain/use_cases/payees.py

@@ -0,0 +1,232 @@
+import re
+from collections.abc import AsyncIterator
+from typing import TypedDict
+from uuid import UUID
+
+from rapidfuzz import fuzz
+
+from ynab_cli.adapters import ynab
+from ynab_cli.adapters.ynab import models, util
+from ynab_cli.adapters.ynab.api.payees import get_payees, update_payee
+from ynab_cli.adapters.ynab.api.transactions import get_transactions_by_payee
+from ynab_cli.domain import ports
+from ynab_cli.domain.constants import UNUSED_PREFIX, YNAB_API_URL
+from ynab_cli.domain.settings import Settings
+
+
+def _should_skip_payee(payee: models.Payee) -> bool:
+    if (
+        payee.deleted
+        or (payee.transfer_account_id and isinstance(payee.transfer_account_id, str))
+        or payee.name.startswith("Transfer : ")
+        or payee.name.startswith(UNUSED_PREFIX)
+        or payee.name in ["Starting Balance"]
+    ):
+        return True
+    return False
+
+
+def _normalize_name(name: str) -> str:
+    normalized_name = name.title().strip()
+    # Normalize possessive names
+    normalized_name = normalized_name.replace("'S", "'s")
+    # Normalize multiple whitespaces
+    normalized_name = re.sub(r"\s+", " ", normalized_name)
+    # Normalize domain names
+    m = re.search(r".+\.([a-zA-Z]{2,3})$", normalized_name)
+    if m:
+        normalized_name = normalized_name.replace(m.group(1), m.group(1).lower())
+
+    return normalized_name
+
+
+class NormalizeNamesParams(TypedDict):
+    pass
+
+
+async def normalize_names(
+    settings: Settings, io: ports.IO, params: NormalizeNamesParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[tuple[models.Payee, str]]:
+    if client is None:
+        client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+    async with client:
+        try:
+            payees = (
+                await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
+            ).data.payees
+            payees.sort(key=lambda p: p.name)
+
+            progress_total = len(payees)
+            for payee in payees:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_payee(payee=payee):
+                    continue
+
+                normalized_name = _normalize_name(payee.name)
+                if normalized_name != payee.name:
+                    yield (payee, normalized_name)
+
+                    if not settings.dry_run:
+                        await util.run_asyncio_detailed(
+                            io,
+                            update_payee.asyncio_detailed,
+                            settings.ynab.budget_id,
+                            str(payee.id),
+                            client=client,
+                            body=models.PatchPayeeWrapper(payee=models.SavePayee(name=normalized_name)),
+                        )
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")
+
+
+class ListDuplicatesParams(TypedDict):
+    pass
+
+
+async def list_duplicates(
+    settings: Settings, io: ports.IO, params: ListDuplicatesParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[tuple[models.Payee, models.Payee]]:
+    if client is None:
+        client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+    async with client:
+        try:
+            possible_duplicates: dict[tuple[UUID, str], list[tuple[UUID, str]]] = {}
+
+            payees = (
+                await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
+            ).data.payees
+            payees.sort(key=lambda p: p.name)
+
+            progress_total = len(payees)
+            for idx, payee in enumerate(payees):
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_payee(payee=payee):
+                    continue
+
+                filtered_payees = list(payees)
+                del filtered_payees[idx]
+
+                for filtered_payee in filtered_payees:
+                    if _should_skip_payee(payee=filtered_payee):
+                        continue
+
+                    normalized_payee_name = _normalize_name(payee.name).lower()
+                    normalized_filtered_payee_name = _normalize_name(filtered_payee.name).lower()
+                    if fuzz.ratio(normalized_payee_name, normalized_filtered_payee_name) > 70:
+                        # Check to see if we already tracked this possible duplicate in the other direction
+                        existing_possible_duplicates = possible_duplicates.get((filtered_payee.id, filtered_payee.name))
+                        if existing_possible_duplicates:
+                            if (payee.id, payee.name) in existing_possible_duplicates:
+                                continue
+
+                        possible_duplicates[(payee.id, payee.name)] = possible_duplicates.get(
+                            (payee.id, payee.name), []
+                        )
+                        possible_duplicates[(payee.id, payee.name)].append((filtered_payee.id, filtered_payee.name))
+
+                        yield (payee, filtered_payee)
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")
+
+
+class ListUnusedParams(TypedDict):
+    prefix_unused: bool
+
+
+async def list_unused(
+    settings: Settings, io: ports.IO, params: ListUnusedParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[models.Payee]:
+    if client is None:
+        client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+    async with client:
+        try:
+            payees = (
+                await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
+            ).data.payees
+            payees.sort(key=lambda p: p.name)
+
+            progress_total = len(payees)
+            for payee in payees:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_payee(payee=payee):
+                    continue
+
+                transactions = (
+                    await util.get_asyncio_detailed(
+                        io,
+                        get_transactions_by_payee.asyncio_detailed,
+                        settings.ynab.budget_id,
+                        str(payee.id),
+                        client=client,
+                    )
+                ).data.transactions
+                num_transactions = len(transactions)
+
+                # List unused payee if no transactions
+                if not num_transactions:
+                    yield payee
+
+                    # If prefix_unused is True, rename the payee
+                    if not settings.dry_run and params.get("prefix_unused", False):
+                        new_name = f"{UNUSED_PREFIX} {payee.name}"
+                        await util.run_asyncio_detailed(
+                            io,
+                            update_payee.asyncio_detailed,
+                            settings.ynab.budget_id,
+                            str(payee.id),
+                            client=client,
+                            body=models.PatchPayeeWrapper(payee=models.SavePayee(name=new_name)),
+                        )
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")
+
+
+class ListAllParams(TypedDict):
+    pass
+
+
+async def list_all(
+    settings: Settings, io: ports.IO, params: ListAllParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[models.Payee]:
+    if client is None:
+        client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+    async with client:
+        try:
+            payees = (
+                await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
+            ).data.payees
+            payees.sort(key=lambda p: p.name)
+
+            progress_total = len(payees)
+            for payee in payees:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_payee(payee=payee):
+                    continue
+
+                yield payee
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")

ynab_cli/domain/use_cases/transactions.py

@@ -0,0 +1,93 @@
+from collections.abc import AsyncIterator
+from typing import TypedDict
+
+import rule_engine
+
+from ynab_cli.adapters import ynab
+from ynab_cli.adapters.ynab import models, util
+from ynab_cli.adapters.ynab.api.transactions import get_transactions, update_transactions
+from ynab_cli.domain import ports
+from ynab_cli.domain.constants import YNAB_API_URL
+from ynab_cli.domain.models import rules
+from ynab_cli.domain.settings import Settings
+
+
+def _should_skip_transaction(transaction: models.TransactionDetail) -> bool:
+    if transaction.deleted or transaction.category_name in ["Split"]:
+        return True
+    return False
+
+
+def _get_save_transaction(
+    transaction_detail: models.TransactionDetail,
+    transaction_rules: rules.TransactionRules,
+) -> models.SaveTransactionWithIdOrImportId | None:
+    transaction_detail_dict = transaction_detail.to_dict()
+
+    context = rule_engine.Context(default_value=None)
+    for rule in transaction_rules.transaction_rules:
+        if any(rule_engine.Rule(rule_str, context=context).matches(transaction_detail_dict) for rule_str in rule.rules):
+            if rule.patch:
+                save_transaction_dict = rule.patch.to_dict()
+                save_transaction_dict["id"] = transaction_detail.id
+                save_transaction_dict["import_id"] = transaction_detail.import_id
+
+                save_transaction = models.SaveTransactionWithIdOrImportId.from_dict(save_transaction_dict)
+
+                return save_transaction
+
+    return None
+
+
+class ApplyRulesParams(TypedDict):
+    transaction_rules: rules.TransactionRules
+
+
+async def apply_rules(
+    settings: Settings, io: ports.IO, params: ApplyRulesParams
+) -> AsyncIterator[tuple[models.TransactionDetail, models.SaveTransactionWithIdOrImportId]]:
+    async with ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token) as client:
+        try:
+            transactions = (
+                await util.get_asyncio_detailed(
+                    io,
+                    get_transactions.asyncio_detailed,
+                    settings.ynab.budget_id,
+                    client=client,
+                    type_=models.GetTransactionsType.UNAPPROVED,
+                )
+            ).data.transactions
+            transactions.sort(key=lambda t: t.date)
+
+            save_transactions = []
+
+            progress_total = len(transactions)
+            for transaction in transactions:
+                await io.progress.update(total=progress_total, advance=1)
+
+                if _should_skip_transaction(transaction=transaction):
+                    continue
+
+                save_transaction = _get_save_transaction(
+                    transaction_detail=transaction, transaction_rules=params["transaction_rules"]
+                )
+                if save_transaction:
+                    yield (transaction, save_transaction)
+
+                    if not settings.dry_run:
+                        save_transactions.append(save_transaction)
+
+            if save_transactions:
+                await util.run_asyncio_detailed(
+                    io,
+                    update_transactions.asyncio_detailed,
+                    settings.ynab.budget_id,
+                    client=client,
+                    body=models.PatchTransactionsWrapper(transactions=save_transactions),
+                )
+
+        except util.ApiError as e:
+            if e.status_code == 429:
+                await io.print("API rate limit exceeded. Try again later, or get a new access token.")
+            else:
+                await io.print(f"Exception when calling YNAB: {e}\n")

ynab_cli/host/__init__.py

@@ -0,0 +1,14 @@
+import os
+
+from dotenv import load_dotenv
+
+cwd = os.getcwd()
+dot_env_path = os.path.join(cwd, ".env")
+
+
+def setup_env() -> None:
+    if os.path.exists(dot_env_path):
+        load_dotenv(dot_env_path)
+
+
+setup_env()

ynab_cli/host/cli.py

@@ -0,0 +1,37 @@
+import click
+from click_default_group import DefaultGroup
+
+from ynab_cli.domain.settings import Settings
+from ynab_cli.host.click.cli import run
+from ynab_cli.host.constants import CONTEXT_KEY_SETTINGS, ENV_PREFIX
+from ynab_cli.host.textual.cli import tui
+
+
+@click.group(cls=DefaultGroup, default="tui", default_if_no_args=True)
+@click.option("--dry-run", is_flag=True, default=False, help="Run without making any changes.")
+@click.option("--debug", is_flag=True, default=False, help="Enable debug mode for more verbose output.")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    dry_run: bool,
+    debug: bool,
+) -> None:
+    """Main entrypoint."""
+
+    ctx.ensure_object(dict)
+    ctx.obj[CONTEXT_KEY_SETTINGS] = Settings(dry_run=dry_run, debug=debug)
+
+
+cli.add_command(run)
+cli.add_command(tui)
+
+
+def main() -> None:
+    cli(
+        auto_envvar_prefix=ENV_PREFIX,
+        obj={},  # click context object
+    )
+
+
+if __name__ == "__main__":
+    main()

ynab_cli/host/click/cli.py

@@ -0,0 +1,44 @@
+import logging
+
+import click
+from rich.logging import RichHandler
+
+from ynab_cli.domain.settings import Settings, YnabSettings
+from ynab_cli.host.click.commands import categories, payees, transactions
+from ynab_cli.host.constants import CONTEXT_KEY_SETTINGS, ENV_PREFIX
+
+
+@click.group()
+@click.option(
+    "--access-token",
+    prompt=True,
+    hide_input=True,
+    envvar=f"{ENV_PREFIX}_ACCESS_TOKEN",
+    show_envvar=True,
+    help="YNAB API access token.",
+)
+@click.option("--budget-id", prompt=True, envvar=f"{ENV_PREFIX}_BUDGET_ID", show_envvar=True, help="YNAB budget ID.")
+@click.pass_context
+def run(
+    ctx: click.Context,
+    access_token: str,
+    budget_id: str,
+) -> None:
+    """Main entrypoint for YNAB CLI commands."""
+
+    ctx.ensure_object(dict)
+    settings: Settings = ctx.obj.get(CONTEXT_KEY_SETTINGS, Settings())
+    settings.ynab = YnabSettings(access_token=access_token, budget_id=budget_id)
+    ctx.obj[CONTEXT_KEY_SETTINGS] = settings
+
+    logging.basicConfig(
+        level="DEBUG" if settings.debug else "WARNING",  # NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler()],
+    )
+
+
+run.add_command(payees.payees)
+run.add_command(categories.categories)
+run.add_command(transactions.transactions)

ynab_cli/host/click/commands/categories.py

@@ -0,0 +1,92 @@
+import asyncio
+
+import click
+from rich.table import Table
+
+from ynab_cli.adapters.rich import io
+from ynab_cli.domain.settings import Settings
+from ynab_cli.domain.use_cases import categories as use_cases
+from ynab_cli.host.click.commands.rich.progress_table import ProgressTable
+from ynab_cli.host.constants import CONTEXT_KEY_SETTINGS
+
+
+async def _list_unused(settings: Settings) -> None:
+    params: use_cases.ListUnusedParams = {}
+
+    table = Table(title="Unused Categories")
+    table.add_column("Category Group ID")
+    table.add_column("Category Group Name")
+    table.add_column("Category ID")
+    table.add_column("Category Name")
+
+    console = None
+    with ProgressTable(table) as progress:
+        console = progress.console
+
+        task_id = progress.add_task("Loading unused categories...")
+        async for category in use_cases.list_unused(settings, io.RichIO((progress, task_id)), params):
+            table.add_row(
+                str(category.category_group_id),
+                str(category.category_group_name),
+                str(category.id),
+                str(category.name),
+            )
+
+    if console:
+        console.print(table)
+
+
+async def _list_all(settings: Settings) -> None:
+    params: use_cases.ListAllParams = {}
+
+    table = Table(title="All Categories")
+    table.add_column("Category Group ID")
+    table.add_column("Category Group Name")
+    table.add_column("Category ID")
+    table.add_column("Category Name")
+
+    console = None
+    with ProgressTable(table) as progress:
+        console = progress.console
+
+        task_id = progress.add_task("Loading all categories...")
+        async for category in use_cases.list_all(settings, io.RichIO((progress, task_id)), params):
+            table.add_row(
+                str(category.category_group_id),
+                str(category.category_group_name),
+                str(category.id),
+                str(category.name),
+            )
+
+    if console:
+        console.print(table)
+
+
+@click.command()
+@click.pass_context
+def list_unused(ctx: click.Context) -> None:
+    """List unused categories in the YNAB budget."""
+
+    ctx.ensure_object(dict)
+    asyncio.run(_list_unused(ctx.obj.get(CONTEXT_KEY_SETTINGS, Settings())))
+
+
+@click.command()
+@click.pass_context
+def list_all(ctx: click.Context) -> None:
+    """List all categories in the YNAB budget."""
+
+    ctx.ensure_object(dict)
+    asyncio.run(_list_all(ctx.obj.get(CONTEXT_KEY_SETTINGS, Settings())))
+
+
+@click.group()
+@click.pass_context
+def categories(ctx: click.Context) -> None:
+    """Manage YNAB categories in the YNAB budget."""
+
+    ctx.ensure_object(dict)
+
+
+categories.add_command(list_unused)
+categories.add_command(list_all)