chore: 初始化 MCM/ICM Toolkit 仓库骨架

审查并精简 ChatGPT 的建库建议后落地的第一版骨架,只定接口不写实现。

- 建议审查:14 个包 → 7 个;约 250 个函数 → 约 40 个;5 个 Result 类 → 1 个
  (docs/01-suggestion-review.md)
- docs/:架构、路线图(含永久不做清单)、环境、Git 工作流、函数卡片模板
- src/mcm_toolkit/:core / data / stats / models / solve / decision / viz
  共 23 个模块,均为签名 + docstring + NotImplementedError
- tests/:9 个文件,其中 test_api_surface.py 已通过(20 passed)
- examples/ problems/ notebooks/ figures/ tables/ 骨架
- pyproject.toml(核心依赖 4 个 + 6 组 extras)、environment.yml
- scripts/:setup-venv.ps1(ASCII + LF)、setup-conda.ps1、doctor.ps1
- 环境:.venv(system-site-packages)与 conda 环境 mcm-toolkit 均已建好,
  数值栈版本与 base 完全对齐(numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6,MKL 后端)
This commit is contained in:
guzhujushi committed 2026-10-01 17:43:48 +08:00
commit 5319589dfd
76 files changed
+6812

No files matched your search

+37
View File
@@ -0,0 +1,37 @@
"""读写表格。
只保留两个函数:`load_table` / `save_table` 按扩展名分派。
原建议里的 `load_csv` `load_excel` `save_csv` `save_excel` 四个函数
只是在转发 pandas,合并后调用点更短。
"""
from __future__ import annotations
from pathlib import Path
from typing import Any
__all__ = ["load_table", "save_table"]
def load_table(path: str | Path, **kwargs: Any) -> Any:
"""按扩展名自动选择读取方式,返回 DataFrame。
约定:
* `.csv` 默认做编码探测(utf-8 → utf-8-sig → gbk → gb18030),
国内赛题数据常见 GBK;
* `.xlsx` / `.xls` 需要 `openpyxl`(`pip install "mcm-toolkit[excel]"`);
* `na_values` 默认包含空串、`"NA"`、`"N/A"`、`"#N/A"`、`"null"`、`"-"`。
Examples
--------
>>> df = load_table("data.csv") # doctest: +SKIP
>>> df.shape # doctest: +SKIP
"""
# TODO(L0): 编码探测 + 分派;Excel 缺 openpyxl 时给出可读报错。
raise NotImplementedError
def save_table(df: Any, path: str | Path, index: bool = False, **kwargs: Any) -> Path:
"""保存 DataFrame,返回实际写入的路径。"""
# TODO(L0)
raise NotImplementedError