bigleague 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. bigleague-0.1.0/LICENSE +21 -0
  2. bigleague-0.1.0/PKG-INFO +224 -0
  3. bigleague-0.1.0/README.md +180 -0
  4. bigleague-0.1.0/bigleague/__init__.py +171 -0
  5. bigleague-0.1.0/bigleague/abs.py +177 -0
  6. bigleague-0.1.0/bigleague/cache.py +135 -0
  7. bigleague-0.1.0/bigleague/fangraphs.py +549 -0
  8. bigleague-0.1.0/bigleague/http.py +120 -0
  9. bigleague-0.1.0/bigleague/mlb.py +474 -0
  10. bigleague-0.1.0/bigleague/models.py +141 -0
  11. bigleague-0.1.0/bigleague/players.py +159 -0
  12. bigleague-0.1.0/bigleague/plots.py +450 -0
  13. bigleague-0.1.0/bigleague/py.typed +0 -0
  14. bigleague-0.1.0/bigleague/savant.py +359 -0
  15. bigleague-0.1.0/bigleague/schema.py +56 -0
  16. bigleague-0.1.0/bigleague/stadiums.py +239 -0
  17. bigleague-0.1.0/bigleague/stats.py +443 -0
  18. bigleague-0.1.0/bigleague.egg-info/PKG-INFO +224 -0
  19. bigleague-0.1.0/bigleague.egg-info/SOURCES.txt +32 -0
  20. bigleague-0.1.0/bigleague.egg-info/dependency_links.txt +1 -0
  21. bigleague-0.1.0/bigleague.egg-info/requires.txt +17 -0
  22. bigleague-0.1.0/bigleague.egg-info/top_level.txt +1 -0
  23. bigleague-0.1.0/pyproject.toml +143 -0
  24. bigleague-0.1.0/setup.cfg +4 -0
  25. bigleague-0.1.0/tests/test_abs.py +163 -0
  26. bigleague-0.1.0/tests/test_cache.py +217 -0
  27. bigleague-0.1.0/tests/test_fangraphs.py +463 -0
  28. bigleague-0.1.0/tests/test_mlb.py +355 -0
  29. bigleague-0.1.0/tests/test_models.py +67 -0
  30. bigleague-0.1.0/tests/test_players.py +191 -0
  31. bigleague-0.1.0/tests/test_plots.py +148 -0
  32. bigleague-0.1.0/tests/test_savant.py +328 -0
  33. bigleague-0.1.0/tests/test_stadiums.py +77 -0
  34. bigleague-0.1.0/tests/test_stats.py +268 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jonathon Klobucar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,224 @@
1
+ Metadata-Version: 2.4
2
+ Name: bigleague
3
+ Version: 0.1.0
4
+ Summary: Async polars-native baseball data and plotting library
5
+ Author: Jonathon Klobucar
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/klobucar/bigleague
8
+ Project-URL: Repository, https://github.com/klobucar/bigleague
9
+ Project-URL: Issues, https://github.com/klobucar/bigleague/issues
10
+ Project-URL: Changelog, https://github.com/klobucar/bigleague/blob/main/CHANGELOG.md
11
+ Keywords: baseball,mlb,statcast,fangraphs,sabermetrics,polars,matplotlib,asyncio
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Programming Language :: Python :: 3.15
22
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
23
+ Classifier: Topic :: Scientific/Engineering :: Visualization
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.12
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: polars>=0.20
29
+ Requires-Dist: httpx>=0.27
30
+ Requires-Dist: curl_cffi>=0.7
31
+ Requires-Dist: matplotlib>=3.8
32
+ Requires-Dist: numpy>=1.26
33
+ Provides-Extra: bloom
34
+ Requires-Dist: bouquet-bloom>=0.1.0; extra == "bloom"
35
+ Provides-Extra: dev
36
+ Requires-Dist: pytest>=8; extra == "dev"
37
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
38
+ Requires-Dist: pytest-recording>=0.13; extra == "dev"
39
+ Requires-Dist: respx>=0.21; extra == "dev"
40
+ Requires-Dist: vcrpy>=6; extra == "dev"
41
+ Requires-Dist: ruff>=0.7; extra == "dev"
42
+ Requires-Dist: ty>=0.0.1; extra == "dev"
43
+ Dynamic: license-file
44
+
45
+ <p align="center">
46
+ <img src="https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/banner.jpg" alt="bigleague: baseball data and plots. An anime girl in a baseball jersey points at a glowing strike-zone heatmap." width="100%">
47
+ </p>
48
+
49
+ # bigleague
50
+
51
+ [![PyPI](https://img.shields.io/pypi/v/bigleague)](https://pypi.org/project/bigleague/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/bigleague)](https://pypi.org/project/bigleague/)
53
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
54
+
55
+ Fetch Statcast pitches, Baseball Savant leaderboards, FanGraphs stats, and MLB
56
+ schedules and rosters from Python. Requests use `asyncio`, tabular results use
57
+ [Polars](https://pola.rs), and plots are returned as PNG bytes.
58
+
59
+ ## Quick start
60
+
61
+ Install with `pip install bigleague` or `uv add bigleague`. Requires Python 3.12+.
62
+
63
+ This saves a strike-zone plot of the pitches Shohei Ohtani saw in April 2025.
64
+
65
+ ```python
66
+ import asyncio
67
+ from datetime import date
68
+ from pathlib import Path
69
+
70
+ import bigleague as bl
71
+
72
+
73
+ async def main() -> None:
74
+ ohtani = 660271 # MLBAM ID
75
+ pitches = await bl.statcast_batter(ohtani, date(2025, 4, 1), date(2025, 4, 30))
76
+ png = bl.strike_zone(pitches, "Shohei Ohtani, April 2025")
77
+ Path("ohtani-april.png").write_bytes(png)
78
+
79
+
80
+ asyncio.run(main())
81
+ ```
82
+
83
+ ## Gallery
84
+
85
+ | `strike_zone` | `hot_zones` |
86
+ | :---: | :---: |
87
+ | ![Strike zone plot of Ohtani's April 2025 pitches, colored by pitch type](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/strike_zone.png) | ![Hot zone heatmap of Ohtani's 2025 batting average by zone](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/hot_zones.png) |
88
+ | `spray_chart` | `stadium_outline` |
89
+ | ![Spray chart of Ohtani's 2025 batted balls at Dodger Stadium](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/spray_chart.png) | ![Dodger Stadium outline](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/stadium_outline.png) |
90
+
91
+ The strike-zone plot covers April 2025. The hot zones and spray chart use
92
+ Ohtani's season data. Passing `stadium_key="dodgers"` to `spray_chart` selects
93
+ batted balls at Dodger Stadium.
94
+
95
+ ## Fetching data
96
+
97
+ ### Statcast
98
+
99
+ ```python
100
+ ohtani = await bl.resolve_id("Shohei", "Ohtani") # 660271
101
+ if ohtani is not None:
102
+ pitches = await bl.statcast_season(ohtani, 2025, "batter")
103
+ print(bl.hot_cold_batter(pitches))
104
+
105
+ yankees = await bl.statcast(date(2025, 4, 1), date(2025, 4, 7), team="NYY")
106
+ ```
107
+
108
+ `resolve_id` looks up an MLBAM ID in the Chadwick Bureau register. Use
109
+ `lookup("Ohtani", "Shohei")` for the register rows.
110
+
111
+ `statcast_batter` and `statcast_pitcher` take a date range. `statcast` takes
112
+ an optional team and splits the range into requests of up to seven days.
113
+ bigleague allows up to five concurrent Savant requests. See
114
+ `STATCAST_SCHEMA` for the pitch columns and their Polars types.
115
+
116
+ Savant leaderboards include sprint speed, expected stats, pitch arsenals,
117
+ and pitch movement. Automated Ball-Strike challenge data is available under
118
+ `bl.abs`.
119
+
120
+ ```python
121
+ speed = await bl.sprint_speed(2025)
122
+ challenges = await bl.abs.team_summary("NYY", 2025)
123
+ ```
124
+
125
+ ### FanGraphs
126
+
127
+ ```python
128
+ ohtani = await bl.player_stats("Shohei", "Ohtani", 2025)
129
+ war_leaders = await bl.top_leaderboard("WAR", 2025, n=10)
130
+ batting = await bl.batting_stats(2024, 2025, qual=100)
131
+ ```
132
+
133
+ `batting_stats`, `pitching_stats`, and `fielding_stats` return Polars
134
+ DataFrames. If Cloudflare blocks a request, bigleague raises
135
+ `FangraphsBlockedError`.
136
+
137
+ ### MLB Stats API
138
+
139
+ ```python
140
+ season = await bl.schedule("NYY", 2025)
141
+ last_five = [game for game in season if game["status"] in {"W", "L"}][-5:]
142
+ for game in last_five:
143
+ print(game["date"], game["opponent"], game["score"], game["record"])
144
+ ```
145
+
146
+ `schedule` defaults to the regular season. It returns games in play order
147
+ with the team's running win-loss record. Status is `W` or `L` for final
148
+ games, `P` for postponed or suspended games, and `S` for scheduled games.
149
+
150
+ Use team abbreviations such as `NYY` or `LAD` with `live_scores`,
151
+ `next_game`, `recent_results`, `roster`, `injuries`, and `transactions`.
152
+ Use `standings(year)` for division standings. Player lists are available
153
+ through `bl.mlb.players` and
154
+ `bl.mlb.players_multi_season`.
155
+
156
+ ## Cache
157
+
158
+ Historical Statcast data is cached as Parquet under `~/.bigleague/cache`.
159
+ Chunks ending today or later are fetched each time. The Chadwick player
160
+ register uses the same directory.
161
+
162
+ Set `BIGLEAGUE_CACHE_DIR` to move the cache or `BIGLEAGUE_NO_CACHE=1` to skip
163
+ cache reads and writes for a run. Statcast entries stay on disk until you
164
+ remove them. Use `bl.cache.size()` to check their size and `bl.cache.clear()`
165
+ to remove them.
166
+
167
+ The optional `bigleague[bloom]` extra skips disk lookups for keys the cache
168
+ doesn't contain.
169
+
170
+ ## Benchmarks
171
+
172
+ These runs use Ohtani's 2025 Statcast data. The month is April, and the season
173
+ run covers April through September. Each library ran in its own process.
174
+ For the warm run, bigleague read from its Parquet cache while the other two
175
+ fetched the data again. The `hotzones` run calculates batting average by zone.
176
+
177
+ | lib | scenario | rows | frame | peak heap | peak RSS | wall |
178
+ | -------------- | ---------- | ----: | -----: | ---------: | --------: | ----: |
179
+ | bigleague | month cold | 426 | 194 KB | 52 MB | 161 MB | 1.35s |
180
+ | pybaseball | month cold | 426 | 433 KB | 85 MB | 260 MB | 2.69s |
181
+ | pandas+pyarrow | month cold | 426 | 375 KB | 48 MB | 167 MB | 1.27s |
182
+ | bigleague | month warm | 426 | 193 KB | 48 MB | 151 MB | 1.20s |
183
+ | pybaseball | month warm | 426 | 433 KB | 85 MB | 260 MB | 2.60s |
184
+ | pandas+pyarrow | month warm | 426 | 375 KB | 48 MB | 166 MB | 1.27s |
185
+ | bigleague | season | 2859 | 1.3 MB | 55 MB | 168 MB | 1.40s |
186
+ | pybaseball | season | 2850 | 2.8 MB | 96 MB | 281 MB | 2.71s |
187
+ | pandas+pyarrow | season | 2859 | 2.5 MB | 51 MB | 176 MB | 1.29s |
188
+ | bigleague | hotzones | 426 | 193 KB | 48 MB | 158 MB | 1.23s |
189
+ | pybaseball | hotzones | 426 | 433 KB | 99 MB | 290 MB | 2.93s |
190
+ | pandas+pyarrow | hotzones | 426 | 375 KB | 80 MB | 250 MB | 2.21s |
191
+
192
+ The benchmark requires network access.
193
+
194
+ ```bash
195
+ uv pip install pybaseball pandas pyarrow
196
+ uv run python bench/compare_pybaseball.py
197
+ ```
198
+
199
+ ## Development
200
+
201
+ ```bash
202
+ git clone https://github.com/klobucar/bigleague
203
+ cd bigleague
204
+ uv sync --extra dev
205
+ uv run pytest
206
+ uv run ruff check . && uv run ruff format --check .
207
+ uv run ty check
208
+ ```
209
+
210
+ The tests mock HTTP requests. Add `--extra bloom` to `uv sync` to run the
211
+ Bloom filter tests.
212
+
213
+ Regenerate the gallery from the repository root with
214
+ `uv run python -m docs.make_gallery`. It fetches data from Baseball Savant
215
+ and writes the PNGs to `docs/img/`.
216
+
217
+ ## Used by
218
+
219
+ [harry-bot](https://github.com/klobucar/harry-bot), a Discord baseball bot.
220
+
221
+ ## License
222
+
223
+ [MIT](LICENSE). bigleague is an independent project. Check the data
224
+ providers' terms before commercial use.
@@ -0,0 +1,180 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/banner.jpg" alt="bigleague: baseball data and plots. An anime girl in a baseball jersey points at a glowing strike-zone heatmap." width="100%">
3
+ </p>
4
+
5
+ # bigleague
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/bigleague)](https://pypi.org/project/bigleague/)
8
+ [![Python](https://img.shields.io/pypi/pyversions/bigleague)](https://pypi.org/project/bigleague/)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10
+
11
+ Fetch Statcast pitches, Baseball Savant leaderboards, FanGraphs stats, and MLB
12
+ schedules and rosters from Python. Requests use `asyncio`, tabular results use
13
+ [Polars](https://pola.rs), and plots are returned as PNG bytes.
14
+
15
+ ## Quick start
16
+
17
+ Install with `pip install bigleague` or `uv add bigleague`. Requires Python 3.12+.
18
+
19
+ This saves a strike-zone plot of the pitches Shohei Ohtani saw in April 2025.
20
+
21
+ ```python
22
+ import asyncio
23
+ from datetime import date
24
+ from pathlib import Path
25
+
26
+ import bigleague as bl
27
+
28
+
29
+ async def main() -> None:
30
+ ohtani = 660271 # MLBAM ID
31
+ pitches = await bl.statcast_batter(ohtani, date(2025, 4, 1), date(2025, 4, 30))
32
+ png = bl.strike_zone(pitches, "Shohei Ohtani, April 2025")
33
+ Path("ohtani-april.png").write_bytes(png)
34
+
35
+
36
+ asyncio.run(main())
37
+ ```
38
+
39
+ ## Gallery
40
+
41
+ | `strike_zone` | `hot_zones` |
42
+ | :---: | :---: |
43
+ | ![Strike zone plot of Ohtani's April 2025 pitches, colored by pitch type](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/strike_zone.png) | ![Hot zone heatmap of Ohtani's 2025 batting average by zone](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/hot_zones.png) |
44
+ | `spray_chart` | `stadium_outline` |
45
+ | ![Spray chart of Ohtani's 2025 batted balls at Dodger Stadium](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/spray_chart.png) | ![Dodger Stadium outline](https://raw.githubusercontent.com/klobucar/bigleague/main/docs/img/stadium_outline.png) |
46
+
47
+ The strike-zone plot covers April 2025. The hot zones and spray chart use
48
+ Ohtani's season data. Passing `stadium_key="dodgers"` to `spray_chart` selects
49
+ batted balls at Dodger Stadium.
50
+
51
+ ## Fetching data
52
+
53
+ ### Statcast
54
+
55
+ ```python
56
+ ohtani = await bl.resolve_id("Shohei", "Ohtani") # 660271
57
+ if ohtani is not None:
58
+ pitches = await bl.statcast_season(ohtani, 2025, "batter")
59
+ print(bl.hot_cold_batter(pitches))
60
+
61
+ yankees = await bl.statcast(date(2025, 4, 1), date(2025, 4, 7), team="NYY")
62
+ ```
63
+
64
+ `resolve_id` looks up an MLBAM ID in the Chadwick Bureau register. Use
65
+ `lookup("Ohtani", "Shohei")` for the register rows.
66
+
67
+ `statcast_batter` and `statcast_pitcher` take a date range. `statcast` takes
68
+ an optional team and splits the range into requests of up to seven days.
69
+ bigleague allows up to five concurrent Savant requests. See
70
+ `STATCAST_SCHEMA` for the pitch columns and their Polars types.
71
+
72
+ Savant leaderboards include sprint speed, expected stats, pitch arsenals,
73
+ and pitch movement. Automated Ball-Strike challenge data is available under
74
+ `bl.abs`.
75
+
76
+ ```python
77
+ speed = await bl.sprint_speed(2025)
78
+ challenges = await bl.abs.team_summary("NYY", 2025)
79
+ ```
80
+
81
+ ### FanGraphs
82
+
83
+ ```python
84
+ ohtani = await bl.player_stats("Shohei", "Ohtani", 2025)
85
+ war_leaders = await bl.top_leaderboard("WAR", 2025, n=10)
86
+ batting = await bl.batting_stats(2024, 2025, qual=100)
87
+ ```
88
+
89
+ `batting_stats`, `pitching_stats`, and `fielding_stats` return Polars
90
+ DataFrames. If Cloudflare blocks a request, bigleague raises
91
+ `FangraphsBlockedError`.
92
+
93
+ ### MLB Stats API
94
+
95
+ ```python
96
+ season = await bl.schedule("NYY", 2025)
97
+ last_five = [game for game in season if game["status"] in {"W", "L"}][-5:]
98
+ for game in last_five:
99
+ print(game["date"], game["opponent"], game["score"], game["record"])
100
+ ```
101
+
102
+ `schedule` defaults to the regular season. It returns games in play order
103
+ with the team's running win-loss record. Status is `W` or `L` for final
104
+ games, `P` for postponed or suspended games, and `S` for scheduled games.
105
+
106
+ Use team abbreviations such as `NYY` or `LAD` with `live_scores`,
107
+ `next_game`, `recent_results`, `roster`, `injuries`, and `transactions`.
108
+ Use `standings(year)` for division standings. Player lists are available
109
+ through `bl.mlb.players` and
110
+ `bl.mlb.players_multi_season`.
111
+
112
+ ## Cache
113
+
114
+ Historical Statcast data is cached as Parquet under `~/.bigleague/cache`.
115
+ Chunks ending today or later are fetched each time. The Chadwick player
116
+ register uses the same directory.
117
+
118
+ Set `BIGLEAGUE_CACHE_DIR` to move the cache or `BIGLEAGUE_NO_CACHE=1` to skip
119
+ cache reads and writes for a run. Statcast entries stay on disk until you
120
+ remove them. Use `bl.cache.size()` to check their size and `bl.cache.clear()`
121
+ to remove them.
122
+
123
+ The optional `bigleague[bloom]` extra skips disk lookups for keys the cache
124
+ doesn't contain.
125
+
126
+ ## Benchmarks
127
+
128
+ These runs use Ohtani's 2025 Statcast data. The month is April, and the season
129
+ run covers April through September. Each library ran in its own process.
130
+ For the warm run, bigleague read from its Parquet cache while the other two
131
+ fetched the data again. The `hotzones` run calculates batting average by zone.
132
+
133
+ | lib | scenario | rows | frame | peak heap | peak RSS | wall |
134
+ | -------------- | ---------- | ----: | -----: | ---------: | --------: | ----: |
135
+ | bigleague | month cold | 426 | 194 KB | 52 MB | 161 MB | 1.35s |
136
+ | pybaseball | month cold | 426 | 433 KB | 85 MB | 260 MB | 2.69s |
137
+ | pandas+pyarrow | month cold | 426 | 375 KB | 48 MB | 167 MB | 1.27s |
138
+ | bigleague | month warm | 426 | 193 KB | 48 MB | 151 MB | 1.20s |
139
+ | pybaseball | month warm | 426 | 433 KB | 85 MB | 260 MB | 2.60s |
140
+ | pandas+pyarrow | month warm | 426 | 375 KB | 48 MB | 166 MB | 1.27s |
141
+ | bigleague | season | 2859 | 1.3 MB | 55 MB | 168 MB | 1.40s |
142
+ | pybaseball | season | 2850 | 2.8 MB | 96 MB | 281 MB | 2.71s |
143
+ | pandas+pyarrow | season | 2859 | 2.5 MB | 51 MB | 176 MB | 1.29s |
144
+ | bigleague | hotzones | 426 | 193 KB | 48 MB | 158 MB | 1.23s |
145
+ | pybaseball | hotzones | 426 | 433 KB | 99 MB | 290 MB | 2.93s |
146
+ | pandas+pyarrow | hotzones | 426 | 375 KB | 80 MB | 250 MB | 2.21s |
147
+
148
+ The benchmark requires network access.
149
+
150
+ ```bash
151
+ uv pip install pybaseball pandas pyarrow
152
+ uv run python bench/compare_pybaseball.py
153
+ ```
154
+
155
+ ## Development
156
+
157
+ ```bash
158
+ git clone https://github.com/klobucar/bigleague
159
+ cd bigleague
160
+ uv sync --extra dev
161
+ uv run pytest
162
+ uv run ruff check . && uv run ruff format --check .
163
+ uv run ty check
164
+ ```
165
+
166
+ The tests mock HTTP requests. Add `--extra bloom` to `uv sync` to run the
167
+ Bloom filter tests.
168
+
169
+ Regenerate the gallery from the repository root with
170
+ `uv run python -m docs.make_gallery`. It fetches data from Baseball Savant
171
+ and writes the PNGs to `docs/img/`.
172
+
173
+ ## Used by
174
+
175
+ [harry-bot](https://github.com/klobucar/harry-bot), a Discord baseball bot.
176
+
177
+ ## License
178
+
179
+ [MIT](LICENSE). bigleague is an independent project. Check the data
180
+ providers' terms before commercial use.
@@ -0,0 +1,171 @@
1
+ """bigleague — async polars-native baseball data and plotting.
2
+
3
+ Public API surface. Submodules remain importable directly
4
+ (`bigleague.savant`, etc.) for code that prefers namespacing.
5
+
6
+ `mlb.players()` and `mlb.players_multi_season()` are intentionally NOT
7
+ re-exported at the top level — they would collide with the
8
+ `bigleague.players` submodule. Use `bigleague.mlb.players(...)` instead.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from bigleague import abs
14
+ from bigleague.cache import StatcastCache, cache
15
+ from bigleague.fangraphs import (
16
+ FangraphsBlockedError,
17
+ batting_stats,
18
+ batting_stats_range,
19
+ career_stats,
20
+ fielding_stats,
21
+ leaderboard,
22
+ pitching_stats,
23
+ pitching_stats_range,
24
+ player_stats,
25
+ player_stats_for_year,
26
+ playoff_odds,
27
+ team_batting,
28
+ team_pitching,
29
+ top_leaderboard,
30
+ )
31
+ from bigleague.mlb import (
32
+ POS_NAMES,
33
+ TEAM_IDS,
34
+ injuries,
35
+ live_scores,
36
+ next_game,
37
+ recent_results,
38
+ roster,
39
+ schedule,
40
+ standings,
41
+ transactions,
42
+ )
43
+ from bigleague.models import StatcastPitch
44
+ from bigleague.players import lookup, mlb_years, resolve_id, reverse_lookup
45
+ from bigleague.plots import (
46
+ batter_zone,
47
+ hot_zones,
48
+ matchup_zone,
49
+ spray_chart,
50
+ stadium_outline,
51
+ strike_zone,
52
+ )
53
+ from bigleague.savant import (
54
+ batter_exit_velo,
55
+ batter_expected_stats,
56
+ batter_percentile_ranks,
57
+ batter_pitch_arsenal,
58
+ pitcher_exit_velo,
59
+ pitcher_expected_stats,
60
+ pitcher_percentile_ranks,
61
+ pitcher_pitch_arsenal,
62
+ pitcher_pitch_movement,
63
+ running_splits,
64
+ sprint_speed,
65
+ statcast,
66
+ statcast_batter,
67
+ statcast_pitcher,
68
+ statcast_season,
69
+ )
70
+ from bigleague.schema import STATCAST_SCHEMA
71
+ from bigleague.stadiums import (
72
+ STADIUM_ALIASES,
73
+ STADIUM_DATA,
74
+ STADIUM_TO_TEAM_CODE,
75
+ known_stadiums,
76
+ )
77
+ from bigleague.stadiums import metadata as stadium_metadata
78
+ from bigleague.stadiums import normalize as normalize_stadium
79
+ from bigleague.stadiums import team_code as stadium_team_code
80
+ from bigleague.stats import (
81
+ AB_EVENTS,
82
+ HIT_EVENTS,
83
+ aggregate_career,
84
+ hot_cold_batter,
85
+ hot_cold_pitcher,
86
+ hot_zones_ab_counts,
87
+ hot_zones_grid,
88
+ matchup_stats,
89
+ parse_exit_velo,
90
+ parse_expected_stats,
91
+ parse_percentile_ranks,
92
+ parse_pitch_arsenal,
93
+ season_range,
94
+ )
95
+
96
+ __all__ = [
97
+ "AB_EVENTS",
98
+ "HIT_EVENTS",
99
+ "POS_NAMES",
100
+ "STADIUM_ALIASES",
101
+ "STADIUM_DATA",
102
+ "STADIUM_TO_TEAM_CODE",
103
+ "STATCAST_SCHEMA",
104
+ "TEAM_IDS",
105
+ "FangraphsBlockedError",
106
+ "StatcastCache",
107
+ "StatcastPitch",
108
+ "abs",
109
+ "aggregate_career",
110
+ "batter_exit_velo",
111
+ "batter_expected_stats",
112
+ "batter_percentile_ranks",
113
+ "batter_pitch_arsenal",
114
+ "batter_zone",
115
+ "batting_stats",
116
+ "batting_stats_range",
117
+ "cache",
118
+ "career_stats",
119
+ "fielding_stats",
120
+ "hot_cold_batter",
121
+ "hot_cold_pitcher",
122
+ "hot_zones",
123
+ "hot_zones_ab_counts",
124
+ "hot_zones_grid",
125
+ "injuries",
126
+ "known_stadiums",
127
+ "leaderboard",
128
+ "live_scores",
129
+ "lookup",
130
+ "matchup_stats",
131
+ "matchup_zone",
132
+ "mlb_years",
133
+ "next_game",
134
+ "normalize_stadium",
135
+ "parse_exit_velo",
136
+ "parse_expected_stats",
137
+ "parse_percentile_ranks",
138
+ "parse_pitch_arsenal",
139
+ "pitcher_exit_velo",
140
+ "pitcher_expected_stats",
141
+ "pitcher_percentile_ranks",
142
+ "pitcher_pitch_arsenal",
143
+ "pitcher_pitch_movement",
144
+ "pitching_stats",
145
+ "pitching_stats_range",
146
+ "player_stats",
147
+ "player_stats_for_year",
148
+ "playoff_odds",
149
+ "recent_results",
150
+ "resolve_id",
151
+ "reverse_lookup",
152
+ "roster",
153
+ "running_splits", # deprecated alias for sprint_speed
154
+ "schedule",
155
+ "season_range",
156
+ "spray_chart",
157
+ "sprint_speed",
158
+ "stadium_metadata",
159
+ "stadium_outline",
160
+ "stadium_team_code",
161
+ "standings",
162
+ "statcast",
163
+ "statcast_batter",
164
+ "statcast_pitcher",
165
+ "statcast_season",
166
+ "strike_zone",
167
+ "team_batting",
168
+ "team_pitching",
169
+ "top_leaderboard",
170
+ "transactions",
171
+ ]