CQL 教程 - 中文适配子包概览

20.1什么是中文适配子包

cql-lang 附带一系列全中文 API 的子包，把热门 Python 库包装成中文类名与方法名，覆盖 Web 后端、桌面 GUI、数据库、网络请求、认证加密、配置、日志、图片、文档、数据处理、定时任务、测试、ORM、时间日期、缓存与命令行等场景。

既可在 .cql 中文源码中直接使用，也可在普通 Python 中使用。
每个子包对应一个底层库，中文 API 只是包装层，底层能力完全保留。
共 19 个子包：CQFastAPI、CQPyqt、CQSqlite、CQHttp、CQSecurity、CQConfig、CQLog、CQPillow、CQCrypto、CQData、CQOffice、CQDataFrame、CQEmail、CQSchedule、CQTest、CQORM、CQDateTime、CQRedis、CQCLI。
其中 cqsqlite 基于 Python 内置 sqlite3、cqemail 基于标准库，无需额外安装依赖。

提示：各子包的详细 API 与示例见后续章节（CQFastAPI、CQPyqt、CQSqlite 等）。

20.2安装方式

子包的依赖都是可选的 extras。核心 CQL 语言只依赖 lark，子包依赖需要按需安装。一次装齐用 [all]：

bash

cd cql-lang
pip install .           # 仅核心 CQL 语言（依赖 lark）
pip install .[all]      # 安装全部中文适配子包的依赖

也可以按需安装部分依赖：

extras	子包	底层库
`[web]`	CQFastAPI	fastapi + uvicorn
`[desktop]`	CQPyqt	PySide6
`[http]`	CQHttp	requests + httpx
`[security]`	CQSecurity	PyJWT + bcrypt
`[config]`	CQConfig	python-dotenv
`[log]`	CQLog	loguru
`[image]`	CQPillow	Pillow
`[crypto]`	CQCrypto	cryptography
`[data]`	CQData	pydantic v2
`[office]`	CQOffice	python-docx + openpyxl
`[dataframe]`	CQDataFrame	pandas + numpy
`[schedule]`	CQSchedule	APScheduler
`[test]`	CQTest	pytest
`[orm]`	CQORM	SQLAlchemy
`[datetime]`	CQDateTime	arrow + python-dateutil
`[redis]`	CQRedis	redis
`[cli]`	CQCLI	typer + click

例如只安装 Web 后端依赖：pip install .[web]；只安装桌面依赖：pip install .[desktop]。未安装对应库时，导入该子包会失败。

20.3子包总表

19 个子包一览：

子包	主要中文 API	底层库	说明
`cqfastapi`	快速应用 / 路由组 / 查询参数 / HTTP异常 / 启动服务	FastAPI	Web 后端开发，用法与 FastAPI 完全一致
`cqpyqt`	应用程序 / 主窗口 / 按钮 / 标签 / 垂直布局 / 信号 / 消息框	PySide6	桌面 GUI 开发，提供中文控件、方法、信号与常量
`cqsqlite`	连接 / 执行 / 查询 / 查询字典 / 提交 / 回滚 / 完整性错误	sqlite3（内置）	数据库操作，无需安装额外依赖
`cqhttp`	获取 / 提交 / 更新 / 删除 / 会话 / 异步会话 / 响应	requests + httpx	网络请求，同步与异步双支持
`cqsecurity`	创建令牌 / 验证令牌 / 密码哈希 / 验证密码	PyJWT + bcrypt	JWT 令牌与密码哈希
`cqconfig`	环境 / 加载 / 读取 / 设置	python-dotenv	配置管理，读取 .env 文件
`cqlog`	调试 / 信息 / 警告 / 错误 / 致命 / 日志器	loguru（回退 logging）	日志输出，未装 loguru 自动回退标准库
`cqpillow`	打开 / 新建 / 缩放 / 裁剪 / 旋转 / 滤镜 / 画布 / 颜色	Pillow	图片处理
`cqcrypto`	对称加密 / 对称解密 / 哈希 / 生成RSA密钥对 / 公钥加密	cryptography	AES-GCM 对称加密、RSA 非对称与哈希
`cqdata`	模型 / 字段 / 校验错误 / 验证	pydantic v2	数据校验，声明式模型自动校验与类型转换
`cqoffice`	新建文档 / 添加段落 / 新建工作簿 / 设置单元格	python-docx + openpyxl	Word 与 Excel 文档处理
`cqdataframe`	数据表 / 系列 / 读取CSV / 过滤 / 排序 / 分组聚合 / 数组	pandas + numpy	表格数据处理与 numpy 数组操作
`cqemail`	创建邮件 / 发送邮件 / 邮件服务器 / 接收邮件	smtplib + email + imaplib	邮件收发，标准库实现，无需额外依赖
`cqschedule`	调度器 / 间隔任务 / 定时任务 / 每 / 在	APScheduler	定时任务，支持间隔、cron 与一次性任务
`cqtest`	测试 / 断言等于 / 参数化 / 期望异常 / 运行 / 夹具	pytest	单元测试，断言系列不依赖 pytest 即可使用
`cqorm`	基类 / 列 / 数据库 / 会话 / 查询结果 / 关系	SQLAlchemy	数据库 ORM，支持 SQLite / MySQL / PostgreSQL
`cqdatetime`	现在 / 解析 / 时间对象 / 偏移 / 人类化 / 计算年龄	arrow + python-dateutil	时间日期处理
`cqredis`	客户端 / 设置 / 获取 / 哈希设置 / 列表右推 / 发布 / 订阅	redis-py	缓存，覆盖字符串、哈希、列表、集合与发布订阅
`cqcli`	命令 / 选项 / 参数 / 运行 / 提示 / 确认 / 进度条 / 表	typer + click	命令行工具，快速构建 CLI 应用

20.4在 CQL 中导入子包

CQL 会把 CQFastAPI / CQPyqt / CQSqlite 等大写包名自动映射到对应的小写包名，大小写均可，直接在 .cql 源码中导入即可：

cql

从 CQFastAPI 导入 快速应用, 查询参数
从 CQSqlite 导入 连接
从 CQLog 导入 信息

应用 = 快速应用()
数据库 = 连接(":memory:")
信息("子包导入成功")

从 CQFastAPI 导入 ... 与 从 cqfastapi 导入 ... 写法等价，转译器自动映射。
导入后的中文 API（快速应用、连接、信息等）与 Python 目标下完全一致。