توثيق API للإضافات¶

يعرّف فئات أساسية مجردة مختلفة يمكن اشتقاقها لإنشاء إضافات قوية. الفئات المفيدة هي:

إضافة ¶

class calibre.customize.Plugin(plugin_path)[المصدر]¶

إضافة calibre. تتضمن الأعضاء المفيدة:

self.installation_type: يخزن كيفية تثبيت الإضافة.

self.plugin_path: يخزن مسار ملف ZIP الذي يحتوي على
هذه الإضافة أو لا شيء إذا كانت إضافة مدمجة

self.site_customization: يخزن سلسلة تخصيص تم إدخالها
من قبل المستخدم.

الأساليب التي يجب تجاوزها في الفئات الفرعية:

تهيئة()

مساعدة_التخصيص()

أساليب مفيدة:

ملف_مؤقت()

__دخول__()

تحميل_الموارد()

supported_platforms = []¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

name = 'Trivial Plugin'¶: اسم هذه الإضافة. يجب عليك تعيينه لشيء آخر غير إضافة تافهة لكي يعمل.

version = (1, 0, 0)¶: إصدار هذه الإضافة كـ 3-tuple (رئيسي، فرعي، مراجعة)

description = 'لا يفعل شيئًا إطلاقًا'¶: سلسلة قصيرة تصف ما تفعله هذه الإضافة

author = 'مجهول'¶: مؤلف هذه الإضافة

priority = 1¶: عند وجود أكثر من إضافة لنوع ملف واحد، يتم تشغيل الإضافات بترتيب الأولوية التنازلية. سيتم تشغيل الإضافات ذات الأولوية الأعلى أولاً. أعلى أولوية ممكنة هي sys.maxsize. الأولوية الافتراضية هي 1.

minimum_calibre_version = (0, 4, 118)¶: أقدم إصدار من calibre تتطلبه هذه الإضافة

installation_type = None¶: طريقة تثبيت هذه الإضافة

can_be_disabled = True¶: إذا كان False، فلن يتمكن المستخدم من تعطيل هذه الإضافة. استخدم بحذر.

type = 'أساس'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

initialize()[المصدر]¶

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

قم بإجراء أي تهيئة خاصة بالإضافة هنا، مثل استخراج الموارد من ملف ZIP الخاص بالإضافة. المسار إلى ملف ZIP متاح كـ self.plugin_path.

لاحظ أن self.site_customization غير متاح في هذه المرحلة.

config_widget()[المصدر]¶

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

يجب أن تعيد هذه الطريقة، إذا تم تنفيذها، QWidget. يمكن أن تحتوي الأداة على طريقة اختيارية validate() لا تأخذ أي وسيطات ويتم استدعاؤها فورًا بعد أن ينقر المستخدم على موافق. يتم تطبيق التغييرات إذا وفقط إذا أعادت الطريقة True.

إذا لم تتمكن لسبب ما من إجراء التكوين في هذا الوقت، أعد زوجًا من سلسلتين (رسالة، تفاصيل)، سيتم عرضهما كـ مربع حوار تحذير للمستخدم وسيتم إحباط العملية.

save_settings(config_widget)[المصدر]¶

احفظ الإعدادات المحددة من قبل المستخدم باستخدام config_widget.

المعلمات:: config_widget -- الأداة التي أعادها config_widget().

do_user_config(parent=None)[المصدر]¶: يعرض هذا الأسلوب مربع حوار تكوين لهذه الإضافة. يعيد True إذا نقر المستخدم على موافق، False بخلاف ذلك. يتم تطبيق التغييرات تلقائيًا.

load_resources(names)[المصدر]¶

إذا كانت هذه الإضافة تأتي في ملف ZIP (إضافة أضافها المستخدم)، فإن هذا الأسلوب سيسمح لك بتحميل الموارد من ملف ZIP.

على سبيل المثال لتحميل صورة:

pixmap = QPixmap()
pixmap.loadFromData(self.load_resources(['images/icon.png'])['images/icon.png'])
icon = QIcon(pixmap)

المعلمات:: names -- قائمة مسارات الموارد في ملف ZIP باستخدام / كفاصل
يعيد:: قاموس بالشكل {الاسم: محتويات_الملف}. أي أسماء لم يتم العثور عليها في ملف ZIP لن تكون موجودة في القاموس.

customization_help(gui=False)[المصدر]¶

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

إذا أعدت تنفيذ هذا الأسلوب في فئتك الفرعية، سيُطلب من المستخدم إدخال سلسلة كتخصيص لهذه الإضافة. ستكون سلسلة التخصيص متاحة كـ self.site_customization.

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

المعلمات:: gui -- إذا كان True، أعد مساعدة HTML، وإلا أعد مساعدة نص عادي.

temporary_file(suffix)[المصدر]¶

إعادة كائن شبيه بالملف وهو ملف مؤقت على نظام الملفات. هذا الملف سيبقى متاحًا حتى بعد إغلاقه ولن يتم إزالته إلا عند إغلاق المفسر. استخدم عضو name في الكائن المعاد لـ الوصول إلى المسار الكامل للملف المؤقت الذي تم إنشاؤه.

المعلمات:: suffix -- اللاحقة التي سيحتوي عليها الملف المؤقت.

cli_main(args)[المصدر]¶: هذا الأسلوب هو نقطة الدخول الرئيسية لواجهة سطر الأوامر لإضافاتك. يتم استدعاؤه عندما يقوم المستخدم بـ: calibre-debug -r "اسم الإضافة". أي وسيطات تم تمريرها موجودة في متغير args.

إضافة نوع الملف ¶

class calibre.customize.FileTypePlugin(plugin_path)[المصدر]¶

الأساس: Plugin

إضافة مرتبطة بمجموعة معينة من أنواع الملفات.

file_types = {}¶: مجموعة من أنواع الملفات التي يجب تشغيل هذه الإضافة من أجلها. استخدم '*' لجميع أنواع الملفات. على سبيل المثال: {'lit', 'mobi', 'prc'}

on_import = False¶: إذا كان True، يتم تشغيل هذه الإضافة عند إضافة الكتب إلى قاعدة البيانات

on_postimport = False¶: إذا كان True، يتم تشغيل هذه الإضافة بعد إضافة الكتب إلى قاعدة البيانات. في هذه الحالة، يتم استدعاء أساليب postimport و postadd الخاصة بالإضافة.

on_postconvert = False¶: إذا كان True، يتم تشغيل هذه الإضافة بعد تحويل الكتاب. في هذه الحالة، يتم استدعاء أسلوب postconvert الخاص بالإضافة.

on_postdelete = False¶: إذا كان True، يتم تشغيل هذه الإضافة بعد حذف ملف كتاب من قاعدة البيانات. في هذه الحالة، يتم استدعاء أسلوب postdelete الخاص بالإضافة.

on_preprocess = False¶: إذا كان True، يتم تشغيل هذه الإضافة قبل التحويل مباشرة

on_postprocess = False¶: إذا كان True، يتم تشغيل هذه الإضافة بعد التحويل على الملف النهائي الذي تنتجه إضافة إخراج التحويل.

type = 'نوع الملف'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

