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

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.13.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.