Extending Python using Python scripts

The simplest way to extend Python is to write modules which can be imported into python in the standard way. Fortunately, Python's interactivity and elegance make this an undaunting task. Refer to the LEARN menu.

User's own modules (.py scripts) are kept separate from Framework and multi-user code, normally in the user's home directory or some subdirectory of it. One of the most common problems people initially encounter with Python is this error message:

>>> import myModule
Traceback (most recent call last):
File "", line 1, in ?
ImportError: No module named myModule


The occurs when python can't find the file myModule.py.

[Aside: If you're unsure about the way the Python interpreter is extended using scripts and modules, read the Module section of the Python Tutorial, available on line at http://www.python.org/doc/2.4.1/tut/node8.html].

Whilst the simple solution to the above error is to run Python from the directory in which myModule.py resides, this becomes unwieldy when you want to put all the files of a project in a project directory or you want to extend the SoniPy framework. This is done by creating 'environment variables' that Python can use as a search path when looking for modules. The way these environment variables are implemented depends on different platforms and how they are configured. Look at the ENVARS menu above, for an outline.

Although Python comes with an extensive standard library and there are many third-party modules available, we are not limited to using just Python modules. A powerful feature of Python is its well-defined interface to other languages. Libraries written in most languages can be integrated through Python by 'extending' it.

The basic principle of SoniPy is to use Python as an encapsulating mechanism which can 'wrap' independent software that can be compiled with python bindings, in such a way that data can flow between them. This means that code already written in other languages can be compiled into an executable library with Python bindings and thus made useful in a sonification environment without the need for re-writing. Another advantage of this approach is that computationally demanding applications (or parts thereof) can be written in a (faster) compiling language, such as C++, in much the same way as assembler-language functions were used in a previous generation. In fact, many native Python modules (transparently) exist in this form.

NB 'Extending' is not 'Embedding'

'Extending' should not be confused with a different process, called 'embedding', in which Python is included in an application by its developers to provide it with an Application Program Interface (API) or by invoking the Python interpreter installed on the user's system as a basic API. We mention embedding in this context because, whilst it may be useful in its own right, it does not provide the interface flexibility needed by SoniPy.

A more technical description is here: http://www.python.org/doc/2.4.1/ext/ext.html

Tools for building Python library interfaces: SWIG

SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. SWIG is used with different types of languages including common scripting languages such as Perl, PHP, Python, Tcl, Ruby and PHP.

SWIG is an interface compiler that connects programs written in C and C++ with scripting languages such as Perl, Python, Ruby, and Tcl. It works by taking the declarations found in C/C++ header files and using them to generate the wrapper code that scripting languages need to access the underlying C/C++ code. In addition, SWIG provides a variety of customization features that let you tailor the wrapping process to suit your application.

SWIG is an essential tool if you plan to build SoniPy modules yourself. Installers are available for a variety of hardware platforms from http://sourceforge.net/project/showfiles.php?group_id=1645

The latest version of SWIG is available via CVS.

Intel Mac OSX users: At the time of writing there was no universal or Intel build available from the latest version (swig-1.3.11) from the above website (only for PPC). You'll need to build it from sources.

1. Dependency: GNU `make'. It should be part of the default tools. To check, type
   % which make
   at the unix prompt. If you need it, you can get it from http://www.gnu.org/software/make/
2. Downlood swig-1.3.11.tar.gz. Its labeled as "Platform-Independent".
3. Gunzip it and then untar in into /usr/local/ : $ tar -xf swig*.tar /usr/local/
4. Build and install: % cd /usr/local/swig*
% ./configure
% make
% make install


By default SWIG installs itself in /usr/local. If you need to install SWIG in a different location, see INSTALL file that accompanies the sources, which also advises that

... configure script will attempt to locate various packages on your machine, including Tcl, Perl5, Python and all the other target languages that SWIG uses. Don't panic if you get 'not found' messages--SWIG does not need these packages to compile or run. The configure script is actually looking for these packages so that you can try out the SWIG examples contained in the 'Examples' directory without having to hack Makefiles.

Tools for compiling libraries: SCons

SCons is an Open Source software construction tool. It is an improved, cross-platform substitute for the classic Make utility with integrated functionality similar to autoconf/automake and compiler caches such as ccache. Configuration files are Python scripts. It provides an automatic dependency analysis built-in for C, C++ and Fortran source code, thus dispensing with the need for "make depend" or "make clean" to get all of the dependencies. Dependency analysis is easily extensible through user-defined dependency Scanners for other languages or file types. SCons is written in python so it is available for all major hardware platforms.

Mac OSX and other *nix users: Running SCons requires Python version 1.5.2 or later. No source-code compilation is required There should be no other dependencies or requirements to run SCons. However it needs to be installed:

1. Download the latest gzipped tarball(.gz) file from http://www.scons.org/ .
2. Gunzip it and then untar in into /usr/local/ : % tar -xf scons*.tar /usr/local/
3. Change directory to the newly created scons directory: % cd /usr/local/scons*/
4. Install it: % python setup.py install

If you're interested in where SCons is installed, see the Macintosh OSX: Installing Extension Modules section under the INSTALL menu.