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 ファイルからテキストを抽出し、1 つのクリーンなドキュメントにまとめます。

サイズ検出：既知の大作のプレーンテキストダウンロードが 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 タイムアウトを上書き（デフォルトは 15 秒）

フィクションとノンフィクションの扱い

分類結果が フィクション の場合、抽出されたテキストは著者の想像力から生まれたものです。分析を次の 2 つの観点に分けることを検討してください。

観点	対象	主張の例
作品内の事実	架空の世界における事実 — 固有名詞、引用された台詞、物語上の出来事、世界のルール	「ストーカーの作品では、ドラキュラは狼、コウモリ、霧の姿に変身できます」
創作技法	現実世界の技法 — 著者が効果を生み出す方法、出版史、文学への影響	「ストーカーの書簡体形式により、読者は探偵のように物語を組み立てることになります」
余白	意図的な省略 — 著者が特に明らかにしていないこと	「小説では、ドラキュラに内面の語りが与えられることはありません」

ノンフィクション と分類された場合、主張は主題に関する現実世界の事実として扱うことができます。

既知の注意点

• 図版のある書籍ではプレーンテキストが途中で切れることがあります — 図、挿絵、数式を含む書籍（幾何学のテキスト、科学書、画集など）は、プレーンテキストのダウンロードが気付かないうちに5～10KBで切れていることがあります（Project Gutenberg のヘッダーのみ）。必ずファイルサイズを確認してください。内容が多いと分かっている書籍で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にフォールバックしてください。
• フィクションの分類が曖昧な場合があります — フィクションとノンフィクションの両方の主題（例：「Historical Fiction」と「History」）を持つ書籍は、ambiguous としてマークされます。--json を使って主題の一覧を確認し、手動で判断してください。

参考資料

• scripts/gutenberg — ポータブルなPython CLIです。外部依存関係はありません（標準ライブラリのみ）。検索、ダウンロード（txt/epub/html）、定型文の除去、EPUBテキストの抽出、フィクションの分類、パイプライン全体など、Gutenbergの主要なワークフローをすべて網羅しています。
• references/epub-extraction.md — 図版のある書籍向けのEPUBテキスト抽出の詳細です。Pythonを使った詳しい手順と、形式を判別するためのヒントも記載しています。
• Project Gutenberg — 70,000冊以上の無料電子書籍。
• Gutendex API — Project Gutenbergのカタログ向けJSONウェブAPI。