Table of Contents generated with DocToc

sportsdataverse-py

Lifecycle:experimental PyPIPyPI - Down loads Contributors Twitter Follow

See CHANGELOG.md for details.

The goal of sportsdataverse-py is to provide the community with a python package for working with sports data as a companion to the cfbfastR, hoopR, and wehoop R packages. Beyond data aggregation and tidying ease, one of the multitude of services that sportsdataverse-py provides is for benchmarking open-source expected points and win probability metrics for American Football.

Supported leagues and data sources

League Module Surfaces covered
NBA sportsdataverse.nba ESPN (Site v2 + Web v3 + Core v2) + stats.nba.com (nba_stats_*, 112 wrappers; G-League league_id="20" / Summer League "15") + Fox Sports (Bifrost)
WNBA sportsdataverse.wnba ESPN + stats.wnba.com (wnba_stats_*, 95 wrappers)
MBB (NCAA M) sportsdataverse.mbb ESPN + NCAA-only (rankings, recruits) + stats.ncaa.org (ncaa_mbb_* bigballR-parity family + mbb_ncaa_* pbp/lineup/stint engine) + Fox Sports (Bifrost)
WBB (NCAA W) sportsdataverse.wbb ESPN + NCAA-only + stats.ncaa.org (ncaa_wbb_* family)
CFB sportsdataverse.cfb ESPN + NCAA + stats.ncaa.org (cfb_ncaa_pbp + box/drives/officials parsers) + football-only (QBR) + Fox Sports (Bifrost) + Yahoo Sports
NFL sportsdataverse.nfl ESPN + NFL.com API (api.nfl.com "Shield") + nflverse loaders (nflreadpy parity) + football-only (QBR)
MLB sportsdataverse.mlb ESPN + MLB Stats API (statsapi.mlb.com) + Baseball Savant / Statcast (43-endpoint mlb_statcast_* surface) + Fox Sports (Bifrost)
NHL sportsdataverse.nhl api-web.nhle.com/v1/ (game-feed) + NHL EDGE (player tracking) + Stats REST + Records site + Fox Sports (Bifrost)
PWHL sportsdataverse.pwhl HockeyTech/LeagueStat (schedule / pbp / shifts / strength-state / xG)
Minor & junior hockey sportsdataverse.hockey.<lg> HockeyTech — 20 registry-driven league families (ahl, echl, ohl, whl, qmjhl, ushl, bchl, …), 13 callables each
College hockey (M/W) sportsdataverse.hockey.mch / .wch ESPN
College baseball & softball sportsdataverse.baseball ESPN + stats.ncaa.org pbp parsers + run-expectancy helpers
Soccer sportsdataverse.soccer ESPN (league-parameterized wrappers — MLS, NWSL, EPL, …)
Cricket sportsdataverse.cricket ESPN (league-parameterized) + bundled win-probability models
UFL / XFL / CFL sportsdataverse.football ESPN
Odds sportsdataverse.odds Odds & betting-lines wrappers and loaders

The big-league modules export roughly 240–680 public functions each (ESPN wrappers + that league's native-API wrappers + dataset loaders + parsers) — about 4,400 exported names package-wide. Fox Sports adds fox_<league>_* Bifrost wrappers (pbp / boxscore / odds / roster / stats / standings / leaders) for nba, mbb, cfb, mlb, nhl; Yahoo Sports adds yahoo_cfb_* season-stats / scoreboard wrappers for college football. sportsdataverse.release ports the sportsdataversedata R release utilities (GitHub-release asset publish / download helpers, including a pure-Python RDS writer).

Polars / pandas parser layer

Parser-backed wrappers return a tidy polars DataFrame by default (0.0.54+). Pass return_parsed=False for the raw Dict, or return_as_pandas=True for pandas. Wrappers without a registered parser return the raw Dict.

from sportsdataverse.nba import espn_nba_team_roster

df  = espn_nba_team_roster(team_id=13)                          # → polars (default)
raw = espn_nba_team_roster(team_id=13, return_parsed=False)     # → Dict
pdf = espn_nba_team_roster(team_id=13,
                            return_as_pandas=True)              # → pandas

For the NHL and MLB sibling-API wrappers, compose the wrapper with its parser:

from sportsdataverse.nhl import nhl_web_pbp, parse_nhl_web_pbp
df = parse_nhl_web_pbp(nhl_web_pbp(2023030417))                 # 331-row polars frame

See py.sportsdataverse.org/docs/architecture/espn-cross-league and py.sportsdataverse.org/docs/parsers/index for the full architecture + parser registry.

Installation

The package metadata lives entirely in pyproject.toml (PEP 621 [project] table). There is no setup.py source-of-truth.

Standard install (pip)

pip install sportsdataverse

With optional extras (defined in [project.optional-dependencies] in pyproject.toml):

pip install "sportsdataverse[all]"      # everything below
pip install "sportsdataverse[models]"   # extra deps for the EPA / WP model code
pip install "sportsdataverse[tests]"    # adds pytest, mypy, ruff, etc.

Modern install (uv — recommended)

uv is the fast, drop-in package manager we use day to day.

# Add to a uv-managed project:
uv add sportsdataverse

# With extras:
uv add "sportsdataverse[all]"

# Or install the latest dev snapshot from GitHub:
uv add "sportsdataverse @ git+https://github.com/sportsdataverse/sportsdataverse-py"

Development install

For contributing or running the test suite:

git clone https://github.com/sportsdataverse/sportsdataverse-py.git
cd sportsdataverse-py

# uv (recommended) — fully resolved editable install with every extra:
uv pip install -e ".[all]"

# Plain pip works too if uv isn't available:
pip install -e ".[all]"

Note: once we add a PEP 735 [dependency-groups] block (currently the repo only ships PEP 621 [project.optional-dependencies]), uv sync --all-extras --all-groups will become the one-shot dev incantation. Until then, uv pip install -e ".[all]" is the equivalent path.

Run the test suite:

uv run pytest                       # offline tests only
SDV_PY_LIVE_TESTS=1 uv run pytest   # include live API tests (slower; hits ESPN / nflverse)

For deeper dev-environment detail (lint, mypy, dep-bumping workflow), see CONTRIBUTING.md.

Notes

  • Python target: 3.9–3.14.
  • DataFrame engine: polars 1.x. Most loaders accept return_as_pandas=True if you prefer pandas.
  • NFL caching: loaders cache to memory by default. Set SDV_PY_NFL_CACHE=filesystem for cross-session reuse, or SDV_PY_NFL_CACHE=off to disable. See sportsdataverse.nfl.config.update_config() for runtime control.
  • stats.nba.com / stats.wnba.com surface (nba_stats_* / wnba_stats_*): 112 NBA (+ G-League + Summer League via league_id) and 95 WNBA wrappers are available — the capture-confirmed live, non-deprecated endpoints (the full active/dying/barren/dead matrix lives in sdv-internal-refs/nba/ENDPOINT_HEALTH.md). The generic parser also handles the family's non-uniform shapes — the shot-location endpoints' grouped (2-level) headers and the scoreboardv3 game feed. Live calls to stats.nba.com require the curl_cffi package (TLS fingerprint protection); install it via pip install "sportsdataverse[all]" or pip install curl_cffi separately.

Examples and tutorials

Every public function ships a runnable Example: block in its docstring showing a quick-start call, common parameter combinations, and a one-line pipeline next-step. Regenerate the API reference locally with uv run python tools/codegen/generate.py --docs (then cd docs && yarn build to preview the Docusaurus site) or browse the live docs at py.sportsdataverse.org.

For longer-form walkthroughs, see the intro/intermediate Jupyter notebooks under examples/notebooks/:

Notebook Covers
01_quickstart.ipynb Cross-sport intro — package layout, polars vs pandas, the download() retry layer
02_cfb_intro.ipynb College football PBP, schedule, teams, espn_cfb_play_participants
03_nfl_intro.ipynb NFL — nflreadpy parity surface, caching layer, current-season helpers
04_nba_intro.ipynb NBA — PBP, schedule, teams, game rosters, shot distribution
05_wbb_intro.ipynb Women's college basketball — PBP, schedule, multi-table player stats
06_mbb_intro.ipynb Men's college basketball — PBP, schedule, conference standings
07_nhl_intro.ipynb NHL — PBP, schedule, teams, shot-event filter
08_wnba_intro.ipynb WNBA — PBP, schedule, rosters, player stats
09_mlb_intro.ipynb MLB — Stats API + Statcast search / leaderboards / gamefeed
10_pwhl_intro.ipynb PWHL — HockeyTech schedule, PBP, shifts, xG
11_junior_hockey_intro.ipynb HockeyTech minor/junior leagues — one family shape across 20 leagues
12_odds_intro.ipynb Odds & betting lines
13_soccer_intro.ipynb ESPN soccer — league-parameterized wrappers
14_cricket_intro.ipynb ESPN cricket + win-probability models
15_other_espn_leagues_intro.ipynb UFL/XFL/CFL, college hockey, college baseball/softball ESPN families

Companion packages

sportsdataverse-py is one corner of the broader SportsDataverse ecosystem. The R sister packages cover the same data sources with deeper sport-specific coverage:

The NFL submodule is a near drop-in replacement for nflreadpy; the broader nflverse ecosystem is the upstream data source for many of those loaders.

Our Authors

Citations

To cite the sportsdataverse-py Python package in publications, use:

BibTex Citation

@misc{gilani_sdvpy_2021,
  author = {Gilani, Saiem},
  title = {sportsdataverse-py: The SportsDataverse's Python Package for Sports Data.},
  url = {https://py.sportsdataverse.org},
  season = {2021}
}

Project links

Data verified by PyPI on Aug 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for saiemgilani from gravatar.com saiemgilani

Credits

PyPI data
Data sourced directly from PyPI's database.

Author/Maintainer: Saiem Gilani

GitHub Statistics

Data verified by PyPI on Aug 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.9

Provides Extra

tests models pff all

Tags

nba wnba nfl college football ncaa basketball mlb nhl espn mlb stats api statcast baseball savant nhl edge nhl api-web data epa statistics win probability play-by-play web scraping polars parser

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sportsdataverse-0.0.75.tar.gz (18.6 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

sportsdataverse-0.0.75-py3-none-any.whl (19.4 MB view details)

Uploaded Python 3

File details

Details for the file sportsdataverse-0.0.75.tar.gz.

File metadata

  • Download URL: sportsdataverse-0.0.75.tar.gz
  • Upload date:
  • Size: 18.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sportsdataverse-0.0.75.tar.gz
Algorithm Hash digest
SHA256 0215606345d91967dabe6eed17a28d894a32e2115f9e99ca82128fcd785f1a1c
MD5 8bccabed69e2639ad453d2a14c3d207c
BLAKE2b-256 b98abef848b90fdaf350da61c033aa0b1745f2d1b56025b2d015a1f0b18c9710

See more details on using hashes here.

Provenance

The following attestation bundles were made for sportsdataverse-0.0.75.tar.gz:

Publisher: python-publish.yml on sportsdataverse/sportsdataverse-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sportsdataverse-0.0.75-py3-none-any.whl.

File metadata

File hashes

Hashes for sportsdataverse-0.0.75-py3-none-any.whl
Algorithm Hash digest
SHA256 3b5a3cb952e6a28c978e8180f495eed8cc60086b0e52ab7042da84e62b277228
MD5 6c04088c10aab9216970b1aa8ba866b9
BLAKE2b-256 ddcda2d0d5067f65765f92ce877b7553208eb515eb9874b4b6f953a152eea1b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for sportsdataverse-0.0.75-py3-none-any.whl:

Publisher: python-publish.yml on sportsdataverse/sportsdataverse-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.75 This release

2 files

0.0.74

2 files

0.0.73

2 files

0.0.72

2 files

0.0.71

2 files

0.0.70

2 files

0.0.69

2 files

0.0.68

2 files

0.0.67

2 files

0.0.66

2 files

0.0.65

2 files

0.0.63

2 files

0.0.62

2 files

0.0.61

2 files

0.0.60

2 files

0.0.59

2 files

0.0.58

2 files

0.0.56

2 files

0.0.55

2 files

0.0.54

2 files

0.0.53

2 files

0.0.52

2 files

0.0.51

2 files

0.0.50

2 files

0.0.40

2 files

0.0.39

2 files

0.0.38

2 files

0.0.37

2 files

0.0.36.3.3

2 files

0.0.36.3.2

2 files

0.0.36.3.1

2 files

Pre-release

0.0.36.3.1.dev1

2 files

0.0.36.2.44

2 files

0.0.36.2.43

2 files

0.0.36.2.42

2 files

0.0.36.2.41

2 files

0.0.36.2.40

2 files

0.0.36.2.39

2 files

0.0.36.2.38

2 files

0.0.36.2.37

2 files

0.0.36.2.36

2 files

0.0.36.2.35

2 files

0.0.36.2.34

2 files

0.0.36.2.33

2 files

0.0.36.2.32

2 files

0.0.36.2.31

2 files

0.0.36.2.30

2 files

0.0.36.2.29

2 files

0.0.36.2.28

2 files

0.0.36.2.27

2 files

0.0.36.2.26

2 files

0.0.36.2.25

2 files

0.0.36.2.24

2 files

0.0.36.2.23

2 files

0.0.36.2.22

2 files

0.0.36.2.21

2 files

0.0.36.2.20

2 files

0.0.36.2.19

2 files

0.0.36.2.18

2 files

0.0.36.2.17

2 files

0.0.36.2.16

2 files

0.0.36.2.15

2 files

0.0.36.2.14

2 files

0.0.36.2.13

2 files

0.0.36.2.12

2 files

0.0.36.2.11

2 files

0.0.36.2.10

2 files

0.0.36.2.9

2 files

0.0.36.2.8

2 files

0.0.36.2.7

2 files

0.0.36.2.6

2 files

0.0.36.2.5

2 files

0.0.36.2.4

2 files

0.0.36.2.3

2 files

0.0.36.2.2

2 files

0.0.36.2.1

2 files

0.0.36.2

2 files

0.0.36.1

2 files

0.0.36

2 files

0.0.35

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page