# ZnPy

**Repository Path**: xnors/znpy

## Basic Information

- **Project Name**: ZnPy
- **Description**: 将 Python 报错信息翻译为中文，专为 Python 初学者设计。支持脚本运行、交互式 Shell 以及所有 Python 标准选项（-c、-m`等），兼容 pip 安装。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Znpy — 中文 Python 错误信息工具

> 归属于: [https://gitee.com/xnors](https://gitee.com/xnors)

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

## 安装

```bash
# 通过 pip 安装
pip install znpy

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

## 快速开始

### 运行 Python 脚本，中文报错

```bash
znpy main.py
```

### 进入交互式 Shell

```bash
znpy
```

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

### 执行单行命令

```bash
znpy -c "1/0"
```

### 作为模块运行

```bash
znpy -m http.server 8000
```

## 示例

### 运行脚本错误

```bash
znpy test.py
```

输出:

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

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

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

### Shell 交互

支持方向键浏览命令历史、移动光标，提供流畅的交互体验。

```bash
$ 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` 文件，定义以下变量即可添加自定义翻译:

```python
# ~/.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          # 扩展加载器
```

## 构建与发布

```bash
# 安装构建依赖
uv pip install build

# 构建分发包
python -m build

# 发布到 PyPI
twine upload dist/*
```

## 开源协议

MIT