Merge pull request #1595 from ewdurbin/pep_639

PEP 639: Add documentation for Metadata 2.4, License-Expression and License-Field

Author: ewdurbin

source/specifications/core-metadata.rst

@@ -48,7 +48,7 @@ Metadata-Version
 .. versionadded:: 1.0
 
 Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
-"2.2", and "2.3".
+"2.2", "2.3", and "2.4".
 
 Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
 greater than the highest version they support, and MUST fail if
@@ -63,7 +63,7 @@ all of the needed fields.
 
 Example::
 
-    Metadata-Version: 2.3
+    Metadata-Version: 2.4
 
 
 .. _core-metadata-name:
@@ -460,6 +460,14 @@ License
 =======
 
 .. versionadded:: 1.0
+.. deprecated:: 2.4
+   in favour of ``License-Expression``.
+
+.. warning::
+    As of Metadata 2.4, ``License`` and ``License-Expression`` are mutually
+    exclusive. If both are specified, tools which parse metadata will disregard
+    ``License`` and PyPI will reject uploads.
+    See `PEP 639 <https://peps.python.org/pep-0639/#deprecate-license-field>`__.
 
 Text indicating the license covering the distribution where the license
 is not a selection from the "License" Trove classifiers. See
@@ -477,6 +485,50 @@ Examples::
     License: GPL version 3, excluding DRM provisions
 
 
+.. _license-expression-optional:
+.. _core-metadata-license-expression:
+
+License-Expression
+==================
+
+.. versionadded:: 2.4
+
+Text string that is a valid SPDX
+`license expression <https://peps.python.org/pep-0639/#term-license-expression>`__
+as `defined in PEP 639 <https://peps.python.org/pep-0639/#spdx>`__.
+
+Examples::
+
+    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-Special-License OR CC0-1.0 OR Unlicense
+    License-Expression: LicenseRef-Proprietary
+
+
+.. _license-file-optional:
+.. _core-metadata-license-file:
+
+License-File (multiple use)
+===========================
+
+.. versionadded:: 2.4
+
+Each entry is a 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. For details see :pep:`639`.
+
+Examples::
+
+    License-File: LICENSE
+    License-File: AUTHORS
+    License-File: LICENSE.txt
+    License-File: licenses/LICENSE.MIT
+    License-File: licenses/LICENSE.CC0
+
+
 .. _metadata-classifier:
 .. _core-metadata-classifier:
 
@@ -490,6 +542,11 @@ for the distribution.  Classifiers are described in :pep:`301`,
 and the Python Package Index publishes a dynamic list of
 `currently defined classifiers <https://pypi.org/classifiers/>`__.
 
+.. note::
+    The use of ``License ::`` classifiers  is deprecated as of Metadata 2.4,
+    use ``License-Expression`` instead. See
+    `PEP 639 <https://peps.python.org/pep-0639/#deprecate-license-classifiers>`_.
+
 This field may be followed by an environment marker after a semicolon.
 
 Examples::
@@ -864,6 +921,11 @@ History
 
   - Restricted extra names to be normalized.
 
+- August 2024: Core metadata 2.4 was approved through :pep:`639`.
+
+  - Added the ``License-Expression`` field.
+  - Added the ``License-File`` field.
+
 ----
 
 .. [1] reStructuredText markup:

source/specifications/platform-compatibility-tags.rst

@@ -343,5 +343,5 @@ History
 
 
 .. _musl: https://musl.libc.org
-.. _ldd: https://www.unix.com/man-page/posix/1/ldd/
+.. _ldd: https://www.man7.org/linux/man-pages/man1/ldd.1.html
 .. _elf: https://refspecs.linuxfoundation.org/elf/elf.pdf