guzhujushi/MCM-ICM_Toolkit
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
97a2f95066192e800dbac3ee15acc9aebac84800
MCM-ICM_Toolkit/CHANGELOG.md
T
guzhujushi 97a2f95066 fix(env): 钉死 pyright 的分析目标，修掉"无法解析导入 numpy/pandas" 
现象：编辑器 / pyright 满屏 reportMissingImports，但 .venv 与 conda 环境里
import numpy, pandas 都正常，pytest 也全过。

根因两层：

1. pyright 没配 venvPath / pythonPath 时会去 PATH 上找 python。本机 PATH 上
   唯一的 python 是 agent-tools 的 shim（Codex 运行时，Python 3.14），没有科学栈。
   pyright --verbose 显示它选了 3.14.6，Search paths 里一个 Anaconda 路径都没有。
   注意持久化的 User/Machine PATH 并没有这一项，是 Codex 进程临时注入的——所以
   "我的终端没问题"和"工具有问题"可以同时成立。
2. .venv 是 --system-site-packages 建的，三方包在 D:\anaconda\Lib\site-packages，
   而 pyright / Pylance 不认 pyvenv.cfg 的 include-system-site-packages，
   只去 .venv\Lib\site-packages 找（那里只有 pip）。
   pyright 不读 pyvenv.cfg，但**认 .pth**。

改动：
- pyproject.toml [tool.pyright]：venvPath = "." / venv = ".venv" /
  pythonVersion = "3.13"，并注释了为什么必须写
- scripts/setup-venv.ps1：新增第 [2/4] 步，自动往 .venv 写
  _mcm_base_site_packages.pth 指向该机 base 的 site-packages，换机重建即可
- tests/test_data.py：3 处 isna().all() 断言外面套 bool()（它的类型是
  Series | bool，直接当条件 pyright 报"条件操作数无效"）；
  2 处故意传错类型的用例加 type: ignore[arg-type]

结果：pyright 17 errors -> 0 errors / 0 warnings；pytest 两套环境均
40 passed, 44 skipped；ruff All checks passed；setup-venv.ps1 通过 AST 解析
（纯 ASCII + LF）。

文档：docs/04-environment.md 新增坑 7（含 pyright --verbose 诊断口诀与
VS Code / PyCharm 的操作步骤）、STATUS 决策 29、CHANGELOG。
2026-10-02 13:36:16 +08:00

5.0 KiB
Raw Blame History

更新日志

格式参考 Keep a Changelog， 版本号参考 语义化版本。

[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

  • 编辑器 / pyright 报"无法解析导入 numpy、pandas"：分析器会去 PATH 上找 python， 本机 PATH 上只有 Codex 运行时的 3.14 shim（无科学栈），且 pyright 不认 pyvenv.cfg 的 include-system-site-packages。 改为 [tool.pyright] 指定 venvPath = "." / venv = ".venv" / pythonVersion = "3.13"，并让 scripts/setup-venv.ps1 往 .venv 里写一个 指向 base site-packages 的 .pth。pyright 17 errors → 0。 详见 docs/04-environment.md 坑 7。
  • tests/test_data.py：df["b"].isna().all() 的类型是 Series | bool， 直接当断言条件 pyright 会报"条件操作数无效"，外面套 bool()； 两条故意传错类型的用例加 # type: ignore[arg-type]。
  • 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

  • 项目初始化，包结构落盘（实现为空）。
Reference in new issue View Git Blame Copy Permalink