class-schedule/README.md

课表日历生成器 (Class Schedule ICS Generator)

这是一个用于将学校提供的 行政历 (Excel) 和 课表 (Excel) 自动转换为通用日历文件 (.ics) 的 Python 脚本。 生成的日历文件可以直接导入到你的手机（iOS/Android）、Mac 日历、Outlook 或 Google Calendar 中。

功能特点

• 通用解析：自动适配每学期新的日期，只需保证行政历中“周次”列和“课表”的星期列格式不变即可。
• 智能避开节假日：行政历中带有“清明”、“劳动”、“端午”等汉字描述的日期，脚本会自动识别为节假日，并在生成当日日历时自动跳过，以免引发混乱。
• 完整的课程信息：每节课自动包含：课程名称 (标题)、教室 (地点)、代课班级/老师 (备注描述)。

---

依赖与安装 (首次使用)

本脚本依赖 Python 环境以及处理 Excel 文件的类库（主要是 pandas 和 openpyxl）。

为了避免污染全局 Python 环境或受到 macOS 系统限制，推荐使用 虚拟环境 (venv)。

1. 创建并激活虚拟环境

首次使用时，需要在项目根目录执行以下命令：

# 1. 创建虚拟环境 (名为 venv)
python3 -m venv venv

# 2. 激活虚拟环境 (每次运行脚本前都需要执行这一步)
source venv/bin/activate

2. 安装必要依赖库

在虚拟环境激活的状态下，安装解析表格所需的依赖：

pip install pandas openpyxl xlrd

---

使用说明 (每半年更新课表时)

当你拿到新学期的《课表.xlsx》和《行政历.xls》时，将它们放入该目录下，然后执行如下步骤：

1. 激活虚拟环境 (如果已在新终端)

source venv/bin/activate

2. 运行生成脚本

# 默认生成方式：
python generate_ics.py 课表.xlsx 行政历.xls

可选参数：

• -o 或 --output：指定输出的文件名（默认输出为 schedule.ics）
• -w 或 --weeks：指定生成多少周的课表（默认生成前 18 周）

例如：

python generate_ics.py 课表.xlsx 行政历.xls -o my_schedule.ics -w 16

3. 导入日历

运行成功后，目录中会多出一个 .ics 文件（如 schedule.ics）。

• Mac/Windows：直接双击使用自带的日历软件打开并导入即可。
• 手机：将文件通过微信 / 隔空投送 (AirDrop) 传输到手机，再选择使用“日历”打开导入。

---

表格数据要求 (格式规范)

如果你未来发现脚本运行报错，请检查新的 Excel 文件是否满足以下基础格式要求：

1. 行政历：
   • 第一列必须为周次，包含大写中文数字 "一"，脚本依靠该行来定位第一周。
   • 这行里必须至少有一列具有“带年份的完整日期”或被 Excel 识别为日期格式的内容，以供推算开学第一天的时间。
   • 节假日放假只需在原本数字上加上中文名称（诸如“4清明”），脚本遇到汉字即认为是假期并自动调休跳过。
2. 课表：
   • 首列应包含完整的时间片段，如 第1-2节 8:30~10:00（必须包含 8:30~10:00）。
   • 列标题需带有 "星期一" 至 "星期五" 等字样。
   • 单元格内换行规则：第一行为课程名，中间为人群/班级描述，最后一行为地点教室（脚本通过换行符 \n 进行拆分）。