fleche.caches ============= .. py:module:: fleche.caches Attributes ---------- .. autoapisummary:: fleche.caches.logger fleche.caches.DigestedIterable fleche.caches.DigestedDict Exceptions ---------- .. autoapisummary:: fleche.caches.Rejected Classes ------- .. autoapisummary:: fleche.caches.BaseCache fleche.caches.Cache fleche.caches.ReadOnlyCache fleche.caches.FilteredCache fleche.caches.RefreshingCache fleche.caches.CacheStack Module Contents --------------- .. py:data:: logger .. py:exception:: Rejected Bases: :py:obj:`Exception` Cache refused to cache the call for some reason or other. .. py:data:: DigestedIterable .. py:data:: DigestedDict .. py:class:: BaseCache Bases: :py:obj:`abc.ABC` Helper class that provides a standard way to create an ABC using inheritance. .. py:method:: save(call: fleche.call.Call) -> str :abstractmethod: .. py:method:: load(key: str, lazy: bool = False) -> fleche.call.Call load(key: str, lazy: bool = True) -> fleche.call.LazyCall .. py:method:: load_value(key: str) -> Any :abstractmethod: .. py:method:: evict(key: str | fleche.digest.Digest) -> None :abstractmethod: .. py:method:: contains(key: str) -> bool .. py:method:: transfer(other: BaseCache, pop: bool = False) -> None Transfer all calls from this cache to another cache. Existing calls in the target cache may be overwritten by the transferred calls. :param other: The destination cache. :param pop: If True, evict transferred keys from the source cache after moving. .. py:method:: push(cache: BaseCache) -> CacheStack .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest :abstractmethod: Find the shortest substring that is still an unambigious reference to the same call. .. warning:: This is a property of how many values there are in your storage! A key returned from this function may become ambigious in the future when more values are added. Do not rely on this function in your programs, it is provided as a convenience for users only! :param key: the key to shorten :type key: str or :class:`Digest` :returns: shortest key possible :rtype: :class:`Digest` :raises AmbiguousDigestError: if no shorter key is possible .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] .. py:method:: table() -> pandas.DataFrame Return a pandas DataFrame summarizing cached calls via query(). This implementation uses a fully-wildcard Call template to retrieve all calls through ``self.query`` and then flattens metadata keys into top-level columns for convenience. Arguments and results are elided. The DataFrame index will be the lookup key (digest) of each call. :returns: table of all calls on cache :rtype: :class:`pandas.DataFrame` .. py:method:: filter(predicate: Callable[[fleche.call.Call | fleche.call.LazyCall], bool] | fleche.call.Call) -> FilteredCache Create a read-only view of this cache that only exposes calls matching the predicate. :param predicate: A function that takes a Call or LazyCall and returns True if it should be included in the new cache, or a Call object to use as a template. :returns: A read-only view of the cache. :rtype: FilteredCache .. py:class:: Cache Bases: :py:obj:`BaseCache` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: values :type: fleche.storage.Storage .. py:attribute:: calls :type: fleche.storage.CallStorage .. py:attribute:: _calls :type: dataclasses.InitVar[fleche.storage.CallStorage | fleche.storage.Storage] .. py:method:: __post_init__(_calls) .. py:method:: load_value(key) .. py:method:: _handle_args_save(value) .. py:method:: _handle_args_load(key) .. py:method:: save(call: fleche.call.Call) -> str .. py:method:: _decode_call(call: fleche.call.Call, lazy: bool = False) -> fleche.call.Call _decode_call(call: fleche.call.Call, lazy: bool = True) -> fleche.call.LazyCall .. py:method:: load(key: str, lazy: bool = False) -> fleche.call.Call load(key: str, lazy: bool = True) -> fleche.call.LazyCall .. py:method:: contains(key: str) -> bool .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest Find the shortest substring that is still an unambigious reference to the same call. .. warning:: This is a property of how many values there are in your storage! A key returned from this function may become ambigious in the future when more values are added. Do not rely on this function in your programs, it is provided as a convenience for users only! :param key: the key to shorten :type key: str or :class:`Digest` :returns: shortest key possible :rtype: :class:`Digest` :raises AmbiguousDigestError: if no shorter key is possible .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] Query for cached calls that match a template and return decoded results. This delegates to the underlying :meth:`CallStorage.query` using the provided template ``call``. Any digested argument values and the result are decoded via this cache's value storage before yielding. :param call: A ``Call`` instance used as a template; fields set to ``None`` act as wildcards. For arguments and result, comparisons follow digest semantics (i.e., values are matched by their digest). :param lazy: If True, return LazyCall instances instead of Call instances. :Yields: *Call | LazyCall* -- Matching calls with arguments and result decoded from digests where possible. .. py:method:: evict(key: str | fleche.digest.Digest) -> None .. py:method:: redigest() -> None Ensures consistent cache keys in case digest function changed. This may take time depending on cache size. .. py:class:: ReadOnlyCache Bases: :py:obj:`BaseCache` A cache that can only be read from. .. py:attribute:: cache :type: BaseCache .. py:method:: save(call: fleche.call.Call) .. py:method:: load(key, lazy: bool = True) .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest Find the shortest substring that is still an unambigious reference to the same call. .. warning:: This is a property of how many values there are in your storage! A key returned from this function may become ambigious in the future when more values are added. Do not rely on this function in your programs, it is provided as a convenience for users only! :param key: the key to shorten :type key: str or :class:`Digest` :returns: shortest key possible :rtype: :class:`Digest` :raises AmbiguousDigestError: if no shorter key is possible .. py:method:: evict(key: str | fleche.digest.Digest) -> None .. py:method:: load_value(key) .. py:method:: contains(key: str) -> bool .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] Forward queries to the wrapped cache. :param call: A template ``Call`` where ``None`` fields act as wildcards. :param lazy: If True, return LazyCall instances. :Yields: *Call | LazyCall* -- Results yielded by the wrapped cache's ``query`` method. .. py:class:: FilteredCache Bases: :py:obj:`ReadOnlyCache` A read-only view of a cache that only exposes calls matching a predicate. .. py:attribute:: predicate :type: Callable[[fleche.call.Call | fleche.call.LazyCall], bool] .. py:method:: load(key, lazy: bool = True) .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] Forward queries to the wrapped cache. :param call: A template ``Call`` where ``None`` fields act as wildcards. :param lazy: If True, return LazyCall instances. :Yields: *Call | LazyCall* -- Results yielded by the wrapped cache's ``query`` method. .. py:class:: RefreshingCache Bases: :py:obj:`BaseCache` A cache that forces re-execution by always missing on load. It forwards saves and value loads to an underlying cache, allowing new results to be stored while ensuring that existing ones are ignored for the duration of its use. This is necessary to handle nested fleche calls during a rerun, otherwise forcing them to re-execute would be awkward. .. py:attribute:: cache :type: BaseCache .. py:method:: save(call: fleche.call.Call) -> str .. py:method:: load(key: str, lazy: bool = False) -> fleche.call.Call load(key: str, lazy: bool = True) -> fleche.call.LazyCall .. py:method:: load_value(key: str) -> Any .. py:method:: contains(key: str) -> bool .. py:method:: evict(key: str | fleche.digest.Digest) -> None .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest Find the shortest substring that is still an unambigious reference to the same call. .. warning:: This is a property of how many values there are in your storage! A key returned from this function may become ambigious in the future when more values are added. Do not rely on this function in your programs, it is provided as a convenience for users only! :param key: the key to shorten :type key: str or :class:`Digest` :returns: shortest key possible :rtype: :class:`Digest` :raises AmbiguousDigestError: if no shorter key is possible .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] .. py:class:: CacheStack Bases: :py:obj:`BaseCache` Represents a combination of caches. Saving will always hit the lowest level, while loading will traverse up. .. py:attribute:: stack :type: tuple[BaseCache, Ellipsis] .. py:method:: save(call: fleche.call.Call) .. py:method:: load(key, lazy: bool = True) .. py:method:: load_value(key) .. py:method:: contains(key: str) -> bool .. py:method:: push(cache: BaseCache) -> CacheStack .. py:method:: evict(key: str | fleche.digest.Digest) -> None .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest Find the shortest substring that is still an unambigious reference to the same call. .. warning:: This is a property of how many values there are in your storage! A key returned from this function may become ambigious in the future when more values are added. Do not rely on this function in your programs, it is provided as a convenience for users only! :param key: the key to shorten :type key: str or :class:`Digest` :returns: shortest key possible :rtype: :class:`Digest` :raises AmbiguousDigestError: if no shorter key is possible .. py:method:: query(call: fleche.call.Call, lazy: bool = False) -> Iterable[fleche.call.Call] query(call: fleche.call.Call, lazy: bool = True) -> Iterable[fleche.call.LazyCall] Aggregate query results across the stack, avoiding duplicates. The caches are queried from bottom to top. Results are deduplicated by their lookup key (via ``Call.to_lookup_key()``) and yielded in the order they are first seen. :param call: A template ``Call`` where ``None`` fields act as wildcards. :param lazy: If True, return LazyCall instances. :Yields: *Call | LazyCall* -- Matching calls from any cache in the stack, without duplicates.