PEP 639: edits from review (#1628)
* Fix monospaces * The 'license expression' term shouldn't be monospaced/capitalized * Rephrasing * Fix capitalization of titles * Make it clear when we're talking about the Classifiers field vs classifiers * More monospace fixes * Edits for clarity * Fix 'License ::' prefix * Update link * More tweaks for clarity * Fix broken ref Co-authored-by: Philippe Ombredanne <pombredanne@gmail.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
This commit is contained in:
Dustin Ingram
GitHub
parent
fe9576d4f6
commit
4bd3577610
418
pep-0639.rst
418
pep-0639.rst
|
|
@ -23,9 +23,9 @@ This PEP describes the changes between versions 2.1 and 2.2 of the `Core
|
|||
Metadata Specification` [#cms]_ for Python packages. Version 2.1 is specified in
|
||||
PEP 566.
|
||||
|
||||
The primary change introduced in this PEP updates how license is documented in
|
||||
Core metadata in the `License` field with `License Expression` strings using
|
||||
SPDX license IDs [#spdxlist]_ such that license documentation is simpler and less
|
||||
The primary change introduced in this PEP updates how licenses are documented in
|
||||
core metadata via the ``License`` field with license expression strings using
|
||||
SPDX license identifiers [#spdxlist]_ such that license documentation is simpler and less
|
||||
ambiguous:
|
||||
|
||||
- for package authors to create,
|
||||
|
|
@ -34,17 +34,17 @@ ambiguous:
|
|||
|
||||
The other changes include:
|
||||
|
||||
- specifying a `License-File` field which is already used by `wheel` and
|
||||
`setuptools` to include license files in built distributions.
|
||||
- specifying a ``License-File`` field which is already used by ``wheel`` and
|
||||
``setuptools`` to include license files in built distributions.
|
||||
- defining how tools can validate license expressions and report warnings to
|
||||
users for invalid expressions (but still accept any string as `License`).
|
||||
users for invalid expressions (but still accept any string as ``License``).
|
||||
|
||||
|
||||
Goals
|
||||
=====
|
||||
|
||||
This PEP's scope is limited strictly to how we document the license of a
|
||||
package distribution:
|
||||
distribution:
|
||||
|
||||
- with an improved and structured way to document a license expression, and,
|
||||
- by including license texts in a built package.
|
||||
|
|
@ -52,17 +52,17 @@ package distribution:
|
|||
The core metadata specification updates that are part of this PEP, have been
|
||||
designed to have minimal impact and to be backward compatible with v2.1.
|
||||
These changes utilize emerging new ways to document licenses that are already
|
||||
in use in some tools (e.g. by adding `Licence-File` field already used in
|
||||
`wheel` and `setuptools`) or by some package authors (e.g. storing an SPDX
|
||||
license expression in the existing `License` field).
|
||||
in use in some tools (e.g. by adding the ``Licence-File`` field already used in
|
||||
``wheel`` and ``setuptools``) or by some package authors (e.g. storing an SPDX
|
||||
license expression in the existing ``License`` field).
|
||||
|
||||
In addition to an update to the metadata specification, this PEP contains:
|
||||
|
||||
- recommendations for Publishing tools on how to validate the `License`
|
||||
and `Classifier` fields and report informational warnings when a package uses
|
||||
an older, non- structured style of license documentation conventions.
|
||||
- recommendations for publishing tools on how to validate the ``License``
|
||||
and ``Classifier`` fields and report informational warnings when a package uses
|
||||
an older, non-structured style of license documentation conventions.
|
||||
|
||||
- informational appendixes that contain surveys of how we document license
|
||||
- informational appendixes that contain surveys of how we document licenses
|
||||
today in Python packages and elsewhere, and a reference Python library to
|
||||
parse, validate and build correct license expressions.
|
||||
|
||||
|
|
@ -81,16 +81,16 @@ simpler and more expressive conventions to document more accurately any kind of
|
|||
license that applies to a Python package, whether under an open source, free or
|
||||
libre software license or a proprietary license.
|
||||
|
||||
This PEP makes no recommendation for certain licenses or require the use of
|
||||
certain license documentation conventions. This PEP also does not impose any
|
||||
This PEP makes no recommendation for certain licenses and does not require the use of
|
||||
specific license documentation conventions. This PEP also does not impose any
|
||||
restrictions when uploading to PyPI.
|
||||
|
||||
Instead, this PEP is intended to document common practices already in use,
|
||||
and recommends that Publishing tools should gently nag users with informational
|
||||
warnings when they do not follow this PEP recommendations.
|
||||
and recommends that publishing tools should encourage users via informational
|
||||
warnings when they do not follow this PEP's recommendations.
|
||||
|
||||
This PEP is not about documenting license in code files, even though this is a
|
||||
surveyed topic in Appendix.
|
||||
surveyed topic in the appendix.
|
||||
|
||||
|
||||
Possible future PEPs
|
||||
|
|
@ -99,7 +99,7 @@ Possible future PEPs
|
|||
It is the intention of the authors of this PEP to consider the submission of
|
||||
related but separate PEPs in the future such as:
|
||||
|
||||
- make `License` and new `License-File` fields mandatory including
|
||||
- make ``License`` and new ``License-File`` fields mandatory including
|
||||
stricter enforcement in tools and PyPI publishing.
|
||||
|
||||
- require uploads to PyPI to use only FOSS (Free and Open Source software)
|
||||
|
|
@ -120,7 +120,7 @@ possibilities to express licensing in package metadata. This also applies to
|
|||
Linux and BSD* distribution packagers. This has triggered several license-related
|
||||
discussions and issues and in particular:
|
||||
|
||||
- https://github.com/pypa/warehouse/issues/2996
|
||||
- https://github.com/pypa/trove-classifiers/issues/17
|
||||
- https://github.com/pypa/interoperability-peps/issues/46
|
||||
- https://github.com/pypa/packaging-problems/issues/41
|
||||
- https://github.com/pypa/wheel/issues/138
|
||||
|
|
@ -137,19 +137,19 @@ source projects that is incubating at the OSI (Open Source Initiative) [#osi]_.
|
|||
Rationale
|
||||
=========
|
||||
|
||||
A mini survey of existing license metadata definitions in use in Python today
|
||||
and documented in several other system/distro and application package formats is
|
||||
provided in Appendix 2, of this PEP.
|
||||
A mini survey of existing license metadata definitions in use in the Python
|
||||
ecosystem today and documented in several other system/distro and application
|
||||
package formats is provided in Appendix 2 of this PEP.
|
||||
|
||||
There are a few takeaways from the survey:
|
||||
|
||||
- Most package formats use a single `License` field.
|
||||
- Most package formats use a single ``License`` field.
|
||||
|
||||
- Many modern package formats use some form of license expression syntax to
|
||||
optionally combine more than one license identifiers together. SPDX and
|
||||
SPDX-like syntaxes are the most popular in use.
|
||||
|
||||
- SPDX license IDs are becoming a de-facto way to reference common licenses
|
||||
- SPDX license identifiers are becoming a de-facto way to reference common licenses
|
||||
everywhere, whether or not a license expression syntax is used.
|
||||
|
||||
- Several package formats support documenting both a license expression and
|
||||
|
|
@ -159,9 +159,9 @@ There are a few takeaways from the survey:
|
|||
|
||||
These considerations have guided the design and recommendations of this PEP.
|
||||
|
||||
The reuse of the `License` field with license expressions will provide an
|
||||
The reuse of the ``License`` field with license expressions will provide an
|
||||
intuitive and more structured way to express the license of a distribution using
|
||||
a well-defined syntax and well-known license ID.
|
||||
a well-defined syntax and well-known license identifiers.
|
||||
|
||||
Over time, recommending the usage of these expressions will help Python package
|
||||
publishers improve the clarity of their license documentation to the benefit of
|
||||
|
|
@ -185,8 +185,8 @@ Added in Version 2.2
|
|||
License-File (multiple use)
|
||||
:::::::::::::::::::::::::::
|
||||
|
||||
The License-File is a string that is a .dist-info relative path to a license
|
||||
file. The license file content __must__ be UTF-8-encoded text.
|
||||
The License-File is a string that is a ``.dist-info`` relative path to a license
|
||||
file. The license file content MUST be UTF-8 encoded text.
|
||||
|
||||
Build tools SHOULD honor this field and include the corresponding license
|
||||
file(s) in the built package.
|
||||
|
|
@ -199,37 +199,37 @@ License (optional)
|
|||
::::::::::::::::::
|
||||
|
||||
Text indicating the license covering the distribution. This text can be either a
|
||||
valid `License Expression` as defined here or any free text.
|
||||
valid license expression as defined here or any free text.
|
||||
|
||||
Publishing tools SHOULD issue an informational warning if this field is empty or
|
||||
missing or is not a valid `License Expression` as defined here. Build tools MAY
|
||||
issue such a warning too.
|
||||
Publishing tools SHOULD issue an informational warning if this field is empty,
|
||||
missing, or is not a valid license expression as defined here. Build tools MAY
|
||||
issue a similar warning.
|
||||
|
||||
|
||||
License Expression syntax
|
||||
'''''''''''''''''''''''''
|
||||
|
||||
A `License Expression` is a string using the SPDX license expression syntax as
|
||||
A license expression is a string using the SPDX license expression syntax as
|
||||
documented in the SPDX specification [#spdx]_ using either Version 2.2
|
||||
[#spdx22]_ or a later compatible version. SPDX is a working group at the Linux
|
||||
Foundation that defines a standard way to exchange package information.
|
||||
|
||||
When used in the `License` field and as a specialization of the SPDX license
|
||||
expression definition, a `License Expression` can use the following license
|
||||
When used in the ``License`` field and as a specialization of the SPDX license
|
||||
expression definition, a license expression can use the following license
|
||||
identifiers:
|
||||
|
||||
- any SPDX-listed license short-form identifiers that are published in the
|
||||
- any SPDX-listed license short-form identifiers that are published in the
|
||||
SPDX License List [#spdxlist]_ using either Version 3.10 of this list or any
|
||||
later compatible version. Note that the SPDX working group never removes any
|
||||
license identifiers: instead they may only mark one as "obsolete".
|
||||
license identifiers: instead they may only mark an identifier as "obsolete".
|
||||
|
||||
- the `LicenseRef-Public-Domain` and `LicenseRef-Proprietary` strings to support
|
||||
generic ids that are not available in the SPDX license list.
|
||||
- the ``LicenseRef-Public-Domain`` and ``LicenseRef-Proprietary`` strings to support
|
||||
generic identifiers that are not available in the SPDX license list.
|
||||
|
||||
When processing the `License` field to determine if it contains a valid license
|
||||
When processing the ``License`` field to determine if it contains a valid license
|
||||
expression, tools:
|
||||
|
||||
- MUST ignore the case of the `License` field
|
||||
- MUST ignore the case of the ``License`` field
|
||||
|
||||
- SHOULD report an informational warning if one or more of the following applies:
|
||||
|
||||
|
|
@ -239,7 +239,7 @@ expression, tools:
|
|||
unknown as defined here or the license identifiers have been marked as
|
||||
deprecated in the SPDX License List [#spdxlist]_
|
||||
|
||||
- SHOULD store a case-normalized version of the `License` field using the
|
||||
- SHOULD store a case-normalized version of the ``License`` field using the
|
||||
reference case for each SPDX license identifier and uppercase for the AND, OR
|
||||
and WITH keywords. And SHOULD report an informational warning if the reference
|
||||
case is not used.
|
||||
|
|
@ -273,73 +273,73 @@ Examples::
|
|||
Classifier: Environment :: Console (Text Based)
|
||||
|
||||
Tools SHOULD issue an informational warning if this field contains a licensing
|
||||
related Classifier string starting with the `License::` prefix and SHOULD
|
||||
suggest the use of a `License Expression` in the `License` field instead.
|
||||
related classifier string starting with the ``License ::`` prefix and SHOULD
|
||||
suggest the use of a license expression in the ``License`` field instead.
|
||||
|
||||
If the `License` field is present and contains a valid License Expression,
|
||||
publishing tools MUST NOT also provide any licensing related Classifiers entries
|
||||
If the ``License`` field is present and contains a valid license expression,
|
||||
publishing tools MUST NOT also provide any licensing related classifier entries
|
||||
[#classif]_.
|
||||
|
||||
However, for compatibility with existing publishing and installation processes,
|
||||
licensing-related Classifiers entries SHOULD continue to be accepted if the
|
||||
License field is absent or does not contain a valid License Expression.
|
||||
licensing-related classifier entries SHOULD continue to be accepted if the
|
||||
``License`` field is absent or does not contain a valid license expression.
|
||||
|
||||
Publishing tools MAY infer a License Expression from the provided Classifiers
|
||||
Publishing tools MAY infer a license expression from the provided classifier
|
||||
entries if they are able to do so unambiguously.
|
||||
|
||||
However, no new licensing related classifiers will be added, with anyone
|
||||
requesting them being directed to use a License Expression in the License field
|
||||
instead. Note that the licensing related Classifiers may be deprecated in a
|
||||
future PEP.
|
||||
requesting them being directed to use a license expression in the ``License``
|
||||
field instead. Note that the licensing related classifiers may be deprecated in
|
||||
a future PEP.
|
||||
|
||||
|
||||
Mapping legacy Classifiers to new License Expressions
|
||||
Mapping Legacy Classifiers to New License Expressions
|
||||
'''''''''''''''''''''''''''''''''''''''''''''''''''''
|
||||
|
||||
Publishing tools MAY infer or suggest an equivalent `License Expression` from
|
||||
the provided License or Classifiers information if they are able to do so
|
||||
Publishing tools MAY infer or suggest an equivalent license expression from
|
||||
the provided ``License`` or ``Classifier`` information if they are able to do so
|
||||
unambiguously. For instance, if a package only has this license classifier::
|
||||
|
||||
Classifier: `License :: OSI Approved :: MIT License`
|
||||
Classifier: License :: OSI Approved :: MIT License
|
||||
|
||||
Then the corresponding value for License using a valid license expression to
|
||||
suggest would be::
|
||||
Then the corresponding value for a ``License`` field using a valid license
|
||||
expression to suggest would be::
|
||||
|
||||
License: MIT
|
||||
|
||||
|
||||
Here are mappings guidelines for the legacy classifiers:
|
||||
|
||||
- Classifier `License :: Other/Proprietary License` becomes License:
|
||||
`LicenseRef-Proprietary` expression.
|
||||
- Classifier ``License :: Other/Proprietary License`` becomes License:
|
||||
``LicenseRef-Proprietary`` expression.
|
||||
|
||||
- Classifier `License :: Public Domain` becomes License: `LicenseRef-Public-Domain`
|
||||
- Classifier ``License :: Public Domain`` becomes License: ``LicenseRef-Public-Domain``
|
||||
expression, though tools should encourage the use of more explicit and legally
|
||||
portable licenses identifiers such as `CC0-1.0` [@cc0]_, the `Unlicense`
|
||||
portable licenses identifiers such as ``CC0-1.0`` [#cc0]_, the ``Unlicense``
|
||||
[#unlic]_: the meaning associated with the term "public domain" is thoroughly
|
||||
dependent on the specific legal jurisdiction involved and some jurisdictions
|
||||
have no concept of Public Domain as it exists in the USA.
|
||||
|
||||
- The generic and ambiguous Classifiers `License :: OSI Approved`
|
||||
and `License :: DFSG approved` do not have an equivalent license expression.
|
||||
- The generic and ambiguous classifiers ``License :: OSI Approved``
|
||||
and ``License :: DFSG approved`` do not have an equivalent license expression.
|
||||
|
||||
- The generic and sometimes ambiguous Classifiers
|
||||
`License :: Free For Educational Use`, `License :: Free For Home Use`,
|
||||
`License :: Free for non-commercial use`, `License :: Freely Distributable`,
|
||||
`License :: Free To Use But Restricted`, and `License :: Freeware` are mapped
|
||||
to the generic License: `LicenseRef-Proprietary` expression.
|
||||
- The generic and sometimes ambiguous classifiers
|
||||
``License :: Free For Educational Use``, ``License :: Free For Home Use``,
|
||||
``License :: Free for non-commercial use``, ``License :: Freely Distributable``,
|
||||
``License :: Free To Use But Restricted``, and ``License :: Freeware`` are mapped
|
||||
to the generic License: ``LicenseRef-Proprietary`` expression.
|
||||
|
||||
- Classifiers `License :: GUST*` have no mapping to SPDX license ids for now and
|
||||
no package uses them in PyPI as of the writing of this PEP.
|
||||
- Classifiers ``License :: GUST*`` have no mapping to SPDX license identifierss
|
||||
for now and no package uses them in PyPI as of the writing of this PEP.
|
||||
|
||||
The remainder of the `Classifiers` using a `License::` prefix map to a simple
|
||||
The remainder of the classifiers using a ``License ::`` prefix map to a simple
|
||||
single license expression using the corresponding SPDX license identifiers.
|
||||
|
||||
When multiple license-related `Classifiers` are used, their relation is
|
||||
When multiple license-related classifiers are used, their relation is
|
||||
ambiguous and it is typically not possible to determine if all the licenses
|
||||
apply or if there is a choice that is possible among the licenses. In this case,
|
||||
tools cannot infer reliably a license expression to suggest using only the
|
||||
legacy Classifier usage.
|
||||
legacy classifier usage.
|
||||
|
||||
|
||||
Summary of Differences From PEP 566
|
||||
|
|
@ -347,21 +347,21 @@ Summary of Differences From PEP 566
|
|||
|
||||
* Metadata-Version is now 2.2.
|
||||
* Added one new field: ``License-File``
|
||||
* Updated the documentation of two fields: ``License`` and ``Classifiers``
|
||||
* Updated the documentation of two fields: ``License`` and ``Classifier``
|
||||
|
||||
|
||||
Backwards Compatibility
|
||||
=======================
|
||||
|
||||
The reuse of the `License` field means that we keep backward compatibility. The
|
||||
specification of the `License-File` field is only writing down the practices
|
||||
of the `wheels` and `setuptools` tools and is backward compatible with their
|
||||
The reuse of the ``License`` field means that we keep backward compatibility. The
|
||||
specification of the ``License-File`` field is only writing down the practices
|
||||
of the ``wheel`` and ``setuptools`` tools and is backward compatible with their
|
||||
support for that field.
|
||||
|
||||
The "soft" validation of the `License` field when it does not contain a valid
|
||||
license expression and when legacy license-related `Classifiers` are used means
|
||||
that we can gently prepare users for a possible strict and incompatible
|
||||
validation of these fields in the future.
|
||||
The "soft" validation of the ``License`` field when it does not contain a valid
|
||||
license expression and when the ``Classifier`` field is used with legacy
|
||||
license-related classifiers means that we can gently prepare users for a
|
||||
possible strict and incompatible validation of these fields in the future.
|
||||
|
||||
|
||||
Security Implications
|
||||
|
|
@ -372,7 +372,7 @@ a plain string and the License-File(s) are file paths. None of them introduces
|
|||
any new security concern.
|
||||
|
||||
|
||||
How to Teach Users to use License Expressions
|
||||
How to Teach Users to Use License Expressions
|
||||
=============================================
|
||||
|
||||
The simple cases are simple: a single license id is a valid license expression
|
||||
|
|
@ -381,7 +381,7 @@ and a large majority of packages use a single license.
|
|||
The plan to teach users of packaging tools how to use the license with a valid
|
||||
license expressions is to have tool issue warning messages when they detect an
|
||||
incorrect license expressions or when a license-related classifier is used in
|
||||
the Classifier field.
|
||||
the ``Classifier`` field.
|
||||
|
||||
With a warning message that does not terminate processing, publishing tools will
|
||||
gently teach users on how to provide correct license expressions over time.
|
||||
|
|
@ -389,40 +389,41 @@ gently teach users on how to provide correct license expressions over time.
|
|||
Tools may also help with the conversion and suggest a license expression in some
|
||||
cases:
|
||||
|
||||
1. The section `Mapping legacy Classifiers to new License expressions` provides
|
||||
1. The section `Mapping Legacy Classifiers to New License expressions` provides
|
||||
tools authors with guidelines on how to suggest a license expression from
|
||||
legacy Classifiers.
|
||||
legacy classifiers.
|
||||
|
||||
2. Tools may also be able to infer and suggest how to update an existing
|
||||
incorrect `License` value and convert that to a correct license expression.
|
||||
For instance a tool may suggest to correct a `License` field from `Apache2`
|
||||
incorrect ``License`` value and convert that to a correct license expression.
|
||||
For instance a tool may suggest to correct a ``License`` field from ``Apache2``
|
||||
(which is not a valid license expression as defined in this PEP) to
|
||||
`Apache-2.0` (which is a valid license expression using an SPDX license id as
|
||||
``Apache-2.0`` (which is a valid license expression using an SPDX license id as
|
||||
defined in this PEP).
|
||||
|
||||
|
||||
Reference Implementation
|
||||
========================
|
||||
|
||||
Tools will need to support parsing and validating `License Expressions` in the
|
||||
`License` field.
|
||||
Tools will need to support parsing and validating license expressions in the
|
||||
``License`` field.
|
||||
|
||||
The `license-expression` library [#licexp]_ is a reference Python implementation
|
||||
for a library that handles `License Expressions` including parsing, validating
|
||||
and formatting `License Expressions` using flexible lists of license symbols
|
||||
(including SPDX license ids and any extra ids referenced here). It is licensed
|
||||
under the Apache-2.0 license and is used in a few projects such as the SPDX
|
||||
Python tools [#spdxpy]_, the ScanCode toolkit [#scancodetk]_ and the Free
|
||||
Software Foundation Europe (FSFE) Reuse project [#reuse]_.
|
||||
The ``license-expression`` library [#licexp]_ is a reference Python
|
||||
implementation for a library that handles license expressions including
|
||||
parsing, validating and formatting license expressions using flexible lists of
|
||||
license symbols (including SPDX license identifiers and any extra identifiers
|
||||
referenced here). It is licensed under the Apache-2.0 license and is used in a
|
||||
few projects such as the SPDX Python tools [#spdxpy]_, the ScanCode toolkit
|
||||
[#scancodetk]_ and the Free Software Foundation Europe (FSFE) Reuse project
|
||||
[#reuse]_.
|
||||
|
||||
|
||||
Rejected ideas
|
||||
==============
|
||||
|
||||
1. use a new `License Expression` field and deprecate the `License` field.
|
||||
1. use a new ``License-Expression`` field and deprecate the ``License`` field.
|
||||
|
||||
Adding a new field would introduce backward incompatible changes when the
|
||||
`License` field would be retired later and require to have a more complex
|
||||
``License`` field would be retired later and require to have a more complex
|
||||
validation. The use of such a field would further introduce a new concept that
|
||||
is not seen anywhere else in any other package metadata (e.g. a new a field only
|
||||
for license expression) and possibly be a source of confusion. Also, users are
|
||||
|
|
@ -440,9 +441,9 @@ are documented by adding an additional nesting level.
|
|||
A mapping would be needed as you cannot guarantee that all expressions (e.g. a
|
||||
GPL with an exception may be in a single file) or all the license keys have a
|
||||
single license file and that any expression does not have more than one. (e.g.
|
||||
an Apache license LICENSE and its NOTICE file for instance are tow distinct
|
||||
file). Yet in most cases, there is a simpler `one license`, `one or more
|
||||
license files`. In the rarer and more complex cases where there are many
|
||||
an Apache license ``LICENSE`` and its ``NOTICE`` file for instance are tow
|
||||
distinct file). Yet in most cases, there is a simpler `one license`, `one or
|
||||
more license files`. In the rarer and more complex cases where there are many
|
||||
licenses involved you can still use the proposed conventions at the cost of a
|
||||
slight loss of clarity by not specifying which text file is for which license
|
||||
id, but you are not forcing the more complex data model (e.g. a mapping) on
|
||||
|
|
@ -459,30 +460,31 @@ string.
|
|||
3. mapping licenses to specific source files and/or directories of source files
|
||||
(or vice versa).
|
||||
|
||||
File-level notices is not considered as part of the scope of this PEP and the
|
||||
existing the `SPDX-License-Identifier` [#spdxids]_ convention can be used and
|
||||
File-level notices are not considered as part of the scope of this PEP and the
|
||||
existing the ``SPDX-License-Identifier`` [#spdxids]_ convention can be used and
|
||||
may not need further specification as a PEP.
|
||||
|
||||
|
||||
Appendix 1. License Expression example
|
||||
======================================
|
||||
|
||||
The current version of `setuptools` metadata [#setuptools5030]_ does not use the
|
||||
`License` field. It uses instead these license-related information::
|
||||
The current version of ``setuptools`` metadata [#setuptools5030]_ does not use
|
||||
the ``License`` field. It uses instead this license-related information in
|
||||
``setup.cfg``::
|
||||
|
||||
license_file = LICENSE
|
||||
classifiers =
|
||||
License :: OSI Approved :: MIT License
|
||||
|
||||
The simplest migration to this PEP would consist in using this instead::
|
||||
The simplest migration to this PEP would consist of using this instead::
|
||||
|
||||
license = MIT
|
||||
license_files =
|
||||
LICENSE
|
||||
|
||||
Another possibility would be to include the licenses of the third-party packages
|
||||
bundled in that are vendored in the `setuptools/_vendor/` and
|
||||
`pkg_resources/_vendor` directories::
|
||||
bundled in that are vendored in the ``setuptools/_vendor/`` and
|
||||
``pkg_resources/_vendor`` directories::
|
||||
|
||||
appdirs==1.4.3
|
||||
packaging==20.4
|
||||
|
|
@ -496,7 +498,7 @@ These are using these license expressions::
|
|||
pyparsing: MIT
|
||||
ordered-set: MIT
|
||||
|
||||
Therefore, a comprehensive license documentation covering both setuptools proper
|
||||
Therefore, a comprehensive license documentation covering both ``setuptools`` proper
|
||||
and its vendored packages could contain these metadata, combining all the
|
||||
license expressions in one expression::
|
||||
|
||||
|
|
@ -505,9 +507,9 @@ license expressions in one expression::
|
|||
LICENSE.MIT
|
||||
LICENSE.packaging
|
||||
|
||||
Here we would assume that the `LICENSE.MIT` file contains the text of the MIT
|
||||
license and the copyrights used by `setuptools`, `appdirs`, `pyparsing` and
|
||||
`ordered-set`, and that the `LICENSE.packaging` file contains the texts of the
|
||||
Here we would assume that the ``LICENSE.MIT`` file contains the text of the MIT
|
||||
license and the copyrights used by ``setuptools``, ``appdirs``, ``pyparsing`` and
|
||||
``ordered-set``, and that the ``LICENSE.packaging`` file contains the texts of the
|
||||
Apache and BSD license, its copyrights and its license choice notice [#packlic]_.
|
||||
|
||||
|
||||
|
|
@ -521,12 +523,12 @@ licenses today:
|
|||
In Core metadata
|
||||
----------------
|
||||
|
||||
There are two overlapping Core metadata fields to document a license: the
|
||||
license-related `Classifiers` strings [#classif]_ prefixed with `License::` and
|
||||
the `License` field as free text [#licfield]_.
|
||||
There are two overlapping core metadata fields to document a license: the
|
||||
license-related ``Classifier`` strings [#classif]_ prefixed with ``License ::`` and
|
||||
the ``License`` field as free text [#licfield]_.
|
||||
|
||||
|
||||
The Core metadata documentation `License` field documentation is currently::
|
||||
The core metadata documentation ``License`` field documentation is currently::
|
||||
|
||||
License (optional)
|
||||
::::::::::::::::::
|
||||
|
|
@ -546,48 +548,49 @@ The Core metadata documentation `License` field documentation is currently::
|
|||
License: GPL version 3, excluding DRM provisions
|
||||
|
||||
Even though there are two fields, it is at times difficult to convey anything
|
||||
but simpler licensing. For instance some `Classifiers` lack accuracy (GPL
|
||||
but simpler licensing. For instance some classifiers lack accuracy (GPL
|
||||
without a version) and when you have multiple License-related classifiers it is
|
||||
not clear if this is a choice or all these apply and which ones. Furthermore,
|
||||
the list of available license-related `Classifiers` is often out-of-date.
|
||||
the list of available license-related classifiers is often out-of-date.
|
||||
|
||||
|
||||
In the PyPA sample project
|
||||
--------------------------
|
||||
In the PyPA ``sampleproject``
|
||||
-----------------------------
|
||||
|
||||
The latest PyPA sample project recommends only to use Classifiers in setup.py
|
||||
and does not list the `license` field in its example `setup.py` [#samplesetup]_.
|
||||
The latest PyPA ``sampleproject`` recommends only to use classifiers in
|
||||
``setup.py`` and does not list the ``license`` field in its example
|
||||
``setup.py`` [#samplesetup]_.
|
||||
|
||||
|
||||
The License files in wheels and setuptools
|
||||
The License Files in wheels and setuptools
|
||||
------------------------------------------
|
||||
|
||||
Beyond a license code or qualifier, license text files are documented and
|
||||
included in a built package either implicitly or explicitly and this is another
|
||||
possible source of confusion:
|
||||
|
||||
- In wheels [#wheels]_ license files are automatically added to the `.dist-info`
|
||||
- In wheels [#wheels]_ license files are automatically added to the ``.dist-info``
|
||||
directory if they match one of a few common license file name patterns (such
|
||||
as LICENSE*, COPYING*). Alternatively a package author can specify a list of
|
||||
license files paths to include in the built wheel using in the
|
||||
`license_files` field in the `[metadata]` section of the project's
|
||||
`setup.cfg`. Previously this was a (singular) `license_file` file attribute
|
||||
``license_files`` field in the ``[metadata]`` section of the project's
|
||||
``setup.cfg``. Previously this was a (singular) ``license_file`` file attribute
|
||||
that is now deprecated but is still in common use. See [#pipsetup]_ for
|
||||
instance.
|
||||
|
||||
- In `setuptools` [#setuptoolssdist]_, a `license_file` attribute is used to add
|
||||
- In ``setuptools`` [#setuptoolssdist]_, a ``license_file`` attribute is used to add
|
||||
a single license file to a source distribution. This singular version is
|
||||
still honored by `wheels` for backward compatibility.
|
||||
still honored by ``wheels`` for backward compatibility.
|
||||
|
||||
- Using a LICENSE.txt file is encouraged in the packaging guide [#packaging]_
|
||||
paired with a `MANIFEST.in` entry to ensure that the license file is included
|
||||
paired with a ``MANIFEST.in`` entry to ensure that the license file is included
|
||||
in a built source distribution (sdist).
|
||||
|
||||
Note: the License-File field proposed in this PEP already exists in `wheel` and
|
||||
`setuptools` with the same behaviour as explained above. This PEP is only
|
||||
recognizing and documenting the existing practice as used in `wheels` (with the
|
||||
`license_file` and `license_files` `setup.cfg` `[metadata]` entries) and in
|
||||
`setuptools` `license_file` `setup()` argument.
|
||||
Note: the License-File field proposed in this PEP already exists in ``wheel`` and
|
||||
``setuptools`` with the same behaviour as explained above. This PEP is only
|
||||
recognizing and documenting the existing practice as used in ``wheel`` (with the
|
||||
``license_file`` and ``license_files`` ``setup.cfg`` ``[metadata]`` entries) and in
|
||||
``setuptools`` ``license_file`` ``setup()`` argument.
|
||||
|
||||
|
||||
In Python code files
|
||||
|
|
@ -595,29 +598,29 @@ In Python code files
|
|||
|
||||
(Note: Documenting licenses in source code is not in the scope of this PEP)
|
||||
|
||||
Beside using comments and/or `SPDX-License-Identifier` conventions, the license
|
||||
Beside using comments and/or ``SPDX-License-Identifier`` conventions, the license
|
||||
is sometimes documented in Python code file using `dunder` variables typically
|
||||
named after one of the lower cased Core metadata field such as `__license__`
|
||||
named after one of the lower cased Core metadata field such as ``__license__``
|
||||
[#pycode]_.
|
||||
|
||||
This convention (dunder global variables) is recognized by the built-in `help()`
|
||||
function and the standard `pydoc` module. The dunder variable(s) will show up in
|
||||
the `help()` DATA section for a module.
|
||||
This convention (dunder global variables) is recognized by the built-in ``help()``
|
||||
function and the standard ``pydoc`` module. The dunder variable(s) will show up in
|
||||
the ``help()`` DATA section for a module.
|
||||
|
||||
|
||||
In some other Python packaging tools
|
||||
------------------------------------
|
||||
|
||||
- `Conda package manifest` [#conda]_ has support for `license` and`license_file`
|
||||
fields as well as a `license_family` license grouping field.
|
||||
- `Conda package manifest` [#conda]_ has support for ``license`` and ``license_file``
|
||||
fields as well as a ``license_family`` license grouping field.
|
||||
|
||||
- `flit` [#flit]_ recommends to use Classifiers instead of License (as per the
|
||||
- ``flit`` [#flit]_ recommends to use classifiers instead of License (as per the
|
||||
current metadata spec).
|
||||
|
||||
- `pbr` [#pbr]_ uses similar data as setuptools but always stored setup.cfg.
|
||||
- ``pbr`` [#pbr]_ uses similar data as setuptools but always stored setup.cfg.
|
||||
|
||||
- `poetry` [#poetry]_ specifies the use of the `license ` field in
|
||||
`pyproject.toml` with SPDX license ids.
|
||||
- ``poetry`` [#poetry]_ specifies the use of the ``license`` field in
|
||||
``pyproject.toml`` with SPDX license identifiers.
|
||||
|
||||
|
||||
Appendix 3. Surveying how other package formats document licenses
|
||||
|
|
@ -634,36 +637,40 @@ globally once in a shared documentation directory (e.g. /usr/share/doc).
|
|||
- Debian document package licenses with machine readable copyright files
|
||||
[#dep5]_. This specification defines its own license expression syntax that is
|
||||
very similar to the SDPX syntax and use its own list of license identifiers
|
||||
for common licenses also closely related to SPDX ids.
|
||||
for common licenses also closely related to SPDX identifiers.
|
||||
|
||||
- Fedora RPM packages [#fedora]_ specifies how to include `License Texts`
|
||||
[#fedoratext]_ and how use a `License` field [#fedoralic]_ that must be filled
|
||||
- Fedora RPM packages [#fedora]_ specifies how to include ``License Texts``
|
||||
[#fedoratext]_ and how use a ``License`` field [#fedoralic]_ that must be filled
|
||||
with an appropriate license Short License identifier(s) from an extensive list
|
||||
of "Good Licenses" identifiers [#fedoralist]_. Fedora also defines ist own
|
||||
license expression syntax very similar to the SDPX syntax.
|
||||
|
||||
- OpenSuse RPMs packages [#opensuse]_ use SPDX license expressions with a either
|
||||
SPDX license ids and a list of extra license ids [#opensuselist]_.
|
||||
- OpenSuse RPMs packages [#opensuse]_ use SPDX license expressions with a
|
||||
either SPDX license identifiers and a list of extra license identifiers
|
||||
[#opensuselist]_.
|
||||
|
||||
- Gentoo ebuild use a LICENSE variable [#gentoo]_. This field is specified in
|
||||
GLEP-0023 [#glep23]_ and in the Gentoo development manual [#gentoodev]_.
|
||||
- Gentoo ebuild use a ``LICENSE`` variable [#gentoo]_. This field is specified
|
||||
in GLEP-0023 [#glep23]_ and in the Gentoo development manual [#gentoodev]_.
|
||||
Gentoo also defines a license expressions syntax and a list of allowed
|
||||
licenses. The expression syntax is rather different from SPDX.
|
||||
|
||||
- FreeBSD package Makefile [#freebsd]_ provide a LICENSE and a LICENSE_FILE
|
||||
field with a list of custom license symbols. For non-standard licenses,
|
||||
FreeBSD recommend to use LICENSE=UNKNOWN and add LICENSE_NAME and LICENSE_TEXT
|
||||
fields, as well as sophisticated LICENSE_PERMS to qualify the license
|
||||
permissions and LICENSE_GROUPS to document a license grouping. The
|
||||
LICENSE_COMB allows to document more than one license and how they apply
|
||||
together, forming a custom license expression syntax. FreeBSD also recommends
|
||||
the use of SPDX-License-Identifier in source code files.
|
||||
- FreeBSD package Makefile [#freebsd]_ provide a ``LICENSE`` and a
|
||||
``LICENSE_FILE`` field with a list of custom license symbols. For
|
||||
non-standard licenses, FreeBSD recommend to use ``LICENSE=UNKNOWN`` and add
|
||||
``LICENSE_NAME`` and ``LICENSE_TEXT`` fields, as well as sophisticated
|
||||
``LICENSE_PERMS`` to qualify the license permissions and ``LICENSE_GROUPS``
|
||||
to document a license grouping. The ``LICENSE_COMB`` allows to document more
|
||||
than one license and how they apply together, forming a custom license
|
||||
expression syntax. FreeBSD also recommends the use of
|
||||
``SPDX-License-Identifier`` in source code files.
|
||||
|
||||
- Archlinux PKGBUILD [#archinux]_ define its own license identifiers
|
||||
[#archlinuxlist]_. 'unknown' can be used if the license is not defined.
|
||||
[#archlinuxlist]_. The value ``'unknown'`` can be used if the license is not
|
||||
defined.
|
||||
|
||||
- OpenWRT ipk packages [#openwrt]_ use the `PKG_LICENSE` and `PKG_LICENSE_FILES`
|
||||
variables and recommend the use of SPDX License ids.
|
||||
- OpenWRT ipk packages [#openwrt]_ use the ``PKG_LICENSE`` and
|
||||
``PKG_LICENSE_FILES`` variables and recommend the use of SPDX License
|
||||
identifiers.
|
||||
|
||||
- NixOS uses SPDX identifiers [#nixos]_ and some extras license identifiers in
|
||||
its license field.
|
||||
|
|
@ -684,27 +691,28 @@ License in Language and Application packages
|
|||
mandatory and the content of each field is not specified.
|
||||
|
||||
- JavaScript npm package.json [#npm]_ use a single license field with SPDX
|
||||
license expression or the `UNLICENSED` id if no license is specified.
|
||||
license expression or the ``UNLICENSED`` id if no license is specified.
|
||||
A license file can be referenced as an alternative using "SEE LICENSE IN
|
||||
<filename>" in the single `license` field.
|
||||
<filename>" in the single ``license`` field.
|
||||
|
||||
- Rubygems gemspec [#gem]_ specifies either a singular license string for a list
|
||||
of licenses strings. The relationship between multiple licenses in a list is
|
||||
not specified. They recommend using SPDX license ids.
|
||||
not specified. They recommend using SPDX license identifiers.
|
||||
|
||||
- CPAN Perl modules [#perl]_ use a single license field which is either a single
|
||||
string or a list of strings. The relationship between the licenses in a list
|
||||
is not specified. There is a list of support own license identifiers plus
|
||||
these generic ids: open_source, restricted, unrestricted, unknown.
|
||||
these generic identifiers: ``open_source``, ``restricted``, ``unrestricted``,
|
||||
``unknown``.
|
||||
|
||||
- Rust Cargo [#cargo]_ specifies the use of an SPDX license expression (v2.1) in
|
||||
the `license` field. It also supports an alternative expression syntax using
|
||||
slash-separated SPDX license ids. There is also a `license_file` field. The
|
||||
crates.io package registry [#cratesio]_ requires that either `license` or
|
||||
`license_file` fields are set when you upload a package.
|
||||
the ``license`` field. It also supports an alternative expression syntax using
|
||||
slash-separated SPDX license identifiers. There is also a ``license_file``
|
||||
field. The crates.io package registry [#cratesio]_ requires that either
|
||||
``license`` or ``license_file`` fields are set when you upload a package.
|
||||
|
||||
- PHP Composer composer.json [#composer]_ uses a `license` field with an SPDX
|
||||
License id or "proprietary". The `license` field is either a single string
|
||||
- PHP Composer composer.json [#composer]_ uses a ``license`` field with an SPDX
|
||||
License id or "proprietary". The ``license`` field is either a single string
|
||||
that can use something which resemble the SPDX license expression syntax with
|
||||
"and" and "or" keywords; or this is a list of strings if there is a choice of
|
||||
licenses (aka. a "disjunctive" choice of license).
|
||||
|
|
@ -715,70 +723,72 @@ License in Language and Application packages
|
|||
accepts license expressions that are `approved by the Open Source Initiative
|
||||
or the Free Software Foundation.`
|
||||
|
||||
- Go language modules `go.mod` have no provision for any metadata beyond
|
||||
- Go language modules ``go.mod`` have no provision for any metadata beyond
|
||||
dependencies. Licensing information is left for code authors and other
|
||||
community package managers to document.
|
||||
|
||||
- Dart/Flutter spec [#flutter]_ recommends to use a single LICENSE file that
|
||||
should contain all the license texts each separated by a line with 80
|
||||
- Dart/Flutter spec [#flutter]_ recommends to use a single ``LICENSE`` file
|
||||
that should contain all the license texts each separated by a line with 80
|
||||
hyphens.
|
||||
|
||||
- JavaScript Bower [#bower]_ `license` field is either a single string or a list
|
||||
- JavaScript Bower [#bower]_ ``license`` field is either a single string or a list
|
||||
of strings using either SPDX license identifiers, a path or a URL to a
|
||||
license file.
|
||||
|
||||
- Cocoapods podspec [#cocoapod]_ `license` field is either a single string or a
|
||||
- Cocoapods podspec [#cocoapod]_ ``license`` field is either a single string or a
|
||||
mapping with attributes of type, file and text keys. This is mandatory unless
|
||||
there is a LICENSE or LICENCE file provided.
|
||||
|
||||
- Haskell Cabal [#cabal]_ accepts an SPDX license expression since version 2.2.
|
||||
The version of the SPDX license list used is a function of the `cabal` version.
|
||||
The version of the SPDX license list used is a function of the ``cabal`` version.
|
||||
The specification also provides a mapping between pre-SPDX Legacy license
|
||||
Identifiers and SPDX ids. Cabal also specifies a `license-file(s)` field that
|
||||
lists license files that will be installed with the package.
|
||||
Identifiers and SPDX identifiers. Cabal also specifies a ``license-file(s)``
|
||||
field that lists license files that will be installed with the package.
|
||||
|
||||
- Erlang/Elixir mix/hex package [#mix]_ specifies a `licenses` field as a
|
||||
required list of license strings and recommends to use SPDX License ids.
|
||||
- Erlang/Elixir mix/hex package [#mix]_ specifies a ``licenses`` field as a
|
||||
required list of license strings and recommends to use SPDX License
|
||||
identifiers.
|
||||
|
||||
- D lang dub package [#dub]_ defines its own list of license identifiers and
|
||||
its own license expression syntax and both are similar to SPDX the conventions.
|
||||
|
||||
- R Package DESCRIPTION [#cran]_ defines its own sophisticated license
|
||||
expression syntax and list of licenses ids. R has a unique way to support
|
||||
specifiers for license versions such as `LGPL (>= 2.0, < 3)` in its license
|
||||
expression syntax.
|
||||
expression syntax and list of licenses identifiers. R has a unique way to
|
||||
support specifiers for license versions such as ``LGPL (>= 2.0, < 3)`` in its
|
||||
license expression syntax.
|
||||
|
||||
|
||||
Conventions used by other ecosystems
|
||||
------------------------------------
|
||||
|
||||
- `SPDX-License-Identifier` [#spdxids]_ is a simple convention to document the
|
||||
- ``SPDX-License-Identifier`` [#spdxids]_ is a simple convention to document the
|
||||
license inside a code file.
|
||||
|
||||
- The Free Software Foundation (FSF) promotes using SPDX license ids for clarity
|
||||
in the GPL and other versioned free software licenses [#gnu]_ [#fsf]_.
|
||||
- The Free Software Foundation (FSF) promotes using SPDX license identifiers
|
||||
for clarity in the GPL and other versioned free software licenses [#gnu]_
|
||||
[#fsf]_.
|
||||
|
||||
- The Free Software Foundation Europe (FSFE) REUSE project [#reuse]_ promotes
|
||||
using `SPDX-License-Identifier`.
|
||||
using ``SPDX-License-Identifier``.
|
||||
|
||||
- The Linux kernel uses `SPDX-License-Identifier` and parts of the FSFE REUSE
|
||||
- The Linux kernel uses ``SPDX-License-Identifier`` and parts of the FSFE REUSE
|
||||
conventions to document its licenses [#linux]_.
|
||||
|
||||
- U-Boot spearheaded using `SPDX-License-Identifier` in code and now follows the
|
||||
- U-Boot spearheaded using ``SPDX-License-Identifier`` in code and now follows the
|
||||
Linux ways [#uboot]_.
|
||||
|
||||
- The Apache Software Foundation projects use RDF DOAP [#apache]_ with a single
|
||||
license field pointing to SPDX license ids.
|
||||
license field pointing to SPDX license identifiers.
|
||||
|
||||
- The Eclipse Foundation promotes using `SPDX-license-Identifiers` [#eclipse]_
|
||||
- The Eclipse Foundation promotes using ``SPDX-license-Identifiers`` [#eclipse]_
|
||||
|
||||
- The ClearlyDefined project [#cd]_ promotes using SPDX license ids and
|
||||
- The ClearlyDefined project [#cd]_ promotes using SPDX license identifiers and
|
||||
expressions to improve license clarity.
|
||||
|
||||
- The Android Open Source Project [#android]_ use MODULE_LICENSE_XXX empty tag
|
||||
files where XXX is a license code such as BSD , APACHE, GPL, etc. And
|
||||
side-by-side with this MODULE_LICENSE file there is a NOTICE file that
|
||||
contains license and notices texts.
|
||||
- The Android Open Source Project [#android]_ use ``MODULE_LICENSE_XXX`` empty
|
||||
tag files where ``XXX`` is a license code such as BSD, APACHE, GPL, etc. And
|
||||
side-by-side with this ``MODULE_LICENSE`` file there is a ``NOTICE`` file
|
||||
that contains license and notices texts.
|
||||
|
||||
|
||||
References
|
||||
|
|
@ -866,7 +876,7 @@ Copyright
|
|||
=========
|
||||
|
||||
This document is placed in the public domain or under the CC0-1.0-Universal
|
||||
license [#cc0]_, whichever is more permissive.
|
||||
license [#cc0]_, whichever is more permissive.
|
||||
|
||||
|
||||
Acknowledgements
|
||||
|
|
|
|||
Loading…
Reference in New Issue