beancount-gocardless 0.1.7__tar.gz → 0.1.9__tar.gz

beancount_gocardless-0.1.9/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Upload Python Package to PyPI when a Release is Created
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  pypi-publish:
+    name: Publish release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/beancount-gocardless
+    permissions:
+      id-token: write
+    steps:
+       - uses: actions/checkout@v4
+       - name: Install uv
+         uses: astral-sh/setup-uv@v4
+         with:
+           version: "latest"
+       - name: Set up Python
+         uses: actions/setup-python@v4
+         with:
+           python-version: "3.12"
+       - name: Install dependencies
+         run: uv sync --extra dev
+       - name: Build package
+         run: uv build
+       - name: Publish package to PyPI
+         run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
+       - name: Build Sphinx documentation
+         run: |
+           uv run sphinx-build -b html docs/ docs/_build
+       - name: Upload documentation artifact
+         uses: actions/upload-artifact@v4
+         with:
+           name: sphinx-docs
+           path: docs/_build

beancount_gocardless-0.1.9/.gitignore

@@ -0,0 +1,182 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   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
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/⚠️
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+**/.DS_Store
+
+# GoCardless cache files and temp data
+*.sqlite
+*.bean
+
+# API spec files (regenerate from swagger.json)
+openapi.yaml

beancount_gocardless-0.1.9/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.8
+    hooks:
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

beancount_gocardless-0.1.9/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+   os: ubuntu-22.04
+   tools:
+      python: "3.12"
+   jobs:
+      post_create_environment:
+         - python -m pip install poetry
+      post_install:
+         - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with dev
+
+sphinx:
+   configuration: docs/conf.py
+   builder: dirhtml

beancount_gocardless-0.1.9/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

beancount_gocardless-0.1.9/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: beancount-gocardless
+Version: 0.1.9
+License-Expression: Unlicense
+License-File: LICENSE
+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: requests
+Requires-Dist: requests-cache
+Requires-Dist: rich
+Requires-Dist: textual-dev>=1.7.0
+Requires-Dist: textual>=3.2.0
+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'
+Description-Content-Type: text/markdown
+
+beancount-gocardless
+====================
+
+GoCardless API client with models manually recreated from swagger spec, plus Beancount importer.
+
+Inspired by https://github.com/tarioch/beancounttools.
+
+Full documentation at https://beancount-gocardless.readthedocs.io/en/latest/.
+
+**Key Features:**
+
+- **API Client:** Models based on swagger spec. Built-in caching via `requests-cache`.
+- **GoCardLess CLI**\: A command-line interface to manage authorization with the GoCardless API:
+
+    - Listing available banks in a specified country (default: GB).
+    - Creating a link to a specific bank using its ID.
+    - Listing authorized accounts.
+    - Deleting an existing link.
+    - Uses environment variables (`GOCARDLESS_SECRET_ID`, `GOCARDLESS_SECRET_KEY`) or command-line arguments for API credentials.
+- **Beancount Importer:**  A `beangulp.Importer` implementation to easily import transactions fetched from the GoCardless API directly into your Beancount ledger.
+
+You'll need to create a GoCardLess account on https://bankaccountdata.gocardless.com/overview/ to get your credentials.
+
+## Development
+
+### API Coverage
+
+The GoCardless client provides **complete API coverage** with Pydantic models for all endpoints and data structures:
+
+**🏦 Core Banking:**
+- **Accounts**: Full account metadata, balances, details, and transactions
+- **Institutions**: Bank/institution information and capabilities
+- **Requisitions**: Bank link management with full lifecycle support
+
+**📋 Agreements & Permissions:**
+- **End User Agreements**: Complete agreement lifecycle management
+- **Access Scopes**: Granular permission control
+- **Reconfirmations**: Agreement renewal workflows
+
+**🔧 Advanced Features:**
+- **Integrations**: Institution capability discovery
+- **Token Management**: JWT token handling (internal)
+- **Pagination**: Full paginated response support
+- **Error Handling**: Error response models
+
+**📊 Rich Data Models:**
+- **Transactions**: Complete transaction details with currency exchange, balances, and metadata
+- **Balances**: Multi-currency balance information with transaction impact
+- **Account Details**: Extensive account information including ownership and addresses
+
+Models manually recreated from the swagger spec, providing type-safe access to every API feature.
+
+**Installation:**
+
+```bash
+pip install beancount-gocardless
+```
+
+**Usage**
+```yaml
+#### gocardless.yaml
+secret_id: $GOCARDLESS_SECRET_ID
+secret_key: $GOCARDLESS_SECRET_KEY
+
+cache_options: # by default, no caching if cache_options is not provided
+  cache_name: "gocardless"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+    - id: <REDACTED_UUID>
+    asset_account: "Assets:Banks:Revolut:Checking"
+```
+
+```python
+#### my.import
+#!/usr/bin/env python
+
+import beangulp
+from beancount_gocardless import GoCardLessImporter
+from smart_importer import apply_hooks, PredictPostings, PredictPayees
+
+importers = [
+    apply_hooks(
+        GoCardLessImporter(),
+        [
+            PredictPostings(),
+            PredictPayees(),
+        ],
+    )
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers)
+    ingest()
+```
+
+Import your data from GoCardLess's API
+```bash
+python my.import extract ./gocardless.yaml --existing ./ledger.bean
+```

