Python-Bibliothek zum Parsen, Validieren und Erstellen von SPDX-Dokumenten

CI-Status (Linux, macOS und Windows):

Breaking changes v0.7 -> v0.8

Bitte beachten Sie, dass die kommende Version 0.8 einem umfassenden Refactoring unterzogen wurde, um die bevorstehende SPDX-v3.0-Veröffentlichung vorzubereiten, was zu Breaking Changes an der API führt. Bitte lesen Sie die Migrationsanleitung, um Ihren vorhandenen Code anzupassen.

Die Hauptfunktionen von v0.8 sind:

• vollständige Validierung von SPDX-Dokumenten gegen die v2.2- und v2.3-Spezifikation
• Unterstützung für das RDF-Format von SPDX mit allen v2.3-Funktionen
• experimentelle Unterstützung für die kommende SPDX-v3-Spezifikation. Beachten Sie jedoch, dass die Unterstützung derzeit weder vollständig noch stabil ist, da sich die Spezifikation noch in der Entwicklung befindet. SPDX3-bezogener Code ist in einem separaten Unterpaket „spdx3“ enthalten und seine Verwendung ist optional. Wir empfehlen, ihn noch nicht in Produktionscode einzusetzen.

Beachten Sie, dass v0.8 nur das Schreiben, nicht das Lesen von SPDX-3.0-Dokumenten unterstützt. Einzelheiten finden Sie unter #760.

Informationen

Diese Bibliothek implementiert SPDX-Parser, Konverter, Validatoren und Handler in Python.

• Home: https://github.com/spdx/tools-python
• Issues: https://github.com/spdx/tools-python/issues
• PyPI: https://pypi.python.org/pypi/spdx-tools
• API durchsuchen: https://spdx.github.io/tools-python

Wichtige Aktualisierungen zu dieser Bibliothek werden über die SPDX-Tech-Mailingliste bekannt gegeben: https://lists.spdx.org/g/Spdx-tech.

Lizenz

Apache-2.0

Funktionen

• API zum Erstellen und Bearbeiten von SPDX-v2.2- und v2.3-Dokumenten
• SPDX-Dateien parsen, konvertieren, erstellen und validieren
• Unterstützte Formate: Tag/Value, RDF, JSON, YAML, XML
• Visualisieren Sie die Struktur eines SPDX-Dokuments durch Erstellen eines AGraph. Hinweis: Dies ist eine optionale Funktion und erfordert die zusätzliche Installation optionaler Abhängigkeiten

Experimentelle Unterstützung für SPDX 3.0

• v3.0-Elemente und -Payloads erstellen
• v2.2/v2.3-Dokumente in v3.0 konvertieren
• Als JSON-LD serialisieren

Siehe Schnellstart zu SPDX 3.0 weiter unten. Die Implementierung basiert auf den beschreibenden Markdown-Dateien im Repository https://github.com/spdx/spdx-3-model (commit: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). Das neueste SPDX-3.0-Modell ist verfügbar unter https://spdx.github.io/spdx-spec/v3.0/serializations/.

Installation

Wie immer sollten Sie in einer virtuellen Umgebung (venv) arbeiten. Sie können einen lokalen Klon dieses Repos mit yourenv/bin/pip install . installieren oder es von PyPI installieren (prüfen Sie die neueste Version und installieren Sie sie z. B. mit yourenv/bin/pip install spdx-tools==0.8.3). Beachten Sie, dass es unter Windows Scripts statt bin wäre.

Verwendung

Befehlszeilenverwendung

1. PARSEN/VALIDIEREN (zum Parsen jedes Formats):

   • Verwenden Sie pyspdxtools -i <filename>, wobei <filename> der Speicherort der Datei ist. Das Eingabeformat wird automatisch anhand der Dateiendung erkannt.

   • Wenn Sie eine Source-Distribution verwenden, versuchen Sie Folgendes auszuführen: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. KONVERTIEREN (zum Konvertieren von einem Format in ein anderes):

   • Verwenden Sie pyspdxtools -i <input_file> -o <output_file>, wobei <input_file> der Speicherort der zu konvertierenden Datei und <output_file> der Speicherort der Ausgabedatei ist. Die Eingabe- und Ausgabeformate werden automatisch anhand der Dateiendungen erkannt.

   • Wenn Sie eine Source-Distribution verwenden, versuchen Sie Folgendes auszuführen: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • Wenn Sie den Validierungsprozess überspringen möchten, geben Sie das Flag --novalidation an, wie folgt: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (Verwenden Sie dies mit Vorsicht: Beachten Sie, dass unerkannte ungültige Dokumente zu unerwartetem Verhalten des Tools führen können)

Verwendung der Bibliothek

