Metadata-Version: 2.4
Name: bookget
Version: 0.4.0
Summary: Download and parse ancient Chinese book resources from digital libraries
Author: 开源古籍 (open-guji)
License-Expression: Apache-2.0
Keywords: ancient-books,digital-library,downloader,classical-chinese
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8
Requires-Dist: requests>=2.28
Requires-Dist: opencc>=1.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == "browser"
Provides-Extra: tiles
Requires-Dist: Pillow>=10.0; extra == "tiles"
Provides-Extra: ia
Requires-Dist: internetarchive>=4.0; extra == "ia"
Dynamic: license-file

# Bookget

古籍数字资源下载与管理工具，支持从 37 个数字图书馆网站下载古籍图片和文字资源（包括 IIIF 2.x / 3.0 manifest）。全异步架构，插件式适配器设计。

## 支持的网站

共 **37** 个站点适配器（其中多数走 IIIF）。下表由适配器注册表自动生成，新增适配器后请重新生成。

### 中国大陆

| 网站 | 域名 | 图片 | PDF | 文字 | 搜索 |
|------|------|:----:|:---:|:----:|:----:|
| 中华古籍智慧化服务平台 | `guji.nlc.cn` | ✓ |  | ✓ |  |
| 中國國家圖書館·讀者雲門戶 | `read.nlc.cn` |  | ✓ |  |  |
| 识典古籍 | `shidianguji.com` | ✓ |  | ✓ | ✓ |
| 中国哲学书电子化计划 (CText) | `ctext.org` | ✓ |  | ✓ | ✓ |

### 日本

| 网站 | 域名 | 图片 | PDF | 文字 | 搜索 |
|------|------|:----:|:---:|:----:|:----:|
| 国立国会図書館 (NDL) | `dl.ndl.go.jp` | ✓ |  |  |  |
| 京都大学贵重资料数字档案馆 (Kyoto RMDA) | `rmda.kulib.kyoto-u.ac.jp` | ✓ |  |  |  |
| 東京国立博物館 (TNM) | `webarchives.tnm.jp` | ✓ |  |  |  |
| 国書データベース (NIJL Kokusho) | `kokusho.nijl.ac.jp` | ✓ |  |  |  |
| 庆应义塾大学数字典藏 (Keio) | `dcollections.lib.keio.ac.jp` | ✓ |  |  |  |
| 东洋文库 (Toyo Bunko / NII-DSR) | `dsr.nii.ac.jp` | ✓ |  |  |  |
| e国宝 (e-Museum) | `emuseum.nich.go.jp` | ✓ |  |  |  |
| 国立歴史民俗博物館 (khirin-a) | `khirin-a.rekihaku.ac.jp` | ✓ |  |  |  |
| 龍谷大學圖書館 (Ryukoku) | `da.library.ryukoku.ac.jp` | ✓ |  |  |  |

### 港台

| 网站 | 域名 | 图片 | PDF | 文字 | 搜索 |
|------|------|:----:|:---:|:----:|:----:|
| 臺灣國家圖書館 (NCL Taiwan, rbook.ncl.edu.tw) | `rbook.ncl.edu.tw` | ✓ |  |  |  |
| 臺灣故宮博物院 (NPM Taipei) | `digitalarchive.npm.gov.tw` | ✓ |  |  |  |
| 漢籍全文資料庫 (Hanchi) | `hanchi.ihp.sinica.edu.tw` |  |  | ✓ |  |
| 臺灣華文電子書庫 | `taiwanebook.ncl.edu.tw` | ✓ | ✓ |  |  |
| 香港大学数字图书馆 (HKU) | `digitalrepository.lib.hku.hk` | ✓ |  |  |  |
| 香港科技大学图书馆 (HKUST) | `lbezone.hkust.edu.hk` | ✓ |  |  |  |

### 欧美图书馆

| 网站 | 域名 | 图片 | PDF | 文字 | 搜索 |
|------|------|:----:|:---:|:----:|:----:|
| 哈佛大学图书馆 (Harvard) | `curiosity.lib.harvard.edu` | ✓ |  |  |  |
| 普林斯顿大学图书馆 (Princeton) | `dpul.princeton.edu` | ✓ |  |  |  |
| 斯坦福大学图书馆 (Stanford) | `searchworks.stanford.edu` | ✓ |  |  |  |
| 柏克莱加州大学东亚图书馆 (Berkeley) | `digicoll.lib.berkeley.edu` | ✓ |  |  |  |
| 美国国会图书馆 (Library of Congress) | `loc.gov` | ✓ |  |  |  |
| 牛津大学博德利图书馆 (Bodleian) | `digital.bodleian.ox.ac.uk` | ✓ |  |  |  |
| 剑桥大学数字图书馆 (CUDL) | `cudl.lib.cam.ac.uk` | ✓ |  |  |  |
| 梵蒂冈宗座图书馆 (DigiVatlib) | `digi.vatlib.it` | ✓ |  |  |  |
| 大英图书馆 (British Library) | `bl.uk` | ✓ |  |  |  |
| 法国国家图书馆 (BnF Gallica) | `gallica.bnf.fr` | ✓ |  |  |  |
| 柏林国立图书馆 (Staatsbibliothek zu Berlin) | `digital.staatsbibliothek-berlin.de` | ✓ |  |  |  |
| 巴伐利亚州立图书馆 (BSB) | `digitale-sammlungen.de` | ✓ |  |  |  |
| 奥地利国家图书馆 (ONB) | `viewer.onb.ac.at` | ✓ |  |  |  |
| 史密森尼学会 (Smithsonian) | `ids.si.edu` | ✓ |  |  |  |

### 通用