run(path_to_ebook)[المصدر]¶

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

يجب إنشاء ملف الكتاب الإلكتروني المعدل باستخدام الأسلوب temporary_file().

المعلمات:: path_to_ebook -- المسار المطلق للكتاب الإلكتروني.
يعيد:: المسار المطلق للكتاب الإلكتروني المعدل.

postimport(book_id, book_format, db)[المصدر]¶

يتم استدعاؤها بعد الاستيراد، أي بعد إضافة ملف الكتاب إلى قاعدة البيانات. لاحظ أن هذا يختلف عن postadd() الذي يتم استدعاؤه عند إنشاء سجل الكتاب لأول مرة. يتم استدعاء هذا الأسلوب كلما تمت إضافة ملف جديد إلى سجل كتاب. وهو مفيد لتعديل سجل الكتاب بناءً على محتويات الملف المضاف حديثًا.

المعلمات:

book_id -- معرف قاعدة البيانات للكتاب المضاف.
book_format -- نوع ملف الكتاب الذي تم إضافته.
db -- قاعدة بيانات المكتبة.

postconvert(book_id, book_format, db)[المصدر]¶

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

المعلمات:

book_id -- معرف قاعدة البيانات للكتاب المضاف.
book_format -- نوع ملف الكتاب الذي تم إضافته.
db -- قاعدة بيانات المكتبة.

postdelete(book_id, book_format, db)[المصدر]¶

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

المعلمات:

book_id -- معرف قاعدة البيانات للكتاب المضاف.
book_format -- نوع ملف الكتاب الذي تم إضافته.
db -- قاعدة بيانات المكتبة.

postadd(book_id, fmt_map, db)[المصدر]¶

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

المعلمات:

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

إضافات البيانات الوصفية ¶

class calibre.customize.MetadataReaderPlugin(*args, **kwargs)[المصدر]¶

الأساس: Plugin

إضافة تقوم بتنفيذ قراءة البيانات الوصفية من مجموعة من أنواع الملفات.

file_types = {}¶: مجموعة من أنواع الملفات التي يجب تشغيل هذه الإضافة من أجلها. على سبيل المثال: set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

version = (8, 7, 0)¶: إصدار هذه الإضافة كـ 3-tuple (رئيسي، فرعي، مراجعة)

author = 'Kovid Goyal'¶: مؤلف هذه الإضافة

type = 'قارئ البيانات الوصفية'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

get_metadata(stream, type)[المصدر]¶

إرجاع البيانات الوصفية للملف الممثل بواسطة التدفق (كائن شبيه بالملف يدعم القراءة). اطرح استثناءً عند وجود خطأ في بيانات الإدخال.

المعلمات:: type -- نوع الملف. مضمون أن يكون أحد الإدخالات في file_types.
يعيد:: كائن calibre.ebooks.metadata.book.Metadata

class calibre.customize.MetadataWriterPlugin(*args, **kwargs)[المصدر]¶

الأساس: Plugin

إضافة تقوم بتنفيذ قراءة البيانات الوصفية من مجموعة من أنواع الملفات.

file_types = {}¶: مجموعة من أنواع الملفات التي يجب تشغيل هذه الإضافة من أجلها. على سبيل المثال: set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

version = (8, 7, 0)¶: إصدار هذه الإضافة كـ 3-tuple (رئيسي، فرعي، مراجعة)

author = 'Kovid Goyal'¶: مؤلف هذه الإضافة

type = 'كاتب البيانات الوصفية'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

set_metadata(stream, mi, type)[المصدر]¶

تعيين البيانات الوصفية للملف الممثل بواسطة التدفق (كائن شبيه بالملف يدعم القراءة). اطرح استثناءً عند وجود خطأ في بيانات الإدخال.

المعلمات:

type -- نوع الملف. مضمون أن يكون أحد الإدخالات في file_types.
mi -- كائن calibre.ebooks.metadata.book.Metadata

إضافات الفهرس ¶

class calibre.customize.CatalogPlugin(plugin_path)[المصدر]¶

الأساس: Plugin

إضافة تقوم بتنفيذ مولد فهرس.

file_types = {}¶: نوع ملف الإخراج الذي يجب تشغيل هذه الإضافة من أجله. على سبيل المثال: 'epub' أو 'xml'

type = 'مولّد المَسرَد'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

cli_options = []¶

خيارات تحليل CLI خاصة بهذه الإضافة، معلنة كـ namedtuple Option:

من collections استورد namedtuple Option = namedtuple('Option', 'option, default, dest, help') cli_options = [Option('--catalog-title', default = 'My Catalog', dest = 'catalog_title', help = (_('عنوان الفهرس الذي تم إنشاؤه. nالافتراضي:') + " '" + '%default' + "'"))] cli_options تم تحليلها في calibre.db.cli.cmd_catalog:option_parser()

initialize()[المصدر]¶: إذا لم تكن الإضافة مدمجة، فانسخ ملفات .ui و .py الخاصة بالإضافة من ملف ZIP إلى $TMPDIR. سيتم إنشاء علامة التبويب ديناميكيًا وإضافتها إلى مربع حوار خيارات الفهرس في calibre.gui2.dialogs.catalog.py:Catalog

run(path_to_output, opts, db, ids, notification=None)[المصدر]¶

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

يجب إنشاء ملف الفهرس الذي تم إنشاؤه باستخدام الأسلوب temporary_file().

المعلمات:

path_to_output -- المسار المطلق لملف الفهرس الذي تم إنشاؤه.
opts -- قاموس من الوسائط الكلمة
db -- كائن LibraryDatabase2

إضافات تنزيل البيانات الوصفية ¶

class calibre.ebooks.metadata.sources.base.Source(*args, **kwargs)[المصدر]¶

الأساس: Plugin

type = 'مصدر البيانات الوصفية'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

author = 'Kovid Goyal'¶: مؤلف هذه الإضافة

supported_platforms = ['windows', 'osx', 'linux']¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

capabilities = frozenset({})¶: مجموعة من القدرات التي تدعمها هذه الإضافة. القدرات المفيدة هي: 'تحديد الهوية'، 'غلاف'

touched_fields = frozenset({})¶: قائمة حقول البيانات الوصفية التي يمكن تنزيلها بواسطة هذه الإضافة خلال مرحلة التحديد

has_html_comments = False¶: عيّن هذا إلى True إذا كانت إضافتك تعيد تعليقات منسقة بـ HTML

supports_gzip_transfer_encoding = False¶: تعيين هذا إلى True يعني أن كائن المتصفح سيشير إلى أنه يدعم ترميز نقل gzip. يمكن أن يسرع هذا التنزيلات ولكن تأكد من أن المصدر يدعم بالفعل ترميز نقل gzip بشكل صحيح أولاً

ignore_ssl_errors = False¶: عيّن هذا إلى True لتجاهل أخطاء شهادة HTTPS عند الاتصال بهذا المصدر.

cached_cover_url_is_reliable = True¶: قد تكون عناوين URL للأغلفة المخزنة مؤقتًا غير موثوقة أحيانًا (أي قد يفشل التنزيل أو قد تكون الصورة المعادة مزيفة). إذا كان هذا هو الحال غالبًا مع هذا المصدر، فعيّن إلى False

