4. 创建源代码分发包

注解

这篇文档只有在 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 setuptools 文档独立涵盖此处包含的所有相关信息之前，才会单独保留。

如 一个简单的例子 一节所示，可以使用 sdist 命令来创建一个源代码分发包。 在最简单的场景下，:

python setup.py sdist

（假定你没有在设置脚本或配置文件中指定任何 sdist 选项），sdist 将创建基于当前平台的默认格式的归档。 在 Unix 上默认格式为 gzip 的 tar 文件，而在 Windows 上则为 ZIP 文件。

你可以使用 --formats 选项来指定任何你想要的格式，例如:

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

创建一个 gzip 的 tar 文件和一个 zip 文件。 可用的格式有:

格式	描述	注释
zip	zip 文件 (.zip)	(1),(3)
gztar	gzip'ed 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 名称。

举例来说，如果你希望归档中所有文件均为 root 所有:

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

4.1. Specifying the files to distribute

If you don't supply an explicit list of files (or instructions on how to generate one), the sdist command puts a minimal default set into the source distribution:

• all Python source files implied by the py_modules and packages options

• all C source files mentioned in the ext_modules or libraries options

• scripts identified by the scripts option See Installing Scripts.

• anything that looks like a test script: test/test*.py (currently, the Distutils don't do anything with test scripts except include them in source distributions, but in the future there will be a standard for testing Python module distributions)

• Any of the standard README files (README, README.txt, or README.rst), setup.py (or whatever you called your setup script), and setup.cfg.

• all files that matches the package_data metadata. See Installing Package Data.

• all files that matches the data_files metadata. See Installing Additional Files.

Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a manifest template, called MANIFEST.in by default. The manifest template is just a list of instructions for how to generate your manifest file, MANIFEST, which is the exact list of files to include in your source distribution. The sdist command processes this template and generates a manifest based on its instructions and what it finds in the filesystem.

If you prefer to roll your own manifest file, the format is simple: one filename per line, regular files (or symlinks to them) only. If you do supply your own MANIFEST, you must specify everything: the default set of files described above does not apply in this case.

在 3.1 版更改: An existing generated MANIFEST will be regenerated without sdist comparing its modification time to the one of MANIFEST.in or setup.py.

在 3.1.3 版更改: MANIFEST files start with a comment indicating they are generated. Files without this comment are not overwritten or removed.

在 3.2.2 版更改: sdist will read a MANIFEST file if no MANIFEST.in exists, like it used to do.

在 3.7 版更改: README.rst is now included in the list of distutils standard READMEs.

The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template:

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

The meanings should be fairly clear: include all files in the distribution root matching *.txt, all files anywhere under the examples directory matching *.txt or *.py, and exclude all directories matching examples/sample?/build. All of this is done after the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the --no-defaults option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section 创建源码发行包: sdist 命令.

The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds to or removes from that list of files. Once we have fully processed the manifest template, we remove files that should not be included in the source distribution:

• all files in the Distutils "build" tree (default build/)

• all files in directories named RCS, CVS, .svn, .hg, .git, .bzr or _darcs

Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s).

You can disable the default set of included files with the --no-defaults option, and you can disable the standard exclude set with --no-prune.

Following the Distutils' own manifest template, let's trace how the sdist command builds the list of files to include in the Distutils source distribution:

1. include all Python source files in the distutils and distutils/command subdirectories (because packages corresponding to those two directories were mentioned in the packages option in the setup script---see section 编写安装脚本)

2. include README.txt, setup.py, and setup.cfg (standard files)

3. include test/test*.py (standard files)

4. include *.txt in the distribution root (this will find README.txt a second time, but such redundancies are weeded out later)

5. include anything matching *.txt or *.py in the sub-tree under examples,

6. exclude all files in the sub-trees starting at directories matching examples/sample?/build---this may exclude files included by the previous two steps, so it's important that the prune command in the manifest template comes after the recursive-include command

7. exclude the entire build tree, and any RCS, CVS, .svn, .hg, .git, .bzr and _darcs directories

Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems.

4.2. Manifest-related options

The normal course of operations for the sdist command is as follows:

• if the manifest file (MANIFEST by default) exists and the first line does not have a comment indicating it is generated from MANIFEST.in, then it is used as is, unaltered

• if the manifest file doesn't exist or has been previously automatically generated, read MANIFEST.in and create the manifest

• if neither MANIFEST nor MANIFEST.in exist, create a manifest with just the default file set

• use the list of files now in MANIFEST (either just generated or read in) to create the source distribution archive(s)

There are a couple of options that modify this behaviour. First, use the --no-defaults and --no-prune to disable the standard "include" and "exclude" sets.

Second, you might just want to (re)generate the manifest, but not create a source distribution:

python setup.py sdist --manifest-only

-o is a shortcut for --manifest-only.