


USING THE PYTHON WRAPPER FOR ARNL
---------------------------------

"Wrapper" libraries for Python have been provided in the "python" directory.
This wrapper layer provides Python modules which simply make calls into the 
regular C++ implementations of ARIA, ArNetworking, ARNL, etc.
In general, the Python API mirrors the C++ API. See the C++ API reference
for exceptions.

The Python wrapper currently requires Python version 2.4.4 if on Debian or Windows,
or Python 2.2 if on RedHat 7.3. In Linux it may be called 'python2' or 'python2.4' 
(or python2.2 in the case of RedHat 7.3) by your distribution (you can make an alias of 
python to python2 in your .bashrc).  

	NOTE: You *must* use these versions of Python, since the wrapper 
	library code is only compatible with the runtime libraries provided 
	by these versions.  To use a different version of Python, you must 
	rebuild the wrapper library (see below).

You can download Python 2.4 from:
    http://www.python.org/download/releases/2.4.4

(Python 2.2 is also at python.org.)

Documentation about the Python language and libraries is at:
    http://docs.python.org

After installing, You then need to create an environment variable called PYTHONPATH 
that has the full path to the Aria and Arnl 'python' directories in it. 

On Linux, set it to:
	/usr/local/Arnl/python:/usr/local/Aria/python

On Windows, set it to:
	C:\Program Files\MobileRobots\Arnl\python;C:\Program Files\MobileRobots\Aria\python

Environment variables are set in Windows in the Advanced tab of the System control panel.

The ArnlBase Python wrapper is in ArnlBasePy.py (ArnlBasePy module), which uses
_ArnlBasePy.so or _ArnlBasePy.dll to make calls into the native library. The ARNL
wrapper is in ArnlPy.py (ArnlPy module), with _ArnlPy.so or _ArnlPy.dll. 
The SONARNL wrapper is SonArnlPy.py (SonArnlPy module) with _SonArnlPy.so
or _SonArnlPy.dll.  The MOGS wrapper is MogsPy.py (MogsPy module) with
_MogsPy.so or _MogsPy.dll. 


	NOTE: The Python wrapper API is not as well tested as ARNL itself. If
	you encounter problems, please notify the aria-users mailing list. Furthermore,
	some methods have been omitted or renamed, and you have to do a few things
	differently (see later sections).

EXAMPLES
--------

For an example you can start the simulator, then enter 
the pythonExamples directory and run:

    python arnlServer.py

Or sonarnlServer.py. On Windows, you can also just double-click arnlServer.py or
sonarnlServer.py.

ARNL includes the arnlServer.py example program in the pythonExamples directory.
SONARNL includes the arnlServer.py example program in the pythonExamples directory.

There are no Python examples distributed with ArnlBase at this time.



USING ACTIONS IN PYTHON
-----------------------

Writing classes in Python that subclass classes from Aria is not as
straightforward as making subclasses of native Python classes.  Subclasses
of classes from the C++ library are in fact more loosely coupled. The practical
consequences of this include the following:

1. You cannot call a virtual method in the parent class which the subclass
   overrides -- it will always be directed to the subclass's implementation.
   For example, you can override ArAction::setRobot(), which is a virtual
   method. But then, any call to setRobot() on the subclass will always 
   be directed to the subclass's implementation; calling
   self.ArAction.setRobot() from you subclass's setRobot() override would
   result in an infinite recursion, so Swig throws an exception instead.
   There is no workaround for this other than extending each parent class 
   in wrapper.i ad-hoc to include an additional method with a new name to 
   invoke the method defined in the parent. If this ever becomes neccesary
   for a particular situation, please let us know and we will add the extension.

2. Swig currently does not make protected virtual methods available to
   subclasses, though this may be fixed in the future.


OTHER DIFFERENCES
-----------------

See the C++ API docs for various classes for notes about how they might be
used differently in Python. For example, ArConfigArg and ArFunctor are used
slightly differently (since those classes use features unique to C++).



REBUILDING THE PYTHON WRAPPER
-----------------------------

You must rebuild the Python wrapper if you make any interface changes to
ARIA and want them to be available in Python.  You may also need to rebuild
the wrapper if you want to use another version of Python (as distributed, the
wrapper libraries were built with and linked against the 2.4 Python runtime library
on Debian Linux and Windows, and 2.2 on RedHat 7).

If you want to rebuild the Python wrapper you need to install SWIG, you
can get it from http://www.swig.org/download.html (the most recent version
is recommended).  You'll also need Python, which you can get from 
http://www.python.org. 

On Linux, you may also need to install a Python "Development" package in addition
to the main Python runtime package.  e.g. on Debian, install python2.4-dev. On 
Windows, if the python24_d.lib library is missing, you can download the
Python 2.4 source code and compile the "python" project in the PCbuild subdirectory.

Set the environment variable PYTHON_INCLUDE to the full path of Python's
include directory.  On Linux, this is usually /usr/include/python2.4 for 
Python 2.4 or /usr/include/python2.2 for Python 2.2.  On Windows, it depends
on where you installed Python but a typical value is C:\Python24\include for
Ptyhon 2.4).  

On Windows you'll also need to set the environment variables
PYTHON_LIB to the full path of the Python library and PYTHON_LIBDIR to the directory
containing all the Python libs.  These depend on where
you installed Python, but a typical value would be "C:\Python24\libs\python24.lib" for
PYTHON_LIB and "C:\Python24\libs" for PYTHON_LIBDIR for Python 2.4.
Set environment variables in the Advanced section of the System control panel.

On Linux Run 'make python' in the Arnl directory.
On Windows, open the ArnlPy.sln file in the 'python'
directory and build ArnlPy and, if desired, ArNetworkingPy.  


