dotenvmodel 0.3.2__tar.gz → 0.5.0__tar.gz

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

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

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

@@ -5,6 +5,35 @@ 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)
+
+
+### Features
+
+* add strip, starts_with/ends_with, and custom validator hook to Field ([#36](https://github.com/AZX-PBC-OSS/dotenvmodel/issues/36)) ([8e4210e](https://github.com/AZX-PBC-OSS/dotenvmodel/commit/8e4210e80e5888ef0b769bbf966f486c7b4b526e))
+
 ## [0.3.2](https://github.com/AZX-PBC-OSS/dotenvmodel/compare/v0.3.1...v0.3.2) (2026-07-15)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.3.2
+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,8 @@ 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), choice validation, 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
 - **Zero Runtime Overhead**: All validation happens at startup/load time
@@ -362,6 +363,8 @@ class Config(DotEnvConfig):
     tags: dict[str, str] = Field(default_factory=dict)
 ```
 
+A `str` default for a non-`str` field type is **coerced to the declared type and validated at load** — e.g. a `bool` default of `'false'` becomes `False`, a `SecretStr` default becomes a masked `SecretStr`, and a `PostgresDsn` default is validated (a bad scheme raises at load) with its password redacted in `repr`. Non-`str` defaults (e.g. `int 8000`, `default_factory=list`) and `str` defaults for `str`-typed fields are left untouched. Constraints fire on the coerced default just as they do on env-provided values.
+
 ### Field Aliases
 
 Use a different environment variable name than the field name:
@@ -389,8 +392,44 @@ class Config(DotEnvConfig):
     )
 ```
 
+### String Stripping
+
+Raw environment values often come with stray whitespace or wrapping quotes. Use `strip` to clean string-like values (`str`, `SecretStr`, their `Optional` forms, `str` subclasses like `HttpUrl`, and `Literal["a", "b"]` fields whose every member is `str`) **before** coercion and validation:
+
+```python
+import re
+
+class Config(DotEnvConfig):
+    # Whitespace strip: "  hello  " -> "hello"
+    name: str = Field(strip=True)
+
+    # Char-set strip (str.strip(chars) semantics): ",'hello'," -> "hello"
+    tag: str = Field(strip=",'\"")
+
+    # Regex strip: removes every match, anywhere in the string
+    key: SecretStr = Field(strip=re.compile(r"^['\"]+|['\"]+$"))
+```
+
+Set `strip_strings = True` on the class to strip every string-like field by default, and opt out per field with `strip=False`:
+
+```python
+class Config(DotEnvConfig):
+    strip_strings: bool = True
+
+    name: str = Field()                # stripped (inherits class setting)
+    literal: str = Field(strip=False)  # per-field override wins
+```
+
+Stripping is value processing, not validation: it runs even with `validate=False`, and constraints see the stripped value (e.g. `min_length` checks the final length, and a whitespace-only value for an `Optional[str]` field strips to `""`, which maps to `None`).
+
+For `SecretStr` fields, `strip` runs **before** `url_unquote`, so percent-encoded whitespace (e.g. `%20`) survives stripping — it is removed while still percent-encoded, then unquoted. Use a `re.Pattern` strip if you need to strip decoded whitespace.
+
+> **Warning — use linear-time regex patterns.** Both the `regex` constraint and `strip` with an `re.Pattern` run developer-supplied patterns against env values, which can be operator-controlled. Avoid patterns with nested quantifiers (e.g. `(a+)+`, `(a*)*`) that can cause catastrophic backtracking (ReDoS). Prefer anchored, linear-time patterns.
+
 ## Validation
 
+> **Note — empty vs missing:** `Optional[T]` fields map missing **and** empty values to `None` and skip constraints, while plain `str` preserves empty strings as real values. So "validate only if present" is spelled `str | None = Field(default=None, min_length=...)`.
+
 ### Numeric Validation
 
 ```python
@@ -425,6 +464,10 @@ class Config(DotEnvConfig):
     # Regex pattern
     email: str = Field(regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')
 
+    # Required prefix / suffix
+    client_key: str = Field(starts_with="sk-")
+    signed_token: str = Field(ends_with=".sig")
+
     # Combined constraints
     password: str = Field(
         min_length=8,
@@ -449,6 +492,106 @@ class Config(DotEnvConfig):
     )
 ```
 
+### Custom Validators
+
+For logic that built-in constraints can't express, attach a `validator` hook. It receives the **coerced, constraint-validated** value plus a `ValidatorContext` (field name and env var name), and its return value becomes the final field value — so it can also transform:
+
+```python
+from dotenvmodel import DotEnvConfig, Field, SecretStr, ValidatorContext
+
+def check_api_key(value: SecretStr, ctx: ValidatorContext) -> SecretStr:
+    # The hook receives the coerced value: a SecretStr stays wrapped,
+    # so call get_secret_value() to inspect the plaintext.
+    if not value.get_secret_value().startswith("sk-"):
+        # ValueError/TypeError are wrapped in ConstraintViolationError
+        # and aggregate into MultipleValidationErrors like any other failure
+        raise ValueError(f"{ctx.env_var_name} must start with 'sk-'")
+    return value
+
+class Config(DotEnvConfig):
+    api_key: SecretStr = Field(validator=check_api_key)
+
+    # Transform example: normalize to lowercase
+    region: str = Field(default="us-east-1", validator=lambda v, ctx: v.lower())
+```
+
+Semantics to know:
+
+- The hook receives the **coerced** value. A `SecretStr` stays wrapped — use `get_secret_value()` to inspect the plaintext.
+- Runs **after** built-in constraints, on non-`None` values only, and even with `validate=False` (transformation is part of loading).
+- Built-in constraints are **not** re-run on a transformed value.
+- For sensitive fields (`SecretStr`, DSN types), returning a plain `str` re-wraps it in the declared type so the secret stays masked in `repr`.
+- Returning `None` on a non-`Optional` field raises `TypeCoercionError`.
+- 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.3.2 → dotenvmodel-0.5.0}/README.md

