python-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Best Practices

Python最佳实践

Guidelines for writing and reviewing Python. 70 rules across 8 categories, prioritized by impact.

A rule match is a signal, not a verdict. Most rules are design preferences for new code, not bugs to fix across the repo — check the rule's impact level before flagging in review or refactoring stable code.

编写和评审Python代码的指南。涵盖8个分类共70条规则，按影响优先级排序。

规则匹配是一个信号而非定论。大多数规则是针对新代码的设计偏好，而非需要在整个仓库中修复的bug——在评审或重构稳定代码时，先检查规则的影响级别。

When to Apply

适用场景

Writing new Python modules, functions, classes, or data models
Reviewing code for correctness or type safety
Refactoring patterns in code that's being edited anyway

Avoid applying these rules as a blanket sweep across stable code — the churn rarely pays off.

编写新的Python模块、函数、类或数据模型
评审代码的正确性或类型安全性
重构正在编辑的代码中的模式

不要将这些规则作为统一标准应用于所有稳定代码——这种改动通常得不偿失。

Impact Levels

影响级别

```
CRITICAL
```
— prevents a real bug class (data corruption, swallowed cancellations, insecure defaults). Fix when found.
```
HIGH
```
— meaningful correctness or maintainability win. Worth fixing in most contexts.
```
MEDIUM
```
— good practice; clarity or drift prevention. Apply to new code; don't churn stable code.
```
LOW-MEDIUM
```
/
```
LOW
```
— style or micro-optimizations. Apply opportunistically.

```
CRITICAL
```
— 预防真实的bug类别（数据损坏、取消操作被吞、不安全默认值）。发现后需修复。
```
HIGH
```
— 在正确性或可维护性上有显著提升。大多数场景下值得修复。
```
MEDIUM
```
— 良好实践；提升清晰度或防止代码退化。应用于新代码；不要改动稳定代码。
```
LOW-MEDIUM
```
/
```
LOW
```
— 风格或微优化。适时应用。

Python Version Baseline

Python版本基准

Rules assume Python 3.11+. Rules depending on higher versions call it out inline:

```
warnings.deprecated()
```
— 3.13+
```
zoneinfo
```
— 3.9+
Union types in
```
isinstance()
```
— 3.10+
```
assert_never
```
— 3.11+ (backport via
```
typing_extensions
```
)

Rules tagged

applicability:pydantic

are Pydantic-specific.

规则基于Python 3.11+制定。依赖更高版本的规则会在文中明确标注：

```
warnings.deprecated()
```
— 3.13+
```
zoneinfo
```
— 3.9+
isinstance()中的联合类型 — 3.10+
```
assert_never
```
— 3.11+（可通过
```
typing_extensions
```
向后兼容）

标记为

applicability:pydantic

的规则是Pydantic专属规则。

Rule Categories by Priority

按优先级排序的规则分类


data-
error-
types-
api-
simplify-
perf-
naming-
imports-

Priority	Category	Impact	Prefix
1	Data Modeling	HIGH	`data-`
2	Error Handling	MEDIUM-HIGH	`error-`
3	Type Safety	MEDIUM-HIGH	`types-`
4	API Design	MEDIUM	`api-`
5	Code Simplification	LOW-MEDIUM	`simplify-`
6	Performance	LOW-MEDIUM	`perf-`
7	Naming	LOW-MEDIUM	`naming-`
8	Imports & Structure	LOW	`imports-`

Section impact is a typical-case label; individual rules range one level above or below — check the rule file.


data-
error-
types-
api-
simplify-
perf-
naming-
imports-

优先级	分类	影响级别	前缀
1	数据建模	HIGH	`data-`
2	错误处理	MEDIUM-HIGH	`error-`
3	类型安全	MEDIUM-HIGH	`types-`
4	API设计	MEDIUM	`api-`
5	代码简化	LOW-MEDIUM	`simplify-`
6	性能优化	LOW-MEDIUM	`perf-`
7	命名规范	LOW-MEDIUM	`naming-`
8	导入与结构	LOW	`imports-`

分类的影响级别是典型场景下的标签；单个规则的影响级别可能上下浮动一级——请查看规则文件确认。

Quick Reference

快速参考

Data Modeling (

data-

)

