4.1.Specifying the files to distribute¶

If you don’t supply an explicit list of files (or instructions on how togenerate one), thesdist command puts a minimal default set into thesource distribution:

• all Python source files implied by thepy_modules andpackages options

• all C source files mentioned in theext_modules orlibraries options

• scripts identified by thescripts optionSeeInstalling Scripts.

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

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

• all files that matches thepackage_data metadata.SeeInstalling Package Data.

• all files that matches thedata_files metadata.SeeInstalling Additional Files.

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

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

The manifest template has one command per line, where each command specifies aset of files to include or exclude from the source distribution. For anexample, again we turn to the Distutils’ own manifest template:

include *.txtrecursive-include examples *.txt *.pyprune examples/sample?/build

The meanings should be fairly clear: include all files in the distribution rootmatching*.txt, all files anywhere under theexamples directorymatching*.txt or*.py, and exclude all directories matchingexamples/sample?/build. All of this is doneafter the standardinclude set, so you can exclude files from the standard set with explicitinstructions in the manifest template. (Or, you can use the--no-defaults option to disable the standard set entirely.) There areseveral other commands available in the manifest template mini-language; seesectionCreating a source distribution: the sdist command.

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

• all files in the Distutils “build” tree (defaultbuild/)

• all files in directories namedRCS,CVS,.svn,.hg,.git,.bzr or_darcs

Now we have our complete list of files, which is written to the manifest forfuture 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 setwith--no-prune.

Following the Distutils’ own manifest template, let’s trace how thesdist command builds the list of files to include in the Distutilssource distribution:

1. include all Python source files in thedistutils anddistutils/command subdirectories (because packages corresponding tothose two directories were mentioned in thepackages option in thesetup script—see sectionWriting the Setup Script)

2. includeREADME.txt,setup.py, andsetup.cfg (standardfiles)

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

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

5. include anything matching*.txt or*.py in the sub-treeunderexamples,

6. exclude all files in the sub-trees starting at directories matchingexamples/sample?/build—this may exclude files included by theprevious two steps, so it’s important that theprune command in the manifesttemplate comes after therecursive-include command

7. exclude the entirebuild tree, and anyRCS,CVS,.svn,.hg,.git,.bzr and_darcsdirectories

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

4.2.Manifest-related options¶

The normal course of operations for thesdist command is as follows:

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

• if the manifest file doesn’t exist or has been previously automaticallygenerated, readMANIFEST.in and create the manifest

• if neitherMANIFEST norMANIFEST.in exist, create a manifestwith just the default file set

• use the list of files now inMANIFEST (either just generated or readin) 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 sourcedistribution:

pythonsetup.pysdist--manifest-only

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