feat: prepare v0.3.0 library delivery
This commit is contained in:
@@ -3,8 +3,9 @@
|
||||
`mdpolish` 是实验室共用的、项目无关的 Python Markdown 修改库。它提供函数式 `Modifier`、精确文本编辑执行器、
|
||||
有序 `Pipeline`、正则修改器工厂，以及少量可以用合成样例完整说明的通用修改器。
|
||||
|
||||
当前版本是 `0.2.0`。库只处理内存中的 Markdown 字符串，不读取或写入文件，不提供默认流水线，也不包含任何项目的
|
||||
规则集合、数据清单、实验脚本或评审工具。
|
||||
当前源码包版本是 `0.3.0`。库只处理内存中的 Markdown 字符串，不读取或写入文件，不提供默认流水线，也不包含任何
|
||||
项目的规则集合、数据清单、实验脚本或评审工具。`v0.3.0` tag 和 GitHub Release 尚未创建，因此当前源码是交付候选，
|
||||
不是已经发布的版本。
|
||||
|
||||
## 当前能力
|
||||
|
||||
@@ -27,13 +28,23 @@
|
||||
|
||||
## 安装
|
||||
|
||||
项目仍在仓库内开发，使用项目可以从本地路径安装：
|
||||
正式版本只计划通过 GitHub tag 和 GitHub Release 交付，不发布到 PyPI 或其他 Python 包索引。`v0.3.0` 发布后，
|
||||
使用项目可以固定不可移动的 tag：
|
||||
|
||||
```bash
|
||||
python -m pip install /path/to/mdpolish
|
||||
python -m pip install 'mdpolish @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
|
||||
python -m pip install 'mdpolish[lexical] @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
|
||||
python -m pip install 'mdpolish[frequency] @ git+https://github.com/Bepr4/mdpolish.git@v0.3.0'
|
||||
```
|
||||
|
||||
开发环境：
|
||||
也可以安装同一 GitHub Release 附带的 wheel；下面的 URL 只有在 Release 实际创建后才存在：
|
||||
|
||||
```bash
|
||||
python -m pip install 'mdpolish[lexical] @ https://github.com/Bepr4/mdpolish/releases/download/v0.3.0/mdpolish-0.3.0-py3-none-any.whl'
|
||||
```
|
||||
|
||||
Release 页面同时提供 wheel 的 SHA-256 校验值。仓库或 Release 如果是私有的，调用方需要自行配置 GitHub 访问权限；
|
||||
库不会保存凭据。开发环境仍从本地工作树安装：
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
@@ -87,6 +98,52 @@ if result.status is not RunStatus.SUCCESS:
|
||||
assert result.output_markdown == "an example text"
|
||||
```
|
||||
|
||||
## 自动英文断词
|
||||
|
||||
普通英文断词不需要逐词维护映射。调用方安装 `lexical` extra 后，可以明确选择 `pyspellchecker` 的本地词典，
|
||||
并用 Pyphen 排除不合法的断词位置：
|
||||
|
||||
```python
|
||||
from mdpolish import Pipeline, RunStatus
|
||||
from mdpolish.modifiers import mapped_line_join
|
||||
from mdpolish.modifiers.mapped_line_join import (
|
||||
LexicalCandidateForm,
|
||||
LexicalLineJoinRule,
|
||||
LexiconBackend,
|
||||
)
|
||||
|
||||
join_english_wraps = mapped_line_join(
|
||||
(
|
||||
LexicalLineJoinRule(
|
||||
rule_id="english.dehyphenate",
|
||||
left_pattern=r"[A-Za-z]+",
|
||||
right_pattern=r"[a-z]+",
|
||||
separator="-",
|
||||
backend=LexiconBackend.SPELLCHECKER,
|
||||
language="en",
|
||||
candidate_forms=(
|
||||
LexicalCandidateForm.JOINED,
|
||||
LexicalCandidateForm.HYPHENATED,
|
||||
),
|
||||
minimum_score=1.0,
|
||||
minimum_score_margin=0.5,
|
||||
hyphenation_language="en_US",
|
||||
case_sensitive=False,
|
||||
),
|
||||
)
|
||||
)
|
||||
|
||||
result = Pipeline((join_english_wraps,)).transform("an exam-\nple")
|
||||
if result.status is not RunStatus.SUCCESS:
|
||||
raise RuntimeError(f"cleaning did not succeed: {result.status}")
|
||||
|
||||
assert result.output_markdown == "an example"
|
||||
```
|
||||
|
||||
`pyspellchecker` 的内置语言词典不支持大小写敏感查询，因此这个 backend 要求调用方明确写出
|
||||
`case_sensitive=False`；库不会替调用方改变该开关或切换 backend。上面的分数和 margin 只用于演示完整配置，
|
||||
不是适合所有项目的生产阈值。`JOINED` 与源 `HYPHENATED` 会共同参与候选选择；词典不能确认唯一结果时保持原文。
|
||||
|
||||
库不会保存 `output_markdown`。调用项目应先检查状态，再自行决定写入位置：
|
||||
|
||||
```python
|
||||
@@ -158,7 +215,9 @@ remove_marker = Modifier(
|
||||
中间最多一个同风格空行，并可在一次提议内完成多行链式合并。保守词法扫描只正向识别段落、ATX 标题 continuation、
|
||||
列表 continuation 和同深度引用；代码块、GFM pipe table、raw HTML table、混合候选行尾及无法确认的容器保持原文。
|
||||
完整公共模型、选择流程和限制见
|
||||
[`0009-generalized-mapped-line-join.md`](research-wiki/design/0009-generalized-mapped-line-join.md)。
|
||||
[`0009-generalized-mapped-line-join.md`](research-wiki/design/0009-generalized-mapped-line-join.md)，真实 backend 验收、
|
||||
版本身份和 GitHub 发布边界见
|
||||
[`0010-first-cross-project-library-delivery.md`](research-wiki/design/0010-first-cross-project-library-delivery.md)。
|
||||
|
||||
`html_table_entity_unescape()` 只在严格完整的 `<td>` / `<th>` 文本中处理 `&lt;`、`&gt;` 和
|
||||
`&amp;`。`html_table_layout()` 只调整严格单行表格的外层行布局，并保留标签、属性和单元格内容。
|
||||
@@ -216,8 +275,13 @@ git diff --check
|
||||
git status --short
|
||||
```
|
||||
|
||||
上述检查已于 2026-08-26 在 Python 3.13.11 环境实际运行：Ruff 通过，mypy 检查 21 个源码和测试文件无问题，
|
||||
pytest 共 168 项通过、2 项因本环境未安装可选词典 backend 而跳过，`mdpolish-0.2.0-py3-none-any.whl` 构建成功。
|
||||
wheel 内容已单独检查，只包含通用 Python 包、类型标记和包元数据，不包含项目规则、实验脚本、评审器或 Node.js 文件。
|
||||
上述检查已于 2026-08-27 实际运行。Python 3.13.11 核心开发环境中 Ruff 和 mypy 通过，pytest 为
|
||||
`170 passed, 3 skipped`；三个 skip 是该环境没有安装的真实 optional backend 路径，不计入发布验收。
|
||||
|
||||
`pyproject.toml` 声明的 Python 3.11 及以上为支持范围；本次结果不表示已经在每个受支持版本上完成兼容性验证。
|
||||
从 `mdpolish-0.3.0-py3-none-any.whl` 安装全部 extras 后，Python 3.11.16 和 Python 3.13.11 环境分别得到
|
||||
`173 passed`，没有 skip。仓库外消费者 smoke test 已覆盖核心精确/正则规则、`pyspellchecker + Pyphen` 和
|
||||
`wordfreq` 的最终输出与版本审计。wheel 共 16 个文件，只包含通用 Python 包、类型标记和包元数据；不包含 tests、
|
||||
Wiki、真实数据或项目规则。当前候选 wheel 的 SHA-256 是
|
||||
`a510ae1755c281f7b40262e242441882f3ccbc3fbc2174c6f5db3e8a8ae85060`。
|
||||
|
||||
上述结果证明当前候选可安装并按合成契约运行，不代表任意词典阈值已经在真实业务语料上达到生产准确率。
|
||||
|
||||
Reference in New Issue
Block a user