ynab-cli 0.5.3__tar.gz → 0.6.0__tar.gz

ynab_cli-0.6.0/.github/.copilot-instructions.md

@@ -0,0 +1,191 @@
+# YNAB CLI - Copilot Instructions
+
+## Project Overview
+
+This is a command-line interface for interacting with YNAB (You Need A Budget) written in Python. The project follows clean architecture principles with ports and adapters pattern.
+
+## Architecture
+
+The project uses a layered architecture:
+
+- `src/ynab_cli/domain/`: Core business logic, models, and ports (interfaces)
+- `src/ynab_cli/adapters/`: External adapters (YNAB API, Rich UI, Textual TUI)
+- `src/ynab_cli/host/`: Application entry points and framework integration (Click CLI, Textual app)
+
+### Key Patterns
+
+1. **Ports and Adapters**: Domain defines protocols/interfaces, adapters implement them
+2. **Dependency Injection**: Dependencies are injected through constructors
+3. **Async/Await**: Most operations are async for better I/O handling
+4. **Type Safety**: Heavy use of type hints and protocols
+
+## Coding Standards
+
+### Python Version & Dependencies
+- Target Python 3.11+
+- Use `uv` for dependency management
+- All dependencies defined in `pyproject.toml`
+
+### Code Style
+- Follow PEP 8
+- Use type hints for all function parameters and return values
+- Prefer `typing_extensions` imports for newer typing features
+- Use `attrs` for data classes with `@define` decorator
+- Use `@override` decorator from `typing_extensions` when overriding methods in protocols or base classes
+
+### Async Patterns
+- Most I/O operations should be async
+- Use `anyio` for async utilities when needed
+- Progress tracking should be async-compatible
+
+### Error Handling
+- Use proper exception types
+- Handle API errors gracefully
+- Provide meaningful error messages to users
+
+## Testing Guidelines
+
+### Test Structure
+- Unit tests in `tests/unit/` mirroring `src/` structure
+- Use pytest as the testing framework
+- All test functions should have proper type annotations
+- Test classes should be named `Test<ClassName>`
+- Test methods should be descriptive: `test_<method_name>_<scenario>`
+
+### Mocking
+- Use `unittest.mock` for mocking external dependencies
+- Mock at the adapter level, not domain level
+- Use `MagicMock` for complex objects, `Mock` for simple ones
+
+### Test Patterns
+```python
+from typing import Any
+from unittest.mock import MagicMock, Mock
+import pytest
+
+class TestMyClass:
+    def test_method_name_success_scenario(self) -> None:
+        """Test description of what is being tested."""
+        # Arrange
+        mock_dependency = Mock()
+        instance = MyClass(mock_dependency)
+        
+        # Act
+        result = instance.method_name()
+        
+        # Assert
+        assert result == expected_value
+        mock_dependency.some_method.assert_called_once()
+```
+
+## Domain Models
+
+### Data Classes
+- Use `@attrs.define` for data classes
+- Implement `to_dict()` and `from_dict()` for serialization when needed
+- Use proper type hints including `Self` for class methods
+
+```python
+from typing import Any, Self
+from attrs import define
+
+@define
+class MyModel:
+    field: str
+    optional_field: int | None = None
+    
+    def to_dict(self) -> dict[str, Any]:
+        return {"field": self.field, "optional_field": self.optional_field}
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(field=data["field"], optional_field=data.get("optional_field"))
+```
+
+### Protocols
+- Define interfaces as protocols in `domain/ports/`
+- Use `typing.Protocol` for structural typing
+- Mark implementation methods with `@override`
+
+## UI Frameworks
+
+### Rich (Progress & Prompts)
+- Used for CLI progress bars and user prompts
+- Implement `Progress` and `IO` protocols
+- Handle console stop/start for prompts
+
+### Textual (TUI)
+- Used for interactive terminal UI
+- Follow Textual app patterns
+- Use proper CSS for styling
+- Handle async operations properly
+
+### Click (CLI Framework)
+- Use Click for command-line interface
+- Use `click-default-group` for default commands
+- Implement proper help text and options
+- Use context objects for passing settings
+
+## API Integration
+
+### YNAB API
+- All API models should be in `adapters/ynab/models/`
+- Use proper error handling for HTTP requests
+- Implement rate limiting if needed
+- Use `httpx` for HTTP client
+
+## File Organization
+
+### Import Order
+1. Standard library imports
+2. Third-party imports
+3. Local imports (domain, then adapters, then host)
+
+### Module Structure
+- Keep modules focused and cohesive
+- Use `__init__.py` for public APIs
+- Private modules should have underscore prefix
+
+## Common Patterns
+
+### Progress Tracking
+```python
+async def long_running_operation(io: IO) -> None:
+    await io.progress.update(total=100)
+    for i in range(100):
+        # Do work
+        await io.progress.update(advance=1)
+```
+
+### Settings & Configuration
+- Use environment variables with `python-dotenv`
+- Settings objects should be immutable
+- Pass settings through dependency injection
+
+### Error Messages
+- Provide actionable error messages
+- Include context about what was being attempted
+- Use appropriate log levels
+
+## Development Workflow
+
+1. Create feature branches from main
+2. Write tests first (TDD when possible)
+3. Implement functionality
+4. Ensure all tests pass
+5. Run linting and formatting (`make lint`)
+6. Create pull request with descriptive title and description
+
+## Performance Considerations
+
+- Use async I/O for network operations
+- Implement progress tracking for long operations
+- Consider memory usage for large datasets
+- Use appropriate data structures for lookups
+
+## Security
+
+- Never log sensitive data (API keys, personal info)
+- Use environment variables for secrets
+- Validate user inputs
+- Handle API rate limits gracefully

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.6.0 (2025-06-28)
+
+### Feat
+
+- use anyio and uvloop
+
+### Fix
+
+- **tests**: adding moar tests
+- **tests**: added tests for a bunch of things
+- **deps**: bump textual from 3.3.0 to 3.4.0
+- **tui**: fix some ui issues and clean up some code
+
+## v0.5.4 (2025-06-10)
+
+### Fix
+
+- **tui**: added some command parameter forms
+
 ## v0.5.3 (2025-06-09)
 
 ### Fix

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ynab-cli
-Version: 0.5.3
+Version: 0.6.0
 Summary: YNAB Command Line Interface
 Project-URL: Changelog, https://github.com/jeffsawatzky/ynab-cli/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://jeffsawatzky.github.io/ynab-cli/
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
+Requires-Dist: anyio~=4.9
 Requires-Dist: attrs~=25.3
 Requires-Dist: click-default-group~=1.2
 Requires-Dist: click~=8.2