| 网站 | 域名 | 图片 | PDF | 文字 | 搜索 |
|------|------|:----:|:---:|:----:|:----:|
| 维基共享资源 | `commons.wikimedia.org` | ✓ |  |  | ✓ |
| 维基文库 | `zh.wikisource.org` |  |  | ✓ | ✓ |
| Internet Archive | `archive.org` | ✓ | ✓ |  |  |
| Generic IIIF | 任意 IIIF Manifest URL | ✓ |  |  |  |
## 安装

### 方式一：下载可执行文件（推荐）

前往 [Releases](https://github.com/open-guji/bookget-py/releases) 下载对应平台的文件，无需安装 Python：

| 文件 | 说明 |
|------|------|
| `bookget-cli-windows.exe` | Windows 命令行工具，双击运行 |
| `bookget-cli-macos` | macOS 命令行工具 |
| `bookget-ui-windows.exe` | Windows 图形界面，双击打开浏览器操作 |

下载后可先跑一次自检，确认这份可执行文件依赖齐全：

```bash
bookget-cli selftest
```

> **注意：识典古籍需要额外安装浏览器内核。** exe 里不包含 Playwright/Chromium
> （体积过大），所以用 exe 下载识典古籍会提示缺少浏览器。需要下载识典的，
> 请改用下面的 pip 方式并执行 `playwright install chromium`。其余 36 个站点
> 不受影响，exe 可直接使用。
| `bookget-ui-macos` | macOS 图形界面 |

> macOS 用户首次运行需赋予执行权限：`chmod +x bookget-cli-macos`

### 方式二：pip 安装

需要 Python 3.10 或更高版本。

```bash
pip install bookget
```

如需下载**识典古籍**（需要浏览器自动化绕过反爬）：

```bash
pip install "bookget[browser]"
playwright install chromium
```

## 使用方法

### 图形界面（bookget-ui）

双击运行 `bookget-ui`，自动打开浏览器，在网页中操作即可。

或通过命令行启动：

```bash
bookget serve
```

### 交互模式（bookget-cli）

直接运行 `bookget`（或双击 `bookget-cli`），按提示逐步操作：

```
=======================================================
  bookget — 古籍下载工具
=======================================================

请输入书目 URL（输入 q 退出）: https://www.shidianguji.com/book/v3/1001
  ✓ 已识别站点：识典古籍
下载目录 [C:\Users\xxx\Downloads\bookget]:
并行数量 [3]:

正在探索书目结构……
  标题：周易
  节点：12  已完成：0

开始下载所有节点？[Y/n]:
```

下载完成后自动回到输入界面，可继续下载其他古籍。按 `q` 或 `Ctrl+C` 退出。

### 命令行模式

#### 下载古籍

```bash
# 基本下载
bookget download "URL" -o ./output

# 增量下载（支持断点续传）
bookget download "URL" -o ./output --incremental --concurrency 3

# 只下载图片，不下载文字
bookget download "URL" -o ./output --no-text

# 只下载文字
bookget download "URL" -o ./output --no-images
```

#### 批量下载

一次下载多本。每本各自存进 `-o` 目录下以书籍 ID 命名的子目录；
其中一本失败不会中断整批，末尾打印汇总。

```bash
# 直接给多个 URL
bookget download "URL1" "URL2" "URL3" -o ./output

# 从文件读取，每行一个 URL（# 开头为注释）
bookget download --url-file urls.txt -o ./output

# 失败的 URL 会写进 <输出目录>/failed_urls.txt，可直接重跑
bookget download --retry-failed ./output/failed_urls.txt -o ./output
```

`urls.txt` 形如：

```text
# 论语
https://ctext.org/analects
https://www.shidianguji.com/zh/book/SBCK001
```

整批有失败时进程退出码为 `1`，方便脚本判断。

#### 结构发现与分步下载

```bash
# 发现书目结构（不下载）
bookget discover "URL" -o ./output

# 展开某个节点
bookget expand "URL" -o ./output --node NODE_ID
```

#### 搜索与匹配

```bash
# 在指定站点搜索书名
bookget search --site ctext --query "周易"

# 精确匹配书名和作者
bookget match --site shidianguji --title "周易" --authors "孔颖达"
```

#### 其他命令

```bash
# 获取书籍元数据
bookget metadata "URL"

# 查看所有支持的网站
bookget sites --list

# 检查某个网址是否支持
bookget sites --check "URL"
```

### 常用选项

| 选项 | 说明 |
|------|------|
| `-o, --output DIR` | 下载保存目录 |
| `--incremental` | 增量下载，支持断点续传 |
| `--concurrency N` | 同时下载数量（默认 1） |
| `--no-images` | 跳过图片 |
| `--no-text` | 跳过文字 |
| `--section NODE_ID` | 只下载指定章节 |
| `--json` | 以 JSON 格式输出结果 |
| `-q, --quiet` | 安静模式，减少输出 |

## 配置

可通过环境变量调整默认行为：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GUJI_OUTPUT_DIR` | 下载目录 | `./downloads` |
| `GUJI_CONCURRENT_DOWNLOADS` | 同时下载数量 | `4` |
| `GUJI_DEBUG` | 调试模式 | `false` |

也可以用配置文件：

```bash
bookget --config config.json download "URL"
```

## 从源码构建

如果你想自行构建可执行文件：

```bash
# 克隆仓库
git clone https://github.com/open-guji/bookget-py.git
cd bookget-py

# 安装依赖
pip install -e ".[dev]"
pip install pyinstaller

# 安装前端依赖
cd ui && npm install && cd ..

# 构建两个可执行文件
python packaging/build.py

# 或只构建其中一个
python packaging/build.py cli   # 只构建 bookget-cli
python packaging/build.py ui    # 只构建 bookget-ui（会自动构建前端）
```

构建产物在 `dist/` 目录下。

## 许可证

[Apache License 2.0](LICENSE)
