ARTICLE · 1028080

JianPy 技术文档(正式查询手册)

发布时间：2026-09-17 22:32:53 最近访问：2026-09-17 22:32:53

JianPy 技术文档(正式查询手册)

JianPy 技术文档（正式查询手册）

版本：v2.10 · 面向已通过基础教程、准备开始写项目的读者
一句话定位：遇到任何语法、关键词、写法问题，查这份文档就能解决。别把它当入门书读，要当字典用——"用什么查什么、怎么查怎么用"。
设计哲学：JianPy = Python 语义 + 声明层拼音关键词 + 大括号 {} + 入口()。它保留 Python 的动态类型与运行时语义，把"声明层"和"控制流"改成中文拼音，用大括号取代缩进，其余（类型、运算符、布尔、None）保持 Python 原样。
命名约定（本手册全篇遵守）：变量名、方法名、类名、函数名优先使用中文，用拼音/拼音缩写当语法关键骨架，中文当语义标识符。

文档说明与术语总表
程序骨架与入口
大括号与缩进、分号、注释
变量、常量、数据类型
运算符与表达式
函数
控制流
结构模式匹配
类与面向对象
模块系统
异常处理
上下文管理器
推导式与集合
常用内置函数与中文标识符规范
Python 第三方库协作
常见问题排查与"过时写法"对照表
编译器当前实现边界
附：JianPy ↔ Python 全量翻译对照速查表

第 1 章文档说明与术语总表

1.1 核心原则（记住三句话）

声明层用拼音：gn（函数）、shu（变量）、chang（常量）、sjgnbao（类）、fanhui（返回）。
控制流用拼音：ruguo/fouzeruguo/fouze（条件）、zhuge/zhiyao（循环）、pifen/ruguoshi（匹配）、changshi/buhuo/zuizong/paochu（异常）、tuoguan...wei（上下文）。
其余保持 Python 原样：int/str/float/list/...、True/False/None、and/or/not、运算符、type、# 注释、@ 装饰器，全部不用记，保持英文。

命名：代码里敲拼音/中文标识符，脑子里想中文，示例里一律用中文标识符（变量、方法、函数、类名）。

1.2 完整拼音关键词速查表

分类	JianPy 关键词	作用	对应 Python
声明	`gn`	函数定义	`def`
声明	`sjgnbao`	类定义	`class`
声明	`shu`	可变变量声明	变量赋值
声明	`chang`	常量（编译期只读检查）	`Final[类型]`
声明	`fanhui`	函数返回	`return`
模块	`引入`	引入模块	`import`
模块	`从 ... 引入`	从模块引入	`from ... import`
模块	`wei`	别名	`as`
模块	`引出`	模块导出（`__all__`）	`__all__`
对象	`ben`	当前实例	`self`
对象	`fuji`	父级调用	`super()`
声明	`hulue`	空操作	`pass`
函数	`wuming`	匿名函数	`lambda`
函数	`zanting`	生成器暂停	`yield`
异步	`rangchu`	异步函数（让出）	`async`
异步	`dengdai`	等待异步	`await`
条件	`ruguo` / `fouzeruguo` / `fouze`	如果 / 否则如果 / 否则	`if` / `elif` / `else`
循环	`zhuge`	逐个遍历	`for`
循环	`zhiyao`	条件循环	`while`
循环	`tiaochu`	跳出循环	`break`
循环	`tiaoguo`	跳过本迭代	`continue`
匹配	`pifen`	结构模式匹配	`match`
匹配	`ruguoshi`	匹配分支	`case`
异常	`changshi`	尝试	`try`
异常	`buhuo`	捕获异常	`except`
异常	`zuizong`	最终执行	`finally`
异常	`paochu`	抛出异常	`raise`
上下文	`tuoguan ... wei 变量`	上下文管理器	`with ... as`
入口	`gn 入口()`	程序入口	`main()` + `if __name__`

1.3 特殊方法（汉字 dunder 写法）

JianPy 中定义类协议方法时，用「汉字 + __ 前缀」的写法，编译器自动映射回 Python 的 dunder 方法，由 Python 内置函数/语法隐式触发：

gn 求长度(ben) { fanhui 求长度(ben._数据) }# 由 len() 触发gn __字符串表示(ben) { fanhui f”...{ben._数据}” }# 由 str()/print() 触发

完整对照见第 9.6 节。

注意：早期规范中的拼音写法（chushi、changdu、wenben 等）在当前编译器中未落地，一律不要使用，请使用 __初始、__求长度、__字符串表示 等汉字形式（详见第 16 章）。

第 2 章程序骨架与入口

2.1 最小可运行程序

每个 JianPy 程序以 gn 入口() 为统一入口。编译时自动生成 Python 的 main() 与 if name == "main": 守卫。

gn 入口() {    打印(”你好，JianPy！”)}

编译为 Python：

def main():    print(”你好，JianPy！”)if __name__ == ”__main__”:    main()

2.2 异步入口

入口函数可以是异步的。编译时自动用 asyncio.run(main()) 包装启动。

rangchu gn 入口() {    shu 数据 = dengdai 取数据(”ht....” )    打印(数据)}

编译为 Python：

import asyncioasync def main():    数据 = await 取数据(”ht....”)    print(数据)if __name__ == ”__main__”:    asyncio.run(main())

2.3 文件与运行方式

JianPy 源文件扩展名统一为 .jpy。
运行通道：

编译为 Python 后运行（推荐、可调试）：
```
jian_py.exe 程序.jpy -o 程序.pypython 程序.py
```

严格检查编译（带作用域/常量检查与提示，非零退出码）：
```
jian_py.exe 程序.jpy --debug -o 程序.py
```

Python → JianPy 转换（把现有 Python 代码翻译成 JianPy，用于反向参考）：
```
python py2Jian.py 程序.py -o 程序.jpy
```

