From faf4c7d882ef2be310d5dc46d54ca666aa18821c Mon Sep 17 00:00:00 2001 From: Karolina Surma Date: Mon, 17 Feb 2025 11:52:21 +0100 Subject: [PATCH] Document the legacy way of declaring pyproject.toml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) --- .../licensing-examples-and-user-scenarios.rst | 4 ++ source/guides/writing-pyproject-toml.rst | 41 ++++++++++- source/tutorials/packaging-projects.rst | 70 +++++++++++++------ 3 files changed, 92 insertions(+), 23 deletions(-) diff --git a/source/guides/licensing-examples-and-user-scenarios.rst b/source/guides/licensing-examples-and-user-scenarios.rst index 5b05d97ea..ae0066581 100644 --- a/source/guides/licensing-examples-and-user-scenarios.rst +++ b/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 ` +and :ref:`flit ` don't support :pep:`639` yet. Licensing Examples diff --git a/source/guides/writing-pyproject-toml.rst b/source/guides/writing-pyproject-toml.rst index f65ab28da..cfde063aa 100644 --- a/source/guides/writing-pyproject-toml.rst +++ b/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 ` +and :ref:`flit ` don't support :pep:`639` yet. + +:pep:`639` license declaration +'''''''''''''''''''''''''''''' + This is a valid :term:`SPDX license expression ` consisting of one or more :term:`license identifiers `. 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 ` +and :ref:`flit ` 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 = [ diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst index 9357fdfa2..8992fffb0 100644 --- a/source/tutorials/packaging-projects.rst +++ b/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="author@example.com" }, - ] - 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="author@example.com" }, + ] + 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="author@example.com" }, + ] + 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 ` 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.