@@ -16,7 +16,8 @@
 - **.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), choice validation, 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
 - **Zero Runtime Overhead**: All validation happens at startup/load time
@@ -334,6 +335,8 @@ class Config(DotEnvConfig):
     tags: dict[str, str] = Field(default_factory=dict)
 ```
 
+A `str` default for a non-`str` field type is **coerced to the declared type and validated at load** — e.g. a `bool` default of `'false'` becomes `False`, a `SecretStr` default becomes a masked `SecretStr`, and a `PostgresDsn` default is validated (a bad scheme raises at load) with its password redacted in `repr`. Non-`str` defaults (e.g. `int 8000`, `default_factory=list`) and `str` defaults for `str`-typed fields are left untouched. Constraints fire on the coerced default just as they do on env-provided values.
+
 ### Field Aliases
 
 Use a different environment variable name than the field name:
@@ -361,8 +364,44 @@ class Config(DotEnvConfig):
     )
 ```
 
+### String Stripping
+
+Raw environment values often come with stray whitespace or wrapping quotes. Use `strip` to clean string-like values (`str`, `SecretStr`, their `Optional` forms, `str` subclasses like `HttpUrl`, and `Literal["a", "b"]` fields whose every member is `str`) **before** coercion and validation:
+
+```python
+import re
+
+class Config(DotEnvConfig):
+    # Whitespace strip: "  hello  " -> "hello"
+    name: str = Field(strip=True)
+
+    # Char-set strip (str.strip(chars) semantics): ",'hello'," -> "hello"
+    tag: str = Field(strip=",'\"")
+
+    # Regex strip: removes every match, anywhere in the string
+    key: SecretStr = Field(strip=re.compile(r"^['\"]+|['\"]+$"))
+```
+
+Set `strip_strings = True` on the class to strip every string-like field by default, and opt out per field with `strip=False`:
+
+```python
+class Config(DotEnvConfig):
+    strip_strings: bool = True
+
+    name: str = Field()                # stripped (inherits class setting)
+    literal: str = Field(strip=False)  # per-field override wins
+```
+
+Stripping is value processing, not validation: it runs even with `validate=False`, and constraints see the stripped value (e.g. `min_length` checks the final length, and a whitespace-only value for an `Optional[str]` field strips to `""`, which maps to `None`).
+
+For `SecretStr` fields, `strip` runs **before** `url_unquote`, so percent-encoded whitespace (e.g. `%20`) survives stripping — it is removed while still percent-encoded, then unquoted. Use a `re.Pattern` strip if you need to strip decoded whitespace.
+
+> **Warning — use linear-time regex patterns.** Both the `regex` constraint and `strip` with an `re.Pattern` run developer-supplied patterns against env values, which can be operator-controlled. Avoid patterns with nested quantifiers (e.g. `(a+)+`, `(a*)*`) that can cause catastrophic backtracking (ReDoS). Prefer anchored, linear-time patterns.
+
 ## Validation
 
+> **Note — empty vs missing:** `Optional[T]` fields map missing **and** empty values to `None` and skip constraints, while plain `str` preserves empty strings as real values. So "validate only if present" is spelled `str | None = Field(default=None, min_length=...)`.
+
 ### Numeric Validation
 
 ```python
@@ -397,6 +436,10 @@ class Config(DotEnvConfig):
     # Regex pattern
     email: str = Field(regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')
 
+    # Required prefix / suffix
+    client_key: str = Field(starts_with="sk-")
+    signed_token: str = Field(ends_with=".sig")
+
     # Combined constraints
     password: str = Field(
         min_length=8,
@@ -421,6 +464,106 @@ class Config(DotEnvConfig):
     )
 ```
 
+### Custom Validators
+
+For logic that built-in constraints can't express, attach a `validator` hook. It receives the **coerced, constraint-validated** value plus a `ValidatorContext` (field name and env var name), and its return value becomes the final field value — so it can also transform:
+
+```python
+from dotenvmodel import DotEnvConfig, Field, SecretStr, ValidatorContext
+
+def check_api_key(value: SecretStr, ctx: ValidatorContext) -> SecretStr:
+    # The hook receives the coerced value: a SecretStr stays wrapped,
+    # so call get_secret_value() to inspect the plaintext.
+    if not value.get_secret_value().startswith("sk-"):
+        # ValueError/TypeError are wrapped in ConstraintViolationError
+        # and aggregate into MultipleValidationErrors like any other failure
+        raise ValueError(f"{ctx.env_var_name} must start with 'sk-'")
+    return value
+
+class Config(DotEnvConfig):
+    api_key: SecretStr = Field(validator=check_api_key)
+
+    # Transform example: normalize to lowercase
+    region: str = Field(default="us-east-1", validator=lambda v, ctx: v.lower())
+```
+
+Semantics to know:
+
+- The hook receives the **coerced** value. A `SecretStr` stays wrapped — use `get_secret_value()` to inspect the plaintext.
+- Runs **after** built-in constraints, on non-`None` values only, and even with `validate=False` (transformation is part of loading).
+- Built-in constraints are **not** re-run on a transformed value.
+- For sensitive fields (`SecretStr`, DSN types), returning a plain `str` re-wraps it in the declared type so the secret stays masked in `repr`.
+- Returning `None` on a non-`Optional` field raises `TypeCoercionError`.
+- 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.5.0/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security vulnerability in dotenvmodel, please report it responsibly.
+
+**Do NOT open a public GitHub issue for security vulnerabilities.**
+
+Instead, please use [GitHub Security Advisories](https://github.com/AZX-PBC-OSS/dotenvmodel/security/advisories/new) to report vulnerabilities privately.
+
+## Response Timeline
+
+- **Acknowledgment:** Within 48 hours
+- **Initial Assessment:** Within 5 business days
+- **Fix or Mitigation:** Depends on severity, typically within 30 days for high-severity issues
+
+## Scope
+
+This policy covers the dotenvmodel Python package and its CI/CD pipeline. Vulnerabilities in third-party dependencies should be reported to their respective maintainers.
+
+## Disclosure
+
+We follow coordinated disclosure. Once a fix is released, we will publish a GitHub Security Advisory with credit to the reporter (unless they prefer to remain anonymous).
+
+## Residual Secret-Exposure Channels
+
+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`); 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.3.2 → dotenvmodel-0.5.0}/docs/guides/fields.md

@@ -39,7 +39,11 @@ class Config(DotEnvConfig):
 | `min_length` | `int \| None` | Minimum string length (inclusive). For `str` and `SecretStr`. |
 | `max_length` | `int \| None` | Maximum string length (inclusive). For `str` and `SecretStr`. |
 | `regex` | `str \| None` | Regular expression pattern the string must match. |
+| `starts_with` | `str \| None` | Required string prefix. For `str` and `SecretStr`. |
+| `ends_with` | `str \| None` | Required string suffix. For `str` and `SecretStr`. |
+| `strip` | `bool \| str \| re.Pattern \| None` | Strip mode applied to the raw string before coercion. `None` inherits the class-level `strip_strings`; `True` strips whitespace; `False` disables; a non-empty `str` is a char set (`value.strip(chars)`); a compiled pattern removes every match. |
 | `choices` | `list[Any] \| None` | List of allowed values (validated after type coercion). |
+| `validator` | `Callable[[Any, ValidatorContext], Any] \| None` | Custom hook receiving the coerced, validated value plus context; its return value becomes the final value. |
 | `min_items` | `int \| None` | Minimum items in a collection (`list`, `set`, `tuple`, `dict`). |
 | `max_items` | `int \| None` | Maximum items in a collection (`list`, `set`, `tuple`, `dict`). |
 | `uuid_version` | `int \| None` | Required UUID version (`1`, `3`, `4`, or `5`). |
@@ -49,7 +53,7 @@ class Config(DotEnvConfig):
 | `require_exists` | `bool` | Whether a `Path` field must point to an existing path. Default: `False`. |
 
 !!! info "Validation parameters"
-    The validation parameters (`ge`, `le`, `gt`, `lt`, `min_length`, `max_length`, `regex`, `choices`, `min_items`, `max_items`, `uuid_version`) are documented in detail in the [Validation guide](validation.md).
+    The validation parameters (`ge`, `le`, `gt`, `lt`, `min_length`, `max_length`, `regex`, `starts_with`, `ends_with`, `choices`, `validator`, `min_items`, `max_items`, `uuid_version`) are documented in detail in the [Validation guide](validation.md).
 
 ---
 
@@ -130,6 +134,9 @@ There are three equivalent ways to mark a field as required. All produce identic
 !!! warning "Never use mutable defaults"
     Using `default=[]` or `default={}` shares the same object across all instances. Always use `default_factory=list` or `default_factory=dict` instead. `Field()` raises a `ValueError` if you specify both `default` and `default_factory`.
 
+!!! note "`str` defaults are coerced and validated for non-`str` field types"
+    A `str` default for a non-`str` field type is coerced to the declared type and run through validation at load — e.g. a `bool` default of `'false'` becomes `False`, a `SecretStr` default becomes a masked `SecretStr`, and a `PostgresDsn` default is validated (a bad scheme raises at load) with its password redacted in `repr`. Non-`str` defaults (e.g. `int 8000`, `default_factory=list`) and `str` defaults for `str`-typed fields are left untouched.
+
 ---
 
 ## Aliases
@@ -186,6 +193,45 @@ See the [Configuration Documentation guide](configuration-docs.md) for examples
 
 ---
 
+## String Stripping
+
+The `strip` parameter cleans raw string values **before** coercion and validation. It applies to string-like fields: `str`, `SecretStr`, their `Optional` forms, `str` subclasses (`HttpUrl`, `PostgresDsn`, `RedisDsn`), and `Literal["a", "b"]` fields whose every member is `str`.
+
+```python
+import re
+
+class Config(DotEnvConfig):
+    # Whitespace strip: "  hello  " -> "hello"
+    name: str = Field(strip=True)
+
+    # Char-set strip (str.strip(chars) semantics): ",'hello'," -> "hello"
+    tag: str = Field(strip=",'\"")
+
+    # Regex strip: removes every match, anywhere in the string
+    key: SecretStr = Field(strip=re.compile(r"^['\"]+|['\"]+$"))
+```
+
+Set the `strip_strings` class attribute to strip every string-like field by default; per-field `strip` overrides it:
+
+```python
+class Config(DotEnvConfig):
+    strip_strings: bool = True
+
+    name: str = Field()                # stripped (inherits class setting)
+    literal: str = Field(strip=False)  # per-field override wins
+```
+
+!!! note "Stripping is processing, not validation"
+    `strip` runs even with `validate=False`, and constraints see the stripped value — `min_length` checks the final length, and a whitespace-only value for an `Optional[str]` field strips to `""`, which maps to `None`.
+
+!!! note "Strip runs before URL-unquoting on `SecretStr`"
+    For `SecretStr` fields, `strip` is applied to the raw value **before** `url_unquote`, so percent-encoded whitespace (e.g. `%20`) survives stripping — it is removed while still percent-encoded, then unquoted. Use a `re.Pattern` strip if you need to strip decoded whitespace.
+
+!!! warning "Use linear-time regex patterns"
+    Both the `regex` constraint and `strip` with an `re.Pattern` run developer-supplied patterns against env values, which can be operator-controlled. Avoid patterns with nested quantifiers (e.g. `(a+)+`, `(a*)*`) that can cause catastrophic backtracking (ReDoS). Prefer anchored, linear-time patterns.
+
+---
+
 ## Path Options
 
 Two parameters control `Path` field behavior:

{dotenvmodel-0.3.2 → 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: