SuperAPI AI Directory

python-best-practices

Coding & development

View repository

Updated 10-16 09:30

About this skill

Python programming best practices

Type annotations

  • Alwaysadd type annotations to function parameters and return values
  • Use Type | None instead of Optional[Type](Python 3.10+)
  • Add from __future__ import annotationsat the top of the file to enable deferred type evaluation
  • Name TypeVar with the T suffix:ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)
  • For read-only input parameters use Mapping instead of MutableMapping
  • For internally called methods, prefer # type: ignore[具体规则] instead of redundant type conversions or isinstance checks; comments need to satisfy both mypy and pyright, avoiding missing other errors
from __future__ import annotations
from collections.abc import Mapping
from typing import TypeVar

ResponseT = TypeVar("ResponseT", bound=BaseResponse)
✅ Correct

def process(data: list[str], limit: int | None = None) -> dict[str, int]: ...

❌ Incorrect

from typing import List, Optional, Dict def process(data: List[str], limit: Optional[int] = None) -> Dict[str, int]: ...


---

## 函数参数

- 位置参数:最多 3 个完全必须的参数
- 可选参数放在 `*` 之后(强制关键字参数)
- 提供基于字符串的重载,避免调用方引入额外的 import

```python
from typing import Literal

def create_agent(
    name: str,
    tool_mode: Literal["auto", "required", "none"] | ChatToolMode,
) -> Agent:
    if isinstance(tool_mode, str):
        tool_mode = ChatToolMode(tool_mode)
    ...
  • Avoid shadowing built-in names (use next_item instead of next, use type_ instead of type)
  • Unless subclass extension is needed, avoid using **kwargs; prefer named parameters

Docstrings

Use Google-style docstrings for all public APIs:

def calculate_discount(price: float, rate: float) -> float:
    """计算折扣后的价格。

    Args:
        price: 原始价格,必须为正数。
        rate: 折扣率,范围 0.0 到 1.0。

    Returns:
        折扣后的价格。

    Raises:
        ValueError: 当 rate 不在 [0, 1] 范围内时抛出。

    Examples:
        >>> calculate_discount(100.0, 0.2)
        80.0
    """
    if not 0.0 <= rate <= 1.0:
        raise ValueError(f"折扣率必须在 0 到 1 之间,当前值: {rate}")
    return price * (1 - rate)
  • Always add descriptions for custom exceptions
  • Explicitly use the Keyword Args: block when there are keyword arguments
  • Standard Python exceptions only need documentation when the triggering conditions are not obvious

Data structure selection

Choose the correct container type

from collections import defaultdict, Counter, deque

# ✅ 使用 set 进行成员检测(O(1) vs list 的 O(n))
valid_statuses = {"pending", "active", "closed"}
if status in valid_statuses:
    ...

# ✅ 使用 defaultdict 避免 KeyError
word_count: defaultdict[str, int] = defaultdict(int)
for word in words:
    word_count[word] += 1

# ✅ 使用 Counter 统计频次
from collections import Counter
top_words = Counter(words).most_common(10)

# ✅ 使用 deque 实现队列(两端 O(1),list 头部操作是 O(n))
queue: deque[str] = deque()
queue.append("item")
queue.appendleft("first")
first = queue.popleft()

Use dataclass, namedtuple, and pydantic

from dataclasses import dataclass, field
from typing import NamedTuple
from pydantic import BaseModel, Field

# ✅ 不可变数据用 NamedTuple
class Coordinate(NamedTuple):
    latitude: float
    longitude: float

# ✅ 可变结构用 dataclass
@dataclass
class Config:
    host: str = "localhost"
    port: int = 8080
    tags: list[str] = field(default_factory=list)

# ✅ 不可变且需要性能时使用 frozen=True
@dataclass(frozen=True)
class CacheKey:
    user_id: int
    resource: str

# ✅ 边界数据、配置加载、接口入参校验优先使用 Pydantic
class UserProfile(BaseModel):
    user_id: int
    name: str = Field(min_length=1)
    email: str
    tags: list[str] = Field(default_factory=list)
  • dataclass is suitable for internal domain objects and lightweight data carriers
  • NamedTuple is suitable for immutable, position-semantics-oriented small structures
  • pydantic is suitable for data modeling at system boundaries: configuration parsing, API requests/responses, message payload validation and serialization
  • When runtime validation, default value normalization, field constraints, or JSON Schema/OpenAPI generation are needed, prefer pydantic

Performance optimization

Generators save memory

# ❌ 一次性加载所有数据到内存
def read_large_file(path: str) -> list[str]:
    with open(path) as f:
        return f.readlines()  # 可能占用大量内存

# ✅ 使用生成器按需处理
def read_large_file(path: str):
    with open(path) as f:
        yield from f

# ✅ 生成器表达式替代列表推导(当不需要随机访问时)
total = sum(x * x for x in range(1_000_000))  # 内存友好

Cache computation results

from functools import lru_cache, cache

# ✅ 缓存纯函数的计算结果
@cache  # Python 3.9+,等价于 lru_cache(maxsize=None)
def fibonacci(n: int) -> int:
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

# ✅ 带大小限制的 LRU 缓存
@lru_cache(maxsize=128)
def get_user_permissions(user_id: int) -> frozenset[str]:
    return frozenset(db.query_permissions(user_id))

String concatenation

# ❌ 循环中拼接字符串(每次创建新对象,O(n²))
result = ""
for item in items:
    result += str(item) + ", "

# ✅ 使用 join(O(n))
result = ", ".join(str(item) for item in items)

# ✅ 大量格式化用 f-string
parts = [f"{k}={v}" for k, v in config.items()]
output = ", ".join(parts)

Concurrency and async

Choose the correct concurrency model

# I/O 密集型网络任务 → asyncio
import asyncio
import httpx

async def fetch_all(urls: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.json() for r in responses]

# 多线程、多进程任务统一使用 joblib
from joblib import Parallel, delayed

def process_data(chunk: list) -> list:
    return [expensive_computation(item) for item in chunk]

def parallel_process(data: list, workers: int = 4) -> list[int]:
    return Parallel(n_jobs=workers, prefer="processes")(
        delayed(expensive_computation)(item) for item in data
    )

def parallel_fetch(paths: list[str], workers: int = 8) -> list[str]:
    return Parallel(n_jobs=workers, prefer="threads")(
        delayed(read_text)(path) for path in paths
    )
  • Consider coroutine concurrency and thread/process concurrency separately: for async I/O use asyncio, for multithreading/multiprocessing uniformly use joblib
  • joblib.Parallel(..., prefer="threads") is suitable for I/O-bound blocking tasks
  • joblib.Parallel(..., prefer="processes") is suitable for CPU-bound tasks
  • By default prefer loky process backend, avoid directly scattering ThreadPoolExecutor / ProcessPoolExecutor 's implementation details
  • When large arrays need to be shared or intermediate results cached, prefer utilizing joblib 's memory mapping and persistence capabilities

Async best practices

import asyncio

# ✅ 并发执行独立任务
async def main():
    # 并发(同时执行)
    results = await asyncio.gather(
        fetch_users(),
        fetch_products(),
        fetch_orders(),
    )

    # 有超时限制
    try:
        result = await asyncio.wait_for(slow_operation(), timeout=5.0)
    except asyncio.TimeoutError:
        logger.warning("操作超时")

# ✅ 异步上下文管理器
async def process():
    async with aiofiles.open("data.txt") as f:
        content = await f.read()

Error handling

Define business exception hierarchy

# ✅ 创建应用专属异常类
class AppError(Exception):
    """应用基础异常。"""

class ValidationError(AppError):
    """数据验证失败。"""
    def __init__(self, field: str, message: str) -> None:
        self.field = field
        super().__init__(f"字段 '{field}' 验证失败: {message}")

class NotFoundError(AppError):
    """资源不存在。"""
    def __init__(self, resource: str, id: int | str) -> None:
        super().__init__(f"{resource} (id={id}) 不存在")

Handle exception chains gracefully

# ✅ 保留原始异常上下文
try:
    data = json.loads(raw_content)
except json.JSONDecodeError as e:
    raise ValidationError("body", "JSON 格式无效") from e

# ✅ 明确抑制异常链(有意为之时)
try:
    return cache[key]
except KeyError:
    return compute_value(key)  # KeyError 不是真正的错误

Paths and file operations

from pathlib import Path

# ✅ 使用 pathlib 替代 os.path
base_dir = Path(__file__).parent
config_path = base_dir / "config" / "settings.toml"

# 检查并创建目录
output_dir = Path("output")
output_dir.mkdir(parents=True, exist_ok=True)

# 遍历文件
for py_file in base_dir.rglob("*.py"):
    print(py_file.relative_to(base_dir))

# 读写文件
content = config_path.read_text(encoding="utf-8")
config_path.write_text(updated_content, encoding="utf-8")

Type safety

Use Protocol instead of abstract base classes

from typing import Protocol, runtime_checkable

# ✅ 结构化子类型(鸭子类型的类型安全版)
@runtime_checkable
class Serializable(Protocol):
    def to_dict(self) -> dict: ...
    @classmethod
    def from_dict(cls, data: dict) -> "Serializable": ...

def save(obj: Serializable) -> None:
    data = obj.to_dict()
    # 任何实现 to_dict/from_dict 的类都可以传入

TypedDict adds types to dictionaries

from typing import TypedDict

class UserData(TypedDict):
    id: int
    name: str
    email: str

class UserDataPartial(TypedDict, total=False):
    name: str
    email: str

def update_user(user_id: int, updates: UserDataPartial) -> None:
    ...

Avoiding common pitfalls

Mutable default arguments

# ❌ 危险!所有调用共享同一个列表
def add_item(item, container=[]):
    container.append(item)
    return container

# ✅ 使用 None 作为默认值
def add_item(item: str, container: list[str] | None = None) -> list[str]:
    if container is None:
        container = []
    container.append(item)
    return container

Loop variables in closures

# ❌ 所有函数都引用同一个 i(循环结束后 i=9)
funcs = [lambda: i for i in range(10)]

# ✅ 通过默认参数捕获当前值
funcs = [lambda i=i: i for i in range(10)]

Integer cache range

# ⚠️ Python 只缓存 -5 到 256 的小整数
a = 256
b = 256
assert a is b  # True(缓存)

a = 257
b = 257
assert a == b  # True(值相等)
assert a is not b  # True(不是同一对象)

# ✅ 比较值用 ==,比较身份用 is(仅用于 None/True/False)

String interning

# ✅ 与 None 比较使用 is
value = get_optional_value()
if value is None:
    ...

# ✅ 类型检查
if isinstance(value, str):
    ...

Code organization

Place module-level constants at the top

# ✅ 模块常量与配置
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30.0
SUPPORTED_FORMATS = frozenset({"json", "csv", "parquet"})

Avoid circular imports

# ✅ 在函数内部导入(打破循环依赖)
def get_service():
    from mypackage.services import UserService  # 延迟导入
    return UserService()

# ✅ 使用 TYPE_CHECKING 仅在类型检查时导入
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from mypackage.models import User

Public API design

# ✅ 明确声明公共接口
__all__ = ["PublicClass", "public_function"]

def public_function() -> None:
    """公开函数。"""
    _internal_helper()

def _internal_helper() -> None:
    """内部实现,不对外暴露。"""
    ...

Public API internal call flow diagram

When a public API entry function internally involves multiple private helper functions, nested loops, or a multi-stage pipeline,you mustdraw an ASCII call flow diagram in the module top-level docstring, and use # ═══ §N ═══ section comments to echo the flow diagram. See reference/public-api-flow-diagram.md。