Migrazione di una configurazione JSON a TOML: cosa converte e cosa ha bisogno di un essere umano

L'era setup.cfg e settings.json sta finendo: un progetto che consolida la configurazione in pyproject.toml e i blocchi JSON che devono essere spostati

I progetti a volte consolidano le impostazioni in un unico file TOML, ma il repository non può supportare l'affermazione della struttura secondo cui "un'era sta finendo". Il compito pratico è più ristretto: spostare un oggetto a forma di JSON in una tabella TOML, ispezionare le perdite, quindi verificare che l'applicazione di destinazione riconosca effettivamente le chiavi risultanti.

ToolAcre richiede un oggetto root per l'output TOML. Un array root, una stringa, un numero, un valore booleano o null viene rifiutato perché un documento TOML è una tabella. Questo controllo anticipato della forma impedisce a un wrapper inventato di sembrare una configurazione approvata dall'applicazione.

Il consolidamento della configurazione è una scelta di progetto, non la fine universale dei formati precedenti

Il convertitore dimostra la meccanica concreta: TOML ha tabelle, array e valori scalari; il suo scrittore trasforma gli oggetti nidificati in strutture TOML valide. Inoltre non ha null e utilizza una sintassi diversa dalle parentesi graffe JSON. Le affermazioni sulla preferenza dell'ecosistema o sulla superiorità del design richiedono fonti esterne a questi file di implementazione.

I commenti sono uno dei motivi per cui i manutentori potrebbero preferire TOML creati, tuttavia l'input JSON non ne contiene nessuno da trasferire. Il documento generato è una serializzazione del valore iniziale. Successivamente è necessario aggiungere la spiegazione umana e l'organizzazione specifica del progetto.

Ciò che questo convertitore dimostra riguardo a TOML piuttosto che alla difesa generale del formato

Stringhe, numeri finiti, booleani, oggetti nidificati e array supportati da smol-toml vengono convertiti meccanicamente. Gli array di oggetti possono diventare array di tabelle; gli oggetti nidificati possono diventare intestazioni di tabella. I ritorni a capo Unicode e con escape sopravvivono ai viaggi di andata e ritorno testati per valori ordinari.

Le regole dell'array TOML possono rifiutare le forme che il suo scrittore non può esprimere e l'errore nomina tale errore anziché forzarlo silenziosamente. Chiamare tutti gli array omogenei in anticipo semplificherebbe eccessivamente il comportamento testato della dipendenza, che legge anche array eterogenei. Utilizza la conversione effettiva come gate.

Ciò che viene convertito meccanicamente, inclusi gli array accettati dal writer TOML

Null non ha alcuna rappresentazione TOML. Le proprietà dell'oggetto che contengono null vengono omesse ed elencate in un avviso. Un valore nullo all'interno di un array diventa una stringa vuota, quindi gli indici successivi non vengono spostati; viene nominata anche quella sostituzione. Nessuno dei due risultati conserva il valore originale.

Decidere cosa significava null prima di accettare una delle modifiche. Potrebbe significare ereditare un valore predefinito, cancellare esplicitamente un campo o non fornire alcun valore. L'eliminazione della chiave o la sostituzione del testo vuoto può alterare la semantica dell'applicazione, quindi risolverlo rispetto al modello di configurazione documentato della destinazione.

Dove lo stile ha bisogno di un essere umano: scegliere tra intestazioni [tabella], chiavi puntate e tabelle in linea e raggruppare le chiavi correlate in modo che il file si legga bene

L'albero non dice se i manutentori preferiscono `[tool.linter]`, chiavi puntate o tabelle in linea. Un serializzatore sceglie una sintassi valida, mentre un essere umano sceglie un raggruppamento che renda chiara la proprietà e le opzioni correlate. Le chiavi di ordinamento possono rendere l'output deterministico ma possono separare concetti che appartengono insieme.

Conserva una piccola differenza e aggiungi commenti dopo aver verificato i valori. La conversione successiva di TOML in JSON non può ripristinare i commenti o l'ortografia della tabella scelta. Lo stile è un'informazione creata al di fuori del modello di valore semplice.

Esempio funzionante: configurazione JSON di un linter in TOML: conversione, risoluzione di due valori null e raggruppamento del risultato sotto un'intestazione [tool.linter]

Converti `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. L'oggetto root è accettato. `preview` è omesso; il membro nullo dell'array diventa una stringa vuota; gli avvisi nominano entrambi i percorsi. L'oggetto nidificato rimanente viene serializzato nelle tabelle TOML scelte dallo scrittore.

Prima di salvare, decidi se l'anteprima deve essere falsa, assente o un altro valore documentato e se una voce di esclusione vuota è valida. Quindi raggrupparsi e commentare la tabella per i lettori. L'esempio dimostra perché la conversione è meccanica mentre la migrazione è semantica.

Cosa non copre: se lo strumento di destinazione legge effettivamente TOML e i nomi delle chiavi specifiche, che solo la sua documentazione può dirti

Un file TOML valido non dimostra che uno strumento legge TOML, riconosce la sezione o interpreta le chiavi come il vecchio consumatore JSON. Controllare la documentazione di destinazione corrente ed eseguire la propria convalida o il comando di prova. ToolAcre non importa mai uno schema dell'applicazione.

Anche le date meritano attenzione nella direzione opposta. I valori temporali TOML-nativi diventano stringhe quando vengono letti in JSON, quindi un viaggio di andata e ritorno successivo li cita. Una catena migratoria che attraversa entrambe le direzioni non può essere definita priva di perdite.

Conclusione: prima converti, poi modifica per migliorare la leggibilità e in che modo il pannello dei convertitori di sintassi esegue la parte meccanica nel tuo browser

Convertire prima per esporre le incompatibilità meccaniche, quindi modificare per semantica e leggibilità. Conserva l'originale, rivedi ogni avviso e prova con l'obiettivo reale. La gestione dei null e la forma della radice sono limiti rigidi; l'organizzazione dei tavoli è una decisione progettuale umana.

I convertitori di sintassi rimuovono il lavoro ripetitivo sulla sintassi senza inventare la conoscenza dell'applicazione. Questa divisione rende utile il risultato: una struttura prodotta dalla macchina per la revisione, seguita da scelte deliberate laddove i formati o gli strumenti non sono d’accordo.

Conserva una nota di migrazione per ogni avviso che accetti. Se un valore nullo diventa assenza, indicare il valore predefinito di destinazione che rende corretta l'assenza. Se un membro dell'array null diventa testo vuoto, spiegare perché l'indice è importante e perché il testo vuoto è valido. Se lo scrittore rifiuta un array misto, riprogetta quel valore invece di forzarlo privatamente. Queste decisioni costituiscono la testimonianza durevole della migrazione; il TOML generato da solo non può spiegarli al successivo manutentore.