Model Validation

This module provides validation functions for model definitions and configuration structure.

Model and configuration structure validation.

This module provides validation functions for: - Model definitions (checking required/optional metadata) - Configuration structure (checking required fields are present)

For value validation (e.g., validate_port, validate_email), see varlord.validators.

exception varlord.model_validation.VarlordError

Bases: Exception

Base exception for varlord errors.

exception varlord.model_validation.ModelDefinitionError(field_name, model_name, reason='invalid')

Bases: VarlordError

Raised when model definition is invalid.

Currently no validation errors are raised - Optional[T] types are supported and automatically recognized as optional fields.

__init__(field_name, model_name, reason='invalid')

Initialize ModelDefinitionError.

Parameters:

• field_name (str) – Name of the field with the issue

• model_name (str) – Name of the model class

• reason (str) – Reason for the error

exception varlord.model_validation.RequiredFieldError(missing_fields, model_name, sources, show_source_help=True, field_infos=None, config_dict=None)

Bases: VarlordError

Raised when required fields are missing from configuration.

This error is raised when a required field is not present in the merged configuration dictionary.

__init__(missing_fields, model_name, sources, show_source_help=True, field_infos=None, config_dict=None)

Initialize RequiredFieldError.

Parameters:

• missing_fields (List[str]) – List of normalized keys of missing required fields

• model_name (str) – Name of the model class

• sources (List[Source]) – List of sources (for generating help examples)

• show_source_help (bool) – Whether to include source mapping help in error message

• field_infos (List[Any] | None) – Optional list of FieldInfo objects for missing fields

• config_dict (Dict[str, Any] | None) – Optional configuration dictionary for enhanced error messages

varlord.model_validation.validate_model_definition(model)

Validate model definition.

Fields are determined as required/optional based on: 1. Type annotation: Optional[T] → optional 2. Default value: has default or default_factory → optional 3. Otherwise → required

Parameters:

model (Type[Any]) – Dataclass model to validate

Example

>>> @dataclass
... class Config:
...     api_key: str = field()  # Required (no default, not Optional)
...     timeout: Optional[int] = field()  # Optional (Optional type)
...     host: str = field(default="localhost")  # Optional (has default)
>>> validate_model_definition(Config)  # OK

varlord.model_validation.validate_config(model, config_dict, sources, show_source_help=True)

Validate that all required fields exist in config_dict.

Parameters:

• model (Type[Any]) – Dataclass model to validate against

• config_dict (Dict[str, Any]) – Configuration dictionary to validate

• sources (List[Source]) – List of sources (for generating help examples)

• show_source_help (bool) – Whether to include source mapping help in error message

Raises:

RequiredFieldError – If any required field is missing from config_dict

Note

Only checks if keys exist in config_dict. Values can be None, empty string, or empty collections - these are all considered valid.

Example

>>> @dataclass
... class Config:
...     api_key: str = field()  # Required by default
>>> validate_config(Config, {}, [])
RequiredFieldError: Required fields are missing...

Functions

validate_model_definition

Validates model definition (currently no validation errors - Optional[T] types are supported).

Fields are automatically determined as required/optional: - Fields without defaults and not Optional[T] are required - Fields with Optional[T] type annotation are optional - Fields with defaults (or default_factory) are optional

Example:

from varlord.model_validation import validate_model_definition
from dataclasses import dataclass, field
from typing import Optional

@dataclass
class Config:
    api_key: str = field()  # Required (no default, not Optional)
    timeout: Optional[int] = field()  # Optional (Optional type)
    host: str = field(default="localhost")  # Optional (has default)

validate_model_definition(Config)  # OK

validate_config

Validates that all required fields exist in a configuration dictionary.

Example:

from varlord.model_validation import validate_config, RequiredFieldError
from dataclasses import dataclass, field

@dataclass
class Config:
    api_key: str = field()

config_dict = {}  # Missing api_key
try:
    validate_config(Config, config_dict, [])
except RequiredFieldError as e:
    print(e)  # Shows missing fields and source help

Exceptions

VarlordError

Base exception for all varlord errors.

ModelDefinitionError

Raised when model definition is invalid (currently not used - Optional[T] types are supported).

RequiredFieldError

Raised when required fields are missing from the configuration dictionary. Includes comprehensive error messages with source mapping help.