Skip to content

Validation

Field validation logic for checking constraints on configuration values.

validation

Field validation logic for dotenvmodel.

validate_field 

validate_field(
    field_name: str,
    value: Any,
    field_info: FieldInfo,
    env_var_name: str,
) -> None

Validate a field value against its constraints.

When to use
  • Called automatically by DotEnvConfig.load() after type coercion
  • Call directly if you need to validate a value outside of config loading
Validates
  • Numeric constraints: ge, le, gt, lt (for int, float, Decimal)
  • String constraints: min_length, max_length, regex (for str, SecretStr)
  • Choice validation: choices (for any type)
  • Collection size: min_items, max_items (for list, set, tuple, dict)
  • UUID version: uuid_version (for UUID)

Parameters:

Name Type Description Default
field_name str

Name of the field being validated (for error messages)

 required
value Any

Value to validate (already type-coerced)

 required
field_info FieldInfo

Field metadata containing validation constraints

 required
env_var_name str

Name of the environment variable (for error messages)

 required

Raises:

Type Description
ConstraintViolationError

If any constraint is violated
See Also
Source code in dotenvmodel/validation.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def validate_field(field_name: str, value: Any, field_info: FieldInfo, env_var_name: str) -> None:
    """Validate a field value against its constraints.

    When to use:
        - Called automatically by `DotEnvConfig.load()` after type coercion
        - Call directly if you need to validate a value outside of config loading

    Validates:
        - Numeric constraints: `ge`, `le`, `gt`, `lt` (for int, float, Decimal)
        - String constraints: `min_length`, `max_length`, `regex` (for str, SecretStr)
        - Choice validation: `choices` (for any type)
        - Collection size: `min_items`, `max_items` (for list, set, tuple, dict)
        - UUID version: `uuid_version` (for UUID)

    Args:
        field_name: Name of the field being validated (for error messages)
        value: Value to validate (already type-coerced)
        field_info: Field metadata containing validation constraints
        env_var_name: Name of the environment variable (for error messages)

    Raises:
        ConstraintViolationError: If any constraint is violated

    See Also:
        - [`FieldInfo`][dotenvmodel.fields.FieldInfo]: Contains all constraint definitions.
        - [`ConstraintViolationError`][dotenvmodel.exceptions.ConstraintViolationError]: Exception on failure.
    """
    # Skip validation for None values (handled by type coercion)
    if value is None:
        return

    # Numeric validation (int, float, Decimal)
    if isinstance(value, (int, float, Decimal)):
        _validate_numeric(field_name, value, field_info, env_var_name)

    # String validation (including SecretStr)
    if isinstance(value, str):
        _validate_string(field_name, value, field_info, env_var_name)
    elif isinstance(value, SecretStr):
        # Check the plaintext for length/regex, but report the masked SecretStr.
        # No plaintext-bearing exception is ever constructed, so nothing can
        # leak via the exception chain (__cause__/__context__).
        _validate_string(
            field_name,
            value.get_secret_value(),
            field_info,
            env_var_name,
            report_value=value,
        )

    # Choice validation (works for any type)
    if field_info.choices is not None:
        _validate_choices(field_name, value, field_info, env_var_name)

    # Collection size validation (for list, set, tuple, dict)
    if isinstance(value, (list, set, tuple, dict)):
        _validate_collection_size(field_name, value, field_info, env_var_name)

    # UUID version validation
    if isinstance(value, UUID):
        _validate_uuid_version(field_name, value, field_info, env_var_name)