# py-draughts
[](https://github.com/michalskibinski109/checkers/actions/workflows/python-app.yml)
[](https://badge.fury.io/py/py-draughts)
[](https://pepy.tech/project/py-draughts)
Efficient modern and flexible implementation of the draughts game with a beautiful web interface.
Supports multiple variants of the game and allows playing against AI.
<img src="https://github.com/michalskibinski109/py-draughts/assets/77834536/11e6be5e-0cfc-412c-ac0b-2b8e87a4f450" width="800" style="border-radius: 1%;">
## Installation
```bash
pip install py-draughts
```
### [Documentation](https://michalskibinski109.github.io/py-draughts/)
## Key features
- Displays simple ascii board for different variants of the game.
```python
>>> from draughts import get_board
>>> board = get_board('standard', "W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32")
>>> board
. . . . . B . w . .
. . . . . . . . . .
. w . . . . . . . .
. . . . . . . . . .
. b . . . . . . . .
. . b . w . . . . .
. w . b . W . W . .
. . . . w . . . w .
. W . . . w . W . w
W . w . . . . . . .
>>> board = get_board("american")
>>> board
. b . b . b . b
b . b . b . b .
. b . b . b . b
. . . . . . . .
. . . . . . . .
w . w . w . w .
. w . w . w . w
w . w . w . w .
```
- Make and undo moves
```python
>>> board.push_uci("31-27")
>>> board.pop() # undo last move
Move: 31->27
>>> board.turn
Color.WHITE
```
- detects draws and wins
> [!Important]
> Those methods are variant specific. Each variant has different set of them.
```python
>>> board.game_over
False
>>> board.is_threefold_repetition
False
>>> board.is_5_moves_rule
False
>>> board.is_16_moves_rule
False
>>> board.is_25_moves_rule
False
>>> board.is_draw
False
```
- Validate and generate moves
```python
>>> board.push_uci("31-22")
ValueError: 31-22 is correct, but not legal in given position.
Legal moves are: ['31-27', '31-26', '32-28', '32-27', '33-29', '33-28', '34-30', '34-29', '35-30']
>>> list(board.legal_moves)
['31-27', '31-26', '32-28', '32-27', '33-29', '33-28', '34-30', '34-29', '35-30']
```
- Reads and writes fen strings
- Writes PDN strings
```python
>>> board.push_uci("31-27")
>>> board.push_uci("32-28")
>>> board.push_uci("27-23")
>>> board.push_uci("28-24")
>>> board.pdn
'[GameType "20"]
[Variant "Standard (international) checkers"]
[Result "-"]
1. 31-27 32-28 2. 27-23 28-24'
```
```python
>>> board = get_board('standard', "W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32")
>>> board.fen
'[FEN "W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32"]'
```
- Has simple engine
```python
>>> from draughts.engine import AlphaBetaEngine
>>> engine = AlphaBetaEngine(depth=5)
>>> engine.get_best_move(board, with_evaluation=True)
Move: 28->37, 3.0
```
## UI
1. Allows to play against AI.
2. Allows to play vs another player. (on the same computer)
3. Allows to test and find bugs in your engine.
```python
python -m draughts.server.server
```
#### Use for testing your engine.
_Example with simplest possible engine._
```python
>>> from draughts import Server
>>> import numpy as np
>>> get_best_mv = lambda board: np.random.choice(list(board.legal_moves))
>>> server = Server(get_best_move_method=get_best_mv)
>>> server.run()
INFO: Started server process [1617]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
_It is as simple as that!_
> [!Warning]
> Server will not start when using _google colab_
---
<img src="https://github.com/michalskibinski109/py-draughts/assets/77834536/11e4b7ea-4b47-4ab2-80b8-6d6cf1052869" width="800" />
## Contributing
Contributions to this project are welcome. If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on the project repository.
## Bibliography
1. [Notation](https://en.wikipedia.org/wiki/Portable_Draughts_Notation)
2. [Rules and variants](https://en.wikipedia.org/wiki/Checkers)
3. [List of PDNs](https://github.com/mig0/Games-Checkers/)
4. [Draughts online](https://lidraughts.org/)
5. [Additional 1 (Checkers online)](https://checkers.online/play)
6. [Additional 2 (Chinook)](https://webdocs.cs.ualberta.ca/~chinook/play/notation.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/michalskibinski109/py-draughts",
"name": "py-draughts",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "draughts,checkers,AI mini-max,game,board",
"author": "Micha\u0142 Skibi\u0144ski",
"author_email": "mskibinski109@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cc/8c/515c5b16bb38609b7a115f5d2854239ac0c94c8aae223b13ced2e73940ac/py-draughts-1.3.1.tar.gz",
"platform": null,
"description": "# py-draughts\r\n\r\n[](https://github.com/michalskibinski109/checkers/actions/workflows/python-app.yml)\r\n[](https://badge.fury.io/py/py-draughts)\r\n[](https://pepy.tech/project/py-draughts)\r\n\r\nEfficient modern and flexible implementation of the draughts game with a beautiful web interface. \r\nSupports multiple variants of the game and allows playing against AI.\r\n\r\n<img src=\"https://github.com/michalskibinski109/py-draughts/assets/77834536/11e6be5e-0cfc-412c-ac0b-2b8e87a4f450\" width=\"800\" style=\"border-radius: 1%;\">\r\n\r\n## Installation\r\n\r\n```bash\r\npip install py-draughts\r\n```\r\n\r\n\r\n### [Documentation](https://michalskibinski109.github.io/py-draughts/)\r\n\r\n## Key features\r\n\r\n- Displays simple ascii board for different variants of the game.\r\n\r\n```python\r\n>>> from draughts import get_board\r\n>>> board = get_board('standard', \"W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32\")\r\n>>> board\r\n . . . . . B . w . .\r\n . . . . . . . . . .\r\n . w . . . . . . . .\r\n . . . . . . . . . .\r\n . b . . . . . . . .\r\n . . b . w . . . . .\r\n . w . b . W . W . .\r\n . . . . w . . . w .\r\n . W . . . w . W . w\r\n W . w . . . . . . .\r\n\r\n>>> board = get_board(\"american\")\r\n>>> board\r\n . b . b . b . b\r\n b . b . b . b .\r\n . b . b . b . b\r\n . . . . . . . .\r\n . . . . . . . .\r\n w . w . w . w .\r\n . w . w . w . w\r\n w . w . w . w .\r\n\r\n```\r\n\r\n- Make and undo moves\r\n\r\n```python\r\n>>> board.push_uci(\"31-27\")\r\n>>> board.pop() # undo last move\r\nMove: 31->27\r\n>>> board.turn\r\nColor.WHITE\r\n```\r\n\r\n- detects draws and wins\r\n\r\n> [!Important] \r\n> Those methods are variant specific. Each variant has different set of them.\r\n\r\n\r\n```python\r\n>>> board.game_over\r\nFalse\r\n>>> board.is_threefold_repetition\r\nFalse\r\n>>> board.is_5_moves_rule\r\nFalse\r\n>>> board.is_16_moves_rule\r\nFalse\r\n>>> board.is_25_moves_rule\r\nFalse\r\n>>> board.is_draw\r\nFalse\r\n```\r\n\r\n- Validate and generate moves\r\n\r\n```python\r\n>>> board.push_uci(\"31-22\")\r\nValueError: 31-22 is correct, but not legal in given position.\r\nLegal moves are: ['31-27', '31-26', '32-28', '32-27', '33-29', '33-28', '34-30', '34-29', '35-30']\r\n\r\n>>> list(board.legal_moves)\r\n['31-27', '31-26', '32-28', '32-27', '33-29', '33-28', '34-30', '34-29', '35-30']\r\n```\r\n\r\n- Reads and writes fen strings\r\n\r\n\r\n- Writes PDN strings\r\n\r\n```python\r\n>>> board.push_uci(\"31-27\")\r\n>>> board.push_uci(\"32-28\")\r\n>>> board.push_uci(\"27-23\")\r\n>>> board.push_uci(\"28-24\")\r\n\r\n>>> board.pdn\r\n'[GameType \"20\"]\r\n [Variant \"Standard (international) checkers\"]\r\n [Result \"-\"]\r\n 1. 31-27 32-28 2. 27-23 28-24'\r\n```\r\n\r\n```python\r\n>>> board = get_board('standard', \"W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32\")\r\n>>> board.fen\r\n'[FEN \"W:W4,11,28,31,K33,K34,38,40,K41,43,K44,45,K46,47:BK3,21,27,32\"]'\r\n```\r\n- Has simple engine\r\n\r\n```python\r\n>>> from draughts.engine import AlphaBetaEngine\r\n>>> engine = AlphaBetaEngine(depth=5)\r\n>>> engine.get_best_move(board, with_evaluation=True)\r\nMove: 28->37, 3.0\r\n```\r\n\r\n## UI\r\n\r\n1. Allows to play against AI.\r\n2. Allows to play vs another player. (on the same computer)\r\n3. Allows to test and find bugs in your engine.\r\n\r\n```python\r\npython -m draughts.server.server\r\n```\r\n\r\n#### Use for testing your engine.\r\n\r\n\r\n\r\n_Example with simplest possible engine._\r\n\r\n\r\n\r\n```python\r\n>>> from draughts import Server\r\n>>> import numpy as np\r\n>>> get_best_mv = lambda board: np.random.choice(list(board.legal_moves))\r\n>>> server = Server(get_best_move_method=get_best_mv)\r\n>>> server.run()\r\nINFO: Started server process [1617]\r\nINFO: Waiting for application startup.\r\nINFO: Application startup complete.\r\nINFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)\r\n```\r\n\r\n_It is as simple as that!_\r\n\r\n> [!Warning] \r\n> Server will not start when using _google colab_\r\n\r\n---\r\n\r\n<img src=\"https://github.com/michalskibinski109/py-draughts/assets/77834536/11e4b7ea-4b47-4ab2-80b8-6d6cf1052869\" width=\"800\" />\r\n\r\n\r\n## Contributing\r\n\r\nContributions to this project are welcome. If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on the project repository.\r\n\r\n## Bibliography\r\n\r\n1. [Notation](https://en.wikipedia.org/wiki/Portable_Draughts_Notation)\r\n2. [Rules and variants](https://en.wikipedia.org/wiki/Checkers)\r\n3. [List of PDNs](https://github.com/mig0/Games-Checkers/)\r\n4. [Draughts online](https://lidraughts.org/)\r\n5. [Additional 1 (Checkers online)](https://checkers.online/play)\r\n6. [Additional 2 (Chinook)](https://webdocs.cs.ualberta.ca/~chinook/play/notation.html)\r\n",
"bugtrack_url": null,
"license": "GPL-3.0+",
"summary": "A draughts library with advenced (customizable) WEB UI move generation and validation, PDN parsing and writing. Supports multiple variants of game.",
"version": "1.3.1",
"project_urls": {
"Documentation": "https://michalskibinski109.github.io/py-draughts/index.html",
"Homepage": "https://github.com/michalskibinski109/py-draughts"
},
"split_keywords": [
"draughts",
"checkers",
"ai mini-max",
"game",
"board"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "75aece9fbada8b9a3ef1ba330bc37ca048c6025f1c641c6c0782cde337e37cf5",
"md5": "9b4cd991ff11f477b5e01bd4d6cb5ef0",
"sha256": "af6b90f373477e32694835514d7aac946801e02e0a995ec57d5384ae6806e107"
},
"downloads": -1,
"filename": "py_draughts-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b4cd991ff11f477b5e01bd4d6cb5ef0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 39399,
"upload_time": "2023-10-02T14:46:43",
"upload_time_iso_8601": "2023-10-02T14:46:43.941606Z",
"url": "https://files.pythonhosted.org/packages/75/ae/ce9fbada8b9a3ef1ba330bc37ca048c6025f1c641c6c0782cde337e37cf5/py_draughts-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc8c515c5b16bb38609b7a115f5d2854239ac0c94c8aae223b13ced2e73940ac",
"md5": "1adebaf730fab227614c2e30947a3335",
"sha256": "fe27340b9c3baa6dc0d8d6d4d11158c6acfbbe2d53347aef86a2660ded7fb224"
},
"downloads": -1,
"filename": "py-draughts-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "1adebaf730fab227614c2e30947a3335",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 37358,
"upload_time": "2023-10-02T14:46:45",
"upload_time_iso_8601": "2023-10-02T14:46:45.754369Z",
"url": "https://files.pythonhosted.org/packages/cc/8c/515c5b16bb38609b7a115f5d2854239ac0c94c8aae223b13ced2e73940ac/py-draughts-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-02 14:46:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michalskibinski109",
"github_project": "py-draughts",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "py-draughts"
}
JSON
