4. 创建源代码分发 — Python 文档
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 格式的支持。
笔记：
- Windows 上的默认设置
- Unix 上的默认值
- 需要外部 zip 实用程序或 zipfile 模块（自 Python 1.6 起成为标准 Python 库的一部分）
- 需要 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 源代码分发中的文件列表：
- 包括
distutils和distutils/command子目录中的所有 Python 源文件（因为在安装脚本的packages选项中提到了对应于这两个目录的包——请参阅 部分）编写安装脚本) - 包括
README.txt、setup.py和setup.cfg（标准文件） - 包括
test/test*.py（标准文件） - 在分布根目录中包含
*.txt（这将再次找到README.txt，但此类冗余稍后会被淘汰） - 在
examples下的子树中包含与*.txt或*.py匹配的任何内容， - 排除从匹配
examples/sample?/build的目录开始的子树中的所有文件——这可能会排除前两个步骤中包含的文件，因此清单模板中的prune命令很重要，在 [ X223X] 命令 - 排除整个
build树，以及任何RCS、CVS、.svn、.hg、.git、.bzr和_darcs目录
就像在安装脚本中一样，清单模板中的文件和目录名称应始终以斜杠分隔； Distutils 将负责将它们转换为您平台上的标准表示。 这样，清单模板就可以跨操作系统移植。
