توثيق API لواجهة قاعدة البيانات

هذه الواجهة البرمجية (API) آمنة للخيوط (تستخدم مخطط قفل متعدد القراء، كاتب واحد). يمكنك الوصول إلى هذه الواجهة البرمجية بهذه الطريقة:

from calibre.library import db
db = db('Path to calibre library folder').new_api

إذا كنت في إضافة calibre وهي جزء من واجهة المستخدم الرسومية الرئيسية لـ calibre، يمكنك الوصول إليها بهذه الطريقة بدلاً من ذلك:

db = self.gui.current_db.new_api

class calibre.db.cache.Cache(backend, library_database_instance=None)

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

يُستخدم SQLITE ببساطة كوسيلة لقراءة وكتابة البيانات من metadata.db بشكل قوي. تمت إعادة تنفيذ جميع منطق قراءة/فرز/بحث/تخزين الجداول مؤقتًا. كان هذا ضروريًا لتحقيق أقصى أداء ومرونة.

class EventType(*values)

book_created = 4

عند إنشاء سجل كتاب جديد في قاعدة البيانات، مع معرف الكتاب كـ الوسيط الوحيد

book_edited = 8

عند تحرير تنسيق كتاب، مع الوسائط: (book_id, fmt)

books_removed = 5

عند إزالة الكتب من قاعدة البيانات مع قائمة معرفات الكتب كـ الوسيط الوحيد

format_added = 2

عند إضافة تنسيق إلى كتاب، مع الوسائط: (book_id, format)

formats_removed = 3

عند إزالة التنسيقات من كتاب، مع الوسائط: (تعيين معرف الكتاب إلى مجموعة التنسيقات التي تمت إزالتها من الكتاب).

indexing_progress_changed = 9

عندما يتغير تقدم الفهرسة

items_removed = 7

عند إزالة عناصر مثل العلامات أو المؤلفين من بعض الكتب. الوسائط: (اسم_الحقل، معرفات_الكتب_المتأثرة، معرفات_العناصر_المزالة)

items_renamed = 6

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

links_changed = 11

عند تغيير الروابط المرتبطة بالعناصر، مع الوسائط: (اسم_الحقل، معرفات_العناصر)

metadata_changed = 1

عند تغيير بعض البيانات الوصفية لبعض الكتب، مع الوسائط: (اسم الحقل الذي تم تغييره، مجموعة معرفات الكتب المتأثرة)

notes_changed = 10

عند تغيير الملاحظات المرتبطة بالعناصر، مع الوسائط: (اسم_الحقل، معرفات_العناصر)

add_books(books, add_duplicates=True, apply_import_tags=True, preserve_uuid=False, run_hooks=True, dbapi=None)

أضف الكتب المحددة إلى المكتبة. يجب أن تكون الكتب قابلة للتكرار من أزواج (tuples) من عنصرين، كل زوج بالشكل (mi, format_map) حيث mi هو كائن Metadata و format_map هو قاموس بالشكل {fmt: path_or_stream}، على سبيل المثال: {'EPUB': '/path/to/file.epub'}.

يعيد زوجًا من القوائم: ids, duplicates. يحتوي ids على معرفات الكتب لجميع الكتب التي تم إنشاؤها حديثًا في قاعدة البيانات. يحتوي duplicates على (mi, format_map) لجميع الكتب الموجودة بالفعل في قاعدة البيانات وفقًا لأسلوب الكشف البسيط عن التكرارات المستخدم بواسطة has_book().

add_custom_book_data(name, val_map, delete_first=False)

أضف بيانات للاسم حيث val_map هي خريطة من book_ids إلى القيم. إذا كان delete_first صحيحًا، فسيتم إزالة جميع البيانات المخزنة مسبقًا للاسم.

add_extra_files(book_id, map_of_relpath_to_stream_or_path, replace=True, auto_rename=False)

إضافة ملفات بيانات إضافية

add_format(book_id, fmt, stream_or_path, replace=True, run_hooks=True, dbapi=None)

أضف تنسيقًا إلى الكتاب المحدد. أعد True إذا تمت إضافة التنسيق بنجاح.

المعلمات:

