ebooklib Package

ebooklib Package

epub Module

Backwards compatible public API for EbookLib.

Historically all of EbookLib lived in this module. The implementation has been split into smaller modules (ebooklib.book, ebooklib.items, ebooklib.reader, ebooklib.writer, ebooklib.toc, ebooklib.consts and ebooklib.exceptions) but everything is still importable from ebooklib.epub and will remain so until a future major release.

class ebooklib.epub.EpubBook

Bases: object

add_author(author: str, file_as: str | None = None, role: str | None = None, uid: str | None = None) → None

Add author for this document

add_item(item: EpubItem) → EpubItem

Add additional item to the book. If not defined, media type and chapter id will be defined for the item.

A missing ID is generated as chapter_N (EpubHtml), image_N (EpubImage) or static_N (any other item). Generated IDs skip IDs already used by items in the book. Explicit IDs are used as given and are not checked for uniqueness.

Args:

• item: Item instance

Returns:

The same item that was passed in, now attached to the book.

add_metadata(namespace: str | None, name: str, value: str, others: dict | None = None) → None

Add metadata

add_prefix(name: str, uri: str) → None

Appends custom prefix to be added to the content.opf document

>>> epub_book.add_prefix('bkterms', 'http://booktype.org/')

Args:

• name: namespave name

• uri: URI for the namespace

get_item_with_href(href: str) → EpubItem | None

Returns item for defined HREF.

>>> book.get_item_with_href('EPUB/document.xhtml')

Args:

• href: HREF for the item we are searching for

Returns:

Returns item object. Returns None if nothing was found.

get_item_with_id(uid: str) → EpubItem | None

Returns item for defined UID.

>>> book.get_item_with_id('image_001')

Args:

• uid: UID for the item

Returns:

Returns item object. Returns None if nothing was found.

get_items() → Iterator[EpubItem]

Returns all items attached to this book.

Returns:

Returns all items as tuple.

get_items_of_media_type(media_type: str) → Iterator[EpubItem]

Returns all items of specified media type.

Args:

• media_type: Media type for items we are searching for

Returns:

Returns found items as tuple.

get_items_of_type(item_type: int) → Iterator[EpubItem]

Returns all items of specified type.

>>> book.get_items_of_type(epub.ITEM_IMAGE)

Args:

• item_type: Type for items we are searching for

Returns:

Returns found items as tuple.

get_metadata(namespace: str | None, name: str) → list

Retrieve metadata

get_template(name: str) → bytes | None

Returns value for the template.

Args:

• name: template name

Returns:

Value of the template.

reset() → None

Initialises all needed variables to default values

set_cover(file_name: str, content: bytes, create_page: bool = True) → None

Set cover and create cover document if needed.

Args:

• file_name: file name of the cover page

• content: Content for the cover image

• create_page: Should cover page be defined. Defined as bool value (optional). Default value is True.

set_direction(direction: str | None) → None

Args:

• direction: Options are “ltr”, “rtl” and “default”

set_identifier(uid: str) → None

Sets unique id for this epub

Args:

• uid: Value of unique identifier for this book

set_language(lang: str) → None

Set language for this epub. You can set multiple languages. Specific items in the book can have different language settings.

Args:

• lang: Language code

set_template(name: str, value: bytes) → None

Defines templates which are used to generate certain types of pages. When defining new value for the template we have to use content of type ‘bytes’.

At the moment we use these templates:

• ncx

• nav

• chapter

• cover

Args:

• name: Name for the template

• value: Content for the template

set_title(title: str) → None

Set title. You can set multiple titles.

Args:

• title: Title value

set_unique_metadata(namespace: str | None, name: str, value: str, others: dict | None = None) → None

Add metadata if metadata with this identifier does not already exist, otherwise update existing metadata.

class ebooklib.epub.EpubCover(uid: str | None = 'cover-img', file_name: str = '')

Bases: EpubItem

