epublib.nav.resource module

class NavigationDocument(
file: IO[bytes] | bytes,
info: ZipInfo | str | Path,
media_type: MediaType,
)

Bases: ContentDocument, SoupChanging

A specialization of the XHTML content document that contains human- and machine-readable global navigation information.

Typical usage is from an EPUB instance:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_toc()
...     toc_title = book.nav.toc.title
...     refs = book.nav.toc.items_referencing("Text/chapter1.xhtml")
>>> toc_title
'Table of Contents'
>>> len(list(refs))
2
Parameters:

  • file – A file-like object or bytes containing the navigation document.

  • info – The ZipInfo or filename of the navigation document in the EPUB archive.

  • media_type – The media type of the navigation document, typically application/xhtml+xml.

property toc: TocRoot

The table of contents in the navigation document.

property page_list: PageListRoot | None

The page list in the navigation document, if any.

property landmarks: LandmarksRoot | None

The landmarks in the navigation document, if any.

reset_toc(
entries: list[TOCEntryData],
) → None

Reset the table of contents in the navigation document to the given entries. Will replace any existing table of contents.

Typically used indirectly from an EPUB instance with the reset_toc or create_toc methods.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_toc(title = "New table of Contents")
...     toc_title = book.nav.toc.title
>>> toc_title
'New table of Contents'
Parameters:

entries – A list of TOCEntryData instances representing the entries to include in the table of contents.

reset_page_list(
pagebreaks: list[PageBreakData],
) → None

Reset the page list in the navigation document to the given pagebreaks. Will replace any existing page list.

Typically used indirectly from an EPUB instance with the reset_page_list or create_page_list methods.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_page_list()
...     tag = book.nav.page_list.tag
>>> tag
<nav epub:type="page-list" ...
Parameters:

pagebreaks – A list of PageBreakData instances representing the pagebreaks to include in the page list.

reset_landmarks(
entries: list[LandmarkEntryData],
) → None

Reset the landmarks in the navigation document to the given entries. Will replace any existing landmarks.

Typically used indirectly from an EPUB instance with the reset_landmarks or create_landmarks methods.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_landmarks(targets_selector='#cover, #toc')
...     tag = book.nav.landmarks.tag
>>> tag
<nav epub:type="landmarks" ...
Parameters:

entries – A list of LandmarkEntryData instances representing the landmarks to include in the landmarks.

remove(filename: str | Path) → None

Remove all references to the given filename from the navigation document

Parameters:

filename – The filename to remove references to.

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.