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)

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 en su lugar.

Ejemplo

Aquí hay algunos ejemplos de casos de uso posibles para comenzar rápidamente con spdx-tools. Si desea más ejemplos, como crear un documento SPDX desde cero, eche un vistazo a la carpeta de ejemplos.

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)

Inicio rápido para SPDX 3.0

En contraste con SPDX v2, todos los elementos son ahora subclases de la clase central Element. Esto incluye paquetes, archivos, fragmentos (snippets), relaciones, anotaciones, pero también SBOMs, SpdxDocuments y más. Con fines de serialización, todos los elementos que se van a serializar en el mismo archivo se recogen en un Payload. Esto es solo un diccionario que asigna el SpdxId de cada elemento a sí mismo. Use las funciones write_payload() para serializar un payload. Actualmente hay dos opciones:

• El módulo spdx_tools.spdx3.writer.json_ld.json_ld_writer genera un archivo JSON-LD del payload.
• El módulo spdx_tools.spdx3.writer.console.payload_writer imprime una salida de depuración en la consola. Tenga en cuenta que esto no es una parte oficial de la especificación SPDX y probablemente se eliminará en cuanto surja un estándar mejor.

Puede convertir un documento SPDX v2 a v3 mediante el módulo spdx_tools.spdx3.bump_from_spdx2.spdx_document. La función bump_spdx_document() devolverá un payload que contiene un elemento SpdxDocument y un elemento por cada paquete, archivo, fragmento, relación o anotación contenido en el documento v2.

Dependencias

• PyYAML: https://pypi.org/project/PyYAML/ para manejar YAML.
• xmltodict: https://pypi.org/project/xmltodict/ para manejar XML.
• rdflib: https://pypi.python.org/pypi/rdflib/ para manejar RDF.
• ply: https://pypi.org/project/ply/ para manejar tag-value.
• click: https://pypi.org/project/click/ para crear la interfaz CLI.
• beartype: https://pypi.org/project/beartype/ para la verificación de tipos.
• uritools: https://pypi.org/project/uritools/ para la validación de URIs.
• license-expression: https://pypi.org/project/license-expression/ para manejar expresiones de licencia SPDX.

Soporte

• Envíe problemas, preguntas o comentarios en https://github.com/spdx/tools-python/issues
• Únase al chat en https://gitter.im/spdx-org/Lobby
• Únase a la discusión en https://lists.spdx.org/g/spdx-tech y https://spdx.dev/participate/tech/

Contribuir

¡Las contribuciones son muy bienvenidas! Consulte CONTRIBUTING.md para obtener instrucciones sobre cómo contribuir al código.

Historia

Este es el resultado de una contribución inicial de GSoC por parte de @ah450 (o https://github.com/a-h-i) y es mantenido por una comunidad de adoptantes y entusiastas de SPDX. Para prepararse para el lanzamiento de SPDX v3.0, el repositorio ha sufrido una refactorización importante durante el período de 11/2022 a 07/2023.