Metadata-Version: 2.4
Name: cql-lang
Version: 1.1.1
Summary: CQL - Chinese Query Language，一套将中文源码转译为 Python 3 的中文编程语言，含 CQFastAPI/CQPyqt 等中文适配子包
Home-page: https://example.com/cql-lang
Author: CQFISH&喵酱出品
Author-email: cqfish@example.com
License: MIT
Keywords: chinese language compiler cql lark python fastapi pyqt sqlite
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.0
Provides-Extra: web
Requires-Dist: fastapi>=0.100; extra == "web"
Requires-Dist: uvicorn>=0.20; extra == "web"
Provides-Extra: desktop
Requires-Dist: PySide6>=6.4; extra == "desktop"
Provides-Extra: http
Requires-Dist: requests>=2.25; extra == "http"
Requires-Dist: httpx>=0.23; extra == "http"
Provides-Extra: security
Requires-Dist: PyJWT>=2.0; extra == "security"
Requires-Dist: bcrypt>=4.0; extra == "security"
Provides-Extra: config
Requires-Dist: python-dotenv>=0.20; extra == "config"
Provides-Extra: log
Requires-Dist: loguru>=0.6; extra == "log"
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: uvicorn>=0.20; extra == "all"
Requires-Dist: PySide6>=6.4; extra == "all"
Requires-Dist: requests>=2.25; extra == "all"
Requires-Dist: httpx>=0.23; extra == "all"
Requires-Dist: PyJWT>=2.0; extra == "all"
Requires-Dist: bcrypt>=4.0; extra == "all"
Requires-Dist: python-dotenv>=0.20; extra == "all"
Requires-Dist: loguru>=0.6; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CQL（Chinese Query Language）

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

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

> 开发者请查阅完整使用手册：[DEVELOPER_GUIDE.md](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](https://github.com/lark-parser/lark)（解析器）。

```bash
cd cql-lang
pip install .
```

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

开发模式：

```bash
pip install -e .
```

运行测试：

```bash
pip install pytest
pytest tests/ -v
```

## 快速开始

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

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

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

在 Python 中以库方式使用：

```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 等价；当别名被当作普通值引用（如 `别名 = 长度`）时，由运行时注入的中文命名空间兜底。

### 类型注解

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

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

### 示例片段

```cql
# 推导式
平方 = [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（包管理器）

```bash
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 中使用：

```bash
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`）

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

应用 = 快速应用()

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

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

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

### CQPyqt 示例（`examples/gui_hello.cql`）

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

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

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


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


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

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

### CQSqlite 示例

```cql
# -*- 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`）：

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

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

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

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

## 当前限制

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

## 许可证

[MIT](LICENSE)
