Add test for forward refs (#20)

Author: flying-sheep

.travis.yml

@@ -5,14 +5,18 @@ branches:
   only:
   - master  # use PR builder only for other branches
 python:
-  - '3.6'
-  - '3.7'
-  - '3.8'
+- '3.6'
+# Travis uses old versions if you specify 3.x,
+# and elegant_typehints trigger a Python bug in those.
+# There seems to be no way to specify the newest patch version,
+# so I’ll just use the newest available at the time of writing.
+- '3.7.9'
+- '3.8.5'
 
 install:
-  - pip install flit codecov
-  - flit install --deps develop
+- pip install flit codecov
+- flit install --deps develop
 script:
-  - PYTHONPATH=. pytest --cov=scanpydoc --black
-  - rst2html.py --halt=2 README.rst >/dev/null
+- PYTHONPATH=. pytest --cov=scanpydoc --black
+- rst2html.py --halt=2 README.rst >/dev/null
 after_success: codecov

scanpydoc/elegant_typehints/return_tuple.py

@@ -1,5 +1,6 @@
 import inspect
 import re
+from logging import getLogger
 from typing import get_type_hints, Any, Union, Optional, Type, Tuple, List
 
 from sphinx.application import Sphinx
@@ -8,6 +9,7 @@
 from .formatting import format_both
 
 
+logger = getLogger(__name__)
 re_ret = re.compile("^:returns?: ")
 
 
@@ -43,7 +45,15 @@ def process_docstring(
     if what in ("class", "exception"):
         obj = obj.__init__
     obj = inspect.unwrap(obj)
-    ret_types = get_tuple_annot(get_type_hints(obj).get("return"))
+    try:
+        hints = get_type_hints(obj)
+    except (AttributeError, TypeError):
+        # Introspecting a slot wrapper will raise TypeError
+        return
+    except NameError as e:
+        check_bpo_34776(obj, e)
+        return
+    ret_types = get_tuple_annot(hints.get("return"))
     if ret_types is None:
         return
 
@@ -87,3 +97,20 @@ def process_docstring(
 #     return_annotation: str,
 # ) -> Optional[Tuple[Optional[str], Optional[str]]]:
 #     return signature, return_annotation
+
+
+def check_bpo_34776(obj: Any, e: NameError):
+    import sys
+
+    ancient = sys.version_info < (3, 7)
+    old_3_7 = (3, 7) < sys.version_info < (3, 7, 6)
+    old_3_8 = (3, 8) < sys.version_info < (3, 8, 1)
+    if ancient or old_3_7 or old_3_8:
+        v = ".".join(map(str, sys.version_info[:3]))
+        logger.warning(
+            f"Error documenting {obj!r}: To avoid this, "
+            f"your Python version {v} must be at least 3.7.6 or 3.8.1. "
+            "For more information see https://bugs.python.org/issue34776"
+        )
+    else:
+        raise e  # No idea what happened

tests/conftest.py

@@ -1,5 +1,8 @@
+import importlib.util
+import sys
 import typing as t
 from tempfile import NamedTemporaryFile
+from textwrap import dedent
 
 import pytest
 from docutils.nodes import document
@@ -49,3 +52,21 @@ def _render(app: Sphinx, doc: document) -> str:
         return writer.output
 
     return _render
+
+
+@pytest.fixture
+def make_module():
+    added_modules = []
+
+    def make_module(name, code):
+        assert name not in sys.modules
+        spec = importlib.util.spec_from_loader(name, loader=None)
+        mod = sys.modules[name] = importlib.util.module_from_spec(spec)
+        exec(dedent(code), mod.__dict__)
+        added_modules.append(name)
+        return mod
+
+    yield make_module
+
+    for name in added_modules:
+        del sys.modules[name]

tests/test_elegant_typehints.py

@@ -22,11 +22,17 @@
 from scanpydoc.elegant_typehints.return_tuple import process_docstring
 
 
-_testmod = sys.modules["_testmod"] = ModuleType("_testmod")
-_testmod.Class = type("Class", (), dict(__module__="_testmod"))
-_testmod.SubCl = type("SubCl", (_testmod.Class,), dict(__module__="_testmod"))
-_testmod.Excep = type("Excep", (RuntimeError,), dict(__module__="_testmod"))
-_testmod.Excep2 = type("Excep2", (_testmod.Excep,), dict(__module__="_testmod"))
+@pytest.fixture
+def _testmod(make_module):
+    return make_module(
+        "_testmod",
+        """\
+        class Class: pass
+        class SubCl(Class): pass
+        class Excep(RuntimeError): pass
+        class Excep2(Excep): pass
+        """,
+    )
 
 
 @pytest.fixture
@@ -150,17 +156,17 @@ def test_literal(app):
     )
 
 
-def test_qualname_overrides_class(app):
+def test_qualname_overrides_class(app, _testmod):
     assert _testmod.Class.__module__ == "_testmod"
     assert _format_terse(_testmod.Class) == ":py:class:`~test.Class`"
 
 
-def test_qualname_overrides_exception(app):
+def test_qualname_overrides_exception(app, _testmod):
     assert _testmod.Excep.__module__ == "_testmod"
     assert _format_terse(_testmod.Excep) == ":py:exc:`~test.Excep`"
 
 
-def test_qualname_overrides_recursive(app):
+def test_qualname_overrides_recursive(app, _testmod):
     assert _format_terse(t.Union[_testmod.Class, str]) == (
         r":py:class:`~test.Class`, :py:class:`str`"
     )
@@ -172,7 +178,7 @@ def test_qualname_overrides_recursive(app):
     )
 
 
-def test_fully_qualified(app):
+def test_fully_qualified(app, _testmod):
     assert _format_terse(t.Union[_testmod.Class, str], True) == (
         r":py:class:`test.Class`, :py:class:`str`"
     )
@@ -237,7 +243,7 @@ def test_typing_class_nested(app):
         ("autoexception", "Excep", "Excep2"),
     ],
 )
-def test_autodoc(app, direc, base, sub):
+def test_autodoc(app, _testmod, direc, base, sub):
     Path(app.srcdir, "index.rst").write_text(
         f"""\
 .. {direc}:: _testmod.{sub}
@@ -252,6 +258,45 @@ def test_autodoc(app, direc, base, sub):
     assert re.search(rf"Bases: <code[^>]*><span[^>]*>test\.{base}", out), out
 
 
+@pytest.mark.skipif(sys.version_info < (3, 7), reason="bpo-34776 only fixed on 3.7+")
+def test_fwd_ref(app, make_module):
+    make_module(
+        "fwd_mod",
+        """\
+        from dataclasses import dataclass
+
+        @dataclass
+        class A:
+           b: 'B'
+
+        @dataclass
+        class B:
+            a: A
+        """,
+    )
+    Path(app.srcdir, "index.rst").write_text(
+        f"""\
+.. autosummary::
+
+   fwd_mod.A
+   fwd_mod.B
+"""
+    )
+    app.setup_extension("sphinx.ext.autosummary")
+
+    app.build()
+
+    out = Path(app.outdir, "index.html").read_text()
+    warnings = [
+        w
+        for w in app._warning.getvalue().splitlines()
+        if "Cannot treat a function defined as a local function" not in w
+    ]
+    assert not warnings, warnings
+    # TODO: actually reproduce #14
+    assert "fwd_mod.A" in out, out
+
+
 @pytest.mark.parametrize(
     "docstring",
     [