Merge branch 'visit-try-orelse-finalbody-and-if-orelse' into choose-T…

…YPE_CHECKING-value-for-a-module

docs/source/codedoc.rst

@@ -318,3 +318,45 @@ The content of ``my_project/__init__.py`` includes::
     from .core._impl import MyClass
 
     __all__ = ("MyClass",)
+
+Branch priorities
+-----------------
+
+When pydoctor deals with try/except/else or if/else block, it makes sure that the names defined in 
+the "principal" branch do not get overriden by names defined in the except hanlders or ifs' else block. 
+
+Meaning that in the context of the code below, ``ssl`` would resolve to ``twisted.internet.ssl``:
+
+.. code:: python
+
+    try:
+        from twisted.internet import ssl as _ssl
+    except ImportError:
+        ssl = None
+    else:
+        ssl = _ssl
+
+Similarly, in the context of the code below, the first ``CapSys`` class will be 
+documented and the second one will be ignored.
+
+.. code:: python
+
+    from typing import TYPE_CHECKING
+    if TYPE_CHECKING:
+        from typing import Protocol
+        class CapSys(Protocol):
+            def readouterr() -> Any:
+                ...
+    else:
+        class CapSys(object): # ignored
+            ...
+
+.. But sometimes pydoctor can be better off analysing the ``TYPE_CHECKING`` blocks and should 
+.. stick to the runtime version of the code instead. 
+
+.. You can instrut pydoctor do to such things with a custom system class. 
+
+.. .. code:: python
+
+..     class MySystem(model.System):
+..         eval_if = {'my_mod':{'TYPE_CHECKING':False}}

pydoctor/astbuilder.py

@@ -232,10 +232,10 @@ def __init__(self, builder: 'ASTBuilder', module: model.Module):
     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.  
+        assigments to existing names within the same context.  Currently used to visit C{If.orelse} and C{Try.handlers}.
         
         @note: The list of existing names is generated at the moment of
-            calling the function.
+            calling the function, such that new names defined inside these blocks follows the usual override rules.
         """
         ctx = getframe(self.builder.current)
         ignore_override_init = self._override_guard_state
@@ -255,6 +255,7 @@ def _list_names(self, ob: model.Documentable) -> List[str]:
         return names
 
     def _name_in_override_guard(self, ob: model.Documentable, name:str) -> bool:
+        """Should this name be ignored because it matches the override guard in the context of C{ob}?"""
         return self._override_guard_state[0] is True \
             and self._override_guard_state[1] is ob \
                 and name in self._override_guard_state[2]
@@ -429,7 +430,7 @@ def _importAll(self, modname: str) -> None:
 
         # Always ignore import * in override guard
         if self._override_guard_state[0]:
-            self.builder.warning("ignored import * from", modname)
+            self.builder.warning("ignored import *", modname)
             return
 
         mod = self.system.getProcessedModule(modname)

pydoctor/test/test_astbuilder.py

@@ -2079,10 +2079,7 @@ class j: pass
 @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.
+    Variables and aliases defined in the main body of a Try node will have priority over the names defined in the except handlers.
     """
     system = systemcls()
     builder = system.systemBuilder(system)