Миграция конфига JSON в TOML: что конвертирует и что нужно человеку

Эпоха setup.cfg и settings.json заканчивается — проект, объединяющий конфигурацию в блоки pyproject.toml и JSON, которые необходимо переместить

Иногда проекты объединяют настройки в один файл TOML, но репозиторий не может поддержать утверждение схемы о том, что «эра заканчивается». Практическая задача уже: переместить объект в форме JSON в таблицу TOML, проверить потери, затем убедиться, что целевое приложение действительно распознает полученные ключи.

ToolAcre требует корневого объекта для вывода TOML. Корневой массив, строка, число, логическое значение или значение NULL отклонены, поскольку документ TOML является таблицей. Эта ранняя проверка формы не позволяет изобретенной оболочке выглядеть как конфигурация, одобренная приложением.

Консолидация конфигурации — это выбор проекта, а не универсальный конец старых форматов.

Конвертер подтверждает конкретную механику: TOML имеет таблицы, массивы и скалярные значения; его автор превращает вложенные объекты в действительные структуры TOML. Он также не имеет нулевого значения и использует синтаксис, отличный от фигурных скобок JSON. Заявления о предпочтениях экосистемы или превосходстве дизайна требуют источников за пределами этих файлов реализации.

Комментарии являются одной из причин, по которой сопровождающие могут предпочесть авторский TOML, однако входные данные JSON не содержат ничего, что можно было бы перенести. Сгенерированный документ представляет собой сериализацию начального значения. Человеческое объяснение и организация, специфичная для проекта, должны быть добавлены позже.

Что этот конвертер доказывает о TOML, а не об общей защите формата

Строки, конечные числа, логические значения, вложенные объекты и массивы, поддерживаемые smol-toml, преобразуются механически. Массивы объектов могут стать массивами таблиц; вложенные объекты могут стать заголовками таблиц. Юникод и экранированные символы новой строки выдерживают проверку обычных значений.

Правила массива TOML могут отклонять формы, которые их автор не может выразить, и ошибка называет это неудачей, а не приводит к молчаливому принуждению. Заранее называя все массивы однородными, мы слишком упростили бы тестируемое поведение зависимости, которая читает даже гетерогенные массивы. Используйте фактическую конверсию в качестве ворот.

Что преобразуется механически, включая массивы, которые принимает модуль записи TOML.

Null не имеет представления TOML. Свойства объекта, содержащие нулевое значение, опускаются и перечисляются в предупреждении. Нуль внутри массива становится пустой строкой, поэтому последующие индексы не смещаются; эта замена также названа. Ни один из результатов не сохраняет исходное значение.

Решите, что означает значение null, прежде чем принимать любое изменение. Это может означать наследование значения по умолчанию, явную очистку поля или отсутствие указания значения. Удаление ключа или замена пустого текста может изменить семантику приложения, поэтому разрешите это в соответствии с документированной моделью конфигурации назначения.

Там, где стиль требует участия человека — выбор между заголовками [таблиц], пунктирными ключами и встроенными таблицами, а также группировка связанных ключей, чтобы файл хорошо читался.

В дереве не указано, предпочитают ли сопровождающие `[tool.linter]`, ключи с точками или встроенные таблицы. Сериализатор выбирает допустимый синтаксис, а человек выбирает группировку, которая четко определяет принадлежность и связанные параметры. Сортировка ключей может сделать вывод детерминированным, но может разделить понятия, которые принадлежат друг другу.

Сохраняйте небольшие различия и добавляйте комментарии после проверки значений. Преобразование TOML обратно в JSON позднее не сможет восстановить эти комментарии или выбранное написание таблицы. Стиль — это авторская информация, находящаяся за пределами модели простых значений.

Рабочий пример: конфигурация JSON линтера в TOML — преобразование, разрешение двух нулевых значений и перегруппировка результата под заголовком [tool.linter]

Преобразуйте `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. Корневой объект принят. `preview` опущен; нулевой элемент массива становится пустой строкой; предупреждения называют оба пути. Оставшийся вложенный объект сериализуется в таблицах TOML, выбранных автором записи.

Перед сохранением решите, должно ли предварительное значение быть ложным, отсутствовать или иметь другое документированное значение, а также допустима ли пустая запись исключения. Затем перегруппируйтесь и прокомментируйте таблицу для читателей. Этот пример демонстрирует, почему преобразование является механическим, а миграция — семантической.

Чего это не касается — действительно ли целевой инструмент читает TOML и его конкретные имена ключей, о которых вам может сообщить только его документация.

Действительный файл TOML не доказывает, что инструмент читает TOML, распознает раздел или интерпретирует ключи, как старый потребитель JSON. Проверьте текущую целевую документацию и запустите собственную команду проверки или пробного прогона. ToolAcre никогда не импортирует схему приложения.

Финики также заслуживают ухода и в обратном направлении. Собственные временные значения TOML становятся строками при чтении в JSON, поэтому при последующем обращении они цитируются. Цепочку миграции, пересекающую оба направления, нельзя назвать без потерь.

Вывод: сначала конвертируйте, затем редактируйте для удобства чтения — и как панель конвертеров синтаксиса выполняет механическую часть в вашем браузере

Сначала преобразуйте, чтобы выявить механическую несовместимость, затем отредактируйте семантику и читабельность. Сохраните оригинал, просмотрите каждое предупреждение и протестируйте с реальной целью. Обработка нулей и форма корня — это жесткие границы; Организация стола — это дизайнерское решение человека.

Преобразователи синтаксиса устраняют повторяющуюся синтаксическую работу, не прибегая к знаниям приложений. Такое разделение делает результат полезным: машинная структура для проверки, за которой следует осознанный выбор там, где форматы или инструменты не совпадают.

Сохраняйте примечания о переносе для каждого принятого вами предупреждения. Если нуль становится отсутствием, укажите назначение по умолчанию, которое делает отсутствие правильным. Если нулевой элемент массива становится пустым текстом, объясните, почему индекс имеет значение и почему пустой текст допустим. Если средство записи отклоняет смешанный массив, измените это значение вместо того, чтобы принудить его в частном порядке. Эти решения являются долговременным миграционным рекордом; сгенерированный TOML сам по себе не может объяснить их следующему сопровождающему.