数据建模 (

data-

)

data-mutable-defaults

— Never

def f(items=[])

; use

None

+ body construction or

default_factory

```
data-derive-dont-store
```
— Compute booleans from state; don't cache flags that mirror each other
```
data-mutation-contract
```
— Mutate OR return; not both

data-aware-datetimes

— Timezone-aware

datetime.now(timezone.utc)

;

utcnow()

is deprecated

```
data-discriminated-unions
```
— Tag variants instead of optional-field bags
```
data-explicit-variants
```
— Concrete classes per mode beat
```
is_thread
```
/
```
is_edit
```
flags
```
data-phased-composition
```
— Group co-present optionals into one nested optional
```
data-encapsulate-mutable-state
```
— Trap mutable state in the narrowest clear scope
```
data-sentinel-when-none-is-valid
```
— Private sentinel when
```
None
```
is a meaningful value

data-newtype-for-ids

—

NewType('UserId', str)

so IDs aren't interchangeable

```
data-delete-dead-variants
```
— Remove union arms that aren't constructed

data-mutable-defaults

— 绝不要使用

def f(items=[])

；使用

None

+ 函数体内构造或

default_factory

```
data-derive-dont-store
```
— 根据状态计算布尔值；不要缓存相互镜像的标志位
```
data-mutation-contract
```
— 要么修改对象要么返回新对象；不要两者兼具

data-aware-datetimes

— 使用时区感知的

datetime.now(timezone.utc)

；

utcnow()

已被弃用

```
data-discriminated-unions
```
— 为变体添加标签，而非使用可选字段集合
```
data-explicit-variants
```
— 为每种模式创建具体类，优于
```
is_thread
```
/
```
is_edit
```
标志位
```
data-phased-composition
```
— 将共存的可选字段分组到一个嵌套的可选结构中
```
data-encapsulate-mutable-state
```
— 将可变状态限制在最窄的明确范围内
```
data-sentinel-when-none-is-valid
```
— 当
```
None
```
是有意义的值时，使用私有标记值

data-newtype-for-ids

— 使用

NewType('UserId', str)

确保ID不可互换

```
data-delete-dead-variants
```
— 移除未被构造的联合类型分支

Error Handling (

error-

)

错误处理 (

error-

)

```
error-specific-exceptions
```
— Catch specific types; never bare
```
except:
```
or
```
except BaseException:
```
(breaks Ctrl-C and async cancellation);
```
except Exception:
```
is cancellation-safe on 3.8+
```
error-context-managers
```
—
```
with
```
/
```
async with
```
for files, locks, sessions
```
error-assert-debug-only
```
—
```
assert
```
vanishes under
```
-O
```
; not for runtime contracts
```
error-validate-at-boundaries
```
— Fail fast at system edges before expensive work
```
error-trust-validated-state
```
— Trust immutable, locally-constructed state
```
error-consolidate-try-except
```
— Merge blocks with the same catch and handling

error-assert-never-exhaustiveness

—

typing.assert_never

for exhaustiveness

error-raise-from-for-chains

—

raise NewErr(...) from original

to preserve causality

```
error-inherit-base-exceptions
```
— New exceptions inherit existing bases for compatibility

error-log-exception-context

—

logger.exception(...)

inside

except

; keep the traceback in the log

```
error-repr-in-messages
```
—
```
f"tool {name!r}"
```
for identifiers in error text

```
error-specific-exceptions
```
— 捕获特定类型；绝不要使用裸
```
except:
```
或
```
except BaseException:
```
（会破坏Ctrl-C和异步取消）；Python 3.8+中
```
except Exception:
```
是支持取消操作的
```
error-context-managers
```
— 对文件、锁、会话使用
```
with
```
/
```
async with
```
上下文管理器
```
error-assert-debug-only
```
—
```
assert
```
在
```
-O
```
模式下会被移除；不要用于运行时契约
```
error-validate-at-boundaries
```
— 在执行昂贵操作前，在系统边界快速失败
```
error-trust-validated-state
```
— 信任不可变的、本地构造的状态
```
error-consolidate-try-except
```
— 合并具有相同捕获逻辑的try-except块

error-assert-never-exhaustiveness

— 使用

typing.assert_never

