Visit Try 'orelse', 'finalbody' and 'handlers' and If 'orelse'

pydoctor/astbuilder.py

@@ -1,6 +1,7 @@
 """Convert ASTs into L{pydoctor.model.Documentable} instances."""
 
 import ast
+import contextlib
 import sys
 from attr import attrs, attrib
 from functools import partial
@@ -201,7 +202,39 @@ def __init__(self, builder: 'ASTBuilder', module: model.Module):
         self.builder = builder
         self.system = builder.system
         self.module = module
+        self._override_guard_state: Tuple[bool, model.Documentable, Sequence[str]] = \
+                                    (False, cast(model.Documentable, None), [])
+
+    @contextlib.contextmanager
+    def override_guard(self) -> Iterator[None]:
+        """
+        Returns a context manager that will make the builder ignore any extraneous 
+        assigments to existing names within the same context.  
+
+        @note: The list of existing names is generated at the moment of
+            calling the function.
+        """
+        current = self.builder.current
+        ignore_override_init = self._override_guard_state
+        # we list names only once to ignore new names added inside the block,
+        # they should be overriden as usual.
+        self._override_guard_state = (True, current, self._list_names(current))
+        yield
+        self._override_guard_state = ignore_override_init
+
+    def _list_names(self, ob: model.Documentable) -> List[str]:
+        """
+        List the names currently defined in a class/module.
+        """
+        names = list(ob.contents)
+        if isinstance(ob, model.CanContainImportsDocumentable):
+            names.extend(ob._localNameToFullName_map)
+        return names
 
+    def _name_in_override_guard(self, ob: model.Documentable, name:str) -> bool:
+        return self._override_guard_state[0] is True \
+            and self._override_guard_state[1] is ob \
+                and name in self._override_guard_state[2]
 
     def visit_If(self, node: ast.If) -> None:
         if isinstance(node.test, ast.Compare):
@@ -210,6 +243,28 @@ def visit_If(self, node: ast.If) -> None:
                 # whatever is declared in them cannot be imported
                 # and thus is not part of the API
                 raise self.SkipNode()
+
+    def depart_If(self, node: ast.If) -> None:
+        # At this point the body of the Try node has already been visited
+        # Visit the 'orelse' block of the If node, with override guard
+        with self.override_guard():
+            for n in node.orelse:
+                self.walkabout(n)
+
+    def depart_Try(self, node: ast.Try) -> None:
+        # At this point the body of the Try node has already been visited
+        # Visit the 'orelse' and 'finalbody' blocks of the Try node.
+
+        for n in node.orelse:
+            self.walkabout(n)
+        for n in node.finalbody:
+            self.walkabout(n)
+
+        # Visit the handlers with override guard
+        with self.override_guard():
+            for h in node.handlers:
+                for n in h.body:
+                    self.walkabout(n)
 
     def visit_Module(self, node: ast.Module) -> None:
         assert self.module.docstring is None
@@ -227,6 +282,9 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
         parent = self.builder.current
         if isinstance(parent, model.Function):
             raise self.SkipNode()
+        # Ignore in override guard
+        if self._name_in_override_guard(parent, node.name):
+            raise self.SkipNode()
 
         rawbases = []
         bases = []
@@ -328,6 +386,11 @@ def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
     def _importAll(self, modname: str) -> None:
         """Handle a C{from <modname> import *} statement."""
 
+        # Always ignore import * in override guard
+        if self._override_guard_state[0]:
+            self.builder.warning("ignored import * from", modname)
+            return
+
         mod = self.system.getProcessedModule(modname)
         if mod is None:
             # We don't have any information about the module, so we don't know
@@ -420,7 +483,11 @@ def _importNames(self, modname: str, names: Iterable[ast.alias]) -> None:
             orgname, asname = al.name, al.asname
             if asname is None:
                 asname = orgname
-
+
+            # Ignore in override guard
+            if self._name_in_override_guard(current, asname):
+                continue
+
             if mod is not None and self._handleReExport(exports, orgname, asname, mod) is True:
                 continue
 
@@ -449,9 +516,14 @@ def visit_Import(self, node: ast.Import) -> None:
                                  str(self.builder.current))
             return
         _localNameToFullName = self.builder.current._localNameToFullName_map
+        current = self.builder.current
         for al in node.names:
             fullname, asname = al.name, al.asname
+            # Ignore in override guard
+            if self._name_in_override_guard(current, asname or fullname):
+                continue
             if asname is not None:
+                # Do not create an alias with the same name as value
                 _localNameToFullName[asname] = fullname
 
 
