Your IP : 216.73.216.240
Copyright Jason R. Coombs
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
.. 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.
.. _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://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords
.. 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) | |
+------------------------+--------------------------------+-------------------------