cql-lang 1.1.1

CQL - Chinese Query Language，一套将中文源码转译为 Python 3 的中文编程语言，含 CQFastAPI/CQPyqt 等中文适配子包

CQL（Chinese Query Language）

CQL 是一套用 Python 实现的中文编程语言。它将 .cql 中文源码转译为等价的 Python 3 代码，覆盖了除元类、异步 await、类型注解泛型等高级特性之外的大多数 Python 原生语法。

由 CQFISH&喵酱出品。本工具面向中文编程学习者、中文教学场景以及对代码可读性有要求的项目。

开发者请查阅完整使用手册：DEVELOPER_GUIDE.md，包含 CQL 语言与全部中文适配子包的详细 API 与示例。

特性一览

• 全中文关键字：如果 / 否则如果 / 否则、循环 / 当、中断 / 继续 / 跳过、函数 / 返回 / 类 / 继承、尝试 / 捕获 / 最终 / 抛出、导入 / 从 / 作为、伴随、延迟（lambda）、产量（yield）……
• 中英双运算符：+ - * / // % ** 与 加 / 减 / 乘 / 除 / 整除 / 取余 / 幂 均可使用；逻辑、比较、位运算同样支持中文词（与 / 或 / 非 / 等于 / 位与 / 左移……）。
• 中文标识符：变量名、函数名、类名均可使用中文（关键字除外）。
• 中文内置函数别名：打印 / 输入 / 长度 / 范围 / 类型 / 求和 / 最大值 / 最小值 / 绝对 / 是否是实例…… 编译期自动替换为 Python 内置函数，同时运行时注入命名空间兜底，用户自定义同名标识符优先。
• 中文类型注解：x: 整数 = 5、函数 加(a: 整数, b: 整数) -> 整数。
• 完整语法覆盖：控制流、函数（默认值 / *args / **kwargs / 返回值）、面向对象（继承 / super / 类与实例方法）、异常处理、导入、容器字面量、切片与解包、四种推导式、装饰器、with、lambda、海象运算符。
• 命令行工具：cql run 运行、cql build 编译、cql repl 交互式解释器。
• 包管理器：cqlip install / uninstall / list，基于 ~/.cql。
• 中文适配子包：CQFastAPI（Web 后端）、CQPyqt（桌面 GUI）、CQSqlite（数据库）、CQHttp（网络请求）、CQSecurity（认证加密）、CQConfig（配置管理）、CQLog（日志），均可直接在 .cql 源码中使用。

安装

要求 Python 3.7+，唯一第三方依赖为 lark（解析器）。

cd cql-lang
pip install .

安装后得到两个命令：cql（编译器/解释器）与 cqlip（包管理器）。

开发模式：

pip install -e .

运行测试：

pip install pytest
pytest tests/ -v

快速开始

# hello.cql
函数 斐波那契(n):
    如果 n <= 1:
        返回 n
    返回 斐波那契(n - 1) + 斐波那契(n - 2)

打印("第 10 项斐波那契数：", 斐波那契(10))

cql run examples/hello.cql
cql build examples/hello.cql        # 生成 hello.py
cql repl                            # 进入交互式解释器

在 Python 中以库方式使用：

import cql
code = cql.compile('打印("你好")')
print(code)          # print("你好")
exec(code)

语法速查

关键字映射

CQL	Python	CQL	Python
如果 / 否则如果 / 否则	if / elif / else	尝试 / 捕获 / 最终	try / except / finally
循环 / 当	for / while	抛出 / 返回 / 产量	raise / return / yield
中断 / 继续 / 跳过	break / continue / pass	导入 / 从 / 作为	import / from / as
函数 / 类 / 继承	def / class / 基类列表	全局 / 非局部	global / nonlocal
自身 / 超类	self / super	伴随	with
与 / 或 / 非	and / or / not	延迟	lambda
是 / 在 / 不是 / 不在	is / in / is not / not in	真 / 假 / 空	True / False / None
删除 / 断言	del / assert	捕获...作为 e	except ... as e

运算符

• 算术：加 减 乘 除 整除 取余 幂 或 + - * / // % **
• 比较：等于 不等于 大于 小于 大于等于 小于等于 或 == != > < >= <=
• 位运算：位与 位或 异或 取反 左移 右移 或 & | ^ ~ << >>
• 赋值：= += -= *= /= //= %= **= &= |= ^= <<= >>= 以及海象 :=
• 优先级与 Python 完全一致（由语法规则保证，转译时无需额外加括号）