options = ()¶: قائمة بكائنات Option. سيتم استخدامها لـ إنشاء أداة التكوين لهذه الإضافة تلقائيًا

config_help_message = None¶: سلسلة يتم عرضها في الجزء العلوي من أداة التكوين لهذه الإضافة

can_get_multiple_covers = False¶: إذا كان True، يمكن لهذا المصدر إرجاع أغلفة متعددة لاستعلام معين

auto_trim_covers = False¶: إذا تم تعيينه على True، يتم قص الأغلفة التي تم تنزيلها بواسطة هذه الإضافة تلقائيًا.

prefer_results_with_isbn = True¶: إذا تم تعيينه على True، وكان هذا المصدر يعيد نتائج متعددة لاستعلام، بعضها يحتوي على أرقام ISBN وبعضها لا يحتوي، فسيتم تجاهل النتائج التي لا تحتوي على أرقام ISBN

is_configured()[المصدر]¶: أعد False إذا كانت إضافتك تحتاج إلى تكوين قبل استخدامها. على سبيل المثال، قد تحتاج إلى اسم مستخدم/كلمة مرور/مفتاح API.

customization_help()[المصدر]¶

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

إذا أعدت تنفيذ هذا الأسلوب في فئتك الفرعية، سيُطلب من المستخدم إدخال سلسلة كتخصيص لهذه الإضافة. ستكون سلسلة التخصيص متاحة كـ self.site_customization.

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

المعلمات:: gui -- إذا كان True، أعد مساعدة HTML، وإلا أعد مساعدة نص عادي.

config_widget()[المصدر]¶

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

يجب أن تعيد هذه الطريقة، إذا تم تنفيذها، QWidget. يمكن أن تحتوي الأداة على طريقة اختيارية validate() لا تأخذ أي وسيطات ويتم استدعاؤها فورًا بعد أن ينقر المستخدم على موافق. يتم تطبيق التغييرات إذا وفقط إذا أعادت الطريقة True.

إذا لم تتمكن لسبب ما من إجراء التكوين في هذا الوقت، أعد زوجًا من سلسلتين (رسالة، تفاصيل)، سيتم عرضهما كـ مربع حوار تحذير للمستخدم وسيتم إحباط العملية.

save_settings(config_widget)[المصدر]¶

احفظ الإعدادات المحددة من قبل المستخدم باستخدام config_widget.

المعلمات:: config_widget -- الأداة التي أعادها config_widget().

get_author_tokens(authors, only_first_author=True)[المصدر]¶: خذ قائمة من المؤلفين وأعد قائمة من الرموز مفيدة لاستعلام بحث AND. تحاول هذه الدالة إرجاع الرموز بترتيب الاسم الأول والأسماء الوسطى والاسم الأخير، بافتراض أنه إذا كانت هناك فاصلة في اسم المؤلف، فإن الاسم يكون بتنسيق الاسم الأخير، أسماء أخرى.

get_title_tokens(title, strip_joiners=True, strip_subtitle=False)[المصدر]¶: خذ عنوانًا وأعد قائمة من الرموز مفيدة لاستعلام بحث AND. يستثني الروابط (اختياريًا) وعلامات الترقيم.

split_jobs(jobs, num)[المصدر]¶: قسّم قائمة المهام إلى num مجموعات كحد أقصى، بأكبر قدر ممكن من التساوي

test_fields(mi)[المصدر]¶: أعد الحقل الأول من self.touched_fields الذي يكون فارغًا في الكائن mi

clean_downloaded_metadata(mi)[المصدر]¶: استدعِ هذا الأسلوب في أسلوب تحديد الهوية الخاص بإضافتك لتوحيد البيانات الوصفية قبل وضع كائن Metadata في result_queue. يمكنك بالطبع استخدام خوارزمية مخصصة تناسب مصدر البيانات الوصفية الخاص بك.

get_book_url(identifiers)[المصدر]¶: أعد 3-tuple أو None. 3-tuple يكون بالشكل: (نوع_المعرف، قيمة_المعرف، URL). عنوان URL هو عنوان URL للكتاب المحدد بواسطة المعرفات في هذا المصدر. يحدد identifier_type، identifier_value المعرف المقابل لعنوان URL. يجب أن يكون عنوان URL هذا قابلاً للتصفح بواسطة إنسان باستخدام متصفح. ويهدف إلى توفير رابط قابل للنقر للمستخدم لزيارة صفحة الكتب بسهولة في هذا المصدر. إذا لم يتم العثور على عنوان URL، أعد None. يجب أن يكون هذا الأسلوب سريعًا ومتسقًا، لذا قم بتنفيذه فقط إذا كان من الممكن إنشاء عنوان URL من مخطط معروف بالنظر إلى المعرفات.

get_book_url_name(idtype, idval, url)[المصدر]¶: إرجاع اسم مقروء بشريًا من القيمة المعادة من get_book_url().

get_book_urls(identifiers)[المصدر]¶: تجاوز هذا الأسلوب إذا كنت ترغب في إرجاع عناوين URL متعددة لهذا الكتاب. أعد قائمة من 3-tuples. افتراضيًا، يستدعي هذا الأسلوب ببساطة get_book_url().

get_cached_cover_url(identifiers)[المصدر]¶

إرجاع عنوان URL للغلاف المخزن مؤقتًا للكتاب المحدد بواسطة قاموس المعرفات أو None إذا لم يكن هناك عنوان URL من هذا القبيل.

لاحظ أن هذا الأسلوب يجب أن يعيد فقط عناوين URL صالحة، أي ليس عناوين URL التي قد تؤدي إلى صورة غلاف عامة أو خطأ عدم العثور.

id_from_url(url)[المصدر]¶: قم بتحليل عنوان URL وأعد tuple بالشكل: (نوع_المعرف، قيمة_المعرف). إذا لم يتطابق عنوان URL مع نمط مصدر البيانات الوصفية، فأعد None.

identify_results_keygen(title=None, authors=None, identifiers={})[المصدر]¶

أعد دالة تستخدم لإنشاء مفتاح يمكنه فرز كائنات البيانات الوصفية حسب مدى صلتها باستعلام بحث (عنوان، مؤلفون، معرفات).

تستخدم هذه المفاتيح لفرز نتائج استدعاء identify().

للحصول على تفاصيل حول الخوارزمية الافتراضية، راجع InternalMetadataCompareKeyGen. أعد تنفيذ هذه الدالة في إضافتك إذا كانت الخوارزمية الافتراضية غير مناسبة.

identify(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30)[المصدر]¶

تحديد كتاب بواسطة عنوانه/مؤلفه/رقم ISBN/إلخ.

إذا تم تحديد معرفات (معرف) ولم يتم العثور على تطابق ولم يخزن مصدر البيانات الوصفية هذا جميع المعرفات ذات الصلة (على سبيل المثال، جميع أرقام ISBN لكتاب)، يجب أن يعيد هذا الأسلوب المحاولة باستخدام العنوان والمؤلف فقط (بافتراض أنهما تم تحديدهما).

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

