cleanup

Author: picnixz

sphinx/util/typing.py

@@ -7,6 +7,7 @@
 import typing
 from collections.abc import Sequence
 from contextvars import Context, ContextVar, Token
+from functools import partial as _partial
 from struct import Struct
 from typing import TYPE_CHECKING, Any, Callable, ForwardRef, TypedDict, TypeVar, Union
 
@@ -15,6 +16,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
+    from collections.abc import Set as AbstractSet
     from typing import Final
 
     from sphinx.application import Sphinx
@@ -166,6 +168,8 @@ def restify(cls: type | None, mode: str = 'fully-qualified-except-typing') -> st
     from sphinx.ext.autodoc.mock import ismock, ismockmodule  # lazy loading
     from sphinx.util import inspect  # lazy loading
 
+    mode = _validate_restify_mode(mode)
+
     if mode == 'smart':
         modprefix = '~'
     else:
@@ -292,11 +296,7 @@ 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)
+    mode = _validate_stringify_mode(mode)
 
     if mode == 'smart':
         module_prefix = '~'
@@ -410,29 +410,48 @@ def stringify_annotation(
     return f'{module_prefix}{qualname}'
 
 
-def _stringify_literal_arg(arg: Any, mode: str) -> str:
+def _restify_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}'
+        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: 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}`'
+        # '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)
 
 
+# validations 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: str, allowed_modes: AbstractSet[str]) -> str:
+    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
+
+
+_RESTIFY_ALLOWED_MODES: Final[AbstractSet[str]] = {'fully-qualified-except-typing', 'smart'}
+_validate_restify_mode = _partial(_validate_mode, allowed_modes=_RESTIFY_ALLOWED_MODES)
+
+_STRINGIFY_ALLOWED_MODES: Final[AbstractSet[str]] = {
+    'fully-qualified-except-typing',
+    'fully-qualified',
+    'smart',
+}
+_validate_stringify_mode = _partial(_validate_mode, allowed_modes=_STRINGIFY_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)),