Skip to content

Add clarifications about experimental status for pyproject.toml configuration #3347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 17, 2022
Merged

Add clarifications about experimental status for pyproject.toml configuration #3347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
61b9413
Warn about 'tool.setuptool' instead of project metadata in pyproject.…
abravalheri Jun 7, 2022
2734a35
Clarify warnings and notes in documentation about experimental pyproj…
abravalheri Jun 7, 2022
94ff0b4
Add news fragment
abravalheri Jun 7, 2022
9c7163b
Change wording from *experimental* to *beta*
abravalheri Jun 16, 2022
9d48703
docs: Reorder example tabs
abravalheri Jun 16, 2022
e85063a
Reorder words in footnote to improve the meaning
abravalheri Jun 17, 2022
b48a0b2
Update docs/userguide/datafiles.rst
abravalheri Jun 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions changelog.d/3347.change.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Changed warnings and documentation notes about *experimental* aspect of ``pyproject.toml`` configuration:
now ``[pyproject]`` is a fully supported configuration interface, but the ``[tool.setuptools]`` table
and sub-tables are still considered to be in **beta** stage.
19 changes: 9 additions & 10 deletions docs/userguide/datafiles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -137,7 +137,7 @@ data files:
package_data={"mypkg": ["*.txt", "*.rst"]}
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
.. tab:: pyproject.toml (**BETA**) [#beta]_

.. code-block:: toml

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -365,7 +365,7 @@ the configuration might look like this:
}
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
.. tab:: pyproject.toml (**BETA**) [#beta]_

.. code-block:: toml

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -539,10 +539,9 @@ 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]``
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`.
Expand Down
128 changes: 58 additions & 70 deletions docs/userguide/dependency_management.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,18 @@ be able to run. ``setuptools`` supports automatically downloading and installing
these dependencies when the package is installed. Although there is more
finesse to it, let's start with a simple example.

.. tab:: pyproject.toml

.. code-block:: toml

[project]
# ...
dependencies = [
"docutils",
"BazSpam == 1.1",
]
# ...

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -75,18 +87,6 @@ finesse to it, let's start with a simple example.
],
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_

.. code-block:: toml

[project]
# ...
dependencies = [
"docutils",
"BazSpam == 1.1",
]
# ...


When your project is installed (e.g., using :pypi:`pip`), all of the dependencies not
already installed will be located (via `PyPI`_), downloaded, built (if necessary),
Expand All @@ -104,6 +104,17 @@ specific dependencies. For example, the ``enum`` package was added in Python
3.4, therefore, package that depends on it can elect to install it only when
the Python version is older than 3.4. To accomplish this

.. tab:: pyproject.toml

.. code-block:: toml

[project]
# ...
dependencies = [
"enum34; python_version<'3.4'",
]
# ...

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -124,20 +135,21 @@ the Python version is older than 3.4. To accomplish this
],
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_
Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
and only install it if the user is using a Windows operating system:

.. tab:: pyproject.toml

.. code-block:: toml

[project]
# ...
dependencies = [
"enum34; python_version<'3.4'",
"pywin32 >= 1.0; platform_system=='Windows'",
]
# ...

Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
and only install it if the user is using a Windows operating system:

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -160,18 +172,6 @@ and only install it if the user is using a Windows operating system:
],
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_

.. code-block:: toml

[project]
# ...
dependencies = [
"enum34; python_version<'3.4'",
"pywin32 >= 1.0; platform_system=='Windows'",
]
# ...

The environmental markers that may be used for testing platform types are
detailed in :pep:`508`.

Expand All @@ -190,6 +190,16 @@ set of extra functionalities.
For example, let's consider a ``Package-A`` that offers
optional PDF support and requires two other dependencies for it to work:

.. tab:: pyproject.toml

.. code-block:: toml

[project]
name = "Package-A"
# ...
[project.optional-dependencies]
PDF = ["ReportLab>=1.2", "RXP"]

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -215,16 +225,6 @@ optional PDF support and requires two other dependencies for it to work:
},
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_

.. code-block:: toml

[project]
name = "Package-A"
# ...
[project.optional-dependencies]
PDF = ["ReportLab>=1.2", "RXP"]

.. sidebar::

.. tip::
Expand All @@ -238,6 +238,17 @@ A use case for this approach is that other package can use this "extra" for thei
own dependencies. For example, if ``Package-B`` needs ``Package-B`` with PDF support
installed, it might declare the dependency like this:

.. tab:: pyproject.toml

.. code-block:: toml

[project]
name = "Package-B"
# ...
dependencies = [
"Package-A[PDF]"
]

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -261,17 +272,6 @@ installed, it might declare the dependency like this:
...,
)

.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_

.. code-block:: toml

[project]
name = "Package-B"
# ...
dependencies = [
"Package-A[PDF]"
]

This will cause ``ReportLab`` to be installed along with ``Package-A``, if ``Package-B`` is
installed -- even if ``Package-A`` was already installed. In this way, a project
can encapsulate groups of optional "downstream dependencies" under a feature
Expand Down Expand Up @@ -338,6 +338,15 @@ Python requirement
In some cases, you might need to specify the minimum required python version.
This can be configured as shown in the example below.

.. tab:: pyproject.toml

.. code-block:: toml

[project]
name = "Package-B"
requires-python = ">=3.6"
# ...

.. tab:: setup.cfg

.. code-block:: ini
Expand All @@ -361,25 +370,4 @@ This can be configured as shown in the example below.
)


.. tab:: pyproject.toml (**EXPERIMENTAL**) [#experimental]_

.. code-block:: toml

[project]
name = "Package-B"
requires-python = ">=3.6"
# ...

----

.. rubric:: Notes

.. [#experimental]
While the ``[build-system]`` table should always be specified in the
``pyproject.toml`` file, support for adding package metadata and build configuration
options via the ``[project]`` and ``[tool.setuptools]`` tables is still
experimental and might change in future releases.
See :doc:`/userguide/pyproject_config`.


.. _PyPI: https://pypi.org
Loading