spdx/tools-pythonUne bibliothèque Python pour analyser, valider et créer des documents SPDX.
Statut CI (Linux, macOS et Windows) : 
Veuillez noter que la prochaine version 0.8 a subi un refactoring important en préparation de la prochaine version SPDX v3.0, entraînant des changements majeurs dans l'API. Veuillez vous référer au guide de migration pour mettre à jour votre code existant.
Les principales fonctionnalités de v0.8 sont :
Notez que v0.8 ne prend en charge que l'écriture, et non la lecture, des documents SPDX 3.0. Voir #760 pour plus de détails.
Cette bibliothèque implémente des analyseurs, convertisseurs, validateurs et gestionnaires SPDX en Python.
Les mises à jour importantes concernant cette bibliothèque sont partagées via la liste de diffusion SPDX tech : https://lists.spdx.org/g/Spdx-tech.
AGraph.
Remarque : il s'agit d'une fonctionnalité facultative qui nécessite
l'installation de dépendances facultatives supplémentairesVoir Démarrage rapide avec SPDX 3.0 plus bas. L'implémentation est basée sur les fichiers Markdown descriptifs du dépôt https://github.com/spdx/spdx-3-model (commit : a5372a3c145dbdfc1381fc1f791c68889aafc7ff). Le dernier modèle SPDX 3.0 est disponible à l'adresse https://spdx.github.io/spdx-spec/v3.0/serializations/.
Comme toujours, vous devriez travailler dans un virtualenv (venv). Vous pouvez installer un clone local
de ce dépôt avec yourenv/bin/pip install . ou l'installer depuis PyPI
(vérifiez la dernière version et installez-la comme
yourenv/bin/pip install spdx-tools==0.8.3). Notez que sur Windows, ce serait Scripts
au lieu de bin.
ANALYSE/VALIDATION (pour analyser n'importe quel format) :
Utilisez pyspdxtools -i <filename> où <filename> est l'emplacement du fichier. Le format d'entrée est déduit automatiquement de l'extension du fichier.
Si vous utilisez une distribution source, essayez d'exécuter :
pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json
CONVERSION (pour convertir un format vers un autre) :
Utilisez pyspdxtools -i <input_file> -o <output_file> où <input_file> est l'emplacement du fichier à convertir
et <output_file> est l'emplacement du fichier de sortie. Les formats d'entrée et de sortie sont déduits automatiquement des extensions des fichiers.
Si vous utilisez une distribution source, essayez d'exécuter :
pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag
Si vous souhaitez ignorer le processus de validation, fournissez l'option --novalidation, comme ceci :
pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation
(à utiliser avec prudence : notez que des documents invalides non détectés peuvent entraîner un comportement inattendu de l'outil)
MODÈLE DE DONNÉES
spdx_tools.spdx.model constitue le modèle de données interne de SPDX v2.3 (v2.2 en est simplement un sous-ensemble). Toutes les classes pertinentes pour la création de documents SPDX sont exposées dans le __init__.py situé ici.@dataclass_with_properties, une extension personnalisée de @dataclass.ConstructorTypeError ou TypeError). Cela permet de détecter facilement les propriétés invalides dès le début et de ne construire que des documents valides.list.append(item) contournent la vérification des types (un TypeError sera tout de même levé à la lecture de list). Nous recommandons d'utiliser à la place.Voici quelques exemples de cas d'utilisation possibles pour vous aider à démarrer rapidement avec spdx-tools. Si vous voulez plus d'exemples, comme la création d'un document SPDX à partir de zéro, jetez un œil au dossier exemples.
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)
Contrairement à SPDX v2, tous les éléments sont désormais des sous-classes de la classe centrale Element.
Cela inclut les packages, fichiers, snippets, relations, annotations, mais aussi les SBOM, les SpdxDocument, et plus encore.
À des fins de sérialisation, tous les éléments qui doivent être sérialisés dans le même fichier sont regroupés dans un Payload.
Il s'agit simplement d'un dictionnaire qui associe le SpdxId de chaque élément à lui-même.
Utilisez les fonctions write_payload() pour sérialiser un payload.
Il existe actuellement deux options :
spdx_tools.spdx3.writer.json_ld.json_ld_writer génère un fichier JSON-LD du payload.spdx_tools.spdx3.writer.console.payload_writer affiche une sortie de débogage dans la console. Notez qu'il ne s'agit pas d'une partie officielle de la spécification SPDX et que cette fonctionnalité sera probablement abandonnée dès qu'un meilleur standard émergera.Vous pouvez convertir un document SPDX v2 en v3 via le module spdx_tools.spdx3.bump_from_spdx2.spdx_document.
La fonction bump_spdx_document() renverra un payload contenant un élément SpdxDocument et un élément pour chaque package, fichier, snippet, relation ou annotation contenu dans le document v2.
Les contributions sont les bienvenues ! Consultez CONTRIBUTING.md pour les instructions sur la façon de contribuer à la base de code.
Ceci est le résultat d'une contribution initiale GSoC de @ah450 (ou https://github.com/a-h-i) et est maintenu par une communauté d'adoptants et de passionnés de SPDX. Afin de préparer la sortie de SPDX v3.0, le dépôt a subi une refonte majeure entre 11/2022 et 07/2023.
Pour obtenir de l'aide, utilisez pyspdxtools --help
GÉNÉRATION DE GRAPHES (fonctionnalité facultative)
Cette fonctionnalité génère un graphe représentant tous les éléments du document SPDX et leurs connexions en fonction des
relations fournies. Le graphe peut être rendu sous forme d'image. Voici un exemple pour le fichier tests/spdx/data/SPDXJSONExample-v2.3.spdx.json :
Assurez-vous d'installer les dépendances facultatives networkx et pygraphviz. Pour ce faire, exécutez pip install ".[graph_generation]".
Utilisez pyspdxtools -i <input_file> --graph -o <output_file> où <output_file> est un nom de fichier de sortie au format valide pour pygraphviz (consultez
la documentation ici).
Si vous utilisez une distribution source, essayez d'exécuter
pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png pour générer
un png avec un aperçu de la structure du fichier d'exemple.
list = list + [item]Document du module document.py, qui renvoie à toutes les autres classes.documentDescribes et hasFiles : ces champs seront convertis en relations dans le modèle de données interne. Comme ils sont obsolètes, ces champs ne seront pas écrits dans la sortie.ANALYSE
parse_file(file_name) du module parse_anything.py pour analyser un fichier arbitraire avec l'une des extensions de fichier prises en charge.Document. Une analyse infructueuse lèvera SPDXParsingError avec une liste de tous les problèmes rencontrés.VALIDATION
validate_full_spdx_document(document) pour valider une instance de la classe Document.ValidationMessage, chacun composé d'une chaîne décrivant l'invalidité et d'un ValidationContext pour identifier la source de l'erreur de validation.SPDX-2.2 et SPDX-2.3 sont prises en charge par cet outil.ÉCRITURE
write_file(document, file_name) du module write_anything.py pour écrire une instance de Document dans le fichier spécifié.
Le format de sérialisation est déterminé à partir de l'extension du nom de fichier.write_file(document, file_name, validate=False).
Attention : seuls les documents valides peuvent être sérialisés de manière fiable ; la sérialisation de documents invalides n'est pas prise en charge.