Merge branch '3.x' into 7650_undecorated_signature

CHANGES

@@ -88,6 +88,10 @@ Bugs fixed
   autodoc_typehints='description' mode
 * #7551: autodoc: failed to import nested class
 * #7362: autodoc: does not render correct signatures for built-in functions
+* #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as
+  ``Union[foo, bar, None]``
+* #7629: autodoc: autofunction emits an unfriendly warning if an invalid object
+  specified
 * #7650: autodoc: undecorated signature is shown for decorated functions
 * #7551: autosummary: a nested class is indexed as non-nested class
 * #7535: sphinx-autogen: crashes when custom template uses inheritance

sphinx/domains/cpp.py

@@ -3722,8 +3722,8 @@ class LookupKey:
 class Symbol:
     debug_indent = 0
     debug_indent_string = "  "
-    debug_lookup = False
+    debug_lookup = False  # overridden by the corresponding config value
-    debug_show_tree = False
+    debug_show_tree = False  # overridden by the corresponding config value
 
     @staticmethod
     def debug_print(*args: Any) -> None:
@@ -7383,9 +7383,18 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("cpp_paren_attributes", [], 'env')
     app.add_post_transform(AliasTransform)
 
+    # debug stuff
+    app.add_config_value("cpp_debug_lookup", False, '')
+    app.add_config_value("cpp_debug_show_tree", False, '')
+
+    def setDebugFlags(app):
+        Symbol.debug_lookup = app.config.cpp_debug_lookup
+        Symbol.debug_show_tree = app.config.cpp_debug_show_tree
+    app.connect("builder-inited", setDebugFlags)
+
     return {
         'version': 'builtin',
-        'env_version': 2,
+        'env_version': 3,
         'parallel_read_safe': True,
         'parallel_write_safe': True,
     }

sphinx/ext/autodoc/__init__.py

@@ -942,7 +942,7 @@ class ClassLevelDocumenter(Documenter):
 
             try:
                 modname, qualname = split_full_qualified_name(mod_cls)
-                parents = qualname.split(".")
+                parents = qualname.split(".") if qualname else []
             except ImportError:
                 parents = mod_cls.split(".")
 
@@ -1058,7 +1058,11 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
             else:
                 sig = inspect.signature(self.object)
             args = stringify_signature(sig, **kwargs)
-        except TypeError:
+        except TypeError as exc:
+            logger.warning(__("Failed to get a function signature for %s: %s"),
+                           self.fullname, exc)
+            return None
+        except ValueError:
             args = ''
 
         if self.env.config.strip_signature_backslash:
@@ -1470,6 +1474,10 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
                     else:
                         sig = inspect.signature(self.object, bound_method=True)
                 args = stringify_signature(sig, **kwargs)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a method signature for %s: %s"),
+                           self.fullname, exc)
+            return None
         except ValueError:
             args = ''
 

sphinx/util/typing.py

@@ -91,11 +91,15 @@ def _stringify_py37(annotation: Any) -> str:
 
     if getattr(annotation, '__args__', None):
         if qualname == 'Union':
-            if len(annotation.__args__) == 2 and annotation.__args__[1] is NoneType:  # type: ignore  # NOQA
+            if len(annotation.__args__) > 1 and annotation.__args__[-1] is NoneType:  # type: ignore  # NOQA
+                if len(annotation.__args__) > 2:
+                    args = ', '.join(stringify(a) for a in annotation.__args__[:-1])
+                    return 'Optional[Union[%s]]' % args
+                else:
                     return 'Optional[%s]' % stringify(annotation.__args__[0])
             else:
                 args = ', '.join(stringify(a) for a in annotation.__args__)
-                return '%s[%s]' % (qualname, args)
+                return 'Union[%s]' % args
         elif qualname == 'Callable':
             args = ', '.join(stringify(a) for a in annotation.__args__[:-1])
             returns = stringify(annotation.__args__[-1])
@@ -170,7 +174,11 @@ def _stringify_py36(annotation: Any) -> str:
           annotation.__origin__ is typing.Union):  # for Python 3.5.2+
         params = annotation.__args__
         if params is not None:
-            if len(params) == 2 and params[1] is NoneType:  # type: ignore
+            if len(params) > 1 and params[-1] is NoneType:  # type: ignore
+                if len(params) > 2:
+                    param_str = ", ".join(stringify(p) for p in params[:-1])
+                    return 'Optional[Union[%s]]' % param_str
+                else:
                     return 'Optional[%s]' % stringify(params[0])
             else:
                 param_str = ', '.join(stringify(p) for p in params)

tests/test_util_inspect.py

@@ -127,7 +127,7 @@ def test_signature_partialmethod():
 
 def test_signature_annotations():
     from typing_test_data import (f0, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10,
-                                  f11, f12, f13, f14, f15, f16, f17, f18, f19, Node)
+                                  f11, f12, f13, f14, f15, f16, f17, f18, f19, f20, Node)
 
     # Class annotations
     sig = inspect.signature(f0)
@@ -184,6 +184,10 @@ def test_signature_annotations():
     sig = inspect.signature(f13)
     assert stringify_signature(sig) == '() -> Optional[str]'
 
+    # optional union
+    sig = inspect.signature(f20)
+    assert stringify_signature(sig) == '() -> Optional[Union[int, str]]'
+
     # Any
     sig = inspect.signature(f14)
     assert stringify_signature(sig) == '() -> Any'

tests/typing_test_data.py

@@ -96,6 +96,10 @@ def f19(*args: int, **kwargs: str):
     pass
 
 
+def f20() -> Optional[Union[int, str]]:
+    pass
+
+
 
 class Node:
     def __init__(self, parent: Optional['Node']) -> None: