Biblioteca Python para analisar, validar e criar documentos SPDX

Status de CI (Linux, macOS e Windows):

Mudanças que quebram a compatibilidade v0.7 -> v0.8

Esteja ciente de que o próximo lançamento 0.8 passou por uma refatoração significativa em preparação para o próximo lançamento do SPDX v3.0, levando a mudanças que quebram a compatibilidade na API. Consulte o guia de migração para atualizar seu código existente.

As principais características do v0.8 são:

• validação completa de documentos SPDX em relação às especificações v2.2 e v2.3
• suporte ao formato RDF do SPDX com todos os recursos do v2.3
• suporte experimental para a próxima especificação SPDX v3. Observe, no entanto, que o suporte não é completo nem estável neste momento, pois a especificação ainda está em evolução. O código relacionado ao SPDX3 está contido em um subpacote separado "spdx3" e seu uso é opcional. Não recomendamos usá-lo em código de produção ainda.

Observe que o v0.8 suporta apenas a escrita, não a leitura, de documentos SPDX 3.0. Consulte #760 para obter detalhes.

Informações

Esta biblioteca implementa analisadores, conversores, validadores e manipuladores SPDX em Python.

• Página inicial: https://github.com/spdx/tools-python
• Problemas: https://github.com/spdx/tools-python/issues
• PyPI: https://pypi.python.org/pypi/spdx-tools
• Navegue pela API: https://spdx.github.io/tools-python

Atualizações importantes sobre esta biblioteca são compartilhadas por meio da lista de discussão técnica do SPDX: https://lists.spdx.org/g/Spdx-tech.

Licença

Apache-2.0

Recursos

• API para criar e manipular documentos SPDX v2.2 e v2.3
• Analisar, converter, criar e validar arquivos SPDX
• Formatos suportados: Tag/Value, RDF, JSON, YAML, XML
• Visualize a estrutura de um documento SPDX criando um AGraph. Nota: Este é um recurso opcional e requer instalação adicional de dependências opcionais

Suporte experimental ao SPDX 3.0

• Criar elementos e payloads v3.0
• Converter documentos v2.2/v2.3 para v3.0
• Serializar para JSON-LD

Consulte Início rápido para SPDX 3.0 abaixo. A implementação é baseada nos arquivos Markdown descritivos do repositório https://github.com/spdx/spdx-3-model (commit: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). O modelo mais recente do SPDX 3.0 está disponível em https://spdx.github.io/spdx-spec/v3.0/serializations/.

Instalação

Como sempre, você deve trabalhar em um virtualenv (venv). Você pode instalar um clone local deste repositório com yourenv/bin/pip install . ou instalá-lo a partir do PyPI (verifique a versão mais recente e instale-o como yourenv/bin/pip install spdx-tools==0.8.3). Observe que no Windows seria Scripts em vez de bin.

Como usar

Uso pela linha de comando

1. ANÁLISE/VALIDAÇÃO (para analisar qualquer formato):

   • Use pyspdxtools -i <filename> em que <filename> é o local do arquivo. O formato de entrada é inferido automaticamente a partir da extensão do arquivo.

   • Se você estiver usando uma distribuição de código-fonte, tente executar: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. CONVERSÃO (para converter um formato em outro):

   • Use pyspdxtools -i <input_file> -o <output_file> em que <input_file> é o local do arquivo a ser convertido e <output_file> é o local do arquivo de saída. Os formatos de entrada e saída são inferidos automaticamente a partir das extensões dos arquivos.

   • Se você estiver usando uma distribuição de código-fonte, tente executar: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • Se quiser pular o processo de validação, forneça a flag --novalidation, da seguinte forma: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (use com cautela: observe que documentos inválidos não detectados podem levar a um comportamento inesperado da ferramenta)

Uso da biblioteca

