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.
