Welcome to Chess.com Wrapper’s Documentation!

Description

“A full Python Wrapper around Chess.com API which provides public data from the Chess.com website. All endpoints provided by Chess.com’s API are available in the respectively named methods. The package allows for simple interaction with the API, eliminating the need for repetitive code and testing.”

Indices and tables

Getting Started

Installation

The package requires Python 3.7 or higher.

Install from PyPI: pip install chess.com

Retrieving Data

All the functions return a ChessDotComResponse object. The data can be accessed in dictionary format or via attributes.

The package uses aiohttp <https://docs.aiohttp.org/en/stable/> for asynchronous requests and requests <https://requests.readthedocs.io/en/latest/> for synchronous requests to interact with the API.

Synchronous

from chessdotcom import get_player_profile, Client

Client.request_config["headers"]["User-Agent"] = (
   "My Python Application. "
   "Contact me at email@example.com"
)
response = get_player_profile("fabianocaruana")

player_name = response.json['player']['name']
#or
player_name = response.player.name

Asynchronous

import asyncio

from chessdotcom.aio import get_player_profile, Client
#or
from chessdotcom import Client
Client.aio = True

usernames = ["fabianocaruana", "GMHikaruOnTwitch", "MagnusCarlsen", "GarryKasparov"]

cors = [get_player_profile(name) for name in usernames]

async def gather_cors(cors):
   responses = await asyncio.gather(*cors)
   return responses

responses = asyncio.run(gather_cors(cors))

Managing Rate Limit

The package offers several ways to deal with the rate limit. Every function accepts a tts parameter which controls the number of seconds the Client will wait before making the request. This is useful if running a lot of coroutines at once.

cors = [get_player_profile(name, tts = i / 10) for i, name in enumerate(usernames)]

The second method is to adjust the rate_limit_handler attribute of the Client object.

Client.rate_limit_handler.tries = 2
Client.rate_limit_handler.tts = 4

If the initial request gets rate limited the client will automatically retry the request 2 more times with an interval of 4 seconds.

Configuring Headers

The project uses requests package to interact with the API. Headers and proxies can be set through the Client object. Official Chess.com documentation requires adding a User-Agent header.

from chessdotcom import Client

Client.request_config["headers"]["User-Agent"] = (
 "My Python Application. "
 "Contact me at email@example.com"
)

All the methods from the package will now include the header when making a request to the API.

API Reference

chessdotcom.types

exception chessdotcom.types.ChessDotComError(status_code: int, response_text: str, headers: CIMultiDictProxy)

Custom Exception object.

Variables:
  • status_code – Contains the status code of the API’s response.

  • json – Dictionary representation of the API’s response.

  • text – API’s raw response decoded into a string.

class chessdotcom.types.ChessDotComResponse(response_text: str, top_level_attr: Optional[str] = None, no_json=False)

Custom object for holding the API’s response.

Variables:
  • json – Dictionary representation of the API’s response.

  • {nested_object} – Object representation of the API’s response.

  • text – API’s raw response decoded into a string.

class chessdotcom.types.Collection(**kwargs)

chessdotcom.client

class chessdotcom.client.Client

Client for Chess.com Public API. The client is only responsible for making calls.

Variables:
  • request_config – Dictionary containing extra keyword arguments for requests to the API (headers, proxy, etc).

  • aio – Determines if the functions behave asynchronously.

Loop_callback:

Function that returns the current loop for aiohttp.ClientSession.

Rate_limit_handler:

A RateLimitHandler object. See chessdotcom.client.RateLimitHandler.

class chessdotcom.client.RateLimitHandler(tts=0, retries=1)

Rate Limit Handler for handling 429 responses from the API.

Tts:

The time the client will wait after a 429 response if there are tries remaining.

Retries:

The number of times the client will retry calling the API after the first attempt.

