Voice et bot modif

venv/lib/python3.12/site-packages/packaging/licenses/__init__.py

@@ -42,14 +42,25 @@ __all__ = [
     "canonicalize_license_expression",
 ]
 
+
+# Simple __dir__ implementation since there are no public submodules
+def __dir__() -> list[str]:
+    return __all__
+
+
 license_ref_allowed = re.compile("^[A-Za-z0-9.-]*$")
 
 NormalizedLicenseExpression = NewType("NormalizedLicenseExpression", str)
+"""
+A :class:`typing.NewType` of :class:`str`, representing a normalized
+License-Expression.
+"""
 
 
 class InvalidLicenseExpression(ValueError):
     """Raised when a license-expression string is invalid
 
+    >>> from packaging.licenses import canonicalize_license_expression
     >>> canonicalize_license_expression("invalid")
     Traceback (most recent call last):
         ...
@@ -60,6 +71,34 @@ class InvalidLicenseExpression(ValueError):
 def canonicalize_license_expression(
     raw_license_expression: str,
 ) -> NormalizedLicenseExpression:
+    """
+    This function takes a valid License-Expression, and returns the normalized
+    form of it.
+
+    The return type is typed as :class:`NormalizedLicenseExpression`. This
+    allows type checkers to help require that a string has passed through this
+    function before use.
+
+    :param str raw_license_expression: The License-Expression to canonicalize.
+    :raises InvalidLicenseExpression: If the License-Expression is invalid due to an
+        invalid/unknown license identifier or invalid syntax.
+
+    .. doctest::
+
+        >>> from packaging.licenses import canonicalize_license_expression
+        >>> canonicalize_license_expression("mit")
+        'MIT'
+        >>> canonicalize_license_expression("mit and (apache-2.0 or bsd-2-clause)")
+        'MIT AND (Apache-2.0 OR BSD-2-Clause)'
+        >>> canonicalize_license_expression("(mit")
+        Traceback (most recent call last):
+          ...
+        InvalidLicenseExpression: Invalid license expression: '(mit'
+        >>> canonicalize_license_expression("Use-it-after-midnight")
+        Traceback (most recent call last):
+          ...
+        InvalidLicenseExpression: Unknown license: 'Use-it-after-midnight'
+    """
     if not raw_license_expression:
         message = f"Invalid license expression: {raw_license_expression!r}"
         raise InvalidLicenseExpression(message)