Convertir YAML en TOML

Le format a été proposé par Tom Preston-Werner en 2013 pour le fichier de configuration de GitHub, et l’idée conductrice était la lisibilité par une personne sans surprise. La syntaxe est celle d’INI : des paires clé-valeur regroupées sous des en-têtes [section], avec des commentaires en #. La différence est que les valeurs ne sont pas des chaînes : un entier est un entier, un booléen est un booléen, une date est une date, et un tableau est un tableau.

Pour une configuration écrite à la main, c’est presque toujours la cible qu’il faut. Pour une configuration générée par une machine et lue par une autre, JSON fait la même chose en plus petit. TOML gagne sa place surtout dans des contextes où une personne édite le fichier et où les types ne doivent pas être devinés — pyproject.toml, Cargo.toml, les fichiers de config des outils Rust en général.

Un YAML qui commence par un objet produit un fichier TOML dont les clés de premier niveau sont les en-têtes [key]. Un objet server, un objet database, un objet logging deviennent [server], [database] et [logging], avec leurs clés filles écrites en dessous. Pour des réglages écrits à l’origine par une personne, c’est presque toujours une correspondance exacte.

Les clés scalaires de premier niveau — un drapeau, un nom d’environnement — sont écrites au-dessus du premier en-tête de section. Comme en INI, une section s’approprie tout ce qui la suit jusqu’à l’en-tête suivant, et une clé nue écrite plus bas serait lue comme membre de la section précédente.

TOML a une syntaxe explicite pour les sous-sections : [parent.enfant] et [parent.enfant.petit_enfant]. Un YAML qui contient un objet server contenant un objet tls produit une section [server.tls], et tout le sous-arbre y est écrit en clair. La règle est lisible et donne, dans la plupart des cas, un fichier qu’une personne aurait tapé.

Là où YAML contient des objets anonymes dans des tableaux — un objet dans une liste de trois hosts autorisés — TOML n’a pas de représentation directe. La conversion écrit le tableau en [[hosts]] qui est la syntaxe TOML pour un tableau de tables, et chaque élément du tableau est nommé par son index. C’est correct et c’est ce que cargo attend quand on lui donne une liste de dépendances par exemple.

Un entier YAML est écrit comme un entier TOML, un booléen comme true ou false, un float comme 1.0, une chaîne comme une chaîne entre guillemets. TOML a des types de plus que JSON : des dates et heures au format ISO 8601, des entiers signés et non signés distincts, et un type datetime qui distingue la date de l’instant. La conversion émet les valeurs avec leur type d’origine, ce qui est ce que pyproject.toml attend quand on lui passe une version « 1.0 » qui doit être une chaîne et pas un float.

Le piège classique est « version : 1.0 ». YAML le lit comme une chaîne, parce qu’un seul point ne suffit pas à faire un float. TOML le lit aussi comme une chaîne, parce qu’un float doit avoir un chiffre après le point. Le piège est ailleurs : un « version : 1.10 » sera lu comme un float 1.1 par un parseur TOML, et un consommateur qui s’attend à une chaîne recevra un nombre. La correction est de mettre la valeur entre guillemets dans YAML source, et la conversion la transporte telle quelle. Pour les très grands entiers, YAML les accepte et TOML aussi, et la conversion préserve la précision tant qu’elle tient dans un int64 — au-delà, la chaîne est mise entre guillemets pour éviter une perte silencieuse que le parseur en aval ne signalerait pas.

YAML permet de définir un bloc une fois (&id) et de le référencer à plusieurs endroits (*id). TOML n’a aucune notion d’alias, donc chaque référence est développée en une copie complète du bloc. Le résultat est correct et plus volumineux, et c’est le compromis à accepter pour passer d’un format à l’autre.

Pour la plupart des fichiers de configuration, c’est indolore. Pour un fichier où la même longue structure est référencée vingt fois, la sortie sera vingt fois plus longue que la source. Si la taille compte, déplier les ancres à la main en YAML avant la conversion est l’édition qui vaut la peine, et c’est aussi une étape qui rend le fichier TOML plus lisible parce que les copies explicites ne demandent pas au lecteur de remonter à la définition. Le registre ne signale pas la duplication, parce qu’elle est silencieuse et que compter les ancres serait une ré-implémentation du parseur ; c’est l’auteur du fichier qui décide, et c’est lui qui voit la sortie.

