CatalogLint

Проверяет полную выгрузку товаров и предложений CommerceML перед загрузкой в интернет-магазин.

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

Запуск

Нужен Python 3.12 или новее.

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1

python -m pip install .
cataloglint examples/import.xml examples/offers.xml --strict
cataloglint examples/import.xml examples/broken-offers.xml --json

Вторая команда найдёт предложение без товара и некорректную цену. Примеры вымышленные и содержат только поля, необходимые для демонстрации проверок; это не полный эталон XSD.

Перед очередной загрузкой

Если есть предыдущая полная выгрузка, добавьте её для контроля исчезнувших товаров:

cataloglint local-data/import.xml local-data/offers.xml \
  --previous-catalog local-data/previous-import.xml \
  --max-removed-percent 20 --strict

Ошибка CATALOG_SHRINK появляется, если исчезло или помечено на удаление больше 20% ранее активных товаров. Ровно 20% допускается. Это настраиваемый порог, не универсальное правило для магазина.

Предыдущий и текущий каталоги должны иметь один Ид. Для частичных обменов инструмент намеренно не подходит: СодержитТолькоИзменения=true отклоняется, чтобы отсутствующий в очередной порции товар не был ошибочно признан удалённым.

Проверки

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

Цена может задать собственную валюту или взять её из типа цены. Ценовые уровни различаются типом цены, единицей измерения, валютой и МинКоличество. Нулевая цена, отрицательный остаток и отсутствие данных об остатке дают предупреждение: в отдельных магазинах это допустимо. --strict делает такие случаи блокирующими.

Составной Ид товар#характеристика сначала ищется целиком; затем проверяется базовый товар. Это распространённое соглашение интеграций, не универсальная семантика всех CommerceML-реализаций. Чтобы требовать точное совпадение, задайте --variant-separator "".

Результат

Коды завершения: 0 — проверка прошла, 1 — найдены ошибки или блокирующие предупреждения, 2 — входные файлы не разобраны либо имеют неподдерживаемую структуру.

--json выводит schema_version, ok, exit_code, количества товаров и предложений и список issues. Каждая ошибка содержит стабильный код и путь вида ПакетПредложений/Предложения/Предложение[2]. Названия товаров и цены не копируются в отчёт.

Инструмент не подключается к 1С или магазину, не переписывает XML и ничего не загружает в сеть.

Границы формата

Поддерживается выбранная структура полных CommerceML 2.x: Каталог/Товары/Товар, ПакетПредложений/Предложения/Предложение, типы цен, общее количество и складские атрибуты. Читаются XML с namespace и без него, а также совмещённый файл — передайте его в оба аргумента.

Это не полная XSD-валидация и не замена правилам конкретного магазина. Заказы, классификаторы, картинки, ассортиментные правила и синонимы валют не проверяются. ПометкаУдаления поддерживается как поле распространённых выгрузок. Остальные расширения формата не интерпретируются. Десятичные значения ограничены 18 цифрами до точки и 6 после; коэффициент должен быть числом.

XML читается в память с ограничениями: 32 MiB на файл, 300 000 элементов, глубина 64. DTD, сущности и внешние ссылки запрещены через defusedxml. После 1000 замечаний отчёт сокращается и проверка завершается неуспешно. Большие каталоги надо делить на отдельные согласованные обмены, а не повышать лимиты вслепую.

Проверки проекта

python -m pip install -c requirements-dev.lock -e ".[dev]"
ruff check .
ruff format --check .
pytest --cov=cataloglint --cov-report=term-missing
python -m build

CI: Windows/Linux, Python 3.12/3.14, установка собранного wheel вне исходного дерева. Тесты проверяют namespace, составные идентификаторы, цены по количеству, удалённые товары, граничный процент потерь и опасный XML.

Основа формата — CommerceML 2 на сайте 1С. Защита XML — defusedxml. Утилита не связана с фирмой 1С.