Skip to content
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

PEP 639: minor edits for clarity and consistency #3921

Closed
wants to merge 1 commit into from
Closed

PEP 639: minor edits for clarity and consistency #3921

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
44 changes: 20 additions & 24 deletions peps/pep-0639.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ Build and publishing tools SHOULD
check that the ``License-Expression`` field contains a valid SPDX expression,
including the validity of the particular license identifiers
(as :ref:`defined above <639-spdx>`).
Tools MAY halt execution and raise an error when an invalid expression is found.
Tools MAY raise an error when an invalid expression is found.
If tools choose to validate the SPDX expression, they also SHOULD
store a case-normalized version of the ``License-Expression``
field using the reference case for each SPDX license identifier and uppercase
Expand Down Expand Up @@ -367,12 +367,10 @@ Add ``License-File`` field
''''''''''''''''''''''''''

``License-File`` is an optional :term:`Core Metadata field`.
Each instance contains the string
representation of the path of a license-related file. The path is located
within the :term:`project source tree`, relative to the
:term:`project root directory`.
It is a multi-use field that may appear zero or
more times and each instance lists the path to one such file. Files specified
It is a multi-use field that may appear zero or more times, where each instance
contains the string representation of the path of a license-related file. The
path is located within the :term:`project source tree`, relative to the
:term:`project root directory`. Files specified
under this field could include license text, author/attribution information,
or other legal notices that need to be distributed with the package.

Expand All @@ -388,8 +386,8 @@ If a ``License-File`` is listed in a
- That file MUST be included in the :term:`distribution archive` at the
specified path relative to the root license directory.

- That file MUST be installed with the :term:`project` at that same relative
path.
- That file MUST be installed with the :term:`project` at that same path
relative to the root license directory.

- The specified relative path MUST be consistent between project source trees,
source distributions (sdists), built distributions (:term:`Wheel`\s) and
Expand Down Expand Up @@ -453,7 +451,7 @@ is deprecated and replaced by the more precise ``License-Expression`` field.

If the ``License-Expression`` field is present, build tools MAY raise an error
if one or more license classifiers
is included in a ``Classifier`` field, and MUST NOT add
are included in a ``Classifier`` field, and MUST NOT add
such classifiers themselves.

