diff --git a/pep-0621.rst b/pep-0621.rst index ca9fb7f2e..6ac40913e 100644 --- a/pep-0621.rst +++ b/pep-0621.rst @@ -14,7 +14,8 @@ Content-Type: text/x-rst Created: 22-Jun-2020 Post-History: 22-Jun-2020, 18-Oct-2020, - 24-Oct-2020 + 24-Oct-2020, + 31-Oct-2020 @@ -31,13 +32,27 @@ Motivation The key motivators of this PEP are: - Encourage users to specify core metadata statically for speed, - ease of specification, and deterministic consumption by build - back-ends + ease of specification, unambiguity, and deterministic consumption by + build back-ends - Provide a tool-agnostic way of specifying metadata for ease of learning and transitioning between build back-ends - Allow for more code sharing between build back-ends for the "boring parts" of a project's metadata +To speak specifically to the motivation for static metadata, that has +been an overall goal of the packaging ecosystem for some time. As +such, making it easy to specify metadata statically is important. This +also means that raising the cost of specifying data as dynamic is +acceptable as users should skew towards wanting to provide static +metadata. + +Requiring the distinction between static and dynamic metadata also +helps with disambiguation for when metadata isn't specified. When any +metadata *may* be dynamic, it means you never no if the absense of +metadata is on purpose or because it is to be provided later. By +requiring that dynamic metadata be specified, it disambiguates the +intent when metadata goes unspecified. + This PEP does **not** attempt to standardize all possible metadata required by a build back-end, only the metadata covered by the `core metadata`_ specification which are very common across projects @@ -82,10 +97,8 @@ metadata as specified in this PEP. If metadata is improperly specified then tools MUST raise an error to notify the user about their mistake. Data specified using this PEP is considered canonical. Tools CANNOT -remove or change data, but they MAY add to it. This allows for tools -to make data more accurate/static when possible. For example, a version -can become more specific when building a wheel (e.g. adding a local -version), but it cannot become less specific. +remove, add or change data that has been statically specified. Only +when a field is marked as `dynamic` may a tool provide a "new" value. Details @@ -216,10 +229,6 @@ error for unsupported content-types. The Python version requirements of the project. -Build back-ends MAY try to backfill appropriate -``Programming Language :: Python`` `trove classifiers`_ based on what -the user specified for this field. - ``license`` ''''''''''' - Format: Table @@ -244,10 +253,7 @@ error if the metadata specifies both keys. A practical string value for the ``license`` key has been purposefully left out to allow for a future PEP to specify support for SPDX_ expressions (the same logic applies to any sort of "type" field -specifying what license the ``file`` or ``text`` represents). If such -support comes to fruition and a tool can unambiguously identify the -license specified, then the tool MAY fill in the appropriate trove -classifiers. +specifying what license the ``file`` or ``text`` represents). ``authors``/``maintainers`` ''''''''''''''''''''''''''' @@ -286,7 +292,7 @@ Using the data to fill in `core metadata`_ is as follows: 3. If both ``email`` and ``name`` are provided, the value goes in ``Author-email``/``Maintainer-email`` as appropriate, with the format ``{name} <{email}>``. - +4. Multiple values should be separated by commas. ``keywords`` '''''''''''' @@ -320,9 +326,6 @@ The keywords for the project. `Trove classifiers`_ which apply to the project. -Build back-ends MAY automatically fill in extra trove classifiers -if the back-end can deduce the classifiers from the provided metadata. - ``urls`` '''''''' - Format: Table, with keys and values of strings @@ -641,13 +644,6 @@ other ecosystems without using terminology that is necessarily foreign to new programmers. It also prevents potential confusion with ``requires`` in the ``[build-system]`` table as specified in :pep:`518`. -Support ``Maintainers``/``Maintainers-email`` ---------------------------------------------- -When discussing how to support ``Authors``/``Authors-email``, the question was -brought up as to how exactly authors differed from maintainers. As this was -never clearly defined and no one could come up with a good definition, the -decision was made to drop the concept of maintainers. - Drop ``maintainers`` to unify with ``authors`` ---------------------------------------------- As the difference between ``Authors`` and ``Maintainers`` fields in @@ -701,6 +697,18 @@ though, the idea of updating ``pyproject.toml`` was not generally liked, and so the idea was rejected in favour of separately pursuing standardizing metadata in sdists. +Allow tools to add/extend data +------------------------------ +In an earlier version of this PEP, tools were allowed to extend data +for fields. For instance, build back-ends could take the version +number and add a local version for when they built the wheel. Tools +could also add more trove classifiers for things like the license or +supported Python versions. + +In the end, though, it was thought better to start out stricter and +contemplate loosening how static the data could be considered based +on real-world usage. + Open Issues ===========