Back to Details

python-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Python Development Patterns

Python开发模式

Idiomatic Python patterns and best practices for building robust, efficient, and maintainable applications.
编写健壮、高效且可维护的Python应用所需的Pythonic编程范式与最佳实践。

When to Activate

适用场景

  • Writing new Python code
  • Reviewing Python code
  • Refactoring existing Python code
  • Designing Python packages/modules
  • 编写新的Python代码
  • 评审Python代码
  • 重构现有Python代码
  • 设计Python包/模块

Core Principles

核心原则

1. Readability Counts

1. 可读性优先

Python prioritizes readability. Code should be obvious and easy to understand.
python
undefined
Python优先重视可读性。代码应清晰易懂。
python
undefined

Good: Clear and readable

良好示例：清晰易读

def get_active_users(users: list[User]) -> list[User]: """Return only active users from the provided list.""" return [user for user in users if user.is_active]
def get_active_users(users: list[User]) -> list[User]: """从提供的列表中返回仅包含活跃用户的列表。""" return [user for user in users if user.is_active]

Bad: Clever but confusing

不良示例：看似巧妙但难以理解

def get_active_users(u): return [x for x in u if x.a]
undefined
def get_active_users(u): return [x for x in u if x.a]
undefined

2. Explicit is Better Than Implicit

2. 显式优于隐式

Avoid magic; be clear about what your code does.
python
undefined
避免魔法操作；明确代码的功能。
python
undefined

Good: Explicit configuration

良好示例：显式配置

import logging
logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' )
import logging
logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' )

Bad: Hidden side effects

不良示例：隐藏的副作用

import some_module some_module.setup() # What does this do?
undefined
import some_module some_module.setup() # 这到底做了什么？
undefined

3. EAFP - Easier to Ask Forgiveness Than Permission

3. EAFP - 先尝试后处理（优于先检查后执行）

Python prefers exception handling over checking conditions.
python
undefined
Python更倾向于使用异常处理而非条件检查。
python
undefined

Good: EAFP style

良好示例：EAFP风格

def get_value(dictionary: dict, key: str) -> Any: try: return dictionary[key] except KeyError: return default_value
def get_value(dictionary: dict, key: str) -> Any: try: return dictionary[key] except KeyError: return default_value

Bad: LBYL (Look Before You Leap) style

不良示例：LBYL（先检查后执行）风格

def get_value(dictionary: dict, key: str) -> Any: if key in dictionary: return dictionary[key] else: return default_value
undefined
def get_value(dictionary: dict, key: str) -> Any: if key in dictionary: return dictionary[key] else: return default_value
undefined

Type Hints

类型提示

Basic Type Annotations

基础类型注解

python
from typing import Optional, List, Dict, Any

def process_user(
    user_id: str,
    data: Dict[str, Any],
    active: bool = True
) -> Optional[User]:
    """Process a user and return the updated User or None."""
    if not active:
        return None
    return User(user_id, data)
python
from typing import Optional, List, Dict, Any

def process_user(
    user_id: str,
    data: Dict[str, Any],
    active: bool = True
) -> Optional[User]:
    """处理用户并返回更新后的User对象或None。"""
    if not active:
        return None
    return User(user_id, data)

Modern Type Hints (Python 3.9+)

现代类型提示（Python 3.9+）

python
undefined
python
undefined

Python 3.9+ - Use built-in types

Python 3.9+ - 使用内置类型

def process_items(items: list[str]) -> dict[str, int]: return {item: len(item) for item in items}
def process_items(items: list[str]) -> dict[str, int]: return {item: len(item) for item in items}

Python 3.8 and earlier - Use typing module

Python 3.8及更早版本 - 使用typing模块

from typing import List, Dict
def process_items(items: List[str]) -> Dict[str, int]: return {item: len(item) for item in items}
undefined
from typing import List, Dict
def process_items(items: List[str]) -> Dict[str, int]: return {item: len(item) for item in items}
undefined

Type Aliases and TypeVar

类型别名与TypeVar

python
from typing import TypeVar, Union
python
from typing import TypeVar, Union

Type alias for complex types

复杂类型的别名

JSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]
def parse_json(data: str) -> JSON: return json.loads(data)
JSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]
def parse_json(data: str) -> JSON: return json.loads(data)

Generic types

泛型类型