• replace -- إذا كان True، استبدل التنسيق الموجود، وإلا إذا كان التنسيق موجودًا بالفعل، أعد False.

• run_hooks -- إذا كان True، يتم تشغيل إضافات نوع الملف على التنسيق قبل وبعد إضافته.

• dbapi -- للاستخدام الداخلي فقط.

add_listener(event_callback_function, check_already_added=False)

سجل دالة رد اتصال سيتم استدعاؤها بعد اتخاذ إجراءات معينة على قاعدة البيانات هذه. يجب أن تأخذ الدالة ثلاثة وسائط: (EventType, library_id, event_type_specific_data)

add_notes_resource(path_or_stream_or_data, name: str, mtime: float = None) → int

أضف المورد المحدد بحيث يمكن الإشارة إليه بواسطة الملاحظات وأعد تجزئة محتواه

all_annotation_types()

إرجاع tuple بجميع أنواع التعليقات التوضيحية في قاعدة البيانات.

all_annotation_users()

إرجاع tuple بجميع (user_type, user name) التي تحتوي على تعليقات توضيحية.

all_annotations(restrict_to_user=None, limit=None, annotation_type=None, ignore_removed=False, restrict_to_book_ids=None)

إرجاع tuple بجميع التعليقات التوضيحية التي تطابق المعايير المحددة. يتحكم ignore_removed فيما إذا كانت التعليقات التوضيحية التي تمت إزالتها (المحذوفة) تُعاد أيضًا. التعليقات التوضيحية التي تمت إزالتها هي مجرد هيكل عظمي يستخدم لدمج التعليقات التوضيحية.

all_annotations_for_book(book_id)

إرجاع tuple يحتوي على جميع التعليقات التوضيحية لـ book_id المحدد كـ قاموس بمفاتيح: format, user_type, user, annotation. هنا، annotation هي بيانات التعليق التوضيحي.

all_book_ids(type=<class 'frozenset'>)

مجموعة مجمدة من جميع معرفات الكتب المعروفة.

all_field_for(field, book_ids, default_value=None)

نفس field_for، باستثناء أنه يعمل على كتب متعددة في وقت واحد

all_field_ids(name)

مجموعة مجمدة من المعرفات لجميع القيم في الحقل name.

all_field_names(field)

مجموعة مجمدة من جميع أسماء الحقول (يجب استخدامها فقط للحقول متعددة إلى واحد ومتعددة إلى متعدد).

annotation_count_for_book(book_id)

إرجاع عدد التعليقات التوضيحية للكتاب المحدد المتاحة في قاعدة البيانات.

annotations_map_for_book(book_id, fmt, user_type='local', user='viewer')

إرجاع خريطة من نوع التعليق التوضيحي -> بيانات التعليق التوضيحي لـ book_id المحدد، التنسيق، المستخدم ونوع المستخدم.

author_data(author_ids=None)

إرجاع بيانات المؤلف كقاموس بمفاتيح: name, sort, link

إذا لم يتم العثور على مؤلفين بالمعرفات المحددة، يتم إرجاع قاموس فارغ. إذا كان author_ids هو None، يتم إرجاع بيانات جميع المؤلفين.

author_sort_from_authors(authors, key_func=<function make_change_case_func.<locals>.change_case>)

بالنظر إلى قائمة من المؤلفين، أعد سلسلة author_sort للمؤلفين، مع تفضيل ترتيب المؤلف المرتبط بالمؤلف على السلسلة المحسوبة.

books_for_field(name, item_id)

إرجاع جميع الكتب المرتبطة بالعنصر المحدد بواسطة item_id، حيث ينتمي العنصر إلى الحقل name.

القيمة المعادة هي مجموعة من معرفات الكتب، أو المجموعة الفارغة إذا لم يكن العنصر أو الحقل موجودًا.

books_in_virtual_library(vl, search_restriction=None, virtual_fields=None)

إرجاع مجموعة الكتب في المكتبة الافتراضية المحددة

compress_covers(book_ids, jpeg_quality=100, progress_callback=None)

ضغط صور الغلاف للكتب المحددة. جودة ضغط 100 ستؤدي إلى ضغط بدون فقدان، وإلا ضغط مع فقدان.

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

copy_cover_to(book_id, dest, use_hardlink=False, report_file_size=None)

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