يجب أن يحتوي كل كائن Metadata يتم وضعه في result_queue بواسطة هذا الأسلوب على سمة source_relevance وهي عدد صحيح يشير إلى الترتيب الذي أعادت به النتائج من مصدر البيانات الوصفية لهذا الاستعلام. هذا العدد الصحيح سيتم استخدامه بواسطة compare_identify_results(). إذا كان الترتيب غير مهم، فعيّنه إلى صفر لكل نتيجة.

تأكد من تخزين أي معلومات تعيين غلاف/ISBN مؤقتًا قبل وضع كائن Metadata في result_queue.

المعلمات:

log -- كائن سجل، استخدمه لإخراج معلومات/أخطاء التصحيح
result_queue -- قائمة انتظار النتائج، يجب وضع النتائج فيها. كل نتيجة هي كائن بيانات وصفية
abort -- إذا أعادت abort.is_set() قيمة True، قم بإلغاء المزيد من المعالجة وعد في أقرب وقت ممكن
title -- عنوان الكتاب، يمكن أن يكون None
authors -- قائمة بمؤلفي الكتاب، يمكن أن تكون None
identifiers -- قاموس لمعرفات أخرى، الأكثر شيوعًا {'isbn':'1234...'}
timeout -- المهلة بالثواني، يجب ألا تتوقف أي طلب شبكة لأكثر من المهلة المحددة.

يعيد:

None إذا لم تحدث أخطاء، وإلا تمثيل يونيكود للخطأ مناسب للعرض للمستخدم

download_cover(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30, get_best_cover=False)[المصدر]¶

قم بتنزيل غلاف وضعه في result_queue. جميع المعلمات لها نفس المعنى كما هو الحال في identify(). ضع (self, cover_data) في result_queue.

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

إذا كانت المعلمة get_best_cover هي True ويمكن لهذه الإضافة الحصول على أغلفة متعددة، فيجب أن تحصل على الأفضل فقط.

class calibre.ebooks.metadata.sources.base.InternalMetadataCompareKeyGen(mi, source_plugin, title, authors, identifiers)[المصدر]¶

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

يضمن مفتاح الفرز أن الفرز بترتيب تصاعدي هو فرز بترتيب الأهمية المتناقصة.

الخوارزمية هي:

تفضيل النتائج التي تحتوي على معرف واحد على الأقل مطابق للاستعلام

تفضيل النتائج ذات عنوان URL للغلاف المخزن مؤقتًا

تفضيل النتائج التي تم ملء جميع الحقول المتاحة فيها

تفضيل النتائج بنفس لغة واجهة المستخدم الحالية

تفضيل النتائج التي تطابق العنوان تمامًا للاستعلام

تفضيل النتائج ذات التعليقات الأطول (أطول بأكثر من 10%)

استخدم مدى صلة النتيجة كما أفاد بها بحث مصدر البيانات الوصفية
المحرك

إضافات التحويل ¶

class calibre.customize.conversion.InputFormatPlugin(*args)[المصدر]¶

الأساس: Plugin

إضافات InputFormatPlugins مسؤولة عن تحويل مستند إلى HTML+OPF+CSS+إلخ. يجب أن تكون نتائج التحويل مُشفرة بـ UTF-8. يحدث الإجراء الرئيسي في convert().

type = 'إدخال التحويل'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

can_be_disabled = False¶: إذا كان False، فلن يتمكن المستخدم من تعطيل هذه الإضافة. استخدم بحذر.

supported_platforms = ['windows', 'osx', 'linux']¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

file_types = {}¶: مجموعة من أنواع الملفات التي يجب تشغيل هذه الإضافة من أجلها. على سبيل المثال: set(['azw', 'mobi', 'prc'])

is_image_collection = False¶: إذا كان True، فإن هذه الإضافة المدخلة تولد مجموعة من الصور، واحدة لكل ملف HTML. يمكن تعيين هذا ديناميكيًا، في أسلوب التحويل إذا كانت ملفات الإدخال يمكن أن تكون مجموعات صور ومجموعات غير صور. إذا قمت بتعيين هذا إلى True، يجب عليك تنفيذ أسلوب get_images() الذي يعيد قائمة من الصور.

core_usage = 1¶: عدد نوى وحدة المعالجة المركزية التي تستخدمها هذه الإضافة. قيمة -1 تعني أنها تستخدم جميع النوى المتاحة

for_viewer = False¶: إذا تم تعيينه على True، ستقوم إضافة الإدخال بإجراء معالجة خاصة لجعل إخراجها مناسبًا للعرض

output_encoding = 'utf-8'¶: الترميز الذي تنشئ به هذه الإضافة المدخلة الملفات. قيمة None تعني أن الترميز غير محدد ويجب اكتشافه بشكل فردي

common_options = {<calibre.customize.conversion.OptionRecommendation object>}¶: خيارات مشتركة بين جميع إضافات تنسيق الإدخال. لا تتجاوز في الفئات الفرعية. استخدم options بدلاً من ذلك. يجب أن يكون كل خيار نسخة من OptionRecommendation.

options = {}¶: خيارات لتخصيص سلوك هذه الإضافة. يجب أن يكون كل خيار نسخة من OptionRecommendation.

recommendations = {}¶: مجموعة من 3-tuples بالشكل (اسم_الخيار، القيمة_الموصى بها، مستوى_التوصية)

get_images()[المصدر]¶: أعد قائمة بالمسارات المطلقة للصور، إذا كانت هذه الإضافة المدخلة تمثل مجموعة صور. قائمة الصور بنفس ترتيب العمود الفقري وجدول المحتويات.

convert(stream, options, file_ext, log, accelerators)[المصدر]¶

يجب تنفيذ هذا الأسلوب في الفئات الفرعية. يجب أن يعيد المسار إلى ملف OPF الذي تم إنشاؤه أو مثيل OEBBook. يجب أن يكون كل الإخراج محتوى في المجلد الحالي. إذا أنشأت هذه الإضافة ملفات خارج المجلد الحالي، فيجب حذفها/وضع علامة عليها للحذف قبل أن يعيد هذا الأسلوب.

المعلمات:

stream -- كائن شبيه بالملف يحتوي على ملف الإدخال.
options -- خيارات لتخصيص عملية التحويل. مضمون أن تحتوي على سمات تتوافق مع جميع الخيارات المعلنة بواسطة هذه الإضافة. بالإضافة إلى ذلك، ستحتوي على سمة verbose تأخذ قيمًا صحيحة من الصفر فصاعدًا. الأرقام الأعلى تعني أن تكون أكثر تفصيلاً. سمة أخرى مفيدة هي input_profile وهي نسخة من calibre.customize.profiles.InputProfile.
file_ext -- الامتداد (بدون النقطة) لملف الإدخال. مضمون أن يكون أحد أنواع الملفات المدعومة بواسطة هذه الإضافة.
log -- كائن calibre.utils.logging.Log. يجب أن يستخدم هذا الكائن جميع المخرجات.
accelerators -- قاموس يحتوي على معلومات مختلفة يمكن لإضافة الإدخال الحصول عليها بسهولة والتي ستسرع المراحل اللاحقة من التحويل.

