1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装 Black
pip install black

# 格式化单个文件
black my_code.py

# 格式化整个目录
black my_project/

# 检查文件格式是否合规（不修改，只报告）
black --check my_code.py

# 显示需要格式化的文件列表（不修改）
black --diff my_code.py

1
2
3
4
5
6
7
8
9

# 格式化前（你的代码）
def  calculate(x,y,z):
    result=x+y*z
    return result

# 格式化后（Black 的版本）
def calculate(x, y, z):
    result = x + y * z
    return result

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

[tool.black]
# 行长度，默认88
line-length = 88

# 是否包含源码目录，True=会格式化 __pycache__ 里的内容（不推荐）
include = '\.pyi?$'

# 排除某些目录不格式化
exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

# 是否使用双引号（默认True）
quote-style = "double"

# 是否使用魔法尾随逗号，默认Simple
magic-trailing-comma = "simple"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 安装 Ruff
pip install ruff

# 检查代码问题（Lint）
ruff check my_code.py

# 格式化代码
ruff format my_code.py

# 自动修复问题
ruff check --fix my_code.py

# 查看所有可用规则
ruff rule <rule_code>
# 例如：ruff rule F401

1
2
3
4
5
6
7
8

# 作为 Linter 使用
ruff check ./src

# 作为 Formatter 使用
ruff format ./src

# 两者结合：先检查再格式化
ruff check --fix ./src && ruff format ./src

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# ruff.toml

# 目标 Python 版本
target-version = "py311"

# 行长度
line-length = 88

# 选择要启用的规则选择器
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
]

# 忽略某些规则
ignore = [
    "E501",   # 行太长（由 formatter 处理）
]

# 排除不检查的目录
exclude = [
    ".git",
    "__pycache__",
    ".venv",
    "build",
    "dist",
]

# isort 配置
[tool.ruff.isort]
known-first-party = ["my_project"]
force-single-line = false

# 格式化器配置
[tool.ruff.format]
quote-style = "double"
indent-style = "space"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 查看特定规则的详细信息
ruff rule E501

# 规则输出示例
"""
Line too long (89 > 88 characters)

Possible causes:
- Comment too long
- String too long
- Imported name too long

Ruff always ignores long lines with inline comments.
"""

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装 isort
pip install isort

# 排序单个文件
isort my_code.py

# 检查是否需要排序（不修改）
isort --check-only my_code.py

# 显示会做什么修改（不修改）
isort --diff my_code.py

# 递归处理整个项目
isort .

1
2
3
4
5

# 先用 isort 排序 import
isort .

# 再用 Black 格式化代码
black .

1
2
3

# pyproject.toml
[tool.isort]
profile = "black"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

[tool.isort]
# 使用 Black 兼容模式
profile = "black"

# 行长度（通常和 Black 保持一致）
line_length = 88

# 自定义分组顺序
force_sort_within_sections = true
known_first_party = ["my_project"]
known_third_party = ["requests", "numpy"]
known_local_folder = ["my_project"]

# 不排序的 import
force_single_line = false

# 添加 trailing comma（和 Black 配合）
add_trailing_comma = true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# =============================================
# 第一类：STDLIB（标准库）—— Python 内置模块
# =============================================
import os
import sys
import json
from collections import defaultdict
from typing import List, Dict

# （空行分隔）

# =============================================
# 第二类：THIRDPARTY（第三方库）—— pip 安装的包
# =============================================
import requests
import numpy as np
from flask import Flask

# （空行分隔）

# =============================================
# 第三类：FIRSTPARTY（第一方）—— 项目内部模块（非本地文件夹）
# =============================================
from my_project.utils import helper
from my_project.models import User

# （空行分隔）

# =============================================
# 第四类：LOCALFOLDER（本地文件夹）—— 项目本地的子模块
# =============================================
# （在 known_local_folder 中配置后，这里专门放子模块的导入）

# （空行分隔）

# =============================================
# 第五类：CUSTOM（自定义组）—— 通过配置指定的特殊模块
# =============================================
# 在 pyproject.toml 中通过 known_first_party 和 known_local_folder
# 配置的模块会单独成组，放在最后

1
2
3
4
5
6
7
8

