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)

   • Para obter ajuda, use pyspdxtools --help

3. GERAÇÃO DE GRAFOS (recurso opcional)

   • Este recurso gera um grafo representando todos os elementos do documento SPDX e suas conexões com base nos relacionamentos fornecidos. O grafo pode ser renderizado em uma imagem. Abaixo está um exemplo para o arquivo tests/spdx/data/SPDXJSONExample-v2.3.spdx.json:

   • Certifique-se de instalar as dependências opcionais networkx e pygraphviz. Para isso, execute pip install ".[graph_generation]".

   • Use pyspdxtools -i <input_file> --graph -o <output_file> em que <output_file> é um nome de arquivo de saída com formato válido para pygraphviz (consulte a documentação aqui).

   • Se você estiver usando uma distribuição de código-fonte, tente executar pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png para gerar um png com uma visão geral da estrutura do arquivo de exemplo.

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 list = list + [item] em vez disso.
   • O principal ponto de entrada de um documento SPDX é a classe Document do módulo document.py, que faz a ligação com todas as outras classes.
   • Para o tratamento de licenças, a biblioteca license_expression é usada.
   • Nota sobre documentDescribes e hasFiles: Esses campos serão convertidos em relacionamentos no modelo de dados interno. Como estão obsoletos, esses campos não serão escritos na saída.

2. ANÁLISE

   • Use parse_file(file_name) do módulo parse_anything.py para analisar um arquivo arbitrário com uma das extensões de arquivo suportadas.
   • Uma análise bem-sucedida retornará uma instância de Document. Uma análise malsucedida levantará SPDXParsingError com uma lista de todos os problemas encontrados.

3. VALIDAÇÃO