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