calibre - en to ar translation catalogue (102 entries)

en: Setting up a calibre development environment
ar: إعداد بيئة تطوير Calibre

en: calibre is completely open source, licensed under the `GNU GPL v3 <https://www.gnu.org/licenses/gpl.html>`_. This means that you are free to download and modify the program to your heart's content. In this section, you will learn how to get a calibre development environment set up on the operating system of your choice. calibre is written primarily in `Python <https://www.python.org>`_ with some C/C++ code for speed and system interfacing. Note that calibre requires at least Python 3.8.
ar: calibre هو برنامج مفتوح المصدر بالكامل، مرخص بموجب `ترخيص جنو العمومي العام الإصدار 3 <https://www.gnu.org/licenses/gpl.html>`_. هذا يعني أنك حر في تنزيل وتعديل البرنامج حسب رغبتك. في هذا القسم، ستتعلم كيفية إعداد بيئة تطوير calibre على نظام التشغيل الذي تختاره. calibre مكتوب بشكل أساسي بلغة `بايثون <https://www.python.org>`_ مع بعض أكواد C/C++ للسرعة وواجهة النظام. لاحظ أن calibre يتطلب بايثون 3.8 على الأقل.

en: Contents
ar: المحتويات

en: Design philosophy
ar: فلسفة التصميم

en: calibre has its roots in the Unix world, which means that its design is highly modular. The modules interact with each other via well defined interfaces. This makes adding new features and fixing bugs in calibre very easy, resulting in a frenetic pace of development. Because of its roots, calibre has a comprehensive command line interface for all its functions, documented in :doc:`generated/en/cli-index`.
ar: تتجذر calibre في عالم يونكس، مما يعني أن تصميمها معياري للغاية. تتفاعل الوحدات مع بعضها البعض عبر واجهات محددة جيدًا. هذا يجعل إضافة ميزات جديدة وإصلاح الأخطاء في calibre سهلاً للغاية، مما يؤدي إلى وتيرة تطوير سريعة. بسبب جذورها، يحتوي calibre على واجهة سطر أوامر شاملة لجميع وظائفه، موثقة في :doc:`generated/ar/cli-index`.

en: The modular design of calibre is expressed via ``Plugins``. There is a :ref:`tutorial <customize>` on writing calibre plugins. For example, adding support for a new device to calibre typically involves writing less than a 100 lines of code in the form of a device driver plugin. You can browse the `built-in drivers <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>`_. Similarly, adding support for new conversion formats involves writing input/output format plugins. Another example of the modular design is the :ref:`recipe system <news>` for fetching news. For more examples of plugins designed to add features to calibre, see the `Index of plugins <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_.
ar: يتم التعبير عن التصميم المعياري لـ calibre عبر ``الإضافات``. يوجد :ref:`برنامج تعليمي <customize>` حول كتابة إضافات calibre. على سبيل المثال، إضافة دعم لجهاز جديد إلى calibre يتضمن عادة كتابة أقل من 100 سطر من الكود في شكل إضافة برنامج تشغيل جهاز. يمكنك تصفح `برامج التشغيل المدمجة <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>`_. وبالمثل، يتضمن إضافة دعم لتنسيقات التحويل الجديدة كتابة إضافات تنسيق الإدخال/الإخراج. مثال آخر على التصميم المعياري هو :ref:`نظام الوصفات <news>` لجلب الأخبار. لمزيد من الأمثلة على الإضافات المصممة لإضافة ميزات إلى calibre، راجع `فهرس الإضافات <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_.

en: Code layout
ar: تخطيط الكود

en: All the calibre Python code is in the ``calibre`` package. This package contains the following main sub-packages
ar: جميع أكواد بايثون لـ calibre موجودة في حزمة ``calibre``. تحتوي هذه الحزمة على الحزم الفرعية الرئيسية التالية

en: devices - All the device drivers. Just look through some of the built-in drivers to get an idea for how they work.
ar: devices - جميع برامج تشغيل الأجهزة. ما عليك سوى مراجعة بعض برامج التشغيل المدمجة للحصول على فكرة عن كيفية عملها.

en: For details, see: ``devices.interface`` which defines the interface supported by device drivers and ``devices.usbms`` which defines a generic driver that connects to a USBMS device. All USBMS based drivers in calibre inherit from it.
ar: للتفاصيل، راجع: ``devices.interface`` الذي يحدد الواجهة المدعومة بواسطة برامج تشغيل الأجهزة و ``devices.usbms`` الذي يحدد برنامج تشغيل عام يتصل بجهاز USBMS. جميع برامج التشغيل المستندة إلى USBMS في calibre ترث منه.

