Merge pull request pypa#1815 from befeleme/document-legacy

Document the legacy way of declaring pyproject.toml

Author: webknjaz

source/guides/licensing-examples-and-user-scenarios.rst

@@ -10,6 +10,10 @@ Licensing examples and user scenarios
 license files and other legally required information.
 This document aims to provide clear guidance how to migrate from the legacy
 to the standardized way of declaring licenses.
+Make sure your preferred build backend supports :pep:`639` before
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
 
 
 Licensing Examples

source/guides/writing-pyproject-toml.rst

@@ -325,6 +325,15 @@ You can also specify the format explicitly, like this:
 ``license``
 -----------
 
+:pep:`639` (accepted in August 2024) has changed the way the ``license`` field
+is declared. Make sure your preferred build backend supports :pep:`639` before
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
+
+:pep:`639` license declaration
+''''''''''''''''''''''''''''''
+
 This is a valid :term:`SPDX license expression <License Expression>` consisting
 of one or more :term:`license identifiers <License Identifier>`.
 The full license list is available at the
@@ -352,10 +361,40 @@ The custom identifiers must follow the SPDX specification,
     [project]
     license = "LicenseRef-My-Custom-License"
 
+Legacy license declaration
+''''''''''''''''''''''''''
+
+This can take two forms. You can put your license in a file, typically
+:file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:
+
+.. code-block:: toml
+
+    [project]
+    license = {file = "LICENSE"}
+
+or you can write the name of the license:
+
+.. code-block:: toml
+
+    [project]
+    license = {text = "MIT License"}
+
+If you are using a standard, well-known license, it is not necessary to use this
+field. Instead, you should use one of the :ref:`classifiers` starting with ``License
+::``. (As a general rule, it is a good idea to use a standard, well-known
+license, both to avoid confusion and because some organizations avoid software
+whose license is unapproved.)
+
 
 ``license-files``
 -----------------
 
+:pep:`639` (accepted in August 2024) has introduced the ``license-files`` field.
+Make sure your preferred build backend supports :pep:`639` before declaring the
+field.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
+
 This is a list of license files and files containing other legal
 information you want to distribute with your package.
 
@@ -529,7 +568,7 @@ A full example
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"
-   license = "MIT"
+   license = "MIT"  # or license = {file = "LICENSE.txt"} for legacy declaration
    license-files = ["LICEN[CS]E.*"]
    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
    classifiers = [

source/tutorials/packaging-projects.rst

@@ -200,27 +200,52 @@ to include your username; this ensures that you have a unique
 package name that doesn't conflict with packages uploaded by other people
 following this tutorial.
 
-.. code-block:: toml
-
-    [project]
-    name = "example_package_YOUR_USERNAME_HERE"
-    version = "0.0.1"
-    authors = [
-      { name="Example Author", email="[email protected]" },
-    ]
-    description = "A small example package"
-    readme = "README.md"
-    requires-python = ">=3.8"
-    classifiers = [
-        "Programming Language :: Python :: 3",
-        "Operating System :: OS Independent",
-    ]
-    license = "MIT"
-    license-files = ["LICEN[CS]E*"]
-
-    [project.urls]
-    Homepage = "https://github.com/pypa/sampleproject"
-    Issues = "https://github.com/pypa/sampleproject/issues"
+.. tab:: hatchling/pdm
+
+  .. code-block:: toml
+
+      [project]
+      name = "example_package_YOUR_USERNAME_HERE"
+      version = "0.0.1"
+      authors = [
+        { name="Example Author", email="[email protected]" },
+      ]
+      description = "A small example package"
+      readme = "README.md"
+      requires-python = ">=3.8"
+      classifiers = [
+          "Programming Language :: Python :: 3",
+          "Operating System :: OS Independent",
+      ]
+      license = "MIT"
+      license-files = ["LICEN[CS]E*"]
+
+      [project.urls]
+      Homepage = "https://github.com/pypa/sampleproject"
+      Issues = "https://github.com/pypa/sampleproject/issues"
+
+.. tab:: setuptools/flit
+
+  .. code-block:: toml
+
+      [project]
+      name = "example_package_YOUR_USERNAME_HERE"
+      version = "0.0.1"
+      authors = [
+        { name="Example Author", email="[email protected]" },
+      ]
+      description = "A small example package"
+      readme = "README.md"
+      requires-python = ">=3.8"
+      classifiers = [
+          "Programming Language :: Python :: 3",
+          "Operating System :: OS Independent",
+          "License :: OSI Approved :: MIT License",
+      ]
+
+      [project.urls]
+      Homepage = "https://github.com/pypa/sampleproject"
+      Issues = "https://github.com/pypa/sampleproject/issues"
 
 - ``name`` is the *distribution name* of your package. This can be any name as
   long as it only contains letters, numbers, ``.``, ``_`` , and ``-``. It also
@@ -249,9 +274,10 @@ following this tutorial.
   your package will work on. For a complete list of classifiers, see
   https://pypi.org/classifiers/.
 - ``license`` is the :term:`SPDX license expression <License Expression>` of
-  your package.
+  your package. Not supported by all the build backends yet.
 - ``license-files`` is the list of glob paths to the license files,
   relative to the directory where :file:`pyproject.toml` is located.
+  Not supported by all the build backends yet.
 - ``urls`` lets you list any number of extra links to show on PyPI.
   Generally this could be to the source, documentation, issue trackers, etc.