Table of Contents generated with DocToc
sportsdataverse-py 
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_*, 128 wrappers; G-League league_id="20" / Summer League "15") + Fox Sports (Bifrost) |
| WNBA | sportsdataverse.wnba |
ESPN + stats.wnba.com (wnba_stats_*, 111 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 + ESPN dataset loaders (teams / rosters / unified schedules / team info) |
| 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,650 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-groupswill 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=Trueif you prefer pandas. - NFL caching: loaders cache to memory by default. Set
SDV_PY_NFL_CACHE=filesystemfor cross-session reuse, orSDV_PY_NFL_CACHE=offto disable. Seesportsdataverse.nfl.config.update_config()for runtime control. - stats.nba.com / stats.wnba.com surface (
nba_stats_*/wnba_stats_*): 112 NBA (+ G-League + Summer League vialeague_id) and 95 WNBA wrappers are available — the capture-confirmed live, non-deprecated endpoints (the full active/dying/barren/dead matrix lives insdv-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 thescoreboardv3game feed. Live calls tostats.nba.comrequire thecurl_cffipackage (TLS fingerprint protection); install it viapip install "sportsdataverse[all]"orpip install curl_cffiseparately.
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:
- wehoop — women's basketball (WNBA + NCAA)
- hoopR — men's basketball (NBA + NCAA)
- cfbfastR — college football
- baseballr — baseball (MLB + MiLB + NCAA)
- fastRhockey — hockey (NHL + WHL)
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}
}
1 maintainer
Metadata
1 maintainer
Release files for sportsdataverse 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sportsdataverse-0.1.0.tar.gz | 18.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sportsdataverse-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 37.4 MB
Release files / sportsdataverse-0.1.0.tar.gz
| Download URL | sportsdataverse-0.1.0.tar.gz |
|---|---|
| Size | 18.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2ab9642965fd484e22f0f1cbc747d7f766620650be5bde1f3b9443a88b63d5b6
|
|
BLAKE2b-256 checksum How to use checksums |
8fe16ed11624290edee81fd9a963620c16545219f5a537494ef8128611cdc605
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.
Transparency logRelease files / sportsdataverse-0.1.0-py3-none-any.whl
| Download URL | sportsdataverse-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
000d8039f07b3ccd0efeaf1cb539e3819699970065e44bff7338bc5f5b51eb5e
|
|
BLAKE2b-256 checksum How to use checksums |
0670e18be2294e77cae559751cb329aad8d50f6af3e4880b24ca1257f67f84ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 27, 2026.
Transparency log
