Migrando uma configuração JSON para TOML: o que converte e o que precisa de um ser humano

A era setup.cfg e settings.json está terminando — um projeto consolidando a configuração em pyproject.toml e os blocos JSON que precisam ser movidos

Às vezes, os projetos consolidam as configurações em um arquivo TOML, mas o repositório não pode suportar a afirmação do esboço de que uma “era está terminando”. A tarefa prática é mais restrita: mover um objeto em forma de JSON para uma tabela TOML, inspecionar as perdas e, em seguida, verificar se o aplicativo de destino realmente reconhece as chaves resultantes.

ToolAcre requer um objeto raiz para saída TOML. Uma matriz raiz, string, número, booleano ou nulo é recusada porque um documento TOML é uma tabela. Essa verificação antecipada do formato evita que um wrapper inventado pareça uma configuração aprovada pelo aplicativo.

A consolidação da configuração é uma escolha do projeto, não o fim universal dos formatos mais antigos

O conversor comprova a mecânica concreta: TOML possui tabelas, arrays e valores escalares; seu escritor transforma objetos aninhados em estruturas TOML válidas. Ele também não possui nulo e usa uma sintaxe diferente dos colchetes JSON. Afirmações sobre preferência de ecossistema ou superioridade de design requerem fontes fora desses arquivos de implementação.

Os comentários são um dos motivos pelos quais os mantenedores podem preferir a autoria de TOML, mas a entrada JSON não contém nenhum para transmitir. O documento gerado é uma serialização de valor inicial. A explicação humana e a organização específica do projeto devem ser adicionadas posteriormente.

O que este conversor prova sobre TOML em vez de defesa do formato geral

Strings, números finitos, booleanos, objetos aninhados e matrizes suportados por smol-toml são convertidos mecanicamente. Matrizes de objetos podem se tornar matrizes de tabelas; objetos aninhados podem se tornar cabeçalhos de tabela. Unicode e novas linhas com escape sobrevivem a viagens de ida e volta testadas para valores comuns.

TOML regras de array podem rejeitar formas que seu escritor não pode expressar, e o erro nomeia essa falha em vez de coagir silenciosamente. Chamar todos os arrays de homogêneos antecipadamente simplificaria demais o comportamento testado da dependência, que até lê arrays heterogêneos. Use a conversão real como porta.

O que é convertido mecanicamente, incluindo matrizes que o gravador TOML aceita

Nulo não tem representação TOML. As propriedades do objeto que contêm nulo são omitidas e listadas em um aviso. Um nulo dentro de um array se torna uma string vazia para que os índices posteriores não mudem; essa substituição também é nomeada. Nenhum dos resultados preserva o valor original.

Decida o que null significa antes de aceitar qualquer alteração. Pode significar herdar um padrão, limpar explicitamente um campo ou nenhum valor fornecido. Excluir a chave ou substituí-la por texto vazio pode alterar a semântica do aplicativo, portanto, resolva isso em relação ao modelo de configuração documentado do destino.

Onde o estilo precisa de um ser humano - escolher entre cabeçalhos [tabela], chaves pontilhadas e tabelas embutidas e agrupar chaves relacionadas para que o arquivo seja bem lido

A árvore não diz se os mantenedores preferem `[tool.linter]`, chaves pontilhadas ou tabelas embutidas. Um serializador escolhe uma sintaxe válida, enquanto um ser humano escolhe um agrupamento que deixa clara a propriedade e as opções relacionadas. As chaves de classificação podem tornar a saída determinística, mas podem separar conceitos que pertencem um ao outro.

Preserve uma pequena diferença e adicione comentários após a verificação dos valores. A conversão de TOML de volta para JSON posteriormente não pode restaurar esses comentários ou a ortografia da tabela escolhida. Estilo é informação de autoria fora do modelo de valor simples.

Exemplo resolvido: configuração JSON de um linter para TOML - convertendo, resolvendo dois valores nulos e reagrupando o resultado sob um cabeçalho [tool.linter]

Converter `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. O objeto raiz é aceito. `preview` é omitido; o membro nulo da matriz se torna uma string vazia; avisos nomeiam ambos os caminhos. O objeto aninhado restante é serializado nas tabelas TOML escolhidas pelo gravador.

Antes de salvar, decida se a visualização deve ser falsa, ausente ou outro valor documentado e se uma entrada de exclusão vazia é válida. Em seguida, reagrupem-se e comentem a tabela para os leitores. O exemplo demonstra por que a conversão é mecânica enquanto a migração é semântica.

O que isso não cobre — se a ferramenta de destino realmente lê TOML e seus nomes de chave específicos, que somente sua documentação pode informar

Um arquivo TOML válido não prova que uma ferramenta lê TOML, reconhece a seção ou interpreta as chaves como o antigo consumidor JSON. Verifique a documentação de destino atual e execute seu próprio comando de validação ou simulação. ToolAcre nunca importa um esquema de aplicativo.

As datas também merecem cuidados no sentido inverso. TOML-valores temporais nativos tornam-se strings quando lidos em JSON, portanto, uma viagem de ida e volta posterior os cita. Uma cadeia de migração que cruza ambas as direções não pode ser chamada de sem perdas.

Conclusão: converta primeiro e depois edite para facilitar a leitura - e como o painel de conversores de sintaxe faz a parte mecânica em seu navegador

Converta primeiro para expor incompatibilidades mecânicas e depois edite para semântica e legibilidade. Mantenha o original, revise cada aviso e teste com o alvo real. O manuseio nulo e o formato da raiz são limites rígidos; a organização da mesa é uma decisão de design humano.

Os conversores de sintaxe eliminam o trabalho repetitivo de sintaxe sem inventar o conhecimento do aplicativo. Essa divisão torna o resultado útil: estrutura produzida por máquina para revisão, seguida de escolhas deliberadas onde os formatos ou ferramentas discordam.

Mantenha uma nota de migração para cada aviso que você aceitar. Se um nulo se tornar ausência, indique o padrão de destino que torna a ausência correta. Se um membro nulo da matriz se tornar um texto vazio, explique por que o índice é importante e por que o texto vazio é válido. Se o escritor rejeitar um array misto, redesenhe esse valor em vez de coagi-lo em particular. Estas decisões constituem o registro duradouro da migração; o TOML gerado sozinho não pode explicá-los ao próximo mantenedor.