确保穷尽性

error-raise-from-for-chains

— 使用

raise NewErr(...) from original

保留因果关系

```
error-inherit-base-exceptions
```
— 新异常继承现有基类以保证兼容性

error-log-exception-context

— 在

except

块内使用

logger.exception(...)

；在日志中保留回溯信息

```
error-repr-in-messages
```
— 在错误文本中对标识符使用
```
f"tool {name!r}"
```
格式

Type Safety (

types-

)

类型安全 (

types-

)

types-fix-errors-not-ignore

— Fix type errors;

# type: ignore

is a last resort

```
types-avoid-any
```
— Protocols, TypeVars, unions over
```
Any
```
```
types-typeddict-over-dict-any
```
—
```
TypedDict
```
/ dataclass when structure is known

types-literal-for-fixed-sets

—

Literal["a", "b"]

for fixed strings

```
types-fix-types-not-cast
```
— Fix the definition;
```
cast()
```
only when runtime genuinely narrows

types-isinstance-for-narrowing

—

isinstance()

over

hasattr

type(x).__name__

```
types-narrow-to-runtime-reality
```
— Annotations match what control flow actually allows
```
types-trust-the-checker
```
— Drop runtime checks the types already enforce
```
types-remove-redundant-optional
```
— Drop
```
| None
```
when values are guaranteed present

types-type-checking-imports

—

if TYPE_CHECKING:

for optional or heavy imports

```
types-fix-errors-not-ignore
```
— 修复类型错误；
```
# type: ignore
```
是最后的手段
```
types-avoid-any
```
— 使用Protocols、TypeVars、联合类型而非
```
Any
```
```
types-typeddict-over-dict-any
```
— 当结构已知时，使用
```
TypedDict
```
/ dataclass

types-literal-for-fixed-sets

— 对固定字符串集合使用

Literal["a", "b"]

```
types-fix-types-not-cast
```
— 修复定义；仅当运行时真正缩小类型范围时使用
```
cast()
```

types-isinstance-for-narrowing

— 使用

isinstance()

而非

hasattr

type(x).__name__

进行类型收窄

```
types-narrow-to-runtime-reality
```
— 注解与控制流实际允许的类型匹配
```
types-trust-the-checker
```
— 移除类型检查器已能保证的运行时检查
```
types-remove-redundant-optional
```
— 当值确保存在时，移除
```
| None
```

types-type-checking-imports

— 对可选或重量级导入使用

if TYPE_CHECKING:

API Design (

api-

)

API设计 (

api-

)

```
api-required-before-optional
```
— Required fields before optional (Python enforces this)
```
api-keyword-only-params
```
—
```
*
```
marker for optional/config params

api-no-boolean-flag-params

—

Literal

Enum

over

True, False

soup

```
api-immutable-transforms
```
— Return new collections; don't mutate inputs
```
api-model-cohesion
```
— Flat models; no duplicate or single-key-wrapped fields

api-underscore-for-private

—

_prefix

for internals; exclude from

__all__

api-deprecated-aliases

—

warnings.deprecated()

(3.13+) for renamed APIs

```
api-no-private-access
```
— Don't reach into
```
_prefixed
```
names from outside the module
```
api-instance-vs-module-fn
```
— Pick the namespace that matches ownership

```
api-required-before-optional
```
— 必填字段放在可选字段之前（Python强制要求）
```
api-keyword-only-params
```
— 使用
```
*
```
标记可选/配置参数

api-no-boolean-flag-params

— 使用

Literal

Enum

而非大量

True, False

参数

```
api-immutable-transforms
```
— 返回新集合；不要修改输入
```
api-model-cohesion
```
— 使用扁平模型；不要有重复或单键包装的字段
```
api-underscore-for-private
```
— 使用
```
_前缀
```
标记内部实现；从
```
__all__
```
中排除

api-deprecated-aliases

— 对重命名的API使用

warnings.deprecated()

（3.13+）

```
api-no-private-access
```
— 不要从模块外部访问
```
_前缀
```
命名的对象
```
api-instance-vs-module-fn
```
— 选择与所有权匹配的命名空间

Code Simplification (

simplify-

)

代码简化 (

simplify-

)

