Skip to content

python-mlb-statsapi 1.1.0

Version 1.1.0 adds first-class asynchronous access to the MLB Stats API while preserving the existing synchronous API. Applications upgrading from 1.0.x that use Mlb or MlbDataAdapter require no code changes.

Async support

Install the optional async extra to add HTTPX, the asynchronous transport dependency:

python3 -m pip install "python-mlb-statsapi[async]"

The extra provides the public AsyncMlb and AsyncMlbDataAdapter classes. AsyncMlb covers the full endpoint surface exposed by Mlb. Sync and async endpoints share the same parsing functions and return matching public Pydantic models, values, and endpoint-specific empty-result shapes.

from mlbstatsapi import AsyncMlb


async def get_player(person_id: int):
    async with AsyncMlb() as mlb:
        return await mlb.get_person(person_id)

async with AsyncMlb(...) returns the client and closes library-owned HTTPX resources when the block exits. Directly constructed clients support explicit await mlb.aclose(), and repeated aclose() calls are safe. An injected httpx.AsyncClient remains caller-owned and is never closed or reconfigured by AsyncMlb.

One AsyncMlb instance supports caller-controlled concurrent requests on the same event loop. It does not create hidden request fanout or background tasks, and cross-event-loop use is not promised. Caller cancellation propagates without blocking unrelated concurrent requests.

Library-created HTTPX clients honor HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY from the environment while retaining the library's bounded retry policy. Injected clients keep their caller-provided proxy and transport configuration.

HTTP compatibility

strict_http=True remains the default for both synchronous and asynchronous clients. New code should use strict_http=True and handle MlbHttpError.

strict_http=False remains supported throughout the 1.x release series and may be removed in 2.0. It continues to provide the documented compatibility path for final non-404 4xx responses; it is not removed or deprecated in 1.1.0.

The base installation remains synchronous-only and does not require HTTPX. Existing 1.0.x synchronous users require zero code changes for 1.1.0.

Python and release validation

python-mlb-statsapi requires Python >=3.10. CI validates Python 3.10 through 3.14 (3.10, 3.11, 3.12, 3.13, and 3.14) for the deterministic offline sync and async suites.

Release validation now checks both wheel and source-distribution installs in separate clean environments. Each artifact retains its existing synchronous smoke validation and is also installed with the async extra to verify the public async imports, lifecycle, ownership, strict/compatibility behavior, and versioned User-Agent without contacting the live MLB API.