Module cache 

Binary cache for parsed ledgers.

This module provides a caching layer that can dramatically speed up subsequent loads of unchanged beancount files by serializing the parsed directives to a binary format using rkyv.

How it works

1. When loading a file, compute a hash of all source files
2. Check if a cache file exists with a matching hash
3. If yes, deserialize and return immediately (typically <1ms)
4. If no, parse normally, serialize to cache, and return

Cache location

By default, cache files are stored alongside the main ledger as a hidden dotfile: ledger.beancount → .ledger.beancount.cache. This matches Python beancount’s .{filename}.picklecache convention.

Two environment variables control the location, both compatible with Python beancount and honored at the loader level (so any consumer of load_cache_entry / save_cache_entry gets the kill switch for free):

• BEANCOUNT_DISABLE_LOAD_CACHE: when set (even to an empty value), load_cache_entry returns None and save_cache_entry is a no-op.
• BEANCOUNT_LOAD_CACHE_FILENAME: a path pattern that may contain {filename} (replaced with the source basename). Relative paths resolve against the source directory; absolute paths are used as-is. If the target directory doesn’t exist, save_cache_entry creates it.

Structs

ArchivedCacheEntry

An archived CacheEntry

ArchivedCachedOptions

An archived CachedOptions

ArchivedCachedPlugin

An archived CachedPlugin

CacheEntry

Complete cache entry containing all data needed to restore a LoadResult.

CacheEntryResolver

The resolver for an archived CacheEntry

CachedOptions

Cached options - a serializable subset of Options.

CachedOptionsResolver

The resolver for an archived CachedOptions

CachedPlugin

Cached plugin information.

CachedPluginResolver

The resolver for an archived CachedPlugin

Constants

CACHE_FILENAME_ENV

Environment variable that overrides the default cache filename pattern.

DISABLE_CACHE_ENV

Environment variable that disables the binary cache entirely when set.

Functions

cache_disabled_by_env

Returns true if BEANCOUNT_DISABLE_LOAD_CACHE is set in the environment.

cache_path

Returns the cache file path for a given source file.

default_cache_path

Returns the default cache file path (no env-var lookup).

invalidate_cache

Invalidate the cache for a file.

load_cache_entry

Try to load a cache entry from disk.

save_cache_entry

Save a cache entry to disk.