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

CI状态（Linux、macOS和Windows）：

版本0.7 -> 版本0.8的重大变更

请注意，即将推出的0.8版本在为即将到来的SPDX v3.0版本做准备的过程中进行了重大重构，导致API出现破坏性变更。请参阅迁移指南以更新现有的代码。

0.8版本的主要特性包括

• 对SPDX文档进行完全验证，以符合v2.2和v2.3规范
• 支持所有v2.3特性的SPDX的RDF格式
• 对即将推出的SPDX v3规范进行了实验性支持。请注意，目前支持既不完整也不稳定，因为规范仍在演进。与SPDX3相关的代码包含在单独的子包"spdx3"中，其使用是可选的。我们不推荐在生产代码中使用它。

信息

此库使用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文件
• 支持的格式：标签/值、RDF、JSON、YAML、XML
• 通过创建一个AGraph来可视化SPDX文档的结构。注意：这是一个可选功能，需要安装额外的可选依赖项

对SPDX 3.0的实验性支持

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

请参阅下面的SPDX 3.0快速入门。
实现基于存储库https://github.com/spdx/spdx-3-model中的描述性markdown文件（最新提交：a5372a3c145dbdfc1381fc1f791c68889aafc7ff）。

安装

始终在虚拟env（venv）中工作。您可以使用yourenv/bin/pip install .安装此存储库的本地克隆，或者从PyPI安装它（检查最新的版本，然后像这样安装：yourenv/bin/pip install spdx-tools==0.8.0a2）。注意，在Windows上，应该是Scripts而不是bin。

如何使用

命令行使用

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

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

• 如果您正在使用源分发版，请尝试运行以下命令：
  pyspdxtools -i tests/data/SPDXJSONExample-v2.3.spdx.json

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

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

• 如果您正在使用源分发版，请尝试运行以下命令：
  pyspdxtools -i tests/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

• 如果您想跳过验证过程，请提供--novalidation标志，如下所示：
  pyspdxtools -i tests/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation
  （请小心使用：请注意，未检测到的无效文档可能导致工具出现意外行为）

• 使用pyspdxtools --help获取帮助

3. 图形生成（可选功能）

• 本功能根据提供的关联关系，生成表示SPDX文档中所有元素及其连接的图形。该图形可以渲染为图片。以下是对文件tests/data/SPDXJSONExample-v2.3.spdx.json的示例：
• 请确保您已安装可选依赖项 networkx 和 pygraphviz。要这样做，请运行 pip install ".[graph_generation]"。
• 使用 pyspdxtools -i <input_file> --graph -o <output_file>，其中 <output_file> 是一个对 pygraphviz 有效的输出文件名（请在此处检查文档 here）。
• 如果您使用的是源代码分发版，请尝试运行 pyspdxtools -i tests/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) 将绕过类型检查（在再次读取 list 时仍会引发 TypeError）。我们建议使用 list = list + [item]。
• SPDX文档的主要入口点是来自 document.py 模块的 Document 类，它链接到所有其他类。
• 对于许可证处理，使用了 license_expression 库。
• 关于 documentDescribes 和 hasFiles 的说明：这些字段将被转换为内部数据模型中的关系。由于它们已被弃用，因此这些字段将不会写入输出。

2. 解析

• 使用来自 parse_anything.py 模块的 parse_file(file_name) 解析具有支持文件结尾之一的任意文件。
• 成功解析将返回一个 Document 实例。解析失败将引发带有遇到的所有问题的列表的 SPDXParsingError。

3. 验证

• 使用 validate_full_spdx_document(document) 验证 Document 类的实例。
• 这将返回一个包含描述无效性的字符串和用于定位验证错误源的 ValidationContext 的 ValidationMessage 对象列表。
• 验证取决于文档的SPDX版本。请注意，本工具只支持版本 SPDX-2.2 和 SPDX-2.3。

4. 写入

• 使用来自 write_anything.py 模块的 write_file(document, file_name) 将 Document 实例写入指定的文件。序列化格式由文件名后缀确定。
• 默认情况下，在写入过程之前执行验证，如果文档无效则取消写入。您可以通过 write_file(document, file_name, validate=False) 跳过验证。注意：只有有效的文档才能可靠地序列化；不支持无效文档的序列化。

示例

以下是一些可能的用例示例，帮助您快速开始使用 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() 函数来序列化负载。目前有两种选择

• 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.ac.cn/project/PyYAML/ 用于处理 YAML。
• xmltodict: https://pypi.ac.cn/project/xmltodict/ 用于处理 XML。
• rdflib: https://pypi.python.org/pypi/rdflib/ 用于处理 RDF。
• ply: https://pypi.ac.cn/project/ply/ 用于处理标记-值。
• click: https://pypi.ac.cn/project/click/ 用于创建 CLI 界面。
• beartype: https://pypi.ac.cn/project/beartype/ 用于类型检查。
• uritools: https://pypi.ac.cn/project/uritools/ 用于验证 URI。
• license-expression: https://pypi.ac.cn/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 月期间进行了重大重构。