مكتبة بايثون لتحليل مستندات SPDX والتحقق منها وإنشائها

حالة CI (Linux وmacOS وWindows):

تغييرات جذرية v0.7 -> v0.8

يرجى العلم أن الإصدار القادم 0.8 قد خضع لإعادة هيكلة كبيرة استعدادًا للإصدار القادم من SPDX v3.0، مما يؤدي إلى تغييرات جذرية في API. يرجى الرجوع إلى دليل الترحيل لتحديث الكود الموجود لديك.

الميزات الرئيسية للإصدار v0.8 هي:

• التحقق الكامل من مستندات SPDX وفقًا لمواصفتي v2.2 وv2.3
• دعم تنسيق RDF الخاص بـ SPDX مع جميع ميزات v2.3
• دعم تجريبي لمواصفة SPDX v3 القادمة. لاحظ مع ذلك أن الدعم ليس كاملاً ولا مستقرًا في هذه المرحلة، حيث أن المواصفة لا تزال قيد التطور. الكود المتعلق بـ SPDX3 موجود في حزمة فرعية منفصلة "spdx3" واستخدامها اختياري. لا نوصي باستخدامها في كود الإنتاج بعد.

لاحظ أن v0.8 يدعم الكتابة فقط، وليس قراءة مستندات SPDX 3.0. انظر #760 للتفاصيل.

معلومات

تنفذ هذه المكتبة محللات ومحولات ومدققات ومعالجات 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

الميزات

• API لإنشاء ومعالجة مستندات SPDX v2.2 وv2.3
• تحليل وتحويل وإنشاء والتحقق من ملفات SPDX
• التنسيقات المدعومة: Tag/Value وRDF وJSON وYAML وXML
• تصور بنية مستند SPDX عن طريق إنشاء AGraph. ملاحظة: هذه ميزة اختيارية وتتطلب تثبيتًا إضافيًا للتبعيات الاختيارية

دعم تجريبي لـ SPDX 3.0

• إنشاء عناصر وحمولات v3.0
• تحويل مستندات v2.2/v2.3 إلى v3.0
• التسلسل إلى JSON-LD

انظر بدء سريع مع SPDX 3.0 أدناه. يعتمد التنفيذ على ملفات Markdown الوصفية في المستودع https://github.com/spdx/spdx-3-model (commit: a5372a3c145dbdfc1381fc1f791c68889aafc7ff). أحدث نموذج لـ SPDX 3.0 متاح على https://spdx.github.io/spdx-spec/v3.0/serializations/.

التثبيت

كما هو الحال دائمًا، يجب أن تعمل في بيئة افتراضية (venv). يمكنك تثبيت نسخة محلية من هذا المستودع باستخدام yourenv/bin/pip install . أو تثبيتها من PyPI (تحقق من أحدث إصدار وقم بتثبيته مثل yourenv/bin/pip install spdx-tools==0.8.3). لاحظ أنه على Windows سيكون Scripts بدلاً من bin.

كيفية الاستخدام

استخدام سطر الأوامر

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) ستلتف على فحص الأنواع (سيتم إثارة TypeError مع ذلك عند قراءة list مرة أخرى). نوصي باستخدام 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 المركزية. وهذا يشمل الحزم والملفات والمقتطفات والعلاقات والتعليقات التوضيحية، وكذلك SBOMs وSpdxDocuments والمزيد. لأغراض التسلسل، يتم جمع جميع العناصر التي سيتم تسلسلها في نفس الملف في Payload. هذا مجرد قاموس يربط SpdxId لكل عنصر بنفسه. استخدم دوال write_payload() لتسلسل حمولة. يوجد حاليًا خياران:

• وحدة spdx_tools.spdx3.writer.json_ld.json_ld_writer تولد ملف JSON-LD للحمولة.
• وحدة spdx_tools.spdx3.writer.console.payload_writer تطبع مخرجات تصحيح أخطاء إلى وحدة التحكم. لاحظ أن هذا ليس جزءًا رسميًا من مواصفة SPDX وسيتم على الأرجح إسقاطه بمجرد ظهور معيار أفضل.

يمكنك تحويل مستند SPDX v2 إلى v3 عبر وحدة spdx_tools.spdx3.bump_from_spdx2.spdx_document. ستعيد الدالة bump_spdx_document() حمولة تحتوي على عنصر SpdxDocument وعنصر واحد لكل حزمة أو ملف أو مقتطف أو علاقة أو تعليق توضيحي موجود في مستند v2.

التبعيات

• 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/ للتحقق من صحة URIs.
• 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 للحصول على إرشادات حول كيفية المساهمة في قاعدة الكود.

التاريخ

هذا هو نتيجة مساهمة أولية في GSoC بواسطة @ah450 (أو https://github.com/a-h-i) ويتم صيانته من قبل مجتمع من معتمدي ومتحمسي SPDX. من أجل التحضير لإصدار SPDX v3.0، خضع المستودع لإعادة هيكلة كبيرة خلال الفترة من 11/2022 إلى 07/2023.