fastballapi 0.1.0__py3-none-any.whl

fastballapi/__init__.py

@@ -0,0 +1,25 @@
+"""FastballAPI: Python client for the FastballAPI MLB data API."""
+from ._core import (
+    APIConnectionError,
+    APIError,
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    to_dataframe,
+)
+from ._version import __version__
+from .client import TOOLS, Client
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "AuthError",
+    "Client",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "TOOLS",
+    "__version__",
+    "to_dataframe",
+]

fastballapi/_core.py

@@ -0,0 +1,307 @@
+"""Shared runtime for the FastballAPI Python client.
+
+Standard library only. The generated methods live in client.py and call
+``Client._call``; everything else (auth, retries, errors, credits headers) is here.
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from ._version import __version__
+
+BRAND = "FastballAPI"
+ENV_VAR = "FASTBALLAPI_API_KEY"
+DEFAULT_BASE_URL = "https://mcp.fastballapi.com"
+SIGNUP_URL = "https://fastballapi.com/signup"
+DEFAULT_TIMEOUT = 60.0
+MAX_RETRIES = 3
+MAX_RETRY_WAIT = 30.0
+
+# A transport takes (method, url, headers, body, timeout) and returns
+# (status, headers, body). Header names in the returned dict are lowercase.
+Transport = Callable[
+    [str, str, Dict[str, str], Optional[bytes], float],
+    Tuple[int, Dict[str, str], bytes],
+]
+
+
+class APIError(Exception):
+    """Any error response from the API, or a failed connection."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return "%s (HTTP %s)" % (self.message, self.status_code)
+        return self.message
+
+
+class AuthError(APIError):
+    """401: the API key is missing, invalid or revoked."""
+
+
+class InsufficientCreditsError(APIError):
+    """402: the account does not have enough credits for this call."""
+
+
+class NotFoundError(APIError):
+    """404: the game, player, team or other id does not exist."""
+
+
+class RateLimitError(APIError):
+    """429: too many requests. ``retry_after`` is in seconds when the server sent it."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = 429,
+        body: Any = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status_code, body)
+        self.retry_after = retry_after
+
+
+class APIConnectionError(APIError):
+    """The request never got a response (DNS, TLS, timeout, reset)."""
+
+
+def _ssl_context() -> Optional[ssl.SSLContext]:
+    """Use certifi's CA bundle when it is installed, else the system default.
+
+    Some python.org installs on macOS ship without root certificates. Installing
+    certifi (or running the "Install Certificates" script) fixes the resulting
+    CERTIFICATE_VERIFY_FAILED error.
+    """
+    try:
+        import certifi
+    except ImportError:
+        return None
+    return ssl.create_default_context(cafile=certifi.where())
+
+
+def _urllib_transport(
+    method: str,
+    url: str,
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    timeout: float,
+) -> Tuple[int, Dict[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=_ssl_context()) as resp:
+            return (
+                resp.status,
+                {k.lower(): v for k, v in resp.headers.items()},
+                resp.read(),
+            )
+    except urllib.error.HTTPError as exc:
+        try:
+            payload = exc.read()
+        finally:
+            exc.close()
+        return (
+            exc.code,
+            {k.lower(): v for k, v in (exc.headers or {}).items()},
+            payload,
+        )
+    except (urllib.error.URLError, socket.timeout, ConnectionError, OSError) as exc:
+        reason = getattr(exc, "reason", exc)
+        raise APIConnectionError("Could not reach the API: %s" % (reason,)) from exc
+
+
+def _to_number(value: Optional[str]) -> Optional[Union[int, float]]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return float(value)
+        except ValueError:
+            return None
+
+
+def _error_message(parsed: Any, raw: bytes, status: int) -> str:
+    if isinstance(parsed, dict):
+        err = parsed.get("error")
+        if isinstance(err, str) and err:
+            return err
+        if isinstance(err, dict) and isinstance(err.get("message"), str):
+            return err["message"]
+    text = raw.decode("utf-8", "replace").strip()
+    if text:
+        return text[:300]
+    return "HTTP %s" % status
+
+
+class BaseClient:
+    """Holds the key, base URL, retry policy and the last credit counters."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        key = api_key or os.environ.get(ENV_VAR)
+        if not key:
+            raise AuthError(
+                "No API key. Pass api_key=... or set %s. "
+                "A free key is at %s" % (ENV_VAR, SIGNUP_URL)
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get(BRAND.upper() + "_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self._transport: Transport = transport or _urllib_transport
+        self._sleep: Callable[[float], None] = time.sleep
+        self.last_credits_used: Optional[Union[int, float]] = None
+        self.last_credits_remaining: Optional[Union[int, float]] = None
+
+    def __repr__(self) -> str:
+        return "<%s.Client base_url=%r>" % (BRAND, self.base_url)
+
+    def call(self, tool: str, arguments: Optional[Dict[str, Any]] = None) -> Any:
+        """Call any tool by name. Useful for tools newer than this package."""
+        return self._call(tool, arguments or {})
+
+    def _call(self, tool: str, arguments: Dict[str, Any]) -> Any:
+        payload = {k: v for k, v in arguments.items() if v is not None}
+        url = "%s/v1/%s" % (self.base_url, tool)
+        headers = {
+            "x-api-key": self.api_key,
+            "content-type": "application/json",
+            "accept": "application/json",
+            "user-agent": "%s-python/%s" % (BRAND.lower(), __version__),
+        }
+        body = json.dumps(payload).encode("utf-8")
+
+        attempt = 0
+        while True:
+            try:
+                status, resp_headers, raw = self._transport("POST", url, headers, body, self.timeout)
+            except APIConnectionError:
+                if attempt >= self.max_retries:
+                    raise
+                self._sleep(self._backoff(attempt, None))
+                attempt += 1
+                continue
+
+            self._record_credits(resp_headers)
+            if status == 429 or status >= 500:
+                if attempt < self.max_retries:
+                    self._sleep(self._backoff(attempt, self._retry_after(resp_headers)))
+                    attempt += 1
+                    continue
+            return self._handle(status, resp_headers, raw)
+
+    @staticmethod
+    def _retry_after(headers: Dict[str, str]) -> Optional[float]:
+        value = headers.get("retry-after")
+        if value is None:
+            return None
+        try:
+            return max(0.0, float(value))
+        except ValueError:
+            return None
+
+    @staticmethod
+    def _backoff(attempt: int, retry_after: Optional[float]) -> float:
+        if retry_after is not None:
+            return min(retry_after, MAX_RETRY_WAIT)
+        return min(0.5 * (2 ** attempt), MAX_RETRY_WAIT)
+
+    def _record_credits(self, headers: Dict[str, str]) -> None:
+        used = _to_number(headers.get("x-credits-used"))
+        remaining = _to_number(headers.get("x-credits-remaining"))
+        if used is not None:
+            self.last_credits_used = used
+        if remaining is not None:
+            self.last_credits_remaining = remaining
+
+    def _handle(self, status: int, headers: Dict[str, str], raw: bytes) -> Any:
+        try:
+            parsed = json.loads(raw.decode("utf-8")) if raw else None
+        except ValueError:
+            parsed = None
+
+        if 200 <= status < 300:
+            if parsed is None:
+                raise APIError("The API returned a response that is not JSON", status, raw[:300])
+            if isinstance(parsed, dict) and "data" in parsed:
+                return parsed["data"]
+            return parsed
+
+        message = _error_message(parsed, raw, status)
+        if status == 401:
+            raise AuthError(message, status, parsed)
+        if status == 402:
+            raise InsufficientCreditsError(message, status, parsed)
+        if status == 404:
+            raise NotFoundError(message, status, parsed)
+        if status == 429:
+            raise RateLimitError(message, status, parsed, self._retry_after(headers))
+        raise APIError(message, status, parsed)
+
+
+def _rows(data: Any, key: Optional[str]) -> List[Any]:
+    if key is not None:
+        cur = data
+        for part in key.split("."):
+            if not isinstance(cur, dict) or part not in cur:
+                raise KeyError("No %r in the response. Keys: %s" % (key, sorted(cur) if isinstance(cur, dict) else type(cur).__name__))
+            cur = cur[part]
+        if isinstance(cur, list):
+            return cur
+        return [cur]
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        lists = {k: v for k, v in data.items() if isinstance(v, list)}
+        records = {k: v for k, v in lists.items() if v and all(isinstance(r, dict) for r in v)}
+        pool = records or lists
+        if pool:
+            return pool[max(pool, key=lambda k: len(pool[k]))]
+        for v in data.values():
+            if isinstance(v, dict) and any(isinstance(x, list) for x in v.values()):
+                return _rows(v, None)
+        return [data]
+    return [data]
+
+
+def to_dataframe(data: Any, key: Optional[str] = None) -> Any:
+    """Turn a response into a pandas DataFrame.
+
+    ``data`` is what a client method returned. ``key`` names the list to use
+    (dots reach into nested dicts, for example ``"props"``). Without a key the
+    longest list of records in the response is used. Nested dicts are flattened
+    into dotted columns. pandas is imported here, so it stays optional.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("to_dataframe needs pandas: pip install pandas") from exc
+    rows = _rows(data, key)
+    if rows and all(isinstance(r, dict) for r in rows):
+        return pd.json_normalize(rows)
+    return pd.DataFrame(rows)

fastballapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fastballapi/client.py

@@ -0,0 +1,773 @@
+"""Generated by packages/python/generate.py from the FastballAPI OpenAPI spec. Do not edit by hand."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from ._core import BaseClient
+
+#: Credits each tool costs, from the spec.
+TOOLS: Dict[str, int] = {
+    "list_teams": 1,
+    "get_games": 2,
+    "get_schedule": 2,
+    "get_game": 5,
+    "get_standings": 2,
+    "get_injuries": 2,
+    "search_players": 1,
+    "get_player": 5,
+    "get_player_games": 5,
+    "get_leaders": 5,
+    "get_team_stats": 5,
+    "get_plate_appearances": 10,
+    "get_pitches": 10,
+    "get_pitch_mix": 5,
+    "get_spray_chart": 10,
+    "get_odds": 5,
+    "get_line_movement": 10,
+    "get_ratings": 2,
+    "get_player_props": 10,
+    "get_prop_history": 10,
+}
+
+
+class Client(BaseClient):
+    """Client for the FastballAPI API (MLB).
+
+    Create one with ``Client()`` (reads FASTBALLAPI_API_KEY) or ``Client(api_key="...")``.
+    Every method returns the unwrapped ``data`` from the response.
+    ``last_credits_used`` and ``last_credits_remaining`` hold the counters from
+    the most recent response.
+    """
+
+    def list_teams(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """List teams.
+
+        Use to find team ids and abbreviations for a season (default: the latest). Every other tool
+        takes a team as an id or abbreviation. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_teams",
+            {
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_games(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason"]] = None,
+        team: Optional[str] = None,
+        date: Optional[str] = None,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        status: Optional[Literal["scheduled", "final"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Games.
+
+        Use to list games with runs, hits and errors by season, date, date range or team, newest first.
+        For upcoming games with lines use get_schedule; for one game's box score use get_game. Costs 2
+        credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            season_type (optional): regular or postseason (default both).
+            team (optional): Team id or abbreviation.
+            date (optional): One date, YYYY-MM-DD (US Eastern).
+            from_ (optional): From date, YYYY-MM-DD.
+            to (optional): To date, YYYY-MM-DD.
+            status (optional): One of: scheduled, final.
+            limit (optional): Max games (default 50).
+            offset (optional): offset
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_games",
+            {
+                "season": season,
+                "season_type": season_type,
+                "team": team,
+                "date": date,
+                "from": from_,
+                "to": to,
+                "status": status,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_schedule(
+        self,
+        *,
+        days: Optional[int] = None,
+        team: Optional[str] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Schedule.
+
+        Use for upcoming games (next 1-30 days, default 7) with the median line across posted
+        sportsbooks: moneylines, run line and total. For every book's line use get_odds. Costs 2
+        credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            days (optional): days
+            team (optional): Team id or abbreviation.
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_schedule",
+            {
+                "days": days,
+                "team": team,
+                "league": league,
+            },
+        )
+
+    def get_game(
+        self,
+        game_id: str,
+        *,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Game.
+
+        Use for one game in full: line score, every batter's and pitcher's line, each sportsbook's
+        opening and closing line, and the win-probability range. For every plate appearance use
+        get_plate_appearances. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            game_id: ESPN game id, from get_games or get_schedule.
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_game",
+            {
+                "game_id": game_id,
+                "league": league,
+            },
+        )
+
+    def get_standings(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Standings.
+
+        Use for a season's regular-season standings computed from every final game: record, home and
+        away, last 10, runs scored and allowed, run differential and Pythagorean win percentage. Costs 2
+        credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_standings",
+            {
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_injuries(
+        self,
+        *,
+        team: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> Any:
+        """Injuries.
+
+        Use for the injury report: every listed player's status, injury and expected return, as captured
+        on the latest day (or the latest on or before date). Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            team (optional): team
+            date (optional): YYYY-MM-DD (default: the latest).
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_injuries",
+            {
+                "team": team,
+                "date": date,
+            },
+        )
+
+    def search_players(
+        self,
+        name: str,
+        *,
+        limit: Optional[int] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Search players.
+
+        Use to find a player's id by name (partial names work). Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            name: Full or partial name.
+            limit (optional): limit
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "search_players",
+            {
+                "name": name,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_player(
+        self,
+        player_id: str,
+        *,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Player.
+
+        Use for a player's season-by-season batting (AVG, OBP, SLG, OPS, HR, K%, BB%, RE24, from every
+        plate appearance) and pitching (ERA, WHIP, K/9, BB/9). Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: ESPN athlete id, from search_players.
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player",
+            {
+                "player_id": player_id,
+                "league": league,
+            },
+        )
+
+    def get_player_games(
+        self,
+        player_id: str,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Player games.
+
+        Use for a player's game log: every game's batting line and pitching line, newest first,
+        optionally one season. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: player_id
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            season_type (optional): One of: regular, postseason.
+            limit (optional): limit
+            offset (optional): offset
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_games",
+            {
+                "player_id": player_id,
+                "season": season,
+                "season_type": season_type,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_leaders(
+        self,
+        stat: Literal["avg", "obp", "slg", "ops", "hr", "re24", "bb_pct", "k_pct", "era", "whip", "so", "k_per_9", "bb_per_9"],
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        min_pa: Optional[int] = None,
+        min_ip: Optional[int] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Leaders.
+
+        Use for a season's leaders among qualified players: batting avg, obp, slg, ops, hr, re24,
+        bb_pct, k_pct (3.1 plate appearances per team game) or pitching era, whip, so, k_per_9, bb_per_9
+        (1 inning per team game). Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            stat: One of: avg, obp, slg, ops, hr, re24, bb_pct, k_pct, era, whip, so, k_per_9, bb_per_9.
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            min_pa (optional): Override the plate-appearance minimum.
+            min_ip (optional): Override the innings minimum.
+            limit (optional): limit
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_leaders",
+            {
+                "stat": stat,
+                "season": season,
+                "min_pa": min_pa,
+                "min_ip": min_ip,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_team_stats(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        team: Optional[str] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Team stats.
+
+        Use for team offence and run prevention for a season: runs per game for and against, run
+        differential, and batting and opponents' batting (AVG, OBP, SLG, OPS, K%, BB%, HR) from every
+        plate appearance. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            season (optional): Season (a year, e.g. 2025; default: the latest).
+            team (optional): team
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_team_stats",
+            {
+                "season": season,
+                "team": team,
+                "league": league,
+            },
+        )
+
+    def get_plate_appearances(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        batter_id: Optional[str] = None,
+        pitcher_id: Optional[str] = None,
+        team: Optional[str] = None,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason"]] = None,
+        result: Optional[str] = None,
+        inning: Optional[int] = None,
+        risp: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Plate appearances.
+
+        Use for plate-appearance play-by-play: a whole game in order, or a batter's, pitcher's or team's
+        season, with the base-out state before, the result, the batted ball (trajectory and location),
+        runs, the win probability after (2019 on) and our run value (RE24). Filter by result, inning or
+        runners in scoring position. Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            game_id (optional): game_id
+            batter_id (optional): batter_id
+            pitcher_id (optional): pitcher_id
+            team (optional): Batting team (id or abbreviation).
+            season (optional): Season (a year; default: the latest; ignored with game_id).
+            season_type (optional): One of: regular, postseason.
+            result (optional): e.g. home-run, strikeout, walk, single, double, ground-out.
+            inning (optional): inning
+            risp (optional): Runners in scoring position only.
+            limit (optional): Max rows (default 200).
+            offset (optional): offset
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_plate_appearances",
+            {
+                "game_id": game_id,
+                "batter_id": batter_id,
+                "pitcher_id": pitcher_id,
+                "team": team,
+                "season": season,
+                "season_type": season_type,
+                "result": result,
+                "inning": inning,
+                "risp": risp,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_pitches(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        pitcher_id: Optional[str] = None,
+        batter_id: Optional[str] = None,
+        season: Optional[Union[int, float, str]] = None,
+        pitch_type: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Any:
+        """Pitches.
+
+        Use for pitch-by-pitch data: every pitch of a game, or a pitcher's or batter's season, with the
+        count, pitch type, velocity, location and result. Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            game_id (optional): game_id
+            pitcher_id (optional): pitcher_id
+            batter_id (optional): batter_id
+            season (optional): Season (a year; default: the latest; ignored with game_id).
+            pitch_type (optional): ESPN abbreviation, e.g. FF, SL, CH, CU, SI, FC.
+            limit (optional): Max pitches (default 500).
+            offset (optional): offset
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_pitches",
+            {
+                "game_id": game_id,
+                "pitcher_id": pitcher_id,
+                "batter_id": batter_id,
+                "season": season,
+                "pitch_type": pitch_type,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+
+    def get_pitch_mix(
+        self,
+        pitcher_id: str,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+    ) -> Any:
+        """Pitch mix.
+
+        Use for a pitcher's arsenal in a season: each pitch type's usage, average and top velocity,
+        whiff rate per swing and ball rate. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            pitcher_id: ESPN athlete id.
+            season (optional): Season (a year; default: the latest; ignored with game_id).
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_pitch_mix",
+            {
+                "pitcher_id": pitcher_id,
+                "season": season,
+            },
+        )
+
+    def get_spray_chart(
+        self,
+        *,
+        batter_id: Optional[str] = None,
+        team: Optional[str] = None,
+        season: Optional[Union[int, float, str]] = None,
+        include_balls: Optional[bool] = None,
+    ) -> Any:
+        """Spray chart.
+
+        Use for where a batter or team hits the ball: balls in play by trajectory (ground ball, line
+        drive, fly ball, pop-up) and by field (left, center, right), with hit rates; include_balls adds
+        each ball's location for drawing. Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            batter_id (optional): batter_id
+            team (optional): team
+            season (optional): Season (a year; default: the latest; ignored with game_id).
+            include_balls (optional): Add each ball in play's x/y (up to 3,000).
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_spray_chart",
+            {
+                "batter_id": batter_id,
+                "team": team,
+                "season": season,
+                "include_balls": include_balls,
+            },
+        )
+
+    def get_odds(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        date: Optional[str] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Odds.
+
+        Use for betting lines: each sportsbook's moneyline, run line and total for a game (opening and
+        closing per book from July 2020 from The Odds API, and from 2024 from ESPN; ESPN's final line
+        only before that), with implied probabilities and, for finished games, whether the favourite won
+        and the total went over against the median close. Pass game_id for one game (5 credits) or date
+        for a day's games (10 credits).
+
+        Costs 5 credits per call.
+
+        Args:
+            game_id (optional): game_id
+            date (optional): A day's games, YYYY-MM-DD (US Eastern).
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_odds",
+            {
+                "game_id": game_id,
+                "date": date,
+                "league": league,
+            },
+        )
+
+    def get_line_movement(
+        self,
+        game_id: str,
+        *,
+        provider: Optional[str] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Line movement.
+
+        Use to see how a game's line moved before first pitch: our pre-game snapshots of each
+        sportsbook's moneyline, run line and total (ESPN's once a day, The Odds API's every hour for
+        games in the next two days). Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            game_id: game_id
+            provider (optional): One sportsbook, e.g. DraftKings.
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_line_movement",
+            {
+                "game_id": game_id,
+                "provider": provider,
+                "league": league,
+            },
+        )
+
+    def get_ratings(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        league: Optional[Literal["mlb", "ncaabase"]] = None,
+    ) -> Any:
+        """Ratings.
+
+        Use for our team power ratings (Elo from every final game in our data), ranked, as of the end of
+        a season or today. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            season (optional): season
+            league (optional): League. Defaults to mlb. One of: mlb, ncaabase.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_ratings",
+            {
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_player_props(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        player_id: Optional[str] = None,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        market: Optional[Literal["batter_hits", "batter_home_runs", "batter_total_bases", "batter_rbis", "pitcher_strikeouts", "pitcher_outs"]] = None,
+        bookmaker: Optional[str] = None,
+        snapshot_type: Optional[Literal["opening", "closing"]] = None,
+        estimate_only: Optional[bool] = None,
+    ) -> Any:
+        """Player props.
+
+        Use for player prop lines by sportsbook: over/under on hits, home runs, total bases, RBI,
+        pitcher strikeouts and pitcher outs, from May 2023 (DraftKings, FanDuel, BetMGM, ESPN BET,
+        Pinnacle and others). Pass game_id for every player's props in one game (10 credits), or
+        player_id with from_date (and to_date) for one player across games (10 credits per game
+        returned, up to 100). Returns the closing line by default (the last before the game starts) or
+        the opening line, with each book's over and under prices. Set estimate_only to get the price
+        without being charged.
+
+        Costs 10 credits per call.
+
+        Args:
+            game_id (optional): Game id: every player's props for that game.
+            player_id (optional): Player id (e.g. 33192) from search_players. With from_date: that
+                player's props across games.
+            from_date (optional): With player_id: first date, YYYY-MM-DD (the game's date).
+            to_date (optional): With player_id: last date (default: no end), YYYY-MM-DD (the game's
+                date).
+            market (optional): One market: batter_hits (hits), batter_home_runs (home runs),
+                batter_total_bases (total bases), batter_rbis (runs batted in), pitcher_strikeouts
+                (pitcher strikeouts), pitcher_outs (pitcher outs recorded)
+            bookmaker (optional): Bookmaker key, e.g. draftkings, fanduel, pinnacle.
+            snapshot_type (optional): closing (default): the last line before the game starts. opening:
+                the first one captured.
+            estimate_only (optional): Return what this call would cost, without charging or running it.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_props",
+            {
+                "game_id": game_id,
+                "player_id": player_id,
+                "from_date": from_date,
+                "to_date": to_date,
+                "market": market,
+                "bookmaker": bookmaker,
+                "snapshot_type": snapshot_type,
+                "estimate_only": estimate_only,
+            },
+        )
+
+    def get_prop_history(
+        self,
+        player_id: str,
+        market: Literal["batter_hits", "batter_home_runs", "batter_total_bases", "batter_rbis", "pitcher_strikeouts", "pitcher_outs"],
+        *,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        bookmaker: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        """Prop history.
+
+        Use to see how a player did against his prop line over time: for one market (hits, home runs,
+        total bases, RBI, pitcher strikeouts or pitcher outs), one row per game with the closing line
+        (the median across books, or one book's), the opening line, the prices, what the player actually
+        recorded from our box scores and the result against the line, plus the over rate. Costs 10
+        credits for up to 200 games.
+
+        Costs 10 credits per call.
+
+        Args:
+            player_id: Player id (e.g. 33192) from search_players.
+            market: The market: batter_hits (hits), batter_home_runs (home runs), batter_total_bases
+                (total bases), batter_rbis (runs batted in), pitcher_strikeouts (pitcher strikeouts),
+                pitcher_outs (pitcher outs recorded)
+            from_date (optional): First date, YYYY-MM-DD (the game's date).
+            to_date (optional): Last date, YYYY-MM-DD (the game's date).
+            bookmaker (optional): One book's closing line instead of the median across books, e.g.
+                draftkings.
+            limit (optional): Games to return, oldest first (default 50, max 200). next_from_date says
+                where to continue.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_prop_history",
+            {
+                "player_id": player_id,
+                "market": market,
+                "from_date": from_date,
+                "to_date": to_date,
+                "bookmaker": bookmaker,
+                "limit": limit,
+            },
+        )

fastballapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: fastballapi
+Version: 0.1.0
+Summary: Python client for the FastballAPI MLB data API. No dependencies.
+Project-URL: Homepage, https://fastballapi.com
+Project-URL: Documentation, https://fastballapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://fastballapi.com/signup
+Author-email: FastballAPI <support@fastballapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,betting,fastballapi,mlb,odds,player-props,sports-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# FastballAPI for Python
+
+Python client for the [FastballAPI](https://fastballapi.com) MLB data API. It has no required dependencies (standard library only) and works on Python 3.9 and newer. Pandas is optional.
+
+## Install
+
+```bash
+pip install fastballapi
+pip install "fastballapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://fastballapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export FASTBALLAPI_API_KEY=your_key_here
+```
+
+```python
+from fastballapi import Client
+
+client = Client()                      # reads FASTBALLAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Player props for one game
+
+`get_player_props` returns lines by sportsbook. Here are home run props for one game.
+
+```python
+from fastballapi import Client, to_dataframe
+
+client = Client()
+
+props = client.get_player_props(
+    game_id="401815991",
+    market="batter_home_runs",
+)
+df = to_dataframe(props, key="props")
+print(df[["player_name", "bookmaker", "line", "over_odds", "under_odds"]].head(10))
+```
+
+### 2. A pitcher's pitch mix
+
+Find the player id with `search_players`, then ask for usage, velocity and whiff rate by pitch type.
+
+```python
+from fastballapi import Client, to_dataframe
+
+client = Client()
+
+ohtani = client.search_players("Ohtani", limit=1)["players"][0]
+mix = client.get_pitch_mix(ohtani["player_id"])
+print(to_dataframe(mix, key="mix")[["name", "usage", "avg_velocity", "whiff_rate"]])
+```
+
+### 3. League leaders
+
+`get_leaders` ranks qualified hitters or pitchers by a stat.
+
+```python
+from fastballapi import Client
+
+client = Client()
+
+leaders = client.get_leaders("ops", limit=5)
+for row in leaders["leaders"]:
+    print(row["name"], row["team"], row["ops"])
+```
+
+## Credits
+
+Every method returns the `data` object from the response. After each call, `client.last_credits_used` and `client.last_credits_remaining` hold the counters from the `X-Credits-Used` and `X-Credits-Remaining` headers. Methods that take `estimate_only=True` return the price of a call without running or charging it.
+
+## Pandas
+
+```python
+from fastballapi import to_dataframe
+
+df = to_dataframe(data)                # finds the main list in the response
+df = to_dataframe(data, key="rows")    # or name the list yourself
+```
+
+Nested fields become dotted columns. Install pandas separately or with `pip install "fastballapi[pandas]"`.
+
+## Errors
+
+Every error is an `APIError` subclass, with the server's message and the HTTP status.
+
+| Exception | Status | Meaning |
+| --- | --- | --- |
+| `AuthError` | 401 | Missing, invalid or revoked key |
+| `InsufficientCreditsError` | 402 | Not enough credits for the call |
+| `NotFoundError` | 404 | The id or name does not exist |
+| `RateLimitError` | 429 | Too many requests; has `.retry_after` when the server sends it |
+| `APIError` | 400, 5xx | Bad arguments or a server problem |
+| `APIConnectionError` | none | No response (network or timeout) |
+
+```python
+from fastballapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_teams()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://fastballapi.com")
+except RateLimitError as exc:
+    print("Slow down, retry after", exc.retry_after)
+except APIError as exc:
+    print(exc.status_code, exc.message)
+```
+
+The client retries 429 and 5xx responses and connection failures up to 3 times with backoff, and honors `Retry-After`. Set `Client(max_retries=0)` to turn that off.
+
+If you see `CERTIFICATE_VERIFY_FAILED` on a python.org install for macOS, run the "Install Certificates.command" script that came with Python, or `pip install certifi` (the client uses it when present).
+
+## Options
+
+```python
+Client(
+    api_key=None,                          # defaults to $FASTBALLAPI_API_KEY
+    base_url="https://mcp.fastballapi.com",           # point at another host
+    timeout=60.0,                          # seconds per request
+    max_retries=3,
+)
+```
+
+`client.call("tool_name", {"arg": "value"})` calls any tool by name, which helps when the API adds a tool before this package does.
+
+## Tools
+
+Method names match the API tool names. Arguments are keyword arguments; required ones can also be passed positionally. Each method's docstring lists its arguments (`help(client.list_teams)`).
+
+| Method | Credits | What it does |
+| --- | --- | --- |
+| `list_teams` | 1 | List teams |
+| `get_games` | 2 | Games |
+| `get_schedule` | 2 | Schedule |
+| `get_game` | 5 | Game |
+| `get_standings` | 2 | Standings |
+| `get_injuries` | 2 | Injuries |
+| `search_players` | 1 | Search players |
+| `get_player` | 5 | Player |
+| `get_player_games` | 5 | Player games |
+| `get_leaders` | 5 | Leaders |
+| `get_team_stats` | 5 | Team stats |
+| `get_plate_appearances` | 10 | Plate appearances |
+| `get_pitches` | 10 | Pitches |
+| `get_pitch_mix` | 5 | Pitch mix |
+| `get_spray_chart` | 10 | Spray chart |
+| `get_odds` | 5 | Odds |
+| `get_line_movement` | 10 | Line movement |
+| `get_ratings` | 2 | Ratings |
+| `get_player_props` | 10 | Player props |
+| `get_prop_history` | 10 | Prop history |
+
+Full API reference: https://fastballapi.com/docs
+
+## License
+
+MIT

fastballapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fastballapi/__init__.py,sha256=_-bSwdL2ZRzjOVTXU1lDbdVQHLrVWKkoaX4y_CDmuXk,513
+fastballapi/_core.py,sha256=F4yf3Wyd7iChpEHT7Khy1HbBQNUTmcg1k3AEOAqPJCE,10614
+fastballapi/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fastballapi/client.py,sha256=2eMu97IGLFbymYmGwbJcKCsXMFicmBTd1_qG3Jw7CIQ,26310
+fastballapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fastballapi-0.1.0.dist-info/METADATA,sha256=hjJ7KdMpBkyQhWHXyTEvMG0GdnOlDO5vZtmlv8T4O1c,6455
+fastballapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastballapi-0.1.0.dist-info/licenses/LICENSE,sha256=V2IlG89uYfGvraoEIwvWnl8uOKLDrYbkQpolsKxJdZ8,1068
+fastballapi-0.1.0.dist-info/RECORD,,

fastballapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fastballapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FastballAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.