python-best-practices

name	python-best-practices
description	Python coding best practices. Use when writing or reviewing Python code. Covers type hints, error handling, and common patterns.
license	MIT
metadata	{"author":"plan-cascade","version":"1.0.0"}

Python Best Practices

Code Style

Rule	Guideline
Formatter	ruff format or black
Linter	ruff check with strict rules
Type hints	Always for public APIs
Docstrings	Google or NumPy style

Type Hints

def process(items: list[str], max_count: int = 10) -> dict[str, int]: ...
def find_user(user_id: int) -> User | None: ...

Error Handling

Rule	Guideline
Specific exceptions	Never bare except:
Context managers	Use with for resources
Early return	Validate inputs, fail fast

# Good
try:
    result = process(data)
except ValidationError as e:
    logger.warning(f"Validation failed: {e}")
    return default

Project Structure

src/package_name/
├── __init__.py
├── core/
└── py.typed
tests/
├── conftest.py
└── test_*.py
pyproject.toml

Common Patterns

Pattern	Usage
@dataclass	Data containers
@property	Computed attributes
Generators	Memory-efficient iteration
functools.cache	Memoization

Anti-Patterns

Avoid	Use Instead
Mutable default args	None default, create inside
import *	Explicit imports
Global state	Dependency injection

# Bad: def add(item, items=[]): ...
# Good:
def add(item, items=None):
    items = items or []
    items.append(item)
    return items

Tools

Tool	Purpose
pytest	Testing
ruff	Linting + formatting
mypy	Type checking
uv	Dependencies