Biblioteca Python para analizar, validar y crear documentos SPDX

Estado de CI (Linux, macOS y Windows):

Cambios importantes v0.7 -> v0.8

Tenga en cuenta que la próxima versión 0.8 ha experimentado una refactorización significativa en preparación para el lanzamiento de SPDX v3.0, lo que conlleva cambios incompatibles en la API. Consulte la guía de migración para actualizar su código existente.

Las principales características de v0.8 son:

• validación completa de documentos SPDX conforme a las especificaciones v2.2 y v2.3
• soporte para el formato RDF de SPDX con todas las funciones de v2.3
• soporte experimental para la próxima especificación SPDX v3. Tenga en cuenta, sin embargo, que el soporte no es completo ni estable en este punto, ya que la especificación aún está evolucionando. El código relacionado con SPDX3 se encuentra en un subpaquete separado "spdx3" y su uso es opcional. No recomendamos usarlo en código de producción todavía.

Tenga en cuenta que v0.8 solo admite escribir, no leer, documentos SPDX 3.0. Vea #760 para más detalles.

Información

Esta biblioteca implementa analizadores (parsers), conversores, validadores y manejadores de SPDX en Python.

• Página principal: https://github.com/spdx/tools-python
• Problemas: https://github.com/spdx/tools-python/issues
• PyPI: https://pypi.python.org/pypi/spdx-tools
• Explorar la API: https://spdx.github.io/tools-python

Las actualizaciones importantes sobre esta biblioteca se comparten a través de la lista de correo de tecnología SPDX: https://lists.spdx.org/g/Spdx-tech.

Licencia

Apache-2.0

Características

• API para crear y manipular documentos SPDX v2.2 y v2.3
• Analizar, convertir, crear y validar archivos SPDX
• Formatos admitidos: Tag/Value, RDF, JSON, YAML, XML
• Visualice la estructura de un documento SPDX creando un AGraph. Nota: Esta es una función opcional y requiere instalación adicional de dependencias opcionales

Soporte experimental para SPDX 3.0

• Crear elementos y payloads v3.0
• Convertir documentos v2.2/v2.3 a v3.0
• Serializar a JSON-LD

Vea Inicio rápido para SPDX 3.0 a continuación. La implementación se basa en los archivos Markdown descriptivos del repositorio https://github.com/spdx/spdx-3-model (commit: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). El modelo más reciente de SPDX 3.0 está disponible en https://spdx.github.io/spdx-spec/v3.0/serializations/.

Instalación

Como siempre, debe trabajar en un virtualenv (venv). Puede instalar un clon local de este repositorio con yourenv/bin/pip install . o instalarlo desde PyPI (consulte la versión más reciente e instálela como yourenv/bin/pip install spdx-tools==0.8.3). Tenga en cuenta que en Windows sería Scripts en lugar de bin.

Cómo usar

Uso de la línea de comandos

1. ANALIZAR/VALIDAR (para analizar cualquier formato):

   • Use pyspdxtools -i <filename> donde <filename> es la ubicación del archivo. El formato de entrada se infiere automáticamente a partir de la extensión del archivo.

   • Si está usando una distribución de código fuente, intente ejecutar: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. CONVERTIR (para convertir un formato a otro):

   • Use pyspdxtools -i <input_file> -o <output_file> donde <input_file> es la ubicación del archivo a convertir y <output_file> es la ubicación del archivo de salida. Los formatos de entrada y salida se infieren automáticamente a partir de las extensiones de los archivos.

   • Si está usando una distribución de código fuente, intente ejecutar: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • Si desea omitir el proceso de validación, proporcione el indicador --novalidation, así: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (úselo con precaución: tenga en cuenta que los documentos no válidos no detectados pueden provocar un comportamiento inesperado de la herramienta)

   • Para obtener ayuda, use pyspdxtools --help

3. GENERACIÓN DE GRÁFICOS (función opcional)

   • Esta función genera un gráfico que representa todos los elementos del documento SPDX y sus conexiones en función de las relaciones proporcionadas. El gráfico se puede renderizar como una imagen. A continuación se muestra un ejemplo para el archivo tests/spdx/data/SPDXJSONExample-v2.3.spdx.json:

   • Asegúrese de instalar las dependencias opcionales networkx y pygraphviz. Para hacerlo, ejecute pip install ".[graph_generation]".

   • Use pyspdxtools -i <input_file> --graph -o <output_file> donde <output_file> es un nombre de archivo de salida con formato válido para pygraphviz (consulte la documentación aquí).

   • Si está usando una distribución de código fuente, intente ejecutar pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png para generar un PNG con una vista general de la estructura del archivo de ejemplo.

Uso de la biblioteca

1. MODELO DE DATOS

   • El paquete spdx_tools.spdx.model constituye el modelo de datos interno de SPDX v2.3 (v2.2 es simplemente un subconjunto de este). Todas las clases relevantes para la creación de documentos SPDX están expuestas en el archivo __init__.py que se encuentra aquí.
   • Los objetos SPDX se implementan mediante @dataclass_with_properties, una extensión personalizada de @dataclass.
   • Cada clase comienza con una lista de sus propiedades y sus posibles tipos. Cuando no se proporciona un valor predeterminado, la propiedad es obligatoria y debe establecerse durante la inicialización.
   • Con las sugerencias de tipo (type hints), se aplica la verificación de tipos al inicializar una nueva instancia o al establecer/obtener una propiedad en una instancia (los tipos incorrectos generarán ConstructorTypeError o TypeError, respectivamente). Esto facilita la detección temprana de propiedades no válidas y la construcción de documentos válidos.
   • Nota: las manipulaciones in-place como list.append(item) eluden la verificación de tipos (se seguirá generando un TypeError al volver a leer list). Recomendamos usar list = list + [item] en su lugar.
   • El punto de entrada principal de un documento SPDX es la clase Document del módulo document.py, que enlaza con todas las demás clases.
   • Para el manejo de licencias, se utiliza la biblioteca license_expression.
   • Nota sobre documentDescribes y hasFiles: Estos campos se convertirán en relaciones en el modelo de datos interno. Al estar obsoletos, estos campos no se escribirán en la salida.

2. ANÁLISIS