cpython / Doc / distutils / apiref.rst

API Reference

:mod:`distutils.core` --- Core Distutils functionality

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

In addition, the :mod:`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 its 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 a 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 :command:`build_ext` command as source for a Python extension. a list of strings
include_dirs list of directories to search for C/C++ header files (in Unix form for portability) a list of strings
define_macros list of macros to define; each macro is defined using a 2-tuple (name, value), 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 :option:`-DFOO` on Unix C compiler command line) a list of tuples
undef_macros list of macros to undefine explicitly a list of strings
library_dirs list of directories to search for C/C++ libraries at link time a list of strings
libraries list of library names (not filenames or paths) to link against a list of strings
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) a list of strings
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.) a list of strings
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. a list of strings
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'. a list of strings
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. a list of strings
depends list of files that the extension depends on a list of strings
language extension language (i.e. 'c', 'c++', 'objc'). Will be detected from the source extensions if not provided. a string
optional specifies that a build failure in the extension should not abort the build process, but simply skip the extension. a boolean

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

See the :func:`setup` function for a list of keyword arguments accepted by the Distribution constructor. :func:`setup` creates a Distribution instance.

A :class:`Command` class (or rather, an instance of one of its subclasses) implement a single distutils command.

:mod:`distutils.ccompiler` --- CCompiler base class

This module provides the abstract base class for the :class:`CCompiler` classes. A :class:`CCompiler` instance can be used for all the compile and link steps needed to build a single project. Methods are provided to set options for the compiler --- macro definitions, include directories, link path, libraries and the like.

This module provides the following functions.

The abstract base class :class:`CCompiler` defines the interface that must be implemented by real compiler classes. The class also has some utility methods used by several compiler classes.

The basic idea behind a compiler abstraction class is that each instance can be used for all the compile/link steps in building a single project. Thus, attributes common to all of those compile and link steps --- include directories, macros to define, libraries to link against, etc. --- are attributes of the compiler instance. To allow for variability in how individual files are treated, most of those attributes may be varied on a per-compilation or per-link basis.

The constructor for each subclass creates an instance of the Compiler object. Flags are verbose (show verbose output), dry_run (don't actually execute the steps) and force (rebuild everything, regardless of dependencies). All of these flags default to 0 (off). Note that you probably don't want to instantiate :class:`CCompiler` or one of its subclasses directly - use the :func:`distutils.CCompiler.new_compiler` factory function instead.

The following methods allow you to manually alter compiler options for the instance of the Compiler class.

The following methods implement methods for autodetection of compiler options, providing some functionality similar to GNU :program:`autoconf`.

The following methods invoke stages in the build process.

The following utility methods are defined by the :class:`CCompiler` class, for use by the various concrete subclasses.

:mod:`distutils.unixccompiler` --- Unix C Compiler

This module provides the :class:`UnixCCompiler` class, a subclass of :class:`CCompiler` that handles the typical Unix-style command-line C compiler:

:mod:`distutils.msvccompiler` --- Microsoft Compiler

This module provides :class:`MSVCCompiler`, an implementation of the abstract :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension modules need to be compiled with the same compiler that was used to compile Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium binaries are created using the Platform SDK.

:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on its own. To override this choice, the environment variables DISTUTILS_USE_SDK and MSSdk must be both set. MSSdk indicates that the current environment has been setup by the SDK's SetEnv.Cmd script, or that the environment variables had been registered when the SDK was installed; DISTUTILS_USE_SDK indicates that the distutils user has made an explicit choice to override the compiler selection by :class:`MSVCCompiler`.

:mod:`distutils.bcppcompiler` --- Borland Compiler

This module provides :class:`BorlandCCompiler`, an subclass of the abstract :class:`CCompiler` class for the Borland C++ compiler.

:mod:`distutils.cygwincompiler` --- Cygwin Compiler

This module provides the :class:`CygwinCCompiler` class, a subclass of :class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to Windows. It also contains the Mingw32CCompiler class which handles the mingw32 port of GCC (same as cygwin in no-cygwin mode).

:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler

This module provides the EMXCCompiler class, a subclass of :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.

:mod:`distutils.archive_util` --- Archiving utilities

This module provides a few functions for creating archive files, such as tarballs or zipfiles.

:mod:`distutils.dep_util` --- Dependency checking

This module provides functions for performing simple, timestamp-based dependency of files and groups of files; also, functions based entirely on such timestamp dependency analysis.

:mod:`distutils.dir_util` --- Directory tree operations

This module provides functions for operating on directories and trees of directories.

:mod:`distutils.file_util` --- Single file operations

This module contains some utility functions for operating on individual files.

:mod:`distutils.util` --- Miscellaneous other utility functions

This module contains other assorted bits and pieces that don't fit into any other utility module.

:mod:`distutils.dist` --- The Distribution class

This module provides the :class:`Distribution` class, which represents the module distribution being built/installed/distributed.

:mod:`distutils.extension` --- The Extension class

This module provides the :class:`Extension` class, used to describe C/C++ extension modules in setup scripts.

:mod:`distutils.debug` --- Distutils debug mode

This module provides the DEBUG flag.

:mod:`distutils.errors` --- Distutils exceptions

Provides exceptions used by the Distutils modules. Note that Distutils modules may raise standard exceptions; in particular, SystemExit is usually raised for errors that are obviously the end-user's fault (eg. bad command-line arguments).

This module is safe to use in from ... import * mode; it only exports symbols whose names start with Distutils and end with Error.

:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module

This module provides a wrapper around the standard :mod:`getopt` module that provides the following additional features:

  • short and long options are tied together
  • options have help strings, so :func:`fancy_getopt` could potentially create a complete usage summary
  • options set attributes of a passed-in object
  • boolean options can have "negative aliases" --- eg. if :option:`--quiet` is the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets verbose to false.

The option_table is a list of 3-tuples: (long_option, short_option, help_string)

If an option takes an argument, its long_option should have '=' appended; short_option should just be a single character, no ':' in any case. short_option should be None if a long_option doesn't have a corresponding short_option. All option tuples must have long options.

The :class:`FancyGetopt` class provides the following methods:

:mod:`distutils.filelist` --- The FileList class

This module provides the :class:`FileList` class, used for poking about the filesystem and building lists of files.

:mod:`distutils.log` --- Simple PEP 282-style logging

:mod:`distutils.spawn` --- Spawn a sub-process

This module provides the :func:`spawn` function, a front-end to various platform-specific functions for launching another program in a sub-process. Also provides :func:`find_executable` to search the path for a given executable name.

:mod:`distutils.sysconfig` --- System configuration information

The :mod:`distutils.sysconfig` module provides access to Python's low-level configuration information. The specific configuration variables available depend heavily on the platform and configuration. The specific variables depend on the build process for the specific version of Python being run; the variables are those found in the :file:`Makefile` and configuration header that are installed with Python on Unix systems. The configuration header is called :file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` for earlier versions of Python.

