Документація з програмного інтерфейсу для роботи з додатками

Визначає різноманітні абстрактні базові класи, з яких можна утворювати підкласи для створення потужних додатків. Корисні класи:

Додаток

class calibre.customize.Plugin(plugin_path)[source]

Додаток до calibre. Корисні учасники:

  • self.plugin_path: Зберігає шлях до файла ZIP, шо містить
    цей додаток або None, якщо це вбудований додаток
  • self.site_customization: зберігає введений рядок налаштовування
    користувачем.

Методи, які слід перевизначити у підкласах:

Корисні методи:

supported_platforms = []

Список платформ, на яких працює додаток. Приклад: ['windows', 'osx', 'linux']

name = u'Trivial Plugin'

Назва цього додатка. Щоб додаток працював, вам слід вказати якусь назву, не просто Trivial Plugin.

version = (1, 0, 0)

Версія цього додатка у форматі кортежу з трьох чисел (основний номер, додатковий номер, модифікація)

description = u'\u041d\u0435 \u0440\u043e\u0431\u0438\u0442\u044c \u0430\u0431\u0441\u043e\u043b\u044e\u0442\u043d\u043e \u043d\u0456\u0447\u043e\u0433\u043e'

Короткий рядок із описом призначення додатка

author = u'\u041d\u0435\u0432\u0456\u0434\u043e\u043c\u0438\u0439'

Автор цього додатка

priority = 1

Якщо для обробки певного типу файлів передбачено декілька додатків, додатки будуть запускатися за зменшенням пріоритетності, тобто першими буде запущено додатки з вищою пріоритетністю. Найвищою можливою пріоритетністю є sys.maxsize. Типовою пріоритетністю є 1.

minimum_calibre_version = (0, 4, 118)

Цей додаток потребує більш ранньої версії Calibre

can_be_disabled = True

Якщо матиме значення False, користувач не зможе вимкнути цей додаток. Користуйтеся із осторогою.

type = u'\u041e\u0441\u043d\u043e\u0432\u043d\u0435'

Тип цього додатка. Використовується для розподілу додатків за категоріями у графічному інтерфейсі програми

initialize()[source]

Викликається один раз під час ініціалізації додатків calibre. Додатки повторно ініціалізуватимуться кожного разу, коли додаватиметься новий додаток. Також зауважте, що якщо додаток запускається у робочому процесі, наприклад для додавання книг, додаток ініціалізуватиметься для кожного нового процесу обробки.

Тут виконується будь-яка специфічна для додатків ініціалізація, зокрема видобування ресурсів з файла ZIP додатка. Шлях до файла ZIP доступний як self.plugin_path.

Зауважте, що на цьому етапі self.site_customization є недоступним.

config_widget()[source]

Реалізуйте цей метод і save_settings() у вашому додатку, щоб скористатися нетиповим діалоговим вікном налаштування, а не покладатися на типове налаштовування на основі рядків.

Цей метод, якщо його реалізовано, має повертати QWidget. Віджет може мати необов’язковий метод validate(), який не приймає аргументів і викликається одразу після натискання користувачем кнопки «Гаразд». Зміни застосовуються, якщо і лише якщо метод повертає True.

Якщо з певної причини ви не змогли виконати налаштовування до цього часу, повернути кортеж з двох рядків (повідомлення, подробиці), ці дані буде показано як діалогове вікно попередження користувачеві, процес буде перервано.

save_settings(config_widget)[source]

Зберегти визначені користувачем за допомогою config_widget параметри.

Параметри:config_widget – Віджет, який повертається config_widget().
do_user_config(parent=None)[source]

Цей метод показує діалогове вікно налаштувань цього додатка. Повертає True, якщо користувач натискає кнопку «Гаразд», і False, якщо ні. Зміни буде застосовано автоматично.

load_resources(names)[source]

Якщо цей додаток постачається у форматі файла 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)[source]

Повертає рядок із довідкою щодо налаштовування цього додатка. Типово, надсилає сигнал NotImplementedError, який позначає, що додаток не потребує налаштовування.

Якщо ви повторно реалізуєте цей метод у вашому підкласі, додаток проситиме користувача ввести рядок для налаштовування цього додатка. Доступ до рядка налаштовування можна буде отримати у формі self.site_customization.

Налаштовуванням місця може бути будь-яким, наприклад, шлях до виконуваного файла на комп’ютері користувача.

Параметри:gui – Якщо True, повертати довідку у форматі HTML, якщо ні, повертати довідку у простому текстовому форматі.
temporary_file(suffix)[source]

Повертає файлоподібний об’єкт, який є тимчасовим файлом у файловій системі. Цей файл залишатиметься доступним навіть після його закриття. Файл буде вилучено під час завершення роботи інтерпретатора коду. Скористайтеся учасником name повернутого об’єкта, щоб отримати доступу до повного шляху до створеного тимчасового файла.

Параметри:suffix – Суфікс назви тимчасових файлів.
cli_main(args)[source]

Цей метод є основною точкою входу до інтерфейсу командного рядка додатка. Викликається, коли користувач віддає таку команду: calibre-debug -r «Назва додатка». Усі передані аргументи будуть зберігатися у змінній args.

FileTypePlugin

class calibre.customize.FileTypePlugin(plugin_path)[source]

Основа: calibre.customize.Plugin

Додаток, який пов’язано із певним набором типів файлів.

file_types = set([])

Набір типів файлів, для яких слід запускати додаток. Скористайтеся «*», якщо додаток слід запускати для усіх файлів. Приклад: {'lit', 'mobi', 'prc'}

on_import = False

Якщо True, цей додаток запускається, якщо до бази даних додаються книги.

on_postimport = False

Якщо True, цей додаток запускається після додавання книг до бази даних. У цьому випадку викликаються методи postimport і postadd додатка.

on_preprocess = False

Якщо True, цей додаток запускається безпосередньо перед перетворенням.

on_postprocess = False

Якщо True, цей додаток запускається після перетворення для обробки остаточного файла, який буде створено додатку виведення даних перетворення.

run(path_to_ebook)[source]

Запустити додаток. Має бути реалізовано у підкласах. Має вносити усі потрібні зміни до електронної книги і повертати абсолютний шлях до файла зміненої книги. Якщо вносити зміни не потрібно. Якщо станеться помилка, має повідомляти про виключення (Exception). Типова реалізація просто повертає шлях до початкового файла електронної книги. Зауважте, що шлях до початкового файла (до запуску будь-яких додатків), доступний як self.original_path_to_file.

Змінений файл електронної книги має бути створено за допомогою методу temporary_file().

Параметри:path_to_ebook – Повний шлях до електронної книги.
Повертає:Повний шлях до зміненої електронної книги.
postimport(book_id, book_format, db)[source]

Викликається після імпортування, тобто після того, як файл книги було додано до бази даних. Зауважте, що цей метод відрізняється від postadd(), який викликається, коли запис книги створюється вперше. Цей метод викликається кожного разу, коли до запису книги додається новий файл. Корисний для внесення змін до запису книги на основі вмісту нового доданого файла.

Параметри:
  • book_id – ідентифікатор доданої книжки в базі даних.
  • book_format – Тип файла доданої книги.
  • db – База даних бібліотеки.
postadd(book_id, fmt_map, db)[source]

Викликається після додавання (add), тобто після того, як книгу буде додано до бази даних. Зауважте, що цей метод відрізняється від postimport(), який викликається після додавання окремого файла до запису книги. postadd() викликається, лише якщо вперше створюється увесь запис книги, можливо з декількома файлами книги. Корисно, якщо вам потрібно внести зміни до запису книги у базі даних, якщо книгу вперше додано до calibre.

Параметри:
  • book_id – ідентифікатор доданої книжки в базі даних.
  • fmt_map – Прив’язка формату файла до шляху, з якого було додано цей формат файла. Зауважте, що цей шлях може і не вказувати на наявний файл, оскільки іноді файли додаються як потоки даних. У такому випадку значення шляху може бути фіктивним або таким, якого не існує.
  • db – База даних бібліотеки

