baseballcommand 0.1.0__py3-none-any.whl

baseballcommand/commands/cache.py

@@ -0,0 +1,65 @@
+"""``base cache`` — inspect or clear the on-disk response cache."""
+
+from __future__ import annotations
+
+from .. import output
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "cache",
+        help="show or clear the cached API responses",
+        description=(
+            "BaseballCommand caches API responses on disk so repeated commands "
+            "are fast and the free public API is not hammered. This shows what "
+            "is cached and can throw it away."
+        ),
+    )
+    parser.add_argument(
+        "action",
+        nargs="?",
+        choices=["info", "clear"],
+        default="info",
+        help="'info' shows size and location, 'clear' deletes every entry",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    cache = ctx.client.cache
+
+    if args.action == "clear":
+        removed = cache.clear()
+        if ctx.json:
+            output.emit_json({"cleared": removed, "path": str(cache.directory)})
+        else:
+            print(f"Cleared {removed} cached response{'s' if removed != 1 else ''}.")
+        return 0
+
+    info = cache.stats()
+    if ctx.json:
+        output.emit_json(info)
+        return 0
+
+    print(output.heading("Response cache"))
+    output.blank()
+    print(
+        output.key_values(
+            [
+                ("Location", info["path"]),
+                ("Entries", info["entries"]),
+                ("Size", _human_bytes(info["bytes"])),
+                ("Enabled", "yes" if cache.enabled else "no (--no-cache)"),
+            ]
+        )
+    )
+    return 0
+
+
+def _human_bytes(count: int) -> str:
+    size = float(count)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} GB"

baseballcommand/commands/compare.py

@@ -0,0 +1,149 @@
+"""``base compare`` — put two or more players' stat lines side by side."""
+
+from __future__ import annotations
+
+from .. import output
+from .. import stats as statcols
+from ..api import current_season
+from ..errors import UsageError
+from ..lookup import resolve_player
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "compare",
+        help="compare players' stats side by side",
+        description=(
+            "Compare two or more players. Stats run down the rows and players "
+            "across the columns, so the numbers line up for reading."
+        ),
+    )
+    parser.add_argument("names", nargs="+", help="two or more player names or MLBAM ids")
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to compare (default: current season)"
+    )
+    parser.add_argument(
+        "-g",
+        "--group",
+        choices=list(statcols.GROUPS),
+        default="hitting",
+        help="stat group to compare (default: hitting)",
+    )
+    parser.add_argument(
+        "-c", "--career", action="store_true", help="compare career totals instead of one season"
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    if len(args.names) < 2:
+        # argparse's nargs="+" accepts one; the command only means something
+        # with at least two.
+        raise UsageError("Give at least two players to compare.")
+
+    season = args.season or current_season()
+    stat_type = "career" if args.career else "season"
+
+    people = [resolve_player(ctx.client, name) for name in args.names]
+    lines = []
+    for person in people:
+        splits = ctx.client.player_stats(
+            person["id"],
+            group=args.group,
+            stat_type=stat_type,
+            season=None if args.career else season,
+        )
+        lines.append(splits[0].get("stat", {}) if splits else {})
+
+    scope = "career" if args.career else str(season)
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "group": args.group,
+                "scope": scope,
+                "players": [
+                    {
+                        "id": person.get("id"),
+                        "name": person.get("fullName"),
+                        "stats": stat,
+                    }
+                    for person, stat in zip(people, lines)
+                ],
+            }
+        )
+        return 0
+
+    print(output.heading(f"{args.group.title()} comparison — {scope}"))
+    output.blank()
+
+    columns = statcols.columns_for(args.group)
+    headers = ["Stat"] + [_short_name(person) for person in people]
+    rows: list[list] = []
+    for heading, key in columns:
+        if key.startswith("_"):
+            continue
+        values = [stat.get(key) for stat in lines]
+        if all(value is None for value in values):
+            continue
+        if key in NEUTRAL:
+            rows.append([heading] + ["-" if v is None else str(v) for v in values])
+            continue
+        lower_better = key in LOWER_IS_BETTER
+        rows.append(
+            [heading]
+            + [_highlight(values, index, lower_better) for index in range(len(values))]
+        )
+
+    if not rows:
+        print(f"  No {args.group} stats for these players in {scope}.")
+        return 0
+
+    print(output.table(headers, rows, aligns=["l"] + ["r"] * len(people)))
+    if output.color_enabled():
+        output.blank()
+        print(output.colorize("  Green marks the better figure in each row.", "dim"))
+    return 0
+
+
+def _short_name(person: dict) -> str:
+    """Use 'F. Lastname' so several columns still fit an 80-column terminal."""
+    name = person.get("fullName", "?")
+    parts = name.split()
+    if len(parts) < 2:
+        return name
+    return f"{parts[0][0]}. {' '.join(parts[1:])}"
+
+
+#: Rows where the smaller number is the better one.
+LOWER_IS_BETTER = {"era", "whip", "walksPer9Inn", "losses", "errors", "caughtStealing"}
+
+#: Rows that measure opportunity rather than performance. Marking a "winner"
+#: for these would say nothing except who played more.
+NEUTRAL = {"gamesPlayed", "gamesStarted", "plateAppearances", "atBats"}
+
+
+def _highlight(values: list, index: int, lower_is_better: bool) -> str:
+    """Render one cell, bolding it if it is the best value in its row.
+
+    A row where everyone is tied gets no highlight — marking every column
+    "best" would just be noise.
+    """
+    value = values[index]
+    if value is None:
+        return "-"
+    numeric = [number for number in (_number(v) for v in values) if number is not None]
+    if len(numeric) < 2:
+        return str(value)
+    best = min(numeric) if lower_is_better else max(numeric)
+    mine = _number(value)
+    if mine is not None and mine == best and any(number != best for number in numeric):
+        return output.colorize(str(value), "bold", "green")
+    return str(value)
+
+
+def _number(value):
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None

