beancount-gocardless 0.1.12__py3-none-any.whl → 0.1.14__py3-none-any.whl

beancount_gocardless/models.py

@@ -4,7 +4,7 @@ Complete coverage of all schemas from swagger.json
 """
 
 from typing import Optional, List, Dict, Any, TypedDict
-from pydantic import BaseModel, Field, ConfigDict, validator
+from pydantic import BaseModel, Field, ConfigDict, field_validator
 from pydantic.alias_generators import to_camel
 from enum import Enum
 
@@ -37,8 +37,10 @@ class StatusEnum(str, Enum):
 class BalanceAmountSchema(BaseModel):
     """Balance amount schema."""
 
-    amount: str
-    currency: str
+    model_config = ConfigDict(populate_by_name=True)
+
+    amount: str = Field(default=None)
+    currency: str = Field(default=None)
 
 
 class BalanceSchema(BaseModel):
@@ -166,6 +168,8 @@ class AccountDetail(BaseModel):
 class TransactionAmountSchema(BaseModel):
     """Transaction amount schema."""
 
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
     amount: str
     currency: str
 
@@ -173,6 +177,8 @@ class TransactionAmountSchema(BaseModel):
 class InstructedAmount(BaseModel):
     """Instructed amount schema."""
 
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
     amount: str
     currency: str
 
@@ -180,6 +186,8 @@ class InstructedAmount(BaseModel):
 class CurrencyExchangeSchema(BaseModel):
     """Currency exchange schema."""
 
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
     source_currency: str
     exchange_rate: Optional[str] = None
     unit_currency: Optional[str] = None
@@ -192,8 +200,12 @@ class CurrencyExchangeSchema(BaseModel):
 class BalanceAfterTransactionSchema(BaseModel):
     """Balance after transaction schema."""
 
-    balance_after_transaction: Optional[BalanceAmountSchema] = None
-    balance_type: Optional[str] = None
+    model_config = ConfigDict(populate_by_name=True)
+
+    balance_amount: Optional[BalanceAmountSchema] = Field(
+        default=None, validation_alias="balanceAmount"
+    )
+    balance_type: Optional[str] = Field(default=None, validation_alias="balanceType")
 
 
 class TransactionSchema(BaseModel):
@@ -206,6 +218,19 @@ class TransactionSchema(BaseModel):
     value_date_time: Optional[str] = Field(None, description="Value date and time.")
     transaction_amount: TransactionAmountSchema
     currency_exchange: Optional[List[CurrencyExchangeSchema]] = None
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    @field_validator("currency_exchange", mode="before")
+    @classmethod
+    def normalize_currency_exchange(cls, v):
+        """Normalize currency_exchange to always be a list."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return [v]
+        return v
+
     creditor_name: Optional[str] = Field(None, description="Creditor name.")
     creditor_account: Optional[AccountSchema] = None
     creditor_agent: Optional[str] = Field(None, description="Creditor agent.")
@@ -259,7 +284,21 @@ class BankTransaction(BaseModel):
     )
     creditor_name: Optional[str] = Field(None, description="Creditor name.")
     creditor_account: Optional[AccountSchema] = None
+    ultimate_creditor: Optional[str] = Field(
+        default=None, description="Ultimate creditor."
+    )
     currency_exchange: Optional[List[CurrencyExchangeSchema]] = None
