From 5bc405ac866795b72309ff403728a023ab30472f Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 28 Jun 2022 18:15:39 -0700 Subject: [PATCH] Document `utils.NormalizedName` Closes #495 --- docs/utils.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/utils.rst b/docs/utils.rst index 8fbb0250..192def74 100644 --- a/docs/utils.rst +++ b/docs/utils.rst @@ -10,10 +10,18 @@ A set of small, helper utilities for dealing with Python packages. Reference --------- +.. class:: NormalizedName + + A :class:`typing.NewType` of :class:`str`, representing a normalized name. + .. function:: canonicalize_name(name) - This function takes a valid Python package name, and returns the normalized - form of it. + This function takes a valid Python package or extra name, and returns the + normalized form of it. + + The return type is typed as :class:`NormalizedName`. This allows type + checkers to help require that a string has passed through this function + before use. :param str name: The name to normalize. @@ -46,10 +54,11 @@ Reference This function takes the filename of a wheel file, and parses it, returning a tuple of name, version, build number, and tags. - The name part of the tuple is normalized. The version portion is an - instance of :class:`~packaging.version.Version`. The build number - is ``()`` if there is no build number in the wheel filename, - otherwise a two-item tuple of an integer for the leading digits and + The name part of the tuple is normalized and typed as + :class:`NormalizedName`. The version portion is an instance of + :class:`~packaging.version.Version`. The build number is ``()`` if + there is no build number in the wheel filename, otherwise a + two-item tuple of an integer for the leading digits and a string for the rest of the build number. The tags portion is an instance of :class:`~packaging.tags.Tag`.