baseballcommand 0.1.0__py3-none-any.whl

baseballcommand/commands/team.py

@@ -0,0 +1,165 @@
+"""``base team`` — club record and team-level statistics."""
+
+from __future__ import annotations
+
+from .. import output
+from .. import stats as statcols
+from ..api import current_season
+from ..lookup import resolve_team
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "team",
+        help="show a team's record and statistics",
+        description=(
+            "Look up a team by abbreviation, city, nickname, or full name and "
+            "print its record and season stat totals."
+        ),
+    )
+    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(
+        "-g",
+        "--group",
+        choices=[*statcols.GROUPS, "all"],
+        help="stat group to show (default: hitting and pitching)",
+    )
+    parser.add_argument(
+        "-f",
+        "--full",
+        action="store_true",
+        help="list every stat the API returns, not just the common ones",
+    )
+    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 = (
+        list(statcols.GROUPS)
+        if args.group == "all"
+        else ([args.group] if args.group else ["hitting", "pitching"])
+    )
+
+    collected = {
+        group: ctx.client.team_stats(team["id"], group=group, season=season)
+        for group in groups
+    }
+    record = _team_record(ctx, team["id"], season)
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "team": _team_json(team),
+                "season": season,
+                "record": record,
+                "stats": collected,
+            }
+        )
+        return 0
+
+    print(output.heading(team.get("name", args.name), _team_subtitle(team, season)))
+    output.blank()
+    print(output.key_values(_team_pairs(team, record)))
+
+    for group in groups:
+        splits = collected[group]
+        output.blank()
+        print(output.colorize(f"{group.title()} — {season}", "bold"))
+        if not splits:
+            print(f"  No {group} stats for {season}.")
+            continue
+        print(_render(splits[0], group, args.full))
+
+    return 0
+
+
+def _render(split: dict, group: str, full: bool) -> str:
+    if full:
+        return output.table(["Stat", "Value"], statcols.full_rows(split), aligns=["l", "r"])
+    columns = statcols.columns_for(group)
+    row = statcols.split_row(split, columns)
+    aligns = ["r"] * len(columns)
+    if group == "fielding":
+        aligns[0] = "l"
+    return output.table(statcols.headers_for(columns), [row], aligns=aligns)
+
+
+def _team_record(ctx, team_id: int, season: int) -> dict | None:
+    """Find a team's standings line for the season.
+
+    Returns None outside the regular season, or for a season the standings
+    endpoint has no data for yet, rather than treating that as an error.
+    """
+    for division in ctx.client.standings(season=season):
+        for entry in division.get("teamRecords", []):
+            if (entry.get("team") or {}).get("id") == team_id:
+                league_record = entry.get("leagueRecord", {})
+                return {
+                    "wins": league_record.get("wins"),
+                    "losses": league_record.get("losses"),
+                    "pct": league_record.get("pct"),
+                    "divisionRank": entry.get("divisionRank"),
+                    "gamesBack": entry.get("gamesBack"),
+                    "streak": (entry.get("streak") or {}).get("streakCode"),
+                }
+    return None
+
+
+def _team_subtitle(team: dict, season: int) -> str:
+    parts = [
+        str(season),
+        (team.get("league") or {}).get("name", ""),
+        (team.get("division") or {}).get("name", ""),
+    ]
+    return " · ".join(part for part in parts if part)
+
+
+def _team_pairs(team: dict, record: dict | None) -> list[tuple]:
+    pairs = [
+        ("Abbreviation", team.get("abbreviation")),
+        ("Venue", (team.get("venue") or {}).get("name")),
+        ("First season", team.get("firstYearOfPlay")),
+    ]
+    if record:
+        line = f"{record['wins']}-{record['losses']} ({record['pct']})"
+        pairs.insert(0, ("Record", line))
+        rank = record.get("divisionRank")
+        # The standings payload names divisions by id only, but the team record
+        # we already fetched carries the readable name.
+        division = (team.get("division") or {}).get("name")
+        if rank and division:
+            back = record.get("gamesBack")
+            suffix = "" if back in (None, "-") else f", {back} GB"
+            pairs.insert(1, ("Division", f"{_ordinal(rank)} in {division}{suffix}"))
+        if record.get("streak"):
+            pairs.insert(2, ("Streak", record["streak"]))
+    return pairs
+
+
+def _ordinal(rank) -> str:
+    try:
+        number = int(rank)
+    except (TypeError, ValueError):
+        return str(rank)
+    if 10 <= number % 100 <= 20:
+        suffix = "th"
+    else:
+        suffix = {1: "st", 2: "nd", 3: "rd"}.get(number % 10, "th")
+    return f"{number}{suffix}"
+
+
+def _team_json(team: dict) -> dict:
+    return {
+        "id": team.get("id"),
+        "name": team.get("name"),
+        "abbreviation": team.get("abbreviation"),
+        "league": (team.get("league") or {}).get("name"),
+        "division": (team.get("division") or {}).get("name"),
+        "venue": (team.get("venue") or {}).get("name"),
+    }

