dotenvmodel 0.3.1__tar.gz → 0.4.0__tar.gz

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

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

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

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.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)
+
+
+### 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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.3.1
+Version: 0.4.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, 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,39 @@ 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).
+
 ## Loading Configuration
 
 ### From Environment Variables
@@ -1036,6 +1112,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 +1364,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.4.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, 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,39 @@ 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).
+
 ## Loading Configuration
 
 ### From Environment Variables
@@ -1008,6 +1084,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 +1336,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.4.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`). 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.1 → dotenvmodel-0.4.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.1 → dotenvmodel-0.4.0}/docs/guides/validation.md

@@ -6,6 +6,9 @@ Constraints are defined as parameters to `Field()`. This page covers every suppo
 
 For the complete API reference, see [Validation API](../api-reference/validation.md).
 
+!!! note "Empty vs missing values"
+    `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 Constraints
@@ -95,6 +98,8 @@ String constraints apply to `str` and `SecretStr` fields.
 | `min_length` | Minimum string length (inclusive) |
 | `max_length` | Maximum string length (inclusive) |
 | `regex` | Regular expression pattern the string must match (uses `re.match`) |
+| `starts_with` | Required string prefix |
+| `ends_with` | Required string suffix |
 
 ### Examples
 
@@ -112,6 +117,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,
@@ -159,6 +168,9 @@ class Config(DotEnvConfig):
 !!! note "Regex uses `re.match`"
     The `regex` constraint uses `re.match`, which anchors at the **start** of the string. Include `^` and `$` in your pattern to anchor both ends, as shown in the examples above.
 
+!!! warning "Use linear-time patterns (ReDoS)"
+    `regex` 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.
+
 ---
 
 ## Choice Validation
@@ -214,6 +226,44 @@ class Config(DotEnvConfig):
 
 ---
 
+## Custom Validators
+
+For logic the built-in constraints can't express, attach a `validator` hook. It receives the **coerced, built-in-constraint-validated** value plus a `ValidatorContext` (field name and resolved env var name), and its return value becomes the final field value — so a hook 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:
+
+- 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, not validation).
+- Built-in constraints are **not** re-run on a transformed value (pydantic "after"-mode semantics).
+- 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`.
+- A `ValueError` or `TypeError` from the hook is wrapped in `ConstraintViolationError` with `constraint="validator=<fn name>"`.
+- Raise `ConstraintViolationError` directly for a fully custom message on non-sensitive fields (passed through untouched).
+
+!!! warning "Sensitive-field leak prevention"
+    For sensitive fields (`SecretStr`, DSN types), **any** exception from the hook is masked to a generic `ConstraintViolationError` with no exception chaining — the hook's exception text is never embedded in the error or its `__cause__`/`__context__` chain, so a carelessly written hook cannot leak the secret or URL password into logs. For non-sensitive fields, `str(e)` is embedded in the error message and the original exception is chained.
+
+---
+
 ## Collection Size Constraints
 
 The `min_items` and `max_items` parameters constrain the number of items in `list`, `set`, `tuple`, and `dict` fields.

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

@@ -44,7 +44,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`), choice validation, and collection size constraints.
+    `max_length`, `regex`, `starts_with`, `ends_with`), choice validation, custom
+    `validator` hooks, string `strip` processing, and collection size constraints.
 
 -   :material-file-document-multiple:{ .lg .middle } **Configuration Documentation**
 

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

@@ -20,6 +20,7 @@ Public API:
     - `DotEnvConfig`: Base class for type-safe configuration
     - `Field`: Define fields with defaults, validation, and aliases
     - `Required`: Sentinel for required fields (alternative to `Field()`)
+    - `ValidatorContext`: Context passed to `Field(validator=...)` hooks
     - `SecretStr`: String type that hides values in logs
     - `HttpUrl`, `PostgresDsn`, `RedisDsn`: URL/DSN types with validation
     - `Json`: Type for parsing JSON strings
@@ -31,7 +32,7 @@ Public API:
       Exception hierarchy
 """
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"
 __author__ = "AZX, PBC."
 __email__ = "oss@azx.io"
 __license__ = "MIT"
@@ -48,7 +49,7 @@ from dotenvmodel.exceptions import (
     TypeCoercionError,
     ValidationError,
 )
-from dotenvmodel.fields import Field, Required
+from dotenvmodel.fields import Field, Required, ValidatorContext
 from dotenvmodel.logging_config import configure_logging, disable_logging
 from dotenvmodel.types import (
     HttpUrl,
@@ -74,6 +75,7 @@ __all__ = [
     "SecretStr",
     "TypeCoercionError",
     "ValidationError",
+    "ValidatorContext",
     "__version__",
     "configure_logging",
     "describe_configs",