pygaindalf documentationο
Contents
π§ββοΈ Gaindalf the Red, White, and Blue π¬π§ ο
You shall not pass⦠until you have paid Capital Gains Tax.
pygaindalf is a Python-powered framework for automating the dark art of UK Capital Gains Tax (CGT) calculations.
Whether youβre juggling broker CSVs, taming forex conversions, deciphering ERI reports, or wrestling with S104 incantations, this project aims to be your trusty wand. Configure your spellbook, summon your data, and let π§ββοΈ Gaindalf the Red, White, and Blue π¬π§ do the rest.
1. β οΈ Disclaimerο
Use pygaindalf at your own risk.
This software is provided as-is with no guarantees or warranties. You alone are responsible for ensuring the accuracy and completeness of any reports or filings you make to HMRC or other authorities - whether generated by pygaindalf or otherwise.
Neither the authors nor distributors accept any liability for any data loss, inaccuracies, or operational failures - even if warned of potential issues.
For full details, see Sections 15 through 17 of the GPLv3 license.
2. β¨ Statusο
βAll we have to decide is what to do with the time that is given us.β - Gandalf
pygaindalf is currently a work-in-progress, a glimmer in the wizardβs eye, and not yet ready for production use.
Expect rapid development, breaking changes, and ongoing improvements. This README will evolve as the project grows.
2.1. Goalsο
pygaindalf aims to:
π§Ύ Import data from multiple brokers, CSVs, APIs, and other mystical sources.
π± Convert all values to GBP using trusted oracles (HMRC spot rates, forex APIs, etc.).
π Apply complex CGT rules: S104 matching, bed & breakfast, ERI adjustments, and other sorcery.
π€ Export results to
.yaml,.json,.csv,.xls,.txtand others, as well as formats accepted by tools like cgtcalculator.com.πΎ Save & restore the full calculation state between tax years - no need to re-slay old dragons.
π Track your holdings over time, across accounts, currencies, and securities.
𧩠Support multiple calculation engines and strategies - e.g., different rounding modes or FIFO vs HMRC rules.
βοΈ Be composable - built from small, swappable, and testable components you can easily extend.
π Be transparent - every step traceable, every transformation explainable.
π¬π§ Focus firmly on UK-specific tax laws and HMRC guidelines.
2.2. Philosophyο
pygaindalf intends to make CGT automation:
Declarative: Sane, declarative YAML configs instead of tangled scripts or spreadsheet rage.
Modular: Small, reusable, easily tested building blocks.
Extensible: Plug in your own magic to tailor calculations to your unique needs.
Transparent: Traceable, auditable calculations for peace of mind.
3. π Installationο
3.1. Requirementsο
3.2. Installing python dependenciesο
To install the required python dependencies, run:
uv sync
This will use pyproject.toml and uv.lock to install all dependencies.
3.3. Environmentο
You can either:
Activate a virtual environment (recommended):
source .venv/bin/activate
Or, skip the venv and prefix commands with
uv run, e.g.:uv run pygaindalf.py uv run pytest
4. π§ͺ Running Testsο
To run the test suite using pytest, simply execute:
uv run pytest
This will discover and run all tests in the test/ directory.
4.1. Filtering Testsο
You can filter which tests to run using pytestβs -k and -m options:
To run only tests with a specific mark (e.g.,
@pytest.mark.logging):uv run pytest -m logging
To run tests whose names match a substring or expression:
uv run pytest -k "expression"
See the pytest documentation for more details.
5. π Licenseο
pygaindalf is licensed under the GNU General Public License v3.0 (GPL-3.0) or later.
This means you are free to use, modify, and distribute the software under the terms of the GPLv3, which ensures that the project and any derivatives remain free and open.
Happy calculating, and may your gains be ever in your favour! π§ββοΈππ