General ledger: posts journal entries to accounts and closes the books at period end.
The ledger is the core of the double-entry bookkeeping system. It holds a
:class:ChartOfAccounts (the accounts) and a :class:Journal (the record of
all entries). Posting an entry simultaneously records it in the journal and
updates the affected T-account balances.
Posting flow::
JournalEntry ──> Ledger.post()
├── journal.add_entry(entry) (audit trail)
├── account.debit(amount) (for each debit leg)
└── account.credit(amount) (for each credit leg)
Period-end closing sequence::
1. close_contra_accounts()
Contra income/expense balances are netted against their parent accounts.
2. close_income_and_expense_accounts()
All income and expense account balances transfer to Income Summary.
3. close_income_summary_account()
Income Summary balance transfers to Retained Earnings.
Classes:
-
Ledger–The general ledger.
dataclass
Ledger(
chart_of_accounts: ChartOfAccounts,
journal: Journal = Journal(),
date_closed: date | None = None,
)
The general ledger.
Attributes:
-
chart_of_accounts(ChartOfAccounts) –The chart of accounts containing all T-accounts.
-
journal(Journal) –The journal recording every posted entry.
-
date_closed(date | None) –The date of the most recent period-end close, or
None.
Methods:
-
close_contra_accounts–Net contra account balances against their parent income/expense accounts.
-
close_income_and_expense_accounts–Transfer all income and expense balances to Income Summary.
-
close_income_summary_account–Transfer the Income Summary balance to Retained Earnings.
-
close_ledger–Run the full period-end closing sequence.
-
get_account_balances–Return a snapshot of all account balances.
-
get_accounts_by_type–Return all accounts matching the given type.
-
post–Post a journal entry: record it and update account balances.
-
set_account_balances–Set opening balances directly on accounts.
close_contra_accounts(date: date) -> None
Net contra account balances against their parent income/expense accounts.
For an income account with contra expenses (e.g., Trading Income with Unrealized Trading Loss), this posts an entry that zeroes the contra balances and reduces the parent's balance by the same amount.
close_income_and_expense_accounts(date: date) -> None
Transfer all income and expense balances to Income Summary.
Skips contra accounts (already closed) and the Income Summary account itself.
close_income_summary_account(date: date) -> None
Transfer the Income Summary balance to Retained Earnings.
close_ledger(date: date) -> None
Run the full period-end closing sequence.
- Net contra accounts against their parents.
- Transfer income/expense balances to Income Summary.
- Transfer Income Summary to Retained Earnings.
get_account_balances() -> AccountBalances
Return a snapshot of all account balances.
get_accounts_by_type(
account_type: AccountType,
) -> list[TAccount]
Return all accounts matching the given type.
post(entry: JournalEntry) -> None
Post a journal entry: record it and update account balances.
For each debit leg, the corresponding account's debit side increases. For each credit leg, the corresponding account's credit side increases. The entry is appended to the journal for audit purposes.
set_account_balances(balances: AccountBalances) -> None
Set opening balances directly on accounts.
This bypasses the journal (no entry is recorded) and should only be used for initial setup, never during normal operation.
Each balance is applied to the account's normal side: debit-normal accounts get a debit, credit-normal accounts get a credit.