Represents Cover image in the EPUB file.

get_type() → int

Guess type according to the file extension. Might not be the best way how to do it, but it works for now.

Items can be of type:

• ITEM_UNKNOWN = 0

• ITEM_IMAGE = 1

• ITEM_STYLE = 2

• ITEM_SCRIPT = 3

• ITEM_NAVIGATION = 4

• ITEM_VECTOR = 5

• ITEM_FONT = 6

• ITEM_VIDEO = 7

• ITEM_AUDIO = 8

• ITEM_DOCUMENT = 9

• ITEM_COVER = 10

We map type according to the extensions which are defined in ebooklib.EXTENSIONS.

Returns:

Returns type of the item as number.

class ebooklib.epub.EpubCoverHtml(uid: str = 'cover', file_name: str = 'cover.xhtml', image_name: str = '', title: str = 'Cover')

Bases: EpubHtml

Represents Cover page in the EPUB file.

get_content(default: str | bytes | None = None) → bytes

Returns content for cover page as HTML string. Content will be of type ‘bytes’.

Returns:

Returns content of this document.

is_chapter() → bool

Returns if this document is chapter or not.

Returns:

Returns book value.

exception ebooklib.epub.EpubException(code: int, msg: str)

Bases: Exception

class ebooklib.epub.EpubHtml(uid: str | None = None, file_name: str = '', media_type: str = '', content: str | bytes | None = None, title: str = '', lang: str | None = None, direction: str | None = None, media_overlay: str | None = None, media_duration: str | None = None)

Bases: EpubItem

Represents HTML document in the EPUB file.

add_item(item: EpubItem) → None

Add other item to this document. It will create additional links according to the item type.

Args:

• item: item we want to add defined as instance of EpubItem

add_link(**kwgs: Any) → None

Add additional link to the document. Links will be embeded only inside of this document.

>>> add_link(href='styles.css', rel='stylesheet', type='text/css')

add_meta(**kwgs: Any) → None

Add additional <meta> to the document.

>>> add_meta(name='viewport', content='width=device-width, initial-scale=1')

get_body_content() → bytes

Returns content of BODY element for this HTML document. Content will be of type ‘bytes’.

Text placed directly in the BODY (before the first child element) is kept, so a body that contains only text is returned too. A body whose only direct text is whitespace (for example the newline and indentation before the first element) and that has no child elements is considered empty.

Returns:

Returns content of this document, or b"" if the BODY is empty.

get_content(default: str | bytes | None = None) → bytes

Returns content for this document as HTML string. Content will be of type ‘bytes’.

Args:

• default: Default value for the content if it is not defined.

Returns:

Returns content of this document.

get_language() → str | None

Get language code for this book item. Language of the book item can be different from the language settings defined globaly for book.

Returns:

As string returns language code.

get_links() → Iterator[dict[str, Any]]

Returns list of additional links defined for this document.

Returns:

As tuple return list of links.

get_links_of_type(link_type: str) → Iterator[dict[str, Any]]

Returns list of additional links of specific type.

Returns:

As tuple returns list of links.

get_metas() → Iterator[dict[str, Any]]

Returns list of additional metas defined for this document.

Returns:

As tuple return list of metas.

get_type() → int

Always returns ebooklib.ITEM_DOCUMENT as type of this document.

Returns:

Always returns ebooklib.ITEM_DOCUMENT

is_chapter() → bool

Returns if this document is chapter or not.

Returns:

Returns book value.

set_language(lang: str | None) → None

Sets language for this book item. By default it will use language of the book but it can be overwritten with this call.

class ebooklib.epub.EpubImage(uid: str | None = None, file_name: str = '', media_type: str = '', content: str | bytes | None = None, manifest: bool = True)

Bases: EpubItem

Represents Image in the EPUB file.

get_type() → int

Guess type according to the file extension. Might not be the best way how to do it, but it works for now.

Items can be of type:

