python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Development

Python开发

Functional-first, production-first Python 3.14+ with uv, type safety, immutability, and small composable modules.

采用函数优先、生产优先理念的Python 3.14+开发，搭配uv、类型安全、不可变性及小型可组合模块。

Activation Triggers

激活触发条件

```
.py
```
files,
```
pyproject.toml
```
, uv commands, Python packaging
pip, pip3, poetry, venv, virtualenv, inline script metadata
Python, typing, asyncio, pytest, mypy, ruff, dataclasses, itertools, functools
Async I/O, data pipelines, CLI tooling, validation, parsing, test strategy

```
.py
```
文件、
```
pyproject.toml
```
、uv命令、Python打包
pip、pip3、poetry、venv、virtualenv、内联脚本元数据
Python、类型标注、asyncio、pytest、mypy、ruff、dataclasses、itertools、functools
异步I/O、数据流水线、CLI工具、验证、解析、测试策略

Workflow

工作流

text

1. MODEL    -> types, invariants, boundaries
2. COMPOSE  -> pure functions, pipelines, small modules
3. VALIDATE -> parse at edges, return errors early
4. TEST     -> pytest, fixtures, async tests
5. HARDEN   -> ruff + format + mypy + regression tests

text

1. 建模    -> 类型、不变量、边界
2. 组合    -> 纯函数、流水线、小型模块
3. 验证    -> 边缘处解析、提前返回错误
4. 测试    -> pytest、夹具、异步测试
5. 加固    -> ruff + 格式化 + mypy + 回归测试

Core Principles

核心原则

Functional core, imperative shell
Immutability by default; copy-on-write
Explicit types and error paths
Small composable units
Production defaults: logging, config, timeouts, retries
Prefer
```
uv
```
for running Python, dependency management, environments, scripts, and builds

函数式核心，命令式外壳
默认不可变；写时复制
显式类型与错误路径
小型可组合单元
生产环境默认配置：日志、配置、超时、重试
运行Python、管理依赖、创建环境、脚本及构建时优先使用
```
uv
```

When to Use

适用场景

New or refactored Python modules
Async I/O, data pipelines, CLI tooling
Type-heavy APIs, validation, parsing
Test strategy or flaky tests
Any request that mentions Python setup, Python dependencies, virtual environments, or script execution

新建或重构Python模块
异步I/O、数据流水线、CLI工具
重度类型API、验证、解析
测试策略或不稳定测试用例
任何涉及Python环境搭建、依赖管理、虚拟环境或脚本执行的需求

When Not to Use

不适用场景

Non-Python runtimes
Browser E2E tests (use Playwright)

非Python运行时
浏览器端到端测试（请使用Playwright）

uv-first workflow

uv优先工作流

Use

uv

instead of raw

python

pip

poetry

, or

python -m venv

使用

uv

替代原生

python

、

pip

、

poetry

或

python -m venv

。

Quick reference

快速参考

bash

uv run python script.py
uv run pytest
uv run --with requests python script.py
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff
uv venv
uv run python -m ast path/to/file.py >/dev/null
uv init --script example.py --python 3.12
uv add --script example.py requests rich
uv lock --script example.py

bash

uv run python script.py
uv run pytest
uv run --with requests python script.py
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff
uv venv
uv run python -m ast path/to/file.py >/dev/null
uv init --script example.py --python 3.12
uv add --script example.py requests rich
uv lock --script example.py

Prefer these replacements

优先采用以下替代方案

```
python script.py
```
->
```
uv run python script.py
```
```
python -m pytest
```
->
```
uv run pytest
```
```
pip install x
```
->
```
uv add x
```
```
python -m venv .venv
```
->
```
uv venv
```

python -m py_compile foo.py

uv run python -m ast foo.py >/dev/null

```
python script.py
```
→
```
uv run python script.py
```
```
python -m pytest
```
→
```
uv run pytest
```
```
pip install x
```
→
```
uv add x
```
```
python -m venv .venv
```
→
```
uv venv
```

python -m py_compile foo.py

→

uv run python -m ast foo.py >/dev/null

Inline script metadata

内联脚本元数据

For standalone scripts, prefer uv inline metadata over ad-hoc setup.

python

undefined

对于独立脚本，优先使用uv内联元数据而非临时配置。

python

undefined

/// script

requires-python = ">=3.12"

