USING THE PYTHON WRAPPER FOR ARIA
---------------------------------
A "wrapper" library for Python has been provided in the "python" directory.
This wrapper layer provides a Python API which simply makes calls into the
regular Aria C++ library (libAria.so/AriaVC10.dll). In general, the Python API
mirrors the C++ API.
The Aria Python wrapper currently requires Python version 2.4.4 if on Debian 3 or Windows,
Python 2.5 if on Debian 5, or Python 2.7 if on Ubuntu 12. Multiple versions of
Python may be installed on Debian Linux; if so, commands are provided such as
'python2.4' or 'python2.5' or 'python2' to invoke the different versions of
Python.
NOTE: You should use the versions of Python mentioned above, since the wrapper
library code is generally 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.4 from:
http://www.python.org/download/releases/2.4.4
(Python 2.2 is also at python.org.)
On Debian, you can install Python 2.5 by entering the following command
when connected to the Internet:
sudo apt-get install python
Or, you can download Python 2.5.5 from:
http://www.python.org/download/releases/2.5.5
On Ubuntu, you can install Python 2.7 with the following command:
sudo apt-get install python2.7
(NOTE if using Python 2.6 or later: Python 2.6 requires native C++ DLLs to be
named with a ".pyd" file extension, rather than .dll/.so as was
allowed in previous versions. So if Python 2.6 is unable to import the
AriaPy DLL module, rename _AriaPy.dll or _AriaPy.so to _AriaPy.pyd
in the python/ subdirectory.)
Documentation about the Python language and libraries is at:
http://docs.python.org
To use the wrapper library you must create an environment variable called PYTHONPATH
that has the full path to Aria's 'python' directory in it.
On Linux, set it to:
/usr/local/Aria/python
On Windows, set it to:
C:\Program Files\MobileRobots\Aria\python
Environment variables are set in Windows in the Advanced tab of the System control panel.
For an example you can start the simulator, then enter
the pythonExamples directory and run:
python simple.py
On Windows, you can just double-click simple.py.
NOTE: The Python wrapper API is not as well tested as Aria 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 next section).
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 in the wrapper are not direct subclasses of the C++ classes,
they are only subclasses of the Python wrapper classes, which implement the logic
to redirect calls between the C++ and wrapper classes. 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. We have done this for a few
cases (such as ArAction::setRobot()), but If this ever becomes neccesary
for any others, please let us know and we will add the extension.
2. Swig currently does not make protected 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 (use version 1.3.29 or newer.)
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 or /usr/include/python2.7
for Python 2.7. 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 Aria directory, and again run 'make python' in
the ArNetworking subdirectory if you also want the wrapper library for
ArNetworking. On Windows, open the AriaPy-vc2010.sln file in the 'python'
directory with Visual Studio 2010 and build AriaPy and, if desired,
ArNetworkingPy in Release configuration. The native ARIAlibrary may be
automatically rebuilt if neccesary.
