Add License-Expression field

The License-Expression optional Core Metadata field is specified to contain a text string that is a valid SPDX license expression, as defined by this PEP.

Publishing tools SHOULD issue an informational warning if this field is missing, and MAY raise an error. Build tools MAY issue a similar warning, but MUST NOT raise an error.

A license expression is an SPDX expression as defined above.

When processing the License-Expression field, build and publishing tools:

• SHOULD halt execution and raise an error if:
  • The field does not contain a valid license expression
  • One or more license identifiers are not valid (as defined above)
• 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.
• 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-uploaded distribution archives that include a License-Expression field, the Python Package Index (PyPI) MUST validate that they contain a valid, case-normalized license expression with valid identifiers (as defined above) 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.

Add License-File field

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

As specified by this PEP, its value is also that file’s path relative to the root license directory in both installed projects and the standardized Distribution Package types.

If a License-File is listed in a Source Distribution or Built Distribution’s Core Metadata:

• That file MUST be included in the distribution archive at the specified path relative to the root license directory.
• That file MUST be installed with the project 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.
• 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 archives that include one or more License-File fields in their Core Metadata and declare a Metadata-Version of 2.4 or higher, PyPI SHOULD validate that all specified files are present in that distribution archives, and MUST reject uploads that do not validate.

Deprecate License field

The legacy unstructured-text License Core Metadata field is deprecated and replaced by the new License-Expression field. Build and publishing tools MUST raise an error if both these fields are present and their values are not identical, including capitalization and excluding leading and trailing whitespace.

If only the License field is present, such tools SHOULD issue a warning informing users it is deprecated and recommending License-Expression instead.

For all newly-uploaded distribution archives that include a License-Expression field, the Python Package Index (PyPI) MUST reject any that specify a License field and the text of which is not identical to that of License-Expression, as defined here.

The License field may be removed from a new version of the specification in a future PEP.

Deprecate license classifiers

Using license classifiers in the Classifier Core Metadata field (described in the Core Metadata specification) is deprecated and replaced by the more precise License-Expression field.

If the License-Expression field is present, build tools SHOULD and 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) MUST reject any that also specify any license classifiers.

New license classifiers MUST NOT be added to PyPI; users needing them SHOULD use the License-Expression field instead. License classifiers may be removed from a new version of the specification in a future PEP.

Add string value to license key

license key in the [project] table is defined to contain a top-level string value. It is a valid SPDX license expression as defined in this PEP. Its value maps to the License-Expression field in the core metadata.

Build tools SHOULD validate the expression as described in the Add License-Expression field section, outputting an error or warning as specified. When generating the Core Metadata, tools MUST perform case normalization.

If a top-level string value for the license key is present and valid, for purposes of backward compatibility tools MAY back-fill the License Core Metadata field with the normalized value of the license key.

Examples:

[project]
license = "MIT"

[project]
license = "MIT AND (Apache-2.0 OR BSD-2-clause)"

[project]
license = "MIT OR GPL-2.0-or-later OR (FSFUL AND BSD-2-Clause)"

[project]
license = "LicenseRef-Proprietary"

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 in the Python standard library.

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.

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

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.

Examples of valid license files declaration:

[project]
license-files = { globs = ["LICEN[CS]E*", "AUTHORS*"] }

[project]
license-files.paths = ["licenses/LICENSE.MIT", "licenses/LICENSE.CC0"]

[project]
license-files = { paths = [] }

[project]
license-files.globs = []

Examples of invalid license files declaration:

[project]
license-files.globs = ["LICEN[CS]E*", "AUTHORS*"]
license-files.paths = ["LICENSE.MIT"]

Reason: license-files.paths and license-files.globs are mutually exclusive.

[project]
license-files = { paths = ["..\LICENSE.MIT"] }

Reason: .. must not be used. \ is an invalid path delimiter, / must be used.

[project]
license-files = { globs = ["LICEN{CSE*"] }

Reason: “LICEN{CSE*” is not a valid glob.

Deprecate license key table subkeys

Table values for the license key in the [project] table, including the text and file table subkeys, are now deprecated. If the new license-files key is present, build tools MUST raise an error if the license key is defined and has a value other than a single top-level string.

If the new license-files key is not present and the text subkey is present in a license table, tools SHOULD issue a warning informing users it is deprecated and recommending a license expression as a top-level string key instead.

Likewise, if the new license-files key is not present and 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.

If the specified license file is present in the source tree, build tools SHOULD use it to fill the License-File field in the core metadata, and MUST include the specified file as if it were specified in a license-file.paths field. If the file does not exist at the specified path, tools MUST raise an informative error as previously specified. However, tools MUST also still assume the specified default value for the license-files key and also include, in addition to a license file specified under the license.file subkey, any license files that match the specified list of patterns.

Table values for the license key MAY be removed from a new version of the specification in a future PEP.