copy_format_to(book_id, fmt, dest, use_hardlink=False, report_file_size=None)

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

cover(book_id, as_file=False, as_image=False, as_path=False, as_pixmap=False)

إرجاع صورة الغلاف أو None. افتراضيًا، يعيد الغلاف كسلسلة بايتات.

تحذير: استخدام as_path سينسخ الغلاف إلى ملف مؤقت ويعيد المسار إلى الملف المؤقت. يجب عليك حذف الملف المؤقت عند الانتهاء منه.

المعلمات:

• as_file -- إذا كان True، أعد الصورة ككائن ملف مفتوح (SpooledTemporaryFile)

• as_image -- إذا كان True، أعد الصورة ككائن QImage

• as_pixmap -- إذا كان True، أعد الصورة ككائن QPixmap

• as_path -- إذا كان True، أعد الصورة كمسار يشير إلى ملف مؤقت

data_for_find_identical_books()

إرجاع البيانات التي يمكن استخدامها لتنفيذ find_identical_books() في عملية عاملة دون الوصول إلى قاعدة البيانات. راجع db.utils للحصول على تطبيق.

data_for_has_book()

إرجاع البيانات المناسبة للاستخدام في has_book(). يمكن استخدام هذا لـ تطبيق has_book() في عملية عاملة دون الوصول إلى قاعدة البيانات.

delete_annotations(annot_ids)

حذف التعليقات التوضيحية بالمعرفات المحددة.

delete_custom_book_data(name, book_ids=())

حذف البيانات للاسم. افتراضيًا يحذف جميع البيانات، إذا كنت تريد فقط حذف البيانات لبعض معرفات الكتب، فمرر قائمة بمعرفات الكتب.

delete_trash_entry(book_id, category)

حذف إدخال من سلة المهملات. هنا الفئة هي 'b' للكتب و 'f' لـ التنسيقات.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)

تحديث البيانات الوصفية في جميع تنسيقات book_ids المحددة إلى البيانات الوصفية الحالية في قاعدة البيانات.

expire_old_trash()

انتهاء صلاحية الإدخالات من سلة المهملات التي تجاوزت مدتها

export_note(field, item_id) → str

تصدير الملاحظة كوثيقة HTML واحدة مع صور مضمنة كـ data: URLs

fast_field_for(field_obj, book_id, default_value=None)

نفس field_for، باستثناء أنه يتجنب البحث الإضافي للحصول على كائن الحقل

field_for(name, book_id, default_value=None)

إرجاع قيمة الحقل name للكتاب المحدد بواسطة book_id. إذا لم يكن هذا الكتاب موجودًا أو لم يكن له قيمة محددة للحقل name أو لم يكن هذا الحقل موجودًا، فسيتم إرجاع default_value.

لا تُستخدم default_value لعناوين title, title_sort, authors, author_sort و series_index. وذلك لأن هذه القيم دائمًا ما تكون موجودة في قاعدة البيانات. تُستخدم default_value لجميع الأعمدة المخصصة.

القيمة المعادة للحقول is_multiple هي دائمًا tuples، حتى عندما لا يتم العثور على قيم (بمعنى آخر، يتم تجاهل default_value). الاستثناء هو المعرفات التي تكون القيمة المعادة لها دائمًا قاموسًا. تكون الـ tuples المعادة دائمًا بترتيب الارتباط، أي الترتيب الذي تم إنشاؤها به.

field_ids_for(name, book_id)

إرجاع المعرفات (كـ tuple) للقيم التي يحتوي عليها الحقل name على الكتاب المحدد بواسطة book_id. إذا لم تكن هناك قيم، أو لم يكن هذا الكتاب موجودًا، أو لم يكن هذا الحقل موجودًا، فسيتم إرجاع tuple فارغ.

field_supports_notes(field=None) → bool

إرجاع True إذا وفقط إذا كان الحقل المحدد يدعم الملاحظات. إذا كان الحقل None، أعد مجموعة مجمدة من جميع الحقول التي تدعم الملاحظات.

find_identical_books(mi, search_restriction='', book_ids=None)