```
simplify-early-return
```
— Return early; don't nest the happy path
```
simplify-extract-after-duplication
```
— Second copy is the decision point; third is the safe default
```
simplify-cached-property
```
—
```
@cached_property
```
on immutable instances; not thread-safe
```
simplify-comprehensions
```
— Comprehensions over
```
for
```
+
```
.append()
```

simplify-any-all-builtins

—

any()

all()

over manual flag +

break

```
simplify-fallback-or
```
—
```
x or default
```
when falsy values aren't semantic

simplify-flatten-nested-if

—

if cond1 and cond2:

when no intervening code

```
simplify-inline-single-use-vars
```
— Drop intermediates used once
```
simplify-remove-dead-code
```
— Delete commented-out code; git preserves history

```
simplify-early-return
```
— 提前返回；不要将正常路径嵌套
```
simplify-extract-after-duplication
```
— 出现第二次重复时考虑提取；第三次重复时默认提取
```
simplify-cached-property
```
— 在不可变实例上使用
```
@cached_property
```
；注意它不是线程安全的
```
simplify-comprehensions
```
— 使用推导式而非
```
for
```
+
```
.append()
```

simplify-any-all-builtins

— 使用

any()

all()

而非手动标记 +

break

```
simplify-fallback-or
```
— 当假值无语义时，使用
```
x or default
```

simplify-flatten-nested-if

— 当没有中间代码时，使用

if cond1 and cond2:

```
simplify-inline-single-use-vars
```
— 移除仅使用一次的中间变量
```
simplify-remove-dead-code
```
— 删除注释掉的代码；git会保留历史记录

Performance (

perf-

)

性能优化 (

perf-

)

```
perf-set-for-membership
```
—
```
set
```
for repeated
```
in
```
checks
```
perf-dict-index-over-nested-loops
```
— Build a
```
dict
```
for lookups

perf-lru-cache-pure-fns

—

functools.lru_cache

functools.cache

on pure functions

```
perf-generator-over-list
```
— Stream with generators when memory or latency matters
```
perf-combine-iterations
```
— Fuse
```
filter
```
+
```
map
```
into one pass
```
perf-compile-regex-module-level
```
— Compile static regex at module scope; matters in tight loops
```
perf-type-adapter-constant
```
— Module-scope
```
TypeAdapter
```
(applicability: pydantic)
```
perf-isinstance-tuple-syntax
```
— Tuple form is marginally faster; profiled hot paths only

```
perf-set-for-membership
```
— 对重复的
```
in
```
检查使用
```
set
```
```
perf-dict-index-over-nested-loops
```
— 构建
```
dict
```
用于查找

perf-lru-cache-pure-fns

— 对纯函数使用

functools.lru_cache

functools.cache

```
perf-generator-over-list
```
— 当内存或延迟很重要时，使用生成器流式处理
```
perf-combine-iterations
```
— 将
```
filter
```
+
```
map
```
合并为一次遍历
```
perf-compile-regex-module-level
```
— 在模块作用域编译静态正则表达式；在密集循环中效果显著
```
perf-type-adapter-constant
```
— 在模块作用域定义
```
TypeAdapter
```
(applicability: pydantic)
```
perf-isinstance-tuple-syntax
```
— 元组形式速度略快；仅在经过性能分析的热点路径中使用

Naming (

naming-

)

命名规范 (

naming-

)

```
naming-rename-on-behavior-change
```
— Rename when behavior changes; stale names mislead
```
naming-consistent-terminology
```
— Same concept, same word across code/docs/errors

naming-specific-over-generic

—

toolset_id

; not bare

id

naming-drop-redundant-prefixes

—

ToolConfig.description

; not

ToolConfig.tool_description

```
naming-upper-case-constants
```
—
```
MAX_RETRIES
```
;
```
_
```
prefix for internal
```
naming-no-type-suffixes
```
— No
```
_dict
```
/
```
_list
```
suffixes; types annotate types

```
naming-rename-on-behavior-change
```
— 当行为改变时重命名；过时的名称会误导他人
```
naming-consistent-terminology
```
— 在代码/文档/错误信息中，同一概念使用相同术语

naming-specific-over-generic

— 使用

toolset_id

；不要使用裸

id

naming-drop-redundant-prefixes

