[bumpversion]
-current_version = 50.3.0
+current_version = 50.3.1
commit = True
tag = True
- python: 3.9-dev
- <<: *latest_py3
env: TOXENV=docs
+ - arch: ppc64le
+ python: pypy3
+ - arch: ppc64le
+ python: 3.5
+ - &latest_py3_ppc
+ arch: ppc64le
+ python: 3.8
+ - <<: *latest_py3_ppc
+ env: LANG=C
+ - arch: ppc64le
+ python: 3.9-dev
allow_failures:
# suppress failures due to pypa/setuptools#2000
- python: pypy3
- <<: *latest_py3
env: TOXENV=docs
+
cache: pip
+before_install:
+- python tools/ppc64le-patch.py
+
install:
# ensure we have recent pip/setuptools/wheel
+v50.3.1
+-------
+
+* #2093: Finalized doc revamp.
+* #2097: doc: simplify index and group deprecated files
+* #2102: doc overhaul step 2: break main doc into multiple sections
+* #2111: doc overhaul step 3: update userguide
+* #2395: Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
+* #2395: Added an illustrative explanation about the change notes to fragments dir -- by :user:`webknjaz`
+* #2379: Travis CI test suite now tests against PPC64.
+* #2413: Suppress EOF errors (and other exceptions) when importing lib2to3.
+
+
v50.3.0
-------
matrix:
- APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2015
- APPVEYOR_JOB_NAME: "python35-x64-vs2015"
- PYTHON: "C:\\Python35-x64"
+ APPVEYOR_JOB_NAME: "Python38-x64-vs2015"
+ PYTHON: "C:\\Python38-x64"
- APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
- APPVEYOR_JOB_NAME: "python35-x64-vs2017"
- PYTHON: "C:\\Python35-x64"
+ APPVEYOR_JOB_NAME: "Python38-x64-vs2017"
+ PYTHON: "C:\\Python38-x64"
- APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
- APPVEYOR_JOB_NAME: "python35-x64-vs2019"
- PYTHON: "C:\\Python35-x64"
- - APPVEYOR_JOB_NAME: "python36-x64"
- PYTHON: "C:\\Python36-x64"
+ APPVEYOR_JOB_NAME: "Python38-x64-vs2019"
+ PYTHON: "C:\\Python38-x64"
- APPVEYOR_JOB_NAME: "python37-x64"
PYTHON: "C:\\Python37-x64"
+ - APPVEYOR_JOB_NAME: "python36-x64"
+ PYTHON: "C:\\Python36-x64"
+ - APPVEYOR_JOB_NAME: "python35-x64"
+ PYTHON: "C:\\Python35-x64"
+ PYTEST_ADDOPTS: "--cov"
+ TOX_TESTENV_PASSENV: "PYTEST_ADDOPTS"
install:
# symlink python from a directory with a space
- python -m pip install --disable-pip-version-check --upgrade pip setuptools wheel
- pip install --upgrade tox tox-venv virtualenv
- pip freeze --all
- - tox -- --cov
+ - tox
after_test:
- tox -e coverage,codecov
--- /dev/null
+.. _Adding change notes with your PRs:
+
+Adding change notes with your PRs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is very important to maintain a log for news of how
+updating to the new version of the software will affect
+end-users. This is why we enforce collection of the change
+fragment files in pull requests as per `Towncrier philosophy`_.
+
+The idea is that when somebody makes a change, they must record
+the bits that would affect end-users only including information
+that would be useful to them. Then, when the maintainers publish
+a new release, they'll automatically use these records to compose
+a change log for the respective version. It is important to
+understand that including unnecessary low-level implementation
+related details generates noise that is not particularly useful
+to the end-users most of the time. And so such details should be
+recorded in the Git history rather than a changelog.
+
+Alright! So how to add a news fragment?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
+for changelog management.
+To submit a change note about your PR, add a text file into the
+``changelog.d/`` folder. It should contain an
+explanation of what applying this PR will change in the way
+end-users interact with the project. One sentence is usually
+enough but feel free to add as many details as you feel necessary
+for the users to understand what it means.
+
+**Use the past tense** for the text in your fragment because,
+combined with others, it will be a part of the "news digest"
+telling the readers **what changed** in a specific version of
+the library *since the previous version*. You should also use
+reStructuredText syntax for highlighting code (inline or block),
+linking parts of the docs or external sites.
+If you wish to sign your change, feel free to add ``-- by
+:user:`github-username``` at the end (replace ``github-username``
+with your own!).
+
+Finally, name your file following the convention that Towncrier
+understands: it should start with the number of an issue or a
+PR followed by a dot, then add a patch type, like ``change``,
+``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
+need to add more than one fragment, you may add an optional
+sequence number (delimited with another period) between the type
+and the suffix.
+
+In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+where the categories are:
+
+- ``change``: Any backwards compatible code change
+- ``breaking``: Any backwards-compatibility breaking change
+- ``doc``: A change to the documentation
+- ``misc``: Changes internal to the repo like CI, test and build changes
+- ``deprecation``: For deprecations of an existing feature or behavior
+
+A pull request may have more than one of these components, for example
+a code change may introduce a new feature that deprecates an old
+feature, in which case two fragments should be added. It is not
+necessary to make a separate documentation fragment for documentation
+changes accompanying the relevant code changes.
+
+Examples for adding changelog entries to your Pull Requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+File :file:`changelog.d/2395.doc.1.rst`:
+
+.. code-block:: rst
+
+ Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
+
+File :file:`changelog.d/1354.misc.rst`:
+
+.. code-block:: rst
+
+ Added ``towncrier`` for changelog managment -- by :user:`pganssle`
+
+File :file:`changelog.d/2355.change.rst`:
+
+.. code-block:: rst
+
+ When pip is imported as part of a build, leave :py:mod:`distutils`
+ patched -- by :user:`jaraco`
+
+.. tip::
+
+ See :file:`pyproject.toml` for all available categories
+ (``tool.towncrier.type``).
+
+.. _Towncrier philosophy:
+ https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy
'setuptools/tests/mod_with_constant.py',
'setuptools/_distutils',
'_distutils_hack',
+ 'setuptools/extern',
+ 'pkg_resources/extern',
+ 'pkg_resources/tests/data',
+ 'setuptools/_vendor',
+ 'pkg_resources/_vendor',
]
-def pytest_configure(config):
- disable_coverage_on_pypy(config)
-
-
-def disable_coverage_on_pypy(config):
- """
- Coverage makes tests on PyPy unbearably slow, so disable it.
- """
- if '__pypy__' not in sys.builtin_module_names:
- return
-
- # Recommended at pytest-dev/pytest-cov#418
- cov = config.pluginmanager.get_plugin('_cov')
- cov.options.no_cov = True
- if cov.cov_controller:
- cov.cov_controller.pause()
-
-
-if sys.version_info < (3,):
- collect_ignore.append('setuptools/lib2to3_ex.py')
- collect_ignore.append('setuptools/_imp.py')
-
-
if sys.version_info < (3, 6):
+ collect_ignore.append('docs/conf.py') # uses f-strings
collect_ignore.append('pavement.py')
--- /dev/null
+=======================================
+Build System Support
+=======================================
+
+What is it?
+-------------
+
+Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
+
+The traditional ``setuptools`` way of packgaging 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", "wheel"]
+ build-backend = "setuptools.build_meta"
+
+Use ``setuptools``' `declarative config`_ to specify the package information::
+
+ [metadata]
+ name = meowpkg
+ version = 0.0.1
+ description = a package that meows
+
+ [options]
+ packages = find:
+
+Now generate the distribution. Although the PyPA is still working to
+`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
+to build packages, the `pep517 package <https://pypi.org/project/pep517>`_
+provides this functionality. To build the package::
+
+ $ pip install -q pep517
+ $ mkdir dist
+ $ python -m pep517.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
+++ /dev/null
-=======================================
-Build System Support
-=======================================
-
-What is it?
--------------
-
-Python packaging has come `a long way <https://www.bernat.tech/pep-517-518/>`_.
-
-The traditional ``setuptools`` way of packgaging 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", "wheel"]
- build-backend = "setuptools.build_meta"
-
-Use ``setuptools``' `declarative config`_ to specify the package information::
-
- [metadata]
- name = meowpkg
- version = 0.0.1
- description = a package that meows
-
- [options]
- packages = find:
-
-Now generate the distribution. Although the PyPA is still working to
-`provide a recommended tool <https://github.com/pypa/packaging-problems/issues/219>`_
-to build packages, the `pep517 package <https://pypi.org/project/pep517>`_
-provides this functionality. To build the package::
-
- $ pip install -q pep517
- $ mkdir dist
- $ python -m pep517.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
cwd=os.path.join(os.path.dirname(__file__), os.path.pardir),
)
+# -- Project information -----------------------------------------------------
+
+github_url = 'https://github.com'
+github_sponsors_url = f'{github_url}/sponsors'
+
# -- General configuration --
-extensions = ['jaraco.packaging.sphinx', 'rst.linker']
+extensions = [
+ 'sphinx.ext.extlinks', # allows to create custom roles easily
+ 'jaraco.packaging.sphinx',
+ 'rst.linker',
+]
# 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'
-# A list of glob-style patterns that should be excluded
-# when looking for source files.
-exclude_patterns = ['requirements.txt']
-
# 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 extlinks extension ---------------------------------------
+extlinks = {
+ 'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
+}
+
# -- Options for HTML output --
# The theme to use for HTML and HTML Help pages. Major themes that come with
--- /dev/null
+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 49.1.2 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is disabled by default. To enable the use of this copy of distutils when invoking setuptools, set the enviroment variable:
+
+ SETUPTOOLS_USE_DISTUTILS=local
+
+This behavior is planned to become the default.
+
+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.log`` → (no replacement yet)
+
+``distutils.version.*`` → ``packaging.version.*``
+
+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.
--- /dev/null
+============
+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.
+
+Please share your experiences with us! If you encounter difficulty installing
+a package, please contact us via the `distutils mailing list
+<http://mail.python.org/pipermail/distutils-sig/>`_. (Note: please DO NOT send
+private email directly to the author of setuptools; it will be discarded. The
+mailing list is a searchable archive of previously-asked and answered
+questions; you should begin your research there before reporting something as a
+bug -- and then do so via list discussion first.)
+
+(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 documentation as well.)
+
+.. contents:: **Table of Contents**
+
+
+Using "Easy Install"
+====================
+
+
+.. _installation instructions:
+
+Installing "Easy Install"
+-------------------------
+
+Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_
+for download links and basic installation instructions for each of the
+supported platforms.
+
+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
+are installing to Python's primary ``site-packages`` directory. If this is
+not the case, you should consult the section below on `Custom Installation
+Locations`_ before installing. (And, on Windows, you should not use the
+``.exe`` installer when installing to an alternate location.)
+
+Note that ``easy_install`` normally works by downloading files from the
+internet. If you are behind an NTLM-based firewall that prevents Python
+programs from accessing the net directly, you may wish to first install and use
+the `APS proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such
+firewalls in the same way that your web browser(s) do.
+
+(Alternately, if you do not wish easy_install to actually download anything, you
+can restrict it from doing so with the ``--allow-hosts`` option; see the
+sections on `restricting downloads with --allow-hosts`_ and `command-line
+options`_ for more details.)
+
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+If EasyInstall/setuptools appears to install correctly, and you can run the
+``easy_install`` command but it fails with an ``ImportError``, the most likely
+cause is that you installed to a location other than ``site-packages``,
+without taking any of the steps described in the `Custom Installation
+Locations`_ section below. Please see that section and follow the steps to
+make sure that your custom location will work correctly. Then re-install.
+
+Similarly, if you can run ``easy_install``, and it appears to be installing
+packages, but then you can't import them, the most likely issue is that you
+installed EasyInstall correctly but are using it to install packages to a
+non-standard location that hasn't been properly prepared. Again, see the
+section on `Custom Installation Locations`_ for more details.
+
+
+Windows Notes
+~~~~~~~~~~~~~
+
+Installing setuptools will provide an ``easy_install`` command according to
+the techniques described in `Executables and Launchers`_. If the
+``easy_install`` command is not available after installation, that section
+provides details on how to configure Windows to make the commands available.
+
+
+Downloading and Installing a Package
+------------------------------------
+
+For basic use of ``easy_install``, you need only supply the filename or URL of
+a source distribution or .egg file (`Python Egg`__).
+
+__ http://peak.telecommunity.com/DevCenter/PythonEggs
+
+**Example 1**. Install a package by name, searching PyPI for the latest
+version, and automatically downloading, building, and installing it::
+
+ easy_install SQLObject
+
+**Example 2**. Install or upgrade a package by name and version by finding
+links on a given "download page"::
+
+ easy_install -f http://pythonpaste.org/package_index.html SQLObject
+
+**Example 3**. Download a source distribution from a specified URL,
+automatically building and installing it::
+
+ easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
+
+**Example 4**. Install an already-downloaded .egg file::
+
+ easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
+
+**Example 5**. Upgrade an already-installed package to the latest version
+listed on PyPI::
+
+ easy_install --upgrade PyProtocols
+
+**Example 6**. Install a source distribution that's already downloaded and
+extracted in the current directory (New in 0.5a9)::
+
+ easy_install .
+
+**Example 7**. (New in 0.6a1) Find a source distribution or Subversion
+checkout URL for a package, and extract it or check it out to
+``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
+can be examined or edited. (The package will not be installed, but it can
+easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing
+and Viewing Source Packages`_ below for more info.)::
+
+ easy_install --editable --build-directory ~/projects SQLObject
+
+**Example 7**. (New in 0.6.11) Install a distribution within your home dir::
+
+ easy_install --user SQLAlchemy
+
+Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
+"distribution" names), and package+version specifiers. In each case, it will
+attempt to locate the latest available version that meets your criteria.
+
+When downloading or processing downloaded files, Easy Install recognizes
+distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
+.tar.bz2, or .zip. And of course it handles already-built .egg
+distributions as well as ``.win32.exe`` installers built using distutils.
+
+By default, packages are installed to the running Python installation's
+``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
+option to specify an alternative directory, or specify an alternate location
+using distutils configuration files. (See `Configuration Files`_, below.)
+
+By default, any scripts included with the package are installed to the running
+Python installation's standard script installation location. However, if you
+specify an installation directory via the command line or a config file, then
+the default directory for installing scripts will be the same as the package
+installation directory, to ensure that the script will have access to the
+installed package. You can override this using the ``-s`` or ``--script-dir``
+option.
+
+Installed packages are added to an ``easy-install.pth`` file in the install
+directory, so that Python will always use the most-recently-installed version
+of the package. If you would like to be able to select which version to use at
+runtime, you should use the ``-m`` or ``--multi-version`` option.
+
+
+Upgrading a Package
+-------------------
+
+You don't need to do anything special to upgrade a package: just install the
+new version, either by requesting a specific version, e.g.::
+
+ easy_install "SomePackage==2.0"
+
+a version greater than the one you have now::
+
+ easy_install "SomePackage>2.0"
+
+using the upgrade flag, to find the latest available version on PyPI::
+
+ easy_install --upgrade SomePackage
+
+or by using a download page, direct download URL, or package filename::
+
+ easy_install -f http://example.com/downloads ExamplePackage
+
+ easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg
+
+ easy_install my_downloads/ExamplePackage-2.0.tgz
+
+If you're using ``-m`` or ``--multi-version`` , using the ``require()``
+function at runtime automatically selects the newest installed version of a
+package that meets your version criteria. So, installing a newer version is
+the only step needed to upgrade such packages.
+
+If you're installing to a directory on PYTHONPATH, or a configured "site"
+directory (and not using ``-m``), installing a package automatically replaces
+any previous version in the ``easy-install.pth`` file, so that Python will
+import the most-recently installed version by default. So, again, installing
+the newer version is the only upgrade step needed.
+
+If you haven't suppressed script installation (using ``--exclude-scripts`` or
+``-x``), then the upgraded version's scripts will be installed, and they will
+be automatically patched to ``require()`` the corresponding version of the
+package, so that you can use them even if they are installed in multi-version
+mode.
+
+``easy_install`` never actually deletes packages (unless you're installing a
+package with the same name and version number as an existing package), so if
+you want to get rid of older versions of a package, please see `Uninstalling
+Packages`_, below.
+
+
+Changing the Active Version
+---------------------------
+
+If you've upgraded a package, but need to revert to a previously-installed
+version, you can do so like this::
+
+ easy_install PackageName==1.2.3
+
+Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
+If a package matching the requested name and version is not already installed
+in a directory on ``sys.path``, it will be located via PyPI and installed.
+
+If you'd like to switch to the latest installed version of ``PackageName``, you
+can do so like this::
+
+ easy_install PackageName
+
+This will activate the latest installed version. (Note: if you have set any
+``find_links`` via distutils configuration files, those download pages will be
+checked for the latest available version of the package, and it will be
+downloaded and installed if it is newer than your current version.)
+
+Note that changing the active version of a package will install the newly
+active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
+specified.
+
+
+Uninstalling Packages
+---------------------
+
+If you have replaced a package with another version, then you can just delete
+the package(s) you don't need by deleting the PackageName-versioninfo.egg file
+or directory (found in the installation directory).
+
+If you want to delete the currently installed version of a package (or all
+versions of a package), you should first run::
+
+ easy_install -m PackageName
+
+This will ensure that Python doesn't continue to search for a package you're
+planning to remove. After you've done this, you can safely delete the .egg
+files or directories, along with any scripts you wish to remove.
+
+
+Managing Scripts
+----------------
+
+Whenever you install, upgrade, or change versions of a package, EasyInstall
+automatically installs the scripts for the selected package version, unless
+you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in
+the script directory have the same name, they are overwritten.
+
+Thus, you do not normally need to manually delete scripts for older versions of
+a package, unless the newer version of the package does not include a script
+of the same name. However, if you are completely uninstalling a package, you
+may wish to manually delete its scripts.
+
+EasyInstall's default behavior means that you can normally only run scripts
+from one version of a package at a time. If you want to keep multiple versions
+of a script available, however, you can simply use the ``--multi-version`` or
+``-m`` option, and rename the scripts that EasyInstall creates. This works
+because EasyInstall installs scripts as short code stubs that ``require()`` the
+matching version of the package the script came from, so renaming the script
+has no effect on what it executes.
+
+For example, suppose you want to use two versions of the ``rst2html`` tool
+provided by the `docutils <http://docutils.sf.net/>`_ package. You might
+first install one version::
+
+ easy_install -m docutils==0.3.9
+
+then rename the ``rst2html.py`` to ``r2h_039``, and install another version::
+
+ easy_install -m docutils==0.3.10
+
+This will create another ``rst2html.py`` script, this one using docutils
+version 0.3.10 instead of 0.3.9. You now have two scripts, each using a
+different version of the package. (Notice that we used ``-m`` for both
+installations, so that Python won't lock us out of using anything but the most
+recently-installed version of the package.)
+
+
+Executables and Launchers
+-------------------------
+
+On Unix systems, scripts are installed with as natural files with a "#!"
+header and no extension and they launch under the Python version indicated in
+the header.
+
+On Windows, there is no mechanism to "execute" files without extensions, so
+EasyInstall provides two techniques to mirror the Unix behavior. The behavior
+is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be
+"executable" (default) or "natural".
+
+Regardless of the technique used, the script(s) will be installed to a Scripts
+directory (by default in the Python installation directory). It is recommended
+for EasyInstall that you ensure this directory is in the PATH environment
+variable. The easiest way to ensure the Scripts directory is in the PATH is
+to run ``Tools\Scripts\win_add2path.py`` from the Python directory.
+
+Note that instead of changing your ``PATH`` to include the Python scripts
+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 control where
+scripts will be installed.
+
+
+Windows Executable Launcher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the "executable" launcher is used, EasyInstall will create a '.exe'
+launcher of the same name beside each installed script (including
+``easy_install`` itself). These small .exe files launch the script of the
+same name using the Python version indicated in the '#!' header.
+
+This behavior is currently default. To force
+the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to "executable".
+
+Natural Script Launcher
+~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall also supports deferring to an external launcher such as
+`pylauncher <https://bitbucket.org/pypa/pylauncher>`_ for launching scripts.
+Enable this experimental functionality by setting the
+``SETUPTOOLS_LAUNCHER`` environment variable to "natural". EasyInstall will
+then install scripts as simple
+scripts with a .pya (or .pyw) extension appended. If these extensions are
+associated with the pylauncher and listed in the PATHEXT environment variable,
+these scripts can then be invoked simply and directly just like any other
+executable. This behavior may become default in a future version.
+
+EasyInstall uses the .pya extension instead of simply
+the typical '.py' extension. This distinct extension is necessary to prevent
+Python
+from treating the scripts as importable modules (where name conflicts exist).
+Current releases of pylauncher do not yet associate with .pya files by
+default, but future versions should do so.
+
+
+Tips & Techniques
+-----------------
+
+Multiple Python Versions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall installs itself under two names:
+``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
+used to install it. Thus, if you install EasyInstall for both Python 3.2 and
+2.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to
+install packages for the respective Python version.
+
+Setuptools also supplies easy_install as a runnable module which may be
+invoked using ``python -m easy_install`` for any Python with Setuptools
+installed.
+
+Restricting Downloads with ``--allow-hosts``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
+EasyInstall will look for links and downloads on. ``--allow-hosts=None``
+prevents downloading altogether. You can also use wildcards, for example
+to restrict downloading to hosts in your own intranet. See the section below
+on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.
+
+By default, there are no host restrictions in effect, but you can change this
+default by editing the appropriate `configuration files`_ and adding:
+
+.. code-block:: ini
+
+ [easy_install]
+ allow_hosts = *.myintranet.example.com,*.python.org
+
+The above example would then allow downloads only from hosts in the
+``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
+command line.
+
+
+Installing on Un-networked Machines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just copy the eggs or source packages you need to a directory on the target
+machine, then use the ``-f`` or ``--find-links`` option to specify that
+directory's location. For example::
+
+ easy_install -H None -f somedir SomePackage
+
+will attempt to install SomePackage using only eggs and source packages found
+in ``somedir`` and disallowing all remote access. You should of course make
+sure you have all of SomePackage's dependencies available in somedir.
+
+If you have another machine of the same operating system and library versions
+(or if the packages aren't platform-specific), you can create the directory of
+eggs using a command like this::
+
+ easy_install -zmaxd somedir SomePackage
+
+This will tell EasyInstall to put zipped eggs or source packages for
+SomePackage and all its dependencies into ``somedir``, without creating any
+scripts or .pth files. You can then copy the contents of ``somedir`` to the
+target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which
+prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
+even if they're installed elsewhere on the machine, and ``-d`` indicates the
+directory to place the eggs in.)
+
+You can also build the eggs from local development packages that were installed
+with the ``setup.py develop`` command, by including the ``-l`` option, e.g.::
+
+ easy_install -zmaxld somedir SomePackage
+
+This will use locally-available source distributions to build the eggs.
+
+
+Packaging Others' Projects As Eggs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Need to distribute a package that isn't published in egg form? You can use
+EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``,
+``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
+``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location
+where you'd like the eggs placed. By placing them in a directory that is
+published to the web, you can then make the eggs available for download, either
+in an intranet or to the internet at large.
+
+If someone distributes a package in the form of a single ``.py`` file, you can
+wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
+So, something like this::
+
+ easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will install the package as an egg, and this::
+
+ easy_install -zmaxd. \
+ -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will create a ``.egg`` file in the current directory.
+
+
+Creating your own Package Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to local directories and the Python Package Index, EasyInstall can
+find download links on most any web page whose URL is given to the ``-f``
+(``--find-links``) option. In the simplest case, you can simply have a web
+page with links to eggs or Python source packages, even an automatically
+generated directory listing (such as the Apache web server provides).
+
+If you are setting up an intranet site for package downloads, you may want to
+configure the target machines to use your download site by default, adding
+something like this to their `configuration files`_:
+
+.. code-block:: ini
+
+ [easy_install]
+ find_links = http://mypackages.example.com/somedir/
+ http://turbogears.org/download/
+ http://peak.telecommunity.com/dist/
+
+As you can see, you can list multiple URLs separated by whitespace, continuing
+on multiple lines if necessary (as long as the subsequent lines are indented.
+
+If you are more ambitious, you can also create an entirely custom package index
+or PyPI mirror. See the ``--index-url`` option under `Command-Line Options`_,
+below, and also the section on `Package Index "API"`_.
+
+
+Password-Protected Sites
+------------------------
+
+If a site you want to download from is password-protected using HTTP "Basic"
+authentication, you can specify your credentials in the URL, like so::
+
+ http://some_userid:some_password@some.example.com/some_path/
+
+You can do this with both index page URLs and direct download URLs. As long
+as any HTML pages read by easy_install use *relative* links to point to the
+downloads, the same user ID and password will be used to do the downloading.
+
+Using .pypirc Credentials
+-------------------------
+
+In additional to supplying credentials in the URL, ``easy_install`` will also
+honor credentials if present in the .pypirc file. Teams maintaining a private
+repository of packages may already have defined access credentials for
+uploading packages according to the distutils documentation. ``easy_install``
+will attempt to honor those if present. Refer to the distutils documentation
+for Python 2.5 or later for details on the syntax.
+
+Controlling Build Options
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall respects standard distutils `Configuration Files`_, so you can use
+them to configure build options for packages that it installs from source. For
+example, if you are on Windows using the MinGW compiler, you can configure the
+default compiler by putting something like this:
+
+.. code-block:: ini
+
+ [build]
+ compiler = mingw32
+
+into the appropriate distutils configuration file. In fact, since this is just
+normal distutils configuration, it will affect any builds using that config
+file, not just ones done by EasyInstall. For example, if you add those lines
+to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
+default compiler for *all* packages you build. See `Configuration Files`_
+below for a list of the standard configuration file locations, and links to
+more documentation on using distutils configuration files.
+
+
+Editing and Viewing Source Packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes a package's source distribution contains additional documentation,
+examples, configuration files, etc., that are not part of its actual code. If
+you want to be able to examine these files, you can use the ``--editable``
+option to EasyInstall, and EasyInstall will look for a source distribution
+or Subversion URL for the package, then download and extract it or check it out
+as a subdirectory of the ``--build-directory`` you specify. If you then wish
+to install the package after editing or configuring it, you can do so by
+rerunning EasyInstall with that directory as the target.
+
+Note that using ``--editable`` stops EasyInstall from actually building or
+installing the package; it just finds, obtains, and possibly unpacks it for
+you. This allows you to make changes to the package if necessary, and to
+either install it in development mode using ``setup.py develop`` (if the
+package uses setuptools, that is), or by running ``easy_install projectdir``
+(where ``projectdir`` is the subdirectory EasyInstall created for the
+downloaded package.
+
+In order to use ``--editable`` (``-e`` for short), you *must* also supply a
+``--build-directory`` (``-b`` for short). The project will be placed in a
+subdirectory of the build directory. The subdirectory will have the same
+name as the project itself, but in all-lowercase. If a file or directory of
+that name already exists, EasyInstall will print an error message and exit.
+
+Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
+You *must* specify project names (and optional version requirements) so that
+EasyInstall knows what directory name(s) to create. If you need to force
+EasyInstall to use a particular URL or filename, you should specify it as a
+``--find-links`` item (``-f`` for short), and then also specify
+the project name, e.g.::
+
+ easy_install -eb ~/projects \
+ -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
+ ctypes==0.9.6
+
+
+Dealing with Installation Conflicts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
+people using older versions of EasyInstall can consult it. As of version
+0.6a11, installation conflicts are handled automatically without deleting the
+old or system-installed packages, and without ignoring the issue. Instead,
+eggs are automatically shifted to the front of ``sys.path`` using special
+code added to the ``easy-install.pth`` file. So, if you are using version
+0.6a11 or better of setuptools, you do not need to worry about conflicts,
+and the following issues do not apply to you.)
+
+EasyInstall installs distributions in a "managed" way, such that each
+distribution can be independently activated or deactivated on ``sys.path``.
+However, packages that were not installed by EasyInstall are "unmanaged",
+in that they usually live all in one directory and cannot be independently
+activated or deactivated.
+
+As a result, if you are using EasyInstall to upgrade an existing package, or
+to install a package with the same name as an existing package, EasyInstall
+will warn you of the conflict. (This is an improvement over ``setup.py
+install``, because the ``distutils`` just install new packages on top of old
+ones, possibly combining two unrelated packages or leaving behind modules that
+have been deleted in the newer version of the package.)
+
+EasyInstall will stop the installation if it detects a conflict
+between an existing, "unmanaged" package, and a module or package in any of
+the distributions you're installing. It will display a list of all of the
+existing files and directories that would need to be deleted for the new
+package to be able to function correctly. To proceed, you must manually
+delete these conflicting files and directories and re-run EasyInstall.
+
+Of course, once you've replaced all of your existing "unmanaged" packages with
+versions managed by EasyInstall, you won't have any more conflicts to worry
+about!
+
+
+Compressed Installation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall tries to install packages in zipped form, if it can. Zipping
+packages can improve Python's overall import performance if you're not using
+the ``--multi-version`` option, because Python processes zipfile entries on
+``sys.path`` much faster than it does directories.
+
+As of version 0.5a9, EasyInstall analyzes packages to determine whether they
+can be safely installed as a zipfile, and then acts on its analysis. (Previous
+versions would not install a package as a zipfile unless you used the
+``--zip-ok`` option.)
+
+The current analysis approach is fairly conservative; it currently looks for:
+
+ * Any use of the ``__file__`` or ``__path__`` variables (which should be
+ replaced with ``pkg_resources`` API calls)
+
+ * Possible use of ``inspect`` functions that expect to manipulate source files
+ (e.g. ``inspect.getsource()``)
+
+ * Top-level modules that might be scripts used with ``python -m`` (Python 2.4)
+
+If any of the above are found in the package being installed, EasyInstall will
+assume that the package cannot be safely run from a zipfile, and unzip it to
+a directory instead. You can override this analysis with the ``-zip-ok`` flag,
+which will tell EasyInstall to install the package as a zipfile anyway. Or,
+you can use the ``--always-unzip`` flag, in which case EasyInstall will always
+unzip, even if its analysis says the package is safe to run as a zipfile.
+
+Normally, however, it is simplest to let EasyInstall handle the determination
+of whether to zip or unzip, and only specify overrides when needed to work
+around a problem. If you find you need to override EasyInstall's guesses, you
+may want to contact the package author and the EasyInstall maintainers, so that
+they can make appropriate changes in future versions.
+
+(Note: If a package uses ``setuptools`` in its setup script, the package author
+has the option to declare the package safe or unsafe for zipped usage via the
+``zip_safe`` argument to ``setup()``. If the package author makes such a
+declaration, EasyInstall believes the package's author and does not perform its
+own analysis. However, your command-line option, if any, will still override
+the package author's choice.)
+
+
+Reference Manual
+================
+
+Configuration Files
+-------------------
+
+(New in 0.4a2)
+
+You may specify default options for EasyInstall using the standard
+distutils configuration files, under the command heading ``easy_install``.
+EasyInstall will look first for a ``setup.cfg`` file in the current directory,
+then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
+and Windows, respectively), and finally a ``distutils.cfg`` file in the
+``distutils`` package directory. Here's a simple example:
+
+.. code-block:: ini
+
+ [easy_install]
+
+ # set the default location to install packages
+ install_dir = /home/me/lib/python
+
+ # Notice that indentation can be used to continue an option
+ # value; this is especially useful for the "--find-links"
+ # option, which tells easy_install to use download links on
+ # these pages before consulting PyPI:
+ #
+ find_links = http://sqlobject.org/
+ http://peak.telecommunity.com/dist/
+
+In addition to accepting configuration for its own options under
+``[easy_install]``, EasyInstall also respects defaults specified for other
+distutils commands. For example, if you don't set an ``install_dir`` for
+``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
+command, this will become EasyInstall's default installation directory. Thus,
+if you are already using distutils configuration files to set default install
+locations, build options, etc., EasyInstall will respect your existing settings
+until and unless you override them explicitly in an ``[easy_install]`` section.
+
+For more information, see also the current Python documentation on the `use and
+location of distutils configuration files <https://docs.python.org/install/index.html#inst-config-files>`_.
+
+Notice that ``easy_install`` will use the ``setup.cfg`` from the current
+working directory only if it was triggered from ``setup.py`` through the
+``install_requires`` option. The standalone command will not use that file.
+
+Command-Line Options
+--------------------
+
+``--zip-ok, -z``
+ Install all packages as zip files, even if they are marked as unsafe for
+ running as a zipfile. This can be useful when EasyInstall's analysis
+ of a non-setuptools package is too conservative, but keep in mind that
+ the package may not work correctly. (Changed in 0.5a9; previously this
+ option was required in order for zipped installation to happen at all.)
+
+``--always-unzip, -Z``
+ Don't install any packages as zip files, even if the packages are marked
+ as safe for running as a zipfile. This can be useful if a package does
+ something unsafe, but not in a way that EasyInstall can easily detect.
+ EasyInstall's default analysis is currently very conservative, however, so
+ you should only use this option if you've had problems with a particular
+ package, and *after* reporting the problem to the package's maintainer and
+ to the EasyInstall maintainers.
+
+ (Note: the ``-z/-Z`` options only affect the installation of newly-built
+ or downloaded packages that are not already installed in the target
+ directory; if you want to convert an existing installed version from
+ zipped to unzipped or vice versa, you'll need to delete the existing
+ version first, and re-run EasyInstall.)
+
+``--multi-version, -m``
+ "Multi-version" mode. Specifying this option prevents ``easy_install`` from
+ adding an ``easy-install.pth`` entry for the package being installed, and
+ if an entry for any version the package already exists, it will be removed
+ upon successful installation. 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``. This can be as
+ simple as::
+
+ from pkg_resources import require
+ require("SomePackage", "OtherPackage", "MyPackage")
+
+ which will put the latest installed version of the specified packages on
+ ``sys.path`` for you. (For more advanced uses, like selecting specific
+ versions and enabling optional dependencies, see the ``pkg_resources`` API
+ doc.)
+
+ Changed in 0.6a10: this option is no longer silently enabled when
+ installing to a non-PYTHONPATH, non-"site" directory. You must always
+ explicitly use this option if you want it to be active.
+
+``--upgrade, -U`` (New in 0.5a4)
+ By default, EasyInstall only searches online if a project/version
+ requirement can't be met by distributions already installed
+ on sys.path or the installation directory. However, if you supply the
+ ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
+ index and ``--find-links`` URLs before selecting a version to install. In
+ this way, you can force EasyInstall to use the latest available version of
+ any package it installs (subject to any version requirements that might
+ exclude such later versions).
+
+``--install-dir=DIR, -d DIR``
+ Set the installation directory. It is up to you to ensure that this
+ directory is on ``sys.path`` at runtime, and to use
+ ``pkg_resources.require()`` to enable the installed package(s) that you
+ need.
+
+ (New in 0.4a2) 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 would 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 installation directory, as is the
+ ``--prefix`` option.
+
+``--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 install scripts. This is useful if you need to install multiple
+ versions of a package, but do not want to reset the version that will be
+ run by scripts that are already installed.
+
+``--user`` (New in 0.6.11)
+ Use the user-site-packages as specified in :pep:`370`
+ instead of the global site-packages.
+
+``--always-copy, -a`` (New in 0.5a4)
+ Copy all needed distributions to the installation directory, even if they
+ are already present in a directory on sys.path. In older versions of
+ EasyInstall, this was the default behavior, but now you must explicitly
+ request it. By default, EasyInstall will no longer copy such distributions
+ from other sys.path directories to the installation directory, unless you
+ explicitly gave the distribution's filename on the command line.
+
+ Note that as of 0.6a10, using this option excludes "system" and
+ "development" eggs from consideration because they can't be reliably
+ copied. 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 copy of something that's already installed. You will see warning
+ messages for any eggs that EasyInstall skips, before it falls back to an
+ older version or attempts to download a fresh copy.
+
+``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
+ Scan the specified "download pages" or directories for direct links to eggs
+ or other distributions. Any existing file or directory names or direct
+ download URLs are immediately added to EasyInstall's search cache, and any
+ indirect URLs (ones that don't point to eggs or other recognized archive
+ formats) are added to a list of additional places to search for download
+ links. As soon as EasyInstall has to go online to find a package (either
+ because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
+ used), the specified URLs will be downloaded and scanned for additional
+ direct links.
+
+ Eggs and archives found by way of ``--find-links`` are only downloaded if
+ they are needed to meet a requirement specified on the command line; links
+ to unneeded packages are ignored.
+
+ If all requested packages can be found using links on the specified
+ download pages, the Python Package Index will not be consulted unless you
+ also specified the ``--upgrade`` or ``-U`` option.
+
+ (Note: if you want to refer to a local HTML file containing links, you must
+ use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
+ archive are ignored.)
+
+ You may specify multiple URLs or file/directory names with this option,
+ separated by whitespace. Note that on the command line, you will probably
+ have to surround the URL list with quotes, so that it is recognized as a
+ single option value. You can also specify URLs in a configuration file;
+ see `Configuration Files`_, above.
+
+ Changed in 0.6a10: previously all URLs and directories passed to this
+ option were scanned as early as possible, but from 0.6a10 on, 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.
+
+``--no-find-links`` Blocks the addition of any link.
+ This parameter is useful if you want to avoid adding links defined in a
+ project easy_install is installing (whether it's a requested project or a
+ dependency). When used, ``--find-links`` is ignored.
+
+ Added in Distribute 0.6.11 and Setuptools 0.7.
+
+``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
+ Specifies the base URL of the Python Package Index. The default is
+ https://pypi.org/simple/ if not specified. When a package is requested
+ that is not locally available or linked from a ``--find-links`` download
+ page, the package index will be searched for download pages for the needed
+ package, and those download pages will be searched for links to download
+ an egg or source distribution.
+
+``--editable, -e`` (New in 0.6a1)
+ Only find and download source distributions for the specified projects,
+ unpacking them to subdirectories of the specified ``--build-directory``.
+ EasyInstall will not actually build or install the requested projects or
+ their dependencies; it will just find and extract them for you. See
+ `Editing and Viewing Source Packages`_ above for more details.
+
+``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
+ Set the directory used to build source packages. If a package is built
+ from a source distribution or checkout, it will be extracted to a
+ subdirectory of the specified directory. The subdirectory will have the
+ same name as the extracted distribution's project, but in all-lowercase.
+ If a file or directory of that name already exists in the given directory,
+ a warning will be printed to the console, and the build will take place in
+ a temporary directory instead.
+
+ This option is most useful in combination with the ``--editable`` option,
+ which forces EasyInstall to *only* find and extract (but not build and
+ install) source distributions. See `Editing and Viewing Source Packages`_,
+ above, for more information.
+
+``--verbose, -v, --quiet, -q`` (New in 0.4a4)
+ Control the level of detail of EasyInstall's progress messages. The
+ default detail level is "info", which prints information only about
+ relatively time-consuming operations like running a setup script, unpacking
+ an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the
+ detail level to "warn", which will only display installation reports,
+ warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail
+ level to include individual file-level operations, link analysis messages,
+ and distutils messages from any setup scripts that get run. If you include
+ the ``-v`` option more than once, the second and subsequent uses are passed
+ down to any setup scripts, increasing the verbosity of their reporting as
+ well.
+
+``--dry-run, -n`` (New in 0.4a4)
+ Don't actually install the package or scripts. This option is passed down
+ to any setup scripts run, so packages should not actually build either.
+ This does *not* skip downloading, nor does it skip extracting source
+ distributions to a temporary/build directory.
+
+``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
+ If you are installing from a source distribution, and are *not* using the
+ ``--zip-ok`` option, this option controls the optimization level for
+ compiling installed ``.py`` files to ``.pyo`` files. It does not affect
+ the compilation of modules contained in ``.egg`` files, only those in
+ ``.egg`` directories. The optimization level can be set to 0, 1, or 2;
+ the default is 0 (unless it's set under ``install`` or ``install_lib`` in
+ one of your distutils configuration files).
+
+``--record=FILENAME`` (New in 0.5a4)
+ Write a record of all installed files to FILENAME. This is basically the
+ same as the same option for the standard distutils "install" command, and
+ is included for compatibility with tools that expect to pass this option
+ to "setup.py install".
+
+``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1)
+ Specify one or more custom "site" directories (separated by commas).
+ "Site" directories are directories where ``.pth`` files are processed, such
+ as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall
+ automatically detects whether a given directory processes ``.pth`` files
+ (or can be made to do so), so you should not normally need to use this
+ option. It is is now only necessary if you want to override EasyInstall's
+ judgment and force an installation directory to be treated as if it
+ supported ``.pth`` files.
+
+``--no-deps, -N`` (New in 0.6a6)
+ Don't install any dependencies. This is intended as a convenience for
+ tools that wrap eggs in a platform-specific packaging system. (We don't
+ recommend that you use it for anything else.)
+
+``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6)
+ Restrict downloading and spidering to hosts matching the specified glob
+ patterns. E.g. ``-H *.python.org`` restricts web access so that only
+ packages listed and downloadable from machines in the ``python.org``
+ domain. The glob patterns must match the *entire* user/host/port section of
+ the target URL(s). For example, ``*.python.org`` will NOT accept a URL
+ like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
+ Multiple patterns can be specified by separating them with commas. The
+ default pattern is ``*``, which matches anything.
+
+ In general, this option is mainly useful for blocking EasyInstall's web
+ access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
+ or other trusted site. EasyInstall will do the best it can to satisfy
+ dependencies given your host restrictions, but of course can fail if it
+ can't find suitable packages. EasyInstall displays all blocked URLs, so
+ that you can adjust your ``--allow-hosts`` setting if it is more strict
+ than you intended. Some sites may wish to define a restrictive default
+ setting for this option in their `configuration files`_, and then manually
+ override the setting on the command line as needed.
+
+``--prefix=DIR`` (New in 0.6a10)
+ Use the specified directory as a base for computing the default
+ installation and script directories. On Windows, the resulting default
+ directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
+ while on other platforms the defaults will be
+ ``prefix/lib/python2.X/site-packages`` (with the appropriate version
+ substituted) for libraries and ``prefix/bin`` for scripts.
+
+ Note that the ``--prefix`` option only sets the *default* installation and
+ script directories, and does not override the ones set on the command line
+ or in a configuration file.
+
+``--local-snapshots-ok, -l`` (New in 0.6c6)
+ Normally, EasyInstall prefers to only install *released* versions of
+ projects, not in-development ones, because such projects may not
+ have a currently-valid version number. So, it usually only installs them
+ when their ``setup.py`` directory is explicitly passed on the command line.
+
+ However, if this option is used, then any in-development projects that were
+ installed using the ``setup.py develop`` command, will be used to build
+ eggs, effectively upgrading the "in-development" project to a snapshot
+ release. Normally, this option is used only in conjunction with the
+ ``--always-copy`` option to create a distributable snapshot of every egg
+ needed to run an application.
+
+ Note that if you use this option, you must make sure that there is a valid
+ version number (such as an SVN revision number tag) for any in-development
+ projects that may be used, as otherwise EasyInstall may not be able to tell
+ what version of the project is "newer" when future installations or
+ upgrades are attempted.
+
+
+.. _non-root installation:
+
+Custom Installation Locations
+-----------------------------
+
+By default, EasyInstall installs python packages into Python's main ``site-packages`` directory,
+and manages them using a custom ``.pth`` file in that same directory.
+
+Very often though, a user or developer wants ``easy_install`` to install and manage python packages
+in an alternative location, usually for one of 3 reasons:
+
+1. They don't have access to write to the main Python site-packages directory.
+
+2. They want a user-specific stash of packages, that is not visible to other users.
+
+3. They want to isolate a set of packages to a specific python application, usually to minimize
+ the possibility of version conflicts.
+
+Historically, there have been many approaches to achieve custom installation.
+The following section lists only the easiest and most relevant approaches [1]_.
+
+`Use the "--user" option`_
+
+`Use the "--user" option and customize "PYTHONUSERBASE"`_
+
+`Use "virtualenv"`_
+
+.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_.
+
+.. _PEP-370: http://www.python.org/dev/peps/pep-0370/
+
+
+Use the "--user" option
+~~~~~~~~~~~~~~~~~~~~~~~
+Python provides a User scheme for installation, which means that all
+python distributions support an alternative install location that is specific to a user [3]_.
+The Default location for each OS is explained in the python documentation
+for the ``site.USER_BASE`` variable. This mode of installation can be turned on by
+specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
+This approach serves the need to have a user-specific stash of packages.
+
+.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.
+
+Use the "--user" option and customize "PYTHONUSERBASE"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment
+variable, which updates the value of ``site.USER_BASE``. To isolate packages to a specific
+application, simply set the OS environment of that application to a specific value of
+``PYTHONUSERBASE``, that contains just those packages.
+
+Use "virtualenv"
+~~~~~~~~~~~~~~~~
+"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby
+creating an isolated location to install packages. The evolution of "virtualenv" started before the existence
+of the User installation scheme. "virtualenv" provides a version of ``easy_install`` that is
+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/
+
+
+
+Package Index "API"
+-------------------
+
+Custom package indexes (and PyPI) must follow the following rules for
+EasyInstall to be able to look up and download packages:
+
+1. Except where stated otherwise, "pages" are HTML or XHTML, and "links"
+ refer to ``href`` attributes.
+
+2. Individual project version pages' URLs must be of the form
+ ``base/projectname/version``, where ``base`` is the package index's base URL.
+
+3. Omitting the ``/version`` part of a project page's URL (but keeping the
+ trailing ``/``) should result in a page that is either:
+
+ a) The single active version of that project, as though the version had been
+ explicitly included, OR
+
+ b) A page with links to all of the active version pages for that project.
+
+4. Individual project version pages should contain direct links to downloadable
+ distributions where possible. It is explicitly permitted for a project's
+ "long_description" to include URLs, and these should be formatted as HTML
+ links by the package index, as EasyInstall does no special processing to
+ identify what parts of a page are index-specific and which are part of the
+ project's supplied description.
+
+5. Where available, MD5 information should be added to download URLs by
+ appending a fragment identifier of the form ``#md5=...``, where ``...`` is
+ the 32-character hex MD5 digest. EasyInstall will verify that the
+ downloaded file's MD5 digest matches the given value.
+
+6. Individual project version pages should identify any "homepage" or
+ "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
+ on the HTML elements linking to those URLs. Use of these attributes will
+ cause EasyInstall to always follow the provided links, unless it can be
+ determined by inspection that they are downloadable distributions. If the
+ links are not to downloadable distributions, they are retrieved, and if they
+ are HTML, they are scanned for download links. They are *not* scanned for
+ additional "homepage" or "download" links, as these are only processed for
+ pages that are part of a package index site.
+
+7. The root URL of the index, if retrieved with a trailing ``/``, must result
+ in a page containing links to *all* projects' active version pages.
+
+ (Note: This requirement is a workaround for the absence of case-insensitive
+ ``safe_name()`` matching of project names in URL paths. If project names are
+ matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
+ mechanism), then it is not necessary to include this all-packages listing
+ page.)
+
+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.
--- /dev/null
+"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.
\ No newline at end of file
--- /dev/null
+======================================================
+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
+
+ python3
+ python_eggs
+ easy_install
+ distutils-legacy
--- /dev/null
+=====================================================
+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 project 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``.
--- /dev/null
+=====================================
+The Internal Structure of Python Eggs
+=====================================
+
+STOP! This is not the first document you should read!
+
+
+
+.. contents:: **Table of Contents**
+
+
+----------------------
+Eggs and their Formats
+----------------------
+
+A "Python egg" is a logical structure embodying the release of a
+specific version of a Python project, comprising its code, resources,
+and metadata. There are multiple formats that can be used to physically
+encode a Python egg, and others can be developed. However, a key
+principle of Python eggs is that they should be discoverable and
+importable. That is, it should be possible for a Python application to
+easily and efficiently find out what eggs are present on a system, and
+to ensure that the desired eggs' contents are importable.
+
+There are two basic formats currently implemented for Python eggs:
+
+1. ``.egg`` format: a directory or zipfile *containing* the project's
+ code and resources, along with an ``EGG-INFO`` subdirectory that
+ contains the project's metadata
+
+2. ``.egg-info`` format: a file or directory placed *adjacent* to the
+ project's code and resources, that directly contains the project's
+ metadata.
+
+Both formats can include arbitrary Python code and resources, including
+static data files, package and non-package directories, Python
+modules, C extension modules, and so on. But each format is optimized
+for different purposes.
+
+The ``.egg`` format is well-suited to distribution and the easy
+uninstallation or upgrades of code, since the project is essentially
+self-contained within a single directory or file, unmingled with any
+other projects' code or resources. It also makes it possible to have
+multiple versions of a project simultaneously installed, such that
+individual programs can select the versions they wish to use.
+
+The ``.egg-info`` format, on the other hand, was created to support
+backward-compatibility, performance, and ease of installation for system
+packaging tools that expect to install all projects' code and resources
+to a single directory (e.g. ``site-packages``). Placing the metadata
+in that same directory simplifies the installation process, since it
+isn't necessary to create ``.pth`` files or otherwise modify
+``sys.path`` to include each installed egg.
+
+Its disadvantage, however, is that it provides no support for clean
+uninstallation or upgrades, and of course only a single version of a
+project can be installed to a given directory. Thus, support from a
+package management tool is required. (This is why setuptools' "install"
+command refers to this type of egg installation as "single-version,
+externally managed".) Also, they lack sufficient data to allow them to
+be copied from their installation source. easy_install can "ship" an
+application by copying ``.egg`` files or directories to a target
+location, but it cannot do this for ``.egg-info`` installs, because
+there is no way to tell what code and resources belong to a particular
+egg -- there may be several eggs "scrambled" together in a single
+installation location, and the ``.egg-info`` format does not currently
+include a way to list the files that were installed. (This may change
+in a future version.)
+
+
+Code and Resources
+==================
+
+The layout of the code and resources is dictated by Python's normal
+import layout, relative to the egg's "base location".
+
+For the ``.egg`` format, the base location is the ``.egg`` itself. That
+is, adding the ``.egg`` filename or directory name to ``sys.path``
+makes its contents importable.
+
+For the ``.egg-info`` format, however, the base location is the
+directory that *contains* the ``.egg-info``, and thus it is the
+directory that must be added to ``sys.path`` to make the egg importable.
+(Note that this means that the "normal" installation of a package to a
+``sys.path`` directory is sufficient to make it an "egg" if it has an
+``.egg-info`` file or directory installed alongside of it.)
+
+
+Project Metadata
+=================
+
+If eggs contained only code and resources, there would of course be
+no difference between them and any other directory or zip file on
+``sys.path``. Thus, metadata must also be included, using a metadata
+file or directory.
+
+For the ``.egg`` format, the metadata is placed in an ``EGG-INFO``
+subdirectory, directly within the ``.egg`` file or directory. For the
+``.egg-info`` format, metadata is stored directly within the
+``.egg-info`` directory itself.
+
+The minimum project metadata that all eggs must have is a standard
+Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the
+metadata directory appropriate to the format. Because it's possible for
+this to be the only metadata file included, ``.egg-info`` format eggs
+are not required to be a directory; they can just be a ``.egg-info``
+file that directly contains the ``PKG-INFO`` metadata. This eliminates
+the need to create a directory just to store one file. This option is
+*not* available for ``.egg`` formats, since setuptools always includes
+other metadata. (In fact, setuptools itself never generates
+``.egg-info`` files, either; the support for using files was added so
+that the requirement could easily be satisfied by other tools, such
+as distutils).
+
+In addition to the ``PKG-INFO`` file, an egg's metadata directory may
+also include files and directories representing various forms of
+optional standard metadata (see the section on `Standard Metadata`_,
+below) or user-defined metadata required by the project. For example,
+some projects may define a metadata format to describe their application
+plugins, and metadata in this format would then be included by plugin
+creators in their projects' metadata directories.
+
+
+Filename-Embedded Metadata
+==========================
+
+To allow introspection of installed projects and runtime resolution of
+inter-project dependencies, a certain amount of information is embedded
+in egg filenames. At a minimum, this includes the project name, and
+ideally will also include the project version number. Optionally, it
+can also include the target Python version and required runtime
+platform if platform-specific C code is included. The syntax of an
+egg filename is as follows::
+
+ name ["-" version ["-py" pyver ["-" required_platform]]] "." ext
+
+The "name" and "version" should be escaped using the ``to_filename()``
+function provided by ``pkg_resources``, after first processing them with
+``safe_name()`` and ``safe_version()`` respectively. These latter two
+functions can also be used to later "unescape" these parts of the
+filename. (For a detailed description of these transformations, please
+see the "Parsing Utilities" section of the ``pkg_resources`` manual.)
+
+The "pyver" string is the Python major version, as found in the first
+3 characters of ``sys.version``. "required_platform" is essentially
+a distutils ``get_platform()`` string, but with enhancements to properly
+distinguish Mac OS versions. (See the ``get_build_platform()``
+documentation in the "Platform Utilities" section of the
+``pkg_resources`` manual for more details.)
+
+Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate
+for the egg's format.
+
+Normally, an egg's filename should include at least the project name and
+version, as this allows the runtime system to find desired project
+versions without having to read the egg's PKG-INFO to determine its
+version number.
+
+Setuptools, however, only includes the version number in the filename
+when an ``.egg`` file is built using the ``bdist_egg`` command, or when
+an ``.egg-info`` directory is being installed by the
+``install_egg_info`` command. When generating metadata for use with the
+original source tree, it only includes the project name, so that the
+directory will not have to be renamed each time the project's version
+changes.
+
+This is especially important when version numbers change frequently, and
+the source metadata directory is kept under version control with the
+rest of the project. (As would be the case when the project's source
+includes project-defined metadata that is not generated from by
+setuptools from data in the setup script.)
+
+
+Egg Links
+=========
+
+In addition to the ``.egg`` and ``.egg-info`` formats, there is a third
+egg-related extension that you may encounter on occasion: ``.egg-link``
+files.
+
+These files are not eggs, strictly speaking. They simply provide a way
+to reference an egg that is not physically installed in the desired
+location. They exist primarily as a cross-platform alternative to
+symbolic links, to support "installing" code that is being developed in
+a different location than the desired installation location. For
+example, if a user is developing an application plugin in their home
+directory, but the plugin needs to be "installed" in an application
+plugin directory, running "setup.py develop -md /path/to/app/plugins"
+will install an ``.egg-link`` file in ``/path/to/app/plugins``, that
+tells the egg runtime system where to find the actual egg (the user's
+project source directory and its ``.egg-info`` subdirectory).
+
+``.egg-link`` files are named following the format for ``.egg`` and
+``.egg-info`` names, but only the project name is included; no version,
+Python version, or platform information is included. When the runtime
+searches for available eggs, ``.egg-link`` files are opened and the
+actual egg file/directory name is read from them.
+
+Each ``.egg-link`` file should contain a single file or directory name,
+with no newlines. This filename should be the base location of one or
+more eggs. That is, the name must either end in ``.egg``, or else it
+should be the parent directory of one or more ``.egg-info`` format eggs.
+
+As of setuptools 0.6c6, the path may be specified as a platform-independent
+(i.e. ``/``-separated) relative path from the directory containing the
+``.egg-link`` file, and a second line may appear in the file, specifying a
+platform-independent relative path from the egg's base directory to its
+setup script directory. This allows installation tools such as EasyInstall
+to find the project's setup directory and build eggs or perform other setup
+commands on it.
+
+
+-----------------
+Standard Metadata
+-----------------
+
+In addition to the minimum required ``PKG-INFO`` metadata, projects can
+include a variety of standard metadata files or directories, as
+described below. Except as otherwise noted, these files and directories
+are automatically generated by setuptools, based on information supplied
+in the setup script or through analysis of the project's code and
+resources.
+
+Most of these files and directories are generated via "egg-info
+writers" during execution of the setuptools ``egg_info`` command, and
+are listed in the ``egg_info.writers`` entry point group defined by
+setuptools' own ``setup.py`` file.
+
+Project authors can register their own metadata writers as entry points
+in this group (as described in the setuptools manual under "Adding new
+EGG-INFO Files") to cause setuptools to generate project-specific
+metadata files or directories during execution of the ``egg_info``
+command. It is up to project authors to document these new metadata
+formats, if they create any.
+
+
+``.txt`` File Formats
+=====================
+
+Files described in this section that have ``.txt`` extensions have a
+simple lexical format consisting of a sequence of text lines, each line
+terminated by a linefeed character (regardless of platform). Leading
+and trailing whitespace on each line is ignored, as are blank lines and
+lines whose first nonblank character is a ``#`` (comment symbol). (This
+is the parsing format defined by the ``yield_lines()`` function of
+the ``pkg_resources`` module.)
+
+All ``.txt`` files defined by this section follow this format, but some
+are also "sectioned" files, meaning that their contents are divided into
+sections, using square-bracketed section headers akin to Windows
+``.ini`` format. Note that this does *not* imply that the lines within
+the sections follow an ``.ini`` format, however. Please see an
+individual metadata file's documentation for a description of what the
+lines and section names mean in that particular file.
+
+Sectioned files can be parsed using the ``split_sections()`` function;
+see the "Parsing Utilities" section of the ``pkg_resources`` manual for
+for details.
+
+
+Dependency Metadata
+===================
+
+
+``requires.txt``
+----------------
+
+This is a "sectioned" text file. Each section is a sequence of
+"requirements", as parsed by the ``parse_requirements()`` function;
+please see the ``pkg_resources`` manual for the complete requirement
+parsing syntax.
+
+The first, unnamed section (i.e., before the first section header) in
+this file is the project's core requirements, which must be installed
+for the project to function. (Specified using the ``install_requires``
+keyword to ``setup()``).
+
+The remaining (named) sections describe the project's "extra"
+requirements, as specified using the ``extras_require`` keyword to
+``setup()``. The section name is the name of the optional feature, and
+the section body lists that feature's dependencies.
+
+Note that it is not normally necessary to inspect this file directly;
+``pkg_resources.Distribution`` objects have a ``requires()`` method
+that can be used to obtain ``Requirement`` objects describing the
+project's core and optional dependencies.
+
+
+``setup_requires.txt``
+----------------------
+
+Much like ``requires.txt`` except represents the requirements
+specified by the ``setup_requires`` parameter to the Distribution.
+
+
+``dependency_links.txt``
+------------------------
+
+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. Please see the setuptools manual for more information on
+specifying this option.
+
+
+``depends.txt`` -- Obsolete, do not create!
+-------------------------------------------
+
+This file follows an identical format to ``requires.txt``, but is
+obsolete and should not be used. The earliest versions of setuptools
+required users to manually create and maintain this file, so the runtime
+still supports reading it, if it exists. The new filename was created
+so that it could be automatically generated from ``setup()`` information
+without overwriting an existing hand-created ``depends.txt``, if one
+was already present in the project's source ``.egg-info`` directory.
+
+
+``namespace_packages.txt`` -- Namespace Package Metadata
+========================================================
+
+A list of namespace package names, one per line, as supplied to the
+``namespace_packages`` keyword to ``setup()``. Please see the manuals
+for setuptools and ``pkg_resources`` for more information about
+namespace packages.
+
+
+``entry_points.txt`` -- "Entry Point"/Plugin Metadata
+=====================================================
+
+This is a "sectioned" text file, whose contents encode the
+``entry_points`` keyword supplied to ``setup()``. All sections are
+named, as the section names specify the entry point groups in which the
+corresponding section's entry points are registered.
+
+Each section is a sequence of "entry point" lines, each parseable using
+the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources``
+manual for the complete entry point parsing syntax.
+
+Note that it is not necessary to parse this file directly; the
+``pkg_resources`` module provides a variety of APIs to locate and load
+entry points automatically. Please see the setuptools and
+``pkg_resources`` manuals for details on the nature and uses of entry
+points.
+
+
+The ``scripts`` Subdirectory
+============================
+
+This directory is currently only created for ``.egg`` files built by
+the setuptools ``bdist_egg`` command. It will contain copies of all
+of the project's "traditional" scripts (i.e., those specified using the
+``scripts`` keyword to ``setup()``). This is so that they can be
+reconstituted when an ``.egg`` file is installed.
+
+The scripts are placed here using the distutils' standard
+``install_scripts`` command, so any ``#!`` lines reflect the Python
+installation where the egg was built. But instead of copying the
+scripts to the local script installation directory, EasyInstall writes
+short wrapper scripts that invoke the original scripts from inside the
+egg, after ensuring that sys.path includes the egg and any eggs it
+depends on. For more about `script wrappers`_, see the section below on
+`Installation and Path Management Issues`_.
+
+
+Zip Support Metadata
+====================
+
+
+``native_libs.txt``
+-------------------
+
+A list of C extensions and other dynamic link libraries contained in
+the egg, one per line. Paths are ``/``-separated and relative to the
+egg's base location.
+
+This file is generated as part of ``bdist_egg`` processing, and as such
+only appears in ``.egg`` files (and ``.egg`` directories created by
+unpacking them). It is used to ensure that all libraries are extracted
+from a zipped egg at the same time, in case there is any direct linkage
+between them. Please see the `Zip File Issues`_ section below for more
+information on library and resource extraction from ``.egg`` files.
+
+
+``eager_resources.txt``
+-----------------------
+
+A list of resource files and/or directories, one per line, as specified
+via the ``eager_resources`` keyword to ``setup()``. Paths are
+``/``-separated and relative to the egg's base location.
+
+Resource files or directories listed here will be extracted
+simultaneously, if any of the named resources are extracted, or if any
+native libraries listed in ``native_libs.txt`` are extracted. Please
+see the setuptools manual for details on what this feature is used for
+and how it works, as well as the `Zip File Issues`_ section below.
+
+
+``zip-safe`` and ``not-zip-safe``
+---------------------------------
+
+These are zero-length files, and either one or the other should exist.
+If ``zip-safe`` exists, it means that the project will work properly
+when installed as an ``.egg`` zipfile, and conversely the existence of
+``not-zip-safe`` means the project should not be installed as an
+``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()``
+determines which file will be written. If the option isn't provided,
+setuptools attempts to make its own assessment of whether the package
+can work, based on code and content analysis.
+
+If neither file is present at installation time, EasyInstall defaults
+to assuming that the project should be unzipped. (Command-line options
+to EasyInstall, however, take precedence even over an existing
+``zip-safe`` or ``not-zip-safe`` file.)
+
+Note that these flag files appear only in ``.egg`` files generated by
+``bdist_egg``, and in ``.egg`` directories created by unpacking such an
+``.egg`` file.
+
+
+
+``top_level.txt`` -- Conflict Management Metadata
+=================================================
+
+This file is a list of the top-level module or package names provided
+by the project, one Python identifier per line.
+
+Subpackages are not included; a project containing both a ``foo.bar``
+and a ``foo.baz`` would include only one line, ``foo``, in its
+``top_level.txt``.
+
+This data is used by ``pkg_resources`` at runtime to issue a warning if
+an egg is added to ``sys.path`` when its contained packages may have
+already been imported.
+
+(It was also once used to detect conflicts with non-egg packages at
+installation time, but in more recent versions, setuptools installs eggs
+in such a way that they always override non-egg packages, thus
+preventing a problem from arising.)
+
+
+``SOURCES.txt`` -- Source Files Manifest
+========================================
+
+This file is roughly equivalent to the distutils' ``MANIFEST`` file.
+The differences are as follows:
+
+* The filenames always use ``/`` as a path separator, which must be
+ converted back to a platform-specific path whenever they are read.
+
+* The file is automatically generated by setuptools whenever the
+ ``egg_info`` or ``sdist`` commands are run, and it is *not*
+ user-editable.
+
+Although this metadata is included with distributed eggs, it is not
+actually used at runtime for any purpose. Its function is to ensure
+that setuptools-built *source* distributions can correctly discover
+what files are part of the project's source, even if the list had been
+generated using revision control metadata on the original author's
+system.
+
+In other words, ``SOURCES.txt`` has little or no runtime value for being
+included in distributed eggs, and it is possible that future versions of
+the ``bdist_egg`` and ``install_egg_info`` commands will strip it before
+installation or distribution. Therefore, do not rely on its being
+available outside of an original source directory or source
+distribution.
+
+
+------------------------------
+Other Technical Considerations
+------------------------------
+
+
+Zip File Issues
+===============
+
+Although zip files resemble directories, they are not fully
+substitutable for them. Most platforms do not support loading dynamic
+link libraries contained in zipfiles, so it is not possible to directly
+import C extensions from ``.egg`` zipfiles. Similarly, there are many
+existing libraries -- whether in Python or C -- that require actual
+operating system filenames, and do not work with arbitrary "file-like"
+objects or in-memory strings, and thus cannot operate directly on the
+contents of zip files.
+
+To address these issues, the ``pkg_resources`` module provides a
+"resource API" to support obtaining either the contents of a resource,
+or a true operating system filename for the resource. If the egg
+containing the resource is a directory, the resource's real filename
+is simply returned. However, if the egg is a zipfile, then the
+resource is first extracted to a cache directory, and the filename
+within the cache is returned.
+
+The cache directory is determined by the ``pkg_resources`` API; please
+see the ``set_cache_path()`` and ``get_default_cache()`` documentation
+for details.
+
+
+The Extraction Process
+----------------------
+
+Resources are extracted to a cache subdirectory whose name is based
+on the enclosing ``.egg`` filename and the path to the resource. If
+there is already a file of the correct name, size, and timestamp, its
+filename is returned to the requester. Otherwise, the desired file is
+extracted first to a temporary name generated using
+``mkstemp(".$extract",target_dir)``, and then its timestamp is set to
+match the one in the zip file, before renaming it to its final name.
+(Some collision detection and resolution code is used to handle the
+fact that Windows doesn't overwrite files when renaming.)
+
+If a resource directory is requested, all of its contents are
+recursively extracted in this fashion, to ensure that the directory
+name can be used as if it were valid all along.
+
+If the resource requested for extraction is listed in the
+``native_libs.txt`` or ``eager_resources.txt`` metadata files, then
+*all* resources listed in *either* file will be extracted before the
+requested resource's filename is returned, thus ensuring that all
+C extensions and data used by them will be simultaneously available.
+
+
+Extension Import Wrappers
+-------------------------
+
+Since Python's built-in zip import feature does not support loading
+C extension modules from zipfiles, the setuptools ``bdist_egg`` command
+generates special import wrappers to make it work.
+
+The wrappers are ``.py`` files (along with corresponding ``.pyc``
+and/or ``.pyo`` files) that have the same module name as the
+corresponding C extension. These wrappers are located in the same
+package directory (or top-level directory) within the zipfile, so that
+say, ``foomodule.so`` will get a corresponding ``foo.py``, while
+``bar/baz.pyd`` will get a corresponding ``bar/baz.py``.
+
+These wrapper files contain a short stanza of Python code that asks
+``pkg_resources`` for the filename of the corresponding C extension,
+then reloads the module using the obtained filename. This will cause
+``pkg_resources`` to first ensure that all of the egg's C extensions
+(and any accompanying "eager resources") are extracted to the cache
+before attempting to link to the C library.
+
+Note, by the way, that ``.egg`` directories will also contain these
+wrapper files. However, Python's default import priority is such that
+C extensions take precedence over same-named Python modules, so the
+import wrappers are ignored unless the egg is a zipfile.
+
+
+Installation and Path Management Issues
+=======================================
+
+Python's initial setup of ``sys.path`` is very dependent on the Python
+version and installation platform, as well as how Python was started
+(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter).
+In fact, Python also provides only two relatively robust ways to affect
+``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH``
+environment variable, and ``.pth`` files.
+
+However, with no cross-platform way to safely and persistently change
+environment variables, this leaves ``.pth`` files as EasyInstall's only
+real option for persistent configuration of ``sys.path``.
+
+But ``.pth`` files are rather strictly limited in what they are allowed
+to do normally. They add directories only to the *end* of ``sys.path``,
+after any locally-installed ``site-packages`` directory, and they are
+only processed *in* the ``site-packages`` directory to start with.
+
+This is a double whammy for users who lack write access to that
+directory, because they can't create a ``.pth`` file that Python will
+read, and even if a sympathetic system administrator adds one for them
+that calls ``site.addsitedir()`` to allow some other directory to
+contain ``.pth`` files, they won't be able to install newer versions of
+anything that's installed in the systemwide ``site-packages``, because
+their paths will still be added *after* ``site-packages``.
+
+So EasyInstall applies two workarounds to solve these problems.
+
+The first is that EasyInstall leverages ``.pth`` files' "import" feature
+to manipulate ``sys.path`` and ensure that anything EasyInstall adds
+to a ``.pth`` file will always appear before both the standard library
+and the local ``site-packages`` directories. Thus, it is always
+possible for a user who can write a Python-read ``.pth`` file to ensure
+that their packages come first in their own environment.
+
+Second, when installing to a ``PYTHONPATH`` directory (as opposed to
+a "site" directory like ``site-packages``) EasyInstall will also install
+a special version of the ``site`` module. Because it's in a
+``PYTHONPATH`` directory, this module will get control before the
+standard library version of ``site`` does. It will record the state of
+``sys.path`` before invoking the "real" ``site`` module, and then
+afterwards it processes any ``.pth`` files found in ``PYTHONPATH``
+directories, including all the fixups needed to ensure that eggs always
+appear before the standard library in sys.path, but are in a relative
+order to one another that is defined by their ``PYTHONPATH`` and
+``.pth``-prescribed sequence.
+
+The net result of these changes is that ``sys.path`` order will be
+as follows at runtime:
+
+1. The ``sys.argv[0]`` directory, or an empty string if no script
+ is being executed.
+
+2. All eggs installed by EasyInstall in any ``.pth`` file in each
+ ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order,
+ then normal ``.pth`` processing order (which is to say alphabetical
+ by ``.pth`` filename, then by the order of listing within each
+ ``.pth`` file).
+
+3. All eggs installed by EasyInstall in any ``.pth`` file in each "site"
+ directory (such as ``site-packages``), following the same ordering
+ rules as for the ones on ``PYTHONPATH``.
+
+4. The ``PYTHONPATH`` directories themselves, in their original order
+
+5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not*
+ eggs installed by EasyInstall, again following the same relative
+ ordering rules.
+
+6. The standard library and "site" directories, along with the contents
+ of any ``.pth`` files found in the "site" directories.
+
+Notice that sections 1, 4, and 6 comprise the "normal" Python setup for
+``sys.path``. Sections 2 and 3 are inserted to support eggs, and
+section 5 emulates what the "normal" semantics of ``.pth`` files on
+``PYTHONPATH`` would be if Python natively supported them.
+
+For further discussion of the tradeoffs that went into this design, as
+well as notes on the actual magic inserted into ``.pth`` files to make
+them do these things, please see also the following messages to the
+distutils-SIG mailing list:
+
+* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html
+* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html
+
+
+Script Wrappers
+---------------
+
+EasyInstall never directly installs a project's original scripts to
+a script installation directory. Instead, it writes short wrapper
+scripts that first ensure that the project's dependencies are active
+on sys.path, before invoking the original script. These wrappers
+have a #! line that points to the version of Python that was used to
+install them, and their second line is always a comment that indicates
+the type of script wrapper, the project version required for the script
+to run, and information identifying the script to be invoked.
+
+The format of this marker line is::
+
+ "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n"
+
+The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or
+``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated
+sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT``
+wrappers, there are two strings: the project version requirement, and
+the script name (as a filename within the ``scripts`` metadata
+directory). For ``ENTRY-SCRIPT`` wrappers, there are three:
+the project version requirement, the entry point group name, and the
+entry point name. (See the "Automatic Script Creation" section in the
+setuptools manual for more information about entry point scripts.)
+
+In each case, the project version requirement string will be a string
+parseable with the ``pkg_resources`` modules' ``Requirement.parse()``
+classmethod. The only difference between a ``SCRIPT`` wrapper and a
+``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original
+source script in the project's source tree, and is created when the
+"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other
+hand, uses the "installed" script written to the ``EGG-INFO/scripts``
+subdirectory of the corresponding ``.egg`` zipfile or directory.
+(``.egg-info`` eggs do not have script wrappers associated with them,
+except in the "setup.py develop" case.)
+
+The purpose of including the marker line in generated script wrappers is
+to facilitate introspection of installed scripts, and their relationship
+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.
+
--- /dev/null
+================================
+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 <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_, or on IRC (Freenode) at
+#pypa.
+
+Discussions about development happen on the distutils-sig 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.
+
+---------------------
+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.readthedocs.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`` and refreshed by way of
+``paver update_vendored`` (pavement.py).
+++ /dev/null
-================================
-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 <https://mail.python.org/mailman3/lists/distutils-sig.python.org/>`_, or on IRC (Freenode) at
-#pypa.
-
-Discussions about development happen on the distutils-sig 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.
-
----------------------
-Making a pull request
----------------------
-
-When making a pull request, please include a short summary of the changes
-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.
-
-``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_
-for changelog management, so when making a PR, please add a news fragment in the
-``changelog.d/`` folder. Changelog files are written in reStructuredText and
-should be a 1 or 2 sentence description of the substantive changes in the PR.
-They should be named ``<pr_number>.<category>.rst``, where the categories are:
-
-- ``change``: Any backwards compatible code change
-- ``breaking``: Any backwards-compatibility breaking change
-- ``doc``: A change to the documentation
-- ``misc``: Changes internal to the repo like CI, test and build changes
-- ``deprecation``: For deprecations of an existing feature or behavior
-
-A pull request may have more than one of these components, for example a code
-change may introduce a new feature that deprecates an old feature, in which
-case two fragments should be added. It is not necessary to make a separate
-documentation fragment for documentation changes accompanying the relevant
-code changes. See the following for an example news fragment:
-
-.. code-block:: bash
-
- $ cat changelog.d/1288.change.rst
- Add support for maintainer in PKG-INFO
-
--------------------
-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.readthedocs.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`` and refreshed by way of
-``paver update_vendored`` (pavement.py).
--- /dev/null
+-------------------------
+Development on Setuptools
+-------------------------
+
+Setuptools is maintained by the Python community under the Python Packaging
+Authority (PyPA) and led by Jason R. Coombs.
+
+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 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
+packages" or "resources" in any detail, as all of these subjects are
+covered at length in the setuptools developer's guide and the
+``pkg_resources`` reference manual.
+
+Instead, this is **internal** documentation for how those concepts and
+features are *implemented* in concrete terms. It is intended for people
+who are working on the setuptools code base, who want to be able to
+troubleshoot setuptools problems, want to write code that reads the file
+formats involved, or want to otherwise tinker with setuptools-generated
+files and directories.
+
+Note, however, that these are all internal implementation details and
+are therefore subject to change; stick to the published API if you don't
+want to be responsible for keeping your code from breaking when
+setuptools changes. You have been warned.
+
+.. toctree::
+ :maxdepth: 1
+
+ developer-guide
+ formats
+ releases
+++ /dev/null
--------------------------
-Development on Setuptools
--------------------------
-
-Setuptools is maintained by the Python community under the Python Packaging
-Authority (PyPA) and led by Jason R. Coombs.
-
-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 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
-packages" or "resources" in any detail, as all of these subjects are
-covered at length in the setuptools developer's guide and the
-``pkg_resources`` reference manual.
-
-Instead, this is **internal** documentation for how those concepts and
-features are *implemented* in concrete terms. It is intended for people
-who are working on the setuptools code base, who want to be able to
-troubleshoot setuptools problems, want to write code that reads the file
-formats involved, or want to otherwise tinker with setuptools-generated
-files and directories.
-
-Note, however, that these are all internal implementation details and
-are therefore subject to change; stick to the published API if you don't
-want to be responsible for keeping your code from breaking when
-setuptools changes. You have been warned.
-
-.. toctree::
- :maxdepth: 1
-
- developer-guide
- formats
- releases
+++ /dev/null
-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 49.1.2 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is disabled by default. To enable the use of this copy of distutils when invoking setuptools, set the enviroment variable:
-
- SETUPTOOLS_USE_DISTUTILS=local
-
-This behavior is planned to become the default.
-
-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.log`` → (no replacement yet)
-
-``distutils.version.*`` → ``packaging.version.*``
-
-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.
+++ /dev/null
-============
-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.
-
-Please share your experiences with us! If you encounter difficulty installing
-a package, please contact us via the `distutils mailing list
-<http://mail.python.org/pipermail/distutils-sig/>`_. (Note: please DO NOT send
-private email directly to the author of setuptools; it will be discarded. The
-mailing list is a searchable archive of previously-asked and answered
-questions; you should begin your research there before reporting something as a
-bug -- and then do so via list discussion first.)
-
-(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 documentation as well.)
-
-.. contents:: **Table of Contents**
-
-
-Using "Easy Install"
-====================
-
-
-.. _installation instructions:
-
-Installing "Easy Install"
--------------------------
-
-Please see the `setuptools PyPI page <https://pypi.org/project/setuptools/>`_
-for download links and basic installation instructions for each of the
-supported platforms.
-
-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
-are installing to Python's primary ``site-packages`` directory. If this is
-not the case, you should consult the section below on `Custom Installation
-Locations`_ before installing. (And, on Windows, you should not use the
-``.exe`` installer when installing to an alternate location.)
-
-Note that ``easy_install`` normally works by downloading files from the
-internet. If you are behind an NTLM-based firewall that prevents Python
-programs from accessing the net directly, you may wish to first install and use
-the `APS proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such
-firewalls in the same way that your web browser(s) do.
-
-(Alternately, if you do not wish easy_install to actually download anything, you
-can restrict it from doing so with the ``--allow-hosts`` option; see the
-sections on `restricting downloads with --allow-hosts`_ and `command-line
-options`_ for more details.)
-
-
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-If EasyInstall/setuptools appears to install correctly, and you can run the
-``easy_install`` command but it fails with an ``ImportError``, the most likely
-cause is that you installed to a location other than ``site-packages``,
-without taking any of the steps described in the `Custom Installation
-Locations`_ section below. Please see that section and follow the steps to
-make sure that your custom location will work correctly. Then re-install.
-
-Similarly, if you can run ``easy_install``, and it appears to be installing
-packages, but then you can't import them, the most likely issue is that you
-installed EasyInstall correctly but are using it to install packages to a
-non-standard location that hasn't been properly prepared. Again, see the
-section on `Custom Installation Locations`_ for more details.
-
-
-Windows Notes
-~~~~~~~~~~~~~
-
-Installing setuptools will provide an ``easy_install`` command according to
-the techniques described in `Executables and Launchers`_. If the
-``easy_install`` command is not available after installation, that section
-provides details on how to configure Windows to make the commands available.
-
-
-Downloading and Installing a Package
-------------------------------------
-
-For basic use of ``easy_install``, you need only supply the filename or URL of
-a source distribution or .egg file (`Python Egg`__).
-
-__ http://peak.telecommunity.com/DevCenter/PythonEggs
-
-**Example 1**. Install a package by name, searching PyPI for the latest
-version, and automatically downloading, building, and installing it::
-
- easy_install SQLObject
-
-**Example 2**. Install or upgrade a package by name and version by finding
-links on a given "download page"::
-
- easy_install -f http://pythonpaste.org/package_index.html SQLObject
-
-**Example 3**. Download a source distribution from a specified URL,
-automatically building and installing it::
-
- easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
-
-**Example 4**. Install an already-downloaded .egg file::
-
- easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
-
-**Example 5**. Upgrade an already-installed package to the latest version
-listed on PyPI::
-
- easy_install --upgrade PyProtocols
-
-**Example 6**. Install a source distribution that's already downloaded and
-extracted in the current directory (New in 0.5a9)::
-
- easy_install .
-
-**Example 7**. (New in 0.6a1) Find a source distribution or Subversion
-checkout URL for a package, and extract it or check it out to
-``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
-can be examined or edited. (The package will not be installed, but it can
-easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing
-and Viewing Source Packages`_ below for more info.)::
-
- easy_install --editable --build-directory ~/projects SQLObject
-
-**Example 7**. (New in 0.6.11) Install a distribution within your home dir::
-
- easy_install --user SQLAlchemy
-
-Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
-"distribution" names), and package+version specifiers. In each case, it will
-attempt to locate the latest available version that meets your criteria.
-
-When downloading or processing downloaded files, Easy Install recognizes
-distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
-.tar.bz2, or .zip. And of course it handles already-built .egg
-distributions as well as ``.win32.exe`` installers built using distutils.
-
-By default, packages are installed to the running Python installation's
-``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
-option to specify an alternative directory, or specify an alternate location
-using distutils configuration files. (See `Configuration Files`_, below.)
-
-By default, any scripts included with the package are installed to the running
-Python installation's standard script installation location. However, if you
-specify an installation directory via the command line or a config file, then
-the default directory for installing scripts will be the same as the package
-installation directory, to ensure that the script will have access to the
-installed package. You can override this using the ``-s`` or ``--script-dir``
-option.
-
-Installed packages are added to an ``easy-install.pth`` file in the install
-directory, so that Python will always use the most-recently-installed version
-of the package. If you would like to be able to select which version to use at
-runtime, you should use the ``-m`` or ``--multi-version`` option.
-
-
-Upgrading a Package
--------------------
-
-You don't need to do anything special to upgrade a package: just install the
-new version, either by requesting a specific version, e.g.::
-
- easy_install "SomePackage==2.0"
-
-a version greater than the one you have now::
-
- easy_install "SomePackage>2.0"
-
-using the upgrade flag, to find the latest available version on PyPI::
-
- easy_install --upgrade SomePackage
-
-or by using a download page, direct download URL, or package filename::
-
- easy_install -f http://example.com/downloads ExamplePackage
-
- easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg
-
- easy_install my_downloads/ExamplePackage-2.0.tgz
-
-If you're using ``-m`` or ``--multi-version`` , using the ``require()``
-function at runtime automatically selects the newest installed version of a
-package that meets your version criteria. So, installing a newer version is
-the only step needed to upgrade such packages.
-
-If you're installing to a directory on PYTHONPATH, or a configured "site"
-directory (and not using ``-m``), installing a package automatically replaces
-any previous version in the ``easy-install.pth`` file, so that Python will
-import the most-recently installed version by default. So, again, installing
-the newer version is the only upgrade step needed.
-
-If you haven't suppressed script installation (using ``--exclude-scripts`` or
-``-x``), then the upgraded version's scripts will be installed, and they will
-be automatically patched to ``require()`` the corresponding version of the
-package, so that you can use them even if they are installed in multi-version
-mode.
-
-``easy_install`` never actually deletes packages (unless you're installing a
-package with the same name and version number as an existing package), so if
-you want to get rid of older versions of a package, please see `Uninstalling
-Packages`_, below.
-
-
-Changing the Active Version
----------------------------
-
-If you've upgraded a package, but need to revert to a previously-installed
-version, you can do so like this::
-
- easy_install PackageName==1.2.3
-
-Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
-If a package matching the requested name and version is not already installed
-in a directory on ``sys.path``, it will be located via PyPI and installed.
-
-If you'd like to switch to the latest installed version of ``PackageName``, you
-can do so like this::
-
- easy_install PackageName
-
-This will activate the latest installed version. (Note: if you have set any
-``find_links`` via distutils configuration files, those download pages will be
-checked for the latest available version of the package, and it will be
-downloaded and installed if it is newer than your current version.)
-
-Note that changing the active version of a package will install the newly
-active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
-specified.
-
-
-Uninstalling Packages
----------------------
-
-If you have replaced a package with another version, then you can just delete
-the package(s) you don't need by deleting the PackageName-versioninfo.egg file
-or directory (found in the installation directory).
-
-If you want to delete the currently installed version of a package (or all
-versions of a package), you should first run::
-
- easy_install -m PackageName
-
-This will ensure that Python doesn't continue to search for a package you're
-planning to remove. After you've done this, you can safely delete the .egg
-files or directories, along with any scripts you wish to remove.
-
-
-Managing Scripts
-----------------
-
-Whenever you install, upgrade, or change versions of a package, EasyInstall
-automatically installs the scripts for the selected package version, unless
-you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in
-the script directory have the same name, they are overwritten.
-
-Thus, you do not normally need to manually delete scripts for older versions of
-a package, unless the newer version of the package does not include a script
-of the same name. However, if you are completely uninstalling a package, you
-may wish to manually delete its scripts.
-
-EasyInstall's default behavior means that you can normally only run scripts
-from one version of a package at a time. If you want to keep multiple versions
-of a script available, however, you can simply use the ``--multi-version`` or
-``-m`` option, and rename the scripts that EasyInstall creates. This works
-because EasyInstall installs scripts as short code stubs that ``require()`` the
-matching version of the package the script came from, so renaming the script
-has no effect on what it executes.
-
-For example, suppose you want to use two versions of the ``rst2html`` tool
-provided by the `docutils <http://docutils.sf.net/>`_ package. You might
-first install one version::
-
- easy_install -m docutils==0.3.9
-
-then rename the ``rst2html.py`` to ``r2h_039``, and install another version::
-
- easy_install -m docutils==0.3.10
-
-This will create another ``rst2html.py`` script, this one using docutils
-version 0.3.10 instead of 0.3.9. You now have two scripts, each using a
-different version of the package. (Notice that we used ``-m`` for both
-installations, so that Python won't lock us out of using anything but the most
-recently-installed version of the package.)
-
-
-Executables and Launchers
--------------------------
-
-On Unix systems, scripts are installed with as natural files with a "#!"
-header and no extension and they launch under the Python version indicated in
-the header.
-
-On Windows, there is no mechanism to "execute" files without extensions, so
-EasyInstall provides two techniques to mirror the Unix behavior. The behavior
-is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be
-"executable" (default) or "natural".
-
-Regardless of the technique used, the script(s) will be installed to a Scripts
-directory (by default in the Python installation directory). It is recommended
-for EasyInstall that you ensure this directory is in the PATH environment
-variable. The easiest way to ensure the Scripts directory is in the PATH is
-to run ``Tools\Scripts\win_add2path.py`` from the Python directory.
-
-Note that instead of changing your ``PATH`` to include the Python scripts
-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 control where
-scripts will be installed.
-
-
-Windows Executable Launcher
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the "executable" launcher is used, EasyInstall will create a '.exe'
-launcher of the same name beside each installed script (including
-``easy_install`` itself). These small .exe files launch the script of the
-same name using the Python version indicated in the '#!' header.
-
-This behavior is currently default. To force
-the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to "executable".
-
-Natural Script Launcher
-~~~~~~~~~~~~~~~~~~~~~~~
-
-EasyInstall also supports deferring to an external launcher such as
-`pylauncher <https://bitbucket.org/pypa/pylauncher>`_ for launching scripts.
-Enable this experimental functionality by setting the
-``SETUPTOOLS_LAUNCHER`` environment variable to "natural". EasyInstall will
-then install scripts as simple
-scripts with a .pya (or .pyw) extension appended. If these extensions are
-associated with the pylauncher and listed in the PATHEXT environment variable,
-these scripts can then be invoked simply and directly just like any other
-executable. This behavior may become default in a future version.
-
-EasyInstall uses the .pya extension instead of simply
-the typical '.py' extension. This distinct extension is necessary to prevent
-Python
-from treating the scripts as importable modules (where name conflicts exist).
-Current releases of pylauncher do not yet associate with .pya files by
-default, but future versions should do so.
-
-
-Tips & Techniques
------------------
-
-Multiple Python Versions
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-EasyInstall installs itself under two names:
-``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
-used to install it. Thus, if you install EasyInstall for both Python 3.2 and
-2.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to
-install packages for the respective Python version.
-
-Setuptools also supplies easy_install as a runnable module which may be
-invoked using ``python -m easy_install`` for any Python with Setuptools
-installed.
-
-Restricting Downloads with ``--allow-hosts``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
-EasyInstall will look for links and downloads on. ``--allow-hosts=None``
-prevents downloading altogether. You can also use wildcards, for example
-to restrict downloading to hosts in your own intranet. See the section below
-on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.
-
-By default, there are no host restrictions in effect, but you can change this
-default by editing the appropriate `configuration files`_ and adding:
-
-.. code-block:: ini
-
- [easy_install]
- allow_hosts = *.myintranet.example.com,*.python.org
-
-The above example would then allow downloads only from hosts in the
-``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
-command line.
-
-
-Installing on Un-networked Machines
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Just copy the eggs or source packages you need to a directory on the target
-machine, then use the ``-f`` or ``--find-links`` option to specify that
-directory's location. For example::
-
- easy_install -H None -f somedir SomePackage
-
-will attempt to install SomePackage using only eggs and source packages found
-in ``somedir`` and disallowing all remote access. You should of course make
-sure you have all of SomePackage's dependencies available in somedir.
-
-If you have another machine of the same operating system and library versions
-(or if the packages aren't platform-specific), you can create the directory of
-eggs using a command like this::
-
- easy_install -zmaxd somedir SomePackage
-
-This will tell EasyInstall to put zipped eggs or source packages for
-SomePackage and all its dependencies into ``somedir``, without creating any
-scripts or .pth files. You can then copy the contents of ``somedir`` to the
-target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which
-prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
-even if they're installed elsewhere on the machine, and ``-d`` indicates the
-directory to place the eggs in.)
-
-You can also build the eggs from local development packages that were installed
-with the ``setup.py develop`` command, by including the ``-l`` option, e.g.::
-
- easy_install -zmaxld somedir SomePackage
-
-This will use locally-available source distributions to build the eggs.
-
-
-Packaging Others' Projects As Eggs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Need to distribute a package that isn't published in egg form? You can use
-EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``,
-``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
-``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location
-where you'd like the eggs placed. By placing them in a directory that is
-published to the web, you can then make the eggs available for download, either
-in an intranet or to the internet at large.
-
-If someone distributes a package in the form of a single ``.py`` file, you can
-wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
-So, something like this::
-
- easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
-
-will install the package as an egg, and this::
-
- easy_install -zmaxd. \
- -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
-
-will create a ``.egg`` file in the current directory.
-
-
-Creating your own Package Index
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In addition to local directories and the Python Package Index, EasyInstall can
-find download links on most any web page whose URL is given to the ``-f``
-(``--find-links``) option. In the simplest case, you can simply have a web
-page with links to eggs or Python source packages, even an automatically
-generated directory listing (such as the Apache web server provides).
-
-If you are setting up an intranet site for package downloads, you may want to
-configure the target machines to use your download site by default, adding
-something like this to their `configuration files`_:
-
-.. code-block:: ini
-
- [easy_install]
- find_links = http://mypackages.example.com/somedir/
- http://turbogears.org/download/
- http://peak.telecommunity.com/dist/
-
-As you can see, you can list multiple URLs separated by whitespace, continuing
-on multiple lines if necessary (as long as the subsequent lines are indented.
-
-If you are more ambitious, you can also create an entirely custom package index
-or PyPI mirror. See the ``--index-url`` option under `Command-Line Options`_,
-below, and also the section on `Package Index "API"`_.
-
-
-Password-Protected Sites
-------------------------
-
-If a site you want to download from is password-protected using HTTP "Basic"
-authentication, you can specify your credentials in the URL, like so::
-
- http://some_userid:some_password@some.example.com/some_path/
-
-You can do this with both index page URLs and direct download URLs. As long
-as any HTML pages read by easy_install use *relative* links to point to the
-downloads, the same user ID and password will be used to do the downloading.
-
-Using .pypirc Credentials
--------------------------
-
-In additional to supplying credentials in the URL, ``easy_install`` will also
-honor credentials if present in the .pypirc file. Teams maintaining a private
-repository of packages may already have defined access credentials for
-uploading packages according to the distutils documentation. ``easy_install``
-will attempt to honor those if present. Refer to the distutils documentation
-for Python 2.5 or later for details on the syntax.
-
-Controlling Build Options
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-EasyInstall respects standard distutils `Configuration Files`_, so you can use
-them to configure build options for packages that it installs from source. For
-example, if you are on Windows using the MinGW compiler, you can configure the
-default compiler by putting something like this:
-
-.. code-block:: ini
-
- [build]
- compiler = mingw32
-
-into the appropriate distutils configuration file. In fact, since this is just
-normal distutils configuration, it will affect any builds using that config
-file, not just ones done by EasyInstall. For example, if you add those lines
-to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
-default compiler for *all* packages you build. See `Configuration Files`_
-below for a list of the standard configuration file locations, and links to
-more documentation on using distutils configuration files.
-
-
-Editing and Viewing Source Packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes a package's source distribution contains additional documentation,
-examples, configuration files, etc., that are not part of its actual code. If
-you want to be able to examine these files, you can use the ``--editable``
-option to EasyInstall, and EasyInstall will look for a source distribution
-or Subversion URL for the package, then download and extract it or check it out
-as a subdirectory of the ``--build-directory`` you specify. If you then wish
-to install the package after editing or configuring it, you can do so by
-rerunning EasyInstall with that directory as the target.
-
-Note that using ``--editable`` stops EasyInstall from actually building or
-installing the package; it just finds, obtains, and possibly unpacks it for
-you. This allows you to make changes to the package if necessary, and to
-either install it in development mode using ``setup.py develop`` (if the
-package uses setuptools, that is), or by running ``easy_install projectdir``
-(where ``projectdir`` is the subdirectory EasyInstall created for the
-downloaded package.
-
-In order to use ``--editable`` (``-e`` for short), you *must* also supply a
-``--build-directory`` (``-b`` for short). The project will be placed in a
-subdirectory of the build directory. The subdirectory will have the same
-name as the project itself, but in all-lowercase. If a file or directory of
-that name already exists, EasyInstall will print an error message and exit.
-
-Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
-You *must* specify project names (and optional version requirements) so that
-EasyInstall knows what directory name(s) to create. If you need to force
-EasyInstall to use a particular URL or filename, you should specify it as a
-``--find-links`` item (``-f`` for short), and then also specify
-the project name, e.g.::
-
- easy_install -eb ~/projects \
- -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
- ctypes==0.9.6
-
-
-Dealing with Installation Conflicts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
-people using older versions of EasyInstall can consult it. As of version
-0.6a11, installation conflicts are handled automatically without deleting the
-old or system-installed packages, and without ignoring the issue. Instead,
-eggs are automatically shifted to the front of ``sys.path`` using special
-code added to the ``easy-install.pth`` file. So, if you are using version
-0.6a11 or better of setuptools, you do not need to worry about conflicts,
-and the following issues do not apply to you.)
-
-EasyInstall installs distributions in a "managed" way, such that each
-distribution can be independently activated or deactivated on ``sys.path``.
-However, packages that were not installed by EasyInstall are "unmanaged",
-in that they usually live all in one directory and cannot be independently
-activated or deactivated.
-
-As a result, if you are using EasyInstall to upgrade an existing package, or
-to install a package with the same name as an existing package, EasyInstall
-will warn you of the conflict. (This is an improvement over ``setup.py
-install``, because the ``distutils`` just install new packages on top of old
-ones, possibly combining two unrelated packages or leaving behind modules that
-have been deleted in the newer version of the package.)
-
-EasyInstall will stop the installation if it detects a conflict
-between an existing, "unmanaged" package, and a module or package in any of
-the distributions you're installing. It will display a list of all of the
-existing files and directories that would need to be deleted for the new
-package to be able to function correctly. To proceed, you must manually
-delete these conflicting files and directories and re-run EasyInstall.
-
-Of course, once you've replaced all of your existing "unmanaged" packages with
-versions managed by EasyInstall, you won't have any more conflicts to worry
-about!
-
-
-Compressed Installation
-~~~~~~~~~~~~~~~~~~~~~~~
-
-EasyInstall tries to install packages in zipped form, if it can. Zipping
-packages can improve Python's overall import performance if you're not using
-the ``--multi-version`` option, because Python processes zipfile entries on
-``sys.path`` much faster than it does directories.
-
-As of version 0.5a9, EasyInstall analyzes packages to determine whether they
-can be safely installed as a zipfile, and then acts on its analysis. (Previous
-versions would not install a package as a zipfile unless you used the
-``--zip-ok`` option.)
-
-The current analysis approach is fairly conservative; it currently looks for:
-
- * Any use of the ``__file__`` or ``__path__`` variables (which should be
- replaced with ``pkg_resources`` API calls)
-
- * Possible use of ``inspect`` functions that expect to manipulate source files
- (e.g. ``inspect.getsource()``)
-
- * Top-level modules that might be scripts used with ``python -m`` (Python 2.4)
-
-If any of the above are found in the package being installed, EasyInstall will
-assume that the package cannot be safely run from a zipfile, and unzip it to
-a directory instead. You can override this analysis with the ``-zip-ok`` flag,
-which will tell EasyInstall to install the package as a zipfile anyway. Or,
-you can use the ``--always-unzip`` flag, in which case EasyInstall will always
-unzip, even if its analysis says the package is safe to run as a zipfile.
-
-Normally, however, it is simplest to let EasyInstall handle the determination
-of whether to zip or unzip, and only specify overrides when needed to work
-around a problem. If you find you need to override EasyInstall's guesses, you
-may want to contact the package author and the EasyInstall maintainers, so that
-they can make appropriate changes in future versions.
-
-(Note: If a package uses ``setuptools`` in its setup script, the package author
-has the option to declare the package safe or unsafe for zipped usage via the
-``zip_safe`` argument to ``setup()``. If the package author makes such a
-declaration, EasyInstall believes the package's author and does not perform its
-own analysis. However, your command-line option, if any, will still override
-the package author's choice.)
-
-
-Reference Manual
-================
-
-Configuration Files
--------------------
-
-(New in 0.4a2)
-
-You may specify default options for EasyInstall using the standard
-distutils configuration files, under the command heading ``easy_install``.
-EasyInstall will look first for a ``setup.cfg`` file in the current directory,
-then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
-and Windows, respectively), and finally a ``distutils.cfg`` file in the
-``distutils`` package directory. Here's a simple example:
-
-.. code-block:: ini
-
- [easy_install]
-
- # set the default location to install packages
- install_dir = /home/me/lib/python
-
- # Notice that indentation can be used to continue an option
- # value; this is especially useful for the "--find-links"
- # option, which tells easy_install to use download links on
- # these pages before consulting PyPI:
- #
- find_links = http://sqlobject.org/
- http://peak.telecommunity.com/dist/
-
-In addition to accepting configuration for its own options under
-``[easy_install]``, EasyInstall also respects defaults specified for other
-distutils commands. For example, if you don't set an ``install_dir`` for
-``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
-command, this will become EasyInstall's default installation directory. Thus,
-if you are already using distutils configuration files to set default install
-locations, build options, etc., EasyInstall will respect your existing settings
-until and unless you override them explicitly in an ``[easy_install]`` section.
-
-For more information, see also the current Python documentation on the `use and
-location of distutils configuration files <https://docs.python.org/install/index.html#inst-config-files>`_.
-
-Notice that ``easy_install`` will use the ``setup.cfg`` from the current
-working directory only if it was triggered from ``setup.py`` through the
-``install_requires`` option. The standalone command will not use that file.
-
-Command-Line Options
---------------------
-
-``--zip-ok, -z``
- Install all packages as zip files, even if they are marked as unsafe for
- running as a zipfile. This can be useful when EasyInstall's analysis
- of a non-setuptools package is too conservative, but keep in mind that
- the package may not work correctly. (Changed in 0.5a9; previously this
- option was required in order for zipped installation to happen at all.)
-
-``--always-unzip, -Z``
- Don't install any packages as zip files, even if the packages are marked
- as safe for running as a zipfile. This can be useful if a package does
- something unsafe, but not in a way that EasyInstall can easily detect.
- EasyInstall's default analysis is currently very conservative, however, so
- you should only use this option if you've had problems with a particular
- package, and *after* reporting the problem to the package's maintainer and
- to the EasyInstall maintainers.
-
- (Note: the ``-z/-Z`` options only affect the installation of newly-built
- or downloaded packages that are not already installed in the target
- directory; if you want to convert an existing installed version from
- zipped to unzipped or vice versa, you'll need to delete the existing
- version first, and re-run EasyInstall.)
-
-``--multi-version, -m``
- "Multi-version" mode. Specifying this option prevents ``easy_install`` from
- adding an ``easy-install.pth`` entry for the package being installed, and
- if an entry for any version the package already exists, it will be removed
- upon successful installation. 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``. This can be as
- simple as::
-
- from pkg_resources import require
- require("SomePackage", "OtherPackage", "MyPackage")
-
- which will put the latest installed version of the specified packages on
- ``sys.path`` for you. (For more advanced uses, like selecting specific
- versions and enabling optional dependencies, see the ``pkg_resources`` API
- doc.)
-
- Changed in 0.6a10: this option is no longer silently enabled when
- installing to a non-PYTHONPATH, non-"site" directory. You must always
- explicitly use this option if you want it to be active.
-
-``--upgrade, -U`` (New in 0.5a4)
- By default, EasyInstall only searches online if a project/version
- requirement can't be met by distributions already installed
- on sys.path or the installation directory. However, if you supply the
- ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
- index and ``--find-links`` URLs before selecting a version to install. In
- this way, you can force EasyInstall to use the latest available version of
- any package it installs (subject to any version requirements that might
- exclude such later versions).
-
-``--install-dir=DIR, -d DIR``
- Set the installation directory. It is up to you to ensure that this
- directory is on ``sys.path`` at runtime, and to use
- ``pkg_resources.require()`` to enable the installed package(s) that you
- need.
-
- (New in 0.4a2) 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 would 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 installation directory, as is the
- ``--prefix`` option.
-
-``--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 install scripts. This is useful if you need to install multiple
- versions of a package, but do not want to reset the version that will be
- run by scripts that are already installed.
-
-``--user`` (New in 0.6.11)
- Use the user-site-packages as specified in :pep:`370`
- instead of the global site-packages.
-
-``--always-copy, -a`` (New in 0.5a4)
- Copy all needed distributions to the installation directory, even if they
- are already present in a directory on sys.path. In older versions of
- EasyInstall, this was the default behavior, but now you must explicitly
- request it. By default, EasyInstall will no longer copy such distributions
- from other sys.path directories to the installation directory, unless you
- explicitly gave the distribution's filename on the command line.
-
- Note that as of 0.6a10, using this option excludes "system" and
- "development" eggs from consideration because they can't be reliably
- copied. 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 copy of something that's already installed. You will see warning
- messages for any eggs that EasyInstall skips, before it falls back to an
- older version or attempts to download a fresh copy.
-
-``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
- Scan the specified "download pages" or directories for direct links to eggs
- or other distributions. Any existing file or directory names or direct
- download URLs are immediately added to EasyInstall's search cache, and any
- indirect URLs (ones that don't point to eggs or other recognized archive
- formats) are added to a list of additional places to search for download
- links. As soon as EasyInstall has to go online to find a package (either
- because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
- used), the specified URLs will be downloaded and scanned for additional
- direct links.
-
- Eggs and archives found by way of ``--find-links`` are only downloaded if
- they are needed to meet a requirement specified on the command line; links
- to unneeded packages are ignored.
-
- If all requested packages can be found using links on the specified
- download pages, the Python Package Index will not be consulted unless you
- also specified the ``--upgrade`` or ``-U`` option.
-
- (Note: if you want to refer to a local HTML file containing links, you must
- use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
- archive are ignored.)
-
- You may specify multiple URLs or file/directory names with this option,
- separated by whitespace. Note that on the command line, you will probably
- have to surround the URL list with quotes, so that it is recognized as a
- single option value. You can also specify URLs in a configuration file;
- see `Configuration Files`_, above.
-
- Changed in 0.6a10: previously all URLs and directories passed to this
- option were scanned as early as possible, but from 0.6a10 on, 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.
-
-``--no-find-links`` Blocks the addition of any link.
- This parameter is useful if you want to avoid adding links defined in a
- project easy_install is installing (whether it's a requested project or a
- dependency). When used, ``--find-links`` is ignored.
-
- Added in Distribute 0.6.11 and Setuptools 0.7.
-
-``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
- Specifies the base URL of the Python Package Index. The default is
- https://pypi.org/simple/ if not specified. When a package is requested
- that is not locally available or linked from a ``--find-links`` download
- page, the package index will be searched for download pages for the needed
- package, and those download pages will be searched for links to download
- an egg or source distribution.
-
-``--editable, -e`` (New in 0.6a1)
- Only find and download source distributions for the specified projects,
- unpacking them to subdirectories of the specified ``--build-directory``.
- EasyInstall will not actually build or install the requested projects or
- their dependencies; it will just find and extract them for you. See
- `Editing and Viewing Source Packages`_ above for more details.
-
-``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
- Set the directory used to build source packages. If a package is built
- from a source distribution or checkout, it will be extracted to a
- subdirectory of the specified directory. The subdirectory will have the
- same name as the extracted distribution's project, but in all-lowercase.
- If a file or directory of that name already exists in the given directory,
- a warning will be printed to the console, and the build will take place in
- a temporary directory instead.
-
- This option is most useful in combination with the ``--editable`` option,
- which forces EasyInstall to *only* find and extract (but not build and
- install) source distributions. See `Editing and Viewing Source Packages`_,
- above, for more information.
-
-``--verbose, -v, --quiet, -q`` (New in 0.4a4)
- Control the level of detail of EasyInstall's progress messages. The
- default detail level is "info", which prints information only about
- relatively time-consuming operations like running a setup script, unpacking
- an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the
- detail level to "warn", which will only display installation reports,
- warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail
- level to include individual file-level operations, link analysis messages,
- and distutils messages from any setup scripts that get run. If you include
- the ``-v`` option more than once, the second and subsequent uses are passed
- down to any setup scripts, increasing the verbosity of their reporting as
- well.
-
-``--dry-run, -n`` (New in 0.4a4)
- Don't actually install the package or scripts. This option is passed down
- to any setup scripts run, so packages should not actually build either.
- This does *not* skip downloading, nor does it skip extracting source
- distributions to a temporary/build directory.
-
-``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
- If you are installing from a source distribution, and are *not* using the
- ``--zip-ok`` option, this option controls the optimization level for
- compiling installed ``.py`` files to ``.pyo`` files. It does not affect
- the compilation of modules contained in ``.egg`` files, only those in
- ``.egg`` directories. The optimization level can be set to 0, 1, or 2;
- the default is 0 (unless it's set under ``install`` or ``install_lib`` in
- one of your distutils configuration files).
-
-``--record=FILENAME`` (New in 0.5a4)
- Write a record of all installed files to FILENAME. This is basically the
- same as the same option for the standard distutils "install" command, and
- is included for compatibility with tools that expect to pass this option
- to "setup.py install".
-
-``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1)
- Specify one or more custom "site" directories (separated by commas).
- "Site" directories are directories where ``.pth`` files are processed, such
- as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall
- automatically detects whether a given directory processes ``.pth`` files
- (or can be made to do so), so you should not normally need to use this
- option. It is is now only necessary if you want to override EasyInstall's
- judgment and force an installation directory to be treated as if it
- supported ``.pth`` files.
-
-``--no-deps, -N`` (New in 0.6a6)
- Don't install any dependencies. This is intended as a convenience for
- tools that wrap eggs in a platform-specific packaging system. (We don't
- recommend that you use it for anything else.)
-
-``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6)
- Restrict downloading and spidering to hosts matching the specified glob
- patterns. E.g. ``-H *.python.org`` restricts web access so that only
- packages listed and downloadable from machines in the ``python.org``
- domain. The glob patterns must match the *entire* user/host/port section of
- the target URL(s). For example, ``*.python.org`` will NOT accept a URL
- like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
- Multiple patterns can be specified by separating them with commas. The
- default pattern is ``*``, which matches anything.
-
- In general, this option is mainly useful for blocking EasyInstall's web
- access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
- or other trusted site. EasyInstall will do the best it can to satisfy
- dependencies given your host restrictions, but of course can fail if it
- can't find suitable packages. EasyInstall displays all blocked URLs, so
- that you can adjust your ``--allow-hosts`` setting if it is more strict
- than you intended. Some sites may wish to define a restrictive default
- setting for this option in their `configuration files`_, and then manually
- override the setting on the command line as needed.
-
-``--prefix=DIR`` (New in 0.6a10)
- Use the specified directory as a base for computing the default
- installation and script directories. On Windows, the resulting default
- directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
- while on other platforms the defaults will be
- ``prefix/lib/python2.X/site-packages`` (with the appropriate version
- substituted) for libraries and ``prefix/bin`` for scripts.
-
- Note that the ``--prefix`` option only sets the *default* installation and
- script directories, and does not override the ones set on the command line
- or in a configuration file.
-
-``--local-snapshots-ok, -l`` (New in 0.6c6)
- Normally, EasyInstall prefers to only install *released* versions of
- projects, not in-development ones, because such projects may not
- have a currently-valid version number. So, it usually only installs them
- when their ``setup.py`` directory is explicitly passed on the command line.
-
- However, if this option is used, then any in-development projects that were
- installed using the ``setup.py develop`` command, will be used to build
- eggs, effectively upgrading the "in-development" project to a snapshot
- release. Normally, this option is used only in conjunction with the
- ``--always-copy`` option to create a distributable snapshot of every egg
- needed to run an application.
-
- Note that if you use this option, you must make sure that there is a valid
- version number (such as an SVN revision number tag) for any in-development
- projects that may be used, as otherwise EasyInstall may not be able to tell
- what version of the project is "newer" when future installations or
- upgrades are attempted.
-
-
-.. _non-root installation:
-
-Custom Installation Locations
------------------------------
-
-By default, EasyInstall installs python packages into Python's main ``site-packages`` directory,
-and manages them using a custom ``.pth`` file in that same directory.
-
-Very often though, a user or developer wants ``easy_install`` to install and manage python packages
-in an alternative location, usually for one of 3 reasons:
-
-1. They don't have access to write to the main Python site-packages directory.
-
-2. They want a user-specific stash of packages, that is not visible to other users.
-
-3. They want to isolate a set of packages to a specific python application, usually to minimize
- the possibility of version conflicts.
-
-Historically, there have been many approaches to achieve custom installation.
-The following section lists only the easiest and most relevant approaches [1]_.
-
-`Use the "--user" option`_
-
-`Use the "--user" option and customize "PYTHONUSERBASE"`_
-
-`Use "virtualenv"`_
-
-.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_.
-
-.. _PEP-370: http://www.python.org/dev/peps/pep-0370/
-
-
-Use the "--user" option
-~~~~~~~~~~~~~~~~~~~~~~~
-Python provides a User scheme for installation, which means that all
-python distributions support an alternative install location that is specific to a user [3]_.
-The Default location for each OS is explained in the python documentation
-for the ``site.USER_BASE`` variable. This mode of installation can be turned on by
-specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
-This approach serves the need to have a user-specific stash of packages.
-
-.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.
-
-Use the "--user" option and customize "PYTHONUSERBASE"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment
-variable, which updates the value of ``site.USER_BASE``. To isolate packages to a specific
-application, simply set the OS environment of that application to a specific value of
-``PYTHONUSERBASE``, that contains just those packages.
-
-Use "virtualenv"
-~~~~~~~~~~~~~~~~
-"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby
-creating an isolated location to install packages. The evolution of "virtualenv" started before the existence
-of the User installation scheme. "virtualenv" provides a version of ``easy_install`` that is
-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/
-
-
-
-Package Index "API"
--------------------
-
-Custom package indexes (and PyPI) must follow the following rules for
-EasyInstall to be able to look up and download packages:
-
-1. Except where stated otherwise, "pages" are HTML or XHTML, and "links"
- refer to ``href`` attributes.
-
-2. Individual project version pages' URLs must be of the form
- ``base/projectname/version``, where ``base`` is the package index's base URL.
-
-3. Omitting the ``/version`` part of a project page's URL (but keeping the
- trailing ``/``) should result in a page that is either:
-
- a) The single active version of that project, as though the version had been
- explicitly included, OR
-
- b) A page with links to all of the active version pages for that project.
-
-4. Individual project version pages should contain direct links to downloadable
- distributions where possible. It is explicitly permitted for a project's
- "long_description" to include URLs, and these should be formatted as HTML
- links by the package index, as EasyInstall does no special processing to
- identify what parts of a page are index-specific and which are part of the
- project's supplied description.
-
-5. Where available, MD5 information should be added to download URLs by
- appending a fragment identifier of the form ``#md5=...``, where ``...`` is
- the 32-character hex MD5 digest. EasyInstall will verify that the
- downloaded file's MD5 digest matches the given value.
-
-6. Individual project version pages should identify any "homepage" or
- "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
- on the HTML elements linking to those URLs. Use of these attributes will
- cause EasyInstall to always follow the provided links, unless it can be
- determined by inspection that they are downloadable distributions. If the
- links are not to downloadable distributions, they are retrieved, and if they
- are HTML, they are scanned for download links. They are *not* scanned for
- additional "homepage" or "download" links, as these are only processed for
- pages that are part of a package index site.
-
-7. The root URL of the index, if retrieved with a trailing ``/``, must result
- in a page containing links to *all* projects' active version pages.
-
- (Note: This requirement is a workaround for the absence of case-insensitive
- ``safe_name()`` matching of project names in URL paths. If project names are
- matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
- mechanism), then it is not necessary to include this all-packages listing
- page.)
-
-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.
+++ /dev/null
-=====================================
-The Internal Structure of Python Eggs
-=====================================
-
-STOP! This is not the first document you should read!
-
-
-
-.. contents:: **Table of Contents**
-
-
-----------------------
-Eggs and their Formats
-----------------------
-
-A "Python egg" is a logical structure embodying the release of a
-specific version of a Python project, comprising its code, resources,
-and metadata. There are multiple formats that can be used to physically
-encode a Python egg, and others can be developed. However, a key
-principle of Python eggs is that they should be discoverable and
-importable. That is, it should be possible for a Python application to
-easily and efficiently find out what eggs are present on a system, and
-to ensure that the desired eggs' contents are importable.
-
-There are two basic formats currently implemented for Python eggs:
-
-1. ``.egg`` format: a directory or zipfile *containing* the project's
- code and resources, along with an ``EGG-INFO`` subdirectory that
- contains the project's metadata
-
-2. ``.egg-info`` format: a file or directory placed *adjacent* to the
- project's code and resources, that directly contains the project's
- metadata.
-
-Both formats can include arbitrary Python code and resources, including
-static data files, package and non-package directories, Python
-modules, C extension modules, and so on. But each format is optimized
-for different purposes.
-
-The ``.egg`` format is well-suited to distribution and the easy
-uninstallation or upgrades of code, since the project is essentially
-self-contained within a single directory or file, unmingled with any
-other projects' code or resources. It also makes it possible to have
-multiple versions of a project simultaneously installed, such that
-individual programs can select the versions they wish to use.
-
-The ``.egg-info`` format, on the other hand, was created to support
-backward-compatibility, performance, and ease of installation for system
-packaging tools that expect to install all projects' code and resources
-to a single directory (e.g. ``site-packages``). Placing the metadata
-in that same directory simplifies the installation process, since it
-isn't necessary to create ``.pth`` files or otherwise modify
-``sys.path`` to include each installed egg.
-
-Its disadvantage, however, is that it provides no support for clean
-uninstallation or upgrades, and of course only a single version of a
-project can be installed to a given directory. Thus, support from a
-package management tool is required. (This is why setuptools' "install"
-command refers to this type of egg installation as "single-version,
-externally managed".) Also, they lack sufficient data to allow them to
-be copied from their installation source. easy_install can "ship" an
-application by copying ``.egg`` files or directories to a target
-location, but it cannot do this for ``.egg-info`` installs, because
-there is no way to tell what code and resources belong to a particular
-egg -- there may be several eggs "scrambled" together in a single
-installation location, and the ``.egg-info`` format does not currently
-include a way to list the files that were installed. (This may change
-in a future version.)
-
-
-Code and Resources
-==================
-
-The layout of the code and resources is dictated by Python's normal
-import layout, relative to the egg's "base location".
-
-For the ``.egg`` format, the base location is the ``.egg`` itself. That
-is, adding the ``.egg`` filename or directory name to ``sys.path``
-makes its contents importable.
-
-For the ``.egg-info`` format, however, the base location is the
-directory that *contains* the ``.egg-info``, and thus it is the
-directory that must be added to ``sys.path`` to make the egg importable.
-(Note that this means that the "normal" installation of a package to a
-``sys.path`` directory is sufficient to make it an "egg" if it has an
-``.egg-info`` file or directory installed alongside of it.)
-
-
-Project Metadata
-=================
-
-If eggs contained only code and resources, there would of course be
-no difference between them and any other directory or zip file on
-``sys.path``. Thus, metadata must also be included, using a metadata
-file or directory.
-
-For the ``.egg`` format, the metadata is placed in an ``EGG-INFO``
-subdirectory, directly within the ``.egg`` file or directory. For the
-``.egg-info`` format, metadata is stored directly within the
-``.egg-info`` directory itself.
-
-The minimum project metadata that all eggs must have is a standard
-Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the
-metadata directory appropriate to the format. Because it's possible for
-this to be the only metadata file included, ``.egg-info`` format eggs
-are not required to be a directory; they can just be a ``.egg-info``
-file that directly contains the ``PKG-INFO`` metadata. This eliminates
-the need to create a directory just to store one file. This option is
-*not* available for ``.egg`` formats, since setuptools always includes
-other metadata. (In fact, setuptools itself never generates
-``.egg-info`` files, either; the support for using files was added so
-that the requirement could easily be satisfied by other tools, such
-as distutils).
-
-In addition to the ``PKG-INFO`` file, an egg's metadata directory may
-also include files and directories representing various forms of
-optional standard metadata (see the section on `Standard Metadata`_,
-below) or user-defined metadata required by the project. For example,
-some projects may define a metadata format to describe their application
-plugins, and metadata in this format would then be included by plugin
-creators in their projects' metadata directories.
-
-
-Filename-Embedded Metadata
-==========================
-
-To allow introspection of installed projects and runtime resolution of
-inter-project dependencies, a certain amount of information is embedded
-in egg filenames. At a minimum, this includes the project name, and
-ideally will also include the project version number. Optionally, it
-can also include the target Python version and required runtime
-platform if platform-specific C code is included. The syntax of an
-egg filename is as follows::
-
- name ["-" version ["-py" pyver ["-" required_platform]]] "." ext
-
-The "name" and "version" should be escaped using the ``to_filename()``
-function provided by ``pkg_resources``, after first processing them with
-``safe_name()`` and ``safe_version()`` respectively. These latter two
-functions can also be used to later "unescape" these parts of the
-filename. (For a detailed description of these transformations, please
-see the "Parsing Utilities" section of the ``pkg_resources`` manual.)
-
-The "pyver" string is the Python major version, as found in the first
-3 characters of ``sys.version``. "required_platform" is essentially
-a distutils ``get_platform()`` string, but with enhancements to properly
-distinguish Mac OS versions. (See the ``get_build_platform()``
-documentation in the "Platform Utilities" section of the
-``pkg_resources`` manual for more details.)
-
-Finally, the "ext" is either ``.egg`` or ``.egg-info``, as appropriate
-for the egg's format.
-
-Normally, an egg's filename should include at least the project name and
-version, as this allows the runtime system to find desired project
-versions without having to read the egg's PKG-INFO to determine its
-version number.
-
-Setuptools, however, only includes the version number in the filename
-when an ``.egg`` file is built using the ``bdist_egg`` command, or when
-an ``.egg-info`` directory is being installed by the
-``install_egg_info`` command. When generating metadata for use with the
-original source tree, it only includes the project name, so that the
-directory will not have to be renamed each time the project's version
-changes.
-
-This is especially important when version numbers change frequently, and
-the source metadata directory is kept under version control with the
-rest of the project. (As would be the case when the project's source
-includes project-defined metadata that is not generated from by
-setuptools from data in the setup script.)
-
-
-Egg Links
-=========
-
-In addition to the ``.egg`` and ``.egg-info`` formats, there is a third
-egg-related extension that you may encounter on occasion: ``.egg-link``
-files.
-
-These files are not eggs, strictly speaking. They simply provide a way
-to reference an egg that is not physically installed in the desired
-location. They exist primarily as a cross-platform alternative to
-symbolic links, to support "installing" code that is being developed in
-a different location than the desired installation location. For
-example, if a user is developing an application plugin in their home
-directory, but the plugin needs to be "installed" in an application
-plugin directory, running "setup.py develop -md /path/to/app/plugins"
-will install an ``.egg-link`` file in ``/path/to/app/plugins``, that
-tells the egg runtime system where to find the actual egg (the user's
-project source directory and its ``.egg-info`` subdirectory).
-
-``.egg-link`` files are named following the format for ``.egg`` and
-``.egg-info`` names, but only the project name is included; no version,
-Python version, or platform information is included. When the runtime
-searches for available eggs, ``.egg-link`` files are opened and the
-actual egg file/directory name is read from them.
-
-Each ``.egg-link`` file should contain a single file or directory name,
-with no newlines. This filename should be the base location of one or
-more eggs. That is, the name must either end in ``.egg``, or else it
-should be the parent directory of one or more ``.egg-info`` format eggs.
-
-As of setuptools 0.6c6, the path may be specified as a platform-independent
-(i.e. ``/``-separated) relative path from the directory containing the
-``.egg-link`` file, and a second line may appear in the file, specifying a
-platform-independent relative path from the egg's base directory to its
-setup script directory. This allows installation tools such as EasyInstall
-to find the project's setup directory and build eggs or perform other setup
-commands on it.
-
-
------------------
-Standard Metadata
------------------
-
-In addition to the minimum required ``PKG-INFO`` metadata, projects can
-include a variety of standard metadata files or directories, as
-described below. Except as otherwise noted, these files and directories
-are automatically generated by setuptools, based on information supplied
-in the setup script or through analysis of the project's code and
-resources.
-
-Most of these files and directories are generated via "egg-info
-writers" during execution of the setuptools ``egg_info`` command, and
-are listed in the ``egg_info.writers`` entry point group defined by
-setuptools' own ``setup.py`` file.
-
-Project authors can register their own metadata writers as entry points
-in this group (as described in the setuptools manual under "Adding new
-EGG-INFO Files") to cause setuptools to generate project-specific
-metadata files or directories during execution of the ``egg_info``
-command. It is up to project authors to document these new metadata
-formats, if they create any.
-
-
-``.txt`` File Formats
-=====================
-
-Files described in this section that have ``.txt`` extensions have a
-simple lexical format consisting of a sequence of text lines, each line
-terminated by a linefeed character (regardless of platform). Leading
-and trailing whitespace on each line is ignored, as are blank lines and
-lines whose first nonblank character is a ``#`` (comment symbol). (This
-is the parsing format defined by the ``yield_lines()`` function of
-the ``pkg_resources`` module.)
-
-All ``.txt`` files defined by this section follow this format, but some
-are also "sectioned" files, meaning that their contents are divided into
-sections, using square-bracketed section headers akin to Windows
-``.ini`` format. Note that this does *not* imply that the lines within
-the sections follow an ``.ini`` format, however. Please see an
-individual metadata file's documentation for a description of what the
-lines and section names mean in that particular file.
-
-Sectioned files can be parsed using the ``split_sections()`` function;
-see the "Parsing Utilities" section of the ``pkg_resources`` manual for
-for details.
-
-
-Dependency Metadata
-===================
-
-
-``requires.txt``
-----------------
-
-This is a "sectioned" text file. Each section is a sequence of
-"requirements", as parsed by the ``parse_requirements()`` function;
-please see the ``pkg_resources`` manual for the complete requirement
-parsing syntax.
-
-The first, unnamed section (i.e., before the first section header) in
-this file is the project's core requirements, which must be installed
-for the project to function. (Specified using the ``install_requires``
-keyword to ``setup()``).
-
-The remaining (named) sections describe the project's "extra"
-requirements, as specified using the ``extras_require`` keyword to
-``setup()``. The section name is the name of the optional feature, and
-the section body lists that feature's dependencies.
-
-Note that it is not normally necessary to inspect this file directly;
-``pkg_resources.Distribution`` objects have a ``requires()`` method
-that can be used to obtain ``Requirement`` objects describing the
-project's core and optional dependencies.
-
-
-``setup_requires.txt``
-----------------------
-
-Much like ``requires.txt`` except represents the requirements
-specified by the ``setup_requires`` parameter to the Distribution.
-
-
-``dependency_links.txt``
-------------------------
-
-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. Please see the setuptools manual for more information on
-specifying this option.
-
-
-``depends.txt`` -- Obsolete, do not create!
--------------------------------------------
-
-This file follows an identical format to ``requires.txt``, but is
-obsolete and should not be used. The earliest versions of setuptools
-required users to manually create and maintain this file, so the runtime
-still supports reading it, if it exists. The new filename was created
-so that it could be automatically generated from ``setup()`` information
-without overwriting an existing hand-created ``depends.txt``, if one
-was already present in the project's source ``.egg-info`` directory.
-
-
-``namespace_packages.txt`` -- Namespace Package Metadata
-========================================================
-
-A list of namespace package names, one per line, as supplied to the
-``namespace_packages`` keyword to ``setup()``. Please see the manuals
-for setuptools and ``pkg_resources`` for more information about
-namespace packages.
-
-
-``entry_points.txt`` -- "Entry Point"/Plugin Metadata
-=====================================================
-
-This is a "sectioned" text file, whose contents encode the
-``entry_points`` keyword supplied to ``setup()``. All sections are
-named, as the section names specify the entry point groups in which the
-corresponding section's entry points are registered.
-
-Each section is a sequence of "entry point" lines, each parseable using
-the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources``
-manual for the complete entry point parsing syntax.
-
-Note that it is not necessary to parse this file directly; the
-``pkg_resources`` module provides a variety of APIs to locate and load
-entry points automatically. Please see the setuptools and
-``pkg_resources`` manuals for details on the nature and uses of entry
-points.
-
-
-The ``scripts`` Subdirectory
-============================
-
-This directory is currently only created for ``.egg`` files built by
-the setuptools ``bdist_egg`` command. It will contain copies of all
-of the project's "traditional" scripts (i.e., those specified using the
-``scripts`` keyword to ``setup()``). This is so that they can be
-reconstituted when an ``.egg`` file is installed.
-
-The scripts are placed here using the distutils' standard
-``install_scripts`` command, so any ``#!`` lines reflect the Python
-installation where the egg was built. But instead of copying the
-scripts to the local script installation directory, EasyInstall writes
-short wrapper scripts that invoke the original scripts from inside the
-egg, after ensuring that sys.path includes the egg and any eggs it
-depends on. For more about `script wrappers`_, see the section below on
-`Installation and Path Management Issues`_.
-
-
-Zip Support Metadata
-====================
-
-
-``native_libs.txt``
--------------------
-
-A list of C extensions and other dynamic link libraries contained in
-the egg, one per line. Paths are ``/``-separated and relative to the
-egg's base location.
-
-This file is generated as part of ``bdist_egg`` processing, and as such
-only appears in ``.egg`` files (and ``.egg`` directories created by
-unpacking them). It is used to ensure that all libraries are extracted
-from a zipped egg at the same time, in case there is any direct linkage
-between them. Please see the `Zip File Issues`_ section below for more
-information on library and resource extraction from ``.egg`` files.
-
-
-``eager_resources.txt``
------------------------
-
-A list of resource files and/or directories, one per line, as specified
-via the ``eager_resources`` keyword to ``setup()``. Paths are
-``/``-separated and relative to the egg's base location.
-
-Resource files or directories listed here will be extracted
-simultaneously, if any of the named resources are extracted, or if any
-native libraries listed in ``native_libs.txt`` are extracted. Please
-see the setuptools manual for details on what this feature is used for
-and how it works, as well as the `Zip File Issues`_ section below.
-
-
-``zip-safe`` and ``not-zip-safe``
----------------------------------
-
-These are zero-length files, and either one or the other should exist.
-If ``zip-safe`` exists, it means that the project will work properly
-when installed as an ``.egg`` zipfile, and conversely the existence of
-``not-zip-safe`` means the project should not be installed as an
-``.egg`` file. The ``zip_safe`` option to setuptools' ``setup()``
-determines which file will be written. If the option isn't provided,
-setuptools attempts to make its own assessment of whether the package
-can work, based on code and content analysis.
-
-If neither file is present at installation time, EasyInstall defaults
-to assuming that the project should be unzipped. (Command-line options
-to EasyInstall, however, take precedence even over an existing
-``zip-safe`` or ``not-zip-safe`` file.)
-
-Note that these flag files appear only in ``.egg`` files generated by
-``bdist_egg``, and in ``.egg`` directories created by unpacking such an
-``.egg`` file.
-
-
-
-``top_level.txt`` -- Conflict Management Metadata
-=================================================
-
-This file is a list of the top-level module or package names provided
-by the project, one Python identifier per line.
-
-Subpackages are not included; a project containing both a ``foo.bar``
-and a ``foo.baz`` would include only one line, ``foo``, in its
-``top_level.txt``.
-
-This data is used by ``pkg_resources`` at runtime to issue a warning if
-an egg is added to ``sys.path`` when its contained packages may have
-already been imported.
-
-(It was also once used to detect conflicts with non-egg packages at
-installation time, but in more recent versions, setuptools installs eggs
-in such a way that they always override non-egg packages, thus
-preventing a problem from arising.)
-
-
-``SOURCES.txt`` -- Source Files Manifest
-========================================
-
-This file is roughly equivalent to the distutils' ``MANIFEST`` file.
-The differences are as follows:
-
-* The filenames always use ``/`` as a path separator, which must be
- converted back to a platform-specific path whenever they are read.
-
-* The file is automatically generated by setuptools whenever the
- ``egg_info`` or ``sdist`` commands are run, and it is *not*
- user-editable.
-
-Although this metadata is included with distributed eggs, it is not
-actually used at runtime for any purpose. Its function is to ensure
-that setuptools-built *source* distributions can correctly discover
-what files are part of the project's source, even if the list had been
-generated using revision control metadata on the original author's
-system.
-
-In other words, ``SOURCES.txt`` has little or no runtime value for being
-included in distributed eggs, and it is possible that future versions of
-the ``bdist_egg`` and ``install_egg_info`` commands will strip it before
-installation or distribution. Therefore, do not rely on its being
-available outside of an original source directory or source
-distribution.
-
-
-------------------------------
-Other Technical Considerations
-------------------------------
-
-
-Zip File Issues
-===============
-
-Although zip files resemble directories, they are not fully
-substitutable for them. Most platforms do not support loading dynamic
-link libraries contained in zipfiles, so it is not possible to directly
-import C extensions from ``.egg`` zipfiles. Similarly, there are many
-existing libraries -- whether in Python or C -- that require actual
-operating system filenames, and do not work with arbitrary "file-like"
-objects or in-memory strings, and thus cannot operate directly on the
-contents of zip files.
-
-To address these issues, the ``pkg_resources`` module provides a
-"resource API" to support obtaining either the contents of a resource,
-or a true operating system filename for the resource. If the egg
-containing the resource is a directory, the resource's real filename
-is simply returned. However, if the egg is a zipfile, then the
-resource is first extracted to a cache directory, and the filename
-within the cache is returned.
-
-The cache directory is determined by the ``pkg_resources`` API; please
-see the ``set_cache_path()`` and ``get_default_cache()`` documentation
-for details.
-
-
-The Extraction Process
-----------------------
-
-Resources are extracted to a cache subdirectory whose name is based
-on the enclosing ``.egg`` filename and the path to the resource. If
-there is already a file of the correct name, size, and timestamp, its
-filename is returned to the requester. Otherwise, the desired file is
-extracted first to a temporary name generated using
-``mkstemp(".$extract",target_dir)``, and then its timestamp is set to
-match the one in the zip file, before renaming it to its final name.
-(Some collision detection and resolution code is used to handle the
-fact that Windows doesn't overwrite files when renaming.)
-
-If a resource directory is requested, all of its contents are
-recursively extracted in this fashion, to ensure that the directory
-name can be used as if it were valid all along.
-
-If the resource requested for extraction is listed in the
-``native_libs.txt`` or ``eager_resources.txt`` metadata files, then
-*all* resources listed in *either* file will be extracted before the
-requested resource's filename is returned, thus ensuring that all
-C extensions and data used by them will be simultaneously available.
-
-
-Extension Import Wrappers
--------------------------
-
-Since Python's built-in zip import feature does not support loading
-C extension modules from zipfiles, the setuptools ``bdist_egg`` command
-generates special import wrappers to make it work.
-
-The wrappers are ``.py`` files (along with corresponding ``.pyc``
-and/or ``.pyo`` files) that have the same module name as the
-corresponding C extension. These wrappers are located in the same
-package directory (or top-level directory) within the zipfile, so that
-say, ``foomodule.so`` will get a corresponding ``foo.py``, while
-``bar/baz.pyd`` will get a corresponding ``bar/baz.py``.
-
-These wrapper files contain a short stanza of Python code that asks
-``pkg_resources`` for the filename of the corresponding C extension,
-then reloads the module using the obtained filename. This will cause
-``pkg_resources`` to first ensure that all of the egg's C extensions
-(and any accompanying "eager resources") are extracted to the cache
-before attempting to link to the C library.
-
-Note, by the way, that ``.egg`` directories will also contain these
-wrapper files. However, Python's default import priority is such that
-C extensions take precedence over same-named Python modules, so the
-import wrappers are ignored unless the egg is a zipfile.
-
-
-Installation and Path Management Issues
-=======================================
-
-Python's initial setup of ``sys.path`` is very dependent on the Python
-version and installation platform, as well as how Python was started
-(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter).
-In fact, Python also provides only two relatively robust ways to affect
-``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH``
-environment variable, and ``.pth`` files.
-
-However, with no cross-platform way to safely and persistently change
-environment variables, this leaves ``.pth`` files as EasyInstall's only
-real option for persistent configuration of ``sys.path``.
-
-But ``.pth`` files are rather strictly limited in what they are allowed
-to do normally. They add directories only to the *end* of ``sys.path``,
-after any locally-installed ``site-packages`` directory, and they are
-only processed *in* the ``site-packages`` directory to start with.
-
-This is a double whammy for users who lack write access to that
-directory, because they can't create a ``.pth`` file that Python will
-read, and even if a sympathetic system administrator adds one for them
-that calls ``site.addsitedir()`` to allow some other directory to
-contain ``.pth`` files, they won't be able to install newer versions of
-anything that's installed in the systemwide ``site-packages``, because
-their paths will still be added *after* ``site-packages``.
-
-So EasyInstall applies two workarounds to solve these problems.
-
-The first is that EasyInstall leverages ``.pth`` files' "import" feature
-to manipulate ``sys.path`` and ensure that anything EasyInstall adds
-to a ``.pth`` file will always appear before both the standard library
-and the local ``site-packages`` directories. Thus, it is always
-possible for a user who can write a Python-read ``.pth`` file to ensure
-that their packages come first in their own environment.
-
-Second, when installing to a ``PYTHONPATH`` directory (as opposed to
-a "site" directory like ``site-packages``) EasyInstall will also install
-a special version of the ``site`` module. Because it's in a
-``PYTHONPATH`` directory, this module will get control before the
-standard library version of ``site`` does. It will record the state of
-``sys.path`` before invoking the "real" ``site`` module, and then
-afterwards it processes any ``.pth`` files found in ``PYTHONPATH``
-directories, including all the fixups needed to ensure that eggs always
-appear before the standard library in sys.path, but are in a relative
-order to one another that is defined by their ``PYTHONPATH`` and
-``.pth``-prescribed sequence.
-
-The net result of these changes is that ``sys.path`` order will be
-as follows at runtime:
-
-1. The ``sys.argv[0]`` directory, or an empty string if no script
- is being executed.
-
-2. All eggs installed by EasyInstall in any ``.pth`` file in each
- ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order,
- then normal ``.pth`` processing order (which is to say alphabetical
- by ``.pth`` filename, then by the order of listing within each
- ``.pth`` file).
-
-3. All eggs installed by EasyInstall in any ``.pth`` file in each "site"
- directory (such as ``site-packages``), following the same ordering
- rules as for the ones on ``PYTHONPATH``.
-
-4. The ``PYTHONPATH`` directories themselves, in their original order
-
-5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not*
- eggs installed by EasyInstall, again following the same relative
- ordering rules.
-
-6. The standard library and "site" directories, along with the contents
- of any ``.pth`` files found in the "site" directories.
-
-Notice that sections 1, 4, and 6 comprise the "normal" Python setup for
-``sys.path``. Sections 2 and 3 are inserted to support eggs, and
-section 5 emulates what the "normal" semantics of ``.pth`` files on
-``PYTHONPATH`` would be if Python natively supported them.
-
-For further discussion of the tradeoffs that went into this design, as
-well as notes on the actual magic inserted into ``.pth`` files to make
-them do these things, please see also the following messages to the
-distutils-SIG mailing list:
-
-* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html
-* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html
-
-
-Script Wrappers
----------------
-
-EasyInstall never directly installs a project's original scripts to
-a script installation directory. Instead, it writes short wrapper
-scripts that first ensure that the project's dependencies are active
-on sys.path, before invoking the original script. These wrappers
-have a #! line that points to the version of Python that was used to
-install them, and their second line is always a comment that indicates
-the type of script wrapper, the project version required for the script
-to run, and information identifying the script to be invoked.
-
-The format of this marker line is::
-
- "# EASY-INSTALL-" script_type ": " tuple_of_strings "\n"
-
-The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or
-``ENTRY-SCRIPT``. The ``tuple_of_strings`` is a comma-separated
-sequence of Python string constants. For ``SCRIPT`` and ``DEV-SCRIPT``
-wrappers, there are two strings: the project version requirement, and
-the script name (as a filename within the ``scripts`` metadata
-directory). For ``ENTRY-SCRIPT`` wrappers, there are three:
-the project version requirement, the entry point group name, and the
-entry point name. (See the "Automatic Script Creation" section in the
-setuptools manual for more information about entry point scripts.)
-
-In each case, the project version requirement string will be a string
-parseable with the ``pkg_resources`` modules' ``Requirement.parse()``
-classmethod. The only difference between a ``SCRIPT`` wrapper and a
-``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original
-source script in the project's source tree, and is created when the
-"setup.py develop" command is run. A ``SCRIPT`` wrapper, on the other
-hand, uses the "installed" script written to the ``EGG-INFO/scripts``
-subdirectory of the corresponding ``.egg`` zipfile or directory.
-(``.egg-info`` eggs do not have script wrappers associated with them,
-except in the "setup.py develop" case.)
-
-The purpose of including the marker line in generated script wrappers is
-to facilitate introspection of installed scripts, and their relationship
-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.
-
--- /dev/null
+:tocdepth: 2
+
+.. _changes:
+
+History
+*******
+
+.. include:: ../CHANGES (links).rst
+
+Credits
+*******
+
+* 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 macOS operating system version
+ compatibility algorithm.
+
+* Ian Bicking implemented many early "creature comfort" features of
+ easy_install, including support for downloading via Sourceforge and
+ Subversion repositories. Ian's comments on the Web-SIG about WSGI
+ application deployment also inspired the concept of "entry points" in eggs,
+ and he has given talks at PyCon and elsewhere to inform and educate the
+ community about eggs and setuptools.
+
+* Jim Fulton contributed time and effort to build automated tests of various
+ aspects of ``easy_install``, and supplied the doctests for the command-line
+ ``.exe`` wrappers on Windows.
+
+* Phillip J. Eby is the seminal author of setuptools, and
+ first proposed the idea of an importable binary distribution format for
+ Python application plug-ins.
+
+* Significant parts of the implementation of setuptools were funded by the Open
+ Source Applications Foundation, to provide a plug-in infrastructure for the
+ Chandler PIM application. In addition, many OSAF staffers (such as Mike
+ "Code Bear" Taylor) contributed their time and stress as guinea pigs for the
+ use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!)
+
+* Tarek Ziadé is the principal author of the Distribute fork, which
+ re-invigorated the community on the project, encouraged renewed innovation,
+ and addressed many defects.
+
+* Jason R. Coombs performed the merge with Distribute, maintaining the
+ project for several years in coordination with the Python Packaging
+ Authority (PyPA).
+++ /dev/null
-:tocdepth: 2
-
-.. _changes:
-
-History
-*******
-
-.. include:: ../CHANGES (links).rst
-
-Credits
-*******
-
-* 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 macOS operating system version
- compatibility algorithm.
-
-* Ian Bicking implemented many early "creature comfort" features of
- easy_install, including support for downloading via Sourceforge and
- Subversion repositories. Ian's comments on the Web-SIG about WSGI
- application deployment also inspired the concept of "entry points" in eggs,
- and he has given talks at PyCon and elsewhere to inform and educate the
- community about eggs and setuptools.
-
-* Jim Fulton contributed time and effort to build automated tests of various
- aspects of ``easy_install``, and supplied the doctests for the command-line
- ``.exe`` wrappers on Windows.
-
-* Phillip J. Eby is the seminal author of setuptools, and
- first proposed the idea of an importable binary distribution format for
- Python application plug-ins.
-
-* Significant parts of the implementation of setuptools were funded by the Open
- Source Applications Foundation, to provide a plug-in infrastructure for the
- Chandler PIM application. In addition, many OSAF staffers (such as Mike
- "Code Bear" Taylor) contributed their time and stress as guinea pigs for the
- use of eggs and setuptools, even before eggs were "cool". (Thanks, guys!)
-
-* Tarek Ziadé is the principal author of the Distribute fork, which
- re-invigorated the community on the project, encouraged renewed innovation,
- and addressed many defects.
-
-* Jason R. Coombs performed the merge with Distribute, maintaining the
- project for several years in coordination with the Python Packaging
- Authority (PyPA).
--- /dev/null
+Documentation
+=============
+
+Setuptools is a fully-featured, actively-maintained, and stable library
+designed to facilitate packaging Python projects.
+
+Documentation content:
+
+.. toctree::
+ :maxdepth: 1
+
+ User guide <userguide/index>
+ Development guide <development>
+ Backward compatibility & deprecated practice <deprecated/index>
+++ /dev/null
-Documentation
-=============
-
-Setuptools is a fully-featured, actively-maintained, and stable library
-designed to facilitate packaging Python projects.
-
-Documentation content:
-
-.. toctree::
- :maxdepth: 2
-
- setuptools
- pkg_resources
- python3
- development
- roadmap
- Deprecated: Easy Install <easy_install>
- distutils-legacy
- history
+++ /dev/null
-``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.
-
-``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`.
-
-``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`.
-
-``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.
-
-``use_2to3_exclude_fixers``
- List of fixer names to be skipped.
-
-``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.
--- /dev/null
+=============================================================
+Package Discovery and Resource Access using ``pkg_resources``
+=============================================================
+
+The ``pkg_resources`` module distributed with ``setuptools`` provides an API
+for Python libraries to access their resource files, and for extensible
+applications and frameworks to automatically discover plugins. It also
+provides runtime support for using C extensions that are inside zipfile-format
+eggs, support for merging packages that have separately-distributed modules or
+subpackages, and APIs for managing Python's current "working set" of active
+packages.
+
+
+.. contents:: **Table of Contents**
+
+
+--------
+Overview
+--------
+
+The ``pkg_resources`` module provides runtime facilities for finding,
+introspecting, activating and using installed Python distributions. Some
+of the more advanced features (notably the support for parallel installation
+of multiple versions) rely specifically on the "egg" format (either as a
+zip archive or subdirectory), while others (such as plugin discovery) will
+work correctly so long as "egg-info" metadata directories are available for
+relevant distributions.
+
+Eggs are a distribution format for Python modules, similar in concept to
+Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427.
+However, unlike a pure distribution format, eggs can also be installed and
+added directly to ``sys.path`` as an import location. When installed in
+this way, eggs are *discoverable*, meaning that they carry metadata that
+unambiguously identifies their contents and dependencies. This means that
+an installed egg can be *automatically* found and added to ``sys.path`` in
+response to simple requests of the form, "get me everything I need to use
+docutils' PDF support". This feature allows mutually conflicting versions of
+a distribution to co-exist in the same Python installation, with individual
+applications activating the desired version at runtime by manipulating the
+contents of ``sys.path`` (this differs from the virtual environment
+approach, which involves creating isolated environments for each
+application).
+
+The following terms are needed in order to explain the capabilities offered
+by this module:
+
+project
+ A library, framework, script, plugin, application, or collection of data
+ or other resources, or some combination thereof. Projects are assumed to
+ have "relatively unique" names, e.g. names registered with PyPI.
+
+release
+ A snapshot of a project at a particular point in time, denoted by a version
+ identifier.
+
+distribution
+ A file or files that represent a particular release.
+
+importable distribution
+ A file or directory that, if placed on ``sys.path``, allows Python to
+ import any modules contained within it.
+
+pluggable distribution
+ An importable distribution whose filename unambiguously identifies its
+ release (i.e. project and version), and whose contents unambiguously
+ specify what releases of other projects will satisfy its runtime
+ requirements.
+
+extra
+ An "extra" is an optional feature of a release, that may impose additional
+ runtime requirements. For example, if docutils PDF support required a
+ PDF support library to be present, docutils could define its PDF support as
+ an "extra", and list what other project releases need to be available in
+ order to provide it.
+
+environment
+ A collection of distributions potentially available for importing, but not
+ necessarily active. More than one distribution (i.e. release version) for
+ a given project may be present in an environment.
+
+working set
+ A collection of distributions actually available for importing, as on
+ ``sys.path``. At most one distribution (release version) of a given
+ project may be present in a working set, as otherwise there would be
+ ambiguity as to what to import.
+
+eggs
+ Eggs are pluggable distributions in one of the three formats currently
+ supported by ``pkg_resources``. There are built eggs, development eggs,
+ and egg links. Built eggs are directories or zipfiles whose name ends
+ with ``.egg`` and follows the egg naming conventions, and contain an
+ ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are
+ normal directories of Python code with one or more ``ProjectName.egg-info``
+ subdirectories. The development egg format is also used to provide a
+ default version of a distribution that is available to software that
+ doesn't use ``pkg_resources`` to request specific versions. Egg links
+ are ``*.egg-link`` files that contain the name of a built or
+ development egg, to support symbolic linking on platforms that do not
+ have native symbolic links (or where the symbolic link support is
+ limited).
+
+(For more information about these terms and concepts, see also this
+`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.)
+
+.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html
+
+
+.. -----------------
+.. Developer's Guide
+.. -----------------
+
+.. This section isn't written yet. Currently planned topics include
+ Accessing Resources
+ Finding and Activating Package Distributions
+ get_provider()
+ require()
+ WorkingSet
+ iter_distributions
+ Running Scripts
+ Configuration
+ Namespace Packages
+ Extensible Applications and Frameworks
+ Locating entry points
+ Activation listeners
+ Metadata access
+ Extended Discovery and Installation
+ Supporting Custom PEP 302 Implementations
+.. For now, please check out the extensive `API Reference`_ below.
+
+
+-------------
+API Reference
+-------------
+
+Namespace Package Support
+=========================
+
+A namespace package is a package that only contains other packages and modules,
+with no direct contents of its own. Such packages can be split across
+multiple, separately-packaged distributions. They are normally used to split
+up large packages produced by a single organization, such as in the ``zope``
+namespace package for Zope Corporation packages, and the ``peak`` namespace
+package for the Python Enterprise Application Kit.
+
+To create a namespace package, you list it in the ``namespace_packages``
+argument to ``setup()``, in your project's ``setup.py``. (See the
+:ref:`setuptools documentation on namespace packages <Namespace Packages>` for
+more information on this.) Also, you must add a ``declare_namespace()`` call
+in the package's ``__init__.py`` file(s):
+
+``declare_namespace(name)``
+ 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
+ package of that name. (More precisely, if an importer's
+ ``find_module(name)`` returns a loader, then it will also be searched for
+ the package's contents.) Whenever a Distribution's ``activate()`` method
+ is invoked, it checks for the presence of namespace packages and updates
+ their ``__path__`` contents accordingly.
+
+Applications that manipulate namespace packages or directly alter ``sys.path``
+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
+ 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
+ contain portions of a namespace package, you will need to call this
+ function to ensure they are added to the existing namespace packages.
+
+Although by default ``pkg_resources`` only supports namespace packages for
+filesystem and zip importers, you can extend its support to other "importers"
+compatible with PEP 302 using the ``register_namespace_handler()`` function.
+See the section below on `Supporting Custom Importers`_ for details.
+
+
+``WorkingSet`` Objects
+======================
+
+The ``WorkingSet`` class provides access to a collection of "active"
+distributions. In general, there is only one meaningful ``WorkingSet``
+instance: the one that represents the distributions that are currently active
+on ``sys.path``. This global instance is available under the name
+``working_set`` in the ``pkg_resources`` module. However, specialized
+tools may wish to manipulate working sets that don't correspond to
+``sys.path``, and therefore may wish to create other ``WorkingSet`` instances.
+
+It's important to note that the global ``working_set`` object is initialized
+from ``sys.path`` when ``pkg_resources`` is first imported, but is only updated
+if you do all future ``sys.path`` manipulation via ``pkg_resources`` APIs. If
+you manually modify ``sys.path``, you must invoke the appropriate methods on
+the ``working_set`` instance to keep it in sync. Unfortunately, Python does
+not provide any way to detect arbitrary changes to a list object like
+``sys.path``, so ``pkg_resources`` cannot automatically update the
+``working_set`` based on changes to ``sys.path``.
+
+``WorkingSet(entries=None)``
+ 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.
+
+ Note that you will not normally construct ``WorkingSet`` instances
+ yourself, but instead you will implicitly or explicitly use the global
+ ``working_set`` instance. For the most part, the ``pkg_resources`` API
+ is designed so that the ``working_set`` is used by default, such that you
+ don't have to explicitly refer to it most of the time.
+
+All distributions available directly on ``sys.path`` will be activated
+automatically when ``pkg_resources`` is imported. This behaviour can cause
+version conflicts for applications which require non-default versions of
+those distributions. To handle this situation, ``pkg_resources`` checks for a
+``__requires__`` attribute in the ``__main__`` module when initializing the
+default working set, and uses this to ensure a suitable version of each
+affected distribution is activated. For example::
+
+ __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import
+ import pkg_resources
+
+
+Basic ``WorkingSet`` Methods
+----------------------------
+
+The following methods of ``WorkingSet`` objects are also available as module-
+level functions in ``pkg_resources`` that apply to the default ``working_set``
+instance. Thus, you can use e.g. ``pkg_resources.require()`` as an
+abbreviation for ``pkg_resources.working_set.require()``:
+
+
+``require(*requirements)``
+ Ensure that distributions matching `requirements` are activated
+
+ `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
+ included, even if they were already activated in this working set.
+
+ For the syntax of requirement specifiers, see the section below on
+ `Requirements Parsing`_.
+
+ In general, it should not be necessary for you to call this method
+ directly. It's intended more for use in quick-and-dirty scripting and
+ 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 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
+ should use the ``resolve()`` method instead, which allows you to pass an
+ ``installer`` callback that will be invoked when a needed distribution
+ can't be found on the local machine. You can then have this callback
+ display a dialog, automatically download the needed distribution, or
+ whatever else is appropriate for your application. See the documentation
+ below on the ``resolve()`` method for more information, and also on the
+ ``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.
+ (See `Requirements Parsing`_ below for the syntax.)
+
+ The script, if found, will be executed in *the caller's globals*. That's
+ because this method is intended to be called from wrapper scripts that
+ act as a proxy for the "real" scripts in a distribution. A wrapper script
+ usually doesn't need to do anything but invoke this function with the
+ correct arguments.
+
+ If you need more control over the script execution environment, you
+ probably want to use the ``run_script()`` method of a ``Distribution``
+ object's `Metadata API`_ instead.
+
+``iter_entry_points(group, name=None)``
+ Yield entry point objects from `group` matching `name`
+
+ 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
+ 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
+ advertised by an individual distribution, there is no particular ordering.
+
+ Please see the section below on `Entry Points`_ for more information.
+
+
+``WorkingSet`` Methods and Attributes
+-------------------------------------
+
+These methods are used to query or manipulate the contents of a specific
+working set, so they must be explicitly invoked on a particular ``WorkingSet``
+instance:
+
+``add_entry(entry)``
+ Add a path item to the ``entries``, finding any distributions on it. You
+ should use this when you add additional items to ``sys.path`` and you want
+ the global ``working_set`` to reflect the change. This method is also
+ 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
+ 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
+ distribution for a given project can be active in a given ``WorkingSet``.
+
+``__iter__()``
+ Yield distributions for non-duplicate projects in the working set.
+ The yield order is the order in which the items' path entries were
+ added to the working set.
+
+``find(req)``
+ 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.
+ 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`
+
+ `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
+ 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`
+ argument.)
+
+``add(dist, entry=None)``
+ 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 it wasn't already present).
+
+ `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.)
+
+ Note: ``add()`` is automatically called for you by the ``require()``
+ method, so you don't normally need to use this method directly.
+
+``entries``
+ This attribute represents a "shadow" ``sys.path``, primarily useful for
+ debugging. If you are experiencing import problems, you should check
+ the global ``working_set`` object's ``entries`` against ``sys.path``, to
+ ensure that they match. If they do not, then some part of your program
+ is manipulating ``sys.path`` without updating the ``working_set``
+ accordingly. IMPORTANT NOTE: do not directly manipulate this attribute!
+ Setting it equal to ``sys.path`` will not fix your problem, any more than
+ putting black tape over an "engine warning" light will fix your car! If
+ this attribute is out of sync with ``sys.path``, it's merely an *indicator*
+ of the problem, not the cause of it.
+
+
+Receiving Change Notifications
+------------------------------
+
+Extensible applications and frameworks may need to receive notification when
+a new distribution (such as a plug-in component) has been added to a working
+set. This is what the ``subscribe()`` method and ``add_activation_listener()``
+function are for.
+
+``subscribe(callback)``
+ Invoke ``callback(distribution)`` once for each active distribution that is
+ in the set now, or gets added later. Because the callback is invoked for
+ already-active distributions, you do not need to loop over the working set
+ yourself to deal with the existing items; just register the callback and
+ be prepared for the fact that it will be called immediately by this method.
+
+ Note that callbacks *must not* allow exceptions to propagate, or they will
+ interfere with the operation of other callbacks and possibly result in an
+ inconsistent working set state. Callbacks should use a try/except block
+ to ignore, log, or otherwise process any errors, especially since the code
+ that caused the callback to be invoked is unlikely to be able to handle
+ the errors any better than the callback itself.
+
+``pkg_resources.add_activation_listener()`` is an alternate spelling of
+``pkg_resources.working_set.subscribe()``.
+
+
+Locating Plugins
+----------------
+
+Extensible applications will sometimes have a "plugin directory" or a set of
+plugin directories, from which they want to load entry points or other
+metadata. The ``find_plugins()`` method allows you to do this, by scanning an
+environment for the newest version of each project that can be safely loaded
+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
+ working set without version conflicts or missing requirements.
+
+ Example usage::
+
+ distributions, errors = working_set.find_plugins(
+ Environment(plugin_dirlist)
+ )
+ 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
+ distributions that are in the project's "plugin directory" or directories.
+ 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
+ ``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
+ were loadable, along with any other distributions that are needed to resolve
+ 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.
+
+ Most applications will use this method mainly on the master ``working_set``
+ instance in ``pkg_resources``, and then immediately add the returned
+ distributions to the working set so that they are available on sys.path.
+ This will make it possible to find any entry points, and allow any other
+ 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.
+ Then, each project's eggs are tried in descending version order (i.e.,
+ newest version first).
+
+ An attempt is made to resolve each egg's dependencies. If the attempt is
+ successful, the egg and its dependencies are added to the output list and to
+ a temporary copy of the working set. The resolution process continues with
+ 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
+ plugin is tried, until a working version is found. If false, the resolution
+ process continues with the next plugin project name.
+
+ Some applications may have stricter fallback requirements than others. For
+ example, an application that has a database schema or persistent objects
+ 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.)
+
+ Note that this algorithm gives precedence to satisfying the dependencies of
+ alphabetically prior project names in case of version conflicts. If two
+ projects named "AaronsPlugin" and "ZekesPlugin" both need different versions
+ of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be
+ disabled due to version conflict.
+
+
+``Environment`` Objects
+=======================
+
+An "environment" is a collection of ``Distribution`` objects, usually ones
+that are present and potentially importable on the current platform.
+``Environment`` objects are used by ``pkg_resources`` to index available
+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
+ sequence of strings such as might be used on ``sys.path``. If a
+ `search_path` isn't supplied, ``sys.path`` is used.
+
+ `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
+ 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
+ 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
+ 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.
+
+``__getitem__(project_name)``
+ Returns a list of distributions for the given project name, ordered
+ from newest to oldest version. (And highest to lowest format precedence
+ for distributions that contain the same version of the project.) If there
+ are no distributions for the project, returns an empty list.
+
+``__iter__()``
+ Yield the unique project names of the distributions in this environment.
+ The yielded names are always in lower case.
+
+``add(dist)``
+ 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.
+
+``can_add(dist)``
+ 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.
+
+``__add__(dist_or_env)`` (``+`` operator)
+ Add a distribution or environment to an ``Environment`` instance, returning
+ a *new* environment object that contains all the distributions previously
+ contained by both. The new environment will have a ``platform`` and
+ ``python`` of ``None``, meaning that it will not reject any distributions
+ from being added to it; it will simply accept whatever is added. If you
+ want the added items to be filtered for platform and Python version, or
+ you want to add them to the *same* environment instance, you should use
+ in-place addition (``+=``) instead.
+
+``__iadd__(dist_or_env)`` (``+=`` operator)
+ Add a distribution or environment to an ``Environment`` instance
+ *in-place*, updating the existing instance and returning it. The
+ ``platform`` and ``python`` filter attributes take effect, so distributions
+ in the source that do not have a suitable platform string or Python version
+ are silently ignored.
+
+``best_match(req, working_set, installer=None)``
+ Find distribution best matching `req` and usable on `working_set`
+
+ 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, 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
+ 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
+ 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.
+
+``scan(search_path=None)``
+ Scan `search_path` for distributions usable on `platform`
+
+ 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
+ ``add()`` to add each one to the environment.
+
+
+``Requirement`` Objects
+=======================
+
+``Requirement`` objects express what versions of a project are suitable for
+some purpose. These objects (or their string form) are used by various
+``pkg_resources`` APIs in order to find distributions that a script or
+distribution needs.
+
+
+Requirements Parsing
+--------------------
+
+``parse_requirements(s)``
+ Yield ``Requirement`` objects for a string or iterable of lines. Each
+ requirement must start on a new line. See below for syntax.
+
+``Requirement.parse(s)``
+ Create a ``Requirement`` object from a string or iterable of lines. A
+ ``ValueError`` is raised if the string or lines do not contain a valid
+ requirement specifier, or if they contain more than one specifier. (To
+ parse multiple specifiers from a string or iterable of strings, use
+ ``parse_requirements()`` instead.)
+
+ The syntax of a requirement specifier is defined in full in PEP 508.
+
+ Some examples of valid requirement specifiers::
+
+ FooProject >= 1.2
+ Fizzy [foo, bar]
+ PickyThing>1.6,<=1.9,!=1.8.6
+ SomethingWhoseVersionIDontCareAbout
+ SomethingWithMarker[foo]>1.0;python_version<"2.7"
+
+ The project name is the only required portion of a requirement string, and
+ if it's the only thing supplied, the requirement will accept any version
+ of that project.
+
+ The "extras" in a requirement are used to request optional features of a
+ project, that may require additional project distributions in order to
+ function. For example, if the hypothetical "Report-O-Rama" project offered
+ optional PDF support, it might require an additional library in order to
+ provide that support. Thus, a project needing Report-O-Rama's PDF features
+ could use a requirement of ``Report-O-Rama[PDF]`` to request installation
+ or activation of both Report-O-Rama and any libraries it needs in order to
+ provide PDF support. For example, you could use::
+
+ pip install Report-O-Rama[PDF]
+
+ 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.
+
+ The "markers" in a requirement are used to specify when a requirement
+ should be installed -- the requirement will be installed if the marker
+ evaluates as true in the current environment. For example, specifying
+ ``argparse;python_version<"3.0"`` will not install in an Python 3
+ environment, but will in a Python 2 environment.
+
+``Requirement`` Methods and Attributes
+--------------------------------------
+
+``__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
+ 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
+ parsed using the ``parse_version()`` utility function. Otherwise, it is
+ assumed to be an already-parsed version.
+
+ The ``Requirement`` object's version specifiers (``.specs``) are internally
+ sorted into ascending version order, and used to establish what ranges of
+ versions are acceptable. Adjacent redundant conditions are effectively
+ consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and
+ ``"<2,<3"`` produces the same results as ``"<2"``). ``"!="`` versions are
+ excised from the ranges they fall within. The version being tested for
+ acceptability is then checked for membership in the resulting ranges.
+
+``__eq__(other_requirement)``
+ A requirement compares equal to another requirement if they have
+ case-insensitively equal project names, version specifiers, and "extras".
+ (The order that extras and version specifiers are in is also ignored.)
+ Equal requirements also have equal hashes, so that requirements can be
+ used in sets or as dictionary keys.
+
+``__str__()``
+ The string form of a ``Requirement`` is a string that, if passed to
+ ``Requirement.parse()``, would return an equal ``Requirement`` object.
+
+``project_name``
+ The name of the required project
+
+``key``
+ An all-lowercase version of the ``project_name``, useful for comparison
+ or indexing.
+
+``extras``
+ A tuple of names of "extras" that this requirement calls for. (These will
+ be all-lowercase and normalized using the ``safe_extra()`` parsing utility
+ function, so they may not exactly equal the extras the requirement was
+ created with.)
+
+``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.
+
+``marker``
+ An instance of ``packaging.markers.Marker`` that allows evaluation
+ against the current environment. May be None if no marker specified.
+
+``url``
+ The location to download the requirement from if specified.
+
+Entry Points
+============
+
+Entry points are a simple way for distributions to "advertise" Python objects
+(such as functions or classes) for use by other distributions. Extensible
+applications and frameworks can search for entry points with a particular name
+or group, either from a specific distribution or from all active distributions
+on sys.path, and then inspect or load the advertised objects at will.
+
+Entry points belong to "groups" which are named with a dotted name similar to
+a Python package or module name. For example, the ``setuptools`` package uses
+an entry point named ``distutils.commands`` in order to find commands defined
+by distutils extensions. ``setuptools`` treats the names of entry points
+defined in that group as the acceptable commands for a setup script.
+
+In a similar way, other packages can define their own entry point groups,
+either using dynamic names within the group (like ``distutils.commands``), or
+possibly using predefined names within the group. For example, a blogging
+framework that offers various pre- or post-publishing hooks might define an
+entry point group and look for entry points named "pre_process" and
+"post_process" within that group.
+
+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](https://setuptools.readthedocs.io/en/latest/setuptools.html#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
+could advertise two different ``distutils.commands`` entry points, as long as
+they had different names. However, there is nothing that prevents *different*
+projects from advertising entry points of the same name in the same group. In
+some cases, this is a desirable thing, since the application or framework that
+uses the entry points may be calling them as hooks, or in some other way
+combining them. It is up to the application or framework to decide what to do
+if multiple distributions advertise an entry point; some possibilities include
+using both entry points, displaying an error message, using the first one found
+in sys.path order, etc.
+
+
+Convenience API
+---------------
+
+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,
+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.
+
+``load_entry_point(dist, group, name)``
+ Load the named entry point from the specified distribution, or raise
+ ``ImportError``.
+
+``get_entry_info(dist, group, name)``
+ 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
+ map for the distribution. This function always returns a dictionary,
+ 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
+ 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`.
+
+ 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
+ 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.)
+
+ (This API is actually a method of the global ``working_set`` object; see
+ the section above on `Basic WorkingSet Methods`_ for more information.)
+
+
+Creating and Parsing
+--------------------
+
+``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
+ 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
+ distribution needs in order to provide this entry point. When the
+ 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
+ a ``Distribution`` instance.
+
+``EntryPoint.parse(src, dist=None)`` (classmethod)
+ Parse a single entry point from string `src`
+
+ Entry point syntax follows the form::
+
+ name = some.module:some.attr [extra1,extra2]
+
+ 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
+ ``EntryPoint()`` constructor, along with the other values parsed from
+ `src`.
+
+``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod)
+ 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
+ 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
+ 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,
+ 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
+ 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
+ ``parse_group()`` so that the entry points will be linked to the specified
+ distribution.
+
+
+``EntryPoint`` Objects
+----------------------
+
+For simple introspection, ``EntryPoint`` objects have attributes that
+correspond exactly to the constructor argument names: ``name``,
+``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In
+addition, the following methods are provided:
+
+``load()``
+ Load the entry point, returning the advertised Python object. Effectively
+ calls ``self.require()`` then returns ``self.resolve()``.
+
+``require(env=None, installer=None)``
+ 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
+ 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
+ taking a ``Requirement`` instance and returning a matching importable
+ ``Distribution`` instance or None.
+
+``resolve()``
+ Resolve the entry point from its module and attrs, returning the advertised
+ Python object. Raises ``ImportError`` if it cannot be obtained.
+
+``__str__()``
+ The string form of an ``EntryPoint`` is a string that could be passed to
+ ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``.
+
+
+``Distribution`` Objects
+========================
+
+``Distribution`` objects represent collections of Python code that may or may
+not be importable, and may or may not have metadata and resources associated
+with them. Their metadata may include information such as what other projects
+the distribution depends on, what entry points the distribution advertises, and
+so on.
+
+
+Getting or Creating Distributions
+---------------------------------
+
+Most commonly, you'll obtain ``Distribution`` objects from a ``WorkingSet`` or
+an ``Environment``. (See the sections above on `WorkingSet Objects`_ and
+`Environment Objects`_, which are containers for active distributions and
+available distributions, respectively.) You can also obtain ``Distribution``
+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
+ 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 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.
+
+However, if you're creating specialized tools for working with distributions,
+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`
+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.
+
+``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
+ 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
+ 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.
+
+``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod)
+ Create a distribution by parsing a local filename. This is a shorter way
+ of saying ``Distribution.from_location(normalize_path(filename),
+ os.path.basename(filename), metadata)``. In other words, it creates a
+ distribution whose location is the normalize form of the filename, parsing
+ name and version information from the base portion of the filename. Any
+ additional keyword arguments are forwarded to the ``Distribution()``
+ constructor.
+
+``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
+ ``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
+ all these arguments individually.
+
+
+``Distribution`` Attributes
+---------------------------
+
+location
+ A string indicating the distribution's location. For an importable
+ distribution, this is the string that would be added to ``sys.path`` to
+ make it actively importable. For non-importable distributions, this is
+ simply a filename, URL, or other way of locating the distribution.
+
+project_name
+ 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
+ function to filter out any unacceptable characters.
+
+key
+ ``dist.key`` is short for ``dist.project_name.lower()``. It's used for
+ case-insensitive comparison and indexing of distributions by project name.
+
+extras
+ A list of strings, giving the names of extra features defined by the
+ project's dependency list (the ``extras_require`` argument specified in
+ the project's setup script).
+
+version
+ A string denoting what release of the project this distribution contains.
+ 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
+ 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,
+ ``ValueError`` is raised.
+
+parsed_version
+ The ``parsed_version`` is an object representing a "parsed" form of the
+ distribution's ``version``. ``dist.parsed_version`` is a shortcut for
+ calling ``parse_version(dist.version)``. It is used to compare or sort
+ 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
+ supplying the missing version info.
+
+py_version
+ The major/minor Python version the distribution supports, as a string.
+ For example, "2.7" or "3.4". The default is the current version of Python.
+
+platform
+ A string representing the platform the distribution is intended for, or
+ ``None`` if the distribution is "pure Python" and therefore cross-platform.
+ See `Platform Utilities`_ below for more information on platform strings.
+
+precedence
+ A distribution's ``precedence`` is used to determine the relative order of
+ two distributions that have the same ``project_name`` and
+ ``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``,
+ which is the highest (i.e. most preferred) precedence. The full list
+ of predefined precedences, from most preferred to least preferred, is:
+ ``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and
+ ``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used
+ only by the ``setuptools.package_index`` module, when sorting distributions
+ found in a package index to determine their suitability for installation.
+ "System" and "Development" eggs (i.e., ones that use the ``.egg-info``
+ format), however, are automatically given a precedence of ``DEVELOP_DIST``.
+
+
+
+``Distribution`` Methods
+------------------------
+
+``activate(path=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
+ 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
+ merged with the contents provided by any other active distributions. See
+ the section above on `Namespace Package Support`_ for more information.)
+
+ ``pkg_resources`` adds a notification callback to the global ``working_set``
+ that ensures this method is called whenever a distribution is added to it.
+ Therefore, you should not normally need to explicitly call this method.
+ (Note that this means that namespace packages on ``sys.path`` are always
+ imported as soon as ``pkg_resources`` is, which is another reason why
+ namespace packages should not contain any code or import statements.)
+
+``as_requirement()``
+ Return a ``Requirement`` instance that matches this distribution's project
+ name and version.
+
+``requires(extras=())``
+ List the ``Requirement`` objects that specify this distribution's
+ 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".
+
+``clone(**kw)``
+ Create a copy of the distribution. Any supplied keyword arguments override
+ the corresponding argument to the ``Distribution()`` constructor, allowing
+ you to change some of the copied distribution's attributes.
+
+``egg_name()``
+ Return what this distribution's standard filename should be, not including
+ the ".egg" extension. For example, a distribution for project "Foo"
+ version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()``
+ of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are
+ converted to underscores. (``Distribution.from_location()`` will convert
+ them back when parsing a ".egg" file name.)
+
+``__cmp__(other)``, ``__hash__()``
+ Distribution objects are hashed and compared on the basis of their parsed
+ version and precedence, followed by their key (lowercase project name),
+ location, Python version, and platform.
+
+The following methods are used to access ``EntryPoint`` objects advertised
+by the distribution. See the section above on `Entry Points`_ for more
+detailed information about these operations:
+
+``get_entry_info(group, name)``
+ 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
+ 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.)
+
+``load_entry_point(group, name)``
+ Short for ``get_entry_info(group, name).load()``. Returns the object
+ advertised by the named entry point, or raises ``ImportError`` if
+ the entry point isn't advertised by this distribution, or there is some
+ other import problem.
+
+In addition to the above methods, ``Distribution`` objects also implement all
+of the `IResourceProvider`_ and `IMetadataProvider Methods`_ (which are
+documented in later sections):
+
+* ``has_metadata(name)``
+* ``metadata_isdir(name)``
+* ``metadata_listdir(name)``
+* ``get_metadata(name)``
+* ``get_metadata_lines(name)``
+* ``run_script(script_name, namespace)``
+* ``get_resource_filename(manager, resource_name)``
+* ``get_resource_stream(manager, resource_name)``
+* ``get_resource_string(manager, resource_name)``
+* ``has_resource(resource_name)``
+* ``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.
+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
+=======================
+
+The ``ResourceManager`` class provides uniform access to package resources,
+whether those resources exist as files and directories or are compressed in
+an archive of some kind.
+
+Normally, you do not need to create or explicitly manage ``ResourceManager``
+instances, as the ``pkg_resources`` module creates a global instance for you,
+and makes most of its methods available as top-level names in the
+``pkg_resources`` module namespace. So, for example, this code actually
+calls the ``resource_string()`` method of the global ``ResourceManager``::
+
+ import pkg_resources
+ my_data = pkg_resources.resource_string(__name__, "foo.dat")
+
+Thus, you can use the APIs below without needing an explicit
+``ResourceManager`` instance; just import and use them as needed.
+
+
+Basic Resource Access
+---------------------
+
+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
+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
+multiple distributions, and is therefore ambiguous as to which distribution
+should be searched for the resource.)
+
+If it is a ``Requirement``, then the requirement is automatically resolved
+(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
+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 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.
+
+``resource_exists(package_or_requirement, resource_name)``
+ Does the named resource exist? Return ``True`` or ``False`` accordingly.
+
+``resource_stream(package_or_requirement, resource_name)``
+ Return a readable file-like object for the specified resource; it may be
+ an actual file, a ``StringIO``, or some similar object. The stream is
+ in "binary mode", in the sense that whatever bytes are in the resource
+ will be read as-is.
+
+``resource_string(package_or_requirement, resource_name)``
+ Return the specified resource as a string. The resource is read in
+ binary fashion, such that the returned string contains exactly the bytes
+ that are stored in the resource.
+
+``resource_isdir(package_or_requirement, resource_name)``
+ Is the named resource a directory? Return ``True`` or ``False``
+ accordingly.
+
+``resource_listdir(package_or_requirement, resource_name)``
+ List the contents of the named resource directory, just like ``os.listdir``
+ except that it works even if the resource is in a zipfile.
+
+Note that only ``resource_exists()`` and ``resource_isdir()`` are insensitive
+as to the resource type. You cannot use ``resource_listdir()`` on a file
+resource, and you can't use ``resource_string()`` or ``resource_stream()`` on
+directory resources. Using an inappropriate method for the resource type may
+result in an exception or undefined behavior, depending on the platform and
+distribution format involved.
+
+
+Resource Extraction
+-------------------
+
+``resource_filename(package_or_requirement, resource_name)``
+ Sometimes, it is not sufficient to access a resource in string or stream
+ form, and a true filesystem filename is needed. In such cases, you can
+ use this method (or module-level function) to obtain a filename for a
+ resource. If the resource is in an archive distribution (such as a zipped
+ egg), it will be extracted to a cache directory, and the filename within
+ the cache will be returned. If the named resource is a directory, then
+ all resources within that directory (including subdirectories) are also
+ extracted. If the named resource is a C extension or "eager resource"
+ (see the ``setuptools`` documentation for details), then all C extensions
+ and eager resources are extracted at the same time.
+
+ Archived resources are extracted to a cache location that can be managed by
+ the following two methods:
+
+``set_extraction_path(path)``
+ Set the base path where resources will be extracted to, if needed.
+
+ If you do not call this routine before any extractions take place, the
+ path defaults to the return value of ``get_default_cache()``. (Which is
+ based on the ``PYTHON_EGG_CACHE`` environment variable, with various
+ platform-specific fallbacks. See that routine's documentation for more
+ details.)
+
+ Resources are extracted to subdirectories of this path based upon
+ information given by the resource provider. You may set this to a
+ temporary directory, but then you must call ``cleanup_resources()`` to
+ delete the extracted files when done. There is no guarantee that
+ ``cleanup_resources()`` will be able to remove all extracted files. (On
+ Windows, for example, you can't unlink .pyd or .dll files that are still
+ in use.)
+
+ Note that you may not change the extraction path for a given resource
+ manager once resources have been extracted, unless you first call
+ ``cleanup_resources()``.
+
+``cleanup_resources(force=False)``
+ Delete all extracted resource files and directories, returning a list
+ of the file and directory names that could not be successfully removed.
+ This function does not have any concurrency protection, so it should
+ generally only be called when the extraction path is a temporary
+ directory exclusive to a single process. This method is not
+ automatically called; you must call it explicitly or register it as an
+ ``atexit`` function if you wish to ensure cleanup of a temporary
+ directory used for extractions.
+
+
+"Provider" Interface
+--------------------
+
+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
+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`
+
+ 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
+ enclosing egg (which may not be the name of the enclosing zipfile!),
+ 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
+ obtain an extraction location, and only for names they intend to
+ extract, as it tracks the generated names for possible cleanup later.
+
+``extraction_error()``
+ Raise an ``ExtractionError`` describing the active exception as interfering
+ with the extraction process. You should call this if you encounter any
+ OS errors extracting the file to the cache path; it will format the
+ operating system exception for you, and add other information to the
+ ``ExtractionError`` instance that may be needed by programs that want to
+ wrap or handle extraction errors themselves.
+
+``postprocess(tempname, filename)``
+ 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`
+ is the name it will be renamed to by the caller after this routine
+ returns.
+
+
+Metadata API
+============
+
+The metadata API is used to access metadata resources bundled in a pluggable
+distribution. Metadata resources are virtual files or directories containing
+information about the distribution, such as might be used by an extensible
+application or framework to connect "plugins". Like other kinds of resources,
+metadata resource names are ``/``-separated and should not contain ``..`` or
+begin with a ``/``. You should not use ``os.path`` routines to manipulate
+resource paths.
+
+The metadata API is provided by objects implementing the ``IMetadataProvider``
+or ``IResourceProvider`` interfaces. ``Distribution`` objects implement this
+interface, as do objects returned by the ``get_provider()`` function:
+
+``get_provider(package_or_requirement)``
+ If a package name is supplied, return an ``IResourceProvider`` for the
+ package. If a ``Requirement`` is supplied, resolve it by returning a
+ ``Distribution`` from the current working set (searching the current
+ ``Environment`` if necessary and adding the newly found ``Distribution``
+ to the working set). If the named package can't be imported, or the
+ ``Requirement`` can't be satisfied, an exception is raised.
+
+ NOTE: if you use a package name rather than a ``Requirement``, the object
+ you get back may not be a pluggable distribution, depending on the method
+ by which the package was installed. In particular, "development" packages
+ and "single-version externally-managed" packages do not have any way to
+ map from a package name to the corresponding project's metadata. Do not
+ write code that passes a package name to ``get_provider()`` and then tries
+ to retrieve project metadata from the returned object. It may appear to
+ work when the named package is in an ``.egg`` file or directory, but
+ it will fail in other installation scenarios. If you want project
+ metadata, you need to ask for a *project*, not a package.
+
+
+``IMetadataProvider`` Methods
+-----------------------------
+
+The methods provided by objects (such as ``Distribution`` instances) that
+implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are:
+
+``has_metadata(name)``
+ Does the named metadata resource exist?
+
+``metadata_isdir(name)``
+ Is the named metadata resource a directory?
+
+``metadata_listdir(name)``
+ List of metadata names in the directory (like ``os.listdir()``)
+
+``get_metadata(name)``
+ Return the named metadata resource as a string. The data is read in binary
+ mode; i.e., the exact bytes of the resource file are returned.
+
+``get_metadata_lines(name)``
+ Yield named metadata resource as list of non-blank non-comment lines. This
+ is short for calling ``yield_lines(provider.get_metadata(name))``. See the
+ section on `yield_lines()`_ below for more information on the syntax it
+ recognizes.
+
+``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
+ a module dictionary if the script is being run as a module.
+
+
+Exceptions
+==========
+
+``pkg_resources`` provides a simple exception hierarchy for problems that may
+occur when processing requests to locate and activate packages::
+
+ ResolutionError
+ DistributionNotFound
+ VersionConflict
+ UnknownExtra
+
+ ExtractionError
+
+``ResolutionError``
+ This class is used as a base class for the other three exceptions, so that
+ you can catch all of them with a single "except" clause. It is also raised
+ directly for miscellaneous requirement-resolution problems like trying to
+ run a script that doesn't exist in the distribution it was requested from.
+
+``DistributionNotFound``
+ A distribution needed to fulfill a requirement could not be found.
+
+``VersionConflict``
+ The requested version of a project conflicts with an already-activated
+ version of the same project.
+
+``UnknownExtra``
+ One of the "extras" requested was not recognized by the distribution it
+ was requested from.
+
+``ExtractionError``
+ A problem occurred extracting a resource to the Python Egg cache. The
+ following attributes are available on instances of this exception:
+
+ manager
+ The resource manager that raised this exception
+
+ cache_path
+ The base directory for resource extraction
+
+ original_error
+ The exception instance that caused extraction to fail
+
+
+Supporting Custom Importers
+===========================
+
+By default, ``pkg_resources`` supports normal filesystem imports, and
+``zipimport`` importers. If you wish to use the ``pkg_resources`` features
+with other (PEP 302-compatible) importers or module loaders, you may need to
+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,
+ if true, means the finder should yield only ``Distribution`` objects whose
+ ``location`` is equal to the path item provided.)
+
+ See the source of the ``pkg_resources.find_on_path`` function for an
+ 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
+ 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
+ with a signature like this::
+
+ def namespace_handler(importer, path_entry, moduleName, module):
+ # return a path_entry to use for child packages
+
+ Namespace handlers are only called if the relevant importer object has
+ already agreed that it can handle the relevant path item. The handler
+ should only return a subpath if the module ``__path__`` does not already
+ contain an equivalent subpath. Otherwise, it should return None.
+
+ For an example namespace handler, see the source of the
+ ``pkg_resources.file_ns_handler`` function, which is used for both zipfile
+ importing and regular importing.
+
+
+IResourceProvider
+-----------------
+
+``IResourceProvider`` is an abstract class that documents what methods are
+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
+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
+ filesystem.
+
+``get_resource_stream(manager, 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`.
+
+``has_resource(resource_name)``
+ Does the package contain the named resource?
+
+``resource_isdir(resource_name)``
+ Is the named resource a directory? Return a false value if the resource
+ does not exist or is not a directory.
+
+``resource_listdir(resource_name)``
+ Return a list of the contents of the resource directory, ala
+ ``os.listdir()``. Requesting the contents of a non-existent directory may
+ raise an exception.
+
+Note, by the way, that your provider classes need not (and should not) subclass
+``IResourceProvider`` or ``IMetadataProvider``! These classes exist solely
+for documentation purposes and do not provide any useful implementation code.
+You may instead wish to subclass one of the `built-in resource providers`_.
+
+
+Built-in Resource Providers
+---------------------------
+
+``pkg_resources`` includes several provider classes that are automatically used
+where appropriate. Their inheritance tree looks like this::
+
+ NullProvider
+ EggProvider
+ DefaultProvider
+ PathMetadata
+ ZipProvider
+ EggMetadata
+ EmptyProvider
+ FileMetadata
+
+
+``NullProvider``
+ This provider class is just an abstract base that provides for common
+ provider behaviors (such as running scripts), given a definition for just
+ a few abstract methods.
+
+``EggProvider``
+ This provider class adds in some egg-specific features that are common
+ to zipped and unzipped eggs.
+
+``DefaultProvider``
+ This provider class is used for unpacked eggs and "plain old Python"
+ filesystem modules.
+
+``ZipProvider``
+ This provider class is used for all zipped modules, whether they are eggs
+ or not.
+
+``EmptyProvider``
+ This provider class always returns answers consistent with a provider that
+ has no metadata or resources. ``Distribution`` objects created without
+ a ``metadata`` argument use an instance of this provider class instead.
+ Since all ``EmptyProvider`` instances are equivalent, there is no need
+ to have more than one instance. ``pkg_resources`` therefore creates a
+ global instance of this class under the name ``empty_provider``, and you
+ may use it if you have need of an ``EmptyProvider`` instance.
+
+``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`
+ 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
+ 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
+ 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
+ that also contains other eggs.
+
+``FileMetadata(path_to_pkg_info)``
+ Create an ``IResourceProvider`` that provides exactly one metadata
+ resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO
+ file. This is basically the same as an ``EmptyProvider``, except that
+ requests for ``PKG-INFO`` will be answered using the contents of the
+ designated file. (This provider is used to wrap ``.egg-info`` files
+ installed by vendor-supplied system packages.)
+
+
+Utility Functions
+=================
+
+In addition to its high-level APIs, ``pkg_resources`` also includes several
+generally-useful utility routines. These routines are used to implement the
+high-level APIs, but can also be quite useful by themselves.
+
+
+Parsing Utilities
+-----------------
+
+``parse_version(version)``
+ Parsed a project's version string as defined by PEP 440. The returned
+ value will be an object that represents the version. These objects may
+ be compared to each other and sorted. The sorting algorithm is as defined
+ by PEP 440 with the addition that any version which is not a valid PEP 440
+ version will be considered less than any valid PEP 440 version and the
+ invalid versions will continue sorting using the original algorithm.
+
+.. _yield_lines():
+
+``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
+ 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
+ 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
+ a file object or a list of strings to ``yield_lines`` will both work.
+ (Note that between each string in a sequence of strings there is assumed to
+ be an implicit line break, so lines cannot bridge two strings in a
+ sequence.)
+
+ This routine is used extensively by ``pkg_resources`` to parse metadata
+ and file formats of various kinds, and most other ``pkg_resources``
+ parsing functions that yield multiple values will use it to break up their
+ input. However, this routine is idempotent, so calling ``yield_lines()``
+ on the output of another call to ``yield_lines()`` is completely harmless.
+
+``split_sections(strs)``
+ Split a string (or possibly-nested iterable thereof), yielding ``(section,
+ content)`` pairs found using an ``.ini``-like syntax. Each ``section`` is
+ a whitespace-stripped version of the section name ("``[section]``")
+ and each ``content`` is a list of stripped lines excluding blank lines and
+ comment-only lines. If there are any non-blank, non-comment lines before
+ the first section header, they're yielded in a first ``section`` of
+ ``None``.
+
+ This routine uses ``yield_lines()`` as its front end, so you can pass in
+ anything that ``yield_lines()`` accepts, such as an open text file, string,
+ or sequence of strings. ``ValueError`` is raised if a malformed section
+ header is found (i.e. a line starting with ``[`` but not ending with
+ ``]``).
+
+ Note that this simplistic parser assumes that any line whose first nonblank
+ character is ``[`` is a section heading, so it can't support .ini format
+ variations that allow ``[`` as the first nonblank character on other lines.
+
+``safe_name(name)``
+ Return a "safe" form of a project's name, suitable for use in a
+ ``Requirement`` string, as a distribution name, or a PyPI project name.
+ All non-alphanumeric runs are condensed to single "-" characters, such that
+ a name like "The $$$ Tree" becomes "The-Tree". Note that if you are
+ generating a filename from this value you should combine it with a call to
+ ``to_filename()`` so all dashes ("-") are replaced by underscores ("_").
+ 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, 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
+ string or a setup script's ``extras_require`` keyword. This routine is
+ similar to ``safe_name()`` except that non-alphanumeric runs are replaced
+ by a single underbar (``_``), and the result is lowercased.
+
+``to_filename(name_or_version)``
+ Escape a name or version string so it can be used in a dash-separated
+ filename (or ``#egg=name-version`` tag) without ambiguity. You
+ should only pass in values that were returned by ``safe_name()`` or
+ ``safe_version()``.
+
+
+Platform Utilities
+------------------
+
+``get_build_platform()``
+ Return this platform's identifier string. For Windows, the return value
+ 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
+ on the local machine. (Backward compatibility note: setuptools versions
+ prior to 0.6b1 called this function ``get_platform()``, and the function is
+ still available under that name for backward compatibility reasons.)
+
+``get_supported_platform()`` (New in 0.6b1)
+ This is the similar to ``get_build_platform()``, but is the maximum
+ platform version that the local machine supports. You will usually want
+ to use this value as the ``provided`` argument to the
+ ``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
+ 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 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.
+
+``get_default_cache()``
+ Determine the default cache location for extracting resources from zipped
+ eggs. This routine returns the ``PYTHON_EGG_CACHE`` environment variable,
+ if set. Otherwise, on Windows, it returns a "Python-Eggs" subdirectory of
+ the user's "Application Data" directory. On all other systems, it returns
+ ``os.path.expanduser("~/.python-eggs")`` if ``PYTHON_EGG_CACHE`` is not
+ set.
+
+
+PEP 302 Utilities
+-----------------
+
+``get_importer(path_item)``
+ A deprecated alias for ``pkgutil.get_importer()``
+
+
+File/Path Utilities
+-------------------
+
+``ensure_directory(path)``
+ 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
+ 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 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.
+
+History
+-------
+
+0.6c9
+ * Fix ``resource_listdir('')`` always returning an empty list for zipped eggs.
+
+0.6c7
+ * Fix package precedence problem where single-version eggs installed in
+ ``site-packages`` would take precedence over ``.egg`` files (or directories)
+ installed in ``site-packages``.
+
+0.6c6
+ * Fix extracted C extensions not having executable permissions under Cygwin.
+
+ * Allow ``.egg-link`` files to contain relative paths.
+
+ * Fix cache dir defaults on Windows when multiple environment vars are needed
+ to construct a path.
+
+0.6c4
+ * Fix "dev" versions being considered newer than release candidates.
+
+0.6c3
+ * Python 2.5 compatibility fixes.
+
+0.6c2
+ * Fix a problem with eggs specified directly on ``PYTHONPATH`` on
+ case-insensitive filesystems possibly not showing up in the default
+ working set, due to differing normalizations of ``sys.path`` entries.
+
+0.6b3
+ * Fixed a duplicate path insertion problem on case-insensitive filesystems.
+
+0.6b1
+ * Split ``get_platform()`` into ``get_supported_platform()`` and
+ ``get_build_platform()`` to work around a Mac versioning problem that caused
+ the behavior of ``compatible_platforms()`` to be platform specific.
+
+ * Fix entry point parsing when a standalone module name has whitespace
+ between it and the extras.
+
+0.6a11
+ * Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that
+ cache permission problems get a more user-friendly explanation of the
+ problem, and so that programs can catch and handle extraction errors if they
+ need to.
+
+0.6a10
+ * Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()``
+ method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods
+ to ``Environment``.
+
+ * ``safe_name()`` now allows dots in project names.
+
+ * There is a new ``to_filename()`` function that escapes project names and
+ versions for safe use in constructing egg filenames from a Distribution
+ object's metadata.
+
+ * Added ``Distribution.clone()`` method, and keyword argument support to other
+ ``Distribution`` constructors.
+
+ * Added the ``DEVELOP_DIST`` precedence, and automatically assign it to
+ eggs using ``.egg-info`` format.
+
+0.6a9
+ * Don't raise an error when an invalid (unfinished) distribution is found
+ unless absolutely necessary. Warn about skipping invalid/unfinished eggs
+ when building an Environment.
+
+ * Added support for ``.egg-info`` files or directories with version/platform
+ information embedded in the filename, so that system packagers have the
+ option of including ``PKG-INFO`` files to indicate the presence of a
+ system-installed egg, without needing to use ``.egg`` directories, zipfiles,
+ or ``.pth`` manipulation.
+
+ * Changed ``parse_version()`` to remove dashes before pre-release tags, so
+ that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal
+ to ``0.2rc1``. The idea that a dash *always* meant a post-release version
+ was highly non-intuitive to setuptools users and Python developers, who
+ seem to want to use ``-rc`` version numbers a lot.
+
+0.6a8
+ * Fixed a problem with ``WorkingSet.resolve()`` that prevented version
+ conflicts from being detected at runtime.
+
+ * Improved runtime conflict warning message to identify a line in the user's
+ program, rather than flagging the ``warn()`` call in ``pkg_resources``.
+
+ * Avoid giving runtime conflict warnings for namespace packages, even if they
+ were declared by a different package than the one currently being activated.
+
+ * Fix path insertion algorithm for case-insensitive filesystems.
+
+ * Fixed a problem with nested namespace packages (e.g. ``peak.util``) not
+ being set as an attribute of their parent package.
+
+0.6a6
+ * Activated distributions are now inserted in ``sys.path`` (and the working
+ set) just before the directory that contains them, instead of at the end.
+ This allows e.g. eggs in ``site-packages`` to override unmanaged modules in
+ the same location, and allows eggs found earlier on ``sys.path`` to override
+ ones found later.
+
+ * When a distribution is activated, it now checks whether any contained
+ non-namespace modules have already been imported and issues a warning if
+ a conflicting module has already been imported.
+
+ * 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.
+
+ * Fixed a problem extracting zipped files on Windows, when the egg in question
+ has had changed contents but still has the same version number.
+
+0.6a4
+ * Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3.
+
+0.6a3
+ * Added ``safe_extra()`` parsing utility routine, and use it for Requirement,
+ EntryPoint, and Distribution objects' extras handling.
+
+0.6a1
+ * Enhanced performance of ``require()`` and related operations when all
+ requirements are already in the working set, and enhanced performance of
+ directory scanning for distributions.
+
+ * Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than
+ ``zipimport``, and the previously-broken "eager resource" support.
+
+ * Fixed ``pkg_resources.resource_exists()`` not working correctly, along with
+ some other resource API bugs.
+
+ * Many API changes and enhancements:
+
+ * Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and
+ ``get_entry_info`` APIs for dynamic plugin discovery.
+
+ * ``list_resources`` is now ``resource_listdir`` (and it actually works)
+
+ * Resource API functions like ``resource_string()`` that accepted a package
+ name and resource name, will now also accept a ``Requirement`` object in
+ place of the package name (to allow access to non-package data files in
+ an egg).
+
+ * ``get_provider()`` will now accept a ``Requirement`` instance or a module
+ name. If it is given a ``Requirement``, it will return a corresponding
+ ``Distribution`` (by calling ``require()`` if a suitable distribution
+ isn't already in the working set), rather than returning a metadata and
+ resource provider for a specific module. (The difference is in how
+ resource paths are interpreted; supplying a module name means resources
+ path will be module-relative, rather than relative to the distribution's
+ root.)
+
+ * ``Distribution`` objects now implement the ``IResourceProvider`` and
+ ``IMetadataProvider`` interfaces, so you don't need to reference the (no
+ longer available) ``metadata`` attribute to get at these interfaces.
+
+ * ``Distribution`` and ``Requirement`` both have a ``project_name``
+ attribute for the project name they refer to. (Previously these were
+ ``name`` and ``distname`` attributes.)
+
+ * The ``path`` attribute of ``Distribution`` objects is now ``location``,
+ 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' 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.
+
+ * ``Distribution`` objects now have an ``as_requirement()`` method that
+ returns a ``Requirement`` for the distribution's project name and version.
+
+ * Distribution objects no longer have an ``installed_on()`` method, and the
+ ``install_on()`` method is now ``activate()`` (but may go away altogether
+ soon). The ``depends()`` method has also been renamed to ``requires()``,
+ and ``InvalidOption`` is now ``UnknownExtra``.
+
+ * ``find_distributions()`` now takes an additional argument called ``only``,
+ that tells it to only yield distributions whose location is the passed-in
+ path. (It defaults to False, so that the default behavior is unchanged.)
+
+ * ``AvailableDistributions`` is now called ``Environment``, and the
+ ``get()``, ``__len__()``, and ``__contains__()`` methods were removed,
+ because they weren't particularly useful. ``__getitem__()`` no longer
+ raises ``KeyError``; it just returns an empty list if there are no
+ distributions for the named project.
+
+ * The ``resolve()`` method of ``Environment`` is now a method of
+ ``WorkingSet`` instead, and the ``best_match()`` method now uses a working
+ set instead of a path list as its second argument.
+
+ * There is a new ``pkg_resources.add_activation_listener()`` API that lets
+ you register a callback for notifications about distributions added to
+ ``sys.path`` (including the distributions already on it). This is
+ basically a hook for extensible applications and frameworks to be able to
+ search for plugin metadata in distributions added at runtime.
+
+0.5a13
+ * Fixed a bug in resource extraction from nested packages in a zipped egg.
+
+0.5a12
+ * Updated extraction/cache mechanism for zipped resources to avoid inter-
+ process and inter-thread races during extraction. The default cache
+ location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable,
+ and the default Windows cache is now a ``Python-Eggs`` subdirectory of the
+ current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE``
+ variable isn't set.
+
+0.5a10
+ * Fix a problem with ``pkg_resources`` being confused by non-existent eggs on
+ ``sys.path`` (e.g. if a user deletes an egg without removing it from the
+ ``easy-install.pth`` file).
+
+ * Fix a problem with "basket" support in ``pkg_resources``, where egg-finding
+ never actually went inside ``.egg`` files.
+
+ * Made ``pkg_resources`` import the module you request resources from, if it's
+ not already imported.
+
+0.5a4
+ * ``pkg_resources.AvailableDistributions.resolve()`` and related methods now
+ accept an ``installer`` argument: a callable taking one argument, a
+ ``Requirement`` instance. The callable must return a ``Distribution``
+ object, or ``None`` if no distribution is found. This feature is used by
+ EasyInstall to resolve dependencies by recursively invoking itself.
+
+0.4a4
+ * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource
+ directory extraction for zipped eggs.
+
+0.4a3
+ * Fixed scripts not being able to see a ``__file__`` variable in ``__main__``
+
+ * Fixed a problem with ``resource_isdir()`` implementation that was introduced
+ in 0.4a2.
+
+0.4a1
+ * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and
+ ``!=``) when only one condition was included.
+
+ * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of
+ arbitrary distribution names and versions found on PyPI.
+
+0.3a4
+ * ``pkg_resources`` now supports resource directories, not just the resources
+ in them. In particular, there are ``resource_listdir()`` and
+ ``resource_isdir()`` APIs.
+
+ * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain
+ multiple distributions in subdirectories whose names end with ``.egg``.
+ Having such a "basket" in a directory on ``sys.path`` is equivalent to
+ having the individual eggs in that directory, but the contained eggs can
+ be individually added (or not) to ``sys.path``. Currently, however, there
+ is no automated way to create baskets.
+
+ * Namespace package manipulation is now protected by the Python import lock.
+
+0.3a1
+ * Initial release.
+
+++ /dev/null
-=============================================================
-Package Discovery and Resource Access using ``pkg_resources``
-=============================================================
-
-The ``pkg_resources`` module distributed with ``setuptools`` provides an API
-for Python libraries to access their resource files, and for extensible
-applications and frameworks to automatically discover plugins. It also
-provides runtime support for using C extensions that are inside zipfile-format
-eggs, support for merging packages that have separately-distributed modules or
-subpackages, and APIs for managing Python's current "working set" of active
-packages.
-
-
-.. contents:: **Table of Contents**
-
-
---------
-Overview
---------
-
-The ``pkg_resources`` module provides runtime facilities for finding,
-introspecting, activating and using installed Python distributions. Some
-of the more advanced features (notably the support for parallel installation
-of multiple versions) rely specifically on the "egg" format (either as a
-zip archive or subdirectory), while others (such as plugin discovery) will
-work correctly so long as "egg-info" metadata directories are available for
-relevant distributions.
-
-Eggs are a distribution format for Python modules, similar in concept to
-Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427.
-However, unlike a pure distribution format, eggs can also be installed and
-added directly to ``sys.path`` as an import location. When installed in
-this way, eggs are *discoverable*, meaning that they carry metadata that
-unambiguously identifies their contents and dependencies. This means that
-an installed egg can be *automatically* found and added to ``sys.path`` in
-response to simple requests of the form, "get me everything I need to use
-docutils' PDF support". This feature allows mutually conflicting versions of
-a distribution to co-exist in the same Python installation, with individual
-applications activating the desired version at runtime by manipulating the
-contents of ``sys.path`` (this differs from the virtual environment
-approach, which involves creating isolated environments for each
-application).
-
-The following terms are needed in order to explain the capabilities offered
-by this module:
-
-project
- A library, framework, script, plugin, application, or collection of data
- or other resources, or some combination thereof. Projects are assumed to
- have "relatively unique" names, e.g. names registered with PyPI.
-
-release
- A snapshot of a project at a particular point in time, denoted by a version
- identifier.
-
-distribution
- A file or files that represent a particular release.
-
-importable distribution
- A file or directory that, if placed on ``sys.path``, allows Python to
- import any modules contained within it.
-
-pluggable distribution
- An importable distribution whose filename unambiguously identifies its
- release (i.e. project and version), and whose contents unambiguously
- specify what releases of other projects will satisfy its runtime
- requirements.
-
-extra
- An "extra" is an optional feature of a release, that may impose additional
- runtime requirements. For example, if docutils PDF support required a
- PDF support library to be present, docutils could define its PDF support as
- an "extra", and list what other project releases need to be available in
- order to provide it.
-
-environment
- A collection of distributions potentially available for importing, but not
- necessarily active. More than one distribution (i.e. release version) for
- a given project may be present in an environment.
-
-working set
- A collection of distributions actually available for importing, as on
- ``sys.path``. At most one distribution (release version) of a given
- project may be present in a working set, as otherwise there would be
- ambiguity as to what to import.
-
-eggs
- Eggs are pluggable distributions in one of the three formats currently
- supported by ``pkg_resources``. There are built eggs, development eggs,
- and egg links. Built eggs are directories or zipfiles whose name ends
- with ``.egg`` and follows the egg naming conventions, and contain an
- ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are
- normal directories of Python code with one or more ``ProjectName.egg-info``
- subdirectories. The development egg format is also used to provide a
- default version of a distribution that is available to software that
- doesn't use ``pkg_resources`` to request specific versions. Egg links
- are ``*.egg-link`` files that contain the name of a built or
- development egg, to support symbolic linking on platforms that do not
- have native symbolic links (or where the symbolic link support is
- limited).
-
-(For more information about these terms and concepts, see also this
-`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.)
-
-.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html
-
-
-.. -----------------
-.. Developer's Guide
-.. -----------------
-
-.. This section isn't written yet. Currently planned topics include
- Accessing Resources
- Finding and Activating Package Distributions
- get_provider()
- require()
- WorkingSet
- iter_distributions
- Running Scripts
- Configuration
- Namespace Packages
- Extensible Applications and Frameworks
- Locating entry points
- Activation listeners
- Metadata access
- Extended Discovery and Installation
- Supporting Custom PEP 302 Implementations
-.. For now, please check out the extensive `API Reference`_ below.
-
-
--------------
-API Reference
--------------
-
-Namespace Package Support
-=========================
-
-A namespace package is a package that only contains other packages and modules,
-with no direct contents of its own. Such packages can be split across
-multiple, separately-packaged distributions. They are normally used to split
-up large packages produced by a single organization, such as in the ``zope``
-namespace package for Zope Corporation packages, and the ``peak`` namespace
-package for the Python Enterprise Application Kit.
-
-To create a namespace package, you list it in the ``namespace_packages``
-argument to ``setup()``, in your project's ``setup.py``. (See the
-:ref:`setuptools documentation on namespace packages <Namespace Packages>` for
-more information on this.) Also, you must add a ``declare_namespace()`` call
-in the package's ``__init__.py`` file(s):
-
-``declare_namespace(name)``
- 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
- package of that name. (More precisely, if an importer's
- ``find_module(name)`` returns a loader, then it will also be searched for
- the package's contents.) Whenever a Distribution's ``activate()`` method
- is invoked, it checks for the presence of namespace packages and updates
- their ``__path__`` contents accordingly.
-
-Applications that manipulate namespace packages or directly alter ``sys.path``
-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
- 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
- contain portions of a namespace package, you will need to call this
- function to ensure they are added to the existing namespace packages.
-
-Although by default ``pkg_resources`` only supports namespace packages for
-filesystem and zip importers, you can extend its support to other "importers"
-compatible with PEP 302 using the ``register_namespace_handler()`` function.
-See the section below on `Supporting Custom Importers`_ for details.
-
-
-``WorkingSet`` Objects
-======================
-
-The ``WorkingSet`` class provides access to a collection of "active"
-distributions. In general, there is only one meaningful ``WorkingSet``
-instance: the one that represents the distributions that are currently active
-on ``sys.path``. This global instance is available under the name
-``working_set`` in the ``pkg_resources`` module. However, specialized
-tools may wish to manipulate working sets that don't correspond to
-``sys.path``, and therefore may wish to create other ``WorkingSet`` instances.
-
-It's important to note that the global ``working_set`` object is initialized
-from ``sys.path`` when ``pkg_resources`` is first imported, but is only updated
-if you do all future ``sys.path`` manipulation via ``pkg_resources`` APIs. If
-you manually modify ``sys.path``, you must invoke the appropriate methods on
-the ``working_set`` instance to keep it in sync. Unfortunately, Python does
-not provide any way to detect arbitrary changes to a list object like
-``sys.path``, so ``pkg_resources`` cannot automatically update the
-``working_set`` based on changes to ``sys.path``.
-
-``WorkingSet(entries=None)``
- 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.
-
- Note that you will not normally construct ``WorkingSet`` instances
- yourself, but instead you will implicitly or explicitly use the global
- ``working_set`` instance. For the most part, the ``pkg_resources`` API
- is designed so that the ``working_set`` is used by default, such that you
- don't have to explicitly refer to it most of the time.
-
-All distributions available directly on ``sys.path`` will be activated
-automatically when ``pkg_resources`` is imported. This behaviour can cause
-version conflicts for applications which require non-default versions of
-those distributions. To handle this situation, ``pkg_resources`` checks for a
-``__requires__`` attribute in the ``__main__`` module when initializing the
-default working set, and uses this to ensure a suitable version of each
-affected distribution is activated. For example::
-
- __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import
- import pkg_resources
-
-
-Basic ``WorkingSet`` Methods
-----------------------------
-
-The following methods of ``WorkingSet`` objects are also available as module-
-level functions in ``pkg_resources`` that apply to the default ``working_set``
-instance. Thus, you can use e.g. ``pkg_resources.require()`` as an
-abbreviation for ``pkg_resources.working_set.require()``:
-
-
-``require(*requirements)``
- Ensure that distributions matching `requirements` are activated
-
- `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
- included, even if they were already activated in this working set.
-
- For the syntax of requirement specifiers, see the section below on
- `Requirements Parsing`_.
-
- In general, it should not be necessary for you to call this method
- directly. It's intended more for use in quick-and-dirty scripting and
- 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 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
- should use the ``resolve()`` method instead, which allows you to pass an
- ``installer`` callback that will be invoked when a needed distribution
- can't be found on the local machine. You can then have this callback
- display a dialog, automatically download the needed distribution, or
- whatever else is appropriate for your application. See the documentation
- below on the ``resolve()`` method for more information, and also on the
- ``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.
- (See `Requirements Parsing`_ below for the syntax.)
-
- The script, if found, will be executed in *the caller's globals*. That's
- because this method is intended to be called from wrapper scripts that
- act as a proxy for the "real" scripts in a distribution. A wrapper script
- usually doesn't need to do anything but invoke this function with the
- correct arguments.
-
- If you need more control over the script execution environment, you
- probably want to use the ``run_script()`` method of a ``Distribution``
- object's `Metadata API`_ instead.
-
-``iter_entry_points(group, name=None)``
- Yield entry point objects from `group` matching `name`
-
- 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
- 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
- advertised by an individual distribution, there is no particular ordering.
-
- Please see the section below on `Entry Points`_ for more information.
-
-
-``WorkingSet`` Methods and Attributes
--------------------------------------
-
-These methods are used to query or manipulate the contents of a specific
-working set, so they must be explicitly invoked on a particular ``WorkingSet``
-instance:
-
-``add_entry(entry)``
- Add a path item to the ``entries``, finding any distributions on it. You
- should use this when you add additional items to ``sys.path`` and you want
- the global ``working_set`` to reflect the change. This method is also
- 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
- 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
- distribution for a given project can be active in a given ``WorkingSet``.
-
-``__iter__()``
- Yield distributions for non-duplicate projects in the working set.
- The yield order is the order in which the items' path entries were
- added to the working set.
-
-``find(req)``
- 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.
- 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`
-
- `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
- 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`
- argument.)
-
-``add(dist, entry=None)``
- 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 it wasn't already present).
-
- `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.)
-
- Note: ``add()`` is automatically called for you by the ``require()``
- method, so you don't normally need to use this method directly.
-
-``entries``
- This attribute represents a "shadow" ``sys.path``, primarily useful for
- debugging. If you are experiencing import problems, you should check
- the global ``working_set`` object's ``entries`` against ``sys.path``, to
- ensure that they match. If they do not, then some part of your program
- is manipulating ``sys.path`` without updating the ``working_set``
- accordingly. IMPORTANT NOTE: do not directly manipulate this attribute!
- Setting it equal to ``sys.path`` will not fix your problem, any more than
- putting black tape over an "engine warning" light will fix your car! If
- this attribute is out of sync with ``sys.path``, it's merely an *indicator*
- of the problem, not the cause of it.
-
-
-Receiving Change Notifications
-------------------------------
-
-Extensible applications and frameworks may need to receive notification when
-a new distribution (such as a plug-in component) has been added to a working
-set. This is what the ``subscribe()`` method and ``add_activation_listener()``
-function are for.
-
-``subscribe(callback)``
- Invoke ``callback(distribution)`` once for each active distribution that is
- in the set now, or gets added later. Because the callback is invoked for
- already-active distributions, you do not need to loop over the working set
- yourself to deal with the existing items; just register the callback and
- be prepared for the fact that it will be called immediately by this method.
-
- Note that callbacks *must not* allow exceptions to propagate, or they will
- interfere with the operation of other callbacks and possibly result in an
- inconsistent working set state. Callbacks should use a try/except block
- to ignore, log, or otherwise process any errors, especially since the code
- that caused the callback to be invoked is unlikely to be able to handle
- the errors any better than the callback itself.
-
-``pkg_resources.add_activation_listener()`` is an alternate spelling of
-``pkg_resources.working_set.subscribe()``.
-
-
-Locating Plugins
-----------------
-
-Extensible applications will sometimes have a "plugin directory" or a set of
-plugin directories, from which they want to load entry points or other
-metadata. The ``find_plugins()`` method allows you to do this, by scanning an
-environment for the newest version of each project that can be safely loaded
-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
- working set without version conflicts or missing requirements.
-
- Example usage::
-
- distributions, errors = working_set.find_plugins(
- Environment(plugin_dirlist)
- )
- 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
- distributions that are in the project's "plugin directory" or directories.
- 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
- ``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
- were loadable, along with any other distributions that are needed to resolve
- 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.
-
- Most applications will use this method mainly on the master ``working_set``
- instance in ``pkg_resources``, and then immediately add the returned
- distributions to the working set so that they are available on sys.path.
- This will make it possible to find any entry points, and allow any other
- 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.
- Then, each project's eggs are tried in descending version order (i.e.,
- newest version first).
-
- An attempt is made to resolve each egg's dependencies. If the attempt is
- successful, the egg and its dependencies are added to the output list and to
- a temporary copy of the working set. The resolution process continues with
- 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
- plugin is tried, until a working version is found. If false, the resolution
- process continues with the next plugin project name.
-
- Some applications may have stricter fallback requirements than others. For
- example, an application that has a database schema or persistent objects
- 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.)
-
- Note that this algorithm gives precedence to satisfying the dependencies of
- alphabetically prior project names in case of version conflicts. If two
- projects named "AaronsPlugin" and "ZekesPlugin" both need different versions
- of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be
- disabled due to version conflict.
-
-
-``Environment`` Objects
-=======================
-
-An "environment" is a collection of ``Distribution`` objects, usually ones
-that are present and potentially importable on the current platform.
-``Environment`` objects are used by ``pkg_resources`` to index available
-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
- sequence of strings such as might be used on ``sys.path``. If a
- `search_path` isn't supplied, ``sys.path`` is used.
-
- `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
- 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
- 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
- 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.
-
-``__getitem__(project_name)``
- Returns a list of distributions for the given project name, ordered
- from newest to oldest version. (And highest to lowest format precedence
- for distributions that contain the same version of the project.) If there
- are no distributions for the project, returns an empty list.
-
-``__iter__()``
- Yield the unique project names of the distributions in this environment.
- The yielded names are always in lower case.
-
-``add(dist)``
- 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.
-
-``can_add(dist)``
- 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.
-
-``__add__(dist_or_env)`` (``+`` operator)
- Add a distribution or environment to an ``Environment`` instance, returning
- a *new* environment object that contains all the distributions previously
- contained by both. The new environment will have a ``platform`` and
- ``python`` of ``None``, meaning that it will not reject any distributions
- from being added to it; it will simply accept whatever is added. If you
- want the added items to be filtered for platform and Python version, or
- you want to add them to the *same* environment instance, you should use
- in-place addition (``+=``) instead.
-
-``__iadd__(dist_or_env)`` (``+=`` operator)
- Add a distribution or environment to an ``Environment`` instance
- *in-place*, updating the existing instance and returning it. The
- ``platform`` and ``python`` filter attributes take effect, so distributions
- in the source that do not have a suitable platform string or Python version
- are silently ignored.
-
-``best_match(req, working_set, installer=None)``
- Find distribution best matching `req` and usable on `working_set`
-
- 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, 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
- 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
- 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.
-
-``scan(search_path=None)``
- Scan `search_path` for distributions usable on `platform`
-
- 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
- ``add()`` to add each one to the environment.
-
-
-``Requirement`` Objects
-=======================
-
-``Requirement`` objects express what versions of a project are suitable for
-some purpose. These objects (or their string form) are used by various
-``pkg_resources`` APIs in order to find distributions that a script or
-distribution needs.
-
-
-Requirements Parsing
---------------------
-
-``parse_requirements(s)``
- Yield ``Requirement`` objects for a string or iterable of lines. Each
- requirement must start on a new line. See below for syntax.
-
-``Requirement.parse(s)``
- Create a ``Requirement`` object from a string or iterable of lines. A
- ``ValueError`` is raised if the string or lines do not contain a valid
- requirement specifier, or if they contain more than one specifier. (To
- parse multiple specifiers from a string or iterable of strings, use
- ``parse_requirements()`` instead.)
-
- The syntax of a requirement specifier is defined in full in PEP 508.
-
- Some examples of valid requirement specifiers::
-
- FooProject >= 1.2
- Fizzy [foo, bar]
- PickyThing>1.6,<=1.9,!=1.8.6
- SomethingWhoseVersionIDontCareAbout
- SomethingWithMarker[foo]>1.0;python_version<"2.7"
-
- The project name is the only required portion of a requirement string, and
- if it's the only thing supplied, the requirement will accept any version
- of that project.
-
- The "extras" in a requirement are used to request optional features of a
- project, that may require additional project distributions in order to
- function. For example, if the hypothetical "Report-O-Rama" project offered
- optional PDF support, it might require an additional library in order to
- provide that support. Thus, a project needing Report-O-Rama's PDF features
- could use a requirement of ``Report-O-Rama[PDF]`` to request installation
- or activation of both Report-O-Rama and any libraries it needs in order to
- provide PDF support. For example, you could use::
-
- pip install Report-O-Rama[PDF]
-
- 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.
-
- The "markers" in a requirement are used to specify when a requirement
- should be installed -- the requirement will be installed if the marker
- evaluates as true in the current environment. For example, specifying
- ``argparse;python_version<"3.0"`` will not install in an Python 3
- environment, but will in a Python 2 environment.
-
-``Requirement`` Methods and Attributes
---------------------------------------
-
-``__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
- 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
- parsed using the ``parse_version()`` utility function. Otherwise, it is
- assumed to be an already-parsed version.
-
- The ``Requirement`` object's version specifiers (``.specs``) are internally
- sorted into ascending version order, and used to establish what ranges of
- versions are acceptable. Adjacent redundant conditions are effectively
- consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and
- ``"<2,<3"`` produces the same results as ``"<2"``). ``"!="`` versions are
- excised from the ranges they fall within. The version being tested for
- acceptability is then checked for membership in the resulting ranges.
-
-``__eq__(other_requirement)``
- A requirement compares equal to another requirement if they have
- case-insensitively equal project names, version specifiers, and "extras".
- (The order that extras and version specifiers are in is also ignored.)
- Equal requirements also have equal hashes, so that requirements can be
- used in sets or as dictionary keys.
-
-``__str__()``
- The string form of a ``Requirement`` is a string that, if passed to
- ``Requirement.parse()``, would return an equal ``Requirement`` object.
-
-``project_name``
- The name of the required project
-
-``key``
- An all-lowercase version of the ``project_name``, useful for comparison
- or indexing.
-
-``extras``
- A tuple of names of "extras" that this requirement calls for. (These will
- be all-lowercase and normalized using the ``safe_extra()`` parsing utility
- function, so they may not exactly equal the extras the requirement was
- created with.)
-
-``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.
-
-``marker``
- An instance of ``packaging.markers.Marker`` that allows evaluation
- against the current environment. May be None if no marker specified.
-
-``url``
- The location to download the requirement from if specified.
-
-Entry Points
-============
-
-Entry points are a simple way for distributions to "advertise" Python objects
-(such as functions or classes) for use by other distributions. Extensible
-applications and frameworks can search for entry points with a particular name
-or group, either from a specific distribution or from all active distributions
-on sys.path, and then inspect or load the advertised objects at will.
-
-Entry points belong to "groups" which are named with a dotted name similar to
-a Python package or module name. For example, the ``setuptools`` package uses
-an entry point named ``distutils.commands`` in order to find commands defined
-by distutils extensions. ``setuptools`` treats the names of entry points
-defined in that group as the acceptable commands for a setup script.
-
-In a similar way, other packages can define their own entry point groups,
-either using dynamic names within the group (like ``distutils.commands``), or
-possibly using predefined names within the group. For example, a blogging
-framework that offers various pre- or post-publishing hooks might define an
-entry point group and look for entry points named "pre_process" and
-"post_process" within that group.
-
-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](https://setuptools.readthedocs.io/en/latest/setuptools.html#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
-could advertise two different ``distutils.commands`` entry points, as long as
-they had different names. However, there is nothing that prevents *different*
-projects from advertising entry points of the same name in the same group. In
-some cases, this is a desirable thing, since the application or framework that
-uses the entry points may be calling them as hooks, or in some other way
-combining them. It is up to the application or framework to decide what to do
-if multiple distributions advertise an entry point; some possibilities include
-using both entry points, displaying an error message, using the first one found
-in sys.path order, etc.
-
-
-Convenience API
----------------
-
-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,
-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.
-
-``load_entry_point(dist, group, name)``
- Load the named entry point from the specified distribution, or raise
- ``ImportError``.
-
-``get_entry_info(dist, group, name)``
- 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
- map for the distribution. This function always returns a dictionary,
- 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
- 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`.
-
- 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
- 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.)
-
- (This API is actually a method of the global ``working_set`` object; see
- the section above on `Basic WorkingSet Methods`_ for more information.)
-
-
-Creating and Parsing
---------------------
-
-``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
- 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
- distribution needs in order to provide this entry point. When the
- 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
- a ``Distribution`` instance.
-
-``EntryPoint.parse(src, dist=None)`` (classmethod)
- Parse a single entry point from string `src`
-
- Entry point syntax follows the form::
-
- name = some.module:some.attr [extra1,extra2]
-
- 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
- ``EntryPoint()`` constructor, along with the other values parsed from
- `src`.
-
-``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod)
- 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
- 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
- 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,
- 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
- 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
- ``parse_group()`` so that the entry points will be linked to the specified
- distribution.
-
-
-``EntryPoint`` Objects
-----------------------
-
-For simple introspection, ``EntryPoint`` objects have attributes that
-correspond exactly to the constructor argument names: ``name``,
-``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In
-addition, the following methods are provided:
-
-``load()``
- Load the entry point, returning the advertised Python object. Effectively
- calls ``self.require()`` then returns ``self.resolve()``.
-
-``require(env=None, installer=None)``
- 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
- 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
- taking a ``Requirement`` instance and returning a matching importable
- ``Distribution`` instance or None.
-
-``resolve()``
- Resolve the entry point from its module and attrs, returning the advertised
- Python object. Raises ``ImportError`` if it cannot be obtained.
-
-``__str__()``
- The string form of an ``EntryPoint`` is a string that could be passed to
- ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``.
-
-
-``Distribution`` Objects
-========================
-
-``Distribution`` objects represent collections of Python code that may or may
-not be importable, and may or may not have metadata and resources associated
-with them. Their metadata may include information such as what other projects
-the distribution depends on, what entry points the distribution advertises, and
-so on.
-
-
-Getting or Creating Distributions
----------------------------------
-
-Most commonly, you'll obtain ``Distribution`` objects from a ``WorkingSet`` or
-an ``Environment``. (See the sections above on `WorkingSet Objects`_ and
-`Environment Objects`_, which are containers for active distributions and
-available distributions, respectively.) You can also obtain ``Distribution``
-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
- 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 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.
-
-However, if you're creating specialized tools for working with distributions,
-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`
-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.
-
-``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
- 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
- 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.
-
-``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod)
- Create a distribution by parsing a local filename. This is a shorter way
- of saying ``Distribution.from_location(normalize_path(filename),
- os.path.basename(filename), metadata)``. In other words, it creates a
- distribution whose location is the normalize form of the filename, parsing
- name and version information from the base portion of the filename. Any
- additional keyword arguments are forwarded to the ``Distribution()``
- constructor.
-
-``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
- ``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
- all these arguments individually.
-
-
-``Distribution`` Attributes
----------------------------
-
-location
- A string indicating the distribution's location. For an importable
- distribution, this is the string that would be added to ``sys.path`` to
- make it actively importable. For non-importable distributions, this is
- simply a filename, URL, or other way of locating the distribution.
-
-project_name
- 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
- function to filter out any unacceptable characters.
-
-key
- ``dist.key`` is short for ``dist.project_name.lower()``. It's used for
- case-insensitive comparison and indexing of distributions by project name.
-
-extras
- A list of strings, giving the names of extra features defined by the
- project's dependency list (the ``extras_require`` argument specified in
- the project's setup script).
-
-version
- A string denoting what release of the project this distribution contains.
- 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
- 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,
- ``ValueError`` is raised.
-
-parsed_version
- The ``parsed_version`` is an object representing a "parsed" form of the
- distribution's ``version``. ``dist.parsed_version`` is a shortcut for
- calling ``parse_version(dist.version)``. It is used to compare or sort
- 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
- supplying the missing version info.
-
-py_version
- The major/minor Python version the distribution supports, as a string.
- For example, "2.7" or "3.4". The default is the current version of Python.
-
-platform
- A string representing the platform the distribution is intended for, or
- ``None`` if the distribution is "pure Python" and therefore cross-platform.
- See `Platform Utilities`_ below for more information on platform strings.
-
-precedence
- A distribution's ``precedence`` is used to determine the relative order of
- two distributions that have the same ``project_name`` and
- ``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``,
- which is the highest (i.e. most preferred) precedence. The full list
- of predefined precedences, from most preferred to least preferred, is:
- ``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and
- ``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used
- only by the ``setuptools.package_index`` module, when sorting distributions
- found in a package index to determine their suitability for installation.
- "System" and "Development" eggs (i.e., ones that use the ``.egg-info``
- format), however, are automatically given a precedence of ``DEVELOP_DIST``.
-
-
-
-``Distribution`` Methods
-------------------------
-
-``activate(path=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
- 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
- merged with the contents provided by any other active distributions. See
- the section above on `Namespace Package Support`_ for more information.)
-
- ``pkg_resources`` adds a notification callback to the global ``working_set``
- that ensures this method is called whenever a distribution is added to it.
- Therefore, you should not normally need to explicitly call this method.
- (Note that this means that namespace packages on ``sys.path`` are always
- imported as soon as ``pkg_resources`` is, which is another reason why
- namespace packages should not contain any code or import statements.)
-
-``as_requirement()``
- Return a ``Requirement`` instance that matches this distribution's project
- name and version.
-
-``requires(extras=())``
- List the ``Requirement`` objects that specify this distribution's
- 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".
-
-``clone(**kw)``
- Create a copy of the distribution. Any supplied keyword arguments override
- the corresponding argument to the ``Distribution()`` constructor, allowing
- you to change some of the copied distribution's attributes.
-
-``egg_name()``
- Return what this distribution's standard filename should be, not including
- the ".egg" extension. For example, a distribution for project "Foo"
- version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()``
- of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are
- converted to underscores. (``Distribution.from_location()`` will convert
- them back when parsing a ".egg" file name.)
-
-``__cmp__(other)``, ``__hash__()``
- Distribution objects are hashed and compared on the basis of their parsed
- version and precedence, followed by their key (lowercase project name),
- location, Python version, and platform.
-
-The following methods are used to access ``EntryPoint`` objects advertised
-by the distribution. See the section above on `Entry Points`_ for more
-detailed information about these operations:
-
-``get_entry_info(group, name)``
- 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
- 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.)
-
-``load_entry_point(group, name)``
- Short for ``get_entry_info(group, name).load()``. Returns the object
- advertised by the named entry point, or raises ``ImportError`` if
- the entry point isn't advertised by this distribution, or there is some
- other import problem.
-
-In addition to the above methods, ``Distribution`` objects also implement all
-of the `IResourceProvider`_ and `IMetadataProvider Methods`_ (which are
-documented in later sections):
-
-* ``has_metadata(name)``
-* ``metadata_isdir(name)``
-* ``metadata_listdir(name)``
-* ``get_metadata(name)``
-* ``get_metadata_lines(name)``
-* ``run_script(script_name, namespace)``
-* ``get_resource_filename(manager, resource_name)``
-* ``get_resource_stream(manager, resource_name)``
-* ``get_resource_string(manager, resource_name)``
-* ``has_resource(resource_name)``
-* ``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.
-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
-=======================
-
-The ``ResourceManager`` class provides uniform access to package resources,
-whether those resources exist as files and directories or are compressed in
-an archive of some kind.
-
-Normally, you do not need to create or explicitly manage ``ResourceManager``
-instances, as the ``pkg_resources`` module creates a global instance for you,
-and makes most of its methods available as top-level names in the
-``pkg_resources`` module namespace. So, for example, this code actually
-calls the ``resource_string()`` method of the global ``ResourceManager``::
-
- import pkg_resources
- my_data = pkg_resources.resource_string(__name__, "foo.dat")
-
-Thus, you can use the APIs below without needing an explicit
-``ResourceManager`` instance; just import and use them as needed.
-
-
-Basic Resource Access
----------------------
-
-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
-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
-multiple distributions, and is therefore ambiguous as to which distribution
-should be searched for the resource.)
-
-If it is a ``Requirement``, then the requirement is automatically resolved
-(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
-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 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.
-
-``resource_exists(package_or_requirement, resource_name)``
- Does the named resource exist? Return ``True`` or ``False`` accordingly.
-
-``resource_stream(package_or_requirement, resource_name)``
- Return a readable file-like object for the specified resource; it may be
- an actual file, a ``StringIO``, or some similar object. The stream is
- in "binary mode", in the sense that whatever bytes are in the resource
- will be read as-is.
-
-``resource_string(package_or_requirement, resource_name)``
- Return the specified resource as a string. The resource is read in
- binary fashion, such that the returned string contains exactly the bytes
- that are stored in the resource.
-
-``resource_isdir(package_or_requirement, resource_name)``
- Is the named resource a directory? Return ``True`` or ``False``
- accordingly.
-
-``resource_listdir(package_or_requirement, resource_name)``
- List the contents of the named resource directory, just like ``os.listdir``
- except that it works even if the resource is in a zipfile.
-
-Note that only ``resource_exists()`` and ``resource_isdir()`` are insensitive
-as to the resource type. You cannot use ``resource_listdir()`` on a file
-resource, and you can't use ``resource_string()`` or ``resource_stream()`` on
-directory resources. Using an inappropriate method for the resource type may
-result in an exception or undefined behavior, depending on the platform and
-distribution format involved.
-
-
-Resource Extraction
--------------------
-
-``resource_filename(package_or_requirement, resource_name)``
- Sometimes, it is not sufficient to access a resource in string or stream
- form, and a true filesystem filename is needed. In such cases, you can
- use this method (or module-level function) to obtain a filename for a
- resource. If the resource is in an archive distribution (such as a zipped
- egg), it will be extracted to a cache directory, and the filename within
- the cache will be returned. If the named resource is a directory, then
- all resources within that directory (including subdirectories) are also
- extracted. If the named resource is a C extension or "eager resource"
- (see the ``setuptools`` documentation for details), then all C extensions
- and eager resources are extracted at the same time.
-
- Archived resources are extracted to a cache location that can be managed by
- the following two methods:
-
-``set_extraction_path(path)``
- Set the base path where resources will be extracted to, if needed.
-
- If you do not call this routine before any extractions take place, the
- path defaults to the return value of ``get_default_cache()``. (Which is
- based on the ``PYTHON_EGG_CACHE`` environment variable, with various
- platform-specific fallbacks. See that routine's documentation for more
- details.)
-
- Resources are extracted to subdirectories of this path based upon
- information given by the resource provider. You may set this to a
- temporary directory, but then you must call ``cleanup_resources()`` to
- delete the extracted files when done. There is no guarantee that
- ``cleanup_resources()`` will be able to remove all extracted files. (On
- Windows, for example, you can't unlink .pyd or .dll files that are still
- in use.)
-
- Note that you may not change the extraction path for a given resource
- manager once resources have been extracted, unless you first call
- ``cleanup_resources()``.
-
-``cleanup_resources(force=False)``
- Delete all extracted resource files and directories, returning a list
- of the file and directory names that could not be successfully removed.
- This function does not have any concurrency protection, so it should
- generally only be called when the extraction path is a temporary
- directory exclusive to a single process. This method is not
- automatically called; you must call it explicitly or register it as an
- ``atexit`` function if you wish to ensure cleanup of a temporary
- directory used for extractions.
-
-
-"Provider" Interface
---------------------
-
-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
-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`
-
- 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
- enclosing egg (which may not be the name of the enclosing zipfile!),
- 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
- obtain an extraction location, and only for names they intend to
- extract, as it tracks the generated names for possible cleanup later.
-
-``extraction_error()``
- Raise an ``ExtractionError`` describing the active exception as interfering
- with the extraction process. You should call this if you encounter any
- OS errors extracting the file to the cache path; it will format the
- operating system exception for you, and add other information to the
- ``ExtractionError`` instance that may be needed by programs that want to
- wrap or handle extraction errors themselves.
-
-``postprocess(tempname, filename)``
- 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`
- is the name it will be renamed to by the caller after this routine
- returns.
-
-
-Metadata API
-============
-
-The metadata API is used to access metadata resources bundled in a pluggable
-distribution. Metadata resources are virtual files or directories containing
-information about the distribution, such as might be used by an extensible
-application or framework to connect "plugins". Like other kinds of resources,
-metadata resource names are ``/``-separated and should not contain ``..`` or
-begin with a ``/``. You should not use ``os.path`` routines to manipulate
-resource paths.
-
-The metadata API is provided by objects implementing the ``IMetadataProvider``
-or ``IResourceProvider`` interfaces. ``Distribution`` objects implement this
-interface, as do objects returned by the ``get_provider()`` function:
-
-``get_provider(package_or_requirement)``
- If a package name is supplied, return an ``IResourceProvider`` for the
- package. If a ``Requirement`` is supplied, resolve it by returning a
- ``Distribution`` from the current working set (searching the current
- ``Environment`` if necessary and adding the newly found ``Distribution``
- to the working set). If the named package can't be imported, or the
- ``Requirement`` can't be satisfied, an exception is raised.
-
- NOTE: if you use a package name rather than a ``Requirement``, the object
- you get back may not be a pluggable distribution, depending on the method
- by which the package was installed. In particular, "development" packages
- and "single-version externally-managed" packages do not have any way to
- map from a package name to the corresponding project's metadata. Do not
- write code that passes a package name to ``get_provider()`` and then tries
- to retrieve project metadata from the returned object. It may appear to
- work when the named package is in an ``.egg`` file or directory, but
- it will fail in other installation scenarios. If you want project
- metadata, you need to ask for a *project*, not a package.
-
-
-``IMetadataProvider`` Methods
------------------------------
-
-The methods provided by objects (such as ``Distribution`` instances) that
-implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are:
-
-``has_metadata(name)``
- Does the named metadata resource exist?
-
-``metadata_isdir(name)``
- Is the named metadata resource a directory?
-
-``metadata_listdir(name)``
- List of metadata names in the directory (like ``os.listdir()``)
-
-``get_metadata(name)``
- Return the named metadata resource as a string. The data is read in binary
- mode; i.e., the exact bytes of the resource file are returned.
-
-``get_metadata_lines(name)``
- Yield named metadata resource as list of non-blank non-comment lines. This
- is short for calling ``yield_lines(provider.get_metadata(name))``. See the
- section on `yield_lines()`_ below for more information on the syntax it
- recognizes.
-
-``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
- a module dictionary if the script is being run as a module.
-
-
-Exceptions
-==========
-
-``pkg_resources`` provides a simple exception hierarchy for problems that may
-occur when processing requests to locate and activate packages::
-
- ResolutionError
- DistributionNotFound
- VersionConflict
- UnknownExtra
-
- ExtractionError
-
-``ResolutionError``
- This class is used as a base class for the other three exceptions, so that
- you can catch all of them with a single "except" clause. It is also raised
- directly for miscellaneous requirement-resolution problems like trying to
- run a script that doesn't exist in the distribution it was requested from.
-
-``DistributionNotFound``
- A distribution needed to fulfill a requirement could not be found.
-
-``VersionConflict``
- The requested version of a project conflicts with an already-activated
- version of the same project.
-
-``UnknownExtra``
- One of the "extras" requested was not recognized by the distribution it
- was requested from.
-
-``ExtractionError``
- A problem occurred extracting a resource to the Python Egg cache. The
- following attributes are available on instances of this exception:
-
- manager
- The resource manager that raised this exception
-
- cache_path
- The base directory for resource extraction
-
- original_error
- The exception instance that caused extraction to fail
-
-
-Supporting Custom Importers
-===========================
-
-By default, ``pkg_resources`` supports normal filesystem imports, and
-``zipimport`` importers. If you wish to use the ``pkg_resources`` features
-with other (PEP 302-compatible) importers or module loaders, you may need to
-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,
- if true, means the finder should yield only ``Distribution`` objects whose
- ``location`` is equal to the path item provided.)
-
- See the source of the ``pkg_resources.find_on_path`` function for an
- 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
- 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
- with a signature like this::
-
- def namespace_handler(importer, path_entry, moduleName, module):
- # return a path_entry to use for child packages
-
- Namespace handlers are only called if the relevant importer object has
- already agreed that it can handle the relevant path item. The handler
- should only return a subpath if the module ``__path__`` does not already
- contain an equivalent subpath. Otherwise, it should return None.
-
- For an example namespace handler, see the source of the
- ``pkg_resources.file_ns_handler`` function, which is used for both zipfile
- importing and regular importing.
-
-
-IResourceProvider
------------------
-
-``IResourceProvider`` is an abstract class that documents what methods are
-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
-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
- filesystem.
-
-``get_resource_stream(manager, 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`.
-
-``has_resource(resource_name)``
- Does the package contain the named resource?
-
-``resource_isdir(resource_name)``
- Is the named resource a directory? Return a false value if the resource
- does not exist or is not a directory.
-
-``resource_listdir(resource_name)``
- Return a list of the contents of the resource directory, ala
- ``os.listdir()``. Requesting the contents of a non-existent directory may
- raise an exception.
-
-Note, by the way, that your provider classes need not (and should not) subclass
-``IResourceProvider`` or ``IMetadataProvider``! These classes exist solely
-for documentation purposes and do not provide any useful implementation code.
-You may instead wish to subclass one of the `built-in resource providers`_.
-
-
-Built-in Resource Providers
----------------------------
-
-``pkg_resources`` includes several provider classes that are automatically used
-where appropriate. Their inheritance tree looks like this::
-
- NullProvider
- EggProvider
- DefaultProvider
- PathMetadata
- ZipProvider
- EggMetadata
- EmptyProvider
- FileMetadata
-
-
-``NullProvider``
- This provider class is just an abstract base that provides for common
- provider behaviors (such as running scripts), given a definition for just
- a few abstract methods.
-
-``EggProvider``
- This provider class adds in some egg-specific features that are common
- to zipped and unzipped eggs.
-
-``DefaultProvider``
- This provider class is used for unpacked eggs and "plain old Python"
- filesystem modules.
-
-``ZipProvider``
- This provider class is used for all zipped modules, whether they are eggs
- or not.
-
-``EmptyProvider``
- This provider class always returns answers consistent with a provider that
- has no metadata or resources. ``Distribution`` objects created without
- a ``metadata`` argument use an instance of this provider class instead.
- Since all ``EmptyProvider`` instances are equivalent, there is no need
- to have more than one instance. ``pkg_resources`` therefore creates a
- global instance of this class under the name ``empty_provider``, and you
- may use it if you have need of an ``EmptyProvider`` instance.
-
-``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`
- 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
- 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
- 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
- that also contains other eggs.
-
-``FileMetadata(path_to_pkg_info)``
- Create an ``IResourceProvider`` that provides exactly one metadata
- resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO
- file. This is basically the same as an ``EmptyProvider``, except that
- requests for ``PKG-INFO`` will be answered using the contents of the
- designated file. (This provider is used to wrap ``.egg-info`` files
- installed by vendor-supplied system packages.)
-
-
-Utility Functions
-=================
-
-In addition to its high-level APIs, ``pkg_resources`` also includes several
-generally-useful utility routines. These routines are used to implement the
-high-level APIs, but can also be quite useful by themselves.
-
-
-Parsing Utilities
------------------
-
-``parse_version(version)``
- Parsed a project's version string as defined by PEP 440. The returned
- value will be an object that represents the version. These objects may
- be compared to each other and sorted. The sorting algorithm is as defined
- by PEP 440 with the addition that any version which is not a valid PEP 440
- version will be considered less than any valid PEP 440 version and the
- invalid versions will continue sorting using the original algorithm.
-
-.. _yield_lines():
-
-``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
- 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
- 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
- a file object or a list of strings to ``yield_lines`` will both work.
- (Note that between each string in a sequence of strings there is assumed to
- be an implicit line break, so lines cannot bridge two strings in a
- sequence.)
-
- This routine is used extensively by ``pkg_resources`` to parse metadata
- and file formats of various kinds, and most other ``pkg_resources``
- parsing functions that yield multiple values will use it to break up their
- input. However, this routine is idempotent, so calling ``yield_lines()``
- on the output of another call to ``yield_lines()`` is completely harmless.
-
-``split_sections(strs)``
- Split a string (or possibly-nested iterable thereof), yielding ``(section,
- content)`` pairs found using an ``.ini``-like syntax. Each ``section`` is
- a whitespace-stripped version of the section name ("``[section]``")
- and each ``content`` is a list of stripped lines excluding blank lines and
- comment-only lines. If there are any non-blank, non-comment lines before
- the first section header, they're yielded in a first ``section`` of
- ``None``.
-
- This routine uses ``yield_lines()`` as its front end, so you can pass in
- anything that ``yield_lines()`` accepts, such as an open text file, string,
- or sequence of strings. ``ValueError`` is raised if a malformed section
- header is found (i.e. a line starting with ``[`` but not ending with
- ``]``).
-
- Note that this simplistic parser assumes that any line whose first nonblank
- character is ``[`` is a section heading, so it can't support .ini format
- variations that allow ``[`` as the first nonblank character on other lines.
-
-``safe_name(name)``
- Return a "safe" form of a project's name, suitable for use in a
- ``Requirement`` string, as a distribution name, or a PyPI project name.
- All non-alphanumeric runs are condensed to single "-" characters, such that
- a name like "The $$$ Tree" becomes "The-Tree". Note that if you are
- generating a filename from this value you should combine it with a call to
- ``to_filename()`` so all dashes ("-") are replaced by underscores ("_").
- 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, 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
- string or a setup script's ``extras_require`` keyword. This routine is
- similar to ``safe_name()`` except that non-alphanumeric runs are replaced
- by a single underbar (``_``), and the result is lowercased.
-
-``to_filename(name_or_version)``
- Escape a name or version string so it can be used in a dash-separated
- filename (or ``#egg=name-version`` tag) without ambiguity. You
- should only pass in values that were returned by ``safe_name()`` or
- ``safe_version()``.
-
-
-Platform Utilities
-------------------
-
-``get_build_platform()``
- Return this platform's identifier string. For Windows, the return value
- 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
- on the local machine. (Backward compatibility note: setuptools versions
- prior to 0.6b1 called this function ``get_platform()``, and the function is
- still available under that name for backward compatibility reasons.)
-
-``get_supported_platform()`` (New in 0.6b1)
- This is the similar to ``get_build_platform()``, but is the maximum
- platform version that the local machine supports. You will usually want
- to use this value as the ``provided`` argument to the
- ``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
- 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 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.
-
-``get_default_cache()``
- Determine the default cache location for extracting resources from zipped
- eggs. This routine returns the ``PYTHON_EGG_CACHE`` environment variable,
- if set. Otherwise, on Windows, it returns a "Python-Eggs" subdirectory of
- the user's "Application Data" directory. On all other systems, it returns
- ``os.path.expanduser("~/.python-eggs")`` if ``PYTHON_EGG_CACHE`` is not
- set.
-
-
-PEP 302 Utilities
------------------
-
-``get_importer(path_item)``
- A deprecated alias for ``pkgutil.get_importer()``
-
-
-File/Path Utilities
--------------------
-
-``ensure_directory(path)``
- 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
- 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 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.
-
-History
--------
-
-0.6c9
- * Fix ``resource_listdir('')`` always returning an empty list for zipped eggs.
-
-0.6c7
- * Fix package precedence problem where single-version eggs installed in
- ``site-packages`` would take precedence over ``.egg`` files (or directories)
- installed in ``site-packages``.
-
-0.6c6
- * Fix extracted C extensions not having executable permissions under Cygwin.
-
- * Allow ``.egg-link`` files to contain relative paths.
-
- * Fix cache dir defaults on Windows when multiple environment vars are needed
- to construct a path.
-
-0.6c4
- * Fix "dev" versions being considered newer than release candidates.
-
-0.6c3
- * Python 2.5 compatibility fixes.
-
-0.6c2
- * Fix a problem with eggs specified directly on ``PYTHONPATH`` on
- case-insensitive filesystems possibly not showing up in the default
- working set, due to differing normalizations of ``sys.path`` entries.
-
-0.6b3
- * Fixed a duplicate path insertion problem on case-insensitive filesystems.
-
-0.6b1
- * Split ``get_platform()`` into ``get_supported_platform()`` and
- ``get_build_platform()`` to work around a Mac versioning problem that caused
- the behavior of ``compatible_platforms()`` to be platform specific.
-
- * Fix entry point parsing when a standalone module name has whitespace
- between it and the extras.
-
-0.6a11
- * Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that
- cache permission problems get a more user-friendly explanation of the
- problem, and so that programs can catch and handle extraction errors if they
- need to.
-
-0.6a10
- * Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()``
- method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods
- to ``Environment``.
-
- * ``safe_name()`` now allows dots in project names.
-
- * There is a new ``to_filename()`` function that escapes project names and
- versions for safe use in constructing egg filenames from a Distribution
- object's metadata.
-
- * Added ``Distribution.clone()`` method, and keyword argument support to other
- ``Distribution`` constructors.
-
- * Added the ``DEVELOP_DIST`` precedence, and automatically assign it to
- eggs using ``.egg-info`` format.
-
-0.6a9
- * Don't raise an error when an invalid (unfinished) distribution is found
- unless absolutely necessary. Warn about skipping invalid/unfinished eggs
- when building an Environment.
-
- * Added support for ``.egg-info`` files or directories with version/platform
- information embedded in the filename, so that system packagers have the
- option of including ``PKG-INFO`` files to indicate the presence of a
- system-installed egg, without needing to use ``.egg`` directories, zipfiles,
- or ``.pth`` manipulation.
-
- * Changed ``parse_version()`` to remove dashes before pre-release tags, so
- that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal
- to ``0.2rc1``. The idea that a dash *always* meant a post-release version
- was highly non-intuitive to setuptools users and Python developers, who
- seem to want to use ``-rc`` version numbers a lot.
-
-0.6a8
- * Fixed a problem with ``WorkingSet.resolve()`` that prevented version
- conflicts from being detected at runtime.
-
- * Improved runtime conflict warning message to identify a line in the user's
- program, rather than flagging the ``warn()`` call in ``pkg_resources``.
-
- * Avoid giving runtime conflict warnings for namespace packages, even if they
- were declared by a different package than the one currently being activated.
-
- * Fix path insertion algorithm for case-insensitive filesystems.
-
- * Fixed a problem with nested namespace packages (e.g. ``peak.util``) not
- being set as an attribute of their parent package.
-
-0.6a6
- * Activated distributions are now inserted in ``sys.path`` (and the working
- set) just before the directory that contains them, instead of at the end.
- This allows e.g. eggs in ``site-packages`` to override unmanaged modules in
- the same location, and allows eggs found earlier on ``sys.path`` to override
- ones found later.
-
- * When a distribution is activated, it now checks whether any contained
- non-namespace modules have already been imported and issues a warning if
- a conflicting module has already been imported.
-
- * 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.
-
- * Fixed a problem extracting zipped files on Windows, when the egg in question
- has had changed contents but still has the same version number.
-
-0.6a4
- * Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3.
-
-0.6a3
- * Added ``safe_extra()`` parsing utility routine, and use it for Requirement,
- EntryPoint, and Distribution objects' extras handling.
-
-0.6a1
- * Enhanced performance of ``require()`` and related operations when all
- requirements are already in the working set, and enhanced performance of
- directory scanning for distributions.
-
- * Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than
- ``zipimport``, and the previously-broken "eager resource" support.
-
- * Fixed ``pkg_resources.resource_exists()`` not working correctly, along with
- some other resource API bugs.
-
- * Many API changes and enhancements:
-
- * Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and
- ``get_entry_info`` APIs for dynamic plugin discovery.
-
- * ``list_resources`` is now ``resource_listdir`` (and it actually works)
-
- * Resource API functions like ``resource_string()`` that accepted a package
- name and resource name, will now also accept a ``Requirement`` object in
- place of the package name (to allow access to non-package data files in
- an egg).
-
- * ``get_provider()`` will now accept a ``Requirement`` instance or a module
- name. If it is given a ``Requirement``, it will return a corresponding
- ``Distribution`` (by calling ``require()`` if a suitable distribution
- isn't already in the working set), rather than returning a metadata and
- resource provider for a specific module. (The difference is in how
- resource paths are interpreted; supplying a module name means resources
- path will be module-relative, rather than relative to the distribution's
- root.)
-
- * ``Distribution`` objects now implement the ``IResourceProvider`` and
- ``IMetadataProvider`` interfaces, so you don't need to reference the (no
- longer available) ``metadata`` attribute to get at these interfaces.
-
- * ``Distribution`` and ``Requirement`` both have a ``project_name``
- attribute for the project name they refer to. (Previously these were
- ``name`` and ``distname`` attributes.)
-
- * The ``path`` attribute of ``Distribution`` objects is now ``location``,
- 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' 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.
-
- * ``Distribution`` objects now have an ``as_requirement()`` method that
- returns a ``Requirement`` for the distribution's project name and version.
-
- * Distribution objects no longer have an ``installed_on()`` method, and the
- ``install_on()`` method is now ``activate()`` (but may go away altogether
- soon). The ``depends()`` method has also been renamed to ``requires()``,
- and ``InvalidOption`` is now ``UnknownExtra``.
-
- * ``find_distributions()`` now takes an additional argument called ``only``,
- that tells it to only yield distributions whose location is the passed-in
- path. (It defaults to False, so that the default behavior is unchanged.)
-
- * ``AvailableDistributions`` is now called ``Environment``, and the
- ``get()``, ``__len__()``, and ``__contains__()`` methods were removed,
- because they weren't particularly useful. ``__getitem__()`` no longer
- raises ``KeyError``; it just returns an empty list if there are no
- distributions for the named project.
-
- * The ``resolve()`` method of ``Environment`` is now a method of
- ``WorkingSet`` instead, and the ``best_match()`` method now uses a working
- set instead of a path list as its second argument.
-
- * There is a new ``pkg_resources.add_activation_listener()`` API that lets
- you register a callback for notifications about distributions added to
- ``sys.path`` (including the distributions already on it). This is
- basically a hook for extensible applications and frameworks to be able to
- search for plugin metadata in distributions added at runtime.
-
-0.5a13
- * Fixed a bug in resource extraction from nested packages in a zipped egg.
-
-0.5a12
- * Updated extraction/cache mechanism for zipped resources to avoid inter-
- process and inter-thread races during extraction. The default cache
- location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable,
- and the default Windows cache is now a ``Python-Eggs`` subdirectory of the
- current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE``
- variable isn't set.
-
-0.5a10
- * Fix a problem with ``pkg_resources`` being confused by non-existent eggs on
- ``sys.path`` (e.g. if a user deletes an egg without removing it from the
- ``easy-install.pth`` file).
-
- * Fix a problem with "basket" support in ``pkg_resources``, where egg-finding
- never actually went inside ``.egg`` files.
-
- * Made ``pkg_resources`` import the module you request resources from, if it's
- not already imported.
-
-0.5a4
- * ``pkg_resources.AvailableDistributions.resolve()`` and related methods now
- accept an ``installer`` argument: a callable taking one argument, a
- ``Requirement`` instance. The callable must return a ``Distribution``
- object, or ``None`` if no distribution is found. This feature is used by
- EasyInstall to resolve dependencies by recursively invoking itself.
-
-0.4a4
- * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource
- directory extraction for zipped eggs.
-
-0.4a3
- * Fixed scripts not being able to see a ``__file__`` variable in ``__main__``
-
- * Fixed a problem with ``resource_isdir()`` implementation that was introduced
- in 0.4a2.
-
-0.4a1
- * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and
- ``!=``) when only one condition was included.
-
- * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of
- arbitrary distribution names and versions found on PyPI.
-
-0.3a4
- * ``pkg_resources`` now supports resource directories, not just the resources
- in them. In particular, there are ``resource_listdir()`` and
- ``resource_isdir()`` APIs.
-
- * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain
- multiple distributions in subdirectories whose names end with ``.egg``.
- Having such a "basket" in a directory on ``sys.path`` is equivalent to
- having the individual eggs in that directory, but the contained eggs can
- be individually added (or not) to ``sys.path``. Currently, however, there
- is no automated way to create baskets.
-
- * Namespace package manipulation is now protected by the Python import lock.
-
-0.3a1
- * Initial release.
-
--- /dev/null
+: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 enviornment, 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.
+++ /dev/null
-: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 enviornment, 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.
+++ /dev/null
-=====================================================
-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 project 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``.
--- /dev/null
+``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.
+
+``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`.
+
+``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`.
+
+``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.
+
+``use_2to3_exclude_fixers``
+ List of fixer names to be skipped.
+
+``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.
--- /dev/null
+===============
+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.
+++ /dev/null
-===============
-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.
--- /dev/null
+=======
+Roadmap
+=======
+
+Setuptools maintains a series of `milestones
+<https://github.com/pypa/setuptools/milestones>`_ to track
+a roadmap of large-scale goals.
+++ /dev/null
-=======
-Roadmap
-=======
-
-Setuptools maintains a series of `milestones
-<https://github.com/pypa/setuptools/milestones>`_ to track
-a roadmap of large-scale goals.
--- /dev/null
+==================================================
+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.
+
+* 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.
+
+.. contents:: **Table of Contents**
+
+
+-----------------
+Developer's Guide
+-----------------
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+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 .``, as :pep:`517` does not support editable installs.
+
+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 ``pep517``.
+
+ .. 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.
+
+
+
+
+
+
+
+
+
+
+
+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/
+++ /dev/null
-==================================================
-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.
-
-* 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.
-
-.. contents:: **Table of Contents**
-
-
------------------
-Developer's Guide
------------------
-
-
-Installing ``setuptools``
-=========================
-
-.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
-
-To install the latest version of setuptools, use::
-
- pip install --upgrade setuptools
-
-Refer to `Installing Packages`_ guide for more information.
-
-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 distributions 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::
-
- 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 to display on PyPI
- author="Me",
- author_email="me@example.com",
- description="This is an Example Package",
- 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/",
- },
- classifiers=[
- "License :: OSI Approved :: Python Software Foundation License"
- ]
-
- # could also include long_description, download_url, 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
-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`` 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`_
-* 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:: keywords.txt
-
-
-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.
-
-``find_namespace_packages()``
------------------------------
-In Python 3.3+, ``setuptools`` also provides the ``find_namespace_packages`` variant
-of ``find_packages``, which has the same function signature as
-``find_packages``, but works with `PEP 420`_ compliant implicit namespace
-packages. Here is a minimal setup script using ``find_namespace_packages``::
-
- from setuptools import setup, find_namespace_packages
- setup(
- name="HelloWorld",
- version="0.1",
- packages=find_namespace_packages(),
- )
-
-
-Keep in mind that according to PEP 420, you may have to either re-organize your
-codebase a bit or define a few exclusions, as the definition of an implicit
-namespace package is quite lenient, so for a project organized like so::
-
-
- ├── namespace
- │ └── mypackage
- │ ├── __init__.py
- │ └── mod1.py
- ├── setup.py
- └── tests
- └── test_mod1.py
-
-A naive ``find_namespace_packages()`` would install both ``namespace.mypackage`` and a
-top-level package called ``tests``! One way to avoid this problem is to use the
-``include`` keyword to whitelist the packages to include, like so::
-
- from setuptools import setup, find_namespace_packages
-
- setup(
- name="namespace.mypackage",
- version="0.1",
- packages=find_namespace_packages(include=["namespace.*"])
- )
-
-Another option is to use the "src" layout, where all package code is placed in
-the ``src`` directory, like so::
-
-
- ├── setup.py
- ├── src
- │ └── namespace
- │ └── mypackage
- │ ├── __init__.py
- │ └── mod1.py
- └── tests
- └── test_mod1.py
-
-With this layout, the package directory is specified as ``src``, as such::
-
- setup(name="namespace.mypackage",
- version="0.1",
- package_dir={"": "src"},
- packages=find_namespace_packages(where="src"))
-
-.. _PEP 420: https://www.python.org/dev/peps/pep-0420/
-
-.. _Automatic Script Creation:
-
-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 with pip), 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
-----------------------
-
-.. 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.
-
-.. _Declaring Dependencies:
-
-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 pip 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 pip, ``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
---------------------------------
-
-.. 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::
-
- 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 "pip install"
-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:
-
-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.)
-
-__ 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``.
-
-``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 `Importlib Resources`_ for
-a quick example of converting code that uses ``__file__`` to use
-``pkg_resources`` instead.
-
-.. _Importlib Resources: https://docs.python.org/3/library/importlib.html#module-importlib.resources
-
-
-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 in the package.
-
-.. _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.
-
-
-Extensible Applications and Frameworks
-======================================
-
-
-.. _Entry Points:
-
-.. _Dynamic Discovery of Services and Plugins:
-
-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``, 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; 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.
-
-
-Distributing a ``setuptools``-based project
-===========================================
-
-Detailed instructions to distribute a setuptools project can be found at
-`Packaging project tutorials`_.
-
-.. _Packaging project tutorials: https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives
-
-Before you begin, make sure you have the latest versions of setuptools and wheel::
-
- pip install --upgrade setuptools wheel
-
-To build a setuptools project, run this command from the same directory where
-setup.py is located::
-
- setup.py sdist bdist_wheel
-
-This will generate distribution archives in the `dist` directory.
-
-Before you upload the generated archives make sure you're registered on
-https://test.pypi.org/account/register/. You will also need to verify your email
-to be able to upload any packages.
-You should install twine to be able to upload packages::
-
- pip install --upgrade twine
-
-Now, to upload these archives, run::
-
- twine upload --repository-url https://test.pypi.org/legacy/ dist/*
-
-To install your newly uploaded package ``example_pkg``, you can use pip::
-
- pip install --index-url https://test.pypi.org/simple/ example_pkg
-
-If you have issues at any point, please refer to `Packaging project tutorials`_
-for clarification.
-
-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.
-
-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.
-
-.. _Namespace Packages:
-
-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 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 `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 "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 `egg_info`_ and `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.
-
-
------------------
-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 `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 `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>`_.
-
-
------------------------------------------
-Configuring setup() 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.
-
-.. 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
- License :: OSI Approved :: BSD License
- 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
- install_requires =
- requests
- importlib; python_version == "2.6"
-
- [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
-
- [options.data_files]
- /etc/my_package =
- site.d/00_default.conf
- host.d/00_default.conf
- data = data/img/logo.png, data/svg/icon.svg
-
-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.
-
-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 .``, as :pep:`517` does not support editable installs.
-
-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 ``pep517``.
-
- .. 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.
-
-
-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 (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_file str
-license_files list-comma
-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
-============================== ================= ================= =============== =====
-
-.. note::
- 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.
-
-Notes:
-1. The `version` file attribute has only been supported since 39.2.0.
-
-Options
--------
-
-======================= =================================== =============== =====
-Key Type Minimum Version Notes
-======================= =================================== =============== =====
-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:, find_namespace:, list-comma
-package_dir dict
-package_data section (1)
-exclude_package_data section
-namespace_packages list-comma
-py_modules list-comma
-data_files dict 40.6.0
-======================= =================================== =============== =====
-
-.. note::
-
- **packages** - 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``.
-
- **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
-
-Notes:
-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`.
-
-
-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
-----------------------------
-
-.. 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
--------------------------
-
-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).
-
-
-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/
--- /dev/null
+-----------------
+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 `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 `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>`_.
--- /dev/null
+====================
+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 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.)
+
+__ 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``.
+
+``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 `Importlib Resources`_ for
+a quick example of converting code that uses ``__file__`` to use
+``pkg_resources`` instead.
+
+.. _Importlib Resources: https://docs.python.org/3/library/importlib.html#module-importlib.resources
+
+
+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 in the package.
\ No newline at end of file
--- /dev/null
+-----------------------------------------
+Configuring setup() 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.
+
+.. 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
+ License :: OSI Approved :: BSD License
+ 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
+ install_requires =
+ requests
+ importlib; python_version == "2.6"
+
+ [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
+
+ [options.data_files]
+ /etc/my_package =
+ site.d/00_default.conf
+ host.d/00_default.conf
+ data = data/img/logo.png, data/svg/icon.svg
+
+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 (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_file str
+license_files list-comma
+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
+============================== ================= ================= =============== =====
+
+.. note::
+ 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.
+
+Notes:
+1. The `version` file attribute has only been supported since 39.2.0.
+
+Options
+-------
+
+======================= =================================== =============== =====
+Key Type Minimum Version Notes
+======================= =================================== =============== =====
+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:, find_namespace:, list-comma
+package_dir dict
+package_data section (1)
+exclude_package_data section
+namespace_packages list-comma
+py_modules list-comma
+data_files dict 40.6.0
+======================= =================================== =============== =====
+
+.. note::
+
+ **packages** - 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``.
+
+ **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
+
+Notes:
+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`.
--- /dev/null
+=====================================
+Dependencies Management in Setuptools
+=====================================
+
+There are three types of dependency styles offered by setuptools:
+1) build system requirement, 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/>`_
+
+
+.. contents::
+
+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 need to actually
+do the packgaging (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
+:ref:`quickstart` or (WIP)):
+
+.. code-block:: ini
+
+ [build-system]
+ requires = ["setuptools", "wheel"]
+ #...
+
+.. 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 :ref:`guide on
+ deprecated practice (WIP)`
+
+
+
+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
+finess to it, let's start with a simple example.
+
+.. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ docutils
+ BazSpam ==1.1
+
+.. code-block:: python
+
+ setup(
+ #...,
+ install_requires = [
+ '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
+
+.. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ enum34;python_version<'3.4'
+
+.. code-block:: python
+
+ setup(
+ #...
+ install_requires=[
+ "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:
+
+.. code-block:: ini
+
+ [options]
+ #...
+ install_requires =
+ enum34;python_version<'3.4'
+ pywin32 >= 1.0;platform_system=='Windows'
+
+.. code-block:: python
+
+ setup(
+ #...
+ install_requires=[
+ "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:
+
+.. code-block:: ini
+
+ [options]
+ #...
+ dependency_links = http://peak.telecommunity.com/snapshots/
+
+.. 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:
+
+.. code-block:: ini
+
+ [metadata]
+ name = Package-A
+
+ [options.extras_require]
+ PDF = ReportLab>=1.2; RXP
+
+
+.. code-block:: python
+
+ setup(
+ name="Project-A",
+ #...
+ extras_require={
+ "PDF": ["ReportLab>=1.2", "RXP"],
+ }
+ )
+
+The name ``PDF`` is an arbitary identifier of such a list of dependencies, to
+which other components can refer and have them installed. There are two common
+use cases.
+
+First is the console_scripts entry point:
+
+.. code-block:: ini
+
+ [metadata]
+ name = Project A
+ #...
+
+ [options]
+ #...
+ entry_points=
+ [console_scripts]
+ rst2pdf = project_a.tools.pdfgen [PDF]
+ rst2html = project_a.tools.htmlgen
+
+.. code-block:: python
+
+ setup(
+ name = "Project-A"
+ #...,
+ entry_points={
+ "console_scripts": [
+ "rst2pdf = project_a.tools.pdfgen [PDF]",
+ "rst2html = project_a.tools.htmlgen",
+ ],
+ }
+ )
+
+When the script ``rst2pdf`` is run, it will trigger the installation of
+the two dependencies ``PDF`` maps to.
+
+The second use case 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::
+
+.. code-block:: ini
+
+ [metadata]
+ name = Project-B
+ #...
+
+ [options]
+ #...
+ install_requires =
+ Project-A[PDF]
+
+.. code-block:: python
+
+ 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::
+ Best practice: 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).
+
+
+Python requirement
+==================
+In some cases, you might need to specify the minimum required python version.
+This is handled with the ``python_requires`` keyword supplied to ``setup.cfg``
+or ``setup.py``.
+
+Example WIP
\ No newline at end of file
--- /dev/null
+"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``, 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; 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.
\ No newline at end of file
--- /dev/null
+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 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 `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 "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 `egg_info`_ and `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
+---------------------------------
+
+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
+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`` 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`_
+* The `egg_info`_ command
\ No newline at end of file
--- /dev/null
+.. _`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 helloworld():
+ print("Hello world")
+
+and ``__main__.py`` providing a hook:
+
+ 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``::
+
+.. code-block:: ini
+
+ [options.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::
+
+ <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.
+
+
+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,
+`importlib_metadata <https://pypi.org/project/importlib_metadata>`_.
+
+For example, to find the console script entry points from the example above::
+
+.. code-block:: python
+
+ >>> 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:: python
+
+ >>> 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 brakets 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
+:ref:`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.
--- /dev/null
+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
+----------------------------
+
+.. 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
+-------------------------
+
+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).
\ No newline at end of file
--- /dev/null
+========================================================
+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.
+
+
--- /dev/null
+==================================================
+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``.
+
+.. toctree::
+ :maxdepth: 1
+
+ quickstart
+ package_discovery
+ entry_point
+ dependency_management
+ datafiles
+ development_mode
+ distribution
+ extension
+ declarative_config
+ keywords
+ commands
--- /dev/null
+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 (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 `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.
+
+ 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 `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.
\ No newline at end of file
--- /dev/null
+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
+`Creating distutils Extensions`_ for more details, especially the subsection on
+`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 `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.
--- /dev/null
+.. _`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 :ref:`keywords reference <keywords_ref>`
+
+.. 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 :ref:`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:
+
+.. code-block:: ini
+
+ [options]
+ #...
+ packages =
+ mypkg1
+ mypkg2
+
+.. code-block:: python
+
+ setup(
+ #...
+ packages = ['mypkg1', 'mypkg2']
+ )
+
+This can get tiresome reallly quickly. To speed things up, we introduce two
+functions provided by setuptools:
+
+.. code-block:: ini
+
+ [options]
+ packages = find:
+ #or
+ packages = find_namespace:
+
+.. code-block:: python
+
+ from setuptools import find_packages
+ #or
+ from setuptools import find_namespace_packages
+
+
+Using ``find:`` or ``find_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
+
+.. code-block:: bash
+
+ mypkg/
+ src/
+ pkg1/__init__.py
+ pkg2/__init__.py
+ additional/__init__.py
+
+ setup.cfg #or setup.py
+
+To have your setup.cfg or setup.py to automatically include packages found
+in ``src`` that starts with the name ``pkg`` and not ``additional``:
+
+.. code-block:: ini
+
+ [options]
+ packages = find:
+ package_dir =
+ =src
+
+ [options.packages.find]
+ where = src
+ include = pkg*
+ exclude = additional
+
+.. code-block:: python
+
+ setup(
+ #...
+ packages = find_packages(
+ where = 'src',
+ include = ['pkg*',],
+ exclude = ['tests',]
+ ),
+ package_dir = {"":"src"}
+ #...
+ )
+
+
+Using ``find_namespace:`` or ``find_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 namespace
+packages are. Here is a quick recap:
+
+Suppose you have two packages named 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:: python
+
+ >>> 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. Suppose you are packaging the ``foo`` part:
+
+.. code-block:: bash
+
+ foo/
+ src/
+ timmins/foo/__init__.py
+ setup.cfg # or setup.py
+
+and you want the ``foo`` to be automatically included, ``find:`` won't work
+because timmins doesn't contain ``__init__.py`` directly, instead, you have
+to use ``find_namespace:``:
+
+.. code-block:: ini
+
+ [options]
+ package_dir =
+ =src
+ packages = find_namespace:
+
+ [options.packages.find_namespace]
+ where = src
+
+When you install the zipped distribution, ``timmins.foo`` would become
+available to your interpreter.
+
+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. As a result, this creates an interesting side effect. If you
+organize your package like this:
+
+.. code-block:: bash
+
+ foo/
+ timmins/
+ foo/__init__.py
+ setup.cfg # or setup.py
+ tests/
+ test_foo/__init__.py
+
+a naive ``find_namespace:`` would include tests as part of your package to
+be installed. A simple way to fix it is to adopt the aforementioned
+``src`` layout.
+
+
+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``:
+
+.. code-block:: ini
+
+ [options]
+ namespace_packages = timmins
+
+.. code-block:: python
+
+ setup(
+ # ...
+ namespace_packages = ['timmins']
+ )
+
+And your directory should look like this
+
+.. code-block:: bash
+
+ /foo/
+ src/
+ timmins/
+ __init__.py
+ foo/__init__.py
+ setup.cfg #or setup.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.
--- /dev/null
+==========================
+``setuptools`` Quickstart
+==========================
+
+.. contents::
+
+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. All 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 tools that provides a ``build sdist``-alike
+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 517 <https://www.python.org/dev/peps/pep-0517/#
+build-requirements>``. To learn more about Python packaging in general,
+navigate to the `bottom <Resources on python packaging>`_ 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", "wheel"]
+ build-backend = "setuptools.build_meta"
+
+Then, you will need a ``setup.cfg`` to specify your package information,
+such as metadata, contents, dependencies, etc. Here we demonstrate the minimum
+
+.. code-block:: ini
+
+ [metadata]
+ name = "mypackage"
+ version = 0.0.1
+
+ [options]
+ packages = "mypackage"
+ install_requires =
+ requests
+ importlib; python_version == "2.6"
+
+This is what your project would look like::
+
+ ~/mypackage/
+ pyproject.toml
+ setup.cfg
+ mypackage/__init__.py
+
+Then, you need an installer, such as `pep517 <https://pypi.org/project/pep517/>`_
+which you can obtain via ``pip install pep517``. After downloading it, invoke
+the installer::
+
+ python -m pep517.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 section,
+we will walk through those 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. ``setuptools``
+therefore provides two convenient tools to ease the burden: ``find: `` and
+``find_namespace: ``. To use it in your project:
+
+.. code-block:: ini
+
+ [options]
+ packages = find:
+
+ [options.packages.find] #optional
+ include=pkg1, pkg2
+ exclude=pk3, pk4
+
+When you pass the above information, alongside other necessary ones,
+``setuptools`` walks through the directory specified in ``where`` (omitted
+here as the package reside in current directory) and filters the packages
+it can find following the ``include`` (default to none), then remove
+those that match the ``exclude`` and return a list of Python packages. Note
+that each entry in the ``[options.packages.find]`` is optional. The above
+setup also allows you to adopt a ``src/`` layout. For more details and advanced
+use, go to :ref:`package_discovery`
+
+
+Entry points and automatic script creation
+===========================================
+Setuptools support automatic creation of scripts upon installation, that runs
+code within your package if you specify them with the ``entry_point`` keyword.
+This is what allows you to run commands like ``pip install`` instead of having
+to type ``python -m pip install``. To accomplish this, add the entry_points
+keyword in your ``setup.cfg``:
+
+.. code-block:: ini
+
+ [options]
+ entry_points =
+ [console_script]
+ main = mypkg:some_func
+
+When this project is installed, a ``main`` script will be installed and will
+invoke the ``some_func`` in the ``__init__.py`` file when called by the user.
+For detailed usage, including managing the additional or optional dependencies,
+go to :ref:`entry_point`.
+
+
+Dependency management
+=====================
+``setuptools`` supports automatically installing dependencies when a package is
+installed. The simplest way to include requirement specifiers is to use the
+``install_requires`` argument to ``setup.cfg``. It takes a string or list of
+strings containing requirement specifiers (A version specifier is one of the
+operators <, >, <=, >=, == or !=, followed by a version identifier):
+
+.. code-block:: ini
+
+ [options]
+ install_requires =
+ docutils >= 0.3
+ requests <= 0.4
+
+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 scenarios. ``setuptools`` also provide
+additional keywords such as ``setup_requires`` that allows you to install
+dependencies before running the script, and ``extras_requires`` that take
+care of those needed by automatically generated scripts. It also provides
+mechanisms to handle dependencies that are not in PyPI. For more advanced use,
+see :ref:`dependency_management`
+
+
+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 simpliest use, you
+can simply use the ``include_package_data`` keyword:
+
+.. code-block:: ini
+
+ [options]
+ 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.
+For more details, see :ref:`datafiles`
+
+
+Development mode
+================
+``setuptools`` allows you to install a package without copying any files
+to your interpretor 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. This is currently incompatible with
+PEP 517 and therefore it requires a ``setup.py`` script with the following
+content::
+
+ import setuptools
+ setuptools.setup()
+
+Then::
+
+ pip install --editable .
+
+This creates a link file in your interpretor site package directory which
+associate with your source code. For more information, see: (WIP)
+
+
+Uploading your package to PyPI
+==============================
+After generating the distribution files, next step would be to upload your
+distribution so others can use it. This functionality is provided by
+``twine <https://pypi.org/project/twine/>`` and we will only demonstrate the
+basic use here.
+
+
+Transitioning from ``setup.py`` to ``setup.cfg``
+==================================================
+To avoid executing arbitary 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. Here we provide a quick guide to understanding how ``setup.cfg`` is
+parsed by ``setuptool`` to ease the pain of transition.
+
+
+Resources on Python packaging
+=============================
+Packaging in Python is hard. Here we provide a list of links for those that
+want to learn more.
directory = "misc"
name = "Misc"
showcontent = true
+
+[tool.jaraco.pytest.plugins.flake8]
+addopts = "--flake8"
+
+[tool.jaraco.pytest.plugins.cov]
+addopts = "--cov"
[pytest]
-addopts=--doctest-modules --flake8 --doctest-glob=pkg_resources/api_tests.txt --cov -r sxX
-norecursedirs=dist build *.egg setuptools/extern pkg_resources/extern pkg_resources/tests/data tools .* setuptools/_vendor pkg_resources/_vendor
+addopts=--doctest-modules --doctest-glob=pkg_resources/api_tests.txt -r sxX
+norecursedirs=dist build .tox .eggs
doctest_optionflags=ELLIPSIS ALLOW_UNICODE
filterwarnings =
# Fail on warnings
ignore:bdist_wininst command is deprecated
# Suppress this error; unimportant for CI tests
ignore:Extraction path is writable by group/others:UserWarning
- # Suppress Python 2 deprecation warning
- ignore:Setuptools will stop working on Python 2:UserWarning
# Suppress weird RuntimeWarning.
ignore:Parent module 'setuptools' not found while handling absolute import:RuntimeWarning
# Suppress use of bytes for filenames on Windows until fixed #2016
ignore:The Windows bytes API has been deprecated:DeprecationWarning
- # Suppress other Python 2 UnicodeWarnings
- ignore:Unicode equal comparison failed to convert:UnicodeWarning
- ignore:Unicode unequal comparison failed to convert:UnicodeWarning
- # https://github.com/pypa/setuptools/issues/2025
- ignore:direct construction of .*Item has been deprecated:DeprecationWarning
# https://github.com/pypa/setuptools/issues/2081
ignore:lib2to3 package is deprecated:PendingDeprecationWarning
ignore:lib2to3 package is deprecated:DeprecationWarning
[metadata]
name = setuptools
-version = 50.3.0
+version = 50.3.1
description = Easily download, build, install, upgrade, and uninstall Python packages
author = Python Packaging Authority
author_email = distutils-sig@python.org
pytest>=3.7
wheel
coverage>=4.5.1
- pytest-cov>=2.5.1
+ # Coverage is unbearably slow on PyPy
+ pytest-cov>=2.5.1; python_implementation != "PyPy"
paver; python_version>="3.6"
pip>=19.1 # For proper file:// URLs support.
jaraco.envs
+ jaraco.test >= 3.1.1; python_version >= "3.6"
docs =
# Keep these in sync with docs/requirements.txt
try:
from setuptools.lib2to3_ex import Mixin2to3
-except ImportError:
+except Exception:
class Mixin2to3:
def run_2to3(self, files, doctests=True):
return safe_name(self.distribution.get_name())
def tagged_version(self):
- version = self.distribution.get_version()
- # egg_info may be called more than once for a distribution,
- # in which case the version string already contains all tags.
- if self.vtags and version.endswith(self.vtags):
- return safe_version(version)
- return safe_version(version + self.vtags)
+ return safe_version(self._maybe_tag(self.distribution.get_version()))
+
+ def _maybe_tag(self, version):
+ """
+ egg_info may be called more than once for a distribution,
+ in which case the version string already contains all tags.
+ """
+ return (
+ version if self.vtags and version.endswith(self.vtags)
+ else version + self.vtags
+ )
def tags(self):
version = ''
names.
"""
allowed = 'deprecation', 'breaking', 'change', 'doc', 'misc'
+ except_ = 'README.rst', '.gitignore'
assert all(
any(key in file.name for key in allowed)
for file in pathlib.Path('changelog.d').iterdir()
- if file.name != '.gitignore'
+ if file.name not in except_
)
--- /dev/null
+"""
+Except on bionic, Travis Linux base image for PPC64LE
+platform lacks the proper
+permissions to the directory ~/.cache/pip/wheels that allow
+the user running travis build to install pip packages.
+TODO: is someone tracking this issue? Maybe just move to bionic?
+"""
+
+import subprocess
+import collections
+import os
+
+
+def patch():
+ env = collections.defaultdict(str, os.environ)
+ if env['TRAVIS_CPU_ARCH'] != 'ppc64le':
+ return
+ cmd = [
+ 'sudo',
+ 'chown',
+ '-Rfv',
+ '{USER}:{GROUP}'.format_map(env),
+ os.path.expanduser('~/.cache/pip/wheels'),
+ ]
+ subprocess.Popen(cmd)
+
+
+__name__ == '__main__' and patch()
projects / platform / upstream / python-setuptools.git / commitdiff