内置函数中文别名

打印 print、输入 input、长度 len、范围 range、类型 type、是否是实例 isinstance、整数 int、文本 str、浮点数 float、布尔 bool、列表 list、字典 dict、集合 set、元组 tuple、枚举 enumerate、压缩 zip、排序 sorted、求和 sum、最大值 max、最小值 min、绝对 abs、地图 map、过滤器 filter、归约 reduce、全部 all、任意 any、打开 open、格式化 format……

以及常见异常：异常 Exception、值错误 ValueError、类型错误 TypeError、键错误 KeyError、索引错误 IndexError、除零错误 ZeroDivisionError、运行时错误 RuntimeError 等。

说明：中文别名在函数调用位置（如 打印(...)）会被转译器替换为 Python 内置函数，性能与手写 Python 等价；当别名被当作普通值引用（如 别名 = 长度）时，由运行时注入的中文命名空间兜底。

类型注解

x: 整数 = 5
名称: 文本 = "CQL"
函数 加(a: 整数, b: 整数) -> 整数:
    返回 a + b

支持的中文类型名：整数 int、文本 str、浮点数 float、布尔 bool、列表 list、字典 dict、集合 set、元组 tuple、字节 bytes。

示例片段

# 推导式
平方 = [x * x 循环 x 在 范围(10) 如果 x % 2 == 0]

# lambda
翻倍 = 延迟 x: x * 2

# 装饰器
@计时器
函数 计算():
    跳过

# 类与继承
类 狗 继承 动物:
    函数 叫(自身):
        返回 "汪汪"

# 异常
尝试:
    抛出 值错误("无效")
捕获 值错误 作为 e:
    打印(e)

# with
伴随 打开("a.txt", "w") 作为 f:
    f.write("内容")

命令行工具

cql

cql run <file.cql>            # 运行 CQL 程序
cql run <file.cql> -e utf-8   # 指定源文件编码
cql build <file.cql>          # 编译为同名 .py
cql build <file.cql> -o out.py
cql repl                      # 交互式 REPL（支持多行输入，空行提交）

cqlip（包管理器）

cqlip install 包名               # 从当前目录的「包名.cql」或「包名/」目录安装
cqlip install 包名 --source 路径  # 从指定文件/目录安装
cqlip uninstall 包名
cqlip list

• 源码存放于 ~/.cql/packages/包名/，编译产物存放于 ~/.cql/cache/包名/（保持相对路径）；
• 安装完成后自动编译全部 .cql；
• cql run 执行时自动将 ~/.cql/cache 加入 sys.path，可直接 导入 已安装的包。

中文适配子包

cql-lang 附带一系列全中文 API 的子包，把热门 Python 库包装成中文类名与方法名，可直接在 .cql 源码或普通 Python 中使用：

pip install .                # 仅核心 cql（依赖 lark）
pip install .[all]           # 安装全部中文适配子包依赖
pip install .[web]           # 仅 Web：fastapi + uvicorn
pip install .[desktop]       # 仅桌面：PySide6

子包	中文 API	底层库	示例
cqfastapi	快速应用 / 路由组 / 查询参数 / HTTP异常 / 启动服务	FastAPI	应用 = 快速应用()；应用.获取("/你好")(函数)
cqpyqt	应用程序 / 主窗口 / 按钮 / 标签 / 垂直布局 / 信号 / 消息框	PySide6	按钮.被点击.连接(槽函数)
cqsqlite	连接 / 执行 / 查询 / 查询字典 / 提交 / 回滚 / 完整性错误	sqlite3（内置）	数据库 = 连接("app.db")
cqhttp	获取 / 提交 / 更新 / 删除 / 会话 / 异步会话 / 响应	requests + httpx	响应 = 获取("https://...")
cqsecurity	创建令牌 / 验证令牌 / 密码哈希 / 验证密码	PyJWT + bcrypt	令牌 = 创建令牌(载荷, 密钥, 过期秒=3600)
cqconfig	环境 / 加载 / 读取 / 设置	python-dotenv	加载(".env")；读取("数据库地址")
cqlog	调试 / 信息 / 警告 / 错误 / 致命 / 日志器	loguru（回退 logging）	信息("服务已启动")