en: e-books  - All the e-book conversion/metadata code. A good starting point is ``calibre.ebooks.conversion.cli`` which is the module powering the :command:`ebook-convert` command. The conversion process is controlled via ``conversion.plumber``. The format independent code is all in ``ebooks.oeb`` and the format dependent code is in ``ebooks.format_name``.
ar: e-books - جميع أكواد تحويل/بيانات الكتب الإلكترونية. نقطة انطلاق جيدة هي ``calibre.ebooks.conversion.cli`` 
    وهي الوحدة التي تشغل الأمر :command:`ebook-convert`. يتم التحكم في عملية التحويل عبر ``conversion.plumber``. 
    الكود المستقل عن التنسيق موجود بالكامل في ``ebooks.oeb`` والكود المعتمد على التنسيق موجود في ``ebooks.
    format_name``.

en: Metadata reading, writing, and downloading is all in ``ebooks.metadata``
ar: قراءة البيانات الوصفية وكتابتها وتنزيلها كلها موجودة في ``ebooks.metadata``

en: Conversion happens in a pipeline, for the structure of the pipeline, see :ref:`conversion-introduction`. The pipeline consists of an input plugin, various transforms and an output plugin. The code that constructs and drives the pipeline is in :file:`plumber.py`. The pipeline works on a representation of an e-book that is like an unzipped epub, with manifest, spine, toc, guide, html content, etc. The class that manages this representation is OEBBook in ``ebooks.oeb.base``. The various transformations that are applied to the book during conversions live in :file:`oeb/transforms/*.py`. And the input and output plugins live in :file:`conversion/plugins/*.py`.
ar: يتم التحويل في مسار عمل، لهيكل مسار العمل، راجع :ref:`conversion-introduction`. يتكون مسار العمل من مكون إضافي للإدخال، وتحويلات مختلفة، ومكون إضافي للإخراج. الكود الذي يبني ويدير مسار العمل موجود في :file:`plumber.py`. يعمل مسار العمل على تمثيل لكتاب إلكتروني يشبه ملف epub غير مضغوط، مع ملف البيان، والعمود الفقري، وجدول المحتويات، والدليل، ومحتوى html، وما إلى ذلك. الفئة التي تدير هذا التمثيل هي OEBBook في ``ebooks.oeb.base``. التحويلات المختلفة التي يتم تطبيقها على الكتاب أثناء التحويلات موجودة في :file:`oeb/transforms/*.py`. وتوجد مكونات الإدخال والإخراج الإضافية في :file:`conversion/plugins/*.py`.

en: E-book editing happens using a different container object. It is documented in :ref:`polish_api`.
ar: يتم تحرير الكتب الإلكترونية باستخدام كائن حاوية مختلف. يتم توثيقه في :ref:`polish_api`.

en: db - The database back-end. See :ref:`db_api` for the interface to the calibre library.
ar: db - الواجهة الخلفية لقاعدة البيانات. راجع :ref:`db_api` لواجهة مكتبة calibre.

en: Content server: ``srv`` is the calibre Content server.
ar: خادم المحتوى: ``srv`` هو خادم محتوى calibre.

en: gui2 - The Graphical User Interface. GUI initialization happens in ``gui2.main`` and ``gui2.ui``. The e-book-viewer is in ``gui2.viewer``. The e-book editor is in ``gui2.tweak_book``.
ar: gui2 - واجهة المستخدم الرسومية. تتم تهيئة واجهة المستخدم الرسومية في ``gui2.main`` و ``gui2.ui``. عارض الكتب الإلكترونية موجود في ``gui2.viewer``. محرر الكتب الإلكترونية موجود في ``gui2.tweak_book``.

en: If you want to locate the entry points for all the various calibre executables, look at the ``entry_points`` structure in `linux.py <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>`_.
ar: إذا كنت ترغب في تحديد نقاط الدخول لجميع ملفات calibre التنفيذية المختلفة، فانظر إلى بنية ``entry_points`` في `linux.py <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>`_.

en: If you need help understanding the code, post in the `development forum <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_ and you will most likely get help from one of calibre's many developers.
ar: إذا كنت بحاجة إلى مساعدة في فهم الكود، فانشر في `منتدى التطوير <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_ وستحصل على المساعدة على الأرجح من أحد مطوري calibre العديدين.

