GENESIS: Documentation

Related Documentation:

Python Packaging

This document contains information for building Python modules, eggs and other distributable packages using the built in setuptools and distutils frameworks.

Setup script

Each GENESIS3 component with a Python interface has a setup.py script in the glue/swig/python directory. The script is responsible for compiling the python source into a module, generating Python eggs, installing compiled modules, and registering and pushing eggs to PyPi.

Building a module

To build a module you simply run the command:

The result of running this command will generate a ’build’ directory that contains a ’lib’ directory, which contains the importable module. And directory that contains any executable scripts. On some systems it may also contain a directory that has any pre-build data. After building the module you can import from build/lib so long as you add the path vis the sys.path variable.

Creating a python egg

The previous build command will just create a directory with all code that is to be compiled and packaged. An egg is a zipped version of this directory for ease of installation and distribution. To build a Python egg run the command:

The script will generate a ’dist’ directory that contains your python egg.

Installing a module

Installing a build module is as simple as using the ’install’ argument with your setup script. To install the module to python’s system path you will need to use sudo for admin privileges.

Uninstalling a module

There is no built in uninstall for packages built and installed with setuptools or distutils. To handle this each python package has a script named uninstall.py. This script will delete the specified Python egg, any info metadata that it installs, and references to the egg in the Python .pth file. Calling the uninstall script must be done with admin privileges:

Registering on PyPi

If you filled out all sections if you setup.py call correctly, and there are no naming conflicts with packages already present on PyPi, you can easily register your package by calling setup.py with the register argument:

It will prompt for a username and password to PyPi. To have this automatically login to PyPi, you need to create a .pypirc file in your home directory. The contents of a pypirc file consists of blocks of information with credentials, similar to mercurial .hgrc files:

where myusername is your username login into PyPi, and mypasswd is your user password. The distutils block is needed if you intend to keep compatability with distutils for packaging.

Pushing an egg to PyPi

To push the latest version of your Python module to PyPi, you simple run this command:

If you have a .pypirc file with valid credentials it will automatically log you in, otherwise, it prompts for a username and password. This will check the version number of the module present on PyPi (if any) and compare it with the recent one. If the newest version has a newer version number, then it pushes the egg so that it can be downloaded using easy_install. Otherwise it will protest and ask you to enter in a valid version number (one that is higher than the one detected).