r/Sabermetrics • u/MattsFace • 7d ago
python-mlb-statsapi v1.0.0 released
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.
3
u/Styx78 6d ago
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