Libreria Python per analizzare, validare e creare documenti SPDX

Stato CI (Linux, macOS e Windows):

Modifiche di rottura v0.7 -> v0.8

Tieni presente che la prossima versione 0.8 ha subito un'importante refactoring in preparazione della prossima release SPDX v3.0, che comporta modifiche di rottura nell'API. Fai riferimento alla guida alla migrazione per aggiornare il tuo codice esistente.

Le principali funzionalità della v0.8 sono:

• validazione completa dei documenti SPDX rispetto alle specifiche v2.2 e v2.3
• supporto per il formato RDF di SPDX con tutte le funzionalità della v2.3
• supporto sperimentale per l'imminente specifica SPDX v3. Nota, tuttavia, che il supporto non è né completo né stabile al momento, poiché la specifica è ancora in evoluzione. Il codice relativo a SPDX3 è contenuto in un sottopacchetto separato "spdx3" e il suo utilizzo è facoltativo. Non consigliamo ancora di usarlo in codice di produzione.

Nota che la v0.8 supporta solo la scrittura, non la lettura, di documenti SPDX 3.0. Vedi #760 per i dettagli.

Informazioni

Questa libreria implementa parser, convertitori, validatori e gestori SPDX 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
• Sfoglia l'API: https://spdx.github.io/tools-python

Gli aggiornamenti importanti riguardanti questa libreria vengono condivisi tramite la mailing list tecnica SPDX: https://lists.spdx.org/g/Spdx-tech.

Licenza

Apache-2.0

Funzionalità

• API per creare e manipolare documenti SPDX v2.2 e v2.3
• Analizzare, convertire, creare e validare file SPDX
• Formati supportati: Tag/Value, RDF, JSON, YAML, XML
• Visualizzare la struttura di un documento SPDX creando un AGraph. Nota: questa è una funzionalità opzionale e richiede l'installazione aggiuntiva di dipendenze opzionali

Supporto sperimentale per SPDX 3.0

• Creare elementi e payload v3.0
• Convertire documenti v2.2/v2.3 in v3.0
• Serializzare in JSON-LD

Vedi Quickstart to SPDX 3.0 qui sotto. L'implementazione è basata sui file Markdown descrittivi nel repository https://github.com/spdx/spdx-3-model (commit: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). L'ultimo modello SPDX 3.0 è disponibile su https://spdx.github.io/spdx-spec/v3.0/serializations/.

Installazione

Come sempre, dovresti lavorare in un virtualenv (venv). Puoi installare un clone locale di questo repository con yourenv/bin/pip install . oppure installarlo da PyPI (controlla la versione più recente e installala, ad esempio, con yourenv/bin/pip install spdx-tools==0.8.3). Nota che su Windows sarebbe Scripts invece di bin.

Come usare

Utilizzo da riga di comando

1. PARSING/VALIDAZIONE (per analizzare qualsiasi formato):

   • Usa pyspdxtools -i <filename> dove <filename> è il percorso del file. Il formato di input viene dedotto automaticamente dall'estensione del file.

   • Se stai utilizzando una distribuzione sorgente, prova a eseguire: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. CONVERSIONE (per convertire un formato in un altro):

   • Usa pyspdxtools -i <input_file> -o <output_file> dove <input_file> è il percorso del file da convertire e <output_file> è il percorso del file di output. I formati di input e output vengono dedotti automaticamente dalle estensioni dei file.

   • Se stai utilizzando una distribuzione sorgente, prova a eseguire: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • Se vuoi saltare il processo di validazione, fornisci il flag --novalidation, in questo modo: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (usalo con cautela: nota che documenti non validi non rilevati possono portare a comportamenti imprevisti dello strumento)

Utilizzo come libreria

