Python Development Rules

Overview

When to Use This Skill

• Writing new Python code or modifying existing Python files
• Creating or updating Jupyter notebooks
• Setting up Python development environments
• Writing or updating tests
• Reviewing Python code for quality and best practices

Code Quality

Principles

• DRY (Don't Repeat Yourself): Avoid code duplication
• Composition over inheritance: Prefer composition patterns
• Pure functions when possible: Functions without side effects
• Simple solutions over clever ones: Prioritize readability and maintainability
• Design for common use cases first: Solve the primary problem before edge cases

Style & Documentation

• Type hints required: All functions must include type annotations
• snake_case naming: Use snake_case for variables, functions, and modules
• Google-style docstrings: Document functions, classes, and modules using Google-style docstrings
• Keep functions small: Single responsibility principle - one function, one purpose
• Preserve existing comments: Maintain and update existing code comments

Example

def calculate_total(items: list[dict[str, float]], tax_rate: float = 0.08) -> float:
    """Calculate total cost including tax.
    
    Args:
        items: List of items with 'price' key
        tax_rate: Tax rate as decimal (default 0.08)
        
    Returns:
        Total cost including tax
        
    Raises:
        ValueError: If tax_rate is negative or items list is empty
    """
    if not items:
        raise ValueError("Items list cannot be empty")
    if tax_rate < 0:
        raise ValueError("Tax rate cannot be negative")
    
    subtotal = sum(item['price'] for item in items)
    return subtotal * (1 + tax_rate)

Error Handling & Efficiency

Error Handling

• Specific exception types: Catch specific exceptions, not bare

  except

• Validate inputs early: Check inputs at function entry
• No bare except: Always specify exception types

Efficiency Patterns

• f-strings: Use f-strings for string formatting
• Comprehensions: Prefer list/dict/set comprehensions over loops when appropriate
• Context managers: Use

  with

  statements for resource management

Example

def process_file(file_path: str) -> list[str]:
    """Process file and return lines.
    
    Args:
        file_path: Path to file
        
    Returns:
        List of non-empty lines
        
    Raises:
        FileNotFoundError: If file doesn't exist
        PermissionError: If file cannot be read
    """
    if not file_path:
        raise ValueError("File path cannot be empty")
    
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            return [line.strip() for line in f if line.strip()]
    except FileNotFoundError:
        raise FileNotFoundError(f"File not found: {file_path}")
    except PermissionError:
        raise PermissionError(f"Permission denied: {file_path}")

Testing (Critical)

Framework & Structure

• pytest only: Use pytest exclusively (no unittest)
• Test location: All tests in

  ./tests/

  directory
• Test package: Include

  __init__.py

  in tests directory
• TDD approach: Write/update tests for all new/modified code
• All tests must pass: Ensure all tests pass before task completion

Test Structure Example

project/
├── src/
│   └── my_module.py
└── tests/
    ├── __init__.py
    └── test_my_module.py

Example Test

# tests/test_calculations.py
import pytest
from src.calculations import calculate_total

def test_calculate_total_basic():
    """Test basic total calculation."""
    items = [{'price': 10.0}, {'price': 20.0}]
    result = calculate_total(items, tax_rate=0.1)
    assert result == 33.0

def test_calculate_total_empty_list():
    """Test error handling for empty list."""
    with pytest.raises(ValueError, match="Items list cannot be empty"):
        calculate_total([])

def test_calculate_total_negative_tax():
    """Test error handling for negative tax rate."""
    items = [{'price': 10.0}]
    with pytest.raises(ValueError, match="Tax rate cannot be negative"):
        calculate_total(items, tax_rate=-0.1)

Environment Management

Dependency Management

• Use uv: Dependency management via uv
• Virtual environments: Use virtual environments (

  venv

  ) or

  uv

• Check existing venv: Always check for existing

  .venv

  in current or parent directories before creating new one
• Activate before use: Activate

  .venv

  before installing packages or executing scripts

Code Style

• Ruff: Use Ruff for code style consistency and linting

Environment Setup Example

# Check for existing .venv
if [ -d ".venv" ]; then
    source .venv/bin/activate
elif [ -d "../.venv" ]; then
    source ../.venv/bin/activate
else
    # Create new venv or use uv
    python3 -m venv .venv
    source .venv/bin/activate
fi

# Install dependencies
pip install -r requirements.txt

# Or with uv
uv pip install -r requirements.txt

Python Script Execution

• Always activate virtual environment before running Python scripts
• Use

  python3

  explicitly when not in venv
• Check for

  requirements.txt

  or

  pyproject.toml

  for dependencies

Best Practices Summary

1. Code Quality: DRY, composition, pure functions, simple solutions
2. Style: Type hints, snake_case, Google docstrings, small functions
3. Errors: Specific exceptions, early validation, no bare except
4. Efficiency: f-strings, comprehensions, context managers
5. Testing: pytest only, TDD, tests in

   ./tests/

   , all must pass
6. Environment: uv or venv, check existing

   .venv

   , activate before use, Ruff for style