postprocess_book(oeb, opts, log)[المصدر]¶: يتم استدعاؤها للسماح لإضافة الإدخال بإجراء معالجة لاحقة بعد تحليل الكتاب.

specialize(oeb, opts, log, output_fmt)[المصدر]¶: يتم استدعاؤها للسماح لإضافة الإدخال بتخصيص الكتاب المحلل لـ تنسيق إخراج معين. يتم استدعاؤها بعد postprocess_book وقبل إجراء أي تحويلات على الكتاب المحلل.

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[المصدر]¶: يتم استدعاؤها لإنشاء الأداة المستخدمة لتكوين هذه الإضافة في واجهة المستخدم الرسومية لـ calibre. يجب أن تكون الأداة نسخة من فئة PluginWidget. راجع إضافات الإدخال المدمجة للحصول على أمثلة.

class calibre.customize.conversion.OutputFormatPlugin(*args)[المصدر]¶

الأساس: Plugin

إضافات OutputFormatPlugins مسؤولة عن تحويل مستند OEB (OPF+HTML) إلى كتاب إلكتروني إخراج.

يمكن افتراض أن مستند OEB مشفر بـ UTF-8. الإجراء الرئيسي يحدث في convert().

type = 'إخراج التحويل'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

can_be_disabled = False¶: إذا كان False، فلن يتمكن المستخدم من تعطيل هذه الإضافة. استخدم بحذر.

supported_platforms = ['windows', 'osx', 'linux']¶: قائمة بالأنظمة الأساسية التي تعمل عليها هذه الإضافة. على سبيل المثال: ['windows', 'osx', 'linux']

file_type = None¶: نوع الملف (الامتداد بدون نقطة بادئة) الذي تنتجه هذه الإضافة

common_options = {<calibre.customize.conversion.OptionRecommendation object>}¶: خيارات مشتركة بين جميع إضافات تنسيق الإدخال. لا تتجاوز في الفئات الفرعية. استخدم options بدلاً من ذلك. يجب أن يكون كل خيار نسخة من OptionRecommendation.

options = {}¶: خيارات لتخصيص سلوك هذه الإضافة. يجب أن يكون كل خيار نسخة من OptionRecommendation.

recommendations = {}¶: مجموعة من 3-tuples بالشكل (اسم_الخيار، القيمة_الموصى بها، مستوى_التوصية)

property description¶

str(كائن='') -> str str(بايت_أو_مخزن[, ترميز[, أخطاء]]) -> str

إنشاء كائن سلسلة جديد من الكائن المحدد. إذا تم تحديد الترميز أو الأخطاء، فيجب أن يكشف الكائن عن مخزن بيانات سيتم فك ترميزه باستخدام الترميز ومعالج الأخطاء المحددين. وإلا، فإنه يعيد نتيجة object.__str__() (إذا تم تعريفه) أو repr(object). الترميز الافتراضي هو 'utf-8'. الأخطاء الافتراضية هي 'strict'.

convert(oeb_book, output, input_plugin, opts, log)[المصدر]¶

عرض محتويات oeb_book (وهو نسخة من calibre.ebooks.oeb.OEBBook) إلى الملف المحدد بواسطة الإخراج.

المعلمات:

output -- إما كائن شبيه بالملف أو سلسلة. إذا كانت سلسلة، فهي مسار إلى مجلد قد يوجد أو لا يوجد. يجب أن تكتب إضافة الإخراج إخراجها في ذلك المجلد. إذا كان كائنًا شبيهًا بالملف، يجب أن تكتب إضافة الإخراج إخراجها في الملف.
input_plugin -- إضافة الإدخال التي تم استخدامها في بداية مسار التحويل.
opts -- خيارات التحويل. مضمون أن تحتوي على سمات تتوافق مع OptionRecommendations لهذه الإضافة.
log -- المسجل. اطبع رسائل التصحيح/المعلومات وما إلى ذلك باستخدام هذا.

specialize_options(log, opts, input_fmt)[المصدر]¶: يمكن استخدامها لتغيير قيم خيارات التحويل، كما تستخدمها مسار التحويل.

specialize_css_for_output(log, opts, item, stylizer)[المصدر]¶

يمكن استخدامها لإجراء تغييرات على CSS أثناء عملية تسطيح CSS.

المعلمات:

item -- العنصر (ملف HTML) الذي تتم معالجته
stylizer -- كائن Stylizer يحتوي على الأنماط المسطحة للعنصر. يمكنك الحصول على نمط أي عنصر عن طريق stylizer.style(element).

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[المصدر]¶: يتم استدعاؤها لإنشاء الأداة المستخدمة لتكوين هذه الإضافة في واجهة المستخدم الرسومية لـ calibre. يجب أن تكون الأداة نسخة من فئة PluginWidget. راجع إضافات الإدخال المدمجة للحصول على أمثلة.

برامج تشغيل الأجهزة ¶

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

class calibre.devices.interface.DevicePlugin(plugin_path)[المصدر]¶

الأساس: Plugin

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

type = 'واجهة الجهاز'¶: نوع هذه الإضافة. تستخدم لتصنيف الإضافات في واجهة المستخدم الرسومية

FORMATS = ['lrf', 'rtf', 'pdf', 'txt']¶: قائمة مرتبة بالتنسيقات المدعومة

VENDOR_ID = 0¶

يمكن أن يكون VENDOR_ID إما عددًا صحيحًا، أو قائمة من الأعداد الصحيحة أو قاموسًا. إذا كان قاموسًا، فيجب أن يكون قاموسًا من القواميس، بالشكل:

{
 integer_vendor_id : { product_id : [list of BCDs], ... },
 ...
}

PRODUCT_ID = 0¶: عدد صحيح أو قائمة من الأعداد الصحيحة

BCD = None¶: يمكن أن يكون BCD إما None لعدم التمييز بين الأجهزة بناءً على BCD، أو يمكن أن يكون قائمة بأرقام BCD لجميع الأجهزة التي يدعمها هذا المشغل.

THUMBNAIL_HEIGHT = 68¶: ارتفاع الصور المصغرة على الجهاز

THUMBNAIL_COMPRESSION_QUALITY = 75¶: جودة ضغط الصور المصغرة. اضبطها أقرب إلى 100 للحصول على صور مصغرة بجودة أفضل مع عدد أقل من عيوب الضغط. بالطبع، تصبح الصور المصغرة أكبر أيضًا.

WANTS_UPDATED_THUMBNAILS = False¶: عيّن هذا إلى True إذا كان الجهاز يدعم تحديث الصور المصغرة للغلاف أثناء sync_booklists. تعيينه إلى true سيطلب من device.py تحديث الصور المصغرة للغلاف أثناء مطابقة الكتاب

CAN_SET_METADATA = ['title', 'authors', 'collections']¶: ما إذا كان يمكن تعيين البيانات الوصفية للكتب عبر واجهة المستخدم الرسومية.

CAN_DO_DEVICE_DB_PLUGBOARD = False¶: ما إذا كان الجهاز يمكنه التعامل مع لوحات توصيل بيانات device_db الوصفية

path_sep = '/'¶: فاصل المسار لمسارات الكتب على الجهاز

