Python Best Practices Type Safety

Debug Type Errors

Purpose

Systematically diagnose and resolve Python type checking errors from pyright/mypy by categorizing error types and applying proven fix patterns.

When to Use This Skill

Use when fixing type errors with "fix pyright errors", "resolve type mismatch", "add type annotations", or "handle Optional types".

Do NOT use for pytest configuration (use pytest-configuration), import validation (use python-best-practices-fail-fast-imports), or runtime errors (type checking is static).

When to Use

Use this skill when:

• Pyright or mypy reports type errors in CI/CD or local checks
• Adding type annotations to untyped code
• Refactoring code and need to maintain type safety
• Debugging "Type X cannot be assigned to Y" errors
• Fixing Optional/None handling issues
• Resolving generic type argument errors
• Converting code to strict type checking mode
• Before committing changes (as part of quality gates)

Table of Contents

Core Sections

• Purpose - Systematic type error diagnosis and resolution
• Quick Start - Fastest way to fix type errors with automation
• Instructions - Complete implementation guide
  • Step 1: Run Type Checker and Capture Output - Pyright execution and error capture
  • Step 2: Categorize Errors - 6 error categories with patterns
  • Step 3: Apply Fix Patterns - Category-specific fix templates
  • Step 4: Use MultiEdit for Batch Fixes - Token-efficient batch fixes
  • Step 5: Verify Fixes - Post-fix validation
• Examples - Real-world error fixes
  • Example 1: Missing Return Type Annotation
  • Example 2: Optional Parameter Handling
  • Example 3: Generic Type Arguments
• Common Error Patterns - Quick reference table
• Project-Specific Rules - Strict type checking rules
• Requirements - Python 3.11+, pyright, pyrightconfig.json
• Automation Scripts - Parser, annotation fixer, Optional handler

Supporting Resources

• scripts/README.md - Automation scripts and workflows
• references/reference.md - Complete error pattern catalog
• CLAUDE.md - Project type safety rules
• ../apply-code-template/references/code-templates.md - Type-safe code templates

Python Scripts

• Parse Pyright Errors - Categorize and analyze pyright type checking errors
• Fix Missing Annotations - Automatically add type hints to Python files
• Fix Optional Handling - Add None checks for Optional types

Quick Start

Using Automation Scripts (Recommended):

# Parse and categorize errors
uv run pyright src/ | python .claude/skills/debug-type-errors/scripts/parse_pyright_errors.py

# Auto-fix missing annotations
python .claude/skills/debug-type-errors/scripts/fix_missing_annotations.py src/file.py --all --dry-run

# Auto-fix Optional handling
python .claude/skills/debug-type-errors/scripts/fix_optional_handling.py src/file.py --dry-run

Manual Analysis:

# Run pyright and capture errors
uv run pyright src/ > type_errors.txt

# Analyze errors by category
grep "is not assignable" type_errors.txt
grep "Cannot access member" type_errors.txt
grep "is not defined" type_errors.txt

# Fix using MultiEdit for multiple errors in same file

See: scripts/README.md for complete automation workflow.

Instructions

Step 1: Run Type Checker and Capture Output

Run pyright with verbose output to get detailed error information:

# Project-wide check
uv run pyright src/ --verbose > type_errors.txt

# Specific file check
uv run pyright src/path/to/file.py --verbose

# Check with stats
uv run pyright src/ --stats

Key flags:

• --verbose - Shows full error context
• --stats - Displays error count by category
• No flags - Standard output (recommended for parsing)

Step 2: Categorize Errors

Parse pyright output and group errors by category:

Category 1: Missing Type Annotations

error: Type of "variable" is unknown
error: Return type of function is unknown
error: Parameter "param" type is unknown

Category 2: Type Mismatch (Assignment)

error: Argument of type "X" cannot be assigned to parameter "Y"
error: Expression of type "X" cannot be assigned to declared type "Y"
error: Type "X" is not assignable to type "Y"

Category 3: Optional/None Handling

error: "None" is not assignable to "X"
error: Argument of type "X | None" cannot be assigned to parameter "X"
error: Object of type "None" cannot be used as iterable value

Category 4: Generic Type Errors

error: Type argument "X" is missing
error: Expected 1 type argument
error: Type "X[Y]" is incompatible with "X[Z]"