建议：先在 .py 里无错地跑通逻辑，再转成 .jpy，可最大限度减少调试成本。

第 3 章大括号与缩进、分号、注释

3.1 大括号界定代码块

JianPy不依赖缩进，用 {} 界定代码块。缩进只用于可读性，不参与语义。

gn 问候(姓名) {    ruguo (姓名) {        打印(”你好，” + 姓名)    } fouze {        打印(”你好，世界”)    }}

3.2 控制流条件用括号包裹

ruguo、zhuge、zhiyao、fouzeruguo 后的条件表达式用小括号()包裹，这是保证优先级与可读性的推荐写法。

ruguo (年龄 >= 18) {    打印(”成年人”)}

函数调用、三元表达式等同样建议随时加括号保护优先级。

3.3 分号可选

语句末尾的 ; 可选；一行可以用 ; 写多条语句。

shu 甲 = 1; shu 乙 = 2; 打印(甲 + 乙)shu 丙 = 3

3.4 注释

只支持 # 注释。
//
是整除运算符，不是注释。别再用 // 写注释，否则会出现难以排查的逻辑错误（见第 16 章）。

# 这是注释shu 商 = 17 // 5# 这是整除，结果是 3

第 4 章变量、常量、数据类型

4.1 可变变量 shu

shu 计数 = 0# 中文变量名shu 姓名 = ”张三”# 字符串shu 分数: int = 95# 类型注解（可选）shu 项目清单 = [”甲”, ”乙”, ”丙”]# 列表# 多变量赋值shu 甲, 乙, 丙 = 1, 2, 3shu 一 = 二 = 三 = 0

元组解包（变量名用括号包裹）：

shu (横, 纵) = (10, 20)shu (姓名, 年龄) = (”李四”, 25)gn 取信息() {    fanhui (”王五”, 30)}shu (姓名, 年龄) = 取信息()

编译为 Python：

(横, 纵) = (10, 20)(姓名, 年龄) = 取信息()

4.2 常量 chang

chang 声明编译期静态只读检查的常量，编译后转换为 Final 类型注解。直接重新赋值会在编译期报错。

chang 最大尺寸 = 100chang API地址 = ”ht....”chang 圆周率 = 3.14159# 以下写法编译期报错（常量不可重新赋值）chang 最大尺寸 = 200# ❌ 错误最大尺寸 = 200# ❌ 错误

说明：Final 只是类型注解，运行时并不真正锁定；globals()["最大尺寸"]=...、setattr、跨模块修改等绕过静态检查的方式仍与普通变量一致。

4.3 数据类型

类型注解保持 Python 原生英文，完全可选：

shu 姓名: str = ”张三”shu 年龄: int = 18shu 分数: float = 95.5shu 是否激活: bool = True# 布尔字面量保持英文shu 数据: None = None# 空值保持英文shu 数字清单: list[int] = [1, 2, 3]shu 成绩表: dict[str, int] = {”甲”: 90, ”乙”: 88}shu 坐标: tuple[int, int] = (10, 20)shu 可选邮箱: str | None = None# 联合类型shu 未知类型对象 ...# 省略号字面量保持英文

类型别名使用英文 type：

type 用户 = dict[str, str | int | None]type 回调类型 = gn (str) bool

集合字面量（用 {} 且元素不是键值对时为集合）：

shu 合法类型 = {'甲', '乙', '丙'}shu 单个元组 = (10,)# 末尾逗号保留，是单元素元组

第 5 章运算符与表达式

5.1 算术运算符

运算符	含义	示例	结果
`+ - * /`	加减乘除	`7 / 2`	`3.5`
`//`	整除	`17 // 5`	`3`
`%`	取余	`17 % 5`	`2`
`**`	幂	`2 ** 10`	`1024`
`@`	矩阵乘（numpy 等）	`矩阵甲 @ 矩阵乙`	矩阵
`=+=-==/=//=%=*=`	赋值/复合赋值	`计数 += 1`	—

shu 商 = 17 // 5# 3shu 余 = 17 % 5# 2shu 幂 = 2 ** 10# 1024shu 总 = 0zhuge (数字 in 范围(5)) {    总 += 数字# 复合赋值}

5.2 比较与逻辑运算符

# 比较：== != < > <= >=，保持英文shu 是否相dengdai = (甲 == 乙)shu 是否包含 = ”张” in ”张三丰”shu 是否同一 = (甲 is 乙)shu 否包含 = 关键字 not in 列表shu 非同一 = (甲 is not 乙)# 逻辑：and / or / not，保持英文shu 结果 = (分数 >= 60) and (出勤率 >= 0.8)shu 反向 = not (甲 > 乙)

5.3 三元表达式

shu 评语 = ”通过” if 分数 >= 90 else ”待定”

坑：三元表达式在比较/拼接等场景要记得整体加括号，避免优先级错误：
shu 上限 = 254 if 条件 else 253shu 合法 = (求长度(列表) > (254 if 条件 else 253))

5.4 运算符优先级

与 Python 一致。括号优先级最高，建议对易混淆的表达式显式加括号：

shu 值 = (1 + 2) * 3# 9，括号优先shu 概率 = 1 / (1 + 数字)# 括号保护

第 6 章函数

6.1 基本函数

