Setuptools and the single file

by Paul Agapow
in programming

Setuptools and the single file

Problems with making an installer for a simple module

Although setuptools is a complex thing, and there has has been widespread complaints about its architecture, for the most part, I've had few problems with it. However, I recently encountered a crusty and under-documented corner of it.

The problem

rst2beamer is a Python module for translating restructured text to the Beamer LaTeX dialect for presentations. The module is fairly simple and consists of a single file of Python (i.e. a one file module), rst2beamer.py. The job of the installer is therefore to copy this file to the local site-packages and create a script that calls the writer defined in this file.

When the normal layout for a setuptools-enabled setup.py installer is used, it generates distributions (source and egg) seemingly without any problems, and these distributions install (via setup.py or easy_install) also without any apparent problems. But while it appears that the distribution is installed, trying to import it or use the generated script to call it results in an import error.

The diagnosis

The non-functional rst2beamer sat on PyPi for months before someone informed me it wasn't working. (Are the expectations for open-source software that bad?) On studying the distribution it became clear that setuptools wasn't recognizing rst2beamer.py as something to install. In fact, the distributions are created without the actual source file. Altering the manifest file and using various other methods to get the source included in the distribution still resulted in non-functional distributions.

The solution

We have to revert to an older way of installing software. While the setup.py file used to say:

setup( name='rst2beamer', version=__version__, # ... packages=find_packages(exclude=['ez_setup', 'examples', 'tests']), include_package_data=True, # ... )

setuptools doesn't see rst2beamer as a package or installable. So it needs to be changed to read:

setup( name='rst2beamer', version=__version__, # ... py_modules=['rst2beamer'], # ... )

i.e. pass the single file module names to py_modules. Note that the .py is not used.

It's a surprising hole in setuptools documentation - there's an implicit assumption that everything you install will be a package, i.e. at least a folder. Perhaps it was felt there was no need to document features carried over from disutils.

Thanks

Thanks to James Heggarty for reporting the problem and helping diagnose it.