Metadata-Version: 2.4
Name: bgg-search
Version: 0.5.0
Summary: Python client and CLI for the BoardGameGeek XML API
Author-email: Arnauld Van Muysewinkel <arnauldvm@gmail.com>
License-Expression: MIT
License-File: LICENSE
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.13
Requires-Python: >=3.13
Requires-Dist: httpx~=0.28.0
Provides-Extra: locked
Requires-Dist: anyio==4.13.0; extra == 'locked'
Requires-Dist: certifi==2026.5.20; extra == 'locked'
Requires-Dist: h11==0.16.0; extra == 'locked'
Requires-Dist: httpcore==1.0.9; extra == 'locked'
Requires-Dist: httpx==0.28.1; extra == 'locked'
Requires-Dist: idna==3.18; extra == 'locked'
Description-Content-Type: text/markdown

# bgg-search

`bgg-search` is a Python package and command-line tool for querying the
[BoardGameGeek](https://boardgamegeek.com) XML API. It lets you search for board games
by name and retrieve full game details — player counts, play time, weight, BGG rating, and
more — from the command line or from your own Python code.

**Contents:**

- [Installation](#installation)
- [Quickstart](#quickstart)
- [Documentation](#documentation)
- [Development](#development)

## Installation

```bash
pip install bgg-search
```

Requires **Python ≥ 3.13**.

A BGG API token is required to make requests. Obtain one by registering your application at
<https://boardgamegeek.com/applications>.

The token is resolved in this order — the first source found is used:

1. **`--token-file PATH`** — CLI option pointing to a file containing the token.
2. **`BGG_TOKEN`** — environment variable.
3. **`.bgg-token`** — plain-text file in the current working directory.

If none of the above is provided, the command exits with code 1 and prints an error to stderr.

## Quickstart

### CLI

```bash
export BGG_TOKEN=<your-token>

# Search for games matching a query
bgg-search search "Catan"
#       13  Catan
#   396790  Catan: New Energies
#      ...

# Fetch full details for a game by its BGG ID
bgg-search details 13
# id:            13
# name:          Catan
# year:          1995
# min_players:   3
# max_players:   4
# ...
```

### Python API

```python
import os
from bgg_search import BggClient, search_games, get_game

client = BggClient(token=os.environ["BGG_TOKEN"])

results = search_games("Catan", client)
for game in results:
    print(game.id, game.name)

details = get_game(13, client)
print(details.name, details.bgg_rating)
```

## Documentation

- [Python API reference](https://arnauldvm.github.io/bgg-search/api.html)
- [CLI reference](https://arnauldvm.github.io/bgg-search/cli.html)

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md).
