ledgerkit 1.0.0.dev1

Python parser and library for hledger journal files — CLI tools, DataFrame export, and a clean data model for the Python ecosystem

ledgerkit

A Python implementation of the hledger plain-text accounting tool.

Features

• Parse .journal files compatible with the hledger 1.52 format
• Comprehensive directive support: include, account, commodity, payee, alias, P, Y, D, apply account
• Core CLI commands: balance, register, print, accounts, stats, check
• Strict mode (-s) and balance assertions
• Multi-commodity balances with tree rollup
• Commodity display style inference and -c override flag
• Optional pandas DataFrame export (pip install ledgerkit[pandas])
• Editor-integration layer: lenient parser, round-trip writer, EditorDocument
• Pure Python — no third-party runtime dependencies
• Python 3.8–3.12

Requirements

• Python 3.8+

Installation

pip install ledgerkit

With optional pandas support:

pip install ledgerkit[pandas]

Development install

git clone https://github.com/ctosullivan/ledgerkit.git
cd ledgerkit
pip install -e ".[pandas]"

Usage

CLI

ledgerkit balance myfile.journal
ledgerkit register myfile.journal
ledgerkit accounts myfile.journal
ledgerkit print myfile.journal
ledgerkit stats myfile.journal

You can also invoke ledgerkit as a Python module:

python -m ledgerkit balance myfile.journal

Python library

import ledgerkit

journal = ledgerkit.load("myfile.journal")
accounts = journal.accounts()
balance  = journal.balance()

See docs/python-api.md for the full library reference.

Documentation

Guide	Description
docs/getting-started.md	Installation, first run, verification
docs/usage.md	CLI commands with examples
docs/journal-format.md	Supported journal syntax with annotated examples
docs/python-api.md	Python library reference

Python ecosystem (pandas)

Install the optional pandas extra for DataFrame export:

pip install ledgerkit[pandas]

Then:

import ledgerkit

journal = ledgerkit.load("myfile.journal")

# Export all postings to a DataFrame
df = journal.to_dataframe()
print(df.groupby("account")["amount"].sum())

# Or export directly from a report object
balance_df = journal.balance().to_dataframe()
register_df = journal.register().to_dataframe()
accounts_df = journal.accounts().to_dataframe()

Development

# Run all tests
python -m unittest discover -s tests -t . -v

See dev-docs/architecture.md for module design and dev-docs/api-spec.md for the full API specification.

Hledger Compatibility

See dev-docs/hledger-compatibility.md for which hledger journal features are supported in v1.

Contributing

See CONTRIBUTING.md for pull request guidelines, commit message format, and branch naming. This project follows the Contributor Code of Conduct.

With AI tooling (Claude Code)

Clone the full repository including AI-workflow files:

git clone https://github.com/ctosullivan/ledgerkit.git

Without AI tooling

Use sparse checkout to clone only the source code, tests, and human docs (excludes CLAUDE.md, dev-docs/, CHANGELOG.md, ROADMAP.md):

git clone --filter=blob:none --sparse https://github.com/ctosullivan/ledgerkit.git
cd ledgerkit
git sparse-checkout set ledgerkit tests docs README.md LICENSE pyproject.toml

Acknowledgements

ledgerkit is a Python implementation inspired by two pioneering plain-text accounting projects. We gratefully acknowledge their authors and contributors.

Ledger

John Wiegley created Ledger, the original plain-text double-entry accounting tool, which established the journal file format and accounting model that this ecosystem is built upon.

https://github.com/ledger/ledger

hledger

Simon Michael created hledger, a Haskell implementation of Ledger's concepts, which has since evolved its own rich feature set and extensive documentation. ledgerkit's journal format support is modelled primarily on the hledger 1.52 specification.

https://github.com/simonmichael/hledger

A full list of hledger contributors can be found at:

https://github.com/simonmichael/hledger/blob/main/doc/CREDITS.md

Their work — and the broader plain-text accounting community — makes ledgerkit possible.