YAML 1.2 a corrigé ce que 1.1 faisait : un « 2024-01-01 » n’est plus automatiquement converti en horodatage. TOML a un type datetime natif qui accepterait exactement cette chaîne, et c’est la conversion tentée : une chaîne qui ressemble à une date ISO 8601 est émise sans guillemets, ce qui fait d’elle un datetime TOML plutôt qu’une chaîne.

Le piège est que tous les consommateurs ne traitent pas un datetime comme une date. pyproject.toml attend des chaînes pour les versions de dépendances, et un datetime 2024-01-01 lu comme tel donne un objet Python datetime, pas une chaîne. Pour forcer la conversion à traiter la valeur comme une chaîne, mettez-la entre guillemets dans YAML source. C’est une édition de deux secondes qui évite une heure de débogage. Pour les timestamps avec un fuseau horaire explicite, la conversion ajoute le suffixe Z quand la valeur n’en a pas, ce qui force le parseur à interpréter la valeur en UTC plutôt qu’en heure locale — c’est l’édition qui rend le fichier portable entre machines de fuseaux différents.

Un tableau YAML devient un tableau TOML entre crochets : [1, 2, 3] pour les entiers, ["a", "b", "c"] pour les chaînes, [{x = 1}, {x = 2}] pour un tableau d’objets inline. La forme est lisible et standard, et la conversion la transporte telle quelle sauf quand un objet anonyme dans un tableau déclenche la syntaxe [[table]] du TOML.

Les tableaux de chaînes hétérogènes — un mélange d’entiers et de chaînes dans un même tableau — sont légaux en YAML et en TOML, mais la conversion normalise en mettant toutes les chaînes entre guillemets. C’est sans perte, et c’est plus prévisible qu’une sortie où le même type serait cité dans un élément et pas dans l’autre. Les tableaux vides sont écrits entre crochets sans contenu : hosts = [], ce qui est la forme qu’attend pyproject quand on lui passe une liste de dépendances à zéro élément pendant un développement. Pour les tableaux longs, la conversion ne les met pas sur plusieurs lignes : c’est le format TOML qui s’en accommode, et casser la ligne ne fait que compliquer la relecture.

YAML autorise un commentaire n’importe où sur une ligne, après un dièse. TOML a la même convention, et la conversion ne transporte pas les commentaires parce que la sortie est générée sans contexte. C’est l’unique perte qui ne soit pas structurelle, et c’est le seul cas où l’opération est destructive.

L’habitude qui compense est d’extraire les commentaires dans un fichier à part avant la conversion, ou de les intégrer dans des clés descriptives que le format cible comprend. TOML se prête particulièrement bien à des commentaires inline parce que la convention est la même, et c’est le bon endroit pour les réintroduire une fois la conversion faite. Pour un fichier pyproject.toml, les commentaires au-dessus d’une dépendance ou d’un outil de build sont la différence entre un fichier qu’une personne comprend et un fichier qu’une personne devine, et c’est précisément le moment de les écrire parce que la forme TOML les accepte en première colonne.

Un scalaire bloc YAML avec un pipe représente une chaîne sur plusieurs lignes. TOML a une syntaxe multi-lignes entre trois guillemets droits, ce qui permet de la transporter presque littéralement. La conversion utilise cette forme quand la chaîne source est multi-ligne, ce qui donne TOML lisible et un aller-retour qui préserve les sauts de ligne.

Le piège est qu’un scalaire bloc replié en YAML (avec un chevron >) joint les lignes avec des espaces. TOML n’a pas d’équivalent direct, et la conversion joint les lignes avec un espace, ce qui est presque toujours ce que l’auteur voulait. Pour les rares cas où la jointure originale avait un sens différent, mettre la chaîne entre guillemets droits dans YAML force la conversion à la transporter telle quelle. Pour un script embarqué dans un fichier de configuration, c’est important : un script mal indenté devient un script qui ne s’exécute pas, et c’est l’édition qui rend l’aller-retour visible à l’œil sans exécuter le fichier.

C’est du JavaScript dans votre onglet. Le YAML est analysé par un parseur chargé à la demande, TOML est écrit par une bibliothèque qui tourne dans l’onglet, et aucune requête ne porte le document. Il n’y a pas d’inscription, pas de file d’attente, et le niveau gratuit accepte jusqu’à 100 Mo — bien plus que n’importe quel fichier de configuration.

Pour ce lectorat, c’est une préoccupation pratique plutôt qu’abstraite. Un fichier pyproject.toml contient des numéros de version et parfois des URLs de dépôt, et un certain nombre d’organisations traitent le fait de coller cela dans un convertisseur web public comme un incident. Ici il n’y a rien à coller et rien à envoyer, et le code du parseur tourne dans l’onglet.