Skip to main content

Python client for Chess.com API

Project description

Python client for Chess.com Public API

GitHub Workflow Status (event) PyPI PyPI - Downloads

Python client for Chess.com API which provides public data from the chess.com website.

Installation

The package requires Python 3.8 or higher.

Install latest version from PyPI pip install chess.com

Resources

Usage

Retrieving Data

The package uses aiohttp for asynchronous requests and requests for synchronous requests to interact with the API.

Using client instance

from chessdotcom import ChessDotComClient
   
client = ChessDotComClient(user_agent = "My Python Application...")

response = client.get_player_profile("fabianocaruana")

response.player.name # 'Fabiano Caruana'
response.player.title # 'GM'
response.player.last_online_datetime # datetime.datetime(2024, 10, 25, 20, 8, 28)
response.player.joined_datetime # datetime.datetime(2013, 3, 17, 15, 14, 32)
# See readthedocs for full documentation of responses

# or access the source
response.json['player']['name'] # 'Fabiano Caruana'

Using functions

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

Asynchronous

from chessdotcom import ChessDotComClient

client = ChessDotComClient(user_agent = "My Python Application...", aio = True)

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

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

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

responses = asyncio.run(gather_cors(cors))

Managing 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 pass rate_limit_handler option to the client.

from chessdotcom import RateLimitHandler

client = ChessDotComClient(
    rate_limit_handler = RateLimitHandler(tts = 4,retries = 2)
)

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

Available Endpoints

Player Data

Clubs

Tournaments

Team Matches

Countries

Daily Puzzle

Other

Reporting Issues

Chess.com API is subject to change. Smoke tests are ran daily to make sure the package is working correctly.

Please open an Issue if you spot any bugs.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chess_com-3.11.1.tar.gz (23.0 kB view details)

Uploaded Source

Built Distribution

chess.com-3.11.1-py3-none-any.whl (47.9 kB view details)

Uploaded Python 3

File details

Details for the file chess_com-3.11.1.tar.gz.

File metadata

  • Download URL: chess_com-3.11.1.tar.gz
  • Upload date:
  • Size: 23.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.11

File hashes

Hashes for chess_com-3.11.1.tar.gz
Algorithm Hash digest
SHA256 2d57d7d0117907afae518bd7d14f3679cf3feae5a0cb701285c8ea0f69f71178
MD5 a8878b1d42169932306e6706aff25b8b
BLAKE2b-256 436f95afeee8691f17acb3149d098a2785f198ff1eabb21bb2ebb329d29da6c4

See more details on using hashes here.

File details

Details for the file chess.com-3.11.1-py3-none-any.whl.

File metadata

  • Download URL: chess.com-3.11.1-py3-none-any.whl
  • Upload date:
  • Size: 47.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.11

File hashes

Hashes for chess.com-3.11.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ab7e976fbd4039c2b01f791d3f82d955ae5a36356317aa9f708ccf0872b1f2b5
MD5 054c27cf213a7cfaa97637a73de9007f
BLAKE2b-256 819ee564c44050a582d275274e75459dccc55c78f6d07b153ad5998e6cf8204b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page