mcrotk-cache-utils 0.1.0__py3-none-any.whl

mcrotk_cache_utils/__init__.py

@@ -0,0 +1,36 @@
+"""Caching decorators for methods and functions, built on cachetools.
+
+Per-instance caches for methods, argument omission, passthrough (e.g. for RNGs), key converters, and
+key helpers for arrays, containers and pandas objects.
+"""
+
+from .copying.instance_copying import CacheCopyWarning, copy_instance
+from .decorators.cache_controls import CacheControls, cache_controls, clear_caches
+from .decorators.function_caching import cached_function
+from .decorators.method_caching import cached_method
+from .decorators.rng_caching import (
+    rng_omit_cached_function,
+    rng_omit_cached_method,
+    rng_passthrough_cached_function,
+    rng_passthrough_cached_method,
+)
+from .keys.converters import array_key, container_key, dataframe_key, index_key, series_key
+
+__all__ = [
+    "CacheControls",
+    "CacheCopyWarning",
+    "array_key",
+    "cache_controls",
+    "cached_function",
+    "cached_method",
+    "clear_caches",
+    "container_key",
+    "copy_instance",
+    "dataframe_key",
+    "index_key",
+    "rng_omit_cached_function",
+    "rng_omit_cached_method",
+    "rng_passthrough_cached_function",
+    "rng_passthrough_cached_method",
+    "series_key",
+]

mcrotk_cache_utils/copying/__init__.py

@@ -0,0 +1 @@
+"""Copying instances with cached methods: ``copy_instance``, and the copy handling ``cached_method`` installs."""

mcrotk_cache_utils/copying/copy_handling.py

