Upgrade to setuptools 61.1.0
This fixes Python 3.10 compat, but does remove Python2 compat.
Test: treehugger
Change-Id: I8e19ad8dec6b34482bfbe996413d3f793ada276c
diff --git a/docs/Makefile b/docs/Makefile
deleted file mode 100644
index 30bf10a..0000000
--- a/docs/Makefile
+++ /dev/null
@@ -1,75 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
-
-help:
- @echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " changes to make an overview over all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
-
-clean:
- -rm -rf build/*
-
-html:
- mkdir -p build/html build/doctrees
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
- @echo
- @echo "Build finished. The HTML pages are in build/html."
-
-pickle:
- mkdir -p build/pickle build/doctrees
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-web: pickle
-
-json:
- mkdir -p build/json build/doctrees
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- mkdir -p build/htmlhelp build/doctrees
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in build/htmlhelp."
-
-latex:
- mkdir -p build/latex build/doctrees
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
- @echo
- @echo "Build finished; the LaTeX files are in build/latex."
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
- "run these through (pdf)latex."
-
-changes:
- mkdir -p build/changes build/doctrees
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
- @echo
- @echo "The overview file is in build/changes."
-
-linkcheck:
- mkdir -p build/linkcheck build/doctrees
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in build/linkcheck/output.txt."
diff --git a/docs/_templates/indexsidebar.html b/docs/_templates/indexsidebar.html
deleted file mode 100644
index 80002d0..0000000
--- a/docs/_templates/indexsidebar.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<h3>Download</h3>
-
-<p>Current version: <b>{{ version }}</b></p>
-<p>Get Setuptools from the <a href="https://pypi.org/project/setuptools/"> Python Package Index</a>
-
-<h3>Questions? Suggestions? Contributions?</h3>
-
-<p>Visit the <a href="https://github.com/pypa/setuptools">Setuptools project page</a> </p>
diff --git a/docs/_theme/nature/static/nature.css_t b/docs/_theme/nature/static/nature.css_t
deleted file mode 100644
index 1a65426..0000000
--- a/docs/_theme/nature/static/nature.css_t
+++ /dev/null
@@ -1,237 +0,0 @@
-/**
- * Sphinx stylesheet -- default theme
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- */
-
-@import url("basic.css");
-
-/* -- page layout ----------------------------------------------------------- */
-
-body {
- font-family: Arial, sans-serif;
- font-size: 100%;
- background-color: #111111;
- color: #555555;
- margin: 0;
- padding: 0;
-}
-
-div.documentwrapper {
- float: left;
- width: 100%;
-}
-
-div.bodywrapper {
- margin: 0 0 0 300px;
-}
-
-hr{
- border: 1px solid #B1B4B6;
-}
-
-div.document {
- background-color: #fafafa;
-}
-
-div.body {
- background-color: #ffffff;
- color: #3E4349;
- padding: 1em 30px 30px 30px;
- font-size: 0.9em;
-}
-
-div.footer {
- color: #555;
- width: 100%;
- padding: 13px 0;
- text-align: center;
- font-size: 75%;
-}
-
-div.footer a {
- color: #444444;
-}
-
-div.related {
- background-color: #6BA81E;
- line-height: 36px;
- color: #ffffff;
- text-shadow: 0px 1px 0 #444444;
- font-size: 1.1em;
-}
-
-div.related a {
- color: #E2F3CC;
-}
-
-div.related .right {
- font-size: 0.9em;
-}
-
-div.sphinxsidebar {
- font-size: 0.9em;
- line-height: 1.5em;
- width: 300px;
-}
-
-div.sphinxsidebarwrapper{
- padding: 20px 0;
-}
-
-div.sphinxsidebar h3,
-div.sphinxsidebar h4 {
- font-family: Arial, sans-serif;
- color: #222222;
- font-size: 1.2em;
- font-weight: bold;
- margin: 0;
- padding: 5px 10px;
- text-shadow: 1px 1px 0 white
-}
-
-div.sphinxsidebar h3 a {
- color: #444444;
-}
-
-div.sphinxsidebar p {
- color: #888888;
- padding: 5px 20px;
- margin: 0.5em 0px;
-}
-
-div.sphinxsidebar p.topless {
-}
-
-div.sphinxsidebar ul {
- margin: 10px 10px 10px 20px;
- padding: 0;
- color: #000000;
-}
-
-div.sphinxsidebar a {
- color: #444444;
-}
-
-div.sphinxsidebar a:hover {
- color: #E32E00;
-}
-
-div.sphinxsidebar input {
- border: 1px solid #cccccc;
- font-family: sans-serif;
- font-size: 1.1em;
- padding: 0.15em 0.3em;
-}
-
-div.sphinxsidebar input[type=text]{
- margin-left: 20px;
-}
-
-/* -- body styles ----------------------------------------------------------- */
-
-a {
- color: #005B81;
- text-decoration: none;
-}
-
-a:hover {
- color: #E32E00;
-}
-
-div.body h1,
-div.body h2,
-div.body h3,
-div.body h4,
-div.body h5,
-div.body h6 {
- font-family: Arial, sans-serif;
- font-weight: normal;
- color: #212224;
- margin: 30px 0px 10px 0px;
- padding: 5px 0 5px 0px;
- text-shadow: 0px 1px 0 white;
- border-bottom: 1px solid #C8D5E3;
-}
-
-div.body h1 { margin-top: 0; font-size: 200%; }
-div.body h2 { font-size: 150%; }
-div.body h3 { font-size: 120%; }
-div.body h4 { font-size: 110%; }
-div.body h5 { font-size: 100%; }
-div.body h6 { font-size: 100%; }
-
-a.headerlink {
- color: #c60f0f;
- font-size: 0.8em;
- padding: 0 4px 0 4px;
- text-decoration: none;
-}
-
-a.headerlink:hover {
- background-color: #c60f0f;
- color: white;
-}
-
-div.body p, div.body dd, div.body li {
- line-height: 1.8em;
-}
-
-div.admonition p.admonition-title + p {
- display: inline;
-}
-
-div.highlight{
- background-color: white;
-}
-
-div.note {
- background-color: #eeeeee;
- border: 1px solid #cccccc;
-}
-
-div.seealso {
- background-color: #ffffcc;
- border: 1px solid #ffff66;
-}
-
-div.topic {
- background-color: #fafafa;
- border-width: 0;
-}
-
-div.warning {
- background-color: #ffe4e4;
- border: 1px solid #ff6666;
-}
-
-p.admonition-title {
- display: inline;
-}
-
-p.admonition-title:after {
- content: ":";
-}
-
-pre {
- padding: 10px;
- background-color: #fafafa;
- color: #222222;
- line-height: 1.5em;
- font-size: 1.1em;
- margin: 1.5em 0 1.5em 0;
- -webkit-box-shadow: 0px 0px 4px #d8d8d8;
- -moz-box-shadow: 0px 0px 4px #d8d8d8;
- box-shadow: 0px 0px 4px #d8d8d8;
-}
-
-tt {
- color: #222222;
- padding: 1px 2px;
- font-size: 1.2em;
- font-family: monospace;
-}
-
-#table-of-contents ul {
- padding-left: 2em;
-}
-
diff --git a/docs/_theme/nature/static/pygments.css b/docs/_theme/nature/static/pygments.css
deleted file mode 100644
index 652b761..0000000
--- a/docs/_theme/nature/static/pygments.css
+++ /dev/null
@@ -1,54 +0,0 @@
-.c { color: #999988; font-style: italic } /* Comment */
-.k { font-weight: bold } /* Keyword */
-.o { font-weight: bold } /* Operator */
-.cm { color: #999988; font-style: italic } /* Comment.Multiline */
-.cp { color: #999999; font-weight: bold } /* Comment.preproc */
-.c1 { color: #999988; font-style: italic } /* Comment.Single */
-.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
-.ge { font-style: italic } /* Generic.Emph */
-.gr { color: #aa0000 } /* Generic.Error */
-.gh { color: #999999 } /* Generic.Heading */
-.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
-.go { color: #111 } /* Generic.Output */
-.gp { color: #555555 } /* Generic.Prompt */
-.gs { font-weight: bold } /* Generic.Strong */
-.gu { color: #aaaaaa } /* Generic.Subheading */
-.gt { color: #aa0000 } /* Generic.Traceback */
-.kc { font-weight: bold } /* Keyword.Constant */
-.kd { font-weight: bold } /* Keyword.Declaration */
-.kp { font-weight: bold } /* Keyword.Pseudo */
-.kr { font-weight: bold } /* Keyword.Reserved */
-.kt { color: #445588; font-weight: bold } /* Keyword.Type */
-.m { color: #009999 } /* Literal.Number */
-.s { color: #bb8844 } /* Literal.String */
-.na { color: #008080 } /* Name.Attribute */
-.nb { color: #999999 } /* Name.Builtin */
-.nc { color: #445588; font-weight: bold } /* Name.Class */
-.no { color: #ff99ff } /* Name.Constant */
-.ni { color: #800080 } /* Name.Entity */
-.ne { color: #990000; font-weight: bold } /* Name.Exception */
-.nf { color: #990000; font-weight: bold } /* Name.Function */
-.nn { color: #555555 } /* Name.Namespace */
-.nt { color: #000080 } /* Name.Tag */
-.nv { color: purple } /* Name.Variable */
-.ow { font-weight: bold } /* Operator.Word */
-.mf { color: #009999 } /* Literal.Number.Float */
-.mh { color: #009999 } /* Literal.Number.Hex */
-.mi { color: #009999 } /* Literal.Number.Integer */
-.mo { color: #009999 } /* Literal.Number.Oct */
-.sb { color: #bb8844 } /* Literal.String.Backtick */
-.sc { color: #bb8844 } /* Literal.String.Char */
-.sd { color: #bb8844 } /* Literal.String.Doc */
-.s2 { color: #bb8844 } /* Literal.String.Double */
-.se { color: #bb8844 } /* Literal.String.Escape */
-.sh { color: #bb8844 } /* Literal.String.Heredoc */
-.si { color: #bb8844 } /* Literal.String.Interpol */
-.sx { color: #bb8844 } /* Literal.String.Other */
-.sr { color: #808000 } /* Literal.String.Regex */
-.s1 { color: #bb8844 } /* Literal.String.Single */
-.ss { color: #bb8844 } /* Literal.String.Symbol */
-.bp { color: #999999 } /* Name.Builtin.Pseudo */
-.vc { color: #ff99ff } /* Name.Variable.Class */
-.vg { color: #ff99ff } /* Name.Variable.Global */
-.vi { color: #ff99ff } /* Name.Variable.Instance */
-.il { color: #009999 } /* Literal.Number.Integer.Long */
\ No newline at end of file
diff --git a/docs/_theme/nature/theme.conf b/docs/_theme/nature/theme.conf
deleted file mode 100644
index 1cc4004..0000000
--- a/docs/_theme/nature/theme.conf
+++ /dev/null
@@ -1,4 +0,0 @@
-[theme]
-inherit = basic
-stylesheet = nature.css
-pygments_style = tango
diff --git a/docs/artwork.rst b/docs/artwork.rst
new file mode 100644
index 0000000..907e62a
--- /dev/null
+++ b/docs/artwork.rst
@@ -0,0 +1,119 @@
+=======
+Artwork
+=======
+
+.. figure:: images/logo-over-white.svg
+ :align: center
+
+ Setuptools logo, designed in 2021 by `Anderson Bravalheri`_
+
+Elements of Design
+==================
+
+The main colours of the design are a dark pastel azure (``#336790``) and a pale
+orange (``#E5B62F``), referred in this document simply as "blue" and "yellow"
+respectively. The text uses the *Monoid* typeface, an open source webfont that
+was developed by Andreas Larsen and contributors in 2015 and is distributed
+under the MIT or SIL licenses (more information at
+https://github.com/larsenwork/monoid)
+
+
+Usage
+=====
+
+The preferred way of using the setuptools logo is over a white (or light)
+background. Alternatively, the following options can be considered, depending
+on the circumstances:
+
+- *"negative"* design - for dark backgrounds (e.g. website displayed in "dark
+ mode"): the white colour (``#FFFFFF``) of the background and the "blue"
+ (``#336790``) colour of the design can be swapped.
+- *"monochrome"* - when colours are not available (e.g. black and white printed
+ media): a completely black or white version of the logo can also be used.
+- *"banner"* mode: the symbol and text can be used alongside depending on the
+ available space.
+
+The following image illustrate these alternatives:
+
+.. image:: images/logo-demo.svg
+ :align: center
+
+Please refer to the SVG files in the `setuptools repository`_ for the specific
+shapes and proportions between the elements of the design.
+
+
+Working with the Design
+=======================
+
+The `setuptools repository`_ contains a series of vector representations of the
+design under the ``docs/images`` directory. These representations can be
+manipulated via any graphic editor that support SVG files,
+however the free and open-source software Inkscape_ is recommended for maximum
+compatibility.
+
+When selecting the right file to work with, file names including
+``editable-inkscape`` indicate "more editable" elements (e.g. editable text),
+while the others prioritise SVG paths for maximum reproducibility.
+
+Also notice that you might have to `install the correct fonts`_ to be able to
+visualise or edit some of the designs.
+
+
+Inspiration
+===========
+
+This design was inspired by :user:`cajhne`'s `original proposal`_ and the
+ancient symbol of the ouroboros_.
+It features a snake moving in a circular trajectory not only as a reference to
+the Python programming language but also to the `wheel package format`_ as one
+of the distribution formats supported by setuptools.
+The shape of the snake also resembles a cog, which together with the hammer is
+a nod to the two words that compose the name of the project.
+
+
+License
+=======
+
+
+This logo, design variations or a modified version may be used by anyone to
+refer to setuptools, but does not indicate endorsement by the project.
+
+Redistribution, usage and derivative works are permitted under the same license
+used by the setuptools software (MIT):
+
+.. code-block:: text
+
+ Copyright (c) Anderson Bravalheri
+
+ 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.
+
+ THE USAGE OF THIS LOGO AND ARTWORK DOES NOT INDICATE ENDORSEMENT BY THE
+ SETUPTOOLS PROJECT.
+
+Whenever possible, please make the image a link to
+https://github.com/pypa/setuptools or https://setuptools.pypa.io.
+
+
+.. _Anderson Bravalheri: https://github.com/abravalheri
+.. _Inkscape: https://inkscape.org
+.. _setuptools repository: https://github.com/pypa/setuptools
+.. _install the correct fonts: https://wiki.inkscape.org/wiki/Installing_fonts
+.. _original proposal: https://github.com/pypa/setuptools/issues/2227#issuecomment-653628344
+.. _wheel package format: https://www.python.org/dev/peps/pep-0427/
+.. _ouroboros: https://en.wikipedia.org/wiki/Ouroboros
diff --git a/docs/build_meta.rst b/docs/build_meta.rst
new file mode 100644
index 0000000..cb37272
--- /dev/null
+++ b/docs/build_meta.rst
@@ -0,0 +1,176 @@
+=======================================
+Build System Support
+=======================================
+
+What is it?
+-------------
+
+Python packaging has come `a long way <https://bernat.tech/posts/pep-517-518/>`_.
+
+The traditional ``setuptools`` way of packaging Python modules
+uses a ``setup()`` function within the ``setup.py`` script. Commands such as
+``python setup.py bdist`` or ``python setup.py bdist_wheel`` generate a
+distribution bundle and ``python setup.py install`` installs the distribution.
+This interface makes it difficult to choose other packaging tools without an
+overhaul. Because ``setup.py`` scripts allowed for arbitrary execution, it
+proved difficult to provide a reliable user experience across environments
+and history.
+
+`PEP 517 <https://www.python.org/dev/peps/pep-0517/>`_ therefore came to
+rescue and specified a new standard to
+package and distribute Python modules. Under PEP 517:
+
+ a ``pyproject.toml`` file is used to specify what program to use
+ for generating distribution.
+
+ Then, two functions provided by the program, ``build_wheel(directory: str)``
+ and ``build_sdist(directory: str)`` create the distribution bundle at the
+ specified ``directory``. The program is free to use its own configuration
+ script or extend the ``.toml`` file.
+
+ Lastly, ``pip install *.whl`` or ``pip install *.tar.gz`` does the actual
+ installation. If ``*.whl`` is available, ``pip`` will go ahead and copy
+ the files into ``site-packages`` directory. If not, ``pip`` will look at
+ ``pyproject.toml`` and decide what program to use to 'build from source'
+ (the default is ``setuptools``)
+
+With this standard, switching between packaging tools becomes a lot easier. ``build_meta``
+implements ``setuptools``' build system support.
+
+How to use it?
+--------------
+
+Starting with a package that you want to distribute. You will need your source
+scripts, a ``pyproject.toml`` file and a ``setup.cfg`` file::
+
+ ~/meowpkg/
+ pyproject.toml
+ setup.cfg
+ meowpkg/__init__.py
+
+The pyproject.toml file is required to specify the build system (i.e. what is
+being used to package your scripts and install from source). To use it with
+setuptools, the content would be::
+
+ [build-system]
+ requires = ["setuptools"]
+ build-backend = "setuptools.build_meta"
+
+The ``setuptools`` package implements the ``build_sdist``
+command and the ``wheel`` package implements the ``build_wheel``
+command; the latter is a dependency of the former
+exposed via :pep:`517` hooks.
+
+Use ``setuptools``' :ref:`declarative config <declarative config>` to
+specify the package information::
+
+ [metadata]
+ name = meowpkg
+ version = 0.0.1
+ description = a package that meows
+
+ [options]
+ packages = find:
+
+.. _building:
+
+Now generate the distribution. To build the package, use
+`PyPA build <https://pypa-build.readthedocs.io/en/latest/>`_::
+
+ $ pip install -q build
+ $ python -m build
+
+And now it's done! The ``.whl`` file and ``.tar.gz`` can then be distributed
+and installed::
+
+ dist/
+ meowpkg-0.0.1.whl
+ meowpkg-0.0.1.tar.gz
+
+ $ pip install dist/meowpkg-0.0.1.whl
+
+or::
+
+ $ pip install dist/meowpkg-0.0.1.tar.gz
+
+Dynamic build dependencies and other ``build_meta`` tweaks
+----------------------------------------------------------
+
+With the changes introduced by :pep:`517` and :pep:`518`, the
+``setup_requires`` configuration field was made deprecated in ``setup.cfg`` and
+``setup.py``, in favour of directly listing build dependencies in the
+``requires`` field of the ``build-system`` table of ``pyproject.toml``.
+This approach has a series of advantages and gives package managers and
+installers the ability to inspect in advance the build requirements and
+perform a series of optimisations.
+
+However some package authors might still need to dynamically inspect the final
+users machine before deciding these requirements. One way of doing that, as
+specified by :pep:`517`, is to "tweak" ``setuptools.build_meta`` by using a
+:pep:`in-tree backend <517#in-tree-build-backends>`.
+
+.. tip:: Before implementing a *in-tree* backend, have a look on
+ :pep:`PEP 508 <508#environment-markers>`. Most of the times, dependencies
+ with **environment markers** are enough to differentiate operating systems
+ and platforms.
+
+If you add the following configuration to your ``pyprojec.toml``:
+
+
+.. code-block:: toml
+
+ [build-system]
+ requires = ["setuptools", "wheel"]
+ build-backend = "backend"
+ backend-path = ["_custom_build"]
+
+
+then you should be able to implement a thin wrapper around ``build_meta`` in
+the ``_custom_build/backend.py`` file, as shown in the following example:
+
+.. code-block:: python
+
+ from setuptools import build_meta as _orig
+
+ prepare_metadata_for_build_wheel = _orig.prepare_metadata_for_build_wheel
+ build_wheel = _orig.build_wheel
+ build_sdist = _orig.build_sdist
+
+
+ def get_requires_for_build_wheel(self, config_settings=None):
+ return _orig.get_requires_for_build_wheel(config_settings) + [...]
+
+
+ def get_requires_for_build_sdist(self, config_settings=None):
+ return _orig.get_requires_for_build_sdist(config_settings) + [...]
+
+
+Note that you can override any of the functions specified in :pep:`PEP 517
+<517#build-backend-interface>`, not only the ones responsible for gathering
+requirements.
+
+.. important:: Make sure your backend script is included in the :doc:`source
+ distribution </userguide/distribution>`, otherwise the build will fail.
+ This can be done by using a SCM_/VCS_ plugin (like :pypi:`setuptools-scm`
+ and :pypi:`setuptools-svn`), or by correctly setting up :ref:`MANIFEST.in
+ <manifest>`.
+
+ If this is the first time you are using a customised backend, please have a
+ look on the generated ``.tar.gz`` and ``.whl``.
+ On POSIX systems that can be done with ``tar -tf dist/*.tar.gz``
+ and ``unzip -l dist/*.whl``.
+ On Windows systems you can rename the ``.whl`` to ``.zip`` to be able to
+ inspect it on the file explorer, and use the same ``tar`` command in a
+ command prompt (alternativelly there are GUI programs like `7-zip`_ that
+ handle ``.tar.gz``).
+
+ In general the backend script should be present in the ``.tar.gz`` (so the
+ project can be build from the source) but not in the ``.whl`` (otherwise the
+ backend script would end up being distributed alongside your package).
+ See ":doc:`/userguide/package_discovery`" for more details about package
+ files.
+
+
+.. _SCM: https://en.wikipedia.org/wiki/Software_configuration_management
+.. _VCS: https://en.wikipedia.org/wiki/Version_control
+.. _7-zip: https://www.7-zip.org
diff --git a/docs/conf.py b/docs/conf.py
index f7d0230..4ebb521 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,87 +1,6 @@
-# -*- coding: utf-8 -*-
-#
-# Setuptools documentation build configuration file, created by
-# sphinx-quickstart on Fri Jul 17 14:22:37 2009.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default
+extensions = ['sphinx.ext.autodoc', 'jaraco.packaging.sphinx', 'rst.linker']
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-import subprocess
-import sys
-import os
-
-
-# hack to run the bootstrap script so that jaraco.packaging.sphinx
-# can invoke setup.py
-'READTHEDOCS' in os.environ and subprocess.check_call(
- [sys.executable, 'bootstrap.py'],
- cwd=os.path.join(os.path.dirname(__file__), os.path.pardir),
-)
-
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['jaraco.packaging.sphinx', 'rst.linker', 'sphinx.ext.autosectionlabel']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.txt'
-
-# The master toctree document.
-master_doc = 'index'
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'nature'
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_theme']
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-html_sidebars = {'index': 'indexsidebar.html'}
-
-# If false, no module index is generated.
-html_use_modindex = False
-
-# If false, no index is generated.
-html_use_index = False
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
- ('index', 'Setuptools.tex', 'Setuptools Documentation',
- 'The fellowship of the packaging', 'manual'),
-]
+master_doc = "index"
link_files = {
'../CHANGES.rst': dict(
@@ -91,7 +10,11 @@
),
replace=[
dict(
- pattern=r'(Issue )?#(?P<issue>\d+)',
+ pattern=r'(?<!\w)PR #(?P<pull>\d+)',
+ url='{package_url}/pull/{pull}',
+ ),
+ dict(
+ pattern=r'(?<!\w)(Issue )?#(?P<issue>\d+)',
url='{package_url}/issues/{issue}',
),
dict(
@@ -115,7 +38,7 @@
url='http://bugs.jython.org/issue{jython}',
),
dict(
- pattern=r'Python #(?P<python>\d+)',
+ pattern=r'(Python #|bpo-)(?P<python>\d+)',
url='http://bugs.python.org/issue{python}',
),
dict(
@@ -135,7 +58,7 @@
url='{GH}/pypa/packaging/blob/{packaging_ver}/CHANGELOG.rst',
),
dict(
- pattern=r'PEP[- ](?P<pep_number>\d+)',
+ pattern=r'(?<![`/\w])PEP[- ](?P<pep_number>\d+)',
url='https://www.python.org/dev/peps/pep-{pep_number:0>4}/',
),
dict(
@@ -143,9 +66,150 @@
url='{GH}/jaraco/setuptools_svn/issues/{setuptools_svn}',
),
dict(
+ pattern=r'pypa/(?P<issue_repo>[\-\.\w]+)#(?P<issue_number>\d+)',
+ url='{GH}/pypa/{issue_repo}/issues/{issue_number}',
+ ),
+ dict(
+ pattern=r'pypa/(?P<commit_repo>[\-\.\w]+)@(?P<commit_number>[\da-f]+)',
+ url='{GH}/pypa/{commit_repo}/commit/{commit_number}',
+ ),
+ dict(
pattern=r'^(?m)((?P<scm_version>v?\d+(\.\d+){1,2}))\n[-=]+\n',
with_scm='{text}\n{rev[timestamp]:%d %b %Y}\n',
),
],
),
}
+
+# Be strict about any broken references:
+nitpicky = True
+
+# Include Python intersphinx mapping to prevent failures
+# jaraco/skeleton#51
+extensions += ['sphinx.ext.intersphinx']
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3', None),
+}
+
+intersphinx_mapping.update({
+ 'pypa-build': ('https://pypa-build.readthedocs.io/en/latest/', None)
+})
+
+# Add support for linking usernames
+github_url = 'https://github.com'
+github_repo_org = 'pypa'
+github_repo_name = 'setuptools'
+github_repo_slug = f'{github_repo_org}/{github_repo_name}'
+github_repo_url = f'{github_url}/{github_repo_slug}'
+github_sponsors_url = f'{github_url}/sponsors'
+extlinks = {
+ 'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
+ 'pypi': ('https://pypi.org/project/%s', '%s'), # noqa: WPS323
+ 'wiki': ('https://wikipedia.org/wiki/%s', '%s'), # noqa: WPS323
+}
+extensions += ['sphinx.ext.extlinks']
+
+# Ref: https://github.com/python-attrs/attrs/pull/571/files\
+# #diff-85987f48f1258d9ee486e3191495582dR82
+default_role = 'any'
+
+# HTML theme
+html_theme = 'furo'
+html_logo = "images/logo.svg"
+
+html_theme_options = {
+ "sidebar_hide_name": True,
+ "light_css_variables": {
+ "color-brand-primary": "#336790", # "blue"
+ "color-brand-content": "#336790",
+ },
+ "dark_css_variables": {
+ "color-brand-primary": "#E5B62F", # "yellow"
+ "color-brand-content": "#E5B62F",
+ },
+}
+
+# Add support for inline tabs
+extensions += ['sphinx_inline_tabs']
+
+# Support for distutils
+
+# Ref: https://stackoverflow.com/a/30624034/595220
+nitpick_ignore = [
+ ('c:func', 'SHGetSpecialFolderPath'), # ref to MS docs
+ ('envvar', 'DISTUTILS_DEBUG'), # undocumented
+ ('envvar', 'HOME'), # undocumented
+ ('envvar', 'PLAT'), # undocumented
+ ('py:attr', 'CCompiler.language_map'), # undocumented
+ ('py:attr', 'CCompiler.language_order'), # undocumented
+ ('py:class', 'distutils.dist.Distribution'), # undocumented
+ ('py:class', 'distutils.extension.Extension'), # undocumented
+ ('py:class', 'BorlandCCompiler'), # undocumented
+ ('py:class', 'CCompiler'), # undocumented
+ ('py:class', 'CygwinCCompiler'), # undocumented
+ ('py:class', 'distutils.dist.DistributionMetadata'), # undocumented
+ ('py:class', 'FileList'), # undocumented
+ ('py:class', 'IShellLink'), # ref to MS docs
+ ('py:class', 'MSVCCompiler'), # undocumented
+ ('py:class', 'OptionDummy'), # undocumented
+ ('py:class', 'UnixCCompiler'), # undocumented
+ ('py:exc', 'CompileError'), # undocumented
+ ('py:exc', 'DistutilsExecError'), # undocumented
+ ('py:exc', 'DistutilsFileError'), # undocumented
+ ('py:exc', 'LibError'), # undocumented
+ ('py:exc', 'LinkError'), # undocumented
+ ('py:exc', 'PreprocessError'), # undocumented
+ ('py:func', 'distutils.CCompiler.new_compiler'), # undocumented
+ # undocumented:
+ ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'),
+ ('py:func', 'distutils.file_util._copy_file_contents'), # undocumented
+ ('py:func', 'distutils.log.debug'), # undocumented
+ ('py:func', 'distutils.spawn.find_executable'), # undocumented
+ ('py:func', 'distutils.spawn.spawn'), # undocumented
+ # TODO: check https://docutils.rtfd.io in the future
+ ('py:mod', 'docutils'), # there's no Sphinx site documenting this
+]
+
+# Allow linking objects on other Sphinx sites seamlessly:
+intersphinx_mapping.update(
+ python2=('https://docs.python.org/2', None),
+ python=('https://docs.python.org/3', None),
+)
+
+# Add support for the unreleased "next-version" change notes
+extensions += ['sphinxcontrib.towncrier']
+# Extension needs a path from here to the towncrier config.
+towncrier_draft_working_directory = '..'
+# Avoid an empty section for unpublished changes.
+towncrier_draft_include_empty = False
+
+extensions += ['jaraco.tidelift']
+
+# Add icons (aka "favicons") to documentation
+extensions += ['sphinx-favicon']
+html_static_path = ['images'] # should contain the folder with icons
+
+# List of dicts with <link> HTML attributes
+# static-file points to files in the html_static_path (href is computed)
+favicons = [
+ { # "Catch-all" goes first, otherwise some browsers will overwrite
+ "rel": "icon",
+ "type": "image/svg+xml",
+ "static-file": "logo-symbol-only.svg",
+ "sizes": "any"
+ },
+ { # Version with thicker strokes for better visibility at smaller sizes
+ "rel": "icon",
+ "type": "image/svg+xml",
+ "static-file": "favicon.svg",
+ "sizes": "16x16 24x24 32x32 48x48"
+ },
+ # rel="apple-touch-icon" does not support SVG yet
+]
+
+intersphinx_mapping['pip'] = 'https://pip.pypa.io/en/latest', None
+intersphinx_mapping['PyPUG'] = ('https://packaging.python.org/en/latest/', None)
+intersphinx_mapping['packaging'] = ('https://packaging.pypa.io/en/latest/', None)
+intersphinx_mapping['importlib-resources'] = (
+ 'https://importlib-resources.readthedocs.io/en/latest', None
+)
diff --git a/docs/deprecated/distutils-legacy.rst b/docs/deprecated/distutils-legacy.rst
new file mode 100644
index 0000000..e73cdff
--- /dev/null
+++ b/docs/deprecated/distutils-legacy.rst
@@ -0,0 +1,36 @@
+Porting from Distutils
+======================
+
+Setuptools and the PyPA have a `stated goal <https://github.com/pypa/packaging-problems/issues/127>`_ to make Setuptools the reference API for distutils.
+
+Since the 60.0.0 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is enabled by default. To disable the use of this copy of distutils when invoking setuptools, set the enviroment variable:
+
+ SETUPTOOLS_USE_DISTUTILS=stdlib
+
+
+Prefer Setuptools
+-----------------
+
+As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements.
+
+``distutils.core.setup`` → ``setuptools.setup``
+
+``distutils.cmd.Command`` → ``setuptools.Command``
+
+``distutils.command.{build_clib,build_ext,build_py,sdist}`` → ``setuptools.command.*``
+
+``distutils.log`` → :mod:`logging` (standard library)
+
+``distutils.version.*`` → :doc:`packaging.version.* <packaging:version>`
+
+``distutils.errors.*`` → ``setuptools.errors.*`` [#errors]_
+
+
+Migration advice is also provided by :pep:`PEP 632 <632#migration-advice>`.
+
+If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker <https://github.com/pypa/setuptools/issues/>`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported.
+
+
+.. [#errors] Please notice errors related to the command line usage of
+ ``setup.py``, such as ``DistutilsArgError``, are intentionally not exposed
+ by setuptools, since this is considered a deprecated practice.
diff --git a/docs/deprecated/distutils/_setuptools_disclaimer.rst b/docs/deprecated/distutils/_setuptools_disclaimer.rst
new file mode 100644
index 0000000..628c2e4
--- /dev/null
+++ b/docs/deprecated/distutils/_setuptools_disclaimer.rst
@@ -0,0 +1,5 @@
+.. note::
+
+ This document is being retained solely until the ``setuptools`` documentation
+ at https://setuptools.pypa.io/en/latest/setuptools.html
+ independently covers all of the relevant information currently included here.
diff --git a/docs/deprecated/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst
new file mode 100644
index 0000000..f00ed74
--- /dev/null
+++ b/docs/deprecated/distutils/apiref.rst
@@ -0,0 +1,2053 @@
+.. _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.pypa.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) | |
+ +------------------------+--------------------------------+---------------------------+
+ | *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? Mac OS X 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:`~CCompiler.language_map` (a dictionary), and :attr:`~CCompiler.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.spawn.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.cygwinccompiler` --- 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:`~distutils.file_util.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:`~distutils.file_util._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 Mac OS X 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 Mac OS X 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 Mac OS X:
+
+ * ``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 fully-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:`~distutils.extension.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:`~FancyGetopt.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:`~distutils.spawn.spawn` function, a
+front-end to various platform-specific functions for launching another
+program in a sub-process.
+Also provides :func:`~distutils.spawn.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.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. moduleauthor:: Greg Ward <gward@python.net>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@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.
+
+
+.. 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 ``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_msi` --- Build a Microsoft Installer binary package
+=================================================================================
+
+.. module:: distutils.command.bdist_msi
+ :synopsis: Build a binary distribution as a Windows MSI file
+
+.. class:: bdist_msi
+
+.. deprecated:: 3.9
+ Use bdist_wheel (wheel packages) instead.
+
+ Builds a `Windows Installer`_ (.msi) binary package.
+
+ .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
+
+ In most cases, the ``bdist_msi`` installer is a better choice than the
+ ``bdist_wininst`` installer, because it provides better support for
+ Win64 platforms, allows administrators to perform non-interactive
+ installations, and allows installation through group policies.
+
+
+:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
+===========================================================================================
+
+.. module:: distutils.command.bdist_rpm
+ :synopsis: Build a binary distribution as a Redhat RPM and SRPM
+
+
+.. % todo
+
+
+:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
+====================================================================
+
+.. module:: distutils.command.bdist_wininst
+ :synopsis: Build a Windows installer
+
+.. deprecated:: 3.8
+ Use bdist_wheel (wheel packages) instead.
+
+
+.. % 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
+
+
+: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:`~distutils.core.setup` function.
+
+.. % todo
diff --git a/docs/deprecated/distutils/builtdist.rst b/docs/deprecated/distutils/builtdist.rst
new file mode 100644
index 0000000..e032c03
--- /dev/null
+++ b/docs/deprecated/distutils/builtdist.rst
@@ -0,0 +1,479 @@
+.. _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` | |
++-------------+------------------------------+---------+
+| ``wininst`` | self-extracting ZIP file for | \(4) |
+| | Windows | |
++-------------+------------------------------+---------+
+| ``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 |
++--------------------------+-------------------------------------+
+| :command:`bdist_wininst` | wininst |
++--------------------------+-------------------------------------+
+| :command:`bdist_msi` | msi |
++--------------------------+-------------------------------------+
+
+.. note::
+ bdist_wininst is deprecated since Python 3.8.
+
+.. note::
+ bdist_msi is deprecated since Python 3.9.
+
+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@example.org>" \
+ bdist_wininst --target-version="2.0"
+
+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.)
+
+
+.. _creating-wininst:
+
+Creating Windows Installers
+===========================
+
+.. warning::
+ bdist_wininst is deprecated since Python 3.8.
+
+.. warning::
+ bdist_msi is deprecated since Python 3.9.
+
+Executable installers are the natural format for binary distributions on
+Windows. They display a nice graphical user interface, display some information
+about the module distribution to be installed taken from the metadata in the
+setup script, let the user select a few options, and start or cancel the
+installation.
+
+Since the metadata is taken from the setup script, creating Windows installers
+is usually as easy as running::
+
+ python setup.py bdist_wininst
+
+or the :command:`bdist` command with the :option:`!--formats` option::
+
+ python setup.py bdist --formats=wininst
+
+If you have a pure module distribution (only containing pure Python modules and
+packages), the resulting installer will be version independent and have a name
+like :file:`foo-1.0.win32.exe`. Note that creating ``wininst`` binary
+distributions in only supported on Windows systems.
+
+If you have a non-pure distribution, the extensions can only be created on a
+Windows platform, and will be Python version dependent. The installer filename
+will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You
+have to create a separate installer for every Python version you want to
+support.
+
+The installer will try to compile pure modules into :term:`bytecode` after installation
+on the target system in normal and optimizing mode. If you don't want this to
+happen for some reason, you can run the :command:`bdist_wininst` command with
+the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize`
+option.
+
+By default the installer will display the cool "Python Powered" logo when it is
+run, but you can also supply your own 152x261 bitmap which must be a Windows
+:file:`.bmp` file with the :option:`!--bitmap` option.
+
+The installer will also display a large title on the desktop background window
+when it is run, which is constructed from the name of your distribution and the
+version number. This can be changed to another text by using the
+:option:`!--title` option.
+
+The installer file will be written to the "distribution directory" --- normally
+:file:`dist/`, but customizable with the :option:`!--dist-dir` option.
+
+.. _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. The Windows Installers also
+support this option, so the command::
+
+ python setup.py build --plat-name=win-amd64 bdist_wininst
+
+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.
+
+
+Vista User Access Control (UAC)
+===============================
+
+Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control`
+option. The default is 'none' (meaning no UAC handling is done), and other
+valid values are 'auto' (meaning prompt for UAC elevation if Python was
+installed for all users) and 'force' (meaning always prompt for elevation).
+
+.. note::
+ bdist_wininst is deprecated since Python 3.8.
+
+.. note::
+ bdist_msi is deprecated since Python 3.9.
diff --git a/docs/deprecated/distutils/commandref.rst b/docs/deprecated/distutils/commandref.rst
new file mode 100644
index 0000000..0f6fe2a
--- /dev/null
+++ b/docs/deprecated/distutils/commandref.rst
@@ -0,0 +1,106 @@
+.. _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}}
+.. % \subsection{\protect\command{bdist\_wininst}}
+
+
diff --git a/docs/deprecated/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst
new file mode 100644
index 0000000..328936f
--- /dev/null
+++ b/docs/deprecated/distutils/configfile.rst
@@ -0,0 +1,144 @@
+.. _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 ``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 ``pkg.mod1`` and ``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@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/docs/deprecated/distutils/examples.rst b/docs/deprecated/distutils/examples.rst
new file mode 100644
index 0000000..d098465
--- /dev/null
+++ b/docs/deprecated/distutils/examples.rst
@@ -0,0 +1,340 @@
+.. _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 ``foo`` and ``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 ``foo`` and ``bar``
+modules belong in package ``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 ``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 ``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 ``foopkg``, then
+
+With exactly the same source tree layout, this extension can be put in the
+``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@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:`~distutils.dist.DistributionMetadata.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/docs/deprecated/distutils/extending.rst b/docs/deprecated/distutils/extending.rst
new file mode 100644
index 0000000..c99d3c7
--- /dev/null
+++ b/docs/deprecated/distutils/extending.rst
@@ -0,0 +1,98 @@
+.. _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:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command`
+indirectly, directly subclassing the command they are replacing. Commands are
+required to derive from :class:`~distutils.cmd.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`, ``distcmds``, and ``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 ``distcmds.bdist_openpkg.bdist_openpkg`` or
+``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/docs/deprecated/distutils/index.rst b/docs/deprecated/distutils/index.rst
new file mode 100644
index 0000000..1f72a25
--- /dev/null
+++ b/docs/deprecated/distutils/index.rst
@@ -0,0 +1,42 @@
+.. _distutils-index:
+
+##############################################
+ Distributing Python Modules (Legacy version)
+##############################################
+
+:Authors: Greg Ward, Anthony Baxter
+:Email: distutils-sig@python.org
+
+.. seealso::
+
+ :ref:`distributing-index`
+ The up to date module distribution documentations
+
+.. 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/docs/deprecated/distutils/introduction.rst b/docs/deprecated/distutils/introduction.rst
new file mode 100644
index 0000000..7491b96
--- /dev/null
+++ b/docs/deprecated/distutils/introduction.rst
@@ -0,0 +1,214 @@
+.. _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 ``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:`~distutils.core.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 ``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).
+
+If you want to make things really easy for your users, you can create one or
+more built distributions for them. For instance, if you are running on a
+Windows machine, and want to make things easy for other Windows users, you can
+create an executable installer (the most appropriate type of built distribution
+for this platform) with the :command:`bdist_wininst` command. For example::
+
+ python setup.py bdist_wininst
+
+will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
+directory.
+
+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/docs/deprecated/distutils/packageindex.rst b/docs/deprecated/distutils/packageindex.rst
new file mode 100644
index 0000000..ccb9a59
--- /dev/null
+++ b/docs/deprecated/distutils/packageindex.rst
@@ -0,0 +1,16 @@
+: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/docs/deprecated/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst
new file mode 100644
index 0000000..f49c4f8
--- /dev/null
+++ b/docs/deprecated/distutils/setupscript.rst
@@ -0,0 +1,715 @@
+.. _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:`~distutils.core.setup`, and most information
+supplied to the Distutils by the module developer is supplied as keyword
+arguments to :func:`~distutils.core.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@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 ``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 ``foo`` package right in
+:file:`lib`, the ``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 ``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
+``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:`~distutils.core.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 ``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:`~distutils.extension.Extension` class can be imported from :mod:`distutils.core` along
+with :func:`~distutils.core.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:`~distutils.extension.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 ``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:`~distutils.core.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 ``pkg.foo``, and
+:file:`bar.c` to ``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:`~distutils.core.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:`~distutils.core.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:`~distutils.core.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:`~distutils.core.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/docs/deprecated/distutils/sourcedist.rst b/docs/deprecated/distutils/sourcedist.rst
new file mode 100644
index 0000000..0600663
--- /dev/null
+++ b/docs/deprecated/distutils/sourcedist.rst
@@ -0,0 +1,242 @@
+.. _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 | |
+| | (:file:`.tar.bz2`) | |
++-----------+-------------------------+---------+
+| ``xztar`` | xz'ed tar file | |
+| | (:file:`.tar.xz`) | |
++-----------+-------------------------+---------+
+| ``ztar`` | compressed tar file | \(4) |
+| | (:file:`.tar.Z`) | |
++-----------+-------------------------+---------+
+| ``tar`` | tar file (:file:`.tar`) | |
++-----------+-------------------------+---------+
+
+.. 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.
+
+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/docs/deprecated/distutils/uploading.rst b/docs/deprecated/distutils/uploading.rst
new file mode 100644
index 0000000..4c391ca
--- /dev/null
+++ b/docs/deprecated/distutils/uploading.rst
@@ -0,0 +1,8 @@
+: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/docs/easy_install.txt b/docs/deprecated/easy_install.rst
similarity index 67%
rename from docs/easy_install.txt
rename to docs/deprecated/easy_install.rst
index 5c99234..3cf3bea 100644
--- a/docs/easy_install.txt
+++ b/docs/deprecated/easy_install.rst
@@ -2,6 +2,12 @@
Easy Install
============
+.. warning::
+ Easy Install is deprecated. Do not use it. Instead use pip. If
+ you think you need Easy Install, please reach out to the PyPA
+ team (a ticket to pip or setuptools is fine), describing your
+ use-case.
+
Easy Install is a python module (``easy_install``) bundled with ``setuptools``
that lets you automatically download, build, install, and manage Python
packages.
@@ -17,10 +23,7 @@
(Also, if you'd like to learn about how you can use ``setuptools`` to make your
own packages work better with EasyInstall, or provide EasyInstall-like features
without requiring your users to use EasyInstall directly, you'll probably want
-to check out the full `setuptools`_ documentation as well.)
-
-.. contents:: **Table of Contents**
-
+to check out the full documentation as well.)
Using "Easy Install"
====================
@@ -31,11 +34,11 @@
Installing "Easy Install"
-------------------------
-Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_
+Please see the :pypi:`setuptools` on the package index
for download links and basic installation instructions for each of the
supported platforms.
-You will need at least Python 3.3 or 2.7. An ``easy_install`` script will be
+You will need at least Python 3.5 or 2.7. An ``easy_install`` script will be
installed in the normal location for Python scripts on your platform.
Note that the instructions on the setuptools PyPI page assume that you are
@@ -311,8 +314,8 @@
directory, you can also retarget the installation location for scripts so they
go on a directory that's already on the ``PATH``. For more information see
`Command-Line Options`_ and `Configuration Files`_. During installation,
-pass command line options (such as ``--script-dir``) to
-``ez_setup.py`` to control where ``easy_install.exe`` will be installed.
+pass command line options (such as ``--script-dir``) to control where
+scripts will be installed.
Windows Executable Launcher
@@ -1017,10 +1020,7 @@
scoped to the cloned python install and is used in the normal way. "virtualenv" does offer various features
that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages.
-Please refer to the `virtualenv`_ documentation for more details.
-
-.. _virtualenv: https://pypi.org/project/virtualenv/
-
+Please refer to the :pypi:`virtualenv` documentation for more details.
Package Index "API"
@@ -1077,546 +1077,3 @@
8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
automatically use ``index.html`` files, if present, when trying to read a
directory with a trailing ``/`` on the URL.
-
-
-Backward Compatibility
-~~~~~~~~~~~~~~~~~~~~~~
-
-Package indexes that wish to support setuptools versions prior to 0.6b4 should
-also follow these rules:
-
-* Homepage and download links must be preceded with ``"<th>Home Page"`` or
- ``"<th>Download URL"``, in addition to (or instead of) the ``rel=""``
- attributes on the actual links. These marker strings do not need to be
- visible, or uncommented, however! For example, the following is a valid
- homepage link that will work with any version of setuptools::
-
- <li>
- <strong>Home Page:</strong>
- <!-- <th>Home Page -->
- <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a>
- </li>
-
- Even though the marker string is in an HTML comment, older versions of
- EasyInstall will still "see" it and know that the link that follows is the
- project's home page URL.
-
-* The pages described by paragraph 3(b) of the preceding section *must*
- contain the string ``"Index of Packages</title>"`` somewhere in their text.
- This can be inside of an HTML comment, if desired, and it can be anywhere
- in the page. (Note: this string MUST NOT appear on normal project pages, as
- described in paragraphs 2 and 3(a)!)
-
-In addition, for compatibility with PyPI versions that do not use ``#md5=``
-fragment IDs, EasyInstall uses the following regular expression to match PyPI's
-displayed MD5 info (broken onto two lines for readability)::
-
- <a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5
- &digest=([0-9a-f]{32})">md5</a>\)
-
-History
-=======
-
-0.6c9
- * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting
- is flattened out in the resulting egg. (There was a case-sensitivity
- problem that affected some distributions, notably ``pywin32``.)
-
- * Prevent ``--help-commands`` and other junk from showing under Python 2.5
- when running ``easy_install --help``.
-
- * Fixed GUI scripts sometimes not executing on Windows
-
- * Fixed not picking up dependency links from recursive dependencies.
-
- * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs
-
- * Changes for Jython compatibility
-
- * Improved error message when a requirement is also a directory name, but the
- specified directory is not a source package.
-
- * Fixed ``--allow-hosts`` option blocking ``file:`` URLs
-
- * Fixed HTTP SVN detection failing when the page title included a project
- name (e.g. on SourceForge-hosted SVN)
-
- * Fix Jython script installation to handle ``#!`` lines better when
- ``sys.executable`` is a script.
-
- * Removed use of deprecated ``md5`` module if ``hashlib`` is available
-
- * Keep site directories (e.g. ``site-packages``) from being included in
- ``.pth`` files.
-
-0.6c7
- * ``ftp:`` download URLs now work correctly.
-
- * The default ``--index-url`` is now ``https://pypi.python.org/simple``, to use
- the Python Package Index's new simpler (and faster!) REST API.
-
-0.6c6
- * EasyInstall no longer aborts the installation process if a URL it wants to
- retrieve can't be downloaded, unless the URL is an actual package download.
- Instead, it issues a warning and tries to keep going.
-
- * Fixed distutils-style scripts originally built on Windows having their line
- endings doubled when installed on any platform.
-
- * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects
- installed using ``setup.py develop``.
-
- * Fixed not HTML-decoding URLs scraped from web pages
-
-0.6c5
- * Fixed ``.dll`` files on Cygwin not having executable permissions when an egg
- is installed unzipped.
-
-0.6c4
- * Added support for HTTP "Basic" authentication using ``http://user:pass@host``
- URLs. If a password-protected page contains links to the same host (and
- protocol), those links will inherit the credentials used to access the
- original page.
-
- * Removed all special support for Sourceforge mirrors, as Sourceforge's
- mirror system now works well for non-browser downloads.
-
- * Fixed not recognizing ``win32.exe`` installers that included a custom
- bitmap.
-
- * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they
- are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as
- is done by ``os.urandom()`` on some platforms).
-
- * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable``
- has a space in it (e.g., the user installed Python to a ``Program Files``
- directory).
-
-0.6c3
- * You can once again use "python -m easy_install" with Python 2.4 and above.
-
- * Python 2.5 compatibility fixes added.
-
-0.6c2
- * Windows script wrappers now support quoted arguments and arguments
- containing spaces. (Patch contributed by Jim Fulton.)
-
- * The ``ez_setup.py`` script now actually works when you put a setuptools
- ``.egg`` alongside it for bootstrapping an offline machine.
-
- * A writable installation directory on ``sys.path`` is no longer required to
- download and extract a source distribution using ``--editable``.
-
- * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable``
- contains non-ASCII characters, to prevent deprecation warnings about an
- unspecified encoding when the script is run.
-
-0.6c1
- * EasyInstall now includes setuptools version information in the
- ``User-Agent`` string sent to websites it visits.
-
-0.6b4
- * Fix creating Python wrappers for non-Python scripts
-
- * Fix ``ftp://`` directory listing URLs from causing a crash when used in the
- "Home page" or "Download URL" slots on PyPI.
-
- * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile
- or directory is deleted/overwritten.
-
- * Fix not recognizing HTML 404 pages from package indexes.
-
- * Allow ``file://`` URLs to be used as a package index. URLs that refer to
- directories will use an internally-generated directory listing if there is
- no ``index.html`` file in the directory.
-
- * Allow external links in a package index to be specified using
- ``rel="homepage"`` or ``rel="download"``, without needing the old
- PyPI-specific visible markup.
-
- * Suppressed warning message about possibly-misspelled project name, if an egg
- or link for that project name has already been seen.
-
-0.6b3
- * Fix local ``--find-links`` eggs not being copied except with
- ``--always-copy``.
-
- * Fix sometimes not detecting local packages installed outside of "site"
- directories.
-
- * Fix mysterious errors during initial ``setuptools`` install, caused by
- ``ez_setup`` trying to run ``easy_install`` twice, due to a code fallthru
- after deleting the egg from which it's running.
-
-0.6b2
- * Don't install or update a ``site.py`` patch when installing to a
- ``PYTHONPATH`` directory with ``--multi-version``, unless an
- ``easy-install.pth`` file is already in use there.
-
- * Construct ``.pth`` file paths in such a way that installing an egg whose
- name begins with ``import`` doesn't cause a syntax error.
-
- * Fixed a bogus warning message that wasn't updated since the 0.5 versions.
-
-0.6b1
- * Better ambiguity management: accept ``#egg`` name/version even if processing
- what appears to be a correctly-named distutils file, and ignore ``.egg``
- files with no ``-``, since valid Python ``.egg`` files always have a version
- number (but Scheme eggs often don't).
-
- * Support ``file://`` links to directories in ``--find-links``, so that
- easy_install can build packages from local source checkouts.
-
- * Added automatic retry for Sourceforge mirrors. The new download process is
- to first just try dl.sourceforge.net, then randomly select mirror IPs and
- remove ones that fail, until something works. The removed IPs stay removed
- for the remainder of the run.
-
- * Ignore bdist_dumb distributions when looking at download URLs.
-
-0.6a11
- * Process ``dependency_links.txt`` if found in a distribution, by adding the
- URLs to the list for scanning.
-
- * Use relative paths in ``.pth`` files when eggs are being installed to the
- same directory as the ``.pth`` file. This maximizes portability of the
- target directory when building applications that contain eggs.
-
- * Added ``easy_install-N.N`` script(s) for convenience when using multiple
- Python versions.
-
- * Added automatic handling of installation conflicts. Eggs are now shifted to
- the front of sys.path, in an order consistent with where they came from,
- making EasyInstall seamlessly co-operate with system package managers.
-
- The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options
- are now no longer necessary, and will generate warnings at the end of a
- run if you use them.
-
- * Don't recursively traverse subdirectories given to ``--find-links``.
-
-0.6a10
- * Added exhaustive testing of the install directory, including a spawn test
- for ``.pth`` file support, and directory writability/existence checks. This
- should virtually eliminate the need to set or configure ``--site-dirs``.
-
- * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of
- RTFM-ing. :)
-
- * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it
- manually to make it work. ``--multi-version`` is no longer a silent
- default; you must explicitly use it if installing to a non-PYTHONPATH,
- non-"site" directory.
-
- * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``,
- ``--install-dir``, and ``--script-dir`` options, whether on the command line
- or in configuration files.
-
- * Improved SourceForge mirror processing to work faster and be less affected
- by transient HTML changes made by SourceForge.
-
- * PyPI searches now use the exact spelling of requirements specified on the
- command line or in a project's ``install_requires``. Previously, a
- normalized form of the name was used, which could lead to unnecessary
- full-index searches when a project's name had an underscore (``_``) in it.
-
- * EasyInstall can now download bare ``.py`` files and wrap them in an egg,
- as long as you include an ``#egg=name-version`` suffix on the URL, or if
- the ``.py`` file is listed as the "Download URL" on the project's PyPI page.
- This allows third parties to "package" trivial Python modules just by
- linking to them (e.g. from within their own PyPI page or download links
- page).
-
- * The ``--always-copy`` option now skips "system" and "development" eggs since
- they can't be reliably copied. Note that this may cause EasyInstall to
- choose an older version of a package than what you expected, or it may cause
- downloading and installation of a fresh version of what's already installed.
-
- * The ``--find-links`` option previously scanned all supplied URLs and
- directories as early as possible, but now only directories and direct
- archive links are scanned immediately. URLs are not retrieved unless a
- package search was already going to go online due to a package not being
- available locally, or due to the use of the ``--update`` or ``-U`` option.
-
- * Fixed the annoying ``--help-commands`` wart.
-
-0.6a9
- * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside
- "baskets") when they weren't explicitly listed in the ``.pth`` file.
-
- * If more than one URL appears to describe the exact same distribution, prefer
- the shortest one. This helps to avoid "table of contents" CGI URLs like the
- ones on effbot.org.
-
- * Quote arguments to python.exe (including python's path) to avoid problems
- when Python (or a script) is installed in a directory whose name contains
- spaces on Windows.
-
- * Support full roundtrip translation of eggs to and from ``bdist_wininst``
- format. Running ``bdist_wininst`` on a setuptools-based package wraps the
- egg in an .exe that will safely install it as an egg (i.e., with metadata
- and entry-point wrapper scripts), and ``easy_install`` can turn the .exe
- back into an ``.egg`` file or directory and install it as such.
-
-0.6a8
- * Update for changed SourceForge mirror format
-
- * Fixed not installing dependencies for some packages fetched via Subversion
-
- * Fixed dependency installation with ``--always-copy`` not using the same
- dependency resolution procedure as other operations.
-
- * Fixed not fully removing temporary directories on Windows, if a Subversion
- checkout left read-only files behind
-
- * Fixed some problems building extensions when Pyrex was installed, especially
- with Python 2.4 and/or packages using SWIG.
-
-0.6a7
- * Fixed not being able to install Windows script wrappers using Python 2.3
-
-0.6a6
- * Added support for "traditional" PYTHONPATH-based non-root installation, and
- also the convenient ``virtual-python.py`` script, based on a contribution
- by Ian Bicking. The setuptools egg now contains a hacked ``site`` module
- that makes the PYTHONPATH-based approach work with .pth files, so that you
- can get the full EasyInstall feature set on such installations.
-
- * Added ``--no-deps`` and ``--allow-hosts`` options.
-
- * Improved Windows ``.exe`` script wrappers so that the script can have the
- same name as a module without confusing Python.
-
- * Changed dependency processing so that it's breadth-first, allowing a
- depender's preferences to override those of a dependee, to prevent conflicts
- when a lower version is acceptable to the dependee, but not the depender.
- Also, ensure that currently installed/selected packages aren't given
- precedence over ones desired by a package being installed, which could
- cause conflict errors.
-
-0.6a3
- * Improved error message when trying to use old ways of running
- ``easy_install``. Removed the ability to run via ``python -m`` or by
- running ``easy_install.py``; ``easy_install`` is the command to run on all
- supported platforms.
-
- * Improved wrapper script generation and runtime initialization so that a
- VersionConflict doesn't occur if you later install a competing version of a
- needed package as the default version of that package.
-
- * Fixed a problem parsing version numbers in ``#egg=`` links.
-
-0.6a2
- * EasyInstall can now install "console_scripts" defined by packages that use
- ``setuptools`` and define appropriate entry points. On Windows, console
- scripts get an ``.exe`` wrapper so you can just type their name. On other
- platforms, the scripts are installed without a file extension.
-
- * Using ``python -m easy_install`` or running ``easy_install.py`` is now
- DEPRECATED, since an ``easy_install`` wrapper is now available on all
- platforms.
-
-0.6a1
- * EasyInstall now does MD5 validation of downloads from PyPI, or from any link
- that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest.
-
- * EasyInstall now handles symlinks in target directories by removing the link,
- rather than attempting to overwrite the link's destination. This makes it
- easier to set up an alternate Python "home" directory (as described above in
- the `Non-Root Installation`_ section).
-
- * Added support for handling MacOS platform information in ``.egg`` filenames,
- based on a contribution by Kevin Dangoor. You may wish to delete and
- reinstall any eggs whose filename includes "darwin" and "Power_Macintosh",
- because the format for this platform information has changed so that minor
- OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
- previous OS version to become obsolete.
-
- * easy_install's dependency processing algorithms have changed. When using
- ``--always-copy``, it now ensures that dependencies are copied too. When
- not using ``--always-copy``, it tries to use a single resolution loop,
- rather than recursing.
-
- * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
- extensions.
-
- * Added ``--site-dirs`` option to allow adding custom "site" directories.
- Made ``easy-install.pth`` work in platform-specific alternate site
- directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X).
-
- * If you manually delete the current version of a package, the next run of
- EasyInstall against the target directory will now remove the stray entry
- from the ``easy-install.pth`` file.
-
- * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID
- as pointing to the named project's source checkout. Such URLs have a lower
- match precedence than any other kind of distribution, so they'll only be
- used if they have a higher version number than any other available
- distribution, or if you use the ``--editable`` option. The ``#egg``
- fragment can contain a version if it's formatted as ``#egg=proj-ver``,
- where ``proj`` is the project name, and ``ver`` is the version number. You
- *must* use the format for these values that the ``bdist_egg`` command uses;
- i.e., all non-alphanumeric runs must be condensed to single underscore
- characters.
-
- * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_
- above for more info. Also, slightly changed the behavior of the
- ``--build-directory`` option.
-
- * Fixed the setup script sandbox facility not recognizing certain paths as
- valid on case-insensitive platforms.
-
-0.5a12
- * Fix ``python -m easy_install`` not working due to setuptools being installed
- as a zipfile. Update safety scanner to check for modules that might be used
- as ``python -m`` scripts.
-
- * Misc. fixes for win32.exe support, including changes to support Python 2.4's
- changed ``bdist_wininst`` format.
-
-0.5a10
- * Put the ``easy_install`` module back in as a module, as it's needed for
- ``python -m`` to run it!
-
- * Allow ``--find-links/-f`` to accept local directories or filenames as well
- as URLs.
-
-0.5a9
- * EasyInstall now automatically detects when an "unmanaged" package or
- module is going to be on ``sys.path`` ahead of a package you're installing,
- thereby preventing the newer version from being imported. By default, it
- will abort installation to alert you of the problem, but there are also
- new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``)
- available to change the default behavior. (Note: this new feature doesn't
- take effect for egg files that were built with older ``setuptools``
- versions, because they lack the new metadata file required to implement it.)
-
- * The ``easy_install`` distutils command now uses ``DistutilsError`` as its
- base error type for errors that should just issue a message to stderr and
- exit the program without a traceback.
-
- * EasyInstall can now be given a path to a directory containing a setup
- script, and it will attempt to build and install the package there.
-
- * EasyInstall now performs a safety analysis on module contents to determine
- whether a package is likely to run in zipped form, and displays
- information about what modules may be doing introspection that would break
- when running as a zipfile.
-
- * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that
- would ordinarily be considered safe to unzip, and changed the meaning of
- ``--zip-ok/-z`` to "always leave everything zipped".
-
-0.5a8
- * There is now a separate documentation page for `setuptools`_; revision
- history that's not specific to EasyInstall has been moved to that page.
-
- .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
-
-0.5a5
- * Made ``easy_install`` a standard ``setuptools`` command, moving it from
- the ``easy_install`` module to ``setuptools.command.easy_install``. Note
- that if you were importing or extending it, you must now change your imports
- accordingly. ``easy_install.py`` is still installed as a script, but not as
- a module.
-
-0.5a4
- * Added ``--always-copy/-a`` option to always copy needed packages to the
- installation directory, even if they're already present elsewhere on
- sys.path. (In previous versions, this was the default behavior, but now
- you must request it.)
-
- * Added ``--upgrade/-U`` option to force checking PyPI for latest available
- version(s) of all packages requested by name and version, even if a matching
- version is available locally.
-
- * Added automatic installation of dependencies declared by a distribution
- being installed. These dependencies must be listed in the distribution's
- ``EGG-INFO`` directory, so the distribution has to have declared its
- dependencies by using setuptools. If a package has requirements it didn't
- declare, you'll still have to deal with them yourself. (E.g., by asking
- EasyInstall to find and install them.)
-
- * Added the ``--record`` option to ``easy_install`` for the benefit of tools
- that run ``setup.py install --record=filename`` on behalf of another
- packaging system.)
-
-0.5a3
- * Fixed not setting script permissions to allow execution.
-
- * Improved sandboxing so that setup scripts that want a temporary directory
- (e.g. pychecker) can still run in the sandbox.
-
-0.5a2
- * Fix stupid stupid refactoring-at-the-last-minute typos. :(
-
-0.5a1
- * Added support for converting ``.win32.exe`` installers to eggs on the fly.
- EasyInstall will now recognize such files by name and install them.
-
- * Fixed a problem with picking the "best" version to install (versions were
- being sorted as strings, rather than as parsed values)
-
-0.4a4
- * Added support for the distutils "verbose/quiet" and "dry-run" options, as
- well as the "optimize" flag.
-
- * Support downloading packages that were uploaded to PyPI (by scanning all
- links on package pages, not just the homepage/download links).
-
-0.4a3
- * Add progress messages to the search/download process so that you can tell
- what URLs it's reading to find download links. (Hopefully, this will help
- people report out-of-date and broken links to package authors, and to tell
- when they've asked for a package that doesn't exist.)
-
-0.4a2
- * Added support for installing scripts
-
- * Added support for setting options via distutils configuration files, and
- using distutils' default options as a basis for EasyInstall's defaults.
-
- * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the
- script installation directory option.
-
- * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
- Python includes SSL support.
-
-0.4a1
- * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
- and search PyPI for needed packages.
-
-0.3a4
- * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
- URL installs, to avoid running the wrong setup.py.
-
-0.3a3
- * Added ``--build-directory=DIR/-b DIR`` option.
-
- * Added "installation report" that explains how to use 'require()' when doing
- a multiversion install or alternate installation directory.
-
- * Added SourceForge mirror auto-select (Contributed by Ian Bicking)
-
- * Added "sandboxing" that stops a setup script from running if it attempts to
- write to the filesystem outside of the build area
-
- * Added more workarounds for packages with quirky ``install_data`` hacks
-
-0.3a2
- * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
- automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)
-
- * Misc. bug fixes
-
-0.3a1
- * Initial release.
-
-
-Future Plans
-============
-
-* Additional utilities to list/remove/verify packages
-* Signature checking? SSL? Ability to suppress PyPI search?
-* Display byte progress meter when downloading distributions and long pages?
-* Redirect stdout/stderr to log during run_setup?
diff --git a/docs/deprecated/functionalities.rst b/docs/deprecated/functionalities.rst
new file mode 100644
index 0000000..7213c5d
--- /dev/null
+++ b/docs/deprecated/functionalities.rst
@@ -0,0 +1,33 @@
+"Eggsecutable" Scripts
+----------------------
+
+.. deprecated:: 45.3.0
+
+Occasionally, there are situations where it's desirable to make an ``.egg``
+file directly executable. You can do this by including an entry point such
+as the following::
+
+ setup(
+ # other arguments here...
+ entry_points={
+ "setuptools.installation": [
+ "eggsecutable = my_package.some_module:main_func",
+ ]
+ }
+ )
+
+Any eggs built from the above setup script will include a short executable
+prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
+The prelude can be run on Unix-like platforms (including Mac and Linux) by
+invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
+``.egg`` file. For the executable prelude to run, the appropriate version of
+Python must be available via the ``PATH`` environment variable, under its
+"long" name. That is, if the egg is built for Python 2.3, there must be a
+``python2.3`` executable present in a directory on ``PATH``.
+
+IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
+invoked via symlinks. They *must* be invoked using their original filename, in
+order to ensure that, once running, ``pkg_resources`` will know what project
+and version is in use. The header script will check this and exit with an
+error if the ``.egg`` file has been renamed or is invoked via a symlink that
+changes its base name.
diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst
new file mode 100644
index 0000000..59fc7be
--- /dev/null
+++ b/docs/deprecated/index.rst
@@ -0,0 +1,20 @@
+======================================================
+Guides on backward compatibility & deprecated practice
+======================================================
+
+``Setuptools`` has undergone tremendous changes since its first debut. As its
+development continues to roll forward, many of the practice and mechanisms it
+had established are now considered deprecated. But they still remain relevant
+as a plethora of libraries continue to depend on them. Many people also find
+it necessary to equip themselves with the knowledge to better support backward
+compatibility. This guide aims to provide the essential information for such
+objectives.
+
+.. toctree::
+ :maxdepth: 1
+
+ python_eggs
+ easy_install
+ distutils/index
+ distutils-legacy
+ functionalities
diff --git a/docs/formats.txt b/docs/deprecated/python_eggs.rst
similarity index 97%
rename from docs/formats.txt
rename to docs/deprecated/python_eggs.rst
index a182eb9..59d1adc 100644
--- a/docs/formats.txt
+++ b/docs/deprecated/python_eggs.rst
@@ -6,9 +6,6 @@
-.. contents:: **Table of Contents**
-
-
----------------------
Eggs and their Formats
----------------------
@@ -299,11 +296,8 @@
A list of dependency URLs, one per line, as specified using the
``dependency_links`` keyword to ``setup()``. These may be direct
download URLs, or the URLs of web pages containing direct download
-links, and will be used by EasyInstall to find dependencies, as though
-the user had manually provided them via the ``--find-links`` command
-line option. Please see the setuptools manual and EasyInstall manual
-for more information on specifying this option, and for information on
-how EasyInstall processes ``--find-links`` URLs.
+links. Please see the setuptools manual for more information on
+specifying this option.
``depends.txt`` -- Obsolete, do not create!
@@ -679,4 +673,3 @@
to installed eggs. For example, an uninstallation tool could use this
data to identify what scripts can safely be removed, and/or identify
what scripts would stop working if a particular egg is uninstalled.
-
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
deleted file mode 100644
index b2c1a0c..0000000
--- a/docs/developer-guide.txt
+++ /dev/null
@@ -1,115 +0,0 @@
-================================
-Developer's Guide for Setuptools
-================================
-
-If you want to know more about contributing on Setuptools, this is the place.
-
-
-.. contents:: **Table of Contents**
-
-
--------------------
-Recommended Reading
--------------------
-
-Please read `How to write the perfect pull request
-<https://blog.jaraco.com/how-to-write-perfect-pull-request/>`_ for some tips
-on contributing to open source projects. Although the article is not
-authoritative, it was authored by the maintainer of Setuptools, so reflects
-his opinions and will improve the likelihood of acceptance and quality of
-contribution.
-
-------------------
-Project Management
-------------------
-
-Setuptools is maintained primarily in Github at `this home
-<https://github.com/pypa/setuptools>`_. Setuptools is maintained under the
-Python Packaging Authority (PyPA) with several core contributors. All bugs
-for Setuptools are filed and the canonical source is maintained in Github.
-
-User support and discussions are done through the issue tracker (for specific)
-issues, through the distutils-sig mailing list, or on IRC (Freenode) at
-#pypa.
-
-Discussions about development happen on the pypa-dev mailing list or on
-`Gitter <https://gitter.im/pypa/setuptools>`_.
-
------------------
-Authoring Tickets
------------------
-
-Before authoring any source code, it's often prudent to file a ticket
-describing the motivation behind making changes. First search to see if a
-ticket already exists for your issue. If not, create one. Try to think from
-the perspective of the reader. Explain what behavior you expected, what you
-got instead, and what factors might have contributed to the unexpected
-behavior. In Github, surround a block of code or traceback with the triple
-backtick "\`\`\`" so that it is formatted nicely.
-
-Filing a ticket provides a forum for justification, discussion, and
-clarification. The ticket provides a record of the purpose for the change and
-any hard decisions that were made. It provides a single place for others to
-reference when trying to understand why the software operates the way it does
-or why certain changes were made.
-
-Setuptools makes extensive use of hyperlinks to tickets in the changelog so
-that system integrators and other users can get a quick summary, but then
-jump to the in-depth discussion about any subject referenced.
-
------------
-Source Code
------------
-
-Grab the code at Github::
-
- $ git checkout https://github.com/pypa/setuptools
-
-If you want to contribute changes, we recommend you fork the repository on
-Github, commit the changes to your repository, and then make a pull request
-on Github. If you make some changes, don't forget to:
-
-- add a note in CHANGES.rst
-
-Please commit all changes in the 'master' branch against the latest available
-commit or for bug-fixes, against an earlier commit or release in which the
-bug occurred.
-
-If you find yourself working on more than one issue at a time, Setuptools
-generally prefers Git-style branches, so use Mercurial bookmarks or Git
-branches or multiple forks to maintain separate efforts.
-
-The Continuous Integration tests that validate every release are run
-from this repository.
-
--------
-Testing
--------
-
-The primary tests are run using tox. To run the tests, first make
-sure you have tox installed, then invoke it::
-
- $ tox
-
-Under continuous integration, additional tests may be run. See the
-``.travis.yml`` file for full details on the tests run under Travis-CI.
-
--------------------
-Semantic Versioning
--------------------
-
-Setuptools follows ``semver``.
-
-.. explain value of reflecting meaning in versions.
-
-----------------------
-Building Documentation
-----------------------
-
-Setuptools relies on the Sphinx system for building documentation.
-To accommodate RTD, docs must be built from the docs/ directory.
-
-To build them, you need to have installed the requirements specified
-in docs/requirements.txt. One way to do this is to use rwt:
-
- setuptools/docs$ python -m rwt -r requirements.txt -- -m sphinx . html
diff --git a/docs/development/developer-guide.rst b/docs/development/developer-guide.rst
new file mode 100644
index 0000000..d2cf159
--- /dev/null
+++ b/docs/development/developer-guide.rst
@@ -0,0 +1,133 @@
+================================
+Developer's Guide for Setuptools
+================================
+
+If you want to know more about contributing on Setuptools, this is the place.
+
+
+-------------------
+Recommended Reading
+-------------------
+
+Please read `How to write the perfect pull request
+<https://blog.jaraco.com/how-to-write-perfect-pull-request/>`_ for some tips
+on contributing to open source projects. Although the article is not
+authoritative, it was authored by the maintainer of Setuptools, so reflects
+his opinions and will improve the likelihood of acceptance and quality of
+contribution.
+
+------------------
+Project Management
+------------------
+
+Setuptools is maintained primarily in GitHub at `this home
+<https://github.com/pypa/setuptools>`_. Setuptools is maintained under the
+Python Packaging Authority (PyPA) with several core contributors. All bugs
+for Setuptools are filed and the canonical source is maintained in GitHub.
+
+User support and discussions are done through
+`GitHub Discussions <https://github.com/pypa/setuptools/discussions>`_,
+or the issue tracker (for specific issues).
+
+Discussions about development happen on GitHub Discussions or
+the ``setuptools`` channel on `PyPA Discord <https://discord.com/invite/pypa>`_.
+
+-----------------
+Authoring Tickets
+-----------------
+
+Before authoring any source code, it's often prudent to file a ticket
+describing the motivation behind making changes. First search to see if a
+ticket already exists for your issue. If not, create one. Try to think from
+the perspective of the reader. Explain what behavior you expected, what you
+got instead, and what factors might have contributed to the unexpected
+behavior. In GitHub, surround a block of code or traceback with the triple
+backtick "\`\`\`" so that it is formatted nicely.
+
+Filing a ticket provides a forum for justification, discussion, and
+clarification. The ticket provides a record of the purpose for the change and
+any hard decisions that were made. It provides a single place for others to
+reference when trying to understand why the software operates the way it does
+or why certain changes were made.
+
+Setuptools makes extensive use of hyperlinks to tickets in the changelog so
+that system integrators and other users can get a quick summary, but then
+jump to the in-depth discussion about any subject referenced.
+
+---------------------
+Making a pull request
+---------------------
+
+When making a pull request, please
+:ref:`include a short summary of the changes <Adding change notes
+with your PRs>` and a reference to any issue tickets that the PR is
+intended to solve.
+All PRs with code changes should include tests. All changes should
+include a changelog entry.
+
+.. include:: ../../changelog.d/README.rst
+
+-------------------
+Auto-Merge Requests
+-------------------
+
+To support running all code through CI, even lightweight contributions,
+the project employs Mergify to auto-merge pull requests tagged as
+auto-merge.
+
+Use ``hub pull-request -l auto-merge`` to create such a pull request
+from the command line after pushing a new branch.
+
+-------
+Testing
+-------
+
+The primary tests are run using tox. Make sure you have tox installed,
+and invoke it::
+
+ $ tox
+
+Under continuous integration, additional tests may be run. See the
+``.travis.yml`` file for full details on the tests run under Travis-CI.
+
+-------------------
+Semantic Versioning
+-------------------
+
+Setuptools follows ``semver``.
+
+.. explain value of reflecting meaning in versions.
+
+----------------------
+Building Documentation
+----------------------
+
+Setuptools relies on the `Sphinx`_ system for building documentation.
+The `published documentation`_ is hosted on Read the Docs.
+
+To build the docs locally, use tox::
+
+ $ tox -e docs
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _published documentation: https://setuptools.pypa.io/en/latest/
+
+---------------------
+Vendored Dependencies
+---------------------
+
+Setuptools has some dependencies, but due to `bootstrapping issues
+<https://github.com/pypa/setuptools/issues/980>`_, those dependencies
+cannot be declared as they won't be resolved soon enough to build
+setuptools from source. Eventually, this limitation may be lifted as
+PEP 517/518 reach ubiquitous adoption, but for now, Setuptools
+cannot declare dependencies other than through
+``setuptools/_vendor/vendored.txt`` and
+``pkg_resources/_vendor/vendored.txt``.
+
+All the dependencies specified in these files are "vendorized" using a
+simple Python script ``tools/vendor.py``.
+
+To refresh the dependencies, run the following command::
+
+ $ tox -e vendor
diff --git a/docs/development.txt b/docs/development/index.rst
similarity index 93%
rename from docs/development.txt
rename to docs/development/index.rst
index 455f038..7ee5236 100644
--- a/docs/development.txt
+++ b/docs/development/index.rst
@@ -7,7 +7,7 @@
This document describes the process by which Setuptools is developed.
This document assumes the reader has some passing familiarity with
-*using* setuptools, the ``pkg_resources`` module, and EasyInstall. It
+*using* setuptools, the ``pkg_resources`` module, and pip. It
does not attempt to explain basic concepts like inter-project
dependencies, nor does it contain detailed lexical syntax for most
file formats. Neither does it explain concepts like "namespace
@@ -31,5 +31,4 @@
:maxdepth: 1
developer-guide
- formats
releases
diff --git a/docs/development/releases.rst b/docs/development/releases.rst
new file mode 100644
index 0000000..35b415c
--- /dev/null
+++ b/docs/development/releases.rst
@@ -0,0 +1,37 @@
+===============
+Release Process
+===============
+
+In order to allow for rapid, predictable releases, Setuptools uses a
+mechanical technique for releases, enacted on tagged commits by
+continuous integration.
+
+To finalize a release, run ``tox -e finalize``, review, then push
+the changes.
+
+If tests pass, the release will be uploaded to PyPI.
+
+Release Frequency
+-----------------
+
+Some have asked why Setuptools is released so frequently. Because Setuptools
+uses a mechanical release process, it's very easy to make releases whenever the
+code is stable (tests are passing). As a result, the philosophy is to release
+early and often.
+
+While some find the frequent releases somewhat surprising, they only empower
+the user. Although releases are made frequently, users can choose the frequency
+at which they use those releases. If instead Setuptools contributions were only
+released in batches, the user would be constrained to only use Setuptools when
+those official releases were made. With frequent releases, the user can govern
+exactly how often he wishes to update.
+
+Frequent releases also then obviate the need for dev or beta releases in most
+cases. Because releases are made early and often, bugs are discovered and
+corrected quickly, in many cases before other users have yet to encounter them.
+
+Release Managers
+----------------
+
+Additionally, anyone with push access to the master branch has access to cut
+releases.
diff --git a/docs/history.txt b/docs/history.rst
similarity index 83%
rename from docs/history.txt
rename to docs/history.rst
index 8fd1dc6..ce7e77a 100644
--- a/docs/history.txt
+++ b/docs/history.rst
@@ -5,6 +5,8 @@
History
*******
+.. towncrier-draft-entries:: DRAFT, unreleased as on |today|
+
.. include:: ../CHANGES (links).rst
Credits
@@ -12,7 +14,7 @@
* The original design for the ``.egg`` format and the ``pkg_resources`` API was
co-created by Phillip Eby and Bob Ippolito. Bob also implemented the first
- version of ``pkg_resources``, and supplied the OS X operating system version
+ version of ``pkg_resources``, and supplied the macOS operating system version
compatibility algorithm.
* Ian Bicking implemented many early "creature comfort" features of
@@ -40,7 +42,6 @@
re-invigorated the community on the project, encouraged renewed innovation,
and addressed many defects.
-* Since the merge with Distribute, Jason R. Coombs is the
- maintainer of setuptools. The project is maintained in coordination with
- the Python Packaging Authority (PyPA) and the larger Python community.
-
+* Jason R. Coombs performed the merge with Distribute, maintaining the
+ project for several years in coordination with the Python Packaging
+ Authority (PyPA).
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..0f52c36
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,31 @@
+.. image:: images/banner-640x320.svg
+ :align: center
+
+Documentation
+=============
+
+Setuptools is a fully-featured, actively-maintained, and stable library
+designed to facilitate packaging Python projects.
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+
+ User guide <userguide/index>
+ build_meta
+ pkg_resources
+ references/keywords
+ setuptools
+
+.. toctree::
+ :caption: Project
+ :maxdepth: 1
+ :hidden:
+
+ roadmap
+ Development guide <development/index>
+ Backward compatibility & deprecated practice <deprecated/index>
+ Changelog <history>
+ artwork
+
+.. tidelift-referral-banner::
diff --git a/docs/index.txt b/docs/index.txt
deleted file mode 100644
index 74aabb5..0000000
--- a/docs/index.txt
+++ /dev/null
@@ -1,25 +0,0 @@
-Welcome to Setuptools' documentation!
-=====================================
-
-Setuptools is a fully-featured, actively-maintained, and stable library
-designed to facilitate packaging Python projects, where packaging includes:
-
- - Python package and module definitions
- - Distribution package metadata
- - Test hooks
- - Project installation
- - Platform-specific details
- - Python 3 support
-
-Documentation content:
-
-.. toctree::
- :maxdepth: 2
-
- setuptools
- easy_install
- pkg_resources
- python3
- development
- roadmap
- history
diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.rst
similarity index 86%
rename from docs/pkg_resources.txt
rename to docs/pkg_resources.rst
index b40a209..21ff6dc 100644
--- a/docs/pkg_resources.txt
+++ b/docs/pkg_resources.rst
@@ -10,8 +10,12 @@
subpackages, and APIs for managing Python's current "working set" of active
packages.
-
-.. contents:: **Table of Contents**
+Use of ``pkg_resources`` is discouraged in favor of
+`importlib.resources <https://docs.python.org/3/library/importlib.html#module-importlib.resources>`_,
+`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_,
+and their backports (:pypi:`importlib_resources`,
+:pypi:`importlib_metadata`).
+Please consider using those libraries instead of pkg_resources.
--------
@@ -149,7 +153,7 @@
in the package's ``__init__.py`` file(s):
``declare_namespace(name)``
- Declare that the dotted package name `name` is a "namespace package" whose
+ Declare that the dotted package name ``name`` is a "namespace package" whose
contained packages and modules may be spread across multiple distributions.
The named package's ``__path__`` will be extended to include the
corresponding package in all distributions on ``sys.path`` that contain a
@@ -163,7 +167,7 @@
at runtime may also need to use this API function:
``fixup_namespace_packages(path_item)``
- Declare that `path_item` is a newly added item on ``sys.path`` that may
+ Declare that ``path_item`` is a newly added item on ``sys.path`` that may
need to be used to update existing namespace packages. Ordinarily, this is
called for you when an egg is automatically added to ``sys.path``, but if
your application modifies ``sys.path`` to include locations that may
@@ -197,7 +201,7 @@
``working_set`` based on changes to ``sys.path``.
``WorkingSet(entries=None)``
- Create a ``WorkingSet`` from an iterable of path entries. If `entries`
+ Create a ``WorkingSet`` from an iterable of path entries. If ``entries``
is not supplied, it defaults to the value of ``sys.path`` at the time
the constructor is called.
@@ -229,9 +233,9 @@
``require(*requirements)``
- Ensure that distributions matching `requirements` are activated
+ Ensure that distributions matching ``requirements`` are activated
- `requirements` must be a string or a (possibly-nested) sequence
+ ``requirements`` must be a string or a (possibly-nested) sequence
thereof, specifying the distributions and versions required. The
return value is a sequence of the distributions that needed to be
activated to fulfill the requirements; all relevant distributions are
@@ -245,8 +249,8 @@
interactive interpreter hacking than for production use. If you're creating
an actual library or application, it's strongly recommended that you create
a "setup.py" script using ``setuptools``, and declare all your requirements
- there. That way, tools like EasyInstall can automatically detect what
- requirements your package has, and deal with them accordingly.
+ there. That way, tools like pip can automatically detect what requirements
+ your package has, and deal with them accordingly.
Note that calling ``require('SomePackage')`` will not install
``SomePackage`` if it isn't already present. If you need to do this, you
@@ -259,8 +263,8 @@
``obtain()`` method of ``Environment`` objects.
``run_script(requires, script_name)``
- Locate distribution specified by `requires` and run its `script_name`
- script. `requires` must be a string containing a requirement specifier.
+ Locate distribution specified by ``requires`` and run its ``script_name``
+ script. ``requires`` must be a string containing a requirement specifier.
(See `Requirements Parsing`_ below for the syntax.)
The script, if found, will be executed in *the caller's globals*. That's
@@ -274,11 +278,11 @@
object's `Metadata API`_ instead.
``iter_entry_points(group, name=None)``
- Yield entry point objects from `group` matching `name`
+ Yield entry point objects from ``group`` matching ``name``
- If `name` is None, yields all entry points in `group` from all
+ If ``name`` is None, yields all entry points in ``group`` from all
distributions in the working set, otherwise only ones matching both
- `group` and `name` are yielded. Entry points are yielded from the active
+ ``group`` and ``name`` are yielded. Entry points are yielded from the active
distributions in the order that the distributions appear in the working
set. (For the global ``working_set``, this should be the same as the order
that they are listed in ``sys.path``.) Note that within the entry points
@@ -301,14 +305,14 @@
called by the ``WorkingSet()`` constructor during initialization.
This method uses ``find_distributions(entry,True)`` to find distributions
- corresponding to the path entry, and then ``add()`` them. `entry` is
+ corresponding to the path entry, and then ``add()`` them. ``entry`` is
always appended to the ``entries`` attribute, even if it is already
present, however. (This is because ``sys.path`` can contain the same value
more than once, and the ``entries`` attribute should be able to reflect
this.)
``__contains__(dist)``
- True if `dist` is active in this ``WorkingSet``. Note that only one
+ True if ``dist`` is active in this ``WorkingSet``. Note that only one
distribution for a given project can be active in a given ``WorkingSet``.
``__iter__()``
@@ -317,34 +321,34 @@
added to the working set.
``find(req)``
- Find a distribution matching `req` (a ``Requirement`` instance).
+ Find a distribution matching ``req`` (a ``Requirement`` instance).
If there is an active distribution for the requested project, this
returns it, as long as it meets the version requirement specified by
- `req`. But, if there is an active distribution for the project and it
- does *not* meet the `req` requirement, ``VersionConflict`` is raised.
+ ``req``. But, if there is an active distribution for the project and it
+ does *not* meet the ``req`` requirement, ``VersionConflict`` is raised.
If there is no active distribution for the requested project, ``None``
is returned.
``resolve(requirements, env=None, installer=None)``
- List all distributions needed to (recursively) meet `requirements`
+ List all distributions needed to (recursively) meet ``requirements``
- `requirements` must be a sequence of ``Requirement`` objects. `env`,
+ ``requirements`` must be a sequence of ``Requirement`` objects. ``env``,
if supplied, should be an ``Environment`` instance. If
not supplied, an ``Environment`` is created from the working set's
- ``entries``. `installer`, if supplied, will be invoked with each
+ ``entries``. ``installer``, if supplied, will be invoked with each
requirement that cannot be met by an already-installed distribution; it
should return a ``Distribution`` or ``None``. (See the ``obtain()`` method
- of `Environment Objects`_, below, for more information on the `installer`
+ of `Environment Objects`_, below, for more information on the ``installer``
argument.)
``add(dist, entry=None)``
- Add `dist` to working set, associated with `entry`
+ Add ``dist`` to working set, associated with ``entry``
- If `entry` is unspecified, it defaults to ``dist.location``. On exit from
- this routine, `entry` is added to the end of the working set's ``.entries``
+ If ``entry`` is unspecified, it defaults to ``dist.location``. On exit from
+ this routine, ``entry`` is added to the end of the working set's ``.entries``
(if it wasn't already present).
- `dist` is only added to the working set if it's for a project that
+ ``dist`` is only added to the working set if it's for a project that
doesn't already have a distribution active in the set. If it's
successfully added, any callbacks registered with the ``subscribe()``
method will be called. (See `Receiving Change Notifications`_, below.)
@@ -401,7 +405,7 @@
without conflicts or missing requirements.
``find_plugins(plugin_env, full_env=None, fallback=True)``
- Scan `plugin_env` and identify which distributions could be added to this
+ Scan ``plugin_env`` and identify which distributions could be added to this
working set without version conflicts or missing requirements.
Example usage::
@@ -412,19 +416,19 @@
map(working_set.add, distributions) # add plugins+libs to sys.path
print "Couldn't load", errors # display errors
- The `plugin_env` should be an ``Environment`` instance that contains only
+ The ``plugin_env`` should be an ``Environment`` instance that contains only
distributions that are in the project's "plugin directory" or directories.
- The `full_env`, if supplied, should be an ``Environment`` instance that
+ The ``full_env``, if supplied, should be an ``Environment`` instance that
contains all currently-available distributions.
- If `full_env` is not supplied, one is created automatically from the
+ If ``full_env`` is not supplied, one is created automatically from the
``WorkingSet`` this method is called on, which will typically mean that
every directory on ``sys.path`` will be scanned for distributions.
- This method returns a 2-tuple: (`distributions`, `error_info`), where
- `distributions` is a list of the distributions found in `plugin_env` that
+ This method returns a 2-tuple: (``distributions``, ``error_info``), where
+ ``distributions`` is a list of the distributions found in ``plugin_env`` that
were loadable, along with any other distributions that are needed to resolve
- their dependencies. `error_info` is a dictionary mapping unloadable plugin
+ their dependencies. ``error_info`` is a dictionary mapping unloadable plugin
distributions to an exception instance describing the error that occurred.
Usually this will be a ``DistributionNotFound`` or ``VersionConflict``
instance.
@@ -436,7 +440,7 @@
metadata tracking and hooks to be activated.
The resolution algorithm used by ``find_plugins()`` is as follows. First,
- the project names of the distributions present in `plugin_env` are sorted.
+ the project names of the distributions present in ``plugin_env`` are sorted.
Then, each project's eggs are tried in descending version order (i.e.,
newest version first).
@@ -446,7 +450,7 @@
the next project name, and no older eggs for that project are tried.
If the resolution attempt fails, however, the error is added to the error
- dictionary. If the `fallback` flag is true, the next older version of the
+ dictionary. If the ``fallback`` flag is true, the next older version of the
plugin is tried, until a working version is found. If false, the resolution
process continues with the next plugin project name.
@@ -455,7 +459,7 @@
may not be able to safely downgrade a version of a package. Others may want
to ensure that a new plugin configuration is either 100% good or else
revert to a known-good configuration. (That is, they may wish to revert to
- a known configuration if the `error_info` return value is non-empty.)
+ a known configuration if the ``error_info`` return value is non-empty.)
Note that this algorithm gives precedence to satisfying the dependencies of
alphabetically prior project names in case of version conflicts. If two
@@ -473,22 +477,22 @@
distributions during dependency resolution.
``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)``
- Create an environment snapshot by scanning `search_path` for distributions
- compatible with `platform` and `python`. `search_path` should be a
+ Create an environment snapshot by scanning ``search_path`` for distributions
+ compatible with ``platform`` and ``python``. ``search_path`` should be a
sequence of strings such as might be used on ``sys.path``. If a
- `search_path` isn't supplied, ``sys.path`` is used.
+ ``search_path`` isn't supplied, ``sys.path`` is used.
- `platform` is an optional string specifying the name of the platform
+ ``platform`` is an optional string specifying the name of the platform
that platform-specific distributions must be compatible with. If
- unspecified, it defaults to the current platform. `python` is an
+ unspecified, it defaults to the current platform. ``python`` is an
optional string naming the desired version of Python (e.g. ``'2.4'``);
it defaults to the currently-running version.
- You may explicitly set `platform` (and/or `python`) to ``None`` if you
+ You may explicitly set ``platform`` (and/or ``python``) to ``None`` if you
wish to include *all* distributions, not just those compatible with the
running platform or Python version.
- Note that `search_path` is scanned immediately for distributions, and the
+ Note that ``search_path`` is scanned immediately for distributions, and the
resulting ``Environment`` is a snapshot of the found distributions. It
is not automatically updated if the system's state changes due to e.g.
installation or removal of distributions.
@@ -504,15 +508,15 @@
The yielded names are always in lower case.
``add(dist)``
- Add `dist` to the environment if it matches the platform and python version
+ Add ``dist`` to the environment if it matches the platform and python version
specified at creation time, and only if the distribution hasn't already
been added. (i.e., adding the same distribution more than once is a no-op.)
``remove(dist)``
- Remove `dist` from the environment.
+ Remove ``dist`` from the environment.
``can_add(dist)``
- Is distribution `dist` acceptable for this environment? If it's not
+ Is distribution ``dist`` acceptable for this environment? If it's not
compatible with the ``platform`` and ``python`` version values specified
when the environment was created, a false value is returned.
@@ -534,34 +538,34 @@
are silently ignored.
``best_match(req, working_set, installer=None)``
- Find distribution best matching `req` and usable on `working_set`
+ Find distribution best matching ``req`` and usable on ``working_set``
- This calls the ``find(req)`` method of the `working_set` to see if a
+ This calls the ``find(req)`` method of the ``working_set`` to see if a
suitable distribution is already active. (This may raise
``VersionConflict`` if an unsuitable version of the project is already
- active in the specified `working_set`.) If a suitable distribution isn't
+ active in the specified ``working_set``.) If a suitable distribution isn't
active, this method returns the newest distribution in the environment
- that meets the ``Requirement`` in `req`. If no suitable distribution is
- found, and `installer` is supplied, then the result of calling
+ that meets the ``Requirement`` in ``req``. If no suitable distribution is
+ found, and ``installer`` is supplied, then the result of calling
the environment's ``obtain(req, installer)`` method will be returned.
``obtain(requirement, installer=None)``
Obtain a distro that matches requirement (e.g. via download). In the
base ``Environment`` class, this routine just returns
- ``installer(requirement)``, unless `installer` is None, in which case
+ ``installer(requirement)``, unless ``installer`` is None, in which case
None is returned instead. This method is a hook that allows subclasses
to attempt other ways of obtaining a distribution before falling back
- to the `installer` argument.
+ to the ``installer`` argument.
``scan(search_path=None)``
- Scan `search_path` for distributions usable on `platform`
+ Scan ``search_path`` for distributions usable on ``platform``
- Any distributions found are added to the environment. `search_path` should
+ Any distributions found are added to the environment. ``search_path`` should
be a sequence of strings such as might be used on ``sys.path``. If not
supplied, ``sys.path`` is used. Only distributions conforming to
the platform/python version defined at initialization are added. This
method is a shortcut for using the ``find_distributions()`` function to
- find the distributions from each item in `search_path`, and then calling
+ find the distributions from each item in ``search_path``, and then calling
``add()`` to add each one to the environment.
@@ -594,7 +598,7 @@
FooProject >= 1.2
Fizzy [foo, bar]
- PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1
+ PickyThing>1.6,<=1.9,!=1.8.6
SomethingWhoseVersionIDontCareAbout
SomethingWithMarker[foo]>1.0;python_version<"2.7"
@@ -611,9 +615,9 @@
or activation of both Report-O-Rama and any libraries it needs in order to
provide PDF support. For example, you could use::
- easy_install.py Report-O-Rama[PDF]
+ pip install Report-O-Rama[PDF]
- To install the necessary packages using the EasyInstall program, or call
+ To install the necessary packages using pip, or call
``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary
distributions to sys.path at runtime.
@@ -627,10 +631,10 @@
--------------------------------------
``__contains__(dist_or_version)``
- Return true if `dist_or_version` fits the criteria for this requirement.
- If `dist_or_version` is a ``Distribution`` object, its project name must
+ Return true if ``dist_or_version`` fits the criteria for this requirement.
+ If ``dist_or_version`` is a ``Distribution`` object, its project name must
match the requirement's project name, and its version must meet the
- requirement's version criteria. If `dist_or_version` is a string, it is
+ requirement's version criteria. If ``dist_or_version`` is a string, it is
parsed using the ``parse_version()`` utility function. Otherwise, it is
assumed to be an already-parsed version.
@@ -668,8 +672,8 @@
``specs``
A list of ``(op,version)`` tuples, sorted in ascending parsed-version
- order. The `op` in each tuple is a comparison operator, represented as
- a string. The `version` is the (unparsed) version number.
+ order. The ``op`` in each tuple is a comparison operator, represented as
+ a string. The ``version`` is the (unparsed) version number.
``marker``
An instance of ``packaging.markers.Marker`` that allows evaluation
@@ -703,7 +707,7 @@
To advertise an entry point, a project needs to use ``setuptools`` and provide
an ``entry_points`` argument to ``setup()`` in its setup script, so that the
entry points will be included in the distribution's metadata. For more
-details, see the ``setuptools`` documentation. (XXX link here to setuptools)
+details, see :ref:`Advertising Behavior<dynamic discovery of services and plugins>`.
Each project distribution can advertise at most one entry point of a given
name within the same entry point group. For example, a distutils extension
@@ -721,14 +725,14 @@
Convenience API
---------------
-In the following functions, the `dist` argument can be a ``Distribution``
+In the following functions, the ``dist`` argument can be a ``Distribution``
instance, a ``Requirement`` instance, or a string specifying a requirement
(i.e. project name, version, etc.). If the argument is a string or
``Requirement``, the specified distribution is located (and added to sys.path
if not already present). An error will be raised if a matching distribution is
not available.
-The `group` argument should be a string containing a dotted identifier,
+The ``group`` argument should be a string containing a dotted identifier,
identifying an entry point group. If you are defining an entry point group,
you should include some portion of your package's name in the group name so as
to avoid collision with other packages' entry point groups.
@@ -738,25 +742,25 @@
``ImportError``.
``get_entry_info(dist, group, name)``
- Return an ``EntryPoint`` object for the given `group` and `name` from
+ Return an ``EntryPoint`` object for the given ``group`` and ``name`` from
the specified distribution. Returns ``None`` if the distribution has not
advertised a matching entry point.
``get_entry_map(dist, group=None)``
- Return the distribution's entry point map for `group`, or the full entry
+ Return the distribution's entry point map for ``group``, or the full entry
map for the distribution. This function always returns a dictionary,
- even if the distribution advertises no entry points. If `group` is given,
+ even if the distribution advertises no entry points. If ``group`` is given,
the dictionary maps entry point names to the corresponding ``EntryPoint``
- object. If `group` is None, the dictionary maps group names to
+ object. If ``group`` is None, the dictionary maps group names to
dictionaries that then map entry point names to the corresponding
``EntryPoint`` instance in that group.
``iter_entry_points(group, name=None)``
- Yield entry point objects from `group` matching `name`.
+ Yield entry point objects from ``group`` matching ``name``.
- If `name` is None, yields all entry points in `group` from all
+ If ``name`` is None, yields all entry points in ``group`` from all
distributions in the working set on sys.path, otherwise only ones matching
- both `group` and `name` are yielded. Entry points are yielded from
+ both ``group`` and ``name`` are yielded. Entry points are yielded from
the active distributions in the order that the distributions appear on
sys.path. (Within entry points for a particular distribution, however,
there is no particular ordering.)
@@ -769,26 +773,26 @@
--------------------
``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)``
- Create an ``EntryPoint`` instance. `name` is the entry point name. The
- `module_name` is the (dotted) name of the module containing the advertised
- object. `attrs` is an optional tuple of names to look up from the
- module to obtain the advertised object. For example, an `attrs` of
- ``("foo","bar")`` and a `module_name` of ``"baz"`` would mean that the
+ Create an ``EntryPoint`` instance. ``name`` is the entry point name. The
+ ``module_name`` is the (dotted) name of the module containing the advertised
+ object. ``attrs`` is an optional tuple of names to look up from the
+ module to obtain the advertised object. For example, an ``attrs`` of
+ ``("foo","bar")`` and a ``module_name`` of ``"baz"`` would mean that the
advertised object could be obtained by the following code::
import baz
advertised_object = baz.foo.bar
- The `extras` are an optional tuple of "extra feature" names that the
+ The ``extras`` are an optional tuple of "extra feature" names that the
distribution needs in order to provide this entry point. When the
- entry point is loaded, these extra features are looked up in the `dist`
+ entry point is loaded, these extra features are looked up in the ``dist``
argument to find out what other distributions may need to be activated
- on sys.path; see the ``load()`` method for more details. The `extras`
- argument is only meaningful if `dist` is specified. `dist` must be
+ on sys.path; see the ``load()`` method for more details. The ``extras``
+ argument is only meaningful if ``dist`` is specified. ``dist`` must be
a ``Distribution`` instance.
``EntryPoint.parse(src, dist=None)`` (classmethod)
- Parse a single entry point from string `src`
+ Parse a single entry point from string ``src``
Entry point syntax follows the form::
@@ -796,27 +800,27 @@
The entry name and module name are required, but the ``:attrs`` and
``[extras]`` parts are optional, as is the whitespace shown between
- some of the items. The `dist` argument is passed through to the
+ some of the items. The ``dist`` argument is passed through to the
``EntryPoint()`` constructor, along with the other values parsed from
- `src`.
+ ``src``.
``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod)
- Parse `lines` (a string or sequence of lines) to create a dictionary
+ Parse ``lines`` (a string or sequence of lines) to create a dictionary
mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is
- raised if entry point names are duplicated, if `group` is not a valid
+ raised if entry point names are duplicated, if ``group`` is not a valid
entry point group name, or if there are any syntax errors. (Note: the
- `group` parameter is used only for validation and to create more
- informative error messages.) If `dist` is provided, it will be used to
+ ``group`` parameter is used only for validation and to create more
+ informative error messages.) If ``dist`` is provided, it will be used to
set the ``dist`` attribute of the created ``EntryPoint`` objects.
``EntryPoint.parse_map(data, dist=None)`` (classmethod)
- Parse `data` into a dictionary mapping group names to dictionaries mapping
- entry point names to ``EntryPoint`` objects. If `data` is a dictionary,
+ Parse ``data`` into a dictionary mapping group names to dictionaries mapping
+ entry point names to ``EntryPoint`` objects. If ``data`` is a dictionary,
then the keys are used as group names and the values are passed to
- ``parse_group()`` as the `lines` argument. If `data` is a string or
+ ``parse_group()`` as the ``lines`` argument. If ``data`` is a string or
sequence of lines, it is first split into .ini-style sections (using
the ``split_sections()`` utility function) and the section names are used
- as group names. In either case, the `dist` argument is passed through to
+ as group names. In either case, the ``dist`` argument is passed through to
``parse_group()`` so that the entry points will be linked to the specified
distribution.
@@ -837,9 +841,9 @@
Ensure that any "extras" needed by the entry point are available on
sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``,
but no ``dist``, or if the named extras are not defined by the
- distribution. If `env` is supplied, it must be an ``Environment``, and it
+ distribution. If ``env`` is supplied, it must be an ``Environment``, and it
will be used to search for needed distributions if they are not already
- present on sys.path. If `installer` is supplied, it must be a callable
+ present on sys.path. If ``installer`` is supplied, it must be a callable
taking a ``Requirement`` instance and returning a matching importable
``Distribution`` instance or None.
@@ -872,16 +876,16 @@
objects from one of these high-level APIs:
``find_distributions(path_item, only=False)``
- Yield distributions accessible via `path_item`. If `only` is true, yield
- only distributions whose ``location`` is equal to `path_item`. In other
- words, if `only` is true, this yields any distributions that would be
- importable if `path_item` were on ``sys.path``. If `only` is false, this
- also yields distributions that are "in" or "under" `path_item`, but would
+ Yield distributions accessible via ``path_item``. If ``only`` is true, yield
+ only distributions whose ``location`` is equal to ``path_item``. In other
+ words, if ``only`` is true, this yields any distributions that would be
+ importable if ``path_item`` were on ``sys.path``. If ``only`` is false, this
+ also yields distributions that are "in" or "under" ``path_item``, but would
not be importable unless their locations were also added to ``sys.path``.
``get_distribution(dist_spec)``
Return a ``Distribution`` object for a given ``Requirement`` or string.
- If `dist_spec` is already a ``Distribution`` instance, it is returned.
+ If ``dist_spec`` is already a ``Distribution`` instance, it is returned.
If it is a ``Requirement`` object or a string that can be parsed into one,
it is used to locate and activate a matching distribution, which is then
returned.
@@ -890,18 +894,18 @@
or creating a new distribution format, you may also need to create
``Distribution`` objects directly, using one of the three constructors below.
-These constructors all take an optional `metadata` argument, which is used to
-access any resources or metadata associated with the distribution. `metadata`
+These constructors all take an optional ``metadata`` argument, which is used to
+access any resources or metadata associated with the distribution. ``metadata``
must be an object that implements the ``IResourceProvider`` interface, or None.
If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects
implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by
-delegating them to the `metadata` object.
+delegating them to the ``metadata`` object.
``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
- Create a distribution for `location`, which must be a string such as a
+ Create a distribution for ``location``, which must be a string such as a
URL, filename, or other string that might be used on ``sys.path``.
- `basename` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``.
- If `basename` ends with ``.egg``, then the project's name, version, python
+ ``basename`` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``.
+ If ``basename`` ends with ``.egg``, then the project's name, version, python
version and platform are extracted from the filename and used to set those
properties of the created distribution. Any additional keyword arguments
are forwarded to the ``Distribution()`` constructor.
@@ -917,8 +921,8 @@
``Distribution(location,metadata,project_name,version,py_version,platform,precedence)``
Create a distribution by setting its properties. All arguments are
- optional and default to None, except for `py_version` (which defaults to
- the current Python version) and `precedence` (which defaults to
+ optional and default to None, except for ``py_version`` (which defaults to
+ the current Python version) and ``precedence`` (which defaults to
``EGG_DIST``; for more details see ``precedence`` under `Distribution
Attributes`_ below). Note that it's usually easier to use the
``from_filename()`` or ``from_location()`` constructors than to specify
@@ -938,7 +942,7 @@
A string, naming the project that this distribution is for. Project names
are defined by a project's setup script, and they are used to identify
projects on PyPI. When a ``Distribution`` is constructed, the
- `project_name` argument is passed through the ``safe_name()`` utility
+ ``project_name`` argument is passed through the ``safe_name()`` utility
function to filter out any unacceptable characters.
key
@@ -952,9 +956,9 @@
version
A string denoting what release of the project this distribution contains.
- When a ``Distribution`` is constructed, the `version` argument is passed
+ When a ``Distribution`` is constructed, the ``version`` argument is passed
through the ``safe_version()`` utility function to filter out any
- unacceptable characters. If no `version` is specified at construction
+ unacceptable characters. If no ``version`` is specified at construction
time, then attempting to access this attribute later will cause the
``Distribution`` to try to discover its version by reading its ``PKG-INFO``
metadata file. If ``PKG-INFO`` is unavailable or can't be parsed,
@@ -967,7 +971,7 @@
distributions by version. (See the `Parsing Utilities`_ section below for
more information on the ``parse_version()`` function.) Note that accessing
``parsed_version`` may result in a ``ValueError`` if the ``Distribution``
- was constructed without a `version` and without `metadata` capable of
+ was constructed without a ``version`` and without ``metadata`` capable of
supplying the missing version info.
py_version
@@ -998,9 +1002,9 @@
------------------------
``activate(path=None)``
- Ensure distribution is importable on `path`. If `path` is None,
+ Ensure distribution is importable on ``path``. If ``path`` is None,
``sys.path`` is used instead. This ensures that the distribution's
- ``location`` is in the `path` list, and it also performs any necessary
+ ``location`` is in the ``path`` list, and it also performs any necessary
namespace package fixups or declarations. (That is, if the distribution
contains namespace packages, this method ensures that they are declared,
and that the distribution's contents for those namespace packages are
@@ -1020,7 +1024,7 @@
``requires(extras=())``
List the ``Requirement`` objects that specify this distribution's
- dependencies. If `extras` is specified, it should be a sequence of names
+ dependencies. If ``extras`` is specified, it should be a sequence of names
of "extras" defined by the distribution, and the list returned will then
include any dependencies needed to support the named "extras".
@@ -1047,11 +1051,11 @@
detailed information about these operations:
``get_entry_info(group, name)``
- Return the ``EntryPoint`` object for `group` and `name`, or None if no
+ Return the ``EntryPoint`` object for ``group`` and ``name``, or None if no
such point is advertised by this distribution.
``get_entry_map(group=None)``
- Return the entry point map for `group`. If `group` is None, return
+ Return the entry point map for ``group``. If ``group`` is None, return
a dictionary mapping group names to entry point maps for all groups.
(An entry point map is a dictionary of entry point names to ``EntryPoint``
objects.)
@@ -1079,14 +1083,15 @@
* ``resource_isdir(resource_name)``
* ``resource_listdir(resource_name)``
-If the distribution was created with a `metadata` argument, these resource and
-metadata access methods are all delegated to that `metadata` provider.
+If the distribution was created with a ``metadata`` argument, these resource and
+metadata access methods are all delegated to that ``metadata`` provider.
Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution
will appear to have no resources or metadata. This delegation approach is used
so that supporting custom importers or new distribution formats can be done
simply by creating an appropriate `IResourceProvider`_ implementation; see the
section below on `Supporting Custom Importers`_ for more details.
+.. _ResourceManager API:
``ResourceManager`` API
=======================
@@ -1111,11 +1116,11 @@
Basic Resource Access
---------------------
-In the following methods, the `package_or_requirement` argument may be either
+In the following methods, the ``package_or_requirement`` argument may be either
a Python package/module name (e.g. ``foo.bar``) or a ``Requirement`` instance.
If it is a package or module name, the named module or package must be
importable (i.e., be in a distribution or directory on ``sys.path``), and the
-`resource_name` argument is interpreted relative to the named package. (Note
+``resource_name`` argument is interpreted relative to the named package. (Note
that if a module name is used, then the resource name is relative to the
package immediately containing the named module. Also, you should not use use
a namespace package name, because a namespace package can be spread across
@@ -1126,13 +1131,13 @@
(searching the current ``Environment`` if necessary) and a matching
distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not
already present. (Unless the ``Requirement`` can't be satisfied, in which
-case an exception is raised.) The `resource_name` argument is then interpreted
+case an exception is raised.) The ``resource_name`` argument is then interpreted
relative to the root of the identified distribution; i.e. its first path
segment will be treated as a peer of the top-level modules or packages in the
distribution.
-Note that resource names must be ``/``-separated paths and cannot be absolute
-(i.e. no leading ``/``) or contain relative names like ``".."``. Do *not* use
+Note that resource names must be ``/``-separated paths rooted at the package,
+cannot contain relative names like ``".."``, and cannot be absolute. Do *not* use
``os.path`` routines to manipulate resource paths, as they are *not* filesystem
paths.
@@ -1146,7 +1151,7 @@
will be read as-is.
``resource_string(package_or_requirement, resource_name)``
- Return the specified resource as a string. The resource is read in
+ Return the specified resource as ``bytes``. The resource is read in
binary fashion, such that the returned string contains exactly the bytes
that are stored in the resource.
@@ -1221,19 +1226,19 @@
If you are implementing an ``IResourceProvider`` and/or ``IMetadataProvider``
for a new distribution archive format, you may need to use the following
-``IResourceManager`` methods to co-ordinate extraction of resources to the
+``IResourceManager`` methods to coordinate extraction of resources to the
filesystem. If you're not implementing an archive format, however, you have
no need to use these methods. Unlike the other methods listed above, they are
*not* available as top-level functions tied to the global ``ResourceManager``;
you must therefore have an explicit ``ResourceManager`` instance to use them.
``get_cache_path(archive_name, names=())``
- Return absolute location in cache for `archive_name` and `names`
+ Return absolute location in cache for ``archive_name`` and ``names``
The parent directory of the resulting path will be created if it does
- not already exist. `archive_name` should be the base filename of the
+ not already exist. ``archive_name`` should be the base filename of the
enclosing egg (which may not be the name of the enclosing zipfile!),
- including its ".egg" extension. `names`, if provided, should be a
+ including its ".egg" extension. ``names``, if provided, should be a
sequence of path name parts "under" the egg's extraction location.
This method should only be called by resource providers that need to
@@ -1249,12 +1254,12 @@
wrap or handle extraction errors themselves.
``postprocess(tempname, filename)``
- Perform any platform-specific postprocessing of `tempname`.
+ Perform any platform-specific postprocessing of ``tempname``.
Resource providers should call this method ONLY after successfully
extracting a compressed resource. They must NOT call it on resources
that are already in the filesystem.
- `tempname` is the current (temporary) name of the file, and `filename`
+ ``tempname`` is the current (temporary) name of the file, and ``filename``
is the name it will be renamed to by the caller after this routine
returns.
@@ -1322,7 +1327,7 @@
``run_script(script_name, namespace)``
Execute the named script in the supplied namespace dictionary. Raises
``ResolutionError`` if there is no script by that name in the ``scripts``
- metadata directory. `namespace` should be a Python dictionary, usually
+ metadata directory. ``namespace`` should be a Python dictionary, usually
a module dictionary if the script is being run as a module.
@@ -1379,11 +1384,11 @@
register various handlers and support functions using these APIs:
``register_finder(importer_type, distribution_finder)``
- Register `distribution_finder` to find distributions in ``sys.path`` items.
- `importer_type` is the type or class of a PEP 302 "Importer" (``sys.path``
- item handler), and `distribution_finder` is a callable that, when passed a
- path item, the importer instance, and an `only` flag, yields
- ``Distribution`` instances found under that path item. (The `only` flag,
+ Register ``distribution_finder`` to find distributions in ``sys.path`` items.
+ ``importer_type`` is the type or class of a PEP 302 "Importer" (``sys.path``
+ item handler), and ``distribution_finder`` is a callable that, when passed a
+ path item, the importer instance, and an ``only`` flag, yields
+ ``Distribution`` instances found under that path item. (The ``only`` flag,
if true, means the finder should yield only ``Distribution`` objects whose
``location`` is equal to the path item provided.)
@@ -1391,16 +1396,16 @@
example finder function.
``register_loader_type(loader_type, provider_factory)``
- Register `provider_factory` to make ``IResourceProvider`` objects for
- `loader_type`. `loader_type` is the type or class of a PEP 302
- ``module.__loader__``, and `provider_factory` is a function that, when
+ Register ``provider_factory`` to make ``IResourceProvider`` objects for
+ ``loader_type``. ``loader_type`` is the type or class of a PEP 302
+ ``module.__loader__``, and ``provider_factory`` is a function that, when
passed a module object, returns an `IResourceProvider`_ for that module,
allowing it to be used with the `ResourceManager API`_.
``register_namespace_handler(importer_type, namespace_handler)``
- Register `namespace_handler` to declare namespace packages for the given
- `importer_type`. `importer_type` is the type or class of a PEP 302
- "importer" (sys.path item handler), and `namespace_handler` is a callable
+ Register ``namespace_handler`` to declare namespace packages for the given
+ ``importer_type``. ``importer_type`` is the type or class of a PEP 302
+ "importer" (sys.path item handler), and ``namespace_handler`` is a callable
with a signature like this::
def namespace_handler(importer, path_entry, moduleName, module):
@@ -1420,23 +1425,23 @@
-----------------
``IResourceProvider`` is an abstract class that documents what methods are
-required of objects returned by a `provider_factory` registered with
+required of objects returned by a ``provider_factory`` registered with
``register_loader_type()``. ``IResourceProvider`` is a subclass of
``IMetadataProvider``, so objects that implement this interface must also
implement all of the `IMetadataProvider Methods`_ as well as the methods
-shown here. The `manager` argument to the methods below must be an object
+shown here. The ``manager`` argument to the methods below must be an object
that supports the full `ResourceManager API`_ documented above.
``get_resource_filename(manager, resource_name)``
- Return a true filesystem path for `resource_name`, coordinating the
- extraction with `manager`, if the resource must be unpacked to the
+ Return a true filesystem path for ``resource_name``, coordinating the
+ extraction with ``manager``, if the resource must be unpacked to the
filesystem.
``get_resource_stream(manager, resource_name)``
- Return a readable file-like object for `resource_name`.
+ Return a readable file-like object for ``resource_name``.
``get_resource_string(manager, resource_name)``
- Return a string containing the contents of `resource_name`.
+ Return a string containing the contents of ``resource_name``.
``has_resource(resource_name)``
Does the package contain the named resource?
@@ -1500,15 +1505,15 @@
``PathMetadata(path, egg_info)``
Create an ``IResourceProvider`` for a filesystem-based distribution, where
- `path` is the filesystem location of the importable modules, and `egg_info`
+ ``path`` is the filesystem location of the importable modules, and ``egg_info``
is the filesystem location of the distribution's metadata directory.
- `egg_info` should usually be the ``EGG-INFO`` subdirectory of `path` for an
- "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of `path` for
+ ``egg_info`` should usually be the ``EGG-INFO`` subdirectory of ``path`` for an
+ "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of ``path`` for
a "development egg". However, other uses are possible for custom purposes.
``EggMetadata(zipimporter)``
Create an ``IResourceProvider`` for a zipfile-based distribution. The
- `zipimporter` should be a ``zipimport.zipimporter`` instance, and may
+ ``zipimporter`` should be a ``zipimport.zipimporter`` instance, and may
represent a "basket" (a zipfile containing multiple ".egg" subdirectories)
a specific egg *within* a basket, or a zipfile egg (where the zipfile
itself is a ".egg"). It can also be a combination, such as a zipfile egg
@@ -1546,12 +1551,12 @@
``yield_lines(strs)``
Yield non-empty/non-comment lines from a string/unicode or a possibly-
- nested sequence thereof. If `strs` is an instance of ``basestring``, it
+ nested sequence thereof. If ``strs`` is an instance of ``basestring``, it
is split into lines, and each non-blank, non-comment line is yielded after
stripping leading and trailing whitespace. (Lines whose first non-blank
character is ``#`` are considered comment lines.)
- If `strs` is not an instance of ``basestring``, it is iterated over, and
+ If ``strs`` is not an instance of ``basestring``, it is iterated over, and
each item is passed recursively to ``yield_lines()``, so that an arbitrarily
nested sequence of strings, or sequences of sequences of strings can be
flattened out to the lines contained therein. So for example, passing
@@ -1595,12 +1600,12 @@
See ``to_filename()``.
``safe_version(version)``
- This will return the normalized form of any PEP 440 version, if the version
- string is not PEP 440 compatible than it is similar to ``safe_name()``
- except that spaces in the input become dots, and dots are allowed to exist
- in the output. As with ``safe_name()``, if you are generating a filename
- from this you should replace any "-" characters in the output with
- underscores.
+ This will return the normalized form of any PEP 440 version. If the version
+ string is not PEP 440 compatible, this function behaves similar to
+ ``safe_name()`` except that spaces in the input become dots, and dots are
+ allowed to exist in the output. As with ``safe_name()``, if you are
+ generating a filename from this you should replace any "-" characters in
+ the output with underscores.
``safe_extra(extra)``
Return a "safe" form of an extra's name, suitable for use in a requirement
@@ -1620,7 +1625,7 @@
``get_build_platform()``
Return this platform's identifier string. For Windows, the return value
- is ``"win32"``, and for Mac OS X it is a string of the form
+ is ``"win32"``, and for macOS it is a string of the form
``"macosx-10.4-ppc"``. All other platforms return the same uname-based
string that the ``distutils.util.get_platform()`` function returns.
This string is the minimum platform version required by distributions built
@@ -1635,15 +1640,15 @@
``compatible_platforms()`` function.
``compatible_platforms(provided, required)``
- Return true if a distribution built on the `provided` platform may be used
- on the `required` platform. If either platform value is ``None``, it is
+ Return true if a distribution built on the ``provided`` platform may be used
+ on the ``required`` platform. If either platform value is ``None``, it is
considered a wildcard, and the platforms are therefore compatible.
Likewise, if the platform strings are equal, they're also considered
compatible, and ``True`` is returned. Currently, the only non-equal
- platform strings that are considered compatible are Mac OS X platform
+ platform strings that are considered compatible are macOS platform
strings with the same hardware type (e.g. ``ppc``) and major version
- (e.g. ``10``) with the `provided` platform's minor version being less than
- or equal to the `required` platform's minor version.
+ (e.g. ``10``) with the ``provided`` platform's minor version being less than
+ or equal to the ``required`` platform's minor version.
``get_default_cache()``
Determine the default cache location for extracting resources from zipped
@@ -1665,15 +1670,15 @@
-------------------
``ensure_directory(path)``
- Ensure that the parent directory (``os.path.dirname``) of `path` actually
+ Ensure that the parent directory (``os.path.dirname``) of ``path`` actually
exists, using ``os.makedirs()`` if necessary.
``normalize_path(path)``
- Return a "normalized" version of `path`, such that two paths represent
+ Return a "normalized" version of ``path``, such that two paths represent
the same filesystem location if they have equal ``normalized_path()``
values. Specifically, this is a shortcut for calling ``os.path.realpath``
- and ``os.path.normcase`` on `path`. Unfortunately, on certain platforms
- (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately
+ and ``os.path.normcase`` on ``path``. Unfortunately, on certain platforms
+ (notably Cygwin and macOS) the ``normcase`` function does not accurately
reflect the platform's case-sensitivity, so there is always the possibility
of two apparently-different paths being equal on such platforms.
@@ -1842,9 +1847,9 @@
because it isn't necessarily a filesystem path (and hasn't been for some
time now). The ``location`` of ``Distribution`` objects in the filesystem
should always be normalized using ``pkg_resources.normalize_path()``; all
- of the setuptools and EasyInstall code that generates distributions from
- the filesystem (including ``Distribution.from_filename()``) ensure this
- invariant, but if you use a more generic API like ``Distribution()`` or
+ of the setuptools' code that generates distributions from the filesystem
+ (including ``Distribution.from_filename()``) ensure this invariant, but if
+ you use a more generic API like ``Distribution()`` or
``Distribution.from_location()`` you should take care that you don't
create a distribution with an un-normalized filesystem path.
@@ -1938,4 +1943,3 @@
0.3a1
* Initial release.
-
diff --git a/docs/python 2 sunset.rst b/docs/python 2 sunset.rst
new file mode 100644
index 0000000..225d655
--- /dev/null
+++ b/docs/python 2 sunset.rst
@@ -0,0 +1,69 @@
+:orphan:
+
+Python 2 Sunset
+===============
+
+Since January 2020 and the release of Setuptools 45, Python 2 is no longer
+supported by the most current release (`discussion
+<https://github.com/pypa/setuptools/issues/1458>`_). Setuptools as a project
+continues to support Python 2 with bugfixes and important features on
+Setuptools 44.x.
+
+By design, most users will be unaffected by this change. That's because
+Setuptools 45 declares its supported Python versions to exclude Python 2.7,
+and installers such as pip 9 or later will honor this declaration and prevent
+installation of Setuptools 45 or later in Python 2 environments.
+
+Users that do import any portion of Setuptools 45 or later on Python 2 are
+directed to this documentation to provide guidance on how to work around the
+issues.
+
+Workarounds
+-----------
+
+The best recommendation is to avoid Python 2 and move to Python 3 where
+possible. This project acknowledges that not all environments can drop Python
+2 support, so provides other options.
+
+In less common scenarios, later versions of Setuptools can be installed on
+unsupported Python versions. In these environments, the installer is advised
+to first install ``setuptools<45`` to "pin Setuptools" to a compatible
+version.
+
+- When using older versions of pip (before 9.0), the ``Requires-Python``
+ directive is not honored and invalid versions can be installed. Users are
+ advised first to upgrade pip and retry or to pin Setuptools. Use ``pip
+ --version`` to determine the version of pip.
+- When using ``easy_install``, ``Requires-Python`` is not honored and later
+ versions can be installed. In this case, users are advised to pin
+ Setuptools. This applies to ``setup.py install`` invocations as well, as
+ they use Setuptools under the hood.
+
+It's still not working
+----------------------
+
+If after trying the above steps, the Python environment still has incompatible
+versions of Setuptools installed, here are some things to try.
+
+1. Uninstall and reinstall Setuptools. Run ``pip uninstall -y setuptools`` for
+ the relevant environment. Repeat until there is no Setuptools installed.
+ Then ``pip install setuptools``.
+2. If possible, attempt to replicate the problem in a second environment
+ (virtual machine, friend's computer, etc). If the issue is isolated to just
+ one unique environment, first determine what is different about those
+ environments (or reinstall/reset the failing one to defaults).
+3. End users who are not themselves the maintainers for the package they are
+ trying to install should contact the support channels for the relevant
+ application. Please be considerate of those projects by searching for
+ existing issues and following the latest guidance before reaching out for
+ support. When filing an issue, be sure to give as much detail as possible
+ to help the maintainers understand what factors led to the issue after
+ following their recommended guidance.
+4. Reach out to your local support groups. There's a good chance someone
+ nearby has the expertise and willingness to help.
+5. If all else fails, `file this template
+ <https://github.com/pypa/setuptools/issues/new?assignees=&labels=Python+2&template=setuptools-warns-about-python-2-incompatibility.md&title=Incompatible+install+in+(summarize+your+environment)>`_
+ with Setuptools. Please complete the whole template, providing as much
+ detail about what factors led to the issue. Setuptools maintainers will
+ summarily close tickets filed without any meaningful detail or engagement
+ with the issue.
diff --git a/docs/python3.txt b/docs/python3.txt
deleted file mode 100644
index c528fc3..0000000
--- a/docs/python3.txt
+++ /dev/null
@@ -1,94 +0,0 @@
-=====================================================
-Supporting both Python 2 and Python 3 with Setuptools
-=====================================================
-
-Starting with Distribute version 0.6.2 and Setuptools 0.7, the Setuptools
-project supported Python 3. Installing and
-using setuptools for Python 3 code works exactly the same as for Python 2
-code.
-
-Setuptools provides a facility to invoke 2to3 on the code as a part of the
-build process, by setting the keyword parameter ``use_2to3`` to True, but
-the Setuptools strongly recommends instead developing a unified codebase
-using `six <https://pypi.org/project/six/>`_,
-`future <https://pypi.org/project/future/>`_, or another compatibility
-library.
-
-
-Using 2to3
-==========
-
-Setuptools attempts to make the porting process easier by automatically
-running
-2to3 as a part of running tests. To do so, you need to configure the
-setup.py so that you can run the unit tests with ``python setup.py test``.
-
-See :ref:`test` for more information on this.
-
-Once you have the tests running under Python 2, you can add the use_2to3
-keyword parameters to setup(), and start running the tests under Python 3.
-The test command will now first run the build command during which the code
-will be converted with 2to3, and the tests will then be run from the build
-directory, as opposed from the source directory as is normally done.
-
-Setuptools will convert all Python files, and also all doctests in Python
-files. However, if you have doctests located in separate text files, these
-will not automatically be converted. By adding them to the
-``convert_2to3_doctests`` keyword parameter Setuptools will convert them as
-well.
-
-By default, the conversion uses all fixers in the ``lib2to3.fixers`` package.
-To use additional fixers, the parameter ``use_2to3_fixers`` can be set
-to a list of names of packages containing fixers. To exclude fixers, the
-parameter ``use_2to3_exclude_fixers`` can be set to fixer names to be
-skipped.
-
-An example setup.py might look something like this::
-
- from setuptools import setup
-
- setup(
- name='your.module',
- version='1.0',
- description='This is your awesome module',
- author='You',
- author_email='your@email',
- package_dir={'': 'src'},
- packages=['your', 'you.module'],
- test_suite='your.module.tests',
- use_2to3=True,
- convert_2to3_doctests=['src/your/module/README.txt'],
- use_2to3_fixers=['your.fixers'],
- use_2to3_exclude_fixers=['lib2to3.fixes.fix_import'],
- )
-
-Differential conversion
------------------------
-
-Note that a file will only be copied and converted during the build process
-if the source file has been changed. If you add a file to the doctests
-that should be converted, it will not be converted the next time you run
-the tests, since it hasn't been modified. You need to remove it from the
-build directory. Also if you run the build, install or test commands before
-adding the use_2to3 parameter, you will have to remove the build directory
-before you run the test command, as the files otherwise will seem updated,
-and no conversion will happen.
-
-In general, if code doesn't seem to be converted, deleting the build directory
-and trying again is a good safeguard against the build directory getting
-"out of sync" with the source directory.
-
-Distributing Python 3 modules
-=============================
-
-You can distribute your modules with Python 3 support in different ways. A
-normal source distribution will work, but can be slow in installing, as the
-2to3 process will be run during the install. But you can also distribute
-the module in binary format, such as a binary egg. That egg will contain the
-already converted code, and hence no 2to3 conversion is needed during install.
-
-Advanced features
-=================
-
-If you don't want to run the 2to3 conversion on the doctests in Python files,
-you can turn that off by setting ``setuptools.use_2to3_on_doctests = False``.
diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst
new file mode 100644
index 0000000..c26b9d4
--- /dev/null
+++ b/docs/references/keywords.rst
@@ -0,0 +1,336 @@
+========
+Keywords
+========
+
+``name``
+ A string specifying the name of the package.
+
+``version``
+ A string specifying the version number of the package.
+
+``description``
+ A string describing the package in a single line.
+
+``long_description``
+ A string providing a longer description of the package.
+
+``long_description_content_type``
+ A string specifying the content type is used for the ``long_description``
+ (e.g. ``text/markdown``)
+
+``author``
+ A string specifying the author of the package.
+
+``author_email``
+ A string specifying the email address of the package author.
+
+``maintainer``
+ A string specifying the name of the current maintainer, if different from
+ the author. Note that if the maintainer is provided, setuptools will use it
+ as the author in ``PKG-INFO``.
+
+``maintainer_email``
+ A string specifying the email address of the current maintainer, if
+ different from the author.
+
+``url``
+ A string specifying the URL for the package homepage.
+
+``download_url``
+ A string specifying the URL to download the package.
+
+``packages``
+ A list of strings specifying the packages that setuptools will manipulate.
+
+``py_modules``
+ A list of strings specifying the modules that setuptools will manipulate.
+
+``scripts``
+ A list of strings specifying the standalone script files to be built and
+ installed.
+
+``ext_package``
+ A string specifying the base package name for the extensions provided by
+ this package.
+
+``ext_modules``
+ A list of instances of ``setuptools.Extension`` providing the list of
+ Python extensions to be built.
+
+``classifiers``
+ A list of strings describing the categories for the package.
+
+``distclass``
+ A subclass of ``Distribution`` to use.
+
+``script_name``
+ A string specifying the name of the setup.py script -- defaults to
+ ``sys.argv[0]``
+
+``script_args``
+ A list of strings defining the arguments to supply to the setup script.
+
+``options``
+ A dictionary providing the default options for the setup script.
+
+``license``
+ A string specifying the license of the package.
+
+``license_file``
+
+ .. warning::
+ ``license_file`` is deprecated. Use ``license_files`` instead.
+
+``license_files``
+
+ A list of glob patterns for license related files that should be included.
+ If neither ``license_file`` nor ``license_files`` is specified, this option
+ defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``.
+
+``keywords``
+ A list of strings or a comma-separated string providing descriptive
+ meta-data. See: `PEP 0314`_.
+
+.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/
+
+``platforms``
+ A list of strings or comma-separated string.
+
+``cmdclass``
+ A dictionary providing a mapping of command names to ``Command``
+ subclasses.
+
+``data_files``
+
+ .. warning::
+ ``data_files`` is deprecated. It does not work with wheels, so it
+ should be avoided.
+
+ A list of strings specifying the data files to install.
+
+``package_dir``
+ A dictionary providing a mapping of package to directory names.
+
+``requires``
+
+ .. warning::
+ ``requires`` is superseded by ``install_requires`` and should not be used
+ anymore.
+
+``obsoletes``
+
+ .. warning::
+ ``obsoletes`` is currently ignored by ``pip``.
+
+ List of strings describing packages which this package renders obsolete,
+ meaning that the two projects should not be installed at the same time.
+
+ Version declarations can be supplied. Version numbers must be in the format
+ specified in Version specifiers (e.g. ``foo (<3.0)``).
+
+ This field may be followed by an environment marker after a semicolon (e.g.
+ ``foo; os_name == "posix"``)
+
+ The most common use of this field will be in case a project name changes,
+ e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install
+ Torqued Python, the Gorgon distribution should be removed.
+
+``provides``
+
+ .. warning::
+ ``provides`` is currently ignored by ``pip``.
+
+ List of strings describing package- and virtual package names contained
+ within this package.
+
+ A package may provide additional names, e.g. to indicate that multiple
+ projects have been bundled together. For instance, source distributions of
+ the ZODB project have historically included the transaction project, which
+ is now available as a separate distribution. Installing such a source
+ distribution satisfies requirements for both ZODB and transaction.
+
+ A package may also provide a “virtual” project name, which does not
+ correspond to any separately-distributed project: such a name might be used
+ to indicate an abstract capability which could be supplied by one of
+ multiple projects. E.g., multiple projects might supply RDBMS bindings for
+ use by a given ORM: each project might declare that it provides
+ ORM-bindings, allowing other projects to depend only on having at most one
+ of them installed.
+
+ A version declaration may be supplied and must follow the rules described in
+ Version specifiers. The distribution’s version number will be implied if
+ none is specified (e.g. ``foo (<3.0)``).
+
+ Each package may be followed by an environment marker after a semicolon
+ (e.g. ``foo; os_name == "posix"``).
+
+.. Below are setuptools keywords, above are distutils
+
+``include_package_data``
+ If set to ``True``, this tells ``setuptools`` to automatically include any
+ data files it finds inside your package directories that are specified by
+ your ``MANIFEST.in`` file. For more information, see the section on
+ :ref:`Including Data Files`.
+
+``exclude_package_data``
+ A dictionary mapping package names to lists of glob patterns that should
+ be *excluded* from your package directories. You can use this to trim back
+ any excess files included by ``include_package_data``. For a complete
+ description and examples, see the section on :ref:`Including Data Files`.
+
+``package_data``
+ A dictionary mapping package names to lists of glob patterns. For a
+ complete description and examples, see the section on :ref:`Including Data
+ Files`. You do not need to use this option if you are using
+ ``include_package_data``, unless you need to add e.g. files that are
+ generated by your setup script and build process. (And are therefore not
+ in source control or are files that you don't want to include in your
+ source distribution.)
+
+``zip_safe``
+ A boolean (True or False) flag specifying whether the project can be
+ safely installed and run from a zip file. If this argument is not
+ supplied, the ``bdist_egg`` command will have to analyze all of your
+ project's contents for possible problems each time it builds an egg.
+
+``install_requires``
+ A string or list of strings specifying what other distributions need to
+ be installed when this one is. See the section on :ref:`Declaring
+ Dependencies` for details and examples of the format of this argument.
+
+``entry_points``
+ A dictionary mapping entry point group names to strings or lists of strings
+ defining the entry points. Entry points are used to support dynamic
+ discovery of services or plugins provided by a project. See :ref:`Dynamic
+ Discovery of Services and Plugins` for details and examples of the format
+ of this argument. In addition, this keyword is used to support
+ :ref:`Automatic Script Creation <entry_points>`.
+
+``extras_require``
+ A dictionary mapping names of "extras" (optional features of your project)
+ to strings or lists of strings specifying what other distributions must be
+ installed to support those features. See the section on :ref:`Declaring
+ Dependencies` for details and examples of the format of this argument.
+
+``python_requires``
+ A string corresponding to a version specifier (as defined in PEP 440) for
+ the Python version, used to specify the Requires-Python defined in PEP 345.
+
+``setup_requires``
+
+ .. warning::
+ Using ``setup_requires`` is discouraged in favor of `PEP-518`_
+
+ A string or list of strings specifying what other distributions need to
+ be present in order for the *setup script* to run. ``setuptools`` will
+ attempt to obtain these (even going so far as to download them using
+ ``EasyInstall``) before processing the rest of the setup script or commands.
+ This argument is needed if you are using distutils extensions as part of
+ your build process; for example, extensions that process setup() arguments
+ and turn them into EGG-INFO metadata files.
+
+ (Note: projects listed in ``setup_requires`` will NOT be automatically
+ installed on the system where the setup script is being run. They are
+ simply downloaded to the ./.eggs directory if they're not locally available
+ already. If you want them to be installed, as well as being available
+ when the setup script is run, you should add them to ``install_requires``
+ **and** ``setup_requires``.)
+
+.. _PEP-518: http://www.python.org/dev/peps/pep-0518/
+
+``dependency_links``
+
+ .. warning::
+ ``dependency_links`` is deprecated. It is not supported anymore by pip.
+
+ A list of strings naming URLs to be searched when satisfying dependencies.
+ These links will be used if needed to install packages specified by
+ ``setup_requires`` or ``tests_require``. They will also be written into
+ the egg's metadata for use by tools like EasyInstall to use when installing
+ an ``.egg`` file.
+
+``namespace_packages``
+ A list of strings naming the project's "namespace packages". A namespace
+ package is a package that may be split across multiple project
+ distributions. For example, Zope 3's ``zope`` package is a namespace
+ package, because subpackages like ``zope.interface`` and ``zope.publisher``
+ may be distributed separately. The egg runtime system can automatically
+ merge such subpackages into a single parent package at runtime, as long
+ as you declare them in each project that contains any subpackages of the
+ namespace package, and as long as the namespace package's ``__init__.py``
+ does not contain any code other than a namespace declaration. See the
+ section on :ref:`Namespace Packages` for more information.
+
+``test_suite``
+ A string naming a ``unittest.TestCase`` subclass (or a package or module
+ containing one or more of them, or a method of such a subclass), or naming
+ a function that can be called with no arguments and returns a
+ ``unittest.TestSuite``. If the named suite is a module, and the module
+ has an ``additional_tests()`` function, it is called and the results are
+ added to the tests to be run. If the named suite is a package, any
+ submodules and subpackages are recursively added to the overall test suite.
+
+ Specifying this argument enables use of the :ref:`test` command to run the
+ specified test suite, e.g. via ``setup.py test``. See the section on the
+ :ref:`test` command below for more details.
+
+ New in 41.5.0: Deprecated the test command.
+
+``tests_require``
+ If your project's tests need one or more additional packages besides those
+ needed to install it, you can use this option to specify them. It should
+ be a string or list of strings specifying what other distributions need to
+ be present for the package's tests to run. When you run the ``test``
+ command, ``setuptools`` will attempt to obtain these (even going
+ so far as to download them using ``EasyInstall``). Note that these
+ required projects will *not* be installed on the system where the tests
+ are run, but only downloaded to the project's setup directory if they're
+ not already installed locally.
+
+ New in 41.5.0: Deprecated the test command.
+
+.. _test_loader:
+
+``test_loader``
+ If you would like to use a different way of finding tests to run than what
+ setuptools normally uses, you can specify a module name and class name in
+ this argument. The named class must be instantiable with no arguments, and
+ its instances must support the ``loadTestsFromNames()`` method as defined
+ in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
+ pass only one test "name" in the ``names`` argument: the value supplied for
+ the ``test_suite`` argument. The loader you specify may interpret this
+ string in any way it likes, as there are no restrictions on what may be
+ contained in a ``test_suite`` string.
+
+ The module name and class name must be separated by a ``:``. The default
+ value of this argument is ``"setuptools.command.test:ScanningLoader"``. If
+ you want to use the default ``unittest`` behavior, you can specify
+ ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This
+ will prevent automatic scanning of submodules and subpackages.
+
+ The module and class you specify here may be contained in another package,
+ as long as you use the ``tests_require`` option to ensure that the package
+ containing the loader class is available when the ``test`` command is run.
+
+ New in 41.5.0: Deprecated the test command.
+
+``eager_resources``
+ A list of strings naming resources that should be extracted together, if
+ any of them is needed, or if any C extensions included in the project are
+ imported. This argument is only useful if the project will be installed as
+ a zipfile, and there is a need to have all of the listed resources be
+ extracted to the filesystem *as a unit*. Resources listed here
+ should be '/'-separated paths, relative to the source root, so to list a
+ resource ``foo.png`` in package ``bar.baz``, you would include the string
+ ``bar/baz/foo.png`` in this argument.
+
+ If you only need to obtain resources one at a time, or you don't have any C
+ extensions that access other files in the project (such as data files or
+ shared libraries), you probably do NOT need this argument and shouldn't
+ mess with it. For more details on how this argument works, see the section
+ below on :ref:`Automatic Resource Extraction`.
+
+``project_urls``
+ An arbitrary map of URL names to hyperlinks, allowing more extensible
+ documentation of where various resources can be found than the simple
+ ``url`` and ``download_url`` options provide.
diff --git a/docs/releases.txt b/docs/releases.txt
deleted file mode 100644
index 30ea084..0000000
--- a/docs/releases.txt
+++ /dev/null
@@ -1,48 +0,0 @@
-===============
-Release Process
-===============
-
-In order to allow for rapid, predictable releases, Setuptools uses a
-mechanical technique for releases, enacted by Travis following a
-successful build of a tagged release per
-`PyPI deployment <https://docs.travis-ci.com/user/deployment/pypi>`_.
-
-Prior to cutting a release, please check that the CHANGES.rst reflects
-the summary of changes since the last release.
-Ideally, these changelog entries would have been added
-along with the changes, but it's always good to check.
-Think about it from the
-perspective of a user not involved with the development--what would
-that person want to know about what has changed--or from the
-perspective of your future self wanting to know when a particular
-change landed.
-
-To cut a release, install and run ``bump2version {part}`` where ``part``
-is major, minor, or patch based on the scope of the changes in the
-release. Then, push the commits to the master branch. If tests pass,
-the release will be uploaded to PyPI (from the Python 3.6 tests).
-
-Release Frequency
------------------
-
-Some have asked why Setuptools is released so frequently. Because Setuptools
-uses a mechanical release process, it's very easy to make releases whenever the
-code is stable (tests are passing). As a result, the philosophy is to release
-early and often.
-
-While some find the frequent releases somewhat surprising, they only empower
-the user. Although releases are made frequently, users can choose the frequency
-at which they use those releases. If instead Setuptools contributions were only
-released in batches, the user would be constrained to only use Setuptools when
-those official releases were made. With frequent releases, the user can govern
-exactly how often he wishes to update.
-
-Frequent releases also then obviate the need for dev or beta releases in most
-cases. Because releases are made early and often, bugs are discovered and
-corrected quickly, in many cases before other users have yet to encounter them.
-
-Release Managers
-----------------
-
-Additionally, anyone with push access to the master branch has access to cut
-releases.
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index 2138c88..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-sphinx
-rst.linker>=1.9
-jaraco.packaging>=3.2
-
-setuptools>=34
diff --git a/docs/roadmap.rst b/docs/roadmap.rst
new file mode 100644
index 0000000..147288f
--- /dev/null
+++ b/docs/roadmap.rst
@@ -0,0 +1,7 @@
+=======
+Roadmap
+=======
+
+Setuptools maintains a series of `milestones
+<https://github.com/pypa/setuptools/milestones>`_ to track
+a roadmap of large-scale goals.
diff --git a/docs/roadmap.txt b/docs/roadmap.txt
deleted file mode 100644
index 8f175b9..0000000
--- a/docs/roadmap.txt
+++ /dev/null
@@ -1,6 +0,0 @@
-=======
-Roadmap
-=======
-
-Setuptools is primarily in maintenance mode. The project attempts to address
-user issues, concerns, and feature requests in a timely fashion.
diff --git a/docs/setuptools.rst b/docs/setuptools.rst
new file mode 100644
index 0000000..aa63830
--- /dev/null
+++ b/docs/setuptools.rst
@@ -0,0 +1,228 @@
+==================================================
+Building and Distributing Packages with Setuptools
+==================================================
+
+``Setuptools`` is a collection of enhancements to the Python ``distutils``
+that allow developers to more easily build and
+distribute Python packages, especially ones that have dependencies on other
+packages.
+
+Packages built and distributed using ``setuptools`` look to the user like
+ordinary Python packages based on the ``distutils``.
+
+Feature Highlights:
+
+* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
+ a single-file importable distribution format
+
+* Enhanced support for accessing data files hosted in zipped packages.
+
+* Automatically include all packages in your source tree, without listing them
+ individually in setup.py
+
+* Automatically include all relevant files in your source distributions,
+ without needing to create a |MANIFEST.in|_ file, and without having to force
+ regeneration of the ``MANIFEST`` file when your source tree changes
+ [#manifest]_.
+
+* Automatically generate wrapper scripts or Windows (console and GUI) .exe
+ files for any number of "main" functions in your project. (Note: this is not
+ a py2exe replacement; the .exe files rely on the local Python installation.)
+
+* Transparent Cython support, so that your setup.py can list ``.pyx`` files and
+ still work even when the end-user doesn't have Cython installed (as long as
+ you include the Cython-generated C in your source distribution)
+
+* Command aliases - create project-specific, per-user, or site-wide shortcut
+ names for commonly used commands and options
+
+* Deploy your project in "development mode", such that it's available on
+ ``sys.path``, yet can still be edited directly from its source checkout.
+
+* Easily extend the distutils with new commands or ``setup()`` arguments, and
+ distribute/reuse your extensions for multiple projects, without copying code.
+
+* Create extensible applications and frameworks that automatically discover
+ extensions, using simple "entry points" declared in a project's setup script.
+
+* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards
+ compatible to the existing ``find_packages()`` for Python >= 3.3.
+
+-----------------
+Developer's Guide
+-----------------
+
+The developer's guide has been updated. See the :doc:`most recent version <userguide/index>`.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+TRANSITIONAL NOTE
+~~~~~~~~~~~~~~~~~
+
+Setuptools automatically calls ``declare_namespace()`` for you at runtime,
+but future versions may *not*. This is because the automatic declaration
+feature has some negative side effects, such as needing to import all namespace
+packages during the initialization of the ``pkg_resources`` runtime, and also
+the need for ``pkg_resources`` to be explicitly imported before any namespace
+packages work at all. In some future releases, you'll be responsible
+for including your own declaration lines, and the automatic declaration feature
+will be dropped to get rid of the negative side effects.
+
+During the remainder of the current development cycle, therefore, setuptools
+will warn you about missing ``declare_namespace()`` calls in your
+``__init__.py`` files, and you should correct these as soon as possible
+before the compatibility support is removed.
+Namespace packages without declaration lines will not work
+correctly once a user has upgraded to a later version, so it's important that
+you make this change now in order to avoid having your code break in the field.
+Our apologies for the inconvenience, and thank you for your patience.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+setup.cfg-only projects
+=======================
+
+.. versionadded:: 40.9.0
+
+If ``setup.py`` is missing from the project directory when a :pep:`517`
+build is invoked, ``setuptools`` emulates a dummy ``setup.py`` file containing
+only a ``setuptools.setup()`` call.
+
+.. note::
+
+ :pep:`517` doesn't support editable installs so this is currently
+ incompatible with ``pip install -e .``.
+
+This means that you can have a Python project with all build configuration
+specified in ``setup.cfg``, without a ``setup.py`` file, if you **can rely
+on** your project always being built by a :pep:`517`/:pep:`518` compatible
+frontend.
+
+To use this feature:
+
+* Specify build requirements and :pep:`517` build backend in
+ ``pyproject.toml``.
+ For example:
+
+ .. code-block:: toml
+
+ [build-system]
+ requires = [
+ "setuptools >= 40.9.0",
+ "wheel",
+ ]
+ build-backend = "setuptools.build_meta"
+
+* Use a :pep:`517` compatible build frontend, such as ``pip >= 19`` or ``build``.
+
+ .. warning::
+
+ As :pep:`517` is new, support is not universal, and frontends that
+ do support it may still have bugs. For compatibility, you may want to
+ put a ``setup.py`` file containing only a ``setuptools.setup()``
+ invocation.
+
+
+Configuration API
+=================
+
+Some automation tools may wish to access data from a configuration file.
+
+``Setuptools`` exposes a ``read_configuration()`` function for
+parsing ``metadata`` and ``options`` sections into a dictionary.
+
+
+.. code-block:: python
+
+ from setuptools.config import read_configuration
+
+ conf_dict = read_configuration("/home/user/dev/package/setup.cfg")
+
+
+By default, ``read_configuration()`` will read only the file provided
+in the first argument. To include values from other configuration files
+which could be in various places, set the ``find_others`` keyword argument
+to ``True``.
+
+If you have only a configuration file but not the whole package, you can still
+try to get data out of it with the help of the ``ignore_option_errors`` keyword
+argument. When it is set to ``True``, all options with errors possibly produced
+by directives, such as ``attr:`` and others, will be silently ignored.
+As a consequence, the resulting dictionary will include no such options.
+
+
+
+
+
+
+
+
+
+
+
+Forum and Bug Tracker
+=====================
+
+Please use `GitHub Discussions`_ for questions and discussion about
+setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
+confirmed via the forum are actual bugs, and which you have reduced to a minimal
+set of steps to reproduce.
+
+.. _GitHub Discussions: https://github.com/pypa/setuptools/discussions
+.. _setuptools bug tracker: https://github.com/pypa/setuptools/
+
+
+----
+
+
+.. [#manifest] The default behaviour for ``setuptools`` will work well for pure
+ Python packages, or packages with simple C extensions (that don't require
+ any special C header). See :ref:`Controlling files in the distribution` and
+ :doc:`userguide/datafiles` for more information about complex scenarios, if
+ you want to include other types of files.
+
+
+.. |MANIFEST.in| replace:: ``MANIFEST.in``
+.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
diff --git a/docs/setuptools.txt b/docs/setuptools.txt
deleted file mode 100644
index e14d208..0000000
--- a/docs/setuptools.txt
+++ /dev/null
@@ -1,2775 +0,0 @@
-==================================================
-Building and Distributing Packages with Setuptools
-==================================================
-
-``Setuptools`` is a collection of enhancements to the Python ``distutils``
-that allow developers to more easily build and
-distribute Python packages, especially ones that have dependencies on other
-packages.
-
-Packages built and distributed using ``setuptools`` look to the user like
-ordinary Python packages based on the ``distutils``. Your users don't need to
-install or even know about setuptools in order to use them, and you don't
-have to include the entire setuptools package in your distributions. By
-including just a single `bootstrap module`_ (a 12K .py file), your package will
-automatically download and install ``setuptools`` if the user is building your
-package from source and doesn't have a suitable version already installed.
-
-.. _bootstrap module: https://bootstrap.pypa.io/ez_setup.py
-
-Feature Highlights:
-
-* Automatically find/download/install/upgrade dependencies at build time using
- the `EasyInstall tool <easy_install.html>`_,
- which supports downloading via HTTP, FTP, Subversion, and SourceForge, and
- automatically scans web pages linked from PyPI to find download links. (It's
- the closest thing to CPAN currently available for Python.)
-
-* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
- a single-file importable distribution format
-
-* Enhanced support for accessing data files hosted in zipped packages.
-
-* Automatically include all packages in your source tree, without listing them
- individually in setup.py
-
-* Automatically include all relevant files in your source distributions,
- without needing to create a ``MANIFEST.in`` file, and without having to force
- regeneration of the ``MANIFEST`` file when your source tree changes.
-
-* Automatically generate wrapper scripts or Windows (console and GUI) .exe
- files for any number of "main" functions in your project. (Note: this is not
- a py2exe replacement; the .exe files rely on the local Python installation.)
-
-* Transparent Pyrex support, so that your setup.py can list ``.pyx`` files and
- still work even when the end-user doesn't have Pyrex installed (as long as
- you include the Pyrex-generated C in your source distribution)
-
-* Command aliases - create project-specific, per-user, or site-wide shortcut
- names for commonly used commands and options
-
-* PyPI upload support - upload your source distributions and eggs to PyPI
-
-* Deploy your project in "development mode", such that it's available on
- ``sys.path``, yet can still be edited directly from its source checkout.
-
-* Easily extend the distutils with new commands or ``setup()`` arguments, and
- distribute/reuse your extensions for multiple projects, without copying code.
-
-* Create extensible applications and frameworks that automatically discover
- extensions, using simple "entry points" declared in a project's setup script.
-
-.. contents:: **Table of Contents**
-
-.. _ez_setup.py: `bootstrap module`_
-
-
------------------
-Developer's Guide
------------------
-
-
-Installing ``setuptools``
-=========================
-
-Please follow the `EasyInstall Installation Instructions`_ to install the
-current stable version of setuptools. In particular, be sure to read the
-section on `Custom Installation Locations`_ if you are installing anywhere
-other than Python's ``site-packages`` directory.
-
-.. _EasyInstall Installation Instructions: easy_install.html#installation-instructions
-
-.. _Custom Installation Locations: easy_install.html#custom-installation-locations
-
-If you want the current in-development version of setuptools, you should first
-install a stable version, and then run::
-
- ez_setup.py setuptools==dev
-
-This will download and install the latest development (i.e. unstable) version
-of setuptools from the Python Subversion sandbox.
-
-
-Basic Use
-=========
-
-For basic use of setuptools, just import things from setuptools instead of
-the distutils. Here's a minimal setup script using setuptools::
-
- from setuptools import setup, find_packages
- setup(
- name="HelloWorld",
- version="0.1",
- packages=find_packages(),
- )
-
-As you can see, it doesn't take much to use setuptools in a project.
-Run that script in your project folder, alongside the Python packages
-you have developed.
-
-Invoke that script to produce eggs, upload to
-PyPI, and automatically include all packages in the directory where the
-setup.py lives. See the `Command Reference`_ section below to see what
-commands you can give to this setup script. For example,
-to produce a source distribution, simply invoke::
-
- python setup.py sdist
-
-Of course, before you release your project to PyPI, you'll want to add a bit
-more information to your setup script to help people find or learn about your
-project. And maybe your project will have grown by then to include a few
-dependencies, and perhaps some data files and scripts::
-
- from setuptools import setup, find_packages
- setup(
- name="HelloWorld",
- version="0.1",
- packages=find_packages(),
- scripts=['say_hello.py'],
-
- # Project uses reStructuredText, so ensure that the docutils get
- # installed or upgraded on the target machine
- install_requires=['docutils>=0.3'],
-
- package_data={
- # If any package contains *.txt or *.rst files, include them:
- '': ['*.txt', '*.rst'],
- # And include any *.msg files found in the 'hello' package, too:
- 'hello': ['*.msg'],
- },
-
- # metadata for upload to PyPI
- author="Me",
- author_email="me@example.com",
- description="This is an Example Package",
- license="PSF",
- keywords="hello world example examples",
- url="http://example.com/HelloWorld/", # project home page, if any
- project_urls={
- "Bug Tracker": "https://bugs.example.com/HelloWorld/",
- "Documentation": "https://docs.example.com/HelloWorld/",
- "Source Code": "https://code.example.com/HelloWorld/",
- }
-
- # could also include long_description, download_url, classifiers, etc.
- )
-
-In the sections that follow, we'll explain what most of these ``setup()``
-arguments do (except for the metadata ones), and the various ways you might use
-them in your own project(s).
-
-
-Specifying Your Project's Version
----------------------------------
-
-Setuptools can work well with most versioning schemes; there are, however, a
-few special things to watch out for, in order to ensure that setuptools and
-EasyInstall can always tell what version of your package is newer than another
-version. Knowing these things will also help you correctly specify what
-versions of other projects your project depends on.
-
-A version consists of an alternating series of release numbers and pre-release
-or post-release tags. A release number is a series of digits punctuated by
-dots, such as ``2.4`` or ``0.5``. Each series of digits is treated
-numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
-same release number, denoting the first subrelease of release 2. But ``2.10``
-is the *tenth* subrelease of release 2, and so is a different and newer release
-from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
-ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
-
-Following a release number, you can have either a pre-release or post-release
-tag. Pre-release tags make a version be considered *older* than the version
-they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``,
-which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make
-a version be considered *newer* than the version they are appended to. So,
-revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older*
-than ``2.4.1`` (which has a higher release number).
-
-A pre-release tag is a series of letters that are alphabetically before
-"final". Some examples of prerelease tags would include ``alpha``, ``beta``,
-``a``, ``c``, ``dev``, and so on. You do not have to place a dot or dash
-before the prerelease tag if it's immediately after a number, but it's okay to
-do so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` and ``2.4-c1`` all
-represent release candidate 1 of version ``2.4``, and are treated as identical
-by setuptools.
-
-In addition, there are three special prerelease tags that are treated as if
-they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version
-``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as
-``2.4c1``, and are treated as identical by setuptools.
-
-A post-release tag is either a series of letters that are alphabetically
-greater than or equal to "final", or a dash (``-``). Post-release tags are
-generally used to separate patch numbers, port numbers, build numbers, revision
-numbers, or date stamps from the release number. For example, the version
-``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of
-version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped
-post-release.
-
-Notice that after each pre or post-release tag, you are free to place another
-release number, followed again by more pre- or post-release tags. For example,
-``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in-
-development version of the ninth alpha of release 0.6. Notice that ``dev`` is
-a pre-release tag, so this version is a *lower* version number than ``0.6a9``,
-which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is
-a post-release tag, so this version is *newer* than ``0.6a9.dev``.
-
-For the most part, setuptools' interpretation of version numbers is intuitive,
-but here are a few tips that will keep you out of trouble in the corner cases:
-
-* Don't stick adjoining pre-release tags together without a dot or number
- between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``,
- *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in
- ``1.9a.dev``, or separate the prerelease tags with a number, as in
- ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are
- identical versions from setuptools' point of view, so you can use whatever
- scheme you prefer.
-
-* If you want to be certain that your chosen numbering scheme works the way
- you think it will, you can use the ``pkg_resources.parse_version()`` function
- to compare different version numbers::
-
- >>> from pkg_resources import parse_version
- >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
- True
- >>> parse_version('2.1-rc2') < parse_version('2.1')
- True
- >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
- True
-
-Once you've decided on a version numbering scheme for your project, you can
-have setuptools automatically tag your in-development releases with various
-pre- or post-release tags. See the following sections for more details:
-
-* `Tagging and "Daily Build" or "Snapshot" Releases`_
-* `Managing "Continuous Releases" Using Subversion`_
-* The `egg_info`_ command
-
-
-New and Changed ``setup()`` Keywords
-====================================
-
-The following keyword arguments to ``setup()`` are added or changed by
-``setuptools``. All of them are optional; you do not have to supply them
-unless you need the associated ``setuptools`` feature.
-
-``include_package_data``
- If set to ``True``, this tells ``setuptools`` to automatically include any
- data files it finds inside your package directories that are specified by
- your ``MANIFEST.in`` file. For more information, see the section below on
- `Including Data Files`_.
-
-``exclude_package_data``
- A dictionary mapping package names to lists of glob patterns that should
- be *excluded* from your package directories. You can use this to trim back
- any excess files included by ``include_package_data``. For a complete
- description and examples, see the section below on `Including Data Files`_.
-
-``package_data``
- A dictionary mapping package names to lists of glob patterns. For a
- complete description and examples, see the section below on `Including
- Data Files`_. You do not need to use this option if you are using
- ``include_package_data``, unless you need to add e.g. files that are
- generated by your setup script and build process. (And are therefore not
- in source control or are files that you don't want to include in your
- source distribution.)
-
-``zip_safe``
- A boolean (True or False) flag specifying whether the project can be
- safely installed and run from a zip file. If this argument is not
- supplied, the ``bdist_egg`` command will have to analyze all of your
- project's contents for possible problems each time it builds an egg.
-
-``install_requires``
- A string or list of strings specifying what other distributions need to
- be installed when this one is. See the section below on `Declaring
- Dependencies`_ for details and examples of the format of this argument.
-
-``entry_points``
- A dictionary mapping entry point group names to strings or lists of strings
- defining the entry points. Entry points are used to support dynamic
- discovery of services or plugins provided by a project. See `Dynamic
- Discovery of Services and Plugins`_ for details and examples of the format
- of this argument. In addition, this keyword is used to support `Automatic
- Script Creation`_.
-
-``extras_require``
- A dictionary mapping names of "extras" (optional features of your project)
- to strings or lists of strings specifying what other distributions must be
- installed to support those features. See the section below on `Declaring
- Dependencies`_ for details and examples of the format of this argument.
-
-``python_requires``
- A string corresponding to a version specifier (as defined in PEP 440) for
- the Python version, used to specify the Requires-Python defined in PEP 345.
-
-``setup_requires``
- A string or list of strings specifying what other distributions need to
- be present in order for the *setup script* to run. ``setuptools`` will
- attempt to obtain these (even going so far as to download them using
- ``EasyInstall``) before processing the rest of the setup script or commands.
- This argument is needed if you are using distutils extensions as part of
- your build process; for example, extensions that process setup() arguments
- and turn them into EGG-INFO metadata files.
-
- (Note: projects listed in ``setup_requires`` will NOT be automatically
- installed on the system where the setup script is being run. They are
- simply downloaded to the ./.eggs directory if they're not locally available
- already. If you want them to be installed, as well as being available
- when the setup script is run, you should add them to ``install_requires``
- **and** ``setup_requires``.)
-
-``dependency_links``
- A list of strings naming URLs to be searched when satisfying dependencies.
- These links will be used if needed to install packages specified by
- ``setup_requires`` or ``tests_require``. They will also be written into
- the egg's metadata for use by tools like EasyInstall to use when installing
- an ``.egg`` file.
-
-``namespace_packages``
- A list of strings naming the project's "namespace packages". A namespace
- package is a package that may be split across multiple project
- distributions. For example, Zope 3's ``zope`` package is a namespace
- package, because subpackages like ``zope.interface`` and ``zope.publisher``
- may be distributed separately. The egg runtime system can automatically
- merge such subpackages into a single parent package at runtime, as long
- as you declare them in each project that contains any subpackages of the
- namespace package, and as long as the namespace package's ``__init__.py``
- does not contain any code other than a namespace declaration. See the
- section below on `Namespace Packages`_ for more information.
-
-``test_suite``
- A string naming a ``unittest.TestCase`` subclass (or a package or module
- containing one or more of them, or a method of such a subclass), or naming
- a function that can be called with no arguments and returns a
- ``unittest.TestSuite``. If the named suite is a module, and the module
- has an ``additional_tests()`` function, it is called and the results are
- added to the tests to be run. If the named suite is a package, any
- submodules and subpackages are recursively added to the overall test suite.
-
- Specifying this argument enables use of the `test`_ command to run the
- specified test suite, e.g. via ``setup.py test``. See the section on the
- `test`_ command below for more details.
-
-``tests_require``
- If your project's tests need one or more additional packages besides those
- needed to install it, you can use this option to specify them. It should
- be a string or list of strings specifying what other distributions need to
- be present for the package's tests to run. When you run the ``test``
- command, ``setuptools`` will attempt to obtain these (even going
- so far as to download them using ``EasyInstall``). Note that these
- required projects will *not* be installed on the system where the tests
- are run, but only downloaded to the project's setup directory if they're
- not already installed locally.
-
-.. _test_loader:
-
-``test_loader``
- If you would like to use a different way of finding tests to run than what
- setuptools normally uses, you can specify a module name and class name in
- this argument. The named class must be instantiable with no arguments, and
- its instances must support the ``loadTestsFromNames()`` method as defined
- in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
- pass only one test "name" in the `names` argument: the value supplied for
- the ``test_suite`` argument. The loader you specify may interpret this
- string in any way it likes, as there are no restrictions on what may be
- contained in a ``test_suite`` string.
-
- The module name and class name must be separated by a ``:``. The default
- value of this argument is ``"setuptools.command.test:ScanningLoader"``. If
- you want to use the default ``unittest`` behavior, you can specify
- ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This
- will prevent automatic scanning of submodules and subpackages.
-
- The module and class you specify here may be contained in another package,
- as long as you use the ``tests_require`` option to ensure that the package
- containing the loader class is available when the ``test`` command is run.
-
-``eager_resources``
- A list of strings naming resources that should be extracted together, if
- any of them is needed, or if any C extensions included in the project are
- imported. This argument is only useful if the project will be installed as
- a zipfile, and there is a need to have all of the listed resources be
- extracted to the filesystem *as a unit*. Resources listed here
- should be '/'-separated paths, relative to the source root, so to list a
- resource ``foo.png`` in package ``bar.baz``, you would include the string
- ``bar/baz/foo.png`` in this argument.
-
- If you only need to obtain resources one at a time, or you don't have any C
- extensions that access other files in the project (such as data files or
- shared libraries), you probably do NOT need this argument and shouldn't
- mess with it. For more details on how this argument works, see the section
- below on `Automatic Resource Extraction`_.
-
-``use_2to3``
- Convert the source code from Python 2 to Python 3 with 2to3 during the
- build process. See :doc:`python3` for more details.
-
-``convert_2to3_doctests``
- List of doctest source files that need to be converted with 2to3.
- See :doc:`python3` for more details.
-
-``use_2to3_fixers``
- A list of modules to search for additional fixers to be used during
- the 2to3 conversion. See :doc:`python3` for more details.
-
-``project_urls``
- An arbitrary map of URL names to hyperlinks, allowing more extensible
- documentation of where various resources can be found than the simple
- ``url`` and ``download_url`` options provide.
-
-
-Using ``find_packages()``
--------------------------
-
-For simple projects, it's usually easy enough to manually add packages to
-the ``packages`` argument of ``setup()``. However, for very large projects
-(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
-package list updated. That's what ``setuptools.find_packages()`` is for.
-
-``find_packages()`` takes a source directory and two lists of package name
-patterns to exclude and include. If omitted, the source directory defaults to
-the same
-directory as the setup script. Some projects use a ``src`` or ``lib``
-directory as the root of their source tree, and those projects would of course
-use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And
-such projects also need something like ``package_dir={'':'src'}`` in their
-``setup()`` arguments, but that's just a normal distutils thing.)
-
-Anyway, ``find_packages()`` walks the target directory, filtering by inclusion
-patterns, and finds Python packages (any directory). Packages are only
-recognized if they include an ``__init__.py`` file. Finally, exclusion
-patterns are applied to remove matching packages.
-
-Inclusion and exclusion patterns are package names, optionally including
-wildcards. For
-example, ``find_packages(exclude=["*.tests"])`` will exclude all packages whose
-last name part is ``tests``. Or, ``find_packages(exclude=["*.tests",
-"*.tests.*"])`` will also exclude any subpackages of packages named ``tests``,
-but it still won't exclude a top-level ``tests`` package or the children
-thereof. In fact, if you really want no ``tests`` packages at all, you'll need
-something like this::
-
- find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])
-
-in order to cover all the bases. Really, the exclusion patterns are intended
-to cover simpler use cases than this, like excluding a single, specified
-package and its subpackages.
-
-Regardless of the parameters, the ``find_packages()``
-function returns a list of package names suitable for use as the ``packages``
-argument to ``setup()``, and so is usually the easiest way to set that
-argument in your setup script. Especially since it frees you from having to
-remember to modify your setup script whenever your project grows additional
-top-level packages or subpackages.
-
-
-Automatic Script Creation
-=========================
-
-Packaging and installing scripts can be a bit awkward with the distutils. For
-one thing, there's no easy way to have a script's filename match local
-conventions on both Windows and POSIX platforms. For another, you often have
-to create a separate file just for the "main" script, when your actual "main"
-is a function in a module somewhere. And even in Python 2.4, using the ``-m``
-option only works for actual ``.py`` files that aren't installed in a package.
-
-``setuptools`` fixes all of these problems by automatically generating scripts
-for you with the correct extension, and on Windows it will even create an
-``.exe`` file so that users don't have to change their ``PATHEXT`` settings.
-The way to use this feature is to define "entry points" in your setup script
-that indicate what function the generated script should import and run. For
-example, to create two console scripts called ``foo`` and ``bar``, and a GUI
-script called ``baz``, you might do something like this::
-
- setup(
- # other arguments here...
- entry_points={
- 'console_scripts': [
- 'foo = my_package.some_module:main_func',
- 'bar = other_module:some_func',
- ],
- 'gui_scripts': [
- 'baz = my_package_gui:start_func',
- ]
- }
- )
-
-When this project is installed on non-Windows platforms (using "setup.py
-install", "setup.py develop", or by using EasyInstall), a set of ``foo``,
-``bar``, and ``baz`` scripts will be installed that import ``main_func`` and
-``some_func`` from the specified modules. The functions you specify are called
-with no arguments, and their return value is passed to ``sys.exit()``, so you
-can return an errorlevel or message to print to stderr.
-
-On Windows, a set of ``foo.exe``, ``bar.exe``, and ``baz.exe`` launchers are
-created, alongside a set of ``foo.py``, ``bar.py``, and ``baz.pyw`` files. The
-``.exe`` wrappers find and execute the right version of Python to run the
-``.py`` or ``.pyw`` file.
-
-You may define as many "console script" and "gui script" entry points as you
-like, and each one can optionally specify "extras" that it depends on, that
-will be added to ``sys.path`` when the script is run. For more information on
-"extras", see the section below on `Declaring Extras`_. For more information
-on "entry points" in general, see the section below on `Dynamic Discovery of
-Services and Plugins`_.
-
-
-"Eggsecutable" Scripts
-----------------------
-
-Occasionally, there are situations where it's desirable to make an ``.egg``
-file directly executable. You can do this by including an entry point such
-as the following::
-
- setup(
- # other arguments here...
- entry_points={
- 'setuptools.installation': [
- 'eggsecutable = my_package.some_module:main_func',
- ]
- }
- )
-
-Any eggs built from the above setup script will include a short executable
-prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
-The prelude can be run on Unix-like platforms (including Mac and Linux) by
-invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
-``.egg`` file. For the executable prelude to run, the appropriate version of
-Python must be available via the ``PATH`` environment variable, under its
-"long" name. That is, if the egg is built for Python 2.3, there must be a
-``python2.3`` executable present in a directory on ``PATH``.
-
-This feature is primarily intended to support ez_setup the installation of
-setuptools itself on non-Windows platforms, but may also be useful for other
-projects as well.
-
-IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
-invoked via symlinks. They *must* be invoked using their original filename, in
-order to ensure that, once running, ``pkg_resources`` will know what project
-and version is in use. The header script will check this and exit with an
-error if the ``.egg`` file has been renamed or is invoked via a symlink that
-changes its base name.
-
-
-Declaring Dependencies
-======================
-
-``setuptools`` supports automatically installing dependencies when a package is
-installed, and including information about dependencies in Python Eggs (so that
-package management tools like EasyInstall can use the information).
-
-``setuptools`` and ``pkg_resources`` use a common syntax for specifying a
-project's required dependencies. This syntax consists of a project's PyPI
-name, optionally followed by a comma-separated list of "extras" in square
-brackets, optionally followed by a comma-separated list of version
-specifiers. A version specifier is one of the operators ``<``, ``>``, ``<=``,
-``>=``, ``==`` or ``!=``, followed by a version identifier. Tokens may be
-separated by whitespace, but any whitespace or nonstandard characters within a
-project name or version identifier must be replaced with ``-``.
-
-Version specifiers for a given project are internally sorted into ascending
-version order, and used to establish what ranges of versions are acceptable.
-Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
-``">2"``, and ``"<2,<3"`` becomes ``"<2"``). ``"!="`` versions are excised from
-the ranges they fall within. A project's version is then checked for
-membership in the resulting ranges. (Note that providing conflicting conditions
-for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
-therefore produce bizarre results.)
-
-Here are some example requirement specifiers::
-
- docutils >= 0.3
-
- # comment lines and \ continuations are allowed in requirement strings
- BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
- ==1.6, ==1.7 # and so are line-end comments
-
- PEAK[FastCGI, reST]>=0.5a4
-
- setuptools==0.5a7
-
-The simplest way to include requirement specifiers is to use the
-``install_requires`` argument to ``setup()``. It takes a string or list of
-strings containing requirement specifiers. If you include more than one
-requirement in a string, each requirement must begin on a new line.
-
-This has three effects:
-
-1. When your project is installed, either by using EasyInstall, ``setup.py
- install``, or ``setup.py develop``, all of the dependencies not already
- installed will be located (via PyPI), downloaded, built (if necessary),
- and installed.
-
-2. Any scripts in your project will be installed with wrappers that verify
- the availability of the specified dependencies at runtime, and ensure that
- the correct versions are added to ``sys.path`` (e.g. if multiple versions
- have been installed).
-
-3. Python Egg distributions will include a metadata file listing the
- dependencies.
-
-Note, by the way, that if you declare your dependencies in ``setup.py``, you do
-*not* need to use the ``require()`` function in your scripts or modules, as
-long as you either install the project or use ``setup.py develop`` to do
-development work on it. (See `"Development Mode"`_ below for more details on
-using ``setup.py develop``.)
-
-
-Dependencies that aren't in PyPI
---------------------------------
-
-If your project depends on packages that aren't registered in PyPI, you may
-still be able to depend on them, as long as they are available for download
-as:
-
-- an egg, in the standard distutils ``sdist`` format,
-- a single ``.py`` file, or
-- a VCS repository (Subversion, Mercurial, or Git).
-
-You just need to add some URLs to the ``dependency_links`` argument to
-``setup()``.
-
-The URLs must be either:
-
-1. direct download URLs,
-2. the URLs of web pages that contain direct download links, or
-3. the repository's URL
-
-In general, it's better to link to web pages, because it is usually less
-complex to update a web page than to release a new version of your project.
-You can also use a SourceForge ``showfiles.php`` link in the case where a
-package you depend on is distributed via SourceForge.
-
-If you depend on a package that's distributed as a single ``.py`` file, you
-must include an ``"#egg=project-version"`` suffix to the URL, to give a project
-name and version number. (Be sure to escape any dashes in the name or version
-by replacing them with underscores.) EasyInstall will recognize this suffix
-and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
-as an egg.
-
-In the case of a VCS checkout, you should also append ``#egg=project-version``
-in order to identify for what package that checkout should be used. You can
-append ``@REV`` to the URL's path (before the fragment) to specify a revision.
-Additionally, you can also force the VCS being used by prepending the URL with
-a certain prefix. Currently available are:
-
-- ``svn+URL`` for Subversion,
-- ``git+URL`` for Git, and
-- ``hg+URL`` for Mercurial
-
-A more complete example would be:
-
- ``vcs+proto://host/path@revision#egg=project-version``
-
-Be careful with the version. It should match the one inside the project files.
-If you want to disregard the version, you have to omit it both in the
-``requires`` and in the URL's fragment.
-
-This will do a checkout (or a clone, in Git and Mercurial parlance) to a
-temporary folder and run ``setup.py bdist_egg``.
-
-The ``dependency_links`` option takes the form of a list of URL strings. For
-example, the below will cause EasyInstall to search the specified page for
-eggs or source distributions, if the package's dependencies aren't already
-installed::
-
- setup(
- ...
- dependency_links=[
- "http://peak.telecommunity.com/snapshots/"
- ],
- )
-
-
-.. _Declaring Extras:
-
-
-Declaring "Extras" (optional features with their own dependencies)
-------------------------------------------------------------------
-
-Sometimes a project has "recommended" dependencies, that are not required for
-all uses of the project. For example, a project might offer optional PDF
-output if ReportLab is installed, and reStructuredText support if docutils is
-installed. These optional features are called "extras", and setuptools allows
-you to define their requirements as well. In this way, other projects that
-require these optional features can force the additional requirements to be
-installed, by naming the desired extras in their ``install_requires``.
-
-For example, let's say that Project A offers optional PDF and reST support::
-
- setup(
- name="Project-A",
- ...
- extras_require={
- 'PDF': ["ReportLab>=1.2", "RXP"],
- 'reST': ["docutils>=0.3"],
- }
- )
-
-As you can see, the ``extras_require`` argument takes a dictionary mapping
-names of "extra" features, to strings or lists of strings describing those
-features' requirements. These requirements will *not* be automatically
-installed unless another package depends on them (directly or indirectly) by
-including the desired "extras" in square brackets after the associated project
-name. (Or if the extras were listed in a requirement spec on the EasyInstall
-command line.)
-
-Extras can be used by a project's `entry points`_ to specify dynamic
-dependencies. For example, if Project A includes a "rst2pdf" script, it might
-declare it like this, so that the "PDF" requirements are only resolved if the
-"rst2pdf" script is run::
-
- setup(
- name="Project-A",
- ...
- entry_points={
- 'console_scripts': [
- 'rst2pdf = project_a.tools.pdfgen [PDF]',
- 'rst2html = project_a.tools.htmlgen',
- # more script entry points ...
- ],
- }
- )
-
-Projects can also use another project's extras when specifying dependencies.
-For example, if project B needs "project A" with PDF support installed, it
-might declare the dependency like this::
-
- setup(
- name="Project-B",
- install_requires=["Project-A[PDF]"],
- ...
- )
-
-This will cause ReportLab to be installed along with project A, if project B is
-installed -- even if project A was already installed. In this way, a project
-can encapsulate groups of optional "downstream dependencies" under a feature
-name, so that packages that depend on it don't have to know what the downstream
-dependencies are. If a later version of Project A builds in PDF support and
-no longer needs ReportLab, or if it ends up needing other dependencies besides
-ReportLab in order to provide PDF support, Project B's setup information does
-not need to change, but the right packages will still be installed if needed.
-
-Note, by the way, that if a project ends up not needing any other packages to
-support a feature, it should keep an empty requirements list for that feature
-in its ``extras_require`` argument, so that packages depending on that feature
-don't break (due to an invalid feature name). For example, if Project A above
-builds in PDF support and no longer needs ReportLab, it could change its
-setup to this::
-
- setup(
- name="Project-A",
- ...
- extras_require={
- 'PDF': [],
- 'reST': ["docutils>=0.3"],
- }
- )
-
-so that Package B doesn't have to remove the ``[PDF]`` from its requirement
-specifier.
-
-
-.. _Platform Specific Dependencies:
-
-
-Declaring platform specific dependencies
-----------------------------------------
-
-Sometimes a project might require a dependency to run on a specific platform.
-This could to a package that back ports a module so that it can be used in
-older python versions. Or it could be a package that is required to run on a
-specific operating system. This will allow a project to work on multiple
-different platforms without installing dependencies that are not required for
-a platform that is installing the project.
-
-For example, here is a project that uses the ``enum`` module and ``pywin32``::
-
- setup(
- name="Project",
- ...
- install_requires=[
- 'enum34;python_version<"3.4"',
- 'pywin32 >= 1.0;platform_system=="Windows"'
- ]
- )
-
-Since the ``enum`` module was added in Python 3.4, it should only be installed
-if the python version is earlier. Since ``pywin32`` will only be used on
-windows, it should only be installed when the operating system is Windows.
-Specifying version requirements for the dependencies is supported as normal.
-
-The environmental markers that may be used for testing platform types are
-detailed in `PEP 508`_.
-
-.. _PEP 508: https://www.python.org/dev/peps/pep-0508/
-
-Including Data Files
-====================
-
-The distutils have traditionally allowed installation of "data files", which
-are placed in a platform-specific location. However, the most common use case
-for data files distributed with a package is for use *by* the package, usually
-by including the data files in the package directory.
-
-Setuptools offers three ways to specify data files to be included in your
-packages. First, you can simply use the ``include_package_data`` keyword,
-e.g.::
-
- from setuptools import setup, find_packages
- setup(
- ...
- include_package_data=True
- )
-
-This tells setuptools to install any data files it finds in your packages.
-The data files must be specified via the distutils' ``MANIFEST.in`` file.
-(They can also be tracked by a revision control system, using an appropriate
-plugin. See the section below on `Adding Support for Revision Control
-Systems`_ for information on how to write such plugins.)
-
-If you want finer-grained control over what files are included (for example,
-if you have documentation files in your package directories and want to exclude
-them from installation), then you can also use the ``package_data`` keyword,
-e.g.::
-
- from setuptools import setup, find_packages
- setup(
- ...
- package_data={
- # If any package contains *.txt or *.rst files, include them:
- '': ['*.txt', '*.rst'],
- # And include any *.msg files found in the 'hello' package, too:
- 'hello': ['*.msg'],
- }
- )
-
-The ``package_data`` argument is a dictionary that maps from package names to
-lists of glob patterns. The globs may include subdirectory names, if the data
-files are contained in a subdirectory of the package. For example, if the
-package tree looks like this::
-
- setup.py
- src/
- mypkg/
- __init__.py
- mypkg.txt
- data/
- somefile.dat
- otherdata.dat
-
-The setuptools setup file might look like this::
-
- from setuptools import setup, find_packages
- setup(
- ...
- packages=find_packages('src'), # include all packages under src
- package_dir={'':'src'}, # tell distutils packages are under src
-
- package_data={
- # If any package contains *.txt files, include them:
- '': ['*.txt'],
- # And include any *.dat files found in the 'data' subdirectory
- # of the 'mypkg' package, also:
- 'mypkg': ['data/*.dat'],
- }
- )
-
-Notice that if you list patterns in ``package_data`` under the empty string,
-these patterns are used to find files in every package, even ones that also
-have their own patterns listed. Thus, in the above example, the ``mypkg.txt``
-file gets included even though it's not listed in the patterns for ``mypkg``.
-
-Also notice that if you use paths, you *must* use a forward slash (``/``) as
-the path separator, even if you are on Windows. Setuptools automatically
-converts slashes to appropriate platform-specific separators at build time.
-
-If datafiles are contained in a subdirectory of a package that isn't a package
-itself (no ``__init__.py``), then the subdirectory names (or ``*``) are required
-in the ``package_data`` argument (as shown above with ``'data/*.dat'``).
-
-When building an ``sdist``, the datafiles are also drawn from the
-``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if
-the ``setup.py`` ``package_data`` list is updated before calling ``setup.py``.
-
-(Note: although the ``package_data`` argument was previously only available in
-``setuptools``, it was also added to the Python ``distutils`` package as of
-Python 2.4; there is `some documentation for the feature`__ available on the
-python.org website. If using the setuptools-specific ``include_package_data``
-argument, files specified by ``package_data`` will *not* be automatically
-added to the manifest unless they are listed in the MANIFEST.in file.)
-
-__ http://docs.python.org/dist/node11.html
-
-Sometimes, the ``include_package_data`` or ``package_data`` options alone
-aren't sufficient to precisely define what files you want included. For
-example, you may want to include package README files in your revision control
-system and source distributions, but exclude them from being installed. So,
-setuptools offers an ``exclude_package_data`` option as well, that allows you
-to do things like this::
-
- from setuptools import setup, find_packages
- setup(
- ...
- packages=find_packages('src'), # include all packages under src
- package_dir={'':'src'}, # tell distutils packages are under src
-
- include_package_data=True, # include everything in source control
-
- # ...but exclude README.txt from all packages
- exclude_package_data={'': ['README.txt']},
- )
-
-The ``exclude_package_data`` option is a dictionary mapping package names to
-lists of wildcard patterns, just like the ``package_data`` option. And, just
-as with that option, a key of ``''`` will apply the given pattern(s) to all
-packages. However, any files that match these patterns will be *excluded*
-from installation, even if they were listed in ``package_data`` or were
-included as a result of using ``include_package_data``.
-
-In summary, the three options allow you to:
-
-``include_package_data``
- Accept all data files and directories matched by ``MANIFEST.in``.
-
-``package_data``
- Specify additional patterns to match files that may or may
- not be matched by ``MANIFEST.in`` or found in source control.
-
-``exclude_package_data``
- Specify patterns for data files and directories that should *not* be
- included when a package is installed, even if they would otherwise have
- been included due to the use of the preceding options.
-
-NOTE: Due to the way the distutils build process works, a data file that you
-include in your project and then stop including may be "orphaned" in your
-project's build directories, requiring you to run ``setup.py clean --all`` to
-fully remove them. This may also be important for your users and contributors
-if they track intermediate revisions of your project using Subversion; be sure
-to let them know when you make changes that remove files from inclusion so they
-can run ``setup.py clean --all``.
-
-
-Accessing Data Files at Runtime
--------------------------------
-
-Typically, existing programs manipulate a package's ``__file__`` attribute in
-order to find the location of data files. However, this manipulation isn't
-compatible with PEP 302-based import hooks, including importing from zip files
-and Python Eggs. It is strongly recommended that, if you are using data files,
-you should use the :ref:`ResourceManager API` of ``pkg_resources`` to access
-them. The ``pkg_resources`` module is distributed as part of setuptools, so if
-you're using setuptools to distribute your package, there is no reason not to
-use its resource management API. See also `Accessing Package Resources`_ for
-a quick example of converting code that uses ``__file__`` to use
-``pkg_resources`` instead.
-
-.. _Accessing Package Resources: http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources
-
-
-Non-Package Data Files
-----------------------
-
-The ``distutils`` normally install general "data files" to a platform-specific
-location (e.g. ``/usr/share``). This feature intended to be used for things
-like documentation, example configuration files, and the like. ``setuptools``
-does not install these data files in a separate location, however. They are
-bundled inside the egg file or directory, alongside the Python modules and
-packages. The data files can also be accessed using the :ref:`ResourceManager
-API`, by specifying a ``Requirement`` instead of a package name::
-
- from pkg_resources import Requirement, resource_filename
- filename = resource_filename(Requirement.parse("MyProject"),"sample.conf")
-
-The above code will obtain the filename of the "sample.conf" file in the data
-root of the "MyProject" distribution.
-
-Note, by the way, that this encapsulation of data files means that you can't
-actually install data files to some arbitrary location on a user's machine;
-this is a feature, not a bug. You can always include a script in your
-distribution that extracts and copies your the documentation or data files to
-a user-specified location, at their discretion. If you put related data files
-in a single directory, you can use ``resource_filename()`` with the directory
-name to get a filesystem directory that then can be copied with the ``shutil``
-module. (Even if your package is installed as a zipfile, calling
-``resource_filename()`` on a directory will return an actual filesystem
-directory, whose contents will be that entire subtree of your distribution.)
-
-(Of course, if you're writing a new package, you can just as easily place your
-data files or directories inside one of your packages, rather than using the
-distutils' approach. However, if you're updating an existing application, it
-may be simpler not to change the way it currently specifies these data files.)
-
-
-Automatic Resource Extraction
------------------------------
-
-If you are using tools that expect your resources to be "real" files, or your
-project includes non-extension native libraries or other files that your C
-extensions expect to be able to access, you may need to list those files in
-the ``eager_resources`` argument to ``setup()``, so that the files will be
-extracted together, whenever a C extension in the project is imported.
-
-This is especially important if your project includes shared libraries *other*
-than distutils-built C extensions, and those shared libraries use file
-extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
-extensions that setuptools 0.6a8 and higher automatically detects as shared
-libraries and adds to the ``native_libs.txt`` file for you. Any shared
-libraries whose names do not end with one of those extensions should be listed
-as ``eager_resources``, because they need to be present in the filesystem when
-he C extensions that link to them are used.
-
-The ``pkg_resources`` runtime for compressed packages will automatically
-extract *all* C extensions and ``eager_resources`` at the same time, whenever
-*any* C extension or eager resource is requested via the ``resource_filename()``
-API. (C extensions are imported using ``resource_filename()`` internally.)
-This ensures that C extensions will see all of the "real" files that they
-expect to see.
-
-Note also that you can list directory resource names in ``eager_resources`` as
-well, in which case the directory's contents (including subdirectories) will be
-extracted whenever any C extension or eager resource is requested.
-
-Please note that if you're not sure whether you need to use this argument, you
-don't! It's really intended to support projects with lots of non-Python
-dependencies and as a last resort for crufty projects that can't otherwise
-handle being compressed. If your package is pure Python, Python plus data
-files, or Python plus C, you really don't need this. You've got to be using
-either C or an external program that needs "real" files in your project before
-there's any possibility of ``eager_resources`` being relevant to your project.
-
-
-Extensible Applications and Frameworks
-======================================
-
-
-.. _Entry Points:
-
-Dynamic Discovery of Services and Plugins
------------------------------------------
-
-``setuptools`` supports creating libraries that "plug in" to extensible
-applications and frameworks, by letting you register "entry points" in your
-project that can be imported by the application or framework.
-
-For example, suppose that a blogging tool wants to support plugins
-that provide translation for various file types to the blog's output format.
-The framework might define an "entry point group" called ``blogtool.parsers``,
-and then allow plugins to register entry points for the file extensions they
-support.
-
-This would allow people to create distributions that contain one or more
-parsers for different file types, and then the blogging tool would be able to
-find the parsers at runtime by looking up an entry point for the file
-extension (or mime type, or however it wants to).
-
-Note that if the blogging tool includes parsers for certain file formats, it
-can register these as entry points in its own setup script, which means it
-doesn't have to special-case its built-in formats. They can just be treated
-the same as any other plugin's entry points would be.
-
-If you're creating a project that plugs in to an existing application or
-framework, you'll need to know what entry points or entry point groups are
-defined by that application or framework. Then, you can register entry points
-in your setup script. Here are a few examples of ways you might register an
-``.rst`` file parser entry point in the ``blogtool.parsers`` entry point group,
-for our hypothetical blogging tool::
-
- setup(
- # ...
- entry_points={'blogtool.parsers': '.rst = some_module:SomeClass'}
- )
-
- setup(
- # ...
- entry_points={'blogtool.parsers': ['.rst = some_module:a_func']}
- )
-
- setup(
- # ...
- entry_points="""
- [blogtool.parsers]
- .rst = some.nested.module:SomeClass.some_classmethod [reST]
- """,
- extras_require=dict(reST="Docutils>=0.3.5")
- )
-
-The ``entry_points`` argument to ``setup()`` accepts either a string with
-``.ini``-style sections, or a dictionary mapping entry point group names to
-either strings or lists of strings containing entry point specifiers. An
-entry point specifier consists of a name and value, separated by an ``=``
-sign. The value consists of a dotted module name, optionally followed by a
-``:`` and a dotted identifier naming an object within the module. It can
-also include a bracketed list of "extras" that are required for the entry
-point to be used. When the invoking application or framework requests loading
-of an entry point, any requirements implied by the associated extras will be
-passed to ``pkg_resources.require()``, so that an appropriate error message
-can be displayed if the needed package(s) are missing. (Of course, the
-invoking app or framework can ignore such errors if it wants to make an entry
-point optional if a requirement isn't installed.)
-
-
-Defining Additional Metadata
-----------------------------
-
-Some extensible applications and frameworks may need to define their own kinds
-of metadata to include in eggs, which they can then access using the
-``pkg_resources`` metadata APIs. Ordinarily, this is done by having plugin
-developers include additional files in their ``ProjectName.egg-info``
-directory. However, since it can be tedious to create such files by hand, you
-may want to create a distutils extension that will create the necessary files
-from arguments to ``setup()``, in much the same way that ``setuptools`` does
-for many of the ``setup()`` arguments it adds. See the section below on
-`Creating distutils Extensions`_ for more details, especially the subsection on
-`Adding new EGG-INFO Files`_.
-
-
-"Development Mode"
-==================
-
-Under normal circumstances, the ``distutils`` assume that you are going to
-build a distribution of your project, not use it in its "raw" or "unbuilt"
-form. If you were to use the ``distutils`` that way, you would have to rebuild
-and reinstall your project every time you made a change to it during
-development.
-
-Another problem that sometimes comes up with the ``distutils`` is that you may
-need to do development on two related projects at the same time. You may need
-to put both projects' packages in the same directory to run them, but need to
-keep them separate for revision control purposes. How can you do this?
-
-Setuptools allows you to deploy your projects for use in a common directory or
-staging area, but without copying any files. Thus, you can edit each project's
-code in its checkout directory, and only need to run build commands when you
-change a project's C extensions or similarly compiled files. You can even
-deploy a project into another project's checkout directory, if that's your
-preferred way of working (as opposed to using a common independent staging area
-or the site-packages directory).
-
-To do this, use the ``setup.py develop`` command. It works very similarly to
-``setup.py install`` or the EasyInstall tool, except that it doesn't actually
-install anything. Instead, it creates a special ``.egg-link`` file in the
-deployment directory, that links to your project's source code. And, if your
-deployment directory is Python's ``site-packages`` directory, it will also
-update the ``easy-install.pth`` file to include your project's source code,
-thereby making it available on ``sys.path`` for all programs using that Python
-installation.
-
-If you have enabled the ``use_2to3`` flag, then of course the ``.egg-link``
-will not link directly to your source code when run under Python 3, since
-that source code would be made for Python 2 and not work under Python 3.
-Instead the ``setup.py develop`` will build Python 3 code under the ``build``
-directory, and link there. This means that after doing code changes you will
-have to run ``setup.py build`` before these changes are picked up by your
-Python 3 installation.
-
-In addition, the ``develop`` command creates wrapper scripts in the target
-script directory that will run your in-development scripts after ensuring that
-all your ``install_requires`` packages are available on ``sys.path``.
-
-You can deploy the same project to multiple staging areas, e.g. if you have
-multiple projects on the same machine that are sharing the same project you're
-doing development work.
-
-When you're done with a given development task, you can remove the project
-source from a staging area using ``setup.py develop --uninstall``, specifying
-the desired staging area if it's not the default.
-
-There are several options to control the precise behavior of the ``develop``
-command; see the section on the `develop`_ command below for more details.
-
-Note that you can also apply setuptools commands to non-setuptools projects,
-using commands like this::
-
- python -c "import setuptools; execfile('setup.py')" develop
-
-That is, you can simply list the normal setup commands and options following
-the quoted part.
-
-
-Distributing a ``setuptools``-based project
-===========================================
-
-Using ``setuptools``... Without bundling it!
----------------------------------------------
-
-.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support.
-
-Your users might not have ``setuptools`` installed on their machines, or even
-if they do, it might not be the right version. Fixing this is easy; just
-download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
-script. (Be sure to add it to your revision control system, too.) Then add
-these two lines to the very top of your setup script, before the script imports
-anything from setuptools:
-
-.. code-block:: python
-
- import ez_setup
- ez_setup.use_setuptools()
-
-That's it. The ``ez_setup`` module will automatically download a matching
-version of ``setuptools`` from PyPI, if it isn't present on the target system.
-Whenever you install an updated version of setuptools, you should also update
-your projects' ``ez_setup.py`` files, so that a matching version gets installed
-on the target machine(s).
-
-By the way, setuptools supports the new PyPI "upload" command, so you can use
-``setup.py sdist upload`` or ``setup.py bdist_egg upload`` to upload your
-source or egg distributions respectively. Your project's current version must
-be registered with PyPI first, of course; you can use ``setup.py register`` to
-do that. Or you can do it all in one step, e.g. ``setup.py register sdist
-bdist_egg upload`` will register the package, build source and egg
-distributions, and then upload them both to PyPI, where they'll be easily
-found by other projects that depend on them.
-
-(By the way, if you need to distribute a specific version of ``setuptools``,
-you can specify the exact version and base download URL as parameters to the
-``use_setuptools()`` function. See the function's docstring for details.)
-
-
-What Your Users Should Know
----------------------------
-
-In general, a setuptools-based project looks just like any distutils-based
-project -- as long as your users have an internet connection and are installing
-to ``site-packages``, that is. But for some users, these conditions don't
-apply, and they may become frustrated if this is their first encounter with
-a setuptools-based project. To keep these users happy, you should review the
-following topics in your project's installation instructions, if they are
-relevant to your project and your target audience isn't already familiar with
-setuptools and ``easy_install``.
-
-Network Access
- If your project is using ``ez_setup``, you should inform users of the
- need to either have network access, or to preinstall the correct version of
- setuptools using the `EasyInstall installation instructions`_. Those
- instructions also have tips for dealing with firewalls as well as how to
- manually download and install setuptools.
-
-Custom Installation Locations
- You should inform your users that if they are installing your project to
- somewhere other than the main ``site-packages`` directory, they should
- first install setuptools using the instructions for `Custom Installation
- Locations`_, before installing your project.
-
-Your Project's Dependencies
- If your project depends on other projects that may need to be downloaded
- from PyPI or elsewhere, you should list them in your installation
- instructions, or tell users how to find out what they are. While most
- users will not need this information, any users who don't have unrestricted
- internet access may have to find, download, and install the other projects
- manually. (Note, however, that they must still install those projects
- using ``easy_install``, or your project will not know they are installed,
- and your setup script will try to download them again.)
-
- If you want to be especially friendly to users with limited network access,
- you may wish to build eggs for your project and its dependencies, making
- them all available for download from your site, or at least create a page
- with links to all of the needed eggs. In this way, users with limited
- network access can manually download all the eggs to a single directory,
- then use the ``-f`` option of ``easy_install`` to specify the directory
- to find eggs in. Users who have full network access can just use ``-f``
- with the URL of your download page, and ``easy_install`` will find all the
- needed eggs using your links directly. This is also useful when your
- target audience isn't able to compile packages (e.g. most Windows users)
- and your package or some of its dependencies include C code.
-
-Revision Control System Users and Co-Developers
- Users and co-developers who are tracking your in-development code using
- a revision control system should probably read this manual's sections
- regarding such development. Alternately, you may wish to create a
- quick-reference guide containing the tips from this manual that apply to
- your particular situation. For example, if you recommend that people use
- ``setup.py develop`` when tracking your in-development code, you should let
- them know that this needs to be run after every update or commit.
-
- Similarly, if you remove modules or data files from your project, you
- should remind them to run ``setup.py clean --all`` and delete any obsolete
- ``.pyc`` or ``.pyo``. (This tip applies to the distutils in general, not
- just setuptools, but not everybody knows about them; be kind to your users
- by spelling out your project's best practices rather than leaving them
- guessing.)
-
-Creating System Packages
- Some users want to manage all Python packages using a single package
- manager, and sometimes that package manager isn't ``easy_install``!
- Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
- ``bdist_dumb`` formats for system packaging. If a user has a locally-
- installed "bdist" packaging tool that internally uses the distutils
- ``install`` command, it should be able to work with ``setuptools``. Some
- examples of "bdist" formats that this should work with include the
- ``bdist_nsi`` and ``bdist_msi`` formats for Windows.
-
- However, packaging tools that build binary distributions by running
- ``setup.py install`` on the command line or as a subprocess will require
- modification to work with setuptools. They should use the
- ``--single-version-externally-managed`` option to the ``install`` command,
- combined with the standard ``--root`` or ``--record`` options.
- See the `install command`_ documentation below for more details. The
- ``bdist_deb`` command is an example of a command that currently requires
- this kind of patching to work with setuptools.
-
- If you or your users have a problem building a usable system package for
- your project, please report the problem via the mailing list so that
- either the "bdist" tool in question or setuptools can be modified to
- resolve the issue.
-
-
-Setting the ``zip_safe`` flag
------------------------------
-
-For some use cases (such as bundling as part of a larger application), Python
-packages may be run directly from a zip file.
-Not all packages, however, are capable of running in compressed form, because
-they may expect to be able to access either source code or data files as
-normal operating system files. So, ``setuptools`` can install your project
-as a zipfile or a directory, and its default choice is determined by the
-project's ``zip_safe`` flag.
-
-You can pass a True or False value for the ``zip_safe`` argument to the
-``setup()`` function, or you can omit it. If you omit it, the ``bdist_egg``
-command will analyze your project's contents to see if it can detect any
-conditions that would prevent it from working in a zipfile. It will output
-notices to the console about any such conditions that it finds.
-
-Currently, this analysis is extremely conservative: it will consider the
-project unsafe if it contains any C extensions or datafiles whatsoever. This
-does *not* mean that the project can't or won't work as a zipfile! It just
-means that the ``bdist_egg`` authors aren't yet comfortable asserting that
-the project *will* work. If the project contains no C or data files, and does
-no ``__file__`` or ``__path__`` introspection or source code manipulation, then
-there is an extremely solid chance the project will work when installed as a
-zipfile. (And if the project uses ``pkg_resources`` for all its data file
-access, then C extensions and other data files shouldn't be a problem at all.
-See the `Accessing Data Files at Runtime`_ section above for more information.)
-
-However, if ``bdist_egg`` can't be *sure* that your package will work, but
-you've checked over all the warnings it issued, and you are either satisfied it
-*will* work (or if you want to try it for yourself), then you should set
-``zip_safe`` to ``True`` in your ``setup()`` call. If it turns out that it
-doesn't work, you can always change it to ``False``, which will force
-``setuptools`` to install your project as a directory rather than as a zipfile.
-
-Of course, the end-user can still override either decision, if they are using
-EasyInstall to install your package. And, if you want to override for testing
-purposes, you can just run ``setup.py easy_install --zip-ok .`` or ``setup.py
-easy_install --always-unzip .`` in your project directory. to install the
-package as a zipfile or directory, respectively.
-
-In the future, as we gain more experience with different packages and become
-more satisfied with the robustness of the ``pkg_resources`` runtime, the
-"zip safety" analysis may become less conservative. However, we strongly
-recommend that you determine for yourself whether your project functions
-correctly when installed as a zipfile, correct any problems if you can, and
-then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
-flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to
-try to guess whether your project can work as a zipfile.
-
-
-Namespace Packages
-------------------
-
-Sometimes, a large package is more useful if distributed as a collection of
-smaller eggs. However, Python does not normally allow the contents of a
-package to be retrieved from more than one location. "Namespace packages"
-are a solution for this problem. When you declare a package to be a namespace
-package, it means that the package has no meaningful contents in its
-``__init__.py``, and that it is merely a container for modules and subpackages.
-
-The ``pkg_resources`` runtime will then automatically ensure that the contents
-of namespace packages that are spread over multiple eggs or directories are
-combined into a single "virtual" package.
-
-The ``namespace_packages`` argument to ``setup()`` lets you declare your
-project's namespace packages, so that they will be included in your project's
-metadata. The argument should list the namespace packages that the egg
-participates in. For example, the ZopeInterface project might do this::
-
- setup(
- # ...
- namespace_packages=['zope']
- )
-
-because it contains a ``zope.interface`` package that lives in the ``zope``
-namespace package. Similarly, a project for a standalone ``zope.publisher``
-would also declare the ``zope`` namespace package. When these projects are
-installed and used, Python will see them both as part of a "virtual" ``zope``
-package, even though they will be installed in different locations.
-
-Namespace packages don't have to be top-level packages. For example, Zope 3's
-``zope.app`` package is a namespace package, and in the future PEAK's
-``peak.util`` package will be too.
-
-Note, by the way, that your project's source tree must include the namespace
-packages' ``__init__.py`` files (and the ``__init__.py`` of any parent
-packages), in a normal Python package layout. These ``__init__.py`` files
-*must* contain the line::
-
- __import__('pkg_resources').declare_namespace(__name__)
-
-This code ensures that the namespace package machinery is operating and that
-the current package is registered as a namespace package.
-
-You must NOT include any other code and data in a namespace package's
-``__init__.py``. Even though it may appear to work during development, or when
-projects are installed as ``.egg`` files, it will not work when the projects
-are installed using "system" packaging tools -- in such cases the
-``__init__.py`` files will not be installed, let alone executed.
-
-You must include the ``declare_namespace()`` line in the ``__init__.py`` of
-*every* project that has contents for the namespace package in question, in
-order to ensure that the namespace will be declared regardless of which
-project's copy of ``__init__.py`` is loaded first. If the first loaded
-``__init__.py`` doesn't declare it, it will never *be* declared, because no
-other copies will ever be loaded!
-
-
-TRANSITIONAL NOTE
-~~~~~~~~~~~~~~~~~
-
-Setuptools automatically calls ``declare_namespace()`` for you at runtime,
-but future versions may *not*. This is because the automatic declaration
-feature has some negative side effects, such as needing to import all namespace
-packages during the initialization of the ``pkg_resources`` runtime, and also
-the need for ``pkg_resources`` to be explicitly imported before any namespace
-packages work at all. In some future releases, you'll be responsible
-for including your own declaration lines, and the automatic declaration feature
-will be dropped to get rid of the negative side effects.
-
-During the remainder of the current development cycle, therefore, setuptools
-will warn you about missing ``declare_namespace()`` calls in your
-``__init__.py`` files, and you should correct these as soon as possible
-before the compatibility support is removed.
-Namespace packages without declaration lines will not work
-correctly once a user has upgraded to a later version, so it's important that
-you make this change now in order to avoid having your code break in the field.
-Our apologies for the inconvenience, and thank you for your patience.
-
-
-
-Tagging and "Daily Build" or "Snapshot" Releases
-------------------------------------------------
-
-When a set of related projects are under development, it may be important to
-track finer-grained version increments than you would normally use for e.g.
-"stable" releases. While stable releases might be measured in dotted numbers
-with alpha/beta/etc. status codes, development versions of a project often
-need to be tracked by revision or build number or even build date. This is
-especially true when projects in development need to refer to one another, and
-therefore may literally need an up-to-the-minute version of something!
-
-To support these scenarios, ``setuptools`` allows you to "tag" your source and
-egg distributions by adding one or more of the following to the project's
-"official" version identifier:
-
-* A manually-specified pre-release tag, such as "build" or "dev", or a
- manually-specified post-release tag, such as a build or revision number
- (``--tag-build=STRING, -bSTRING``)
-
-* An 8-character representation of the build date (``--tag-date, -d``), as
- a postrelease tag
-
-You can add these tags by adding ``egg_info`` and the desired options to
-the command line ahead of the ``sdist`` or ``bdist`` commands that you want
-to generate a daily build or snapshot for. See the section below on the
-`egg_info`_ command for more details.
-
-(Also, before you release your project, be sure to see the section above on
-`Specifying Your Project's Version`_ for more information about how pre- and
-post-release tags affect how setuptools and EasyInstall interpret version
-numbers. This is important in order to make sure that dependency processing
-tools will know which versions of your project are newer than others.)
-
-Finally, if you are creating builds frequently, and either building them in a
-downloadable location or are copying them to a distribution server, you should
-probably also check out the `rotate`_ command, which lets you automatically
-delete all but the N most-recently-modified distributions matching a glob
-pattern. So, you can use a command line like::
-
- setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
-
-to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
-most recent Subversion revision that affected the source tree), and then
-delete any egg files from the distribution directory except for the three
-that were built most recently.
-
-If you have to manage automated builds for multiple packages, each with
-different tagging and rotation policies, you may also want to check out the
-`alias`_ command, which would let each package define an alias like ``daily``
-that would perform the necessary tag, build, and rotate commands. Then, a
-simpler script or cron job could just run ``setup.py daily`` in each project
-directory. (And, you could also define sitewide or per-user default versions
-of the ``daily`` alias, so that projects that didn't define their own would
-use the appropriate defaults.)
-
-
-Generating Source Distributions
--------------------------------
-
-``setuptools`` enhances the distutils' default algorithm for source file
-selection with pluggable endpoints for looking up files to include. If you are
-using a revision control system, and your source distributions only need to
-include files that you're tracking in revision control, use a corresponding
-plugin instead of writing a ``MANIFEST.in`` file. See the section below on
-`Adding Support for Revision Control Systems`_ for information on plugins.
-
-If you need to include automatically generated files, or files that are kept in
-an unsupported revision control system, you'll need to create a ``MANIFEST.in``
-file to specify any files that the default file location algorithm doesn't
-catch. See the distutils documentation for more information on the format of
-the ``MANIFEST.in`` file.
-
-But, be sure to ignore any part of the distutils documentation that deals with
-``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
-from these issues and doesn't work the same way in any case. Unlike the
-distutils, setuptools regenerates the source distribution manifest file
-every time you build a source distribution, and it builds it inside the
-project's ``.egg-info`` directory, out of the way of your main project
-directory. You therefore need not worry about whether it is up-to-date or not.
-
-Indeed, because setuptools' approach to determining the contents of a source
-distribution is so much simpler, its ``sdist`` command omits nearly all of
-the options that the distutils' more complex ``sdist`` process requires. For
-all practical purposes, you'll probably use only the ``--formats`` option, if
-you use any option at all.
-
-
-Making your package available for EasyInstall
----------------------------------------------
-
-If you use the ``register`` command (``setup.py register``) to register your
-package with PyPI, that's most of the battle right there. (See the
-`docs for the register command`_ for more details.)
-
-.. _docs for the register command: http://docs.python.org/dist/package-index.html
-
-If you also use the `upload`_ command to upload actual distributions of your
-package, that's even better, because EasyInstall will be able to find and
-download them directly from your project's PyPI page.
-
-However, there may be reasons why you don't want to upload distributions to
-PyPI, and just want your existing distributions (or perhaps a Subversion
-checkout) to be used instead.
-
-So here's what you need to do before running the ``register`` command. There
-are three ``setup()`` arguments that affect EasyInstall:
-
-``url`` and ``download_url``
- These become links on your project's PyPI page. EasyInstall will examine
- them to see if they link to a package ("primary links"), or whether they are
- HTML pages. If they're HTML pages, EasyInstall scans all HREF's on the
- page for primary links
-
-``long_description``
- EasyInstall will check any URLs contained in this argument to see if they
- are primary links.
-
-A URL is considered a "primary link" if it is a link to a .tar.gz, .tgz, .zip,
-.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an ``#egg=project`` or
-``#egg=project-version`` fragment identifier attached to it. EasyInstall
-attempts to determine a project name and optional version number from the text
-of a primary link *without* downloading it. When it has found all the primary
-links, EasyInstall will select the best match based on requested version,
-platform compatibility, and other criteria.
-
-So, if your ``url`` or ``download_url`` point either directly to a downloadable
-source distribution, or to HTML page(s) that have direct links to such, then
-EasyInstall will be able to locate downloads automatically. If you want to
-make Subversion checkouts available, then you should create links with either
-``#egg=project`` or ``#egg=project-version`` added to the URL. You should
-replace ``project`` and ``version`` with the values they would have in an egg
-filename. (Be sure to actually generate an egg and then use the initial part
-of the filename, rather than trying to guess what the escaped form of the
-project name and version number will be.)
-
-Note that Subversion checkout links are of lower precedence than other kinds
-of distributions, so EasyInstall will not select a Subversion checkout for
-downloading unless it has a version included in the ``#egg=`` suffix, and
-it's a higher version than EasyInstall has seen in any other links for your
-project.
-
-As a result, it's a common practice to use mark checkout URLs with a version of
-"dev" (i.e., ``#egg=projectname-dev``), so that users can do something like
-this::
-
- easy_install --editable projectname==dev
-
-in order to check out the in-development version of ``projectname``.
-
-
-Making "Official" (Non-Snapshot) Releases
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When you make an official release, creating source or binary distributions,
-you will need to override the tag settings from ``setup.cfg``, so that you
-don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
-easy to do if you are developing on the trunk and using tags or branches for
-your releases - just make the change to ``setup.cfg`` after branching or
-tagging the release, so the trunk will still produce development snapshots.
-
-Alternately, if you are not branching for releases, you can override the
-default version options on the command line, using something like::
-
- python setup.py egg_info -Db "" sdist bdist_egg register upload
-
-The first part of this command (``egg_info -Db ""``) will override the
-configured tag information, before creating source and binary eggs, registering
-the project with PyPI, and uploading the files. Thus, these commands will use
-the plain version from your ``setup.py``, without adding the build designation
-string.
-
-Of course, if you will be doing this a lot, you may wish to create a personal
-alias for this operation, e.g.::
-
- python setup.py alias -u release egg_info -Db ""
-
-You can then use it like this::
-
- python setup.py release sdist bdist_egg register upload
-
-Or of course you can create more elaborate aliases that do all of the above.
-See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
-
-
-
-Distributing Extensions compiled with Pyrex
--------------------------------------------
-
-``setuptools`` includes transparent support for building Pyrex extensions, as
-long as you define your extensions using ``setuptools.Extension``, *not*
-``distutils.Extension``. You must also not import anything from Pyrex in
-your setup script.
-
-If you follow these rules, you can safely list ``.pyx`` files as the source
-of your ``Extension`` objects in the setup script. ``setuptools`` will detect
-at build time whether Pyrex is installed or not. If it is, then ``setuptools``
-will use it. If not, then ``setuptools`` will silently change the
-``Extension`` objects to refer to the ``.c`` counterparts of the ``.pyx``
-files, so that the normal distutils C compilation process will occur.
-
-Of course, for this to work, your source distributions must include the C
-code generated by Pyrex, as well as your original ``.pyx`` files. This means
-that you will probably want to include current ``.c`` files in your revision
-control system, rebuilding them whenever you check changes in for the ``.pyx``
-source files. This will ensure that people tracking your project in a revision
-control system will be able to build it even if they don't have Pyrex
-installed, and that your source releases will be similarly usable with or
-without Pyrex.
-
-
------------------
-Command Reference
------------------
-
-.. _alias:
-
-``alias`` - Define shortcuts for commonly used commands
-=======================================================
-
-Sometimes, you need to use the same commands over and over, but you can't
-necessarily set them as defaults. For example, if you produce both development
-snapshot releases and "stable" releases of a project, you may want to put
-the distributions in different places, or use different ``egg_info`` tagging
-options, etc. In these cases, it doesn't make sense to set the options in
-a distutils configuration file, because the values of the options changed based
-on what you're trying to do.
-
-Setuptools therefore allows you to define "aliases" - shortcut names for
-an arbitrary string of commands and options, using ``setup.py alias aliasname
-expansion``, where aliasname is the name of the new alias, and the remainder of
-the command line supplies its expansion. For example, this command defines
-a sitewide alias called "daily", that sets various ``egg_info`` tagging
-options::
-
- setup.py alias --global-config daily egg_info --tag-build=development
-
-Once the alias is defined, it can then be used with other setup commands,
-e.g.::
-
- setup.py daily bdist_egg # generate a daily-build .egg file
- setup.py daily sdist # generate a daily-build source distro
- setup.py daily sdist bdist_egg # generate both
-
-The above commands are interpreted as if the word ``daily`` were replaced with
-``egg_info --tag-build=development``.
-
-Note that setuptools will expand each alias *at most once* in a given command
-line. This serves two purposes. First, if you accidentally create an alias
-loop, it will have no effect; you'll instead get an error message about an
-unknown command. Second, it allows you to define an alias for a command, that
-uses that command. For example, this (project-local) alias::
-
- setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
-
-redefines the ``bdist_egg`` command so that it always runs the ``rotate``
-command afterwards to delete all but the newest egg file. It doesn't loop
-indefinitely on ``bdist_egg`` because the alias is only expanded once when
-used.
-
-You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
-
- setup.py alias --global-config --remove daily
-
-would delete the "daily" alias we defined above.
-
-Aliases can be defined on a project-specific, per-user, or sitewide basis. The
-default is to define or remove a project-specific alias, but you can use any of
-the `configuration file options`_ (listed under the `saveopts`_ command, below)
-to determine which distutils configuration file an aliases will be added to
-(or removed from).
-
-Note that if you omit the "expansion" argument to the ``alias`` command,
-you'll get output showing that alias' current definition (and what
-configuration file it's defined in). If you omit the alias name as well,
-you'll get a listing of all current aliases along with their configuration
-file locations.
-
-
-``bdist_egg`` - Create a Python Egg for the project
-===================================================
-
-This command generates a Python Egg (``.egg`` file) for the project. Python
-Eggs are the preferred binary distribution format for EasyInstall, because they
-are cross-platform (for "pure" packages), directly importable, and contain
-project metadata including scripts and information about the project's
-dependencies. They can be simply downloaded and added to ``sys.path``
-directly, or they can be placed in a directory on ``sys.path`` and then
-automatically discovered by the egg runtime system.
-
-This command runs the `egg_info`_ command (if it hasn't already run) to update
-the project's metadata (``.egg-info``) directory. If you have added any extra
-metadata files to the ``.egg-info`` directory, those files will be included in
-the new egg file's metadata directory, for use by the egg runtime system or by
-any applications or frameworks that use that metadata.
-
-You won't usually need to specify any special options for this command; just
-use ``bdist_egg`` and you're done. But there are a few options that may
-be occasionally useful:
-
-``--dist-dir=DIR, -d DIR``
- Set the directory where the ``.egg`` file will be placed. If you don't
- supply this, then the ``--dist-dir`` setting of the ``bdist`` command
- will be used, which is usually a directory named ``dist`` in the project
- directory.
-
-``--plat-name=PLATFORM, -p PLATFORM``
- Set the platform name string that will be embedded in the egg's filename
- (assuming the egg contains C extensions). This can be used to override
- the distutils default platform name with something more meaningful. Keep
- in mind, however, that the egg runtime system expects to see eggs with
- distutils platform names, so it may ignore or reject eggs with non-standard
- platform names. Similarly, the EasyInstall program may ignore them when
- searching web pages for download links. However, if you are
- cross-compiling or doing some other unusual things, you might find a use
- for this option.
-
-``--exclude-source-files``
- Don't include any modules' ``.py`` files in the egg, just compiled Python,
- C, and data files. (Note that this doesn't affect any ``.py`` files in the
- EGG-INFO directory or its subdirectories, since for example there may be
- scripts with a ``.py`` extension which must still be retained.) We don't
- recommend that you use this option except for packages that are being
- bundled for proprietary end-user applications, or for "embedded" scenarios
- where space is at an absolute premium. On the other hand, if your package
- is going to be installed and used in compressed form, you might as well
- exclude the source because Python's ``traceback`` module doesn't currently
- understand how to display zipped source code anyway, or how to deal with
- files that are in a different place from where their code was compiled.
-
-There are also some options you will probably never need, but which are there
-because they were copied from similar ``bdist`` commands used as an example for
-creating this one. They may be useful for testing and debugging, however,
-which is why we kept them:
-
-``--keep-temp, -k``
- Keep the contents of the ``--bdist-dir`` tree around after creating the
- ``.egg`` file.
-
-``--bdist-dir=DIR, -b DIR``
- Set the temporary directory for creating the distribution. The entire
- contents of this directory are zipped to create the ``.egg`` file, after
- running various installation commands to copy the package's modules, data,
- and extensions here.
-
-``--skip-build``
- Skip doing any "build" commands; just go straight to the
- install-and-compress phases.
-
-
-.. _develop:
-
-``develop`` - Deploy the project source in "Development Mode"
-=============================================================
-
-This command allows you to deploy your project's source for use in one or more
-"staging areas" where it will be available for importing. This deployment is
-done in such a way that changes to the project source are immediately available
-in the staging area(s), without needing to run a build or install step after
-each change.
-
-The ``develop`` command works by creating an ``.egg-link`` file (named for the
-project) in the given staging area. If the staging area is Python's
-``site-packages`` directory, it also updates an ``easy-install.pth`` file so
-that the project is on ``sys.path`` by default for all programs run using that
-Python installation.
-
-The ``develop`` command also installs wrapper scripts in the staging area (or
-a separate directory, as specified) that will ensure the project's dependencies
-are available on ``sys.path`` before running the project's source scripts.
-And, it ensures that any missing project dependencies are available in the
-staging area, by downloading and installing them if necessary.
-
-Last, but not least, the ``develop`` command invokes the ``build_ext -i``
-command to ensure any C extensions in the project have been built and are
-up-to-date, and the ``egg_info`` command to ensure the project's metadata is
-updated (so that the runtime and wrappers know what the project's dependencies
-are). If you make any changes to the project's setup script or C extensions,
-you should rerun the ``develop`` command against all relevant staging areas to
-keep the project's scripts, metadata and extensions up-to-date. Most other
-kinds of changes to your project should not require any build operations or
-rerunning ``develop``, but keep in mind that even minor changes to the setup
-script (e.g. changing an entry point definition) require you to re-run the
-``develop`` or ``test`` commands to keep the distribution updated.
-
-Here are some of the options that the ``develop`` command accepts. Note that
-they affect the project's dependencies as well as the project itself, so if you
-have dependencies that need to be installed and you use ``--exclude-scripts``
-(for example), the dependencies' scripts will not be installed either! For
-this reason, you may want to use EasyInstall to install the project's
-dependencies before using the ``develop`` command, if you need finer control
-over the installation options for dependencies.
-
-``--uninstall, -u``
- Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
- option to designate the staging area. The created ``.egg-link`` file will
- be removed, if present and it is still pointing to the project directory.
- The project directory will be removed from ``easy-install.pth`` if the
- staging area is Python's ``site-packages`` directory.
-
- Note that this option currently does *not* uninstall script wrappers! You
- must uninstall them yourself, or overwrite them by using EasyInstall to
- activate a different version of the package. You can also avoid installing
- script wrappers in the first place, if you use the ``--exclude-scripts``
- (aka ``-x``) option when you run ``develop`` to deploy the project.
-
-``--multi-version, -m``
- "Multi-version" mode. Specifying this option prevents ``develop`` from
- adding an ``easy-install.pth`` entry for the project(s) being deployed, and
- if an entry for any version of a project already exists, the entry will be
- removed upon successful deployment. In multi-version mode, no specific
- version of the package is available for importing, unless you use
- ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
- a wrapper script generated by ``setuptools`` or EasyInstall. (In which
- case the wrapper script calls ``require()`` for you.)
-
- Note that if you install to a directory other than ``site-packages``,
- this option is automatically in effect, because ``.pth`` files can only be
- used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
- the ``--install-dir`` or ``-d`` option (or they are set via configuration
- file(s)) your project and its dependencies will be deployed in multi-
- version mode.
-
-``--install-dir=DIR, -d DIR``
- Set the installation directory (staging area). If this option is not
- directly specified on the command line or in a distutils configuration
- file, the distutils default installation location is used. Normally, this
- will be the ``site-packages`` directory, but if you are using distutils
- configuration files, setting things like ``prefix`` or ``install_lib``,
- then those settings are taken into account when computing the default
- staging area.
-
-``--script-dir=DIR, -s DIR``
- Set the script installation directory. If you don't supply this option
- (via the command line or a configuration file), but you *have* supplied
- an ``--install-dir`` (via command line or config file), then this option
- defaults to the same directory, so that the scripts will be able to find
- their associated package installation. Otherwise, this setting defaults
- to the location where the distutils would normally install scripts, taking
- any distutils configuration file settings into account.
-
-``--exclude-scripts, -x``
- Don't deploy script wrappers. This is useful if you don't want to disturb
- existing versions of the scripts in the staging area.
-
-``--always-copy, -a``
- Copy all needed distributions to the staging area, even if they
- are already present in another directory on ``sys.path``. By default, if
- a requirement can be met using a distribution that is already available in
- a directory on ``sys.path``, it will not be copied to the staging area.
-
-``--egg-path=DIR``
- Force the generated ``.egg-link`` file to use a specified relative path
- to the source directory. This can be useful in circumstances where your
- installation directory is being shared by code running under multiple
- platforms (e.g. Mac and Windows) which have different absolute locations
- for the code under development, but the same *relative* locations with
- respect to the installation directory. If you use this option when
- installing, you must supply the same relative path when uninstalling.
-
-In addition to the above options, the ``develop`` command also accepts all of
-the same options accepted by ``easy_install``. If you've configured any
-``easy_install`` settings in your ``setup.cfg`` (or other distutils config
-files), the ``develop`` command will use them as defaults, unless you override
-them in a ``[develop]`` section or on the command line.
-
-
-``easy_install`` - Find and install packages
-============================================
-
-This command runs the `EasyInstall tool
-<easy_install.html>`_ for you. It is exactly
-equivalent to running the ``easy_install`` command. All command line arguments
-following this command are consumed and not processed further by the distutils,
-so this must be the last command listed on the command line. Please see
-the EasyInstall documentation for the options reference and usage examples.
-Normally, there is no reason to use this command via the command line, as you
-can just use ``easy_install`` directly. It's only listed here so that you know
-it's a distutils command, which means that you can:
-
-* create command aliases that use it,
-* create distutils extensions that invoke it as a subcommand, and
-* configure options for it in your ``setup.cfg`` or other distutils config
- files.
-
-
-.. _egg_info:
-
-``egg_info`` - Create egg metadata and set build tags
-=====================================================
-
-This command performs two operations: it updates a project's ``.egg-info``
-metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
-commands), and it allows you to temporarily change a project's version string,
-to support "daily builds" or "snapshot" releases. It is run automatically by
-the ``sdist``, ``bdist_egg``, ``develop``, ``register``, and ``test`` commands
-in order to update the project's metadata, but you can also specify it
-explicitly in order to temporarily change the project's version string while
-executing other commands. (It also generates the``.egg-info/SOURCES.txt``
-manifest file, which is used when you are building source distributions.)
-
-In addition to writing the core egg metadata defined by ``setuptools`` and
-required by ``pkg_resources``, this command can be extended to write other
-metadata files as well, by defining entry points in the ``egg_info.writers``
-group. See the section on `Adding new EGG-INFO Files`_ below for more details.
-Note that using additional metadata writers may require you to include a
-``setup_requires`` argument to ``setup()`` in order to ensure that the desired
-writers are available on ``sys.path``.
-
-
-Release Tagging Options
------------------------
-
-The following options can be used to modify the project's version string for
-all remaining commands on the setup command line. The options are processed
-in the order shown, so if you use more than one, the requested tags will be
-added in the following order:
-
-``--tag-build=NAME, -b NAME``
- Append NAME to the project's version string. Due to the way setuptools
- processes "pre-release" version suffixes beginning with the letters "a"
- through "e" (like "alpha", "beta", and "candidate"), you will usually want
- to use a tag like ".build" or ".dev", as this will cause the version number
- to be considered *lower* than the project's default version. (If you
- want to make the version number *higher* than the default version, you can
- always leave off --tag-build and then use one or both of the following
- options.)
-
- If you have a default build tag set in your ``setup.cfg``, you can suppress
- it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
- to the ``egg_info`` command.
-
-``--tag-date, -d``
- Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
- project's version number.
-
-``--no-date, -D``
- Don't include a date stamp in the version number. This option is included
- so you can override a default setting in ``setup.cfg``.
-
-
-(Note: Because these options modify the version number used for source and
-binary distributions of your project, you should first make sure that you know
-how the resulting version numbers will be interpreted by automated tools
-like EasyInstall. See the section above on `Specifying Your Project's
-Version`_ for an explanation of pre- and post-release tags, as well as tips on
-how to choose and verify a versioning scheme for your your project.)
-
-For advanced uses, there is one other option that can be set, to change the
-location of the project's ``.egg-info`` directory. Commands that need to find
-the project's source directory or metadata should get it from this setting:
-
-
-Other ``egg_info`` Options
---------------------------
-
-``--egg-base=SOURCEDIR, -e SOURCEDIR``
- Specify the directory that should contain the .egg-info directory. This
- should normally be the root of your project's source tree (which is not
- necessarily the same as your project directory; some projects use a ``src``
- or ``lib`` subdirectory as the source root). You should not normally need
- to specify this directory, as it is normally determined from the
- ``package_dir`` argument to the ``setup()`` function, if any. If there is
- no ``package_dir`` set, this option defaults to the current directory.
-
-
-``egg_info`` Examples
----------------------
-
-Creating a dated "nightly build" snapshot egg::
-
- python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
-
-Creating and uploading a release with no version tags, even if some default
-tags are specified in ``setup.cfg``::
-
- python setup.py egg_info -RDb "" sdist bdist_egg register upload
-
-(Notice that ``egg_info`` must always appear on the command line *before* any
-commands that you want the version changes to apply to.)
-
-
-.. _install command:
-
-``install`` - Run ``easy_install`` or old-style installation
-============================================================
-
-The setuptools ``install`` command is basically a shortcut to run the
-``easy_install`` command on the current project. However, for convenience
-in creating "system packages" of setuptools-based projects, you can also
-use this option:
-
-``--single-version-externally-managed``
- This boolean option tells the ``install`` command to perform an "old style"
- installation, with the addition of an ``.egg-info`` directory so that the
- installed project will still have its metadata available and operate
- normally. If you use this option, you *must* also specify the ``--root``
- or ``--record`` options (or both), because otherwise you will have no way
- to identify and remove the installed files.
-
-This option is automatically in effect when ``install`` is invoked by another
-distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
-will create system packages of eggs. It is also automatically in effect if
-you specify the ``--root`` option.
-
-
-``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
-==============================================================================
-
-Setuptools runs this command as part of ``install`` operations that use the
-``--single-version-externally-managed`` options. You should not invoke it
-directly; it is documented here for completeness and so that distutils
-extensions such as system package builders can make use of it. This command
-has only one option:
-
-``--install-dir=DIR, -d DIR``
- The parent directory where the ``.egg-info`` directory will be placed.
- Defaults to the same as the ``--install-dir`` option specified for the
- ``install_lib`` command, which is usually the system ``site-packages``
- directory.
-
-This command assumes that the ``egg_info`` command has been given valid options
-via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
-command and use its options to locate the project's source ``.egg-info``
-directory.
-
-
-.. _rotate:
-
-``rotate`` - Delete outdated distribution files
-===============================================
-
-As you develop new versions of your project, your distribution (``dist``)
-directory will gradually fill up with older source and/or binary distribution
-files. The ``rotate`` command lets you automatically clean these up, keeping
-only the N most-recently modified files matching a given pattern.
-
-``--match=PATTERNLIST, -m PATTERNLIST``
- Comma-separated list of glob patterns to match. This option is *required*.
- The project name and ``-*`` is prepended to the supplied patterns, in order
- to match only distributions belonging to the current project (in case you
- have a shared distribution directory for multiple projects). Typically,
- you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
- the specified type. Note that each supplied pattern is treated as a
- distinct group of files for purposes of selecting files to delete.
-
-``--keep=COUNT, -k COUNT``
- Number of matching distributions to keep. For each group of files
- identified by a pattern specified with the ``--match`` option, delete all
- but the COUNT most-recently-modified files in that group. This option is
- *required*.
-
-``--dist-dir=DIR, -d DIR``
- Directory where the distributions are. This defaults to the value of the
- ``bdist`` command's ``--dist-dir`` option, which will usually be the
- project's ``dist`` subdirectory.
-
-**Example 1**: Delete all .tar.gz files from the distribution directory, except
-for the 3 most recently modified ones::
-
- setup.py rotate --match=.tar.gz --keep=3
-
-**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
-directory, except the most recently modified one for each Python version::
-
- setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
-
-
-.. _saveopts:
-
-``saveopts`` - Save used options to a configuration file
-========================================================
-
-Finding and editing ``distutils`` configuration files can be a pain, especially
-since you also have to translate the configuration options from command-line
-form to the proper configuration file format. You can avoid these hassles by
-using the ``saveopts`` command. Just add it to the command line to save the
-options you used. For example, this command builds the project using
-the ``mingw32`` C compiler, then saves the --compiler setting as the default
-for future builds (even those run implicitly by the ``install`` command)::
-
- setup.py build --compiler=mingw32 saveopts
-
-The ``saveopts`` command saves all options for every command specified on the
-command line to the project's local ``setup.cfg`` file, unless you use one of
-the `configuration file options`_ to change where the options are saved. For
-example, this command does the same as above, but saves the compiler setting
-to the site-wide (global) distutils configuration::
-
- setup.py build --compiler=mingw32 saveopts -g
-
-Note that it doesn't matter where you place the ``saveopts`` command on the
-command line; it will still save all the options specified for all commands.
-For example, this is another valid way to spell the last example::
-
- setup.py saveopts -g build --compiler=mingw32
-
-Note, however, that all of the commands specified are always run, regardless of
-where ``saveopts`` is placed on the command line.
-
-
-Configuration File Options
---------------------------
-
-Normally, settings such as options and aliases are saved to the project's
-local ``setup.cfg`` file. But you can override this and save them to the
-global or per-user configuration files, or to a manually-specified filename.
-
-``--global-config, -g``
- Save settings to the global ``distutils.cfg`` file inside the ``distutils``
- package directory. You must have write access to that directory to use
- this option. You also can't combine this option with ``-u`` or ``-f``.
-
-``--user-config, -u``
- Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
- ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option
- with ``-g`` or ``-f``.
-
-``--filename=FILENAME, -f FILENAME``
- Save settings to the specified configuration file to use. You can't
- combine this option with ``-g`` or ``-u``. Note that if you specify a
- non-standard filename, the ``distutils`` and ``setuptools`` will not
- use the file's contents. This option is mainly included for use in
- testing.
-
-These options are used by other ``setuptools`` commands that modify
-configuration files, such as the `alias`_ and `setopt`_ commands.
-
-
-.. _setopt:
-
-``setopt`` - Set a distutils or setuptools option in a config file
-==================================================================
-
-This command is mainly for use by scripts, but it can also be used as a quick
-and dirty way to change a distutils configuration option without having to
-remember what file the options are in and then open an editor.
-
-**Example 1**. Set the default C compiler to ``mingw32`` (using long option
-names)::
-
- setup.py setopt --command=build --option=compiler --set-value=mingw32
-
-**Example 2**. Remove any setting for the distutils default package
-installation directory (short option names)::
-
- setup.py setopt -c install -o install_lib -r
-
-
-Options for the ``setopt`` command:
-
-``--command=COMMAND, -c COMMAND``
- Command to set the option for. This option is required.
-
-``--option=OPTION, -o OPTION``
- The name of the option to set. This option is required.
-
-``--set-value=VALUE, -s VALUE``
- The value to set the option to. Not needed if ``-r`` or ``--remove`` is
- set.
-
-``--remove, -r``
- Remove (unset) the option, instead of setting it.
-
-In addition to the above options, you may use any of the `configuration file
-options`_ (listed under the `saveopts`_ command, above) to determine which
-distutils configuration file the option will be added to (or removed from).
-
-
-.. _test:
-
-``test`` - Build package and run a unittest suite
-=================================================
-
-When doing test-driven development, or running automated builds that need
-testing before they are deployed for downloading or use, it's often useful
-to be able to run a project's unit tests without actually deploying the project
-anywhere, even using the ``develop`` command. The ``test`` command runs a
-project's unit tests without actually deploying it, by temporarily putting the
-project's source on ``sys.path``, after first running ``build_ext -i`` and
-``egg_info`` to ensure that any C extensions and project metadata are
-up-to-date.
-
-To use this command, your project's tests must be wrapped in a ``unittest``
-test suite by either a function, a ``TestCase`` class or method, or a module
-or package containing ``TestCase`` classes. If the named suite is a module,
-and the module has an ``additional_tests()`` function, it is called and the
-result (which must be a ``unittest.TestSuite``) is added to the tests to be
-run. If the named suite is a package, any submodules and subpackages are
-recursively added to the overall test suite. (Note: if your project specifies
-a ``test_loader``, the rules for processing the chosen ``test_suite`` may
-differ; see the `test_loader`_ documentation for more details.)
-
-Note that many test systems including ``doctest`` support wrapping their
-non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
-package that does not support this, we suggest you encourage its developers to
-implement test suite support, as this is a convenient and standard way to
-aggregate a collection of tests to be run under a common test harness.
-
-By default, tests will be run in the "verbose" mode of the ``unittest``
-package's text test runner, but you can get the "quiet" mode (just dots) if
-you supply the ``-q`` or ``--quiet`` option, either as a global option to
-the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
-command itself (e.g. ``setup.py test -q``). There is one other option
-available:
-
-``--test-suite=NAME, -s NAME``
- Specify the test suite (or module, class, or method) to be run
- (e.g. ``some_module.test_suite``). The default for this option can be
- set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
-
- setup(
- # ...
- test_suite="my_package.tests.test_all"
- )
-
- If you did not set a ``test_suite`` in your ``setup()`` call, and do not
- provide a ``--test-suite`` option, an error will occur.
-
-
-.. _upload:
-
-``upload`` - Upload source and/or egg distributions to PyPI
-===========================================================
-
-The ``upload`` command is implemented and `documented
-<https://docs.python.org/3.1/distutils/uploading.html>`_
-in distutils.
-
-Setuptools augments the ``upload`` command with support
-for `keyring <https://pypi.org/project/keyring/>`_,
-allowing the password to be stored in a secure
-location and not in plaintext in the .pypirc file. To use
-keyring, first install keyring and set the password for
-the relevant repository, e.g.::
-
- python -m keyring set <repository> <username>
- Password for '<username>' in '<repository>': ********
-
-Then, in .pypirc, set the repository configuration as normal,
-but omit the password. Thereafter, uploads will use the
-password from the keyring.
-
-New in 20.1: Added keyring support.
-
-
------------------------------------------
-Configuring setup() using setup.cfg files
------------------------------------------
-
-.. note:: New in 30.3.0 (8 Dec 2016).
-
-.. important::
- A ``setup.py`` file containing a ``setup()`` function call is still
- required even if your configuration resides in ``setup.cfg``.
-
-``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
-to define a package’s metadata and other options that are normally supplied
-to the ``setup()`` function.
-
-This approach not only allows automation scenarios but also reduces
-boilerplate code in some cases.
-
-.. note::
-
- This implementation has limited compatibility with the distutils2-like
- ``setup.cfg`` sections used by the ``pbr`` and ``d2to1`` packages.
-
- Namely: only metadata-related keys from ``metadata`` section are supported
- (except for ``description-file``); keys from ``files``, ``entry_points``
- and ``backwards_compat`` are not supported.
-
-
-.. code-block:: ini
-
- [metadata]
- name = my_package
- version = attr: src.VERSION
- description = My package description
- long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
- keywords = one, two
- license = BSD 3-Clause License
- classifiers =
- Framework :: Django
- Programming Language :: Python :: 3
- Programming Language :: Python :: 3.5
-
- [options]
- zip_safe = False
- include_package_data = True
- packages = find:
- scripts =
- bin/first.py
- bin/second.py
-
- [options.package_data]
- * = *.txt, *.rst
- hello = *.msg
-
- [options.extras_require]
- pdf = ReportLab>=1.2; RXP
- rest = docutils>=0.3; pack ==1.1, ==1.3
-
- [options.packages.find]
- exclude =
- src.subpackage1
- src.subpackage2
-
-
-Metadata and options are set in the config sections of the same name.
-
-* Keys are the same as the keyword arguments one provides to the ``setup()``
- function.
-
-* Complex values can be written comma-separated or placed one per line
- in *dangling* config values. The following are equivalent:
-
- .. code-block:: ini
-
- [metadata]
- keywords = one, two
-
- [metadata]
- keywords =
- one
- two
-
-* In some cases, complex values can be provided in dedicated subsections for
- clarity.
-
-* Some keys allow ``file:``, ``attr:``, and ``find:`` directives in order to
- cover common usecases.
-
-* Unknown keys are ignored.
-
-
-Specifying values
-=================
-
-Some values are treated as simple strings, some allow more logic.
-
-Type names used below:
-
-* ``str`` - simple string
-* ``list-comma`` - dangling list or string of comma-separated values
-* ``list-semi`` - dangling list or string of semicolon-separated values
-* ``bool`` - ``True`` is 1, yes, true
-* ``dict`` - list-comma where keys are separated from values by ``=``
-* ``section`` - values are read from a dedicated (sub)section
-
-
-Special directives:
-
-* ``attr:`` - Value is read from a module attribute. ``attr:`` supports
- callables and iterables; unsupported types are cast using ``str()``.
-* ``file:`` - Value is read from a list of files and then concatenated
-
-
-.. note::
- The ``file:`` directive is sandboxed and won't reach anything outside
- the directory containing ``setup.py``.
-
-
-Metadata
---------
-
-.. note::
- The aliases given below are supported for compatibility reasons,
- but their use is not advised.
-
-============================== ================= =====
-Key Aliases Type
-============================== ================= =====
-name str
-version attr:, str
-url home-page str
-download_url download-url str
-project_urls dict
-author str
-author_email author-email str
-maintainer str
-maintainer_email maintainer-email str
-classifiers classifier file:, list-comma
-license file:, str
-description summary file:, str
-long_description long-description file:, str
-long_description_content_type str
-keywords list-comma
-platforms platform list-comma
-provides list-comma
-requires list-comma
-obsoletes list-comma
-============================== ================= =====
-
-
-Options
--------
-
-======================= =====
-Key Type
-======================= =====
-zip_safe bool
-setup_requires list-semi
-install_requires list-semi
-extras_require section
-python_requires str
-entry_points file:, section
-use_2to3 bool
-use_2to3_fixers list-comma
-use_2to3_exclude_fixers list-comma
-convert_2to3_doctests list-comma
-scripts list-comma
-eager_resources list-comma
-dependency_links list-comma
-tests_require list-semi
-include_package_data bool
-packages find:, list-comma
-package_dir dict
-package_data section
-exclude_package_data section
-namespace_packages list-comma
-py_modules list-comma
-======================= =====
-
-.. note::
-
- **packages** - The ``find:`` directive can be further configured
- in a dedicated subsection ``options.packages.find``. This subsection
- accepts the same keys as the `setuptools.find` function:
- ``where``, ``include``, and ``exclude``.
-
-
-Configuration API
-=================
-
-Some automation tools may wish to access data from a configuration file.
-
-``Setuptools`` exposes a ``read_configuration()`` function for
-parsing ``metadata`` and ``options`` sections into a dictionary.
-
-
-.. code-block:: python
-
- from setuptools.config import read_configuration
-
- conf_dict = read_configuration('/home/user/dev/package/setup.cfg')
-
-
-By default, ``read_configuration()`` will read only the file provided
-in the first argument. To include values from other configuration files
-which could be in various places, set the ``find_others`` keyword argument
-to ``True``.
-
-If you have only a configuration file but not the whole package, you can still
-try to get data out of it with the help of the ``ignore_option_errors`` keyword
-argument. When it is set to ``True``, all options with errors possibly produced
-by directives, such as ``attr:`` and others, will be silently ignored.
-As a consequence, the resulting dictionary will include no such options.
-
-
---------------------------------
-Extending and Reusing Setuptools
---------------------------------
-
-Creating ``distutils`` Extensions
-=================================
-
-It can be hard to add new commands or setup arguments to the distutils. But
-the ``setuptools`` package makes it a bit easier, by allowing you to distribute
-a distutils extension as a separate project, and then have projects that need
-the extension just refer to it in their ``setup_requires`` argument.
-
-With ``setuptools``, your distutils extension projects can hook in new
-commands and ``setup()`` arguments just by defining "entry points". These
-are mappings from command or argument names to a specification of where to
-import a handler from. (See the section on `Dynamic Discovery of Services and
-Plugins`_ above for some more background on entry points.)
-
-
-Adding Commands
----------------
-
-You can add new ``setup`` commands by defining entry points in the
-``distutils.commands`` group. For example, if you wanted to add a ``foo``
-command, you might add something like this to your distutils extension
-project's setup script::
-
- setup(
- # ...
- entry_points={
- "distutils.commands": [
- "foo = mypackage.some_module:foo",
- ],
- },
- )
-
-(Assuming, of course, that the ``foo`` class in ``mypackage.some_module`` is
-a ``setuptools.Command`` subclass.)
-
-Once a project containing such entry points has been activated on ``sys.path``,
-(e.g. by running "install" or "develop" with a site-packages installation
-directory) the command(s) will be available to any ``setuptools``-based setup
-scripts. It is not necessary to use the ``--command-packages`` option or
-to monkeypatch the ``distutils.command`` package to install your commands;
-``setuptools`` automatically adds a wrapper to the distutils to search for
-entry points in the active distributions on ``sys.path``. In fact, this is
-how setuptools' own commands are installed: the setuptools project's setup
-script defines entry points for them!
-
-
-Adding ``setup()`` Arguments
-----------------------------
-
-Sometimes, your commands may need additional arguments to the ``setup()``
-call. You can enable this by defining entry points in the
-``distutils.setup_keywords`` group. For example, if you wanted a ``setup()``
-argument called ``bar_baz``, you might add something like this to your
-distutils extension project's setup script::
-
- setup(
- # ...
- entry_points={
- "distutils.commands": [
- "foo = mypackage.some_module:foo",
- ],
- "distutils.setup_keywords": [
- "bar_baz = mypackage.some_module:validate_bar_baz",
- ],
- },
- )
-
-The idea here is that the entry point defines a function that will be called
-to validate the ``setup()`` argument, if it's supplied. The ``Distribution``
-object will have the initial value of the attribute set to ``None``, and the
-validation function will only be called if the ``setup()`` call sets it to
-a non-None value. Here's an example validation function::
-
- def assert_bool(dist, attr, value):
- """Verify that value is True, False, 0, or 1"""
- if bool(value) != value:
- raise DistutilsSetupError(
- "%r must be a boolean value (got %r)" % (attr,value)
- )
-
-Your function should accept three arguments: the ``Distribution`` object,
-the attribute name, and the attribute value. It should raise a
-``DistutilsSetupError`` (from the ``distutils.errors`` module) if the argument
-is invalid. Remember, your function will only be called with non-None values,
-and the default value of arguments defined this way is always None. So, your
-commands should always be prepared for the possibility that the attribute will
-be ``None`` when they access it later.
-
-If more than one active distribution defines an entry point for the same
-``setup()`` argument, *all* of them will be called. This allows multiple
-distutils extensions to define a common argument, as long as they agree on
-what values of that argument are valid.
-
-Also note that as with commands, it is not necessary to subclass or monkeypatch
-the distutils ``Distribution`` class in order to add your arguments; it is
-sufficient to define the entry points in your extension, as long as any setup
-script using your extension lists your project in its ``setup_requires``
-argument.
-
-
-Adding new EGG-INFO Files
--------------------------
-
-Some extensible applications or frameworks may want to allow third parties to
-develop plugins with application or framework-specific metadata included in
-the plugins' EGG-INFO directory, for easy access via the ``pkg_resources``
-metadata API. The easiest way to allow this is to create a distutils extension
-to be used from the plugin projects' setup scripts (via ``setup_requires``)
-that defines a new setup keyword, and then uses that data to write an EGG-INFO
-file when the ``egg_info`` command is run.
-
-The ``egg_info`` command looks for extension points in an ``egg_info.writers``
-group, and calls them to write the files. Here's a simple example of a
-distutils extension defining a setup argument ``foo_bar``, which is a list of
-lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any
-project that uses the argument::
-
- setup(
- # ...
- entry_points={
- "distutils.setup_keywords": [
- "foo_bar = setuptools.dist:assert_string_list",
- ],
- "egg_info.writers": [
- "foo_bar.txt = setuptools.command.egg_info:write_arg",
- ],
- },
- )
-
-This simple example makes use of two utility functions defined by setuptools
-for its own use: a routine to validate that a setup keyword is a sequence of
-strings, and another one that looks up a setup argument and writes it to
-a file. Here's what the writer utility looks like::
-
- def write_arg(cmd, basename, filename):
- argname = os.path.splitext(basename)[0]
- value = getattr(cmd.distribution, argname, None)
- if value is not None:
- value = '\n'.join(value) + '\n'
- cmd.write_or_delete_file(argname, filename, value)
-
-As you can see, ``egg_info.writers`` entry points must be a function taking
-three arguments: a ``egg_info`` command instance, the basename of the file to
-write (e.g. ``foo_bar.txt``), and the actual full filename that should be
-written to.
-
-In general, writer functions should honor the command object's ``dry_run``
-setting when writing files, and use the ``distutils.log`` object to do any
-console output. The easiest way to conform to this requirement is to use
-the ``cmd`` object's ``write_file()``, ``delete_file()``, and
-``write_or_delete_file()`` methods exclusively for your file operations. See
-those methods' docstrings for more details.
-
-
-Adding Support for Revision Control Systems
--------------------------------------------------
-
-If the files you want to include in the source distribution are tracked using
-Git, Mercurial or SVN, you can use the following packages to achieve that:
-
-- Git and Mercurial: `setuptools_scm <https://pypi.org/project/setuptools_scm/>`_
-- SVN: `setuptools_svn <https://pypi.org/project/setuptools_svn/>`_
-
-If you would like to create a plugin for ``setuptools`` to find files tracked
-by another revision control system, you can do so by adding an entry point to
-the ``setuptools.file_finders`` group. The entry point should be a function
-accepting a single directory name, and should yield all the filenames within
-that directory (and any subdirectories thereof) that are under revision
-control.
-
-For example, if you were going to create a plugin for a revision control system
-called "foobar", you would write a function something like this:
-
-.. code-block:: python
-
- def find_files_for_foobar(dirname):
- # loop to yield paths that start with `dirname`
-
-And you would register it in a setup script using something like this::
-
- entry_points={
- "setuptools.file_finders": [
- "foobar = my_foobar_module:find_files_for_foobar",
- ]
- }
-
-Then, anyone who wants to use your plugin can simply install it, and their
-local setuptools installation will be able to find the necessary files.
-
-It is not necessary to distribute source control plugins with projects that
-simply use the other source control system, or to specify the plugins in
-``setup_requires``. When you create a source distribution with the ``sdist``
-command, setuptools automatically records what files were found in the
-``SOURCES.txt`` file. That way, recipients of source distributions don't need
-to have revision control at all. However, if someone is working on a package
-by checking out with that system, they will need the same plugin(s) that the
-original author is using.
-
-A few important points for writing revision control file finders:
-
-* Your finder function MUST return relative paths, created by appending to the
- passed-in directory name. Absolute paths are NOT allowed, nor are relative
- paths that reference a parent directory of the passed-in directory.
-
-* Your finder function MUST accept an empty string as the directory name,
- meaning the current directory. You MUST NOT convert this to a dot; just
- yield relative paths. So, yielding a subdirectory named ``some/dir`` under
- the current directory should NOT be rendered as ``./some/dir`` or
- ``/somewhere/some/dir``, but *always* as simply ``some/dir``
-
-* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
- with the absence of needed programs (i.e., ones belonging to the revision
- control system itself. It *may*, however, use ``distutils.log.warn()`` to
- inform the user of the missing program(s).
-
-
-Subclassing ``Command``
------------------------
-
-Sorry, this section isn't written yet, and neither is a lot of what's below
-this point.
-
-XXX
-
-
-Reusing ``setuptools`` Code
-===========================
-
-``ez_setup``
-------------
-
-XXX
-
-
-``setuptools.archive_util``
----------------------------
-
-XXX
-
-
-``setuptools.sandbox``
-----------------------
-
-XXX
-
-
-``setuptools.package_index``
-----------------------------
-
-XXX
-
-
-Mailing List and Bug Tracker
-============================
-
-Please use the `distutils-sig mailing list`_ for questions and discussion about
-setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
-confirmed via the list are actual bugs, and which you have reduced to a minimal
-set of steps to reproduce.
-
-.. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
-.. _setuptools bug tracker: https://github.com/pypa/setuptools/
diff --git a/docs/userguide/commands.rst b/docs/userguide/commands.rst
new file mode 100644
index 0000000..e632e55
--- /dev/null
+++ b/docs/userguide/commands.rst
@@ -0,0 +1,566 @@
+-----------------
+Command Reference
+-----------------
+
+.. _alias:
+
+``alias`` - Define shortcuts for commonly used commands
+=======================================================
+
+Sometimes, you need to use the same commands over and over, but you can't
+necessarily set them as defaults. For example, if you produce both development
+snapshot releases and "stable" releases of a project, you may want to put
+the distributions in different places, or use different ``egg_info`` tagging
+options, etc. In these cases, it doesn't make sense to set the options in
+a distutils configuration file, because the values of the options changed based
+on what you're trying to do.
+
+Setuptools therefore allows you to define "aliases" - shortcut names for
+an arbitrary string of commands and options, using ``setup.py alias aliasname
+expansion``, where aliasname is the name of the new alias, and the remainder of
+the command line supplies its expansion. For example, this command defines
+a sitewide alias called "daily", that sets various ``egg_info`` tagging
+options::
+
+ setup.py alias --global-config daily egg_info --tag-build=development
+
+Once the alias is defined, it can then be used with other setup commands,
+e.g.::
+
+ setup.py daily bdist_egg # generate a daily-build .egg file
+ setup.py daily sdist # generate a daily-build source distro
+ setup.py daily sdist bdist_egg # generate both
+
+The above commands are interpreted as if the word ``daily`` were replaced with
+``egg_info --tag-build=development``.
+
+Note that setuptools will expand each alias *at most once* in a given command
+line. This serves two purposes. First, if you accidentally create an alias
+loop, it will have no effect; you'll instead get an error message about an
+unknown command. Second, it allows you to define an alias for a command, that
+uses that command. For example, this (project-local) alias::
+
+ setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
+
+redefines the ``bdist_egg`` command so that it always runs the ``rotate``
+command afterwards to delete all but the newest egg file. It doesn't loop
+indefinitely on ``bdist_egg`` because the alias is only expanded once when
+used.
+
+You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
+
+ setup.py alias --global-config --remove daily
+
+would delete the "daily" alias we defined above.
+
+Aliases can be defined on a project-specific, per-user, or sitewide basis. The
+default is to define or remove a project-specific alias, but you can use any of
+the `configuration file options`_ (listed under the `saveopts`_ command, below)
+to determine which distutils configuration file an aliases will be added to
+(or removed from).
+
+Note that if you omit the "expansion" argument to the ``alias`` command,
+you'll get output showing that alias' current definition (and what
+configuration file it's defined in). If you omit the alias name as well,
+you'll get a listing of all current aliases along with their configuration
+file locations.
+
+
+``bdist_egg`` - Create a Python Egg for the project
+===================================================
+
+.. warning::
+ **eggs** are deprecated in favor of wheels, and not supported by pip.
+
+This command generates a Python Egg (``.egg`` file) for the project. Python
+Eggs are the preferred binary distribution format for EasyInstall, because they
+are cross-platform (for "pure" packages), directly importable, and contain
+project metadata including scripts and information about the project's
+dependencies. They can be simply downloaded and added to ``sys.path``
+directly, or they can be placed in a directory on ``sys.path`` and then
+automatically discovered by the egg runtime system.
+
+This command runs the `egg_info`_ command (if it hasn't already run) to update
+the project's metadata (``.egg-info``) directory. If you have added any extra
+metadata files to the ``.egg-info`` directory, those files will be included in
+the new egg file's metadata directory, for use by the egg runtime system or by
+any applications or frameworks that use that metadata.
+
+You won't usually need to specify any special options for this command; just
+use ``bdist_egg`` and you're done. But there are a few options that may
+be occasionally useful:
+
+``--dist-dir=DIR, -d DIR``
+ Set the directory where the ``.egg`` file will be placed. If you don't
+ supply this, then the ``--dist-dir`` setting of the ``bdist`` command
+ will be used, which is usually a directory named ``dist`` in the project
+ directory.
+
+``--plat-name=PLATFORM, -p PLATFORM``
+ Set the platform name string that will be embedded in the egg's filename
+ (assuming the egg contains C extensions). This can be used to override
+ the distutils default platform name with something more meaningful. Keep
+ in mind, however, that the egg runtime system expects to see eggs with
+ distutils platform names, so it may ignore or reject eggs with non-standard
+ platform names. Similarly, the EasyInstall program may ignore them when
+ searching web pages for download links. However, if you are
+ cross-compiling or doing some other unusual things, you might find a use
+ for this option.
+
+``--exclude-source-files``
+ Don't include any modules' ``.py`` files in the egg, just compiled Python,
+ C, and data files. (Note that this doesn't affect any ``.py`` files in the
+ EGG-INFO directory or its subdirectories, since for example there may be
+ scripts with a ``.py`` extension which must still be retained.) We don't
+ recommend that you use this option except for packages that are being
+ bundled for proprietary end-user applications, or for "embedded" scenarios
+ where space is at an absolute premium. On the other hand, if your package
+ is going to be installed and used in compressed form, you might as well
+ exclude the source because Python's ``traceback`` module doesn't currently
+ understand how to display zipped source code anyway, or how to deal with
+ files that are in a different place from where their code was compiled.
+
+There are also some options you will probably never need, but which are there
+because they were copied from similar ``bdist`` commands used as an example for
+creating this one. They may be useful for testing and debugging, however,
+which is why we kept them:
+
+``--keep-temp, -k``
+ Keep the contents of the ``--bdist-dir`` tree around after creating the
+ ``.egg`` file.
+
+``--bdist-dir=DIR, -b DIR``
+ Set the temporary directory for creating the distribution. The entire
+ contents of this directory are zipped to create the ``.egg`` file, after
+ running various installation commands to copy the package's modules, data,
+ and extensions here.
+
+``--skip-build``
+ Skip doing any "build" commands; just go straight to the
+ install-and-compress phases.
+
+
+.. _develop:
+
+``develop`` - Deploy the project source in "Development Mode"
+=============================================================
+
+This command allows you to deploy your project's source for use in one or more
+"staging areas" where it will be available for importing. This deployment is
+done in such a way that changes to the project source are immediately available
+in the staging area(s), without needing to run a build or install step after
+each change.
+
+The ``develop`` command works by creating an ``.egg-link`` file (named for the
+project) in the given staging area. If the staging area is Python's
+``site-packages`` directory, it also updates an ``easy-install.pth`` file so
+that the project is on ``sys.path`` by default for all programs run using that
+Python installation.
+
+The ``develop`` command also installs wrapper scripts in the staging area (or
+a separate directory, as specified) that will ensure the project's dependencies
+are available on ``sys.path`` before running the project's source scripts.
+And, it ensures that any missing project dependencies are available in the
+staging area, by downloading and installing them if necessary.
+
+Last, but not least, the ``develop`` command invokes the ``build_ext -i``
+command to ensure any C extensions in the project have been built and are
+up-to-date, and the ``egg_info`` command to ensure the project's metadata is
+updated (so that the runtime and wrappers know what the project's dependencies
+are). If you make any changes to the project's setup script or C extensions,
+you should rerun the ``develop`` command against all relevant staging areas to
+keep the project's scripts, metadata and extensions up-to-date. Most other
+kinds of changes to your project should not require any build operations or
+rerunning ``develop``, but keep in mind that even minor changes to the setup
+script (e.g. changing an entry point definition) require you to re-run the
+``develop`` or ``test`` commands to keep the distribution updated.
+
+Here are some of the options that the ``develop`` command accepts. Note that
+they affect the project's dependencies as well as the project itself, so if you
+have dependencies that need to be installed and you use ``--exclude-scripts``
+(for example), the dependencies' scripts will not be installed either! For
+this reason, you may want to use pip to install the project's dependencies
+before using the ``develop`` command, if you need finer control over the
+installation options for dependencies.
+
+``--uninstall, -u``
+ Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
+ option to designate the staging area. The created ``.egg-link`` file will
+ be removed, if present and it is still pointing to the project directory.
+ The project directory will be removed from ``easy-install.pth`` if the
+ staging area is Python's ``site-packages`` directory.
+
+ Note that this option currently does *not* uninstall script wrappers! You
+ must uninstall them yourself, or overwrite them by using pip to install a
+ different version of the package. You can also avoid installing script
+ wrappers in the first place, if you use the ``--exclude-scripts`` (aka
+ ``-x``) option when you run ``develop`` to deploy the project.
+
+``--multi-version, -m``
+ "Multi-version" mode. Specifying this option prevents ``develop`` from
+ adding an ``easy-install.pth`` entry for the project(s) being deployed, and
+ if an entry for any version of a project already exists, the entry will be
+ removed upon successful deployment. In multi-version mode, no specific
+ version of the package is available for importing, unless you use
+ ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
+ a wrapper script generated by ``setuptools``. (In which case the wrapper
+ script calls ``require()`` for you.)
+
+ Note that if you install to a directory other than ``site-packages``,
+ this option is automatically in effect, because ``.pth`` files can only be
+ used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
+ the ``--install-dir`` or ``-d`` option (or they are set via configuration
+ file(s)) your project and its dependencies will be deployed in multi-
+ version mode.
+
+``--install-dir=DIR, -d DIR``
+ Set the installation directory (staging area). If this option is not
+ directly specified on the command line or in a distutils configuration
+ file, the distutils default installation location is used. Normally, this
+ will be the ``site-packages`` directory, but if you are using distutils
+ configuration files, setting things like ``prefix`` or ``install_lib``,
+ then those settings are taken into account when computing the default
+ staging area.
+
+``--script-dir=DIR, -s DIR``
+ Set the script installation directory. If you don't supply this option
+ (via the command line or a configuration file), but you *have* supplied
+ an ``--install-dir`` (via command line or config file), then this option
+ defaults to the same directory, so that the scripts will be able to find
+ their associated package installation. Otherwise, this setting defaults
+ to the location where the distutils would normally install scripts, taking
+ any distutils configuration file settings into account.
+
+``--exclude-scripts, -x``
+ Don't deploy script wrappers. This is useful if you don't want to disturb
+ existing versions of the scripts in the staging area.
+
+``--always-copy, -a``
+ Copy all needed distributions to the staging area, even if they
+ are already present in another directory on ``sys.path``. By default, if
+ a requirement can be met using a distribution that is already available in
+ a directory on ``sys.path``, it will not be copied to the staging area.
+
+``--egg-path=DIR``
+ Force the generated ``.egg-link`` file to use a specified relative path
+ to the source directory. This can be useful in circumstances where your
+ installation directory is being shared by code running under multiple
+ platforms (e.g. Mac and Windows) which have different absolute locations
+ for the code under development, but the same *relative* locations with
+ respect to the installation directory. If you use this option when
+ installing, you must supply the same relative path when uninstalling.
+
+In addition to the above options, the ``develop`` command also accepts all of
+the same options accepted by ``easy_install``. If you've configured any
+``easy_install`` settings in your ``setup.cfg`` (or other distutils config
+files), the ``develop`` command will use them as defaults, unless you override
+them in a ``[develop]`` section or on the command line.
+
+
+.. _egg_info:
+
+``egg_info`` - Create egg metadata and set build tags
+=====================================================
+
+This command performs two operations: it updates a project's ``.egg-info``
+metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
+commands), and it allows you to temporarily change a project's version string,
+to support "daily builds" or "snapshot" releases. It is run automatically by
+the ``sdist``, ``bdist_egg``, ``develop``, and ``test`` commands in order to
+update the project's metadata, but you can also specify it explicitly in order
+to temporarily change the project's version string while executing other
+commands. (It also generates the ``.egg-info/SOURCES.txt`` manifest file, which
+is used when you are building source distributions.)
+
+In addition to writing the core egg metadata defined by ``setuptools`` and
+required by ``pkg_resources``, this command can be extended to write other
+metadata files as well, by defining entry points in the ``egg_info.writers``
+group. See the section on :ref:`Adding new EGG-INFO Files` below for more details.
+Note that using additional metadata writers may require you to include a
+``setup_requires`` argument to ``setup()`` in order to ensure that the desired
+writers are available on ``sys.path``.
+
+
+Release Tagging Options
+-----------------------
+
+The following options can be used to modify the project's version string for
+all remaining commands on the setup command line. The options are processed
+in the order shown, so if you use more than one, the requested tags will be
+added in the following order:
+
+``--tag-build=NAME, -b NAME``
+ Append NAME to the project's version string. Due to the way setuptools
+ processes "pre-release" version suffixes beginning with the letters "a"
+ through "e" (like "alpha", "beta", and "candidate"), you will usually want
+ to use a tag like ".build" or ".dev", as this will cause the version number
+ to be considered *lower* than the project's default version. (If you
+ want to make the version number *higher* than the default version, you can
+ always leave off --tag-build and then use one or both of the following
+ options.)
+
+ If you have a default build tag set in your ``setup.cfg``, you can suppress
+ it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
+ to the ``egg_info`` command.
+
+``--tag-date, -d``
+ Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
+ project's version number.
+
+``--no-date, -D``
+ Don't include a date stamp in the version number. This option is included
+ so you can override a default setting in ``setup.cfg``.
+
+
+(Note: Because these options modify the version number used for source and
+binary distributions of your project, you should first make sure that you know
+how the resulting version numbers will be interpreted by automated tools
+like pip. See the section above on :ref:`Specifying Your Project's Version` for an
+explanation of pre- and post-release tags, as well as tips on how to choose and
+verify a versioning scheme for your project.)
+
+For advanced uses, there is one other option that can be set, to change the
+location of the project's ``.egg-info`` directory. Commands that need to find
+the project's source directory or metadata should get it from this setting:
+
+
+Other ``egg_info`` Options
+--------------------------
+
+``--egg-base=SOURCEDIR, -e SOURCEDIR``
+ Specify the directory that should contain the .egg-info directory. This
+ should normally be the root of your project's source tree (which is not
+ necessarily the same as your project directory; some projects use a ``src``
+ or ``lib`` subdirectory as the source root). You should not normally need
+ to specify this directory, as it is normally determined from the
+ ``package_dir`` argument to the ``setup()`` function, if any. If there is
+ no ``package_dir`` set, this option defaults to the current directory.
+
+
+``egg_info`` Examples
+---------------------
+
+Creating a dated "nightly build" snapshot egg::
+
+ setup.py egg_info --tag-date --tag-build=DEV bdist_egg
+
+Creating a release with no version tags, even if some default tags are
+specified in ``setup.cfg``::
+
+ setup.py egg_info -RDb "" sdist bdist_egg
+
+(Notice that ``egg_info`` must always appear on the command line *before* any
+commands that you want the version changes to apply to.)
+
+.. _rotate:
+
+``rotate`` - Delete outdated distribution files
+===============================================
+
+As you develop new versions of your project, your distribution (``dist``)
+directory will gradually fill up with older source and/or binary distribution
+files. The ``rotate`` command lets you automatically clean these up, keeping
+only the N most-recently modified files matching a given pattern.
+
+``--match=PATTERNLIST, -m PATTERNLIST``
+ Comma-separated list of glob patterns to match. This option is *required*.
+ The project name and ``-*`` is prepended to the supplied patterns, in order
+ to match only distributions belonging to the current project (in case you
+ have a shared distribution directory for multiple projects). Typically,
+ you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
+ the specified type. Note that each supplied pattern is treated as a
+ distinct group of files for purposes of selecting files to delete.
+
+``--keep=COUNT, -k COUNT``
+ Number of matching distributions to keep. For each group of files
+ identified by a pattern specified with the ``--match`` option, delete all
+ but the COUNT most-recently-modified files in that group. This option is
+ *required*.
+
+``--dist-dir=DIR, -d DIR``
+ Directory where the distributions are. This defaults to the value of the
+ ``bdist`` command's ``--dist-dir`` option, which will usually be the
+ project's ``dist`` subdirectory.
+
+**Example 1**: Delete all .tar.gz files from the distribution directory, except
+for the 3 most recently modified ones::
+
+ setup.py rotate --match=.tar.gz --keep=3
+
+**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
+directory, except the most recently modified one for each Python version::
+
+ setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
+
+
+.. _saveopts:
+
+``saveopts`` - Save used options to a configuration file
+========================================================
+
+Finding and editing ``distutils`` configuration files can be a pain, especially
+since you also have to translate the configuration options from command-line
+form to the proper configuration file format. You can avoid these hassles by
+using the ``saveopts`` command. Just add it to the command line to save the
+options you used. For example, this command builds the project using
+the ``mingw32`` C compiler, then saves the --compiler setting as the default
+for future builds (even those run implicitly by the ``install`` command)::
+
+ setup.py build --compiler=mingw32 saveopts
+
+The ``saveopts`` command saves all options for every command specified on the
+command line to the project's local ``setup.cfg`` file, unless you use one of
+the `configuration file options`_ to change where the options are saved. For
+example, this command does the same as above, but saves the compiler setting
+to the site-wide (global) distutils configuration::
+
+ setup.py build --compiler=mingw32 saveopts -g
+
+Note that it doesn't matter where you place the ``saveopts`` command on the
+command line; it will still save all the options specified for all commands.
+For example, this is another valid way to spell the last example::
+
+ setup.py saveopts -g build --compiler=mingw32
+
+Note, however, that all of the commands specified are always run, regardless of
+where ``saveopts`` is placed on the command line.
+
+
+Configuration File Options
+--------------------------
+
+Normally, settings such as options and aliases are saved to the project's
+local ``setup.cfg`` file. But you can override this and save them to the
+global or per-user configuration files, or to a manually-specified filename.
+
+``--global-config, -g``
+ Save settings to the global ``distutils.cfg`` file inside the ``distutils``
+ package directory. You must have write access to that directory to use
+ this option. You also can't combine this option with ``-u`` or ``-f``.
+
+``--user-config, -u``
+ Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
+ ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option
+ with ``-g`` or ``-f``.
+
+``--filename=FILENAME, -f FILENAME``
+ Save settings to the specified configuration file to use. You can't
+ combine this option with ``-g`` or ``-u``. Note that if you specify a
+ non-standard filename, the ``distutils`` and ``setuptools`` will not
+ use the file's contents. This option is mainly included for use in
+ testing.
+
+These options are used by other ``setuptools`` commands that modify
+configuration files, such as the `alias`_ and `setopt`_ commands.
+
+
+.. _setopt:
+
+``setopt`` - Set a distutils or setuptools option in a config file
+==================================================================
+
+This command is mainly for use by scripts, but it can also be used as a quick
+and dirty way to change a distutils configuration option without having to
+remember what file the options are in and then open an editor.
+
+**Example 1**. Set the default C compiler to ``mingw32`` (using long option
+names)::
+
+ setup.py setopt --command=build --option=compiler --set-value=mingw32
+
+**Example 2**. Remove any setting for the distutils default package
+installation directory (short option names)::
+
+ setup.py setopt -c install -o install_lib -r
+
+
+Options for the ``setopt`` command:
+
+``--command=COMMAND, -c COMMAND``
+ Command to set the option for. This option is required.
+
+``--option=OPTION, -o OPTION``
+ The name of the option to set. This option is required.
+
+``--set-value=VALUE, -s VALUE``
+ The value to set the option to. Not needed if ``-r`` or ``--remove`` is
+ set.
+
+``--remove, -r``
+ Remove (unset) the option, instead of setting it.
+
+In addition to the above options, you may use any of the `configuration file
+options`_ (listed under the `saveopts`_ command, above) to determine which
+distutils configuration file the option will be added to (or removed from).
+
+
+.. _test:
+
+``test`` - Build package and run a unittest suite
+=================================================
+
+.. warning::
+ ``test`` is deprecated and will be removed in a future version. Users
+ looking for a generic test entry point independent of test runner are
+ encouraged to use `tox <https://tox.readthedocs.io>`_.
+
+When doing test-driven development, or running automated builds that need
+testing before they are deployed for downloading or use, it's often useful
+to be able to run a project's unit tests without actually deploying the project
+anywhere, even using the ``develop`` command. The ``test`` command runs a
+project's unit tests without actually deploying it, by temporarily putting the
+project's source on ``sys.path``, after first running ``build_ext -i`` and
+``egg_info`` to ensure that any C extensions and project metadata are
+up-to-date.
+
+To use this command, your project's tests must be wrapped in a ``unittest``
+test suite by either a function, a ``TestCase`` class or method, or a module
+or package containing ``TestCase`` classes. If the named suite is a module,
+and the module has an ``additional_tests()`` function, it is called and the
+result (which must be a ``unittest.TestSuite``) is added to the tests to be
+run. If the named suite is a package, any submodules and subpackages are
+recursively added to the overall test suite. (Note: if your project specifies
+a ``test_loader``, the rules for processing the chosen ``test_suite`` may
+differ; see the :ref:`test_loader <test_loader>` documentation for more details.)
+
+Note that many test systems including ``doctest`` support wrapping their
+non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
+package that does not support this, we suggest you encourage its developers to
+implement test suite support, as this is a convenient and standard way to
+aggregate a collection of tests to be run under a common test harness.
+
+By default, tests will be run in the "verbose" mode of the ``unittest``
+package's text test runner, but you can get the "quiet" mode (just dots) if
+you supply the ``-q`` or ``--quiet`` option, either as a global option to
+the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
+command itself (e.g. ``setup.py test -q``). There is one other option
+available:
+
+``--test-suite=NAME, -s NAME``
+ Specify the test suite (or module, class, or method) to be run
+ (e.g. ``some_module.test_suite``). The default for this option can be
+ set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
+
+ setup(
+ # ...
+ test_suite="my_package.tests.test_all"
+ )
+
+ If you did not set a ``test_suite`` in your ``setup()`` call, and do not
+ provide a ``--test-suite`` option, an error will occur.
+
+New in 41.5.0: Deprecated the test command.
+
+
+.. _upload:
+
+``upload`` - Upload source and/or egg distributions to PyPI
+===========================================================
+
+The ``upload`` command was deprecated in version 40.0 and removed in version
+42.0. Use `twine <https://pypi.org/p/twine>`_ instead.
+
+For more information on the current best practices in uploading your packages
+to PyPI, see the Python Packaging User Guide's "Packaging Python Projects"
+tutorial specifically the section on `uploading the distribution archives
+<https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives>`_.
diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst
new file mode 100644
index 0000000..9817e63
--- /dev/null
+++ b/docs/userguide/datafiles.rst
@@ -0,0 +1,206 @@
+====================
+Data Files Support
+====================
+
+The distutils have traditionally allowed installation of "data files", which
+are placed in a platform-specific location. However, the most common use case
+for data files distributed with a package is for use *by* the package, usually
+by including the data files **inside the package directory**.
+
+Setuptools offers three ways to specify this most common type of data files to
+be included in your package's [#datafiles]_.
+First, you can simply use the ``include_package_data`` keyword, e.g.::
+
+ from setuptools import setup, find_packages
+ setup(
+ ...
+ include_package_data=True
+ )
+
+This tells setuptools to install any data files it finds in your packages.
+The data files must be specified via the |MANIFEST.in|_ file.
+(They can also be tracked by a revision control system, using an appropriate
+plugin such as :pypi:`setuptools-scm` or :pypi:`setuptools-svn`.
+See the section below on :ref:`Adding Support for Revision
+Control Systems` for information on how to write such plugins.)
+
+If you want finer-grained control over what files are included (for example,
+if you have documentation files in your package directories and want to exclude
+them from installation), then you can also use the ``package_data`` keyword,
+e.g.::
+
+ from setuptools import setup, find_packages
+ setup(
+ ...
+ package_data={
+ # If any package contains *.txt or *.rst files, include them:
+ "": ["*.txt", "*.rst"],
+ # And include any *.msg files found in the "hello" package, too:
+ "hello": ["*.msg"],
+ }
+ )
+
+The ``package_data`` argument is a dictionary that maps from package names to
+lists of glob patterns. The globs may include subdirectory names, if the data
+files are contained in a subdirectory of the package. For example, if the
+package tree looks like this::
+
+ setup.py
+ src/
+ mypkg/
+ __init__.py
+ mypkg.txt
+ data/
+ somefile.dat
+ otherdata.dat
+
+The setuptools setup file might look like this::
+
+ from setuptools import setup, find_packages
+ setup(
+ ...
+ packages=find_packages("src"), # include all packages under src
+ package_dir={"": "src"}, # tell distutils packages are under src
+
+ package_data={
+ # If any package contains *.txt files, include them:
+ "": ["*.txt"],
+ # And include any *.dat files found in the "data" subdirectory
+ # of the "mypkg" package, also:
+ "mypkg": ["data/*.dat"],
+ }
+ )
+
+Notice that if you list patterns in ``package_data`` under the empty string,
+these patterns are used to find files in every package, even ones that also
+have their own patterns listed. Thus, in the above example, the ``mypkg.txt``
+file gets included even though it's not listed in the patterns for ``mypkg``.
+
+Also notice that if you use paths, you *must* use a forward slash (``/``) as
+the path separator, even if you are on Windows. Setuptools automatically
+converts slashes to appropriate platform-specific separators at build time.
+
+If datafiles are contained in a subdirectory of a package that isn't a package
+itself (no ``__init__.py``), then the subdirectory names (or ``*``) are required
+in the ``package_data`` argument (as shown above with ``"data/*.dat"``).
+
+When building an ``sdist``, the datafiles are also drawn from the
+``package_name.egg-info/SOURCES.txt`` file, so make sure that this is removed if
+the ``setup.py`` ``package_data`` list is updated before calling ``setup.py``.
+
+.. note::
+ If using the ``include_package_data`` argument, files specified by
+ ``package_data`` will *not* be automatically added to the manifest unless
+ they are listed in the |MANIFEST.in|_ file or by a plugin like
+ :pypi:`setuptools-scm` or :pypi:`setuptools-svn`.
+
+.. https://docs.python.org/3/distutils/setupscript.html#installing-package-data
+
+Sometimes, the ``include_package_data`` or ``package_data`` options alone
+aren't sufficient to precisely define what files you want included. For
+example, you may want to include package README files in your revision control
+system and source distributions, but exclude them from being installed. So,
+setuptools offers an ``exclude_package_data`` option as well, that allows you
+to do things like this::
+
+ from setuptools import setup, find_packages
+ setup(
+ ...
+ packages=find_packages("src"), # include all packages under src
+ package_dir={"": "src"}, # tell distutils packages are under src
+
+ include_package_data=True, # include everything in source control
+
+ # ...but exclude README.txt from all packages
+ exclude_package_data={"": ["README.txt"]},
+ )
+
+The ``exclude_package_data`` option is a dictionary mapping package names to
+lists of wildcard patterns, just like the ``package_data`` option. And, just
+as with that option, a key of ``""`` will apply the given pattern(s) to all
+packages. However, any files that match these patterns will be *excluded*
+from installation, even if they were listed in ``package_data`` or were
+included as a result of using ``include_package_data``.
+
+In summary, the three options allow you to:
+
+``include_package_data``
+ Accept all data files and directories matched by |MANIFEST.in|_ or added by
+ a :ref:`plugin <Adding Support for Revision Control Systems>`.
+
+``package_data``
+ Specify additional patterns to match files that may or may
+ not be matched by |MANIFEST.in|_ or added by
+ a :ref:`plugin <Adding Support for Revision Control Systems>`.
+
+``exclude_package_data``
+ Specify patterns for data files and directories that should *not* be
+ included when a package is installed, even if they would otherwise have
+ been included due to the use of the preceding options.
+
+NOTE: Due to the way the distutils build process works, a data file that you
+include in your project and then stop including may be "orphaned" in your
+project's build directories, requiring you to run ``setup.py clean --all`` to
+fully remove them. This may also be important for your users and contributors
+if they track intermediate revisions of your project using Subversion; be sure
+to let them know when you make changes that remove files from inclusion so they
+can run ``setup.py clean --all``.
+
+
+.. _Accessing Data Files at Runtime:
+
+Accessing Data Files at Runtime
+-------------------------------
+
+Typically, existing programs manipulate a package's ``__file__`` attribute in
+order to find the location of data files. However, this manipulation isn't
+compatible with PEP 302-based import hooks, including importing from zip files
+and Python Eggs. It is strongly recommended that, if you are using data files,
+you should use :mod:`importlib.resources` to access them.
+:mod:`importlib.resources` was added to Python 3.7 and the latest version of
+the library is also available via the :pypi:`importlib-resources` backport.
+See :doc:`importlib-resources:using` for detailed instructions [#importlib]_.
+
+.. tip:: Files inside the package directory should be *read-only* to avoid a
+ series of common problems (e.g. when multiple users share a common Python
+ installation, when the package is loaded from a zip file, or when multiple
+ instances of a Python application run in parallel).
+
+ If your Python package needs to write to a file for shared data or configuration,
+ you can use standard platform/OS-specific system directories, such as
+ ``~/.local/config/$appname`` or ``/usr/share/$appname/$version`` (Linux specific) [#system-dirs]_.
+ A common approach is to add a read-only template file to the package
+ directory that is then copied to the correct system directory if no
+ pre-existing file is found.
+
+
+Non-Package Data Files
+----------------------
+
+Historically, ``setuptools`` by way of ``easy_install`` would encapsulate data
+files from the distribution into the egg (see `the old docs
+<https://github.com/pypa/setuptools/blob/52aacd5b276fedd6849c3a648a0014f5da563e93/docs/setuptools.txt#L970-L1001>`_). As eggs are deprecated and pip-based installs
+fall back to the platform-specific location for installing data files, there is
+no supported facility to reliably retrieve these resources.
+
+Instead, the PyPA recommends that any data files you wish to be accessible at
+run time be included **inside the package**.
+
+
+----
+
+.. [#datafiles] ``setuptools`` consider a *package data file* any non-Python
+ file **inside the package directory** (i.e., that co-exists in the same
+ location as the regular ``.py`` files being distributed).
+
+.. [#system-dirs] These locations can be discovered with the help of
+ third-party libraries such as :pypi:`platformdirs`.
+
+.. [#importlib] Recent versions of :mod:`importlib.resources` available in
+ Pythons' standard library should be API compatible with
+ :pypi:`importlib-metadata`. However this might vary depending on which version
+ of Python is installed.
+
+
+.. |MANIFEST.in| replace:: ``MANIFEST.in``
+.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst
new file mode 100644
index 0000000..52379db
--- /dev/null
+++ b/docs/userguide/declarative_config.rst
@@ -0,0 +1,282 @@
+.. _declarative config:
+
+------------------------------------------------
+Configuring setuptools using ``setup.cfg`` files
+------------------------------------------------
+
+.. note:: New in 30.3.0 (8 Dec 2016).
+
+.. important::
+ If compatibility with legacy builds (i.e. those not using the :pep:`517`
+ build API) is desired, a ``setup.py`` file containing a ``setup()`` function
+ call is still required even if your configuration resides in ``setup.cfg``.
+
+``Setuptools`` allows using configuration files (usually :file:`setup.cfg`)
+to define a package’s metadata and other options that are normally supplied
+to the ``setup()`` function (declarative config).
+
+This approach not only allows automation scenarios but also reduces
+boilerplate code in some cases.
+
+.. _example-setup-config:
+
+.. code-block:: ini
+
+ [metadata]
+ name = my_package
+ version = attr: my_package.VERSION
+ description = My package description
+ long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
+ keywords = one, two
+ license = BSD 3-Clause License
+ classifiers =
+ Framework :: Django
+ Programming Language :: Python :: 3
+
+ [options]
+ zip_safe = False
+ include_package_data = True
+ packages = find:
+ install_requires =
+ requests
+ importlib-metadata; python_version<"3.8"
+
+ [options.package_data]
+ * = *.txt, *.rst
+ hello = *.msg
+
+ [options.entry_points]
+ console_scripts =
+ executable-name = my_package.module:function
+
+ [options.extras_require]
+ pdf = ReportLab>=1.2; RXP
+ rest = docutils>=0.3; pack ==1.1, ==1.3
+
+ [options.packages.find]
+ exclude =
+ examples*
+ tools*
+ docs*
+ my_package.tests*
+
+Metadata and options are set in the config sections of the same name.
+
+* Keys are the same as the keyword arguments one provides to the ``setup()``
+ function.
+
+* Complex values can be written comma-separated or placed one per line
+ in *dangling* config values. The following are equivalent:
+
+ .. code-block:: ini
+
+ [metadata]
+ keywords = one, two
+
+ [metadata]
+ keywords =
+ one
+ two
+
+* In some cases, complex values can be provided in dedicated subsections for
+ clarity.
+
+* Some keys allow ``file:``, ``attr:``, ``find:``, and ``find_namespace:`` directives in
+ order to cover common usecases.
+
+* Unknown keys are ignored.
+
+
+Using a ``src/`` layout
+=======================
+
+One commonly used package configuration has all the module source code in a
+subdirectory (often called the ``src/`` layout), like this::
+
+ ├── src
+ │ └── mypackage
+ │ ├── __init__.py
+ │ └── mod1.py
+ ├── setup.py
+ └── setup.cfg
+
+You can set up your ``setup.cfg`` to automatically find all your packages in
+the subdirectory like this:
+
+.. code-block:: ini
+
+ # This example contains just the necessary options for a src-layout, set up
+ # the rest of the file as described above.
+
+ [options]
+ package_dir=
+ =src
+ packages=find:
+
+ [options.packages.find]
+ where=src
+
+Specifying values
+=================
+
+Some values are treated as simple strings, some allow more logic.
+
+Type names used below:
+
+* ``str`` - simple string
+* ``list-comma`` - dangling list or string of comma-separated values
+* ``list-semi`` - dangling list or string of semicolon-separated values
+* ``bool`` - ``True`` is 1, yes, true
+* ``dict`` - list-comma where keys are separated from values by ``=``
+* ``section`` - values are read from a dedicated (sub)section
+
+
+Special directives:
+
+* ``attr:`` - Value is read from a module attribute. ``attr:`` supports
+ callables and iterables; unsupported types are cast using ``str()``.
+
+ In order to support the common case of a literal value assigned to a variable
+ in a module containing (directly or indirectly) third-party imports,
+ ``attr:`` first tries to read the value from the module by examining the
+ module's AST. If that fails, ``attr:`` falls back to importing the module.
+
+* ``file:`` - Value is read from a list of files and then concatenated
+
+ .. note::
+ The ``file:`` directive is sandboxed and won't reach anything outside
+ the directory containing ``setup.py``.
+
+
+Metadata
+--------
+
+.. note::
+ The aliases given below are supported for compatibility reasons,
+ but their use is not advised.
+
+============================== ================= ================= =============== ==========
+Key Aliases Type Minimum Version Notes
+============================== ================= ================= =============== ==========
+name str
+version attr:, file:, str 39.2.0 [#meta-1]_
+url home-page str
+download_url download-url str
+project_urls dict 38.3.0
+author str
+author_email author-email str
+maintainer str
+maintainer_email maintainer-email str
+classifiers classifier file:, list-comma
+license str
+license_files license_file list-comma 42.0.0
+description summary file:, str
+long_description long-description file:, str
+long_description_content_type str 38.6.0
+keywords list-comma
+platforms platform list-comma
+provides list-comma
+requires list-comma
+obsoletes list-comma
+============================== ================= ================= =============== ==========
+
+**Notes**:
+
+.. [#meta-1] The ``version`` file attribute has only been supported since 39.2.0.
+
+ A version loaded using the ``file:`` directive must comply with PEP 440.
+ It is easy to accidentally put something other than a valid version
+ string in such a file, so validation is stricter in this case.
+
+
+Options
+-------
+
+======================= =================================== =============== =========
+Key Type Minimum Version Notes
+======================= =================================== =============== =========
+zip_safe bool
+setup_requires list-semi 36.7.0
+install_requires list-semi
+extras_require section [#opt-2]_
+python_requires str 34.4.0
+entry_points file:, section 51.0.0
+scripts list-comma
+eager_resources list-comma
+dependency_links list-comma
+tests_require list-semi
+include_package_data bool
+packages find:, find_namespace:, list-comma [#opt-3]_
+package_dir dict
+package_data section [#opt-1]_
+exclude_package_data section
+namespace_packages list-comma
+py_modules list-comma 34.4.0
+data_files section 40.6.0 [#opt-4]_
+======================= =================================== =============== =========
+
+**Notes**:
+
+.. [#opt-1] In the ``package_data`` section, a key named with a single asterisk
+ (``*``) refers to all packages, in lieu of the empty string used in ``setup.py``.
+
+.. [#opt-2] In the ``extras_require`` section, values are parsed as ``list-semi``.
+ This implies that in order to include markers, they **must** be *dangling*:
+
+ .. code-block:: ini
+
+ [options.extras_require]
+ rest = docutils>=0.3; pack ==1.1, ==1.3
+ pdf =
+ ReportLab>=1.2
+ RXP
+ importlib-metadata; python_version < "3.8"
+
+.. [#opt-3] The ``find:`` and ``find_namespace:`` directive can be further configured
+ in a dedicated subsection ``options.packages.find``. This subsection accepts the
+ same keys as the ``setuptools.find_packages`` and the
+ ``setuptools.find_namespace_packages`` function:
+ ``where``, ``include``, and ``exclude``.
+
+ The ``find_namespace:`` directive is supported since Python >=3.3.
+
+.. [#opt-4] ``data_files`` is deprecated and should be avoided.
+ Please check :doc:`/userguide/datafiles` for more information.
+
+
+Compatibility with other tools
+==============================
+
+Historically, several tools explored declarative package configuration
+in parallel. And several of them chose to place the packaging
+configuration within the project's :file:`setup.cfg` file.
+One of the first was ``distutils2``, which development has stopped in
+2013. Other include ``pbr`` which is still under active development or
+``d2to1``, which was a plug-in that backports declarative configuration
+to ``distutils``, but has had no release since Oct. 2015.
+As a way to harmonize packaging tools, ``setuptools``, having held the
+position of *de facto* standard, has gradually integrated those
+features as part of its core features.
+
+Still this has lead to some confusion and feature incompatibilities:
+
+- some tools support features others don't;
+- some have similar features but the declarative syntax differs;
+
+The table below tries to summarize the differences. But, please, refer
+to each tool documentation for up-to-date information.
+
+=========================== ========== ========== ===== ===
+feature setuptools distutils2 d2to1 pbr
+=========================== ========== ========== ===== ===
+[metadata] description-file S Y Y Y
+[files] S Y Y Y
+entry_points Y Y Y S
+[backwards_compat] N Y Y Y
+=========================== ========== ========== ===== ===
+
+Y: supported, N: unsupported, S: syntax differs (see
+:ref:`above example<example-setup-config>`).
+
+Also note that some features were only recently added to ``setuptools``.
+Please refer to the previous sections to find out when.
diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
new file mode 100644
index 0000000..279f794
--- /dev/null
+++ b/docs/userguide/dependency_management.rst
@@ -0,0 +1,443 @@
+=====================================
+Dependencies Management in Setuptools
+=====================================
+
+There are three types of dependency styles offered by setuptools:
+1) build system requirement, 2) required dependency and 3) optional
+dependency.
+
+.. Note::
+ Packages that are added to dependency can be optionally specified with the
+ version by following `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_
+
+
+Build system requirement
+========================
+
+Package requirement
+-------------------
+After organizing all the scripts and files and getting ready for packaging,
+there needs to be a way to tell Python what programs it needs to actually
+do the packaging (in our case, ``setuptools`` of course). Usually,
+you also need the ``wheel`` package as well since it is recommended that you
+upload a ``.whl`` file to PyPI alongside your ``.tar.gz`` file. Unlike the
+other two types of dependency keyword, this one is specified in your
+``pyproject.toml`` file (if you have forgot what this is, go to
+:doc:`quickstart` or (WIP)):
+
+.. code-block:: ini
+
+ [build-system]
+ requires = ["setuptools"]
+ #...
+
+.. note::
+ This used to be accomplished with the ``setup_requires`` keyword but is
+ now considered deprecated in favor of the PEP 517 style described above.
+ To peek into how this legacy keyword is used, consult our :doc:`guide on
+ deprecated practice (WIP) <../deprecated/index>`
+
+
+.. _Declaring Dependencies:
+
+Declaring required dependency
+=============================
+This is where a package declares its core dependencies, without which it won't
+be able to run. ``setuptools`` support automatically download and install
+these dependencies when the package is installed. Although there is more
+finesse to it, let's start with a simple example.
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ docutils
+ BazSpam ==1.1
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ ...,
+ install_requires=[
+ 'docutils',
+ 'BazSpam ==1.1',
+ ],
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "docutils",
+ "BazSpam == 1.1",
+ ]
+ # ...
+
+
+When your project is installed (e.g. using pip), all of the dependencies not
+already installed will be located (via PyPI), downloaded, built (if necessary),
+and installed and 2) Any scripts in your project will be installed with wrappers
+that verify the availability of the specified dependencies at runtime.
+
+
+Platform specific dependencies
+------------------------------
+Setuptools offer the capability to evaluate certain conditions before blindly
+installing everything listed in ``install_requires``. This is great for platform
+specific dependencies. For example, the ``enum`` package was added in Python
+3.4, therefore, package that depends on it can elect to install it only when
+the Python version is older than 3.4. To accomplish this
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ enum34;python_version<'3.4'
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ ...,
+ install_requires=[
+ "enum34;python_version<'3.4'",
+ ],
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "enum34; python_version<'3.4'",
+ ]
+ # ...
+
+Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
+and only install it if the user is using a Windows operating system:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ enum34;python_version<'3.4'
+ pywin32 >= 1.0;platform_system=='Windows'
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ ...,
+ install_requires=[
+ "enum34;python_version<'3.4'",
+ "pywin32 >= 1.0;platform_system=='Windows'",
+ ],
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "enum34; python_version<'3.4'",
+ "pywin32 >= 1.0; platform_system=='Windows'",
+ ]
+ # ...
+
+The environmental markers that may be used for testing platform types are
+detailed in `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_.
+
+
+Dependencies that aren't in PyPI
+--------------------------------
+.. warning::
+ Dependency links support has been dropped by pip starting with version
+ 19.0 (released 2019-01-22).
+
+If your project depends on packages that don't exist on PyPI, you may still be
+able to depend on them, as long as they are available for download as:
+
+- an egg, in the standard distutils ``sdist`` format,
+- a single ``.py`` file, or
+- a VCS repository (Subversion, Mercurial, or Git).
+
+You just need to add some URLs to the ``dependency_links`` argument to
+``setup()``.
+
+The URLs must be either:
+
+1. direct download URLs,
+2. the URLs of web pages that contain direct download links, or
+3. the repository's URL
+
+In general, it's better to link to web pages, because it is usually less
+complex to update a web page than to release a new version of your project.
+You can also use a SourceForge ``showfiles.php`` link in the case where a
+package you depend on is distributed via SourceForge.
+
+If you depend on a package that's distributed as a single ``.py`` file, you
+must include an ``"#egg=project-version"`` suffix to the URL, to give a project
+name and version number. (Be sure to escape any dashes in the name or version
+by replacing them with underscores.) EasyInstall will recognize this suffix
+and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
+as an egg.
+
+In the case of a VCS checkout, you should also append ``#egg=project-version``
+in order to identify for what package that checkout should be used. You can
+append ``@REV`` to the URL's path (before the fragment) to specify a revision.
+Additionally, you can also force the VCS being used by prepending the URL with
+a certain prefix. Currently available are:
+
+- ``svn+URL`` for Subversion,
+- ``git+URL`` for Git, and
+- ``hg+URL`` for Mercurial
+
+A more complete example would be:
+
+ ``vcs+proto://host/path@revision#egg=project-version``
+
+Be careful with the version. It should match the one inside the project files.
+If you want to disregard the version, you have to omit it both in the
+``requires`` and in the URL's fragment.
+
+This will do a checkout (or a clone, in Git and Mercurial parlance) to a
+temporary folder and run ``setup.py bdist_egg``.
+
+The ``dependency_links`` option takes the form of a list of URL strings. For
+example, this will cause a search of the specified page for eggs or source
+distributions, if the package's dependencies aren't already installed:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ #...
+ dependency_links = http://peak.telecommunity.com/snapshots/
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ ...,
+ dependency_links=[
+ "http://peak.telecommunity.com/snapshots/",
+ ],
+ )
+
+
+Optional dependencies
+=====================
+Setuptools allows you to declare dependencies that only get installed under
+specific circumstances. These dependencies are specified with ``extras_require``
+keyword and are only installed if another package depends on it (either
+directly or indirectly) This makes it convenient to declare dependencies for
+ancillary functions such as "tests" and "docs".
+
+.. note::
+ ``tests_require`` is now deprecated
+
+For example, Package-A offers optional PDF support and requires two other
+dependencies for it to work:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [metadata]
+ name = Package-A
+
+ [options.extras_require]
+ PDF = ReportLab>=1.2; RXP
+
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ name="Project-A",
+ ...,
+ extras_require={
+ "PDF": ["ReportLab>=1.2", "RXP"],
+ },
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ # ...
+ [project.optional-dependencies]
+ PDF = ["ReportLab>=1.2", "RXP"]
+
+The name ``PDF`` is an arbitrary identifier of such a list of dependencies, to
+which other components can refer and have them installed.
+
+A use case for this approach is that other package can use this "extra" for their
+own dependencies. For example, if "Project-B" needs "project A" with PDF support
+installed, it might declare the dependency like this:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [metadata]
+ name = Project-B
+ #...
+
+ [options]
+ #...
+ install_requires =
+ Project-A[PDF]
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ name="Project-B",
+ install_requires=["Project-A[PDF]"],
+ ...,
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ name = "Project-B"
+ # ...
+ dependencies = [
+ "Project-A[PDF]"
+ ]
+
+This will cause ReportLab to be installed along with project A, if project B is
+installed -- even if project A was already installed. In this way, a project
+can encapsulate groups of optional "downstream dependencies" under a feature
+name, so that packages that depend on it don't have to know what the downstream
+dependencies are. If a later version of Project A builds in PDF support and
+no longer needs ReportLab, or if it ends up needing other dependencies besides
+ReportLab in order to provide PDF support, Project B's setup information does
+not need to change, but the right packages will still be installed if needed.
+
+.. note::
+ Best practice: if a project ends up no longer needing any other packages to
+ support a feature, it should keep an empty requirements list for that feature
+ in its ``extras_require`` argument, so that packages depending on that feature
+ don't break (due to an invalid feature name).
+
+Historically ``setuptools`` also used to support extra dependencies in console
+scripts, for example:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [metadata]
+ name = Project A
+ #...
+
+ [options]
+ #...
+ entry_points=
+ [console_scripts]
+ rst2pdf = project_a.tools.pdfgen [PDF]
+ rst2html = project_a.tools.htmlgen
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ name="Project-A",
+ ...,
+ entry_points={
+ "console_scripts": [
+ "rst2pdf = project_a.tools.pdfgen [PDF]",
+ "rst2html = project_a.tools.htmlgen",
+ ],
+ },
+ )
+
+This syntax indicates that the entry point (in this case a console script)
+is only valid when the PDF extra is installed. It is up to the installer
+to determine how to handle the situation where PDF was not indicated
+(e.g. omit the console script, provide a warning when attempting to load
+the entry point, assume the extras are present and let the implementation
+fail later).
+
+.. warning::
+ ``pip`` and other tools might not support this use case for extra
+ dependencies, therefore this practice is considered **deprecated**.
+ See :doc:`PyPUG:specifications/entry-points`.
+
+
+Python requirement
+==================
+In some cases, you might need to specify the minimum required python version.
+This can be configured as shown in the example below.
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [metadata]
+ name = Project-B
+ #...
+
+ [options]
+ #...
+ python_requires = >=3.6
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ name="Project-B",
+ python_requires=">=3.6",
+ ...,
+ )
+
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ name = "Project-B"
+ requires-python = ">=3.6"
+ # ...
+
+----
+
+.. rubric:: Notes
+
+.. [#experimental]
+ While the ``[build-system]`` table should always be specified in the
+ ``pyproject.toml`` file, support for adding package metadata and build configuration
+ options via the ``[project]`` and ``[tool.setuptools]`` tables is still
+ experimental and might change (or be completely removed) in future releases.
+ See :doc:`/userguide/pyproject_config`.
diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst
new file mode 100644
index 0000000..90bc567
--- /dev/null
+++ b/docs/userguide/development_mode.rst
@@ -0,0 +1,52 @@
+"Development Mode"
+==================
+
+Under normal circumstances, the ``distutils`` assume that you are going to
+build a distribution of your project, not use it in its "raw" or "unbuilt"
+form. However, if you were to use the ``distutils`` to build a distribution,
+you would have to rebuild and reinstall your project every time you made a
+change to it during development.
+
+Another problem that sometimes comes up with the ``distutils`` is that you may
+need to do development on two related projects at the same time. You may need
+to put both projects' packages in the same directory to run them, but need to
+keep them separate for revision control purposes. How can you do this?
+
+Setuptools allows you to deploy your projects for use in a common directory or
+staging area, but without copying any files. Thus, you can edit each project's
+code in its checkout directory, and only need to run build commands when you
+change a project's C extensions or similarly compiled files. You can even
+deploy a project into another project's checkout directory, if that's your
+preferred way of working (as opposed to using a common independent staging area
+or the site-packages directory).
+
+To do this, use the ``setup.py develop`` command. It works very similarly to
+``setup.py install``, except that it doesn't actually install anything.
+Instead, it creates a special ``.egg-link`` file in the deployment directory,
+that links to your project's source code. And, if your deployment directory is
+Python's ``site-packages`` directory, it will also update the
+``easy-install.pth`` file to include your project's source code, thereby making
+it available on ``sys.path`` for all programs using that Python installation.
+
+In addition, the ``develop`` command creates wrapper scripts in the target
+script directory that will run your in-development scripts after ensuring that
+all your ``install_requires`` packages are available on ``sys.path``.
+
+You can deploy the same project to multiple staging areas, e.g. if you have
+multiple projects on the same machine that are sharing the same project you're
+doing development work.
+
+When you're done with a given development task, you can remove the project
+source from a staging area using ``setup.py develop --uninstall``, specifying
+the desired staging area if it's not the default.
+
+There are several options to control the precise behavior of the ``develop``
+command; see the section on the :ref:`develop <develop>` command below for more details.
+
+Note that you can also apply setuptools commands to non-setuptools projects,
+using commands like this::
+
+ python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop
+
+That is, you can simply list the normal setup commands and options following
+the quoted part.
diff --git a/docs/userguide/distribution.rst b/docs/userguide/distribution.rst
new file mode 100644
index 0000000..db0f1a5
--- /dev/null
+++ b/docs/userguide/distribution.rst
@@ -0,0 +1,251 @@
+Tagging and "Daily Build" or "Snapshot" Releases
+------------------------------------------------
+
+When a set of related projects are under development, it may be important to
+track finer-grained version increments than you would normally use for e.g.
+"stable" releases. While stable releases might be measured in dotted numbers
+with alpha/beta/etc. status codes, development versions of a project often
+need to be tracked by revision or build number or even build date. This is
+especially true when projects in development need to refer to one another, and
+therefore may literally need an up-to-the-minute version of something!
+
+To support these scenarios, ``setuptools`` allows you to "tag" your source and
+egg distributions by adding one or more of the following to the project's
+"official" version identifier:
+
+* A manually-specified pre-release tag, such as "build" or "dev", or a
+ manually-specified post-release tag, such as a build or revision number
+ (``--tag-build=STRING, -bSTRING``)
+
+* An 8-character representation of the build date (``--tag-date, -d``), as
+ a postrelease tag
+
+You can add these tags by adding ``egg_info`` and the desired options to
+the command line ahead of the ``sdist`` or ``bdist`` commands that you want
+to generate a daily build or snapshot for. See the section below on the
+:ref:`egg_info <egg_info>` command for more details.
+
+(Also, before you release your project, be sure to see the section on
+:ref:`Specifying Your Project's Version` for more information about how pre- and
+post-release tags affect how version numbers are interpreted. This is
+important in order to make sure that dependency processing tools will know
+which versions of your project are newer than others.)
+
+Finally, if you are creating builds frequently, and either building them in a
+downloadable location or are copying them to a distribution server, you should
+probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
+delete all but the N most-recently-modified distributions matching a glob
+pattern. So, you can use a command line like::
+
+ setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
+
+to build an egg whose version info includes "DEV-rNNNN" (where NNNN is the
+most recent Subversion revision that affected the source tree), and then
+delete any egg files from the distribution directory except for the three
+that were built most recently.
+
+If you have to manage automated builds for multiple packages, each with
+different tagging and rotation policies, you may also want to check out the
+:ref:`alias <alias>` command, which would let each package define an alias like ``daily``
+that would perform the necessary tag, build, and rotate commands. Then, a
+simpler script or cron job could just run ``setup.py daily`` in each project
+directory. (And, you could also define sitewide or per-user default versions
+of the ``daily`` alias, so that projects that didn't define their own would
+use the appropriate defaults.)
+
+Generating Source Distributions
+-------------------------------
+
+``setuptools`` enhances the distutils' default algorithm for source file
+selection with pluggable endpoints for looking up files to include. If you are
+using a revision control system, and your source distributions only need to
+include files that you're tracking in revision control, use a corresponding
+plugin instead of writing a ``MANIFEST.in`` file. See the section below on
+:ref:`Adding Support for Revision Control Systems` for information on plugins.
+
+If you need to include automatically generated files, or files that are kept in
+an unsupported revision control system, you'll need to create a ``MANIFEST.in``
+file to specify any files that the default file location algorithm doesn't
+catch. See the distutils documentation for more information on the format of
+the ``MANIFEST.in`` file.
+
+But, be sure to ignore any part of the distutils documentation that deals with
+``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
+from these issues and doesn't work the same way in any case. Unlike the
+distutils, setuptools regenerates the source distribution manifest file
+every time you build a source distribution, and it builds it inside the
+project's ``.egg-info`` directory, out of the way of your main project
+directory. You therefore need not worry about whether it is up-to-date or not.
+
+Indeed, because setuptools' approach to determining the contents of a source
+distribution is so much simpler, its ``sdist`` command omits nearly all of
+the options that the distutils' more complex ``sdist`` process requires. For
+all practical purposes, you'll probably use only the ``--formats`` option, if
+you use any option at all.
+
+
+Making "Official" (Non-Snapshot) Releases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you make an official release, creating source or binary distributions,
+you will need to override the tag settings from ``setup.cfg``, so that you
+don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
+easy to do if you are developing on the trunk and using tags or branches for
+your releases - just make the change to ``setup.cfg`` after branching or
+tagging the release, so the trunk will still produce development snapshots.
+
+Alternately, if you are not branching for releases, you can override the
+default version options on the command line, using something like::
+
+ setup.py egg_info -Db "" sdist bdist_egg
+
+The first part of this command (``egg_info -Db ""``) will override the
+configured tag information, before creating source and binary eggs. Thus, these
+commands will use the plain version from your ``setup.py``, without adding the
+build designation string.
+
+Of course, if you will be doing this a lot, you may wish to create a personal
+alias for this operation, e.g.::
+
+ setup.py alias -u release egg_info -Db ""
+
+You can then use it like this::
+
+ setup.py release sdist bdist_egg
+
+Or of course you can create more elaborate aliases that do all of the above.
+See the sections below on the :ref:`egg_info <egg_info>` and
+:ref:`alias <alias>` commands for more ideas.
+
+Distributing Extensions compiled with Cython
+--------------------------------------------
+
+``setuptools`` will detect at build time whether Cython is installed or not.
+If Cython is not found ``setuptools`` will ignore pyx files.
+
+To ensure Cython is available, include Cython in the build-requires section
+of your pyproject.toml::
+
+ [build-system]
+ requires=[..., "cython"]
+
+Built with pip 10 or later, that declaration is sufficient to include Cython
+in the build. For broader compatibility, declare the dependency in your
+setup-requires of setup.cfg::
+
+ [options]
+ setup_requires =
+ ...
+ cython
+
+As long as Cython is present in the build environment, ``setuptools`` includes
+transparent support for building Cython extensions, as
+long as extensions are defined using ``setuptools.Extension``.
+
+If you follow these rules, you can safely list ``.pyx`` files as the source
+of your ``Extension`` objects in the setup script. If it is, then ``setuptools``
+will use it.
+
+Of course, for this to work, your source distributions must include the C
+code generated by Cython, as well as your original ``.pyx`` files. This means
+that you will probably want to include current ``.c`` files in your revision
+control system, rebuilding them whenever you check changes in for the ``.pyx``
+source files. This will ensure that people tracking your project in a revision
+control system will be able to build it even if they don't have Cython
+installed, and that your source releases will be similarly usable with or
+without Cython.
+
+
+.. _Specifying Your Project's Version:
+
+Specifying Your Project's Version
+---------------------------------
+
+Setuptools can work well with most versioning schemes. Over the years,
+setuptools has tried to closely follow the
+`PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_ scheme, but it
+also supports legacy versions. There are, however, a
+few special things to watch out for, in order to ensure that setuptools and
+other tools can always tell what version of your package is newer than another
+version. Knowing these things will also help you correctly specify what
+versions of other projects your project depends on.
+
+A version consists of an alternating series of release numbers and pre-release
+or post-release tags. A release number is a series of digits punctuated by
+dots, such as ``2.4`` or ``0.5``. Each series of digits is treated
+numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
+same release number, denoting the first subrelease of release 2. But ``2.10``
+is the *tenth* subrelease of release 2, and so is a different and newer release
+from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
+ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
+
+Following a release number, you can have either a pre-release or post-release
+tag. Pre-release tags make a version be considered *older* than the version
+they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``,
+which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make
+a version be considered *newer* than the version they are appended to. So,
+revisions like ``2.4-1`` are newer than ``2.4``, but *older*
+than ``2.4.1`` (which has a higher release number).
+
+In the case of legacy versions (for example, ``2.4pl1``), they are considered
+older than non-legacy versions. Taking that in count, a revision ``2.4pl1``
+is *older* than ``2.4``
+
+A pre-release tag is a series of letters that are alphabetically before
+"final". Some examples of prerelease tags would include ``alpha``, ``beta``,
+``a``, ``c``, ``dev``, and so on. You do not have to place a dot or dash
+before the prerelease tag if it's immediately after a number, but it's okay to
+do so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` and ``2.4-c1`` all
+represent release candidate 1 of version ``2.4``, and are treated as identical
+by setuptools.
+
+In addition, there are three special prerelease tags that are treated as if
+they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version
+``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as
+``2.4c1``, and are treated as identical by setuptools.
+
+A post-release tag is either a series of letters that are alphabetically
+greater than or equal to "final", or a dash (``-``). Post-release tags are
+generally used to separate patch numbers, port numbers, build numbers, revision
+numbers, or date stamps from the release number. For example, the version
+``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of
+version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped
+post-release.
+
+Notice that after each pre or post-release tag, you are free to place another
+release number, followed again by more pre- or post-release tags. For example,
+``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in-
+development version of the ninth alpha of release 0.6. Notice that ``dev`` is
+a pre-release tag, so this version is a *lower* version number than ``0.6a9``,
+which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is
+a post-release tag, so this version is *newer* than ``0.6a9.dev``.
+
+For the most part, setuptools' interpretation of version numbers is intuitive,
+but here are a few tips that will keep you out of trouble in the corner cases:
+
+* Don't stick adjoining pre-release tags together without a dot or number
+ between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``,
+ *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in
+ ``1.9a.dev``, or separate the prerelease tags with a number, as in
+ ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are
+ identical versions from setuptools' point of view, so you can use whatever
+ scheme you prefer.
+
+* If you want to be certain that your chosen numbering scheme works the way
+ you think it will, you can use the ``pkg_resources.parse_version()`` function
+ to compare different version numbers::
+
+ >>> from pkg_resources import parse_version
+ >>> parse_version("1.9.a.dev") == parse_version("1.9a0dev")
+ True
+ >>> parse_version("2.1-rc2") < parse_version("2.1")
+ True
+ >>> parse_version("0.6a9dev-r41475") < parse_version("0.6a9")
+ True
+
+Once you've decided on a version numbering scheme for your project, you can
+have setuptools automatically tag your in-development releases with various
+pre- or post-release tags. See the following sections for more details:
+
+* `Tagging and "Daily Build" or "Snapshot" Releases`_
+* The :ref:`egg_info <egg_info>` command
diff --git a/docs/userguide/entry_point.rst b/docs/userguide/entry_point.rst
new file mode 100644
index 0000000..b97419c
--- /dev/null
+++ b/docs/userguide/entry_point.rst
@@ -0,0 +1,181 @@
+.. _`entry_points`:
+
+============
+Entry Points
+============
+
+Packages may provide commands to be run at the console (console scripts),
+such as the ``pip`` command. These commands are defined for a package
+as a specific kind of entry point in the ``setup.cfg`` or
+``setup.py``.
+
+
+Console Scripts
+===============
+
+First consider an example without entry points. Imagine a package
+defined thus:
+
+.. code-block:: bash
+
+ timmins/
+ timmins/__init__.py
+ timmins/__main__.py
+ setup.cfg # or setup.py
+ #other necessary files
+
+with ``__init__.py`` as:
+
+.. code-block:: python
+
+ def hello_world():
+ print("Hello world")
+
+and ``__main__.py`` providing a hook:
+
+.. code-block:: python
+
+ from . import hello_world
+
+ if __name__ == '__main__':
+ hello_world()
+
+After installing the package, the function may be invoked through the
+`runpy <https://docs.python.org/3/library/runpy.html>`_ module:
+
+.. code-block:: bash
+
+ python -m timmins
+
+Adding a console script entry point allows the package to define a
+user-friendly name for installers of the package to execute. Installers
+like pip will create wrapper scripts to execute a function. In the
+above example, to create a command ``hello-world`` that invokes
+``timmins.hello_world``, add a console script entry point to
+``setup.cfg``:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options.entry_points]
+ console_scripts =
+ hello-world = timmins:hello_world
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ from setuptools import setup
+
+ setup(
+ name='timmins',
+ version='0.0.1',
+ packages=['timmins'],
+ # ...
+ entry_points={
+ 'console_scripts': [
+ 'hello-world=timmins:hello_world',
+ ]
+ }
+ )
+
+
+After installing the package, a user may invoke that function by simply calling
+``hello-world`` on the command line.
+
+The syntax for entry points is specified as follows:
+
+.. code-block:: ini
+
+ <name> = [<package>.[<subpackage>.]]<module>[:<object>.<object>]
+
+where ``name`` is the name for the script you want to create, the left hand
+side of ``:`` is the module that contains your function and the right hand
+side is the object you want to invoke (e.g. a function).
+
+In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which
+will launch a GUI application without running in a terminal window.
+
+
+.. _dynamic discovery of services and plugins:
+
+Advertising Behavior
+====================
+
+Console scripts are one use of the more general concept of entry points. Entry
+points more generally allow a packager to advertise behavior for discovery by
+other libraries and applications. This feature enables "plug-in"-like
+functionality, where one library solicits entry points and any number of other
+libraries provide those entry points.
+
+A good example of this plug-in behavior can be seen in
+`pytest plugins <https://docs.pytest.org/en/latest/writing_plugins.html>`_,
+where pytest is a test framework that allows other libraries to extend
+or modify its functionality through the ``pytest11`` entry point.
+
+The console scripts work similarly, where libraries advertise their commands
+and tools like ``pip`` create wrapper scripts that invoke those commands.
+
+For a project wishing to solicit entry points, Setuptools recommends the
+`importlib.metadata <https://docs.python.org/3/library/importlib.metadata.html>`_
+module (part of stdlib since Python 3.8) or its backport,
+:pypi:`importlib_metadata`.
+
+For example, to find the console script entry points from the example above:
+
+.. code-block:: pycon
+
+ >>> from importlib import metadata
+ >>> eps = metadata.entry_points()['console_scripts']
+
+``eps`` is now a list of ``EntryPoint`` objects, one of which corresponds
+to the ``hello-world = timmins:hello_world`` defined above. Each ``EntryPoint``
+contains the ``name``, ``group``, and ``value``. It also supplies a ``.load()``
+method to import and load that entry point (module or object).
+
+.. code-block:: ini
+
+ [options.entry_points]
+ my.plugins =
+ hello-world = timmins:hello_world
+
+Then, a different project wishing to load 'my.plugins' plugins could run
+the following routine to load (and invoke) such plugins:
+
+.. code-block:: pycon
+
+ >>> from importlib import metadata
+ >>> eps = metadata.entry_points()['my.plugins']
+ >>> for ep in eps:
+ ... plugin = ep.load()
+ ... plugin()
+ ...
+
+The project soliciting the entry points needs not to have any dependency
+or prior knowledge about the libraries implementing the entry points, and
+downstream users are able to compose functionality by pulling together
+libraries implementing the entry points.
+
+
+Dependency Management
+=====================
+
+Some entry points may require additional dependencies to properly function.
+For such an entry point, declare in square brackets any number of dependency
+``extras`` following the entry point definition. Such entry points will only
+be viable if their extras were declared and installed. See the
+:doc:`guide on dependencies management <dependency_management>` for
+more information on defining extra requirements. Consider from the
+above example:
+
+.. code-block:: ini
+
+ [options.entry_points]
+ console_scripts =
+ hello-world = timmins:hello_world [pretty-printer]
+
+In this case, the ``hello-world`` script is only viable if the ``pretty-printer``
+extra is indicated, and so a plugin host might exclude that entry point
+(i.e. not install a console script) if the relevant extra dependencies are not
+installed.
diff --git a/docs/userguide/extension.rst b/docs/userguide/extension.rst
new file mode 100644
index 0000000..21fb05b
--- /dev/null
+++ b/docs/userguide/extension.rst
@@ -0,0 +1,250 @@
+.. _Creating ``distutils`` Extensions:
+
+Creating ``distutils`` Extensions
+=================================
+
+It can be hard to add new commands or setup arguments to the distutils. But
+the ``setuptools`` package makes it a bit easier, by allowing you to distribute
+a distutils extension as a separate project, and then have projects that need
+the extension just refer to it in their ``setup_requires`` argument.
+
+With ``setuptools``, your distutils extension projects can hook in new
+commands and ``setup()`` arguments just by defining "entry points". These
+are mappings from command or argument names to a specification of where to
+import a handler from. (See the section on :ref:`Dynamic Discovery of
+Services and Plugins` above for some more background on entry points.)
+
+
+Adding Commands
+---------------
+
+You can add new ``setup`` commands by defining entry points in the
+``distutils.commands`` group. For example, if you wanted to add a ``foo``
+command, you might add something like this to your distutils extension
+project's setup script::
+
+ setup(
+ # ...
+ entry_points={
+ "distutils.commands": [
+ "foo = mypackage.some_module:foo",
+ ],
+ },
+ )
+
+(Assuming, of course, that the ``foo`` class in ``mypackage.some_module`` is
+a ``setuptools.Command`` subclass.)
+
+Once a project containing such entry points has been activated on ``sys.path``,
+(e.g. by running "install" or "develop" with a site-packages installation
+directory) the command(s) will be available to any ``setuptools``-based setup
+scripts. It is not necessary to use the ``--command-packages`` option or
+to monkeypatch the ``distutils.command`` package to install your commands;
+``setuptools`` automatically adds a wrapper to the distutils to search for
+entry points in the active distributions on ``sys.path``. In fact, this is
+how setuptools' own commands are installed: the setuptools project's setup
+script defines entry points for them!
+
+.. note::
+ When creating commands, and specially when defining custom ways of building
+ compiled extensions (for example via ``build_ext``), consider
+ handling exceptions such as ``CompileError``, ``LinkError``, ``LibError``,
+ among others. These exceptions are available in the ``setuptools.errors``
+ module.
+
+
+Adding ``setup()`` Arguments
+----------------------------
+
+.. warning:: Adding arguments to setup is discouraged as such arguments
+ are only supported through imperative execution and not supported through
+ declarative config.
+
+Sometimes, your commands may need additional arguments to the ``setup()``
+call. You can enable this by defining entry points in the
+``distutils.setup_keywords`` group. For example, if you wanted a ``setup()``
+argument called ``bar_baz``, you might add something like this to your
+distutils extension project's setup script::
+
+ setup(
+ # ...
+ entry_points={
+ "distutils.commands": [
+ "foo = mypackage.some_module:foo",
+ ],
+ "distutils.setup_keywords": [
+ "bar_baz = mypackage.some_module:validate_bar_baz",
+ ],
+ },
+ )
+
+The idea here is that the entry point defines a function that will be called
+to validate the ``setup()`` argument, if it's supplied. The ``Distribution``
+object will have the initial value of the attribute set to ``None``, and the
+validation function will only be called if the ``setup()`` call sets it to
+a non-None value. Here's an example validation function::
+
+ def assert_bool(dist, attr, value):
+ """Verify that value is True, False, 0, or 1"""
+ if bool(value) != value:
+ raise DistutilsSetupError(
+ "%r must be a boolean value (got %r)" % (attr,value)
+ )
+
+Your function should accept three arguments: the ``Distribution`` object,
+the attribute name, and the attribute value. It should raise a
+``DistutilsSetupError`` (from the ``distutils.errors`` module) if the argument
+is invalid. Remember, your function will only be called with non-None values,
+and the default value of arguments defined this way is always None. So, your
+commands should always be prepared for the possibility that the attribute will
+be ``None`` when they access it later.
+
+If more than one active distribution defines an entry point for the same
+``setup()`` argument, *all* of them will be called. This allows multiple
+distutils extensions to define a common argument, as long as they agree on
+what values of that argument are valid.
+
+Also note that as with commands, it is not necessary to subclass or monkeypatch
+the distutils ``Distribution`` class in order to add your arguments; it is
+sufficient to define the entry points in your extension, as long as any setup
+script using your extension lists your project in its ``setup_requires``
+argument.
+
+
+Customizing Distribution Options
+--------------------------------
+
+Plugins may wish to extend or alter the options on a Distribution object to
+suit the purposes of that project. For example, a tool that infers the
+``Distribution.version`` from SCM-metadata may need to hook into the
+option finalization. To enable this feature, Setuptools offers an entry
+point "setuptools.finalize_distribution_options". That entry point must
+be a callable taking one argument (the Distribution instance).
+
+If the callable has an ``.order`` property, that value will be used to
+determine the order in which the hook is called. Lower numbers are called
+first and the default is zero (0).
+
+Plugins may read, alter, and set properties on the distribution, but each
+plugin is encouraged to load the configuration/settings for their behavior
+independently.
+
+
+.. _Adding new EGG-INFO Files:
+
+Adding new EGG-INFO Files
+-------------------------
+
+Some extensible applications or frameworks may want to allow third parties to
+develop plugins with application or framework-specific metadata included in
+the plugins' EGG-INFO directory, for easy access via the ``pkg_resources``
+metadata API. The easiest way to allow this is to create a distutils extension
+to be used from the plugin projects' setup scripts (via ``setup_requires``)
+that defines a new setup keyword, and then uses that data to write an EGG-INFO
+file when the ``egg_info`` command is run.
+
+The ``egg_info`` command looks for extension points in an ``egg_info.writers``
+group, and calls them to write the files. Here's a simple example of a
+distutils extension defining a setup argument ``foo_bar``, which is a list of
+lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any
+project that uses the argument::
+
+ setup(
+ # ...
+ entry_points={
+ "distutils.setup_keywords": [
+ "foo_bar = setuptools.dist:assert_string_list",
+ ],
+ "egg_info.writers": [
+ "foo_bar.txt = setuptools.command.egg_info:write_arg",
+ ],
+ },
+ )
+
+This simple example makes use of two utility functions defined by setuptools
+for its own use: a routine to validate that a setup keyword is a sequence of
+strings, and another one that looks up a setup argument and writes it to
+a file. Here's what the writer utility looks like::
+
+ def write_arg(cmd, basename, filename):
+ argname = os.path.splitext(basename)[0]
+ value = getattr(cmd.distribution, argname, None)
+ if value is not None:
+ value = "\n".join(value) + "\n"
+ cmd.write_or_delete_file(argname, filename, value)
+
+As you can see, ``egg_info.writers`` entry points must be a function taking
+three arguments: a ``egg_info`` command instance, the basename of the file to
+write (e.g. ``foo_bar.txt``), and the actual full filename that should be
+written to.
+
+In general, writer functions should honor the command object's ``dry_run``
+setting when writing files, and use the ``distutils.log`` object to do any
+console output. The easiest way to conform to this requirement is to use
+the ``cmd`` object's ``write_file()``, ``delete_file()``, and
+``write_or_delete_file()`` methods exclusively for your file operations. See
+those methods' docstrings for more details.
+
+
+.. _Adding Support for Revision Control Systems:
+
+Adding Support for Revision Control Systems
+-------------------------------------------------
+
+If the files you want to include in the source distribution are tracked using
+Git, Mercurial or SVN, you can use the following packages to achieve that:
+
+- Git and Mercurial: :pypi:`setuptools_scm`
+- SVN: :pypi:`setuptools_svn`
+
+If you would like to create a plugin for ``setuptools`` to find files tracked
+by another revision control system, you can do so by adding an entry point to
+the ``setuptools.file_finders`` group. The entry point should be a function
+accepting a single directory name, and should yield all the filenames within
+that directory (and any subdirectories thereof) that are under revision
+control.
+
+For example, if you were going to create a plugin for a revision control system
+called "foobar", you would write a function something like this:
+
+.. code-block:: python
+
+ def find_files_for_foobar(dirname):
+ ... # loop to yield paths that start with `dirname`
+
+And you would register it in a setup script using something like this::
+
+ entry_points={
+ "setuptools.file_finders": [
+ "foobar = my_foobar_module:find_files_for_foobar",
+ ]
+ }
+
+Then, anyone who wants to use your plugin can simply install it, and their
+local setuptools installation will be able to find the necessary files.
+
+It is not necessary to distribute source control plugins with projects that
+simply use the other source control system, or to specify the plugins in
+``setup_requires``. When you create a source distribution with the ``sdist``
+command, setuptools automatically records what files were found in the
+``SOURCES.txt`` file. That way, recipients of source distributions don't need
+to have revision control at all. However, if someone is working on a package
+by checking out with that system, they will need the same plugin(s) that the
+original author is using.
+
+A few important points for writing revision control file finders:
+
+* Your finder function MUST return relative paths, created by appending to the
+ passed-in directory name. Absolute paths are NOT allowed, nor are relative
+ paths that reference a parent directory of the passed-in directory.
+
+* Your finder function MUST accept an empty string as the directory name,
+ meaning the current directory. You MUST NOT convert this to a dot; just
+ yield relative paths. So, yielding a subdirectory named ``some/dir`` under
+ the current directory should NOT be rendered as ``./some/dir`` or
+ ``/somewhere/some/dir``, but *always* as simply ``some/dir``
+
+* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
+ with the absence of needed programs (i.e., ones belonging to the revision
+ control system itself. It *may*, however, use ``distutils.log.warn()`` to
+ inform the user of the missing program(s).
diff --git a/docs/userguide/functionalities_rewrite.rst b/docs/userguide/functionalities_rewrite.rst
new file mode 100644
index 0000000..d0997ca
--- /dev/null
+++ b/docs/userguide/functionalities_rewrite.rst
@@ -0,0 +1,9 @@
+========================================================
+Using setuptools to package and distribute your project
+========================================================
+
+``setuptools`` offers a variety of functionalities that make it easy to
+build and distribute your python package. Here we provide an overview on
+the commonly used ones.
+
+
diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
new file mode 100644
index 0000000..49655ac
--- /dev/null
+++ b/docs/userguide/index.rst
@@ -0,0 +1,38 @@
+==================================================
+Building and Distributing Packages with Setuptools
+==================================================
+
+``Setuptools`` is a collection of enhancements to the Python ``distutils``
+that allow developers to more easily build and
+distribute Python packages, especially ones that have dependencies on other
+packages.
+
+Packages built and distributed using ``setuptools`` look to the user like
+ordinary Python packages based on the ``distutils``.
+
+Transition to PEP517
+====================
+
+Since setuptools no longer serves as the default build tool, one must explicitly
+opt in (by providing a :file:`pyproject.toml` file) to use this library. The user
+facing part is provided by tools such as pip and
+backend interface is described :doc:`in this document <../build_meta>`. The
+quickstart provides an overview of the new workflow.
+
+.. toctree::
+ :maxdepth: 1
+
+ quickstart
+ package_discovery
+ entry_point
+ dependency_management
+ datafiles
+ development_mode
+ distribution
+ extension
+ declarative_config
+ pyproject_config
+ keywords
+ commands
+ functionalities_rewrite
+ miscellaneous
diff --git a/docs/userguide/keywords.rst b/docs/userguide/keywords.rst
new file mode 100644
index 0000000..5388ffe
--- /dev/null
+++ b/docs/userguide/keywords.rst
@@ -0,0 +1,163 @@
+New and Changed ``setup()`` Keywords
+====================================
+
+The following keyword arguments to ``setup()`` are added or changed by
+``setuptools``. All of them are optional; you do not have to supply them
+unless you need the associated ``setuptools`` feature.
+
+``include_package_data``
+ If set to ``True``, this tells ``setuptools`` to automatically include any
+ data files it finds inside your package directories that are specified by
+ your ``MANIFEST.in`` file. For more information, see the section on
+ :ref:`Including Data Files`.
+
+``exclude_package_data``
+ A dictionary mapping package names to lists of glob patterns that should
+ be *excluded* from your package directories. You can use this to trim back
+ any excess files included by ``include_package_data``. For a complete
+ description and examples, see the section on :ref:`Including Data Files`.
+
+``package_data``
+ A dictionary mapping package names to lists of glob patterns. For a
+ complete description and examples, see the section on :ref:`Including
+ Data Files`. You do not need to use this option if you are using
+ ``include_package_data``, unless you need to add e.g. files that are
+ generated by your setup script and build process. (And are therefore not
+ in source control or are files that you don't want to include in your
+ source distribution.)
+
+``zip_safe``
+ A boolean (True or False) flag specifying whether the project can be
+ safely installed and run from a zip file. If this argument is not
+ supplied, the ``bdist_egg`` command will have to analyze all of your
+ project's contents for possible problems each time it builds an egg.
+
+``install_requires``
+ A string or list of strings specifying what other distributions need to
+ be installed when this one is. See the section on :ref:`Declaring
+ Dependencies` for details and examples of the format of this argument.
+
+``entry_points``
+ A dictionary mapping entry point group names to strings or lists of strings
+ defining the entry points. Entry points are used to support dynamic
+ discovery of services or plugins provided by a project. See :ref:`Dynamic
+ Discovery of Services and Plugins` for details and examples of the format
+ of this argument. In addition, this keyword is used to support
+ :ref:`Automatic Script Creation <entry_points>`.
+
+``extras_require``
+ A dictionary mapping names of "extras" (optional features of your project)
+ to strings or lists of strings specifying what other distributions must be
+ installed to support those features. See the section on :ref:`Declaring
+ Dependencies` for details and examples of the format of this argument.
+
+``python_requires``
+ A string corresponding to a version specifier (as defined in PEP 440) for
+ the Python version, used to specify the Requires-Python defined in PEP 345.
+
+``setup_requires``
+ A string or list of strings specifying what other distributions need to
+ be present in order for the *setup script* to run. ``setuptools`` will
+ attempt to obtain these (using pip if available) before processing the
+ rest of the setup script or commands. This argument is needed if you
+ are using distutils extensions as part of your build process; for
+ example, extensions that process setup() arguments and turn them into
+ EGG-INFO metadata files.
+
+ (Note: projects listed in ``setup_requires`` will NOT be automatically
+ installed on the system where the setup script is being run. They are
+ simply downloaded to the ./.eggs directory if they're not locally available
+ already. If you want them to be installed, as well as being available
+ when the setup script is run, you should add them to ``install_requires``
+ **and** ``setup_requires``.)
+
+``dependency_links``
+ A list of strings naming URLs to be searched when satisfying dependencies.
+ These links will be used if needed to install packages specified by
+ ``setup_requires`` or ``tests_require``. They will also be written into
+ the egg's metadata for use during install by tools that support them.
+
+``namespace_packages``
+ A list of strings naming the project's "namespace packages". A namespace
+ package is a package that may be split across multiple project
+ distributions. For example, Zope 3's ``zope`` package is a namespace
+ package, because subpackages like ``zope.interface`` and ``zope.publisher``
+ may be distributed separately. The egg runtime system can automatically
+ merge such subpackages into a single parent package at runtime, as long
+ as you declare them in each project that contains any subpackages of the
+ namespace package, and as long as the namespace package's ``__init__.py``
+ does not contain any code other than a namespace declaration. See the
+ section below on :ref:`Namespace Packages` for more information.
+
+``test_suite``
+ A string naming a ``unittest.TestCase`` subclass (or a package or module
+ containing one or more of them, or a method of such a subclass), or naming
+ a function that can be called with no arguments and returns a
+ ``unittest.TestSuite``. If the named suite is a module, and the module
+ has an ``additional_tests()`` function, it is called and the results are
+ added to the tests to be run. If the named suite is a package, any
+ submodules and subpackages are recursively added to the overall test suite.
+
+ Specifying this argument enables use of the :ref:`test <test>` command to run the
+ specified test suite, e.g. via ``setup.py test``. See the section on the
+ :ref:`test <test>` command below for more details.
+
+ New in 41.5.0: Deprecated the test command.
+
+``tests_require``
+ If your project's tests need one or more additional packages besides those
+ needed to install it, you can use this option to specify them. It should
+ be a string or list of strings specifying what other distributions need to
+ be present for the package's tests to run. When you run the ``test``
+ command, ``setuptools`` will attempt to obtain these (using pip if
+ available). Note that these required projects will *not* be installed on
+ the system where the tests are run, but only downloaded to the project's setup
+ directory if they're not already installed locally.
+
+ New in 41.5.0: Deprecated the test command.
+
+.. _test_loader:
+
+``test_loader``
+ If you would like to use a different way of finding tests to run than what
+ setuptools normally uses, you can specify a module name and class name in
+ this argument. The named class must be instantiable with no arguments, and
+ its instances must support the ``loadTestsFromNames()`` method as defined
+ in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
+ pass only one test "name" in the ``names`` argument: the value supplied for
+ the ``test_suite`` argument. The loader you specify may interpret this
+ string in any way it likes, as there are no restrictions on what may be
+ contained in a ``test_suite`` string.
+
+ The module name and class name must be separated by a ``:``. The default
+ value of this argument is ``"setuptools.command.test:ScanningLoader"``. If
+ you want to use the default ``unittest`` behavior, you can specify
+ ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This
+ will prevent automatic scanning of submodules and subpackages.
+
+ The module and class you specify here may be contained in another package,
+ as long as you use the ``tests_require`` option to ensure that the package
+ containing the loader class is available when the ``test`` command is run.
+
+ New in 41.5.0: Deprecated the test command.
+
+``eager_resources``
+ A list of strings naming resources that should be extracted together, if
+ any of them is needed, or if any C extensions included in the project are
+ imported. This argument is only useful if the project will be installed as
+ a zipfile, and there is a need to have all of the listed resources be
+ extracted to the filesystem *as a unit*. Resources listed here
+ should be "/"-separated paths, relative to the source root, so to list a
+ resource ``foo.png`` in package ``bar.baz``, you would include the string
+ ``bar/baz/foo.png`` in this argument.
+
+ If you only need to obtain resources one at a time, or you don't have any C
+ extensions that access other files in the project (such as data files or
+ shared libraries), you probably do NOT need this argument and shouldn't
+ mess with it. For more details on how this argument works, see the section
+ below on :ref:`Automatic Resource Extraction`.
+
+``project_urls``
+ An arbitrary map of URL names to hyperlinks, allowing more extensible
+ documentation of where various resources can be found than the simple
+ ``url`` and ``download_url`` options provide.
diff --git a/docs/userguide/miscellaneous.rst b/docs/userguide/miscellaneous.rst
new file mode 100644
index 0000000..5fd2f0a
--- /dev/null
+++ b/docs/userguide/miscellaneous.rst
@@ -0,0 +1,159 @@
+.. _Automatic Resource Extraction:
+
+Automatic Resource Extraction
+-----------------------------
+
+If you are using tools that expect your resources to be "real" files, or your
+project includes non-extension native libraries or other files that your C
+extensions expect to be able to access, you may need to list those files in
+the ``eager_resources`` argument to ``setup()``, so that the files will be
+extracted together, whenever a C extension in the project is imported.
+
+This is especially important if your project includes shared libraries *other*
+than distutils-built C extensions, and those shared libraries use file
+extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
+extensions that setuptools 0.6a8 and higher automatically detects as shared
+libraries and adds to the ``native_libs.txt`` file for you. Any shared
+libraries whose names do not end with one of those extensions should be listed
+as ``eager_resources``, because they need to be present in the filesystem when
+he C extensions that link to them are used.
+
+The ``pkg_resources`` runtime for compressed packages will automatically
+extract *all* C extensions and ``eager_resources`` at the same time, whenever
+*any* C extension or eager resource is requested via the ``resource_filename()``
+API. (C extensions are imported using ``resource_filename()`` internally.)
+This ensures that C extensions will see all of the "real" files that they
+expect to see.
+
+Note also that you can list directory resource names in ``eager_resources`` as
+well, in which case the directory's contents (including subdirectories) will be
+extracted whenever any C extension or eager resource is requested.
+
+Please note that if you're not sure whether you need to use this argument, you
+don't! It's really intended to support projects with lots of non-Python
+dependencies and as a last resort for crufty projects that can't otherwise
+handle being compressed. If your package is pure Python, Python plus data
+files, or Python plus C, you really don't need this. You've got to be using
+either C or an external program that needs "real" files in your project before
+there's any possibility of ``eager_resources`` being relevant to your project.
+
+Defining Additional Metadata
+----------------------------
+
+Some extensible applications and frameworks may need to define their own kinds
+of metadata to include in eggs, which they can then access using the
+``pkg_resources`` metadata APIs. Ordinarily, this is done by having plugin
+developers include additional files in their ``ProjectName.egg-info``
+directory. However, since it can be tedious to create such files by hand, you
+may want to create a distutils extension that will create the necessary files
+from arguments to ``setup()``, in much the same way that ``setuptools`` does
+for many of the ``setup()`` arguments it adds. See the section below on
+:ref:`Creating ``distutils\`\` Extensions` for more details, especially the
+subsection on :ref:`Adding new EGG-INFO Files`.
+
+Setting the ``zip_safe`` flag
+-----------------------------
+
+For some use cases (such as bundling as part of a larger application), Python
+packages may be run directly from a zip file.
+Not all packages, however, are capable of running in compressed form, because
+they may expect to be able to access either source code or data files as
+normal operating system files. So, ``setuptools`` can install your project
+as a zipfile or a directory, and its default choice is determined by the
+project's ``zip_safe`` flag.
+
+You can pass a True or False value for the ``zip_safe`` argument to the
+``setup()`` function, or you can omit it. If you omit it, the ``bdist_egg``
+command will analyze your project's contents to see if it can detect any
+conditions that would prevent it from working in a zipfile. It will output
+notices to the console about any such conditions that it finds.
+
+Currently, this analysis is extremely conservative: it will consider the
+project unsafe if it contains any C extensions or datafiles whatsoever. This
+does *not* mean that the project can't or won't work as a zipfile! It just
+means that the ``bdist_egg`` authors aren't yet comfortable asserting that
+the project *will* work. If the project contains no C or data files, and does
+no ``__file__`` or ``__path__`` introspection or source code manipulation, then
+there is an extremely solid chance the project will work when installed as a
+zipfile. (And if the project uses ``pkg_resources`` for all its data file
+access, then C extensions and other data files shouldn't be a problem at all.
+See the :ref:`Accessing Data Files at Runtime` section above for more information.)
+
+However, if ``bdist_egg`` can't be *sure* that your package will work, but
+you've checked over all the warnings it issued, and you are either satisfied it
+*will* work (or if you want to try it for yourself), then you should set
+``zip_safe`` to ``True`` in your ``setup()`` call. If it turns out that it
+doesn't work, you can always change it to ``False``, which will force
+``setuptools`` to install your project as a directory rather than as a zipfile.
+
+In the future, as we gain more experience with different packages and become
+more satisfied with the robustness of the ``pkg_resources`` runtime, the
+"zip safety" analysis may become less conservative. However, we strongly
+recommend that you determine for yourself whether your project functions
+correctly when installed as a zipfile, correct any problems if you can, and
+then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
+flag, so that it will not be necessary for ``bdist_egg`` to try to guess
+whether your project can work as a zipfile.
+
+
+.. _Controlling files in the distribution:
+
+Controlling files in the distribution
+-------------------------------------
+
+For the most common use cases, ``setuptools`` will automatically find out which
+files are necessary for distributing the package.
+This includes all :term:`pure Python modules <Pure Module>` in the
+``py_modules`` or ``packages`` configuration, and the C sources (but not C
+headers) listed as part of extensions when creating a :term:`Source
+Distribution (or "sdist")`.
+
+However, when building more complex packages (e.g. packages that include
+non-Python files, or that need to use custom C headers), you might find that
+not all files present in your project folder are included in package
+:term:`distribution archive <Distribution Package>`.
+
+In these situations you can use a ``setuptools``
+:ref:`plugin <Adding Support for Revision Control Systems>`,
+such as :pypi:`setuptools-scm` or :pypi:`setuptools-svn` to automatically
+include all files tracked by your Revision Control System into the ``sdist``.
+
+.. _Using MANIFEST.in:
+
+Alternatively, if you need finer control, you can add a ``MANIFEST.in`` file at
+the root of your project.
+This file contains instructions that tell ``setuptools`` which files exactly
+should be part of the ``sdist`` (or not).
+A comprehensive guide to ``MANIFEST.in`` syntax is available at the
+:doc:`PyPA's Packaging User Guide <PyPUG:guides/using-manifest-in>`.
+
+Once the correct files are present in the ``sdist``, they can then be used by
+binary extensions during the build process, or included in the final
+:term:`wheel <Wheel>` [#build-process]_ if you configure ``setuptools`` with
+``include_package_data=True``.
+
+.. important::
+ Please note that, when using ``include_package_data=True``, only files **inside
+ the package directory** are included in the final ``wheel``, by default.
+
+ So for example, if you create a :term:`Python project <Project>` that uses
+ :pypi:`setuptools-scm` and have a ``tests`` directory outside of the package
+ folder, the ``tests`` directory will be present in the ``sdist`` but not in the
+ ``wheel`` [#wheel-vs-sdist]_.
+
+ See :doc:`/userguide/datafiles` for more information.
+
+----
+
+.. [#build-process]
+ You can think about the build process as two stages: first the ``sdist``
+ will be created and then the ``wheel`` will be produced from that ``sdist``.
+
+.. [#wheel-vs-sdist]
+ This happens because the ``sdist`` can contain files that are useful during
+ development or the build process itself, but not in runtime (e.g. tests,
+ docs, examples, etc...).
+ The ``wheel``, on the other hand, is a file format that has been optimized
+ and is ready to be unpacked into a running installation of Python or
+ :term:`Virtual Environment`.
+ Therefore it only contains items that are required during runtime.
diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
new file mode 100644
index 0000000..ee8e983
--- /dev/null
+++ b/docs/userguide/package_discovery.rst
@@ -0,0 +1,576 @@
+.. _`package_discovery`:
+
+========================================
+Package Discovery and Namespace Package
+========================================
+
+.. note::
+ a full specification for the keyword supplied to ``setup.cfg`` or
+ ``setup.py`` can be found at :doc:`keywords reference <keywords>`
+
+.. note::
+ the examples provided here are only to demonstrate the functionality
+ introduced. More metadata and options arguments need to be supplied
+ if you want to replicate them on your system. If you are completely
+ new to setuptools, the :doc:`quickstart section <quickstart>` is a good
+ place to start.
+
+``Setuptools`` provide powerful tools to handle package discovery, including
+support for namespace package.
+
+Normally, you would specify the package to be included manually in the following manner:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ #...
+ packages =
+ mypkg1
+ mypkg2
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ packages=['mypkg1', 'mypkg2']
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ # ...
+ [tool.setuptools]
+ packages = ["mypkg1", "mypkg2"]
+ # ...
+
+
+If your packages are not in the root of the repository you also need to
+configure ``package_dir``:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ # ...
+ package_dir =
+ = src
+ # directory containing all the packages (e.g. src/mypkg1, src/mypkg2)
+ # OR
+ package_dir =
+ mypkg1 = lib1
+ # mypkg1.mod corresponds to lib1/mod.py
+ # mypkg1.subpkg.mod corresponds to lib1/subpkg/mod.py
+ mypkg2 = lib2
+ # mypkg2.mod corresponds to lib2/mod.py
+ mypkg2.subpkg = lib3
+ # mypkg2.subpkg.mod corresponds to lib3/mod.py
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ package_dir = {"": "src"}
+ # directory containing all the packages (e.g. src/mypkg1, src/mypkg2)
+ )
+
+ # OR
+
+ setup(
+ # ...
+ package_dir = {
+ "mypkg1": "lib1", # mypkg1.mod corresponds to lib1/mod.py
+ # mypkg1.subpkg.mod corresponds to lib1/subpkg/mod.py
+ "mypkg2": "lib2", # mypkg2.mod corresponds to lib2/mod.py
+ "mypkg2.subpkg": "lib3" # mypkg2.subpkg.mod corresponds to lib3/mod.py
+ # ...
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [tool.setuptools]
+ # ...
+ package-dir = {"" = "src"}
+ # directory containing all the packages (e.g. src/mypkg1, src/mypkg2)
+
+ # OR
+
+ [tool.setuptools.package-dir]
+ mypkg1 = "lib1"
+ # mypkg1.mod corresponds to lib1/mod.py
+ # mypkg1.subpkg.mod corresponds to lib1/subpkg/mod.py
+ mypkg2 = "lib2"
+ # mypkg2.mod corresponds to lib2/mod.py
+ "mypkg2.subpkg" = "lib3"
+ # mypkg2.subpkg.mod corresponds to lib3/mod.py
+ # ...
+
+This can get tiresome really quickly. To speed things up, you can rely on
+setuptools automatic discovery, or use the provided tools, as explained in
+the following sections.
+
+
+.. _auto-discovery:
+
+Automatic discovery
+===================
+
+.. warning:: Automatic discovery is an **experimental** feature and might change
+ (or be completely removed) in the future.
+ See :ref:`custom-discovery` for a stable way of configuring ``setuptools``.
+
+By default ``setuptools`` will consider 2 popular project layouts, each one with
+its own set of advantages and disadvantages [#layout1]_ [#layout2]_ as
+discussed in the following sections.
+
+Setuptools will automatically scan your project directory looking for these
+layouts and try to guess the correct values for the :ref:`packages <declarative
+config>` and :doc:`py_modules </references/keywords>` configuration.
+
+.. important::
+ Automatic discovery will **only** be enabled if you **don't** provide any
+ configuration for ``packages`` and ``py_modules``.
+ If at least one of them is explicitly set, automatic discovery will not take place.
+
+ **Note**: specifying ``ext_modules`` might also prevent auto-discover from
+ taking place, unless your opt into :doc:`pyproject_config` (which will
+ disable the backward compatible behaviour).
+
+.. _src-layout:
+
+src-layout
+----------
+The project should contain a ``src`` directory under the project root and
+all modules and packages meant for distribution are placed inside this
+directory::
+
+ project_root_directory
+ ├── pyproject.toml
+ ├── setup.cfg # or setup.py
+ ├── ...
+ └── src/
+ └── mypkg/
+ ├── __init__.py
+ ├── ...
+ └── mymodule.py
+
+This layout is very handy when you wish to use automatic discovery,
+since you don't have to worry about other Python files or folders in your
+project root being distributed by mistake. In some circumstances it can be
+also less error-prone for testing or when using :pep:`420`-style packages.
+On the other hand you cannot rely on the implicit ``PYTHONPATH=.`` to fire
+up the Python REPL and play with your package (you will need an
+`editable install`_ to be able to do that).
+
+.. _flat-layout:
+
+flat-layout
+-----------
+*(also known as "adhoc")*
+
+The package folder(s) are placed directly under the project root::
+
+ project_root_directory
+ ├── pyproject.toml
+ ├── setup.cfg # or setup.py
+ ├── ...
+ └── mypkg/
+ ├── __init__.py
+ ├── ...
+ └── mymodule.py
+
+This layout is very practical for using the REPL, but in some situations
+it can be can be more error-prone (e.g. during tests or if you have a bunch
+of folders or Python files hanging around your project root)
+
+To avoid confusion, file and folder names that are used by popular tools (or
+that correspond to well-known conventions, such as distributing documentation
+alongside the project code) are automatically filtered out in the case of
+*flat-layout*:
+
+.. autoattribute:: setuptools.discovery.FlatLayoutPackageFinder.DEFAULT_EXCLUDE
+
+.. autoattribute:: setuptools.discovery.FlatLayoutModuleFinder.DEFAULT_EXCLUDE
+
+.. warning::
+ If you are using auto-discovery with *flat-layout*, ``setuptools`` will
+ refuse to create :term:`distribution archives <Distribution Package>` with
+ multiple top-level packages or modules.
+
+ This is done to prevent common errors such as accidentally publishing code
+ not meant for distribution (e.g. maintenance-related scripts).
+
+ Users that purposefully want to create multi-package distributions are
+ advised to use :ref:`custom-discovery` or the ``src-layout``.
+
+There is also a handy variation of the *flat-layout* for utilities/libraries
+that can be implemented with a single Python file:
+
+single-module distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A standalone module is placed directly under the project root, instead of
+inside a package folder::
+
+ project_root_directory
+ ├── pyproject.toml
+ ├── setup.cfg # or setup.py
+ ├── ...
+ └── single_file_lib.py
+
+
+.. _custom-discovery:
+
+Custom discovery
+================
+
+If the automatic discovery does not work for you
+(e.g., you want to *include* in the distribution top-level packages with
+reserved names such as ``tasks``, ``example`` or ``docs``, or you want to
+*exclude* nested packages that would be otherwise included), you can use
+the provided tools for package discovery:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ packages = find:
+ #or
+ packages = find_namespace:
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ from setuptools import find_packages
+ # or
+ from setuptools import find_namespace_packages
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ # ...
+ [tool.setuptools.packages]
+ find = {} # Scanning implicit namespaces is active by default
+ # OR
+ find = {namespace = false} # Disable implicit namespaces
+
+
+Finding simple packages
+-----------------------
+Let's start with the first tool. ``find:`` (``find_packages()``) takes a source
+directory and two lists of package name patterns to exclude and include, and
+then return a list of ``str`` representing the packages it could find. To use
+it, consider the following directory::
+
+ mypkg
+ ├── setup.cfg # and/or setup.py, pyproject.toml
+ └── src
+ ├── pkg1
+ │ └── __init__.py
+ ├── pkg2
+ │ └── __init__.py
+ ├── aditional
+ │ └── __init__.py
+ └── pkg
+ └── namespace
+ └── __init__.py
+
+To have setuptools to automatically include packages found
+in ``src`` that starts with the name ``pkg`` and not ``additional``:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ packages = find:
+ package_dir =
+ =src
+
+ [options.packages.find]
+ where = src
+ include = pkg*
+ exclude = additional
+
+ .. note::
+ ``pkg`` does not contain an ``__init__.py`` file, therefore
+ ``pkg.namespace`` is ignored by ``find:`` (see ``find_namespace:`` below).
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ packages=find_packages(
+ where='src',
+ include=['pkg*'],
+ exclude=['additional'],
+ ),
+ package_dir={"": "src"}
+ # ...
+ )
+
+
+ .. note::
+ ``pkg`` does not contain an ``__init__.py`` file, therefore
+ ``pkg.namespace`` is ignored by ``find_packages()``
+ (see ``find_namespace_packages()`` below).
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [tool.setuptools.packages.find]
+ where = ["src"]
+ include = ["pkg*"]
+ exclude = ["additional"]
+ namespaces = false
+
+ .. note::
+ When using ``tool.setuptools.packages.find`` in ``pyproject.toml``,
+ setuptools will consider :pep:`implicit namespaces <420>` by default when
+ scanning your project directory.
+ To avoid ``pkg.namespace`` from being added to your package list
+ you can set ``namespaces = false``. This will prevent any folder
+ without an ``__init__.py`` file from being scanned.
+
+.. important::
+ ``include`` and ``exclude`` accept strings representing :mod:`glob` patterns.
+ These patterns should match the **full** name of the Python module (as if it
+ was written in an ``import`` statement).
+
+ For example if you have ``util`` pattern, it will match
+ ``util/__init__.py`` but not ``util/files/__init__.py``.
+
+ The fact that the parent package is matched by the pattern will not dictate
+ if the submodule will be included or excluded from the distribution.
+ You will need to explicitly add a wildcard (e.g. ``util*``)
+ if you want the pattern to also match submodules.
+
+.. _Namespace Packages:
+
+Finding namespace packages
+--------------------------
+``setuptools`` provides the ``find_namespace:`` (``find_namespace_packages()``)
+which behaves similarly to ``find:`` but works with namespace package.
+
+Before diving in, it is important to have a good understanding of what
+:pep:`namespace packages <420>` are. Here is a quick recap.
+
+When you have two packages organized as follows:
+
+.. code-block:: bash
+
+ /Users/Desktop/timmins/foo/__init__.py
+ /Library/timmins/bar/__init__.py
+
+If both ``Desktop`` and ``Library`` are on your ``PYTHONPATH``, then a
+namespace package called ``timmins`` will be created automatically for you when
+you invoke the import mechanism, allowing you to accomplish the following:
+
+.. code-block:: pycon
+
+ >>> import timmins.foo
+ >>> import timmins.bar
+
+as if there is only one ``timmins`` on your system. The two packages can then
+be distributed separately and installed individually without affecting the
+other one.
+
+Now, suppose you decide to package the ``foo`` part for distribution and start
+by creating a project directory organized as follows::
+
+ foo
+ ├── setup.cfg # and/or setup.py, pyproject.toml
+ └── src
+ └── timmins
+ └── foo
+ └── __init__.py
+
+If you want the ``timmins.foo`` to be automatically included in the
+distribution, then you will need to specify:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ package_dir =
+ =src
+ packages = find_namespace:
+
+ [options.packages.find]
+ where = src
+
+ ``find:`` won't work because timmins doesn't contain ``__init__.py``
+ directly, instead, you have to use ``find_namespace:``.
+
+ You can think of ``find_namespace:`` as identical to ``find:`` except it
+ would count a directory as a package even if it doesn't contain ``__init__.py``
+ file directly.
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ packages=find_namespace_packages(where='src'),
+ package_dir={"": "src"}
+ # ...
+ )
+
+ When you use ``find_packages()``, all directories without an
+ ``__init__.py`` file will be disconsidered.
+ On the other hand, ``find_namespace_packages()`` will scan all
+ directories.
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [tool.setuptools.packages.find]
+ where = ["src"]
+
+ When using ``tool.setuptools.packages.find`` in ``pyproject.toml``,
+ setuptools will consider :pep:`implicit namespaces <420>` by default when
+ scanning your project directory.
+
+After installing the package distribution, ``timmins.foo`` would become
+available to your interpreter.
+
+.. warning::
+ Please have in mind that ``find_namespace:`` (setup.cfg),
+ ``find_namespace_packages()`` (setup.py) and ``find`` (pyproject.toml) will
+ scan **all** folders that you have in your project directory if you use a
+ :ref:`flat-layout`.
+
+ If used naïvely, this might result in unwanted files being added to your
+ final wheel. For example, with a project directory organized as follows::
+
+ foo
+ ├── docs
+ │ └── conf.py
+ ├── timmins
+ │ └── foo
+ │ └── __init__.py
+ └── tests
+ └── tests_foo
+ └── __init__.py
+
+ final users will end up installing not only ``timmins.foo``, but also
+ ``docs`` and ``tests.tests_foo``.
+
+ A simple way to fix this is to adopt the aforementioned :ref:`src-layout`,
+ or make sure to properly configure the ``include`` and/or ``exclude``
+ accordingly.
+
+.. tip::
+ After :ref:`building your package <building>`, you can have a look if all
+ the files are correct (nothing missing or extra), by running the following
+ commands:
+
+ .. code-block:: bash
+
+ tar tf dist/*.tar.gz
+ unzip -l dist/*.whl
+
+ This requires the ``tar`` and ``unzip`` to be installed in your OS.
+ On Windows you can also use a GUI program such as 7zip_.
+
+
+Legacy Namespace Packages
+=========================
+The fact you can create namespace package so effortlessly above is credited
+to `PEP 420 <https://www.python.org/dev/peps/pep-0420/>`_. It use to be more
+cumbersome to accomplish the same result. Historically, there were two methods
+to create namespace packages. One is the ``pkg_resources`` style supported by
+``setuptools`` and the other one being ``pkgutils`` style offered by
+``pkgutils`` module in Python. Both are now considered deprecated despite the
+fact they still linger in many existing packages. These two differ in many
+subtle yet significant aspects and you can find out more on `Python packaging
+user guide <https://packaging.python.org/guides/packaging-namespace-packages/>`_
+
+
+``pkg_resource`` style namespace package
+----------------------------------------
+This is the method ``setuptools`` directly supports. Starting with the same
+layout, there are two pieces you need to add to it. First, an ``__init__.py``
+file directly under your namespace package directory that contains the
+following:
+
+.. code-block:: python
+
+ __import__("pkg_resources").declare_namespace(__name__)
+
+And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ namespace_packages = timmins
+
+.. tab:: setup.py
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ namespace_packages=['timmins']
+ )
+
+And your directory should look like this
+
+.. code-block:: bash
+
+ foo
+ ├── setup.cfg # and/or setup.py, pyproject.toml
+ └── src
+ └── timmins
+ ├── __init__.py
+ └── foo
+ └── __init__.py
+
+Repeat the same for other packages and you can achieve the same result as
+the previous section.
+
+``pkgutil`` style namespace package
+-----------------------------------
+This method is almost identical to the ``pkg_resource`` except that the
+``namespace_packages`` declaration is omitted and the ``__init__.py``
+file contains the following:
+
+.. code-block:: python
+
+ __path__ = __import__('pkgutil').extend_path(__path__, __name__)
+
+The project layout remains the same and ``setup.cfg`` remains the same.
+
+
+----
+
+
+.. [#experimental]
+ Support for specifying package metadata and build configuration options via
+ ``pyproject.toml`` is experimental and might change (or be completely
+ removed) in the future. See :doc:`/userguide/pyproject_config`.
+.. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
+.. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/
+
+.. _editable install: https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs
+.. _7zip: https://www.7-zip.org
diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst
new file mode 100644
index 0000000..47c4511
--- /dev/null
+++ b/docs/userguide/pyproject_config.rst
@@ -0,0 +1,218 @@
+.. _pyproject.toml config:
+
+-----------------------------------------------------
+Configuring setuptools using ``pyproject.toml`` files
+-----------------------------------------------------
+
+.. note:: New in 61.0.0 (**experimental**)
+
+.. warning::
+ Support for declaring :doc:`project metadata
+ <PyPUG:specifications/declaring-project-metadata>` or configuring
+ ``setuptools`` via ``pyproject.toml`` files is still experimental and might
+ change (or be removed) in future releases.
+
+.. important::
+ For the time being, ``pip`` still might require a ``setup.py`` file
+ to support :doc:`editable installs <pip:cli/pip_install>`.
+
+ A simple script will suffice, for example:
+
+ .. code-block:: python
+
+ from setuptools import setup
+
+ setup()
+
+Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as
+a standard way of specifying *project metadata*.
+``Setuptools`` has adopted this standard and will use the information contained
+in this file as an input in the build process.
+
+The example below illustrates how to write a ``pyproject.toml`` file that can
+be used with ``setuptools``. It contains two TOML tables (identified by the
+``[table-header]`` syntax): ``build-system`` and ``project``.
+The ``build-system`` table is used to tell the build frontend (e.g.
+:pypi:`build` or :pypi:`pip`) to use ``setuptools`` and any other plugins (e.g.
+``setuptools-scm``) to build the package.
+The ``project`` table contains metadata fields as described by
+:doc:`PyPUG:specifications/declaring-project-metadata` guide.
+
+.. _example-pyproject-config:
+
+.. code-block:: toml
+
+ [build-system]
+ requires = ["setuptools", "setuptools-scm"]
+ build-backend = "setuptools.build_meta"
+
+ [project]
+ name = "my_package"
+ description = "My package description"
+ readme = "README.rst"
+ keywords = ["one", "two"]
+ license = {text = "BSD 3-Clause License"}
+ classifiers = [
+ "Framework :: Django",
+ "Programming Language :: Python :: 3",
+ ]
+ dependencies = [
+ "requests",
+ 'importlib-metadata; python_version<"3.8"',
+ ]
+ dynamic = ["version"]
+
+ [project.optional-dependencies]
+ pdf = ["ReportLab>=1.2", "RXP"]
+ rest = ["docutils>=0.3", "pack ==1.1, ==1.3"]
+
+ [project.scripts]
+ my-script = "my_package.module:function"
+
+
+.. _setuptools-table:
+
+Setuptools-specific configuration
+=================================
+
+While the standard ``project`` table in the ``pyproject.toml`` file covers most
+of the metadata used during the packaging process, there are still some
+``setuptools``-specific configurations that can be set by users that require
+customization.
+These configurations are completely optional and probably can be skipped when
+creating simple packages.
+They are equivalent to the :doc:`/references/keywords` used by the ``setup.py``
+file, and can be set via the ``tool.setuptools`` table:
+
+========================= =========================== =========================
+Key Value Type (TOML) Notes
+========================= =========================== =========================
+``platforms`` array
+``zip-safe`` boolean If not specified, ``setuptools`` will try to guess
+ a reasonable default for the package
+``eager-resources`` array
+``py-modules`` array See tip below
+``packages`` array or ``find`` directive See tip below
+``package-dir`` table/inline-table Used when explicitly listing ``packages``
+``namespace-packages`` array Not necessary if you use :pep:`420`
+``package-data`` table/inline-table See :doc:`/userguide/datafiles`
+``include-package-data`` boolean ``True`` by default
+``exclude-package-data`` table/inline-table
+``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639`
+ (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``)
+``data-files`` table/inline-table **Deprecated** - check :doc:`/userguide/datafiles`
+``script-files`` array **Deprecated** - equivalent to the ``script`` keyword in ``setup.py``
+ (should be avoided in favour of ``project.scripts``)
+``provides`` array **Ignored by pip**
+``obsoletes`` array **Ignored by pip**
+========================= =========================== =========================
+
+.. note::
+ The `TOML value types`_ ``array`` and ``table/inline-table`` are roughly
+ equivalent to the Python's :obj:`dict` and :obj:`list` data types.
+
+Please note that some of these configurations are deprecated or at least
+discouraged, but they are made available to ensure portability.
+New packages should avoid relying on deprecated/discouraged fields, and
+existing packages should consider alternatives.
+
+.. tip::
+ When both ``py-modules`` and ``packages`` are left unspecified,
+ ``setuptools`` will attempt to perform :ref:`auto-discovery`, which should
+ cover most popular project directory organization techniques, such as the
+ :ref:`src-layout` and the :ref:`flat-layout`.
+
+ However if your project does not follow these conventional layouts
+ (e.g. you want to use a ``flat-layout`` but at the same time have custom
+ directories at the root of your project), you might need to use the ``find``
+ directive [#directives]_ as shown below:
+
+ .. code-block:: toml
+
+ [tool.setuptools.packages.find]
+ where = ["src"] # list of folders that contain the packages (["."] by default)
+ include = ["my_package*"] # package names should match these glob patterns (["*"] by default)
+ exclude = ["my_package.tests*"] # exclude packages matching these glob patterns (empty by default)
+ namespaces = false # to disable scanning PEP 420 namespaces (true by default)
+
+ Note that the glob patterns in the example above need to be matched
+ by the **entire** package name. This means that if you specify ``exclude = ["tests"]``,
+ modules like ``tests.my_package.test1`` will still be included in the distribution
+ (to remove them, add a wildcard to the end of the pattern: ``"tests*"``).
+
+ Alternatively, you can explicitly list the packages in modules:
+
+ .. code-block:: toml
+
+ [tool.setuptools]
+ packages = ["my_package"]
+
+
+.. _dynamic-pyproject-config:
+
+Dynamic Metadata
+================
+
+Note that in the first example of this page we use ``dynamic`` to identify
+which metadata fields are dynamically computed during the build by either
+``setuptools`` itself or the plugins installed via ``build-system.requires``
+(e.g. ``setuptools-scm`` is capable of deriving the current project version
+directly from the ``git`` :wiki:`version control` system).
+
+Currently the following fields can be listed as dynamic: ``version``,
+``classifiers``, ``description``, ``entry-points``, ``scripts``,
+``gui-scripts`` and ``readme``.
+When these fields are expected to be provided by ``setuptools`` a
+corresponding entry is required in the ``tool.setuptools.dynamic`` table
+[#entry-points]_. For example:
+
+.. code-block:: toml
+
+ # ...
+ [project]
+ name = "my_package"
+ dynamic = ["version", "readme"]
+ # ...
+ [tool.setuptools.dynamic]
+ version = {attr = "my_package.VERSION"}
+ readme = {file = ["README.rst", "USAGE.rst"]}
+
+In the ``dynamic`` table, the ``attr`` directive [#directives]_ will read an
+attribute from the given module [#attr]_, while ``file`` will read the contents
+of all given files and concatenate them in a single string.
+
+================= =================== =========================
+Key Directive Notes
+================= =================== =========================
+``version`` ``attr``, ``file``
+``readme`` ``file``
+``description`` ``file`` One-line text
+``classifiers`` ``file`` Multi-line text with one classifier per line
+``entry-points`` ``file`` INI format following :doc:`PyPUG:specifications/entry-points`
+ (``console_scripts`` and ``gui_scripts`` can be included)
+================= =================== =========================
+
+----
+
+.. rubric:: Notes
+
+.. [#entry-points] Dynamic ``scripts`` and ``gui-scripts`` are a special case.
+ When resolving these metadata keys, ``setuptools`` will look for
+ ``tool.setuptool.dynamic.entry-points``, and use the values of the
+ ``console_scripts`` and ``gui_scripts`` :doc:`entry-point groups
+ <PyPUG:specifications/entry-points>`.
+
+.. [#directives] In the context of this document, *directives* are special TOML
+ values that are interpreted differently by ``setuptools`` (usually triggering an
+ associated function). Most of the times they correspond to a special TOML table
+ (or inline-table) with a single top-level key.
+ For example, you can have the ``{find = {where = ["src"], exclude=["tests*"]}}``
+ directive for ``tool.setuptools.packages``, or ``{attr = "mymodule.attr"}``
+ directive for ``tool.setuptools.dynamic.version``.
+
+.. [#attr] ``attr`` is meant to be used when the module attribute is statically
+ specified (e.g. as a string, list or tuple). As a rule of thumb, the
+ attribute should be able to be parsed with :func:`ast.literal_eval`, and
+ should not be modified or re-assigned.
+
+.. _TOML value types: https://toml.io/en/v1.0.0
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
new file mode 100644
index 0000000..5be1078
--- /dev/null
+++ b/docs/userguide/quickstart.rst
@@ -0,0 +1,414 @@
+==========================
+``setuptools`` Quickstart
+==========================
+
+Installation
+============
+
+To install the latest version of setuptools, use::
+
+ pip install --upgrade setuptools
+
+
+Python packaging at a glance
+============================
+The landscape of Python packaging is shifting and ``Setuptools`` has evolved to
+only provide backend support, no longer being the de-facto packaging tool in
+the market. Every python package must provide a ``pyproject.toml`` and specify
+the backend (build system) it wants to use. The distribution can then
+be generated with whatever tool that provides a ``build sdist``-like
+functionality. While this may appear cumbersome, given the added pieces,
+it in fact tremendously enhances the portability of your package. The
+change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general,
+navigate to the :ref:`bottom <packaging-resources>` of this page.
+
+
+Basic Use
+=========
+For basic use of setuptools, you will need a ``pyproject.toml`` with the
+exact following info, which declares you want to use ``setuptools`` to
+package your project:
+
+.. code-block:: toml
+
+ [build-system]
+ requires = ["setuptools"]
+ build-backend = "setuptools.build_meta"
+
+Then, you will need to specify your package information such as metadata,
+contents, dependencies, etc.
+
+Setuptools currently supports configurations from either ``setup.cfg``,
+``setup.py`` or ``pyproject.toml`` [#experimental]_ files, however, configuring new
+projects via ``setup.py`` is discouraged [#setup.py]_.
+
+The following example demonstrates a minimum configuration:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [metadata]
+ name = mypackage
+ version = 0.0.1
+
+ [options]
+ packages = mypackage
+ install_requires =
+ requests
+ importlib-metadata; python_version < "3.8"
+
+ See :doc:`/userguide/declarative_config` for more information.
+
+.. tab:: setup.py [#setup.py]_
+
+ .. code-block:: python
+
+ from setuptools import setup
+
+ setup(
+ name='mypackage',
+ version='0.0.1',
+ packages=['mypackage'],
+ install_requires=[
+ 'requests',
+ 'importlib-metadata; python_version == "3.8"',
+ ],
+ )
+
+ See :doc:`/references/keywords` for more information.
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ name = "mypackage"
+ version = "0.0.1"
+ dependencies = [
+ "requests",
+ 'importlib-metadata; python_version<"3.8"',
+ ]
+
+ See :doc:`/userguide/pyproject_config` for more information.
+
+This is what your project would look like::
+
+ ~/mypackage/
+ pyproject.toml
+ setup.cfg # or setup.py
+ mypackage/__init__.py
+
+Then, you need a builder, such as :std:doc:`PyPA build <pypa-build:index>`
+which you can obtain via ``pip install build``. After downloading it, invoke
+the builder::
+
+ python -m build
+
+You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl``
+file in the ``dist`` directory), which you can upload to PyPI!
+
+Of course, before you release your project to PyPI, you'll want to add a bit
+more information to your setup script to help people find or learn about your
+project. And maybe your project will have grown by then to include a few
+dependencies, and perhaps some data files and scripts. In the next few sections,
+we will walk through the additional but essential information you need
+to specify to properly package your project.
+
+
+Automatic package discovery
+===========================
+For simple projects, it's usually easy enough to manually add packages to
+the ``packages`` keyword in ``setup.cfg``. However, for very large projects,
+it can be a big burden to keep the package list updated.
+Therefore, ``setuptoops`` provides a convenient way to automatically list all
+the packages in your project directory:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ packages = find: # OR `find_namespaces:` if you want to use namespaces
+
+ [options.packages.find] (always `find` even if `find_namespaces:` was used before)
+ # This section is optional
+ # Each entry in this section is optional, and if not specified, the default values are:
+ # `where=.`, `include=*` and `exclude=` (empty).
+ include=mypackage*
+ exclude=mypackage.tests*
+
+.. tab:: setup.py [#setup.py]_
+
+ .. code-block:: python
+
+ from setuptools import find_packages # or find_namespace_packages
+
+ setup(
+ # ...
+ packages=find_packages(
+ where='.',
+ include=['mypackage*'], # ["*"] by default
+ exclude=['mypackage.tests'], # empty by default
+ ),
+ # ...
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ # ...
+ [tool.setuptools.packages]
+ find = {} # Scan the project directory with the default parameters
+
+ # OR
+ [tool.setuptools.packages.find]
+ where = ["src"] # ["."] by default
+ include = ["mypackage*"] # ["*"] by default
+ exclude = ["mypackage.tests*"] # empty by default
+ namespaces = false # true by default
+
+When you pass the above information, alongside other necessary information,
+``setuptools`` walks through the directory specified in ``where`` (omitted
+here as the package resides in the current directory) and filters the packages
+it can find following the ``include`` (defaults to none), then removes
+those that match the ``exclude`` and returns a list of Python packages. The above
+setup also allows you to adopt a ``src/`` layout. For more details and advanced
+use, go to :ref:`package_discovery`.
+
+.. tip::
+ Starting with version 61.0.0, setuptools' automatic discovery capabilities
+ have been improved to detect popular project layouts (such as the
+ :ref:`flat-layout` and :ref:`src-layout`) without requiring any
+ special configuration. Check out our :ref:`reference docs <package_discovery>`
+ for more information, but please keep in mind that this functionality is
+ still considered **experimental** and might change (or even be removed) in
+ future releases.
+
+
+Entry points and automatic script creation
+===========================================
+Setuptools supports automatic creation of scripts upon installation, that runs
+code within your package if you specify them as :doc:`entry points
+<PyPUG:specifications/entry-points>`.
+This is what allows you to run commands like ``pip install`` instead of having
+to type ``python -m pip install``.
+The following configuration examples show how to accomplish this:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options.entry_points]
+ console_scripts =
+ cli-name = mypkg.mymodule:some_func
+
+.. tab:: setup.py [#setup.py]_
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ entry_points={
+ 'console_scripts': [
+ 'cli-name = mypkg.mymodule:some_func',
+ ]
+ }
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project.scripts]
+ cli-name = mypkg.mymodule:some_func
+
+When this project is installed, a ``cli-name`` executable will be created.
+``cli-name`` will invoke the function ``some_func`` in the
+``mypkg/mymodule.py`` file when called by the user.
+Note that you can also use the ``entry-points`` mechanism to advertise
+components between installed packages and implement plugin systems.
+For detailed usage, go to :doc:`entry_point`.
+
+
+Dependency management
+=====================
+Packages built with ``setuptools`` can specify dependencies to be automatically
+installed when the package itself is installed.
+The example below show how to configure this kind of dependencies:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ install_requires =
+ docutils
+ requests <= 0.4
+
+.. tab:: setup.py [#setup.py]_
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ install_requires=["docutils", "requests <= 0.4"],
+ # ...
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "docutils",
+ "requires <= 0.4",
+ ]
+ # ...
+
+Each dependency is represented by a string that can optionally contain version requirements
+(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),
+and/or conditional environment markers, e.g. ``sys_platform == "win32"``
+(see :doc:`PyPUG:specifications/version-specifiers` for more information).
+
+When your project is installed, all of the dependencies not already installed
+will be located (via PyPI), downloaded, built (if necessary), and installed.
+This, of course, is a simplified scenario. You can also specify groups of
+extra dependencies that are not strictly required by your package to work, but
+that will provide additional functionalities.
+For more advanced use, see :doc:`dependency_management`.
+
+
+.. _Including Data Files:
+
+Including Data Files
+====================
+The distutils have traditionally allowed installation of "data files", which
+are placed in a platform-specific location. Setuptools offers three ways to
+specify data files to be included in your packages. For the simplest use, you
+can simply use the ``include_package_data`` keyword:
+
+.. tab:: setup.cfg
+
+ .. code-block:: ini
+
+ [options]
+ include_package_data = True
+
+.. tab:: setup.py [#setup.py]_
+
+ .. code-block:: python
+
+ setup(
+ # ...
+ include_package_data=True,
+ # ...
+ )
+
+.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
+
+ .. code-block:: toml
+
+ [tool.setuptools]
+ include-package-data = true
+ # This is already the default behaviour if your are using
+ # pyproject.toml to configure your build.
+ # You can deactivate that with `include-package-data = false`
+
+This tells setuptools to install any data files it finds in your packages.
+The data files must be specified via the distutils' |MANIFEST.in|_ file
+or automatically added by a :ref:`Revision Control System plugin
+<Adding Support for Revision Control Systems>`.
+For more details, see :doc:`datafiles`.
+
+
+Development mode
+================
+
+``setuptools`` allows you to install a package without copying any files
+to your interpreter directory (e.g. the ``site-packages`` directory).
+This allows you to modify your source code and have the changes take
+effect without you having to rebuild and reinstall.
+Here's how to do it::
+
+ pip install --editable .
+
+This creates a link file in your interpreter site package directory which
+associate with your source code. For more information, see :doc:`development_mode`.
+
+.. tip::
+
+ Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was
+ required to be compatible with development mode. With late
+ versions of pip, ``setup.cfg``-only projects may be installed in this mode.
+
+ If you are experimenting with :doc:`configuration using <pyproject_config>`,
+ or have version of ``pip`` older than v21.1, you might need to keep a
+ ``setup.py`` file in file in your repository if you want to use editable
+ installs (for the time being).
+
+ A simple script will suffice, for example:
+
+ .. code-block:: python
+
+ from setuptools import setup
+
+ setup()
+
+ You can still keep all the configuration in :doc:`setup.cfg </userguide/declarative_config>`
+ (or :doc:`pyproject.toml </userguide/pyproject_config>`).
+
+
+Uploading your package to PyPI
+==============================
+After generating the distribution files, the next step would be to upload your
+distribution so others can use it. This functionality is provided by
+:pypi:`twine` and is documented in the :doc:`Python packaging tutorial
+<PyPUG:tutorials/packaging-projects>`.
+
+
+Transitioning from ``setup.py`` to ``setup.cfg``
+================================================
+To avoid executing arbitrary scripts and boilerplate code, we are transitioning
+into a full-fledged ``setup.cfg`` to declare your package information instead
+of running ``setup()``. This inevitably brings challenges due to a different
+syntax. :doc:`Here </userguide/declarative_config>` we provide a quick guide to
+understanding how ``setup.cfg`` is parsed by ``setuptools`` to ease the pain of
+transition.
+
+.. _packaging-resources:
+
+Resources on Python packaging
+=============================
+Packaging in Python can be hard and is constantly evolving.
+`Python Packaging User Guide <https://packaging.python.org>`_ has tutorials and
+up-to-date references that can help you when it is time to distribute your work.
+
+
+.. |MANIFEST.in| replace:: ``MANIFEST.in``
+.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
+
+
+----
+
+.. rubric:: Notes
+
+.. [#setup.py]
+ The ``setup.py`` file should be used only when custom scripting during the
+ build is necessary.
+ Examples are kept in this document to help people interested in maintaining or
+ contributing to existing packages that use ``setup.py``.
+ Note that you can still keep most of configuration declarative in
+ :doc:`setup.cfg <declarative_config>` or :doc:`pyproject.toml
+ <pyproject_config>` and use ``setup.py`` only for the parts not
+ supported in those files (e.g. C extensions).
+
+.. [#experimental]
+ While the ``[build-system]`` table should always be specified in the
+ ``pyproject.toml`` file, support for adding package metadata and build configuration
+ options via the ``[project]`` and ``[tool.setuptools]`` tables is still
+ experimental and might change (or be completely removed) in future releases.
+ See :doc:`/userguide/pyproject_config`.