SPDX दस्तावेज़ों को पार्स करने, मान्य करने और बनाने के लिए Python लाइब्रेरी

CI स्थिति (Linux, macOS और Windows):

विनाशकारी परिवर्तन v0.7 -> v0.8

कृपया ध्यान दें कि आगामी 0.8 रिलीज़ में आगामी SPDX v3.0 रिलीज़ की तैयारी में एक महत्वपूर्ण रीफैक्टरिंग की गई है, जिससे API में विनाशकारी परिवर्तन हुए हैं। अपने मौजूदा कोड को अपडेट करने के लिए कृपया माइग्रेशन गाइड देखें।

v0.8 की मुख्य विशेषताएँ हैं:

• v2.2 और v2.3 विनिर्देश के अनुसार SPDX दस्तावेज़ों का पूर्ण मान्यकरण
• सभी v2.3 सुविधाओं के साथ SPDX के RDF प्रारूप के लिए समर्थन
• आगामी SPDX v3 विनिर्देश के लिए प्रायोगिक समर्थन। हालाँकि, ध्यान दें कि यह समर्थन इस समय न तो पूर्ण है और न ही स्थिर, क्योंकि विनिर्देश अभी भी विकसित हो रहा है। SPDX3 से संबंधित कोड एक अलग सबपैकेज "spdx3" में समाहित है और इसका उपयोग वैकल्पिक है। हम इसे अभी प्रोडक्शन कोड में उपयोग करने की अनुशंसा नहीं करते हैं।

ध्यान दें कि v0.8 केवल SPDX 3.0 दस्तावेज़ों को लिखने का समर्थन करता है, पढ़ने का नहीं। विवरण के लिए #760 देखें।

जानकारी

यह लाइब्रेरी Python में SPDX पार्सर, कन्वर्टर, वैलिडेटर और हैंडलर लागू करती है।

• होम: https://github.com/spdx/tools-python
• मुद्दे: https://github.com/spdx/tools-python/issues
• PyPI: https://pypi.python.org/pypi/spdx-tools
• API ब्राउज़ करें: https://spdx.github.io/tools-python

इस लाइब्रेरी से संबंधित महत्वपूर्ण अपडेट SPDX तकनीकी मेलिंग सूची के माध्यम से साझा किए जाते हैं: https://lists.spdx.org/g/Spdx-tech।

लाइसेंस

Apache-2.0

विशेषताएँ

• SPDX v2.2 और v2.3 दस्तावेज़ बनाने और हेरफेर करने के लिए API
• SPDX फ़ाइलों को पार्स, कन्वर्ट, निर्मित और मान्य करें
• समर्थित प्रारूप: Tag/Value, RDF, JSON, YAML, XML
• AGraph बनाकर SPDX दस्तावेज़ की संरचना को विज़ुअलाइज़ करें। नोट: यह एक वैकल्पिक सुविधा है और इसके लिए वैकल्पिक निर्भरताओं की अतिरिक्त स्थापना आवश्यक है

SPDX 3.0 के लिए प्रायोगिक समर्थन

• v3.0 तत्व और पेलोड बनाएं
• v2.2/v2.3 दस्तावेज़ों को v3.0 में बदलें
• JSON-LD में क्रमबद्ध करें

नीचे Quickstart to SPDX 3.0 देखें। कार्यान्वयन रिपॉजिटरी में वर्णनात्मक Markdown फ़ाइलों पर आधारित है https://github.com/spdx/spdx-3-model (कमिट: a5372a3c145dbdfc1381fc1f791c68889aafc7ff)। नवीनतम SPDX 3.0 मॉडल यहाँ उपलब्ध है https://spdx.github.io/spdx-spec/v3.0/serializations/।

स्थापना

हमेशा की तरह आपको virtualenv (venv) में काम करना चाहिए। आप इस रिपो की एक स्थानीय क्लोन yourenv/bin/pip install . के साथ स्थापित कर सकते हैं या इसे PyPI से स्थापित कर सकते हैं (नवीनतम रिलीज़ देखें और इसे इस तरह स्थापित करें yourenv/bin/pip install spdx-tools==0.8.3)। ध्यान दें कि Windows पर यह bin के बजाय Scripts होगा।

उपयोग कैसे करें

कमांड-लाइन उपयोग

1. पार्सिंग/मान्यकरण (किसी भी प्रारूप को पार्स करने के लिए):

   • pyspdxtools -i <filename> का उपयोग करें जहाँ <filename> फ़ाइल का स्थान है। इनपुट प्रारूप फ़ाइल के अंत से स्वचालित रूप से अनुमानित किया जाता है।

   • यदि आप सोर्स डिस्ट्रीब्यूशन का उपयोग कर रहे हैं, तो यह चलाकर देखें: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json

2. कन्वर्ट करना (एक प्रारूप से दूसरे प्रारूप में बदलने के लिए):

   • pyspdxtools -i <input_file> -o <output_file> का उपयोग करें जहाँ <input_file> परिवर्तित की जाने वाली फ़ाइल का स्थान है और <output_file> आउटपुट फ़ाइल का स्थान है। इनपुट और आउटपुट प्रारूप फ़ाइल के अंत से स्वचालित रूप से अनुमानित किए जाते हैं।

   • यदि आप सोर्स डिस्ट्रीब्यूशन का उपयोग कर रहे हैं, तो यह चलाकर देखें: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag

   • यदि आप मान्यकरण प्रक्रिया को छोड़ना चाहते हैं, तो --novalidation फ़्लैग प्रदान करें, जैसे: pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag --novalidation (इसे सावधानी से उपयोग करें: ध्यान दें कि अनपेक्षित अमान्य दस्तावेज़ टूल के अप्रत्याशित व्यवहार का कारण बन सकते हैं)