— 使用

ToolConfig.description

；不要使用

ToolConfig.tool_description

```
naming-upper-case-constants
```
— 使用
```
MAX_RETRIES
```
；内部常量使用
```
_
```
前缀
```
naming-no-type-suffixes
```
— 不要使用
```
_dict
```
/
```
_list
```
后缀；类型由注解说明

Imports & Structure (

imports-

)

导入与结构 (

imports-

)

```
imports-no-side-effects
```
— Modules must be cheap to import — no network/model/env reads at import
```
imports-top-of-file
```
— Imports at the top; documented exceptions for circular / optional / deferred

imports-optional-dependencies

—

try

except ImportError

with install hints

```
imports-scope-helpers-to-usage
```
— Define helpers near where they're used
```
imports-remove-unused
```
— Delete unused imports
```
imports-no-duplicates
```
— One import per name

```
imports-no-side-effects
```
— 模块导入必须轻量化——导入时不要进行网络/模型/环境读取操作
```
imports-top-of-file
```
— 导入放在文件顶部；循环依赖、可选依赖、延迟导入等情况需注明

imports-optional-dependencies

— 使用

try

except ImportError

并提供安装提示

```
imports-scope-helpers-to-usage
```
— 在使用辅助函数的附近定义它们
```
imports-remove-unused
```
— 删除未使用的导入
```
imports-no-duplicates
```
— 每个名称仅导入一次

How to Use

使用方法

Read individual rule files for detail:

rules/data-mutable-defaults.md
rules/error-specific-exceptions.md

Each rule has:

Impact level in frontmatter
Brief explanation
Incorrect example
Correct example
Optional note on edge cases

For the full compiled guide with all rules expanded:

AGENTS.md

查看单个规则文件获取详细信息：

rules/data-mutable-defaults.md
rules/error-specific-exceptions.md

每个规则包含：

前置元数据中的影响级别
简要说明
错误示例
正确示例
可选的边缘情况说明

如需查看包含所有展开规则的完整编译指南，请参考：

AGENTS.md

。

python-best-practices

Original

Translation

Python Best Practices

Python最佳实践

When to Apply

适用场景

Impact Levels

影响级别

Python Version Baseline

Python版本基准

Rule Categories by Priority

按优先级排序的规则分类

Quick Reference

快速参考

Data Modeling (
`data-`
)

数据建模 (
`data-`
)

Error Handling (
`error-`
)

错误处理 (
`error-`
)

Type Safety (
`types-`
)

类型安全 (
`types-`
)

API Design (
`api-`
)

API设计 (
`api-`
)

Code Simplification (
`simplify-`
)

代码简化 (
`simplify-`
)

Performance (
`perf-`
)

性能优化 (
`perf-`
)

Naming (
`naming-`
)

命名规范 (
`naming-`
)

Imports & Structure (
`imports-`
)

导入与结构 (
`imports-`
)

How to Use

使用方法

python-best-practices

Original

Translation

Python Best Practices

Python最佳实践

When to Apply

适用场景

Impact Levels

影响级别

Python Version Baseline

Python版本基准

Rule Categories by Priority

按优先级排序的规则分类

Quick Reference

快速参考

Data Modeling (data-)

数据建模 (data-)

Error Handling (error-)

错误处理 (error-)

Type Safety (types-)

类型安全 (types-)

API Design (api-)

API设计 (api-)

Code Simplification (simplify-)

代码简化 (simplify-)

Performance (perf-)

性能优化 (perf-)

Naming (naming-)

命名规范 (naming-)

Imports & Structure (imports-)

导入与结构 (imports-)

How to Use

使用方法

Data Modeling (
`data-`
)

数据建模 (
`data-`
)

Error Handling (
`error-`
)

错误处理 (
`error-`
)

Type Safety (
`types-`
)

类型安全 (
`types-`
)

API Design (
`api-`
)

API设计 (
`api-`
)

Code Simplification (
`simplify-`
)

代码简化 (
`simplify-`
)

Performance (
`perf-`
)

性能优化 (
`perf-`
)

Naming (
`naming-`
)

命名规范 (
`naming-`
)

Imports & Structure (
`imports-`
)

导入与结构 (
`imports-`
)