en: Getting the code
ar: الحصول على الكود

en: You can get the calibre source code in two ways, using a version control system or directly downloading a :website_base:`tarball <dist/src>`.
ar: يمكنك الحصول على الكود المصدري لـ calibre بطريقتين، باستخدام نظام التحكم في الإصدارات أو بتنزيل مباشر لـ :website_base:`ملف tarball <dist/src>`.

en: calibre uses `Git <https://www.git-scm.com/>`_, a distributed version control system. Git is available on all the platforms calibre supports.  After installing Git, you can get the calibre source code with the command::
ar: يستخدم calibre `Git <https://www.git-scm.com/>`_، وهو نظام تحكم في الإصدارات موزع. يتوفر Git على جميع الأنظمة الأساسية التي يدعمها calibre. بعد تثبيت Git، يمكنك الحصول على الكود المصدري لـ calibre بالأمر::

en: On Windows you will need the complete path name, that will be something like :file:`C:\\Program Files\\Git\\git.exe`.
ar: على نظام Windows، ستحتاج إلى اسم المسار الكامل، والذي سيكون شيئًا مثل  :file:`C:\\Program Files\\Git\\git.exe`.

en: calibre is a very large project with a very long source control history, so the above can take a while (10 mins to an hour depending on your internet speed).
ar: calibre هو مشروع كبير جدًا بتاريخ تحكم في المصدر طويل جدًا، لذا قد يستغرق الأمر بعض الوقت (من 10 دقائق إلى ساعة حسب سرعة الإنترنت لديك).

en: If you want to get the code faster, the source code for the latest release is always available as an :website_base:`archive <dist/src>`.
ar: إذا كنت ترغب في الحصول على الكود بشكل أسرع، فإن الكود المصدري لأحدث إصدار متاح دائمًا كـ :website_base:`أرشيف <dist/src>`.

en: To update a branch to the latest code, use the command::
ar: لتحديث فرع إلى أحدث كود، استخدم الأمر::

en: You can also browse the code at `GitHub <https://github.com/kovidgoyal/calibre>`_.
ar: يمكنك أيضًا تصفح الكود على `GitHub <https://github.com/kovidgoyal/calibre>`_.

en: Submitting your changes to be included
ar: إرسال تغييراتك لتضمينها

en: If you only plan to make a few small changes, you can make your changes and create a "merge directive" which you can then attach to a ticket in the calibre `bug tracker <https://bugs.launchpad.net/calibre>`_. To do this, make your changes, then run::
ar: إذا كنت تخطط لإجراء بعض التغييرات الصغيرة فقط، يمكنك إجراء تغييراتك وإنشاء "تعليمات دمج" يمكنك بعد ذلك إرفاقها بتذكرة في متتبع أخطاء calibre `هنا <https://bugs.launchpad.net/calibre>`_. للقيام بذلك، قم بإجراء تغييراتك، ثم قم بتشغيل::

en: This will create a :file:`my-changes` file in the current folder, simply attach that to a ticket on the calibre `bug tracker <https://bugs.launchpad.net/calibre>`_. Note that this will include *all* the commits you have made. If you only want to send some commits, you have to change ``origin/master`` above. To send only the last commit, use::
ar: سيؤدي هذا إلى إنشاء ملف :file:`my-changes` في المجلد الحالي، ما عليك سوى إرفاقه بتذكرة على `متتبع الأخطاء الخاص بـ calibre <https://bugs.launchpad.net/calibre>`_. لاحظ أن هذا سيتضمن *جميع* التغييرات التي قمت بها. إذا كنت ترغب في إرسال بعض التغييرات فقط، فيجب عليك تغيير ``origin/master`` أعلاه. لإرسال آخر تغيير فقط، استخدم::

en: To send the last *n* commits, replace *1* with *n*, for example, for the last 3 commits::
ar: لإرسال آخر *n* من التغييرات، استبدل *1* بـ *n*، على سبيل المثال، لآخر 3 تغييرات::

en: Be careful to not include merges when using ``HEAD~n``.
ar: احذر من عدم تضمين عمليات الدمج عند استخدام ``HEAD~n``.

