python-peps/pep-0639.rst

PEP: 639
Title: Improving License Clarity with Better Package Metadata
Author: Philippe Ombredanne <pombredanne@nexb.com>,
        C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>,
Sponsor: Paul Moore <p.f.moore@gmail.com>
PEP-Delegate: Brett Cannon <brett@python.org>
Discussions-To: https://discuss.python.org/t/12622
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 15-Aug-2019
Post-History: `15-Aug-2019 <https://discuss.python.org/t/2154>`__,
              `17-Dec-2021 <https://discuss.python.org/t/12622>`__


.. _639-abstract:

Abstract
========

This PEP defines a specification for how licenses are documented in the
`core metadata <coremetadataspec_>`__, with
:ref:`license expression strings <639-spec-field-license-expression>` using
`SPDX identifiers <spdxid_>`__ 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.

The PEP also:

- :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.

- Deprecates the legacy ``License`` :ref:`field <639-spec-field-license>`
  and ``license ::`` :ref:`classifiers <639-spec-field-classifier>`.

- :ref:`Adds and deprecates <639-spec-source-metadata>` the corresponding keys
  in the :pep:`621` project source metadata format.

- :ref:`Provides clear guidance <639-spec-converting-metadata>` for authors and
  tools converting legacy license metadata, adding license files and
  validating license expressions.

- Describes a :ref:`reference implementation <639-reference-implementation>`,
  analyzes numerous :ref:`potential alternatives <639-rejected-ideas>`,
  includes :ref:`detailed examples <639-examples>`,
  explains :ref:`user scenarios <639-user-scenarios>` and
  surveys license documentation
  :ref:`in Python packaging <639-license-doc-python>` and
  :ref:`other ecosystems <639-license-doc-other-projects>`.

The changes in this PEP will update the
:`core metadata <coremetadataspec_>`__ to version 2.3, modify the
`PEP 621 project metadata specification <pep621spec_>`__,
and make minor additions to the `source distribution (sdist) <sdistspec_>`__,
`built distribution (wheel) <wheelspec_>`__ and
`installed project <installedspec_>`__ standards.


.. _639-goals:

Goals
=====

This PEP's scope is limited to covering new mechanisms for documenting
the license of a distribution package, specifically defining:

- A means of specifying a SPDX license expression.
- A method of including license texts in distributions and installed projects.

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.


.. _639-non-goals:

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.

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.

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,
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>`.


.. _639-motivation:

Motivation
==========

All software is licensed, and 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.

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 <classifierissue_>`__,
`license interoperability with other ecosystems <interopissue_>`__,
`too many confusing license metadata options <packagingissue_>`__,
`limited support for license files in the Wheel project <wheelfiles_>`__, and
`the lack of clear, precise and standardized license metadata <pepissue_>`__.

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 <cdstats_>`__ of the
`ClearlyDefined project <clearlydefined_>`__, an
`Open Source Initiative <osi_>`__ incubated effort to help
improve licensing clarity of other FOSS projects, covering all packages
from PyPI, Maven, npm and Rubygems.


.. _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>`.

There are a few takeaways from the survey:

- Most package formats use a single ``License`` field.

- 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.

- 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 distribution.

These considerations have guided the design and recommendations of this PEP.

The current license classifiers cover some common cases, and could
theoretically be extended to include the full range of current SPDX
identifiers while deprecating the many ambiguous classifiers (including some
extremely popular and particularly problematic ones, such as
``License :: OSI Approved :: BSD License``). However, this both requires a
substantial amount of effort to duplicate the SPDX license list and keep
it in sync, and 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.

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.

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.


.. _639-terminology:

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. :pep:`621` *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 <pypugglossary_>`__
(specifically *built/binary distribution*, *distribution package*,
*project* and *source distribution*), and by the `SPDX Project <spdx_>`__
(*license identifier*, *license expression*).

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 <coremetadataspec_>`__ and the set of metadata fields
  it defines that describe key static attributes of distribution packages
  and installed projects.

  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``).

**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, *not* a :pep:`621` project
  metadata format key.

**Distribution Package** *(Sub: Package, Distribution Archive)*
  (`See PyPUG <pypugdistributionpackage_>`__)
  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**.

**License Classifier**
  A `PyPI Trove classifier <classifiers_>`__ (as originally defined in
  :pep:`301`) which begins with ``License ::``, currently used to indicate
  a project's license status by including it as a ``Classifier``
  in the core metadata.

**License Expression** *(Syn: SPDX Expression)*
  A string with valid `SPDX license expression syntax <spdxpression_>`__
  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 Identifier** *(Syn: License ID/SPDX Identifier)*
  A valid `SPDX short-form license identifier <spdxid_>`__, 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``

**Project** *(Sub: Project Source Tree, Installed Project)*
  (`See PyPUG <pypugproject_>`__)
  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 <installedspec_>`__.

**Project Source Metadata** *(Sub: PEP 621 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 :pep:`621` ``pyproject.toml``,
  in the ``[metadata]`` table of ``setup.cfg``, or the equivalent for other
  build tools.

  The **PEP 621 metadata** refers specifically to the former, as defined by the
  `PyPA Declaring Project Metadata specification <pep621spec_>`__.
  A **PEP 621 metadata key**, or an unqualified *key* refers specifically to
  a top-level ``[project]`` key (notably, *not* a core metadata *field*),
  while a **subkey** refers to a second-level key in a table-valued
  :pep:`621` 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  ``license_files`` of the directory
  containing the core metadata (i.e., the ``.dist-info/license_files``
  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 PyPA <wheelspec_>`__, will be referred to in
  lowercase, while the `Wheel project <wheelproject_>`__, its reference
  implementation, will be referred to as such with **Wheel** in Title Case.


.. _639-specification:

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 <coremetadataspec_>`__, and
:ref:`author-provided project source metadata <639-spec-source-metadata>`,
as originally defined in :pep:`621`.

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.

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:

Core metadata
-------------

The `PyPA Core Metadata specification <coremetadataspec_>`__ 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.3.


.. _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
documented in the `SPDX specification <spdxpression_>`__, 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:

- Any SPDX-listed license short-form identifiers that are published in the
  `SPDX License List <spdxlist_>`__, version 3.15 or any later compatible
  version. Note that the SPDX working group never removes any license
  identifiers; instead, they may choose to mark an identifier as "deprecated".

- 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:

- 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>`)

- SHOULD report an informational warning, and publishing tools MAY raise an
  error, if one or more license identifiers have been marked as deprecated in
  the `SPDX License List <spdxlist_>`__.

- MUST store a case-normalized version of the ``License-Expression`` field
  using the reference case for each SPDX license identifier and
  uppercase for the ``AND``, ``OR`` and ``WITH`` keywords.

- SHOULD report an informational warning, and MAY raise an error if
  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) <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.
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.


.. _639-spec-field-license-file:

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.
It is a multi-use field that may appear zero or
more times, each instance listing 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.

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.

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.

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.3`` or
higher, PyPI SHOULD validate that the specified files are present in all
uploaded distributions, and MUST reject uploads that do not validate.


.. _639-spec-field-license:

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,
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
``License-Expression`` field, the `Python Package Index (PyPI) <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.

Along with license classifiers, the ``License`` field may be removed from a
new version of the specification in a future PEP.


.. _639-spec-field-classifier:

Deprecate license classifiers
'''''''''''''''''''''''''''''

Using license `classifiers <classifiers_>`__ in the ``Classifier`` field
(described in :pep:`301`) is deprecated and replaced by the more precise
``License-Expression`` field.

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

Otherwise, if this field contains a license classifier, build tools MAY
and publishing tools SHOULD issue a warning informing users such classifiers
are deprecated, and recommending ``License-Expression`` instead.
For compatibility with existing publishing and installation processes,
the presence of license classifiers SHOULD NOT raise an error unless
``License-Expression`` is also provided.

For all newly-uploaded distributions that include a
``License-Expression`` field, the `Python Package Index (PyPI) <pypi_>`__ MUST
reject any that also specify any license classifiers.

New license classifiers MUST NOT be `added to PyPI <classifiersrepo_>`__;
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.


.. _639-spec-source-metadata:

Project source metadata
-----------------------

As originally introduced in :pep:`621`, the
`PyPA Declaring Project Metadata specification <pep621spec_>`__
defines how to declare a project's source
metadata in 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>` the ``license-expression``
key, :ref:`adds <639-spec-key-license-files>` the ``license-files`` key and
:ref:`deprecates <639-spec-key-license>` the ``license`` key.


