Python library to parse, validate and create SPDX documents

Статус CI (Linux, macOS и Windows):

Критические изменения v0.7 -> v0.8

Обратите внимание, что предстоящий релиз 0.8 подвергся значительному рефакторингу в рамках подготовки к предстоящему релизу SPDX v3.0, что привело к критическим изменениям в API. Пожалуйста, обратитесь к руководству по миграции, чтобы обновить существующий код.

Основные возможности v0.8:

• полная проверка SPDX-документов на соответствие спецификациям v2.2 и v2.3
• поддержка формата RDF для SPDX со всеми возможностями v2.3
• экспериментальная поддержка предстоящей спецификации SPDX v3. Однако учтите, что поддержка пока не является ни полной, ни стабильной, поскольку спецификация всё ещё развивается. Код, связанный с SPDX3, содержится в отдельном подпакете "spdx3", и его использование необязательно. Мы пока не рекомендуем использовать его в production-коде.

Обратите внимание, что v0.8 поддерживает только запись, но не чтение SPDX 3.0-документов. Подробности см. в #760.

Информация

Эта библиотека реализует парсеры, конвертеры, валидаторы и обработчики SPDX на Python.

• Домашняя страница: https://github.com/spdx/tools-python
• Вопросы (Issues): https://github.com/spdx/tools-python/issues
• PyPI: https://pypi.python.org/pypi/spdx-tools
• Просмотр API: https://spdx.github.io/tools-python

Важные обновления, касающиеся этой библиотеки, публикуются в списке рассылки SPDX tech: https://lists.spdx.org/g/Spdx-tech.

Лицензия

Apache-2.0

Возможности

• API для создания и работы с документами SPDX v2.2 и v2.3
• Разбор, конвертация, создание и проверка SPDX-файлов
• Поддерживаемые форматы: Tag/Value, RDF, JSON, YAML, XML
• Визуализация структуры SPDX-документа с помощью создания AGraph. Примечание: это опциональная возможность и требует дополнительной установки опциональных зависимостей

Экспериментальная поддержка SPDX 3.0

• Создание элементов и полезных нагрузок v3.0
• Конвертация документов v2.2/v2.3 в v3.0
• Сериализация в JSON-LD

См. Краткое руководство по SPDX 3.0 ниже. Реализация основана на описательных Markdown-файлах в репозитории https://github.com/spdx/spdx-3-model (коммит: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). Последняя модель SPDX 3.0 доступна по адресу https://spdx.github.io/spdx-spec/v3.0/serializations/.

Установка

Как всегда, вам следует работать в virtualenv (venv). Вы можете установить локальную копию этого репозитория с помощью yourenv/bin/pip install . или установить её из PyPI (проверьте последний релиз и установите его, например, так: yourenv/bin/pip install spdx-tools==0.8.3). Обратите внимание, что в Windows вместо bin будет Scripts.

Как использовать

Использование командной строки

1. РАЗБОР/ПРОВЕРКА (для разбора любого формата):

   • Используйте pyspdxtools -i <filename>, где <filename> — путь к файлу. Формат входных данных определяется автоматически по расширению файла.

   • Если вы используете дистрибутив из исходного кода, попробуйте выполнить: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. КОНВЕРТАЦИЯ (для конвертации одного формата в другой):

   • Используйте pyspdxtools -i <input_file> -o <output_file>, где <input_file> — путь к файлу, который нужно конвертировать, а <output_file> — путь к выходному файлу. Форматы ввода и вывода определяются автоматически по расширениям файлов.

   • Если вы используете дистрибутив из исходного кода, попробуйте выполнить: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • Если вы хотите пропустить процесс проверки, укажите флаг --novalidation, например: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (используйте с осторожностью: незамеченные недействительные документы могут привести к непредвиденному поведению инструмента)

   • Для справки используйте pyspdxtools --help

3. ГЕНЕРАЦИЯ ГРАФА (опциональная возможность)

   • Эта возможность создаёт граф, представляющий все элементы SPDX-документа и их связи на основе предоставленных отношений. Граф можно визуализировать в виде картинки. Ниже приведён пример для файла tests/spdx/data/SPDXJSONExample-v2.3.spdx.json:

   • Убедитесь, что вы установили опциональные зависимости networkx и pygraphviz. Для этого выполните pip install ".[graph_generation]".

   • Используйте pyspdxtools -i <input_file> --graph -o <output_file>, где <output_file> — имя выходного файла с допустимым для pygraphviz форматом (см. документацию здесь).

   • Если вы используете дистрибутив из исходного кода, попробуйте выполнить pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png, чтобы сгенерировать png-файл с обзором структуры примерного файла.

Использование библиотеки

1. МОДЕЛЬ ДАННЫХ

   • Пакет spdx_tools.spdx.model представляет внутреннюю модель данных SPDX v2.3 (v2.2 — просто её подмножество). Все соответствующие классы для создания SPDX-документов доступны в __init__.py, который находится здесь.
   • Объекты SPDX реализованы через @dataclass_with_properties — пользовательское расширение @dataclass.
   • Каждый класс начинается со списка своих свойств и их возможных типов. Если значение по умолчанию не указано, свойство является обязательным и должно быть задано при инициализации.
   • Благодаря аннотациям типов проверка типов выполняется при инициализации нового экземпляра или при установке/чтении свойства экземпляра (неправильные типы вызовут ConstructorTypeError или TypeError соответственно). Это позволяет легко выявлять некорректные свойства на раннем этапе и создавать только валидные документы.
   • Примечание: операции на месте, такие как list.append(item), обходят проверку типов (TypeError всё равно будет вызван при повторном чтении list). Вместо этого мы рекомендуем использовать list = list + [item].
   • Основной точкой входа в SPDX-документ является класс Document из модуля document.py, который связывает все остальные классы.
   • Для работы с лицензиями используется библиотека license_expression.
   • Примечание о documentDescribes и hasFiles: эти поля будут преобразованы в отношения во внутренней модели данных. Поскольку они устарели, эти поля не будут записаны в выходные данные.

2. РАЗБОР

   • Используйте parse_file(file_name) из модуля parse_anything.py для разбора произвольного файла с одним из поддерживаемых расширений.
   • При успешном разборе будет возвращён экземпляр Document. При неудачном разборе будет вызвано исключение SPDXParsingError со списком всех обнаруженных проблем.

3. ПРОВЕРКА