aemetxfb.cache

Optional SQLite-backed disk cache.

Optional disk-based response cache for AEMet API calls.

This module provides a @cached decorator backed by a single SQLite database file. Cached entries expire after the TTL defined in aemetxfb.utils.CONFIG (cache_ttl seconds).

The cache is disabled by default; enable it via

from aemetxfb import AEMetConfig, set_config

set_config(AEMetConfig(cache_enabled=True, cache_ttl=86400))

Only pure data-returning functions should be decorated. Functions that perform side-effects (downloading images, writing files) must not use @cached because their return values are typically file paths that are meaningless when replayed from cache.

Typical use case — climate data that changes rarely:

from aemetxfb.cache import cached
from aemetxfb.clim import get_normals

@cached
def my_get_normals(station: str) -> pd.DataFrame:
    return get_normals(station)

aemetxfb.cache.cache_get(key)

Retrieve a value from the cache by key.

Returns None if the key is missing or has expired.

Examples

>>> cache_get("nonexistent_key") is None  # cache disabled by default
True

Parameters:

key (str)

Return type:

Any | None

aemetxfb.cache.cache_set(key, value)

Store a value in the cache.

If the key already exists it is overwritten.

Parameters:

• key (str)

• value (Any)

Return type:

None

aemetxfb.cache.clear_cache()

Delete all entries from the cache database.

The database file itself is kept so that subsequent inserts do not need to re-create the schema.

Examples

>>> clear_cache()  # safe to call even when cache is disabled

Return type:

None

aemetxfb.cache.get_cache_stats()

Return basic statistics about the current cache.

Returns:

{"size": ..., "entries": ...} where size is the file size in bytes and entries is the number of rows in the cache table. If the database does not exist yet both values are 0.

Return type:

dict

Examples

>>> stats = get_cache_stats()
>>> "size" in stats and "entries" in stats
True

aemetxfb.cache.cached(func)

Decorator that caches the return value of a function.

The cache key is derived from the function name, positional arguments, and keyword arguments. Entries expire after CONFIG.cache_ttl seconds. If CONFIG.cache_enabled is False the decorator is a no-op and the underlying function is called every time.

Parameters that are not hashable (e.g. mutable lists) will cause a TypeError when pickling the cache key.

Examples

>>> from aemetxfb import AEMetConfig, set_config
>>> from aemetxfb.cache import cached
>>> set_config(AEMetConfig(cache_enabled=True, cache_ttl=3600))
>>> @cached
... def fetch_normals(station: str):
...     return get_normals(station)

Parameters:

func (Any)

Return type:

Any