From 661ed478eb042398226e010596a6739927355da4 Mon Sep 17 00:00:00 2001 From: Jeremy Paige Date: Thu, 5 May 2022 09:44:03 -0700 Subject: [PATCH 01/12] Sync references keywords doc from userguide --- docs/references/keywords.rst | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index c26b9d497d..463e6e8bc5 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -223,11 +223,11 @@ Keywords A string or list of strings specifying what other distributions need to be present in order for the *setup script* to run. ``setuptools`` will - attempt to obtain these (even going so far as to download them using - ``EasyInstall``) before processing the rest of the setup script or commands. - This argument is needed if you are using distutils extensions as part of - your build process; for example, extensions that process setup() arguments - and turn them into EGG-INFO metadata files. + attempt to obtain these (using pip if available) before processing the + rest of the setup script or commands. This argument is needed if you + are using distutils extensions as part of your build process; for + example, extensions that process setup() arguments and turn them into + EGG-INFO metadata files. (Note: projects listed in ``setup_requires`` will NOT be automatically installed on the system where the setup script is being run. They are @@ -246,8 +246,7 @@ Keywords A list of strings naming URLs to be searched when satisfying dependencies. These links will be used if needed to install packages specified by ``setup_requires`` or ``tests_require``. They will also be written into - the egg's metadata for use by tools like EasyInstall to use when installing - an ``.egg`` file. + the egg's metadata for use during install by tools that support them. ``namespace_packages`` A list of strings naming the project's "namespace packages". A namespace @@ -270,9 +269,9 @@ Keywords added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite. - Specifying this argument enables use of the :ref:`test` command to run the + Specifying this argument enables use of the :ref:`test ` command to run the specified test suite, e.g. via ``setup.py test``. See the section on the - :ref:`test` command below for more details. + :ref:`test ` command below for more details. New in 41.5.0: Deprecated the test command. @@ -281,11 +280,10 @@ Keywords needed to install it, you can use this option to specify them. It should be a string or list of strings specifying what other distributions need to be present for the package's tests to run. When you run the ``test`` - command, ``setuptools`` will attempt to obtain these (even going - so far as to download them using ``EasyInstall``). Note that these - required projects will *not* be installed on the system where the tests - are run, but only downloaded to the project's setup directory if they're - not already installed locally. + command, ``setuptools`` will attempt to obtain these (using pip if + available). Note that these required projects will *not* be installed on + the system where the tests are run, but only downloaded to the project's setup + directory if they're not already installed locally. New in 41.5.0: Deprecated the test command. From 311c3795a5207e9cf88d647c8db1a222071ea4b4 Mon Sep 17 00:00:00 2001 From: Jeremy Paige Date: Thu, 5 May 2022 10:59:28 -0700 Subject: [PATCH 02/12] redirect userguide keywords to references keywords --- docs/userguide/keywords.rst | 262 ++++++++++++++---------------------- 1 file changed, 101 insertions(+), 161 deletions(-) diff --git a/docs/userguide/keywords.rst b/docs/userguide/keywords.rst index 5388ffea7f..94d14b097c 100644 --- a/docs/userguide/keywords.rst +++ b/docs/userguide/keywords.rst @@ -1,163 +1,103 @@ -New and Changed ``setup()`` Keywords +``setup()`` Keywords ==================================== -The following keyword arguments to ``setup()`` are added or changed by -``setuptools``. All of them are optional; you do not have to supply them -unless you need the associated ``setuptools`` feature. - -``include_package_data`` - If set to ``True``, this tells ``setuptools`` to automatically include any - data files it finds inside your package directories that are specified by - your ``MANIFEST.in`` file. For more information, see the section on - :ref:`Including Data Files`. - -``exclude_package_data`` - A dictionary mapping package names to lists of glob patterns that should - be *excluded* from your package directories. You can use this to trim back - any excess files included by ``include_package_data``. For a complete - description and examples, see the section on :ref:`Including Data Files`. - -``package_data`` - A dictionary mapping package names to lists of glob patterns. For a - complete description and examples, see the section on :ref:`Including - Data Files`. You do not need to use this option if you are using - ``include_package_data``, unless you need to add e.g. files that are - generated by your setup script and build process. (And are therefore not - in source control or are files that you don't want to include in your - source distribution.) - -``zip_safe`` - A boolean (True or False) flag specifying whether the project can be - safely installed and run from a zip file. If this argument is not - supplied, the ``bdist_egg`` command will have to analyze all of your - project's contents for possible problems each time it builds an egg. - -``install_requires`` - A string or list of strings specifying what other distributions need to - be installed when this one is. See the section on :ref:`Declaring - Dependencies` for details and examples of the format of this argument. - -``entry_points`` - A dictionary mapping entry point group names to strings or lists of strings - defining the entry points. Entry points are used to support dynamic - discovery of services or plugins provided by a project. See :ref:`Dynamic - Discovery of Services and Plugins` for details and examples of the format - of this argument. In addition, this keyword is used to support - :ref:`Automatic Script Creation `. - -``extras_require`` - A dictionary mapping names of "extras" (optional features of your project) - to strings or lists of strings specifying what other distributions must be - installed to support those features. See the section on :ref:`Declaring - Dependencies` for details and examples of the format of this argument. - -``python_requires`` - A string corresponding to a version specifier (as defined in PEP 440) for - the Python version, used to specify the Requires-Python defined in PEP 345. - -``setup_requires`` - A string or list of strings specifying what other distributions need to - be present in order for the *setup script* to run. ``setuptools`` will - attempt to obtain these (using pip if available) before processing the - rest of the setup script or commands. This argument is needed if you - are using distutils extensions as part of your build process; for - example, extensions that process setup() arguments and turn them into - EGG-INFO metadata files. - - (Note: projects listed in ``setup_requires`` will NOT be automatically - installed on the system where the setup script is being run. They are - simply downloaded to the ./.eggs directory if they're not locally available - already. If you want them to be installed, as well as being available - when the setup script is run, you should add them to ``install_requires`` - **and** ``setup_requires``.) - -``dependency_links`` - A list of strings naming URLs to be searched when satisfying dependencies. - These links will be used if needed to install packages specified by - ``setup_requires`` or ``tests_require``. They will also be written into - the egg's metadata for use during install by tools that support them. - -``namespace_packages`` - A list of strings naming the project's "namespace packages". A namespace - package is a package that may be split across multiple project - distributions. For example, Zope 3's ``zope`` package is a namespace - package, because subpackages like ``zope.interface`` and ``zope.publisher`` - may be distributed separately. The egg runtime system can automatically - merge such subpackages into a single parent package at runtime, as long - as you declare them in each project that contains any subpackages of the - namespace package, and as long as the namespace package's ``__init__.py`` - does not contain any code other than a namespace declaration. See the - section below on :ref:`Namespace Packages` for more information. - -``test_suite`` - A string naming a ``unittest.TestCase`` subclass (or a package or module - containing one or more of them, or a method of such a subclass), or naming - a function that can be called with no arguments and returns a - ``unittest.TestSuite``. If the named suite is a module, and the module - has an ``additional_tests()`` function, it is called and the results are - added to the tests to be run. If the named suite is a package, any - submodules and subpackages are recursively added to the overall test suite. - - Specifying this argument enables use of the :ref:`test ` command to run the - specified test suite, e.g. via ``setup.py test``. See the section on the - :ref:`test ` command below for more details. - - New in 41.5.0: Deprecated the test command. - -``tests_require`` - If your project's tests need one or more additional packages besides those - needed to install it, you can use this option to specify them. It should - be a string or list of strings specifying what other distributions need to - be present for the package's tests to run. When you run the ``test`` - command, ``setuptools`` will attempt to obtain these (using pip if - available). Note that these required projects will *not* be installed on - the system where the tests are run, but only downloaded to the project's setup - directory if they're not already installed locally. - - New in 41.5.0: Deprecated the test command. - -.. _test_loader: - -``test_loader`` - If you would like to use a different way of finding tests to run than what - setuptools normally uses, you can specify a module name and class name in - this argument. The named class must be instantiable with no arguments, and - its instances must support the ``loadTestsFromNames()`` method as defined - in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will - pass only one test "name" in the ``names`` argument: the value supplied for - the ``test_suite`` argument. The loader you specify may interpret this - string in any way it likes, as there are no restrictions on what may be - contained in a ``test_suite`` string. - - The module name and class name must be separated by a ``:``. The default - value of this argument is ``"setuptools.command.test:ScanningLoader"``. If - you want to use the default ``unittest`` behavior, you can specify - ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This - will prevent automatic scanning of submodules and subpackages. - - The module and class you specify here may be contained in another package, - as long as you use the ``tests_require`` option to ensure that the package - containing the loader class is available when the ``test`` command is run. - - New in 41.5.0: Deprecated the test command. - -``eager_resources`` - A list of strings naming resources that should be extracted together, if - any of them is needed, or if any C extensions included in the project are - imported. This argument is only useful if the project will be installed as - a zipfile, and there is a need to have all of the listed resources be - extracted to the filesystem *as a unit*. Resources listed here - should be "/"-separated paths, relative to the source root, so to list a - resource ``foo.png`` in package ``bar.baz``, you would include the string - ``bar/baz/foo.png`` in this argument. - - If you only need to obtain resources one at a time, or you don't have any C - extensions that access other files in the project (such as data files or - shared libraries), you probably do NOT need this argument and shouldn't - mess with it. For more details on how this argument works, see the section - below on :ref:`Automatic Resource Extraction`. - -``project_urls`` - An arbitrary map of URL names to hyperlinks, allowing more extensible - documentation of where various resources can be found than the simple - ``url`` and ``download_url`` options provide. +The following are keywords ``setup()`` accepts. All of them are optional; you +do not have to supply them unless you need the associated ``setuptools`` +feature. For a complete description of what each argument does see the +:doc:`full keywords reference `. + +``name`` string + +``version`` string + +``description`` string + +``long_description`` string + +``long_description_content_type`` string + +``author`` string + +``author_email`` string + +``maintainer`` string + +``maintainer_email`` string + +``url`` string + +``download_url`` string + +``packages`` list + +``py_modules`` list + +``scripts`` list + +``ext_package`` string + +``ext_modules`` list + +``classifiers`` list + +``distclass`` Distribution subclass + +``script_name`` string + +``script_args`` list + +``options`` dictionary + +``license`` string + +``license_file`` string **deprecated** + +``license_files`` list + +``keywords`` string or list + +``platforms`` list + +``cmdclass`` dictionary + +``data_files`` list **deprecated** + +``package_dir`` dictionary + +``requires`` string or list **deprecated** + +``obsoletes`` list **deprecated** + +``provides`` list + +``include_package_data`` bool + +``exclude_package_data`` dictionary + +``package_data`` dictionary + +``zip_safe`` bool + +``install_requires`` string or list + +``entry_points`` dictionary + +``extras_require`` dictionary + +``python_requires`` string + +``setup_requires`` string or list **deprecated** + +``dependency_links`` list **deprecated** + +``namespace_packages`` list + +``test_suite`` string or function **deprecated** + +``tests_require`` string or list **deprecated** + +``test_loader`` class **deprecated** + +``eager_resources`` list + +``project_urls`` dictionary From 88e578445bdc18a0612a8b5980b5ed10d8476a8b Mon Sep 17 00:00:00 2001 From: Jeremy Paige Date: Thu, 5 May 2022 11:16:58 -0700 Subject: [PATCH 03/12] add changelog --- changelog.d/3307.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/3307.doc.rst diff --git a/changelog.d/3307.doc.rst b/changelog.d/3307.doc.rst new file mode 100644 index 0000000000..5f9c2d727f --- /dev/null +++ b/changelog.d/3307.doc.rst @@ -0,0 +1 @@ +Linked the userguide keywords documentation to the more complete references keywords documentation From 67126f0735cecd1e5439b057f5cc8defa07f3215 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 10:30:18 +0100 Subject: [PATCH 04/12] Avoid mentioning that pip is used for download It seems that setuptools currently uses its own mechanism for downloading dependencies (setuptools/package_index.py). --- docs/references/keywords.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 463e6e8bc5..f0527859be 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -223,7 +223,7 @@ Keywords A string or list of strings specifying what other distributions need to be present in order for the *setup script* to run. ``setuptools`` will - attempt to obtain these (using pip if available) before processing the + attempt to obtain these before processing the rest of the setup script or commands. This argument is needed if you are using distutils extensions as part of your build process; for example, extensions that process setup() arguments and turn them into @@ -280,8 +280,8 @@ Keywords needed to install it, you can use this option to specify them. It should be a string or list of strings specifying what other distributions need to be present for the package's tests to run. When you run the ``test`` - command, ``setuptools`` will attempt to obtain these (using pip if - available). Note that these required projects will *not* be installed on + command, ``setuptools`` will attempt to obtain these. + Note that these required projects will *not* be installed on the system where the tests are run, but only downloaded to the project's setup directory if they're not already installed locally. From d41e298828176bcb661077102a1d82ac418fb181 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 10:38:21 +0100 Subject: [PATCH 05/12] Add markup to highlight deprecation of test-related keywords --- docs/references/keywords.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index f0527859be..a9a53c9e2f 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -273,7 +273,10 @@ Keywords specified test suite, e.g. via ``setup.py test``. See the section on the :ref:`test ` command below for more details. - New in 41.5.0: Deprecated the test command. + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. ``tests_require`` If your project's tests need one or more additional packages besides those @@ -285,7 +288,10 @@ Keywords the system where the tests are run, but only downloaded to the project's setup directory if they're not already installed locally. - New in 41.5.0: Deprecated the test command. + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. .. _test_loader: @@ -310,7 +316,10 @@ Keywords as long as you use the ``tests_require`` option to ensure that the package containing the loader class is available when the ``test`` command is run. - New in 41.5.0: Deprecated the test command. + .. warning:: + .. deprecated:: 41.5.0 + The test command will be removed in a future version of ``setuptools``, + alongside any test configuration parameter. ``eager_resources`` A list of strings naming resources that should be extracted together, if From 4561ddadfbdbd97fc028005f40376e295f67af52 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 10:41:28 +0100 Subject: [PATCH 06/12] Fix markup on keywords documentation Due to extra new lines some entries were interpreted by the rst parser as quoted blocks. This change fixes that. --- docs/references/keywords.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index a9a53c9e2f..990653e51e 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -77,12 +77,10 @@ Keywords A string specifying the license of the package. ``license_file`` - .. warning:: ``license_file`` is deprecated. Use ``license_files`` instead. ``license_files`` - A list of glob patterns for license related files that should be included. If neither ``license_file`` nor ``license_files`` is specified, this option defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``. @@ -101,7 +99,6 @@ Keywords subclasses. ``data_files`` - .. warning:: ``data_files`` is deprecated. It does not work with wheels, so it should be avoided. @@ -112,13 +109,11 @@ Keywords A dictionary providing a mapping of package to directory names. ``requires`` - .. warning:: ``requires`` is superseded by ``install_requires`` and should not be used anymore. ``obsoletes`` - .. warning:: ``obsoletes`` is currently ignored by ``pip``. @@ -136,7 +131,6 @@ Keywords Torqued Python, the Gorgon distribution should be removed. ``provides`` - .. warning:: ``provides`` is currently ignored by ``pip``. @@ -217,7 +211,6 @@ Keywords the Python version, used to specify the Requires-Python defined in PEP 345. ``setup_requires`` - .. warning:: Using ``setup_requires`` is discouraged in favor of `PEP-518`_ @@ -239,7 +232,6 @@ Keywords .. _PEP-518: http://www.python.org/dev/peps/pep-0518/ ``dependency_links`` - .. warning:: ``dependency_links`` is deprecated. It is not supported anymore by pip. From b06270e4f41d10e61cd5838e5a92184adb72d30e Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 11:22:22 +0100 Subject: [PATCH 07/12] Add introduction text to keywords docs --- docs/references/keywords.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 990653e51e..38c5b26d45 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -2,6 +2,36 @@ Keywords ======== +The following are keywords ``setuptools.setup()`` accepts. +They allow configuring the build process for a Python distribution or adding +metadata via a ``setup.py`` script placed at the root of your project. +All of them are optional; you do not have to supply them unless you need the +associated ``setuptools`` feature. + +Metadata and configuration supplied via ``setup()`` is complementary to (and +may be overwritten by) the information present in ``setup.cfg`` and ``pyproject.toml``. +Some important metadata, such as ``name`` and ``version``, may assume +a default *degenerate* value if not specified. + +Users are strongly encouraged to use a declarative config either via +:doc:`setup.cfg ` or :doc:`pyproject.toml +` and only rely on ``setup.py`` if they need to +tap into special behaviour that requires scripting (such as building C +extensions). + +.. note:: + When using declarative configs via ``pyproject.toml`` users can still keep a + very simple ``setup.py`` just to ensure editable installs are supported, for + example:: + + from setuptools import setup + + setup() + + Future versions of ``setuptools`` may support editable installs even + without ``setup.py``. + + ``name`` A string specifying the name of the package. From 0487627353982981dbaf855ab8a7b31e8771a0a7 Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 11:51:58 +0100 Subject: [PATCH 08/12] Add anchors for keywords in docs. This way we can reference them. --- docs/references/keywords.rst | 98 +++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 2 deletions(-) diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index 38c5b26d45..fcc77970a2 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -32,102 +32,158 @@ extensions). without ``setup.py``. +.. _keyword/name: + ``name`` A string specifying the name of the package. +.. _keyword/version: + ``version`` A string specifying the version number of the package. +.. _keyword/description: + ``description`` A string describing the package in a single line. +.. _keyword/long_description: + ``long_description`` A string providing a longer description of the package. +.. _keyword/long_description_content_type: + ``long_description_content_type`` A string specifying the content type is used for the ``long_description`` (e.g. ``text/markdown``) +.. _keyword/author: + ``author`` A string specifying the author of the package. +.. _keyword/author_email: + ``author_email`` A string specifying the email address of the package author. +.. _keyword/maintainer: + ``maintainer`` A string specifying the name of the current maintainer, if different from the author. Note that if the maintainer is provided, setuptools will use it as the author in ``PKG-INFO``. +.. _keyword/maintainer_email: + ``maintainer_email`` A string specifying the email address of the current maintainer, if different from the author. +.. _keyword/url: + ``url`` A string specifying the URL for the package homepage. +.. _keyword/download_url: + ``download_url`` A string specifying the URL to download the package. +.. _keyword/packages: + ``packages`` A list of strings specifying the packages that setuptools will manipulate. +.. _keyword/py_modules: + ``py_modules`` A list of strings specifying the modules that setuptools will manipulate. +.. _keyword/scripts: + ``scripts`` A list of strings specifying the standalone script files to be built and installed. +.. _keyword/ext_package: + ``ext_package`` A string specifying the base package name for the extensions provided by this package. +.. _keyword/ext_modules: + ``ext_modules`` A list of instances of ``setuptools.Extension`` providing the list of Python extensions to be built. +.. _keyword/classifiers: + ``classifiers`` A list of strings describing the categories for the package. +.. _keyword/distclass: + ``distclass`` A subclass of ``Distribution`` to use. +.. _keyword/script_name: + ``script_name`` A string specifying the name of the setup.py script -- defaults to ``sys.argv[0]`` +.. _keyword/script_args: + ``script_args`` A list of strings defining the arguments to supply to the setup script. +.. _keyword/options: + ``options`` A dictionary providing the default options for the setup script. +.. _keyword/license: + ``license`` A string specifying the license of the package. +.. _keyword/license_file: + ``license_file`` .. warning:: ``license_file`` is deprecated. Use ``license_files`` instead. +.. _keyword/license_files: + ``license_files`` A list of glob patterns for license related files that should be included. If neither ``license_file`` nor ``license_files`` is specified, this option defaults to ``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*``, and ``AUTHORS*``. +.. _keyword/keywords: + ``keywords`` A list of strings or a comma-separated string providing descriptive meta-data. See: `PEP 0314`_. .. _PEP 0314: https://www.python.org/dev/peps/pep-0314/ +.. _keyword/platforms: + ``platforms`` A list of strings or comma-separated string. +.. _keyword/cmdclass: + ``cmdclass`` A dictionary providing a mapping of command names to ``Command`` subclasses. +.. _keyword/data_files: + ``data_files`` .. warning:: ``data_files`` is deprecated. It does not work with wheels, so it @@ -135,14 +191,20 @@ extensions). A list of strings specifying the data files to install. +.. _keyword/package_dir: + ``package_dir`` A dictionary providing a mapping of package to directory names. +.. _keyword/requires: + ``requires`` .. warning:: ``requires`` is superseded by ``install_requires`` and should not be used anymore. +.. _keyword/obsoletes: + ``obsoletes`` .. warning:: ``obsoletes`` is currently ignored by ``pip``. @@ -160,6 +222,8 @@ extensions). e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install Torqued Python, the Gorgon distribution should be removed. +.. _keyword/provides: + ``provides`` .. warning:: ``provides`` is currently ignored by ``pip``. @@ -190,18 +254,24 @@ extensions). .. Below are setuptools keywords, above are distutils +.. _keyword/include_package_data: + ``include_package_data`` If set to ``True``, this tells ``setuptools`` to automatically include any data files it finds inside your package directories that are specified by your ``MANIFEST.in`` file. For more information, see the section on :ref:`Including Data Files`. +.. _keyword/exclude_package_data: + ``exclude_package_data`` A dictionary mapping package names to lists of glob patterns that should be *excluded* from your package directories. You can use this to trim back any excess files included by ``include_package_data``. For a complete description and examples, see the section on :ref:`Including Data Files`. +.. _keyword/package_data: + ``package_data`` A dictionary mapping package names to lists of glob patterns. For a complete description and examples, see the section on :ref:`Including Data @@ -211,17 +281,23 @@ extensions). in source control or are files that you don't want to include in your source distribution.) +.. _keyword/zip_safe: + ``zip_safe`` A boolean (True or False) flag specifying whether the project can be safely installed and run from a zip file. If this argument is not supplied, the ``bdist_egg`` command will have to analyze all of your project's contents for possible problems each time it builds an egg. +.. _keyword/install_requires: + ``install_requires`` A string or list of strings specifying what other distributions need to be installed when this one is. See the section on :ref:`Declaring Dependencies` for details and examples of the format of this argument. +.. _keyword/entry_points: + ``entry_points`` A dictionary mapping entry point group names to strings or lists of strings defining the entry points. Entry points are used to support dynamic @@ -230,19 +306,25 @@ extensions). of this argument. In addition, this keyword is used to support :ref:`Automatic Script Creation `. +.. _keyword/extras_require: + ``extras_require`` A dictionary mapping names of "extras" (optional features of your project) to strings or lists of strings specifying what other distributions must be installed to support those features. See the section on :ref:`Declaring Dependencies` for details and examples of the format of this argument. +.. _keyword/python_requires: + ``python_requires`` A string corresponding to a version specifier (as defined in PEP 440) for the Python version, used to specify the Requires-Python defined in PEP 345. +.. _keyword/setup_requires: + ``setup_requires`` .. warning:: - Using ``setup_requires`` is discouraged in favor of `PEP-518`_ + Using ``setup_requires`` is discouraged in favor of :pep:`518`. A string or list of strings specifying what other distributions need to be present in order for the *setup script* to run. ``setuptools`` will @@ -259,7 +341,7 @@ extensions). when the setup script is run, you should add them to ``install_requires`` **and** ``setup_requires``.) -.. _PEP-518: http://www.python.org/dev/peps/pep-0518/ +.. _keyword/dependency_links: ``dependency_links`` .. warning:: @@ -270,6 +352,8 @@ extensions). ``setup_requires`` or ``tests_require``. They will also be written into the egg's metadata for use during install by tools that support them. +.. _keyword/namespace_packages: + ``namespace_packages`` A list of strings naming the project's "namespace packages". A namespace package is a package that may be split across multiple project @@ -282,6 +366,8 @@ extensions). does not contain any code other than a namespace declaration. See the section on :ref:`Namespace Packages` for more information. +.. _keyword/test_suite: + ``test_suite`` A string naming a ``unittest.TestCase`` subclass (or a package or module containing one or more of them, or a method of such a subclass), or naming @@ -300,6 +386,8 @@ extensions). The test command will be removed in a future version of ``setuptools``, alongside any test configuration parameter. +.. _keyword/tests_require: + ``tests_require`` If your project's tests need one or more additional packages besides those needed to install it, you can use this option to specify them. It should @@ -317,6 +405,8 @@ extensions). .. _test_loader: +.. _keyword/test_loader: + ``test_loader`` If you would like to use a different way of finding tests to run than what setuptools normally uses, you can specify a module name and class name in @@ -343,6 +433,8 @@ extensions). The test command will be removed in a future version of ``setuptools``, alongside any test configuration parameter. +.. _keyword/eager_resources: + ``eager_resources`` A list of strings naming resources that should be extracted together, if any of them is needed, or if any C extensions included in the project are @@ -359,6 +451,8 @@ extensions). mess with it. For more details on how this argument works, see the section below on :ref:`Automatic Resource Extraction`. +.. _keyword/project_urls: + ``project_urls`` An arbitrary map of URL names to hyperlinks, allowing more extensible documentation of where various resources can be found than the simple From 3a6b7be2b5e13e279c23ced23b750eb1033b968a Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 12:19:37 +0100 Subject: [PATCH 09/12] Make the separation between distutils and setuptools keywords more clear The biggest value of retaining the `userguide/keywords` document is to retain information about which keywords have changed. Therefore it makes sense to preserve (and highlight) that information. --- docs/userguide/keywords.rst | 115 +++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 53 deletions(-) diff --git a/docs/userguide/keywords.rst b/docs/userguide/keywords.rst index 94d14b097c..ba9a0df5f2 100644 --- a/docs/userguide/keywords.rst +++ b/docs/userguide/keywords.rst @@ -1,103 +1,112 @@ -``setup()`` Keywords +New and Changed ``setup()`` Keywords ==================================== -The following are keywords ``setup()`` accepts. All of them are optional; you -do not have to supply them unless you need the associated ``setuptools`` -feature. For a complete description of what each argument does see the -:doc:`full keywords reference `. +This document tracks historical differences between ``setuptools`` and +``distutils``. -``name`` string +Since ``distutils`` was scheduled for removal from the standard library in +Python 3.12, and ``setuptools`` started its adoption, these differences became less +relevant. +Please check :doc:`/references/keywords` for a complete list of keyword +arguments that can be passed to the ``setuptools.setup()`` function and +a their complete description. -``version`` string +.. tab:: Supported by both ``distutils`` and ``setuptoools`` -``description`` string + ``name`` string -``long_description`` string + ``version`` string -``long_description_content_type`` string + ``description`` string -``author`` string + ``long_description`` string -``author_email`` string + ``long_description_content_type`` string -``maintainer`` string + ``author`` string -``maintainer_email`` string + ``author_email`` string -``url`` string + ``maintainer`` string -``download_url`` string + ``maintainer_email`` string -``packages`` list + ``url`` string -``py_modules`` list + ``download_url`` string -``scripts`` list + ``packages`` list -``ext_package`` string + ``py_modules`` list -``ext_modules`` list + ``scripts`` list -``classifiers`` list + ``ext_package`` string -``distclass`` Distribution subclass + ``ext_modules`` list -``script_name`` string + ``classifiers`` list -``script_args`` list + ``distclass`` Distribution subclass -``options`` dictionary + ``script_name`` string -``license`` string + ``script_args`` list -``license_file`` string **deprecated** + ``options`` dictionary -``license_files`` list + ``license`` string -``keywords`` string or list + ``license_file`` string **deprecated** -``platforms`` list + ``license_files`` list -``cmdclass`` dictionary + ``keywords`` string or list -``data_files`` list **deprecated** + ``platforms`` list -``package_dir`` dictionary + ``cmdclass`` dictionary -``requires`` string or list **deprecated** + ``data_files`` list **deprecated** -``obsoletes`` list **deprecated** + ``package_dir`` dictionary -``provides`` list + ``requires`` string or list **deprecated** -``include_package_data`` bool + ``obsoletes`` list **deprecated** -``exclude_package_data`` dictionary + ``provides`` list -``package_data`` dictionary +.. tab:: Added or changed by ``setuptoools`` -``zip_safe`` bool + ``include_package_data`` bool -``install_requires`` string or list + ``exclude_package_data`` dictionary -``entry_points`` dictionary + ``package_data`` dictionary -``extras_require`` dictionary + ``zip_safe`` bool -``python_requires`` string + ``install_requires`` string or list -``setup_requires`` string or list **deprecated** + ``entry_points`` dictionary -``dependency_links`` list **deprecated** + ``extras_require`` dictionary -``namespace_packages`` list + ``python_requires`` string -``test_suite`` string or function **deprecated** + ``setup_requires`` string or list **deprecated** -``tests_require`` string or list **deprecated** + ``dependency_links`` list **deprecated** -``test_loader`` class **deprecated** + ``namespace_packages`` list -``eager_resources`` list + ``test_suite`` string or function **deprecated** -``project_urls`` dictionary + ``tests_require`` string or list **deprecated** + + ``test_loader`` class **deprecated** + + ``eager_resources`` list + + ``project_urls`` dictionary From 094809b515b38940a8cd015633d815ec0f18b83d Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 12:46:54 +0100 Subject: [PATCH 10/12] Move userguide/keywords to deprecated/changed_keyworkds --- docs/conf.py | 6 ++++++ .../keywords.rst => deprecated/changed_keywords.rst} | 0 docs/deprecated/index.rst | 1 + docs/userguide/index.rst | 1 - docs/userguide/package_discovery.rst | 2 +- setup.cfg | 1 + 6 files changed, 9 insertions(+), 2 deletions(-) rename docs/{userguide/keywords.rst => deprecated/changed_keywords.rst} (100%) diff --git a/docs/conf.py b/docs/conf.py index 4ebb521cf6..1023539c62 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -129,6 +129,12 @@ }, } +# Redirect old docs so links and references in the ecosystem don't break +extensions += ['sphinx_reredirects'] +redirects = { + "userguide/keywords": "/deprecated/changed_keywords.html", +} + # Add support for inline tabs extensions += ['sphinx_inline_tabs'] diff --git a/docs/userguide/keywords.rst b/docs/deprecated/changed_keywords.rst similarity index 100% rename from docs/userguide/keywords.rst rename to docs/deprecated/changed_keywords.rst diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index 59fc7befd0..8169b3b70c 100644 --- a/docs/deprecated/index.rst +++ b/docs/deprecated/index.rst @@ -13,6 +13,7 @@ objectives. .. toctree:: :maxdepth: 1 + changed_keywords python_eggs easy_install distutils/index diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index 49655acdd0..74e9b1e4ce 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -32,7 +32,6 @@ quickstart provides an overview of the new workflow. extension declarative_config pyproject_config - keywords commands functionalities_rewrite miscellaneous diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 38119bc6fa..0854a709b8 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -6,7 +6,7 @@ Package Discovery and Namespace Package .. note:: a full specification for the keyword supplied to ``setup.cfg`` or - ``setup.py`` can be found at :doc:`keywords reference ` + ``setup.py`` can be found at :doc:`keywords reference ` .. note:: the examples provided here are only to demonstrate the functionality diff --git a/setup.cfg b/setup.cfg index 4b386243a4..158919e55c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -93,6 +93,7 @@ docs = pygments-github-lexers==0.0.5 sphinx-favicon sphinx-inline-tabs + sphinx-reredirects sphinxcontrib-towncrier furo From 1b8961fe3a3d214a3375eba3a50bc83bb36a69cc Mon Sep 17 00:00:00 2001 From: Anderson Bravalheri Date: Fri, 6 May 2022 13:05:50 +0100 Subject: [PATCH 11/12] Update docs/deprecated/changed_keywords.rst --- docs/deprecated/changed_keywords.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deprecated/changed_keywords.rst b/docs/deprecated/changed_keywords.rst index ba9a0df5f2..7db372f2fe 100644 --- a/docs/deprecated/changed_keywords.rst +++ b/docs/deprecated/changed_keywords.rst @@ -9,7 +9,7 @@ Python 3.12, and ``setuptools`` started its adoption, these differences became l relevant. Please check :doc:`/references/keywords` for a complete list of keyword arguments that can be passed to the ``setuptools.setup()`` function and -a their complete description. +a their full description. .. tab:: Supported by both ``distutils`` and ``setuptoools`` From 63d16710e7a698a10470436b6c786306c8afb580 Mon Sep 17 00:00:00 2001 From: Jeremy Paige Date: Fri, 6 May 2022 09:58:49 -0700 Subject: [PATCH 12/12] update changelog to cover new chagnes --- changelog.d/3307.doc.rst | 5 ++++- docs/references/keywords.rst | 2 -- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/changelog.d/3307.doc.rst b/changelog.d/3307.doc.rst index 5f9c2d727f..cdab873785 100644 --- a/changelog.d/3307.doc.rst +++ b/changelog.d/3307.doc.rst @@ -1 +1,4 @@ -Linked the userguide keywords documentation to the more complete references keywords documentation +Added introduction to references/keywords +Added deprecation tags to test kwargs +Moved userguide/keywords to deprecated section +Clarified in deprecated doc what keywords came from distutils and which were added or changed by setuptools diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst index fcc77970a2..f231b2b8ee 100644 --- a/docs/references/keywords.rst +++ b/docs/references/keywords.rst @@ -252,8 +252,6 @@ extensions). Each package may be followed by an environment marker after a semicolon (e.g. ``foo; os_name == "posix"``). -.. Below are setuptools keywords, above are distutils - .. _keyword/include_package_data: ``include_package_data``