diff options
author | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-12-26 02:03:59 +0900 |
---|---|---|
committer | Takeshi KOMIYA <i.tkomiya@gmail.com> | 2021-12-26 03:11:39 +0900 |
commit | 2ea9118181df74ea6a8371d72b2a4ac7da658438 (patch) | |
tree | b808a72bf2274987f8ea80bc2b0417ccdf63ab3c /sphinx/util/typing.py | |
parent | bdbad40f579bd7db7f837bfa998320658add3b89 (diff) | |
download | sphinx-git-2ea9118181df74ea6a8371d72b2a4ac7da658438.tar.gz |
refactor: Merge arguments of sphinx.util.typing:stringify()
Diffstat (limited to 'sphinx/util/typing.py')
-rw-r--r-- | sphinx/util/typing.py | 84 |
1 files changed, 43 insertions, 41 deletions
diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py index d00c3ba09..005599f79 100644 --- a/sphinx/util/typing.py +++ b/sphinx/util/typing.py @@ -299,19 +299,25 @@ def _restify_py36(cls: Optional[Type]) -> str: return ':py:obj:`%s.%s`' % (cls.__module__, qualname) -def stringify(annotation: Any, smartref: bool = False, show_typing: bool = False) -> str: +def stringify(annotation: Any, mode: str = 'fully-qualified-except-typing') -> str: """Stringify type annotation object. - :param smartref: If true, add "~" prefix to the result to remove the leading - module and class names from the reference text - :param show_typing: If true, do not suppress the "typing" module name + :param mode: Specify a method how annotations will be stringified. + + 'fully-qualified-except-typing' + Show the module name and qualified name of the annotation except + the "typing" module. + 'smart' + Show the name of the annotation. + 'fully-qualified' + Show the module name and qualified name of the annotation. """ from sphinx.util import inspect # lazy loading - if smartref: - prefix = '~' + if mode == 'smart': + modprefix = '~' else: - prefix = '' + modprefix = '' if isinstance(annotation, str): if annotation.startswith("'") and annotation.endswith("'"): @@ -320,14 +326,15 @@ def stringify(annotation: Any, smartref: bool = False, show_typing: bool = False else: return annotation elif isinstance(annotation, TypeVar): - if show_typing is False and annotation.__module__ == 'typing': + if (annotation.__module__ == 'typing' and + mode in ('fully-qualified-except-typing', 'smart')): return annotation.__name__ else: - return prefix + '.'.join([annotation.__module__, annotation.__name__]) + return modprefix + '.'.join([annotation.__module__, annotation.__name__]) elif inspect.isNewType(annotation): if sys.version_info > (3, 10): # newtypes have correct module info since Python 3.10+ - return prefix + '%s.%s' % (annotation.__module__, annotation.__name__) + return modprefix + '%s.%s' % (annotation.__module__, annotation.__name__) else: return annotation.__name__ elif not annotation: @@ -335,7 +342,7 @@ def stringify(annotation: Any, smartref: bool = False, show_typing: bool = False elif annotation is NoneType: return 'None' elif annotation in INVALID_BUILTIN_CLASSES: - return prefix + INVALID_BUILTIN_CLASSES[annotation] + return modprefix + INVALID_BUILTIN_CLASSES[annotation] elif str(annotation).startswith('typing.Annotated'): # for py310+ pass elif (getattr(annotation, '__module__', None) == 'builtins' and @@ -348,12 +355,12 @@ def stringify(annotation: Any, smartref: bool = False, show_typing: bool = False return '...' if sys.version_info >= (3, 7): # py37+ - return _stringify_py37(annotation, smartref, show_typing) + return _stringify_py37(annotation, mode) else: - return _stringify_py36(annotation, smartref, show_typing) + return _stringify_py36(annotation, mode) -def _stringify_py37(annotation: Any, smartref: bool = False, show_typing: bool = False) -> str: +def _stringify_py37(annotation: Any, mode: str = 'fully-qualified-except-typing') -> str: """stringify() for py37+.""" module = getattr(annotation, '__module__', None) modprefix = '' @@ -367,19 +374,19 @@ def _stringify_py37(annotation: Any, smartref: bool = False, show_typing: bool = else: qualname = stringify(annotation.__origin__).replace('typing.', '') # ex. Union - if smartref: + if mode == 'smart': modprefix = '~%s.' % module - elif show_typing: + elif mode == 'fully-qualified': modprefix = '%s.' % module elif hasattr(annotation, '__qualname__'): - if smartref: + if mode == 'smart': modprefix = '~%s.' % module else: modprefix = '%s.' % module qualname = annotation.__qualname__ elif hasattr(annotation, '__origin__'): # instantiated generic provided by a user - qualname = stringify(annotation.__origin__, smartref, show_typing) + qualname = stringify(annotation.__origin__, mode) elif UnionType and isinstance(annotation, UnionType): # types.Union (for py3.10+) qualname = 'types.Union' else: @@ -394,15 +401,13 @@ def _stringify_py37(annotation: Any, smartref: bool = False, show_typing: bool = elif qualname in ('Optional', 'Union'): if len(annotation.__args__) > 1 and annotation.__args__[-1] is NoneType: if len(annotation.__args__) > 2: - args = ', '.join(stringify(a, smartref, show_typing) for a - in annotation.__args__[:-1]) + args = ', '.join(stringify(a, mode) for a in annotation.__args__[:-1]) return '%sOptional[%sUnion[%s]]' % (modprefix, modprefix, args) else: - return '%sOptional[%s]' % (modprefix, stringify(annotation.__args__[0], - smartref, show_typing)) + return '%sOptional[%s]' % (modprefix, + stringify(annotation.__args__[0], mode)) else: - args = ', '.join(stringify(a, smartref, show_typing) for a - in annotation.__args__) + args = ', '.join(stringify(a, mode) for a in annotation.__args__) return '%sUnion[%s]' % (modprefix, args) elif qualname == 'types.Union': if len(annotation.__args__) > 1 and None in annotation.__args__: @@ -411,27 +416,25 @@ def _stringify_py37(annotation: Any, smartref: bool = False, show_typing: bool = else: return ' | '.join(stringify(a) for a in annotation.__args__) elif qualname == 'Callable': - args = ', '.join(stringify(a, smartref, show_typing) for a - in annotation.__args__[:-1]) - returns = stringify(annotation.__args__[-1], smartref, show_typing) + args = ', '.join(stringify(a, mode) for a in annotation.__args__[:-1]) + returns = stringify(annotation.__args__[-1], mode) return '%s%s[[%s], %s]' % (modprefix, qualname, args, returns) elif qualname == 'Literal': args = ', '.join(repr(a) for a in annotation.__args__) return '%s%s[%s]' % (modprefix, qualname, args) elif str(annotation).startswith('typing.Annotated'): # for py39+ - return stringify(annotation.__args__[0], smartref, show_typing) + return stringify(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 modprefix + qualname else: - args = ', '.join(stringify(a, smartref, show_typing) for a - in annotation.__args__) + args = ', '.join(stringify(a, mode) for a in annotation.__args__) return '%s%s[%s]' % (modprefix, qualname, args) return modprefix + qualname -def _stringify_py36(annotation: Any, smartref: bool = False, show_typing: bool = False) -> str: +def _stringify_py36(annotation: Any, mode: str = 'fully-qualified-except-typing') -> str: """stringify() for py36.""" module = getattr(annotation, '__module__', None) modprefix = '' @@ -447,12 +450,12 @@ def _stringify_py36(annotation: Any, smartref: bool = False, show_typing: bool = else: qualname = repr(annotation).replace('typing.', '') - if smartref: + if mode == 'smart': modprefix = '~%s.' % module - elif show_typing: + elif mode == 'fully-qualified': modprefix = '%s.' % module elif hasattr(annotation, '__qualname__'): - if smartref: + if mode == 'smart': modprefix = '~%s.' % module else: modprefix = '%s.' % module @@ -464,7 +467,7 @@ def _stringify_py36(annotation: Any, smartref: bool = False, show_typing: bool = not hasattr(annotation, '__tuple_params__')): # for Python 3.6 params = annotation.__args__ if params: - param_str = ', '.join(stringify(p, smartref, show_typing) for p in params) + param_str = ', '.join(stringify(p, mode) for p in params) return '%s%s[%s]' % (modprefix, qualname, param_str) else: return modprefix + qualname @@ -475,12 +478,12 @@ def _stringify_py36(annotation: Any, smartref: bool = False, show_typing: bool = elif annotation.__origin__ == Generator: # type: ignore params = annotation.__args__ # type: ignore else: # typing.Callable - args = ', '.join(stringify(arg, smartref, show_typing) for arg + args = ', '.join(stringify(arg, mode) for arg in annotation.__args__[:-1]) # type: ignore result = stringify(annotation.__args__[-1]) # type: ignore return '%s%s[[%s], %s]' % (modprefix, qualname, args, result) if params is not None: - param_str = ', '.join(stringify(p, smartref, show_typing) for p in params) + param_str = ', '.join(stringify(p, mode) for p in params) return '%s%s[%s]' % (modprefix, qualname, param_str) elif (hasattr(annotation, '__origin__') and annotation.__origin__ is typing.Union): @@ -488,13 +491,12 @@ def _stringify_py36(annotation: Any, smartref: bool = False, show_typing: bool = if params is not None: if len(params) > 1 and params[-1] is NoneType: if len(params) > 2: - param_str = ", ".join(stringify(p, smartref, show_typing) for p - in params[:-1]) + param_str = ", ".join(stringify(p, mode) for p in params[:-1]) return '%sOptional[%sUnion[%s]]' % (modprefix, modprefix, param_str) else: - return '%sOptional[%s]' % (modprefix, stringify(params[0])) + return '%sOptional[%s]' % (modprefix, stringify(params[0], mode)) else: - param_str = ', '.join(stringify(p, smartref, show_typing) for p in params) + param_str = ', '.join(stringify(p, mode) for p in params) return '%sUnion[%s]' % (modprefix, param_str) return modprefix + qualname |