icon = 'reader.png'¶: أيقونة لهذا الجهاز

UserAnnotation¶: alias of Annotation

OPEN_FEEDBACK_MESSAGE = None¶: تعرض واجهة المستخدم الرسومية هذا كرسالة إذا لم تكن None في شريط الحالة. مفيد إذا كان الفتح يستغرق وقتًا طويلاً

VIRTUAL_BOOK_EXTENSIONS = frozenset({})¶: مجموعة من الامتدادات التي هي "كتب افتراضية" على الجهاز وبالتالي لا يمكن عرضها/حفظها/إضافتها إلى المكتبة. على سبيل المثال: frozenset(['kobo'])

VIRTUAL_BOOK_EXTENSION_MESSAGE = None¶: رسالة لعرضها للمستخدم لملحقات الكتب الافتراضية.

NUKE_COMMENTS = None¶: ما إذا كان سيتم حذف التعليقات في نسخة الكتاب المرسلة إلى الجهاز. إذا لم تكن None، فيجب أن تكون هذه سلسلة قصيرة سيتم استبدال التعليقات بها.

MANAGES_DEVICE_PRESENCE = False¶: إذا كان True، فهذا يشير إلى أن هذا المشغل يدير بشكل كامل اكتشاف الأجهزة، والإخراج وما إلى ذلك. إذا قمت بتعيين هذا إلى True، فيجب عليك بالتأكيد تنفيذ أساليب detect_managed_devices و debug_managed_device_detection. المشغل الذي تم تعيين هذا الخيار له على True مسؤول عن اكتشاف الأجهزة، وإدارة قائمة سوداء للأجهزة، وقائمة بالأجهزة التي تم إخراجها وما إلى ذلك. سيقوم calibre باستدعاء أسلوب detect_managed_devices() بشكل دوري، وإذا أعاد جهازًا مكتشفًا، فسيقوم calibre باستدعاء open(). سيتم استدعاء open() في كل مرة يتم فيها إرجاع جهاز حتى لو فشلت الاستدعاءات السابقة لـ open()، لذلك يجب على المشغل الاحتفاظ بقائمة سوداء خاصة به للأجهزة الفاشلة. وبالمثل، عند الإخراج، سيقوم calibre باستدعاء eject() ثم بافتراض أن الاستدعاء التالي لـ detect_managed_devices() يعيد None، فسيقوم باستدعاء post_yank_cleanup().

SLOW_DRIVEINFO = False¶: إذا تم تعيينه على True، سيقوم calibre باستدعاء الأسلوب get_driveinfo() بعد تحميل قوائم الكتب للحصول على معلومات محرك الأقراص.

ASK_TO_ALLOW_CONNECT = False¶: إذا تم تعيينه على True، سيطلب calibre من المستخدم ما إذا كان يريد إدارة الجهاز باستخدام calibre، في المرة الأولى التي يتم فيها اكتشافه. إذا قمت بتعيين هذا على True، فيجب عليك تنفيذ get_device_uid() و ignore_connected_device() و get_user_blacklisted_devices() و set_user_blacklisted_devices()

user_feedback_after_callback = None¶: عيّن هذا إلى قاموس بالشكل {'title':عنوان، 'msg':رسالة، 'det_msg':رسالة_مفصلة} لجعل calibre يعرض رسالة منبثقة للمستخدم بعد تشغيل بعض ردود الاتصال (حاليًا فقط upload_books). كن حذرًا لعدم إغراق المستخدم بالكثير من الرسائل. يتم التحقق من هذا المتغير بعد كل رد اتصال، لذا قم بتعيينه فقط عندما تحتاج إليه حقًا.

classmethod get_open_popup_message()[المصدر]¶: تعرض واجهة المستخدم الرسومية هذا كنافذة منبثقة غير مشروطة. يجب أن يكون نسخة من OpenPopupMessage

classmethod model_metadata() → tuple[ModelMetadata, ...][المصدر]¶: بيانات وصفية حول جميع نماذج الأجهزة الفعلية التي يدعمها هذا المشغل

is_usb_connected(devices_on_system, debug=False, only_presence=False)[المصدر]¶

أعد True، device_info إذا كان جهازًا يتعامل معه هذا المكون الإضافي متصلاً حاليًا.

المعلمات:: devices_on_system -- قائمة بالأجهزة المتصلة حاليًا

detect_managed_devices(devices_on_system, force_refresh=False)[المصدر]¶

يتم استدعاؤها فقط إذا كانت MANAGES_DEVICE_PRESENCE هي True.

مسح الأجهزة التي يمكن لهذا المشغل التعامل معها. يجب أن يعيد كائن جهاز إذا تم العثور على جهاز. سيتم تمرير هذا الكائن إلى أسلوب open() كـ connected_device. إذا لم يتم العثور على جهاز، أعد None. الكائن المعاد يمكن أن يكون أي شيء، calibre لا يستخدمه، يتم تمريره فقط إلى open().

يتم استدعاء هذا الأسلوب بشكل دوري بواسطة واجهة المستخدم الرسومية، لذا تأكد من أنه ليس مستهلكًا للموارد بشكل كبير. استخدم ذاكرة تخزين مؤقت لتجنب المسح المتكرر للنظام.

المعلمات:

devices_on_system -- مجموعة من أجهزة USB الموجودة على النظام.
force_refresh -- إذا كان True ويستخدم المشغل ذاكرة تخزين مؤقت لمنع المسح المتكرر، فيجب مسح ذاكرة التخزين المؤقت.

debug_managed_device_detection(devices_on_system, output)[المصدر]¶

يتم استدعاؤها فقط إذا كانت MANAGES_DEVICE_PRESENCE هي True.

يجب أن يكتب معلومات حول الأجهزة المكتشفة على النظام إلى الإخراج، وهو كائن شبيه بالملف.

يجب أن يعيد True إذا تم اكتشاف جهاز وفتحه بنجاح، وإلا False.

reset(key='-1', log_packets=False, report_progress=None, detected_device=None)[المصدر]¶

المعلمات:

key -- مفتاح فتح الجهاز
log_packets -- إذا كان صحيحًا، يتم تسجيل تدفق الحزم من/إلى الجهاز
report_progress -- دالة يتم استدعاؤها مع نسبة مئوية من التقدم (عدد بين 0 و 100) لـ مهام مختلفة. إذا تم استدعاؤها بـ -1 فهذا يعني أن المهمة لا تحتوي على أي معلومات تقدم
detected_device -- معلومات الجهاز من ماسح الجهاز

can_handle_windows(usbdevice, debug=False)[المصدر]¶

طريقة اختيارية لإجراء المزيد من الفحوصات على الجهاز لمعرفة ما إذا كان هذا المشغل قادرًا على التعامل معه. إذا لم يكن كذلك، فيجب أن يعيد False. يتم استدعاء هذا الأسلوب فقط بعد تطابق معرفات البائع والمنتج و bcd، لذلك يمكنه إجراء بعض الفحوصات التي تستغرق وقتًا طويلاً نسبيًا. التنفيذ الافتراضي يعيد True. يتم استدعاء هذا الأسلوب فقط على Windows. راجع أيضًا can_handle().

