akkudoktoreos.core.cache.cache_in_file

akkudoktoreos.core.cache.cache_in_file(ignore_params: List[str] = [], force_update: bool | None = None, until_date: Any | None = None, until_datetime: Any | None = None, with_ttl: Any | None = None, mode: Literal['w', 'w+', 'wb', 'wb+', 'r', 'r+', 'rb', 'rb+'] = 'wb+', delete: bool = False, suffix: str | None = None) → Callable[[Callable[[Param], RetType]], Callable[[Param], RetType]]

Cache the output of a function into a temporary file.

This decorator caches the result of a function call in a temporary file. The cache is identified by a key derived from the function’s input arguments, excluding those specified in ignore_params. This is useful for caching results of expensive computations while avoiding redundant recalculations.

The cache file is created using CacheFileStore and stored with the generated key. If a valid cache file exists, it is returned instead of recomputing the result. The cache expiration is controlled by the until_date, until_datetime, with_ttl, or force_update arguments. If these arguments are present in the function call, their values override those specified in the decorator.

By default, cache files are pickled to save storage space unless a suffix is provided. The mode parameter allows specifying file modes for reading and writing, and the delete parameter controls whether the cache file is deleted after use.

Parameters:

  • ignore_params (List[str], optional) – List of parameter names to ignore when generating the cache key. Useful for excluding non-deterministic or irrelevant inputs, such as timestamps or large constant objects.

  • force_update (bool, optional) – Forces the cache to update, bypassing any existing cached results. If not provided, the function will check for a force_update argument in the decorated function call.

  • until_date (Optional[Any], optional) – Date until which the cache file is valid. If a date is provided, the time is set to the end of the day (23:59:59). If not specified, the function call arguments are checked.

  • until_datetime (Optional[Any], optional) – Datetime until which the cache file is valid. Time of day is set to maximum time (23:59:59) if not provided.

  • with_ttl (Union[timedelta, str, int, float, None], optional) – Time-to-live (TTL) for the cache file, starting from the time of caching. Can be specified as a timedelta, a numeric value (in seconds), or a string.

  • mode (Literal["w", "w+", "wb", "wb+", "r", "r+", "rb", "rb+"], optional) – File mode for opening the cache file. Defaults to “wb+” (write-binary with updates).

  • delete (bool, optional) – If True, deletes the cache file after it is closed. Defaults to False.

  • suffix (Optional[str], optional) – A file suffix (e.g., “.txt” or “.json”) for the cache file. Defaults to None. If not provided, files are pickled by default.

Returns:

A decorated function that caches its result in a temporary file.

Return type:

Callable[[Callable[Param, RetType]], Callable[Param, RetType]]

Example

>>> from datetime import date
>>> @cache_in_file(suffix='.txt')
>>> def expensive_computation(until_date=None):
>>>     # Perform some expensive computation
>>>     return 'Some large result'
>>>
>>> result = expensive_computation(until_date=date.today())

Notes

  • The cache key is based on the function arguments after excluding those in ignore_params.

  • If conflicting expiration parameters are provided (until_date, until_datetime, with_ttl), the one in the function call takes precedence.