前言

  我们学习一门语言，既要服务于我们所解决的问题， 也要对语言的设计者对设计该语言的初衷进行了解。"经验丰富的程序员倡导尽可能避繁就简。Python社区的理念都包含在Tim Peters撰写的 “Python之禅”中。要获悉这些有关编写优秀Python代码的指导原则，只需在解释器中执行命令 import this"（引用《Python编程：从入门到实践》），以下让我们对"Python之禅"的内容进行简单的翻译，没事儿看看，可能在不同的编程阶段会有不同的感悟。

bash
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

1. 优美胜于丑陋（Python 以编写优美的代码为目标）
2. 明了胜于晦涩（优美的代码应当是明了的，命名规范，风格相似）
3. 简洁胜于复杂（优美的代码应当是简洁的，不要有复杂的内部实现）
4. 复杂胜于凌乱（如果复杂不可避免，那代码间也不能有难懂的关系，要保持接口简洁）
5. 扁平胜于嵌套（优美的代码应当是扁平的，不能有太多的嵌套，少写一些复杂的列表推倒式，对自己对别人都友好）
6. 间隔胜于紧凑（优美的代码有适当的间隔，不要奢望一行代码解决问题）
7. 可读性很重要（优美的代码是可读的）
8. 即便假借特例的实用性之名，也不可违背这些规则（这些规则至高无上）
9. 不要包容所有错误，除非你确定需要这样做（精准地捕获异常，不写 except
   风格的代码）
10. 当存在多种可能，不要尝试去猜测
11. 而是尽量找一种，最好是唯一一种明显的解决方案（如果不确定，就用穷举法）
12. 虽然这并不容易，因为你不是 Python 之父（这里的 Dutch 是指 Guido ）
13. 做也许好过不做，但不假思索就动手还不如不做（动手之前要细思量，但不要过分考虑，开始就追求完美并不是一个好主意，追求完美最好分阶段进行）
14. 如果你无法向人描述你的方案，那肯定不是一个好方案；反之亦然（方案测评标准）
15. 命名空间是一种绝妙的理念，我们应当多加利用（倡导与号召）

Python风格规范

1. 统一使用4个空格缩进

2. 单行最大长度为100

3. 行数超过规定，建议用小括号()将多行内容连接起来，而不推荐使用反斜杠\进行连接。具体例子如下：

• 函数/方法参数过长

python

# ✅ 推荐：括号隐式换行 + 每行一个参数 + 可加尾随逗号
result = do_something(
    user_id=uid,
    retries=3,
    timeout=5.0,
    on_error=handle_error,  # 行内注释也没问题
)

# ❌ 不推荐：反斜杠续行，注释/空格稍不注意就报错
result = do_something( \
    user_id=uid, \
    retries=3, \
    timeout=5.0, \
    on_error=handle_error \
)

• 构造列表/字典/集合

python

# ✅ [] / {} 内天然支持多行
fields = [
    "id",  #用户ID
    "name",
    "email",  # 轻松加注释
]

config = {
    "host": "localhost",  # 测试服IP
    "port": 5432,
    "debug": True,
}

• 复杂布尔表达式（建议“操作符前置”）

python

# ✅ 推荐：把每个子条件单独一行，且操作符前置，便于增删
if (
    is_logged_in
    and has_permission("export")
    and (items_count > 0)
):
    export()

• with / import 多项

python

# ✅ 多个上下文管理器
with (
    open("input.txt") as fin,
    open("output.txt", "w") as fout,
):
    fout.write(fin.read())

# ✅ 多个导入（小括号内自动换行）
from pathlib import (
    Path,
    PurePath,
)

• 长字符串拼接（相邻字面量自动拼接 + 括号包裹）

python

# ✅ 相邻字符串字面量会在编译期合并
sql = (
    "SELECT id, name, email "
    "FROM users "
    "WHERE active = 1 "
    "ORDER BY created_at DESC"
)

# ✅ f-string 也可以拆成多个相邻 f-string
user_line = (
    f"id={user.id} "
    f"name={user.name} "
    f"email={user.email}"
)

• 数学/链式调用过长

python

# ✅ 保持结构清晰
score = (
    0.25 * precision
    + 0.25 * recall
    + 0.50 * f1
)

# ✅ 链式调用
(
    pd.read_csv("data.csv")
      .query("age >= 18")
      .assign(is_vip=lambda df: df["score"] > 80)
      .to_csv("out.csv", index=False)
)

• 长的类型注解（typing）

python

from typing import Dict, List, Tuple

# ✅ 类型别名分行清晰
UserIndex = Dict[
    int,  # user_id
    Tuple[str, List[str]]  # (name, tags)
]

• 推导式也可用括号（注意：小括号会变成生成器表达式）

python

# ✅ 方括号推导式可多行（仍是列表）
names = [
    user.name
    for user in users
    if user.active
]

