SPDXドキュメントを解析・検証・作成するためのPythonライブラリ

CIステータス（Linux、macOS、Windows）:

v0.7 -> v0.8 における破壊的変更

まもなくリリースされる0.8では、今後のSPDX v3.0リリースに備えて大幅なリファクタリングが行われており、APIに破壊的変更が生じています。 既存のコードを更新する際は、移行ガイド を参照してください。

v0.8の主な機能は次のとおりです:

• v2.2およびv2.3仕様に対するSPDXドキュメントの完全な検証
• v2.3の全機能を備えたSPDX RDF形式のサポート
• 今後のSPDX v3仕様への実験的サポート。ただし、現時点ではサポートは完全でも安定でもありません。仕様はまだ進化中です。SPDX3関連のコードは「spdx3」という別のサブパッケージに含まれており、その使用は任意です。本番コードでの使用はまだお勧めしません。

v0.8はSPDX 3.0ドキュメントの読み取りではなく書き込みのみをサポートしていることに注意してください。 詳細は#760を参照してください。

情報

このライブラリは、SPDXパーサー、コンバーター、バリデーター、ハンドラーをPythonで実装しています。

• ホーム: 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エレメントとペイロードの作成
• 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/で入手できます。

インストール

いつものように、virtualenv（venv）内で作業する必要があります。このリポジトリのローカルクローンはyourenv/bin/pip install .でインストールするか、PyPIからインストールできます （最新リリースを確認し、 yourenv/bin/pip install spdx-tools==0.8.3のようにインストールしてください）。WindowsではbinではなくScriptsになることに注意してください。

使用方法

コマンドラインでの使用

1. 解析/検証（任意の形式の解析用）:

   • <filename>をファイルの場所として、pyspdxtools -i <filename>を使用します。入力形式はファイルの拡張子から自動的に推測されます。

   • ソース配布版を使用している場合は、次のコマンドを実行してみてください: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. 変換（ある形式から別の形式への変換用）:

   • <input_file>を変換するファイルの場所、<output_file>を出力ファイルの場所として、pyspdxtools -i <input_file> -o <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を使用します

ライブラリでの使用

1. データモデル

   • spdx_tools.spdx.modelパッケージは、内部のSPDX v2.3データモデルを構成します（v2.2は単にそのサブセットです）。SPDXドキュメント作成に関連するすべてのクラスは、ここにある__init__.pyで公開されています。
   • SPDXオブジェクトは、@dataclassのカスタム拡張である@dataclass_with_propertiesを介して実装されています。
   • 各クラスは、そのプロパティと可能な型のリストから始まります。デフォルト値が提供されていない場合、そのプロパティは必須であり、初期化中に設定する必要があります。
   • 型ヒントを使用することで、新しいインスタンスの初期化時やインスタンスのプロパティの設定/取得時に型チェックが強制されます（誤った型はそれぞれConstructorTypeErrorまたはTypeErrorを発生させます）。これにより、無効なプロパティを早期に検出し、有効なドキュメントのみを構築することが容易になります。
   • 注: list.append(item)のようなインプレース操作は型チェックを回避します（listを再度読み取るとTypeErrorが依然として発生します）。代わりにlist = list + [item]を使用することをお勧めします。
   • SPDXドキュメントの主要なエントリポイントは、document.pyモジュールのDocumentクラスであり、他のすべてのクラスにリンクしています。

例

ここでは、spdx-toolsをすぐに使い始めるためのユースケースの例をいくつか示します。 SPDXドキュメントをゼロから作成する方法など、さらに多くの例が必要な場合は、examplesフォルダをご覧ください。

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()関数を使用してペイロードをシリアライズします。現在、次の2つのオプションがあります:

• 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ドキュメントに含まれる各パッケージ、ファイル、スニペット、リレーションシップ、またはアノテーションごとに1つのエレメントを含むペイロードを返します。

依存関係

• 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月にかけて大規模なリファクタリングが行われました。