1. MODELO DE DADOS

   • O pacote spdx_tools.spdx.model constitui o modelo de dados interno do SPDX v2.3 (o v2.2 é simplesmente um subconjunto deste). Todas as classes relevantes para a criação de documentos SPDX estão expostas no __init__.py encontrado aqui.
   • Os objetos SPDX são implementados por meio de @dataclass_with_properties, uma extensão personalizada de @dataclass.
   • Cada classe começa com uma lista de suas propriedades e seus possíveis tipos. Quando nenhum valor padrão é fornecido, a propriedade é obrigatória e deve ser definida durante a inicialização.
   • Usando as dicas de tipo, a verificação de tipos é aplicada ao inicializar uma nova instância ou ao definir/obter uma propriedade em uma instância (tipos incorretos gerarão ConstructorTypeError ou TypeError, respectivamente). Isso torna fácil detectar propriedades inválidas precocemente e construir apenas documentos válidos.
   • Nota: manipulações in-place, como list.append(item), contornam a verificação de tipos (um TypeError ainda será gerado ao ler list novamente). Recomendamos usar em vez disso.

Exemplo

Aqui estão alguns exemplos de casos de uso possíveis para você começar rapidamente com o spdx-tools. Se você quiser mais exemplos, como criar um documento SPDX do zero, dê uma olhada na pasta de exemplos.

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)

Início rápido para SPDX 3.0

Em contraste com o SPDX v2, todos os elementos agora são subclasses da classe central Element. Isso inclui pacotes, arquivos, trechos (snippets), relacionamentos, anotações, mas também SBOMs, SpdxDocuments e mais. Para fins de serialização, todos os Elementos que devem ser serializados no mesmo arquivo são coletados em um Payload. Isso é apenas um dicionário que mapeia o SpdxId de cada Elemento para si mesmo. Use as funções write_payload() para serializar um payload. Atualmente, existem duas opções:

• O módulo spdx_tools.spdx3.writer.json_ld.json_ld_writer gera um arquivo JSON-LD do payload.
• O módulo spdx_tools.spdx3.writer.console.payload_writer imprime uma saída de depuração no console. Observe que isso não é uma parte oficial da especificação SPDX e provavelmente será descartado assim que um padrão melhor surgir.

Você pode converter um documento SPDX v2 para v3 por meio do módulo spdx_tools.spdx3.bump_from_spdx2.spdx_document. A função bump_spdx_document() retornará um payload contendo um Elemento SpdxDocument e um Elemento para cada pacote, arquivo, trecho, relacionamento ou anotação contido no documento v2.

Dependências

• PyYAML: https://pypi.org/project/PyYAML/ para lidar com YAML.
• xmltodict: https://pypi.org/project/xmltodict/ para lidar com XML.
• rdflib: https://pypi.python.org/pypi/rdflib/ para lidar com RDF.
• ply: https://pypi.org/project/ply/ para lidar com tag-value.
• click: https://pypi.org/project/click/ para criar a interface CLI.
• beartype: https://pypi.org/project/beartype/ para verificação de tipos.
• uritools: https://pypi.org/project/uritools/ para validação de URIs.
• license-expression: https://pypi.org/project/license-expression/ para lidar com expressões de licença SPDX.

Suporte

• Envie problemas, perguntas ou feedback em https://github.com/spdx/tools-python/issues
• Junte-se ao chat em https://gitter.im/spdx-org/Lobby
• Junte-se à discussão em https://lists.spdx.org/g/spdx-tech e https://spdx.dev/participate/tech/

Contribuindo

Contribuições são muito bem-vindas! Consulte CONTRIBUTING.md para obter instruções sobre como contribuir com a base de código.

Histórico

Este é o resultado de uma contribuição inicial do GSoC por @ah450 (ou https://github.com/a-h-i) e é mantido por uma comunidade de adotantes e entusiastas do SPDX. Para se preparar para o lançamento do SPDX v3.0, o repositório passou por uma grande refatoração durante o período de 11/2022 a 07/2023.