Metadata-Version: 2.4
Name: chesscompy
Version: 0.1.0
Summary: Python library extending the Chess.com public API (e.g. games by opening)
Author-email: Your Name <you@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cdewitt02/chesscompy
Project-URL: Repository, https://github.com/cdewitt02/chesscompy
Project-URL: Bug Tracker, https://github.com/cdewitt02/chesscompy/issues
Keywords: chess,chess.com,api,opening,eco
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Dynamic: license-file

# chesscompy

A small Python library that extends the [Chess.com public API](https://www.chess.com/news/view/published-data-api). It starts by adding **games by opening**: fetch a player's games and filter by ECO code or opening name (e.g. Pirc Defense, Caro-Kann).

The official API only supports:

- `GET /player/{username}/games/{YYYY}/{MM}` — games in a given month.

There is no server-side filter by opening, so chesscompy fetches games (by month) and filters client-side using each game's `eco` field (Chess.com opening URL) and PGN `[ECO "B07"]` tag.

## Install

```bash
pip install chesscompy
```

### Development

For an editable install with test tools:

```bash
git clone https://github.com/cdewitt02/chesscompy.git
cd chesscompy
python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS (.venv\Scripts\activate on Windows)
pip install -e ".[dev]"
```

Run tests:

```bash
pytest tests/ -v
```

## Usage

```python
from chesscompy import get_games, get_games_by_opening

# All games for a player in a month (direct API)
games = get_games("cdew4", 2026, 1)

# Games in that month that match an opening (client-side filter)
pirc_games = get_games_by_opening("cdew4", "B07", 2026, 1)   # ECO code
caro_games = get_games_by_opening("cdew4", "Caro-Kann", 2026, 1)  # name substring

# All games in a year matching an opening (12 API calls, then filter)
caro_in_year = get_games_by_opening("cdew4", "Caro-Kann", 2026)
```

Each game is a dict with the same shape as the API: `url`, `pgn`, `white`, `black`, `eco`, `time_control`, `fen`, etc.

## Project layout

- `chesscompy/` — main package  
  - `_client.py` — HTTP GET and URL helpers for api.chess.com  
  - `games.py` — `get_games(username, year, month)`, `get_games_by_opening(...)`  
  - `__init__.py` — re-exports public API
- `pyproject.toml` — metadata, dependencies, tool config
- `responses/` — sample API responses (e.g. for tests)

## License

MIT (see LICENSE).
