# 易语言风格 Python 编码规范

## 目标

本规范用于约束一种“易语言风格”的 Python 编码方式：用中文表达程序意图，用接近自然语言的函数名、变量名和注释降低阅读门槛，同时遵守 Python 语法、PEP8 格式和基本工程质量要求。

这种风格不是简单把英文 API 翻译成中文，而是让代码像中文命令一样直接表达“做什么”。

核心目标：

- 代码可运行，符合 Python 语法
- 命名中文化，语义清晰
- 函数职责单一，像“命令”一样可组合
- 注释解释意图和边界，不重复代码
- 格式遵循 PEP8，便于工具格式化和维护
- 尽量使用标准库实现通用能力

## 总体风格

易语言风格代码强调“读代码像读中文说明”。

推荐：

```python
import uuid


def 取UUID() -> str:
    """生成一个随机 UUID（文本形式）。"""
    return str(uuid.uuid4())
```

不推荐：

```python
def get_uuid():
    return uuid.uuid4()
```

如果代码主要服务中文风格训练或中文使用者，优先使用中文命名；如果必须调用第三方库或系统 API，保留原始英文 API 名称，只在自定义封装层使用中文命名。

## 命名规范

### 函数命名

函数名应表达一个明确动作，通常采用“动词 + 对象”结构。

推荐形式：

- `取UUID`
- `取时间戳`
- `生成随机字符串`
- `读取JSON文件`
- `写入文本文件`
- `计算MD5`
- `文本_取左边`
- `文本_取右边`
- `文本_取中间`
- `文件_是否存在`
- `路径_拼接`
- `异常_转中文提示`

常用动词约定：

- `取`：获取已有值或即时计算值，如 `取时间戳`
- `生成`：创建新值，如 `生成随机字符串`
- `读取`：从文件、网络、配置中取数据，如 `读取JSON文件`
- `写入`：把数据保存到外部位置，如 `写入文本文件`
- `转换` / `到`：类型转换，如 `文本到字节集`
- `判断` / `是否`：返回布尔值，如 `文件_是否存在`
- `计算`：摘要、统计、数值结果，如 `计算SHA256`
- `删除`：移除内容，如 `文本_删左边`
- `查找` / `寻找`：定位内容，如 `寻找文本`

### 变量命名

变量名应使用中文名词或名词短语，表达数据含义。

推荐：

```python
文件路径 = "config.json"
文本内容 = "你好世界"
哈希对象 = hashlib.md5()
当前时间 = datetime.datetime.now()
随机文本 = 生成随机字符串(16)
```

避免：

```python
a = "config.json"
txt = "你好世界"
hash_obj = hashlib.md5()
```

允许在非常局部的循环中使用短变量，但更推荐中文语义变量：

```python
for 序号, 项目 in enumerate(项目列表, start=1):
    print(序号, 项目)
```

### 类命名

类名使用中文名词，表达对象或工具集合。

推荐：

- `文本工具`
- `文件工具`
- `配置读取器`
- `异常处理器`
- `日期时间工具`

类中方法仍使用动词结构：

```python
class 文本工具:
    def 取左边(self, 文本: str, 长度: int) -> str:
        return 文本[:长度]
```

### 常量命名

常量使用清晰中文名，优先保持统一。

```python
默认编码 = "utf-8"
最大重试次数 = 3
请求超时时间 = 10
```

如果项目已有英文大写常量风格，可以保留：

```python
DEFAULT_ENCODING = "utf-8"
```

## 模块组织

一个文件应围绕一个主题组织。

推荐模块主题：

- 文本操作
- 文件操作
- 路径操作
- 编码解码
- JSON 操作
- 时间日期
- 哈希摘要
- 随机数据
- 异常处理
- 网络请求
- 配置读取

文件内部推荐顺序：

1. 标准库导入
2. 第三方库导入
3. 常量定义
4. 工具函数
5. 类定义
6. `if __name__ == "__main__":` 示例或测试入口

示例：

```python
import json
from pathlib import Path


默认编码 = "utf-8"


def 读取JSON文件(文件路径: str):
    """读取 JSON 文件并返回解析后的对象。"""
    with open(文件路径, "r", encoding=默认编码) as 文件对象:
        return json.load(文件对象)


def 写入JSON文件(文件路径: str, 数据) -> None:
    """将对象写入 JSON 文件。"""
    Path(文件路径).parent.mkdir(parents=True, exist_ok=True)
    with open(文件路径, "w", encoding=默认编码) as 文件对象:
        json.dump(数据, 文件对象, ensure_ascii=False, indent=4)
```

## 函数设计规范

函数应短小、明确、可复用。

要求：

- 一个函数只做一件事
- 函数名能说明用途
- 参数名使用中文，必要时加类型注解
- 返回值类型尽量稳定
- 不在工具函数里随意 `print`，除非函数职责就是输出
- 不在函数里吞掉异常后返回含糊结果，除非函数名明确表达“安全”或“尝试”

推荐：

```python
def 文本_取左边(文本: str, 长度: int) -> str:
    """从左侧取指定长度的文本。"""
    if 长度 <= 0:
        return ""
    return 文本[:长度]
```

不推荐：

```python
def 处理(a, b):
    print(a[:b])
```

