Bonjour à tous,
Je bossais sur le support du suivi via un device_tracker dans l'intégration Meteo-France et j'ai observé un changement dans la gestion des flows.
Cela pourra avoir un impact sur les vieilles installations de Home Assistant non mises à jour.
Note #1 : Ce message a été écrit avec une IA
Note #2 : Ce post est à destination des développeurs d'intégrations si vous ne comprenez pas les 3 premières phrases, c'est que vous n'êtes pas concernés.
Bonjour à tous,
Depuis la 2026.9, Home Assistant a changé de moteur de validation des données. voluptuous (les fameux vol.Schema, vol.Required… des config flows, services et schémas YAML) est remplacé par probatio. Voici ce que ça implique concrètement pour celles et ceux qui développent des intégrations personnalisées (HACS) ou contribuent au cœur.
En bref
- Vos intégrations personnalisées qui font
import voluptuous as volcontinuent de fonctionner. Home Assistant redirige cet import vers une couche de compatibilité de probatio. - Les données validées sont identiques. En revanche, les messages d'erreur par défaut ont changé de forme : à surveiller si vos tests les comparent.
- Une poignée de symboles internes de voluptuous n'existent plus via
vol.. - Pour contribuer au cœur : à partir de la 2026.10, le linter refuse
import voluptuous, il faut écrireimport probatio.
Ce qui a changé, et quand
- #175128 « Use Probatio as the data validation engine », fusionnée le 24/08/2026, publiée en 2026.9.
- #182112 « Use probatio directly in all integrations », fusionnée le 13/09/2026 : les intégrations du cœur importent désormais probatio directement (2026.10).
| Version | probatio | import voluptuous dans HA |
Linter du cœur |
|---|---|---|---|
| 2026.9.4 (stable) | 0.11.4 | redirigé vers probatio | autorisé |
| 2026.10.0b0 (bêta) | 0.12.4 | redirigé vers probatio | interdit |
dev (2026.11) |
0.13.0 | redirigé vers probatio | interdit |
Home Assistant ne déclare plus voluptuous comme dépendance. Le paquet peut rester installé parce que d'autres bibliothèques l'exigent (hass-nabucasa, annotatedyaml…), mais il n'est plus utilisé : la redirection se fait dès le chargement de Home Assistant, dans homeassistant/__init__.py :
from probatio.compat import install_as_voluptuous
# Probatio replaces voluptuous as the validation engine. Custom integrations and a
# few dependencies still import voluptuous directly, so alias it to probatio in
# sys.modules before anything imports it. This must run before the first
# `import voluptuous`, hence the package __init__.
install_as_voluptuous()
probatio est développé par Franck Nijhof (frenck), sous licence MIT : documentation, code source.
Intégrations personnalisées : ce qu'il faut vérifier
Ce qui fonctionne à l'identique
J'ai comparé le vrai voluptuous (0.15.2 et 0.16.0) à la couche de compatibilité de probatio (0.11.4, 0.12.4 et 0.13.0). Résultat identique sur les trois versions de probatio : mêmes données validées, mêmes types d'exception (jusqu'aux sous-classes comme TypeInvalid ou MatchInvalid), même err.path, y compris dans les dictionnaires imbriqués et les listes, pour :
Schema, Schema.extend, Required / Optional avec default, All, Any, In, Coerce, Range, Clamp, Length, Lower / Upper, Boolean, Maybe, Url, Email, Remove, Exclusive / Inclusive, extra=ALLOW_EXTRA, les validateurs personnalisés (fonctions qui lèvent vol.Invalid) et les messages personnalisés (msg=, vol.Msg).
Les sous-modules voluptuous.humanize, voluptuous.error, voluptuous.validators, voluptuous.schema_builder et voluptuous.util restent importables.
Ce qui change : les messages d'erreur par défaut
| Cas | voluptuous | probatio |
|---|---|---|
| Clé obligatoire absente | required key not provided @ data['host'] |
required key not provided at 'host' |
| Valeur hors plage | value must be at least 1 for dictionary value @ data['port'] |
value must be at least 1 at 'port' |
| Clé en trop | extra keys not allowed @ data['extra'] |
not a valid option at 'extra' |
Match |
does not match regular expression ^\d+$ |
does not match the expected pattern |
humanize_error |
expected int for dictionary value @ data['a']. Got 'x' |
expected int at 'a'. Got 'x' |
Si vos tests comparent str(err), ils casseront. Préférez vérifier le type d'exception et err.path, ou passez un msg= explicite.
Symboles qui n'existent plus via vol.
DOMAIN_REGEX, USER_REGEX, DefaultFactory, Decimal, InvalidOperation, Generator, basestring, primitive_types, cache, contextmanager, wraps.
Ce sont des éléments internes que voluptuous ré-exportait sans le vouloir. Si vous les utilisiez via vol., importez-les depuis leur module d'origine (decimal, functools, contextlib, typing).
Scripts et tests autonomes : importez Home Assistant en premier
Si voluptuous est importé avant homeassistant (script autonome, conftest de tests…), Home Assistant affiche :
RuntimeWarning: install_as_voluptuous is shadowing an already-imported voluptuous; call it before anything imports voluptuous so references resolve to probatio
Les objets créés avant cet avertissement restent du vrai voluptuous. Dans une instance Home Assistant normale, le problème ne se pose pas : Home Assistant est toujours chargé en premier.
Supporter les versions avant et après 2026.9
Le plus simple est de garder import voluptuous as vol : vous aurez le vrai voluptuous avant 2026.9, et la couche de compatibilité ensuite.
Si vous voulez déjà écrire probatio. dans votre code, ce repli fonctionne, à condition de vous limiter aux fonctions communes aux deux :
try:
import probatio
except ImportError: # Home Assistant < 2026.9
import voluptuous as probatio
Contribuer au cœur : probatio obligatoire
À partir de la 2026.10, ruff refuse ces imports dans le dépôt home-assistant/core :
| Interdit | À utiliser |
|---|---|
import voluptuous |
import probatio |
cv.ensure_list |
probatio.EnsureList() |
cv.port |
probatio.Port() |
cv.has_at_least_one_key |
probatio.AtLeastOne |
cv.has_at_most_one_key |
probatio.AtMostOne |
Exemple réel, tiré de la migration du config flow de Météo-France (#182112) :
# Avant
import voluptuous as vol
data_schema=vol.Schema(
{vol.Required(CONF_CITY, default=user_input.get(CONF_CITY, "")): str}
)
# Après
import probatio
data_schema=probatio.Schema(
{probatio.Required(CONF_CITY, default=user_input.get(CONF_CITY, "")): str}
)
Pensez aussi à mettre à jour votre branche si elle date d'avant la migration : un import voluptuous qui passait hier fera échouer le lint aujourd'hui.
Limites de cette analyse
- Testé en conditions réelles sur 2026.9.4 et
dev. Pour la 2026.10.0b0, j'ai seulement lu le code et testé probatio 0.12.4 hors de Home Assistant. - Les comparaisons couvrent les validateurs les plus courants, pas l'intégralité de l'API voluptuous.
- Rien dans le code n'indique si la couche de compatibilité sera retirée un jour.
N'hésitez pas à partager vos retours si vous tombez sur un cas qui se comporte différemment !