From d307b46c898fa5ee902344dab7ecc6e8ed595987 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 09:23:51 +0200 Subject: Moved keywords section into separate document, added link in index --- docs/index.txt | 1 + docs/keywords.txt | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/setuptools.txt | 173 ---------------------------------------------------- 3 files changed, 173 insertions(+), 173 deletions(-) create mode 100644 docs/keywords.txt diff --git a/docs/index.txt b/docs/index.txt index 13a46e74..60c4f331 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -17,6 +17,7 @@ Documentation content: :maxdepth: 2 setuptools + keywords pkg_resources python3 development diff --git a/docs/keywords.txt b/docs/keywords.txt new file mode 100644 index 00000000..a1097aca --- /dev/null +++ b/docs/keywords.txt @@ -0,0 +1,172 @@ +============================== +Supported ``setup()`` Keywords +============================== + +The following keyword arguments to ``setup()`` are supported by ``setuptools``. +All of them are optional; you do not have to supply them unless you need the +associated ``setuptools`` feature. + +``include_package_data`` + If set to ``True``, this tells ``setuptools`` to automatically include any + data files it finds inside your package directories that are specified by + your ``MANIFEST.in`` file. For more information, see the section below on + `Including Data Files`_. + +``exclude_package_data`` + A dictionary mapping package names to lists of glob patterns that should + be *excluded* from your package directories. You can use this to trim back + any excess files included by ``include_package_data``. For a complete + description and examples, see the section below on `Including Data Files`_. + +``package_data`` + A dictionary mapping package names to lists of glob patterns. For a + complete description and examples, see the section below on `Including + Data Files`_. You do not need to use this option if you are using + ``include_package_data``, unless you need to add e.g. files that are + generated by your setup script and build process. (And are therefore not + in source control or are files that you don't want to include in your + source distribution.) + +``zip_safe`` + A boolean (True or False) flag specifying whether the project can be + safely installed and run from a zip file. If this argument is not + supplied, the ``bdist_egg`` command will have to analyze all of your + project's contents for possible problems each time it builds an egg. + +``install_requires`` + A string or list of strings specifying what other distributions need to + be installed when this one is. See the section below on `Declaring + Dependencies`_ for details and examples of the format of this argument. + +``entry_points`` + A dictionary mapping entry point group names to strings or lists of strings + defining the entry points. Entry points are used to support dynamic + discovery of services or plugins provided by a project. See `Dynamic + Discovery of Services and Plugins`_ for details and examples of the format + of this argument. In addition, this keyword is used to support `Automatic + Script Creation`_. + +``extras_require`` + A dictionary mapping names of "extras" (optional features of your project) + to strings or lists of strings specifying what other distributions must be + installed to support those features. See the section below on `Declaring + Dependencies`_ for details and examples of the format of this argument. + +``python_requires`` + A string corresponding to a version specifier (as defined in PEP 440) for + the Python version, used to specify the Requires-Python defined in PEP 345. + +``setup_requires`` + A string or list of strings specifying what other distributions need to + be present in order for the *setup script* to run. ``setuptools`` will + attempt to obtain these (even going so far as to download them using + ``EasyInstall``) before processing the rest of the setup script or commands. + This argument is needed if you are using distutils extensions as part of + your build process; for example, extensions that process setup() arguments + and turn them into EGG-INFO metadata files. + + (Note: projects listed in ``setup_requires`` will NOT be automatically + installed on the system where the setup script is being run. They are + simply downloaded to the ./.eggs directory if they're not locally available + already. If you want them to be installed, as well as being available + when the setup script is run, you should add them to ``install_requires`` + **and** ``setup_requires``.) + +``dependency_links`` + A list of strings naming URLs to be searched when satisfying dependencies. + These links will be used if needed to install packages specified by + ``setup_requires`` or ``tests_require``. They will also be written into + the egg's metadata for use by tools like EasyInstall to use when installing + an ``.egg`` file. + +``namespace_packages`` + A list of strings naming the project's "namespace packages". A namespace + package is a package that may be split across multiple project + distributions. For example, Zope 3's ``zope`` package is a namespace + package, because subpackages like ``zope.interface`` and ``zope.publisher`` + may be distributed separately. The egg runtime system can automatically + merge such subpackages into a single parent package at runtime, as long + as you declare them in each project that contains any subpackages of the + namespace package, and as long as the namespace package's ``__init__.py`` + does not contain any code other than a namespace declaration. See the + section below on `Namespace Packages`_ for more information. + +``test_suite`` + A string naming a ``unittest.TestCase`` subclass (or a package or module + containing one or more of them, or a method of such a subclass), or naming + a function that can be called with no arguments and returns a + ``unittest.TestSuite``. If the named suite is a module, and the module + has an ``additional_tests()`` function, it is called and the results are + added to the tests to be run. If the named suite is a package, any + submodules and subpackages are recursively added to the overall test suite. + + Specifying this argument enables use of the `test`_ command to run the + specified test suite, e.g. via ``setup.py test``. See the section on the + `test`_ command below for more details. + +``tests_require`` + If your project's tests need one or more additional packages besides those + needed to install it, you can use this option to specify them. It should + be a string or list of strings specifying what other distributions need to + be present for the package's tests to run. When you run the ``test`` + command, ``setuptools`` will attempt to obtain these (even going + so far as to download them using ``EasyInstall``). Note that these + required projects will *not* be installed on the system where the tests + are run, but only downloaded to the project's setup directory if they're + not already installed locally. + +.. _test_loader: + +``test_loader`` + If you would like to use a different way of finding tests to run than what + setuptools normally uses, you can specify a module name and class name in + this argument. The named class must be instantiable with no arguments, and + its instances must support the ``loadTestsFromNames()`` method as defined + in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will + pass only one test "name" in the `names` argument: the value supplied for + the ``test_suite`` argument. The loader you specify may interpret this + string in any way it likes, as there are no restrictions on what may be + contained in a ``test_suite`` string. + + The module name and class name must be separated by a ``:``. The default + value of this argument is ``"setuptools.command.test:ScanningLoader"``. If + you want to use the default ``unittest`` behavior, you can specify + ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This + will prevent automatic scanning of submodules and subpackages. + + The module and class you specify here may be contained in another package, + as long as you use the ``tests_require`` option to ensure that the package + containing the loader class is available when the ``test`` command is run. + +``eager_resources`` + A list of strings naming resources that should be extracted together, if + any of them is needed, or if any C extensions included in the project are + imported. This argument is only useful if the project will be installed as + a zipfile, and there is a need to have all of the listed resources be + extracted to the filesystem *as a unit*. Resources listed here + should be '/'-separated paths, relative to the source root, so to list a + resource ``foo.png`` in package ``bar.baz``, you would include the string + ``bar/baz/foo.png`` in this argument. + + If you only need to obtain resources one at a time, or you don't have any C + extensions that access other files in the project (such as data files or + shared libraries), you probably do NOT need this argument and shouldn't + mess with it. For more details on how this argument works, see the section + below on `Automatic Resource Extraction`_. + +``use_2to3`` + Convert the source code from Python 2 to Python 3 with 2to3 during the + build process. See :doc:`python3` for more details. + +``convert_2to3_doctests`` + List of doctest source files that need to be converted with 2to3. + See :doc:`python3` for more details. + +``use_2to3_fixers`` + A list of modules to search for additional fixers to be used during + the 2to3 conversion. See :doc:`python3` for more details. + +``project_urls`` + An arbitrary map of URL names to hyperlinks, allowing more extensible + documentation of where various resources can be found than the simple + ``url`` and ``download_url`` options provide. diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 64b385cb..7c0535d0 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -239,179 +239,6 @@ pre- or post-release tags. See the following sections for more details: * The `egg_info`_ command -New and Changed ``setup()`` Keywords -==================================== - -The following keyword arguments to ``setup()`` are added or changed by -``setuptools``. All of them are optional; you do not have to supply them -unless you need the associated ``setuptools`` feature. - -``include_package_data`` - If set to ``True``, this tells ``setuptools`` to automatically include any - data files it finds inside your package directories that are specified by - your ``MANIFEST.in`` file. For more information, see the section below on - `Including Data Files`_. - -``exclude_package_data`` - A dictionary mapping package names to lists of glob patterns that should - be *excluded* from your package directories. You can use this to trim back - any excess files included by ``include_package_data``. For a complete - description and examples, see the section below on `Including Data Files`_. - -``package_data`` - A dictionary mapping package names to lists of glob patterns. For a - complete description and examples, see the section below on `Including - Data Files`_. You do not need to use this option if you are using - ``include_package_data``, unless you need to add e.g. files that are - generated by your setup script and build process. (And are therefore not - in source control or are files that you don't want to include in your - source distribution.) - -``zip_safe`` - A boolean (True or False) flag specifying whether the project can be - safely installed and run from a zip file. If this argument is not - supplied, the ``bdist_egg`` command will have to analyze all of your - project's contents for possible problems each time it builds an egg. - -``install_requires`` - A string or list of strings specifying what other distributions need to - be installed when this one is. See the section below on `Declaring - Dependencies`_ for details and examples of the format of this argument. - -``entry_points`` - A dictionary mapping entry point group names to strings or lists of strings - defining the entry points. Entry points are used to support dynamic - discovery of services or plugins provided by a project. See `Dynamic - Discovery of Services and Plugins`_ for details and examples of the format - of this argument. In addition, this keyword is used to support `Automatic - Script Creation`_. - -``extras_require`` - A dictionary mapping names of "extras" (optional features of your project) - to strings or lists of strings specifying what other distributions must be - installed to support those features. See the section below on `Declaring - Dependencies`_ for details and examples of the format of this argument. - -``python_requires`` - A string corresponding to a version specifier (as defined in PEP 440) for - the Python version, used to specify the Requires-Python defined in PEP 345. - -``setup_requires`` - A string or list of strings specifying what other distributions need to - be present in order for the *setup script* to run. ``setuptools`` will - attempt to obtain these (even going so far as to download them using - ``EasyInstall``) before processing the rest of the setup script or commands. - This argument is needed if you are using distutils extensions as part of - your build process; for example, extensions that process setup() arguments - and turn them into EGG-INFO metadata files. - - (Note: projects listed in ``setup_requires`` will NOT be automatically - installed on the system where the setup script is being run. They are - simply downloaded to the ./.eggs directory if they're not locally available - already. If you want them to be installed, as well as being available - when the setup script is run, you should add them to ``install_requires`` - **and** ``setup_requires``.) - -``dependency_links`` - A list of strings naming URLs to be searched when satisfying dependencies. - These links will be used if needed to install packages specified by - ``setup_requires`` or ``tests_require``. They will also be written into - the egg's metadata for use by tools like EasyInstall to use when installing - an ``.egg`` file. - -``namespace_packages`` - A list of strings naming the project's "namespace packages". A namespace - package is a package that may be split across multiple project - distributions. For example, Zope 3's ``zope`` package is a namespace - package, because subpackages like ``zope.interface`` and ``zope.publisher`` - may be distributed separately. The egg runtime system can automatically - merge such subpackages into a single parent package at runtime, as long - as you declare them in each project that contains any subpackages of the - namespace package, and as long as the namespace package's ``__init__.py`` - does not contain any code other than a namespace declaration. See the - section below on `Namespace Packages`_ for more information. - -``test_suite`` - A string naming a ``unittest.TestCase`` subclass (or a package or module - containing one or more of them, or a method of such a subclass), or naming - a function that can be called with no arguments and returns a - ``unittest.TestSuite``. If the named suite is a module, and the module - has an ``additional_tests()`` function, it is called and the results are - added to the tests to be run. If the named suite is a package, any - submodules and subpackages are recursively added to the overall test suite. - - Specifying this argument enables use of the `test`_ command to run the - specified test suite, e.g. via ``setup.py test``. See the section on the - `test`_ command below for more details. - -``tests_require`` - If your project's tests need one or more additional packages besides those - needed to install it, you can use this option to specify them. It should - be a string or list of strings specifying what other distributions need to - be present for the package's tests to run. When you run the ``test`` - command, ``setuptools`` will attempt to obtain these (even going - so far as to download them using ``EasyInstall``). Note that these - required projects will *not* be installed on the system where the tests - are run, but only downloaded to the project's setup directory if they're - not already installed locally. - -.. _test_loader: - -``test_loader`` - If you would like to use a different way of finding tests to run than what - setuptools normally uses, you can specify a module name and class name in - this argument. The named class must be instantiable with no arguments, and - its instances must support the ``loadTestsFromNames()`` method as defined - in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will - pass only one test "name" in the `names` argument: the value supplied for - the ``test_suite`` argument. The loader you specify may interpret this - string in any way it likes, as there are no restrictions on what may be - contained in a ``test_suite`` string. - - The module name and class name must be separated by a ``:``. The default - value of this argument is ``"setuptools.command.test:ScanningLoader"``. If - you want to use the default ``unittest`` behavior, you can specify - ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This - will prevent automatic scanning of submodules and subpackages. - - The module and class you specify here may be contained in another package, - as long as you use the ``tests_require`` option to ensure that the package - containing the loader class is available when the ``test`` command is run. - -``eager_resources`` - A list of strings naming resources that should be extracted together, if - any of them is needed, or if any C extensions included in the project are - imported. This argument is only useful if the project will be installed as - a zipfile, and there is a need to have all of the listed resources be - extracted to the filesystem *as a unit*. Resources listed here - should be '/'-separated paths, relative to the source root, so to list a - resource ``foo.png`` in package ``bar.baz``, you would include the string - ``bar/baz/foo.png`` in this argument. - - If you only need to obtain resources one at a time, or you don't have any C - extensions that access other files in the project (such as data files or - shared libraries), you probably do NOT need this argument and shouldn't - mess with it. For more details on how this argument works, see the section - below on `Automatic Resource Extraction`_. - -``use_2to3`` - Convert the source code from Python 2 to Python 3 with 2to3 during the - build process. See :doc:`python3` for more details. - -``convert_2to3_doctests`` - List of doctest source files that need to be converted with 2to3. - See :doc:`python3` for more details. - -``use_2to3_fixers`` - A list of modules to search for additional fixers to be used during - the 2to3 conversion. See :doc:`python3` for more details. - -``project_urls`` - An arbitrary map of URL names to hyperlinks, allowing more extensible - documentation of where various resources can be found than the simple - ``url`` and ``download_url`` options provide. - - Using ``find_packages()`` ------------------------- -- cgit v1.2.3 From 46a73d96faedee345834f29a7ac218de64519da2 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 10:29:11 +0200 Subject: Fixed broken implicit links --- docs/keywords.txt | 34 +++++++++++++++++----------------- docs/setuptools.txt | 10 +++++++++- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/keywords.txt b/docs/keywords.txt index a1097aca..6a8fc2f2 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -9,19 +9,19 @@ associated ``setuptools`` feature. ``include_package_data`` If set to ``True``, this tells ``setuptools`` to automatically include any data files it finds inside your package directories that are specified by - your ``MANIFEST.in`` file. For more information, see the section below on - `Including Data Files`_. + 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 below on `Including Data Files`_. + 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 below on `Including - Data Files`_. You do not need to use this option if you are using + 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 @@ -35,22 +35,22 @@ associated ``setuptools`` feature. ``install_requires`` A string or list of strings specifying what other distributions need to - be installed when this one is. See the section below on `Declaring - Dependencies`_ for details and examples of the format of this argument. + 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 `Dynamic - Discovery of Services and Plugins`_ for details and examples of the format - of this argument. In addition, this keyword is used to support `Automatic - Script Creation`_. + 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 below on `Declaring - Dependencies`_ for details and examples of the format of this argument. + 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 @@ -89,7 +89,7 @@ associated ``setuptools`` feature. as you declare them in each project that contains any subpackages of the namespace package, and as long as the namespace package's ``__init__.py`` does not contain any code other than a namespace declaration. See the - section below on `Namespace Packages`_ for more information. + section on :ref:`Namespace Packages` for more information. ``test_suite`` A string naming a ``unittest.TestCase`` subclass (or a package or module @@ -100,9 +100,9 @@ associated ``setuptools`` feature. added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite. - Specifying this argument enables use of the `test`_ command to run the + 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 - `test`_ command below for more details. + :ref:`test` command below for more details. ``tests_require`` If your project's tests need one or more additional packages besides those @@ -152,7 +152,7 @@ associated ``setuptools`` feature. extensions that access other files in the project (such as data files or shared libraries), you probably do NOT need this argument and shouldn't mess with it. For more details on how this argument works, see the section - below on `Automatic Resource Extraction`_. + below on :ref:`Automatic Resource Extraction`. ``use_2to3`` Convert the source code from Python 2 to Python 3 with 2to3 during the diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 7c0535d0..e07ac296 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -345,6 +345,8 @@ With this layout, the package directory is specified as ``src``, as such:: .. _PEP 420: https://www.python.org/dev/peps/pep-0420/ +.. _Automatic Script Creation: + Automatic Script Creation ========================= @@ -432,6 +434,7 @@ and version is in use. The header script will check this and exit with an error if the ``.egg`` file has been renamed or is invoked via a symlink that changes its base name. +.. _Declaring Dependencies: Declaring Dependencies ====================== @@ -685,6 +688,8 @@ detailed in `PEP 508`_. .. _PEP 508: https://www.python.org/dev/peps/pep-0508/ +.. _Including Data Files: + Including Data Files ==================== @@ -860,6 +865,7 @@ no supported facility to reliably retrieve these resources. Instead, the PyPA recommends that any data files you wish to be accessible at run time be included in the package. +.. _Automatic Resource Extraction: Automatic Resource Extraction ----------------------------- @@ -905,6 +911,8 @@ Extensible Applications and Frameworks .. _Entry Points: +.. _Dynamic Discovery of Services and Plugins: + Dynamic Discovery of Services and Plugins ----------------------------------------- @@ -1977,7 +1985,7 @@ result (which must be a ``unittest.TestSuite``) is added to the tests to be run. If the named suite is a package, any submodules and subpackages are recursively added to the overall test suite. (Note: if your project specifies a ``test_loader``, the rules for processing the chosen ``test_suite`` may -differ; see the `test_loader`_ documentation for more details.) +differ; see the :ref:`test_loader ` documentation for more details.) Note that many test systems including ``doctest`` support wrapping their non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test -- cgit v1.2.3 From d2de0b92773c4304d6264258228a008499ccfd21 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 11:03:51 +0200 Subject: Transcibed all keywords from https://docs.python.org/3/distutils/apiref.html#distutils.core.setup --- docs/keywords.txt | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/docs/keywords.txt b/docs/keywords.txt index 6a8fc2f2..877a4caf 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -3,9 +3,96 @@ Supported ``setup()`` Keywords ============================== The following keyword arguments to ``setup()`` are supported by ``setuptools``. -All of them are optional; you do not have to supply them unless you need the +Some of them are optional; you do not have to supply them unless you need the associated ``setuptools`` feature. +``name`` + A string specifying the name of the package. + +``version`` + A string specifying the version number of the package. + +``description`` + A string describing the package in a single line. + +``long_description`` + A string providing a longer description of the package. + +``author`` + A string specifying the author of the package. + +``author_email`` + A string specifying the email address of the package author. + +``maintainer`` + A string specifying the name of the current maintainer, if different from + the author. Note that if the maintainer is provided, setuptools will use it + as the author in ``PKG-INFO``. + +``maintainer_email`` + A string specifying the email address of the current maintainer, if + different from the author. + +``url`` + A string specifying the URL for the package homepage. + +``download_url`` + A string specifying the URL to download the package. + +``packages`` + A list of strings specifying the packages that setuptools will manipulate. + +``py_modules`` + A list of strings specifying the modules that setuptools will manipulate. + +``scripts`` + A list of strings specifying the standalone script files to be built and + installed. + +``ext_modules`` + A list of instances of ``setuptools.Extension`` providing the list of + Python extensions to be built. + +``classifiers`` + A list of strings describing the categories for the package. + +``distclass`` + A subclass of ``Distribution`` to use. + +``script_name`` + A string specifying the name of the setup.py script -- defaults to + ``sys.argv[0]`` + +``script_args`` + A list of strings defining the arguments to supply to the setup script. + +``options`` + A dictionary providing the default options for the setup script. + +``license`` + A string specifying the license of the package. + +``keywords`` + A list of strings or a comma-separated string providing descriptive + meta-data. See: `PEP 0314`_. + +.. _PEP 0314: https://www.python.org/dev/peps/pep-0314/ + +``platforms`` + A list of strings or comma-separated string. + +``cmdclass`` + A dictionary providing a mapping of command names to ``Command`` + subclasses. + +``data_files`` + A list of strings specifying the data files to install. + +``package_dir`` + A dictionary providing a mapping of package to directory names. + +.. Below are setuptools keywords, above are distutils + ``include_package_data`` If set to ``True``, this tells ``setuptools`` to automatically include any data files it finds inside your package directories that are specified by -- cgit v1.2.3 From 734e5106be681eec7f1717f9feb4836b025dbe97 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 11:07:58 +0200 Subject: Added changelog fragment --- changelog.d/1700.change.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/1700.change.rst diff --git a/changelog.d/1700.change.rst b/changelog.d/1700.change.rst new file mode 100644 index 00000000..f66046a2 --- /dev/null +++ b/changelog.d/1700.change.rst @@ -0,0 +1 @@ +Document all supported keywords by migrating the ones from distutils. -- cgit v1.2.3 From a7fcfcdf8e224f42aa83c32363df3a39100ca69c Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 14:18:59 +0200 Subject: Added warnings for data_files, setup_requires and dependency_links --- docs/keywords.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index 877a4caf..81b80344 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -86,6 +86,11 @@ associated ``setuptools`` feature. subclasses. ``data_files`` + + .. warning:: + ``data_files`` is deprecated. It does not work with wheels, so it + should be avoided. + A list of strings specifying the data files to install. ``package_dir`` @@ -144,6 +149,10 @@ associated ``setuptools`` feature. the Python version, used to specify the Requires-Python defined in PEP 345. ``setup_requires`` + + .. warning:: + Using ``setup_requires`` is discouraged in favour for `PEP-518`_ + A string or list of strings specifying what other distributions need to be present in order for the *setup script* to run. ``setuptools`` will attempt to obtain these (even going so far as to download them using @@ -159,7 +168,13 @@ associated ``setuptools`` feature. when the setup script is run, you should add them to ``install_requires`` **and** ``setup_requires``.) +.. _PEP-518: http://www.python.org/dev/peps/pep-0518/ + ``dependency_links`` + + .. warning:: + ``dependency_links`` is deprecated. It is not supported anymore by pip. + A list of strings naming URLs to be searched when satisfying dependencies. These links will be used if needed to install packages specified by ``setup_requires`` or ``tests_require``. They will also be written into -- cgit v1.2.3 From 13c1825df412b6ed63ff05594af0e4dde5ef0455 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Thu, 16 May 2019 14:19:25 +0200 Subject: Maintain old header and link to new keywords document --- docs/keywords.txt | 2 ++ docs/setuptools.txt | 7 +++++++ 2 files changed, 9 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index 81b80344..2666ba85 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -1,3 +1,5 @@ +.. _Supported setup() Keywords: + ============================== Supported ``setup()`` Keywords ============================== diff --git a/docs/setuptools.txt b/docs/setuptools.txt index e07ac296..4ddc2b7a 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -239,6 +239,13 @@ pre- or post-release tags. See the following sections for more details: * The `egg_info`_ command +New and Changed ``setup()`` Keywords +==================================== + +The keywords supported by setuptools can be found in :ref:`Supported setup() +Keywords` + + Using ``find_packages()`` ------------------------- -- cgit v1.2.3 From cc9e041823a6a06cabeaa27949abc4e2ff08aee0 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 12:37:06 +0200 Subject: Added unused requires, obsolete and requires for completenes --- docs/keywords.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index 2666ba85..ff757231 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -98,6 +98,23 @@ associated ``setuptools`` feature. ``package_dir`` A dictionary providing a mapping of package to directory names. +``requires`` + + .. warning:: + ``requires`` is superseded by ``install_requires`` and should not be used + anymore. + +``obsoletes`` + + .. warning:: + ``obsoletes`` is not supported by ``pip`` and should not be used. + +``requires`` + + .. warning:: + ``requires`` is not supported by ``pip`` and should not be used. + + .. Below are setuptools keywords, above are distutils ``include_package_data`` -- cgit v1.2.3 From 0b323b5e158bfd284cdd6c99b130cfc05eb05187 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 12:37:48 +0200 Subject: Added ext_package --- docs/keywords.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index ff757231..4d7efd38 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -51,6 +51,10 @@ associated ``setuptools`` feature. A list of strings specifying the standalone script files to be built and installed. +``ext_package`` + A string specifying the base package name for the extensions provided by + this package. + ``ext_modules`` A list of instances of ``setuptools.Extension`` providing the list of Python extensions to be built. -- cgit v1.2.3 From e21b663802f7ca97c1cd4c2866338c0129e9a502 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 12:37:58 +0200 Subject: added use_2to3_exclude_fixers --- docs/keywords.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index 4d7efd38..7881e285 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -291,6 +291,9 @@ associated ``setuptools`` feature. A list of modules to search for additional fixers to be used during the 2to3 conversion. See :doc:`python3` for more details. +``use_2to3_exclude_fixers`` + List of fixer names to be skipped. + ``project_urls`` An arbitrary map of URL names to hyperlinks, allowing more extensible documentation of where various resources can be found than the simple -- cgit v1.2.3 From 4521d88caac6a68a1baf55c401589f8ce7b04243 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 12:38:09 +0200 Subject: added long_description_content_type --- docs/keywords.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/keywords.txt b/docs/keywords.txt index 7881e285..5086bcf1 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -20,6 +20,10 @@ associated ``setuptools`` feature. ``long_description`` A string providing a longer description of the package. +``long_description_content_type`` + A string specifying the content type is used for the ``long_description`` + (e.g. ``text/markdown``) + ``author`` A string specifying the author of the package. -- cgit v1.2.3 From 4786eb4053e1eac5cbf869b290a90436a9cfe347 Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 12:59:56 +0200 Subject: Made keywords a subpage (via include directive) maintaining the old structure --- docs/index.txt | 1 - docs/keywords.txt | 10 ---------- docs/setuptools.txt | 7 +++++-- 3 files changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index 60c4f331..13a46e74 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -17,7 +17,6 @@ Documentation content: :maxdepth: 2 setuptools - keywords pkg_resources python3 development diff --git a/docs/keywords.txt b/docs/keywords.txt index 5086bcf1..cbaf7ae9 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -1,13 +1,3 @@ -.. _Supported setup() Keywords: - -============================== -Supported ``setup()`` Keywords -============================== - -The following keyword arguments to ``setup()`` are supported by ``setuptools``. -Some of them are optional; you do not have to supply them unless you need the -associated ``setuptools`` feature. - ``name`` A string specifying the name of the package. diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 4ddc2b7a..ae85b8f5 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -242,8 +242,11 @@ pre- or post-release tags. See the following sections for more details: New and Changed ``setup()`` Keywords ==================================== -The keywords supported by setuptools can be found in :ref:`Supported setup() -Keywords` +The following keyword arguments to ``setup()`` are supported by ``setuptools``. +Some of them are optional; you do not have to supply them unless you need the +associated ``setuptools`` feature. + +.. include:: keywords.txt Using ``find_packages()`` -- cgit v1.2.3 From 345f7e6fbc3118f3fd6c97a307dbbd9cda30a84c Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 13:05:39 +0200 Subject: s/requires/provides/ --- docs/keywords.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/keywords.txt b/docs/keywords.txt index cbaf7ae9..488ed20b 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -107,10 +107,10 @@ .. warning:: ``obsoletes`` is not supported by ``pip`` and should not be used. -``requires`` +``provides`` .. warning:: - ``requires`` is not supported by ``pip`` and should not be used. + ``provides`` is not supported by ``pip`` and should not be used. .. Below are setuptools keywords, above are distutils -- cgit v1.2.3 From 73dbe0ec07e3738bc592e92def65209b45a14dfb Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 13:06:53 +0200 Subject: s/favour/favor/ Co-Authored-By: Benoit Pierre --- docs/keywords.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/keywords.txt b/docs/keywords.txt index 488ed20b..db50163a 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -168,7 +168,7 @@ ``setup_requires`` .. warning:: - Using ``setup_requires`` is discouraged in favour for `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 -- cgit v1.2.3 From 6a3674a18d22dbea4d6b513b8e8a7ac28ada5eba Mon Sep 17 00:00:00 2001 From: Bastian Venthur Date: Sat, 18 May 2019 22:37:49 +0200 Subject: Added meat to obsoletes and provides, removed that they should not be used. --- docs/keywords.txt | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/docs/keywords.txt b/docs/keywords.txt index db50163a..d56014e0 100644 --- a/docs/keywords.txt +++ b/docs/keywords.txt @@ -105,13 +105,49 @@ ``obsoletes`` .. warning:: - ``obsoletes`` is not supported by ``pip`` and should not be used. + ``obsoletes`` is currently ignored by ``pip``. + + List of strings describing packages which this package renders obsolete, + meaning that the two projects should not be installed at the same time. + + Version declarations can be supplied. Version numbers must be in the format + specified in Version specifiers (e.g. ``foo (<3.0)``). + + This field may be followed by an environment marker after a semicolon (e.g. + ``foo; os_name == "posix"``) + + The most common use of this field will be in case a project name changes, + e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. When you install + Torqued Python, the Gorgon distribution should be removed. ``provides`` .. warning:: - ``provides`` is not supported by ``pip`` and should not be used. - + ``provides`` is currently ignored by ``pip``. + + List of strings describing package- and virtual package names contained + within this package. + + A package may provide additional names, e.g. to indicate that multiple + projects have been bundled together. For instance, source distributions of + the ZODB project have historically included the transaction project, which + is now available as a separate distribution. Installing such a source + distribution satisfies requirements for both ZODB and transaction. + + A package may also provide a “virtual” project name, which does not + correspond to any separately-distributed project: such a name might be used + to indicate an abstract capability which could be supplied by one of + multiple projects. E.g., multiple projects might supply RDBMS bindings for + use by a given ORM: each project might declare that it provides + ORM-bindings, allowing other projects to depend only on having at most one + of them installed. + + A version declaration may be supplied and must follow the rules described in + Version specifiers. The distribution’s version number will be implied if + none is specified (e.g. ``foo (<3.0)``). + + Each package may be followed by an environment marker after a semicolon + (e.g. ``foo; os_name == "posix"``). .. Below are setuptools keywords, above are distutils -- cgit v1.2.3