Thanks to visit codestin.com
Credit goes to github.com

Skip to content

PEP 639: Incorporate the latest discussion feedback #3866

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 25, 2024
Merged

PEP 639: Incorporate the latest discussion feedback #3866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b593a4d
Remove the requirement of license-files defaults
befeleme Jul 4, 2024
926952c
Cover all rejected subkeysideas in one paragraph
befeleme Jul 4, 2024
5469b1a
Change the deprecation policy around classifiers
befeleme Jul 4, 2024
3e7d44f
Flatten the value of the license-files key, only globs are specified
befeleme Jul 17, 2024
8382675
Update the Rejected ideas to match the current license-files proposal
befeleme Jul 17, 2024
dddf688
Update peps/pep-0639.rst
befeleme Jul 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 29 additions & 79 deletions peps/pep-0639.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -451,22 +451,18 @@ in the ``Classifier`` :term:`Core Metadata field`
(`described in the Core Metadata specification <coremetadataclassifiers_>`__)
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
If the ``License-Expression`` field is present, build tools MAY 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
Otherwise, if this field contains a license classifier,
tools MAY 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.
License classifiers may be removed from a new version of the specification
Expand Down Expand Up @@ -524,104 +520,62 @@ 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.

Its value is an array of strings which MUST contain valid glob patterns,
as specified below.
The glob patterns MAY contain special glob characters: ``*``, ``?``, ``**``
and character ranges: ``[]``, and tools MUST support them.
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.
Literal paths (e.g. ``LICENSE``) are treated as valid globs which means they
can also be defined.

- MUST list each file path under a ``License-File`` field in the Core Metadata.
To achieve better portability, the filenames to match should only contain
the alphanumeric characters, underscores (``_``), hyphens (``-``)
and dots (``.``).

- 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:
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
- MUST include all files matched by a 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
- MUST raise an error 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
If the ``license-files`` key is present and
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.

Examples of valid license files declaration:

.. code-block:: toml

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

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

[project]
license-files = { paths = [] }
license-files = ["LICENSE.txt", "licenses/*"]

[project]
license-files.globs = []
license-files = []

Examples of invalid license files declaration:

.. code-block:: toml

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

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

.. code-block:: toml

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

Reason: ``..`` must not be used.
``\`` is an invalid path delimiter, ``/`` must be used.
Expand All @@ -630,7 +584,7 @@ Reason: ``..`` must not be used.
.. code-block:: toml

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

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

Expand Down Expand Up @@ -659,14 +613,9 @@ 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.
as if it were specified in a ``license-file`` 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
:ref:`specified default value <639-default-patterns>`
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.
Expand Down Expand Up @@ -751,9 +700,9 @@ and license classifiers retain backwards compatibility. A removal is
left to a future PEP and a new version of the Core Metadata specification.

Specification of the new ``License-File`` Core Metadata field and adding the
files in the distribution codifies the existing practices of many packaging
tools. It is designed to be largely backwards-compatible with their existing
use of that field. The new ``license-files`` key in the ``[project]`` table of
files in the distribution is designed to be largely backwards-compatible with
the existing use of that field in many packaging tools.
The new ``license-files`` key in the ``[project]`` table of
``pyproject.toml`` will only have an effect once users and tools adopt it.

This PEP specifies that license files should be placed in a dedicated
Expand Down Expand Up @@ -807,7 +756,8 @@ If an invalid ``License-Expression`` is used, the users will not be able
to publish their package to PyPI and an error message will help them
understand they need to use SPDX identifiers.
It will be possible to generate a distribution with incorrect license metadata,
but not to publish one on PyPI or any other index server that enforces ``License-Expression`` validity.
but not to publish one on PyPI or any other index server that enforces
``License-Expression`` validity.
For authors using the now-deprecated ``License`` field or license classifiers,
packaging tools may warn them and inform them of the replacement,
``License-Expression``.
Expand Down
24 changes: 13 additions & 11 deletions peps/pep-0639/appendix-examples.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,29 +127,30 @@ Putting it all together, our ``setup.cfg`` would be:
setuptools/_vendor/packaging/LICENSE.APACHE
setuptools/_vendor/packaging/LICENSE.BSD

In the ``[project]`` table of ``pyproject.toml``, with license files
specified explicitly via the ``paths`` subkey, this would look like:
In the ``[project]`` table of ``pyproject.toml``, license files
can be specified via glob patterns:

.. code-block:: toml

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

Or alternatively, matched via glob patterns, this could be:
Or alternatively, they can be specified explicitly (paths will be interpreted
as glob patterns):

.. code-block:: toml

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

With either approach, the output Core Metadata in the distribution
Expand Down Expand Up @@ -211,6 +212,7 @@ Some additional examples of valid ``License-Expression`` values:
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
License-Expression: LicenseRef-Custom-License


.. _packaginglicense: https://github.com/pypa/packaging/blob/21.2/LICENSE
Expand Down
Loading