.. _639-spec-key-license-expression:

Add ``license-expression`` key
''''''''''''''''''''''''''''''

A new ``license-expression`` key is added to the ``project`` table, which has
a string value that is a valid SPDX license expression, as
:ref:`defined previously <639-license-expression-definition>`.
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.

If and only if the ``license-expression`` key is listed as ``dynamic``
(and is not specified), tools MAY infer a value for the ``License-Expression``
field if they can do so unambiguously, but MUST follow the provisions in the
:ref:`639-spec-converting-metadata` section.

If the ``license-expression`` key is present and valid (and the ``license``
key is not specified), for purposes of backward compatibility, tools MAY
back-fill the ``License`` core metadata field with the case-normalized value
of the ``license-expression`` key.


.. _639-spec-key-license-files:

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.

Its value is a table, which if present MUST contain one of two optional,
mutually exclusive subkeys, ``paths`` and ``globs``; if both are specified,
tools MUST raise an error. Both are arrays of strings; the ``paths`` subkey
contains verbatim file paths, and the ``globs`` subkey valid glob patterns,
which MUST be parsable by the ``glob`` `module <globmodule_>`__ 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,
and SHOULD validate this and raise an error if it is not.

If the ``paths`` subkey is a non-empty array, build tools:

- MUST treat each value as a verbatim, literal file path, and
  MUST NOT treat them as glob patterns.

- MUST include each listed file in all distribution archives.

- 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 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.

If the ``globs`` subkey is a non-empty array, build tools:

- MUST treat each value as a glob pattern, and MUST raise an error if the
  pattern contains invalid glob syntax.

- MUST include all files matched by at least one listed pattern in all
  distribution archives.

- MAY exclude files matched by glob patterns that can be unambiguously
  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.

- SHOULD issue a warning and MAY raise an error if no files are matched.

- MAY issue a warning if any individual user-specified pattern
  does not match at least one file.

If the ``license-files`` key is present, and the ``paths`` or ``globs`` subkey
is set to a value of an empty array, then tools MUST NOT include any
license files and MUST NOT raise an error.

.. _639-default-patterns:

If the ``license-files`` key is not present and not explicitly marked as
``dynamic``, tools MUST assume a default value of the following:

.. code-block:: toml

    license-files.globs = ["LICEN[CS]E*", "COPYING*", "NOTICE*", "AUTHORS*"]

In this case, tools MAY issue a warning if no license files are matched,
but MUST NOT raise an error.

If the ``license-files`` key is marked as ``dynamic`` (and not present),
to preserve consistent behavior with current tools and help ensure the packages
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.


.. _639-spec-key-license:

Deprecate ``license`` key
'''''''''''''''''''''''''

The ``license`` key in the ``project`` table is now deprecated.
It MUST NOT be used or listed as ``dynamic`` if either of the new
``license-expression`` or ``license-files`` keys are defined,
and build tools MUST raise an error if either is the case.

Otherwise, if the ``text`` subkey is present in the ``license`` table, tools
SHOULD issue a warning informing users it is deprecated and recommending the
``license-expression`` key instead.

Likewise, if the ``file`` subkey is present in the ``license`` table, tools
SHOULD issue a warning informing users it is deprecated and recommending
the ``license-files`` key instead. However, if the file is present in the
source, build tools SHOULD still use it to fill the ``License-File`` field
in the core metadata, and if so, MUST include the specified file in any
distribution archives for the project. If the file does not exist at the
specified path, tools SHOULD issue a warning, and MUST NOT fill it in a
``License-File`` field.

For backwards compatibility, to preserve consistent behavior with current tools
and ensure that users do not unknowingly create packages that are not legally
distributable, tools MUST assume the
:ref:`specified default value <639-default-patterns>` for the
``license-files`` key and also include, in addition to the license file
specified under this ``file`` subkey, any license files that match the
specified list of patterns.

The ``license`` key may be removed from a new version of the specification
in a future PEP.


.. _639-spec-project-formats:

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.

