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.
- bigleague-0.1.0/LICENSE +21 -0
- bigleague-0.1.0/PKG-INFO +224 -0
- bigleague-0.1.0/README.md +180 -0
- bigleague-0.1.0/bigleague/__init__.py +171 -0
- bigleague-0.1.0/bigleague/abs.py +177 -0
- bigleague-0.1.0/bigleague/cache.py +135 -0
- bigleague-0.1.0/bigleague/fangraphs.py +549 -0
- bigleague-0.1.0/bigleague/http.py +120 -0
- bigleague-0.1.0/bigleague/mlb.py +474 -0
- bigleague-0.1.0/bigleague/models.py +141 -0
- bigleague-0.1.0/bigleague/players.py +159 -0
- bigleague-0.1.0/bigleague/plots.py +450 -0
- bigleague-0.1.0/bigleague/py.typed +0 -0
- bigleague-0.1.0/bigleague/savant.py +359 -0
- bigleague-0.1.0/bigleague/schema.py +56 -0
- bigleague-0.1.0/bigleague/stadiums.py +239 -0
- bigleague-0.1.0/bigleague/stats.py +443 -0
- bigleague-0.1.0/bigleague.egg-info/PKG-INFO +224 -0
- bigleague-0.1.0/bigleague.egg-info/SOURCES.txt +32 -0
- bigleague-0.1.0/bigleague.egg-info/dependency_links.txt +1 -0
- bigleague-0.1.0/bigleague.egg-info/requires.txt +17 -0
- bigleague-0.1.0/bigleague.egg-info/top_level.txt +1 -0
- bigleague-0.1.0/pyproject.toml +143 -0
- bigleague-0.1.0/setup.cfg +4 -0
- bigleague-0.1.0/tests/test_abs.py +163 -0
- bigleague-0.1.0/tests/test_cache.py +217 -0
- bigleague-0.1.0/tests/test_fangraphs.py +463 -0
- bigleague-0.1.0/tests/test_mlb.py +355 -0
- bigleague-0.1.0/tests/test_models.py +67 -0
- bigleague-0.1.0/tests/test_players.py +191 -0
- bigleague-0.1.0/tests/test_plots.py +148 -0
- bigleague-0.1.0/tests/test_savant.py +328 -0
- bigleague-0.1.0/tests/test_stadiums.py +77 -0
- bigleague-0.1.0/tests/test_stats.py +268 -0
bigleague-0.1.0/LICENSE
ADDED
|
@@ -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.
|
bigleague-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/bigleague/)
|
|
52
|
+
[](https://pypi.org/project/bigleague/)
|
|
53
|
+
[](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
|
+
|  |  |
|
|
88
|
+
| `spray_chart` | `stadium_outline` |
|
|
89
|
+
|  |  |
|
|
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
|
+
[](https://pypi.org/project/bigleague/)
|
|
8
|
+
[](https://pypi.org/project/bigleague/)
|
|
9
|
+
[](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
|
+
|  |  |
|
|
44
|
+
| `spray_chart` | `stadium_outline` |
|
|
45
|
+
|  |  |
|
|
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
|
+
]
|