epublib.ncx package

class NCXMeta(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, name: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], content: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)])

Bases: XMLElement[NCXSoup]

A metadata item in the NCX head section.

Parameters:

  • soup – The NCX soup this element belongs to.

  • name – The name of the meta item.

  • content – The content of the meta item.

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

Bases: XMLParent[NCXMeta, NCXSoup]

The head section of the NCX file, a container of NCXMeta items.

Parameters:

soup – The NCX soup this element belongs to.

add(name: str, content: str) → NCXMeta

Add a new meta item to the head section.

Parameters:

  • name – The name of the meta item.

  • content – The content of the meta item.

Returns:

The newly created NCXMeta item.

property uid: str

Return the unique identifier of the publication.

property depth: int

Return the depth of the navigation map structure.

property total_page_count: int | None

Return the total page count of the publication.

If there are no navigable pages (represented as 0), return None.

property max_page_number: int | None

Return the largest value attribute on page targets in the page list.

If there are no navigable pages (represented as 0), return None.

class NCXDocData(soup: S, tag: bs4.element.Tag = <sentinel/>, *, text: Annotated[str, XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get='text', create='text', prefix='')], id: Annotated[str | None, XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix='')] = None)

Bases: XMLElement[NCXSoup], ABC

class NCXAuthor(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, text: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=text, create=text, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)

Bases: NCXDocData

An authorship in the NCX file.

Parameters:

  • soup – The NCX soup this element belongs to.

  • text – The name of the author.

  • id – An optional identifier for the author.

class NCXTitle(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, text: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=text, create=text, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)

Bases: NCXDocData

The title of the publication in the NCX file.

Parameters:

  • soup – The NCX soup this element belongs to.

  • text – The title of the publication.

  • id – An optional identifier for the title.

class NCXHrefElement(soup: S, tag: bs4.element.Tag = <sentinel/>, *, filename: str, href: Annotated[str, XMLAttribute(init_name='src', sync=<SyncType.ATTR: 1>, get='content', create=<staticmethod(<function NCXHrefElement.create_href_tag at 0x7a1fb1fadda0>)>, prefix='')] = '', own_filename: str, id: Annotated[str, XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix='')], text: Annotated[str, XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=<function NCXHrefElement.<lambda> at 0x7a1fb1fade40>, create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>, 'navLabel'), prefix='')])

Bases: HrefElement[NCXSoup], ABC

class NCXWithInfo(
*,
info: Annotated[str | None,
XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=<function NCXWithInfo.<lambda> at 0x7a1fb1fadf80>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navInfo'),
prefix='')] = None,
)

Bases: object

class NCXNavPoint(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, info: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.ncx.NCXWithInfo.<lambda>, create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>, 'navInfo'), prefix=)] = None, filename: str, href: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=src, sync=<SyncType.ATTR: 1>, get=content, create=~epublib.ncx.NCXHrefElement.create_href_tag, prefix=)] = '', own_filename: str, parent: ~epublib.xml_element.ParentProtocol | None = None, id: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], text: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.ncx.NCXHrefElement.<lambda>, create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>, 'navLabel'), prefix=)], play_order: ~typing.Annotated[int | None, ~epublib.xml_element.XMLAttribute(init_name=playOrder, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)

Bases: NCXHrefElement, HrefRecursiveElement[NCXNavPoint, NCXSoup], NCXWithInfo

A navigation point in NCX table of contents.

Parameters:

  • soup – The NCX soup this element belongs to.

  • href – The href of the navPoint. May include a fragment. If empty, will be calculated from filename and own_filename. One of href or filename must be given.

  • filename – The filename the navPoint points to. May include a fragment. If empty, will be calculated from href and own_filename. One of href or filename must be given.

  • own_filename – The filename of the NCX file this element belongs to.

  • id – The identifier of the navPoint.

  • text – The label of the navPoint.

  • play_order – The play order of the navPoint.

  • info – An optional info text for the navPoint.

add(
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Add a new navPoint to this element.

Parameters:

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Returns:

The newly created NCXNavPoint item.

insert(
position: int | None,
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Insert a new navPoint in a specific position of this element.

Parameters:

  • position – The position to insert the new navPoint at. If None, the new navPoint will be added at the end.

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

add_after_self(
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Add a new navPoint in this element’s parent, after this one.

Parameters:

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Raises:

EPUBError – If this element has no parent.

class NCXNavList(
soup: S,
tag: ~bs4.element.Tag = <sentinel/>,
*,
info: ~typing.Annotated[str | None,
~epublib.xml_element.XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=~epublib.ncx.NCXWithInfo.<lambda>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navInfo'),
prefix=)] = None,
own_filename: str,
text: ~typing.Annotated[str | None,
~epublib.xml_element.XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=~epublib.ncx.NCXNavList.<lambda>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navLabel'),
prefix=)] = None,
)

Bases: HrefRoot[NCXNavPoint, NCXSoup], XMLElement[NCXSoup], NCXWithInfo

A navigation list in the NCX file.

Parameters:

  • soup – The NCX soup this element belongs to.

  • own_filename – The filename of the NCX file this element belongs to.

  • text – The label of the navList.

  • info – An optional info text for the navList.

add(
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Add a new navPoint to this navList.

Parameters:

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Returns:

The newly created NCXNavPoint item.

insert(
position: int | None,
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Insert a new navPoint to this navList in a specific position.

Parameters:

  • position – The position to insert the new navPoint at. If None, the new navPoint will appended.

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Returns:

The newly created NCXNavPoint item.

class NumberUpdating(*args, **kwargs)

Bases: Protocol

class NCXNavMap(
soup: S,
tag: ~bs4.element.Tag = <sentinel/>,
*,
info: ~typing.Annotated[str | None,
~epublib.xml_element.XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=~epublib.ncx.NCXWithInfo.<lambda>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navInfo'),
prefix=)] = None,
own_filename: str,
text: ~typing.Annotated[str | None,
~epublib.xml_element.XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=~epublib.ncx.NCXNavList.<lambda>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navLabel'),
prefix=)] = None,
parent: ~epublib.ncx.NumberUpdating,
)

Bases: NCXNavList

The navigation map in the NCX file.

Parameters:

  • soup – The NCX soup this element belongs to.

  • own_filename – The filename of the NCX file this element belongs to.

  • text – The label of the navMap.

  • parent – The parent object that will be notified when the navMap changes, so it can update numbers accordingly.

  • info – An optional info text for the navMap.

classmethod from_tag(
soup: NCXSoup,
tag: Tag,
own_filename: str | Path,
parent: NumberUpdating,
) → Self

Create this XMLElement from an existing tag.

Any attributes that are not represented in the tag are passed as keyword arguments.

Parameters:

  • soup – The BeautifulSoup this element is part of.

  • tag – The existing tag to use.

  • **kwargs – Any attributes that are not represented in the tag.

Returns:

An instance of this XMLElement.

add(
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Add a new navPoint to this navMap.

Parameters:

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Returns:

The newly created NCXNavPoint item.

insert(
position: int | None,
text: str,
filename: str | Path,
id: str | None = None,
info: str | None = None,
) → NCXNavPoint

Insert a new navPoint to the navMap in a specific position.

Parameters:

  • position – The position to insert the new navPoint at. If None, the new navPoint will appended.

  • text – The label of the new navPoint.

  • filename – The filename the new navPoint points to. May include a fragment.

  • id – The identifier of the new navPoint. If None, a new identifier will be generated.

  • info – An optional info text for the new navPoint.

Returns:

The newly created NCXNavPoint item.

class NCXPageTarget(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, filename: str, href: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=src, sync=<SyncType.ATTR: 1>, get=content, create=~epublib.ncx.NCXHrefElement.create_href_tag, prefix=)] = '', own_filename: str, id: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], text: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.STRING: 2>, get=~epublib.ncx.NCXHrefElement.<lambda>, create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>, 'navLabel'), prefix=)], type: ~typing.Annotated[~typing.Literal['front', 'normal', 'special'] | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)

