10.1 distutils.core -- Core Distutils functionality

Python PEP

10.1 distutils.core -- Core Distutils functionality

The distutils.core module is the only module that needs to be installed to use the Distutils. It provides the setup() (which is called from the setup script). Indirectly provides the distutils.dist.Distribution and distutils.cmd.Command class.

The basic do-everything function that does most everything you could ever ask for from a Distutils method. See XXXXX

The setup function takes a large number of arguments. These are laid out in the following table.

argument name value type
name The name of the package a string
version The version number of the package See distutils.version
description A single line describing the package a string
long_description Longer description of the package a string
author The name of the package author a string
author_email The email address of the package author a string
maintainer The name of the current maintainer, if different from the author a string
maintainer_email The email address of the current maintainer, if different from the author
url A URL for the package (homepage) a URL
download_url A URL to download the package a URL
packages A list of Python packages that distutils will manipulate a list of strings
py_modules A list of Python modules that distutils will manipulate a list of strings
scripts A list of standalone script files to be built and installed a list of strings
ext_modules A list of Python extensions to be built A list of instances of distutils.core.Extension
classifiers A list of Trove categories for the package XXX link to better definition
distclass the Distribution class to use A subclass of distutils.core.Distribution
script_name The name of the setup.py script - defaults to sys.argv[0] a string
script_args Arguments to supply to the setup script a list of strings
options default options for the setup script a string
license The license for the package
keywords Descriptive meta-data. See PEP 314
platforms
cmdclass A mapping of command names to Command subclasses a dictionary

Run a setup script in a somewhat controlled environment, and return the distutils.dist.Distribution instance that drives things. This is useful if you need to find out the distribution meta-data (passed as keyword args from script to setup()), or the contents of the config files or command-line.

script_name is a file that will be run with execfile() sys.argv[0] will be replaced with script for the duration of the call. script_args is a list of strings; if supplied, sys.argv[1:] will be replaced by script_args for the duration of the call.

stop_after tells setup() when to stop processing; possible values:

value description
init Stop after the Distribution instance has been created and populated with the keyword arguments to setup()
config Stop after config files have been parsed (and their data stored in the Distribution instance)
commandline Stop after the command-line (sys.argv[1:] or script_args) have been parsed (and the data stored in the Distribution instance.)
run Stop after all commands have been run (the same as if setup() had been called in the usual way). This is the default value.

In addition, the distutils.core module exposed a number of classes that live elsewhere.

A short description of each of these follows, but see the relevant module for the full reference.

The Extension class describes a single C or C++extension module in a setup script. It accepts the following keyword arguments in it's constructor

argument name value type
name the full name of the extension, including any packages -- ie. not a filename or pathname, but Python dotted name string
sources list of source filenames, relative to the distribution root (where the setup script lives), in Unix form (slash-separated) for portability. Source files may be C, C++, SWIG (.i), platform-specific resource files, or whatever else is recognized by the build_ext command as source for a Python extension. string
include_dirs list of directories to search for C/C++ header files (in Unix form for portability) string
define_macros list of macros to define; each macro is defined using a 2-tuple, where 'value' is either the string to define it to or None to define it without a particular value (equivalent of #define FOO in source or -DFOO on Unix C compiler command line) (string,string) tuple or (name,None)
undef_macros list of macros to undefine explicitly string
library_dirs list of directories to search for C/C++ libraries at link time string
libraries list of library names (not filenames or paths) to link against string
runtime_library_dirs list of directories to search for C/C++ libraries at run time (for shared extensions, this is when the extension is loaded) string
extra_objects list of extra files to link with (eg. object files not implied by 'sources', static library that must be explicitly specified, binary resource files, etc.) string
extra_compile_args any extra platform- and compiler-specific information to use when compiling the source files in 'sources'. For platforms and compilers where a command line makes sense, this is typically a list of command-line arguments, but for other platforms it could be anything. string
extra_link_args any extra platform- and compiler-specific information to use when linking object files together to create the extension (or to create a new static Python interpreter). Similar interpretation as for 'extra_compile_args'. string
export_symbols list of symbols to be exported from a shared extension. Not used on all platforms, and not generally necessary for Python extensions, which typically export exactly one symbol: init + extension_name. string
depends list of files that the extension depends on string
language extension language (i.e. 'c', 'c++', 'objc'). Will be detected from the source extensions if not provided. string

A Distribution describes how to build, install and package up a Python software package.

See the setup() function for a list of keyword arguments accepted by the Distribution constructor. setup() creates a Distribution instance.

A Command class (or rather, an instance of one of it's subclasses) implement a single distutils command.

See About this document... for information on suggesting changes.