إعداد بيئة تطوير Calibre

calibre هو برنامج مفتوح المصدر بالكامل، مرخص بموجب ترخيص جنو العمومي العام الإصدار 3. هذا يعني أنك حر في تنزيل وتعديل البرنامج حسب رغبتك. في هذا القسم، ستتعلم كيفية إعداد بيئة تطوير calibre على نظام التشغيل الذي تختاره. calibre مكتوب بشكل أساسي بلغة بايثون مع بعض أكواد C/C++ للسرعة وواجهة النظام. لاحظ أن calibre يتطلب بايثون 3.8 على الأقل.

فلسفة التصميم

تتجذر calibre في عالم يونكس، مما يعني أن تصميمها معياري للغاية. تتفاعل الوحدات مع بعضها البعض عبر واجهات محددة جيدًا. هذا يجعل إضافة ميزات جديدة وإصلاح الأخطاء في calibre سهلاً للغاية، مما يؤدي إلى وتيرة تطوير سريعة. بسبب جذورها، يحتوي calibre على واجهة سطر أوامر شاملة لجميع وظائفه، موثقة في واجهة سطر الأوامر.

يتم التعبير عن التصميم المعياري لـ calibre عبر الإضافات. يوجد برنامج تعليمي حول كتابة إضافات calibre. على سبيل المثال، إضافة دعم لجهاز جديد إلى calibre يتضمن عادة كتابة أقل من 100 سطر من الكود في شكل إضافة برنامج تشغيل جهاز. يمكنك تصفح برامج التشغيل المدمجة. وبالمثل، يتضمن إضافة دعم لتنسيقات التحويل الجديدة كتابة إضافات تنسيق الإدخال/الإخراج. مثال آخر على التصميم المعياري هو نظام الوصفات لجلب الأخبار. لمزيد من الأمثلة على الإضافات المصممة لإضافة ميزات إلى calibre، راجع فهرس الإضافات.

تخطيط الكود

