python-mlb-statsapi 0.9.0

Version 0.9.0 is the configurable HTTP behavior release.

Version 0.8.0 made the network layer reliable. Version 0.9.0 makes it explainable and adjustable: callers can now reuse the library's retry policy, inspect much more context on a failed request, and choose whether an unexpected HTTP response raises or falls back to the historical empty result.

Default return values and endpoint behavior remain compatible. Compatibility mode is still the default, but final non-404 4xx responses now emit MlbHttpCompatibilityWarning. Applications that treat warnings as errors may need to handle or selectively filter this warning, or opt into strict_http=True.

Most applications do not need code changes to upgrade because compatibility mode remains the default. Applications that treat warnings as errors should handle or selectively filter MlbHttpCompatibilityWarning, or opt into strict_http=True.

Highlights

Public retry policy

create_retry_policy() is now part of the public API:

import requests
import mlbstatsapi

session = requests.Session()
adapter = requests.adapters.HTTPAdapter(
    max_retries=mlbstatsapi.create_retry_policy(),
)
session.mount("https://", adapter)
session.mount("http://", adapter)

try:
    with mlbstatsapi.Mlb(session=session) as mlb:
        player = mlb.get_person(664034)
finally:
    session.close()

Each call returns a new urllib3.util.retry.Retry instance configured exactly like the policy the library mounts on Sessions it creates, so a caller-managed Session can opt in to the same tested behavior instead of reinventing it.

Injected Sessions are still never modified automatically. The caller mounts the adapters and the caller closes the Session.

The retry values themselves are unchanged from version 0.8.0: up to three retries for GET requests, a 0.5 backoff factor, Retry-After respected, and a retryable status list of 429, 500, 502, 503, and 504.

Richer HTTP errors

MlbHttpError now carries enough context to diagnose a failure without re-running the request:

method
status_code
reason
url
response_data
body_excerpt

try:
    with mlbstatsapi.Mlb() as mlb:
        player = mlb.get_person(664034)
except mlbstatsapi.MlbHttpError as exc:
    print(exc.method)
    print(exc.status_code)
    print(exc.reason)
    print(exc.url)
    print(exc.response_data)
    print(exc.body_excerpt)

response_data holds the decoded JSON dictionary or list when the error body contains one, and is None for HTML, plain text, empty bodies, and JSON scalars. body_excerpt is a bounded excerpt of the response text, capped at 500 characters.

Context collection is best-effort and never replaces the original HTTP error. Complete response bodies are not retained beyond the excerpt and are not automatically logged, and str(exc) stays concise.

status_code, reason, and url behave exactly as they did in version 0.8.0.

Optional strict HTTP mode

Applications that prefer explicit failures can opt in:

import mlbstatsapi

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

In strict mode a final non-404 4xx response raises MlbHttpError instead of returning the historical empty result. Final 5xx responses raise in both modes, as they already did.

Strict mode is evaluated only after the bounded retry policy is exhausted, it does not change 404 handling, and it does not affect timeout, transport, decode, or Pydantic validation failures.

Compatibility warnings

Compatibility mode remains the default, but it is no longer silent. When a final non-404 4xx response is converted into the historical empty result, the library emits MlbHttpCompatibilityWarning:

HTTP 403 for https://statsapi.mlb.com/api/v1/sports was handled through
compatibility mode and returned the historical empty result. Pass
strict_http=True to raise MlbHttpError. This compatibility behavior may
change in version 1.0.

The category inherits from FutureWarning so it stays visible under default filters, and it can be targeted precisely:

import warnings
import mlbstatsapi

warnings.filterwarnings(
    "error",
    category=mlbstatsapi.MlbHttpCompatibilityWarning,
)

Warning messages contain only the status code and the request URL. No warning is emitted for successful responses, 404 responses, intermediate retries, final 5xx responses, or in strict mode.

Versioned User-Agent

A Session created by the library now identifies itself:

python-mlb-statsapi/0.9.0

The version is read from the installed distribution metadata rather than a duplicated source constant, so the header always matches the installed release. Only the User-Agent header is set; the remaining Requests defaults are preserved.

Caller-injected Session headers are left untouched. This header carries nothing beyond the package name and version.

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

Ownership rules are unchanged from version 0.8.0. Version 0.9.0 only makes the library-created side more capable, and the injected side is still never reconfigured or closed by the library.

Preserved compatibility

This release preserves:

• The synchronous Mlb client and every existing endpoint method
• Existing constructor arguments, with strict_http added as a keyword-only option
• Existing endpoint return types
• Endpoint-specific 404 results such as None, [], and {}
• Existing MlbHttpError attributes
• Existing broad handling through TheMlbStatsApiException
• Existing retry values
• Existing Session ownership behavior

Testing and release validation

The release adds deterministic offline coverage for the HTTP contract, compatibility warnings, the public retry policy, exception context, and Session ownership. Warnings are asserted directly rather than suppressed.

Packaging is validated by scripts/validate_release.py, which builds on the artifacts in dist/ and checks the wheel and source distribution, the reported distribution name and version, a clean-virtual-environment installation, the public imports, the retry policy return type, both HTTP modes, the User-Agent produced from installed metadata, and that injected Session headers survive untouched. The validator never contacts the MLB API and runs in offline CI.

Migration guidance

No action is required to upgrade. Compatibility mode is the default and existing code keeps its current behavior.

If MlbHttpCompatibilityWarning appears in your logs, it marks a call site where the MLB API returned a non-404 4xx and the library returned an empty result anyway. That is a real request failure being hidden, and it is worth handling.

The recommended path is:

1. Leave the default in place and watch for the warning
2. Handle or investigate the call sites the warning identifies
3. Turn the warning into an error in tests to keep new occurrences from creeping in
4. Enable strict_http=True once those call sites handle MlbHttpError

Version 0.9.0 keeps compatibility mode as the default, and the warnings provide advance migration guidance. A future 1.0 release may make stricter non-404 4xx behavior the default. No final 1.0 decision is being made in this release.

Installation

Once version 0.9.0 is published:

python3 -m pip install --upgrade python-mlb-statsapi

Not included

Version 0.9.0 does not add:

• Async support
• Response caching
• New MLB endpoints
• Global rate limiting
• Strict behavior for 404 responses
• Strict mode as the default
• New retry values
• Telemetry