gutenberg

Gutenberg — 公版图书工具包

搜索、下载并提取 Project Gutenberg 中的纯文本——这里有 70,000 多本免费的公版电子书。提供便携式 Python CLI，无需任何外部依赖。

快速开始

# Search for books
python3 scripts/gutenberg search "Moby Dick"

# Download by Gutenberg ID (plain text)
python3 scripts/gutenberg download 2701 --format txt

# Download EPUB (for illustrated books)
python3 scripts/gutenberg download 2701 --format epub

# Extract clean text (strips PG boilerplate)
python3 scripts/gutenberg extract 2701

# Classify fiction vs non-fiction
python3 scripts/gutenberg classify 2701

# Full pipeline: search → download → extract
python3 scripts/gutenberg pipeline "Alice's Adventures in Wonderland"

工作原理

Project Gutenberg 提供多种格式的 70,000 多本免费公版电子书。gutendex API（https://gutendex.com）提供免费的免身份验证 JSON 目录。无需 API 密钥——使用 curl 或此 CLI 即可。

数据流

User provides title/ID/author
       ↓
gutendex API search → pick book by ID
       ↓
Download plain text (preferred) or EPUB (fallback for illustrated books)
       ↓
Strip PG boilerplate → clean text
       ↓
Classify fiction/non-fiction → extract content

CLI 参考

search — 按关键词查找图书

python3 scripts/gutenberg search "Moby Dick"
python3 scripts/gutenberg search "Dracula" --limit 5
python3 scripts/gutenberg search "Sherlock Holmes" --json
python3 scripts/gutenberg search "Alice" --language en

返回：ID、书名、作者（含生卒年份）、语言、主题、下载次数。结果按下载次数排序（最受欢迎的排在前面）。

metadata — 按 ID 获取图书的完整元数据

python3 scripts/gutenberg metadata 2701          # Moby Dick
python3 scripts/gutenberg metadata 11            # Alice's Adventures
python3 scripts/gutenberg metadata 1342          # Pride and Prejudice
python3 scripts/gutenberg metadata 1342 --json   # JSON-only output

返回：书名、作者、语言、主题、书架分类、摘要、版权状态、下载次数以及所有可用格式的 URL。

download — 按 Gutenberg ID 下载图书

# Plain text (UTF-8, preferred — works for most books)
python3 scripts/gutenberg download 2701 --format txt

# EPUB with images (for illustrated/scientific books)
python3 scripts/gutenberg download 2701 --format epub

# HTML (alternative fallback)
python3 scripts/gutenberg download 2701 --format html

# Specify output directory
python3 scripts/gutenberg download 2701 --format txt --output ./books/

文件将保存为 ./gutenberg-<id>.<ext>（或保存到 --output 指定的路径）。较大的图书可能需要稍等片刻。

extract — 去除 PG 的模板文本并生成纯文本

python3 scripts/gutenberg extract 2701            # from downloaded txt
python3 scripts/gutenberg extract 2701 --input ./gutenberg-2701.txt
python3 scripts/gutenberg extract 2701 --format epub  # extract from EPUB

输出：去除 Project Gutenberg 许可页眉和页脚的纯文本。提取 EPUB（插图书籍）时，会从所有 XHTML 文件中提取文本，并合并为一份清理后的文档。

大小检测：对于已知篇幅较长的图书，如果纯文本下载文件小于 50KB，则会发出警告，提示文本可能被截断，并建议使用 EPUB 模式。

classify — 分类为虚构类或非虚构类

python3 scripts/gutenberg classify 2701
python3 scripts/gutenberg classify 2701 --json

根据图书的主题和书架分类进行分类：

• 虚构类信号： “Fiction”“novels”“short stories”“poetry”“drama”“fantasy”“horror”
• 非虚构类信号： “Essays”“History”“Philosophy”“Biography”“Science”“Religion”

