Feature request: docstrings for public members of Position class

[pitchforks]

Typical workflow of a starter:

• download the source code
• build from source
• install
• proceed to studying the API

That's pretty much what I did, then I fired IPython for the last step. But when I do

import chess
pos = chess.Position()
pos.PRETTY_MUCH_ANYTHING??

I see this:

Docstring:  <no docstring>

Next thing I did was to try reading the source code and realized it's C++. I understand this was done for performance reasons, yet for someone who doesn't know any C++ past 'hello world' this is a total show stopper :(

[niklasf]

Yeah, I am not really happy with that.

• There should be more documentation. Does the README help a little? Is there something specific I can help you with?
• I am considering to try to rewrite it in pure python, which would be more portable (in a way) and easier to install, hack and use. In fact this was a pure python project, originally, but awfully slow. The problem was that I didn't really want to accept any "hacks" for performance. It should be possible to create a pure python version that is relatively fast and still has a clean API.

[pitchforks]

Does the README help a little?

Of course it does, but this is just a first short introduction. To learn the full potential of the API, one still has to dive into the docs (or at least read the docstrings in the source code).

Is there something specific I can help you with?

Perhaps you should know what am I expecting from a python chess library.

Anything you can do with a real wooden chess board: put pieces on it, one by one (this means the starting position as well as any other), be able to move them, move validation checks.

A virtual chess board would also have some additional features:

• report the current position as FEN string. This is Position.fen, according to the README
• report the current position as "human visible" board, think of something like Position.get_board() that will return something like https://gist.github.com/pitchforks/10953810 . This is the reason I tried to look closer at the API and realized there are no docstrings.
• be able to load a whole position at once, from a FEN string, README documents this as well
• save the history of moves to provide back/forward functionality. I couldn't find this
• provide a list of possible moves in a position. This is Position.get_legal_moves() and it makes this library particularly appealing for a reason that I'm going to mention below

Fixing the build was a good first step. Adding some docstrings would be a good next step. Doing this will certainly help even if you decide to rewrite the whole thing in pure Python later. And will prevent future complaints about lack of them from people like me :-)

A couple of years ago I have found http://arainyday.se/projects/python/ChessBoard/ and played a bit with it, but ultimately had to give up, because:

• it looked like being abandoned by its author (and still looks abandoned to this day)
• it had bugs
• it had no tests at all, which made it absolutely impossible to attempt modifying the source code
• it lacked what's named Position.get_legal_moves() in python-chess

There seems to be a big gap in the python world when it comes to chess, perhaps python-chess could fix it by providing a feature rich virtual chess board with an user friendly well documented API.

[niklasf]

In the last weeks I made a lot of progress with the pure Python rewrite and documentation. Except from the human readable board notation pretty much everything is included.

As always, the documentation could be more thourough, though.

Careful when updating: At this stage it is more important to me to get things right, so I completely ignored backwards compability and broke it all over.

[niklasf]

The latest version also features some basic ASCII printing, which makes debugging a bit easier.

>>> board = chess.Bitboard()
>>> board
Bitboard('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1')
>>> print board
r n b q k b n r
p p p p p p p p
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
P P P P P P P P
R N B Q K B N R

>>> board.attackers(chess.WHITE, chess.F3)
SquareSet(0b101000001000000)
>>> print board.attackers(chess.WHITE, chess.F3)
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . 1 . 1 .
. . . . . . 1 .