**Project source trees**
  As described in the :ref:`639-spec-source-metadata` section, the
  `Declaring Project Metadata specification <pep621spec_>`__
  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 <sdistspec_>`__ will be updated to reflect that for
  ``Metadata-Version`` is ``2.3`` 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).

**Built distributions** *(wheels)*
  The `wheel specification <wheelspec_>`__ will be updated to reflect that if
  the ``Metadata-Version`` is ``2.3`` or greater and one or more
  ``License-File`` fields is specified, the ``.dist-info`` directory MUST
  contain a ``license_files`` subdirectory which MUST contain the files listed
  in the ``License-File`` fields in the ``METADATA`` file at their respective
  paths relative to the ``license_files`` directory.

**Installed projects**
  The `Recording Installed Projects specification <installedspec_>`__ will be
  updated to reflect that if the ``Metadata-Version`` is ``2.3`` or greater
  and one or more ``License-File`` fields is specified, the ``.dist-info``
  directory MUST contain a ``license_files`` subdirectory which MUST contain
  the files listed in the ``License-File`` fields in the ``METADATA`` file
  at their respective paths relative to the ``license_files`` directory,
  and that any files in this directory MUST be copied from wheels
  by install tools.


.. _639-spec-converting-metadata:

Converting legacy metadata
--------------------------

If the contents of the ``license.text`` :pep:`621` source metadata key
(or equivalent for tool-specific config formats) is a valid license expression
containing solely known, non-deprecated license identifiers, and, if
:pep:`621` metadata are defined, the ``license-expression`` key is listed as
``dynamic``, build tools MAY use it to fill the ``License-Expression`` field.

Similarly, if the ``classifiers`` :pep:`621` source metadata key (or equivalent
for tool-specific config formats) contains exactly one license classifier
that unambiguously maps to exactly one valid, non-deprecated SPDX license
identifier, tools MAY fill the ``License-Expression`` field with the latter.

If both a ``license.text`` or equivalent value and a single license classifier
are present, the contents of the former, including capitalization
(but excluding leading and trailing whitespace), MUST exactly match the SPDX
license identifier mapped to the license classifier to be considered
unambiguous for the purposes of automatically filling the
``License-Expression`` field.

If tools have filled the ``License-Expression`` field as described here,
they MUST output a prominent, user-visible warning informing package authors
of that fact, including the ``License-Expression`` string they have output,
and recommending that the project source metadata be updated accordingly
with the indicated license expression.

In any other case, tools MUST NOT use the contents of the ``license.text``
key (or equivalent) or license classifiers to fill the
``License-Expression`` field without informing the user and requiring
unambiguous, affirmative user action to select and confirm the desired
``License-Expression`` value before proceeding.


.. _639-spec-mapping-classifiers-identifiers:

Mapping license classifiers to SPDX identifiers
'''''''''''''''''''''''''''''''''''''''''''''''

Most single license classifiers (namely, all those not mentioned below)
map to a single valid SPDX license identifier, allowing tools to insert them
into the ``License-Expression`` field following the
:ref:`specification above <639-spec-converting-metadata>`.

Many legacy license classifiers intend to specify a particular license,
but do not specify the particular version or variant, leading to a
`critical ambiguity <classifierissue_>`__ as to their terms, compatibility
and acceptability. Tools MUST NOT attempt to automatically infer a
``License-Expression`` when one of these classifiers is used, and SHOULD
instead prompt the user to affirmatively select and confirm their intended
license choice.

These classifiers are the following:

- ``License :: OSI Approved :: Academic Free License (AFL)``
- ``License :: OSI Approved :: Apache Software License``
- ``License :: OSI Approved :: Apple Public Source License``
- ``License :: OSI Approved :: Artistic License``
- ``License :: OSI Approved :: BSD License``
- ``License :: OSI Approved :: GNU Affero General Public License v3``
- ``License :: OSI Approved :: GNU Free Documentation License (FDL)``
- ``License :: OSI Approved :: GNU General Public License (GPL)``
- ``License :: OSI Approved :: GNU General Public License v2 (GPLv2)``
- ``License :: OSI Approved :: GNU General Public License v3 (GPLv3)``
- ``License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)``
- ``License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)``
- ``License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)``
- ``License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)``

A comprehensive mapping of these classifiers to their possible specific
identifiers was `assembled by Dustin Ingram <badclassifiers_>`__, which tools
MAY use as a reference for the identifier selection options to offer users
when prompting the user to explicitly select the license identifier
they intended for their project.

**Note**: Several additional classifiers, namely the "or later" variants of
the AGPLv3, GPLv2, GPLv3 and LGPLv3, are also listed in the aforementioned
mapping, but as they were merely proposed for textual harmonization and
still unambiguously map to their respective licenses,
they were not included here; LGPLv2 is, however, as it could ambiguously
refer to either the distinct v2.0 or v2.1 variants of that license.

In addition, for the various special cases, the following mappings are
considered canonical and normative for the purposes of this specification:

- Classifier ``License :: Public Domain`` MAY be mapped to the generic
  ``License-Expression: LicenseRef-Public-Domain``.
  If tools do so, they SHOULD issue an informational warning encouraging
  the use of more explicit and legally portable license identifiers,
  such as those for the `CC0 1.0 license <cc0_>`__ (``CC0-1.0``),
  the `Unlicense <unlicense_>`__ (``Unlicense``),
  or the `MIT license <mitlicense_>`__ (``MIT``),
  since the meaning associated with the term "public domain" is thoroughly
  dependent on the specific legal jurisdiction involved,
  some of which lack the concept entirely.
  Alternatively, tools MAY choose to treat these classifiers as ambiguous and
  require user confirmation to fill ``License-Expression`` in these cases.

- The generic and sometimes ambiguous classifiers
  ``License :: Free For Educational Use``,
  ``License :: Free For Home Use``,
  ``License :: Free for non-commercial use``,
  ``License :: Freely Distributable``,
  ``License :: Free To Use But Restricted``,
  ``License :: Freeware``, and
  ``License :: Other/Proprietary License`` MAY be mapped to the generic
  ``License-Expression: LicenseRef-Proprietary``,
  but tools MUST issue a prominent, informative warning if they do so.
  Alternatively, tools MAY choose to treat these classifiers as ambiguous and
  require user confirmation to fill ``License-Expression`` in these cases.

- The generic and ambiguous classifiers ``License :: OSI Approved`` and
  ``License :: DFSG approved`` do not map to any license expression,
  and thus tools MUST treat them as ambiguous and require user intervention
  to fill ``License-Expression``.

- The classifiers ``License :: GUST Font License 1.0`` and
  ``License :: GUST Font License 2006-09-30`` have no mapping to SPDX license
  identifiers and no PyPI package uses them, as of the writing of this PEP.
  Therefore, tools MUST treat them as ambiguous when attempting to fill
  ``License-Expression``.

When multiple license classifiers are used, their relationship is ambiguous,
and it is typically not possible to determine if all the licenses apply or if
there is a choice that is possible among the licenses. In this case, tools
MUST NOT automatically infer a license expression, and SHOULD suggest that the
package author construct one which expresses their intent.


.. _639-backwards-compatibility:

Backwards Compatibility
=======================

Adding a new, dedicated ``License-Expression`` core metadata field and
``license-expression`` :pep:`621` source metadata key 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.

The legacy ``License`` core metadata field and ``license`` :pep:`621` source
metadata key 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.

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``
:pep:`621` source metadata key 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.

Due to requiring license files not be flattened into ``.dist-info`` and
specifying that they should be placed in a dedicated ``license_files`` 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.

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.

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.

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.


.. _639-security-implications:

Security Implications
=====================

This PEP has no foreseen security implications: the ``License-Expression``
field is a plain string and the ``License-File`` fields are file paths.
Neither introduces any known new security concerns.


.. _639-how-to-teach-this:

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.

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.

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-expression``
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:

- The section :ref:`639-spec-mapping-classifiers-identifiers` provides
  tool authors with guidelines 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 and convert that to a ``License-Expression``.
  For instance, a tool may suggest converting from a ``License`` field with
  ``Apache2`` (which is not a valid license expression as defined in this PEP)
  to a ``License-Expression`` field with ``Apache-2.0`` (which is a valid
  license expression using an SPDX license identifier).


.. _639-reference-implementation:

Reference Implementation
========================

Tools will need to support parsing and validating license expressions in the
``License-Expression`` field.

The `license-expression library <licenseexplib_>`__ is a reference Python
implementation that handles license expressions including parsing,
formatting and validation, using flexible lists of license symbols
(including SPDX license IDs and any extra identifiers included here).
It is licensed under Apache-2.0 and is already used in several projects,
including the `SPDX Python Tools <spdxpy_>`__,
the `ScanCode toolkit <scancodetk_>`__
and the Free Software Foundation Europe (FSFE) `REUSE project <reuse_>`__.


.. _639-rejected-ideas:

Rejected Ideas
==============

Core metadata fields
--------------------

Potential alternatives to the structure, content and deprecation of the
core metadata fields specified in this PEP.


Re-use the ``License`` field
''''''''''''''''''''''''''''

Following `initial discussion <reusediscussion_>`__, earlier versions of this
PEP 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.

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),
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 this PEP.

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 this PEP 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``).

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 this PEP provides extensive
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
the ``License`` field. However, this effectively amounted to creating
a field within a field, and doesn't address all 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
project's source metadata. Therefore, it was rejected in favor of a new field.


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
license metadata in no less than *three* different fields, which is
squarely contrary to the goals of this PEP of making the licensing story
simpler and unambiguous. Therefore, and in concert with clear community
consensus otherwise, this idea was soundly rejected.


Don't deprecate existing ``License`` field and classifiers
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Several community members were initially 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
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-expression`` 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 <choosealicense_>`__ 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, this PEP 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. This PEP 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 this PEP, 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 this PEP.

Finally, for unmaintained packages, those using tools supporting older
metadata versions, or those who choose not to provide license metadata,
no changes are required regardless of the deprecation.


Don't mandate validating new fields on PyPI
'''''''''''''''''''''''''''''''''''''''''''

Previously, while this PEP did include normative guidelines for packaging
publishing tools (such as Twine), it 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
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
the new field should be validated from the start, guaranteeing that all
distributions uploaded to PyPI that declare core metadata version 2.3
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
specification in this PEP, it is assured to be valid.


Source metadata ``license`` key
-------------------------------

Alternate possibilities related to the ``license`` key in the
``pyproject.toml`` project source metadata specified in :pep:`621`.


Add ``expression`` and ``files`` subkeys to table
'''''''''''''''''''''''''''''''''''''''''''''''''

A previous working draft of this PEP added ``expression`` and ``files`` subkeys
to the existing ``license`` table in the :pep:`621` 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
relative to that ultimately taken here.

Most saliently, 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.
This also breaks from the consensus for the core metadata fields, namely to
separate the license expression into its own explicit field.

Furthermore, this leads to a conflict with marking the key as ``dynamic``
(assuming that is intended to specify :pep:`621` keys, as that PEP seems to rather
imprecisely imply, rather than core metadata fields), as either both would have
to be treated as ``dynamic``. A user may want to specify the ``expression``
key as ``dynamic``, if they intend their tooling to generate it automatically;
conversely, they may rely on their build tool to dynamically detect license
files via means outside of that strictly specified here. And indeed, current
users may mark the present ``license`` key as ``dynamic`` to automatically
fill it in the metadata. Grouping all these uses under the same key forces an
"all or nothing" approach, and creates ambiguity as to user intent.

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
:pep:`621` keys and core metadata fields, not in keeping with :pep:`621`.
This causes the :pep:`621` naming and structure to diverge further 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.

The approach this PEP now takes, adding distinct ``license-expression`` and
``license-files`` keys and simply deprecating the whole ``license`` key, avoids
all the issues identified above, 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
:pep:`621` keys to core metadata fields, and reduces nesting by a level for both.
Other than adding two extra keys to the file, there was no significant
apparent downside to this latter approach, so it was adopted for this PEP.


