dotenvmodel 0.5.4__tar.gz → 0.6.0__tar.gz

{dotenvmodel-0.5.4 → dotenvmodel-0.6.0}/.github/workflows/ci.yml

@@ -53,7 +53,7 @@ jobs:
         run: uv sync --group dev
 
       - name: Type check with pyright
-        run: uv run pyright dotenvmodel
+        run: uv run pyright dotenvmodel tests
 
   test:
     runs-on: ubuntu-latest

{dotenvmodel-0.5.4 → dotenvmodel-0.6.0}/.github/workflows/publish.yml

@@ -28,7 +28,7 @@ jobs:
           ref: ${{ inputs.tag_name || github.ref }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.2
+        uses: astral-sh/setup-uv@v9.0.0
         with:
           enable-cache: true
 

{dotenvmodel-0.5.4 → dotenvmodel-0.6.0}/.gitignore

@@ -193,6 +193,9 @@ cython_debug/
 # Serena
 .serena/
 
+# Cross-family review scratch output
+.xreview/
+
 # Ruff stuff:
 .ruff_cache/
 

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

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

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

@@ -5,6 +5,18 @@ 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.0](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.5.4...v0.6.0) (2026-07-27)
+
+
+### Features
+
+* add cached() / reset_cached() / cached_override() singleton accessor ([#51](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/51)) ([638f8cc](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/638f8cc8515398ad983bc321dd906effe4df17f8))
+
+
+### Continuous Integration
+
+* bump setup-uv to v9.0.0 ([#48](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/48)) ([21bcc4f](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/21bcc4f96d16a1e075d3c59ba3291cb1f9af32d6))
+
 ## [0.5.4](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.5.3...v0.5.4) (2026-07-22)
 
 

{dotenvmodel-0.5.4 → dotenvmodel-0.6.0}/Makefile

@@ -4,9 +4,9 @@ help:
 	@echo "Available commands:"
 	@echo "  make install      - Install package and dev dependencies"
 	@echo "  make test         - Run tests with coverage"
-	@echo "  make lint         - Run ruff linter"
+	@echo "  make lint         - Run ruff linter and formatting check (matches CI)"
 	@echo "  make format       - Format code with ruff"
-	@echo "  make type-check   - Run pyright type checker"
+	@echo "  make type-check   - Run pyright type checker (dotenvmodel + tests)"
 	@echo "  make clean        - Clean build artifacts"
 	@echo "  make build        - Build package"
 	@echo "  make publish      - Publish to PyPI"
@@ -19,13 +19,14 @@ test:
 
 lint:
 	uv run ruff check .
+	uv run ruff format --check .
 
 format:
 	uv run ruff format .
 	uv run ruff check --fix .
 
 type-check:
-	uv run pyright dotenvmodel
+	uv run pyright dotenvmodel tests
 
 clean:
 	rm -rf build/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.5.4
+Version: 0.6.0
 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
@@ -1357,6 +1357,27 @@ def test_with_fixture(test_config):
     assert test_config.database_url == "sqlite:///:memory:"
 ```
 
+The `load_from_dict()` examples above test a config's field-parsing logic directly. If your application code calls `AppConfig.cached()` — the process-wide singleton — one test's cached instance will leak into the next. Use `cached_override()` for a scoped, self-restoring per-test override (the recommended approach, structurally similar to Django's `override_settings`):
+
+```python
+def test_with_custom_config():
+    test_config = AppConfig.load_from_dict({"DATABASE_URL": "postgresql://localhost/test"})
+    with AppConfig.cached_override(test_config):
+        assert AppConfig.cached() is test_config
+    # Previous cached() state is automatically restored here — even if the test raised.
+```
+
+For a blanket teardown between test modules, use `reset_cached()` in an `autouse` fixture:
+
+```python
+@pytest.fixture(autouse=True)
+def reset_config_cache():
+    yield
+    AppConfig.reset_cached()
+```
+
+See the [Caching guide](docs/guides/loading.md#caching-a-singleton-instance) for the full lazy/thread-safe singleton pattern, test idioms, and guidance on when `cached()` is appropriate vs. dependency injection.
+
 ## Best Practices
 
 1. **Use Type Hints**: Always specify type hints for proper validation
@@ -1401,9 +1422,10 @@ def test_with_fixture(test_config):
 
 `DotEnvConfig` instances are **not thread-safe** during `reload()`. If multiple threads call `reload()` on the same instance concurrently, field values may become inconsistent. In multi-threaded server environments (FastAPI, gunicorn, etc.):
 
-- Call `load()` once at startup and share the immutable instance
+- Call `load()` once at startup and share the immutable instance, or use `cached()` for a built-in lazy, thread-safe singleton that does this automatically
 - If you need to reload, use a lock or create a new instance via `load()` instead of calling `reload()` on a shared instance
 - Avoid calling `reload()` while request handlers are reading config values
+- In tests that need different configurations per test, use `cached_override()` for a scoped, self-restoring override, or `reset_cached()` in a fixture for a blanket teardown between test modules
 
 ### Union Types (Non-Optional)
 

{dotenvmodel-0.5.4 → dotenvmodel-0.6.0}/README.md

@@ -1329,6 +1329,27 @@ def test_with_fixture(test_config):
     assert test_config.database_url == "sqlite:///:memory:"
 ```
 
+The `load_from_dict()` examples above test a config's field-parsing logic directly. If your application code calls `AppConfig.cached()` — the process-wide singleton — one test's cached instance will leak into the next. Use `cached_override()` for a scoped, self-restoring per-test override (the recommended approach, structurally similar to Django's `override_settings`):
+
+```python
+def test_with_custom_config():
+    test_config = AppConfig.load_from_dict({"DATABASE_URL": "postgresql://localhost/test"})
+    with AppConfig.cached_override(test_config):
+        assert AppConfig.cached() is test_config
+    # Previous cached() state is automatically restored here — even if the test raised.
+```
+
+For a blanket teardown between test modules, use `reset_cached()` in an `autouse` fixture:
+
+```python
+@pytest.fixture(autouse=True)
+def reset_config_cache():
+    yield
+    AppConfig.reset_cached()
+```
+
+See the [Caching guide](docs/guides/loading.md#caching-a-singleton-instance) for the full lazy/thread-safe singleton pattern, test idioms, and guidance on when `cached()` is appropriate vs. dependency injection.
+
 ## Best Practices
 
 1. **Use Type Hints**: Always specify type hints for proper validation
@@ -1373,9 +1394,10 @@ def test_with_fixture(test_config):
 
 `DotEnvConfig` instances are **not thread-safe** during `reload()`. If multiple threads call `reload()` on the same instance concurrently, field values may become inconsistent. In multi-threaded server environments (FastAPI, gunicorn, etc.):
 
-- Call `load()` once at startup and share the immutable instance
+- Call `load()` once at startup and share the immutable instance, or use `cached()` for a built-in lazy, thread-safe singleton that does this automatically
 - If you need to reload, use a lock or create a new instance via `load()` instead of calling `reload()` on a shared instance
 - Avoid calling `reload()` while request handlers are reading config values
+- In tests that need different configurations per test, use `cached_override()` for a scoped, self-restoring override, or `reset_cached()` in a fixture for a blanket teardown between test modules
 
 ### Union Types (Non-Optional)
 

dotenvmodel-0.6.0/docs/api-reference/caching.md

@@ -0,0 +1,5 @@
+# Caching
+
+Cached singleton-instance machinery for DotEnvConfig subclasses.
+
+::: dotenvmodel.caching

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

@@ -201,9 +201,97 @@ config.reload(override=False)
 
     `DotEnvConfig` instances are **not thread-safe** during `reload()`. In multi-threaded environments, use a lock or create a new instance via `load()` instead of calling `reload()` on a shared instance.
 
+## Caching a Singleton Instance
+
+Application code often needs a single shared config instance that is loaded once and reused everywhere. `cached()` provides this as a built-in: it loads on first call and returns the same instance on every subsequent call, with no re-reading of the environment.
+
+```python
+class AppConfig(DotEnvConfig):
+    database_url: str = Field()
+    port: int = Field(default=8000)
+
+# First call loads from the environment.
+config = AppConfig.cached()
+
+# Subsequent calls return the same instance — no re-read.
+same_config = AppConfig.cached()
+assert config is same_config
+```
+
+### Lazy and Thread-Safe
+
+`cached()` is lazy — the environment is only read on the very first call. It is also thread-safe: if multiple threads call `cached()` simultaneously before the first load completes, they race on a lock and only one thread calls `load()`; the rest block and receive the same instance. Once the cache is warm, all calls return immediately without acquiring the lock.
+
+Arguments (`env`, `override`, `env_dir`) are only used on the first call. Once the instance is cached, subsequent calls ignore any arguments and return the existing instance. A warning is logged if non-default arguments are passed against an already-warm cache.
+
+Calling `.reload()` on the cached instance mutates it in place; since `cached()` always returns the same object, subsequent `cached()` calls see the reloaded values.
+
+!!! 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`.
+
+### Scoped Overrides for Tests
+
+`cached_override()` is a context manager that temporarily replaces the cached instance for the duration of a `with` block and automatically restores the previous state on exit — even if the block raises an exception. This is the **primary recommended tool** for test isolation when a single test needs a different config: it is structurally the same shape as Django's `override_settings` — scoped, self-restoring, and failure-safe.
+
+```python
+def test_with_custom_config():
+    test_config = AppConfig.load_from_dict({"DATABASE_URL": "postgresql://localhost/test"})
+    with AppConfig.cached_override(test_config):
+        assert AppConfig.cached() is test_config
+    # Previous cached() state (or absence of one) is restored here.
+```
+
+Because restoration is automatic and unconditional, `cached_override()` cannot forget to clean up — unlike a bare `reset_cached()` call that a test author might omit, silently leaking state into the next test. Reach for `cached_override()` first when a single test needs a different config; use `reset_cached()` (below) for the coarser case of a blanket fixture teardown between test modules.
+
+!!! warning "Not for concurrent use"
+
+    `cached_override()` is not designed for use while other threads may concurrently call `cached()` on the same class. The override window is not synchronized against concurrent readers beyond the lock-protected set/restore operations, so overlapping a `cached_override()` block with genuinely concurrent cross-thread `cached()` calls is racy in terms of which threads observe the override vs. the restored value. No data corruption occurs, but the observed value is unspecified during the transition.
+
+### Resetting the Cache for Tests
+
+`reset_cached()` is the coarser fallback: it unconditionally clears this class's cached instance so the next `cached()` call will call `load()` again. It is useful as a blanket fixture teardown — for example, clearing everything between test modules — but `cached_override()` (above) should be reached for first when a single test needs a different config, because `reset_cached()` cannot auto-restore and a forgotten call leaks state.
+
+```python
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def reset_config_cache():
+    yield
+    AppConfig.reset_cached()
+
+
+def test_dev_config(monkeypatch):
+    monkeypatch.setenv("DATABASE_URL", "postgresql://localhost/dev")
+    config = AppConfig.cached()
+    assert "dev" in config.database_url
+
+
+def test_prod_config(monkeypatch):
+    monkeypatch.setenv("DATABASE_URL", "postgresql://localhost/prod")
+    config = AppConfig.cached()
+    assert "prod" in config.database_url
+```
+
+`reset_cached()` only affects the exact class it is called on — other `DotEnvConfig` subclasses keep their own cached instances.
+
+!!! note "Per-class isolation"
+
+    The cache is keyed by the exact class object. `SubA.cached()` and `SubB.cached()` cache independently, and a subclass of a subclass does not inherit its parent's cached instance.
+
+### Not a Substitute for Dependency Injection
+
+`cached()` is a single-config-per-process convenience for the common case where there is no DI framework already in place — scripts, simple services, cases where threading a config parameter through every call is impractical. It is **not** a substitute for dependency injection in applications that already have one.
+
+- **pydantic-settings** deliberately does not ship a singleton/caching accessor itself; the maintainers' position (see [pydantic/pydantic-settings#410](https://github.com/pydantic/pydantic-settings/issues/410)) is that singleton lifecycle is an application concern, not the settings library's.
+- **FastAPI**'s own documented settings pattern uses `functools.lru_cache` to avoid re-loading, but the load-bearing mechanism for *testability* is `app.dependency_overrides` — FastAPI's docs steer people toward DI-based overriding for tests, with the cache being an optimization, not the override mechanism.
+
+**Conclusion:** if your application already has an app/request object and a DI mechanism (FastAPI, Flask with a DI extension, `svcs`-style service locators, etc.), prefer injecting the loaded config instance through that mechanism rather than calling `cached()` from deep in the call stack. `cached()` and `cached_override()` exist for the case where there is no DI framework to thread the config through — not to encourage a global-singleton-everywhere style in apps that already have DI.
+
 ## See Also
 
 - [Loading API Reference](../api-reference/loading.md) — `load_env_files()`, `get_env_var()`, `get_env_var_name()`
-- [DotEnvConfig API Reference](../api-reference/config.md) — `load()`, `reload()`, `load_from_dict()`
+- [DotEnvConfig API Reference](../api-reference/config.md) — `load()`, `reload()`, `load_from_dict()`, `cached()`, `reset_cached()`, `cached_override()`
 - [Field Definitions](fields.md) — Defining config fields with `Field()`
 - [Validation](validation.md) — Constraint validation

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

@@ -23,6 +23,9 @@ Public API:
     - `ValidatorContext`: Context passed to `Field(validator=...)` hooks
     - `DotEnvConfig.post_load`: Model-level hook for cross-field validation
       and normalization after loading
+    - `DotEnvConfig.cached` / `DotEnvConfig.reset_cached` / `DotEnvConfig.cached_override`:
+      Process-wide thread-safe singleton accessor, its reset, and a scoped
+      self-restoring override for test isolation
     - `SecretStr`: String type that hides values in logs
     - `HttpUrl`, `PostgresDsn`, `RedisDsn`: URL/DSN types with validation
     - `Json`: Type for parsing JSON strings
@@ -34,7 +37,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.5.4"  # x-release-please-version
+__version__ = "0.6.0"  # x-release-please-version
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"

dotenvmodel-0.6.0/dotenvmodel/caching.py

@@ -0,0 +1,195 @@
+"""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.Lock`` guards the double-checked-locking
+    initialization path and the save/restore operations in
+    ``begin_override`` / ``end_override``.  A ``threading.local`` set tracks
+    same-thread reentrant ``cached()`` calls to detect and raise on
+    self-deadlock scenarios.
+"""
+
+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.Lock()
+_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 for reentrant-``cached()`` deadlock detection. Each thread gets its
+    own independent set, so only same-thread reentrancy is detected (the actual
+    deadlock scenario). 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.
+    """
+    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 non-default arguments were passed against
+    an already-warm cache). 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`` instead of
+    deadlocking on the non-reentrant lock.
+
+    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.
+    """
+    cached = get_cached(cls)
+    if cached is not None:
+        if env is not None or override is not True or env_dir is not None:
+            logger.warning(
+                "cached() called on %s with arguments (env=%r, override=%r, "
+                "env_dir=%r) but the cache is already populated; "
+                "arguments were ignored.",
+                cls.__name__,
+                env,
+                override,
+                env_dir,
+            )
+        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). This would deadlock. "
+            f"If a hook needs the instance mid-load, call cls.load() "
+            f"directly or use 'self' instead."
+        )
+
+    loading.add(cls)
+    try:
+        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.
+    """
+    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.
+    """
+    with _cache_lock:
+        if had_cached:
+            set_cached(cls, cast("DotEnvConfig", previous))
+        elif has_cached(cls):
+            delattr(cls, _CACHED_ATTR)