+
+    @field_validator("currency_exchange", mode="before")
+    @classmethod
+    def normalize_currency_exchange(cls, v):
+        """Normalize currency_exchange to always be a list."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return [v]
+        return v
+
     balance_after_transaction: Optional[BalanceAfterTransactionSchema] = None
     bank_transaction_code: Optional[str] = Field(
         None, description="Bank transaction code."
@@ -276,11 +315,13 @@ class BankTransaction(BaseModel):
     booking_date_time: Optional[str] = Field(None, description="Booking date and time.")
     value_date_time: Optional[str] = Field(None, description="Value date and time.")
     entry_reference: Optional[str] = Field(None, description="Entry reference.")
-    additional_information_structured: Optional[str] = Field(
-        None, description="Additional structured information."
+    additional_data_structured: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Additional structured information.",
     )
     card_transaction: Optional[Dict[str, Any]] = Field(
-        None, description="Card transaction details."
+        default=None,
+        description="Card transaction details.",
     )
     merchant_category_code: Optional[str] = Field(
         None, description="Merchant category code."
@@ -543,8 +584,12 @@ class AccountConfig(BaseModel):
     asset_account: str
     metadata: Dict[str, Any] = {}
     transaction_types: List[str] = ["booked", "pending"]
+    preferred_balance_type: Optional[str] = None
+    exclude_default_metadata: List[str] = []
+    metadata_fields: Optional[Dict[str, str]] = None
 
-    @validator("transaction_types")
+    @field_validator("transaction_types")
+    @classmethod
     def validate_transaction_types(cls, v):
         allowed = {"booked", "pending"}
         if not set(v).issubset(allowed):

beancount_gocardless/utils.py

@@ -0,0 +1,39 @@
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def load_dotenv(dotenv_path: Optional[str] = None) -> None:
+    """
+    Simple .env loader that searches in current and parent directories.
+    Only handles simple KEY=VALUE pairs and ignores comments.
+    """
+    if dotenv_path:
+        search_paths = [Path(dotenv_path)]
+    else:
+        # Search in current and parent directories
+        current = Path.cwd().resolve()
+        search_paths = [current / ".env"] + [p / ".env" for p in current.parents]
+
+    for path in search_paths:
+        if path.exists() and path.is_file():
+            try:
+                with open(path, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        # Ignore comments and empty lines
+                        if not line or line.startswith("#"):
+                            continue
+                        # Basic KEY=VALUE parsing
+                        if "=" in line:
+                            key, value = line.split("=", 1)
+                            key = key.strip()
+                            # Strip quotes and whitespace
+                            value = value.strip().strip("'\"")
+                            # Only set if not already present in environment
+                            if key and key not in os.environ:
+                                os.environ[key] = value
+                return  # Stop after the first .env file found and successfully read
+            except Exception:
+                # Silently fail if we can't read a specific .env file
+                continue

beancount_gocardless-0.1.14.dist-info/METADATA

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

@@ -0,0 +1,14 @@
+beancount_gocardless/__init__.py,sha256=JVJivGs-o5yY8YGqTYwn1cXY7aiA76lUyc95s1Ye-j0,253
+beancount_gocardless/__main__.py,sha256=0yFL6yq31qI-pf_dp0_0-TgMHlG5QyHQ1wYzi8mhAWI,81
+beancount_gocardless/cli.py,sha256=VlqbJaLRxagaGbV9AKr-oMxwhCkWKoHys3u4gYifdIg,21882
+beancount_gocardless/client.py,sha256=DrbvGN85Pf5Cl20mgC_grLLhhrEk2Jn4ArJJOWQ0wjU,16162
+beancount_gocardless/importer.py,sha256=-sfO0CKNmH9ivUPyU_aY4xFG0y1ohUi3v4Y--rG76hs,18824
+beancount_gocardless/mock_client.py,sha256=WvcKGjpUTzYlqRVz3mUoDWiKKEc_12yi3TLwreMbHC4,7765
+beancount_gocardless/models.py,sha256=jLMPFVW7FiiN2nERPPGSa2sW-r33_DY08wvZT_yYpwA,19765
+beancount_gocardless/utils.py,sha256=DKRG1sm-jyLmGN17oZJ3fGplXPc91ASHhH0f0KCANlc,1613
+beancount_gocardless/openapi/swagger.json,sha256=t8TLbt0l2UOyorZX8JyoG4XO2qtXDRYUlsllM3ckyG4,264957
+beancount_gocardless-0.1.14.dist-info/METADATA,sha256=hiKH5B8ekd9OKuN1LWNiCQxX8aMUUkZI8ok2EOO5mwM,7838
+beancount_gocardless-0.1.14.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+beancount_gocardless-0.1.14.dist-info/entry_points.txt,sha256=LFBqXX9sLw7EABb1w-2k2T8PqIDgh56F4cwtAvB2hLk,71
+beancount_gocardless-0.1.14.dist-info/licenses/LICENSE,sha256=VR2hkz3p9Sw4hSXc7S5iZTOXGeV4h-i8AO_q0zEmtkE,1074
+beancount_gocardless-0.1.14.dist-info/RECORD,,

{beancount_gocardless-0.1.12.dist-info → beancount_gocardless-0.1.14.dist-info}/entry_points.txt

@@ -1,3 +1,2 @@
 [console_scripts]
 beancount-gocardless = beancount_gocardless.cli:main
-beancount-gocardless-tui = beancount_gocardless.tui:main

beancount_gocardless-0.1.14.dist-info/licenses/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.