جميع أكواد بايثون لـ calibre موجودة في حزمة calibre. تحتوي هذه الحزمة على الحزم الفرعية الرئيسية التالية

  • devices - جميع برامج تشغيل الأجهزة. ما عليك سوى مراجعة بعض برامج التشغيل المدمجة للحصول على فكرة عن كيفية عملها.

    • للتفاصيل، راجع: devices.interface الذي يحدد الواجهة المدعومة بواسطة برامج تشغيل الأجهزة و devices.usbms الذي يحدد برنامج تشغيل عام يتصل بجهاز USBMS. جميع برامج التشغيل المستندة إلى USBMS في calibre ترث منه.

  • e-books - جميع أكواد تحويل/بيانات الكتب الإلكترونية. نقطة انطلاق جيدة هي calibre.ebooks.conversion.cli وهي الوحدة التي تشغل الأمر ebook-convert. يتم التحكم في عملية التحويل عبر conversion.plumber. الكود المستقل عن التنسيق موجود بالكامل في ebooks.oeb والكود المعتمد على التنسيق موجود في ebooks. format_name.

    • قراءة البيانات الوصفية وكتابتها وتنزيلها كلها موجودة في ebooks.metadata

    • يتم التحويل في مسار عمل، لهيكل مسار العمل، راجع مقدمة. يتكون مسار العمل من مكون إضافي للإدخال، وتحويلات مختلفة، ومكون إضافي للإخراج. الكود الذي يبني ويدير مسار العمل موجود في plumber.py. يعمل مسار العمل على تمثيل لكتاب إلكتروني يشبه ملف epub غير مضغوط، مع ملف البيان، والعمود الفقري، وجدول المحتويات، والدليل، ومحتوى html، وما إلى ذلك. الفئة التي تدير هذا التمثيل هي OEBBook في ebooks.oeb.base. التحويلات المختلفة التي يتم تطبيقها على الكتاب أثناء التحويلات موجودة في oeb/transforms/*.py. وتوجد مكونات الإدخال والإخراج الإضافية في conversion/plugins/*.py.

    • يتم تحرير الكتب الإلكترونية باستخدام كائن حاوية مختلف. يتم توثيقه في توثيق واجهة برمجة التطبيقات لأدوات تحرير الكتب الإلكترونية.

  • db - الواجهة الخلفية لقاعدة البيانات. راجع توثيق API لواجهة قاعدة البيانات لواجهة مكتبة calibre.

  • خادم المحتوى: srv هو خادم محتوى calibre.

  • gui2 - واجهة المستخدم الرسومية. تتم تهيئة واجهة المستخدم الرسومية في gui2.main و gui2.ui. عارض الكتب الإلكترونية موجود في gui2.viewer. محرر الكتب الإلكترونية موجود في gui2.tweak_book.

إذا كنت ترغب في تحديد نقاط الدخول لجميع ملفات calibre التنفيذية المختلفة، فانظر إلى بنية entry_points في linux.py.

إذا كنت بحاجة إلى مساعدة في فهم الكود، فانشر في منتدى التطوير وستحصل على المساعدة على الأرجح من أحد مطوري calibre العديدين.

الحصول على الكود

يمكنك الحصول على الكود المصدري لـ calibre بطريقتين، باستخدام نظام التحكم في الإصدارات أو بتنزيل مباشر لـ ملف tarball.

يستخدم calibre Git، وهو نظام تحكم في الإصدارات موزع. يتوفر Git على جميع الأنظمة الأساسية التي يدعمها calibre. بعد تثبيت Git، يمكنك الحصول على الكود المصدري لـ calibre بالأمر:

git clone https://github.com/kovidgoyal/calibre.git

على نظام Windows، ستحتاج إلى اسم المسار الكامل، والذي سيكون شيئًا مثل C:\Program Files\Git\git.exe.

calibre هو مشروع كبير جدًا بتاريخ تحكم في المصدر طويل جدًا، لذا قد يستغرق الأمر بعض الوقت (من 10 دقائق إلى ساعة حسب سرعة الإنترنت لديك).

إذا كنت ترغب في الحصول على الكود بشكل أسرع، فإن الكود المصدري لأحدث إصدار متاح دائمًا كـ أرشيف.

لتحديث فرع إلى أحدث كود، استخدم الأمر:

git pull --no-edit

يمكنك أيضًا تصفح الكود على GitHub.

إرسال تغييراتك لتضمينها

إذا كنت تخطط لإجراء بعض التغييرات الصغيرة فقط، يمكنك إجراء تغييراتك وإنشاء "تعليمات دمج" يمكنك بعد ذلك إرفاقها بتذكرة في متتبع أخطاء calibre هنا. للقيام بذلك، قم بإجراء تغييراتك، ثم قم بتشغيل:

git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes

سيؤدي هذا إلى إنشاء ملف my-changes في المجلد الحالي، ما عليك سوى إرفاقه بتذكرة على متتبع الأخطاء الخاص بـ calibre. لاحظ أن هذا سيتضمن جميع التغييرات التي قمت بها. إذا كنت ترغب في إرسال بعض التغييرات فقط، فيجب عليك تغيير origin/master أعلاه. لإرسال آخر تغيير فقط، استخدم:

git format-patch HEAD~1 --stdout > my-changes

لإرسال آخر n من التغييرات، استبدل 1 بـ n، على سبيل المثال، لآخر 3 تغييرات:

git format-patch HEAD~3 --stdout > my-changes

احذر من عدم تضمين عمليات الدمج عند استخدام HEAD~n.

إذا كنت تخطط للقيام بالكثير من التطوير على calibre، فإن أفضل طريقة هي إنشاء حساب GitHub. فيما يلي دليل أساسي لإعداد نسختك الخاصة من calibre بطريقة تسمح لك بإرسال طلبات سحب لتضمينها في مستودع calibre الرئيسي:

  • إعداد git على جهازك كما هو موضح في هذه المقالة: إعداد Git

  • إعداد مفاتيح ssh للمصادقة على GitHub، كما هو موضح هنا: إنشاء مفاتيح SSH

  • انتقل إلى https://github.com/kovidgoyal/calibre وانقر على زر Fork.

  • في الطرفية قم بـ:

    git clone git@github.com:<username>/calibre.git
git remote add upstream https://github.com/kovidgoyal/calibre.git

    استبدل <username> أعلاه باسم مستخدم GitHub الخاص بك. سيؤدي ذلك إلى سحب نسختك محليًا.

  • يمكنك إجراء التغييرات وتثبيتها وقتما تشاء. عندما تكون جاهزًا لدمج عملك، قم بـ:

    git push

    وانتقل إلى https://github.com/<username>/calibre وانقر على زر طلب سحب لإنشاء طلب سحب يمكن دمجه.

  • يمكنك تحديث نسختك المحلية بالكود من المستودع الرئيسي في أي وقت عن طريق القيام بـ:

    git pull upstream

يجب عليك أيضًا مراقبة منتدى تطوير calibre. قبل إجراء تغييرات كبيرة، يجب مناقشتها في المنتدى أو الاتصال بـ Kovid مباشرة (عنوان بريده الإلكتروني موجود في كل مكان في الكود المصدري).

بيئة تطوير ويندوز

ملاحظة

يجب عليك أيضًا الحصول على الكود المصدري لـ calibre بشكل منفصل كما هو موضح أعلاه.

قم بتثبيت calibre بشكل طبيعي، باستخدام مثبت Windows. ثم افتح موجه الأوامر وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا. على سبيل المثال:

cd C:\Users\kovid\work\calibre

calibre هو المجلد الذي يحتوي على المجلدين الفرعيين src و resources.

الخطوة التالية هي تعيين متغير البيئة CALIBRE_DEVELOP_FROM إلى المسار المطلق لمجلد src. لذا، باتباع المثال أعلاه، سيكون C:\Users\kovid\work\calibre\src. هنا دليل قصير لتعيين متغيرات البيئة على Windows.

بمجرد تعيين متغير البيئة، افتح موجه أوامر جديد وتحقق من أنه تم تعيينه بشكل صحيح باستخدام الأمر:

echo %CALIBRE_DEVELOP_FROM%

تعيين متغير البيئة هذا يعني أن calibre سيقوم الآن بتحميل جميع أكواد بايثون الخاصة به من الموقع المحدد.

هذا كل شيء! أنت الآن جاهز للبدء في تعديل كود calibre. على سبيل المثال، افتح الملف src\calibre\__init__.py في محرر النصوص المفضل لديك وأضف السطر:

print("Hello, world!")

بالقرب من أعلى الملف. الآن قم بتشغيل الأمر calibredb. يجب أن يكون السطر الأول من الإخراج هو Hello, world!.

يمكنك أيضًا إعداد بيئة تطوير calibre داخل برنامج Microsoft Visual Studio المجاني، إذا أردت، باتباع التعليمات هنا.

بيئة تطوير macOS

ملاحظة

يجب عليك أيضًا الحصول على الكود المصدري لـ calibre بشكل منفصل كما هو موضح أعلاه.

قم بتثبيت calibre بشكل طبيعي باستخدام ملف .dmg الموفر. ثم افتح Terminal وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا، على سبيل المثال:

cd /Users/kovid/work/calibre

calibre هو المجلد الذي يحتوي على المجلدين الفرعيين src و resources. توجد أدوات سطر أوامر calibre داخل حزمة تطبيق calibre، في /Applications/calibre.app/Contents/MacOS يجب عليك إضافة هذا المجلد إلى متغير بيئة PATH الخاص بك، إذا كنت ترغب في تشغيل أدوات سطر الأوامر بسهولة.

الخطوة التالية هي إنشاء نص برمجي (bash script) يقوم بتعيين متغير البيئة CALIBRE_DEVELOP_FROM إلى المسار المطلق لمجلد src عند تشغيل calibre في وضع التصحيح.

أنشئ ملف نص عادي:

#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g

احفظ هذا الملف باسم /usr/local/bin/calibre-develop، ثم اضبط أذوناته بحيث يمكن تنفيذه:

chmod +x /usr/local/bin/calibre-develop

بمجرد الانتهاء من ذلك، قم بتشغيل:

calibre-develop

يجب أن ترى بعض معلومات التشخيص في نافذة Terminal عند بدء تشغيل calibre، ويجب أن ترى نجمة بعد رقم الإصدار في نافذة واجهة المستخدم الرسومية، مما يشير إلى أنك تقوم بالتشغيل من المصدر.

بيئة تطوير Linux

ملاحظة

يجب عليك أيضًا الحصول على الكود المصدري لـ calibre بشكل منفصل كما هو موضح أعلاه.

يتم تطوير calibre بشكل أساسي على نظام Linux. لديك خياران في إعداد بيئة التطوير. يمكنك تثبيت ثنائي calibre كالمعتاد واستخدامه كبيئة تشغيل للقيام بتطويرك. هذا النهج مشابه لما هو مستخدم في Windows و macOS. بدلاً من ذلك، يمكنك تثبيت calibre من المصدر. توجد تعليمات إعداد بيئة التطوير من المصدر في ملف INSTALL في شجرة المصدر. هنا سنتناول استخدام الثنائي كبيئة تشغيل، وهي الطريقة الموصى بها.

قم بتثبيت calibre باستخدام المثبت الثنائي. ثم افتح طرفية وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا، على سبيل المثال:

cd /home/kovid/work/calibre

calibre هو المجلد الذي يحتوي على المجلدين الفرعيين src و resources.

الخطوة التالية هي تعيين متغير البيئة CALIBRE_DEVELOP_FROM إلى المسار المطلق لمجلد src. لذا، باتباع المثال أعلاه، سيكون /home/kovid/work/calibre/src. تعتمد كيفية تعيين متغيرات البيئة على توزيعة Linux التي تستخدمها وأي shell تستخدمه.

ملاحظة

It is recommended to use the binary installer provided from upstream. Should you insist on using a package provided by your distribution, use the CALIBRE_PYTHON_PATH and CALIBRE_RESOURCES_PATH variables instead. You can get these by running calibre-debug --paths. But note that distribution calibre packages are often terminally broken and are completely unsupported.

بمجرد تعيين متغير البيئة، افتح طرفية جديدة وتحقق من أنه تم تعيينه بشكل صحيح باستخدام الأمر:

echo $CALIBRE_DEVELOP_FROM

تعيين متغير البيئة هذا يعني أن calibre سيقوم الآن بتحميل جميع أكواد بايثون الخاصة به من الموقع المحدد.

هذا كل شيء! أنت الآن جاهز للبدء في تعديل كود calibre. على سبيل المثال، افتح الملف src/calibre/__init__.py في محرر النصوص المفضل لديك وأضف السطر:

print("Hello, world!")

بالقرب من أعلى الملف. الآن قم بتشغيل الأمر calibredb. يجب أن يكون السطر الأول من الإخراج هو Hello, world!.

امتلاك تثبيتات calibre "عادية" و "تطوير" منفصلة على نفس الكمبيوتر

شجرة مصادر calibre مستقرة جدًا ونادرًا ما تتعطل، ولكن إذا شعرت بالحاجة إلى التشغيل من المصدر على مكتبة اختبار منفصلة وتشغيل إصدار calibre الذي تم إصداره مع مكتبتك اليومية، يمكنك تحقيق ذلك بسهولة باستخدام ملفات .bat أو نصوص shell لتشغيل calibre. يوضح المثال أدناه كيفية القيام بذلك على نظام Windows باستخدام ملفات .bat (التعليمات للمنصات الأخرى هي نفسها، فقط استخدم نص shell بدلاً من ملف .bat)

لتشغيل إصدار calibre الرسمي مع مكتبتك اليومية:

calibre-normal.bat:

calibre.exe "--with-library=C:\path\to\everyday\library folder"

calibre-dev.bat:

set CALIBRE_DEVELOP_FROM=C:\path\to\calibre\checkout\src
calibre.exe "--with-library=C:\path\to\test\library folder"

نصائح التصحيح

بايثون هي لغة ذات كتابة ديناميكية مع إمكانيات ممتازة لـ الاستبطان. كتب كوفيد الكود الأساسي لـ calibre دون استخدام مصحح أخطاء مرة واحدة. هناك العديد من الاستراتيجيات لتصحيح أخطاء كود calibre:

استخدام عبارات الطباعة

هذه هي الطريقة المفضلة لكوفيد للتصحيح. ببساطة أدخل عبارات الطباعة في النقاط المهمة وقم بتشغيل برنامجك في الطرفية. على سبيل المثال، يمكنك بدء الواجهة الرسومية من الطرفية كالتالي:

calibre-debug -g

وبالمثل، يمكنك بدء عارض الكتب الإلكترونية كالتالي:

calibre-debug -w /path/to/file/to/be/viewed

يمكن بدء محرر الكتب الإلكترونية كالتالي:

calibre-debug --edit-book /path/to/be/edited

استخدام مترجم بايثون تفاعلي

يمكنك إدراج السطرين التاليين من الكود لبدء جلسة بايثون تفاعلية عند تلك النقطة:

from calibre import ipython
ipython(locals())

عند التشغيل من سطر الأوامر، سيؤدي هذا إلى بدء مترجم بايثون تفاعلي مع إمكانية الوصول إلى جميع المتغيرات المعرفة محليًا (المتغيرات في النطاق المحلي). حتى موجه الأوامر التفاعلي لديه إكمال Tab لخصائص الكائن ويمكنك استخدام مرافق بايثون المختلفة للاستبطان، مثل dir()، type()، repr()، إلخ.

استخدام مصحح أخطاء بايثون كمصحح أخطاء عن بعد

يمكنك استخدام مصحح أخطاء بايثون المدمج (pdb) كمصحح أخطاء عن بعد من سطر الأوامر. أولاً، ابدأ مصحح الأخطاء عن بعد عند النقطة في كود calibre التي تهتم بها، هكذا:

from calibre.rpdb import set_trace
set_trace()

ثم قم بتشغيل calibre، إما بشكل طبيعي، أو باستخدام أحد أوامر calibre-debug الموضحة في القسم السابق. بمجرد الوصول إلى النقطة المذكورة أعلاه في الكود، سيتوقف calibre، في انتظار اتصال المصحح.

الآن افتح طرفية أو موجه أوامر واستخدم الأمر التالي لبدء جلسة التصحيح:

calibre-debug -c "from calibre.rpdb import cli; cli()"

يمكنك قراءة كيفية استخدام مصحح أخطاء بايثون في وثائق مكتبة بايثون القياسية لوحدة pdb.

ملاحظة

افتراضيًا، سيحاول مصحح الأخطاء عن بعد الاتصال على المنفذ 4444. يمكنك تغييره، عن طريق تمرير معلمة المنفذ إلى كل من دالتي set_trace() و cli() أعلاه، كالتالي: set_trace(port=1234) و cli(port=1234).

ملاحظة

لا يستطيع مصحح أخطاء بايثون التعامل مع سلاسل متعددة، لذا يجب عليك استدعاء set_trace مرة واحدة لكل سلسلة، في كل مرة برقم منفذ مختلف.

استخدام مصحح الأخطاء في بيئة التطوير المتكاملة (IDE) المفضلة لديك في بايثون

من الممكن استخدام مصحح الأخطاء المدمج في بيئة التطوير المتكاملة (IDE) المفضلة لديك في بايثون، إذا كانت تدعم تصحيح الأخطاء عن بُعد. الخطوة الأولى هي إضافة مجلد src الخاص بـ calibre إلى PYTHONPATH في بيئة التطوير المتكاملة الخاصة بك. بعبارة أخرى، يجب أن يكون المجلد الذي عينته كـ CALIBRE_DEVELOP_FROM أعلاه، موجودًا أيضًا في PYTHONPATH الخاص بـ بيئة التطوير المتكاملة الخاصة بك.

ثم ضع وحدة مصحح الأخطاء عن بعد الخاصة بـ IDE في المجلد الفرعي src من نسخة الكود المصدري لـ calibre. أضف أي كود مطلوب لتشغيل مصحح الأخطاء عن بعد إلى calibre عند النقطة المهمة، على سبيل المثال في الدالة الرئيسية. ثم قم بتشغيل calibre كالمعتاد. يجب أن تكون بيئة التطوير المتكاملة الخاصة بك الآن قادرة على الاتصال بمصحح الأخطاء عن بعد الذي يعمل داخل calibre.

تنفيذ نصوص برمجية عشوائية في بيئة بايثون لـ calibre

يوفر الأمر calibre-debug بعض المفاتيح المفيدة لـ تنفيذ الكود الخاص بك، مع الوصول إلى وحدات calibre:

calibre-debug -c "some Python code"

رائع لاختبار مقتطف صغير من الكود في سطر الأوامر. يعمل بنفس طريقة مفتاح -c لمترجم بايثون:

calibre-debug myscript.py

يمكن استخدامه لتنفيذ نص بايثون الخاص بك. يعمل بنفس الطريقة التي يتم بها تمرير النص إلى مترجم بايثون، باستثناء أن بيئة calibre مُهيأة بالكامل، لذلك يمكنك استخدام جميع أكواد calibre في النص الخاص بك. لاستخدام وسائط سطر الأوامر مع النص الخاص بك، استخدم الشكل:

calibre-debug myscript.py -- --option1 arg1

تتسبب -- في تمرير جميع الوسائط اللاحقة إلى النص البرمجي الخاص بك.

استخدام calibre في مشاريعك

من الممكن استخدام دوال/أكواد calibre مباشرة في مشروع بايثون الخاص بك. توجد طريقتان للقيام بذلك:

تثبيت calibre الثنائي

إذا كان لديك تثبيت ثنائي لـ calibre، يمكنك استخدام مترجم بايثون المضمن مع calibre، كالتالي:

calibre-debug /path/to/your/python/script.py -- arguments to your script

تثبيت المصدر على Linux

بالإضافة إلى استخدام التقنية المذكورة أعلاه، إذا قمت بتثبيت المصدر على Linux، يمكنك أيضًا استيراد calibre مباشرة، كالتالي:

import init_calibre
import calibre

print(calibre.__version__)

من الضروري أن تقوم باستيراد وحدة init_calibre قبل أي وحدات/حزم calibre أخرى لأنها تهيئ المترجم لتشغيل كود calibre.

توثيق API لأجزاء مختلفة من calibre