Merge branch 'cleanup/util-2c-typing-reformat-style' into cleanup/util-2d-inspect-typeguards

Author: picnixz

sphinx/ext/autodoc/mock.py

@@ -54,7 +54,7 @@ def __contains__(self, key: str) -> bool:
     def __iter__(self) -> Iterator[Any]:
         return iter([])
 
-    def __mro_entries__(self, bases: tuple[Any, ...]) -> tuple[type[Any], ...]:
+    def __mro_entries__(self, bases: tuple[Any, ...]) -> tuple[type, ...]:
         return (self.__class__,)
 
     def __getitem__(self, key: Any) -> _MockObject:
@@ -160,8 +160,8 @@ def mock(modnames: list[str]) -> Iterator[None]:
         # mock modules are enabled here
         ...
     """
+    finder = MockFinder(modnames)
     try:
-        finder = MockFinder(modnames)
         sys.meta_path.insert(0, finder)
         yield
     finally:

sphinx/util/typing.py

@@ -24,7 +24,8 @@
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
-    from typing import Final, Protocol
+    from collections.abc import Set as AbstractSet
+    from typing import Final, Literal, Protocol
 
     from typing_extensions import TypeGuard
 
@@ -33,6 +34,9 @@
     class _SpecialFormInterface(Protocol):
         _name: str
 
+    _RestifyMode = Literal['fully-qualified-except-typing', 'smart']
+    _StringifyMode = Literal['fully-qualified-except-typing', 'fully-qualified', 'smart']
+    _MT_co = TypeVar('_MT_co', bound=Any, covariant=True)
 
 if sys.version_info >= (3, 10):
     from types import UnionType
@@ -186,7 +190,7 @@ 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:
+def restify(cls: Any, mode: object = '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.
@@ -200,10 +204,10 @@ def restify(cls: Any, mode: str = 'fully-qualified-except-typing') -> str:
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util import inspect  # lazy loading
 
-    if mode == 'smart':
-        modprefix = '~'
-    else:
-        modprefix = ''
+    mode = _validate_restify_mode(mode)
+    # With an if-else block, mypy infers 'mode' to be a 'str'
+    # instead of a literal string (and we don't want to cast).
+    module_prefix = '~' if mode == 'smart' else ''
 
     try:
         if cls is None or cls is NoneType:
@@ -213,15 +217,18 @@ def restify(cls: Any, mode: str = 'fully-qualified-except-typing') -> str:
         elif isinstance(cls, str):
             return cls
         elif ismockmodule(cls):
-            return f':py:class:`{modprefix}{cls.__name__}`'
+            return f':py:class:`{module_prefix}{cls.__name__}`'
         elif ismock(cls):
-            return f':py:class:`{modprefix}{cls.__module__}.{cls.__name__}`'
-        elif is_invalid_builtin_class(cls):  # this never raises TypeError
-            return f':py:class:`{modprefix}{_INVALID_BUILTIN_CLASSES[cls]}`'
+            return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
+        elif is_invalid_builtin_class(cls):
+            # The above predicate never raises TypeError but should not be
+            # evaluated before determining whether *cls* is a mocked object
+            # or not; instead of two try-except blocks, we keep it here.
+            return f':py:class:`{module_prefix}{_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__}`'
+                return f':py:class:`{module_prefix}{cls.__module__}.{cls.__name__}`'
             return f':py:class:`{cls.__name__}`'
         elif UnionType and isinstance(cls, UnionType):
             # Union types (PEP 585) retain their definition order when they
@@ -264,7 +271,7 @@ def restify(cls: Any, mode: str = 'fully-qualified-except-typing') -> str:
             if _is_annotated_form(__origin__):
                 text = restify(__origin__, mode)
             elif internal_class_name := _get_typing_internal_name(cls):
-                prefix = '~' if cls.__module__ == 'typing' else modprefix
+                prefix = '~' if cls.__module__ == 'typing' else module_prefix
                 text = f':py:class:`{prefix}{cls.__module__}.{internal_class_name}`'
             else:
                 text = restify(__origin__, mode)
@@ -290,13 +297,13 @@ def restify(cls: Any, mode: str = 'fully-qualified-except-typing') -> str:
             # handle bpo-46998
             return f':py:obj:`~{cls.__module__}.{cls.__name__}`'
         elif hasattr(cls, '__qualname__'):
-            prefix = '~' if cls.__module__ == 'typing' else modprefix
+            prefix = '~' if cls.__module__ == 'typing' else module_prefix
             return f':py:class:`{prefix}{cls.__module__}.{cls.__qualname__}`'
         elif isinstance(cls, ForwardRef):
             return f':py:class:`{cls.__forward_arg__}`'
         else:
             # not a class (ex. TypeVar)
-            prefix = '~' if cls.__module__ == 'typing' else modprefix
+            prefix = '~' if cls.__module__ == 'typing' else module_prefix
             return f':py:obj:`{prefix}{cls.__module__}.{cls.__name__}`'
     except (AttributeError, TypeError):
         return inspect.object_description(cls)
@@ -323,16 +330,10 @@ def stringify_annotation(
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util.inspect import isNewType  # lazy loading
 
-    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 = ''
+    mode = _validate_stringify_mode(mode)
+    # With an if-else block, mypy infers 'mode' to be a 'str'
+    # instead of a literal string (and we don't want to cast).
+    module_prefix = '~' if mode == 'smart' else ''
 
     # The values below must be strings if the objects are well-formed.
     annotation_qualname: str = getattr(annotation, '__qualname__', '')
@@ -440,29 +441,57 @@ def stringify_annotation(
     return f'{module_prefix}{qualname}'
 
 
-def _stringify_literal_arg(arg: Any, mode: str) -> str:
+def _restify_literal_arg(arg: Any, mode: _RestifyMode) -> 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}'
+        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)
 
 
-def _restify_literal_arg(arg: Any, mode: str) -> str:
+def _stringify_literal_arg(arg: Any, mode: _StringifyMode) -> 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}`'
+        # 'MyEnum.member' in 'smart' mode, otherwise 'module.MyEnum.member'
+        prefix = '' if mode == 'smart' else enum_cls.__module__
+        return f'{prefix}.{enum_cls.__qualname__}.{arg.name}'
     return repr(arg)
 
 
+# validation functions (keep them as separate functions to handle enumerations
+# values instead of plain strings in the future and to be able to add better
+# type annotations using literal values)
+def _validate_mode(mode: Any, allowed_modes: AbstractSet[_MT_co]) -> _MT_co:
+    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)
+    return mode
+
+
+def _validate_restify_mode(mode: Any) -> _RestifyMode:
+    # add more allowed modes here (e.g., enumeration values)
+    allowed_modes: AbstractSet[_RestifyMode] = {
+        'fully-qualified-except-typing',
+        'smart',
+    }
+    return _validate_mode(mode, allowed_modes)
+
+
+def _validate_stringify_mode(mode: Any) -> _StringifyMode:
+    # add more allowed modes here (e.g., enumeration values)
+    allowed_modes: AbstractSet[_StringifyMode] = {
+        'fully-qualified-except-typing',
+        'fully-qualified',
+        'smart',
+    }
+    return _validate_mode(mode, allowed_modes)
+
+
 # deprecated name -> (object to return, canonical path or empty string, removal version)
 _DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
     'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation', (8, 0)),