iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 639: Post-split edits (language simplification, deeper edits of sections) (#3743) 

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
This commit is contained in:
Karolina Surma 2024-05-10 06:04:17 +02:00 committed by GitHub
parent 2257e94edf
commit 0efd257074
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 744 additions and 959 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1019
peps/pep-0639.rst
View File

File diff suppressed because it is too large Load Diff

8
peps/pep-0639/appendix-examples.rst
View File

@ -49,7 +49,7 @@ Or, in the ``[project]`` table of ``pyproject.toml``:
[project]
license = "MIT"
The output core metadata for the distribution packages would then be:
The output Core Metadata for the distribution packages would then be:
.. code-block:: email
@ -60,7 +60,7 @@ The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE``
in the sdist and ``/setuptools-${VERSION}.dist-info/licenses/LICENSE``
in the wheel, and unpacked from there into the site directory (e.g.
``site-packages``) on installation; ``/`` is the root of the respective archive
and ``${VERSION}`` the version of the Setuptools release in the core metadata.
and ``${VERSION}`` the version of the Setuptools release in the Core Metadata.
.. _639-example-advanced:
@ -152,7 +152,7 @@ Or alternatively, matched via glob patterns, this could be:
"setuptools/_vendor/LICENSE*",
]
With either approach, the output core metadata in the distribution
With either approach, the output Core Metadata in the distribution
would be:
.. code-block:: email
@ -164,7 +164,7 @@ would be:
License-File: setuptools/_vendor/packaging/LICENSE.BSD
In the resulting sdist, with ``/`` as the root of the archive and ``${VERSION}``
the version of the Setuptools release specified in the core metadata,
the version of the Setuptools release specified in the Core Metadata,
the license files would be located at the paths:
.. code-block:: shell

29
peps/pep-0639/appendix-license-survey.rst
View File

@ -10,6 +10,23 @@ There are multiple ways used or recommended to document licenses.
This document contains the results of a comprehensive survey of license
documentation in Python and other languages.
The key takeaways from the survey, which have guided the recommendations of
PEP 639, are as follows:
- Most package formats use a single ``License`` field.
- Many modern package systems use some form of :term:`license expression`
to optionally combine more than one :term:`license identifier` together.
SPDX and SPDX-like syntaxes are the most popular in use.
- SPDX license identifiers are becoming the de facto way to reference common
licenses everywhere, whether or not a full license expression syntax is used.
- Several package formats support documenting both a license expression and the
paths of the corresponding files that contain the license text. Most Free and
Open Source Software licenses require package authors to include their full
text in a :term:`Distribution Package`.
.. _639-license-doc-python:
@ -18,14 +35,14 @@ License Documentation in Python
.. _639-license-doc-core-metadata:
Core metadata
Core Metadata
'''''''''''''
There are two overlapping core metadata fields to document a license: the
There are two overlapping Core Metadata fields to document a license: the
license ``Classifier`` `strings <classifiers_>`__ prefixed with ``License ::``
and the ``License`` `field <licensefield_>`__ as free text.
The core metadata ``License`` field documentation is currently:
The Core Metadata ``License`` field documentation is currently:
.. code-block:: rst
@ -148,14 +165,14 @@ globally in a shared documentation directory (e.g. ``/usr/share/doc``).
`License Texts <fedoratext_>`__ and use a
`License field <fedoralicense_>`__ that must be filled
with appropriate short license identifier(s) from an extensive list
of `"Good Licenses" <fedoralist_>`__. Fedora also defines its own
license expression syntax, similar to that of SPDX.
of `"Good Licenses" <fedoralist_>`__. Fedora uses SPDX
license expression syntax.
- `OpenSUSE packages <opensuse_>`__ use SPDX license expressions with
SPDX license IDs and a
`list of additional license identifiers <opensuselist_>`__.
- `Gentoo ebuild <pycode_>`__ uses a ``LICENSE`` variable.
- `Gentoo ebuild <gentoo_>`__ uses a ``LICENSE`` variable.
This field is specified in `GLEP-0023 <glep23_>`__ and in the
`Gentoo development manual <gentoodev_>`__.
Gentoo also defines a list of allowed licenses and a license expression

608
peps/pep-0639/appendix-rejected-ideas.rst
View File

