acesapi 0.1.0__py3-none-any.whl

acesapi/__init__.py

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

acesapi/_core.py

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

acesapi/_version.py

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

acesapi/client.py

@@ -0,0 +1,518 @@
+"""Generated by packages/python/generate.py from the AcesAPI 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_tournament": 2,
+    "get_matches": 2,
+    "get_schedule": 2,
+    "get_match": 2,
+    "search_players": 1,
+    "get_player": 5,
+    "get_player_matches": 5,
+    "get_head_to_head": 3,
+    "get_surface_splits": 3,
+    "get_player_stats": 3,
+    "get_rankings": 2,
+    "get_ratings": 2,
+}
+
+
+class Client(BaseClient):
+    """Client for the AcesAPI API (tennis).
+
+    Create one with ``Client()`` (reads ACESAPI_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,
+        surface: Optional[Literal["hard", "clay", "grass", "carpet"]] = None,
+        status: Optional[Literal["scheduled", "live", "final"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """List tournaments.
+
+        Use to find tournaments. Lists a season's tournaments in calendar order with dates, city,
+        surface, whether it is a Grand Slam, status, main-draw match count and the champion. Filter by
+        surface (hard, clay, grass, carpet) and status. Tour: atp (default) or wta; on the shared
+        endpoint pass league: "wta" for the WTA. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            season (optional): Year, e.g. 2025 (default this year).
+            surface (optional): Only tournaments on this surface. One of: hard, clay, grass, carpet.
+            status (optional): Only upcoming, in-progress or completed tournaments. One of: scheduled,
+                live, final.
+            limit (optional): Max tournaments (default 100).
+            offset (optional): Page offset; use next_offset.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_tournaments",
+            {
+                "season": season,
+                "surface": surface,
+                "status": status,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_tournament(
+        self,
+        tournament_id: str,
+        *,
+        draw: Optional[Literal["main", "qualifying", "all"]] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Tournament.
+
+        Use for a tournament's draw and results: every singles match of one edition grouped by round in
+        draw order (qualifying, then the main draw to the final), each with the score by set and
+        tiebreak points, seeds, and the champion and runner-up. draw: main (default), qualifying or all.
+        Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2
+        credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            tournament_id: Tournament edition id from list_tournaments, e.g. "188-2025".
+            draw (optional): Which draw (default main). One of: main, qualifying, all.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_tournament",
+            {
+                "tournament_id": tournament_id,
+                "draw": draw,
+                "league": league,
+            },
+        )
+
+    def get_matches(
+        self,
+        *,
+        date: Optional[str] = None,
+        tournament_id: Optional[str] = None,
+        season: Optional[Union[str, int, float]] = None,
+        round: Optional[str] = None,
+        status: Optional[Literal["scheduled", "live", "final"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Matches.
+
+        Use for match results by day, tournament or season: each match with both players, seeds, round,
+        status, score and sets (games and tiebreak points). Pass a date (YYYY-MM-DD, UTC), a
+        tournament_id or a season; filter by round (e.g. "Final") and status. Tour: atp (default) or
+        wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            date (optional): UTC date, YYYY-MM-DD.
+            tournament_id (optional): Tournament edition id, e.g. "188-2025".
+            season (optional): Year.
+            round (optional): Round name as listed, e.g. "Final", "Semifinal", "Round 1".
+            status (optional): One of: scheduled, live, final.
+            limit (optional): Max matches (default 100).
+            offset (optional): offset
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_matches",
+            {
+                "date": date,
+                "tournament_id": tournament_id,
+                "season": season,
+                "round": round,
+                "status": status,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_schedule(
+        self,
+        *,
+        days: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Schedule.
+
+        Use for upcoming matches: every scheduled or in-progress singles match in the next N days
+        (default 7, max 30) with players, seeds, round and start time where ESPN has set one. Tour: atp
+        (default) or wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            days (optional): Days ahead (default 7).
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_schedule",
+            {
+                "days": days,
+                "league": league,
+            },
+        )
+
+    def get_match(
+        self,
+        match_id: str,
+        *,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Match.
+
+        Use for everything about one match: the score by set with tiebreak points, seeds, each player's
+        sets, games and tiebreaks won, both players' ratings before and after (overall and on the
+        surface), and what the score says (total games, tiebreaks, whether it went the distance,
+        comebacks). No serve statistics: ESPN does not publish them. Tour: atp (default) or wta; on the
+        shared endpoint pass league: "wta" for the WTA. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            match_id: Match id from get_tournament, get_matches or get_player_matches.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_match",
+            {
+                "match_id": match_id,
+                "league": league,
+            },
+        )
+
+    def search_players(
+        self,
+        *,
+        name: Optional[str] = None,
+        country: Optional[str] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Search players.
+
+        Use to find a player's id. Search by name (accents optional) and/or country code (e.g. ITA);
+        most-played first, with matches, last match and rank on the current list (null outside ESPN's
+        top 100 to 150). Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the
+        WTA. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            name (optional): Part of the player's name, e.g. "sinner".
+            country (optional): Three-letter country code, e.g. ESP.
+            limit (optional): Max players (default 20).
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "search_players",
+            {
+                "name": name,
+                "country": country,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_player(
+        self,
+        player_id: str,
+        *,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Player.
+
+        Use for a player profile: date of birth, country, height, playing hand; latest ranking; our
+        rating overall and per surface with peak; career record (wins, losses, sets, games, tiebreaks,
+        deciding sets), titles, finals and Grand Slam titles; record by surface; and the last 10
+        matches. Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA.
+        Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player",
+            {
+                "player_id": player_id,
+                "league": league,
+            },
+        )
+
+    def get_player_matches(
+        self,
+        player_id: str,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        surface: Optional[Literal["hard", "clay", "grass", "carpet"]] = None,
+        opponent_id: Optional[str] = None,
+        tournament_id: Optional[str] = None,
+        draw: Optional[Literal["main", "qualifying"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Player matches.
+
+        Use for a player's matches, newest first: tournament, surface, round, opponent, result, score by
+        set and the player's rating before and after. Filter by season, surface, opponent_id,
+        tournament_id or draw. Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for
+        the WTA. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            season (optional): Year.
+            surface (optional): One of: hard, clay, grass, carpet.
+            opponent_id (optional): Only matches against this player.
+            tournament_id (optional): Only this tournament edition, e.g. "188-2025".
+            draw (optional): One of: main, qualifying.
+            limit (optional): Max matches (default 50).
+            offset (optional): offset
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_matches",
+            {
+                "player_id": player_id,
+                "season": season,
+                "surface": surface,
+                "opponent_id": opponent_id,
+                "tournament_id": tournament_id,
+                "draw": draw,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_head_to_head(
+        self,
+        player_id: str,
+        opponent_id: str,
+        *,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Head to head.
+
+        Use for two players' head to head: wins each, sets won, wins by surface and in finals, and every
+        meeting with its score. Walkovers are listed but not counted as wins; incomplete records are not
+        counted. Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA.
+        Costs 3 credits.
+
+        Costs 3 credits per call.
+
+        Args:
+            player_id: First player id.
+            opponent_id: Second player id.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_head_to_head",
+            {
+                "player_id": player_id,
+                "opponent_id": opponent_id,
+                "league": league,
+            },
+        )
+
+    def get_surface_splits(
+        self,
+        player_id: str,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        by_season: Optional[bool] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Surface splits.
+
+        Use for a player's record by surface (hard, clay, grass, carpet): wins, losses, win rate, sets,
+        share of games won, tiebreaks, deciding sets and 6-0 sets, plus the current surface ratings. For
+        one season or the whole career; by_season splits each surface by year. Tour: atp (default) or
+        wta; on the shared endpoint pass league: "wta" for the WTA. Costs 3 credits.
+
+        Costs 3 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            season (optional): Year (default the whole career).
+            by_season (optional): Split each surface by season.
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_surface_splits",
+            {
+                "player_id": player_id,
+                "season": season,
+                "by_season": by_season,
+                "league": league,
+            },
+        )
+
+    def get_player_stats(
+        self,
+        player_id: str,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Player stats.
+
+        Use for a player's match statistics by season: wins, losses, sets and games won, tiebreaks won
+        and lost, deciding sets, 6-0 sets and retirements, all counted from scores; plus the record by
+        round and by the opponent's ranking (top 10, 11-50, 51-100). No serve statistics: ESPN does not
+        publish them. Tour: atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA.
+        Costs 3 credits.
+
+        Costs 3 credits per call.
+
+        Args:
+            player_id: Player id from search_players.
+            season (optional): Year (default every season).
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_player_stats",
+            {
+                "player_id": player_id,
+                "season": season,
+                "league": league,
+            },
+        )
+
+    def get_rankings(
+        self,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        week: Optional[int] = None,
+        date: Optional[str] = None,
+        player_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Rankings.
+
+        Use for the ranking list: the latest (default), or a season and week, or the list in force on a
+        date, with rank, previous rank, points and player. Pass player_id instead for one player's
+        ranking history. ESPN keeps the top 100 to 150 for most weeks since 2007. Tour: atp (default) or
+        wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            season (optional): Year.
+            week (optional): Week number of the season.
+            date (optional): The list in force on this date, YYYY-MM-DD.
+            player_id (optional): One player's ranking history instead of a list.
+            limit (optional): Max rows of a list (default 100).
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_rankings",
+            {
+                "season": season,
+                "week": week,
+                "date": date,
+                "player_id": player_id,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_ratings(
+        self,
+        *,
+        surface: Optional[Literal["hard", "clay", "grass", "carpet"]] = None,
+        active_since: Optional[str] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["tennis", "wta"]] = None,
+    ) -> Any:
+        """Ratings.
+
+        Use for our Elo ratings, highest first: overall, or on one surface (hard, clay, grass). Players
+        with a rated match since active_since (default a year ago) and at least 10 rated matches. Tour:
+        atp (default) or wta; on the shared endpoint pass league: "wta" for the WTA. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            surface (optional): Rank by the surface rating instead of overall. One of: hard, clay,
+                grass, carpet.
+            active_since (optional): Only players with a rated match since this date, YYYY-MM-DD
+                (default one year ago).
+            limit (optional): Max players (default 50).
+            league (optional): League. Defaults to tennis. One of: tennis, wta.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_ratings",
+            {
+                "surface": surface,
+                "active_since": active_since,
+                "limit": limit,
+                "league": league,
+            },
+        )

acesapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: acesapi
+Version: 0.1.0
+Summary: Python client for the AcesAPI tennis data API. No dependencies.
+Project-URL: Homepage, https://acesapi.com
+Project-URL: Documentation, https://acesapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://acesapi.com/signup
+Author-email: AcesAPI <support@acesapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acesapi,api-client,betting,odds,player-props,sports-data,tennis
+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
+
+# AcesAPI for Python
+
+Python client for the [AcesAPI](https://acesapi.com) tennis 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 acesapi
+pip install "acesapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://acesapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export ACESAPI_API_KEY=your_key_here
+```
+
+```python
+from acesapi import Client
+
+client = Client()                      # reads ACESAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Current rankings
+
+ATP is the default tour. Pass `league="wta"` for the women's tour.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+ranks = client.get_rankings(limit=5)
+for row in ranks["rankings"]:
+    print(row["rank"], row["name"], row["points"])
+```
+
+### 2. Head to head
+
+Look up two player ids with `search_players`, then compare them.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+alcaraz = client.search_players(name="Alcaraz", limit=1)["players"][0]
+h2h = client.get_head_to_head(sinner["player_id"], alcaraz["player_id"])
+print(sinner["name"], "vs", alcaraz["name"])
+print("matches:", h2h["summary"]["matches"])
+print("wins:", h2h["summary"]["wins"])
+```
+
+### 3. Results by surface
+
+`get_surface_splits` shows how a player does on hard, clay and grass.
+
+```python
+from acesapi import Client
+
+client = Client()
+
+sinner = client.search_players(name="Sinner", limit=1)["players"][0]
+splits = client.get_surface_splits(sinner["player_id"])
+for row in splits["splits"]:
+    print(row["surface"], row["wins"], "-", row["losses"], row["win_pct"])
+```
+
+## 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 acesapi 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 "acesapi[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 acesapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_tournaments()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://acesapi.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 $ACESAPI_API_KEY
+    base_url="https://mcp.acesapi.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_tournament` | 2 | Tournament |
+| `get_matches` | 2 | Matches |
+| `get_schedule` | 2 | Schedule |
+| `get_match` | 2 | Match |
+| `search_players` | 1 | Search players |
+| `get_player` | 5 | Player |
+| `get_player_matches` | 5 | Player matches |
+| `get_head_to_head` | 3 | Head to head |
+| `get_surface_splits` | 3 | Surface splits |
+| `get_player_stats` | 3 | Player stats |
+| `get_rankings` | 2 | Rankings |
+| `get_ratings` | 2 | Ratings |
+
+Full API reference: https://acesapi.com/docs
+
+## License
+
+MIT

acesapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+acesapi/__init__.py,sha256=QP2-5MzYJSBnmubzaGvbYZTpfC4A5qSseio3Df19t0c,508
+acesapi/_core.py,sha256=Q-Ks1j9kBI7MJlzYktUm_-MrgJSBkFj6l6ztAWzT13E,10594
+acesapi/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+acesapi/client.py,sha256=zTpezgIAEUZ4WvkQEpp6IIGQ-GLjAwbKooDgnBa_Rxs,18673
+acesapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+acesapi-0.1.0.dist-info/METADATA,sha256=GGaxFkb_f4CsatXVTu3bt9QrCewxuL-Av4C46Xd-5vg,6199
+acesapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+acesapi-0.1.0.dist-info/licenses/LICENSE,sha256=8DCMeriFDveJPVNKBZ_wIStWeud4JxPLa_-T3GVio8A,1064
+acesapi-0.1.0.dist-info/RECORD,,

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

acesapi-0.1.0.dist-info/licenses/LICENSE

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