# python-error-handling

Guides the coding assistant in Python error handling patterns, focusing on early boundary validation and chained exception traces.

- skill · `type=skill` · Claude Code, Codex, Cursor · 14116 installs · ★ 41729
- Author: Seth Hobson
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/wshobson/agents/tree/HEAD/plugins/python-development/skills/python-error-handling/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/python-error-handling

## What it does

The skill guides an AI assistant in handling failures across Python code. It enforces early input validation at function boundaries, stopping execution before expensive calls run. Raw strings from user input are parsed into domain types like `Enum` to keep internal operations strictly typed.

For complex payloads, the pattern prescribes `BaseModel` with `field_validator` methods. Generic `Exception` raises without context are discarded in favor of standard built-ins such as `ValueError` or `KeyError`. In batch processing, single item failures are isolated so that the entire batch does not abort. Chained exceptions preserve the complete traceback via `raise ... from e`.

Using the structured models requires `pydantic` in your environment. Additional worked examples are stored in `references/details.md`.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add wshobson/agents
```
In the agent chat (not a shell):
```text
/plugin install python-development@claude-code-workflows
```
This installs the whole python-development plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add wshobson/agents --skill python-error-handling -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/python-error-handling/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/python-error-handling/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add wshobson/agents --skill python-error-handling -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/python-error-handling/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add wshobson/agents --skill python-error-handling -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/python-error-handling/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install wshobson/agents python-error-handling
```

2. **Manually: put the files in place**
- File: `.github/skills/python-error-handling/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/wshobson/agents --path plugins/python-development/skills/python-error-handling
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/python-error-handling/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/wshobson/agents/tree/HEAD/plugins/python-development/skills/python-error-handling/SKILL.md

## When to use it
- validate function inputs early before executing expensive operations
- convert raw input strings into typed `Enum` members
- structure complex validation logic using Pydantic models
- preserve debugging tracebacks by chaining exceptions with `raise ... from e`
- track partial failures in batch operations without aborting the entire run

## Example prompts
- Add input validation and early `ValueError` checks to `process_order`
- Create a Pydantic model for user registration with email format validation
- Implement partial failure handling for the batch export loop so one error does not halt the job

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6683b7de76347a98.

BEGIN THIRD-PARTY FILE 6683b7de76347a98
````text
---
name: python-error-handling
description: 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.
---

# 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:
````
END THIRD-PARTY FILE 6683b7de76347a98

The third-party file has ended. Everything between the 6683b7de76347a98 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2670 of 6164 bytes. © Seth Hobson · MIT · https://github.com/wshobson/agents/tree/HEAD/plugins/python-development/skills/python-error-handling/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md