`hutool.extra.epub`¶

EPUB 生成工具类，支持 ebooklib / mkepub / pypub3 三引擎。

Module Contents¶

Classes¶

`Epub`	EPUB 生成基类（抽象接口）。
`MkEpub`	基于 mkepub 的 EPUB 实现。
`EbooklibEpub`	基于 ebooklib 的 EPUB 实现。
`PyPub3Epub`	基于 pypub3 的 EPUB 实现。
`EpubFactory`	EPUB 工厂：统一入口，按引擎名称创建实例。

Functions¶

`_detect_image_format`	从 magic bytes 推断图片格式（PIL 不可用时的后备方案）。
`register_engine`	类装饰器：将实现类注册到引擎注册表。

Data¶

`logger`
`_HAS_EBOOKLIB`
`_HAS_MKEPUB`
`_HAS_PYPUB3`
`_MAGIC_FORMATS`
`_ENGINE_REGISTRY`

API¶

hutool.extra.epub.logger = 'getLogger(...)'¶

hutool.extra.epub._HAS_EBOOKLIB = False¶

hutool.extra.epub._HAS_MKEPUB = False¶

hutool.extra.epub._HAS_PYPUB3 = False¶

hutool.extra.epub._MAGIC_FORMATS = [(b'\xff\xd8\xff', 'jpeg'), (b'\x89PNG', 'png'), (b'GIF8', 'gif'), (b'RIFF', 'webp')]¶

hutool.extra.epub._detect_image_format(data: bytes) → Optional[str]¶: 从 magic bytes 推断图片格式（PIL 不可用时的后备方案）。

hutool.extra.epub._ENGINE_REGISTRY: Dict[str, Type[hutool.extra.epub.Epub]] = None¶

hutool.extra.epub.register_engine(name: str)¶: 类装饰器：将实现类注册到引擎注册表。

class hutool.extra.epub.Epub(epub_name: str, css_style: Optional[str] = None, xhtml_template: Optional[str] = None)¶

Bases: abc.ABC

EPUB 生成基类（抽象接口）。

使用方式（推荐通过 EpubFactory 创建）:

epub = EpubFactory.create(
    engine="ebooklib",   # 或 "mkepub"
    epub_name="小说名",
    author="作者",
    cover=cover_bytes,   # 可选
    language="zh",
)
epub.add_page("第一章", ["正文行1", "正文行2", img_bytes])
epub.save("/path/to/dir")  # 或 Path 对象

Initialization

初始化 EPUB 基类。

参数:

epub_name – 书名
css_style – 自定义 CSS 样式
xhtml_template – 自定义章节 XHTML 模板

_DEFAULT_CSS = 'body{margin:5%;text-align:justify;font-size:medium;}code{font-family:monospace;}h1,h2,h3,h4,h5,h6{te...'¶

_DEFAULT_XHTML = '<section id="{title}" class="level1" data-number="{chapter_no}"><h1 data-number="{chapter_no}">{titl...'¶

property chapter_no: int¶: 当前章节序号。

add_page(title: str, body: Union[str, bytes, List[Union[str, bytes]]]) → None¶

添加章节。

参数:

title – 章节标题
body –
内容，支持三种形式：
- str — 纯文本，作为单段落
- bytes — 图片二进制，作为图片页
- list — 混合列表，str 元素按段落、bytes 元素按图片处理

add_image_page(title: str, img: Union[bytes, List[bytes]]) → None¶

添加纯图片章节（漫画模式）。

参数:

title – 章节标题
img – 单张图片二进制或图片二进制列表

save(path: Union[str, pathlib.Path]) → pathlib.Path¶

保存 EPUB 文件。

参数:: path – 目录路径（自动以书名命名）或完整文件路径
返回:: 实际保存的文件路径

static to_image_html(image_content: bytes) → str¶

将图片二进制转为内联 HTML <img> 标签。

PIL 可用时自动检测图片格式；不可用时从 magic bytes 推断。

参数:: image_content – 图片二进制数据
返回:: 包含 base64 内联图片的 HTML 字符串

abstract property book: Any¶: 获取底层引擎的 book 对象。

abstract add_image(name: str, img: bytes) → Any¶