T = TypeVar('T')
def first(items: list[T]) -> T | None: """Return the first item or None if list is empty.""" return items[0] if items else None
undefined
T = TypeVar('T')
def first(items: list[T]) -> T | None: """返回列表的第一个元素，若列表为空则返回None。""" return items[0] if items else None
undefined

Protocol-Based Duck Typing

基于协议的鸭子类型

python
from typing import Protocol

class Renderable(Protocol):
    def render(self) -> str:
        """Render the object to a string."""

def render_all(items: list[Renderable]) -> str:
    """Render all items that implement the Renderable protocol."""
    return "\n".join(item.render() for item in items)
python
from typing import Protocol

class Renderable(Protocol):
    def render(self) -> str:
        """将对象渲染为字符串。"""

def render_all(items: list[Renderable]) -> str:
    """渲染所有实现了Renderable协议的对象。"""
    return "\n".join(item.render() for item in items)

Error Handling Patterns

错误处理模式

Specific Exception Handling

特定异常捕获

python
undefined
python
undefined

Good: Catch specific exceptions

良好示例：捕获特定异常

def load_config(path: str) -> Config: try: with open(path) as f: return Config.from_json(f.read()) except FileNotFoundError as e: raise ConfigError(f"Config file not found: {path}") from e except json.JSONDecodeError as e: raise ConfigError(f"Invalid JSON in config: {path}") from e
def load_config(path: str) -> Config: try: with open(path) as f: return Config.from_json(f.read()) except FileNotFoundError as e: raise ConfigError(f"配置文件未找到：{path}") from e except json.JSONDecodeError as e: raise ConfigError(f"配置文件JSON格式无效：{path}") from e

Bad: Bare except

不良示例：裸except语句

def load_config(path: str) -> Config: try: with open(path) as f: return Config.from_json(f.read()) except: return None # Silent failure!
undefined
def load_config(path: str) -> Config: try: with open(path) as f: return Config.from_json(f.read()) except: return None # 静默失败！
undefined

Exception Chaining

异常链

python
def process_data(data: str) -> Result:
    try:
        parsed = json.loads(data)
    except json.JSONDecodeError as e:
        # Chain exceptions to preserve the traceback
        raise ValueError(f"Failed to parse data: {data}") from e
python
def process_data(data: str) -> Result:
    try:
        parsed = json.loads(data)
    except json.JSONDecodeError as e:
        # 链式异常以保留调用栈
        raise ValueError(f"解析数据失败：{data}") from e

Custom Exception Hierarchy

自定义异常层级

python
class AppError(Exception):
    """Base exception for all application errors."""
    pass

class ValidationError(AppError):
    """Raised when input validation fails."""
    pass

class NotFoundError(AppError):
    """Raised when a requested resource is not found."""
    pass
python
class AppError(Exception):
    """所有应用异常的基类。"""
    pass

class ValidationError(AppError):
    """输入验证失败时抛出。"""
    pass

class NotFoundError(AppError):
    """请求的资源不存在时抛出。"""
    pass

Usage

使用示例

def get_user(user_id: str) -> User: user = db.find_user(user_id) if not user: raise NotFoundError(f"User not found: {user_id}") return user
undefined
def get_user(user_id: str) -> User: user = db.find_user(user_id) if not user: raise NotFoundError(f"用户未找到：{user_id}") return user
undefined

Context Managers

上下文管理器

Resource Management

资源管理

python
undefined
python
undefined

Good: Using context managers

良好示例：使用上下文管理器

def process_file(path: str) -> str: with open(path, 'r') as f: return f.read()
def process_file(path: str) -> str: with open(path, 'r') as f: return f.read()

Bad: Manual resource management

不良示例：手动管理资源

def process_file(path: str) -> str: f = open(path, 'r') try: return f.read() finally: f.close()
undefined
def process_file(path: str) -> str: f = open(path, 'r') try: return f.read() finally: f.close()
undefined

Custom Context Managers

自定义上下文管理器

python
from contextlib import contextmanager

@contextmanager
def timer(name: str):
    """Context manager to time a block of code."""
    start = time.perf_counter()
    yield
    elapsed = time.perf_counter() - start
    print(f"{name} took {elapsed:.4f} seconds")
python
from contextlib import contextmanager

@contextmanager
def timer(name: str):
    """用于计时代码块的上下文管理器。"""
    start = time.perf_counter()
    yield
    elapsed = time.perf_counter() - start
    print(f"{name} 耗时 {elapsed:.4f} 秒")

Usage

使用示例

