Metadata-Version: 2.4
Name: kingsplaybook
Version: 0.1.0
Summary: Official Python SDK for the KingsPlaybook Developer API — confirmed lineups, player projections, canonical lines, and pick-history archive for NBA, MLB, and NHL.
Project-URL: Homepage, https://kingsplaybook.org/devs
Project-URL: Documentation, https://api.kingsplaybook.org/openapi.json
Author: KingsPlaybook
License: MIT
Keywords: betting,kingsplaybook,lineups,mlb,nba,nhl,odds,projections,sports,sports-betting,sports-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# kingsplaybook

The official **Python SDK** for the
[KingsPlaybook Developer API](https://kingsplaybook.org/devs) — confirmed
lineups, raw player projections, canonical game lines, and a pick-history
archive for NBA, MLB, and NHL.

It's a thin, typed wrapper over the public `/v1` REST API: one client
class, one method per endpoint. **Zero dependencies** — it uses only the
Python standard library.

## Install

```sh
pip install kingsplaybook
```

Requires Python 3.9+.

## Get an API key

Sign up at **[kingsplaybook.org/devs](https://kingsplaybook.org/devs)**.
Your key looks like `kp_live_…`. The Free tier covers lineups; paid tiers
add projections, lines, and history.

## Quick start

```python
from kingsplaybook import KingsPlaybook

kp = KingsPlaybook(api_key="kp_live_...")

# Confirmed lineups (Free tier)
lineups = kp.lineups(league="nba", date="2026-05-21")
for game in lineups["data"]:
    away = (game["away_team"] or {}).get("abbreviation")
    home = (game["home_team"] or {}).get("abbreviation")
    print(f"{away} @ {home}")

# Player projections (Starter tier and up)
projections = kp.projections(league="nba", date="2026-05-21")
print(f"{projections['meta']['count']} projections")
```

The `api_key` argument falls back to the `KINGSPLAYBOOK_API_KEY`
environment variable, so `KingsPlaybook()` works when that is set.

## Methods

| Method | Endpoint | Min. tier |
|---|---|---|
| `kp.health()` | `GET /v1/health` | none |
| `kp.freshness()` | `GET /v1/meta/freshness` | Free |
| `kp.lineups(league, date)` | `GET /v1/lineups` | Free |
| `kp.projections(league, date)` | `GET /v1/projections` | Starter |
| `kp.lines(league, date)` | `GET /v1/lines` | Pro |
| `kp.history(date, pick_type=…, sport=…)` | `GET /v1/history/picks` | Premium |

`league` is `"nba"`, `"mlb"`, or `"nhl"`. `date` is an ISO-8601 string
(`YYYY-MM-DD`). For `history`, `pick_type` is `"game"` or `"prop"` (omit
for both).

Each method returns a plain `dict` shaped `{"data": ..., "meta": ...}`.
The package ships [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)
definitions (`LineupsResponse`, `ProjectionsResponse`, …) in
`kingsplaybook.models`, and is marked `py.typed` — type checkers and
editors get full autocomplete over the responses.

## Error handling

Every failure raises a `KingsPlaybookError` or a subclass. The subclass
tells you what went wrong without parsing a message:

```python
from kingsplaybook import (
    KingsPlaybook,
    AuthenticationError,
    TierError,
    RateLimitError,
    KingsPlaybookError,
)

try:
    kp.lines(league="mlb", date="2026-05-21")
except AuthenticationError:
    ...  # 401 — key missing, invalid, or revoked
except TierError:
    ...  # 403 — your plan does not include this endpoint
except RateLimitError:
    ...  # 429 — back off and retry
except KingsPlaybookError as exc:
    ...  # anything else (transport, 404, 5xx) — exc.status has the code
```

## Configuration

```python
KingsPlaybook(
    api_key="kp_live_...",   # or KINGSPLAYBOOK_API_KEY
    base_url="https://api.kingsplaybook.org",  # or KINGSPLAYBOOK_API_URL
    timeout=30.0,            # per-request timeout, seconds
)
```

## License

MIT