beancount_gocardless-0.1.9/README.md

@@ -0,0 +1,102 @@
+beancount-gocardless
+====================
+
+GoCardless API client with models manually recreated from swagger spec, plus Beancount importer.
+
+Inspired by https://github.com/tarioch/beancounttools.
+
+Full documentation at https://beancount-gocardless.readthedocs.io/en/latest/.
+
+**Key Features:**
+
+- **API Client:** Models based on swagger spec. Built-in caching via `requests-cache`.
+- **GoCardLess CLI**\: A command-line interface to manage authorization with the GoCardless API:
+
+    - Listing available banks in a specified country (default: GB).
+    - Creating a link to a specific bank using its ID.
+    - Listing authorized accounts.
+    - Deleting an existing link.
+    - Uses environment variables (`GOCARDLESS_SECRET_ID`, `GOCARDLESS_SECRET_KEY`) or command-line arguments for API credentials.
+- **Beancount Importer:**  A `beangulp.Importer` implementation to easily import transactions fetched from the GoCardless API directly into your Beancount ledger.
+
+You'll need to create a GoCardLess account on https://bankaccountdata.gocardless.com/overview/ to get your credentials.
+
+## Development
+
+### API Coverage
+
+The GoCardless client provides **complete API coverage** with Pydantic models for all endpoints and data structures:
+
+**🏦 Core Banking:**
+- **Accounts**: Full account metadata, balances, details, and transactions
+- **Institutions**: Bank/institution information and capabilities
+- **Requisitions**: Bank link management with full lifecycle support
+
+**📋 Agreements & Permissions:**
+- **End User Agreements**: Complete agreement lifecycle management
+- **Access Scopes**: Granular permission control
+- **Reconfirmations**: Agreement renewal workflows
+
+**🔧 Advanced Features:**
+- **Integrations**: Institution capability discovery
+- **Token Management**: JWT token handling (internal)
+- **Pagination**: Full paginated response support
+- **Error Handling**: Error response models
+
+**📊 Rich Data Models:**
+- **Transactions**: Complete transaction details with currency exchange, balances, and metadata
+- **Balances**: Multi-currency balance information with transaction impact
+- **Account Details**: Extensive account information including ownership and addresses
+
+Models manually recreated from the swagger spec, providing type-safe access to every API feature.
+
+**Installation:**
+
+```bash
+pip install beancount-gocardless
+```
+
+**Usage**
+```yaml
+#### gocardless.yaml
+secret_id: $GOCARDLESS_SECRET_ID
+secret_key: $GOCARDLESS_SECRET_KEY
+
+cache_options: # by default, no caching if cache_options is not provided
+  cache_name: "gocardless"
+  backend: "sqlite"
+  expire_after: 3600
+  old_data_on_error: true
+
+accounts:
+    - id: <REDACTED_UUID>
+    asset_account: "Assets:Banks:Revolut:Checking"
+```
+
+```python
+#### my.import
+#!/usr/bin/env python
+
+import beangulp
+from beancount_gocardless import GoCardLessImporter
+from smart_importer import apply_hooks, PredictPostings, PredictPayees
+
+importers = [
+    apply_hooks(
+        GoCardLessImporter(),
+        [
+            PredictPostings(),
+            PredictPayees(),
+        ],
+    )
+]
+
+if __name__ == "__main__":
+    ingest = beangulp.Ingest(importers)
+    ingest()
+```
+
+Import your data from GoCardLess's API
+```bash
+python my.import extract ./gocardless.yaml --existing ./ledger.bean
+```

beancount_gocardless-0.1.9/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

beancount_gocardless-0.1.9/docs/cli.rst

@@ -0,0 +1,43 @@
+GoCardless CLI
+===============
+
+Commands: list banks, create/delete links, list accounts, check balances. Uses GoCardlessClient. Args or env vars.
+
+Usage
+-----
+
+.. code-block:: console
+
+    beancount-gocardless <mode> [options]
+
+Modes
+-----
+
+- list_banks: Banks by country
+- create_link: Create bank link
+- list_accounts: Connected accounts
+- delete_link: Delete link
+- balance: Account balance
+
+Options
+-------
+
+- --secret_id: Secret ID (env: GOCARDLESS_SECRET_ID)
+- --secret_key: Secret key (env: GOCARDLESS_SECRET_KEY)
+- --country: Country code, default "GB" (list_banks)
+- --reference: Reference, default "beancount" (create_link/delete_link)
+- --bank: Bank ID (create_link)
+- --account: Account ID (balance)
+- --cache: Enable caching
+- --cache_backend: Backend, default "sqlite"
+- --cache_expire: Expiry secs, default 0
+- --cache_name: Name, default "gocardless"
+
+Examples
+--------
+
+- List UK banks: beancount-gocardless list_banks --country GB
+- Create link: beancount-gocardless create_link --bank MY_BANK_ID --reference myref
+- List accounts: beancount-gocardless list_accounts
+- Delete link: beancount-gocardless delete_link --reference myref
+- Check balance: beancount-gocardless balance --account MY_ACCOUNT_ID

beancount_gocardless-0.1.9/docs/client.rst

@@ -0,0 +1,43 @@
+GoCardless Client
+=================
+
+Auto-generated from swagger.json. Typed with Pydantic. Full caching support. Header stripping. Token refresh. Cache status check.
+
+Features
+--------
+
+- Typed responses via Pydantic models
+- Convenience methods: list_banks(), create_bank_link(), get_all_accounts()
+- All 14 API endpoints
+- Error handling with token refresh
+- Caching: sqlite, configurable expiry
+- Header stripping for privacy
+- Cache debugging via check_cache_status()
+
+Usage
+-----
+
+.. code-block:: python
+
+    from beancount_gocardless import GoCardlessClient
+
+    client = GoCardlessClient("secret_id", "secret_key", cache_options={
+        "cache_name": "my_cache",
+        "expire_after": 3600
+    })
+
+    banks = client.list_banks("GB")
+    accounts = client.get_all_accounts()
+
+CLI
+---
+
+.. code-block:: bash
+
+    beancount-gocardless list_banks --country GB --cache --cache_expire 3600
+    beancount-gocardless create_link --reference mybank --bank SANDBOXFINANCE_SFIN0000 --cache
+
+Regeneration
+------------
+
+Update API: cd openapi; ./regen_simple_client.sh

beancount_gocardless-0.1.9/docs/conf.py

@@ -0,0 +1,69 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))  # Correct path to your source
+
+print()
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "beancount-gocardless"
+copyright = "2025, forgx1"
+author = "forgx1"
+release = "0.1.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc.typehints",
+]
+# Add this to enable Markdown in docstrings:
+autodoc_mock_imports = ["requests", "requests-cache", "beancount", "beangulp", "pyyaml"]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "special-members": "__init__",
+}
+autodoc_typehints = "description"
+
+# Napoleon settings for Google and NumPy style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_use_ivar = True
+templates_path = ["_templates"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# Enable proper parsing of markdown in docstrings
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# MyST parser settings for markdown support
+myst_parse_docstrings = True
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]