birdieapi 0.1.0__py3-none-any.whl

birdieapi/__init__.py

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

birdieapi/_core.py

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

birdieapi/_version.py

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

birdieapi/client.py

@@ -0,0 +1,536 @@
+"""Generated by packages/python/generate.py from the BirdieAPI 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_tournaments": 1,
+    "get_schedule": 1,
+    "get_leaderboard": 2,
+    "get_course": 2,
+    "search_players": 1,
+    "get_player": 5,
+    "get_player_results": 5,
+    "get_player_stats": 5,
+    "get_scorecard": 2,
+    "get_course_history": 5,
+    "get_head_to_head": 5,
+    "get_ratings": 2,
+    "get_leaders": 5,
+    "get_winner_odds": 5,
+}
+
+
+class Client(BaseClient):
+    """Client for the BirdieAPI API (golf).
+
+    Create one with ``Client()`` (reads BIRDIEAPI_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_tournaments(
+        self,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        status: Optional[Literal["scheduled", "live", "final"]] = None,
+        major: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """List tournaments.
+
+        Use to find tournaments. Lists a season's tournaments (ascending) or the latest ones
+        (descending) with dates, status, purse, whether it is a major, the winner and winning score,
+        field size and the courses. Filter by season, status and major. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            season (optional): Season year, e.g. 2025.
+            status (optional): Only upcoming, in-progress or completed tournaments. One of: scheduled,
+                live, final.
+            major (optional): Only the majors.
+            limit (optional): Max tournaments (default 60).
+            offset (optional): Page offset; use next_offset.
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_tournaments",
+            {
+                "season": season,
+                "status": status,
+                "major": major,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_schedule(
+        self,
+        *,
+        days: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Schedule.
+
+        Use for what is on now and next: tournaments in play or starting in the next N days (default
+        30), with the courses and the defending champion. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            days (optional): Days ahead (default 30, max 365).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_schedule",
+            {
+                "days": days,
+                "league": league,
+            },
+        )
+
+    def get_leaderboard(
+        self,
+        tournament_id: str,
+        *,
+        limit: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Leaderboard.
+
+        Use for a tournament's results: every player in the field in finishing order with position (T5),
+        status (cut, wd, dq), score to par, total strokes, each round's score and strokes versus the
+        field, earnings and season points, plus any playoff. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            tournament_id: Tournament id from list_tournaments or get_schedule.
+            limit (optional): Max players (default the whole field).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_leaderboard",
+            {
+                "tournament_id": tournament_id,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_course(
+        self,
+        tournament_id: str,
+        *,
+        course_id: Optional[str] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Course.
+
+        Use for a course as it was set up for a tournament: par and yards per hole, and how each hole
+        played (scoring average, to par, birdie and bogey rates, difficulty rank) from every round on
+        it. For a tournament on more than one course pass course_id. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            tournament_id: Tournament id from list_tournaments.
+            course_id (optional): Course id, for tournaments played on more than one course
+                (list_tournaments lists them).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_course",
+            {
+                "tournament_id": tournament_id,
+                "course_id": course_id,
+                "league": league,
+            },
+        )
+
+    def search_players(
+        self,
+        query: str,
+        *,
+        limit: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Search players.
+
+        Use to find a player's id by name (accents optional). Returns country, tournaments played, wins
+        and the seasons played. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            query: Part of the player's name, e.g. 'scheffler'.
+            limit (optional): Max players (default 20).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "search_players",
+            {
+                "query": query,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_player(
+        self,
+        player_id: str,
+        *,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Player.
+
+        Use for a player's overview: profile, career totals (starts, wins, top tens, cuts, money,
+        scoring average, strokes versus the field), our current rating, a line per season and the last
+        ten results. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players or get_leaderboard.
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player",
+            {
+                "player_id": player_id,
+                "league": league,
+            },
+        )
+
+    def get_player_results(
+        self,
+        player_id: str,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Player results.
+
+        Use for a player's tournament-by-tournament record: finish, score, earnings and each round with
+        the field's average and strokes versus the field (raw and field-strength adjusted). Newest
+        first; filter by season. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            season (optional): Season year, e.g. 2025.
+            limit (optional): Max tournaments (default 50).
+            offset (optional): Page offset; use next_offset.
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_results",
+            {
+                "player_id": player_id,
+                "season": season,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_player_stats(
+        self,
+        player_id: str,
+        season: Union[str, int, float],
+        *,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Player stats.
+
+        Use for a player's season in numbers: results (starts, wins, top tens, cuts, money), scoring
+        average and strokes versus the field, hole scoring from every hole played (birdies and bogeys
+        per round, par 3/4/5 averages) and, for the PGA Tour and Korn Ferry Tour, strokes versus the
+        field by hole type (sg_par3, sg_par4, sg_par5; score-based, not shot data) and, where ESPN keeps
+        them, driving distance and accuracy, greens in regulation and putts per green. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            season: Season year, e.g. 2025.
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_stats",
+            {
+                "player_id": player_id,
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_scorecard(
+        self,
+        tournament_id: str,
+        player_id: str,
+        *,
+        league: Optional[Literal["golf", "kornferry"]] = None,
+    ) -> Any:
+        """Scorecard.
+
+        Use for one player's tournament hole by hole: every round's strokes on each hole with par, yards
+        and the result (birdie, bogey), the course played, out and in, and strokes versus the field.
+        Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            tournament_id: Tournament id from list_tournaments.
+            player_id: Player id from get_leaderboard or search_players.
+            league (optional): League. Defaults to golf. One of: golf, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_scorecard",
+            {
+                "tournament_id": tournament_id,
+                "player_id": player_id,
+                "league": league,
+            },
+        )
+
+    def get_course_history(
+        self,
+        player_id: str,
+        *,
+        tournament_id: Optional[str] = None,
+        course_id: Optional[str] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Course history.
+
+        Use for course or event form: a player's record at one tournament across every year (pass any
+        edition's tournament_id) or at one course across every tournament played there (course_id), with
+        finishes, rounds and strokes versus the field, and a summary. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            tournament_id (optional): Any year's id of the tournament; every edition is returned.
+            course_id (optional): A course id (list_tournaments lists each tournament's courses).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_course_history",
+            {
+                "player_id": player_id,
+                "tournament_id": tournament_id,
+                "course_id": course_id,
+                "league": league,
+            },
+        )
+
+    def get_head_to_head(
+        self,
+        player_a: str,
+        player_b: str,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Head to head.
+
+        Use to compare two players: every tournament both played with each one's finish, who finished
+        ahead (making the cut beats missing it), round-by-round strokes on the same course, and a
+        summary. Filter by season. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_a: First player id.
+            player_b: Second player id.
+            season (optional): Season year, e.g. 2025.
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_head_to_head",
+            {
+                "player_a": player_a,
+                "player_b": player_b,
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_ratings(
+        self,
+        *,
+        limit: Optional[int] = None,
+        as_of: Optional[str] = None,
+        min_rounds: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Ratings.
+
+        Use for who is playing best: our strokes-versus-field rating for every player active in the past
+        year, best first. A rating of 2.0 means two strokes a round better than an average player in the
+        same fields, adjusted for field strength and weighted toward recent rounds. Pass as_of for the
+        ratings on a past date. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            limit (optional): Max players (default 50).
+            as_of (optional): A date (YYYY-MM-DD): the ratings as they stood then. Default the latest.
+            min_rounds (optional): Minimum decay-weighted rounds behind a rating (default 20).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_ratings",
+            {
+                "limit": limit,
+                "as_of": as_of,
+                "min_rounds": min_rounds,
+                "league": league,
+            },
+        )
+
+    def get_leaders(
+        self,
+        stat: Literal["scoring_average", "adj_vs_field", "vs_field", "birdies_per_round", "bogey_avoidance", "par3_average", "par4_average", "par5_average", "sg_par3", "sg_par4", "sg_par5", "earnings", "cup_points", "wins", "top_tens", "driving_distance", "driving_accuracy", "greens_in_regulation", "putts_per_gir"],
+        season: Union[str, int, float],
+        *,
+        min: Optional[int] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["golf", "lpga", "liv", "dpwt", "kornferry"]] = None,
+    ) -> Any:
+        """Leaders.
+
+        Use for a season's leaders in one stat, with each player's sample. Stats from rounds and holes:
+        scoring_average, vs_field, adj_vs_field, birdies_per_round, bogey_avoidance, par3_average,
+        par4_average, par5_average, and sg_par3, sg_par4, sg_par5 (strokes versus the field on par 3, 4
+        or 5 holes, field-strength adjusted; PGA Tour and Korn Ferry Tour only, score-based, not shot
+        data). From results: earnings, cup_points, wins, top_tens. From ESPN's tournament lines (PGA
+        Tour from 2011): driving_distance, driving_accuracy, greens_in_regulation, putts_per_gir. Costs
+        5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            stat: The stat to rank. One of: scoring_average, adj_vs_field, vs_field, birdies_per_round,
+                bogey_avoidance, par3_average, par4_average, par5_average, sg_par3, sg_par4, sg_par5,
+                earnings, cup_points, wins, top_tens, driving_distance, driving_accuracy,
+                greens_in_regulation, putts_per_gir.
+            season: Season year, e.g. 2025.
+            min (optional): Minimum sample: rounds (default 40), starts (1) or tournaments with a stat
+                line (8).
+            limit (optional): Max players (default 25).
+            league (optional): League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_leaders",
+            {
+                "stat": stat,
+                "season": season,
+                "min": min,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_winner_odds(
+        self,
+        *,
+        tournament_id: Optional[str] = None,
+        season: Optional[Union[str, int, float]] = None,
+        major: Optional[Literal["masters", "pga_championship", "us_open", "the_open"]] = None,
+        player_id: Optional[str] = None,
+        bookmaker: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        """Winner odds.
+
+        Use for the pre-tournament winner prices of the four men's majors by sportsbook, and how they
+        moved: for each golfer and book the opening price (the first snapshot) and the latest price
+        before the first round, with the implied probability, from The Odds API (the archive for every
+        major from 2021 plus the 2020 U.S. Open, then refreshed daily while a major's market is open,
+        every six hours in tournament week). For past majors the latest price can be up to a week before
+        the first tee time; round, matchup and finishing-position markets are not held. Pass
+        tournament_id, or season (all four majors), or player_id (one golfer across the majors). Costs 5
+        credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            tournament_id (optional): A major's tournament id from list_tournaments (major: true).
+            season (optional): ESPN's season year, e.g. 2025: all four majors of that season (the 2020
+                U.S. Open and the November 2020 Masters are season 2021).
+            major (optional): Only this major (with season, or alone for every year). One of: masters,
+                pga_championship, us_open, the_open.
+            player_id (optional): Player id from search_players: this golfer across the majors he was
+                priced for.
+            bookmaker (optional): Bookmaker key, e.g. draftkings, fanduel, betmgm, bovada, betonlineag,
+                espnbet, pinnacle, mybookieag.
+            limit (optional): Golfers per tournament, favourites first (default 20, max 200). Ignored
+                with player_id.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_winner_odds",
+            {
+                "tournament_id": tournament_id,
+                "season": season,
+                "major": major,
+                "player_id": player_id,
+                "bookmaker": bookmaker,
+                "limit": limit,
+            },
+        )

birdieapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: birdieapi
+Version: 0.1.0
+Summary: Python client for the BirdieAPI golf data API. No dependencies.
+Project-URL: Homepage, https://birdieapi.com
+Project-URL: Documentation, https://birdieapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://birdieapi.com/signup
+Author-email: BirdieAPI <support@birdieapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,betting,birdieapi,golf,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
+
+# BirdieAPI for Python
+
+Python client for the [BirdieAPI](https://birdieapi.com) golf 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 birdieapi
+pip install "birdieapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://birdieapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export BIRDIEAPI_API_KEY=your_key_here
+```
+
+```python
+from birdieapi import Client
+
+client = Client()                      # reads BIRDIEAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Recent tournaments
+
+`list_tournaments` filters by season and status.
+
+```python
+from birdieapi import Client
+
+client = Client()
+
+events = client.list_tournaments(status="final", limit=3)["tournaments"]
+for e in events:
+    print(e["tournament_id"], e["name"], e["winner_name"], e["winning_to_par"])
+```
+
+### 2. A leaderboard
+
+Pass a tournament id from `list_tournaments`.
+
+```python
+from birdieapi import Client, to_dataframe
+
+client = Client()
+
+board = client.get_leaderboard("401850916", limit=10)
+print(to_dataframe(board).head(10))
+```
+
+### 3. A player's results
+
+Find the player id with `search_players`, then pull his results for a season.
+
+```python
+from birdieapi import Client
+
+client = Client()
+
+scheffler = client.search_players("Scheffler", limit=1)["players"][0]
+results = client.get_player_results(scheffler["player_id"], season=2026, limit=5)
+print(scheffler["name"], results)
+```
+
+## 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 birdieapi 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 "birdieapi[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 birdieapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_tournaments()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://birdieapi.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 $BIRDIEAPI_API_KEY
+    base_url="https://mcp.birdieapi.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_tournaments)`).
+
+| Method | Credits | What it does |
+| --- | --- | --- |
+| `list_tournaments` | 1 | List tournaments |
+| `get_schedule` | 1 | Schedule |
+| `get_leaderboard` | 2 | Leaderboard |
+| `get_course` | 2 | Course |
+| `search_players` | 1 | Search players |
+| `get_player` | 5 | Player |
+| `get_player_results` | 5 | Player results |
+| `get_player_stats` | 5 | Player stats |
+| `get_scorecard` | 2 | Scorecard |
+| `get_course_history` | 5 | Course history |
+| `get_head_to_head` | 5 | Head to head |
+| `get_ratings` | 2 | Ratings |
+| `get_leaders` | 5 | Leaders |
+| `get_winner_odds` | 5 | Winner odds |
+
+Full API reference: https://birdieapi.com/docs
+
+## License
+
+MIT

birdieapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+birdieapi/__init__.py,sha256=NiicMIy_okR7a3JvZ5_Y9IR3oeEWA5gdRwNp2ywT2vg,510
+birdieapi/_core.py,sha256=4zyKuW-zKf3LnxwXYRF4kNV2JiomWxhNzCjIXHSVRQ8,10604
+birdieapi/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+birdieapi/client.py,sha256=5OXc4bMy2iMOGaN_X9g93767RQc9nMGUcY0uVKPGOWc,19838
+birdieapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+birdieapi-0.1.0.dist-info/METADATA,sha256=_AZuCwXF_iO10Sa6bBwVI_Rdl2aw8RLfweLOGyhRKzg,6038
+birdieapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+birdieapi-0.1.0.dist-info/licenses/LICENSE,sha256=jZbcZfjQOO4cnpy0N68uhPi2HgElF8sPB80CmySOqnM,1066
+birdieapi-0.1.0.dist-info/RECORD,,

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

birdieapi-0.1.0.dist-info/licenses/LICENSE

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