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 (इसे सावधानी से उपयोग करें: ध्यान दें कि अनपेक्षित अमान्य दस्तावेज़ टूल के अप्रत्याशित व्यवहार का कारण बन सकते हैं)

   • सहायता के लिए pyspdxtools --help का उपयोग करें

3. ग्राफ़ निर्माण (वैकल्पिक सुविधा)

   • यह सुविधा प्रदान किए गए संबंधों के आधार पर SPDX दस्तावेज़ के सभी तत्वों और उनके कनेक्शनों को दर्शाने वाला एक ग्राफ़ बनाती है। ग्राफ़ को एक चित्र में प्रस्तुत किया जा सकता है। नीचे tests/spdx/data/SPDXJSONExample-v2.3.spdx.json फ़ाइल के लिए एक उदाहरण है:

   • सुनिश्चित करें कि आप वैकल्पिक निर्भरताएँ networkx और pygraphviz स्थापित करते हैं। ऐसा करने के लिए pip install ".[graph_generation]" चलाएँ।

   • pyspdxtools -i <input_file> --graph -o <output_file> का उपयोग करें जहाँ <output_file> pygraphviz के लिए मान्य प्रारूप वाला आउटपुट फ़ाइल नाम है (दस्तावेज़ यहाँ देखें)।

   • यदि आप सोर्स डिस्ट्रीब्यूशन का उपयोग कर रहे हैं, तो उदाहरण फ़ाइल की संरचना का अवलोकन प्रदान करने वाला png उत्पन्न करने के लिए pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png चलाकर देखें।

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

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 दस्तावेज़ का मुख्य प्रवेश बिंदु document.py मॉड्यूल से Document क्लास है, जो अन्य सभी क्लासों से जुड़ती है।
   • लाइसेंस प्रबंधन के लिए, license_expression लाइब्रेरी का उपयोग किया जाता है।
   • documentDescribes और hasFiles पर नोट: ये फ़ील्ड आंतरिक डेटा मॉडल में संबंधों में परिवर्तित हो जाएंगे। चूंकि ये पदावनत हैं, ये फ़ील्ड आउटपुट में नहीं लिखे जाएंगे।

2. पार्सिंग

   • समर्थित फ़ाइल अंत में से किसी एक के साथ किसी भी फ़ाइल को पार्स करने के लिए parse_anything.py मॉड्यूल से parse_file(file_name) का उपयोग करें।
   • सफल पार्सिंग एक Document इंस्टेंस लौटाएगी। असफल पार्सिंग सामने आई सभी समस्याओं की सूची के साथ SPDXParsingError उठाएगी।

3. मान्यकरण

   • Document क्लास के इंस्टेंस को मान्य करने के लिए validate_full_spdx_document(document) का उपयोग करें।
   • यह ValidationMessage ऑब्जेक्ट्स की एक सूची लौटाएगा, जिनमें से प्रत्येक में अमान्यता का वर्णन करने वाली एक String और मान्यकरण त्रुटि के स्रोत को इंगित करने के लिए एक ValidationContext होता है।
   • मान्यकरण दस्तावेज़ के SPDX संस्करण पर निर्भर करता है। ध्यान दें कि इस टूल द्वारा केवल SPDX-2.2 और SPDX-2.3 संस्करण समर्थित हैं।

4. लेखन