Use Pydantic for validation of env config

[tomschr]

Situation

Currently, the configuration for the docbuild environment isn't validated against errors.
The issue about docbuild app config is described in #88.

Use Case

Having a mechanism for validating the content of the env config helps in discovering configuration problems like typos or improper types.

Possible Implementation

Use Pydantic and create a hierarchy of classes. Each class serves as a "section" in the TOML file. It's properties are the respective keys with their values (see below as an example).

• Prefer Field() for each attribute.
• Use title, description, and possible examples as arguments in Field. They are used in the documentation.
• Add an additional docstring after Field() (yes, it's a weird requirement for our documentation build tool)

Draft of the env config model

"""Pydantic models for application and environment configuration."""

from pathlib import Path
from typing import Annotated

from pydantic import BaseModel, Field, HttpUrl, IPvAnyAddress

from ..models.language import LanguageCode

# A type for domain names, validated with a regex.
# This ensures the string looks like a valid domain, but doesn't do a DNS lookup.
# TODO: Add title, description, examples
DomainName = Annotated[
    str,
    Field(
        pattern=r"^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}$"
    ),
]


class Env_Server(BaseModel):
    """Defines server settings."""

    # TODO: Add Field and title, description, examples
    name: str
    role: str
    host: IPvAnyAddress | DomainName
    port: int | None = None
    enable_mail: bool


class Env_GeneralConfig(BaseModel):
    """Defines general configuration."""

    # TODO: Add Field and title, description, examples
    default_lang: LanguageCode
    languages: list[LanguageCode]
    canonical_url_domain: HttpUrl


class Env_TmpPaths(BaseModel):
    """Defines temporary paths."""

    # TODO: Add Field and title, description, examples
    tmp_base_path: Path
    tmp_path: Path
    tmp_deliverable_path: Path
    tmp_build_dir: Path
    tmp_out_path: Path
    log_path: Path
    tmp_deliverable_name: str


class Env_TargetPaths(BaseModel):
    """Defines target paths."""

    # TODO: Add Field and title, description, examples
    target_path: str
    backup_path: Path


class Env_PathsConfig(BaseModel):
    """Defines various application paths."""

    # TODO: Add Field and title, description, examples
    config_dir: Path
    repo_dir: Path
    temp_repo_dir: Path
    base_cache_dir: Path
    cache_dir: Path
    meta_cache_dir: Path
    tmp: TmpPaths
    target: Env_TargetPaths


class EnvConfig(BaseModel):
    """Root model for the environment configuration (env.toml)."""

    # TODO: Add Field and title, description, examples
    server: Env_Server
    config: Env_GeneralConfig
    paths: Env_PathsConfig
    xslt_params: dict[str, str | int] = Field(alias='xslt-params')

Additionally, we need to rethink how we want to deal with the placeholders. This can be done in two ways:

1. Load the raw data, replace the placeholders, and pass the structure to EnvConfig.
2. Let Pydantic's method model_validator deal with the replacement inside.

To make it possible, you need to add in EnvConfig:

from copy import deepcopy
from pydantic import BaseModel, Field, HttpUrl, IPvAnyAddress, model_validator

class EnvConfig(BaseModel):
    # ...
    @model_validator(mode='before')
    @classmethod
    def _resolve_placeholders(cls, data: Any) -> Any:
        """Resolve placeholders before any other validation."""
        if isinstance(data, dict):
            # Make a deep copy to avoid modifying the original input data,
            # as replace_placeholders works in-place.
            return replace_placeholders(deepcopy(data))
        return data

The execution flow looks like this:

1. You call EnvConfig.model_validate(raw_config_dict).
2. Pydantic sees the @model_validator(mode='before') on EnvConfig.
3. It calls our _resolve_placeholders method, passing it the raw_config_dict.
4. Our method calls replace_placeholders(raw_config_dict), which walks the entire dictionary and resolves all placeholders in one pass.
5. Pydantic then takes the processed dictionary (with all placeholders resolved) and begins its normal validation, creating instances of Env_ServerConfig etc., from the clean data.

[tomschr]

I've split this issue in env config (this issue) and app config (#88).

[sushant-suse]

Proposed Plan to Implement Environment Configuration Validation

The proposed solution using a Pydantic model hierarchy is the correct and most reliable approach for validating the complex environment configuration (env.toml). This ensures strict type checking and catches user errors (like typos) at application startup.

1. Architectural Decision: Precise Validation

We will use a hierarchy of Pydantic classes (Env_Server, Env_PathsConfig, etc.) to enforce a precise schema for every section and key in the env.toml.

• Enforcement: To prevent user typos (e.g., misspellings like hostt for host), we will configure all core models with ConfigDict(extra='forbid'). This forces users to adhere strictly to the defined schema.
• Documentation: This hierarchical structure guarantees that tools like Sphinx can automatically generate complete and accurate configuration reference documentation via autodoc.

2. Placeholder Resolution Strategy (Model Validator)

The choice to handle placeholder resolution inside the Pydantic model is superior to external processing.

• Method: We will use the proposed @model_validator(mode='before') on the root EnvConfig model.
• Execution Flow: This ensures that the custom _resolve_placeholders method runs first, replacing all {placeholders} with concrete values, before Pydantic attempts its type coercion (e.g., converting a placeholder string into a validated Path or HttpUrl object). This separation of concerns is clean and idiomatic to Pydantic.

3. Implementation Steps

1. Create Models: Define the entire hierarchy of models (Env_Server, Env_PathsConfig, etc.) as drafted, placing them in a dedicated file (e.g., src/docbuild/models/config_model/env.py).
2. Integrate Placeholder Resolver: Implement the _resolve_placeholders method in EnvConfig to call the existing replace_placeholders utility.
3. Update CLI: Modify the application entry point to pass the raw environment configuration dictionary to EnvConfig.model_validate(raw_data).

[tomschr]

Sounds great! Please continue. 👍