Python Error Handling

作者 wshobson46891e7e60da无许可证收录于 2026年10月8日更新于 2026年10月8日

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.

仅含说明Software Development
AI 生成的概览

指导 Python 错误处理：输入验证、异常层次结构和部分失败处理。

功能
该技能提供构建健壮 Python 应用并妥善处理错误的指导与代码模式。内容涵盖快速失败的输入验证、将外部数据转换为带类型的领域对象、使用 Pydantic 模型进行结构化验证、将失败映射到标准内置异常，以及在批处理操作中处理部分失败。它产出的是说明性模式、代码示例和最佳实践清单，而非可执行脚本。
适用场景
适用于实现验证逻辑、设计异常层次结构、处理批处理失败或构建健壮 API 的场景。在将外部数据转换为领域类型或编写用户友好的错误消息时同样适用。
运行要求
除智能体外无需脚本或运行时依赖；该技能仅为说明性内容。示例涉及 Python 和 Pydantic 库，更多细节位于 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...

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 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())

Pattern 4: Map Errors to Standard Exceptions

Use Python's built-in exception types appropriately, adding context as needed.

Failure TypeExceptionExample
Invalid inputValueErrorBad parameter values
Wrong typeTypeErrorExpected string, got int
Missing itemKeyErrorDict key not found
Operational failureRuntimeErrorService unavailable
TimeoutTimeoutErrorOperation took too long
File not foundFileNotFoundErrorPath doesn't exist
Permission deniedPermissionErrorAccess 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")

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

来源与署名

来源：wshobson/agents位于plugins/python-development/skills/python-error-handling提交46891e7

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 wshobson/agents 的技能

Uv Package Manager

wshobson

关于使用 uv Python 包管理器管理依赖、虚拟环境和项目工作流的参考指南。

Software Development2026年10月8日

Web Component Design

wshobson

指导在 React、Vue 和 Svelte 中构建可复用 UI 组件，涵盖组合模式、CSS-in-JS 选择与组件 API 设计。

Software Development2026年10月8日

Python Type Safety

wshobson

指导 Python 类型注解、泛型、协议以及 mypy/pyright 严格类型检查。

Software Development2026年10月8日

Visual Design Foundations

wshobson

指导排版、色彩、间距与图标设计，帮助建立统一且无障碍的视觉设计体系。

Design & Creative2026年10月8日

Responsive Design

wshobson

指导使用容器查询、流体排版、CSS Grid 和断点策略实现响应式网页布局。

Software Development2026年10月8日

Python Resource Management

wshobson

指导 Python 开发者使用上下文管理器、清理模式和流式处理来确定性管理资源。

Software Development2026年10月8日

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Dpop Adoption

google

精选

指导为 Google OAuth 平台实现 OAuth 2.0 DPoP（RFC 9449）发送方约束刷新令牌。

Software Development21K今天更新

Gemini Live Api

google

精选

生成 Gemini Live API WebSocket 客户端类、测试、文档和用于双向流式传输的演示界面。

Software Development21K今天更新

Gemini Api

google

精选

指导如何在 Google Agent Platform 上使用 Gen AI SDK 调用 Gemini API，涵盖多语言与多项能力。

Software Development21K今天更新