gn 相加(甲, 乙) {    fanhui 甲 + 乙}gn 问候(姓名: str, 年龄: int) str {# 参数注解 + 返回类型    fanhui f”你好，{姓名}，你今年{年龄}岁”}gn 记录(消息) {# 无返回，等效返回 None    打印(消息)}

6.2 参数

gn 创建用户(姓名: str, 年龄: int = 18) {# 默认参数    fanhui {”姓名”: 姓名, ”年龄”: 年龄}}gn 求总和(*数字清单) {# 可变参数 *args    shu 总 = 0    zhuge (数字 in 数字清单) {        总 += 数字    }    fanhui 总}gn 展示参数(**关键字参数) {# 关键字参数 **kwargs    zhuge (键, 值 in 关键字参数.items()) {        打印(f”{键}={值}”)    }}shu 用户 = 创建用户(”张三”)# 默认年龄 18shu 总 = 求总和(1, 2, 3, 4, 5)# 15shu 结果 = 函数(1, 2, 模式=”严格”)# 函数调用关键字参数

6.3 匿名函数 wuming

shu 平方 = wuming (数字) { fanhui 数字 * 数字 }打印(平方(5))# 25shu 翻倍 = list(map(wuming (数字) { fanhui 数字 * 2 }, [1, 2, 3]))# [2, 4, 6]

6.4 生成器函数 zanting

gn 计数器(起点, 终点) {    shu 当前 = 起点    zhiyao (当前 <= 终点) {        zanting 当前# 暂停并产出，等效 yield        当前 += 1    }}shu 生成器 = 计数器(1, 3)zhuge (数字 in 生成器) {    打印(数字)# 1, 2, 3}

zanting 从可迭代对应 Python 的 yield from。

6.5 异步函数 rangchu gn / dengdai

rangchu gn 取数据(地址) {    shu 响应 = dengdai 请求(地址)    shu 数据 = dengdai 响应.json()    fanhui 数据}

dengdai
（await）只能在 rangchu gn 内部使用。
rangchu gn 入口()
见第 2.2 节。

6.6 装饰器 @

装饰器语法保持英文 @：

gn 计时(原函数) {    gn 包装(*参数, **关键字) {        shu 开始 = 时间()        shu 结果 = 原函数(*参数, **关键字)        打印(f”耗时 {时间() - 开始} 秒”)        fanhui 结果    }    fanhui 包装}@计时gn 慢函数() {    shu 总 = 0    zhuge (数字 in 范围(1000000)) {        总 += 数字    }    fanhui 总}

第 7 章控制流

7.1 条件 ruguo / fouzeruguo / fouze

shu 年龄 = 20ruguo (年龄 < 13) {    打印(”儿童”)} fouzeruguo (年龄 < 18) {    打印(”青少年”)} fouzeruguo (年龄 < 60) {    打印(”成年人”)} fouze {    打印(”老年人”)}# 单行条件ruguo (是否激活) { 打印(”活跃用户”) }

7.2 遍历循环 zhuge

shu 水果清单 = [”苹果”, ”香蕉”, ”橙子”]zhuge (水果 in 水果清单) {    打印(水果)}zhuge (数字 in 范围(5)) {# 0,1,2,3,4    打印(数字)}shu 用户 = {”姓名”: ”张三”, ”年龄”: 18}zhuge (键, 值 in 用户.items()) {# 遍历字典键值对    打印(f”{键}: {值}”)}zhuge (索引, 水果 in 枚举(水果清单)) {# 带索引    打印(f”{索引}: {水果}”)}

循环变量元组解包（配对遍历）：

shu 配对 = [(1, 2), (3, 4), (5, 6)]zhuge (甲, 乙 in 配对) {    打印(f”甲={甲} 乙={乙}”)}shu 名单 = [”张三”, ”李四”]shu 年龄表 = [20, 25]zhuge (姓名, 年龄 in 拉链(名单, 年龄表)) {    打印(f”{姓名}: {年龄}岁”)}

编译为 Python：

for (甲, 乙) in 配对:    print(f”甲={甲} 乙={乙}”)

7.3 条件循环 zhiyao

shu 计数 = 0zhiyao (计数 < 5) {    打印(计数)    计数 += 1}# 无限循环 + 手动退出zhiyao (True) {    shu 输入 = input(”输入 q 退出: ”)    ruguo (输入 == ”q”) {        tiaochu    }}

7.4 tiaochu / tiaoguo

# tiaochu 跳出整个循环zhuge (数字 in 范围(10)) {    ruguo (数字 == 5) {        tiaochu    }    打印(数字)# 0,1,2,3,4}# tiaoguo 跳过当前这次迭代zhuge (数字 in 范围(10)) {    ruguo (数字 % 2 == 0) {        tiaoguo# 跳过偶数    }    打印(数字)# 1,3,5,7,9}

7.5 循环的 fouze（else）

循环正常走完（未被 tiaochu 打断）时执行 fouze 分支：

zhuge (数字 in 范围(3)) {    打印(数字)} fouze {    打印(”循环正常结束”)# 会执行}zhuge (数字 in 范围(10)) {    ruguo (数字 == 2) {        tiaochu    }    打印(数字)} fouze {    打印(”循环正常结束”)# 不会执行，因为被 tiaochu 打断}

7.6 assert 与 hulue

assert 值 > 0, ”值必须为正”# 断言，保持英文 assertassert 对象 is not None# 空操作（占位），对应 Python 的 passzhuge (数字 in 范围(3)) {    hulue}

第 8 章结构模式匹配

8.1 基本用法 pifen / ruguoshi

对应 Python 3.10+ 的 match/case：

gn 判断类型(值) {    pifen 值 {        ruguoshi int():            fanhui ”整数”        ruguoshi str():            fanhui ”字符串”        ruguoshi list():            fanhui ”列表”        ruguoshi _:            fanhui ”其他”    }}

编译为 Python：

def 判断类型(值):    match 值:        case int():            return ”整数”        case str():            return ”字符串”        case list():            return ”列表”        case _:            return ”其他”

8.2 综合模式示例

支持映射模式、序列模式、通配符、OR 模式、if 守卫dengdai Python 原生模式特性：

gn 处理消息(消息) {    pifen 消息 {        ruguoshi {”类型”: ”文本”, ”内容”: 内容}:            fanhui f”收到文本: {内容}”        ruguoshi {”类型”: ”图片”, ”地址”: 地址}:            fanhui f”加载图片: {地址}”        ruguoshi [”命令”, 命令名, *参数]:            fanhui f”执行命令 {命令名}，参数: {参数}”        ruguoshi _:            fanhui ”未知消息”    }}

语法要点：

pifen 表达式 { ... }
，用大括号包裹所有 ruguoshi 分支。
每个 ruguoshi 模式: 后跟该分支的语句。
通配符用 _；分支体写在 : 之后。

第 9 章类与面向对象

9.1 定义类与构造

sjgnbao 定义类；__初始是构造函数（对应 init）；ben 是当前实例（对应 self）：

sjgnbao 人物 {    gn __初始(ben, 姓名, 年龄) {        ben.姓名 = 姓名        ben.年龄 = 年龄    }    gn 问候(ben) {        fanhui f”你好，我是{ben.姓名}，今年{ben.年龄}岁”    }    gn 庆祝生日(ben) {        ben.年龄 += 1        打印(f”{ben.姓名} 现在 {ben.年龄} 岁了”)    }}shu 一个人 = 人物(”张三”, 18)打印(一个人.问候())

编译为 Python：

class 人物:    def __init__(self, 姓名, 年龄):        self.姓名 = 姓名        self.年龄 = 年龄    def 问候(self):        return f”你好，我是{self.姓名}，今年{self.年龄}岁”

9.2 继承 fuji

sjgnbao 子类(父类) 声明继承；fuji 对应 super()，用来调用父类成员：

sjgnbao 学生(人物) {    gn __初始(ben, 姓名, 年龄, 学校) {        fuji.__初始(姓名, 年龄)# 调用父类构造函数        ben.学校 = 学校    }    gn 学习(ben) {        打印(f”{ben.姓名} 在 {ben.学校} 学习”)    }    gn 问候(ben) {# 重写父类方法        fanhui f”学生{ben.姓名}在{ben.学校}”    }}

9.3 类属性、静态方法、类方法

sjgnbao 计算器 {    PI = 3.14159# 类属性    @staticmethod    gn 相加(甲, 乙) {        fanhui 甲 + 乙    }    @classmethod    gn 创建(cls, 值) {# cls 对应 Python 的 classmethod        fanhui cls(值)    }}打印(计算器.PI)# 3.14159打印(计算器.相加(3, 5))# 8

9.4 属性装饰器 @property / setter

sjgnbao 圆 {    gn __初始(ben, 半径) {        ben._半径 = 半径    }    @property    gn 半径(ben) {        fanhui ben._半径    }    @半径.setter    gn 半径(ben, 值) {        ruguo (值 < 0) {            paochu ValueError(”半径不能为负数”)        }        ben._半径 = 值    }    @property    gn 面积(ben) {        fanhui 3.14159 * ben._半径 ** 2    }}shu 一个圆 = 圆(5)打印(一个圆.面积)# 78.53975（当作属性访问，不是方法）一个圆.半径 = 10# 触发 setter打印(一个圆.面积)# 314.159

9.5 类体内的文档字符串

类体顶部的字符串字面量会被自动当作 docstring 跳过：

sjgnbao 模型 {    ”这是模型的文档字符串”    gn __初始(ben, 配置) {        ben.配置 = 配置    }}

9.6 协议方法（汉字写法）

自定义类可通过实现汉字特殊方法参与 Python 内置机制。方法名以 __ 前缀书写，自动映射回对应 dunder，由内置函数/语法隐式触发：

汉字写法	对应 Python	触发方式
`__初始`	`__init__`	`类()` 构造
`__字符串表示`	`__str__`	`str()` / `print()`
`__官方表示`	`__repr__`	`repr()`
`__求长度`	`__len__`	`len()`
`__取项`	`__getitem__`	`对象[key]`
`__设项`	`__setitem__`	`对象[key] = 值`
`__删项`	`__delitem__`	`del 对象[key]`
`__迭代`	`__iter__`	`iter()` / `zhuge`
`__下一个`	`__next__`	`next()`
`__包含`	`__contains__`	`in`
`__调用`	`__call__`	`对象()`
`__进入`	`__enter__`	`tuoguan`
`__退出`	`__exit__`	`tuoguan`
`__格式`	`__format__`	`format()` / f-string
`__布尔值`	`__bool__`	`bool()` / `ruguo`
`__逆序`	`__reversed__`	`reversed()`
`__绝对值`	`__abs__`	`abs()`
`__散列`	`__hash__`	`hash()`

保持英文的部分：运算符重载（__add__ 等）、比较（__eq__ 等）、描述符、属性钩子（__getattr__）、__new__/__del__、__slots__ 等元编程钩子不要中文化，保持 __xxx__ 原样。

示例：

sjgnbao 自定义列表 {    gn __初始(ben, 初始数据) {        ben._数据 = 初始数据    }    gn __求长度(ben) {        fanhui 求长度(ben._数据)    }    gn __取项(ben, 下标) {        fanhui ben._数据[下标]    }    gn __设项(ben, 下标, 值) {        ben._数据[下标] = 值    }    gn __字符串表示(ben) {        fanhui f”自定义列表{ben._数据}”    }}shu 名单 = 自定义列表([”苹果”, ”香蕉”])打印(求长度(名单))# 2，调用 __求长度打印(名单[1])# 香蕉，调用 __取项打印(str(名单))# 自定义列表['苹果','香蕉']，调用 __字符串表示

编译为 Python：

class 自定义列表:    def __init__(self, 初始数据):        self._数据 = 初始数据    def __len__(self):        return len(self._数据)    def __getitem__(self, 下标):        return self._数据[下标]    def __setitem__(self, 下标, 值):        self._数据[下标] = 值    def __str__(self):        return f”自定义列表{self._数据}”

第 10 章模块系统

10.1 引入模块

引入 math引入 json wei json解析器# 别名 wei 对应 as从 datetime 引入 datetime, timedelta从 os 引入 path wei 路径从 json 引入 dumps, loads

10.2 别名 wei

wei 对应 Python 的 as，用于给引入的模块/名字起别名，也在 buhuo ... wei 变量、tuoguan ... wei 变量中复用（见对应章节）。

引入 numpy wei np从 collections.abc 引入 Iterable wei 可迭代

10.3 相对导入

用点号 . 表示相对层级：1 个点 . 当前包、2 个点 .. 上级包、以此类推：

从 . 引入 助手从 .引擎 引入 Value从 .. 引入 工具从 ..配置 引入 设置从 ... 引入 基础

编译为 Python：

from . import 助手from .引擎 import Valuefrom .. import 工具from ..配置 import 设置from ... import 基础

10.4 点分模块路径

引入 os.path从 os.path 引入 join从 collections.abc 引入 Iterable

10.5 星号导入与引出

从 ... 引入 * 对应 from ... import *，只导入被引出导出的符号：

# 某模块 file_a.jpy 内引出 shu PI = 3.14159引出 gn 计算面积(半径) {    fanhui PI * 半径 ** 2}gn 私有助手(数字) {# 未被引出，from * 时不可见    fanhui 数字 + 1}引出 sjgnbao 公开类 {    ...}

引出语义：

引出
会把对应符号加入模块的 __all__ 列表。
从某模块引入 *
时，只有 引出 过的符号可见。
未被引出的符号仍可通过 引入某模块 后用点号访问。

用法示例：

# 另一个文件引入从 file_a 引入 *# 只得到 PI、计算面积、公开类从 file_a 引入 计算面积, 私有助手# 显式点名也可取到私有符号

第 11 章异常处理

11.1 changshi / buhuo / zuizong / paochu

对应 try / except / finally / raise：

changshi {    shu 数字 = int(input(”输入数字: ”))    shu 结果 = 10 / 数字    打印(f”结果: {结果}”)} buhuo (ZeroDivisionError) {    打印(”错误：不能除以零”)} buhuo (ValueError) {    打印(”错误：请输入有效数字”)} buhuo (错误) {    打印(f”未知错误: {错误}”)} zuizong {    打印(”程序执行完毕”)}

11.2 抛出异常 paochu

gn 除法(甲, 乙) {    ruguo (乙 == 0) {        paochu ZeroDivisionError(”除数不能为零”)    }    fanhui 甲 / 乙}

11.3 多异常捕获

用双层括号捕获多个异常类型：

changshi {    代码()} buhuo ((ValueError, TypeError)) {    打印(”值类型错误”)}

编译为 Python：

try:    代码()except (ValueError, TypeError):    print(”值类型错误”)

buhuo ... wei 变量取得异常实例：

changshi {    代码()} buhuo (ValueError) wei 错误对象 {    打印(错误对象)}

11.4 自定义异常

继承 Exception，用它扩展自定义异常类型：

sjgnbao 业务异常(Exception) {    gn __初始(ben, 消息) {        fuji.__初始(消息)# 调用父类 Exception 构造函数    }}paochu 业务异常(”业务校验未通过”)

第 12 章上下文管理器

12.1 tuoguan ... wei 变量

对应 with ... as；wei 可选（不需要 as 变量时可省略）：

tuoguan open(”文件.txt”, ”r”) wei 文件 {    shu 内容 = 文件.read()    打印(内容)}

编译为 Python：

with open(”文件.txt”, ”r”) as 文件:    内容 = 文件.read()    print(内容)

无as子句（常用于 torch 等）：

tuoguan torch.no_grad() {    张量.复制_(源张量.t())}

12.2 自定义上下文管理器

实现 __进入（enter）与 __退出（exit）：

sjgnbao 文件上下文 {    gn __进入(ben) {        打印(”打开资源”)        fanhui ben# 返回值会成为 wei 后面的变量    }    gn __退出(ben, 异常类型, 异常值, 回溯) {        打印(”关闭资源”)    }}tuoguan 文件上下文() wei 上下文 {    打印(”处理中...”)}

第 13 章推导式与集合

13.1 列表推导式

shu 平方表 = [数字 ** 2 zhuge 数字 in 范围(10)]shu 偶数表 = [数字 zhuge 数字 in 范围(20) if 数字 % 2 == 0]# 多 zhuge 子句shu 配对表 = [甲 + 乙 zhuge 甲 in 范围(3) zhuge 乙 in 范围(3)]# 带条件过滤shu 正数表 = [数字 zhuge 数字 in 原始表 if 数字 > 0]

13.2 推导式中的元组解包

shu 配对 = [(1, 2), (3, 4), (5, 6)]shu 首元表 = [甲 zhuge (甲, 乙) in 配对]# [1, 3, 5]shu 和表 = [甲 + 乙 zhuge (甲, 乙) in 配对]# [3, 7, 11]shu 配置 = {”主机”: ”localhost”, ”端口”: 8080}shu 项表 = [f”{键}={值}” zhuge (键, 值) in 配置.items()]

编译为 Python：

配对 = [(1, 2), (3, 4), (5, 6)]首元表 = [甲 for (甲, 乙) in 配对]和表 = [甲 + 乙 for (甲, 乙) in 配对]

13.3 字典 / 集合推导式

# 字典推导式shu 平方字典 = {数字: 数字 ** 2 zhuge 数字 in 范围(5)}shu 参数字典 = {参数名: 参数 zhuge (参数名, 参数) in 配置表}# 集合推导式shu 平方集合 = {数字 ** 2 zhuge 数字 in 范围(5)}# 集合字面量shu 合法类型 = {'甲', '乙', '丙'}

13.4 生成器表达式

用小括号 () 包裹，惰性求值；可作函数参数：

shu 生成器 = (数字 ** 2 zhuge 数字 in 范围(10))zhuge (值 in 生成器) {    打印(值)}# 生成器表达式作为函数参数shu 总 = 求和(元素.数量() zhuge 元素 in 集合)shu 衰减参数 = [参数 zhuge (名称, 参数) in 参数字典.items() if 参数.维度() >= 2]

第 14 章常用内置函数与中文标识符规范

14.1 中文化内置函数

编译器内置了一批中文名内置函数，可直接使用（也有对应的 Python 英文名，均可）：

中文名	对应 Python	中文名	对应 Python
`打印`	`print`	`求长度`	`len`
`范围`	`range`	`枚举`	`enumerate`
`拉链`	`zip`	`求和`	`sum`
`最小`	`min`	`最大`	`max`
`绝对`	`abs`	`四舍五入`	`round`
`字符`	`chr`	`序数`	`ord`
`十六进制`	`hex`	`八进制`	`oct`
`二进制`	`bin`	`幂`	`pow`
`整除`	`divmod`	`追加` *	`append` *

追加作为方法使用：清单.追加(元素) → list.append(...)。

示例：

打印(求长度([1, 2, 3]))# 3打印(求和(范围(5)))# 10shu 排序索引 = 枚举([”甲”, ”乙”, ”丙”])

熟悉的英文内置函数（print、len、range、sum、sorted、map 等）保持可用，中英混合不冲突。

14.2 中文标识符命名规范

变量名、方法名、函数名、类名优先使用中文，语义直观。
常量名用中文全称即可（规范对自定义标识符不强求大写）。
中文标识符可安全用于：变量赋名、函数/方法名、参数名、f-string 插值、推导式变量、循环变量、类型注解。

shu 本月销售额 = 12800gn 计算税后工资(税前工资, 税率) {    fanhui 税前工资 * (1 - 税率)}shu 编码结果 = 编码器(输入文本)打印(f”本月销售额为 {本月销售额} 元”)

14.3 不可用作标识符的名字（保留词）

以下关键字不能用作变量名、函数名、类名：

gn sjgnbao shu chang fanhui ruguo fouzeruguo fouze zhuge zhiyao tiaochu tiaoguo pifen ruguoshi changshi buhuo zuizong paochu tuoguan wei 引入从引出 ben fuji 入口 hulue wuming zanting rangchu dengdai in

以及上述中文化内置函数名（打印、求长度、范围等）与特殊方法名（__初始等）也不要用作标识符，否则会被分别映射成内置名/特殊方法。

第 15 章 Python 第三方库协作

15.1 无缝使用生态库

JianPy 以 Python 为中间层，运行时语义与 Python 完全一致，NumPy、Pandas、PyTorch、requests、FastAPI 等库可直接用：

引入 numpy wei np从 sklearn.model_selection 引入 train_test_splitshu 矩阵甲 = np.array([[1, 2], [3, 4]])shu 矩阵结果 = 矩阵甲 @ 矩阵甲# 矩阵乘法 @打印(矩阵结果)

15.2 点分路径导入

引入 torch.nn wei nn从 torch.optim 引入 AdamWshu 层 = nn.Linear(768, 768, bias=False)

15.3 继承第三方类（点分路径继承）

引入 torch.nn wei nnsjgnbao 我的模型(nn.Module) {    ”模型文档字符串”    gn __初始(ben, 配置) {        fuji.__初始()        ben.线性层 = nn.Linear(配置.嵌入维度, 配置.嵌入维度)    }    gn forward(ben, 输入) {# PyTorch 前向方法        fanhui ben.线性层(输入)    }}

编译为 Python：

import torch.nn as nnclass 我的模型(nn.Module):    def __init__(self, 配置):        super().__init__()        self.线性层 = nn.Linear(配置.嵌入维度, 配置.嵌入维度)    def forward(self, 输入):        return self.线性层(输入)

提示：第三方库内部的 .py 文件是直接复制使用、不经过 JianPy 语法转换的，所以完全不用担心生态兼容性。

第 16 章常见问题排查与"过时写法"对照表

16.1 老教程过时写法 → 正确写法

早期教程（职场小白版/中学生版）沿用旧式写法，不要照抄。下表给出正确写法：

过时写法	正确写法	说明
`如果 (条件) { ... } 否则 { ... }`	`ruguo (条件) { ... } fouze { ... }`	旧"中文"条件词已改为拼音
`逐个 (x in 清单)`	`zhuge (x in 清单)`	旧循环词改为拼音
`只要 (条件)`	`zhiyao (条件)`	改拼音
`数据 x = 1`	`shu x = 1`	旧"数据"改为 `shu`
`常量数据税率 = 0.13`	`chang 税率 = 0.13`	旧写法改 `chang`
`功能 f() {}`	`gn f() {}`	旧写法改 `gn`
`数据功能包类 {}`	`sjgnbao 类 {}`	旧写法改 `sjgnbao`
`返回值`	`fanhui 值`	旧写法改 `fanhui`
`跳出` / `跳过`	`tiaochu` / `tiaoguo`	旧写法改拼音
`父级.初始化()`	`fuji.__初始(...)`	结合下条
`__初始` （部分旧教程遗漏）	`__初始`	构造方法统一用汉字 `__初始`
直接写 `if/elif/else/for/while`	`ruguo/fouzeruguo/fouze/zhuge/zhiyao`	英文控制流已改拼音（也会收到提示）
`if (__name__ == '__main__')`	无需手写	编译器为 `入口()` 自动生成

16.2 命名冲突：拼音 vs 汉字特殊方法（重点）

你可能会写	是否可用	正确写法
`gn chushi(ben, ...)`	❌ 不能用	`gn __初始(ben, ...)`
`gn changdu(ben)`	❌ 不能用	`gn __求长度(ben)`
`gn wenben(ben)`	❌ 不能用	`gn __字符串表示(ben)`
`gn diedai(ben)`	❌ 不能用	`gn __迭代(ben)`

原因：规范文档曾给出拼音协议方法（chushi/changdu/wenben/…），但当前编译器尚未实现。请一律使用汉字 __xxx 形式，它们经过实测可运行。

16.3 常见报错与解决

现象	原因	解决
`类() takes no arguments`	构造函数没写对（用了拼音 `chushi`）	用 `__初始`
除法结果不对 / 该整除却出现小数	把 `//` 当注释、误用 `/`	`//` 是整除运算符
`期望声明，但得到 '='`	`引出 x = 1` 少了声明词	写 `引出 shu x = 1`
中文字符在 f-string 里报错	少数早期编译器版本有 bug	用当前 release 版本重建后即可
三元表达式优先级错误	未加括号	`(a if 条件 else b)` 整体加括号
`if/elif/else` 被提示改用拼音	习惯检测建议	确实应改 `ruguo/fouzeruguo/fouze`

16.4 排查建议

先在 .py 里把逻辑跑通，再由 py2Jian 转成 .jpy，能定位绝大多数"写法错误"。
编译用 --debug 严格模式，能同时获得作用域、常量、控制流合法性检查，出错时返回非零退出码。
转换后运行，规范化输出与原始 .py 对比，确认语义一致。

第 17 章编译器当前实现边界

依据 jpy语法规范.md 第 19 章「编译器实现状态」整理。凡标注差异的，以实测/当前二进制为准。

17.1 已实现（可放心使用）

类别	已支持范围
函数 `gn`	参数、默认值、`args`/`*kwargs`、异步、嵌套函数、返回值
类 `sjgnbao`	继承（含点分路径 `nn.Module`）、方法、类属性/静态/类方法、@property、docstring 跳过
变量 `shu`	类型注解、元组解包 `shu (x,y)=...`、属性/下标解包赋值
常量 `chang`	编译期只读检查
导入	相对导入（`.`/`..`/`...`）、点分路径、别名 `wei`、关键词作导入项
星号导入	`从模块引入 *` （配合 `引出`）
`引出`	`引出 gn/sjgnbao/shu` → 生成声明 + `__all__`
控制流	`ruguo/fouzeruguo/fouze` 、`zhuge`（含元组解包、循环 else）、`zhiyao`、`tiaochu/tiaoguo`
匹配	`pifen/ruguoshi` （结构模式匹配）
异常	顶层 try、多异常元组捕获 `buhuo ((A,B))`、`buhuo ... wei var`、`paochu`
上下文	`tuoguan` （有/无 `wei`）、自定义 `__进入/__退出`
函数特性	`fanhui` 、`dengdai`(await)、`zanting`(yield / yield from)、`wuming`(lambda)、装饰器 `@`
推导式	列表/字典/集合推导式（多 zhuge、if、元组解包）、生成器表达式（可作函数参数）
运算符	三元表达式、`not in`/`is not`、`@`矩阵乘、`//`整除、复合赋值、括号保优先级
特殊方法	汉字形式全表（`__初始`、`__求长度`、`__字符串表示` 等，见第 9.6 节）
其他	中文内置函数（`打印/求长度/范围/...`）、`类型`/`type` 别名、`assert`、`del`、`global`、`waiceng`(nonlocal)、字典/单元素元组、切片、f-string（含 `ben→self` 替换与格式化说明符）、科学计数法、省略号 `...`
入口	`gn 入口()` （含异步）自动生成 `main()` + `if __name__`

17.2 差异与说明

项目	状态	说明
拼音协议方法（`chushi`/`changdu`/`wenben`/…）	未落地	规范曾列拼音 dunder 名，但当前二进制未实现；一律用汉字 `__xxx`
注释	仅 `#`	`//` 是整除，不是注释
布尔/空值	保持英文	`True` /`False`/`None` 不翻译
逻辑运算符	保持英文	`and` /`or`/`not` 不翻译

17.3 批量验证数据

截至规范记录：347 个文件（g4f、nanoGPT、TF2-RL、单元测试等）零错误编译，覆盖模型前向/反向/训练收敛、相对导入、点分继承、生成器表达式、多维切片、嵌套解包等场景。本手册示例均经 py2Jian → jian_py --debug 回环验证后写入。

第 18 章附：JianPy ↔ Python 全量翻译对照速查表

18.1 关键字速查

JianPy	Python	说明
`gn f() {}`	`def f():`	函数
`sjgnbao C {}`	`class C:`	类
`shu x = 1`	`x = 1`	变量
`chang X = 1`	`X: Final = 1`	常量
`fanhui x`	`return x`	返回
`引入 m`	`import m`	导入
`从 m 引入 f`	`from m import f`	从导入
`引入 m wei 别名` / `从 m 引入 f wei g`	`import m as 别名` / `from m import f as g`	别名
`引出`	`__all__`	导出
`ben`	`self`	实例
`fuji`	`super()`	父类
`ruguo` / `fouzeruguo` / `fouze`	`if` / `elif` / `else`	条件
`zhuge` / `zhiyao`	`for` / `while`	循环
`tiaochu` / `tiaoguo`	`break` / `continue`	跳转
`pifen` / `ruguoshi`	`match` / `case`	匹配
`changshi` / `buhuo` / `zuizong` / `paochu`	`try` / `except` / `finally` / `raise`	异常
`tuoguan ... wei 变量`	`with ... as 变量`	上下文
`rangchu gn` / `dengdai`	`async def` / `await`	异步
`zanting` / `zanting 从`	`yield` / `yield from`	生成器
`wuming (x) { }`	`lambda x: ...`	匿名函数
`hulue`	`pass`	空操作
`gn 入口()`	`main()` + `if __name__`	入口

18.2 特殊方法速查

JianPy	Python	触发
`__初始`	`__init__`	构造
`__字符串表示` / `__官方表示`	`__str__` / `__repr__`	`str()` / `repr()`
`__求长度`	`__len__`	`len()`
`__取项` / `__设项` / `__删项`	`__getitem__` / `__setitem__` / `__delitem__`	`obj[key]` dengdai
`__迭代` / `__下一个`	`__iter__` / `__next__`	`iter()` / `next()`
`__包含`	`__contains__`	`in`
`__调用`	`__call__`	`obj()`
`__进入` / `__退出`	`__enter__` / `__exit__`	`tuoguan`
`__格式` / `__布尔值`	`__format__` / `__bool__`	`format()` / `bool()`
`__逆序` / `__绝对值` / `__散列`	`__reversed__` / `__abs__` / `__hash__`	`reversed()` / `abs()` / `hash()`

18.3 中文内置函数速查

JianPy	Python	JianPy	Python
`打印`	`print`	`求长度`	`len`
`范围`	`range`	`枚举`	`enumerate`
`拉链`	`zip`	`求和`	`sum`
`最小` / `最大`	`min` / `max`	`绝对`	`abs`
`四舍五入`	`round`	`字符` / `序数`	`chr` / `ord`
`十六进制` / `八进制` / `二进制`	`hex` / `oct` / `bin`	`幂` / `整除`	`pow` / `divmod`
`清单.追加(x)`	`list.append(x)`	—	—

18.4 常用完整示例

从 datetime 引入 datetime引入 json wei json解析器sjgnbao 用户管理 {    gn __初始(ben) {        ben._用户表 = []    }    gn 添加(ben, 姓名: str, 年龄: int) {        ben._用户表.append({”姓名”: 姓名, ”年龄”: 年龄})    }    gn 查找(ben, 姓名: str) {        zhuge (用户 in ben._用户表) {            ruguo (用户[”姓名”] == 姓名) {                fanhui 用户            }        }        fanhui None    }}gn 入口() {    shu 管理 = 用户管理()    管理.添加(”张三”, 25)    管理.添加(”李四”, 30)    shu 目标 = 管理.查找(”张三”)    ruguo (目标) {        打印(f”找到: {目标}”)    } fouze {        打印(”不存在”)    }}

JianPy 技术文档（正式查询手册）

目录

第 1 章 文档说明与术语总表

1.1 核心原则（记住三句话）

1.2 完整拼音关键词速查表

1.3 特殊方法（汉字 dunder 写法）

第 2 章 程序骨架与入口

2.1 最小可运行程序

2.2 异步入口

2.3 文件与运行方式

第 3 章 大括号与缩进、分号、注释

3.1 大括号界定代码块

3.2 控制流条件用括号包裹

3.3 分号可选

3.4 注释

第 4 章 变量、常量、数据类型

4.1 可变变量 shu

4.2 常量 chang

4.3 数据类型

第 5 章 运算符与表达式

5.1 算术运算符

5.2 比较与逻辑运算符

5.3 三元表达式

5.4 运算符优先级

第 6 章 函数

6.1 基本函数

6.2 参数

6.3 匿名函数 wuming

6.4 生成器函数 zanting

6.5 异步函数 rangchu gn / dengdai

6.6 装饰器 @

第 7 章 控制流

7.1 条件 ruguo / fouzeruguo / fouze

7.2 遍历循环 zhuge

7.3 条件循环 zhiyao

7.4 tiaochu / tiaoguo

7.5 循环的 fouze（else）

7.6 assert 与 hulue

第 8 章 结构模式匹配

8.1 基本用法 pifen / ruguoshi

8.2 综合模式示例

第 9 章 类与面向对象

9.1 定义类与构造

9.2 继承 fuji

9.3 类属性、静态方法、类方法

9.4 属性装饰器 @property / setter

9.5 类体内的文档字符串

9.6 协议方法（汉字写法）

第 10 章 模块系统

10.1 引入模块

10.2 别名 wei

10.3 相对导入

10.4 点分模块路径

10.5 星号导入与 引出

第 11 章 异常处理

11.1 changshi / buhuo / zuizong / paochu

11.2 抛出异常 paochu

11.3 多异常捕获

11.4 自定义异常

第 12 章 上下文管理器

12.1 tuoguan ... wei 变量

12.2 自定义上下文管理器

第 13 章 推导式与集合

13.1 列表推导式

13.2 推导式中的元组解包

13.3 字典 / 集合推导式

13.4 生成器表达式

第 14 章 常用内置函数与中文标识符规范

14.1 中文化内置函数

14.2 中文标识符命名规范

14.3 不可用作标识符的名字（保留词）

第 15 章 Python 第三方库协作

15.1 无缝使用生态库

15.2 点分路径导入

15.3 继承第三方类（点分路径继承）

第 16 章 常见问题排查与"过时写法"对照表

16.1 老教程过时写法 → 正确写法

16.2 命名冲突：拼音 vs 汉字特殊方法（重点）

16.3 常见报错与解决

16.4 排查建议

第 1 章文档说明与术语总表

第 2 章程序骨架与入口

第 3 章大括号与缩进、分号、注释

第 4 章变量、常量、数据类型

第 5 章运算符与表达式

第 6 章函数

第 7 章控制流

第 8 章结构模式匹配

第 9 章类与面向对象

第 10 章模块系统

10.5 星号导入与引出

第 11 章异常处理

第 12 章上下文管理器

第 13 章推导式与集合

第 14 章常用内置函数与中文标识符规范

第 16 章常见问题排查与"过时写法"对照表

第 17 章编译器当前实现边界

第 18 章附：JianPy ↔ Python 全量翻译对照速查表