استراتيجية إدماج التبعيات

السياسة

تتطلّب بيئة التشغيل المكتفية بذاتها في Apothem أن تكون تبعيات المحرّك من الطرف الثالث قابلةً للاستيراد من شجرة المصدر نفسها. لذا تُعالَج كلّ تبعية من تبعيات بيئة التشغيل بإحدى ثلاث طرق:

• مُدمَجة بوصفها مصدرًا بلغة Python الخالصة تحت src/apothem/_vendor/. يُقدِّم التمهيد ذلك الدليل في مقدّمة sys.path أمام site-packages، فتفوز النسخة المُدمَجة بسباق حلّ الاستيراد على أيّ إصدار مُثبَّت على النظام.
• مُستبدَلة برقعة بلغة Python الخالصة حين يشحن التوزيع المنبع امتدادًا مُصرَّفًا لا يمكنه السفر مصدرًا محمولًا.
• مُبقاة بوصفها متطلّبًا مسبقًا موثَّقًا للنظام حين يحمل الإدماج سطحًا أكثر ممّا يوفّر.

قاعدة الوضع صارمة: التوزيعات بلغة Python الخالصة وحدها تسكن في _vendor/. أمّا الامتداد المُصرَّف (C وRust/PyO3 وCython) فهو خاصّ بالمنصّة وABI ولا ينتمي إلى هناك أبدًا. تحمل كلّ حزمة مُدمَجة ملفّ ترخيصها المنبع بجوار المصدر.

ما الذي يُدمَج

رقعة rpds

يعتمد jsonschema المنبع على rpds-py، وهي مكتبة لبُنى البيانات المُستديمة مُنفَّذة بلغة Rust (PyO3) تشحن .pyd/.so مُصرَّفًا مع غلاف .py رقيق فحسب. لا يوجد مصدر محمول بلغة Python الخالصة لنسخه، فلا يمكن إدماجه.

بدلًا من ذلك، src/apothem/_vendor/rpds/ هي رقعة بلغة Python الخالصة تُعيد تنفيذ المجموعة الجزئية من API بدقّة تامّة كما يمارسها jsonschema وreferencing — HashTrieMap وHashTrieSet وList — مدعومةً بالأنواع المُضمَّنة dict / frozenset / tuple. تحترم الرقعة عقد الاستدامة المنبع: تُعيد الطرائق المُحوِّرة نسخةً جديدة وتترك المُستقبِل دون تغيير، وهو ما يعوّل عليه المستهلكون حين يخزّنون هذه البُنى بوصفها قيمًا افتراضية لحقول الأصناف المُجمَّدة. مخطّطات Apothem صغيرة، فلا يهمّ فرق الأداء مقابل تنفيذ Rust.

ما الذي لا يُدمَج

• click — إطار CLI. هو كبير وموجَّه نحو الطرفية ومتوفّر على نطاق واسع، فيبقى متطلّبًا مسبقًا للنظام يتحقّق منه المُثبِّتون.
• rich — مكتبة تصيير الطرفية، مُبقاة متطلّبًا مسبقًا للنظام للأسباب نفسها.
• rpds-py — مُصرَّف؛ مُستبدَل بالرقعة أعلاه.
• امتداد libyaml بلغة C — اختياري؛ حزمة yaml المُدمَجة بلغة Python الخالصة لا تحتاج إليه قطّ.

يتحقّق المُثبِّتون من أنّ click وrich قابلان للاستيراد تحت المفسّر المُختار قبل القيام بأيّ شيء؛ فإن غاب أحدهما سمّياه وعرضا تثبيته لك — بتأكيدك، أو تلقائيًّا عبر --yes / APOTHEM_AUTO_INSTALL_DEPS=1.

تحديث حزمة مُدمَجة

لتحديث حزمة مُدمَجة إلى إصدار منبع أحدث:

1. اجلب توزيع المصدر المنبع عند الإصدار المُستهدَف.
2. انسخ دليل الحزمة بلغة Python الخالصة إلى src/apothem/_vendor/، مُستبدِلًا النسخة السابقة، وحدِّث ملفّ الترخيص المجاور.
3. حدِّث src/apothem/_vendor/vendor.txt — الإغلاق المُثبَّت — بحيث يطابق سطر name==version الخاصّ بالحزمة إصدار المنبع الجديد، وحدِّث كتلة [[annotations]] الخاصّة بالحزمة في REUSE.toml الجذري إن تغيّر ترخيصها أو حقوقها المنبع. كلاهما مطلوب في مجموعة التغيير نفسها التي تضمّ النسخ (تكليف التبعيات الحيّة)؛ يقرؤهما مُدقِّقو سلسلة التوريد وبوّابة reuse lint.
4. اترك مسارات الاستيراد دون مساس — يستورد المستهلكون الأسماء القانونية، وتُتمّ أولوية sys.path في التمهيد بقيّة العمل.
5. شغِّل مجموعة الاختبارات وبوّابة المطابقة؛ سلوك حزمة التحقّق مُغطّى باختبارات التحقّق من profile والمخطّط.

تُحدَّث رقعة rpds بطريقة مختلفة: إنّها تتبّع المجموعة الجزئية من API التي يستخدمها مستهلكوها، فيُفحَص تحديث jsonschema/referencing مقابل السطح المُنفَّذ للرقعة، ولا تنمو الرقعة إلّا حين يظهر موضع استدعاء جديد.

الخطوة التالية المُوصى بها

اقرأ صفحة بيئة التشغيل المكتفية بذاتها لمعرفة كيف تتلاءم الشجرة المُدمَجة، ونموذج الاستدعاء PYTHONPATH=src، وتمهيد شجرة الإضافة معًا في وقت التشغيل.