# 安装 yapf
pip install yapf

# 格式化代码
yapf -i my_code.py

# 使用 diff 模式查看变更
yapf -d my_code.py

1
2
3
4
5
6
7
8

# Google 风格
yapf -i --style=google my_code.py

# PEP 8 风格
yapf -i --style=pep8 my_code.py

# Facebook 风格
yapf -i --style=facebook my_code.py

1
2
3
4
5
6

# yapf 配置示例（.style.yapf 或 pyproject.toml）

[style]
based_on_style = "pep8"
column_limit = 88
indent_width = 4

1
2
3
4
5
6

# 安装 pre-commit
pip install pre-commit

# 验证安装
pre-commit --version
# 输出: pre-commit 3.6.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# .pre-commit-config.yaml
# pre-commit hook 配置文件

repos:
  # Ruff：Lint + Format 二合一
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      # 先 Lint 检查
      - id: ruff
        args: [--fix]
      # 再格式化
      - id: ruff-format

  # isort：import 排序（如果不用 Ruff 的 I 规则）
  - repo: https://github.com/pycqa/isort
    rev: "5.13.2"
    hooks:
      - id: isort
        args: [--profile, black]

  # 验证 Python 语法
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-yaml          # 检查 YAML 语法
      - id: end-of-file-fixer   # 确保文件以换行符结尾
      - id: trailing-whitespace # 去除尾部空格
      - id: check-added-large-files  # 防止提交大文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 在项目根目录执行
pre-commit install

# 输出: pre-commit installed at .git/hooks/pre-commit

# 手动运行所有 hook（首次使用）
pre-commit run --all-files

# 或者针对特定文件
pre-commit run --files my_code.py

1
2
3
4
5
6
7
8

$ git commit -m "Add new feature"
Ruff.....................................................................Passed
Ruff Format...........................................................Passed
isort..................................................................Passed
Check Yaml............................................................Passed
End-of-file fixer.....................................................Passed
Trailing whitespace....................................................Passed
[main abc1234] Add new feature

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装 Flake8
pip install flake8

# 检查代码
flake8 my_code.py

# 检查整个项目
flake8 ./src

# 显示详细错误
flake8 --show-source my_code.py

# 最多显示的错误数量
flake8 --max-line-length=120 my_code.py

1
2
3
4

$ flake8 my_code.py
my_code.py:5:1: E302 expected 2 blank lines, found 1
my_code.py:15:20: E501 line too long (92 > 88 characters)
my_code.py:28:1: F401 'os' imported but unused

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

[flake8]
# 行长度限制
max-line-length = 88

# 复杂度限制
max-complexity = 10

# 排除检查的目录
exclude =
    .git,
    __pycache__,
    .venv,
    build,
    dist,
    *.egg-info

# 忽略的错误
ignore =
    E203,  # 空格在冒号周围（Black 会处理）
    E501,  # 行太长（由 formatter 或手动处理）
    W503   # 运算符换行

# 统计每个错误类型出现的次数
count = True

# 显示错误来源
show-source = True

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# E501: 行太长 ❌
def get_user_info_from_database_and_format_itNicely(user_id, session_token, include_private_fields):
    pass

# 修复：缩短或换行 ✅
def get_user_info(
    user_id: int,
    session_token: str,
    include_private: bool
) -> dict:
    pass

# E302: 需要空行 ❌
def func_a():
    pass
def func_b():
    pass

# 修复：函数间加空行 ✅
def func_a():
    pass


def func_b():
    pass

# F401: 未使用的 import ❌
import os  # 导入了但没使用
def hello():
    print("Hello!")

# 修复：删除或使用它 ✅
import os
print(os.name)  # 现在用了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装 Pylint
pip install pylint

# 检查代码
pylint my_code.py

# 检查模块
pylint my_project

# 只输出消息，不输出详细报告
pylint --reports=n my_code.py

# 生成报告文件
pylint --output-format=text my_code.py > report.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

$ pylint my_code.py

--------------------------------------------------------------------
Your code has been rated at 5.67/10 (previous run: 5.50/10)

# 分数分解
+2.22 for line-related issues
+1.85 for unused imports
+0.67 for missing docstrings
+0.00 for other issues