en: If you plan to do a lot of development on calibre, then the best method is to create a `GitHub <https://github.com>`__ account. Below is a basic guide to setting up your own fork of calibre in a way that will allow you to submit pull requests for inclusion into the main calibre repository:
ar: إذا كنت تخطط للقيام بالكثير من التطوير على calibre، فإن أفضل طريقة هي إنشاء حساب `GitHub <https://github.com>`__. فيما يلي دليل أساسي لإعداد نسختك الخاصة من calibre بطريقة تسمح لك بإرسال طلبات سحب لتضمينها في مستودع calibre الرئيسي:

en: Setup git on your machine as described in this article: `Setup Git <https://help.github.com/articles/set-up-git>`_
ar: إعداد git على جهازك كما هو موضح في هذه المقالة: `إعداد Git <https://help.github.com/articles/set-up-git>`_

en: Setup ssh keys for authentication to GitHub, as described here: `Generating SSH keys <https://help.github.com/articles/generating-ssh-keys>`_
ar: إعداد مفاتيح ssh للمصادقة على GitHub، كما هو موضح هنا: `إنشاء مفاتيح SSH <https://help.github.com/articles/generating-ssh-keys>`_

en: Go to https://github.com/kovidgoyal/calibre and click the :guilabel:`Fork` button.
ar: انتقل إلى https://github.com/kovidgoyal/calibre وانقر على زر :guilabel:`Fork`.

en: In a Terminal do::
ar: في الطرفية قم بـ::

en: Replace <username> above with your GitHub username. That will get your fork checked out locally.
ar: استبدل <username> أعلاه باسم مستخدم GitHub الخاص بك. سيؤدي ذلك إلى سحب نسختك محليًا.

en: You can make changes and commit them whenever you like. When you are ready to have your work merged, do a::
ar: يمكنك إجراء التغييرات وتثبيتها وقتما تشاء. عندما تكون جاهزًا لدمج عملك، قم بـ::

en: and go to ``https://github.com/<username>/calibre`` and click the :guilabel:`Pull Request` button to generate a pull request that can be merged.
ar: وانتقل إلى ``https://github.com/<username>/calibre`` وانقر على زر :guilabel:`طلب سحب` لإنشاء طلب سحب يمكن دمجه.

en: You can update your local copy with code from the main repo at any time by doing::
ar: يمكنك تحديث نسختك المحلية بالكود من المستودع الرئيسي في أي وقت عن طريق القيام بـ::

en: You should also keep an eye on the calibre `development forum <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_. Before making major changes, you should discuss them in the forum or contact Kovid directly (his email address is all over the source code).
ar: يجب عليك أيضًا مراقبة `منتدى تطوير calibre <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_. قبل إجراء تغييرات كبيرة، يجب مناقشتها في المنتدى أو الاتصال بـ Kovid مباشرة (عنوان بريده الإلكتروني موجود في كل مكان في الكود المصدري).

en: Windows development environment
ar: بيئة تطوير ويندوز

en: You must also get the calibre source code separately as described above.
ar: يجب عليك أيضًا الحصول على الكود المصدري لـ calibre بشكل منفصل كما هو موضح أعلاه.

en: Install calibre normally, using the `Windows installer <https://calibre-ebook.com/download_windows>`__. Then open a Command Prompt and change to the previously checked out calibre code folder. For example::
ar: قم بتثبيت calibre بشكل طبيعي، باستخدام `مثبت Windows <https://calibre-ebook.com/download_windows>`__. ثم افتح موجه الأوامر وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا. على سبيل المثال::

en: calibre is the folder that contains the src and resources sub-folders.
ar: calibre هو المجلد الذي يحتوي على المجلدين الفرعيين src و resources.

en: The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src folder. So, following the example above, it would be ``C:\Users\kovid\work\calibre\src``. `Here is a short guide <https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_ to setting environment variables on Windows.
ar: الخطوة التالية هي تعيين متغير البيئة ``CALIBRE_DEVELOP_FROM`` إلى المسار المطلق لمجلد src. لذا، باتباع المثال أعلاه، سيكون ``C:\Users\kovid\work\calibre\src``. `هنا دليل قصير <https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_ لتعيين متغيرات البيئة على Windows.

en: Once you have set the environment variable, open a new command prompt and check that it was correctly set by using the command::
ar: بمجرد تعيين متغير البيئة، افتح موجه أوامر جديد وتحقق من أنه تم تعيينه بشكل صحيح باستخدام الأمر::

