epublib.ncx.resource module

class NCXFile(

file: IO[bytes] | bytes,

info: ZipInfo | str | Path,

media_type: MediaType | str = MediaType.NCX,

)

Bases: PublicationResource, XMLResource[NCXSoup], SoupChanging

The NCX document of the EPUB file, sometimes known as the ‘toc.ncx’ file. This is used in EPUB2 files for navigation, and was largely superseded by the package document in EPUB3. Support for it in EPUB3 is optional.

Parameters:

• file – The file-like object or bytes containing the NCX XML data.

• info – The ZipInfo object or filename for this resource in the EPUB archive.

• media_type – The media type of this resource. Defaults to MediaType.NCX.

soup_class

alias of NCXSoup

property head: NCXHead

Return the head of the NCX document, containing metadata, as a NCXHead object.

property title: NCXTitle

Return the title of the NCX document, as a NCXTitle object.

property authors: Sequence[NCXAuthor]

Return a sequence of authors of the NCX document as NCXAuthor objects.

property nav_map: NCXNavMap

Return the navigation map of the NCX document as a NCXNavMap object.

property page_list: NCXPageList | None

Return the page list of the NCX document as a NCXPageList object, or None if there is no page list.

property nav_lists: Sequence[NCXNavList]

Return a sequence of nav lists in the NCX document as NCXNavList objects.

remove(filename: str | Path) → None

Remove all references to the given filename from the NCX document.

Parameters:

filename – The filename to remove references to.

get_author(name: str) → NCXAuthor | None

Return the author with the given name, or None if no such author exists.

Parameters:

name – The name of the author to find.

Returns:

The NCXAuthor object with the given name, or None if no such author exists.

add_author(name: str) → NCXAuthor

Add a new author with the given name to the NCX document, and return the corresponding NCXAuthor object.

Parameters:

name – The name of the author to add.

Returns:

The newly created NCXAuthor object.

remove_author(

author: str | NCXAuthor,

) → NCXAuthor | None

Remove the given author from the NCX document, and return the removed NCXAuthor object, or None if no such author exists.

Parameters:

author – The NCXAuthor object or name of the author to remove.

Returns:

The removed NCXAuthor object, or None if no such author exists.

add_nav_list(

items: Iterable[TOCEntryData],

) → NCXNavList

Add a new nav list with the given items to the NCX document, and return the corresponding NCXNavList object.

Parameters:

items – An iterable of TOCEntryData objects representing the items to add to the new nav list.

Returns:

The newly created NCXNavList object.

reset_page_list(

entries: list[PageBreakData],

) → None

Reset the page list of the NCX document to contain the given entries.

Parameters:

entries – A list of PageBreakData objects representing the entries to set in the page list.

update_total_page_count() → None

Update the total page count in the head of the NCX document.

update_depth() → None

Update the depth in the head of the NCX document, based on the maximum depth of the nav map.

update_max_page_number() → None

Update the max page number in the head of the NCX document.

update_play_order() → None

Update the play order of all nav points in the nav map, starting from 1 and incrementing by 1 for each nav point in a depth-first traversal.

update_numbers() → None

Update required numbers in the head and nav map of the NCX file: - max depth; - max page number (if there is a page list); - total page count (if there is a page list); - play order.

sync_head(

metadata: BookMetadata,

) → NCXHead

Sync metadata from the package document metadata to the NCX document, erasing any existing head > meta items. Should be used after populating the navMap and pageList (if there is one), to get an accurate page and depth count.

Parameters:

metadata – The BookMetadata object to sync from.

Returns:

The NCXHead object after syncing.

sync_toc(

nav: NavigationDocument,

) → NCXNavMap

Sync the NCX navMap to match the given TOC structure, erasing any existing navMap items.

Parameters:

nav – The NavigationDocument to sync from.

Returns:

The NCXNavMap object after syncing.

Raises:

EPUBError – If self referential structure is detected in the TOC structure.

sync_page_list(

nav: NavigationDocument,

) → NCXPageList

Sync the NCX page list to match the given navigation document page list structure, erasing any existing page list items.

Parameters:

nav – The NavigationDocument to sync from.

Returns:

The NCXPageList object after syncing.

Raises:

EPUBError – If the given navigation document has no page list.

on_soup_change() → None

Trigger reparsing of the internal representations of the resource. Used after the soup is modified directly.

on_content_change() → None

Hook called when the content of this resource changes.