BUG: Avoid as much as touching __pdoc__-blacklisted objects

Fixes #285

Author: kernc

pdoc/__init__.py

@@ -66,6 +66,15 @@
     tpl_lookup.directories.insert(0, path.join(os.getenv("XDG_CONFIG_HOME", ''), "pdoc"))
 
 
+# A surrogate so that the check in Module._link_inheritance()
+# "__pdoc__-overriden key {!r} does not exist" can pick the object up
+# (and not warn).
+# If you know how to keep the warning, but skip the object creation
+# altogether, please make it happen!
+class _BLACKLISTED_DUMMY:
+    pass
+
+
 class Context(dict):
     """
     The context object that maps all documented identifiers
@@ -90,7 +99,9 @@ def reset():
     _global_context.clear()
 
     # Clear LRU caches
-    for func in (_get_type_hints,):
+    for func in (_get_type_hints,
+                 _is_blacklisted,
+                 _is_whitelisted):
         func.cache_clear()
     for cls in (Doc, Module, Class, Function, Variable, External):
         for _, method in inspect.getmembers(cls):
@@ -318,6 +329,7 @@ def _pep224_docstrings(doc_obj: Union['Module', 'Class'], *,
     return vars, instance_vars
 
 
+@lru_cache()
 def _is_whitelisted(name: str, doc_obj: Union['Module', 'Class']):
     """
     Returns `True` if `name` (relative or absolute refname) is
@@ -333,6 +345,7 @@ def _is_whitelisted(name: str, doc_obj: Union['Module', 'Class']):
     return False
 
 
+@lru_cache()
 def _is_blacklisted(name: str, doc_obj: Union['Module', 'Class']):
     """
     Returns `True` if `name` (relative or absolute refname) is
@@ -624,24 +637,32 @@ def __init__(self, module: Union[ModuleType, str], *, docfilter: Callable[[Doc],
             public_objs = []
             for name in self.obj.__all__:
                 try:
-                    public_objs.append((name, getattr(self.obj, name)))
+                    obj = getattr(self.obj, name)
                 except AttributeError:
                     warn("Module {!r} doesn't contain identifier `{}` "
                          "exported in `__all__`".format(self.module, name))
+                if not _is_blacklisted(name, self):
+                    obj = inspect.unwrap(obj)
+                public_objs.append((name, obj))
         else:
             def is_from_this_module(obj):
                 mod = inspect.getmodule(inspect.unwrap(obj))
                 return mod is None or mod.__name__ == self.obj.__name__
 
-            public_objs = [(name, inspect.unwrap(obj))
+            public_objs = [(name, (_BLACKLISTED_DUMMY
+                                   if _is_blacklisted(name, self) else
+                                   inspect.unwrap(obj)))
                            for name, obj in inspect.getmembers(self.obj)
                            if ((_is_public(name) or _is_whitelisted(name, self)) and
-                               (is_from_this_module(obj) or name in var_docstrings))]
+                               (_is_blacklisted(name, self) or  # skips unwrapping that follows
+                                is_from_this_module(obj) or name in var_docstrings))]
             index = list(self.obj.__dict__).index
             public_objs.sort(key=lambda i: index(i[0]))
 
         for name, obj in public_objs:
-            if _is_function(obj):
+            if obj is _BLACKLISTED_DUMMY:
+                self.doc[name] = Variable(name, self, 'dummy', obj=obj)
+            elif _is_function(obj):
                 self.doc[name] = Function(name, self, obj)
             elif inspect.isclass(obj):
                 self.doc[name] = Class(name, self, obj)
@@ -955,7 +976,9 @@ def __init__(self, name, module, obj, *, docstring=None):
         # Use only own, non-inherited annotations (the rest will be inherited)
         annotations = getattr(self.obj, '__annotations__', {})
 
-        public_objs = [(_name, inspect.unwrap(obj))
+        public_objs = [(_name, (_BLACKLISTED_DUMMY
+                                if _is_blacklisted(_name, self) else
+                                inspect.unwrap(obj)))
                        for _name, obj in _getmembers_all(self.obj)
                        # Filter only *own* members. The rest are inherited
                        # in Class._fill_inheritance()
@@ -981,7 +1004,9 @@ def definition_order_index(
 
         # Convert the public Python objects to documentation objects.
         for name, obj in public_objs:
-            if _is_function(obj):
+            if obj is _BLACKLISTED_DUMMY:
+                self.doc[name] = Variable(name, self.module, 'dummy', obj=obj, cls=self)
+            elif _is_function(obj):
                 self.doc[name] = Function(
                     name, self.module, obj, cls=self)
             else:

pdoc/test/__init__.py

@@ -19,6 +19,7 @@
 from random import randint
 from tempfile import TemporaryDirectory
 from time import sleep
+from types import ModuleType
 from unittest.mock import patch
 from urllib.error import HTTPError
 from urllib.request import Request, urlopen
@@ -35,6 +36,9 @@
 TESTS_BASEDIR = os.path.abspath(os.path.dirname(__file__) or '.')
 EXAMPLE_MODULE = 'example_pkg'
 
+EMPTY_MODULE = ModuleType('empty')
+EMPTY_MODULE.__pdoc__ = {}
+
 sys.path.insert(0, TESTS_BASEDIR)
 
 T = typing.TypeVar("T")
@@ -608,6 +612,30 @@ def test__pdoc__dict(self):
             self.assertEqual(cm, [])
             self.assertNotIn('downloaded_modules', mod.doc)
 
+    @ignore_warnings
+    def test_dont_touch__pdoc__blacklisted(self):
+        class Bomb:
+            def __getattribute__(self, item):
+                raise RuntimeError
+
+        class D:
+            x = Bomb()
+            """doc"""
+            __qualname__ = 'D'
+
+        module = EMPTY_MODULE
+        D.__module__ = module.__name__  # Need to match is_from_this_module check
+        with patch.object(module, 'x', Bomb(), create=True), \
+             patch.object(module, '__pdoc__', {'x': False}):
+            mod = pdoc.Module(module)
+            pdoc.link_inheritance()
+            self.assertNotIn('x', mod.doc)
+        with patch.object(module, 'D', D, create=True), \
+             patch.object(module, '__pdoc__', {'D.x': False}):
+            mod = pdoc.Module(module)
+            pdoc.link_inheritance()
+            self.assertNotIn('x', mod.doc['D'].doc)
+
     def test__pdoc__invalid_value(self):
         module = pdoc.import_module(EXAMPLE_MODULE)
         with patch.object(module, '__pdoc__', {'B': 1}), \