إعداد بيئة تطوير 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.