Python 之禅：19 条格言背后的取舍与实战

import this

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

# 纯显式写法：每一步都手动展开
result = []
for item in items:
    if item.is_valid():
        processed = transform(item)
        result.append(processed)

# 实用写法：隐式依赖 list comprehension 的语义
result = [transform(item) for item in items if item.is_valid()]

# Simple：一个函数里直接校验
def delete_user(user_id, current_user):
    if not current_user.has_permission("admin"):
        raise PermissionError
    db.delete(user_id)

# Complex but not complicated：装饰器分层，每层只管一件事
@require_permission("admin")
@audit_log(action="delete_user")
def delete_user(user_id):
    db.delete(user_id)

# 立刻做：日志格式统一，收益确定，风险为零
import logging
logging.basicConfig(format="%(asctime)s %(levelname)s %(name)s: %(message)s")

# 先不做：引入新 ORM 框架替换 SQLAlchemy
# 收益：可能简化查询写法
# 风险：迁移成本、团队学习曲线、未知边界情况
# → 写个 spike 验证，不要直接全量切换

"""
zen_linter.py — 把 Python 之禅变成可运行的代码检查
用法: python zen_linter.py <目标文件或目录>
"""

import ast
import sys
from pathlib import Path

def check_flat_vs_nested(tree: ast.AST, filepath: str) -> list[str]:
    """第5条: Flat is better than nested — 检查嵌套深度超过3层的if/for"""
    warnings = []
    def _walk(node: ast.AST, depth: int = 0):
        if isinstance(node, (ast.If, ast.For, ast.While, ast.With)):
            if depth >= 3:
                warnings.append(
                    f"{filepath}:{node.lineno} — 嵌套深度 {depth}，"
                    f"考虑提取函数或用 early return 降低层级 (Flat > Nested)"
                )
            for child in ast.iter_child_nodes(node):
                _walk(child, depth + 1)
        else:
            for child in ast.iter_child_nodes(node):
                _walk(child, depth)
    _walk(tree)
    return warnings

def check_sparse_vs_dense(tree: ast.AST, filepath: str) -> list[str]:
    """第6条: Sparse is better than dense — 检查单行多条语句"""
    warnings = []
    for node in ast.walk(tree):
        if isinstance(node, ast.stmt) and hasattr(node, "end_lineno") and hasattr(node, "lineno"):
            if node.end_lineno == node.lineno:
                # 单行语句本身没问题，但用分号拼多条就有问题
                pass
    # 更直接的方式：扫描源码里的分号
    source = Path(filepath).read_text()
    for i, line in enumerate(source.splitlines(), 1):
        if ";" in line and not line.strip().startswith("#"):
            # 排除字符串内的分号
            try:
                stmts = ast.parse(line, mode="exec").body
                if len(stmts) > 1:
                    warnings.append(
                        f"{filepath}:{i} — 单行多条语句，"
                        f"拆开更易读 (Sparse > Dense)"
                    )
            except SyntaxError:
                pass
    return warnings

def check_readability(tree: ast.AST, filepath: str) -> list[str]:
    """第7条: Readability counts — 检查单字母变量名（循环变量除外）"""
    warnings = []
    ALLOWED = {"i", "j", "k", "x", "y", "z", "_", "e", "f", "n", "m"}
    for node in ast.walk(tree):
        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
            if len(node.id) == 1 and node.id not in ALLOWED:
                warnings.append(
                    f"{filepath}:{node.lineno} — 变量 '{node.id}' 命名过短，"
                    f"可读性不足 (Readability counts)"
                )
    return warnings

def lint_file(filepath: str) -> list[str]:
    source = Path(filepath).read_text()
    tree = ast.parse(source, filename=filepath)
    all_warnings = []
    all_warnings.extend(check_flat_vs_nested(tree, filepath))
    all_warnings.extend(check_sparse_vs_dense(tree, filepath))
    all_warnings.extend(check_readability(tree, filepath))
    return all_warnings

def main():
    target = sys.argv[1] if len(sys.argv) > 1 else "."
    path = Path(target)
    files = path.rglob("*.py") if path.is_dir() else [path]
    total = 0
    for f in files:
        if f.name == "zen_linter.py":
            continue
        warnings = lint_file(str(f))
        for w in warnings:
            print(w)
        total += len(warnings)
    print(f"\n共 {total} 条 Zen 警告")

if __name__ == "__main__":
    main()

python zen_linter.py ./your_project/