返回：fiction、non-fiction 或 ambiguous（并说明原因）。

pipeline — 完整获取流程

python3 scripts/gutenberg pipeline "Moby Dick"                           # search first
python3 scripts/gutenberg pipeline 2701                                   # by known ID
python3 scripts/gutenberg pipeline 2701 --clean /tmp/pipeline-output/     # save cleaned text

执行：搜索（如果提供书名）→ 元数据 → 下载（txt）→ 检查大小 → 提取（或回退到 EPUB）→ 分类。最后输出执行摘要。

全局标志

标志	作用
--json	输出机器可读的 JSON，而不是便于阅读的文本
--quiet	隐藏诊断输出
--dry-run	显示将要执行的操作，但不实际执行
--output ./dir	将下载文件保存到指定目录
--timeout 30	覆盖 API 超时时间（默认 15s）

虚构类与非虚构类的处理

当分类结果为虚构类时，提取的文本来自作者的想象。可考虑将分析拆分为两条路径：

路径	涵盖内容	声明示例
正典	虚构世界中的事实——专有名词、引用语句、故事事件、世界规则	“在 Stoker 的文本中，Dracula 可以化身为狼、蝙蝠和雾”
创作技巧	现实世界中的技法——作者如何达到创作效果、出版史、文学影响	“Stoker 的书信体形式迫使读者像调查员一样拼凑叙事”
留白	刻意省略的内容——作者明显未加说明之处	“小说从未赋予 Dracula 内心独白”

当分类为非虚构类时，可将相关声明视为对主题内容的现实事实陈述。

已知问题

• 带插图书籍的纯文本会被截断 — 带有图表、插图或公式的书籍（几何学教材、科学著作、艺术书籍）下载的纯文本可能会被悄悄截断至 5-10KB（仅有 PG 页眉）。请务必检查文件大小。已知内容丰富的书籍若文件小于 50KB → 改用 EPUB 提取。pipeline 命令会自动执行此检查。
• Gutendex 可能响应缓慢或超时 — 该 API 是免费服务，查询较冷门的书籍时可能会比较慢。CLI 的默认超时时间为 15 秒。响应较慢时可使用 --timeout 30，或直接访问 https://www.gutenberg.org/ebooks/<id> 作为备用方案。
• HTML 下载包含导航标记 — HTML 下载内容包含网站导航和格式标记。为获得干净的文本提取结果，建议优先使用纯文本或 EPUB。
• 某些格式 URL 可能对冷门书籍返回 404 — 并非每本书都提供所有格式。CLI 会先尝试 UTF-8 纯文本，再回退到 US-ASCII，然后尝试 -0.txt 文件路径，接着尝试 EPUB，最后尝试 HTML。download 命令会报告实际获取的格式。
• 速率限制 — Gutendex 无需身份验证，但有速率限制。快速连续请求超过 10 次时，请在批量请求之间使用 sleep 1。
• utf-8 与 us-ascii — Gutendex 会同时返回 text/plain; charset=utf-8 和 text/plain; charset=us-ascii URL。优先使用 UTF-8；如果 UTF-8 URL 返回 404，则回退到 US-ASCII。
• 小说分类存在歧义 — 同时具有小说和非小说主题的书籍（例如“历史小说”+“历史”）会被标记为 ambiguous。使用 --json 查看主题列表并手动判断。

参考资料

• scripts/gutenberg — 可移植的 Python CLI。无需任何外部依赖（仅使用标准库）。涵盖所有主要的 Gutenberg 工作流：搜索、下载（txt/epub/html）、去除模板文本、提取 EPUB 文本、小说分类以及完整处理流程。
• references/epub-extraction.md — 面向带插图书籍的 EPUB 文本提取详情，包含扩展版 Python 操作指南和格式检测技巧。
• Project Gutenberg — 70,000 多本免费电子书。
• Gutendex API — Project Gutenberg 目录的 JSON Web API。