with timer("data processing"): process_large_dataset()
undefined
with timer("数据处理"): process_large_dataset()
undefined

Context Manager Classes

基于类的上下文管理器

python
class DatabaseTransaction:
    def __init__(self, connection):
        self.connection = connection

    def __enter__(self):
        self.connection.begin_transaction()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is None:
            self.connection.commit()
        else:
            self.connection.rollback()
        return False  # Don't suppress exceptions
python
class DatabaseTransaction:
    def __init__(self, connection):
        self.connection = connection

    def __enter__(self):
        self.connection.begin_transaction()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_type is None:
            self.connection.commit()
        else:
            self.connection.rollback()
        return False  # 不抑制异常

Usage

使用示例

with DatabaseTransaction(conn): user = conn.create_user(user_data) conn.create_profile(user.id, profile_data)
undefined
with DatabaseTransaction(conn): user = conn.create_user(user_data) conn.create_profile(user.id, profile_data)
undefined

Comprehensions and Generators

推导式与生成器

List Comprehensions

列表推导式

python
undefined
python
undefined

Good: List comprehension for simple transformations

良好示例：简单转换使用列表推导式

names = [user.name for user in users if user.is_active]
names = [user.name for user in users if user.is_active]

Bad: Manual loop

不良示例：手动循环

names = [] for user in users: if user.is_active: names.append(user.name)
names = [] for user in users: if user.is_active: names.append(user.name)

Complex comprehensions should be expanded

复杂推导式应展开

Bad: Too complex

不良示例：过于复杂

result = [x * 2 for x in items if x > 0 if x % 2 == 0]
result = [x * 2 for x in items if x > 0 if x % 2 == 0]

Good: Use a generator function

良好示例：使用生成器函数

def filter_and_transform(items: Iterable[int]) -> list[int]: result = [] for x in items: if x > 0 and x % 2 == 0: result.append(x * 2) return result
undefined
def filter_and_transform(items: Iterable[int]) -> list[int]: result = [] for x in items: if x > 0 and x % 2 == 0: result.append(x * 2) return result
undefined

Generator Expressions

生成器表达式

python
undefined
python
undefined

Good: Generator for lazy evaluation

良好示例：使用生成器实现惰性求值

total = sum(x * x for x in range(1_000_000))
total = sum(x * x for x in range(1_000_000))

Bad: Creates large intermediate list

不良示例：创建大型中间列表

total = sum([x * x for x in range(1_000_000)])
undefined
total = sum([x * x for x in range(1_000_000)])
undefined

Generator Functions

生成器函数

python
def read_large_file(path: str) -> Iterator[str]:
    """Read a large file line by line."""
    with open(path) as f:
        for line in f:
            yield line.strip()
python
def read_large_file(path: str) -> Iterator[str]:
    """逐行读取大文件。"""
    with open(path) as f:
        for line in f:
            yield line.strip()

Usage

使用示例

for line in read_large_file("huge.txt"): process(line)
undefined
for line in read_large_file("huge.txt"): process(line)
undefined

Data Classes and Named Tuples

数据类与命名元组

Data Classes

数据类

python
from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class User:
    """User entity with automatic __init__, __repr__, and __eq__."""
    id: str
    name: str
    email: str
    created_at: datetime = field(default_factory=datetime.now)
    is_active: bool = True
python
from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class User:
    """用户实体，自动生成__init__、__repr__和__eq__方法。"""
    id: str
    name: str
    email: str
    created_at: datetime = field(default_factory=datetime.now)
    is_active: bool = True

Usage

使用示例

user = User( id="123", name="Alice", email="alice@example.com" )
undefined
user = User( id="123", name="Alice", email="alice@example.com" )
undefined

Data Classes with Validation

带验证的 Data Classes

python
@dataclass
class User:
    email: str
    age: int

    def __post_init__(self):
        # Validate email format
        if "@" not in self.email:
            raise ValueError(f"Invalid email: {self.email}")
        # Validate age range
        if self.age < 0 or self.age > 150:
            raise ValueError(f"Invalid age: {self.age}")
python
@dataclass
class User:
    email: str
    age: int

    def __post_init__(self):
        # 验证邮箱格式
        if "@" not in self.email:
            raise ValueError(f"无效邮箱：{self.email}")
        # 验证年龄范围
        if self.age < 0 or self.age > 150:
            raise ValueError(f"无效年龄：{self.age}")

Named Tuples

命名元组

python
from typing import NamedTuple

