{"id":22117177,"url":"https://github.com/sportsdataverse/sportsdataverse-py","last_synced_at":"2026-06-15T23:00:40.964Z","repository":{"id":40399062,"uuid":"416449053","full_name":"sportsdataverse/sportsdataverse-py","owner":"sportsdataverse","description":"sportsdataverse python package","archived":false,"fork":false,"pushed_at":"2026-06-11T20:54:36.000Z","size":26750,"stargazers_count":103,"open_issues_count":35,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-06-11T22:11:41.574Z","etag":null,"topics":["cfb-data","college-basketball","college-football","data-science","espn","hockey","nba","nba-stats","nfl","nflfastr","nhl","nhl-api","python","sports","sports-analytics","sports-data","sports-stats","sportsdataverse","wnba","womens-basketball"],"latest_commit_sha":null,"homepage":"https://py.sportsdataverse.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sportsdataverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-12T18:16:16.000Z","updated_at":"2026-06-11T20:51:57.000Z","dependencies_parsed_at":"2024-03-19T02:43:13.405Z","dependency_job_id":null,"html_url":"https://github.com/sportsdataverse/sportsdataverse-py","commit_stats":{"total_commits":271,"total_committers":5,"mean_commits":54.2,"dds":"0.28044280442804426","last_synced_commit":"8f757d3f30f0196f9e66da3711051d8c30ae5e88"},"previous_names":["saiemgilani/sportsdataverse-py"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/sportsdataverse/sportsdataverse-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sportsdataverse%2Fsportsdataverse-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sportsdataverse%2Fsportsdataverse-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sportsdataverse%2Fsportsdataverse-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sportsdataverse%2Fsportsdataverse-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sportsdataverse","download_url":"https://codeload.github.com/sportsdataverse/sportsdataverse-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sportsdataverse%2Fsportsdataverse-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34383468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cfb-data","college-basketball","college-football","data-science","espn","hockey","nba","nba-stats","nfl","nflfastr","nhl","nhl-api","python","sports","sports-analytics","sports-data","sports-stats","sportsdataverse","wnba","womens-basketball"],"created_at":"2024-12-01T13:29:34.361Z","updated_at":"2026-06-15T23:00:40.958Z","avatar_url":"https://github.com/sportsdataverse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*\n\n- [sportsdataverse-py \u003ca href='https://py.sportsdataverse.org'\u003e\u003cimg src='https://raw.githubusercontent.com/sportsdataverse/sportsdataverse-py/master/sdv-py-logo.png' align=\"right\"  width=\"20%\" min-width=\"100px\" /\u003e\u003c/a\u003e](#sportsdataverse-py-a-hrefhttpspysportsdataverseorgimg-srchttpsrawgithubusercontentcomsportsdataversesportsdataverse-pymastersdv-py-logopng-alignright--width20%25-min-width100px-a)\n  - [Supported leagues and data sources](#supported-leagues-and-data-sources)\n  - [Polars / pandas parser layer](#polars--pandas-parser-layer)\n  - [Installation](#installation)\n    - [Standard install (pip)](#standard-install-pip)\n    - [Modern install (uv — recommended)](#modern-install-uv--recommended)\n    - [Development install](#development-install)\n    - [Notes](#notes)\n  - [Examples and tutorials](#examples-and-tutorials)\n  - [Companion packages](#companion-packages)\n- [**Our Authors**](#our-authors)\n  - [**Citations**](#citations)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# sportsdataverse-py \u003ca href='https://py.sportsdataverse.org'\u003e\u003cimg src='https://raw.githubusercontent.com/sportsdataverse/sportsdataverse-py/master/sdv-py-logo.png' align=\"right\"  width=\"20%\" min-width=\"100px\" /\u003e\u003c/a\u003e\n\u003c!-- badges: start --\u003e\n\n![Lifecycle:experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg?style=for-the-badge\u0026logo=github)\n[![PyPI](https://img.shields.io/pypi/v/sportsdataverse?label=sportsdataverse\u0026logo=python\u0026style=for-the-badge)](https://pypi.org/project/sportsdataverse/)\u003ca href='https://pypi.org/project/sportsdataverse/'\u003e\u003cimg alt=\"PyPI - Down\nloads\" src=\"https://img.shields.io/pypi/dm/sportsdataverse?style=for-the-badge\"\u003e\u003c/a\u003e\n![Contributors](https://img.shields.io/github/contributors/sportsdataverse/sportsdataverse-py?style=for-the-badge)\n[![Twitter\nFollow](https://img.shields.io/twitter/follow/sportsdataverse?color=blue\u0026label=%40sportsdataverse\u0026logo=twitter\u0026style=for-the-badge)](https://twitter.com/sportsdataverse)\n\n\u003c!-- badges: end --\u003e\n\n\nSee [CHANGELOG.md](https://py.sportsdataverse.org/CHANGELOG) for details.\n\nThe goal of [sportsdataverse-py](https://py.sportsdataverse.org) is to provide the community with a python package for working with sports data as a companion to the [cfbfastR](https://cfbfastR.sportsdataverse.org/), [hoopR](https://hoopR.sportsdataverse.org/), and [wehoop](https://wehoop.sportsdataverse.org/) R packages. Beyond data aggregation and tidying ease, one of the multitude of services that [sportsdataverse-py](https://py.sportsdataverse.org) provides is for benchmarking open-source expected points and win probability metrics for American Football.\n\n## Supported leagues and data sources\n\n| League | Module | Surfaces covered |\n|---|---|---|\n| NBA | `sportsdataverse.nba` | ESPN (Site v2 + Web v3 + Core v2) + Fox Sports (Bifrost) |\n| WNBA | `sportsdataverse.wnba` | ESPN |\n| MBB (NCAA M) | `sportsdataverse.mbb` | ESPN + NCAA-only (rankings, recruits) + Fox Sports (Bifrost) |\n| WBB (NCAA W) | `sportsdataverse.wbb` | ESPN + NCAA-only |\n| CFB | `sportsdataverse.cfb` | ESPN + NCAA + football-only (QBR) + Fox Sports (Bifrost) + Yahoo Sports |\n| NFL | `sportsdataverse.nfl` | ESPN + **NFL.com API** (`api.nfl.com` \"Shield\") + **nflverse loaders** (nflreadpy parity) + football-only (QBR) |\n| MLB | `sportsdataverse.mlb` | ESPN + MLB Stats API (`statsapi.mlb.com`) + Baseball Savant / Statcast + Fox Sports (Bifrost) |\n| NHL | `sportsdataverse.nhl` | `api-web.nhle.com/v1/` (game-feed) + NHL EDGE (player tracking) + Stats REST + Records site + Fox Sports (Bifrost) |\n\nEach league exports 150–340 public functions (ESPN wrappers + that league's\nnative-API wrappers + dataset loaders + parsers); ~1,600 in total. **Fox Sports**\nadds `fox_\u003cleague\u003e_*` Bifrost wrappers (pbp / boxscore / odds / roster / stats /\nstandings / leaders) for nba, mbb, cfb, mlb, nhl; **Yahoo Sports** adds\n`yahoo_cfb_*` season-stats / scoreboard wrappers for college football.\n\n## Polars / pandas parser layer\n\nParser-backed wrappers return a tidy polars DataFrame **by default**\n(0.0.54+). Pass `return_parsed=False` for the raw `Dict`, or\n`return_as_pandas=True` for pandas. Wrappers without a registered\nparser return the raw `Dict`.\n\n```python\nfrom sportsdataverse.nba import espn_nba_team_roster\n\ndf  = espn_nba_team_roster(team_id=13)                          # → polars (default)\nraw = espn_nba_team_roster(team_id=13, return_parsed=False)     # → Dict\npdf = espn_nba_team_roster(team_id=13,\n                            return_as_pandas=True)              # → pandas\n```\n\nFor the NHL and MLB sibling-API wrappers, compose the wrapper with\nits parser:\n\n```python\nfrom sportsdataverse.nhl import nhl_web_pbp, parse_nhl_web_pbp\ndf = parse_nhl_web_pbp(nhl_web_pbp(2023030417))                 # 331-row polars frame\n```\n\nSee [py.sportsdataverse.org/docs/architecture/espn-cross-league](https://py.sportsdataverse.org/docs/architecture/espn-cross-league)\nand [py.sportsdataverse.org/docs/parsers/index](https://py.sportsdataverse.org/docs/parsers/index)\nfor the full architecture + parser registry.\n\n## Installation\n\nThe package metadata lives entirely in [`pyproject.toml`](pyproject.toml)\n(PEP 621 `[project]` table). There is no `setup.py` source-of-truth.\n\n### Standard install (pip)\n\n```bash\npip install sportsdataverse\n```\n\nWith optional extras (defined in `[project.optional-dependencies]` in\n`pyproject.toml`):\n\n```bash\npip install \"sportsdataverse[all]\"      # everything below\npip install \"sportsdataverse[models]\"   # extra deps for the EPA / WP model code\npip install \"sportsdataverse[tests]\"    # adds pytest, mypy, ruff, etc.\n```\n\n### Modern install (uv — recommended)\n\n[uv](https://docs.astral.sh/uv/) is the fast, drop-in package manager we use day to day.\n\n```bash\n# Add to a uv-managed project:\nuv add sportsdataverse\n\n# With extras:\nuv add \"sportsdataverse[all]\"\n\n# Or install the latest dev snapshot from GitHub:\nuv add \"sportsdataverse @ git+https://github.com/sportsdataverse/sportsdataverse-py\"\n```\n\n### Development install\n\nFor contributing or running the test suite:\n\n```bash\ngit clone https://github.com/sportsdataverse/sportsdataverse-py.git\ncd sportsdataverse-py\n\n# uv (recommended) — fully resolved editable install with every extra:\nuv pip install -e \".[all]\"\n\n# Plain pip works too if uv isn't available:\npip install -e \".[all]\"\n```\n\n\u003e Note: once we add a PEP 735 `[dependency-groups]` block (currently the\n\u003e repo only ships PEP 621 `[project.optional-dependencies]`),\n\u003e `uv sync --all-extras --all-groups` will become the one-shot dev incantation.\n\u003e Until then, `uv pip install -e \".[all]\"` is the equivalent path.\n\nRun the test suite:\n\n```bash\nuv run pytest                       # offline tests only\nSDV_PY_LIVE_TESTS=1 uv run pytest   # include live API tests (slower; hits ESPN / nflverse)\n```\n\nFor deeper dev-environment detail (lint, mypy, dep-bumping workflow), see\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n### Notes\n\n- **Python target:** 3.9–3.14.\n- **DataFrame engine:** polars 1.x. Most loaders accept `return_as_pandas=True`\n  if you prefer pandas.\n- **NFL caching:** loaders cache to memory by default. Set\n  `SDV_PY_NFL_CACHE=filesystem` for cross-session reuse, or\n  `SDV_PY_NFL_CACHE=off` to disable. See\n  `sportsdataverse.nfl.config.update_config()` for runtime control.\n\n## Examples and tutorials\n\nEvery public function ships a runnable `Example:` block in its docstring\nshowing a quick-start call, common parameter combinations, and a one-line\npipeline next-step. Regenerate the API reference locally with\n`uv run python tools/codegen/generate.py --docs` (then `cd docs \u0026\u0026 yarn build`\nto preview the Docusaurus site) or browse the live docs at\n[py.sportsdataverse.org](https://py.sportsdataverse.org).\n\nFor longer-form walkthroughs, see the intro/intermediate Jupyter notebooks\nunder [`examples/notebooks/`](examples/notebooks):\n\n| Notebook | Covers |\n|---|---|\n| `01_quickstart.ipynb` | Cross-sport intro — package layout, polars vs pandas, the `download()` retry layer |\n| `02_cfb_intro.ipynb` | College football PBP, schedule, teams, `espn_cfb_play_participants` |\n| `03_nfl_intro.ipynb` | NFL — nflreadpy parity surface, caching layer, current-season helpers |\n| `04_nba_intro.ipynb` | NBA — PBP, schedule, teams, game rosters, shot distribution |\n| `05_wbb_wnba_intro.ipynb` | Women's basketball — NCAA + WNBA parallels, multi-table stats |\n| `06_mbb_intro.ipynb` | Men's college basketball — PBP, schedule, conference standings |\n| `07_nhl_intro.ipynb` | NHL — PBP, schedule, teams, shot-event filter |\n\n## Companion packages\n\n`sportsdataverse-py` is one corner of the broader [SportsDataverse](https://www.sportsdataverse.org)\necosystem. The R sister packages cover the same data sources with deeper\nsport-specific coverage:\n\n- [wehoop](https://wehoop.sportsdataverse.org) — women's basketball (WNBA + NCAA)\n- [hoopR](https://hoopR.sportsdataverse.org) — men's basketball (NBA + NCAA)\n- [cfbfastR](https://cfbfastR.sportsdataverse.org) — college football\n- [baseballr](https://baseballr.sportsdataverse.org) — baseball (MLB + MiLB + NCAA)\n- [fastRhockey](https://fastRhockey.sportsdataverse.org) — hockey (NHL + WHL)\n\nThe NFL submodule is a near drop-in replacement for [nflreadpy](https://github.com/nflverse/nflreadpy);\nthe broader [nflverse](https://nflverse.nflverse.com) ecosystem is the\nupstream data source for many of those loaders.\n\n# **Our Authors**\n\n-   [Saiem Gilani](https://twitter.com/saiemgilani)\n\u003ca href=\"https://twitter.com/saiemgilani\" target=\"blank\"\u003e\u003cimg src=\"https://img.shields.io/twitter/follow/saiemgilani?color=blue\u0026label=%40saiemgilani\u0026logo=twitter\u0026style=for-the-badge\" alt=\"@saiemgilani\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/saiemgilani\" target=\"blank\"\u003e\u003cimg src=\"https://img.shields.io/github/followers/saiemgilani?color=eee\u0026logo=Github\u0026style=for-the-badge\" alt=\"@saiemgilani\" /\u003e\u003c/a\u003e\n\n\n## **Citations**\n\nTo cite the [**`sportsdataverse-py`**](https://py.sportsdataverse.org) Python package in publications, use:\n\nBibTex Citation\n\n```bibtex\n@misc{gilani_sdvpy_2021,\n  author = {Gilani, Saiem},\n  title = {sportsdataverse-py: The SportsDataverse's Python Package for Sports Data.},\n  url = {https://py.sportsdataverse.org},\n  season = {2021}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsportsdataverse%2Fsportsdataverse-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsportsdataverse%2Fsportsdataverse-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsportsdataverse%2Fsportsdataverse-py/lists"}