Migration d'une configuration JSON vers TOML : ce qui convertit et ce qui nécessite un humain

L'ère setup.cfg et settings.json touche à sa fin - un projet consolidant la configuration dans pyproject.toml et les blocs JSON qui doivent être déplacés Les projets

consolident parfois les paramètres dans un seul fichier TOML, mais le référentiel ne peut pas soutenir l'affirmation du plan selon laquelle une « époque se termine ». La tâche pratique est plus restreinte : déplacer un objet en forme de JSON dans une table TOML, inspecter les pertes, puis vérifier que l'application cible reconnaît réellement les clés résultantes.

ToolAcre nécessite un objet racine pour la sortie TOML. Un tableau racine, une chaîne, un nombre, un booléen ou un null est refusé car un document TOML est une table. Cette vérification précoce de la forme empêche un wrapper inventé de ressembler à une configuration approuvée par l'application.

Une consolidation de configuration est un choix de projet et non la fin universelle des anciens formats.

Le convertisseur prouve la mécanique concrète : TOML contient des tableaux, des tableaux et des valeurs scalaires ; son rédacteur transforme les objets imbriqués en structures TOML valides. Il n'a pas non plus de valeur nulle et utilise une syntaxe différente des accolades JSON. Les allégations concernant la préférence de l'écosystème ou la supériorité de la conception nécessitent des sources extérieures à ces fichiers de mise en œuvre. Les commentaires

sont l'une des raisons pour lesquelles les responsables peuvent préférer l'auteur TOML, mais l'entrée JSON n'en contient aucun à transmettre. Le document généré est une sérialisation de valeur de départ. Il faudra ensuite ajouter une explication humaine et une organisation spécifique au projet.

Ce que ce convertisseur prouve à propos de TOML plutôt que de la promotion générale du format

Les chaînes, les nombres finis, les booléens, les objets imbriqués et les tableaux pris en charge par smol-toml se convertissent mécaniquement. Les tableaux d'objets peuvent devenir des tableaux de tables ; les objets imbriqués peuvent devenir des en-têtes de tableau. Unicode et les nouvelles lignes échappées survivent aux allers-retours testés pour les valeurs ordinaires. Les règles de tableau

TOML peuvent rejeter les formes que son auteur ne peut pas exprimer, et les noms d'erreur qui échouent plutôt que de contraindre silencieusement. Appeler tous les tableaux homogènes à l’avance simplifierait à l’extrême le comportement testé de la dépendance, qui lit même des tableaux hétérogènes. Utilisez la conversion réelle comme porte.

Ce qui est converti mécaniquement, y compris les tableaux acceptés par l'écrivain TOML

Null n'a pas de représentation TOML. Les propriétés d'objet contenant la valeur null sont omises et répertoriées dans un avertissement. Un null à l'intérieur d'un tableau devient une chaîne vide afin que les indices ultérieurs ne soient pas décalés ; ce remplacement est également nommé. Aucun des deux résultats ne préserve la valeur d’origine.

Décidez de ce que null signifie avant d'accepter l'un ou l'autre changement. Cela peut signifier hériter d'une valeur par défaut, effacer explicitement un champ ou aucune valeur fournie. La suppression de la clé ou le remplacement d'un texte vide peut modifier la sémantique de l'application, alors résolvez-la par rapport au modèle de configuration documenté de la destination.

Là où le style a besoin d'un humain : choisir entre les en-têtes [de table], les touches pointillées et les tableaux en ligne, et regrouper les clés associées pour que le fichier soit bien lu

L'arborescence ne dit pas si les responsables préfèrent `[tool.linter]`, les clés pointées ou les tables en ligne. Un sérialiseur choisit une syntaxe valide, tandis qu'un humain choisit un regroupement qui clarifie la propriété et les options associées. Les clés de tri peuvent rendre la sortie déterministe mais peuvent séparer les concepts qui vont ensemble.

Conservez une petite différence et ajoutez des commentaires une fois les valeurs vérifiées. La conversion ultérieure de TOML en JSON ne peut pas restaurer ces commentaires ou l'orthographe du tableau choisi. Le style est une information créée en dehors du modèle de valeur simple.

Exemple pratique : la configuration JSON d'un linter en TOML — conversion, résolution de deux valeurs nulles et regroupement du résultat sous un en-tête [tool.linter]

Convertissez `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. L'objet racine est accepté. `preview` est omis ; le membre nul du tableau devient une chaîne vide ; les avertissements nomment les deux chemins. L'objet imbriqué restant est sérialisé sous les tables TOML choisies par le rédacteur.

Avant d'enregistrer, décidez si l'aperçu doit être faux, absent ou une autre valeur documentée, et si une entrée d'exclusion vide est valide. Regroupez-vous ensuite et commentez le tableau pour les lecteurs. L'exemple montre pourquoi la conversion est mécanique alors que la migration est sémantique.

Ce que cela ne couvre pas : si l'outil cible lit réellement TOML et ses noms de clés spécifiques, que seule sa documentation peut vous indiquer.

Un fichier TOML valide ne prouve pas qu'un outil lit TOML, reconnaît la section ou interprète les clés comme l'ancien consommateur JSON. Vérifiez la documentation cible actuelle et exécutez sa propre commande de validation ou d'exécution à sec. ToolAcre n'importe jamais de schéma d'application.

Les dattes méritent également des soins dans le sens inverse. Les valeurs temporelles natives de TOML deviennent des chaînes lorsqu'elles sont lues dans JSON, donc un aller-retour ultérieur les cite. Une chaîne de migration traversant les deux sens ne peut pas être qualifiée de sans perte.

À retenir : convertissez d'abord, puis modifiez pour plus de lisibilité - et comment le panneau des convertisseurs de syntaxe effectue la partie mécanique dans votre navigateur

Convertissez d'abord pour exposer les incompatibilités mécaniques, puis modifiez pour des raisons de sémantique et de lisibilité. Conservez l’original, examinez chaque avertissement et testez avec la cible réelle. La gestion des valeurs nulles et la forme de la racine sont des limites strictes ; l'organisation de la table est une décision de conception humaine.

Les convertisseurs de syntaxe suppriment le travail de syntaxe répétitif sans inventer de connaissances applicatives. Cette division rend le résultat utile : une structure produite par une machine pour examen, suivie de choix délibérés là où les formats ou les outils sont en désaccord.

Conservez une note de migration pour chaque avertissement que vous acceptez. Si une valeur nulle devient absence, indiquez la destination par défaut qui corrige l'absence. Si un membre nul du tableau devient du texte vide, expliquez pourquoi l'index est important et pourquoi le texte vide est valide. Si l'auteur rejette un tableau mixte, reconcevez cette valeur au lieu de la forcer en privé. Ces décisions constituent le bilan migratoire durable ; le TOML généré à lui seul ne peut pas les expliquer au prochain responsable.