From 4bd35776101a10e559b9ff1bd71402ab43b0c680 Mon Sep 17 00:00:00 2001 From: Dustin Ingram Date: Wed, 30 Sep 2020 09:13:58 -0500 Subject: [PATCH] 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 Co-authored-by: Jelle Zijlstra --- pep-0639.rst | 418 ++++++++++++++++++++++++++------------------------- 1 file changed, 214 insertions(+), 204 deletions(-) diff --git a/pep-0639.rst b/pep-0639.rst index 238dd6d61..4153a411d 100644 --- a/pep-0639.rst +++ b/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 - " in the single `license` field. + " 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