Merge pull request #1190 from pradyunsg/name-normalization

Author: pradyunsg

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 <name-normalization>` 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::

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 <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.

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 <name-normalization>` before comparing.
 
 .. _core-metadata-version:
 

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 <name-normalization>` this name, as soon
 as it is read for internal consistency.
 
 .. code-block:: toml

source/specifications/index.rst

@@ -15,6 +15,7 @@ Package Distribution Metadata
 .. toctree::
    :maxdepth: 1
 
+   name-normalization
    core-metadata
    version-specifiers
    dependency-specifiers

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)

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