epublib.nav.reset module

reset_toc(
book: ~epublib.types.BookProtocol,
targets_selector: str | None = 'h1,
h2,
h3,
h4,
h5,
h6',
include_filenames: bool = False,
spine_only: bool = True,
reset_ncx: bool | None = None,
resource_class: type[~epublib.resources.Resource] = <class 'epublib.resources.ContentDocument'>,
title: str | None = None,
) → 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")
Parameters:

  • book – The book to reset the table of contents for.

  • targets_selector – A CSS selector to find the targets for the table of contents. If None, only the resource titles will be used. Defaults to “h1, h2, h3, h4, h5, h6”.

  • include_filenames – Whether to include the resource filenames as top-level entries in the table of contents. Defaults to False.

  • spine_only – Whether to only include resources in the spine. Defaults to True. Guarantees the toc is in reading order.

  • reset_ncx – Whether to also reset the NCX file if there is one. If None (the default), the NCX file will be reset if it exists in the EPUB.

  • resource_class – The resource class to consider. Defaults to ContentDocument.

  • title – An optional title for the table of contents. If None, the existing title will be kept if there is one.

Raises:

EPUBError – If reset_ncx is True but the book has no NCX file.

reset_page_list(
book: BookProtocol,
id_format: str = 'page_{page}',
label_format: str = '{page}',
pagebreak_selector: str = '[role="doc-pagebreak"], [epub|type="pagebreak"]',
reset_ncx: bool | None = None,
)

Reset the page list in the navigation document based on the pagebreak elements in the book’s content documents. Will replace any existing page list.

Typically used indirectly from an EPUB instance with the reset_page_list.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_page_list()
Parameters:

  • book – The book to reset the page list for.

  • id_format – A format string to generate IDs for pagebreak elements that don’t have one. The string must contain a {page} placeholder which will be replaced with the page number. Defaults to “page_{page}”.

  • label_format – A format string to generate labels for the page list entries. The string must contain a {page} placeholder which will be replaced with the page number. Defaults to “{page}”.

  • pagebreak_selector – A CSS selector to find the pagebreak elements. Defaults to ‘[role=”doc-pagebreak”], [epub|type=”pagebreak”]’.

  • reset_ncx – Whether to also reset the NCX file if there is one. If None (the default), the NCX file will be reset if it exists

Raises:

EPUBError – If reset_ncx is True but the book has no NCX file.

create_page_list(
book: BookProtocol,
id_format: str = 'page_{page}',
label_format: str = '{page}',
pagebreak_selector: str = '[role="doc-pagebreak"], [epub|type="pagebreak"]',
reset_ncx: bool | None = None,
)

Create a page list in the navigation document based on the pagebreak elements in the book’s content documents.

Typically used indirectly from an EPUB instance with the create_page_list method.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.create_page_list()
Parameters:

  • book – The book to create the page list for.

  • id_format – A format string to generate IDs for pagebreak elements that don’t have one. The string must contain a {page} placeholder which will be replaced with the page number. Defaults to “page_{page}”.

  • label_format – A format string to generate labels for the page list entries. The string must contain a {page} placeholder which will be replaced with the page number. Defaults to “{page}”.

  • pagebreak_selector – A CSS selector to find the pagebreak elements. Defaults to ‘[role=”doc-pagebreak”], [epub|type=”pagebreak”]’.

  • reset_ncx – Whether to also reset the NCX file if there is one. If None (the default), the NCX file will be reset if it exists.

Raises:

EPUBError – If reset_ncx is True but the book has no NCX file, or if the book already has a page list.

reset_landmarks(
book: BookProtocol,
include_toc: bool = True,
targets_selector: str | None = None,
default_epub_type: str = 'chapter',
)

Reset the landmarks in the navigation document by detecting targets in content documents, and optionally including the TOC. Will replace existing landmarks.

Typically used indirectly from an EPUB instance with the reset_landmarks method.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_landmarks(targets_selector='#cover, #toc')

If more control is needed over which landmarks to include, use the navigation document’s reset_landmarks method directly.

>>> from epublib import EPUB
>>> from epublib.nav.util import LandmarkEntryData
>>> with EPUB(sample) as book:
...     entries = [
...         LandmarkEntryData('cover.xhtml#cover', 'Cover', 'cover'),
...         LandmarkEntryData('toc.xhtml#toc', 'Table of Contents', 'toc'),
...     ]
...     book.nav.reset_landmarks(entries)
Parameters:

  • book – The book to reset the landmarks for.

  • include_toc – Whether to include the table of contents as a landmark. Defaults to True.

  • targets_selector – A CSS selector to find the targets for the landmarks. If None, no additional landmarks will be added. Defaults to None.

  • default_epub_type – The default EPUB type to use for landmarks found via the targets_selector. Defaults to “chapter”.

create_landmarks(
book: BookProtocol,
include_toc: bool = True,
targets_selector: str | None = None,
default_epub_type: str = 'chapter',
)

Create landmarks in the navigation document by detecting targets in content documents, and optionally including the TOC. Will raise error if landmarks already exist.

Typically used indirectly from an EPUB instance with the create_landmarks method.

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     book.reset_landmarks(targets_selector='#cover, #toc')

If more control is needed over which landmarks to include, use the navigation document’s reset_landmarks method directly.

>>> from epublib import EPUB
>>> from epublib.nav.util import LandmarkEntryData
>>> with EPUB(sample) as book:
...     entries = [
...         LandmarkEntryData('cover.xhtml#cover', 'Cover', 'cover'),
...         LandmarkEntryData('toc.xhtml#toc', 'Table of Contents', 'toc'),
...     ]
...     book.nav.reset_landmarks(entries)
Parameters:

  • book – The book to reset the landmarks for.

  • include_toc – Whether to include the table of contents as a landmark. Defaults to True.

  • targets_selector – A CSS selector to find the targets for the landmarks. If None, no additional landmarks will be added. Defaults to None.

  • default_epub_type – The default EPUB type to use for landmarks found via the targets_selector. Defaults to “chapter”.