Support enriched metadata in packaging.metadata (#686)

Introduce the `packaging.metadata.Metadata` class which gives an object API similar to `packaging.metadata.RawMetadata` while returning "enriched" objects like `version.Version` where appropriate. It also supports validating the metadata.

Part of #570

CHANGELOG.rst

@@ -7,6 +7,9 @@ Changelog
 * Enforce that the entire marker string is parsed (:issue:`687`)
 * Requirement parsing no longer automatically validates the URL (:issue:`120`)
 * Canonicalize names for requirements comparison (:issue:`644`)
+* Introduce `metadata.Metadata` (along with `metadata.ExceptionGroup` and `metadata.InvalidMetadata`; :issue:`570`)
+* Introduce the `validate` keyword parameter to `utils.validate_name()` (:issue:`570`)
+* Introduce `utils.is_normalized_name()` (:issue:`570`)
 
 23.1 - 2023-04-12
 ~~~~~~~~~~~~~~~~~

docs/metadata.rst

@@ -25,15 +25,39 @@ Usage
     'packaging'
     >>> raw["version"]
     '24.0'
+    >>> from packaging.metadata import Metadata
+    >>> parsed = Metadata.from_raw(raw)
+    >>> parsed.name
+    'packaging'
+    >>> parsed.version
+    <Version('24.0')>
 
 
 Reference
 ---------
 
+High Level Interface
+''''''''''''''''''''
+
+.. autoclass:: packaging.metadata.Metadata
+    :members:
+
 Low Level Interface
 '''''''''''''''''''
 
-.. automodule:: packaging.metadata
+.. autoclass:: packaging.metadata.RawMetadata
+    :members:
+
+.. autofunction:: packaging.metadata.parse_email
+
+
+Exceptions
+''''''''''
+
+.. autoclass:: packaging.metadata.InvalidMetadata
+    :members:
+
+.. autoclass:: packaging.metadata.ExceptionGroup
     :members:
 
 

docs/utils.rst

@@ -14,7 +14,7 @@ Reference
 
     A :class:`typing.NewType` of :class:`str`, representing a normalized name.
 
-.. function:: canonicalize_name(name)
+.. function:: canonicalize_name(name, validate=False)
 
     This function takes a valid Python package or extra name, and returns the
     normalized form of it.
@@ -23,7 +23,13 @@ Reference
     checkers to help require that a string has passed through this function
     before use.
 
+    If **validate** is true, then the function will check if **name** is a valid
+    distribution name before normalizing.
+
     :param str name: The name to normalize.
+    :param bool validate: Check whether the name is a valid distribution name.
+    :raises InvalidName: If **validate** is true and the name is not an
+        acceptable distribution name.
 
     .. doctest::
 
@@ -35,6 +41,21 @@ Reference
         >>> canonicalize_name("requests")
         'requests'
 
+.. function:: is_normalized_name(name)
+
+    Check if a name is already normalized (i.e. :func:`canonicalize_name` would
+    roundtrip to the same value).
+
+    :param str name: The name to check.
+
+    .. doctest::
+
+        >>> from packaging.utils import is_normalized_name
+        >>> is_normalized_name("requests")
+        True
+        >>> is_normalized_name("Django")
+        False
+
 .. function:: canonicalize_version(version)
 
     This function takes a string representing a package version (or a
@@ -103,6 +124,9 @@ Reference
         >>> ver == Version('1.0')
         True
 
+.. exception:: InvalidName
+
+    Raised when a distribution name is invalid.
 
 .. exception:: InvalidWheelFilename