@@ -28,8 +29,9 @@ Requires-Dist: rapidfuzz~=3.13
 Requires-Dist: rich~=14.0
 Requires-Dist: rule-engine~=4.5
 Requires-Dist: textual-fspicker~=0.4
-Requires-Dist: textual~=3.3
+Requires-Dist: textual~=3.5
 Requires-Dist: typing-extensions~=4.14
+Requires-Dist: uvloop~=0.21
 Description-Content-Type: text/markdown
 
 # YNAB CLI

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ynab-cli"
-version = "0.5.3"
+version = "0.6.0"
 description = "YNAB Command Line Interface"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,6 +33,7 @@ classifiers = [
 ]
 
 dependencies = [
+  "anyio~=4.9",
   "attrs~=25.3",
   "click-default-group~=1.2",
   "click~=8.2",
@@ -42,8 +43,9 @@ dependencies = [
   "rich~=14.0",
   "rule-engine~=4.5",
   "textual-fspicker~=0.4",
-  "textual~=3.3",
+  "textual~=3.5",
   "typing-extensions~=4.14",
+  "uvloop~=0.21",
 ]
 
 [project.urls]
@@ -59,18 +61,18 @@ ynab-cli = "ynab_cli.host.cli:main"
 
 [dependency-groups]
 dev = [
-  "commitizen>=4.8.2",
+  "commitizen>=4.8.3",
   "factory-boy>=3.3.3",
   "mkdocs-click>=0.9.0",
   "mkdocs-material>=9.6.14",
   "mkdocs>=1.6.1",
   "mypy>=1.16.0",
-  "pytest-asyncio>=1.0.0",
-  "pytest-cov>=6.1.1",
+  "pytest-cov>=6.2.1",
   "pytest-mock>=3.14.1",
-  "pytest>=8.4.0",
-  "ruff>=0.11.12",
+  "pytest>=8.4.1",
+  "ruff>=0.12.1",
   "textual-dev>=1.7.0",
+  "trio>=0.30.0",
   "types-python-dateutil>=2.9.0.20250516",
 ]
 
@@ -136,6 +138,12 @@ max-complexity = 70
 builtins-ignorelist = ["type", "id"]
 
 
+[tool.coverage.run]
+omit = [
+  "src/ynab_cli/adapters/ynab/**/*",
+]
+
+
 [tool.commitizen]
 name = "cz_conventional_commits"
 annotated_tag = true

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/src/ynab_cli/domain/models/rules.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Self
 
 from attrs import define as _attrs_define
 
@@ -18,20 +18,33 @@ class TransactionRule:
     #   See: https://api.ynab.com/v1#/Transactions/updateTransactions
     patch: models.SaveTransactionWithIdOrImportId | None = None
 
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "rules": self.rules,
+            "patch": self.patch.to_dict() if self.patch else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        rules = [str(r) for r in data.get("rules", [])]
+        patch = None
+        if "patch" in data:
+            patch = models.SaveTransactionWithIdOrImportId.from_dict(data["patch"])
+
+        return cls(rules=rules, patch=patch)
+
 
 @_attrs_define
 class TransactionRules:
     transaction_rules: list[TransactionRule]
 
+    def to_dict(self) -> dict[str, Any]:
+        return {"transaction_rules": [rule.to_dict() for rule in self.transaction_rules]}
+
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "TransactionRules":
+    def from_dict(cls, data: dict[str, Any]) -> Self:
         transaction_rules = []
         for rule in data.get("transaction_rules", []):
-            rules = [str(r) for r in rule.get("rules", [])]
-            patch = None
-            if "patch" in rule:
-                patch = models.SaveTransactionWithIdOrImportId.from_dict(rule["patch"])
-
-            transaction_rules.append(TransactionRule(rules=rules, patch=patch))
+            transaction_rules.append(TransactionRule.from_dict(rule))
 
         return cls(transaction_rules=transaction_rules)

ynab_cli-0.6.0/src/ynab_cli/domain/use_cases/budgets.py

@@ -0,0 +1,45 @@
+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.budgets import get_budgets
+from ynab_cli.domain import ports
+from ynab_cli.domain.constants import YNAB_API_URL
+from ynab_cli.domain.settings import Settings
+
+
+class ListAllParams(TypedDict):
+    pass
+
+
+async def list_all(
+    settings: Settings, io: ports.IO, params: ListAllParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[models.BudgetSummary]:
+    try:
+        progress_total = 0
+
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
+            budgets = (
+                await util.get_asyncio_detailed(io, get_budgets.asyncio_detailed, include_accounts=False, client=client)
+            ).data.budgets
+            budgets.sort(key=lambda b: b.name)
+
+            progress_total = len(budgets)
+            await io.progress.update(total=progress_total)
+            for budget in budgets:
+                await io.progress.update(advance=1)
+                yield budget
+
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/src/ynab_cli/domain/use_cases/categories.py

@@ -20,10 +20,16 @@ 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:
+async def list_unused(
+    settings: Settings, io: ports.IO, params: ListUnusedParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[models.Category]:
+    try:
         progress_total = 0
-        try:
+
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
             category_groups = (
                 await util.get_asyncio_detailed(
                     io, get_categories.asyncio_detailed, settings.ynab.budget_id, client=client
@@ -63,23 +69,31 @@ async def list_unused(settings: Settings, io: ports.IO, params: ListUnusedParams
                     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")
-        finally:
-            await io.progress.update(total=progress_total, completed=progress_total)
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)
 
 
 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:
+async def list_all(
+    settings: Settings, io: ports.IO, params: ListAllParams, *, client: ynab.AuthenticatedClient | None = None
+) -> AsyncIterator[models.Category]:
+    try:
         progress_total = 0
-        try:
+
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
             category_groups = (
                 await util.get_asyncio_detailed(
                     io, get_categories.asyncio_detailed, settings.ynab.budget_id, client=client
@@ -106,10 +120,12 @@ async def list_all(settings: Settings, io: ports.IO, params: ListAllParams) -> A
 
                     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")
-        finally:
-            await io.progress.update(total=progress_total, completed=progress_total)
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)

{ynab_cli-0.5.3 → ynab_cli-0.6.0}/src/ynab_cli/domain/use_cases/payees.py

@@ -47,13 +47,13 @@ class NormalizeNamesParams(TypedDict):
 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:
         progress_total = 0
 
-        try:
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
             payees = (
                 await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
             ).data.payees
@@ -81,13 +81,15 @@ async def normalize_names(
                             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")
-        finally:
-            await io.progress.update(total=progress_total, completed=progress_total)
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)
 
 
 class ListDuplicatesParams(TypedDict):
@@ -97,13 +99,13 @@ class ListDuplicatesParams(TypedDict):
 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:
         progress_total = 0
 
-        try:
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
             possible_duplicates: dict[tuple[UUID, str], list[tuple[UUID, str]]] = {}
 
             payees = (
@@ -142,13 +144,15 @@ async def list_duplicates(
 
                         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")
-        finally:
-            await io.progress.update(total=progress_total, completed=progress_total)
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)
 
 
 class ListUnusedParams(TypedDict):
@@ -158,13 +162,13 @@ class ListUnusedParams(TypedDict):
 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:
         progress_total = 0
 
-        try:
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
+
+        async with client:
             payees = (
                 await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
             ).data.payees
@@ -205,11 +209,15 @@ async def list_unused(
                             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")
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)
 
 
 class ListAllParams(TypedDict):
@@ -219,11 +227,13 @@ class ListAllParams(TypedDict):
 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)
+    try:
+        progress_total = 0
+
+        if client is None:
+            client = ynab.AuthenticatedClient(base_url=YNAB_API_URL, token=settings.ynab.access_token)
 
-    async with client:
-        try:
+        async with client:
             payees = (
                 await util.get_asyncio_detailed(io, get_payees.asyncio_detailed, settings.ynab.budget_id, client=client)
             ).data.payees
@@ -239,10 +249,12 @@ async def list_all(
 
                 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")
-        finally:
-            await io.progress.update(total=progress_total, completed=progress_total)
+    except Exception as e:
+        if isinstance(e, util.ApiError) and e.status_code == 401:
+            await io.print("Invalid or expired access token. Please update your settings.")
+        elif isinstance(e, util.ApiError) and 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}")
+    finally:
+        await io.progress.update(total=progress_total, completed=progress_total)