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 she has 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, PIL (the Python Imaging 197 Library), 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