# 问题数量统计
19 statements analysed.
21 errors, 5 warnings, 10 conventions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# pyproject.toml
[tool.pylint.messages_control]
# 禁用特定消息
disable = [
    "missing-docstring",
    "too-few-public-methods",
    "too-many-arguments",
]

[tool.pylint.format]
# 行长度
max-line-length = 88

# 空行数量
max-module-lines = 1000

[tool.pylint.basic]
# 良好的类名格式（正则）
class-naming-style = "PascalCase"

# 良好的函数名格式
function-naming-style = "snake_case"

[tool.pylint.design]
# 最大函数参数数量
max-args = 5

# 最大函数长度（行数）
max-locals = 15

# 最大分支数量
max-branches = 12

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 安装（如果还没安装）
pip install ruff

# Lint 检查
ruff check ./src

# 详细输出
ruff check ./src --output-format=text

# 显示问题代码
ruff check ./src --show-fixes --diff

1
2
3
4
5
6
7
8

# 检查并自动修复
ruff check --fix ./src

# 只修复特定规则
ruff check --fix --select F401 ./src  # 只修复未使用的 import

# 查看能修复的内容（不实际修复）
ruff check --fix --diff ./src

1
2
3
4
5
6
7
8

$ ruff check --fix my_code.py

Found 3 errors (3 fixed, 0 unreadable, 0 unsupported).

✖ Fixed 3 errors:
  • F401: Removed unused import: 'os' (1 fix)
  • I001: Fixed import order (1 fix)
  • E714: Fixed test for singleton (1 fix)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# E731: 函数名用了 camelCase ❌
def calculateTotalPrice(items):
    return sum(item.price for item in items)

# 修复：使用 snake_case ✅
def calculate_total_price(items):
    return sum(item.price for item in items)

# N806: 常量名没用全大写 ❌
max_size = 1000
default_timeout = 30

# 修复：常量用全大写 ✅
MAX_SIZE = 1000
DEFAULT_TIMEOUT = 30

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# I001: import 顺序错误 ❌
import my_project.utils
import os
import requests

# 修复：标准库 → 第三方 → 本地 ✅
import os
import requests

import my_project.utils

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# F841: 变量定义了但没使用 ❌
def calculate():
    result = 10 + 20  # result 没被使用
    return result

# 修复：删除或使用 ✅
def calculate():
    return 10 + 20

# 或者如果确实需要中间变量
def calculate():
    result = 10 + 20
    print(f"Debug: {result}")  # 用了
    return result

# F811: import 了但没用 ❌
import os  # 没用到
def hello():
    print("Hello")

# 修复：删除 import 或者使用它 ✅
def hello():
    print("Hello")
# import os 已删除

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# C901: 函数太复杂 ❌
def process_user_data(user_data, config, db, cache):
    # 100+ 行代码，嵌套 5 层 if
    if user_data.is_valid:
        if config.enable_cache:
            if cache.get(user_data.id):
                # ... 100行逻辑
    return result

# 修复：拆分成多个小函数 ✅
def process_user_data(user_data, config, db, cache):
    if not user_data.is_valid:
        return None
    
    cached = get_cached_data(cache, user_data.id, config)
    if cached:
        return cached
    
    return compute_and_cache(user_data, db, cache, config)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# .ruffignore
# 忽略整个目录
tests/
build/
dist/

# 忽略特定文件
legacy_code.py
temporary_fix.py

# 忽略匹配模式的所有文件
*.pyc
__pycache__/
*.egg-info/

1
2
3
4
5

# 验证 ignore 是否生效
ruff check --verbose ./src

# 输出会显示哪些文件被忽略
Discovered 152 files. 3 files ignored by .ruffignore.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# noqa: E501 跳过 E501 检查（行太长）
long_long_long_long_long_long_long_long_variable_name = "这是一个超长的变量名"  # noqa: E501

# noqa: F401 跳过 F401 检查（未使用的 import）—— 这种情况通常是 __all__ 导出
from my_module import helpers  # noqa: F401

# noqa: E302,F401 跳过多个规则
import os  # noqa: E302,F401

# 跳过所有检查
result = some_weird_calculation()  # noqa

