Skip to content

python-mlb-statsapi 0.7.1

Version 0.7.1 completes the package’s migration to Pydantic v2 and removes the response-key transformation layer that previously altered data returned by the MLB Stats API.

This release includes breaking model and field-access changes for applications upgrading from the 0.5.x or 0.6.x releases.

Highlights

Native MLB response keys

The _transform_keys_in_data() compatibility layer has been removed.

Previous versions lowercased keys returned by the MLB Stats API before passing them into package models. Models now validate directly against MLB’s native response keys and use explicit Pydantic aliases where necessary.

This change:

  • Removes an unnecessary data-transformation step
  • Preserves the original MLB response structure
  • Makes unusual MLB capitalization easier to support
  • Reduces the risk of key collisions or silently altered field names
  • Simplifies response parsing and model validation

Complete Pydantic v2 migration

The migration from Python dataclasses to Pydantic v2 models, started in version 0.7.0, is now complete.

All package models now use Pydantic for:

  • Input validation
  • Type conversion
  • Field aliases
  • Serialization
  • Nested model construction
  • Optional and missing-field handling

Returned objects continue to expose Python-style snake_case attributes while accepting MLB’s native response keys through Pydantic aliases.

Example:

game.game_data.weather

Pydantic models can be serialized with:

data = model.model_dump()
json_data = model.model_dump_json()

Simplified test suite

The previous mocked-response tests and their associated JSON fixtures have been removed.

This deleted more than 22,000 lines of test and fixture data. The remaining test suite focuses on integration behavior against the live MLB Stats API.

Breaking changes

Model attributes use snake_case

Applications must access model fields using Python-style snake_case names.

Before:

game.gamedata.weather
stat.totalsplits

After:

game.game_data.weather
stat.total_splits

Validation failures use Pydantic exceptions

Invalid model data now raises:

pydantic.ValidationError

Applications that previously expected TypeError during model construction may need to update their exception handling.

Serialization uses Pydantic methods

Applications should use Pydantic’s public serialization methods instead of reading model internals directly.

Before:

data = game.__dict__

After:

data = game.model_dump()

JSON serialization is available through:

data = game.model_dump_json()

Model updates

Core models

  • Migrated remaining models to the shared Pydantic MLBBaseModel
  • Updated aliases to match MLB’s native response keys
  • Added optional handling for fields that may be missing or null
  • Improved nested-model validation
  • Preserved Python-style snake_case attribute access

Game models

Corrected aliases for:

gamePk
gameData
liveData
metaData

Home Run Derby models

Corrected aliases for:

homeRun
tieBreaker
isHomeRun
isTieBreaker

Statistics models

Corrected aliases for:

wobaCon
pitchArsenal

Additional statistics fixes include:

  • Added age to SimplePitchingSplit
  • Added caughtstealingpercentage to SimplePitchingSplit
  • Corrected flyballpercentage in AdvancedPitchingSplit
  • Added support for newly observed MLB statistics fields
  • Fixed missing values in several statistics models

Schedule models

Made calendarEventId optional to support responses where the field is absent.

Standings models

Made the following fields optional:

wildcardGamesBack
wildcardEliminationNumber

Live-feed models

Updated live-feed models to support previously missing response keys.

Compatibility

Applications already using the Pydantic models introduced in version 0.7.0 should require fewer changes than applications upgrading from 0.5.x or 0.6.x.

Applications upgrading from older releases should review:

  • Model attribute naming
  • Validation exception handling
  • Serialization code
  • Any direct assumptions about transformed response keys

The public endpoint methods remain available, but the model objects they return now consistently follow Pydantic v2 behavior.

Migration guide

Update field access

Replace older compact or camelCase-style field access with the model’s snake_case attributes.

Before:

game.gamedata.weather
stat.totalsplits

After:

game.game_data.weather
stat.total_splits

Update validation handling

Import and catch Pydantic’s validation exception:

from pydantic import ValidationError

try:
    game = Game(**data)
except ValidationError as exc:
    print(exc)

Update serialization

Replace direct __dict__ access with:

data = game.model_dump()

To exclude fields containing None:

data = game.model_dump(exclude_none=True)

To serialize as JSON:

json_data = game.model_dump_json()

Dependencies and packaging

  • Added Pydantic v2 as a core dependency
  • Completed the migration from setuptools-based project management to Poetry
  • Updated dependency and build configuration for the Poetry workflow

Testing and CI

This release:

  • Removes the previous mocked-response test suite
  • Removes the associated JSON fixtures
  • Updates external tests for the Pydantic model changes
  • Updates CI configuration to stop running the removed mocked tests

The test suite for this release relies primarily on the live MLB Stats API. Because MLB data and responses can change, external test results may be affected by upstream API availability or response changes.

Documentation

The README now includes:

  • Pydantic model examples
  • model_dump() and model_dump_json() usage
  • Python-style snake_case field examples
  • Updated code samples
  • A contributor section

Not included

Version 0.7.1 does not add:

  • New MLB endpoints
  • HTTP retries
  • Explicit request timeouts
  • Shared HTTP Sessions
  • Structured transport exceptions
  • Response caching
  • Async support

Those transport reliability improvements are planned separately.

Contributors

Thank you to everyone who contributed model corrections, migration work, testing, and documentation updates for this release.

Full changelog

Review the repository commit history and merged pull requests associated with versions 0.7.0 and 0.7.1 for the complete set of changes.