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/executor/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.wrap_executor 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 A plain callable that freezes cache and metadata state at construction time. :class:`.BoundWrapper` is intentionally a minimal wrapper: it captures the active :class:`.BaseCache` and metadata tuple and restores them around every call to the wrapped function, but it does **not** expose the ``fleche`` helper namespace (``digest``, ``call``, ``load``, ``contains``, ``query``, ``rerun``). Those helpers are available on the original decorated function. This is intended to enable passing around fleche-decorated functions in pickled form by baking the active state into the object. .. 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 plain callable that always executes as if called under the context in which :meth:`.bind()` was originally invoked. The returned object is a :class:`.BoundWrapper` — a simple dataclass with a ``__call__`` method — and does **not** carry the ``fleche`` helper namespace. To access helpers such as ``digest`` or ``query``, use them on the original decorated function. :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, accessible either directly on the wrapped function or bundled under a ``.fleche`` :class:`types.SimpleNamespace` (e.g. ``f.fleche.call(...)`` is equivalent to ``f.call(...)``): - .call(*args, **kwargs): Get the :class:`.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. - .query(*args, **kwargs): Return matching calls from the active cache. - .rerun(*args, **kwargs): Forces reevaluation recursively. - .bind(*args, **kwargs): Create a :class:`.BoundWrapper` that freezes the current cache/metadata state. Optionally pre-applies *args*/*kwargs* via :func:`functools.partial`. 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:: wrap_executor(executor) Monkey-patch ``executor.submit`` to intercept fleche-wrapped functions. Calling :func:`wrap_executor` on an executor that is already wrapped is a no-op: the patch is not stacked, and the original ``submit`` continues to refer to the pre-wrap method. :param executor: any object with a ``submit(func, *args, **kwargs)`` method (e.g. :class:`concurrent.futures.Executor` subclass instances). :returns: The same ``executor`` instance, with a replaced ``submit`` attribute. .. 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.