Проверяемые примеры

Фрагмент в статье помогает увидеть структуру, но скачиваемый пример даёт возможность воспроизвести операцию. Между ними не должно быть скрытых различий в кодировке, переносах и обязательных полях. Если показано сокращённое описание бинарного формата, его нужно так и назвать. Текстовая схема Parquet не является настоящим Parquet-файлом.

У каждого примера должна быть конкретная задача: проверить парсер, показать null, продемонстрировать quoting или воспроизвести резервную копию. Набор из двух согласованных записей часто полезнее случайной большой таблицы. Для связанных форматов сохраняйте одинаковые идентификаторы и значения, чтобы результат конвертации можно было сопоставить без догадок.

Успешный json.tool подтверждает синтаксис JSON, но не контракт полей. ElementTree подтверждает разбор XML, но не XSD. Чтение первых байтов SQLite не подтверждает целостность страниц. Для каждой команды укажите, что она проверяет и чего не устанавливает. Это позволяет использовать простую проверку честно, не создавая ложной гарантии.

Бинарный образец следует создавать реальным кодировщиком. SQLite доступен через стандартную библиотеку Python, поэтому нет причин публиковать файл с расширением sqlite и текстом внутри. Для формата, которому нужен отсутствующий внешний инструмент, допустимо дать корректный исходник схемы и описать зависимость. Нельзя подменять контейнер заглушкой ради количества загрузок.

Команды должны работать в отдельном каталоге и создавать новые имена. Режим x в Python помогает не затереть существующий результат. Shell-перенаправление по умолчанию перезаписывает файл ещё до запуска программы, поэтому для примеров полезны subshell с set -C или явное предупреждение. Не нужно sudo для чтения локальной таблицы и создания собственной копии.

Образцы конфигурации содержат только очевидно ложные значения. Даже случайная строка, похожая на ключ, создаёт ненужную неоднозначность при сканировании. Адреса и контакты в примерах должны быть условными. В публичный каталог не должны попадать локальные журналы, реальные базы или файлы окружения оператора, даже если они удобны для быстрой проверки.

Каждый новый пример увеличивает обязательства проверки. Полезно иметь явный список поддерживаемых артефактов и назначение каждого из них, чтобы случайный служебный файл не стал публичной загрузкой. Для таблицы укажите число записей и правила пустых значений; для календаря — условный UID и фиксированный момент; для SQL — диалект и ограниченный набор безопасных операторов. Не добавляйте двоичный пример только ради расширения, если нет надёжного способа проверить его чтение. Лучше честно описать зависимость внешнего инструмента. При редакционном изменении сначала обновите исходник, затем пересоберите весь набор и проверьте связанные страницы. Ручная правка одного HTML-хеша создаёт вторую истину, которая исчезнет при следующей сборке и запутает пользователя.

После генерации посчитайте размер и SHA-256 по фактическим байтам, затем сверяйте эти значения с HTML, manifest и checksums.txt. Проверка не должна доверять только одному из этих источников. Если метаданные созданы из старой копии, интерфейс будет показывать убедительный, но неверный отпечаток. Воспроизводимая сборка помогает заметить такое расхождение.

Добавьте несколько структурных проверок: одинаковое число строк CSV и JSON, наличие таблицы items в SQLite, корректные CRLF в календаре, обязательные свойства схемы. Не превращайте маленький пример в полный тестовый набор стандарта. Важно, чтобы он проверял заявленную операцию и не демонстрировал ошибку как нормальное использование.

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