pypublib.chapter module

class pypublib.chapter.Chapter(href, title)[source]

Bases: object

Represents a single chapter (XHTML document) within the EPUB.

A Chapter in an EPUB book is an XHTML file which is rendered by ebook reader software. The Chapter structure stores only the BODY content of this file, which can be modified by accessing the content attribute. The HEAD part of the file is generated on the fly by inserting the stored title and stylesheet attributes in a template. This regeneration occurs every time when the read-only HTML property is accessed.

Parameters:

href (str)
title (str)

href

Filename inside the EPUB archive.

Type:: str

content

The HTML body content of the chapter.

Type:: str

styles

List of stylesheet hrefs linked in the chapter head.

Type:: list[str]

__repr__()[source]

Return a compact debug string representation of the chapter.

Returns:: Compact representation including title, href, and styles.
Return type:: str

__str__()[source]

Return a neat, human-readable chapter summary. :returns: Neat representation including title, href, and styles. :rtype: str

Return type:: str

add_style(style)[source]

Add a stylesheet href to the chapter.

Prevents duplicate stylesheets from being added.

Parameters:: style (str) – The href of the stylesheet to add.
Return type:: None

classmethod from_content(href, title, content, styles=None)[source]

Create a Chapter instance from raw HTML content string.

Strips any existing <body> tags and wraps the content in a full XHTML structure. If styles are provided, they are linked in the <head>.

Parameters:

href (str) – Filename inside the EPUB archive.
title (str) – Chapter title.
content (str) – Raw HTML content (may include <body> tags which will be stripped).
styles (str | list[str] | None, optional) – List of stylesheet hrefs or a single href as string. Defaults to None.

Returns:

A new Chapter instance with the provided content.

Return type:

Chapter

Example

>>> chapter1 = Chapter.from_content("chapter1.xhtml", "Chapter 1",
...                                 "<p>Hello world</p>",
...                                 ["styles.css"])

classmethod from_cover(name)[source]

Create a synthetic cover chapter.

Generates a Chapter containing a cover image displayed at full width and height.

Parameters:: name (str) – Filename of the cover image (used in the img src attribute).
Returns:: A new Chapter instance with cover styling applied.
Return type:: Chapter

classmethod from_html(href, html)[source]

Create a Chapter instance from a raw HTML string using lxml.html.

The parser is more forgiving than etree and can handle typical HTML errors. Automatically removes XML declarations if present.

Parameters:

href (str) – Filename inside the EPUB archive.
html (str) – HTML string (may contain typical HTML errors or XML declarations).

Returns:

A new Chapter instance parsed from the HTML string.

Return type:

Chapter

Note

This method removes XML declarations automatically, making it suitable for non-strict HTML parsing. For strict XHTML validation, use from_xhtml().

classmethod from_xhtml(href, html)[source]

Create a Chapter instance from a raw XHTML string.

The parser is stricter than lxml.html and expects well-formed XML. Uses etree.fromstring for parsing which enforces XML compliance.

Parameters:

href (str) – Filename inside the EPUB archive.
html (str) – Well-formed XHTML string.

Returns:

A new Chapter instance parsed from the XHTML string.

Return type:

Chapter

Raises:

ValueError – If the HTML is not valid XHTML or cannot be parsed.

Note

This method expects strict XML compliance. For more forgiving parsing, use from_html() instead.

property html: str

Get the full chapter HTML including HEAD and BODY.

Generates the HEAD section on the fly from the title and styles attributes, and combines it with the stored content attribute in the TEMPLATE_CHAPTER.

Returns:: Complete XHTML document as string.
Return type:: str

property images: List[str]

Get all image src attributes from img tags in this chapter.

Parses the chapter’s HTML and extracts all src attributes from <img> elements.

Returns:: List of image src paths referenced in this chapter.
Return type:: list[str]

property title: str

Get the chapter title.

Returns:: The chapter title.
Return type:: str