znpy 0.2.0

中文 Python 错误信息工具 - 将 Python 错误信息翻译为中文

Znpy — 中文 Python 错误信息工具

归属于: https://gitee.com/xnors

将 Python 报错信息翻译为中文，专为 Python 初学者设计。支持脚本运行、交互式 Shell 以及所有 Python 标准选项（-c、-m 等），兼容 pip 安装。

安装

# 通过 pip 安装
pip install znpy

# 通过 uv 全局安装
uv tool install znpy

快速开始

运行 Python 脚本，中文报错

znpy main.py

进入交互式 Shell

znpy

在 Shell 中输入的代码如果报错，将显示中文翻译。

执行单行命令

znpy -c "1/0"

作为模块运行

znpy -m http.server 8000

示例

运行脚本错误

znpy test.py

输出:

==================================================
  中文错误报告 (Chinese Error Report)
==================================================

  文件: test.py
  行号: 2
  位置: 函数 divide
  代码: return a / b

--------------------------------------------------
  ❌ 除零错误: division by zero
--------------------------------------------------

Shell 交互

$ znpy
==================================================
  Znpy - 中文 Python Shell
  输入 Python 代码，错误信息将以中文显示
  输入 exit() 或 Ctrl+Z 退出
==================================================

Python 3.13.3 ... on win32
(ChineseConsole)
>>> print(undefined_var)
==================================================
  中文错误报告 (Chinese Error Report)
==================================================

  文件: <console>
  行号: 1
  位置: 顶层模块
  代码: print(undefined_var)

--------------------------------------------------
  ❌ 名称错误: name 'undefined_var' is not defined
--------------------------------------------------

翻译覆盖范围

• 70+ 内置异常类型中文名称（NameError → 名称错误、ZeroDivisionError → 除零错误 等）
• 120+ 常见错误消息中文翻译（通过正则匹配）
• 原始堆栈跟踪文本中文翻译（Traceback (most recent call last): → 堆栈跟踪（最近一次调用最后）：、File "...", line N, in func → 文件: "...", 第 N 行, 位于 func 等）
• 堆栈跟踪（Traceback）完整中文格式化
• 语法错误（SyntaxError）详细中文展示

扩展翻译

在 ~/.znpy/extensions/ 目录下创建 .py 文件，定义以下变量即可添加自定义翻译:

# ~/.znpy/extensions/my_ext.py

# 自定义异常中文名
EXCEPTION_ZH = {
    "MyCustomError": "我的自定义错误",
}

# 自定义错误消息模板 (支持 {msg} 占位符)
EXCEPTION_TEMPLATES = {
    "MyCustomError": "自定义错误: {msg}",
}

# 自定义正则翻译模式
PATTERNS = [
    (r"my (.+) pattern", "我的 {0} 模式"),
]

项目结构

znpy/
├── pyproject.toml              # 项目构建配置 (hatchling)
├── src/
│   └── znpy/
│       ├── __init__.py         # 包入口
│       ├── __main__.py         # CLI 入口
│       ├── runner.py           # 脚本/模块执行引擎
│       ├── shell.py            # 交互式 Shell
│       ├── translator.py       # 翻译核心引擎
│       └── errors/
│           ├── __init__.py
│           ├── builtins.py     # 内置异常中文名 + 模板
│           ├── common.py       # 常见错误消息正则匹配
│           └── ext.py          # 扩展加载器

构建与发布

# 安装构建依赖
uv pip install build

# 构建分发包
python -m build

# 发布到 PyPI
twine upload dist/*

开源协议

MIT