dotenvmodel 0.6.0__tar.gz → 0.6.2__tar.gz

dotenvmodel-0.6.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.6.2"
+}

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.2](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.6.1...v0.6.2) (2026-07-28)
+
+
+### Bug Fixes
+
+* warn on cached() argument disagreement, not on non-default args ([#54](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/54)) ([ba80777](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/ba80777e7486797d8a33d27b124b069f90664de6))
+
+## [0.6.1](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.6.0...v0.6.1) (2026-07-27)
+
+
+### Bug Fixes
+
+* eliminate cross-class reentrancy deadlock in cached() locking ([#52](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/52)) ([592297a](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/592297a1823b2c26b00f974882834e5ace8bc968))
+
 ## [0.6.0](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.5.4...v0.6.0) (2026-07-27)
 
 

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.6.0
+Version: 0.6.2
 Summary: Type-safe environment configuration with automatic .env file loading
 Project-URL: Homepage, https://github.com/AZX-PBC-OSS/dotenvmodel
 Project-URL: Repository, https://github.com/AZX-PBC-OSS/dotenvmodel

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/docs/api-reference/caching.md

@@ -3,3 +3,5 @@
 Cached singleton-instance machinery for DotEnvConfig subclasses.
 
 ::: dotenvmodel.caching
+    options:
+      members: []

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/docs/guides/loading.md

@@ -228,7 +228,11 @@ Calling `.reload()` on the cached instance mutates it in place; since `cached()`
 
 !!! warning "Reentrant `cached()` calls raise `RuntimeError`"
 
-    Calling `cached()` reentrantly for the same class from within that class's own `load()` / `post_load()` / field `validator` hooks raises `RuntimeError` instead of deadlocking. This prevents a self-deadlock that would otherwise occur because the internal lock is not reentrant. If a hook needs the config instance mid-load, call `cls.load()` directly or use `self`.
+    Calling `cached()` reentrantly for the same class from within that class's own `load()` / `post_load()` / field `validator` hooks raises `RuntimeError`. The internal lock is reentrant, so the nested call would not deadlock — it would see a cold cache and recurse into `load()` without bound, which is why it is rejected. If a hook needs the config instance mid-load, use `self`, or call `cls.load()` directly with re-entry guarding (an unconditional `cls.load()` inside `post_load()` re-runs the hooks and recurses until `RecursionError`).
+
+    Calling `cached()`, `reset_cached()`, or `cached_override()` for **other** classes from those hooks is supported — for example, one class's `post_load()` may call `cached()` on another config class. However, calling `reset_cached()` or entering `cached_override()` for the **same** class whose first load is still in flight raises `RuntimeError` (the load installs its instance when it completes, which would silently undo the reset or discard the override). A circular cross-class hook chain (A's hook loads B, B's hook loads A) collapses back onto the first class and likewise raises `RuntimeError`.
+
+    Hooks must not block on another thread (e.g. `thread.join()`) that touches the cache: the internal lock is held for the duration of a load, so the joining thread would hold the lock while the joined thread waits for it — a deadlock the reentrant lock cannot prevent.
 
 ### Scoped Overrides for Tests
 

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/dotenvmodel/__init__.py

@@ -37,7 +37,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.6.0"  # x-release-please-version
+__version__ = "0.6.2"  # x-release-please-version
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"

dotenvmodel-0.6.2/dotenvmodel/caching.py

@@ -0,0 +1,278 @@
+"""Cached singleton-instance machinery for DotEnvConfig subclasses.
+
+Provides the internal implementation behind ``DotEnvConfig.cached()``,
+``DotEnvConfig.reset_cached()``, and ``DotEnvConfig.cached_override()``.
+The public API lives on ``DotEnvConfig`` itself as thin classmethod wrappers
+that preserve concrete-subclass typing (``Self``); this module operates on
+plain ``type[DotEnvConfig]`` / ``DotEnvConfig`` and is not part of the
+package's public API.
+
+The cached instance is stored as a private class attribute
+(``_cached_instance``) on each config subclass's own ``__dict__`` rather than
+in a module-level registry.  This ties the cache lifetime to the class object:
+when nothing else references the class, both the class and its cached instance
+become collectible together.
+
+Thread safety:
+    A module-level ``threading.RLock`` guards the double-checked-locking
+    initialization path and the save/restore operations in
+    ``begin_override`` / ``end_override``. A reentrant lock (not a plain
+    ``Lock``) is required because the lock is held across ``cls.load()``:
+    ``post_load()`` and field ``validator`` hooks may legitimately touch
+    the cache for *other* classes, and a non-reentrant lock would
+    self-deadlock that thread. With a single module-level lock no
+    cross-thread circular wait is possible — only one thread holds the
+    lock and the holder always proceeds — so same-thread nesting is the
+    only reentrancy case, and the RLock permits it.
+
+    Same-class operations from within that class's own in-flight load
+    remain invalid: ``cached()`` cannot return an instance that does not
+    exist yet (the nested call would see a cold cache and recurse into
+    ``load()`` without bound), and ``reset_cached()`` /
+    ``cached_override()`` would be silently overwritten when the
+    in-flight load installs its instance. A ``threading.local`` set
+    tracks classes currently loading on each thread; all three entry
+    points raise ``RuntimeError`` in that case. A circular cross-class
+    chain (A's hook loads B, B's hook loads A) collapses back onto the
+    first class and is likewise reported as a same-class
+    ``RuntimeError``.
+
+    One residual hazard sits outside this design: the lock is held for
+    the duration of a load, so a hook must not block on another thread
+    (e.g. ``thread.join()``) that touches the cache — the joining thread
+    holds the lock while the joined thread waits for it, deadlocking
+    both.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, cast
+
+from dotenvmodel._constants import LOGGER_NAME
+
+if TYPE_CHECKING:
+    from dotenvmodel.config import DotEnvConfig
+
+logger = logging.getLogger(LOGGER_NAME)
+
+_CACHED_ATTR = "_cached_instance"
+_cache_lock = threading.RLock()
+_loading_local = threading.local()
+
+
+def _get_loading_set() -> set[type[DotEnvConfig]]:
+    """Get or create this thread's set of classes currently loading via ``cached()``.
+
+    Used to reject same-class cache operations issued from within that
+    class's own in-flight load (see the module docstring's "Thread safety"
+    section). Each thread gets its own independent set, so only same-thread
+    reentrancy is detected (the only possible nesting case with a single
+    module-level reentrant lock). Cross-thread contention is handled by
+    ``_cache_lock``.
+    """
+    loading = cast("set[type[DotEnvConfig]] | None", getattr(_loading_local, "loading", None))
+    if loading is None:
+        loading = set()
+        _loading_local.__dict__["loading"] = loading
+    return loading
+
+
+def get_cached(cls: type[DotEnvConfig]) -> DotEnvConfig | None:
+    """Return the cached instance stored in *cls*'s own ``__dict__``, or ``None``.
+
+    Reads ``cls.__dict__`` (not ``getattr``) so that only an entry set
+    directly on *cls* — not one inherited from a parent class via the MRO —
+    is considered a cache hit.
+    """
+    return cls.__dict__.get(_CACHED_ATTR)
+
+
+def has_cached(cls: type[DotEnvConfig]) -> bool:
+    """Return ``True`` if *cls* has its own ``_cached_instance`` entry in ``__dict__``."""
+    return _CACHED_ATTR in cls.__dict__
+
+
+def set_cached(cls: type[DotEnvConfig], instance: DotEnvConfig) -> None:
+    """Store *instance* as the cached singleton on *cls*.
+
+    This is an unlocked primitive — callers are responsible for acquiring
+    ``_cache_lock`` when thread-safety is required.
+    """
+    setattr(cls, _CACHED_ATTR, instance)
+
+
+def clear_cached(cls: type[DotEnvConfig]) -> None:
+    """Remove *cls*'s own cached instance entry if one exists.
+
+    Safe to call when no entry is present (no-op). Acquires ``_cache_lock``
+    internally.
+
+    Raises:
+        RuntimeError: If called for *cls* from within that class's own
+            in-flight load (``load()`` / ``post_load()`` / field
+            ``validator`` on this thread): the load installs its instance
+            when it completes, which would silently undo this reset.
+            Cross-class calls (e.g. one class's hook resetting another
+            class) are permitted.
+    """
+    if cls in _get_loading_set():
+        raise RuntimeError(
+            f"reset_cached() called for {cls.__name__} from within that "
+            f"class's own in-flight load (load() / post_load() / "
+            f"validator): the load installs its instance when it "
+            f"completes, which would silently undo this reset. Call "
+            f"reset_cached() after the load finishes instead."
+        )
+    with _cache_lock:
+        if has_cached(cls):
+            delattr(cls, _CACHED_ATTR)
+
+
+def acquire_cached(
+    cls: type[DotEnvConfig],
+    env: str | None,
+    override: bool,
+    env_dir: Path | None,
+) -> DotEnvConfig:
+    """Return the cached instance for *cls*, loading on first call.
+
+    Implements double-checked locking: a lock-free fast path checks
+    ``cls.__dict__``; if the cache is warm, the existing instance is returned
+    immediately (with a warning if arguments that disagree with the ones
+    that populated the cache are passed). If the cache is cold, a module-level lock is
+    acquired and the check is repeated before calling ``cls.load()``.
+
+    Reentrant calls for the same class from within that class's own
+    ``load()`` / ``post_load()`` / field ``validator`` hooks are detected
+    via a thread-local loading set and raise ``RuntimeError``: the internal
+    lock is reentrant, so the nested call would not deadlock — it would see
+    a cold cache and recurse into ``load()`` without bound. Nested calls
+    for *other* classes from those hooks proceed normally.
+
+    Args:
+        cls: The config class to cache for.
+        env: Environment name (only used on first call).
+        override: Whether .env files override env vars (only used on first call).
+        env_dir: Custom .env directory (only used on first call).
+
+    Returns:
+        The cached ``DotEnvConfig`` instance.
+
+    Raises:
+        RuntimeError: If ``cached()`` is called reentrantly for *cls* from
+            within that class's own load path (including via a circular
+            cross-class hook chain that collapses back onto *cls*).
+    """
+    cached = get_cached(cls)
+    if cached is not None:
+        # Warn on DISAGREEMENT, not on non-default arguments. An application accessor that
+        # consistently passes the same non-default arguments (e.g. `override=False`) on every
+        # call is asking for exactly what it already got, and warning it every time would train
+        # readers to filter the message out. A caller passing something the cache was NOT built
+        # with is the real bug this catches, and it still fires.
+        #
+        # Compared against the INSTANCE's own record of how it was loaded — the same fields
+        # `reload()` reuses — rather than a second copy kept beside the cache. One source of
+        # truth, and self-correcting: `reload(env="prod")` updates them, so a later `cached()`
+        # is judged against what the cached object actually holds now, not against whatever
+        # populated it originally.
+        loaded = cached.loaded_with()
+        if (env, override, env_dir) != loaded:
+            logger.warning(
+                "cached() called on %s with arguments (env=%r, override=%r, "
+                "env_dir=%r) but the cache is already populated with "
+                "(env=%r, override=%r, env_dir=%r); arguments were ignored.",
+                cls.__name__,
+                env,
+                override,
+                env_dir,
+                *loaded,
+            )
+        return cached
+
+    loading = _get_loading_set()
+    if cls in loading:
+        raise RuntimeError(
+            f"Reentrant cached() call detected for {cls.__name__}: "
+            f"cached() was called for this class while its first "
+            f"cached() call is still loading (inside load() / "
+            f"post_load() / validator). The instance cannot exist until "
+            f"that first load completes, and the internal lock is "
+            f"reentrant, so the nested call would recurse into load() "
+            f"without bound. If a hook needs the instance mid-load, call "
+            f"cls.load() directly or use 'self' instead."
+        )
+
+    try:
+        # add() lives inside the try so a (vanishingly unlikely) async
+        # exception between add and try-entry cannot strand cls in this
+        # thread's loading set; discard() on a never-added class is a no-op.
+        loading.add(cls)
+        with _cache_lock:
+            cached = get_cached(cls)
+            if cached is not None:
+                return cached
+
+            instance = cls.load(env=env, override=override, env_dir=env_dir)
+            set_cached(cls, instance)
+            return instance
+    finally:
+        loading.discard(cls)
+
+
+def begin_override(
+    cls: type[DotEnvConfig],
+    instance: DotEnvConfig,
+) -> tuple[bool, DotEnvConfig | None]:
+    """Save the current cached state on *cls* and install *instance* as the override.
+
+    Returns ``(had_cached, previous)`` so the caller can restore the exact
+    pre-override state via :func:`end_override`. Acquires ``_cache_lock``
+    internally.
+
+    Raises:
+        RuntimeError: If called for *cls* from within that class's own
+            in-flight load (``load()`` / ``post_load()`` / field
+            ``validator`` on this thread): the load installs its instance
+            when it completes, which would silently discard the override.
+            Cross-class calls (e.g. one class's hook overriding another
+            class) are permitted.
+    """
+    if cls in _get_loading_set():
+        raise RuntimeError(
+            f"cached_override() entered for {cls.__name__} from within "
+            f"that class's own in-flight load (load() / post_load() / "
+            f"validator): the load installs its instance when it "
+            f"completes, which would silently discard the override. "
+            f"Enter the override after the load finishes instead."
+        )
+    with _cache_lock:
+        had_cached = has_cached(cls)
+        previous = get_cached(cls)
+        set_cached(cls, instance)
+    return had_cached, previous
+
+
+def end_override(
+    cls: type[DotEnvConfig],
+    had_cached: bool,
+    previous: DotEnvConfig | None,
+) -> None:
+    """Restore the cached state saved by :func:`begin_override`.
+
+    If *had_cached* is ``True``, *previous* is restored. If *had_cached* is
+    ``False`` and *cls* now has its own entry (e.g. a concurrent ``cached()``
+    call set one), the entry is removed. Acquires ``_cache_lock`` internally.
+
+    No same-class loading guard here by design: via ``cached_override()`` this
+    only runs after a successful :func:`begin_override`, which already
+    rejected entry while *cls* was loading on this thread.
+    """
+    with _cache_lock:
+        if had_cached:
+            set_cached(cls, cast("DotEnvConfig", previous))
+        elif has_cached(cls):
+            delattr(cls, _CACHED_ATTR)

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/dotenvmodel/config.py

@@ -303,7 +303,13 @@ class DotEnvConfig(metaclass=ConfigMeta):
     _load_env: str | None = None  # Store the env used during load
     _load_override: bool = True  # Store the override flag used during load
     _load_env_dir: Path | None = None  # Store the env_dir used during load
-    _cached_instance: ClassVar["DotEnvConfig | None"] = None
+    # Bare annotation only — no assignment. An actual `= None` here would
+    # place a real entry in DotEnvConfig.__dict__, making has_cached() treat
+    # the base class as already-cached and letting reset_cached() delete the
+    # class-body default (an irreversible process-wide mutation). The
+    # annotation alone gives type checkers the declaration without a runtime
+    # entry; per-subclass entries are set by the caching module.
+    _cached_instance: ClassVar["DotEnvConfig | None"]
     env_prefix: str = ""  # Class-level prefix for environment variables (default: no prefix)
     strip_strings: bool = False  # Class-level default for stripping string values
 
@@ -561,6 +567,20 @@ class DotEnvConfig(metaclass=ConfigMeta):
         instance._load_env_dir = env_dir
         return instance
 
+    def loaded_with(self) -> tuple[str | None, bool, Path | None]:
+        """The ``(env, override, env_dir)`` this instance was last loaded with.
+
+        `reload()` uses it to repeat a load without restating its arguments — so a SIGHUP
+        handler calling `reload()` with no arguments keeps the original precedence rather than
+        silently reverting to `override=True`. `cached()`'s warm path uses it to tell a caller
+        who agrees with how the cache was built from one who disagrees.
+
+        Exposed rather than read field-by-field so there is one definition of "how was this
+        loaded", and callers outside this class do not reach into three private attributes.
+        Values reflect the most recent `reload()`, not only the original `load()`.
+        """
+        return (self._load_env, self._load_override, self._load_env_dir)
+
     def reload(
         self,
         env: str | None = None,
@@ -622,9 +642,10 @@ class DotEnvConfig(metaclass=ConfigMeta):
         """
         logger.info(f"Reloading {self.__class__.__name__} configuration")
 
-        reload_env = env if env is not None else self._load_env
-        reload_override = override if override is not None else self._load_override
-        reload_env_dir = env_dir if env_dir is not None else self._load_env_dir
+        loaded_env, loaded_override, loaded_env_dir = self.loaded_with()
+        reload_env = env if env is not None else loaded_env
+        reload_override = override if override is not None else loaded_override
+        reload_env_dir = env_dir if env_dir is not None else loaded_env_dir
 
         load_env_files(env=reload_env, override=reload_override, env_dir=reload_env_dir)
 
@@ -703,8 +724,8 @@ class DotEnvConfig(metaclass=ConfigMeta):
         calls `load()`, the rest block and receive the same instance. Subsequent
         calls (from any thread) return the cached instance immediately without
         re-reading the environment, ignoring any arguments passed after the first
-        call (a warning is logged if non-default arguments are passed against an
-        already-warm cache).
+        call (a warning is logged if arguments that disagree with the ones
+        that populated the cache are passed against an already-warm cache).
 
         The cached instance is stored as a private class attribute on the config
         class itself (not in a module-level registry), so its lifetime is tied
@@ -735,7 +756,9 @@ class DotEnvConfig(metaclass=ConfigMeta):
             - When you need multiple instances with different parameters
             - From within a `post_load()` hook or field `validator` on the same
               class: a reentrant `cached()` call for the same class while its
-              first load is still in flight raises `RuntimeError` (see below)
+              first load is still in flight raises `RuntimeError` (see below).
+              Calling `cached()` for *other* classes from those hooks is
+              supported.
 
         Args:
             env: Environment name (e.g., "dev", "prod", "test"). If None, reads
@@ -765,9 +788,17 @@ class DotEnvConfig(metaclass=ConfigMeta):
                 simultaneously (only on first call)
             RuntimeError: If `cached()` is called reentrantly for the same
                 class from within that class's own `load()` / `post_load()` /
-                field `validator` hooks. This would otherwise deadlock on the
-                non-reentrant internal lock. Hooks that need the instance
-                mid-load should call `cls.load()` directly or use `self`.
+                field `validator` hooks. The internal lock is reentrant, so
+                the nested call would not deadlock — it would see a cold
+                cache and recurse into `load()` without bound; it is rejected
+                instead. A circular cross-class hook chain (A's hook loads B,
+                B's hook loads A) collapses back onto the first class and
+                raises the same `RuntimeError`. Calling `cached()` for other
+                classes from hooks is supported. Hooks that need the instance
+                mid-load should use `self`, or call `cls.load()` directly with
+                re-entry guarding (an unconditional `cls.load()` inside
+                `post_load()` re-runs the hooks and recurses until
+                `RecursionError`).
 
         Example:
             ```python
@@ -811,6 +842,13 @@ class DotEnvConfig(metaclass=ConfigMeta):
             - After changing environment variables to force `cached()` to
               re-read the environment
 
+        Raises:
+            RuntimeError: If called for this class from within that same
+                class's own in-flight `load()` / `post_load()` / field
+                `validator` hook: the load installs its instance when it
+                completes, which would silently undo the reset. Calling
+                `reset_cached()` for *other* classes from hooks is fine.
+
         Example:
             ```python
             @pytest.fixture(autouse=True)
@@ -855,6 +893,13 @@ class DotEnvConfig(metaclass=ConfigMeta):
         Yields:
             `instance`, unchanged, for convenience in a `with ... as` binding.
 
+        Raises:
+            RuntimeError: If entered for this class from within that same
+                class's own in-flight `load()` / `post_load()` / field
+                `validator` hook: the load installs its instance when it
+                completes, which would silently discard the override. Calling
+                `cached_override()` for *other* classes from hooks is fine.
+
         Example:
             ```python
             test_config = AppConfig.load_from_dict({"PORT": "9000"})

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dotenvmodel"
-version = "0.6.0"
+version = "0.6.2"
 description = "Type-safe environment configuration with automatic .env file loading"
 readme = "README.md"
 requires-python = ">=3.12"

{dotenvmodel-0.6.0 → dotenvmodel-0.6.2}/tests/conftest.py

@@ -9,15 +9,20 @@ from dotenvmodel.caching import _CACHED_ATTR
 
 
 def _all_dotenv_subclasses() -> Iterator[type[DotEnvConfig]]:
-    """Yield every currently-alive DotEnvConfig subclass, recursively.
+    """Yield DotEnvConfig itself and every currently-alive subclass, recursively.
+
+    The stack is seeded with the base class so its own cached state (if any)
+    is snapshotted/restored too — the caching module stores instances as
+    per-class ``__dict__`` entries, and the base class is itself a valid
+    ``cached()`` target.
 
     ``type.__subclasses__()`` returns only direct subclasses and uses weak
     references internally — it does not prevent garbage collection of classes
     with no other referents (verified empirically). We walk the tree
     depth-first, deduplicating by identity to handle diamond hierarchies.
     """
-    seen: set[type] = set()
-    stack: list[type] = list(DotEnvConfig.__subclasses__())
+    seen: set[type[DotEnvConfig]] = set()
+    stack: list[type[DotEnvConfig]] = [DotEnvConfig]
     while stack:
         cls = stack.pop()
         if cls in seen:
@@ -29,19 +34,19 @@ def _all_dotenv_subclasses() -> Iterator[type[DotEnvConfig]]:
 
 @pytest.fixture(autouse=True)
 def _restore_cached_state() -> Iterator[None]:
-    """Snapshot and restore ``_cached_instance`` on every DotEnvConfig subclass.
+    """Snapshot and restore ``_cached_instance`` on DotEnvConfig and every subclass.
 
     Function-scoped (autouse) because cached state must be restored after
     every single test — a session-scoped fixture would allow one test's
     cached instance to leak into the next.
 
-    At setup, walks every alive ``DotEnvConfig`` subclass and records which
-    ones have their *own* ``_cached_instance`` entry in ``cls.__dict__``
-    (not inherited) and what the value is. At teardown, restores the exact
-    pre-test state: classes that had an entry get it restored; classes
-    discovered after the test that have an entry but did not have one before
-    get it removed. Classes that had no entry before and still have none
-    are untouched.
+    At setup, walks ``DotEnvConfig`` itself and every alive subclass and
+    records which ones have their *own* ``_cached_instance`` entry in
+    ``cls.__dict__`` (not inherited) and what the value is. At teardown,
+    restores the exact pre-test state: classes that had an entry get it
+    restored; classes discovered after the test that have an entry but did
+    not have one before get it removed. Classes that had no entry before
+    and still have none are untouched.
 
     This is a belt-and-suspenders safety net. For test files where every
     test defines its own locally-scoped subclass, isolation is already
@@ -54,7 +59,7 @@ def _restore_cached_state() -> Iterator[None]:
 
 
 def _snapshot_and_restore_cached_state() -> Iterator[None]:
-    """Generator that snapshots and restores ``_cached_instance`` on all subclasses.
+    """Generator that snapshots/restores ``_cached_instance`` on the base class and all subclasses.
 
     This is the underlying logic for :func:`_restore_cached_state`, extracted
     as a plain (non-fixture) generator so it can also be driven manually in