epublib.package.spine module

class SpineItemRef(soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, properties: ~typing.Annotated[list[str] | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, idref: ~typing.Annotated[~epublib.identifier.EPUBId, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], id: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, linear: ~typing.Annotated[bool | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)

Bases: WithProperties, XMLElement

An item reference in the EPUB spine.

Example:

>>> import bs4
>>> soup = bs4.BeautifulSoup("", "xml")
>>> item = SpineItemRef(
...     soup=soup,
...     idref="chapter15",
... )
>>> item.tag
<itemref idref="chapter15"/>

Create from existing tag:

>>> soup = bs4.BeautifulSoup("<itemref idref='chapter15' id='chapter15' />", "xml")
>>> tag = soup.find("itemref")
>>> item = SpineItemRef.from_tag(soup, tag)
>>> item.tag is tag
True
>>> item.idref
'chapter15'
Parameters:

  • soup – The BeautifulSoup object to use for creating XML tags.

  • idref – The ID of the item in the manifest.

  • id – The ID of the itemref element. Defaults to None.

  • linear – Whether the item is part of the linear reading order. Defaults to None, which means it is linear (set to false to make it non-linear).

  • properties – A space-separated list of properties for the itemref.

create_tag() → None

Create a new tag for this element.

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

Bases: XMLParent[SpineItemRef, BeautifulSoup]

The EPUB spine, which defines the linear reading order of the book.

Typical usage is from an EPUB object:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     print(book.spine[0].idref)
chapter1
Parameters:

  • soup – The BeautifulSoup object of which this spine is part of.

  • tag – The BeautifulSoup Tag object representing the spine. If not given, a new tag will be created.

default_item_type

alias of SpineItemRef

add(
idref: str | EPUBId,
id: str | None = None,
linear: bool | None = None,
properties: str | None = None,
)

Add a new item to the spine.

Parameters:

  • idref – The ID of the item in the manifest.

  • id – The ID of the itemref element. Defaults to None.

  • linear – Whether the item is part of the linear reading order. Defaults to None, which means it is linear (set to false to make it non-linear).

  • properties – A space-separated list of properties for the itemref.

insert(
position: int,
idref: str | EPUBId,
id: str | None = None,
linear: bool | None = None,
properties: str | None = None,
)

Insert a new item at the given position in the spine.

Parameters:

  • position – The position to insert the item at.

  • idref – The ID of the item in the manifest.

  • id – The ID of the itemref element. Defaults to None.

  • linear – Whether the item is part of the linear reading order. Defaults to None, which means it is linear (set to false to make it non-linear).

  • properties – A space-separated list of properties for the itemref.

get_position(
idref: str | EPUBId,
) → int | None

Get the position of the item with the given ID in the spine.

Parameters:

idref – The ID of the item to be searched for in the manifest.

Returns:

The position of the item in the spine, or None if not found.

remove(idref: str | EPUBId) → None

Remove the item with the given ID from the spine, if it exists.

Parameters:

idref – The ID of the item to be removed from the manifest.

move_item(
item: int | str | EPUBId | SpineItemRef,
new_position: int,
) → None

Move the given item to a new position in the spine.

Parameters:

  • item – The item to be moved, specified by its index, ID, or SpineItemRef.

  • new_position – The new position for the item.

Raises:

EPUBError – If the item is not found in the spine.

reorder(
items: Sequence[SpineItemRef],
) → None

Reorder the spine items to match the given list.

Parameters:

items – The new order of spine items.

Raises:

EPUBError – If the new items do not match the current spine items, or if there are duplicates in the new items.