| Name | chess.com JSON |
| Version |
3.11.0
JSON |
| download |
| home_page | None |
| Summary | Python Wrapper for Chess.com API |
| upload_time | 2025-01-18 16:18:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License |
| keywords |
chess
chess.com
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Python wrapper for Chess.com Public API
<img alt="GitHub Workflow Status (event)" src="https://img.shields.io/github/actions/workflow/status/sarartur/chess.com/build_and_publish.yml?branch=master"> <img src="https://img.shields.io/readthedocs/chessdotcom"> <img src="https://img.shields.io/github/license/sarartur/chess.com"> <img alt="PyPI" src="https://img.shields.io/pypi/v/chess.com"> <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/chess.com?color=007EC6"> <img src="https://img.shields.io/github/forks/sarartur/chess.com"> <img src="https://img.shields.io/github/stars/sarartur/chess.com">
---
Python wrapper 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](https://pypi.org/project/chess.com/) ```pip install chess.com```
## Resources
* Documentation: [readthedocs.org](https://chesscom.readthedocs.io/)
* Published-Data API: [chess.com](https://www.chess.com/news/view/published-data-api)
## Usage
### Retrieving Data
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.
#### Using client instance
``` python
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
``` python
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
``` python
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.
``` python
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.
``` python
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](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_profile.html)
- [Stats](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_stats.html)
- [Clubs](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_clubs.html)
- [Game archives](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_game_archives.html)
- [Current games](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_current_games.html)
- [Games by month](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_games_by_month.html)
- [Games by month PGN](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_games_by_month_pgn.html)
- [Tournaments](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_tournaments.html)
- [Titled players](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.titled_players.html)
- [Team matches](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_team_matches.html)
- [Current games to move](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_current_games_to_move.html)
#### Clubs
- [Club details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_details.html)
- [Club members](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_members.html)
- [Club matches](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_matches.html)
#### Tournaments
- [Tournament details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_details.html)
- [Tournament round](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_round.html)
- [Tournament round group details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_round_group_details.html)
#### Team Matches
- [Team match](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match.html)
- [Team match board](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_board.html)
- [Team match live](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_live.html)
- [Team match live board](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_live_board.html)
#### Countries
- [Country clubs](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_clubs.html)
- [Country players](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_players.html)
- [Country details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_details.html)
#### Daily Puzzle
- [Random daily puzzle](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.random_daily_puzzle.html)
- [Current daily puzzle](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.current_daily_puzzle.html)
#### Other
- [Streamers](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.streamers.html)
- [Leaderboards](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.leaderboards.html)
## Reporting Issues
Chess.com API is subject to change. Smoke tests are ran daily to make sure the package is working correctly.
<img src="https://img.shields.io/github/actions/workflow/status/sarartur/chess.com/smoke_tests.yml?branch=master&label=smoke%20tests"> <img src="https://img.shields.io/github/issues/sarartur/chess.com">
Please open an [Issue](https://github.com/sarartur/chess.com/issues) if you spot any bugs.
Raw data
{
"_id": null,
"home_page": null,
"name": "chess.com",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "chess, chess.com",
"author": null,
"author_email": "Artur Saradzhyan <sarartur.ruk@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/c2/641c81964f6421a5cfc662775cc32d4860bbaecb217e050193ebda69a600/chess_com-3.11.0.tar.gz",
"platform": null,
"description": "# Python wrapper for Chess.com Public API\n<img alt=\"GitHub Workflow Status (event)\" src=\"https://img.shields.io/github/actions/workflow/status/sarartur/chess.com/build_and_publish.yml?branch=master\"> <img src=\"https://img.shields.io/readthedocs/chessdotcom\"> <img src=\"https://img.shields.io/github/license/sarartur/chess.com\"> <img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/chess.com\"> <img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/chess.com?color=007EC6\"> <img src=\"https://img.shields.io/github/forks/sarartur/chess.com\"> <img src=\"https://img.shields.io/github/stars/sarartur/chess.com\">\n---\nPython wrapper for Chess.com API which provides public data from the chess.com website. \n## Installation \n**The package requires Python 3.8 or higher**.\n\nInstall latest version from [PyPI](https://pypi.org/project/chess.com/) ```pip install chess.com``` \n\n## Resources\n* Documentation: [readthedocs.org](https://chesscom.readthedocs.io/)\n* Published-Data API: [chess.com](https://www.chess.com/news/view/published-data-api)\n\n## Usage\n### Retrieving Data\nThe 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. \n\n#### Using client instance\n\n``` python\nfrom chessdotcom import ChessDotComClient\n \nclient = ChessDotComClient(user_agent = \"My Python Application...\")\n\nresponse = client.get_player_profile(\"fabianocaruana\")\n\nresponse.player.name # 'Fabiano Caruana'\nresponse.player.title # 'GM'\nresponse.player.last_online_datetime # datetime.datetime(2024, 10, 25, 20, 8, 28)\nresponse.player.joined_datetime # datetime.datetime(2013, 3, 17, 15, 14, 32)\n# See readthedocs for full documentation of responses\n\n# or access the source\nresponse.json['player']['name'] # 'Fabiano Caruana'\n```\n\n#### Using functions\n\n``` python\nfrom chessdotcom import get_player_profile, Client\n \nClient.request_config[\"headers\"][\"User-Agent\"] = (\n \"My Python Application. \"\n \"Contact me at email@example.com\"\n)\nresponse = get_player_profile(\"fabianocaruana\")\n```\n\n#### Asynchronous \n``` python \nfrom chessdotcom import ChessDotComClient\n\nclient = ChessDotComClient(user_agent = \"My Python Application...\", aio = True)\n\nusernames = [\"fabianocaruana\", \"GMHikaruOnTwitch\", \"MagnusCarlsen\", \"GarryKasparov\"]\n\ncors = [client.get_player_profile(name) for name in usernames]\n\nasync def gather_cors(cors):\n return await asyncio.gather(*cors)\n\nresponses = asyncio.run(gather_cors(cors))\n\n```\n#### Managing Rate Limit\nEvery 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.\n \n ``` python \n cors = [get_player_profile(name, tts = i / 10) for i, name in enumerate(usernames)]\n```\nThe second method is to pass ```rate_limit_handler``` option to the client.\n\n``` python\nfrom chessdotcom import RateLimitHandler\n\nclient = ChessDotComClient(\n rate_limit_handler = RateLimitHandler(tts = 4,retries = 2)\n)\n```\nIf the initial request gets rate limited the client will automatically retry the request **2 more times** with an interval of **4 seconds**.\n\n## Available Endpoints\n\n#### Player Data\n\n- [Profile](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_profile.html)\n- [Stats](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_stats.html)\n- [Clubs](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_clubs.html)\n- [Game archives](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_game_archives.html)\n- [Current games](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_current_games.html)\n- [Games by month](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_games_by_month.html)\n- [Games by month PGN](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_games_by_month_pgn.html)\n- [Tournaments](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_tournaments.html)\n- [Titled players](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.titled_players.html)\n- [Team matches](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_team_matches.html)\n- [Current games to move](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.player_current_games_to_move.html)\n\n#### Clubs\n\n- [Club details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_details.html)\n- [Club members](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_members.html)\n- [Club matches](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.club_matches.html)\n\n\n#### Tournaments\n\n- [Tournament details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_details.html)\n- [Tournament round](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_round.html)\n- [Tournament round group details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.tournament_round_group_details.html)\n\n#### Team Matches\n\n- [Team match](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match.html)\n- [Team match board](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_board.html)\n- [Team match live](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_live.html)\n- [Team match live board](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.team_match_live_board.html)\n\n#### Countries\n\n- [Country clubs](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_clubs.html)\n- [Country players](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_players.html)\n- [Country details](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.country_details.html)\n\n#### Daily Puzzle\n\n- [Random daily puzzle](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.random_daily_puzzle.html)\n- [Current daily puzzle](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.current_daily_puzzle.html)\n\n#### Other\n\n- [Streamers](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.streamers.html)\n- [Leaderboards](https://chesscom.readthedocs.io/en/latest/members/chessdotcom.endpoints.leaderboards.html)\n\n## Reporting Issues\n\nChess.com API is subject to change. Smoke tests are ran daily to make sure the package is working correctly.\n\n<img src=\"https://img.shields.io/github/actions/workflow/status/sarartur/chess.com/smoke_tests.yml?branch=master&label=smoke%20tests\"> <img src=\"https://img.shields.io/github/issues/sarartur/chess.com\">\n\nPlease open an [Issue](https://github.com/sarartur/chess.com/issues) if you spot any bugs.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Python Wrapper for Chess.com API",
"version": "3.11.0",
"project_urls": {
"Documentation": "https://chesscom.readthedocs.io",
"Homepage": "https://github.com/sarartur/chess.com"
},
"split_keywords": [
"chess",
" chess.com"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "71603d65d6325796038557523b67c512ee648d60097b1758b5a6e83238d894cd",
"md5": "2995416b0686db357d1a1e33b47d9c66",
"sha256": "b39018a69be403b36a262896d40ad276e10736c8a10e3df3eb291ff6a75928c1"
},
"downloads": -1,
"filename": "chess.com-3.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2995416b0686db357d1a1e33b47d9c66",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47954,
"upload_time": "2025-01-18T16:18:40",
"upload_time_iso_8601": "2025-01-18T16:18:40.142771Z",
"url": "https://files.pythonhosted.org/packages/71/60/3d65d6325796038557523b67c512ee648d60097b1758b5a6e83238d894cd/chess.com-3.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0fc2641c81964f6421a5cfc662775cc32d4860bbaecb217e050193ebda69a600",
"md5": "0e884b710080edcd82219e8ccc5bead0",
"sha256": "079ce8e1a67dfa5e1c17eeeb850c45481992cb5d0e8cccb107496868cd0bdc4d"
},
"downloads": -1,
"filename": "chess_com-3.11.0.tar.gz",
"has_sig": false,
"md5_digest": "0e884b710080edcd82219e8ccc5bead0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22956,
"upload_time": "2025-01-18T16:18:42",
"upload_time_iso_8601": "2025-01-18T16:18:42.005909Z",
"url": "https://files.pythonhosted.org/packages/0f/c2/641c81964f6421a5cfc662775cc32d4860bbaecb217e050193ebda69a600/chess_com-3.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-18 16:18:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sarartur",
"github_project": "chess.com",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "chess.com"
}