يعثر على الكتب التي تحتوي على مجموعة فائقة من المؤلفين في mi ونفس العنوان (يتم مطابقة العنوان بشكل تقريبي). راجع أيضًا data_for_find_identical_books().

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)

إرجاع تنسيق الكتاب الإلكتروني كسلسلة بايتات أو None إذا لم يكن التنسيق موجودًا، أو إذا لم يكن لدينا إذن للكتابة إلى ملف الكتاب الإلكتروني.

المعلمات:

• as_file -- إذا كان True، يتم إرجاع تنسيق الكتاب الإلكتروني ككائن ملف. لاحظ أن كائن الملف هو SpooledTemporaryFile، لذا إذا كنت ترغب في نسخ التنسيق إلى ملف آخر، استخدم copy_format_to() بدلاً من ذلك للأداء.

• as_path -- ينسخ ملف التنسيق إلى ملف مؤقت ويعيد المسار إلى الملف المؤقت

• preserve_filename -- إذا كان True وإرجاع مسار، فإن اسم الملف هو نفسه المستخدم في المكتبة. لاحظ أن استخدام هذا يعني أن الاستدعاءات المتكررة تنتج نفس الملف المؤقت (الذي يتم إعادة إنشائه في كل مرة).

format_abspath(book_id, fmt)

إرجاع المسار المطلق لملف الكتاب الإلكتروني بتنسيق format. يجب عليك عدم استخدام هذا أبدًا تقريبًا، لأنه يكسر وعد الأمان للخيوط في واجهة برمجة التطبيقات هذه. بدلاً من ذلك، استخدم copy_format_to().

يستخدم حاليًا فقط في قائمة calibredb، العارض، تحرير الكتاب، مقارنة التنسيق بالتنسيق الأصلي، الفتح باستخدام، تحرير البيانات الوصفية بالجملة والكتالوجات (عبر get_data_as_dict()).

بصرف النظر عن العارض، والفتح باستخدام، وتحرير الكتاب، لا أعتقد أن أيًا من الآخرين يقوم بأي إدخال/إخراج كتابة ملفات مع نتائج هذا الاستدعاء.

format_hash(book_id, fmt)

إرجاع تجزئة التنسيق المحدد للكتاب المحدد. نوع التجزئة يعتمد على الواجهة الخلفية، ولكنه عادةً SHA-256.

format_metadata(book_id, fmt, allow_cache=True, update_db=False)

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

المعلمات:

• allow_cache -- إذا كان True، يتم استخدام القيم المخزنة مؤقتًا، وإلا يتم إجراء وصول بطيء إلى نظام الملفات. قد تكون قيم ذاكرة التخزين المؤقت قديمة إذا تم الوصول إلى نظام الملفات خارج واجهة برمجة التطبيقات هذه.

• update_db -- إذا كان True، يتم تحديث حقل max_size في قاعدة البيانات لهذا الكتاب.

formats(book_id, verify_formats=True)

إرجاع tuple بجميع التنسيقات للكتاب المحدد. إذا كان verify_formats هو True، يتحقق من وجود الملفات على القرص.

get_all_items_that_have_notes(field_name=None) → set[int] | dict[str, set[int]]

إرجاع جميع item_ids للعناصر التي تحتوي على ملاحظات في الحقل المحدد أو جميع الحقول إذا كان field_name هو None

get_all_link_maps_for_book(book_id)

يعيد جميع الروابط لجميع الحقول المشار إليها بواسطة الكتاب المحدد بواسطة book_id. إذا لم يكن book_id موجودًا، فإن الأسلوب يعيد {}.

مثال: افترض أن المؤلف أ لديه رابط X، والمؤلف ب لديه رابط Y، والعلامة S لديها رابط F، والعلامة T لديها رابط G. إذا كان الكتاب 1 لديه المؤلف أ والعلامة T، فإن هذا الأسلوب يعيد {'authors':{'A':'X'}, 'tags':{'T', 'G'}}. إذا لم يكن مؤلف الكتاب 2 لا أ ولا ب وليس لديه علامات، فإن هذا الأسلوب يعيد {}.

المعلمات:

book_id -- معرف الكتاب المعني.

يعيد:

