bloc.yaml_validation#

YAML validation utilities for Bloc.

Provides functions to validate YAML files for common syntax issues, particularly in comments and unit notation.

Functions#

`extract_notes_from_yaml`(path)	Extract note comments from YAML file.
`extract_nested_param_hints`(path)	Extract nested-parameter display hints from inline YAML comments.
`validate_yaml_note_syntax`(path)	Validate note syntax in YAML file and report inconsistencies.
`validate_yaml_unit_brackets`(path)	Validate that units in comments are enclosed in brackets.
`validate_yaml_units`(path, *[, section, strict])	Validate that units in YAML comments match `INPUT_VARIABLE_MAP`.
`validate_yaml_file`(path)	Run all YAML validations on a single file.
`validate_yaml_directory`([directory, pattern])	Validate all YAML files in a directory.

Module Contents#

bloc.yaml_validation.extract_notes_from_yaml(path)#

Extract note comments from YAML file.

Searches for comments in the following formats:

# .. note: This is a note about the parameter (preceding line)
parameter: value

parameter: value  # .. note: This is an inline note

# note: This is a note about the parameter (preceding line)
parameter: value

parameter: value  # note: This is an inline note

Returns a dictionary mapping parameter names to their notes. Multiple notes for the same parameter are collected in a list.

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: Dictionary mapping parameter names to lists of note strings.
Return type:: dict[str, list[str]]

Examples

>>> notes = extract_notes_from_yaml("config.yaml")
>>> notes["X_torch_input"]
["Chose to use worst case gas composition..."]

bloc.yaml_validation.extract_nested_param_hints(path)#

Extract nested-parameter display hints from inline YAML comments.

The parser looks for comments on nested keys with the format:

child_key: {...} # [unit] description text

Returned structure is:

{
    "parent_key": {
        "child_key": {"unit": "...", "description": "..."},
    },
}

bloc.yaml_validation.validate_yaml_note_syntax(path)#

Validate note syntax in YAML file and report inconsistencies.

Checks for common errors: - Incorrect capitalization: “.. Note:”, “.. NOTE:” - Extra spaces: “ .. note : “, “. . note:” - Missing colon: “.. note”

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: List of validation issues. Each issue is a dict with: - ‘line_no’: Line number (1-indexed) - ‘line’: The problematic line - ‘issue’: Description of the issue - ‘suggestion’: Corrected syntax
Return type:: list[dict]

Examples

>>> issues = validate_yaml_note_syntax("config.yaml")
>>> for issue in issues:
...     print(f"Line {issue['line_no']}: {issue['issue']}")
...     print(f"  Found: {issue['line'].strip()}")
...     print(f"  Use: {issue['suggestion']}")
...

bloc.yaml_validation.validate_yaml_unit_brackets(path)#

Validate that units in comments are enclosed in brackets.

Checks for units that should be in brackets but aren’t, such as: - # kW -> should be # [kW] - # °C -> should be # [°C] - # kg/d -> should be # [kg/d]

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: List of validation issues. Each issue is a dict with: - ‘line_no’: Line number (1-indexed) - ‘line’: The problematic line - ‘issue’: Description of the issue - ‘suggestion’: Corrected syntax
Return type:: list[dict]

Examples

>>> issues = validate_yaml_unit_brackets("config.yaml")
>>> for issue in issues:
...     print(f"Line {issue['line_no']}: Unit not in brackets")
...     print(f"  Found: {issue['line'].strip()}")
...     print(f"  Use: {issue['suggestion']}")
...

bloc.yaml_validation.validate_yaml_units(path, *, section='initial', strict=False)#

Validate that units in YAML comments match INPUT_VARIABLE_MAP.

Cross-references the inline comment unit of each parameter in the given YAML section against the expected unit declared in bloc.yaml_utils.INPUT_VARIABLE_MAP (and bloc.yaml_utils.NESTED_INPUT_MAP for dict-valued parameters).

Only parameters that (a) appear in the YAML and (b) have a corresponding entry in the variable map are checked. Parameters without an inline comment are silently skipped.

Parameters:

path (str or Path) – Path to the YAML file.
section (str) – Top-level YAML section to inspect (default "initial").
strict (bool) – If True, raise a ValueError when any mismatch is found. If False (default), return the list of issues without raising.

Returns:

Each element is a dict with keys:

parameter – YAML parameter name
yaml_unit – unit found in the YAML comment
expected_unit – unit declared in the variable map
issue – human-readable description

Return type:

list[dict]

Raises:

ValueError – Only when strict is True and at least one mismatch is found.

bloc.yaml_validation.validate_yaml_file(path)#

Run all YAML validations on a single file.

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: Dictionary with validation results: - ‘file’: Path to the file - ‘note_issues’: List of note syntax issues - ‘bracket_issues’: List of unit bracket issues - ‘total_issues’: Total number of issues found
Return type:: dict

Examples

>>> result = validate_yaml_file("config.yaml")
>>> if result["total_issues"] > 0:
...     print(f"Found {result['total_issues']} issues in {result['file']}")
...

bloc.yaml_validation.validate_yaml_directory(directory='models', pattern='**/*.yaml')#

Validate all YAML files in a directory.

Parameters:

directory (str or Path, optional) – Directory to search for YAML files (default: “models”)
pattern (str, optional) – Glob pattern for finding YAML files (default: “**/*.yaml”)

Returns:

Dictionary with summary statistics and detailed results: - ‘total_files’: Number of files checked - ‘files_with_issues’: Number of files with issues - ‘total_issues’: Total number of issues across all files - ‘details’: List of per-file validation results

Return type:

dict

Examples

>>> result = validate_yaml_directory("models")
>>> print(f"Checked {result['total_files']} files")
>>> print(
...     f"Found {result['total_issues']} issues in {result['files_with_issues']} files"
... )
>>> for detail in result["details"]:
...     if detail["total_issues"] > 0:
...         print(f"  {detail['file']}: {detail['total_issues']} issues")
...