@@ -729,6 +801,8 @@ def _handleAssignment(self,
         if isinstance(targetNode, ast.Name):
             target = targetNode.id
             scope = self.builder.current
+            if self._name_in_override_guard(scope, target):
+                return
             if isinstance(scope, model.Module):
                 self._handleAssignmentInModule(target, annotation, expr, lineno)
             elif isinstance(scope, model.Class):
@@ -788,6 +862,9 @@ def _handleFunctionDef(self,
         parent = self.builder.current
         if isinstance(parent, model.Function):
             raise self.SkipNode()
+        # Ignore in override guard
+        if self._name_in_override_guard(parent, node.name):
+            raise self.SkipNode()
 
         lineno = node.lineno
 

pydoctor/extensions/deprecate.py

@@ -60,7 +60,8 @@ def depart_ClassDef(self, node:ast.ClassDef) -> None:
         except KeyError:
             # Classes inside functions are ignored.
             return
-        assert isinstance(cls, model.Class)
+        if not isinstance(cls, model.Class):
+            return
         getDeprecated(cls, node.decorator_list)
 
     def depart_FunctionDef(self, node:ast.FunctionDef) -> None:
@@ -73,7 +74,8 @@ def depart_FunctionDef(self, node:ast.FunctionDef) -> None:
         except KeyError:
             # Inner functions are ignored.
             return
-        assert isinstance(func, (model.Function, model.Attribute))
+        if not isinstance(func, (model.Function, model.Attribute)):
+            return
         getDeprecated(func, node.decorator_list)
 
 _incremental_Version_signature = inspect.signature(Version)

pydoctor/test/test_astbuilder.py

@@ -2075,3 +2075,230 @@ class j: pass
     assert system.allobjects['top._impl'].resolveName('f') == system.allobjects['top'].contents['f']
     assert system.allobjects['_impl2'].resolveName('i') == system.allobjects['top'].contents['i']
     assert all(n in system.allobjects['top'].contents for n in  ['f', 'g', 'h', 'i', 'j'])
+
+@systemcls_param
+def test_module_level_attributes_and_aliases(systemcls: Type[model.System]) -> None:
+    """
+    Currently, the first analyzed assigment wins, basically. I believe further logic should be added
+    such that definitions in the orelse clause of the Try node is processed before the 
+    except handlers. This way could define our aliases both there and in the body of the
+    Try node and fall back to what's defnied in the handlers if the names doesn't exist yet.
+    """
+    system = systemcls()
+    builder = system.systemBuilder(system)
+    builder.addModuleString('''
+    ssl = 1
+    ''', modname='twisted.internet')
+    builder.addModuleString('''
+    try:
+        from twisted.internet import ssl as _ssl
+        # The names defined in the body of the if block wins over the
+        # names defined in the except handler
+        ssl = _ssl
+        var = 1
+        VAR = 1
+        ALIAS = _ssl
+    except ImportError:
+        ssl = None
+        var = 2
+        VAR = 2
+        ALIAS = None
+    ''', modname='mod')
+    builder.buildModules()
+    mod = system.allobjects['mod']
+
+    # Test alias
+    assert mod.expandName('ssl')=="twisted.internet.ssl"
+    assert mod.expandName('_ssl')=="twisted.internet.ssl"
+    s = mod.resolveName('ssl')
+    assert isinstance(s, model.Attribute)
+    assert s.value is not None
+    assert ast.literal_eval(s.value)==1
+    assert s.kind == model.DocumentableKind.VARIABLE
+
+    # Test variable
+    assert mod.expandName('var')=="mod.var"
+    v = mod.resolveName('var')
+    assert isinstance(v, model.Attribute)
+    assert v.value is not None
+    assert ast.literal_eval(v.value)==1
+    assert v.kind == model.DocumentableKind.VARIABLE
+
+    # Test constant
+    assert mod.expandName('VAR')=="mod.VAR"
+    V = mod.resolveName('VAR')
+    assert isinstance(V, model.Attribute)
+    assert V.value is not None
+    assert ast.literal_eval(V.value)==1
+    assert V.kind == model.DocumentableKind.CONSTANT
+
+    # Test looks like constant but actually an alias.
+    assert mod.expandName('ALIAS')=="twisted.internet.ssl"
+    s = mod.resolveName('ALIAS')
+    assert isinstance(s, model.Attribute)
+    assert s.value is not None
+    assert ast.literal_eval(s.value)==1
+    assert s.kind == model.DocumentableKind.VARIABLE
+
+@systemcls_param
+def test_module_level_attributes_and_aliases_orelse(systemcls: Type[model.System]) -> None:
+    """
+    We visit the orelse body and these names have priority over the names in the except handlers.
+    """
+    system = systemcls()
+    builder = system.systemBuilder(system)
+    builder.addModuleString('''
+    ssl = 1
+    ''', modname='twisted.internet')
+    builder.addModuleString('''
+    try:
+        from twisted.internet import ssl as _ssl
+    except ImportError:
+        ssl = None
+        var = 2
+        VAR = 2
+        ALIAS = None
+        newname = 2
+    else:
+        # The names defined in the orelse or finally block wins over the
+        # names defined in the except handler
+        ssl = _ssl
+        var = 1
+    finally:
+        VAR = 1
+        ALIAS = _ssl
+
+    if sys.version_info > (3,7):
+        def func():
+            'func doc'
+        class klass:
+            'klass doc'
+        var2 = 1
+        'var2 doc'
+    else:
+        # these definition will be ignored since they are
+        # alreade definied in the body of the If block.
+        func = None
+        'not this one'
+        def klass():
+            'not this one'
+        class var2:
+            'not this one'
+    ''', modname='mod')
+    builder.buildModules()
+    mod = system.allobjects['mod']
+
+    # Tes newname survives the override guard
+    assert 'newname' in mod.contents
+
+    # Test alias
+    assert mod.expandName('ssl')=="twisted.internet.ssl"
+    assert mod.expandName('_ssl')=="twisted.internet.ssl"
+    s = mod.resolveName('ssl')
+    assert isinstance(s, model.Attribute)
+    assert s.value is not None
+    assert ast.literal_eval(s.value)==1
+    assert s.kind == model.DocumentableKind.VARIABLE
+
+    # Test variable
+    assert mod.expandName('var')=="mod.var"
+    v = mod.resolveName('var')
+    assert isinstance(v, model.Attribute)
+    assert v.value is not None
+    assert ast.literal_eval(v.value)==1
+    assert v.kind == model.DocumentableKind.VARIABLE
+
+    # Test constant
+    assert mod.expandName('VAR')=="mod.VAR"
+    V = mod.resolveName('VAR')
+    assert isinstance(V, model.Attribute)
+    assert V.value is not None
+    assert ast.literal_eval(V.value)==1
+    assert V.kind == model.DocumentableKind.CONSTANT
+
+    # Test looks like constant but actually an alias.
+    assert mod.expandName('ALIAS')=="twisted.internet.ssl"
+    s = mod.resolveName('ALIAS')
+    assert isinstance(s, model.Attribute)
+    assert s.value is not None
+    assert ast.literal_eval(s.value)==1
+    assert s.kind == model.DocumentableKind.VARIABLE
+
+    # Test if override guard
+    func, klass, var2 = mod.resolveName('func'), mod.resolveName('klass'), mod.resolveName('var2')
+    assert isinstance(func, model.Function) 
+    assert func.docstring == 'func doc'
+    assert isinstance(klass, model.Class)
+    assert klass.docstring == 'klass doc'
+    assert isinstance(var2, model.Attribute)
+    assert var2.docstring == 'var2 doc'
+
+@systemcls_param
+def test_class_level_attributes_and_aliases_orelse(systemcls: Type[model.System]) -> None:
+    system = systemcls()
+    builder = system.systemBuilder(system)
+    builder.addModuleString('crazy_var=2', modname='crazy')
+    builder.addModuleString('''
+    if sys.version_info > (3,0):
+        thing = object
+        class klass(thing):
+            'klass doc'
+            var2 = 3
+
+        # regular import
+        from crazy import crazy_var as cv
+    else:
+        # these imports will be ignored because the names
+        # have been defined in the body of the If block.
+        from six import t as thing 
+        import klass
+        from crazy27 import crazy_var as cv
+
+        # Wildcard imports are not processed 
+        # in name override guard context
+        from crazy import * 
+
+        # this import is not ignored
+        from six import seven
+
+        # this class is not ignored and will be part of the public docs.
+        class klassfallback(thing): 
+            'klassfallback doc'
+            var2 = 1
+            # this overrides var2
+            var2 = 2 
+
+        # this is ignored because the name 'klass' 
+        # has been defined in the body of the If block.
+        klass = klassfallback                 
+        'ignored'
+
+        var3 = 1
+        # this overrides var3
+        var3 = 2 
+    ''', modname='mod')
+    builder.buildModules()
+    mod = system.allobjects['mod']
+    assert isinstance(mod, model.Module)
+
+    klass, klassfallback, var2, var3 = \
+        mod.resolveName('klass'), \
+        mod.resolveName('klassfallback'), \
+        mod.resolveName('klassfallback.var2'), \
+        mod.resolveName('var3')
+
+    assert isinstance(klass, model.Class)
+    assert isinstance(klassfallback, model.Class)
+    assert isinstance(var2, model.Attribute)
+    assert isinstance(var3, model.Attribute)
+
+    assert klassfallback.docstring == 'klassfallback doc'
+    assert klass.docstring == 'klass doc'
+    assert ast.literal_eval(var2.value or '') == 2
+    assert ast.literal_eval(var3.value or '') == 2
+
+    assert mod.expandName('cv') == 'crazy.crazy_var'
+    assert mod.expandName('thing') == 'object'
+    assert mod.expandName('seven') == 'six.seven'
+    assert 'klass' not in mod._localNameToFullName_map
+    assert 'crazy_var' not in mod._localNameToFullName_map