Distributing Python Modules

Previous: 2 Concepts & Terminology Up: 2 Concepts & Terminology Next: 2.2 General Python terminology

---

2.1 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.¹ If all you want to do is distribute a module called foo, contained in a file foo.py, then your setup script can be as little as this:

from distutils.core import setup
setup (name = "foo",
       version = "1.0",
       py_modules = ["foo"])

Some observations:

• most information that you supply to the Distutils is supplied as keyword arguments to the setup() function
• those keyword arguments fall into two categories: package meta-data (name, version number) and information about what's in the package (a list of pure Python modules, in this case)
• modules are specified by module name, not filename (the same will hold true for packages and extensions)
• it's recommended that you supply a little more meta-data, in particular your name, email address and a URL for the project (see section  for an example)

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

python setup.py sdist

If an end-user wishes to install your foo module, all she has to do is download Foo-1.0.tar.gz (or .zip), unpack it, and--from the Foo-1.0 directory--run

python setup.py install

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 Distutils commands they use: the sdist command is almost exclusively for module developers, while install is more often for installers (although most developers will want to install their own code occasionally).

If you want to make things really easy for your users, you can create one or more built distributions for them. For instance, if you are running on a Windows machine, and want to make things easy for other Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the bdist_wininst command. For example:

python setup.py bdist_wininst

** not implemented yet ** (Another way to create executable installers for Windows is with the bdist_wise command, which uses Wise--the commercial installer-generator used to create Python's own installer--to create the installer. Wise-based installers are more appropriate for large, industrial-strength applications that need the full capabilities of a ``real'' installer. bdist_wininst creates a self-extracting zip file with a minimal user interface, which is enough for small- to medium-sized module collections. You'll need to have version XXX of Wise installed on your system for the bdist_wise command to work; it's available from http://foo/bar/baz.)

Currently (Distutils 0.9.2), the are only other useful built distribution format is RPM, implemented by the bdist_rpm command. For example, the following command will create an RPM file called Foo-1.0.noarch.rpm:

python setup.py bdist_rpm

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

python setup.py bdist --help-formats

Footnotes

... it.¹

But be careful about putting arbitrarily expensive operations in your setup script; unlike, say, Autoconf-style configure scripts, the setup script may be run multiple times in the course of building and installing your module distribution. If you need to insert potentially expensive processing steps into the Distutils chain, see section  on extending the Distutils.

---

Distributing Python Modules

Previous: 2 Concepts & Terminology Up: 2 Concepts & Terminology Next: 2.2 General Python terminology