dependencies = [

"requests<3",

"rich",

]

///


Then run:

```bash
uv run script.py

Helpful commands:

bash

uv init --script script.py --python 3.12
uv add --script script.py requests rich
uv lock --script script.py

For executable scripts:

python

#!/usr/bin/env -S uv run --script


然后运行：

```bash
uv run script.py

实用命令：

bash

uv init --script script.py --python 3.12
uv add --script script.py requests rich
uv lock --script script.py

对于可执行脚本：

python

#!/usr/bin/env -S uv run --script

/// script

dependencies = ["httpx"]

///

undefined

undefined

Project quick start

项目快速启动

bash

uv init my-project && cd my-project
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff

uv run python script.py
uv run pytest

bash

uv init my-project && cd my-project
uv add requests pydantic httpx
uv add --dev pytest pytest-asyncio mypy ruff

uv run python script.py
uv run pytest

Quality gates

质量门禁

bash

uv run ruff check src/
uv run ruff format --check src/
uv run mypy src/
uv run pytest

bash

uv run ruff check src/
uv run ruff format --check src/
uv run mypy src/
uv run pytest

Build backend

构建后端

Use

uv_build

for pure Python packages. For extension modules, prefer another backend such as

hatchling

toml

[build-system]
requires = ["uv_build>=0.9.28,<0.10.0"]
build-backend = "uv_build"

Prefer the standard

src/

layout unless the repo has a strong reason not to.

纯Python包请使用

uv_build

。对于扩展模块，优先选择其他后端如

hatchling

。

toml

[build-system]
requires = ["uv_build>=0.9.28,<0.10.0"]
build-backend = "uv_build"

除非仓库有特殊理由，否则优先采用标准

src/

目录结构。

Must / Must Not

必须/禁止

MUST: type hints on public APIs; validate inputs at boundaries; prefer pathlib
MUST: use
```
uv
```
for running Python, adding deps, script metadata, and env setup
MUST NOT: use raw
```
pip
```
,
```
pip3
```
,
```
poetry
```
, or
```
python -m venv
```
when uv is the intended workflow
MUST NOT: use mutable default args; bare except; mix sync/async in one call chain

必须：公共API添加类型提示；在边界处验证输入；优先使用pathlib
必须：运行Python、添加依赖、脚本元数据及环境搭建时使用
```
uv
```
禁止：当计划使用uv工作流时，使用原生
```
pip
```
、
```
pip3
```
、
```
poetry
```
或
```
python -m venv
```
禁止：使用可变默认参数；裸except语句；在同一调用链中混合同步/异步代码

Notes

注意事项

Core patterns, async examples, and anti-patterns live in

reference.md

and the cookbooks. Read the relevant cookbook when the task narrows:

async work ->
```
cookbook/async.md
```
functional structure ->
```
cookbook/patterns*.md
```
tests ->
```
cookbook/testing*.md
```
language features ->
```
cookbook/modern*.md
```

核心模式、异步示例及反模式请参考

reference.md

和食谱文档。当任务范围缩小后，请阅读对应食谱文档：

异步工作 →
```
cookbook/async.md
```
函数式结构 →
```
cookbook/patterns*.md
```
测试 →
```
cookbook/testing*.md
```
语言特性 →
```
cookbook/modern*.md
```

Research tools

研究工具

bash

undefined

bash

undefined

gh search code for real-world examples

gh搜索代码获取真实场景示例

gh search code "asyncio.TaskGroup(" --language=python gh search code "class.*Protocol):" --language=python gh search code "async with httpx.AsyncClient(" --language=python

undefined

gh search code "asyncio.TaskGroup(" --language=python gh search code "class.*Protocol):" --language=python gh search code "async with httpx.AsyncClient(" --language=python

undefined

References

参考资料

reference.md - Data structures, best practices, idioms, error handling
patterns.md - Functional patterns
async.md - Async/await deep dive
testing.md - pytest patterns & fixtures
design-patterns.md - Builder, DI, Factory, Strategy, Repository
modern.md - Python 3.8-3.14 key features

reference.md - 数据结构、最佳实践、惯用写法、错误处理
patterns.md - 函数式模式
async.md - Async/await深度解析
testing.md - pytest模式与夹具
design-patterns.md - 建造者、依赖注入、工厂、策略、仓库模式
modern.md - Python 3.8-3.14核心特性