/Doc/distutils/introduction.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 208 lines · 151 code · 57 blank · 0 comment · 0 complexity · 0fd98332fa28833e9ded42cc201645ff MD5 · raw file

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