diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst index a4ff2b35c..f9d2d74c4 100644 --- a/source/guides/hosting-your-own-index.rst +++ b/source/guides/hosting-your-own-index.rst @@ -35,8 +35,7 @@ all repositories using a valid HTTPS setup. =================== The directory layout is fairly simple, within a root directory you need to -create a directory for each project. This directory should be the normalized -name (as defined by :pep:`503`) of the project. Within each of these directories +create a directory for each project. This directory should be the :ref:`normalized name ` of the project. Within each of these directories simply place each of the downloadable files. If you have the projects "Foo" (with the versions 1.0 and 2.0) and "bar" (with the version 0.1) You should end up with a structure that looks like:: diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst index 1f4bd89fa..277792658 100644 --- a/source/specifications/binary-distribution-format.rst +++ b/source/specifications/binary-distribution-format.rst @@ -161,7 +161,7 @@ this character cannot appear within any component. This is handled as follows: - In distribution names, any run of ``-_.`` characters (HYPHEN-MINUS, LOW LINE and FULL STOP) should be replaced with ``_`` (LOW LINE), and uppercase characters should be replaced with corresponding lowercase ones. This is - equivalent to :pep:`503` normalisation followed by replacing ``-`` with ``_``. + equivalent to regular :ref:`name normalization ` followed by replacing ``-`` with ``_``. Tools consuming wheels must be prepared to accept ``.`` (FULL STOP) and uppercase letters, however, as these were allowed by an earlier version of this specification. diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index aa0d44c8a..644380962 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -84,13 +84,7 @@ Example:: Name: BeagleVote -To normalize a distribution name for comparison purposes, it should be -lowercased with all runs of the characters ``.``, ``-``, or ``_`` replaced with -a single ``-`` character. This can be done using the following snippet of code -(as specified in :pep:`503`):: - - re.sub(r"[-_.]+", "-", name).lower() - +For comparison purposes, the names should be :ref:`normalized ` before comparing. .. _core-metadata-version: diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst index 23e73d065..83fac600d 100644 --- a/source/specifications/declaring-project-metadata.rst +++ b/source/specifications/declaring-project-metadata.rst @@ -70,7 +70,7 @@ The complete list of keys allowed in the ``[project]`` table are: The name of the project. -Tools SHOULD normalize this name, as specified by :pep:`503`, as soon +Tools SHOULD :ref:`normalize ` this name, as soon as it is read for internal consistency. .. code-block:: toml diff --git a/source/specifications/index.rst b/source/specifications/index.rst index 6a282b243..3265ce56f 100644 --- a/source/specifications/index.rst +++ b/source/specifications/index.rst @@ -15,6 +15,7 @@ Package Distribution Metadata .. toctree:: :maxdepth: 1 + name-normalization core-metadata version-specifiers dependency-specifiers diff --git a/source/specifications/name-normalization.rst b/source/specifications/name-normalization.rst new file mode 100644 index 000000000..4fd885afc --- /dev/null +++ b/source/specifications/name-normalization.rst @@ -0,0 +1,39 @@ +.. _name-normalization: + +========================== +Package name normalization +========================== + +Project names are "normalized" for use in various contexts. This document describes how project names should be normalized. + +Valid non-normalized names +-------------------------- + +A valid name consists only of ASCII letters and numbers, period, +underscore and hyphen. It must start and end with a letter or number. +This means that valid project names are limited to those which match the +following regex (run with ``re.IGNORECASE``):: + + ^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$ + +Normalization +------------- + +The name should be lowercased with all runs of the characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This can be implemented in Python with the re module: + +.. code-block:: python + + import re + + def normalize(name): + return re.sub(r"[-_.]+", "-", name).lower() + +This means that the following names are all equivalent: + +* ``friendly-bard`` (normalized form) +* ``Friendly-Bard`` +* ``FRIENDLY-BARD`` +* ``friendly.bard`` +* ``friendly_bard`` +* ``friendly--bard`` +* ``FrIeNdLy-._.-bArD`` (a _terrible_ way to write a name, but it is valid) diff --git a/source/specifications/recording-installed-packages.rst b/source/specifications/recording-installed-packages.rst index 9085807f3..6a01544d5 100644 --- a/source/specifications/recording-installed-packages.rst +++ b/source/specifications/recording-installed-packages.rst @@ -40,7 +40,7 @@ packages (commonly, the ``site-packages`` directory). This directory is named as ``{name}-{version}.dist-info``, with ``name`` and ``version`` fields corresponding to :ref:`core-metadata`. Both fields must be -normalized (see :pep:`PEP 503 <503#normalized-names>` and +normalized (see :ref:`name-normalization` and :pep:`PEP 440 <440#normalization>` for the definition of normalization for each field respectively), and replace dash (``-``) characters with underscore (``_``) characters, so the ``.dist-info`` directory always has