The four stats methods — get_stats, get_player_stats, get_team_stats, and get_players_stats_for_game — are easy to call wrong and hard to debug when you do.
The main problem
Everything that can go wrong returns the same thing: an empty dict.
- Misspell a stat group (
hiting) → {}
- Misspell a stat type (
sesaon) → {}
- Ask for a player who genuinely has no stats →
{}
- Get a 404 →
{}
So when you get nothing back, you have no idea whether you made a typo or the answer is really "no stats." Nothing warns you either way.
The other problem
Nothing in the package tells you what the valid values are. The docstrings point at two URLs and that's it, so you have to go read a web page to find out that "hitting" is a group and "season" is a type. Autocomplete can't help you.
Ideas
Rough, in order of how much they'd help:
-
Ship the valid values as constants. Something like StatGroup.HITTING and StatType.SEASON, so typos get caught while you're typing instead of showing up as an empty result later.
-
Return something friendlier than a bare dict. A dict subclass would still behave exactly like a dict for anyone who already has working code, but it could have a useful repr and could say "no 'hiting' group — this response has: hitting, pitching" instead of just raising KeyError: 'hiting'.
-
Warn on values we don't recognize. The package already has MlbHttpCompatibilityWarning, so there's a pattern for this. Less certain about this one — warnings are more intrusive than the first two.
The first two are additive and wouldn't break anyone's existing code.
Context
Split out of #305 while porting the stats methods to AsyncMlb. That port was deliberately kept at strict parity with the sync client, so none of this was done there — the behavior above is the same on both clients today.
The four stats methods —
get_stats,get_player_stats,get_team_stats, andget_players_stats_for_game— are easy to call wrong and hard to debug when you do.The main problem
Everything that can go wrong returns the same thing: an empty dict.
hiting) →{}sesaon) →{}{}{}So when you get nothing back, you have no idea whether you made a typo or the answer is really "no stats." Nothing warns you either way.
The other problem
Nothing in the package tells you what the valid values are. The docstrings point at two URLs and that's it, so you have to go read a web page to find out that "hitting" is a group and "season" is a type. Autocomplete can't help you.
Ideas
Rough, in order of how much they'd help:
Ship the valid values as constants. Something like
StatGroup.HITTINGandStatType.SEASON, so typos get caught while you're typing instead of showing up as an empty result later.Return something friendlier than a bare dict. A
dictsubclass would still behave exactly like a dict for anyone who already has working code, but it could have a usefulreprand could say "no 'hiting' group — this response has: hitting, pitching" instead of just raisingKeyError: 'hiting'.Warn on values we don't recognize. The package already has
MlbHttpCompatibilityWarning, so there's a pattern for this. Less certain about this one — warnings are more intrusive than the first two.The first two are additive and wouldn't break anyone's existing code.
Context
Split out of #305 while porting the stats methods to
AsyncMlb. That port was deliberately kept at strict parity with the sync client, so none of this was done there — the behavior above is the same on both clients today.