As shown in section 2.1, you use the
sdist
command to create a source distribution. In the
simplest case,
python setup.py sdist
(assuming you haven't specified any sdist
options in the setup
script or config file), sdist
creates the archive of the
default format for the current platform. The default format is a gzip'ed
tar file (.tar.gz) on Unix, and ZIP file on Windows.
** no MacOS support here **
You can specify as many formats as you like using the --formats option, for example:
python setup.py sdist --formats=gztar,zip
to create a gzipped tarball and a zip file. The available formats are:
Format | Description | Notes |
---|---|---|
zip |
zip file (.zip) | (1),(3) |
gztar |
gzip'ed tar file (.tar.gz) | (2),(4) |
bztar |
bzip2'ed tar file (.tar.bz2) | (4) |
ztar |
compressed tar file (.tar.Z) | (4) |
tar |
tar file (.tar) | (4) |
Notes:
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:
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.
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 9.2.
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:
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:
prune
command in the manifest template comes after the
recursive-include
command
The normal course of operations for the sdist
command is as
follows:
Second, you might want to force the manifest to be regenerated--for example, if you have added or removed files or directories that match an existing pattern in the manifest template, you should regenerate the manifest:
python setup.py sdist --force-manifest
Or, you might just want to (re)generate the manifest, but not create a source distribution:
python setup.py sdist --manifest-only
--manifest-only implies --force-manifest. -o is a shortcut for --manifest-only, and -f for --force-manifest.
See About this document... for information on suggesting changes.