Validator

Env validator.

======================================================================================================================== Name: core/env/validator.py Description: Validates the runtime environment against the env_spec.yaml contract. Reports missing required variables, type mismatches, and secret exposure with structured, human-readable output via the project logger.

Copyright ©2026 PyModeller. All rights reserved.

Classes:

Name	Description
EnvValidationError	Raised when required environment variables are missing or malformed.
EnvValidationResult	Aggregated result of a full environment validation run.
EnvValidator	Validates the running process environment against an EnvSpec.
IssueKind	Issue kind.
VarIssue	A single validation problem for one environment variable.

Functions:

Name	Description
validate_env	Load the env spec and validate the current environment in one call.

EnvValidationError

Bases: RuntimeError

Raised when required environment variables are missing or malformed.

Methods:

Name	Description
__init__	Initialise the error with a full validation result.

__init__

__init__(result: EnvValidationResult) -> None

Initialise the error with a full validation result.

EnvValidationResult dataclass

Aggregated result of a full environment validation run.

Attributes:

Name	Type	Description
empty_required	list[VarIssue]	Variables that are required but set to an empty string.
missing	list[VarIssue]	Variables that are required but completely absent from the environment.
ok	bool	True when no issues were found.
type_errors	list[VarIssue]	Variables whose value cannot be coerced to the declared type.

empty_required property

empty_required: list[VarIssue]

Variables that are required but set to an empty string.

missing property

missing: list[VarIssue]

Variables that are required but completely absent from the environment.

ok property

ok: bool

True when no issues were found.

type_errors property

type_errors: list[VarIssue]

Variables whose value cannot be coerced to the declared type.

EnvValidator

Validates the running process environment against an EnvSpec.

Usage::

spec = load_env_spec("env_spec.yaml")
validator = EnvValidator(spec)
result = validator.validate()
if not result.ok:
    validator.report(result)

Methods:

Name	Description
__init__	Initialise the validator with a parsed EnvSpec.
report	Log a human-readable summary of the validation result.
validate	Run the full validation pass.

__init__

__init__(spec: EnvSpec) -> None

Initialise the validator with a parsed EnvSpec.

report staticmethod

report(result: EnvValidationResult) -> None

Log a human-readable summary of the validation result.

Parameters:

Name	Type	Description	Default
result	EnvValidationResult	The result produced by :meth:validate.	required

validate

validate(
    env: dict[str, str] | None = None,
) -> EnvValidationResult

Run the full validation pass.

Parameters:

Name	Type	Description	Default
env	dict[str, str] | None	Optional dict of environment variables to validate against. Defaults to os.environ.	None

Returns:

Type	Description
EnvValidationResult	EnvValidationResult with all discovered issues.

IssueKind

Bases: StrEnum

Issue kind.

VarIssue dataclass

A single validation problem for one environment variable.

validate_env

validate_env(
    spec_path: str | Path | None = None,
    *,
    env: dict[str, str] | None = None,
    raise_on_error: bool = False,
) -> EnvValidationResult

Load the env spec and validate the current environment in one call.

Typical usage at application startup::

from pyModeller import validate_env

validate_env(raise_on_error=True)

Parameters:

Name	Type	Description	Default
spec_path	str | Path | None	Path to env_spec.yaml. Defaults to CWD.	None
env	dict[str, str] | None	Override for the environment dict (useful in tests).	None
raise_on_error	bool	If True, raises EnvValidationError when required variables are missing or empty.	False

Returns:

Type	Description
EnvValidationResult	EnvValidationResult

Raises:

Type	Description
EnvValidationError	Only when raise_on_error is True and issues exist.
FileNotFoundError	If the spec file cannot be found.