Created by: gwideman, Nov 23, 2013 1:52 pm
Revised by: gwideman, Oct 7, 2014 7:35 pm (32 revisions)

Overview

This is a template for documentation about python installation libraries 'distutils' and setuptools.

(((MainPage)))
Generated
$GeneratedTimeStamp$
Python version
$PythonVersion$
distutils version
$DistutilsVersion$
setuptools version
$SetuptoolsVersion$

Contents

Overview

This page presents combined detail documentation for the setup() function supplied by distutils and setuptools (plus wheel extension), including setup()'s arguments, the command-line arguments it digests and interprets as commands, and the arguments to those commands.
For an introduction to distutils and setuptools, please see the page: Python- distutils-setuptools introduction.
The information on this page has been gathered almost completely automatically from distutils and setuptools libraries, so should agree closely with actual behavior of those libraries. (See applicable version numbers, above.)

Command-line invocation of setup.py

Usage as documented by distutils.core.USAGE:

$core_usage$

Usage as documented by Distribution.common_usage:

Common commands: (see '--help-commands' for more)
Example invocation
Description
setup.py build
will build the package underneath 'build/'
setup.py install
will install the package

Command line parsing details

Command line parsing details from parse_command_line( ) functions' doc strings:
distutils
$DU_parse_command_line_doc$
setuptools
$ST_parse_command_line_doc$

setup.py commands summary

Command-line options that distutils.core.setup( ) interprets as commands.
Command category
Command
DU
ST
Description
$CommandsSummaryRows$
Key: DU and ST columns indicate for each command whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils.

General options

Global and Display options to setup.py, which must be provided on the command line before Commands.

Global options

Long
Short
Args
Description
$GlobalOptionRows$

Display options

Long
Short
Args
Description
$DisplayOptionRows$

Command Details

Commands listed in alphabetical order.

$CommandsDetails$

setup( ) function

distutils.core.setup() doc string:

$setup_func_doc$

distutils and setuptools Distribution class doc strings:

distutils
$DU_setup_func_Distribution_doc$
setuptools
$ST_setup_func_Distribution_doc$

setup( ) function arguments

Keyword arguments to distutils.core.setup( ). All arguments are in general optional (which is why they are keyword arguments and not positional), though some are required depending on the command being executed.
Most of the arguments to setup( ) specify metadata about, or components to include in, the distribution package being prepared or installed.
Other arguments provide less-frequently needed functionality. For example, script_name and script_args can be used to supply as function arguments what setup( ) would normally get from the script's command line arguments.
(Note that in the docs that follow, "package" generally means "distribution package", not "module package" as found in the python language.)
Argument name
Type
Defn
Description
$SetupFuncArgRows$

Analysis of distutils and setuptools

  • My program: $DataCollectionProgram$
  • Python version: $PythonVersion$
(((/MainPage)))

(((OptionRow)))
$Long$
$Short$
$Args$
$Description$
(((/OptionRow)))

(((CommandsSummaryRow)))
$CmdCat$
$Command$
$DU$
$ST$
$Description$
(((/CommandsSummaryRow)))

(((CommandDetail)))

Command: $CommandName$

Command defined in
Description
Docstring
$CommandDefDetailRows$

Options for $CommandName$

Long
Short
Args
bool
DU
ST
Description
$CommandDetailOptionRows$
Key: DU and ST columns indicate for each option whether it is available and implemented in distutils and setuptools. Uppercase indicates implemented. Lowercase 'du' in the ST column indicates available in setuptools, simply inherited from distutils. 'X' in ST column indicates not available.

(((/CommandDetail)))

(((CommandDefDetailRow)))
$package$
$Description$
$Docstring$
(((/CommandDefDetailRow)))

(((CommandDetailOptionRow)))
$Long$
$Short$
$Args$
$bool$
$DU$
$ST$
$Description$
(((/CommandDetailOptionRow)))

(((SetupFuncArgRow)))
$ArgName$
$Type$
$Defn$
$Description$
(((/SetupFuncArgRow)))