مكتبة بايثون لتحليل مستندات 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 (استخدم هذا بحذر: لاحظ أن المستندات غير الصالحة غير المكتشفة قد تؤدي إلى سلوك غير متوقع للأداة)

   • للمساعدة استخدم 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 (تحقق من التوثيق هنا).

   • إذا كنت تستخدم توزيعة مصدرية، جرب تشغيل pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png لتوليد ملف png مع نظرة عامة على بنية ملف المثال.

استخدام المكتبة

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 هي فئة Document من وحدة document.py، والتي ترتبط بجميع الفئات الأخرى.
   • للتعامل مع التراخيص، يتم استخدام مكتبة license_expression.
   • ملاحظة حول documentDescribes وhasFiles: سيتم تحويل هذه الحقول إلى علاقات في نموذج البيانات الداخلي. نظرًا لأنها مهملة، لن تتم كتابة هذه الحقول في المخرجات.

2. التحليل

   • استخدم parse_file(file_name) من وحدة parse_anything.py لتحليل أي ملف بأحد نهايات الملفات المدعومة.
   • التحليل الناجح سيعيد مثيل Document. التحليل غير الناجح سيثير SPDXParsingError مع قائمة بجميع المشكلات التي تمت مواجهتها.

3. التحقق

   • استخدم validate_full_spdx_document(document) للتحقق من مثيل من فئة Document.
   • سيعيد هذا قائمة بكائنات ValidationMessage، يتكون كل منها من سلسلة تصف عدم الصلاحية وValidationContext لتحديد مصدر خطأ التحقق بدقة.
   • يعتمد التحقق على إصدار SPDX للمستند. لاحظ أن الإصدارين SPDX-2.2 وSPDX-2.3 فقط مدعومان من هذه الأداة.

4. الكتابة

   • استخدم write_file(document, file_name) من وحدة write_anything.py لكتابة مثيل Document إلى الملف المحدد. يتم تحديد تنسيق التسلسل من نهاية اسم الملف.
   • يتم إجراء التحقق افتراضيًا قبل عملية الكتابة، والتي يتم إلغاؤها إذا كان المستند غير صالح. يمكنك تخطي التحقق عبر write_file(document, file_name, validate=False). تحذير: يمكن تسلسل المستندات الصالحة فقط بشكل موثوق؛ تسلسل المستندات غير الصالحة غير مدعوم.

مثال

فيما يلي بعض الأمثلة على حالات الاستخدام الممكنة لمساعدتك على البدء بسرعة مع spdx-tools. إذا كنت تريد المزيد من الأمثلة، مثل كيفية إنشاء مستند SPDX من الصفر، ألقِ نظرة على مجلد الأمثلة.

import logging

from license_expression import get_spdx_licensing