6.1.Pure Python distribution (by module)¶

If you’re just distributing a couple of modules, especially if they don’t livein a particular package, you can specify them individually using thepy_modules option in the setup script.

In the simplest case, you’ll have two files to worry about: a setup script andthe single module you’re distributing,foo.py in this example:

<root>/setup.pyfoo.py

(In all diagrams in this section,<root> will refer to the distribution rootdirectory.) A minimal setup script to describe this situation would be:

fromdistutils.coreimportsetupsetup(name='foo',version='1.0',py_modules=['foo'],)

Note that the name of the distribution is specified independently with thename option, and there’s no rule that says it has to be the same asthe name of the sole module in the distribution (although that’s probably a goodconvention to follow). However, the distribution name is used to generatefilenames, so you should stick to letters, digits, underscores, and hyphens.

Sincepy_modules is a list, you can of course specify multiplemodules, eg. if you’re distributing modulesfoo andbar, yoursetup might look like this:

<root>/setup.pyfoo.pybar.py

and the setup script might be

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',py_modules=['foo','bar'],)

You can put module source files into another directory, but if you have enoughmodules to do that, it’s probably easier to specify modules by package ratherthan listing them individually.

6.2.Pure Python distribution (by package)¶

If you have more than a couple of modules to distribute, especially if they arein multiple packages, it’s probably easier to specify whole packages rather thanindividual modules. This works even if your modules are not in a package; youcan just tell the Distutils to process modules from the root package, and thatworks the same as any other package (except that you don’t have to have an__init__.py file).

The setup script from the last example could also be written as

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',packages=[''],)

(The empty string stands for the root package.)

If those two files are moved into a subdirectory, but remain in the rootpackage, e.g.:

<root>/setup.pysrc/foo.pybar.py

then you would still specify the root package, but you have to tell theDistutils where source files in the root package live:

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',package_dir={'':'src'},packages=[''],)

More typically, though, you will want to distribute multiple modules in the samepackage (or in sub-packages). For example, if thefoo andbarmodules belong in packagefoobar, one way to layout your source tree is

<root>/setup.pyfoobar/__init__.pyfoo.pybar.py

This is in fact the default layout expected by the Distutils, and the one thatrequires the least work to describe in your setup script:

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',packages=['foobar'],)

If you want to put modules in directories not named for their package, then youneed to use thepackage_dir option again. For example, if thesrc directory holds modules in thefoobar package:

<root>/setup.pysrc/__init__.pyfoo.pybar.py

an appropriate setup script would be

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',package_dir={'foobar':'src'},packages=['foobar'],)

Or, you might put modules from your main package right in the distributionroot:

<root>/setup.py__init__.pyfoo.pybar.py

in which case your setup script would be

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',package_dir={'foobar':''},packages=['foobar'],)

(The empty string also stands for the current directory.)

If you have sub-packages, they must be explicitly listed inpackages,but any entries inpackage_dir automatically extend to sub-packages.(In other words, the Distutils doesnot scan your source tree, trying tofigure out which directories correspond to Python packages by looking for__init__.py files.) Thus, if the default layout grows a sub-package:

<root>/setup.pyfoobar/__init__.pyfoo.pybar.pysubfoo/__init__.pyblah.py

then the corresponding setup script would be

fromdistutils.coreimportsetupsetup(name='foobar',version='1.0',packages=['foobar','foobar.subfoo'],)

6.3.Single extension module¶

Extension modules are specified using theext_modules option.package_dir has no effect on where extension source files are found;it only affects the source for pure Python modules. The simplest case, asingle extension module in a single C source file, is:

<root>/setup.pyfoo.c

If thefoo extension belongs in the root package, the setup script forthis could be

fromdistutils.coreimportsetupfromdistutils.extensionimportExtensionsetup(name='foobar',version='1.0',ext_modules=[Extension('foo',['foo.c'])],)

If the extension actually belongs in a package, sayfoopkg, then

With exactly the same source tree layout, this extension can be put in thefoopkg package simply by changing the name of the extension:

fromdistutils.coreimportsetupfromdistutils.extensionimportExtensionsetup(name='foobar',version='1.0',ext_modules=[Extension('foopkg.foo',['foo.c'])],)

6.4.Checking a package¶

Thecheck command allows you to verify if your package meta-datameet the minimum requirements to build a distribution.

To run it, just call it using yoursetup.py script. If something ismissing,check will display a warning.

Let’s take an example with a simple script:

fromdistutils.coreimportsetupsetup(name='foobar')

Running thecheck command will display some warnings:

$pythonsetup.pycheckrunning checkwarning: check: missing required meta-data: version

If you use the reStructuredText syntax in thelong_description field anddocutils is installed you can check if the syntax is fine with thecheck command, using therestructuredtext option.

For example, if thesetup.py script is changed like this:

fromdistutils.coreimportsetupdesc="""\My description==============This is the description of the ``foobar`` package."""setup(name='foobar',version='1',author='tarek',author_email='tarek@ziade.org',url='http://example.com',long_description=desc)

Where the long description is broken,check will be able to detect itby using thedocutils parser:

$pythonsetup.pycheck--restructuredtextrunning checkwarning: check: Title underline too short. (line 2)warning: check: Could not finish the parsing.

6.5.Reading the metadata¶

Thedistutils.core.setup() function provides a command-line interfacethat allows you to query the metadata fields of a project through thesetup.py script of a given project:

$pythonsetup.py--namedistribute

This call reads thename metadata by running thedistutils.core.setup() function. Although, when a source or binarydistribution is created with Distutils, the metadata fields are writtenin a static file calledPKG-INFO. When a Distutils-based project isinstalled in Python, thePKG-INFO file is copied alongside the modulesand packages of the distribution underNAME-VERSION-pyX.X.egg-info,whereNAME is the name of the project,VERSION its version as definedin the Metadata, andpyX.X the major and minor version of Python like2.7 or3.2.

You can read back this static file, by using thedistutils.dist.DistributionMetadata class and itsread_pkg_file() method:

>>>fromdistutils.distimportDistributionMetadata>>>metadata=DistributionMetadata()>>>metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))>>>metadata.name'distribute'>>>metadata.version'0.6.8'>>>metadata.description'Easily download, build, install, upgrade, and uninstall Python packages'

Notice that the class can also be instantiated with a metadata file path toloads its values:

>>>pkg_info_path='distribute-0.6.8-py2.7.egg-info'>>>DistributionMetadata(pkg_info_path).name'distribute'