Chessnut is a simple chess board model written in Python. Chessnut is not a chess engine -- it has no AI to play games, and it has no GUI. It is a simple package that can import/export games in Forsyth-Edwards Notation (FEN), generate a list of legal moves for the current board position, intelligently validate & apply moves (including en passant, castling, etc.), and keep track of the game with a history of both moves and corresponding FEN representation.
Chessnut is not written for speed, it is written for simplicity (there are only two real classes, and only about 200 lines of code). By adding a custom move evaluation function, Chessnut could be used as a chess engine. The simplicity of the model lends itself well to studying the construction of a chess engine without worrying about implementing a chess model, or to easily find the set of legal moves for either player on a particular chess board for use in conjunction with another chess application.
Chessnut can be used as a module within your project or it can be installed on your system as a package. If you're going to install it as a package, you should consider using Virtualenv to manage your python environment. With virtualenv installed, creating a new project environment is easy. From your terminal shell:
~$ mkdir ~/project ~/$ cd project ~/project$ virtualenv env ~/project$ source env/bin/activate (env):~/project$
From here you can use
setup.py to install the package and it will be restricted to the copy of python in the
env directory. You can leave the virtual environment by typing
deactivate in the terminal, and restart the environment with
pip install Chessnut
Upgrading to the latest version can be performed with the
pip install -U Chessnut
pip install git+https://github.com/cgearhart/Chessnut.git
If you prefer, you can install Chessnut manually with
setup.py. After downloading the source files to a local directory (and setting up a
virtualenv), switch into the project directory and run
python -m setup.py install
(Note: To install the package globally you may have to use the
As a Module
Finally, Chessnut is also a standalone module, so if you place the
Chessnut directory within your project folder, you don't need to install the package, you can just import the module as usual. (Using one of the package versions--particularly PIP--is still recommended as a way to create separation between your code and the Chessnut package, so that you don't have to worry about merging your changes into future upgrades of Chessnut.
from Chessnut import Game ... *<your code>*
Unit tests can be run with the
test.sh shell script which launches the
coverage.py framework as configured in
.coveragerc, or you can use the standard unittest framework via
python -m unittest discover. If you install the
pylint package, you can run the checker with default options using
pylint --ignore=tests Chessnut.
There are only two real classes in the Chessnut package:
Game. (There is also a namedtuple,
State, which creates a class, and another class,
InvalidMove--a subclass of
Exception, used to avoid generic try/except statements).
Board is only used internally by
Game to keep track of pieces and perform string formatting to and from FEN notation, so
Game should be the only class you need to import. After installing the Chessnut package, you can import and use it as you would expect:
from Chessnut import Game chessgame = Game() print chessgame # 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1' print chessgame.get_moves() """ ['a2a3', 'a2a4', 'b2b3', 'b2b4', 'c2c3', 'c2c4', 'd2d3', 'd2d4', 'e2e3', 'e2e4', 'f2f3', 'f2f4', 'g2g3', 'g2g4', 'h2h3', 'h2h4', 'b1c3', 'b1a3', 'g1h3', 'g1f3'] """ chessgame.apply_move('e2e4') # succeeds! print chessgame # 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1' chessgame.apply_move('e2e4') # fails! (raises InvalidMove exception)