en: Setting this environment variable means that calibre will now load all its Python code from the specified location.
ar: تعيين متغير البيئة هذا يعني أن calibre سيقوم الآن بتحميل جميع أكواد بايثون الخاصة به من الموقع المحدد.

en: That's it! You are now ready to start hacking on the calibre code. For example, open the file :file:`src\\calibre\\__init__.py` in your favorite editor and add the line::
ar: هذا كل شيء! أنت الآن جاهز للبدء في تعديل كود calibre. على سبيل المثال، افتح الملف :file:`src\\calibre\\__init__.py` في محرر النصوص المفضل لديك وأضف السطر::

en: near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``.
ar: بالقرب من أعلى الملف. الآن قم بتشغيل الأمر :command:`calibredb`. يجب أن يكون السطر الأول من الإخراج هو ``Hello, world!``.

en: You can also setup a calibre development environment inside the free Microsoft Visual Studio, if you like, following the instructions `here <https://www.mobileread.com/forums/showthread.php?t=251201>`_.
ar: يمكنك أيضًا إعداد بيئة تطوير calibre داخل برنامج Microsoft Visual Studio المجاني، إذا أردت، باتباع التعليمات `هنا <https://www.mobileread.com/forums/showthread.php?t=251201>`_.

en: macOS development environment
ar: بيئة تطوير macOS

en: Install calibre normally using the `provided .dmg <https://calibre-ebook.com/download_osx>`__. Then open a Terminal and change to the previously checked out calibre code folder, for example::
ar: قم بتثبيت calibre بشكل طبيعي باستخدام `ملف .dmg الموفر <https://calibre-ebook.com/download_osx>`__. ثم افتح Terminal وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا، على سبيل المثال::

en: calibre is the folder that contains the src and resources sub-folders. The calibre command line tools are found inside the calibre app bundle, in :file:`/Applications/calibre.app/Contents/MacOS` you should add this folder to your PATH environment variable, if you want to run the command line tools easily.
ar: calibre هو المجلد الذي يحتوي على المجلدين الفرعيين src و resources. توجد أدوات سطر أوامر calibre داخل حزمة تطبيق calibre، في :file:`/Applications/calibre.app/Contents/MacOS` يجب عليك إضافة هذا المجلد إلى متغير بيئة PATH الخاص بك، إذا كنت ترغب في تشغيل أدوات سطر الأوامر بسهولة.

en: The next step is to create a bash script that will set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src folder when running calibre in debug mode.
ar: الخطوة التالية هي إنشاء نص برمجي (bash script) يقوم بتعيين متغير البيئة ``CALIBRE_DEVELOP_FROM`` إلى المسار المطلق لمجلد src عند تشغيل calibre في وضع التصحيح.

en: Create a plain text file::
ar: أنشئ ملف نص عادي::

en: Save this file as :file:`/usr/local/bin/calibre-develop`, then set its permissions so that it can be executed::
ar: احفظ هذا الملف باسم :file:`/usr/local/bin/calibre-develop`، ثم اضبط أذوناته بحيث يمكن تنفيذه::

en: Once you have done this, run::
ar: بمجرد الانتهاء من ذلك، قم بتشغيل::

en: You should see some diagnostic information in the Terminal window as calibre starts up, and you should see an asterisk after the version number in the GUI window, indicating that you are running from source.
ar: يجب أن ترى بعض معلومات التشخيص في نافذة Terminal عند بدء تشغيل calibre، ويجب أن ترى نجمة بعد رقم الإصدار في نافذة واجهة المستخدم الرسومية، مما يشير إلى أنك تقوم بالتشغيل من المصدر.

en: Linux development environment
ar: بيئة تطوير Linux

en: calibre is primarily developed on Linux. You have two choices in setting up the development environment. You can install the calibre binary as normal and use that as a runtime environment to do your development. This approach is similar to that used in Windows and macOS. Alternatively, you can install calibre from source. Instructions for setting up a development environment from source are in the INSTALL file in the source tree. Here we will address using the binary as a runtime, which is the recommended method.
ar: يتم تطوير calibre بشكل أساسي على نظام Linux. لديك خياران في إعداد بيئة التطوير. يمكنك تثبيت ثنائي calibre كالمعتاد واستخدامه كبيئة تشغيل للقيام بتطويرك. هذا النهج مشابه لما هو مستخدم في Windows و macOS. بدلاً من ذلك، يمكنك تثبيت calibre من المصدر. توجد تعليمات إعداد بيئة التطوير من المصدر في ملف INSTALL في شجرة المصدر. هنا سنتناول استخدام الثنائي كبيئة تشغيل، وهي الطريقة الموصى بها.