CQFastAPI 示例（examples/web_hello.cql）

# -*- coding: utf-8 -*-
从 CQFastAPI 导入 快速应用, 查询参数, 启动服务

应用 = 快速应用()

@应用.获取("/")
函数 首页():
    返回 {"消息": "你好，CQL Web 世界！"}

@应用.获取("/物品/{id}")
函数 获取物品(id: 整数, 名称: 文本 = 查询参数(描述="物品名称")):
    返回 {"编号": id, "名称": 名称}

如果 __name__ == "__main__":
    启动服务(应用, 端口=8000)

CQPyqt 示例（examples/gui_hello.cql）

# -*- coding: utf-8 -*-
从 CQPyqt 导入 应用程序, 主窗口, 按钮, 标签, 垂直布局, 定时器

应用 = 应用程序([])
窗口 = 主窗口()
窗口.设置窗口标题("CQL 桌面示例")

标签控件 = 标签("点击按钮试试")
按钮控件 = 按钮("点我")


函数 处理点击():
    标签控件.设置文本("被点击了！")


按钮控件.被点击.连接(处理点击)

布局 = 垂直布局()
布局.添加控件(标签控件)
布局.添加控件(按钮控件)
窗口.设置布局(布局)
窗口.显示()
应用.执行()

CQSqlite 示例

# -*- coding: utf-8 -*-
从 CQSqlite 导入 连接

数据库 = 连接(":memory:")
数据库.执行("CREATE TABLE 用户(编号 INTEGER PRIMARY KEY, 姓名 TEXT)")
数据库.执行("INSERT INTO 用户(姓名) VALUES(?)", ("小明",))
数据库.提交()
行们 = 数据库.查询("SELECT * FROM 用户")
打印(数据库.查询字典("SELECT * FROM 用户"))
数据库.关闭()

注意：SQL 语句本身仍使用英文关键字（SQL 并非 Python 语法，CQL 转译器不会改写字符串中的 SQL）。

项目结构

cql-lang/
├── cql/
│   ├── __init__.py    # 包入口：compile / compile_file / CQLCompileError
│   ├── lexer.py       # Lark EBNF 语法定义 + 缩进处理器
│   ├── parser.py      # Transformer：语法树 -> Python 代码字符串
│   ├── compiler.py    # 编译主流程：解析 + 转译 + 中文友好错误
│   ├── cli.py         # cql 命令：run / build / repl
│   ├── cqlip.py       # cqlip 命令：install / uninstall / list
│   └── utils.py       # 缩进辅助、关键字/运算符/内置函数/类型映射
├── cqfastapi/         # 中文适配：Web 后端（FastAPI）
├── cqpyqt/            # 中文适配：桌面 GUI（PySide6）
├── cqsqlite/          # 中文适配：数据库（sqlite3）
├── cqhttp/            # 中文适配：网络请求（requests/httpx）
├── cqsecurity/        # 中文适配：认证加密（PyJWT/bcrypt）
├── cqconfig/          # 中文适配：配置管理（python-dotenv）
├── cqlog/             # 中文适配：日志（loguru/logging）
├── tests/             # pytest 测试用例（覆盖主要语法）
├── examples/          # 示例程序
├── setup.py           # 打包配置（包名 cql-lang，依赖仅 lark）
├── README.md
└── LICENSE

转译示例

输入（fib.cql）：

函数 斐波那契(n):
    如果 n <= 1:
        返回 n
    返回 斐波那契(n - 1) + 斐波那契(n - 2)

cql build fib.cql 输出（fib.py）：

def 斐波那契(n):
    if n <= 1:
        return n
    return 斐波那契(n - 1) + 斐波那契(n - 2)

转译后的代码与手写 Python 逻辑完全等价，缩进统一为四个空格，字符串字面量与中文标识符原样保留。

当前限制

• 不支持：元类、异步（async/await）、泛型类型注解、f-string 前缀字符串；
• # 注释在词法阶段被忽略（不会出现在编译产物中），文档字符串（"""..."""）原样保留；
• 关键字（如果 / 循环 等）不能用作标识符；中文内置别名作为标识符时由用户自定义优先。

许可证

MIT