diff --git a/README.rst b/README.rst index 37506a259..e69de29bb 100644 --- a/README.rst +++ b/README.rst @@ -1,365 +0,0 @@ -python-chess: a chess library for Python -======================================== - -.. image:: https://github.com/niklasf/python-chess/workflows/Test/badge.svg - :target: https://github.com/niklasf/python-chess/actions - :alt: Test status - -.. image:: https://badge.fury.io/py/chess.svg - :target: https://pypi.python.org/pypi/chess - :alt: PyPI package - -.. image:: https://readthedocs.org/projects/python-chess/badge/?version=latest - :target: https://python-chess.readthedocs.io/en/latest/ - :alt: Docs - -.. image:: https://badges.gitter.im/python-chess/community.svg - :target: https://gitter.im/python-chess/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - :alt: Chat on Gitter - -Introduction ------------- - -python-chess is a chess library for Python, with move generation, -move validation, and support for common formats. This is the Scholar's mate in -python-chess: - -.. code:: python - - >>> import chess - - >>> board = chess.Board() - - >>> board.legal_moves # doctest: +ELLIPSIS - - >>> chess.Move.from_uci("a8a1") in board.legal_moves - False - - >>> board.push_san("e4") - Move.from_uci('e2e4') - >>> board.push_san("e5") - Move.from_uci('e7e5') - >>> board.push_san("Qh5") - Move.from_uci('d1h5') - >>> board.push_san("Nc6") - Move.from_uci('b8c6') - >>> board.push_san("Bc4") - Move.from_uci('f1c4') - >>> board.push_san("Nf6") - Move.from_uci('g8f6') - >>> board.push_san("Qxf7") - Move.from_uci('h5f7') - - >>> board.is_checkmate() - True - - >>> board - Board('r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4') - -Installing ----------- - -Download and install the latest release: - -:: - - pip install chess - - -`Documentation `__ --------------------------------------------------------------------- - -* `Core `_ -* `PGN parsing and writing `_ -* `Polyglot opening book reading `_ -* `Gaviota endgame tablebase probing `_ -* `Syzygy endgame tablebase probing `_ -* `UCI/XBoard engine communication `_ -* `Variants `_ -* `Changelog `_ - -Features --------- - -* Supports Python 3.7+. Includes mypy typings. - -* IPython/Jupyter Notebook integration. - `SVG rendering docs `_. - - .. code:: python - - >>> board # doctest: +SKIP - - .. image:: https://backscattering.de/web-boardimage/board.png?fen=r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR&lastmove=h5f7&check=e8 - :alt: r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR - -* Chess variants: Standard, Chess960, Suicide, Giveaway, Atomic, - King of the Hill, Racing Kings, Horde, Three-check, Crazyhouse. - `Variant docs `_. - -* Make and unmake moves. - - .. code:: python - - >>> Nf3 = chess.Move.from_uci("g1f3") - >>> board.push(Nf3) # Make the move - - >>> board.pop() # Unmake the last move - Move.from_uci('g1f3') - -* Show a simple ASCII board. - - .. code:: python - - >>> board = chess.Board("r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4") - >>> print(board) - r . b q k b . r - p p p p . Q p p - . . n . . n . . - . . . . p . . . - . . B . P . . . - . . . . . . . . - P P P P . P P P - R N B . K . N R - -* Detects checkmates, stalemates and draws by insufficient material. - - .. code:: python - - >>> board.is_stalemate() - False - >>> board.is_insufficient_material() - False - >>> board.outcome() - Outcome(termination=Termination.CHECKMATE, winner=True) - -* Detects repetitions. Has a half-move clock. - - .. code:: python - - >>> board.can_claim_threefold_repetition() - False - >>> board.halfmove_clock - 0 - >>> board.can_claim_fifty_moves() - False - >>> board.can_claim_draw() - False - - With the new rules from July 2014, a game ends as a draw (even without a - claim) once a fivefold repetition occurs or if there are 75 moves without - a pawn push or capture. Other ways of ending a game take precedence. - - .. code:: python - - >>> board.is_fivefold_repetition() - False - >>> board.is_seventyfive_moves() - False - -* Detects checks and attacks. - - .. code:: python - - >>> board.is_check() - True - >>> board.is_attacked_by(chess.WHITE, chess.E8) - True - - >>> attackers = board.attackers(chess.WHITE, chess.F3) - >>> attackers - SquareSet(0x0000_0000_0000_4040) - >>> chess.G2 in attackers - True - >>> print(attackers) - . . . . . . . . - . . . . . . . . - . . . . . . . . - . . . . . . . . - . . . . . . . . - . . . . . . . . - . . . . . . 1 . - . . . . . . 1 . - -* Parses and creates SAN representation of moves. - - .. code:: python - - >>> board = chess.Board() - >>> board.san(chess.Move(chess.E2, chess.E4)) - 'e4' - >>> board.parse_san('Nf3') - Move.from_uci('g1f3') - >>> board.variation_san([chess.Move.from_uci(m) for m in ["e2e4", "e7e5", "g1f3"]]) - '1. e4 e5 2. Nf3' - -* Parses and creates FENs, extended FENs and Shredder FENs. - - .. code:: python - - >>> board.fen() - 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1' - >>> board.shredder_fen() - 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w HAha - 0 1' - >>> board = chess.Board("8/8/8/2k5/4K3/8/8/8 w - - 4 45") - >>> board.piece_at(chess.C5) - Piece.from_symbol('k') - -* Parses and creates EPDs. - - .. code:: python - - >>> board = chess.Board() - >>> board.epd(bm=board.parse_uci("d2d4")) - 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - bm d4;' - - >>> ops = board.set_epd("1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - bm Qd1+; id \"BK.01\";") - >>> ops == {'bm': [chess.Move.from_uci('d6d1')], 'id': 'BK.01'} - True - -* Detects `absolute pins and their directions `_. - -* Reads Polyglot opening books. - `Docs `__. - - .. code:: python - - >>> import chess.polyglot - - >>> book = chess.polyglot.open_reader("data/polyglot/performance.bin") - - >>> board = chess.Board() - >>> main_entry = book.find(board) - >>> main_entry.move - Move.from_uci('e2e4') - >>> main_entry.weight - 1 - - >>> book.close() - -* Reads and writes PGNs. Supports headers, comments, NAGs and a tree of - variations. - `Docs `__. - - .. code:: python - - >>> import chess.pgn - - >>> with open("data/pgn/molinari-bordais-1979.pgn") as pgn: - ... first_game = chess.pgn.read_game(pgn) - - >>> first_game.headers["White"] - 'Molinari' - >>> first_game.headers["Black"] - 'Bordais' - - >>> first_game.mainline() # doctest: +ELLIPSIS - - - >>> first_game.headers["Result"] - '0-1' - -* Probe Gaviota endgame tablebases (DTM, WDL). - `Docs `__. - -* Probe Syzygy endgame tablebases (DTZ, WDL). - `Docs `__. - - .. code:: python - - >>> import chess.syzygy - - >>> tablebase = chess.syzygy.open_tablebase("data/syzygy/regular") - - >>> # Black to move is losing in 53 half moves (distance to zero) in this - >>> # KNBvK endgame. - >>> board = chess.Board("8/2K5/4B3/3N4/8/8/4k3/8 b - - 0 1") - >>> tablebase.probe_dtz(board) - -53 - - >>> tablebase.close() - -* Communicate with UCI/XBoard engines. Based on ``asyncio``. - `Docs `__. - - .. code:: python - - >>> import chess.engine - - >>> engine = chess.engine.SimpleEngine.popen_uci("stockfish") - - >>> board = chess.Board("1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - 0 1") - >>> limit = chess.engine.Limit(time=2.0) - >>> engine.play(board, limit) # doctest: +ELLIPSIS - - - >>> engine.quit() - -Selected projects ------------------ - -If you like, share interesting things you are using python-chess for, for example: - -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/syzygy.png?raw=true | https://syzygy-tables.info/ | -| :height: 64 | | -| :width: 64 | | -| :target: https://syzygy-tables.info/ | A website to probe Syzygy endgame tablebases | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/maia.png?raw=true | https://maiachess.com/ | -| :height: 64 | | -| :width: 64 | | -| :target: https://maiachess.com/ | A human-like neural network chess engine | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/clente-chess.png?raw=true | `clente/chess `_ | -| :height: 64 | | -| :width: 64 | | -| :target: https://github.com/clente/chess | Oppinionated wrapper to use python-chess from the R programming language | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/crazyara.png?raw=true | https://crazyara.org/ | -| :height: 64 | | -| :width: 64 | | -| :target: https://crazyara.org/ | Deep learning for Crazyhouse | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/jcchess.png?raw=true | `http://johncheetham.com `_ | -| :height: 64 | | -| :width: 64 | | -| :target: http://johncheetham.com/projects/jcchess/ | A GUI to play against UCI chess engines | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| .. image:: https://github.com/niklasf/python-chess/blob/master/docs/images/pettingzoo.png?raw=true | `https://www.pettingzoo.ml `_ | -| :width: 64 | | -| :height: 64 | | -| :target: https://www.pettingzoo.ml/classic/chess | A multi-agent reinforcement learning environment | -+------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ - -* a stand-alone chess computer based on DGT board – http://www.picochess.org/ -* a bridge between Lichess API and chess engines – https://github.com/careless25/lichess-bot -* a command-line PGN annotator – https://github.com/rpdelaney/python-chess-annotator -* an HTTP microservice to render board images – https://github.com/niklasf/web-boardimage -* building a toy chess engine with alpha-beta pruning, piece-square tables, and move ordering – https://healeycodes.com/building-my-own-chess-engine/ -* a JIT compiled chess engine – https://github.com/SamRagusa/Batch-First -* teaching Cognitive Science – `https://jupyter.brynmawr.edu `_ -* an `Alexa skill to play blindfold chess `_ – https://github.com/laynr/blindfold-chess -* a chessboard widget for PySide2 – https://github.com/H-a-y-k/hichesslib -* Django Rest Framework API for multiplayer chess – https://github.com/WorkShoft/capablanca-api - -Acknowledgements ----------------- - -Thanks to the Stockfish authors and thanks to Sam Tannous for publishing his -approach to `avoid rotated bitboards with direct lookup (PDF) `_ -alongside his GPL2+ engine `Shatranj `_. -Some move generation ideas are taken from these sources. - -Thanks to Ronald de Man for his -`Syzygy endgame tablebases `_. -The probing code in python-chess is very directly ported from his C probing code. - -Thanks to `Kristian Glass `_ for -transferring the namespace ``chess`` on PyPI. - -License -------- - -python-chess is licensed under the GPL 3 (or any later version at your option). -Check out LICENSE.txt for the full text.