Bibliothèque Python pour analyser, valider et créer des documents SPDX

Statut CI (Linux, macOS et Windows) :

Changements majeurs v0.7 -> v0.8

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 :

• validation complète des documents SPDX par rapport aux spécifications v2.2 et v2.3
• prise en charge du format RDF de SPDX avec toutes les fonctionnalités v2.3
• prise en charge expérimentale de la prochaine spécification SPDX v3. Notez toutefois que cette prise en charge n'est ni complète ni stable à ce stade, car la spécification est encore en évolution. Le code lié à SPDX3 est contenu dans un sous-package séparé « spdx3 » et son utilisation est facultative. Nous déconseillons de l'utiliser dans du code de production pour le moment.

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.

Informations

Cette bibliothèque implémente des analyseurs, convertisseurs, validateurs et gestionnaires SPDX en Python.

• Accueil : https://github.com/spdx/tools-python
• Problèmes : https://github.com/spdx/tools-python/issues
• PyPI : https://pypi.python.org/pypi/spdx-tools
• Parcourir l'API : https://spdx.github.io/tools-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.

Licence

Apache-2.0

Fonctionnalités

• API pour créer et manipuler des documents SPDX v2.2 et v2.3
• Analyser, convertir, créer et valider des fichiers SPDX
• Formats pris en charge : Tag/Value, RDF, JSON, YAML, XML
• Visualiser la structure d'un document SPDX en créant un AGraph. Remarque : il s'agit d'une fonctionnalité facultative qui nécessite l'installation de dépendances facultatives supplémentaires

Prise en charge expérimentale de SPDX 3.0

• Créer des éléments et des payloads v3.0
• Convertir des documents v2.2/v2.3 en v3.0
• Sérialiser en JSON-LD

Voir 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/.

Installation

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.

Comment l'utiliser

Utilisation en ligne de commande

1. 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

2. 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)

   • Pour obtenir de l'aide, utilisez pyspdxtools --help

3. 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.

Utilisation de la bibliothèque

1. MODÈLE DE DONNÉES

   • Le package 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.
   • Les objets SPDX sont implémentés via @dataclass_with_properties, une extension personnalisée de @dataclass.
   • Chaque classe commence par une liste de ses propriétés et de leurs types possibles. Lorsqu'aucune valeur par défaut n'est fournie, la propriété est obligatoire et doit être définie lors de l'initialisation.
   • Grâce aux indications de type, la vérification des types est appliquée lors de l'initialisation d'une nouvelle instance ou lors de la définition/lecture d'une propriété sur une instance (des types incorrects lèveront respectivement 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.
   • Remarque : les manipulations en place comme 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 list = list + [item] à la place.
   • Le point d'entrée principal d'un document SPDX est la classe Document du module document.py, qui renvoie à toutes les autres classes.
   • Pour la gestion des licences, la bibliothèque license_expression est utilisée.
   • Remarque sur 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.

2. ANALYSE