用于解析、验证和创建 SPDX 文档的 Python 库

CI 状态（Linux、macOS 和 Windows）：

破坏性变更 v0.7 -> v0.8

请注意，即将发布的 0.8 版本为迎接即将到来的 SPDX v3.0 版本进行了重大重构，导致 API 出现破坏性变更。 请参考 迁移指南 来更新您现有的代码。

v0.8 的主要特性包括：

• 针对 v2.2 和 v2.3 规范对 SPDX 文档进行全面验证
• 支持 SPDX 的 RDF 格式，并包含所有 v2.3 特性
• 对即将推出的 SPDX v3 规范的实验性支持。但请注意，目前该支持既不完整也不稳定，因为该规范仍在演进中。与 SPDX3 相关的代码包含在一个独立的子包 "spdx3" 中，其使用是可选的。我们建议您暂时不要在生产代码中使用它。

请注意，v0.8 仅支持写入，不支持读取 SPDX 3.0 文档。 详情请参见 #760。

信息

该库以 Python 实现了 SPDX 解析器、转换器、验证器和处理器。

• 主页：https://github.com/spdx/tools-python
• 问题追踪：https://github.com/spdx/tools-python/issues
• PyPI：https://pypi.python.org/pypi/spdx-tools
• 浏览 API：https://spdx.github.io/tools-python

有关此库的重要更新会通过 SPDX 技术邮件列表分享：https://lists.spdx.org/g/Spdx-tech。

许可证

Apache-2.0

特性

• 用于创建和操作 SPDX v2.2 和 v2.3 文档的 API
• 解析、转换、创建和验证 SPDX 文件
• 支持的格式：Tag/Value、RDF、JSON、YAML、XML
• 通过创建 AGraph 来可视化 SPDX 文档的结构。 注意：这是一个可选特性，需要额外安装可选依赖项

对 SPDX 3.0 的实验性支持

• 创建 v3.0 元素和有效载荷（payload）
• 将 v2.2/v2.3 文档转换为 v3.0
• 序列化为 JSON-LD

请参阅下面的 SPDX 3.0 快速入门。 该实现基于仓库 https://github.com/spdx/spdx-3-model 中的描述性 Markdown 文件 （提交：a5372a3c145dbdfc1381fc1f791c68889aafc7ff）。 最新的 SPDX 3.0 模型可在 https://spdx.github.io/spdx-spec/v3.0/serializations/ 获取。

安装

和往常一样，您应该在虚拟环境（venv）中工作。您可以使用 yourenv/bin/pip install . 安装本仓库的本地克隆，也可以从 PyPI 安装 （请查看 最新版本，并像这样安装： yourenv/bin/pip install spdx-tools==0.8.3）。请注意，在 Windows 上应为 Scripts 而不是 bin。

使用方法

命令行用法

1. 解析/验证（用于解析任何格式）：

   • 使用 pyspdxtools -i <文件名>，其中 <文件名> 是文件的位置。输入格式会根据文件扩展名自动推断。

   • 如果您使用的是源代码发行版，请尝试运行： pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. 转换（用于将一种格式转换为另一种格式）：

   • 使用 pyspdxtools -i <输入文件> -o <输出文件>，其中 <输入文件> 是要转换的文件位置， 而 <输出文件> 是输出文件的位置。输入和输出格式会根据文件扩展名自动推断。

   • 如果您使用的是源代码发行版，请尝试运行： 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

库用法

1. 数据模型

   • spdx_tools.spdx.model 包构成了内部 SPDX v2.3 数据模型（v2.2 只是它的一个子集）。所有与 SPDX 文档创建相关的类都在 此处 的 __init__.py 中导出。
   • SPDX 对象通过 @dataclass_with_properties 实现，这是 @dataclass 的自定义扩展。
   • 每个类都以一个属性列表及其可能类型开头。当未提供默认值时，该属性是必填项，必须在初始化期间设置。
   • 借助类型提示，在初始化新实例或在实例上设置/获取属性时会强制进行类型检查 （错误的类型将分别引发 ConstructorTypeError 或 TypeError）。这使得尽早捕获无效属性并仅构造有效文档变得容易。
   • 注意：原地操作如 list.append(item) 会绕过类型检查（当再次读取 list 时仍会引发 TypeError）。我们建议改用 list = list + [item]。
   • SPDX 文档的主要入口点是来自 document.py 模块的 Document 类，它链接到所有其他类。
   • 对于许可证处理，使用了 库。

示例

以下是一些可能用例的示例，可帮助您快速上手 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、SpdxDocument 等。 为了序列化，所有要序列化到同一文件中的元素都被收集到一个 Payload 中。 这只是一个字典，将每个元素的 SpdxId 映射到其自身。 使用 write_payload() 函数来序列化有效载荷。 目前有两种选择：

• spdx_tools.spdx3.writer.json_ld.json_ld_writer 模块会生成该有效载荷的 JSON-LD 文件。
• spdx_tools.spdx3.writer.console.payload_writer 模块会向控制台输出调试信息。请注意，这不是 SPDX 规范的一部分，一旦有更好的标准出现，它可能会被移除。

您可以通过 spdx_tools.spdx3.bump_from_spdx2.spdx_document 模块将 SPDX v2 文档转换为 v3。 bump_spdx_document() 函数将返回一个有效载荷，其中包含一个 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 了解如何向代码库做出贡献的说明。

历史

这是 @ah450（或 https://github.com/a-h-i）最初 GSoC 贡献的成果，并由一个由 SPDX 采用者和爱好者组成的社区维护。 为了准备 SPDX v3.0 的发布，该仓库在 2022 年 11 月至 2023 年 7 月期间进行了重大重构。