A pure Python chess library with move generation and validation, Polyglot opening book probing, PGN reading and writing, Gaviota tablebase probing, Syzygy tablebase probing and XBoard/UCI engine communication.
Project description
Introduction
python-chess is a pure Python chess library with move generation, move validation and support for common formats. This is the Scholar’s mate in python-chess:
>>> import chess
>>> board = chess.Board()
>>> board.legal_moves
<LegalMoveGenerator at ... (Nh3, Nf3, Nc3, Na3, h3, g3, f3, e3, d3, c3, ...)>
>>> 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')
Documentation
Features
Supports Python 3.5+ and PyPy3.
IPython/Jupyter Notebook integration. SVG rendering docs.
>>> board
Chess variants: Standard, Chess960, Suicide, Giveaway, Atomic, King of the Hill, Racing Kings, Horde, Three-check, Crazyhouse. Variant docs.
Make and unmake moves.
>>> 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.
>>> 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.
>>> board.is_stalemate() False >>> board.is_insufficient_material() False >>> board.is_game_over() True
Detects repetitions. Has a half-move clock.
>>> 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.
>>> board.is_fivefold_repetition() False >>> board.is_seventyfive_moves() False
Detects checks and attacks.
>>> board.is_check() True >>> board.is_attacked_by(chess.WHITE, chess.E8) True >>> attackers = board.attackers(chess.WHITE, chess.F3) >>> attackers SquareSet(0x0000000000004040) >>> chess.G2 in attackers True >>> print(attackers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . . . . . . . 1 .
Parses and creates SAN representation of moves.
>>> 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.
>>> 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.
>>> 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.
>>> 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.
>>> 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() <Mainline at ... (1. e4 c5 2. c4 Nc6 3. Ne2 Nf6 4. Nbc3 Nb4 5. g3 Nd3#)> >>> first_game.headers["Result"] '0-1'
Probe Gaviota endgame tablebases (DTM, WDL). Docs.
Probe Syzygy endgame tablebases (DTZ, WDL). Docs.
>>> 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.
>>> import chess.engine >>> engine = chess.engine.SimpleEngine.popen_uci("stockfish") >>> engine.id.get("name") 'Stockfish 10 64 POPCNT' >>> 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) <PlayResult at ... (move=d6d1, ponder=c1d1, info={...}, draw_offered=False, resigned=False)> >>> engine.quit()
Installing
Download and install the latest release:
pip install python-chess
Selected use cases
If you like, let me know if you are creating something intresting with python-chess, for example:
a stand-alone chess computer based on DGT board – http://www.picochess.org/
a website to probe Syzygy endgame tablebases – https://syzygy-tables.info/
deep learning for Crazyhouse – https://github.com/QueensGambit/CrazyAra
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
a JIT compiled chess engine – https://github.com/SamRagusa/Batch-First
a GUI to play against UCI chess engines – http://johncheetham.com/projects/jcchess/
teaching Cognitive Science – https://jupyter.brynmawr.edu
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.
License
python-chess is licensed under the GPL 3 (or any later version at your option). Check out LICENSE.txt for the full text.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python-chess-bughouse-0.28.0.tar.gz
.
File metadata
- Download URL: python-chess-bughouse-0.28.0.tar.gz
- Upload date:
- Size: 6.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | dd3fbd4ab581bb6cb0ce2a99143493c169e28bc235b136e5b9f0edc744ec9bdf |
|
MD5 | e1418a662b467aff6c635e4214444be9 |
|
BLAKE2b-256 | 4ecbcbcec1049b7e117415898206704c765e53c78f31a1cc4b7e98aa4d570649 |
File details
Details for the file python_chess_bughouse-0.28.0-py3-none-any.whl
.
File metadata
- Download URL: python_chess_bughouse-0.28.0-py3-none-any.whl
- Upload date:
- Size: 131.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.11.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 95bae7eedb5047f2d18689eeed6c71b0e5b582f56eb4afd15f0d69f190d378e4 |
|
MD5 | 496f633d0cc7d9a8f596d714a73e041d |
|
BLAKE2b-256 | bd0ba71aefcb45368ef362218cc4b40821404ac59e84ba5d14e9455677685da2 |