1
2
3
4
5
6
7

# 动态类型的"惊喜"
def add(a, b):
    return a + b

print(add(1, 2))       # 输出: 3 ✓
print(add("Hello", "World"))  # 输出: HelloWorld ✓
print(add(1, "World")) # 输出: TypeError! 💥

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 安装 mypy
pip install mypy

# 检查代码
mypy my_code.py

# 检查整个项目
mypy ./src

# 严格模式
mypy --strict my_code.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# mypy_test.py
def greet(name: str) -> str:
    """问候函数"""
    return f"Hello, {name}!"

def add(a: int, b: int) -> int:
    return a + b

# 测试
print(greet("World"))  # OK
print(add(1, 2))       # OK
print(add("1", "2"))  # mypy 会报错！

1
2
3
4
5

$ mypy mypy_test.py

mypy_test.py:10: error: Argument 1 to "add" has incompatible type "str"; expected "int"
mypy_test.py:10: error: Argument 2 to "add" has incompatible type "str"; expected "int"
Found 2 errors in 1 file

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# pyproject.toml
[tool.mypy]
# Python 版本
python_version = "3.11"

# 严格模式（后面详解）
strict = false

# 忽略缺失的 import
ignore_missing_imports = true

# 排除检查的目录
exclude = [
    "tests/",
    "build/",
]

1
2
3
4
5
6
7
8
9

[mypy]
python_version = 3.11
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = False
ignore_missing_imports = True

[mypy-tests.*]
ignore_errors = True

1

mypy --strict my_code.py

1
2
3
4
5
6
7

# 非严格模式：可以运行，但 mypy 可能放行
def process(data):  # 没有类型提示
    return data.value  # mypy 可能看不出问题

# 严格模式：必须写类型提示
def process(data: Any) -> Any:  # 或者具体类型
    return data.value

1
2
3
4
5
6
7
8

[tool.mypy]
# 忽略所有第三方库缺失的类型信息
ignore_missing_imports = true

# 或者针对特定库
[[tool.mypy.overrides]]
module = "pandas.*"
ignore_missing_imports = true

1
2

# 也可以在代码里用注释忽略
from untyped_library import something  # type: ignore[import]

1
2
3
4
5

# 作为命令行工具安装
npm install -g pyright  # 需要 Node.js

# 或者用 pip
pip install pyright

1
2
3
4
5
6
7
8

# 检查代码
pyright my_code.py

# 检查整个项目
pyright ./src

# 输出 JSON 格式（适合 CI/CD）
pyright --outputjson ./src

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "include": ["src"],
    "exclude": ["**/__pycache__", "build", "dist"],
    "venvPath": ".",
    "venv": ".venv",
    "pythonVersion": "3.11",
    "typeCheckingMode": "basic",
    "reportMissingImports": true,
    "reportMissingTypeStubs": false,
    "reportUnusedVariable": "warning",
    "reportUnusedImport": "warning"
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "typeCheckingMode": "strict",
    
    // strict 模式下自动开启的选项
    "reportMissingTypeStubs": "error",
    "reportUnknownMemberType": "error",
    "reportUnknownVariableType": "error",
    "strictParameterType": true,
    "strictReturnType": true
}

1
2
3
4
5
6

# Python 不强制类型，所以这些都能运行
def greet(name: str) -> str:
    return f"Hello, {name}"

# 类型提示只是"建议"，Python 不会检查
greet(12345)  # 运行不会报错！只是 mypy 会报警

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from typing import List, Dict, Optional

class User:
    def __init__(self, name: str, age: int):
        self.name: str = name
        self.age: int = age
    
    def to_dict(self) -> Dict[str, str]:
        return {
            "name": self.name,      # OK
            "age": str(self.age)     # OK: int → str 转换
        }

def get_users() -> List[User]:
    return [User("Alice", 30), User("Bob", 25)]

# mypy 会检查：
# - name 是 str，没问题
# - age 是 int，但在 to_dict() 里转成 str，没问题
# - 返回 List[User]，没问题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 阶段 1：完全没有类型（Python 默认）
def process(data):
    return data.value

# 阶段 2：部分类型
def process(data: dict) -> Any:
    return data["value"]

