dunkapi 0.1.0__py3-none-any.whl

dunkapi/__init__.py

@@ -0,0 +1,25 @@
+"""DunkAPI: Python client for the DunkAPI NBA 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",
+]

dunkapi/_core.py

@@ -0,0 +1,307 @@
+"""Shared runtime for the DunkAPI 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 = "DunkAPI"
+ENV_VAR = "DUNKAPI_API_KEY"
+DEFAULT_BASE_URL = "https://mcp.dunkapi.com"
+SIGNUP_URL = "https://dunkapi.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)

dunkapi/_version.py

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

dunkapi/client.py

@@ -0,0 +1,731 @@
+"""Generated by packages/python/generate.py from the DunkAPI 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,
+    "list_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_plays": 10,
+    "get_shot_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 DunkAPI API (NBA).
+
+    Create one with ``Client()`` (reads DUNKAPI_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["nba", "wnba", "ncaam", "ncaaw"]] = 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. Pass league for the WNBA (wnba) or college (ncaam,
+        ncaaw); default NBA. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            season (optional): Season by the year it ends: 2025 = 2024-25. WNBA: the calendar year.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_teams",
+            {
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def list_games(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason", "play_in", "preseason"]] = 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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """List games.
+
+        Use to list games with scores 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 by the year it ends: 2025 = 2024-25.
+            season_type (optional): regular, postseason, play_in or preseason.
+            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): Page offset; use next_offset.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Schedule.
+
+        Use for upcoming games (next 1-30 days, default 7) with the median line across posted
+        sportsbooks: spread, total and moneylines. For every book's line use get_odds. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            days (optional): Days ahead (default 7).
+            team (optional): Team id or abbreviation.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Game.
+
+        Use for one game in full: score, both teams' box scores, every player's line, each sportsbook's
+        opening and closing line, and the win-probability range. For the play-by-play use get_plays.
+        Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            game_id: ESPN game id, from list_games or get_schedule.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Standings.
+
+        Use for a season's regular-season standings computed from every final game: overall, conference,
+        home and away records, points for and against, margin and last 10. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            season (optional): Season by the year it ends (default: the latest).
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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,
+        league: Optional[Literal["nba", "wnba"]] = None,
+    ) -> Any:
+        """Injuries.
+
+        Use for the injury report: every listed player's status (out, day-to-day), injury and expected
+        return, as captured on the latest day (or the latest on or before date). NBA and WNBA. Costs 2
+        credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            team (optional): One team (id or abbreviation).
+            date (optional): The report as of this day, YYYY-MM-DD (default: the latest).
+            league (optional): League. Defaults to nba. One of: nba, wnba.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_injuries",
+            {
+                "team": team,
+                "date": date,
+                "league": league,
+            },
+        )
+
+    def search_players(
+        self,
+        name: str,
+        *,
+        limit: Optional[int] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Search players.
+
+        Use to find a player's id by name (partial names work), most recent players first. Pass league
+        for the WNBA (wnba) or college (ncaam, ncaaw); default NBA. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            name: Full or partial name.
+            limit (optional): limit
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Player.
+
+        Use for a player's profile, per-season averages and shooting splits (regular season and
+        postseason separately) and last 10 games. For every game use get_player_games. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: ESPN athlete id, from search_players.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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", "play_in", "preseason"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Player games.
+
+        Use for a player's game log: every game's box-score line with opponent and result, newest first,
+        optionally one season. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: ESPN athlete id.
+            season (optional): Season by the year it ends: 2025 = 2024-25 (default: the latest).
+            season_type (optional): One of: regular, postseason, play_in, preseason.
+            limit (optional): Max games (default 100).
+            offset (optional): offset
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["pts", "reb", "ast", "stl", "blk", "tpm", "min", "plus_minus", "fg_pct", "tp_pct", "ft_pct", "ts_pct", "total_pts"],
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason", "play_in", "preseason"]] = None,
+        min_games: Optional[int] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Leaders.
+
+        Use for a season's statistical leaders (per game, shooting percentages with a volume floor, or
+        totals) from every box score. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            stat: Stat to rank by. One of: pts, reb, ast, stl, blk, tpm, min, plus_minus, fg_pct,
+                tp_pct, ft_pct, ts_pct, total_pts.
+            season (optional): Season by the year it ends: 2025 = 2024-25 (default: the latest).
+            season_type (optional): Default regular. One of: regular, postseason, play_in, preseason.
+            min_games (optional): Minimum games played (default: a quarter of the season).
+            limit (optional): limit
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_leaders",
+            {
+                "stat": stat,
+                "season": season,
+                "season_type": season_type,
+                "min_games": min_games,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_team_stats(
+        self,
+        *,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason", "play_in", "preseason"]] = None,
+        team: Optional[str] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Team stats.
+
+        Use for team efficiency for a season: pace, offensive, defensive and net rating per 100
+        possessions, the four factors (eFG%, turnover %, offensive rebound %, free throw rate) and
+        three-point rate, from every box score. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            season (optional): Season by the year it ends: 2025 = 2024-25 (default: the latest).
+            season_type (optional): One of: regular, postseason, play_in, preseason.
+            team (optional): One team (id or abbreviation).
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_team_stats",
+            {
+                "season": season,
+                "season_type": season_type,
+                "team": team,
+                "league": league,
+            },
+        )
+
+    def get_plays(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        player_id: Optional[str] = None,
+        team: Optional[str] = None,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason", "play_in", "preseason"]] = None,
+        shots_only: Optional[bool] = None,
+        made: Optional[bool] = None,
+        zone: Optional[Literal["restricted_area", "paint", "midrange", "corner_3", "above_break_3", "free_throw"]] = None,
+        period: Optional[int] = None,
+        clutch: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Plays.
+
+        Use for play-by-play: every event of a game, or a player's or team's plays across a season, with
+        shot location (feet), zone, our expected points, the score and the home win probability after
+        each play (2018 on). Filter to shots, makes or misses, a zone, a period or clutch time. Pass
+        league for the WNBA (wnba) or college (ncaam, ncaaw); default NBA. Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            game_id (optional): One game: every play in order.
+            player_id (optional): A player's plays (with season).
+            team (optional): A team's plays (id or abbreviation).
+            season (optional): Season by the year it ends (default: the latest; ignored with game_id).
+            season_type (optional): One of: regular, postseason, play_in, preseason.
+            shots_only (optional): Field goal and free throw attempts only.
+            made (optional): Only made (true) or missed (false) shots.
+            zone (optional): One shot zone. One of: restricted_area, paint, midrange, corner_3,
+                above_break_3, free_throw.
+            period (optional): period
+            clutch (optional): Last 5 minutes of the 4th quarter (college men: 2nd half) or overtime,
+                score within 5.
+            limit (optional): Max plays (default 200).
+            offset (optional): offset
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_plays",
+            {
+                "game_id": game_id,
+                "player_id": player_id,
+                "team": team,
+                "season": season,
+                "season_type": season_type,
+                "shots_only": shots_only,
+                "made": made,
+                "zone": zone,
+                "period": period,
+                "clutch": clutch,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_shot_chart(
+        self,
+        *,
+        player_id: Optional[str] = None,
+        team: Optional[str] = None,
+        opponent: Optional[bool] = None,
+        game_id: Optional[str] = None,
+        season: Optional[Union[int, float, str]] = None,
+        season_type: Optional[Literal["regular", "postseason", "play_in", "preseason"]] = None,
+        include_shots: Optional[bool] = None,
+        league: Optional[Literal["nba", "wnba"]] = None,
+    ) -> Any:
+        """Shot chart.
+
+        Use for a shot profile: attempts, makes, percentage, points per shot and expected points per
+        shot in each zone (restricted area, paint, midrange, corner three, above-the-break three, free
+        throws) for a player, a team, a team's opponents or one game. include_shots adds every located
+        shot's x/y and result for drawing a chart. Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            player_id (optional): player_id
+            team (optional): Team id or abbreviation.
+            opponent (optional): With team: the shots its opponents took (its defence).
+            game_id (optional): game_id
+            season (optional): Season by the year it ends (default: the latest).
+            season_type (optional): One of: regular, postseason, play_in, preseason.
+            include_shots (optional): Add each shot's x, y and result (up to 3,000).
+            league (optional): League. Defaults to nba. One of: nba, wnba.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_shot_chart",
+            {
+                "player_id": player_id,
+                "team": team,
+                "opponent": opponent,
+                "game_id": game_id,
+                "season": season,
+                "season_type": season_type,
+                "include_shots": include_shots,
+                "league": league,
+            },
+        )
+
+    def get_odds(
+        self,
+        *,
+        game_id: Optional[str] = None,
+        date: Optional[str] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Odds.
+
+        Use for betting lines: each sportsbook's moneyline, spread and total for a game (opening and
+        closing per book from July 2020 from The Odds API, and from 2023-24 from ESPN; ESPN's final line
+        only before that), with implied probabilities and, for finished games, whether the home side
+        covered 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): One game.
+            date (optional): A day's games, YYYY-MM-DD (US Eastern).
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["nba", "wnba", "ncaam", "ncaaw"]] = None,
+    ) -> Any:
+        """Line movement.
+
+        Use to see how a game's line moved before tip-off: our pre-game snapshots of each sportsbook's
+        moneyline, spread 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 nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["nba", "wnba", "ncaam", "ncaaw"]] = 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 by the year it ends (default: the latest).
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
+
+        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["player_points", "player_rebounds", "player_assists", "player_threes", "player_points_rebounds_assists", "player_blocks", "player_steals"]] = None,
+        bookmaker: Optional[str] = None,
+        snapshot_type: Optional[Literal["opening", "closing"]] = None,
+        estimate_only: Optional[bool] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam"]] = None,
+    ) -> Any:
+        """Player props.
+
+        Use for player prop lines by sportsbook: over/under on points, rebounds, assists, threes, points
+        + rebounds + assists, blocks and steals, from May 2023 for the NBA and WNBA and the 2023-24
+        season for men's college basketball (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. 3945274) 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: player_points (points), player_rebounds (rebounds),
+                player_assists (assists), player_threes (three-pointers made),
+                player_points_rebounds_assists (points + rebounds + assists), player_blocks (blocks),
+                player_steals (steals)
+            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.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam.
+
+        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,
+                "league": league,
+            },
+        )
+
+    def get_prop_history(
+        self,
+        player_id: str,
+        market: Literal["player_points", "player_rebounds", "player_assists", "player_threes", "player_points_rebounds_assists", "player_blocks", "player_steals"],
+        *,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        bookmaker: Optional[str] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["nba", "wnba", "ncaam"]] = None,
+    ) -> Any:
+        """Prop history.
+
+        Use to see how a player did against his prop line over time: for one market (points, rebounds,
+        assists, threes, points + rebounds + assists, blocks or steals), 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. 3945274) from search_players.
+            market: The market: player_points (points), player_rebounds (rebounds), player_assists
+                (assists), player_threes (three-pointers made), player_points_rebounds_assists (points +
+                rebounds + assists), player_blocks (blocks), player_steals (steals)
+            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.
+            league (optional): League. Defaults to nba. One of: nba, wnba, ncaam.
+
+        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,
+                "league": league,
+            },
+        )

dunkapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: dunkapi
+Version: 0.1.0
+Summary: Python client for the DunkAPI NBA data API. No dependencies.
+Project-URL: Homepage, https://dunkapi.com
+Project-URL: Documentation, https://dunkapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://dunkapi.com/signup
+Author-email: DunkAPI <support@dunkapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,betting,dunkapi,nba,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
+
+# DunkAPI for Python
+
+Python client for the [DunkAPI](https://dunkapi.com) NBA 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 dunkapi
+pip install "dunkapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://dunkapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export DUNKAPI_API_KEY=your_key_here
+```
+
+```python
+from dunkapi import Client
+
+client = Client()                      # reads DUNKAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Player props for one game
+
+`get_player_props` returns every player's line for one market, by sportsbook.
+
+```python
+from dunkapi import Client, to_dataframe
+
+client = Client()
+
+props = client.get_player_props(
+    game_id="401810726",
+    market="player_points",
+    bookmaker="draftkings",
+)
+df = to_dataframe(props, key="props")
+print(df[["player_name", "line", "over_odds", "under_odds"]].head(10))
+```
+
+### 2. One player's prop history
+
+`get_prop_history` shows how a player's line for a market moved across games. Search for the player id first.
+
+```python
+from dunkapi import Client, to_dataframe
+
+client = Client()
+
+jokic = client.search_players("Jokic", limit=1)["players"][0]
+history = client.get_prop_history(
+    jokic["player_id"],
+    "player_points",
+    from_date="2026-03-01",
+    to_date="2026-03-08",
+    bookmaker="draftkings",
+    limit=10,
+)
+print(to_dataframe(history).head())
+```
+
+### 3. Games on a date, and scoring leaders
+
+`list_games` needs a filter such as `date`, `season` or `team`.
+
+```python
+from dunkapi import Client
+
+client = Client()
+
+games = client.list_games(date="2026-03-15", limit=3)["games"]
+for g in games:
+    print(g["away"]["abbrev"], g["away"]["score"], "at", g["home"]["abbrev"], g["home"]["score"])
+
+leaders = client.get_leaders("pts", limit=5)
+for row in leaders["leaders"]:
+    print(row["name"], row["team"], row["value"])
+```
+
+## 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 dunkapi 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 "dunkapi[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 dunkapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_teams()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://dunkapi.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 $DUNKAPI_API_KEY
+    base_url="https://mcp.dunkapi.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 |
+| `list_games` | 2 | List 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_plays` | 10 | Plays |
+| `get_shot_chart` | 10 | Shot 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://dunkapi.com/docs
+
+## License
+
+MIT

dunkapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dunkapi/__init__.py,sha256=ATLWrzFMYlP1Z6Cnu0xg4jj8hW5mXHuPAjGX4J_ZfhY,505
+dunkapi/_core.py,sha256=VL8fy7Vf3_a71xVhrlWQ4-dzSuGDrjg8HcdeuEcvVR4,10594
+dunkapi/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+dunkapi/client.py,sha256=zfhgbvdNJBty163Is2wweuRN5qhGg9Eavv05und-Zco,27251
+dunkapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dunkapi-0.1.0.dist-info/METADATA,sha256=KraEaS2acYiyI1_CHYN_ngGGGZXeq3M4DR2QkdOHvM4,6559
+dunkapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dunkapi-0.1.0.dist-info/licenses/LICENSE,sha256=u471lqnuQ34I5CiZKd7-BtYYdeajVU9iMFrJhy11V2U,1064
+dunkapi-0.1.0.dist-info/RECORD,,

dunkapi-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

dunkapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DunkAPI
+
+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.