Skip to content

python-mlb-statsapi 0.8.0

Version 0.8.0 is the HTTP reliability release.

This release modernizes the package’s network layer while preserving the existing synchronous public API, endpoint return types, and endpoint-specific 404 behavior.

Highlights

Shared HTTP Sessions

Each Mlb client now uses one shared requests.Session for its v1 and v1.1 adapters.

This allows repeated requests to reuse pooled network connections.

Library-created Sessions are closed automatically when using the client as a context manager:

import mlbstatsapi

with mlbstatsapi.Mlb() as mlb:
    player = mlb.get_person(664034)
    team = mlb.get_team(136)

Callers may also inject their own Session. Injected Sessions remain caller-owned and are not closed or reconfigured by the library.

Explicit timeouts

Every request now has an explicit timeout.

The default is:

Connect timeout: 3.05 seconds
Read timeout: 30 seconds

Custom scalar or connect/read timeout values may be supplied:

with mlbstatsapi.Mlb(timeout=(5.0, 60.0)) as mlb:
    player = mlb.get_person(664034)

Bounded retries

Library-created Sessions automatically retry temporary GET failures for:

429
500
502
503
504

The initial request may be followed by up to three retries. Retries use exponential backoff and respect Retry-After headers.

Ordinary client errors such as 400, 401, 403, and 404 are not retried.

Caller-injected Sessions retain their existing retry and adapter configuration.

Structured exceptions

Version 0.8.0 introduces:

TheMlbStatsApiException
├── MlbTransportError
│   └── MlbTimeoutError
├── MlbHttpError
└── MlbDecodeError

All new exceptions inherit from TheMlbStatsApiException, preserving compatibility with applications that already catch the package’s base exception.

MlbHttpError exposes:

status_code
reason
url

HTTP response correctness

The HTTP adapter now:

  • Supports the complete successful 2xx status range
  • Handles status codes before decoding error bodies
  • Handles successful empty responses safely
  • Avoids shared mutable result dictionaries
  • Avoids modifying caller-owned response dictionaries
  • Distinguishes transport, timeout, HTTP, and JSON decoding failures

Preserved compatibility

This release preserves:

  • The synchronous Mlb client
  • Existing endpoint methods and constructor usage
  • Existing endpoint return types
  • Existing MlbResult attributes
  • Existing broad exception handling
  • Endpoint-specific 404 results such as None, [], and {}

A final 429 continues through the package’s existing 4xx compatibility behavior. Final 5xx responses raise MlbHttpError.

Testing and CI

The release adds deterministic offline transport coverage for:

  • Sessions and ownership
  • Timeout forwarding
  • Retry behavior
  • HTTP status handling
  • Empty and malformed responses
  • Structured exceptions
  • Context-manager cleanup

Offline CI now runs on Python 3.10, 3.11, and 3.12.

Live MLB API tests run separately through a manual and scheduled workflow. Normal pushes no longer publish automatically to TestPyPI or PyPI.

The final release package was validated by:

  • The deterministic offline test suite
  • The live MLB API test suite
  • A clean wheel installation
  • Public import checks
  • Live README example execution

Documentation

The README now includes practical examples for:

  • Context-manager usage
  • Shared Sessions
  • Custom timeouts
  • Injected Sessions
  • Retry behavior
  • Structured exceptions

See docs/http-transport.md for the complete HTTP transport documentation.

Not included

Version 0.8.0 does not add:

  • Async support
  • Response caching
  • New MLB endpoints
  • Strict exceptions for every 4xx response
  • Global rate limiting