cleanup

Author: picnixz

.ruff.toml

@@ -554,7 +554,6 @@ exclude = [
     "sphinx/util/http_date.py",
     "sphinx/util/matching.py",
     "sphinx/util/index_entries.py",
-    "sphinx/util/typing.py",
     "sphinx/util/images.py",
     "sphinx/util/exceptions.py",
     "sphinx/util/requests.py",

sphinx/util/typing.py

@@ -14,7 +14,8 @@
 from docutils.parsers.rst.states import Inliner
 
 if TYPE_CHECKING:
-    import enum
+    from collections.abc import Mapping
+    from typing import Final
 
     from sphinx.application import Sphinx
 
@@ -24,7 +25,7 @@
     UnionType = None
 
 # classes that have an incorrect .__module__ attribute
-_INVALID_BUILTIN_CLASSES = {
+_INVALID_BUILTIN_CLASSES: Final[Mapping[Any, str]] = {
     Context: 'contextvars.Context',  # Context.__module__ == '_contextvars'
     ContextVar: 'contextvars.ContextVar',  # ContextVar.__module__ == '_contextvars'
     Token: 'contextvars.Token',  # Token.__module__ == '_contextvars'
@@ -71,8 +72,10 @@ def is_invalid_builtin_class(obj: Any) -> bool:
 PathMatcher = Callable[[str], bool]
 
 # common role functions
-RoleFunction = Callable[[str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
-                        tuple[list[nodes.Node], list[nodes.system_message]]]
+RoleFunction = Callable[
+    [str, str, str, int, Inliner, dict[str, Any], Sequence[str]],
+    tuple[list[nodes.Node], list[nodes.system_message]],
+]
 
 # A option spec for directive
 OptionSpec = dict[str, Callable[[str], Any]]
@@ -115,7 +118,9 @@ class ExtensionMetadata(TypedDict, total=False):
 
 
 def get_type_hints(
-    obj: Any, globalns: dict[str, Any] | None = None, localns: dict[str, Any] | None = None,
+    obj: Any,
+    globalns: dict[str, Any] | None = None,
+    localns: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Return a dictionary containing type hints for a function, method, module or class
     object.
@@ -177,32 +182,33 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
             return f':py:class:`{modprefix}{cls.__name__}`'
         elif ismock(cls):
             return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
-        elif is_invalid_builtin_class(cls):
+        elif is_invalid_builtin_class(cls):  # this never raises TypeError
             return f':py:class:`{modprefix}{_INVALID_BUILTIN_CLASSES[cls]}`'
         elif inspect.isNewType(cls):
             if sys.version_info[:2] >= (3, 10):
                 # newtypes have correct module info since Python 3.10+
                 return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
-            else:
-                return ':py:class:`%s`' % cls.__name__
+            return f':py:class:`{cls.__name__}`'
         elif UnionType and isinstance(cls, UnionType):
             # Union types (PEP 585) retain their definition order when they
             # are printed natively and ``None``-like types are kept as is.
             return ' | '.join(restify(a, mode) for a in cls.__args__)
         elif cls.__module__ in ('__builtin__', 'builtins'):
             if hasattr(cls, '__args__'):
-                if not cls.__args__:  # Empty tuple, list, ...
-                    return fr':py:class:`{cls.__name__}`\ [{cls.__args__!r}]'
-
-                concatenated_args = ', '.join(restify(arg, mode) for arg in cls.__args__)
-                return fr':py:class:`{cls.__name__}`\ [{concatenated_args}]'
-            else:
-                return ':py:class:`%s`' % cls.__name__
-        elif (inspect.isgenericalias(cls)
-              and cls.__module__ == 'typing'
-              and cls.__origin__ is Union):  # type: ignore[attr-defined]
+                __args__: tuple[Any, ...] = cls.__args__
+                if not __args__:  # Empty tuple, list, ...
+                    return rf':py:class:`{cls.__name__}`\ [{__args__!r}]'
+
+                concatenated_args = ', '.join(restify(arg, mode) for arg in __args__)
+                return rf':py:class:`{cls.__name__}`\ [{concatenated_args}]'
+            return f':py:class:`{cls.__name__}`'
+        elif (
+            inspect.isgenericalias(cls)
+            and cls.__module__ == 'typing'
+            and cls.__origin__ is Union  # type: ignore[attr-defined]
+        ):
             # *cls* is defined in ``typing``, and thus ``__args__`` must exist;
-            if NoneType in (__args__ := cls.__args__):
+            if NoneType in (__args__ := cls.__args__):  # type: ignore[attr-defined]
                 # Shape: Union[T_1, ..., T_k, None, T_{k+1}, ..., T_n]
                 #
                 # Note that we keep Literal[None] in their rightful place
@@ -237,41 +243,29 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
             elif all(is_system_TypeVar(a) for a in cls.__args__):
                 # Suppress arguments if all system defined TypeVars (ex. Dict[KT, VT])
                 pass
-            elif (cls.__module__ == 'typing'
-                  and cls._name == 'Callable'):  # type: ignore[attr-defined]
+            elif cls.__module__ == 'typing' and cls._name == 'Callable':  # type: ignore[attr-defined]
                 args = ', '.join(restify(a, mode) for a in cls.__args__[:-1])
-                text += fr"\ [[{args}], {restify(cls.__args__[-1], mode)}]"
+                text += rf'\ [[{args}], {restify(cls.__args__[-1], mode)}]'
             elif cls.__module__ == 'typing' and getattr(origin, '_name', None) == 'Literal':
-                literal_args = []
-                for a in cls.__args__:
-                    if inspect.isenumattribute(a):
-                        literal_args.append(_format_literal_enum_arg(a, mode=mode))
-                    else:
-                        literal_args.append(repr(a))
-                text += r"\ [%s]" % ', '.join(literal_args)
-                del literal_args
+                literals = ', '.join(_restify_literal_arg(a, mode) for a in cls.__args__)
+                text += rf'\ [{literals}]'
             elif cls.__args__:
-                text += r"\ [%s]" % ", ".join(restify(a, mode) for a in cls.__args__)
-
+                text += rf'\ [{", ".join(restify(a, mode) for a in cls.__args__)}]'
             return text
         elif isinstance(cls, typing._SpecialForm):
             return f':py:obj:`~{cls.__module__}.{cls._name}`'
         elif sys.version_info[:2] >= (3, 11) and cls is typing.Any:
             # handle bpo-46998
             return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
         elif hasattr(cls, '__qualname__'):
-            if cls.__module__ == 'typing':
-                return f':py:class:`~{cls.__module__}.{cls.__qualname__}`'
-            else:
-                return f':py:class:`{modprefix}{cls.__module__}.{cls.__qualname__}`'
+            prefix = '~' if cls.__module__ == 'typing' else modprefix
+            return f':py:class:`{prefix}{cls.__module__}.{cls.__qualname__}`'
         elif isinstance(cls, ForwardRef):
-            return ':py:class:`%s`' % cls.__forward_arg__
+            return f':py:class:`{cls.__forward_arg__}`'
         else:
             # not a class (ex. TypeVar)
-            if cls.__module__ == 'typing':
-                return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
-            else:
-                return f':py:obj:`{modprefix}{cls.__module__}.{cls.__name__}`'
+            prefix = '~' if cls.__module__ == 'typing' else modprefix
+            return f':py:obj:`{prefix}{cls.__module__}.{cls.__name__}`'
     except (AttributeError, TypeError):
         return inspect.object_description(cls)
 
@@ -297,67 +291,66 @@ def stringify_annotation(
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util.inspect import isNewType  # lazy loading
 
-    if mode not in {'fully-qualified-except-typing', 'fully-qualified', 'smart'}:
-        msg = ("'mode' must be one of 'fully-qualified-except-typing', "
-               f"'fully-qualified', or 'smart'; got {mode!r}.")
+    allowed_modes = {'fully-qualified-except-typing', 'fully-qualified', 'smart'}
+    if mode not in allowed_modes:
+        allowed = ', '.join(map(repr, sorted(allowed_modes)))
+        msg = f'%r must be one of %s; got {mode!r}' % ('mode', allowed)
         raise ValueError(msg)
 
     if mode == 'smart':
         module_prefix = '~'
     else:
         module_prefix = ''
 
-    annotation_qualname = getattr(annotation, '__qualname__', '')
-    annotation_module = getattr(annotation, '__module__', '')
-    annotation_name = getattr(annotation, '__name__', '')
+    # The values below must be strings if the objects are well-formed.
+    annotation_qualname: str = getattr(annotation, '__qualname__', '')
+    annotation_module: str = getattr(annotation, '__module__', '')
+    annotation_name: str = getattr(annotation, '__name__', '')
     annotation_module_is_typing = annotation_module == 'typing'
 
     if isinstance(annotation, str):
         if annotation.startswith("'") and annotation.endswith("'"):
             # might be a double Forward-ref'ed type.  Go unquoting.
             return annotation[1:-1]
-        else:
-            return annotation
+        return annotation
     elif isinstance(annotation, TypeVar):
         if annotation_module_is_typing and mode in {'fully-qualified-except-typing', 'smart'}:
             return annotation_name
-        else:
-            return module_prefix + f'{annotation_module}.{annotation_name}'
+        return f'{module_prefix}{annotation_module}.{annotation_name}'
     elif isNewType(annotation):
         if sys.version_info[:2] >= (3, 10):
             # newtypes have correct module info since Python 3.10+
-            return module_prefix + f'{annotation_module}.{annotation_name}'
-        else:
-            return annotation_name
+            return f'{module_prefix}{annotation_module}.{annotation_name}'
+        return annotation_name
     elif not annotation:
         return repr(annotation)
     elif annotation is NoneType:
         return 'None'
     elif ismockmodule(annotation):
-        return module_prefix + annotation_name
+        return f'{module_prefix}{annotation_name}'
     elif ismock(annotation):
-        return module_prefix + f'{annotation_module}.{annotation_name}'
+        return f'{module_prefix}{annotation_module}.{annotation_name}'
     elif is_invalid_builtin_class(annotation):
-        return module_prefix + _INVALID_BUILTIN_CLASSES[annotation]
-    elif str(annotation).startswith('typing.Annotated'):  # for py310+
+        return f'{module_prefix}{_INVALID_BUILTIN_CLASSES[annotation]}'
+    elif str(annotation).startswith('typing.Annotated'):  # for py39+
         pass
     elif annotation_module == 'builtins' and annotation_qualname:
-        if (args := getattr(annotation, '__args__', None)) is not None:  # PEP 585 generic
-            if not args:  # Empty tuple, list, ...
-                return repr(annotation)
-
-            concatenated_args = ', '.join(stringify_annotation(arg, mode) for arg in args)
-            return f'{annotation_qualname}[{concatenated_args}]'
-        else:
+        if (args := getattr(annotation, '__args__', None)) is None:
             return annotation_qualname
+
+        # PEP 585 generic
+        if not args:  # Empty tuple, list, ...
+            return repr(annotation)
+        concatenated_args = ', '.join(stringify_annotation(arg, mode) for arg in args)
+        return f'{annotation_qualname}[{concatenated_args}]'
     elif annotation is Ellipsis:
         return '...'
 
     module_prefix = f'{annotation_module}.'
-    annotation_forward_arg = getattr(annotation, '__forward_arg__', None)
+    annotation_forward_arg: str | None = getattr(annotation, '__forward_arg__', None)
     if annotation_qualname or (annotation_module_is_typing and not annotation_forward_arg):
         if mode == 'smart':
-            module_prefix = '~' + module_prefix
+            module_prefix = f'~{module_prefix}'
         if annotation_module_is_typing and mode == 'fully-qualified-except-typing':
             module_prefix = ''
     else:
@@ -375,7 +368,8 @@ def stringify_annotation(
                 qualname = annotation_qualname
             else:
                 qualname = stringify_annotation(
-                    annotation.__origin__, 'fully-qualified-except-typing',
+                    annotation.__origin__,
+                    'fully-qualified-except-typing',
                 ).replace('typing.', '')  # ex. Union
     elif annotation_qualname:
         qualname = annotation_qualname
@@ -401,40 +395,41 @@ def stringify_annotation(
             returns = stringify_annotation(annotation_args[-1], mode)
             return f'{module_prefix}Callable[[{args}], {returns}]'
         elif qualname == 'Literal':
-            from sphinx.util.inspect import isenumattribute  # lazy loading
-
-            def format_literal_arg(arg: Any) -> str:
-                if isenumattribute(arg):
-                    enumcls = arg.__class__
-
-                    if mode == 'smart':
-                        # MyEnum.member
-                        return f'{enumcls.__qualname__}.{arg.name}'
-
-                    # module.MyEnum.member
-                    return f'{enumcls.__module__}.{enumcls.__qualname__}.{arg.name}'
-                return repr(arg)
-
-            args = ', '.join(map(format_literal_arg, annotation_args))
-            return f'{module_prefix}Literal[{args}]'
+            literals = ', '.join(_stringify_literal_arg(a, mode) for a in annotation_args)
+            return f'{module_prefix}Literal[{literals}]'
         elif str(annotation).startswith('typing.Annotated'):  # for py39+
             return stringify_annotation(annotation_args[0], mode)
         elif all(is_system_TypeVar(a) for a in annotation_args):
             # Suppress arguments if all system defined TypeVars (ex. Dict[KT, VT])
-            return module_prefix + qualname
+            return f'{module_prefix}{qualname}'
         else:
             args = ', '.join(stringify_annotation(a, mode) for a in annotation_args)
             return f'{module_prefix}{qualname}[{args}]'
 
-    return module_prefix + qualname
+    return f'{module_prefix}{qualname}'
 
 
-def _format_literal_enum_arg(arg: enum.Enum, /, *, mode: str) -> str:
-    enum_cls = arg.__class__
-    if mode == 'smart' or enum_cls.__module__ == 'typing':
-        return f':py:attr:`~{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
-    else:
-        return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+def _stringify_literal_arg(arg: Any, mode: str) -> str:
+    from sphinx.util.inspect import isenumattribute  # lazy loading
+
+    if isenumattribute(arg):
+        enumcls = arg.__class__
+        if mode == 'smart':
+            # MyEnum.member
+            return f'{enumcls.__qualname__}.{arg.name}'
+        # module.MyEnum.member
+        return f'{enumcls.__module__}.{enumcls.__qualname__}.{arg.name}'
+    return repr(arg)
+
+
+def _restify_literal_arg(arg: Any, mode: str) -> str:
+    from sphinx.util.inspect import isenumattribute  # lazy loading
+
+    if isenumattribute(arg):
+        enum_cls = arg.__class__
+        prefix = '~' if mode == 'smart' or enum_cls.__module__ == 'typing' else ''
+        return f':py:attr:`{prefix}{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
+    return repr(arg)
 
 
 # deprecated name -> (object to return, canonical path or empty string, removal version)