Agent skill
python-best-practices
Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).
Install this agent skill to your Project
npx add-skill https://github.com/0xBigBoss/claude-code/tree/main/.claude/skills/python-best-practices
SKILL.md
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:
from dataclasses import dataclass
from 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:
from dataclasses import dataclass
from typing import Literal
@dataclass
class Success:
status: Literal["success"] = "success"
data: str
@dataclass
class 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:
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:
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:
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):
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.
uvx ty check # run directly, no install needed
uvx ty check src/ # check specific path
# pyproject.toml
[tool.ty]
python-version = "3.12"
When to choose:
ty— fastest, good for CI and large codebases (early stage, rapidly evolving)pyright— most complete type inference, VS Code integrationmypy— mature, extensive plugin ecosystem
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
0xBigBoss/claude-code
canton-nodes
Canton validator node reference data. Use for participant IDs, database names, port availability, and architecture context.
0xBigBoss/claude-code
writing-plans
Use when requirements are clear enough to plan and the work spans multiple steps, files, or verification stages
0xBigBoss/claude-code
writing-skills
Use when creating or editing a skill and you need it to be discoverable, concise, and native to the target harness
0xBigBoss/claude-code
dispatching-parallel-agents
Use when there are multiple independent subtasks that can progress in parallel without overlapping ownership or blocking the next local step
0xBigBoss/claude-code
testing-best-practices
Use when designing tests, writing test cases, or planning test strategy for a module. Covers unit, integration, and e2e layering.
0xBigBoss/claude-code
git-best-practices
Use when creating commits, managing branches, opening PRs, or rewriting history. Not for non-git implementation tasks or repo-specific release policy decisions.
Didn't find tool you were looking for?