Metadata-Version: 2.4
Name: znpy
Version: 0.2.1
Summary: 中文 Python 错误信息工具 - 将 Python 错误信息翻译为中文
Project-URL: Repository, https://gitee.com/xnors/znpy
Author: Znpy
License: MIT
Keywords: chinese,error,python,translation,znpy
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: System :: Shells
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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
