Metadata-Version: 2.5
Name: dugout
Version: 0.1.0
Summary: Python client for the Barajitas trading-card database API
Project-URL: Homepage, https://github.com/Barajitas-Project/dugout
Project-URL: Documentation, https://barajitas-project.github.io/
Requires-Python: >=3.10
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# dugout

The Python client for the [Barajitas](https://github.com/Barajitas-Project/barajitas)
trading-card database API — the dugout is where the team keeps
everything within reach.

Part of [The Barajitas Project](https://github.com/Barajitas-Project) ·
API contract in the
[barajitas docs](https://github.com/Barajitas-Project/barajitas/blob/main/docs/api.md)

```bash
pip install dugout
```

```python
import dugout

api = dugout.Dugout(token="your-api-token",
                    base_url="https://your-barajitas-host/api/v1/")

for card_set in api.sets():
    print(card_set["year"], card_set["name"])

# Filters are passed straight through to the API. A name search needs a
# set or checklist scope — the server refuses an unscoped one.
judges = api.cards(set=card_set["id"], name="aaron judge")

# Every id is a UUID that survives a re-import — safe to store.
```

## What it wraps

| Method | Endpoint |
|---|---|
| `sets()` / `set(id)` | `/sets/` |
| `checklists()` / `checklist(id)` | `/checklists/` |
| `checklist_index(id)` | `/checklists/{id}/index/` |
| `cards()` / `card(id)` | `/cards/` |
| `parallels()` / `parallel(id)` | `/parallels/` |

List methods return iterators that walk the pagination for you, at the
server's maximum page size.

## Honest by inheritance

The API refuses to guess, and this client passes that through verbatim:
`imported: null` on a checklist means declared-but-not-loaded, and
`coverage: "unknown"` on a parallel never means "all cards".

## Rate limits

Every response's rate-limit state is on `api.rate_limit`. On a 429 the
client sleeps out the server's `Retry-After` and retries once
(`wait_on_limit=False` to get a `RateLimited` exception instead — the
windows are fixed, not sliding, so hammering only keeps them full).

## Status

Early — the endpoints above work; typed models and the collection-sync
surface (for [vitrina](https://github.com/Barajitas-Project/vitrina))
will follow the server's API.