@ -12,11 +12,11 @@ This document contains a list of the alternative ideas to the ones proposed
in PEP 639 with detailed explanations why they were rejected.
Core metadata fields
Core Metadata fields
--------------------
Potential alternatives to the structure, content and deprecation of the
core metadata fields specified in :pep:`639`.
Core Metadata fields specified in :pep:`639`.
Re-use the ``License`` field
@ -25,68 +25,50 @@ Re-use the ``License`` field
Following `initial discussion <reusediscussion_>`__, earlier versions of
PEP 639 proposed re-using the existing ``License`` field, which tools would
attempt to parse as a SPDX license expression with a fallback to free text.
Initially, this would merely cause a warning (or even pass silently),
but would eventually be treated as an error by modern tooling.
Initially, this would cause a warning and eventually it would be treated as an
error.
This offered the potential benefit of greater backwards-compatibility,
easing the community into using SPDX license expressions while taking advantage
of packages that already have them (either intentionally or coincidentally),
This would be more backwards-compatibile, allowed a smooth adoption
of SPDX license expressions in the community,
and avoided adding yet another license-related field.
However, following substantial discussion, consensus was reached that a
dedicated ``License-Expression`` field was the preferred overall approach.
The presence of this field is an unambiguous signal that a package
intends it to be interpreted as a valid SPDX identifier, without the need
for complex and potentially erroneous heuristics, and allows tools to
easily and unambiguously detect invalid content.
This avoids both false positive (``License`` values that a package author
didn't explicitly intend as an explicit SPDX identifier, but that happen
to validate as one), and false negatives (expressions the author intended
to be valid SPDX, but due to a typo or mistake are not), which are otherwise
not clearly distinguishable from true positives and negatives, an ambiguity
at odds with the goals of PEP 639.
Eventually, consensus was reached that a
dedicated ``License-Expression`` field was a better approach.
The presence of this field unambiguously signals support for the SPDX
identifiers, without the need for complex heuristics, and allows tools to
easily detect invalid content.
Furthermore, it allows both the existing ``License`` field and
the license classifiers to be more easily deprecated,
with tools able to cleanly distinguish between packages intending to
affirmatively conform to the updated specification in PEP 639 or not,
and adapt their behavior (warnings, errors, etc) accordingly.
Otherwise, tools would either have to allow duplicative and potentially
conflicting ``License`` fields and classifiers, or warn/error on the
substantial number of existing packages that have SPDX identifiers as the
value for the ``License`` field, intentionally or otherwise (e.g. ``MIT``).
the license classifiers to be easily deprecated,
with tools able to distinguish between packages conforming to PEP 639 or not,
and adapt their behavior accordingly.
Finally, it avoids changing the behavior of an existing metadata field,
and avoids tools having to guess the ``Metadata-Version`` and field behavior
based on its value rather than merely its presence.
While this would mean the subset of existing distributions containing
``License`` fields valid as SPDX license expressions wouldn't automatically be
recognized as such, this only requires appending a few characters to the key
name in the project's source metadata, and PEP 639 provides extensive
Distributions which already contain valid SPDX license expressions in the
``License`` fields will not automatically be recognized as such.
The migration is simple though, and PEP 639 provides
guidance on how this can be done automatically by tooling.
Given all this, it was decided to proceed with defining a new,
purpose-created field, ``License-Expression``.
Re-Use the ``License`` field with a value prefix
''''''''''''''''''''''''''''''''''''''''''''''''
As an alternative to the previous, prefixing SPDX license expressions with,
e.g. ``spdx:`` was suggested to reduce the ambiguity inherent in re-using
e.g. ``spdx:`` was suggested to reduce the ambiguity of re-using
the ``License`` field. However, this effectively amounted to creating
a field within a field, and doesn't address all the downsides of
a field within a field, and doesn't address the downsides of
keeping the ``License`` field. Namely, it still changes the behavior of an
existing metadata field, requires tools to parse its value
to determine how to handle its content, and makes the specification and
deprecation process more complex and less clean.
Yet, it still shares a same main potential downside as just creating a new
field: projects currently using valid SPDX identifiers in the ``License``
field, intentionally or not, won't be automatically recognized, and requires
about the same amount of effort to fix, namely changing a line in the
Projects currently using valid SPDX identifiers in the ``License``
field won't be automatically recognized, and require
about the same amount of effort to fix as in the case of introducing a new
field, namely changing a line in the
project's source metadata. Therefore, it was rejected in favor of a new field.
@ -96,76 +78,36 @@ Don't make ``License-Expression`` mutually exclusive
For backwards compatibility, the ``License`` field and/or the license
classifiers could still be allowed together with the new
``License-Expression`` field, presumably with a warning. However, this
could easily lead to inconsistent, and at the very least duplicative
could easily lead to inconsistent
license metadata in no less than *three* different fields, which is
squarely contrary to the goals of PEP 639 of making the licensing story
simpler and unambiguous. Therefore, and in concert with clear community
consensus otherwise, this idea was soundly rejected.
contrary to the goal of PEP 639 of making the licensing story
unambiguous. Therefore, with the community
consensus this idea was rejected.
Don't deprecate existing ``License`` field and classifiers
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Several community members were initially concerned that deprecating the
Several community members were concerned that deprecating the
existing ``License`` field and classifiers would result in
excessive churn for existing package authors and raise the barrier to
entry for new ones, particularly everyday Python developers seeking to
package and publish their personal projects without necessarily caring
too much about the legal technicalities or being a "license lawyer".
Indeed, every deprecation comes with some non-zero short-term cost,
and should be carefully considered relative to the overall long-term
net benefit. And at the minimum, this change shouldn't make it more
difficult for the average Python developer to share their work under
much churn for package authors and raise the barrier to
entry for new ones, particularly developers seeking to
package their personal projects without caring
too much about the legal technicalities.
Indeed, every deprecation should be carefully considered relative to the
long-term
net benefit. At the minimum, this change shouldn't make it more
difficult for a Python developer to share their work under
a license of their choice, and ideally improve the situation.
Following many rounds of proposals, discussion and refinement,
the general consensus was clearly in favor of deprecating the legacy
means of specifying a license, in favor of "one obvious way to do it",
to improve the currently complex and fragmented story around license
documentation. Not doing so would leave three different un-deprecated ways of
specifying a license for a package, two of them ambiguous, less than
clear/obvious how to use, inconsistently documented and out of date.
This is more complex for all tools in the ecosystem to support
indefinitely (rather than simply installers supporting older packages
implementing previous frozen metadata versions), resulting in a non-trivial
and unbounded maintenance cost.
Furthermore, it leads to a more complex and confusing landscape for users with
three similar but distinct options to choose from, particularly with older
documentation, answers and articles floating around suggesting different ones.
Of the three, ``License-Expression`` is the simplest and clearest to use
correctly; users just paste in their desired license identifier, or select it
via a tool, and they're done; no need to learn about Trove classifiers and
dig through the list to figure out which one(s) apply (and be confused
by many ambiguous options), or figure out on their own what should go
in the ``license`` key (anything from nothing, to the license text,
to a free-form description, to the same SPDX identifier they would be
entering in the ``license`` key anyway, assuming they can
easily find documentation at all about it). In fact, this can be
made even easier thanks to the new field. For example, GitHub's popular
`ChooseALicense.com <choosealicense_>`__ links to how to add SPDX license
identifiers to the project source metadata of various languages that support
them right in the sidebar of every license page; the SPDX support in this
PEP enables adding Python to that list.
For current package maintainers who have specified a ``License`` or license
classifiers, PEP 639 only recommends warnings and prohibits errors for
all but publishing tools, which are allowed to error if their intended
distribution platform(s) so requires. Once maintainers are ready to
upgrade, for those already using SPDX license expressions (accidentally or not)
this only requires appending a few characters to the key name in the
project's source metadata, and for those with license classifiers that
map to a single unambiguous license, or another defined case (public domain,
proprietary), they merely need to drop the classifier and paste in the
corresponding license identifier. PEP 639 provides extensive guidance and
examples, as will other resources, as well as explicit instructions for
automated tooling to take care of this with no human changes needed.
More complex cases where license metadata is currently specified may
need a bit of human intervention, but in most cases tools will be able
to provide a list of options following the mappings in PEP 639, and
these are typically the projects most likely to be constrained by the
limitations of the existing license metadata, and thus most benefited
by the new fields in PEP 639.
Following many rounds of discussion,
the general consensus was in favor of deprecating the legacy
means of specifying a license and in favor of "one obvious way to do it".
Not doing so would leave three different un-deprecated ways of
specifying a license for a package, two of them ambiguous,
inconsistently documented and out of date.
This is more complex for tools to support
indefinitely, resulting in a non-trivial maintenance cost.
Finally, for unmaintained packages, those using tools supporting older
metadata versions, or those who choose not to provide license metadata,
@ -175,77 +117,63 @@ no changes are required regardless of the deprecation.
Don't mandate validating new fields on PyPI
'''''''''''''''''''''''''''''''''''''''''''
Previously, while PEP 639 did include normative guidelines for packaging
publishing tools (such as Twine), it did not provide specific guidance
Previously, PEP 639 did not provide specific guidance
for PyPI (or other package indices) as to whether and how they
should validate the ``License-Expression`` or ``License-File`` fields,
nor how they should handle using them in combination with the deprecated
``License`` field or license classifiers. This simplifies the specification
and either defers implementation on PyPI to a later PEP, or gives
discretion to PyPI to enforce the stated invariants, to minimize
and defers implementation on PyPI to a later PEP to minimize
disruption to package authors.
However, this had been left unstated from before the ``License-Expression``
field was separate from the existing ``License``, which would make
validation much more challenging and backwards-incompatible, breaking
existing packages. With that change, there was a clear consensus that
This was in place for an earlier draft of PEP 639 which didn't separate
``License-Expression`` from the ``License`` field. The validation would have
been difficult and backwards-incompatible, breaking existing packages.
With the current proposal, there was a clear consensus that
the new field should be validated from the start, guaranteeing that all
distributions uploaded to PyPI that declare core metadata version 2.4
distributions uploaded to PyPI that declare Core Metadata version 2.4
or higher and have the ``License-Expression`` field will have a valid
expression, such that PyPI and consumers of its packages and metadata
can rely upon to follow the specification here.
The same can be extended to the new ``License-File`` field as well,
to ensure that it is valid and the legally required license files are
present, and thus it is lawful for PyPI, users and downstream consumers
to distribute the package. (Of course, this makes no *guarantee* of such
as it is ultimately reliant on authors to declare them, but it improves
assurance of this and allows doing so in the future if the community so
decides.) To be clear, this would not require that any uploaded distribution
have such metadata, only that if they choose to declare it per the new
present. To be clear, this would not require that any uploaded distribution
have such metadata, only that if they choose to declare it per the
specification in PEP 639, it is assured to be valid.
Source metadata ``license`` key
-------------------------------
Alternate possibilities related to the ``license`` key in the
Alternative possibilities related to the ``license`` key in the
``pyproject.toml`` project source metadata.
Add ``expression`` and ``files`` subkeys to table
'''''''''''''''''''''''''''''''''''''''''''''''''
A previous working draft of PEP 639 added ``expression`` and ``files`` subkeys
A previous draft of PEP 639 added ``expression`` and ``files`` subkeys
to the existing ``license`` table in the project source metadata, to parallel
the existing ``file`` and ``text`` subkeys. While this seemed perhaps the
most obvious approach at first glance, it had several serious drawbacks
the existing ``file`` and ``text`` subkeys. While this seemed the
most obvious approach at first glance, it had serious drawbacks
relative to that ultimately taken here.
Most saliently, this means two very different types of metadata are being
This means two very different types of metadata are being
specified under the same top-level key that require very different handling,
and furthermore, unlike the previous arrangement, the subkeys were not mutually
exclusive and can both be specified at once, and with some subkeys potentially
being dynamic and others static, and mapping to different core metadata fields.
Furthermore, this leads to a conflict with marking the key as ``dynamic``
(assuming that is intended to specify the ``[project]`` table keys,
as that PEP seems to imprecisely imply,
rather than core metadata fields), as either or both would have
to be treated as ``dynamic``.
Grouping both license expressions and license files under the same key
forces an "all or nothing" approach, and creates ambiguity as to user intent.
and unlike the previous arrangement, the subkeys were not mutually
exclusive and could both be specified at once, with some subkeys potentially
being dynamic and others static, and mapping to different Core Metadata fields.
There are further downsides to this as well. Both users and tools would need to
keep track of which fields are mutually exclusive with which of the others,
greatly increasing cognitive and code complexity, and in turn the probability
of errors. Conceptually, juxtaposing so many different fields under the
same key is rather jarring, and leads to a much more complex mapping between
``[project]`` keys and core metadata fields, not in keeping with :pep:`621`.
greatly increasing complexity, and the probability
of errors. Having so many different fields under the
same key leads to a much more complex mapping between
``[project]`` keys and Core Metadata fields, not in keeping with :pep:`621`.
This causes the ``[project]`` table naming and structure to diverge further
from both the core metadata and native formats of the various popular packaging
from both the Core Metadata and native formats of the various popular packaging
tools that use it. Finally, this results in the spec being significantly more
complex and convoluted to understand and implement than the alternatives.
complex to understand and implement than the alternatives.
The approach PEP 639 now takes, using the reserved top-level string value
of the ``license`` key, adding a new ``license-files`` key
@ -255,7 +183,7 @@ and results in a much clearer and cleaner design overall.
It allows ``license`` and ``license-files`` to be tagged
``dynamic`` independently, separates two independent types of metadata
(syntactically and semantically), restores a closer to 1:1 mapping of
``[project]`` table keys to core metadata fields,
``[project]`` table keys to Core Metadata fields,
and reduces nesting by a level for both.
Other than adding one extra key to the file, there was no significant
apparent downside to this latter approach, so it was adopted for PEP 639.
@ -265,20 +193,20 @@ Add an ``expression`` subkey instead of a string value
''''''''''''''''''''''''''''''''''''''''''''''''''''''
Adding just an ``expression`` subkey to the ``license`` table,
instead of using the reserved top-level string value,
instead of using the top-level string value,
would be more explicit for readers and writers,
in line with PEP 639's goals.
However, it still has the downsides listed above
that are not specific to the inclusion of the ``files`` key.
Relative to a flat string value,
it adds verbosity, complexity and an extra level of nesting,
it adds complexity and an extra level of nesting,
and requires users and tools to remember and handle
the mutual exclusivity of the subkeys
and remember which are deprecated and which are not,
and remember which are deprecated,
instead of cleanly deprecating the table subkeys as a whole.
Furthermore, it is less clearly the "default" choice for modern use,
given users tend to gravitate toward the simplest and most obvious option.
given users tend to gravitate toward the most obvious option.
Finally, it seems reasonable to follow the suggested guidance in :pep:`621`,
given the top-level string value was specifically reserved for this purpose.
@ -288,18 +216,17 @@ Define a new top-level ``license-expression`` key
An earlier version of PEP 639 defined a new, top-level ``license-expression``
under the ``[project]`` table,
rather than using the reserved string value of the ``license`` key.
This was seen as clearer and more explicit for readers and writers,
rather than using the string value of the ``license`` key.
This was seen as clearer for readers and writers,
in line with the goals of PEP 639.
Additionally, while differences from existing tool formats (and core metadata
field names) have precedent in :pep:`621`,
using a key with an identical name as in most/all current tools
to mean something different (and map to a different core metadata field),
with distinct and incompatible syntax and semantics, does not,
and could cause confusion and ambiguity for readers and authors.
While differences from existing tool formats (and Core Metadata
field names) have precedent in :pep:`621`, repurposing an existing key to mean
something different (and map to a different Core Metadata field),
with distinct and incompatible syntax does not,
and could cause ambiguity for readers and authors.
Also, per the `project source metadata spec <pep621specdynamic_>`__,
Also, per the `project source metadata spec <pyprojecttomldynamic_>`__,
this would allow separately marking the ``[project]`` keys
corresponding to the ``License`` and ``License-Expression`` metadata fields
as ``dynamic``,
@ -317,18 +244,18 @@ as :pep:`reserved for this purpose by PEP 621 <621#license>`:
(the same logic applies to any sort of "type" field specifying what
license the file or text represents).
This is shorter and simpler for users to remember and type,
This is simpler for users to remember and type,
avoids adding a new top-level key while taking advantage of an existing one,
guides users toward using a license expression as the default,
and follows what was envisioned in the original :pep:`621`.
Additionally, this allows cleanly deprecating the table values
without deprecating the key itself,
and makes them inherently mutually exclusive without users having to remember
and makes them mutually exclusive without users having to remember
and tools having to enforce it.
Finally, consistency with other tool formats and the underlying core metadata
was not considered a sufficient priority
Finally, consistency with other tool formats and the underlying Core Metadata
was not a sufficient priority
to override the advantages of using the existing key,
and the ``dynamic`` concerns were mostly mitigated by
not specifying legacy license to license expression conversion at build time,
@ -348,30 +275,28 @@ of the ``license`` key in the ``[project]`` table,
one could add a ``type`` subkey to the ``license`` table
to control whether ``text`` (or a string value)
is interpreted as free-text or a license expression. This could make
backward compatibility a little more seamless, as older tools could ignore
backward compatibility a bit easier, as older tools could ignore
it and always treat ``text`` as ``license``, while newer tools would
know to treat it as a license expression, if ``type`` was set appropriately.
Indeed, :pep:`621` seems to suggest something of this sort as a possible
alternative way that SPDX license expressions could be implemented.
way that SPDX license expressions could be implemented.
However, all the same downsides as in the previous item apply here,
However, it has got all the same downsides as in the previous item,
including greater complexity, a more complex mapping between the project
source metadata and core metadata and inconsistency between the presentation
in tool config, project source metadata and core metadata,
a much less clean deprecation, further bikeshedding over what to name it,
source metadata and Core Metadata and inconsistency between the presentation
in tool config, project source metadata and Core Metadata,
a harder deprecation, further bikeshedding over what to name it,
and inability to mark one but not the other as dynamic, among others.
In addition, while theoretically potentially a little easier in the short
In addition, while theoretically a little easier in the short
term, in the long term it would mean users would always have to remember
to specify the correct ``type`` to ensure their license expression is
interpreted correctly, which adds work and potential for error; we could
never safety change the default while being confident that users
never safely change the default while being confident that users
understand that what they are entering is unambiguously a license expression,
with all the false positive and false negative issues as above.
Therefore, for these as well as the same reasons this approach was rejected
for the core metadata in favor of a distinct ``License-Expression`` field,
we similarly reject this here in favor of
Therefore, for these reasons, we reject this here in favor of
the reserved string value of the ``license`` key.
@ -379,7 +304,7 @@ Must be marked dynamic to back-fill
'''''''''''''''''''''''''''''''''''
The ``license`` key in the ``pyproject.toml`` could be required to be
explicitly set to dynamic in order for the ``License`` core metadata field
explicitly set to dynamic in order for the ``License`` Core Metadata field
to be automatically back-filled from
the top-level string value of the ``license`` key.
This would be more explicit that the filling will be done,
@ -388,9 +313,9 @@ as strictly speaking the ``license`` key is not (and cannot be) specified in
of the previous :pep:`621` specification that PEP 639 revises.
However, this doesn't seem to be necessary, because it is simply using the
static, verbatim literal value of the ``license`` key, as specified
strictly in PEP 639. Therefore, any conforming tool can trivially,
deterministically and unambiguously derive this using only the static data
static, literal value of the ``license`` key, as specified
strictly in PEP 639. Therefore, any conforming tool can
deterministically derive this using only the static data
in the ``pyproject.toml`` file itself.
Furthermore, this actually adds significant ambiguity, as it means the value
@ -401,9 +326,9 @@ why such is explicitly prohibited by PEP 639. Therefore, not marking it as
requirements.
Finally, users explicitly being told to mark it as ``dynamic``, or not, to
control filling behavior seems to be a bit of a mis-use of the ``dynamic``
control filling behavior seems to be a bit of a misuse of the ``dynamic``
field as apparently intended, and prevents tools from adapting to best
practices (fill, don't fill, etc) as they develop and evolve over time.
practices (fill, don't fill, etc.) as they develop and evolve over time.
Source metadata ``license-files`` key
@ -420,47 +345,46 @@ Add a ``type`` subkey to ``license-files``
Instead of defining mutually exclusive ``paths`` and ``globs`` subkeys
of the ``license-files`` ``[project]`` table key, we could
achieve the same effect with a ``files`` subkey for the list and
a ``type`` subkey for how to interpret it. However, the latter offers no
real advantage over the former, in exchange for requiring more keystrokes,
verbosity and complexity, as well as less flexibility in allowing both,
a ``type`` subkey for how to interpret it. However, it offers no
real advantage in exchange for requiring more keystrokes,
increased complexity, as well as less flexibility in allowing both,
or another additional subkey in the future, as well as the need to bikeshed
over the subkey name. Therefore, it was summarily rejected.
over the subkey name. Therefore, it was rejected.
Only accept verbatim paths
''''''''''''''''''''''''''
Globs could be disallowed completely as values to the ``license-files``
key in ``pyproject.toml`` and only verbatim literal paths allowed.
This would ensure that all license files are explicitly specified, all
specified license files are found and included, and the source metadata
Globs could be disallowed as values to the ``license-files``
key in ``pyproject.toml`` and only verbatim paths allowed.
This would ensure that all license files are explicitly specified,
found and included, and the source metadata
is completely static in the strictest sense of the term, without tools
having to inspect the rest of the project source files to determine exactly
what license files will be included and what the ``License-File`` values
will be. This would also modestly simplify the spec and tool implementation.
will be. This would also simplify the spec and tool implementation.
However, practicality once again beats purity here. Globs are supported and
used by many existing tools for finding license files, and explicitly
However, practicality beats purity here. Globs are already supported
by many existing tools, and explicitly
specifying the full path to every license file would be unnecessarily tedious
for more complex projects with vendored code and dependencies. More
for complex projects with vendored dependencies. More
critically, it would make it much easier to accidentally miss a required
legal file, silently rendering the package illegal to distribute.
legal file, creating the package illegal to distribute.
Tools can still statically and consistently determine the files to be included,
based only on those glob patterns the user explicitly specified and the
Tools can still determine the files to be included,
based only on the glob patterns the user specified and the
filenames in the package, without installing it, executing its code or even
examining its files. Furthermore, tools are still explicitly allowed to warn
if specified glob patterns (including full paths) don't match any files.
examining its files. Furthermore, tools are explicitly allowed to warn
if specified glob patterns don't match any files.
And, of course, sdists, wheels and others will have the full static list
of files specified in their distribution metadata.
Perhaps most importantly, this would also preclude the currently specified
default value, as widely used by the current most popular tools, and thus
be a major break to backward compatibility, tool consistency, and safe
and sane default functionality to avoid unintentional license violations.
And of course, authors are welcome and encouraged to specify their license
Perhaps most importantly, this would also exclude the currently specified
default value widely used by the most popular tools, and thus
be a major break to backward compatibility.
And of course, authors are welcome to specify their license
files explicitly via the ``paths`` table subkey, once they are aware of it and
if it is suitable for their project and workflow.
find it suitable for their project.
Only accept glob patterns
@ -480,14 +404,14 @@ Including an explicit ``paths`` value ensures that the resulting
``License-File`` metadata is correct, complete and purely static in the
strictest sense of the term, with all license paths explicitly specified
in the ``pyproject.toml`` file, guaranteed to be included and with an early
error should any be missing. This is not practical to do, at least without
error if any are missing. This is not practical to do, at least without
serious limitations for many workflows, if we must assume the items
are glob patterns rather than literal paths.
This allows tools to locate them and know the exact values of the
``License-File`` core metadata fields without having to traverse the
source tree of the project and match globs, potentially allowing easier,
more efficient and reliable programmatic inspection and processing.
``License-File`` Core Metadata fields without having to traverse the
source tree of the project and match globs, potentially allowing
more reliable programmatic inspection and processing.
Therefore, given the relatively small cost and the significant benefits,
this approach was not adopted.
@ -498,28 +422,26 @@ Infer whether paths or globs
It was considered whether to simply allow specifying an array of strings
directly for the ``license-files`` key, rather than making it a table with
explicit ``paths`` and ``globs``. This would be somewhat simpler and avoid
explicit ``paths`` and ``globs``. This would be simpler and avoid
an extra level of nesting, and more closely match the configuration format
of existing tools. However, it was ultimately rejected in favor of separate,
mutually exclusive ``paths`` and ``globs`` table subkeys.
In practice, it only saves six extra characters in the ``pyproject.toml``
(``license-files = [...]`` vs ``license-files.globs = [...]``), but allows
the user to more explicitly declare their intent, ensures they understand how
the values are going to be interpreted, and serves as an unambiguous indicator
for tools to parse them as globs rather than verbatim path literals.
the user to explicitly declare their intent and serves as an unambiguous
indicator for tools to parse them as globs rather than verbatim paths.
This, in turn, allows for more appropriate, clearly specified tool
This, in turn, allows for clearly specified tool
behaviors for each case, many of which would be unreliable or impossible
without it, to avoid common traps, provide more helpful feedback and
behave more sensibly and intuitively overall. These include, with ``paths``,
guaranteeing that each and every specified file is included and immediately
without it and
behave more intuitively overall. These include, with ``paths``,
guaranteeing that each specified file is included and immediately
raising an error if one is missing, and with ``globs``, checking glob syntax,
excluding unwanted backup, temporary, or other such files (as current tools
already do), and optionally warning if a glob doesn't match any files.
excluding unwanted backup, temporary, or other such files,
and optionally warning if a glob doesn't match any files.
This also avoids edge cases (e.g. paths that contain glob characters) and
reliance on heuristics to determine interpretation—the very thing PEP 639
seeks to avoid.
reliance on heuristics to determine interpretation.
.. _639-license-files-allow-flat-array:
@ -530,25 +452,23 @@ Also allow a flat array value
Initially, after deciding to define ``license-files`` as a table of ``paths``
and ``globs``, thought was given to making a top-level string array under the
``license-files`` key mean one or the other (probably ``globs``, to match most
current tools). This is slightly shorter and simpler, would allow gently
nudging users toward a preferred one, and allow a slightly cleaner handling of
the empty case (which, at present, is treated identically for either).
current tools). This is slightly shorter, indicates to
the users which one is a preferred one, and allows a cleaner handling of
the empty case.
However, this again only saves six characters in the best case, and there
isn't an obvious choice; whether from a perspective of preference (both had
clear use cases and benefits), nor as to which one users would naturally
assume.
However, this only saves six characters in the best case, and there
isn't an obvious choice.
Flat may be better than nested, but in the face of ambiguity, users
may not resist the temptation to guess. Requiring users to explicitly specify
one or the other ensures they are aware of how their inputs will be handled,
and is more readable for others, both human and machine alike. It also makes
and is more readable for others. It also makes
the spec and tool implementation slightly more complicated, and it can always
be added in the future, but not removed without breaking backward
compatibility. And finally, for the "preferred" option, it means there is
more than one obvious way to do it.
Therefore, per :pep:`20`, the Zen of Python, this approach is hereby rejected.
Therefore, per :pep:`20`, the Zen of Python, this approach is rejected.
Allow both ``paths`` and ``globs`` subkeys
@ -556,73 +476,64 @@ Allow both ``paths`` and ``globs`` subkeys
Allowing both ``paths`` and ``globs`` subkeys to be specified under the
``license-files`` table was considered, as it could potentially allow
more flexible handling for particularly complex projects, and specify on a
per-pattern rather than overall basis whether ``license-files`` entries
should be treated as ``paths`` or ``globs``.
more flexible handling for particularly complex projects.
However, given the existing proposed approach already matches or exceeds the
power and capabilities of those offered in tools' config files, there isn't
clear demand for this and few likely cases that would benefit, it adds a large
amount of complexity for relatively minimal gain, in terms of the
specification, in tool implementations and in ``pyproject.toml`` itself.
capabilities of those offered in tools' config files, there isn't
clear demand for this, and it adds a large
amount of complexity in tool implementations and ``pyproject.toml``
for relatively minimal gain.
There would be many more edge cases to deal with, such as how to handle files
matched by both lists, and it conflicts in multiple places with the current
specification for how tools should behave with one or the other, such as when
no files match, guarantees of all files being included and of the file paths
being explicitly, statically specified, and others.
matched by both lists, and it conflicts with the current
specification for how tools should behave, such as when
no files match.
Like the previous, if there is a clear need for it, it can be always allowed
in the future in a backward-compatible manner (to the extent it is possible
in the first place), while the same is not true of disallowing it.
in the future in a backward-compatible manner,
while the same is not true of disallowing it.
Therefore, it was decided to require the two subkeys to be mutually exclusive.
Rename ``paths`` subkey to ``files``
''''''''''''''''''''''''''''''''''''
Initially, it was considered whether to name the ``paths`` subkey of the
``license-files`` table ``files`` instead. However, ``paths`` was ultimately
chosen, as calling the table subkey ``files`` resulted in duplication between
Initially, the name ``files`` was considered instead of the ``paths`` for the
subkey of ``license-files`` table. However, ``paths`` was ultimately
chosen to avoid duplication between
the table name (``license-files``) and the subkey name (``files``), i.e.
``license-files.files = ["LICENSE.txt"]``, made it seem like the preferred/
default subkey when it was not, and lacked the same parallelism with ``globs``
in describing the format of the string entry rather than what was being
pointed to.
``license-files.files = ["LICENSE.txt"]``. It made it seem like
the preferred subkey when it was not, and didn't describe the format of the
string entry similarly to the existing ``globs``.
Must be marked dynamic to use defaults
''''''''''''''''''''''''''''''''''''''
It may seem outwardly sensible, at least with a particularly restrictive
interpretation of :pep:`621`'s description of the ``dynamic`` list, to
consider requiring the ``license-files`` key to be explicitly marked as
``dynamic`` in order for the default glob patterns to be used, or alternatively
With a restrictive
interpretation of :pep:`621`'s description of the ``dynamic`` list it may
seem sensible to require the ``license-files`` key to be marked as
``dynamic`` for the default glob patterns to be used, or alternatively
for license files to be matched and included at all.
However, this is merely declaring a static, strictly-specified default value
for this particular key, required to be used exactly by all conforming tools
(so long as it is not marked ``dynamic``, negating this argument entirely),
and is no less static than any other set of glob patterns the user themself
may specify. Furthermore, the resulting ``License-File`` core metadata values
can still be determined with only a list of files in the source, without
installing or executing any of the code, or even inspecting file contents.
However, this is just declaring a static, strictly-specified default value,
required to be used exactly by all conforming tools, similarly to any other set
of glob patterns the user themself may specify.
The resulting ``License-File`` Core Metadata values
can be determined through inspecting a list of files in the source, without
executing code, or even inspecting file contents.
Moreover, even if this were not so, practicality would trump purity, as this
interpretation would be strictly backwards-incompatible with the existing
Moreover, even if this were not so, this
interpretation would be backwards-incompatible with the existing
format, and be inconsistent with the behavior with the existing tools.
Further, this would create a very serious and likely risk of a large number of
Further, this would create a serious risk of a large number of
projects unknowingly no longer including legally mandatory license files,
making their distribution technically illegal, and is thus not a sane,
much less sensible default.
and is thus not a sane default.
Finally, aside from adding an additional line of default-required boilerplate
to the file, not defining the default as dynamic allows authors to clearly
and unambiguously indicate when their build/packaging tools are going to be
handling the inclusion of license files themselves rather than strictly
conforming to the project source metadata portions of PEP 639;
to do otherwise would defeat the primary purpose of the ``dynamic`` list
as a marker and escape hatch.
Finally, not defining the default as dynamic allows authors to unambiguously
indicate when their build/packaging tools are going to be
handling the inclusion of license files themselves;
to do otherwise would defeat the purpose of the ``dynamic`` list.
License file paths
@ -635,36 +546,31 @@ and built distributions.
Flatten license files in subdirectories
'''''''''''''''''''''''''''''''''''''''
Previous drafts of PEP 639 were silent on the issue of handling license files
in subdirectories. Currently, the `Wheel <wheelfiles_>`__ and (following its
example) `Setuptools <setuptoolsfiles_>`__ projects flatten all license files
Previous drafts of PEP 639 didn't specify how to handle the license files
in subdirectories. Currently, the `Wheel <wheelfiles_>`__ and
`Setuptools <setuptoolsfiles_>`__ projects flatten all license files
into the ``.dist-info`` directory without preserving the source subdirectory
hierarchy.
While this is the simplest approach and matches existing ad hoc practice,
this can result in name conflicts and license files clobbering others,
with no obvious defined behavior for how to resolve them, and leaving the
package legally un-distributable without any clear indication to users that
their specified license files have not been included.
While this approach and matches existing ad hoc practice,
it can result in name conflicts and license files clobbering others,
with no defined behavior for how to resolve them, and leaving the
package legally un-distributable without any clear indication that
the specified license files have not been included.
Furthermore, this leads to inconsistent relative file paths for non-root
license files between the source, sdist and wheel, and prevents the paths
given in the "static" ``[project]`` table metadata from being truly static,
as they need to be flattened, and may potentially overwrite one another.
Finally, the source directory structure often implies valuable information
about what the licenses apply to, and where to find them in the source,
given in the "static" ``[project]`` table metadata from being truly static.
Finally, the source directory structure often holds valuable information
about what the licenses apply to,
which is lost when flattening them and far from trivial to reconstruct.
To resolve this, the PEP now proposes, as did contributors on both of the
above issues, reproducing the source directory structure of the original
license files inside the ``.dist-info`` directory. This would fully resolve the
concerns above, with the only downside being a more nested ``.dist-info``
directory. There is still a risk of collision with edge-case custom
filenames (e.g. ``RECORD``, ``METADATA``), but that is also the case
with the previous approach, and in fact with fewer files flattened
into the root, this would actually reduce the risk. Furthermore,
the following proposal rooting the license files under a ``licenses``
subdirectory eliminates both collisions and the clutter problem entirely.
To resolve this, the PEP now proposes reproducing the source directory
structure of the original
license files inside the ``.dist-info`` directory. The only downside of this
approach is having a more nested ``.dist-info``
directory. The following proposal rooting the license files under a ``licenses``
subdirectory eliminates both name collisions and the clutter problem entirely.
Resolve name conflicts differently
@ -677,95 +583,79 @@ to the license filename, traversing up the tree until the name was unique,
to avoid excessively nested directories.
However, this would not address the path consistency issues, would require
much more discussion, coordination and bikeshedding, and further complicate
the specification and the implementations. Therefore, it was rejected in
favor of the simpler and more obvious solution of just preserving the
source subdirectory layout, as many stakeholders have already advocated for.
much more discussion and further complicate
the specification. Therefore, it was rejected in
favor of the more obvious solution of just preserving the
source subdirectory layout, as many stakeholders have advocated for.
Dump directly in ``.dist-info``
'''''''''''''''''''''''''''''''
Previously, the included license files were stored directly in the top-level
``.dist-info`` directory of built wheels and installed projects. This followed
existing ad hoc practice, ensured most existing wheels currently using this
feature will match new ones, and kept the specification simpler, with the
license files always being stored in the same location relative to the core
metadata regardless of distribution type.
``.dist-info`` directory of built wheels and installed projects.
However, this leads to a more cluttered ``.dist-info`` directory, littered
with arbitrary license files and subdirectories, as opposed to separating
licenses into their own namespace (which per the Zen of Python, :pep:`20`, are
"one honking great idea"). While currently small, there is still a
risk of collision with specific custom license filenames
However, this leads to a more cluttered ``.dist-info`` directory
as opposed to separating
licenses into their own namespace. There is still a
risk of collision with custom license filenames
(e.g. ``RECORD``, ``METADATA``) in the ``.dist-info`` directory, which
would only increase if and when additional files were specified here, and
would require carefully limiting the potential filenames used to avoid
likely conflicts with those of license-related files. Finally,
would require limiting the potential filenames used. Finally,
putting licenses into their own specified subdirectory would allow
humans and tools to quickly, easily and correctly list, copy and manipulate
all of them at once (such as in distro packaging, legal checks, etc)
without having to reference each of their paths from the core metadata.
humans and tools to correctly manipulate
all of them at once (such as in distro packaging, legal checks, etc.)
without having to reference each of their paths from the Core Metadata.
Therefore, now is a prudent time to specify an alternate approach.
The simplest and most obvious solution, as suggested by several on the Wheel
and Setuptools implementation issues, is to simply root the license files
Therefore, the simplest and most obvious solution, as suggested by several
on the Wheel
and Setuptools implementation issues, is to root the license files
relative to a ``licenses`` subdirectory of ``.dist-info``. This is simple
to implement and solves all the problems noted here, without clear significant
to implement and solves all the problems noted here, without significant
drawbacks relative to other more complex options.
It does make the specification a bit more complex and less elegant, but
It does make the specification a bit more complex, but
implementation should remain equally simple. It does mean that wheels
produced with following this change will have differently-located licenses
than those prior, but as this was already true for those in subdirectories,
and until PEP 639 there was no way of discovering these files or
accessing them programmatically, this doesn't seem likely to pose
significant problems in practice. Given this will be much harder if not
impossible to change later, once the status quo is standardized, tools are
relying on the current behavior and there is much greater uptake of not
only simply including license files but potentially accessing them as well
using the core metadata, if we're going to change it, now would be the time
(particularly since we're already introducing an edge-case change with how
license files in subdirs are handled, along with other refinements).
Therefore, the latter has been incorporated into current drafts of PEP 639.
and until PEP 639 there was no way of
accessing these files programmatically, this should not pose
significant problems in practice.
Add new ``licenses`` category to wheel
''''''''''''''''''''''''''''''''''''''
Instead of defining a root license directory (``licenses``) inside
the core metadata directory (``.dist-info``) for wheels, we could instead
the Core Metadata directory (``.dist-info``) for wheels, we could instead
define a new category (and, presumably, a corresponding install scheme),
similar to the others currently included under ``.data`` in the wheel archive,
specifically for license files, called (e.g.) ``licenses``. This was mentioned
by the wheel creator, and would allow installing licenses somewhere more
platform-appropriate and flexible than just the ``.dist-info`` directory
in the site path, and potentially be conceptually cleaner than including
them there.
in the site path.
However, at present, PEP 639 does not implement this idea, and it is
deferred to a future one. It would add significant complexity and friction
to PEP 639, being primarily concerned with standardizing existing practice
and updating the core metadata specification. Furthermore, doing so would
likely require modifying ``sysconfig`` and the install schemes specified
and updating the Core Metadata specification. Furthermore, doing so could
require modifying ``sysconfig`` and the install schemes specified
therein, alongside Wheel, Installer and other tools, which would be a
non-trivial undertaking. While potentially slightly more complex for
repackagers (such as those for Linux distributions), the current proposal still
ensures all license files are included, and in a single dedicated directory
(which can easily be copied or relocated downstream), and thus should still
greatly improve the status quo in this regard without the attendant complexity.
repackagers, the current proposal still
ensures all license files are included in a single dedicated directory,
and thus should still
greatly improve the status quo in this regard.
In addition, this approach is not fully backwards compatible (since it
isn't transparent to tools that simply extract the wheel), is a greater
departure from existing practice and would lead to more inconsistent
license install locations from wheels of different versions. Finally,
this would mean licenses would not be installed as proximately to their
this would mean licenses would not be installed as close to their
associated code, there would be more variability in the license root path
across platforms and between built distributions and installed projects,
accessing installed licenses programmatically would be more difficult, and a
suitable install location and method would need to be created, discussed
and decided that would avoid name clashes.
suitable install location and method would need to be created that would avoid
name clashes.
Therefore, to keep PEP 639 in scope, the current approach was retained.
@ -777,11 +667,11 @@ Both ``licenses`` and ``license_files`` have been suggested as potential
names for the root license directory inside ``.dist-info`` of wheels and
installed projects. An initial draft of the PEP specified the former
due to being slightly clearer and consistent with the
name of the core metadata field (``License-File``)
name of the Core Metadata field (``License-File``)
and the ``[project]`` table key (``license-files``).
However, the current version of the PEP adopts the ``license`` name,
due to a general preference by the community for its shorter length,
greater simplicity and the lack of a separator character (``_``, ``-``, etc.).
However, the current version of the PEP adopts the ``licenses`` name,
due to a general preference by the community for its shorter length
and the lack of a separator character.
Other ideas
@ -794,9 +684,8 @@ ultimately not adopted.
Map identifiers to license files
''''''''''''''''''''''''''''''''
This would require using a mapping (as two parallel lists would be too prone to
alignment errors), which would add extra complexity to how license
are documented and add an additional nesting level.
This would require using a mapping, which would add extra complexity to how
license are documented and add an additional nesting level.
A mapping would be needed, as it cannot be guaranteed that all expressions
(keys) have a single license file associated with them (e.g.
@ -805,15 +694,15 @@ does not have more than one. (e.g. an Apache license ``LICENSE`` and
its ``NOTICE`` file, for instance, are two distinct files).
For most common cases, a single license expression and one or more license
files would be perfectly adequate. In the rarer and more complex cases where
there are many licenses involved, authors can still safety use the fields
there are many licenses involved, authors can still safely use the fields
specified here, just with a slight loss of clarity by not specifying which
text file(s) map to which license identifier (though this should be clear in
practice given each license identifier has corresponding SPDX-registered
full license text), while not forcing the more complex data model
(a mapping) on the large majority of users who do not need or want it.
text file(s) map to which license identifier (though each license identifier
has corresponding SPDX-registered
full license text), while not forcing the more complex mapping
on the large majority of users who do not need or want it.
We could of course have a data field with multiple possible value types (it's a
string, it's a list, it's a mapping!) but this could be a source of confusion.
We could of course have a data field with multiple possible value types
but this could be a source of confusion.
This is what has been done, for instance, in npm (historically) and in Rubygems
(still today), and as result tools need to test the type of the metadata field
before using it in code, while users are confused about when to use a list or a
@ -833,8 +722,7 @@ Don't freeze compatibility with a specific SPDX version
PEP 639 could omit specifying a specific SPDX specification version,
or one for the list of valid license identifiers, which would allow
more flexible updates as the specification evolves without another
PEP or equivalent.
more flexible updates as the specification evolves.
However, serious concerns were expressed about a future SPDX update breaking
compatibility with existing expressions and identifiers, leaving current
@ -844,11 +732,10 @@ and a PEP or similar process to update it avoids this contingency,
and follows the practice of other packaging ecosystems.
Therefore, it was `decided <spdxversion_>`__ to specify a minimum version
and requires tools to be compatible with it, while still allowing updates
and require tools to be compatible with it, while still allowing updates
so long as they don't break backward compatibility. This enables
tools to immediate take advantage of improvements and accept new
licenses, but also remain backwards compatible with the version
specified here, balancing flexibility and compatibility.
licenses balancing flexibility and compatibility.
.. _639-rejected-ideas-difference-license-source-binary:
@ -856,15 +743,13 @@ specified here, balancing flexibility and compatibility.
Different licenses for source and binary distributions
''''''''''''''''''''''''''''''''''''''''''''''''''''''
As an additional use case, it was asked whether it was in scope for this
PEP to handle cases where the license expression for a binary distribution
As an additional use case, it was asked whether it was in scope for
PEP 639 to handle cases where the license expression for a binary distribution
(wheel) is different from that for a source distribution (sdist), such
as in cases of non-pure-Python packages that compile and bundle binaries
under different licenses than the project itself. An example cited was
`PyTorch <pytorch_>`__, which contains CUDA from Nvidia, which is freely
distributable but not open source. `NumPy <numpyissue_>`__ and
`SciPy <scipyissue_>`__ also had similar issues, as reported by the
original author of PEP 639 and now resolved for those cases.
distributable but not open source.
However, given the inherent complexity here and a lack of an obvious
mechanism to do so, the fact that each wheel would need its own license
@ -875,12 +760,9 @@ to resolve if sufficient need and interest exists and an appropriate
mechanism can be found.
.. _choosealicense: https://choosealicense.com/
.. _numpyissue: https://github.com/numpy/numpy/issues/8689
.. _pep621specdynamic: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/#dynamic
.. _pyprojecttomldynamic: https://packaging.python.org/en/latest/specifications/pyproject-toml/#dynamic
.. _pytorch: https://pypi.org/project/torch/
.. _reusediscussion: https://github.com/pombredanne/spdx-pypi-pep/issues/7
.. _scipyissue: https://github.com/scipy/scipy/issues/7093
.. _setuptoolsfiles: https://github.com/pypa/setuptools/issues/2739
.. _spdxid: https://spdx.dev/ids/
.. _spdxversion: https://github.com/pombredanne/spdx-pypi-pep/issues/6

35
peps/pep-0639/appendix-user-scenarios.rst
View File

@ -16,7 +16,7 @@ User Scenarios
--------------
The following covers the range of common use cases from a user perspective,
providing straightforward guidance for each. Do note that the following
providing guidance for each. Do note that the following
should **not** be considered legal advice, and readers should consult a
licensed legal practitioner in their jurisdiction if they are unsure about
the specifics for their situation.
@ -50,8 +50,7 @@ To apply it, just paste `the text <chooseamitlicense_>`__ into a file named
``LICENSE.txt`` at the root of your repo, and add the year and your name to
the copyright line. Then, just add ``license = "MIT"`` under
``[project]`` in your ``pyproject.toml`` if your packaging tool supports it,
or in its config file/section (e.g. Setuptools ``license_expression = MIT``
under ``[metadata]`` in ``setup.cfg``). You're done!
or in its config file/section. You're done!
I want to distribute my project under a specific license
@ -62,8 +61,7 @@ file at the root of your repo, if you don't have it in a file starting with
``LICENSE`` or ``COPYING`` already, and add
``license = "LICENSE-ID"`` under ``[project]`` in your
``pyproject.toml`` if your packaging tool supports it, or else in its
config file (e.g. for Setuptools, ``license_expression = LICENSE-ID``
under ``[metadata]`` in ``setup.cfg``). You can find the ``LICENSE-ID``
config file. You can find the ``LICENSE-ID``
and copyable license text on sites like
`ChooseALicense <choosealicenselist_>`__ or `SPDX <spdxlist_>`__.
@ -80,7 +78,6 @@ functionality.
In your project config file, enter your license expression under
``license`` (``[project]`` table in ``pyproject.toml``),
``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``),
or the equivalent for your packaging tool,
and make sure to remove any legacy ``license`` table subkeys or
``License ::`` classifiers. Your existing ``license`` value may already
@ -88,16 +85,12 @@ be valid as one (e.g. ``MIT``, ``Apache-2.0 OR BSD-2-Clause``, etc);
otherwise, check the `SPDX license list <spdxlist_>`__ for the identifier
that matches the license used in your project.
If your license files begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or
``AUTHORS``, or you've already configured your packaging tool to add them
(e.g. ``license_files`` in ``setup.cfg``), you should already be good to go.
If not, make sure to list them under ``license-files.paths``
Make sure to list your license files under ``license-files.paths``
or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
(if your tool supports it), or else in your tool's configuration file
(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
or else in your tool's configuration file.
See the :ref:`639-example-basic` for a simple but complete real-world demo
of how this works in practice, including some additional technical details.
of how this works in practiced.
Packaging tools may support automatically converting legacy licensing
metadata; check your tool's documentation for more information.
@ -107,8 +100,8 @@ My package includes other code under different licenses
If your project includes code from others covered by different licenses,
such as vendored dependencies or files copied from other open source
software, you can construct a license expression (or have a tool
help you do so) to describe the licenses involved and the relationship
software, you can construct a license expression
to describe the licenses involved and the relationship
between them.
In short, ``License-1 AND License-2`` mean that *both* licenses apply
@ -121,19 +114,15 @@ complex situations.
In your project config file, enter your license expression under
``license`` (``[project]`` table of ``pyproject.toml``),
``license_expression`` (Setuptools ``setup.cfg`` / ``setup.py``),
or the equivalent for your packaging tool,
and make sure to remove any legacy ``license`` table subkeys
or ``License ::`` classifiers.
Also, make sure you add the full license text of all the licenses as files
somewhere in your project repository. If all of them are in the root directory
and begin with ``LICENSE``, ``COPYING``, ``NOTICE`` or ``AUTHORS``,
they will be included automatically. Otherwise, you'll need to list the
somewhere in your project repository. List the
relative path or glob patterns to each of them under ``license-files.paths``
or ``license-files.globs`` under ``[project]`` in ``pyproject.toml``
(if your tool supports it), or else in your tool's configuration file
(e.g. ``license_files`` in ``setup.cfg`` for Setuptools).
(if your tool supports it), or else in your tool's configuration file.
As an example, if your project was licensed MIT but incorporated
a vendored dependency (say, ``packaging``) that was licensed under
@ -146,8 +135,8 @@ as glob patterns, or
``["LICENSE.txt", "_vendor/LICENSE-APACHE.txt", "_vendor/LICENSE-BSD.txt"]``
as literal file paths.
See a fully worked out :ref:`639-example-advanced` for a comprehensive end-to-end
application of this to a real-world complex project, with copious technical
See a fully worked out :ref:`639-example-advanced` for an end-to-end
application of this to a real-world complex project, with many technical
details, and consult a `tutorial <spdxtutorial_>`__ for more help and examples
using SPDX identifiers and expressions.