fleche ====== .. py:module:: fleche .. autoapi-nested-parse:: lru_cache on 'roids. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/fleche/caches/index /autoapi/fleche/call/index /autoapi/fleche/config/index /autoapi/fleche/digest/index /autoapi/fleche/metadata/index /autoapi/fleche/query/index /autoapi/fleche/security/index /autoapi/fleche/state/index /autoapi/fleche/storage/index /autoapi/fleche/wrapper/index Attributes ---------- .. autoapisummary:: fleche.__version__ Classes ------- .. autoapisummary:: fleche.BoundWrapper fleche.Ignored fleche.Required Functions --------- .. autoapisummary:: fleche.cache fleche.meta fleche.tags fleche.project fleche.fleche fleche.D Package Contents ---------------- .. py:data:: __version__ :value: 'unknown' .. py:function:: cache(new_cache: None = None, stack: bool = False) -> fleche.caches.BaseCache cache(new_cache: fleche.caches.BaseCache | str, stack: bool = False) -> contextlib.AbstractContextManager[None] Manages the active cache for Fleche. If ``new_cache`` is ``None``, returns the currently active cache. Otherwise, immediately sets ``new_cache`` as the active cache and returns a context manager. When used in a ``with`` statement the previous cache is restored on exit; when the returned context manager is discarded the new cache remains active (sticky behaviour). :param new_cache: Cache object or named cache string to activate, or ``None`` to query. :param stack: If ``True``, wrap ``new_cache`` in a :class:`.CacheStack` on top of the current cache. :returns: The current :class:`.BaseCache` when called without arguments, otherwise a :class:`._StickyContext` context manager. .. py:function:: meta(*new_metadata: fleche.metadata.MetaData, stack=False) -> contextlib.AbstractContextManager[None] Manages the active metadata for Fleche. Immediately sets ``new_metadata`` as the active metadata and returns a context manager. When used in a ``with`` statement the previous metadata is restored on exit; when the returned context manager is discarded the new metadata remains active (sticky behaviour). :param \*new_metadata: :class:`.MetaData` instances to activate. :param stack: If ``True``, prepend the current metadata tuple before the new entries. :returns: A :class:`._StickyContext` context manager. .. py:function:: tags(**kwargs) A context manager to add arbitrary tags to results. :param \*\*kwargs: The tags to add to the results. .. py:function:: project(name) A context manager to tag results with a project name. :param name: The name of the project. :type name: str .. py:class:: BoundWrapper Utility class that freezes global state for the cache and metadata config. Essentially acts like an early binding closure. This is intended to enable passing around fleche-decorated functions in pickled form by baking in the state into the pickle on request. .. py:attribute:: func :type: Callable .. py:attribute:: cache :type: fleche.caches.BaseCache .. py:attribute:: meta :type: tuple[fleche.metadata.MetaData, Ellipsis] .. py:method:: bind(func) :classmethod: Bind cache and metadata state. Returns a new callable that will behave always as if run under the context under which :meth:`.bind()` was originally called. :param func: any callable; plain functions that only call fleche-wrapped ones are explicitly allowed :type func: callable :returns: instance with the bound cache and metadata state :rtype: :class:`.BoundWrapper` .. py:method:: __call__(*args, **kwargs) .. py:function:: fleche(_func=None, *, version: int | None = None, meta: tuple[fleche.metadata.MetaData, Ellipsis] = (), hash_version: bool = True, hash_module: bool = True, hash_code: bool = False, require: None | str | list[str] | tuple[str] = None, ignore: None | str | list[str] | tuple[str] = None, isolate: bool = False) Cache decorator for functions. The decorated function is enhanced with helper methods: - .call(*args, **kwargs): Get the :clas:`.Call` object. - .digest(*args, **kwargs): Get the cache key. - .load(*args, **kwargs): Load result from cache. - .contains(*args, **kwargs): Check if result is in cache. - .rerun(*args, **kwargs): Forces reevaluation recursively. The original function is available via .__wrapped__. .. warning:: ``isolate=True`` is **not thread-safe**. Internally it calls :func:`os.chdir`, which is a process-wide POSIX syscall shared by all threads. Concurrent calls with ``isolate=True`` from multiple threads will clobber each other's working directory, and a thread may find its temporary directory deleted before it has finished using it. Use ``isolate=True`` only from a single thread, or run isolated calls in separate processes (e.g. via :class:`concurrent.futures.ProcessPoolExecutor`) where each process has its own working directory. .. py:class:: Ignored Type wrapper to mark a function argument as ignored for caching. Can be used as a type hint: ``arg: fleche.Ignored`` or ``arg: fleche.Ignored[int]``. .. py:method:: __class_getitem__(item) :classmethod: .. py:class:: Required Type wrapper to mark a function argument as required for caching. Arguments marked as required must be explicitly provided by the caller as keyword arguments (i.e. not via their default value) for the result to be cached. This is useful for arguments like random seeds or iteration counts, where using the default value might lead to non-deterministic or otherwise undesirable caching behavior. This is mainly useful when wrapping third-party functions where you do not control the default arguments. Can be used as a type hint: ``arg: fleche.Required`` or ``arg: fleche.Required[int]``. .. py:method:: __class_getitem__(item) :classmethod: .. py:function:: D(value) -> digest.Digest Convenience wrapper to create a Digest from a value. If given a non-empty string that is a valid hexadecimal string of at most :data:`~fleche.digest.DIGEST_LENGTH` characters, wraps it in a :class:`~fleche.digest.Digest` directly (allowing short hex prefixes for use with :meth:`~fleche.digest.Digest.expand`). For any other value — including strings that are not valid hex digests — computes the digest. .. warning:: Passing an arbitrary string to ``D()`` will silently compute its digest rather than treating the string as a digest identifier. Only strings that consist entirely of hexadecimal characters (``0-9``, ``a-f``, ``A-F``) and are no longer than :data:`~fleche.digest.DIGEST_LENGTH` characters are used verbatim. If you intend to look up a cached value by its digest string, make sure the string you pass satisfies those constraints; otherwise you will get the digest *of* the string itself, which is almost certainly not what you want. Digests passed as arguments to @fleche decorated functions are automatically expanded to their cached values.