splurge-exceptions 2025.3.1

The standardized exception framework for Splurge projects.

Splurge Exceptions

A comprehensive Python exception management library that provides structured error handling, semantic error codes, and intelligent error organization for Splurge projects.

Quick Start

Installation

pip install splurge-exceptions

Basic Usage

1. Create Structured Exceptions

from splurge_exceptions import SplurgeValueError

# Create a semantic exception with context
error = SplurgeValueError(
    "Email address format is invalid",
    error_code="invalid-email",
    details={"provided": "user@", "expected": "[e-mail]"}
)

# Attach context and suggestions
error.attach_context("user_id", 12345)
error.add_suggestion("Use format: [e-mail]")
error.add_suggestion("Verify domain is included")

# Full error code: "splurge.value.invalid-email"
print(error.full_code)

2. Convert Exceptions with Chaining

from splurge_exceptions import SplurgeValueError

try:
    # Some operation that might fail
    int("invalid")
except ValueError as e:
    # Wrap the exception with structured error
    wrapped = SplurgeValueError(
        "Could not parse input as integer",
        error_code="invalid-integer",
        details={"input": "invalid"}
    )
    raise wrapped from e

3. Format Errors for Users

from splurge_exceptions import ErrorMessageFormatter

formatter = ErrorMessageFormatter()
formatted = formatter.format_error(
    error,
    include_context=True,
    include_suggestions=True,
)
print(formatted)

4. Integration Support for Splurge Family Libraries

from splurge_exceptions import SplurgeFrameworkError

class SplurgeSafeIoError(SplurgeFrameworkError):
    _domain = "splurge-safe-io"

class SplurgeSafeIoRuntimeError(SplurgeSafeIoError):
    _domain = "splurge-safe-io.runtime"

raise SplurgeSafeIoRuntimeError(
    "Unexpected error occurred",
    error_code="unexpected",
)
# Resulting full error code: "splurge-safe-io.runtime.unexpected"

Key Features

🎯 Semantic Error Codes - Hierarchical error codes with domain organization
� Exception Chaining - Preserve exception chains with raise ... from
📋 Context Attachment - Add operation context and recovery suggestions
� Message Formatting - Beautiful, structured error message output
� Type Safe - Full type annotations with MyPy strict mode support
🎭 Framework Extensions - Clean extension points for domain-specific exceptions

Exception Types

Splurge Exceptions provides 9 exception types for different error scenarios:

• SplurgeError - Base exception class
• SplurgeValueError - Input validation errors
• SplurgeOSError - Operating system errors
• SplurgeRuntimeError - Runtime execution errors
• SplurgeTypeError - Type errors
• SplurgeAttributeError - Missing object attributes/methods
• SplurgeImportError - Module import failures
• SplurgeLookupError - Lookup errors
• SplurgeFrameworkError - Framework-level errors
• SplurgeSubclassError - Framework misconfiguration errors (used internally)

Documentation

• README-DETAILS.md - Comprehensive feature documentation and examples
• API-REFERENCE.md - Complete API reference
• CLI-REFERENCE.md - CLI tools reference
• CHANGELOG.md - Version history and changes

Project Structure

splurge-exceptions/
├── splurge_exceptions/          # Main package
│   ├── core/                    # Core exceptions and error codes
│   ├── formatting/              # Message formatting utilities
│   ├── context/                 # Context utilities
│   └── cli.py                   # CLI interface
├── tests/                       # Test suite (130+ tests)
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
└── docs/                        # Documentation

Testing

The library includes comprehensive test coverage:

• 130 tests - Unit tests (100% passing)
• 94% code coverage - All public APIs tested
• MyPy strict mode - Full type safety validation
• Ruff linting - Code quality enforcement

Run tests:

pytest tests/
pytest tests/ --cov=splurge_exceptions --cov-report=html

License

MIT License - See LICENSE file for details

Author

Jim Schilling