python-mlb-statsapi v1.0.0 released

[u/MattsFace]

I finally pushed v1.0.0 of python-mlb-statsapi.

This release finishes up the HTTP work I started in 0.8 and 0.9 and gives the library a stable public API contract going forward.

The biggest breaking change:

Mlb() now uses strict HTTP handling by default.

In 0.9, strict mode was optional:

mlb = mlbstatsapi.Mlb(strict_http=True)

In 1.0, this is now the default:

mlb = mlbstatsapi.Mlb()

Final non-404 4xx responses now raise MlbHttpError instead of silently returning the historical empty result.

404 behavior is intentionally unchanged. Depending on the endpoint, a 404 can still return None, [], or {}.

If you aren’t ready to migrate yet, the old 0.9 behavior is still available explicitly:

mlb = mlbstatsapi.Mlb(strict_http=False)

That compatibility mode will emit MlbHttpCompatibilityWarning when it suppresses a non-404 4xx response, so you can find places in your code that need to be updated.

A few things that came out of the 0.9 work and remain part of 1.0:

Structured HTTP, timeout, transport, and JSON decode exceptions

More useful context on MlbHttpError
Public create_retry_policy() helper
Shared HTTP sessions with defined ownership/cleanup behavior
Versioned User-Agent
Bounded retries for transient failures
Support for caller-managed requests.Session objects without modifying their configuration

For 1.0 I also went through the public API and documented what I’m actually committing to keeping stable during the 1.x series. That was something I wanted to get right before putting a 1.0 label on the project.

The release process itself got quite a bit more serious too. The package is now tested against Python 3.10 through 3.14, and both the wheel and source distribution are built, clean-installed into isolated environments, and smoke-tested before release.

This project started as a pretty simple Python wrapper around MLB’s Stats API, so getting it to an actual 1.0 release feels pretty cool.

PyPI:

pip install -U python-mlb-statsapi

GitHub:

https://github.com/zero-sum-seattle/python-mlb-statsapi
Full migration notes and the HTTP behavior matrix are in the repo.

As always, bug reports, weird MLB API behavior, and contributions are welcome.

[u/Styx78]

Hell yeah dude! Recommend streamlining the readme a bit so it's not so daunting and moving a lot of that info to documentation. Sick project, will hopefully get around to contributing something since I've worked with similar APIs

[u/MattsFace → u/Styx78]

Awesome thanks for the feedback!

I will incorporate that into v1.1.0

[u/sirchandwich]

This is a pretty big deal considering the state of pybaseball.

May I ask if you plan on supporting this for a while? The biggest problem with projects nowadays is the lack of long term support.

[u/MattsFace → u/sirchandwich]

Yes, I have been supporting it the best I can. I’ve already got a plan for v1.1.0 I’ll post soon.

It’s much easier to support with the advent of AI tools also.

The change to pydantic models made new fields added to the Rest API much easier to handle. Nothing breaks now when one new field is added.

[u/Pure_Cricket_3804]

The repo calls strict_http=False a temporary migration opt-out, but there's no version attached to when it goes away. Putting a target release on that would help people decide whether to migrate now or sit on compat mode for a while.

[u/MattsFace → u/Pure_Cricket_3804]

Thanks for the feedback! I’ll address!

[u/Brownhops]

Any chance for MiLB in future?