Add warnings for future strict HTTP behavior

[Mattsface]

Add warnings for future strict HTTP behavior

Why

Version 1.0 may make stricter handling the default for non-404 4xx responses.

Users relying on compatibility behavior need advance notice before that default changes.

Version 0.9.0 should emit targeted warnings when compatibility mode suppresses an HTTP error that strict mode would raise.

Parent release issue: #265

Scope

Add a package-specific warning class:

MlbHttpCompatibilityWarning

The warning should be emitted only when:

• Compatibility mode is active
• A final non-404 4xx response is received
• Strict mode would have raised MlbHttpError

Do not warn for:

• Successful responses
• Intermediate retry attempts
• Endpoint-specific 404 behavior
• Transport failures
• Timeouts
• Invalid JSON
• Pydantic validation errors

Warning message

The warning should include:

• Status code
• Request URL or endpoint
• An explanation that compatibility mode returned the historical result
• Instructions for enabling strict_http=True
• Notice that stricter defaults may be introduced in version 1.0

Example:

HTTP 403 was handled through compatibility mode. Pass
strict_http=True to raise MlbHttpError. This compatibility
behavior may change in version 1.0.

Testing requirements

• Warning class is publicly importable
• Warning is emitted for final non-404 4xx responses
• Warning is not emitted in strict mode
• Warning is not emitted for 404
• Warning is not emitted for successful requests
• Warning is emitted only after retries are exhausted
• Warning message includes migration guidance
• Existing return behavior remains unchanged

Suggested branch

feat/http-compatibility-warnings

The branch should start from and target:

release/0.9.0

Dependencies

Depends on:

• Add optional strict HTTP mode #269

Acceptance criteria

• Compatibility behavior remains functional
• A targeted package warning is emitted
• Users can filter the warning by class
• The warning explains how to opt into strict mode
• 404 behavior remains warning-free
• Documentation includes warning-filter examples
• Offline tests pass

Not included

• Changing the default to strict mode
• Warning on every request
• Removing compatibility behavior
• Strict 404 handling