# 阶段 3：完全类型化
from typing import Any
def process(data: Dict[str, Any]) -> str:
    return str(data["value"])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 安装 Radon
pip install radon

# 计算复杂度
radon cc my_code.py

# 查看详细报告
radon cc -a my_code.py    # -a: 显示所有函数的复杂度
radon cc -x my_code.py    # -x: 显示复杂度的等级

# 计算代码行数
radon lines my_code.py

# 计算 Halstead 复杂度
radon halstead my_code.py

1
2
3
4
5
6
7

$ radon cc -a my_code.py

my_code.py
    M 4 (10) my_function - A
    M 3 (7) process_data - A
    F 2 (4) calculate - A
    M 1 (1) helper - A

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 复杂度 A（简单）✅
def add(a, b):
    return a + b

# 复杂度 B（有点分支）✅
def classify_score(score):
    if score >= 90:
        return "A"
    elif score >= 80:
        return "B"
    elif score >= 70:
        return "C"
    else:
        return "F"

# 复杂度 F（炸弹）❌
def process_everything(data, config, user, env, options):
    if data:
        if config:
            if user:
                if env:
                    if options:
                        # ... 无限嵌套
                        pass
                    else:
                        pass
                else:
                    if options:
                        pass

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 安装 wily
pip install wily

# 初始化（扫描 Git 历史）
wily calc ./src

# 查看报告
wily report ./src

# 查看某个文件的复杂度历史
wily graph ./src/my_code.py

# 查看 TOP 10 最复杂的函数
wily report ./src --metrics complexity --aggregate function

1
2
3
4
5
6
7
8
9

$ wily report ./src

File: src/utils.py
----------------------------------------
    Commit              Author      Complexity
    abc1234 (HEAD)      alice       A (3)
    def5678             alice       A (2)
    ghi9012             bob         C (15)  ← Bob 把复杂度弄高了
    jkl3456             alice       A (2)

1
2
3
4

# 在 GitHub 网页上点击 "Fork" 按钮
# 或者用命令行
git clone https://github.com/你的用户名/项目名.git
cd 项目名

1
2
3
4
5
6

# 创建新分支
git checkout -b feature/add-user-validation

# 或者
git branch feature/add-user-validation
git checkout feature/add-user-validation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# 查看修改
git status
git diff

# 添加文件到暂存区
git add my_code.py
git add ./src/

# 提交
git commit -m "feat: 添加用户验证功能

- 添加邮箱格式验证
- 添加密码强度检查
- 更新相关测试"

# 推送分支
git push origin feature/add-user-validation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

## PR 描述模板

### 做了什么
- 添加了用户邮箱验证功能
- 添加了密码强度检查（至少8位，包含数字和字母）

### 为什么做
- 解决用户注册时没有验证的问题
- 符合安全部门的要求

### 如何测试
1. 打开注册页面
2. 尝试输入无效邮箱 → 应该显示错误
3. 尝试输入弱密码 → 应该显示错误

### 截图/录屏
（如果有 UI 变化）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

## Review 注释示例

### 整体看起来不错！✅
> -- @reviewer_alice

### 小建议
> 这里可以用列表推导式让代码更简洁：
> ```python
> # 当前
> valid_users = []
> for user in users:
>     if user.is_active:
>         valid_users.append(user)
>
> # 建议
> valid_users = [u for u in users if u.is_active]
> ```
> -- @reviewer_bob

### 需要修改
> 这个函数没有处理空列表的情况，会抛出异常。需要在开头加个判断。
> -- @reviewer_alice

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 在 GitHub 网页上点击 "Merge pull request"
# 或者本地合并

git checkout main
git merge feature/add-user-validation
git push origin main

# 删除已合并的分支
git branch -d feature/add-user-validation
git push origin --delete feature/add-user-validation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# .pre-commit-config.yaml
# 完整示例

