Metadata-Version: 2.4
Name: wenjuanxing-parser
Version: 0.2.0b0
Summary: 为CollegesChat的答卷准备的非通用解析器。仅支持填空/多选+可选额外文本/单选+可选额外文本/多项填空。
Project-URL: Homepage, https://github.com/CollegesChat/wenjuanxing-parser
Author: Kaesinol
License: AGPL-3.0-only
License-File: LICENSE
Keywords: collegeschat,parser,pydantic,questionnaire,wenjuanxing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: pandas>=3.0.3
Requires-Dist: pydantic>=2.13.4
Provides-Extra: all
Requires-Dist: py-yaml12>=0.1.0; extra == 'all'
Requires-Dist: python-calamine>=0.6.2; extra == 'all'
Description-Content-Type: text/markdown

# wenjuanxing-parser 📊

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

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

## ✨ 特性

- **非通用定制化解析**：精准支持以下高阶/复合题型：
  - 单选题（支持可选的“其他”附加文本）
  - 多选题（支持可选的“其他”附加文本）
  - 单项填空题（支持基于正则表达式的弱校验）
  - 多项填空题（支持复合空格拆分）
- **智慧文件识别**：命令行支持自动识别并读取 `.csv` 或 `.xlsx` (Excel) 格式的原始问卷数据。
- **严格类型保障**：基于 `Pydantic` 展开全量矩阵解析，保障元数据（IP归属地、提交时间、序号）与答案结构的绝对可靠。
- **智能化流式美化**：自动处理附加文本前置标點符號，保证导出的文本排版优雅统一。

## 📦 安装与准备

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

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

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

```

## 🚀 快速使用

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

1. 先编写问卷schema：[例子](https://github.com/CollegesChat/questionnaire/blob/main/v2.yaml)
2. 下载问卷的答卷（按文本）
3. 用你的代码调用此库，示例：[\_\_main\_\_.py](src/wenjuanxing_parser/__main__.py)

### 命令行参数说明

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

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

### 🎯 导出文本示例

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

```

## 🧪 自动化测试

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

执行以下命令运行测试：

```bash
uv run pytest

```

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

## 📄 开源协议

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