baseballcommand 0.1.0__py3-none-any.whl

baseballcommand/commands/roster.py

@@ -0,0 +1,225 @@
+"""``base roster`` — a club's roster, optionally with everyone's stat line."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .. import output
+from .. import stats as statcols
+from ..api import current_season
+from ..errors import UsageError
+from ..lookup import resolve_team
+
+#: Friendly names for the API's ``rosterType`` values.
+ROSTER_TYPES = {
+    "active": "active",
+    "40man": "40Man",
+    "full": "fullSeason",
+    "depth": "depthChart",
+}
+
+#: Columns where a smaller number is better, so ``--sort`` orders them ascending.
+LOWER_IS_BETTER = {"ERA", "WHIP", "BB/9", "L", "E", "CS"}
+
+#: Default sort per group: the stat that best approximates "how much did this
+#: player actually play".
+DEFAULT_SORT = {"hitting": "PA", "pitching": "IP", "fielding": "INN"}
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "roster",
+        help="list a team's roster, with stats if asked",
+        description=(
+            "List a team's roster. With --stats, every player's season line is "
+            "included; the API returns them all in a single request, so this "
+            "costs no more than the plain listing."
+        ),
+    )
+    parser.add_argument("name", help="team name, e.g. NYY, Toronto, 'Blue Jays'")
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to show (default: current season)"
+    )
+    parser.add_argument(
+        "-t",
+        "--type",
+        choices=sorted(ROSTER_TYPES),
+        default="active",
+        help="which roster to show (default: active)",
+    )
+    parser.add_argument(
+        "--stats", action="store_true", help="include each player's season stat line"
+    )
+    parser.add_argument(
+        "-g",
+        "--group",
+        choices=["hitting", "pitching", "fielding"],
+        help="with --stats, show only this group (default: hitting and pitching)",
+    )
+    parser.add_argument(
+        "--sort",
+        help="with --stats, sort by a column heading such as HR, OPS, or ERA",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    season = args.season or current_season()
+    team = resolve_team(ctx.client, args.name, season)
+
+    groups = [args.group] if args.group else ["hitting", "pitching"]
+    if ctx.json:
+        # The JSON shape carries all three groups regardless of --group, so
+        # scripts get a consistent structure.
+        groups = list(statcols.GROUPS)
+
+    entries = ctx.client.roster(
+        team["id"],
+        season=season,
+        roster_type=ROSTER_TYPES[args.type],
+        stat_groups=groups if args.stats else (),
+    )
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "team": {"id": team["id"], "name": team.get("name")},
+                "season": season,
+                "rosterType": ROSTER_TYPES[args.type],
+                "players": [_player_json(entry, args.stats) for entry in entries],
+            }
+        )
+        return 0
+
+    # Build every table before printing anything, so a bad --sort column fails
+    # cleanly rather than half-way through the output.
+    tables = (
+        {group: _stat_table(entries, group, args.sort) for group in groups}
+        if args.stats and entries
+        else {}
+    )
+
+    subtitle = f"{season} · {args.type} roster · {len(entries)} players"
+    print(output.heading(team.get("name", args.name), subtitle))
+
+    if not entries:
+        output.blank()
+        print("  No players on this roster.")
+        return 0
+
+    if not args.stats:
+        output.blank()
+        rows = [
+            [
+                entry.get("jerseyNumber") or "",
+                (entry.get("person") or {}).get("fullName", "?"),
+                (entry.get("position") or {}).get("abbreviation", ""),
+                (entry.get("status") or {}).get("description", ""),
+            ]
+            for entry in entries
+        ]
+        rows.sort(key=lambda row: row[1])
+        print(output.table(["#", "Player", "Pos", "Status"], rows, aligns=["r", "l", "l", "l"]))
+        return 0
+
+    for group in groups:
+        output.blank()
+        print(output.colorize(f"{group.title()} — {season}", "bold"))
+        print(tables[group] or f"  No {group} stats on this roster for {season}.")
+    return 0
+
+
+def _stat_table(entries: list[dict], group: str, sort_by: str | None) -> str:
+    columns = [("Player", "_player"), ("Pos", "_pos")] + list(statcols.columns_for(group))
+    if group == "fielding":
+        # The synthetic POS column from the fielding split duplicates the roster
+        # position we already show.
+        columns = [column for column in columns if column[1] != "_position"]
+
+    rows: list[list[Any]] = []
+    for entry in entries:
+        split = _season_split(entry, group)
+        if split is None:
+            continue
+        row = statcols.split_row(split, columns)
+        row[0] = (entry.get("person") or {}).get("fullName", "?")
+        row[1] = (entry.get("position") or {}).get("abbreviation", "")
+        rows.append(row)
+
+    if not rows:
+        return ""
+
+    headers = statcols.headers_for(columns)
+    rows = _sort_rows(rows, headers, sort_by or DEFAULT_SORT.get(group, ""))
+    return output.table(headers, rows, aligns=["l", "l"] + ["r"] * (len(headers) - 2))
+
+
+def _season_split(entry: dict, group: str) -> dict | None:
+    """Pull one season split for ``group`` out of a hydrated roster entry.
+
+    A player traded mid-season has one split per club. The roster we are
+    printing belongs to a specific team, so prefer that team's split and fall
+    back to the first one otherwise.
+    """
+    person = entry.get("person") or {}
+    team_id = (entry.get("parentTeamId") or person.get("currentTeam", {}).get("id"))
+    for block in person.get("stats", []) or []:
+        if (block.get("group") or {}).get("displayName") != group:
+            continue
+        splits = block.get("splits") or []
+        if not splits:
+            continue
+        for split in splits:
+            if (split.get("team") or {}).get("id") == team_id:
+                return split
+        return splits[0]
+    return None
+
+
+def _sort_rows(rows: list[list[Any]], headers: list[str], sort_by: str) -> list[list[Any]]:
+    if not sort_by:
+        return sorted(rows, key=lambda row: str(row[0]))
+
+    lookup = {header.upper(): index for index, header in enumerate(headers)}
+    index = lookup.get(sort_by.upper())
+    if index is None:
+        raise UsageError(
+            f"Cannot sort by {sort_by!r}. Available columns: {', '.join(headers[2:])}."
+        )
+
+    ascending = headers[index].upper() in LOWER_IS_BETTER
+    return sorted(rows, key=lambda row: _sort_key(row[index], ascending), reverse=not ascending)
+
+
+def _sort_key(value: Any, ascending: bool) -> float:
+    """Coerce a stat cell to a float for sorting.
+
+    Missing stats sort to the bottom either way, which is why the sentinel
+    flips with the sort direction.
+    """
+    missing = float("inf") if ascending else float("-inf")
+    if value is None or value == "":
+        return missing
+    try:
+        # float() already handles the API's leading-dot rates (".331") and its
+        # innings notation ("112.2"), which orders correctly as a decimal.
+        return float(value)
+    except (TypeError, ValueError):
+        return missing
+
+
+def _player_json(entry: dict, with_stats: bool) -> dict[str, Any]:
+    person = entry.get("person") or {}
+    record = {
+        "id": person.get("id"),
+        "name": person.get("fullName"),
+        "number": entry.get("jerseyNumber"),
+        "position": (entry.get("position") or {}).get("abbreviation"),
+        "status": (entry.get("status") or {}).get("description"),
+    }
+    if with_stats:
+        record["stats"] = {
+            group: (_season_split(entry, group) or {}).get("stat")
+            for group in ("hitting", "pitching", "fielding")
+        }
+    return record

baseballcommand/commands/scores.py

@@ -0,0 +1,214 @@
+"""``base scores`` — the day's games, with line scores on request."""
+
+from __future__ import annotations
+
+from .. import output
+from ..dates import human_date, iso, local_time, parse_date
+from ..lookup import resolve_team
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "scores",
+        help="show scores for a day's games",
+        description="Show the scores and status of every MLB game on a given day.",
+    )
+    parser.add_argument(
+        "date",
+        nargs="?",
+        help="date to show: YYYY-MM-DD, MM/DD, today/yesterday/tomorrow, "
+        "or an offset like -3 (default: today)",
+    )
+    parser.add_argument("-t", "--team", help="only show games involving this team")
+    parser.add_argument(
+        "-l",
+        "--linescore",
+        action="store_true",
+        help="also print the inning-by-inning line score for each game",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    day = parse_date(args.date)
+    team_id: int | None = None
+    team_label = None
+    if args.team:
+        team = resolve_team(ctx.client, args.team)
+        team_id = team["id"]
+        team_label = team.get("name")
+
+    payload = ctx.client.schedule(game_date=iso(day), team_id=team_id, ttl=ctx.live_ttl)
+    games = _games_for(payload)
+
+    if ctx.json:
+        output.emit_json({"date": iso(day), "games": [_game_json(g) for g in games]})
+        return 0
+
+    subtitle = f"{len(games)} game{'s' if len(games) != 1 else ''}"
+    if team_label:
+        subtitle += f" — {team_label}"
+    print(output.heading(f"Scores — {human_date(day)}", subtitle))
+    output.blank()
+
+    if not games:
+        print("  No games scheduled.")
+        return 0
+
+    rows = [_score_row(game) for game in games]
+    print(
+        output.table(
+            ["Status", "Away", "R", "Home", "R", "Notes"],
+            rows,
+            aligns=["l", "l", "r", "l", "r", "l"],
+        )
+    )
+
+    if args.linescore:
+        for game in games:
+            block = _linescore_block(game)
+            if block:
+                output.blank()
+                print(block)
+
+    return 0
+
+
+def _games_for(payload: dict) -> list[dict]:
+    games: list[dict] = []
+    for entry in payload.get("dates", []):
+        games.extend(entry.get("games", []))
+    return games
+
+
+def _team_name(side: dict) -> str:
+    team = side.get("team", {}) or {}
+    return team.get("name") or team.get("teamName") or "?"
+
+
+def _status_text(game: dict) -> str:
+    status = game.get("status", {}) or {}
+    abstract = status.get("abstractGameState")
+    detailed = status.get("detailedState", abstract or "?")
+    linescore = game.get("linescore", {}) or {}
+
+    if abstract == "Live":
+        half = (linescore.get("inningState") or "").replace("Middle", "Mid")[:3]
+        inning = linescore.get("currentInningOrdinal") or ""
+        text = f"{half} {inning}".strip() or detailed
+        return output.colorize(text, "green", "bold")
+
+    if abstract == "Final":
+        innings = linescore.get("currentInning")
+        scheduled = linescore.get("scheduledInnings") or 9
+        # Extra-inning games get the familiar "F/11" shorthand.
+        if detailed in ("Final", "Game Over") and innings and innings != scheduled:
+            return f"F/{innings}"
+        return output.colorize(detailed, "dim")
+
+    if detailed in ("Scheduled", "Pre-Game", "Warmup", "Delayed Start"):
+        start = local_time(game.get("gameDate"))
+        return start or detailed
+    return output.colorize(detailed, "yellow")
+
+
+def _score_row(game: dict) -> list:
+    away = game.get("teams", {}).get("away", {}) or {}
+    home = game.get("teams", {}).get("home", {}) or {}
+    started = game.get("status", {}).get("abstractGameState") in ("Live", "Final")
+
+    away_runs = _format_runs(away, started)
+    home_runs = _format_runs(home, started)
+
+    return [
+        _status_text(game),
+        _team_name(away),
+        away_runs,
+        _team_name(home),
+        home_runs,
+        _notes(game),
+    ]
+
+
+def _format_runs(side: dict, started: bool) -> str:
+    if not started:
+        return ""
+    runs = side.get("score")
+    if runs is None:
+        return ""
+    text = str(runs)
+    return output.colorize(text, "bold") if side.get("isWinner") else text
+
+
+def _notes(game: dict) -> str:
+    """Probable starters before first pitch; otherwise nothing worth a column."""
+    if game.get("status", {}).get("abstractGameState") != "Preview":
+        return ""
+    teams = game.get("teams", {})
+    away = (teams.get("away", {}).get("probablePitcher") or {}).get("fullName")
+    home = (teams.get("home", {}).get("probablePitcher") or {}).get("fullName")
+    if not away and not home:
+        return ""
+    return f"{_last_name(away)} vs {_last_name(home)}"
+
+
+def _last_name(full_name: str | None) -> str:
+    if not full_name:
+        return "TBD"
+    return full_name.split()[-1]
+
+
+def _linescore_block(game: dict) -> str:
+    """Render one game's inning-by-inning line score, R/H/E included."""
+    linescore = game.get("linescore", {}) or {}
+    innings = linescore.get("innings") or []
+    if not innings:
+        return ""
+
+    headers = [""] + [str(inning.get("num", "")) for inning in innings] + ["R", "H", "E"]
+    rows = []
+    for side in ("away", "home"):
+        name = _team_name(game.get("teams", {}).get(side, {}))
+        cells = [name]
+        for inning in innings:
+            half = inning.get(side, {}) or {}
+            runs = half.get("runs")
+            # A blank cell means the half-inning has not been played — the
+            # standard way a bottom-of-the-9th walk-off is shown.
+            cells.append("" if runs is None else str(runs))
+        totals = linescore.get("teams", {}).get(side, {}) or {}
+        cells += [totals.get("runs", 0), totals.get("hits", 0), totals.get("errors", 0)]
+        rows.append(cells)
+
+    return output.table(headers, rows, aligns=["l"] + ["r"] * (len(headers) - 1))
+
+
+def _game_json(game: dict) -> dict:
+    """Flatten a game into the stable shape ``--json`` promises."""
+    teams = game.get("teams", {})
+    status = game.get("status", {})
+    linescore = game.get("linescore", {}) or {}
+    return {
+        "gamePk": game.get("gamePk"),
+        "gameDate": game.get("gameDate"),
+        "status": status.get("detailedState"),
+        "abstractState": status.get("abstractGameState"),
+        "inning": linescore.get("currentInning"),
+        "inningState": linescore.get("inningState"),
+        "venue": (game.get("venue") or {}).get("name"),
+        "away": _side_json(teams.get("away", {})),
+        "home": _side_json(teams.get("home", {})),
+    }
+
+
+def _side_json(side: dict) -> dict:
+    team = side.get("team", {}) or {}
+    return {
+        "id": team.get("id"),
+        "name": team.get("name"),
+        "abbreviation": team.get("abbreviation"),
+        "score": side.get("score"),
+        "isWinner": side.get("isWinner"),
+        "record": side.get("leagueRecord"),
+        "probablePitcher": (side.get("probablePitcher") or {}).get("fullName"),
+    }

baseballcommand/commands/standings.py

@@ -0,0 +1,193 @@
+"""``base standings`` — division and wild card standings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .. import output
+from ..api import LEAGUE_AL, LEAGUE_NL, current_season
+
+#: The standings payload identifies divisions by id only. Hydrated team records
+#: usually carry the name, but this map keeps the output readable when they
+#: don't.
+DIVISION_NAMES = {
+    200: "American League West",
+    201: "American League East",
+    202: "American League Central",
+    203: "National League West",
+    204: "National League East",
+    205: "National League Central",
+}
+
+#: Wild card records span a whole league, and the payload names it by id only.
+LEAGUE_NAMES = {LEAGUE_AL: "American League", LEAGUE_NL: "National League"}
+
+LEAGUE_IDS = {"al": (LEAGUE_AL,), "nl": (LEAGUE_NL,), "both": (LEAGUE_AL, LEAGUE_NL)}
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "standings",
+        help="show division or wild card standings",
+        description="Show the current standings, by division or by wild card race.",
+    )
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to show (default: current season)"
+    )
+    parser.add_argument(
+        "-l",
+        "--league",
+        choices=["al", "nl", "both"],
+        default="both",
+        help="restrict to one league (default: both)",
+    )
+    parser.add_argument(
+        "-w",
+        "--wildcard",
+        action="store_true",
+        help="show the wild card race instead of division standings",
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    season = args.season or current_season()
+    standings_type = "wildCard" if args.wildcard else "regularSeason"
+    records = ctx.client.standings(
+        season=season,
+        league_ids=LEAGUE_IDS[args.league],
+        standings_type=standings_type,
+    )
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "season": season,
+                "type": standings_type,
+                "groups": [
+                    {
+                        "name": _group_name(record, args.wildcard),
+                        "teams": [_team_json(entry) for entry in record.get("teamRecords", [])],
+                    }
+                    for record in records
+                ],
+            }
+        )
+        return 0
+
+    label = "Wild Card" if args.wildcard else "Standings"
+    print(output.heading(f"{label} — {season}"))
+
+    if not records:
+        output.blank()
+        print(f"  No standings available for {season}.")
+        return 0
+
+    for record in sorted(records, key=lambda r: _group_name(r, args.wildcard)):
+        entries = record.get("teamRecords", [])
+        if not entries:
+            continue
+        output.blank()
+        print(output.colorize(_group_name(record, args.wildcard), "bold"))
+        headers = ["Team", "W", "L", "PCT", "GB", "L10", "STRK", "RS", "RA", "DIFF"]
+        rows = [_row(entry, args.wildcard) for entry in entries]
+        print(output.table(headers, rows, aligns=["l"] + ["r"] * (len(headers) - 1)))
+
+    output.blank()
+    print(
+        output.colorize(
+            "  z = division champion   y = division leader   "
+            "w = wild card   e = eliminated",
+            "dim",
+        )
+    )
+    return 0
+
+
+def _group_name(record: dict, wildcard: bool = False) -> str:
+    """Title the block of teams in one standings record.
+
+    A wild card record covers an entire league, but the payload still carries a
+    leftover ``division`` from the regular-season shape — using it would label
+    twelve teams "American League East".
+    """
+    league = record.get("league") or {}
+    if wildcard:
+        return league.get("name") or LEAGUE_NAMES.get(league.get("id"), "Wild Card")
+
+    division = record.get("division") or {}
+    if division.get("name"):
+        return division["name"]
+    # Fall back to the first team's hydrated division, then to the static map.
+    for entry in record.get("teamRecords", []):
+        team_division = (entry.get("team") or {}).get("division") or {}
+        if team_division.get("name"):
+            return team_division["name"]
+    return DIVISION_NAMES.get(division.get("id"), league.get("name", "—"))
+
+
+def _first(*values) -> Any:
+    """Return the first value that isn't None. Zero counts as a value."""
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def _row(entry: dict, wildcard: bool) -> list[Any]:
+    league_record = entry.get("leagueRecord", {}) or {}
+    wins = _first(entry.get("wins"), league_record.get("wins"))
+    losses = _first(entry.get("losses"), league_record.get("losses"))
+    pct = _first(entry.get("winningPercentage"), league_record.get("pct"))
+    games_back = entry.get("wildCardGamesBack") if wildcard else entry.get("gamesBack")
+
+    name = (entry.get("team") or {}).get("name", "?")
+    indicator = entry.get("clinchIndicator")
+    if indicator:
+        name = f"{name} - {indicator}"
+
+    differential = entry.get("runDifferential")
+    return [
+        name,
+        wins,
+        losses,
+        pct,
+        games_back,
+        _split_record(entry, "lastTen"),
+        (entry.get("streak") or {}).get("streakCode"),
+        entry.get("runsScored"),
+        entry.get("runsAllowed"),
+        _signed(differential),
+    ]
+
+
+def _split_record(entry: dict, split_type: str) -> str | None:
+    for split in (entry.get("records") or {}).get("splitRecords", []):
+        if split.get("type") == split_type:
+            return f"{split.get('wins')}-{split.get('losses')}"
+    return None
+
+
+def _signed(value) -> str | None:
+    if value is None:
+        return None
+    return f"+{value}" if value > 0 else str(value)
+
+
+def _team_json(entry: dict) -> dict:
+    league_record = entry.get("leagueRecord", {}) or {}
+    return {
+        "id": (entry.get("team") or {}).get("id"),
+        "name": (entry.get("team") or {}).get("name"),
+        "wins": _first(entry.get("wins"), league_record.get("wins")),
+        "losses": _first(entry.get("losses"), league_record.get("losses")),
+        "pct": _first(entry.get("winningPercentage"), league_record.get("pct")),
+        "gamesBack": entry.get("gamesBack"),
+        "wildCardGamesBack": entry.get("wildCardGamesBack"),
+        "divisionRank": entry.get("divisionRank"),
+        "streak": (entry.get("streak") or {}).get("streakCode"),
+        "runsScored": entry.get("runsScored"),
+        "runsAllowed": entry.get("runsAllowed"),
+        "runDifferential": entry.get("runDifferential"),
+        "clinchIndicator": entry.get("clinchIndicator"),
+    }