लाइब्रेरी उपयोग

1. डेटा मॉडल

   • spdx_tools.spdx.model पैकेज आंतरिक SPDX v2.3 डेटा मॉडल का गठन करता है (v2.2 केवल इसका एक उपसमुच्चय है)। SPDX दस्तावेज़ निर्माण के लिए सभी प्रासंगिक क्लासें यहाँ पाई जाने वाली __init__.py में उजागर की गई हैं।
   • SPDX ऑब्जेक्ट @dataclass_with_properties के माध्यम से लागू किए जाते हैं, जो @dataclass का एक कस्टम विस्तार है।
   • प्रत्येक क्लास अपने गुणों और उनके संभावित प्रकारों की सूची से शुरू होती है। जब कोई डिफ़ॉल्ट मान प्रदान नहीं किया जाता है, तो गुण अनिवार्य होता है और आरंभीकरण के दौरान सेट किया जाना चाहिए।
   • टाइप हिंट का उपयोग करके, एक नया इंस्टेंस आरंभ करते समय या किसी इंस्टेंस पर गुण सेट/प्राप्त करते समय टाइप जाँच लागू की जाती है (गलत प्रकार क्रमशः ConstructorTypeError या TypeError उठाएंगे)। यह अमान्य गुणों को जल्दी पकड़ना और केवल मान्य दस्तावेज़ बनाना आसान बनाता है।
   • नोट: list.append(item) जैसी इन-प्लेस हेरफेर टाइप जाँच को दरकिनार कर देगी (list को दोबारा पढ़ने पर भी TypeError उठाया जाएगा)। हम इसके बजाय list = list + [item] उपयोग करने की सलाह देते हैं।

उदाहरण

यहाँ कुछ संभावित उपयोग-मामलों के उदाहरण दिए गए हैं जो आपको spdx-tools के साथ जल्दी शुरू करने में मदद करेंगे। यदि आप और अधिक उदाहरण चाहते हैं, जैसे कि शुरू से SPDX दस्तावेज़ कैसे बनाएं, तो उदाहरण फ़ोल्डर देखें।

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)

SPDX 3.0 के लिए त्वरित आरंभ

SPDX v2 के विपरीत, सभी तत्व अब केंद्रीय Element क्लास के उपवर्ग हैं। इसमें पैकेज, फ़ाइलें, स्निपेट, संबंध, एनोटेशन, साथ ही SBOM, SpdxDocument और भी बहुत कुछ शामिल है। क्रमांकन प्रयोजनों के लिए, वे सभी तत्व जिन्हें एक ही फ़ाइल में क्रमबद्ध किया जाना है, एक Payload में एकत्र किए जाते हैं। यह केवल एक शब्दकोश है जो प्रत्येक Element के SpdxId को स्वयं से मैप करता है। पेलोड को क्रमबद्ध करने के लिए write_payload() फ़ंक्शन का उपयोग करें। वर्तमान में दो विकल्प हैं:

• spdx_tools.spdx3.writer.json_ld.json_ld_writer मॉड्यूल पेलोड की एक JSON-LD फ़ाइल उत्पन्न करता है।
• spdx_tools.spdx3.writer.console.payload_writer मॉड्यूल कंसोल पर एक डीबग आउटपुट प्रिंट करता है। ध्यान दें कि यह SPDX विनिर्देश का आधिकारिक हिस्सा नहीं है और संभवतः एक बेहतर मानक उभरते ही इसे हटा दिया जाएगा।

आप spdx_tools.spdx3.bump_from_spdx2.spdx_document मॉड्यूल के माध्यम से SPDX v2 दस्तावेज़ को v3 में बदल सकते हैं। bump_spdx_document() फ़ंक्शन एक पेलोड लौटाएगा जिसमें एक SpdxDocument Element और v2 दस्तावेज़ में निहित प्रत्येक पैकेज, फ़ाइल, स्निपेट, संबंध या एनोटेशन के लिए एक Element होगा।

निर्भरताएँ

• PyYAML: https://pypi.org/project/PyYAML/ YAML को संभालने के लिए।
• xmltodict: https://pypi.org/project/xmltodict/ XML को संभालने के लिए।
• rdflib: https://pypi.python.org/pypi/rdflib/ RDF को संभालने के लिए।
• ply: https://pypi.org/project/ply/ tag-value को संभालने के लिए।
• click: https://pypi.org/project/click/ CLI इंटरफ़ेस बनाने के लिए।
• beartype: https://pypi.org/project/beartype/ टाइप जाँच के लिए।
• uritools: https://pypi.org/project/uritools/ URI की मान्यता के लिए।
• license-expression: https://pypi.org/project/license-expression/ SPDX लाइसेंस एक्सप्रेशन को संभालने के लिए।

सहायता

• मुद्दे, प्रश्न या प्रतिक्रिया यहाँ सबमिट करें https://github.com/spdx/tools-python/issues
• चैट में शामिल हों https://gitter.im/spdx-org/Lobby
• चर्चा में शामिल हों https://lists.spdx.org/g/spdx-tech और https://spdx.dev/participate/tech/

योगदान

योगदान का स्वागत है! कोडबेस में योगदान कैसे करें, इसके निर्देशों के लिए CONTRIBUTING.md देखें।

इतिहास

यह @ah450 (या https://github.com/a-h-i) द्वारा एक प्रारंभिक GSoC योगदान का परिणाम है और SPDX अपनाने वालों और उत्साही लोगों के समुदाय द्वारा बनाए रखा जाता है। SPDX v3.0 की रिलीज़ की तैयारी के लिए, रिपॉजिटरी में 11/2022 से 07/2023 की अवधि के दौरान एक बड़ा रीफैक्टरिंग हुआ है।