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 |