1. MODELLO DEI DATI

   • Il pacchetto spdx_tools.spdx.model costituisce il modello dati interno SPDX v2.3 (la v2.2 è semplicemente un suo sottoinsieme). Tutte le classi rilevanti per la creazione di documenti SPDX sono esposte nel file __init__.py disponibile qui.
   • Gli oggetti SPDX sono implementati tramite @dataclass_with_properties, un'estensione personalizzata di @dataclass.
   • Ogni classe inizia con un elenco delle sue proprietà e dei loro possibili tipi. Quando non viene fornito un valore predefinito, la proprietà è obbligatoria e deve essere impostata durante l'inizializzazione.
   • Utilizzando i type hint, il controllo dei tipi viene applicato quando si inizializza una nuova istanza o si imposta/legge una proprietà su un'istanza (i tipi errati solleveranno rispettivamente ConstructorTypeError o TypeError). Questo rende facile individuare tempestivamente proprietà non valide e costruire solo documenti validi.
   • Nota: le manipolazioni in-place come list.append(item) aggirano il controllo dei tipi (un TypeError verrà comunque sollevato quando si rilegge list). Consigliamo invece di usare .

Esempio

Ecco alcuni esempi di possibili casi d'uso per iniziare rapidamente con spdx-tools. Se vuoi altri esempi, ad esempio su come creare un documento SPDX da zero, dai un'occhiata alla cartella degli esempi.

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)

Quickstart to SPDX 3.0

A differenza di SPDX v2, tutti gli elementi sono ora sottoclassi della classe centrale Element. Questo include pacchetti, file, snippet, relazioni, annotazioni, ma anche SBOM, SpdxDocument e altro. Ai fini della serializzazione, tutti gli Element che devono essere serializzati nello stesso file vengono raccolti in un Payload. Si tratta semplicemente di un dizionario che mappa ogni SpdxId dell'Element sull'elemento stesso. Usa le funzioni write_payload() per serializzare un payload. Attualmente ci sono due opzioni:

• Il modulo spdx_tools.spdx3.writer.json_ld.json_ld_writer genera un file JSON-LD del payload.
• Il modulo spdx_tools.spdx3.writer.console.payload_writer stampa un output di debug sulla console. Nota che questa non è una parte ufficiale della specifica SPDX e probabilmente verrà eliminata appena emergerà uno standard migliore.

Puoi convertire un documento SPDX v2 in v3 tramite il modulo spdx_tools.spdx3.bump_from_spdx2.spdx_document. La funzione bump_spdx_document() restituirà un payload contenente un Element SpdxDocument e un Element per ogni pacchetto, file, snippet, relazione o annotazione presente nel documento v2.

Dipendenze

• PyYAML: https://pypi.org/project/PyYAML/ per la gestione di YAML.
• xmltodict: https://pypi.org/project/xmltodict/ per la gestione di XML.
• rdflib: https://pypi.python.org/pypi/rdflib/ per la gestione di RDF.
• ply: https://pypi.org/project/ply/ per la gestione di tag-value.
• click: https://pypi.org/project/click/ per creare l'interfaccia CLI.
• beartype: https://pypi.org/project/beartype/ per il controllo dei tipi.
• uritools: https://pypi.org/project/uritools/ per la validazione degli URI.
• license-expression: https://pypi.org/project/license-expression/ per la gestione delle espressioni di licenza SPDX.

Supporto

• Invia problemi, domande o feedback su https://github.com/spdx/tools-python/issues
• Partecipa alla chat su https://gitter.im/spdx-org/Lobby
• Partecipa alla discussione su https://lists.spdx.org/g/spdx-tech e https://spdx.dev/participate/tech/

Contribuire

I contributi sono molto graditi! Vedi CONTRIBUTING.md per le istruzioni su come contribuire al codebase.

Storia

Questo è il risultato di un contributo iniziale GSoC di @ah450 (o https://github.com/a-h-i) ed è mantenuto da una comunità di adottanti e appassionati di SPDX. Per preparare il rilascio di SPDX v3.0, il repository ha subito un'importante refactoring nel periodo da 11/2022 a 07/2023.