baseballcommand 0.1.0__py3-none-any.whl

baseballcommand/output.py

@@ -0,0 +1,193 @@
+"""Terminal rendering: colors, tables, and small layout helpers.
+
+Deliberately dependency-free. Everything here degrades to plain ASCII when
+output is piped or when the user asks for no color, so ``base scores | grep``
+behaves the way a shell user expects.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+# ANSI SGR codes. Kept as raw strings rather than an enum so that disabling
+# color is a matter of swapping in empty strings.
+_CODES = {
+    "reset": "\033[0m",
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "blue": "\033[34m",
+    "magenta": "\033[35m",
+    "cyan": "\033[36m",
+    "white": "\033[37m",
+}
+
+_color_enabled = True
+
+
+def supports_color(stream=None) -> bool:
+    """Return whether ``stream`` should get ANSI escapes.
+
+    Respects the informal `NO_COLOR <https://no-color.org/>`_ convention, and
+    treats a non-TTY (a pipe, a file, CI) as "no color".
+    """
+    stream = stream or sys.stdout
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def set_color(enabled: bool | None = None) -> None:
+    """Force color on or off; pass None to auto-detect from stdout."""
+    global _color_enabled
+    _color_enabled = supports_color() if enabled is None else bool(enabled)
+
+
+def color_enabled() -> bool:
+    """Return whether output is currently being colorized."""
+    return _color_enabled
+
+
+def colorize(text: str, *styles: str) -> str:
+    """Wrap ``text`` in the named styles, or return it unchanged if color is off."""
+    if not _color_enabled or not styles:
+        return text
+    prefix = "".join(_CODES.get(style, "") for style in styles)
+    return f"{prefix}{text}{_CODES['reset']}" if prefix else text
+
+
+def visible_width(text: str) -> int:
+    """Return the printed width of ``text``, ignoring ANSI escape sequences."""
+    width = 0
+    in_escape = False
+    for char in text:
+        if in_escape:
+            # SGR sequences end with 'm'; that's all we ever emit.
+            if char.isalpha():
+                in_escape = False
+        elif char == "\033":
+            in_escape = True
+        else:
+            width += 1
+    return width
+
+
+def _pad(text: str, width: int, align: str) -> str:
+    """Pad ``text`` to ``width`` columns, measuring around any escape codes."""
+    padding = max(0, width - visible_width(text))
+    if align == "r":
+        return " " * padding + text
+    if align == "c":
+        left = padding // 2
+        return " " * left + text + " " * (padding - left)
+    return text + " " * padding
+
+
+def table(
+    headers: Sequence[str],
+    rows: Iterable[Sequence[Any]],
+    aligns: Sequence[str] | None = None,
+    indent: str = "  ",
+    gap: str = "  ",
+) -> str:
+    """Render an aligned text table.
+
+    Args:
+        headers: Column headings. Numeric columns read best right-aligned.
+        rows: Row sequences. Cells are stringified; None becomes an em dash.
+        aligns: Per-column alignment, ``"l"``, ``"r"``, or ``"c"``. Defaults to
+            left for the first column and right for the rest, which is the
+            shape almost every stat table wants.
+        indent: Prefix for every line.
+        gap: Separator between columns.
+
+    Returns:
+        The rendered table, without a trailing newline. Empty ``rows`` yields
+        an empty string so callers can test the result for emptiness.
+    """
+    rows = [list(row) for row in rows]
+    if not rows:
+        return ""
+
+    columns = max(len(headers), max(len(row) for row in rows))
+    if aligns is None:
+        aligns = ["l"] + ["r"] * (columns - 1)
+    aligns = list(aligns) + ["l"] * (columns - len(aligns))
+
+    headers = list(headers) + [""] * (columns - len(headers))
+    cells = [[_cell(value) for value in row] + [""] * (columns - len(row)) for row in rows]
+
+    widths = [visible_width(header) for header in headers]
+    for row in cells:
+        for index, value in enumerate(row):
+            widths[index] = max(widths[index], visible_width(value))
+
+    lines = [
+        indent
+        + gap.join(
+            colorize(_pad(header, widths[i], aligns[i]), "bold")
+            for i, header in enumerate(headers)
+        ).rstrip()
+    ]
+    lines.append(indent + colorize(gap.join("-" * width for width in widths), "dim"))
+    for row in cells:
+        lines.append(
+            indent
+            + gap.join(_pad(value, widths[i], aligns[i]) for i, value in enumerate(row)).rstrip()
+        )
+    return "\n".join(lines)
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return "-"
+    if isinstance(value, float):
+        return f"{value:g}"
+    return str(value)
+
+
+def heading(text: str, subtitle: str | None = None) -> str:
+    """Render a section heading, optionally with a dimmed subtitle beneath it."""
+    line = colorize(text, "bold", "cyan")
+    if subtitle:
+        line += "\n" + colorize(subtitle, "dim")
+    return line
+
+
+def key_values(pairs: Sequence[tuple], indent: str = "  ") -> str:
+    """Render ``(label, value)`` pairs as an aligned two-column block."""
+    pairs = [(label, value) for label, value in pairs if value not in (None, "")]
+    if not pairs:
+        return ""
+    width = max(len(label) for label, _ in pairs)
+    return "\n".join(
+        f"{indent}{colorize(label.ljust(width), 'dim')}  {value}" for label, value in pairs
+    )
+
+
+def warn(message: str) -> None:
+    """Print a warning to stderr so it stays out of piped stdout."""
+    print(colorize(f"warning: {message}", "yellow"), file=sys.stderr)
+
+
+def emit_json(payload: Any) -> None:
+    """Print ``payload`` as indented JSON, for ``--json``."""
+    print(json.dumps(payload, indent=2, default=str))
+
+
+def blank() -> None:
+    print()
+
+
+def paragraphs(*blocks: str) -> None:
+    """Print non-empty blocks separated by blank lines."""
+    rendered: list[str] = [block for block in blocks if block]
+    print("\n\n".join(rendered))

baseballcommand/stats.py

@@ -0,0 +1,171 @@
+"""Which stats to show, in which order, under which headings.
+
+The API returns every stat it has for a given group — 30-odd keys for hitting,
+50-odd for pitching. Dumping all of them makes an unreadable wall of numbers, so
+each group gets a curated column list in the order a box score or a baseball
+reference page would use. ``--full`` bypasses the curation and prints
+everything.
+
+Column lists are ``(heading, api_key)`` pairs. Missing keys render as ``-``
+rather than raising, because the API omits stats that don't apply to a given
+player, season, or split.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+Column = tuple[str, str]
+
+#: The three stat groups the API exposes for players and teams.
+GROUPS = ("hitting", "pitching", "fielding")
+
+HITTING_COLUMNS: list[Column] = [
+    ("G", "gamesPlayed"),
+    ("PA", "plateAppearances"),
+    ("AB", "atBats"),
+    ("R", "runs"),
+    ("H", "hits"),
+    ("2B", "doubles"),
+    ("3B", "triples"),
+    ("HR", "homeRuns"),
+    ("RBI", "rbi"),
+    ("BB", "baseOnBalls"),
+    ("SO", "strikeOuts"),
+    ("SB", "stolenBases"),
+    ("CS", "caughtStealing"),
+    ("AVG", "avg"),
+    ("OBP", "obp"),
+    ("SLG", "slg"),
+    ("OPS", "ops"),
+]
+
+PITCHING_COLUMNS: list[Column] = [
+    ("W", "wins"),
+    ("L", "losses"),
+    ("ERA", "era"),
+    ("G", "gamesPlayed"),
+    ("GS", "gamesStarted"),
+    ("CG", "completeGames"),
+    ("SHO", "shutouts"),
+    ("SV", "saves"),
+    ("HLD", "holds"),
+    ("IP", "inningsPitched"),
+    ("H", "hits"),
+    ("R", "runs"),
+    ("ER", "earnedRuns"),
+    ("HR", "homeRuns"),
+    ("BB", "baseOnBalls"),
+    ("SO", "strikeOuts"),
+    ("WHIP", "whip"),
+    ("K/9", "strikeoutsPer9Inn"),
+    ("BB/9", "walksPer9Inn"),
+]
+
+FIELDING_COLUMNS: list[Column] = [
+    ("POS", "_position"),
+    ("G", "gamesPlayed"),
+    ("GS", "gamesStarted"),
+    ("INN", "innings"),
+    ("TC", "chances"),
+    ("PO", "putOuts"),
+    ("A", "assists"),
+    ("E", "errors"),
+    ("DP", "doublePlays"),
+    ("FPCT", "fielding"),
+    ("RF/9", "rangeFactorPer9Inn"),
+]
+
+COLUMNS: dict[str, list[Column]] = {
+    "hitting": HITTING_COLUMNS,
+    "pitching": PITCHING_COLUMNS,
+    "fielding": FIELDING_COLUMNS,
+}
+
+#: Human-readable names for the curated column headings, used by
+#: ``base glossary`` and the docs.
+GLOSSARY: dict[str, str] = {
+    "G": "Games played",
+    "GS": "Games started",
+    "PA": "Plate appearances",
+    "AB": "At bats",
+    "R": "Runs scored",
+    "H": "Hits",
+    "2B": "Doubles",
+    "3B": "Triples",
+    "HR": "Home runs",
+    "RBI": "Runs batted in",
+    "BB": "Walks (bases on balls)",
+    "SO": "Strikeouts",
+    "SB": "Stolen bases",
+    "CS": "Caught stealing",
+    "AVG": "Batting average (H/AB)",
+    "OBP": "On-base percentage",
+    "SLG": "Slugging percentage (TB/AB)",
+    "OPS": "On-base plus slugging",
+    "W": "Wins",
+    "L": "Losses",
+    "ERA": "Earned run average (9 x ER/IP)",
+    "CG": "Complete games",
+    "SHO": "Shutouts",
+    "SV": "Saves",
+    "HLD": "Holds",
+    "IP": "Innings pitched",
+    "ER": "Earned runs",
+    "WHIP": "Walks plus hits per inning pitched",
+    "K/9": "Strikeouts per nine innings",
+    "BB/9": "Walks per nine innings",
+    "POS": "Primary position for the split",
+    "INN": "Innings played in the field",
+    "TC": "Total chances (PO + A + E)",
+    "PO": "Putouts",
+    "A": "Assists",
+    "E": "Errors",
+    "DP": "Double plays turned",
+    "FPCT": "Fielding percentage ((PO + A)/TC)",
+    "RF/9": "Range factor per nine innings",
+}
+
+
+def columns_for(group: str) -> list[Column]:
+    """Return the curated columns for a stat group."""
+    return COLUMNS.get(group, HITTING_COLUMNS)
+
+
+def split_row(split: dict, columns: Sequence[Column]) -> list[Any]:
+    """Extract one table row from a stat split.
+
+    Underscore-prefixed keys are synthetic: they come from the split itself
+    rather than from its ``stat`` payload.
+    """
+    stat = split.get("stat", {}) or {}
+    row: list[Any] = []
+    for _, key in columns:
+        if key == "_position":
+            row.append((stat.get("position") or {}).get("abbreviation", "-"))
+        elif key == "_season":
+            row.append(split.get("season", "-"))
+        elif key == "_team":
+            # A year-by-year split with no team is the season total for a
+            # player who changed clubs mid-year.
+            row.append((split.get("team") or {}).get("name") or "(total)")
+        else:
+            row.append(stat.get(key))
+    return row
+
+
+def headers_for(columns: Sequence[Column]) -> list[str]:
+    return [heading for heading, _ in columns]
+
+
+def full_rows(split: dict) -> list[tuple[str, Any]]:
+    """Return every stat in a split as sorted ``(key, value)`` pairs, for ``--full``."""
+    stat = split.get("stat", {}) or {}
+    rows = []
+    for key in sorted(stat):
+        value = stat[key]
+        if isinstance(value, dict):
+            value = value.get("abbreviation") or value.get("name") or value.get("displayName")
+        rows.append((key, value))
+    return rows