4. 创建源分发

注解

本文件仅保留至 setuptools https://setuptools.readthedocs.io/en/latest/setuptools.html上的文档独立地涵盖了此处当前包含的所有相关信息。

如第节所示 一个简单的例子 ，您使用 sdist 创建源分发的命令。在最简单的情况下：

python setup.py sdist

（假设您没有指定 sdist 设置脚本或配置文件中的选项）。 sdist 为当前平台创建默认格式的存档。默认格式是gzip'ed tar文件 (.tar.gz ）在Unix上，在Windows上是zip文件。

您可以使用 --formats 选项，例如：

python setup.py sdist --formats=gztar,zip

创建gzipped tarball和zip文件。可用的格式有：

格式

描述

笔记

zip

压缩文件 (.zip ）

(1),(3)

gztar

gzip'ed tar文件 (.tar.gz ）

(2)

bztar

bzip2'ed tar文件 (.tar.bz2 ）

xztar

XAR焦油锉 (.tar.xz ）

ztar

压缩tar文件 (.tar.Z ）

(4)

tar

焦油锉 (.tar ）

在 3.5 版更改: 增加了对 xztar 格式。

笔记：

  1. Windows上的默认设置

  2. UNIX上的缺省

  3. 需要外部 zip 效用或 zipfile 模块（自python 1.6以来标准python库的一部分）

  4. 需要 compress 程序。请注意，此格式现在正等待取消预测，并将在将来的Python版本中删除。

当使用任何 tar 格式 (gztar ， bztar ， xztar ， ztar 或 tar ，在Unix下，可以指定 owner 和 group 将为存档的每个成员设置的名称。

例如，如果希望存档的所有文件都归根目录所有：

python setup.py sdist --owner=root --group=root

4.1. 指定要分发的文件

如果没有提供明确的文件列表（或有关如何生成文件的说明），则 sdist 命令将最小默认集放入源分发：

  • 所有python源文件 py_modules 和 packages 选项

  • 中提到的所有C源文件 ext_modules 或 libraries 选项

  • 脚本由 scripts 选项请参见 正在安装脚本 .

  • 任何看起来像测试脚本的内容： test/test*.py （目前，distuils对测试脚本不做任何操作，除了将它们包含在源代码发行版中之外，但将来将有一个用于测试Python模块发行版的标准）

  • 任何标准自述文件 (README ， README.txt 或 README.rst ） setup.py （或您称之为安装脚本的任何内容），以及 setup.cfg .

  • 与匹配的所有文件 package_data 元数据。见 正在安装包数据 .

  • 与匹配的所有文件 data_files 元数据。见 安装其他文件 .

有时这就足够了，但通常您需要指定要分发的其他文件。典型的方法是写一个 清单模板 ，叫做 MANIFEST.in 默认情况下。清单模板只是如何生成清单文件的指令列表， MANIFEST ，这是要包含在源分发中的文件的确切列表。这个 sdist 命令处理此模板，并根据其指令和在文件系统中找到的内容生成清单。

如果您类似于滚动自己的清单文件，格式很简单：每行一个文件名，常规文件（或指向它们的符号链接）。如果你提供你自己的 MANIFEST ，必须指定所有内容：在这种情况下，上面描述的默认文件集不适用。

在 3.1 版更改: 现有生成的 MANIFEST 将在没有 sdist 将其修改时间与 MANIFEST.in 或 setup.py .

在 3.1.3 版更改: MANIFEST 文件以指示生成它们的注释开始。没有此注释的文件不会被覆盖或删除。

在 3.2.2 版更改: sdist 将阅读 MANIFEST 文件否 MANIFEST.in 存在，就像过去一样。

在 3.7 版更改: README.rst 现在包含在distutils标准自述文件列表中。

清单模板每行有一个命令，其中每个命令指定一组要包含或从源分发中排除的文件。例如，我们再次使用distutils自己的清单模板：

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

其含义应该相当清楚：包括分发根目录匹配中的所有文件 *.txt ，所有文件位于 examples 目录匹配 *.txt 或 *.py ，并排除所有匹配的目录 examples/sample?/build .所有这些都完成了 之后 标准包含集，因此可以使用清单模板中的显式说明从标准集排除文件。（或者，您可以使用 --no-defaults 选项完全禁用标准集。）清单模板迷你语言中还有其他几个命令可用；请参见第节 创建源分发：源分发 sdist 命令 .

清单模板中命令的顺序很重要：最初，我们有如上所述的默认文件列表，模板中的每个命令都添加到该文件列表或从中删除。一旦我们完全处理了清单模板，我们将删除不应包含在源分发中的文件：

  • distutils“build”树中的所有文件（默认 build/ ）

  • 名为的目录中的所有文件 RCS ， CVS ， .svn ， .hg ， .git ， .bzr 或 _darcs

现在我们有了完整的文件列表，这些文件被写入清单以供将来参考，然后用于构建源分发存档。

您可以使用 --no-defaults 选项，您可以禁用标准排除集 --no-prune .

按照distutils自己的清单模板，我们来跟踪 sdist 命令生成要包含在distutils源分发中的文件列表：

  1. 在中包含所有python源文件 distutils 和 distutils/command 子目录（因为在 packages 设置脚本中的选项---请参见第节 编写安装脚本 ）

  2. 包括 README.txt ， setup.py 和 setup.cfg （标准文件）

  3. 包括 test/test*.py （标准文件）

  4. 包括 *.txt 在分发根目录中（这将找到 README.txt 第二次，但这样的冗余稍后会被消除）

  5. 包括任何匹配的内容 *.txt 或 *.py 在下面的子树中 examples ，

  6. 从目录匹配开始排除子目录树中的所有文件 examples/sample?/build ---这可能会排除前两个步骤包含的文件，因此 prune 清单模板中的命令出现在 recursive-include 命令

  7. 排除整个 build 树，以及任何 RCS ， CVS ， .svn ， .hg ， .git ， .bzr 和 _darcs 目录

就像在安装脚本中一样，清单模板中的文件名和目录名应该始终用斜线分隔；distuils将负责将它们转换为平台上的标准表示形式。这样，清单模板就可以跨操作系统进行移植。