[](https://badge.fury.io/py/chess_insight)
# chess_insight
__Modern application for gathering chess data and analyzing chess games.__
### Features:
1. Download games from `lichess.org` and `chess.com`
2. Analyze games using set of custom methods and `stockfish-16` engine.
3. Parses games to `Game` object which contains all information about game and players to python object and `json`.
4. Provides method for exporting list of analyzed games to `csv`
## interactive mode
### installation
1. ```bash
pip install chess_insight # download application
```
2. [Optional] Download stockfish-16 from [here](https://stockfishchess.org/download/)
3. ```bash
python -m chess_insight # run app
```
Now answer questions and have fun with [csv](#csv) or [json](#json) data
## Python module
```bash
pip install chess_insight
```
[Optional] Download stockfish-16 from [here](https://stockfishchess.org/download/)
## Usage
- get games
```python
from chess_insight import ChessComApiCommunicator, LichessApiCommunicator
c1 = LichessApiCommunicator("path/to/stockfish")
c2 = ChessComApiCommunicator("path/to/stockfish" # if blank stocfish wont be used
)
games = list(c1.games_generator("your lichess username", 10, "blitz"))
games += list(c2.games_generator("your chess com username", 10, "blitz"))
```
- export games to csv
```python
chess_insight.export_games_to_csv(list(games))
```
#### CSV
| date | host | opening | opening_short | opponent_accuracy_opening_inaccuracy | opponent_accuracy_opening_mistake | opponent_accuracy_opening_blunder | opponent_accuracy_middle_game_inaccuracy | opponent_accuracy_middle_game_mistake | opponent_accuracy_middle_game_blunder | opponent_accuracy_end_game_inaccuracy | opponent_accuracy_end_game_mistake | opponent_accuracy_end_game_blunder | opponent_avg_move_time_opening | opponent_avg_move_time_middle_game | opponent_avg_move_time_end_game | opponent_elo | phases_opening | phases_middle_game | phases_end_game | player_accuracy_opening_inaccuracy | player_accuracy_opening_mistake | player_accuracy_opening_blunder | player_accuracy_middle_game_inaccuracy | player_accuracy_middle_game_mistake | player_accuracy_middle_game_blunder | player_accuracy_end_game_inaccuracy | player_accuracy_end_game_mistake | player_accuracy_end_game_blunder | player_avg_move_time_opening | player_avg_move_time_middle_game | player_avg_move_time_end_game | player_elo | player_color | result | time_class | time_control | url | username |
| ------------------- | ----------- | ------------------------------------- | ---------------- | ------------------------------------ | --------------------------------- | --------------------------------- | ---------------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------------------- | ---------------------------------- | ------------------------------ | ---------------------------------- | ------------------------------- | ------------ | -------------- | ------------------ | --------------- | ---------------------------------- | ------------------------------- | ------------------------------- | -------------------------------------- | ----------------------------------- | ----------------------------------- | ----------------------------------- | -------------------------------- | -------------------------------- | ---------------------------- | -------------------------------- | ----------------------------- | ---------- | ------------ | -------------------- | ---------- | ------------ | ---------------------------- | ----------- |
| 2022-05-26 16:51:04 | lichess.org | Pirc Defense: Classical Variation | Pirc Defense | 2 | 2 | 2 | 10 | 11 | 11 | 0 | 0 | 0 | 0.25 | 2.88 | 2.88 | 1737 | 8 | 51 | 51 | 1 | 0 | 0 | 2 | 1 | 1 | 0 | 0 | 0 | 1.0 | 2.2308 | 2.2308 | 1779 | white | ["white", "timeout"] | blitz | 180+0 | https://lichess.org/vf8yqCKh | pro100wdupe |
| 2022-05-11 20:26:37 | lichess.org | Vienna Game | Vienna Game | 1 | 1 | 1 | 8 | 9 | 9 | 14 | 14 | 14 | 0.0 | 2.875 | 2.2692 | 1792 | 3 | 48 | 104 | 0 | 0 | 0 | 3 | 2 | 2 | 0 | 0 | 0 | 1.5 | 5.9167 | 3.3462 | 1790 | white | ["black", "timeout"] | blitz | 180+0 | https://lichess.org/PjE2bZ8r | pro100wdupe |
| 2022-05-11 20:22:35 | lichess.org | Sicilian Defense: Chekhover Variation | Sicilian Defense | 0 | 0 | 0 | 1 | 1 | 1 | 0 | 0 | 0 | 1.0 | 6.2 | 6.2 | 1772 | 7 | 30 | 30 | 2 | 2 | 2 | 5 | 5 | 5 | 0 | 0 | 0 | 0.3333 | 5.9333 | 5.9333 | 1778 | black | ["black", "timeout"] | blitz | 180+0 | https://lichess.org/y1OSLD9A | pro100wdupe |
| 2022-05-05 07:52:37 | lichess.org | Indian Defense: Knights Variation | Indian Defense | 0 | 0 | 0 | 1 | 1 | 1 | 4 | 1 | 1 | 0.0 | 1.7917 | 2.5211 | 1789 | 3 | 48 | 142 | 1 | 1 | 1 | 11 | 11 | 11 | 18 | 22 | 22 | 0.0 | 2.3333 | 2.2676 | 1778 | black | ["draw", "timeout"] | blitz | 180+0 | https://lichess.org/Yn1BxD8r | pro100wdupe |
- get games as dict
```python
for game in games:
print(game.asdict())
```
#### json
```json
{
"date": datetime.datetime(2023, 9, 14, 21, 57, 47),
"host": "chess.com",
"opening": "Sicilian Defense: Closed, Traditional",
"opening_short": "Sicilian Defense",
"opponent": {
"avg_move_time": {"opening": 1.2, "middle_game": 5.1906, "end_game": 3.9467},
"elo": 1603,
"evaluation": {
"opening": {"inaccuracy": 1, "mistake": 1, "blunder": 1},
"middle_game": {"inaccuracy": 13, "mistake": 13, "blunder": 15},
"end_game": {"inaccuracy": 6, "mistake": 7, "blunder": 7}
}
},
"phases": {"opening": 4, "middle_game": 64, "end_game": 91},
"player": {
"avg_move_time": {"opening": 1.65, "middle_game": 3.4875, "end_game": 3.0109},
"elo": 1619,
"evaluation": {
"opening": {"inaccuracy": 0, "mistake": 0, "blunder": 0},
"middle_game": {"inaccuracy": 1, "mistake": 1, "blunder": 1},
"end_game": {"inaccuracy": 1, "mistake": 1, "blunder": 1}
}
},
"player_color": "white",
"result": ["white", "timeout"],
"time_class": "blitz",
"time_control": "180+0",
"url": "https://www.chess.com/game/live/88467619273",
"username": "barabasz60"
}
```
## Architecture
### Game object
| Attribute | Description |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `host` | Server where game was played. |
| `url` | Url to game. |
| `player_color` | Player color in game. |
| `time_control` | time control in format "time+increment" in seconds. e.g. "600+0" or "180+2" |
| `date` | Date and time of game in UTC. |
| `result` | Returns tuple (result, reason) eg: (white, resign) -> white won by resignation |
| `opening_short` | Short opening name in ECO format. e.g. "Sicilian Defense: Alapin Variation" -> "Sicilian Defense" |
| `phases` | Phases in half moves https://en.wikipedia.org/wiki/Chess_endgame#The_start_of_the_endgame |
| `host` | Server where game was played. |
| `username` | Username of player. |
| `time_class` | Time class of game. |
| `opening` | Opening name in ECO format. |
| `player` | Dict containing player data. Determined by `username`. |
| `opponent` | Dict containing opponent data. |
| `url` | Url to game. |
### Player object
| Attribute | Description |
| --------------- | -------------------------------------------- |
| `elo` | elo of player at the time of game. |
| `avg_move_time` | list with average move time for each phase. |
| `evaluation` | dict with number of mistakes for each phase. |
- example game:
## Example charts (Code can be found in [here](./example.py))
Raw data
{
"_id": null,
"home_page": "https://github.com/michalskibinski109/chess_insight",
"name": "chess-insight",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "chess,statistic,game,board",
"author": "Micha\u0142 Skibi\u0144ski",
"author_email": "mskibinski109@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/20/18/e3ff16badc4ed27762fddeca3cbad9065a6dd3f0b98fded5a123b7bb7d31/chess_insight-0.3.4.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/chess_insight)\n\n\n# chess_insight\n\n__Modern application for gathering chess data and analyzing chess games.__\n\n \n### Features:\n1. Download games from `lichess.org` and `chess.com`\n2. Analyze games using set of custom methods and `stockfish-16` engine.\n3. Parses games to `Game` object which contains all information about game and players to python object and `json`.\n4. Provides method for exporting list of analyzed games to `csv`\n\n## interactive mode\n\n\n\n\n### installation\n1. ```bash\n pip install chess_insight # download application\n ```\n2. [Optional] Download stockfish-16 from [here](https://stockfishchess.org/download/)\n\n\n3. ```bash\n python -m chess_insight # run app\n ```\nNow answer questions and have fun with [csv](#csv) or [json](#json) data\n\n\n\n## Python module\n\n```bash\npip install chess_insight\n```\n [Optional] Download stockfish-16 from [here](https://stockfishchess.org/download/)\n\n\n\n\n## Usage\n\n- get games \n\n```python\nfrom chess_insight import ChessComApiCommunicator, LichessApiCommunicator\n\nc1 = LichessApiCommunicator(\"path/to/stockfish\")\nc2 = ChessComApiCommunicator(\"path/to/stockfish\" # if blank stocfish wont be used\n)\n\ngames = list(c1.games_generator(\"your lichess username\", 10, \"blitz\"))\ngames += list(c2.games_generator(\"your chess com username\", 10, \"blitz\"))\n```\n\n- export games to csv\n\n```python \nchess_insight.export_games_to_csv(list(games))\n```\n \n#### CSV \n\n| date | host | opening | opening_short | opponent_accuracy_opening_inaccuracy | opponent_accuracy_opening_mistake | opponent_accuracy_opening_blunder | opponent_accuracy_middle_game_inaccuracy | opponent_accuracy_middle_game_mistake | opponent_accuracy_middle_game_blunder | opponent_accuracy_end_game_inaccuracy | opponent_accuracy_end_game_mistake | opponent_accuracy_end_game_blunder | opponent_avg_move_time_opening | opponent_avg_move_time_middle_game | opponent_avg_move_time_end_game | opponent_elo | phases_opening | phases_middle_game | phases_end_game | player_accuracy_opening_inaccuracy | player_accuracy_opening_mistake | player_accuracy_opening_blunder | player_accuracy_middle_game_inaccuracy | player_accuracy_middle_game_mistake | player_accuracy_middle_game_blunder | player_accuracy_end_game_inaccuracy | player_accuracy_end_game_mistake | player_accuracy_end_game_blunder | player_avg_move_time_opening | player_avg_move_time_middle_game | player_avg_move_time_end_game | player_elo | player_color | result | time_class | time_control | url | username |\n| ------------------- | ----------- | ------------------------------------- | ---------------- | ------------------------------------ | --------------------------------- | --------------------------------- | ---------------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------- | ---------------------------------- | ---------------------------------- | ------------------------------ | ---------------------------------- | ------------------------------- | ------------ | -------------- | ------------------ | --------------- | ---------------------------------- | ------------------------------- | ------------------------------- | -------------------------------------- | ----------------------------------- | ----------------------------------- | ----------------------------------- | -------------------------------- | -------------------------------- | ---------------------------- | -------------------------------- | ----------------------------- | ---------- | ------------ | -------------------- | ---------- | ------------ | ---------------------------- | ----------- |\n| 2022-05-26 16:51:04 | lichess.org | Pirc Defense: Classical Variation | Pirc Defense | 2 | 2 | 2 | 10 | 11 | 11 | 0 | 0 | 0 | 0.25 | 2.88 | 2.88 | 1737 | 8 | 51 | 51 | 1 | 0 | 0 | 2 | 1 | 1 | 0 | 0 | 0 | 1.0 | 2.2308 | 2.2308 | 1779 | white | [\"white\", \"timeout\"] | blitz | 180+0 | https://lichess.org/vf8yqCKh | pro100wdupe |\n| 2022-05-11 20:26:37 | lichess.org | Vienna Game | Vienna Game | 1 | 1 | 1 | 8 | 9 | 9 | 14 | 14 | 14 | 0.0 | 2.875 | 2.2692 | 1792 | 3 | 48 | 104 | 0 | 0 | 0 | 3 | 2 | 2 | 0 | 0 | 0 | 1.5 | 5.9167 | 3.3462 | 1790 | white | [\"black\", \"timeout\"] | blitz | 180+0 | https://lichess.org/PjE2bZ8r | pro100wdupe |\n| 2022-05-11 20:22:35 | lichess.org | Sicilian Defense: Chekhover Variation | Sicilian Defense | 0 | 0 | 0 | 1 | 1 | 1 | 0 | 0 | 0 | 1.0 | 6.2 | 6.2 | 1772 | 7 | 30 | 30 | 2 | 2 | 2 | 5 | 5 | 5 | 0 | 0 | 0 | 0.3333 | 5.9333 | 5.9333 | 1778 | black | [\"black\", \"timeout\"] | blitz | 180+0 | https://lichess.org/y1OSLD9A | pro100wdupe |\n| 2022-05-05 07:52:37 | lichess.org | Indian Defense: Knights Variation | Indian Defense | 0 | 0 | 0 | 1 | 1 | 1 | 4 | 1 | 1 | 0.0 | 1.7917 | 2.5211 | 1789 | 3 | 48 | 142 | 1 | 1 | 1 | 11 | 11 | 11 | 18 | 22 | 22 | 0.0 | 2.3333 | 2.2676 | 1778 | black | [\"draw\", \"timeout\"] | blitz | 180+0 | https://lichess.org/Yn1BxD8r | pro100wdupe |\n\n\n- get games as dict\n\n```python\nfor game in games:\n print(game.asdict())\n```\n\n#### json\n\n```json\n{\n \"date\": datetime.datetime(2023, 9, 14, 21, 57, 47),\n \"host\": \"chess.com\",\n \"opening\": \"Sicilian Defense: Closed, Traditional\",\n \"opening_short\": \"Sicilian Defense\",\n \"opponent\": {\n \"avg_move_time\": {\"opening\": 1.2, \"middle_game\": 5.1906, \"end_game\": 3.9467},\n \"elo\": 1603,\n \"evaluation\": {\n \"opening\": {\"inaccuracy\": 1, \"mistake\": 1, \"blunder\": 1},\n \"middle_game\": {\"inaccuracy\": 13, \"mistake\": 13, \"blunder\": 15},\n \"end_game\": {\"inaccuracy\": 6, \"mistake\": 7, \"blunder\": 7}\n }\n },\n \"phases\": {\"opening\": 4, \"middle_game\": 64, \"end_game\": 91},\n \"player\": {\n \"avg_move_time\": {\"opening\": 1.65, \"middle_game\": 3.4875, \"end_game\": 3.0109},\n \"elo\": 1619,\n \"evaluation\": {\n \"opening\": {\"inaccuracy\": 0, \"mistake\": 0, \"blunder\": 0},\n \"middle_game\": {\"inaccuracy\": 1, \"mistake\": 1, \"blunder\": 1},\n \"end_game\": {\"inaccuracy\": 1, \"mistake\": 1, \"blunder\": 1}\n }\n },\n \"player_color\": \"white\",\n \"result\": [\"white\", \"timeout\"],\n \"time_class\": \"blitz\",\n \"time_control\": \"180+0\",\n \"url\": \"https://www.chess.com/game/live/88467619273\",\n \"username\": \"barabasz60\"\n}\n```\n\n\n## Architecture \n\n### Game object\n\n| Attribute | Description |\n| --------------- | --------------------------------------------------------------------------------------------------------- |\n| `host` | Server where game was played. |\n| `url` | Url to game. |\n| `player_color` | Player color in game. |\n| `time_control` | time control in format \"time+increment\" in seconds. e.g. \"600+0\" or \"180+2\" |\n| `date` | Date and time of game in UTC. |\n| `result` | Returns tuple (result, reason) eg: (white, resign) -> white won by resignation |\n| `opening_short` | Short opening name in ECO format. e.g. \"Sicilian Defense: Alapin Variation\" -> \"Sicilian Defense\" |\n| `phases` | Phases in half moves https://en.wikipedia.org/wiki/Chess_endgame#The_start_of_the_endgame |\n| `host` | Server where game was played. |\n| `username` | Username of player. |\n| `time_class` | Time class of game. |\n| `opening` | Opening name in ECO format. |\n| `player` | Dict containing player data. Determined by `username`. |\n| `opponent` | Dict containing opponent data. |\n| `url` | Url to game. |\n\n### Player object\n\n| Attribute | Description |\n| --------------- | -------------------------------------------- |\n| `elo` | elo of player at the time of game. |\n| `avg_move_time` | list with average move time for each phase. |\n| `evaluation` | dict with number of mistakes for each phase. |\n\n\n\n- example game:\n\n\n\n## Example charts (Code can be found in [here](./example.py))\n\n\n\n\n",
"bugtrack_url": null,
"license": "GPL-3.0+",
"summary": "Modern package for analyzing chess games.",
"version": "0.3.4",
"project_urls": {
"Homepage": "https://github.com/michalskibinski109/chess_insight"
},
"split_keywords": [
"chess",
"statistic",
"game",
"board"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5517e086a8deb39005ec60c83cc7c51d296009de217eacece1036ed836027d13",
"md5": "e4563b6691ab8a7197a773c4726d11cc",
"sha256": "1e71d7169817b5e59478262637b31ca117a388034a5d51d656a23c6fda593303"
},
"downloads": -1,
"filename": "chess_insight-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4563b6691ab8a7197a773c4726d11cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 74987,
"upload_time": "2023-12-09T11:47:28",
"upload_time_iso_8601": "2023-12-09T11:47:28.382720Z",
"url": "https://files.pythonhosted.org/packages/55/17/e086a8deb39005ec60c83cc7c51d296009de217eacece1036ed836027d13/chess_insight-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2018e3ff16badc4ed27762fddeca3cbad9065a6dd3f0b98fded5a123b7bb7d31",
"md5": "af49e408fe6be9d092b16bc775b1b1fd",
"sha256": "06083b77c15c5975d8e3d53725951b503160f8287280ea3a4e1ccb71d8db69c7"
},
"downloads": -1,
"filename": "chess_insight-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "af49e408fe6be9d092b16bc775b1b1fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 76761,
"upload_time": "2023-12-09T11:47:29",
"upload_time_iso_8601": "2023-12-09T11:47:29.580991Z",
"url": "https://files.pythonhosted.org/packages/20/18/e3ff16badc4ed27762fddeca3cbad9065a6dd3f0b98fded5a123b7bb7d31/chess_insight-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-09 11:47:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michalskibinski109",
"github_project": "chess_insight",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "stockfish",
"specs": []
},
{
"name": "easy-logs",
"specs": []
},
{
"name": "chess",
"specs": []
},
{
"name": "berserk",
"specs": []
},
{
"name": "chess.com",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "rich",
"specs": []
},
{
"name": "textual",
"specs": []
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.3.0"
]
]
}
],
"lcname": "chess-insight"
}
JSON
