Updated special dataclass handling (#153)

* Add a protection against dataclass handling errors

The existing test did not have any fields and missed an edge case in a
bugfix python version update.

* Update special dataclass handling

The dataclass generated qualnames were updated in a patch version of
python, likely the update that either caused or fixed https://bugs.python.org/issue34776

Author: Lihu Ben-Ezri-Ravin

sphinx_autodoc_typehints.py

@@ -165,8 +165,20 @@ def process_signature(app, what: str, name: str, obj, options, signature, return
         for param in signature.parameters.values()
     ]
 
-    # The generated dataclass __init__() is weird and needs the second condition
-    if '<locals>' in obj.__qualname__ and not (what == 'method' and name.endswith('.__init__')):
+    # The generated dataclass __init__() and class are weird and need extra checks
+    # This helper function operates on the generated class and methods
+    # of a dataclass, not an instantiated dataclass object. As such,
+    # it cannot be replaced by a call to `dataclasses.is_dataclass()`.
+    def _is_dataclass(name: str, what: str, qualname: str) -> bool:
+        if what == 'method' and name.endswith('.__init__'):
+            # generated __init__()
+            return True
+        if what == 'class' and qualname.endswith('.__init__'):
+            # generated class
+            return True
+        return False
+
+    if '<locals>' in obj.__qualname__ and not _is_dataclass(name, what, obj.__qualname__):
         logger.warning(
             'Cannot treat a function defined as a local function: "%s"  (use @functools.wraps)',
             name)

tests/conftest.py

@@ -1,4 +1,5 @@
 import os
+import re
 import sys
 import pathlib
 import shutil
@@ -42,3 +43,12 @@ def remove_sphinx_projects(sphinx_test_tempdir):
 @pytest.fixture
 def rootdir():
     return path(os.path.dirname(__file__) or '.').abspath() / 'roots'
+
+
+def pytest_ignore_collect(path, config):
+    version_re = re.compile(r'_py(\d)(\d)\.py$')
+    match = version_re.search(path.basename)
+    if match:
+        version = tuple(int(x) for x in match.groups())
+        if sys.version_info < version:
+            return True

tests/roots/test-dataclass/conf.py

@@ -0,0 +1,15 @@
+import pathlib
+import sys
+
+
+# Make dataclass_module.py available for autodoc.
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+
+master_doc = 'index'
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_autodoc_typehints',
+    ]

tests/roots/test-dataclass/dataclass_module.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class DataClass:
+    """Class docstring."""
+
+    x: int

tests/roots/test-dataclass/index.rst

@@ -0,0 +1,6 @@
+Dataclass Module
+================
+
+.. autoclass:: dataclass_module.DataClass
+    :undoc-members:
+    :special-members: __init__

tests/roots/test-dummy/dummy_module.py

@@ -235,11 +235,6 @@ def undocumented_function(x: int) -> str:
     return str(x)
 
 
-@dataclass
-class DataClass:
-    """Class docstring."""
-
-
 class Decorator:
     """
     Initializer docstring.

tests/test_dataclass_py36.py

@@ -0,0 +1,48 @@
+import pathlib
+import sys
+import textwrap
+
+import pytest
+
+
+@pytest.mark.parametrize('always_document_param_types', [True, False])
+@pytest.mark.sphinx('text', testroot='dataclass')
+def test_sphinx_output(app, status, warning, always_document_param_types):
+    test_path = pathlib.Path(__file__).parent
+
+    # Add test directory to sys.path to allow imports of dummy module.
+    if str(test_path) not in sys.path:
+        sys.path.insert(0, str(test_path))
+
+    app.config.always_document_param_types = always_document_param_types
+    app.build()
+
+    assert 'build succeeded' in status.getvalue()  # Build succeeded
+
+    format_args = {}
+    if always_document_param_types:
+        for indentation_level in range(3):
+            format_args['undoc_params_{}'.format(indentation_level)] = textwrap.indent(
+                '\n\n   Parameters:\n      **x** ("int") --', '   ' * indentation_level
+            )
+    else:
+        for indentation_level in range(3):
+            format_args['undoc_params_{}'.format(indentation_level)] = ''
+
+    text_path = pathlib.Path(app.srcdir) / '_build' / 'text' / 'index.txt'
+    with text_path.open('r') as f:
+        text_contents = f.read().replace('–', '--')
+        expected_contents = textwrap.dedent('''\
+        Dataclass Module
+        ****************
+
+        class dataclass_module.DataClass(x)
+
+           Class docstring.{undoc_params_0}
+
+           __init__(x)
+
+              Initialize self.  See help(type(self)) for accurate signature.{undoc_params_1}
+        ''')
+        expected_contents = expected_contents.format(**format_args).replace('–', '--')
+        assert text_contents == expected_contents

tests/test_sphinx_autodoc_typehints.py

@@ -226,7 +226,7 @@ def test_sphinx_output(app, status, warning, always_document_param_types):
     if always_document_param_types:
         format_args['undoc_params'] = '\n\n   Parameters:\n      **x** ("int") --'
     else:
-        format_args['undoc_params'] = ""
+        format_args['undoc_params'] = ''
 
     text_path = pathlib.Path(app.srcdir) / '_build' / 'text' / 'index.txt'
     with text_path.open('r') as f:
@@ -474,14 +474,6 @@ class dummy_module.ClassWithTypehintsNotInline(x=None)
            Return type:
               "str"
 
-        class dummy_module.DataClass
-
-           Class docstring.
-
-           __init__()
-
-              Initialize self.  See help(type(self)) for accurate signature.
-
         @dummy_module.Decorator(func)
 
            Initializer docstring.