BUG: Rewrite inspect.unwrap() to respect classes

Fixes #463

Post-review changes:
* Remove argument `stop` from `pdoc._unwrap_object()`
* Fix flake8 errors

Author: USSX-Hares

pdoc/__init__.py

@@ -449,6 +449,39 @@ def _unwrap_descriptor(dobj):
     return getattr(obj, '__get__', obj)
 
 
+def _unwrap_object(obj: T) -> T:
+    """
+    This is a modified version of `inspect.unwrap()` that properly handles classes.
+
+    Follows the chains of `__wrapped__` attributes, until either:
+    1. `obj.__wrapped__` is missing or None
+    2. `obj` is a class and `obj.__wrapped__` has a different name or module
+    """
+
+    orig = obj  # remember the original func for error reporting
+    # Memoise by id to tolerate non-hashable objects, but store objects to
+    # ensure they aren't destroyed, which would allow their IDs to be reused.
+    memo = {id(orig): orig}
+    recursion_limit = sys.getrecursionlimit()
+    while hasattr(obj, '__wrapped__'):
+        candidate = obj.__wrapped__
+        if candidate is None:
+            break
+
+        if isinstance(candidate, type) and isinstance(orig, type):
+            if not (candidate.__name__ == orig.__name__
+                    and candidate.__module__ == orig.__module__):
+                break
+
+        obj = typing.cast(T, candidate)
+        id_func = id(obj)
+        if (id_func in memo) or (len(memo) >= recursion_limit):
+            raise ValueError('wrapper loop when unwrapping {!r}'.format(orig))
+        memo[id_func] = obj
+
+    return obj
+
+
 def _filter_type(type: Type[T],
                  values: Union[Iterable['Doc'], Mapping[str, 'Doc']]) -> List[T]:
     """
@@ -712,11 +745,11 @@ def __init__(self, module: Union[ModuleType, str], *,
                          "exported in `__all__`")
                 else:
                     if not _is_blacklisted(name, self):
-                        obj = inspect.unwrap(obj)
+                        obj = _unwrap_object(obj)
                     public_objs.append((name, obj))
         else:
             def is_from_this_module(obj):
-                mod = inspect.getmodule(inspect.unwrap(obj))
+                mod = inspect.getmodule(_unwrap_object(obj))
                 return mod is None or mod.__name__ == self.obj.__name__
 
             for name, obj in inspect.getmembers(self.obj):
@@ -730,7 +763,7 @@ def is_from_this_module(obj):
                         self._context.blacklisted.add(f'{self.refname}.{name}')
                         continue
 
-                    obj = inspect.unwrap(obj)
+                    obj = _unwrap_object(obj)
                     public_objs.append((name, obj))
 
             index = list(self.obj.__dict__).index
@@ -1066,7 +1099,7 @@ def __init__(self, name: str, module: Module, obj, *, docstring: Optional[str] =
                     self.module._context.blacklisted.add(f'{self.refname}.{_name}')
                     continue
 
-                obj = inspect.unwrap(obj)
+                obj = _unwrap_object(obj)
                 public_objs.append((_name, obj))
 
         def definition_order_index(
@@ -1428,7 +1461,7 @@ def _is_async(self):
         try:
             # Both of these are required because coroutines aren't classified as async
             # generators and vice versa.
-            obj = inspect.unwrap(self.obj)
+            obj = _unwrap_object(self.obj)
             return (inspect.iscoroutinefunction(obj) or
                     inspect.isasyncgenfunction(obj))
         except AttributeError:

pdoc/cli.py

@@ -574,7 +574,7 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
         _print_pdf(modules, **template_config)
         import textwrap
         PANDOC_CMD = textwrap.indent(_PANDOC_COMMAND, '    ')
-        print(f"""
+        help_msg = f"""
 PDF-ready markdown written to standard output.
                               ^^^^^^^^^^^^^^^
 Convert this file to PDF using e.g. Pandoc:
@@ -600,7 +600,7 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
     wkhtmltopdf --encoding utf8 -s A4 --print-media-type pdf.html pdf.pdf
 
 or similar, at your own discretion.""",
-              file=sys.stderr)
+        print(help_msg, file=sys.stderr)
         sys.exit(0)
 
     for module in modules:

pdoc/html_helpers.py

@@ -565,7 +565,7 @@ def format_git_link(template: str, dobj: pdoc.Doc):
         if 'commit' in _str_template_fields(template):
             commit = _git_head_commit()
         obj = pdoc._unwrap_descriptor(dobj)
-        abs_path = inspect.getfile(inspect.unwrap(obj))
+        abs_path = inspect.getfile(pdoc._unwrap_object(obj))
         path = _project_relative_path(abs_path)
 
         # Urls should always use / instead of \\

pdoc/test/__init__.py

@@ -659,7 +659,6 @@ def test__pdoc__dict(self):
             self.assertEqual(cm, [])
             self.assertNotIn('downloaded_modules', mod.doc)
 
-    # flake8: noqa: E501 line too long
     def test_class_wrappers(self):
         """
         Check that decorated classes are unwrapped properly.
@@ -685,15 +684,15 @@ def test_class_wrappers(self):
                          """This is `DecoratedClassParent` class.""")
         self.assertEqual(root_wrapped_cls_child.qualname, 'DecoratedClassChild')
         self.assertEqual(root_wrapped_cls_child.docstring,
-                         """This is an `DecoratedClassParent`'s implementation that always returns 1.""")
+                         """This is an `DecoratedClassParent`'s implementation that always returns 1.""")  # noqa: E501 [LineTooLong]
 
         self.assertEqual(module_classdef.qualname, f'{module_name}.class_definition')
         self.assertEqual(module_classdef_cls_parent.qualname, 'DecoratedClassParent')
         self.assertEqual(module_classdef_cls_parent.docstring,
                          """This is `DecoratedClassParent` class.""")
         self.assertEqual(module_classdef_cls_child.qualname, 'DecoratedClassChild')
         self.assertEqual(module_classdef_cls_child.docstring,
-                         """This is an `DecoratedClassParent`'s implementation that always returns 1.""")
+                         """This is an `DecoratedClassParent`'s implementation that always returns 1.""")  # noqa: E501 [LineTooLong]
 
         self.assertEqual(module_util.qualname, f'{module_name}.util')
         self.assertEqual(module_util_decorator.qualname, 'decorate_class')