Define license expression as string value
'''''''''''''''''''''''''''''''''''''''''

A compromise approach between adding two new top-level keys for license
expressions and files would be adding a separate ``license-files`` key,
but re-using the ``license`` key for the license expression, either by
defining it as the (previously reserved) string value for the ``license``
key, retaining the ``expression`` subkey in the ``license`` table, or
allowing both. Indeed, this would seem to have been envisioned by :pep:`621`
itself with this PEP in mind, in particular the first approach:

    A practical string value for the license key has been purposefully left
    out to allow for a future PEP to specify support for SPDX expressions
    (the same logic applies to any sort of "type" field specifying what
    license the file or text represents).

However, while a working draft temporarily explored this solution, it was
ultimately rejected, as it shared most of the downsides identified with
adding new subkeys under the existing ``license`` table, as well as several
of its own, with again minimal advantage over separating both.

Most importantly, it still means that per :pep:`621`, it is not possible to
separately mark the ``[project]`` keys corresponding to the ``License`` and
``License-Expression`` metadata fields as dynamic. This, in turn, still
renders specifying metadata following that standard incompatible with
conversion of legacy metadata, as specified in this PEP's
:ref:`639-spec-converting-metadata`, as :pep:`621` strictly prohibits the
``license`` key from being both present (to define the existing value of
the ``License`` field, or the path to a license file, and thus able to be
converted), and specified as ``dynamic`` (which would allow tools to
use the generated value for the ``License-Expression`` field.

For the same reasons, this would make it impossible to back-fill the
``License`` field from the ``License-Expression`` field as this PEP
currently allows (without making an exception from strict
``dynamic`` behavior in this case), as again, marking ``license`` as dynamic
would mean it cannot be specified in the ``project`` table at all.

Furthermore, this would mean existing project source metadata specifying
``license`` as ``dynamic`` would be ambiguous, as it would be impossible for
tools to statically determine if they are intended to conform to previous
metadata versions specifying ``License``, or this version specifying
``License-Expression``. Tools would have no way of determining which field,
if either, might be filled in the resulting distribution's core metadata.
By contrast, the present approach makes clear what the author intended,
allows tools to unambiguously determine which field(s) may be dynamically
inserted, and ensures backward compatibility such that current project
source metadata do not unknowingly specify both the old and the new field
as dynamic, and instead must do so explicitly per :pep:`621`'s intent.

Additionally, while differences from existing tool formats (and core metadata
field names) has precedent in :pep:`621` (though is best avoided if practical),
using a key with an identical name as in all current tools (and of an existing
core metadata field) to mean something different (and map to a different
core metadata field), with distinct and incompatible syntax and semantics,
does not, and is likely to create substantial and confusion and ambiguity
for readers and authors, contrary to the fundamental goals of this PEP.

Finally, this means that the top-level ``license`` key still maps to multiple
core metadata fields with different purposes and interpretation (``License``
and ``License-Expression``), this would deny a clear separation from the
old behavior by not cleanly deprecating the ``license`` key, and
increases the complexity of the specification and implementation.

In addition to the aforementioned issues, this also requires deciding between
the three individual approaches (``expression`` subkey, top-level string or
allowing both), all of which have further significant downsides and none of
which are clearly superior or more obvious, leading to needless bikeshedding.

If the license expression was made the string value of the ``license`` key,
as reserved by :pep:`621`, it would be slightly shorter for users to type and
more obviously the preferred approach. However, it is far *less* obvious that
it is a license expression at all, to authors and those viewing the files,
and this lack of clarity, explicitness, ambiguity and potential for user
confusion is exactly what this PEP seeks to avoid, all to save a few characters
over other approaches.

If an ``expression`` subkey was added to the ``license`` table, it would retain
the clarity of a new top-level key, but add additional complexity for no
real benefit, with an extra level of nesting, and users and tools needing to
deal with the mutual exclusivity of the subkeys, as before. And allowing both
(as a table subkey *and* the string value) would inherit both's downsides,
while adding even more spec and tool complexity and making there more than
"one obvious way to do it", further potentially confusing users.

Therefore, a separate top-level ``license-expression`` key was adopted to avoid
all these issues, with relatively minimal downside aside from adding a single
additional key and (versus some approaches) a few extra characters to type.


Add a ``type`` key to treat as expression
'''''''''''''''''''''''''''''''''''''''''

Instead of creating a new top-level ``license-expression`` key in the
:pep:`621` source metadata, one could add a ``type`` subkey to the existing
``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
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.

However, all the same downsides as in the previous item apply here,
including greater complexity, a more complex mapping between the project
source metadata and core metadata and inconsistency between the presentation
in tool config, :pep:`621` and core metadata, a much less clean 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
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
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.


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
to be automatically back-filled from the value of the ``license-expression``
key. This would be more explicit that the filling will be done, as strictly
speaking the ``license`` key is not (and cannot be) specified in
``pyproject.toml``, and satisfies a stricter interpretation of the letter
of the current :pep:`621` specification that this PEP revises.

However, this isn't seen to be necessary, because it is simply using the
static, verbatim literal value of the ``license-expression`` key, as specified
strictly in this PEP. Therefore, any conforming tool can trivially,
deterministically and unambiguously derive this using only the static data
in the ``pyproject.toml`` file itself.

Furthermore, this actually adds significant ambiguity, as it means the value
could get filled arbitrarily by other tools, which would in turn compromise
and conflict with the value of the new ``License-Expression`` field, which is
why such is explicitly prohibited by this PEP. Therefore, not marking it as
``dynamic`` will ensure it is only handled in accordance with this PEP's
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``
field as apparently intended, and prevents tools from adapting to best
practices (fill, don't fill, etc) as they develop and evolve over time.


Source metadata ``license-files`` key
-------------------------------------

Alternatives considered for the ``license-files`` key in the
:pep:`621` project source metadata, primarily related to the
path/glob type handling.


Add a ``type`` subkey to ``license-files``
''''''''''''''''''''''''''''''''''''''''''

Instead of defining mutually exclusive ``paths`` and ``globs`` subkeys
of the ``license-files`` :pep:`621` project metadata 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,
or another additional subkey in the future, as well as the need to bikeshed
over the subkey name. Therefore, it was summarily 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
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.

However, practicality once again beats purity here. Globs are supported and
used by many existing tools for finding license files, and explicitly
specifying the full path to every license file would be unnecessarily tedious
for more complex projects with vendored code and dependencies. More
critically, it would make it much easier to accidentally miss a required
legal file, silently rendering 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
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.
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
files explicitly via the ``paths`` table subkey, once they are aware of it and
if it is suitable for their project and workflow.


Only accept glob patterns
'''''''''''''''''''''''''

Conversely, all ``license-files`` strings could be treated as glob patterns.
This would slightly simplify the spec and implementation, avoid an extra level
of nesting, and more closely match the configuration format of existing tools.

However, for the cost of a few characters, it ensures users are aware
whether they are entering globs or verbatim paths. Furthermore, allowing
license files to be specified as literal paths avoids edge cases, such as those
containing glob characters (or those confusingly or even maliciously similar
to them, as described in :pep:`672`).

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
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.

Therefore, given the relatively small cost and the significant benefits,
this approach was not adopted.


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
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.

This, in turn, allows for more appropriate, 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
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.
This also avoids edge cases (e.g. paths that contain glob characters) and
reliance on heuristics to determine interpretation—the very thing this PEP
seeks to avoid.


.. _639-license-files-allow-flat-array:

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).

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.

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
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.


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``.

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.

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.

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.
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
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.


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
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.

Moreover, even if this were not so, practicality would trump purity, as this
interpretation would be strictly 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
projects unknowingly no longer including legally mandatory license files,
making their distribution technically illegal, and is thus not a sane,
much less sensible 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 :pep:`621` portions of this PEP; to do otherwise would defeat
the primary purpose of the ``dynamic`` list as a marker and escape hatch.


License file paths
------------------

Alternatives related to the paths and locations of license files in the source
and built distributions.


Flatten license files in subdirectories
'''''''''''''''''''''''''''''''''''''''

Previous drafts of this PEP were silent on the issue of handling license files
in subdirectories. Currently, the `Wheel <wheelfiles_>`__ and (following its
example) `Setuptools <setuptoolsfiles_>`__ 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.

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 :pep:`621` "static" 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,
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 ``license_files``
subdirectory eliminates both collisions and the clutter problem entirely.


Resolve name conflicts differently
''''''''''''''''''''''''''''''''''

