diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst index 44ff742529f..08b0489bdd9 100644 --- a/docs/userguide/datafiles.rst +++ b/docs/userguide/datafiles.rst @@ -56,7 +56,7 @@ and you supply this configuration: include_package_data=True ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -137,7 +137,7 @@ data files: package_data={"mypkg": ["*.txt", "*.rst"]} ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -210,7 +210,7 @@ use the ``package_data`` option, the following configuration will work: package_data={"": ["*.txt"], "mypkg1": ["data1.rst"]}, ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -288,7 +288,7 @@ use the ``exclude_package_data`` option: exclude_package_data={"mypkg": [".gitattributes"]}, ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -365,7 +365,7 @@ the configuration might look like this: } ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -412,7 +412,7 @@ scanning of namespace packages in the ``src`` directory and the rest is handled include_package_data=True, ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -539,10 +539,6 @@ run time be included **inside the package**. ---- -.. [#beta] - Support for adding build configuration options via the ``[tool.setuptools]`` - table in the ``pyproject.toml`` file. See :doc:`/userguide/pyproject_config`. - .. [#system-dirs] These locations can be discovered with the help of third-party libraries such as :pypi:`platformdirs`. diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 5fc38e587b3..12eb9168952 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -39,7 +39,7 @@ Normally, you would specify the packages to be included manually in the followin packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2'] ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -92,7 +92,7 @@ exactly to the directory structure, you also need to configure ``package_dir``: # ... ) -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -127,9 +127,6 @@ the following sections. Automatic discovery =================== -.. warning:: Automatic discovery is a **beta** feature and might change in the future. - See :ref:`custom-discovery` for other methods of discovery. - By default ``setuptools`` will consider 2 popular project layouts, each one with its own set of advantages and disadvantages [#layout1]_ [#layout2]_ as discussed in the following sections. @@ -271,7 +268,7 @@ the provided tools for package discovery: # or from setuptools import find_namespace_packages -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -343,7 +340,7 @@ in ``src`` that start with the name ``pkg`` and not ``additional``: ``pkg.namespace`` is ignored by ``find_packages()`` (see ``find_namespace_packages()`` below). -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -451,7 +448,7 @@ distribution, then you will need to specify: On the other hand, ``find_namespace_packages()`` will scan all directories. -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -578,10 +575,6 @@ The project layout remains the same and ``pyproject.toml/setup.cfg`` remains the ---- -.. [#beta] - Support for adding build configuration options via the ``[tool.setuptools]`` - table in the ``pyproject.toml`` file is still in **beta** stage. - See :doc:`/userguide/pyproject_config`. .. [#layout1] https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure .. [#layout2] https://blog.ionelmc.ro/2017/09/25/rehashing-the-src-layout/ diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst index c897ab9b3ce..b6813992fa6 100644 --- a/docs/userguide/pyproject_config.rst +++ b/docs/userguide/pyproject_config.rst @@ -75,11 +75,6 @@ The ``project`` table contains metadata fields as described by Setuptools-specific configuration ================================= -.. warning:: - Support for declaring configurations not standardized by :pep:`621` - (i.e. the ``[tool.setuptools]`` table), - is still in **beta** stage and might change in future releases. - While the standard ``project`` table in the ``pyproject.toml`` file covers most of the metadata used during the packaging process, there are still some ``setuptools``-specific configurations that can be set by users that require @@ -92,24 +87,30 @@ file, and can be set via the ``tool.setuptools`` table: ========================= =========================== ========================= Key Value Type (TOML) Notes ========================= =========================== ========================= -``platforms`` array -``zip-safe`` boolean If not specified, ``setuptools`` will try to guess - a reasonable default for the package -``eager-resources`` array -``py-modules`` array See tip below -``packages`` array or ``find`` directive See tip below -``package-dir`` table/inline-table Used when explicitly listing ``packages`` -``namespace-packages`` array **Deprecated** - Use implicit namespaces instead (:pep:`420`) -``package-data`` table/inline-table See :doc:`/userguide/datafiles` -``include-package-data`` boolean ``True`` by default -``exclude-package-data`` table/inline-table +``py-modules`` array See tip below. +``packages`` array or ``find`` directive See tip below. +``package-dir`` table/inline-table Used when explicitly listing ``packages``. +------------------------- --------------------------- ------------------------- +``package-data`` table/inline-table See :doc:`/userguide/datafiles`. +``include-package-data`` boolean ``True`` by default. See :doc:`/userguide/datafiles`. +``exclude-package-data`` table/inline-table Empty by default. See :doc:`/userguide/datafiles`. +------------------------- --------------------------- ------------------------- ``license-files`` array of glob patterns **Provisional** - likely to change with :pep:`639` (by default: ``['LICEN[CS]E*', 'COPYING*', 'NOTICE*', 'AUTHORS*']``) -``data-files`` table/inline-table **Discouraged** - check :doc:`/userguide/datafiles` -``script-files`` array **Deprecated** - equivalent to the ``script`` keyword in ``setup.py`` - (should be avoided in favour of ``project.scripts``) -``provides`` array **Ignored by pip** -``obsoletes`` array **Ignored by pip** +``data-files`` table/inline-table **Discouraged** - check :doc:`/userguide/datafiles`. +``script-files`` array **Discouraged** - equivalent to the ``script`` keyword in ``setup.py``. + Whenever possible, please use ``project.scripts`` instead. +------------------------- --------------------------- ------------------------- +``provides`` array Sets the ``Provides-Dist`` :doc:`core-metadata ` field + (*ignored by pip when installing packages*). +``obsoletes`` array Sets the ``Obsoletes-Dist`` :doc:`core-metadata ` field + (*ignored by pip when installing packages*). +``platforms`` array Sets the ``Platform`` :doc:`core-metadata ` field + (*ignored by pip when installing packages*). +------------------------- --------------------------- ------------------------- +``zip-safe`` boolean **Discouraged** - only relevant for ``pkg_resources`` and/or ``easy_install`` in the context of :doc:`eggs ` (deprecated). +``eager-resources`` array **Discouraged** - only relevant for ``pkg_resources`` and/or ``easy_install`` in the context of :doc:`eggs ` (deprecated). +``namespace-packages`` array **Deprecated** - Use implicit namespaces instead (:pep:`420`). ========================= =========================== ========================= .. note:: @@ -152,6 +153,15 @@ existing packages should consider alternatives. [tool.setuptools] packages = ["my_package"] + If you want to publish a distribution that does not include any Python module + (e.g. a "meta-distribution" that just aggregate dependencies), please + consider something like the following: + + .. code-block:: toml + + [tool.setuptools] + packages = [] + .. _dynamic-pyproject-config: diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index c1a42038c2e..2afab9e54cc 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -69,7 +69,7 @@ library will be used to actually do the packaging. In addition to specifying a build system, you also will need to add some package information such as metadata, contents, dependencies, etc. -This can be done in the same ``pyproject.toml`` [#beta]_ file, +This can be done in the same ``pyproject.toml`` file, or in a separated one: ``setup.cfg`` or ``setup.py`` [#setup.py]_. The following example demonstrates a minimum configuration @@ -196,7 +196,7 @@ Therefore, ``setuptools`` provides a convenient way to customize which packages should be distributed and in which directory they should be found, as shown in the example below: -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -254,8 +254,7 @@ For more details and advanced use, go to :ref:`package_discovery`. have been improved to detect popular project layouts (such as the :ref:`flat-layout` and :ref:`src-layout`) without requiring any special configuration. Check out our :ref:`reference docs ` - for more information, but please keep in mind that this functionality is - still considered **beta** and might change in future releases. + for more information. Entry points and automatic script creation @@ -363,7 +362,7 @@ Including Data Files Setuptools offers three ways to specify data files to be included in your packages. For the simplest use, you can simply use the ``include_package_data`` keyword: -.. tab:: pyproject.toml (**BETA**) [#beta]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -479,9 +478,4 @@ up-to-date references that can help you when it is time to distribute your work. supported in those files (e.g. C extensions). See :ref:`note `. -.. [#beta] - Support for adding build configuration options via the ``[tool.setuptools]`` - table in the ``pyproject.toml`` file is still in **beta** stage. - See :doc:`/userguide/pyproject_config`. - .. _PyPI: https://pypi.org