voxcity.utils.cache
===================

.. py:module:: voxcity.utils.cache

.. autoapi-nested-parse::

   On-disk cache for downloaded geospatial data.

   Downloads are keyed by the wrapped function's fully-qualified name plus ALL of
   its bound arguments (positional and keyword, matched against the function's
   signature so equivalent calls hash the same regardless of calling
   convention). Parameters named ``output_dir`` or ``download_dir`` are excluded
   from the key, since they only control where files are staged on disk and do
   not affect the downloaded data itself -- two calls that differ only in
   ``output_dir`` should hit the same cache entry. Results are stored as pickles
   under a per-user cache directory. The cache is best-effort: any read/write
   failure falls back to a fresh download. Layout:

       <cache_dir>/downloads/<key>.pkl        # pickled return value
       <cache_dir>/downloads/<key>.meta.json  # source, args, created timestamp

   The cache directory resolves, in order: the VOXCITY_CACHE_DIR environment
   variable, else ``~/.voxcity/cache``.

   Entries never expire on their own: a cached rectangle is reused until the
   caller passes ``force_refresh=True`` or ``clear_download_cache()`` is run.
   Empty results (None or a zero-length GeoDataFrame/collection) are NOT cached,
   so a transient upstream outage cannot poison future runs.



Functions
---------

.. autoapisummary::

   voxcity.utils.cache.get_cache_dir
   voxcity.utils.cache.cached_download
   voxcity.utils.cache.clear_download_cache


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

.. py:function:: get_cache_dir() -> pathlib.Path

   Return (creating if needed) the directory downloads are cached under.


.. py:function:: cached_download(func)

   Cache a downloader's return value on disk, keyed by its arguments.

   The wrapped function gains two keyword-only controls (consumed here, not
   forwarded to ``func``): ``use_download_cache`` (default True) and
   ``force_refresh`` (default False).


.. py:function:: clear_download_cache() -> int

   Delete all cached downloads. Returns the number of files removed.