Skip to content

S
setuptools
Commit 490301f4 authored by 谭九鼎's avatar 谭九鼎 Committed by GitHub
Browse files
Options

Merge branch 'master' into patch-2

parents bcb6d47f 0ce07159
Hide whitespace changes
Inline Side-by-side
Showing with 458 additions and 371 deletions
.bumpversion.cfg
View file @ 490301f4
[bumpversion] [bumpversion]
current_version = 50.3.0 current_version = 50.3.1
commit = True commit = True
tag = True tag = True
......
CHANGES.rst
View file @ 490301f4
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 v50.3.0
------- -------
...@@ -9,9 +22,9 @@ v50.2.0 ...@@ -9,9 +22,9 @@ v50.2.0
* #2355: When pip is imported as part of a build, leave distutils patched. * #2355: When pip is imported as part of a build, leave distutils patched.
* #2380: There are some setuptools specific changes in the * #2380: There are some setuptools specific changes in the
`setuptools.command.bdist_rpm` module that are no longer needed, because ``setuptools.command.bdist_rpm`` module that are no longer needed, because
they are part of the `bdist_rpm` module in distutils in Python they are part of the ``bdist_rpm`` module in distutils in Python
3.5.0. Therefore, code was removed from `setuptools.command.bdist_rpm`. 3.5.0. Therefore, code was removed from ``setuptools.command.bdist_rpm``.
v50.1.0 v50.1.0
...@@ -35,7 +48,7 @@ v50.0.2 ...@@ -35,7 +48,7 @@ v50.0.2
v50.0.1 v50.0.1
------- -------
* #2357: Restored Python 3.5 support in distutils.util for missing `subprocess._optim_args_from_interpreter_flags`. * #2357: Restored Python 3.5 support in distutils.util for missing ``subprocess._optim_args_from_interpreter_flags``.
* #2358: Restored AIX support on Python 3.8 and earlier. * #2358: Restored AIX support on Python 3.8 and earlier.
* #2361: Add Python 3.10 support to _distutils_hack. Get the 'Loader' abstract class * #2361: Add Python 3.10 support to _distutils_hack. Get the 'Loader' abstract class
from importlib.abc rather than importlib.util.abc (alias removed in Python from importlib.abc rather than importlib.util.abc (alias removed in Python
...@@ -482,7 +495,7 @@ v40.7.1 ...@@ -482,7 +495,7 @@ v40.7.1
v40.7.0 v40.7.0
------- -------
* #1551: File inputs for the `license` field in `setup.cfg` files now explicitly raise an error. * #1551: File inputs for the ``license`` field in ``setup.cfg`` files now explicitly raise an error.
* #1180: Add support for non-ASCII in setup.cfg (#1062). Add support for native strings on some parameters (#1136). * #1180: Add support for non-ASCII in setup.cfg (#1062). Add support for native strings on some parameters (#1136).
* #1499: ``setuptools.package_index`` no longer relies on the deprecated ``urllib.parse.splituser`` per Python #27485. * #1499: ``setuptools.package_index`` no longer relies on the deprecated ``urllib.parse.splituser`` per Python #27485.
* #1544: Added tests for PackageIndex.download (for git URLs). * #1544: Added tests for PackageIndex.download (for git URLs).
...@@ -532,7 +545,7 @@ v40.5.0 ...@@ -532,7 +545,7 @@ v40.5.0
* #1335: In ``pkg_resources.normalize_path``, fix issue on Cygwin when cwd contains symlinks. * #1335: In ``pkg_resources.normalize_path``, fix issue on Cygwin when cwd contains symlinks.
* #1502: Deprecated support for downloads from Subversion in package_index/easy_install. * #1502: Deprecated support for downloads from Subversion in package_index/easy_install.
* #1517: Dropped use of six.u in favor of `u""` literals. * #1517: Dropped use of six.u in favor of ``u""`` literals.
* #1520: Added support for ``data_files`` in ``setup.cfg``. * #1520: Added support for ``data_files`` in ``setup.cfg``.
* #1525: Fixed rendering of the deprecation warning in easy_install doc. * #1525: Fixed rendering of the deprecation warning in easy_install doc.
...@@ -581,7 +594,7 @@ v40.2.0 ...@@ -581,7 +594,7 @@ v40.2.0
v40.1.1 v40.1.1
-------- --------
* #1465: Fix regression with `egg_info` command when tagging is used. * #1465: Fix regression with ``egg_info`` command when tagging is used.
v40.1.0 v40.1.0
...@@ -618,8 +631,8 @@ v39.2.0 ...@@ -618,8 +631,8 @@ v39.2.0
a text file. a text file.
* #1360: Fixed issue with a mismatch between the name of the package and the * #1360: Fixed issue with a mismatch between the name of the package and the
name of the .dist-info file in wheel files name of the .dist-info file in wheel files
* #1364: Add `__dir__()` implementation to `pkg_resources.Distribution()` that * #1364: Add ``__dir__()`` implementation to ``pkg_resources.Distribution()`` that
includes the attributes in the `_provider` instance variable. includes the attributes in the ``_provider`` instance variable.
* #1365: Take the package_dir option into account when loading the version from * #1365: Take the package_dir option into account when loading the version from
a module attribute. a module attribute.
* #1353: Added coverage badge to README. * #1353: Added coverage badge to README.
...@@ -729,7 +742,7 @@ v38.2.5 ...@@ -729,7 +742,7 @@ v38.2.5
v38.2.4 v38.2.4
------- -------
* #1220: Fix `data_files` handling when installing from wheel. * #1220: Fix ``data_files`` handling when installing from wheel.
v38.2.3 v38.2.3
------- -------
...@@ -1493,7 +1506,7 @@ v25.4.0 ...@@ -1493,7 +1506,7 @@ v25.4.0
v25.3.0 v25.3.0
------- -------
* #739 Fix unquoted libpaths by fixing compatibility between `numpy.distutils` and `distutils._msvccompiler` for numpy < 1.11.2 (Fix issue #728, error also fixed in Numpy). * #739 Fix unquoted libpaths by fixing compatibility between ``numpy.distutils`` and ``distutils._msvccompiler`` for numpy < 1.11.2 (Fix issue #728, error also fixed in Numpy).
* #731: Bump certifi. * #731: Bump certifi.
...@@ -1510,13 +1523,13 @@ v25.2.0 ...@@ -1510,13 +1523,13 @@ v25.2.0
v25.1.6 v25.1.6
------- -------
* #725: revert `library_dir_option` patch (Error is related to `numpy.distutils` and make errors on non Numpy users). * #725: revert ``library_dir_option`` patch (Error is related to ``numpy.distutils`` and make errors on non Numpy users).
v25.1.5 v25.1.5
------- -------
* #720 * #720
* #723: Improve patch for `library_dir_option`. * #723: Improve patch for ``library_dir_option``.
v25.1.4 v25.1.4
------- -------
...@@ -1524,7 +1537,7 @@ v25.1.4 ...@@ -1524,7 +1537,7 @@ v25.1.4
* #717 * #717
* #713 * #713
* #707: Fix Python 2 compatibility for MSVC by catching errors properly. * #707: Fix Python 2 compatibility for MSVC by catching errors properly.
* #715: Fix unquoted libpaths by patching `library_dir_option`. * #715: Fix unquoted libpaths by patching ``library_dir_option``.
v25.1.3 v25.1.3
------- -------
...@@ -3052,10 +3065,10 @@ not all users will find 1.0 a drop-in replacement for 0.9. ...@@ -3052,10 +3065,10 @@ not all users will find 1.0 a drop-in replacement for 0.9.
* Issue #50: Normalized API of environment marker support. Specifically, * Issue #50: Normalized API of environment marker support. Specifically,
removed line number and filename from SyntaxErrors when returned from removed line number and filename from SyntaxErrors when returned from
`pkg_resources.invalid_marker`. Any clients depending on the specific ``pkg_resources.invalid_marker``. Any clients depending on the specific
string representation of exceptions returned by that function may need to string representation of exceptions returned by that function may need to
be updated to account for this change. be updated to account for this change.
* Issue #50: SyntaxErrors generated by `pkg_resources.invalid_marker` are * Issue #50: SyntaxErrors generated by ``pkg_resources.invalid_marker`` are
normalized for cross-implementation consistency. normalized for cross-implementation consistency.
* Removed ``--ignore-conflicts-at-my-risk`` and ``--delete-conflicting`` * Removed ``--ignore-conflicts-at-my-risk`` and ``--delete-conflicting``
options to easy_install. These options have been deprecated since 0.6a11. options to easy_install. These options have been deprecated since 0.6a11.
...@@ -3063,13 +3076,13 @@ not all users will find 1.0 a drop-in replacement for 0.9. ...@@ -3063,13 +3076,13 @@ not all users will find 1.0 a drop-in replacement for 0.9.
0.9.8 0.9.8
----- -----
* Issue #53: Fix NameErrors in `_vcs_split_rev_from_url`. * Issue #53: Fix NameErrors in ``_vcs_split_rev_from_url``.
0.9.7 0.9.7
----- -----
* Issue #49: Correct AttributeError on PyPy where a hashlib.HASH object does * Issue #49: Correct AttributeError on PyPy where a hashlib.HASH object does
not have a `.name` attribute. not have a ``.name`` attribute.
* Issue #34: Documentation now refers to bootstrap script in code repository * Issue #34: Documentation now refers to bootstrap script in code repository
referenced by bookmark. referenced by bookmark.
* Add underscore-separated keys to environment markers (markerlib). * Add underscore-separated keys to environment markers (markerlib).
...@@ -3077,7 +3090,7 @@ not all users will find 1.0 a drop-in replacement for 0.9. ...@@ -3077,7 +3090,7 @@ not all users will find 1.0 a drop-in replacement for 0.9.
0.9.6 0.9.6
----- -----
* Issue #44: Test failure on Python 2.4 when MD5 hash doesn't have a `.name` * Issue #44: Test failure on Python 2.4 when MD5 hash doesn't have a ``.name``
attribute. attribute.
0.9.5 0.9.5
...@@ -3111,7 +3124,7 @@ not all users will find 1.0 a drop-in replacement for 0.9. ...@@ -3111,7 +3124,7 @@ not all users will find 1.0 a drop-in replacement for 0.9.
0.9 0.9
--- ---
* `package_index` now validates hashes other than MD5 in download links. * ``package_index`` now validates hashes other than MD5 in download links.
0.8 0.8
--- ---
...@@ -3158,7 +3171,7 @@ not all users will find 1.0 a drop-in replacement for 0.9. ...@@ -3158,7 +3171,7 @@ not all users will find 1.0 a drop-in replacement for 0.9.
0.7.2 0.7.2
----- -----
* Issue #14: Use markerlib when the `parser` module is not available. * Issue #14: Use markerlib when the ``parser`` module is not available.
* Issue #10: ``ez_setup.py`` now uses HTTPS to download setuptools from PyPI. * Issue #10: ``ez_setup.py`` now uses HTTPS to download setuptools from PyPI.
0.7.1 0.7.1
...@@ -3242,7 +3255,7 @@ Added several features that were slated for setuptools 0.6c12: ...@@ -3242,7 +3255,7 @@ Added several features that were slated for setuptools 0.6c12:
------ ------
* Distribute #27: Use public api for loading resources from zip files rather than * Distribute #27: Use public api for loading resources from zip files rather than
the private method `_zip_directory_cache`. the private method ``_zip_directory_cache``.
* Added a new function ``easy_install.get_win_launcher`` which may be used by * Added a new function ``easy_install.get_win_launcher`` which may be used by
third-party libraries such as buildout to get a suitable script launcher. third-party libraries such as buildout to get a suitable script launcher.
...@@ -3308,7 +3321,7 @@ how it parses version numbers. ...@@ -3308,7 +3321,7 @@ how it parses version numbers.
* Fix 2 errors with Jython 2.5. * Fix 2 errors with Jython 2.5.
* Fix 1 failure with Jython 2.5 and 2.7. * Fix 1 failure with Jython 2.5 and 2.7.
* Disable workaround for Jython scripts on Linux systems. * Disable workaround for Jython scripts on Linux systems.
* Distribute #336: `setup.py` no longer masks failure exit code when tests fail. * Distribute #336: ``setup.py`` no longer masks failure exit code when tests fail.
* Fix issue in pkg_resources where try/except around a platform-dependent * Fix issue in pkg_resources where try/except around a platform-dependent
import would trigger hook load failures on Mercurial. See pull request 32 import would trigger hook load failures on Mercurial. See pull request 32
for details. for details.
...@@ -3319,7 +3332,7 @@ how it parses version numbers. ...@@ -3319,7 +3332,7 @@ how it parses version numbers.
* Fix test suite with Python 2.6. * Fix test suite with Python 2.6.
* Fix some DeprecationWarnings and ResourceWarnings. * Fix some DeprecationWarnings and ResourceWarnings.
* Distribute #335: Backed out `setup_requires` superceding installed requirements * Distribute #335: Backed out ``setup_requires`` superceding installed requirements
until regression can be addressed. until regression can be addressed.
0.6.31 0.6.31
...@@ -3329,7 +3342,7 @@ how it parses version numbers. ...@@ -3329,7 +3342,7 @@ how it parses version numbers.
* Distribute #329: Properly close files created by tests for compatibility with * Distribute #329: Properly close files created by tests for compatibility with
Jython. Jython.
* Work around Jython #1980 and Jython #1981. * Work around Jython #1980 and Jython #1981.
* Distribute #334: Provide workaround for packages that reference `sys.__stdout__` * Distribute #334: Provide workaround for packages that reference ``sys.__stdout__``
such as numpy does. This change should address such as numpy does. This change should address
`virtualenv #359 <https://github.com/pypa/virtualenv/issues/359>`_ as long `virtualenv #359 <https://github.com/pypa/virtualenv/issues/359>`_ as long
as the system encoding is UTF-8 or the IO encoding is specified in the as the system encoding is UTF-8 or the IO encoding is specified in the
...@@ -3338,7 +3351,7 @@ how it parses version numbers. ...@@ -3338,7 +3351,7 @@ how it parses version numbers.
PYTHONIOENCODING=utf8 pip install numpy PYTHONIOENCODING=utf8 pip install numpy
* Fix for encoding issue when installing from Windows executable on Python 3. * Fix for encoding issue when installing from Windows executable on Python 3.
* Distribute #323: Allow `setup_requires` requirements to supercede installed * Distribute #323: Allow ``setup_requires`` requirements to supercede installed
requirements. Added some new keyword arguments to existing pkg_resources requirements. Added some new keyword arguments to existing pkg_resources
methods. Also had to updated how __path__ is handled for namespace packages methods. Also had to updated how __path__ is handled for namespace packages
to ensure that when a new egg distribution containing a namespace package is to ensure that when a new egg distribution containing a namespace package is
...@@ -3358,16 +3371,16 @@ how it parses version numbers. ...@@ -3358,16 +3371,16 @@ how it parses version numbers.
* BB Pull Request #14: Honor file permissions in zip files. * BB Pull Request #14: Honor file permissions in zip files.
* Distribute #327: Merged pull request #24 to fix a dependency problem with pip. * Distribute #327: Merged pull request #24 to fix a dependency problem with pip.
* Merged pull request #23 to fix https://github.com/pypa/virtualenv/issues/301. * Merged pull request #23 to fix https://github.com/pypa/virtualenv/issues/301.
* If Sphinx is installed, the `upload_docs` command now runs `build_sphinx` * If Sphinx is installed, the ``upload_docs`` command now runs ``build_sphinx``
to produce uploadable documentation. to produce uploadable documentation.
* Distribute #326: `upload_docs` provided mangled auth credentials under Python 3. * Distribute #326: ``upload_docs`` provided mangled auth credentials under Python 3.
* Distribute #320: Fix check for "createable" in distribute_setup.py. * Distribute #320: Fix check for "createable" in distribute_setup.py.
* Distribute #305: Remove a warning that was triggered during normal operations. * Distribute #305: Remove a warning that was triggered during normal operations.
* Distribute #311: Print metadata in UTF-8 independent of platform. * Distribute #311: Print metadata in UTF-8 independent of platform.
* Distribute #303: Read manifest file with UTF-8 encoding under Python 3. * Distribute #303: Read manifest file with UTF-8 encoding under Python 3.
* Distribute #301: Allow to run tests of namespace packages when using 2to3. * Distribute #301: Allow to run tests of namespace packages when using 2to3.
* Distribute #304: Prevent import loop in site.py under Python 3.3. * Distribute #304: Prevent import loop in site.py under Python 3.3.
* Distribute #283: Reenable scanning of `*.pyc` / `*.pyo` files on Python 3.3. * Distribute #283: Reenable scanning of ``*.pyc`` / ``*.pyo`` files on Python 3.3.
* Distribute #299: The develop command didn't work on Python 3, when using 2to3, * Distribute #299: The develop command didn't work on Python 3, when using 2to3,
as the egg link would go to the Python 2 source. Linking to the 2to3'd code as the egg link would go to the Python 2 source. Linking to the 2to3'd code
in build/lib makes it work, although you will have to rebuild the module in build/lib makes it work, although you will have to rebuild the module
...@@ -3377,10 +3390,10 @@ how it parses version numbers. ...@@ -3377,10 +3390,10 @@ how it parses version numbers.
* Distribute #313: Support for sdist subcommands (Python 2.7) * Distribute #313: Support for sdist subcommands (Python 2.7)
* Distribute #314: test_local_index() would fail an OS X. * Distribute #314: test_local_index() would fail an OS X.
* Distribute #310: Non-ascii characters in a namespace __init__.py causes errors. * Distribute #310: Non-ascii characters in a namespace __init__.py causes errors.
* Distribute #218: Improved documentation on behavior of `package_data` and * Distribute #218: Improved documentation on behavior of ``package_data`` and
`include_package_data`. Files indicated by `package_data` are now included ``include_package_data``. Files indicated by ``package_data`` are now included
in the manifest. in the manifest.
* `distribute_setup.py` now allows a `--download-base` argument for retrieving * ``distribute_setup.py`` now allows a ``--download-base`` argument for retrieving
distribute from a specified location. distribute from a specified location.
0.6.28 0.6.28
...@@ -3389,7 +3402,7 @@ how it parses version numbers. ...@@ -3389,7 +3402,7 @@ how it parses version numbers.
* Distribute #294: setup.py can now be invoked from any directory. * Distribute #294: setup.py can now be invoked from any directory.
* Scripts are now installed honoring the umask. * Scripts are now installed honoring the umask.
* Added support for .dist-info directories. * Added support for .dist-info directories.
* Distribute #283: Fix and disable scanning of `*.pyc` / `*.pyo` files on * Distribute #283: Fix and disable scanning of ``*.pyc`` / ``*.pyo`` files on
Python 3.3. Python 3.3.
0.6.27 0.6.27
...@@ -3623,7 +3636,7 @@ how it parses version numbers. ...@@ -3623,7 +3636,7 @@ how it parses version numbers.
0.6.4 0.6.4
----- -----
* Added the generation of `distribute_setup_3k.py` during the release. * Added the generation of ``distribute_setup_3k.py`` during the release.
This closes Distribute #52. This closes Distribute #52.
* Added an upload_docs command to easily upload project documentation to * Added an upload_docs command to easily upload project documentation to
......
changelog.d/2097.doc.rst deleted 100644 → 0
View file @ bcb6d47f
doc: simplify index and group deprecated files
changelog.d/2102.doc.rst deleted 100644 → 0
View file @ bcb6d47f
doc overhaul step 2: break main doc into multiple sections
\ No newline at end of file
changelog.d/2111.doc.rst deleted 100644 → 0
View file @ bcb6d47f
doc overhaul step 3: update userguide
changelog.d/2379.misc.rst deleted 100644 → 0
View file @ bcb6d47f
Travis CI test suite now tests against PPC64.
changelog.d/2427.doc.rst 0 → 100644
View file @ 490301f4
Started enforcing strict syntax and reference validation
in the Sphinx docs -- by :user:`webknjaz`
changelog.d/2428.doc.rst 0 → 100644
View file @ 490301f4
Removed redundant Sphinx ``Makefile`` support -- by :user:`webknjaz`
changelog.d/README.rst 0 → 100644
View file @ 490301f4
.. _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
conftest.py
View file @ 490301f4
...@@ -25,4 +25,5 @@ collect_ignore = [ ...@@ -25,4 +25,5 @@ collect_ignore = [
if sys.version_info < (3, 6): if sys.version_info < (3, 6):
collect_ignore.append('docs/conf.py') # uses f-strings
collect_ignore.append('pavement.py') collect_ignore.append('pavement.py')
docs/Makefile deleted 100644 → 0
View file @ bcb6d47f
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview over all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
clean:
-rm -rf build/*
html:
mkdir -p build/html build/doctrees
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
@echo
@echo "Build finished. The HTML pages are in build/html."
pickle:
mkdir -p build/pickle build/doctrees
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
@echo
@echo "Build finished; now you can process the pickle files."
web: pickle
json:
mkdir -p build/json build/doctrees
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
mkdir -p build/htmlhelp build/doctrees
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in build/htmlhelp."
latex:
mkdir -p build/latex build/doctrees
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
@echo
@echo "Build finished; the LaTeX files are in build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
mkdir -p build/changes build/doctrees
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
@echo
@echo "The overview file is in build/changes."
linkcheck:
mkdir -p build/linkcheck build/doctrees
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in build/linkcheck/output.txt."
docs/build_meta.rst
View file @ 490301f4
...@@ -56,7 +56,8 @@ setuptools, the content would be:: ...@@ -56,7 +56,8 @@ setuptools, the content would be::
requires = ["setuptools", "wheel"] requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta" build-backend = "setuptools.build_meta"
Use ``setuptools``' `declarative config`_ to specify the package information:: Use ``setuptools``' :ref:`declarative config <declarative config>` to
specify the package information::
[metadata] [metadata]
name = meowpkg name = meowpkg
......
docs/conf.py
View file @ 490301f4
...@@ -10,9 +10,18 @@ import os ...@@ -10,9 +10,18 @@ import os
cwd=os.path.join(os.path.dirname(__file__), os.path.pardir), 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 -- # -- 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. # Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates'] templates_path = ['_templates']
...@@ -27,6 +36,11 @@ exclude_trees = [] ...@@ -27,6 +36,11 @@ exclude_trees = []
# The name of the Pygments (syntax highlighting) style to use. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx' pygments_style = 'sphinx'
# -- Options for extlinks extension ---------------------------------------
extlinks = {
'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
}
# -- Options for HTML output -- # -- Options for HTML output --
# The theme to use for HTML and HTML Help pages. Major themes that come with # The theme to use for HTML and HTML Help pages. Major themes that come with
...@@ -132,3 +146,12 @@ link_files = { ...@@ -132,3 +146,12 @@ link_files = {
], ],
), ),
} }
# Be strict about any broken references:
nitpicky = True
# Ref: https://github.com/python-attrs/attrs/pull/571/files\
# #diff-85987f48f1258d9ee486e3191495582dR82
default_role = 'any'
docs/deprecated/index.rst
View file @ 490301f4
...@@ -17,3 +17,4 @@ objectives. ...@@ -17,3 +17,4 @@ objectives.
python_eggs python_eggs
easy_install easy_install
distutils-legacy distutils-legacy
functionalities
docs/developer-guide.rst
View file @ 490301f4
...@@ -61,33 +61,14 @@ jump to the in-depth discussion about any subject referenced. ...@@ -61,33 +61,14 @@ jump to the in-depth discussion about any subject referenced.
Making a pull request Making a pull request
--------------------- ---------------------
When making a pull request, please include a short summary of the changes When making a pull request, please
and a reference to any issue tickets that the PR is intended to solve. :ref:`include a short summary of the changes <Adding change notes
All PRs with code changes should include tests. All changes should include a with your PRs>` and a reference to any issue tickets that the PR is
changelog entry. intended to solve.
All PRs with code changes should include tests. All changes should
``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_ include a changelog entry.
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 .. include:: ../changelog.d/README.rst
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 Auto-Merge Requests
......
docs/development.rst
View file @ 490301f4
...@@ -31,5 +31,4 @@ setuptools changes. You have been warned. ...@@ -31,5 +31,4 @@ setuptools changes. You have been warned.
:maxdepth: 1 :maxdepth: 1
developer-guide developer-guide
formats
releases releases
docs/index.rst
View file @ 490301f4
...@@ -10,5 +10,11 @@ Documentation content: ...@@ -10,5 +10,11 @@ Documentation content:
:maxdepth: 1 :maxdepth: 1
User guide <userguide/index> User guide <userguide/index>
build_meta
pkg_resources
references/keywords
roadmap
setuptools
Development guide <development> Development guide <development>
Backward compatibility & deprecated practice <deprecated/index> Backward compatibility & deprecated practice <deprecated/index>
Changelog <history>
docs/pkg_resources.rst
View file @ 490301f4
...@@ -149,7 +149,7 @@ more information on this.) Also, you must add a ``declare_namespace()`` call ...@@ -149,7 +149,7 @@ more information on this.) Also, you must add a ``declare_namespace()`` call
in the package's ``__init__.py`` file(s): in the package's ``__init__.py`` file(s):
``declare_namespace(name)`` ``declare_namespace(name)``
Declare that the dotted package name `name` is a "namespace package" whose Declare that the dotted package name ``name`` is a "namespace package" whose
contained packages and modules may be spread across multiple distributions. contained packages and modules may be spread across multiple distributions.
The named package's ``__path__`` will be extended to include the The named package's ``__path__`` will be extended to include the
corresponding package in all distributions on ``sys.path`` that contain a corresponding package in all distributions on ``sys.path`` that contain a
...@@ -163,7 +163,7 @@ Applications that manipulate namespace packages or directly alter ``sys.path`` ...@@ -163,7 +163,7 @@ Applications that manipulate namespace packages or directly alter ``sys.path``
at runtime may also need to use this API function: at runtime may also need to use this API function:
``fixup_namespace_packages(path_item)`` ``fixup_namespace_packages(path_item)``
Declare that `path_item` is a newly added item on ``sys.path`` that may Declare that ``path_item`` is a newly added item on ``sys.path`` that may
need to be used to update existing namespace packages. Ordinarily, this is 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 called for you when an egg is automatically added to ``sys.path``, but if
your application modifies ``sys.path`` to include locations that may your application modifies ``sys.path`` to include locations that may
...@@ -197,7 +197,7 @@ not provide any way to detect arbitrary changes to a list object like ...@@ -197,7 +197,7 @@ not provide any way to detect arbitrary changes to a list object like
``working_set`` based on changes to ``sys.path``. ``working_set`` based on changes to ``sys.path``.
``WorkingSet(entries=None)`` ``WorkingSet(entries=None)``
Create a ``WorkingSet`` from an iterable of path entries. If `entries` Create a ``WorkingSet`` from an iterable of path entries. If ``entries``
is not supplied, it defaults to the value of ``sys.path`` at the time is not supplied, it defaults to the value of ``sys.path`` at the time
the constructor is called. the constructor is called.
...@@ -229,9 +229,9 @@ abbreviation for ``pkg_resources.working_set.require()``: ...@@ -229,9 +229,9 @@ abbreviation for ``pkg_resources.working_set.require()``:
``require(*requirements)`` ``require(*requirements)``
Ensure that distributions matching `requirements` are activated Ensure that distributions matching ``requirements`` are activated
`requirements` must be a string or a (possibly-nested) sequence ``requirements`` must be a string or a (possibly-nested) sequence
thereof, specifying the distributions and versions required. The thereof, specifying the distributions and versions required. The
return value is a sequence of the distributions that needed to be return value is a sequence of the distributions that needed to be
activated to fulfill the requirements; all relevant distributions are activated to fulfill the requirements; all relevant distributions are
...@@ -259,8 +259,8 @@ abbreviation for ``pkg_resources.working_set.require()``: ...@@ -259,8 +259,8 @@ abbreviation for ``pkg_resources.working_set.require()``:
``obtain()`` method of ``Environment`` objects. ``obtain()`` method of ``Environment`` objects.
``run_script(requires, script_name)`` ``run_script(requires, script_name)``
Locate distribution specified by `requires` and run its `script_name` Locate distribution specified by ``requires`` and run its ``script_name``
script. `requires` must be a string containing a requirement specifier. script. ``requires`` must be a string containing a requirement specifier.
(See `Requirements Parsing`_ below for the syntax.) (See `Requirements Parsing`_ below for the syntax.)
The script, if found, will be executed in *the caller's globals*. That's The script, if found, will be executed in *the caller's globals*. That's
...@@ -274,11 +274,11 @@ abbreviation for ``pkg_resources.working_set.require()``: ...@@ -274,11 +274,11 @@ abbreviation for ``pkg_resources.working_set.require()``:
object's `Metadata API`_ instead. object's `Metadata API`_ instead.
``iter_entry_points(group, name=None)`` ``iter_entry_points(group, name=None)``
Yield entry point objects from `group` matching `name` Yield entry point objects from ``group`` matching ``name``
If `name` is None, yields all entry points in `group` from all If ``name`` is None, yields all entry points in ``group`` from all
distributions in the working set, otherwise only ones matching both distributions in the working set, otherwise only ones matching both
`group` and `name` are yielded. Entry points are yielded from the active ``group`` and ``name`` are yielded. Entry points are yielded from the active
distributions in the order that the distributions appear in the working 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 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 that they are listed in ``sys.path``.) Note that within the entry points
...@@ -301,14 +301,14 @@ instance: ...@@ -301,14 +301,14 @@ instance:
called by the ``WorkingSet()`` constructor during initialization. called by the ``WorkingSet()`` constructor during initialization.
This method uses ``find_distributions(entry,True)`` to find distributions This method uses ``find_distributions(entry,True)`` to find distributions
corresponding to the path entry, and then ``add()`` them. `entry` is corresponding to the path entry, and then ``add()`` them. ``entry`` is
always appended to the ``entries`` attribute, even if it is already always appended to the ``entries`` attribute, even if it is already
present, however. (This is because ``sys.path`` can contain the same value present, however. (This is because ``sys.path`` can contain the same value
more than once, and the ``entries`` attribute should be able to reflect more than once, and the ``entries`` attribute should be able to reflect
this.) this.)
``__contains__(dist)`` ``__contains__(dist)``
True if `dist` is active in this ``WorkingSet``. Note that only one True if ``dist`` is active in this ``WorkingSet``. Note that only one
distribution for a given project can be active in a given ``WorkingSet``. distribution for a given project can be active in a given ``WorkingSet``.
``__iter__()`` ``__iter__()``
...@@ -317,34 +317,34 @@ instance: ...@@ -317,34 +317,34 @@ instance:
added to the working set. added to the working set.
``find(req)`` ``find(req)``
Find a distribution matching `req` (a ``Requirement`` instance). Find a distribution matching ``req`` (a ``Requirement`` instance).
If there is an active distribution for the requested project, this If there is an active distribution for the requested project, this
returns it, as long as it meets the version requirement specified by 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 ``req``. But, if there is an active distribution for the project and it
does *not* meet the `req` requirement, ``VersionConflict`` is raised. does *not* meet the ``req`` requirement, ``VersionConflict`` is raised.
If there is no active distribution for the requested project, ``None`` If there is no active distribution for the requested project, ``None``
is returned. is returned.
``resolve(requirements, env=None, installer=None)`` ``resolve(requirements, env=None, installer=None)``
List all distributions needed to (recursively) meet `requirements` List all distributions needed to (recursively) meet ``requirements``
`requirements` must be a sequence of ``Requirement`` objects. `env`, ``requirements`` must be a sequence of ``Requirement`` objects. ``env``,
if supplied, should be an ``Environment`` instance. If if supplied, should be an ``Environment`` instance. If
not supplied, an ``Environment`` is created from the working set's not supplied, an ``Environment`` is created from the working set's
``entries``. `installer`, if supplied, will be invoked with each ``entries``. ``installer``, if supplied, will be invoked with each
requirement that cannot be met by an already-installed distribution; it requirement that cannot be met by an already-installed distribution; it
should return a ``Distribution`` or ``None``. (See the ``obtain()`` method should return a ``Distribution`` or ``None``. (See the ``obtain()`` method
of `Environment Objects`_, below, for more information on the `installer` of `Environment Objects`_, below, for more information on the ``installer``
argument.) argument.)
``add(dist, entry=None)`` ``add(dist, entry=None)``
Add `dist` to working set, associated with `entry` Add ``dist`` to working set, associated with ``entry``
If `entry` is unspecified, it defaults to ``dist.location``. On exit from 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`` this routine, ``entry`` is added to the end of the working set's ``.entries``
(if it wasn't already present). (if it wasn't already present).
`dist` is only added to the working set if it's for a project that ``dist`` is only added to the working set if it's for a project that
doesn't already have a distribution active in the set. If it's doesn't already have a distribution active in the set. If it's
successfully added, any callbacks registered with the ``subscribe()`` successfully added, any callbacks registered with the ``subscribe()``
method will be called. (See `Receiving Change Notifications`_, below.) method will be called. (See `Receiving Change Notifications`_, below.)
...@@ -401,7 +401,7 @@ environment for the newest version of each project that can be safely loaded ...@@ -401,7 +401,7 @@ environment for the newest version of each project that can be safely loaded
without conflicts or missing requirements. without conflicts or missing requirements.
``find_plugins(plugin_env, full_env=None, fallback=True)`` ``find_plugins(plugin_env, full_env=None, fallback=True)``
Scan `plugin_env` and identify which distributions could be added to this Scan ``plugin_env`` and identify which distributions could be added to this
working set without version conflicts or missing requirements. working set without version conflicts or missing requirements.
Example usage:: Example usage::
...@@ -412,19 +412,19 @@ without conflicts or missing requirements. ...@@ -412,19 +412,19 @@ without conflicts or missing requirements.
map(working_set.add, distributions) # add plugins+libs to sys.path map(working_set.add, distributions) # add plugins+libs to sys.path
print "Couldn't load", errors # display errors print "Couldn't load", errors # display errors
The `plugin_env` should be an ``Environment`` instance that contains only The ``plugin_env`` should be an ``Environment`` instance that contains only
distributions that are in the project's "plugin directory" or directories. distributions that are in the project's "plugin directory" or directories.
The `full_env`, if supplied, should be an ``Environment`` instance that The ``full_env``, if supplied, should be an ``Environment`` instance that
contains all currently-available distributions. contains all currently-available distributions.
If `full_env` is not supplied, one is created automatically from the If ``full_env`` is not supplied, one is created automatically from the
``WorkingSet`` this method is called on, which will typically mean that ``WorkingSet`` this method is called on, which will typically mean that
every directory on ``sys.path`` will be scanned for distributions. every directory on ``sys.path`` will be scanned for distributions.
This method returns a 2-tuple: (`distributions`, `error_info`), where This method returns a 2-tuple: (``distributions``, ``error_info``), where
`distributions` is a list of the distributions found in `plugin_env` that ``distributions`` is a list of the distributions found in ``plugin_env`` that
were loadable, along with any other distributions that are needed to resolve were loadable, along with any other distributions that are needed to resolve
their dependencies. `error_info` is a dictionary mapping unloadable plugin their dependencies. ``error_info`` is a dictionary mapping unloadable plugin
distributions to an exception instance describing the error that occurred. distributions to an exception instance describing the error that occurred.
Usually this will be a ``DistributionNotFound`` or ``VersionConflict`` Usually this will be a ``DistributionNotFound`` or ``VersionConflict``
instance. instance.
...@@ -436,7 +436,7 @@ without conflicts or missing requirements. ...@@ -436,7 +436,7 @@ without conflicts or missing requirements.
metadata tracking and hooks to be activated. metadata tracking and hooks to be activated.
The resolution algorithm used by ``find_plugins()`` is as follows. First, The resolution algorithm used by ``find_plugins()`` is as follows. First,
the project names of the distributions present in `plugin_env` are sorted. the project names of the distributions present in ``plugin_env`` are sorted.
Then, each project's eggs are tried in descending version order (i.e., Then, each project's eggs are tried in descending version order (i.e.,
newest version first). newest version first).
...@@ -446,7 +446,7 @@ without conflicts or missing requirements. ...@@ -446,7 +446,7 @@ without conflicts or missing requirements.
the next project name, and no older eggs for that project are tried. 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 If the resolution attempt fails, however, the error is added to the error
dictionary. If the `fallback` flag is true, the next older version of the dictionary. If the ``fallback`` flag is true, the next older version of the
plugin is tried, until a working version is found. If false, the resolution plugin is tried, until a working version is found. If false, the resolution
process continues with the next plugin project name. process continues with the next plugin project name.
...@@ -455,7 +455,7 @@ without conflicts or missing requirements. ...@@ -455,7 +455,7 @@ without conflicts or missing requirements.
may not be able to safely downgrade a version of a package. Others may want 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 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 revert to a known-good configuration. (That is, they may wish to revert to
a known configuration if the `error_info` return value is non-empty.) a known configuration if the ``error_info`` return value is non-empty.)
Note that this algorithm gives precedence to satisfying the dependencies of Note that this algorithm gives precedence to satisfying the dependencies of
alphabetically prior project names in case of version conflicts. If two alphabetically prior project names in case of version conflicts. If two
...@@ -473,22 +473,22 @@ that are present and potentially importable on the current platform. ...@@ -473,22 +473,22 @@ that are present and potentially importable on the current platform.
distributions during dependency resolution. distributions during dependency resolution.
``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)`` ``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)``
Create an environment snapshot by scanning `search_path` for distributions Create an environment snapshot by scanning ``search_path`` for distributions
compatible with `platform` and `python`. `search_path` should be a compatible with ``platform`` and ``python``. ``search_path`` should be a
sequence of strings such as might be used on ``sys.path``. If a sequence of strings such as might be used on ``sys.path``. If a
`search_path` isn't supplied, ``sys.path`` is used. ``search_path`` isn't supplied, ``sys.path`` is used.
`platform` is an optional string specifying the name of the platform ``platform`` is an optional string specifying the name of the platform
that platform-specific distributions must be compatible with. If that platform-specific distributions must be compatible with. If
unspecified, it defaults to the current platform. `python` is an unspecified, it defaults to the current platform. ``python`` is an
optional string naming the desired version of Python (e.g. ``'2.4'``); optional string naming the desired version of Python (e.g. ``'2.4'``);
it defaults to the currently-running version. it defaults to the currently-running version.
You may explicitly set `platform` (and/or `python`) to ``None`` if you You may explicitly set ``platform`` (and/or ``python``) to ``None`` if you
wish to include *all* distributions, not just those compatible with the wish to include *all* distributions, not just those compatible with the
running platform or Python version. running platform or Python version.
Note that `search_path` is scanned immediately for distributions, and the Note that ``search_path`` is scanned immediately for distributions, and the
resulting ``Environment`` is a snapshot of the found distributions. It resulting ``Environment`` is a snapshot of the found distributions. It
is not automatically updated if the system's state changes due to e.g. is not automatically updated if the system's state changes due to e.g.
installation or removal of distributions. installation or removal of distributions.
...@@ -504,15 +504,15 @@ distributions during dependency resolution. ...@@ -504,15 +504,15 @@ distributions during dependency resolution.
The yielded names are always in lower case. The yielded names are always in lower case.
``add(dist)`` ``add(dist)``
Add `dist` to the environment if it matches the platform and python version Add ``dist`` to the environment if it matches the platform and python version
specified at creation time, and only if the distribution hasn't already 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.) been added. (i.e., adding the same distribution more than once is a no-op.)
``remove(dist)`` ``remove(dist)``
Remove `dist` from the environment. Remove ``dist`` from the environment.
``can_add(dist)`` ``can_add(dist)``
Is distribution `dist` acceptable for this environment? If it's not Is distribution ``dist`` acceptable for this environment? If it's not
compatible with the ``platform`` and ``python`` version values specified compatible with the ``platform`` and ``python`` version values specified
when the environment was created, a false value is returned. when the environment was created, a false value is returned.
...@@ -534,34 +534,34 @@ distributions during dependency resolution. ...@@ -534,34 +534,34 @@ distributions during dependency resolution.
are silently ignored. are silently ignored.
``best_match(req, working_set, installer=None)`` ``best_match(req, working_set, installer=None)``
Find distribution best matching `req` and usable on `working_set` Find distribution best matching ``req`` and usable on ``working_set``
This calls the ``find(req)`` method of the `working_set` to see if a This calls the ``find(req)`` method of the ``working_set`` to see if a
suitable distribution is already active. (This may raise suitable distribution is already active. (This may raise
``VersionConflict`` if an unsuitable version of the project is already ``VersionConflict`` if an unsuitable version of the project is already
active in the specified `working_set`.) If a suitable distribution isn't active in the specified ``working_set``.) If a suitable distribution isn't
active, this method returns the newest distribution in the environment active, this method returns the newest distribution in the environment
that meets the ``Requirement`` in `req`. If no suitable distribution is that meets the ``Requirement`` in ``req``. If no suitable distribution is
found, and `installer` is supplied, then the result of calling found, and ``installer`` is supplied, then the result of calling
the environment's ``obtain(req, installer)`` method will be returned. the environment's ``obtain(req, installer)`` method will be returned.
``obtain(requirement, installer=None)`` ``obtain(requirement, installer=None)``
Obtain a distro that matches requirement (e.g. via download). In the Obtain a distro that matches requirement (e.g. via download). In the
base ``Environment`` class, this routine just returns base ``Environment`` class, this routine just returns
``installer(requirement)``, unless `installer` is None, in which case ``installer(requirement)``, unless ``installer`` is None, in which case
None is returned instead. This method is a hook that allows subclasses None is returned instead. This method is a hook that allows subclasses
to attempt other ways of obtaining a distribution before falling back to attempt other ways of obtaining a distribution before falling back
to the `installer` argument. to the ``installer`` argument.
``scan(search_path=None)`` ``scan(search_path=None)``
Scan `search_path` for distributions usable on `platform` Scan ``search_path`` for distributions usable on ``platform``
Any distributions found are added to the environment. `search_path` should Any distributions found are added to the environment. ``search_path`` should
be a sequence of strings such as might be used on ``sys.path``. If not be a sequence of strings such as might be used on ``sys.path``. If not
supplied, ``sys.path`` is used. Only distributions conforming to supplied, ``sys.path`` is used. Only distributions conforming to
the platform/python version defined at initialization are added. This the platform/python version defined at initialization are added. This
method is a shortcut for using the ``find_distributions()`` function to method is a shortcut for using the ``find_distributions()`` function to
find the distributions from each item in `search_path`, and then calling find the distributions from each item in ``search_path``, and then calling
``add()`` to add each one to the environment. ``add()`` to add each one to the environment.
...@@ -627,10 +627,10 @@ Requirements Parsing ...@@ -627,10 +627,10 @@ Requirements Parsing
-------------------------------------- --------------------------------------
``__contains__(dist_or_version)`` ``__contains__(dist_or_version)``
Return true if `dist_or_version` fits the criteria for this requirement. Return true if ``dist_or_version`` fits the criteria for this requirement.
If `dist_or_version` is a ``Distribution`` object, its project name must If ``dist_or_version`` is a ``Distribution`` object, its project name must
match the requirement's project name, and its version must meet the match the requirement's project name, and its version must meet the
requirement's version criteria. If `dist_or_version` is a string, it is requirement's version criteria. If ``dist_or_version`` is a string, it is
parsed using the ``parse_version()`` utility function. Otherwise, it is parsed using the ``parse_version()`` utility function. Otherwise, it is
assumed to be an already-parsed version. assumed to be an already-parsed version.
...@@ -668,8 +668,8 @@ Requirements Parsing ...@@ -668,8 +668,8 @@ Requirements Parsing
``specs`` ``specs``
A list of ``(op,version)`` tuples, sorted in ascending parsed-version A list of ``(op,version)`` tuples, sorted in ascending parsed-version
order. The `op` in each tuple is a comparison operator, represented as order. The ``op`` in each tuple is a comparison operator, represented as
a string. The `version` is the (unparsed) version number. a string. The ``version`` is the (unparsed) version number.
``marker`` ``marker``
An instance of ``packaging.markers.Marker`` that allows evaluation An instance of ``packaging.markers.Marker`` that allows evaluation
...@@ -721,14 +721,14 @@ in sys.path order, etc. ...@@ -721,14 +721,14 @@ in sys.path order, etc.
Convenience API Convenience API
--------------- ---------------
In the following functions, the `dist` argument can be a ``Distribution`` In the following functions, the ``dist`` argument can be a ``Distribution``
instance, a ``Requirement`` instance, or a string specifying a requirement instance, a ``Requirement`` instance, or a string specifying a requirement
(i.e. project name, version, etc.). If the argument is a string or (i.e. project name, version, etc.). If the argument is a string or
``Requirement``, the specified distribution is located (and added to sys.path ``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 if not already present). An error will be raised if a matching distribution is
not available. not available.
The `group` argument should be a string containing a dotted identifier, The ``group`` argument should be a string containing a dotted identifier,
identifying an entry point group. If you are defining an entry point group, 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 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. to avoid collision with other packages' entry point groups.
...@@ -738,25 +738,25 @@ to avoid collision with other packages' entry point groups. ...@@ -738,25 +738,25 @@ to avoid collision with other packages' entry point groups.
``ImportError``. ``ImportError``.
``get_entry_info(dist, group, name)`` ``get_entry_info(dist, group, name)``
Return an ``EntryPoint`` object for the given `group` and `name` from Return an ``EntryPoint`` object for the given ``group`` and ``name`` from
the specified distribution. Returns ``None`` if the distribution has not the specified distribution. Returns ``None`` if the distribution has not
advertised a matching entry point. advertised a matching entry point.
``get_entry_map(dist, group=None)`` ``get_entry_map(dist, group=None)``
Return the distribution's entry point map for `group`, or the full entry Return the distribution's entry point map for ``group``, or the full entry
map for the distribution. This function always returns a dictionary, map for the distribution. This function always returns a dictionary,
even if the distribution advertises no entry points. If `group` is given, even if the distribution advertises no entry points. If ``group`` is given,
the dictionary maps entry point names to the corresponding ``EntryPoint`` the dictionary maps entry point names to the corresponding ``EntryPoint``
object. If `group` is None, the dictionary maps group names to object. If ``group`` is None, the dictionary maps group names to
dictionaries that then map entry point names to the corresponding dictionaries that then map entry point names to the corresponding
``EntryPoint`` instance in that group. ``EntryPoint`` instance in that group.
``iter_entry_points(group, name=None)`` ``iter_entry_points(group, name=None)``
Yield entry point objects from `group` matching `name`. Yield entry point objects from ``group`` matching ``name``.
If `name` is None, yields all entry points in `group` from all If ``name`` is None, yields all entry points in ``group`` from all
distributions in the working set on sys.path, otherwise only ones matching distributions in the working set on sys.path, otherwise only ones matching
both `group` and `name` are yielded. Entry points are yielded from both ``group`` and ``name`` are yielded. Entry points are yielded from
the active distributions in the order that the distributions appear on the active distributions in the order that the distributions appear on
sys.path. (Within entry points for a particular distribution, however, sys.path. (Within entry points for a particular distribution, however,
there is no particular ordering.) there is no particular ordering.)
...@@ -769,26 +769,26 @@ Creating and Parsing ...@@ -769,26 +769,26 @@ Creating and Parsing
-------------------- --------------------
``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)`` ``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)``
Create an ``EntryPoint`` instance. `name` is the entry point name. The Create an ``EntryPoint`` instance. ``name`` is the entry point name. The
`module_name` is the (dotted) name of the module containing the advertised ``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 object. ``attrs`` is an optional tuple of names to look up from the
module to obtain the advertised object. For example, an `attrs` of module to obtain the advertised object. For example, an ``attrs`` of
``("foo","bar")`` and a `module_name` of ``"baz"`` would mean that the ``("foo","bar")`` and a ``module_name`` of ``"baz"`` would mean that the
advertised object could be obtained by the following code:: advertised object could be obtained by the following code::
import baz import baz
advertised_object = baz.foo.bar advertised_object = baz.foo.bar
The `extras` are an optional tuple of "extra feature" names that the The ``extras`` are an optional tuple of "extra feature" names that the
distribution needs in order to provide this entry point. When the distribution needs in order to provide this entry point. When the
entry point is loaded, these extra features are looked up in the `dist` entry point is loaded, these extra features are looked up in the ``dist``
argument to find out what other distributions may need to be activated argument to find out what other distributions may need to be activated
on sys.path; see the ``load()`` method for more details. The `extras` on sys.path; see the ``load()`` method for more details. The ``extras``
argument is only meaningful if `dist` is specified. `dist` must be argument is only meaningful if ``dist`` is specified. ``dist`` must be
a ``Distribution`` instance. a ``Distribution`` instance.
``EntryPoint.parse(src, dist=None)`` (classmethod) ``EntryPoint.parse(src, dist=None)`` (classmethod)
Parse a single entry point from string `src` Parse a single entry point from string ``src``
Entry point syntax follows the form:: Entry point syntax follows the form::
...@@ -796,27 +796,27 @@ Creating and Parsing ...@@ -796,27 +796,27 @@ Creating and Parsing
The entry name and module name are required, but the ``:attrs`` and The entry name and module name are required, but the ``:attrs`` and
``[extras]`` parts are optional, as is the whitespace shown between ``[extras]`` parts are optional, as is the whitespace shown between
some of the items. The `dist` argument is passed through to the some of the items. The ``dist`` argument is passed through to the
``EntryPoint()`` constructor, along with the other values parsed from ``EntryPoint()`` constructor, along with the other values parsed from
`src`. ``src``.
``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod) ``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod)
Parse `lines` (a string or sequence of lines) to create a dictionary Parse ``lines`` (a string or sequence of lines) to create a dictionary
mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is
raised if entry point names are duplicated, if `group` is not a valid raised if entry point names are duplicated, if ``group`` is not a valid
entry point group name, or if there are any syntax errors. (Note: the entry point group name, or if there are any syntax errors. (Note: the
`group` parameter is used only for validation and to create more ``group`` parameter is used only for validation and to create more
informative error messages.) If `dist` is provided, it will be used to informative error messages.) If ``dist`` is provided, it will be used to
set the ``dist`` attribute of the created ``EntryPoint`` objects. set the ``dist`` attribute of the created ``EntryPoint`` objects.
``EntryPoint.parse_map(data, dist=None)`` (classmethod) ``EntryPoint.parse_map(data, dist=None)`` (classmethod)
Parse `data` into a dictionary mapping group names to dictionaries mapping Parse ``data`` into a dictionary mapping group names to dictionaries mapping
entry point names to ``EntryPoint`` objects. If `data` is a dictionary, 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 then the keys are used as group names and the values are passed to
``parse_group()`` as the `lines` argument. If `data` is a string or ``parse_group()`` as the ``lines`` argument. If ``data`` is a string or
sequence of lines, it is first split into .ini-style sections (using sequence of lines, it is first split into .ini-style sections (using
the ``split_sections()`` utility function) and the section names are used the ``split_sections()`` utility function) and the section names are used
as group names. In either case, the `dist` argument is passed through to as group names. In either case, the ``dist`` argument is passed through to
``parse_group()`` so that the entry points will be linked to the specified ``parse_group()`` so that the entry points will be linked to the specified
distribution. distribution.
...@@ -837,9 +837,9 @@ addition, the following methods are provided: ...@@ -837,9 +837,9 @@ addition, the following methods are provided:
Ensure that any "extras" needed by the entry point are available on Ensure that any "extras" needed by the entry point are available on
sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``, sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``,
but no ``dist``, or if the named extras are not defined by the but no ``dist``, or if the named extras are not defined by the
distribution. If `env` is supplied, it must be an ``Environment``, and it distribution. If ``env`` is supplied, it must be an ``Environment``, and it
will be used to search for needed distributions if they are not already will be used to search for needed distributions if they are not already
present on sys.path. If `installer` is supplied, it must be a callable present on sys.path. If ``installer`` is supplied, it must be a callable
taking a ``Requirement`` instance and returning a matching importable taking a ``Requirement`` instance and returning a matching importable
``Distribution`` instance or None. ``Distribution`` instance or None.
...@@ -872,16 +872,16 @@ available distributions, respectively.) You can also obtain ``Distribution`` ...@@ -872,16 +872,16 @@ available distributions, respectively.) You can also obtain ``Distribution``
objects from one of these high-level APIs: objects from one of these high-level APIs:
``find_distributions(path_item, only=False)`` ``find_distributions(path_item, only=False)``
Yield distributions accessible via `path_item`. If `only` is true, yield Yield distributions accessible via ``path_item``. If ``only`` is true, yield
only distributions whose ``location`` is equal to `path_item`. In other only distributions whose ``location`` is equal to ``path_item``. In other
words, if `only` is true, this yields any distributions that would be 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 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 also yields distributions that are "in" or "under" ``path_item``, but would
not be importable unless their locations were also added to ``sys.path``. not be importable unless their locations were also added to ``sys.path``.
``get_distribution(dist_spec)`` ``get_distribution(dist_spec)``
Return a ``Distribution`` object for a given ``Requirement`` or string. Return a ``Distribution`` object for a given ``Requirement`` or string.
If `dist_spec` is already a ``Distribution`` instance, it is returned. If ``dist_spec`` is already a ``Distribution`` instance, it is returned.
If it is a ``Requirement`` object or a string that can be parsed into one, 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 it is used to locate and activate a matching distribution, which is then
returned. returned.
...@@ -890,18 +890,18 @@ However, if you're creating specialized tools for working with distributions, ...@@ -890,18 +890,18 @@ However, if you're creating specialized tools for working with distributions,
or creating a new distribution format, you may also need to create or creating a new distribution format, you may also need to create
``Distribution`` objects directly, using one of the three constructors below. ``Distribution`` objects directly, using one of the three constructors below.
These constructors all take an optional `metadata` argument, which is used to These constructors all take an optional ``metadata`` argument, which is used to
access any resources or metadata associated with the distribution. `metadata` access any resources or metadata associated with the distribution. ``metadata``
must be an object that implements the ``IResourceProvider`` interface, or None. must be an object that implements the ``IResourceProvider`` interface, or None.
If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects
implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by
delegating them to the `metadata` object. delegating them to the ``metadata`` object.
``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod) ``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
Create a distribution for `location`, which must be a string such as a Create a distribution for ``location``, which must be a string such as a
URL, filename, or other string that might be used on ``sys.path``. 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``. ``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 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 version and platform are extracted from the filename and used to set those
properties of the created distribution. Any additional keyword arguments properties of the created distribution. Any additional keyword arguments
are forwarded to the ``Distribution()`` constructor. are forwarded to the ``Distribution()`` constructor.
...@@ -917,8 +917,8 @@ delegating them to the `metadata` object. ...@@ -917,8 +917,8 @@ delegating them to the `metadata` object.
``Distribution(location,metadata,project_name,version,py_version,platform,precedence)`` ``Distribution(location,metadata,project_name,version,py_version,platform,precedence)``
Create a distribution by setting its properties. All arguments are Create a distribution by setting its properties. All arguments are
optional and default to None, except for `py_version` (which defaults to optional and default to None, except for ``py_version`` (which defaults to
the current Python version) and `precedence` (which defaults to the current Python version) and ``precedence`` (which defaults to
``EGG_DIST``; for more details see ``precedence`` under `Distribution ``EGG_DIST``; for more details see ``precedence`` under `Distribution
Attributes`_ below). Note that it's usually easier to use the Attributes`_ below). Note that it's usually easier to use the
``from_filename()`` or ``from_location()`` constructors than to specify ``from_filename()`` or ``from_location()`` constructors than to specify
...@@ -938,7 +938,7 @@ project_name ...@@ -938,7 +938,7 @@ project_name
A string, naming the project that this distribution is for. Project names 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 are defined by a project's setup script, and they are used to identify
projects on PyPI. When a ``Distribution`` is constructed, the projects on PyPI. When a ``Distribution`` is constructed, the
`project_name` argument is passed through the ``safe_name()`` utility ``project_name`` argument is passed through the ``safe_name()`` utility
function to filter out any unacceptable characters. function to filter out any unacceptable characters.
key key
...@@ -952,9 +952,9 @@ extras ...@@ -952,9 +952,9 @@ extras
version version
A string denoting what release of the project this distribution contains. A string denoting what release of the project this distribution contains.
When a ``Distribution`` is constructed, the `version` argument is passed When a ``Distribution`` is constructed, the ``version`` argument is passed
through the ``safe_version()`` utility function to filter out any through the ``safe_version()`` utility function to filter out any
unacceptable characters. If no `version` is specified at construction unacceptable characters. If no ``version`` is specified at construction
time, then attempting to access this attribute later will cause the time, then attempting to access this attribute later will cause the
``Distribution`` to try to discover its version by reading its ``PKG-INFO`` ``Distribution`` to try to discover its version by reading its ``PKG-INFO``
metadata file. If ``PKG-INFO`` is unavailable or can't be parsed, metadata file. If ``PKG-INFO`` is unavailable or can't be parsed,
...@@ -967,7 +967,7 @@ parsed_version ...@@ -967,7 +967,7 @@ parsed_version
distributions by version. (See the `Parsing Utilities`_ section below for distributions by version. (See the `Parsing Utilities`_ section below for
more information on the ``parse_version()`` function.) Note that accessing more information on the ``parse_version()`` function.) Note that accessing
``parsed_version`` may result in a ``ValueError`` if the ``Distribution`` ``parsed_version`` may result in a ``ValueError`` if the ``Distribution``
was constructed without a `version` and without `metadata` capable of was constructed without a ``version`` and without ``metadata`` capable of
supplying the missing version info. supplying the missing version info.
py_version py_version
...@@ -998,9 +998,9 @@ precedence ...@@ -998,9 +998,9 @@ precedence
------------------------ ------------------------
``activate(path=None)`` ``activate(path=None)``
Ensure distribution is importable on `path`. If `path` is None, Ensure distribution is importable on ``path``. If ``path`` is None,
``sys.path`` is used instead. This ensures that the distribution's ``sys.path`` is used instead. This ensures that the distribution's
``location`` is in the `path` list, and it also performs any necessary ``location`` is in the ``path`` list, and it also performs any necessary
namespace package fixups or declarations. (That is, if the distribution namespace package fixups or declarations. (That is, if the distribution
contains namespace packages, this method ensures that they are declared, contains namespace packages, this method ensures that they are declared,
and that the distribution's contents for those namespace packages are and that the distribution's contents for those namespace packages are
...@@ -1020,7 +1020,7 @@ precedence ...@@ -1020,7 +1020,7 @@ precedence
``requires(extras=())`` ``requires(extras=())``
List the ``Requirement`` objects that specify this distribution's List the ``Requirement`` objects that specify this distribution's
dependencies. If `extras` is specified, it should be a sequence of names dependencies. If ``extras`` is specified, it should be a sequence of names
of "extras" defined by the distribution, and the list returned will then of "extras" defined by the distribution, and the list returned will then
include any dependencies needed to support the named "extras". include any dependencies needed to support the named "extras".
...@@ -1047,11 +1047,11 @@ by the distribution. See the section above on `Entry Points`_ for more ...@@ -1047,11 +1047,11 @@ by the distribution. See the section above on `Entry Points`_ for more
detailed information about these operations: detailed information about these operations:
``get_entry_info(group, name)`` ``get_entry_info(group, name)``
Return the ``EntryPoint`` object for `group` and `name`, or None if no Return the ``EntryPoint`` object for ``group`` and ``name``, or None if no
such point is advertised by this distribution. such point is advertised by this distribution.
``get_entry_map(group=None)`` ``get_entry_map(group=None)``
Return the entry point map for `group`. If `group` is None, return Return the entry point map for ``group``. If ``group`` is None, return
a dictionary mapping group names to entry point maps for all groups. 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`` (An entry point map is a dictionary of entry point names to ``EntryPoint``
objects.) objects.)
...@@ -1079,8 +1079,8 @@ documented in later sections): ...@@ -1079,8 +1079,8 @@ documented in later sections):
* ``resource_isdir(resource_name)`` * ``resource_isdir(resource_name)``
* ``resource_listdir(resource_name)`` * ``resource_listdir(resource_name)``
If the distribution was created with a `metadata` argument, these resource and If the distribution was created with a ``metadata`` argument, these resource and
metadata access methods are all delegated to that `metadata` provider. metadata access methods are all delegated to that ``metadata`` provider.
Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution
will appear to have no resources or metadata. This delegation approach is used 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 so that supporting custom importers or new distribution formats can be done
...@@ -1112,11 +1112,11 @@ Thus, you can use the APIs below without needing an explicit ...@@ -1112,11 +1112,11 @@ Thus, you can use the APIs below without needing an explicit
Basic Resource Access Basic Resource Access
--------------------- ---------------------
In the following methods, the `package_or_requirement` argument may be either In the following methods, the ``package_or_requirement`` argument may be either
a Python package/module name (e.g. ``foo.bar``) or a ``Requirement`` instance. 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 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 importable (i.e., be in a distribution or directory on ``sys.path``), and the
`resource_name` argument is interpreted relative to the named package. (Note ``resource_name`` argument is interpreted relative to the named package. (Note
that if a module name is used, then the resource name is relative to the 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 package immediately containing the named module. Also, you should not use use
a namespace package name, because a namespace package can be spread across a namespace package name, because a namespace package can be spread across
...@@ -1127,7 +1127,7 @@ If it is a ``Requirement``, then the requirement is automatically resolved ...@@ -1127,7 +1127,7 @@ If it is a ``Requirement``, then the requirement is automatically resolved
(searching the current ``Environment`` if necessary) and a matching (searching the current ``Environment`` if necessary) and a matching
distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not
already present. (Unless the ``Requirement`` can't be satisfied, in which already present. (Unless the ``Requirement`` can't be satisfied, in which
case an exception is raised.) The `resource_name` argument is then interpreted case an exception is raised.) The ``resource_name`` argument is then interpreted
relative to the root of the identified distribution; i.e. its first path 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 segment will be treated as a peer of the top-level modules or packages in the
distribution. distribution.
...@@ -1229,12 +1229,12 @@ no need to use these methods. Unlike the other methods listed above, they are ...@@ -1229,12 +1229,12 @@ no need to use these methods. Unlike the other methods listed above, they are
you must therefore have an explicit ``ResourceManager`` instance to use them. you must therefore have an explicit ``ResourceManager`` instance to use them.
``get_cache_path(archive_name, names=())`` ``get_cache_path(archive_name, names=())``
Return absolute location in cache for `archive_name` and `names` Return absolute location in cache for ``archive_name`` and ``names``
The parent directory of the resulting path will be created if it does The parent directory of the resulting path will be created if it does
not already exist. `archive_name` should be the base filename of the not already exist. ``archive_name`` should be the base filename of the
enclosing egg (which may not be the name of the enclosing zipfile!), enclosing egg (which may not be the name of the enclosing zipfile!),
including its ".egg" extension. `names`, if provided, should be a including its ".egg" extension. ``names``, if provided, should be a
sequence of path name parts "under" the egg's extraction location. sequence of path name parts "under" the egg's extraction location.
This method should only be called by resource providers that need to This method should only be called by resource providers that need to
...@@ -1250,12 +1250,12 @@ you must therefore have an explicit ``ResourceManager`` instance to use them. ...@@ -1250,12 +1250,12 @@ you must therefore have an explicit ``ResourceManager`` instance to use them.
wrap or handle extraction errors themselves. wrap or handle extraction errors themselves.
``postprocess(tempname, filename)`` ``postprocess(tempname, filename)``
Perform any platform-specific postprocessing of `tempname`. Perform any platform-specific postprocessing of ``tempname``.
Resource providers should call this method ONLY after successfully Resource providers should call this method ONLY after successfully
extracting a compressed resource. They must NOT call it on resources extracting a compressed resource. They must NOT call it on resources
that are already in the filesystem. that are already in the filesystem.
`tempname` is the current (temporary) name of the file, and `filename` ``tempname`` is the current (temporary) name of the file, and ``filename``
is the name it will be renamed to by the caller after this routine is the name it will be renamed to by the caller after this routine
returns. returns.
...@@ -1323,7 +1323,7 @@ implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are: ...@@ -1323,7 +1323,7 @@ implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are:
``run_script(script_name, namespace)`` ``run_script(script_name, namespace)``
Execute the named script in the supplied namespace dictionary. Raises Execute the named script in the supplied namespace dictionary. Raises
``ResolutionError`` if there is no script by that name in the ``scripts`` ``ResolutionError`` if there is no script by that name in the ``scripts``
metadata directory. `namespace` should be a Python dictionary, usually metadata directory. ``namespace`` should be a Python dictionary, usually
a module dictionary if the script is being run as a module. a module dictionary if the script is being run as a module.
...@@ -1380,11 +1380,11 @@ with other (PEP 302-compatible) importers or module loaders, you may need to ...@@ -1380,11 +1380,11 @@ with other (PEP 302-compatible) importers or module loaders, you may need to
register various handlers and support functions using these APIs: register various handlers and support functions using these APIs:
``register_finder(importer_type, distribution_finder)`` ``register_finder(importer_type, distribution_finder)``
Register `distribution_finder` to find distributions in ``sys.path`` items. Register ``distribution_finder`` to find distributions in ``sys.path`` items.
`importer_type` is the type or class of a PEP 302 "Importer" (``sys.path`` ``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 item handler), and ``distribution_finder`` is a callable that, when passed a
path item, the importer instance, and an `only` flag, yields path item, the importer instance, and an ``only`` flag, yields
``Distribution`` instances found under that path item. (The `only` flag, ``Distribution`` instances found under that path item. (The ``only`` flag,
if true, means the finder should yield only ``Distribution`` objects whose if true, means the finder should yield only ``Distribution`` objects whose
``location`` is equal to the path item provided.) ``location`` is equal to the path item provided.)
...@@ -1392,16 +1392,16 @@ register various handlers and support functions using these APIs: ...@@ -1392,16 +1392,16 @@ register various handlers and support functions using these APIs:
example finder function. example finder function.
``register_loader_type(loader_type, provider_factory)`` ``register_loader_type(loader_type, provider_factory)``
Register `provider_factory` to make ``IResourceProvider`` objects for Register ``provider_factory`` to make ``IResourceProvider`` objects for
`loader_type`. `loader_type` is the type or class of a PEP 302 ``loader_type``. ``loader_type`` is the type or class of a PEP 302
``module.__loader__``, and `provider_factory` is a function that, when ``module.__loader__``, and ``provider_factory`` is a function that, when
passed a module object, returns an `IResourceProvider`_ for that module, passed a module object, returns an `IResourceProvider`_ for that module,
allowing it to be used with the `ResourceManager API`_. allowing it to be used with the `ResourceManager API`_.
``register_namespace_handler(importer_type, namespace_handler)`` ``register_namespace_handler(importer_type, namespace_handler)``
Register `namespace_handler` to declare namespace packages for the given Register ``namespace_handler`` to declare namespace packages for the given
`importer_type`. `importer_type` is the type or class of a PEP 302 ``importer_type``. ``importer_type`` is the type or class of a PEP 302
"importer" (sys.path item handler), and `namespace_handler` is a callable "importer" (sys.path item handler), and ``namespace_handler`` is a callable
with a signature like this:: with a signature like this::
def namespace_handler(importer, path_entry, moduleName, module): def namespace_handler(importer, path_entry, moduleName, module):
...@@ -1421,23 +1421,23 @@ IResourceProvider ...@@ -1421,23 +1421,23 @@ IResourceProvider
----------------- -----------------
``IResourceProvider`` is an abstract class that documents what methods are ``IResourceProvider`` is an abstract class that documents what methods are
required of objects returned by a `provider_factory` registered with required of objects returned by a ``provider_factory`` registered with
``register_loader_type()``. ``IResourceProvider`` is a subclass of ``register_loader_type()``. ``IResourceProvider`` is a subclass of
``IMetadataProvider``, so objects that implement this interface must also ``IMetadataProvider``, so objects that implement this interface must also
implement all of the `IMetadataProvider Methods`_ as well as the methods implement all of the `IMetadataProvider Methods`_ as well as the methods
shown here. The `manager` argument to the methods below must be an object shown here. The ``manager`` argument to the methods below must be an object
that supports the full `ResourceManager API`_ documented above. that supports the full `ResourceManager API`_ documented above.
``get_resource_filename(manager, resource_name)`` ``get_resource_filename(manager, resource_name)``
Return a true filesystem path for `resource_name`, coordinating the Return a true filesystem path for ``resource_name``, coordinating the
extraction with `manager`, if the resource must be unpacked to the extraction with ``manager``, if the resource must be unpacked to the
filesystem. filesystem.
``get_resource_stream(manager, resource_name)`` ``get_resource_stream(manager, resource_name)``
Return a readable file-like object for `resource_name`. Return a readable file-like object for ``resource_name``.
``get_resource_string(manager, resource_name)`` ``get_resource_string(manager, resource_name)``
Return a string containing the contents of `resource_name`. Return a string containing the contents of ``resource_name``.
``has_resource(resource_name)`` ``has_resource(resource_name)``
Does the package contain the named resource? Does the package contain the named resource?
...@@ -1501,15 +1501,15 @@ where appropriate. Their inheritance tree looks like this:: ...@@ -1501,15 +1501,15 @@ where appropriate. Their inheritance tree looks like this::
``PathMetadata(path, egg_info)`` ``PathMetadata(path, egg_info)``
Create an ``IResourceProvider`` for a filesystem-based distribution, where Create an ``IResourceProvider`` for a filesystem-based distribution, where
`path` is the filesystem location of the importable modules, and `egg_info` ``path`` is the filesystem location of the importable modules, and ``egg_info``
is the filesystem location of the distribution's metadata directory. is the filesystem location of the distribution's metadata directory.
`egg_info` should usually be the ``EGG-INFO`` subdirectory of `path` for an ``egg_info`` should usually be the ``EGG-INFO`` subdirectory of ``path`` for an
"unpacked egg", and a ``ProjectName.egg-info`` subdirectory of `path` for "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of ``path`` for
a "development egg". However, other uses are possible for custom purposes. a "development egg". However, other uses are possible for custom purposes.
``EggMetadata(zipimporter)`` ``EggMetadata(zipimporter)``
Create an ``IResourceProvider`` for a zipfile-based distribution. The Create an ``IResourceProvider`` for a zipfile-based distribution. The
`zipimporter` should be a ``zipimport.zipimporter`` instance, and may ``zipimporter`` should be a ``zipimport.zipimporter`` instance, and may
represent a "basket" (a zipfile containing multiple ".egg" subdirectories) represent a "basket" (a zipfile containing multiple ".egg" subdirectories)
a specific egg *within* a basket, or a zipfile egg (where the zipfile 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 itself is a ".egg"). It can also be a combination, such as a zipfile egg
...@@ -1547,12 +1547,12 @@ Parsing Utilities ...@@ -1547,12 +1547,12 @@ Parsing Utilities
``yield_lines(strs)`` ``yield_lines(strs)``
Yield non-empty/non-comment lines from a string/unicode or a possibly- Yield non-empty/non-comment lines from a string/unicode or a possibly-
nested sequence thereof. If `strs` is an instance of ``basestring``, it nested sequence thereof. If ``strs`` is an instance of ``basestring``, it
is split into lines, and each non-blank, non-comment line is yielded after is split into lines, and each non-blank, non-comment line is yielded after
stripping leading and trailing whitespace. (Lines whose first non-blank stripping leading and trailing whitespace. (Lines whose first non-blank
character is ``#`` are considered comment lines.) character is ``#`` are considered comment lines.)
If `strs` is not an instance of ``basestring``, it is iterated over, and If ``strs`` is not an instance of ``basestring``, it is iterated over, and
each item is passed recursively to ``yield_lines()``, so that an arbitrarily each item is passed recursively to ``yield_lines()``, so that an arbitrarily
nested sequence of strings, or sequences of sequences of strings can be nested sequence of strings, or sequences of sequences of strings can be
flattened out to the lines contained therein. So for example, passing flattened out to the lines contained therein. So for example, passing
...@@ -1636,15 +1636,15 @@ Platform Utilities ...@@ -1636,15 +1636,15 @@ Platform Utilities
``compatible_platforms()`` function. ``compatible_platforms()`` function.
``compatible_platforms(provided, required)`` ``compatible_platforms(provided, required)``
Return true if a distribution built on the `provided` platform may be used 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 on the ``required`` platform. If either platform value is ``None``, it is
considered a wildcard, and the platforms are therefore compatible. considered a wildcard, and the platforms are therefore compatible.
Likewise, if the platform strings are equal, they're also considered Likewise, if the platform strings are equal, they're also considered
compatible, and ``True`` is returned. Currently, the only non-equal compatible, and ``True`` is returned. Currently, the only non-equal
platform strings that are considered compatible are macOS platform platform strings that are considered compatible are macOS platform
strings with the same hardware type (e.g. ``ppc``) and major version 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 (e.g. ``10``) with the ``provided`` platform's minor version being less than
or equal to the `required` platform's minor version. or equal to the ``required`` platform's minor version.
``get_default_cache()`` ``get_default_cache()``
Determine the default cache location for extracting resources from zipped Determine the default cache location for extracting resources from zipped
...@@ -1666,14 +1666,14 @@ File/Path Utilities ...@@ -1666,14 +1666,14 @@ File/Path Utilities
------------------- -------------------
``ensure_directory(path)`` ``ensure_directory(path)``
Ensure that the parent directory (``os.path.dirname``) of `path` actually Ensure that the parent directory (``os.path.dirname``) of ``path`` actually
exists, using ``os.makedirs()`` if necessary. exists, using ``os.makedirs()`` if necessary.
``normalize_path(path)`` ``normalize_path(path)``
Return a "normalized" version of `path`, such that two paths represent Return a "normalized" version of ``path``, such that two paths represent
the same filesystem location if they have equal ``normalized_path()`` the same filesystem location if they have equal ``normalized_path()``
values. Specifically, this is a shortcut for calling ``os.path.realpath`` values. Specifically, this is a shortcut for calling ``os.path.realpath``
and ``os.path.normcase`` on `path`. Unfortunately, on certain platforms and ``os.path.normcase`` on ``path``. Unfortunately, on certain platforms
(notably Cygwin and macOS) the ``normcase`` function does not accurately (notably Cygwin and macOS) the ``normcase`` function does not accurately
reflect the platform's case-sensitivity, so there is always the possibility reflect the platform's case-sensitivity, so there is always the possibility
of two apparently-different paths being equal on such platforms. of two apparently-different paths being equal on such platforms.
......
docs/references/keywords.rst
View file @ 490301f4
========
Keywords
========
``name`` ``name``
A string specifying the name of the package. A string specifying the name of the package.
...@@ -189,7 +193,7 @@ ...@@ -189,7 +193,7 @@
discovery of services or plugins provided by a project. See :ref:`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 Discovery of Services and Plugins` for details and examples of the format
of this argument. In addition, this keyword is used to support of this argument. In addition, this keyword is used to support
:ref:`Automatic Script Creation`. :ref:`Automatic Script Creation <entry_points>`.
``extras_require`` ``extras_require``
A dictionary mapping names of "extras" (optional features of your project) A dictionary mapping names of "extras" (optional features of your project)
...@@ -282,7 +286,7 @@ ...@@ -282,7 +286,7 @@
this argument. The named class must be instantiable with no arguments, and this argument. The named class must be instantiable with no arguments, and
its instances must support the ``loadTestsFromNames()`` method as defined its instances must support the ``loadTestsFromNames()`` method as defined
in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
pass only one test "name" in the `names` argument: the value supplied for pass only one test "name" in the ``names`` argument: the value supplied for
the ``test_suite`` argument. The loader you specify may interpret this 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 string in any way it likes, as there are no restrictions on what may be
contained in a ``test_suite`` string. contained in a ``test_suite`` string.
...@@ -317,15 +321,15 @@ ...@@ -317,15 +321,15 @@
``use_2to3`` ``use_2to3``
Convert the source code from Python 2 to Python 3 with 2to3 during the Convert the source code from Python 2 to Python 3 with 2to3 during the
build process. See :doc:`python3` for more details. build process. See :doc:`../deprecated/python3` for more details.
``convert_2to3_doctests`` ``convert_2to3_doctests``
List of doctest source files that need to be converted with 2to3. List of doctest source files that need to be converted with 2to3.
See :doc:`python3` for more details. See :doc:`../deprecated/python3` for more details.
``use_2to3_fixers`` ``use_2to3_fixers``
A list of modules to search for additional fixers to be used during A list of modules to search for additional fixers to be used during
the 2to3 conversion. See :doc:`python3` for more details. the 2to3 conversion. See :doc:`../deprecated/python3` for more details.
``use_2to3_exclude_fixers`` ``use_2to3_exclude_fixers``
List of fixer names to be skipped. List of fixer names to be skipped.
......
docs/userguide/commands.rst
View file @ 490301f4
...@@ -275,7 +275,7 @@ is used when you are building source distributions.) ...@@ -275,7 +275,7 @@ is used when you are building source distributions.)
In addition to writing the core egg metadata defined by ``setuptools`` and In addition to writing the core egg metadata defined by ``setuptools`` and
required by ``pkg_resources``, this command can be extended to write other 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`` 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. group. See the section on :ref:`Adding new EGG-INFO Files` below for more details.
Note that using additional metadata writers may require you to include a Note that using additional metadata writers may require you to include a
``setup_requires`` argument to ``setup()`` in order to ensure that the desired ``setup_requires`` argument to ``setup()`` in order to ensure that the desired
writers are available on ``sys.path``. writers are available on ``sys.path``.
...@@ -315,7 +315,7 @@ added in the following order: ...@@ -315,7 +315,7 @@ added in the following order:
(Note: Because these options modify the version number used for source and (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 binary distributions of your project, you should first make sure that you know
how the resulting version numbers will be interpreted by automated tools 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 like pip. See the section above on :ref:`Specifying Your Project's Version` for an
explanation of pre- and post-release tags, as well as tips on how to choose and explanation of pre- and post-release tags, as well as tips on how to choose and
verify a versioning scheme for your project.) verify a versioning scheme for your project.)
......
docs/userguide/datafiles.rst
View file @ 490301f4
...@@ -20,8 +20,8 @@ e.g.:: ...@@ -20,8 +20,8 @@ e.g.::
This tells setuptools to install any data files it finds in your packages. 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. 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 (They can also be tracked by a revision control system, using an appropriate
plugin. See the section below on `Adding Support for Revision Control plugin. See the section below on :ref:`Adding Support for Revision
Systems`_ for information on how to write such plugins.) 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 want finer-grained control over what files are included (for example,
if you have documentation files in your package directories and want to exclude if you have documentation files in your package directories and want to exclude
...@@ -144,6 +144,9 @@ if they track intermediate revisions of your project using Subversion; be sure ...@@ -144,6 +144,9 @@ 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 to let them know when you make changes that remove files from inclusion so they
can run ``setup.py clean --all``. can run ``setup.py clean --all``.
.. _Accessing Data Files at Runtime:
Accessing Data Files at Runtime Accessing Data Files at Runtime
------------------------------- -------------------------------
...@@ -171,4 +174,4 @@ fall back to the platform-specific location for installing data files, there is ...@@ -171,4 +174,4 @@ fall back to the platform-specific location for installing data files, there is
no supported facility to reliably retrieve these resources. no supported facility to reliably retrieve these resources.
Instead, the PyPA recommends that any data files you wish to be accessible at Instead, the PyPA recommends that any data files you wish to be accessible at
run time be included in the package. run time be included in the package.
\ No newline at end of file
docs/userguide/declarative_config.rst
View file @ 490301f4
.. _declarative config:
----------------------------------------- -----------------------------------------
Configuring setup() using setup.cfg files Configuring setup() using setup.cfg files
----------------------------------------- -----------------------------------------
...@@ -199,7 +201,7 @@ obsoletes list-comma ...@@ -199,7 +201,7 @@ obsoletes list-comma
string in such a file, so validation is stricter in this case. string in such a file, so validation is stricter in this case.
Notes: Notes:
1. The `version` file attribute has only been supported since 39.2.0. 1. The ``version`` file attribute has only been supported since 39.2.0.
Options Options
------- -------
...@@ -235,12 +237,12 @@ data_files dict 40.6.0 ...@@ -235,12 +237,12 @@ data_files dict 40.6.0
**packages** - The ``find:`` and ``find_namespace:`` directive can be further configured **packages** - The ``find:`` and ``find_namespace:`` directive can be further configured
in a dedicated subsection ``options.packages.find``. This subsection in a dedicated subsection ``options.packages.find``. This subsection
accepts the same keys as the `setuptools.find_packages` and the accepts the same keys as the ``setuptools.find_packages`` and the
`setuptools.find_namespace_packages` function: ``setuptools.find_namespace_packages`` function:
``where``, ``include``, and ``exclude``. ``where``, ``include``, and ``exclude``.
**find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3. **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3.
Notes: Notes:
1. In the `package_data` section, a key named with a single asterisk (`*`) 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`. refers to all packages, in lieu of the empty string used in ``setup.py``.
docs/userguide/dependency_management.rst
View file @ 490301f4
...@@ -25,7 +25,7 @@ you also need the ``wheel`` package as well since it is recommended that you ...@@ -25,7 +25,7 @@ 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 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 other two types of dependency keyword, this one is specified in your
``pyproject.toml`` file (if you have forgot what this is, go to ``pyproject.toml`` file (if you have forgot what this is, go to
:ref:`quickstart` or (WIP)): :doc:`quickstart` or (WIP)):
.. code-block:: ini .. code-block:: ini
...@@ -36,10 +36,11 @@ other two types of dependency keyword, this one is specified in your ...@@ -36,10 +36,11 @@ other two types of dependency keyword, this one is specified in your
.. note:: .. note::
This used to be accomplished with the ``setup_requires`` keyword but is This used to be accomplished with the ``setup_requires`` keyword but is
now considered deprecated in favor of the PEP 517 style described above. 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 To peek into how this legacy keyword is used, consult our :doc:`guide on
deprecated practice (WIP)` deprecated practice (WIP) <../deprecated/index>`
.. _Declaring Dependencies:
Declaring required dependency Declaring required dependency
============================= =============================
......
docs/userguide/development_mode.rst
View file @ 490301f4
...@@ -49,7 +49,7 @@ source from a staging area using ``setup.py develop --uninstall``, specifying ...@@ -49,7 +49,7 @@ source from a staging area using ``setup.py develop --uninstall``, specifying
the desired staging area if it's not the default. the desired staging area if it's not the default.
There are several options to control the precise behavior of the ``develop`` There are several options to control the precise behavior of the ``develop``
command; see the section on the `develop`_ command below for more details. command; see the section on the :ref:`develop <develop>` command below for more details.
Note that you can also apply setuptools commands to non-setuptools projects, Note that you can also apply setuptools commands to non-setuptools projects,
using commands like this:: using commands like this::
...@@ -57,4 +57,4 @@ using commands like this:: ...@@ -57,4 +57,4 @@ using commands like this::
python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop 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 That is, you can simply list the normal setup commands and options following
the quoted part. the quoted part.
\ No newline at end of file
docs/userguide/distribution.rst
View file @ 490301f4
...@@ -23,17 +23,17 @@ egg distributions by adding one or more of the following to the project's ...@@ -23,17 +23,17 @@ egg distributions by adding one or more of the following to the project's
You can add these tags by adding ``egg_info`` and the desired options to 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 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 to generate a daily build or snapshot for. See the section below on the
`egg_info`_ command for more details. :ref:`egg_info <egg_info>` command for more details.
(Also, before you release your project, be sure to see the section above on (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 :ref:`Specifying Your Project's Version` for more information about how pre- and
post-release tags affect how version numbers are interpreted. This is post-release tags affect how version numbers are interpreted. This is
important in order to make sure that dependency processing tools will know important in order to make sure that dependency processing tools will know
which versions of your project are newer than others.) which versions of your project are newer than others.)
Finally, if you are creating builds frequently, and either building them in a 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 downloadable location or are copying them to a distribution server, you should
probably also check out the `rotate`_ command, which lets you automatically probably also check out the :ref:`rotate <rotate>` command, which lets you automatically
delete all but the N most-recently-modified distributions matching a glob delete all but the N most-recently-modified distributions matching a glob
pattern. So, you can use a command line like:: pattern. So, you can use a command line like::
...@@ -46,7 +46,7 @@ that were built most recently. ...@@ -46,7 +46,7 @@ that were built most recently.
If you have to manage automated builds for multiple packages, each with 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 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`` :ref:`alias <alias>` command, which would let each package define an alias like ``daily``
that would perform the necessary tag, build, and rotate commands. Then, a 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 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 directory. (And, you could also define sitewide or per-user default versions
...@@ -61,7 +61,7 @@ selection with pluggable endpoints for looking up files to include. If you are ...@@ -61,7 +61,7 @@ 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 using a revision control system, and your source distributions only need to
include files that you're tracking in revision control, use a corresponding 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 plugin instead of writing a ``MANIFEST.in`` file. See the section below on
`Adding Support for Revision Control Systems`_ for information on plugins. :ref:`Adding Support for Revision Control Systems` for information on plugins.
If you need to include automatically generated files, or files that are kept in 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`` an unsupported revision control system, you'll need to create a ``MANIFEST.in``
...@@ -114,7 +114,8 @@ You can then use it like this:: ...@@ -114,7 +114,8 @@ You can then use it like this::
setup.py release sdist bdist_egg setup.py release sdist bdist_egg
Or of course you can create more elaborate aliases that do all of the above. 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. See the sections below on the :ref:`egg_info <egg_info>` and
:ref:`alias <alias>` commands for more ideas.
Distributing Extensions compiled with Cython Distributing Extensions compiled with Cython
-------------------------------------------- --------------------------------------------
...@@ -154,6 +155,9 @@ control system will be able to build it even if they don't have Cython ...@@ -154,6 +155,9 @@ 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 installed, and that your source releases will be similarly usable with or
without Cython. without Cython.
.. _Specifying Your Project's Version:
Specifying Your Project's Version Specifying Your Project's Version
--------------------------------- ---------------------------------
...@@ -237,4 +241,4 @@ have setuptools automatically tag your in-development releases with various ...@@ -237,4 +241,4 @@ have setuptools automatically tag your in-development releases with various
pre- or post-release tags. See the following sections for more details: pre- or post-release tags. See the following sections for more details:
* `Tagging and "Daily Build" or "Snapshot" Releases`_ * `Tagging and "Daily Build" or "Snapshot" Releases`_
* The `egg_info`_ command * The :ref:`egg_info <egg_info>` command
\ No newline at end of file
docs/userguide/entry_point.rst
View file @ 490301f4
...@@ -76,6 +76,8 @@ In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which ...@@ -76,6 +76,8 @@ In addition to ``console_scripts``, Setuptools supports ``gui_scripts``, which
will launch a GUI application without running in a terminal window. will launch a GUI application without running in a terminal window.
.. _dynamic discovery of services and plugins:
Advertising Behavior Advertising Behavior
==================== ====================
...@@ -140,7 +142,7 @@ Some entry points may require additional dependencies to properly function. ...@@ -140,7 +142,7 @@ Some entry points may require additional dependencies to properly function.
For such an entry point, declare in square brakets any number of dependency For such an entry point, declare in square brakets any number of dependency
``extras`` following the entry point definition. Such entry points will only ``extras`` following the entry point definition. Such entry points will only
be viable if their extras were declared and installed. See the be viable if their extras were declared and installed. See the
:ref:`guide on dependencies management <dependency_management>` for :doc:`guide on dependencies management <dependency_management>` for
more information on defining extra requirements. Consider from the more information on defining extra requirements. Consider from the
above example: above example:
......
docs/userguide/extension.rst
View file @ 490301f4
.. _Creating ``distutils`` Extensions:
Creating ``distutils`` Extensions Creating ``distutils`` Extensions
================================= =================================
...@@ -9,8 +11,8 @@ the extension just refer to it in their ``setup_requires`` argument. ...@@ -9,8 +11,8 @@ the extension just refer to it in their ``setup_requires`` argument.
With ``setuptools``, your distutils extension projects can hook in new With ``setuptools``, your distutils extension projects can hook in new
commands and ``setup()`` arguments just by defining "entry points". These commands and ``setup()`` arguments just by defining "entry points". These
are mappings from command or argument names to a specification of where to 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 import a handler from. (See the section on :ref:`Dynamic Discovery of
Plugins`_ above for some more background on entry points.) Services and Plugins` above for some more background on entry points.)
Adding Commands Adding Commands
...@@ -120,6 +122,8 @@ plugin is encouraged to load the configuration/settings for their behavior ...@@ -120,6 +122,8 @@ plugin is encouraged to load the configuration/settings for their behavior
independently. independently.
.. _Adding new EGG-INFO Files:
Adding new EGG-INFO Files Adding new EGG-INFO Files
------------------------- -------------------------
...@@ -173,6 +177,9 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and ...@@ -173,6 +177,9 @@ the ``cmd`` object's ``write_file()``, ``delete_file()``, and
``write_or_delete_file()`` methods exclusively for your file operations. See ``write_or_delete_file()`` methods exclusively for your file operations. See
those methods' docstrings for more details. those methods' docstrings for more details.
.. _Adding Support for Revision Control Systems:
Adding Support for Revision Control Systems Adding Support for Revision Control Systems
------------------------------------------------- -------------------------------------------------
...@@ -232,4 +239,4 @@ A few important points for writing revision control file finders: ...@@ -232,4 +239,4 @@ A few important points for writing revision control file finders:
* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully * 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 with the absence of needed programs (i.e., ones belonging to the revision
control system itself. It *may*, however, use ``distutils.log.warn()`` to control system itself. It *may*, however, use ``distutils.log.warn()`` to
inform the user of the missing program(s). inform the user of the missing program(s).
\ No newline at end of file
docs/userguide/index.rst
View file @ 490301f4
...@@ -24,3 +24,5 @@ ordinary Python packages based on the ``distutils``. ...@@ -24,3 +24,5 @@ ordinary Python packages based on the ``distutils``.
declarative_config declarative_config
keywords keywords
commands commands
functionalities_rewrite
miscellaneous
docs/userguide/keywords.rst
View file @ 490301f4
...@@ -8,19 +8,19 @@ unless you need the associated ``setuptools`` feature. ...@@ -8,19 +8,19 @@ unless you need the associated ``setuptools`` feature.
``include_package_data`` ``include_package_data``
If set to ``True``, this tells ``setuptools`` to automatically include any If set to ``True``, this tells ``setuptools`` to automatically include any
data files it finds inside your package directories that are specified by data files it finds inside your package directories that are specified by
your ``MANIFEST.in`` file. For more information, see the section below on your ``MANIFEST.in`` file. For more information, see the section on
`Including Data Files`_. :ref:`Including Data Files`.
``exclude_package_data`` ``exclude_package_data``
A dictionary mapping package names to lists of glob patterns that should 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 be *excluded* from your package directories. You can use this to trim back
any excess files included by ``include_package_data``. For a complete any excess files included by ``include_package_data``. For a complete
description and examples, see the section below on `Including Data Files`_. description and examples, see the section on :ref:`Including Data Files`.
``package_data`` ``package_data``
A dictionary mapping package names to lists of glob patterns. For a A dictionary mapping package names to lists of glob patterns. For a
complete description and examples, see the section below on `Including complete description and examples, see the section on :ref:`Including
Data Files`_. You do not need to use this option if you are using 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 ``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 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 in source control or are files that you don't want to include in your
...@@ -34,22 +34,22 @@ unless you need the associated ``setuptools`` feature. ...@@ -34,22 +34,22 @@ unless you need the associated ``setuptools`` feature.
``install_requires`` ``install_requires``
A string or list of strings specifying what other distributions need to A string or list of strings specifying what other distributions need to
be installed when this one is. See the section below on `Declaring be installed when this one is. See the section on :ref:`Declaring
Dependencies`_ for details and examples of the format of this argument. Dependencies` for details and examples of the format of this argument.
``entry_points`` ``entry_points``
A dictionary mapping entry point group names to strings or lists of strings A dictionary mapping entry point group names to strings or lists of strings
defining the entry points. Entry points are used to support dynamic 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 or plugins provided by a project. See :ref:`Dynamic
Discovery of Services and Plugins`_ for details and examples of the format Discovery of Services and Plugins` for details and examples of the format
of this argument. In addition, this keyword is used to support `Automatic of this argument. In addition, this keyword is used to support
Script Creation`_. :ref:`Automatic Script Creation <entry_points>`.
``extras_require`` ``extras_require``
A dictionary mapping names of "extras" (optional features of your project) A dictionary mapping names of "extras" (optional features of your project)
to strings or lists of strings specifying what other distributions must be to strings or lists of strings specifying what other distributions must be
installed to support those features. See the section below on `Declaring installed to support those features. See the section on :ref:`Declaring
Dependencies`_ for details and examples of the format of this argument. Dependencies` for details and examples of the format of this argument.
``python_requires`` ``python_requires``
A string corresponding to a version specifier (as defined in PEP 440) for A string corresponding to a version specifier (as defined in PEP 440) for
...@@ -87,7 +87,7 @@ unless you need the associated ``setuptools`` feature. ...@@ -87,7 +87,7 @@ unless you need the associated ``setuptools`` feature.
as you declare them in each project that contains any subpackages of the 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`` namespace package, and as long as the namespace package's ``__init__.py``
does not contain any code other than a namespace declaration. See the does not contain any code other than a namespace declaration. See the
section below on `Namespace Packages`_ for more information. section below on :ref:`Namespace Packages` for more information.
``test_suite`` ``test_suite``
A string naming a ``unittest.TestCase`` subclass (or a package or module A string naming a ``unittest.TestCase`` subclass (or a package or module
...@@ -98,9 +98,9 @@ unless you need the associated ``setuptools`` feature. ...@@ -98,9 +98,9 @@ unless you need the associated ``setuptools`` feature.
added to the tests to be run. If the named suite is a package, any 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. submodules and subpackages are recursively added to the overall test suite.
Specifying this argument enables use of the `test`_ command to run the Specifying this argument enables use of the :ref:`test <test>` command to run the
specified test suite, e.g. via ``setup.py test``. See the section on the specified test suite, e.g. via ``setup.py test``. See the section on the
`test`_ command below for more details. :ref:`test <test>` command below for more details.
New in 41.5.0: Deprecated the test command. New in 41.5.0: Deprecated the test command.
...@@ -124,7 +124,7 @@ unless you need the associated ``setuptools`` feature. ...@@ -124,7 +124,7 @@ unless you need the associated ``setuptools`` feature.
this argument. The named class must be instantiable with no arguments, and this argument. The named class must be instantiable with no arguments, and
its instances must support the ``loadTestsFromNames()`` method as defined its instances must support the ``loadTestsFromNames()`` method as defined
in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
pass only one test "name" in the `names` argument: the value supplied for pass only one test "name" in the ``names`` argument: the value supplied for
the ``test_suite`` argument. The loader you specify may interpret this 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 string in any way it likes, as there are no restrictions on what may be
contained in a ``test_suite`` string. contained in a ``test_suite`` string.
...@@ -155,21 +155,21 @@ unless you need the associated ``setuptools`` feature. ...@@ -155,21 +155,21 @@ unless you need the associated ``setuptools`` feature.
extensions that access other files in the project (such as data files or 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 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 mess with it. For more details on how this argument works, see the section
below on `Automatic Resource Extraction`_. below on :ref:`Automatic Resource Extraction`.
``use_2to3`` ``use_2to3``
Convert the source code from Python 2 to Python 3 with 2to3 during the Convert the source code from Python 2 to Python 3 with 2to3 during the
build process. See :doc:`python3` for more details. build process. See :doc:`../deprecated/python3` for more details.
``convert_2to3_doctests`` ``convert_2to3_doctests``
List of doctest source files that need to be converted with 2to3. List of doctest source files that need to be converted with 2to3.
See :doc:`python3` for more details. See :doc:`../deprecated/python3` for more details.
``use_2to3_fixers`` ``use_2to3_fixers``
A list of modules to search for additional fixers to be used during A list of modules to search for additional fixers to be used during
the 2to3 conversion. See :doc:`python3` for more details. the 2to3 conversion. See :doc:`../deprecated/python3` for more details.
``project_urls`` ``project_urls``
An arbitrary map of URL names to hyperlinks, allowing more extensible An arbitrary map of URL names to hyperlinks, allowing more extensible
documentation of where various resources can be found than the simple documentation of where various resources can be found than the simple
``url`` and ``download_url`` options provide. ``url`` and ``download_url`` options provide.
\ No newline at end of file
docs/userguide/miscellaneous.rst
View file @ 490301f4
.. _Automatic Resource Extraction:
Automatic Resource Extraction Automatic Resource Extraction
----------------------------- -----------------------------
...@@ -46,8 +48,8 @@ directory. However, since it can be tedious to create such files by hand, you ...@@ -46,8 +48,8 @@ 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 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 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 for many of the ``setup()`` arguments it adds. See the section below on
`Creating distutils Extensions`_ for more details, especially the subsection on :ref:`Creating ``distutils\`\` Extensions` for more details, especially the
`Adding new EGG-INFO Files`_. subsection on :ref:`Adding new EGG-INFO Files`.
Setting the ``zip_safe`` flag Setting the ``zip_safe`` flag
----------------------------- -----------------------------
...@@ -75,7 +77,7 @@ no ``__file__`` or ``__path__`` introspection or source code manipulation, then ...@@ -75,7 +77,7 @@ no ``__file__`` or ``__path__`` introspection or source code manipulation, then
there is an extremely solid chance the project will work when installed as a 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 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. 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.) See the :ref:`Accessing Data Files at Runtime` section above for more information.)
However, if ``bdist_egg`` can't be *sure* that your package will work, but 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 you've checked over all the warnings it issued, and you are either satisfied it
......
docs/userguide/package_discovery.rst
View file @ 490301f4
...@@ -6,13 +6,13 @@ Package Discovery and Namespace Package ...@@ -6,13 +6,13 @@ Package Discovery and Namespace Package
.. note:: .. note::
a full specification for the keyword supplied to ``setup.cfg`` or a full specification for the keyword supplied to ``setup.cfg`` or
``setup.py`` can be found at :ref:`keywords reference <keywords_ref>` ``setup.py`` can be found at :doc:`keywords reference <keywords>`
.. note:: .. note::
the examples provided here are only to demonstrate the functionality the examples provided here are only to demonstrate the functionality
introduced. More metadata and options arguments need to be supplied introduced. More metadata and options arguments need to be supplied
if you want to replicate them on your system. If you are completely if you want to replicate them on your system. If you are completely
new to setuptools, the :ref:`quickstart section <quickstart>` is a good new to setuptools, the :doc:`quickstart section <quickstart>` is a good
place to start. place to start.
``Setuptools`` provide powerful tools to handle package discovery, including ``Setuptools`` provide powerful tools to handle package discovery, including
...@@ -97,6 +97,8 @@ in ``src`` that starts with the name ``pkg`` and not ``additional``: ...@@ -97,6 +97,8 @@ in ``src`` that starts with the name ``pkg`` and not ``additional``:
) )
.. _Namespace Packages:
Using ``find_namespace:`` or ``find_namespace_packages`` Using ``find_namespace:`` or ``find_namespace_packages``
======================================================== ========================================================
``setuptools`` provides the ``find_namespace:`` (``find_namespace_packages``) ``setuptools`` provides the ``find_namespace:`` (``find_namespace_packages``)
......
docs/userguide/quickstart.rst
View file @ 490301f4
...@@ -21,8 +21,7 @@ the backend (build system) it wants to use. The distribution can then ...@@ -21,8 +21,7 @@ the backend (build system) it wants to use. The distribution can then
be generated with whatever tools that provides a ``build sdist``-alike be generated with whatever tools that provides a ``build sdist``-alike
functionality. While this may appear cumbersome, given the added pieces, functionality. While this may appear cumbersome, given the added pieces,
it in fact tremendously enhances the portability of your package. The 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/# change is driven under :pep:`517 <517#build-requirements>`. To learn more about Python packaging in general,
build-requirements>``. To learn more about Python packaging in general,
navigate to the `bottom <Resources on python packaging>`_ of this page. navigate to the `bottom <Resources on python packaging>`_ of this page.
...@@ -122,7 +121,7 @@ keyword in your ``setup.cfg``: ...@@ -122,7 +121,7 @@ keyword in your ``setup.cfg``:
When this project is installed, a ``main`` script will be installed and will 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. invoke the ``some_func`` in the ``__init__.py`` file when called by the user.
For detailed usage, including managing the additional or optional dependencies, For detailed usage, including managing the additional or optional dependencies,
go to :ref:`entry_point`. go to :doc:`entry_point`.
Dependency management Dependency management
...@@ -147,9 +146,11 @@ additional keywords such as ``setup_requires`` that allows you to install ...@@ -147,9 +146,11 @@ additional keywords such as ``setup_requires`` that allows you to install
dependencies before running the script, and ``extras_requires`` that take dependencies before running the script, and ``extras_requires`` that take
care of those needed by automatically generated scripts. It also provides care of those needed by automatically generated scripts. It also provides
mechanisms to handle dependencies that are not in PyPI. For more advanced use, mechanisms to handle dependencies that are not in PyPI. For more advanced use,
see :ref:`dependency_management` see :doc:`dependency_management`
.. _Including Data Files:
Including Data Files Including Data Files
==================== ====================
The distutils have traditionally allowed installation of "data files", which The distutils have traditionally allowed installation of "data files", which
...@@ -164,7 +165,7 @@ can simply use the ``include_package_data`` keyword: ...@@ -164,7 +165,7 @@ can simply use the ``include_package_data`` keyword:
This tells setuptools to install any data files it finds in your packages. 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. The data files must be specified via the distutils' ``MANIFEST.in`` file.
For more details, see :ref:`datafiles` For more details, see :doc:`datafiles`
Development mode Development mode
......
setup.cfg
View file @ 490301f4
...@@ -16,7 +16,7 @@ formats = zip ...@@ -16,7 +16,7 @@ formats = zip
[metadata] [metadata]
name = setuptools name = setuptools
version = 50.3.0 version = 50.3.1
description = Easily download, build, install, upgrade, and uninstall Python packages description = Easily download, build, install, upgrade, and uninstall Python packages
author = Python Packaging Authority author = Python Packaging Authority
author_email = distutils-sig@python.org author_email = distutils-sig@python.org
......
setuptools/command/build_py.py
View file @ 490301f4
...@@ -11,7 +11,7 @@ import stat ...@@ -11,7 +11,7 @@ import stat
try: try:
from setuptools.lib2to3_ex import Mixin2to3 from setuptools.lib2to3_ex import Mixin2to3
except ImportError: except Exception:
class Mixin2to3: class Mixin2to3:
def run_2to3(self, files, doctests=True): def run_2to3(self, files, doctests=True):
......
setuptools/command/egg_info.py
View file @ 490301f4
...@@ -123,12 +123,17 @@ class InfoCommon: ...@@ -123,12 +123,17 @@ class InfoCommon:
return safe_name(self.distribution.get_name()) return safe_name(self.distribution.get_name())
def tagged_version(self): def tagged_version(self):
version = self.distribution.get_version() return safe_version(self._maybe_tag(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. def _maybe_tag(self, version):
if self.vtags and version.endswith(self.vtags): """
return safe_version(version) egg_info may be called more than once for a distribution,
return safe_version(version + self.vtags) 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): def tags(self):
version = '' version = ''
......
tools/finalize.py
View file @ 490301f4
...@@ -66,10 +66,11 @@ def check_changes(): ...@@ -66,10 +66,11 @@ def check_changes():
names. names.
""" """
allowed = 'deprecation', 'breaking', 'change', 'doc', 'misc' allowed = 'deprecation', 'breaking', 'change', 'doc', 'misc'
except_ = 'README.rst', '.gitignore'
assert all( assert all(
any(key in file.name for key in allowed) any(key in file.name for key in allowed)
for file in pathlib.Path('changelog.d').iterdir() for file in pathlib.Path('changelog.d').iterdir()
if file.name != '.gitignore' if file.name not in except_
) )
......
tox.ini
View file @ 490301f4
...@@ -49,7 +49,16 @@ extras = ...@@ -49,7 +49,16 @@ extras =
testing testing
changedir = docs changedir = docs
commands = commands =
python -m sphinx . {toxinidir}/build/html {envpython} -m sphinx \
-j auto \
-b html \
--color \
-a \
-n \
-W \
-d "{temp_dir}/.doctrees" \
. \
"{toxinidir}/build/html"
[testenv:finalize] [testenv:finalize]
skip_install = True skip_install = True
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7