Python client for Chess.com Public API
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
- Documentation: readthedocs.org
- Published-Data API: chess.com
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
- Profile
- Stats
- Clubs
- Game archives
- Current games
- Games by month
- Games by month PGN
- Tournaments
- Titled players
- Team matches
- Current games to move
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.
1 maintainer
Metadata
1 maintainer
Release files for chess.com 3.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| chess_com-3.13.0.tar.gz | 23.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| chess_com-3.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 73.5 kB
Release files / chess_com-3.13.0.tar.gz
| Download URL | chess_com-3.13.0.tar.gz |
|---|---|
| Size | 23.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e06eb6d7740011574e4af9ea0e808a96d4bddade85dee76ff595bf26369bc1fd
|
|
BLAKE2b-256 checksum How to use checksums |
59d251ebf748fb337e2acb351598ecc9f58d8e967cb77cc60e1882452a606d3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Release files / chess_com-3.13.0-py3-none-any.whl
| Download URL | chess_com-3.13.0-py3-none-any.whl |
|---|---|
| Size | 49.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11fe0999a681b93385c8d5dabf9d692e734fa250fbe58e3717f9f7cb98f98981
|
|
BLAKE2b-256 checksum How to use checksums |
e9f4ef4860a2be9b2f6d4f7126c181f3554b711e577ec1e7613eeefb886f7ab6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