Rather than preserving the source directory structure for license files
inside the ``.dist-info`` directory, we could specify some other mechanism
for conflict resolution, such as pre- or appending the parent directory name
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.


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.

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
(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,
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.

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
relative to a ``license_files`` subdirectory of ``.dist-info``. This is simple
to implement and solves all the problems noted here, without clear significant
drawbacks relative to other more complex options.

It does make the specification a bit more complex and less elegant, 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 this PEP 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 this PEP.


Add new ``licenses`` category to wheel
''''''''''''''''''''''''''''''''''''''

Instead of defining a root license directory (``license_files``) inside
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.

However, at present, this PEP does not implement this idea, and it is
deferred to a future one. It would add significant complexity and friction
to this PEP, 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
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.

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
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.

Therefore, to keep this PEP in scope, the current approach was retained.


Name the subdirectory ``licenses``
''''''''''''''''''''''''''''''''''

Both ``licenses`` and ``license_files`` have been suggested as potential
names for the root license directory inside ``.dist-info`` of wheels and
installed projects. The former is slightly shorter, but the latter is
more clear and unambiguous regarding its contents, and is consistent with
the name of the core metadata field (``License-File``) and the :pep:`621`
project source metadata key (``license-files``). Therefore, the latter
was chosen instead.


Other ideas
-----------

Miscellaneous proposals, possibilities and discussion points that were
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.

A mapping would be needed, as it cannot be guaranteed that all expressions
(keys) have a single license file associated with them (e.g.
GPL with an exception may be in a single file) and that any expression
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
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.

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.
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
string. Therefore, this approach is rejected.


Map identifiers to source files
'''''''''''''''''''''''''''''''

As discussed previously, file-level notices are out of scope for this PEP,
and the existing ``SPDX-License-Identifier`` `convention <spdxid_>`__ can
already be used if this is needed without further specification here.


Don't freeze compatibility with a specific SPDX version
'''''''''''''''''''''''''''''''''''''''''''''''''''''''

This PEP 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.

However, serious concerns were expressed about a future SPDX update breaking
compatibility with existing expressions and identifiers, leaving current
packages with invalid metadata per the definition in this PEP. Requiring
compatibility with a specific version of these specifications here
and a PEP or similar process to update it avoids this contingency,
and follows the practice of other packaging ecosystems.

Therefore, it was `decided <spdxversion_>`__ to specify a minimum version
and requires 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.


.. _639-rejected-ideas-difference-license-source-binary:

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
(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 <pytorch_>`__, which contains CUDA from Nvidia, which is freely
distributable but not open source. `NumPy <numpyissue_>`__ and
`SciPy <scipyissue_>`__ also had similar issues, as reported by the
original author of this PEP and now resolved for those cases.

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
information, lack of support on PyPI for exposing license info on a
per-distribution archive basis, and the relatively niche use case, it was
determined to be out of scope for this PEP, and left to a future PEP
to resolve if sufficient need and interest exists and an appropriate
mechanism can be found.


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.

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.

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?


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
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.

For maximum flexibility, custom ``LicenseRef-<CUSTOM-TEXT>`` 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.

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.

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 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 (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.


.. _639-examples:

Appendix: License Expression Examples
=====================================

.. _639-example-basic:

Basic example
-------------

The Setuptools project itself, as of `version 59.1.1 <setuptools5911_>`__,
does not use the ``License`` field in its own project source metadata.
Further, it no longer explicitly specifies ``license_file``/``license_files``
as it did previously, since Setuptools relies on its own automatic
inclusion of license-related files matching common patterns,
such as the ``LICENSE`` file it uses.

It includes the following license-related metadata in its ``setup.cfg``:

.. code-block:: ini

    [metadata]
    classifiers =
        License :: OSI Approved :: MIT License

The simplest migration to this PEP would consist of using this instead:

.. code-block:: ini

    [metadata]
    license_expression = MIT

Or, in a :pep:`621` ``pyproject.toml``:

.. code-block:: toml

    [project]
    license-expression = "MIT"

The output core metadata for the distribution packages would then be:

.. code-block:: email

    License-Expression: MIT
    License-File: LICENSE

The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE``
in the sdist and ``/setuptools-${VERSION}.dist-info/license_files/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.


.. _639-example-advanced:

Advanced example
----------------

Suppose Setuptools were to include the licenses of the third-party projects
that are vendored in the ``setuptools/_vendor/`` and ``pkg_resources/_vendor``
directories; specifically:

.. code-block:: text

    packaging==21.2
    pyparsing==2.2.1
    ordered-set==3.1.1
    more_itertools==8.8.0

The license expressions for these projects are:

.. code-block:: text

    packaging: Apache-2.0 OR BSD-2-Clause
    pyparsing: MIT
    ordered-set: MIT
    more_itertools: MIT

A comprehensive license expression covering both Setuptools
proper and its vendored dependencies would contain these metadata,
combining all the license expressions into one. Such an expression might be:

.. code-block:: text

    MIT AND (Apache-2.0 OR BSD-2-Clause)

In addition, per the requirements of the licenses, the relevant license files
must be included in the package. Suppose the ``LICENSE`` file contains the text
of the MIT license and the copyrights used by Setuptools, ``pyparsing``,
``more_itertools`` and ``ordered-set``; and the ``LICENSE*`` files in the
``setuptools/_vendor/packaging/`` directory contain the Apache 2.0 and
2-clause BSD license text, and the Packaging copyright statement and
`license choice notice <packaginglicense_>`__.

Specifically, we assume the license files are located at the following
paths in the project source tree (relative to the project root and
``pyproject.toml``):

.. code-block:: ini

    LICENSE
    setuptools/_vendor/packaging/LICENSE
    setuptools/_vendor/packaging/LICENSE.APACHE
    setuptools/_vendor/packaging/LICENSE.BSD

Putting it all together, our ``setup.cfg`` would be:

.. code-block:: ini

    [metadata]
    license_expression = MIT AND (Apache-2.0 OR BSD-2-Clause)
    license_files =
        LICENSE
        setuptools/_vendor/packaging/LICENSE
        setuptools/_vendor/packaging/LICENSE.APACHE
        setuptools/_vendor/packaging/LICENSE.BSD

In a :pep:`621` ``pyproject.toml``, with license files specified explicitly
via the ``paths`` subkey, this would look like:

.. code-block:: toml

    [project]
    license-expression = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
    license-files.paths = [
        "LICENSE",
        "setuptools/_vendor/LICENSE",
        "setuptools/_vendor/LICENSE.APACHE",
        "setuptools/_vendor/LICENSE.BSD",
    ]

Or alternatively, matched via glob patterns, this could be:

.. code-block:: toml

    [project]
    license-expression = "MIT AND (Apache-2.0 OR BSD-2-Clause)"
    license-files.globs = [
        "LICENSE*",
        "setuptools/_vendor/LICENSE*",
    ]

With either approach, the output core metadata in the distribution
would be:

.. code-block:: email

    License-Expression: MIT AND (Apache-2.0 OR BSD-2-Clause)
    License-File: LICENSE
    License-File: setuptools/_vendor/packaging/LICENSE
    License-File: setuptools/_vendor/packaging/LICENSE.APACHE
    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 license files would be located at the paths:

.. code-block:: shell

    /setuptools-${VERSION}/LICENSE
    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE
    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE.APACHE
    /setuptools-${VERSION}/setuptools/_vendor/packaging/LICENSE.BSD

In the built wheel, with ``/`` being the root of the archive and
``{version}`` as the previous, the license files would be stored at:

.. code-block:: shell

    /setuptools-${VERSION}.dist-info/license_files/LICENSE
    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
    /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD

Finally, in the installed project, with ``site-packages`` being the site dir
and ``{version}`` as the previous, the license files would be installed to:

.. code-block:: shell

    site-packages/setuptools-${VERSION}.dist-info/license_files/LICENSE
    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE
    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE
    site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD


.. _639-example-conversion:

Conversion example
------------------

Suppose we were to return to our simple Setuptools case.
Per the specification, given it only has the following license classifier:

.. code-block:: email

    Classifier: License :: OSI Approved :: MIT License

And no value for the ``License`` field, or equivalently, if it had a
value of:

.. code-block:: email

    License: MIT

Then the suggested value for the ``License-Expression`` field would be:

.. code-block:: email

    License-Expression: MIT

For the more complex case, assuming it was currently expressed as multiple
license classifiers, no automatic conversion could be performed due to the
inherent ambiguity, and the user would be prompted on how to handle the
situation themselves.


.. _639-example-expression:

Expression examples
-------------------

Some additional examples of valid ``License-Expression`` values:

.. code-block:: email

    License-Expression: MIT
    License-Expression: BSD-3-Clause
    License-Expression: MIT AND (Apache-2.0 OR BSD-2-clause)
    License-Expression: MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)
    License-Expression: GPL-3.0-only WITH Classpath-Exception-2.0 OR BSD-3-Clause
    License-Expression: LicenseRef-Public-Domain OR CC0-1.0 OR Unlicense
    License-Expression: LicenseRef-Proprietary


.. _639-user-scenarios:

Appendix: 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
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.


I have a private package that won't be distributed
--------------------------------------------------

If your package isn't shared publicly, i.e. outside your company,
organization or household, it *usually* isn't strictly necessary to include
a formal license, so you wouldn't necessarily have to do anything extra here.

However, it is still a good idea to include ``LicenseRef-Proprietary``
as a license expression in your package configuration, and/or a
copyright statement and any legal notices in a ``LICENSE.txt`` file
in the root of your project directory, which will be automatically
included by packaging tools.


I just want to share my own work without legal restrictions
-----------------------------------------------------------

While you aren't required to include a license, if you don't, no one has
`any permission to download, use or improve your work <dontchoosealicense_>`__,
so that's probably the *opposite* of what you actually want.
The `MIT license <mitlicense_>`__ is a great choice instead, as it's simple,
widely used and allows anyone to do whatever they want with your work
(other than sue you, which you probably also don't want).

To apply it, just paste `the text <chooseamitlicense_>`__ into a file named
``LICENSE.txt`` at the root of your repo, and add the year and your name to
the copyright line. Then, just add ``license-expression = "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!


I want to distribute my project under a specific license
--------------------------------------------------------

To use a particular license, simply paste its text into a ``LICENSE.txt``
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-expression = "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``
and copyable license text on sites like
`ChooseALicense <choosealicenselist_>`__ or `SPDX <spdxlist_>`__.

Many popular code hosts, project templates and packaging tools can add the
license file for you, and may support the expression as well in the future.


I maintain an existing package that's already licensed
------------------------------------------------------

If you already have license files and metadata in your project, you
should only need to make a couple of tweaks to take advantage of the new
functionality.

In your project config file, enter your license expression under
``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
packaging tool, and make sure to remove any legacy ``license`` value or
``License ::`` classifiers. Your existing ``license`` value may already
be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
otherwise, check the `SPDX license list <spdxlist_>`__ for the identifier
that matches the license used in your project.

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``
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).

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.
Packaging tools may support automatically converting legacy licensing
metadata; check your tool's documentation for more information.


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
between them.

In short, ``License-1 AND License-2`` mean that *both* licenses apply
to your project, or parts of it (for example, you included a file
under another license), and ``License-1 OR License-2`` means that
*either* of the licenses can be used, at the user's option (for example,
you want to allow users a choice of multiple licenses). You can use
parenthesis (``()``) for grouping to form expressions that cover even the most
complex situations.

In your project config file, enter your license expression under
``license-expression`` (:pep:`621` ``pyproject.toml``), ``license_expression``
(Setuptools ``setup.cfg`` / ``setup.py``), or the equivalent for your
packaging tool, and make sure to remove any legacy ``license`` value 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
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).

As an example, if your project was licensed MIT but incorporated
a vendored dependency (say, ``packaging``) that was licensed under
either Apache 2.0 or the 2-clause BSD, your license expression would
be ``MIT AND (Apache-2.0 OR BSD-2-Clause)``. You might have a
``LICENSE.txt`` in your repo root, and a ``LICENSE-APACHE.txt`` and
``LICENSE-BSD.txt`` in the ``_vendor`` subdirectory, so to include
all of them, you'd specify ``["LICENSE.txt", "_vendor/packaging/LICENSE*"]``
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
details, and consult a `tutorial <spdxtutorial_>`__ for more help and examples
using SPDX identifiers and expressions.


.. _639-license-doc-python:

Appendix: License Documentation in Python
=========================================

There are multiple ways used or recommended to document Python project
licenses today. The most common are listed below.


.. _639-license-doc-core-metadata:

Core metadata
-------------

There are two overlapping core metadata fields to document a license: the
license ``Classifier`` `strings <classifiers_>`__ prefixed with ``License ::``
and the ``License`` `field <licensefield_>`__ as free text.

The core metadata ``License`` field documentation is currently:

.. code-block:: rst

    License
    =======

    .. versionadded:: 1.0

    Text indicating the license covering the distribution where the license
    is not a selection from the "License" Trove classifiers. See
    :ref:`"Classifier" <metadata-classifier>` below.
    This field may also be used to specify a
    particular version of a license which is named via the ``Classifier``
    field, or to indicate a variation or exception to such a license.

    Examples::

        License: This software may only be obtained by sending the
                author a postcard, and then the user promises not
                to redistribute it.

        License: GPL version 3, excluding DRM provisions

Even though there are two fields, it is at times difficult to convey anything
but simpler licensing. For instance, some classifiers lack precision
(GPL without a version) and when multiple license classifiers are
listed, it is not clear if both licenses must apply, or the user may choose
between them. Furthermore, the list of available license classifiers
is rather limited and out-of-date.


.. _639-license-doc-setuptools-wheel:

Setuptools and Wheel
--------------------

Beyond a license code or qualifier, license text files are documented and
included in a built package either implicitly or explicitly,
and this is another possible source of confusion:

- In the `Setuptools <setuptoolssdist_>`__ and `Wheel <wheels_>`__ projects,
  license files are automatically added to the distribution (at their source
  location in a source distribution/sdist, and in the ``.dist-info``
  directory of a built wheel) if they match one of a number of common license
  file name patterns (``LICEN[CS]E*``, ``COPYING*``, ``NOTICE*`` and
  ``AUTHORS*``). Alternatively, a package author can specify a list of license
  file paths to include in the built wheel under the ``license_files`` key in
  the ``[metadata]`` section of the project's ``setup.cfg``, or as an argument
  to the ``setuptools.setup()`` function. At present, following the Wheel
  project's lead, Setuptools flattens the collected license files into the
  metadata directory, clobbering files with the same name, and dumps license
  files directly into the top-level ``.dist-info`` directory, but there is a
  `desire to resolve both these issues <setuptoolsfiles_>`__,
  contingent on this PEP being accepted.

- Both tools also support an older, singular ``license_file`` parameter that
  allows specifying only one license file to add to the distribution, which
  has been deprecated for some time but still sees `some use <pipsetup_>`__.

- Following the publication of an earlier draft of this PEP, Setuptools
  `added support <setuptoolspep639_>`__ for ``License-File`` in distribution
  metadata as described in this specification. This allows other tools
  consuming the resulting metadata to unambiguously locate the license file(s)
  for a given package.


.. _639-license-doc-pypug:

PyPA Packaging Guide and Sample Project
---------------------------------------

Both the `PyPA beginner packaging tutorial <packagingtuttxt_>`__ and its more
comprehensive `packaging guide <packagingguidetxt_>`__ state that it is
important that every package include a license file. They point to the
``LICENSE.txt`` in the official PyPA sample project as an example, which is
`explicitly listed <samplesetupcfg_>`__ under the ``license_files`` key in
its ``setup.cfg``, following existing practice formally specified by this PEP.

Both the `beginner packaging tutorial <packagingtutkey_>`__ and the
`sample project <samplesetuppy_>`__ only use classifiers to declare a
package's license, and do not include or mention the ``License`` field.
The `full packaging guide <licensefield_>`__ does mention this field, but
states that authors should use the license classifiers instead, unless the
project uses a non-standard license (which the guide discourages).


.. _639-license-doc-source-files:

Python source code files
------------------------

**Note:** Documenting licenses in source code is not in the scope of this PEP.

Beside using comments and/or ``SPDX-License-Identifier`` conventions, the
license is `sometimes <pycode_>`__ documented in Python code files using
a "dunder" module-level constant, typically named ``__license__``.

This convention, while perhaps somewhat antiquated, is recognized by the
built-in ``help()`` function and the standard ``pydoc`` module.
The dunder variable will show up in the ``help()`` DATA section for a module.


.. _639-license-doc-other-packaging-tools:

Other Python packaging tools
----------------------------

- `Conda package manifests <conda_>`__ have support for ``license`` and
  ``license_file`` fields, and automatically include license files
  following similar naming patterns as the Wheel and Setuptools projects.

- `Flit <flit_>`__ recommends using classifiers instead of the ``License``
  field (per the current PyPA packaging guide).

- `PBR <pbr_>`__ uses similar data as Setuptools, but always stored in
  ``setup.cfg``.

- `Poetry <poetry_>`__ specifies the use of the ``license`` field in
  ``pyproject.toml`` with SPDX license identifiers.


.. _639-license-doc-other-projects:

Appendix: License Documentation in Other Projects
=================================================

Here is a survey of how things are done elsewhere.


Linux distribution packages
---------------------------

**Note:** in most cases, the texts of the most common licenses are included
globally in a shared documentation directory (e.g. ``/usr/share/doc``).

- Debian documents package licenses with
  `machine readable copyright files <dep5_>`__.
  It defines its own license expression syntax and list of identifiers for
  common licenses, both of which are closely related to those of SPDX.

- `Fedora packages <fedora_>`__ specify how to include
  `License Texts <fedoratext_>`__ and use a
  `License field <fedoralicense_>`__ that must be filled
  with appropriate short license identifier(s) from an extensive list
  of `"Good Licenses" <fedoralist_>`__. Fedora also defines its own
  license expression syntax, similar to that of SPDX.

- `OpenSUSE packages <opensuse_>`__ use SPDX license expressions with
  SPDX license IDs and a
  `list of additional license identifiers <opensuselist_>`__.

- `Gentoo ebuild <pycode_>`__ uses a ``LICENSE`` variable.
  This field is specified in `GLEP-0023 <glep23_>`__ and in the
  `Gentoo development manual <gentoodev_>`__.
  Gentoo also defines a list of allowed licenses and a license expression
  syntax, which is rather different from SPDX.

- The `FreeBSD package Makefile <freebsd_>`__ provides ``LICENSE`` and
  ``LICENSE_FILE`` fields with a list of custom license symbols. For
  non-standard licenses, FreeBSD recommends using ``LICENSE=UNKNOWN`` and
  adding ``LICENSE_NAME`` and ``LICENSE_TEXT`` fields, as well as sophisticated
  ``LICENSE_PERMS`` to qualify the license permissions and ``LICENSE_GROUPS``
  to document a license grouping. The ``LICENSE_COMB`` allows documenting more
  than one license and how they apply together, forming a custom license
  expression syntax. FreeBSD also recommends the use of
  ``SPDX-License-Identifier`` in source code files.

- `Arch Linux PKGBUILD <archinux_>`__ defines its
  `own license identifiers <archlinuxlist_>`__.
  The value ``'unknown'`` can be used if the license is not defined.

- `OpenWRT ipk packages <openwrt_>`__ use the ``PKG_LICENSE`` and
  ``PKG_LICENSE_FILES`` variables and recommend the use of SPDX License
  identifiers.

- `NixOS uses SPDX identifiers <nixos_>`__ and some extra license IDs
  in its license field.

- GNU Guix (based on NixOS) has a single License field, uses its own
  `license symbols list <guix_>`__ and specifies how to use one license or a
  `list of them <guixlicense_>`__.

- `Alpine Linux packages <alpine_>`__ recommend using SPDX identifiers in the
  license field.


Language and application packages
---------------------------------

- In Java, `Maven POM <maven_>`__ defines a ``licenses`` XML tag with a list
  of licenses, each with a name, URL, comments and "distribution" type.
  This is not mandatory, and the content of each field is not specified.

- The `JavaScript NPM package.json <npm_>`__ uses a single license field with
  a SPDX license expression, or the ``UNLICENSED`` ID if none is specified.
  A license file can be referenced as an alternative using
  ``SEE LICENSE IN <filename>`` in the single ``license`` field.

- `Rubygems gemspec <gem_>`__ specifies either a single or list of license
  strings. The relationship between multiple licenses in a
  list is not specified. They recommend using SPDX license identifiers.

- `CPAN Perl modules <perl_>`__ use a single license field, which is either a
  single or a list of strings. The relationship between the licenses in
  a list is not specified. There is a list of custom license identifiers plus
  these generic identifiers: ``open_source``, ``restricted``, ``unrestricted``,
  ``unknown``.

- `Rust Cargo <cargo_>`__ specifies the use of an SPDX license expression
  (v2.1) in the ``license`` field. It also supports an alternative expression
  syntax using slash-separated SPDX license identifiers, and there is also a
  ``license_file`` field. The `crates.io package registry <cratesio_>`__
  requires that either ``license`` or ``license_file`` fields are set when
  uploading a package.

- `PHP composer.json <composer_>`__ uses a ``license`` field with
  an SPDX license ID or ``proprietary``. The ``license`` field is either a
  single string with resembling the SPDX license expression syntax with
  ``and`` and ``or`` keywords; or is a list of strings if there is a
  (disjunctive) choice of licenses.

- `NuGet packages <nuget_>`__ previously used only a simple license URL, but
  now specify using a SPDX license expression and/or the path to a license
  file within the package. The NuGet.org repository states that they only
  accept license expressions that are "approved by the Open Source Initiative
  or the Free Software Foundation."

- Go language modules ``go.mod`` have no provision for any metadata beyond
  dependencies. Licensing information is left for code authors and other
  community package managers to document.

- The `Dart/Flutter spec <flutter_>`__ recommends using a single ``LICENSE``
  file that should contain all the license texts, each separated by a line
  with 80 hyphens.

- The `JavaScript Bower <bower_>`__ ``license`` field is either a single string
  or list of strings using either SPDX license identifiers, or a path/URL
  to a license file.

- The `Cocoapods podspec <cocoapod_>`__ ``license`` field is either a single
  string, or a mapping with ``type``, ``file`` and ``text`` keys.
  This is mandatory unless there is a ``LICENSE``/``LICENCE`` file provided.

- `Haskell Cabal <cabal_>`__ accepts an SPDX license expression since
  version 2.2. The version of the SPDX license list used is a function of
  the Cabal version. The specification also provides a mapping between
  legacy (pre-SPDX) and SPDX license Identifiers. Cabal also specifies a
  ``license-file(s)`` field that lists license files to be installed with
  the package.

- `Erlang/Elixir mix/hex package <mix_>`__ specifies a ``licenses`` field as a
  required list of license strings, and recommends using SPDX license
  identifiers.

- `D Langanguage dub packages <dub_>`__ define their own list of license
  identifiers and license expression syntax, similar to the SPDX standard.

- The `R Package DESCRIPTION <cran_>`__ defines its own sophisticated license
  expression syntax and list of licenses identifiers. R has a unique way of
  supporting specifiers for license versions (such as ``LGPL (>= 2.0, < 3)``)
  in its license expression syntax.


Other ecosystems
----------------

- The ``SPDX-License-Identifier`` `header <spdxid_>`__ is a simple
  convention to document the license inside a file.

- The `Free Software Foundation (FSF) <fsf_>`__ promotes the use of
  SPDX license identifiers for clarity in the `GPL <gnu_>`__ and other
  versioned free software licenses.

- The Free Software Foundation Europe (FSFE) `REUSE project <reuse_>`__
  promotes using ``SPDX-License-Identifier``.

- The `Linux kernel <linux_>`__ uses ``SPDX-License-Identifier``
  and parts of the FSFE REUSE conventions to document its licenses.

- `U-Boot <uboot_>`__ spearheaded using ``SPDX-License-Identifier`` in code
  and now follows the Linux approach.

- The Apache Software Foundation projects use `RDF DOAP <apache_>`__ with
  a single license field pointing to SPDX license identifiers.

- The `Eclipse Foundation <eclipse_>`__ promotes using
  ``SPDX-license-Identifiers``.

- The `ClearlyDefined project <clearlydefined_>`__ promotes using SPDX
  license identifiers and expressions to improve license clarity.

- The `Android Open Source Project <android_>`__ uses ``MODULE_LICENSE_XXX``
  empty tag files, where ``XXX`` is a license code such as ``BSD``, ``APACHE``,
  ``GPL``, etc. It also uses a ``NOTICE`` file that contains license and
  notice texts.


References
==========

.. _alpine: https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package#license
.. _android: https://github.com/aosp-mirror/platform_external_tcpdump/blob/android-platform-12.0.0_r1/MODULE_LICENSE_BSD
.. _apache: https://svn.apache.org/repos/asf/allura/doap_Allura.rdf
.. _archinux: https://wiki.archlinux.org/title/PKGBUILD#license
.. _archlinuxlist: https://archlinux.org/packages/core/any/licenses/files/
.. _badclassifiers: https://github.com/pypa/trove-classifiers/issues/17#issuecomment-385027197
.. _bower: https://github.com/bower/spec/blob/b00c4403e22e3f6177c410ed3391b9259687e461/json.md#license
.. _cabal: https://cabal.readthedocs.io/en/3.6/cabal-package.html?highlight=license#pkg-field-license
.. _cargo: https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata
.. _cc0: https://creativecommons.org/publicdomain/zero/1.0/
.. _cdstats: https://clearlydefined.io/stats
.. _choosealicense: https://choosealicense.com/
.. _choosealicenselist: https://choosealicense.com/licenses/
.. _chooseamitlicense: https://choosealicense.com/licenses/mit/
.. _classifierissue: https://github.com/pypa/trove-classifiers/issues/17
.. _classifiers: https://pypi.org/classifiers
.. _classifiersrepo: https://github.com/pypa/trove-classifiers
.. _clearlydefined: https://clearlydefined.io
.. _cocoapod: https://guides.cocoapods.org/syntax/podspec.html#license
.. _composer: https://getcomposer.org/doc/04-schema.md#license
.. _conda: https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html#about-section
.. _coremetadataspec: https://packaging.python.org/specifications/core-metadata
.. _cran: https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Licensing
.. _cratesio: https://doc.rust-lang.org/cargo/reference/registries.html#publish
.. _dep5: https://dep-team.pages.debian.net/deps/dep5/
.. _dontchoosealicense: https://choosealicense.com/no-permission/
.. _dub: https://dub.pm/package-format-json.html#licenses
.. _eclipse: https://www.eclipse.org/legal/epl-2.0/faq.php
.. _fedora: https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/
.. _fedoralicense: https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/#_valid_license_short_names
.. _fedoralist: https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses
.. _fedoratext: https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/#_license_text
.. _flit: https://flit.readthedocs.io/en/stable/pyproject_toml.html
.. _flutter: https://flutter.dev/docs/development/packages-and-plugins/developing-packages#adding-licenses-to-the-license-file
.. _freebsd: https://docs.freebsd.org/en/books/porters-handbook/makefiles/#licenses
.. _fsf: https://www.fsf.org/blogs/rms/rms-article-for-claritys-sake-please-dont-say-licensed-under-gnu-gpl-2
.. _gem: https://guides.rubygems.org/specification-reference/#license=
.. _gentoo: https://devmanual.gentoo.org/ebuild-writing/variables/index.html#license
.. _gentoodev: https://devmanual.gentoo.org/general-concepts/licenses/index.html
.. _glep23: https://www.gentoo.org/glep/glep-0023.html
.. _globmodule: https://docs.python.org/3/library/glob.html
.. _gnu: https://www.gnu.org/licenses/identify-licenses-clearly.html
.. _guix: https://git.savannah.gnu.org/cgit/guix.git/tree/guix/licenses.scm?h=v1.3.0
.. _guixlicense: https://guix.gnu.org/manual/en/html_node/package-Reference.html#index-license_002c-of-packages
.. _installedspec: https://packaging.python.org/specifications/recording-installed-packages/
.. _interopissue: https://github.com/pypa/interoperability-peps/issues/46
.. _licenseexplib: https://github.com/nexB/license-expression/
.. _licensefield: https://packaging.python.org/guides/distributing-packages-using-setuptools/#license
.. _linux: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/license-rules.rst
.. _maven: https://maven.apache.org/pom.html#Licenses
.. _mitlicense: https://opensource.org/licenses/MIT
.. _mix: https://hex.pm/docs/publish
.. _nixos: https://github.com/NixOS/nixpkgs/blob/21.05/lib/licenses.nix
.. _npm: https://docs.npmjs.com/cli/v8/configuring-npm/package-json#license
.. _nuget: https://docs.microsoft.com/en-us/nuget/reference/nuspec#licenseurl
.. _numpyissue: https://github.com/numpy/numpy/issues/8689
.. _opensuse: https://en.opensuse.org/openSUSE:Packaging_guidelines#Licensing
.. _opensuselist: https://docs.google.com/spreadsheets/d/14AdaJ6cmU0kvQ4ulq9pWpjdZL5tkR03exRSYJmPGdfs/pub
.. _openwrt: https://openwrt.org/docs/guide-developer/packages#buildpackage_variables
.. _osi: https://opensource.org
.. _packagingguidetxt: https://packaging.python.org/guides/distributing-packages-using-setuptools/#license-txt
.. _packagingissue: https://github.com/pypa/packaging-problems/issues/41
.. _packaginglicense: https://github.com/pypa/packaging/blob/21.2/LICENSE
.. _packagingtutkey: https://packaging.python.org/tutorials/packaging-projects/#configuring-metadata
.. _packagingtuttxt: https://packaging.python.org/tutorials/packaging-projects/#creating-a-license
.. _pbr: https://docs.openstack.org/pbr/latest/user/features.html
.. _pep621spec: https://packaging.python.org/specifications/declaring-project-metadata/
.. _pepissue: https://github.com/pombredanne/spdx-pypi-pep/issues/1
.. _perl: https://metacpan.org/pod/CPAN::Meta::Spec#license
.. _pipsetup: https://github.com/pypa/pip/blob/21.3.1/setup.cfg#L114
.. _poetry: https://python-poetry.org/docs/pyproject/#license
.. _pycode: https://github.com/search?l=Python&q=%22__license__%22&type=Code
.. _pypi: https://pypi.org/
.. _pypugdistributionpackage: https://packaging.python.org/en/latest/glossary/#term-Distribution-Package
.. _pypugglossary: https://packaging.python.org/glossary/
.. _pypugproject: https://packaging.python.org/en/latest/glossary/#term-Project
.. _pytorch: https://pypi.org/project/torch/
.. _reuse: https://reuse.software/
.. _reusediscussion: https://github.com/pombredanne/spdx-pypi-pep/issues/7
.. _samplesetupcfg: https://github.com/pypa/sampleproject/blob/3a836905fbd687af334db16b16c37cf51dcbc99c/setup.cfg
.. _samplesetuppy: https://github.com/pypa/sampleproject/blob/3a836905fbd687af334db16b16c37cf51dcbc99c/setup.py#L98
.. _scancodetk: https://github.com/nexB/scancode-toolkit
.. _scipyissue: https://github.com/scipy/scipy/issues/7093
.. _sdistspec: https://packaging.python.org/specifications/source-distribution-format/
.. _setuptools5911: https://github.com/pypa/setuptools/blob/v59.1.1/setup.cfg
.. _setuptoolsfiles: https://github.com/pypa/setuptools/issues/2739
.. _setuptoolspep639: https://github.com/pypa/setuptools/pull/2645
.. _setuptoolssdist: https://github.com/pypa/setuptools/pull/1767
.. _spdx: https://spdx.dev/
.. _spdxid: https://spdx.dev/ids/
.. _spdxlist: https://spdx.org/licenses/
.. _spdxpression: https://spdx.github.io/spdx-spec/SPDX-license-expressions/
.. _spdxpy: https://github.com/spdx/tools-python/
.. _spdxtutorial: https://github.com/david-a-wheeler/spdx-tutorial
.. _spdxversion: https://github.com/pombredanne/spdx-pypi-pep/issues/6
.. _uboot: https://www.denx.de/wiki/U-Boot/Licensing
.. _unlicense: https://unlicense.org/
.. _wheelfiles: https://github.com/pypa/wheel/issues/138
.. _wheelproject: https://wheel.readthedocs.io/en/stable/
.. _wheels: https://github.com/pypa/wheel/blob/0.37.0/docs/user_guide.rst#including-license-files-in-the-generated-wheel-file
.. _wheelspec: https://packaging.python.org/specifications/binary-distribution-format/


Acknowledgments
===============

- Nick Coghlan
- Kevin P. Fleming
- Pradyun Gedam
- Oleg Grenrus
- Dustin Ingram
- Chris Jerdonek
- Cyril Roelandt
- Luis Villa


Copyright
=========

This document is placed in the public domain or under the
`CC0-1.0-Universal license <cc0_>`__, whichever is more permissive.