chessdotcom.client.get_club_details(url_id: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing additional details about a club.

chessdotcom.client.get_club_matches(url_id: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of daily and club matches.

chessdotcom.client.get_club_members(url_id: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of club members.

chessdotcom.client.get_country_clubs(iso: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • iso – country’s 2-character ISO 3166 code.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of URLs for clubs identified as being in or associated with this country.

chessdotcom.client.get_country_details(iso: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • iso – country’s 2-character ISO 3166 code.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing additional details about a country.

chessdotcom.client.get_country_players(iso: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • iso – country’s 2-character ISO 3166 code.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of usernames for players who identify themselves as being in this country.

chessdotcom.client.get_current_daily_puzzle(tts=0, **kwargs) ChessDotComResponse
Parameters:

tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about the daily puzzle found in www.chess.com.

chessdotcom.client.get_leaderboards(tts=0, **kwargs) ChessDotComResponse
Parameters:

tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about top 50 player for daily and live games, tactics and lessons.

chessdotcom.client.get_player_clubs(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of clubs the player is a member of.

chessdotcom.client.get_player_current_games(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of Daily Chess games that a player is currently playing.

chessdotcom.client.get_player_current_games_to_move(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of Daily Chess games where it is the player’s turn to act.

chessdotcom.client.get_player_game_archives(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of monthly archives available for this player.

chessdotcom.client.get_player_games_by_month(username: str, year: Optional[Union[str, int]] = None, month: Optional[Union[str, int]] = None, datetime_obj: Optional[datetime] = None, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • year – the year (yyyy).

  • month – the month (mm).

  • date – datetime.datetime of the month. Can be passed in instead of month and year parameters.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of live and daily Chess games that a player has finished.

chessdotcom.client.get_player_games_by_month_pgn(username: str, year: Optional[Union[str, int]] = None, month: Optional[Union[str, int]] = None, datetime_obj: Optional[datetime] = None, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • year – the year (yyyy).

  • month – the month (mm).

  • date – datetime.datetime of the month. Can be passed in instead of month and year parameters.

Returns:

ChessDotComResponse object containing standard multi-game format PGN containing all games for a month.

chessdotcom.client.get_player_profile(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about the player’s profile.

chessdotcom.client.get_player_stats(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about the plyers’s ratings, win/loss, and other stats.

chessdotcom.client.get_player_team_matches(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of team matches the player has attended, is participating or is currently registered.

chessdotcom.client.get_player_tournaments(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of tournaments the player is registered, is attending or has attended in the past.

chessdotcom.client.get_random_daily_puzzle(tts=0, **kwargs) ChessDotComResponse
Parameters:

tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about a randomly picked daily puzzle.

chessdotcom.client.get_streamers(tts=0, **kwargs) ChessDotComResponse
Parameters:

tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing information about Chess.com streamers.

chessdotcom.client.get_team_match(match_id: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • match_id – the id of the match.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a team match and players playing that match.

chessdotcom.client.get_team_match_board(match_id: int, board_num: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • match_id – the id of the match.

  • board_num – the number of the board.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a team match board.

chessdotcom.client.get_team_match_live(match_id: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • match_id – the id of the match.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a team match and players playing that match.

chessdotcom.client.get_team_match_live_board(match_id: int, board_num: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • match_id – the id of the match.

  • board_num – the number of the board.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a team match board.

chessdotcom.client.get_titled_players(title_abbrev: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • title_abbrev – abbreviation of chess title.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing a list of usernames.

chessdotcom.client.get_tournament_details(url_id: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a daily, live and arena tournament.

chessdotcom.client.get_tournament_round(url_id: str, round_num: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • round_num – the round of the tournament.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a tournament’s round.

chessdotcom.client.get_tournament_round_group_details(url_id: str, round_num: int, group_num: int, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • url_id – URL for the club’s web page on www.chess.com.

  • round_num – the round of the tournament.

  • group_num – the group in the tournament.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing details about a tournament’s round group.

chessdotcom.client.is_player_online(username: str, tts=0, **kwargs) ChessDotComResponse
Parameters:
  • username – username of the player.

  • tts – the time the client will wait before making the first request.

Returns:

ChessDotComResponse object containing infomation about whether or not a player is online