1.1.Concepts & Terminology¶

Using the Distutils is quite simple, both for module developers and forusers/administrators installing third-party modules. As a developer, yourresponsibilities (apart from writing solid, well-documented and well-testedcode, of course!) are:

• write a setup script (setup.py by convention)

• (optional) write a setup configuration file

• create a source distribution

• (optional) create one or more built (binary) distributions

Each of these tasks is covered in this document.

Not all module developers have access to a multitude of platforms, so it’s notalways feasible to expect them to create a multitude of built distributions. Itis hoped that a class of intermediaries, calledpackagers, will arise toaddress this need. Packagers will take source distributions released by moduledevelopers, build them on one or more platforms, and release the resulting builtdistributions. Thus, users on the most popular platforms will be able toinstall most popular Python module distributions in the most natural way fortheir platform, without having to run a single setup script or compile a line ofcode.

1.2.A Simple Example¶

The setup script is usually quite simple, although since it’s written in Python,there are no arbitrary limits to what you can do with it, though you should becareful about putting arbitrarily expensive operations in your setup script.Unlike, say, Autoconf-style configure scripts, the setup script may be runmultiple times in the course of building and installing your moduledistribution.

If all you want to do is distribute a module calledfoo, contained in afilefoo.py, then your setup script can be as simple as this:

fromdistutils.coreimportsetupsetup(name='foo',version='1.0',py_modules=['foo'],)

Some observations:

• most information that you supply to the Distutils is supplied as keywordarguments to thesetup() function

• those keyword arguments fall into two categories: package metadata (name,version number) and information about what’s in the package (a list of purePython modules, in this case)

• modules are specified by module name, not filename (the same will hold truefor packages and extensions)

• it’s recommended that you supply a little more metadata, in particular yourname, email address and a URL for the project (see sectionWriting the Setup Scriptfor an example)

To create a source distribution for this module, you would create a setupscript,setup.py, containing the above code, and run this command from aterminal:

pythonsetup.pysdist

For Windows, open a command prompt window (Start ‣Accessories) and change the command to:

setup.pysdist

sdist will create an archive file (e.g., tarball on Unix, ZIP file on Windows)containing your setup scriptsetup.py, and your modulefoo.py.The archive file will be namedfoo-1.0.tar.gz (or.zip), andwill unpack into a directoryfoo-1.0.

If an end-user wishes to install yourfoo module, all they have to do isdownloadfoo-1.0.tar.gz (or.zip), unpack it, and—from thefoo-1.0 directory—run

pythonsetup.pyinstall

which will ultimately copyfoo.py to the appropriate directory forthird-party modules in their Python installation.

This simple example demonstrates some fundamental concepts of the Distutils.First, both developers and installers have the same basic user interface, i.e.the setup script. The difference is which Distutilscommands they use: thesdist command is almost exclusively for module developers, whileinstall is more often for installers (although most developers willwant to install their own code occasionally).

Other useful built distribution formats are RPM, implemented by thebdist_rpm command, Solarispkgtool(bdist_pkgtool), and HP-UXswinstall(bdist_sdux). For example, the following command will create an RPMfile calledfoo-1.0.noarch.rpm:

pythonsetup.pybdist_rpm

(Thebdist_rpm command uses therpm executable, thereforethis has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, orMandrake Linux.)

You can find out what distribution formats are available at any time by running

pythonsetup.pybdist--help-formats

1.3.General Python terminology¶

If you’re reading this document, you probably have a good idea of what modules,extensions, and so forth are. Nevertheless, just to be sure that everyone isoperating from a common starting point, we offer the following glossary ofcommon Python terms:

module

the basic unit of code reusability in Python: a block of code imported by someother code. Three types of modules concern us here: pure Python modules,extension modules, and packages.

pure Python module

a module written in Python and contained in a single.py file (andpossibly associated.pyc files). Sometimes referred to as a“pure module.”

extension module

a module written in the low-level language of the Python implementation: C/C++for Python, Java for Jython. Typically contained in a single dynamicallyloadable pre-compiled file, e.g. a shared object (.so) file for Pythonextensions on Unix, a DLL (given the.pyd extension) for Pythonextensions on Windows, or a Java class file for Jython extensions. (Note thatcurrently, the Distutils only handles C/C++ extensions for Python.)

package

a module that contains other modules; typically contained in a directory in thefilesystem and distinguished from other directories by the presence of a file__init__.py.

root package

the root of the hierarchy of packages. (This isn’t really a package, since itdoesn’t have an__init__.py file. But we have to call it something.)The vast majority of the standard library is in the root package, as are manysmall, standalone third-party modules that don’t belong to a larger modulecollection. Unlike regular packages, modules in the root package can be found inmany directories: in fact, every directory listed insys.path contributesmodules to the root package.

1.4.Distutils-specific terminology¶

The following terms apply more specifically to the domain of distributing Pythonmodules using the Distutils:

module distribution

a collection of Python modules distributed together as a single downloadableresource and meant to be installeden masse. Examples of some well-knownmodule distributions are NumPy, SciPy, Pillow,or mxBase. (This would be called apackage, except that term isalready taken in the Python context: a single module distribution may containzero, one, or many Python packages.)

pure module distribution

a module distribution that contains only pure Python modules and packages.Sometimes referred to as a “pure distribution.”

non-pure module distribution

a module distribution that contains at least one extension module. Sometimesreferred to as a “non-pure distribution.”

distribution root

the top-level directory of your source tree (or source distribution); thedirectory wheresetup.py exists. Generallysetup.py will berun from this directory.