لاحظ أنه بالنسبة للأجهزة المستندة إلى USBMS، يقوم هذا الأسلوب بشكل افتراضي بتفويض إلى can_handle(). لذا تحتاج فقط إلى تجاوز can_handle() في فئتك الفرعية من USBMS.

المعلمات:: usbdevice -- جهاز USB كما أعادته calibre.devices.winusb.scan_usb_devices()

can_handle(device_info, debug=False)[المصدر]¶

نسخة Unix من can_handle_windows().

المعلمات:: device_info -- هو tuple من (vid, pid, bcd, manufacturer, product, serial number)

open(connected_device, library_uuid)[المصدر]¶

قم بإجراء أي تهيئة خاصة بالجهاز. يتم استدعاؤها بعد اكتشاف الجهاز ولكن قبل أي وظائف أخرى تتواصل مع الجهاز. على سبيل المثال: بالنسبة للأجهزة التي تقدم نفسها كأجهزة تخزين USB جماعي، سيكون هذا الأسلوب مسؤولاً عن تركيب الجهاز أو إذا كان الجهاز قد تم تركيبه تلقائيًا، عن معرفة مكان تركيبه. الأسلوب calibre.devices.usbms.device.Device.open() لديه تنفيذ لهذه الوظيفة يجب أن يكون بمثابة مثال جيد لأجهزة تخزين USB الجماعي.

يمكن لهذا الأسلوب طرح استثناء OpenFeedback لعرض رسالة للمستخدم.

المعلمات:

connected_device -- الجهاز الذي نحاول فتحه. إنه tuple من (معرف البائع، معرف المنتج، bcd، اسم الشركة المصنعة، اسم المنتج، الرقم التسلسلي للجهاز). ومع ذلك، بعض الأجهزة لا تحتوي على رقم تسلسلي وعلى نظام Windows توجد فقط الحقول الثلاثة الأولى، والباقي None.
library_uuid -- معرف UUID لمكتبة calibre الحالية. يمكن أن يكون None إذا لم تكن هناك مكتبة (على سبيل المثال عند الاستخدام من سطر الأوامر).

eject()[المصدر]¶

إلغاء تركيب / إخراج الجهاز من نظام التشغيل. هذا لا يتحقق مما إذا كانت هناك مهام واجهة مستخدم رسومية معلقة تحتاج إلى التواصل مع الجهاز.

ملاحظة: قد لا يتم استدعاء هذا الأسلوب على نفس الخيط مثل بقية أساليب الجهاز.

post_yank_cleanup()[المصدر]¶: يتم استدعاؤها إذا قام المستخدم بسحب الجهاز دون إخراجه أولاً.

set_progress_reporter(report_progress)[المصدر]¶

تعيين دالة للإبلاغ عن معلومات التقدم.

المعلمات:: report_progress -- دالة يتم استدعاؤها مع نسبة مئوية من التقدم (عدد بين 0 و 100) لـ مهام مختلفة. إذا تم استدعاؤها بـ -1 فهذا يعني أن المهمة لا تحتوي على أي معلومات تقدم

get_device_information(end_session=True)[المصدر]¶

اطلب معلومات الجهاز من الجهاز. راجع L{DeviceInfoQuery}.

يعيد:: (اسم الجهاز، إصدار الجهاز، إصدار البرنامج على الجهاز، نوع MIME) يمكن أن يحتوي الـ tuple اختياريًا على عنصر خامس، وهو قاموس معلومات محرك الأقراص. راجع usbms.driver للحصول على مثال.

get_driveinfo()[المصدر]¶: إرجاع قاموس driveinfo. يتم استدعاؤها عادةً من get_device_information()، ولكن إذا كان تحميل driveinfo بطيئًا لهذا المشغل، فيجب أن يعيّن SLOW_DRIVEINFO. في هذه الحالة، سيتم استدعاء هذا الأسلوب بواسطة calibre بعد تحميل قوائم الكتب. لاحظ أنه لا يتم استدعاؤها على خيط الجهاز، لذا يجب على المشغل تخزين معلومات محرك الأقراص مؤقتًا في أسلوب books() ويجب أن تعيد هذه الدالة البيانات المخزنة مؤقتًا.

card_prefix(end_session=True)[المصدر]¶: إرجاع قائمة من عنصرين للبادئة إلى المسارات على البطاقات. إذا لم تكن هناك بطاقة موجودة، يتم تعيين None لبادئة البطاقة. على سبيل المثال: ('/place', '/place2') (None، 'place2') ('place', None) (None، None)

total_space(end_session=True)[المصدر]¶

احصل على إجمالي المساحة المتاحة على نقاط التحميل:

الذاكرة الرئيسية
بطاقة الذاكرة أ
بطاقة الذاكرة ب

يعيد:: قائمة من 3 عناصر تحتوي على إجمالي المساحة بالبايت (1، 2، 3). إذا لم يكن لدى جهاز معين أي من هذه المواقع، فيجب أن يعيد 0.

free_space(end_session=True)[المصدر]¶

احصل على المساحة الحرة المتاحة على نقاط التحميل:

الذاكرة الرئيسية
البطاقة أ
البطاقة ب

يعيد:: قائمة من 3 عناصر تحتوي على مساحة حرة بالبايت (1، 2، 3). إذا لم يكن لدى جهاز معين أي من هذه المواقع، فيجب أن يعيد -1.

books(oncard=None, end_session=True)[المصدر]¶

إرجاع قائمة بالكتب الإلكترونية على الجهاز.

المعلمات:: oncard -- إذا كانت 'carda' أو 'cardb' تعيد قائمة بالكتب الإلكترونية على بطاقة التخزين المحددة، وإلا أعد قائمة بالكتب الإلكترونية في الذاكرة الرئيسية للجهاز. إذا تم تحديد بطاقة ولم تكن هناك كتب على البطاقة، أعد قائمة فارغة.
يعيد:: قائمة كتب.

upload_books(files, names, on_card=None, end_session=True, metadata=None)[المصدر]¶

تحميل قائمة من الكتب إلى الجهاز. إذا كان الملف موجودًا بالفعل على الجهاز، فيجب استبداله. يجب أن يطرح هذا الأسلوب FreeSpaceError إذا لم تكن هناك مساحة حرة كافية على الجهاز. يجب أن يحتوي نص FreeSpaceError على كلمة "card" إذا لم يكن on_card None، وإلا يجب أن يحتوي على كلمة "memory".

المعلمات:

files -- قائمة المسارات
names -- قائمة بأسماء الملفات التي يجب أن تكون للكتب بمجرد تحميلها إلى الجهاز. len(names) == len(files)
metadata -- إذا لم تكن None، فهي قائمة بكائنات Metadata. الفكرة هي استخدام البيانات الوصفية لتحديد مكان وضع الكتاب على الجهاز. len(metadata) == len(files). بصرف النظر عن الغلاف العادي (مسار الغلاف)، قد يكون هناك أيضًا سمة مصغرة، والتي يجب استخدامها كأولوية. سمة المصغرة تكون بالشكل (العرض، الارتفاع، بيانات الغلاف كـ jpeg).