class Point(NamedTuple):
    """Immutable 2D point."""
    x: float
    y: float

    def distance(self, other: 'Point') -> float:
        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
python
from typing import NamedTuple

class Point(NamedTuple):
    """不可变的2D点。"""
    x: float
    y: float

    def distance(self, other: 'Point') -> float:
        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5

Usage

使用示例

p1 = Point(0, 0) p2 = Point(3, 4) print(p1.distance(p2)) # 5.0
undefined
p1 = Point(0, 0) p2 = Point(3, 4) print(p1.distance(p2)) # 5.0
undefined

Decorators

装饰器

Function Decorators

函数装饰器

python
import functools
import time

def timer(func: Callable) -> Callable:
    """Decorator to time function execution."""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.4f}s")
        return result
    return wrapper

@timer
def slow_function():
    time.sleep(1)
python
import functools
import time

def timer(func: Callable) -> Callable:
    """用于计时函数执行的装饰器。"""
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} 耗时 {elapsed:.4f}秒")
        return result
    return wrapper

@timer
def slow_function():
    time.sleep(1)

slow_function() prints: slow_function took 1.0012s

调用slow_function()会输出：slow_function took 1.0012s

undefined
undefined

Parameterized Decorators

参数化装饰器

python
def repeat(times: int):
    """Decorator to repeat a function multiple times."""
    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            results = []
            for _ in range(times):
                results.append(func(*args, **kwargs))
            return results
        return wrapper
    return decorator

@repeat(times=3)
def greet(name: str) -> str:
    return f"Hello, {name}!"
python
def repeat(times: int):
    """用于重复执行函数多次的装饰器。"""
    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            results = []
            for _ in range(times):
                results.append(func(*args, **kwargs))
            return results
        return wrapper
    return decorator

@repeat(times=3)
def greet(name: str) -> str:
    return f"Hello, {name}!"

greet("Alice") returns ["Hello, Alice!", "Hello, Alice!", "Hello, Alice!"]

greet("Alice")会返回 ["Hello, Alice!", "Hello, Alice!", "Hello, Alice!"]

undefined
undefined

Class-Based Decorators

基于类的装饰器

python
class CountCalls:
    """Decorator that counts how many times a function is called."""
    def __init__(self, func: Callable):
        functools.update_wrapper(self, func)
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.func.__name__} has been called {self.count} times")
        return self.func(*args, **kwargs)

@CountCalls
def process():
    pass
python
class CountCalls:
    """用于统计函数调用次数的装饰器。"""
    def __init__(self, func: Callable):
        functools.update_wrapper(self, func)
        self.func = func
        self.count = 0

    def __call__(self, *args, **kwargs):
        self.count += 1
        print(f"{self.func.__name__} 已被调用 {self.count} 次")
        return self.func(*args, **kwargs)

@CountCalls
def process():
    pass

Each call to process() prints the call count

每次调用process()都会打印调用次数

undefined
undefined

Concurrency Patterns

并发模式

Threading for I/O-Bound Tasks

线程处理I/O密集型任务

python
import concurrent.futures
import threading

def fetch_url(url: str) -> str:
    """Fetch a URL (I/O-bound operation)."""
    import urllib.request
    with urllib.request.urlopen(url) as response:
        return response.read().decode()

def fetch_all_urls(urls: list[str]) -> dict[str, str]:
    """Fetch multiple URLs concurrently using threads."""
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
        future_to_url = {executor.submit(fetch_url, url): url for url in urls}
        results = {}
        for future in concurrent.futures.as_completed(future_to_url):
            url = future_to_url[future]
            try:
                results[url] = future.result()
            except Exception as e:
                results[url] = f"Error: {e}"
    return results
python
import concurrent.futures
import threading

def fetch_url(url: str) -> str:
    """获取URL内容（I/O密集型操作）。"""
    import urllib.request
    with urllib.request.urlopen(url) as response:
        return response.read().decode()

