fix(data): 校验早于副作用,补空行;经验写入 pitfalls

save_table 的两处收尾(用户授权代改):

- 后缀校验原先藏在 if/else 分支的 else 里,排在 path.parent.mkdir(...) 之后,
  传 sub/x.txt 会先把 sub\ 建出来再抛 ValueError。改成守卫子句,集中在 mkdir 之前,
  校验段结束后才产生副作用;此时 else 分支自然消失,用回 if/else 两路分派
- __all__ 与下一个 def 之间补回第二个空行(PEP 8 / E302)

测试:
- 新增 test_save_table_validates_before_touching_disk,
  断言参数非法时 tmp_path 下一个条目都不留(ValueError 与 TypeError 两条路径)
- 40 passed / 44 skipped,两套环境一致;ruff All checks passed

文档:
- docs/dev/personal-pitfalls.md 追加条目 5(参数校验排在副作用之后)
  与条目 6(把 lint 的"没报错"当成"没问题"),索引表同步加行
- STATUS:io.py 收尾,L0 第 3 项完成;测试计数 40
- CHANGELOG:Fixed 段补两条
This commit is contained in:
guzhujushi committed 2026-10-01 23:26:47 +08:00
1 parent 19f4a15107
commit 6758e81c9d
5 files changed
+61 -9

No files matched your search

+8 -6
View File
@@ -85,7 +85,9 @@
utf-8 → utf-8-sig → gbk → gb18030,显式传 `encoding=` 时不再探测
- `na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`
- 不支持的扩展名抛 `ValueError`;文件不存在抛带路径的 `FileNotFoundError`
- 测试:`tests/test_data.py` 由 1 条(且被模块级 skip 掉)扩到 **8 条**
- `save_table` 的校验顺序已修正:后缀判断提到 `mkdir` 之前
(此前传 `.txt` 会先留下一个空目录再抛错)
- 测试:`tests/test_data.py` 由 1 条(且被模块级 skip 掉)扩到 **9 条**
- docstring 的 `Parameters` / `Raises` 已按 §4.7 补齐(Codex 代写,用户授权)——
numpydoc 格式,对齐参考实现 `core/random.py` 的 `get_rng`
- [ ] 剩余 9 项(10 个函数):`clean_missing`
@@ -96,7 +98,7 @@
| 检查 | venv | conda `mcm-toolkit` |
|---|---|---|
| `pytest` | **39 passed, 44 skipped** | **39 passed, 44 skipped** |
| `pytest` | **40 passed, 44 skipped** | **40 passed, 44 skipped** |
| `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
| `ruff check` | All checks passed | All checks passed |
| `scripts/doctor.ps1` | 跑通 | — |
@@ -105,7 +107,7 @@
- base 亦已复核:numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6(与两套环境一致)
- skip 的都是等实现的算法行为测试;通过的 39 条 = 20 条公开 API 契约测试
(`tests/test_api_surface.py`)+ 11 条 `core` 行为测试(`tests/test_core.py`)
+ 8 条 `data` 行为测试(`tests/test_data.py`)
+ 9 条 `data` 行为测试(`tests/test_data.py`)
- 三个 `.ps1` 通过 PowerShell AST 语法解析
### ⚠️ 需要注意 / 遗留
@@ -162,9 +164,9 @@
## 下一步
1. **`data/io.py` 还剩一处**:`isinstance(df, pd.DataFrame)` 已经挪到 `mkdir` 前面了,
但**后缀校验还留在 `else` 分支里**,仍在 `mkdir` 之后。传 `sub/x.txt` 依旧会先建出
`sub/` 再抛 `ValueError`(实测确认)。把后缀判断也提到 `mkdir` 前面即可。
1. ~~`save_table` 校验顺序~~ **已修**:后缀判断提到 `mkdir` 前面,并补了回归测试
`test_save_table_validates_before_touching_disk`(断言参数非法时 `tmp_path` 下一个条目都不留)。
`io.py` 至此收尾,L0 的第 3 项完成。
2. 继续 L0,**下一个:`data/clean.py` 的 `clean_missing`**(L0 / A 档,直接能写)。
同文件的 `detect_outliers` 是 **S 档**,要先按 `docs/dev/function-card-template.md`
把函数卡片写出来再动手。