distutilsIntroduction

.. _distutils-intro:

**************************** An Introduction to Distutils ****************************

This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for information on installing Python modules, you should refer to the :ref:install-index chapter.

.. _distutils-concepts:

Concepts & Terminology ======================

Using the Distutils is quite simple, both for module developers and for users/administrators installing third-party modules. As a developer, your responsibilities (apart from writing solid, well-documented and well-tested code, of course!) are:

* write a setup script (:file:`setup.py` by convention)

* (optional) write a setup configuration file

* create a source distribution

* (optional) create one or more built (binary) distributions

Each of these tasks is covered in this document.

Not all module developers have access to a multitude of platforms, so it's not always feasible to expect them to create a multitude of built distributions. It is hoped that a class of intermediaries, called *packagers*, will arise to address this need. Packagers will take source distributions released by module developers, build them on one or more platforms, and release the resulting built distributions. Thus, users on the most popular platforms will be able to install most popular Python module distributions in the most natural way for their platform, without having to run a single setup script or compile a line of code.

.. _distutils-simple-example:

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, though you should 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 all you want to do is distribute a module called :mod:foo, contained in a file :file:`foo.py`, then your setup script can be as simple 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 :func:setup function

* those keyword arguments fall into two categories: package metadata (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 metadata, in particular your

• name, email address and a URL for the project (see section :ref:setup-script for an example)

To create a source distribution for this module, you would create a setup script, :file:`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 :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`.

If an end-user wishes to install your :mod:foo module, all she has to do is download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the :file:`foo-1.0` directory---run ::

• python setup.py install

which will ultimately copy :file:`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 :command:sdist command is almost exclusively for module developers, while :command: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 :command:bdist_wininst command. For example::

• python setup.py bdist_wininst

will create an executable installer, :file:`foo-1.0.win32.exe`, in the current directory.

Other useful built distribution formats are RPM, implemented by the :command:bdist_rpm command, Solaris :program:pkgtool (:command:bdist_pkgtool), and HP-UX :program:swinstall (:command:bdist_sdux). For example, the following command will create an RPM file called :file:`foo-1.0.noarch.rpm`::

• python setup.py bdist_rpm

(The :command:bdist_rpm command uses the :command:rpm executable, therefore this 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

.. _python-terms:

General Python terminology ==========================

If you're reading this document, you probably have a good idea of what modules, extensions, and so forth are. Nevertheless, just to be sure that everyone is operating from a common starting point, we offer the following glossary of common Python terms:

常见Python术语词汇：

module

• the basic unit of code reusability in Python: a block of code imported by some other code. Three types of modules concern us here: pure Python modules, extension modules, and packages.

模块（module）

• Python中可以复用的基本单元代码：一段（block）可以被其它代码导入（import）的代码。 我们这儿使用三种类型模块：纯Python模块（pure Python module），扩展模块（extension module），和包（package）。

pure Python module

• a module written in Python and contained in a single :file:`.py` file (and possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred to as a "pure module."

纯Python模块(pure Python module)

• 使用Python编写的一个模块，并且它被包含在一个独立的.py文件内 （也有可能是.pyc和/或.pyo文件）。有时也看作是一个“纯模块”（pure module）。

extension module

• a module written in the low-level language of the Python implementation: C/C++ for Python, Java for Jython. Typically contained in a single dynamically

  loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python extensions on Windows, or a Java class file for Jython extensions. (Note that currently, the Distutils only handles C/C++ extensions for Python.)

扩展模块（extension module）

• 使用低级语言编写Python实现的一个模块：C/C++的Python，Java的Jython。 通常包含在一个单独的可以动态加载的预编译文件里，如，Unix上Python扩展的一个共享对象 （.so）文件，Windows上Pyhton扩展的一个DLL（指定.pyd扩展）， 或一个Jython扩展的Java类文件。（注意，目前Disutils只处理Python的C/C++扩展。）

package

• a module that contains other modules; typically contained in a directory in the filesystem and distinguished from other directories by the presence of a file

  :file:`__init__.py`.

包（package）

• 包含其它模块的一个模块；通常包含在文件系统上的一个目录里，通过添加一个init.py 文件跟其它目录区别开来。

root package

• the root of the hierarchy of packages. (This isn't really a package, since it

  doesn't have an :file:`__init__.py` file. But we have to call it something.) The vast majority of the standard library is in the root package, as are many small, standalone third-party modules that don't belong to a larger module collection. Unlike regular packages, modules in the root package can be found in many directories: in fact, every directory listed in sys.path contributes modules to the root package.

根包（root package）

• 具层次包里的根目录。（它不是一个真正的包，因为它没有init.py文件。 但我们总得给它一个名字。） 约大多数标准库都在根包下，因为许多小的，独立的第三方模块不属于一个更大的模块集合。 跟一般的包不一样，可以在要许多目录里找到要根包的模块。 事实上，sys.path列出的各个目录的模块，组成根包。

.. _distutils-term:

Distutils-specific terminology ==============================

The following terms apply more specifically to the domain of distributing Python modules using the Distutils:

module distribution

• a collection of Python modules distributed together as a single downloadable resource and meant to be installed *en masse*. Examples of some well-known module distributions are Numeric Python, PyXML, PIL (the Python Imaging Library), or mxBase. (This would be called a *package*, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.)

pure module distribution

• a module distribution that contains only pure Python modules and packages. Sometimes referred to as a "pure distribution."

non-pure module distribution

• a module distribution that contains at least one extension module. Sometimes referred to as a "non-pure distribution."

distribution root

• the top-level directory of your source tree (or source distribution); the

  directory where :file:`setup.py` exists. Generally :file:`setup.py` will be run from this directory.