|
|
|
Distributing Python Modules |
|
|
|
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 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 all you want to do is distribute a module called foo,
contained in a file foo.py, then your setup script can be as
simple 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
metadata (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 metadata, in
particular your name, email address and a URL for the project
(see section 2 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:
which will create an archive file (e.g., tarball on Unix, ZIP file on
Windows) containing your setup script setup.py, and your module
foo.py. The archive file will be named foo-1.0.tar.gz (or
.zip), and will unpack into a directory foo-1.0.
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
which will ultimately copy foo.py to the appropriate directory
for third-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
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
will create an executable installer, foo-1.0.win32.exe, in the
current directory.
Other useful built distribution formats are RPM, implemented by the
bdist_rpm command, Solaris pkgtool
(bdist_pkgtool ), and HP-UX swinstall
(bdist_sdux ). For example, the following command will
create an RPM file called foo-1.0.noarch.rpm:
python setup.py bdist_rpm
(The bdist_rpm command uses the rpm executable,
therefore this has to be run on an RPM-based system such as Red Hat
Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by
running
python setup.py bdist --help-formats
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|