• ITEM_UNKNOWN = 0

• ITEM_IMAGE = 1

• ITEM_STYLE = 2

• ITEM_SCRIPT = 3

• ITEM_NAVIGATION = 4

• ITEM_VECTOR = 5

• ITEM_FONT = 6

• ITEM_VIDEO = 7

• ITEM_AUDIO = 8

• ITEM_DOCUMENT = 9

• ITEM_COVER = 10

We map type according to the extensions which are defined in ebooklib.EXTENSIONS.

Returns:

Returns type of the item as number.

class ebooklib.epub.EpubItem(uid: str | None = None, file_name: str = '', media_type: str = '', content: str | bytes | None = None, manifest: bool = True)

Bases: object

Base class for the items in a book.

get_content(default: str | bytes | None = None) → str | bytes

Returns content of the item. Content is usually of type ‘bytes’ but API users assign ‘str’ as well.

Args:

• default: Default value for the content if it is not already defined.

Returns:

Returns content of the item.

get_id() → str | None

Returns unique identifier for this item.

Returns:

Returns uid number as string.

get_name() → str

Returns name for this item. By default it is always file name but it does not have to be.

Returns:

Returns file name for this item.

get_type() → int

Guess type according to the file extension. Might not be the best way how to do it, but it works for now.

Items can be of type:

• ITEM_UNKNOWN = 0

• ITEM_IMAGE = 1

• ITEM_STYLE = 2

• ITEM_SCRIPT = 3

• ITEM_NAVIGATION = 4

• ITEM_VECTOR = 5

• ITEM_FONT = 6

• ITEM_VIDEO = 7

• ITEM_AUDIO = 8

• ITEM_DOCUMENT = 9

• ITEM_COVER = 10

We map type according to the extensions which are defined in ebooklib.EXTENSIONS.

Returns:

Returns type of the item as number.

set_content(content: str | bytes) → None

Sets content value for this item.

Args:

• content: Content value

class ebooklib.epub.EpubNav(uid: str | None = 'nav', file_name: str = 'nav.xhtml', media_type: str = 'application/xhtml+xml', title: str = '', direction: str | None = None)

Bases: EpubHtml

Represents Navigation Document in the EPUB file.

is_chapter() → bool

Returns if this document is chapter or not.

Returns:

Returns book value.

class ebooklib.epub.EpubNcx(uid: str | None = 'ncx', file_name: str = 'toc.ncx')

Bases: EpubItem

Represents Navigation Control File (NCX) in the EPUB.

class ebooklib.epub.EpubReader(epub_file_name, options: dict[str, Any] | None = None)

Bases: object

DEFAULT_OPTIONS: dict[str, Any] = {'ignore_ncx': True}

load() → EpubBook

process() → None

read_file(name: str) → bytes

class ebooklib.epub.EpubSMIL(uid: str | None = None, file_name: str = '', content: str | bytes | None = None)

Bases: EpubItem

get_type() → int

Guess type according to the file extension. Might not be the best way how to do it, but it works for now.

Items can be of type:

• ITEM_UNKNOWN = 0

• ITEM_IMAGE = 1

• ITEM_STYLE = 2

• ITEM_SCRIPT = 3

• ITEM_NAVIGATION = 4

• ITEM_VECTOR = 5

• ITEM_FONT = 6

• ITEM_VIDEO = 7

• ITEM_AUDIO = 8

• ITEM_DOCUMENT = 9

• ITEM_COVER = 10

We map type according to the extensions which are defined in ebooklib.EXTENSIONS.

Returns:

Returns type of the item as number.

class ebooklib.epub.EpubWriter(name: str | PathLike[str] | _WritableFile, book: EpubBook, options: dict[str, Any] | None = None)

Bases: object

DEFAULT_OPTIONS: dict[str, Any] = {'compresslevel': 6, 'epub2_guide': True, 'epub3_landmark': True, 'epub3_pages': True, 'landmark_title': 'Guide', 'package_direction': False, 'pages_title': 'Pages', 'play_order': {'enabled': False, 'start_from': 1}, 'raise_exceptions': True, 'spine_direction': True}

classmethod datetime_to_zipinfo_datetime(dt: datetime) → tuple[int, int, int, int, int, int]

Converts a datetime object to a tuple format compatible with zipfile.ZipInfo.

Args:

• dt: datetime.datetime object

Returns:

Tuple of (year, month, day, hour, minute, second) for use in ZipInfo

classmethod get_default_options() → dict[str, Any]

process() → None

write() → None

zipinfo(name: str) → ZipInfo

class ebooklib.epub.Link(href: str, title: str, uid: str | None = None)

Bases: object

class ebooklib.epub.Section(title: str, href: str = '')

Bases: object

ebooklib.epub.read_epub(name, options: dict[str, Any] | None = None) → EpubBook

Creates new instance of EpubBook with the content defined in the input file.

>>> book = ebooklib.read_epub('book.epub')

Args:

• name: full path to the input file

• options: extra options as dictionary (optional)

Returns:

Instance of EpubBook.

ebooklib.epub.write_epub(name: str | PathLike[str] | _WritableFile, book: EpubBook, options: dict[str, Any] | None = None) → bool

Creates epub file with the content defined in EpubBook.

>>> ebooklib.write_epub('book.epub', book)

Args:

• name: file name for the output file

• book: instance of EpubBook

• options: extra opions as dictionary (optional)

utils Module

class ebooklib.utils.Directory(directory_path: str | PathLike)

Bases: object

Reads files from an unpacked EPUB directory, using the same interface as ZipFile.

close() → None

read(subname: str) → bytes

Read the file subname relative to the EPUB directory and return its bytes.

subname typically comes from OPF manifest href attributes, which are attacker-controlled and URL-decoded, so the resolved path must stay inside the EPUB directory.

Parameters:

subname – Path of the file, relative to the EPUB directory.

Returns:

Raw content of the file.

Raises:

OSError – If subname escapes the EPUB directory (path traversal, e.g. "../../secret"), or if the file cannot be read.

ebooklib.utils.create_pagebreak(pageref: str, label: str | None = None, html: bool = True) → _Element | str

ebooklib.utils.debug(obj: object) → None

ebooklib.utils.get_headers(elem) → str | None

ebooklib.utils.get_pages(item) → list[tuple[str, str, str]]

ebooklib.utils.get_pages_for_items(items) → list[tuple[str, str, str]]

ebooklib.utils.guess_type(extenstion: str) → tuple[str | None, str | None]

ebooklib.utils.parse_html_string(s: str | bytes)

ebooklib.utils.parse_string(s: str | bytes) → _ElementTree

Subpackages

• plugins Package
  • base Module
    • BasePlugin
      • BasePlugin.after_read()
      • BasePlugin.after_write()
      • BasePlugin.before_read()
      • BasePlugin.before_write()
      • BasePlugin.html_after_read()
      • BasePlugin.html_before_write()
      • BasePlugin.item_after_read()
      • BasePlugin.item_before_write()
  • booktype Module
    • BooktypeFootnotes
      • BooktypeFootnotes.NAME
      • BooktypeFootnotes.html_before_write()
    • BooktypeLinks
      • BooktypeLinks.NAME
      • BooktypeLinks.html_before_write()
  • sourcecode Module
    • SourceHighlighter
      • SourceHighlighter.html_before_write()
  • standard Module
    • SyntaxPlugin
      • SyntaxPlugin.NAME
      • SyntaxPlugin.html_before_write()
    • leave_only()
  • tidyhtml Module
    • TidyPlugin
      • TidyPlugin.NAME
      • TidyPlugin.OPTIONS
      • TidyPlugin.html_after_read()
      • TidyPlugin.html_before_write()
    • tidy_cleanup()