Metadata-Version: 2.4
Name: ledgerloom
Version: 0.1.2
Summary: LedgerLoom: accounting concepts for the modern software mind.
Author: PyStatsV1
License: MIT
Project-URL: Homepage, https://github.com/pystatsv1/ledgerloom
Project-URL: Repository, https://github.com/pystatsv1/ledgerloom
Project-URL: Issues, https://github.com/pystatsv1/ledgerloom/issues
Project-URL: Documentation, https://ledgerloom.readthedocs.io
Project-URL: Changelog, https://github.com/pystatsv1/ledgerloom/blob/main/CHANGELOG.md
Keywords: accounting,bookkeeping,double-entry,ledger,event-sourcing,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Dynamic: license-file

# LedgerLoom

LedgerLoom is a tiny, opinionated Python project that teaches accounting using modern developer mental models:
**event logs**, **derived views**, and **invariants**.

It ships as:

- a Python package (`ledgerloom`) you can run locally
- a ReadTheDocs “textbook” with short chapters + reproducible outputs

## Install

```bash
pip install ledgerloom


## Run Chapter 01 (Journal vs Event Log)

This chapter generates a small, deterministic demo dataset and writes artifacts to an output folder:

```bash
python -m ledgerloom.chapters.ch01_journal_vs_eventlog --outdir outputs/ledgerloom --seed 123
```

## You should see files like:

**journal.csv (traditional accounting journal)**

**eventlog.jsonl (append-only event log)**

**ledger_view.csv (derived view)**

**trial_balance.csv (invariant check)**

**entry_explanations.md (human-friendly explanation)**


# LedgerLoom

**LedgerLoom** teaches accounting using modern developer mental models: **event logs**, **database views**, **invariants**, and **reproducible pipelines**.

It is both:
1) a **textbook-style** set of chapters on Read the Docs, and  
2) a **tiny, MIT-licensed Python library + CLI** for generating and validating accounting-shaped artifacts.

---

## Links

- Docs: https://ledgerloom.readthedocs.io/en/latest/
- PyPI: https://pypi.org/project/ledgerloom/
- GitHub: https://github.com/pystatsv1/ledgerloom

---

## Why LedgerLoom exists

Many people learn accounting as rules + vocabulary.

LedgerLoom teaches accounting as **systems engineering**:

- a **ledger** is a *database view* of an **event log**
- **double-entry** is a **consistency invariant**
- a **trial balance** is an automated **check**
- financial statements are **deterministic outputs** from well-defined transformations

**Core idea:**  
> Don’t just calculate results — engineer them.

---

## The mental model mapping

| Accounting concept | Developer mental model |
|---|---|
| Journal entries | Append-only event log (immutable facts) |
| General ledger | Derived view / projection over events |
| Double-entry | Invariant: debits == credits (by entry) |
| Trial balance | Automated check over account totals |
| Close process | Period-end transformation + roll-forward |
| Audit trail | Reproducibility + provenance + diffs |
| Reconciliation | Control loop: expected vs observed |

---

## Install

```bash
pip install ledgerloom
