mound 0.1.0__py3-none-any.whl

mound/__init__.py

@@ -0,0 +1,14 @@
+"""Mound: a CLI and Python toolkit for MLB pitch-level data."""
+
+from mound.pitches import PitchCollection, Pitcher
+from mound.players import AmbiguousPlayerError, Player, PlayerNotFoundError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Pitcher",
+    "PitchCollection",
+    "Player",
+    "PlayerNotFoundError",
+    "AmbiguousPlayerError",
+]

mound/analysis.py

@@ -0,0 +1,72 @@
+"""Pitch usage and outcome calculations.
+
+Kept intentionally small for the prototype -- pitch mix and strike rate --
+but structured so additional Statcast metrics (whiff rate, chase rate, exit
+velocity, etc.) can be added as more functions over the same
+:class:`~mound.pitches.PitchCollection` shape.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from mound.pitches import PitchCollection
+
+
+def pitch_mix(collection: PitchCollection) -> pd.Series:
+    """Percentage of pitches thrown, by pitch type, sorted descending.
+
+        >>> roki.pitches(last=4).pitch_mix()
+        splitter               31.2
+        four-seam fastball     28.4
+        slider                 19.1
+        ...
+    """
+    df = collection.to_frame()
+    if df.empty:
+        return pd.Series(dtype=float, name="pitch_mix")
+
+    counts = df["pitch_type"].value_counts()
+    pct = (counts / counts.sum() * 100).round(1)
+    pct.name = "pitch_mix"
+    pct.index.name = "pitch_type"
+    return pct
+
+
+def strike_rate(collection: PitchCollection, by_pitch_type: bool = False) -> float | pd.Series:
+    """Strike rate (percentage of pitches that were strikes).
+
+    With ``by_pitch_type=True``, returns a :class:`pandas.Series` broken out
+    per pitch type instead of a single overall rate.
+    """
+    df = collection.to_frame()
+    if df.empty:
+        return pd.Series(dtype=float, name="strike_rate") if by_pitch_type else float("nan")
+
+    if by_pitch_type:
+        rates = df.groupby("pitch_type")["is_strike"].mean() * 100
+        rates = rates.round(1).sort_values(ascending=False)
+        rates.name = "strike_rate"
+        return rates
+
+    return round(df["is_strike"].mean() * 100, 1)
+
+
+def usage_rate(collection: PitchCollection, by: str = "game_date") -> pd.DataFrame:
+    """Pitch usage percentage by pitch type, grouped by ``by`` (e.g. per game or date).
+
+    Useful for comparing how a pitch's usage has changed across outings,
+    e.g. ``roki.pitches(last=8).usage_rate(by="game_date")``.
+    """
+    df = collection.to_frame()
+    if df.empty:
+        return pd.DataFrame()
+
+    counts = df.groupby([by, "pitch_type"]).size().rename("count")
+    totals = df.groupby(by).size().rename("total")
+    result = counts.reset_index().merge(totals.reset_index(), on=by)
+    result["usage_rate"] = (result["count"] / result["total"] * 100).round(1)
+    return result.pivot(index=by, columns="pitch_type", values="usage_rate").fillna(0.0)

mound/cli.py

@@ -0,0 +1,182 @@
+"""Mound's command-line interface.
+
+    mound search "Roki Sasaki"
+    mound pitches "Roki Sasaki" --last 4 --pitch splitter
+    mound mix "Roki Sasaki" --last 4
+    mound results "Roki Sasaki" --last 4 --pitch splitter
+    mound zone "Roki Sasaki" --pitch splitter --last 4 --out zone.png
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+import typer
+
+from mound.pitches import PitchCollection, Pitcher
+from mound.players import AmbiguousPlayerError, PlayerNotFoundError
+
+app = typer.Typer(
+    name="mound",
+    help="Retrieve, analyze and visualize MLB pitch-level data.",
+    no_args_is_help=True,
+)
+
+
+def _fail(message: str) -> None:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+def _get_pitches(
+    name: str,
+    last: int | None,
+    since: str | None,
+    until: str | None,
+    game: int | None,
+    pitch: str | None,
+) -> PitchCollection:
+    try:
+        pitcher = Pitcher(name)
+    except PlayerNotFoundError as exc:
+        _fail(str(exc))
+    except AmbiguousPlayerError as exc:
+        _fail(str(exc))
+
+    try:
+        return pitcher.pitches(last=last, since=since, until=until, game=game, pitch_type=pitch)
+    except Exception as exc:  # surface retrieval failures without a traceback
+        _fail(f"Failed to retrieve pitches for {pitcher.name}: {exc}")
+
+
+@app.command()
+def search(
+    name: str = typer.Argument(..., help="Player name to search for, e.g. 'Roki Sasaki'"),
+) -> None:
+    """Find a player's MLB ID and basic info by name."""
+    from mound.players import search_players
+
+    matches = search_players(name)
+    if not matches:
+        _fail(f"No player found matching '{name}'")
+
+    for player in matches:
+        role = player.primary_position or "?"
+        team = player.team_name or "no current team"
+        typer.echo(f"{player.id}\t{player.full_name}\t{role}\t{team}")
+
+
+@app.command()
+def pitches(
+    name: str = typer.Argument(..., help="Pitcher name or MLB player ID"),
+    last: int | None = typer.Option(None, "--last", help="Most recent N appearances"),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    until: str | None = typer.Option(None, "--until", help="End date (YYYY-MM-DD)"),
+    game: int | None = typer.Option(None, "--game", help="A specific MLB game_pk"),
+    pitch: str | None = typer.Option(None, "--pitch", help="Pitch type, e.g. 'splitter'"),
+    export_path: str | None = typer.Option(None, "--export", help="Path to export results to"),
+    export_format: str | None = typer.Option(
+        None, "--format", help="Export format (csv/json/parquet); inferred from --export if omitted"
+    ),
+    limit: int | None = typer.Option(20, "--limit", help="Rows to print (use 0 for all)"),
+) -> None:
+    """Retrieve individual pitch records for a pitcher."""
+    collection = _get_pitches(name, last, since, until, game, pitch)
+
+    if collection.empty:
+        typer.echo("No pitches found for the given filters.")
+    else:
+        df = collection.to_frame()
+        display_cols = [
+            "game_date",
+            "inning",
+            "pitch_type",
+            "velocity",
+            "pitch_call",
+            "at_bat_result",
+        ]
+        display_df = df[display_cols]
+        if limit:
+            display_df = display_df.head(limit)
+        typer.echo(display_df.to_string(index=False))
+        typer.echo(f"\n{len(collection)} pitch(es) total.")
+
+    if export_path:
+        collection.export(export_path, format=export_format)
+        typer.echo(f"Exported {len(collection)} pitch(es) to {export_path}")
+
+
+@app.command()
+def mix(
+    name: str = typer.Argument(..., help="Pitcher name or MLB player ID"),
+    last: int | None = typer.Option(None, "--last", help="Most recent N appearances"),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    until: str | None = typer.Option(None, "--until", help="End date (YYYY-MM-DD)"),
+    game: int | None = typer.Option(None, "--game", help="A specific MLB game_pk"),
+    pitch: str | None = typer.Option(None, "--pitch", help="Pitch type, e.g. 'splitter'"),
+) -> None:
+    """Calculate a pitcher's pitch mix (usage percentage by pitch type)."""
+    collection = _get_pitches(name, last, since, until, game, pitch)
+
+    if collection.empty:
+        typer.echo("No pitches found for the given filters.")
+        return
+
+    mix_series = collection.pitch_mix()
+    for pitch_type, pct in mix_series.items():
+        typer.echo(f"{pitch_type:<24} {pct:>5.1f}%")
+
+
+@app.command()
+def results(
+    name: str = typer.Argument(..., help="Pitcher name or MLB player ID"),
+    last: int | None = typer.Option(None, "--last", help="Most recent N appearances"),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    until: str | None = typer.Option(None, "--until", help="End date (YYYY-MM-DD)"),
+    game: int | None = typer.Option(None, "--game", help="A specific MLB game_pk"),
+    pitch: str | None = typer.Option(None, "--pitch", help="Pitch type, e.g. 'splitter'"),
+) -> None:
+    """Show pitch counts, strikes/balls and strike rate, broken out by pitch type."""
+    collection = _get_pitches(name, last, since, until, game, pitch)
+
+    if collection.empty:
+        typer.echo("No pitches found for the given filters.")
+        return
+
+    df = collection.to_frame()
+    summary = df.groupby("pitch_type").agg(
+        pitches=("pitch_type", "count"),
+        strikes=("is_strike", "sum"),
+    )
+    summary["balls"] = summary["pitches"] - summary["strikes"]
+    summary["strike_rate"] = (summary["strikes"] / summary["pitches"] * 100).round(1)
+    summary["usage_rate"] = (summary["pitches"] / summary["pitches"].sum() * 100).round(1)
+    summary = summary.sort_values("pitches", ascending=False)
+    summary = summary[["pitches", "strikes", "balls", "strike_rate", "usage_rate"]]
+
+    with pd.option_context("display.float_format", "{:.1f}".format):
+        typer.echo(summary.to_string())
+
+
+@app.command()
+def zone(
+    name: str = typer.Argument(..., help="Pitcher name or MLB player ID"),
+    last: int | None = typer.Option(None, "--last", help="Most recent N appearances"),
+    since: str | None = typer.Option(None, "--since", help="Start date (YYYY-MM-DD)"),
+    until: str | None = typer.Option(None, "--until", help="End date (YYYY-MM-DD)"),
+    game: int | None = typer.Option(None, "--game", help="A specific MLB game_pk"),
+    pitch: str | None = typer.Option(None, "--pitch", help="Pitch type, e.g. 'splitter'"),
+    kind: str = typer.Option("scatter", "--kind", help="'scatter' or 'heatmap'"),
+    out: str = typer.Option("zone.png", "--out", help="Output image path"),
+) -> None:
+    """Plot pitch locations against a theoretical strike zone."""
+    collection = _get_pitches(name, last, since, until, game, pitch)
+
+    if collection.empty:
+        _fail("No pitches found for the given filters.")
+
+    collection.plot_zone(kind=kind, out=out)
+    typer.echo(f"Saved plot of {len(collection)} pitch(es) to {out}")
+
+
+if __name__ == "__main__":
+    app()

