python-rules

Python Coding Rules

Coding Style

Immutability (CRITICAL)

ALWAYS create new objects, NEVER mutate existing ones:

// Pseudocode
WRONG:  modify(original, field, value) -> changes original in-place
CORRECT: update(original, field, value) -> returns new copy with change

Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.

File Organization

MANY SMALL FILES > FEW LARGE FILES:

• High cohesion, low coupling
• 200-400 lines typical, 800 max
• Extract utilities from large modules
• Organize by feature/domain, not by type

Standards

• Follow PEP 8 conventions
• Use type annotations on all function signatures

Immutable Data Structures

Prefer immutable data structures:

from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    name: str
    email: str

from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

Formatting

• black for code formatting
• isort for import sorting
• ruff for linting

Error Handling

ALWAYS handle errors comprehensively:

• Handle errors explicitly at every level
• Provide user-friendly error messages in UI-facing code
• Log detailed error context on the server side
• Never silently swallow errors

Input Validation

ALWAYS validate at system boundaries:

• Validate all user input before processing
• Use schema-based validation where available
• Fail fast with clear error messages
• Never trust external data (API responses, user input, file content)

Code Quality Checklist

Before marking work complete:

• Code is readable and well-named
• Functions are small (<50 lines)
• Files are focused (<800 lines)
• No deep nesting (>4 levels)
• Proper error handling
• No hardcoded values (use constants or config)
• No mutation (immutable patterns used)

Patterns

Skeleton Projects

When implementing new functionality:

1. Search for battle-tested skeleton projects
2. Evaluate options for security, extensibility, relevance
3. Clone best match as foundation
4. Iterate within proven structure