Home Assistant

Home Assistant validates its configuration with voluptuous, and it does so heavily. The config_validation helper is one of the largest voluptuous consumers there is. Probatio mirrors the voluptuous API, so it can stand in.

The simple case: change the import

If your code uses the voluptuous public API, the swap is a one-liner. Change the import and keep your schemas exactly as they are.

from probatio import Schema, Required, Optional

CONFIG_SCHEMA = Schema(
    {
        Required("name"): str,
        Optional("port", default=8123): int,
    }
)

CONFIG_SCHEMA({"name": "living-room"})  # {'name': 'living-room', 'port': 8123}

The names, signatures, and behavior match. Required, Optional, All, Any, Coerce, Range, In, the markers, the error classes: same surface, fresh implementation.

The harder case: code that imports voluptuous internals

Not everything imports the public API. Some dependencies reach into voluptuous internals. Home Assistant’s annotatedyaml, for example, imports voluptuous.schema_builder._compile_scalar directly. You cannot change the import in code you do not own.

For that, Probatio ships install_as_voluptuous. Call it once at process startup, before anything imports voluptuous:

from probatio.compat import install_as_voluptuous

install_as_voluptuous()

It registers a small voluptuous-shaped shim, backed by Probatio, into sys.modules under the voluptuous name, so every later import voluptuous resolves to Probatio for the rest of the process. It is process-wide, so call it from an application entry point, not from library code, and call it early: if a real voluptuous was already imported, it is shadowed and a RuntimeWarning is emitted, since references already taken to the real module will not update. The Compatibility page covers exactly what it registers and when to call it.

It is tested against the real thing

This is not a paraphrase of compatibility. Probatio is validated against Home Assistant’s own config_validation test suite, with voluptuous swapped out for Probatio through install_as_voluptuous. All 142 tests in that suite pass.

Getting there surfaced real compatibility gaps that isolated unit tests had missed, like Remove(key) keeping a value that fails its schema, and the exact "for dictionary value @ data[...]" wording on a failed mapping value. Those are fixed. The proof harness lives in compat/home_assistant/ in the repository, so you can reproduce it against a Home Assistant checkout.

Where to next

• Migrating from voluptuous: the general swap, beyond Home Assistant.
• Validating a config file: a worked end-to-end example.
• Error handling: paths, multiple errors, and readable messages.