## 注释和文档字符串

注释使用中文，解释“为什么这样做”或“边界条件”，不要重复代码本身。

推荐 docstring：

```python
import hashlib


def 计算MD5(文本内容: str) -> str:
    """计算文本内容的 MD5 十六进制摘要。"""
    哈希对象 = hashlib.md5()
    哈希对象.update(文本内容.encode("utf-8"))
    return 哈希对象.hexdigest()
```

复杂函数可以写参数说明：

```python
def 生成随机字符串(长度: int, 包含数字: bool = True) -> str:
    """
    生成指定长度的随机字符串。

    参数:
        长度: 生成字符串的字符数量。
        包含数字: 是否允许结果中出现数字。
    """
```

避免无意义注释：

```python
# 返回结果
return 结果
```

## 异常处理规范

默认让异常自然抛出，除非有明确的中文化、重试、默认值需求。

推荐显式异常：

```python
def 读取文本文件(文件路径: str, 编码: str = "utf-8") -> str:
    """读取文本文件内容。"""
    with open(文件路径, "r", encoding=编码) as 文件对象:
        return 文件对象.read()
```

需要安全返回时，函数名要说明行为：

```python
def 尝试读取文本文件(文件路径: str, 默认值: str = "") -> str:
    """读取文本文件，失败时返回默认值。"""
    try:
        with open(文件路径, "r", encoding="utf-8") as 文件对象:
            return 文件对象.read()
    except OSError:
        return 默认值
```

异常中文化函数应单独封装：

```python
def 异常_转中文提示(异常对象: Exception) -> str:
    """把常见 Python 异常转换为中文提示。"""
    异常类型 = type(异常对象).__name__
    原始信息 = str(异常对象)
    return f"{异常类型}：{原始信息}"
```

## PEP8 格式规范

易语言风格只改变命名表达，不改变 Python 的格式底线。代码必须遵守 PEP8。

要求：

- 使用 4 个空格缩进
- 顶层函数、类之间空 2 行
- 类方法之间空 1 行
- import 放在文件顶部
- 标准库、第三方库、本地库分组导入
- 行宽尽量控制在 88 到 100 个字符
- 运算符两侧保留空格
- 逗号后保留一个空格
- 函数默认参数写作 `参数: 类型 = 默认值`
- 文件末尾保留一个换行
- 优先使用 `ruff format` 或 `black` 格式化

推荐：

```python
import hashlib


def 计算SHA256(文本内容: str) -> str:
    """计算文本内容的 SHA256 摘要。"""
    哈希对象 = hashlib.sha256()
    哈希对象.update(文本内容.encode("utf-8"))
    return 哈希对象.hexdigest()
```

不推荐：

```python
import hashlib

def 计算SHA256(文本内容):
  哈希对象=hashlib.sha256();哈希对象.update(文本内容.encode('utf-8'));return 哈希对象.hexdigest()
```

## 常用代码模板

### UUID

```python
import uuid


def 取UUID() -> str:
    """生成随机 UUID 字符串。"""
    return str(uuid.uuid4())
```

### 时间戳

```python
import time


def 取时间戳(毫秒: bool = False) -> int:
    """获取当前时间戳。"""
    当前时间 = time.time()
    if 毫秒:
        return int(当前时间 * 1000)
    return int(当前时间)
```

### 文本截取

```python
def 文本_取中间(文本: str, 左标记: str, 右标记: str) -> str:
    """提取两个标记之间的文本。"""
    左位置 = 文本.find(左标记)
    if 左位置 == -1:
        return ""

    开始位置 = 左位置 + len(左标记)
    右位置 = 文本.find(右标记, 开始位置)
    if 右位置 == -1:
        return ""

    return 文本[开始位置:右位置]
```

### JSON 文件

```python
import json


def 读取JSON文件(文件路径: str):
    """读取 JSON 文件并返回 Python 对象。"""
    with open(文件路径, "r", encoding="utf-8") as 文件对象:
        return json.load(文件对象)


def 写入JSON文件(文件路径: str, 数据) -> None:
    """把 Python 对象写入 JSON 文件。"""
    with open(文件路径, "w", encoding="utf-8") as 文件对象:
        json.dump(数据, 文件对象, ensure_ascii=False, indent=4)
```

## 禁止事项

- 不要为了中文化牺牲 Python 语法正确性
- 不要使用拼音代替中文命名
- 不要把多个无关能力塞进一个函数
- 不要在工具函数中随意打印调试信息
- 不要保留明显错误的示例代码
- 不要生成无法通过 `ast.parse` 的代码
- 不要把第三方项目名写进通用风格规范
- 不要使用 `from xxx import *` 作为通用模板

## 质量检查清单

提交或生成代码前检查：

- 函数名是否中文且能表达用途
- 变量名是否清楚表达数据含义
- 函数是否只做一件事
- 是否使用标准库优先实现
- 是否有必要的中文 docstring
- 是否遵守 PEP8 缩进和空行
- 是否通过格式化工具
- 是否通过 Python 语法检查
- 是否去除了无意义打印和临时代码
- 是否没有依赖特定项目内部路径

## 风格一句话

用中文命名表达意图，用 Python 语法保证正确，用 PEP8 格式保证可维护。