@@ -0,0 +1,231 @@
+"""Copy handling for instances with cached methods: the ``__copy__``/``__deepcopy__`` ``cached_method`` installs.
+
+Python's default copy would duplicate the instance ``__dict__``, which holds our caches and
+cachetools' bound wrappers (bound to the original instance). The installed methods do the
+default copy (honoring ``__getstate__``, ``__reduce__``, ``__slots__``), but first drop the
+wrappers (recreated for the copy on first use) and empty or copy each cache according to its
+method's ``on_copy``.
+"""
+
+import copy
+import os
+import sys
+import warnings
+import weakref
+from collections.abc import Iterator, MutableMapping
+from typing import Any, Literal, NamedTuple
+
+import cachetools
+
+OnCopy = Literal["empty", "copy", "manual"]
+ON_COPY_VALUES = ("empty", "copy", "manual")
+
+CACHE_ATTR = "_mcrotk_cache_attr"  # on our descriptors: the name of the instance attribute holding the cache
+ON_COPY = "_mcrotk_on_copy"  # on our descriptors: (on_copy value, whether it was given explicitly)
+_OURS = "_mcrotk_copy"  # on the __copy__/__deepcopy__ functions we install
+
+_WRAPPERS = "__cachetools_cachedmethods"  # cachetools' per-instance wrappers for super() lookups
+
+
+class CacheCopyWarning(UserWarning):
+    """A class with cached methods defines its own ``__copy__`` or ``__deepcopy__``.
+
+    Then ``cached_method`` can't install its copy handling, and whether copies are correct
+    depends on that method (:func:`copy_instance` can do the copying inside it). Silence with
+    ``on_copy='manual'`` on the cached methods, or with
+    ``warnings.filterwarnings('ignore', category=CacheCopyWarning)``.
+    """
+
+
+class CachedMethodInfo(NamedTuple):
+    """A cached method found in a class, with what copying needs to know about it."""
+
+    name: str  # the method's name in its class (also the key of its cachetools wrapper in instances)
+    cache_attr: str
+    on_copy: str
+    explicit: bool
+
+
+def cached_methods(cls: type) -> Iterator[tuple[type, CachedMethodInfo]]:
+    """Our cached methods in ``cls`` and its bases, with the class each is defined in."""
+    for klass in cls.__mro__:
+        for name, value in vars(klass).items():
+            attr = getattr(value, CACHE_ATTR, None)
+            if isinstance(attr, str):
+                on_copy, explicit = getattr(value, ON_COPY, ("empty", False))
+                yield klass, CachedMethodInfo(name, attr, on_copy, explicit)
+
+
+# --- Installing at class creation ---
+
+
+class InstallsCopyMethods:
+    """Mixin for ``cached_method``'s descriptor: copy handling for the class, set up when the class is created."""
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        super().__set_name__(owner, name)  # pyright: ignore[reportAttributeAccessIssue]  (cachetools' descriptor)
+        on_copy, explicit = getattr(self, ON_COPY)
+        theirs = user_copy_methods(owner)
+        _check_on_copy(owner, name, on_copy, explicit, theirs)
+        if on_copy != "manual":
+            _install_copy_methods(owner, theirs)
+
+
+def _check_on_copy(owner: type, name: str, on_copy: str, explicit: bool, theirs: list[str]) -> None:
+    """Errors for an ``on_copy`` that conflicts with the class's own copy methods, or the warning for the default."""
+    where = f"{owner.__qualname__}.{name}"
+    if on_copy == "manual":
+        if "__copy__" not in theirs:
+            raise TypeError(
+                f"{where}: on_copy='manual', but {owner.__qualname__} has no __copy__ of its own, so copy.copy "
+                "would give the copy the original's cache and run its cached methods on the original. Define "
+                "__copy__, or use on_copy='empty' or 'copy'."
+            )
+    elif theirs and explicit:
+        raise TypeError(
+            f"{where}: on_copy={on_copy!r} can't take effect: {owner.__qualname__} defines its own "
+            f"{' and '.join(theirs)}. Use on_copy='manual' and handle the cache there."
+        )
+    elif theirs:
+        _warn_once(owner, theirs)
+
+
+def _install_copy_methods(owner: type, theirs: list[str]) -> None:
+    """Give ``owner`` our ``__copy__`` and ``__deepcopy__``, except where it has its own."""
+    for dunder, function in (("__copy__", _copy), ("__deepcopy__", _deepcopy)):
+        if dunder not in theirs and getattr(owner, dunder, None) is not function:
+            setattr(owner, dunder, function)
+
+
+def user_copy_methods(cls: type) -> list[str]:
+    """Which of ``__copy__``/``__deepcopy__`` ``cls`` gets from its own code (itself or a base), not from us."""
+    return [
+        dunder
+        for dunder in ("__copy__", "__deepcopy__")
+        if (method := getattr(cls, dunder, None)) is not None and not getattr(method, _OURS, False)
+    ]
+
+
+_checked: "weakref.WeakSet[type]" = weakref.WeakSet()
+_warned: "weakref.WeakSet[type]" = weakref.WeakSet()
+
+
+def check_copy_handling(cls: type) -> None:
+    """At an instance's first cache: warn (once per class) if ``cls`` replaced our copy methods.
+
+    Catches subclasses that define ``__copy__``/``__deepcopy__``, which class creation can't see.
+    """
+    if cls in _checked:
+        return
+    _checked.add(cls)
+    theirs = user_copy_methods(cls)
+    if theirs and any(info.on_copy != "manual" for _, info in cached_methods(cls)):
+        _warn_once(cls, theirs)
+
+
+def _warn_once(cls: type, theirs: list[str]) -> None:
+    """Give a :class:`CacheCopyWarning` for ``cls``, which defines its own ``theirs`` methods, once per class."""
+    if cls in _warned:
+        return
+    _warned.add(cls)
+    warnings.warn(
+        f"{cls.__qualname__} defines its own {' and '.join(theirs)}, so copies of its instances don't get "
+        "mcrotk_cache_utils' handling of its cached methods' caches. Make sure "
+        f"{'it doesn' if len(theirs) == 1 else 'they don'}'t give the copy the original's caches or the "
+        "cachetools wrappers in the instance __dict__ (bound to the original): copy_instance(self) makes "
+        "such a copy correctly. Then set on_copy='manual' on the cached methods to silence this warning.",
+        CacheCopyWarning,
+        stacklevel=_caller_outside_libraries(),
+    )
+
+
+_PACKAGE_DIR = os.path.dirname(os.path.dirname(__file__))  # mcrotk_cache_utils/, above copying/
+_SKIP_DIRS = (_PACKAGE_DIR + os.sep, os.path.dirname(cachetools.__file__) + os.sep)
+_SKIP_FILES = (getattr(sys.modules.get("abc"), "__file__", None) or "",)  # ABCMeta.__new__ runs __set_name__
+
+
+def _caller_outside_libraries() -> int:
+    """The stacklevel of the nearest frame outside this package (any of its folders), cachetools and abc."""
+    level, frame = 2, sys._getframe(2)  # 1: _warn_once; 2: its caller
+    while frame is not None and (
+        frame.f_code.co_filename.startswith(_SKIP_DIRS) or frame.f_code.co_filename in _SKIP_FILES
+    ):
+        level, frame = level + 1, frame.f_back
+    return level
+
+
+# --- The installed methods ---
+
+
+def _copy(self: Any) -> Any:
+    return copy_with_caches(self, None)
+
+
+def _deepcopy(self: Any, memo: dict[int, Any]) -> Any:
+    return copy_with_caches(self, memo)
+
+
+_copy.__name__ = _copy.__qualname__ = "__copy__"
+_deepcopy.__name__ = _deepcopy.__qualname__ = "__deepcopy__"
+_copy.__doc__ = "Shallow copy; cached methods' caches are emptied or copied according to their on_copy."
+_deepcopy.__doc__ = "Deep copy; cached methods' caches are emptied or deep-copied according to their on_copy."
+setattr(_copy, _OURS, True)
+setattr(_deepcopy, _OURS, True)
+
+
+def copy_with_caches(obj: Any, memo: dict[int, Any] | None, methods: list[CachedMethodInfo] | None = None) -> Any:
+    """Python's default copy (deep if ``memo`` is given), with the cache handling applied first."""
+    deep = memo is not None
+    if methods is None:
+        methods = [info for _, info in cached_methods(type(obj))]
+    rv = obj.__reduce_ex__(4)
+    if isinstance(rv, str):  # a global (copied by reference), as in copy.copy
+        return obj
+    func, args, state, *rest = rv
+    if isinstance(state, dict):
+        state, prepared = _prepare(state, methods, deep), True
+    elif isinstance(state, tuple) and len(state) == 2 and isinstance(state[0], dict):  # (__dict__, __slots__ values)
+        state, prepared = (_prepare(state[0], methods, deep), state[1]), True
+    else:
+        prepared = False  # a custom __getstate__/__reduce__ state: fix the copy's __dict__ afterwards
+    new = copy._reconstruct(obj, memo, func, args, state, *rest)  # pyright: ignore[reportAttributeAccessIssue]
+    if not prepared and isinstance(getattr(new, "__dict__", None), dict):
+        fixed = _prepare(new.__dict__, methods, deep)
+        new.__dict__.clear()
+        new.__dict__.update(fixed)
+    return new
+
+
+def _prepare(instance_dict: dict[str, Any], methods: list[CachedMethodInfo], deep: bool) -> dict[str, Any]:
+    """A copy of the instance's ``__dict__`` for the new instance: no wrappers; caches emptied or copied."""
+    result = dict(instance_dict)
+    result.pop(_WRAPPERS, None)
+    for info in methods:
+        if type(result.get(info.name)).__module__.startswith("cachetools"):
+            del result[info.name]  # cachetools' wrapper, bound to the original
+        if info.cache_attr not in result or info.on_copy == "manual":
+            continue
+        if info.on_copy == "empty":
+            del result[info.cache_attr]  # created again on first use
+        elif not deep:  # "copy", shallow (a deep copy copies the cache with the rest of the state)
+            result[info.cache_attr] = copy_cache(result[info.cache_attr])
+    return result
+
+
+def copy_cache(cache: MutableMapping) -> MutableMapping:
+    """A new cache with the same entries: the cached keys and results are shared, not copied.
+
+    cachetools' caches don't support ``copy.copy`` (the copy would share their internal
+    structures), so the cache is deep-copied with its keys and results kept as they are. This
+    keeps e.g. an LRUCache's order and a TTLCache's expiry times.
+    """
+    if type(cache) is dict:
+        return cache.copy()
+    keys = list(cache)
+    if isinstance(cache, cachetools.Cache):
+        # Read the values without "using" them: LRUCache.__getitem__ would change the original's order.
+        values = [cachetools.Cache.__getitem__(cache, key) for key in keys]
+    else:
+        values = [cache[key] for key in keys]
+    memo: dict[int, Any] = {id(obj): obj for obj in (*keys, *values)}
+    return copy.deepcopy(cache, memo)

