python-best-practices

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 |