dotenvmodel 0.3.1__tar.gz → 0.3.2__tar.gz

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

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

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.3.2](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.3.1...v0.3.2) (2026-07-15)
+
+
+### Bug Fixes
+
+* resolve nested DotEnvConfig field defaults not being loaded ([#34](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/34)) ([4a3bb88](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/4a3bb8864dad044977d7b72be41e15307fff8f4d))
+
 ## [0.3.1](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.3.0...v0.3.1) (2026-07-13)
 
 

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.3.1
+Version: 0.3.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
@@ -1036,6 +1036,30 @@ redis = RedisConfig.load()      # Reads REDIS_HOST, REDIS_PORT
 app = AppConfig.load()          # Reads APP_NAME, APP_VERSION
 ```
 
+### Nested Configuration
+
+A field typed as another `DotEnvConfig` subclass is loaded as a nested config, resolving its own fields (including defaults) from its own `env_prefix` — independently of the parent's prefix:
+
+```python
+class OIDCSettings(DotEnvConfig):
+    env_prefix = "WARDEN_OIDC_"
+    issuer: str = Field(default="")
+    session_max_age_seconds: int = Field(default=28800)
+
+class Settings(DotEnvConfig):
+    env_prefix = "WARDEN_"
+    service_name: str = Field(default="warden")
+    oidc: OIDCSettings = Field(default_factory=OIDCSettings)
+
+settings = Settings.load_from_dict({
+    "WARDEN_OIDC_SESSION_MAX_AGE_SECONDS": "3600",
+})
+settings.oidc.session_max_age_seconds  # 3600 (overridden)
+settings.oidc.issuer                   # "" (nested default, not the parent's prefix)
+```
+
+Nested `env_prefix` values are **absolute, not concatenated** with the parent's — `OIDCSettings.env_prefix` above is `WARDEN_OIDC_` in full, not appended to `Settings.env_prefix`. `.load()`, `.load_from_dict()`, and `.reload()` all resolve nested fields the same way. See [Known Limitations](#known-limitations) for `Optional[NestedConfig]` and `describe()` caveats.
+
 ## Error Handling
 
 ### Missing Required Field
@@ -1264,6 +1288,25 @@ config = Config.load()
 value_as_int = int(config.value) if config.value.isdigit() else config.value
 ```
 
+### Optional Nested Configuration
+
+`Optional[NestedConfig]` / `NestedConfig | None` fields are **not** supported the way a plain `nested: NestedConfig = Field(default_factory=NestedConfig)` field is — an Optional-typed nested field falls through to ordinary Optional-scalar handling and silently resolves to `None`, discarding any env vars set at the nested prefix:
+
+```python
+class Config(DotEnvConfig):
+    env_prefix = "APP_"
+    nested: NestedConfig | None = Field(default=None)
+
+config = Config.load_from_dict({"APP_NESTED_PORT": "8080"})
+config.nested  # None — the override above is silently ignored
+```
+
+**Workaround**: give the nested field a non-Optional type with `default_factory`, as in [Nested Configuration](#nested-configuration) above. If the nested config is conditionally absent in your app, model that with a `bool`/enum field inside the nested config itself rather than making the field Optional.
+
+### `describe()` / `generate_env_example()` and Nested Configuration
+
+`describe()` and `generate_env_example()` do not recurse into nested config fields — a nested field renders as an opaque, non-functional placeholder (e.g. `APP_NESTED=<NestedConfig()>`) rather than expanding to the nested class's real, settable env vars (e.g. `APP_NESTED_PORT`). Don't rely on generated `.env.example` output to discover a nested config's real variables — read the nested class's own fields (or its own `describe()` output) directly.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/README.md

@@ -1008,6 +1008,30 @@ redis = RedisConfig.load()      # Reads REDIS_HOST, REDIS_PORT
 app = AppConfig.load()          # Reads APP_NAME, APP_VERSION
 ```
 
+### Nested Configuration
+
+A field typed as another `DotEnvConfig` subclass is loaded as a nested config, resolving its own fields (including defaults) from its own `env_prefix` — independently of the parent's prefix:
+
+```python
+class OIDCSettings(DotEnvConfig):
+    env_prefix = "WARDEN_OIDC_"
+    issuer: str = Field(default="")
+    session_max_age_seconds: int = Field(default=28800)
+
+class Settings(DotEnvConfig):
+    env_prefix = "WARDEN_"
+    service_name: str = Field(default="warden")
+    oidc: OIDCSettings = Field(default_factory=OIDCSettings)
+
+settings = Settings.load_from_dict({
+    "WARDEN_OIDC_SESSION_MAX_AGE_SECONDS": "3600",
+})
+settings.oidc.session_max_age_seconds  # 3600 (overridden)
+settings.oidc.issuer                   # "" (nested default, not the parent's prefix)
+```
+
+Nested `env_prefix` values are **absolute, not concatenated** with the parent's — `OIDCSettings.env_prefix` above is `WARDEN_OIDC_` in full, not appended to `Settings.env_prefix`. `.load()`, `.load_from_dict()`, and `.reload()` all resolve nested fields the same way. See [Known Limitations](#known-limitations) for `Optional[NestedConfig]` and `describe()` caveats.
+
 ## Error Handling
 
 ### Missing Required Field
@@ -1236,6 +1260,25 @@ config = Config.load()
 value_as_int = int(config.value) if config.value.isdigit() else config.value
 ```
 
+### Optional Nested Configuration
+
+`Optional[NestedConfig]` / `NestedConfig | None` fields are **not** supported the way a plain `nested: NestedConfig = Field(default_factory=NestedConfig)` field is — an Optional-typed nested field falls through to ordinary Optional-scalar handling and silently resolves to `None`, discarding any env vars set at the nested prefix:
+
+```python
+class Config(DotEnvConfig):
+    env_prefix = "APP_"
+    nested: NestedConfig | None = Field(default=None)
+
+config = Config.load_from_dict({"APP_NESTED_PORT": "8080"})
+config.nested  # None — the override above is silently ignored
+```
+
+**Workaround**: give the nested field a non-Optional type with `default_factory`, as in [Nested Configuration](#nested-configuration) above. If the nested config is conditionally absent in your app, model that with a `bool`/enum field inside the nested config itself rather than making the field Optional.
+
+### `describe()` / `generate_env_example()` and Nested Configuration
+
+`describe()` and `generate_env_example()` do not recurse into nested config fields — a nested field renders as an opaque, non-functional placeholder (e.g. `APP_NESTED=<NestedConfig()>`) rather than expanding to the nested class's real, settable env vars (e.g. `APP_NESTED_PORT`). Don't rely on generated `.env.example` output to discover a nested config's real variables — read the nested class's own fields (or its own `describe()` output) directly.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/dotenvmodel/__init__.py

@@ -31,7 +31,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/dotenvmodel/config.py

@@ -78,6 +78,7 @@ class DotEnvConfig(metaclass=ConfigMeta):
         raw_value: str | None,
         env_var_name: str,
         *,
+        env_source: builtins.dict[str, str] | None = None,
         validate: bool = True,
     ) -> Any:
         """
@@ -89,6 +90,10 @@ class DotEnvConfig(metaclass=ConfigMeta):
             field_info: Field metadata
             raw_value: Raw string value from environment (or None)
             env_var_name: Environment variable name for error messages
+            env_source: The source passed to the enclosing `_load_fields` call
+                (None for real env vars, or a dict for `load_from_dict`).
+                Forwarded to nested `DotEnvConfig` fields so they resolve
+                from the same source as their parent.
             validate: Whether to perform validation (default: True)
 
         Returns:
@@ -98,6 +103,33 @@ class DotEnvConfig(metaclass=ConfigMeta):
             MissingFieldError: If required field is missing
             ValidationError: If validation fails
         """
+        # Nested DotEnvConfig fields (e.g. `oidc: OIDCSettings`) are not a
+        # scalar to coerce — a nested config resolves its own fields from
+        # the same env_source using its own env_prefix, so it must always
+        # go through _load_fields() regardless of whether raw_value (the
+        # value of an env var literally named after the field, which no
+        # one sets) is present. A bare `field_type()` here would silently
+        # produce an unloaded instance whose fields never got populated.
+        #
+        # Note: this only matches a plain `type` — `Optional[Nested]` /
+        # `Nested | None` is a Union, not a `type`, so it does NOT take
+        # this branch and instead falls through to the Optional handling
+        # in coerce_value(), which just returns None for a missing literal
+        # env var without trying the nested prefix. See
+        # TestOptionalNestedConfigLimitation below — tracked as a known
+        # follow-up, not fixed here.
+        #
+        # Note: field_info.required is deliberately not consulted here —
+        # a `Field()`-required (no default) nested config now always
+        # resolves successfully using the nested class's own defaults,
+        # rather than raising MissingFieldError. "Required" is expressed
+        # on the nested class's own fields instead. See
+        # TestRequiredNestedConfigField below for the pinned behavior.
+        if isinstance(field_type, type) and issubclass(field_type, DotEnvConfig):
+            nested = field_type()
+            nested._load_fields(env_source, validate=validate)
+            return nested
+
         # Handle missing values
         if raw_value is None:
             if field_info.required:
@@ -164,11 +196,18 @@ class DotEnvConfig(metaclass=ConfigMeta):
                     field_info,
                     raw_value,
                     env_var_name,
+                    env_source=env_source,
                     validate=validate,
                 )
                 setattr(self, field_name, value)
             except ValidationError as e:
                 errors.append(e)
+            except MultipleValidationErrors as e:
+                # Raised when a nested DotEnvConfig field (see
+                # _process_field) has multiple invalid fields of its own —
+                # flatten into this level's collection instead of letting
+                # it escape uncaught past the aggregation loop.
+                errors.extend(e.errors)
 
         if errors:
             if len(errors) == 1:

{dotenvmodel-0.3.1 → dotenvmodel-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dotenvmodel"
-version = "0.3.1"
+version = "0.3.2"
 description = "Type-safe environment configuration with automatic .env file loading"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -49,13 +49,13 @@ packages = ["dotenvmodel"]
 dev = [
     "mkdocs>=1.6.1",
     "mkdocs-material>=9.7.6",
-    "mkdocstrings[python]>=1.0.4",
+    "mkdocstrings[python]>=1.0.6",
     "pip-audit>=2.10.1",
     "pyright>=1.1.411",
     "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
-    "ruff>=0.15.20",
-    "ty>=0.0.56",
+    "ruff>=0.15.21",
+    "ty>=0.0.59",
 ]
 
 [tool.ruff]

dotenvmodel-0.3.2/tests/test_nested_config.py

@@ -0,0 +1,238 @@
+"""Tests for nested DotEnvConfig fields (a config field whose type is itself
+a DotEnvConfig subclass, e.g. `oidc: OIDCSettings = Field(default_factory=OIDCSettings)`).
+
+Regression coverage for a bug where a nested config's own declared field
+defaults silently resolved to None: the metaclass resets every field's
+class attribute to None at class-definition time (to avoid sharing mutable
+FieldInfo objects across instances) and relies on _load_fields() being
+called at instantiation to repopulate them. A nested field's default_factory
+bare-constructs the nested class without ever calling _load_fields() on it,
+so every one of its fields stayed at that reset-to-None class attribute.
+"""
+
+import pytest
+
+from dotenvmodel import DotEnvConfig, Field
+from dotenvmodel.exceptions import ConstraintViolationError, MultipleValidationErrors
+
+
+class Nested(DotEnvConfig):
+    env_prefix = "APP_NESTED_"
+    port: int = Field(default=10, ge=1, le=100)
+    name: str = Field(default="nested-default")
+    enabled: bool = Field(default=True)
+
+
+class Outer(DotEnvConfig):
+    env_prefix = "APP_"
+    top: str = Field(default="top-default")
+    nested: Nested = Field(default_factory=Nested)
+
+
+class TestNestedConfigDefaults:
+    def test_load_from_dict_resolves_nested_defaults(self) -> None:
+        config = Outer.load_from_dict({})
+
+        assert config.top == "top-default"
+        assert config.nested.port == 10
+        assert config.nested.name == "nested-default"
+        assert config.nested.enabled is True
+
+    def test_load_resolves_nested_defaults_with_empty_environment(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("APP_TOP", raising=False)
+        monkeypatch.delenv("APP_NESTED_PORT", raising=False)
+        monkeypatch.delenv("APP_NESTED_NAME", raising=False)
+        monkeypatch.delenv("APP_NESTED_ENABLED", raising=False)
+
+        config = Outer.load()
+
+        assert config.nested.port == 10
+        assert config.nested.name == "nested-default"
+        assert config.nested.enabled is True
+
+    def test_nested_default_is_a_real_instance_not_none(self) -> None:
+        config = Outer.load_from_dict({})
+
+        assert isinstance(config.nested, Nested)
+        assert config.nested.port is not None
+        assert config.nested.name is not None
+        assert config.nested.enabled is not None
+
+
+class TestNestedConfigOverrides:
+    def test_env_var_with_nested_prefix_overrides_default(self) -> None:
+        config = Outer.load_from_dict({"APP_NESTED_PORT": "55"})
+
+        assert config.nested.port == 55
+        # Sibling nested fields keep their own defaults
+        assert config.nested.name == "nested-default"
+
+    def test_nested_prefix_is_independent_of_parent_prefix(self) -> None:
+        config = Outer.load_from_dict({"APP_TOP": "override", "APP_NESTED_NAME": "override-nested"})
+
+        assert config.top == "override"
+        assert config.nested.name == "override-nested"
+
+    def test_env_var_named_after_outer_field_does_not_override_nested(self) -> None:
+        # Setting "APP_NESTED" (the outer field's own env var name) should
+        # not be interpreted as a value for the nested config as a whole —
+        # nested configs are never scalar-coerced.
+        config = Outer.load_from_dict({"APP_NESTED": "not-a-real-value"})
+
+        assert isinstance(config.nested, Nested)
+        assert config.nested.port == 10
+
+
+class TestNestedConfigValidation:
+    def test_invalid_nested_field_raises_constraint_violation(self) -> None:
+        with pytest.raises(ConstraintViolationError):
+            Outer.load_from_dict({"APP_NESTED_PORT": "999"})
+
+    def test_invalid_nested_and_outer_field_aggregate_into_multiple_errors(self) -> None:
+        class OuterWithConstraint(DotEnvConfig):
+            env_prefix = "APP_"
+            top: int = Field(default=1, ge=1, le=10)
+            nested: Nested = Field(default_factory=Nested)
+
+        with pytest.raises(MultipleValidationErrors) as exc_info:
+            OuterWithConstraint.load_from_dict({"APP_TOP": "999", "APP_NESTED_PORT": "999"})
+
+        assert len(exc_info.value.errors) == 2
+        field_names = {e.field_name for e in exc_info.value.errors}
+        assert field_names == {"top", "port"}
+
+    def test_validate_false_skips_nested_validation(self) -> None:
+        config = Outer.load_from_dict({"APP_NESTED_PORT": "999"}, validate=False)
+
+        assert config.nested.port == 999
+
+    def test_multiple_invalid_fields_within_single_nested_config_aggregate(self) -> None:
+        # Exercises the `except MultipleValidationErrors` branch in
+        # _load_fields specifically: a single nested config raising its
+        # own MultipleValidationErrors (>=2 bad fields inside ONE nested
+        # instance) must be caught and flattened into the parent's error
+        # list, not just two independent single-field ValidationErrors
+        # bubbling from two different fields (that's a different code path
+        # — see test_invalid_nested_and_outer_field_aggregate_into_multiple_errors).
+        class TwoConstrainedFields(DotEnvConfig):
+            env_prefix = "APP_TWO_"
+            a: int = Field(default=1, ge=1, le=10)
+            b: int = Field(default=1, ge=1, le=10)
+
+        class OuterWithTwoConstrainedNested(DotEnvConfig):
+            env_prefix = "APP_"
+            nested: TwoConstrainedFields = Field(default_factory=TwoConstrainedFields)
+
+        with pytest.raises(MultipleValidationErrors) as exc_info:
+            OuterWithTwoConstrainedNested.load_from_dict({"APP_TWO_A": "999", "APP_TWO_B": "999"})
+
+        assert len(exc_info.value.errors) == 2
+        field_names = {e.field_name for e in exc_info.value.errors}
+        assert field_names == {"a", "b"}
+
+
+class TestOptionalNestedConfigLimitation:
+    """Pins a KNOWN, UNFIXED gap: `Optional[Nested]` / `Nested | None` does
+    not take the nested-loading branch (it's a Union, not a plain `type`),
+    so it falls through to Optional scalar handling and silently discards
+    the nested config instead of resolving it. This behavior is identical
+    before and after the nested-config-defaults fix — not a regression,
+    but a documented limitation so it isn't rediscovered as a surprise.
+    """
+
+    def test_optional_nested_config_silently_resolves_to_none(self) -> None:
+        class OuterOptional(DotEnvConfig):
+            env_prefix = "APP_"
+            nested: Nested | None = Field(default=None)
+
+        config = OuterOptional.load_from_dict({"APP_NESTED_PORT": "55"})
+
+        # Known limitation: the override is silently discarded rather than
+        # applied — `nested` stays None even though APP_NESTED_PORT was set.
+        assert config.nested is None
+
+
+class TestRequiredNestedConfigField:
+    """Pins the (new, intentional) behavior for a nested config field with
+    no default_factory: field_info.required is not consulted for nested
+    DotEnvConfig fields, so it always resolves via the nested class's own
+    defaults rather than raising MissingFieldError. "Required" is expected
+    to be expressed on the nested class's own fields instead.
+    """
+
+    def test_required_nested_field_resolves_via_nested_defaults(self) -> None:
+        class OuterRequiredNested(DotEnvConfig):
+            env_prefix = "APP_"
+            nested: Nested = Field()  # no default_factory — required=True
+
+        config = OuterRequiredNested.load_from_dict({})
+
+        assert isinstance(config.nested, Nested)
+        assert config.nested.port == 10
+
+
+class TestNestedConfigReload:
+    def test_reload_picks_up_nested_env_changes(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("APP_NESTED_PORT", "20")
+        config = Outer.load()
+        assert config.nested.port == 20
+
+        monkeypatch.setenv("APP_NESTED_PORT", "30")
+        config.reload()
+        assert config.nested.port == 30
+
+
+class TestNestedConfigIntrospection:
+    def test_dict_includes_nested_instance(self) -> None:
+        config = Outer.load_from_dict({})
+
+        as_dict = config.dict()
+        assert isinstance(as_dict["nested"], Nested)
+        assert as_dict["nested"].port == 10
+
+    def test_repr_renders_nested_instance(self) -> None:
+        config = Outer.load_from_dict({})
+
+        rendered = repr(config)
+        assert "Nested(" in rendered
+        assert "port=10" in rendered
+
+
+class TestDeeplyNestedConfig:
+    def test_two_levels_of_nesting_resolve_defaults(self) -> None:
+        class Inner(DotEnvConfig):
+            env_prefix = "APP_MID_INNER_"
+            value: int = Field(default=7)
+
+        class Mid(DotEnvConfig):
+            env_prefix = "APP_MID_"
+            inner: Inner = Field(default_factory=Inner)
+            label: str = Field(default="mid-default")
+
+        class Top(DotEnvConfig):
+            env_prefix = "APP_"
+            mid: Mid = Field(default_factory=Mid)
+
+        config = Top.load_from_dict({})
+
+        assert config.mid.label == "mid-default"
+        assert config.mid.inner.value == 7
+
+    def test_two_levels_of_nesting_apply_overrides(self) -> None:
+        class Inner(DotEnvConfig):
+            env_prefix = "APP_MID_INNER_"
+            value: int = Field(default=7)
+
+        class Mid(DotEnvConfig):
+            env_prefix = "APP_MID_"
+            inner: Inner = Field(default_factory=Inner)
+
+        class Top(DotEnvConfig):
+            env_prefix = "APP_"
+            mid: Mid = Field(default_factory=Mid)
+
+        config = Top.load_from_dict({"APP_MID_INNER_VALUE": "42"})
+
+        assert config.mid.inner.value == 42