Python Error Handling

by wshobson46891e7e60daNo licenseListed Oct 8, 2026Updated Oct 8, 2026

Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs.

Instructions onlySoftware Development

AI-generated overview

Guides Python error handling: input validation, exception hierarchies, and partial failure handling.

What it does: This skill provides guidance and code patterns for building robust Python applications with proper error handling. It covers fail-fast input validation, converting external data into typed domain objects, using Pydantic models for structured validation, mapping failures to standard built-in exceptions, and handling partial failures in batch operations. It produces explanatory patterns, code examples, and a best-practices checklist rather than executable scripts.
When to use it: Use it when implementing validation logic, designing exception hierarchies, handling batch processing failures, or building robust APIs. It is also relevant when converting external data to domain types or writing user-friendly error messages.
Requirements: No scripts or runtime dependencies are required beyond the agent; the skill is instructions only. The examples reference Python and the Pydantic library, and additional detail lives in references/details.md.

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...

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)

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 boundarydef export_data(data: list[dict], format_str: str) -> bytes:    output_format = parse_output_format(format_str)  # Fail fast    # Rest of function uses typed OutputFormat    ...

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 boundarydef 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()
# Usagetry:    user_input = CreateUserInput(        email="[email protected]",        name="john doe",        age=25,    )except ValidationError as e:    # Pydantic provides detailed error information    print(e.errors())

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()
# Usagetry:    user_input = CreateUserInput(        email="[email protected]",        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 contextraise ValueError(f"'page_size' must be 1-100, got {page_size}")
# Avoid: Generic exception, no contextraise Exception("Invalid parameter")

# Good: Specific exception with contextraise ValueError(f"'page_size' must be 1-100, got {page_size}")
# Avoid: Generic exception, no contextraise 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

Validate early - Check inputs before expensive operations
Use specific exceptions - ValueError, TypeError, not generic Exception
Include context - Messages should explain what, why, and how to fix
Convert types at boundaries - Parse strings to enums/domain types early
Chain exceptions - Use raise ... from e to preserve debug info
Handle partial failures - Don't abort batches on single item errors
Use Pydantic - For complex input validation with structured errors
Document failure modes - Docstrings should list possible exceptions
Log with context - Include IDs, counts, and other debugging info
Test error paths - Verify exceptions are raised correctly

Source and attribution

Source:wshobson/agentsinplugins/python-development/skills/python-error-handlingat commit46891e7

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Python Error Handling

Python Error Handling

When to Use This Skill

Core Concepts

1. Fail Fast

2. Meaningful Exceptions

3. Partial Failures

4. Preserve Context

Quick Start

Fundamental Patterns

Pattern 1: Early Input Validation

Pattern 2: Convert to Domain Types Early

Pattern 3: Pydantic for Complex Validation

Pattern 4: Map Errors to Standard Exceptions

Detailed worked examples and patterns

Best Practices Summary

Source and attribution

More from wshobson/agents

Uv Package Manager

Web Component Design

Python Type Safety

Visual Design Foundations

Responsive Design

Python Resource Management

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api