[Freeciv-Dev] [RFC] Embedding Python

[Lino Mastrodomenico <mastro@xxxxxxxxxx>]

Hi all.

I have attached 2 work-in-progress patches for embedding python in the 
server, if you are impatient please see this screenshot:

  http://www.mastrodomenico.f2s.com/freeciv/temp/python1.png


The first patch (embed_python.diff) simply embed the python, without doing 
anything else.
The second (python_callbacks.diff) creates a new server variable, "script", 
that specify a server script to load (please see data/script/default.py for 
an example).

This script can be used for writing:
  * dynamic scenarios (it would be nice to offer all the capabilities of civ2 
    script language (for a detailed description see:
    <http://apolyton.net/forums/showthread.php?s=&threadid=17520>), so we can
    eventually write an utility for automatic importing civ2 scenarios);
  * user AIs;
  * user agents;
  * server gui (?);
  * cheats...
(well... at least in the future: for now it can only spam messages using the 
wall function)

If we embed python in the client, it should be possible to allow AIs and 
agent scripts to run both server-side and client-side, by using a construct 
like:

  try:
      from civserver import game
      wow_now_i_can_cheat = 1
  except ImportError:
      from civclient import game
      wow_now_i_can_cheat = 0


After applying both patches you should run:

  automake && autoheader && autoconf && ./configure --with-python

You need both python and python-devel packages.
Technically it should work with python 1.5.2+ (tested with 1.5.2, 2.0 and 
2.2a2), but if we want distribute a _precompiled_ executable we must use a 
version with a GPL-compatible license (2.0.1, 2.1.1 or 2.2).


Technical details:

  * all the interactions between the server and the script take place through 
    the "civserver.game" python object (from the python side) and through the 
    script.c file (from the c side);

  * the game object contains (for now...):
      - data attributes:
          * is_new_game
          * year
          * turn
        (they came from "struct civ_game game"; to add new attributes simply  
        copy them from game.h to data/script/civserver.i and rerun swig)

      - methods:
          * wall(string)
            (it works like the server wall command)

      - callback handlers lists (use X.append(my_func) to add a new callback  
        and X.remove(my_func) to remove it):
          * begin_turn
          * start_game

  * I have used swig 1.3a5; the generated files are included in the patch, so 
    you need swig only if you modify civserver.i (more than half of the
    second patch size is automatically generated);

  * I think is a bit stupid inserting a copyright like "(C) 1996 - A
    Kjeldberg, L Gregersen, P Unold" in a code written in 2001, so I have
    used "(C) 2001 - Lino Mastrodomenico" in the new files that I have
    created. If this is a problem I can e.g. assign the copyright to the
    maintainers.

  * The script.c interface is high-level and not python-specific, so we can
    later embed other languages (guile, perl, tcl, ruby...).


And now some very nice ascii art:

*  ================C================   ============Python=============
*   ___________    ________________     ______________     __________
*  /           \  /                \   /              \   /          \
*  |           |--|    script.c    |---|              |   |   user   |
*  |           |  \________________/   | civserver.py |---|  script  |
*  |  Freeciv  |    |   _____|_____    |              |   |          |
*  |           |    |  /           \   \______________/   | (AI,     |
*  |  server   |    |  | libpython |          |           | dynamic  |
*  |           |    |  \___________/          |           | scenario |
*  |  classic  |   _|________|_____     ______|________   | ...)     |
*  |           |  /                \   /               \  \__________/
*  |           |__| swig_wrapper.c |___| _civserver.py |
*  |           |  |   (by swig)    |   |   (by swig)   |
*  \___________/  \________________/   \_______________/


I hope this isn't too confusing ;-) (however the code should be simple to 
understand).


Of course these patches are not ready for cvs inclusion: this it's a 
proof-of-concept/work-in-progress and I now need some feedback.

Comments? Suggestions? Flames? ;-)

ciao

-- 
Lino Mastrodomenico
E-mail: mastro@xxxxxxxxxx

python-v1.tar.gz
Description: GNU Zip compressed data