{الحقل: {قيمة_الحقل، قيمة_الرابط}، ... لجميع الحقول التي تحتوي على قيمة_الحقل ذات قيمة رابط غير فارغة لذلك الكتاب

get_categories(sort='name', book_ids=None, already_fixed=None, first_letter_sort=False, uncollapsed_categories=None)

يستخدم داخليًا لتنفيذ متصفح العلامات

get_custom_book_data(name, book_ids=(), default=None)

احصل على بيانات للاسم. افتراضيًا، يعيد البيانات لجميع book_ids، مرر قائمة بمعرفات الكتب إذا كنت تريد بعض البيانات فقط. يعيد خريطة من book_id إلى القيم. إذا تعذر فك ترميز قيمة معينة، فسيستخدم القيمة الافتراضية لها.

get_id_map(field)

إرجاع تعيين من أرقام المعرفات إلى القيم للحقل المحدد. يجب أن يكون الحقل متعددًا إلى واحد أو متعددًا إلى متعدد، وإلا يتم طرح ValueError.

get_ids_for_custom_book_data(name)

إرجاع مجموعة معرفات الكتب التي تحتوي على بيانات للاسم.

get_item_id(field, item_name, case_sensitive=False)

إرجاع معرف العنصر لـ item_name أو None إذا لم يتم العثور عليه. هذه الدالة بطيئة جدًا إذا كنت تقوم بعمليات بحث عن أسماء متعددة، استخدم إما get_item_ids() أو get_item_name_map(). وبالمثل، فإن عمليات البحث الحساسة لحالة الأحرف أسرع من تلك غير الحساسة لحالة الأحرف.

get_item_ids(field, item_names, case_sensitive=False)

إرجاع قاموس يربط item_name بمعرف العنصر أو None

get_item_name(field, item_id)

إرجاع اسم العنصر للعنصر المحدد بواسطة item_id في الحقل المحدد. راجع أيضًا get_id_map().

get_item_name_map(field, normalize_func=None)

إرجاع تعيين قيم العناصر إلى معرفاتها

get_link_map(for_field)

إرجاع قاموس بالروابط للحقل المقدم.

المعلمات:

for_field -- اسم البحث للحقل الذي يراد الحصول على خريطة الرابط له

يعيد:

{قيمة_الحقل:قيمة_الرابط، ...} للروابط غير الفارغة

get_metadata(book_id, get_cover=False, get_user_categories=True, cover_as_data=False)

إرجاع البيانات الوصفية للكتاب المحدد بواسطة book_id كـ كائن calibre.ebooks.metadata.book.base.Metadata. لاحظ أن قائمة التنسيقات غير متحقق منها. إذا كان get_cover هو True، يتم إرجاع الغلاف، إما مسار إلى ملف مؤقت كـ mi.cover أو إذا كان cover_as_data هو True فحينئذٍ كـ mi.cover_data.

get_next_series_num_for(series, field='series', current_indices=False)

إرجاع فهرس السلسلة التالي للسلسلة المحددة، مع الأخذ في الاعتبار التفضيلات المختلفة التي تتحكم في إنشاء رقم السلسلة التالي.

المعلمات:

• field -- الحقل الشبيه بالسلسلة (الافتراضي هو عمود السلسلة المدمج)

• current_indices -- إذا كان True، يعيد تعيينًا من book_id إلى قيمة series_index الحالية بدلاً من ذلك.

get_notes_resource(resource_hash) → dict | None

إرجاع قاموس يحتوي على بيانات المورد واسمه أو None إذا لم يتم العثور على مورد بالتجزئة المحددة

get_proxy_metadata(book_id)

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

get_usage_count_by_id(field)

إرجاع تعيين من المعرف إلى عدد الاستخدام لجميع قيم الحقل المحدد، والذي يجب أن يكون حقلاً متعددًا إلى واحد أو متعددًا إلى متعدد.

has_book(mi)

إرجاع True إذا وفقط إذا كانت قاعدة البيانات تحتوي على إدخال بنفس العنوان مثل كائن Metadata الذي تم تمريره. المقارنة غير حساسة لحالة الأحرف. راجع أيضًا data_for_has_book().

has_format(book_id, fmt)

إرجاع True إذا وفقط إذا كان التنسيق موجودًا على القرص

has_id(book_id)

إرجاع True إذا وفقط إذا كان book_id المحدد موجودًا في قاعدة البيانات

import_note(field, item_id, path_to_html_file, path_is_data=False)

استيراد ملاحظة تم تصديرها مسبقًا أو ملف HTML عشوائي كملاحظة لـ العنصر المحدد

init()

تهيئة ذاكرة التخزين المؤقت هذه ببيانات من الواجهة الخلفية.

items_with_notes_in_book(book_id: int) → dict[str, dict[int, str]]

إرجاع قاموس من الحقول إلى العناصر التي تحتوي على ملاحظات مرتبطة بهذا الحقل للكتاب المحدد

link_for(field, item_id)

إرجاع الرابط، إن وجد، للعنصر المحدد أو None إذا لم يتم العثور على رابط

list_extra_files(book_id, use_cache=False, pattern='') → tuple[ExtraFile, ...]

الحصول على معلومات حول الملفات الإضافية في دليل الكتاب.

المعلمات:

• book_id -- معرف كتاب قاعدة البيانات للكتاب

• pattern -- نمط أسماء الملفات للبحث عنها. النمط الفارغ يطابق جميع الملفات الإضافية. يجب أن تستخدم الأنماط / كفاصل. استخدم الثابت DATA_FILE_PATTERN لمطابقة الملفات داخل دليل البيانات.

يعيد:

زوج (tuple) من جميع الملفات الإضافية التي تطابق النمط المحدد. كل عنصر من الزوج هو ExtraFile(relpath, file_path, stat_result). حيث relpath هو المسار النسبي للملف إلى دليل الكتاب باستخدام / كفاصل. stat_result هو نتيجة استدعاء os.stat() على الملف.

merge_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')

دمج التعليقات التوضيحية المحددة في التعليقات التوضيحية الموجودة لـ book_id، fm، user_type، والمستخدم.

merge_extra_files(dest_id, src_ids, replace=False)

دمج الملفات الإضافية من src_ids إلى dest_id. يتم إعادة تسمية الملفات المتعارضة تلقائيًا ما لم يكن replace=True، وفي هذه الحالة يتم استبدالها.

move_book_from_trash(book_id)

إلغاء حذف كتاب من دليل المهملات

move_format_from_trash(book_id, fmt)

إلغاء حذف تنسيق من دليل المهملات

multisort(fields, ids_to_sort=None, virtual_fields=None)

إرجاع قائمة بمعرفات الكتب المرتبة. إذا كان ids_to_sort هو None، يتم إرجاع جميع معرفات الكتب.

يجب أن تكون الحقول قائمة من أزواج (tuples) من عنصرين بالشكل (field_name, ascending=True أو False). الحقل الأكثر أهمية هو الزوج الأول.

notes_data_for(field, item_id) → str

إرجاع جميع بيانات الملاحظات كقاموس أو None إذا لم تكن الملاحظة موجودة

notes_for(field, item_id) → str

إرجاع مستند الملاحظات أو سلسلة فارغة إذا لم يتم العثور عليه

notes_resources_used_by(field, item_id)

إرجاع مجموعة تجزئات الموارد لجميع الموارد المستخدمة بواسطة الملاحظة لـ العنصر المحدد

pref(name, default=None, namespace=None)

إرجاع القيمة للتفضيل المحدد أو القيمة المحددة كـ default إذا لم يتم تعيين التفضيل.

read_backup(book_id)

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

remove_books(book_ids, permanent=False)

إزالة الكتب المحددة بواسطة book_ids من قاعدة البيانات وحذف ملفات تنسيقاتها. إذا كان permanent هو False، فسيتم وضع ملفات التنسيقات في دليل المهملات الخاص بالمكتبة.

remove_extra_files(book_id: int, relpaths: Iterable[str], permanent=False) → dict[str, Exception | None]

حذف الملفات الإضافية المحددة، إما إلى سلة المحذوفات أو بشكل دائم.

remove_formats(formats_map, db_only=False)

إزالة التنسيقات المحددة من الكتب المحددة.

المعلمات:

• formats_map -- تعيين من book_id إلى قائمة من التنسيقات المراد إزالتها من الكتاب.

• db_only -- إذا كان True، فقم فقط بإزالة السجل الخاص بالتنسيق من قاعدة البيانات، ولا تحذف ملف التنسيق الفعلي من نظام الملفات.

يعيد:

خريطة من معرف الكتاب إلى مجموعة التنسيقات التي تم حذفها فعليًا من نظام الملفات لـ هذا الكتاب

remove_items(field, item_ids, restrict_to_book_ids=None)

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

rename_extra_files(book_id, map_of_relpath_to_new_relpath, replace=False)

إعادة تسمية ملفات البيانات الإضافية

rename_items(field, item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)

إعادة تسمية العناصر من حقل متعدد إلى واحد أو متعدد إلى متعدد مثل العلامات أو السلاسل.

المعلمات:

• change_index -- عند إعادة التسمية في حقل شبيه بالسلسلة، قم أيضًا بتغيير قيم series_index.

• restrict_to_book_ids -- مجموعة اختيارية من معرفات الكتب التي سيتم إجراء إعادة التسمية لها، الافتراضي هو جميع الكتب.

restore_book(book_id, mi, last_modified, path, formats, annotations=())

استعادة إدخال الكتاب في قاعدة البيانات لكتاب موجود بالفعل على نظام الملفات

restore_original_format(book_id, original_fmt)

استعادة التنسيق المحدد من ORIGINAL_FORMAT المحفوظ سابقًا، إن وجد. أعد True عند النجاح. يتم حذف ORIGINAL_FORMAT بعد استعادة ناجحة.

property safe_read_lock

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

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

save_original_format(book_id, fmt)

حفظ نسخة من التنسيق المحدد كـ ORIGINAL_FORMAT، مع الكتابة فوق أي ORIGINAL_FORMAT موجود.

search(query, restriction='', virtual_fields=None, book_ids=None)

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

المعلمات:

• restriction -- قيد يتم ربطه بالاستعلام المحدد بواسطة AND. لاحظ أن القيود يتم تخزينها مؤقتًا، وبالتالي فإن البحث عن a AND b سيكون أبطأ من a مع القيد b.

• virtual_fields -- يستخدم داخليًا (حقول افتراضية مثل on_device للبحث فيها).

• book_ids -- إذا لم يكن None، فمجموعة من معرفات الكتب التي سيتم البحث عنها بدلاً من البحث في جميع الكتب.

search_annotations(fts_engine_query, use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, annotation_type=None, restrict_to_book_ids=None, restrict_to_user=None, ignore_removed=False)

إرجاع tuple من التعليقات التوضيحية التي تطابق استعلام النص الكامل المحدد.

search_notes(fts_engine_query='', use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, restrict_to_fields=(), return_text=True, result_type=<class 'tuple'>, process_each_result=None, limit=None)

البحث في نص الملاحظات باستخدام فهرس FTS. إذا كان الاستعلام فارغًا، أعد جميع الملاحظات.

set_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')

عيّن جميع التعليقات التوضيحية لـ book_id المحدد، fmt، user_type، والمستخدم.

set_conversion_options(options, fmt='PIPE')

يجب أن تكون الخيارات خريطة بالشكل {book_id:conversion_options}

set_cover(book_id_data_map)

عيّن الغلاف لهذا الكتاب. يمكن أن تكون البيانات إما QImage، QPixmap، كائن ملف أو سلسلة بايتات. يمكن أن تكون أيضًا None، وفي هذه الحالة يتم إزالة أي غلاف موجود.

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)

