Refactor Error Handling: Introducing Structured, Typed Exceptions for Clearer Server & Validation Errors

Start by reviewing the completed exception work in exceptions.py and the HTTP/XML mapping in _api_calls.py. Run the existing test suite, then update tests including test_too_long_uri to cover typed exceptions and backward compatibility. Done means the tests pass and the error-handling documentation includes retry, missing-resource, and permission examples.

Problem Summary

OpenML-Python currently funnels diverse server and client-side errors into the broad exceptions OpenMLServerError and OpenMLServerException. This limits users and downstream systems from:

1. Distinguishing retryable vs non-retryable failures
2. Providing meaningful user-facing error messages
3. Programmatically responding to rate limits, missing resources, or validation failures
4. Debugging large-scale uploads where different failure modes look identical

Current Situation

All these different scenarios raise the same generic exception:

try:
    openml.datasets.get_dataset(999999)
except OpenMLServerError:
    # Could be dataset missing, rate limit, timeout, validation issue, DB issue, etc.
    pass

Proposed Solution

Introducing a hierarchical exception system with specific, typed error classes:

OpenMLServerError (existing)
├── OpenMLURITooLongError (HTTP 414)
├── OpenMLRateLimitError (HTTP 429)
├── OpenMLNotFoundError (HTTP 404)
├── OpenMLTimeoutError (HTTP 408, 504)
├── OpenMLServiceUnavailableError (HTTP 503)
├── OpenMLAuthenticationError (missing/invalid API key)
├── OpenMLNotAuthorizedError (insufficient permissions)
│
└── OpenMLServerException (existing)
    ├── OpenMLServerNoResult (existing - empty results)
    ├── OpenMLValidationError (code 163, validation failures)
    └── OpenMLDatabaseConnectionError (code 107, temporary DB issues)

Key Benefits

1. Typed Exceptions → programmatic handling (except OpenMLRateLimitError: retry).
2. HTTP & OpenML Code Mapping → consistent error interpretation.
3. Rich Metadata → e.g., retry_after, resource_type, timeout_seconds.
4. Backward Compatible → all classes still inherit existing base exceptions.

I will systematically link the changes to this thread. Hope this helps users and contributors alike.

Implementation Checklist

PR1 — Typed Exceptions (exceptions.py only)

• Add new typed exception classes
• Organize categories (HTTP, validation, auth, timeout, DB, etc.)
• Keep backward compatibility

PR2 — Server Error Mapping (_api_calls.py)

• Map HTTP status codes → typed exceptions
• Map OpenML XML error codes → typed exceptions
• Add message-based fallbacks
• Add pre-check for overly long URLs

PR3 — Test Suite Updates

• Update tests to expect typed exceptions
• Fix test_too_long_uri with pre-request check
• Ensure full backward compatibility

PR4 — Documentation

• Update error-handling documentation
• Add examples for retry, missing resources, permissions
• Submit PR4