feat: Enterprise Exception Architecture (v5.0.0)

[eman]

🎯 Overview

This PR implements a comprehensive enterprise-grade exception architecture for nwp500-python v5.0.0, replacing generic RuntimeError and ValueError with specific, typed exceptions throughout the library.

🚨 Breaking Changes

This is a BREAKING CHANGE release. Users catching generic exceptions will need to update their error handling code.

✨ New Features

Exception Hierarchy (18 Exception Classes)

• Nwp500Error: Base class for all library exceptions
• MqttError hierarchy (6 classes): Connection, publish, subscription errors
• ValidationError hierarchy (2 classes): Parameter and range validation
• DeviceError hierarchy (3 classes): Device operation errors
• Enhanced AuthenticationError and APIError classes

Enhanced Exception Features

• ✅ Exception chaining: All wrapped exceptions preserve stack traces (raise ... from e)
• ✅ Structured error data: to_dict() method for logging/monitoring
• ✅ Retriable flag: Indicates which operations can be retried
• ✅ Rich attributes: error_code, details, field names, min/max values

📦 What's Changed

Core Library

• Replaced 25+ RuntimeError instances with MqttNotConnectedError, MqttConnectionError
• Replaced 35+ ValueError instances with RangeValidationError, ParameterValidationError
• Added exception chaining to 15+ locations
• All exceptions now inherit from Nwp500Error base class

CLI Enhancement

• 8 specific exception handlers in CLI main
• 5 specific exception handlers in CLI commands
• User-friendly error messages with actionable guidance
• Shows valid ranges for validation errors

Examples

• New comprehensive exception handling example (examples/exception_handling_example.py)
• Updated 4 key examples with best practices
• Demonstrates retry logic, structured logging, and error recovery patterns

Documentation

• Complete rewrite of docs/python_api/exceptions.rst (19KB, 736 lines)
• 15+ code examples in documentation
• Updated quickstart and configuration guides
• API reference with Sphinx directives

Tests

• 30+ new test cases for exception hierarchy
• Tests for attributes, chaining, usage patterns
• 100% coverage of exception functionality

📊 Impact

Files Created: 3

• src/nwp500/exceptions.py (461 lines)
• tests/test_exceptions.py (379 lines)
• examples/exception_handling_example.py (320 lines)

Files Modified: 18

• Core library: 9 files
• CLI: 2 files
• Examples: 4 files
• Documentation: 3 files

Total Changes: +1031 lines, -391 lines = +640 net lines

🔄 Migration Guide

MQTT Errors

Before (v4.x):

try:
    await mqtt.request_device_status(device)
except RuntimeError as e:
    if "Not connected" in str(e):
        await mqtt.connect()

After (v5.0+):

from nwp500 import MqttNotConnectedError

try:
    await mqtt.request_device_status(device)
except MqttNotConnectedError:
    await mqtt.connect()
    await mqtt.request_device_status(device)

Validation Errors

Before (v4.x):

try:
    set_vacation_mode(days=35)
except ValueError as e:
    print(f"Invalid: {e}")

After (v5.0+):

from nwp500 import RangeValidationError

try:
    set_vacation_mode(days=35)
except RangeValidationError as e:
    print(f"Invalid {e.field}: must be {e.min_value}-{e.max_value}")

Catch All Library Errors

New in v5.0:

from nwp500 import Nwp500Error

try:
    # Any library operation
    await mqtt.connect()
except Nwp500Error as e:
    # Catches all library exceptions
    print(f"Error: {e}")
    if e.retriable:
        # Can retry this operation
        pass

See CHANGELOG.rst for complete migration guide with more examples.

✅ Testing

• ✅ All existing tests passing
• ✅ 30+ new exception tests passing
• ✅ Type checking: mypy strict mode passing
• ✅ Linting: ruff passing
• ✅ All examples working with new exceptions
• ✅ Backward compatible imports verified

📚 Documentation

Complete documentation includes:

• Exception hierarchy diagram
• API reference for all 18 exception classes
• 5 error handling patterns with code examples
• Exception chaining explanation
• Best practices guide
• Migration guide

View: docs/python_api/exceptions.rst

🎁 Benefits

1. Specific exception types - No more string matching in error handlers
2. Preserved stack traces - Full exception chains with raise ... from
3. Structured logging - to_dict() for monitoring systems
4. Smart retries - retriable flag indicates when to retry
5. Better debugging - Rich error attributes and clear messages
6. Type safety - IDE autocomplete and type checking support
7. User-friendly CLI - Actionable error messages with guidance
8. Production ready - Enterprise-grade patterns

🐛 Bug Fixes

• Fixed pre-existing bug in examples/reservation_schedule_example.py (incorrect import)

🚀 Ready for Release

This PR is ready for v5.0.0 release:

• All quality checks passing ✅
• Comprehensive testing ✅
• Complete documentation ✅
• Migration guide provided ✅
• Examples updated ✅

---

Related Issues: N/A (proactive enhancement)
Version: 5.0.0 (Breaking Changes)
Status: Ready for Review

[Copilot]

Pull Request Overview

This PR implements a comprehensive enterprise-grade exception architecture to replace generic RuntimeError and ValueError with 18 specific, typed exception classes across the library. This is a breaking change that enhances error handling with structured error information, exception chaining, retriable flags, and rich attributes.

Key Changes:

• New exception hierarchy with 18 exception classes inheriting from Nwp500Error base
• Replaced 25+ RuntimeError and 35+ ValueError instances with specific exceptions
• Added exception chaining throughout the library to preserve stack traces
• Enhanced CLI and examples with specific exception handling

Reviewed Changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/nwp500/exceptions.py	New module defining complete exception hierarchy with 18 classes
tests/test_exceptions.py	Comprehensive test suite with 30+ test cases for exception functionality
src/nwp500/__init__.py	Updated exports to include all new exception types
src/nwp500/auth.py	Moved exception classes to exceptions.py, added exception chaining
src/nwp500/api_client.py	Moved APIError to exceptions.py, added exception chaining
src/nwp500/mqtt_client.py	Replaced RuntimeError/ValueError with specific MQTT exceptions
src/nwp500/mqtt_connection.py	Replaced RuntimeError/ValueError with MqttConnectionError/MqttCredentialsError
src/nwp500/mqtt_subscriptions.py	Replaced RuntimeError with MqttNotConnectedError
src/nwp500/mqtt_device_control.py	Replaced ValueError with ParameterValidationError/RangeValidationError
src/nwp500/encoding.py	Replaced ValueError with RangeValidationError/ParameterValidationError
src/nwp500/cli/__main__.py	Added 8 specific exception handlers with user guidance
src/nwp500/cli/commands.py	Added 5 specific exception handlers in command functions
examples/exception_handling_example.py	New comprehensive example demonstrating exception handling patterns
examples/*.py	Updated 4 examples with new exception imports
docs/python_api/exceptions.rst	Complete rewrite with 736 lines of documentation
docs/quickstart.rst	Added exception handling example
docs/configuration.rst	Added exception handling example
CHANGELOG.rst	Added v5.0.0 entry with migration guide
tests/test_api_helpers.py	Updated tests to use RangeValidationError