编程狮 Python 代码风格指南（GNU Mailman 衍生版）

适用版本：Python 3.12+

0️⃣ 写在前面

这份指南在 PEP 8 的基础上，结合 GNU Mailman 团队的实践经验，由编程狮（W3Cschool）针对国内零基础同学重新翻译、精简和本土化，确保你第一次写 Python 就能写出“大厂味”代码。

1️⃣ 导入语句（import）怎么排？

位置：文件最顶部，顺序固定，不要乱放！

# 1. 未来语句 / 元数据
from __future__ import annotations


# 2. 标准库 & 第三方库（非 from）
import os
import sys


# 3. 项目内部模块（非 from）
import mailman.config


# 4. 标准库 & 第三方库（from）
from datetime import datetime
from typing import List


# 5. 项目内部模块（from）
from mailman.models.user import User

编程狮小提示：

安装 pip install flufl.flake8 可自动检查顺序，VSCode 保存即修复。

2️⃣ 一个文件只放一个类？

建议：一个 .py 文件只写一个公共类，文件名保持小写下划线（如 email_sender.py）。
如果多个类强相关，可以放在同一文件，但务必在顶部写明：
```
__all__ = ["EmailSender", "EmailConfig"]
```
工具推荐：pip install atpublic 一键导出公共 API。

3️⃣ 注释与空行

不要右侧注释，阅读体验差：
❌ name = "编程狮" # 网站名称
✅
```
# 网站名称
name = "编程狮"
```
空行规则：
- 顶级定义（类/函数/全局变量）之间 2 空行
- 类内方法之间 1 空行
- 方法与其文档字符串之间 0 空行

4️⃣ 引号使用口诀

短字符串 → 单引号 'w3cschool'
带英文单引号 → 双引号 "Don't stop"
多行文档 → 三双引号：

"""编程狮 Python 风格指南
- 简洁
- 易读
- 可维护
"""

5️⃣ 文档字符串（docstring）

必须写：模块、类、公共函数、公共方法。
单行写法："""返回用户名称"""

多行写法（Google 风格）：

def get_user(uid: int) -> User:
"""根据用户 ID 获取用户对象




Args:
    uid: 用户唯一标识




Returns:
    User 实例




Raises:
    ValueError: 用户不存在
"""

每行长度 ≤ 78 字符，W3Cschool 在线编辑器自动换行提示。

6️⃣ 序列判空

明确写长度，减少歧义：
✅ if len(users) == 0:
❌ if not users:（除非变量可能为 0、None、[] 等多种假值）

7️⃣ 私有 vs 公有

形式	含义	示例	编程狮建议
`name`	公有	`user.name`	正常业务字段
`_name`	内部使用	`_cache`	模块内部缓存
`__name`	防继承冲突	`__secret`	很少用，慎用

8️⃣ 一键格式化

装好以下工具，保存文件即自动完成风格检查：

pip install black isort flake8 flufl.flake8

black：自动格式化
isort：自动排序 import
flake8：静态检查

9️⃣ 完整模板（复制即用）

新建 demo.py：

"""demo.py - 编程狮 Python 风格示例"""

 
from __future__ import annotations

 
import os
from typing import List

 
__all__ = ["greet"]

 

 
def greet(names: List[str]) -> str:
    """拼接欢迎语

 
    Args:
        names: 用户名列表

 
    Returns:
        欢迎字符串
    """
    if len(names) == 0:
        return "Hello, 编程狮！"
    return "Hello, " + ", ".join(names) + "!"

想要系统学习 Python 请移步《Python零基础到高薪就业》