dotenvmodel 0.3.2__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.2 → dotenvmodel-0.4.0}/CHANGELOG.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotenvmodel
-Version: 0.3.2
+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

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

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.2 → 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.2 → 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.2 → 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.2 → 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.2"
+__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",

{dotenvmodel-0.3.2 → dotenvmodel-0.4.0}/dotenvmodel/coercion.py

@@ -2,6 +2,7 @@
 
 import inspect
 import logging
+import re
 import types
 from datetime import datetime, timedelta
 from decimal import Decimal
@@ -14,6 +15,7 @@ from typing_extensions import TypeForm
 
 from dotenvmodel._constants import LOGGER_NAME
 from dotenvmodel.exceptions import TypeCoercionError
+from dotenvmodel.types import SecretStr
 
 if TYPE_CHECKING:
     from dotenvmodel.fields import FieldInfo
@@ -21,6 +23,73 @@ if TYPE_CHECKING:
 logger = logging.getLogger(LOGGER_NAME)
 
 
+def unwrap_optional(field_type: TypeForm[Any]) -> TypeForm[Any]:
+    """Return the non-None member of an ``Optional[T]`` / ``T | None`` type.
+
+    ``Optional[T]`` and ``T | None`` resolve to ``T``. Any other type —
+    including non-Optional Unions with multiple non-None members, which this
+    library rejects elsewhere — is returned unchanged.
+
+    Args:
+        field_type: The field's type annotation
+
+    Returns:
+        The Optional-unwrapped type, or ``field_type`` itself when it is not
+        a single-member Optional.
+    """
+    origin = get_origin(field_type)
+    if origin is types.UnionType or origin is Union:
+        non_none = [arg for arg in get_args(field_type) if arg is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return field_type
+
+
+def is_string_like_type(field_type: TypeForm[Any]) -> bool:
+    """Check whether a field type is string-like (eligible for ``strip``).
+
+    Unwraps ``Optional[T]`` and checks for ``str``, ``SecretStr``, a
+    ``str`` subclass (e.g. ``HttpUrl``, ``PostgresDsn``, ``RedisDsn``), or a
+    ``Literal[...]`` whose every argument is ``str`` (e.g.
+    ``Literal["dev", "prod"]``), so that strip is applied before coercion.
+
+    Args:
+        field_type: The field's type annotation
+
+    Returns:
+        True if the field holds a string-like value
+    """
+    unwrapped = unwrap_optional(field_type)
+    if inspect.isclass(unwrapped):
+        return issubclass(unwrapped, (str, SecretStr))
+    origin = get_origin(unwrapped)
+    if origin is Literal:
+        return all(isinstance(arg, str) for arg in get_args(unwrapped))
+    return False
+
+
+def apply_strip(value: str, mode: bool | str | re.Pattern[str]) -> str:
+    """Apply a strip mode to a raw string value.
+
+    Args:
+        value: The raw string from the environment
+        mode: Strip mode — ``True`` for whitespace stripping, ``False`` for no
+            stripping, a non-empty ``str`` for char-set stripping
+            (``value.strip(chars)``), or a compiled ``re.Pattern`` to remove
+            every match (``pattern.sub("", value)``)
+
+    Returns:
+        The stripped string
+    """
+    if mode is False:
+        return value
+    if mode is True:
+        return value.strip()
+    if isinstance(mode, str):
+        return value.strip(mode)
+    return mode.sub("", value)
+
+
 def coerce_value(
     field_name: str,
     value: str | None,