epublib.package.resource module

class PackageDocument(
file: IO[bytes] | bytes,
info: ZipInfo | str | Path,
)

Bases: XMLResource[PackageDocumentSoup], SoupChanging

The package document of the EPUB file, sometimes known as the ‘content.opf’ file.

Typically used via an EPUB object:

>>> from epublib import EPUB
>>> with EPUB(sample) as book:
...     print(book.package_document)
...     print(book.package_document.metadata)
...     print(book.package_document.manifest)
...     print(book.package_document.spine)
PackageDocument(content.opf)
BookMetadata(... items)
BookManifest(... items)
BookSpine(... items)
Parameters:

  • file – The file-like object or bytes representing the package document.

  • info – The ZipInfo, filename, or Path of the package document within the EPUB archive.

soup_class

alias of PackageDocumentSoup

property manifest: BookManifest

The manifest in this package.

property metadata: BookMetadata

The metadata in this package.

property spine: BookSpine

The spine in this package.

property guide: BookGuide | None

The guide in this package, if any, else None.

remove(
resource: Resource | str | Path | EPUBId | ManifestItem | SpineItemRef,
) → None

Remove items referencing a resource from the manifest, spine and guide, if it exists. If the resource is marked as cover image in the manifest, remove the corresponding item in the metadata.

Parameters:

resource – The resource to remove, as a filename (str or Path), an identifier, a resource, a manifest item or a spine item.

on_soup_change() → None

Trigger reparsing of the internal representations of the resource. Used after the soup is modified directly.

on_content_change() → None

Hook called when the content of this resource changes.

resource_to_manifest_item(
resource: Resource,
package: PackageDocument,
identifier: EPUBId | str | None = None,
media_type: MediaType | str | None = None,
fallback: str | None = None,
media_overlay: str | None = None,
is_nav: bool = False,
is_cover: bool = False,
properties: list[str] | None = None,
detect_properties: bool = True,
) → ManifestItem

Create a manifest item from a resource.

Parameters:

  • resource – The resource to create a manifest item for.

  • package – The package document to create the manifest item in.

  • identifier – The identifier to use for the manifest item. If None, a new identifier will be generated. Defaults to None.

  • media_type – The media type to use for the manifest item. If None, the media type will be determined from the resource. Defaults to None.

  • fallback – The fallback identifier to use for the manifest item. Defaults to None.

  • media_overlay – The media overlay identifier to use for the manifest item. Defaults to None.

  • is_nav – Whether the resource is a navigation document. Defaults to False.

  • is_cover – Whether the resource is a cover image. Defaults to False.

  • properties – List of properties to set on the manifest item. Defaults to None.

  • detect_properties – Whether to detect properties from the resource. Defaults to True.

Returns:

The created manifest item.

Raises:

EPUBError – If any of the following occurr: - The identifier is already used in the manifest. - The media type cannot be determined from the resource. - is_nav is set to True, but the resource is not a content document. - is_cover is set to True, but the resource is not an image.