nflmeta 0.1.3__py3-none-any.whl

nflmeta/__init__.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import NFLMetaClientCore, __version__
+from .errors import (
+    NFLMetaBadRequestError,
+    NFLMetaError,
+    NFLMetaInvalidUrlError,
+    NFLMetaNotFoundError,
+    NFLMetaRateLimitError,
+    NFLMetaTimeoutError,
+    NFLMetaUnauthorizedError,
+)
+from .resources import (
+    AllStarGamesResource,
+    AssetsResource,
+    CoachesResource,
+    ContributorsResource,
+    ExecutivesResource,
+    GamesResource,
+    HallOfFameResource,
+    HealthResource,
+    HistoryResource,
+    MetadataResource,
+    PlayersResource,
+    PlayoffGamesResource,
+    PlayoffsResource,
+    PlaysResource,
+    ReferenceResource,
+    SeasonsResource,
+    StaffResource,
+    StandingsResource,
+    StatsResource,
+    SuperBowlsResource,
+    TeamsResource,
+    UsageResource,
+)
+from .types import APIResponse, FieldValue, RateLimitInfo
+
+
+class NFLMetaClient(NFLMetaClientCore):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.health = HealthResource(self)
+        self.usage = UsageResource(self)
+        self.metadata = MetadataResource(self)
+        self.seasons = SeasonsResource(self)
+        self.teams = TeamsResource(self)
+        self.players = PlayersResource(self)
+        self.games = GamesResource(self)
+        self.plays = PlaysResource(self)
+        self.playoff_games = PlayoffGamesResource(self)
+        self.standings = StandingsResource(self)
+        self.playoffs = PlayoffsResource(self)
+        self.super_bowls = SuperBowlsResource(self)
+        self.history = HistoryResource(self)
+        self.hall_of_fame = HallOfFameResource(self)
+        self.contributors = ContributorsResource(self, "contributors")
+        self.executives = ExecutivesResource(self, "executives")
+        self.staff = StaffResource(self, "staff")
+        self.coaches = CoachesResource(self, "coaches")
+        self.assets = AssetsResource(self)
+        self.all_star_games = AllStarGamesResource(self)
+        self.stats = StatsResource(self)
+        self.reference = ReferenceResource(self)
+
+
+def create_client(**kwargs: Any) -> NFLMetaClient:
+    return NFLMetaClient(**kwargs)
+
+
+__all__ = [
+    "APIResponse",
+    "__version__",
+    "FieldValue",
+    "NFLMetaBadRequestError",
+    "NFLMetaClient",
+    "NFLMetaError",
+    "NFLMetaInvalidUrlError",
+    "NFLMetaNotFoundError",
+    "NFLMetaRateLimitError",
+    "NFLMetaTimeoutError",
+    "NFLMetaUnauthorizedError",
+    "RateLimitInfo",
+    "create_client",
+]