repos:
  # 1. 代码格式化（Lint + Format）
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  # 2. import 排序
  - repo: https://github.com/pycqa/isort
    rev: "5.13.2"
    hooks:
      - id: isort
        args: [--profile, black]

  # 3. 类型检查
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

  # 4. 安全检查
  - repo: https://github.com/pycqa/bandit
    rev: "1.7.6"
    hooks:
      - id: bandit
        args: [-r]

  # 5. Git 基础检查
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-yaml
      - id: end-of-file-fixer
      - id: trailing-whitespace
      - id: check-added-large-files
        args: ['--maxkb=1000']

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# 重构前 ❌
def send_order_email(order):
    # 验证订单
    if not order.items:
        return False
    if order.total <= 0:
        return False
    
    # 查找客户
    customer = get_customer(order.customer_id)
    if not customer:
        return False
    
    # 查找邮件模板
    template = get_template("order_confirmation")
    if not template:
        return False
    
    # 填充数据
    email_body = template.render(
        customer_name=customer.name,
        order_items=order.items,
        total=order.total
    )
    
    # 发送邮件
    send_email(customer.email, "Order Confirmation", email_body)
    return True

# 重构后 ✅
def send_order_email(order):
    if not validate_order(order):
        return False
    
    customer = get_customer(order.customer_id)
    if not customer:
        return False
    
    email_body = prepare_email_body(order, customer)
    send_email(customer.email, "Order Confirmation", email_body)
    return True

def validate_order(order):
    """验证订单是否有效"""
    return bool(order.items) and order.total > 0

def prepare_email_body(order, customer):
    """准备邮件内容"""
    template = get_template("order_confirmation")
    return template.render(
        customer_name=customer.name,
        order_items=order.items,
        total=order.total
    )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 重构前 ❌
if (user.age >= 18 and user.country in ["US", "CA", "UK"]) or (user.age >= 21 and user.country == "US"):
    grant_access()

# 重构后 ✅
is_adult_in_supported_country = user.age >= 18 and user.country in ["US", "CA", "UK"]
is_us_adult = user.age >= 21 and user.country == "US"

if is_adult_in_supported_country or is_us_adult:
    grant_access()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 重构前 ❌
def create_user(user_data):
    # 鬼知道 user_data 里有什么键！
    name = user_data["name"]
    email = user_data["email"]
    age = user_data.get("age", 0)
    return f"{name} ({email})"

user = {"name": "Alice", "email": "alice@example.com"}
print(create_user(user))

# 拼写错误？运行时才爆炸 💥
# print(create_user({"nmae": "Bob", "email": "bob@example.com"}))

# 重构后 ✅
from dataclasses import dataclass

@dataclass
class User:
    name: str
    email: str
    age: int = 0

def create_user(user: User) -> str:
    return f"{user.name} ({user.email})"

user = User(name="Alice", email="alice@example.com")
print(create_user(user))  # IDE 会提示可用属性！

# 拼写错误？写代码时就报错了 ✅
# User(nmae="Bob", email="bob@example.com")  # IDE 报错！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# 重构前 ❌
def process_order(order, status):
    if status == "pending":
        # 处理待处理订单
        pass
    elif status == "paid":
        # 处理已支付订单
        pass
    elif status == "shipped":
        # 处理已发货订单
        pass
    elif status == "delivered":
        # 处理已送达订单
        pass

# 两年后...
# status == "pendig"  # 拼写错误，bug！
# status == 1  # 数字更难看不懂

# 重构后 ✅
from enum import Enum

class OrderStatus(Enum):
    PENDING = "pending"
    PAID = "paid"
    SHIPPED = "shipped"
    DELIVERED = "delivered"

def process_order(order, status: OrderStatus):
    if status == OrderStatus.PENDING:
        # 处理待处理订单
        pass
    elif status == OrderStatus.PAID:
        # 处理已支付订单
        pass
    # ...

# IDE 自动补全！拼写错误？不存在的！

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 重构前 ❌ - 金字塔地狱
def process_user(user):
    if user is not None:
        if user.is_active:
            if user.has_permission:
                if user.email_verified:
                    # 终于做正事！
                    send_notification(user)
                else:
                    return "请先验证邮箱"
            else:
                return "没有权限"
        else:
            return "用户未激活"
    else:
        return "用户不存在"

