dotenvmodel 0.6.1__tar.gz → 0.6.3__tar.gz

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

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

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/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.3](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.6.2...v0.6.3) (2026-07-28)
+
+
+### Bug Fixes
+
+* reload() must update the instance's recorded load arguments ([#56](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/56)) ([a293461](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/a2934612da52130cc539be65bd1fe196a4381dde))
+
+## [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)
 
 

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.6.1
+Version: 0.6.3
 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.1 → dotenvmodel-0.6.3}/docs/guides/loading.md

@@ -222,9 +222,9 @@ assert config is same_config
 
 `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.
+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 when the arguments passed disagree with the ones the cached instance was loaded with — so an accessor that consistently passes the same non-default arguments (`override=False`, say) stays silent, while a caller asking for something the cache does not hold is told what it actually holds.
 
-Calling `.reload()` on the cached instance mutates it in place; since `cached()` always returns the same object, subsequent `cached()` calls see the reloaded values.
+Calling `.reload()` on the cached instance mutates it in place; since `cached()` always returns the same object, subsequent `cached()` calls see the reloaded values. A reload also updates what the instance reports as its load arguments, so `reload(env="prod")` is reflected by both `loaded_with()` and the comparison above.
 
 !!! warning "Reentrant `cached()` calls raise `RuntimeError`"
 

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/dotenvmodel/__init__.py

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

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/dotenvmodel/caching.py

@@ -141,8 +141,8 @@ def acquire_cached(
 
     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
+    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
@@ -168,15 +168,28 @@ def acquire_cached(
     """
     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:
+        # 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; "
-                "arguments were ignored.",
+                "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
 

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/dotenvmodel/config.py

@@ -567,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,
@@ -628,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)
 
@@ -640,6 +655,9 @@ class DotEnvConfig(metaclass=ConfigMeta):
         logger.info(f"{self.__class__.__name__} configuration reloaded successfully")
         logger.debug(f"Reloaded fields: {', '.join(self._fields.keys())}")
 
+        self._load_env = reload_env
+        self._load_override = reload_override
+        self._load_env_dir = reload_env_dir
         return self
 
     @classmethod
@@ -709,8 +727,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

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/pyproject.toml

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

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/tests/test_cached.py

@@ -162,8 +162,10 @@ class TestCached:
         assert_type(config, MyConfig)
         assert config.value == "typed"
 
-    def test_warning_logged_when_non_default_args_on_warm_cache(self, monkeypatch, caplog) -> None:
-        """cached() logs a warning when non-default args are passed against a warm cache."""
+    def test_warning_logged_when_args_disagree_with_the_warm_cache(
+        self, monkeypatch, caplog
+    ) -> None:
+        """cached() warns when a caller's args differ from the ones that populated the cache."""
 
         class Config(DotEnvConfig):
             value: str = Field(default="x")
@@ -176,6 +178,130 @@ class TestCached:
         assert result is Config.cached()
         assert any("arguments were ignored" in r.message for r in caplog.records)
 
+    def test_repeating_the_arguments_the_cache_was_built_with_is_silent(
+        self, monkeypatch, caplog
+    ) -> None:
+        """Asking for what you already got is not a mistake and must not be reported as one.
+
+        The motivating case is an application accessor that must pass ``override=False`` (the
+        process environment beats ``.env`` files, per 12-factor) on every call. Warning it every
+        time emits a line per settings access for entirely correct usage — and a warning that
+        fires on correct usage is one readers learn to filter out, costing it the job it exists
+        for, which ``test_warning_logged_when_args_disagree_with_the_warm_cache`` still covers.
+
+        Asserts on WHETHER anything was reported, never on the wording: the promise is silence,
+        not a particular sentence, and a reworded message must not fail this test.
+        """
+
+        class Config(DotEnvConfig):
+            value: str = Field(default="x")
+
+        args = {"env": "prod", "override": False, "env_dir": Path("/tmp")}
+        first = Config.cached(**args)
+
+        # Window opened AFTER the populating call, so only the repeats are observed.
+        with caplog.at_level("WARNING", logger="dotenvmodel"):
+            caplog.clear()
+            second = Config.cached(**args)
+            third = Config.cached(**args)
+            repeats_reported = list(caplog.records)
+
+        assert second is first
+        assert third is first
+        assert repeats_reported == []
+
+    def test_a_bare_reload_keeps_the_precedence_the_cache_was_loaded_with(
+        self, monkeypatch, caplog
+    ) -> None:
+        """The SIGHUP shape: ``reload()`` with no arguments must not revert to ``override=True``.
+
+        A hot-reload handler calls ``reload()`` bare. If that silently reset precedence to
+        "``.env`` files beat the process environment", a running service would flip to the
+        opposite configuration on a signal it was told was a no-op refresh — and an accessor
+        passing ``override=False`` would then also start warning, having never changed.
+        """
+
+        class Config(DotEnvConfig):
+            value: str = Field(default="x")
+
+        instance = Config.cached(override=False, env_dir=Path("/tmp"))
+        assert instance.loaded_with() == (None, False, Path("/tmp"))
+
+        instance.reload()
+
+        assert instance.loaded_with() == (None, False, Path("/tmp"))
+        with caplog.at_level("WARNING", logger="dotenvmodel"):
+            caplog.clear()
+            assert Config.cached(override=False, env_dir=Path("/tmp")) is instance
+            reported = list(caplog.records)
+        assert reported == []
+
+    def test_reload_with_new_env_updates_loaded_with(self, monkeypatch) -> None:
+        """``reload(env=...)`` must update ``loaded_with()`` so a subsequent bare reload reuses it.
+
+        Without this, ``reload(env="prod")`` leaves ``loaded_with()`` reporting the original
+        env, a bare ``reload()`` silently reverts to it, and ``cached()`` warns on the
+        env the instance actually holds because ``loaded_with()`` still says the old one.
+        """
+
+        class Config(DotEnvConfig):
+            value: str = Field(default="x")
+
+        instance = Config.load(env="dev", override=False)
+        assert instance.loaded_with() == ("dev", False, None)
+
+        instance.reload(env="prod")
+
+        assert instance.loaded_with() == ("prod", False, None)
+
+        instance.reload()
+
+        assert instance.loaded_with() == ("prod", False, None)
+
+    def test_a_reset_cache_is_not_judged_against_the_arguments_it_dropped(
+        self, monkeypatch, caplog
+    ) -> None:
+        """After ``reset_cached()`` the next call repopulates, so it cannot disagree with anything."""
+
+        class Config(DotEnvConfig):
+            value: str = Field(default="x")
+
+        Config.cached(override=False)
+        Config.reset_cached()
+        # Repopulate OUTSIDE the window: a real load emits its own unrelated warnings (e.g. "no
+        # .env files found"), and this test is about the warm path, not about loading.
+        Config.cached(env="prod")
+
+        with caplog.at_level("WARNING", logger="dotenvmodel"):
+            caplog.clear()
+            Config.cached(env="prod")
+            reported = list(caplog.records)
+
+        assert reported == []
+
+    def test_a_scoped_override_leaves_the_warm_cache_judged_as_before(
+        self, monkeypatch, caplog
+    ) -> None:
+        """Exiting ``cached_override()`` restores the pre-override state, warnings included."""
+
+        class Config(DotEnvConfig):
+            value: str = Field(default="x")
+
+        Config.cached(override=False)
+        with Config.cached_override(Config.load_from_dict({"VALUE": "y"})):
+            pass
+
+        with caplog.at_level("WARNING", logger="dotenvmodel"):
+            caplog.clear()
+            Config.cached(override=False)
+            agreeing = list(caplog.records)
+            caplog.clear()
+            Config.cached(env="prod")
+            disagreeing = list(caplog.records)
+
+        assert agreeing == []
+        assert len(disagreeing) == 1
+
     def test_thread_safety_concurrent_first_access(self, monkeypatch) -> None:
         """Concurrent first callers all receive the same single instance."""
         import time

{dotenvmodel-0.6.1 → dotenvmodel-0.6.3}/uv.lock

@@ -245,7 +245,7 @@ wheels = [
 
 [[package]]
 name = "dotenvmodel"
-version = "0.6.1"
+version = "0.6.3"
 source = { editable = "." }
 dependencies = [
     { name = "python-dotenv" },

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

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