mound/config.py

@@ -0,0 +1,28 @@
+"""Shared constants: API base URLs, headers and defaults."""
+
+from __future__ import annotations
+
+STATSAPI_BASE = "https://statsapi.mlb.com/api"
+STATSAPI_V1 = f"{STATSAPI_BASE}/v1"
+
+SAVANT_BASE = "https://baseballsavant.mlb.com"
+SAVANT_GAMEFEED_URL = f"{SAVANT_BASE}/gf"
+
+# MLB's Stats API groups all affiliated leagues under sportId=1 for MLB itself.
+MLB_SPORT_ID = 1
+
+DEFAULT_SEASON_START_MONTH = 3  # spring training/season generally begins in March
+
+USER_AGENT = "mound/0.1 (+https://github.com/stiles/mound; personal project)"
+
+DEFAULT_HEADERS = {
+    "User-Agent": USER_AGENT,
+    "Accept": "application/json",
+    "Referer": "https://www.mlb.com/",
+}
+
+# Reasonable network defaults for a courteous client against unofficial endpoints.
+REQUEST_TIMEOUT = 15
+RETRY_TOTAL = 4
+RETRY_BACKOFF_FACTOR = 1.5
+RETRY_STATUS_FORCELIST = (429, 500, 502, 503, 504)

