Valohai YAML Parser and Validator

0.56.0 · active · verified Fri Apr 17

valohai-yaml is a Python library for parsing, validating, and programmatically constructing `valohai.yaml` configuration files, which define machine learning pipelines and experiments for the Valohai platform. It ensures YAML configurations adhere to the Valohai schema. The current version is 0.56.0, and it maintains a frequent release cadence, often with minor updates and new feature support aligning with the Valohai platform.

Common errors

```
ModuleNotFoundError: No module named 'valohai_yaml'
```
cause The `valohai-yaml` library is not installed in the current Python environment.

fix Run `pip install valohai-yaml` to install the package.
```
valohai_yaml.errors.ValidationError: [YAML is not valid] ...
```
cause The provided YAML content does not conform to the Valohai YAML schema, or contains structural errors.

fix Carefully review the YAML content against the Valohai documentation and the error messages provided by the `ValidationError` to identify and correct the invalid syntax or structure. Use `valohai_yaml.lint` for detailed validation reports.
```
yaml.parser.ParserError: while parsing a block mapping
```
cause The input string contains malformed YAML syntax that even the underlying PyYAML parser cannot process, typically due to incorrect indentation, missing colons, or invalid character sequences.

fix Correct the YAML syntax. Pay close attention to indentation and standard YAML formatting rules. Tools like online YAML validators can help identify basic syntax errors.
```
AttributeError: 'NoneType' object has no attribute 'steps'
```
cause This usually happens when `valohai_yaml.parse()` fails due to invalid YAML, returns `None` or raises an exception, and subsequent code attempts to access attributes (like `steps`) on the non-existent or unhandled parsed object.

fix Always wrap `parse()` calls in a `try...except valohai_yaml.errors.ValidationError` block, or check the return value to ensure it's not `None` before attempting to access its attributes. Ensure the YAML input is valid.

Warnings

breaking Support for Python 3.8 was dropped in version 0.47.0. Users on Python 3.8 will encounter installation or runtime errors.
Fix: Upgrade your Python environment to version 3.9 or newer. `valohai-yaml` >=0.47.0 requires Python >=3.9.
breaking In version 0.47.0, the linter was updated to flag duplicate top-level entity names (e.g., two steps with the same name) as errors instead of warnings. Previously invalid configurations may now fail validation.
Fix: Review your `valohai.yaml` files for any duplicate step, pipeline, or endpoint names and ensure all top-level entities have unique identifiers.
gotcha Version 0.56.0 changed serialization behavior to not serialize empty edge configs or default node error actions. If you rely on programmatic serialization to regenerate exact YAML structures, this might result in differences.
Fix: If programmatically generating or comparing YAML, be aware that empty configurations or default error actions may no longer be explicitly written to the YAML output. Adjust comparison logic if necessary.
gotcha The `valohai-yaml` library exports various `Items` and `Enums` directly from the top-level package since v0.56.0 for convenience. While importing from submodules (e.g., `valohai_yaml.yaml.parse`) still works, the recommended path is direct import (`from valohai_yaml import parse`).
Fix: Update your import statements to use the top-level exports, e.g., `from valohai_yaml import parse` instead of `from valohai_yaml.yaml import parse` for better future compatibility and readability.

Install

pip install valohai-yaml Install latest version

Imports

parse
wrong:
```
from valohai_yaml.yaml import parse
```
correct:
```
from valohai_yaml import parse
```
Top-level `parse` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.
lint
wrong:
```
from valohai_yaml.lint import lint
```
correct:
```
from valohai_yaml import lint
```
Top-level `lint` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.
build_config
wrong:
```
from valohai_yaml.build import build_config
```
correct:
```
from valohai_yaml import build_config
```
Top-level `build_config` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.

Quickstart

This quickstart demonstrates how to parse a `valohai.yaml` string using the `parse` function. It takes a YAML string as input and returns a `Config` object, which provides programmatic access to the defined steps, pipelines, and other Valohai configuration elements. This is the fundamental way to interact with Valohai YAML files in Python.

from valohai_yaml import parse

valohai_yaml_content = '''
- step: 
    name: training-step
    image: python:3.9
    command: python train.py
    inputs:
      - name: dataset
        default: s3://my-bucket/data/dataset.csv
    outputs:
      - name: model
        default: model.pkl
'''

config = parse(valohai_yaml_content)

print(f"Parsed Valohai config with {len(config.steps)} step(s).")
print(f"First step name: {config.steps[0].name}")

# Example of linting (requires more complex setup usually)
# from valohai_yaml import lint
# errors = lint(config)
# if errors: print(f"Linting errors: {errors}")

view raw JSON →