add type guards

Author: picnixz

.ruff.toml

@@ -545,7 +545,6 @@ exclude = [
     "sphinx/util/cfamily.py",
     "sphinx/util/math.py",
     "sphinx/util/logging.py",
-    "sphinx/util/inspect.py",
     "sphinx/util/parallel.py",
     "sphinx/util/inventory.py",
     "sphinx/util/__init__.py",

pyproject.toml

@@ -87,6 +87,7 @@ lint = [
     "sphinx-lint",
     "types-docutils",
     "types-requests",
+    "typing-extensions",
     "importlib_metadata",  # for mypy (Python<=3.9)
     "tomli",  # for mypy (Python<=3.10)
     "pytest>=6.0",

sphinx/ext/autodoc/__init__.py

@@ -2267,7 +2267,7 @@ def format_signature(self, **kwargs: Any) -> str:
                     pass  # default implementation. skipped.
                 else:
                     if inspect.isclassmethod(func):
-                        func = func.__func__
+                        func = func.__func__  # type: ignore[attr-defined]
                     dispatchmeth = self.annotate_to_first_argument(func, typ)
                     if dispatchmeth:
                         documenter = MethodDocumenter(self.directive, '')

sphinx/util/inspect.py

@@ -5,13 +5,13 @@
 import ast
 import builtins
 import contextlib
-import enum
 import inspect
 import re
 import sys
 import types
 import typing
 from collections.abc import Mapping
+from enum import Enum
 from functools import cached_property, partial, partialmethod, singledispatchmethod
 from importlib import import_module
 from inspect import Parameter, Signature
@@ -26,8 +26,44 @@
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
     from inspect import _ParameterKind
-    from types import MethodType, ModuleType
-    from typing import Final
+    from typing import Final, Protocol, Union
+
+    from typing_extensions import TypeGuard
+
+    class _SupportsGet(Protocol):
+        def __get__(self, __instance: Any, __owner: type | None = ...) -> Any: ...  # NoQA: E704
+
+    class _SupportsSet(Protocol):
+        # instance and value are contravariants but we do not need that precision
+        def __set__(self, __instance: Any, __value: Any) -> None: ...  # NoQA: E704
+
+    class _SupportsDelete(Protocol):
+        # instance is contravariant but we do not need that precision
+        def __delete__(self, __instance: Any) -> None: ...  # NoQA: E704
+
+    class _GenericAliasLike(Protocol):
+        # Minimalist interface for a generic alias in typing.py.
+
+        # The ``__origin__`` is defined both on the base type for generics
+        # in typing.py *and* on the public ``types.GenericAlias`` type.
+        __origin__: type
+
+        # Note that special generic alias types (tuple and callables) do
+        # not directly define ``__args__``. At runtime, however, they are
+        # actually instances of ``typing._GenericAlias`` which does have
+        # an ``__args__`` field.
+        __args__: tuple[Any, ...]
+
+    _RoutineType = Union[
+        types.FunctionType,
+        types.LambdaType,
+        types.MethodType,
+        types.BuiltinFunctionType,
+        types.BuiltinMethodType,
+        types.WrapperDescriptorType,
+        types.MethodDescriptorType,
+        types.ClassMethodDescriptorType,
+    ]
 
 logger = logging.getLogger(__name__)
 
@@ -90,7 +126,7 @@ class methods and static methods.
 
 
 def getall(obj: Any) -> Sequence[str] | None:
-    """Get the ``__all__`` attribute of an object as sequence.
+    """Get the ``__all__`` attribute of an object as a sequence.
 
     This returns ``None`` if the given ``obj.__all__`` does not exist and
     raises :exc:`ValueError` if ``obj.__all__`` is not a list or tuple of
@@ -184,14 +220,14 @@ def isNewType(obj: Any) -> bool:
     return __module__ == 'typing' and __qualname__ == 'NewType.<locals>.new_type'
 
 
-def isenumclass(x: Any) -> bool:
+def isenumclass(x: Any) -> TypeGuard[type[Enum]]:
     """Check if the object is an :class:`enumeration class <enum.Enum>`."""
-    return isclass(x) and issubclass(x, enum.Enum)
+    return isclass(x) and issubclass(x, Enum)
 
 
-def isenumattribute(x: Any) -> bool:
+def isenumattribute(x: Any) -> TypeGuard[Enum]:
     """Check if the object is an enumeration attribute."""
-    return isinstance(x, enum.Enum)
+    return isinstance(x, Enum)
 
 
 def unpartial(obj: Any) -> Any:
@@ -206,7 +242,7 @@ def unpartial(obj: Any) -> Any:
     return obj
 
 
-def ispartial(obj: Any) -> bool:
+def ispartial(obj: Any) -> TypeGuard[partial | partialmethod]:
     """Check if the object is a partial function or method."""
     return isinstance(obj, (partial, partialmethod))
 
@@ -239,7 +275,7 @@ def isstaticmethod(obj: Any, cls: Any = None, name: str | None = None) -> bool:
     return False
 
 
-def isdescriptor(x: Any) -> bool:
+def isdescriptor(x: Any) -> TypeGuard[_SupportsGet | _SupportsSet | _SupportsDelete]:
     """Check if the object is a :external+python:term:`descriptor`."""
     return any(
         callable(safe_getattr(x, item, None)) for item in ('__get__', '__set__', '__delete__')
@@ -251,7 +287,7 @@ def isabstractmethod(obj: Any) -> bool:
     return safe_getattr(obj, '__isabstractmethod__', False) is True
 
 
-def isboundmethod(method: MethodType) -> bool:
+def isboundmethod(method: types.MethodType) -> bool:
     """Check if the method is a bound method."""
     return safe_getattr(method, '__self__', None) is not None
 
@@ -306,12 +342,12 @@ def is_singledispatch_function(obj: Any) -> bool:
     )
 
 
-def is_singledispatch_method(obj: Any) -> bool:
+def is_singledispatch_method(obj: Any) -> TypeGuard[singledispatchmethod]:
     """Check if the object is a :class:`~functools.singledispatchmethod`."""
     return isinstance(obj, singledispatchmethod)
 
 
-def isfunction(obj: Any) -> bool:
+def isfunction(obj: Any) -> TypeGuard[types.FunctionType]:
     """Check if the object is a user-defined function.
 
     Partial objects are unwrapped before checking them.
@@ -321,7 +357,7 @@ def isfunction(obj: Any) -> bool:
     return inspect.isfunction(unpartial(obj))
 
 
-def isbuiltin(obj: Any) -> bool:
+def isbuiltin(obj: Any) -> TypeGuard[types.BuiltinFunctionType]:
     """Check if the object is a built-in function or method.
 
     Partial objects are unwrapped before checking them.
@@ -331,7 +367,7 @@ def isbuiltin(obj: Any) -> bool:
     return inspect.isbuiltin(unpartial(obj))
 
 
-def isroutine(obj: Any) -> bool:
+def isroutine(obj: Any) -> TypeGuard[_RoutineType]:
     """Check if the object is a kind of function or method.
 
     Partial objects are unwrapped before checking them.
@@ -356,7 +392,7 @@ def _is_wrapped_coroutine(obj: Any) -> bool:
     return hasattr(obj, '__wrapped__')
 
 
-def isproperty(obj: Any) -> bool:
+def isproperty(obj: Any) -> TypeGuard[property | cached_property]:
     """Check if the object is property (possibly cached)."""
     return isinstance(obj, (property, cached_property))
 
@@ -431,8 +467,8 @@ def object_description(obj: Any, *, _seen: frozenset[int] = frozenset()) -> str:
         return 'frozenset({%s})' % ', '.join(
             object_description(x, _seen=seen) for x in sorted_values
         )
-    elif isinstance(obj, enum.Enum):
-        if obj.__repr__.__func__ is not enum.Enum.__repr__:  # type: ignore[attr-defined]
+    elif isinstance(obj, Enum):
+        if obj.__repr__.__func__ is not Enum.__repr__:  # type: ignore[attr-defined]
             return repr(obj)
         return f'{obj.__class__.__name__}.{obj.name}'
     elif isinstance(obj, tuple):
@@ -527,7 +563,7 @@ def __init__(self, modname: str, mapping: Mapping[str, str]) -> None:
         self.__modname = modname
         self.__mapping = mapping
 
-        self.__module: ModuleType | None = None
+        self.__module: types.ModuleType | None = None
 
     def __getattr__(self, name: str) -> Any:
         fullname = '.'.join(filter(None, [self.__modname, name]))

sphinx/util/typing.py

@@ -8,17 +8,32 @@
 from collections.abc import Sequence
 from contextvars import Context, ContextVar, Token
 from struct import Struct
-from typing import TYPE_CHECKING, Any, Callable, ForwardRef, TypedDict, TypeVar, Union
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Callable,
+    ForwardRef,
+    TypedDict,
+    TypeVar,
+    Union,
+)
 
 from docutils import nodes
 from docutils.parsers.rst.states import Inliner
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
-    from typing import Final
+    from typing import Final, Protocol
+
+    from typing_extensions import TypeGuard
 
     from sphinx.application import Sphinx
 
+    class _SpecialFormInterface(Protocol):
+        _name: str
+
+
 if sys.version_info >= (3, 10):
     from types import UnionType
 else:
@@ -152,8 +167,27 @@ def is_system_TypeVar(typ: Any) -> bool:
     return modname == 'typing' and isinstance(typ, TypeVar)
 
 
-def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> str:
-    """Convert python class to a reST reference.
+def _is_special_form(obj: Any) -> TypeGuard[_SpecialFormInterface]:
+    """Check if *obj* is a typing special form.
+
+    The guarded type is a protocol with the members that Sphinx needs in
+    this module and not the native ``typing._SpecialForm`` from typeshed,
+    but the runtime type of *obj* must be a true special form instance.
+    """
+    return isinstance(obj, typing._SpecialForm)
+
+
+def _is_annotated_form(obj: Any) -> TypeGuard[Annotated[Any, ...]]:
+    """Check if *obj* is an annotated type."""
+    return typing.get_origin(obj) is Annotated or str(obj).startswith('typing.Annotated')
+
+
+def _get_typing_internal_name(obj: Any) -> str | None:
+    return getattr(obj, '_name', None)
+
+
+def restify(cls: Any, mode: str = 'fully-qualified-except-typing') -> str:
+    """Convert a python type-like object to a reST reference.
 
     :param mode: Specify a method how annotations will be stringified.
 
@@ -205,10 +239,10 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
         elif (
             inspect.isgenericalias(cls)
             and cls.__module__ == 'typing'
-            and cls.__origin__ is Union  # type: ignore[attr-defined]
+            and cls.__origin__ is Union
         ):
-            # *cls* is defined in ``typing``, and thus ``__args__`` must exist;
-            if NoneType in (__args__ := cls.__args__):  # type: ignore[attr-defined]
+            # *cls* is defined in ``typing``, thus ``__args__`` should exist
+            if NoneType in (__args__ := cls.__args__):
                 # Shape: Union[T_1, ..., T_k, None, T_{k+1}, ..., T_n]
                 #
                 # Note that we keep Literal[None] in their rightful place
@@ -226,33 +260,33 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
             args = ', '.join(restify(a, mode) for a in __args__)
             return rf':py:obj:`~typing.Union`\ [{args}]'
         elif inspect.isgenericalias(cls):
-            if isinstance(cls.__origin__, typing._SpecialForm):  # type: ignore[attr-defined]
-                text = restify(cls.__origin__, mode)  # type: ignore[attr-defined,arg-type]
-            elif getattr(cls, '_name', None):
-                cls_name = cls._name  # type: ignore[attr-defined]
+            __origin__ = cls.__origin__
+            if _is_annotated_form(__origin__):
+                text = restify(__origin__, mode)
+            elif internal_name := _get_typing_internal_name(cls):
                 if cls.__module__ == 'typing':
-                    text = f':py:class:`~{cls.__module__}.{cls_name}`'
+                    text = f':py:class:`~{cls.__module__}.{internal_name}`'
                 else:
-                    text = f':py:class:`{modprefix}{cls.__module__}.{cls_name}`'
+                    text = f':py:class:`{modprefix}{cls.__module__}.{internal_name}`'
             else:
-                text = restify(cls.__origin__, mode)  # type: ignore[attr-defined]
+                text = restify(__origin__, mode)
 
             origin = getattr(cls, '__origin__', None)
             if not hasattr(cls, '__args__'):  # NoQA: SIM114
                 pass
             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 _get_typing_internal_name(cls) == 'Callable':
                 args = ', '.join(restify(a, mode) for a in cls.__args__[:-1])
                 text += rf'\ [[{args}], {restify(cls.__args__[-1], mode)}]'
-            elif cls.__module__ == 'typing' and getattr(origin, '_name', None) == 'Literal':
+            elif cls.__module__ == 'typing' and _get_typing_internal_name(origin) == 'Literal':
                 literals = ', '.join(_restify_literal_arg(a, mode) for a in cls.__args__)
                 text += rf'\ [{literals}]'
             elif cls.__args__:
                 text += rf'\ [{", ".join(restify(a, mode) for a in cls.__args__)}]'
             return text
-        elif isinstance(cls, typing._SpecialForm):
+        elif _is_special_form(cls):
             return f':py:obj:`~{cls.__module__}.{cls._name}`'
         elif sys.version_info[:2] >= (3, 11) and cls is typing.Any:
             # handle bpo-46998
@@ -332,7 +366,7 @@ def stringify_annotation(
         return f'{module_prefix}{annotation_module}.{annotation_name}'
     elif is_invalid_builtin_class(annotation):
         return f'{module_prefix}{_INVALID_BUILTIN_CLASSES[annotation]}'
-    elif str(annotation).startswith('typing.Annotated'):  # for py39+
+    elif _is_annotated_form(annotation):  # for py39+
         pass
     elif annotation_module == 'builtins' and annotation_qualname:
         if (args := getattr(annotation, '__args__', None)) is None:
@@ -361,9 +395,8 @@ def stringify_annotation(
             # handle ForwardRefs
             qualname = annotation_forward_arg
         else:
-            _name = getattr(annotation, '_name', '')
-            if _name:
-                qualname = _name
+            if internal_name := _get_typing_internal_name(annotation):
+                qualname = internal_name
             elif annotation_qualname:
                 qualname = annotation_qualname
             else:
@@ -397,7 +430,7 @@ def stringify_annotation(
         elif qualname == 'Literal':
             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+
+        elif _is_annotated_form(annotation):  # 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])