= Python-purple !HowTo =

== Introduction ==

'''Python-purple''' is a python bind for libpurple. It was written using [http://www.cython.org Cython] extension. As the Cython's website says: ''"Cython is a language that makes writing C extensions for the Python language as easy as Python itself. Cython is based on the well-known Pyrex, but supports more cutting edge functionality and optimizations."''.

'''Python-purple''' provides access to libpurple functions from python programs. You only need to import purple.so module (e.g. ''import purple'' from python shell) to start using python-purple. This HOWTO is not about modifying/extending python-purple bind itself, but how to write a python application using python-purple.

== Downloading python-purple ==

To download from GIT repository, issue the following command:

{{{
git clone https://vcs.maemo.org/git/python-purple
}}}

You will find python-purple source code inside ''python-purple/'' directory.

== Building and installing python-purple ==

In order to build python-purple, you need the following packages:

 * cdbs
 * debhelper
 * libpurple-dev
 * libglib2.0-dev
 * python2.5-dev
 * python2.5-distutils
 * cython (optional)

NOTE: Although it's not dependent, cython should also needed if you want to re-create purple.c file (generated from cython using ''purple.pyx'').

Building cython-generated ''purple.c'' file (optional):

{{{
$ cython purple.pyx -I libpurple/
}}}

This is also done by ''setup.py'' when running:

{{{
$ python2.5 setup.py build
}}}

If you don't need to generate ''purple.c'' file, you can use ''setup_dist.py'':

{{{
$ python2.5 setup_dist.py build
}}}

Both setups generates ''purple.so'' inside ''build/'' directory. The difference is that ''setup.py'' also generates ''purple.c'' file, if it doesn't exists.

To install files inside your system:

{{{
$ sudo python2.5 setup.py install --root=/usr
}}}

You can also create a debian package of it:

{{{
$ dpkg-buildpackage -rfakeroot
}}}

== Run python-purple module ==

To import ''purple'' module inside a python program, you need to call python interpreter and/or run the python script with '''LD_PRELOAD''' tag attached. For example:

{{{
$ LD_PRELOAD=/usr/lib/libpurple.so.0 python2.5 nullclient.py
}}}