PEP 621 & 631: pull in details from PEP 631 into PEP 621 (#1647)
Along the way, update PEP 631 as accepted and add a note about it contributing to PEP 621.
This commit is contained in:
Brett Cannon
GitHub
parent
1dc309632a
commit
b8dae20a52
86
pep-0621.rst
86
pep-0621.rst
|
|
@ -3,7 +3,6 @@ Title: Storing project metadata in pyproject.toml
|
|||
Author: Brett Cannon <brett@python.org>,
|
||||
Dustin Ingram <di@python.org>,
|
||||
Paul Ganssle <paul at ganssle.io>,
|
||||
Paul Moore <p.f.moore@gmail.com>,
|
||||
Pradyun Gedam <pradyunsg@gmail.com>,
|
||||
Sébastien Eustace <sebastien@eustace.io>,
|
||||
Thomas Kluyver <thomas@kluyver.me.uk>,
|
||||
|
|
@ -377,9 +376,12 @@ be ambiguous in the face of ``[project.scripts]`` and
|
|||
|
||||
``dependencies``/``optional-dependencies``
|
||||
''''''''''''''''''''''''''''''''''''''''''
|
||||
- Format: TBD
|
||||
- `Core metadata`_: ``Requires-Dist``
|
||||
(`link <https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use>`__)
|
||||
- Format: Array of :pep:`508` strings (``dependencies``) and a table
|
||||
with values of arrays of :pep:`508` strings
|
||||
(``optional-dependencies``)
|
||||
- `Core metadata`_: ``Requires-Dist`` and ``Provides-Extra``
|
||||
(`link <https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use>`__,
|
||||
`link <https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use>`__)
|
||||
- Synonyms
|
||||
|
||||
- Flit_: ``requires`` for required dependencies, ``requires-extra``
|
||||
|
|
@ -393,8 +395,19 @@ be ambiguous in the face of ``[project.scripts]`` and
|
|||
``extras_require`` for optional dependencies
|
||||
(`link <https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata>`__)
|
||||
|
||||
See the open issue on `How to specify dependencies?`_ for a
|
||||
discussion of the options of how to specify a project's dependencies.
|
||||
The (optional) dependencies of the project.
|
||||
|
||||
For ``dependencies``, it is a key whose value is an array of strings.
|
||||
Each string represents a dependency of the project and MUST be
|
||||
formatted as a valid :pep:`508` string. Each string maps directly to
|
||||
a ``Requires-Dist`` entry in the `core metadata`_.
|
||||
|
||||
For ``optional-dependencies``, it is a table where each key specifies
|
||||
an extra and whose value is an array of strings. The strings of the
|
||||
arrays must be valid :pep:`508` strings. The keys MUST be valid values
|
||||
for the ``Provides-Extra`` `core metadata`_. Each value in the array
|
||||
thus becomes a corresponding ``Requires-Dist`` entry for the matching
|
||||
``Provides-Extra`` metadata.
|
||||
|
||||
``dynamic``
|
||||
'''''''''''
|
||||
|
|
@ -454,9 +467,18 @@ Example
|
|||
"Programming Language :: Python"
|
||||
]
|
||||
|
||||
# Using 'dependencies' and 'optional-dependencies' as an example
|
||||
# as those fields' format are an Open Issue.
|
||||
dynamic = ["dependencies", "optional-dependencies"]
|
||||
dependencies = [
|
||||
"httpx",
|
||||
"gidgethub[httpx]>4.0.0",
|
||||
"django>2.1; os_name != 'nt'",
|
||||
"django>2.0; os_name == 'nt'"
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
test = [
|
||||
"pytest < 5.0.0",
|
||||
"pytest-cov[all]"
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
homepage = "example.com"
|
||||
|
|
@ -652,44 +674,24 @@ Originally this PEP said that tools SHOULD backfill appropriate trove classifier
|
|||
This was changed to say it MAY occur to emphasize it was entirely optional for
|
||||
build back-ends to implement.
|
||||
|
||||
Open Issues
|
||||
===========
|
||||
|
||||
How to specify dependencies?
|
||||
----------------------------
|
||||
People seem to fall into two camps on how to specify dependencies:
|
||||
using :pep:`508` strings or TOML tables (sometimes referred to as the
|
||||
"exploded table" format due to it being the equivalent of translating
|
||||
a :pep:`508` string into a table format). There is no question as to
|
||||
whether one format or another can fully represent what the other can.
|
||||
This very much comes down to a question of familiarity and (perceived)
|
||||
ease of use.
|
||||
|
||||
Supporters of :pep:`508` strings believe familiarity is important as
|
||||
the format has been in use for 5 years and in some variant for 15
|
||||
years (since the introduction of :pep:`345`). This would facilitate
|
||||
transitioning people to using this PEP as there would be one less new
|
||||
concept to learn. Supporters also think the format is reasonably
|
||||
ergonomic and understandable upon first glance, so using a DSL for it
|
||||
is not a major drawback.
|
||||
|
||||
Supporters of the exploded table format believe it has better
|
||||
ergonomics. Tooling which can validate TOML formats could also help
|
||||
detect errors in a ``pyproject.toml`` file while editing instead of
|
||||
waiting until the user has run a tool in the case of :pep:`508`'s DSL.
|
||||
Supporters also believe it is easier to read and reason (both in
|
||||
general and for first-time users). They also point out that other
|
||||
programming languages have adopted a format more like an exploded
|
||||
table thanks to their use of standardized configuration formats (e.g.
|
||||
`Rust <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html>`__,
|
||||
and `Dart <https://dart.dev/tools/pub/dependencies>`__). The thinking
|
||||
is that an exploded table format would be more familiar to people
|
||||
coming to Python from another programming language.
|
||||
Using structured TOML dictionaries to specify dependencies
|
||||
----------------------------------------------------------
|
||||
The format for specifying the dependencies of a project was the most
|
||||
hotly contested topic in terms of data format. It led to the creation
|
||||
of both :pep:`631` and :pep:`633` which represent what is in this PEP
|
||||
and using TOML dictionaries more extensively, respectively. The
|
||||
decision on those PEPs can be found at
|
||||
https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38.
|
||||
|
||||
The authors briefly considered supporting both formats, but decided
|
||||
that it would lead to confusion as people would need to be familiar
|
||||
with two formats instead of just one.
|
||||
|
||||
|
||||
Open Issues
|
||||
===========
|
||||
None at the moment.
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
|
|
|
|||
|
|
@ -3,12 +3,12 @@ Title: Dependency specification in pyproject.toml based on PEP 508
|
|||
Author: Ofek Lev <ofekmeister@gmail.com>
|
||||
Sponsor: Paul Ganssle <paul@ganssle.io>
|
||||
Discussions-To: https://discuss.python.org/t/5018
|
||||
Status: Draft
|
||||
Status: Accepted
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 20-Aug-2020
|
||||
Post-History: 20-Aug-2020
|
||||
|
||||
Resolution: https://discuss.python.org/t/how-to-specify-dependencies-pep-508-strings-or-a-table-in-toml/5243/38
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
|
@ -17,6 +17,10 @@ This PEP specifies how to write a project's dependencies in a
|
|||
``pyproject.toml`` file for packaging-related tools to consume
|
||||
using the `fields defined in PEP 621`_.
|
||||
|
||||
.. note::
|
||||
This PEP has been accepted and is expected to be merged into
|
||||
:pep:`621`.
|
||||
|
||||
Entries
|
||||
=======
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue