wenjuanxing-parser 📊

wenjuanxing-parser 是一个专为 CollegesChat 校园生活现状调研问卷定制的非通用数据解析与文本清洗工具。

本项目正处于 Beta 阶段。它打破了传统表格的行列限制，通过将问卷星导出的原始矩阵数据横向聚合，自动转换为利于阅读、排版和开源共享的精简文本格式。

✨ 特性

• 非通用定制化解析：精准支持以下高阶/复合题型：
  • 单选题（支持可选的“其他”附加文本）
  • 多选题（支持可选的“其他”附加文本）
  • 单项填空题（支持基于正则表达式的弱校验）
  • 多项填空题（支持复合空格拆分）
• 智慧文件识别：命令行支持自动识别并读取 .csv 或 .xlsx (Excel) 格式的原始问卷数据。
• 类型安全的答案解析：内层模型（QuestionnaireResponse、UserAnswer、BasicData 等）基于 Pydantic 构建，保障元数据（IP 归属地、提交时间、序号）与答案结构的类型可靠。
• 懒加载：from_dataframe() 返回可迭代对象，按需逐行解析，不一次性物化全量数据。
• 可选业务校验：validate=True 开启必填项检查与正则弱校验，默认关闭以最大化吞吐。
• 智能化流式美化：自动处理附加文本前置标點符號，保证导出的文本排版优雅统一。

📦 安装与准备

项目使用现代 Python 包管理工具 uv 进行环境管理。

# 克隆仓库
git clone https://github.com/CollegesChat/wenjuanxing-parser
cd wenjuanxing-parser

# 同步并安装依赖环境
uv sync

🚀 快速使用

安装：

pip install wenjuanxing-parser[all] # 安装推荐的YAML（py-yaml12，用于问卷schema） + xlsx（python-calamine） 格式支持库
pip install wenjuanxing-parser # 仅安装数据处理模块，数据用你自己的库读

使用方法

1. 先编写问卷schema：例子
2. 下载问卷的答卷（按文本）
3. 用你的代码调用此库，示例：

import polars as pl
from yaml12 import parse_yaml
from wenjuanxing_parser import QuestionnaireData, load_questions_from_yaml

questions_map = load_questions_from_yaml(parse_yaml(yaml_text))
df = pl.read_csv("data.csv")

# 懒加载迭代：按需逐行解析，任意时刻仅一条 response 在内存
for response in QuestionnaireData.from_dataframe(df, questions_map):
    print(response.metadata.num, response.answers)

完整命令行入口参见：__main__.py

命令行参数说明

以下只能在安装了wenjuanxing-parser[all]后使用。

参数	短参数	默认值	说明
--data	-d	data.csv	问卷星导出的原始数据文件路径 (支持 .csv/.xlsx)
--config	-c	v2.yaml	对应 CollegesChat 标准的题库定义 YAML 路径
--output	-o	None	导出的文本路径 (留空则直接打印在终端控制台)

🎯 导出文本示例

Q: 宿舍是上床下桌吗？
A21136: 否。六人寝上下床，大一只有一张长桌，非常非常挤。
A21335: 否
A21818: 否，大一校区和本部都不是
Q: 教室和宿舍有没有空调？
A21335: 有，我是大一新生，北校区有的
A21818: 有，宿舍均有空调，本部部分常用教室没有空调

🧪 自动化测试

项目内置了完整的单元测试，利用 pytest 虚拟沙盒环境（tmp_path）对解析管线和强弱校验逻辑进行自动化覆盖。

执行以下命令运行测试：

uv run pytest

注意：本项目在打包与构建发布时，已通过 pyproject.toml 策略自动将 tests/ 目录和临时配置排除在 Wheel 包外，确保生产环境轻量纯净。

📄 开源协议

本项目采用 AGPL-3.0-only 协议开源。