release: prepare python-mlb-statsapi 0.9.0

[Mattsface]

Refs #265
Refs #272

Summary

Version 0.9.0 is the configurable HTTP behavior release.

This release builds on the HTTP reliability work from 0.8.0 by exposing the retry policy as a supported public API, adding richer HTTP error context, introducing an optional strict mode, warning when compatibility mode suppresses a client error, and identifying library-created Sessions with a versioned User-Agent.

The release branch is currently 20 commits ahead of main and 0 commits behind.

Highlights

Public retry policy

create_retry_policy() is now part of the package-root public API.

Callers who own their own requests.Session can explicitly mount the same tested retry policy used by library-created Sessions without the library silently changing their adapters.

The retry values remain unchanged from 0.8.0:

• GET requests only
• up to three retries after the initial request
• retry statuses: 429, 500, 502, 503, and 504
• backoff factor: 0.5
• Retry-After respected

Richer MlbHttpError context

MlbHttpError preserves its existing public fields and adds:

• method
• response_data
• body_excerpt

JSON dictionaries and lists are captured when available, while text context is limited to a bounded 500-character excerpt. Context extraction is best-effort and cannot replace the original HTTP error.

Optional strict HTTP mode

Applications can opt into stricter behavior:

import mlbstatsapi

with mlbstatsapi.Mlb(strict_http=True) as mlb:
    player = mlb.get_person(664034)

In strict mode:

• final non-404 4xx responses raise MlbHttpError
• final 5xx responses raise MlbHttpError
• existing endpoint-specific 404 behavior remains unchanged

Compatibility mode remains the default for 0.9.0.

Compatibility warnings and the path toward 1.0

When compatibility mode converts a final non-404 4xx response into the historical empty result, the library now emits MlbHttpCompatibilityWarning.

The warning inherits from FutureWarning, includes migration guidance for strict_http=True, and can be filtered independently from unrelated warnings.

This release does not make strict mode the default. A future 1.0 release may make final non-404 4xx responses raise by default, which would be a breaking change. Version 0.9.0 provides the opt-in mode and warning period needed to find affected call sites before that decision is finalized.

Versioned User-Agent

Sessions created by the library now send:

python-mlb-statsapi/<installed-version>

For this release, the installed wheel resolves that to:

python-mlb-statsapi/0.9.0

The value comes from installed package metadata rather than a duplicated source constant. Caller-injected Session headers remain untouched.

Session ownership remains explicit

Library-created Session
    Configured and closed by the library
    Receives retry adapters
    Receives the package User-Agent

Caller-injected Session
    Configured and closed by the caller
    Existing adapters remain untouched
    Existing headers remain untouched

The library does not silently reconfigure or close a Session supplied by the caller.

Documentation and release validation

This release expands the README and detailed HTTP transport documentation, adds 0.9.0 release notes, updates CI for the current release branch, and adds a focused release validator.

The validator checks:

• wheel and source-distribution presence
• package name, version, and Python metadata
• clean virtual-environment installation of the wheel
• public imports
• retry-policy construction
• compatibility-warning inheritance
• strict and compatibility mode construction
• metadata-driven User-Agent behavior
• injected Session header preservation

The installed-wheel smoke test runs outside the repository checkout so local source files cannot shadow the installed package.

Compatibility

Version 0.9.0 preserves:

• the synchronous Mlb client
• existing endpoint method names and return types
• existing constructor usage, with strict_http added as a keyword-only option
• compatibility mode as the default
• endpoint-specific 404 results such as None, [], and {}
• broad exception handling through TheMlbStatsApiException
• existing retry values
• caller ownership of injected Sessions
• caller-defined headers and adapters on injected Sessions

One intentional visible difference is that compatibility mode is no longer silent for final non-404 4xx responses. Applications or test suites that treat warnings as errors may need to handle or selectively filter MlbHttpCompatibilityWarning, or opt into strict_http=True.

Validation completed on the release branch

• poetry check — passed, with pre-existing Poetry deprecation notices only
• offline suite — 318 passed
• focused HTTP contract, warning, retry, exception, and Session suites — passed
• live MLB API suite — 119 passed, 1 pre-existing skip
• Python 3.10, 3.11, and 3.12 offline CI — passed
• wheel and source distribution build — passed
• clean-wheel release validator — passed
• git diff --check — clean

The final pull-request CI must still pass against main before this PR is marked ready.

Review focus

Please pay particular attention to:

• compatibility-mode versus strict-mode response boundaries
• final 429 behavior after retry exhaustion
• unchanged 404 handling
• warning conditions and migration guidance
• bounded and safe HTTP error context
• injected Session ownership and non-modification
• versioned User-Agent behavior
• public API exports
• release documentation accuracy
• package metadata and clean-wheel validation

Before marking ready

• Clarify the release-note statements that currently say “Nothing about the default behavior changes” and “No action is required to upgrade”; default return behavior is preserved, but warning-as-error environments can be affected
• Remove or revise the temporary pre-publication disclaimer in the permanent release-notes document
• Confirm final PR CI passes against main
• Run python -m twine check dist/*
• Review the complete main...release/0.9.0 diff one final time

Merge and publishing plan

After review and validation:

1. Merge this PR using a merge commit so the release-branch history remains visible.
2. Tag the exact merge commit as v0.9.0.
3. Rebuild the wheel and source distribution from the tagged commit.
4. Run the release validator and twine check against those artifacts.
5. Publish both artifacts to PyPI through an explicitly authorized release action.
6. Install python-mlb-statsapi==0.9.0 from public PyPI with cache disabled and run the public smoke checks.
7. Create the GitHub release from the final 0.9.0 release notes.
8. Close Document and prepare release 0.9.0 #272 and Release 0.9.0: Configurable HTTP behavior #265 after publication is verified.

Do not tag or publish as part of reviewing this PR.