Re: [Bug-gnubg] Documentation: Looking for documentation on python scripting

[Martin Micklinghoff]

Michael, I appreciate you help help a lot, I think I have enough information to get started, I will let you know if I get stuck.

For now though, thank you very much! - Martin

On Mon, Dec 30, 2013 at 11:37 PM, Michael Petch <address@hidden> wrote:

On 2013-12-30 13:28, Martin Micklinghoff wrote:
> Hi Michael,
>
> Thanks a lot for you help! I've followed the steps, got the latest
> version from cvs, and built from source. Also have ipython installed,
> and the ">" command takes me to an ipython shell. I'm curious where I
> can take it from here, as in 'where can I find a list of modules and
> methods', and 'how can uses methods from as python script as opposed to
> from a command line'?

Having you use the latest version and use ipython are your benefit as
much as it is mine. I am actually busy at the moment but at least want
to respond with some basics. At least this will get you started
(although) you will probably be left with more questions than answers.

First thing. GNUBG isn't imported into python like you are probably use
to. SO you might be thinking that somehow you can load python and do
something like:

import gnubg

Unfortunately this isn't the way GNUBG was designed. What you must do is
load GNUBG and access the internal version of embedded Python that GNUBG
exposes.

As you may have guessed that embedded Python is available at the command
line by using the greater than sign that I had you use to test earlier.

Okay, so how do you run a Python script and pass it to GNUBG. You can
run GNUBG with the -p option which allows you to specify a Python script
to run. Once the script is complete GNUBG will exit. As well when
working with Python for scripting it is often preferred to use the -t
option to force everything to the console. eg:

/path/to/gnubg -t -p testfile.py

This will launch GNUBG in command mode (no GUI) and run testfile.py and
then exit.

Now you know how to run a script.

So how does one interact with GNUBG then. What are the classes and
method available. Well there is a hidden object that is available when
your script is run (or when you are at the Python command prompt via the
> (greater than sign) command. The object you are interested in is
called 'gnubg'

So how can you find out more about the gnubg object. Load up gnubg a the
command line (gnubg -t) use the greater than sign > to get a python
prompt. You can then issue this command:

help(gnubg)

This will print out all the methods that are supported and their arguments.

You can get out of the Python command line and back to the GNUBG command
line by using control-D.

As you are probably already aware, most things you do in the gui have
corresponding text mode commands. If you launch GNUBG and type the
command in the terminal:

new match 7

This would start a new match.

So at the GNUBG command line you can find out all the commands that
GNUBG supports by typing:

help

For any command you can get further help b doing:

help commandname

so:

help new

would show you the new command. From there you could get help on the
match sub command via:

help new match

One thing you get use to when using GNUBG command line and the GUI at
the same time is the ability to see the commands as the GUI proceeds.
This gives you an idea of how GNUGB does things under the hood.

So why am I spending a reat deal of time about GNUBG's command line.
Because one of the fucntions available to you in Python is to execute an
arbitrary command as if it was typed on the GNUBG command line.

SO load GNUBG and type

>
        (now we are at Python prompt).
gnubg.command('new match 7')

You should see GNUBG start a new match. You cna query the current game
state by using this method:

gnubg.posinfo()

This will return a dictionary of the current player and whether they
have been doubled, what the dice are (if not doubled). Dice of (0,0) and
doubled = 0 means that the player is on roll and has to make a cube
action. To cube you can then send the 'double' command via:

gnubg.command('double')
gnubg.posinfo()

posinfo should now show you what roll you have (meaning) you are on
turn. How do you send a move from Python to GNUBG? Let us say posinfo
says you rolled a '31' you could send this command to mak that play:

gnubg.command('8/5 6/5')


GNUBG's command line takes moves like that to actually make a play. If
you play with the GUI launched from the console you can see all these
commands being execute while the GUI is playing (That is an invaluable
tool to get an idea of how things are done).

As well one other very valuable method is:

gnubg.match(analysis=0,boards=0,verbose=0)

Analysis, boards, and verbose can be set to 1 as well. The amount of
information returned can be a lot. with everything turned on. Part fo
the data structure (dictionary) is documented. You can see it via:

help(gnubg.match)

gnubg.match(...) is designed to return every game, every move (and cube)
and associated information.

If you undertsnad python and dictionaries (required knowledge) you could
in theory get the very last move/cube/resign made in a match via:

gnubg.match(analysis=0,boards=1)['games'][-1]['game'][-1]

Notice I'm not using the print command (nor assigning it to a variable).
if you don't specify either print or assignment ipython will pretty
print the dictionary that is generally more readable than had you issued:

print gnubg.match(analysis=0,boards=0,verbose=0)

I find this technique for understanding data structures I am not
familiar with.

There are some sample file that should be available in:

/usr/local/share/gnubg/scripts/

In particular matchseries.py may be useful to get an idea of things.
This was the very first Python program I ever played with (I wasn't a
Python developer at that time), and what got me started with Python
development in general.

help(gnubg) is your friend. Although the documentation in there isn't
complete you can often learn what is available.

I will stop things here. This email is meant as a starting point in your
learning

--
Michael Petch
CApp::Sysware Consulting Ltd.
OpenPGP FingerPrint=D81C 6A0D 987E 7DA5 3219 6715 466A 2ACE 5CAE 3304