Metadata-Version: 2.4
Name: nflmeta
Version: 0.1.0
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/pbourdon71/NFLMeta-public
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)
```