en: Install calibre using the `binary installer <https://calibre-ebook.com/download_linux>`_. Then open a terminal and change to the previously checked out calibre code folder, for example::
ar: قم بتثبيت calibre باستخدام `المثبت الثنائي <https://calibre-ebook.com/download_linux>`_. ثم افتح طرفية وانتقل إلى مجلد كود calibre الذي تم سحبه مسبقًا، على سبيل المثال::

en: The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src folder. So, following the example above, it would be ``/home/kovid/work/calibre/src``. How to set environment variables depends on your Linux distribution and what shell you are using.
ar: الخطوة التالية هي تعيين متغير البيئة ``CALIBRE_DEVELOP_FROM`` إلى المسار المطلق لمجلد src. لذا، باتباع المثال أعلاه، سيكون ``/home/kovid/work/calibre/src``. تعتمد كيفية تعيين متغيرات البيئة على توزيعة Linux التي تستخدمها وأي shell تستخدمه.

en: 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.
ar: يوصى باستخدام المثبت الثنائي المقدم من المصدر. إذا أصررت على استخدام حزمة مقدمة من توزيعتك، فاستخدم متغيري ``CALIBRE_PYTHON_PATH`` و ``CALIBRE_RESOURCES_PATH`` بدلاً من ذلك.

en: Once you have set the environment variable, open a new terminal and check that it was correctly set by using the command::
ar: بمجرد تعيين متغير البيئة، افتح طرفية جديدة وتحقق من أنه تم تعيينه بشكل صحيح باستخدام الأمر::

en: That's it! You are now ready to start hacking on the calibre code. For example, open the file :file:`src/calibre/__init__.py` in your favorite editor and add the line::
ar: هذا كل شيء! أنت الآن جاهز للبدء في تعديل كود calibre. على سبيل المثال، افتح الملف :file:`src/calibre/__init__.py` في محرر النصوص المفضل لديك وأضف السطر::

en: Having separate "normal" and "development" calibre installs on the same computer
ar: امتلاك تثبيتات calibre "عادية" و "تطوير" منفصلة على نفس الكمبيوتر

en: The calibre source tree is very stable and rarely breaks, but if you feel the need to run from source on a separate test library and run the released calibre version with your everyday library, you can achieve this easily using .bat files or shell scripts to launch calibre. The example below shows how to do this on Windows using .bat files (the instructions for other platforms are the same, just use a shell script instead of a .bat file)
ar: شجرة مصادر calibre مستقرة جدًا ونادرًا ما تتعطل، ولكن إذا شعرت بالحاجة إلى التشغيل من المصدر على مكتبة اختبار منفصلة وتشغيل إصدار calibre الذي تم إصداره مع مكتبتك اليومية، يمكنك تحقيق ذلك بسهولة باستخدام ملفات .bat أو نصوص shell لتشغيل calibre. يوضح المثال أدناه كيفية القيام بذلك على نظام Windows باستخدام ملفات .bat (التعليمات للمنصات الأخرى هي نفسها، فقط استخدم نص shell بدلاً من ملف .bat)

en: To launch the release version of calibre with your everyday library:
ar: لتشغيل إصدار calibre الرسمي مع مكتبتك اليومية:

en: Debugging tips
ar: نصائح التصحيح

en: Python is a dynamically typed language with excellent facilities for introspection. Kovid wrote the core calibre code without once using a debugger. There are many strategies to debug calibre code:
ar: بايثون هي لغة ذات كتابة ديناميكية مع إمكانيات ممتازة لـ الاستبطان. كتب كوفيد الكود الأساسي لـ calibre دون استخدام مصحح أخطاء مرة واحدة. هناك العديد من الاستراتيجيات لتصحيح أخطاء كود calibre:

en: Using print statements
ar: استخدام عبارات الطباعة

en: This is Kovid's favorite way to debug. Simply insert print statements at points of interest and run your program in the terminal. For example, you can start the GUI from the terminal as::
ar: هذه هي الطريقة المفضلة لكوفيد للتصحيح. ببساطة أدخل عبارات الطباعة في النقاط المهمة وقم بتشغيل برنامجك في الطرفية. على سبيل المثال، يمكنك بدء الواجهة الرسومية من الطرفية كالتالي::