Some additional functions are provided which perform some useful manipulations for other parts of the :mod:`distutils` package.

The following function is only intended for use within the :mod:`distutils` package.

This function is even more special-purpose, and should only be used from Python's own build procedures.

:mod:`distutils.text_file` --- The TextFile class

This module provides the :class:`TextFile` class, which gives an interface to text files that (optionally) takes care of stripping comments, ignoring blank lines, and joining lines with backslashes.

This class provides a file-like object that takes care of all the things you commonly want to do when processing a text file that has some line-by-line syntax: strip comments (as long as # is your comment character), skip blank lines, join adjacent lines by escaping the newline (ie. backslash at end of line), strip leading and/or trailing whitespace. All of these are optional and independently controllable.

The class provides a :meth:`warn` method so you can generate warning messages that report physical line number, even if the logical line in question spans multiple physical lines. Also provides :meth:`unreadline` for implementing line-at-a-time lookahead.

:class:`TextFile` instances are create with either filename, file, or both. :exc:`RuntimeError` is raised if both are None. filename should be a string, and file a file object (or something that provides :meth:`readline` and :meth:`close` methods). It is recommended that you supply at least filename, so that :class:`TextFile` can include it in warning messages. If file is not supplied, :class:`TextFile` creates its own using the :func:`open` built-in function.

The options are all boolean, and affect the values returned by :meth:`readline`

option name description default
strip_comments strip from '#' to end-of- line, as well as any whitespace leading up to the '#'---unless it is escaped by a backslash true
lstrip_ws strip leading whitespace from each line before returning it false
rstrip_ws strip trailing whitespace (including line terminator!) from each line before returning it. true
skip_blanks skip lines that are empty *after* stripping comments and whitespace. (If both lstrip_ws and rstrip_ws are false, then some lines may consist of solely whitespace: these will *not* be skipped, even if skip_blanks is true.) true
join_lines if a backslash is the last non-newline character on a line after stripping comments and whitespace, join the following line to it to form one logical line; if N consecutive lines end with a backslash, then N+1 physical lines will be joined to form one logical line. false
collapse_join strip leading whitespace from lines that are joined to their predecessor; only matters if (join_lines and not lstrip_ws) false

Note that since rstrip_ws can strip the trailing newline, the semantics of :meth:`readline` must differ from those of the built-in file object's :meth:`readline` method! In particular, :meth:`readline` returns None for end-of-file: an empty string might just be a blank line (or an all-whitespace line), if rstrip_ws is true but skip_blanks is not.

:mod:`distutils.version` --- Version number classes

:mod:`distutils.cmd` --- Abstract base class for Distutils commands

This module supplies the abstract base class :class:`Command`.

Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as subroutines with local variables called options. The options are declared in :meth:`initialize_options` and defined (given their final values) in :meth:`finalize_options`, both of which must be defined by every command class. The distinction between the two is necessary because option values might come from the outside world (command line, config file, ...), and any options dependent on other options must be computed after these outside influences have been processed --- hence :meth:`finalize_options`. The body of the subroutine, where it does all its work based on the values of its options, is the :meth:`run` method, which must also be implemented by every command class.

The class constructor takes a single argument dist, a :class:`Distribution` instance.

Creating a new Distutils command

This section outlines the steps to create a new Distutils command.

A new command lives in a module in the :mod:`distutils.command` package. There is a sample template in that directory called :file:`command_template`. Copy this file to a new module with the same name as the new command you're implementing. This module should implement a class with the same name as the module (and the command). So, for instance, to create the command peel_banana (so that users can run peel_banana), you'd copy :file:`command_template` to :file:`distutils/command/`, then edit it so that it's implementing the class :class:`peel_banana`, a subclass of :class:`distutils.cmd.Command`.

Subclasses of :class:`Command` must define the following methods.

:mod:`distutils.command` --- Individual Distutils commands

:mod:`distutils.command.bdist` --- Build a binary installer

:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers

:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer

:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package

Builds a Windows Installer (.msi) binary package.

In most cases, the bdist_msi installer is a better choice than the bdist_wininst installer, because it provides better support for Win64 platforms, allows administrators to perform non-interactive installations, and allows installation through group policies.

:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM

:mod:`distutils.command.bdist_wininst` --- Build a Windows installer

:mod:`distutils.command.sdist` --- Build a source distribution

:mod:`` --- Build all files of a package

:mod:`distutils.command.build_clib` --- Build any C libraries in a package

:mod:`distutils.command.build_ext` --- Build any extensions in a package

:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package

Alternative implementation of build_py which also runs the 2to3 conversion library on each .py file that is going to be installed. To use this in a file for a distribution that is designed to run with both Python 2.x and 3.x, add:

   from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
   from distutils.command.build_py import build_py

to your, and later:

cmdclass = {'build_py': build_py}

to the invocation of setup().

:mod:`distutils.command.build_scripts` --- Build the scripts of a package

:mod:`distutils.command.clean` --- Clean a package build area

:mod:`distutils.command.config` --- Perform package configuration

:mod:`distutils.command.install` --- Install a package

:mod:`distutils.command.install_data` --- Install data files from a package

:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package

:mod:`distutils.command.install_lib` --- Install library files from a package

:mod:`distutils.command.install_scripts` --- Install script files from a package

:mod:`distutils.command.register` --- Register a module with the Python Package Index

The register command registers the package with the Python Package Index. This is described in more detail in PEP 301.

:mod:`distutils.command.check` --- Check the meta-data of a package

The check command performs some tests on the meta-data of a package. For example, it verifies that all required meta-data are provided as the arguments passed to the :func:`setup` function.