Skip to main content

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

https://travis-ci.org/niklasf/python-chess.svg?branch=v0.20.0 https://coveralls.io/repos/github/niklasf/python-chess/badge.svg?branch=master https://badge.fury.io/py/python-chess.svg https://readthedocs.org/projects/python-chess/badge/?version=v0.20.0

Introduction

python-chess is a pure Python chess library with move generation and validation and handling of common formats. This is the scholars mate in python-chess:

>>> import chess

>>> board = chess.Board()

>>> board.legal_moves  # doctest: +ELLIPSIS
<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 2.6+, Python 3.3+ and PyPy.

  • IPython notebook integration. SVG rendering docs.

    >>> board  # doctest: +SKIP
    https://backscattering.de/web-boardimage/board.png?fen=r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR&lastmove=h5f7&check=e8
  • 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 drawn (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.

  • Read 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
    >>> main_entry.learn
    0
    
    >>> book.close()
  • Read and write 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'
    
    >>> # Get the mainline as a list of moves.
    >>> moves = first_game.main_line()
    >>> first_game.board().variation_san(moves)
    '1. e4 c5 2. c4 Nc6 3. Ne2 Nf6 4. Nbc3 Nb4 5. g3 Nd3#'
    
    >>> # Iterate through the mainline of this embarrasingly short game.
    >>> node = first_game
    >>> while not node.is_end():
    ...     next_node = node.variations[0]
    ...     print(node.board().san(next_node.move))
    ...     node = next_node
    e4
    c5
    c4
    Nc6
    Ne2
    Nf6
    Nbc3
    Nb4
    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
    
    >>> tablebases = chess.syzygy.open_tablebases("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")
    >>> tablebases.probe_dtz(board)
    -53
    
    >>> tablebases.close()
  • Communicate with an UCI engine. Docs.

    >>> import chess.uci
    
    >>> engine = chess.uci.popen_engine("stockfish")
    >>> engine.uci()
    >>> engine.author  # doctest: +SKIP
    'Tord Romstad, Marco Costalba and Joona Kiiski'
    
    >>> # Synchronous mode.
    >>> board = chess.Board("1k1r4/pp1b1R2/3q2pp/4p3/2B5/4Q3/PPP2B2/2K5 b - - 0 1")
    >>> engine.position(board)
    >>> engine.go(movetime=2000)  # Gets tuple of bestmove and ponder move.
    BestMove(bestmove=Move.from_uci('d6d1'), ponder=Move.from_uci('c1d1'))
    
    >>> # Asynchronous mode.
    >>> def callback(command):
    ...    bestmove, ponder = command.result()
    ...    assert bestmove == chess.Move.from_uci('d6d1')
    ...
    >>> command = engine.go(movetime=2000, async_callback=callback)
    >>> command.done()
    False
    >>> command.result()
    BestMove(bestmove=Move.from_uci('d6d1'), ponder=Move.from_uci('c1d1'))
    >>> command.done()
    True
    
    >>> # Quit.
    >>> engine.quit()
    0

Installing

Download and install the latest release:

pip install python-chess[engine,gaviota]

Selected use cases

If you like, let me know if you are creating something intresting with python-chess, for example:

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 Miguel A. Ballicora for his Gaviota tablebases. (I wish the generating code was free software).

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

python-chess-0.20.0.tar.gz (131.2 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page