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

Repository Pattern

Encapsulate data access behind a consistent interface:

• Define standard operations: findAll, findById, create, update, delete
• Concrete implementations handle storage details (database, API, file, etc.)
• Business logic depends on the abstract interface, not the storage mechanism
• Enables easy swapping of data sources and simplifies testing with mocks

API Response Format

Use a consistent envelope for all API responses:

• Include a success/status indicator
• Include the data payload (nullable on error)
• Include an error message field (nullable on success)
• Include metadata for paginated responses (total, page, limit)

Protocol (Duck Typing)

from typing import Protocol

class Repository(Protocol):
    def find_by_id(self, id: str) -> dict | None: ...
    def save(self, entity: dict) -> dict: ...

Dataclasses as DTOs

from dataclasses import dataclass

@dataclass
class CreateUserRequest:
    name: str
    email: str
    age: int | None = None

Context Managers & Generators

• Use context managers (with statement) for resource management
• Use generators for lazy evaluation and memory-efficient iteration

Testing

Minimum Test Coverage: 80%

Test Types (ALL required):

1. Unit Tests - Individual functions, utilities, components
2. Integration Tests - API endpoints, database operations
3. E2E Tests - Critical user flows

Test-Driven Development

MANDATORY workflow:

1. Write test first (RED)
2. Run test - it should FAIL
3. Write minimal implementation (GREEN)
4. Run test - it should PASS
5. Refactor (IMPROVE)
6. Verify coverage (80%+)

Troubleshooting Test Failures

1. Check test isolation
2. Verify mocks are correct
3. Fix implementation, not tests (unless tests are wrong)

Framework

Use pytest as the testing framework.

Coverage

pytest --cov=src --cov-report=term-missing

Test Organization

Use pytest.mark for test categorization:

import pytest

@pytest.mark.unit
def test_calculate_total():
    ...

@pytest.mark.integration
def test_database_connection():
    ...

Security

Mandatory Security Checks

Before ANY commit:

• No hardcoded secrets (API keys, passwords, tokens)
• All user inputs validated
• SQL injection prevention (parameterized queries)
• XSS prevention (sanitized HTML)
• CSRF protection enabled
• Authentication/authorization verified
• Rate limiting on all endpoints
• Error messages don't leak sensitive data

Secret Management

• NEVER hardcode secrets in source code
• ALWAYS use environment variables or a secret manager
• Validate that required secrets are present at startup
• Rotate any secrets that may have been exposed

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.environ["OPENAI_API_KEY"]  # Raises KeyError if missing

Security Scanning

• Use bandit for static security analysis:

  bandit -r src/
  

Security Response Protocol

If security issue found:

1. STOP immediately
2. Fix CRITICAL issues before continuing
3. Rotate any exposed secrets
4. Review entire codebase for similar issues