# ✅ 小括号=生成器表达式，传给 sum 等函数更省内存
total = sum(
    item.price
    for item in items
    if item.in_stock
)

• 正确地给长字典/列表“加注释 + 尾随逗号”

python
# ✅ 尾随逗号让 diff 更干净，后续新增行无需改上一行
settings = {
    "timeout": 10,   # seconds
    "retries": 3,
    "cache": True,
}

• 较长的 return/dict() 构造

python

def build_payload(user):
    return {
        "id": user.id,
        "name": user.name,
        "roles": [r.name for r in user.roles],
        "active": user.active,
    }

• 常用范式模版

python
todo: 范式 A：长调用参数

resp = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "id": user.id,
        "name": user.name,
        "tags": user.tags,
    },
    timeout=10,
)

todo: 范式 B：长条件判断

if (
    user.is_active
    and user.email_verified
    and not user.is_banned
    and (quota.used < quota.limit)
):
    allow_access()
    
todo: 范式 C：长字符串（SQL/日志模板）

query = (
    "SELECT u.id, u.name, COUNT(o.id) AS orders "
    "FROM users u "
    "LEFT JOIN orders o ON u.id = o.user_id "
    "WHERE u.created_at >= :start "
    "GROUP BY u.id, u.name "
    "ORDER BY orders DESC "
    "LIMIT 100"
)

todo: 范式 D：分步计算/链式

final = (
    normalize(raw)
    .pipe(filter_invalid)
    .pipe(enrich_with_geo)
    .pipe(attach_metrics)
)

• 反例

python

# ❌ 行尾注释与 \ 冲突
total = price + tax \  # 因为反斜杠后还有东西（注释），所以这个反斜杠失效，并不会把下一行接起来
         + fee         # Python 会尝试单独解析 + fee 这一行，但这在语法上是不完整的表达式，直接报错： SyntaxError: invalid syntax

"""
1. \ 表示“当前行还没结束，请继续看下一行”。
2. 但是 \ 必须是这一行的最后一个字符，后面不能有空格、不能有注释。
   否则 Python 认为 \ 只是一个普通字符，行就结束了。
"""

5. 空行使用

1. 函数之间用两个空行隔开
2. 类之间用两个空行隔开
3. 类中方法用一个空行隔开
4. 函数中不同逻辑代码块之间可适当插入空行
5. 文件末尾必须有一个空行（有助于 diff 友好和工具处理）

6. 空格使用

1. 在二元运算符两边都要有空格。二元运算包括：算术(+ - * / ** )、赋值(=，+=，-=)、比较( ==, <, >, !=, in, not in, is, is not)、逻辑运算(and or not)、位运算(& | ! ~ >> <<)、海象运算符 :=
2. 函数关键字参数=两侧不需要空格。例： res = func(name="Tom")
3. 逗号后面要加空格，但是如果后面是小括号则不用。例：List=[1, 2, 4]
4. 冒号前不加空格，冒号后要加空格。但是切片里前后都不可加空格 。例：Dict = {key: value}
5. 不要为对齐赋值语句而使用的额外空格
6. 切片特殊规则：默认切片arr = a[1:5]不要加空格、如果切片表达式本身比较复杂，可以用 对称空格 提高可读性如arr = a[lower : upper + 1]

命名

Python 函数设计规范

1. 强制规则

python
from dataclasses import dataclass, field
@dataclass
class Bag:
    items: list[int] = field(default_factory=list) # 每次实例化时都给我一个全新的空列表

2. 推荐规则

3. 常见反例与正确写法

1) 可变默认值

python
# ❌ 错误：默认列表在定义时创建，后续调用共享同一对象
def append_item(item, bucket=[]):
    bucket.append(item)
    return bucket

append_item(1)  # [1]
append_item(2)  # [1, 2] ← 期望之外的“记忆效应”

# ✅ 正确：用 None 作为哨兵
def append_item(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

2) 圈复杂度控制与拆解

python
# ❌ 复杂、嵌套多
def handle(order):
    if order.valid:
        if order.paid:
            if order.stock_ok:
                ship(order)
            else:
                refund(order)
        else:
            notify_to_pay(order)

# ✅ 早返回 + 小函数
def handle(order):
    if not order.valid:
        return reject(order)
    if not order.paid:
        return notify_to_pay(order)
    return _fulfill(order)

def _fulfill(order):
    if not order.stock_ok:
        return refund(order)
    return ship(order)

3) 单一职责与命名

python
# ❌ 名不副实：既下载又解析又落库
def process_user_data(url): ...

# ✅ 明确边界
def fetch_user_csv(url): ...
def parse_user_csv(text: str) -> list[User]: ...
def save_users(users: list[User]) -> None: ...

Python 模块导入规则

1. 导入位置：文件顶部

导入语句应放在模块文件顶部（模块注释 / 文档字符串之后），并在模块全局常量/变量之前。例如：

python
"""module docstring"""

import os
import typing

CONSTANT = 42

2. 导入分组和顺序

