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