{"id":10335,"library":"valohai-yaml","title":"Valohai YAML Parser and Validator","description":"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.","status":"active","version":"0.56.0","language":"en","source_language":"en","source_url":"https://github.com/valohai/valohai-yaml","tags":["yaml","configuration","valohai","validation","machine-learning"],"install":[{"cmd":"pip install valohai-yaml","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"Top-level `parse` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.","wrong":"from valohai_yaml.yaml import parse","symbol":"parse","correct":"from valohai_yaml import parse"},{"note":"Top-level `lint` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.","wrong":"from valohai_yaml.lint import lint","symbol":"lint","correct":"from valohai_yaml import lint"},{"note":"Top-level `build_config` is re-exported for convenience since v0.56.0. The submodule path still works but is less direct.","wrong":"from valohai_yaml.build import build_config","symbol":"build_config","correct":"from valohai_yaml import build_config"}],"quickstart":{"code":"from valohai_yaml import parse\n\nvalohai_yaml_content = '''\n- step: \n    name: training-step\n    image: python:3.9\n    command: python train.py\n    inputs:\n      - name: dataset\n        default: s3://my-bucket/data/dataset.csv\n    outputs:\n      - name: model\n        default: model.pkl\n'''\n\nconfig = parse(valohai_yaml_content)\n\nprint(f\"Parsed Valohai config with {len(config.steps)} step(s).\")\nprint(f\"First step name: {config.steps[0].name}\")\n\n# Example of linting (requires more complex setup usually)\n# from valohai_yaml import lint\n# errors = lint(config)\n# if errors: print(f\"Linting errors: {errors}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or newer. `valohai-yaml` >=0.47.0 requires Python >=3.9.","message":"Support for Python 3.8 was dropped in version 0.47.0. Users on Python 3.8 will encounter installation or runtime errors.","severity":"breaking","affected_versions":">=0.47.0"},{"fix":"Review your `valohai.yaml` files for any duplicate step, pipeline, or endpoint names and ensure all top-level entities have unique identifiers.","message":"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.","severity":"breaking","affected_versions":">=0.47.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.56.0"},{"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.","message":"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`).","severity":"gotcha","affected_versions":">=0.56.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install valohai-yaml` to install the package.","cause":"The `valohai-yaml` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'valohai_yaml'"},{"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.","cause":"The provided YAML content does not conform to the Valohai YAML schema, or contains structural errors.","error":"valohai_yaml.errors.ValidationError: [YAML is not valid] ..."},{"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.","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.","error":"yaml.parser.ParserError: while parsing a block mapping"},{"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.","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.","error":"AttributeError: 'NoneType' object has no attribute 'steps'"}]}