Category 5: Attribute/Method Errors

error: Cannot access member "X" for type "Y"
error: "X" is not a known member of "Y"

Category 6: Import/Module Errors

error: Import "X" could not be resolved
error: Stub file not found for "X"

Step 3: Apply Fix Patterns

Use category-specific fix patterns (see references/reference.md for detailed examples):

Pattern 1: Add Type Annotations

# Before
def process_data(data):
    return data.strip()

# After
def process_data(data: str) -> str:
    return data.strip()

Pattern 2: Fix Type Mismatches

# Before
result: ServiceResult[bool] = service.get_data()  # Returns ServiceResult[dict]

# After
result: ServiceResult[dict] = service.get_data()

Pattern 3: Handle Optional Types

# Before
def get_value(config: Settings | None) -> str:
    return config.value  # Error: config might be None

# After
def get_value(config: Settings | None) -> str:
    if not config:
        raise ValueError("Config required")
    return config.value

Pattern 4: Fix Generic Types

# Before
items: list = []  # Missing type argument

# After
items: list[str] = []

Step 4: Use MultiEdit for Batch Fixes

When fixing multiple errors in the same file, ALWAYS use MultiEdit:

# ❌ WRONG - Sequential edits (wastes tokens)
Edit("file.py", old1, new1)
Edit("file.py", old2, new2)

# ✅ CORRECT - Single MultiEdit operation
MultiEdit("file.py", [
    {"old_string": old1, "new_string": new1},
    {"old_string": old2, "new_string": new2}
])

Step 5: Verify Fixes

After applying fixes, verify the changes:

# Run pyright on specific file
uv run pyright src/path/to/file.py

# Run full type check
uv run pyright src/

# Run quality gates
./scripts/check_all.sh

Examples

Example 1: Missing Return Type Annotation

Error:

src/application/services/indexing_service.py:45:5 - error: Return type of "process" is unknown

Fix:

# Before
def process(self, data: dict):
    return ServiceResult.success(data)

# After
def process(self, data: dict) -> ServiceResult[dict]:
    return ServiceResult.success(data)

Example 2: Optional Parameter Handling

Error:

src/infrastructure/neo4j_repository.py:23:9 - error: Argument of type "Settings | None" cannot be assigned to parameter "settings" of type "Settings"

Fix:

# Before
def __init__(self, settings: Settings | None = None):
    self.settings = settings

# After
def __init__(self, settings: Settings):
    if not settings:
        raise ValueError("Settings required")
    self.settings = settings

Example 3: Generic Type Arguments

Error:

src/domain/entities/chunk.py:12:5 - error: Type argument for "list" is missing

Fix:

# Before
class Chunk:
    entities: list

# After
class Chunk:
    entities: list[str]

Common Error Patterns

See references/reference.md for comprehensive error pattern catalog.

Quick Reference:

Project-Specific Rules

This project enforces strict type checking with the following rules:

1. No Optional Config Parameters - Use Settings, not Settings | None
2. Fail Fast on None - Check and raise ValueError immediately
3. ServiceResult Returns - All service methods return ServiceResult[T]
4. No Bare None Returns - Use ServiceResult.failure() instead
5. Generic Types Required - Always specify type arguments: list[str], not list

Requirements

• Python 3.11+
• pyright (installed via uv): uv pip install pyright
• Project type checking config in pyrightconfig.json

Automation Scripts

This skill includes powerful automation utilities in scripts/:

1. parse_pyright_errors.py - Parse and categorize pyright errors

   • Categorizes errors by type (missing annotations, type mismatch, etc.)
   • Groups by file and severity
   • Provides fix templates and quick wins

2. fix_missing_annotations.py - Auto-add type hints

   • Infers return types from return statements
   • Detects ServiceResult[T] patterns
   • Suggests parameter types from usage

3. fix_optional_handling.py - Fix Optional/None handling

   • Detects Optional parameters without None checks
   • Adds fail-fast validation
   • Follows project pattern: if not param: raise ValueError()

See: scripts/README.md for usage examples and workflow integration.

See Also

• scripts/README.md - Automation scripts and workflows
• references/reference.md - Complete error pattern catalog
• CLAUDE.md - Project type safety rules
• ../apply-code-template/references/code-templates.md - Type-safe code templates