baseballcommand 0.1.0__py3-none-any.whl

baseballcommand/__init__.py

@@ -0,0 +1,8 @@
+"""BaseballCommand — a free, open-source baseball CLI.
+
+Scores, player stats, team stats, standings and league leaders, straight from
+the public MLB Stats API. No API key, no account, no dependencies.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

baseballcommand/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m baseballcommand`` as well as the installed ``base`` script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

baseballcommand/api.py

@@ -0,0 +1,395 @@
+"""Client for the public MLB Stats API.
+
+The API at ``statsapi.mlb.com`` needs no key and no account, which is what makes
+this tool free to run. Everything here is stdlib ``urllib`` — no request
+library, no auth, no state beyond the on-disk cache.
+
+Only :class:`StatsAPI` talks to the network. Command modules take a client and
+never build URLs themselves, so retries, caching, and error translation stay in
+one place.
+"""
+
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Iterable
+from datetime import date
+from typing import Any
+
+from . import __version__
+from .cache import TTL_STATIC, TTL_STATS, Cache
+from .errors import APIError
+
+BASE_URL = "https://statsapi.mlb.com/api"
+USER_AGENT = f"BaseballCommand/{__version__} (+https://github.com/opowell28/BaseballCommand)"
+
+#: ``sportId`` 1 is Major League Baseball. The API also carries the minors,
+#: college, and international ball under other ids.
+SPORT_MLB = 1
+
+#: League ids used when a caller asks for one league's worth of data.
+LEAGUE_AL = 103
+LEAGUE_NL = 104
+
+#: Regular season games. The API also has 'S' (spring), 'P'/'D'/'L'/'W'
+#: (postseason rounds), and 'A' (all-star).
+GAME_TYPE_REGULAR = "R"
+
+
+#: Shown when TLS verification fails, which on macOS almost always means a
+#: python.org interpreter whose root certificates were never installed.
+CERT_HELP = (
+    "TLS certificate verification failed. Your Python installation has no "
+    "usable root certificates.\n"
+    "  macOS (python.org build): run "
+    "'/Applications/Python 3.x/Install Certificates.command'\n"
+    "  any platform: 'pip install certifi' — BaseballCommand uses it "
+    "automatically when present."
+)
+
+
+def _ssl_context() -> ssl.SSLContext:
+    """Build a verifying TLS context, preferring certifi's roots if installed.
+
+    certifi is not a dependency — the tool works without it wherever the system
+    trust store is wired up. When it is present we use it, which fixes the
+    common macOS case at no cost to everyone else. Verification is never
+    disabled.
+    """
+    try:
+        import certifi  # noqa: PLC0415 — optional, imported only if installed
+
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        return ssl.create_default_context()
+
+
+def current_season(today: date | None = None) -> int:
+    """Return the season a bare ``base`` invocation should default to.
+
+    January and February have no baseball, and stat lines for the new year are
+    empty until Opening Day in late March. During those months the season the
+    user almost certainly means is the one that just finished.
+    """
+    today = today or date.today()
+    return today.year if today.month >= 3 else today.year - 1
+
+
+class StatsAPI:
+    """A thin, cached wrapper over the MLB Stats API.
+
+    Args:
+        cache: Response cache. A disabled :class:`~.cache.Cache` turns every
+            request into a live fetch.
+        timeout: Per-request socket timeout, in seconds.
+        retries: Extra attempts after the first failure. Retries apply to
+            timeouts, connection errors, and 5xx responses — not to 4xx, which
+            will fail identically no matter how often we ask.
+    """
+
+    def __init__(
+        self,
+        cache: Cache | None = None,
+        timeout: float = 15.0,
+        retries: int = 2,
+    ):
+        self.cache = cache if cache is not None else Cache()
+        self.timeout = timeout
+        self.retries = retries
+        self.ssl_context = _ssl_context()
+
+    # ------------------------------------------------------------------
+    # Transport
+    # ------------------------------------------------------------------
+
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        ttl: int = TTL_STATS,
+        version: str = "v1",
+    ) -> Any:
+        """GET ``path`` and return the decoded JSON body.
+
+        Args:
+            path: Path below the version segment, e.g. ``"schedule"``.
+            params: Query parameters. ``None`` values are dropped; lists and
+                tuples are joined with commas, which is how the API expects
+                multi-valued parameters such as ``leagueId=103,104``.
+            ttl: Seconds a cached copy stays fresh. Pass 0 to bypass the cache.
+            version: API version segment (``v1``, or ``v1.1`` for game feeds).
+
+        Raises:
+            APIError: On network failure or a non-2xx response.
+        """
+        url = self._build_url(path, params, version)
+
+        cached = self.cache.get(url, ttl)
+        if cached is not None:
+            return cached
+
+        payload = self._fetch(url)
+        self.cache.set(url, payload)
+        return payload
+
+    @staticmethod
+    def _build_url(path: str, params: dict[str, Any] | None, version: str) -> str:
+        query: list[tuple] = []
+        for key, value in (params or {}).items():
+            if value is None:
+                continue
+            if isinstance(value, (list, tuple, set)):
+                value = ",".join(str(v) for v in value)
+            elif isinstance(value, bool):
+                value = "true" if value else "false"
+            query.append((key, str(value)))
+        url = f"{BASE_URL}/{version}/{path.lstrip('/')}"
+        if query:
+            url = f"{url}?{urllib.parse.urlencode(query)}"
+        return url
+
+    def _fetch(self, url: str) -> Any:
+        request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+        last_error: Exception | None = None
+
+        for attempt in range(self.retries + 1):
+            try:
+                with urllib.request.urlopen(
+                    request, timeout=self.timeout, context=self.ssl_context
+                ) as response:
+                    return json.loads(response.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                if exc.code < 500 or attempt == self.retries:
+                    raise APIError(
+                        f"MLB Stats API returned HTTP {exc.code} ({exc.reason}) for {url}"
+                    ) from exc
+                last_error = exc
+            except urllib.error.URLError as exc:
+                # A missing trust store fails identically on every retry, and
+                # the fix is a local one, so report it immediately.
+                if isinstance(exc.reason, ssl.SSLCertVerificationError):
+                    raise APIError(CERT_HELP) from exc
+                if attempt == self.retries:
+                    raise APIError(
+                        f"Could not reach the MLB Stats API: {exc.reason}. "
+                        "Check your network connection."
+                    ) from exc
+                last_error = exc
+            except json.JSONDecodeError as exc:
+                raise APIError(f"MLB Stats API returned malformed JSON for {url}") from exc
+            except TimeoutError as exc:
+                if attempt == self.retries:
+                    raise APIError(
+                        f"Request to the MLB Stats API timed out after {self.timeout:g}s"
+                    ) from exc
+                last_error = exc
+
+            # Back off before retrying: 0.5s, then 1.0s.
+            time.sleep(0.5 * (attempt + 1))
+
+        raise APIError(f"Request to the MLB Stats API failed: {last_error}")
+
+    # ------------------------------------------------------------------
+    # Endpoints
+    # ------------------------------------------------------------------
+
+    def schedule(
+        self,
+        game_date: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        team_id: int | None = None,
+        ttl: int = 60,
+    ) -> dict:
+        """Return the schedule for a date or a date range, with line scores."""
+        return self.get(
+            "schedule",
+            {
+                "sportId": SPORT_MLB,
+                "date": game_date,
+                "startDate": start_date,
+                "endDate": end_date,
+                "teamId": team_id,
+                "hydrate": "linescore,probablePitcher,team",
+            },
+            ttl=ttl,
+        )
+
+    def teams(self, season: int | None = None) -> list[dict]:
+        """Return all 30 MLB clubs for a season."""
+        payload = self.get(
+            "teams",
+            {"sportId": SPORT_MLB, "season": season},
+            ttl=TTL_STATIC,
+        )
+        return payload.get("teams", [])
+
+    def search_people(self, name: str) -> list[dict]:
+        """Search players by name, active and historical."""
+        payload = self.get(
+            "people/search",
+            {"names": name, "hydrate": "currentTeam", "limit": 50},
+            ttl=TTL_STATIC,
+        )
+        return payload.get("people", [])
+
+    def person(self, player_id: int) -> dict | None:
+        """Return one player's biographical record, or None if the id is unknown."""
+        payload = self.get(
+            f"people/{player_id}",
+            {"hydrate": "currentTeam"},
+            ttl=TTL_STATIC,
+        )
+        people = payload.get("people", [])
+        return people[0] if people else None
+
+    def player_stats(
+        self,
+        player_id: int,
+        group: str,
+        stat_type: str = "season",
+        season: int | None = None,
+        game_type: str = GAME_TYPE_REGULAR,
+    ) -> list[dict]:
+        """Return stat splits for a player.
+
+        Args:
+            group: ``hitting``, ``pitching``, or ``fielding``.
+            stat_type: ``season``, ``career``, or ``yearByYear``.
+            season: Only meaningful for ``season`` splits.
+        """
+        payload = self.get(
+            f"people/{player_id}/stats",
+            {
+                "stats": stat_type,
+                "group": group,
+                "season": season if stat_type == "season" else None,
+                "gameType": game_type,
+                "sportId": SPORT_MLB,
+            },
+            ttl=TTL_STATS,
+        )
+        return _splits(payload)
+
+    def team_stats(
+        self,
+        team_id: int,
+        group: str,
+        season: int | None = None,
+        stat_type: str = "season",
+    ) -> list[dict]:
+        """Return team-level stat splits for a season."""
+        payload = self.get(
+            f"teams/{team_id}/stats",
+            {
+                "stats": stat_type,
+                "group": group,
+                "season": season,
+                "sportId": SPORT_MLB,
+            },
+            ttl=TTL_STATS,
+        )
+        return _splits(payload)
+
+    def standings(
+        self,
+        season: int | None = None,
+        league_ids: Iterable[int] = (LEAGUE_AL, LEAGUE_NL),
+        standings_type: str = "regularSeason",
+    ) -> list[dict]:
+        """Return division records, one entry per division."""
+        payload = self.get(
+            "standings",
+            {
+                "leagueId": list(league_ids),
+                "season": season,
+                "standingsTypes": standings_type,
+                "hydrate": "team",
+            },
+            ttl=TTL_STATS,
+        )
+        return payload.get("records", [])
+
+    def leaders(
+        self,
+        category: str,
+        season: int | None = None,
+        group: str | None = None,
+        league_id: int | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        """Return league leader groups for a statistical category."""
+        payload = self.get(
+            "stats/leaders",
+            {
+                "leaderCategories": category,
+                "season": season,
+                "statGroup": group,
+                "leagueId": league_id,
+                "sportId": SPORT_MLB,
+                "limit": limit,
+            },
+            ttl=TTL_STATS,
+        )
+        return payload.get("leagueLeaders", [])
+
+    def leader_categories(self) -> list[str]:
+        """Return every category name accepted by :meth:`leaders`."""
+        payload = self.get("leagueLeaderTypes", ttl=TTL_STATIC)
+        # This endpoint returns a bare list rather than the usual envelope.
+        items = payload if isinstance(payload, list) else payload.get("leagueLeaderTypes", [])
+        return [item["displayName"] for item in items if "displayName" in item]
+
+    def roster(
+        self,
+        team_id: int,
+        season: int | None = None,
+        roster_type: str = "active",
+        stat_groups: Iterable[str] = (),
+    ) -> list[dict]:
+        """Return a team's roster.
+
+        Args:
+            roster_type: ``active``, ``40Man``, ``fullSeason``, or ``depthChart``.
+            stat_groups: Stat groups to hydrate onto each player. The API does
+                this server-side, so a whole team's stat lines cost one request
+                instead of one per player. The groups must be named explicitly:
+                left to itself the API returns only the one matching each
+                player's position, so fielding never appears.
+        """
+        hydrate = None
+        groups = list(stat_groups)
+        if groups:
+            season_arg = season or current_season()
+            hydrate = (
+                f"person(stats(type=season,season={season_arg},group=[{','.join(groups)}]))"
+            )
+        payload = self.get(
+            f"teams/{team_id}/roster",
+            {"season": season, "rosterType": roster_type, "hydrate": hydrate},
+            ttl=TTL_STATS,
+        )
+        return payload.get("roster", [])
+
+
+def _splits(payload: dict) -> list[dict]:
+    """Flatten the API's ``stats -> splits`` envelope into a list of splits.
+
+    Each split is annotated with the group and stat type it came from so that a
+    caller holding a mixed list can still tell hitting from pitching.
+    """
+    results: list[dict] = []
+    for block in payload.get("stats", []):
+        group = block.get("group", {}).get("displayName")
+        stat_type = block.get("type", {}).get("displayName")
+        for split in block.get("splits", []):
+            split = dict(split)
+            split["_group"] = group
+            split["_type"] = stat_type
+            results.append(split)
+    return results

baseballcommand/cache.py

@@ -0,0 +1,115 @@
+"""A small on-disk response cache.
+
+The MLB Stats API is free and unauthenticated, which makes it easy to hammer by
+accident: a single ``base standings`` run resolves 30 teams, and a shell loop can
+issue hundreds of identical requests a minute. Caching responses on disk keeps
+repeated runs fast and keeps us from being a bad citizen.
+
+Entries are plain JSON files under the user cache directory, keyed by a hash of
+the request URL. Each file records the time it was written; reads past the
+caller-supplied TTL are treated as misses. Anything unreadable or corrupt is
+also a miss, so a damaged cache degrades to "slower", never to "broken".
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+# TTLs in seconds, named so call sites read as intent rather than magic numbers.
+TTL_LIVE = 30  # in-progress games; short enough to feel live
+TTL_SCHEDULE = 300  # a day's schedule once games are final
+TTL_STATS = 3600  # season/career stat lines
+TTL_STATIC = 86400  # team lists, leader categories, biographical data
+
+
+def default_cache_dir() -> Path:
+    """Return the directory used for cached responses.
+
+    Honors ``BASEBALLCOMMAND_CACHE_DIR`` first, then ``XDG_CACHE_HOME``, then
+    falls back to ``~/.cache``.
+    """
+    override = os.environ.get("BASEBALLCOMMAND_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".cache"
+    return base / "baseballcommand"
+
+
+class Cache:
+    """A TTL cache for JSON API responses.
+
+    Args:
+        directory: Where to store entries. Defaults to :func:`default_cache_dir`.
+        enabled: When false, every read misses and every write is dropped. This
+            is how ``--no-cache`` is implemented, so callers need no branches.
+    """
+
+    def __init__(self, directory: Path | None = None, enabled: bool = True):
+        self.directory = Path(directory) if directory else default_cache_dir()
+        self.enabled = enabled
+
+    def _path_for(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        # Shard by the first two hex characters so no single directory ends up
+        # with thousands of entries.
+        return self.directory / digest[:2] / f"{digest}.json"
+
+    def get(self, key: str, ttl: int) -> Any | None:
+        """Return the cached payload for ``key``, or None if absent or stale."""
+        if not self.enabled or ttl <= 0:
+            return None
+        path = self._path_for(key)
+        try:
+            with path.open("r", encoding="utf-8") as handle:
+                entry = json.load(handle)
+            if time.time() - entry["stored_at"] > ttl:
+                return None
+            return entry["payload"]
+        except (OSError, ValueError, KeyError, TypeError):
+            # Missing, unreadable, or corrupt: all just cache misses.
+            return None
+
+    def set(self, key: str, payload: Any) -> None:
+        """Store ``payload`` under ``key``. Failures are silently ignored."""
+        if not self.enabled:
+            return
+        path = self._path_for(key)
+        entry = {"stored_at": time.time(), "key": key, "payload": payload}
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            # Write to a temp file in the same directory, then rename, so a
+            # concurrent reader never sees a half-written entry.
+            tmp = path.with_suffix(".tmp")
+            with tmp.open("w", encoding="utf-8") as handle:
+                json.dump(entry, handle)
+            os.replace(tmp, path)
+        except OSError:
+            pass
+
+    def clear(self) -> int:
+        """Delete every cached entry. Returns the number of files removed."""
+        if not self.directory.exists():
+            return 0
+        count = sum(1 for _ in self.directory.rglob("*.json"))
+        shutil.rmtree(self.directory, ignore_errors=True)
+        return count
+
+    def stats(self) -> dict:
+        """Return ``{'entries': int, 'bytes': int, 'path': str}`` for the cache."""
+        entries = 0
+        total = 0
+        if self.directory.exists():
+            for path in self.directory.rglob("*.json"):
+                entries += 1
+                try:
+                    total += path.stat().st_size
+                except OSError:
+                    pass
+        return {"entries": entries, "bytes": total, "path": str(self.directory)}

baseballcommand/cli.py

@@ -0,0 +1,121 @@
+"""Argument parsing and dispatch for the ``base`` command."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+
+from . import __version__, commands, output
+from .api import StatsAPI
+from .cache import Cache
+from .errors import BaseballCommandError, UsageError
+
+EPILOG = """\
+examples:
+  base scores                        today's games
+  base scores yesterday -l           yesterday's games with line scores
+  base player "Aaron Judge"          this season's line for one player
+  base player Ohtani --years         every season a player has played
+  base team NYY                      a club's record and season totals
+  base standings --league al         American League standings
+  base leaders hr -n 5               the season's top five home run hitters
+  base roster LAD --stats --sort HR  a roster sorted by home runs
+  base compare Judge Ohtani          two players side by side
+
+Data comes from the free public MLB Stats API. No key or account is needed.
+"""
+
+
+@dataclass
+class Context:
+    """Everything a command handler needs beyond its own arguments."""
+
+    client: StatsAPI
+    json: bool = False
+
+    @property
+    def live_ttl(self) -> int:
+        """Cache lifetime for schedule data.
+
+        Scores change while you watch, so they get a much shorter TTL than
+        season stats — short enough to feel live, long enough that a watch loop
+        doesn't turn into a request per second.
+        """
+        return 30 if self.client.cache.enabled else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="base",
+        description="BaseballCommand — baseball scores and statistics in your terminal.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=f"BaseballCommand {__version__}"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="print raw JSON instead of formatted tables"
+    )
+    parser.add_argument("--no-color", action="store_true", help="disable ANSI color output")
+    parser.add_argument(
+        "--no-cache", action="store_true", help="bypass the cache and always fetch fresh data"
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=15.0,
+        metavar="SECONDS",
+        help="network timeout per request (default: 15)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    for module in commands.MODULES:
+        module.register(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point. Returns a process exit status.
+
+    Expected failures print a one-line message and return 1; unexpected ones
+    keep their traceback, because those are bugs worth reporting.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Color is decided before anything prints, and --json always means clean,
+    # parseable output with no escape codes.
+    output.set_color(False if (args.no_color or args.json) else None)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    client = StatsAPI(cache=Cache(enabled=not args.no_cache), timeout=args.timeout)
+    ctx = Context(client=client, json=args.json)
+
+    try:
+        return args.func(args, ctx) or 0
+    except UsageError as exc:
+        print(f"base: {exc}", file=sys.stderr)
+        return 2
+    except BaseballCommandError as exc:
+        print(f"base: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(file=sys.stderr)
+        return 130
+    except BrokenPipeError:
+        # Happens routinely under `base ... | head`. Exit quietly rather than
+        # letting Python print an ignored-exception warning at shutdown.
+        try:
+            sys.stdout.close()
+        except OSError:
+            pass
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

baseballcommand/commands/__init__.py

@@ -0,0 +1,38 @@
+"""Command implementations.
+
+Each module here registers one subcommand. A module exposes ``register(sub)``,
+which builds its argparse parser and attaches its handler via
+``set_defaults(func=...)``. The handler signature is ``run(args, ctx)`` where
+``ctx`` is a :class:`~baseballcommand.cli.Context`.
+
+Adding a command means writing a module and appending it to ``MODULES``.
+"""
+
+from . import (  # noqa: F401
+    cache,
+    compare,
+    glossary,
+    leaders,
+    player,
+    roster,
+    scores,
+    standings,
+    team,
+    teams,
+)
+
+#: Registration order determines the order subcommands appear in ``base --help``.
+MODULES = (
+    scores,
+    player,
+    team,
+    standings,
+    leaders,
+    roster,
+    compare,
+    teams,
+    glossary,
+    cache,
+)
+
+__all__ = ["MODULES"]