Skip to content

Add custom exception hierarchy for better error handling #2

Description

@NP-compete

Problem

The codebase uses generic Exception for all error cases:

raise Exception("Processing failed")  # processor.py:291
raise Exception(f"finish reason: {finish_reason}")  # processor.py:440

This makes it difficult to:

  • Catch specific error types
  • Provide meaningful error messages to users
  • Debug issues in production

Proposed Solution

Create a custom exception hierarchy in src/pageindex/exceptions.py:

class PageIndexError(Exception):
    """Base exception for all PageIndex errors."""
    pass

class DocumentParseError(PageIndexError):
    """Raised when document parsing fails."""
    pass

class TOCExtractionError(PageIndexError):
    """Raised when TOC extraction fails."""
    pass

class LLMResponseError(PageIndexError):
    """Raised when LLM returns invalid or unexpected response."""
    pass

class ConfigurationError(PageIndexError):
    """Raised when configuration is invalid."""
    pass

class ConversionError(PageIndexError):
    """Raised when document conversion fails."""
    pass

Acceptance Criteria

  • Create exceptions.py with exception hierarchy
  • Replace all raise Exception(...) with specific exception types
  • Replace bare except Exception with specific catches where appropriate
  • Add exception documentation to README
  • Add tests for exception handling

Files to Modify

  • Create src/pageindex/exceptions.py
  • src/pageindex/pdf/processor.py
  • src/pageindex/pdf/toc.py
  • src/pageindex/markdown/processor.py
  • src/pageindex/batch.py
  • src/pageindex/llm.py

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions