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

Author: brettcannon

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