mcrotk_cache_utils/copying/instance_copying.py

@@ -0,0 +1,54 @@
+"""Copying an instance with cached methods, choosing what the copy gets in their caches.
+
+The machinery (the ``__copy__``/``__deepcopy__`` that ``cached_method`` installs, and their checks)
+is in ``copy_handling``; ``CacheCopyWarning`` is defined there, where it's given.
+"""
+
+from typing import Any, Literal, TypeVar
+
+from .copy_handling import CacheCopyWarning, cached_methods, copy_with_caches
+
+__all__ = ["CacheCopyWarning", "copy_instance"]
+
+T = TypeVar("T")
+
+
+def copy_instance(
+    obj: T,
+    caches: Literal["empty", "copy"] | None = None,
+    *,
+    deep: bool = False,
+    memo: dict[int, Any] | None = None,
+) -> T:
+    """Copy an instance with cached methods, choosing what the copy gets in their caches.
+
+    Makes the same copy as ``copy.copy(obj)`` (or ``copy.deepcopy(obj)`` with ``deep=True``)
+    does with the copy methods ``cached_method`` installs, but never calls the class's own
+    ``__copy__``/``__deepcopy__``, so it can be used inside them::
+
+        @cached_method(on_copy="manual")
+        def simulate(self, n): ...
+
+        def __copy__(self):
+            new = copy_instance(self)
+            ...  # anything else your copy needs
+            return new
+
+    Args:
+        obj: The instance to copy.
+        caches: ``'empty'`` or ``'copy'`` for every cached method's cache in the copy (see
+            ``on_copy`` in :func:`cached_method`), or ``None`` (default) to follow each method's
+            ``on_copy``, with ``'manual'`` methods' caches emptied.
+        deep: Make a deep copy.
+        memo: Inside your own ``__deepcopy__(self, memo)``, pass its ``memo`` (implies ``deep``),
+            so references shared with other parts of the object being copied stay shared.
+    """
+    if caches not in (None, "empty", "copy"):
+        raise ValueError(f"copy_instance: caches must be 'empty', 'copy' or None, got {caches!r}")
+    if memo is None and deep:
+        memo = {}
+    methods = [
+        info._replace(on_copy=caches or ("empty" if info.on_copy == "manual" else info.on_copy))
+        for _, info in cached_methods(type(obj))
+    ]
+    return copy_with_caches(obj, memo, methods)

