将 JSON 配置迁移到 TOML：什么会转换以及什么需要人工

setup.cfg 和 settings.json 时代即将结束——一个将配置合并到 pyproject.toml 和需要移动的 JSON 块的项目

项目有时会将设置合并到一个 TOML 文件中，但存储库无法支持大纲中“时代正在结束”的说法。实际任务范围较小：将 JSON 形状的对象移动到 TOML 表中，检查损失，然后验证目标应用程序是否确实识别生成的密钥。

ToolAcre 需要 TOML 输出的根对象。拒绝根数组、字符串、数字、布尔值或 null，因为 TOML 文档是一个表。早期的形状检查可以防止发明的包装器看起来像应用程序批准的配置。

配置整合是一个项目选择，而不是旧格式的通用结束

转换器证明了具体的机制： TOML 有表、数组和标量值；它的编写器将嵌套对象转换为有效的 TOML 结构。它也没有 null 并使用与 JSON 大括号不同的语法。关于生态系统偏好或设计优越性的主张需要这些实施文件之外的来源。

注释是维护者可能更喜欢编写 TOML 的原因之一，但 JSON 输入不包含任何内容。生成的文档是起始值序列化。之后必须添加人工解释和特定于项目的组织。

该转换器证明了 TOML 而不是一般格式倡导

smol-toml 支持的字符串、有限数字、布尔值、嵌套对象和数组进行机械转换。对象数组可以变成表数组；嵌套对象可以成为表头。 Unicode 和转义换行符可以通过普通值的往返测试。

TOML 数组规则可以拒绝其编写者无法表达的形状，并且错误名称失败而不是默默地强制。提前将所有数组称为同质数组会过度简化依赖项的测试行为，甚至会读取异构数组。以实际转换为门。

机械转换的内容，包括 TOML writer 接受的数组

Null 没有 TOML 表示。保留 null 的对象属性将被省略并在警告中列出。数组内的 null 会变成空字符串，因此后面的索引不会移动；该替代品也被命名。这两种结果都不会保留原始值。

在接受任何更改之前确定 null 的含义。这可能意味着继承默认值、显式清除字段或不提供任何值。删除密钥或替换空文本可能会改变应用程序语义，因此请根据目标记录的配置模型来解析它。

样式需要人为的地方 - 在[表]标题、点键和内联表之间进行选择，并对相关键进行分组，以便文件阅读良好

该树没有说明维护者是否更喜欢 `[tool.linter]`、点键或内联表。序列化程序选择有效的语法，而人类选择使所有权和相关选项清晰的分组。排序键可以使输出具有确定性，但可能会分离属于在一起的概念。

保留一个小的差异并在验证值后添加注释。稍后将 TOML 转换回 JSON 无法恢复这些注释或所选的表拼写。风格是在简单价值模型之外创作的信息。

工作示例：linter 的 JSON 配置为 TOML — 转换、解析两个空值并将结果重新分组到 [tool.linter] 标头下

转换 `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`。根对象被接受。 `preview` 被省略； null 数组成员变成空字符串；警告命名了这两条路径。剩余的嵌套对象在作者选择的 TOML 表下序列化。

在保存之前，确定预览是否应为 false、不存在或其他记录值，以及空的排除条目是否有效。然后重新整理表格并为读者进行评论。该示例说明了为什么转换是机械的，而迁移是语义的。

这不包括什么 - 目标工具是否实际读取 TOML 及其具体键名称，只有其文档可以告诉您

有效的 TOML 文件不能证明工具可以读取 TOML、识别该部分或像旧的 JSON 使用者一样解释键。检查当前目标文档并运行其自己的验证或试运行命令。 ToolAcre 从不导入应用程序架构。

日期也值得反向关注。 TOML-本机时间值在读入 JSON 时会变成字符串，因此稍后的往返会引用它们。跨越两个方向的迁移链不能称为无损。

要点：先转换，然后编辑以提高可读性 - 以及语法转换器面板如何在浏览器中执行机械部分

首先进行转换以暴露机械不兼容性，然后进行语义和可读性编辑。保留原始内容，查看每个警告并根据实际目标进行测试。空处理和根形状是硬边界；表格组织是人为设计的决定。

语法转换器消除了重复的语法工作，而无需发明应用程序知识。这种划分使得输出变得有用：机器生成的结构供审查，然后在格式或工具不一致的地方进行深思熟虑的选择。

为您接受的每个警告保留迁移注释。如果空值变为缺席，请说明使缺席正确的目标默认值。如果空数组成员变成空文本，请解释为什么索引很重要以及为什么空文本有效。如果编写者拒绝混合数组，请重新设计该值，而不是私下强制它。这些决定是持久的迁移记录；仅生成的 TOML 无法向下一个维护者解释它们。