def fetch_all_urls(urls: list[str]) -> dict[str, str]:
    """使用线程并发获取多个URL的内容。"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
        future_to_url = {executor.submit(fetch_url, url): url for url in urls}
        results = {}
        for future in concurrent.futures.as_completed(future_to_url):
            url = future_to_url[future]
            try:
                results[url] = future.result()
            except Exception as e:
                results[url] = f"错误：{e}"
    return results

Multiprocessing for CPU-Bound Tasks

多进程处理CPU密集型任务

python
def process_data(data: list[int]) -> int:
    """CPU-intensive computation."""
    return sum(x ** 2 for x in data)

def process_all(datasets: list[list[int]]) -> list[int]:
    """Process multiple datasets using multiple processes."""
    with concurrent.futures.ProcessPoolExecutor() as executor:
        results = list(executor.map(process_data, datasets))
    return results
python
def process_data(data: list[int]) -> int:
    """CPU密集型计算。"""
    return sum(x ** 2 for x in data)

def process_all(datasets: list[list[int]]) -> list[int]:
    """使用多进程处理多个数据集。"""
    with concurrent.futures.ProcessPoolExecutor() as executor:
        results = list(executor.map(process_data, datasets))
    return results

Async/Await for Concurrent I/O

Async/Await处理并发I/O

python
import asyncio

async def fetch_async(url: str) -> str:
    """Fetch a URL asynchronously."""
    import aiohttp
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

async def fetch_all(urls: list[str]) -> dict[str, str]:
    """Fetch multiple URLs concurrently."""
    tasks = [fetch_async(url) for url in urls]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    return dict(zip(urls, results))
python
import asyncio

async def fetch_async(url: str) -> str:
    """异步获取URL内容。"""
    import aiohttp
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

async def fetch_all(urls: list[str]) -> dict[str, str]:
    """并发获取多个URL的内容。"""
    tasks = [fetch_async(url) for url in urls]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    return dict(zip(urls, results))

Package Organization

包组织

Standard Project Layout

标准项目结构

myproject/
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── main.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_api.py
│   └── test_models.py
├── pyproject.toml
├── README.md
└── .gitignore
myproject/
├── src/
│   └── mypackage/
│       ├── __init__.py
│       ├── main.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_api.py
│   └── test_models.py
├── pyproject.toml
├── README.md
└── .gitignore

Import Conventions

导入约定

python
undefined
python
undefined

Good: Import order - stdlib, third-party, local

良好示例：导入顺序 - 标准库、第三方库、本地模块

import os import sys from pathlib import Path
import requests from fastapi import FastAPI
from mypackage.models import User from mypackage.utils import format_name
import os import sys from pathlib import Path
import requests from fastapi import FastAPI
from mypackage.models import User from mypackage.utils import format_name

Good: Use isort for automatic import sorting

良好示例：使用isort自动排序导入

pip install isort

pip install isort

undefined
undefined

init.py for Package Exports

init.py用于包导出

python
undefined
python
undefined

mypackage/init.py

mypackage/init.py

"""mypackage - A sample Python package."""
version = "1.0.0"
"""mypackage - 一个示例Python包。"""
version = "1.0.0"

Export main classes/functions at package level

在包级别导出主要类/函数

from mypackage.models import User, Post from mypackage.utils import format_name
all = ["User", "Post", "format_name"]
undefined
from mypackage.models import User, Post from mypackage.utils import format_name
all = ["User", "Post", "format_name"]
undefined

Memory and Performance

内存与性能优化

Using slots for Memory Efficiency

使用__slots__提升内存效率

python
undefined
python
undefined

Bad: Regular class uses dict (more memory)

不良示例：常规类使用__dict__（占用更多内存）

class Point: def init(self, x: float, y: float): self.x = x self.y = y
class Point: def init(self, x: float, y: float): self.x = x self.y = y

Good: slots reduces memory usage

良好示例：__slots__减少内存占用

class Point: slots = ['x', 'y']
def __init__(self, x: float, y: float):
    self.x = x
    self.y = y
undefined
class Point: slots = ['x', 'y']
def __init__(self, x: float, y: float):
    self.x = x
    self.y = y
undefined

Generator for Large Data

生成器处理大数据

python
undefined
python
undefined

Bad: Returns full list in memory

不良示例：在内存中返回完整列表

def read_lines(path: str) -> list[str]: with open(path) as f: return [line.strip() for line in f]
def read_lines(path: str) -> list[str]: with open(path) as f: return [line.strip() for line in f]

Good: Yields lines one at a time

良好示例：逐行生成数据

def read_lines(path: str) -> Iterator[str]: with open(path) as f: for line in f: yield line.strip()
undefined
def read_lines(path: str) -> Iterator[str]: with open(path) as f: for line in f: yield line.strip()
undefined

Avoid String Concatenation in Loops

避免循环中的字符串拼接

python
undefined
python
undefined

Bad: O(n²) due to string immutability

不良示例：由于字符串不可变，时间复杂度为O(n²)

result = "" for item in items: result += str(item)
result = "" for item in items: result += str(item)

Good: O(n) using join

良好示例：使用join，时间复杂度为O(n)

result = "".join(str(item) for item in items)
result = "".join(str(item) for item in items)

Good: Using StringIO for building

良好示例：使用StringIO构建字符串

from io import StringIO
buffer = StringIO() for item in items: buffer.write(str(item)) result = buffer.getvalue()
undefined
from io import StringIO
buffer = StringIO() for item in items: buffer.write(str(item)) result = buffer.getvalue()
undefined

Python Tooling Integration

Python工具集成

Essential Commands

核心命令

bash
undefined
bash
undefined

Code formatting

代码格式化

black . isort .
black . isort .

Linting

代码检查

ruff check . pylint mypackage/
ruff check . pylint mypackage/

Type checking

类型检查

mypy .
mypy .

Testing

测试

pytest --cov=mypackage --cov-report=html
pytest --cov=mypackage --cov-report=html

Security scanning

安全扫描

bandit -r .
bandit -r .

Dependency management

依赖管理

pip-audit safety check
undefined
pip-audit safety check
undefined

pyproject.toml Configuration

pyproject.toml配置

toml
[project]
name = "mypackage"
version = "1.0.0"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

[tool.black]
line-length = 88
target-version = ['py39']

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N", "W"]

[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=mypackage --cov-report=term-missing"
toml
[project]
name = "mypackage"
version = "1.0.0"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.31.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.5.0",
]

[tool.black]
line-length = 88
target-version = ['py39']

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N", "W"]

[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--cov=mypackage --cov-report=term-missing"

Quick Reference: Python Idioms

速查：Python编程范式

IdiomDescription
EAFPEasier to Ask Forgiveness than Permission
Context managersUse 
with
for resource management
List comprehensionsFor simple transformations
GeneratorsFor lazy evaluation and large datasets
Type hintsAnnotate function signatures
DataclassesFor data containers with auto-generated methods
__slots__
For memory optimization
f-stringsFor string formatting (Python 3.6+)
pathlib.Path
For path operations (Python 3.4+)
enumerate
For index-element pairs in loops
范式描述
EAFP先尝试后处理（优于先检查后执行）
上下文管理器使用
with
进行资源管理
列表推导式用于简单的数据转换
生成器用于惰性求值和处理大型数据集
类型提示为函数签名添加注解
数据类用于自动生成方法的数据容器
__slots__
用于内存优化
f-strings用于字符串格式化（Python 3.6+）
pathlib.Path
用于路径操作（Python 3.4+）
enumerate
用于在循环中同时获取索引和元素

Anti-Patterns to Avoid

需避免的反模式

python
undefined
python
undefined

Bad: Mutable default arguments

不良示例：可变默认参数

def append_to(item, items=[]): items.append(item) return items
def append_to(item, items=[]): items.append(item) return items

Good: Use None and create new list

良好示例：使用None并创建新列表

def append_to(item, items=None): if items is None: items = [] items.append(item) return items
def append_to(item, items=None): if items is None: items = [] items.append(item) return items

Bad: Checking type with type()

不良示例：使用type()检查类型

if type(obj) == list: process(obj)
if type(obj) == list: process(obj)

Good: Use isinstance

良好示例：使用isinstance

if isinstance(obj, list): process(obj)
if isinstance(obj, list): process(obj)

Bad: Comparing to None with ==

不良示例：使用==与None比较

if value == None: process()
if value == None: process()

Good: Use is

良好示例：使用is与None比较

if value is None: process()
if value is None: process()

Bad: from module import *

不良示例：from module import *

from os.path import *
from os.path import *

Good: Explicit imports

良好示例：显式导入

from os.path import join, exists
from os.path import join, exists

Bad: Bare except

不良示例：裸except语句

try: risky_operation() except: pass
try: risky_operation() except: pass

Good: Specific exception

良好示例：捕获特定异常

try: risky_operation() except SpecificError as e: logger.error(f"Operation failed: {e}")

__Remember__: Python code should be readable, explicit, and follow the principle of least surprise. When in doubt, prioritize clarity over cleverness.
try: risky_operation() except SpecificError as e: logger.error(f"操作失败：{e}")

__请记住__：Python代码应具备可读性、显式性，并遵循最小意外原则。如有疑问，优先选择清晰而非巧妙的实现。