mcrotk_cache_utils/decorators/__init__.py

@@ -0,0 +1 @@
+"""The decorators, and ``cache_controls``/``clear_caches`` for what they return."""

mcrotk_cache_utils/decorators/cache_controls.py

@@ -0,0 +1,82 @@
+"""Working with the caches of cached functions and methods: ``cache_controls`` and ``clear_caches``.
+
+``cache_controls`` gives typed access to a cached function's or method's cache attributes
+(``cache_clear``, ``cache_info``, ...).
+
+The decorators keep the decorated function's own type, so type checkers see a plain function and
+don't know about the attributes cachetools adds. ``cache_controls`` gives them a type.
+"""
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from cachetools import CacheInfo
+
+from ..copying.copy_handling import CACHE_ATTR
+
+
+class CacheControls(Protocol):
+    """The cache attributes of a cached function, or of a cached method on an instance."""
+
+    @property
+    def cache(self) -> Any:
+        """The cache itself (what ``cache_factory`` made)."""
+        ...
+
+    @property
+    def cache_key(self) -> Callable[..., Any]: ...
+    @property
+    def cache_lock(self) -> Any: ...
+    @property
+    def cache_condition(self) -> Any: ...
+    def cache_clear(self) -> None:
+        """Empty the cache (and reset the ``info`` counters)."""
+        ...
+
+    def cache_info(self) -> CacheInfo:
+        """Hit and miss counts. Only with ``info=True``: otherwise an ``AttributeError``."""
+        ...
+
+
+def cache_controls(cached: Callable[..., Any]) -> CacheControls:
+    """The cache attributes of ``cached``, typed for type checkers.
+
+    ``cached`` is a function decorated with ``cached_function`` (including a static or class
+    method, accessed as ``Class.method``), or a method decorated with ``cached_method`` accessed
+    on an instance (``obj.method``)::
+
+        cache_controls(fit).cache_clear()
+        cache_controls(model.fit).cache_info()
+
+    The attributes are the same as ``fit.cache_clear()`` etc., which also work at runtime but
+    which type checkers report as unknown. To empty an instance's caches, :func:`clear_caches`
+    also works.
+    """
+    if not callable(getattr(cached, "cache_clear", None)):
+        hint = (
+            " (pass a cached method accessed on an instance, obj.method, not on the class)"
+            if type(cached).__module__.startswith("cachetools")  # cachedmethod's class-level object
+            else ""
+        )
+        raise TypeError(f"cache_controls: {cached!r} is not a cached function or method{hint}")
+    return cached  # type: ignore[return-value]  # cachetools' wrapper (or a method bound to one) has these attributes
+
+
+def clear_caches(obj: Any, *methods: str) -> None:
+    """Empty ``obj``'s caches for the named cached methods, or for all of them if none are named.
+
+    Only caches made by this library's decorators are touched. Use after changing an
+    attribute that affects cached results, e.g. in a copy made with ``on_copy='copy'``.
+    """
+    found = set()
+    for cls in type(obj).__mro__:
+        for name, value in vars(cls).items():
+            attr = getattr(value, CACHE_ATTR, None)
+            if not isinstance(attr, str) or (methods and name not in methods):
+                continue
+            found.add(name)
+            if attr in getattr(obj, "__dict__", {}):
+                value.__get__(obj, cls).cache_clear()  # through cachetools, so locks and info counters are handled
+    unknown = set(methods) - found
+    if unknown:
+        raise ValueError(f"{type(obj).__name__} has no cached method(s) named {sorted(unknown)}")

