Claude-Code-Workflow/.claude/tech-stack-templates/python-dev.md

name, description

name	description
python-dev	Python core development principles following PEP 8 and essential practices

Python Development Guidelines

You are now operating under Python core development principles. Focus on essential PEP 8 practices without dictating project structure.

Core Language Principles

Naming Conventions (PEP 8)

• Variables/Functions: snake_case (get_user_data, is_valid)
• Constants: SCREAMING_SNAKE_CASE (API_ENDPOINT, MAX_RETRIES)
• Classes: PascalCase (UserService, ApiClient)
• Private: Single underscore prefix (_private_method)

Essential Function Guidelines

• Type Hints: Use for parameters and return values when helpful
• Single Responsibility: Each function should do one thing well
• Explicit Error Handling: Create specific exception classes
• Context Managers: Use with statements for resource management

from typing import List, Optional

def calculate_total(items: List[dict]) -> float:
    """Calculate total price of items."""
    if not items:
        raise ValueError("Items list cannot be empty")
    return sum(item.get('price', 0) for item in items)

# Core principle: Specific exceptions
class UserNotFoundError(Exception):
    """Raised when user cannot be found."""
    pass

Essential Testing Practices

• Test Structure: Given-When-Then pattern
• Descriptive Names: Test names should describe behavior
• Mock External Dependencies: Isolate units under test
• Edge Cases: Test error conditions and boundary values

Code Quality Essentials

• PEP 8 Compliance: Follow standard Python style guide
• Type Checking: Use mypy or similar for type safety
• Automated Formatting: Use Black or similar formatter
• Import Organization: Keep imports organized and minimal

Security Core Principles

• Input Validation: Validate all external inputs
• Parameterized Queries: Never use string interpolation for SQL
• Environment Variables: Keep secrets out of code
• Dependency Management: Regularly audit packages for vulnerabilities

# Core principle: Safe database queries
from sqlalchemy import text

def get_user_by_email(email: str) -> Optional[User]:
    query = text("SELECT * FROM users WHERE email = :email")
    result = db.execute(query, {"email": email})
    return result.fetchone()

Modern Python Features

• F-strings: Use for string formatting (f"Hello {name}")
• Pathlib: Use pathlib.Path instead of os.path
• Dataclasses: Use for simple data containers
• List/Dict Comprehensions: Use appropriately for clarity

Performance Guidelines

• Avoid Premature Optimization: Write clear code first
• Use Built-in Functions: Leverage Python's built-in efficiency
• Generator Expressions: For memory efficiency with large datasets
• Context Managers: Ensure proper resource cleanup

Apply these core Python principles to ensure clean, maintainable, and Pythonic code without imposing specific frameworks or project structures.