en: Similarly, you can start the E-book viewer as::
ar: وبالمثل، يمكنك بدء عارض الكتب الإلكترونية كالتالي::

en: The e-book editor can be started as::
ar: يمكن بدء محرر الكتب الإلكترونية كالتالي::

en: Using an interactive Python interpreter
ar: استخدام مترجم بايثون تفاعلي

en: You can insert the following two lines of code to start an interactive Python session at that point::
ar: يمكنك إدراج السطرين التاليين من الكود لبدء جلسة بايثون تفاعلية عند تلك النقطة::

en: When running from the command line, this will start an interactive Python interpreter with access to all locally defined variables (variables in the local scope). The interactive prompt even has :kbd:`Tab` completion for object properties and you can use the various Python facilities for introspection, such as :func:`dir`, :func:`type`, :func:`repr`, etc.
ar: عند التشغيل من سطر الأوامر، سيؤدي هذا إلى بدء مترجم بايثون تفاعلي مع إمكانية الوصول إلى جميع المتغيرات المعرفة محليًا (المتغيرات في النطاق المحلي). حتى موجه الأوامر التفاعلي لديه إكمال :kbd:`Tab` لخصائص الكائن ويمكنك استخدام مرافق بايثون المختلفة للاستبطان، مثل :func:`dir`، :func:`type`، :func:`repr`، إلخ.

en: Using the Python debugger as a remote debugger
ar: استخدام مصحح أخطاء بايثون كمصحح أخطاء عن بعد

en: You can use the builtin Python debugger (pdb) as a remote debugger from the command line. First, start the remote debugger at the point in the calibre code you are interested in, like this::
ar: يمكنك استخدام مصحح أخطاء بايثون المدمج (pdb) كمصحح أخطاء عن بعد من سطر الأوامر. أولاً، ابدأ مصحح الأخطاء عن بعد عند النقطة في كود calibre التي تهتم بها، هكذا::

en: Then run calibre, either as normal, or using one of the calibre-debug commands described in the previous section. Once the above point in the code is reached, calibre will freeze, waiting for the debugger to connect.
ar: ثم قم بتشغيل calibre، إما بشكل طبيعي، أو باستخدام أحد أوامر calibre-debug الموضحة في القسم السابق. بمجرد الوصول إلى النقطة المذكورة أعلاه في الكود، سيتوقف calibre، في انتظار اتصال المصحح.

en: Now open a terminal or command prompt and use the following command to start the debugging session::
ar: الآن افتح طرفية أو موجه أوامر واستخدم الأمر التالي لبدء جلسة التصحيح::

en: You can read about how to use the Python debugger in the `Python stdlib docs for the pdb module <https://docs.python.org/library/pdb.html#debugger-commands>`_.
ar: يمكنك قراءة كيفية استخدام مصحح أخطاء بايثون في `وثائق مكتبة بايثون القياسية لوحدة pdb <https://docs.python.org/library/pdb.html#debugger-commands>`_.

en: By default, the remote debugger will try to connect on port 4444. You can change it, by passing the port parameter to both the set_trace() and the cli() functions above, like this: ``set_trace(port=1234)`` and ``cli(port=1234)``.
ar: افتراضيًا، سيحاول مصحح الأخطاء عن بعد الاتصال على المنفذ 4444. يمكنك تغييره، عن طريق تمرير معلمة المنفذ إلى كل من دالتي set_trace() و cli() أعلاه، كالتالي: ``set_trace(port=1234)`` و ``cli(port=1234)``.

en: The Python debugger cannot handle multiple threads, so you have to call set_trace once per thread, each time with a different port number.
ar: لا يستطيع مصحح أخطاء بايثون التعامل مع سلاسل متعددة، لذا يجب عليك استدعاء set_trace مرة واحدة لكل سلسلة، في كل مرة برقم منفذ مختلف.

en: Using the debugger in your favorite Python IDE
ar: استخدام مصحح الأخطاء في بيئة التطوير المتكاملة (IDE) المفضلة لديك في بايثون

