From 9b90b35477941117d6f59add7cd6113c156d6ccc Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 30 Jun 2022 22:04:09 -0500 Subject: [PATCH] PEP 639: Rename licence_files license directory to just licenses --- pep-0639.rst | 54 +++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/pep-0639.rst b/pep-0639.rst index 1b846585450..c67f7aaeb10 100644 --- a/pep-0639.rst +++ b/pep-0639.rst @@ -322,8 +322,8 @@ for the purposes of this PEP (``Syn:``). and the root directory that their paths, as recorded under the ``License-File`` core metadata fields, are relative to. Defined here to be the project root directory for source trees and source - distributions, and a subdirectory named ``license_files`` of the directory - containing the core metadata (i.e., the ``.dist-info/license_files`` + distributions, and a subdirectory named ``licenses`` of the directory + containing the core metadata (i.e., the ``.dist-info/licenses`` directory) for built distributions and installed projects. **Tool** *(Sub: Packaging Tool, Build Tool, Install Tool, Publishing Tool)* @@ -756,17 +756,17 @@ each format, per the :ref:`639-spec-field-license-file` section. The `wheel specification `__ will be updated to reflect that if the ``Metadata-Version`` is ``2.4`` or greater and one or more ``License-File`` fields is specified, the ``.dist-info`` directory MUST - contain a ``license_files`` subdirectory which MUST contain the files listed + contain a ``licenses`` subdirectory, which MUST contain the files listed in the ``License-File`` fields in the ``METADATA`` file at their respective - paths relative to the ``license_files`` directory. + paths relative to the ``licenses`` directory. **Installed projects** The `Recording Installed Projects specification `__ will be updated to reflect that if the ``Metadata-Version`` is ``2.4`` or greater and one or more ``License-File`` fields is specified, the ``.dist-info`` - directory MUST contain a ``license_files`` subdirectory which MUST contain + directory MUST contain a ``licenses`` subdirectory which MUST contain the files listed in the ``License-File`` fields in the ``METADATA`` file - at their respective paths relative to the ``license_files`` directory, + at their respective paths relative to the ``licenses`` directory, and that any files in this directory MUST be copied from wheels by install tools. @@ -934,7 +934,7 @@ as well as the default behavior, and allows other tools to make use of them, while only having an effect once users and tools expressly adopt it. Due to requiring license files not be flattened into ``.dist-info`` and -specifying that they should be placed in a dedicated ``license_files`` subdir, +specifying that they should be placed in a dedicated ``licenses`` subdir, wheels produced following this change will have differently-located licenses relative to those produced via the previous unspecified, installer-specific behavior, but as until this PEP there was no way of @@ -1712,7 +1712,7 @@ 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 ``license_files`` +the following proposal rooting the license files under a ``licenses`` subdirectory eliminates both collisions and the clutter problem entirely. @@ -1759,7 +1759,7 @@ 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 -relative to a ``license_files`` subdirectory of ``.dist-info``. This is simple +relative to a ``licenses`` subdirectory of ``.dist-info``. This is simple to implement and solves all the problems noted here, without clear significant drawbacks relative to other more complex options. @@ -1783,7 +1783,7 @@ Therefore, the latter has been incorporated into current drafts of this PEP. Add new ``licenses`` category to wheel '''''''''''''''''''''''''''''''''''''' -Instead of defining a root license directory (``license_files``) inside +Instead of defining a root license directory (``licenses``) inside 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, @@ -1819,16 +1819,18 @@ and decided that would avoid name clashes. Therefore, to keep this PEP in scope, the current approach was retained. -Name the subdirectory ``licenses`` -'''''''''''''''''''''''''''''''''' +Name the subdirectory ``license_files`` +''''''''''''''''''''''''''''''''''''''' Both ``licenses`` and ``license_files`` have been suggested as potential names for the root license directory inside ``.dist-info`` of wheels and -installed projects. The former is slightly shorter, but the latter is -more clear and unambiguous regarding its contents, and is consistent with -the name of the core metadata field (``License-File``) and the -project source metadata key (``license-files``). -Therefore, the latter was chosen instead. +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``) +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.). Other ideas @@ -2067,7 +2069,7 @@ The output core metadata for the distribution packages would then be: License-File: LICENSE The ``LICENSE`` file would be stored at ``/setuptools-${VERSION}/LICENSE`` -in the sdist and ``/setuptools-${VERSION}.dist-info/license_files/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. @@ -2189,20 +2191,20 @@ In the built wheel, with ``/`` being the root of the archive and .. code-block:: shell - /setuptools-${VERSION}.dist-info/license_files/LICENSE - /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE - /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE - /setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD + /setuptools-${VERSION}.dist-info/licenses/LICENSE + /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE + /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE + /setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD Finally, in the installed project, with ``site-packages`` being the site dir and ``{version}`` as the previous, the license files would be installed to: .. code-block:: shell - site-packages/setuptools-${VERSION}.dist-info/license_files/LICENSE - site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE - site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.APACHE - site-packages/setuptools-${VERSION}.dist-info/license_files/setuptools/_vendor/packaging/LICENSE.BSD + site-packages/setuptools-${VERSION}.dist-info/licenses/LICENSE + site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE + site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.APACHE + site-packages/setuptools-${VERSION}.dist-info/licenses/setuptools/_vendor/packaging/LICENSE.BSD .. _639-example-conversion: