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)

   • Per aiuto usa pyspdxtools --help

3. GENERAZIONE DEL GRAFO (funzionalità opzionale)

   • Questa funzionalità genera un grafo che rappresenta tutti gli elementi del documento SPDX e le loro connessioni in base alle relazioni fornite. Il grafo può essere renderizzato come immagine. Di seguito è riportato un esempio per il file tests/spdx/data/SPDXJSONExample-v2.3.spdx.json:

   • Assicurati di installare le dipendenze opzionali networkx e pygraphviz. Per farlo, esegui pip install ".[graph_generation]".

   • Usa pyspdxtools -i <input_file> --graph -o <output_file> dove <output_file> è un nome di file di output con un formato valido per pygraphviz (consulta la documentazione qui).

   • Se stai utilizzando una distribuzione sorgente, prova a eseguire pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png per generare un png con una panoramica della struttura del file di esempio.

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 list = list + [item].
   • Il punto di ingresso principale di un documento SPDX è la classe Document del modulo document.py, che si collega a tutte le altre classi.
   • Per la gestione delle licenze viene utilizzata la libreria license_expression.
   • Nota su documentDescribes e hasFiles: questi campi verranno convertiti in relazioni nel modello dati interno. Poiché sono deprecati, questi campi non verranno scritti nell'output.

2. PARSING

   • Usa parse_file(file_name) del modulo parse_anything.py per analizzare un file arbitrario con una delle estensioni di file supportate.
   • Un'analisi riuscita restituirà un'istanza di Document. Un'analisi non riuscita solleverà SPDXParsingError con un elenco di tutti i problemi incontrati.

3. VALIDAZIONE