يعيد:

قائمة من 3-عناصر tuple. القائمة مخصصة لتمريرها إلى add_books_to_metadata().

classmethod add_books_to_metadata(locations, metadata, booklists)[المصدر]¶

أضف المواقع إلى قوائم الكتب. يجب ألا تتواصل هذه الدالة مع الجهاز.

المعلمات:

locations -- نتيجة استدعاء L{upload_books}
metadata -- قائمة بكائنات Metadata، مثل upload_books().
booklists -- زوج (tuple) يحتوي على نتيجة استدعاءات إلى (books(oncard=None)()، books(oncard='carda')()، :meth`books(oncard='cardb')`).

delete_books(paths, end_session=True)[المصدر]¶: حذف الكتب من المسارات الموجودة على الجهاز.

classmethod remove_books_from_metadata(paths, booklists)[المصدر]¶

إزالة الكتب من قائمة البيانات الوصفية. يجب ألا تتواصل هذه الدالة مع الجهاز.

المعلمات:

paths -- مسارات الكتب على الجهاز.
booklists -- زوج (tuple) يحتوي على نتيجة استدعاءات إلى (books(oncard=None)()، books(oncard='carda')()، :meth`books(oncard='cardb')`).

sync_booklists(booklists, end_session=True)[المصدر]¶

تحديث البيانات الوصفية على الجهاز.

المعلمات:: booklists -- زوج (tuple) يحتوي على نتيجة استدعاءات إلى (books(oncard=None)()، books(oncard='carda')()، :meth`books(oncard='cardb')`).

get_file(path, outfile, end_session=True)[المصدر]¶

اقرأ الملف في path على الجهاز واكتبه إلى outfile.

المعلمات:: outfile -- كائن ملف مثل sys.stdout أو نتيجة استدعاء open().

classmethod config_widget()[المصدر]¶: يجب أن تعيد QWidget. يحتوي QWidget على إعدادات واجهة الجهاز

classmethod save_settings(settings_widget)[المصدر]¶: يجب أن يحفظ الإعدادات على القرص. يأخذ الأداة التي تم إنشاؤها في config_widget() ويحفظ جميع الإعدادات على القرص.

classmethod settings()[المصدر]¶: يجب أن يعيد كائن خيارات. يجب أن يحتوي كائن الخيارات على سمة واحدة على الأقل format_map وهي قائمة مرتبة من التنسيقات للجهاز.

set_plugboards(plugboards, pb_func)[المصدر]¶

تزويد المشغل بالمجموعة الحالية من لوحات التوصيل ودالة لتحديد لوحة توصيل معينة. يتم استدعاء هذا الأسلوب مباشرة قبل add_books و sync_booklists.

pb_func هو كائن قابل للاستدعاء بالتوقيع التالي:: def pb_func(اسم_الجهاز, تنسيق, لوحات_توصيل)

تعطيه اسم الجهاز الحالي (إما اسم الفئة أو DEVICE_PLUGBOARD_NAME)، والتنسيق الذي تهتم به (تنسيق 'حقيقي' أو 'device_db')، ولوحات التوصيل (التي تم إعطاؤها لك بواسطة set_plugboards، نفس المكان الذي حصلت منه على هذا الأسلوب).

يعيد:: None أو مثيل لوحة توصيل واحدة.

set_driveinfo_name(location_code, name)[المصدر]¶

عيّن اسم الجهاز في ملف driveinfo إلى 'name'. سيستمر هذا الإعداد حتى يتم إعادة إنشاء الملف أو تغيير الاسم مرة أخرى.

يجب أن تنفذ الأجهزة غير القرصية هذا الأسلوب بناءً على رموز الموقع التي أعادها أسلوب get_device_information().

prepare_addable_books(paths)[المصدر]¶

بالنظر إلى قائمة من المسارات، يعيد قائمة أخرى من المسارات. تشير هذه المسارات إلى إصدارات قابلة للإضافة من الكتب.

إذا كان هناك خطأ في إعداد كتاب، فبدلاً من المسار، يجب أن يكون الموضع في القائمة المعادة لذلك الكتاب عبارة عن tuple ثلاثي: (original_path، مثيل الاستثناء، traceback)

startup()[المصدر]¶: يتم استدعاؤها عند بدء calibre للجهاز. قم بأي تهيئة مطلوبة. لاحظ أنه يمكن إنشاء عدة مثيلات من الفئة، وبالتالي يمكن استدعاء __init__ عدة مرات، ولكن سيتم استدعاء هذا الأسلوب لمثيل واحد فقط. يتم استدعاء هذا الأسلوب على خيط الجهاز، وليس خيط واجهة المستخدم الرسومية.

shutdown()[المصدر]¶: يتم استدعاؤها عند إغلاق calibre، إما بشكل دائم أو استعدادًا لإعادة التشغيل. قم بأي تنظيف مطلوب. يتم استدعاء هذا الأسلوب على خيط الجهاز، وليس خيط واجهة المستخدم الرسومية.

get_device_uid()[المصدر]¶: يجب أن يعيد معرفًا فريدًا للجهاز المتصل حاليًا (يتم استدعاء هذا مباشرة بعد استدعاء ناجح لـ open()). يجب عليك تنفيذ هذا الأسلوب إذا قمت بتعيين ASK_TO_ALLOW_CONNECT = True

ignore_connected_device(uid)[المصدر]¶: يجب أن يتجاهل الجهاز المحدد بواسطة uid (نتيجة استدعاء get_device_uid()) في المستقبل. يجب عليك تنفيذ هذا الأسلوب إذا قمت بتعيين ASK_TO_ALLOW_CONNECT = True. لاحظ أن هذه الدالة يتم استدعاؤها مباشرة بعد open()، لذا إذا قامت open() بتخزين بعض الحالات مؤقتًا، فيجب على المشغل إعادة تعيين تلك الحالة.

get_user_blacklisted_devices()[المصدر]¶: إرجاع خريطة من معرف الجهاز إلى الاسم الودي لجميع الأجهزة التي طلب المستخدم تجاهلها.

set_user_blacklisted_devices(devices)[المصدر]¶: عيّن قائمة معرفات الجهاز التي يجب تجاهلها بواسطة هذا المشغل.

specialize_global_preferences(device_prefs)[المصدر]¶: نفّذ هذا الأسلوب إذا كان جهازك يريد تجاوز تفضيل معين. يجب عليك التأكد من أن جميع مواقع الاستدعاء التي تريد تفضيلًا يمكن تجاوزه تستخدم device_prefs['something'] بدلاً من prefs['something']. يجب أن يستدعي أسلوبك device_prefs.set_overrides(pref=val, pref=val, ...). يستخدم حاليًا لـ: إدارة البيانات الوصفية (prefs['manage_device_metadata'])

set_library_info(library_name, library_uuid, field_metadata)[المصدر]¶: نفّذ هذا الأسلوب إذا كنت تريد معلومات حول مكتبة calibre الحالية. يتم استدعاء هذا الأسلوب عند بدء التشغيل وعند تغيير مكتبة calibre أثناء الاتصال.

is_dynamically_controllable()[المصدر]¶

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