Otherwise, if this field contains a license classifier,
Expand Down Expand Up @@ -483,10 +481,10 @@ metadata under a ``[project]`` table in the ``pyproject.toml`` file.
Add string value to ``license`` key
'''''''''''''''''''''''''''''''''''

``license`` key in the ``[project]`` table is defined to contain a top-level
The ``license`` key in the ``[project]`` table is defined to contain a top-level
string value. It is a valid SPDX license expression as
:ref:`defined in this PEP <639-spdx>`.
Its value maps to the ``License-Expression`` field in the core metadata.
Its value maps to the ``License-Expression`` field in the Core Metadata.

Build tools SHOULD validate and perform case normalization of the expression
as described in the
Expand Down Expand Up @@ -518,7 +516,7 @@ Add ``license-files`` key
A new ``license-files`` key is added to the ``[project]`` table for specifying
paths in the project source tree relative to ``pyproject.toml`` to file(s)
containing licenses and other legal notices to be distributed with the package.
It corresponds to the ``License-File`` fields in the Core Metadata.
It corresponds to the ``License-File`` field in the Core Metadata.

Its value is an array of strings which MUST contain valid glob patterns,
as specified below:
Expand Down Expand Up @@ -624,7 +622,7 @@ the ``license-files`` key instead.

If the specified license ``file`` is present in the source tree,
build tools SHOULD use it to fill the ``License-File`` field
in the core metadata, and MUST include the specified file
in the Core Metadata, and MUST include the specified file
as if it were specified in a ``license-file`` field.
If the file does not exist at the specified path,
tools MUST raise an informative error as previously specified.
Expand All @@ -638,7 +636,7 @@ from a new version of the specification in a future PEP.
License files in project formats
--------------------------------

A few additions will be made to the existing specifications.
A few additions will be made to the existing specifications:

:term:`Project source tree`\s
Per :ref:`639-spec-source-metadata` section, the
Expand Down Expand Up @@ -668,12 +666,10 @@ A few additions will be made to the existing specifications.
:term:`Installed project`\s
The `Recording Installed Projects specification <installedspec_>`__ will be
updated to reflect that if the ``Metadata-Version`` is ``2.4`` or greater
and one or more ``License-File`` fields is specified, the ``.dist-info``
and one or more ``License-File`` fields is specified, the installed ``.dist-info``
directory MUST contain a ``licenses`` subdirectory which MUST contain
the files listed in the ``License-File`` fields in the ``METADATA`` file
at their respective paths relative to the ``licenses`` directory,
and that any files in this directory MUST be copied from wheels
by install tools.
at their respective paths relative to the ``licenses`` directory.
Comment on lines -671 to +672
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The clause "and that any files in this directory MUST be copied from wheels by install tools" has two potential interpretations:

  • Files declared via the License-File Core Metadata field in the wheel distribution MUST be copied into this directory. This isn't wrong, but it is redundant with the earlier text. Simply stating that we're talking about the installed .dist-info directory should suffice IMO.
  • Only files declared in the License-File Core Metadata field are permitted to be in this directory. If this is the case, I'd suggest adding the word "only" somewhere.

I initially read the line under the second interpretation, but that seems wrong? I'd appreciate your thoughts @befeleme.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I'm not the original author, let me provide another interpretation - how I see it: PEP doesn't specify nor forbid what else, except for the files listed under the License-File fields can be listed in the .dist-info/licenses directory, but it ensures that whatever is there (e.g. filled in by a build backend custom means), will always be installed with the copies of the software. Hence the partial redundancy of the wording.



.. _639-spec-converting-metadata:
Expand Down Expand Up @@ -718,10 +714,10 @@ The new ``license-files`` key in the ``[project]`` table of
``pyproject.toml`` will only have an effect once users and tools adopt it.

This PEP specifies that license files should be placed in a dedicated
``licenses`` subdir of ``.dist-info`` directory. This is new and ensures that
wheels following this PEP will have differently-located licenses relative to
those produced via the previous installer-specific behavior. This is further
supported by a new metadata version.
``licenses`` subdirectory of the ``.dist-info`` directory. This is new and
ensures that wheels following this PEP will have differently-located licenses
relative to those produced via the previous installer-specific behavior. This
is further supported by a new metadata version.

This also resolves current issues where license files are accidentally
replaced if they have the same names in different places, making wheels
Expand Down Expand Up @@ -777,7 +773,7 @@ packaging tools may warn them and inform them of the replacement,
Tools may also help with the conversion and suggest a license expression in
many common cases:

- The appendix :ref:`639-spec-mapping-classifiers-identifiers` provides
- The :ref:`639-spec-mapping-classifiers-identifiers` provides
Comment on lines -780 to +776
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the reference is rendered, the word "appendix" appears twice.

image

tool authors with recommendation on how to suggest a license expression
produced from legacy classifiers.

Expand Down
4 changes: 2 additions & 2 deletions peps/pep-0639/appendix-rejected-ideas.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,7 +459,7 @@ Name the subdirectory ``license_files``

Both ``licenses`` and ``license_files`` have been suggested as potential
names for the root license directory inside ``.dist-info`` of wheels and
installed projects. An initial draft of the PEP specified the former
installed projects. An initial draft of the PEP specified the latter
due to being slightly clearer and consistent with the
name of the Core Metadata field (``License-File``)
and the ``[project]`` table key (``license-files``).
Expand Down Expand Up @@ -543,7 +543,7 @@ The custom identifiers cannot be checked for correctness and users may think
they always have to prepend identifiers with ``LicenseRef``.
This would lead to tools producing invalid metadata.

However, Python packages are produced in many open and close
However, Python packages are produced in many open and closed
environments,
where it may be impossible to declare the license using only the small subset
of the allowed custom identifiers and where, for various reasons,
Expand Down
17 changes: 9 additions & 8 deletions peps/pep-0639/appendix-user-scenarios.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ widely used and allows anyone to do whatever they want with your work
To apply it, just paste `the text <chooseamitlicense_>`__ into a file named
``LICENSE.txt`` at the root of your repo, and add the year and your name to
the copyright line. Then, just add ``license = "MIT"`` under
``[project]`` in your ``pyproject.toml`` if your packaging tool supports it,
or in its config file/section. You're done!
``[project]`` in your ``pyproject.toml``. If your packaging tool does not
support the ``license`` project field in ``pyproject.toml``, you should use the
equivalent license field in your tool's configuration. You're done!


I want to distribute my project under a specific license
Expand Down Expand Up @@ -85,9 +86,9 @@ be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
otherwise, check the `SPDX license list <spdxlist_>`__ for the identifier
that matches the license used in your project.

Make sure to list your license files under ``license-files.paths``
or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
or else in your tool's configuration file.
Make sure to list your license files under ``license-files`` under
``[project]`` in ``pyproject.toml`` or the equivalent in your packaging tool's
configuration file.

See the :ref:`639-example-basic` for a simple but complete real-world demo
of how this works in practiced.
Expand Down Expand Up @@ -120,9 +121,9 @@ or ``License ::`` classifiers.

Also, make sure you add the full license text of all the licenses as files
somewhere in your project repository. List the
relative path or glob patterns to each of them under ``license-files.paths``
or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
(if your tool supports it), or else in your tool's configuration file.
relative path or glob patterns to each of them in ``license-files`` under
``[project]`` in ``pyproject.toml``
(if your tool supports it), or the equivalent in your tool's configuration file.

As an example, if your project was licensed MIT but incorporated
a vendored dependency (say, ``packaging``) that was licensed under
Expand Down