Add some doctests to cover all the changes.

Author: jaraco

importlib_metadata/_compat/localize.py

@@ -13,6 +13,27 @@ def dist(
 ) -> importlib_metadata.Distribution:
     """
     Ensure dist is an :class:`importlib_metadata.Distribution`.
+
+    >>> stdlib = importlib.metadata.PathDistribution('foo')
+    >>> type(stdlib)
+    <class 'importlib.metadata.PathDistribution'>
+    >>> local = dist(stdlib)
+    >>> type(local)
+    <class 'importlib_metadata.PathDistribution'>
+
+    >>> class CustomDist(importlib.metadata.Distribution):
+    ...     def read_text(self, name):
+    ...         return
+    ...     def locate_file(self, name):
+    ...         return
+    >>> subclass = CustomDist()
+    >>> type(subclass)
+    <class 'importlib_metadata._compat.localize.CustomDist'>
+    >>> import pytest
+    >>> with pytest.warns(UserWarning, match="Unrecognized distribution subclass <class 'importlib_metadata._compat.localize.CustomDist'>"):
+    ...     local = dist(subclass)
+    >>> type(local) is type(subclass)
+    True
     """
     if isinstance(dist, importlib_metadata.Distribution):
         return dist
@@ -30,6 +51,14 @@ def dist(
 def message(
     input: importlib_metadata._adapters.Message | email.message.Message,
 ) -> importlib_metadata._adapters.Message:
+    """
+    Ensure a message is adapted to an importlib_metadata.Message.
+
+    >>> stdlib = email.message.Message()
+    >>> local = message(stdlib)
+    >>> type(local)
+    <class 'importlib_metadata._adapters.Message'>
+    """
     if isinstance(input, importlib_metadata._adapters.Message):
         return input
     return importlib_metadata._adapters.Message(input)
@@ -38,6 +67,16 @@ def message(
 def package_path(
     input: importlib_metadata.PackagePath | importlib.metadata.PackagePath,
 ) -> importlib_metadata.PackagePath:
+    """
+    Ensure a package path is adapted to an importlib_metadata.PackagePath.
+
+    >>> stdlib = importlib.metadata.PackagePath('foo')
+    >>> type(stdlib)
+    <class 'importlib.metadata.PackagePath'>
+    >>> local = package_path(stdlib)
+    >>> type(local)
+    <class 'importlib_metadata.PackagePath'>
+    """
     if isinstance(input, importlib_metadata.PackagePath):
         return input
     replacement = importlib_metadata.PackagePath(input)