عيّن قيم الحقل المحدد بواسطة name. يعيد مجموعة جميع معرفات الكتب التي تأثرت بالتغيير.

المعلمات:

• book_id_to_val_map -- تعيين من book_ids إلى القيم التي يجب تطبيقها.

• allow_case_change -- إذا كان True، فسيتم تغيير حالة الحقول متعددة إلى واحد أو متعددة إلى متعدد. على سبيل المثال، إذا كان كتاب يحتوي على العلامة tag1 وقمت بتعيين العلامة لكتاب آخر إلى Tag1، فسيحتوي كلا الكتابين على العلامة Tag1 إذا كان allow_case_change هو True، وإلا فسيحتوي كلاهما على العلامة tag1.

• do_path_update -- يستخدم داخليًا، لا يجب عليك تغييره أبدًا.

set_link_map(field, value_to_link_map, only_set_if_no_existing_link=False)

يعيّن الروابط لقيم العناصر في الحقل. ملاحظة: هذا الأسلوب لا يغير القيم غير الموجودة في value_to_link_map

المعلمات:

• field -- اسم البحث

• value_to_link_map -- قاموس (قيمة_الحقل:رابط، ...). لاحظ أن هذه قيم، وليست معرفات حقول.

يعيد:

الكتب التي تغيرت بتعيين الرابط

set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)

عيّن البيانات الوصفية للكتاب id من كائن Metadata mi

تعيين force_changes=True سيجبر set_metadata على تحديث الحقول حتى لو احتوى mi على قيم فارغة. في هذه الحالة، يتم تمييز 'None' عن 'empty'. إذا كان mi.XXX هو None، فلن يتم استبدال XXX، وإلا فسيتم استبداله. علامات، معرفات، وسمات الغلاف هي حالات خاصة. لا يمكن تعيين العلامات والمعرفات إلى None، لذا سيتم استبدالها دائمًا إذا كان force_changes صحيحًا. يجب عليك التأكد من أن mi يحتوي على القيم التي تريد أن يحتوي عليها الكتاب. تتغير الأغلفة دائمًا إذا تم توفير غلاف جديد، ولكنها لا تُحذف أبدًا. لاحظ أيضًا أن force_changes ليس له تأثير على تعيين العنوان أو المؤلفين.

set_notes_for(field, item_id, doc: str, searchable_text: str = '', resource_hashes=(), remove_unused_resources=False) → int

عيّن مستند الملاحظات. إذا كان النص القابل للبحث مختلفًا عن المستند، حدده كـ searchable_text. إذا كان المستند يشير إلى موارد، فيجب أن تكون تجزئاتها موجودة في resource_hashes. عيّن remove_unused_resources إلى True لتنظيف الموارد غير المستخدمة، لاحظ أن تحديث ملاحظة ينظف تلقائيًا الموارد المتعلقة بتلك الملاحظة على أي حال.

