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.