iomgaa/mdpolish
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 公开精确物理行范围接口

Browse Source
This commit is contained in:
Bepr4
2026-08-28 15:00:56 +08:00
parent 8b689eebe1
commit 61b7ea7534
9 changed files with 466 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+38 -16
View File
@@ -3,8 +3,8 @@
`mdpolish` 是实验室共用的、项目无关的 Python Markdown 修改库。它提供函数式 `Modifier`、精确文本编辑执行器、
有序 `Pipeline`、正则修改器工厂，以及少量可以用合成样例完整说明的通用修改器。
当前发布版本是 [`v0.4.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.4.0)，当前源码树的下一候选版本是
`0.5.0`。库只处理内存中的 Markdown 字符串，不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、
当前发布版本是 [`v0.6.0`](https://github.com/Bepr4/mdpolish/releases/tag/v0.6.0)。库只处理内存中的 Markdown 字符串，
不读取或写入文件，不提供默认流水线，也不包含任何项目的规则集合、
数据清单、实验脚本或评审界面。
## 当前能力
@@ -18,6 +18,7 @@
| `render_markdown_report()` | 把评审视图编排成完整 Markdown 源码报告字符串 | 只返回内存字符串，不创建文件或业务页面 |
| `review_document_to_dict()` | 按 schema `1.0` 把评审视图投影成普通 JSON 基本值 | 单向投影，不反序列化或重新应用修改 |
| `render_json_report()` | 复用正式 dict 投影生成确定的内存 JSON 字符串 | 不创建文件；默认摘要不等于公开安全日志 |
| `mdpolish.text_ranges` | 返回 CR/LF/CRLF 物理行的精确不可变原文范围 | 不解析 Markdown 块，不自动执行或修改文本 |
| `regex_replace()` | 把非空正则匹配转换为精确编辑 | 不提供规则注册表、配置加载或默认模式 |
| `mapped_line_join()` | 用精确、正则或可选本地词典规则合并跨行片段 | 无默认规则；代码、表格、未知结构和歧义失败关闭 |
| HTML 表格修改器 | 处理严格表格子集的实体和单行布局 | 不是完整 HTML parser，也不是 HTML→GFM 转换器 |
@@ -36,20 +37,19 @@
不可移动的 tag：
```bash
python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.4.0'
python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.6.0'
python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.6.0'
python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.6.0'
```
也可以安装同一 GitHub Release 附带的 wheel：
```bash
python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.4.0/mdpolish-0.4.0-py3-none-any.whl'
python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.6.0/mdpolish-0.6.0-py3-none-any.whl'
```
Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 GitHub 访问权限；
库不会保存凭据。以上命令当前安装的是已发布的 `v0.4.0`，不包含本源码树尚未发布的 `0.5.0` 机器投影。开发环境仍从
本地工作树安装：
库不会保存凭据。开发环境仍从本地工作树安装：
```bash
python -m venv .venv
@@ -212,6 +212,26 @@ Markdown reporter 会包含完整输入、当前全文、统一 diff 以及实
dict 和 JSON 都是单向派生视图，不用于恢复 `ReviewDocument` 或重新应用修改。完整 schema、坐标、哈希和兼容口径见
[`review-projection-schema-v1.md`](research-wiki/reference/review-projection-schema-v1.md)。
## 扫描精确物理行
项目 Modifier 如果需要识别独占行、检查相邻行或连同行尾删除一行，可以按原文 code point 范围扫描：
```python
from mdpolish.text_ranges import physical_lines
source = "first\r\n\r\nlast"
lines = physical_lines(source)
assert lines[0].content(source) == "first"
assert lines[0].line_ending(source) == "\r\n"
assert lines[1].is_empty
assert source[lines[2].content_start : lines[2].full_end] == "last"
```
扫描只识别 LF、CR 和 CRLF，不规范化原文，也不判断段落、标题、列表、引用、代码或表格。它不会成为 Pipeline 的全局预处理；
只有显式调用它的 Modifier 才会扫描当前阶段快照。精确空文档、尾换行、offset 和失败关闭口径见
[`physical-line-ranges.md`](research-wiki/reference/physical-line-ranges.md)。
## 编写项目自己的修改器
复杂规则使用普通函数返回精确候选修改，不需要继承库基类：
@@ -288,6 +308,7 @@ src/mdpolish/
├── pipeline.py # 有序执行与最终稳定性复查
├── review.py # 可信评审视图、机器投影及内存 JSON/Markdown reporter
├── regex.py # 正则修改器工厂
├── text_ranges.py # 公共精确物理行范围
└── modifiers/ # 少量项目无关的通用修改器
tests/ # 只使用虚构文本的核心与通用修改器测试
research-wiki/
@@ -312,8 +333,9 @@ research-wiki/
[`0011-generic-review-projection-and-reporting.md`](research-wiki/design/0011-generic-review-projection-and-reporting.md)，当前机制见
[`review-projection.md`](research-wiki/explanation/review-projection.md)。正式机器投影的批准边界见
[`0012-review-document-machine-projection.md`](research-wiki/design/0012-review-document-machine-projection.md)，schema `1.0` 的稳定
查询口径见 [`review-projection-schema-v1.md`](research-wiki/reference/review-projection-schema-v1.md)。旧 design 只保存历史
决策，不代表当前交付能力。
查询口径见 [`review-projection-schema-v1.md`](research-wiki/reference/review-projection-schema-v1.md)。精确物理行公共接口的边界见
[`0013-public-physical-line-ranges.md`](research-wiki/design/0013-public-physical-line-ranges.md)，稳定查询口径见
[`physical-line-ranges.md`](research-wiki/reference/physical-line-ranges.md)。旧 design 只保存历史决策，不代表当前交付能力。
## 当前可用检查
@@ -344,10 +366,10 @@ Python 标准库。Release wheel 的 SHA-256 是
上述结果证明当前版本可安装并按合成契约运行，不代表任意词典阈值已经在真实业务语料上达到生产准确率。
`0.5.0` 候选于 2026-08-28 在 Python 3.13.11 开发环境中实际得到：mypy 通过，pytest 为
`228 passed, 3 skipped`；三个 skip 仍是没有安装的 optional backend。除工作区已有的 `src/mdpolish/regex.py` 中文注释
改动外，Ruff 全部通过；未排除该文件的全仓 Ruff 因其中 30 个 `RUF002` / `RUF003` 失败，本轮没有擅自修改该用户改动。
`v0.6.0` 于 2026-08-28 在 Python 3.13.11 开发环境中实际得到：Ruff 和 mypy 通过，pytest 为
`290 passed, 3 skipped`；三个 skip 仍是没有安装的 optional backend。
候选 `mdpolish-0.5.0-py3-none-any.whl` 构建成功，共 17 个文件，包含更新后的 `review.py` 和 `py.typed`，不包含 tests、Wiki、
报告或真实数据；在仓库外全新虚拟环境中无依赖安装后，dict 投影与 JSON reporter smoke test 通过。该临时 wheel 不是 Release
资产，其哈希不构成发布身份；完成全仓 Ruff、提交、合并、tag 和 Release 仍需要分别确认。
Release wheel `mdpolish-0.6.0-py3-none-any.whl` 共 17 个文件，包含 `text_ranges.py`、`review.py` 和 `py.typed`，不包含
`_text_ranges.py`、tests、Wiki、报告或真实数据；在仓库外全新虚拟环境中无依赖安装后，版本、公共导入、精确混合行尾范围、
行尾集合、空行判断和 wheel 清单 smoke test 通过。Release wheel 的 SHA-256 是
`695502b1a443d4e98dbf63e8bdcee59452baea2185cb7e1e13160127f70c920f`。