Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

fix: update page range syntax from '~' to '-' across documentation and codebase

myhlolidcc69e4e9bc4
diff --git a/README.md b/README.md
index cb080265..e4a2ef0d 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ Then answer from `content.content`. If `next_request` exists and the question ne
### Continue progressively
```bash
-mineru parse "book.pdf" --pages 1~10 --limit 12000 --json
+mineru parse "book.pdf" --pages 1-10 --limit 12000 --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json
```
@@ -498,10 +498,12 @@ Use JSON when you need structured status, tier, content, and continuation:
mineru parse "report.pdf" --json
```
-For a specific page range:
+PDF page selection is shared across CLI, Doclib, API, Gradio and Python. See the [page-range contract and breaking upgrade instructions](docs/next/page-ranges.md). The old `~` and negative page-number syntax is no longer supported.
+
+For a specific page range (1-based, inclusive; `r1` is the last page, `all` selects every page):
```bash
-mineru parse "report.pdf" --pages 1~10
+mineru parse "report.pdf" --pages 1-10
mineru parse "report.pdf" --pages all
```
@@ -532,7 +534,7 @@ mineru parse "report.pdf" --output ./report.md
Rules:
- Quote paths with spaces.
-- For paged documents, the default active read range is the first page window, usually `1~10`; continue with the returned marker or `next_request` instead of reading the whole document by default.
+- For paged documents, the default active read range is the first page window, usually `1-10`; continue with the returned marker or `next_request` instead of reading the whole document by default.
- Use the default tier unless the user has a quality/speed/privacy preference.
- Use `--pages all` only when the user asks for the whole document or the document is known to be small enough.
- Prefer `--limit` and continuation for long documents.
@@ -549,7 +551,7 @@ MinerU output may include a command to continue reading:
or:
```text
-<!-- Next: mineru parse report.pdf --pages 11~20 -->
+<!-- Next: mineru parse report.pdf --pages 11-20 -->
```
Run the suggested command exactly unless the user asks for a different page, block, format, or limit.
diff --git a/docs/en/usage/cli_tools.md b/docs/en/usage/cli_tools.md
index 39af2a9a..180cf215 100644
--- a/docs/en/usage/cli_tools.md
+++ b/docs/en/usage/cli_tools.md
@@ -73,3 +73,13 @@ mineru-kit vlm-server --engine auto --port 30000
- `MINERU_INTRA_OP_NUM_THREADS` / `MINERU_INTER_OP_NUM_THREADS`: ONNX operator thread settings.
Prefer each command's `--help` output and [model source documentation](./model_source.md) for current defaults.
+
+## PDF page selection
+
+Use `--pages "1-5,8,r3-r1"`: page numbers start at 1, ranges include both endpoints,
+and `r1` means the last page. Use `all` for every page. Results are sorted and deduplicated;
+partially out-of-bounds ranges select their valid intersection. Reversed or empty selections
+fail with `page_range_invalid`. Without `--pages`, `mineru parse` starts with the first 10 pages;
+`mineru-kit parse`, Python and Gradio select all pages. The old `~` and negative-number syntax
+is no longer accepted. Upgrade clients and servers together and rebuild old Doclib caches
+in a fresh data directory. See the [shared page-range contract](../../next/page-ranges.md).
diff --git a/docs/en/usage/quick_usage.md b/docs/en/usage/quick_usage.md
index c7375be3..997ec2e4 100644
--- a/docs/en/usage/quick_usage.md
+++ b/docs/en/usage/quick_usage.md
@@ -106,3 +106,13 @@ model:
```
See [Model Source Documentation](./model_source.md) for model download and local-source details.
+
+## PDF page selection
+
+Use `--pages "1-5,8,r3-r1"`: page numbers start at 1, ranges include both endpoints,
+and `r1` means the last page. Use `all` for every page. Results are sorted and deduplicated;
+partially out-of-bounds ranges select their valid intersection. Reversed or empty selections
+fail with `page_range_invalid`. Without `--pages`, `mineru parse` starts with the first 10 pages;
+`mineru-kit parse`, Python and Gradio select all pages. The old `~` and negative-number syntax
+is no longer accepted. Upgrade clients and servers together and rebuild old Doclib caches
+in a fresh data directory. See the [shared page-range contract](../../next/page-ranges.md).
diff --git a/docs/next/README.md b/docs/next/README.md
index 12581360..83dd91b3 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -1,5 +1,7 @@
# Next MinerU 文档体系
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。
+
状态: Implemented
读者: 项目核心开发者、SDK/API 设计参与者、需要理解下一代能力边界的外部开发者
范围: 组织下一阶段 MinerU 的产品方向、系统架构、公开接口和关键内部规范
diff --git a/docs/next/api/parse-jobs.md b/docs/next/api/parse-jobs.md
index 940e27e4..2cc11a01 100644
--- a/docs/next/api/parse-jobs.md
+++ b/docs/next/api/parse-jobs.md
@@ -1,5 +1,7 @@
# Parse Jobs
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: API 使用者、服务端开发者、SDK 开发者
范围: 解析任务创建、查询和轮询
@@ -34,7 +36,7 @@ Job 状态:
"type": "file_id",
"file_id": "file-01HXYZ123ABCDEF"
},
- "page_range": "1~10"
+ "page_range": "1-10"
}
],
"tier": null,
@@ -125,7 +127,7 @@ Local Parse Server 的 source 策略由启动参数决定:
| 字段 | 类型 | 默认 | 说明 |
|------|------|------|------|
-| `page_range` | string | `null` | PDF 页码范围。省略或传 `null` 表示解析整个文件;图片及其他非 PDF 输入只允许省略或传 `null`。推荐 `~` 分隔,如 `1~10`、`1,3,5~7`、`-5~-1`。 |
+| `page_range` | string | `null` | PDF 页码范围。省略或传 `null` 表示解析整个文件;图片及其他非 PDF 输入只允许省略或传 `null`。使用 `-` 分隔,如 `1-10`、`1,3,5-7`、`r5-r1`。 |
OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定,客户端不能通过文件级参数单独关闭或开启。
@@ -165,7 +167,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定
{
"file_id": "file-01HXYZ123ABCDEF",
"name": "report.pdf",
- "page_range": "1~12",
+ "page_range": "1-12",
"status": "queued"
}
],
@@ -213,7 +215,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定
{
"file_id": "file-01HXYZ123ABCDEF",
"name": "report.pdf",
- "page_range": "1~12",
+ "page_range": "1-12",
"status": "completed",
"parse": {
"model_used": "MinerU2.5-Pro-2605-1.2B",
@@ -245,7 +247,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定
|------|------|------|
| `file_id` | string 或 null | 输入 File ID。`local` source 可以为 `null`。 |
| `name` | string | 文件显示名。 |
-| `page_range` | string | 服务端规范化后的实际解析页码范围。请求未指定时为 `1~{total}`;请求指定时,服务端先按文件总页数展开负数页码,再去重并合并连续页码区间。例如 `1,2,3,-1,-1` 在 10 页文件中规范化为 `1~3,10`。 |
+| `page_range` | string | 服务端规范化后的实际解析页码范围。请求未指定时为 `1-{total}`;请求指定时,服务端先按文件总页数展开倒数页码 `rN`,再去重并合并连续页码区间。例如 `1,2,3,r1,r1` 在 10 页文件中规范化为 `1-3,10`。 |
| `status` | string | 文件级状态。 |
| `parse.model_used` | string | 实际模型 ID。仅当该文件 `status="completed"` 时出现。 |
| `parse.duration_ms` | integer | 单文件从开始解析到结束的耗时,不包含排队时间。仅当该文件 `status="completed"` 时出现。 |
diff --git a/docs/next/architecture.md b/docs/next/architecture.md
index 15a02fe0..3c13af0b 100644
--- a/docs/next/architecture.md
+++ b/docs/next/architecture.md
@@ -154,7 +154,7 @@ metadata 更新规则:入库阶段写基础 metadata;解析完成后,只
|------|------|
| `sha256` | 指向文档内容 |
| `tier` | 实体 tier:`flash` / `basic` / `standard` / `advanced`;未指定 tier 应在入队前或执行前解析为实体 tier |
-| `page_range` | 正值页码范围字符串,如 `1~5,46~50` |
+| `page_range` | 正值页码范围字符串,如 `1-5,46-50` |
| `status` | `pending` / `parsing` / `done` / `failed` / `superseded` |
| `priority` | Agent 同步请求高于 watch 后台任务 |
| `privacy` | 用户请求偏好:`local` / `remote` |
@@ -314,16 +314,16 @@ ParseWorker 按 `tier`、`privacy` 和 parse-server 健康状态路由:
ab/
ab3f...7e2d/
flash/
- 1~5_1710000000000.json
- 98~102_1710000123000.json
+ 1-5_1710000000000.json
+ 98-102_1710000123000.json
basic/
- 1~10_1710001234000.json
- 11~20_1710002234000.json
+ 1-10_1710001234000.json
+ 11-20_1710002234000.json
images/ # 仅在解析结果包含必要 sidecar 时存在
standard/
- 1~20_1710003234000.json
+ 1-20_1710003234000.json
advanced/
- 1~20_1710004234000.json
+ 1-20_1710004234000.json
```
每个 JSON 文件表示一次解析批次,文件名由页码范围和完成时间组成。每个 tier 独立目录,互不覆盖。remote 解析完成后也写入同一结构,供 CLI、SDK、搜索和缓存统一读取。
diff --git a/docs/next/cli/mineru-e2e-test-cases.md b/docs/next/cli/mineru-e2e-test-cases.md
index b6996879..e3304ec5 100644
--- a/docs/next/cli/mineru-e2e-test-cases.md
+++ b/docs/next/cli/mineru-e2e-test-cases.md
@@ -815,7 +815,7 @@ mineru search "mineru-e2e-query-that-should-not-exist" --limit 1
```bash
mineru telemetry enable --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru search "mineru-e2e-query-that-should-not-exist" --limit 1 --json
mineru telemetry preview
```
@@ -1072,7 +1072,7 @@ mineru config parsing-rules list
命令:
```bash
-mineru config parsing-rules add "*/mineru-e2e-remove/*" --tier flash --pages 1~1 --name e2e-remove-rule --json
+mineru config parsing-rules add "*/mineru-e2e-remove/*" --tier flash --pages 1-1 --name e2e-remove-rule --json
mineru config parsing-rules list --json
mineru config parsing-rules remove <rule_id>
mineru config parsing-rules list --json
@@ -1086,7 +1086,7 @@ mineru config parsing-rules list --json
- 四条 exit code = 0
- add/list JSON 均可直接解析
-- remove 前 list 中包含 pattern、`flash`、`1~1`
+- remove 前 list 中包含 pattern、`flash`、`1-1`
- remove 输出包含 `removed`、`Parsing rule` 或等价成功信息
- remove 后 list 中不再包含该 rule id
@@ -1457,7 +1457,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf"
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60
```
预期:
@@ -1471,7 +1471,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -1490,7 +1490,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
重复执行:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -1505,7 +1505,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --no-wait --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --no-wait --json
```
预期:
@@ -1523,7 +1523,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --no-
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
```
预期:
@@ -1537,7 +1537,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --for
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60
```
预期:
@@ -1553,7 +1553,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --for
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --verbose
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --verbose
```
预期:
@@ -1574,7 +1574,7 @@ Profile 前置条件: `MINERU_MODEL_STACK=light`,doclib server 及 managed par
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1600,7 +1600,7 @@ mineru show parse <created_parse_id> --json
mineru config set parse_server.local.managed_tier basic
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1~1 --force --wait 120 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --json
mineru show parse <created_parse_id> --json
```
@@ -1627,7 +1627,7 @@ mineru show parse <created_parse_id> --json
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1654,7 +1654,7 @@ mineru show parse <created_parse_id> --json
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1~1 --force --wait 300 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --json
mineru show parse <created_parse_id> --json
```
@@ -1686,7 +1686,7 @@ mineru show parse <created_parse_id> --json
mineru config set parse_server.local.managed_tier basic
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1~1 --force --wait 120 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --json
mineru show parse <created_parse_id> --json
```
@@ -1713,7 +1713,7 @@ mineru show parse <created_parse_id> --json
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1738,7 +1738,7 @@ mineru show parse <created_parse_id> --json
```bash
mineru server status --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1~1 --force --wait 300 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --json
mineru show parse <created_parse_id> --json
```
@@ -1760,10 +1760,10 @@ mineru show parse <created_parse_id> --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier medium --pages 1~1
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier high --pages 1~1
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier xhigh --pages 1~1
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier pro --pages 1~1
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier medium --pages 1-1
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier high --pages 1-1
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier xhigh --pages 1-1
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier pro --pages 1-1
```
预期:
@@ -1778,7 +1778,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier pro --pages 1~1
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output.md"
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output.md"
```
预期:
@@ -1794,7 +1794,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output-json.md" --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output-json.md" --json
```
预期:
@@ -1815,7 +1815,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --limit 20 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --json
```
预期:
@@ -1834,7 +1834,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令模板:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --after <after_cursor> --limit 30000 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --after <after_cursor> --limit 30000 --json
```
预期:
@@ -1850,7 +1850,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --aft
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --limit 20 --no-marker
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --no-marker
```
预期:
@@ -1864,7 +1864,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --remote --wait 20 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --remote --wait 20 --json
```
预期分支:
@@ -1881,7 +1881,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --rem
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --remote --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1907,7 +1907,7 @@ mineru show parse <created_parse_id> --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1929,7 +1929,7 @@ mineru show parse <created_parse_id> --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --no-wait --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --no-wait --json
mineru show parse <created_parse_id> --json
```
@@ -1952,7 +1952,7 @@ mineru show parse <created_parse_id> --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
```
@@ -1980,7 +1980,7 @@ mineru show parse <created_parse_id> --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --wait 180 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/remote-output.md"
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/remote-output.md"
```
预期分支:
@@ -2001,9 +2001,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pag
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --wait 180 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -2018,7 +2018,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru config parsing-rules add "*/sample.pdf" --tier standard --remote --pages 1~1 --name e2e-remote-rule --json
+mineru config parsing-rules add "*/sample.pdf" --tier standard --remote --pages 1-1 --name e2e-remote-rule --json
mineru watch add "$MINERU_E2E_FIXTURE_DIR" --label e2e-remote-rule-watch --json
mineru watch rescan "$MINERU_E2E_FIXTURE_DIR" --wait 60 --json
mineru list parses --limit 20 --json
@@ -2080,7 +2080,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --format json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
```
预期:
@@ -2891,7 +2891,7 @@ mineru invalidate "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf" --tier flash
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -3328,8 +3328,8 @@ mineru find "sample" --limit 1 --offset 1 --json
```bash
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages all --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 2~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 999~1000 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 2-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 999-1000 --wait 60 --json
```
预期:
@@ -3443,11 +3443,11 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/no-read.pdf" --tier flash --wait 60 --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.epub" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odt" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.epub" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odt" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -3502,9 +3502,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --wait 60 --json
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample doc.pdf" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/中文样例.pdf" --tier flash --pages 1~1 --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample doc.pdf" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/中文样例.pdf" --tier flash --pages 1-1 --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -3519,9 +3519,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf" --tier flash --pages 1
命令:
```bash
-mineru parse "sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "sample.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru show file "sample.pdf" --json
-mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1~1 --wait 60 --json
+mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
```
预期:
@@ -3538,10 +3538,10 @@ mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1~1 --wait 60 -
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output -
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/existing.md"
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/not-exist-dir/out.md"
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "~/mineru-e2e-test/output-dir/home-output.md"
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output -
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/existing.md"
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/not-exist-dir/out.md"
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "~/mineru-e2e-test/output-dir/home-output.md"
```
预期:
@@ -3558,7 +3558,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output - --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output - --json
mineru read "doc:<short_id>/tier:flash/page:1" --output - --json
```
@@ -3616,8 +3616,8 @@ mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_
命令:
```bash
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --json
-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
```
预期:
@@ -4156,3 +4156,22 @@ Environment:
- remote Standard available: yes
- pdf fixture source: ...
```
+
+## PDF 页码语法验收
+
+以下用例使用已知 10 页的 PDF;完整语义见 [PDF 页码范围规范](../page-ranges.md)。
+
+| 用例 | 输入 `--pages` | 预期 |
+|---|---|---|
+| PAGE-RANGE-001 | `1-3,7,r2-r1` | 实际范围 `1-3,7,9-10`;原始 `page_idx` 为 `0,1,2,6,8,9` |
+| PAGE-RANGE-002 | `3,1-3,2` | 合并为 `1-3`;不重排、不重复页面 |
+| PAGE-RANGE-003 | `r1` | 第 10 页 |
+| PAGE-RANGE-004 | `8-15` | 取有效交集 `8-10` |
+| PAGE-RANGE-005 | `20` | `page_range_invalid`,不回退到全文 |
+| PAGE-RANGE-006 | `5-3`、`r1-r5`、`8-r5` | `page_range_invalid` |
+| PAGE-RANGE-007 | `1~5`、`-1`、`-5~-1` | 旧语法统一拒绝 |
+| PAGE-RANGE-008 | `all` | 全部页面;直接 Python/API/Gradio 的留空也选择全部 |
+| PAGE-RANGE-009 | `1,,3`、`5-`、`r0`、`1,3` | `page_range_invalid` |
+
+对更长文档另行验证:`mineru parse` 不传页码仍首次处理前 10 页,续读命令使用 `11-20`。
+重复请求应命中新格式缓存;覆盖状态、新缓存文件名、API 页数统计均使用同一实际页面集合。
diff --git a/docs/next/cli/mineru-kit-gradio.md b/docs/next/cli/mineru-kit-gradio.md
index f65b39c6..2777f25c 100644
--- a/docs/next/cli/mineru-kit-gradio.md
+++ b/docs/next/cli/mineru-kit-gradio.md
@@ -1,5 +1,7 @@
# mineru-kit gradio
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Implemented
`mineru-kit gradio` 提供一个基于 MinerU V1 API 的文档解析界面。它不直接调用旧 `/file_parse` 或 `/tasks` 接口,也不使用 `doclib` 缓存。
@@ -51,7 +53,11 @@ mineru-kit gradio \
界面一次提交一个文件,支持 `filetypes.PARSEABLE_EXTENSIONS` 中的 PDF、图片、Office/ODF、RTF、HTML、CSV/TSV、EPUB 和 OFD。
-页码输入使用 V1 `page_range` 语法,例如 `1~5,8,-1`;留空表示全部页面。只有原始 PDF 支持显式页码范围,其他格式会自动清空并禁用页码控件。
+解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,仅包含服务实际支持的档位。默认优先选择 `standard`,否则选择最高可用档位;仅有一个档位时禁用滑块。上传新文件或清除结果会保留当前选择。
+
+启用 Gradio 事件 API 时,转换事件的 `tier_position` 参数为从 `0` 开始的整数位置,替代原来的 tier 字符串。例如四档齐全时 `3` 对应 `advanced`;仅支持 `basic/standard/advanced` 时 `2` 对应 `advanced`。位置始终按照上述顺序对实际可用档位编号,越界位置会报错。V1 API 的 `tier` 参数仍使用字符串,启动参数不变。
+
+页码输入使用 V1 `page_range` 语法,例如 `1-5,8,r1`;留空表示全部页面。只有原始 PDF 支持显式页码范围,其他格式会自动清空并禁用页码控件。
Gradio 首先发现 `/v1/health` 和 `/v1/tiers`,然后通过 `MinerUApiParser` 上传文件、创建 `/v1/parse/jobs`、轮询任务并下载 ZIP 结果。解析结果保存为严格 Middle JSON 2.0。
diff --git a/docs/next/cli/mineru-kit-parse.md b/docs/next/cli/mineru-kit-parse.md
index 5483f720..bf59a78e 100644
--- a/docs/next/cli/mineru-kit-parse.md
+++ b/docs/next/cli/mineru-kit-parse.md
@@ -1,5 +1,7 @@
# mineru-kit parse
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: 批处理开发者、解析内核开发者
范围: `mineru-kit parse` 的输入、输出、local/remote 规则和命名约定
diff --git a/docs/next/cli/mineru-library.md b/docs/next/cli/mineru-library.md
index 38125888..9fa5b493 100644
--- a/docs/next/cli/mineru-library.md
+++ b/docs/next/cli/mineru-library.md
@@ -125,8 +125,8 @@ JSON 输出为 `FileInfoResponse` 顶层对象,至少包含:
```json
[
- {"tier": "flash", "page_range": "1~20", "status": "done", "done_at": 1730000000},
- {"tier": "basic", "page_range": "1~5,18~20", "status": "done", "done_at": 1730000100}
+ {"tier": "flash", "page_range": "1-20", "status": "done", "done_at": 1730000000},
+ {"tier": "basic", "page_range": "1-5,18-20", "status": "done", "done_at": 1730000100}
]
```
@@ -134,7 +134,7 @@ JSON 输出为 `FileInfoResponse` 顶层对象,至少包含:
```json
[
- {"id": 123, "tier": "standard", "page_range": "6~17", "status": "parsing"}
+ {"id": 123, "tier": "standard", "page_range": "6-17", "status": "parsing"}
]
```
diff --git a/docs/next/cli/mineru-parse.md b/docs/next/cli/mineru-parse.md
index fc5d65f2..3e619f3a 100644
--- a/docs/next/cli/mineru-parse.md
+++ b/docs/next/cli/mineru-parse.md
@@ -1,5 +1,7 @@
# mineru parse
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: Agent skill 作者、CLI 使用者、核心开发者
范围: `mineru parse` 的默认行为、参数、隐私、tier、输出、等待和缓存
@@ -100,7 +102,7 @@ PDF/image 的默认选择策略通过当前目标 parse-server 的能力发现
分页文档使用物理页码:
```text
-<!-- Next: mineru parse report.pdf --pages 11~20 -->
+<!-- Next: mineru parse report.pdf --pages 11-20 -->
```
非分页文档当前也使用 `--after` cursor 继续读取:
diff --git a/docs/next/config.md b/docs/next/config.md
index 29a6a495..7261869b 100644
--- a/docs/next/config.md
+++ b/docs/next/config.md
@@ -1,5 +1,7 @@
# 配置体系
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。
+
状态: Draft
读者: 想了解 doclib / mineru 配置的用户、实现配置能力的核心开发者
范围: 本地配置、远端配置、解析参数、环境变量和优先级规则
diff --git a/docs/next/decisions/0003-parse-request-wait-batches.md b/docs/next/decisions/0003-parse-request-wait-batches.md
index cbe10d0f..6495de48 100644
--- a/docs/next/decisions/0003-parse-request-wait-batches.md
+++ b/docs/next/decisions/0003-parse-request-wait-batches.md
@@ -27,7 +27,7 @@ parse 请求返回本次请求需要等待的 batch 集合,而不是单个 `pa
{
"sha256": "...",
"tier": "basic",
- "page_range": "1~10",
+ "page_range": "1-10",
"status": "pending",
"wait_parse_ids": [12, 13],
"created_parse_ids": [13],
@@ -69,8 +69,8 @@ GET /parses?ids=12,13
```json
{
"parses": [
- {"id": 12, "sha256": "...", "tier": "basic", "page_range": "1~5", "status": "done"},
- {"id": 13, "sha256": "...", "tier": "basic", "page_range": "6~10", "status": "parsing"}
+ {"id": 12, "sha256": "...", "tier": "basic", "page_range": "1-5", "status": "done"},
+ {"id": 13, "sha256": "...", "tier": "basic", "page_range": "6-10", "status": "parsing"}
]
}
```
diff --git a/docs/next/decisions/0004-doclib-http-api-resources.md b/docs/next/decisions/0004-doclib-http-api-resources.md
index 9c99412e..92310dd2 100644
--- a/docs/next/decisions/0004-doclib-http-api-resources.md
+++ b/docs/next/decisions/0004-doclib-http-api-resources.md
@@ -51,7 +51,7 @@ POST /invalidate
{
"sha256": "...",
"tier": "basic",
- "page_range": "1~10",
+ "page_range": "1-10",
"status": "pending",
"cache_hit": false,
"wait_parse_ids": [12, 13],
@@ -66,7 +66,7 @@ POST /invalidate
GET /parses?ids=12,13
GET /parses?doc_ref=...&tier=basic
GET /parses?doc_ref=...&tier=basic&status=pending
-GET /parses?doc_ref=...&tier=basic&page_range=1~10
+GET /parses?doc_ref=...&tier=basic&page_range=1-10
```
`ids` 查询用于 CLI wait 等精确请求状态判断。`doc_ref + tier + page_range` 查询用于计算页覆盖状态(过滤参数为 `doc_ref`,可接受 sha256 或 path 等文档引用,与 [ADR-0003](0003-parse-request-wait-batches.md) 一致)。
@@ -93,7 +93,7 @@ GET /docs/{sha256}
`GET /docs/{sha256}/content` 从有效 done parse record 的 Middle JSON 中读取并转换内容:
```http
-GET /docs/{sha256}/content?tier=basic&page_range=1~10&format=markdown
+GET /docs/{sha256}/content?tier=basic&page_range=1-10&format=markdown
```
读取内容不触发解析。缺页时应返回明确错误或 pending 状态,由调用方再决定是否 `POST /parses`。
diff --git a/docs/next/decisions/0013-doc-content-progressive-reading.md b/docs/next/decisions/0013-doc-content-progressive-reading.md
index a9386741..bd2a3879 100644
--- a/docs/next/decisions/0013-doc-content-progressive-reading.md
+++ b/docs/next/decisions/0013-doc-content-progressive-reading.md
@@ -82,8 +82,8 @@ def get_doc_content(
HTTP API 使用 GET query,不使用 request body:
```http
-GET /api/v1/docs/{sha256}/content?tier=basic&page_range=1~10&limit=30000
-GET /api/v1/docs/{sha256}/content?tier=basic&page_range=7~10&after=doc:ab12cd3/tier:basic/page:7/block:4&limit=30000
+GET /api/v1/docs/{sha256}/content?tier=basic&page_range=1-10&limit=30000
+GET /api/v1/docs/{sha256}/content?tier=basic&page_range=7-10&after=doc:ab12cd3/tier:basic/page:7/block:4&limit=30000
GET /api/v1/docs/{sha256}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:1/block:42&limit=30000
```
@@ -92,8 +92,8 @@ GET /api/v1/docs/{sha256}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:1
- content 接口的默认 `limit` 是 `30000`。
- CLI、HTTP API、SDK 使用同一个默认 `limit`。
- export 接口没有 `limit`,也不设计 `limit` 参数。
-- 分页文档默认 `page_range=1~10`。
-- 分页文档如果显式传 `page_range=all`,Server 规范化为 `1~{page_count}`。
+- 分页文档默认 `page_range=1-10`。
+- 分页文档如果显式传 `page_range=all`,Server 规范化为 `1-{page_count}`。
- 非分页文档可以不传 `page_range`,也可以只传 `after`。
`limit` 是 soft limit,单位是渲染后的字符预算。Server 应尽量在自然边界停止,但协议不承诺精确等于 `limit`。
@@ -122,7 +122,7 @@ doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}
```json
{
- "page_range": "1~10",
+ "page_range": "1-10",
"after": null,
"limit": 30000
}
@@ -147,7 +147,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21
```json
{
"request_scope": {
- "page_range": "21~30",
+ "page_range": "21-30",
"after": "doc:ab12cd3/tier:basic/page:21",
"limit": 30000
}
@@ -165,13 +165,13 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21
- 非分页文档常规情况下使用 block 级 cursor。
- 只有在单页或单 block 过长时,才细化到 block 或 char。
-默认 `page_range=1~10` 且未截断:
+默认 `page_range=1-10` 且未截断:
```json
{
"content_ranges": [
{
- "page_range": "1~10",
+ "page_range": "1-10",
"start": "doc:ab12cd3/tier:basic/page:1",
"end": "doc:ab12cd3/tier:basic/page:10"
}
@@ -184,18 +184,18 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21
```json
{
"request_scope": {
- "page_range": "1~5,20~25",
+ "page_range": "1-5,20-25",
"after": null,
"limit": 30000
},
"content_ranges": [
{
- "page_range": "1~5",
+ "page_range": "1-5",
"start": "doc:ab12cd3/tier:basic/page:1",
"end": "doc:ab12cd3/tier:basic/page:5"
},
{
- "page_range": "20~25",
+ "page_range": "20-25",
"start": "doc:ab12cd3/tier:basic/page:20",
"end": "doc:ab12cd3/tier:basic/page:25"
}
@@ -240,7 +240,7 @@ truncated=false => next_request may be null or non-null
请求:
```http
-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-10&limit=30000
```
响应:
@@ -248,20 +248,20 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
```json
{
"request_scope": {
- "page_range": "1~10",
+ "page_range": "1-10",
"after": null,
"limit": 30000
},
"content_ranges": [
{
- "page_range": "1~10",
+ "page_range": "1-10",
"start": "doc:ab12cd3/tier:basic/page:1",
"end": "doc:ab12cd3/tier:basic/page:10"
}
],
"truncated": false,
"next_request": {
- "page_range": "11~20"
+ "page_range": "11-20"
}
}
```
@@ -273,7 +273,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
```json
{
"next_request": {
- "page_range": "36~38"
+ "page_range": "36-38"
}
}
```
@@ -292,7 +292,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
请求:
```http
-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-10&limit=30000
```
如果 Server 只输出到第 6 页,并在页边缘停止:
@@ -301,14 +301,14 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
{
"content_ranges": [
{
- "page_range": "1~6",
+ "page_range": "1-6",
"start": "doc:ab12cd3/tier:basic/page:1",
"end": "doc:ab12cd3/tier:basic/page:6"
}
],
"truncated": true,
"next_request": {
- "page_range": "7~10"
+ "page_range": "7-10"
}
}
```
@@ -322,7 +322,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000
请求:
```http
-GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000
+GET /api/v1/docs/{sha}/content?tier=basic&page_range=7-10&limit=30000
```
响应:
@@ -338,7 +338,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000
],
"truncated": true,
"next_request": {
- "page_range": "7~10",
+ "page_range": "7-10",
"after": "doc:ab12cd3/tier:basic/page:7/block:4"
}
}
@@ -357,7 +357,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000
],
"truncated": true,
"next_request": {
- "page_range": "7~10",
+ "page_range": "7-10",
"after": "doc:ab12cd3/tier:basic/page:7/block:4/char:32784"
}
}
@@ -372,7 +372,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000
示例:
```http
-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~5,20~25
+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-5,20-25
```
若文档还有第 26 页之后的内容:
@@ -380,18 +380,18 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~5,20~25
```json
{
"request_scope": {
- "page_range": "1~5,20~25",
+ "page_range": "1-5,20-25",
"after": null,
"limit": 30000
},
"truncated": false,
"next_request": {
- "page_range": "26~35"
+ "page_range": "26-35"
}
}
```
-`6~19` 不会被自动补读。用户显式跳过的页段不属于 Server 的下一段建议。
+`6-19` 不会被自动补读。用户显式跳过的页段不属于 Server 的下一段建议。
## 非分页文档
@@ -452,13 +452,13 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL
分页文档:
```html
-<!-- Next: mineru parse report.pdf --pages 11~20 -->
+<!-- Next: mineru parse report.pdf --pages 11-20 -->
```
分页文档页内 continuation:
```html
-<!-- Next: mineru parse report.pdf --pages 7~10 --after doc:ab12cd3/tier:basic/page:7/block:4 -->
+<!-- Next: mineru parse report.pdf --pages 7-10 --after doc:ab12cd3/tier:basic/page:7/block:4 -->
```
非分页文档:
@@ -481,15 +481,15 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL
### 方案 C: 用 server-side read session 记录已读页
-拒绝。它需要状态存储、过期、清理和并发语义。P0 采用无状态请求。默认页改为线性 `1~10` 后,分页文档可以用简单的下一段 `page_range` 推荐避免尾页重复。
+拒绝。它需要状态存储、过期、清理和并发语义。P0 采用无状态请求。默认页改为线性 `1-10` 后,分页文档可以用简单的下一段 `page_range` 推荐避免尾页重复。
### 方案 D: 分页文档 continuation 总是用 `after`
拒绝。分页文档最自然的继续方式是页码范围。常规页边缘截断应简化为 `next_request.page_range`,只有页内 block/char 截断才需要 `after`。
-### 方案 E: 继续使用默认 `1~5,-5~-1`
+### 方案 E: 继续使用默认 `1-5,r5-r1`
-拒绝。头尾采样会导致无状态渐进阅读时容易重复读取尾页,也让 `next_request` 必须携带额外 read state 才能正确推荐后续页。P0 改为默认 `1~10`,使阅读计划线性、可预测。
+拒绝。头尾采样会导致无状态渐进阅读时容易重复读取尾页,也让 `next_request` 必须携带额外 read state 才能正确推荐后续页。P0 改为默认 `1-10`,使阅读计划线性、可预测。
## 影响
@@ -499,7 +499,7 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL
- CLI 应根据 `next_request` 渲染下一条命令提示。
- CLI 不应反解析 Markdown marker 来决定下一次请求。
- export 接口保持不截断,不增加 `limit`。
-- 分页文档默认页码范围使用 `1~10`。
+- 分页文档默认页码范围使用 `1-10`。
- 分页文档只要 `next_request` 非空,就必须包含 `page_range`。
## 后续动作
@@ -507,14 +507,14 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL
1. 更新 doclib Interface、Client、Server 类型和签名。
2. 实现 content cursor parser 和 validator。
3. 实现 `request_scope` 规范化:
- - 默认 `page_range=1~10`。
+ - 默认 `page_range=1-10`。
- 分页文档只传 `after` 时推导连续 10 页。
- 校验 `after` 属于 `page_range` scope。
4. 实现 `content_ranges` 和 `next_request` 计算。
5. 为 Markdown render 增加 soft limit。
6. 更新 CLI parse 输出 marker,使其从 `next_request` 生成。
7. 增加测试:
- - 默认 `1~10`。
+ - 默认 `1-10`。
- 未截断时生成下一段 `page_range`。
- 页边缘截断时只返回 `next_request.page_range`。
- 页内 block/char 截断时返回 `page_range + after`。
diff --git a/docs/next/decisions/0014-mineru-read-command.md b/docs/next/decisions/0014-mineru-read-command.md
index f7f3b75b..bc987af6 100644
--- a/docs/next/decisions/0014-mineru-read-command.md
+++ b/docs/next/decisions/0014-mineru-read-command.md
@@ -181,7 +181,7 @@ parse read 返回示例:
"format": "markdown",
"content": "...",
"request_scope": {
- "page_range": "1~10",
+ "page_range": "1-10",
"after": null,
"limit": 30000,
"locator": null,
@@ -189,14 +189,14 @@ parse read 返回示例:
},
"content_ranges": [
{
- "page_range": "1~10",
+ "page_range": "1-10",
"start": "doc:ab12cd3/tier:basic/page:1",
"end": "doc:ab12cd3/tier:basic/page:10/block:18"
}
],
"truncated": false,
"next_request": {
- "page_range": "11~20",
+ "page_range": "11-20",
"after": null,
"locator": null
},
diff --git a/docs/next/decisions/0016-mineru-kit-parse-command.md b/docs/next/decisions/0016-mineru-kit-parse-command.md
index 80b5edac..d4faeaf0 100644
--- a/docs/next/decisions/0016-mineru-kit-parse-command.md
+++ b/docs/next/decisions/0016-mineru-kit-parse-command.md
@@ -65,7 +65,7 @@ mineru-kit parse <input...> -o <output> [flags]
其中:
-- `--pages` 支持如 `1~5` 或 `all`
+- `--pages` 支持如 `1-5` 或 `all`
- `--format` 当前只支持 `markdown`、`middle_json`、`zip`
- 默认 `--format` 为 `markdown`
diff --git a/docs/next/implementation-plan.md b/docs/next/implementation-plan.md
index 5c466044..daed56b5 100644
--- a/docs/next/implementation-plan.md
+++ b/docs/next/implementation-plan.md
@@ -641,11 +641,11 @@ M1 和 M2 的部分测试任务可以并行,但 `ParseResult.from_dict()`、JS
具体步骤:
-1. 准备已有 done batch: `page_range=1~5`。
-2. 请求 `page_range=1~10`。
-3. 期望只创建 `6~10` 的 pending batch。
-4. 准备已有 pending batch: `page_range=6~10`。
-5. 再请求 `1~10`,期望不重复创建,而是提升 priority。
+1. 准备已有 done batch: `page_range=1-5`。
+2. 请求 `page_range=1-10`。
+3. 期望只创建 `6-10` 的 pending batch。
+4. 准备已有 pending batch: `page_range=6-10`。
+5. 再请求 `1-10`,期望不重复创建,而是提升 priority。
6. 测试 `force=True` 时跳过 done cache,但复用 active batch。
7. 测试 `force=True` 只为 active 未覆盖页创建新 parse。
8. 测试返回 `wait_parse_ids`、`created_parse_ids`、`reused_parse_ids`。
diff --git a/docs/next/open-questions.md b/docs/next/open-questions.md
index 8dedb289..9f0da61d 100644
--- a/docs/next/open-questions.md
+++ b/docs/next/open-questions.md
@@ -54,7 +54,7 @@
| `mineru-kit parse` local/remote | local 支持 `tier/backend` 并校验兼容,PDF/image 二者都不传时默认 `standard`,OFD/EPUB/Office/HTML/CSV 按 ADR-0024/0028 归一,其它 text 不作为解析输入;remote 支持 `--remote`/`--remote-url`/`--api-key`,允许传 `tier`,禁止传 `backend`。 |
| parsing-rules 默认 tier | parsing-rules 允许不指定 tier;PDF/image 按 `standard` -> `basic` -> `flash` 选择,OFD/EPUB/Office/HTML/CSV 归一为 `flash`,其它 text 只入库和索引;只记录实际 tier。 |
| Telemetry P0 | P0 必须实现 doclib server telemetry 状态、聚合、flush 和 CLI 管理入口;纯工具无 telemetry 能力。 |
-| `mineru parse` 默认页码范围 | 分页文档默认解析和读取 `1~min(page_count,10)`;该默认由 doclib 读取/解析计划负责,CLI 参数层不硬编码默认 `--pages`。 |
+| `mineru parse` 默认页码范围 | 分页文档默认解析和读取 `1-min(page_count,10)`;该默认由 doclib 读取/解析计划负责,CLI 参数层不硬编码默认 `--pages`。 |
| 渐进式阅读协议 | Server 返回结构化 `next_request`;CLI marker 只由 `next_request` 渲染,不作为协议源头,详见 [ADR-0013](decisions/0013-doc-content-progressive-reading.md)。 |
| 非分页文档增量读取 | 非分页长文档通过 `after` cursor 继续读取;当前不为 `mineru parse` 暴露单独的 `--offset` 参数。 |
| Doc short id | `docs.short_id` 按 SHA256 7 位前缀起步、冲突递增长度、写入后保持稳定,详见 [ADR-0011](decisions/0011-doclib-doc-short-id.md)。 |
diff --git a/docs/next/page-naming.md b/docs/next/page-naming.md
index 62ef4b83..907e2f57 100644
--- a/docs/next/page-naming.md
+++ b/docs/next/page-naming.md
@@ -1,5 +1,7 @@
# Page Naming Convention
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。
+
状态: Implemented
读者: 核心开发者、编程 Agent、SDK/API/CLI 设计参与者、文档作者
范围: MinerU Next 中页码、页码范围、页面数组和页数统计的命名约定
@@ -21,7 +23,7 @@
| 名称 | 含义 | 类型示例 | 说明 |
|------|------|----------|------|
-| `page_range` | 页码范围字符串 | `str \| None` | 例如 `"1~10"`、`"1,3,5~7"`、`"all"`。是否已经规范化由所在层契约定义。 |
+| `page_range` | 页码范围字符串 | `str \| None` | 例如 `"1-10"`、`"1,3,5-7"`、`"all"`。是否已经规范化由所在层契约定义。 |
| `pages` | 页面对象列表 | `list[PageInfo]` / `list[dict]` | 只用于真实页面结构,例如 `ParseResult.pages`、Middle JSON 顶层 `{"pages": [...]}`。 |
| `<state>_pages` | 某状态下的页面对象列表 | `done_pages: list[PageInfo]` | 仅当值仍然是 `PageInfo` / page dict 列表时使用。 |
| `page_idx` | 0-based 页面索引 | `int` | 第一页为 `0`。对应 `PageInfo.page_idx`。 |
@@ -45,7 +47,7 @@
| 避免写法 | 推荐写法 |
|----------|----------|
| `pages: str` | `page_range: str` |
-| `result.pages == "1~10"` | `result.page_range == "1~10"` |
+| `result.pages == "1-10"` | `result.page_range == "1-10"` |
| `num_pages` | `page_count` 或 `total_page_count` |
| `total_pages` | `page_count` 或 `total_page_count` |
| `done_pages: str` | `done_page_range: str` |
@@ -69,9 +71,9 @@
示例:
```python
-ParseRequest(page_range="1~10")
-ParseInfo(page_range="1~5")
-ContentNextRequest(page_range="11~20")
+ParseRequest(page_range="1-10")
+ParseInfo(page_range="1-5")
+ContentNextRequest(page_range="11-20")
```
### 4.2 `pages`
@@ -157,7 +159,7 @@ page_numbers = sorted(parse_page_range_set(page_range))
命名时先问这几个问题:
-1. 值是不是 `"1~10"` 这样的范围字符串?
+1. 值是不是 `"1-10"` 这样的范围字符串?
- 是: 用 `page_range`。
2. 值是不是 `PageInfo` 或 page dict 的列表?
- 是: 用 `pages` 或 `<state>_pages`。
diff --git a/docs/next/page-ranges.md b/docs/next/page-ranges.md
new file mode 100644
index 00000000..907a9fc2
--- /dev/null
+++ b/docs/next/page-ranges.md
@@ -0,0 +1,98 @@
+# PDF 页码范围规范
+
+状态: Implemented
+
+CLI 的 `--pages`、Python/Doclib/API 的 `page_range` 和 Gradio 页码输入使用同一套语法。
+页码表示 PDF 文件内的页面顺序,从 1 开始,不使用正文印刷页码或 PDF page label。
+内部 `page_idx` / `page_indices` 仍从 0 开始,抽页后保留原始页索引。
+
+## 输入语法
+
+| 表达式 | 含义 |
+|---|---|
+| `5` | 第五页 |
+| `1-5` | 第一到第五页,包含两端 |
+| `1-3,7,10-12` | 多个区间和单页 |
+| `all` | 全部页面 |
+| `r1` | 最后一页 |
+| `r5-r1` | 最后五页 |
+| `3-r1` | 第三页到最后一页 |
+
+端点使用 ASCII 正整数(`[1-9][0-9]*`),或小写 `r` 加该正整数。`all` 只能独立使用。
+允许首尾、逗号和连字符两侧空白,例如 ` 1 - 3 , r1 `。不接受前导零、正负号、中文分隔符、
+大写 `R` / `ALL`、空选项和缺失端点;`1:5` 不是受支持的切片语法。
+
+先以文档总页数求值 `rN`,再检查区间方向;任何倒序区间均报错。
+`5-3`、`r1-r5` 无效;五页文档的 `4-r3` 也无效,不能被其他有效选项掩盖。
+
+有效页面取区间与文档的交集,再去重、升序和合并相邻页:
+
+- 十页文档的 `8-15` 得到 `8-10`。
+- 十页文档的 `r20-r8` 得到 `1-3`。
+- `3,1-3,2` 得到 `1-3`,不会重排或复制页面。
+- 整个表达式选不到页面时,例如十页文档的 `20`,返回 `page_range_invalid`。
+
+## 未指定与全部
+
+空字符串、纯空白和接口允许的 `null` 都表示未指定,默认策略由入口选择:
+
+| 入口 | 未指定 PDF 页码时 |
+|---|---|
+| `mineru parse` / Doclib 解析 | 首次前 10 页,不足 10 页则全部 |
+| Doclib 内容读取 | 首次前 10 页;带续读游标时保留现有窗口策略 |
+| Doclib 内容导出 | 导出已有缓存内容 |
+| Python `parse` / `parse_async` | 全部 |
+| V1 Parse Jobs / `MinerUApiParser` | 全部 |
+| `mineru-kit parse` / Gradio | 全部 |
+
+显式 `all` 选择全部 PDF 页面;内容读取/导出仍受实际缓存可用性约束。
+非 PDF 的解析限制不变:不能显式设置页码(包括 `all`);Gradio 对非 PDF 自动清空并禁用此控件。
+
+## 输入与输出
+
+```bash
+mineru parse report.pdf --pages "1-3,7,r2-r1"
+mineru parse report.pdf --pages all
+mineru-kit parse report.pdf -o result.md --pages "r5-r1"
+```
+
+```python
+from mineru.parser import parse
+
+result = parse("report.pdf", tier="flash", page_range="1,3,r1")
+```
+
+```json
+{
+ "tier": "flash",
+ "files": [{"source": {"type": "file_id", "file_id": "file-example"}, "page_range": "1-3,r1"}],
+ "output_formats": ["middle_json"]
+}
+```
+
+已求值的 API/Doclib 范围、覆盖状态、续读命令、解析记录及新缓存文件名使用正整数连字符格式。
+例如十页文档的 `1-3,r1` 输出为 `1-3,10`,`5-5` 输出为 `5`,空覆盖集合输出空字符串。
+parsing rules 和排队中的 V1 请求尚未取得总页数时允许保留 `rN` / `all`;实际解析时再求值。
+
+## 错误与实现边界
+
+统一错误码为 `page_range_invalid`,类型为 `invalid_request_error`。Python 抛出
+`InvalidRequestError`;CLI 和 Gradio 保留该错误含义。V1 创建任务的语法错误返回 HTTP 400,
+`error.param` 定位到 `files.<index>.page_range`。总页数求值错误通过异步任务的文件级错误返回。
+
+共享实现位于 `mineru/parser/page_range.py`,负责语法、求值、格式化和页数统计。缓存内部的空范围
+表示空集合,不表示用户输入的“未指定”。总页数未知的缓存内容导出可使用绝对页码或全部缓存,
+不能用已有缓存的最大页码推测 `r1`。
+
+## 不兼容升级
+
+本次不支持旧输入 `1~5`、`-1`、`-5~-1`,也不提供旧页码缓存迁移或旧服务端回退。
+更新调用方、SDK、Doclib 和 Parse Server,重新创建使用旧语法的 parsing rules。
+
+已有 Doclib 数据可保留备份。升级后使用新的数据目录重新入库、解析:
+
+1. 停止旧 Doclib 实例,在独立配置文件中把 `doclib.data_dir` 配置为新的空目录。
+2. 按[配置说明](config.md)同步配置独立 DB/endpoint 路径,以新配置启动 Doclib;客户端使用同一配置。
+3. 重新添加 watch / parsing rules,重新扫描或执行 `mineru parse`,生成新格式记录与缓存。
+
+程序不会在此次升级中自动删除旧数据。不要把旧数据库或旧 parsed 目录复制到新实例继续使用。
diff --git a/docs/next/sdk/doclib-client.md b/docs/next/sdk/doclib-client.md
index 5902211f..1ab00d8b 100644
--- a/docs/next/sdk/doclib-client.md
+++ b/docs/next/sdk/doclib-client.md
@@ -1,5 +1,7 @@
# Doclib SDK: `DoclibClient`
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: SDK 开发者、`mineru` CLI 开发者、MCP/桌面端集成方
范围: 本地 doclib client 的公开能力、方法和错误模型
diff --git a/docs/next/sdk/migration.md b/docs/next/sdk/migration.md
index b141fe78..e7c8b5f6 100644
--- a/docs/next/sdk/migration.md
+++ b/docs/next/sdk/migration.md
@@ -1,5 +1,7 @@
# 迁移路径
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: 核心开发者、SDK 开发者
范围: 从当前 SDK 代码走向目标公开契约的步骤
diff --git a/docs/next/sdk/parser.md b/docs/next/sdk/parser.md
index c39e042a..cc927fd6 100644
--- a/docs/next/sdk/parser.md
+++ b/docs/next/sdk/parser.md
@@ -1,5 +1,7 @@
# Tool SDK: `mineru.parser`
+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。
+
状态: Draft
读者: SDK 开发者、`mineru-kit` 开发者、核心开发者
范围: 无状态解析工具层的公开入口、统一 parser 类和目标契约
@@ -148,7 +150,7 @@ class DocumentParser:
```python
from mineru.parser import parse
-result = parse("report.pdf", tier="basic", page_range="1~5")
+result = parse("report.pdf", tier="basic", page_range="1-5")
print(result.markdown())
```
@@ -158,7 +160,7 @@ print(result.markdown())
from mineru.parser import MinerUParser
with MinerUParser(tier="basic") as parser:
- result = parser.parse("report.pdf", page_range="1~10")
+ result = parser.parse("report.pdf", page_range="1-10")
images = result.images()
```
diff --git a/docs/next/workflows.md b/docs/next/workflows.md
index d1433552..9020f725 100644
--- a/docs/next/workflows.md
+++ b/docs/next/workflows.md
@@ -383,7 +383,7 @@ watch -> flash index -> search result -> Agent chooses document -> mineru parse
当输出被截断或只解析部分页时,应输出可机器理解的 marker:
```text
-<!-- mineru:next page_range=6~10 tier=standard -->
+<!-- mineru:next page_range=6-10 tier=standard -->
```
marker 不应依赖自然语言提示。具体 marker 格式可在 CLI 或 Agent 文档中继续细化。
@@ -481,16 +481,16 @@ doclib 解析产物按内容和实际使用的 tier 隔离。`parsed/` 目录下
ab/
ab3f...7e2d/
flash/
- 1~5_1710000000000.json
- 98~102_1710000123000.json
+ 1-5_1710000000000.json
+ 98-102_1710000123000.json
basic/
- 1~10_1710001234000.json
- 11~20_1710002234000.json
+ 1-10_1710001234000.json
+ 11-20_1710002234000.json
images/ # 可选,仅保存解析产生的必要 sidecar
standard/
- 1~20_1710003234000.json
+ 1-20_1710003234000.json
advanced/
- 1~20_1710004234000.json
+ 1-20_1710004234000.json
```
单个 JSON 文件表示一次解析批次,基本形态:
@@ -732,8 +732,8 @@ mineru parse report.pdf --tier flash
输入:
```bash
-mineru parse report.pdf --tier basic --pages 1~5
-mineru parse report.pdf --tier basic --pages 6~10
+mineru parse report.pdf --tier basic --pages 1-5
+mineru parse report.pdf --tier basic --pages 6-10
```
期望:
@@ -741,7 +741,7 @@ mineru parse report.pdf --tier basic --pages 6~10
1. 两次请求可以生成两个 done parse batch。
2. `parsed/<sha-prefix>/<sha>/basic/` 下保存两个 JSON 文件。
3. 每个 JSON 文件只包含对应页码范围的 `pages`。
-4. 后续请求 `--pages 1~10` 可以由已完成批次覆盖,不需要重新解析。
+4. 后续请求 `--pages 1-10` 可以由已完成批次覆盖,不需要重新解析。
5. compaction 可以将两个批次合并成更少的 parse row 和 JSON 文件。
6. 合并时按 `page_idx` 组织页面;同一页如果被重复解析,较新批次覆盖较旧批次。
@@ -750,18 +750,18 @@ mineru parse report.pdf --tier basic --pages 6~10
输入:
```bash
-mineru parse report.pdf --tier basic --pages 1~5
-mineru parse report.pdf --tier basic --pages 1~5 --force
+mineru parse report.pdf --tier basic --pages 1-5
+mineru parse report.pdf --tier basic --pages 1-5 --force
```
期望:
1. 第二次请求调用 `POST /parses`,返回 `wait_parse_ids`。
2. 旧 done batch 不被删除,也不被标记失效。
-3. 如果已有 active parse 覆盖 `1~5`,第二次请求可以复用该 parse,并把 id 放入 `reused_parse_ids`。
+3. 如果已有 active parse 覆盖 `1-5`,第二次请求可以复用该 parse,并把 id 放入 `reused_parse_ids`。
4. 如果没有 active parse 覆盖,第二次请求创建新 parse,并把 id 放入 `created_parse_ids`。
5. CLI wait 查询 `GET /parses?ids=...`,等待所有 `wait_parse_ids` 完成。
-6. 如果第二次解析成功,读取 `1~5` 时使用 `done_at` 更新的有效 batch。
+6. 如果第二次解析成功,读取 `1-5` 时使用 `done_at` 更新的有效 batch。
7. 如果第二次解析失败,第一次解析结果仍然可读、可搜索,但本次 force 请求显示为失败。
### 13.8 Invalidate 缓存
diff --git a/docs/zh/usage/cli_tools.md b/docs/zh/usage/cli_tools.md
index 52d7d11e..0ce6d910 100644
--- a/docs/zh/usage/cli_tools.md
+++ b/docs/zh/usage/cli_tools.md
@@ -73,3 +73,11 @@ mineru-kit vlm-server --engine auto --port 30000
- `MINERU_INTRA_OP_NUM_THREADS` / `MINERU_INTER_OP_NUM_THREADS`:ONNX 算子线程配置。
当前默认值以各命令的 `--help` 和[模型源说明](./model_source.md)为准。
+
+## PDF 页码选择
+
+使用 `--pages "1-5,8,r3-r1"`:页码从 1 开始,包含区间两端,`r1` 表示最后一页,`all` 表示全部。
+结果去重并按原页序排列;部分越界取有效交集,倒序或选不到页面时返回 `page_range_invalid`。
+省略页码时 `mineru parse` 默认前 10 页,`mineru-kit parse`、Python 和 Gradio 默认全部。
+不再接受 `~` 和负数页码;升级调用方和服务端后,在新 Doclib 数据目录重建解析缓存。
+完整说明见 [PDF 页码范围规范](../../next/page-ranges.md)。
diff --git a/docs/zh/usage/quick_usage.md b/docs/zh/usage/quick_usage.md
index e2a22d2c..58def7b0 100644
--- a/docs/zh/usage/quick_usage.md
+++ b/docs/zh/usage/quick_usage.md
@@ -106,3 +106,11 @@ model:
```
模型下载和本地模型源的详细说明见[模型源说明](./model_source.md)。
+
+## PDF 页码选择
+
+使用 `--pages "1-5,8,r3-r1"`:页码从 1 开始,包含区间两端,`r1` 表示最后一页,`all` 表示全部。
+结果去重并按原页序排列;部分越界取有效交集,倒序或选不到页面时返回 `page_range_invalid`。
+省略页码时 `mineru parse` 默认前 10 页,`mineru-kit parse`、Python 和 Gradio 默认全部。
+不再接受 `~` 和负数页码;升级调用方和服务端后,在新 Doclib 数据目录重建解析缓存。
+完整说明见 [PDF 页码范围规范](../../next/page-ranges.md)。
diff --git a/mineru/cli/commands/config.py b/mineru/cli/commands/config.py
index b7cb3bc2..9d6fb411 100644
--- a/mineru/cli/commands/config.py
+++ b/mineru/cli/commands/config.py
@@ -21,6 +21,7 @@ from ...doclib.types import (
RemoveExcludeRuleResponse,
RemoveParsingRuleResponse,
)
+from ...parser.page_range import normalize_page_range_input
from ...types import Tier
from ..contracts import CliContext
from ..runtime import run_cli
@@ -101,7 +102,7 @@ def exclude_rules_remove(rule_id: int = typer.Argument(..., help="Rule id to rem
def parsing_rules_add(
pattern: str = typer.Argument(..., help="Glob pattern to match"),
tier: Tier | None = typer.Option(None, "--tier", help="Parse tier: flash, basic, standard, advanced"),
- pages: str | None = typer.Option(None, "--pages", help="Page range, e.g. all or 1~10"),
+ pages: str | None = typer.Option(None, "--pages", help="PDF pages, e.g. all, 1-10 or r3-r1"),
remote: bool = typer.Option(False, "--remote", help="Allow remote parsing"),
name: str | None = typer.Option(None, "--name", help="Rule name"),
json_mode: bool = typer.Option(False, "--json", help="JSON output"),
@@ -110,13 +111,21 @@ def parsing_rules_add(
ctx = CliContext(json_mode=json_mode)
run_cli(
ctx,
- lambda: _client().add_parsing_rule(
- ParsingRuleRequest(pattern=pattern, tier=tier, page_range=pages, remote=remote, name=name)
- ),
+ lambda: _add_parsing_rule(pattern, tier=tier, page_range=pages, remote=remote, name=name),
render=_render_parsing_rule_added,
)
+def _add_parsing_rule(
+ pattern: str, *, tier: Tier | None, page_range: str | None, remote: bool, name: str | None
+) -> ParsingRuleInfo:
+ """在访问 Doclib 前校验规则中的页码表达式。"""
+ page_range = normalize_page_range_input(page_range) or None
+ return _client().add_parsing_rule(
+ ParsingRuleRequest(pattern=pattern, tier=tier, page_range=page_range, remote=remote, name=name)
+ )
+
+
@parsing_rules_app.command("list")
def parsing_rules_list(json_mode: bool = typer.Option(False, "--json", help="JSON output")) -> None:
"""List parsing rules."""
diff --git a/mineru/cli/commands/parse.py b/mineru/cli/commands/parse.py
index b5613d62..32e33f57 100644
--- a/mineru/cli/commands/parse.py
+++ b/mineru/cli/commands/parse.py
@@ -21,6 +21,7 @@ from ...doclib.types import (
TelemetryObservationsRequest,
)
from ...errors import MineruError, error_response
+from ...parser.page_range import normalize_page_range_input
from ...types import Tier
from ..contracts import CliContext, CliResult
from ..guidance import api_key_guidance_for_error
@@ -66,23 +67,11 @@ def _emit_notice(message: str, *, json_mode: bool) -> None:
def _validate_page_range_input(page_range: str | None) -> None:
- if page_range is None or page_range.strip() == "" or page_range.strip() == "all":
- return
+ """复用共享语法校验,并把错误参数定位到 CLI 的 pages 选项。"""
try:
- for raw_part in page_range.split(","):
- part = raw_part.strip()
- if not part:
- raise ValueError
- if "~" in part:
- raw_start, raw_end = part.split("~", 1)
- start = int(raw_start.strip())
- end = int(raw_end.strip())
- if start > 0 and end > 0 and start > end:
- raise ValueError
- else:
- int(part)
- except ValueError:
- raise MineruError("page_range_invalid", f"Invalid page range: {page_range}", "pages") from None
+ normalize_page_range_input(page_range)
+ except MineruError as exc:
+ raise MineruError(exc.code, str(exc), "pages") from None
def parse_cmd(
@@ -92,7 +81,7 @@ def parse_cmd(
"--tier",
help="Parse tier: flash, basic, standard, advanced (default: server decides)",
),
- pages: str = typer.Option(None, "-p", "--pages", help="Page range, e.g. '1~5' or 'all'"),
+ pages: str = typer.Option(None, "-p", "--pages", help="PDF pages: '1-5,8,r3-r1' or 'all'; default: first 10 pages"),
after: str = typer.Option(None, "--after", help="Continue reading after a content cursor"),
limit: int | None = typer.Option(None, "--limit", help="Soft character limit for STDOUT content"),
format: Literal["markdown"] = typer.Option("markdown", "-f", "--format", help="Output format: markdown"),
@@ -159,6 +148,7 @@ def _parse(
raise MineruError("file_not_found", f"File not found: {file_path}", "path")
_validate_page_range_input(pages)
+ pages = normalize_page_range_input(pages) or None
client = DoclibClient(timeout=wait + 30)
diff --git a/mineru/doclib/background/compaction.py b/mineru/doclib/background/compaction.py
index 3b153b44..13a72ca9 100644
--- a/mineru/doclib/background/compaction.py
+++ b/mineru/doclib/background/compaction.py
@@ -11,6 +11,7 @@ from collections.abc import Sequence
from typing import Any, cast
from ...parser.base import MIDDLE_JSON_SCHEMA_VERSION
+from ...parser.page_range import format_page_range
from ...types import Tier
from ..core.db import DatabaseManager
from ..rows import ParseBatchRow, ParseGroupRow, ParseRow
@@ -124,19 +125,8 @@ class Compaction:
if r["done_at"] and r["done_at"] > max_done_at:
max_done_at = r["done_at"]
- # merge contiguous ranges
- sorted_page_numbers = sorted(all_page_numbers)
- merged_ranges: list[str] = []
- start = sorted_page_numbers[0]
- end = start
- for page_no in sorted_page_numbers[1:]:
- if page_no == end + 1:
- end = page_no
- else:
- merged_ranges.append(f"{start}~{end}" if start != end else str(start))
- start = page_no
- end = page_no
- merged_ranges.append(f"{start}~{end}" if start != end else str(start))
+ # 使用统一格式化逻辑生成每段连续页的缓存范围。
+ merged_ranges = format_page_range(all_page_numbers).split(",")
# check if merge actually reduced row count
if len(merged_ranges) >= len(rows):
diff --git a/mineru/doclib/client.py b/mineru/doclib/client.py
index de73196a..57ace97b 100644
--- a/mineru/doclib/client.py
+++ b/mineru/doclib/client.py
@@ -11,6 +11,7 @@ from pydantic import BaseModel
from pydantic_core import to_jsonable_python
from ..errors import MineruError, ServerNotRunningError
+from ..parser.page_range import normalize_page_range_input
from ..types import Tier
from .base import DoclibInterface
from .endpoint import (
@@ -128,6 +129,7 @@ class DoclibClient(DoclibInterface):
@route("POST", "/parses", tags=("parse",))
def ensure_parse(self, request: ParseRequest) -> ParseResponse:
+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})
return self._request_model(ParseResponse, body=request)
@route("GET", "/parses", tags=("parse",))
@@ -143,6 +145,7 @@ class DoclibClient(DoclibInterface):
limit: int = 50,
offset: int = 0,
) -> ListParsesResponse:
+ page_range = normalize_page_range_input(page_range) or None
return self._request_model(
ListParsesResponse,
params={
@@ -237,6 +240,7 @@ class DoclibClient(DoclibInterface):
format: str = "markdown",
no_marker: bool = False,
) -> DocContentResponse:
+ page_range = normalize_page_range_input(page_range) or None
return self._request_model(
DocContentResponse,
path_params={"doc_ref": doc_ref},
@@ -275,6 +279,7 @@ class DoclibClient(DoclibInterface):
@route("POST", "/docs/{doc_ref}/exports", tags=("docs",))
def export_doc_content(self, doc_ref: str, request: DocContentExportRequest) -> DocContentExportResponse:
+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})
return self._request_model(DocContentExportResponse, path_params={"doc_ref": doc_ref}, body=request)
@route("GET", "/search", tags=("search",))
@@ -354,6 +359,7 @@ class DoclibClient(DoclibInterface):
@route("POST", "/parsing-rules", tags=("rules",))
def add_parsing_rule(self, request: ParsingRuleRequest) -> ParsingRuleInfo:
+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})
return self._request_model(ParsingRuleInfo, body=request)
@route("GET", "/parsing-rules", tags=("rules",))
diff --git a/mineru/doclib/server.py b/mineru/doclib/server.py
index f60b8c1d..19b2c22f 100644
--- a/mineru/doclib/server.py
+++ b/mineru/doclib/server.py
@@ -24,6 +24,11 @@ from pydantic import ValidationError
from ..config import config
from ..errors import InvalidRequestError, MineruError, NotFoundError, error_response, http_status_for
from ..filetypes import IMAGE_EXTENSIONS, TEXT_EXTENSIONS, TEXT_FILE_TYPES
+from ..parser.page_range import (
+ expand_page_range as _expand_page_range,
+ format_page_range as _page_numbers_to_range_str,
+ normalize_page_range_input,
+)
from ..parser.tier import TierDependencyError, ensure_tier_runtime_dependencies
from ..render._internal.markdown.assets import build_markdown_image
from ..render._internal.markdown.blocks import render_single_block
@@ -406,6 +411,12 @@ class DoclibServer(AsyncDoclibInterface):
limit=limit,
offset=offset,
)
+ page_range = normalize_page_range_input(page_range)
+ if resolved_sha256 and tier and page_range:
+ doc = await self.state.db.fetchone("SELECT * FROM docs WHERE sha256=?", (resolved_sha256,))
+ if doc is None:
+ raise NotFoundError("doc_not_found", f"Document {resolved_sha256} not found.", "doc_ref")
+ page_range = _expand_page_range(page_range, doc["page_count"] or 1)
coverage = _parse_coverage(page_range, rows) if resolved_sha256 and tier and page_range else None
return ListParsesResponse(
parses=[_parse_info(row, coverage=coverage) for row in rows],
@@ -1210,13 +1221,17 @@ class DoclibServer(AsyncDoclibInterface):
(sha256, tier, PARSE_STATUS_DONE),
)
loaded_pages = load_pages_from_done_batches(data_dir, sha256, tier, cast(list[ParseBatchRow], rows))
- if page_range:
- loaded_pages = filter_pages_by_user_range(loaded_pages, page_range)
- if not loaded_pages:
- raise NotFoundError("not_cached", "Requested parsed content is not cached.", "page_range")
doc = cast(DocRow | None, await self.state.db.fetchone("SELECT * FROM docs WHERE sha256=?", (sha256,)))
if doc is None:
raise NotFoundError("doc_not_found", f"Document {sha256} not found.", "doc_ref")
+ page_range = normalize_page_range_input(page_range)
+ if page_range and doc["page_count"] is not None:
+ loaded_pages = filter_pages_by_user_range(loaded_pages, _expand_page_range(page_range, doc["page_count"]))
+ elif page_range and page_range != "all":
+ # 总页数未知时只允许绝对页码,不能用已缓存页数推断文档末页。
+ loaded_pages = filter_pages_by_user_range(loaded_pages, page_range)
+ if not loaded_pages:
+ raise NotFoundError("not_cached", "Requested parsed content is not cached.", "page_range")
output: list[str] = []
page_count = doc["page_count"]
for page in loaded_pages:
@@ -1695,19 +1710,20 @@ def _is_paginated_doc(doc: DocRow) -> bool:
def _normalize_content_page_range(page_range: str | None, after: str | None, doc: DocRow) -> str | None:
+ page_range = normalize_page_range_input(page_range)
page_count = doc.get("page_count") or 1
if _is_paginated_doc(doc):
if page_range and page_range.strip() == "all":
- return f"1~{page_count}"
+ return _expand_page_range("all", page_count)
if page_range:
return _normalize_page_range(page_range, page_count)
if after:
cursor = _parse_after_cursor(after)
assert cursor is not None
end = min(page_count, cursor.page_no + 9)
- return f"{cursor.page_no}~{end}" if cursor.page_no != end else str(cursor.page_no)
+ return _range_str(cursor.page_no, end)
end = min(page_count, 10)
- return f"1~{end}" if end > 1 else "1"
+ return _range_str(1, end)
if page_range and page_range.strip() == "all":
return None
return _normalize_page_range(page_range, page_count) if page_range else None
@@ -1717,55 +1733,6 @@ def _normalize_page_range(page_range: str, page_count: int) -> str:
return _expand_page_range(page_range, page_count)
-def _expand_page_range(page_range: str, page_count: int) -> str:
- available_page_numbers = set(range(1, page_count + 1))
- if not page_range or page_range.strip() == "all":
- page_numbers = available_page_numbers
- else:
- page_numbers: set[int] = set()
- for part in page_range.split(","):
- part = part.strip()
- if not part:
- continue
- if "~" in part:
- raw_start, raw_end = part.split("~", 1)
- start = int(raw_start.strip())
- end = int(raw_end.strip())
- if start < 0:
- start = page_count + start + 1
- if end < 0:
- end = page_count + end + 1
- if start <= end:
- page_numbers.update(range(start, end + 1))
- else:
- page_no = int(part)
- if page_no < 0:
- page_no = page_count + page_no + 1
- page_numbers.add(page_no)
- page_numbers &= available_page_numbers
- if not page_numbers:
- raise InvalidRequestError("page_range_invalid", f"Page range does not select any pages: {page_range}", "page_range")
- return _page_numbers_to_range_str(page_numbers)
-
-
-def _page_numbers_to_range_str(page_numbers: set[int]) -> str:
- if not page_numbers:
- return ""
- ranges: list[str] = []
- ordered = sorted(page_numbers)
- start = ordered[0]
- end = ordered[0]
- for page_no in ordered[1:]:
- if page_no == end + 1:
- end = page_no
- continue
- ranges.append(f"{start}~{end}" if start != end else str(start))
- start = page_no
- end = page_no
- ranges.append(f"{start}~{end}" if start != end else str(start))
- return ",".join(ranges)
-
-
def _select_context_pages(pages: list[PageInfo], target: ContentCursor | None, context: int) -> list[PageInfo]:
if target is None or target.page_no is None or context <= 0:
return pages
@@ -2179,7 +2146,7 @@ def _last_requested_page(page_range: str | None) -> int | None:
def _range_str(start: int, end: int) -> str:
- return f"{start}~{end}" if start != end else str(start)
+ return _page_numbers_to_range_str(range(start, end + 1))
def _effective_data_dir(state: Any) -> str:
diff --git a/mineru/doclib/services/config_svc.py b/mineru/doclib/services/config_svc.py
index e6080ffa..3b05eb1a 100644
--- a/mineru/doclib/services/config_svc.py
+++ b/mineru/doclib/services/config_svc.py
@@ -9,6 +9,7 @@ import time
from typing import cast
from ...errors import InvalidRequestError
+from ...parser.page_range import normalize_page_range_input
from ...types import Tier
from ..config_defaults import CONFIG_DEFAULTS, CONFIG_SOURCE_DEFAULT, CONFIG_SOURCE_OVERRIDE, ConfigSource
from ..config_schema import validate_config_key, validate_config_value
@@ -208,6 +209,7 @@ class ConfigService:
(name, pattern, priority, now, now),
)
if rule_type == RULE_TYPE_PARSING_RULE:
+ page_range = normalize_page_range_input(page_range) or None
return await self.db.execute_insert(
"INSERT INTO parsing_rules (name, pattern, tier, page_range, remote, priority, created_at, updated_at) "
"VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
diff --git a/mineru/doclib/services/parse_svc.py b/mineru/doclib/services/parse_svc.py
index b0f59bf1..85e4e80a 100644
--- a/mineru/doclib/services/parse_svc.py
+++ b/mineru/doclib/services/parse_svc.py
@@ -28,6 +28,12 @@ from ...filetypes import (
)
from ...parser.api_client import _APITransportError, _V1APIError
from ...parser.base import ParseResult
+from ...parser.page_range import (
+ expand_page_range,
+ format_page_range as _page_numbers_to_range_str,
+ normalize_page_range_input,
+ parse_page_range_set,
+)
from ...types import QUALITY_TIERS, TIER_ORDER, PageInfo, Tier, select_default_quality_tier, select_parsing_rule_tier
from ..core.db import DatabaseManager
from ..core.file_io import FileStat, MetadataExtractionError, compute_sha256, extract_metadata, get_file_stat
@@ -124,21 +130,6 @@ def _raise_refresh_error(refreshed: FileRefreshResult) -> None:
# ── range helpers ──────────────────────────────────────────────────
-def parse_page_range_set(page_range: str) -> set[int]:
- """Parse a page_range string like '1~5,10~15' into 1-based page numbers."""
- page_numbers: set[int] = set()
- for part in page_range.split(","):
- part = part.strip()
- if not part:
- continue
- if "~" in part:
- a, b = part.split("~", 1)
- page_numbers.update(range(int(a.strip()), int(b.strip()) + 1))
- else:
- page_numbers.add(int(part))
- return page_numbers
-
-
def filter_pages_by_user_range(pages: list[PageInfo], page_range: str) -> list[PageInfo]:
"""Filter 0-based PageInfo objects by a user-facing 1-based page range."""
requested_page_numbers = parse_page_range_set(page_range)
@@ -166,64 +157,10 @@ def page_range_uncovered(request_page_range: str, done_batches: list[ParseRow])
return needed_page_numbers - covered_page_numbers
-def _page_numbers_to_range_str(page_numbers: set[int]) -> str:
- """Convert a set of page numbers (1-based) to a compact range string."""
- if not page_numbers:
- return ""
- sorted_page_numbers = sorted(page_numbers)
- ranges: list[str] = []
- start = sorted_page_numbers[0]
- end = start
- for page_no in sorted_page_numbers[1:]:
- if page_no == end + 1:
- end = page_no
- else:
- ranges.append(f"{start}~{end}" if start != end else str(start))
- start = page_no
- end = page_no
- ranges.append(f"{start}~{end}" if start != end else str(start))
- return ",".join(ranges)
-
-
-def expand_page_range(page_range: str | None, page_count: int) -> str:
- """Expand shorthand page_range like 'all' or negative ranges like '-5~-1'
- into positive page ranges. Returns '1~{page_count}' for None/empty."""
- available_page_numbers = set(range(1, page_count + 1))
- if not page_range or page_range.strip() == "all":
- page_numbers = available_page_numbers
- else:
- page_numbers: set[int] = set()
- for part in page_range.split(","):
- part = part.strip()
- if not part:
- continue
- if "~" in part:
- a, b = part.split("~", 1)
- a, b = a.strip(), b.strip()
- start = int(a)
- end = int(b)
- # negative index: -5 means page_count-5+1
- if start < 0:
- start = page_count + start + 1
- if end < 0:
- end = page_count + end + 1
- if start <= end:
- page_numbers.update(range(start, end + 1))
- else:
- page_no = int(part.strip())
- if page_no < 0:
- page_no = page_count + page_no + 1
- page_numbers.add(page_no)
- page_numbers &= available_page_numbers
- if not page_numbers:
- raise InvalidRequestError("page_range_invalid", f"Page range does not select any pages: {page_range}", "page_range")
- return _page_numbers_to_range_str(page_numbers)
-
-
def default_parse_range(page_count: int | None) -> str:
"""Return the default page range for active reading."""
if page_count and page_count > 0:
- return f"1~{min(page_count, 10)}"
+ return expand_page_range("1-10", page_count)
return "1"
@@ -726,6 +663,7 @@ class ParseService:
remote: bool = False,
) -> ParseResponse:
"""Handle a parse request from CLI. Returns info for status polling."""
+ page_range = normalize_page_range_input(page_range) or None
# ensure the path is current before trusting files.sha256
refreshed = await self.refresh_file(path, ensure_ingested=True, allow_images=True)
if refreshed.status == "unsupported":
@@ -1383,8 +1321,12 @@ class ParseService:
sql += " ORDER BY created_at DESC"
rows = cast(list[ParseRow], await self.db.fetchall(sql, tuple(params)))
result: dict[str, object] = {"parses": [_parse_record_response(row) for row in rows]}
+ page_range = normalize_page_range_input(page_range)
if sha256 and tier and page_range:
- result["coverage"] = _parse_coverage(page_range, rows)
+ doc = await self.db.fetchone("SELECT * FROM docs WHERE sha256=?", (sha256,))
+ if doc is None:
+ raise InvalidRequestError("doc_not_found", f"Document {sha256} not found.", "doc_ref")
+ result["coverage"] = _parse_coverage(expand_page_range(page_range, doc["page_count"] or 1), rows)
return result
async def invalidate(self, sha256: str, tier: Tier | None = None) -> int:
diff --git a/mineru/doclib/types.py b/mineru/doclib/types.py
index ad48932e..f4967a27 100644
--- a/mineru/doclib/types.py
+++ b/mineru/doclib/types.py
@@ -6,6 +6,7 @@ from typing import Any, Literal
from pydantic import BaseModel, Field
+from ..parser.page_range import PAGE_RANGE_DESCRIPTION
from ..types import Tier
ParseSubmitStatus = Literal["pending", "done"]
@@ -95,7 +96,7 @@ class RemoveParsingRuleResponse(DoclibModel):
class ParseRequest(DoclibModel):
path: str
tier: Tier | None = None
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
force: bool = False
remote: bool = False
@@ -104,7 +105,7 @@ class ParseResponse(DoclibModel):
sha256: str
short_id: str | None = None
tier: Tier
- page_range: str
+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")
status: ParseSubmitStatus
cache_hit: bool = False
wait_parse_ids: list[int] = Field(default_factory=list)
@@ -114,9 +115,9 @@ class ParseResponse(DoclibModel):
class ParseCoverage(DoclibModel):
- done_page_range: str
- active_page_range: str
- missing_page_range: str
+ done_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")
+ active_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")
+ missing_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")
class ParseInfo(DoclibModel):
@@ -124,7 +125,7 @@ class ParseInfo(DoclibModel):
sha256: str
short_id: str
tier: Tier
- page_range: str
+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")
status: ParseStatus
priority: int = 0
privacy: str
@@ -276,7 +277,7 @@ class DocContentResponse(DoclibModel):
class ContentRequestScope(DoclibModel):
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
after: str | None = None
limit: int = 30000
locator: str | None = None
@@ -285,13 +286,13 @@ class ContentRequestScope(DoclibModel):
class ContentRange(DoclibModel):
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
start: str
end: str
class ContentNextRequest(DoclibModel):
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
after: str | None = None
locator: str | None = None
@@ -306,7 +307,7 @@ class ContentAsset(DoclibModel):
class DocContentExportRequest(DoclibModel):
tier: Tier
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
format: str = "markdown"
output: str
no_marker: bool = False
@@ -368,7 +369,7 @@ class FileInfoResponse(DoclibModel):
class TierParseInfo(DoclibModel):
tier: Tier
status: ParseStatus
- page_range: str
+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")
done_at: int | None = None
@@ -461,7 +462,7 @@ class ParsingRuleRequest(DoclibModel):
pattern: str
name: str | None = None
tier: Tier | None = None
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
remote: bool = False
priority: int = 0
@@ -482,7 +483,7 @@ class ParsingRuleInfo(DoclibModel):
pattern: str
name: str | None = None
tier: Tier | None = None
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)
remote: bool = False
enabled: bool = True
priority: int = 0
diff --git a/mineru/kit/commands/parse.py b/mineru/kit/commands/parse.py
index c139949d..34731d7c 100644
--- a/mineru/kit/commands/parse.py
+++ b/mineru/kit/commands/parse.py
@@ -6,11 +6,14 @@ from typing import Literal, cast
import typer
+from ...errors import MineruError
from ...filetypes import ensure_tier_supported_for_parse_extension, is_flash_only_parse_extension
from ...parser import MinerUApiParser
from ...parser import parse as local_parse
-from ...types import Tier
+from ...parser.api_client import _V1APIError
+from ...parser.page_range import normalize_page_range_input
from ...parser.tier import normalize_backend
+from ...types import Tier
from ..common import (
build_remote_api_url,
effective_local_tier_and_backend,
@@ -27,7 +30,7 @@ from ..output import print_info, print_success
def parse_cmd(
inputs: list[str] = typer.Argument(..., help="Input files or directories"),
output: str = typer.Option(..., "-o", "--output", help="Output path; required"),
- pages: str | None = typer.Option(None, "-p", "--pages", help="Page range, e.g. '1~5' or 'all'"),
+ pages: str | None = typer.Option(None, "-p", "--pages", help="PDF pages: '1-5,8,r3-r1' or 'all'; default: all pages"),
format: str = typer.Option(
"markdown",
"-f",
@@ -44,6 +47,10 @@ def parse_cmd(
disable_image_analysis: bool = typer.Option(False, "--disable-image-analysis", help="Disable image analysis"),
) -> None:
"""Parse files or directories into markdown, middle JSON, or zip outputs."""
+ try:
+ pages = normalize_page_range_input(pages)
+ except MineruError as exc:
+ exit_with_message(exc.code, str(exc), "pages")
output_format = cast(Literal["markdown", "middle_json", "zip"], format)
parse_tier = cast(Tier | None, tier)
parse_ocr_mode = cast(Literal["auto", "txt", "ocr"], ocr_mode)
@@ -107,6 +114,8 @@ def parse_cmd(
save_parse_result(result, dest, output_format)
if verbose:
print_info(str(parse_result_payload(path, dest, output_format)))
+ except (MineruError, _V1APIError) as exc:
+ exit_with_message(exc.code, str(exc), exc.param)
except Exception as exc:
exit_with_message("parse_failed", f"Failed to parse {path}: {exc}")
print_success(f"Parsed {len(paths)} input(s).")
diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.py
index 3fa7194d..e9b6ad08 100644
--- a/mineru/kit/gradio/app.py
+++ b/mineru/kit/gradio/app.py
@@ -4,13 +4,17 @@ from __future__ import annotations
import asyncio
import html
+import json
import os
from pathlib import Path
from collections.abc import Callable
from typing import Any, Literal
from urllib.parse import quote
+from ...errors import MineruError
from ...filetypes import IMAGE_EXTENSIONS, OFFICE_EXTENSIONS, PARSEABLE_EXTENSIONS, PDF_EXTENSIONS
+from ...parser.page_range import normalize_page_range_input
+from ...types import TIERS, Tier
from ...utils.stdio import configure_standard_streams
from .artifacts import RunArtifacts, markdown_for_gradio, persist_parse_result, render_download
from .client import (
@@ -131,6 +135,13 @@ def _default_tier(capabilities: V1ServerCapabilities) -> str:
return capabilities.tiers[0]
+def _tier_for_position(position: int | float, tier_choices: list[Tier]) -> Tier:
+ """把离散滑块位置映射为服务支持的 tier,并拒绝越界或非整数位置。"""
+ if isinstance(position, bool) or position not in range(len(tier_choices)):
+ raise ValueError("Invalid tier slider position")
+ return tier_choices[int(position)]
+
+
def _status_html(message: str) -> str:
"""生成不解释协议细节、只显示当前阶段的安全状态片段。"""
raw_message = str(message or _DEFAULT_STATUS)
@@ -186,7 +197,7 @@ def _effective_page_range(path_value: str | Path | None, raw_page_range: str | N
"""仅为 PDF 保留用户输入的 V1 page_range,其它格式统一返回空字符串。"""
if _file_suffix(path_value) not in PDF_EXTENSIONS:
return ""
- return str(raw_page_range or "").strip()
+ return normalize_page_range_input(raw_page_range)
def _is_pdf_or_image(path_value: str | Path | None) -> bool:
@@ -232,9 +243,9 @@ def build_gradio_app(
import gradio as gr
from gradio_pdf import PDF
- if not capabilities.tiers:
+ tier_choices = [tier for tier in TIERS if tier in capabilities.tiers]
+ if not tier_choices:
raise ValueError("V1 API server did not advertise any parsing tier")
- tier_choices = list(capabilities.tiers)
preferred_tier = _default_tier(capabilities)
file_types = _supported_file_types()
markdown_copy_kwargs = {"buttons": ["copy"]} if _gradio_major_version(gr) >= 6 else {"show_copy_button": True}
@@ -253,16 +264,28 @@ def build_gradio_app(
type="filepath",
elem_classes=["mineru-upload-file"],
)
- tier = gr.Dropdown(
- choices=tier_choices,
- value=preferred_tier,
- label="解析 tier",
- elem_classes=["mineru-tier-select"],
- )
+ with gr.Group():
+ tier_label = gr.Markdown(
+ value=f"解析 tier:{preferred_tier}",
+ padding=True,
+ elem_classes=["mineru-tier-label"],
+ )
+ tier = gr.Slider(
+ minimum=0,
+ # 单档位时保留非零跨度,避免原生滑块计算进度时除零。
+ maximum=max(1, len(tier_choices) - 1),
+ value=tier_choices.index(preferred_tier),
+ step=1,
+ precision=0,
+ interactive=len(tier_choices) > 1,
+ label="解析 tier",
+ show_label=False,
+ elem_classes=["mineru-tier-slider"],
+ )
page_range = gr.Textbox(
value="",
label="页码范围",
- placeholder="例如 1~5,8,-1;留空表示全部",
+ placeholder="例如 1-5,8,r1 或 all;留空表示全部",
interactive=False,
elem_classes=["mineru-kit-page-range"],
)
@@ -415,6 +438,18 @@ def build_gradio_app(
)
private_event_kwargs = _private_event_kwargs(gr)
+ tier.input(
+ fn=None,
+ inputs=tier,
+ outputs=tier_label,
+ js="""(position) => {
+ // 在浏览器端即时显示当前档位;实际解析独立读取滑块位置。
+ const tiers = %s;
+ return ["解析 tier:" + tiers[position]];
+ }"""
+ % json.dumps(tier_choices),
+ **private_event_kwargs,
+ )
input_file.change(
fn=update_file_preview,
inputs=input_file,
@@ -436,7 +471,7 @@ def build_gradio_app(
async def convert_handler(
file_path: str | None,
- selected_tier: str,
+ tier_position: int | float,
raw_page_range: str,
request: object | None = None,
) -> Any:
@@ -464,7 +499,16 @@ def build_gradio_app(
if suffix not in PARSEABLE_EXTENSIONS:
yield (_status_html(f"Failed: unsupported file type '.{suffix}'"), "", "", "", *empty_result[4:])
return
- page_text = _effective_page_range(source_path, raw_page_range)
+ try:
+ selected_tier = _tier_for_position(tier_position, tier_choices)
+ except ValueError as exc:
+ yield (_status_html(f"Failed: {exc}"), "", "", "", *empty_result[4:])
+ return
+ try:
+ page_text = _effective_page_range(source_path, raw_page_range)
+ except MineruError as exc:
+ yield (_status_html(f"Failed: {exc.code}: {exc}"), "", "", "", *empty_result[4:])
+ return
yield (_status_html(STATUS_PREPARING_REQUEST), "", "", "", *empty_result[4:])
status_queue: asyncio.Queue[str] = asyncio.Queue()
loop = asyncio.get_running_loop()
diff --git a/mineru/kit/gradio/artifacts.py b/mineru/kit/gradio/artifacts.py
index f62552a5..f397935d 100644
--- a/mineru/kit/gradio/artifacts.py
+++ b/mineru/kit/gradio/artifacts.py
@@ -514,8 +514,6 @@ def _prepare_origin_pdf(
with PDFDocument(source_bytes) as doc:
page_count = doc.page_count
page_indices = parse_page_range(page_range, page_count)
- if page_range.strip() and not page_indices:
- raise ValueError(f"Page range does not select any pages: {page_range}")
if page_indices == list(range(page_count)):
output_path.write_bytes(source_bytes)
return output_path, page_indices
diff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.py
index bf70924d..49796383 100644
--- a/mineru/kit/gradio/client.py
+++ b/mineru/kit/gradio/client.py
@@ -18,6 +18,7 @@ import httpx
from ...parser.api_client import MinerUApiParser, should_trust_env_for_url
from ...parser.base import ParseResult
+from ...parser.page_range import normalize_page_range_input
from ...parser.process_control import ManagedProcessControl
from ...types import SERVER_TIERS, TIERS, ServerTier, Tier
from ...utils.stdio import utf8_subprocess_env
@@ -183,6 +184,7 @@ class V1ArtifactClient:
status_callback: Callable[[str], None] | None = None,
) -> ParseResult:
"""通过 V1 API 解析单个文件,并返回带图片/模型输出的 `ParseResult`。"""
+ page_range = normalize_page_range_input(page_range)
if not path.is_file():
raise FileNotFoundError(path)
if tier not in TIERS:
diff --git a/mineru/parser/api_client.py b/mineru/parser/api_client.py
index 7e5fd013..cceef8ae 100644
--- a/mineru/parser/api_client.py
+++ b/mineru/parser/api_client.py
@@ -29,6 +29,7 @@ from ..filetypes import mime_type_for_extension
from ..types import PageInfo, Tier, validate_tier
from ..utils.image_payload import validate_image_sidecar_path
from .base import DocumentParser, ParseResult
+from .page_range import normalize_page_range_input
_POLL_INTERVAL_SECONDS = 1
_POLL_MAX_ATTEMPTS = 3600
@@ -99,6 +100,7 @@ class MinerUApiParser(DocumentParser):
# ── DocumentParser interface ─────────────────────────────────────
def parse(self, path: str | Path, *, page_range: str = "") -> ParseResult:
+ page_range = normalize_page_range_input(page_range)
file_path = Path(path)
if not file_path.exists():
raise FileNotFoundError(file_path)
@@ -108,6 +110,7 @@ class MinerUApiParser(DocumentParser):
return self._build_result(job, file_path.name)
async def parse_async(self, path: str | Path, *, page_range: str = "") -> ParseResult:
+ page_range = normalize_page_range_input(page_range)
file_path = Path(path)
if not file_path.exists():
raise FileNotFoundError(file_path)
@@ -160,6 +163,7 @@ class MinerUApiParser(DocumentParser):
return source
def _build_payload(self, source: dict[str, Any], page_range: str) -> dict[str, Any]:
+ page_range = normalize_page_range_input(page_range)
file_entry: dict[str, Any] = {"source": source}
if page_range:
file_entry["page_range"] = page_range
diff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.py
index 76582ef6..78c5f2b0 100644
--- a/mineru/parser/api_server.py
+++ b/mineru/parser/api_server.py
@@ -56,6 +56,12 @@ from ..utils.stdio import configure_standard_streams
from ..version import __version__
from . import parse_async
from .base import ParseResult
+from .page_range import (
+ PAGE_RANGE_DESCRIPTION,
+ count_pages_in_range as _count_pages_in_range,
+ format_page_range as _compact_page_numbers,
+ normalize_page_range_input,
+)
from .tier import (
ParserRuntimeOptions,
TierDependencyError,
@@ -445,7 +451,7 @@ FileSource = Annotated[
class JobFileEntry(BaseModel):
model_config = _PYDANTIC_CONFIG
source: FileSource
- page_range: str | None = None
+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION, examples=["1-5,8,r3-r1", "all"])
class CallbackConfig(BaseModel):
@@ -1245,22 +1251,6 @@ def _job_has_any_flash_only_inputs(req: CreateJobRequest, file_store: FileStore)
return any(is_flash_only_parse_extension(_source_name(entry.source, file_store)) for entry in req.files)
-def _compact_page_numbers(page_numbers: list[int]) -> str:
- if not page_numbers:
- return ""
- ordered = sorted(set(page_numbers))
- ranges: list[str] = []
- start = prev = ordered[0]
- for page in ordered[1:]:
- if page == prev + 1:
- prev = page
- continue
- ranges.append(str(start) if start == prev else f"{start}~{prev}")
- start = prev = page
- ranges.append(str(start) if start == prev else f"{start}~{prev}")
- return ",".join(ranges)
-
-
def _page_range_from_result_pages(pages: list[PageInfo]) -> str:
page_numbers: list[int] = []
for i, page in enumerate(pages):
@@ -1270,26 +1260,6 @@ def _page_range_from_result_pages(pages: list[PageInfo]) -> str:
return _compact_page_numbers(page_numbers)
-def _count_pages_in_range(page_range: str) -> int:
- total = 0
- for part in page_range.split(","):
- token = part.strip()
- if not token:
- continue
- if "~" not in token:
- total += 1
- continue
- left, right = token.split("~", 1)
- try:
- start = int(left)
- end = int(right)
- except ValueError:
- total += 1
- continue
- total += max(0, end - start + 1)
- return total
-
-
@dataclass(frozen=True, slots=True)
class _ExtractedSource:
"""保存 API 输入字节、响应类型及 HTML 来源上下文。"""
@@ -1787,6 +1757,13 @@ async def create_job(
access_level: AccessLevel = Depends(_resolve_access_level),
) -> Response:
"""Create a parse job."""
+ for index, entry in enumerate(body.files):
+ try:
+ entry.page_range = normalize_page_range_input(entry.page_range) or None
+ except MineruError as exc:
+ _raise_api_error(
+ 400, error_type=exc.type, code=exc.code, message=str(exc), param=f"files.{index}.page_range"
+ )
_require_model_preload_ready(request)
if body.callback is not None:
_raise_api_error(
diff --git a/mineru/parser/base.py b/mineru/parser/base.py
index 019b95f3..7d614782 100644
--- a/mineru/parser/base.py
+++ b/mineru/parser/base.py
@@ -227,7 +227,7 @@ class DocumentParser(ABC):
path:
Path to the document file.
page_range:
- PDF-only 1-based page range string (``"1~5,-3~-1"``). Empty means all pages.
+ PDF-only 1-based inclusive range (``"1-5,r3-r1"``). ``r1`` is the last page; empty or ``"all"`` means all pages.
"""
async def parse_async(self, path: str | Path, *, page_range: str = "") -> ParseResult:
diff --git a/mineru/parser/mineru_parser.py b/mineru/parser/mineru_parser.py
index 34a733b9..a8dfccbd 100644
--- a/mineru/parser/mineru_parser.py
+++ b/mineru/parser/mineru_parser.py
@@ -129,6 +129,9 @@ class MinerUParser(DocumentParser):
) -> _PreparedInput:
"""读取路径、检测类型并补齐 HTML 来源或 PDF 页范围状态。"""
from .file_type import guess_suffix_by_path
+ from .page_range import normalize_page_range_input
+
+ page_range = normalize_page_range_input(page_range)
file_name = path.stem
file_bytes = path.read_bytes()
@@ -201,16 +204,11 @@ class MinerUParser(DocumentParser):
from ..model.flash.pdf.document import PDFDocument
from .page_range import parse_page_range
- doc = PDFDocument(file_bytes)
- page_indices = parse_page_range(page_range, doc.page_count)
- if page_range.strip() and not page_indices:
- raise InvalidRequestError(
- "page_range_invalid",
- f"Page range does not select any pages: {page_range}",
- "page_range",
- )
+ with PDFDocument(file_bytes) as doc:
+ page_count = doc.page_count
+ page_indices = parse_page_range(page_range, page_count)
- if page_indices == list(range(doc.page_count)):
+ if page_indices == list(range(page_count)):
return file_bytes, None, None
from ..model.flash.pdf.pdfium import safe_rewrite_pdf_bytes_with_pdfium_result
diff --git a/mineru/parser/page_range.py b/mineru/parser/page_range.py
index a144efe5..113a85de 100644
--- a/mineru/parser/page_range.py
+++ b/mineru/parser/page_range.py
@@ -1,8 +1,23 @@
# Copyright (c) Opendatalab. All rights reserved.
+"""所有入口共享的页码范围语法、求值和格式化;默认选页策略由调用方决定。"""
+
from __future__ import annotations
+import re
+from collections.abc import Iterable
+
from loguru import logger
+from ..errors import InvalidRequestError
+
+PAGE_RANGE_DESCRIPTION = (
+ "PDF page selection: 1-based inclusive ranges, e.g. '1-5,8,r3-r1'; "
+ "'r1' is the last page and 'all' selects every page. Blank means unspecified. "
+ "Selections are sorted and deduplicated; out-of-bounds pages are omitted. "
+ "Reversed ranges, '~' and negative page numbers are invalid."
+)
+_SEGMENT_PATTERN = re.compile(r"(r?[1-9][0-9]*)(?:\s*-\s*(r?[1-9][0-9]*))?")
+
def get_end_page_id(end_page_id: int | None, pdf_page_num: int) -> int:
"""归一化旧 CLI 的 0-based 结束页,越界时钳制到最后一页。"""
@@ -13,47 +28,134 @@ def get_end_page_id(end_page_id: int | None, pdf_page_num: int) -> int:
return normalized_end_page_id
-def parse_page_range(raw: str, page_count: int) -> list[int]:
- """Parse a 1-based page-range string into a 0-based flattened list of page indices.
-
- Format (aligned with Unified API ``page_range``):
- ``"1~5"`` → pages 1 through 5
- ``"1,3,5~7"`` → pages 1, 3, 5, 6, 7
- ``"-5~-1"`` → last 5 pages (page_count=100 → [95, 96, 97, 98, 99])
- ``"5"`` → single page 5
- ``""`` → all pages
-
- Separator: ``~`` recommended, ``-`` also accepted.
- Negative values are resolved against *page_count* (e.g. ``-1`` = last page).
- Returns an empty list when every resolved segment is outside ``[0, page_count)``.
- """
- if not raw or not raw.strip():
- return list(range(page_count))
-
- result: list[int] = []
- for segment in raw.split(","):
- segment = segment.strip()
- if not segment:
- continue
- sep = "~" if "~" in segment else "-"
- parts = segment.split(sep, 1)
-
- def _resolve(token: str) -> int:
- n = int(token.strip())
- return page_count + n + 1 if n < 0 else n
-
- start_1b = _resolve(parts[0])
- end_1b = _resolve(parts[1]) if len(parts) > 1 and parts[1].strip() else start_1b
-
- start_0b = start_1b - 1 # 1-based → 0-based
- end_0b = end_1b - 1
-
- lo = max(0, min(start_0b, end_0b))
- hi = min(page_count - 1, max(start_0b, end_0b))
+def _invalid_range(raw: str | None, reason: str) -> InvalidRequestError:
+ """统一生成可跨 Python、CLI 和 HTTP 传递的页码错误。"""
+ return InvalidRequestError("page_range_invalid", f"Invalid page range {raw!r}: {reason}", "page_range")
+
+
+def _parse_endpoint(token: str) -> int:
+ """以负整数在内部标记倒数端点,外部输入只接受 rN。"""
+ return -int(token[1:]) if token.startswith("r") else int(token)
+
+
+def _parse_segments(raw: str | None) -> list[tuple[int, int]] | None:
+ """解析完整表达式;None 表示全部,倒数端点留待获得总页数后求值。"""
+ value = (raw or "").strip()
+ if not value or value == "all":
+ return None
+ segments: list[tuple[int, int]] = []
+ for part in value.split(","):
+ match = _SEGMENT_PATTERN.fullmatch(part.strip())
+ if match is None:
+ raise _invalid_range(raw, "expected a page, an inclusive range, or 'all'")
+ try:
+ start = _parse_endpoint(match[1])
+ end = _parse_endpoint(match[2]) if match[2] else start
+ except ValueError as exc:
+ raise _invalid_range(raw, "page number is too large") from exc
+ if (start > 0) == (end > 0) and start > end:
+ raise _invalid_range(raw, "reversed ranges are not supported")
+ segments.append((start, end))
+ return segments
+
+
+def _merge_intervals(intervals: Iterable[tuple[int, int]]) -> list[tuple[int, int]]:
+ """合并已求值区间,无需逐页展开即可排序、去重和连接相邻区间。"""
+ merged: list[tuple[int, int]] = []
+ for start, end in sorted(intervals):
+ if merged and start <= merged[-1][1] + 1:
+ merged[-1] = (merged[-1][0], max(end, merged[-1][1]))
+ else:
+ merged.append((start, end))
+ return merged
+
+
+def _format_endpoint(value: int) -> str:
+ """把内部端点转换为正整数或 rN 文本。"""
+ return str(value) if value > 0 else f"r{-value}"
+
+
+def _format_intervals(intervals: Iterable[tuple[int, int]]) -> str:
+ """生成无空白的范围文本,单页只输出一个端点。"""
+ return ",".join(
+ _format_endpoint(start) if start == end else f"{_format_endpoint(start)}-{_format_endpoint(end)}"
+ for start, end in intervals
+ )
+
+
+def normalize_page_range_input(raw: str | None) -> str:
+ """校验未绑定文档的输入,清理空白并保留 all/rN;空值统一为未指定。"""
+ segments = _parse_segments(raw)
+ if segments is None:
+ return "all" if (raw or "").strip() else ""
+ if all(start > 0 and end > 0 for start, end in segments):
+ segments = _merge_intervals(segments)
+ return _format_intervals(segments)
+
+
+def _resolved_intervals(raw: str | None, page_count: int) -> list[tuple[int, int]]:
+ """按文档总页数求值并裁剪,先验证所有区间再合并有效交集。"""
+ segments = _parse_segments(raw)
+ if page_count <= 0:
+ raise _invalid_range(raw, "document has no available pages")
+ if segments is None:
+ return [(1, page_count)]
+ intervals: list[tuple[int, int]] = []
+ for start, end in segments:
+ start = start if start > 0 else page_count + start + 1
+ end = end if end > 0 else page_count + end + 1
+ if start > end:
+ raise _invalid_range(raw, "reversed ranges are not supported")
+ lo, hi = max(1, start), min(page_count, end)
if lo <= hi:
- result.extend(range(lo, hi + 1))
+ intervals.append((lo, hi))
+ if not intervals:
+ raise _invalid_range(raw, "selection does not contain any available pages")
+ return _merge_intervals(intervals)
+
+
+def parse_page_range(raw: str, page_count: int) -> list[int]:
+ """把 1-based 表达式转换为去重升序的 0-based 页索引,空值选择全部。"""
+ return [page_idx for start, end in _resolved_intervals(raw, page_count) for page_idx in range(start - 1, end)]
+
+
+def expand_page_range(raw: str | None, page_count: int) -> str:
+ """将含 all/rN 的表达式展开为实际文档的正整数规范范围。"""
+ return _format_intervals(_resolved_intervals(raw, page_count))
+
+
+def _absolute_intervals(raw: str) -> list[tuple[int, int]]:
+ """读取已求值的覆盖范围;空文本表示空集合,禁止未经求值的 all/rN。"""
+ if not raw.strip():
+ return []
+ segments = _parse_segments(raw)
+ if segments is None or any(start < 0 or end < 0 for start, end in segments):
+ raise _invalid_range(raw, "page count is required to resolve all/rN")
+ return _merge_intervals(segments)
+
+
+def parse_page_range_set(raw: str) -> set[int]:
+ """把已求值的范围转换为 1-based 页码集合,供缓存覆盖与内容过滤使用。"""
+ return {page_no for start, end in _absolute_intervals(raw) for page_no in range(start, end + 1)}
+
+
+def count_pages_in_range(raw: str) -> int:
+ """统计已求值范围的唯一页数,不为统计分配逐页集合。"""
+ return sum(end - start + 1 for start, end in _absolute_intervals(raw))
+
- return sorted(set(result))
+def format_page_range(page_numbers: Iterable[int]) -> str:
+ """将 1-based 页码集合格式化为去重升序的连续范围;空集合输出空字符串。"""
+ return _format_intervals(_merge_intervals((page_no, page_no) for page_no in page_numbers))
-__all__ = ["get_end_page_id", "parse_page_range"]
+__all__ = [
+ "PAGE_RANGE_DESCRIPTION",
+ "count_pages_in_range",
+ "expand_page_range",
+ "format_page_range",
+ "get_end_page_id",
+ "normalize_page_range_input",
+ "parse_page_range",
+ "parse_page_range_set",
+]
diff --git a/mineru/resources/gradio_app.css b/mineru/resources/gradio_app.css
index 138e91a9..e7a449dc 100644
--- a/mineru/resources/gradio_app.css
+++ b/mineru/resources/gradio_app.css
@@ -46,6 +46,12 @@ body.dark .gradio-container {
top: 12px;
align-self: flex-start;
}
+/* 档位名称由上方 Markdown 显示,仅隐藏原生滑块的数字区,不修改轨道和滑块样式。 */
+.mineru-tier-slider .head,
+.mineru-tier-slider .min_value,
+.mineru-tier-slider .max_value {
+ display: none;
+}
.mineru-upload-file label[data-testid="block-label"] {
align-items: flex-start !important;
line-height: 1.35 !important;
diff --git a/tests/unittest/test_cli_next_command_design.py b/tests/unittest/test_cli_next_command_design.py
index daa5d8bb..a9facdba 100644
--- a/tests/unittest/test_cli_next_command_design.py
+++ b/tests/unittest/test_cli_next_command_design.py
@@ -358,7 +358,7 @@ def test_list_renderers_return_tables(monkeypatch: Any) -> None:
sha256="a" * 64,
short_id="aaaaaaa",
tier="basic",
- page_range="1~2",
+ page_range="1-2",
status="done",
privacy="local",
created_at=1,
@@ -405,7 +405,7 @@ def test_list_renderers_return_tables(monkeypatch: Any) -> None:
docs_table = list_resources._render_list_docs(ListDocsResponse(docs=[doc], total=1, limit=50))
assert parses_table.title == "Parses (1 total)"
- assert ("7", "done", "basic", "1~2", "aaaaaaa") in parses_table.rows
+ assert ("7", "done", "basic", "1-2", "aaaaaaa") in parses_table.rows
assert scans_table.title == "Scans (1 total)"
assert ("8", "done", "manual", "/tmp/docs", "3", "2", "1") in scans_table.rows
assert files_table.title == "Files (1 total)"
@@ -426,7 +426,7 @@ def test_config_and_rule_renderers_return_tables(monkeypatch: Any) -> None:
parsing_table = config._render_parsing_rules(
ParsingRuleListResponse(
rules=[
- ParsingRuleInfo(id=4, pattern="*.pdf", tier="basic", page_range="1~2", remote=True, name="pdfs")
+ ParsingRuleInfo(id=4, pattern="*.pdf", tier="basic", page_range="1-2", remote=True, name="pdfs")
]
)
)
@@ -436,7 +436,7 @@ def test_config_and_rule_renderers_return_tables(monkeypatch: Any) -> None:
assert exclude_table.title == "Exclude Rules"
assert ("3", "*.tmp", "10") in exclude_table.rows
assert parsing_table.title == "Parsing Rules"
- assert ("4", "*.pdf", "basic", "1~2", "yes", "pdfs") in parsing_table.rows
+ assert ("4", "*.pdf", "basic", "1-2", "yes", "pdfs") in parsing_table.rows
def test_watch_list_renderer_returns_table(monkeypatch: Any) -> None:
@@ -738,7 +738,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_p
sha256="a" * 64,
short_id="aaaaaaa",
tier="standard",
- page_range="1~10",
+ page_range="1-10",
status="failed",
privacy="remote",
created_at=1,
@@ -751,7 +751,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_p
sha256="a" * 64,
short_id="aaaaaaa",
tier="standard",
- page_range="1~10",
+ page_range="1-10",
status="done",
privacy="remote",
via="remote",
@@ -768,7 +768,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_p
return ParseResponse(
sha256="a" * 64,
tier="standard",
- page_range="1~10",
+ page_range="1-10",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -785,7 +785,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_p
tier="standard",
format="markdown",
content="parsed",
- request_scope=ContentRequestScope(page_range="1~10", after=None, limit=30000),
+ request_scope=ContentRequestScope(page_range="1-10", after=None, limit=30000),
)
monkeypatch.setattr(parse, "DoclibClient", _Client)
@@ -810,7 +810,7 @@ def test_parse_wait_json_maps_invalid_api_key_param(monkeypatch: Any, tmp_path:
sha256="a" * 64,
short_id="aaaaaaa",
tier="standard",
- page_range="1~1",
+ page_range="1-1",
status="failed",
privacy="remote",
created_at=3,
@@ -827,7 +827,7 @@ def test_parse_wait_json_maps_invalid_api_key_param(monkeypatch: Any, tmp_path:
return ParseResponse(
sha256="a" * 64,
tier="standard",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -917,7 +917,7 @@ def test_parse_verbose_json_writes_cache_hit_notice_to_stderr(monkeypatch: Any,
assert timeout == 90
def ensure_parse(self, request: Any) -> ParseResponse:
- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~1", status="done", cache_hit=True)
+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-1", status="done", cache_hit=True)
def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:
return DocContentResponse(
@@ -926,7 +926,7 @@ def test_parse_verbose_json_writes_cache_hit_notice_to_stderr(monkeypatch: Any,
tier="flash",
format="markdown",
content="parsed",
- request_scope=ContentRequestScope(page_range="1~1", limit=30000),
+ request_scope=ContentRequestScope(page_range="1-1", limit=30000),
)
monkeypatch.setattr(parse, "DoclibClient", _Client)
@@ -950,7 +950,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_
sha256="a" * 64,
short_id="aaaaaaa",
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="done",
privacy="local",
created_at=3,
@@ -966,7 +966,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -982,7 +982,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_
tier="flash",
format="markdown",
content="parsed",
- request_scope=ContentRequestScope(page_range="1~1", limit=30000),
+ request_scope=ContentRequestScope(page_range="1-1", limit=30000),
)
monkeypatch.setattr(parse, "DoclibClient", _Client)
@@ -1114,20 +1114,20 @@ def test_parse_ingest_error_json_is_machine_readable(monkeypatch: Any, tmp_path:
def test_parse_next_marker_quotes_windows_path() -> None:
path = r"C:\Users\jinzhenj\Downloads\2606.20787v1.pdf"
- marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7~10"))
+ marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7-10"))
assert marker is not None
command = marker.removeprefix("<!-- Next: ").removesuffix(" -->")
- assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7~10"]
+ assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7-10"]
def test_parse_next_marker_escapes_double_quotes_in_path() -> None:
path = r'C:\Users\jinzhenj\Downloads\bad"name.pdf'
- marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7~10"))
+ marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7-10"))
assert marker is not None
command = marker.removeprefix("<!-- Next: ").removesuffix(" -->")
- assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7~10"]
+ assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7-10"]
def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tmp_path: Path) -> None:
@@ -1141,7 +1141,7 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tm
def ensure_parse(self, request: Any) -> ParseResponse:
assert request.tier == "flash"
assert request.remote is True
- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~10", status="done", cache_hit=True)
+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-10", status="done", cache_hit=True)
def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:
assert kwargs["limit"] == 30000
@@ -1151,8 +1151,8 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tm
tier="flash",
format="markdown",
content="parsed",
- request_scope=ContentRequestScope(page_range="1~10", limit=30000),
- next_request=ContentNextRequest(page_range="11~20"),
+ request_scope=ContentRequestScope(page_range="1-10", limit=30000),
+ next_request=ContentNextRequest(page_range="11-20"),
)
monkeypatch.setattr(parse, "DoclibClient", _Client)
@@ -1172,7 +1172,7 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tm
"--limit",
"30000",
"--pages",
- "11~20",
+ "11-20",
]
@@ -1187,7 +1187,7 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_pat
def ensure_parse(self, request: Any) -> ParseResponse:
assert request.tier is None
assert request.remote is False
- return ParseResponse(sha256="a" * 64, tier="basic", page_range="1~10", status="done", cache_hit=True)
+ return ParseResponse(sha256="a" * 64, tier="basic", page_range="1-10", status="done", cache_hit=True)
def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:
assert kwargs["limit"] == 30000
@@ -1197,8 +1197,8 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_pat
tier="basic",
format="markdown",
content="parsed",
- request_scope=ContentRequestScope(page_range="1~10", limit=30000),
- next_request=ContentNextRequest(page_range="11~20"),
+ request_scope=ContentRequestScope(page_range="1-10", limit=30000),
+ next_request=ContentNextRequest(page_range="11-20"),
)
monkeypatch.setattr(parse, "DoclibClient", _Client)
@@ -1208,7 +1208,7 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_pat
assert result.exit_code == 0
marker = result.output.strip().splitlines()[-1]
command = marker.removeprefix("<!-- Next: ").removesuffix(" -->")
- assert shlex.split(command) == ["mineru", "parse", str(source.resolve()), "--pages", "11~20"]
+ assert shlex.split(command) == ["mineru", "parse", str(source.resolve()), "--pages", "11-20"]
def test_parse_json_no_wait_wraps_parse_and_null_content(monkeypatch: Any, tmp_path: Path) -> None:
@@ -1223,7 +1223,7 @@ def test_parse_json_no_wait_wraps_parse_and_null_content(monkeypatch: Any, tmp_p
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1252,7 +1252,7 @@ def test_parse_no_wait_text_prints_parse_id_tracking_hint(monkeypatch: Any, tmp_
return ParseResponse(
sha256="a" * 64,
tier="standard",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[4686],
created_parse_ids=[4686],
@@ -1282,7 +1282,7 @@ def test_parse_no_wait_text_prints_multiple_parse_id_tracking_hints(monkeypatch:
return ParseResponse(
sha256="a" * 64,
tier="standard",
- page_range="1~2",
+ page_range="1-2",
status="pending",
wait_parse_ids=[4686, 4687],
created_parse_ids=[4687],
@@ -1319,7 +1319,7 @@ def test_parse_expands_user_home_in_input_path(monkeypatch: Any, tmp_path: Path)
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1386,7 +1386,7 @@ def test_parse_json_output_writes_file_and_returns_output_object(monkeypatch: An
assert timeout == 90
def ensure_parse(self, request: Any) -> ParseResponse:
- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~1", status="done", cache_hit=True)
+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-1", status="done", cache_hit=True)
def export_doc_content(self, doc_ref: str, request: Any) -> Any:
Path(request.output).write_text("exported", encoding="utf-8")
@@ -1414,7 +1414,7 @@ def test_parse_wait_status_line_is_verbose_only(monkeypatch: Any, tmp_path: Path
sha256="a" * 64,
short_id="aaaaaaa",
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="done",
privacy="local",
via="local",
@@ -1431,7 +1431,7 @@ def test_parse_wait_status_line_is_verbose_only(monkeypatch: Any, tmp_path: Path
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1472,7 +1472,7 @@ def test_parse_wait_timeout_json_returns_timeout_error(monkeypatch: Any, tmp_pat
sha256="a" * 64,
short_id="aaaaaaa",
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
privacy="local",
via="local",
@@ -1488,7 +1488,7 @@ def test_parse_wait_timeout_json_returns_timeout_error(monkeypatch: Any, tmp_pat
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1528,7 +1528,7 @@ def test_parse_wait_timeout_text_returns_nonzero_exit(monkeypatch: Any, tmp_path
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1559,7 +1559,7 @@ def test_parse_wait_timeout_json_uses_latest_parsing_status(monkeypatch: Any, tm
sha256="a" * 64,
short_id="aaaaaaa",
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="parsing",
privacy="local",
via="local",
@@ -1575,7 +1575,7 @@ def test_parse_wait_timeout_json_uses_latest_parsing_status(monkeypatch: Any, tm
return ParseResponse(
sha256="a" * 64,
tier="flash",
- page_range="1~1",
+ page_range="1-1",
status="pending",
wait_parse_ids=[3],
created_parse_ids=[3],
@@ -1709,7 +1709,7 @@ def test_parse_rejects_reverse_page_range_as_json_error(monkeypatch: Any, tmp_pa
monkeypatch.setattr(parse, "DoclibClient", _Client)
- result = runner.invoke(app, ["parse", str(source), "--tier", "flash", "--pages", "2~1", "--json"])
+ result = runner.invoke(app, ["parse", str(source), "--tier", "flash", "--pages", "2-1", "--json"])
assert result.exit_code == 1
payload = json.loads(result.output)
diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.py
index b8bae2ec..7cb7675c 100644
--- a/tests/unittest/test_doclib_cache_semantics.py
+++ b/tests/unittest/test_doclib_cache_semantics.py
@@ -319,12 +319,12 @@ def test_load_pages_from_done_batches_keeps_newest_page_idx(tmp_path: Path) -> N
"blocks": [{"type": "text", "index": 0, "bbox": [0.0, 0.0, 0.1, 0.1], "content": _inline("newer")}],
}
- _write_batch(tmp_path, sha256, tier, "1~2", 1000, [older_page, older_duplicate])
+ _write_batch(tmp_path, sha256, tier, "1-2", 1000, [older_page, older_duplicate])
_write_batch(tmp_path, sha256, tier, "2", 2000, [newer_duplicate])
done_rows = [
{"page_range": "2", "done_at": 2000},
- {"page_range": "1~2", "done_at": 1000},
+ {"page_range": "1-2", "done_at": 1000},
]
pages = load_pages_from_done_batches(str(tmp_path), sha256, tier, done_rows)
@@ -1225,24 +1225,24 @@ def test_compaction_uses_configured_data_dir(tmp_path: Path) -> None:
older_duplicate = {"page_idx": 1, "content": "old"}
newer_duplicate = {"page_idx": 1, "content": "new"}
- _write_batch(tmp_path, sha256, tier, "1~2", 1000, [older_page, older_duplicate])
+ _write_batch(tmp_path, sha256, tier, "1-2", 1000, [older_page, older_duplicate])
_write_batch(tmp_path, sha256, tier, "2", 2000, [newer_duplicate])
compaction = Compaction(db=None, interval_sec=600, data_dir=str(tmp_path))
done_rows = [
{"page_range": "2", "done_at": 2000},
- {"page_range": "1~2", "done_at": 1000},
+ {"page_range": "1-2", "done_at": 1000},
]
- asyncio.run(compaction._compact_json(sha256, tier, ["1~2"], done_rows, 2000))
+ asyncio.run(compaction._compact_json(sha256, tier, ["1-2"], done_rows, 2000))
- compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~2", 2000))
+ compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-2", 2000))
compacted = json.loads(compacted_path.read_text(encoding="utf-8"))
assert compacted["schema_version"] == MIDDLE_JSON_SCHEMA_VERSION
assert compacted["is_full_document"] is True
assert compacted["pages"] == [older_page, newer_duplicate]
- assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1~2_2000.json"]
+ assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1-2_2000.json"]
def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -> None:
@@ -1263,13 +1263,13 @@ def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -
await db.execute(
"INSERT INTO parses (sha256, tier, page_range, status, done_at, created_at, updated_at) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
- (sha256, tier, "1~10", "done", done_at, done_at, done_at),
+ (sha256, tier, "1-10", "done", done_at, done_at, done_at),
)
_write_batch(
tmp_path,
sha256,
tier,
- "1~10",
+ "1-10",
done_at,
[{"page_idx": page_idx, "blocks": []} for page_idx in range(12)],
file_suffix="epub",
@@ -1280,13 +1280,13 @@ def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -
rows = await db.fetchall("SELECT page_range, done_at FROM parses WHERE sha256=? AND tier=?", (sha256, tier))
doc = await db.fetchone("SELECT page_count FROM docs WHERE sha256=?", (sha256,))
- compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~12", 2000))
+ compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-12", 2000))
compacted = json.loads(compacted_path.read_text(encoding="utf-8"))
- assert rows == [{"page_range": "1~12", "done_at": 2000}]
+ assert rows == [{"page_range": "1-12", "done_at": 2000}]
assert doc == {"page_count": 12}
assert compacted["is_full_document"] is True
assert [page["page_idx"] for page in compacted["pages"]] == list(range(12))
- assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1~12_2000.json"]
+ assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1-12_2000.json"]
asyncio.run(_run())
@@ -1305,7 +1305,7 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)
"VALUES (?, ?, ?, ?, ?, ?, ?)",
(sha256, "eeeeeee", 1, "epub", 12, 1, 1),
)
- for page_range, done_at in (("1~10", 1000), ("11~12", 2000)):
+ for page_range, done_at in (("1-10", 1000), ("11-12", 2000)):
await db.execute(
"INSERT INTO parses (sha256, tier, page_range, status, done_at, created_at, updated_at) "
"VALUES (?, ?, ?, ?, ?, ?, ?)",
@@ -1315,7 +1315,7 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)
tmp_path,
sha256,
tier,
- "1~10",
+ "1-10",
1000,
[{"page_idx": page_idx, "blocks": []} for page_idx in range(10)],
file_suffix="epub",
@@ -1327,8 +1327,8 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)
"SELECT page_range, done_at FROM parses WHERE sha256=? AND tier=? ORDER BY done_at",
(sha256, tier),
)
- assert rows == [{"page_range": "1~10", "done_at": 1000}, {"page_range": "11~12", "done_at": 2000}]
- assert Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~10", 1000)).is_file()
+ assert rows == [{"page_range": "1-10", "done_at": 1000}, {"page_range": "11-12", "done_at": 2000}]
+ assert Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-10", 1000)).is_file()
asyncio.run(_run())
@@ -1970,7 +1970,7 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:
"id": 10,
"sha256": sha256,
"tier": "standard",
- "page_range": "1~5",
+ "page_range": "1-5",
"status": "done",
"priority": 0,
"done_at": 1000,
@@ -1980,7 +1980,7 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:
"id": 11,
"sha256": sha256,
"tier": "standard",
- "page_range": "6~8",
+ "page_range": "6-8",
"status": "pending",
"priority": 0,
"done_at": None,
@@ -2004,18 +2004,18 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:
)
service = ParseService(db=db, fts=_FakeFTS(), config_svc=None, data_dir=str(tmp_path), parse_lock_timeout_sec=1800)
- result = asyncio.run(service.request_parse(path, tier="standard", page_range="1~10", force=True))
+ result = asyncio.run(service.request_parse(path, tier="standard", page_range="1-10", force=True))
assert isinstance(result, ParseResponse)
assert result.wait_parse_ids == [11, 12]
assert result.reused_parse_ids == [11]
assert result.created_parse_ids == [12]
- assert result.page_range == "1~10"
+ assert result.page_range == "1-10"
assert result.short_id == "eeeeeee"
assert result.status == "pending"
assert result.cache_hit is False
assert db.updated_priorities == [11]
- assert parses[-1]["page_range"] == "1~5,9~10"
+ assert parses[-1]["page_range"] == "1-5,9-10"
def test_non_pdf_requests_use_one_full_document_batch(
@@ -2059,7 +2059,7 @@ def test_non_pdf_requests_use_one_full_document_batch(
monkeypatch.setattr(parse_svc_module, "extract_metadata", _metadata)
initial = await service.request_parse(str(source))
- assert initial.page_range == "1~12"
+ assert initial.page_range == "1-12"
assert initial.created_parse_ids == []
assert len(initial.reused_parse_ids) == 1
initial_id = initial.reused_parse_ids[0]
@@ -2069,41 +2069,41 @@ def test_non_pdf_requests_use_one_full_document_batch(
await db.execute(
"UPDATE parses SET page_range=?, status=?, done_at=?, updated_at=? WHERE id=?",
- ("1~10", "done", 1000, 1000, initial_id),
+ ("1-10", "done", 1000, 1000, initial_id),
)
_write_batch(
tmp_path / "data",
sha256,
"flash",
- "1~10",
+ "1-10",
1000,
[{"page_idx": page_idx, "blocks": []} for page_idx in range(12)],
file_suffix="epub",
)
repaired = await service.request_parse(str(source))
- assert repaired.page_range == "1~12"
+ assert repaired.page_range == "1-12"
assert len(repaired.created_parse_ids) == 1
repaired_id = repaired.created_parse_ids[0]
repaired_row = await db.fetchone("SELECT page_range, status FROM parses WHERE id=?", (repaired_id,))
- assert repaired_row == {"page_range": "1~12", "status": "pending"}
+ assert repaired_row == {"page_range": "1-12", "status": "pending"}
reused = await service.request_parse(str(source), force=True)
assert reused.created_parse_ids == []
assert reused.reused_parse_ids == [repaired_id]
- assert reused.page_range == "1~12"
+ assert reused.page_range == "1-12"
asyncio.run(_run())
def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> None:
parses = [
- {"id": 1, "sha256": "f" * 64, "tier": "standard", "page_range": "1~5", "status": "done", "done_at": 1000},
+ {"id": 1, "sha256": "f" * 64, "tier": "standard", "page_range": "1-5", "status": "done", "done_at": 1000},
{
"id": 2,
"sha256": "f" * 64,
"tier": "standard",
- "page_range": "6~10",
+ "page_range": "6-10",
"status": "failed",
"error_code": "parse_failed",
"error_msg": "boom",
@@ -2119,7 +2119,7 @@ def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> Non
"id": 2,
"sha256": "f" * 64,
"tier": "standard",
- "page_range": "6~10",
+ "page_range": "6-10",
"status": "failed",
"done_at": None,
"created_at": None,
@@ -2130,7 +2130,7 @@ def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> Non
"id": 1,
"sha256": "f" * 64,
"tier": "standard",
- "page_range": "1~5",
+ "page_range": "1-5",
"status": "done",
"done_at": 1000,
"created_at": None,
@@ -2149,12 +2149,12 @@ def test_filter_pages_by_user_range_uses_one_based_page_numbers() -> None:
def test_expand_page_range_uses_available_subset_and_merges_ranges() -> None:
- assert expand_page_range("1~10,3,4~5", 5) == "1~5"
+ assert expand_page_range("1-10,3,4-5", 5) == "1-5"
def test_expand_page_range_rejects_empty_available_subset() -> None:
with pytest.raises(InvalidRequestError) as exc_info:
- expand_page_range("6~10", 5)
+ expand_page_range("6-10", 5)
assert exc_info.value.code == "page_range_invalid"
@@ -2173,7 +2173,7 @@ def test_remap_api_result_pages_to_non_contiguous_page_range() -> None:
)
)
- _remap_api_result_pages_to_page_range(result, "11,13~14")
+ _remap_api_result_pages_to_page_range(result, "11,13-14")
assert [page.page_idx for page in result.pages] == [10, 12, 13]
@@ -2213,7 +2213,7 @@ def test_remap_api_result_pages_rejects_count_mismatch() -> None:
)
with pytest.raises(ParseFailure) as exc:
- _remap_api_result_pages_to_page_range(result, "11~13")
+ _remap_api_result_pages_to_page_range(result, "11-13")
assert exc.value.code == "parse_page_remap_failed"
@@ -3673,7 +3673,7 @@ def test_read_locator_out_of_range_page_returns_page_range_invalid(tmp_path: Pat
assert exc_info.value.code == "page_range_invalid"
assert exc_info.value.param == "page_range"
- assert exc_info.value.message == "Page range does not select any pages: 500"
+ assert "500" in exc_info.value.message and "available pages" in exc_info.value.message
finally:
await db.close()
@@ -4680,7 +4680,7 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:
"id": 1,
"sha256": sha256,
"tier": "flash",
- "page_range": "1~10",
+ "page_range": "1-10",
"status": "parsing",
"privacy": "local",
}
@@ -4714,7 +4714,7 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:
async def _parse(file_row: dict, tier: Tier, page_range: str) -> ParseResult:
"""返回十二页整本 EPUB 结果。"""
- assert page_range == "1~10"
+ assert page_range == "1-10"
return ParseResult(
middle_json=MiddleJson(
pages=[PageInfo(page_idx=page_idx) for page_idx in range(12)],
@@ -4736,11 +4736,11 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:
assert asyncio.run(service.process_doc(task)) is True
assert parses[0]["status"] == "done"
- assert parses[0]["page_range"] == "1~12"
+ assert parses[0]["page_range"] == "1-12"
assert doc_row["page_count"] == 12
- batch_path = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1~12", parses[0]["done_at"]))
+ batch_path = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-12", parses[0]["done_at"]))
assert batch_path.is_file()
- assert not Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1~10", parses[0]["done_at"])).exists()
+ assert not Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-10", parses[0]["done_at"])).exists()
assert len(json.loads(batch_path.read_text(encoding="utf-8"))["pages"]) == 12
diff --git a/tests/unittest/test_doclib_interface_contract.py b/tests/unittest/test_doclib_interface_contract.py
index b201ac35..d2c0e53e 100644
--- a/tests/unittest/test_doclib_interface_contract.py
+++ b/tests/unittest/test_doclib_interface_contract.py
@@ -363,7 +363,7 @@ def test_cleanup_temp_rejects_negative_older_than(tmp_path) -> None:
def test_core_doclib_schemas_are_instantiable() -> None:
- parse_request = ParseRequest(path="/tmp/a.pdf", tier=None, page_range="1~5")
+ parse_request = ParseRequest(path="/tmp/a.pdf", tier=None, page_range="1-5")
forget_request = ForgetPathRequest(path="/tmp/a.pdf")
forget_response = ForgetPathResponse(path="/tmp/a.pdf", matched_as="file", forgotten_files=1, dry_run=True)
scan_request = ScanRequest(path="/tmp", kind="manual", source="cli")
@@ -436,7 +436,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:
sha256="abc",
short_id="abc",
tier="standard",
- page_range="1~2",
+ page_range="1-2",
status="pending",
priority=10,
privacy="local",
@@ -447,7 +447,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:
error_code="parse_failed",
error_msg="failed",
)
- tier_info = TierParseInfo(tier="standard", page_range="1~2", status="pending")
+ tier_info = TierParseInfo(tier="standard", page_range="1-2", status="pending")
info = FileInfoResponse(
file=file_info,
doc=doc_info,
@@ -456,7 +456,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:
)
watch = WatchInfo(id=1, path="/tmp", recursive=True, status="active", last_scan_at=100, last_scan_files=3)
exclude_rule = ExcludeRuleInfo(id=2, pattern="*.tmp", hit_count=4)
- parsing_rule = ParsingRuleInfo(id=3, pattern="*.pdf", tier="standard", page_range="1~5", remote=True)
+ parsing_rule = ParsingRuleInfo(id=3, pattern="*.pdf", tier="standard", page_range="1-5", remote=True)
watches = WatchListResponse(watches=[watch])
exclude_rules = ExcludeRuleListResponse(rules=[exclude_rule])
parsing_rules = ParsingRuleListResponse(rules=[parsing_rule])
@@ -498,7 +498,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:
remove_exclude_response = RemoveExcludeRuleResponse(rule_id=2, removed=True)
remove_parsing_response = RemoveParsingRuleResponse(rule_id=3, removed=True)
exclude_rule_request = ExcludeRuleRequest(pattern="*.tmp")
- parsing_rule_request = ParsingRuleRequest(pattern="*.pdf", tier="standard", page_range="1~5")
+ parsing_rule_request = ParsingRuleRequest(pattern="*.pdf", tier="standard", page_range="1-5")
error_info = ErrorInfo(type="invalid_request_error", code="file_not_found", message="missing", param="path")
error_response = ErrorResponse(error=error_info)
@@ -555,7 +555,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:
def test_parse_request_rejects_auto_tier() -> None:
with pytest.raises(ValidationError):
- ParseRequest(path="/tmp/a.pdf", tier="auto", page_range="1~5")
+ ParseRequest(path="/tmp/a.pdf", tier="auto", page_range="1-5")
def test_parse_response_status_is_submit_state_only() -> None:
diff --git a/tests/unittest/test_doclib_progressive_reading.py b/tests/unittest/test_doclib_progressive_reading.py
index 207dafb7..81eef5e5 100644
--- a/tests/unittest/test_doclib_progressive_reading.py
+++ b/tests/unittest/test_doclib_progressive_reading.py
@@ -23,22 +23,22 @@ def _page(page_idx: int, *texts: str) -> PageInfo:
def test_paginated_default_content_pages_are_first_ten() -> None:
doc = {"page_count": 38}
- assert _normalize_content_page_range(None, None, doc) == "1~10"
- assert _normalize_content_page_range("all", None, doc) == "1~38"
- assert _normalize_content_page_range("1~5,-5~-1", None, doc) == "1~5,34~38"
+ assert _normalize_content_page_range(None, None, doc) == "1-10"
+ assert _normalize_content_page_range("all", None, doc) == "1-38"
+ assert _normalize_content_page_range("1-5,r5-r1", None, doc) == "1-5,34-38"
def test_content_page_range_uses_available_subset_and_merges_ranges() -> None:
doc = {"page_count": 5}
- assert _normalize_content_page_range("1~10,3,4~5", None, doc) == "1~5"
+ assert _normalize_content_page_range("1-10,3,4-5", None, doc) == "1-5"
def test_content_page_range_rejects_empty_available_subset() -> None:
doc = {"page_count": 5}
with pytest.raises(InvalidRequestError) as exc_info:
- _normalize_content_page_range("6~10", None, doc)
+ _normalize_content_page_range("6-10", None, doc)
assert exc_info.value.code == "page_range_invalid"
@@ -48,16 +48,16 @@ def test_paginated_page_boundary_truncation_suggests_pages_only() -> None:
rendered = _render_progressive_markdown(pages, short_id="ab12cd3", tier="standard", after=None, limit=40, add_markers=False)
next_request = _next_content_request(
rendered=rendered,
- request_page_range="1~10",
+ request_page_range="1-10",
after=None,
page_count=38,
paginated=True,
)
assert rendered.truncated is True
- assert rendered.content_ranges[0].page_range == "1~5"
+ assert rendered.content_ranges[0].page_range == "1-5"
assert next_request is not None
- assert next_request.page_range == "6~10"
+ assert next_request.page_range == "6-10"
assert next_request.after is None
@@ -66,7 +66,7 @@ def test_paginated_long_single_page_truncation_keeps_pages_with_after() -> None:
rendered = _render_progressive_markdown(pages, short_id="ab12cd3", tier="standard", after=None, limit=40, add_markers=False)
next_request = _next_content_request(
rendered=rendered,
- request_page_range="7~10",
+ request_page_range="7-10",
after=None,
page_count=38,
paginated=True,
@@ -75,7 +75,7 @@ def test_paginated_long_single_page_truncation_keeps_pages_with_after() -> None:
assert rendered.truncated is True
assert rendered.content_ranges[-1].end.startswith("doc:ab12cd3/tier:standard/page:7/block:1/char:")
assert next_request is not None
- assert next_request.page_range == "7~10"
+ assert next_request.page_range == "7-10"
assert next_request.after == rendered.content_ranges[-1].end
@@ -113,14 +113,14 @@ def test_non_contiguous_pages_suggest_after_last_requested_page() -> None:
)
next_request = _next_content_request(
rendered=rendered,
- request_page_range="1~5,20~25",
+ request_page_range="1-5,20-25",
after=None,
page_count=38,
paginated=True,
)
assert next_request is not None
- assert next_request.page_range == "26~35"
+ assert next_request.page_range == "26-35"
def test_truncated_false_can_still_have_next_request() -> None:
@@ -134,7 +134,7 @@ def test_truncated_false_can_still_have_next_request() -> None:
)
next_request = _next_content_request(
rendered=rendered,
- request_page_range="1~10",
+ request_page_range="1-10",
after=None,
page_count=38,
paginated=True,
@@ -142,7 +142,7 @@ def test_truncated_false_can_still_have_next_request() -> None:
assert rendered.truncated is False
assert next_request is not None
- assert next_request.page_range == "11~20"
+ assert next_request.page_range == "11-20"
def test_paginated_next_request_is_never_after_only() -> None:
@@ -164,14 +164,14 @@ def test_paginated_next_request_is_never_after_only() -> None:
"cut_inside_page": True,
},
)(),
- request_page_range="7~10",
+ request_page_range="7-10",
after=None,
page_count=38,
paginated=True,
)
assert next_request is not None
- assert next_request.page_range == "7~10"
+ assert next_request.page_range == "7-10"
assert next_request.after is not None
diff --git a/tests/unittest/test_doclib_telemetry_core.py b/tests/unittest/test_doclib_telemetry_core.py
index e4a71a3a..f81b1550 100644
--- a/tests/unittest/test_doclib_telemetry_core.py
+++ b/tests/unittest/test_doclib_telemetry_core.py
@@ -463,7 +463,7 @@ def test_parse_wait_observation_uses_parse_rows_for_tier_and_pages_bucket(tmp_pa
)
await db.execute(
"INSERT INTO parses (sha256, tier, page_range, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
- ("sha", "standard", "1~3", "done", now, now),
+ ("sha", "standard", "1-3", "done", now, now),
)
row = await db.fetchone("SELECT id FROM parses WHERE sha256=?", ("sha",))
diff --git a/tests/unittest/test_flash_epub.py b/tests/unittest/test_flash_epub.py
index a20fba47..5d9cc70b 100644
--- a/tests/unittest/test_flash_epub.py
+++ b/tests/unittest/test_flash_epub.py
@@ -410,11 +410,11 @@ def test_public_parser_rejects_epub_page_range(tmp_path: Path) -> None:
source.write_bytes(build_epub_fixture())
with pytest.raises(InvalidRequestError, match="only supported for PDF") as exc_info:
- parse(source, page_range="2~3")
+ parse(source, page_range="2-3")
assert exc_info.value.code == "page_range_invalid"
with pytest.raises(InvalidRequestError, match="only supported for PDF"):
- asyncio.run(parse_async(source, page_range="2~3"))
+ asyncio.run(parse_async(source, page_range="2-3"))
@pytest.mark.parametrize(
@@ -976,7 +976,7 @@ def test_doclib_ingests_epub_as_local_flash_with_spine_page_count(tmp_path: Path
)
assert response.tier == "flash"
assert doc == {"file_type": "epub", "page_count": 3}
- assert parses == [{"tier": "flash", "status": "pending", "privacy": "local", "page_range": "1~3"}]
+ assert parses == [{"tier": "flash", "status": "pending", "privacy": "local", "page_range": "1-3"}]
with pytest.raises(InvalidRequestError) as range_exc:
await service.request_parse(str(source), tier="flash", page_range="2")
@@ -1005,7 +1005,7 @@ def test_doclib_local_epub_task_clears_persisted_full_page_range(monkeypatch: py
service._parse_via_local( # type: ignore[arg-type]
{"path": "/tmp/book.epub", "ext": "epub"},
"flash",
- "1~3",
+ "1-3",
)
)
assert result is expected
diff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.py
index b015cac0..f6711950 100644
--- a/tests/unittest/test_kit_gradio.py
+++ b/tests/unittest/test_kit_gradio.py
@@ -8,6 +8,7 @@ import zipfile
from pathlib import Path
from types import SimpleNamespace
from typing import Any
+from unittest.mock import AsyncMock
import httpx
import pytest
@@ -398,15 +399,15 @@ def test_v1_client_preserves_v1_error_code(monkeypatch: pytest.MonkeyPatch, tmp_
async def parse_async(self, _path: Path, *, page_range: str) -> ParseResult:
"""抛出与正式 API client 一致的错误形态。"""
error = RuntimeError(f"bad range: {page_range}")
- error.code = "invalid_page_range" # type: ignore[attr-defined]
+ error.code = "page_range_invalid" # type: ignore[attr-defined]
raise error
monkeypatch.setattr(gradio_client, "MinerUApiParser", FailingParser)
client = V1ArtifactClient(api_url="http://example.test")
client._capabilities = V1ServerCapabilities("http://example.test", ("flash",), ("zip",), ("file_id",))
with pytest.raises(V1ArtifactError) as error:
- asyncio.run(client.parse_file(source, tier="flash", page_range="bad"))
- assert error.value.code == "invalid_page_range"
+ asyncio.run(client.parse_file(source, tier="flash", page_range="999"))
+ assert error.value.code == "page_range_invalid"
def test_v1_client_parse_uses_api_parser_zip_contract(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
@@ -437,12 +438,12 @@ def test_v1_client_parse_uses_api_parser_zip_contract(monkeypatch: pytest.Monkey
("file_id",),
)
statuses: list[str] = []
- result = asyncio.run(client.parse_file(source, tier="standard", page_range="1~2", status_callback=statuses.append))
+ result = asyncio.run(client.parse_file(source, tier="standard", page_range="1-2", status_callback=statuses.append))
assert isinstance(result, ParseResult)
assert calls["include_images"] is True
assert calls["include_model_output"] is True
assert calls["tier"] == "standard"
- assert calls["page_range"] == "1~2"
+ assert calls["page_range"] == "1-2"
assert statuses[0] == "Preparing request..."
assert statuses[-1] == STATUS_DOWNLOADING_RESULT
@@ -625,7 +626,7 @@ def test_page_range_image_crops_follow_original_page_indices(tmp_path: Path) ->
ParseResult(middle_json=_middle_json(page_indices=(1, 2))),
source,
output_root=tmp_path / "output",
- page_range="2~3",
+ page_range="2-3",
)
images = sorted((artifacts.root / "images").glob("*.jpg"))
assert len(images) == 2
@@ -644,7 +645,7 @@ def test_persist_page_range_keeps_cropped_origin_page_order(tmp_path: Path) -> N
ParseResult(middle_json=_middle_json(with_image=False, page_indices=(1, 2))),
source,
output_root=tmp_path / "output",
- page_range="2~3",
+ page_range="2-3",
)
assert artifacts.page_indices == (1, 2)
assert artifacts.origin_pdf_path is not None
@@ -701,8 +702,8 @@ def test_render_download_rejects_state_outside_allowed_root(tmp_path: Path) -> N
def test_gradio_file_types_page_range_and_header_follow_new_contract() -> None:
"""验证完整扩展名、PDF-only 页码规则和复用后的 Header。"""
assert set(gradio_app._supported_file_types()) == {f".{extension}" for extension in PARSEABLE_EXTENSIONS}
- assert gradio_app._effective_page_range("report.PDF", " 1~3,-1 ") == "1~3,-1"
- assert gradio_app._effective_page_range("report.docx", "1~3") == ""
+ assert gradio_app._effective_page_range("report.PDF", " 1-3,r1 ") == "1-3,r1"
+ assert gradio_app._effective_page_range("report.docx", "1-3") == ""
header = gradio_app._render_header(gradio_major_version=6)
assert "mineru-gradio6-header" in header
assert "mineru-header-popover mineru-model-popover" in header
@@ -742,8 +743,60 @@ def test_build_gradio_app_exposes_three_tabs_and_download_menu(tmp_path: Path) -
assert sum(1 for dependency in app.config["dependencies"] if dependency.get("queue") is True) >= 7
-def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_path: Path) -> None:
- """验证转换事件透传 PDF page_range,并只在新结果完成后启用下载。"""
+ ("tiers", "default_position", "default_tier", "maximum"),
+ [
+ (("advanced", "flash", "standard", "basic"), 2, "standard", 3),
+ (("advanced", "standard", "basic"), 1, "standard", 2),
+ (("advanced", "flash"), 1, "advanced", 1),
+ (("basic", "flash"), 1, "basic", 1),
+ (("flash",), 0, "flash", 1),
+ (("advanced",), 0, "advanced", 1),
+ ],
+)
+def test_gradio_tier_slider_uses_available_tiers_and_preserves_selection(
+ tmp_path: Path, tiers: tuple[str, ...], default_position: int, default_tier: str, maximum: int
+) -> None:
+ """验证乱序、缺档及单档位下的原生滑块默认值与文件切换、清除行为。"""
+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))
+ demo = build_gradio_app(
+ V1ArtifactClient(api_url=capabilities.base_url), capabilities, output_root=tmp_path, enable_example=False
+ )
+ slider = next(block for block in demo.blocks.values() if block.__class__.__name__ == "Slider")
+ label = next(block for block in demo.blocks.values() if "mineru-tier-label" in (block.elem_classes or []))
+ assert (slider.minimum, slider.maximum, slider.step, slider.precision) == (0, maximum, 1, 0)
+ assert slider.value == default_position
+ assert slider.interactive is (len(tiers) > 1)
+ assert label.value == f"解析 tier:{default_tier}"
+ assert not any(block.__class__.__name__ == "Dropdown" for block in demo.blocks.values())
+ label_event = next(event for event in demo.config["dependencies"] if event["targets"] == [(slider._id, "input")])
+ assert label_event["backend_fn"] is False
+ assert label_event["queue"] is False
+ assert label_event["outputs"] == [label._id]
+ for fn in demo.fns.values():
+ if fn.name in {"update_file_preview", "reset_ui"}:
+ assert slider not in fn.outputs and label not in fn.outputs
+ if fn.name == "convert_handler":
+ assert fn.inputs[1] is slider
+ assert slider.api_info()["type"] == "integer"
+
+
+ ("tiers", "position", "expected_tier"),
+ [
+ (("advanced", "flash", "standard", "basic"), 0, "flash"),
+ (("advanced", "flash", "standard", "basic"), 1, "basic"),
+ (("advanced", "flash", "standard", "basic"), 2, "standard"),
+ (("advanced", "flash", "standard", "basic"), 3, "advanced"),
+ (("advanced", "standard", "basic"), 2, "advanced"),
+ (("advanced", "flash"), 1, "advanced"),
+ (("flash",), 0, "flash"),
+ ],
+)
+def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(
+ tmp_path: Path, tiers: tuple[str, ...], position: int, expected_tier: str
+) -> None:
+ """验证滑块位置映射与 PDF page_range 透传,并只在新结果完成后启用下载。"""
source = tmp_path / "demo.pdf"
source.write_bytes(_pdf_bytes())
@@ -770,9 +823,9 @@ def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_p
async def collect_updates(handler: Any) -> list[tuple[Any, ...]]:
"""收集 Gradio 异步生成器的全部增量输出。"""
- return [update async for update in handler(str(source), "flash", " 1 ")]
+ return [update async for update in handler(str(source), position, " 1 ")]
- capabilities = V1ServerCapabilities("http://127.0.0.1:1", ("flash",), ("zip",), ("file_id",))
+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))
client = FakeClient()
demo = build_gradio_app(
client, # type: ignore[arg-type]
@@ -783,13 +836,44 @@ def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_p
convert_handler = next(fn.fn for fn in demo.fns.values() if fn.name == "convert_handler")
updates = asyncio.run(collect_updates(convert_handler))
- assert client.calls == [(source.resolve(), "flash", "1")]
+ assert client.calls == [(source.resolve(), expected_tier, "1")]
assert len(updates[-1]) == 15
assert updates[-1][8] is not None
assert all(update["interactive"] is True and update["value"] is None for update in updates[-1][-6:])
assert all(update["interactive"] is False and update["value"] is None for update in updates[0][-6:])
+ ("tiers", "position"),
+ [
+ (("flash", "basic", "standard", "advanced"), -1),
+ (("flash", "basic", "standard", "advanced"), 4),
+ (("flash",), 1),
+ (("flash", "advanced"), 0.5),
+ (("flash", "advanced"), float("nan")),
+ (("flash", "advanced"), True),
+ ],
+)
+def test_gradio_conversion_rejects_invalid_tier_position(tmp_path: Path, tiers: tuple[str, ...], position: int | float) -> None:
+ """验证非法位置会清除结果且不会向解析服务提交请求,包括单档位的占位上界。"""
+ source = tmp_path / "demo.csv"
+ source.write_text("name,value\na,1\n", encoding="utf-8")
+ client = SimpleNamespace(parse_file=AsyncMock())
+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))
+ demo = build_gradio_app(client, capabilities, output_root=tmp_path, enable_example=False)
+ handler = next(fn.fn for fn in demo.fns.values() if fn.name == "convert_handler")
+
+ async def collect_updates() -> list[tuple[Any, ...]]:
+ """收集非法滑块位置对应的错误输出。"""
+ return [update async for update in handler(str(source), position, "")]
+
+ updates = asyncio.run(collect_updates())
+ assert "Failed: Invalid tier slider position" in updates[-1][0]
+ assert updates[-1][8] is None
+ assert all(item["interactive"] is False and item["value"] is None for item in updates[-1][-6:])
+ client.parse_file.assert_not_called()
+
+
def test_gradio_conversion_failure_clears_previous_downloads(tmp_path: Path) -> None:
"""验证解析失败会清空结果 State 并禁用所有旧下载按钮。"""
source = tmp_path / "demo.pdf"
@@ -804,7 +888,7 @@ def test_gradio_conversion_failure_clears_previous_downloads(tmp_path: Path) ->
async def final_update(handler: Any) -> tuple[Any, ...]:
"""返回 Gradio 异步生成器的最后一次更新。"""
- updates = [update async for update in handler(str(source), "flash", "")]
+ updates = [update async for update in handler(str(source), 0, "")]
return updates[-1]
capabilities = V1ServerCapabilities("http://127.0.0.1:1", ("flash",), ("zip",), ("file_id",))
diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.py
index c1c9f3fa..2c8d0227 100644
--- a/tests/unittest/test_parser_api_contract.py
+++ b/tests/unittest/test_parser_api_contract.py
@@ -447,10 +447,10 @@ def test_api_client_builds_file_page_range_without_options(tmp_path: Path) -> No
pdf.write_bytes(b"%PDF-1.7\n")
parser = MinerUApiParser(api_url="http://localhost:8000", tier="standard")
- payload = parser._build_payload({"type": "local", "path": str(pdf)}, "1,3~5")
+ payload = parser._build_payload({"type": "local", "path": str(pdf)}, "1,3-5")
assert payload["output_formats"] == ["middle_json"]
- assert payload["files"] == [{"source": {"type": "local", "path": str(pdf)}, "page_range": "1,3~5"}]
+ assert payload["files"] == [{"source": {"type": "local", "path": str(pdf)}, "page_range": "1,3-5"}]
assert "options" not in payload["files"][0]
diff --git a/tests/unittest/test_pdf_page_id.py b/tests/unittest/test_pdf_page_id.py
index 28d0d6c5..28a08417 100644
--- a/tests/unittest/test_pdf_page_id.py
+++ b/tests/unittest/test_pdf_page_id.py
@@ -1,26 +1,367 @@
from __future__ import annotations
+import asyncio
+import io
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
import pytest
+from fastapi.testclient import TestClient
+from pypdf import PdfReader
+from reportlab.pdfgen import canvas
+from typer.testing import CliRunner
+
+from mineru.cli.commands.parse import _validate_page_range_input
+from mineru.cli.main import app as cli_app
+from mineru.doclib.server import _normalize_content_page_range
+from mineru.doclib.services.config_svc import ConfigService
+from mineru.doclib.services.parse_svc import default_parse_range
+from mineru.errors import InvalidRequestError, MineruError
+from mineru.kit.gradio.app import _effective_page_range
+from mineru.kit.gradio.artifacts import persist_parse_result
+from mineru.kit.gradio.client import V1ArtifactClient
+from mineru.kit.main import app as kit_app
+from mineru.parser import MinerUParser, api_server
+from mineru.parser.api_client import MinerUApiParser
+from mineru.parser.page_range import (
+ count_pages_in_range,
+ expand_page_range,
+ format_page_range,
+ normalize_page_range_input,
+ parse_page_range,
+ parse_page_range_set,
+)
+
+VALID_RANGES = [
+ ("5", [5], "5"),
+ ("1-5", [1, 2, 3, 4, 5], "1-5"),
+ ("1-3,7,9-10", [1, 2, 3, 7, 9, 10], "1-3,7,9-10"),
+ ("3,1-3,2", [1, 2, 3], "1-3"),
+ ("all", list(range(1, 11)), "1-10"),
+ ("r1", [10], "10"),
+ ("r5-r1", [6, 7, 8, 9, 10], "6-10"),
+ ("3-r1", list(range(3, 11)), "3-10"),
+ (" 1 - 3 , r2 - r1 ", [1, 2, 3, 9, 10], "1-3,9-10"),
+ ("8-15", [8, 9, 10], "8-10"),
+ ("r20-r8", [1, 2, 3], "1-3"),
+ ("1,50", [1], "1"),
+ ("5-5", [5], "5"),
+]
+INVALID_RANGES = [
+ "1~5",
+ "-1",
+ "-5~-1",
+ "0",
+ "r0",
+ "5-",
+ "-5",
+ "1,,3",
+ ",1",
+ "1,",
+ "1,3",
+ "1:5",
+ "5-3",
+ "r1-r5",
+ "all,1",
+ "ALL",
+ "R1",
+ "r 1",
+ "01",
+ "+1",
+ "1",
+ "1--5",
+]
+
+
[email protected](("raw", "page_numbers", "canonical"), VALID_RANGES)
+def test_page_selection_contract_across_entrypoints(raw: str, page_numbers: list[int], canonical: str) -> None:
+ """同一矩阵覆盖共享解析、Doclib 内容读取、CLI 校验和 Gradio 输入。"""
+ _validate_page_range_input(raw)
+ assert parse_page_range(raw, 10) == [page - 1 for page in page_numbers]
+ assert expand_page_range(raw, 10) == canonical
+ assert _normalize_content_page_range(raw, None, {"page_count": 10}) == canonical
+ assert expand_page_range(_effective_page_range("demo.pdf", raw), 10) == canonical
+ assert parse_page_range_set(canonical) == set(page_numbers)
+ assert count_pages_in_range(canonical) == len(page_numbers)
+ assert format_page_range(reversed(page_numbers)) == canonical
+
+
[email protected]("raw", INVALID_RANGES)
+def test_invalid_and_retired_syntax_is_rejected_everywhere(raw: str) -> None:
+ """旧语法与非法端点必须在所有校验入口返回稳定页码错误。"""
+ for action in (
+ lambda: normalize_page_range_input(raw),
+ lambda: parse_page_range(raw, 10),
+ lambda: expand_page_range(raw, 10),
+ lambda: _normalize_content_page_range(raw, None, {"page_count": 10}),
+ lambda: _effective_page_range("demo.pdf", raw),
+ lambda: _validate_page_range_input(raw),
+ ):
+ with pytest.raises(MineruError) as error:
+ action()
+ assert error.value.code == "page_range_invalid"
+ assert error.value.type == "invalid_request_error"
+
+
[email protected]("raw", ["20", "11-20", "r20-r11", "r11", "8-r5", "1,8-r5"])
+def test_resolution_rejects_empty_selection_or_reversed_relative_range(raw: str) -> None:
+ """依赖总页数的错误在求值时发生;混合有效选项不能掩盖倒序。"""
+ normalize_page_range_input(raw)
+ with pytest.raises(InvalidRequestError) as error:
+ parse_page_range(raw, 10)
+ assert error.value.code == "page_range_invalid"
+
+
[email protected]("raw", [None, "", " \t\n"])
+def test_unspecified_range_preserves_entrypoint_default(raw: str | None) -> None:
+ """空值统一为未指定,但 Doclib 与直接 Parser 保留各自默认窗口。"""
+ assert normalize_page_range_input(raw) == ""
+ assert parse_page_range(raw or "", 15) == list(range(15))
+ assert _normalize_content_page_range(raw, None, {"page_count": 15}) == "1-10"
+ assert default_parse_range(1) == "1"
+ assert _normalize_content_page_range("all", None, {"page_count": 15}) == "1-15"
+
+
+def test_large_ranges_are_clipped_before_expansion() -> None:
+ """验证巨大端点只处理实际存在的页面,并以区间计算规范化与统计。"""
+ assert parse_page_range("1-999999999999999999", 3) == [0, 1, 2]
+ assert expand_page_range("r999999999999999999-r1", 3) == "1-3"
+ assert normalize_page_range_input("2,1-999999999999999999") == "1-999999999999999999"
+ assert count_pages_in_range("1-999999999999999999,2") == 999999999999999999
+ assert parse_page_range_set("") == set()
+ assert format_page_range([]) == ""
+ assert count_pages_in_range("") == 0
+ for raw in ["all", "r1"]:
+ with pytest.raises(InvalidRequestError):
+ parse_page_range_set(raw)
+
+
[email protected]("raw", ["1~5", "-1", "r1-r5"])
+def test_remote_clients_validate_before_network(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, raw: str) -> None:
+ """同步、异步 API 与 Gradio 客户端在上传或能力发现前拒绝非法表达式。"""
+ source = tmp_path / "input.pdf"
+ source.write_bytes(b"%PDF-1.7")
+ parser = MinerUApiParser(api_url="http://example.test", tier="flash")
+ build_source = Mock(side_effect=AssertionError("must not upload"))
+ async_build_source = AsyncMock(side_effect=AssertionError("must not upload"))
+ monkeypatch.setattr(parser, "_build_source", build_source)
+ monkeypatch.setattr(parser, "_async_build_source", async_build_source)
+ with pytest.raises(InvalidRequestError):
+ parser.parse(source, page_range=raw)
+ with pytest.raises(InvalidRequestError):
+ asyncio.run(parser.parse_async(source, page_range=raw))
+ client = V1ArtifactClient(api_url="http://example.test")
+ discover = AsyncMock(side_effect=AssertionError("must not discover"))
+ monkeypatch.setattr(client, "discover", discover)
+ with pytest.raises(InvalidRequestError):
+ asyncio.run(client.parse_file(source, tier="flash", page_range=raw))
+ build_source.assert_not_called()
+ async_build_source.assert_not_called()
+ discover.assert_not_called()
+
+
+def test_api_rejects_bad_ranges_before_creating_jobs(tmp_path: Path) -> None:
+ """直接 HTTP 请求校验共享语法,错误定位到批量请求的具体文件。"""
+ app = api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash", allow_local_source=True)
+ with TestClient(app) as client:
+ for raw in INVALID_RANGES:
+ response = client.post(
+ "/v1/parse/jobs",
+ json={
+ "tier": "flash",
+ "files": [
+ {"source": {"type": "local", "path": "/unused.pdf"}},
+ {"source": {"type": "local", "path": "/unused.pdf"}, "page_range": raw},
+ ],
+ },
+ )
+ assert response.status_code == 400
+ error = response.json()["error"]
+ assert error["code"] == "page_range_invalid"
+ assert error["param"] == "files.1.page_range"
+ schema = client.get("/openapi.json").json()
+ assert "r1" in schema["components"]["schemas"]["JobFileEntry"]["properties"]["page_range"]["description"]
+
+
+def test_cli_rejects_old_syntax_and_kit_preserves_range_error(tmp_path: Path) -> None:
+ """两个 CLI 均在执行解析前拒绝旧表达式,主 CLI 返回机器可读错误码。"""
+ source = tmp_path / "input.pdf"
+ source.write_bytes(b"%PDF-1.7")
+ runner = CliRunner()
+ for raw in ["1~5", "-1"]:
+ result = runner.invoke(cli_app, ["parse", str(source), "--pages", raw, "--json"])
+ assert result.exit_code == 1
+ assert '"page_range_invalid"' in result.output
+ result = runner.invoke(kit_app, ["parse", str(source), "--pages", raw, "-o", str(tmp_path / "out.md")])
+ assert result.exit_code == 1
+ assert "Invalid page range" in result.output
+
+
+def test_parsing_rules_validate_without_a_document() -> None:
+ """规则保存前校验表达式,允许暂存 rN/all 并拒绝旧语法。"""
+ database = SimpleNamespace(execute_insert=AsyncMock(return_value=7))
+ service = ConfigService(database)
+ for raw, expected in [(" r3 - r1 ", "r3-r1"), ("all", "all"), (" ", None), ("3,1-3", "1-3")]:
+ asyncio.run(service.add_rule("pdfs", "parsing_rule", "*.pdf", page_range=raw))
+ assert database.execute_insert.call_args.args[1][3] == expected
+ database.execute_insert.reset_mock()
+ with pytest.raises(InvalidRequestError):
+ asyncio.run(service.add_rule("pdfs", "parsing_rule", "*.pdf", page_range="1~5"))
+ database.execute_insert.assert_not_called()
+
+
+def _numbered_pdf(path: Path, page_count: int = 5) -> None:
+ """创建每页带不同正文的真实 PDF,供裁剪和原始页号验证。"""
+ document = canvas.Canvas(str(path), pagesize=(240, 320))
+ for page_no in range(1, page_count + 1):
+ document.drawString(30, 250, f"Source page {page_no}")
+ document.showPage()
+ document.save()
+
+
+def test_real_pdf_selection_preserves_original_indices_and_artifact_order(tmp_path: Path) -> None:
+ """实测非连续选页与末页组合,同时核对解析页号、原始 PDF 和 layout PDF。"""
+ source = tmp_path / "numbered.pdf"
+ _numbered_pdf(source)
+ parser = MinerUParser(tier="flash")
+ result = parser.parse(source, page_range="r1,3,1,3")
+ assert [page.page_idx for page in result.pages] == [0, 2, 4]
+ assert not result.middle_json.is_full_document
+ assert "Source page 3" in result.markdown()
+ assert "Source page 2" not in result.markdown()
+ artifacts = persist_parse_result(result, source, output_root=tmp_path / "review", page_range="r1,3,1,3")
+ assert artifacts.page_indices == (0, 2, 4)
+ assert artifacts.origin_pdf_path is not None and artifacts.layout_pdf_path is not None
+ reader = PdfReader(str(artifacts.origin_pdf_path))
+ assert [page.extract_text().strip() for page in reader.pages] == ["Source page 1", "Source page 3", "Source page 5"]
+ assert len(PdfReader(str(artifacts.layout_pdf_path)).pages) == 3
+ prepared = parser._prepare_input(source, "r1")
+ assert prepared.retained_page_indices == [4]
+ assert PdfReader(io.BytesIO(prepared.file_bytes)).pages[0].extract_text().strip() == "Source page 5"
+
+
+def test_async_job_resolves_relative_ranges_and_reports_file_errors(tmp_path: Path) -> None:
+ """后台任务完成后返回规范实际范围,依赖总页数的错误保留文件级错误码。"""
+ source = tmp_path / "numbered.pdf"
+ _numbered_pdf(source)
+ store = api_server.FileStore(tmp_path / "files")
+ request = api_server.CreateJobRequest.model_validate(
+ {
+ "tier": "flash",
+ "output_formats": ["middle_json"],
+ "files": [
+ {"source": {"type": "local", "path": str(source)}, "page_range": "1,r2-r1"},
+ {"source": {"type": "local", "path": str(source)}, "page_range": "20"},
+ ],
+ }
+ )
+ record = api_server.JobStore().create(request, store)
+ asyncio.run(api_server._run_job(record, request, store, ocr_mode="auto", image_analysis=True, allow_local_source=True))
+ assert record.status == "partial"
+ assert record.files[0].page_range == "1,4-5"
+ assert record.files[0].status == "completed"
+ assert record.files[1].error.code == "page_range_invalid"
+ assert record.files[1].error.param == "page_range"
+
-from mineru.parser.page_range import parse_page_range
+def test_doclib_client_validates_requests_before_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Doclib SDK 的解析、查询、导出和规则请求复用校验且不修改调用方模型。"""
+ from mineru.doclib.client import DoclibClient
+ from mineru.doclib.types import DocContentExportRequest, ParseRequest, ParsingRuleRequest
+ client = DoclibClient(base_url="http://example.test")
+ transport = Mock()
+ monkeypatch.setattr(client, "_request_model", transport)
+ actions = (
+ lambda: client.ensure_parse(ParseRequest(path="demo.pdf", page_range="1~5")),
+ lambda: client.list_parses(page_range="1~5"),
+ lambda: client.get_doc_content("a" * 64, tier="flash", page_range="1~5"),
+ lambda: client.export_doc_content(
+ "a" * 64, DocContentExportRequest(tier="flash", output="out.md", format="markdown", page_range="1~5")
+ ),
+ lambda: client.add_parsing_rule(ParsingRuleRequest(pattern="*.pdf", page_range="1~5")),
+ )
+ for action in actions:
+ with pytest.raises(InvalidRequestError):
+ action()
+ transport.assert_not_called()
+ request = ParseRequest(path="demo.pdf", page_range=" 3,1-3 ")
+ client.ensure_parse(request)
+ assert transport.call_args.kwargs["body"].page_range == "1-3"
+ assert request.page_range == " 3,1-3 "
+ client.close()
-def test_parse_page_range_empty_means_all_pages() -> None:
- assert parse_page_range("", 5) == [0, 1, 2, 3, 4]
+def test_kit_preserves_remote_page_range_error(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """远端返回的页码错误不能在 mineru-kit 中被泛化为 parse_failed。"""
+ from mineru.kit.commands import parse as kit_parse
+ from mineru.parser.api_client import _V1APIError
[email protected]("raw", ["6", "6~8", "0", "-20~-10"])
-def test_parse_page_range_explicit_out_of_range_does_not_fallback_to_all_pages(raw: str) -> None:
- assert parse_page_range(raw, 5) == []
+ source = tmp_path / "input.pdf"
+ source.write_bytes(b"%PDF-1.7")
+ parser = SimpleNamespace(parse=Mock(side_effect=_V1APIError("page_range_invalid", "empty selection", "page_range")))
+ monkeypatch.setattr(kit_parse, "MinerUApiParser", Mock(return_value=parser))
+ fail = Mock(side_effect=RuntimeError("captured error"))
+ monkeypatch.setattr(kit_parse, "exit_with_message", fail)
+ result = CliRunner().invoke(
+ kit_app,
+ [
+ "parse",
+ str(source),
+ "--remote-url",
+ "http://example.test",
+ "--pages",
+ "r1",
+ "-o",
+ str(tmp_path / "out.md"),
+ ],
+ )
+ assert result.exit_code != 0
+ assert fail.call_args.args[0] == "page_range_invalid"
+ assert fail.call_args.args[2] == "page_range"
-def test_parse_page_range_explicit_partial_out_of_range_keeps_valid_intersection() -> None:
- assert parse_page_range("3~8", 5) == [2, 3, 4]
+def test_doclib_relative_selection_coverage_and_export(tmp_path: Path) -> None:
+ """真实 SQLite 缓存的覆盖查询与内容导出必须先按文档总页数求值 rN/all。"""
+ import json
+ from mineru.doclib.core.db import DatabaseManager
+ from mineru.doclib.server import DoclibServer
+ from mineru.doclib.services.parse_svc import parse_batch_json_path
-def test_parse_page_range_expands_deduplicates_and_sorts_available_pages() -> None:
- assert parse_page_range("1~10,3,4~5", 5) == [0, 1, 2, 3, 4]
+ source = tmp_path / "numbered.pdf"
+ _numbered_pdf(source)
+ result = MinerUParser(tier="flash").parse(source, page_range="1-3,r1")
+ sha256 = "a" * 64
+ cache = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-3,5", 1000))
+ cache.parent.mkdir(parents=True)
+ cache.write_text(json.dumps(result.to_dict()), encoding="utf-8")
+ async def verify() -> None:
+ """构造实际元数据与缓存记录,验证公开服务读取结果。"""
+ db = DatabaseManager(str(tmp_path / "doclib.db"))
+ await db.initialize()
+ try:
+ await db.execute(
+ "INSERT INTO docs (sha256, short_id, size_bytes, file_type, page_count, first_seen_at, updated_at) "
+ "VALUES (?, ?, ?, ?, ?, ?, ?)",
+ (sha256, "aaaaaaa", source.stat().st_size, "pdf", 5, 1000, 1000),
+ )
+ await db.execute(
+ "INSERT INTO parses (sha256, tier, page_range, status, privacy, done_at, created_at, updated_at) "
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+ (sha256, "flash", "1-3,5", "done", "local", 1000, 1000, 1000),
+ )
+ server = DoclibServer(SimpleNamespace(db=db, data_dir=str(tmp_path)))
+ listing = await server.list_parses(doc_ref="aaaaaaa", tier="flash", page_range="r3-r1")
+ assert listing.coverage.done_page_range == "3,5"
+ assert listing.coverage.missing_page_range == "4"
+ text = await server._render_doc_content(sha256, tier="flash", page_range="r1", format="markdown", no_marker=True)
+ assert "Source page 5" in text and "Source page 3" not in text
+ text = await server._render_doc_content(sha256, tier="flash", page_range="all", format="markdown", no_marker=True)
+ assert "Source page 1" in text and "Source page 5" in text
+ finally:
+ await db.close()
-def test_parse_page_range_negative_one_is_last_page() -> None:
- assert parse_page_range("-2~-1", 5) == [3, 4]
+ asyncio.run(verify())