This document contains information for building Python modules, eggs and other distributable packages using the built in setuptools and distutils frameworks.
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.
To build a module you simply run the command:
python setup.py build
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.
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:
python setup.py bdist_egg
The script will generate a ’dist’ directory that contains your python egg.
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.
sudo python setup.py install
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:
sudo python uninstall.py
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:
python setup.py register
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.
To push the latest version of your Python module to PyPi, you simple run this command:
python setup.py release
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).