nflmeta 0.1.1__tar.gz

nflmeta-0.1.1/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.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: nflmeta
+Version: 0.1.1
+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 :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+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`
+- `playoff_games`
+- `standings`
+- `playoffs`
+- `super_bowls`
+- `history`
+- `hall_of_fame`
+- `contributors`
+- `executives`
+- `staff`
+- `coaches`
+- `assets`
+- `all_star_games`
+- `stats.players`
+- `reference`
+
+## Errors
+
+- `NFLMetaBadRequestError`
+- `NFLMetaUnauthorizedError`
+- `NFLMetaNotFoundError`
+- `NFLMetaRateLimitError`
+- `NFLMetaTimeoutError`
+- `NFLMetaError`
+
+## Escape Hatch
+
+```python
+raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})
+print(raw.data)
+```

nflmeta-0.1.1/README.md

@@ -0,0 +1,87 @@
+# `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`
+- `playoff_games`
+- `standings`
+- `playoffs`
+- `super_bowls`
+- `history`
+- `hall_of_fame`
+- `contributors`
+- `executives`
+- `staff`
+- `coaches`
+- `assets`
+- `all_star_games`
+- `stats.players`
+- `reference`
+
+## Errors
+
+- `NFLMetaBadRequestError`
+- `NFLMetaUnauthorizedError`
+- `NFLMetaNotFoundError`
+- `NFLMetaRateLimitError`
+- `NFLMetaTimeoutError`
+- `NFLMetaError`
+
+## Escape Hatch
+
+```python
+raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})
+print(raw.data)
+```

nflmeta-0.1.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nflmeta"
+version = "0.1.1"
+description = "Official Python SDK for the NFLMeta API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "NFLMeta" }
+]
+keywords = ["nfl", "nflmeta", "sports", "api", "sdk", "python"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: Other/Proprietary License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nflmeta = ["py.typed"]
+
+[project.urls]
+Homepage = "https://nflmeta.org/api-docs/sdk"
+Documentation = "https://nflmeta.org/api-docs"
+Source = "https://github.com/philippebourdon/NFLMeta"

nflmeta-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nflmeta-0.1.1/src/nflmeta/__init__.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .client import NFLMetaClientCore
+from .errors import (
+    NFLMetaBadRequestError,
+    NFLMetaError,
+    NFLMetaNotFoundError,
+    NFLMetaRateLimitError,
+    NFLMetaTimeoutError,
+    NFLMetaUnauthorizedError,
+)
+from .resources import (
+    AllStarGamesResource,
+    AssetsResource,
+    CoachesResource,
+    ContributorsResource,
+    ExecutivesResource,
+    GamesResource,
+    HallOfFameResource,
+    HealthResource,
+    HistoryResource,
+    MetadataResource,
+    PlayoffGamesResource,
+    PlayoffsResource,
+    PlayersResource,
+    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.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",
+    "FieldValue",
+    "NFLMetaBadRequestError",
+    "NFLMetaClient",
+    "NFLMetaError",
+    "NFLMetaNotFoundError",
+    "NFLMetaRateLimitError",
+    "NFLMetaTimeoutError",
+    "NFLMetaUnauthorizedError",
+    "RateLimitInfo",
+    "create_client",
+]

nflmeta-0.1.1/src/nflmeta/client.py

@@ -0,0 +1,164 @@
+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
+from urllib.request import Request, urlopen
+
+from .errors import NFLMetaTimeoutError, create_http_error
+from .types import APIResponse, QueryParams, RateLimitInfo
+
+
+def _normalize_base_url(base_url: str | None) -> str:
+    base = (base_url or "https://nflmeta.org").strip()
+    return base.rstrip("/")
+
+
+def _is_absolute_url(value: str) -> bool:
+    return value.startswith("http://") or value.startswith("https://")
+
+
+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 _parse_int_header(headers: Mapping[str, str], name: str) -> Optional[int]:
+    value = headers.get(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=headers.get("X-RateLimit-Reset"),
+        policy=headers.get("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 = Request(url, headers=dict(headers), method="GET")
+    try:
+        with urlopen(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:
+        url = path if _is_absolute_url(path) else urljoin(f"{self.base_url}/", path.lstrip("/"))
+        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-0.1.1/src/nflmeta/errors.py

@@ -0,0 +1,83 @@
+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 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-0.1.1/src/nflmeta/py.typed

@@ -0,0 +1 @@
+

nflmeta-0.1.1/src/nflmeta/resources.py

@@ -0,0 +1,466 @@
+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 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-0.1.1/src/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.1/src/nflmeta.egg-info/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: nflmeta
+Version: 0.1.1
+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 :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+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`
+- `playoff_games`
+- `standings`
+- `playoffs`
+- `super_bowls`
+- `history`
+- `hall_of_fame`
+- `contributors`
+- `executives`
+- `staff`
+- `coaches`
+- `assets`
+- `all_star_games`
+- `stats.players`
+- `reference`
+
+## Errors
+
+- `NFLMetaBadRequestError`
+- `NFLMetaUnauthorizedError`
+- `NFLMetaNotFoundError`
+- `NFLMetaRateLimitError`
+- `NFLMetaTimeoutError`
+- `NFLMetaError`
+
+## Escape Hatch
+
+```python
+raw = client.get("/api/v1/reference/team-colors", query={"limit": 10})
+print(raw.data)
+```

