guzhujushi
6758e81c9d
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 段补两条
63 lines
4.3 KiB
Markdown
63 lines
4.3 KiB
Markdown
# 更新日志
|
||
|
||
格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
|
||
版本号参考 [语义化版本](https://semver.org/lang/zh-CN/)。
|
||
|
||
## [Unreleased]
|
||
|
||
### Added
|
||
- 仓库骨架：`src/mcm_toolkit/` 7 个包（core / data / stats / models / solve / decision / viz）
|
||
- 顶层 `__init__.py` 只导出 7 个子包 + 8 个快捷函数，`__all__` 即公开 API 清单
|
||
- `core.Result`：唯一的结果对象（替代原建议里的 5 个 Result 类）
|
||
- `docs/01-suggestion-review.md`：对 ChatGPT 建库建议的审查与精简（14 包 → 7 包，~250 函数 → ~40）
|
||
- `docs/02-architecture.md`：包边界、`Result` / RNG / `fit-predict-score` 协议、依赖分层
|
||
- `docs/03-roadmap.md`：L0/L1/L2 分级 + **永久不做清单**
|
||
- `docs/04-environment.md`：conda / venv 配置与三个已踩的坑
|
||
- `docs/dev/function-card-template.md`：S 档算法的函数卡片模板
|
||
- `.venv`（基于 Anaconda base，`--system-site-packages`）+ 可编辑安装 —— 10.5 MB，离线可用
|
||
- conda 环境 `mcm-toolkit`（`D:\anaconda\envs\mcm-toolkit`）—— Python 3.13.15，含 SALib / pymoo / pyright
|
||
- `scripts/setup-conda.ps1` / `scripts/setup-venv.ps1` / `scripts/doctor.ps1`
|
||
- `environment.yml`：需联网时的精确复现方案
|
||
- `pyproject.toml`：核心依赖只 4 个，其余走 extras
|
||
|
||
### Changed
|
||
- `core.get_rng` / `core.set_seed`：实现（L0 第 2 项）。`get_rng` 收 `int` / `np.integer` /
|
||
`Generator` / `None`，其余类型抛 `TypeError`；无参调用复用同一个会推进的共享生成器。
|
||
`set_seed` 同时覆盖 numpy 旧全局状态，让 sklearn / statsmodels 也可复现。
|
||
- `core.Result`：补上 `__repr__` 与 `summary()` 实现（L0 第 1 项落地）。
|
||
`repr` 紧凑单行且不打印 `data` 内容；`summary()` 输出可直接贴进论文的 Markdown 表格。
|
||
- `data.load_table`：实现（L0 第 3 项）。按扩展名分派 `.csv` / `.xlsx` / `.xls`；
|
||
`.csv` 默认做编码探测（utf-8 → utf-8-sig → gbk → gb18030），显式传 `encoding=` 时不再探测；
|
||
`na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`。
|
||
- `data.save_table`：实现（原属 L1，顺手落地）。按扩展名分派，父目录不存在时自动创建，
|
||
返回实际写入的 `Path`。
|
||
- `data.load_table` / `data.save_table`：docstring 补 `Parameters` / `Raises`
|
||
（`docs/02-architecture.md` §4.7 对每个公开函数的硬要求）。
|
||
- `data.load_table` 的返回注解 `Any` → `pd.DataFrame`，与 docstring 的承诺对齐。
|
||
|
||
### Added
|
||
- `docs/02-architecture.md` §4.7「类型约定」：注解要写全、numpy 标量的判断写法、
|
||
非法类型必须抛 `TypeError`。配套在 `docs/03-roadmap.md` 的开发纪律里加了指针。
|
||
- `docs/dev/personal-pitfalls.md`：个人易错点清单，**只追加、不通读**
|
||
|
||
### Fixed
|
||
- `data.save_table` 的后缀校验排在 `path.parent.mkdir(...)` **之后**，传 `.txt` 会先留下一个
|
||
空目录再抛 `ValueError`。改为**先校验、后副作用**，并加回归测试。
|
||
- `data/io.py` 里 `__all__` 与下一个 `def` 之间只有 1 个空行（PEP 8 要 2 个）。
|
||
- `tests/test_data.py` 顶上的**模块级** `pytestmark = pytest.mark.skip(...)` 会连带跳过同文件里
|
||
已经写好的函数，导致 `load_table` 零覆盖。改为逐条 skip 未实现的算法，并补 8 条 io 测试
|
||
（编码探测、NA 归一、后缀校验、缺文件报错、往返读写、类型校验）。测试数 31 → **39 passed**。
|
||
- conda base 里 zstandard 的 `*.conda_trash` 残骸目录被 Python 当成 namespace package 导入，
|
||
使 `.venv`（= base）的 `pd.read_csv` 抛 `ImportError: Can't determine version for zstandard`。
|
||
已把残骸目录改名禁用（**可逆**，未删除），详见 `docs/04-environment.md` 坑 6。
|
||
|
||
### Notes
|
||
- 除 `core.Result`、`core.get_rng`、`core.set_seed`、`data.load_table`、`data.save_table` 外，其余函数体**尚未实现**（统一 `raise NotImplementedError` + `TODO(L0/L1/v0.2)` 标记）。
|
||
这是刻意的：先定接口，再按 `docs/03-roadmap.md` 的 L0 → L1 顺序填实现。
|
||
- 已知缺口：`SALib`（Sobol/Morris）、`pymoo`、`pyright` 已装进 conda 环境 `mcm-toolkit`，`.venv` 里没有。
|
||
|
||
## [0.0.1] - 2026-10-01
|
||
|
||
### Added
|
||
- 项目初始化，包结构落盘（实现为空）。
|