把 imports 分成三组，每组内部按字母序排列（工具会自动处理）：

• 标准库（os, sys, json...）
• 第三方库（requests, numpy...）
• 本地应用/库（from mypkg import utils）
• 每两组之间用一个空行分隔：

python
# 标准库
import os
import sys

# 第三方
import requests
import numpy as np

# 本地应用/库
from myapp.utils import helper

3. 导入的例外/特殊场景

虽然一般放顶部，但下列情形允许局部导入：

• 避免循环依赖（circular import）：把某个依赖移入函数内部，延迟导入。
• 可选依赖：仅在某些功能执行时才需要，避免程序启动就报错。
• 性能/启动时间优化：重型库（如 pandas）在仅部分路径使用时可延迟导入。

python
def use_pandas():
    import pandas as pd  # 延迟导入，避免全局开销或循环依赖
    return pd.DataFrame(...)

注释

1. Docstring（接口注释，使用 """）

用途：模块 / 类 / 函数 / 方法 的接口文档 — 描述做什么、参数、返回值、异常、示例等。 格式建议：首行一句话概述；若有更多说明，首行后空行写详细描述。

Google 风格

python
def find_user(user_id: int) -> dict | None:
    """Find a user by id.

    Args:
        user_id (int): The ID of the user to lookup.

    Returns:
        dict | None: The user dict if found, otherwise None.

    Raises:
        DatabaseError: If the DB query fails.
    """
    ...

模块 docstring（文件顶部）

python

"""utils.strings

Utilities for string normalization and tokenization used across the service.
"""

2. TODO / FIXME / HACK / NOTE

用途：标记待办、需要修复或不完美的解决方案。

python

def process_data(data):
    # TODO(issue#101): add input validation — @bob
    # FIXME: fails if data contains None
    # HACK: using global cache to speed up, need proper caching later
    # NOTE: this function is called by both sync and async tasks
    ...

在团队中统一格式，比如都加 issue# 和负责人，可以用 CI/脚本统计 TODO/FIXME/HACK 数量，避免遗漏。

真值判断

1. 容器类型空值判断（推荐使用布尔值而非长度比较）

理由：

• Python 内置类型的空值都可以被视作 False，非空值视作 True。
• if user_list: 比 if len(user_list) 更简洁，可读性高。
• 避免不必要的函数调用（如 len()），性能上略优。

示例：

python
user_list = []

# 推荐
if not user_list:
    print("列表为空")

if user_list:
    print("列表不为空")

# 不推荐
if len(user_list) == 0:
    print("列表为空")

if len(user_list):
    print("列表不为空")

2. None 值判断

示例：

python

value = None

# 推荐
if value is None:
    print("value 是 None")

if value is not None:
    print("value 有值")

# 不推荐
if not value is None:
    print("不要这样写")

3. 布尔类型判断

示例：

python

greeting = True

# 推荐
if greeting:
    print("Hello")

# 不推荐
if greeting is True:
    print("Hello")

if greeting == True:
    print("Hello")

4. 综合实例

python
user_list = []
greeting = True
value = None

# 容器判断
if not user_list:
    print("列表为空")

# 布尔类型判断
if greeting:
    print("问候开启")

# None 判断
if value is None:
    print("值未初始化")

# 结合使用
if user_list and greeting and value is not None:
    print("执行逻辑")

异常捕捉

1. 异常捕捉原则

2. 推荐做法

3. 异常处理结构示例

单操作异常捕获（颗粒度小）

python
try:
    value = int(user_input)
except ValueError as e:
    print(f"输入错误: {e}")

大段 try 块（不推荐）

python
# ❌ 错误示例
try:
    value = int(user_input)
    result = 10 / value
    with open("file.txt") as f:
        data = f.read()
except Exception as e:
    print("出错了")  # 不明确，不利于排查

finally 禁止 return

python
def test_finally():
    try:
        return 1
    finally:
        return 2  # ❌ 会覆盖 try 的返回值

print(test_finally())  # 输出 2，而非 1

推荐的 finally 用法

python
def test_finally_correct():
    try:
        return 1
    finally:
        print("执行清理操作")  # 仅做清理，不 return

print(test_finally_correct())  # 输出 1

项目工程结构

推荐项目结构示例如下：

markdown
sample_project
 ├── readme.md
 ├── docs
 │   ├── api.yml
 │   └── public_read.md
 ├── requirements.txt
 ├── app
 │   ├── __init__.py
 │   ├── core.py
 │   └── helpers.py
 ├── config
 │   ├── mysql.py
 ├── deploy
 │   ├── __init__.py
 │   └── run.sh
 ├── db
 │ 
 ├── utils
 │ 
 └── tests
     ├── __init__.py
     └── test_basic.py

1. 项目根目录文件

2. 核心代码目录 app/

3. 配置目录 config/

4. 部署目录 deploy/

5. 数据库目录 db/

6. 工具目录 utils/

7. 测试目录 tests/