Додати роботи з метаданими

class calibre.customize.MetadataReaderPlugin(*args, **kwargs)[source]

Основа: calibre.customize.Plugin

Додаток, який реалізує читання метаданих із файлів певного набору типів.

file_types = set([])

Набір типів файлів, для яких слід запускати додаток. Приклад: set(['lit', 'mobi', 'prc'])

get_metadata(stream, type)[source]

Повертає метадані для файла, представленого потоком даних (файлоподібним об’єктом, для якого передбачено підтримку читання). Надсилає повідомлення щодо виключення, якщо сталася помилка із вхідними даними.

Параметри:type – тип файла. Гарантовано є одним із записів у file_types.
Повертає:A calibre.ebooks.metadata.book.Metadata object
class calibre.customize.MetadataWriterPlugin(*args, **kwargs)[source]

Основа: calibre.customize.Plugin

Додаток, який реалізує читання метаданих із файлів певного набору типів.

file_types = set([])

Набір типів файлів, для яких слід запускати додаток. Приклад: set(['lit', 'mobi', 'prc'])

set_metadata(stream, mi, type)[source]

Встановлює метадані для файла, представленого потоком даних (файлоподібним об’єктом, для якого передбачено підтримку читання). Надсилає повідомлення щодо виключення, якщо сталася помилка із вхідними даними.

Параметри:
  • type – тип файла. Гарантовано є одним із записів у file_types.
  • mi – A calibre.ebooks.metadata.book.Metadata object

Додатки роботи з каталогом

class calibre.customize.CatalogPlugin(plugin_path)[source]

Основа: calibre.customize.Plugin

Додаток, який реалізує засіб створення каталогу.

file_types = set([])

Вивести тип файлів, для яких слід запускати додаток. Приклад: „epub“ або „xml“

cli_options = []

Параметри обробки інтерфейсу командного рядка, специфічні для цього додатка, оголошені як namedtuple. Параметр:

from collections import namedtuple Option = namedtuple(„Option“, „option, default, dest, help“) cli_options = [Option(„–catalog-title“, default = „My Catalog“, dest = „catalog_title“, help = (_(„Title of generated catalog. nDefault:“) + » „» + „%default“ + «“»))] cli_options parsed in calibre.db.cli.cmd_catalog:option_parser()

initialize()[source]

Якщо додаток не є вбудованим, копіює файли .ui і .py з файла ZIP до $TMPDIR. Вкладку буде створено динамічно і додано до діалогового вікна параметрів каталогу у calibre.gui2.dialogs.catalog.py:Catalog

run(path_to_output, opts, db, ids, notification=None)[source]

Запускає додаток. Має бути реалізовано у підкласах. Має створити каталог у форматі, вказаному у file_types, повернувши абсолютний шлях до створеного файла каталогу. Якщо станеться помилка, має надіслати сигнал Exception.

Створений файл каталогу має бути створено за допомогою методу temporary_file().

Параметри:
  • path_to_output – Абсолютний шлях до створеного файла каталогу.
  • opts – Словник аргументів ключових слів
  • db – Об’єкт LibraryDatabase2

Додатки отримання метаданих

class calibre.ebooks.metadata.sources.base.Source(*args, **kwargs)[source]

Основа: calibre.customize.Plugin

capabilities = frozenset([])

Набір можливостей, підтримуваних цим додатком. Корисні можливості: «identify», «cover»

touched_fields = frozenset([])

Список полів метаданих, які потенційно може бути отримано цим додатком під час фази ідентифікації.

has_html_comments = False

Встановіть значення True, якщо ваш додаток повертає форматовані у HTML коментарі.

supports_gzip_transfer_encoding = False

Встановлення для цього параметра значення True означає, що об’єкт навігатора (browser) вказуватиме, що у ньому передбачено підтримку передавання даних зі стисканням gzip. Це може пришвидшити отримання даних, але варто спочатку пересвідчитися, що джерело справді може надавати дані у форматі gzip належним чином.

ignore_ssl_errors = False

Встановіть значення True, якщо помилки, пов’язані із сертифікатами HTTPS, слід ігнорувати для цього джерела.

cached_cover_url_is_reliable = True

Кешовані адреси зображень обкладинок іноді можуть стати неактуальними (тобто обкладинка стає недоступно до отримання або повернуте зображення є непридатним до використання). Якщо таке трапляється часто з цим джерелом, встановіть значення 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()[source]

Повертає False, якщо ваш додаток має бути налаштовано перед використанням. Наприклад, йому потрібне ім’я користувача, пароль або ключ до програмного інтерфейсу.

get_author_tokens(authors, only_first_author=True)[source]

Отримує список авторів і повертає список ключів, корисних для створення запитів щодо пошуку із логікою «І». Ця функція намагається повернути ключі у порядку «ім’я по-батькові прізвище», припускаючи, що якщо у імені автора є кома, ім’я записано у формі «прізвище, решта імені».

get_title_tokens(title, strip_joiners=True, strip_subtitle=False)[source]

Отримує заголовок і повертає список ключів, які потрібні для запиту щодо пошуку з логікою І. Включає з’єднання (необов’язково) і пунктуацію.

split_jobs(jobs, num)[source]

Поділити список завдань на не більше за num груп, наскільки можна однаково.

test_fields(mi)[source]

Повертає перше поле з self.touched_fields, яке є нулем у об’єкті mi.

clean_downloaded_metadata(mi)[source]

Викличте цей метод у вашому методі identify додатка для нормалізації метаданих до передавання об’єкта Metadata до result_queue. Ви, звичайно ж, можете скористатися нетиповим алгоритмом, який відповідатиме вашому джерелу метаданих.

get_book_url(identifiers)[source]

Повертає триелементний кортеж або None. Триелементний кортеж записується у такому форматі: (тип ідентифікатора, значення ідентифікатора, адреса). Адресою є адреса (URL) книги, що визначається за ідентифікаторами у цьому джерелі. Тип ідентифікатора та значення ідентифікатора визначають ідентифікатор, що відповідає адресі. Адреса має бути придатною для переходу за нею користувача за допомогою програми для перегляду сторінок інтернету. Її призначено для створення придатного до натискання посилання для відвідання користувачем сторінки книги у цьому джерелі. Якщо адреси не буде знайдено, буде повернуто None. Цей метод має працювати швидко і послідовно, отже, вам слід реалізовувати його, лише якщо можна побудувати адресу на основі відомих ідентифікаторів з бази даних.

get_book_url_name(idtype, idval, url)[source]

Повернути назву у зручному для читанні форматі із повернутого значення get_book_url().

get_book_urls(identifiers)[source]

Перевизначте цей метод, якщо для цієї книги слід повернути декілька адрес. Повертає список з кортежів, що складаються з 3 значень. Типово, цей метод просто викликає get_book_url().

get_cached_cover_url(identifiers)[source]

Повертає кешовану адресу зображення обкладинки для книги, вказаної словником ідентифікаторів, або None, якщо такої адреси не існує.

Зауважте, що цей метод має повертати лише перевірені адреси, тобто не ті адреси, використання яких може призвести до використання типового зображення обкладинки або які не може бути знайдено.

id_from_url(url)[source]

Обробити адресу і повернути кортеж у форматі (тип_ідентифікатора, значення_ідентифікатора). Якщо адреса не відповідає взірцю для джерела метаданих, повернути None.

identify_results_keygen(title=None, authors=None, identifiers={})[source]

Повертає функцію, яка використовується для створення ключа, який може упорядковувати об’єкти Metadata за відповідністю вказаному критерію пошуку (назві, авторам, ідентифікаторам).

Ці ключі використовуються для упорядковування результатів виклику identify().

Докладніше про типовий алгоритм можна дізнатися з документації до InternalMetadataCompareKeyGen. Повторно реалізуйте цю функцію у вашому додатку, якщо типовий алгоритм є непридатним.

identify(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30)[source]

Ідентифікувати книжку за назвою/автором/isbn

Якщо вказано ідентифікатори і не знайдено відповідників, а це джерело метаданих не зберігає усіх пов’язаних ідентифікаторів (наприклад, усіх ISBN книги), цей метод має повторити спробу на основі лише даних про назву та автора (припускаючи, що ці дані вказано).

Якщо це джерело метаданих також надає зображення обкладинок, адресу обкладинки має бути кешовано так, щоб наступний виклик функції отримання даних з тими самими даними щодо ISBN або спеціального ідентифікатор не потребував повторного отримання адреси обкладинки. Для цього використовуйте програмний інтерфейс кешування.

Усі об’єкти Metadata, які додаються до result_queue за допомогою цього методу, повинні мати атрибут source_relevance, тобто ціле число, яке позначає порядок, у якому слід повертати результати з цього джерела метаданих для цього запиту. Це ціле число буде використано методом compare_identify_results(). Якщо порядок не є важливим, встановіть нульове значення для усіх результатів.

Переконайтеся, що усі дані щодо прив’язки до обкладинки або isbn буде кешовано до того, як об’єкт Metadata буде передано до result_queue.

Параметри:
  • log – Об’єкт журналу. Використовуйте його для виведення діагностичної інформації і даних щодо помилок.
  • result_queue – Черга результатів, до неї додаються результати. Кожен результат є об’єктом Metadata.
  • abort – Якщо abort.is_set() повертає True, перервати подальшу обробку і повернути керування якомога швидше.
  • title – Назва (заголовок) книги, може бути None
  • authors – Список авторів книги, може бути None
  • identifiers – Словник інших ідентифікаторів, найчастіше {„isbn“:„1234…“}
  • timeout – Час очікування у секундах. Жоден запит до мережі має бути виконано протягом часу, який визначається часом очікування.
Повертає:

None, якщо помилок не було. Якщо сталися помилки, буде виведено представлення unicode повідомлення про помилку для показу користувачеві.

download_cover(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30, get_best_cover=False)[source]

Отримати обкладинку і додати її до result_queue. Параметри усі мають те саме значення, що і для identify(). Додати (self, cover_data) до result_queue.

Якщо можна, цей метод має використовувати кешовані адреси обкладинок. Якщо кешованих даних немає, більшість додатків просто викликають identify і використовують її результати.

Якщо параметр get_best_cover має значення True і цей додаток може отримувати декілька обкладинок, він має отримувати лише «найкращу».

class calibre.ebooks.metadata.sources.base.InternalMetadataCompareKeyGen(mi, source_plugin, title, authors, identifiers)[source]

Створює ключ упорядковування для порівняння відповідності об’єктів Metadata за заданим запитом щодо пошуку. Використовується лише для порівняння результатів з одного джерела метаданих, а не з різних джерел.

Ключ упорядковування забезпечує відповідність упорядковування за зростанням упорядковуванню за спаданням відповідності.

Алгоритм:

  • Надавати перевагу результатам, які мають принаймні один ідентифікатор, який збігається із запитом.
  • Пріоритет результатів із кешованою адресою зображення обкладинки
  • Пріоритет результатів, у яких усі поля заповнено
  • Надавати перевагу результатам тією самою мовою, що і поточна мова інтерфейсу користувача.
  • Пріоритет результатів, які повністю збігаються за назвою із запитом
  • Надавати перевагу результатам із довшими коментарями (понад 10% довшими)
  • Використовувати відповідність результатів, яку повідомляє засіб пошуку джерела метаданих
    engine

Додатки перетворення даних

class calibre.customize.conversion.InputFormatPlugin(*args)[source]

Основа: calibre.customize.Plugin

Додатки InputFormatPlugins відповідають за перетворення документів у набір даних HTML+OPF+CSS+інше. Результати перетворення мають зберігатися у кодуванні UTF-8. Основна дія відбувається у convert().

file_types = set([])

Набір типів файлів, для яких слід запускати додаток. Приклад: set(['azw', 'mobi', 'prc'])

is_image_collection = False

Якщо має значення True, цей додаток вхідних даних створює збірку зображень, по одному на файл HTML. Можна встановлювати під час роботи додатка, у методі convert, якщо файли вхідних даних можуть бути як збірками зображень, так і збірками без зображень. Якщо ви встановите значення True, вам слід реалізувати метод get_images(), який повертатиме список зображень.

core_usage = 1

Кількість ядер процесора, які використовуються цим додатком. Значення «-1» означає, що слід використовувати усі доступні ядра.

for_viewer = False

Якщо встановлено значення True, додаток обробки вхідних даних виконуватиме спеціальну обробку, щоб зробити виведені дані придатними для перегляду.

output_encoding = u'utf-8'

Кодування, у якому цей додаток створює файли. Значення None означає, що кодування не визначено, і його слід визначити окремо.

common_options = set([<calibre.customize.conversion.OptionRecommendation object>])

Параметри є спільними для усіх додатків вхідних форматів даних. Не перевизначайте їх у підкласах. Замість цього, скористайтеся options. Кожен параметр має бути екземпляром OptionRecommendation.

options = set([])

Параметри для налаштовування поведінки цього додатка. Кожен параметр має бути екземпляром OptionRecommendation.

recommendations = set([])

Набір кортежів з 3 елементів у формі (назва_параметра, рекомендоване_значення, рівень_рекомендування)

get_images()[source]

Повернути список абсолютних шляхів до зображень, якщо цей вхідні дані є збіркою зображень. Список зображень формується у тому самому порядку, що і у вмісті та таблиці змісту.

convert(stream, options, file_ext, log, accelerators)[source]

Цей метод має бути реалізовано у підкласах. Має повертати шлях до створеного файла OPF або екземпляр OEBBook. Усі виведені дані мають міститися у поточному каталозі. Якщо цей додаток створює файли поза поточним каталогом, їх має бути вилучено або позначено для вилучення до повернення керування цим методом.

Параметри:
  • stream – Файл як об’єкт, який містить дані файла вхідних даних.
  • options – Параметри для налаштовування процесу перетворення. Гарантовано має атрибути, що відповідають усім параметрам, оголошеним цим додатком. Крім того, має атрибут verbose, який приймає інтегральні дані від нуля. Більші значення атрибута означають докладніше виведення діагностичних даних. Іншим корисним атрибутом є input_profile, який є екземпляром calibre.customize.profiles.InputProfile.
  • file_ext – Суфікс назви (без крапки) файла вхідних даних. Гарантовано має належати набору значень file_types, підтримку яких передбачено у додатку.
  • log – Об’єкт calibre.utils.logging.Log. Усе виведення має використовувати цей об’єкт.
  • accelarators – Словник різноманітних даних, доступ до якого має бути простим для додатка вхідних даних. Пришвидшує наступні етапи перетворення.
postprocess_book(oeb, opts, log)[source]

Викликається для уможливлення виконання додатком вхідних даних остаточної обробки після основного етапу обробки даних книги.

specialize(oeb, opts, log, output_fmt)[source]

Викликається для того, щоб надати змогу додатку спеціалізувати оброблену книгу для певного формату виведення даних. Викликається після postprocess_book і перед будь-якими перетвореннями, які виконуються над обробленою книгою.

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[source]

Викликається для створення віджета, який використовується для налаштовування цього додатка у графічному інтерфейсі calibre. Віджет має бути екземпляром класу PluginWidget. Приклади можна знайти у вбудованих додатках обробки вхідних даних.

class calibre.customize.conversion.OutputFormatPlugin(*args)[source]

Основа: calibre.customize.Plugin

OutputFormatPlugins відповідають за перетворення документа OEB (OPF+HTML) на остаточну електронну книгу.

Можна припускати, що документ OEB має кодування UTF-8. Основна дія відбувається у convert().

file_type = None