baseballcommand/commands/teams.py

@@ -0,0 +1,83 @@
+"""``base teams`` — the list of clubs, so lookups are discoverable."""
+
+from __future__ import annotations
+
+from .. import output
+from ..api import LEAGUE_AL, LEAGUE_NL, current_season
+
+
+def register(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "teams",
+        help="list all MLB teams and their abbreviations",
+        description=(
+            "List every MLB club with the abbreviation, city, and division. "
+            "Any of these can be passed to commands that take a team."
+        ),
+    )
+    parser.add_argument(
+        "-s", "--season", type=int, help="season to list (default: current season)"
+    )
+    parser.add_argument(
+        "-l", "--league", choices=["al", "nl", "both"], default="both", help="restrict to a league"
+    )
+    parser.set_defaults(func=run)
+
+
+def run(args, ctx) -> int:
+    season = args.season or current_season()
+    teams = ctx.client.teams(season)
+
+    wanted = {"al": LEAGUE_AL, "nl": LEAGUE_NL}.get(args.league)
+    if wanted:
+        teams = [team for team in teams if (team.get("league") or {}).get("id") == wanted]
+
+    teams.sort(
+        key=lambda team: (
+            (team.get("league") or {}).get("name", ""),
+            (team.get("division") or {}).get("name", ""),
+            team.get("name", ""),
+        )
+    )
+
+    if ctx.json:
+        output.emit_json(
+            {
+                "season": season,
+                "teams": [
+                    {
+                        "id": team.get("id"),
+                        "name": team.get("name"),
+                        "abbreviation": team.get("abbreviation"),
+                        "clubName": team.get("clubName"),
+                        "locationName": team.get("locationName"),
+                        "league": (team.get("league") or {}).get("name"),
+                        "division": (team.get("division") or {}).get("name"),
+                        "venue": (team.get("venue") or {}).get("name"),
+                    }
+                    for team in teams
+                ],
+            }
+        )
+        return 0
+
+    print(output.heading(f"MLB teams — {season}", f"{len(teams)} clubs"))
+    output.blank()
+    rows = [
+        [
+            team.get("abbreviation", ""),
+            team.get("name", ""),
+            (team.get("division") or {}).get("name", ""),
+            (team.get("venue") or {}).get("name", ""),
+            team.get("id"),
+        ]
+        for team in teams
+    ]
+    print(
+        output.table(
+            ["Abbr", "Team", "Division", "Venue", "Id"],
+            rows,
+            aligns=["l", "l", "l", "l", "r"],
+        )
+    )
+    return 0

baseballcommand/dates.py

