api_24sea.cache
===============

.. py:module:: api_24sea.cache

.. autoapi-nested-parse::

   Optional, bounded local storage for successful data-query responses.



Classes
-------

.. autoapisummary::

   api_24sea.cache.QueryCache


Functions
---------

.. autoapisummary::

   api_24sea.cache.query_cache_key
   api_24sea.cache.resolve_query_cache


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

.. py:class:: QueryCache(directory: Optional[Union[str, pathlib.Path]] = None, ttl: float = 86400, max_bytes: int = 1024**3)

   Cache query responses on disk without storing credentials or pickles.

   Parameters
   ----------
   directory : str or pathlib.Path, optional
       Dedicated cache directory. Defaults to the user's XDG cache directory.
   ttl : float, default 86400
       Maximum age of a cached response, in seconds.
   max_bytes : int, default 1073741824
       Maximum total size of cache entries. Oldest entries are evicted first.

   Notes
   -----
   Cached values are snapshots. Use ``force_cache_miss=True`` to refresh both
   local and server caches after underlying data or permissions change.


   .. py:method:: get(key: str, url: str, method: str) -> Optional[httpx.Response]

      Read an intact, unexpired response, or return a cache miss.



   .. py:method:: put(key: str, response: httpx.Response) -> None

      Atomically store a successfully decoded response and enforce size.



   .. py:method:: prune() -> None

      Remove expired entries and then the oldest entries over the limit.



   .. py:method:: clear() -> None

      Remove this cache's query entries while preserving unrelated files.



.. py:function:: query_cache_key(url: str, method: str, params: Dict, headers: Optional[Dict[str, str]], auth: Optional[httpx.BasicAuth]) -> str

   Hash the query, endpoint, headers, and credential scope into a key.

   No credentials, query parameters, or request headers are persisted in the
   filename or cache metadata. Refresh flags do not change result identity.


.. py:function:: resolve_query_cache(cache: Union[bool, QueryCache]) -> Optional[QueryCache]

   Resolve the opt-in shorthand without creating directories eagerly.