mound/export.py

@@ -0,0 +1,96 @@
+"""Export pitch data to disk.
+
+Serialization (turning a :class:`~mound.pitches.PitchCollection` into
+CSV/JSON/Parquet bytes) is kept separate from *where* those bytes are
+written. Today that's always :class:`LocalStorage`, but the split means a
+future ``S3Storage`` can be dropped in without touching the format logic or
+the core data model.
+"""
+
+from __future__ import annotations
+
+import io
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mound.pitches import PitchCollection
+
+SUPPORTED_FORMATS = ("csv", "json", "parquet")
+
+
+class Storage(ABC):
+    """Destination for exported pitch data."""
+
+    @abstractmethod
+    def write(self, path: str, data: bytes) -> None:
+        """Persist ``data`` at ``path``."""
+
+
+class LocalStorage(Storage):
+    """Write exported data to the local filesystem, creating parent directories."""
+
+    def write(self, path: str, data: bytes) -> None:
+        file_path = Path(path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_bytes(data)
+
+
+_default_storage = LocalStorage()
+
+
+def _resolve_storage(storage: Storage | None) -> Storage:
+    return storage if storage is not None else _default_storage
+
+
+def to_csv(
+    collection: PitchCollection, path: str, storage: Storage | None = None, **kwargs
+) -> None:
+    """Export pitches to CSV."""
+    data = collection.to_frame().to_csv(index=False, **kwargs).encode("utf-8")
+    _resolve_storage(storage).write(path, data)
+
+
+def to_json(
+    collection: PitchCollection, path: str, storage: Storage | None = None, **kwargs
+) -> None:
+    """Export pitches to JSON (one record per pitch)."""
+    kwargs.setdefault("orient", "records")
+    kwargs.setdefault("indent", 2)
+    kwargs.setdefault("date_format", "iso")
+    data = collection.to_frame().to_json(**kwargs).encode("utf-8")
+    _resolve_storage(storage).write(path, data)
+
+
+def to_parquet(
+    collection: PitchCollection, path: str, storage: Storage | None = None, **kwargs
+) -> None:
+    """Export pitches to Parquet. Requires the optional `pyarrow` dependency."""
+    try:
+        import pyarrow  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "Parquet export requires pyarrow. Install it with: pip install 'mound[parquet]'"
+        ) from exc
+
+    buffer = io.BytesIO()
+    collection.to_frame().to_parquet(buffer, engine="pyarrow", **kwargs)
+    _resolve_storage(storage).write(path, buffer.getvalue())
+
+
+_FORMAT_HANDLERS = {"csv": to_csv, "json": to_json, "parquet": to_parquet}
+
+
+def export(
+    collection: PitchCollection,
+    path: str,
+    format: str | None = None,
+    storage: Storage | None = None,
+) -> None:
+    """Export pitches, inferring the format from ``path``'s suffix if not given."""
+    fmt = format or Path(path).suffix.lstrip(".").lower()
+    handler = _FORMAT_HANDLERS.get(fmt)
+    if handler is None:
+        raise ValueError(f"Unsupported format: {fmt!r} (expected one of {SUPPORTED_FORMATS})")
+    handler(collection, path, storage=storage)

