bencher.cache_management
========================

.. py:module:: bencher.cache_management

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   bencher.cache_management.logger
   bencher.cache_management.CACHE_VERSION
   bencher.cache_management.DEFAULT_CACHE_SIZE_BYTES
   bencher.cache_management._MANAGED_CACHES
   bencher.cache_management._MEDIA_FOLDERS
   bencher.cache_management._MEDIA_EXTENSIONS


Classes
-------

.. autoapisummary::

   bencher.cache_management.CacheDirStats
   bencher.cache_management.CacheStats


Functions
---------

.. autoapisummary::

   bencher.cache_management.ensure_cache_version
   bencher.cache_management._fmt_size
   bencher.cache_management._dir_stats
   bencher.cache_management.cache_stats
   bencher.cache_management.print_cache_stats
   bencher.cache_management.cleanup_job_media
   bencher.cache_management.clear_all
   bencher.cache_management.clear_media
   bencher.cache_management._collect_sample_cache_keys
   bencher.cache_management.clean_orphaned_media


Module Contents
---------------

.. py:data:: logger

.. py:data:: CACHE_VERSION
   :value: '3'


.. py:data:: DEFAULT_CACHE_SIZE_BYTES
   :value: 0


.. py:data:: _MANAGED_CACHES
   :value: ('sample_cache', 'benchmark_inputs', 'history')


.. py:data:: _MEDIA_FOLDERS
   :value: ('img', 'vid', 'rrd', 'generic')


.. py:data:: _MEDIA_EXTENSIONS

.. py:function:: ensure_cache_version(cachedir: str = 'cachedir') -> None

   Check the cache version file; clear everything on mismatch.

   Called automatically when a :class:`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.


.. py:function:: _fmt_size(n: int) -> str

   Format a byte count as a human-readable string.


.. py:class:: CacheDirStats

   Statistics for a single cache or media directory.


   .. py:attribute:: path
      :type:  str


   .. py:attribute:: entries
      :type:  int


   .. py:attribute:: size_bytes
      :type:  int


   .. py:attribute:: size_limit_bytes
      :type:  int | None
      :value: None



   .. py:method:: summary_line() -> str


.. py:class:: CacheStats

   Aggregate cache statistics.


   .. py:attribute:: managed
      :type:  list[CacheDirStats]


   .. py:attribute:: media
      :type:  list[CacheDirStats]


   .. py:attribute:: total_bytes
      :type:  int


   .. py:method:: summary() -> str


.. py:function:: _dir_stats(path: pathlib.Path) -> tuple[int, int]

   Return (file_count, total_bytes) for all files under *path*.


.. py:function:: cache_stats(cachedir: str = 'cachedir') -> CacheStats

   Collect statistics for all managed caches and media directories.


.. py:function:: print_cache_stats(cachedir: str = 'cachedir') -> None

   Print a human-readable cache statistics summary.


.. py:function:: 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.


.. py:function:: clear_all(cachedir: str = 'cachedir') -> None

   Remove the entire cache directory tree.


.. py:function:: clear_media(cachedir: str = 'cachedir') -> tuple[int, int]

   Delete all files in media directories.

   Returns (files_deleted, bytes_freed).


.. py:function:: _collect_sample_cache_keys(cachedir: str) -> set[str]

   Return all keys currently in the sample cache.


.. py:function:: 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).

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

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