fighterapi 0.1.0__py3-none-any.whl

fighterapi/__init__.py

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

fighterapi/_core.py

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

fighterapi/_version.py

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

fighterapi/client.py

@@ -0,0 +1,402 @@
+"""Generated by packages/python/generate.py from the FighterAPI 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_events": 1,
+    "get_event": 2,
+    "get_schedule": 2,
+    "get_fight": 5,
+    "search_fighters": 1,
+    "get_fighter": 5,
+    "get_fighter_fights": 5,
+    "get_leaders": 5,
+    "get_ratings": 2,
+    "get_odds": 5,
+    "get_line_movement": 10,
+}
+
+
+class Client(BaseClient):
+    """Client for the FighterAPI API (MMA).
+
+    Create one with ``Client()`` (reads FIGHTERAPI_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_events(
+        self,
+        *,
+        season: Optional[Union[str, int, float]] = None,
+        status: Optional[Literal["scheduled", "final"]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """List events.
+
+        Use to find cards. Lists events newest first with the venue, status, number of fights and main
+        event. Filter by season (year) and status (scheduled or final). Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            season (optional): Year, e.g. 2025.
+            status (optional): Only upcoming or only completed cards. One of: scheduled, final.
+            limit (optional): Max events (default 50).
+            offset (optional): Page offset; use next_offset.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "list_events",
+            {
+                "season": season,
+                "status": status,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_event(
+        self,
+        event_id: str,
+        *,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Event.
+
+        Use for one card: every fight in order with the result, method, round and time, judges' scores
+        and referee. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            event_id: Event id from list_events or get_schedule.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_event",
+            {
+                "event_id": event_id,
+                "league": league,
+            },
+        )
+
+    def get_schedule(
+        self,
+        *,
+        days: Optional[int] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Schedule.
+
+        Use for upcoming fights: every scheduled bout in the next N days (default 30) with the current
+        moneyline from any book that has posted one. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            days (optional): Days ahead (default 30, max 180).
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_schedule",
+            {
+                "days": days,
+                "league": league,
+            },
+        )
+
+    def get_fight(
+        self,
+        bout_id: str,
+        *,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Fight.
+
+        Use for everything about one fight: the result, both fighters' full stat sheets (strikes by
+        target and position, takedowns, control time, guard passes, reversals, submission attempts; UFC
+        only, null elsewhere and where the source has no sheet), round-by-round lines (UFC only), each
+        fighter's rating before and after, and the opening and closing moneyline from each book that
+        posted one (2024 on). Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            bout_id: Fight id (bout_id) from get_event or get_fighter_fights.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_fight",
+            {
+                "bout_id": bout_id,
+                "league": league,
+            },
+        )
+
+    def search_fighters(
+        self,
+        query: str,
+        *,
+        weight_class: Optional[str] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Search fighters.
+
+        Use to find a fighter's id by name or nickname (accents optional). Returns weight class,
+        country, pro record, number of fights in the promotion (bouts; ufc_bouts for the UFC only) and
+        last fight date. Costs 1 credit.
+
+        Costs 1 credit per call.
+
+        Args:
+            query: Name or nickname, e.g. Topuria or 'El Matador'.
+            weight_class (optional): e.g. Lightweight, Women's Strawweight.
+            limit (optional): Max results (default 20).
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "search_fighters",
+            {
+                "query": query,
+                "weight_class": weight_class,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_fighter(
+        self,
+        fighter_id: str,
+        *,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Fighter.
+
+        Use for one fighter's profile: date of birth, height, reach, stance, gym, record in the
+        promotion by method (record; ufc_record is the same for the UFC and null for other promotions),
+        career rates per 15 minutes from the stat sheets (significant strikes landed and absorbed,
+        accuracy, defense, takedowns, submission attempts, control share; UFC only), current and peak
+        rating, and the last five fights. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            fighter_id: Fighter id from search_fighters.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_fighter",
+            {
+                "fighter_id": fighter_id,
+                "league": league,
+            },
+        )
+
+    def get_fighter_fights(
+        self,
+        fighter_id: str,
+        *,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Fighter fights.
+
+        Use for a fighter's full history in the promotion: every fight with the opponent, result,
+        method, round, time, strikes landed and absorbed and takedowns (UFC only), rating before and
+        after, and the median closing moneyline across sportsbooks. Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            fighter_id: Fighter id from search_fighters.
+            limit (optional): Max fights (default 50).
+            offset (optional): Page offset; use next_offset.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_fighter_fights",
+            {
+                "fighter_id": fighter_id,
+                "limit": limit,
+                "offset": offset,
+                "league": league,
+            },
+        )
+
+    def get_leaders(
+        self,
+        stat: Literal["sig_landed_per_15", "sig_absorbed_per_15", "sig_accuracy", "sig_defense", "td_per_15", "td_accuracy", "td_defense", "knockdowns", "sub_attempts_per_15", "control_share", "finish_rate"],
+        *,
+        weight_class: Optional[str] = None,
+        since: Optional[Union[str, int, float]] = None,
+        min_fights: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        """Leaders.
+
+        Use for career leaderboards computed from every fight's stat sheet: sig_landed_per_15
+        (significant strikes landed per 15 min), sig_absorbed_per_15 (significant strikes absorbed per
+        15 min), sig_accuracy (significant strike accuracy), sig_defense (significant strike defense),
+        td_per_15 (takedowns landed per 15 min), td_accuracy (takedown accuracy), td_defense (takedown
+        defense), knockdowns (knockdowns), sub_attempts_per_15 (submission attempts per 15 min),
+        control_share (share of fight time in control), finish_rate (wins by KO/TKO or submission, as a
+        share of wins). Filter by weight class, a starting year, and a minimum number of fights (default
+        5). Costs 5 credits.
+
+        Costs 5 credits per call.
+
+        Args:
+            stat: Which leaderboard. One of: sig_landed_per_15, sig_absorbed_per_15, sig_accuracy,
+                sig_defense, td_per_15, td_accuracy, td_defense, knockdowns, sub_attempts_per_15,
+                control_share, finish_rate.
+            weight_class (optional): Only fights in this weight class, e.g. Lightweight.
+            since (optional): Only fights from this year on, e.g. 2020.
+            min_fights (optional): Minimum fights to qualify (default 5).
+            limit (optional): Max fighters (default 20).
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_leaders",
+            {
+                "stat": stat,
+                "weight_class": weight_class,
+                "since": since,
+                "min_fights": min_fights,
+                "limit": limit,
+            },
+        )
+
+    def get_ratings(
+        self,
+        *,
+        weight_class: Optional[str] = None,
+        active_since: Optional[Union[str, int, float]] = None,
+        limit: Optional[int] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Ratings.
+
+        Use for our fighter ratings: an Elo built from the promotion's own results (the UFC since 2000),
+        highest first, for fighters active since a given year (default last year). Filter by weight
+        class. Costs 2 credits.
+
+        Costs 2 credits per call.
+
+        Args:
+            weight_class (optional): e.g. Welterweight.
+            active_since (optional): Only fighters whose last fight was in this year or later.
+            limit (optional): Max fighters (default 25).
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_ratings",
+            {
+                "weight_class": weight_class,
+                "active_since": active_since,
+                "limit": limit,
+                "league": league,
+            },
+        )
+
+    def get_odds(
+        self,
+        *,
+        bout_id: Optional[str] = None,
+        event_id: Optional[str] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Odds.
+
+        Use for betting lines: each posted sportsbook's opening, closing and current moneyline for both
+        fighters, with implied probabilities and the total-rounds line. Opening and closing lines start
+        with the UFC cards of June 2020; a median of 5 to 7 books per fight (ESPN's own feed is one book
+        per fight since mid-2024). Pass bout_id for one fight (5 credits) or event_id for a whole card
+        (10 credits).
+
+        Costs 5 credits per call.
+
+        Args:
+            bout_id (optional): One fight.
+            event_id (optional): A whole card.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_odds",
+            {
+                "bout_id": bout_id,
+                "event_id": event_id,
+                "league": league,
+            },
+        )
+
+    def get_line_movement(
+        self,
+        bout_id: str,
+        *,
+        provider: Optional[str] = None,
+        league: Optional[Literal["mma", "pfl", "bellator"]] = None,
+    ) -> Any:
+        """Line movement.
+
+        Use to see how a fight's line moved before the bell: our snapshots of each posted moneyline,
+        from first capture to fight day (ESPN's once a day from October 2026, The Odds API's every hour
+        in the two days before). Costs 10 credits.
+
+        Costs 10 credits per call.
+
+        Args:
+            bout_id: Fight id.
+            provider (optional): One sportsbook, e.g. DraftKings.
+            league (optional): League. Defaults to mma. One of: mma, pfl, bellator.
+
+        Returns:
+            The unwrapped ``data`` object from the response.
+        """
+        return self._call(
+            "get_line_movement",
+            {
+                "bout_id": bout_id,
+                "provider": provider,
+                "league": league,
+            },
+        )

fighterapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: fighterapi
+Version: 0.1.0
+Summary: Python client for the FighterAPI MMA data API. No dependencies.
+Project-URL: Homepage, https://fighterapi.com
+Project-URL: Documentation, https://fighterapi.com/docs
+Project-URL: Repository, https://github.com/noahowsh/puckapi
+Project-URL: Sign up, https://fighterapi.com/signup
+Author-email: FighterAPI <support@fighterapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,betting,fighterapi,mma,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
+
+# FighterAPI for Python
+
+Python client for the [FighterAPI](https://fighterapi.com) MMA 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 fighterapi
+pip install "fighterapi[pandas]"   # only if you want DataFrames
+```
+
+## Set your key
+
+Get a free key at https://fighterapi.com/signup. Free accounts get 500 credits a month.
+
+```bash
+export FIGHTERAPI_API_KEY=your_key_here
+```
+
+```python
+from fighterapi import Client
+
+client = Client()                      # reads FIGHTERAPI_API_KEY
+client = Client(api_key="your_key")    # or pass it in
+```
+
+## Examples
+
+### 1. Recent events
+
+`list_events` filters by season and status. Pass `league="pfl"` or `"bellator"` for other promotions.
+
+```python
+from fighterapi import Client
+
+client = Client()
+
+events = client.list_events(status="final", limit=3)["events"]
+for e in events:
+    print(e["event_id"], e["event_date"], e["name"])
+```
+
+### 2. A fight card
+
+`get_event` returns the bouts on one event.
+
+```python
+from fighterapi import Client
+
+client = Client()
+
+card = client.get_event("600061541")
+print(card)
+```
+
+### 3. A fighter's record
+
+Find the id with `search_fighters`, then pull his fight history.
+
+```python
+from fighterapi import Client
+
+client = Client()
+
+fighter = client.search_fighters("Makhachev", limit=1)["fighters"][0]
+fights = client.get_fighter_fights(fighter["fighter_id"], limit=5)
+print(fighter["name"], fights)
+```
+
+## 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 fighterapi 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 "fighterapi[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 fighterapi import Client, APIError, InsufficientCreditsError, RateLimitError
+
+client = Client()
+try:
+    data = client.list_events()
+except InsufficientCreditsError:
+    print("Out of credits, top up at https://fighterapi.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 $FIGHTERAPI_API_KEY
+    base_url="https://mcp.fighterapi.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_events)`).
+
+| Method | Credits | What it does |
+| --- | --- | --- |
+| `list_events` | 1 | List events |
+| `get_event` | 2 | Event |
+| `get_schedule` | 2 | Schedule |
+| `get_fight` | 5 | Fight |
+| `search_fighters` | 1 | Search fighters |
+| `get_fighter` | 5 | Fighter |
+| `get_fighter_fights` | 5 | Fighter fights |
+| `get_leaders` | 5 | Leaders |
+| `get_ratings` | 2 | Ratings |
+| `get_odds` | 5 | Odds |
+| `get_line_movement` | 10 | Line movement |
+
+Full API reference: https://fighterapi.com/docs
+
+## License
+
+MIT

fighterapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+fighterapi/__init__.py,sha256=LJNQAaYcXr3e-wdAeNRu0SxI_F8YKYYETOlHjoJZ6RE,511
+fighterapi/_core.py,sha256=1hlUDyXd2tJ9hsCdKphFaqp-lSfyzrRff7DEF5zKjFM,10609
+fighterapi/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fighterapi/client.py,sha256=kTBWwdL98AcglMDEeFmfDJ1X7mKA7CQFqNBuZEnU02s,13845
+fighterapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fighterapi-0.1.0.dist-info/METADATA,sha256=mv6DfRk-RxhrMtZBHtqLZE2kqtq-T9eDvz8nkttFaYM,5819
+fighterapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fighterapi-0.1.0.dist-info/licenses/LICENSE,sha256=IOWMvk6uaPzhTuyLCjGmy-Uwmuy0rzc7oGufSqpEqP4,1067
+fighterapi-0.1.0.dist-info/RECORD,,

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

fighterapi-0.1.0.dist-info/licenses/LICENSE

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