# 1. Distutils 模块介绍

备注

这篇文档是历史遗留文档，在 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 `setuptools` 文档独立涵盖此处包含的所有相关信息之后，将不再单独作为正式文档保留。

本文档介绍了使用 Distutils 模块分发你的 Python 模块，主要是针对开发者/分发者的使用的——如果你想了解如何安装 Python 模块，你应该参考这个章节： 安装Python模块（旧版）。

## 1.1. 概念和术语

Distutils 用起来非常简单，对于模块开发者或安装第三方模块的用户/管理员均是如此。开发者的责任（当然还有编写可靠、良好文档和经过良好测试的代码！）就是：

- 编写一个设置脚本 (`setup.py` by convention)

- (可选)编写设置脚本的配置文件

- 创建源码的发行版

- （可选）创建一个或多个编译好（二进制）的发行版

这些操作在此文档均有讲解。

并非所有的模块开发者都能接触到众多的平台，所以期望他们创造众多的内置发行版不是总是可行的。最好是有一类名为 打包者 的中介，以满足这一需求。打包者将读取模块开发者发布的源代码，在一个或多个平台上进行编译，并发布构建出来的发行版。这样，最流行平台的用户就能以最自然的方式安装最流行的 Python 模块发行版，不必运行一段 setup 脚本或编译代码了。

## 1.2. 一个简单的例子

setup 脚本通常很简单，尽管是用 Python 编写的，它能干的事情没有限制，当然应小心别在 setup 脚本中加入什么运行缓慢的操作。与 Autoconf 风格的 configure 脚本不同，在构建和安装模块的过程中 setup 脚本可能会运行多次。

如果只想发布一个名为 `foo` 的模块，位于 `foo.py` 文件中，那么 setup 脚本可以如此简单：

    from distutils.core import setup
    setup(name='foo',
          version='1.0',
          py_modules=['foo'],
          )

注意要点：

- 提供给 Distutils 的大部分信息将作为关键字参数发给 `setup()` 函数。

- 这些关键字参数分为两类：包的元数据（名称、版本号）和包中内容的描述信息（本例中是纯 Python 模块的列表）。

- 模块由模块名指定，而不是文件名（包和扩展也是如此）。

- 建议多提供一些元数据，特别是开发者姓名、电子邮件地址和项目的URL（参见 编写安装脚本 中的例子）。

要为该模块创建一个源码发布版本，需要创建一段 setup 脚本 `setup.py`，包含上述代码，然后从终端运行以下命令：

    python setup.py sdist

对于 Windows 用户来说，打开命令行窗口（Start ‣ Accessories）并且写上如下命令:

    setup.py sdist

sdist 将创建一个归档文件（例如在 Unix 中为 tarball，在 Windows 中为 ZIP 文件），其中包含你的配置脚本 `setup.py` 以及你的模块 `foo.py`。 此归档文件将被命名为 `foo-1.0.tar.gz` (或 `.zip`)，并将解包到目录 `foo-1.0` 当中。

如果最终用户希望安装 `foo` 模块，只需下载 `foo-1.0.tar.gz` （或 `.zip` ）并解压，进入 `foo-1.0` 目录运行：

    python setup.py install

这会把 `foo.py` 复制到 Python 安装环境的第三方模块目录中。

上述简单例子展示了 Distutils 的一些基本概念。首先，开发者和安装者拥有相同的基本用户界面，即 setup 脚本。区别在于使用哪种 Distutils 命令 ： sdist 命令几乎只适用于模块开发者，而 install 则更适用于安装者（当然大多数开发者偶尔也想要安装自己的代码）。

其他有用的内置分发格式是 RPM，可由 bdist_rpm 、Solaris pkgtool`（:command:`bdist_pkgtool）和 HP-UX swinstall`（:command:`bdist_sdux）实现。比如，以下命令将创建一个名为 `foo-1.0.noarch.rpm` 的RPM文件：

    python setup.py bdist_rpm

（bdist_rpm 命令用到了 rpm 可执行文件，因此必须运行在基于 RPM 的系统中，如 Red Hat Linux 、 SuSE Linux 或 Mandrake Linux）。

可以随时运行以下命令，以便了解当前可用的分发格式：

    python setup.py bdist --help-formats

## 1.3. 通用的 Python 术语

本文读者可能对模块、扩展等已有了很好的理解。但为确保所有人都站在同一起点上，下面提供了 Python 常用术语表：

module

  实现 Python 代码重用的基本单位：可被其他代码导入的一段代码。有三种类型的模块与本文有关：纯 Python 模块、扩展模块和包。

纯 Python 模块

  用 Python 编写的模块，包含在某 `.py` 文件中（可能还会有相关的 `.pyc` 文件）。有时被称为 "纯模块"。

extension module -- 扩展模块

  用低级语言编写的 Python 模块。Python 用 C/C++ ，而 Jython 则用Java。通常包含在一个可动态加载的预编译文件中，比如 Unix 中的 Python 扩展是一个共享对象（`.so`）文件，Windows 中的 Python 扩展则是一个 DLL （扩展名为 `.pyd` )，而 Jython 的扩展是个 Java class 文件。（注意，目前，Distutils 只处理 Python 的 C/C++ 扩展。）

包

  包含其他模块的模块；通常位于文件系统的某个目录中，区别于其他目录的标记就是存在一个 `__init__.py` 文件。

根包

  包的层次结构的根。（其并非一个真正的包，因为没有 `__init__.py` 文件。但总得给它起个名字）。 绝大多数标准库都在根包中，还有许多不属于任何大型模块的小型、独立的第三方模块。与普通的包不同，根包中的模块可能会在很多目录中出现：事实上，`sys.path` 列出的每个目录都会为根包提供模块。

## 1.4. Distutils 特定的术语

以下属于更加特别地用于 Distutils 发布 Python 模块。

模块发行版

  一组 Python 模块，作为可下载的资源组团发布，以便 大规模 安装。模块发布版的著名例子是 NumPy 、 SciPy 、 Pillow 或 mxBase。（这些会被称为 package，这个词在 Python 的语境中也使用过：一个模块发行版可能包含零个、一个或多个 Python 包。)

纯模块发行版

  只包含纯 Python 模块和软件包的模块发布版。有时被称为“纯发行版”。

非纯模块发行版

  至少包含一个扩展模块的模块发行版。 有时被称为“非纯发行版”。

根发行版

  源代码树（或源代码发行版）的顶级目录；即 `setup.py` 所在的目录。 一般来说，`setup.py` 会在该目录下运行。