python-error-handling

# Python Error Handling Build robust Python applications with proper input validation, meaningful exceptions, and graceful failure handling. Good error handling makes debugging easier and systems more reliable. ## When to Use This Skill - Validating user input and API parameters - Designing exception hierarchies for applications - Handling partial failures in batch operations - Converting external data to domain types - Building user-friendly error messages - Implementing fail-fast validation patterns ## Core Concepts ### 1. Fail Fast Validate inputs early, before expensive operations. Report all validation errors at once when possible. ### 2. Meaningful Exceptions Use appropriate exception types with context. Messages should explain what failed, why, and how to fix it. ### 3. Partial Failures In batch operations, don't let one failure abort everything. Track successes and failures separately. ### 4. Preserve Context Chain exceptions to maintain the full error trail for debugging. ## Quick Start ```python def fetch_page(url: str, page_size: int) -> Page: if not url: raise ValueError("'url' is required") if not 1 <= page_size <= 100: raise ValueError(f"'page_size' must be 1-100, got {page_size}") # Now safe to proceed... ``` ## Fundamental Patterns ### Pattern 1: Early Input Validation Validate all inputs at API boundaries before any processing begins. ```python def process_order( order_id: str, quantity: int, discount_percent: float, ) -> OrderResult: """Process an order with validation.""" # Validate required fields if not order_id: raise ValueError("'order_id' is required") # Validate ranges if quantity <= 0: raise ValueError(f"'quantity' must be positive, got {quantity}") if not 0 <= discount_percent <= 100: raise ValueError( f"'discount_percent' must be 0-100, got {discount_percent}" ) # Validation passed, proceed with processing return _process_validated_order(order_id, quantity, discount_percent) ``` ### Pattern 2: Convert to Domain Types Early Parse strings and external data into typed domain objects at system boundaries. ```python from enum import Enum class OutputFormat(Enum): JSON = "json" CSV = "csv" PARQUET = "parquet" def parse_output_format(value: str) -> OutputFormat: """Parse string to OutputFormat enum. Args: value: Format string from user input. Returns: Validated OutputFormat enum member. Raises: ValueError: If format is not recognized. """ try: return OutputFormat(value.lower()) except ValueError: valid_formats = [f.value for f in OutputFormat] raise ValueError( f"Invalid format '{value}'. " f"Valid options: {', '.join(valid_formats)}" ) # Usage at API boundary def export_data(data: list[dict], format_str: str) -> bytes: output_format = parse_output_format(format_str) # Fail fast # Rest of function uses typed OutputFormat ... ``` ### Pattern 3: Pydantic for Complex Validation Use Pydantic models for structured input validation with automatic error messages. ```python from pydantic import BaseModel, Field, field_validator class CreateUserInput(BaseModel): """Input model for user creation.""" email: str = Field(..., min_length=5, max_length=255) name: str = Field(..., min_length=1, max_length=100) age: int = Field(ge=0, le=150) @field_validator("email") @classmethod def validate_email_format(cls, v: str) -> str: if "@" not in v or "." not in v.split("@")[-1]: raise ValueError("Invalid email format") return v.lower() @field_validator("name") @classmethod def normalize_name(cls, v: str) -> str: return v.strip().title() # Usage try: user_input = CreateUserInput( email="user@example.com", name="john doe", age=25, ) except ValidationError as e: # Pydantic provides detailed error information print(e.errors()) ``` ### Pattern 4: Map Errors to Standard Exceptions Use Python's built-in exception types appropriately, adding context as needed. | Failure Type | Exception | Example | |--------------|-----------|---------| | Invalid input | `ValueError` | Bad parameter values | | Wrong type | `TypeError` | Expected string, got int | | Missing item | `KeyError` | Dict key not found | | Operational failure | `RuntimeError` | Service unavailable | | Timeout | `TimeoutError` | Operation took too long | | File not found | `FileNotFoundError` | Path doesn't exist | | Permission denied | `PermissionError` | Access forbidden | ```python # Good: Specific exception with context raise ValueError(f"'page_size' must be 1-100, got {page_size}") # Avoid: Generic exception, no context raise Exception("Invalid parameter") ``` ## Detailed worked examples and patterns Detailed sections (starting with `## Advanced Patterns`) live in `references/details.md`. Read that file when the navigation summary above is insufficient. ## Best Practices Summary 1. **Validate early** - Check inputs before expensive operations 2. **Use specific exceptions** - `ValueError`, `TypeError`, not generic `Exception` 3. **Include context** - Messages should explain what, why, and how to fix 4. **Convert types at boundaries** - Parse strings to enums/domain types early 5. **Chain exceptions** - Use `raise ... from e` to preserve debug info 6. **Handle partial failures** - Don't abort batches on single item errors 7. **Use Pydantic** - For complex input validation with structured errors 8. **Document failure modes** - Docstrings should list possible exceptions 9. **Log with context** - Include IDs, counts, and other debugging info 10. **Test error paths** - Verify exceptions are raised correctly