bencher.cache_management

Cache management utilities for bencher.

Architecture

Media files (images, videos, .rrd recordings) are stored in per-job-key subdirectories under cachedir/{folder}/{filename}/{job_key}/. This makes lifecycle management trivial:

Overwrite — cleanup_job_media(job_key) deletes the directory before the new benchmark run writes fresh files.
LRU eviction — clean_orphaned_media() walks the media tree, checks each job-key directory against the sample cache, and deletes directories whose entries are gone.
Full clear — clear_all() removes the entire cachedir/.

A CACHE_VERSION file inside cachedir/ guards against stale data from older formats. ensure_cache_version() auto-clears on mismatch.

Attributes

`logger`
`CACHE_VERSION`
`DEFAULT_CACHE_SIZE_BYTES`
`_MANAGED_CACHES`
`_MEDIA_FOLDERS`
`_MEDIA_EXTENSIONS`

Classes

`CacheDirStats`	Statistics for a single cache or media directory.
`CacheStats`	Aggregate cache statistics.

Functions

`ensure_cache_version`(→ None)	Check the cache version file; clear everything on mismatch.
`_fmt_size`(→ str)	Format a byte count as a human-readable string.
`_dir_stats`(→ tuple[int, int])	Return (file_count, total_bytes) for all files under path.
`cache_stats`(→ CacheStats)	Collect statistics for all managed caches and media directories.
`print_cache_stats`(→ None)	Print a human-readable cache statistics summary.
`cleanup_job_media`(→ int)	Delete the per-job-key media directories for job_key.
`clear_all`(→ None)	Remove the entire cache directory tree.
`clear_media`(→ tuple[int, int])	Delete all files in media directories.
`_collect_sample_cache_keys`(→ set[str])	Return all keys currently in the sample cache.
`clean_orphaned_media`(→ tuple[list[str], int])	Find and optionally delete per-job-key media dirs with no cache entry.

Module Contents

bencher.cache_management.logger

bencher.cache_management.CACHE_VERSION = '3'

bencher.cache_management.DEFAULT_CACHE_SIZE_BYTES = 0

bencher.cache_management._MANAGED_CACHES = ('sample_cache', 'benchmark_inputs', 'history')

bencher.cache_management._MEDIA_FOLDERS = ('img', 'vid', 'rrd', 'generic')

bencher.cache_management._MEDIA_EXTENSIONS

bencher.cache_management.ensure_cache_version(cachedir: str = 'cachedir') → None

Check the cache version file; clear everything on mismatch.

Called automatically when a Bench is instantiated. If the version file is missing or doesn’t match CACHE_VERSION, the entire cache tree is deleted so stale data from incompatible layouts doesn’t linger.

bencher.cache_management._fmt_size(n: int) → str: Format a byte count as a human-readable string.

class bencher.cache_management.CacheDirStats

Statistics for a single cache or media directory.

path: str

entries: int

size_bytes: int

size_limit_bytes: int | None = None

summary_line() → str

class bencher.cache_management.CacheStats

Aggregate cache statistics.

managed: list[CacheDirStats]

media: list[CacheDirStats]

total_bytes: int

summary() → str

bencher.cache_management._dir_stats(path: pathlib.Path) → tuple[int, int]: Return (file_count, total_bytes) for all files under path.

bencher.cache_management.cache_stats(cachedir: str = 'cachedir') → CacheStats: Collect statistics for all managed caches and media directories.

bencher.cache_management.print_cache_stats(cachedir: str = 'cachedir') → None: Print a human-readable cache statistics summary.

bencher.cache_management.cleanup_job_media(job_key: str, cachedir: str = 'cachedir') → int

Delete the per-job-key media directories for job_key.

Called automatically before a cache entry is overwritten so that stale media files from the previous run are removed.

Returns the number of directories removed.

bencher.cache_management.clear_all(cachedir: str = 'cachedir') → None: Remove the entire cache directory tree.

bencher.cache_management.clear_media(cachedir: str = 'cachedir') → tuple[int, int]

Delete all files in media directories.

Returns (files_deleted, bytes_freed).

bencher.cache_management._collect_sample_cache_keys(cachedir: str) → set[str]: Return all keys currently in the sample cache.

bencher.cache_management.clean_orphaned_media(cachedir: str = 'cachedir', dry_run: bool = True) → tuple[list[str], int]

Find and optionally delete per-job-key media dirs with no cache entry.

Walks the media tree looking for job-key subdirectories. If the key is not present in the sample cache, the directory is an orphan (its cache entry was evicted by LRU or cleared).

Parameters:

cachedir – Root cache directory.
dry_run – If True, only report orphans without deleting.

Returns:

(orphan_dirs, total_bytes) — list of orphaned directory paths and their combined size.