Merge pull request #8142 from jcarrano/typing-generic-signatures

autodoc: fix constructor signatures for classes derived from typing.Generic

sphinx/ext/autodoc/__init__.py

@@ -1325,6 +1325,12 @@ def format_args(self, **kwargs: Any) -> Any:
 ]
 
 
+# Types whose __new__ signature is a pass-thru.
+_CLASS_NEW_BLACKLIST = [
+    'typing.Generic.__new__',
+]
+
+
 class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type: ignore
     """
     Specialized Documenter subclass for classes.
@@ -1393,6 +1399,11 @@ def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
 
         # Now we check if the 'obj' class has a '__new__' method
         new = get_user_defined_function_or_method(self.object, '__new__')
+
+        if new is not None:
+            if "{0.__module__}.{0.__qualname__}".format(new) in _CLASS_NEW_BLACKLIST:
+                new = None
+
         if new is not None:
             self.env.app.emit('autodoc-before-process-signature', new, True)
             try:

tests/roots/test-ext-autodoc/target/generic_class.py

@@ -0,0 +1,12 @@
+from typing import TypeVar, Generic
+
+
+T = TypeVar('T')
+
+
+# Test that typing.Generic's __new__ method does not mask our class'
+# __init__ signature.
+class A(Generic[T]):
+    """docstring for A"""
+    def __init__(self, a, b=None):
+        pass

tests/test_ext_autodoc.py

@@ -290,6 +290,21 @@ def foo3(self, d='\n'):
         '(b, c=42, *d, **e)'
 
 
+@pytest.mark.skipif(sys.version_info < (3, 5), reason='typing is available since python3.5.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodoc_process_signature_typing_generic(app):
+    actual = do_autodoc(app, 'class', 'target.generic_class.A', {})
+
+    assert list(actual) == [
+        '',
+        '.. py:class:: A(a, b=None)',
+        '   :module: target.generic_class',
+        '',
+        '   docstring for A',
+        '',
+    ]
+
+
 def test_autodoc_process_signature_typehints(app):
     captured = []