Тип файлів (суфікс назви без крапки), до якого виводить дані цей додаток

common_options = set([<calibre.customize.conversion.OptionRecommendation object>])

Параметри є спільними для усіх додатків вхідних форматів даних. Не перевизначайте їх у підкласах. Замість цього, скористайтеся options. Кожен параметр має бути екземпляром OptionRecommendation.

options = set([])

Параметри для налаштовування поведінки цього додатка. Кожен параметр має бути екземпляром OptionRecommendation.

recommendations = set([])

Набір кортежів з 3 елементів у формі (назва_параметра, рекомендоване_значення, рівень_рекомендування)

convert(oeb_book, output, input_plugin, opts, log)[source]

Обробити вміст oeb_book (екземпляра calibre.ebooks.oeb.OEBBook) до файла, вказаного параметром виведення.

Параметри:
  • output – Файлоподібний об’єкт або рядок. Якщо це рядок, він вважається шляхом до каталогу, який може і не існувати. Додаток виведення даних має записати виведені дані до цього каталогу. Якщо це файлоподібний об’єкт, додаток виведення має записати свої дані до цього файла.
  • input_plugin – Додаток обробки вхідних даних, який було використано на початку конвеєра перетворення.
  • opts – Параметри перетворення. Гарантовано мають атрибути, які відповідають OptionRecommendations цього додатка.
  • log – Засіб журналювання. За допомогою цього можна виводити діагностичні та інші повідомлення.
specialize_options(log, opts, input_fmt)[source]

Можна скористатися для зміни значень параметрів перетворення, які використовуються у конвеєрі перетворення.

specialize_css_for_output(log, opts, item, stylizer)[source]

Можна використовувати для внесення змін до css під час процедури спрощення CSS.

Параметри:
  • item – Запис (файл HTML), який обробляється.
  • stylizer – Об’єкт Stylizer, який містить спрощені стилі для запису. Отримати стиль для будь-якого елемента можна за допомогою stylizer.style(елемент).
gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[source]

Викликається для створення віджета, який використовується для налаштовування цього додатка у графічному інтерфейсі calibre. Віджет має бути екземпляром класу PluginWidget. Приклади можна знайти у вбудованих додатках для виведення даних.

Драйвери пристроїв

Базовим класом для всіх драйверів пристроїв є DevicePlugin. Втім, якщо пристрій представляє себе операційній системі як диск USBMS, вам слід використовувати замість нього клас USBMS, оскільки у ньому реалізовано усю логіку, потрібну для цього типу пристроїв.

class calibre.devices.interface.DevicePlugin(plugin_path)[source]

Основа: calibre.customize.Plugin

Визначає інтерфейс, який має бути реалізовано модулями обробки, які обмінюються даними з пристроєм для читання електронних книг.

FORMATS = [u'lrf', u'rtf', u'pdf', u'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 = [u'title', u'authors', u'collections']

Визначає, чи може бути встановлено метадані для книг за допомогою графічного інтерфейсу.

CAN_DO_DEVICE_DB_PLUGBOARD = False

Визначає, чи може пристрій обробляти набори метаданих device_db.

path_sep = '/'

Роздільник у шляху для шляхів до книг на пристрої

icon = u'/home/kovid/work/calibre/resources/images/reader.png'

Піктограма для цього пристрою

UserAnnotation

синонім 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() після завантаження списків книг для отримання даних щодо диска (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“:title, „msg“:msg, „det_msg“:detailed_msg}, щоб програма calibre показувала повідомлення користувачеві після певних зворотних викликів (у поточній версії лише upload_books). Спробуйте не набридати користувачеві повідомленнями. Значення цієї змінної перевірятиметься після кожного зворотного виклику, тому вам слід встановлювати його, лише якщо це справді потрібно.

is_usb_connected(devices_on_system, debug=False, only_presence=False)[source]

Повертає True, device_info, якщо пристрій, який обробляється цим додатком, з’єднано з комп’ютером.

Параметри:devices_on_system – Поточний список з’єднаних пристроїв
detect_managed_devices(devices_on_system, force_refresh=False)[source]

Викликається, лише якщо 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)[source]

Викликається, лише якщо MANAGES_DEVICE_PRESENCE має значення True.

Має записувати дані щодо пристроїв, які виявлено у системі, до виведення, яке є файлоподібним об’єктом.

Має повернути True, якщо пристрій було виявлено і успішно відкрито. Якщо цього не відбулося, має повернути False.

reset(key=u'-1', log_packets=False, report_progress=None, detected_device=None)[source]
Параметри:
  • key – Ключ для розблокування пристрою
  • log_packets – Якщо true, потік пакетів на пристрій і з пристрою записується до журналу.
  • report_progress – Функція, яка викликається із відсотком виконання (числом від 0 до 100) для виконання різних завдань. Якщо викликано з -1, програма вважатиме, що завдання не має даних щодо поступу виконання.
  • detected_device – Дані щодо пристрою від засобу сканування пристроїв
can_handle_windows(usbdevice, debug=False)[source]

Необов’язковий метод для виконання подальших перевірок для пристрою з метою переконатися, що цей драйвер може з ним працювати. Якщо це не так, має повертати False. Цей метод викликається лише після встановлення відповідності виробника, ідентифікаторів продукту та bcd, отже він може виконувати доволі тривалі за часом перевірки. Типова реалізація завжди повертає True. Цей метод викликається лише у Windows. Див. також can_handle().

Зауважте, що для пристроїв на основі USBMS це метод типово делегується can_handle(). Отже, вам слід лише перевизначити can_handle() у вашому підкласі USBMS.

Параметри:usbdevice – Пристрій USB (usbdevice) у форматі, який повертає calibre.devices.winusb.scan_usb_devices()
can_handle(device_info, debug=False)[source]

Версія Unix can_handle_windows().

Параметри:device_info – Є кортежем (vid, pid, bcd, виробник, продукт, серійний номер)
open(connected_device, library_uuid)[source]

Виконати усі специфічні для пристрою дії з ініціалізації. Викликається після виявлення пристрою, але перед усіма іншими функціями, які обмінюються даними з пристроєм. Приклад: для пристроїв, які представляються як сховища даних із інтерфейсом USB, цей метод має відповідати за монтування пристрою або, якщо пристрій змонтовано у автоматичному режимі, за пошук точки монтування. Метод calibre.devices.usbms.device.Device.open() містить реалізацію цієї функції і має слугувати добрим прикладом для реалізації доступу до сховищ даних із інтерфейсом USB.

Цей метод може викликати виключення OpenFeedback для показу повідомлення користувачеві.

Параметри:
  • connected_device – The device that we are trying to open. It is a tuple of (vendor id, product id, bcd, manufacturer name, product name, device serial number). However, some devices have no serial number and on Windows only the first three fields are present, the rest are None.
  • library_uuid – UUID поточної бібліотеки calibre. Може мати значення None, якщо бібліотеки немає (наприклад, якщо використано з командного рядка).
eject()[source]

Демонтувати і вилучити запис пристрою з операційної системи. Наявність завдань з графічним інтерфейсом, які продовжують виконувати завдання з пристроєм, при цьому не перевіряється.

ЗАУВАЖЕННЯ: цей метод не можна викликати у тому самому потоці виконання, що і решта методів роботи з пристроями.

post_yank_cleanup()[source]

Викликається, якщо користувач від’єднує пристрій без його вилучення з системи.

set_progress_reporter(report_progress)[source]

Встановлює функцію для надання даних щодо поступу виконання.

Параметри:report_progress – Функція, яка викликається із відсотком виконання (числом від 0 до 100) для виконання різних завдань. Якщо викликано з -1, програма вважатиме, що завдання не має даних щодо поступу виконання.
get_device_information(end_session=True)[source]

Опитує пристрій щодо даних про нього. Див. L{DeviceInfoQuery}.

Повертає:(назва пристрою, версія пристрою, версія програмного забезпечення на пристрої, тип MIME) Кортеж даних може містити п’ятий елемент, який є словником із даними щодо диска. Див. приклад у usbms.driver.
get_driveinfo()[source]

Повертає словник driveinfo. Зазвичай, викликається з get_device_information(), але якщо завантаження driveinfo є повільним для цього драйвера, він має встановити SLOW_DRIVEINFO. У цьому випадку, функцію буде викликано calibre після завантаження списків книг. Зауважте, що метод викликається не у потоці обробки пристрою, отже, драйвер має кешувати дані щодо диска у методі books(), а ця функція має повернути кешовані дані.

card_prefix(end_session=True)[source]

Повертає двоелементний список префіксів до шляхів на картках. Якщо картки немає, для префікса картки буде встановлено значення None. Приклади: („/місце“, „/місце2“) (None, „місце2“) („місце“, None) (None, None)

total_space(end_session=True)[source]
Отримати загальний об’єм доступного місця на точках монтування:
  1. Основна пам’ять
  2. Картка пам’яті A
  3. Картка пам’яті B
Повертає:Триелементних список із загальним об’ємом у байтах для (1, 2, 3). Якщо за якоюсь із адрес пристрою немає, має повернути 0.
free_space(end_session=True)[source]
Отримати об’єм вільного місця на точках монтування:
  1. Основна пам’ять
  2. Картка A
  3. Картка B
Повертає:Триелементних список із вільним об’ємом у байтах для (1, 2, 3). Якщо за якоюсь із адрес пристрою немає, має повернути -1.
books(oncard=None, end_session=True)[source]

Повертає список електронних книг на пристрої.

Параметри:oncard – Якщо «carda» або «cardb», повертає список електронних книг на вказаній картці пам’яті. Якщо інше значення, повертає список електронних книг у основній пам’яті пристрою. Якщо вказано картку, але на картці немає книг, повертає порожній список.
Повертає:BookList.
upload_books(files, names, on_card=None, end_session=True, metadata=None)[source]

Вивантажити список книг на пристрій. Якщо якийсь файл вже існує на пристрої, його буде замінено. Цей метод має повідомляти про FreeSpaceError, якщо на пристрої недостатньо вільного місця. Текст FreeSpaceError має містити слово «card», якщо on_card має значення, відмінне від None. Інакше, він має містити слово «memory».

Параметри:
  • files – Список шляхів
  • names – Список назв файлів, які повинні мати книги після вивантаження на пристрій. len(names) == len(files)
  • metadata – Якщо має значення, яке є відмінним від None, є списком об’єктів Metadata. Ідея полягає у використанні метаданих для визначення, куди на пристрої слід зберегти книгу. len(metadata) == len(files). Окрім типового зображення обкладинки (шляху до зображення), може також існувати атрибут мініатюри, який матиме вищий пріоритет. Атрибут мініатюри записується у форматі (ширина, висота, дані обкладинки у форматі jpeg).
Повертає:

Список триелементни кортежів. Список призначено для передавання до add_books_to_metadata().

classmethod add_books_to_metadata(locations, metadata, booklists)[source]

Додає адреси до списків книг. Ця функція не повинна обмінюватися даними з пристроєм.

Параметри:
  • locations – Результати виклику L{upload_books}
  • metadata – Список об’єктів Metadata, той самий, що і для upload_books().
  • booklists – Кортеж, що містить результати викликів (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=“cardb“)`).
delete_books(paths, end_session=True)[source]

Вилучити книги за вказаними шляхами на пристрої.

classmethod remove_books_from_metadata(paths, booklists)[source]

Вилучити книги зі списку метаданих. Ця функція не повинна обмінюватися даними з пристроєм.

Параметри:
  • paths – шляхи до книг на пристрої.
  • booklists – Кортеж, що містить результати викликів (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=“cardb“)`).
sync_booklists(booklists, end_session=True)[source]

Оновити метадані на пристрої.

Параметри:booklists – Кортеж, що містить результати викликів (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=“cardb“)`).
get_file(path, outfile, end_session=True)[source]

Прочитати файл з адресою path на пристрої і записати його вміст до outfile.

Параметри:outfile – файлових об’єкт, наприклад sys.stdout, або результат виклику open().
classmethod config_widget()[source]

Має повернути QWidget. QWidget містить параметри для інтерфейсу пристрою.

classmethod save_settings(settings_widget)[source]

Має зберегти параметри на диск. Отримує віджет, створений у config_widget(), із зберігає усі параметри на диск.

classmethod settings()[source]

Має повернути об’єкт opts. Об’єкт opts повинен мати принаймні один атрибут format_map, який є упорядкованим списком форматів для пристрою.

set_plugboards(plugboards, pb_func)[source]

надає драйверу поточний набір метаданих та функцію для вибору певного набору. Цей метод викликається безпосередньо перед add_books і sync_booklists.

pb_func є придатною до виконання функцією із таким підписом:
def pb_func(назва_пристрою, формат, засоби обробки метаданих)

Ви передаєте функції назву поточного пристрою (як назву класу або як DEVICE_PLUGBOARD_NAME), формат, який вам потрібен («справжній» формат або «device_db»), і засоби обробки метаданих (ви вказали їх за допомогою set_plugboards там, де ви отримали цей метод).

Повертає:None або окремий екземпляр засобу обробки метаданих.
set_driveinfo_name(location_code, name)[source]

Встановити назву пристрою у файлі driveinfo у значення «name». Цей параметр не змінюється, аж доки файл не буде повторно створено або його назву не буде знову змінено.

Недискові пристрої мають реалізовувати цей метод на основі кодів розташування, які повертаються методом get_device_information().

prepare_addable_books(paths)[source]

За вказаним списком шляхів повертає інший список шляхів. Ці шляхи вказують на придатні до додавання версії книг.

Якщо під час приготування книги сталася помилка, замість шляху позиція книги у повернутому списку має бути триелементним кортежем: (початковий шлях, екземпляр виключення, трасування)

startup()[source]

Викликається, коли calibre розпочинає роботу з пристроєм. Виконує усі потрібні дії з ініціалізації. Зауважте, що можна створити декілька екземплярів класу, отже __init__ можна викликати декілька разів, але викликатиме цей метод лише один екземпляр. Цей метод викликається у потоці виконання пристрою, а не у потоці графічного інтерфейсу.

shutdown()[source]

Викликається, коли calibre завершує роботу за наказом користувача або під час приготувань до перезапуску. Виконує правильне завершення усіх завдань. Цей метод викликається у потоці обробки пристрою, а не у потоці роботи графічного інтерфейсу користувача.

get_device_uid()[source]

Має повертати унікальний ідентифікатор для поточного з’єднаного пристрою (викликається одразу після успішного виклику open()). Вам слід реалізувати цей метод, якщо ви встановили ASK_TO_ALLOW_CONNECT = True

ignore_connected_device(uid)[source]

Програма має у майбутньому ігнорувати пристрій, вказаний за uid (результат виклику get_device_uid()). Вам слід реалізувати цей метод, якщо ви встановлюєте ASK_TO_ALLOW_CONNECT = True. Зауважте, що ця функція викликається негайно після open(). Отже, якщо open() кешовано якийсь стан, драйвер має скинути систему до цього стану.

get_user_blacklisted_devices()[source]

Повертає відображення uid пристрою на зручну для користування назву для усіх пристроїв, які користувач наказав ігнорувати.

set_user_blacklisted_devices(devices)[source]

Встановлює список uid пристроїв, які мають ігноруватися цим драйвером.

specialize_global_preferences(device_prefs)[source]

Реалізуйте цей метод, якщо ваш пристрій має перевизначати певне налаштування. Вам слід переконатися, що усі виклики, яким потрібно налаштування, яке може бути перевизначено, використовують device_prefs[„щось“], а не prefs[„щось“]. Ваш метод має викликати device_prefs.set_overrides(налаштування=значення, налаштування=значення, …). У поточній версії використовується для керування метаданими (prefs[„manage_device_metadata“])

set_library_info(library_name, library_uuid, field_metadata)[source]

Реалізуйте цей метод, якщо вам потрібна інформація щодо поточної бібліотеки calibre. Цей метод викликається під час запуску і коли бібліотека calibre змінюється під час з’єднання з пристроєм.

is_dynamically_controllable()[source]

Викликається засобом керування пристроями під час запуску додатків. Якщо цей метод повертає рядок, то: а) у ньому передбачено підтримку інтерфейсу динамічного керування засобу керування пристроями; і б) цю назву слід використовувати під час обміну даними з додатком.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

start_plugin()[source]

Цей метод викликається для запуску додатка. Додаток має розпочати приймання з’єднань зі пристроєм, у який би спосіб він це не робив. Якщо додаток вже приймає з’єднання, ніяких додаткових дій не виконується.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

stop_plugin()[source]

Цей метод викликається для завершення роботи додатка. Після цього додаток має припинити приймання з’єднань і почистити свої сліди у системі. Ймовірно, цей метод має викликати вимикання. Якщо додаток вже не приймає з’єднань, ніяких додаткових дій не виконується.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

get_option(opt_string, default=None)[source]

Повертає значення параметра, вказаного за допомогою opt_string. Цей метод можна викликати, якщо додаток не запущено. Повертає None, якщо вказаного параметра не існує.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

set_option(opt_string, opt_value)[source]

Встановлює значення параметра, вказаного за допомогою opt_string. Цей метод можна викликати, якщо додаток не запущено.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

is_running()[source]

Повертає True, якщо додаток запущено. Якщо додаток не запущено, повертає false.

Цей метод можна викликати у потоці обробки графічного інтерфейсу. Драйвер, який реалізує цей метод, має бути захищено для роботи у потоці.

synchronize_with_db(db, book_id, book_metadata, first_call)[source]

Викликається під час встановлення відповідності книг, коли програма намагається пов’язати книгу на пристрої із книгою у базі даних calibre. Цей метод відповідальний за синхронізацію даних з пристрою із базою даних calibre (якщо це потрібно).

Цей метод має повертати двоелементний кортеж. Першим значенням є набір ідентифікаторів книг calibre, які змінюються, якщо було внесено зміни до бази даних calibre, або None, якщо до бази даних не було внесено змін. Якщо першим значенням є порожня множина, метадані книги на пристрої оновлено на основі метаданих calibre і повернуто на пристрій, але оновлення даних у графічному інтерфейсі для цієї книги не відбулося. Корисно, якщо дані у calibre є правильними, але їх ще слід надіслати на пристрій для читання книг.

Другим значенням є двоелементний кортеж. Перше значення у цьому кортежі визначає, чи слід надсилати формат книги на пристрій. Це значення призначено для перевірки того, що книга на пристрої збігається із книгою у calibre. Це значення має дорівнювати None, якщо немає книг для надсилання, інакше повертає базову назву файла на пристрої (рядок, подібний до щосьтам.epub). Переконайтеся, що до назви файла включено суфікс. Підсистема пристроїв побудує завдання send_books для усіх книг, для яких повернуто значення, що не дорівнюють None. Зауваження: окрім випадку неотримання суфікса назви, назву буде проігноровано тоді, коли на пристрої використовується шаблон для створення назв файлів (такий шаблон використовується на більшості пристроїв). Друге значення у повернутому кортежі позначає, чи є дата для формату майбутньою. Повертає True, якщо це так, інакше повертає False. Calibre показуватиме користувачеві діалогове вікно зі списком усіх книг із датами у майбутньому.

Надзвичайно важливо: цей метод викликається у потоці обробки графічного інтерфейсу. Він має бути безпечним до роботи у потоках щодо потоку засобу керування пристроями.

book_id: ідентифікатор книги у базі даних calibre. book_metadata: об’єкт Metadata для книги, що походить з пристрою. first_call: має значення True, якщо це перший виклик під час синхронізації; False, якщо цей виклик не є першим.

class calibre.devices.interface.BookList(oncard, prefix, settings)[source]

Основа: list

Список книг. Кожен об’єкт Book повинен мати такі поля

  1. title
  2. authors
  3. size (розмір файла книги)
  4. datetime (кортеж даних часу для часового поясу UTC)
  5. path (шлях до файла книги на пристрої)
  6. thumbnail: (може мати значення None) — мініатюра: або рядковий/байтовий об’єкт із даними зображення, або повинен містити атрибут image_path, у якому зберігається абсолютний шлях (у форматі програмної платформи) до зображення.
  7. tags (список рядків, може бути порожнім).
supports_collections()[source]

Повертає True, якщо на пристрої передбачено підтримку збірок для цього списку книг.

add_book(book, replace_metadata)[source]

Додає книгу до списку книг. Призначено для збереження усіх внутрішніх для пристрою метаданих. Повертає True, якщо списки книг слід синхронізувати.

remove_book(book)[source]

Вилучає книгу зі списку книг. Одночасно виправляє усі метадані пристрою.

get_collections(collection_attributes)[source]

Повертає словник збірок, створених з collection_attributes. Кожен запис у словнику має формат «назва збірки:[список книг]»

Список книг упорядковується за назвами, окрім збірок, які створено на основі циклів, у яких для упорядковування використовується series_index.

Параметри:collection_attributes – Список атрибутів об’єкта Book

USB-пристрої великого об’єму

Базовим класом для таких пристроїв є calibre.devices.usbms.driver.USBMS. Цей клас, своєю чергою, успадковує частину своїх функціональних можливостей від своєї основ, документованої нижче. Типовий базовий драйвер на основі USBMS має такий код:

from calibre.devices.usbms.driver import USBMS

class PDNOVEL(USBMS):
    name = 'Pandigital Novel device interface'
    gui_name = 'PD Novel'
    description = _('Communicate with the Pandigital Novel')
    author = 'Kovid Goyal'
    supported_platforms = ['windows', 'linux', 'osx']
    FORMATS = ['epub', 'pdf']

    VENDOR_ID   = [0x18d1]
    PRODUCT_ID  = [0xb004]
    BCD         = [0x224]

    THUMBNAIL_HEIGHT = 144

    EBOOK_DIR_MAIN = 'eBooks'
    SUPPORTS_SUB_DIRS = False

    def upload_cover(self, path, filename, metadata):
        coverdata = getattr(metadata, 'thumbnail', None)
        if coverdata and coverdata[2]:
            with open('%s.jpg' % os.path.join(path, filename), 'wb') as coverfile:
                coverfile.write(coverdata[2])
class calibre.devices.usbms.device.Device(plugin_path)[source]

Основи: calibre.devices.usbms.deviceconfig.DeviceConfig, calibre.devices.interface.DevicePlugin

Цей клас містить логіку, яка є загальною для усіх драйверів для пристроїв, які експортують себе як пристрої сховищ даних з інтерфейсом USB. Надає реалізації методів для монтування та вилучення пристроїв USBMS для усіх платформ.

WINDOWS_MAIN_MEM = None

String identifying the main memory of the device in the Windows PnP id strings This can be None, string, list of strings or compiled regex

WINDOWS_CARD_A_MEM = None

String identifying the first card of the device in the Windows PnP id strings This can be None, string, list of strings or compiled regex

WINDOWS_CARD_B_MEM = None

String identifying the second card of the device in the Windows PnP id strings This can be None, string, list of strings or compiled regex

OSX_MAIN_MEM_VOL_PAT = None

Використовується засобом виявлення нових драйверів для розрізнення основної пам’яті і карток пам’яті пристрою. Має бути формальним виразом, який відповідає точні монтування основної пам’яті, яка призначається macOS.

MAX_PATH_LEN = 250

Максимальна довжина шляхів, які створюються на пристрої

NEWS_IN_FOLDER = True

Записує новини у власну теку новин.

windows_sort_drives(drives)[source]

Викликається для розрізнення основної пам’яті пристрою та карток пам’яті для пристроїв, які не розрізняють їх за WINDOWS_CARD_NAME. Приклад: EB600

sanitize_callback(path)[source]

Зворотний виклик, який дозволяє окремим драйверам пристроїв перевизначати засіб обробки шляхів, що використовується методом create_upload_path().

filename_callback(default, mi)[source]

Зворотний виклик, який надає змогу драйверам змінити типову назву файла, яку встановлено за допомогою create_upload_path().

sanitize_path_components(components)[source]

Виконує будь-яку специфічну для пристрою попередню обробку компонентів шляху для файлів, які буде вивантажено на пристрій.

get_annotations(path_map)[source]

Перетворити path_map на annotation_map файлів, які виявлено на пристрої

add_annotation_to_library(db, db_id, annotation)[source]

Додати анотацію до бібліотеки calibre

class calibre.devices.usbms.cli.CLI[source]
class calibre.devices.usbms.driver.USBMS(plugin_path)[source]

Основи: calibre.devices.usbms.cli.CLI, calibre.devices.usbms.device.Device

Базовий клас для усіх пристроїв USBMS. Реалізує логіку для надсилання, отримання, оновлення, кешування метаданих тощо.

upload_cover(path, filename, metadata, filepath)[source]

Вивантажує зображення обкладинки книги на пристрій. Типова реалізація не виконує ніяких дій.

Параметри:
  • path – Повний шлях до каталогу, де розташовано відповідну книгу.
  • filename – Назва файла книги без суфікса назви.
  • metadata – метадані, що стосуються книги. Скористайтеся виразом metadata.thumbnail, якщо вам потрібне зображення обкладинки.
  • filepath – Шлях до файла електронної книги повністю.
classmethod normalize_path(path)[source]

Повертає шлях із природними для платформи роздільниками.

Дії інтерфейсу користувача

Якщо ви додаєте власний додаток у файлі ZIP, вам слід створити підкласи для InterfaceActionBase і для InterfaceAction. Метод load_actual_plugin() вашого підкласу InterfaceActionBase має повертати створений екземпляр об’єкта вашого підкласу InterfaceBase.

class calibre.gui2.actions.InterfaceAction(parent, site_customization)[source]

Основа: PyQt5.QtCore.QObject

Додаток, що відповідає «дії», яку буде виконано у графічному інтерфейсі користувача. Усі пункти на панелі та у контекстних меню реалізуються за допомогою таких додатків.

Зауважте, що цей клас є базовим класом для цих додатків. Втім, для інтегрування додатка до системи додатків calibre вам слід створити клас-обгортку, який посилатиметься на сам додаток. Див. приклад у модулі calibre.customize.builtins.

Якщо два об’єкта InterfaceAction мають однакові назви, перевага надається об’єкту із вищою пріоритетністю.

Підкласти мають реалізовувати методи genesis(), library_changed(), location_selected(), shutting_down() і initialization_complete().

Після ініціалізації цей додаток матиме доступ до основного графічного інтерфейсу calibre за допомогою учасника класу gui. Ви можете отримувати доступ до інших додатків за назвою. Приклад:

self.gui.iactions['Save To Disk']

Щоб отримати доступ до самого додатка, скористайтеся атрибутом interface_action_base_plugin. Цей атрибут стане доступним, лише після ініціалізації додатка. Корисно, коли вам потрібно скористатися методами з класу додатка, зокрема do_user_config().

QAction, вказана за допомогою action_spec, автоматично створюється і робиться доступною як self.qaction.

name = u'Implement me'

Назва додатка. Якщо існує два додатки із однаковими назвами, перевагу матиме додаток із вищим рівнем пріоритетності.

priority = 1

Пріоритетність додатка. Якщо існує два додатки із однаковими назвами, перевагу матиме додаток із вищим рівнем пріоритетності.

popup_type = 1

Тип контекстної підказки меню, якщо цей додаток додає кнопку на панель інструментів.

auto_repeat = False

Визначає, чи має ця дія повторюватися, якщо утримується натиснутою комбінація клавіш для виклику додатка.

action_spec = (u'text', u'icon', None, None)

У такій формі: (текст, шлях до піктограми, підказка, клавіатурне скорочення). Піктограма, підказка і клавіатурне скорочення можуть мати значення None. Клавіатурне скорочення мєа бути рядком, None або кортежем скорочень. Якщо має значення None, клавіатурне скорочення для дії не реєструватиметься. Якщо передано порожній кортеж, буде зареєстровано скорочення без типової прив’язки до клавіш.

action_add_menu = False

Якщо має значення True, автоматично створюється і додається до self.qaction меню.

action_menu_clone_qaction = False

Якщо має значення True, до меню self.qaction додається клон self.qaction. Якщо ви хочете, щоб текст цієї доданої дії був не таким як у self.qaction, встановіть для цієї змінної нове текстове значення.

dont_add_to = frozenset([])

Набір місць, до яких не слід додавати цю дію. Список можливих місць наведено у описі all_locations.

dont_remove_from = frozenset([])

Набір місць, з яких не слід вилучати цю дію. Список можливих місць наведено у описі all_locations.

action_type = u'global'

Тип дії «current» означає, що дія виконується для поточної панелі перегляду. Тип «global» означає дію, яку не призначено для поточної панелі перегляду, а призначено для усього екземпляра calibre.

accepts_drops = False

Якщо має значення True, ця InterfaceAction буде мати змогу обробляти події з перетягування зі скиданням. Докладніше про це у описі методів accept_enter_event(), :meth`:accept_drag_move_event`, drop_event().

accept_enter_event(event, mime_data)[source]

Цей метод має повертати True тоді і лише тоді, коли ця дія інтерфейсу здатна обробляти подію з перетягування. Не викликайте accept/ignore для події, оскільки ці виклики буде оброблено інтерфейсом користувача calibre.

accept_drag_move_event(event, mime_data)[source]

Цей метод має повертати True тоді і лише тоді, коли ця дія інтерфейсу здатна обробляти подію з перетягування. Не викликайте accept/ignore для події, оскільки ці виклики буде оброблено інтерфейсом користувача calibre.

drop_event(event, mime_data)[source]

Цей метод має виконати певну корисну дію і повернути True тоді і лише тоді, коли ця дія інтерфейсу здатна обробляти подію скидання. Не викликайте accept/ignore для події, про це подбає інтерфейс користувача calibre. Вам не слід виконувати блокування або тривалі дії у цій функції. Замість цього надішліть сигнал або скористайтеся QTimer.singleShot і швидко поверніть керування. Приклади можна знайти серед вбудованих до програми дій.

create_menu_action(menu, unique_name, text, icon=None, shortcut=None, description=None, triggered=None, shortcut_name=None)[source]

Зручний метод для спрощення додавання пунктів дій до QMenu. Повертає створену QAction. Ця дія має лише один додатковий атрибут, calibre_shortcut_unique_name, який, якщо не має значення None, посилається на унікальну назву, під якою цю дію зареєстровано у засобі керування клавіатурними скороченнями.

Параметри:
  • menu – QMenu, до якого буде додано пункт створеної дії.
  • unique_name – Унікальна назва для цієї дії. Має бути унікальною на загальному рівні, тому робіть її якомога описовішою. Якщо маєте сумніви, додайте до неї UUID.
  • text – Текст дії.
  • icon – QIcon або назва файла. Назву файла буде передано до вбудованої функції I(), отже вам не потрібно передавати повний шлях до каталогу images.
  • shortcut – Рядок, список рядків, None або False. Якщо False, для цієї дії не буде зареєстровано клавіатурного скорочення. Якщо None, буде зареєстровано клавіатурне скорочення без типового значення. Рядок або список рядків реєструють клавіатурне скорочення із вказаними типовим значеннями.
  • description – Опис дії. Використовується для встановлення підказок.
  • triggered – Придатна до виклику функція, яка з’єднується із сигналом-перемикачем створеної дії.
  • shortcut_name – Текстове повідомлення, яке буде показано користувачеві під час налаштовування клавіатурних скорочень для цієї дії. Типово встановлено значення text.
load_resources(names)[source]

Якщо цей додаток постачається у форматі файла ZIP (додаток, що встановлюється користувачем), цей метод дозволить вам завантажити ресурси з файла ZIP.

Наприклад, для завантаження зображення:

pixmap = QPixmap()
pixmap.loadFromData(tuple(self.load_resources(['images/icon.png']).values())[0])
icon = QIcon(pixmap)
Параметри:names – Список шляхів до ресурсів у файлі ZIP з використанням роздільника /
Повертає:Словник у формі {назва: вміст_файла}. Усі назви, які не було знайдено у файлі ZIP, не буде включено до словника.
genesis()[source]

Налаштовує цей додаток. Викликається лише раз під час ініціалізації. Доступним є self.gui. Дія, вказана action_spec є доступною як self.qaction.

location_selected(loc)[source]

Викликається щоразу, коли змінюється список книг, що показується у calibre. У поточній версії можливими значенням loc є такі значення: library, main, card і cardb.

Цей метод має вмикати або вимикати цю дію і її підлеглі дії відповідним чином для цього місця.

library_changed(db)[source]

Викликається у відповідь на зміну поточної бібліотеки.

Параметри:db – LibraryDatabase, що відповідає поточній бібліотеці.
gui_layout_complete()[source]

Викликається один раз для кожної дії після завершення компонування основного графічного інтерфейсу. Якщо вашій дії потрібно внести зміни до компонування, їх слід внести тут, а не у initialization_complete().

initialization_complete()[source]

Викликається один раз на кожну дію, коли завершується ініціалізація основного графічного інтерфейсу.

shutting_down()[source]

Викликається один раз для кожного з додатків, коли основний графічний інтерфейс програми перебуває у стані завершення роботи. Має звільнити усі ресурси, але не намагатися блокувати процес завершення роботи на довгі проміжки часу.

class calibre.customize.InterfaceActionBase(*args, **kwargs)[source]

Основа: calibre.customize.Plugin

load_actual_plugin(gui)[source]

Цей метод має повертати поточний інтерфейс об’єкта додатка дії.

Додатки налаштувань

class calibre.customize.PreferencesPlugin(plugin_path)[source]

Основа: calibre.customize.Plugin

Додаток, що забезпечує роботу віджета, який показується у діалоговому вікні «Налаштування».

У цього додатка є лише один важливий метод, create_widget(). Різноманітні поля додатка керують тим, як його буде категоризовано у інтерфейсі користувача.

config_widget = None

Шлях імпортування модуля, який містить клас із назвою ConfigWidget, який реалізує ConfigWidgetInterface. Використовується методом create_widget().

category_order = 100

Визначає, де має бути у списку категорій категорія цього додатка.

name_order = 100

Визначає, де у списку назв у категорії має бути gui_name цього додатка.

category = None

Категорія, до якої належить цей додаток.

gui_category = None

Назва категорії, яку буде показано користувачеві для цього додатка.

gui_name = None

Назва, яку буде показано користувачеві цього додатка.

icon = None

Піктограма цього додатка, має бути вказано абсолютний шлях.

description = None

Опис, який використовується для підказок та інших довідкових панелей.

create_widget(parent=None)[source]

Створює і повертає сам віджет Qt, який використовується для встановлення цієї групи налаштувань. Віджет має реалізовувати calibre.gui2.preferences.ConfigWidgetInterface.

Типова реалізація використовує config_widget для створення екземпляра віджета.

class calibre.gui2.preferences.ConfigWidgetInterface[source]

Цей клас визначає інтерфейс, який мають реалізовувати усі віджети, які показано у діалоговому вікні «Налаштування». Базовим класом, який реалізовує цей інтерфейс і визначає зручні методи, є ConfigWidgetBase.

changed_signal = None

Цей сигнал має бути надіслано кожного разу, коли користувач змінює значення у цьому віджеті.

supports_restoring_to_defaults = True

Встановіть значення True тоді і лише тоді, коли реалізовано метод restore_to_defaults().

restore_defaults_desc = u'\u0412\u0456\u0434\u043d\u043e\u0432\u0438\u0442\u0438 \u0442\u0438\u043f\u043e\u0432\u0456 \u0437\u043d\u0430\u0447\u0435\u043d\u043d\u044f \u043f\u0430\u0440\u0430\u043c\u0435\u0442\u0440\u0456\u0432. \u0429\u043e\u0431 \u0437\u0431\u0435\u0440\u0435\u0433\u0442\u0438 \u0442\u0438\u043f\u043e\u0432\u0456 \u043f\u0430\u0440\u0430\u043c\u0435\u0442\u0440\u0438, \u0432\u0430\u043c \u0441\u043b\u0456\u0434 \u043d\u0430\u0442\u0438\u0441\u043d\u0443\u0442\u0438 \u043a\u043d\u043e\u043f\u043a\u0443 \xab\u0417\u0430\u0441\u0442\u043e\u0441\u0443\u0432\u0430\u0442\u0438\xbb.'

Підказка для кнопки «Відновити типові значення»

restart_critical = False

Якщо має значення True, діалогове вікно «Налаштування» заборонить користувачеві продовжувати зміну налаштувань. Працює, лише якщо commit() повертає True.

genesis(gui)[source]

Викликається один раз перед показом віджета, має виконати усі потрібні налаштовування.

Параметри:gui – Основний графічний інтерфейс calibre
initialize()[source]

Має встановити усі початкові значення налаштувань (значення, які зберігаються у файлах налаштувань).

restore_defaults()[source]

Має встановити типові значення для усіх налаштувань.

commit()[source]

Зберігає усі змінені параметри. Повертає True, якщо зміни потребують перезапуску програми, і False, якщо ні. Надсилає виключення AbortCommit, щоб повідомити про те, що сталася помилка. Ви маєте самі визначити, як слід повідомити користувачеві про помилку і про те, як її виправити.

refresh_gui(gui)[source]

Викликається один раз після надсилання цього віджета. Відповідає за повторне читання графічним інтерфейсом усіх змінених параметрів. Зауважте, що типово графічний інтерфейс попри усе повторно ініціалізує різноманітні елементи, отже для більшості віджетів потреби у використанні цього методу немає.

class calibre.gui2.preferences.ConfigWidgetBase(parent=None)[source]

Базовий клас, який містить код для спрощення додавання стандартних віджетів налаштовування, зокрема пунктів позначок, спадних списків, текстових полів тощо. Див. метод register().

Цей клас виконує автоматичну обробку сповіщення про зміни, повернення до типових значень, перенесення даних із об’єктів графічного інтерфейсу до об’єктів налаштувань тощо для зареєстрованих параметрів.

Якщо ваш віджет налаштувань успадковується від цього класу, але включає параметр, який не зареєстровано, вам слід перевизначити методи ConfigWidgetInterface і викликати методи базового класу всередині перевизначення.

register(name, config_obj, gui_name=None, choices=None, restart_required=False, empty_string_is_None=True, setting=<class 'calibre.gui2.preferences.Setting'>)[source]

Зареєструвати параметр.

Параметри:
  • name – Назва параметра
  • config – Об’єкт налаштувань, який читає або запису параметр.
  • gui_name – Назва об’єкта графічного інтерфейсу користувача, який надає інтерфейс для зміни параметра. Типовою назвою вважається 'opt_' + назва.
  • choices – Якщо цей параметр є параметром із декількома варіантами (визначається спадним списком), список варіантів. Форматом запису списку є двоелементний кортеж. Формат списку: [(назва у графічному інтерфейсі, значення), ...]
  • setting – Клас, що відповідає за керування цим параметром. Типовий клас обробляє майже усі класи, отже цей параметр використовується нечасто.