annotatedyaml

What it is and what it does

annotatedyaml is a YAML parser and validator for Python that combines YAML parsing with schema validation and secrets support. It wraps pyyaml for parsing and voluptuous for schema validation, allowing developers to define typed, validated configuration structures in YAML while handling sensitive data securely. The package is in pre-alpha and requires Python 3.13 or later.

The package is designed to handle configuration files that need both structural validation and the ability to reference or embed secrets. It appears to be part of the Home Assistant ecosystem but is published as a standalone library. With significant adoption, its pre-alpha status and recent release date mean the API and behavior may still evolve.

Use it for:

• Validate Home Assistant configuration YAML files with type checking and schema enforcement
• Parse application config files that contain both public settings and secret references
• Define and enforce YAML schema structures using voluptuous validators in Python
• Load and validate typed configuration data from YAML with automatic error reporting

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses and validates YAML files with support for embedded secrets and type annotations, using a schema-based validation approach.

Yes, with conditions. The package is actively maintained and permissively licensed, making it suitable for projects requiring YAML validation with secrets support. However, its pre-alpha status and Python 3.13-only requirement limit adoption; evaluate whether your environment supports Python 3.13 and whether pre-alpha stability is acceptable for your use case. No known vulnerabilities.

Install

annotatedyaml on PyPI

pip install annotatedyaml

uv add annotatedyaml

poetry add annotatedyaml

Installing annotatedyaml

Before you install

Medium install friction due to compiled wheels across multiple Python versions and platforms. Active maintenance with recent commits; however, the package is in pre-alpha status (Development Status :: 2) and has been in active development for less than a year, so stability is not yet established.

License in practice

Licensed under Apache-2.0 (permissive), allowing use in commercial and private projects with minimal restrictions beyond attribution and liability disclaimers.

Quickstart

pip install annotatedyaml

import annotatedyaml
from voluptuous import Schema, Required

schema = Schema({Required('key'): str})
data = annotatedyaml.load(open('config.yaml'), schema=schema)

Requires Python 3.13 or later; pyyaml, propcache, and voluptuous must be available.

Verify before relying

• How secrets are embedded and retrieved within YAML (encryption method, storage format, or reference mechanism not detailed in excerpt)
• Whether the package integrates with Home Assistant or is usable standalone
• Performance characteristics when validating large YAML files
• Exact validation error messages and debugging experience

Package facts

Evidence: annotatedyaml-1.0.2-cp313-cp313-macosx_10_13_x86_64.whl; annotatedyaml-1.0.2-cp313-cp313-macosx_11_0_arm64.whl; annotatedyaml-1.0.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; annotatedyaml-1.0.2-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; annotatedyaml-1.0.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; annotatedyaml-1.0.2-cp313-cp313-manylinux_2_36_x86_64.whl; annotatedyaml-1.0.2-cp313-cp313-musllinux_1_2_aarch64.whl; annotatedyaml-1.0.2-cp313-cp313-musllinux_1_2_armv7l.whl; annotatedyaml-1.0.2-cp313-cp313-musllinux_1_2_x86_64.whl; annotatedyaml-1.0.2-cp313-cp313-win32.whl; annotatedyaml-1.0.2-cp313-cp313-win_amd64.whl; annotatedyaml-1.0.2-cp314-cp314-macosx_10_13_x86_64.whl; annotatedyaml-1.0.2-cp314-cp314-macosx_11_0_arm64.whl; annotatedyaml-1.0.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl; annotatedyaml-1.0.2-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl; annotatedyaml-1.0.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl; annotatedyaml-1.0.2-cp314-cp314-musllinux_1_2_aarch64.whl; annotatedyaml-1.0.2-cp314-cp314-musllinux_1_2_armv7l.whl; annotatedyaml-1.0.2-cp314-cp314-musllinux_1_2_x86_64.whl; annotatedyaml-1.0.2-cp314-cp314t-macosx_10_13_x86_64.whl

Tags

More Libraries packages