GNU Info

(python2.1-dist.info)A simple example

---

Next: General Python terminology Prev: Concepts & Terminology Up: Concepts & Terminology

---

Enter node , (file) or (file)node

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.(1)  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~Note: Writing the Setup Script 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

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

     python setup.py install

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.

Currently (Distutils 0.9.2), the 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

(This uses the `rpm' command, so 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

---------- Footnotes ----------

(1) 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.