Python Coding Guidelines

# Python Coding Guidelines

Code Style (PEP 8)

• 4 spaces for indentation (never tabs)
• Max line length: 88 chars (Black default) or 79 (strict PEP 8)
• Two blank lines before top-level definitions, one within classes
• Imports: stdlib → third-party → local, alphabetized within groups
• Snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants

Before Committing

```bash # Syntax check (always) python -m py_compile *.py

# Run tests if present python -m pytest tests/ -v 2>/dev/null || python -m unittest discover -v 2>/dev/null || echo "No tests found"

# Format check (if available) ruff check . --fix 2>/dev/null || python -m black --check . 2>/dev/null ```

Python Version

• Minimum: Python 3.10+ (3.9 EOL Oct 2025)
• Target: Python 3.11-3.13 for new projects
• Never use Python 2 syntax or patterns
• Use modern features: match statements, walrus operator, type hints

Dependency Management

Check for uv first, fall back to pip: ```bash # Prefer uv if available if command -v uv &>/dev/null; then uv pip install <package> uv pip compile requirements.in -o requirements.txt else pip install <package> fi ```

For new projects with uv: `uv init` or `uv venv && source .venv/bin/activate`

Pythonic Patterns

```python # ✅ List/dict comprehensions over loops squares = [x**2 for x in range(10)] lookup = {item.id: item for item in items}

# ✅ Context managers for resources with open("file.txt") as f: data = f.read()

# ✅ Unpacking first, *rest = items a, b = b, a # swap

# ✅ EAFP over LBYL try: value = d[key] except KeyError: value = default

# ✅ f-strings for formatting msg = f"Hello {name}, you have {count} items"

# ✅ Type hints def process(items: list[str]) -> dict[str, int]: ...

# ✅ dataclasses/attrs for data containers from dataclasses import dataclass

@dataclass class User: name: str email: str active: bool = True

# ✅ pathlib over os.path from pathlib import Path config = Path.home() / ".config" / "app.json"

# ✅ enumerate, zip, itertools for i, item in enumerate(items): ... for a, b in zip(list1, list2, strict=True): ... ```

Anti-patterns to Avoid

```python # ❌ Mutable default arguments def bad(items=[]): # Bug: shared across calls ... def good(items=None): items = items or []

# ❌ Bare except try: ... except: # Catches SystemExit, KeyboardInterrupt ... except Exception: # Better ...

# ❌ Global state # ❌ from module import * # ❌ String concatenation in loops (use join) # ❌ == None (use `is None`) # ❌ len(x) == 0 (use `not x`) ```

Testing

• Use pytest (preferred) or unittest
• Name test files `test_*.py`, test functions `test_*`
• Aim for focused unit tests, mock external dependencies
• Run before every commit: `python -m pytest -v`

Docstrings

```python def fetch_user(user_id: int, include_deleted: bool = False) -> User | None: """Fetch a user by ID from the database. Args: user_id: The unique user identifier. include_deleted: If True, include soft-deleted users. Returns: User object if found, None otherwise. Raises: DatabaseError: If connection fails. """ ```

Quick Checklist

• [ ] Syntax valid (`py_compile`)
• [ ] Tests pass (`pytest`)
• [ ] Type hints on public functions
• [ ] No hardcoded secrets
• [ ] f-strings, not `.format()` or `%`
• [ ] `pathlib` for file paths
• [ ] Context managers for I/O
• [ ] No mutable default args