setuphelper 0.5.1

A helper module for setup.py scripts.

This Python module will make your setup scripts simpler to write, by automating as much as possible of the ‘boilerplate’ that normally goes into them. Instead of invoking the setup function with a long list of keyword arguments, you just set global variables in your setup script and then invoke the setup_main function, passing globals() as its argument. (The SetupHelper setup.py script itself illustrates this usage.)

The helper module does all the grunt work of translating your variables into keyword arguments, including automatically deducing and generating many arguments so that you only have to specify a much simpler set of data. As a bonus, if you are using Python’s standard distutils, SetupHelper provides (very basic!) support for the requires keyword, downloading and installing required packages for you, as long as their download URLs are available on PyPI. (You can also specify a local directory as a “repository” by setting the environment variable PYPI_LOCAL to point to it–see the CHANGES file in the source archive for details.) This functionality currently does not support version specifiers after the package name (unless you are using setuptools, which does allow this–see below).

(Note that the Python 2.5 and later distutils package allows the requires keyword in distribution metadata, but does not actually use it to install anything for you. Of course some distutils replacements like setuptools do provide this functionality; if you are using setuptools, you can set the variable __distutils_pkg__ to 'setuptools' and SetupHelper will use setuptools’ support instead of its own, which has some additional features, such as allowing version specifiers for required packages. SetupHelper also adds the requires, provides, and obsoletes keywords to your package metadata when you use the setup.py register command with Python versions < 2.5; in other words, it gives you support for metadata version 1.1 even if your Python version doesn’t.)

Since SetupHelper has all the information needed to determine what should be in your source or binary distribution files, it auto-generates MANIFEST.in each time it runs, so you don’t have to maintain your MANIFEST.in file manually (and if you did, it would get overwritten anyway). Even though it is not strictly necessary to write MANIFEST.in unless you are running a distribution command, SetupHelper does it every time because checking its output can often help you debug problems with the variable definitions in your setup script. (At least, it has certainly helped me to do that!)

Using SetupHelper as an Installer

This distribution includes a script, setuphelper, that you can use to leverage SetupHelper’s requires keyword support to use it as an installer. Command line arguments to the script are treated as a list of requirements to be installed, and the script uses SetupHelper to download and install them, just as if they were listed in a setup.py script. If you want to use setuptools’ easy_install support with this technique, use the command line option --use-setuptools (short form -s).

Since this script uses the requires keyword functionality in SetupHelper, it has the limitation noted above, that no version specifiers can currently be used after package names.

Post-Install Script Support

As one other bonus, SetupHelper allows you to automate the running of post-install scripts; just set the __post_install__ variable in your setup.py to a list of script names to be run from a subshell (this is done using os.system, so it has the limitations of that Python command). It is desirable to allow post-install scripts to be run from setup.py so that SetupHelper can ensure that any required packages are fully installed by just calling python setup.py install on them once they are unpacked. (Note that, if you are using setuptools, this feature does not work, as setuptools does not actually run python setup.py install to install your package. A future version of SetupHelper might lift this constraint.)

Note that SetupHelper patches the install_scripts command in distutils to capture the correct script installation directory. This ensures that the correct version of your post-install scripts (i.e., the one that just got installed) runs even if there are multiple copies on your path.

Installation

Of course, to install SetupHelper, you can simply type:

$ python setup.py install

in the directory where you unpacked the SetupHelper archive. However, since SetupHelper is used by setup scripts, you will probably want to include it along with your setup.py in the source archives for your Python projects as well as having it installed on your own system.