From 0efd2570741ab48bf6ba3243bf62ea05d53445a3 Mon Sep 17 00:00:00 2001 From: Karolina Surma <33810531+befeleme@users.noreply.github.com> Date: Fri, 10 May 2024 06:04:17 +0200 Subject: [PATCH] PEP 639: Post-split edits (language simplification, deeper edits of sections) (#3743) Co-authored-by: C.A.M. Gerlach Co-authored-by: Jelle Zijlstra --- peps/pep-0639.rst | 1023 +++++++++------------ peps/pep-0639/appendix-examples.rst | 8 +- peps/pep-0639/appendix-license-survey.rst | 29 +- peps/pep-0639/appendix-rejected-ideas.rst | 608 +++++------- peps/pep-0639/appendix-user-scenarios.rst | 35 +- 5 files changed, 744 insertions(+), 959 deletions(-) diff --git a/peps/pep-0639.rst b/peps/pep-0639.rst index a3042fc64..42a922b7e 100644 --- a/peps/pep-0639.rst +++ b/peps/pep-0639.rst @@ -2,12 +2,12 @@ PEP: 639 Title: Improving License Clarity with Better Package Metadata Author: Philippe Ombredanne , C.A.M. Gerlach , + Karolina Surma , PEP-Delegate: Brett Cannon Discussions-To: https://discuss.python.org/t/12622 Status: Draft Type: Standards Track Topic: Packaging -Content-Type: text/x-rst Created: 15-Aug-2019 Post-History: `15-Aug-2019 `__, `17-Dec-2021 `__, @@ -18,41 +18,34 @@ Post-History: `15-Aug-2019 `__, Abstract ======== -This PEP defines a specification for how licenses are documented in the -`core metadata `__, with -:ref:`license expression strings <639-spec-field-license-expression>` using -`SPDX identifiers `__ in a new ``License-Expression`` field. -This will make license declarations simpler and less ambiguous for -package authors to create, end users to read and understand, and -tools to programmatically process. +This PEP defines a specification how licenses are documented in the Python +projects. -The PEP also: +To achieve that, it: -- :ref:`Formally specifies <639-spec-field-license-file>` - a new ``License-File`` field, and defines how license files should be - :ref:`included in distributions <639-spec-project-formats>`, - as already used by the Wheel and Setuptools projects. +- Adopts the `SPDX license expression syntax <639-spdx_>`__ as a + means of expressing the license for a Python project. -- Deprecates the legacy ``License`` :ref:`field <639-spec-field-license>` - and ``license ::`` :ref:`classifiers <639-spec-field-classifier>`. +- Defines how to include license files within the projects, source and built + distributions. -- :ref:`Adds and deprecates <639-spec-source-metadata>` the corresponding keys - in the ``pyproject.toml`` ``[project]`` table. +- Specifies the necessary changes to :term:`Core Metadata` and + the corresponding :term:`Pyproject Metadata key`\s -- :ref:`Provides clear guidance <639-spec-converting-metadata>` for authors and - tools converting legacy license metadata, adding license files and - validating license expressions. +- Describes the necessary changes to related specifications, + namely the `source distribution (sdist) `__, + `built distribution (wheel) `__ and + `installed project `__ standards. -- Describes a :ref:`reference implementation <639-reference-implementation>` - and analyzes numerous :ref:`potential alternatives <639-rejected-ideas>`. +- :ref:`Provides guidance <639-spec-converting-metadata>` + for authors and tools converting legacy license metadata. -The changes in this PEP will update the -`core metadata `__ to version 2.4, modify the -`project (source) metadata specification `__, -and make minor additions to the `source distribution (sdist) `__, -`built distribution (wheel) `__ and -`installed project `__ standards. +This will make license declaration simpler and less ambiguous for +package authors to create, end users to understand, +and tools to programmatically process. +The changes will update the +`Core Metadata specification `__ to version 2.4. .. _639-goals: @@ -60,27 +53,14 @@ Goals ===== This PEP's scope is limited to covering new mechanisms for documenting -the license of a distribution package, specifically defining: +the license of a :term:`distribution package`, specifically defining: -- A means of specifying a SPDX license expression. -- A method of including license texts in distributions and installed projects. +- A means of specifying a SPDX :term:`license expression`. +- A method of including license texts in :term:`distribution package`\s + and installed :term:`Project`\s. -The changes to the core metadata specification that this PEP requires have been -designed to minimize impact and maximize backward compatibility. -This specification builds off of existing ways to document licenses that are -already in use in popular tools (e.g. adding support to core metadata for the -``License-File`` field :ref:`already used <639-license-doc-setuptools-wheel>` -in the Wheel and Setuptools projects) and by some package authors -(e.g. storing an SPDX license expression in the existing ``License`` field). - -In addition to these proposed changes, this PEP contains guidance for tools -handling and converting these metadata, a tutorial for package authors -covering various common use cases, detailed examples of them in use, -and a comprehensive survey of license documentation in Python and other -languages. - -It is the intent of the PEP authors to work closely with tool maintainers to -implement the recommendations for validation and warnings specified here. +The changes that this PEP requires have been designed to minimize impact and +maximize backward compatibility. .. _639-non-goals: @@ -88,27 +68,18 @@ implement the recommendations for validation and warnings specified here. Non-Goals ========= -This PEP is neutral regarding the choice of license by any particular -package author. This PEP makes no recommendation for specific licenses, -and does not require the use of a particular license documentation convention. +This PEP doesn't recommend any particular license to be chosen by any +particular package author. -Rather, the SPDX license expression syntax proposed in this PEP provides a -simpler and more expressive mechanism to accurately document any kind of -license that applies to a Python package, whether it is open source, -free/libre, proprietary, or a combination of such. +If projects decide not to use the new fields, no additional restrictions are +imposed by this PEP when uploading to PyPI. -This PEP also does not impose any additional restrictions when uploading to -PyPI, unless projects choose to make use of the new fields. - -Instead, it is intended to document best practices already in use, extend them -to use a new formally-specified and supported mechanism, and provide guidance -for packaging tools on how to hand the transition and inform users accordingly. - -This PEP also is not about license documentation in files inside projects, +This PEP also is not about license documentation for individual files, though this is a :ref:`surveyed topic <639-license-doc-source-files>` -in an appendix, and nor does it intend to cover cases where the source and -binary distribution packages don't have :ref:`the same licenses -<639-rejected-ideas-difference-license-source-binary>`. +in an appendix, nor does it intend to cover cases where the +:term:`source distribution ` and +:term:`binary distribution` packages don't have +:ref:`the same licenses <639-rejected-ideas-difference-license-source-binary>`. .. _639-motivation: @@ -117,16 +88,13 @@ Motivation ========== Software must be licensed in order for anyone other than its creator to -download, use, share and modify it, so providing accurate license information -to Python package users is an important matter. -Today, there are multiple fields where -licenses are documented in core metadata, and there are limitations to what -can be expressed in each of them. This often leads to confusion and a lack of -clarity, both for package authors and end users. +download, use, share and modify it. +Today, there are multiple fields where licenses +are documented in :term:`Core Metadata`, +and there are limitations to what can be expressed in each of them. +This often leads to confusion both for package authors +and end users, including distribution re-packagers. -Many package authors have expressed difficulty and frustrations due to the -limited capabilities to express licensing in project metadata, and this -creates further trouble for Linux and BSD distribution re-packagers. This has triggered a number of license-related discussions and issues, including on `outdated and ambiguous PyPI classifiers `__, `license interoperability with other ecosystems `__, @@ -134,90 +102,77 @@ including on `outdated and ambiguous PyPI classifiers `__, `limited support for license files in the Wheel project `__, and `the lack of clear, precise and standardized license metadata `__. -The current license classifiers address some common cases, and could -be extended to include the full range of current SPDX identifiers -while deprecating the many ambiguous classifiers -(including some popular and problematic ones, -such as ``License :: OSI Approved :: BSD License``). -However, this requires a substantial amount of effort -to duplicate the SPDX license list and keep it in sync. -Furthermore, it is effectively a hard break in backward compatibility, -forcing a huge proportion of package authors to immediately update to new -classifiers (in most cases, with many possible choices that require closely -examining the project's license) immediately when PyPI deprecates the old ones. - -Furthermore, this only covers simple packages entirely under a single license; -it doesn't address the substantial fraction of common projects that vendor -dependencies (e.g. Setuptools), offer a choice of licenses (e.g. Packaging) -or were relicensed, adapt code from other projects or contain fonts, images, -examples, binaries or other assets under other licenses. It also requires -both authors and tools understand and implement the PyPI-specific bespoke -classifier system, rather than using short, easy to add and standardized -SPDX identifiers in a simple text field, as increasingly widely adopted by -most other packaging systems to reduce the overall burden on the ecosystem. -Finally, this does not provide as clear an indicator that a package -has adopted the new system, and should be treated accordingly. - -On average, Python packages tend to have more ambiguous and missing license -information than other common ecosystems (such as npm, Maven or -Gem). This is supported by the `statistics page `__ of the +As a result, on average, Python packages tend to have more ambiguous and +missing license information than other common ecosystems. This is supported by +the `statistics page `__ of the `ClearlyDefined project `__, an -`Open Source Initiative `__ incubated effort to help +`Open Source Initiative `__ effort to help improve licensing clarity of other FOSS projects, covering all packages from PyPI, Maven, npm and Rubygems. +The current license classifiers could be extended to include the full range of +the SPDX identifiers while deprecating the ambiguous classifiers +(such as ``License :: OSI Approved :: BSD License``). + +However, there are multiple arguments against such an approach: + +- It requires a great effort to duplicate the SPDX license list and keep it in + sync. + +- It is a hard break in backward compatibility, forcing package authors + to update to new classifiers immediately when PyPI deprecates the old ones. + +- It only covers packages under a single license; + it doesn't address projects that vendor dependencies (e.g. Setuptools), + offer a choice of licenses (e.g. Packaging) or were relicensed, + adapt code from other projects or contain fonts, images, + examples, binaries or other assets under other licenses. + +- It requires both authors and tools understand and implement the PyPI-specific + classifier system. + +- It does not provide as clear an indicator that a package + has adopted the new system, and should be treated accordingly. + .. _639-rationale: Rationale ========= -A survey of existing license metadata definitions in use in the Python -ecosystem today is provided in -:ref:`an appendix <639-license-doc-python>` of this PEP, -and license documentation in a variety of other packaging systems, -Linux distros, languages ecosystems and applications is surveyed in -:ref:`another appendix <639-license-doc-other-projects>`. +A survey was conducted to map the existing license metadata +definitions in the :ref:`Python ecosystem <639-license-doc-python>` and a +:ref:`variety of other packaging systems, Linux distributions, +language ecosystems and applications <639-license-doc-other-projects>`. -There are a few takeaways from the survey, which have guided the design -and recommendations of this PEP: +The takeaways from the survey have guided the recommendations of this PEP: -- Most package formats use a single ``License`` field. +- SPDX and SPDX-like syntaxes are the most popular :term:`license expression`\s + in many modern package systems. -- Many modern package systems use some form of license expression syntax to - optionally combine more than one license identifier together. - SPDX and SPDX-like syntaxes are the most popular in use. +- Most Free and Open Source Software licenses require package authors to + include their full text in a :term:`Distribution Package`. -- SPDX license identifiers are becoming the de facto way to reference common - licenses everywhere, whether or not a full license expression syntax is used. +Therefore, this PEP introduces two new Core Metadata fields: -- Several package formats support documenting both a license expression and the - paths of the corresponding files that contain the license text. Most Free and - Open Source Software licenses require package authors to include their full - text in a distribution. +- :ref:`License-Expression <639-spec-field-license-expression>` that + provides an unambiguous way to express the license of a package + using SPDX license expressions. -The use of a new ``License-Expression`` field will provide an intuitive, -structured and unambiguous way to express the license of a -package using a well-defined syntax and well-known license identifiers. -Similarly, a formally-specified ``License-File`` field offers a standardized -way to ensure that the full text of the license(s) are included with the -package when distributed, as legally required, and allows other tools consuming -the core metadata to unambiguously locate a distribution's license files. +- :ref:`License-File <639-spec-field-license-file>` that + offers a standardized way to include the full text of the license(s) + with the package when distributed, + and allows other tools consuming the :term:`Core Metadata` + to locate a :term:`distribution archive`'s license files. -While dramatically simplifying and improving the present Python license -metadata story, this specification standardizes and builds upon +Furthermore, this specification builds upon existing practice in the `Setuptools `__ and `Wheel `__ projects. -Furthermore, an up-to-date version of the current draft of this PEP is -`already successfully implemented `__ in the popular -PyPA `Hatch `__ packaging tool, and an earlier draft of the -license files portion is `implemented in Setuptools `__. - -Over time, encouraging the use of these fields and deprecating the ambiguous, -duplicative and confusing legacy alternatives will help Python software -publishers improve the clarity, accuracy and portability of their licensing -practices, to the benefit of package authors, consumers and redistributors -alike. +An up-to-date version of the current draft of this PEP is +`implemented `__ in the +`Hatch `__ packaging tool, and an earlier draft of the +:ref:`license files portion <639-spec-field-license-file>` +is `implemented in Setuptools `__. .. _639-terminology: @@ -225,128 +180,63 @@ alike. Terminology =========== -This PEP seeks to clearly define the terms it uses, given that some have -multiple established meanings (e.g. import vs. distribution package, -wheel *format* vs. Wheel *project*); are related and often used -interchangeably, but have critical distinctions in meaning -(e.g. ``[project]`` *key* vs. core metadata *field*); are existing concepts -that don't have formal terms/definitions (e.g. project/source metadata vs. -distribution/built metadata, build vs. publishing tools), or are new concepts -introduced here (e.g. license expression/identifier). - -This PEP also uses terms defined in the -`PyPA PyPUG Glossary `__ -(specifically *built/binary distribution*, *distribution package*, -*project* and *source distribution*), and by the `SPDX Project `__ -(*license identifier*, *license expression*). - The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in :rfc:`2119`. -Terms are listed here in their full versions; -related words (``Rel:``) are in parenthesis, -including short forms (``Short:``), sub-terms (``Sub:``) and common synonyms -for the purposes of this PEP (``Syn:``). -**Core Metadata** *(Syn: Package Metadata, Sub: Distribution Metadata)* - The `PyPA specification `__ and the set of metadata fields - it defines that describe key static attributes of distribution packages - and installed projects. +.. _639-terminology-license: - The **distribution metadata** refers to, more specifically, the concrete form - core metadata takes when included inside a distribution archive - (``PKG-INFO`` in a sdist and ``METADATA`` in a wheel) or installed project - (``METADATA``). +License terms +------------- -**Core Metadata Field** *(Short: Metadata Field/Field)* - A single key-value pair, or sequence of such with the same key, as defined - by the `core metadata specification `__. - Notably, distinct from a ``pyproject.toml`` ``[project]`` table *key*. +The license-related terminology draws heavily from the `SPDX Project `__, +particularly :term:`license identifier` and :term:`license expression`. -**Distribution Package** *(Sub: Package, Distribution Archive)* - (`See PyPUG `__) - In this PEP, **package** is used to refer to the abstract concept of a - distributable form of a Python project, while **distribution** more - specifically references the physical **distribution archive**. +.. glossary:: -**License Classifier** - A `PyPI Trove classifier `__ - (as `described in the core metadata specification - `__) - which begins with ``License ::``, currently used to indicate - a project's license status by including it as a ``Classifier`` - in the core metadata. + license classifier + A `PyPI Trove classifier `__ + (as :ref:`described ` + in the :term:`Core Metadata` specification) + which begins with ``License ::``. -**License Expression** *(Syn: SPDX Expression)* - A string with valid `SPDX license expression syntax `__ - including any SPDX license identifiers as defined here, which describes - a project's license(s) and how they relate to one another. Examples: - ``GPL-3.0-or-later``, ``MIT AND (Apache-2.0 OR BSD-2-clause)`` + license expression + SPDX expression + A string with valid `SPDX license expression syntax `__ + including one or more SPDX :term:`license identifier`\(s), + which describes a :term:`Project`'s license(s) + and how they inter-relate. + Examples: + ``GPL-3.0-or-later``, + ``MIT AND (Apache-2.0 OR BSD-2-clause)`` -**License Identifier** *(Syn: License ID/SPDX Identifier)* - A valid `SPDX short-form license identifier `__, as described in the - :ref:`639-spec-field-license-expression` section of this PEP; briefly, - this includes all valid SPDX identifiers and the ``LicenseRef-Public-Domain`` - and ``LicenseRef-Proprietary`` strings. Examples: ``MIT``, ``GPL-3.0-only`` + license identifier + SPDX identifier + A valid `SPDX short-form license identifier `__, + as described in the + :ref:`639-spec-field-license-expression` section of this PEP. + This includes all valid SPDX identifiers and + the strings ``LicenseRef-Public-Domain`` and ``LicenseRef-Proprietary``. + Examples: + ``MIT``, + ``GPL-3.0-only`` -**Project** *(Sub: Project Source Tree, Installed Project)* - (`See PyPUG `__) - Here, a **project source tree** refers to the on-disk format of - a project used for development, while an **installed project** is the form a - project takes once installed from a distribution, as - `specified by PyPA `__. - -**Project Source Metadata** *(Sub: Project Table Metadata, Key, Subkey)* - Core metadata defined by the package author in the project source tree, - as top-level keys in the ``[project]`` table of a ``pyproject.toml`` file, - in the ``[metadata]`` table of ``setup.cfg``, or the equivalent for other - build tools. - - The **Project Table Metadata**, or ``pyproject.toml`` ``[project]`` metadata, - refers specifically to the former, as defined by the - `PyPA Declaring Project Metadata specification `__ - and originally specified in :pep:`621`. - A **Project Table Key**, or an unqualified *key* refers specifically to - a top-level ``[project]`` key - (notably, distinct from a core metadata *field*), - while a **subkey** refers to a second-level key in a table-valued - ``[project]`` key. - -**Root License Directory** *(Short: License Directory)* - The directory under which license files are stored in a project/distribution - and the root directory that their paths, as recorded under the - ``License-File`` core metadata fields, are relative to. - Defined here to be the project root directory for source trees and source - distributions, and a subdirectory named ``licenses`` of the directory - containing the core metadata (i.e., the ``.dist-info/licenses`` - directory) for built distributions and installed projects. - -**Tool** *(Sub: Packaging Tool, Build Tool, Install Tool, Publishing Tool)* - A program, script or service executed by the user or automatically that - seeks to conform to the specification defined in this PEP. - - A **packaging tool** refers to a tool used to build, publish, - install, or otherwise directly interact with Python packages. - - A **build tool** is a packaging tool used to generate a source or built - distribution from a project source tree or sdist, when directly invoked - as such (as opposed to by end-user-facing install tools). - Examples: Wheel project, :pep:`517` backends via ``build`` or other - package-developer-facing frontends, calling ``setup.py`` directly. - - An **install tool** is a packaging tool used to install a source or built - distribution in a target environment. Examples include the PyPA pip and - ``installer`` projects. - - A **publishing tool** is a packaging tool used to upload distribution - archives to a package index, such as Twine for PyPI. - -**Wheel** *(Short: wheel, Rel: wheel format, Wheel project)* - Here, **wheel**, the standard built distribution format introduced in - :pep:`427` and `specified by the PyPA `__, will be referred to in - lowercase, while the `Wheel project `__, its reference - implementation, will be referred to as such with **Wheel** in Title Case. + root license directory + license directory + The directory under which license files are stored in a + :term:`project source tree`, :term:`distribution archive` + or :term:`installed project`. + Also, the root directory that their paths + recorded in the :ref:`License-File <639-spec-field-license-file>` + :term:`Core Metadata field` are relative to. + Defined to be the :term:`project root directory` + for a :term:`project source tree` or + :term:`source distribution `; + and a subdirectory named ``licenses`` of + the directory containing the :term:`built metadata`— + i.e., the ``.dist-info/licenses`` directory— + for a :term:`Built Distribution` or :term:`installed project`. .. _639-specification: @@ -354,72 +244,38 @@ for the purposes of this PEP (``Syn:``). Specification ============= -The changes necessary to implement the improved license handling outlined in -this PEP include those in both -:ref:`distribution package metadata <639-spec-core-metadata>`, -as defined in the `core metadata specification `__, and -:ref:`author-provided project source metadata <639-spec-source-metadata>`, -as defined in the `project source metadata specification <_pep621spec>`__ -(and originally introduced in :pep:`621`). +The changes necessary to implement this PEP include: -Further, :ref:`minor additions <639-spec-project-formats>` to the -source distribution (sdist), built distribution (wheel) and installed project -specifications will help document and clarify the already allowed, -now formally standardized behavior in these respects. -Finally, :ref:`guidance is established <639-spec-converting-metadata>` -for tools handling and converting legacy license metadata to license -expressions, to ensure the results are consistent, correct and unambiguous. +- additions to :ref:`Core Metadata <639-spec-core-metadata>`, + as defined in the `specification `__. + +- additions to the author-provided + :ref:`project source metadata <639-spec-source-metadata>`, + as defined in the `specification `__. + +- :ref:`minor additions <639-spec-project-formats>` to the + source distribution (sdist), built distribution (wheel) and installed project + specifications. + +- :ref:`guide for tools <639-spec-converting-metadata>` + handling and converting legacy license metadata to license + expressions, to ensure the results are consistent and correct. Note that the guidance on errors and warnings is for tools' default behavior; they MAY operate more strictly if users explicitly configure them to do so, such as by a CLI flag or a configuration option. -.. _639-spec-core-metadata: +.. _639-spdx: -Core metadata -------------- +SPDX license expression syntax +------------------------------ -The `PyPA Core Metadata specification `__ defines the names -and semantics of each of the supported fields in the distribution metadata of -Python distribution packages and installed projects. - -This PEP :ref:`adds <639-spec-field-license-expression>` the -``License-Expression`` field, -:ref:`adds <639-spec-field-license-file>` the ``License-File`` field, -:ref:`deprecates <639-spec-field-license>` the ``License`` field, -and :ref:`deprecates <639-spec-field-classifier>` the license classifiers -in the ``Classifier`` field. - -The error and warning guidance in this section applies to build and -publishing tools; end-user-facing install tools MAY be more lenient than -mentioned here when encountering malformed metadata -that does not conform to this specification. - -As it adds new fields, this PEP updates the core metadata to version 2.4. - - -.. _639-spec-field-license-expression: - -Add ``License-Expression`` field -'''''''''''''''''''''''''''''''' - -The ``License-Expression`` optional field is specified to contain a text string -that is a valid SPDX license expression, as defined herein. - -Publishing tools SHOULD issue an informational warning if this field is -missing, and MAY raise an error. Build tools MAY issue a similar warning, -but MUST NOT raise an error. - -.. _639-license-expression-definition: - -A license expression is a string using the SPDX license expression syntax as +This PEP adopts the SPDX license expression syntax as documented in the `SPDX specification `__, either Version 2.2 or a later compatible version. -When used in the ``License-Expression`` field and as a specialization of -the SPDX license expression definition, a license expression can use the -following license identifiers: +A license expression can use the following :term:`license identifier`\s: - Any SPDX-listed license short-form identifiers that are published in the `SPDX License List `__, version 3.17 or any later compatible @@ -429,15 +285,64 @@ following license identifiers: - The ``LicenseRef-Public-Domain`` and ``LicenseRef-Proprietary`` strings, to identify licenses that are not included in the SPDX license list. -When processing the ``License-Expression`` field to determine if it contains -a valid license expression, build and publishing tools: + +Examples of valid SPDX expressions: + +.. code-block:: none + + MIT + BSD-3-Clause + MIT AND (Apache-2.0 OR BSD-2-clause) + MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause) + GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause + LicenseRef-Public-Domain OR CC0-1.0 OR Unlicense + LicenseRef-Proprietary + + +Examples of invalid SPDX expressions: + +.. code-block:: none + + Use-it-after-midnight + Apache-2.0 OR 2-BSD-Clause + + +.. _639-spec-core-metadata: + +Core Metadata +------------- + +The error and warning guidance in this section applies to build and +publishing tools; end-user-facing install tools MAY be less strict than +mentioned here when encountering malformed metadata +that does not conform to this specification. + +As it adds new fields, this PEP updates the Core Metadata version to 2.4. + + +.. _639-spec-field-license-expression: + +Add ``License-Expression`` field +'''''''''''''''''''''''''''''''' + +The ``License-Expression`` optional :term:`Core Metadata field` +is specified to contain a text string +that is a valid SPDX :term:`license expression`, as defined by this PEP. + +Publishing tools SHOULD issue an informational warning if this field is +missing, and MAY raise an error. Build tools MAY issue a similar warning, +but MUST NOT raise an error. + +A license expression is an SPDX expression as :ref:`defined above <639-spdx>`. + +When processing the ``License-Expression`` field, build and publishing tools: - SHOULD halt execution and raise an error if: - The field does not contain a valid license expression - One or more license identifiers are not valid - (as :ref:`defined above <639-license-expression-definition>`) + (as :ref:`defined above <639-spdx>`) - SHOULD report an informational warning, and publishing tools MAY raise an error, if one or more license identifiers have been marked as deprecated in @@ -451,10 +356,12 @@ a valid license expression, build and publishing tools: the normalization process results in changes to the ``License-Expression`` field contents. -For all newly-upload distributions that include a -``License-Expression`` field, the `Python Package Index (PyPI) `__ MUST -validate that it contains a valid, case-normalized license expression with -valid identifiers (as defined here) and MUST reject uploads that do not. +For all newly-uploaded :term:`distribution archive`\s +that include a ``License-Expression`` field, +the `Python Package Index (PyPI) `__ MUST +validate that they contain a valid, case-normalized license expression with +valid identifiers (as :ref:`defined above <639-spdx>`) +and MUST reject uploads that do not. PyPI MAY reject an upload for using a deprecated license identifier, so long as it was deprecated as of the above-mentioned SPDX License List version. @@ -465,46 +372,54 @@ version. Add ``License-File`` field '''''''''''''''''''''''''' -Each instance of the ``License-File`` optional field is specified to contain -the string representation of the path in the project source tree, relative to -the project root directory, of a license-related file. +``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, each instance listing the path to one such file. Files specified +more times and each instance lists the path to one such file. Files specified under this field could include license text, author/attribution information, or other legal notices that need to be distributed with the package. As :ref:`specified by this PEP <639-spec-project-formats>`, its value -is also that file's path relative to the root license directory in both -installed projects and the standardized distribution package types. -In other legacy, non-standard or new distribution package formats and -mechanisms of accessing and storing core metadata, the value MAY correspond -to the license file path relative to a format-defined root license directory. -Alternatively, it MAY be treated as a unique abstract key to access the -license file contents by another means, as specified by the format. +is also that file's path relative to the :term:`root license directory` +in both :term:`installed project`\s +and the standardized :term:`Distribution Package` types. -If a ``License-File`` is listed in a source or built distribution's core -metadata, that file MUST be included in the distribution at the specified path -relative to the root license directory, and MUST be installed with the -distribution at that same relative path. +If a ``License-File`` is listed in a +:term:`Source Distribution ` or +:term:`Built Distribution`'s Core Metadata: -The specified relative path MUST be consistent between project source trees, -source distributions (sdists), built distributions (wheels) and installed -projects. Therefore, inside the root license directory, packaging tools -MUST reproduce the directory structure under which the -source license files are located relative to the project root. +- That file MUST be included in the :term:`distribution archive` at the + specified path relative to the root license directory. -Path delimiters MUST be the forward slash character (``/``), -and parent directory indicators (``..``) MUST NOT be used. -License file content MUST be UTF-8 encoded text. +- That file MUST be installed with the :term:`project` at that same relative + path. + +- The specified relative path MUST be consistent between project source trees, + source distributions (sdists), built distributions (:term:`Wheel`\s) and + installed projects. + +- Inside the root license directory, packaging tools MUST reproduce the + directory structure under which the source license files are located + relative to the project root. + +- Path delimiters MUST be the forward slash character (``/``), + and parent directory indicators (``..``) MUST NOT be used. + +- License file content MUST be UTF-8 encoded text. Build tools MAY and publishing tools SHOULD produce an informative warning if a built distribution's metadata contains no ``License-File`` entries, and publishing tools MAY but build tools MUST NOT raise an error. -For all newly-uploaded distribution packages that include one or more -``License-File`` fields and declare a ``Metadata-Version`` of ``2.4`` or -higher, PyPI SHOULD validate that the specified files are present in all -uploaded distributions, and MUST reject uploads that do not validate. +For all newly-uploaded :term:`distribution archive`\s that include one or more +``License-File`` fields in their Core Metadata +and declare a ``Metadata-Version`` of ``2.4`` or higher, +PyPI SHOULD validate that all specified files are present in that +:term:`distribution archive`\s, +and MUST reject uploads that do not validate. .. _639-spec-field-license: @@ -512,22 +427,24 @@ uploaded distributions, and MUST reject uploads that do not validate. Deprecate ``License`` field ''''''''''''''''''''''''''' -The legacy unstructured-text ``License`` field is deprecated and replaced by -the new ``License-Expression`` field. Build and publishing tools MUST raise -an error if both these fields are present and their values are not identical, +The legacy unstructured-text ``License`` :term:`Core Metadata field` +is deprecated and replaced by the new ``License-Expression`` field. +Build and publishing tools MUST raise an error +if both these fields are present and their values are not identical, including capitalization and excluding leading and trailing whitespace. If only the ``License`` field is present, such tools SHOULD issue a warning informing users it is deprecated and recommending ``License-Expression`` instead. -For all newly-uploaded distributions that include a +For all newly-uploaded :term:`distribution archive`\s that include a ``License-Expression`` field, the `Python Package Index (PyPI) `__ MUST reject any that specify a ``License`` field and the text of which is not -identical to that of ``License-Expression``, as defined in this section. +identical to that of ``License-Expression``, +as :ref:`defined here <639-spdx>`. -Along with license classifiers, the ``License`` field may be removed from a -new version of the specification in a future PEP. +The ``License`` field may be removed from a new version of the specification +in a future PEP. .. _639-spec-field-classifier: @@ -535,8 +452,9 @@ new version of the specification in a future PEP. Deprecate license classifiers ''''''''''''''''''''''''''''' -Using license `classifiers `__ in the ``Classifier`` field -(`described in the core metadata specification `__) +Using :term:`license classifier`\s +in the ``Classifier`` :term:`Core Metadata field` +(`described in the Core Metadata specification `__) is deprecated and replaced by the more precise ``License-Expression`` field. If the ``License-Expression`` field is present, build tools SHOULD and @@ -557,8 +475,8 @@ reject any that also specify any license classifiers. New license classifiers MUST NOT be `added to PyPI `__; users needing them SHOULD use the ``License-Expression`` field instead. -Along with the ``License`` field, license classifiers may be removed from a -new version of the specification in a future PEP. +License classifiers may be removed from a new version of the specification +in a future PEP. .. _639-spec-source-metadata: @@ -566,41 +484,46 @@ new version of the specification in a future PEP. Project source metadata ----------------------- -As originally introduced in :pep:`621`, the -`PyPA Declaring Project Metadata specification `__ -defines how to declare a project's source -metadata under a ``[project]`` table in the ``pyproject.toml`` file for -build tools to consume and output distribution core metadata. - -This PEP :ref:`adds <639-spec-key-license-expression>` -a top-level string value for the ``license`` key, -:ref:`adds <639-spec-key-license-files>` the new ``license-files`` key -and :ref:`deprecates <639-spec-key-license>` -the table value for the ``license`` key -along with its corresponding table subkeys, ``text`` and ``file``. +This PEP specifies changes to the project's source +metadata under a ``[project]`` table in the ``pyproject.toml`` file. -.. _639-spec-key-license-expression: +.. _639-spec-key-license-text: Add string value to ``license`` key ''''''''''''''''''''''''''''''''''' -A top-level string value is defined -for the ``license`` key in the ``[project]`` table, -which is specified to be a valid SPDX license expression, -as :ref:`defined previously <639-license-expression-definition>`. +``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. Build tools SHOULD validate the expression as described in the :ref:`639-spec-field-license-expression` section, outputting an error or warning as specified. -When generating the core metadata, tools MUST perform case normalization. +When generating the Core Metadata, tools MUST perform case normalization. If a top-level string value for the ``license`` key is present and valid, for purposes of backward compatibility -tools MAY back-fill the ``License`` core metadata field +tools MAY back-fill the ``License`` Core Metadata field with the normalized value of the ``license`` key. +Examples: + +.. code-block:: toml + + [project] + license = "MIT" + + [project] + license = "MIT AND (Apache-2.0 OR BSD-2-clause)" + + [project] + license = "MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)" + + [project] + license = "LicenseRef-Proprietary" + .. _639-spec-key-license-files: @@ -610,7 +533,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`` fields in the Core Metadata. Its value is a table, which if present MUST contain one of two optional, mutually exclusive subkeys, ``paths`` and ``globs``; if both are specified, @@ -619,11 +542,6 @@ contains verbatim file paths, and the ``globs`` subkey valid glob patterns, which MUST be parsable by the ``glob`` `module `__ in the Python standard library. -**Note**: To avoid ambiguity, confusion and (per :pep:`20`, the Zen of Python) -"more than one (obvious) way to do it", allowing a flat array of strings -as the value for the ``license-files`` key has been -:ref:`left out for now <639-license-files-allow-flat-array>`. - Path delimiters MUST be the forward slash character (``/``), and parent directory indicators (``..``) MUST NOT be used. Tools MUST assume that license file content is valid UTF-8 encoded text, @@ -639,7 +557,7 @@ If the ``paths`` subkey is a non-empty array, build tools: - MUST NOT match any additional license files beyond those explicitly statically specified by the user under the ``paths`` subkey. -- MUST list each file path under a ``License-File`` field in the core metadata. +- MUST list each file path under a ``License-File`` field in the Core Metadata. - MUST raise an error if one or more paths do not correspond to a valid file in the project source that can be copied into the distribution archive. @@ -656,7 +574,7 @@ If the ``globs`` subkey is a non-empty array, build tools: determined to be backup, temporary, hidden, OS-generated or VCS-ignored. - MUST list each matched file path under a ``License-File`` field in the - core metadata. + Core Metadata. - SHOULD issue a warning and MAY raise an error if no files are matched. @@ -685,8 +603,50 @@ they create are legally distributable, build tools SHOULD default to including at least the license files matching the above patterns, unless the user has explicitly specified their own. +Examples of valid license files declaration: -.. _639-spec-key-license: +.. code-block:: toml + + [project] + license-files = { globs = ["LICEN[CS]E*", "AUTHORS*"] } + + [project] + license-files.paths = ["licenses/LICENSE.MIT", "licenses/LICENSE.CC0"] + + [project] + license-files = { paths = [] } + + [project] + license-files.globs = [] + +Examples of invalid license files declaration: + +.. code-block:: toml + + [project] + license-files.globs = ["LICEN[CS]E*", "AUTHORS*"] + license-files.paths = ["LICENSE.MIT"] + +Reason: license-files.paths and license-files.globs are mutually exclusive. + +.. code-block:: toml + + [project] + license-files = { paths = ["..\LICENSE.MIT"] } + +Reason: ``..`` must not be used. +``\`` is an invalid path delimiter, ``/`` must be used. + + +.. code-block:: toml + + [project] + license-files = { globs = ["LICEN{CSE*"] } + +Reason: "LICEN{CSE*" is not a valid glob. + + +.. _639-spec-key-license-table: Deprecate ``license`` key table subkeys ''''''''''''''''''''''''''''''''''''''' @@ -728,36 +688,34 @@ from a new version of the specification in a future PEP. License files in project formats -------------------------------- -A few minor additions will be made to the relevant existing specifications -to document, standardize and clarify what is already currently supported, -allowed and implemented behavior, as well as explicitly mention the root -license directory the license files are located in and relative to for -each format, per the :ref:`639-spec-field-license-file` section. +A few additions will be made to the existing specifications. -**Project source trees** - As described in the :ref:`639-spec-source-metadata` section, the - `Declaring Project Metadata specification `__ +:term:`Project source tree`\s + Per :ref:`639-spec-source-metadata` section, the + `Declaring Project Metadata specification `__ will be updated to reflect that license file paths MUST be relative to the project root directory; i.e. the directory containing the ``pyproject.toml`` (or equivalently, other legacy project configuration, e.g. ``setup.py``, ``setup.cfg``, etc). -**Source distributions** *(sdists)* - The `sdist specification `__ will be updated to reflect that for - ``Metadata-Version`` is ``2.4`` or greater, the sdist MUST contain any - license files specified by ``License-File`` in the ``PKG-INFO`` at their - respective paths relative to the top-level directory of the sdist - (containing the ``pyproject.toml`` and the ``PKG-INFO`` core metadata). +:term:`Source distributions (sdists) ` + The `sdist specification `__ will be updated to reflect that if + the ``Metadata-Version`` is ``2.4`` or greater, + the sdist MUST contain any license files specified by + the :ref:`License-File field <639-spec-field-license-file>` + in the ``PKG-INFO`` at their respective paths + relative to the of the sdist + (containing the ``pyproject.toml`` and the ``PKG-INFO`` Core Metadata). -**Built distributions** *(wheels)* - The `wheel specification `__ will be updated to reflect that if +:term:`Built distribution`\s (:term:`wheel`\s) + The `Wheel 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`` 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. -**Installed projects** +: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`` @@ -775,9 +733,9 @@ Converting legacy metadata Tools MUST NOT use the contents of the ``license.text`` ``[project]`` key (or equivalent tool-specific format), -license classifiers or the value of the core metadata ``License`` field +license classifiers or the value of the Core Metadata ``License`` field to fill the top-level string value of the ``license`` key -or the core metadata ``License-Expression`` field +or the Core Metadata ``License-Expression`` field without informing the user and requiring unambiguous, affirmative user action to select and confirm the desired license expression value before proceeding. @@ -792,72 +750,46 @@ the PEP authors. Backwards Compatibility ======================= -Adding a new, dedicated ``License-Expression`` core metadata field -and a top-level string value for the ``license`` key reserved for this purpose -in the ``pyproject.toml`` ``[project]`` table -unambiguously signals support for the specification in this PEP. -This avoids the risk of new tooling -misinterpreting a license expression as a free-form license description -or vice versa, and raises an error if and only if the user affirmatively -upgrades to the latest metadata version and adds the new field/key. +Adding a new ``License-Expression`` Core Metadata field and a top-level string +value for the ``license`` key in the ``pyproject.toml`` ``[project]`` table +unambiguously means support for the specification in this PEP. This avoids the +risk of new tooling misinterpreting a license expression as a free-form license +description or vice versa. -The legacy ``License`` core metadata field -and the ``license`` key table subkeys (``text`` and ``file``) -in the ``pyproject.toml`` ``[project]`` table -will be deprecated along with the license classifiers, -retaining backwards compatibility while gently preparing users for their -future removal. Such a removal would follow a suitable transition period, and -be left to a future PEP and a new version of the core metadata specification. +The legacy deprecated Core Metadata ``License`` field, ``license`` key table +subkeys (``text`` and ``file``) in the ``pyproject.toml`` ``[project]`` table +and license classifiers retain backwards compatibility. A removal is +left to a future PEP and a new version of the Core Metadata specification. -Formally specifying the new ``License-File`` core metadata field and the -inclusion of the listed files in the distribution merely codifies and -refines the existing practices in popular packaging tools, including the Wheel -and Setuptools projects, and is designed to be largely backwards-compatible -with their existing use of that field. Likewise, the new ``license-files`` -key in the ``[project]`` table of ``pyproject.toml`` -standardizes statically specifying the files to include, -as well as the default behavior, and allows other tools to make use of them, -while only having an effect once users and tools expressly adopt it. +Specification of the new ``License-File`` Core Metadata field and adding the +files in the distribution codifies the existing practices of many packaging +tools. It is designed to be largely backwards-compatible with their existing +use of that field. The new ``license-files`` key in the ``[project]`` table of +``pyproject.toml`` will only have an effect once users and tools adopt it. -Due to requiring license files not be flattened into ``.dist-info`` and -specifying that they should be placed in a dedicated ``licenses`` subdir, -wheels produced following this change will have differently-located -licenses relative to those produced via the previous unspecified, -installer-specific behavior, but as until this PEP there was no way of -discovering these files or accessing them programmatically, and this will -be further discriminated by a new metadata version, there aren't any foreseen -mechanism for this to pose a practical issue. +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. -Furthermore, this resolves existing compatibility issues with the current -ad hoc behavior, namely license files being silently clobbered if they have -the same names as others at different paths, unknowingly rendering the wheel -undistributable, and conflicting with the names of other metadata files in -the same directory. Formally specifying otherwise would in fact block full -forward compatibility with additional standard or installer-specified files -and directories added to ``.dist-info``, as they too could conflict with -the names of existing licenses. +This also resolves current issues where license files are accidentally +replaced if they have the same names in different places, making wheels +undistributable without noticing. It also prevents conflicts with other +metadata files in the same directory. -While minor additions will be made to the source distribution (sdist), -built distribution (wheel) and installed project specifications, all of these -are merely documenting, clarifying and formally specifying behaviors explicitly -allowed under their current respective specifications, and already implemented -in practice, and gating them behind the explicit presence of both the new -metadata versions and the new fields. In particular, sdists may contain -arbitrary files following the project source tree layout, and formally -mentioning that these must include the license files listed in the metadata -merely documents and codifies existing Setuptools practice. Likewise, arbitrary -installer-specific files are allowed in the ``.dist-info`` directory of wheels -and copied to installed projects, and again this PEP just formally clarifies -and standardizes what is already being done. +The additions will be made to the source distribution (sdist), built +distribution (wheel) and installed project specifications. They document +behaviors allowed under their current specifications, and gate them behind the +new metadata version. -Finally, while this PEP does propose PyPI implement validation of the new -``License-Expression`` and ``License-File`` fields, this has no effect on -existing packages, nor any effect on any new distributions uploaded unless they -explicitly choose to opt in to using these new fields while not -following the requirements in the specification. Therefore, this does not have -a backward compatibility impact, and in fact ensures forward compatibility with -any future changes by ensuring all distributions uploaded to PyPI with the new -fields are valid and conform to the specification. +This PEP proposes PyPI implement validation of the new +``License-Expression`` and ``License-File`` fields, which has no effect on +new and existing packages uploaded unless they explicitly opt in to using +these new fields and fail to follow the specification correctly. +Therefore, this does not have a backward compatibility impact, and guarantees +forward compatibility by ensuring all distributions uploaded to PyPI with the +new fields conform to the specification. .. _639-security-implications: @@ -875,44 +807,37 @@ Neither introduces any known new security concerns. How to Teach This ================= -The simple cases are simple: a single license identifier is a valid license -expression, and a large majority of packages use a single license. +A majority of packages use a single license which makes the case simple: +a single license identifier is a valid license expression. -The plan to teach users of packaging tools how to express their package's -license with a valid license expression is to have tools issue informative -messages when they detect invalid license expressions, or when the deprecated -``License`` field or license classifiers are used. +Users of packaging tools will learn the valid license expression of their +package through the messages issued by the tools when they detect invalid +ones, or when the deprecated ``License`` field or license classifiers are used. -An immediate, descriptive error message if an invalid ``License-Expression`` -is used will help users understand they need to use SPDX identifiers in -this field, and catch them if they make a mistake. -For authors still using the now-deprecated, less precise and more redundant -``License`` field or license classifiers, packaging tools will warn -them and inform them of the modern replacement, ``License-Expression``. -Finally, for users who may have forgotten or not be aware they need to do so, -publishing tools will gently guide them toward including ``license`` -and ``license-files`` in their project source metadata. +If an invalid ``License-Expression`` is used, an error message will help users +understand they need to use SPDX identifiers. For authors using the +now-deprecated ``License`` field or license classifiers, packaging tools will +warn them and inform them of the modern replacement, ``License-Expression``. +Finally, the users who may not be aware of this PEP will be guided by the +publishing tools toward including ``license`` and ``license-files`` in their +project source metadata. Tools may also help with the conversion and suggest a license expression in -many, if not most common cases: +many common cases: - The appendix :ref:`639-spec-mapping-classifiers-identifiers` provides - tool authors with recommendation on how to suggest a license expression produced - from legacy classifiers. + tool authors with recommendation on how to suggest a license expression + produced from legacy classifiers. -- Tools may also be able to infer and suggest how to update - an existing ``License`` value in project source metadata - and convert that to a license expression, +- Tools may be able to suggest how to update an existing ``License`` value + in project source metadata and convert that to a license expression, as also :ref:`specified in this PEP <639-spec-converting-metadata>`. - For instance, a tool may suggest converting a value of ``MIT`` - in the ``license.text`` key in ``[project]`` - (or the equivalent in tool-specific formats) - to a top-level string value of the ``license`` key (or equivalent). + For instance, a tool may suggest converting a value of ``MIT`` in the + ``license.text`` key in ``[project]`` (or the equivalent in tool-specific + formats) to a top-level string value of the ``license`` key (or equivalent). Likewise, a tool could suggest converting from a ``License`` of ``Apache2`` - (which is not a valid license expression - as :ref:`defined in this PEP <639-spec-field-license-expression>`) - to a ``License-Expression`` of ``Apache-2.0`` - (the equivalent valid license expression using an SPDX license identifier). + (which is not a valid license expression as :ref:`defined in this PEP + <639-spdx>`) to a ``License-Expression`` of ``Apache-2.0``. .. _639-reference-implementation: @@ -949,96 +874,69 @@ Open Issues Should the ``License`` field be back-filled, or mutually exclusive? ------------------------------------------------------------------- -At present, this PEP explicitly allows, but does not formally recommend or -require, build tools to back-fill the ``License`` core metadata field with -the verbatim text from the ``License-Expression`` field. This would -presumably improve backwards compatibility and was suggested -by some on the Discourse thread. On the other hand, allowing it does -increase complexity and is less of a clean, consistent separation, -preventing the ``License`` field from being completely mutually exclusive -with the new ``License-Expression`` field and requiring that their values -match. +At present, this PEP explicitly allows, but does not require, build tools to +back-fill the ``License`` Core Metadata field with the verbatim text from the +``License-Expression`` field. This would improve backwards compatibility and was +suggested by some on the Discourse thread. On the other hand, allowing it does +increase complexity and is less of a clean separation, preventing the +``License`` field from being mutually exclusive with the new +``License-Expression`` field and requiring that their values match. -As such, it would be very useful to have a more concrete and specific -rationale and use cases for the back-filled data, and give fuller -consideration to any potential benefits or drawbacks of this approach, -in order to come to a final consensus on this matter that can be appropriately -justified here. +As such, it would be useful to have a more concrete rationale and use cases for +the back-filled data in order to come to a final consensus on this matter. -Therefore, is the status quo expressed here acceptable, allowing tools -leeway to decide this for themselves? Should this PEP formally recommend, -or even require, that tools back-fill this metadata (which would presumably -be reversed once a breaking revision of the metadata spec is issued)? -Or should this not be explicitly allowed, discouraged or even prohibited? +Therefore, is the status quo acceptable, allowing tools to decide this for +themselves? Should this PEP recommend, or even require, that tools back-fill +this metadata (which would presumably be reversed once a breaking revision of +the metadata spec is issued)? Or should this not be explicitly allowed, or even +prohibited? Should custom license identifiers be allowed? --------------------------------------------- -The current version of this PEP retains the behavior of only specifying -the use of SPDX-defined license identifiers, as well as the explicitly defined +The current version of this PEP specifies the possibility to use the custom identifiers ``LicenseRef-Public-Domain`` and ``LicenseRef-Proprietary`` -to handle the two common cases where projects have a license, but it is not -one that has a recognized SPDX license identifier. +to handle the cases where projects have a license, but there is not a +recognized SPDX license identifier for it. For maximum flexibility, custom +``LicenseRef-`` license identifiers could be allowed. In some cases +``LicenseRef-Proprietary`` may not be appropriate or specific enough, but +package authors could still want to benefit from the mainstream Python build +tooling. -For maximum flexibility, custom ``LicenseRef-`` license -identifiers could be allowed, which could potentially be useful for niche -cases or corporate environments where ``LicenseRef-Proprietary`` is not -appropriate or insufficiently specific, but relying on mainstream Python -build tooling and the ``License-Expression`` metadata field is still -desirable to use for this purpose. +However, this could increase the confusion about licensing. 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. Additionally, this promotes the use of custom license +identifiers, leading to even more ambiguity. -This has the downsides, however, of not catching misspellings of the -canonically defined license identifiers and thus producing license metadata -that is not a valid match for what the author intended, as well as users -potentially thinking they have to prepend ``LicenseRef`` in front of valid -license identifiers, as there seems to be some previous confusion about. -Furthermore, this encourages the proliferation of bespoke license identifiers, -which obviates the purpose of enabling clear, unambiguous and well -understood license metadata for which this PEP was created. +Standards-conforming tools should not be required to allow custom license +identifiers, since they will not recognize or know how to treat them. By +contrast, custom tools, which would be required to understand custom +identifiers, don't have to follow the listed rules for license identifiers. This +specification already allows such use in specific ecosystems, which avoids the +disadvantages of forcing them on all mainstream packaging tools. -Indeed, for niche cases that need specific, proprietary custom licenses, -they could always simply specify ``LicenseRef-Proprietary``, and then -include the actual license files needed to unambiguously identify the license -regardless (if not using SPDX license identifiers) under the ``License-File`` -fields. Requiring standards-conforming tools to allow custom license -identifiers does not seem very useful, since standard tools will not recognize -bespoke ones or know how to treat them. By contrast, bespoke tools, which -would be required in any case to understand and act on custom identifiers, -are explicitly allowed, with good reason (thus the ``SHOULD`` keyword) -to not require that license identifiers conform to those listed here. -Therefore, this specification still allows such use in private corporate -environments or specific ecosystems, while avoiding the disadvantages of -imposing them on all mainstream packaging tools. +As an alternative, a ``LicenseRef-Custom`` identifier could be defined, which +would more explicitly indicate that the license cannot be expressed with +existing identifiers and the license text should be referenced for details, +in cases where ``LicenseRef-Proprietary`` is not appropriate. This would avoid +the main downsides of the approach of allowing an arbitrary ``LicenseRef``, +while addressing several of the potential scenarios cited for it. -As an alternative, a literal ``LicenseRef-Custom`` identifier could be -defined, which would more explicitly indicate that the license cannot be -expressed with defined identifiers and the license text should be referenced -for details, without carrying the negative and potentially inappropriate -implications of ``LicenseRef-Proprietary``. This would avoid the main -mentioned downsides (misspellings, confusion, license proliferation) of -the approve approach of allowing an arbitrary ``LicenseRef``, while -addressing several of the potential theoretical scenarios cited for it. +On the other hand, as SPDX aims to encompass all FSF-recognized "Free" and +OSI-approved "Open Source" licenses, anything outside those bounds would +generally be covered by ``LicenseRef-Proprietary``, thus making +``LicenseRef-Custom`` somewhat redundant to it. Furthermore, it may mislead +authors of projects with complex/multiple licenses that they should use it over +specifying a license expression. -On the other hand, as SPDX aims to (and generally does) encompass all -FSF-recognized "Free" and OSI-approved "Open Source" licenses, -and those sources are kept closely in sync and are now relatively stable, -anything outside those bounds would generally be covered by -``LicenseRef-Proprietary``, thus making ``LicenseRef-Custom`` less specific -in that regard, and somewhat redundant to it. Furthermore, it may mislead -authors of projects with complex/multiple licenses that they should use it -over specifying a license expression. - -At present, the PEP retains the existing approach over either of these, given -the use cases and benefits were judged to be sufficiently marginal based -on the current understanding of the packaging landscape. For both these -proposals, however, if more concrete use cases emerge, this can certainly -be reconsidered, either for this current PEP or a future one (before or -in tandem with actually removing the legacy unstructured ``License`` -metadata field). Not defining this now enables allowing it later -(or still now, with custom packaging tools), without affecting backward -compatibility, while the same is not so if they are allowed now and later -determined to be unnecessary or too problematic in practice. +At present, the PEP retains the existing approach over either of these, since +the benefits +otherwise seem marginal. Not defining this now enables allowing it later (or +even now, with custom packaging tools) without affecting backward compatibility. +This would be problematic, if they were allowed now and later determined to be +unnecessary. Appendices @@ -1073,8 +971,7 @@ References .. _licenseexplib: https://github.com/nexB/license-expression/ .. _osi: https://opensource.org .. _packagingissue: https://github.com/pypa/packaging-problems/issues/41 -.. _pep621spec: https://packaging.python.org/specifications/declaring-project-metadata/ -.. _pep621specdynamic: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic +.. _pyprojecttoml: https://packaging.python.org/en/latest/specifications/pyproject-toml/ .. _pepissue: https://github.com/pombredanne/spdx-pypi-pep/issues/1 .. _pypi: https://pypi.org/ .. _pypugdistributionpackage: https://packaging.python.org/en/latest/glossary/#term-Distribution-Package diff --git a/peps/pep-0639/appendix-examples.rst b/peps/pep-0639/appendix-examples.rst index fbde566a7..71d8e8629 100644 --- a/peps/pep-0639/appendix-examples.rst +++ b/peps/pep-0639/appendix-examples.rst @@ -49,7 +49,7 @@ Or, in the ``[project]`` table of ``pyproject.toml``: [project] license = "MIT" -The output core metadata for the distribution packages would then be: +The output Core Metadata for the distribution packages would then be: .. code-block:: email @@ -60,7 +60,7 @@ The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE`` in the sdist and ``/setuptools-${VERSION}.dist-info/licenses/LICENSE`` in the wheel, and unpacked from there into the site directory (e.g. ``site-packages``) on installation; ``/`` is the root of the respective archive -and ``${VERSION}`` the version of the Setuptools release in the core metadata. +and ``${VERSION}`` the version of the Setuptools release in the Core Metadata. .. _639-example-advanced: @@ -152,7 +152,7 @@ Or alternatively, matched via glob patterns, this could be: "setuptools/_vendor/LICENSE*", ] -With either approach, the output core metadata in the distribution +With either approach, the output Core Metadata in the distribution would be: .. code-block:: email @@ -164,7 +164,7 @@ would be: License-File: setuptools/_vendor/packaging/LICENSE.BSD In the resulting sdist, with ``/`` as the root of the archive and ``${VERSION}`` -the version of the Setuptools release specified in the core metadata, +the version of the Setuptools release specified in the Core Metadata, the license files would be located at the paths: .. code-block:: shell diff --git a/peps/pep-0639/appendix-license-survey.rst b/peps/pep-0639/appendix-license-survey.rst index ea4b8e7f1..722df6596 100644 --- a/peps/pep-0639/appendix-license-survey.rst +++ b/peps/pep-0639/appendix-license-survey.rst @@ -10,6 +10,23 @@ There are multiple ways used or recommended to document licenses. This document contains the results of a comprehensive survey of license documentation in Python and other languages. +The key takeaways from the survey, which have guided the recommendations of +PEP 639, are as follows: + +- Most package formats use a single ``License`` field. + +- Many modern package systems use some form of :term:`license expression` + to optionally combine more than one :term:`license identifier` together. + SPDX and SPDX-like syntaxes are the most popular in use. + +- SPDX license identifiers are becoming the de facto way to reference common + licenses everywhere, whether or not a full license expression syntax is used. + +- Several package formats support documenting both a license expression and the + paths of the corresponding files that contain the license text. Most Free and + Open Source Software licenses require package authors to include their full + text in a :term:`Distribution Package`. + .. _639-license-doc-python: @@ -18,14 +35,14 @@ License Documentation in Python .. _639-license-doc-core-metadata: -Core metadata +Core Metadata ''''''''''''' -There are two overlapping core metadata fields to document a license: the +There are two overlapping Core Metadata fields to document a license: the license ``Classifier`` `strings `__ prefixed with ``License ::`` and the ``License`` `field `__ as free text. -The core metadata ``License`` field documentation is currently: +The Core Metadata ``License`` field documentation is currently: .. code-block:: rst @@ -148,14 +165,14 @@ globally in a shared documentation directory (e.g. ``/usr/share/doc``). `License Texts `__ and use a `License field `__ that must be filled with appropriate short license identifier(s) from an extensive list - of `"Good Licenses" `__. Fedora also defines its own - license expression syntax, similar to that of SPDX. + of `"Good Licenses" `__. Fedora uses SPDX + license expression syntax. - `OpenSUSE packages `__ use SPDX license expressions with SPDX license IDs and a `list of additional license identifiers `__. -- `Gentoo ebuild `__ uses a ``LICENSE`` variable. +- `Gentoo ebuild `__ uses a ``LICENSE`` variable. This field is specified in `GLEP-0023 `__ and in the `Gentoo development manual `__. Gentoo also defines a list of allowed licenses and a license expression diff --git a/peps/pep-0639/appendix-rejected-ideas.rst b/peps/pep-0639/appendix-rejected-ideas.rst index 330250852..91f9b58cd 100644 --- a/peps/pep-0639/appendix-rejected-ideas.rst +++ b/peps/pep-0639/appendix-rejected-ideas.rst @@ -12,11 +12,11 @@ This document contains a list of the alternative ideas to the ones proposed in PEP 639 with detailed explanations why they were rejected. -Core metadata fields +Core Metadata fields -------------------- Potential alternatives to the structure, content and deprecation of the -core metadata fields specified in :pep:`639`. +Core Metadata fields specified in :pep:`639`. Re-use the ``License`` field @@ -25,68 +25,50 @@ Re-use the ``License`` field Following `initial discussion `__, earlier versions of PEP 639 proposed re-using the existing ``License`` field, which tools would attempt to parse as a SPDX license expression with a fallback to free text. -Initially, this would merely cause a warning (or even pass silently), -but would eventually be treated as an error by modern tooling. +Initially, this would cause a warning and eventually it would be treated as an +error. -This offered the potential benefit of greater backwards-compatibility, -easing the community into using SPDX license expressions while taking advantage -of packages that already have them (either intentionally or coincidentally), +This would be more backwards-compatibile, allowed a smooth adoption +of SPDX license expressions in the community, and avoided adding yet another license-related field. -However, following substantial discussion, consensus was reached that a -dedicated ``License-Expression`` field was the preferred overall approach. -The presence of this field is an unambiguous signal that a package -intends it to be interpreted as a valid SPDX identifier, without the need -for complex and potentially erroneous heuristics, and allows tools to -easily and unambiguously detect invalid content. - -This avoids both false positive (``License`` values that a package author -didn't explicitly intend as an explicit SPDX identifier, but that happen -to validate as one), and false negatives (expressions the author intended -to be valid SPDX, but due to a typo or mistake are not), which are otherwise -not clearly distinguishable from true positives and negatives, an ambiguity -at odds with the goals of PEP 639. +Eventually, consensus was reached that a +dedicated ``License-Expression`` field was a better approach. +The presence of this field unambiguously signals support for the SPDX +identifiers, without the need for complex heuristics, and allows tools to +easily detect invalid content. Furthermore, it allows both the existing ``License`` field and -the license classifiers to be more easily deprecated, -with tools able to cleanly distinguish between packages intending to -affirmatively conform to the updated specification in PEP 639 or not, -and adapt their behavior (warnings, errors, etc) accordingly. -Otherwise, tools would either have to allow duplicative and potentially -conflicting ``License`` fields and classifiers, or warn/error on the -substantial number of existing packages that have SPDX identifiers as the -value for the ``License`` field, intentionally or otherwise (e.g. ``MIT``). +the license classifiers to be easily deprecated, +with tools able to distinguish between packages conforming to PEP 639 or not, +and adapt their behavior accordingly. Finally, it avoids changing the behavior of an existing metadata field, and avoids tools having to guess the ``Metadata-Version`` and field behavior based on its value rather than merely its presence. -While this would mean the subset of existing distributions containing -``License`` fields valid as SPDX license expressions wouldn't automatically be -recognized as such, this only requires appending a few characters to the key -name in the project's source metadata, and PEP 639 provides extensive +Distributions which already contain valid SPDX license expressions in the +``License`` fields will not automatically be recognized as such. +The migration is simple though, and PEP 639 provides guidance on how this can be done automatically by tooling. -Given all this, it was decided to proceed with defining a new, -purpose-created field, ``License-Expression``. - Re-Use the ``License`` field with a value prefix '''''''''''''''''''''''''''''''''''''''''''''''' As an alternative to the previous, prefixing SPDX license expressions with, -e.g. ``spdx:`` was suggested to reduce the ambiguity inherent in re-using +e.g. ``spdx:`` was suggested to reduce the ambiguity of re-using the ``License`` field. However, this effectively amounted to creating -a field within a field, and doesn't address all the downsides of +a field within a field, and doesn't address the downsides of keeping the ``License`` field. Namely, it still changes the behavior of an existing metadata field, requires tools to parse its value to determine how to handle its content, and makes the specification and deprecation process more complex and less clean. -Yet, it still shares a same main potential downside as just creating a new -field: projects currently using valid SPDX identifiers in the ``License`` -field, intentionally or not, won't be automatically recognized, and requires -about the same amount of effort to fix, namely changing a line in the +Projects currently using valid SPDX identifiers in the ``License`` +field won't be automatically recognized, and require +about the same amount of effort to fix as in the case of introducing a new +field, namely changing a line in the project's source metadata. Therefore, it was rejected in favor of a new field. @@ -96,76 +78,36 @@ Don't make ``License-Expression`` mutually exclusive For backwards compatibility, the ``License`` field and/or the license classifiers could still be allowed together with the new ``License-Expression`` field, presumably with a warning. However, this -could easily lead to inconsistent, and at the very least duplicative +could easily lead to inconsistent license metadata in no less than *three* different fields, which is -squarely contrary to the goals of PEP 639 of making the licensing story -simpler and unambiguous. Therefore, and in concert with clear community -consensus otherwise, this idea was soundly rejected. +contrary to the goal of PEP 639 of making the licensing story +unambiguous. Therefore, with the community +consensus this idea was rejected. Don't deprecate existing ``License`` field and classifiers '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' -Several community members were initially concerned that deprecating the +Several community members were concerned that deprecating the existing ``License`` field and classifiers would result in -excessive churn for existing package authors and raise the barrier to -entry for new ones, particularly everyday Python developers seeking to -package and publish their personal projects without necessarily caring -too much about the legal technicalities or being a "license lawyer". -Indeed, every deprecation comes with some non-zero short-term cost, -and should be carefully considered relative to the overall long-term -net benefit. And at the minimum, this change shouldn't make it more -difficult for the average Python developer to share their work under +much churn for package authors and raise the barrier to +entry for new ones, particularly developers seeking to +package their personal projects without caring +too much about the legal technicalities. +Indeed, every deprecation should be carefully considered relative to the +long-term +net benefit. At the minimum, this change shouldn't make it more +difficult for a Python developer to share their work under a license of their choice, and ideally improve the situation. -Following many rounds of proposals, discussion and refinement, -the general consensus was clearly in favor of deprecating the legacy -means of specifying a license, in favor of "one obvious way to do it", -to improve the currently complex and fragmented story around license -documentation. Not doing so would leave three different un-deprecated ways of -specifying a license for a package, two of them ambiguous, less than -clear/obvious how to use, inconsistently documented and out of date. -This is more complex for all tools in the ecosystem to support -indefinitely (rather than simply installers supporting older packages -implementing previous frozen metadata versions), resulting in a non-trivial -and unbounded maintenance cost. - -Furthermore, it leads to a more complex and confusing landscape for users with -three similar but distinct options to choose from, particularly with older -documentation, answers and articles floating around suggesting different ones. -Of the three, ``License-Expression`` is the simplest and clearest to use -correctly; users just paste in their desired license identifier, or select it -via a tool, and they're done; no need to learn about Trove classifiers and -dig through the list to figure out which one(s) apply (and be confused -by many ambiguous options), or figure out on their own what should go -in the ``license`` key (anything from nothing, to the license text, -to a free-form description, to the same SPDX identifier they would be -entering in the ``license`` key anyway, assuming they can -easily find documentation at all about it). In fact, this can be -made even easier thanks to the new field. For example, GitHub's popular -`ChooseALicense.com `__ links to how to add SPDX license -identifiers to the project source metadata of various languages that support -them right in the sidebar of every license page; the SPDX support in this -PEP enables adding Python to that list. - -For current package maintainers who have specified a ``License`` or license -classifiers, PEP 639 only recommends warnings and prohibits errors for -all but publishing tools, which are allowed to error if their intended -distribution platform(s) so requires. Once maintainers are ready to -upgrade, for those already using SPDX license expressions (accidentally or not) -this only requires appending a few characters to the key name in the -project's source metadata, and for those with license classifiers that -map to a single unambiguous license, or another defined case (public domain, -proprietary), they merely need to drop the classifier and paste in the -corresponding license identifier. PEP 639 provides extensive guidance and -examples, as will other resources, as well as explicit instructions for -automated tooling to take care of this with no human changes needed. -More complex cases where license metadata is currently specified may -need a bit of human intervention, but in most cases tools will be able -to provide a list of options following the mappings in PEP 639, and -these are typically the projects most likely to be constrained by the -limitations of the existing license metadata, and thus most benefited -by the new fields in PEP 639. +Following many rounds of discussion, +the general consensus was in favor of deprecating the legacy +means of specifying a license and in favor of "one obvious way to do it". +Not doing so would leave three different un-deprecated ways of +specifying a license for a package, two of them ambiguous, +inconsistently documented and out of date. +This is more complex for tools to support +indefinitely, resulting in a non-trivial maintenance cost. Finally, for unmaintained packages, those using tools supporting older metadata versions, or those who choose not to provide license metadata, @@ -175,77 +117,63 @@ no changes are required regardless of the deprecation. Don't mandate validating new fields on PyPI ''''''''''''''''''''''''''''''''''''''''''' -Previously, while PEP 639 did include normative guidelines for packaging -publishing tools (such as Twine), it did not provide specific guidance +Previously, PEP 639 did not provide specific guidance for PyPI (or other package indices) as to whether and how they should validate the ``License-Expression`` or ``License-File`` fields, nor how they should handle using them in combination with the deprecated ``License`` field or license classifiers. This simplifies the specification -and either defers implementation on PyPI to a later PEP, or gives -discretion to PyPI to enforce the stated invariants, to minimize +and defers implementation on PyPI to a later PEP to minimize disruption to package authors. -However, this had been left unstated from before the ``License-Expression`` -field was separate from the existing ``License``, which would make -validation much more challenging and backwards-incompatible, breaking -existing packages. With that change, there was a clear consensus that +This was in place for an earlier draft of PEP 639 which didn't separate +``License-Expression`` from the ``License`` field. The validation would have +been difficult and backwards-incompatible, breaking existing packages. +With the current proposal, there was a clear consensus that the new field should be validated from the start, guaranteeing that all -distributions uploaded to PyPI that declare core metadata version 2.4 +distributions uploaded to PyPI that declare Core Metadata version 2.4 or higher and have the ``License-Expression`` field will have a valid expression, such that PyPI and consumers of its packages and metadata can rely upon to follow the specification here. The same can be extended to the new ``License-File`` field as well, to ensure that it is valid and the legally required license files are -present, and thus it is lawful for PyPI, users and downstream consumers -to distribute the package. (Of course, this makes no *guarantee* of such -as it is ultimately reliant on authors to declare them, but it improves -assurance of this and allows doing so in the future if the community so -decides.) To be clear, this would not require that any uploaded distribution -have such metadata, only that if they choose to declare it per the new +present. To be clear, this would not require that any uploaded distribution +have such metadata, only that if they choose to declare it per the specification in PEP 639, it is assured to be valid. Source metadata ``license`` key ------------------------------- -Alternate possibilities related to the ``license`` key in the +Alternative possibilities related to the ``license`` key in the ``pyproject.toml`` project source metadata. Add ``expression`` and ``files`` subkeys to table ''''''''''''''''''''''''''''''''''''''''''''''''' -A previous working draft of PEP 639 added ``expression`` and ``files`` subkeys +A previous draft of PEP 639 added ``expression`` and ``files`` subkeys to the existing ``license`` table in the project source metadata, to parallel -the existing ``file`` and ``text`` subkeys. While this seemed perhaps the -most obvious approach at first glance, it had several serious drawbacks +the existing ``file`` and ``text`` subkeys. While this seemed the +most obvious approach at first glance, it had serious drawbacks relative to that ultimately taken here. -Most saliently, this means two very different types of metadata are being +This means two very different types of metadata are being specified under the same top-level key that require very different handling, -and furthermore, unlike the previous arrangement, the subkeys were not mutually -exclusive and can both be specified at once, and with some subkeys potentially -being dynamic and others static, and mapping to different core metadata fields. - -Furthermore, this leads to a conflict with marking the key as ``dynamic`` -(assuming that is intended to specify the ``[project]`` table keys, -as that PEP seems to imprecisely imply, -rather than core metadata fields), as either or both would have -to be treated as ``dynamic``. -Grouping both license expressions and license files under the same key -forces an "all or nothing" approach, and creates ambiguity as to user intent. +and unlike the previous arrangement, the subkeys were not mutually +exclusive and could both be specified at once, with some subkeys potentially +being dynamic and others static, and mapping to different Core Metadata fields. There are further downsides to this as well. Both users and tools would need to keep track of which fields are mutually exclusive with which of the others, -greatly increasing cognitive and code complexity, and in turn the probability -of errors. Conceptually, juxtaposing so many different fields under the -same key is rather jarring, and leads to a much more complex mapping between -``[project]`` keys and core metadata fields, not in keeping with :pep:`621`. +greatly increasing complexity, and the probability +of errors. Having so many different fields under the +same key leads to a much more complex mapping between +``[project]`` keys and Core Metadata fields, not in keeping with :pep:`621`. This causes the ``[project]`` table naming and structure to diverge further -from both the core metadata and native formats of the various popular packaging +from both the Core Metadata and native formats of the various popular packaging tools that use it. Finally, this results in the spec being significantly more -complex and convoluted to understand and implement than the alternatives. +complex to understand and implement than the alternatives. The approach PEP 639 now takes, using the reserved top-level string value of the ``license`` key, adding a new ``license-files`` key @@ -255,7 +183,7 @@ and results in a much clearer and cleaner design overall. It allows ``license`` and ``license-files`` to be tagged ``dynamic`` independently, separates two independent types of metadata (syntactically and semantically), restores a closer to 1:1 mapping of -``[project]`` table keys to core metadata fields, +``[project]`` table keys to Core Metadata fields, and reduces nesting by a level for both. Other than adding one extra key to the file, there was no significant apparent downside to this latter approach, so it was adopted for PEP 639. @@ -265,20 +193,20 @@ Add an ``expression`` subkey instead of a string value '''''''''''''''''''''''''''''''''''''''''''''''''''''' Adding just an ``expression`` subkey to the ``license`` table, -instead of using the reserved top-level string value, +instead of using the top-level string value, would be more explicit for readers and writers, in line with PEP 639's goals. However, it still has the downsides listed above that are not specific to the inclusion of the ``files`` key. Relative to a flat string value, -it adds verbosity, complexity and an extra level of nesting, +it adds complexity and an extra level of nesting, and requires users and tools to remember and handle the mutual exclusivity of the subkeys -and remember which are deprecated and which are not, +and remember which are deprecated, instead of cleanly deprecating the table subkeys as a whole. Furthermore, it is less clearly the "default" choice for modern use, -given users tend to gravitate toward the simplest and most obvious option. +given users tend to gravitate toward the most obvious option. Finally, it seems reasonable to follow the suggested guidance in :pep:`621`, given the top-level string value was specifically reserved for this purpose. @@ -288,18 +216,17 @@ Define a new top-level ``license-expression`` key An earlier version of PEP 639 defined a new, top-level ``license-expression`` under the ``[project]`` table, -rather than using the reserved string value of the ``license`` key. -This was seen as clearer and more explicit for readers and writers, +rather than using the string value of the ``license`` key. +This was seen as clearer for readers and writers, in line with the goals of PEP 639. -Additionally, while differences from existing tool formats (and core metadata -field names) have precedent in :pep:`621`, -using a key with an identical name as in most/all current tools -to mean something different (and map to a different core metadata field), -with distinct and incompatible syntax and semantics, does not, -and could cause confusion and ambiguity for readers and authors. +While differences from existing tool formats (and Core Metadata +field names) have precedent in :pep:`621`, repurposing an existing key to mean +something different (and map to a different Core Metadata field), +with distinct and incompatible syntax does not, +and could cause ambiguity for readers and authors. -Also, per the `project source metadata spec `__, +Also, per the `project source metadata spec `__, this would allow separately marking the ``[project]`` keys corresponding to the ``License`` and ``License-Expression`` metadata fields as ``dynamic``, @@ -317,18 +244,18 @@ as :pep:`reserved for this purpose by PEP 621 <621#license>`: (the same logic applies to any sort of "type" field specifying what license the file or text represents). -This is shorter and simpler for users to remember and type, +This is simpler for users to remember and type, avoids adding a new top-level key while taking advantage of an existing one, guides users toward using a license expression as the default, and follows what was envisioned in the original :pep:`621`. Additionally, this allows cleanly deprecating the table values without deprecating the key itself, -and makes them inherently mutually exclusive without users having to remember +and makes them mutually exclusive without users having to remember and tools having to enforce it. -Finally, consistency with other tool formats and the underlying core metadata -was not considered a sufficient priority +Finally, consistency with other tool formats and the underlying Core Metadata +was not a sufficient priority to override the advantages of using the existing key, and the ``dynamic`` concerns were mostly mitigated by not specifying legacy license to license expression conversion at build time, @@ -348,30 +275,28 @@ of the ``license`` key in the ``[project]`` table, one could add a ``type`` subkey to the ``license`` table to control whether ``text`` (or a string value) is interpreted as free-text or a license expression. This could make -backward compatibility a little more seamless, as older tools could ignore +backward compatibility a bit easier, as older tools could ignore it and always treat ``text`` as ``license``, while newer tools would know to treat it as a license expression, if ``type`` was set appropriately. Indeed, :pep:`621` seems to suggest something of this sort as a possible -alternative way that SPDX license expressions could be implemented. +way that SPDX license expressions could be implemented. -However, all the same downsides as in the previous item apply here, +However, it has got all the same downsides as in the previous item, including greater complexity, a more complex mapping between the project -source metadata and core metadata and inconsistency between the presentation -in tool config, project source metadata and core metadata, -a much less clean deprecation, further bikeshedding over what to name it, +source metadata and Core Metadata and inconsistency between the presentation +in tool config, project source metadata and Core Metadata, +a harder deprecation, further bikeshedding over what to name it, and inability to mark one but not the other as dynamic, among others. -In addition, while theoretically potentially a little easier in the short +In addition, while theoretically a little easier in the short term, in the long term it would mean users would always have to remember to specify the correct ``type`` to ensure their license expression is interpreted correctly, which adds work and potential for error; we could -never safety change the default while being confident that users +never safely change the default while being confident that users understand that what they are entering is unambiguously a license expression, with all the false positive and false negative issues as above. -Therefore, for these as well as the same reasons this approach was rejected -for the core metadata in favor of a distinct ``License-Expression`` field, -we similarly reject this here in favor of +Therefore, for these reasons, we reject this here in favor of the reserved string value of the ``license`` key. @@ -379,7 +304,7 @@ Must be marked dynamic to back-fill ''''''''''''''''''''''''''''''''''' The ``license`` key in the ``pyproject.toml`` could be required to be -explicitly set to dynamic in order for the ``License`` core metadata field +explicitly set to dynamic in order for the ``License`` Core Metadata field to be automatically back-filled from the top-level string value of the ``license`` key. This would be more explicit that the filling will be done, @@ -388,9 +313,9 @@ as strictly speaking the ``license`` key is not (and cannot be) specified in of the previous :pep:`621` specification that PEP 639 revises. However, this doesn't seem to be necessary, because it is simply using the -static, verbatim literal value of the ``license`` key, as specified -strictly in PEP 639. Therefore, any conforming tool can trivially, -deterministically and unambiguously derive this using only the static data +static, literal value of the ``license`` key, as specified +strictly in PEP 639. Therefore, any conforming tool can +deterministically derive this using only the static data in the ``pyproject.toml`` file itself. Furthermore, this actually adds significant ambiguity, as it means the value @@ -401,9 +326,9 @@ why such is explicitly prohibited by PEP 639. Therefore, not marking it as requirements. Finally, users explicitly being told to mark it as ``dynamic``, or not, to -control filling behavior seems to be a bit of a mis-use of the ``dynamic`` +control filling behavior seems to be a bit of a misuse of the ``dynamic`` field as apparently intended, and prevents tools from adapting to best -practices (fill, don't fill, etc) as they develop and evolve over time. +practices (fill, don't fill, etc.) as they develop and evolve over time. Source metadata ``license-files`` key @@ -420,47 +345,46 @@ Add a ``type`` subkey to ``license-files`` Instead of defining mutually exclusive ``paths`` and ``globs`` subkeys of the ``license-files`` ``[project]`` table key, we could achieve the same effect with a ``files`` subkey for the list and -a ``type`` subkey for how to interpret it. However, the latter offers no -real advantage over the former, in exchange for requiring more keystrokes, -verbosity and complexity, as well as less flexibility in allowing both, +a ``type`` subkey for how to interpret it. However, it offers no +real advantage in exchange for requiring more keystrokes, +increased complexity, as well as less flexibility in allowing both, or another additional subkey in the future, as well as the need to bikeshed -over the subkey name. Therefore, it was summarily rejected. +over the subkey name. Therefore, it was rejected. Only accept verbatim paths '''''''''''''''''''''''''' -Globs could be disallowed completely as values to the ``license-files`` -key in ``pyproject.toml`` and only verbatim literal paths allowed. -This would ensure that all license files are explicitly specified, all -specified license files are found and included, and the source metadata +Globs could be disallowed as values to the ``license-files`` +key in ``pyproject.toml`` and only verbatim paths allowed. +This would ensure that all license files are explicitly specified, +found and included, and the source metadata is completely static in the strictest sense of the term, without tools having to inspect the rest of the project source files to determine exactly what license files will be included and what the ``License-File`` values -will be. This would also modestly simplify the spec and tool implementation. +will be. This would also simplify the spec and tool implementation. -However, practicality once again beats purity here. Globs are supported and -used by many existing tools for finding license files, and explicitly +However, practicality beats purity here. Globs are already supported +by many existing tools, and explicitly specifying the full path to every license file would be unnecessarily tedious -for more complex projects with vendored code and dependencies. More +for complex projects with vendored dependencies. More critically, it would make it much easier to accidentally miss a required -legal file, silently rendering the package illegal to distribute. +legal file, creating the package illegal to distribute. -Tools can still statically and consistently determine the files to be included, -based only on those glob patterns the user explicitly specified and the +Tools can still determine the files to be included, +based only on the glob patterns the user specified and the filenames in the package, without installing it, executing its code or even -examining its files. Furthermore, tools are still explicitly allowed to warn -if specified glob patterns (including full paths) don't match any files. +examining its files. Furthermore, tools are explicitly allowed to warn +if specified glob patterns don't match any files. And, of course, sdists, wheels and others will have the full static list of files specified in their distribution metadata. -Perhaps most importantly, this would also preclude the currently specified -default value, as widely used by the current most popular tools, and thus -be a major break to backward compatibility, tool consistency, and safe -and sane default functionality to avoid unintentional license violations. -And of course, authors are welcome and encouraged to specify their license +Perhaps most importantly, this would also exclude the currently specified +default value widely used by the most popular tools, and thus +be a major break to backward compatibility. +And of course, authors are welcome to specify their license files explicitly via the ``paths`` table subkey, once they are aware of it and -if it is suitable for their project and workflow. +find it suitable for their project. Only accept glob patterns @@ -480,14 +404,14 @@ Including an explicit ``paths`` value ensures that the resulting ``License-File`` metadata is correct, complete and purely static in the strictest sense of the term, with all license paths explicitly specified in the ``pyproject.toml`` file, guaranteed to be included and with an early -error should any be missing. This is not practical to do, at least without +error if any are missing. This is not practical to do, at least without serious limitations for many workflows, if we must assume the items are glob patterns rather than literal paths. This allows tools to locate them and know the exact values of the -``License-File`` core metadata fields without having to traverse the -source tree of the project and match globs, potentially allowing easier, -more efficient and reliable programmatic inspection and processing. +``License-File`` Core Metadata fields without having to traverse the +source tree of the project and match globs, potentially allowing +more reliable programmatic inspection and processing. Therefore, given the relatively small cost and the significant benefits, this approach was not adopted. @@ -498,28 +422,26 @@ Infer whether paths or globs It was considered whether to simply allow specifying an array of strings directly for the ``license-files`` key, rather than making it a table with -explicit ``paths`` and ``globs``. This would be somewhat simpler and avoid +explicit ``paths`` and ``globs``. This would be simpler and avoid an extra level of nesting, and more closely match the configuration format of existing tools. However, it was ultimately rejected in favor of separate, mutually exclusive ``paths`` and ``globs`` table subkeys. In practice, it only saves six extra characters in the ``pyproject.toml`` (``license-files = [...]`` vs ``license-files.globs = [...]``), but allows -the user to more explicitly declare their intent, ensures they understand how -the values are going to be interpreted, and serves as an unambiguous indicator -for tools to parse them as globs rather than verbatim path literals. +the user to explicitly declare their intent and serves as an unambiguous +indicator for tools to parse them as globs rather than verbatim paths. -This, in turn, allows for more appropriate, clearly specified tool +This, in turn, allows for clearly specified tool behaviors for each case, many of which would be unreliable or impossible -without it, to avoid common traps, provide more helpful feedback and -behave more sensibly and intuitively overall. These include, with ``paths``, -guaranteeing that each and every specified file is included and immediately +without it and +behave more intuitively overall. These include, with ``paths``, +guaranteeing that each specified file is included and immediately raising an error if one is missing, and with ``globs``, checking glob syntax, -excluding unwanted backup, temporary, or other such files (as current tools -already do), and optionally warning if a glob doesn't match any files. +excluding unwanted backup, temporary, or other such files, +and optionally warning if a glob doesn't match any files. This also avoids edge cases (e.g. paths that contain glob characters) and -reliance on heuristics to determine interpretation—the very thing PEP 639 -seeks to avoid. +reliance on heuristics to determine interpretation. .. _639-license-files-allow-flat-array: @@ -530,25 +452,23 @@ Also allow a flat array value Initially, after deciding to define ``license-files`` as a table of ``paths`` and ``globs``, thought was given to making a top-level string array under the ``license-files`` key mean one or the other (probably ``globs``, to match most -current tools). This is slightly shorter and simpler, would allow gently -nudging users toward a preferred one, and allow a slightly cleaner handling of -the empty case (which, at present, is treated identically for either). +current tools). This is slightly shorter, indicates to +the users which one is a preferred one, and allows a cleaner handling of +the empty case. -However, this again only saves six characters in the best case, and there -isn't an obvious choice; whether from a perspective of preference (both had -clear use cases and benefits), nor as to which one users would naturally -assume. +However, this only saves six characters in the best case, and there +isn't an obvious choice. Flat may be better than nested, but in the face of ambiguity, users may not resist the temptation to guess. Requiring users to explicitly specify one or the other ensures they are aware of how their inputs will be handled, -and is more readable for others, both human and machine alike. It also makes +and is more readable for others. It also makes the spec and tool implementation slightly more complicated, and it can always be added in the future, but not removed without breaking backward compatibility. And finally, for the "preferred" option, it means there is more than one obvious way to do it. -Therefore, per :pep:`20`, the Zen of Python, this approach is hereby rejected. +Therefore, per :pep:`20`, the Zen of Python, this approach is rejected. Allow both ``paths`` and ``globs`` subkeys @@ -556,73 +476,64 @@ Allow both ``paths`` and ``globs`` subkeys Allowing both ``paths`` and ``globs`` subkeys to be specified under the ``license-files`` table was considered, as it could potentially allow -more flexible handling for particularly complex projects, and specify on a -per-pattern rather than overall basis whether ``license-files`` entries -should be treated as ``paths`` or ``globs``. +more flexible handling for particularly complex projects. However, given the existing proposed approach already matches or exceeds the -power and capabilities of those offered in tools' config files, there isn't -clear demand for this and few likely cases that would benefit, it adds a large -amount of complexity for relatively minimal gain, in terms of the -specification, in tool implementations and in ``pyproject.toml`` itself. +capabilities of those offered in tools' config files, there isn't +clear demand for this, and it adds a large +amount of complexity in tool implementations and ``pyproject.toml`` +for relatively minimal gain. There would be many more edge cases to deal with, such as how to handle files -matched by both lists, and it conflicts in multiple places with the current -specification for how tools should behave with one or the other, such as when -no files match, guarantees of all files being included and of the file paths -being explicitly, statically specified, and others. +matched by both lists, and it conflicts with the current +specification for how tools should behave, such as when +no files match. Like the previous, if there is a clear need for it, it can be always allowed -in the future in a backward-compatible manner (to the extent it is possible -in the first place), while the same is not true of disallowing it. +in the future in a backward-compatible manner, +while the same is not true of disallowing it. Therefore, it was decided to require the two subkeys to be mutually exclusive. Rename ``paths`` subkey to ``files`` '''''''''''''''''''''''''''''''''''' -Initially, it was considered whether to name the ``paths`` subkey of the -``license-files`` table ``files`` instead. However, ``paths`` was ultimately -chosen, as calling the table subkey ``files`` resulted in duplication between +Initially, the name ``files`` was considered instead of the ``paths`` for the +subkey of ``license-files`` table. However, ``paths`` was ultimately +chosen to avoid duplication between the table name (``license-files``) and the subkey name (``files``), i.e. -``license-files.files = ["LICENSE.txt"]``, made it seem like the preferred/ -default subkey when it was not, and lacked the same parallelism with ``globs`` -in describing the format of the string entry rather than what was being -pointed to. +``license-files.files = ["LICENSE.txt"]``. It made it seem like +the preferred subkey when it was not, and didn't describe the format of the +string entry similarly to the existing ``globs``. Must be marked dynamic to use defaults '''''''''''''''''''''''''''''''''''''' -It may seem outwardly sensible, at least with a particularly restrictive -interpretation of :pep:`621`'s description of the ``dynamic`` list, to -consider requiring the ``license-files`` key to be explicitly marked as -``dynamic`` in order for the default glob patterns to be used, or alternatively +With a restrictive +interpretation of :pep:`621`'s description of the ``dynamic`` list it may +seem sensible to require the ``license-files`` key to be marked as +``dynamic`` for the default glob patterns to be used, or alternatively for license files to be matched and included at all. -However, this is merely declaring a static, strictly-specified default value -for this particular key, required to be used exactly by all conforming tools -(so long as it is not marked ``dynamic``, negating this argument entirely), -and is no less static than any other set of glob patterns the user themself -may specify. Furthermore, the resulting ``License-File`` core metadata values -can still be determined with only a list of files in the source, without -installing or executing any of the code, or even inspecting file contents. +However, this is just declaring a static, strictly-specified default value, +required to be used exactly by all conforming tools, similarly to any other set +of glob patterns the user themself may specify. +The resulting ``License-File`` Core Metadata values +can be determined through inspecting a list of files in the source, without +executing code, or even inspecting file contents. -Moreover, even if this were not so, practicality would trump purity, as this -interpretation would be strictly backwards-incompatible with the existing +Moreover, even if this were not so, this +interpretation would be backwards-incompatible with the existing format, and be inconsistent with the behavior with the existing tools. -Further, this would create a very serious and likely risk of a large number of +Further, this would create a serious risk of a large number of projects unknowingly no longer including legally mandatory license files, -making their distribution technically illegal, and is thus not a sane, -much less sensible default. +and is thus not a sane default. -Finally, aside from adding an additional line of default-required boilerplate -to the file, not defining the default as dynamic allows authors to clearly -and unambiguously indicate when their build/packaging tools are going to be -handling the inclusion of license files themselves rather than strictly -conforming to the project source metadata portions of PEP 639; -to do otherwise would defeat the primary purpose of the ``dynamic`` list -as a marker and escape hatch. +Finally, not defining the default as dynamic allows authors to unambiguously +indicate when their build/packaging tools are going to be +handling the inclusion of license files themselves; +to do otherwise would defeat the purpose of the ``dynamic`` list. License file paths @@ -635,36 +546,31 @@ and built distributions. Flatten license files in subdirectories ''''''''''''''''''''''''''''''''''''''' -Previous drafts of PEP 639 were silent on the issue of handling license files -in subdirectories. Currently, the `Wheel `__ and (following its -example) `Setuptools `__ projects flatten all license files +Previous drafts of PEP 639 didn't specify how to handle the license files +in subdirectories. Currently, the `Wheel `__ and +`Setuptools `__ projects flatten all license files into the ``.dist-info`` directory without preserving the source subdirectory hierarchy. -While this is the simplest approach and matches existing ad hoc practice, -this can result in name conflicts and license files clobbering others, -with no obvious defined behavior for how to resolve them, and leaving the -package legally un-distributable without any clear indication to users that -their specified license files have not been included. +While this approach and matches existing ad hoc practice, +it can result in name conflicts and license files clobbering others, +with no defined behavior for how to resolve them, and leaving the +package legally un-distributable without any clear indication that +the specified license files have not been included. Furthermore, this leads to inconsistent relative file paths for non-root license files between the source, sdist and wheel, and prevents the paths -given in the "static" ``[project]`` table metadata from being truly static, -as they need to be flattened, and may potentially overwrite one another. -Finally, the source directory structure often implies valuable information -about what the licenses apply to, and where to find them in the source, +given in the "static" ``[project]`` table metadata from being truly static. +Finally, the source directory structure often holds valuable information +about what the licenses apply to, which is lost when flattening them and far from trivial to reconstruct. -To resolve this, the PEP now proposes, as did contributors on both of the -above issues, reproducing the source directory structure of the original -license files inside the ``.dist-info`` directory. This would fully resolve the -concerns above, with the only downside being a more nested ``.dist-info`` -directory. There is still a risk of collision with edge-case custom -filenames (e.g. ``RECORD``, ``METADATA``), but that is also the case -with the previous approach, and in fact with fewer files flattened -into the root, this would actually reduce the risk. Furthermore, -the following proposal rooting the license files under a ``licenses`` -subdirectory eliminates both collisions and the clutter problem entirely. +To resolve this, the PEP now proposes reproducing the source directory +structure of the original +license files inside the ``.dist-info`` directory. The only downside of this +approach is having a more nested ``.dist-info`` +directory. The following proposal rooting the license files under a ``licenses`` +subdirectory eliminates both name collisions and the clutter problem entirely. Resolve name conflicts differently @@ -677,95 +583,79 @@ to the license filename, traversing up the tree until the name was unique, to avoid excessively nested directories. However, this would not address the path consistency issues, would require -much more discussion, coordination and bikeshedding, and further complicate -the specification and the implementations. Therefore, it was rejected in -favor of the simpler and more obvious solution of just preserving the -source subdirectory layout, as many stakeholders have already advocated for. +much more discussion and further complicate +the specification. Therefore, it was rejected in +favor of the more obvious solution of just preserving the +source subdirectory layout, as many stakeholders have advocated for. Dump directly in ``.dist-info`` ''''''''''''''''''''''''''''''' Previously, the included license files were stored directly in the top-level -``.dist-info`` directory of built wheels and installed projects. This followed -existing ad hoc practice, ensured most existing wheels currently using this -feature will match new ones, and kept the specification simpler, with the -license files always being stored in the same location relative to the core -metadata regardless of distribution type. +``.dist-info`` directory of built wheels and installed projects. -However, this leads to a more cluttered ``.dist-info`` directory, littered -with arbitrary license files and subdirectories, as opposed to separating -licenses into their own namespace (which per the Zen of Python, :pep:`20`, are -"one honking great idea"). While currently small, there is still a -risk of collision with specific custom license filenames +However, this leads to a more cluttered ``.dist-info`` directory +as opposed to separating +licenses into their own namespace. There is still a +risk of collision with custom license filenames (e.g. ``RECORD``, ``METADATA``) in the ``.dist-info`` directory, which -would only increase if and when additional files were specified here, and -would require carefully limiting the potential filenames used to avoid -likely conflicts with those of license-related files. Finally, +would require limiting the potential filenames used. Finally, putting licenses into their own specified subdirectory would allow -humans and tools to quickly, easily and correctly list, copy and manipulate -all of them at once (such as in distro packaging, legal checks, etc) -without having to reference each of their paths from the core metadata. +humans and tools to correctly manipulate +all of them at once (such as in distro packaging, legal checks, etc.) +without having to reference each of their paths from the Core Metadata. -Therefore, now is a prudent time to specify an alternate approach. -The simplest and most obvious solution, as suggested by several on the Wheel -and Setuptools implementation issues, is to simply root the license files +Therefore, the simplest and most obvious solution, as suggested by several +on the Wheel +and Setuptools implementation issues, is to root the license files relative to a ``licenses`` subdirectory of ``.dist-info``. This is simple -to implement and solves all the problems noted here, without clear significant +to implement and solves all the problems noted here, without significant drawbacks relative to other more complex options. -It does make the specification a bit more complex and less elegant, but +It does make the specification a bit more complex, but implementation should remain equally simple. It does mean that wheels produced with following this change will have differently-located licenses than those prior, but as this was already true for those in subdirectories, -and until PEP 639 there was no way of discovering these files or -accessing them programmatically, this doesn't seem likely to pose -significant problems in practice. Given this will be much harder if not -impossible to change later, once the status quo is standardized, tools are -relying on the current behavior and there is much greater uptake of not -only simply including license files but potentially accessing them as well -using the core metadata, if we're going to change it, now would be the time -(particularly since we're already introducing an edge-case change with how -license files in subdirs are handled, along with other refinements). - -Therefore, the latter has been incorporated into current drafts of PEP 639. +and until PEP 639 there was no way of +accessing these files programmatically, this should not pose +significant problems in practice. Add new ``licenses`` category to wheel '''''''''''''''''''''''''''''''''''''' Instead of defining a root license directory (``licenses``) inside -the core metadata directory (``.dist-info``) for wheels, we could instead +the Core Metadata directory (``.dist-info``) for wheels, we could instead define a new category (and, presumably, a corresponding install scheme), similar to the others currently included under ``.data`` in the wheel archive, specifically for license files, called (e.g.) ``licenses``. This was mentioned by the wheel creator, and would allow installing licenses somewhere more platform-appropriate and flexible than just the ``.dist-info`` directory -in the site path, and potentially be conceptually cleaner than including -them there. +in the site path. However, at present, PEP 639 does not implement this idea, and it is deferred to a future one. It would add significant complexity and friction to PEP 639, being primarily concerned with standardizing existing practice -and updating the core metadata specification. Furthermore, doing so would -likely require modifying ``sysconfig`` and the install schemes specified +and updating the Core Metadata specification. Furthermore, doing so could +require modifying ``sysconfig`` and the install schemes specified therein, alongside Wheel, Installer and other tools, which would be a non-trivial undertaking. While potentially slightly more complex for -repackagers (such as those for Linux distributions), the current proposal still -ensures all license files are included, and in a single dedicated directory -(which can easily be copied or relocated downstream), and thus should still -greatly improve the status quo in this regard without the attendant complexity. +repackagers, the current proposal still +ensures all license files are included in a single dedicated directory, +and thus should still +greatly improve the status quo in this regard. In addition, this approach is not fully backwards compatible (since it isn't transparent to tools that simply extract the wheel), is a greater departure from existing practice and would lead to more inconsistent license install locations from wheels of different versions. Finally, -this would mean licenses would not be installed as proximately to their +this would mean licenses would not be installed as close to their associated code, there would be more variability in the license root path across platforms and between built distributions and installed projects, accessing installed licenses programmatically would be more difficult, and a -suitable install location and method would need to be created, discussed -and decided that would avoid name clashes. +suitable install location and method would need to be created that would avoid +name clashes. Therefore, to keep PEP 639 in scope, the current approach was retained. @@ -777,11 +667,11 @@ 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 due to being slightly clearer and consistent with the -name of the core metadata field (``License-File``) +name of the Core Metadata field (``License-File``) and the ``[project]`` table key (``license-files``). -However, the current version of the PEP adopts the ``license`` name, -due to a general preference by the community for its shorter length, -greater simplicity and the lack of a separator character (``_``, ``-``, etc.). +However, the current version of the PEP adopts the ``licenses`` name, +due to a general preference by the community for its shorter length +and the lack of a separator character. Other ideas @@ -794,9 +684,8 @@ ultimately not adopted. Map identifiers to license files '''''''''''''''''''''''''''''''' -This would require using a mapping (as two parallel lists would be too prone to -alignment errors), which would add extra complexity to how license -are documented and add an additional nesting level. +This would require using a mapping, which would add extra complexity to how +license are documented and add an additional nesting level. A mapping would be needed, as it cannot be guaranteed that all expressions (keys) have a single license file associated with them (e.g. @@ -805,15 +694,15 @@ does not have more than one. (e.g. an Apache license ``LICENSE`` and its ``NOTICE`` file, for instance, are two distinct files). For most common cases, a single license expression and one or more license files would be perfectly adequate. In the rarer and more complex cases where -there are many licenses involved, authors can still safety use the fields +there are many licenses involved, authors can still safely use the fields specified here, just with a slight loss of clarity by not specifying which -text file(s) map to which license identifier (though this should be clear in -practice given each license identifier has corresponding SPDX-registered -full license text), while not forcing the more complex data model -(a mapping) on the large majority of users who do not need or want it. +text file(s) map to which license identifier (though each license identifier +has corresponding SPDX-registered +full license text), while not forcing the more complex mapping +on the large majority of users who do not need or want it. -We could of course have a data field with multiple possible value types (it's a -string, it's a list, it's a mapping!) but this could be a source of confusion. +We could of course have a data field with multiple possible value types +but this could be a source of confusion. This is what has been done, for instance, in npm (historically) and in Rubygems (still today), and as result tools need to test the type of the metadata field before using it in code, while users are confused about when to use a list or a @@ -833,8 +722,7 @@ Don't freeze compatibility with a specific SPDX version PEP 639 could omit specifying a specific SPDX specification version, or one for the list of valid license identifiers, which would allow -more flexible updates as the specification evolves without another -PEP or equivalent. +more flexible updates as the specification evolves. However, serious concerns were expressed about a future SPDX update breaking compatibility with existing expressions and identifiers, leaving current @@ -844,11 +732,10 @@ and a PEP or similar process to update it avoids this contingency, and follows the practice of other packaging ecosystems. Therefore, it was `decided `__ to specify a minimum version -and requires tools to be compatible with it, while still allowing updates +and require tools to be compatible with it, while still allowing updates so long as they don't break backward compatibility. This enables tools to immediate take advantage of improvements and accept new -licenses, but also remain backwards compatible with the version -specified here, balancing flexibility and compatibility. +licenses balancing flexibility and compatibility. .. _639-rejected-ideas-difference-license-source-binary: @@ -856,15 +743,13 @@ specified here, balancing flexibility and compatibility. Different licenses for source and binary distributions '''''''''''''''''''''''''''''''''''''''''''''''''''''' -As an additional use case, it was asked whether it was in scope for this -PEP to handle cases where the license expression for a binary distribution +As an additional use case, it was asked whether it was in scope for +PEP 639 to handle cases where the license expression for a binary distribution (wheel) is different from that for a source distribution (sdist), such as in cases of non-pure-Python packages that compile and bundle binaries under different licenses than the project itself. An example cited was `PyTorch `__, which contains CUDA from Nvidia, which is freely -distributable but not open source. `NumPy `__ and -`SciPy `__ also had similar issues, as reported by the -original author of PEP 639 and now resolved for those cases. +distributable but not open source. However, given the inherent complexity here and a lack of an obvious mechanism to do so, the fact that each wheel would need its own license @@ -875,12 +760,9 @@ to resolve if sufficient need and interest exists and an appropriate mechanism can be found. -.. _choosealicense: https://choosealicense.com/ -.. _numpyissue: https://github.com/numpy/numpy/issues/8689 -.. _pep621specdynamic: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic +.. _pyprojecttomldynamic: https://packaging.python.org/en/latest/specifications/pyproject-toml/#dynamic .. _pytorch: https://pypi.org/project/torch/ .. _reusediscussion: https://github.com/pombredanne/spdx-pypi-pep/issues/7 -.. _scipyissue: https://github.com/scipy/scipy/issues/7093 .. _setuptoolsfiles: https://github.com/pypa/setuptools/issues/2739 .. _spdxid: https://spdx.dev/ids/ .. _spdxversion: https://github.com/pombredanne/spdx-pypi-pep/issues/6 diff --git a/peps/pep-0639/appendix-user-scenarios.rst b/peps/pep-0639/appendix-user-scenarios.rst index 449f8fc2c..d54902963 100644 --- a/peps/pep-0639/appendix-user-scenarios.rst +++ b/peps/pep-0639/appendix-user-scenarios.rst @@ -16,7 +16,7 @@ User Scenarios -------------- The following covers the range of common use cases from a user perspective, -providing straightforward guidance for each. Do note that the following +providing guidance for each. Do note that the following should **not** be considered legal advice, and readers should consult a licensed legal practitioner in their jurisdiction if they are unsure about the specifics for their situation. @@ -50,8 +50,7 @@ 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 (e.g. Setuptools ``license_expression = MIT`` -under ``[metadata]`` in ``setup.cfg``). You're done! +or in its config file/section. You're done! I want to distribute my project under a specific license @@ -62,8 +61,7 @@ file at the root of your repo, if you don't have it in a file starting with ``LICENSE`` or ``COPYING`` already, and add ``license = "LICENSE-ID"`` under ``[project]`` in your ``pyproject.toml`` if your packaging tool supports it, or else in its -config file (e.g. for Setuptools, ``license_expression = LICENSE-ID`` -under ``[metadata]`` in ``setup.cfg``). You can find the ``LICENSE-ID`` +config file. You can find the ``LICENSE-ID`` and copyable license text on sites like `ChooseALicense `__ or `SPDX `__. @@ -80,7 +78,6 @@ functionality. In your project config file, enter your license expression under ``license`` (``[project]`` table in ``pyproject.toml``), -``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` table subkeys or ``License ::`` classifiers. Your existing ``license`` value may already @@ -88,16 +85,12 @@ 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. -If your license files begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or -``AUTHORS``, or you've already configured your packaging tool to add them -(e.g. ``license_files`` in ``setup.cfg``), you should already be good to go. -If not, make sure to list them under ``license-files.paths`` +Make sure to list your license files 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 -(e.g. ``license_files`` in ``setup.cfg`` for Setuptools). +or else in your tool's configuration file. See the :ref:`639-example-basic` for a simple but complete real-world demo -of how this works in practice, including some additional technical details. +of how this works in practiced. Packaging tools may support automatically converting legacy licensing metadata; check your tool's documentation for more information. @@ -107,8 +100,8 @@ My package includes other code under different licenses If your project includes code from others covered by different licenses, such as vendored dependencies or files copied from other open source -software, you can construct a license expression (or have a tool -help you do so) to describe the licenses involved and the relationship +software, you can construct a license expression +to describe the licenses involved and the relationship between them. In short, ``License-1 AND License-2`` mean that *both* licenses apply @@ -121,19 +114,15 @@ complex situations. In your project config file, enter your license expression under ``license`` (``[project]`` table of ``pyproject.toml``), -``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your packaging tool, and make sure to remove any legacy ``license`` table subkeys or ``License ::`` classifiers. Also, make sure you add the full license text of all the licenses as files -somewhere in your project repository. If all of them are in the root directory -and begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or ``AUTHORS``, -they will be included automatically. Otherwise, you'll need to list the +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 -(e.g. ``license_files`` in ``setup.cfg`` for Setuptools). +(if your tool supports it), or else 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 @@ -146,8 +135,8 @@ as glob patterns, or ``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]`` as literal file paths. -See a fully worked out :ref:`639-example-advanced` for a comprehensive end-to-end -application of this to a real-world complex project, with copious technical +See a fully worked out :ref:`639-example-advanced` for an end-to-end +application of this to a real-world complex project, with many technical details, and consult a `tutorial `__ for more help and examples using SPDX identifiers and expressions.