apluslms/grade-python Docker 镜像 - 轩辕镜像

Python评分环境Docker镜像文档

1. 镜像概述和主要用途

本镜像为特定Python版本的程序作业自动评分环境，旨在提供标准化的评分运行时。镜像集成了路径中的指定Python版本，并预装核心评分工具（python-grader-utils、pytest），支持多种扩展场景的依赖库，适用于各类Python程序作业的自动化评分流程。

2. 核心功能和特性

2.1 基础功能

• 特定Python版本：镜像路径中包含指定版本的Python解释器，确保评分环境版本一致性。
• 核心评分工具：预装
  • python-grader-utils（作业评分工具库）
  • pytest（Python测试框架）。

2.2 扩展特性

• 多标签变体：提供多种标签后缀（如math-*、ml-*），按需集成扩展库（如科学计算、机器学习、数据库等）。
• 丰富实用命令：内置graderutils、unittest系列、run-all-unittests等命令，简化评分流程配置。
• 兼容性：基于grading-base镜像构建，支持其核心功能（如capture、testcase包装器）。

3. 标签说明

3.1 基础标签格式

镜像标签遵循<Python版本>-<评分基础版本>格式，其中：

• <Python版本>：镜像内置的Python版本（如3.5、3.7）。
• <评分基础版本>：底层grading-base镜像版本（如2.0、3.1）。
• 更新标识：标签中可包含uN（N为递增数字），表示在软件版本不变的情况下的镜像更新（如3.5-2.0u1表示Python 3.5、评分基础2.0的第1次更新）。

3.2 新版本标签格式

较新版本标签包含python-grader-utils版本，格式为<Python版本>-<grader-utils版本>-<评分基础版本>（如3.7-3.3-3.1表示Python 3.7、grader-utils 3.3、评分基础3.1）。

3.3 扩展标签变体

除基础标签外，提供以下功能扩展标签（前缀+基础标签格式，如math-3.9-3.5-4.0）：

4. 使用场景和适用范围

本镜像适用于各类Python程序作业的自动化评分场景，尤其适合教育机构、在线编程平台等需要标准化评分环境的场景。具体适用范围包括：

• 基础Python作业：使用基础标签（如3.9-4.0），通过graderutils或unittest进行代码评分。
• 科学计算作业：使用math-*标签，支持NumPy、SciPy等库的作业评分。
• 机器学习作业：使用ml-*标签，满足pandas、scikit-learn依赖的评分需求。
• 特定课程作业：通过y2-*、mec-*等专用标签，适配课程定制化依赖。
• 数据库相关作业：使用psql-*标签，支持PostgreSQL交互代码的评分。

5. 使用方法和配置说明

5.1 基础命令概述

镜像提供以下核心实用命令，用于简化评分流程配置：

5.1.1 graderutils

功能：执行python-grader-utils评分工具，支持多种参数配置。
语法：

bash
graderutils [--use-iotester] [--use-rpyc] [--novalidate] [--container] [--show-config] [--develop-mode] [--exercise-path <绝对路径>] -- [<测试配置绝对路径>]

参数说明：

• --use-iotester：创建iotester所需的目录结构及权限。
• --use-rpyc：通过RPyC（远程Python调用）在独立进程中导入并执行学生代码。
• --novalidate：跳过测试配置文件的验证。
• --container：在基于grading-base的容器中运行时，将graderutils自身异常输出到stderr（通常不使用）。
• --show-config：将测试配置打印为警告信息。
• --develop-mode：显示所有未处理异常（无格式化），并隐含--show-config；默认情况下，测试配置错误会被通用错误信息掩盖，以避免泄露评分细节。
• --exercise-path <绝对路径>：指定评分测试运行目录（默认/exercise；个性化作业可设为/personalized_exercise）。

说明：

• 命令通过grading-base的capture包装器执行graderutils.main（使用--use-rpyc时执行graderutils.__main__）。
• 除--use-iotester、--use-rpyc、--exercise-path外，其他参数均传递给Python模块。
• 若无参数，默认使用/exercise/test_config.yaml作为测试配置文件（即配置文件为test_config.yaml时，仅需执行graderutils）。

5.1.2 unittest

功能：python3 -m unittest的别名，自动将/exercise添加到PYTHONPATH。
语法：

bash
unittest [unittest参数]

5.1.3 unittest-capture

功能：基于capture包装器的unittest执行命令，自动将/exercise添加到PYTHONPATH；无错误时自动执行err-to-out（错误输出重定向到标准输出）。
语法：

bash
unittest-capture [unittest参数]

5.1.4 unittest-testcase

功能：结合testcase（来自grading-base）和unittest的包装命令，自动将/exercise添加到PYTHONPATH。
语法：

bash
unittest-testcase [-t 标题] [-p 分数] [-s 跳过条件] [unittest参数]

参数：

• -t：测试标题。
• -p：测试分数。
• -s：跳过条件。
• 其余参数传递给unittest。
  说明：需参考grading-base的testcase文档。

5.1.5 python-compile-all

功能：python3 -m compileall的别名，用于验证提交文件的Python语法。
语法：

bash
python-compile-all [compileall参数]

5.1.6 run-all-unittests

功能：一站式评分命令，可替代简单场景下的run.sh。
语法：

bash
run-all-unittests [-S] [-p 每个测试类分数]

流程：

1. 语法验证（除非指定-S跳过）；若语法错误，终止测试。
2. 查找提交和练习路径中所有匹配*test*.py的文件。
3. 对每个直接继承unittest.TestCase的类，通过testcase和unittest执行测试。
   参数：

• -S：跳过语法验证。
• -p：每个测试类通过时的分数（默认按配置）。

6. 部署示例

6.1 基础评分任务（使用graderutils）

挂载练习目录（含test_config.yaml），执行基础评分：

bash
docker run --rm -v /本地练习目录:/exercise apluslms/python-grading:3.9-3.5-4.0 graderutils

6.2 运行单元测试（使用run-all-unittests）

对提交作业执行全流程测试（语法验证+单元测试）：

bash
docker run --rm -v /本地提交目录:/submission -v /本地练习目录:/exercise apluslms/python-grading:3.9-3.5-4.0 run-all-unittests -p 5

（-p 5表示每个测试类满分5分）

6.3 科学计算作业评分（使用math-*标签）

运行需要NumPy和Excel解析的作业评分：

bash
docker run --rm -v /本地练习目录:/exercise apluslms/python-grading:math-3.9-3.5-4.0 graderutils --exercise-path /personalized_exercise