Add Comprehensive Custom Exceptions for Better Error Handling

[LifeJiggy]

🚨 Add Comprehensive Custom Exceptions for Better Error Handling

This PR introduces a complete custom exception hierarchy for the pydo client, providing greatly improved error handling and debugging capabilities for users.

---

🛠️ Problem Solved

Previously, users only had access to generic HttpResponseError exceptions from the underlying Azure SDK, which made it difficult to:

• Distinguish between different types of API errors
• Provide appropriate error handling logic
• Debug issues effectively
• Write robust, maintainable error-handling code

---

🚀 Solution

• Custom Exception Hierarchy: Specific exception types for common HTTP status codes.
• Better Error Messages: Clear, actionable messages for each error type.
• Status Code Tracking: All exceptions include status_code and response attributes.
• Easy Import: from pydo import exceptions provides access to all exception types.

---

🆕 New Exception Types

• AuthenticationError (401) — Invalid API token
• PermissionDeniedError (403) — Insufficient permissions
• ResourceNotFoundError (404) — Resource doesn't exist
• ValidationError (400) — Bad request parameters
• ConflictError (409) — Resource state conflicts
• RateLimitError (429) — API rate limit exceeded
• ServerError (5xx) — Server-side errors
• ServiceUnavailableError (503) — Service temporarily down
• DigitalOceanError — Base class for all custom exceptions

---

🧑‍💻 Usage Examples

from pydo import Client
from pydo.exceptions import AuthenticationError, ResourceNotFoundError, RateLimitError

client = Client(token="...")

try:
    droplets = client.droplets.list()
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    # Handle invalid token
except RateLimitError as e:
    print(f"Rate limit exceeded: {e.message}")
    # Implement backoff/retry logic
except ResourceNotFoundError as e:
    print(f"Resource not found: {e.message}")
    # Handle missing resources

---

🌟 Key Features

• Specific Error Types: Each HTTP status code has its own exception class
• Rich Error Information: Status codes, response objects, and descriptive messages
• Inheritance: All exceptions inherit from DigitalOceanError for easy catching
• Backward Compatible: Existing code continues to work unchanged
• Comprehensive Testing: Full test coverage for all exception types

---

📄 Files Changed

• src/pydo/exceptions.py — Added custom exception classes
• src/pydo/_patch.py — Exposed exceptions and added error handling method
• README.md — Added exception documentation and usage examples
• tests/mocked/test_exceptions.py — Comprehensive test suite

---

💥 Impact

• Developer Experience: Much easier to write robust error-handling code
• Debugging: Clear error messages help identify and fix issues quickly
• Reliability: Better error handling leads to more stable applications
• API Maturity: Professional-grade error handling for a production client

---

🧪 Testing

• Comprehensive tests for all exception types
• Verified exception inheritance and attribute storage
• Mocked HTTP responses to test error conversion logic
• All existing functionality preserved

---

Feedback and suggestions are welcome!

[LifeJiggy]

Hi maintainers and reviewers!
This PR is ready for review. At least one approving review and workflow approval are required to proceed, and all pending checks are either in progress or awaiting status updates.
When you have a moment, could you please review and approve the workflow? Let me know if any changes are needed or if you have feedback.

Thank you for your time and consideration!