• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. _distutils-intro:
2
3****************************
4An Introduction to Distutils
5****************************
6
7This document covers using the Distutils to distribute your Python modules,
8concentrating on the role of developer/distributor: if you're looking for
9information on installing Python modules, you should refer to the
10:ref:`install-index` chapter.
11
12
13.. _distutils-concepts:
14
15Concepts & Terminology
16======================
17
18Using the Distutils is quite simple, both for module developers and for
19users/administrators installing third-party modules.  As a developer, your
20responsibilities (apart from writing solid, well-documented and well-tested
21code, of course!) are:
22
23* write a setup script (:file:`setup.py` by convention)
24
25* (optional) write a setup configuration file
26
27* create a source distribution
28
29* (optional) create one or more built (binary) distributions
30
31Each of these tasks is covered in this document.
32
33Not all module developers have access to a multitude of platforms, so it's not
34always feasible to expect them to create a multitude of built distributions.  It
35is hoped that a class of intermediaries, called *packagers*, will arise to
36address this need.  Packagers will take source distributions released by module
37developers, build them on one or more platforms, and release the resulting built
38distributions.  Thus, users on the most popular platforms will be able to
39install most popular Python module distributions in the most natural way for
40their platform, without having to run a single setup script or compile a line of
41code.
42
43
44.. _distutils-simple-example:
45
46A Simple Example
47================
48
49The setup script is usually quite simple, although since it's written in Python,
50there are no arbitrary limits to what you can do with it, though you should be
51careful about putting arbitrarily expensive operations in your setup script.
52Unlike, say, Autoconf-style configure scripts, the setup script may be run
53multiple times in the course of building and installing your module
54distribution.
55
56If all you want to do is distribute a module called :mod:`foo`, contained in a
57file :file:`foo.py`, then your setup script can be as simple as this::
58
59   from distutils.core import setup
60   setup(name='foo',
61         version='1.0',
62         py_modules=['foo'],
63         )
64
65Some observations:
66
67* most information that you supply to the Distutils is supplied as keyword
68  arguments to the :func:`setup` function
69
70* those keyword arguments fall into two categories: package metadata (name,
71  version number) and information about what's in the package (a list of pure
72  Python modules, in this case)
73
74* modules are specified by module name, not filename (the same will hold true
75  for packages and extensions)
76
77* it's recommended that you supply a little more metadata, in particular your
78  name, email address and a URL for the project (see section :ref:`setup-script`
79  for an example)
80
81To create a source distribution for this module, you would create a setup
82script, :file:`setup.py`, containing the above code, and run this command from a
83terminal::
84
85   python setup.py sdist
86
87For Windows, open a command prompt windows (:menuselection:`Start -->
88Accessories`) and change the command to::
89
90   setup.py sdist
91
92:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
93containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
94The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
95will unpack into a directory :file:`foo-1.0`.
96
97If an end-user wishes to install your :mod:`foo` module, all they have to do is
98download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
99:file:`foo-1.0` directory---run ::
100
101   python setup.py install
102
103which will ultimately copy :file:`foo.py` to the appropriate directory for
104third-party modules in their Python installation.
105
106This simple example demonstrates some fundamental concepts of the Distutils.
107First, both developers and installers have the same basic user interface, i.e.
108the setup script.  The difference is which Distutils *commands* they use: the
109:command:`sdist` command is almost exclusively for module developers, while
110:command:`install` is more often for installers (although most developers will
111want to install their own code occasionally).
112
113If you want to make things really easy for your users, you can create one or
114more built distributions for them.  For instance, if you are running on a
115Windows machine, and want to make things easy for other Windows users, you can
116create an executable installer (the most appropriate type of built distribution
117for this platform) with the :command:`bdist_wininst` command.  For example::
118
119   python setup.py bdist_wininst
120
121will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
122directory.
123
124Other useful built distribution formats are RPM, implemented by the
125:command:`bdist_rpm` command, Solaris :program:`pkgtool`
126(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
127(:command:`bdist_sdux`).  For example, the following command will create an RPM
128file called :file:`foo-1.0.noarch.rpm`::
129
130   python setup.py bdist_rpm
131
132(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
133this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
134Mandrake Linux.)
135
136You can find out what distribution formats are available at any time by running
137::
138
139   python setup.py bdist --help-formats
140
141
142.. _python-terms:
143
144General Python terminology
145==========================
146
147If you're reading this document, you probably have a good idea of what modules,
148extensions, and so forth are.  Nevertheless, just to be sure that everyone is
149operating from a common starting point, we offer the following glossary of
150common Python terms:
151
152module
153   the basic unit of code reusability in Python: a block of code imported by some
154   other code.  Three types of modules concern us here: pure Python modules,
155   extension modules, and packages.
156
157pure Python module
158   a module written in Python and contained in a single :file:`.py` file (and
159   possibly associated :file:`.pyc` and/or :file:`.pyo` files).  Sometimes referred
160   to as a "pure module."
161
162extension module
163   a module written in the low-level language of the Python implementation: C/C++
164   for Python, Java for Jython. Typically contained in a single dynamically
165   loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
166   extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
167   extensions on Windows, or a Java class file for Jython extensions.  (Note that
168   currently, the Distutils only handles C/C++ extensions for Python.)
169
170package
171   a module that contains other modules; typically contained in a directory in the
172   filesystem and distinguished from other directories by the presence of a file
173   :file:`__init__.py`.
174
175root package
176   the root of the hierarchy of packages.  (This isn't really a package, since it
177   doesn't have an :file:`__init__.py` file.  But we have to call it something.)
178   The vast majority of the standard library is in the root package, as are many
179   small, standalone third-party modules that don't belong to a larger module
180   collection. Unlike regular packages, modules in the root package can be found in
181   many directories: in fact, every directory listed in ``sys.path`` contributes
182   modules to the root package.
183
184
185.. _distutils-term:
186
187Distutils-specific terminology
188==============================
189
190The following terms apply more specifically to the domain of distributing Python
191modules using the Distutils:
192
193module distribution
194   a collection of Python modules distributed together as a single downloadable
195   resource and meant to be installed *en masse*.  Examples of some well-known
196   module distributions are Numeric Python, PyXML, Pillow,
197   or mxBase.  (This would be called a *package*, except that term is
198   already taken in the Python context: a single module distribution may contain
199   zero, one, or many Python packages.)
200
201pure module distribution
202   a module distribution that contains only pure Python modules and packages.
203   Sometimes referred to as a "pure distribution."
204
205non-pure module distribution
206   a module distribution that contains at least one extension module.  Sometimes
207   referred to as a "non-pure distribution."
208
209distribution root
210   the top-level directory of your source tree (or  source distribution); the
211   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will be
212   run from this directory.
213
214
215