Python/docs/3.9/distutils/sourcedist

4. 创建源代码分发

笔记

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

如 简单示例 部分所示，您可以使用 sdist 命令创建源分发。 在最简单的情况下，

python setup.py sdist

（假设您没有在安装脚本或配置文件中指定任何 sdist 选项），sdist 会为当前平台创建默认格式的存档。 默认格式在 Unix 上是 gzip 压缩的 tar 文件 (.tar.gz)，在 Windows 上是 ZIP 文件。

您可以使用 --formats 选项指定任意数量的格式，例如：

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

创建一个 gzip 压缩包和一个 zip 文件。 可用的格式有：

格式	描述	笔记
zip	压缩文件 (.zip)	(1),(3)
gztar	gzip 压缩的 tar 文件 (.tar.gz)	(2)
bztar	bzip2'ed tar 文件 (.tar.bz2)
xztar	xz'ed tar 文件 (.tar.xz)
ztar	压缩的 tar 文件 (.tar.Z)	(4)
tar	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 命令会将最小的默认设置放入源代码分发版中：

• py_modules 和 packages 选项隐含的所有 Python 源文件
• ext_modules 或 libraries 选项中提到的所有 C 源文件
• 由 scripts 选项标识的脚本 请参阅 安装脚本 。
• 任何看起来像测试脚本的东西：test/test*.py（目前，Distutils 不对测试脚本做任何事情，除了将它们包含在源代码分发中，但将来会有一个用于测试 Python 模块分发的标准）
• 任何标准 README 文件（README、README.txt 或 README.rst）、setup.py（或任何您调用的安装脚本）和 setup.cfg。
• 与 package_data 元数据匹配的所有文件。 请参阅 安装包数据 。
• 与 data_files 元数据匹配的所有文件。 请参阅 安装附加文件 。

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

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

3.1 版更改： 将重新生成现有生成的 MANIFEST，无需 sdist 将其修改时间与 MANIFEST.in 或 [ X171X]。

在 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/）
• 名为 RCS、CVS、.svn、.hg、.git、.bzr 或 _darcs

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

您可以使用 --no-defaults 选项禁用默认的包含文件集，也可以使用 --no-prune 禁用标准排除集。

遵循 Distutils 自己的清单模板，让我们跟踪 sdist 命令如何构建要包含在 Distutils 源代码分发中的文件列表：

1. 包括 distutils 和 distutils/command 子目录中的所有 Python 源文件（因为在安装脚本的 packages 选项中提到了对应于这两个目录的包——请参阅 部分）编写安装脚本)
2. 包括 README.txt、setup.py 和 setup.cfg（标准文件）
3. 包括 test/test*.py（标准文件）
4. 在分布根目录中包含 *.txt（这将第二次找到 README.txt，但这种冗余稍后会被淘汰）
5. 在 examples 下的子树中包含与 *.txt 或 *.py 匹配的任何内容，
6. 排除从匹配 examples/sample?/build 的目录开始的子树中的所有文件——这可能会排除前两个步骤中包含的文件，因此清单模板中的 prune 命令很重要，在 [ X223X] 命令
7. 排除整个 build 树，以及任何 RCS、CVS、.svn、.hg、.git、.bzr 和 _darcs 目录

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

4.2. 清单相关选项

sdist命令的正常操作过程如下：

• 如果清单文件（默认情况下为 MANIFEST）存在并且第一行没有注释表明它是从 MANIFEST.in 生成的，则按原样使用，未更改
• 如果清单文件不存在或之前已自动生成，请阅读 MANIFEST.in 并创建清单
• 如果 MANIFEST 和 MANIFEST.in 都不存在，则创建一个仅包含默认文件集的清单
• 现在使用 MANIFEST 中的文件列表（刚刚生成或读入）来创建源分发存档

有几个选项可以修改此行为。 首先，使用 --no-defaults 和 --no-prune 禁用标准的“包含”和“排除”集。

其次，您可能只想（重新）生成清单，而不是创建源分发：

python setup.py sdist --manifest-only

-o 是 --manifest-only 的快捷方式。