Score Stats：Excel 成绩分析工具

一个采用 MIT 许可证的 Python 教学项目。支持导入 Excel/CSV、检查成绩数据、统计多科成绩，并导出 Excel 报告；仍保留直接输入分数的命令行用法。

第一版功能

• 导入 .xlsx 或 .csv，可指定 Excel 工作表和待统计科目。
• 检查缺失身份信息、重复学号、缺考、非数字成绩、越界值和公式。
• 输出每科平均分、中位数、最高分、最低分、及格率、优秀率和有效人数。
• 汇总学生总分、有效科目平均分及总分排名；同分采用 1、1、3 竞争排名。
• 导出“使用说明、原始成绩、学生汇总、科目统计、异常记录”五张工作表。
• 报告包含表头、筛选、冻结窗格、数值格式和百分比格式。

本版使用命令行操作，各科等权，及格线为 60 分、优秀线为 90 分。暂不包含图形界面、权重设置或图表。

快速开始

环境：Python 3.8 或以上版本。Excel 导入/导出使用 openpyxl，依赖版本见 requirements.txt。

在项目目录打开 PowerShell，首次使用执行：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

使用附带的虚构成绩表生成报告：

.\.venv\Scripts\python.exe score_stats.py --input examples/示例成绩.xlsx --sheet 正常成绩 --output output/成绩分析报告.xlsx

安装依赖后即可执行上面的分析命令。报告文件已存在时，换一个文件名，或在命令末尾加上 --overwrite。--overwrite 仅允许替换报告，始终禁止覆盖输入文件。

如果 Python 环境已经安装了依赖，下面的示例均可直接使用 python；使用本项目虚拟环境时，将 python 换成 .\.venv\Scripts\python.exe 即可。

导入自己的表格

python score_stats.py --input 我的成绩.xlsx --sheet 一班 --output 一班报告.xlsx
python score_stats.py --input examples/示例成绩.csv --output CSV报告.xlsx
python score_stats.py --input 旧编码成绩.csv --encoding gb18030

默认读取 Excel 的第一个工作表；默认在输入文件旁生成 <输入文件名>_分析报告.xlsx。CSV 默认使用 UTF-8（兼容 BOM）；旧编码文件可以指定 --encoding gb18030。

表格有“班级”等非成绩列时，应明确指定科目：

python score_stats.py --input 我的成绩.xlsx --subjects 数学 英语 程序设计

体验数据校验

python score_stats.py --input examples/示例成绩.xlsx --sheet 异常演示 --output 异常分析报告.xlsx

附带文件均为虚构数据：

文件	用途
示例成绩.xlsx	包含“正常成绩”和“异常演示”两个工作表
示例成绩.csv	正常成绩的 CSV 版本
异常成绩.csv	演示缺考、越界、重复学号、公式等情况
成绩分析报告.xlsx	正常示例运行得到的报告，供查看效果

原有用法仍可使用

python score_stats.py 88 92 76 59 100

直接输入模式只依赖 Python 标准库，输出人数 5、平均分 83.00、最高分 100.00、最低分 59.00、及格人数 4、及格率 80.00%。运行 python score_stats.py --help 查看完整参数。

输入格式

第一行必须是表头，包含名称为“学号”和“姓名”的列，以及至少一门科目。列顺序不限；空白行会跳过，异常记录仍保留原始行号。请勿在表头上方添加标题或使用合并表头。

学号	姓名	数学	英语	程序设计
0001	张三	88	92	95
0002	李四	76	85	90

• 未指定 --subjects 时，除“学号”“姓名”外的所有列均作为科目。
• 学号应在 Excel 中设为文本，以保留 0001 的前导零。程序不会猜测补零位数。
• 分数使用 0—100 之间的数值，可含小数。空白、“缺考”“缺失”作为缺失成绩。
• 不支持旧版 .xls、加密文件或公式求值。公式成绩会记录为异常；请在源表中复制并“粘贴为值”后再导入。

统计和异常处理规则

情况	处理方法
合法零分	计入统计，并判定不及格
空白、缺考、缺失	不记零分，排除该科统计；该生不参与总分排名
非数字、越界、无穷大、NaN、公式	记录行号、列名、原始值和原因；排除该科统计，该生不参与总分排名
学号重复	同学号所有记录均排除统计，避免任意选取其中一条
学号或姓名缺失/无效	整行排除统计，并保留在原始成绩和学生汇总中
数字型学号	转为文本并提示；已丢失的前导零无法恢复
重复/缺失表头、只有表头、无表头的额外数据	停止分析并提示修正，不生成误导性报告

每科平均分、及格率和优秀率均以身份有效、且该科分数有效的人数为分母。某科没有有效成绩时，均值和比例留空，计数显示 0。“有效人数＋缺失人数＋无效人数”等于身份有效记录数。

只有身份有效、且所选科目全部有效的学生，才计算总分和排名；平均分可按已取得的有效成绩计算，因此不同有效科目数的学生不宜直接比较平均分。总分排名使用未按显示位数舍入的值，同分并列。

导出文件是本次分析的数值快照，修改其中的单元格不会自动重新统计。需要更新结果时，请修改原始输入文件并重新运行程序。原始成绩页保留读取的单元格值及来源行号，不复制原工作簿的格式、图形或其他工作表；输入中的公式按文本保存。

项目结构与测试

score-stats/
├── score_stats.py       # 命令行入口与原有单科模式
├── gradebook.py         # 读取、校验、分析和报告导出
├── requirements.txt    # Excel 功能依赖
├── examples/           # 虚构成绩示例
├── tests/              # 关键统计口径和文件流程测试
├── output/             # 示例报告与提交截图
├── README.md
└── LICENSE

在项目目录运行：

python -m unittest discover -s tests -v

测试覆盖旧用法、Excel/CSV 导入、工作表选择、文本学号、缺考与零分、重复学号、并列排名、无有效成绩、公式文本导出及覆盖保护。

许可证

本项目代码采用 MIT License，完整文本见 LICENSE。主要源文件使用 SPDX-License-Identifier: MIT 标明许可证。

选择 MIT 的理由

1. 本项目用于教学，目标是方便他人学习、修改和复用。
2. MIT 是宽松型许可证，允许商用和闭源衍生，便于整合到其他项目。
3. 条款简洁，适合小型工具；分发副本或实质性部分时仍须保留版权和许可声明。
4. MIT 不强制公开衍生修改，本项目选择优先促进复用，而不强制下游贡献回流。

这与第三章课件第 15、32 页中“MIT 适合传播和商业化”的理论一致。开源不等于放弃版权，许可证也不承诺软件质量保证。

第三方依赖 openpyxl 采用 MIT 许可证，其依赖也遵循各自许可。本项目的 MIT 声明不替代第三方许可；发布包含第三方代码的安装包时应保留相应声明。本提交包只包含本项目代码及依赖清单，不打包虚拟环境。

参考：MIT 标准文本、openpyxl 项目与许可信息、openpyxl 官方使用文档。