mound/http.py

@@ -0,0 +1,41 @@
+"""Shared HTTP session used by all Mound API clients.
+
+Centralizing the session lets every module benefit from the same retry
+policy, headers and timeout defaults without duplicating boilerplate.
+"""
+
+from __future__ import annotations
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from mound import config
+
+_session: requests.Session | None = None
+
+
+def get_session() -> requests.Session:
+    """Return a shared, retry-configured requests session (created lazily)."""
+    global _session
+    if _session is None:
+        session = requests.Session()
+        session.headers.update(config.DEFAULT_HEADERS)
+        retry = Retry(
+            total=config.RETRY_TOTAL,
+            backoff_factor=config.RETRY_BACKOFF_FACTOR,
+            status_forcelist=config.RETRY_STATUS_FORCELIST,
+            allowed_methods=("GET",),
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+        _session = session
+    return _session
+
+
+def get_json(url: str, params: dict | None = None) -> dict:
+    """GET a URL and return the parsed JSON body, raising on HTTP errors."""
+    response = get_session().get(url, params=params, timeout=config.REQUEST_TIMEOUT)
+    response.raise_for_status()
+    return response.json()

mound/models.py

@@ -0,0 +1,192 @@
+"""The normalized ``Pitch`` record and pitch-type vocabulary.
+
+Baseball Savant's raw ``/gf`` payload uses short codes (``FF``, ``FS``, ...)
+and inconsistent field names. This module defines the flat schema Mound
+normalizes every pitch into, plus the vocabulary that lets users filter by
+familiar names like ``"splitter"`` instead of memorizing Statcast codes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+from mound.zone import is_in_zone
+
+# Statcast pitch-type code -> canonical human-readable name.
+PITCH_TYPE_NAMES: dict[str, str] = {
+    "FF": "four-seam fastball",
+    "FT": "two-seam fastball",
+    "SI": "sinker",
+    "FC": "cutter",
+    "SL": "slider",
+    "ST": "sweeper",
+    "SV": "slurve",
+    "CU": "curveball",
+    "KC": "knuckle curve",
+    "CS": "slow curve",
+    "CH": "changeup",
+    "FS": "splitter",
+    "FO": "forkball",
+    "SC": "screwball",
+    "KN": "knuckleball",
+    "EP": "eephus",
+    "PO": "pitchout",
+    "IN": "intentional ball",
+    "UN": "unknown",
+    "AB": "automatic ball",
+}
+
+# Common aliases users might type, mapped to the Statcast code they resolve
+# to. Keys are matched case-insensitively with spaces/hyphens/underscores
+# collapsed (see `normalize_pitch_type`).
+PITCH_TYPE_ALIASES: dict[str, str] = {
+    "fastball": "FF",
+    "four seam": "FF",
+    "four seam fastball": "FF",
+    "4 seam": "FF",
+    "two seam": "FT",
+    "two seam fastball": "FT",
+    "sinker": "SI",
+    "cutter": "FC",
+    "cut fastball": "FC",
+    "slider": "SL",
+    "sweeper": "ST",
+    "sweeping slider": "ST",
+    "slurve": "SV",
+    "curveball": "CU",
+    "curve": "CU",
+    "knuckle curve": "KC",
+    "knuckle curveball": "KC",
+    "slow curve": "CS",
+    "changeup": "CH",
+    "change up": "CH",
+    "splitter": "FS",
+    "split finger": "FS",
+    "split finger fastball": "FS",
+    "forkball": "FO",
+    "screwball": "SC",
+    "knuckleball": "KN",
+    "knuckler": "KN",
+    "eephus": "EP",
+}
+
+
+def _normalize_key(text: str) -> str:
+    return " ".join(text.strip().lower().replace("-", " ").replace("_", " ").split())
+
+
+def normalize_pitch_type(pitch_type: str) -> str | None:
+    """Resolve a user-supplied pitch type (name, alias or code) to a Statcast code.
+
+    Returns ``None`` if the input doesn't match anything known. Matching is
+    case-insensitive and tolerant of hyphens/underscores/extra whitespace,
+    e.g. ``"Four-Seam"``, ``"four_seam"`` and ``"FF"`` all resolve to ``"FF"``.
+    """
+    if not pitch_type:
+        return None
+
+    code = pitch_type.strip().upper()
+    if code in PITCH_TYPE_NAMES:
+        return code
+
+    key = _normalize_key(pitch_type)
+    if key in PITCH_TYPE_ALIASES:
+        return PITCH_TYPE_ALIASES[key]
+
+    for statcast_code, name in PITCH_TYPE_NAMES.items():
+        if _normalize_key(name) == key:
+            return statcast_code
+
+    return None
+
+
+@dataclass
+class Pitch:
+    """A single, normalized pitch."""
+
+    game_pk: int
+    game_date: str
+    pitch_id: str | None
+    at_bat_number: int | None
+    pitch_number: int | None
+    inning: int | None
+    half_inning: str | None
+    pitcher_id: int
+    pitcher_name: str | None
+    batter_id: int | None
+    batter_name: str | None
+    pitch_type_code: str | None
+    pitch_type: str | None
+    velocity: float | None
+    plate_x: float | None
+    plate_z: float | None
+    sz_top: float | None
+    sz_bot: float | None
+    in_zone: bool | None
+    balls: int | None
+    strikes: int | None
+    pitch_call: str | None
+    call_description: str | None
+    is_strike: bool | None
+    at_bat_result: str | None
+    description: str | None
+
+    @classmethod
+    def field_names(cls) -> list[str]:
+        return [f.name for f in fields(cls)]
+
+
+# Savant `pitch_call` values that count as a strike for strike-rate purposes.
+# Everything else (ball, hit-by-pitch, etc.) counts as not-a-strike.
+STRIKE_CALLS = {
+    "called_strike",
+    "swinging_strike",
+    "swinging_strike_blocked",
+    "foul",
+    "foul_tip",
+    "foul_bunt",
+    "missed_bunt",
+    "bunt_foul_tip",
+    "hit_into_play",
+}
+
+
+def pitch_from_savant(raw: dict) -> Pitch:
+    """Build a normalized :class:`Pitch` from one entry of a Savant ``/gf`` pitcher list."""
+    pitch_type_code = raw.get("pitch_type")
+    plate_x = raw.get("plate_x", raw.get("px"))
+    plate_z = raw.get("plate_z", raw.get("pz"))
+    sz_top = raw.get("sz_top")
+    sz_bot = raw.get("sz_bot")
+    pitch_call = raw.get("pitch_call")
+
+    game_pk_raw = raw.get("game_pk")
+
+    return Pitch(
+        game_pk=int(game_pk_raw) if game_pk_raw is not None else None,
+        game_date=raw.get("game_date") or "",
+        pitch_id=raw.get("play_id"),
+        at_bat_number=raw.get("ab_number"),
+        pitch_number=raw.get("pitch_number"),
+        inning=raw.get("inning"),
+        half_inning=raw.get("half_inning"),
+        pitcher_id=raw.get("pitcher"),
+        pitcher_name=raw.get("pitcher_name"),
+        batter_id=raw.get("batter"),
+        batter_name=raw.get("batter_name"),
+        pitch_type_code=pitch_type_code,
+        pitch_type=PITCH_TYPE_NAMES.get(pitch_type_code, pitch_type_code),
+        velocity=raw.get("start_speed"),
+        plate_x=plate_x,
+        plate_z=plate_z,
+        sz_top=sz_top,
+        sz_bot=sz_bot,
+        in_zone=is_in_zone(plate_x, plate_z, sz_top, sz_bot),
+        balls=raw.get("pre_balls", raw.get("balls")),
+        strikes=raw.get("pre_strikes", raw.get("strikes")),
+        pitch_call=pitch_call,
+        call_description=raw.get("call_name") or raw.get("description"),
+        is_strike=(pitch_call in STRIKE_CALLS) if pitch_call is not None else None,
+        at_bat_result=raw.get("result"),
+        description=raw.get("des"),
+    )