Release 0.9.0: Configurable HTTP behavior

[Mattsface]

Release 0.9.0: Configurable HTTP behavior

Why

Version 0.8.0 improved the reliability of the HTTP transport with shared Sessions, explicit timeouts, bounded retries, and structured exceptions.

However, several transport policies are still fixed or internal:

• The default retry policy is only applied to library-created Sessions
• Caller-injected Sessions cannot reuse the library’s tested retry policy through a supported public API
• Most final 4xx responses still use the package’s historical compatibility behavior
• MlbHttpError contains limited response context
• The HTTP client does not identify its package version through a default User-Agent

Version 0.9.0 should make these behaviors more configurable while preserving the current defaults.

This release should also provide a clear migration path toward stricter HTTP error handling in version 1.0.

Goals

• Establish deterministic tests for the new HTTP behavior
• Expose the default retry policy as a supported public API
• Allow caller-injected Sessions to explicitly opt into the tested retry policy
• Add richer context to MlbHttpError
• Add an optional strict HTTP mode
• Add targeted warnings for compatibility behavior planned to change in 1.0
• Add a versioned User-Agent to library-created Sessions
• Update HTTP documentation and release notes
• Preserve current behavior by default

Compatibility requirements

Version 0.9.0 must preserve:

• The synchronous Mlb client
• Existing endpoint method signatures
• Existing endpoint return types
• Existing constructor usage
• Existing broad exception handling through TheMlbStatsApiException
• Compatibility-mode behavior as the default
• Existing endpoint-specific 404 behavior
• Ownership of caller-injected Sessions
• Existing caller-defined adapters and retry settings
• Existing timeout configuration
• Existing library-created Session retry behavior

The library must not silently reconfigure a caller-injected Session.

Strict HTTP behavior must remain explicitly opt-in during version 0.9.0.

Planned work

• Establish the 0.9.0 HTTP behavior contract #266
• Expose the default retry policy for caller-managed Sessions #267
• Add richer context to MlbHttpError #268
• Add optional strict HTTP mode #269
• Add warnings for future strict HTTP behavior #270
• Add a versioned User-Agent #271
• Document and prepare release 0.9.0 #272
• Validate the built package
• Merge release/0.9.0 into main
• Tag and publish v0.9.0

Proposed behavior

Compatibility mode

Compatibility mode remains the default:

import mlbstatsapi

mlb = mlbstatsapi.Mlb()

Existing endpoint-specific handling remains unchanged.

A 404 continues to produce domain-level results such as:

None
[]
{}

Final non-404 4xx responses continue through the existing compatibility path during version 0.9.0.

Strict HTTP mode

Strict handling is explicitly enabled:

import mlbstatsapi

mlb = mlbstatsapi.Mlb(
    strict_http=True,
)

In strict mode:

• Final non-404 4xx responses raise MlbHttpError
• Final 5xx responses raise MlbHttpError
• Transport failures raise MlbTransportError
• Timeouts raise MlbTimeoutError
• Successful invalid JSON raises MlbDecodeError
• Existing endpoint-specific 404 behavior remains unchanged

Keeping 404 behavior separate avoids changing the domain-level not-found contract during version 0.9.0.

Branch strategy

feature branch
    ↓
release/0.9.0
    ↓
main
    ↓
v0.9.0

All version 0.9.0 feature branches should start from and target:

release/0.9.0

Recommended implementation order

#266 HTTP contract tests
    ↓
#267 Public retry policy
    ↓
#268 Richer HTTP errors
    ↓
#269 Optional strict mode
    ↓
#270 Compatibility warnings
    ↓
#271 Versioned User-Agent
    ↓
#272 Documentation and release preparation

The User-Agent work may proceed in parallel after the contract tests are established.

Out of scope

Version 0.9.0 will not add:

• Async support
• Response caching
• Persistent storage
• Global rate limiting
• Automatic throttling
• New MLB endpoints
• Broad endpoint return-type changes
• Strict 404 exceptions
• Strict mode as the default
• Removal of deprecated arguments
• Automatic modification of injected Sessions
• A major public API redesign

Optional transport observability hooks may be considered separately but should not block the release.

Definition of done

• Offline tests pass on every supported Python version
• Relevant live MLB API tests pass
• The default retry policy is available through a documented public API
• Injected Sessions can explicitly opt into the retry policy
• Injected Sessions remain caller-owned
• The library does not silently replace adapters on injected Sessions
• Existing MlbHttpError attributes remain available
• Additional HTTP error context is bounded and safe
• Compatibility mode remains the default
• Strict mode raises for final non-404 HTTP failures
• Existing 404 behavior remains unchanged
• Compatibility warnings clearly explain future 1.0 behavior
• Library-created Sessions send a versioned User-Agent
• Injected Session headers remain under caller control
• Documentation matches the final implementation
• The built wheel installs and passes smoke tests
• Version 0.9.0 is published to PyPI
• GitHub release v0.9.0 is published