diff --git a/changelog.d/3347.change.rst b/changelog.d/3347.change.rst index f0dac6b833..b229981a66 100644 --- a/changelog.d/3347.change.rst +++ b/changelog.d/3347.change.rst @@ -1,2 +1,3 @@ Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration: -now only the ``[tool.setuptools]`` table (and sub-tables) are considered experimental. +now ``[pyproject]`` is a fully supported configuration interface, but the ``[tool.setuptools]`` table +and sub-tables are still considered to be in **beta** stage. diff --git a/docs/userguide/datafiles.rst b/docs/userguide/datafiles.rst index 3a2ffbdf05..8501e95dc9 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 (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -137,7 +137,7 @@ data files: package_data={"mypkg": ["*.txt", "*.rst"]} ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. 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 (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -288,7 +288,7 @@ use the ``exclude_package_data`` option: exclude_package_data={"mypkg": [".gitattributes"]}, ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -365,7 +365,7 @@ the configuration might look like this: } ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. 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 (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -539,10 +539,10 @@ run time be included **inside the package**. ---- -.. [#experimental] - Support for specifying package metadata and build configuration options via - ``pyproject.toml`` is experimental and might change - in the future. See :doc:`/userguide/pyproject_config`. +.. [#beta] + Support for adding build configuration options via the ``[tool.setuptools]`` + in the ``pyproject.toml`` file table is still in **beta** stage. + 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/entry_point.rst b/docs/userguide/entry_point.rst index b7dd7aa917..bad083f490 100644 --- a/docs/userguide/entry_point.rst +++ b/docs/userguide/entry_point.rst @@ -92,7 +92,7 @@ configuration: } ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -162,7 +162,7 @@ Then, we can add a GUI script entry point: } ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -368,7 +368,7 @@ of ``timmins-plugin-fancy``: } ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -441,7 +441,7 @@ The configuration of ``timmins-plugin-fancy`` would then change to: } ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml .. code-block:: toml @@ -562,11 +562,6 @@ class or module. ---- -.. [#experimental] - Support for specifying package metadata and build configuration options via - ``pyproject.toml`` is experimental and might change - in the future. See :doc:`/userguide/pyproject_config`. - .. [#use_for_scripts] Reference: https://packaging.python.org/en/latest/specifications/entry-points/#use-for-scripts diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst index 4391aa1273..ec282bad86 100644 --- a/docs/userguide/package_discovery.rst +++ b/docs/userguide/package_discovery.rst @@ -40,7 +40,7 @@ Normally, you would specify the packages to be included manually in the followin packages=['mypkg', 'mypkg.subpkg1', 'mypkg.subpkg2'] ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -93,7 +93,7 @@ exactly to the directory structure, you also need to configure ``package_dir``: # ... ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -128,7 +128,7 @@ the following sections. Automatic discovery =================== -.. warning:: Automatic discovery is an **experimental** feature and might change +.. warning:: Automatic discovery is an **beta** feature and might change (or be completely removed) in the future. See :ref:`custom-discovery` for a stable way of configuring ``setuptools``. @@ -276,7 +276,7 @@ the provided tools for package discovery: # or from setuptools import find_namespace_packages -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -349,7 +349,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 (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -458,7 +458,7 @@ distribution, then you will need to specify: On the other hand, ``find_namespace_packages()`` will scan all directories. -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -585,10 +585,10 @@ The project layout remains the same and ``setup.cfg`` remains the same. ---- -.. [#experimental] - Support for specifying package metadata and build configuration options via - ``pyproject.toml`` is experimental and might change - in the future. See :doc:`/userguide/pyproject_config`. +.. [#beta] + Support for adding build configuration options via the ``[tool.setuptools]`` + in the ``pyproject.toml`` file table 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 dcf284d5f3..2b0f9cbc82 100644 --- a/docs/userguide/pyproject_config.rst +++ b/docs/userguide/pyproject_config.rst @@ -72,7 +72,7 @@ Setuptools-specific configuration .. warning:: Support for declaring configurations not standardized by :pep:`621` (i.e. the ``[tool.setuptools]`` table), - is still **experimental** and might change in future releases. + 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 @@ -99,7 +99,7 @@ Key Value Type (TOML) Notes ``exclude-package-data`` table/inline-table ``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 **Deprecated** - check :doc:`/userguide/datafiles` +``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** diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 923b1d4e1b..4e3d73280e 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -58,7 +58,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`` [#experimental]_ file, +This can be done in the same ``pyproject.toml`` [#beta]_ file, or in a separated one: ``setup.cfg`` or ``setup.py`` (please note however that configuring new projects via ``setup.py`` is discouraged [#setup.py]_). @@ -196,7 +196,7 @@ found, as shown in the example below: # ... ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -225,7 +225,7 @@ For more details and advanced use, go to :ref:`package_discovery`. :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 **experimental** and might change in future releases. + still considered **beta** and might change in future releases. Entry points and automatic script creation @@ -349,7 +349,7 @@ For the simplest use, you can simply use the ``include_package_data`` keyword: # ... ) -.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_ +.. tab:: pyproject.toml (**BETA**) [#beta]_ .. code-block:: toml @@ -447,9 +447,9 @@ up-to-date references that can help you when it is time to distribute your work. ` and use ``setup.py`` only for the parts not supported in those files (e.g. C extensions). -.. [#experimental] +.. [#beta] Support for adding build configuration options via the ``[tool.setuptools]`` - in the ``pyproject.toml`` file table is still experimental and might change - in future releases. See :doc:`/userguide/pyproject_config`. + in the ``pyproject.toml`` file table is still in **beta** stage. + See :doc:`/userguide/pyproject_config`. .. _PyPI: https://pypi.org diff --git a/pytest.ini b/pytest.ini index 0be8d7e2ef..7c863960b1 100644 --- a/pytest.ini +++ b/pytest.ini @@ -59,4 +59,4 @@ filterwarnings= ignore:Distutils was imported before setuptools ignore:Setuptools is replacing distutils - ignore:Support for configuring .* in .pyproject.toml. is still experimental + ignore:Support for .* in .pyproject.toml. is still .beta. diff --git a/setuptools/config/pyprojecttoml.py b/setuptools/config/pyprojecttoml.py index ce5ad04d7a..e9532d41b9 100644 --- a/setuptools/config/pyprojecttoml.py +++ b/setuptools/config/pyprojecttoml.py @@ -96,11 +96,8 @@ def read_configuration( if setuptools_table: # TODO: Remove the following once the feature stabilizes: - msg = ( - "Support for configuring `[tool.setuptools]` in `pyproject.toml` is still " - "experimental and may change in future releases." - ) - warnings.warn(msg, _ExperimentalConfiguration) + msg = "Support for `[tool.setuptools]` in `pyproject.toml` is still *beta*." + warnings.warn(msg, _BetaConfiguration) # There is an overall sense in the community that making include_package_data=True # the default would be an improvement. @@ -414,8 +411,8 @@ def __exit__(self, exc_type, exc_value, traceback): return super().__exit__(exc_type, exc_value, traceback) -class _ExperimentalConfiguration(UserWarning): - """Explicitly inform users that `pyproject.toml` configuration is experimental""" +class _BetaConfiguration(UserWarning): + """Explicitly inform users that some `pyproject.toml` configuration is *beta*""" class _InvalidFile(UserWarning):