Python Best Practices

作者 alleneubank2921eb8a685a无许可证52 个星标收录于 2026年10月8日更新于 2026年10月8日仓库3个月前更新

Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

已归档仅含说明Software Development

AI 生成的概览

以类型优先、函数式和错误处理模式指导 Python 编码风格。

功能: 该技能提供用于编写和审阅 .py 文件、pyproject.toml 与 requirements.txt 的 Python 语言惯用法。内容涵盖用冻结数据类、Literal 可辨识联合、NewType 和 Protocol 让非法状态无法表示，以及用 'from err' 链接异常和使用延迟 %s 格式化的结构化日志。它还比较可选的类型检查器 ty、pyright 和 mypy，并展示如何在 pyproject.toml 中配置 ty。
适用场景: 在阅读或编写 Python 源文件、配置文件或依赖清单时使用。适合需要为 Python 代码统一应用类型、错误处理和日志约定的场景。
运行要求: 不附带脚本，仅为说明性内容。可选的类型检查部分提到 ty 工具，可通过 uvx 运行，并提及 pyright 和 mypy 作为替代方案。

Python Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.

Make Illegal States Unrepresentable

Use Python's type system to prevent invalid states at type-check time.

Frozen dataclasses for immutable domain models:

python

from dataclasses import dataclassfrom datetime import datetime
@dataclass(frozen=True)class User:    id: str    email: str    name: str    created_at: datetime
# Frozen dataclasses are immutable — no accidental mutation

from dataclasses import dataclassfrom datetime import datetime
@dataclass(frozen=True)class User:    id: str    email: str    name: str    created_at: datetime
# Frozen dataclasses are immutable — no accidental mutation

Discriminated unions with Literal:

python

from dataclasses import dataclassfrom typing import Literal
@dataclassclass Success:    status: Literal["success"] = "success"    data: str
@dataclassclass Failure:    status: Literal["error"] = "error"    error: Exception
RequestState = Success | Failure
def handle_state(state: RequestState) -> None:    match state:        case Success(data=data):            render(data)        case Failure(error=err):            show_error(err)

from dataclasses import dataclassfrom typing import Literal
@dataclassclass Success:    status: Literal["success"] = "success"    data: str
@dataclassclass Failure:    status: Literal["error"] = "error"    error: Exception
RequestState = Success | Failure
def handle_state(state: RequestState) -> None:    match state:        case Success(data=data):            render(data)        case Failure(error=err):            show_error(err)

NewType for domain primitives:

python

from typing import NewType
UserId = NewType("UserId", str)OrderId = NewType("OrderId", str)
def get_user(user_id: UserId) -> User:    # Type checker prevents passing OrderId here    ...

from typing import NewType
UserId = NewType("UserId", str)OrderId = NewType("OrderId", str)
def get_user(user_id: UserId) -> User:    # Type checker prevents passing OrderId here    ...

Protocol for structural typing:

python

from typing import Protocol
class Readable(Protocol):    def read(self, n: int = -1) -> bytes: ...
def process_input(source: Readable) -> bytes:    # Accepts any object with a read() method — no inheritance required    return source.read()

from typing import Protocol
class Readable(Protocol):    def read(self, n: int = -1) -> bytes: ...
def process_input(source: Readable) -> bytes:    # Accepts any object with a read() method — no inheritance required    return source.read()

Python-Specific Error Handling

Chain exceptions with from err to preserve the original traceback:

python

try:    data = json.loads(raw)except json.JSONDecodeError as err:    raise ValueError(f"invalid JSON payload: {err}") from err

try:    data = json.loads(raw)except json.JSONDecodeError as err:    raise ValueError(f"invalid JSON payload: {err}") from err

Structured Logging

Use a module-level logger with %s formatting (deferred string interpolation):

python

import logging
logger = logging.getLogger("myapp.widgets")
def create_widget(name: str) -> Widget:    logger.debug("creating widget: %s", name)    widget = Widget(name=name)    logger.debug("created widget id=%s", widget.id)    return widget

import logging
logger = logging.getLogger("myapp.widgets")
def create_widget(name: str) -> Widget:    logger.debug("creating widget: %s", name)    widget = Widget(name=name)    logger.debug("created widget id=%s", widget.id)    return widget

Optional: ty

For fast type checking, consider ty from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright.

bash

uvx ty check          # run directly, no install neededuvx ty check src/     # check specific path

uvx ty check          # run directly, no install neededuvx ty check src/     # check specific path

When to choose:

ty — fastest, good for CI and large codebases (early stage, rapidly evolving)
pyright — most complete type inference, VS Code integration
mypy — mature, extensive plugin ecosystem

来源与署名

来源：alleneubank/claude-code位于.claude/skills/python-best-practices提交2921eb8

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Python Best Practices

Python Best Practices

Make Illegal States Unrepresentable

Python-Specific Error Handling

Structured Logging

Optional: ty

来源与署名

更多来自 alleneubank/claude-code 的技能

React Best Practices

Web Fetch

Typescript Best Practices

Zig Best Practices

Nix Best Practices

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices