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 (используйте с осторожностью: незамеченные недействительные документы могут привести к непредвиденному поведению инструмента)

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

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-tools. Если вам нужно больше примеров, например как создать SPDX-документ с нуля, загляните в папку с примерами.

import logging

from license_expression import get_spdx_licensing

from spdx_tools.spdx.model import (Checksum, ChecksumAlgorithm, File,
                                   FileType, Relationship, RelationshipType)
from spdx_tools.spdx.parser.parse_anything import parse_file
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
from spdx_tools.spdx.writer.write_anything import write_file

# read in an SPDX document from a file
document = parse_file("spdx_document.json")

# change the document's name
document.creation_info.name = "new document name"

# define a file and a DESCRIBES relationship between the file and the document
checksum = Checksum(ChecksumAlgorithm.SHA1, "71c4025dd9897b364f3ebbb42c484ff43d00791c")

file = File(name="./fileName.py", spdx_id="SPDXRef-File", checksums=[checksum],
            file_types=[FileType.TEXT],
            license_concluded=get_spdx_licensing().parse("MIT and GPL-2.0"),
            license_comment="licenseComment", copyright_text="copyrightText")

relationship = Relationship("SPDXRef-DOCUMENT", RelationshipType.DESCRIBES, "SPDXRef-File")

# add the file and the relationship to the document
# (note that we do not use "document.files.append(file)" as that would circumvent the type checking)
document.files = document.files + [file]
document.relationships = document.relationships + [relationship]

# validate the edited document and log the validation messages
# (depending on your use case, you might also want to utilize the validation_message.context)
validation_messages = validate_full_spdx_document(document)
for validation_message in validation_messages:
    logging.warning(validation_message.validation_message)

# if there are no validation messages, the document is valid
# and we can safely serialize it without validating again
if not validation_messages:
    write_file(document, "new_spdx_document.rdf", validate=False)

Краткое руководство по SPDX 3.0

В отличие от SPDX v2, теперь все элементы являются подклассами центрального класса Element. Сюда входят пакеты, файлы, фрагменты, отношения, аннотации, а также SBOM, SpdxDocuments и другие. Для целей сериализации все элементы, которые должны быть сериализованы в один файл, собираются в Payload. Это просто словарь, который сопоставляет SpdxId каждого элемента с самим элементом. Используйте функции write_payload() для сериализации payload. Сейчас есть два варианта:

• Модуль spdx_tools.spdx3.writer.json_ld.json_ld_writer генерирует JSON-LD файл payload.
• Модуль spdx_tools.spdx3.writer.console.payload_writer выводит отладочные данные в консоль. Обратите внимание, что это не является официальной частью спецификации SPDX и, вероятно, будет удалено, как только появится лучший стандарт.

Вы можете конвертировать документ SPDX v2 в v3 с помощью модуля spdx_tools.spdx3.bump_from_spdx2.spdx_document. Функция bump_spdx_document() вернёт payload, содержащий элемент SpdxDocument и по одному элементу для каждого пакета, файла, фрагмента, отношения или аннотации, содержащихся в документе v2.

Зависимости

• PyYAML: https://pypi.org/project/PyYAML/ для работы с YAML.
• xmltodict: https://pypi.org/project/xmltodict/ для работы с XML.
• rdflib: https://pypi.python.org/pypi/rdflib/ для работы с RDF.
• ply: https://pypi.org/project/ply/ для работы с tag-value.
• click: https://pypi.org/project/click/ для создания CLI-интерфейса.
• beartype: https://pypi.org/project/beartype/ для проверки типов.
• uritools: https://pypi.org/project/uritools/ для валидации URI.
• license-expression: https://pypi.org/project/license-expression/ для работы с выражениями SPDX-лицензий.

Поддержка

• Отправляйте вопросы, проблемы или отзывы на https://github.com/spdx/tools-python/issues
• Присоединяйтесь к чату: https://gitter.im/spdx-org/Lobby
• Присоединяйтесь к обсуждению на https://lists.spdx.org/g/spdx-tech и https://spdx.dev/participate/tech/

Участие в разработке

Вклад очень приветствуется! Инструкции о том, как внести вклад в кодовую базу, см. в CONTRIBUTING.md.

История

Это результат первоначального вклада в рамках GSoC от @ah450 (или https://github.com/a-h-i); проект поддерживается сообществом пользователей и энтузиастов SPDX. В рамках подготовки к выпуску SPDX v3.0 репозиторий прошёл серьёзный рефакторинг в период с 11/2022 по 07/2023.