dotenvmodel 0.4.0__tar.gz → 0.5.0__tar.gz

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

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

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.5.0](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.4.0...v0.5.0) (2026-07-21)
+
+
+### Features
+
+* add post_load hook for cross-field validation and normalization ([78bcef1](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/78bcef18b90354ea29050f30c8548a193e78c0e3))
+* add post_load hook for cross-field validation and normalization ([#39](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/39)) ([39241ed](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/39241ed09ca416c38869076cfe6e22a7c94b2d95))
+
+
+### Bug Fixes
+
+* mask hook-authored constraint in sensitive validator errors ([6f99371](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/6f99371c5038d60020c68524c05f766d1bfc0ddd))
+
+
+### Documentation
+
+* correct post_load raise-propagation boundary, document partial reload ([9ec9a00](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/9ec9a00fdfb0e2d455830690489d4c7b5215a92c))
+* document post_load cross-field validation hook ([536c981](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/536c981b201d169a219c49af16e45cdd92202443))
+* post_load discoverability and secrets-warning scope ([895566e](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/895566e365c1d32952b06d59e4063cf7cf2ace8c))
+* qualify post_load claims for validate=False and reload paths ([0786c8d](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/0786c8da115e2d033cad278a97557425ffad4c63))
+* qualify post_load raise propagation for nested ValidationError ([40416b6](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/40416b69c15e33b3234fd8ee6531a743589f4e27))
+
 ## [0.4.0](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.3.2...v0.4.0) (2026-07-20)
 
 

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.4.0
+Version: 0.5.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
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 - **.env.example Generation**: Automatically generate `.env.example` files with type hints, constraints, and examples
 - **File Export**: Save documentation directly to files for integration with build tools and wikis
 - **Environment Prefixes**: Class-level `env_prefix` to namespace environment variables
-- **Validation**: Numeric constraints (ge, le, gt, lt), string constraints (min_length, max_length, regex, starts_with, ends_with), choice validation, custom validator hooks, and collection size constraints (min_items, max_items)
+- **Validation**: Numeric constraints (ge, le, gt, lt), string constraints (min_length, max_length, regex, starts_with, ends_with), choice validation, custom validator hooks, a model-level `post_load` hook for cross-field validation, and collection size constraints (min_items, max_items)
 - **String Stripping**: Per-field and class-level whitespace/char-set/regex stripping of raw values before coercion
 - **Clear Error Messages**: Helpful validation errors that guide you to fixes
 - **Optional Logging**: Built-in logging support to debug configuration loading
@@ -525,6 +525,73 @@ Semantics to know:
 - For sensitive fields, **any** exception from the hook is masked to a generic `ConstraintViolationError` with no exception chaining — the hook's message is never embedded, so a carelessly written hook can't leak the secret. For non-sensitive fields, `str(e)` is embedded in the error message and the original exception is chained.
 - Raise `ConstraintViolationError` directly for a fully custom message on non-sensitive fields (it passes through untouched).
 
+### Cross-Field Validation with `post_load`
+
+Per-field constraints and `validator` hooks see one value at a time. For invariants that span several fields (`lock_lease >= 4 * heartbeat_interval`) or derived values built from multiple inputs (a replica DSN falling back to the primary), override the model-level `post_load()` hook. It runs **once after all fields load cleanly**, on every load path — `load()`, `load_from_dict()`, `reload()`, and nested config loading — and always runs, even with `validate=False` (transformation is part of loading, same as the per-field `validator` hook). The default implementation is a no-op.
+
+```python
+from dotenvmodel import DotEnvConfig, Field, ValidationError
+
+class WorkerConfig(DotEnvConfig):
+    primary_dsn: str = Field(default="postgresql://localhost/primary")
+    replica_dsn: str | None = Field(default=None)
+    heartbeat_interval: int = Field(default=5, ge=1)  # seconds
+    lock_lease: int = Field(default=30, ge=1)         # seconds
+
+    def post_load(self) -> list[ValidationError] | None:
+        # Fix/transform: derived value — fall back to the primary DSN.
+        if self.replica_dsn is None:
+            self.replica_dsn = self.primary_dsn
+
+        # Cross-validate: invariant spanning two fields.
+        if self.lock_lease < 4 * self.heartbeat_interval:
+            return [
+                ValidationError(
+                    field_name="lock_lease",  # tag the primary field
+                    value=self.lock_lease,
+                    error_msg="lock_lease must be >= 4 * heartbeat_interval",
+                )
+            ]
+        return None
+
+config = WorkerConfig.load_from_dict({})
+print(config.replica_dsn)  # postgresql://localhost/primary (fallback applied)
+
+try:
+    WorkerConfig.load_from_dict({"LOCK_LEASE": "10"})  # 10 < 4 * 5
+except ValidationError as e:
+    print(f"{e.field_name}: {e.error_msg}")
+    # lock_lease: lock_lease must be >= 4 * heartbeat_interval
+```
+
+Usage modes (combinable in one body):
+
+- **Fix / transform** — mutate `self`, return `None` (the DSN fallback above).
+- **Cross-validate** — collect violations into a `list[ValidationError]` and return them (the DSN-invariant style above); the library raises them as described below.
+- **Continue** — log or swallow issues internally, return `None`.
+- **Fatal** — `raise`; an exception that is neither `ValidationError` nor `MultipleValidationErrors` propagates unchanged (never wrapped or aggregated), even when raised from a nested config's hook. Use `raise` for unexpected/programming errors and `return` for expected violations.
+
+Semantics to know:
+
+- Return `None` or `[]` → success. Return **one** `ValidationError` → raised directly, its exact type preserved (e.g. `ConstraintViolationError`). Return **several** → raised as `MultipleValidationErrors`.
+- Returned errors are the same `ValidationError` objects field validation produces, so introspection is uniform whether the failure came from a constraint, a per-field `validator`, or `post_load`:
+
+  ```python
+  except MultipleValidationErrors as e:
+      for err in e.errors:
+          print(f"{err.field_name} ({err.env_var_name}): {err.error_msg}")
+  ```
+
+- **Hook-author contract:** tag each returned error with the *primary* field name (`lock_lease` above) and reference the other participating fields in `error_msg`. `env_var_name` defaults to the uppercased field name if not passed.
+- The hook runs **only when every field loaded cleanly** — cross-field checks always see **coerced** values, constraint-validated too unless you loaded with `validate=False` (which skips constraints but still runs the hook). A nested config's hook fires when the nested instance finishes loading, before the parent's hook; its returned errors flatten into the parent's collection. A `ValidationError` or `MultipleValidationErrors` **raised** (rather than returned) by a nested hook is treated the same way — its errors join the parent's collection like nested field failures: a single collected error is re-raised as-is (a solo raised `MultipleValidationErrors` surfaces as its bare member), several aggregate into `MultipleValidationErrors`.
+- `reload()` re-runs the hook against the freshly reloaded state. If the hook (or field validation) fails during `reload()`, the instance may be **partially reloaded** — the same caveat as field errors during reload.
+- The hook does **not** run on bare `Cls()` construction — no load path is involved.
+- If the hook both mutates and returns errors, the load still fails — on `load()`/`load_from_dict()` the half-built instance is discarded and the mutations vanish with it, but on `reload()` the caller already holds the instance, so hook mutations persist even though the reload raised (see the partial-reload caveat above).
+
+> **Warning — keep secrets out of `error_msg` and raised exceptions.** The library redacts the `value` attribute for `SecretStr`/DSN fields when formatting raised errors, but it cannot mask prose you write. Never embed secret values in `error_msg` — and don't interpolate them into exceptions raised from the hook either, since those propagate unmasked.
+
+The pattern follows pydantic's `model_validator(mode="after")` (run after all fields validate; mutate and return `self`) and the zod/t3-env final-schema `.transform()` pattern (one post-hook that can both transform values and accumulate multiple issues).
+
 ## Loading Configuration
 
 ### From Environment Variables

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/README.md

@@ -16,7 +16,7 @@
 - **.env.example Generation**: Automatically generate `.env.example` files with type hints, constraints, and examples
 - **File Export**: Save documentation directly to files for integration with build tools and wikis
 - **Environment Prefixes**: Class-level `env_prefix` to namespace environment variables
-- **Validation**: Numeric constraints (ge, le, gt, lt), string constraints (min_length, max_length, regex, starts_with, ends_with), choice validation, custom validator hooks, and collection size constraints (min_items, max_items)
+- **Validation**: Numeric constraints (ge, le, gt, lt), string constraints (min_length, max_length, regex, starts_with, ends_with), choice validation, custom validator hooks, a model-level `post_load` hook for cross-field validation, and collection size constraints (min_items, max_items)
 - **String Stripping**: Per-field and class-level whitespace/char-set/regex stripping of raw values before coercion
 - **Clear Error Messages**: Helpful validation errors that guide you to fixes
 - **Optional Logging**: Built-in logging support to debug configuration loading
@@ -497,6 +497,73 @@ Semantics to know:
 - For sensitive fields, **any** exception from the hook is masked to a generic `ConstraintViolationError` with no exception chaining — the hook's message is never embedded, so a carelessly written hook can't leak the secret. For non-sensitive fields, `str(e)` is embedded in the error message and the original exception is chained.
 - Raise `ConstraintViolationError` directly for a fully custom message on non-sensitive fields (it passes through untouched).
 
+### Cross-Field Validation with `post_load`
+
+Per-field constraints and `validator` hooks see one value at a time. For invariants that span several fields (`lock_lease >= 4 * heartbeat_interval`) or derived values built from multiple inputs (a replica DSN falling back to the primary), override the model-level `post_load()` hook. It runs **once after all fields load cleanly**, on every load path — `load()`, `load_from_dict()`, `reload()`, and nested config loading — and always runs, even with `validate=False` (transformation is part of loading, same as the per-field `validator` hook). The default implementation is a no-op.
+
+```python
+from dotenvmodel import DotEnvConfig, Field, ValidationError
+
+class WorkerConfig(DotEnvConfig):
+    primary_dsn: str = Field(default="postgresql://localhost/primary")
+    replica_dsn: str | None = Field(default=None)
+    heartbeat_interval: int = Field(default=5, ge=1)  # seconds
+    lock_lease: int = Field(default=30, ge=1)         # seconds
+
+    def post_load(self) -> list[ValidationError] | None:
+        # Fix/transform: derived value — fall back to the primary DSN.
+        if self.replica_dsn is None:
+            self.replica_dsn = self.primary_dsn
+
+        # Cross-validate: invariant spanning two fields.
+        if self.lock_lease < 4 * self.heartbeat_interval:
+            return [
+                ValidationError(
+                    field_name="lock_lease",  # tag the primary field
+                    value=self.lock_lease,
+                    error_msg="lock_lease must be >= 4 * heartbeat_interval",
+                )
+            ]
+        return None
+
+config = WorkerConfig.load_from_dict({})
+print(config.replica_dsn)  # postgresql://localhost/primary (fallback applied)
+
+try:
+    WorkerConfig.load_from_dict({"LOCK_LEASE": "10"})  # 10 < 4 * 5
+except ValidationError as e:
+    print(f"{e.field_name}: {e.error_msg}")
+    # lock_lease: lock_lease must be >= 4 * heartbeat_interval
+```
+
+Usage modes (combinable in one body):
+
+- **Fix / transform** — mutate `self`, return `None` (the DSN fallback above).
+- **Cross-validate** — collect violations into a `list[ValidationError]` and return them (the DSN-invariant style above); the library raises them as described below.
+- **Continue** — log or swallow issues internally, return `None`.
+- **Fatal** — `raise`; an exception that is neither `ValidationError` nor `MultipleValidationErrors` propagates unchanged (never wrapped or aggregated), even when raised from a nested config's hook. Use `raise` for unexpected/programming errors and `return` for expected violations.
+
+Semantics to know:
+
+- Return `None` or `[]` → success. Return **one** `ValidationError` → raised directly, its exact type preserved (e.g. `ConstraintViolationError`). Return **several** → raised as `MultipleValidationErrors`.
+- Returned errors are the same `ValidationError` objects field validation produces, so introspection is uniform whether the failure came from a constraint, a per-field `validator`, or `post_load`:
+
+  ```python
+  except MultipleValidationErrors as e:
+      for err in e.errors:
+          print(f"{err.field_name} ({err.env_var_name}): {err.error_msg}")
+  ```
+
+- **Hook-author contract:** tag each returned error with the *primary* field name (`lock_lease` above) and reference the other participating fields in `error_msg`. `env_var_name` defaults to the uppercased field name if not passed.
+- The hook runs **only when every field loaded cleanly** — cross-field checks always see **coerced** values, constraint-validated too unless you loaded with `validate=False` (which skips constraints but still runs the hook). A nested config's hook fires when the nested instance finishes loading, before the parent's hook; its returned errors flatten into the parent's collection. A `ValidationError` or `MultipleValidationErrors` **raised** (rather than returned) by a nested hook is treated the same way — its errors join the parent's collection like nested field failures: a single collected error is re-raised as-is (a solo raised `MultipleValidationErrors` surfaces as its bare member), several aggregate into `MultipleValidationErrors`.
+- `reload()` re-runs the hook against the freshly reloaded state. If the hook (or field validation) fails during `reload()`, the instance may be **partially reloaded** — the same caveat as field errors during reload.
+- The hook does **not** run on bare `Cls()` construction — no load path is involved.
+- If the hook both mutates and returns errors, the load still fails — on `load()`/`load_from_dict()` the half-built instance is discarded and the mutations vanish with it, but on `reload()` the caller already holds the instance, so hook mutations persist even though the reload raised (see the partial-reload caveat above).
+
+> **Warning — keep secrets out of `error_msg` and raised exceptions.** The library redacts the `value` attribute for `SecretStr`/DSN fields when formatting raised errors, but it cannot mask prose you write. Never embed secret values in `error_msg` — and don't interpolate them into exceptions raised from the hook either, since those propagate unmasked.
+
+The pattern follows pydantic's `model_validator(mode="after")` (run after all fields validate; mutate and return `self`) and the zod/t3-env final-schema `.transform()` pattern (one post-hook that can both transform values and accumulate multiple issues).
+
 ## Loading Configuration
 
 ### From Environment Variables

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/SECURITY.md

@@ -26,5 +26,5 @@ We follow coordinated disclosure. Once a fix is released, we will publish a GitH
 
 dotenvmodel masks secrets in the common display paths (`repr`, error messages, and exception chains for `SecretStr` and DSN-typed fields). Two residual channels remain by design and are the caller's responsibility to mitigate:
 
-- **Traceback frame locals.** When a load-time error is raised, library internals hold the raw env value in local variables (e.g. `raw_value` in `_process_field`). Error-reporting tools that capture locals will record these — Sentry with `include_locals=True`, `pytest --showlocals`, or rich tracebacks. Do not enable local capture for processes that load configs containing secrets.
+- **Traceback frame locals.** When a load-time error is raised, library internals hold the raw env value in local variables (e.g. `raw_value` in `_process_field`); validator-hook errors additionally hold the coerced value in `_run_field_validator`/`_run_sensitive_validator` frame locals. Error-reporting tools that capture locals will record these — Sentry with `include_locals=True`, `pytest --showlocals`, or rich tracebacks. Do not enable local capture for processes that load configs containing secrets.
 - **`FieldInfo.__repr__`.** `FieldInfo.__repr__` prints `default` values verbatim (the raw default stored on the descriptor, before load-time coercion). A `str` default supplied for a `SecretStr` field is visible in `repr(field_info)` and in `describe()`/`generate_env_example()` introspection. Do not log `FieldInfo` reprs, or pass secret defaults as `SecretStr(...)` instances (which mask themselves) rather than plain strings.

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/docs/guides/loading.md

@@ -185,6 +185,10 @@ config.reload(env="prod")
 config.reload(override=False)
 ```
 
+!!! warning "A failed reload can leave the instance partially reloaded"
+
+    Fields are reloaded onto the same instance one at a time, so if validation (or the `post_load` hook) fails mid-reload, fields already reloaded keep their new values while the rest keep the old. If you catch reload errors, treat the instance as suspect — or build a fresh one with `load()` instead.
+
 !!! info "reload() returns the same instance"
 
     `reload()` returns `self`, making it useful for method chaining:

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/docs/guides/validation.md

@@ -264,6 +264,87 @@ Semantics:
 
 ---
 
+## Cross-Field Validation with `post_load`
+
+Constraints and per-field `validator` hooks see one value at a time. For invariants that span several fields (`lock_lease >= 4 * heartbeat_interval`) or derived values built from multiple inputs (a replica DSN falling back to the primary), override the model-level `post_load()` hook. It runs **once after all fields load cleanly**, on every load path — `load()`, `load_from_dict()`, `reload()`, and nested config loading — and always runs, even with `validate=False` (transformation is part of loading, same as the per-field `validator` hook). The default implementation is a no-op.
+
+```python
+from dotenvmodel import DotEnvConfig, Field, ValidationError
+
+class WorkerConfig(DotEnvConfig):
+    primary_dsn: str = Field(default="postgresql://localhost/primary")
+    replica_dsn: str | None = Field(default=None)
+    heartbeat_interval: int = Field(default=5, ge=1)  # seconds
+    lock_lease: int = Field(default=30, ge=1)         # seconds
+
+    def post_load(self) -> list[ValidationError] | None:
+        # Fix / transform: derived value — fall back to the primary DSN.
+        if self.replica_dsn is None:
+            self.replica_dsn = self.primary_dsn
+
+        # Cross-validate: invariant spanning two fields.
+        if self.lock_lease < 4 * self.heartbeat_interval:
+            return [
+                ValidationError(
+                    field_name="lock_lease",  # tag the primary field
+                    value=self.lock_lease,
+                    error_msg="lock_lease must be >= 4 * heartbeat_interval",
+                )
+            ]
+        return None
+```
+
+!!! example "Valid vs Invalid"
+    === "Valid"
+
+        ```python
+        config = WorkerConfig.load_from_dict({})
+        # Fallback applied even though no env vars were set:
+        assert config.replica_dsn == "postgresql://localhost/primary"
+        ```
+
+    === "Invalid"
+
+        ```bash
+        # .env — 10 < 4 * 5
+        LOCK_LEASE=10
+        ```
+
+        ```python
+        # Raises ValidationError:
+        # Field 'lock_lease' validation failed:
+        #   Value: 10
+        #   Error: lock_lease must be >= 4 * heartbeat_interval
+        #   Environment variable: LOCK_LEASE
+        ```
+
+Usage modes (combinable in one body):
+
+| Mode | How | Use for |
+|------|-----|---------|
+| Fix / transform | Mutate `self`, return `None` | Derived values, fallbacks, normalization |
+| Cross-validate | Return `list[ValidationError]` | Invariants spanning multiple fields |
+| Continue | Log or swallow issues internally, return `None` | Non-fatal drift you only want to observe |
+| Fatal | `raise` | Unexpected/programming errors — an exception that is neither `ValidationError` nor `MultipleValidationErrors` propagates unchanged (never wrapped or aggregated), even from a nested hook |
+
+Semantics:
+
+- Return `None` or `[]` → success. One returned error → raised directly, its exact type preserved (e.g. `ConstraintViolationError`). Several → raised as `MultipleValidationErrors`.
+- Returned errors are the same `ValidationError` objects field validation produces, so introspection is uniform: iterating `MultipleValidationErrors.errors` yields `field_name`, `env_var_name`, `value`, and `error_msg` per error, whether the failure came from a constraint, a per-field `validator`, or `post_load`. See [Error Handling](error-handling.md).
+- The hook runs **only when every field loaded cleanly** — cross-field checks always see **coerced** values; constraint validation has also been applied unless you loaded with `validate=False` (which skips constraints but still runs the hook). A nested config's hook fires when the nested instance finishes loading, before the parent's hook; its returned errors flatten into the parent's collection. A `ValidationError` or `MultipleValidationErrors` **raised** (rather than returned) by a nested hook is treated the same way — its errors join the parent's collection like nested field failures: a single collected error is re-raised as-is (a solo raised `MultipleValidationErrors` surfaces as its bare member), several aggregate into `MultipleValidationErrors`.
+- **Hook-author contract:** tag each returned error with the *primary* field name (`lock_lease` above) and reference the other participating fields in `error_msg`. `env_var_name` defaults to the uppercased field name if not passed.
+
+!!! warning "Keep secrets out of error messages"
+    The library redacts the `value` attribute for `SecretStr`/DSN fields when formatting raised errors, but it cannot mask prose you write. Never embed secret values in `error_msg` — and don't interpolate them into exceptions raised from the hook either, since those propagate unmasked.
+
+!!! note "When the hook does not run"
+    `post_load()` does not run on bare `Cls()` construction (no load path is involved), and it does not run if any field fails to load. On `reload()` the hook re-runs against the freshly reloaded state; if it (or field validation) fails mid-reload, the instance may be **partially reloaded** — the same caveat as field errors during reload.
+
+!!! tip "Pattern lineage"
+    The hook follows pydantic's `model_validator(mode="after")` (run after all fields validate; mutate and return `self`) and the zod/t3-env final-schema `.transform()` pattern (one post-hook that can both transform values and accumulate multiple issues).
+
+---
+
 ## Collection Size Constraints
 
 The `min_items` and `max_items` parameters constrain the number of items in `list`, `set`, `tuple`, and `dict` fields.

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/docs/index.md

@@ -45,7 +45,8 @@ safety, validation, and automatic `.env` loading — with only one runtime depen
 
     Numeric constraints (`ge`, `le`, `gt`, `lt`), string constraints (`min_length`,
     `max_length`, `regex`, `starts_with`, `ends_with`), choice validation, custom
-    `validator` hooks, string `strip` processing, and collection size constraints.
+    `validator` hooks, a model-level `post_load` hook for cross-field validation,
+    string `strip` processing, and collection size constraints.
 
 -   :material-file-document-multiple:{ .lg .middle } **Configuration Documentation**
 

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/dotenvmodel/__init__.py

@@ -21,6 +21,8 @@ Public API:
     - `Field`: Define fields with defaults, validation, and aliases
     - `Required`: Sentinel for required fields (alternative to `Field()`)
     - `ValidatorContext`: Context passed to `Field(validator=...)` hooks
+    - `DotEnvConfig.post_load`: Model-level hook for cross-field validation
+      and normalization after loading
     - `SecretStr`: String type that hides values in logs
     - `HttpUrl`, `PostgresDsn`, `RedisDsn`: URL/DSN types with validation
     - `Json`: Type for parsing JSON strings
@@ -32,7 +34,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/dotenvmodel/config.py

@@ -53,15 +53,20 @@ def _run_sensitive_validator(
     """Run a validator hook for a sensitive-typed field.
 
     Any hook failure (``ConstraintViolationError`` or any other ``Exception``)
-    is masked: the hook's exception text — which may embed the plaintext secret
-    or a URL password — is never embedded, and the masked error is raised
-    outside the ``except`` block with ``__cause__``/``__context__`` cleared so
-    the hook exception appears nowhere in the chain or traceback frame locals.
-    A plain-``str`` return value is re-wrapped in the declared type so the
-    secret stays masked in ``repr``.
+    is masked: nothing from the hook exception — message, ``constraint``, or
+    any other text, any of which may embed the plaintext secret or a URL
+    password — is carried into the raised error, which uses a generic
+    ``validator=<name>`` constraint and message. The masked error is raised
+    outside the ``except`` block with ``__cause__``/``__context__`` cleared
+    (an empty chain). A plain-``str`` return value is re-wrapped in the
+    declared type so the secret stays masked in ``repr``.
+
+    Note:
+        Traceback frame locals across the load path still reference the live
+        value (this frame's ``value``, caller frames' ``raw_value`` and
+        ``value``), so locals-capturing error reporting must not be enabled
+        for processes loading secrets — see SECURITY.md.
     """
-    constraint = f"validator={name}"
-    cve_constraint: str | None = None
     failed = False
     result: Any = None
     try:
@@ -73,30 +78,18 @@ def _run_sensitive_validator(
         # construction is caught below and masked.
         if isinstance(result, str) and not isinstance(result, unwrapped_type):
             result = unwrapped_type(result)
-    except ConstraintViolationError as e:
-        cve_constraint = e.constraint
-        failed = True
-        del e
     except Exception:
-        # Drop the bound exception entirely; raise the masked error outside the
-        # except so __context__ stays None.
+        # Carry nothing over from the hook exception — message, constraint, or
+        # any other text may embed the plaintext secret. Raising the masked
+        # error outside the except keeps __context__ None.
         failed = True
 
     if failed:
-        report_value = _masked_report_value(value)
-        if cve_constraint is not None:
-            raise ConstraintViolationError(
-                field_name=field_name,
-                value=report_value,
-                constraint=cve_constraint,
-                error_msg=f"validator={name} rejected the value",
-                env_var_name=env_var_name,
-            ) from None
         raise ConstraintViolationError(
             field_name=field_name,
-            value=report_value,
-            constraint=constraint,
-            error_msg="Custom validator rejected the value",
+            value=_masked_report_value(value),
+            constraint=f"validator={name}",
+            error_msg=f"validator={name} rejected the value",
             env_var_name=env_var_name,
         ) from None
 
@@ -218,6 +211,29 @@ def _run_field_validator(
     )
 
 
+def _raise_collected(errors: list[ValidationError] | None) -> None:
+    """Raise collected validation errors, preserving single-error types.
+
+    Shared by the field-error loop and the `post_load` hook in
+    `DotEnvConfig._load_fields`. A single error is raised unchanged so its
+    specific type (e.g. `MissingFieldError`, `ConstraintViolationError`)
+    reaches the caller; several are aggregated into
+    `MultipleValidationErrors`. `None` and an empty list both mean success.
+
+    Args:
+        errors: Collected errors, or `None` when the source reports success.
+
+    Raises:
+        ValidationError: The single collected error, raised unchanged.
+        MultipleValidationErrors: If two or more errors were collected.
+    """
+    if not errors:
+        return
+    if len(errors) == 1:
+        raise errors[0]
+    raise MultipleValidationErrors(errors)
+
+
 class DotEnvConfig(metaclass=ConfigMeta):
     """Base class for type-safe environment configuration.
 
@@ -458,10 +474,8 @@ class DotEnvConfig(metaclass=ConfigMeta):
                 # it escape uncaught past the aggregation loop.
                 errors.extend(e.errors)
 
-        if errors:
-            if len(errors) == 1:
-                raise errors[0]
-            raise MultipleValidationErrors(errors)
+        _raise_collected(errors)
+        _raise_collected(self.post_load())
 
     @classmethod
     def load(
@@ -667,6 +681,72 @@ class DotEnvConfig(metaclass=ConfigMeta):
         instance._loaded = True
         return instance
 
+    def post_load(self) -> list[ValidationError] | None:
+        """Normalize derived values and run cross-field validation after loading.
+
+        Runs once after all fields are loaded and validated, on every load
+        path: `load()`, `load_from_dict()`, `reload()`, and nested config
+        loading. Always runs, including with `validate=False` (consistent
+        with the per-field `validator` hook: transformation is part of
+        loading). The default implementation is a no-op.
+
+        Usage modes (combinable in one body):
+
+        - Fix / transform: mutate `self` (e.g. apply fallback values),
+          return `None`.
+        - Cross-validate: return a list of `ValidationError`. One error is
+          raised directly; several are raised as `MultipleValidationErrors`.
+        - Continue: log or swallow issues internally, return `None`.
+        - Fatal: raise; an exception that is neither `ValidationError`
+          nor `MultipleValidationErrors` propagates unchanged.
+
+        Tag each returned error with the primary field name and reference
+        other participating fields in `error_msg`. Do not embed secret
+        values in `error_msg` — the library redacts the `value` attribute
+        but cannot mask prose. The same applies to exceptions raised from
+        the hook: they propagate unmasked, so never interpolate secrets
+        into a raised exception's message. The hook runs only when every
+        field loaded cleanly, and does not run on bare `Cls()` construction.
+
+        Returns:
+            `None` or an empty list on success; a list of `ValidationError`
+            describing cross-field violations otherwise.
+
+        Example:
+            ```python
+            class DatabaseConfig(DotEnvConfig):
+                primary_dsn: str = Field()
+                replica_dsn: str | None = Field(default=None)
+                pool_min: int = Field(default=1)
+                pool_max: int = Field(default=10)
+
+                def post_load(self) -> list[ValidationError] | None:
+                    # Fix / transform: fall back to the primary DSN.
+                    if self.replica_dsn is None:
+                        self.replica_dsn = self.primary_dsn
+
+                    # Cross-validate: pool bounds must stay coherent.
+                    if self.pool_min > self.pool_max:
+                        return [
+                            ValidationError(
+                                field_name="pool_min",
+                                value=self.pool_min,
+                                error_msg="pool_min must be <= pool_max",
+                            )
+                        ]
+                    return None
+            ```
+
+        See Also:
+            - [`load`][dotenvmodel.config.DotEnvConfig.load]: Triggers this hook.
+            - [`reload`][dotenvmodel.config.DotEnvConfig.reload]: Re-runs this hook.
+            - [`Field`][dotenvmodel.fields.Field]: Per-field `validator` hook for
+              single-field validation and transformation.
+            - [`MultipleValidationErrors`][dotenvmodel.exceptions.MultipleValidationErrors]:
+              Raised when this hook returns several errors.
+        """
+        return None
+
     def dict(self) -> dict[str, Any]:
         """Return configuration as a dictionary with actual values.
 

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/dotenvmodel/describe/formatters.py

@@ -10,7 +10,7 @@ from dataclasses import dataclass
 from datetime import timedelta
 from enum import Enum
 from pathlib import Path
-from typing import Any, Union, get_args, get_origin
+from typing import TYPE_CHECKING, Any, Union, get_args, get_origin
 
 from typing_extensions import TypeForm
 
@@ -19,6 +19,9 @@ from dotenvmodel.coercion import is_string_like_type
 from dotenvmodel.fields import _MISSING, FieldInfo, _validator_name
 from dotenvmodel.types import BaseDsn, SecretStr
 
+if TYPE_CHECKING:
+    from dotenvmodel.config import DotEnvConfig
+
 # Maximum column widths to prevent unbounded table growth
 MAX_WIDTHS = {
     0: 40,  # ENV Variable
@@ -349,7 +352,7 @@ def format_constraints(
     return ", ".join(constraints) if constraints else "-"
 
 
-def _union_members(field_type: TypeForm[Any]) -> list[Any]:
+def _union_members(field_type: TypeForm[Any] | types.UnionType) -> list[Any]:
     """Return the non-None members of an Optional/Union, else ``[field_type]``.
 
     Handles multi-member unions (``PostgresDsn | RedisDsn | None``) so a DSN or
@@ -361,7 +364,7 @@ def _union_members(field_type: TypeForm[Any]) -> list[Any]:
     return [field_type]
 
 
-def _is_type_in_union(field_type: TypeForm[Any], target: type) -> bool:
+def _is_type_in_union(field_type: TypeForm[Any] | types.UnionType, target: type) -> bool:
     """True if any member of ``field_type`` is a subclass of ``target``."""
     return any(isinstance(m, type) and issubclass(m, target) for m in _union_members(field_type))
 
@@ -422,7 +425,7 @@ def format_default(field_info: FieldInfo, field_type: TypeForm[Any], truncate: b
 
 
 def describe_class(
-    config_cls: type,  # type: ignore[type-arg]
+    config_cls: type[DotEnvConfig],
     truncate: bool = True,
 ) -> tuple[str, str, list[FieldDescription]]:
     """Extract field descriptions from a config class.

{dotenvmodel-0.4.0 → dotenvmodel-0.5.0}/dotenvmodel/exceptions.py

@@ -295,7 +295,8 @@ class MultipleValidationErrors(DotEnvModelError):
             if error.value is not None:
                 msg += f"   Value: {_value_repr(error.value)}\n"
             msg += f"   Environment variable: {error.env_var_name}\n"
-            if hasattr(error, "constraint") and error.constraint is not None:  # type: ignore[attr-defined]
-                msg += f"   Constraint: {error.constraint}\n"  # type: ignore[attr-defined]
+            constraint = getattr(error, "constraint", None)
+            if constraint is not None:
+                msg += f"   Constraint: {constraint}\n"
             msg += "\n"
         return msg.rstrip()