# 重构后 ✅ - Early Return
def process_user(user):
    # 提前返回，告别嵌套！
    if user is None:
        return "用户不存在"
    
    if not user.is_active:
        return "用户未激活"
    
    if not user.has_permission:
        return "没有权限"
    
    if not user.email_verified:
        return "请先验证邮箱"
    
    # 终于做正事！
    send_notification(user)
    return "成功"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# ✅ 正确
user_name = "Alice"
is_active = True
calculate_total_price = 100.0
get_user_by_id = lambda x: x

# ❌ 错误
userName = "Alice"       # camelCase（不 Python）
IsActive = True         # PascalCase（这是类名风格）
CalculateTotalPrice = 100.0  # PascalCase

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# ✅ 正确
class UserAccount:
    pass

class ShoppingCart:
    pass

class HttpResponse:
    pass

# ❌ 错误
class user_account:  # snake_case（这是变量名风格）
    pass

class userAccount:  # camelCase（不标准）
    pass

1
2
3
4
5
6
7
8

# ✅ 正确
MAX_RETRY_COUNT = 3
DEFAULT_TIMEOUT = 30
API_BASE_URL = "https://api.example.com"
PI = 3.14159

# ❌ 错误
max_retry_count = 3  # 这是变量，不是常量（虽然值不变）

1
2
3
4
5
6
7
8

class User:
    def __init__(self, name, email):
        self.name = name        # 公开属性
        self._email = email     # 私有属性（约定）
    
    def _send_email(self):  # 私有方法
        """私有方法，外部不要调用"""
        print(f"Sending email to {self._email}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

class User:
    def __init__(self, password):
        self.__password = password  # 双下划线
    
    def _get_password(self):
        return self.__password

# 外部访问
user = User("secret")
# print(user.__password)  # ❌ AttributeError！

# 正确的访问方式（其实也不应该访问）
print(user._User__password)  # 能访问，但不建议！⚠️

1
2
3
4
5
6
7
8
9

# ❌ 避免：l（小写L）、O（大写o）、I（大写i）
l = 1   # 看起来像数字 1
O = 0   # 看起来像数字 0
I = 1   # 看起来像数字 1

# ✅ 推荐：用其他字符或单词
length = 1
count = 0
index = 1

1
2
3
4
5
6
7
8
9

# ❌ 超过 88 字符
def get_user_full_address_with_postal_code_and_country_name(user):
    return f"{user.street}, {user.city}, {user.postal_code}, {user.country_name}"

# ✅ 修复：缩短或换行
def get_user_full_address(
    user,
) -> str:
    return f"{user.street}, {user.city}, {user.postal_code}, {user.country_name}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# ✅ 推荐：运算符在行首（数学家习惯）
total = (
    item_price
    + tax
    - discount
    + shipping
)

# ❌ 不推荐：运算符在行尾
total = (
    item_price +
    tax -
    discount +
    shipping
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 方法一：悬挂缩进（Indentation with continuation）
def send_email(
    recipient,
    subject,
    body,
):
    # 继续代码

# 方法二：悬挂缩进（多一层缩进）
def send_email(
        recipient,
        subject,
        body,
    ):
    # 继续代码

# 方法三：括号对齐（更紧凑）
def send_email(recipient, subject, body):
    pass

# 方法四：反斜杠续行（不推荐，但有时需要）
text = "这是一段很长的文字，\
       可以用反斜杠连接。"

1
2
3
4
5
6
7

# ✅ 正确
import os
import sys
import requests

# ❌ 错误
import os, sys, requests

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# 第一组：标准库
import os
import sys
import json
from collections import defaultdict
from typing import List, Dict

# 空行

# 第二组：第三方库
import requests
import numpy as np
from flask import Flask

# 空行

# 第三组：本地项目
from my_project.utils import helper
from my_project.models import User

1
2
3
4
5
6
7

# ✅ 推荐：绝对导入
from my_project.utils import helper
from my_project.models import User

# ❌ 避免：相对导入（除非在复杂包结构中）
from .utils import helper
from ..models import User

1
2
3
4
5
6
7
8
9

# ❌ 非常糟糕：不知道导入了什么
from my_module import *

# ✅ 明确列出需要的
from my_module import specific_function, SpecificClass

# ✅ 或者用模块前缀
import my_module
my_module.specific_function()