nflmeta/client.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import json
+import socket
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Any, Callable, Mapping, MutableMapping, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urljoin, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from .errors import NFLMetaInvalidUrlError, NFLMetaTimeoutError, create_http_error
+from .types import APIResponse, QueryParams, RateLimitInfo
+
+__version__ = "0.1.3"
+USER_AGENT = f"nflmeta-python/{__version__}"
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    base = (base_url or "https://nflmeta.org").strip()
+    return base.rstrip("/")
+
+
+def _origin(url: str) -> tuple[str, str]:
+    parts = urlsplit(url)
+    return (parts.scheme.lower(), parts.netloc.lower())
+
+
+def _resolve_request_url(base_url: str, path: str) -> str:
+    """Resolve a caller-supplied path against the base, refusing anything that leaves it.
+
+    This used to accept any absolute http(s) URL and then attach X-NFLMeta-Key to
+    it unconditionally, so an application passing a user-controlled or mistakenly
+    absolute URL handed its API key to whatever host was named.
+
+    The boundary is the one mcp-server/src/api-client.mts already enforces: stay
+    on the configured origin, and keep the path inside /api/v1. Every endpoint
+    this client can reach lives there. Same-origin absolute URLs are still
+    accepted -- they are not a leak.
+    """
+    base = f"{base_url}/"
+    resolved = urljoin(base, path)
+    if _origin(resolved) != _origin(base):
+        raise NFLMetaInvalidUrlError(
+            f"Refusing to send the API key to {urlsplit(resolved).netloc}. "
+            f"Requests must stay on {urlsplit(base).netloc}."
+        )
+    if not urlsplit(resolved).path.startswith("/api/v1/"):
+        raise NFLMetaInvalidUrlError(
+            f"The request path resolved outside /api/v1: {urlsplit(resolved).path}"
+        )
+    return resolved
+
+
+class _SameOriginRedirectHandler(HTTPRedirectHandler):
+    """Follow same-origin redirects; refuse to carry the key across an origin.
+
+    Redirects are a second way the key escapes, and one the request-URL check does
+    not cover. Measured on 2026-08-27 against a local server: urllib forwards
+    every request header across a cross-origin redirect -- X-NFLMeta-Key AND
+    Authorization, which even Node's fetch strips.
+
+    Same-origin redirects are left alone: the API normalises trailing slashes with
+    a 308 and that has to keep working.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        if _origin(newurl) != _origin(req.full_url):
+            raise NFLMetaInvalidUrlError(
+                f"Refusing to follow a redirect to {urlsplit(newurl).netloc}, which would send "
+                f"the API key off {urlsplit(req.full_url).netloc}."
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+_OPENER = build_opener(_SameOriginRedirectHandler())
+
+
+def _serialize_query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)
+
+
+def _build_query_string(query: QueryParams | None) -> str:
+    if not query:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    for key, raw_value in query.items():
+        if raw_value is None:
+            continue
+        values = raw_value if isinstance(raw_value, (list, tuple)) else [raw_value]
+        for value in values:
+            if value is None:
+                continue
+            pairs.append((key, _serialize_query_value(value)))
+    return urlencode(pairs)
+
+
+def _lookup_header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    """Case-insensitive header lookup.
+
+    HTTP header names are case-insensitive, but the transport hands back a plain
+    dict built from whatever casing the wire used. Looking these up by the
+    canonical spelling returned None for every response, so the documented
+    ``response.rate_limit.remaining`` was always None in Python while the
+    TypeScript SDK reported the real number.
+    """
+    value = headers.get(name)
+    if value is not None:
+        return value
+    target = name.lower()
+    for key, candidate in headers.items():
+        if key.lower() == target:
+            return candidate
+    return None
+
+
+def _parse_int_header(headers: Mapping[str, str], name: str) -> Optional[int]:
+    value = _lookup_header(headers, name)
+    if not value:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse_rate_limit(headers: Mapping[str, str]) -> RateLimitInfo:
+    return RateLimitInfo(
+        limit=_parse_int_header(headers, "X-RateLimit-Limit"),
+        remaining=_parse_int_header(headers, "X-RateLimit-Remaining"),
+        reset=_lookup_header(headers, "X-RateLimit-Reset"),
+        policy=_lookup_header(headers, "X-RateLimit-Policy"),
+    )
+
+
+def _decode_payload(raw: bytes, content_type: str | None) -> Any:
+    text = raw.decode("utf-8") if raw else ""
+    if not text:
+        return None
+    if content_type and "application/json" in content_type.lower():
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"message": text}
+    return {"message": text}
+
+
+@dataclass(slots=True)
+class TransportResponse:
+    status: int
+    headers: MutableMapping[str, str]
+    payload: Any
+
+
+def _default_transport(url: str, headers: Mapping[str, str], timeout: float | None) -> TransportResponse:
+    request_headers = dict(headers)
+    # urllib supplies its own "Python-urllib/x.y" User-Agent when none is set,
+    # and the edge in front of the API rejects that string outright: every call
+    # from the published package came back 403 (Cloudflare error 1010) before
+    # reaching the application. Note the fix is to send a real User-Agent, not
+    # to send none -- omitting it is what produces the failing default.
+    if not _lookup_header(request_headers, "User-Agent"):
+        request_headers["User-Agent"] = USER_AGENT
+    request = Request(url, headers=request_headers, method="GET")
+    try:
+        # _OPENER, not urlopen: the default opener follows a cross-origin
+        # redirect and re-sends every header, key included.
+        with _OPENER.open(request, timeout=timeout) as response:
+            raw = response.read()
+            response_headers = {key: value for key, value in response.headers.items()}
+            payload = _decode_payload(raw, response.headers.get("Content-Type"))
+            return TransportResponse(status=response.status, headers=response_headers, payload=payload)
+    except HTTPError as error:
+        raw = error.read()
+        response_headers = {key: value for key, value in error.headers.items()}
+        payload = _decode_payload(raw, error.headers.get("Content-Type"))
+        return TransportResponse(status=error.code, headers=response_headers, payload=payload)
+    except TimeoutError as error:
+        raise NFLMetaTimeoutError(timeout or 0.0) from error
+    except socket.timeout as error:
+        raise NFLMetaTimeoutError(timeout or 0.0) from error
+    except URLError as error:
+        if isinstance(error.reason, socket.timeout):
+            raise NFLMetaTimeoutError(timeout or 0.0) from error
+        raise
+
+
+Transport = Callable[[str, Mapping[str, str], float | None], TransportResponse]
+
+
+class NFLMetaClientCore:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        headers: Mapping[str, str] | None = None,
+        transport: Transport | None = None,
+    ) -> None:
+        self.api_key = api_key.strip() if api_key else None
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = timeout
+        self.default_headers = dict(headers or {})
+        self._transport = transport or _default_transport
+
+    def get(
+        self,
+        path: str,
+        query: QueryParams | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> APIResponse:
+        # Before any header is built: a URL that leaves the configured origin must
+        # never reach the point where the key is attached.
+        url = _resolve_request_url(self.base_url, path)
+        query_string = _build_query_string(query)
+        if query_string:
+            separator = "&" if "?" in url else "?"
+            url = f"{url}{separator}{query_string}"
+
+        request_headers: dict[str, str] = {"Accept": "application/json"}
+        request_headers.update(self.default_headers)
+        if headers:
+            request_headers.update(headers)
+        if self.api_key and "X-NFLMeta-Key" not in request_headers:
+            request_headers["X-NFLMeta-Key"] = self.api_key
+
+        transport_response = self._transport(url, request_headers, self.timeout)
+        rate_limit = _parse_rate_limit(transport_response.headers)
+
+        if transport_response.status < 200 or transport_response.status >= 300:
+            raise create_http_error(transport_response.status, transport_response.payload, rate_limit)
+
+        payload = transport_response.payload
+        if not isinstance(payload, dict) or "data" not in payload:
+            raise create_http_error(transport_response.status, payload, rate_limit)
+
+        return APIResponse(
+            data=payload.get("data"),
+            meta=payload.get("meta"),
+            status=transport_response.status,
+            rate_limit=rate_limit,
+            headers=transport_response.headers,
+        )

nflmeta/errors.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .types import RateLimitInfo
+
+
+@dataclass(slots=True)
+class NFLMetaErrorDetails:
+    code: Optional[str] = None
+    payload: Any = None
+    rate_limit: Optional[RateLimitInfo] = None
+
+
+class NFLMetaError(Exception):
+    def __init__(self, message: str, status: int, details: NFLMetaErrorDetails | None = None) -> None:
+        super().__init__(message)
+        details = details or NFLMetaErrorDetails()
+        self.status = status
+        self.code = details.code
+        self.payload = details.payload
+        self.rate_limit = details.rate_limit
+
+
+class NFLMetaInvalidUrlError(NFLMetaError):
+    """A request was refused before it was sent, because its URL left the API origin.
+
+    ``status`` is 0 precisely because nothing was transmitted: the client attaches
+    X-NFLMeta-Key to every request, so a URL pointing elsewhere has to be stopped
+    before any header is built, not reported after the fact.
+    """
+
+    def __init__(self, message: str, details: NFLMetaErrorDetails | None = None) -> None:
+        details = details or NFLMetaErrorDetails()
+        if details.code is None:
+            details.code = "invalid_url"
+        super().__init__(message, 0, details)
+
+
+class NFLMetaBadRequestError(NFLMetaError):
+    pass
+
+
+class NFLMetaUnauthorizedError(NFLMetaError):
+    pass
+
+
+class NFLMetaNotFoundError(NFLMetaError):
+    pass
+
+
+class NFLMetaRateLimitError(NFLMetaError):
+    pass
+
+
+class NFLMetaTimeoutError(TimeoutError):
+    def __init__(self, timeout_seconds: float) -> None:
+        super().__init__(f"NFLMeta request timed out after {timeout_seconds:.3f}s")
+        self.timeout_seconds = timeout_seconds
+
+
+def _error_message(payload: Any, status: int) -> str:
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        if isinstance(error, dict):
+            message = error.get("message")
+            if isinstance(message, str) and message.strip():
+                return message
+    return f"NFLMeta request failed with status {status}"
+
+
+def _error_code(payload: Any) -> Optional[str]:
+    if isinstance(payload, dict):
+        error = payload.get("error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            if isinstance(code, str) and code.strip():
+                return code
+    return None
+
+
+def create_http_error(status: int, payload: Any, rate_limit: RateLimitInfo | None = None) -> NFLMetaError:
+    details = NFLMetaErrorDetails(
+        code=_error_code(payload),
+        payload=payload,
+        rate_limit=rate_limit,
+    )
+    message = _error_message(payload, status)
+    if status == 400:
+        return NFLMetaBadRequestError(message, status, details)
+    if status == 401:
+        return NFLMetaUnauthorizedError(message, status, details)
+    if status == 404:
+        return NFLMetaNotFoundError(message, status, details)
+    if status == 429:
+        return NFLMetaRateLimitError(message, status, details)
+    return NFLMetaError(message, status, details)

nflmeta/py.typed

@@ -0,0 +1 @@
+

nflmeta/resources.py

@@ -0,0 +1,486 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .client import NFLMetaClientCore
+from .types import APIResponse, QueryParams
+
+
+def _segment(value: str | int) -> str:
+    return quote(str(value), safe="")
+
+
+def _api_path(*parts: str | int) -> str:
+    return "/api/v1/" + "/".join(_segment(part) for part in parts)
+
+
+class BaseResource:
+    def __init__(self, client: NFLMetaClientCore) -> None:
+        self.client = client
+
+    def _request(self, path: str, query: QueryParams | None = None) -> APIResponse:
+        return self.client.get(path, query=query)
+
+    def _field(self, path: str, query: QueryParams | None = None) -> APIResponse:
+        return self.client.get(path, query=query)
+
+
+class HealthResource(BaseResource):
+    def get(self) -> APIResponse:
+        return self._request(_api_path("health"))
+
+
+class UsageResource(BaseResource):
+    def get(self) -> APIResponse:
+        return self._request(_api_path("usage"))
+
+
+class MetadataResource(BaseResource):
+    def show(self) -> APIResponse:
+        return self._request(_api_path("show"))
+
+
+class SeasonsResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("seasons"), query=query or None)
+
+    def summary(self, year: int) -> APIResponse:
+        return self._request(_api_path("season", year))
+
+    def summary_field(self, year: int, field: str) -> APIResponse:
+        return self._field(_api_path("season", year, field))
+
+    def byes(self, year: int) -> APIResponse:
+        return self._request(_api_path("byes", year))
+
+
+class TeamsResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams"), query=query or None)
+
+    def get(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr), query=query or None)
+
+    def recent_games(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "games"), query=query or None)
+
+    def profile(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "profile"), query=query or None)
+
+    def profile_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "profile", field), query=query or None)
+
+    def identity(self, abbr: str) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "identity"))
+
+    def identity_field(self, abbr: str, field: str) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "identity", field))
+
+    def season(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "season"), query=query or None)
+
+    def season_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "season", field), query=query or None)
+
+    def stats(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "stats"), query=query or None)
+
+    def stats_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "stats", field), query=query or None)
+
+    def power_rankings(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "power-rankings"), query=query or None)
+
+    def power_rankings_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "power-rankings", field), query=query or None)
+
+    def stadium(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "stadium"), query=query or None)
+
+    def stadium_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "stadium", field), query=query or None)
+
+    def pro_bowl(self, abbr: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("teams", abbr, "pro-bowl"), query=query or None)
+
+    def pro_bowl_field(self, abbr: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("teams", abbr, "pro-bowl", field), query=query or None)
+
+
+class PlayersResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("players"), query=query or None)
+
+    def get(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key))
+
+    def identity(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "identity"))
+
+    def identity_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "identity", field))
+
+    def bio(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "bio"))
+
+    def bio_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "bio", field))
+
+    def ids(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "ids"))
+
+    def ids_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "ids", field))
+
+    def history(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "history"))
+
+    def history_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "history", field))
+
+    def honors(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "honors"))
+
+    def honors_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "honors", field))
+
+    def roster(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "roster"))
+
+    def games(self, player_key: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("players", player_key, "games"), query=query or None)
+
+    def career(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "career"))
+
+    def career_field(self, player_key: str, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "career", field))
+
+    def career_seasons(self, player_key: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("players", player_key, "career", "seasons"), query=query or None)
+
+    def splits(self, player_key: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("players", player_key, "splits"), query=query or None)
+
+    def splits_field(self, player_key: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("players", player_key, "splits", field), query=query or None)
+
+    def records(self, player_key: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("players", player_key, "records"), query=query or None)
+
+    def records_field(self, player_key: str, field: str, **query: Any) -> APIResponse:
+        return self._field(_api_path("players", player_key, "records", field), query=query or None)
+
+    def kicking(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "kicking"))
+
+    def kicking_season(self, player_key: str, season_year: int) -> APIResponse:
+        return self._request(_api_path("players", player_key, "kicking", season_year))
+
+    def kicking_season_field(self, player_key: str, season_year: int, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "kicking", season_year, field))
+
+    def punting(self, player_key: str) -> APIResponse:
+        return self._request(_api_path("players", player_key, "punting"))
+
+    def punting_season(self, player_key: str, season_year: int) -> APIResponse:
+        return self._request(_api_path("players", player_key, "punting", season_year))
+
+    def punting_season_field(self, player_key: str, season_year: int, field: str) -> APIResponse:
+        return self._field(_api_path("players", player_key, "punting", season_year, field))
+
+
+class GamesResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("games"), query=query or None)
+
+    def get(self, game_id: int) -> APIResponse:
+        return self._request(_api_path("games", game_id))
+
+    def field(self, game_id: int, field: str) -> APIResponse:
+        return self._field(_api_path("games", game_id, field))
+
+    def extras(self, game_id: int) -> APIResponse:
+        return self._request(_api_path("games", game_id, "extras"))
+
+
+class PlaysResource(BaseResource):
+    """Play-by-play.
+
+    ``list`` is metered per play and the API refuses an unnarrowed request with
+    400: pass ``game_id``, or ``player``, or ``season`` together with one of
+    ``week``, ``team`` or ``opponent``. ``summary`` and ``leaders`` answer
+    season-wide questions server-side in tens of rows, which is what most
+    callers actually want.
+    """
+
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("plays"), query=query or None)
+
+    def summary(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("plays", "summary"), query=query or None)
+
+    def leaders(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("plays", "leaders"), query=query or None)
+
+
+class PlayoffGamesResource(BaseResource):
+    def get(self, game_id: int) -> APIResponse:
+        return self._request(_api_path("playoff-games", game_id))
+
+    def field(self, game_id: int, field: str) -> APIResponse:
+        return self._field(_api_path("playoff-games", game_id, field))
+
+    def extras(self, game_id: int) -> APIResponse:
+        return self._request(_api_path("playoff-games", game_id, "extras"))
+
+    def supplemental(self, game_id: int) -> APIResponse:
+        return self._request(_api_path("playoff-games", game_id, "supplemental"))
+
+
+class StandingsResource(BaseResource):
+    def get(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("standings"), query=query or None)
+
+
+class PlayoffsResource(BaseResource):
+    def picture(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("playoffs", "picture"), query=query or None)
+
+
+class SuperBowlsResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("super-bowls"), query=query or None)
+
+    def by_season(self, season_year: int) -> APIResponse:
+        return self._request(_api_path("super-bowls", season_year))
+
+    def by_team(self, abbr: str) -> APIResponse:
+        return self._request(_api_path("super-bowls", "teams", abbr))
+
+
+class HistoryResource(BaseResource):
+    def officials(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("history", "officials"), query=query or None)
+
+    def stadiums(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("history", "stadiums"), query=query or None)
+
+    def team_logos(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("history", "team-logos"), query=query or None)
+
+    def venues(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("history", "venues"), query=query or None)
+
+
+class HallOfFameResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("hall-of-fame"), query=query or None)
+
+    def election(self, year: int) -> APIResponse:
+        return self._request(_api_path("hall-of-fame", year))
+
+    def election_field(self, year: int, field: str) -> APIResponse:
+        return self._field(_api_path("hall-of-fame", year, field))
+
+
+class _PeopleResource(BaseResource):
+    def __init__(self, client: NFLMetaClientCore, *base_segments: str) -> None:
+        super().__init__(client)
+        self.base_segments = base_segments
+
+    def _resource_path(self, key: str, *suffix: str | int) -> str:
+        return _api_path(*self.base_segments, key, *suffix)
+
+    def get(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key))
+
+    def identity(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "identity"))
+
+    def identity_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "identity", field))
+
+    def bio(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "bio"))
+
+    def bio_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "bio", field))
+
+    def history(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "history"))
+
+    def history_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "history", field))
+
+
+class ContributorsResource(_PeopleResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("contributors"), query=query or None)
+
+
+class ExecutivesResource(_PeopleResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("executives"), query=query or None)
+
+    def career(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "career"))
+
+    def career_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "career", field))
+
+
+class StaffResource(_PeopleResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("staff"), query=query or None)
+
+    def career(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "career"))
+
+    def career_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "career", field))
+
+
+class CoachesResource(_PeopleResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("coaches"), query=query or None)
+
+    def career(self, key: str) -> APIResponse:
+        return self._request(self._resource_path(key, "career"))
+
+    def career_field(self, key: str, field: str) -> APIResponse:
+        return self._field(self._resource_path(key, "career", field))
+
+
+class AssetsResource(BaseResource):
+    def logos(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("assets", "logos"), query=query or None)
+
+    def images(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("assets", "images"), query=query or None)
+
+
+class AllStarGamesResource(BaseResource):
+    def list(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("all-star-games"), query=query or None)
+
+
+class StatsPlayersResource(BaseResource):
+    def catalog(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "catalog"), query=query or None)
+
+    def search(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "search"), query=query or None)
+
+    def compare(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "compare"), query=query or None)
+
+    def seasons(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "seasons"), query=query or None)
+
+    def seasons_by_stat(self, season_year: int, stat: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "seasons", season_year, stat), query=query or None)
+
+    def careers(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "careers"), query=query or None)
+
+    def careers_by_stat(self, stat: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "careers", stat), query=query or None)
+
+    def games(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "games"), query=query or None)
+
+    def game_splits(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "games", "splits"), query=query or None)
+
+    def game_leaders_by_family(self, stat_family: str, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "games", "leaders", stat_family), query=query or None)
+
+    def teams(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "teams"), query=query or None)
+
+    def weeks(self, season_year: int, **query: Any) -> APIResponse:
+        return self._request(_api_path("stats", "players", "season", season_year, "weeks"), query=query or None)
+
+
+class StatsResource:
+    def __init__(self, client: NFLMetaClientCore) -> None:
+        self.players = StatsPlayersResource(client)
+
+
+class ReferenceResource(BaseResource):
+    def all_star_games(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "all-star-games"), query=query or None)
+
+    def coaches(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "coaches"), query=query or None)
+
+    def coach(self, key: str) -> APIResponse:
+        return self._request(_api_path("reference", "coaches", key))
+
+    def coach_field(self, key: str, field: str) -> APIResponse:
+        return self._field(_api_path("reference", "coaches", key, field))
+
+    def officials(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "officials"), query=query or None)
+
+    def official(self, key: str) -> APIResponse:
+        return self._request(_api_path("reference", "officials", key))
+
+    def official_field(self, key: str, field: str) -> APIResponse:
+        return self._field(_api_path("reference", "officials", key, field))
+
+    def power_rankings(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "power-rankings"), query=query or None)
+
+    def pro_bowl_player_bios(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "pro-bowl-player-bios"), query=query or None)
+
+    def pro_bowl_player_stats(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "pro-bowl-player-stats"), query=query or None)
+
+    def pro_bowl_selections(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "pro-bowl-selections"), query=query or None)
+
+    def seasons(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "seasons"), query=query or None)
+
+    def stadium_histories(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "stadium-histories"), query=query or None)
+
+    def stadiums(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "stadiums"), query=query or None)
+
+    def team_aliases(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-aliases"), query=query or None)
+
+    def team_coaches(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-coaches"), query=query or None)
+
+    def team_colors(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-colors"), query=query or None)
+
+    def team_logo_histories(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-logo-histories"), query=query or None)
+
+    def team_name_histories(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-name-histories"), query=query or None)
+
+    def team_season_records(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-season-records"), query=query or None)
+
+    def team_season_stats(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "team-season-stats"), query=query or None)
+
+    def teams(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "teams"), query=query or None)
+
+    def venues(self, **query: Any) -> APIResponse:
+        return self._request(_api_path("reference", "venues"), query=query or None)
+
+    def venue(self, key: str) -> APIResponse:
+        return self._request(_api_path("reference", "venues", key))
+
+    def venue_field(self, key: str, field: str) -> APIResponse:
+        return self._field(_api_path("reference", "venues", key, field))

nflmeta/types.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Mapping, MutableMapping, Optional, Sequence, Union
+
+QueryScalar = Union[str, int, float, bool, date, datetime]
+QueryValue = Union[QueryScalar, Sequence[QueryScalar], None]
+QueryParams = Mapping[str, QueryValue]
+
+
+@dataclass(slots=True)
+class RateLimitInfo:
+    limit: Optional[int] = None
+    remaining: Optional[int] = None
+    reset: Optional[str] = None
+    policy: Optional[str] = None
+
+
+@dataclass(slots=True)
+class APIResponse:
+    data: Any
+    meta: Any = None
+    status: int = 200
+    rate_limit: RateLimitInfo = field(default_factory=RateLimitInfo)
+    headers: Mapping[str, str] | MutableMapping[str, str] | None = None
+
+
+@dataclass(slots=True)
+class FieldValue:
+    field: str
+    value: Any

nflmeta-0.1.3.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: nflmeta
+Version: 0.1.3
+Summary: Official Python SDK for the NFLMeta API
+Author: NFLMeta
+License: MIT
+Project-URL: Homepage, https://nflmeta.org/api-docs/sdk
+Project-URL: Documentation, https://nflmeta.org/api-docs
+Project-URL: Source, https://github.com/philippebourdon/NFLMeta
+Keywords: nfl,nflmeta,sports,api,sdk,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# `nflmeta`
+
+Official Python SDK for the NFLMeta API.
+
+## Install
+
+```bash
+pip install nflmeta
+```
+
+## Quickstart
+
+```python
+from nflmeta import NFLMetaClient
+
+client = NFLMetaClient(api_key="YOUR_KEY")
+
+team = client.teams.get("PIT", season=2025)
+player = client.players.identity("josh-allen-1996")
+usage = client.usage.get()
+
+print(team.data["displayName"])
+print(player.data["display_name"])
+print(usage.data["quota_remaining"])
+```
+
+## What The SDK Does
+
+- sends `X-NFLMeta-Key` automatically when you provide `api_key`
+- preserves the API envelope shape: `data`, optional `meta`, plus parsed rate-limit headers
+- throws typed HTTP errors for common failure cases
+- exposes the main public API surfaces as resource clients instead of forcing raw URL construction
+- still gives you a low-level `client.get(path, query={...})` escape hatch for any route not wrapped yet
+
+## Configuration
+
+```python
+client = NFLMetaClient(
+    api_key="YOUR_KEY",
+    base_url="https://nflmeta.org",
+    timeout=10.0,
+)
+```
+
+You can also pass default headers or a custom `transport(url, headers, timeout)` callable if you want the SDK to run through your own HTTP layer in tests or internal tooling.
+
+## Resource Coverage
+
+The Python SDK wraps the same main surfaces as the TypeScript package:
+
+- `health`
+- `usage`
+- `metadata`
+- `seasons`
+- `teams`
+- `players`
+- `games`
+- `plays`
+- `playoff_games`
+- `standings`
+- `playoffs`
+- `super_bowls`
+- `history`
+- `hall_of_fame`
+- `contributors`
+- `executives`
+- `staff`
+- `coaches`
+- `assets`
+- `all_star_games`
+- `stats.players`
+- `reference`
+
+```python
+client.plays.summary(season=2024, group_by="team")
+client.plays.leaders(season=2024, role="passer")
+client.plays.list(game_id=21390, skip_markers=True)
+```
+
+`plays.list` is metered per play and the API refuses an unnarrowed request with
+`400 invalid_request`: pass `game_id`, or `player`, or `season` together with one
+of `week`, `team` or `opponent`. `plays.summary` and `plays.leaders` answer
+season-wide questions server-side in tens of rows.
+
+## Errors
+
+- `NFLMetaBadRequestError`
+- `NFLMetaUnauthorizedError`
+- `NFLMetaNotFoundError`
+- `NFLMetaRateLimitError`
+- `NFLMetaTimeoutError`
+- `NFLMetaError`
+
+## Escape Hatch
+
+```python
+raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})
+print(raw.data)
+```
+
+The path is resolved against `base_url` and has to stay there. A URL on another
+origin is refused with `NFLMetaInvalidUrlError` **before** any header is built,
+and a redirect that would leave the origin is refused rather than followed —
+your API key travels in the `X-NFLMeta-Key` header, and `urllib` forwards every
+request header across a cross-origin redirect. Same-origin absolute URLs still
+work.

nflmeta-0.1.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+nflmeta/__init__.py,sha256=32i_AyKiksBAXjoKXX2qr4rt9szNQydlM_OKB-BVYEk,2501
+nflmeta/client.py,sha256=3NIkPrtnFAnfqNXGmfRwbQI3M_vW4WxEa-TelnrQONg,9771
+nflmeta/errors.py,sha256=wsARGmwA27V9MCG9KR3pRct5E9M3uyD9IhDyhCeZ6yg,3065
+nflmeta/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+nflmeta/resources.py,sha256=1FzMW3muWx-Yjxtvv7ge3bpz_Nk8DsQt09noOvsDc5I,20810
+nflmeta/types.py,sha256=-7or03gfPjUeXbrJ0fPwoQiJPmkj65OeiFb83feabDA,842
+nflmeta-0.1.3.dist-info/licenses/LICENSE,sha256=CvieYTWEkYHB4hdt-3nbkw4-UsHNEDMFiCnHguw5f-A,1091
+nflmeta-0.1.3.dist-info/METADATA,sha256=7oVWihmc1sG9X-WuEERrh2BPYoXWCVfI2suV9PLwX2U,3643
+nflmeta-0.1.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nflmeta-0.1.3.dist-info/top_level.txt,sha256=LG6vsDGLjCPcaIhUopRKcxOgeWoXXTf841tQLIgOyxw,8
+nflmeta-0.1.3.dist-info/RECORD,,

nflmeta-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nflmeta-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philippe Bourdon / ClearOak Studio
+
+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.

nflmeta-0.1.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+nflmeta