Using setuptools in IPython

Setuptools is a system that tries to address some of the limitations of distutils. Below we list a few basic guidelines for how to best use setuptools in IPython development. These are different from the standard setuptools documentation, partly because past experience has shown us that some of it suggests an over-enthusiastic use of things that can break in all sorts of ways. So here we list what we consider to be a good, conservative compromise to provide setuptools support, while keeping a system that is safe and robust.

In particular, we want to pay special attention to the fact that users who simply want to type

$ python setup.py install

using plain distutils should get correct behavior, even if:

• They have setuptools installed on their system (maybe as part of a system-wide installation they do not control).

• setuptools is somehow broken (so that bugs in setuptools, which I've seen a fair share of, have absolutely zero impact on IPython users who do not wish to use setuptools).

The basic guidelines are:

• Avoid ez_setup like the plague. ez_setup is a self-bootstrapping script which, from past experience, causes far more problems than it solves. Its use is absolutely forbidden in IPython, at least until a lot of experience shows that all of its problems have truly been fixed. I don't have time to engage in such exercise, so the burden of proof will rest on someone else if they ever want this.

• Make sure that the regular setup.py script can build a good egg. Otherwise, easy_install cannot build an egg from the source tarball or SVN checkout.

• If you are using setuptools features heavily, and the package is using pkg_resources and egg-based plugin discovery, go whole hog and write your setup.py using setuptools from the ground up. E.g. TurboGears simply can't be built without setuptools; it's integral to how TurboGears works.

• If you just want to be able to build a nice egg from your package which does not otherwise use setuptools, use the ('setuptools' in sys.modules) test to make sure setuptools does not get used unless the builder actually uses setuptools to build/install the package.

In current IPython trunk, eggsetup.py is the way to run setup.py with setuptools imported. Do

$ python eggsetup.py bdist_egg

to build an egg, 'install' to install the egg directly etc.