ledgerkit 1.0.0.dev1__tar.gz

ledgerkit-1.0.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cormac O' Sullivan
+
+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.

ledgerkit-1.0.0.dev1/MANIFEST.in

@@ -0,0 +1,5 @@
+# Exclude AI-workflow files from the source distribution (sdist).
+# The ledgerkit/ package, tests/, docs/ (human docs), README.md,
+# LICENSE, and pyproject.toml are included by setuptools automatically.
+exclude CLAUDE.md CHANGELOG.md ROADMAP.md
+recursive-exclude dev-docs *

ledgerkit-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: ledgerkit
+Version: 1.0.0.dev1
+Summary: Python parser and library for hledger journal files — CLI tools, DataFrame export, and a clean data model for the Python ecosystem
+License: MIT
+Project-URL: Homepage, https://github.com/ctosullivan/ledgerkit
+Project-URL: Repository, https://github.com/ctosullivan/ledgerkit
+Project-URL: Bug Tracker, https://github.com/ctosullivan/ledgerkit/issues
+Project-URL: Changelog, https://github.com/ctosullivan/ledgerkit/blob/main/CHANGELOG.md
+Keywords: hledger,ledger,accounting,plain-text-accounting,finance,pandas
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == "pandas"
+Dynamic: license-file
+
+# ledgerkit
+
+[![Tests](https://github.com/ctosullivan/ledgerkit/actions/workflows/tests.yml/badge.svg)](https://github.com/ctosullivan/ledgerkit/actions/workflows/tests.yml)
+
+A Python implementation of the [hledger](https://hledger.org) 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
+
+```bash
+pip install ledgerkit
+```
+
+With optional pandas support:
+
+```bash
+pip install ledgerkit[pandas]
+```
+
+### Development install
+
+```bash
+git clone https://github.com/ctosullivan/ledgerkit.git
+cd ledgerkit
+pip install -e ".[pandas]"
+```
+
+## Usage
+
+### CLI
+
+```bash
+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:
+
+```bash
+python -m ledgerkit balance myfile.journal
+```
+
+### Python library
+
+```python
+import ledgerkit
+
+journal = ledgerkit.load("myfile.journal")
+accounts = journal.accounts()
+balance  = journal.balance()
+```
+
+See [docs/python-api.md](docs/python-api.md) for the full library reference.
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | Installation, first run, verification |
+| [docs/usage.md](docs/usage.md) | CLI commands with examples |
+| [docs/journal-format.md](docs/journal-format.md) | Supported journal syntax with annotated examples |
+| [docs/python-api.md](docs/python-api.md) | Python library reference |
+
+## Python ecosystem (pandas)
+
+Install the optional pandas extra for DataFrame export:
+
+```bash
+pip install ledgerkit[pandas]
+```
+
+Then:
+
+```python
+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
+
+```bash
+# Run all tests
+python -m unittest discover -s tests -t . -v
+```
+
+See [dev-docs/architecture.md](dev-docs/architecture.md) for module design and
+[dev-docs/api-spec.md](dev-docs/api-spec.md) for the full API specification.
+
+## Hledger Compatibility
+
+See [dev-docs/hledger-compatibility.md](dev-docs/hledger-compatibility.md) for which
+hledger journal features are supported in v1.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines, commit
+message format, and branch naming. This project follows the
+[Contributor Code of Conduct](CODE_OF_CONDUCT.md).
+
+### With AI tooling (Claude Code)
+
+Clone the full repository including AI-workflow files:
+
+```bash
+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`):
+
+```bash
+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.

ledgerkit-1.0.0.dev1/README.md

@@ -0,0 +1,176 @@
+# ledgerkit
+
+[![Tests](https://github.com/ctosullivan/ledgerkit/actions/workflows/tests.yml/badge.svg)](https://github.com/ctosullivan/ledgerkit/actions/workflows/tests.yml)
+
+A Python implementation of the [hledger](https://hledger.org) 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
+
+```bash
+pip install ledgerkit
+```
+
+With optional pandas support:
+
+```bash
+pip install ledgerkit[pandas]
+```
+
+### Development install
+
+```bash
+git clone https://github.com/ctosullivan/ledgerkit.git
+cd ledgerkit
+pip install -e ".[pandas]"
+```
+
+## Usage
+
+### CLI
+
+```bash
+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:
+
+```bash
+python -m ledgerkit balance myfile.journal
+```
+
+### Python library
+
+```python
+import ledgerkit
+
+journal = ledgerkit.load("myfile.journal")
+accounts = journal.accounts()
+balance  = journal.balance()
+```
+
+See [docs/python-api.md](docs/python-api.md) for the full library reference.
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [docs/getting-started.md](docs/getting-started.md) | Installation, first run, verification |
+| [docs/usage.md](docs/usage.md) | CLI commands with examples |
+| [docs/journal-format.md](docs/journal-format.md) | Supported journal syntax with annotated examples |
+| [docs/python-api.md](docs/python-api.md) | Python library reference |
+
+## Python ecosystem (pandas)
+
+Install the optional pandas extra for DataFrame export:
+
+```bash
+pip install ledgerkit[pandas]
+```
+
+Then:
+
+```python
+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
+
+```bash
+# Run all tests
+python -m unittest discover -s tests -t . -v
+```
+
+See [dev-docs/architecture.md](dev-docs/architecture.md) for module design and
+[dev-docs/api-spec.md](dev-docs/api-spec.md) for the full API specification.
+
+## Hledger Compatibility
+
+See [dev-docs/hledger-compatibility.md](dev-docs/hledger-compatibility.md) for which
+hledger journal features are supported in v1.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines, commit
+message format, and branch naming. This project follows the
+[Contributor Code of Conduct](CODE_OF_CONDUCT.md).
+
+### With AI tooling (Claude Code)
+
+Clone the full repository including AI-workflow files:
+
+```bash
+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`):
+
+```bash
+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.

ledgerkit-1.0.0.dev1/ledgerkit/__init__.py

@@ -0,0 +1,51 @@
+"""ledgerkit: a Python implementation of the hledger plain-text accounting tool."""
+
+from ledgerkit.loader import load_journal as load
+from ledgerkit.models import (
+    BalanceAssertion,
+    BalanceRow,
+    Query,
+    RegisterRow,
+    ReportSection,
+    ReportSpec,
+    ReportSectionResult,
+    SourceSpan,
+)
+from ledgerkit.parser import parse_string_lenient, resolve_elision
+from ledgerkit.reports import (
+    AccountsResult,
+    BalanceResult,
+    JournalStats,
+    RegisterResult,
+    balance_from_spec,
+)
+from ledgerkit.checks import CheckError, check_transaction_autobalanced
+from ledgerkit.writer import journal_to_text, transaction_to_text
+from ledgerkit.editor_model import EditorDocument
+from ledgerkit.commodity_style import CommodityStyle
+
+__version__ = "1.0.0.dev1"
+__all__ = [
+    "load",
+    "AccountsResult",
+    "BalanceAssertion",
+    "BalanceResult",
+    "BalanceRow",
+    "CheckError",
+    "CommodityStyle",
+    "EditorDocument",
+    "JournalStats",
+    "RegisterResult",
+    "RegisterRow",
+    "ReportSection",
+    "ReportSpec",
+    "ReportSectionResult",
+    "SourceSpan",
+    "balance_from_spec",
+    "check_transaction_autobalanced",
+    "journal_to_text",
+    "parse_string_lenient",
+    "resolve_elision",
+    "transaction_to_text",
+    "__version__",
+]

ledgerkit-1.0.0.dev1/ledgerkit/__main__.py

@@ -0,0 +1,12 @@
+"""Enables `python -m ledgerkit` invocation.
+
+Usage:
+    python -m ledgerkit <command> <journal-file>
+
+This is equivalent to running the `ledgerkit` CLI entry point directly.
+"""
+
+import sys
+from ledgerkit.cli import main
+
+sys.exit(main())

ledgerkit-1.0.0.dev1/ledgerkit/_pandas_compat.py

@@ -0,0 +1,21 @@
+"""Lazy import helper for optional pandas dependency."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd  # noqa: F401 — type hints only
+
+
+def require_pandas():
+    """Import and return the pandas module, raising ImportError with a helpful
+    message if it is not installed."""
+    try:
+        import pandas as pd
+        return pd
+    except ImportError:
+        raise ImportError(
+            "pandas is required for DataFrame export. "
+            "Install it with: pip install ledgerkit[pandas]"
+        ) from None