Bases: NCXHrefElement

A page target in the NCX page list.

Parameters:

  • soup – The NCX soup this element belongs to.

  • filename – The filename the pageTarget points to. May include a fragment. If empty, will be calculated from href and own_filename. One of href or filename must be given.

  • href – The href the pageTarget points to. May include a fragment. If empty, will be calculated from filename and own_filename. One of href or filename must be given.

  • own_filename – The filename of the NCX file this element belongs to.

  • id – The identifier of the pageTarget.

  • text – The label of the pageTarget.

  • type – The type of the pageTarget. If None, it will be inferred from the text. Can be “front” (for roman numerals), “normal” (for arabic numerals) or “special” (for anything else).

class NCXPageList(
soup: S,
tag: ~bs4.element.Tag = <sentinel/>,
*,
info: ~typing.Annotated[str | None,
~epublib.xml_element.XMLAttribute(init_name=None,
sync=<SyncType.STRING: 2>,
get=~epublib.ncx.NCXWithInfo.<lambda>,
create=functools.partial(<function create_ncx_text_tag at 0x7a1fb1f4c0e0>,
'navInfo'),
prefix=)] = None,
own_filename: str,
parent: ~epublib.ncx.NumberUpdating,
)

Bases: ParentOfHref[NCXPageTarget, NCXSoup], XMLElement[NCXSoup], NCXWithInfo

The page list in the NCX file.

Parameters:

  • soup – The NCX soup this element belongs to.

  • info – An optional info text for the pageList.

  • own_filename – The filename of the NCX file this element belongs to.

  • parent – The parent object that will be notified when the pageList changes, so it can update numbers accordingly.

property largest_page_number: int | None

Return the largest page number in the page list.

classmethod from_tag(
soup: NCXSoup,
tag: Tag,
own_filename: str | Path,
parent: NumberUpdating,
) → Self

Create this XMLElement from an existing tag.

Any attributes that are not represented in the tag are passed as keyword arguments.

Parameters:

  • soup – The BeautifulSoup this element is part of.

  • tag – The existing tag to use.

  • **kwargs – Any attributes that are not represented in the tag.

Returns:

An instance of this XMLElement.

add(
text: str,
filename: str | Path,
id: str | None = None,
type: Literal['front', 'normal', 'special'] | None = None,
) → NCXPageTarget

Add a new pageTarget to the pageList.

Parameters:

  • text – The label of the new pageTarget.

  • filename – The filename the new pageTarget points to. May include a fragment.

  • id – The identifier of the new pageTarget. If None, a new identifier will be generated.

  • type – The type of the new pageTarget. If None, it will be inferred from the text. Can be “front” (for roman numerals), “normal” (for arabic numerals) or “special” (for anything else).

Returns:

The newly created NCXPageTarget item.

insert(
position: int,
text: str,
filename: str | Path,
id: str | None = None,
type: Literal['front', 'normal', 'special'] | None = None,
) → NCXPageTarget

Insert a new pageTarget to the pageList at a specific position.

Parameters:

  • position – The position to insert the new pageTarget at.

  • text – The label of the new pageTarget.

  • filename – The filename the new pageTarget points to. May include a fragment.

  • id – The identifier of the new pageTarget. If None, a new identifier will be generated.

  • type – The type of the new pageTarget. If None, it will be inferred from the text. Can be “front” (for roman numerals), “normal” (for arabic numerals) or “special” (for anything else).

Returns:

The newly created NCXPageTarget item.

Submodules