pitchapi 0.1.0__py3-none-any.whl

pitchapi/__init__.py

@@ -0,0 +1,44 @@
+"""PitchAPI — Python SDK for the PitchAPI football-data API.
+
+Example:
+    from pitchapi import PitchAPI
+
+    with PitchAPI(api_key="pk_live_...") as client:
+        for m in client.date.get("2026-08-27").matches:
+            print(m.home_team.name, m.score_home, "-", m.score_away, m.away_team.name)
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import models
+from .client import AsyncPitchAPI, PitchAPI
+from .errors import (
+    APIConnectionError,
+    AuthError,
+    InvalidParameterError,
+    NotFoundError,
+    PitchAPIError,
+    PlanUpgradeRequiredError,
+    RateLimitError,
+    ServerError,
+    SubscriptionSuspendedError,
+)
+
+__all__ = [
+    "__version__",
+    "PitchAPI",
+    "AsyncPitchAPI",
+    "models",
+    # errors
+    "PitchAPIError",
+    "APIConnectionError",
+    "InvalidParameterError",
+    "AuthError",
+    "SubscriptionSuspendedError",
+    "PlanUpgradeRequiredError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

pitchapi/_transport.py

@@ -0,0 +1,101 @@
+"""Transport-level helpers shared by the sync and async clients.
+
+Keeping envelope handling, error mapping, and the retry policy here means the
+two clients differ only in how they run the HTTP call itself, not in how they
+interpret the result.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Any, Optional
+
+from . import __version__
+from .errors import (
+    PitchAPIError,
+    RateLimitError,
+    ServerError,
+    exception_for_code,
+)
+
+DEFAULT_BASE_URL = "https://api.pitchapi.dev"
+API_PREFIX = "/v1"
+
+# Statuses that a GET may safely be replayed on. Everything else (400/401/403/
+# 404) is a deterministic client error and is surfaced immediately.
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+def user_agent() -> str:
+    return f"pitchapi-python/{__version__}"
+
+
+def build_headers(api_key: str, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+    headers = {
+        "X-API-KEY": api_key,
+        "Accept": "application/json",
+        "User-Agent": user_agent(),
+    }
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def should_retry(status: int, attempt: int, max_retries: int) -> bool:
+    return attempt < max_retries and status in _RETRY_STATUSES
+
+
+def backoff_seconds(attempt: int, retry_after: Optional[int]) -> float:
+    """Delay before the next attempt.
+
+    Honours a server-provided ``Retry-After`` exactly; otherwise falls back to
+    exponential backoff with full jitter so retried clients do not synchronise.
+    """
+    if retry_after is not None and retry_after >= 0:
+        return float(retry_after)
+    base = min(2.0**attempt, 8.0)
+    return random.uniform(0.0, base)
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def unwrap(status: int, payload: Any, request_id: Optional[str], retry_after: Optional[int]) -> Any:
+    """Return the ``data`` object on success, or raise the mapped exception.
+
+    ``payload`` is the already-decoded JSON body, or ``None`` when the body was
+    absent or not JSON (which is itself an error for this API).
+    """
+    if 200 <= status < 300:
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        # A 2xx without the envelope should not happen; surface it rather than
+        # hand back a shape the models cannot parse.
+        raise PitchAPIError(
+            "malformed success response: missing 'data' envelope",
+            status_code=status,
+            request_id=request_id,
+        )
+
+    code: Optional[str] = None
+    message = f"HTTP {status}"
+    if isinstance(payload, dict):
+        err = payload.get("error")
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message", message)
+
+    exc_cls = exception_for_code(code, status)
+    if exc_cls is RateLimitError:
+        raise RateLimitError(
+            message, retry_after=retry_after, code=code, status_code=status, request_id=request_id
+        )
+    if exc_cls is ServerError and code is None:
+        message = f"server error (HTTP {status})"
+    raise exc_cls(message, code=code, status_code=status, request_id=request_id)

pitchapi/client.py

@@ -0,0 +1,184 @@
+"""Synchronous and asynchronous entry-point clients.
+
+Both wrap an :mod:`httpx` client and share every policy decision through
+:mod:`pitchapi._transport`. Resource namespaces hang off each instance:
+
+    >>> from pitchapi import PitchAPI
+    >>> client = PitchAPI(api_key="pk_live_...")
+    >>> match = client.matches.get("m_4DP2fy")
+
+Prefer a context manager (or call :meth:`close` / :meth:`aclose`) so the
+underlying connection pool is released.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Optional
+
+import httpx
+
+from . import resources
+from ._transport import (
+    API_PREFIX,
+    DEFAULT_BASE_URL,
+    backoff_seconds,
+    build_headers,
+    parse_retry_after,
+    should_retry,
+    unwrap,
+)
+from .errors import APIConnectionError
+
+_ENV_API_KEY = "PITCHAPI_API_KEY"
+_ENV_BASE_URL = "PITCHAPI_BASE_URL"
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get(_ENV_API_KEY)
+    if not key:
+        raise ValueError(
+            "an API key is required: pass api_key=... or set the "
+            f"{_ENV_API_KEY} environment variable"
+        )
+    return key
+
+
+def _resolve_base_url(base_url: Optional[str]) -> str:
+    return (base_url or os.environ.get(_ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _decode_json(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+class PitchAPI:
+    """Synchronous PitchAPI client.
+
+    Args:
+        api_key: A ``pk_live_`` / ``pk_test_`` key. Falls back to the
+            ``PITCHAPI_API_KEY`` environment variable.
+        base_url: Override the API host (mainly for testing / self-hosting).
+        timeout: Per-request timeout in seconds.
+        max_retries: How many times to replay a request on 429/5xx and network
+            errors. ``0`` disables retries.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        _http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = _resolve_base_url(base_url)
+        self._max_retries = max_retries
+        self._http = _http_client or httpx.Client(
+            timeout=timeout, headers=build_headers(self._api_key)
+        )
+
+        self.matches = resources.Matches(self)
+        self.leagues = resources.Leagues(self)
+        self.teams = resources.Teams(self)
+        self.players = resources.Players(self)
+        self.date = resources.Date(self)
+
+    # ── transport ──────────────────────────────────────────
+    def _get(self, path: str, params: Optional[dict[str, str]] = None) -> Any:
+        url = self._base_url + API_PREFIX + path
+        attempt = 0
+        while True:
+            try:
+                response = self._http.get(url, params=params)
+            except httpx.RequestError as exc:
+                if attempt < self._max_retries:
+                    time.sleep(backoff_seconds(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"request failed: {exc}") from exc
+
+            status = response.status_code
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+            if should_retry(status, attempt, self._max_retries):
+                time.sleep(backoff_seconds(attempt, retry_after))
+                attempt += 1
+                continue
+
+            request_id = response.headers.get("X-Request-ID")
+            return unwrap(status, _decode_json(response), request_id, retry_after)
+
+    # ── lifecycle ──────────────────────────────────────────
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "PitchAPI":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncPitchAPI:
+    """Asynchronous PitchAPI client — the async twin of :class:`PitchAPI`."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        _http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._api_key = _resolve_api_key(api_key)
+        self._base_url = _resolve_base_url(base_url)
+        self._max_retries = max_retries
+        self._http = _http_client or httpx.AsyncClient(
+            timeout=timeout, headers=build_headers(self._api_key)
+        )
+
+        self.matches = resources.AsyncMatches(self)
+        self.leagues = resources.AsyncLeagues(self)
+        self.teams = resources.AsyncTeams(self)
+        self.players = resources.AsyncPlayers(self)
+        self.date = resources.AsyncDate(self)
+
+    async def _get(self, path: str, params: Optional[dict[str, str]] = None) -> Any:
+        url = self._base_url + API_PREFIX + path
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.get(url, params=params)
+            except httpx.RequestError as exc:
+                if attempt < self._max_retries:
+                    await asyncio.sleep(backoff_seconds(attempt, None))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"request failed: {exc}") from exc
+
+            status = response.status_code
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+            if should_retry(status, attempt, self._max_retries):
+                await asyncio.sleep(backoff_seconds(attempt, retry_after))
+                attempt += 1
+                continue
+
+            request_id = response.headers.get("X-Request-ID")
+            return unwrap(status, _decode_json(response), request_id, retry_after)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncPitchAPI":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

pitchapi/errors.py

@@ -0,0 +1,128 @@
+"""Exception hierarchy for the PitchAPI SDK.
+
+Every error the API returns carries a stable ``error.code`` string in its
+envelope. Exceptions are mapped from that code first and the HTTP status second,
+so callers can branch on a semantic type rather than parsing status numbers.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PitchAPIError(Exception):
+    """Base class for every error raised by the SDK.
+
+    Attributes:
+        message: Human-readable description from the API (or the SDK).
+        code: The stable ``error.code`` string, when the failure came from the
+            API envelope. ``None`` for transport-level failures.
+        status_code: The HTTP status, when there was a response.
+        request_id: The ``X-Request-ID`` echoed by the API, useful in support.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"code={self.code}")
+        if self.status_code:
+            parts.append(f"status={self.status_code}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+        return " ".join(parts) if len(parts) == 1 else f"{parts[0]} ({', '.join(parts[1:])})"
+
+
+class APIConnectionError(PitchAPIError):
+    """The request never produced a response (network error, timeout, DNS)."""
+
+
+class InvalidParameterError(PitchAPIError):
+    """400 INVALID_PARAMETER — a malformed ID, date, or season."""
+
+
+class AuthError(PitchAPIError):
+    """401 UNAUTHORIZED — the API key is missing, malformed, or revoked."""
+
+
+class SubscriptionSuspendedError(PitchAPIError):
+    """403 SUBSCRIPTION_SUSPENDED — the account's subscription is not active."""
+
+
+class PlanUpgradeRequiredError(PitchAPIError):
+    """403 PLAN_UPGRADE_REQUIRED — the resource's league is Pro-only."""
+
+
+class NotFoundError(PitchAPIError):
+    """404 — the resource does not exist, or its analytics are unavailable.
+
+    ``code`` distinguishes ``RESOURCE_NOT_FOUND`` from ``ANALYTICS_UNAVAILABLE``.
+    """
+
+
+class RateLimitError(PitchAPIError):
+    """429 RATE_LIMIT_EXCEEDED — the per-user fair-use ceiling was hit.
+
+    ``retry_after`` is the number of seconds the API asked the client to wait,
+    taken from the ``Retry-After`` header. ``None`` if the header was absent.
+    """
+
+    def __init__(
+        self, message: str, *, retry_after: Optional[int] = None, **kwargs: object
+    ) -> None:
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+        self.retry_after = retry_after
+
+
+class ServerError(PitchAPIError):
+    """5xx — the API failed to serve the request."""
+
+
+# Maps the API's stable error.code onto an exception class. HTTP status is the
+# fallback when a code is absent or unrecognised (see _transport.raise_for).
+_CODE_MAP = {
+    "INVALID_PARAMETER": InvalidParameterError,
+    "UNAUTHORIZED": AuthError,
+    "SUBSCRIPTION_SUSPENDED": SubscriptionSuspendedError,
+    "PLAN_UPGRADE_REQUIRED": PlanUpgradeRequiredError,
+    "RESOURCE_NOT_FOUND": NotFoundError,
+    "ANALYTICS_UNAVAILABLE": NotFoundError,
+    "RATE_LIMIT_EXCEEDED": RateLimitError,
+    "INTERNAL_SERVER_ERROR": ServerError,
+}
+
+
+def exception_for_code(code: Optional[str], status_code: int) -> type[PitchAPIError]:
+    """Pick the exception class for an error response.
+
+    Prefers the semantic ``code``; falls back to a coarse mapping by HTTP status
+    so an unrecognised code still lands on a sensible type.
+    """
+    if code and code in _CODE_MAP:
+        return _CODE_MAP[code]
+    if status_code == 400:
+        return InvalidParameterError
+    if status_code == 401:
+        return AuthError
+    if status_code == 403:
+        return PlanUpgradeRequiredError
+    if status_code == 404:
+        return NotFoundError
+    if status_code == 429:
+        return RateLimitError
+    if status_code >= 500:
+        return ServerError
+    return PitchAPIError

pitchapi/models/__init__.py

@@ -0,0 +1,127 @@
+"""Response dataclasses, a declarative mirror of the API's JSON shapes.
+
+Build one from a raw ``data`` object with :func:`from_dict`, though most callers
+never do so directly — the resource methods return fully built models.
+"""
+
+from ._convert import from_dict
+from .advanced import (
+    AdvancedNetworks,
+    AdvancedPlayers,
+    AdvancedPlayerStat,
+    AdvancedTeams,
+    AdvancedTeamStat,
+    CarryingStats,
+    Goalkeeping,
+    NetworkWindow,
+    PassingStats,
+    PassNetwork,
+    PassNetworkEdge,
+    PassNetworkNode,
+    PlayerCreation,
+    PlayerDefending,
+    PlayerSCABreakdown,
+    PossessionValue,
+    TeamCreation,
+    TeamDefending,
+    TeamSCABreakdown,
+    TempoStats,
+    TerritoryStats,
+)
+from .common import (
+    AdvancedPlayerRef,
+    CoachRef,
+    LeagueRef,
+    PlayerRef,
+    TeamNameRef,
+    TeamRef,
+)
+from .event import Event, Events
+from .h2h import H2H, H2HMatch
+from .league import (
+    League,
+    LeagueMatches,
+    LeagueMatchSummary,
+    LeagueSeasonRef,
+    LeaguesList,
+    LeagueSummary,
+)
+from .lineup import LineupPlayer, Lineups, LineupSide
+from .match import DateMatches, Match, MatchSummary
+from .momentum import Momentum, MomentumPoint
+from .player import PlayerDetail, PlayerMatchStats, PlayerProfile
+from .shot import PlayerShots, Shot, ShotPeriod, Shots
+from .stats import MatchStatGroup, MatchStatItem, MatchStatPeriod, MatchStats
+from .team import Team
+
+__all__ = [
+    "from_dict",
+    # common
+    "LeagueRef",
+    "TeamRef",
+    "TeamNameRef",
+    "PlayerRef",
+    "AdvancedPlayerRef",
+    "CoachRef",
+    # match / date
+    "Match",
+    "MatchSummary",
+    "DateMatches",
+    # shots
+    "Shot",
+    "ShotPeriod",
+    "Shots",
+    "PlayerShots",
+    # events
+    "Event",
+    "Events",
+    # lineups
+    "LineupPlayer",
+    "LineupSide",
+    "Lineups",
+    # momentum
+    "MomentumPoint",
+    "Momentum",
+    # stats
+    "MatchStatItem",
+    "MatchStatGroup",
+    "MatchStatPeriod",
+    "MatchStats",
+    # h2h
+    "H2HMatch",
+    "H2H",
+    # leagues
+    "League",
+    "LeagueSummary",
+    "LeaguesList",
+    "LeagueSeasonRef",
+    "LeagueMatchSummary",
+    "LeagueMatches",
+    # teams / players
+    "Team",
+    "PlayerProfile",
+    "PlayerMatchStats",
+    "PlayerDetail",
+    # advanced
+    "PossessionValue",
+    "PassingStats",
+    "CarryingStats",
+    "TeamSCABreakdown",
+    "TeamCreation",
+    "PlayerSCABreakdown",
+    "PlayerCreation",
+    "PlayerDefending",
+    "TeamDefending",
+    "TerritoryStats",
+    "TempoStats",
+    "Goalkeeping",
+    "AdvancedTeamStat",
+    "AdvancedTeams",
+    "AdvancedPlayerStat",
+    "AdvancedPlayers",
+    "NetworkWindow",
+    "PassNetworkNode",
+    "PassNetworkEdge",
+    "PassNetwork",
+    "AdvancedNetworks",
+]

pitchapi/models/_convert.py

@@ -0,0 +1,79 @@
+"""Generic ``from_dict`` for the response dataclasses.
+
+Every response model is a plain :func:`dataclasses.dataclass`. Rather than hand-
+writing a constructor per model, :func:`from_dict` walks a class's fields and
+their type hints and builds the object recursively. This keeps the models a
+faithful, declarative mirror of the Go response structs.
+
+Design notes:
+    * Annotations are real type objects (the model modules deliberately do *not*
+      ``from __future__ import annotations``), so ``field.type`` can be read
+      directly without resolving forward references.
+    * A JSON key that differs from the Python attribute name — e.g. the reserved
+      word ``from`` — is declared via ``field(metadata={"json": "from"})``.
+    * Unknown JSON keys are ignored and missing keys default to ``None``, so a
+      new field added server-side never breaks an older client.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import typing
+from typing import Any, TypeVar, Union, cast
+
+_NoneType = type(None)
+
+T = TypeVar("T")
+
+
+def _unwrap_optional(tp: Any) -> tuple[Any, bool]:
+    """Return ``(inner, is_optional)`` for ``Optional[T]`` / ``Union[T, None]``."""
+    if typing.get_origin(tp) is Union:
+        args = [a for a in typing.get_args(tp) if a is not _NoneType]
+        if len(args) == 1:
+            return args[0], True
+        return tp, True
+    return tp, False
+
+
+def _convert_value(tp: Any, value: Any) -> Any:
+    if value is None:
+        return None
+
+    tp, _ = _unwrap_optional(tp)
+    origin = typing.get_origin(tp)
+
+    if origin in (list, typing.List):
+        (elem_tp,) = typing.get_args(tp) or (Any,)
+        return [_convert_value(elem_tp, v) for v in value]
+
+    if origin in (dict, typing.Dict):
+        return value  # raw pass-through (e.g. the variable player stats blob)
+
+    # ``isinstance(tp, type)`` is not redundant: it rules out the parameterised
+    # generics and special forms that also reach here, and it is what lets
+    # from_dict be typed as taking a class rather than an instance-or-class.
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp) and isinstance(value, dict):
+        return from_dict(tp, value)
+
+    return value
+
+
+def from_dict(cls: type[T], data: dict[str, Any]) -> T:
+    """Instantiate dataclass ``cls`` from an API ``data`` object.
+
+    Generic in ``cls`` so that callers get the concrete model type back rather
+    than ``Any`` — without it every resource method would silently widen its
+    own declared return type.
+    """
+    if not dataclasses.is_dataclass(cls):
+        raise TypeError(f"{cls!r} is not a dataclass")
+
+    kwargs: dict[str, Any] = {}
+    for f in dataclasses.fields(cls):
+        json_key = f.metadata.get("json", f.name)
+        if json_key in data:
+            kwargs[f.name] = _convert_value(f.type, data[json_key])
+    # The field walk above is what makes this safe; the constructor itself is
+    # untypeable from here, so the cast is where the generic contract is paid.
+    return cast(T, cast(Any, cls)(**kwargs))