set_pref(name, val, namespace=None)

عيّن التفضيل المحدد إلى القيمة المحددة. راجع أيضًا pref().

split_if_is_multiple_composite(f, val)

إذا كان f مفتاح بحث عمود مركب وكان العمود is_multiple، فقم بتقسيم v إلى قيم فريدة غير فارغة. المقارنة حساسة لحالة الأحرف. الترتيب لا يتم الحفاظ عليه. أعد قائمة () للتوافق مع وظائف الحصول على حقول البيانات الوصفية الوكيلة، على سبيل المثال العلامات.

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)

إرجاع معرفات جميع الكتب التي تحتوي على العلامة tag والتي هي أقدم من الوقت المحدد. مقارنة العلامة غير حساسة لحالة الأحرف.

المعلمات:

• delta -- كائن timedelta أو None. إذا كان None، فسيتم إرجاع جميع المعرفات التي تحتوي على العلامة.

• must_have_tag -- إذا لم يكن None، فسيتم تقييد قائمة التطابقات على الكتب التي تحتوي على هذه العلامة

• must_have_authors -- قائمة من المؤلفين. إذا لم تكن None، فسيتم تقييد قائمة التطابقات على الكتب التي تحتوي على هؤلاء المؤلفين (غير حساسة لحالة الأحرف).

unretire_note_for(field, item_id) → int

إلغاء إيقاف ملاحظة سابقة تم إيقافها للعنصر المحدد. يتم إيقاف الملاحظات عند إزالة عنصر من قاعدة البيانات

update_annotations(annot_id_map)

تحديث التعليقات التوضيحية.

user_categories_for_books(book_ids, proxy_metadata_map=None)

إرجاع فئات المستخدم للكتب المحددة. proxy_metadata_map اختياري ومفيد لتعزيز الأداء، في السياقات التي يوجد فيها كائن ProxyMetadata للكتب بالفعل. يجب أن يكون تعيينًا من book_ids إلى كائنات ProxyMetadata المقابلة لها.

© حقوق النشر Kovid Goyal. آخر تحديث في يونيو 20, 2025.