mcrotk_cache_utils/decorators/function_caching.py

@@ -0,0 +1,94 @@
+"""Caching decorators for functions, including static and class methods, with one cache per function."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, MutableMapping
+from typing import TYPE_CHECKING, Any, TypeVar, overload
+
+import cachetools
+
+from ..keys.cache_keys import ArgRef, ArgSpec, Passthrough
+from ..keys.passthrough import make_view
+from .support.decorator_options import FunctionOptions
+from .support.placement_checks import FunctionNotInClassBody, add_check, reject_static_or_class_method
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+F = TypeVar("F", bound=Callable[..., Any])  # the decorated function: its type is kept as it is
+
+
+@overload
+def cached_function(func: F, /, **options: Unpack[FunctionOptions]) -> F: ...
+@overload
+def cached_function(func: None = None, /, **options: Unpack[FunctionOptions]) -> Callable[[F], F]: ...
+def cached_function(
+    func: Callable[..., Any] | None = None,
+    /,
+    *,
+    cache_factory: Callable[[], MutableMapping] = dict,
+    omit: ArgRef | Iterable[ArgRef] = (),
+    passthrough: Mapping[ArgRef, int | Passthrough] | None = None,
+    key_converters: Mapping[ArgRef, Callable[[Any], Any]] | None = None,
+    lock: Any = None,
+    condition: Any = None,
+    info: bool = False,
+) -> Any:
+    """Cache a function's results.
+
+    Use as ``@cached_function`` or ``@cached_function(...)``. Built on
+    :func:`cachetools.cached`, which does the calling, locking and statistics. The options are
+    the same as for :func:`cached_method`, except that ``lock`` and ``condition`` are objects
+    rather than functions of ``self``.
+
+    **The cache.** One per function, made by ``cache_factory`` when the decorator is applied,
+    and available as ``cache_controls(f).cache``. It lives as long as the function does,
+    usually the whole program, so with the default (an unbounded ``dict``) it keeps every
+    result until ``cache_controls(f).cache_clear()`` is called. Pass e.g.
+    ``cache_factory=lambda: cachetools.LRUCache(maxsize=128)`` to bound it.
+
+    **The key.** Built from the call's arguments bound to the signature with defaults filled
+    in, so ``f(1)``, ``f(x=1)`` and ``f()`` with default ``x=1`` are the same call. Unhashable
+    arrays and containers are converted as for :func:`cached_method`. Positions in the options
+    count the parameters as in the ``def`` line, from 0.
+
+    **Types.** Type checkers see the decorated function's own type (its signature and return
+    type). The cache attributes cachetools adds (``f.cache_clear()``, ...) work, but aren't part
+    of that type: :func:`cache_controls` gives typed access to them.
+
+    **Static and class methods.** Put ``@staticmethod`` or ``@classmethod`` above this decorator.
+    For a class method, ``cls`` is part of the key, so subclasses get their own entries (in one
+    shared cache); ``omit=['cls']`` makes them share results. For ordinary methods use
+    :func:`cached_method`: using this decorator directly in a class body is an error.
+
+    Args:
+        cache_factory: Makes the cache. Default ``dict`` (unbounded).
+        omit, passthrough, key_converters: As for :func:`cached_method`.
+        lock, condition, info: Passed to :func:`cachetools.cached`. A ``dict`` cache is safe
+            to use from several threads without a lock (at worst two threads compute the same
+            result); cachetools' caches (``LRUCache`` etc.) are not, so pass e.g.
+            ``lock=threading.Lock()`` with them. ``condition`` also stops two threads from
+            computing the same result. With ``info=True``, ``cache_controls(f).cache_info()``
+            gives hit and miss counts.
+
+    Caveats:
+        - Results are returned as stored, not copied: changing a returned object in place
+          changes the cached result.
+        - Each process has its own cache: worker processes (e.g. in a ``ProcessPoolExecutor``)
+          start with empty caches, and their results don't reach the parent's cache.
+    """
+
+    def decorate(func: Callable[..., Any]) -> Any:
+        """Wrap ``func`` with cachetools, with its key spec and its one cache."""
+        reject_static_or_class_method(
+            func, "cached_function", "Put @staticmethod/@classmethod above @cached_function instead."
+        )
+        spec = ArgSpec(func, has_self=False, omit=omit, passthrough=passthrough, key_converters=key_converters)
+        cache = cache_factory()
+        if spec.passthrough:
+            cache = make_view(cache, spec.qualname)
+        wrapper = cachetools.cached(cache, key=spec.make_key, lock=lock, condition=condition, info=info)(func)
+        add_check(wrapper, FunctionNotInClassBody)
+        return wrapper
+
+    return decorate if func is None else decorate(func)