bloc.io.yaml#

YAML utilities for Bloc: comment-aware parsing and deep merge.

Uses ruamel.yaml to preserve and extract inline comments from YAML files. Comment convention: # [<unit>] <description> [| <remark>]

Example YAML:

initial:
  G_PW_IN: 111  # [kW] Generator power IN
  G_ETA: 0.80   # [-] Generator efficiency

Functions#

`load_yaml_raw`(path)	Load a YAML file preserving comments (ruamel.yaml round-trip mode).
`extract_comment_metadata`(data[, section])	Extract inline comment metadata from a YAML section.
`extract_header_comments`(path)	Extract leading comments from a YAML file (before the first key).
`get_bloc_version_info`()	Get Bloc version and git commit hash.
`load_scenario`(base_path[, overlay_path])	Load a scenario by deep-merging an optional overlay onto a base YAML.
`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.io.yaml.load_yaml_raw(path)#

Load a YAML file preserving comments (ruamel.yaml round-trip mode).

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: The parsed YAML data with comments preserved.
Return type:: CommentedMap

bloc.io.yaml.extract_comment_metadata(data, section='initial')#

Extract inline comment metadata from a YAML section.

Parses comments following the convention # [unit] description [| remark].

Parameters:

data (CommentedMap) – Parsed YAML data (from load_yaml_raw()).
section (str) – The top-level section to extract from (default "initial").

Returns:

{key: {"value": ..., "unit": str, "description": str, "remark": str}}

Return type:

dict

bloc.io.yaml.extract_header_comments(path)#

Extract leading comments from a YAML file (before the first key).

These are typically the file description, update log, etc.

Parameters:: path (str or Path) – Path to the YAML file.
Returns:: Each line of header comments (with # prefix stripped).
Return type:: list of str

bloc.io.yaml.get_bloc_version_info()#

Get Bloc version and git commit hash.

Returns:: {"version": str, "commit": str}
Return type:: dict

bloc.io.yaml.load_scenario(base_path, overlay_path=None)#

Load a scenario by deep-merging an optional overlay onto a base YAML.

If the overlay has a top-level from key, it must match the base filename (e.g. from: SPRING_A3_BG_20260212.yaml when base is that file); otherwise a ValueError is raised. The from key is not merged into the result (metadata only).

Parameters:

base_path (str or Path) – Path to the base YAML file.
overlay_path (str or Path or None) – Path to the overlay YAML file. If None, only the base is returned.

Returns:

The merged configuration dictionary (plain dict, no comments).

Return type:

dict

bloc.io.yaml.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.io.yaml.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.io.yaml.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.io.yaml.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.io.yaml.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.io.yaml.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.io.yaml.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")
...