中文大战代码

用户手册 ​

面向使用者。开发者/接手者请看 项目仓库；每个决策的来龙去脉在 项目仓库。 版本：0.1.1（基于 CPython 3.14.7 fork）—— 本手册与手里的包不一致时，以包里 python --build-info 打出来的为准。

1. 这是什么 ​

一个说中文的 Python：

  • 中文关键字（如果/类型/对于…）与英文关键字并列，中英可以混写；
  • 标准库有中文 API（操作系统、并行.futures、多进程、正则、压缩包…），且英文原名一个不少（中英名指向同一对象）；
  • 报错文案是中文（显示层），但 str(e)、e.args、type(e).__name__ 一律是英文 —— 第三方库、except ValueError、日志、pickle 全不受影响；
  • 报错显示层三档（环境变量 CHINESEPYTHON_ERRORS）：zh（默认，中文）/ en（100% 还原英文）/ both（中英并排，校对用）；没设或写错都当 zh。

2. 怎么跑（绿色目录） ​

powershell
# 解释器
Python\PCbuild\amd64\python.exe

# 官方示例（中英混写、关键字、异常、并发）
Python\PCbuild\amd64\python.exe examples\五分钟上手.py
Python\PCbuild\amd64\python.exe examples\能力演示.py
Python\PCbuild\amd64\python.exe examples\能力全景.py

发行形态是「绿色目录」：python.exe + Lib\ + Doc\html\（官方英文 HTML 文档，每页顶部加了一条中文横幅，另有一页 中文入口.html：中文关键字全表 + 中文库名 → 官方文档页）+ 启动.cmd + 本手册；不写注册表、不改 PATH（要加 PATH 自己把 Python\PCbuild\amd64 加进去）。发行时另有两个单文件 exe（不在 zip 里）：ChinesePython.exe（便携解释器，单文件.exe 脚本.py 直接用；首次运行解包到 %LOCALAPPDATA%\ChinesePython\，之后走缓存）与 ChinesePython-install.exe（自解压到自己目录并跑一遍包内自检）。

3. 中文关键字全表（硬 35 + 软 3） ​

硬关键字（与英文同号、可混写）：

英文中文英文中文英文中文
if如果elif否则如果else否则
while每当for对于break跳出
continue跳过class类型def定义
lambda匿名函数return返回yield产出
pass略过del删除assert断言
global全局nonlocal非局部try尝试
except捕获finally最终必须raise抛出
import导入from来自as作为
with使用True真值False假值
None空值and并且or或者
not并非in属于is等同
async异步await等待

软关键字（只在特定语法位置生效，平时可以当普通名字）：match→匹配、case→情形、type→类型别名。

⚠ 关键字与「名字」是两层：class（关键字）译作类型；但库里一个普通名字叫 CLASS 时译作类（例如 symtable.CLASS 表示「类作用域」）—— 关键字只在小写 token 层生效，名字走各自的词表。

4. 内置名 / 异常 / 方法名的中文别名 ​

除了关键字，还有一层中文别名（英文名照旧）：

  • 内置名 74 个（如 print→打印、len→长度…）；内置异常 72 个（如 ValueError→值错误）；
  • 形参名 258 个、内置方法名 245 个、模块异常名 183 个。 完整对照（含反向索引）见 项目仓库（由编译器表自动生成，不是手抄）。

5. 标准库中文 API 怎么用 ​

python
导入 操作系统 作为 操        # 也写作 import os
导入 并行.futures 作为 并行   # concurrent.futures
导入 多进程                 # multiprocessing

打印(操.取当前目录())
对于 项 属于 操.遍历目录("."):
    打印(项)
使用 并行.线程池执行器(2) 作为 池:
    ...
  • 已铺 157 个库（112 单文件模块 + 25 包 + 20 包装层）；
  • 英文原名一直能用（中英名是同一对象），所以老代码一行不用改。

6. ⚠ 只翻了一部分的库（诚实清单） ​

库没翻的部分
套接字（socket）零散常量留英文（族常量按语义翻了：地址族_INET、协议_TCP 等）
C类型（ctypes）wintypes 只翻教学常用的一批；其余 P*/LP* 指针别名留英文
安全套接字（ssl）上百个协议常量留待后续
多进程（multiprocessing）_multiprocessing 那边 import 进来的 C 类型（SemLock 等）留英文
类型注解（typing）/ 平台信息（platform）整模块薄壳：中文名是别名（同一对象），typing 覆盖 __all__ 全部 105 个、platform 23 个；官方用例照英文原样跑（不换名）—— 这两个库的用例通篇按模块名自证 / 直接给真模块打补丁
导入机制（importlib）薄壳包：中文名是别名（跟英文名同一个对象），共 94 个 —— 包级 3 个 + 子模块内部名 91 个（导入机制.工具.规格自路径、导入机制.机械.源文件加载器、导入机制.元数据.取版本、导入机制.资源.读取器.文件读取器 …）；私有子模块（_abc、metadata/_*、resources/_*）没有中文名，只有英文名的身份别名
异步IO（asyncio）薄壳：中文名是别名（指向英文那份同一对象），包级可用 71 个；子模块内部名（如 Lock.acquire）不在包级别名里
单元测试（unittest）子类覆盖点（setUp/tearDown/run/addSuccess/loadTestsFrom*… 共 51 个）留英文 —— 改了定义名，子类按英文名写的覆盖就失效；中文可用的是类名、模块级函数与 55 个 断言* 助手
其余以 项目仓库 每行的备注为准

7. 未铺的库（28 个已否决，都有决策号与证据） ​

常见几类（完整见 项目仓库）：

  • 启动期/进程级耦合：site、warnings、codecs、encodings、_collections_abc；
  • 自我描述型：typing；
  • 跨进程/验证台限制：multiprocessing（已收，但走专门机制）、dbm（Windows 无 C 扩展）；
  • GUI/环境：tkinter（用例在桌面会话里不可行）；
  • 带非 .py 数据的包：ensurepip、venv —— 相关记录 已撤销否决并入册（生成器现在会同步非 .py 数据；官方用例 32/32 与 42/42 全过）⇒ 36 个降为 34 个；相关记录 再修正为 33 个；相关记录/相关记录/相关记录 收走 unittest/asyncio/importlib ⇒ 30 个；
  • 薄再导层/彩蛋/废弃层：compression、antigravity、this、sre_*。 这些库英文版照常可用（它们没被替换，只是没有中文 API）。

还有一类：没有 Lib/ 文件的内置模块（71 个） ​

有些模块编在解释器本体里，磁盘上根本没有对应文件（实测它们的 __file__ 都是 None）—— 这类没法「复制文件再改名」， 我们已给其中 4 个铺了中文名（数学、时间、垃圾回收、ZLIB压缩），其余按用户需要跳过：

  • sys（解释器自己的接口）：暂不中文化。它是地基（我们 133 个中文名模块里 69 个内部都在用它）， 而用户代码真正会碰的只有几个成员 ⇒ 照英文写就好：
python
import sys
print(sys.version)      # 解释器版本字符串
print(sys.executable)   # 这个解释器是哪个 exe / 可执行文件
print(sys.argv)         # 命令行参数；脚本名在第 0 个

常用还有：sys.path（导入路径，装包/找不到模块时先看它）、sys.stdout / sys.stderr（输出与重定向）、 sys.exit(码)（结束程序）、sys.platform、sys.version_info、sys.maxsize、sys.getrecursionlimit()。 中文名将来可能加（最省的一条是给 sys 做「一行身份别名」，让它与英文那份是同一个模块对象），但现在不做。

  • atexit / errno / marshal：不铺 —— 用户向的文档与示例里 0 次使用；errno 的正常用法是 OSError.errno（属性）， marshal 是 .pyc 内部件。
  • 其余 63 个是地基件、内部加速件、平台件（nt/msvcrt/winreg）与调试件 —— 用户不用，跳过； 完整清单与定性见项目仓库 的附录。

8. 已知差异与限制 ​

  1. pickle 协议 <4 写不了中文模块名：用协议 4/5（pickle.HIGHEST_PROTOCOL 即可）——套接字/路径库/C类型/多进程 都有这一条；
  2. 少数 repr / __all__ 项目仓库；
  3. 第三方库（pip 装的）仍是英文，与中文标准库共存无冲突；
  4. str(e) 是英文（有意的：保证与第三方/日志/pickle 兼容）。

9. 怎么切回英文 ​

  • 报错文案：CHINESEPYTHON_ERRORS 三档 —— zh（默认）/ en（显示层完全还原英文）/ both（中英并排：校对、或排查「是显示层的问题还是别处」时最好用）；没设或写错都当 zh（判据在 Python/Lib/zh_traceback.py:27-35）；
  • 代码：直接用英文原名（import os、os.walk）——一直有效；
  • 想知道某名字的中英对照：查 项目仓库 或 项目仓库。

10. 这个解释器是哪一份？（--build-info） ​

同一个版本号下可能有字节不同的两份（比如引擎里那份旧的）—— 所以「哪一份」不能只看版本号：

python --build-info

打印四类东西：身份（base-3.14.7 到现在全量改动文件的内容联合哈希，唯一排除物是生成物自身）、python314.dll 的 SHA-256（当场实测，与生成时并排）、两个仓的 HEAD（生成时快照）、生成器/词表哈希与预装 pip 版本。第一行是人类可读的一句话。

换过 dll 会当场显示 [不一致（这个 dll 不是生成时那个！）] —— 这正是「同版本号的第二份」露馅的地方。身份数据由 tools\生成构建信息.py 生成（--检查 只查不改）。

11. 许可与来源 ​

  • 基于 CPython 3.14.7 fork：保留上游 PSF LICENSE（见 Python\LICENSE）；
  • 本项目自身许可：MIT（发行时随包附 LICENSE）；
  • 上游：https://github.com/python/cpython

12. 常见问题 ​

Q：为什么异常类名还是英文？ A：type(e).__name__ 保持英文是铁律（见 项目仓库 §1 红线 #2/#3）：中文只在显示层，可被 CHINESEPYTHON_ERRORS=en 完全还原（both 则中英并排给校对看）；这样 except ValueError、第三方库、str(e) 全不受影响。 Q：为什么有的模块是中文名、有的还是英文？ A：中文名是多出来的一份（操作系统 与 os 是同一个模块对象）；没铺的库（见 §7）只有英文名。 Q：类 能当变量名吗？ A：能（它不是关键字）；但 类型 不能（它就是 class）。

以 MIT / Apache-2.0 等宽松许可发布 · 联系作者 QQ：1396257961

Copyright © 2026 YoloLogic（张永乐）