epublib.resources package

class SoupChanging(*args, **kwargs)

Bases: Protocol

on_soup_change() → None

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

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

Bases: object

Base class for all resources (i.e. files) in an EPUB file.

>>> resource = Resource(b"Hello, world!", "misc/hello.txt")
>>> resource.filename
'misc/hello.txt'
>>> resource.content
b'Hello, world!'
Parameters:

  • file – A file-like object or bytes containing the resource data.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

classmethod from_path(
filename: str | Path,
info: str | Path | ZipInfo,
) → Self

Create a Resource from a file on disk.

Parameters:

  • filename – The path to the file on disk.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

on_content_change() → None

Hook called when the content of this resource changes.

property filename: str

The absolute path to this resource in the EPUB archive. When setting, any fragment will be removed.

get_content(cache: bool = True) → bytes

Get the content of this resource. If this content hasn’t been cached yet and cache is False, the content will be read directly from the underlying file without storing it in memory.

Parameters:

  • cache – Whether to cache the content in memory for future access.

  • True. (Defaults to)

Raises:

ClosedEPUBError – If this resource has been closed.

property content: bytes

The contents of this resource.

Raises:

ClosedEPUBError – When getting the content, if this resource has been closed.

get_title() → str

Get a human-readable title for this resource.

property closed: bool

Whether this resource has been closed.

check_closed() → None

Raise an error if this resource has been closed.

Raises:

ClosedEPUBError – If this resource has been closed.

close() → None

Close this resource and free any associated resources.

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

Bases: Resource, Generic

A resource that is an XML file. Provides a soup property that contains a BeautifulSoup representation of the XML content.

Parameters:

  • file – A file-like object or bytes containing the resource data.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

soup_class

alias of BeautifulSoup

property soup: S

A BeautifulSoup representation of the XML content of this resource.

get_content(cache: bool = True) → bytes

Get the content of this resource. If this content hasn’t been cached yet and cache is False, the content will be read directly from the underlying file without storing it in memory.

Parameters:

  • cache – Whether to cache the content in memory for future access.

  • True. (Defaults to)

Raises:

ClosedEPUBError – If this resource has been closed.

on_content_change() → None

Hook called when the content of this resource changes.

get_title() → str

Get a human-readable title for this resource.

class PublicationResource(
file: IO[bytes] | bytes,
info: ZipInfo | str | Path,
media_type: MediaType | str | None = None,
)

Bases: Resource

A resource that contributes to the logic and rendering of the publication.

This includes resources like the package document, content documents (XHTML), CSS stylesheets, audio, video, images, fonts, and scripts.

This class provides the media_type attribute.

Parameters:

  • file – A file-like object or bytes containing the resource data.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

  • media_type – The media type of this resource. If not provided, it will be guessed based on the filename.

Raises:

EPUBError – If the media type is not provided and cannot be determined from the filename.

classmethod from_path(
filename: str | Path,
info: str | Path | ZipInfo,
media_type: MediaType | str | None = None,
)

Create a PublicationResource from a file on disk.

Parameters:

  • filename – The path to the file on disk.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

  • media_type – The media type of this resource. If not provided, it will be guessed based on the filename.

Raises:

EPUBError – If the media type is not provided and cannot be determined from the filename.

property is_foreign: bool

Whether this resource is a foreign resource.

property category: Category

The category of the media type of this resource.

classmethod from_resource(
other: Resource,
media_type: MediaType | str | None = None,
) → Self

Create a PublicationResource from another Resource.

Parameters:

  • other – The resource to copy.

  • media_type – The media type of the new resource. If not provided, it will be guessed based on the filename of the given resource.

Raises:

  • EPUBError – If the media type is not provided and cannot be determined from the filename of the given resource.

  • ClosedEPUBError – If the given resource has been closed.

class ContentDocument(
file: IO[bytes] | bytes,
info: ZipInfo | str | Path,
media_type: MediaType | str | None = None,
)

Bases: PublicationResource, XMLResource, Generic

A publication resource that is either a XHTML or an SVG file.

Parameters:

  • file – A file-like object or bytes containing the resource data.

  • info – A ZipInfo object or a string/Path representing the location of the resource in the EPUB archive.

  • media_type – The media type of this resource. If not provided, it will be guessed based on the filename. Must be either MediaType.XHTML (application/xhtml+xml) or MediaType.SVG (image/svg+xml).

get_title() → str

Get a human-readable title for this resource.

Submodules