chesscompy 0.1.0

Python library extending the Chess.com public API (e.g. games by opening)

chesscompy

A small Python library that extends the Chess.com public 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

pip install chesscompy

Development

For an editable install with test tools:

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:

pytest tests/ -v

Usage

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).