nflmeta-0.1.1/src/nflmeta.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/nflmeta/__init__.py
+src/nflmeta/client.py
+src/nflmeta/errors.py
+src/nflmeta/py.typed
+src/nflmeta/resources.py
+src/nflmeta/types.py
+src/nflmeta.egg-info/PKG-INFO
+src/nflmeta.egg-info/SOURCES.txt
+src/nflmeta.egg-info/dependency_links.txt
+src/nflmeta.egg-info/top_level.txt
+tests/test_client.py

nflmeta-0.1.1/src/nflmeta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nflmeta-0.1.1/src/nflmeta.egg-info/top_level.txt

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

nflmeta-0.1.1/tests/test_client.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import unittest
+from io import BytesIO
+from urllib.error import HTTPError
+from urllib.request import Request
+
+from nflmeta import NFLMetaClient, NFLMetaUnauthorizedError
+from nflmeta.client import TransportResponse, _default_transport
+
+
+class NFLMetaClientTests(unittest.TestCase):
+    def test_adds_api_key_and_parses_rate_limits(self) -> None:
+        captured: dict[str, object] = {}
+
+        def transport(url: str, headers, timeout):
+            captured["url"] = url
+            captured["headers"] = dict(headers)
+            captured["timeout"] = timeout
+            return TransportResponse(
+                status=200,
+                headers={
+                    "X-RateLimit-Limit": "1000",
+                    "X-RateLimit-Remaining": "999",
+                    "X-RateLimit-Reset": "2026-04-01T00:00:00.000Z",
+                    "X-RateLimit-Policy": "monthly",
+                },
+                payload={
+                    "data": [{"year": 2025, "id": 57}],
+                    "meta": {"total": 1, "returned": 1},
+                },
+            )
+
+        client = NFLMetaClient(api_key="test-key", transport=transport)
+        result = client.seasons.list(year_from=2025, limit=1)
+
+        self.assertEqual(captured["headers"]["X-NFLMeta-Key"], "test-key")
+        self.assertTrue(str(captured["url"]).endswith("/api/v1/seasons?year_from=2025&limit=1"))
+        self.assertEqual(result.rate_limit.limit, 1000)
+        self.assertEqual(result.rate_limit.remaining, 999)
+        self.assertEqual(result.data[0]["year"], 2025)
+
+    def test_raises_typed_unauthorized_errors(self) -> None:
+        def transport(_url: str, _headers, _timeout):
+            return TransportResponse(
+                status=401,
+                headers={},
+                payload={"error": {"code": "unauthorized", "message": "invalid api key"}},
+            )
+
+        client = NFLMetaClient(transport=transport)
+
+        with self.assertRaises(NFLMetaUnauthorizedError) as ctx:
+            client.usage.get()
+
+        self.assertEqual(ctx.exception.status, 401)
+        self.assertEqual(ctx.exception.code, "unauthorized")
+
+    def test_builds_nested_resource_paths(self) -> None:
+        captured: dict[str, object] = {}
+
+        def transport(url: str, _headers, _timeout):
+            captured["url"] = url
+            return TransportResponse(
+                status=200,
+                headers={},
+                payload={"data": {"field": "pass_passer_rating", "value": 99.4}},
+            )
+
+        client = NFLMetaClient(transport=transport)
+        result = client.players.career_field("josh-allen-1996", "pass_passer_rating")
+
+        self.assertTrue(str(captured["url"]).endswith("/api/v1/players/josh-allen-1996/career/pass_passer_rating"))
+        self.assertEqual(result.data["value"], 99.4)
+
+    def test_default_transport_normalizes_http_errors(self) -> None:
+        request = Request("https://nflmeta.org/api/v1/usage", method="GET")
+        http_error = HTTPError(
+            request.full_url,
+            401,
+            "Unauthorized",
+            hdrs={"Content-Type": "application/json"},
+            fp=BytesIO(b'{"error":{"code":"unauthorized","message":"invalid api key"}}'),
+        )
+
+        def fake_urlopen(_request, timeout=None):
+            raise http_error
+
+        from nflmeta import client as client_module
+
+        original_urlopen = client_module.urlopen
+        client_module.urlopen = fake_urlopen
+        try:
+            response = _default_transport(request.full_url, {}, 10.0)
+        finally:
+            client_module.urlopen = original_urlopen
+
+        self.assertEqual(response.status, 401)
+        self.assertEqual(response.payload["error"]["code"], "unauthorized")
+
+
+if __name__ == "__main__":
+    unittest.main()