baseballcommand/commands/glossary.py

@@ -0,0 +1,48 @@
+"""``base glossary`` — what the column headings mean."""
+
+from __future__ import annotations
+
+from .. import output
+from .. import stats as statcols
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "glossary",
+        help="explain the stat abbreviations used in tables",
+        description="Explain every abbreviation that appears as a column heading.",
+    )
+    parser.add_argument(
+        "-g",
+        "--group",
+        choices=list(statcols.GROUPS),
+        help="only show abbreviations for one stat group",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    groups = [args.group] if args.group else list(statcols.GROUPS)
+
+    if ctx.json:
+        output.emit_json(
+            {
+                group: {
+                    heading: statcols.GLOSSARY.get(heading, "")
+                    for heading, _ in statcols.columns_for(group)
+                }
+                for group in groups
+            }
+        )
+        return 0
+
+    print(output.heading("Stat glossary"))
+    for group in groups:
+        output.blank()
+        print(output.colorize(group.title(), "bold"))
+        rows = [
+            [heading, statcols.GLOSSARY.get(heading, "")]
+            for heading, _ in statcols.columns_for(group)
+        ]
+        print(output.table(["Abbr", "Meaning"], rows, aligns=["l", "l"]))
+    return 0

baseballcommand/commands/leaders.py

@@ -0,0 +1,222 @@
+"""``base leaders`` — league leaderboards for any statistical category."""
+
+from __future__ import annotations
+
+from .. import output
+from ..api import LEAGUE_AL, LEAGUE_NL, current_season
+from ..errors import UsageError
+
+#: Shorthand a baseball fan would actually type, mapped to the API's category
+#: name and the stat group it belongs to. A group of None lets the API decide,
+#: which matters for categories that exist on both sides of the ball.
+ALIASES = {
+    "hr": ("homeRuns", "hitting"),
+    "avg": ("battingAverage", "hitting"),
+    "ba": ("battingAverage", "hitting"),
+    "rbi": ("runsBattedIn", "hitting"),
+    "sb": ("stolenBases", "hitting"),
+    "obp": ("onBasePercentage", "hitting"),
+    "slg": ("sluggingPercentage", "hitting"),
+    "ops": ("onBasePlusSlugging", "hitting"),
+    "h": ("hits", "hitting"),
+    "hits": ("hits", "hitting"),
+    "r": ("runs", "hitting"),
+    "runs": ("runs", "hitting"),
+    "2b": ("doubles", "hitting"),
+    "3b": ("triples", "hitting"),
+    "xbh": ("extraBaseHits", "hitting"),
+    "tb": ("totalBases", "hitting"),
+    "bb": ("walks", "hitting"),
+    "era": ("earnedRunAverage", "pitching"),
+    "whip": ("walksAndHitsPerInningPitched", "pitching"),
+    "w": ("wins", "pitching"),
+    "wins": ("wins", "pitching"),
+    "l": ("losses", "pitching"),
+    "sv": ("saves", "pitching"),
+    "saves": ("saves", "pitching"),
+    "k": ("strikeouts", "pitching"),
+    "so": ("strikeouts", "pitching"),
+    "ip": ("inningsPitched", "pitching"),
+    "cg": ("completeGames", "pitching"),
+    "sho": ("shutouts", "pitching"),
+    "k9": ("strikeoutsPer9Inn", "pitching"),
+    "holds": ("holds", "pitching"),
+    "e": ("errors", "fielding"),
+    "fpct": ("fieldingPercentage", "fielding"),
+}
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "leaders",
+        help="show league leaders in a statistical category",
+        description=(
+            "Show the league leaders in a statistical category. Common "
+            "shorthand works: hr, avg, rbi, era, whip, k, sv."
+        ),
+    )
+    parser.add_argument(
+        "category",
+        nargs="?",
+        help="category or shorthand, e.g. hr, era, stolenBases",
+    )
+    parser.add_argument(
+        "--list", action="store_true", help="list every category the API accepts and exit"
+    )
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to show (default: current season)"
+    )
+    parser.add_argument(
+        "-g",
+        "--group",
+        choices=["hitting", "pitching", "fielding"],
+        help="stat group (default: inferred from the category)",
+    )
+    parser.add_argument(
+        "-l",
+        "--league",
+        choices=["al", "nl", "both"],
+        default="both",
+        help="restrict to one league (default: both)",
+    )
+    parser.add_argument(
+        "-n", "--limit", type=int, default=10, help="how many leaders to show (default: 10)"
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    if args.list:
+        return _list_categories(ctx)
+
+    if not args.category:
+        raise UsageError(
+            "Which category? Try `base leaders hr`, or `base leaders --list` to see them all."
+        )
+
+    category, group = _resolve_category(ctx, args.category, args.group)
+    season = args.season or current_season()
+    league_id = {"al": LEAGUE_AL, "nl": LEAGUE_NL, "both": None}[args.league]
+
+    groups = ctx.client.leaders(
+        category=category,
+        season=season,
+        group=group,
+        league_id=league_id,
+        limit=args.limit,
+    )
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "category": category,
+                "season": season,
+                "group": group,
+                "leaderboards": [
+                    {
+                        "statGroup": board.get("statGroup"),
+                        "league": (board.get("league") or {}).get("name"),
+                        "leaders": [_leader_json(leader) for leader in board.get("leaders", [])],
+                    }
+                    for board in groups
+                ],
+            }
+        )
+        return 0
+
+    print(output.heading(f"{category} leaders — {season}", _subtitle(group, args.league)))
+
+    printed = False
+    boards = [board for board in groups if board.get("leaders")]
+    for board in boards:
+        leaders = board["leaders"]
+        printed = True
+        output.blank()
+        # With a single leaderboard the heading above already says everything a
+        # per-board title would; only label them when there are several.
+        if len(boards) > 1:
+            title = board.get("statGroup", "").title() or category
+            league = (board.get("league") or {}).get("name")
+            if league:
+                title = f"{title} — {league}"
+            print(output.colorize(title, "bold"))
+        rows = [
+            [
+                leader.get("rank"),
+                (leader.get("person") or {}).get("fullName"),
+                (leader.get("team") or {}).get("name"),
+                leader.get("value"),
+            ]
+            for leader in leaders
+        ]
+        print(output.table(["#", "Player", "Team", category], rows, aligns=["r", "l", "l", "r"]))
+
+    if not printed:
+        output.blank()
+        print(f"  No leaders returned for {category} in {season}.")
+    return 0
+
+
+def _resolve_category(ctx, requested: str, group: str | None) -> tuple[str, str | None]:
+    """Map user input to an API category name, and infer a stat group.
+
+    Checks the alias table first, then matches the API's own category list
+    case-insensitively so both ``homeRuns`` and ``homeruns`` work.
+    """
+    key = requested.strip().lower().replace("/", "").replace("-", "").replace("_", "")
+    if key in ALIASES:
+        category, inferred = ALIASES[key]
+        return category, group or inferred
+
+    valid = ctx.client.leader_categories()
+    for name in valid:
+        if name.lower() == key:
+            return name, group
+
+    near = [name for name in valid if key in name.lower()]
+    hint = f" Did you mean: {', '.join(near[:5])}?" if near else ""
+    raise UsageError(
+        f"{requested!r} is not a leader category.{hint} "
+        "Run `base leaders --list` to see all of them."
+    )
+
+
+def _list_categories(ctx) -> int:
+    categories = sorted(ctx.client.leader_categories())
+    if ctx.json:
+        output.emit_json({"categories": categories, "aliases": ALIASES})
+        return 0
+    print(output.heading("Leader categories", f"{len(categories)} available"))
+    output.blank()
+    # Three columns keeps a 70-item list to a screenful. This is a plain grid
+    # rather than a table: with no meaningful headings, the rule line above the
+    # first row would just be noise.
+    per_column = (len(categories) + 2) // 3
+    columns = [categories[i : i + per_column] for i in range(0, len(categories), per_column)]
+    width = max(len(name) for name in categories) + 2
+    for index in range(per_column):
+        cells = [column[index] if index < len(column) else "" for column in columns]
+        print("  " + "".join(cell.ljust(width) for cell in cells).rstrip())
+    output.blank()
+    print(output.colorize("  Shorthand: " + ", ".join(sorted(ALIASES)), "dim"))
+    return 0
+
+
+def _subtitle(group: str | None, league: str) -> str:
+    parts = []
+    if group:
+        parts.append(group)
+    if league != "both":
+        parts.append(league.upper())
+    return " · ".join(parts)
+
+
+def _leader_json(leader: dict) -> dict:
+    return {
+        "rank": leader.get("rank"),
+        "value": leader.get("value"),
+        "playerId": (leader.get("person") or {}).get("id"),
+        "player": (leader.get("person") or {}).get("fullName"),
+        "teamId": (leader.get("team") or {}).get("id"),
+        "team": (leader.get("team") or {}).get("name"),
+    }

baseballcommand/commands/player.py

@@ -0,0 +1,209 @@
+"""``base player`` — biographical info and stat lines for one player."""
+
+from __future__ import annotations
+
+from .. import output
+from .. import stats as statcols
+from ..api import current_season
+from ..lookup import resolve_player
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "player",
+        help="show a player's statistics",
+        description=(
+            "Look up a player by name or MLBAM id and print their statistics. "
+            "By default this shows the current season in the group that fits "
+            "their position; two-way players get both."
+        ),
+    )
+    parser.add_argument("name", help="player name (or MLBAM id), e.g. 'Aaron Judge' or 592450")
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to show (default: current season)"
+    )
+    parser.add_argument(
+        "-g",
+        "--group",
+        choices=[*statcols.GROUPS, "all"],
+        help="stat group to show (default: chosen from the player's position)",
+    )
+    parser.add_argument(
+        "-c", "--career", action="store_true", help="show career totals instead of one season"
+    )
+    parser.add_argument(
+        "-y",
+        "--years",
+        action="store_true",
+        help="show a year-by-year table of every season played",
+    )
+    parser.add_argument(
+        "-f",
+        "--full",
+        action="store_true",
+        help="list every stat the API returns, not just the common ones",
+    )
+    parser.add_argument(
+        "--postseason",
+        action="store_true",
+        help="use postseason games instead of the regular season",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    person = resolve_player(ctx.client, args.name)
+    season = args.season or current_season()
+    game_type = "P" if args.postseason else "R"
+
+    groups = _groups_for(person, args.group)
+    stat_type = "career" if args.career else ("yearByYear" if args.years else "season")
+
+    collected = {}
+    for group in groups:
+        collected[group] = ctx.client.player_stats(
+            person["id"],
+            group=group,
+            stat_type=stat_type,
+            season=None if stat_type != "season" else season,
+            game_type=game_type,
+        )
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "player": _bio_json(person),
+                "statType": stat_type,
+                "season": season if stat_type == "season" else None,
+                "gameType": game_type,
+                "stats": collected,
+            }
+        )
+        return 0
+
+    print(output.heading(person.get("fullName", args.name), _bio_subtitle(person)))
+    output.blank()
+    print(output.key_values(_bio_pairs(person)))
+
+    scope = _scope_label(stat_type, season, args.postseason)
+    for group in groups:
+        splits = collected[group]
+        output.blank()
+        label = f"{group.title()} — {scope}"
+        if not splits:
+            print(output.colorize(label, "bold"))
+            print(f"  No {group} stats for this scope.")
+            continue
+        print(output.colorize(label, "bold"))
+        print(_render_splits(splits, group, stat_type, args.full))
+
+    return 0
+
+
+def _groups_for(person: dict, requested) -> list[str]:
+    """Pick which stat groups to fetch.
+
+    An explicit ``--group`` always wins. Otherwise the player's primary position
+    decides: pitchers get pitching, two-way players get both, everyone else gets
+    hitting. Fetching all three by default would triple the requests to show
+    mostly empty tables.
+    """
+    if requested == "all":
+        return list(statcols.GROUPS)
+    if requested:
+        return [requested]
+
+    position = person.get("primaryPosition") or {}
+    if position.get("abbreviation") == "TWP" or position.get("code") == "Y":
+        return ["hitting", "pitching"]
+    if position.get("code") == "1" or position.get("abbreviation") == "P":
+        return ["pitching"]
+    return ["hitting"]
+
+
+def _scope_label(stat_type: str, season: int, postseason: bool) -> str:
+    base = {
+        "career": "career",
+        "yearByYear": "year by year",
+        "season": str(season),
+    }[stat_type]
+    return f"{base} (postseason)" if postseason else base
+
+
+def _render_splits(splits: list[dict], group: str, stat_type: str, full: bool) -> str:
+    if full:
+        # One block per split, every key the API returned.
+        blocks = []
+        for split in splits:
+            title = split.get("season") or "career"
+            rows = statcols.full_rows(split)
+            blocks.append(
+                output.colorize(f"  {title}", "dim")
+                + "\n"
+                + output.table(["Stat", "Value"], rows, aligns=["l", "r"], indent="    ")
+            )
+        return "\n\n".join(blocks)
+
+    columns = list(statcols.columns_for(group))
+    if stat_type == "yearByYear":
+        # Year-by-year needs to say which year and which club each line is.
+        columns = [("Season", "_season"), ("Team", "_team")] + columns
+
+    rows = [statcols.split_row(split, columns) for split in splits]
+    aligns = ["l"] * (2 if stat_type == "yearByYear" else 0)
+    aligns += ["r"] * (len(columns) - len(aligns))
+    if stat_type != "yearByYear" and group == "fielding":
+        aligns[0] = "l"  # the POS column
+    return output.table(statcols.headers_for(columns), rows, aligns=aligns)
+
+
+def _bio_subtitle(person: dict) -> str:
+    position = (person.get("primaryPosition") or {}).get("name", "")
+    team = (person.get("currentTeam") or {}).get("name", "")
+    number = person.get("primaryNumber")
+    parts = [part for part in (f"#{number}" if number else "", position, team) if part]
+    return " · ".join(parts)
+
+
+def _bio_pairs(person: dict) -> list[tuple]:
+    bats = (person.get("batSide") or {}).get("description")
+    throws = (person.get("pitchHand") or {}).get("description")
+    birth_place = ", ".join(
+        part
+        for part in (
+            person.get("birthCity"),
+            person.get("birthStateProvince"),
+            person.get("birthCountry"),
+        )
+        if part
+    )
+    born = person.get("birthDate")
+    if born and birth_place:
+        born = f"{born} ({birth_place})"
+
+    height, weight = person.get("height"), person.get("weight")
+    return [
+        ("Bats/Throws", f"{bats}/{throws}" if bats and throws else bats or throws),
+        ("Height/Weight", f"{height}, {weight} lb" if height and weight else None),
+        ("Age", person.get("currentAge")),
+        ("Born", born),
+        ("MLB debut", person.get("mlbDebutDate")),
+        ("Last played", person.get("lastPlayedDate")),
+        ("Status", "Active" if person.get("active") else "Retired / inactive"),
+        ("MLBAM id", person.get("id")),
+    ]
+
+
+def _bio_json(person: dict) -> dict:
+    return {
+        "id": person.get("id"),
+        "fullName": person.get("fullName"),
+        "position": (person.get("primaryPosition") or {}).get("abbreviation"),
+        "team": (person.get("currentTeam") or {}).get("name"),
+        "number": person.get("primaryNumber"),
+        "bats": (person.get("batSide") or {}).get("code"),
+        "throws": (person.get("pitchHand") or {}).get("code"),
+        "birthDate": person.get("birthDate"),
+        "active": person.get("active"),
+        "mlbDebutDate": person.get("mlbDebutDate"),
+    }