Skip to content

Make the stats endpoints easier to use #326

Description

@Mattsface

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:

  1. 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.

  2. 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'.

  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions