PR2: Map Server & HTTP Errors to Typed Exceptions + Fix URL-Length Validation

[kindler-king]

Metadata

Reference Issue: Fixes #1491
New Tests Added: No (tests covered in PR3 per roadmap)
Documentation Updated: No

Details

What This PR Implements

This PR introduces structured error mapping in _api_calls.py, enabling the OpenML Python client to raise typed, semantically meaningful exceptions in response to:

1. HTTP Status Codes → Typed Exceptions

• 414 → OpenMLURITooLongError
• 429 → OpenMLRateLimitError
• 404 → OpenMLNotFoundError
• 408, 504 → OpenMLTimeoutError
• 503 → OpenMLServiceUnavailableError
• 401 → OpenMLAuthenticationError

2. OpenML XML Error Codes → Typed Exceptions

Includes mappings for:

• 107 → OpenMLDatabaseConnectionError
• 111, 372, 482, 500, 512, 542, 674 → OpenMLServerNoResult
• 163 → OpenMLValidationError
• 102, 137, 310, 320, 350, 400, 460 → OpenMLNotAuthorizedError

3. Message-Based Fallback Classification

When server responses return:

• HTML error pages
• Partial or malformed XML
• Generic messages

…the client now makes reasonable inferences for:
authentication failures, rate limits, validation errors, missing resources, timeouts, and server outages.

4. Pre-check for Overly Long URLs (Fix for test_too_long_uri)

Before sending a request:

if len(url) > MAX_URL_LENGTH:
    raise OpenMLURITooLongError(url)

This resolves:

• Unnecessary network calls
• XML parsing failures on HTML responses
• A previously failing test described in a now-closed issue

Why This Change Is Necessary

The prior system funneled most server errors into OpenMLServerError or OpenMLServerException, providing limited diagnostic value.

Typed exceptions allow:

• better retry logic
• clearer user-facing error messages
• easier debugging
• more reliable behavior in large-scale workflows (e.g., batch model uploads)

This PR also fixes a longstanding edge case where very long URLs caused inconsistent failures.

How to Reproduce the Issue

• Construct a request with >10,000 data IDs.
• Call a list endpoint (e.g., openml.datasets.list_datasets(...)).

Previously:

• Server returned HTTP 414 with HTML
• HTML was parsed as XML → crash
• Generic OpenMLServerError raised

After this PR:

• URL length is checked client-side
• A clean OpenMLURITooLongError is raised immediately

Additional Notes / Pre-commit Status

Some Ruff warnings remain for maintainers to decide:

• C901, PLR0912, PLR0911 for __parse_server_exception complexity
• N818 for existing exception names (OpenMLServerException, etc.)

These were intentionally not addressed in this PR to avoid breaking changes or large refactors.