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)

   • Für Hilfe verwenden Sie pyspdxtools --help

3. GRAPHERZEUGUNG (optionale Funktion)

   • Diese Funktion erzeugt einen Graphen, der alle Elemente im SPDX-Dokument und ihre Verbindungen basierend auf den angegebenen Beziehungen darstellt. Der Graph kann als Bild gerendert werden. Nachfolgend finden Sie ein Beispiel für die Datei tests/spdx/data/SPDXJSONExample-v2.3.spdx.json:

   • Stellen Sie sicher, dass Sie die optionalen Abhängigkeiten networkx und pygraphviz installieren. Führen Sie dazu pip install ".[graph_generation]" aus.

   • Verwenden Sie pyspdxtools -i <input_file> --graph -o <output_file>, wobei <output_file> ein Ausgabedateiname mit gültigem Format für pygraphviz ist (sehen Sie sich die Dokumentation hier an).

   • Wenn Sie eine Source-Distribution verwenden, versuchen Sie Folgendes auszuführen: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png, um ein PNG mit einer Übersicht über die Struktur der Beispieldatei zu erzeugen.

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 list = list + [item] zu verwenden.
   • Der Haupteinstiegspunkt eines SPDX-Dokuments ist die Klasse Document aus dem Modul document.py, die mit allen anderen Klassen verknüpft ist.
   • Für die Lizenzbehandlung wird die Bibliothek license_expression verwendet.
   • Hinweis zu documentDescribes und hasFiles: Diese Felder werden im internen Datenmodell in Beziehungen umgewandelt. Da sie veraltet sind, werden diese Felder nicht in die Ausgabe geschrieben.

2. PARSEN