beancount-gocardless 0.1.12__tar.gz → 0.1.14__tar.gz

beancount_gocardless-0.1.14/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install mise
+        uses: jdx/mise-action@v2
+
+      - name: Run tests
+        run: mise run test
+
+      - name: Run lint
+        run: mise run lint
+
+      - name: Run format check
+        run: mise run fmt-check

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/.github/workflows/publish.yml

@@ -2,7 +2,7 @@ name: Upload Python Package to PyPI when a Release is Created
 
 on:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   pypi-publish:
@@ -28,7 +28,9 @@ jobs:
        - name: Build package
          run: uv build
        - name: Publish package to PyPI
-         run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
+         env:
+           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+         run: uv publish
        - name: Build Sphinx documentation
          run: |
            uv run sphinx-build -b html docs/ docs/_build

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/.gitignore

@@ -100,13 +100,6 @@ ipython_config.py
 #   commonly ignored for libraries.
 uv.lock
 
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
 #pdm.lock

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/.pre-commit-config.yaml

@@ -2,6 +2,8 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.9.8
     hooks:
+      - id: ruff
+        args: [--fix]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pre-commit-hooks

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/.readthedocs.yaml

@@ -6,9 +6,8 @@ build:
       python: "3.12"
    jobs:
       post_create_environment:
-         - python -m pip install poetry
-      post_install:
-         - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with dev
+         - python -m pip install uv
+         - uv sync --extra dev
 
 sphinx:
    configuration: docs/conf.py

beancount_gocardless-0.1.14/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Patrick Ruckstuhl
+
+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.

