Section 7.4. The Distribution Utilities (distutils)

7.4. The Distribution Utilities (distutils)

Python modules, extensions, and applications can be packaged and distributed in several forms:

Compressed archive files

Generally .zip for Windows and .tar.gz (a.k.a. .tgz) for Unix-based systems, but both forms are portable

Self-unpacking or self-installing executables

Normally .exe for Windows

Self-contained, ready-to-run executables that require no installation

For example, .exe for Windows, ZIP archives with a short script prefix on Unix, .app for the Mac, and so on

Platform-specific installers

For example, .msi on Windows, .rpm and .srpm on most Linux distributions, and .deb on Debian GNU/Linux and Ubuntu

Python Eggs

A very popular third-party extension, covered in "Python Eggs" on page 151

When you distribute a package as a self-installing executable or platform-specific installer, a user can then install the package simply by running the installer. How to run such an installer program depends on the platform, but it no longer matters which language the program was written in. How to build self-contained, ready-to run executables for various platforms is covered in Chapter 27.

When you distribute a package as an archive file or as an executable that unpacks but does not install itself, it does matter that the package was coded in Python. In this case, the user must first unpack the archive file into some appropriate directory, say C:\Temp\MyPack on a Windows machine or ~/MyPack on a Unix-like machine. Among the extracted files there should be a script, conventionally named setup.py, which uses the Python facility known as the distribution utilities (standard library package distutils). The distributed package is then almost as easy to install as a self-installing executable would be. The user opens a command-prompt window and changes to the directory into which the archive is unpacked. Then the user runs, for example:

 C:\Temp\MyPack> python setup.py install 

The setup.py script, run with this install command, installs the package as a part of the user's Python installation, according to the options specified in the setup script by the package's author (of course, the user needs appropriate permissions to write into the directories of the Python installations, so permission-raising commands such as su or sudo may be needed). distutils, by default, provides tracing information when the user runs setup.py. Option --quiet, placed right before the install command, hides most details (the user still sees error messages, if any). The following command gives detailed help on distutils:

 C:\> python setup.py --help 

When you are installing a package prepared with distutils, you can, if you wish, exert detailed control over how distutils performs installations. You can record installation options in a text file with extension .cfg, called a config file, so that distutils applies your favorite installation options by default. Such customization can be done on a system-wide basis for a single user, or even for a single package installation. For example, if you want an installation with minimal amounts of output to be your system-wide default, create the following text file named pydistutils.cfg:

  [global] quiet=1 

Put this file in the same directory in which the distutils package resides. On a typical Python 2.4 installation on Windows, for example, the file is C:\Python24\Lib\distutils\pydistutils.cfg. "Python's distutils" on page 666 provides more information on using distutils to prepare modules, packages, extensions, and applications for distribution.

7.4.1. Python Eggs

A new emerging standard for distributing Python packages is Python Eggs, ZIP files that optionally include structured metadata as well as Python code, and sporting a file extension of .egg. Among the many endearing characteristics of Eggs is the fact that sufficiently simple Eggs need no real "installation" procedure: just place an .egg file anywhere along your Python sys.path, and your Python code can immediately start using that package. Despite this simplicity, the fact that Eggs can contain rich metadata also offers many other exciting possibilities.

Unfortunately, Eggs have not made it into the Python 2.5 release, for reasons of mere timing (Eggs were still under development at the time of the cut-off date for new features to be accepted into Python 2.5). Nevertheless, you can use Eggs with all Python releases from 2.3 onward by downloading and running a single Python script from http://peak.telecommunity.com/DevCenter/EasyInstall. I highly recommend Eggs as an excellent way to distribute your Python packages; besides their other advantages, Eggs also come with a package of powerful tools for setup and installations, setuptools, to complement distutils, covered in "Python's distutils" on page 666. Read all about Eggs and setuptools at http://peak.telecommunity.com/DevCenter/PythonEggs.