en: It is possible to use the builtin debugger in your favorite Python IDE, if it supports remote debugging. The first step is to add the calibre src checkout to the ``PYTHONPATH`` in your IDE. In other words, the folder you set as ``CALIBRE_DEVELOP_FROM`` above, must also be in the ``PYTHONPATH`` of your IDE.
ar: من الممكن استخدام مصحح الأخطاء المدمج في بيئة التطوير المتكاملة (IDE) المفضلة لديك في بايثون، إذا كانت تدعم تصحيح الأخطاء عن بُعد. الخطوة الأولى هي إضافة مجلد src الخاص بـ calibre إلى ``PYTHONPATH`` في بيئة التطوير المتكاملة الخاصة بك. بعبارة أخرى، يجب أن يكون المجلد الذي عينته كـ ``CALIBRE_DEVELOP_FROM`` أعلاه، موجودًا أيضًا في ``PYTHONPATH`` الخاص بـ بيئة التطوير المتكاملة الخاصة بك.

en: Then place the IDE's remote debugger module into the :file:`src` sub-folder of the calibre source code checkout. Add whatever code is needed to launch the remote debugger to calibre at the point of interest, for example in the main function. Then run calibre as normal. Your IDE should now be able to connect to the remote debugger running inside calibre.
ar: ثم ضع وحدة مصحح الأخطاء عن بعد الخاصة بـ IDE في المجلد الفرعي :file:`src` من نسخة الكود المصدري لـ calibre. أضف أي كود مطلوب لتشغيل مصحح الأخطاء عن بعد إلى calibre عند النقطة المهمة، على سبيل المثال في الدالة الرئيسية. ثم قم بتشغيل calibre كالمعتاد. يجب أن تكون بيئة التطوير المتكاملة الخاصة بك الآن قادرة على الاتصال بمصحح الأخطاء عن بعد الذي يعمل داخل calibre.

en: Executing arbitrary scripts in the calibre Python environment
ar: تنفيذ نصوص برمجية عشوائية في بيئة بايثون لـ calibre

en: The :command:`calibre-debug` command provides a couple of handy switches to execute your own code, with access to the calibre modules::
ar: يوفر الأمر :command:`calibre-debug` بعض المفاتيح المفيدة لـ تنفيذ الكود الخاص بك، مع الوصول إلى وحدات calibre::

en: is great for testing a little snippet of code on the command line. It works in the same way as the -c switch to the Python interpreter::
ar: رائع لاختبار مقتطف صغير من الكود في سطر الأوامر. يعمل بنفس طريقة مفتاح -c لمترجم بايثون::

en: can be used to execute your own Python script. It works in the same way as passing the script to the Python interpreter, except that the calibre environment is fully initialized, so you can use all the calibre code in your script. To use command line arguments with your script, use the form::
ar: يمكن استخدامه لتنفيذ نص بايثون الخاص بك. يعمل بنفس الطريقة التي يتم بها تمرير النص إلى مترجم بايثون، باستثناء أن بيئة calibre مُهيأة بالكامل، لذلك يمكنك استخدام جميع أكواد calibre في النص الخاص بك. لاستخدام وسائط سطر الأوامر مع النص الخاص بك، استخدم الشكل::

en: The ``--`` causes all subsequent arguments to be passed to your script.
ar: تتسبب ``--`` في تمرير جميع الوسائط اللاحقة إلى النص البرمجي الخاص بك.

en: Using calibre in your projects
ar: استخدام calibre في مشاريعك

en: It is possible to directly use calibre functions/code in your Python project. Two ways exist to do this:
ar: من الممكن استخدام دوال/أكواد calibre مباشرة في مشروع بايثون الخاص بك. توجد طريقتان للقيام بذلك:

en: Binary install of calibre
ar: تثبيت calibre الثنائي

en: If you have a binary install of calibre, you can use the Python interpreter bundled with calibre, like this::
ar: إذا كان لديك تثبيت ثنائي لـ calibre، يمكنك استخدام مترجم بايثون المضمن مع calibre، كالتالي::

en: Source install on Linux
ar: تثبيت المصدر على Linux

en: In addition to using the above technique, if you do a source install on Linux, you can also directly import calibre, as follows::
ar: بالإضافة إلى استخدام التقنية المذكورة أعلاه، إذا قمت بتثبيت المصدر على Linux، يمكنك أيضًا استيراد calibre مباشرة، كالتالي::

en: It is essential that you import the init_calibre module before any other calibre modules/packages as it sets up the interpreter to run calibre code.
ar: من الضروري أن تقوم باستيراد وحدة init_calibre قبل أي وحدات/حزم calibre أخرى لأنها تهيئ المترجم لتشغيل كود calibre.

en: API documentation for various parts of calibre
ar: توثيق API لأجزاء مختلفة من calibre