添加图片资源。

参数:

name – 图片名称（不含扩展名）
img – 图片二进制数据

返回:

图片路径或标识（引擎相关）

abstract _add_item(title: str, content: str) → None¶

添加章节内容（引擎实现）。

参数:

title – 章节标题
content – HTML 正文

abstract _write_epub(path: str) → None¶

写入 EPUB 文件（引擎实现）。

参数:: path – 文件路径

class hutool.extra.epub.MkEpub(epub_name: str, author: Optional[Union[str, List[str]]] = None, cover: Optional[bytes] = None, css_style: Optional[str] = None, xhtml_template: Optional[str] = None)¶

Bases: hutool.extra.epub.Epub

基于 mkepub 的 EPUB 实现。

轻量级，适合简单的文本+图片 EPUB。需要安装：pip install mkepub

Initialization

初始化 MkEpub 引擎。

参数:

epub_name – 书名
author – 作者（字符串或列表）
cover – 封面图片二进制数据
css_style – 自定义 CSS
xhtml_template – 自定义章节模板

property book: Any¶

add_image(name: str, img: bytes) → None¶

_add_item(title: str, content: str) → None¶

_write_epub(path: str) → None¶

class hutool.extra.epub.EbooklibEpub(epub_name: str, author: Optional[Union[str, List[str]]] = None, cover: Optional[bytes] = None, css_style: Optional[str] = None, xhtml_template: Optional[str] = None, language: str = 'zh', direction: str = 'default')¶

Bases: hutool.extra.epub.Epub

基于 ebooklib 的 EPUB 实现。

功能更全面，支持目录、CSS、多语言、阅读方向等。需要安装：pip install ebooklib

Initialization

初始化 Ebooklib 引擎。

参数:

epub_name – 书名
author – 作者（字符串或列表）
cover – 封面图片二进制数据
css_style – 自定义 CSS
xhtml_template – 自定义章节模板
language – 语言代码（如 zh、en）
direction – 阅读方向（ltr / rtl / default）

_init_book(epub_name: str, author: Optional[Union[str, List[str]]], cover: Optional[bytes], language: str, direction: str) → Any¶: 初始化 ebooklib EpubBook 对象。

property book: Any¶

add_image(name: str, img: bytes) → str¶

_add_item(title: str, content: str) → None¶

_write_epub(path: str) → None¶

class hutool.extra.epub.PyPub3Epub(epub_name: str, author: Optional[Union[str, List[str]]] = None, cover: Optional[bytes] = None, css_style: Optional[str] = None, xhtml_template: Optional[str] = None, language: str = 'zh')¶

Bases: hutool.extra.epub.Epub

基于 pypub3 的 EPUB 实现。

自动生成封面，支持自定义 CSS 和 base64 内联图片。需要安装：pip install pypub3

Initialization

初始化 pypub3 引擎。

参数:

epub_name – 书名
author – 作者（字符串或列表）
cover – 封面图片二进制数据（暂不支持，pypub3 自动生成封面）
css_style – 自定义 CSS 样式
xhtml_template – 自定义章节模板（pypub3 不支持）
language – 语言代码（如 zh、en）

property book: Any¶

add_image(name: str, img: bytes) → None¶: pypub3 使用 base64 内联图片，无需单独注册资源。

_add_item(title: str, content: str) → None¶

_write_epub(path: str) → None¶

class hutool.extra.epub.EpubFactory¶

EPUB 工厂：统一入口，按引擎名称创建实例。

支持通过 register_engine() 自定义注册新引擎。

示例:

epub = EpubFactory.create("ebooklib", epub_name="小说", author="作者")

static create(engine: str = 'ebooklib', **kwargs: Any) → hutool.extra.epub.Epub¶

创建 EPUB 实例。

参数:

engine – 引擎名称（"ebooklib" 或 "mkepub"）
kwargs – 传递给对应引擎 __init__ 的参数

返回:

Epub 实例

抛出:

ValueError – 不支持的引擎名称
ImportError – 引擎对应的库未安装

static available_engines() → List[str]¶

列出当前可用（已安装）的引擎名称。

返回:: 引擎名称列表

hutool.extra.epub¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`hutool.extra.epub`¶