From bffa6a5987b738a77ba2f4cb08170ce5c850fd92 Mon Sep 17 00:00:00 2001 From: Richard Si Date: Fri, 23 Aug 2024 14:48:00 -0400 Subject: [PATCH] PEP 639: minor edits for clarity and consistency The main substantive edits are: - Removing references to the `license-files.globs` and `license-files.paths` fields that no longer exist in the current draft - Shortening the summary of changes to the recording installed distributions specification by removing a redundant (implied) clause --- peps/pep-0639.rst | 44 +++++++++++------------ peps/pep-0639/appendix-rejected-ideas.rst | 4 +-- peps/pep-0639/appendix-user-scenarios.rst | 17 ++++----- 3 files changed, 31 insertions(+), 34 deletions(-) diff --git a/peps/pep-0639.rst b/peps/pep-0639.rst index 8556c016e7d..59cdf14462a 100644 --- a/peps/pep-0639.rst +++ b/peps/pep-0639.rst @@ -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 @@ -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. @@ -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 @@ -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, @@ -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 @@ -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: @@ -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. @@ -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 @@ -668,12 +666,10 @@ A few additions will be made to the existing specifications. :term:`Installed project`\s The `Recording Installed Projects specification `__ 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. .. _639-spec-converting-metadata: @@ -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 @@ -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 tool authors with recommendation on how to suggest a license expression produced from legacy classifiers. diff --git a/peps/pep-0639/appendix-rejected-ideas.rst b/peps/pep-0639/appendix-rejected-ideas.rst index 92681925dca..35068c8d6b9 100644 --- a/peps/pep-0639/appendix-rejected-ideas.rst +++ b/peps/pep-0639/appendix-rejected-ideas.rst @@ -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``). @@ -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, diff --git a/peps/pep-0639/appendix-user-scenarios.rst b/peps/pep-0639/appendix-user-scenarios.rst index d5490296386..bd97a8609c0 100644 --- a/peps/pep-0639/appendix-user-scenarios.rst +++ b/peps/pep-0639/appendix-user-scenarios.rst @@ -49,8 +49,9 @@ widely used and allows anyone to do whatever they want with your work To apply it, just paste `the text `__ 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 @@ -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 `__ 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. @@ -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