@@ -0,0 +1,96 @@
+"""Date parsing and time formatting helpers.
+
+Users type ``yesterday`` far more often than ``2026-08-13``, so anything taking
+a date accepts both. Game times come back from the API in UTC; they are shown in
+the machine's local timezone, which is what a person checking tonight's slate
+actually wants.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timedelta, timezone
+
+from .errors import UsageError
+
+ISO_FORMAT = "%Y-%m-%d"
+
+_RELATIVE = {
+    "today": 0,
+    "yesterday": -1,
+    "tomorrow": 1,
+}
+
+
+def parse_date(value: str | None, today: date | None = None) -> date:
+    """Parse a user-supplied date.
+
+    Accepts ``YYYY-MM-DD``, ``MM/DD`` and ``MM-DD`` (current year), the words
+    ``today``/``yesterday``/``tomorrow``, and signed day offsets like ``-3`` or
+    ``+2``. ``None`` or an empty string means today.
+
+    Raises:
+        UsageError: If the string isn't a date in any accepted form.
+    """
+    today = today or date.today()
+    if not value:
+        return today
+
+    text = value.strip().lower()
+
+    if text in _RELATIVE:
+        return today + timedelta(days=_RELATIVE[text])
+
+    if re.fullmatch(r"[+-]\d+", text):
+        return today + timedelta(days=int(text))
+
+    for fmt in (ISO_FORMAT, "%Y/%m/%d", "%m/%d/%Y", "%m-%d-%Y"):
+        try:
+            return datetime.strptime(text, fmt).date()
+        except ValueError:
+            continue
+
+    # Month/day without a year: assume the current year.
+    match = re.fullmatch(r"(\d{1,2})[/-](\d{1,2})", text)
+    if match:
+        month, day = int(match.group(1)), int(match.group(2))
+        try:
+            return date(today.year, month, day)
+        except ValueError as exc:
+            raise UsageError(f"{value!r} is not a real date.") from exc
+
+    raise UsageError(
+        f"Could not read {value!r} as a date. Use YYYY-MM-DD, MM/DD, "
+        "today/yesterday/tomorrow, or an offset like -3."
+    )
+
+
+def iso(value: date) -> str:
+    """Format a date the way the API expects it."""
+    return value.strftime(ISO_FORMAT)
+
+
+def human_date(value: date) -> str:
+    """Format a date for a heading, e.g. ``Thursday, August 14, 2026``."""
+    # %-d is not portable to every libc, so strip the zero by hand.
+    return value.strftime("%A, %B ") + str(value.day) + value.strftime(", %Y")
+
+
+def local_time(iso_timestamp: str | None) -> str | None:
+    """Convert a UTC ISO-8601 timestamp to a local clock time like ``7:10 PM``.
+
+    Returns None if the timestamp is missing or unparseable, so callers can fall
+    back to whatever text the API gave them.
+    """
+    if not iso_timestamp:
+        return None
+    text = iso_timestamp.replace("Z", "+00:00")
+    try:
+        moment = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    local = moment.astimezone()
+    hour = local.hour % 12 or 12
+    return f"{hour}:{local.minute:02d} {'AM' if local.hour < 12 else 'PM'}"

baseballcommand/errors.py

@@ -0,0 +1,39 @@
+"""Exceptions raised by BaseballCommand.
+
+Every error that is expected to reach the user inherits from
+:class:`BaseballCommandError`. ``cli.main`` catches that base class and prints
+``str(exc)`` without a traceback, so error messages should be written for a
+human reading a terminal.
+"""
+
+
+class BaseballCommandError(Exception):
+    """Base class for all errors that should be reported to the user."""
+
+
+class APIError(BaseballCommandError):
+    """The MLB Stats API returned an error or could not be reached."""
+
+
+class NotFoundError(BaseballCommandError):
+    """A player, team, or other entity could not be found."""
+
+
+class AmbiguousError(BaseballCommandError):
+    """A lookup matched more than one entity.
+
+    Args:
+        message: The headline shown to the user.
+        candidates: Pre-formatted lines describing each match.
+    """
+
+    def __init__(self, message: str, candidates=()):
+        self.candidates = list(candidates)
+        if self.candidates:
+            listing = "\n".join("  " + c for c in self.candidates)
+            message = f"{message}\n{listing}"
+        super().__init__(message)
+
+
+class UsageError(BaseballCommandError):
+    """The command was invoked with arguments that cannot be satisfied."""

baseballcommand/lookup.py

@@ -0,0 +1,207 @@
+"""Turning what a person types into the ids the API wants.
+
+Users type ``nyy``, ``yanks``, or ``New York Yankees``; they type ``judge`` or
+``Aaron Judge``. The API wants ``147`` and ``592450``. This module is the
+translation layer, and it is deliberately forgiving: exact matches win, then
+well-known nicknames, then unique substring matches. When a query genuinely
+matches several entities we raise :class:`~.errors.AmbiguousError` with the
+candidates rather than guessing, because silently picking the wrong Will Smith
+is worse than asking.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .api import StatsAPI
+from .errors import AmbiguousError, NotFoundError
+
+#: Nicknames and shorthands that no amount of substring matching would catch.
+#: Keys are normalized (lowercase, alphanumeric only); values are the club name
+#: as the API spells it.
+TEAM_ALIASES: dict[str, str] = {
+    "dbacks": "Diamondbacks",
+    "snakes": "Diamondbacks",
+    "ari": "Diamondbacks",
+    "az": "Diamondbacks",
+    "bravos": "Braves",
+    "os": "Orioles",
+    "birds": "Orioles",
+    "bosox": "Red Sox",
+    "redsox": "Red Sox",
+    "chisox": "White Sox",
+    "whitesox": "White Sox",
+    "cws": "White Sox",
+    "chw": "White Sox",
+    "northsiders": "Cubs",
+    "tribe": "Guardians",
+    "guards": "Guardians",
+    "rox": "Rockies",
+    "tigs": "Tigers",
+    "stros": "Astros",
+    "halos": "Angels",
+    "laa": "Angels",
+    "lad": "Dodgers",
+    "dodgers": "Dodgers",
+    "fish": "Marlins",
+    "brew": "Brewers",
+    "brewcrew": "Brewers",
+    "twinkies": "Twins",
+    "yanks": "Yankees",
+    "nyy": "Yankees",
+    "nym": "Mets",
+    "as": "Athletics",
+    "athletics": "Athletics",
+    "oak": "Athletics",
+    "phils": "Phillies",
+    "bucs": "Pirates",
+    "buccos": "Pirates",
+    "pads": "Padres",
+    "sd": "Padres",
+    "friars": "Padres",
+    "giants": "Giants",
+    "sf": "Giants",
+    "ms": "Mariners",
+    "cards": "Cardinals",
+    "rays": "Rays",
+    "tb": "Rays",
+    "jays": "Blue Jays",
+    "bluejays": "Blue Jays",
+    "nats": "Nationals",
+    "wsh": "Nationals",
+}
+
+
+def normalize(text: str) -> str:
+    """Lowercase ``text`` and strip everything that isn't a letter or digit."""
+    return re.sub(r"[^a-z0-9]", "", text.lower())
+
+
+def resolve_team(client: StatsAPI, query: str, season: int | None = None) -> dict:
+    """Return the team record matching ``query``.
+
+    Accepts a numeric team id, an abbreviation (``NYY``), a nickname (``yanks``),
+    a club name (``Yankees``), a city (``Toronto``), or a full name.
+
+    Raises:
+        NotFoundError: If nothing matches.
+        AmbiguousError: If several teams match equally well.
+    """
+    teams = client.teams(season)
+    if not teams:
+        raise NotFoundError("Could not load the team list from the MLB Stats API.")
+
+    raw = query.strip()
+    key = normalize(raw)
+    if not key:
+        raise NotFoundError("No team name given.")
+
+    if raw.isdigit():
+        for team in teams:
+            if team.get("id") == int(raw):
+                return team
+        raise NotFoundError(f"No MLB team has id {raw}.")
+
+    # An alias rewrites the query to a club name, then falls through to the
+    # regular exact-match pass below.
+    key = normalize(TEAM_ALIASES.get(key, key))
+
+    exact_fields = ("abbreviation", "teamName", "clubName", "shortName", "name", "locationName")
+    for field in exact_fields:
+        matches = [team for team in teams if normalize(str(team.get(field, ""))) == key]
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            raise AmbiguousError(
+                f"{query!r} matches more than one team:", _team_candidates(matches)
+            )
+
+    # Last resort: unique substring match anywhere in the full name.
+    matches = [team for team in teams if key in normalize(str(team.get("name", "")))]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise AmbiguousError(f"{query!r} matches more than one team:", _team_candidates(matches))
+
+    raise NotFoundError(
+        f"No MLB team matches {query!r}. Try an abbreviation (NYY), a city "
+        "(Toronto), or a club name (Blue Jays); `base teams` lists them all."
+    )
+
+
+def _team_candidates(teams: list[dict]) -> list[str]:
+    return [f"{team.get('abbreviation', '?'):>4}  {team.get('name', '?')}" for team in teams]
+
+
+def resolve_player(client: StatsAPI, query: str, prefer_active: bool = True) -> dict:
+    """Return the player record matching ``query``.
+
+    Accepts an MLBAM player id or any part of a name. Historical players are
+    searchable too — ``base player "ken griffey jr"`` works.
+
+    Args:
+        prefer_active: When a name matches several players and exactly one of
+            them is active, take the active one. Turn this off to force the
+            ambiguity to surface.
+
+    Raises:
+        NotFoundError: If nothing matches.
+        AmbiguousError: If the name matches several players.
+    """
+    raw = query.strip()
+    if not raw:
+        raise NotFoundError("No player name given.")
+
+    if raw.isdigit():
+        person = client.person(int(raw))
+        if person is None:
+            raise NotFoundError(f"No player has MLBAM id {raw}.")
+        return person
+
+    people = client.search_people(raw)
+    if not people:
+        raise NotFoundError(
+            f"No player matches {query!r}. Check the spelling, or pass an "
+            "MLBAM id directly."
+        )
+    if len(people) == 1:
+        return people[0]
+
+    # An exact full-name match beats every partial one: searching "Will Smith"
+    # should not be ambiguous just because "Will Smithson" also exists.
+    key = normalize(raw)
+    exact = [p for p in people if normalize(p.get("fullName", "")) == key]
+    if len(exact) == 1:
+        return exact[0]
+    if exact:
+        people = exact
+
+    if prefer_active:
+        active = [p for p in people if p.get("active")]
+        if len(active) == 1:
+            return active[0]
+
+    raise AmbiguousError(
+        f"{query!r} matches {len(people)} players — rerun with a fuller name or an id:",
+        _player_candidates(people),
+    )
+
+
+def _player_candidates(people: list[dict], limit: int = 12) -> list[str]:
+    lines = []
+    for person in people[:limit]:
+        team = (person.get("currentTeam") or {}).get("name", "")
+        position = (person.get("primaryPosition") or {}).get("abbreviation", "")
+        status = "" if person.get("active") else " (retired)"
+        detail = " — ".join(part for part in (position, team) if part)
+        lines.append(f"{person.get('id')}  {person.get('fullName')}{status}"
+                     + (f"  [{detail}]" if detail else ""))
+    if len(people) > limit:
+        lines.append(f"... and {len(people) - limit} more")
+    return lines
+
+
+def player_display_team(person: dict) -> str | None:
+    """Return the club a player record is associated with, if any."""
+    team = person.get("currentTeam") or {}
+    return team.get("name")