Migración de una configuración JSON a TOML: qué convierte y qué necesita un humano

La era setup.cfg y settings.json está terminando: un proyecto que consolida la configuración en pyproject.toml y los bloques JSON que deben moverse

Los proyectos a veces consolidan la configuración en un archivo TOML, pero el repositorio no puede respaldar la afirmación del esquema de que "una era está terminando". La tarea práctica es más específica: mover un objeto con forma de JSON a una tabla TOML, inspeccionar las pérdidas y luego verificar que la aplicación de destino realmente reconozca las claves resultantes.

ToolAcre requiere un objeto raíz para la salida TOML. Se rechaza una matriz raíz, una cadena, un número, un booleano o un valor nulo porque un documento TOML es una tabla. Esa verificación temprana de la forma evita que un contenedor inventado parezca una configuración aprobada por la aplicación.

La consolidación de la configuración es una elección del proyecto, no el fin universal de los formatos más antiguos.

El convertidor demuestra mecánica concreta: TOML tiene tablas, matrices y valores escalares; su escritor convierte objetos anidados en estructuras TOML válidas. Tampoco tiene nulo y utiliza una sintaxis diferente de las llaves JSON. Las afirmaciones sobre la preferencia del ecosistema o la superioridad del diseño requieren fuentes fuera de estos archivos de implementación.

Los comentarios son una de las razones por las que los mantenedores pueden preferir el autor TOML, pero la entrada JSON no contiene ninguno para transferir. El documento generado es una serialización de valor inicial. Después hay que añadir la explicación humana y la organización específica del proyecto.

Lo que este convertidor demuestra sobre TOML en lugar de la defensa general del formato

Cadenas, números finitos, booleanos, objetos anidados y matrices compatibles con smol-toml convierten mecánicamente. Los conjuntos de objetos pueden convertirse en conjuntos de tablas; Los objetos anidados pueden convertirse en encabezados de tablas. Unicode y las nuevas líneas escapadas sobreviven a los viajes de ida y vuelta probados para valores ordinarios.

TOML las reglas de matriz pueden rechazar formas que su escritor no puede expresar, y el error nombra esa falla en lugar de coaccionar silenciosamente. Llamar a todas las matrices homogéneas de antemano simplificaría demasiado el comportamiento probado de la dependencia, que incluso lee matrices heterogéneas. Utilice la conversión real como puerta.

Qué se convierte mecánicamente, incluidas las matrices que acepta el escritor TOML

Nulo no tiene representación TOML. Las propiedades de los objetos que contienen valores nulos se omiten y se enumeran en una advertencia. Un valor nulo dentro de una matriz se convierte en una cadena vacía, por lo que los índices posteriores no cambian; ese reemplazo también se nombra. Ninguno de los resultados conserva el valor original.

Decida qué significa nulo antes de aceptar cualquiera de los cambios. Puede significar heredar un valor predeterminado, borrar explícitamente un campo o no proporcionar ningún valor. Eliminar la clave o sustituir texto vacío puede alterar la semántica de la aplicación, así que resuélvalo según el modelo de configuración documentado del destino.

Donde el estilo necesita un ser humano: elegir entre encabezados de [tabla], claves de puntos y tablas en línea, y agrupar claves relacionadas para que el archivo se lea bien

El árbol no dice si los mantenedores prefieren `[tool.linter]`, claves de puntos o tablas en línea. Un serializador elige una sintaxis válida, mientras que un humano elige una agrupación que deja clara la propiedad y las opciones relacionadas. La clasificación de claves puede hacer que la salida sea determinista, pero puede separar conceptos que van juntos.

Conserve una pequeña diferencia y agregue comentarios después de verificar los valores. Convertir TOML nuevamente a JSON más adelante no puede restaurar esos comentarios ni la ortografía de la tabla elegida. El estilo es información creada fuera del modelo de valor simple.

Ejemplo resuelto: configuración JSON de un linter a TOML: convertir, resolver dos valores nulos y reagrupar el resultado bajo un encabezado [tool.linter]

Convertir `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. Se acepta el objeto raíz. `preview` se omite; el miembro nulo de la matriz se convierte en una cadena vacía; las advertencias nombran ambas rutas. El objeto anidado restante se serializa en TOML tablas elegidas por el escritor.

Antes de guardar, decida si la vista previa debe ser falsa, ausente u otro valor documentado, y si una entrada de exclusión vacía es válida. Luego reagrupe y comente la tabla para los lectores. El ejemplo demuestra por qué la conversión es mecánica mientras que la migración es semántica.

Lo que esto no cubre: si la herramienta de destino realmente lee TOML y sus nombres clave específicos, que solo su documentación puede indicarle.

Un archivo TOML válido no prueba que una herramienta lea TOML, reconozca la sección o interprete las claves como el antiguo consumidor JSON. Verifique la documentación de destino actual y ejecute su propio comando de validación o ejecución en seco. ToolAcre nunca importa un esquema de aplicación.

Las fechas también merecen atención en la dirección inversa. TOML: los valores temporales nativos se convierten en cadenas cuando se leen en JSON, por lo que un viaje de ida y vuelta posterior los cita. Una cadena migratoria que cruza ambas direcciones no puede considerarse sin pérdidas.

Conclusión: primero convierta, luego edite para facilitar la lectura y cómo el panel de convertidores de sintaxis realiza la parte mecánica en su navegador

Convierta primero para exponer incompatibilidades mecánicas, luego edítelo por semántica y legibilidad. Conserve el original, revise cada advertencia y pruebe con el objetivo real. El manejo de nulos y la forma de la raíz son límites estrictos; La organización de la mesa es una decisión de diseño humano.

Los convertidores de sintaxis eliminan el trabajo de sintaxis repetitivo sin inventar conocimientos de aplicaciones. Esa división hace que el resultado sea útil: una estructura producida por una máquina para su revisión, seguida de elecciones deliberadas cuando los formatos o herramientas no coinciden.

Mantenga una nota de migración por cada advertencia que acepte. Si un valor nulo se convierte en ausencia, indique el destino predeterminado que hace que la ausencia sea correcta. Si un miembro nulo de la matriz se convierte en texto vacío, explique por qué el índice es importante y por qué el texto vacío es válido. Si el escritor rechaza una matriz mixta, rediseñe ese valor en lugar de forzarlo en privado. Estas decisiones son el registro duradero de la migración; el TOML generado por sí solo no puede explicárselo al siguiente mantenedor.