Ledger: A Parsed Ledger File#

class means.types.Ledger.Ledger(*, path: Annotated[Path, PathType(path_type=file)], users: list[User] = [], transactions: list[Transaction] = [])#

Represents a single parsed .ledger file.

I Loading and Serialization#

Ledger.serialize() → str#

Transform this python instance into a valid .ledger file.

classmethod Ledger.load(user: User) → Self#

Load a ledger from the filesystem for the given user.

classmethod Ledger.setup(directory: Annotated[Path, PathType(path_type=dir)]) → None#

Perform one-time static setup tasks.

II Ingestion Pipeline#

classmethod Ledger.find_new_files(transactions: Annotated[Path, PathType(path_type=dir)]) → dict[str, list[Annotated[Path, PathType(path_type=file)]]]#

Find all new CSV files in the transactions directory.

Parameters:

transactions – The directory to scan for downloaded .csv files.

Returns:

A mapping of bank-account uid to the files it owns.

static Ledger.line_filter(line: str, ignore_strs: list[str])#

Return True if the line should be included in the cleaned CSV, False otherwise.

classmethod Ledger.should_grow() → bool#

Return True if accounts.ledger is missing or older than its seed file.

Ledger.apply_templates(tr: Transaction) → bool#

Apply any memo-based templates to this transaction, returning True if one was applied.

Ledger.apply_routes(tr: Transaction, i: int, to_drop: set[int]) → bool#

Apply the first matching route to this transaction, returning True if one was applied.

Ledger.check_transactions(transactions: list[Transaction]) → bool#

Check for any problems with the given transactions, such as invalid accounts.

Ledger.clean_csv(csvfile: Path, bank_account: BankAccount) → str#

Clean a raw bank .csv into a standardized form ready for ingestion.

Applies bank-specific standardizations — such as skipping the first few lines or omitting a particular account — replaces the bank’s CSV header with the standardized one, and sanitizes description fields.

Parameters:

  • csvfile – Transaction history downloaded from an institution.

  • bank_account – Configuration info for this institution.

Returns:

A cleaned version of the csv ready for ingestion by ledger convert.

Ledger.csv_to_ledger(csv: str, acct: BankAccount) → list[Transaction]#

Translate cleaned csv text into transactions via ledger convert.

Parameters:

  • csv – The cleaned csv text to convert.

  • acct – The bank account the data belongs to.

Returns:

The transactions parsed from the converted output.

III Ledger Maintenance#

Ledger.merge(new: list[Transaction]) → None#

Merge a new set of transactions into the existing ledger, replacing any duplicates.

Ledger.write() → None#

Write this ledger back to its file.

Ledger.sort() → None#

Sort the transactions in this ledger by date, then by uid.

Ledger.clean_ledger(transactions: list[Transaction]) → list[Transaction]#

Apply templates and routes to the given transactions.

IV Views and Archival#

Ledger.accounts#

The set of registered accounts that belong to this ledger’s users.

Ledger.base_user#

The first/primary user for this ledger.

Ledger.new_files#

A mapping of bank-account uid to any new CSV files found for this ledger’s users.

Ledger.archive() → None#

Archive any processed .csv files.