epublib.nav package¶

class NavElement(soup: S, tag: bs4.element.Tag = <sentinel/>)¶

Bases: XMLParent[I, BeautifulSoup], XMLElement, ABC, Generic

property parent_tag: Tag | None¶: Return the parent tag of this element (i.e. the one whose direct descendants are the children of this element) or None if it does not exist.

create_parent_tag() → Tag¶: Return the parent tag of this element (i.e. the one whose direct descendants are the children of this element), creating it if it does not exist.

class NavItem(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, filename: str = '', href: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=a, create=~epublib.nav.create_href, prefix=)] = '', own_filename: str, parent: ~epublib.xml_element.ParentProtocol | None = None, text: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.nav.NavItem.<lambda>, create=~epublib.nav.create_href, prefix=)])¶

Bases: NavElement[NavItem], HrefRecursiveElement[NavItem, BeautifulSoup]

A navigation item in the navigation document.

>>> item = NavItem(
...     soup=bs4.BeautifulSoup("", "lxml"),
...     text="Chapter 1",
...     own_filename="Text/nav.xhtml",
... )
>>> item.tag
<li><span>Chapter 1</span></li>
>>> item.href = "chapter1.xhtml#heading1"
>>> item.tag
<li><a href="chapter1.xhtml#heading1">Chapter 1</a></li>
>>> item.filename
'Text/chapter1.xhtml#heading1'
>>> item.href
'chapter1.xhtml#heading1'
>>> item.add(text="Chapter 2")
NavItem(...)
>>> item.tag
<li><a href="...">...</a><ol><li><span>Chapter 2</span></li></ol></li>

Parameters:

soup – The BeautifulSoup of which this item is part of.
filename – The filename of the navigation item. If empty, will be calculated from href and own_filename. One of filename or href must be provided.
href – The href of the navigation item. If empty, will be calculated from filename and own_filename. One of filename or href must be provided.
own_filename – The filename of the document containing this item.
parent – The parent navigation item (or NavRoot).
text – The text of the navigation item.

create_tag() → None¶: Create a new tag for this element.

add( text: str, filename: str = '', href: str = '', ) → NavItem¶

Add a new navigation item as a child of this item.

Parameters:

text – The text of the new navigation item.
filename – The filename of the new navigation item. If empty, will be calculated from href and self.own_filename. One of filename or href must be provided.
href – The href of the new navigation item. If empty, will be calculated from filename and self.own_filename. One of filename or href must be provided.

Returns:

The newly created navigation item.

insert( position: int | None, text: str, filename: str = '', href: str = '', ) → NavItem¶

Insert a new navigation item as a child of this item at the given position.

Parameters:

position – The position to insert the new navigation item at. If None, the item will be added at the end.
text – The text of the new navigation item.
filename – The filename of the new navigation item. If empty, will be calculated from href and self.own_filename. One of filename or href must be provided.
href – The href of the new navigation item. If empty, will be calculated from filename and self.own_filename. One of filename or href must be provided.

add_after_self( text: str, filename: str = '', href: str = '', ) → NavItem¶

Add a new navigation item after this item in the parent’s list of items.

Parameters:

text – The text of the new navigation item.
filename – The filename of the new navigation item. If empty, will be calculated from href and self.own_filename. One of filename or href must be provided.
href – The href of the new navigation item. If empty, will be calculated from filename and self.own_filename. One of filename or href must be provided.

Raises:

EPUBError – If this element has no parent.

class NavRoot( soup: S, tag: bs4.element.Tag = <sentinel/>, *, own_filename: str, title: Annotated[str | None, XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=<function NavRoot.<lambda> at 0x7a1fb1f92fc0>, create=<function NavRoot.<lambda> at 0x7a1fb1f93060>, prefix='')] = None, )¶

Bases: NavElement[NavItem], HrefRoot[NavItem, BeautifulSoup], ABC

create_tag() → None¶: Create a new tag for this element.

property text: str | None¶: The text of this navigation root’s title.

add( text: str, filename: str = '', href: str = '', ) → NavItem¶

Insert a new navigation item as a child of this element.

Parameters:

text – The text of the new navigation item.
filename – The filename of the new navigation item. If empty, will be calculated from href and self.own_filename. One of filename or href must be provided.
href – The href of the new navigation item. If empty, will be calculated from filename and self.own_filename. One of filename or href must be provided.

insert( position: int | None, text: str, filename: str = '', href: str = '', ) → NavItem¶

Insert a new navigation item as a child of this element at the given position

Parameters:

position – The position to insert the new navigation item at. If None, the item will be added at the end.
text – The text of the new navigation item.
filename – The filename of the new navigation item. If empty, will be calculated from href and self.own_filename. One of filename or href must be provided.
href – The href of the new navigation item. If empty, will be calculated from filename and self.own_filename. One of filename or href must be provided.

class TocRoot( soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, own_filename: str, title: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.nav.NavRoot.<lambda>, create=~epublib.nav.NavRoot.<lambda>, prefix=)] = None, )¶

Bases: NavRoot

The root of the table of contents of the navigation document.

>>> toc = TocRoot(
...     soup=bs4.BeautifulSoup("", "lxml"),
...     title="Table of Contents",
...     own_filename="Text/nav.xhtml",
... )

>>> toc.tag
<nav epub:type="toc" id="toc" role="doc-toc"><h1>Table of Contents</h1></nav>
>>> toc.add("Chapter 1", href="chapter1.xhtml#heading1")
NavItem(...)
>>> toc.tag.ol
<ol><li><a href="chapter1.xhtml#heading1">Chapter 1</a></li></ol>

Parameters:

soup – The BeautifulSoup of which this TOC is part of.
own_filename – The filename of the document containing this TOC.
title – The title of the TOC.

class PageListRoot( soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, own_filename: str, title: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.nav.NavRoot.<lambda>, create=~epublib.nav.NavRoot.<lambda>, prefix=)] = None, )¶

Bases: NavRoot

The page list in the navigation document.

>>> pl = PageListRoot(
...     soup=bs4.BeautifulSoup("", "lxml"),
...     own_filename="Text/nav.xhtml",
... )

>>> pl.tag
<nav epub:type="page-list" hidden="" id="page-list"></nav>
>>> pl.add("Chapter 1", href="chapter1.xhtml#heading1")
NavItem(...)
>>> pl.tag.ol
<ol><li><a href="chapter1.xhtml#heading1">Chapter 1</a></li></ol>

Parameters:

soup – The BeautifulSoup of which this page list is part of.
own_filename – The filename of the document containing this page list.
title – The title of the page list.

class LandmarksRoot( soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, own_filename: str, title: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.nav.NavRoot.<lambda>, create=~epublib.nav.NavRoot.<lambda>, prefix=)] = None, )¶

Bases: NavRoot

The page list in the navigation document.

>>> lm = LandmarksRoot(
...     soup=bs4.BeautifulSoup("", "lxml"),
...     own_filename="Text/nav.xhtml",
... )

>>> lm.tag
<nav epub:type="landmarks" hidden="" id="landmarks"></nav>
>>> lm.add("Chapter 1", href="chapter1.xhtml#heading1")
NavItem(...)
>>> lm.tag.ol
<ol><li><a href="chapter1.xhtml#heading1">Chapter 1</a></li></ol>

Parameters:

soup – The BeautifulSoup of which these landmarks are part of.
own_filename – The filename of the document containing these landmarks.
title – The title of the landmarks.

epublib.nav package¶

Submodules¶