ebookerr-sdk

The toolkit for writing ebookerr plugins: the plugin contract (ebookerr_sdk.spi), the host that runs a plugin (ebookerr_sdk.host), a test kit (ebookerr_sdk.testing), the pack command, and helper kits for EPUB files, downloads, validation, library servers and text generation.

• Guide: https://github.com/ArcCdr/lit-ebookerr/blob/main/docs/PLUGIN_DEV.md
• API reference: https://arccdr.github.io/lit-ebookerr/
• Plugins: https://github.com/ArcCdr/ebookerr-plugins

Install

pip install "ebookerr-sdk==3.3.*"

The SDK's MAJOR.MINOR is the SPI version it speaks: ebookerr-sdk 3.3.x speaks SPI 3.3. It needs Python 3.11 or later.

Start a plugin

python -m ebookerr_sdk.pack new hello_book --type book
pytest hello_book/tests
python -m ebookerr_sdk.pack check hello_book
python -m ebookerr_sdk.pack build hello_book --out dist

new writes a plugin that passes check and its own test; --type is source, epub, book or catalog. The guide explains what to write next and how to install the zip in ebookerr.

Compatibility

ebookerr loads a plugin when its spi_version has ebookerr's SPI MAJOR and a MINOR not above ebookerr's; otherwise it shows the plugin as incompatible and offers a compatible release.

Versioning

1. A MINOR release only adds: an optional manifest key whose default keeps today's behaviour, or a new protocol, role, operation, context method, event or trigger scope that you opt into.
2. Anything else — removing or renaming, changing a default or a meaning, making a key required, refusing a manifest that was valid — waits for the next MAJOR release.
3. ebookerr ignores manifest keys it does not know, with a warning; your plugin should ignore request keys it does not know. python -m ebookerr_sdk.pack check refuses unknown manifest keys and settings-field types, so a typo is caught before you release.
4. Before it is removed, a public item is deprecated: named in these release notes and logged once per plugin as a warning when used, it keeps working for at least two MINOR releases and six months.
5. An ebookerr release supports one SPI MAJOR, and moves to a new MAJOR only once every official plugin has a compatible release.
6. A PATCH release of the SDK fixes defects only; it never changes the public API.
7. The public API is manifest.toml, ebookerr_sdk.spi, ebookerr_sdk.host, ebookerr_sdk.testing, python -m ebookerr_sdk.pack and the kits ebookerr_sdk.epub, .validate, .download, .generation, .providers and .domain. ebookerr_sdk.wire, .readpos, .registry_index and every _-prefixed name are internal and may change in any release.

Release notes

3.3.0

SPI 3.3. The EPUB kit gains helpers for the EPUBs ebookerr writes; later sentences of this section name each one. A plugin written for SPI 3.2 needs no change. build_epub writes its package through ebookerr_sdk.epub.builder: the NCX dtb:uid is the OPF identifier and the package carries its creation date, so a built book validates without findings. EpubDocument.set_title writes a new title into the package and every table of contents (NcxDocument.set_doc_title, NavDocument.set_doc_title), so a retitled book's OPF and NCX agree. retitle_built_epub gives a build_epub output a new title in its package, tables of contents and title page; convert_stage and download_convert_stage use it, so a converted book's file carries the title the book gets. ebookerr_sdk.epub.text_convert.is_chapter_heading names the prose chapter-heading rule. convert_stage titles an uploaded document after its own title, else its file name unless the name is a placeholder such as Document1 or Untitled, else a first line that is no chapter heading. Book.front_matter holds the text above a document's first heading; build_epub puts it on the title page, and parse_text_to_book fills it instead of making that text a chapter. parse_text_to_book keeps each line of a text that has no blank line at all as its own paragraph. convert_stage and download_convert_stage pass a user_facing conversion error's message through unchanged and answer "The file could not be converted." for any other failure, so no library message or path reaches a user. EpubDocument.drm_protected() tells a DRM-protected book (a rights.xml, or an encryption.xml using anything but font obfuscation) from one whose fonts are only obfuscated.

3.2.0

SPI 3.2. A story can name the multi-part work it is one part of: StoryPatch.work and StoryPatch.work_url. series and series_url mean a series the site itself declares — separate works in a declared order — never the work a chapter belongs to. BookView.work_url carries the work a book is a chapter of. ebookerr_sdk.domain.adoption gains same_series and same_work; AdoptionSide.work_url and Evidence.same_work are new, and signal E5 is "same series or same work". EBOOKERR_META_KEYS gains work_url. A plugin written for SPI 3.1 needs no change.

3.1.0

SPI 3.1. A [[ui_triggers]] entry's icon is optional and defaults to the plugin's icon; declare one only when a plugin has more than one action. Every glyph name must be one the self-hosted Material Symbols font renders (ebookerr_sdk/spi/material_symbols.txt): pack check reports an unknown name, two actions of one scope showing the same glyph, and a trigger without icon in a manifest that still declares spi_version = "3.0". pack check now reports a declared requirement that is not installed where it runs instead of guessing its module names. A plugin written for SPI 3.0 needs no change.

3.0.0

SPI 3.0. A plugin written for SPI 2.x declares spi_version = "3.0" and applies these changes:

• spi_version is required.
• Roles are declared only as [roles.<name>] tables. The top-level keys exclusive_group, provider, delete_mode, reader_url_template, handles_merge_proposals, catch_all and extract_url_patterns are gone (provider, delete_mode and reader_url_template remain keys of [roles.library_server]).
• network, auth_methods, headless, headed and default_enabled are no longer manifest keys. A plugin runs on events when it declares events, and runs by hand when it declares a book_selection_action or cover_invalidate trigger; PluginManifest.headed is derived from its triggers.
• Settings-field types are string, textarea, int, float, bool, url, url_list, threshold_list, record_list and command: a secret is secret = true on a string, a drop-down is options with options_strict = true on a string; the types text, secret and select are gone. SettingsGroup.collapsed is gone.
• UiFilter and UiTrigger.filters are gone.
• PluginContext.ask_yes_no returns True, False, or None when the prompt was abandoned or timed out; PluginContext.ask_yes_no_answer and PluginContext.queue are gone.
• UpdateCheckingSource.check_for_update always receives ctx; its cancel_event parameter is gone.
• BookView.erotica_tags is gone; use BookView.tags.
• ProviderAnchor, ProviderBookmark and ReadPositionAnchoring are imported from ebookerr_sdk.providers only.
• New: PluginContext.credentials(url) and SiteCredential — the stored sign-in for a site the plugin may use: a host in its auth_sites ("*" for any site it processes) or the host of a credential = true URL setting.
• New: python -m ebookerr_sdk.pack new starts a plugin; pack check refuses unknown manifest keys, settings-field types and trigger scopes.
• ebookerr_sdk.spi is split into modules (errors, settings, types, views, declarations, context, protocols); every name still imports from ebookerr_sdk.spi.
• ebookerr_sdk.wire, ebookerr_sdk.readpos and ebookerr_sdk.registry_index are internal.

Licence

ebookerr-sdk is released under the MIT licence. Each plugin carries its own licence.