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 则更适用于安装者（当然大多数开发者偶尔也想要安装自己的代码）。

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 bdist_wininst command. For example:

python setup.py bdist_wininst

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

其他有用的内置分发格式是 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 会在该目录下运行。