1. DATENMODELL

   • Das Paket spdx_tools.spdx.model bildet das interne SPDX-v2.3-Datenmodell (v2.2 ist lediglich eine Teilmenge davon). Alle relevanten Klassen für die Erstellung von SPDX-Dokumenten werden in der __init__.py bereitgestellt, die Sie hier finden.
   • SPDX-Objekte werden über @dataclass_with_properties implementiert, eine benutzerdefinierte Erweiterung von @dataclass.
   • Jede Klasse beginnt mit einer Liste ihrer Eigenschaften und deren möglichen Typen. Wenn kein Standardwert angegeben ist, ist die Eigenschaft obligatorisch und muss während der Initialisierung gesetzt werden.
   • Mithilfe der Typannotationen wird die Typprüfung beim Initialisieren einer neuen Instanz oder beim Setzen/Abrufen einer Eigenschaft einer Instanz erzwungen (falsche Typen lösen entsprechend ConstructorTypeError bzw. TypeError aus). Dadurch lassen sich ungültige Eigenschaften frühzeitig erkennen und es werden nur gültige Dokumente erstellt.
   • Hinweis: In-Place-Manipulationen wie list.append(item) umgehen die Typprüfung (ein TypeError wird dennoch ausgelöst, wenn list erneut gelesen wird). Wir empfehlen, stattdessen zu verwenden.

Beispiel

Hier sind einige Beispiele für mögliche Anwendungsfälle, mit denen Sie schnell mit den spdx-tools loslegen können. Wenn Sie weitere Beispiele wünschen, z. B. wie Sie ein SPDX-Dokument von Grund auf erstellen, werfen Sie einen Blick in den Beispiele-Ordner.

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)

Schnellstart zu SPDX 3.0

Im Gegensatz zu SPDX v2 sind jetzt alle Elemente Unterklassen der zentralen Klasse Element. Dies umfasst Pakete, Dateien, Snippets, Beziehungen, Annotationen, aber auch SBOMs, SpdxDocuments und mehr. Für Serialisierungszwecke werden alle Elemente, die in dieselbe Datei serialisiert werden sollen, in einem Payload gesammelt. Dies ist lediglich ein Wörterbuch, das die SpdxId jedes Elements auf sich selbst abbildet. Verwenden Sie die Funktionen write_payload(), um einen Payload zu serialisieren. Es gibt derzeit zwei Optionen:

• Das Modul spdx_tools.spdx3.writer.json_ld.json_ld_writer erzeugt eine JSON-LD-Datei des Payloads.
• Das Modul spdx_tools.spdx3.writer.console.payload_writer gibt eine Debug-Ausgabe auf der Konsole aus. Beachten Sie, dass dies kein offizieller Bestandteil der SPDX-Spezifikation ist und wahrscheinlich entfernt wird, sobald ein besserer Standard entsteht.

Sie können ein SPDX-v2-Dokument über das Modul spdx_tools.spdx3.bump_from_spdx2.spdx_document in v3 konvertieren. Die Funktion bump_spdx_document() gibt einen Payload zurück, der ein SpdxDocument-Element und ein Element für jedes Paket, jede Datei, jedes Snippet, jede Beziehung oder Annotation enthält, die im v2-Dokument enthalten sind.

Abhängigkeiten

• PyYAML: https://pypi.org/project/PyYAML/ zur Verarbeitung von YAML.
• xmltodict: https://pypi.org/project/xmltodict/ zur Verarbeitung von XML.
• rdflib: https://pypi.python.org/pypi/rdflib/ zur Verarbeitung von RDF.
• ply: https://pypi.org/project/ply/ zur Verarbeitung von tag-value.
• click: https://pypi.org/project/click/ zum Erstellen der CLI-Schnittstelle.
• beartype: https://pypi.org/project/beartype/ für die Typprüfung.
• uritools: https://pypi.org/project/uritools/ zur Validierung von URIs.
• license-expression: https://pypi.org/project/license-expression/ zur Verarbeitung von SPDX-Lizenzausdrücken.

Unterstützung

• Reichen Sie Probleme, Fragen oder Feedback unter https://github.com/spdx/tools-python/issues ein
• Treten Sie dem Chat unter https://gitter.im/spdx-org/Lobby bei
• Beteiligen Sie sich an der Diskussion auf https://lists.spdx.org/g/spdx-tech und https://spdx.dev/participate/tech/

Mitwirken

Beiträge sind sehr willkommen! Anweisungen, wie Sie zum Codebase beitragen können, finden Sie in CONTRIBUTING.md.

Historie

Dies ist das Ergebnis eines ursprünglichen GSoC-Beitrags von @ah450 (oder https://github.com/a-h-i) und wird von einer Gemeinschaft aus SPDX-Anwendern und -Enthusiasten gepflegt. Zur Vorbereitung auf die Veröffentlichung von SPDX v3.0 wurde das Repository im Zeitraum von 11/2022 bis 07/2023 einem umfassenden Refactoring unterzogen.