beancount_gocardless-0.1.14/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: beancount-gocardless
+Version: 0.1.14
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <4,>=3.12
+Requires-Dist: beancount
+Requires-Dist: beangulp
+Requires-Dist: pre-commit>=4.5.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: requests
+Requires-Dist: requests-cache
+Requires-Dist: rich
+Provides-Extra: dev
+Requires-Dist: myst-parser; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.9.8; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![Python versions](https://img.shields.io/pypi/pyversions/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![License](https://img.shields.io/pypi/l/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![Documentation Status](https://readthedocs.org/projects/beancount-gocardless/badge/?version=latest)](https://beancount-gocardless.readthedocs.io/en/latest/)
+[![Publish](https://github.com/jodoox/beancount-gocardless/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/jodoox/beancount-gocardless/actions/workflows/publish.yml)
+
+# beancount-gocardless
+
+Python client for the GoCardless Bank Account Data API (formerly Nordigen), with Pydantic models recreated from the OpenAPI/Swagger spec, plus a Beancount importer.
+
+Inspired by https://github.com/tarioch/beancounttools.
+
+Documentation: https://beancount-gocardless.readthedocs.io/en/latest/
+
+## Key features
+
+- API client with typed Pydantic models for endpoints and data structures.
+- Built-in HTTP caching via `requests-cache` (optional).
+- CLI to manage bank authorization (list banks, create links, list accounts, delete links).
+- Beancount importer: a `beangulp.Importer` implementation that fetches transactions and emits Beancount entries.
+- Import-time metadata control (exclude fields, add custom fields), plus subclassing hooks for advanced needs.
+
+## Installation
+
+```bash
+pip install beancount-gocardless
+```
+
+## Prerequisites (credentials)
+
+Create a GoCardless Bank Account Data account to get API credentials:
+
+https://bankaccountdata.gocardless.com/overview/
+
+You will need:
+
+- `GOCARDLESS_SECRET_ID`
+- `GOCARDLESS_SECRET_KEY`
+
+## CLI usage (bank authorization)
+
+The importer needs an authorized bank connection first. Use the CLI to create and manage connections.
+
+Set credentials as environment variables:
+
+```bash
+export GOCARDLESS_SECRET_ID="..."
+export GOCARDLESS_SECRET_KEY="..."
+```
+
+Launch the CLI:
+
+```bash
+beancount-gocardless
+```
+
+Options:
+- List accounts: view connected accounts with expiry status (EXPIRED badge shown for expired connections), select an account to view details, check balances, or delete the link
+- Add account: add a new bank connection by selecting country, choosing a bank, and creating an authorization link
+- List banks: browse available banks by country and create links
+
+Account expiry is shown in the list. Use --mock flag for testing without real credentials.
+
+## Beancount usage
+
+### 1) Create a YAML config
+
+Create `gocardless.yaml`:
+
+```yaml
+secret_id: $GOCARDLESS_SECRET_ID
+secret_key: $GOCARDLESS_SECRET_KEY
+
+# Note: this project substitutes environment variables in YAML values at runtime.
+
+cache_options: # if omitted, caching is disabled
+  cache_name: "gocardless"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    transaction_types: ["booked", "pending"] # optional, defaults to both
+    preferred_balance_type: "interimAvailable" # optional
+```
+
+### 2) Create an import script
+
+Create `my.import`:
+
+```python
+#!/usr/bin/env python3
+
+import beangulp
+from beancount_gocardless import GoCardLessImporter
+from smart_importer import PredictPayees, PredictPostings
+
+importers = [
+    GoCardLessImporter(),
+]
+
+hooks = [
+    PredictPostings().hook,
+    PredictPayees().hook,
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers, hooks=hooks)
+    ingest()
+```
+
+### 3) Run the import
+
+```bash
+python my.import extract ./gocardless.yaml --existing ./ledger.bean
+```
+
+## Customizing metadata
+
+### Via YAML configuration
+
+You can control metadata per account:
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+
+    # Exclude specific default metadata fields.
+    exclude_default_metadata: ["bookingDate", "creditorName"]
+
+    # Add custom metadata fields using dotted paths.
+    metadata_fields:
+      payee: "creditorName"
+      cardScheme: "additionalDataStructured.cardInstrument.cardSchemeName"
+      balanceType: "balanceAfterTransaction.balance_type"
+```
+
+Supported options:
+
+- `exclude_default_metadata` (default: `[]`) - Exclude specific default metadata fields.
+  - Default fields include: `nordref`, `creditorName`, `debtorName`, `bookingDate`
+- `metadata_fields` (default: `null`) - Add or override metadata fields using dotted paths.
+  - Specify the output key as the dict key and the GoCardless path as the value.
+  - Example: `"cardScheme": "additionalDataStructured.cardInstrument.cardSchemeName"`
+
+### Example configurations
+
+**Use defaults with exclusions:**
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    exclude_default_metadata: ["bookingDate"]  # Keep nordref, creditorName, debtorName
+```
+
+**Full customization with custom keys:**
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    exclude_default_metadata: []  # Keep all defaults
+    metadata_fields:
+      # Rename default field by using custom key name
+      payee: "creditorName"
+      # Add nested custom fields
+      cardScheme: "additionalDataStructured.cardInstrument.cardSchemeName"
+      mcc: "merchant_category_code"
+      ultimateCreditor: "ultimate_creditor"
+```
+
+### Via subclassing
+
+For advanced customization, subclass `GoCardLessImporter` and override `add_metadata`:
+
+```python
+from beancount_gocardless import GoCardLessImporter
+
+class CustomImporter(GoCardLessImporter):
+    def add_metadata(self, transaction, custom_metadata, account_config=None):
+        metakv = super().add_metadata(transaction, custom_metadata, account_config)
+
+        if transaction.ultimate_creditor:
+            metakv["ultimateCreditor"] = transaction.ultimate_creditor
+        if transaction.merchant_category_code:
+            metakv["mcc"] = transaction.merchant_category_code
+        if transaction.bank_transaction_code:
+            metakv["bankCode"] = transaction.bank_transaction_code
+
+        return metakv
+
+importers = [CustomImporter()]
+```
+
+The `BankTransaction` model (see `models.py`) contains many optional fields you can expose as metadata, for example:
+
+- `ultimate_creditor`, `ultimate_debtor`
+- `bank_transaction_code`, `proprietary_bank_transaction_code`
+- `merchant_category_code`, `creditor_id`, `mandate_id`
+- `entry_reference`, `account_servicer_reference`
+
+## Development
+
+### API coverage and models
+
+The GoCardless client aims to provide full API coverage with typed models for endpoints and data structures.
+
+Models are manually recreated from the OpenAPI/Swagger spec to keep strong typing and stable semantics.
+
+### Local development
+
+```bash
+git clone https://github.com/jodoox/beancount-gocardless.git
+cd beancount-gocardless
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[dev]"
+pytest
+```

beancount_gocardless-0.1.14/README.md

@@ -0,0 +1,224 @@
+[![PyPI](https://img.shields.io/pypi/v/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![Python versions](https://img.shields.io/pypi/pyversions/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![License](https://img.shields.io/pypi/l/beancount-gocardless.svg)](https://pypi.org/project/beancount-gocardless/)
+[![Documentation Status](https://readthedocs.org/projects/beancount-gocardless/badge/?version=latest)](https://beancount-gocardless.readthedocs.io/en/latest/)
+[![Publish](https://github.com/jodoox/beancount-gocardless/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/jodoox/beancount-gocardless/actions/workflows/publish.yml)
+
+# beancount-gocardless
+
+Python client for the GoCardless Bank Account Data API (formerly Nordigen), with Pydantic models recreated from the OpenAPI/Swagger spec, plus a Beancount importer.
+
+Inspired by https://github.com/tarioch/beancounttools.
+
+Documentation: https://beancount-gocardless.readthedocs.io/en/latest/
+
+## Key features
+
+- API client with typed Pydantic models for endpoints and data structures.
+- Built-in HTTP caching via `requests-cache` (optional).
+- CLI to manage bank authorization (list banks, create links, list accounts, delete links).
+- Beancount importer: a `beangulp.Importer` implementation that fetches transactions and emits Beancount entries.
+- Import-time metadata control (exclude fields, add custom fields), plus subclassing hooks for advanced needs.
+
+## Installation
+
+```bash
+pip install beancount-gocardless
+```
+
+## Prerequisites (credentials)
+
+Create a GoCardless Bank Account Data account to get API credentials:
+
+https://bankaccountdata.gocardless.com/overview/
+
+You will need:
+
+- `GOCARDLESS_SECRET_ID`
+- `GOCARDLESS_SECRET_KEY`
+
+## CLI usage (bank authorization)
+
+The importer needs an authorized bank connection first. Use the CLI to create and manage connections.
+
+Set credentials as environment variables:
+
+```bash
+export GOCARDLESS_SECRET_ID="..."
+export GOCARDLESS_SECRET_KEY="..."
+```
+
+Launch the CLI:
+
+```bash
+beancount-gocardless
+```
+
+Options:
+- List accounts: view connected accounts with expiry status (EXPIRED badge shown for expired connections), select an account to view details, check balances, or delete the link
+- Add account: add a new bank connection by selecting country, choosing a bank, and creating an authorization link
+- List banks: browse available banks by country and create links
+
+Account expiry is shown in the list. Use --mock flag for testing without real credentials.
+
+## Beancount usage
+
+### 1) Create a YAML config
+
+Create `gocardless.yaml`:
+
+```yaml
+secret_id: $GOCARDLESS_SECRET_ID
+secret_key: $GOCARDLESS_SECRET_KEY
+
+# Note: this project substitutes environment variables in YAML values at runtime.
+
+cache_options: # if omitted, caching is disabled
+  cache_name: "gocardless"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    transaction_types: ["booked", "pending"] # optional, defaults to both
+    preferred_balance_type: "interimAvailable" # optional
+```
+
+### 2) Create an import script
+
+Create `my.import`:
+
+```python
+#!/usr/bin/env python3
+
+import beangulp
+from beancount_gocardless import GoCardLessImporter
+from smart_importer import PredictPayees, PredictPostings
+
+importers = [
+    GoCardLessImporter(),
+]
+
+hooks = [
+    PredictPostings().hook,
+    PredictPayees().hook,
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers, hooks=hooks)
+    ingest()
+```
+
+### 3) Run the import
+
+```bash
+python my.import extract ./gocardless.yaml --existing ./ledger.bean
+```
+
+## Customizing metadata
+
+### Via YAML configuration
+
+You can control metadata per account:
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+
+    # Exclude specific default metadata fields.
+    exclude_default_metadata: ["bookingDate", "creditorName"]
+
+    # Add custom metadata fields using dotted paths.
+    metadata_fields:
+      payee: "creditorName"
+      cardScheme: "additionalDataStructured.cardInstrument.cardSchemeName"
+      balanceType: "balanceAfterTransaction.balance_type"
+```
+
+Supported options:
+
+- `exclude_default_metadata` (default: `[]`) - Exclude specific default metadata fields.
+  - Default fields include: `nordref`, `creditorName`, `debtorName`, `bookingDate`
+- `metadata_fields` (default: `null`) - Add or override metadata fields using dotted paths.
+  - Specify the output key as the dict key and the GoCardless path as the value.
+  - Example: `"cardScheme": "additionalDataStructured.cardInstrument.cardSchemeName"`
+
+### Example configurations
+
+**Use defaults with exclusions:**
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    exclude_default_metadata: ["bookingDate"]  # Keep nordref, creditorName, debtorName
+```
+
+**Full customization with custom keys:**
+
+```yaml
+accounts:
+  - id: "<REDACTED_UUID>"
+    asset_account: "Assets:Banks:Revolut:Checking"
+    exclude_default_metadata: []  # Keep all defaults
+    metadata_fields:
+      # Rename default field by using custom key name
+      payee: "creditorName"
+      # Add nested custom fields
+      cardScheme: "additionalDataStructured.cardInstrument.cardSchemeName"
+      mcc: "merchant_category_code"
+      ultimateCreditor: "ultimate_creditor"
+```
+
+### Via subclassing
+
+For advanced customization, subclass `GoCardLessImporter` and override `add_metadata`:
+
+```python
+from beancount_gocardless import GoCardLessImporter
+
+class CustomImporter(GoCardLessImporter):
+    def add_metadata(self, transaction, custom_metadata, account_config=None):
+        metakv = super().add_metadata(transaction, custom_metadata, account_config)
+
+        if transaction.ultimate_creditor:
+            metakv["ultimateCreditor"] = transaction.ultimate_creditor
+        if transaction.merchant_category_code:
+            metakv["mcc"] = transaction.merchant_category_code
+        if transaction.bank_transaction_code:
+            metakv["bankCode"] = transaction.bank_transaction_code
+
+        return metakv
+
+importers = [CustomImporter()]
+```
+
+The `BankTransaction` model (see `models.py`) contains many optional fields you can expose as metadata, for example:
+
+- `ultimate_creditor`, `ultimate_debtor`
+- `bank_transaction_code`, `proprietary_bank_transaction_code`
+- `merchant_category_code`, `creditor_id`, `mandate_id`
+- `entry_reference`, `account_servicer_reference`
+
+## Development
+
+### API coverage and models
+
+The GoCardless client aims to provide full API coverage with typed models for endpoints and data structures.
+
+Models are manually recreated from the OpenAPI/Swagger spec to keep strong typing and stable semantics.
+
+### Local development
+
+```bash
+git clone https://github.com/jodoox/beancount-gocardless.git
+cd beancount-gocardless
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[dev]"
+pytest
+```

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/docs/importer.rst

@@ -23,6 +23,8 @@ YAML file:
   - id: Account ID
   - asset_account: Beancount asset account
   - filing_account (opt): For hooks
+  - preferred_balance_type (opt): Preferred type for balance assertions, availability depends on the bank (e.g. "expected", "closingBooked", "interimBooked", "interimAvailable", "available", "booked")
+  - transaction_types (opt): List of types to fetch ("booked" and/or "pending")
 
 Usage
 -----
@@ -44,17 +46,26 @@ Example
     accounts:
         - id: <REDACTED_UUID>
           asset_account: "Assets:Banks:Revolut:Checking"
+          preferred_balance_type: "expected"
+          transaction_types: ["booked", "pending"]
 
 .. code-block:: python
 
     import beangulp
     from beancount_gocardless import GoCardLessImporter
-    from smart_importer import apply_hooks, PredictPostings, PredictPayees
+    from smart_importer import PredictPostings, PredictPayees
 
-    importers = [apply_hooks(GoCardLessImporter(), [PredictPostings(), PredictPayees()])]
+    importers = [
+        GoCardLessImporter()
+    ]
+
+    hooks = [
+        PredictPostings().hook,
+        PredictPayees().hook,
+    ]
 
     if __name__ == "__main__":
-        ingest = beangulp.Ingest(importers)
+        ingest = beangulp.Ingest(importers, hooks=hooks)
         ingest()
 
 .. code-block:: bash

beancount_gocardless-0.1.14/mise.toml

@@ -0,0 +1,7 @@
+[tasks]
+test = "uv sync --extra test && uv run pytest tests/ -v"
+lint = "uv sync --extra lint && uv run ruff check src/ tests/"
+fmt = "uv sync --extra lint && uv run ruff check src/ tests/ --fix"
+fmt-check = "uv sync --extra lint && uv run ruff check src/ tests/"
+build = "uv sync && uv build"
+publish = "uv sync && uv publish --token $PYPI_TOKEN"

{beancount_gocardless-0.1.12 → beancount_gocardless-0.1.14}/pyproject.toml

@@ -1,10 +1,14 @@
 [project]
 name = "beancount-gocardless"
-version = "0.1.12"
+version = "0.1.14"
 description = ""
 authors = []
 readme = "README.md"
 requires-python = ">=3.12,<4"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12"
+]
 dependencies = [
     "requests",
     "requests-cache",
@@ -12,17 +16,15 @@ dependencies = [
     "beangulp",
     "pyyaml",
     "rich",
-    "textual>=3.2.0",
-    "textual-dev>=1.7.0",
     "pydantic>=2.0.0",
     "pre-commit>=4.5.1",
+    "questionary>=2.0.0",
 ]
-license = "Unlicense"
+license = "MIT"
 license-files = ["LICENSE"]
 
 [project.scripts]
 beancount-gocardless = "beancount_gocardless.cli:main"
-beancount-gocardless-tui = "beancount_gocardless.tui:main"
 
 [project.optional-dependencies]
 dev = [
@@ -38,6 +40,9 @@ test = [
     "pytest-asyncio",
 ]
 
+[tool.uv]
+package = true
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

beancount_gocardless-0.1.14/src/beancount_gocardless/__main__.py

@@ -0,0 +1,4 @@
+from beancount_gocardless.cli import main
+
+if __name__ == "__main__":
+    main()