epublib.package.manifest module¶

class ManifestItem(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=None, create=None, prefix=)] = '', own_filename: str, properties: ~typing.Annotated[list[str] | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, id: ~typing.Annotated[~epublib.identifier.EPUBId, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], media_type: ~typing.Annotated[str, ~epublib.xml_element.XMLAttribute(init_name=media-type, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)], fallback: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=None, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None, media_overlay: ~typing.Annotated[str | None, ~epublib.xml_element.XMLAttribute(init_name=media-overlay, sync=<SyncType.ATTR: 1>, get=None, create=None, prefix=)] = None)¶

Bases: WithProperties, HrefElement

An item in the EPUB manifest. Filename (absolute path) and href (relative path) are kept in sync.

Creating item with specific attributes:

>>> from epublib.media_type import MediaType
>>> soup = bs4.BeautifulSoup("", "xml")
>>> item = ManifestItem(
...     soup=soup,
...     filename="chapter15.xhtml",
...     id="chapter15",
...     media_type=MediaType.XHTML,
...     own_filename="base/content.opf"
... )
>>> item.tag
<item href="../chapter15.xhtml" ...>

Creating item from tag:

>>> soup = bs4.BeautifulSoup(
...     "<item href='chapter15.xhtml' id='chapter15' media-type='application/xhtml+xml'/>",
...     "xml"
... )
>>> tag = soup.find("item")
>>> item = ManifestItem.from_tag(soup, tag, own_filename="base/content.opf")
>>> item.tag is tag
True

Parameters:

soup – The BeautifulSoup object of wich this item is part of.
filename – The filename of the resource this item references. If not given, will be derived from href and own_filename.
href – The href of the resource this item references. If not given, it will be derived from filename and own_filename. At least one of filename and href should be provided
id – The unique identifier of this item.
media_type – The media type of the resource this item references.
fallback – The id of the item that is the fallback for this item, if any. defaults to None.
media_overlay – The id of the item that is the media overlay for this item, if any. defaults to None.
properties – A list of properties for this item, if any. defaults to None.

class BookManifest( soup: S, tag: ~bs4.element.Tag = <sentinel/>, *, own_filename: str, )¶

Bases: ParentOfHref[ManifestItem, BeautifulSoup]

The EPUB manifest, which is a container of all resources in the book.

Typical usage is from an EPUB object:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     item = book.manifest.items[0]
...     item = book.manifest["Text/chapter1.xhtml"]
...     item = book.manifest.get(EPUBId("chapter1"))
...     print(item.id, item.filename, item.media_type)
chapter1 Text/chapter1.xhtml application/xhtml+xml

But can be created directly as well:

>>> manifest = BookManifest(soup=bs4.BeautifulSoup("", "xml"), own_filename="content.opf")
>>> manifest
BookManifest(0 items)
>>> manifest.add("chapter15.xhtml", id="chapter15")
ManifestItem(filename='chapter15.xhtml', ..., id='chapter15', ...)
>>> manifest[0].media_type
'application/xhtml+xml'

Parameters:

soup – The BeautifulSoup object of which this manifest is part of.
tag – The tag representing this manifest. If not given, a new tag will be created.
own_filename – The filename of the package document containing this manifest.

property nav: ManifestItem¶

Return the navigation document item, i.e. the only item containing the “nav” property.

Raises:: EPUBError – If no navigation document is found in the manifest.

property cover_image: ManifestItem | None¶: Return the cover image item, i.e. the item containing the “cover-image” property, or None if no such item exists.

Create a new manifest item and add it to the manifest.

Parameters:

filename – The filename of the resource to add.
id – The unique identifier of the item. If not given, it will be generated from the filename.
media_type – The media type of the resource. If not given, it will be guessed from the filename.
fallback – The id of the item that is the fallback for this item, if any. defaults to None.
media_overlay – The id of the item that is the media overlay for this item, if any. defaults to None.
properties – A list of properties for this item, if any. defaults to None.

Returns:

The created and added item.

Raises:

EPUBError – If the media type could not be detected, or if an item with the same id or filename already exists in the manifest.

add_item( item: ManifestItem, ) → ManifestItem¶

Add an item to the manifest.

Parameters:

item – The item to add.

Returns:

The added item.

Raises:

EPUBError – If item itself or another item with the same id or
filename already exists in the manifest. –

get( name: ItemIdentifier, ignore_fragment: bool = True, ) → ManifestItem | None¶

Get an item from the manifest by its filename, id, corresponding spine item or corresponding resource.

Parameters:

name – The identifier of the item to get. Can be a filename (str or Path), an EPUBId, a SpineItemRef or a Resource.
ignore_fragment – Whether to ignore URL fragments when looking for the item. Defaults to True.

Returns:

The found item, or None if no such item exists.

remove( filename: ItemIdentifier, ignore_fragment: bool = True, ) → None¶

Remove an item from the manifest, if it exists, looking it up by its filename, id, corresponding spine item or corresponding resource.

Parameters:

filename – The identifier of the item to remove. Can be a filename (str or Path), an EPUBId, a SpineItemRef or a Resource.
ignore_fragment – Whether to ignore URL fragments when looking for the item. Defaults to True.

Returns:

The removed item, or None if no such item existed.