[Python-checkins] gh-85454: Remove distutils documentation (#95239)
ambv
webhook-mailer at python.org
Mon Jul 25 09:50:57 EDT 2022
https://github.com/python/cpython/commit/a566912049722386478c075b83534fa9f7a1de45
commit: a566912049722386478c075b83534fa9f7a1de45
branch: main
author: Christian Heimes <christian at python.org>
committer: ambv <lukasz at langa.pl>
date: 2022-07-25T15:50:46+02:00
summary:
gh-85454: Remove distutils documentation (#95239)
Most places now refer to setuptools or link to setuptools documentation.
Some examples like zipapp need to be updated later.
files:
D Doc/distutils/_setuptools_disclaimer.rst
D Doc/distutils/apiref.rst
D Doc/distutils/builtdist.rst
D Doc/distutils/commandref.rst
D Doc/distutils/configfile.rst
D Doc/distutils/examples.rst
D Doc/distutils/extending.rst
D Doc/distutils/index.rst
D Doc/distutils/introduction.rst
D Doc/distutils/packageindex.rst
D Doc/distutils/setupscript.rst
D Doc/distutils/sourcedist.rst
D Doc/distutils/uploading.rst
D Doc/library/distutils.rst
M Doc/contents.rst
M Doc/extending/building.rst
M Doc/extending/windows.rst
M Doc/install/index.rst
M Doc/library/distribution.rst
M Doc/library/sysconfig.rst
M Doc/library/venv.rst
M Doc/using/configure.rst
M Doc/using/windows.rst
M Doc/whatsnew/2.7.rst
M Doc/whatsnew/3.4.rst
diff --git a/Doc/contents.rst b/Doc/contents.rst
index 8690de77bf3d8..464f93bdf85f9 100644
--- a/Doc/contents.rst
+++ b/Doc/contents.rst
@@ -27,5 +27,4 @@
.. toctree::
:hidden:
- distutils/index.rst
install/index.rst
diff --git a/Doc/distutils/_setuptools_disclaimer.rst b/Doc/distutils/_setuptools_disclaimer.rst
deleted file mode 100644
index cc75858326d44..0000000000000
--- a/Doc/distutils/_setuptools_disclaimer.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. note::
-
- This document is being retained solely until the ``setuptools`` documentation
- at https://setuptools.readthedocs.io/en/latest/setuptools.html
- independently covers all of the relevant information currently included here.
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
deleted file mode 100644
index 87c928555554a..0000000000000
--- a/Doc/distutils/apiref.rst
+++ /dev/null
@@ -1,2041 +0,0 @@
-.. _api-reference:
-
-*************
-API Reference
-*************
-
-.. seealso::
-
- `New and changed setup.py arguments in setuptools`_
- The ``setuptools`` project adds new capabilities to the ``setup`` function
- and other APIs, makes the API consistent across different Python versions,
- and is hence recommended over using ``distutils`` directly.
-
-.. _New and changed setup.py arguments in setuptools: https://web.archive.org/web/20210614192516/https://setuptools.pypa.io/en/stable/userguide/keywords.html
-
-.. include:: ./_setuptools_disclaimer.rst
-
-:mod:`distutils.core` --- Core Distutils functionality
-======================================================
-
-.. module:: distutils.core
- :synopsis: The 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.
-
-
-.. function:: setup(arguments)
-
- The basic do-everything function that does most everything you could ever ask
- for from a Distutils method.
-
- The setup function takes a large number of arguments. These are laid out in the
- following table.
-
- .. tabularcolumns:: |l|L|L|
-
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | argument name | value | type |
- +====================+================================+=============================================================+
- | *name* | The name of the package | a string |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *version* | The version number of the | a string |
- | | package; see | |
- | | :mod:`distutils.version` | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *description* | A single line describing the | a string |
- | | package | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *long_description* | Longer description of the | a string |
- | | package | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *author* | The name of the package author | a string |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *author_email* | The email address of the | a string |
- | | package author | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *maintainer* | The name of the current | a string |
- | | maintainer, if different from | |
- | | the author. Note that if | |
- | | the maintainer is provided, | |
- | | distutils will use it as the | |
- | | author in :file:`PKG-INFO` | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *maintainer_email* | The email address of the | a string |
- | | current maintainer, if | |
- | | different from the author | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *url* | A URL for the package | a string |
- | | (homepage) | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *download_url* | A URL to download the package | a string |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *packages* | A list of Python packages that | a list of strings |
- | | distutils will manipulate | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *py_modules* | A list of Python modules that | a list of strings |
- | | distutils will manipulate | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *scripts* | A list of standalone script | a list of strings |
- | | files to be built and | |
- | | installed | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *ext_modules* | A list of Python extensions to | a list of instances of |
- | | be built | :class:`distutils.core.Extension` |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI |
- | | package | <https://pypi.org/classifiers>`_. |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *distclass* | the :class:`Distribution` | a subclass of |
- | | class to use | :class:`distutils.core.Distribution` |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *script_name* | The name of the setup.py | a string |
- | | script - defaults to | |
- | | ``sys.argv[0]`` | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *script_args* | Arguments to supply to the | a list of strings |
- | | setup script | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *options* | default options for the setup | a dictionary |
- | | script | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *license* | The license for the package | a string |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string |
- | | :pep:`314` | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *platforms* | | a list of strings or a comma-separated string |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *cmdclass* | A mapping of command names to | a dictionary |
- | | :class:`Command` subclasses | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *data_files* | A list of data files to | a list |
- | | install | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
- | *package_dir* | A mapping of package to | a dictionary |
- | | directory names | |
- +--------------------+--------------------------------+-------------------------------------------------------------+
-
-
-
-.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
-
- Run a setup script in a somewhat controlled environment, and return the
- :class:`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 :func:`setup`), or the contents of the config files or
- command-line.
-
- *script_name* is a file that will be read and run with :func:`exec`. ``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 :func:`setup` when to stop processing; possible values:
-
- .. tabularcolumns:: |l|L|
-
- +---------------+---------------------------------------------+
- | value | description |
- +===============+=============================================+
- | *init* | Stop after the :class:`Distribution` |
- | | instance has been created and populated |
- | | with the keyword arguments to :func:`setup` |
- +---------------+---------------------------------------------+
- | *config* | Stop after config files have been parsed |
- | | (and their data stored in the |
- | | :class:`Distribution` instance) |
- +---------------+---------------------------------------------+
- | *commandline* | Stop after the command-line |
- | | (``sys.argv[1:]`` or *script_args*) have |
- | | been parsed (and the data stored in the |
- | | :class:`Distribution` instance.) |
- +---------------+---------------------------------------------+
- | *run* | Stop after all commands have been run (the |
- | | same as if :func:`setup` had been called |
- | | in the usual way). This is the default |
- | | value. |
- +---------------+---------------------------------------------+
-
-In addition, the :mod:`distutils.core` module exposed a number of classes that
-live elsewhere.
-
-* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
-
-* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
-
-* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
-
-A short description of each of these follows, but see the relevant module for
-the full reference.
-
-
-.. class:: Extension
-
- The Extension class describes a single C or C++ extension module in a setup
- script. It accepts the following keyword arguments in its constructor:
-
- .. tabularcolumns:: |l|L|l|
-
- +------------------------+--------------------------------+---------------------------+
- | argument name | value | type |
- +========================+================================+===========================+
- | *name* | the full name of the | a string |
- | | extension, including any | |
- | | packages --- ie. *not* a | |
- | | filename or pathname, but | |
- | | Python dotted name | |
- +------------------------+--------------------------------+---------------------------+
- | *sources* | list of source filenames, | a list of strings |
- | | 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. | |
- +------------------------+--------------------------------+---------------------------+
- | *include_dirs* | list of directories to search | a list of strings |
- | | for C/C++ header files (in | |
- | | Unix form for portability) | |
- +------------------------+--------------------------------+---------------------------+
- | *define_macros* | list of macros to define; each | a list of tuples |
- | | 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) | |
- +------------------------+--------------------------------+---------------------------+
- | *undef_macros* | list of macros to undefine | a list of strings |
- | | explicitly | |
- +------------------------+--------------------------------+---------------------------+
- | *library_dirs* | list of directories to search | a list of strings |
- | | for C/C++ libraries at link | |
- | | time | |
- +------------------------+--------------------------------+---------------------------+
- | *libraries* | list of library names (not | a list of strings |
- | | filenames or paths) to link | |
- | | against | |
- +------------------------+--------------------------------+---------------------------+
- | *runtime_library_dirs* | list of directories to search | a list of strings |
- | | for C/C++ libraries at run | |
- | | time (for shared extensions, | |
- | | this is when the extension is | |
- | | loaded) | |
- +------------------------+--------------------------------+---------------------------+
- | *extra_objects* | list of extra files to link | a list of strings |
- | | with (eg. object files not | |
- | | implied by 'sources', static | |
- | | library that must be | |
- | | explicitly specified, binary | |
- | | resource files, etc.) | |
- +------------------------+--------------------------------+---------------------------+
- | *extra_compile_args* | any extra platform- and | a list of strings |
- | | 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. | |
- +------------------------+--------------------------------+---------------------------+
- | *extra_link_args* | any extra platform- and | a list of strings |
- | | 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'. | |
- +------------------------+--------------------------------+---------------------------+
- | *export_symbols* | list of symbols to be exported | a list of strings |
- | | 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. | |
- +------------------------+--------------------------------+---------------------------+
- | *depends* | list of files that the | a list of strings |
- | | extension depends on | |
- +------------------------+--------------------------------+---------------------------+
- | *language* | extension language (i.e. | a string |
- | | ``'c'``, ``'c++'``, | |
- | | ``'objc'``). Will be detected | |
- | | from the source extensions if | |
- | | not provided. | |
- +------------------------+--------------------------------+---------------------------+
- | *optional* | specifies that a build failure | a boolean |
- | | in the extension should not | |
- | | abort the build process, but | |
- | | simply skip the extension. | |
- +------------------------+--------------------------------+---------------------------+
-
- .. versionchanged:: 3.8
-
- On Unix, C extensions are no longer linked to libpython except on
- Android and Cygwin.
-
-
-.. class:: Distribution
-
- 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.
-
- .. versionchanged:: 3.7
- :class:`~distutils.core.Distribution` now warns if ``classifiers``,
- ``keywords`` and ``platforms`` fields are not specified as a list or
- a string.
-
-.. class:: Command
-
- A :class:`Command` class (or rather, an instance of one of its subclasses)
- implement a single distutils command.
-
-
-:mod:`distutils.ccompiler` --- CCompiler base class
-===================================================
-
-.. module:: distutils.ccompiler
- :synopsis: Abstract CCompiler 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.
-
-
-.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
-
- Generate linker options for searching library directories and linking with
- specific libraries. *libraries* and *library_dirs* are, respectively, lists of
- library names (not filenames!) and search directories. Returns a list of
- command-line options suitable for use with some compiler (depending on the two
- format strings passed in).
-
-
-.. function:: gen_preprocess_options(macros, include_dirs)
-
- Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
- used by at least two types of compilers: the typical Unix compiler and Visual
- C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
- means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
- (:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of
- directory names to be added to the header file search path (:option:`!-I`).
- Returns a list of command-line options suitable for either Unix compilers or
- Visual C++.
-
-
-.. function:: get_default_compiler(osname, platform)
-
- Determine the default compiler to use for the given platform.
-
- *osname* should be one of the standard Python OS names (i.e. the ones returned
- by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
- the platform in question.
-
- The default values are ``os.name`` and ``sys.platform`` in case the parameters
- are not given.
-
-
-.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
-
- Factory function to generate an instance of some CCompiler subclass for the
- supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
- ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
- that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
- default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
- class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
- possible to ask for a Unix compiler object under Windows, and a Microsoft
- compiler object under Unix---if you supply a value for *compiler*, *plat* is
- ignored.
-
- .. % Is the posix/nt only thing still true? macOS seems to work, and
- .. % returns a UnixCCompiler instance. How to document this... hmm.
-
-
-.. function:: show_compilers()
-
- Print list of available compilers (used by the :option:`!--help-compiler` options
- to :command:`build`, :command:`build_ext`, :command:`build_clib`).
-
-
-.. class:: CCompiler([verbose=0, dry_run=0, force=0])
-
- 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.
-
-
- .. method:: CCompiler.add_include_dir(dir)
-
- Add *dir* to the list of directories that will be searched for header files.
- The compiler is instructed to search directories in the order in which they are
- supplied by successive calls to :meth:`add_include_dir`.
-
-
- .. method:: CCompiler.set_include_dirs(dirs)
-
- Set the list of directories that will be searched to *dirs* (a list of strings).
- Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
- :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
- This does not affect any list of standard include directories that the compiler
- may search by default.
-
-
- .. method:: CCompiler.add_library(libname)
-
- Add *libname* to the list of libraries that will be included in all links driven
- by this compiler object. Note that *libname* should \*not\* be the name of a
- file containing a library, but the name of the library itself: the actual
- filename will be inferred by the linker, the compiler, or the compiler class
- (depending on the platform).
-
- The linker will be instructed to link against libraries in the order they were
- supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
- valid to duplicate library names; the linker will be instructed to link against
- libraries as many times as they are mentioned.
-
-
- .. method:: CCompiler.set_libraries(libnames)
-
- Set the list of libraries to be included in all links driven by this compiler
- object to *libnames* (a list of strings). This does not affect any standard
- system libraries that the linker may include by default.
-
-
- .. method:: CCompiler.add_library_dir(dir)
-
- Add *dir* to the list of directories that will be searched for libraries
- specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
- instructed to search for libraries in the order they are supplied to
- :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
-
-
- .. method:: CCompiler.set_library_dirs(dirs)
-
- Set the list of library search directories to *dirs* (a list of strings). This
- does not affect any standard library search path that the linker may search by
- default.
-
-
- .. method:: CCompiler.add_runtime_library_dir(dir)
-
- Add *dir* to the list of directories that will be searched for shared libraries
- at runtime.
-
-
- .. method:: CCompiler.set_runtime_library_dirs(dirs)
-
- Set the list of directories to search for shared libraries at runtime to *dirs*
- (a list of strings). This does not affect any standard search path that the
- runtime linker may search by default.
-
-
- .. method:: CCompiler.define_macro(name[, value=None])
-
- Define a preprocessor macro for all compilations driven by this compiler object.
- The optional parameter *value* should be a string; if it is not supplied, then
- the macro will be defined without an explicit value and the exact outcome
- depends on the compiler used.
-
- .. XXX true? does ANSI say anything about this?
-
-
- .. method:: CCompiler.undefine_macro(name)
-
- Undefine a preprocessor macro for all compilations driven by this compiler
- object. If the same macro is defined by :meth:`define_macro` and
- undefined by :meth:`undefine_macro` the last call takes precedence
- (including multiple redefinitions or undefinitions). If the macro is
- redefined/undefined on a per-compilation basis (ie. in the call to
- :meth:`compile`), then that takes precedence.
-
-
- .. method:: CCompiler.add_link_object(object)
-
- Add *object* to the list of object files (or analogues, such as explicitly named
- library files or the output of "resource compilers") to be included in every
- link driven by this compiler object.
-
-
- .. method:: CCompiler.set_link_objects(objects)
-
- Set the list of object files (or analogues) to be included in every link to
- *objects*. This does not affect any standard object files that the linker may
- include by default (such as system libraries).
-
- The following methods implement methods for autodetection of compiler options,
- providing some functionality similar to GNU :program:`autoconf`.
-
-
- .. method:: CCompiler.detect_language(sources)
-
- Detect the language of a given file, or list of files. Uses the instance
- attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
- list) to do the job.
-
-
- .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
-
- Search the specified list of directories for a static or shared library file
- *lib* and return the full path to that file. If *debug* is true, look for a
- debugging version (if that makes sense on the current platform). Return
- ``None`` if *lib* wasn't found in any of the specified directories.
-
-
- .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
-
- Return a boolean indicating whether *funcname* is supported on the current
- platform. The optional arguments can be used to augment the compilation
- environment by providing additional include files and paths and libraries and
- paths.
-
-
- .. method:: CCompiler.library_dir_option(dir)
-
- Return the compiler option to add *dir* to the list of directories searched for
- libraries.
-
-
- .. method:: CCompiler.library_option(lib)
-
- Return the compiler option to add *lib* to the list of libraries linked into the
- shared library or executable.
-
-
- .. method:: CCompiler.runtime_library_dir_option(dir)
-
- Return the compiler option to add *dir* to the list of directories searched for
- runtime libraries.
-
-
- .. method:: CCompiler.set_executables(**args)
-
- Define the executables (and options for them) that will be run to perform the
- various stages of compilation. The exact set of executables that may be
- specified here depends on the compiler class (via the 'executables' class
- attribute), but most will have:
-
- +--------------+------------------------------------------+
- | attribute | description |
- +==============+==========================================+
- | *compiler* | the C/C++ compiler |
- +--------------+------------------------------------------+
- | *linker_so* | linker used to create shared objects and |
- | | libraries |
- +--------------+------------------------------------------+
- | *linker_exe* | linker used to create binary executables |
- +--------------+------------------------------------------+
- | *archiver* | static library creator |
- +--------------+------------------------------------------+
-
- On platforms with a command-line (Unix, DOS/Windows), each of these is a string
- that will be split into executable name and (optional) list of arguments.
- (Splitting the string is done similarly to how Unix shells operate: words are
- delimited by spaces, but quotes and backslashes can override this. See
- :func:`distutils.util.split_quoted`.)
-
- The following methods invoke stages in the build process.
-
-
- .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
-
- Compile one or more source files. Generates object files (e.g. transforms a
- :file:`.c` file to a :file:`.o` file.)
-
- *sources* must be a list of filenames, most likely C/C++ files, but in reality
- anything that can be handled by a particular compiler and compiler class (eg.
- :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
- object filenames, one per source filename in *sources*. Depending on the
- implementation, not all source files will necessarily be compiled, but all
- corresponding object filenames will be returned.
-
- If *output_dir* is given, object files will be put under it, while retaining
- their original path component. That is, :file:`foo/bar.c` normally compiles to
- :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
- it would compile to :file:`build/foo/bar.o`.
-
- *macros*, if given, must be a list of macro definitions. A macro definition is
- either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
- a macro; if the value is ``None``, the macro is defined without an explicit
- value. The 1-tuple case undefines a macro. Later
- definitions/redefinitions/undefinitions take precedence.
-
- *include_dirs*, if given, must be a list of strings, the directories to add to
- the default include file search path for this compilation only.
-
- *debug* is a boolean; if true, the compiler will be instructed to output debug
- symbols in (or alongside) the object file(s).
-
- *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
- that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
- likely lists of strings: extra command-line arguments to prepend/append to the
- compiler command line. On other platforms, consult the implementation class
- documentation. In any event, they are intended as an escape hatch for those
- occasions when the abstract compiler framework doesn't cut the mustard.
-
- *depends*, if given, is a list of filenames that all targets depend on. If a
- source file is older than any file in depends, then the source file will be
- recompiled. This supports dependency tracking, but only at a coarse
- granularity.
-
- Raises :exc:`CompileError` on failure.
-
-
- .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
-
- Link a bunch of stuff together to create a static library file. The "bunch of
- stuff" consists of the list of object files supplied as *objects*, the extra
- object files supplied to :meth:`add_link_object` and/or
- :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
- :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
-
- *output_libname* should be a library name, not a filename; the filename will be
- inferred from the library name. *output_dir* is the directory where the library
- file will be put.
-
- .. XXX defaults to what?
-
- *debug* is a boolean; if true, debugging information will be included in the
- library (note that on most platforms, it is the compile step where this matters:
- the *debug* flag is included here just for consistency).
-
- *target_lang* is the target language for which the given objects are being
- compiled. This allows specific linkage time treatment of certain languages.
-
- Raises :exc:`LibError` on failure.
-
-
- .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
-
- Link a bunch of stuff together to create an executable or shared library file.
-
- The "bunch of stuff" consists of the list of object files supplied as *objects*.
- *output_filename* should be a filename. If *output_dir* is supplied,
- *output_filename* is relative to it (i.e. *output_filename* can provide
- directory components if needed).
-
- *libraries* is a list of libraries to link against. These are library names,
- not filenames, since they're translated into filenames in a platform-specific
- way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
- DOS/Windows). However, they can include a directory component, which means the
- linker will look in that specific directory rather than searching all the normal
- locations.
-
- *library_dirs*, if supplied, should be a list of directories to search for
- libraries that were specified as bare library names (ie. no directory
- component). These are on top of the system default and those supplied to
- :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
- is a list of directories that will be embedded into the shared library and used
- to search for other shared libraries that \*it\* depends on at run-time. (This
- may only be relevant on Unix.)
-
- *export_symbols* is a list of symbols that the shared library will export.
- (This appears to be relevant only on Windows.)
-
- *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
- slight distinction that it actually matters on most platforms (as opposed to
- :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
- sake).
-
- *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
- course that they supply command-line arguments for the particular linker being
- used).
-
- *target_lang* is the target language for which the given objects are being
- compiled. This allows specific linkage time treatment of certain languages.
-
- Raises :exc:`LinkError` on failure.
-
-
- .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
-
- Link an executable. *output_progname* is the name of the file executable, while
- *objects* are a list of object filenames to link in. Other arguments are as for
- the :meth:`link` method.
-
-
- .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
-
- Link a shared library. *output_libname* is the name of the output library,
- while *objects* is a list of object filenames to link in. Other arguments are
- as for the :meth:`link` method.
-
-
- .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
-
- Link a shared object. *output_filename* is the name of the shared object that
- will be created, while *objects* is a list of object filenames to link in.
- Other arguments are as for the :meth:`link` method.
-
-
- .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
-
- Preprocess a single C/C++ source file, named in *source*. Output will be written
- to file named *output_file*, or *stdout* if *output_file* not supplied.
- *macros* is a list of macro definitions as for :meth:`compile`, which will
- augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
- *include_dirs* is a list of directory names that will be added to the default
- list, in the same way as :meth:`add_include_dir`.
-
- Raises :exc:`PreprocessError` on failure.
-
- The following utility methods are defined by the :class:`CCompiler` class, for
- use by the various concrete subclasses.
-
-
- .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
-
- Returns the filename of the executable for the given *basename*. Typically for
- non-Windows platforms this is the same as the basename, while Windows will get
- a :file:`.exe` added.
-
-
- .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
-
- Returns the filename for the given library name on the current platform. On Unix
- a library with *lib_type* of ``'static'`` will typically be of the form
- :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
- :file:`liblibname.so`.
-
-
- .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
-
- Returns the name of the object files for the given source files.
- *source_filenames* should be a list of filenames.
-
-
- .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
-
- Returns the name of a shared object file for the given file name *basename*.
-
-
- .. method:: CCompiler.execute(func, args[, msg=None, level=1])
-
- Invokes :func:`distutils.util.execute`. This method invokes a Python function
- *func* with the given arguments *args*, after logging and taking into account
- the *dry_run* flag.
-
-
- .. method:: CCompiler.spawn(cmd)
-
- Invokes :func:`distutils.util.spawn`. This invokes an external process to run
- the given command.
-
-
- .. method:: CCompiler.mkpath(name[, mode=511])
-
- Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
- missing ancestor directories.
-
-
- .. method:: CCompiler.move_file(src, dst)
-
- Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*.
-
-
- .. method:: CCompiler.announce(msg[, level=1])
-
- Write a message using :func:`distutils.log.debug`.
-
-
- .. method:: CCompiler.warn(msg)
-
- Write a warning message *msg* to standard error.
-
-
- .. method:: CCompiler.debug_print(msg)
-
- If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
- standard output, otherwise do nothing.
-
-.. % \subsection{Compiler-specific modules}
-.. %
-.. % The following modules implement concrete subclasses of the abstract
-.. % \class{CCompiler} class. They should not be instantiated directly, but should
-.. % be created using \function{distutils.ccompiler.new_compiler()} factory
-.. % function.
-
-
-:mod:`distutils.unixccompiler` --- Unix C Compiler
-==================================================
-
-.. module:: distutils.unixccompiler
- :synopsis: 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:
-
-* macros defined with :option:`!-Dname[=value]`
-
-* macros undefined with :option:`!-Uname`
-
-* include search directories specified with :option:`!-Idir`
-
-* libraries specified with :option:`!-llib`
-
-* library search directories specified with :option:`!-Ldir`
-
-* compile handled by :program:`cc` (or similar) executable with :option:`!-c`
- option: compiles :file:`.c` to :file:`.o`
-
-* link static library handled by :program:`ar` command (possibly with
- :program:`ranlib`)
-
-* link shared library handled by :program:`cc` :option:`!-shared`
-
-
-:mod:`distutils.msvccompiler` --- Microsoft Compiler
-====================================================
-
-.. module:: distutils.msvccompiler
- :synopsis: Microsoft Compiler
-
-.. XXX: This is *waaaaay* out of date!
-
-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.
-
-: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
-==================================================
-
-.. module:: distutils.bcppcompiler
-
-
-This module provides :class:`BorlandCCompiler`, a subclass of the abstract
-:class:`CCompiler` class for the Borland C++ compiler.
-
-
-:mod:`distutils.cygwincompiler` --- Cygwin Compiler
-===================================================
-
-.. module:: distutils.cygwinccompiler
-
-
-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.archive_util` --- Archiving utilities
-======================================================
-
-.. module:: distutils.archive_util
- :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
-
-
-This module provides a few functions for creating archive files, such as
-tarballs or zipfiles.
-
-
-.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
-
- Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
- the file to create, minus any format-specific extension; *format* is the
- archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or
- ``ztar``. *root_dir* is a directory that will be the root directory of the
- archive; ie. we typically ``chdir`` into *root_dir* before creating the
- archive. *base_dir* is the directory where we start archiving from; ie.
- *base_dir* will be the common prefix of all files and directories in the
- archive. *root_dir* and *base_dir* both default to the current directory.
- Returns the name of the archive file.
-
- .. versionchanged:: 3.5
- Added support for the ``xztar`` format.
-
-
-.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
-
- 'Create an (optional compressed) archive as a tar file from all files in and
- under *base_dir*. *compress* must be ``'gzip'`` (the default),
- ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``. For the ``'compress'``
- method the compression utility named by :program:`compress` must be on the
- default program search path, so this is probably Unix-specific. The output
- tar file will be named :file:`base_dir.tar`, possibly plus the appropriate
- compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the
- output filename.
-
- .. versionchanged:: 3.5
- Added support for the ``xz`` compression.
-
-
-.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
-
- Create a zip file from all files in and under *base_dir*. The output zip file
- will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python
- module (if available) or the InfoZIP :file:`zip` utility (if installed and
- found on the default search path). If neither tool is available, raises
- :exc:`DistutilsExecError`. Returns the name of the output zip file.
-
-
-:mod:`distutils.dep_util` --- Dependency checking
-=================================================
-
-.. module:: distutils.dep_util
- :synopsis: Utility functions for simple 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.
-
-
-.. function:: newer(source, target)
-
- Return true if *source* exists and is more recently modified than *target*, or
- if *source* exists and *target* doesn't. Return false if both exist and *target*
- is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
- *source* does not exist.
-
-
-.. function:: newer_pairwise(sources, targets)
-
- Walk two filename lists in parallel, testing if each source is newer than its
- corresponding target. Return a pair of lists (*sources*, *targets*) where
- source is newer than target, according to the semantics of :func:`newer`.
-
- .. % % equivalent to a listcomp...
-
-
-.. function:: newer_group(sources, target[, missing='error'])
-
- Return true if *target* is out-of-date with respect to any file listed in
- *sources*. In other words, if *target* exists and is newer than every file in
- *sources*, return false; otherwise return true. *missing* controls what we do
- when a source file is missing; the default (``'error'``) is to blow up with an
- :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
- drop any missing source files; if it is ``'newer'``, any missing source files
- make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
- it'll make you pretend to carry out commands that wouldn't work because inputs
- are missing, but that doesn't matter because you're not actually going to run
- the commands).
-
-
-:mod:`distutils.dir_util` --- Directory tree operations
-=======================================================
-
-.. module:: distutils.dir_util
- :synopsis: Utility functions for operating on directories and directory trees
-
-
-This module provides functions for operating on directories and trees of
-directories.
-
-
-.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])
-
- Create a directory and any missing ancestor directories. If the directory
- already exists (or if *name* is the empty string, which means the current
- directory, which of course exists), then do nothing. Raise
- :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
- some sub-path exists, but is a file rather than a directory). If *verbose* is
- true, print a one-line summary of each mkdir to stdout. Return the list of
- directories actually created.
-
-
-.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])
-
- Create all the empty directories under *base_dir* needed to put *files* there.
- *base_dir* is just the name of a directory which doesn't necessarily exist
- yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
- *base_dir* + the directory portion of every file in *files* will be created if
- it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
- :func:`mkpath`.
-
-
-.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
-
- Copy an entire directory tree *src* to a new location *dst*. Both *src* and
- *dst* must be directory names. If *src* is not a directory, raise
- :exc:`DistutilsFileError`. If *dst* does not exist, it is created with
- :func:`mkpath`. The end result of the copy is that every file in *src* is
- copied to *dst*, and directories under *src* are recursively copied to *dst*.
- Return the list of files that were copied or might have been copied, using their
- output name. The return value is unaffected by *update* or *dry_run*: it is
- simply the list of all files under *src*, with the names changed to be under
- *dst*.
-
- *preserve_mode* and *preserve_times* are the same as for
- :func:`distutils.file_util.copy_file`; note that they only apply to
- regular files, not to
- directories. If *preserve_symlinks* is true, symlinks will be copied as
- symlinks (on platforms that support them!); otherwise (the default), the
- destination of the symlink will be copied. *update* and *verbose* are the same
- as for :func:`copy_file`.
-
- Files in *src* that begin with :file:`.nfs` are skipped (more information on
- these files is available in answer D2 of the `NFS FAQ page
- <http://nfs.sourceforge.net/#section_d>`_).
-
- .. versionchanged:: 3.3.1
- NFS files are ignored.
-
-.. function:: remove_tree(directory[, verbose=0, dry_run=0])
-
- Recursively remove *directory* and all files and directories underneath it. Any
- errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
- true).
-
-
-:mod:`distutils.file_util` --- Single file operations
-=====================================================
-
-.. module:: distutils.file_util
- :synopsis: Utility functions for operating on single files
-
-
-This module contains some utility functions for operating on individual files.
-
-
-.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
-
- Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
- with the same name; otherwise, it must be a filename. (If the file exists, it
- will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
- file's mode (type and permission bits, or whatever is analogous on the
- current platform) is copied. If *preserve_times* is true (the default), the
- last-modified and last-access times are copied as well. If *update* is true,
- *src* will only be copied if *dst* does not exist, or if *dst* does exist but
- is older than *src*.
-
- *link* allows you to make hard links (using :func:`os.link`) or symbolic links
- (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
- ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
- on systems that don't support it: :func:`copy_file` doesn't check if hard or
- symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
- contents.
-
- Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
- output file, and *copied* is true if the file was copied (or would have been
- copied, if *dry_run* true).
-
- .. % XXX if the destination file already exists, we clobber it if
- .. % copying, but blow up if linking. Hmmm. And I don't know what
- .. % macostools.copyfile() does. Should definitely be consistent, and
- .. % should probably blow up if destination exists and we would be
- .. % changing it (ie. it's not already a hard/soft link to src OR
- .. % (not update) and (src newer than dst)).
-
-
-.. function:: move_file(src, dst[, verbose, dry_run])
-
- Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
- it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
- new full name of the file.
-
- .. warning::
-
- Handles cross-device moves on Unix using :func:`copy_file`. What about
- other systems?
-
-
-.. function:: write_file(filename, contents)
-
- Create a file called *filename* and write *contents* (a sequence of strings
- without line terminators) to it.
-
-
-:mod:`distutils.util` --- Miscellaneous other utility functions
-===============================================================
-
-.. module:: distutils.util
- :synopsis: Miscellaneous other utility functions
-
-
-This module contains other assorted bits and pieces that don't fit into any
-other utility module.
-
-
-.. function:: get_platform()
-
- Return a string that identifies the current platform. This is used mainly to
- distinguish platform-specific build directories and platform-specific built
- distributions. Typically includes the OS name and version and the
- architecture (as supplied by 'os.uname()'), although the exact information
- included depends on the OS; e.g., on Linux, the kernel version isn't
- particularly important.
-
- Examples of returned values:
-
- * ``linux-i586``
- * ``linux-alpha``
- * ``solaris-2.6-sun4u``
-
- For non-POSIX platforms, currently just returns ``sys.platform``.
-
- For macOS systems the OS version reflects the minimal version on which
- binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
- during the build of Python), not the OS version of the current system.
-
- For universal binary builds on macOS the architecture value reflects
- the universal binary status instead of the architecture of the current
- processor. For 32-bit universal binaries the architecture is ``fat``,
- for 64-bit universal binaries the architecture is ``fat64``, and
- for 4-way universal binaries the architecture is ``universal``. Starting
- from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
- a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
- a universal build with the i386 and x86_64 architectures
-
- Examples of returned values on macOS:
-
- * ``macosx-10.3-ppc``
-
- * ``macosx-10.3-fat``
-
- * ``macosx-10.5-universal``
-
- * ``macosx-10.6-intel``
-
- For AIX, Python 3.9 and later return a string starting with "aix", followed
- by additional fields (separated by ``'-'``) that represent the combined
- values of AIX Version, Release and Technology Level (first field), Build Date
- (second field), and bit-size (third field). Python 3.8 and earlier returned
- only a single additional field with the AIX Version and Release.
-
- Examples of returned values on AIX:
-
- * ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000
-
- * ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731
-
- * ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier
-
- .. versionchanged:: 3.9
- The AIX platform string format now also includes the technology level,
- build date, and ABI bit-size.
-
-
-.. function:: convert_path(pathname)
-
- Return 'pathname' as a name that will work on the native filesystem, i.e. split
- it on '/' and put it back together again using the current directory separator.
- Needed because filenames in the setup script are always supplied in Unix style,
- and have to be converted to the local convention before we can actually use them
- in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
- *pathname* either starts or ends with a slash.
-
-
-.. function:: change_root(new_root, pathname)
-
- Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
- equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
- *pathname* relative and then joining the two, which is tricky on DOS/Windows.
-
-
-.. function:: check_environ()
-
- Ensure that 'os.environ' has all the environment variables we guarantee that
- users can use in config files, command-line options, etc. Currently this
- includes:
-
- * :envvar:`HOME` - user's home directory (Unix only)
- * :envvar:`PLAT` - description of the current platform, including hardware and
- OS (see :func:`get_platform`)
-
-
-.. function:: subst_vars(s, local_vars)
-
- Perform shell/Perl-style variable substitution on *s*. Every occurrence of
- ``$`` followed by a name is considered a variable, and variable is substituted
- by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
- not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
- it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
- for any variables not found in either *local_vars* or ``os.environ``.
-
- Note that this is not a full-fledged string interpolation function. A valid
- ``$variable`` can consist only of upper and lower case letters, numbers and an
- underscore. No { } or ( ) style quoting is available.
-
-
-.. function:: split_quoted(s)
-
- Split a string up according to Unix shell-like rules for quotes and backslashes.
- In short: words are delimited by spaces, as long as those spaces are not escaped
- by a backslash, or inside a quoted string. Single and double quotes are
- equivalent, and the quote characters can be backslash-escaped. The backslash is
- stripped from any two-character escape sequence, leaving only the escaped
- character. The quote characters are stripped from any quoted string. Returns a
- list of words.
-
- .. % Should probably be moved into the standard library.
-
-
-.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
-
- Perform some action that affects the outside world (for instance, writing to the
- filesystem). Such actions are special because they are disabled by the
- *dry_run* flag. This method takes care of all that bureaucracy for you; all
- you have to do is supply the function to call and an argument tuple for it (to
- embody the "external action" being performed), and an optional message to print.
-
-
-.. function:: strtobool(val)
-
- Convert a string representation of truth to true (1) or false (0).
-
- True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
- are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
- :exc:`ValueError` if *val* is anything else.
-
-
-.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
-
- Byte-compile a collection of Python source files to :file:`.pyc` files in a
- :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`).
- *py_files* is a list of files to compile; any files that don't end in
- :file:`.py` are silently skipped. *optimize* must be one of the following:
-
- * ``0`` - don't optimize
- * ``1`` - normal optimization (like ``python -O``)
- * ``2`` - extra optimization (like ``python -OO``)
-
- If *force* is true, all files are recompiled regardless of timestamps.
-
- The source filename encoded in each :term:`bytecode` file defaults to the filenames
- listed in *py_files*; you can modify these with *prefix* and *basedir*.
- *prefix* is a string that will be stripped off of each source filename, and
- *base_dir* is a directory name that will be prepended (after *prefix* is
- stripped). You can supply either or both (or neither) of *prefix* and
- *base_dir*, as you wish.
-
- If *dry_run* is true, doesn't actually do anything that would affect the
- filesystem.
-
- Byte-compilation is either done directly in this interpreter process with the
- standard :mod:`py_compile` module, or indirectly by writing a temporary script
- and executing it. Normally, you should let :func:`byte_compile` figure out to
- use direct compilation or not (see the source for details). The *direct* flag
- is used by the script generated in indirect mode; unless you know what you're
- doing, leave it set to ``None``.
-
- .. versionchanged:: 3.2.3
- Create ``.pyc`` files with an :func:`import magic tag
- <imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory
- instead of files without tag in the current directory.
-
- .. versionchanged:: 3.5
- Create ``.pyc`` files according to :pep:`488`.
-
-
-.. function:: rfc822_escape(header)
-
- Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
- ensuring there are 8 spaces space after each newline. Note that it does no other
- modification of the string.
-
- .. % this _can_ be replaced
-
-.. % \subsection{Distutils objects}
-
-
-:mod:`distutils.dist` --- The Distribution class
-================================================
-
-.. module:: distutils.dist
- :synopsis: Provides the Distribution class, which represents the module distribution being
- built/installed/distributed
-
-
-This module provides the :class:`~distutils.core.Distribution` class, which
-represents the module distribution being built/installed/distributed.
-
-
-:mod:`distutils.extension` --- The Extension class
-==================================================
-
-.. module:: distutils.extension
- :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
- scripts
-
-
-This module provides the :class:`Extension` class, used to describe C/C++
-extension modules in setup scripts.
-
-.. % \subsection{Ungrouped modules}
-.. % The following haven't been moved into a more appropriate section yet.
-
-
-:mod:`distutils.debug` --- Distutils debug mode
-===============================================
-
-.. module:: distutils.debug
- :synopsis: Provides the debug flag for distutils
-
-
-This module provides the DEBUG flag.
-
-
-:mod:`distutils.errors` --- Distutils exceptions
-================================================
-
-.. module:: distutils.errors
- :synopsis: Provides standard 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
-===========================================================================
-
-.. module:: distutils.fancy_getopt
- :synopsis: Additional getopt functionality
-
-
-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.
-
-.. function:: fancy_getopt(options, negative_opt, object, args)
-
- Wrapper function. *options* is a list of ``(long_option, short_option,
- help_string)`` 3-tuples as described in the constructor for
- :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
- to option names, both the key and value should be in the *options* list.
- *object* is an object which will be used to store values (see the :meth:`getopt`
- method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
- ``sys.argv[1:]`` if you pass ``None`` as *args*.
-
-
-.. function:: wrap_text(text, width)
-
- Wraps *text* to less than *width* wide.
-
-
-.. class:: FancyGetopt([option_table=None])
-
- 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:
-
-
-.. method:: FancyGetopt.getopt([args=None, object=None])
-
- Parse command-line options in args. Store as attributes on *object*.
-
- If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
- ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
- option values there, and returns a tuple ``(args, object)``. If *object* is
- supplied, it is modified in place and :func:`getopt` just returns *args*; in
- both cases, the returned *args* is a modified copy of the passed-in *args* list,
- which is left untouched.
-
- .. % and args returned are?
-
-
-.. method:: FancyGetopt.get_option_order()
-
- Returns the list of ``(option, value)`` tuples processed by the previous run of
- :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
- yet.
-
-
-.. method:: FancyGetopt.generate_help([header=None])
-
- Generate help text (a list of strings, one per suggested line of output) from
- the option table for this :class:`FancyGetopt` object.
-
- If supplied, prints the supplied *header* at the top of the help.
-
-
-:mod:`distutils.filelist` --- The FileList class
-================================================
-
-.. module:: distutils.filelist
- :synopsis: The FileList class, used for poking about the file system and
- building lists of files.
-
-
-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
-========================================================
-
-.. module:: distutils.log
- :synopsis: A simple logging mechanism, :pep:`282`-style
-
-
-:mod:`distutils.spawn` --- Spawn a sub-process
-==============================================
-
-.. module:: distutils.spawn
- :synopsis: Provides the spawn() function
-
-
-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
-===============================================================
-
-.. module:: distutils.sysconfig
- :synopsis: Low-level access to configuration information of the Python interpreter.
-.. deprecated:: 3.10
- :mod:`distutils.sysconfig` has been merged into :mod:`sysconfig`.
-.. moduleauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
-.. moduleauthor:: Greg Ward <gward at python.net>
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
-
-
-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.
-
-
-.. data:: PREFIX
-
- The result of ``os.path.normpath(sys.prefix)``.
-
-
-.. data:: EXEC_PREFIX
-
- The result of ``os.path.normpath(sys.exec_prefix)``.
-
-
-.. function:: get_config_var(name)
-
- Return the value of a single variable. This is equivalent to
- ``get_config_vars().get(name)``.
-
-
-.. function:: get_config_vars(...)
-
- Return a set of variable definitions. If there are no arguments, this returns a
- dictionary mapping names of configuration variables to values. If arguments are
- provided, they should be strings, and the return value will be a sequence giving
- the associated values. If a given name does not have a corresponding value,
- ``None`` will be included for that variable.
-
-
-.. function:: get_config_h_filename()
-
- Return the full path name of the configuration header. For Unix, this will be
- the header generated by the :program:`configure` script; for other platforms the
- header will have been supplied directly by the Python source distribution. The
- file is a platform-specific text file.
-
-
-.. function:: get_makefile_filename()
-
- Return the full path name of the :file:`Makefile` used to build Python. For
- Unix, this will be a file generated by the :program:`configure` script; the
- meaning for other platforms will vary. The file is a platform-specific text
- file, if it exists. This function is only useful on POSIX platforms.
-
-The following functions are deprecated together with this module and they
-have no direct replacement.
-
-
-.. function:: get_python_inc([plat_specific[, prefix]])
-
- Return the directory for either the general or platform-dependent C include
- files. If *plat_specific* is true, the platform-dependent include directory is
- returned; if false or omitted, the platform-independent directory is returned.
- If *prefix* is given, it is used as either the prefix instead of
- :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
- *plat_specific* is true.
-
-
-.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
-
- Return the directory for either the general or platform-dependent library
- installation. If *plat_specific* is true, the platform-dependent include
- directory is returned; if false or omitted, the platform-independent directory
- is returned. If *prefix* is given, it is used as either the prefix instead of
- :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
- *plat_specific* is true. If *standard_lib* is true, the directory for the
- standard library is returned rather than the directory for the installation of
- third-party extensions.
-
-The following function is only intended for use within the :mod:`distutils`
-package.
-
-
-.. function:: customize_compiler(compiler)
-
- Do any platform-specific customization of a
- :class:`distutils.ccompiler.CCompiler` instance.
-
- This function is only needed on Unix at this time, but should be called
- consistently to support forward-compatibility. It inserts the information that
- varies across Unix flavors and is stored in Python's :file:`Makefile`. This
- information includes the selected compiler, compiler and linker options, and the
- extension used by the linker for shared objects.
-
-This function is even more special-purpose, and should only be used from
-Python's own build procedures.
-
-
-.. function:: set_python_build()
-
- Inform the :mod:`distutils.sysconfig` module that it is being used as part of
- the build process for Python. This changes a lot of relative locations for
- files, allowing them to be located in the build area rather than in an installed
- Python.
-
-
-:mod:`distutils.text_file` --- The TextFile class
-=================================================
-
-.. module:: distutils.text_file
- :synopsis: Provides the TextFile class, a simple interface to text files
-
-
-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.
-
-
-.. class:: TextFile([filename=None, file=None, **options])
-
- 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`
-
- .. tabularcolumns:: |l|L|l|
-
- +------------------+--------------------------------+---------+
- | option name | description | default |
- +==================+================================+=========+
- | *strip_comments* | strip from ``'#'`` to | true |
- | | end-of-line, as well as any | |
- | | whitespace leading up to the | |
- | | ``'#'``\ ---unless it is | |
- | | escaped by a backslash | |
- +------------------+--------------------------------+---------+
- | *lstrip_ws* | strip leading whitespace from | false |
- | | each line before returning it | |
- +------------------+--------------------------------+---------+
- | *rstrip_ws* | strip trailing whitespace | true |
- | | (including line terminator!) | |
- | | from each line before | |
- | | returning it. | |
- +------------------+--------------------------------+---------+
- | *skip_blanks* | skip lines that are empty | true |
- | | \*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.) | |
- +------------------+--------------------------------+---------+
- | *join_lines* | if a backslash is the last | false |
- | | 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. | |
- +------------------+--------------------------------+---------+
- | *collapse_join* | strip leading whitespace from | false |
- | | lines that are joined to their | |
- | | predecessor; only matters if | |
- | | ``(join_lines and not | |
- | | lstrip_ws)`` | |
- +------------------+--------------------------------+---------+
-
- 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.
-
-
- .. method:: TextFile.open(filename)
-
- Open a new file *filename*. This overrides any *file* or *filename*
- constructor arguments.
-
-
- .. method:: TextFile.close()
-
- Close the current file and forget everything we know about it (including the
- filename and the current line number).
-
-
- .. method:: TextFile.warn(msg[,line=None])
-
- Print (to stderr) a warning message tied to the current logical line in the
- current file. If the current logical line in the file spans multiple physical
- lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
- *line* is supplied, it overrides the current line number; it may be a list or
- tuple to indicate a range of physical lines, or an integer for a single
- physical line.
-
-
- .. method:: TextFile.readline()
-
- Read and return a single logical line from the current file (or from an internal
- buffer if lines have previously been "unread" with :meth:`unreadline`). If the
- *join_lines* option is true, this may involve reading multiple physical lines
- concatenated into a single string. Updates the current line number, so calling
- :meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
- just read. Returns ``None`` on end-of-file, since the empty string can occur
- if *rstrip_ws* is true but *strip_blanks* is not.
-
-
- .. method:: TextFile.readlines()
-
- Read and return the list of all logical lines remaining in the current file.
- This updates the current line number to the last line of the file.
-
-
- .. method:: TextFile.unreadline(line)
-
- Push *line* (a string) onto an internal buffer that will be checked by future
- :meth:`readline` calls. Handy for implementing a parser with line-at-a-time
- lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
- subsequently re-cleansed (whitespace stripped, or whatever) when read with
- :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
- to :meth:`readline`, the lines will be returned most in most recent first order.
-
-
-:mod:`distutils.version` --- Version number classes
-===================================================
-
-.. module:: distutils.version
- :synopsis: Implements classes that represent module version numbers.
-
-
-.. % todo
-.. % \section{Distutils Commands}
-.. %
-.. % This part of Distutils implements the various Distutils commands, such
-.. % as \code{build}, \code{install} \&c. Each command is implemented as a
-.. % separate module, with the command name as the name of the module.
-
-
-:mod:`distutils.cmd` --- Abstract base class for Distutils commands
-===================================================================
-
-.. module:: distutils.cmd
- :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class
- is subclassed by the modules in the distutils.command subpackage.
-
-
-This module supplies the abstract base class :class:`Command`.
-
-
-.. class:: Command(dist)
-
- 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:`~distutils.core.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 ``setup.py peel_banana``), you'd copy
-:file:`command_template` to :file:`distutils/command/peel_banana.py`, 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.
-
-.. method:: Command.initialize_options()
-
- Set default values for all the options that this command supports. Note that
- these defaults may be overridden by other commands, by the setup script, by
- config files, or by the command-line. Thus, this is not the place to code
- dependencies between options; generally, :meth:`initialize_options`
- implementations are just a bunch of ``self.foo = None`` assignments.
-
-
-.. method:: Command.finalize_options()
-
- Set final values for all the options that this command supports. This is
- always called as late as possible, ie. after any option assignments from the
- command-line or from other commands have been done. Thus, this is the place
- to code option dependencies: if *foo* depends on *bar*, then it is safe to
- set *foo* from *bar* as long as *foo* still has the same value it was
- assigned in :meth:`initialize_options`.
-
-
-.. method:: Command.run()
-
- A command's raison d'etre: carry out the action it exists to perform, controlled
- by the options initialized in :meth:`initialize_options`, customized by other
- commands, the setup script, the command-line, and config files, and finalized in
- :meth:`finalize_options`. All terminal output and filesystem interaction should
- be done by :meth:`run`.
-
-
-.. attribute:: Command.sub_commands
-
- *sub_commands* formalizes the notion of a "family" of commands,
- e.g. ``install`` as the parent with sub-commands ``install_lib``,
- ``install_headers``, etc. The parent of a family of commands defines
- *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
- predicate)``, with *command_name* a string and *predicate* a function, a
- string or ``None``. *predicate* is a method of the parent command that
- determines whether the corresponding command is applicable in the current
- situation. (E.g. ``install_headers`` is only applicable if we have any C
- header files to install.) If *predicate* is ``None``, that command is always
- applicable.
-
- *sub_commands* is usually defined at the *end* of a class, because
- predicates can be methods of the class, so they must already have been
- defined. The canonical example is the :command:`install` command.
-
-
-:mod:`distutils.command` --- Individual Distutils commands
-==========================================================
-
-.. module:: distutils.command
- :synopsis: Contains one module for each standard Distutils command.
-
-
-.. % \subsubsection{Individual Distutils commands}
-.. % todo
-
-
-:mod:`distutils.command.bdist` --- Build a binary installer
-===========================================================
-
-.. module:: distutils.command.bdist
- :synopsis: Build a binary installer for a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
-=============================================================================
-
-.. module:: distutils.command.bdist_packager
- :synopsis: Abstract base class for packagers
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
-================================================================
-
-.. module:: distutils.command.bdist_dumb
- :synopsis: Build a "dumb" installer - a simple archive of files
-
-
-.. % todo
-
-
-:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
-===========================================================================================
-
-.. module:: distutils.command.bdist_rpm
- :synopsis: Build a binary distribution as a Redhat RPM and SRPM
-
-
-.. % todo
-
-
-:mod:`distutils.command.sdist` --- Build a source distribution
-==============================================================
-
-.. module:: distutils.command.sdist
- :synopsis: Build a source distribution
-
-
-.. % todo
-
-
-:mod:`distutils.command.build` --- Build all files of a package
-===============================================================
-
-.. module:: distutils.command.build
- :synopsis: Build all files of a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_clib` --- Build any C libraries in a package
-==========================================================================
-
-.. module:: distutils.command.build_clib
- :synopsis: Build any C libraries in a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_ext` --- Build any extensions in a package
-========================================================================
-
-.. module:: distutils.command.build_ext
- :synopsis: Build any extensions in a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
-===========================================================================
-
-.. module:: distutils.command.build_py
- :synopsis: Build the .py/.pyc files of a package
-
-
-.. class:: build_py
-
-.. class:: build_py_2to3
-
- 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 setup.py file for a distribution
- that is designed to run with both Python 2.x and 3.x, add::
-
- try:
- from distutils.command.build_py import build_py_2to3 as build_py
- except ImportError:
- from distutils.command.build_py import build_py
-
- to your setup.py, and later::
-
- cmdclass = {'build_py': build_py}
-
- to the invocation of setup().
-
-
-:mod:`distutils.command.build_scripts` --- Build the scripts of a package
-=========================================================================
-
-.. module:: distutils.command.build_scripts
- :synopsis: Build the scripts of a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.clean` --- Clean a package build area
-=============================================================
-
-.. module:: distutils.command.clean
- :synopsis: Clean a package build area
-
-This command removes the temporary files created by :command:`build`
-and its subcommands, like intermediary compiled object files. With
-the ``--all`` option, the complete build directory will be removed.
-
-Extension modules built :ref:`in place <distutils-build-ext-inplace>`
-will not be cleaned, as they are not in the build directory.
-
-
-:mod:`distutils.command.config` --- Perform package configuration
-=================================================================
-
-.. module:: distutils.command.config
- :synopsis: Perform package configuration
-
-
-.. % todo
-
-
-:mod:`distutils.command.install` --- Install a package
-======================================================
-
-.. module:: distutils.command.install
- :synopsis: Install a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_data` --- Install data files from a package
-===========================================================================
-
-.. module:: distutils.command.install_data
- :synopsis: Install data files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
-======================================================================================
-
-.. module:: distutils.command.install_headers
- :synopsis: Install C/C++ header files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_lib` --- Install library files from a package
-=============================================================================
-
-.. module:: distutils.command.install_lib
- :synopsis: Install library files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.install_scripts` --- Install script files from a package
-================================================================================
-
-.. module:: distutils.command.install_scripts
- :synopsis: Install script files from a package
-
-
-.. % todo
-
-
-:mod:`distutils.command.register` --- Register a module with the Python Package Index
-=====================================================================================
-
-.. module:: distutils.command.register
- :synopsis: 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`.
-
-.. % todo
-
-
-:mod:`distutils.command.check` --- Check the meta-data of a package
-===================================================================
-
-.. module:: distutils.command.check
- :synopsis: 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.
-
-.. % todo
diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst
deleted file mode 100644
index c1d9ea533dab6..0000000000000
--- a/Doc/distutils/builtdist.rst
+++ /dev/null
@@ -1,392 +0,0 @@
-.. _built-dist:
-
-****************************
-Creating Built Distributions
-****************************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-A "built distribution" is what you're probably used to thinking of either as a
-"binary package" or an "installer" (depending on your background). It's not
-necessarily binary, though, because it might contain only Python source code
-and/or byte-code; and we don't call it a package, because that word is already
-spoken for in Python. (And "installer" is a term specific to the world of
-mainstream desktop systems.)
-
-A built distribution is how you make life as easy as possible for installers of
-your module distribution: for users of RPM-based Linux systems, it's a binary
-RPM; for Windows users, it's an executable installer; for Debian-based Linux
-users, it's a Debian package; and so forth. Obviously, no one person will be
-able to create built distributions for every platform under the sun, so the
-Distutils are designed to enable module developers to concentrate on their
-specialty---writing code and creating source distributions---while an
-intermediary species called *packagers* springs up to turn source distributions
-into built distributions for as many platforms as there are packagers.
-
-Of course, the module developer could be their own packager; or the packager could
-be a volunteer "out there" somewhere who has access to a platform which the
-original developer does not; or it could be software periodically grabbing new
-source distributions and turning them into built distributions for as many
-platforms as the software has access to. Regardless of who they are, a packager
-uses the setup script and the :command:`bdist` command family to generate built
-distributions.
-
-As a simple example, if I run the following command in the Distutils source
-tree::
-
- python setup.py bdist
-
-then the Distutils builds my module distribution (the Distutils itself in this
-case), does a "fake" installation (also in the :file:`build` directory), and
-creates the default type of built distribution for my platform. The default
-format for built distributions is a "dumb" tar file on Unix, and a simple
-executable installer on Windows. (That tar file is considered "dumb" because it
-has to be unpacked in a specific location to work.)
-
-Thus, the above command on a Unix system creates
-:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
-installs the Distutils just as though you had downloaded the source distribution
-and run ``python setup.py install``. (The "right place" is either the root of
-the filesystem or Python's :file:`{prefix}` directory, depending on the options
-given to the :command:`bdist_dumb` command; the default is to make dumb
-distributions relative to :file:`{prefix}`.)
-
-Obviously, for pure Python distributions, this isn't any simpler than just
-running ``python setup.py install``\ ---but for non-pure distributions, which
-include extensions that would need to be compiled, it can mean the difference
-between someone being able to use your extensions or not. And creating "smart"
-built distributions, such as an RPM package or an executable installer for
-Windows, is far more convenient for users even if your distribution doesn't
-include any extensions.
-
-The :command:`bdist` command has a :option:`!--formats` option, similar to the
-:command:`sdist` command, which you can use to select the types of built
-distribution to generate: for example, ::
-
- python setup.py bdist --format=zip
-
-would, when run on a Unix system, create
-:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked
-from the root directory to install the Distutils.
-
-The available formats for built distributions are:
-
-+-------------+------------------------------+---------+
-| Format | Description | Notes |
-+=============+==============================+=========+
-| ``gztar`` | gzipped tar file | \(1) |
-| | (:file:`.tar.gz`) | |
-+-------------+------------------------------+---------+
-| ``bztar`` | bzipped tar file | |
-| | (:file:`.tar.bz2`) | |
-+-------------+------------------------------+---------+
-| ``xztar`` | xzipped tar file | |
-| | (:file:`.tar.xz`) | |
-+-------------+------------------------------+---------+
-| ``ztar`` | compressed tar file | \(3) |
-| | (:file:`.tar.Z`) | |
-+-------------+------------------------------+---------+
-| ``tar`` | tar file (:file:`.tar`) | |
-+-------------+------------------------------+---------+
-| ``zip`` | zip file (:file:`.zip`) | (2),(4) |
-+-------------+------------------------------+---------+
-| ``rpm`` | RPM | \(5) |
-+-------------+------------------------------+---------+
-| ``pkgtool`` | Solaris :program:`pkgtool` | |
-+-------------+------------------------------+---------+
-| ``sdux`` | HP-UX :program:`swinstall` | |
-+-------------+------------------------------+---------+
-| ``msi`` | Microsoft Installer. | |
-+-------------+------------------------------+---------+
-
-.. versionchanged:: 3.5
- Added support for the ``xztar`` format.
-
-
-Notes:
-
-(1)
- default on Unix
-
-(2)
- default on Windows
-
-(3)
- requires external :program:`compress` utility.
-
-(4)
- requires either external :program:`zip` utility or :mod:`zipfile` module (part
- of the standard Python library since Python 1.6)
-
-(5)
- requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
- --version`` to find out which version you have)
-
-You don't have to use the :command:`bdist` command with the :option:`!--formats`
-option; you can also use the command that directly implements the format you're
-interested in. Some of these :command:`bdist` "sub-commands" actually generate
-several similar formats; for instance, the :command:`bdist_dumb` command
-generates all the "dumb" archive formats (``tar``, ``gztar``, ``bztar``,
-``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both
-binary and source RPMs. The :command:`bdist` sub-commands, and the formats
-generated by each, are:
-
-+--------------------------+-------------------------------------+
-| Command | Formats |
-+==========================+=====================================+
-| :command:`bdist_dumb` | tar, gztar, bztar, xztar, ztar, zip |
-+--------------------------+-------------------------------------+
-| :command:`bdist_rpm` | rpm, srpm |
-+--------------------------+-------------------------------------+
-
-The following sections give details on the individual :command:`bdist_\*`
-commands.
-
-
-.. .. _creating-dumb:
-
-.. Creating dumb built distributions
-.. =================================
-
-.. XXX Need to document absolute vs. prefix-relative packages here, but first
- I have to implement it!
-
-
-.. _creating-rpms:
-
-Creating RPM packages
-=====================
-
-The RPM format is used by many popular Linux distributions, including Red Hat,
-SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
-distributions) is your usual environment, creating RPM packages for other users
-of that same distribution is trivial. Depending on the complexity of your module
-distribution and differences between Linux distributions, you may also be able
-to create RPMs that work on different RPM-based distributions.
-
-The usual way to create an RPM of your module distribution is to run the
-:command:`bdist_rpm` command::
-
- python setup.py bdist_rpm
-
-or the :command:`bdist` command with the :option:`!--format` option::
-
- python setup.py bdist --formats=rpm
-
-The former allows you to specify RPM-specific options; the latter allows you to
-easily specify multiple formats in one run. If you need to do both, you can
-explicitly specify multiple :command:`bdist_\*` commands and their options::
-
- python setup.py bdist_rpm --packager="John Doe <jdoe at example.org>"
-
-Creating RPM packages is driven by a :file:`.spec` file, much as using the
-Distutils is driven by the setup script. To make your life easier, the
-:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
-information you supply in the setup script, on the command line, and in any
-Distutils configuration files. Various options and sections in the
-:file:`.spec` file are derived from options in the setup script as follows:
-
-+------------------------------------------+----------------------------------------------+
-| RPM :file:`.spec` file option or section | Distutils setup script option |
-+==========================================+==============================================+
-| Name | ``name`` |
-+------------------------------------------+----------------------------------------------+
-| Summary (in preamble) | ``description`` |
-+------------------------------------------+----------------------------------------------+
-| Version | ``version`` |
-+------------------------------------------+----------------------------------------------+
-| Vendor | ``author`` and ``author_email``, |
-| | or --- & ``maintainer`` and |
-| | ``maintainer_email`` |
-+------------------------------------------+----------------------------------------------+
-| Copyright | ``license`` |
-+------------------------------------------+----------------------------------------------+
-| Url | ``url`` |
-+------------------------------------------+----------------------------------------------+
-| %description (section) | ``long_description`` |
-+------------------------------------------+----------------------------------------------+
-
-Additionally, there are many options in :file:`.spec` files that don't have
-corresponding options in the setup script. Most of these are handled through
-options to the :command:`bdist_rpm` command as follows:
-
-+-------------------------------+-----------------------------+-------------------------+
-| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value |
-| or section | | |
-+===============================+=============================+=========================+
-| Release | ``release`` | "1" |
-+-------------------------------+-----------------------------+-------------------------+
-| Group | ``group`` | "Development/Libraries" |
-+-------------------------------+-----------------------------+-------------------------+
-| Vendor | ``vendor`` | (see above) |
-+-------------------------------+-----------------------------+-------------------------+
-| Packager | ``packager`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Provides | ``provides`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Requires | ``requires`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Conflicts | ``conflicts`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Obsoletes | ``obsoletes`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Distribution | ``distribution_name`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| BuildRequires | ``build_requires`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-| Icon | ``icon`` | (none) |
-+-------------------------------+-----------------------------+-------------------------+
-
-Obviously, supplying even a few of these options on the command-line would be
-tedious and error-prone, so it's usually best to put them in the setup
-configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
-you distribute or package many Python module distributions, you might want to
-put options that apply to all of them in your personal Distutils configuration
-file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable
-this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`.
-
-There are three steps to building a binary RPM package, all of which are
-handled automatically by the Distutils:
-
-#. create a :file:`.spec` file, which describes the package (analogous to the
- Distutils setup script; in fact, much of the information in the setup script
- winds up in the :file:`.spec` file)
-
-#. create the source RPM
-
-#. create the "binary" RPM (which may or may not contain binary code, depending
- on whether your module distribution contains Python extensions)
-
-Normally, RPM bundles the last two steps together; when you use the Distutils,
-all three steps are typically bundled together.
-
-If you wish, you can separate these three steps. You can use the
-:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
-:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
-written to the "distribution directory"---normally :file:`dist/`, but
-customizable with the :option:`!--dist-dir` option. (Normally, the :file:`.spec`
-file winds up deep in the "build tree," in a temporary directory created by
-:command:`bdist_rpm`.)
-
-.. % \XXX{this isn't implemented yet---is it needed?!}
-.. % You can also specify a custom \file{.spec} file with the
-.. % \longprogramopt{spec-file} option; used in conjunction with
-.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
-.. % the \file{.spec} file manually:
-.. %
-.. % \ begin{verbatim}
-.. % > python setup.py bdist_rpm --spec-only
-.. % # ...edit dist/FooBar-1.0.spec
-.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
-.. % \ end{verbatim}
-.. %
-.. % (Although a better way to do this is probably to override the standard
-.. % \command{bdist\_rpm} command with one that writes whatever else you want
-.. % to the \file{.spec} file.)
-
-
-.. _cross-compile-windows:
-
-Cross-compiling on Windows
-==========================
-
-Starting with Python 2.6, distutils is capable of cross-compiling between
-Windows platforms. In practice, this means that with the correct tools
-installed, you can use a 32bit version of Windows to create 64bit extensions
-and vice-versa.
-
-To build for an alternate platform, specify the :option:`!--plat-name` option
-to the build command. Valid values are currently 'win32', and 'win-amd64'.
-For example, on a 32bit version of Windows, you could execute::
-
- python setup.py build --plat-name=win-amd64
-
-to build a 64bit version of your extension.
-
-would create a 64bit installation executable on your 32bit version of Windows.
-
-To cross-compile, you must download the Python source code and cross-compile
-Python itself for the platform you are targeting - it is not possible from a
-binary installation of Python (as the .lib etc file for other platforms are
-not included.) In practice, this means the user of a 32 bit operating
-system will need to use Visual Studio 2008 to open the
-:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the
-"x64" configuration of the 'pythoncore' project before cross-compiling
-extensions is possible.
-
-Note that by default, Visual Studio 2008 does not install 64bit compilers or
-tools. You may need to reexecute the Visual Studio setup process and select
-these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
-check or modify your existing install.)
-
-.. _postinstallation-script:
-
-The Postinstallation script
----------------------------
-
-Starting with Python 2.3, a postinstallation script can be specified with the
-:option:`!--install-script` option. The basename of the script must be
-specified, and the script filename must also be listed in the scripts argument
-to the setup function.
-
-This script will be run at installation time on the target system after all the
-files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
-uninstallation time before the files are removed with ``argv[1]`` set to
-:option:`!-remove`.
-
-The installation script runs embedded in the windows installer, every output
-(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
-displayed in the GUI after the script has finished.
-
-Some functions especially useful in this context are available as additional
-built-in functions in the installation script.
-
-
-.. function:: directory_created(path)
- file_created(path)
-
- These functions should be called when a directory or file is created by the
- postinstall script at installation time. It will register *path* with the
- uninstaller, so that it will be removed when the distribution is uninstalled.
- To be safe, directories are only removed if they are empty.
-
-
-.. function:: get_special_folder_path(csidl_string)
-
- This function can be used to retrieve special folder locations on Windows like
- the Start Menu or the Desktop. It returns the full path to the folder.
- *csidl_string* must be one of the following strings::
-
- "CSIDL_APPDATA"
-
- "CSIDL_COMMON_STARTMENU"
- "CSIDL_STARTMENU"
-
- "CSIDL_COMMON_DESKTOPDIRECTORY"
- "CSIDL_DESKTOPDIRECTORY"
-
- "CSIDL_COMMON_STARTUP"
- "CSIDL_STARTUP"
-
- "CSIDL_COMMON_PROGRAMS"
- "CSIDL_PROGRAMS"
-
- "CSIDL_FONTS"
-
- If the folder cannot be retrieved, :exc:`OSError` is raised.
-
- Which folders are available depends on the exact Windows version, and probably
- also the configuration. For details refer to Microsoft's documentation of the
- :c:func:`SHGetSpecialFolderPath` function.
-
-
-.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])
-
- This function creates a shortcut. *target* is the path to the program to be
- started by the shortcut. *description* is the description of the shortcut.
- *filename* is the title of the shortcut that the user will see. *arguments*
- specifies the command line arguments, if any. *workdir* is the working directory
- for the program. *iconpath* is the file containing the icon for the shortcut,
- and *iconindex* is the index of the icon in the file *iconpath*. Again, for
- details consult the Microsoft documentation for the :class:`IShellLink`
- interface.
diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst
deleted file mode 100644
index 3e247e68d3a05..0000000000000
--- a/Doc/distutils/commandref.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-.. _reference:
-
-*****************
-Command Reference
-*****************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-.. % \section{Building modules: the \protect\command{build} command family}
-.. % \label{build-cmds}
-.. % \subsubsection{\protect\command{build}}
-.. % \label{build-cmd}
-.. % \subsubsection{\protect\command{build\_py}}
-.. % \label{build-py-cmd}
-.. % \subsubsection{\protect\command{build\_ext}}
-.. % \label{build-ext-cmd}
-.. % \subsubsection{\protect\command{build\_clib}}
-.. % \label{build-clib-cmd}
-
-
-.. _install-cmd:
-
-Installing modules: the :command:`install` command family
-=========================================================
-
-The install command ensures that the build commands have been run and then runs
-the subcommands :command:`install_lib`, :command:`install_data` and
-:command:`install_scripts`.
-
-.. % \subsubsection{\protect\command{install\_lib}}
-.. % \label{install-lib-cmd}
-
-
-.. _install-data-cmd:
-
-:command:`install_data`
------------------------
-
-This command installs all data files provided with the distribution.
-
-
-.. _install-scripts-cmd:
-
-:command:`install_scripts`
---------------------------
-
-This command installs all (Python) scripts in the distribution.
-
-.. % \subsection{Cleaning up: the \protect\command{clean} command}
-.. % \label{clean-cmd}
-
-
-.. _sdist-cmd:
-
-Creating a source distribution: the :command:`sdist` command
-============================================================
-
-.. XXX fragment moved down from above: needs context!
-
-The manifest template commands are:
-
-+-------------------------------------------+-----------------------------------------------+
-| Command | Description |
-+===========================================+===============================================+
-| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
-| | patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
-| | patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
-| ...` | the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
-| ...` | the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
-| | matching --- & any of the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
-| | matching --- & any of the listed patterns |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`prune dir` | exclude all files under *dir* |
-+-------------------------------------------+-----------------------------------------------+
-| :command:`graft dir` | include all files under *dir* |
-+-------------------------------------------+-----------------------------------------------+
-
-The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
-regular filename characters, ``?`` matches any single regular filename
-character, and ``[range]`` matches any of the characters in *range* (e.g.,
-``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
-character" is platform-specific: on Unix it is anything except slash; on Windows
-anything except backslash or colon.
-
-.. XXX Windows support not there yet
-
-.. % \section{Creating a built distribution: the
-.. % \protect\command{bdist} command family}
-.. % \label{bdist-cmds}
-
-.. % \subsection{\protect\command{bdist}}
-.. % \subsection{\protect\command{bdist\_dumb}}
-.. % \subsection{\protect\command{bdist\_rpm}}
-
-
diff --git a/Doc/distutils/configfile.rst b/Doc/distutils/configfile.rst
deleted file mode 100644
index 2a5c8329e318b..0000000000000
--- a/Doc/distutils/configfile.rst
+++ /dev/null
@@ -1,144 +0,0 @@
-.. _setup-config:
-
-************************************
-Writing the Setup Configuration File
-************************************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-Often, it's not possible to write down everything needed to build a distribution
-*a priori*: you may need to get some information from the user, or from the
-user's system, in order to proceed. As long as that information is fairly
-simple---a list of directories to search for C header files or libraries, for
-example---then providing a configuration file, :file:`setup.cfg`, for users to
-edit is a cheap and easy way to solicit it. Configuration files also let you
-provide default values for any command option, which the installer can then
-override either on the command-line or by editing the config file.
-
-The setup configuration file is a useful middle-ground between the setup
-script---which, ideally, would be opaque to installers [#]_---and the command-line to
-the setup script, which is outside of your control and entirely up to the
-installer. In fact, :file:`setup.cfg` (and any other Distutils configuration
-files present on the target system) are processed after the contents of the
-setup script, but before the command-line. This has several useful
-consequences:
-
-.. % (If you have more advanced needs, such as determining which extensions
-.. % to build based on what capabilities are present on the target system,
-.. % then you need the Distutils ``auto-configuration'' facility. This
-.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
-.. % or stable enough yet for real-world use.)
-
-* installers can override some of what you put in :file:`setup.py` by editing
- :file:`setup.cfg`
-
-* you can provide non-standard defaults for options that are not easily set in
- :file:`setup.py`
-
-* installers can override anything in :file:`setup.cfg` using the command-line
- options to :file:`setup.py`
-
-The basic syntax of the configuration file is simple:
-
-.. code-block:: ini
-
- [command]
- option=value
- ...
-
-where *command* is one of the Distutils commands (e.g. :command:`build_py`,
-:command:`install`), and *option* is one of the options that command supports.
-Any number of options can be supplied for each command, and any number of
-command sections can be included in the file. Blank lines are ignored, as are
-comments, which run from a ``'#'`` character until the end of the line. Long
-option values can be split across multiple lines simply by indenting the
-continuation lines.
-
-You can find out the list of options supported by a particular command with the
-universal :option:`!--help` option, e.g.
-
-.. code-block:: shell-session
-
- $ python setup.py --help build_ext
- [...]
- Options for 'build_ext' command:
- --build-lib (-b) directory for compiled extension modules
- --build-temp (-t) directory for temporary files (build by-products)
- --inplace (-i) ignore build-lib and put compiled extensions into the
- source directory alongside your pure Python modules
- --include-dirs (-I) list of directories to search for header files
- --define (-D) C preprocessor macros to define
- --undef (-U) C preprocessor macros to undefine
- --swig-opts list of SWIG command line options
- [...]
-
-Note that an option spelled :option:`!--foo-bar` on the command-line is spelled
-``foo_bar`` in configuration files.
-
-.. _distutils-build-ext-inplace:
-
-For example, say you want your extensions to be built "in-place"---that is, you
-have an extension :mod:`pkg.ext`, and you want the compiled extension file
-(:file:`ext.so` on Unix, say) to be put in the same source directory as your
-pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the
-:option:`!--inplace` option on the command-line to ensure this:
-
-.. code-block:: sh
-
- python setup.py build_ext --inplace
-
-But this requires that you always specify the :command:`build_ext` command
-explicitly, and remember to provide :option:`!--inplace`. An easier way is to
-"set and forget" this option, by encoding it in :file:`setup.cfg`, the
-configuration file for this distribution:
-
-.. code-block:: ini
-
- [build_ext]
- inplace=1
-
-This will affect all builds of this module distribution, whether or not you
-explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in
-your source distribution, it will also affect end-user builds---which is
-probably a bad idea for this option, since always building extensions in-place
-would break installation of the module distribution. In certain peculiar cases,
-though, modules are built right in their installation directory, so this is
-conceivably a useful ability. (Distributing extensions that expect to be built
-in their installation directory is almost always a bad idea, though.)
-
-Another example: certain commands take a lot of options that don't change from
-run to run; for example, :command:`bdist_rpm` needs to know everything required
-to generate a "spec" file for creating an RPM distribution. Some of this
-information comes from the setup script, and some is automatically generated by
-the Distutils (such as the list of files installed). But some of it has to be
-supplied as options to :command:`bdist_rpm`, which would be very tedious to do
-on the command-line for every run. Hence, here is a snippet from the Distutils'
-own :file:`setup.cfg`:
-
-.. code-block:: ini
-
- [bdist_rpm]
- release = 1
- packager = Greg Ward <gward at python.net>
- doc_files = CHANGES.txt
- README.txt
- USAGE.txt
- doc/
- examples/
-
-Note that the ``doc_files`` option is simply a whitespace-separated string
-split across multiple lines for readability.
-
-
-.. seealso::
-
- :ref:`inst-config-syntax` in "Installing Python Modules"
- More information on the configuration files is available in the manual for
- system administrators.
-
-
-.. rubric:: Footnotes
-
-.. [#] This ideal probably won't be achieved until auto-configuration is fully
- supported by the Distutils.
-
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
deleted file mode 100644
index e492b7f605759..0000000000000
--- a/Doc/distutils/examples.rst
+++ /dev/null
@@ -1,340 +0,0 @@
-.. _distutils_examples:
-
-******************
-Distutils Examples
-******************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-This chapter provides a number of basic examples to help get started with
-distutils. Additional information about using distutils can be found in the
-Distutils Cookbook.
-
-
-.. seealso::
-
- `Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_
- Collection of recipes showing how to achieve more control over distutils.
-
-
-.. _pure-mod:
-
-Pure Python distribution (by module)
-====================================
-
-If you're just distributing a couple of modules, especially if they don't live
-in a particular package, you can specify them individually using the
-``py_modules`` option in the setup script.
-
-In the simplest case, you'll have two files to worry about: a setup script and
-the single module you're distributing, :file:`foo.py` in this example::
-
- <root>/
- setup.py
- foo.py
-
-(In all diagrams in this section, *<root>* will refer to the distribution root
-directory.) A minimal setup script to describe this situation would be::
-
- from distutils.core import setup
- setup(name='foo',
- version='1.0',
- py_modules=['foo'],
- )
-
-Note that the name of the distribution is specified independently with the
-``name`` option, and there's no rule that says it has to be the same as
-the name of the sole module in the distribution (although that's probably a good
-convention to follow). However, the distribution name is used to generate
-filenames, so you should stick to letters, digits, underscores, and hyphens.
-
-Since ``py_modules`` is a list, you can of course specify multiple
-modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
-setup might look like this::
-
- <root>/
- setup.py
- foo.py
- bar.py
-
-and the setup script might be ::
-
- from distutils.core import setup
- setup(name='foobar',
- version='1.0',
- py_modules=['foo', 'bar'],
- )
-
-You can put module source files into another directory, but if you have enough
-modules to do that, it's probably easier to specify modules by package rather
-than listing them individually.
-
-
-.. _pure-pkg:
-
-Pure Python distribution (by package)
-=====================================
-
-If you have more than a couple of modules to distribute, especially if they are
-in multiple packages, it's probably easier to specify whole packages rather than
-individual modules. This works even if your modules are not in a package; you
-can just tell the Distutils to process modules from the root package, and that
-works the same as any other package (except that you don't have to have an
-:file:`__init__.py` file).
-
-The setup script from the last example could also be written as ::
-
- from distutils.core import setup
- setup(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 root
-package, e.g.::
-
- <root>/
- setup.py
- src/ foo.py
- bar.py
-
-then you would still specify the root package, but you have to tell the
-Distutils where source files in the root package live::
-
- from distutils.core import setup
- setup(name='foobar',
- version='1.0',
- package_dir={'': 'src'},
- packages=[''],
- )
-
-More typically, though, you will want to distribute multiple modules in the same
-package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar`
-modules belong in package :mod:`foobar`, one way to layout your source tree is
-::
-
- <root>/
- setup.py
- foobar/
- __init__.py
- foo.py
- bar.py
-
-This is in fact the default layout expected by the Distutils, and the one that
-requires the least work to describe in your setup script::
-
- from distutils.core import setup
- setup(name='foobar',
- version='1.0',
- packages=['foobar'],
- )
-
-If you want to put modules in directories not named for their package, then you
-need to use the ``package_dir`` option again. For example, if the
-:file:`src` directory holds modules in the :mod:`foobar` package::
-
- <root>/
- setup.py
- src/
- __init__.py
- foo.py
- bar.py
-
-an appropriate setup script would be ::
-
- from distutils.core import setup
- setup(name='foobar',
- version='1.0',
- package_dir={'foobar': 'src'},
- packages=['foobar'],
- )
-
-Or, you might put modules from your main package right in the distribution
-root::
-
- <root>/
- setup.py
- __init__.py
- foo.py
- bar.py
-
-in which case your setup script would be ::
-
- from distutils.core import setup
- setup(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 in ``packages``,
-but any entries in ``package_dir`` automatically extend to sub-packages.
-(In other words, the Distutils does *not* scan your source tree, trying to
-figure out which directories correspond to Python packages by looking for
-:file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
-
- <root>/
- setup.py
- foobar/
- __init__.py
- foo.py
- bar.py
- subfoo/
- __init__.py
- blah.py
-
-then the corresponding setup script would be ::
-
- from distutils.core import setup
- setup(name='foobar',
- version='1.0',
- packages=['foobar', 'foobar.subfoo'],
- )
-
-
-.. _single-ext:
-
-Single extension module
-=======================
-
-Extension modules are specified using the ``ext_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, a
-single extension module in a single C source file, is::
-
- <root>/
- setup.py
- foo.c
-
-If the :mod:`foo` extension belongs in the root package, the setup script for
-this could be ::
-
- from distutils.core import setup
- from distutils.extension import Extension
- setup(name='foobar',
- version='1.0',
- ext_modules=[Extension('foo', ['foo.c'])],
- )
-
-If the extension actually belongs in a package, say :mod:`foopkg`, then
-
-With exactly the same source tree layout, this extension can be put in the
-:mod:`foopkg` package simply by changing the name of the extension::
-
- from distutils.core import setup
- from distutils.extension import Extension
- setup(name='foobar',
- version='1.0',
- ext_modules=[Extension('foopkg.foo', ['foo.c'])],
- )
-
-Checking a package
-==================
-
-The ``check`` command allows you to verify if your package meta-data
-meet the minimum requirements to build a distribution.
-
-To run it, just call it using your :file:`setup.py` script. If something is
-missing, ``check`` will display a warning.
-
-Let's take an example with a simple script::
-
- from distutils.core import setup
-
- setup(name='foobar')
-
-Running the ``check`` command will display some warnings:
-
-.. code-block:: shell-session
-
- $ python setup.py check
- running check
- warning: check: missing required meta-data: version, url
- warning: check: missing meta-data: either (author and author_email) or
- (maintainer and maintainer_email) should be supplied
-
-
-If you use the reStructuredText syntax in the ``long_description`` field and
-`docutils`_ is installed you can check if the syntax is fine with the
-``check`` command, using the ``restructuredtext`` option.
-
-For example, if the :file:`setup.py` script is changed like this::
-
- from distutils.core import setup
-
- desc = """\
- My description
- ==============
-
- This is the description of the ``foobar`` package.
- """
-
- setup(name='foobar', version='1', author='tarek',
- author_email='tarek at ziade.org',
- url='http://example.com', long_description=desc)
-
-Where the long description is broken, ``check`` will be able to detect it
-by using the :mod:`docutils` parser:
-
-.. code-block:: shell-session
-
- $ python setup.py check --restructuredtext
- running check
- warning: check: Title underline too short. (line 2)
- warning: check: Could not finish the parsing.
-
-Reading the metadata
-=====================
-
-The :func:`distutils.core.setup` function provides a command-line interface
-that allows you to query the metadata fields of a project through the
-``setup.py`` script of a given project:
-
-.. code-block:: shell-session
-
- $ python setup.py --name
- distribute
-
-This call reads the ``name`` metadata by running the
-:func:`distutils.core.setup` function. Although, when a source or binary
-distribution is created with Distutils, the metadata fields are written
-in a static file called :file:`PKG-INFO`. When a Distutils-based project is
-installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
-and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`,
-where ``NAME`` is the name of the project, ``VERSION`` its version as defined
-in the Metadata, and ``pyX.X`` the major and minor version of Python like
-``2.7`` or ``3.2``.
-
-You can read back this static file, by using the
-:class:`distutils.dist.DistributionMetadata` class and its
-:func:`read_pkg_file` method::
-
- >>> from distutils.dist import DistributionMetadata
- >>> 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 to
-loads its values::
-
- >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
- >>> DistributionMetadata(pkg_info_path).name
- 'distribute'
-
-
-.. % \section{Multiple extension modules}
-.. % \label{multiple-ext}
-
-.. % \section{Putting it all together}
-
-
-.. _docutils: http://docutils.sourceforge.net
diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst
deleted file mode 100644
index 1075e81779a7b..0000000000000
--- a/Doc/distutils/extending.rst
+++ /dev/null
@@ -1,98 +0,0 @@
-.. _extending-distutils:
-
-*******************
-Extending Distutils
-*******************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-Distutils can be extended in various ways. Most extensions take the form of new
-commands or replacements for existing commands. New commands may be written to
-support new types of platform-specific packaging, for example, while
-replacements for existing commands may be made to modify details of how the
-command operates on a package.
-
-Most extensions of the distutils are made within :file:`setup.py` scripts that
-want to modify existing commands; many simply add a few file extensions that
-should be copied into packages in addition to :file:`.py` files as a
-convenience.
-
-Most distutils command implementations are subclasses of the
-:class:`distutils.cmd.Command` class. New commands may directly inherit from
-:class:`Command`, while replacements often derive from :class:`Command`
-indirectly, directly subclassing the command they are replacing. Commands are
-required to derive from :class:`Command`.
-
-.. % \section{Extending existing commands}
-.. % \label{extend-existing}
-
-.. % \section{Writing new commands}
-.. % \label{new-commands}
-.. % \XXX{Would an uninstall command be a good example here?}
-
-
-Integrating new commands
-========================
-
-There are different ways to integrate new command implementations into
-distutils. The most difficult is to lobby for the inclusion of the new features
-in distutils itself, and wait for (and require) a version of Python that
-provides that support. This is really hard for many reasons.
-
-The most common, and possibly the most reasonable for most needs, is to include
-the new implementations with your :file:`setup.py` script, and cause the
-:func:`distutils.core.setup` function use them::
-
- from distutils.command.build_py import build_py as _build_py
- from distutils.core import setup
-
- class build_py(_build_py):
- """Specialized Python source builder."""
-
- # implement whatever needs to be different...
-
- setup(cmdclass={'build_py': build_py},
- ...)
-
-This approach is most valuable if the new implementations must be used to use a
-particular package, as everyone interested in the package will need to have the
-new command implementation.
-
-Beginning with Python 2.4, a third option is available, intended to allow new
-commands to be added which can support existing :file:`setup.py` scripts without
-requiring modifications to the Python installation. This is expected to allow
-third-party extensions to provide support for additional packaging systems, but
-the commands can be used for anything distutils commands can be used for. A new
-configuration option, ``command_packages`` (command-line option
-:option:`!--command-packages`), can be used to specify additional packages to be
-searched for modules implementing commands. Like all distutils options, this
-can be specified on the command line or in a configuration file. This option
-can only be set in the ``[global]`` section of a configuration file, or before
-any commands on the command line. If set in a configuration file, it can be
-overridden from the command line; setting it to an empty string on the command
-line causes the default to be used. This should never be set in a configuration
-file provided with a package.
-
-This new option can be used to add any number of packages to the list of
-packages searched for command implementations; multiple package names should be
-separated by commas. When not specified, the search is only performed in the
-:mod:`distutils.command` package. When :file:`setup.py` is run with the option
-``--command-packages distcmds,buildcmds``, however, the packages
-:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
-in that order. New commands are expected to be implemented in modules of the
-same name as the command by classes sharing the same name. Given the example
-command line option above, the command :command:`bdist_openpkg` could be
-implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
-:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
-
-
-Adding new distribution types
-=============================
-
-Commands that create distributions (files in the :file:`dist/` directory) need
-to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
-:command:`upload` can upload it to PyPI. The *filename* in the pair contains no
-path information, only the name of the file itself. In dry-run mode, pairs
-should still be added to represent what would have been created.
-
-
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
deleted file mode 100644
index 2ccddc38b5f26..0000000000000
--- a/Doc/distutils/index.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-.. _distutils-index:
-
-##############################################
- Distributing Python Modules (Legacy version)
-##############################################
-
-:Authors: Greg Ward, Anthony Baxter
-:Email: distutils-sig at python.org
-
-.. seealso::
-
- :ref:`distributing-index`
- The up to date module distribution documentations
-
-.. note::
-
- The entire ``distutils`` package has been deprecated and will be
- removed in Python 3.12. This documentation is retained as a
- reference only, and will be removed with the package. See the
- :ref:`What's New <distutils-deprecated>` entry for more information.
-
-.. include:: ./_setuptools_disclaimer.rst
-
-.. note::
-
- This guide only covers the basic tools for building and distributing
- extensions that are provided as part of this version of Python. Third party
- tools offer easier to use and more secure alternatives. Refer to the `quick
- recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
- in the Python Packaging User Guide for more information.
-
-This document describes the Python Distribution Utilities ("Distutils") from
-the module developer's point of view, describing the underlying capabilities
-that ``setuptools`` builds on to allow Python developers to make Python modules
-and extensions readily available to a wider audience.
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- introduction.rst
- setupscript.rst
- configfile.rst
- sourcedist.rst
- builtdist.rst
- examples.rst
- extending.rst
- commandref.rst
- apiref.rst
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
deleted file mode 100644
index 87ed178e52bd4..0000000000000
--- a/Doc/distutils/introduction.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-.. _distutils-intro:
-
-****************************
-An Introduction to Distutils
-****************************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-This document covers using the Distutils to distribute your Python modules,
-concentrating on the role of developer/distributor: if you're looking for
-information on installing Python modules, you should refer to the
-:ref:`install-index` chapter.
-
-
-.. _distutils-concepts:
-
-Concepts & Terminology
-======================
-
-Using the Distutils is quite simple, both for module developers and for
-users/administrators installing third-party modules. As a developer, your
-responsibilities (apart from writing solid, well-documented and well-tested
-code, of course!) are:
-
-* write a setup script (:file:`setup.py` by convention)
-
-* (optional) write a setup configuration file
-
-* create a source distribution
-
-* (optional) create one or more built (binary) distributions
-
-Each of these tasks is covered in this document.
-
-Not all module developers have access to a multitude of platforms, so it's not
-always feasible to expect them to create a multitude of built distributions. It
-is hoped that a class of intermediaries, called *packagers*, will arise to
-address this need. Packagers will take source distributions released by module
-developers, build them on one or more platforms, and release the resulting built
-distributions. Thus, users on the most popular platforms will be able to
-install most popular Python module distributions in the most natural way for
-their platform, without having to run a single setup script or compile a line of
-code.
-
-
-.. _distutils-simple-example:
-
-A Simple Example
-================
-
-The setup script is usually quite simple, although since it's written in Python,
-there are no arbitrary limits to what you can do with it, though you should be
-careful about putting arbitrarily expensive operations in your setup script.
-Unlike, say, Autoconf-style configure scripts, the setup script may be run
-multiple times in the course of building and installing your module
-distribution.
-
-If all you want to do is distribute a module called :mod:`foo`, contained in a
-file :file:`foo.py`, then your setup script can be as simple as this::
-
- from distutils.core import setup
- setup(name='foo',
- version='1.0',
- py_modules=['foo'],
- )
-
-Some observations:
-
-* most information that you supply to the Distutils is supplied as keyword
- arguments to the :func:`setup` function
-
-* those keyword arguments fall into two categories: package metadata (name,
- version number) and information about what's in the package (a list of pure
- Python modules, in this case)
-
-* modules are specified by module name, not filename (the same will hold true
- for packages and extensions)
-
-* it's recommended that you supply a little more metadata, in particular your
- name, email address and a URL for the project (see section :ref:`setup-script`
- for an example)
-
-To create a source distribution for this module, you would create a setup
-script, :file:`setup.py`, containing the above code, and run this command from a
-terminal::
-
- python setup.py sdist
-
-For Windows, open a command prompt window (:menuselection:`Start -->
-Accessories`) and change the command to::
-
- setup.py sdist
-
-:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
-containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
-The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
-will unpack into a directory :file:`foo-1.0`.
-
-If an end-user wishes to install your :mod:`foo` module, all they have to do is
-download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
-:file:`foo-1.0` directory---run ::
-
- python setup.py install
-
-which will ultimately copy :file:`foo.py` to the appropriate directory for
-third-party modules in their Python installation.
-
-This simple example demonstrates some fundamental concepts of the Distutils.
-First, both developers and installers have the same basic user interface, i.e.
-the setup script. The difference is which Distutils *commands* they use: the
-:command:`sdist` command is almost exclusively for module developers, while
-:command:`install` is more often for installers (although most developers will
-want to install their own code occasionally).
-
-Other useful built distribution formats are RPM, implemented by the
-:command:`bdist_rpm` command, Solaris :program:`pkgtool`
-(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
-(:command:`bdist_sdux`). For example, the following command will create an RPM
-file called :file:`foo-1.0.noarch.rpm`::
-
- python setup.py bdist_rpm
-
-(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
-this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
-Mandrake Linux.)
-
-You can find out what distribution formats are available at any time by running
-::
-
- python setup.py bdist --help-formats
-
-
-.. _python-terms:
-
-General Python terminology
-==========================
-
-If you're reading this document, you probably have a good idea of what modules,
-extensions, and so forth are. Nevertheless, just to be sure that everyone is
-operating from a common starting point, we offer the following glossary of
-common Python terms:
-
-module
- the basic unit of code reusability in Python: a block of code imported by some
- other code. Three types of modules concern us here: pure Python modules,
- extension modules, and packages.
-
-pure Python module
- a module written in Python and contained in a single :file:`.py` file (and
- possibly associated :file:`.pyc` files). Sometimes referred to as a
- "pure module."
-
-extension module
- a module written in the low-level language of the Python implementation: C/C++
- for Python, Java for Jython. Typically contained in a single dynamically
- loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
- extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
- extensions on Windows, or a Java class file for Jython extensions. (Note that
- currently, the Distutils only handles C/C++ extensions for Python.)
-
-package
- a module that contains other modules; typically contained in a directory in the
- filesystem and distinguished from other directories by the presence of a file
- :file:`__init__.py`.
-
-root package
- the root of the hierarchy of packages. (This isn't really a package, since it
- doesn't have an :file:`__init__.py` file. But we have to call it something.)
- The vast majority of the standard library is in the root package, as are many
- small, standalone third-party modules that don't belong to a larger module
- collection. Unlike regular packages, modules in the root package can be found in
- many directories: in fact, every directory listed in ``sys.path`` contributes
- modules to the root package.
-
-
-.. _distutils-term:
-
-Distutils-specific terminology
-==============================
-
-The following terms apply more specifically to the domain of distributing Python
-modules using the Distutils:
-
-module distribution
- a collection of Python modules distributed together as a single downloadable
- resource and meant to be installed *en masse*. Examples of some well-known
- module distributions are NumPy, SciPy, Pillow,
- or mxBase. (This would be called a *package*, except that term is
- already taken in the Python context: a single module distribution may contain
- zero, one, or many Python packages.)
-
-pure module distribution
- a module distribution that contains only pure Python modules and packages.
- Sometimes referred to as a "pure distribution."
-
-non-pure module distribution
- a module distribution that contains at least one extension module. Sometimes
- referred to as a "non-pure distribution."
-
-distribution root
- the top-level directory of your source tree (or source distribution); the
- directory where :file:`setup.py` exists. Generally :file:`setup.py` will be
- run from this directory.
diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst
deleted file mode 100644
index ccb9a598b2b7a..0000000000000
--- a/Doc/distutils/packageindex.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-:orphan:
-
-.. _package-index:
-
-*******************************
-The Python Package Index (PyPI)
-*******************************
-
-The `Python Package Index (PyPI)`_ stores metadata describing distributions
-packaged with distutils and other publishing tools, as well the distribution
-archives themselves.
-
-References to up to date PyPI documentation can be found at
-:ref:`publishing-python-packages`.
-
-.. _Python Package Index (PyPI): https://pypi.org
diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst
deleted file mode 100644
index 4386a60b664bf..0000000000000
--- a/Doc/distutils/setupscript.rst
+++ /dev/null
@@ -1,713 +0,0 @@
-.. _setup-script:
-
-************************
-Writing the Setup Script
-************************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-The setup script is the centre of all activity in building, distributing, and
-installing modules using the Distutils. The main purpose of the setup script is
-to describe your module distribution to the Distutils, so that the various
-commands that operate on your modules do the right thing. As we saw in section
-:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
-:func:`setup`, and most information supplied to the Distutils by the module
-developer is supplied as keyword arguments to :func:`setup`.
-
-Here's a slightly more involved example, which we'll follow for the next couple
-of sections: the Distutils' own setup script. (Keep in mind that although the
-Distutils are included with Python 1.6 and later, they also have an independent
-existence so that Python 1.5.2 users can use them to install other module
-distributions. The Distutils' own setup script, shown here, is used to install
-the package into Python 1.5.2.) ::
-
- #!/usr/bin/env python
-
- from distutils.core import setup
-
- setup(name='Distutils',
- version='1.0',
- description='Python Distribution Utilities',
- author='Greg Ward',
- author_email='gward at python.net',
- url='https://www.python.org/sigs/distutils-sig/',
- packages=['distutils', 'distutils.command'],
- )
-
-There are only two differences between this and the trivial one-file
-distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
-specification of pure Python modules by package, rather than by module. This is
-important since the Distutils consist of a couple of dozen modules split into
-(so far) two packages; an explicit list of every module would be tedious to
-generate and difficult to maintain. For more information on the additional
-meta-data, see section :ref:`meta-data`.
-
-Note that any pathnames (files or directories) supplied in the setup script
-should be written using the Unix convention, i.e. slash-separated. The
-Distutils will take care of converting this platform-neutral representation into
-whatever is appropriate on your current platform before actually using the
-pathname. This makes your setup script portable across operating systems, which
-of course is one of the major goals of the Distutils. In this spirit, all
-pathnames in this document are slash-separated.
-
-This, of course, only applies to pathnames given to Distutils functions. If
-you, for example, use standard Python functions such as :func:`glob.glob` or
-:func:`os.listdir` to specify files, you should be careful to write portable
-code instead of hardcoding path separators::
-
- glob.glob(os.path.join('mydir', 'subdir', '*.html'))
- os.listdir(os.path.join('mydir', 'subdir'))
-
-
-.. _listing-packages:
-
-Listing whole packages
-======================
-
-The ``packages`` option tells the Distutils to process (build, distribute,
-install, etc.) all pure Python modules found in each package mentioned in the
-``packages`` list. In order to do this, of course, there has to be a
-correspondence between package names and directories in the filesystem. The
-default correspondence is the most obvious one, i.e. package :mod:`distutils` is
-found in the directory :file:`distutils` relative to the distribution root.
-Thus, when you say ``packages = ['foo']`` in your setup script, you are
-promising that the Distutils will find a file :file:`foo/__init__.py` (which
-might be spelled differently on your system, but you get the idea) relative to
-the directory where your setup script lives. If you break this promise, the
-Distutils will issue a warning but still process the broken package anyway.
-
-If you use a different convention to lay out your source directory, that's no
-problem: you just have to supply the ``package_dir`` option to tell the
-Distutils about your convention. For example, say you keep all Python source
-under :file:`lib`, so that modules in the "root package" (i.e., not in any
-package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
-:file:`lib/foo`, and so forth. Then you would put ::
-
- package_dir = {'': 'lib'}
-
-in your setup script. The keys to this dictionary are package names, and an
-empty package name stands for the root package. The values are directory names
-relative to your distribution root. In this case, when you say ``packages =
-['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
-
-Another possible convention is to put the :mod:`foo` package right in
-:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
-written in the setup script as ::
-
- package_dir = {'foo': 'lib'}
-
-A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
-applies to all packages below *package*, so the :mod:`foo.bar` case is
-automatically handled here. In this example, having ``packages = ['foo',
-'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
-:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir``
-applies recursively, you must explicitly list all packages in
-``packages``: the Distutils will *not* recursively scan your source tree
-looking for any directory with an :file:`__init__.py` file.)
-
-
-.. _listing-modules:
-
-Listing individual modules
-==========================
-
-For a small module distribution, you might prefer to list all modules rather
-than listing packages---especially the case of a single module that goes in the
-"root package" (i.e., no package at all). This simplest case was shown in
-section :ref:`distutils-simple-example`; here is a slightly more involved example::
-
- py_modules = ['mod1', 'pkg.mod2']
-
-This describes two modules, one of them in the "root" package, the other in the
-:mod:`pkg` package. Again, the default package/directory layout implies that
-these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
-that :file:`pkg/__init__.py` exists as well. And again, you can override the
-package/directory correspondence using the ``package_dir`` option.
-
-
-.. _describing-extensions:
-
-Describing extension modules
-============================
-
-Just as writing Python extension modules is a bit more complicated than writing
-pure Python modules, describing them to the Distutils is a bit more complicated.
-Unlike pure modules, it's not enough just to list modules or packages and expect
-the Distutils to go out and find the right files; you have to specify the
-extension name, source file(s), and any compile/link requirements (include
-directories, libraries to link with, etc.).
-
-.. XXX read over this section
-
-All of this is done through another keyword argument to :func:`setup`, the
-``ext_modules`` option. ``ext_modules`` is just a list of
-:class:`~distutils.core.Extension` instances, each of which describes a
-single extension module.
-Suppose your distribution includes a single extension, called :mod:`foo` and
-implemented by :file:`foo.c`. If no additional instructions to the
-compiler/linker are needed, describing this extension is quite simple::
-
- Extension('foo', ['foo.c'])
-
-The :class:`Extension` class can be imported from :mod:`distutils.core` along
-with :func:`setup`. Thus, the setup script for a module distribution that
-contains only this one extension and nothing else might be::
-
- from distutils.core import setup, Extension
- setup(name='foo',
- version='1.0',
- ext_modules=[Extension('foo', ['foo.c'])],
- )
-
-The :class:`Extension` class (actually, the underlying extension-building
-machinery implemented by the :command:`build_ext` command) supports a great deal
-of flexibility in describing Python extensions, which is explained in the
-following sections.
-
-
-Extension names and packages
-----------------------------
-
-The first argument to the :class:`~distutils.core.Extension` constructor is
-always the name of the extension, including any package names. For example, ::
-
- Extension('foo', ['src/foo1.c', 'src/foo2.c'])
-
-describes an extension that lives in the root package, while ::
-
- Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
-
-describes the same extension in the :mod:`pkg` package. The source files and
-resulting object code are identical in both cases; the only difference is where
-in the filesystem (and therefore where in Python's namespace hierarchy) the
-resulting extension lives.
-
-If you have a number of extensions all in the same package (or all under the
-same base package), use the ``ext_package`` keyword argument to
-:func:`setup`. For example, ::
-
- setup(...,
- ext_package='pkg',
- ext_modules=[Extension('foo', ['foo.c']),
- Extension('subpkg.bar', ['bar.c'])],
- )
-
-will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
-:mod:`pkg.subpkg.bar`.
-
-
-Extension source files
-----------------------
-
-The second argument to the :class:`~distutils.core.Extension` constructor is
-a list of source
-files. Since the Distutils currently only support C, C++, and Objective-C
-extensions, these are normally C/C++/Objective-C source files. (Be sure to use
-appropriate extensions to distinguish C++ source files: :file:`.cc` and
-:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
-
-However, you can also include SWIG interface (:file:`.i`) files in the list; the
-:command:`build_ext` command knows how to deal with SWIG extensions: it will run
-SWIG on the interface file and compile the resulting C/C++ file into your
-extension.
-
-.. XXX SWIG support is rough around the edges and largely untested!
-
-This warning notwithstanding, options to SWIG can be currently passed like
-this::
-
- setup(...,
- ext_modules=[Extension('_foo', ['foo.i'],
- swig_opts=['-modern', '-I../include'])],
- py_modules=['foo'],
- )
-
-Or on the commandline like this::
-
- > python setup.py build_ext --swig-opts="-modern -I../include"
-
-On some platforms, you can include non-source files that are processed by the
-compiler and included in your extension. Currently, this just means Windows
-message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
-Visual C++. These will be compiled to binary resource (:file:`.res`) files and
-linked into the executable.
-
-
-Preprocessor options
---------------------
-
-Three optional arguments to :class:`~distutils.core.Extension` will help if
-you need to specify include directories to search or preprocessor macros to
-define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
-
-For example, if your extension requires header files in the :file:`include`
-directory under your distribution root, use the ``include_dirs`` option::
-
- Extension('foo', ['foo.c'], include_dirs=['include'])
-
-You can specify absolute directories there; if you know that your extension will
-only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
-away with ::
-
- Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
-
-You should avoid this sort of non-portable usage if you plan to distribute your
-code: it's probably better to write C code like ::
-
- #include <X11/Xlib.h>
-
-If you need to include header files from some other Python extension, you can
-take advantage of the fact that header files are installed in a consistent way
-by the Distutils :command:`install_headers` command. For example, the Numerical
-Python header files are installed (on a standard Unix installation) to
-:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
-according to your platform and Python installation.) Since the Python include
-directory---\ :file:`/usr/local/include/python1.5` in this case---is always
-included in the search path when building Python extensions, the best approach
-is to write C code like ::
-
- #include <Numerical/arrayobject.h>
-
-If you must put the :file:`Numerical` include directory right into your header
-search path, though, you can find that directory using the Distutils
-:mod:`distutils.sysconfig` module::
-
- from distutils.sysconfig import get_python_inc
- incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
- setup(...,
- Extension(..., include_dirs=[incdir]),
- )
-
-Even though this is quite portable---it will work on any Python installation,
-regardless of platform---it's probably easier to just write your C code in the
-sensible way.
-
-You can define and undefine pre-processor macros with the ``define_macros`` and
-``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
-tuples, where ``name`` is the name of the macro to define (a string) and
-``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
-to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
-most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
-just a list of macros to undefine.
-
-For example::
-
- Extension(...,
- define_macros=[('NDEBUG', '1'),
- ('HAVE_STRFTIME', None)],
- undef_macros=['HAVE_FOO', 'HAVE_BAR'])
-
-is the equivalent of having this at the top of every C source file::
-
- #define NDEBUG 1
- #define HAVE_STRFTIME
- #undef HAVE_FOO
- #undef HAVE_BAR
-
-
-Library options
----------------
-
-You can also specify the libraries to link against when building your extension,
-and the directories to search for those libraries. The ``libraries`` option is
-a list of libraries to link against, ``library_dirs`` is a list of directories
-to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
-directories to search for shared (dynamically loaded) libraries at run-time.
-
-For example, if you need to link against libraries known to be in the standard
-library search path on target systems ::
-
- Extension(...,
- libraries=['gdbm', 'readline'])
-
-If you need to link with libraries in a non-standard location, you'll have to
-include the location in ``library_dirs``::
-
- Extension(...,
- library_dirs=['/usr/X11R6/lib'],
- libraries=['X11', 'Xt'])
-
-(Again, this sort of non-portable construct should be avoided if you intend to
-distribute your code.)
-
-.. XXX Should mention clib libraries here or somewhere else!
-
-
-Other options
--------------
-
-There are still some other options which can be used to handle special cases.
-
-The ``optional`` option is a boolean; if it is true,
-a build failure in the extension will not abort the build process, but
-instead simply not install the failing extension.
-
-The ``extra_objects`` option is a list of object files to be passed to the
-linker. These files must not have extensions, as the default extension for the
-compiler is used.
-
-``extra_compile_args`` and ``extra_link_args`` can be used to
-specify additional command line options for the respective compiler and linker
-command lines.
-
-``export_symbols`` is only useful on Windows. It can contain a list of
-symbols (functions or variables) to be exported. This option is not needed when
-building compiled extensions: Distutils will automatically add ``initmodule``
-to the list of exported symbols.
-
-The ``depends`` option is a list of files that the extension depends on
-(for example header files). The build command will call the compiler on the
-sources to rebuild extension if any on this files has been modified since the
-previous build.
-
-Relationships between Distributions and Packages
-================================================
-
-A distribution may relate to packages in three specific ways:
-
-#. It can require packages or modules.
-
-#. It can provide packages or modules.
-
-#. It can obsolete packages or modules.
-
-These relationships can be specified using keyword arguments to the
-:func:`distutils.core.setup` function.
-
-Dependencies on other Python modules and packages can be specified by supplying
-the *requires* keyword argument to :func:`setup`. The value must be a list of
-strings. Each string specifies a package that is required, and optionally what
-versions are sufficient.
-
-To specify that any version of a module or package is required, the string
-should consist entirely of the module or package name. Examples include
-``'mymodule'`` and ``'xml.parsers.expat'``.
-
-If specific versions are required, a sequence of qualifiers can be supplied in
-parentheses. Each qualifier may consist of a comparison operator and a version
-number. The accepted comparison operators are::
-
- < > ==
- <= >= !=
-
-These can be combined by using multiple qualifiers separated by commas (and
-optional whitespace). In this case, all of the qualifiers must be matched; a
-logical AND is used to combine the evaluations.
-
-Let's look at a bunch of examples:
-
-+-------------------------+----------------------------------------------+
-| Requires Expression | Explanation |
-+=========================+==============================================+
-| ``==1.0`` | Only version ``1.0`` is compatible |
-+-------------------------+----------------------------------------------+
-| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
-| | is compatible, except ``1.5.1`` |
-+-------------------------+----------------------------------------------+
-
-Now that we can specify dependencies, we also need to be able to specify what we
-provide that other distributions can require. This is done using the *provides*
-keyword argument to :func:`setup`. The value for this keyword is a list of
-strings, each of which names a Python module or package, and optionally
-identifies the version. If the version is not specified, it is assumed to match
-that of the distribution.
-
-Some examples:
-
-+---------------------+----------------------------------------------+
-| Provides Expression | Explanation |
-+=====================+==============================================+
-| ``mypkg`` | Provide ``mypkg``, using the distribution |
-| | version |
-+---------------------+----------------------------------------------+
-| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
-| | the distribution version |
-+---------------------+----------------------------------------------+
-
-A package can declare that it obsoletes other packages using the *obsoletes*
-keyword argument. The value for this is similar to that of the *requires*
-keyword: a list of strings giving module or package specifiers. Each specifier
-consists of a module or package name optionally followed by one or more version
-qualifiers. Version qualifiers are given in parentheses after the module or
-package name.
-
-The versions identified by the qualifiers are those that are obsoleted by the
-distribution being described. If no qualifiers are given, all versions of the
-named module or package are understood to be obsoleted.
-
-.. _distutils-installing-scripts:
-
-Installing Scripts
-==================
-
-So far we have been dealing with pure and non-pure Python modules, which are
-usually not run by themselves but imported by scripts.
-
-Scripts are files containing Python source code, intended to be started from the
-command line. Scripts don't require Distutils to do anything very complicated.
-The only clever feature is that if the first line of the script starts with
-``#!`` and contains the word "python", the Distutils will adjust the first line
-to refer to the current interpreter location. By default, it is replaced with
-the current interpreter location. The :option:`!--executable` (or :option:`!-e`)
-option will allow the interpreter path to be explicitly overridden.
-
-The ``scripts`` option simply is a list of files to be handled in this
-way. From the PyXML setup script::
-
- setup(...,
- scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
- )
-
-.. versionchanged:: 3.1
- All the scripts will also be added to the ``MANIFEST`` file if no template is
- provided. See :ref:`manifest`.
-
-
-.. _distutils-installing-package-data:
-
-Installing Package Data
-=======================
-
-Often, additional files need to be installed into a package. These files are
-often data that's closely related to the package's implementation, or text files
-containing documentation that might be of interest to programmers using the
-package. These files are called :dfn:`package data`.
-
-Package data can be added to packages using the ``package_data`` keyword
-argument to the :func:`setup` function. The value must be a mapping from
-package name to a list of relative path names that should be copied into the
-package. The paths are interpreted as relative to the directory containing the
-package (information from the ``package_dir`` mapping is used if appropriate);
-that is, the files are expected to be part of the package in the source
-directories. They may contain glob patterns as well.
-
-The path names may contain directory portions; any necessary directories will be
-created in the installation.
-
-For example, if a package should contain a subdirectory with several data files,
-the files can be arranged like this in the source tree::
-
- setup.py
- src/
- mypkg/
- __init__.py
- module.py
- data/
- tables.dat
- spoons.dat
- forks.dat
-
-The corresponding call to :func:`setup` might be::
-
- setup(...,
- packages=['mypkg'],
- package_dir={'mypkg': 'src/mypkg'},
- package_data={'mypkg': ['data/*.dat']},
- )
-
-
-.. versionchanged:: 3.1
- All the files that match ``package_data`` will be added to the ``MANIFEST``
- file if no template is provided. See :ref:`manifest`.
-
-
-.. _distutils-additional-files:
-
-Installing Additional Files
-===========================
-
-The ``data_files`` option can be used to specify additional files needed
-by the module distribution: configuration files, message catalogs, data files,
-anything which doesn't fit in the previous categories.
-
-``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
-following way::
-
- setup(...,
- data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
- ('config', ['cfg/data.cfg'])],
- )
-
-Each (*directory*, *files*) pair in the sequence specifies the installation
-directory and the files to install there.
-
-Each file name in *files* is interpreted relative to the :file:`setup.py`
-script at the top of the package source distribution. Note that you can
-specify the directory where the data files will be installed, but you cannot
-rename the data files themselves.
-
-The *directory* should be a relative path. It is interpreted relative to the
-installation prefix (Python's ``sys.prefix`` for system installations;
-``site.USER_BASE`` for user installations). Distutils allows *directory* to be
-an absolute installation path, but this is discouraged since it is
-incompatible with the wheel packaging format. No directory information from
-*files* is used to determine the final location of the installed file; only
-the name of the file is used.
-
-You can specify the ``data_files`` options as a simple sequence of files
-without specifying a target directory, but this is not recommended, and the
-:command:`install` command will print a warning in this case. To install data
-files directly in the target directory, an empty string should be given as the
-directory.
-
-.. versionchanged:: 3.1
- All the files that match ``data_files`` will be added to the ``MANIFEST``
- file if no template is provided. See :ref:`manifest`.
-
-
-.. _meta-data:
-
-Additional meta-data
-====================
-
-The setup script may include additional meta-data beyond the name and version.
-This information includes:
-
-+----------------------+---------------------------+-----------------+--------+
-| Meta-Data | Description | Value | Notes |
-+======================+===========================+=================+========+
-| ``name`` | name of the package | short string | \(1) |
-+----------------------+---------------------------+-----------------+--------+
-| ``version`` | version of this release | short string | (1)(2) |
-+----------------------+---------------------------+-----------------+--------+
-| ``author`` | package author's name | short string | \(3) |
-+----------------------+---------------------------+-----------------+--------+
-| ``author_email`` | email address of the | email address | \(3) |
-| | package author | | |
-+----------------------+---------------------------+-----------------+--------+
-| ``maintainer`` | package maintainer's name | short string | \(3) |
-+----------------------+---------------------------+-----------------+--------+
-| ``maintainer_email`` | email address of the | email address | \(3) |
-| | package maintainer | | |
-+----------------------+---------------------------+-----------------+--------+
-| ``url`` | home page for the package | URL | \(1) |
-+----------------------+---------------------------+-----------------+--------+
-| ``description`` | short, summary | short string | |
-| | description of the | | |
-| | package | | |
-+----------------------+---------------------------+-----------------+--------+
-| ``long_description`` | longer description of the | long string | \(4) |
-| | package | | |
-+----------------------+---------------------------+-----------------+--------+
-| ``download_url`` | location where the | URL | |
-| | package may be downloaded | | |
-+----------------------+---------------------------+-----------------+--------+
-| ``classifiers`` | a list of classifiers | list of strings | (6)(7) |
-+----------------------+---------------------------+-----------------+--------+
-| ``platforms`` | a list of platforms | list of strings | (6)(8) |
-+----------------------+---------------------------+-----------------+--------+
-| ``keywords`` | a list of keywords | list of strings | (6)(8) |
-+----------------------+---------------------------+-----------------+--------+
-| ``license`` | license for the package | short string | \(5) |
-+----------------------+---------------------------+-----------------+--------+
-
-Notes:
-
-(1)
- These fields are required.
-
-(2)
- It is recommended that versions take the form *major.minor[.patch[.sub]]*.
-
-(3)
- Either the author or the maintainer must be identified. If maintainer is
- provided, distutils lists it as the author in :file:`PKG-INFO`.
-
-(4)
- The ``long_description`` field is used by PyPI when you publish a package,
- to build its project page.
-
-(5)
- The ``license`` field is a text indicating the license covering the
- package where the license is not a selection from the "License" Trove
- classifiers. See the ``Classifier`` field. Notice that
- there's a ``licence`` distribution option which is deprecated but still
- acts as an alias for ``license``.
-
-(6)
- This field must be a list.
-
-(7)
- The valid classifiers are listed on
- `PyPI <https://pypi.org/classifiers>`_.
-
-(8)
- To preserve backward compatibility, this field also accepts a string. If
- you pass a comma-separated string ``'foo, bar'``, it will be converted to
- ``['foo', 'bar']``, Otherwise, it will be converted to a list of one
- string.
-
-'short string'
- A single line of text, not more than 200 characters.
-
-'long string'
- Multiple lines of plain text in reStructuredText format (see
- http://docutils.sourceforge.net/).
-
-'list of strings'
- See below.
-
-Encoding the version information is an art in itself. Python packages generally
-adhere to the version format *major.minor[.patch][sub]*. The major number is 0
-for initial, experimental releases of software. It is incremented for releases
-that represent major milestones in a package. The minor number is incremented
-when important new features are added to the package. The patch number
-increments when bug-fix releases are made. Additional trailing version
-information is sometimes used to indicate sub-releases. These are
-"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
-"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
-(for final pre-release release testing). Some examples:
-
-0.1.0
- the first, experimental release of a package
-
-1.0.1a2
- the second alpha release of the first patch version of 1.0
-
-``classifiers`` must be specified in a list::
-
- setup(...,
- classifiers=[
- 'Development Status :: 4 - Beta',
- 'Environment :: Console',
- 'Environment :: Web Environment',
- 'Intended Audience :: End Users/Desktop',
- 'Intended Audience :: Developers',
- 'Intended Audience :: System Administrators',
- 'License :: OSI Approved :: Python Software Foundation License',
- 'Operating System :: MacOS :: MacOS X',
- 'Operating System :: Microsoft :: Windows',
- 'Operating System :: POSIX',
- 'Programming Language :: Python',
- 'Topic :: Communications :: Email',
- 'Topic :: Office/Business',
- 'Topic :: Software Development :: Bug Tracking',
- ],
- )
-
-.. versionchanged:: 3.7
- :class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords``
- or ``platforms`` fields are not specified as a list or a string.
-
-.. _debug-setup-script:
-
-Debugging the setup script
-==========================
-
-Sometimes things go wrong, and the setup script doesn't do what the developer
-wants.
-
-Distutils catches any exceptions when running the setup script, and print a
-simple error message before the script is terminated. The motivation for this
-behaviour is to not confuse administrators who don't know much about Python and
-are trying to install a package. If they get a big long traceback from deep
-inside the guts of Distutils, they may think the package or the Python
-installation is broken because they don't read all the way down to the bottom
-and see that it's a permission problem.
-
-On the other hand, this doesn't help the developer to find the cause of the
-failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
-to anything except an empty string, and distutils will now print detailed
-information about what it is doing, dump the full traceback when an exception
-occurs, and print the whole command line when an external program (like a C
-compiler) fails.
diff --git a/Doc/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst
deleted file mode 100644
index b55d01157f3ee..0000000000000
--- a/Doc/distutils/sourcedist.rst
+++ /dev/null
@@ -1,245 +0,0 @@
-.. _source-dist:
-
-******************************
-Creating a Source Distribution
-******************************
-
-.. include:: ./_setuptools_disclaimer.rst
-
-As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
-to create a source distribution. In the simplest case, ::
-
- python setup.py sdist
-
-(assuming you haven't specified any :command:`sdist` options in the setup script
-or config file), :command:`sdist` creates the archive of the default format for
-the current platform. The default format is a gzip'ed tar file
-(:file:`.tar.gz`) on Unix, and ZIP file on Windows.
-
-You can specify as many formats as you like using the :option:`!--formats`
-option, for example::
-
- python setup.py sdist --formats=gztar,zip
-
-to create a gzipped tarball and a zip file. The available formats are:
-
-+-----------+-------------------------+-------------+
-| Format | Description | Notes |
-+===========+=========================+=============+
-| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
-+-----------+-------------------------+-------------+
-| ``gztar`` | gzip'ed tar file | \(2) |
-| | (:file:`.tar.gz`) | |
-+-----------+-------------------------+-------------+
-| ``bztar`` | bzip2'ed tar file | \(5) |
-| | (:file:`.tar.bz2`) | |
-+-----------+-------------------------+-------------+
-| ``xztar`` | xz'ed tar file | \(5) |
-| | (:file:`.tar.xz`) | |
-+-----------+-------------------------+-------------+
-| ``ztar`` | compressed tar file | (4),(5) |
-| | (:file:`.tar.Z`) | |
-+-----------+-------------------------+-------------+
-| ``tar`` | tar file (:file:`.tar`) | \(5) |
-+-----------+-------------------------+-------------+
-
-.. versionchanged:: 3.5
- Added support for the ``xztar`` format.
-
-Notes:
-
-(1)
- default on Windows
-
-(2)
- default on Unix
-
-(3)
- requires either external :program:`zip` utility or :mod:`zipfile` module (part
- of the standard Python library since Python 1.6)
-
-(4)
- requires the :program:`compress` program. Notice that this format is now
- pending for deprecation and will be removed in the future versions of Python.
-(5)
- deprecated by `PEP 527 <https://peps.python.org/pep-0527/>`_;
- `PyPI <https://pypi.org>`_ only accepts ``.zip`` and ``.tar.gz`` files.
-
-When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or
-``tar``), under Unix you can specify the ``owner`` and ``group`` names
-that will be set for each member of the archive.
-
-For example, if you want all files of the archive to be owned by root::
-
- python setup.py sdist --owner=root --group=root
-
-
-.. _manifest:
-
-Specifying the files to distribute
-==================================
-
-If you don't supply an explicit list of files (or instructions on how to
-generate one), the :command:`sdist` command puts a minimal default set into the
-source distribution:
-
-* all Python source files implied by the ``py_modules`` and
- ``packages`` options
-
-* all C source files mentioned in the ``ext_modules`` or
- ``libraries`` options
-
- .. XXX getting C library sources currently broken---no
- :meth:`get_source_files` method in :file:`build_clib.py`!
-
-* scripts identified by the ``scripts`` option
- See :ref:`distutils-installing-scripts`.
-
-* anything that looks like a test script: :file:`test/test\*.py` (currently, the
- Distutils don't do anything with test scripts except include them in source
- distributions, but in the future there will be a standard for testing Python
- module distributions)
-
-* Any of the standard README files (:file:`README`, :file:`README.txt`,
- or :file:`README.rst`), :file:`setup.py` (or whatever you called your setup
- script), and :file:`setup.cfg`.
-
-* all files that matches the ``package_data`` metadata.
- See :ref:`distutils-installing-package-data`.
-
-* all files that matches the ``data_files`` metadata.
- See :ref:`distutils-additional-files`.
-
-Sometimes this is enough, but usually you will want to specify additional files
-to distribute. The typical way to do this is to write a *manifest template*,
-called :file:`MANIFEST.in` by default. The manifest template is just a list of
-instructions for how to generate your manifest file, :file:`MANIFEST`, which is
-the exact list of files to include in your source distribution. The
-:command:`sdist` command processes this template and generates a manifest based
-on its instructions and what it finds in the filesystem.
-
-If you prefer to roll your own manifest file, the format is simple: one filename
-per line, regular files (or symlinks to them) only. If you do supply your own
-:file:`MANIFEST`, you must specify everything: the default set of files
-described above does not apply in this case.
-
-.. versionchanged:: 3.1
- An existing generated :file:`MANIFEST` will be regenerated without
- :command:`sdist` comparing its modification time to the one of
- :file:`MANIFEST.in` or :file:`setup.py`.
-
-.. versionchanged:: 3.1.3
- :file:`MANIFEST` files start with a comment indicating they are generated.
- Files without this comment are not overwritten or removed.
-
-.. versionchanged:: 3.2.2
- :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
- exists, like it used to do.
-
-.. versionchanged:: 3.7
- :file:`README.rst` is now included in the list of distutils standard READMEs.
-
-
-The manifest template has one command per line, where each command specifies a
-set of files to include or exclude from the source distribution. For an
-example, again we turn to the Distutils' own manifest template:
-
-.. code-block:: none
-
- include *.txt
- recursive-include examples *.txt *.py
- prune examples/sample?/build
-
-The meanings should be fairly clear: include all files in the distribution root
-matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
-matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
-:file:`examples/sample?/build`. All of this is done *after* the standard
-include set, so you can exclude files from the standard set with explicit
-instructions in the manifest template. (Or, you can use the
-:option:`!--no-defaults` option to disable the standard set entirely.) There are
-several other commands available in the manifest template mini-language; see
-section :ref:`sdist-cmd`.
-
-The order of commands in the manifest template matters: initially, we have the
-list of default files as described above, and each command in the template adds
-to or removes from that list of files. Once we have fully processed the
-manifest template, we remove files that should not be included in the source
-distribution:
-
-* all files in the Distutils "build" tree (default :file:`build/`)
-
-* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
- :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
-
-Now we have our complete list of files, which is written to the manifest for
-future reference, and then used to build the source distribution archive(s).
-
-You can disable the default set of included files with the
-:option:`!--no-defaults` option, and you can disable the standard exclude set
-with :option:`!--no-prune`.
-
-Following the Distutils' own manifest template, let's trace how the
-:command:`sdist` command builds the list of files to include in the Distutils
-source distribution:
-
-#. include all Python source files in the :file:`distutils` and
- :file:`distutils/command` subdirectories (because packages corresponding to
- those two directories were mentioned in the ``packages`` option in the
- setup script---see section :ref:`setup-script`)
-
-#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
- files)
-
-#. include :file:`test/test\*.py` (standard files)
-
-#. include :file:`\*.txt` in the distribution root (this will find
- :file:`README.txt` a second time, but such redundancies are weeded out later)
-
-#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
- under :file:`examples`,
-
-#. exclude all files in the sub-trees starting at directories matching
- :file:`examples/sample?/build`\ ---this may exclude files included by the
- previous two steps, so it's important that the ``prune`` command in the manifest
- template comes after the ``recursive-include`` command
-
-#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
- :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
- directories
-
-Just like in the setup script, file and directory names in the manifest template
-should always be slash-separated; the Distutils will take care of converting
-them to the standard representation on your platform. That way, the manifest
-template is portable across operating systems.
-
-
-.. _manifest-options:
-
-Manifest-related options
-========================
-
-The normal course of operations for the :command:`sdist` command is as follows:
-
-* if the manifest file (:file:`MANIFEST` by default) exists and the first line
- does not have a comment indicating it is generated from :file:`MANIFEST.in`,
- then it is used as is, unaltered
-
-* if the manifest file doesn't exist or has been previously automatically
- generated, read :file:`MANIFEST.in` and create the manifest
-
-* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
- with just the default file set
-
-* use the list of files now in :file:`MANIFEST` (either just generated or read
- in) to create the source distribution archive(s)
-
-There are a couple of options that modify this behaviour. First, use the
-:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
-"include" and "exclude" sets.
-
-Second, you might just want to (re)generate the manifest, but not create a source
-distribution::
-
- python setup.py sdist --manifest-only
-
-:option:`!-o` is a shortcut for :option:`!--manifest-only`.
diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
deleted file mode 100644
index 4c391cab072ea..0000000000000
--- a/Doc/distutils/uploading.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-:orphan:
-
-***************************************
-Uploading Packages to the Package Index
-***************************************
-
-References to up to date PyPI documentation can be found at
-:ref:`publishing-python-packages`.
diff --git a/Doc/extending/building.rst b/Doc/extending/building.rst
index 53817074ab1ee..880bb33ee5671 100644
--- a/Doc/extending/building.rst
+++ b/Doc/extending/building.rst
@@ -11,7 +11,7 @@ A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
and must be named after the module name, with an appropriate extension.
-When using distutils, the correct filename is generated automatically.
+When using setuptools, the correct filename is generated automatically.
The initialization function has the signature:
@@ -45,122 +45,12 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details.
.. highlight:: c
-Building C and C++ Extensions with distutils
-============================================
+.. _setuptools-index:
-.. sectionauthor:: Martin v. Löwis <martin at v.loewis.de>
+Building C and C++ Extensions with setuptools
+=============================================
-Extension modules can be built using distutils, which is included in Python.
-Since distutils also supports creation of binary packages, users don't
-necessarily need a compiler and distutils to install the extension.
-
-A distutils package contains a driver script, :file:`setup.py`. This is a plain
-Python file, which, in the most simple case, could look like this:
-
-.. code-block:: python3
-
- from distutils.core import setup, Extension
-
- module1 = Extension('demo',
- sources = ['demo.c'])
-
- setup (name = 'PackageName',
- version = '1.0',
- description = 'This is a demo package',
- ext_modules = [module1])
-
-
-With this :file:`setup.py`, and a file :file:`demo.c`, running ::
-
- python setup.py build
-
-will compile :file:`demo.c`, and produce an extension module named ``demo`` in
-the :file:`build` directory. Depending on the system, the module file will end
-up in a subdirectory :file:`build/lib.system`, and may have a name like
-:file:`demo.so` or :file:`demo.pyd`.
-
-In the :file:`setup.py`, all execution is performed by calling the ``setup``
-function. This takes a variable number of keyword arguments, of which the
-example above uses only a subset. Specifically, the example specifies
-meta-information to build packages, and it specifies the contents of the
-package. Normally, a package will contain additional modules, like Python
-source modules, documentation, subpackages, etc. Please refer to the distutils
-documentation in :ref:`distutils-index` to learn more about the features of
-distutils; this section explains building extension modules only.
-
-It is common to pre-compute arguments to :func:`setup`, to better structure the
-driver script. In the example above, the ``ext_modules`` argument to
-:func:`~distutils.core.setup` is a list of extension modules, each of which is
-an instance of
-the :class:`~distutils.extension.Extension`. In the example, the instance
-defines an extension named ``demo`` which is build by compiling a single source
-file, :file:`demo.c`.
-
-In many cases, building an extension is more complex, since additional
-preprocessor defines and libraries may be needed. This is demonstrated in the
-example below.
-
-.. code-block:: python3
-
- from distutils.core import setup, Extension
-
- module1 = Extension('demo',
- define_macros = [('MAJOR_VERSION', '1'),
- ('MINOR_VERSION', '0')],
- include_dirs = ['/usr/local/include'],
- libraries = ['tcl83'],
- library_dirs = ['/usr/local/lib'],
- sources = ['demo.c'])
-
- setup (name = 'PackageName',
- version = '1.0',
- description = 'This is a demo package',
- author = 'Martin v. Loewis',
- author_email = 'martin at v.loewis.de',
- url = 'https://docs.python.org/extending/building',
- long_description = '''
- This is really just a demo package.
- ''',
- ext_modules = [module1])
-
-
-In this example, :func:`~distutils.core.setup` is called with additional
-meta-information, which
-is recommended when distribution packages have to be built. For the extension
-itself, it specifies preprocessor defines, include directories, library
-directories, and libraries. Depending on the compiler, distutils passes this
-information in different ways to the compiler. For example, on Unix, this may
-result in the compilation commands ::
-
- gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
-
- gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
-
-These lines are for demonstration purposes only; distutils users should trust
-that distutils gets the invocations right.
-
-
-.. _distributing:
-
-Distributing your extension modules
-===================================
-
-When an extension has been successfully built, there are three ways to use it.
-
-End-users will typically want to install the module, they do so by running ::
-
- python setup.py install
-
-Module maintainers should produce source packages; to do so, they run ::
-
- python setup.py sdist
-
-In some cases, additional files need to be included in a source distribution;
-this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details.
-
-If the source distribution has been built successfully, maintainers can also
-create binary distributions. Depending on the platform, one of the following
-commands can be used to do so. ::
-
- python setup.py bdist_rpm
- python setup.py bdist_dumb
+Python 3.12 and newer no longer come with distutils. Please refer to the
+``setuptools`` documentation at
+https://setuptools.readthedocs.io/en/latest/setuptools.html
+to learn more about how build and distribute C/C++ extensions with setuptools.
diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst
index 28d0350f6f114..1129b0968bc4e 100644
--- a/Doc/extending/windows.rst
+++ b/Doc/extending/windows.rst
@@ -34,10 +34,10 @@ A Cookbook Approach
===================
There are two approaches to building extension modules on Windows, just as there
-are on Unix: use the :mod:`distutils` package to control the build process, or
-do things manually. The distutils approach works well for most extensions;
-documentation on using :mod:`distutils` to build and package extension modules
-is available in :ref:`distutils-index`. If you find you really need to do
+are on Unix: use the ``setuptools`` package to control the build process, or
+do things manually. The setuptools approach works well for most extensions;
+documentation on using ``setuptools`` to build and package extension modules
+is available in :ref:`setuptools-index`. If you find you really need to do
things manually, it may be instructive to study the project file for the
:source:`winsound <PCbuild/winsound.vcxproj>` standard library module.
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 63b64b95fc721..0923267d06601 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -23,7 +23,11 @@
The up to date module installation documentation. For regular Python
usage, you almost certainly want that document rather than this one.
-.. include:: ../distutils/_setuptools_disclaimer.rst
+.. note::
+
+ This document is being retained solely until the ``setuptools`` documentation
+ at https://setuptools.readthedocs.io/en/latest/setuptools.html
+ independently covers all of the relevant information currently included here.
.. note::
diff --git a/Doc/library/distribution.rst b/Doc/library/distribution.rst
index 8d4befe41b329..bec1ca3cc3913 100644
--- a/Doc/library/distribution.rst
+++ b/Doc/library/distribution.rst
@@ -9,7 +9,6 @@ with a local index server, or without any index server at all.
.. toctree::
- distutils.rst
ensurepip.rst
venv.rst
zipapp.rst
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
deleted file mode 100644
index 31c4ae5b23906..0000000000000
--- a/Doc/library/distutils.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-:mod:`distutils` --- Building and installing Python modules
-===========================================================
-
-.. module:: distutils
- :synopsis: Support for building and installing Python modules into an
- existing Python installation.
-
-.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
-
---------------
-
-:mod:`distutils` is deprecated with removal planned for Python 3.12.
-See the :ref:`What's New <distutils-deprecated>` entry for more information.
-
---------------
-
-The :mod:`distutils` package provides support for building and installing
-additional modules into a Python installation. The new modules may be either
-100%-pure Python, or may be extension modules written in C, or may be
-collections of Python packages which include modules coded in both Python and C.
-
-Most Python users will *not* want to use this module directly, but instead
-use the cross-version tools maintained by the Python Packaging Authority. In
-particular,
-`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
-enhanced alternative to :mod:`distutils` that provides:
-
-* support for declaring project dependencies
-* additional mechanisms for configuring which files to include in source
- releases (including plugins for integration with version control systems)
-* the ability to declare project "entry points", which can be used as the
- basis for application plugin systems
-* the ability to automatically generate Windows command line executables at
- installation time rather than needing to prebuild them
-* consistent behaviour across all supported Python versions
-
-The recommended `pip <https://pip.pypa.io/>`__ installer runs all
-``setup.py`` scripts with ``setuptools``, even if the script itself only
-imports ``distutils``. Refer to the
-`Python Packaging User Guide <https://packaging.python.org>`_ for more
-information.
-
-For the benefits of packaging tool authors and users seeking a deeper
-understanding of the details of the current packaging and distribution
-system, the legacy :mod:`distutils` based user documentation and API
-reference remain available:
-
-* :ref:`install-index`
-* :ref:`distutils-index`
diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst
index fa18d62d22af5..024988777030f 100644
--- a/Doc/library/sysconfig.rst
+++ b/Doc/library/sysconfig.rst
@@ -25,7 +25,7 @@ Configuration variables
A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
header file that are necessary to build both the Python binary itself and
-third-party C extensions compiled using :mod:`distutils`.
+third-party C extensions compiled using ``setuptools``.
:mod:`sysconfig` puts all variables found in these files in a dictionary that
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 3cf143d552ac8..513a982c6ede6 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -64,7 +64,7 @@ Creating virtual environments
Python installation).
When a virtual environment is active, any options that change the
- installation path will be ignored from all :mod:`distutils` configuration
+ installation path will be ignored from all ``setuptools`` configuration
files to prevent projects being inadvertently installed outside of the
virtual environment.
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 80c0dc08dae73..580cbd814f786 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -599,7 +599,7 @@ Main files of the build system
* :file:`pyconfig.h` (created by :file:`configure`);
* :file:`Modules/Setup`: C extensions built by the Makefile using
:file:`Module/makesetup` shell script;
-* :file:`setup.py`: C extensions built using the :mod:`distutils` module.
+* :file:`setup.py`: C extensions built using the ``setuptools`` package.
Main build steps
----------------
diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst
index 7d2fcb586b3f2..1025c14e397df 100644
--- a/Doc/using/windows.rst
+++ b/Doc/using/windows.rst
@@ -1187,11 +1187,10 @@ shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
cx_Freeze
---------
-`cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a :mod:`distutils`
-extension (see :ref:`extending-distutils`) which wraps Python scripts into
-executable Windows programs (:file:`{*}.exe` files). When you have done this,
-you can distribute your application without requiring your users to install
-Python.
+`cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a ``distutils``
+extension which wraps Python scripts into executable Windows programs
+(:file:`{*}.exe` files). When you have done this, you can distribute your
+application without requiring your users to install Python.
Compiling Python on Windows
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index f753055c16ee2..59d68a192b8f7 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -2697,7 +2697,7 @@ projects.
However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as :ref:`install-index`
-and :ref:`distutils-index`.
+and :ref:`setuptools-index`.
.. seealso::
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index a09b60ffb331e..95e86550bc032 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -247,7 +247,7 @@ projects.
However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as :ref:`install-index`
-and :ref:`distutils-index`.
+and :ref:`setuptools-index`.
.. seealso::
More information about the Python-checkins
mailing list