A resposta curta
- TOML é um formato de configuração em texto que mapeia chaves e valores sem ambiguidade para uma tabela hash, com nomes sensíveis a maiúsculas e minúsculas e codificação UTF-8 válida obrigatória.
- Abra o arquivo em um editor de texto. No Windows, use Abrir; no Mac, escolha o modo de texto simples; no celular, use um aplicativo que abra texto UTF-8. Mantenha UTF-8 ao salvar. A visualização não valida a sintaxe. Python pode analisar o conteúdo com tomllib.load() ou tomllib.loads(); documentos inválidos geram TOMLDecodeError.
- O registro da IANA informa que TOML não contém conteúdo executável. Ainda assim, entradas maliciosas podem consumir muita CPU e memória durante a análise. Limite o tamanho dos dados antes de analisá-los. Uma análise bem-sucedida não comprova a confiabilidade do conteúdo.
Arquivos TOML: abrir, editar e converter configurações
TOML significa Tom's Obvious, Minimal Language. Usa key = value e aceita strings, inteiros, números de ponto flutuante, booleanos, datas e horas, arrays, tabelas e arrays de tabelas. Comentários começam com #. O tipo de mídia registrado é application/toml, a extensão é .toml e não há bytes mágicos fixos.
tomllib lê TOML como dicionários Python, mas não grava TOML. A documentação do Python recomenda TOML Kit para editar arquivos existentes preservando o estilo. Passar por um dicionário não garante a preservação de comentários e formatação. Números de ponto flutuante podem sofrer arredondamento; parse_float permite selecionar decimal.Decimal.
Como abrir
Abra o arquivo em um editor de texto. No Windows, use Abrir; no Mac, escolha o modo de texto simples; no celular, use um aplicativo que abra texto UTF-8. Mantenha UTF-8 ao salvar. A visualização não valida a sintaxe. Python pode analisar o conteúdo com tomllib.load() ou tomllib.loads(); documentos inválidos geram TOMLDecodeError.
Abra o arquivo em um editor de texto. No Windows, use Abrir; no Mac, escolha o modo de texto simples; no celular, use um aplicativo que abra texto UTF-8. Mantenha UTF-8 ao salvar. A visualização não valida a sintaxe. Python pode analisar o conteúdo com tomllib.load() ou tomllib.loads(); documentos inválidos geram TOMLDecodeError.
tomllib lê TOML como dicionários Python, mas não grava TOML. A documentação do Python recomenda TOML Kit para editar arquivos existentes preservando o estilo. Passar por um dicionário não garante a preservação de comentários e formatação. Números de ponto flutuante podem sofrer arredondamento; parse_float permite selecionar decimal.Decimal.
Segurança
O registro da IANA informa que TOML não contém conteúdo executável. Ainda assim, entradas maliciosas podem consumir muita CPU e memória durante a análise. Limite o tamanho dos dados antes de analisá-los. Uma análise bem-sucedida não comprova a confiabilidade do conteúdo.
Remetente desconhecido, nome terminando em duas extensões ou conteúdo que não bate com a extensão: confira antes de abrir.
Como converter
tomllib lê TOML como dicionários Python, mas não grava TOML. A documentação do Python recomenda TOML Kit para editar arquivos existentes preservando o estilo. Passar por um dicionário não garante a preservação de comentários e formatação. Números de ponto flutuante podem sofrer arredondamento; parse_float permite selecionar decimal.Decimal.
Converta uma cópia, nunca o original, e depois compare qualidade, metadados e diagramação com o arquivo de partida.
Perguntas frequentes
O que é um arquivo TOML e para que serve?
É um arquivo de configuração em texto com atribuições key = value que correspondem sem ambiguidade a uma tabela hash. Diferencia maiúsculas de minúsculas e exige UTF-8 válido.
Como abrir um arquivo TOML no Windows?
Inicie um editor de texto e selecione o arquivo .toml pelo comando Abrir. Se o filtro ocultar o arquivo, escolha todos os arquivos. Salve as alterações em UTF-8.
Como editar um arquivo TOML no Mac?
Abra o arquivo em um editor no modo de texto simples. Preserve a sintaxe key = value e salve como texto UTF-8 com a extensão .toml.
Como abrir um arquivo TOML no celular?
Use um aplicativo de texto capaz de abrir arquivos UTF-8 e selecione o .toml. O acesso e as opções de edição dependem do aplicativo. Exibir o texto não valida a sintaxe TOML.
Por que aparece TOMLDecodeError ao ler um arquivo TOML?
Esse erro indica que o Python encontrou um documento TOML inválido. Revise atribuições, aspas, declarações de tabelas e UTF-8. Verifique a versão: Python 3.11 trouxe tomllib com TOML 1.0.0; Python 3.15 acrescenta TOML 1.1.0.
Devo usar um editor de texto ou um analisador Python para TOML?
Use o editor para ler ou alterar o texto. Use tomllib para obter um dicionário e detectar TOML inválido. tomllib apenas lê; ele não grava arquivos nem preserva uma representação textual editável.
Como converter TOML sem perder comentários e formatação?
A passagem por um dicionário não garante a conservação do estilo original. A documentação do Python recomenda TOML Kit para edição com preservação de estilo e suporte a leitura e escrita. Confira os comentários e a formatação do resultado.
Quais são os riscos de analisar um arquivo TOML não confiável?
A IANA informa que TOML não contém conteúdo executável, mas entradas maliciosas podem consumir muita CPU e memória. Limite o tamanho antes da análise; não há aqui um limite universal que garanta segurança.
A precisão dos números de ponto flutuante em TOML pode mudar?
Sim. TOML recomenda pelo menos IEEE 754 binary64, e valores com mais de 15 dígitos decimais significativos podem ser arredondados. Em tomllib, parse_float=decimal.Decimal permite escolher um tipo decimal.
Como ler arquivos TOML com Python?
Use tomllib.load() com um arquivo aberto em modo binário ou tomllib.loads() com uma string. Ambos retornam um dicionário. O módulo está na biblioteca padrão desde Python 3.11 e só faz leitura.
Uma análise bem-sucedida de TOML comprova que a configuração é confiável?
Não. Ela indica apenas que o analisador aceitou o documento. Não confirma a origem, a exatidão dos valores ou a adequação da configuração ao uso pretendido.
Formatos relacionados
Fontes
TOML v1.1.0 官方规范 · TOML 官方项目
application/toml 媒体类型登记 · IANA
tomllib — Parse TOML files · Python 官方文档
Tom's Obvious, Minimal Language · 美国国会图书馆