ENH: Add type annotations for Variables

Now including global variables.

PEP 526 recommends instance variables should be type annotated
on the class. With source parsing involved, that's the only case
we opt to support.

Fixes: #121

Refs:
* 62c66cb
* b8758dd
* #175

Author: kernc

pdoc/__init__.py

@@ -264,9 +264,9 @@ def _pep224_docstrings(doc_obj: Union['Module', 'Class'], *,
             target = assign_node.targets[0]
         elif isinstance(assign_node, ast_AnnAssign):
             target = assign_node.target
-            # TODO: use annotation
-            # Note, need only for instance variables. Class variables are already
-            # handled by `typing.get_type_hints()` elsewhere.
+            # Skip the annotation. PEP 526 says:
+            # > Putting the instance variable annotations together in the class
+            # > makes it easier to find them, and helps a first-time reader of the code.
         else:
             continue
 
@@ -1154,6 +1154,13 @@ def return_annotation(self, *, link=None) -> str:
                 pass
             else:
                 raise
+            try:
+                # global variables
+                annot = _get_type_hints(not self.cls and self.module.obj)[self.name]
+            except Exception:
+                pass
+            else:
+                raise
             try:
                 annot = inspect.signature(self.obj).return_annotation
             except Exception:
@@ -1170,9 +1177,8 @@ def return_annotation(self, *, link=None) -> str:
         except RuntimeError:  # Success.
             pass
         else:
-            # Don't warn on instance variables. Their annotations remain TODO
-            # to be found when parsing _pep224_docstrings()
-            if not getattr(self, 'instance_var', False):
+            # Don't warn on variables. The annotation just isn't available.
+            if not isinstance(self, Variable):
                 warn("Error handling return annotation for {!r}".format(self), stacklevel=3)
 
         if annot is inspect.Parameter.empty or not annot:

pdoc/templates/html.mako

@@ -16,6 +16,13 @@
 
   def to_html(text):
     return _to_html(text, module=module, link=link, latex_math=latex_math)
+
+
+  def get_annotation(bound_method, sep=':'):
+    annot = show_type_annotations and bound_method(link=link) or ''
+    if annot:
+        annot = ' ' + sep + '\N{NBSP}' + annot
+    return annot
 %>
 
 <%def name="ident(name)"><span class="ident">${name}</span></%def>
@@ -100,11 +107,9 @@
     <dt id="${f.refname}"><code class="name flex">
         <%
             params = ', '.join(f.params(annotate=show_type_annotations, link=link))
-            returns = show_type_annotations and f.return_annotation(link=link) or ''
-            if returns:
-                returns = ' ->\N{NBSP}' + returns
+            return_type = get_annotation(f.return_annotation, '->')
         %>
-        <span>${f.funcdef()} ${ident(f.name)}</span>(<span>${params})${returns}</span>
+        <span>${f.funcdef()} ${ident(f.name)}</span>(<span>${params})${return_type}</span>
     </code></dt>
     <dd>${show_desc(f)}</dd>
   </%def>
@@ -147,7 +152,8 @@
     <h2 class="section-title" id="header-variables">Global variables</h2>
     <dl>
     % for v in variables:
-      <dt id="${v.refname}"><code class="name">var ${ident(v.name)}</code></dt>
+      <% return_type = get_annotation(v.type_annotation) %>
+      <dt id="${v.refname}"><code class="name">var ${ident(v.name)}${return_type}</code></dt>
       <dd>${show_desc(v)}</dd>
     % endfor
     </dl>
@@ -209,7 +215,8 @@
           <h3>Class variables</h3>
           <dl>
           % for v in class_vars:
-              <dt id="${v.refname}"><code class="name">var ${ident(v.name)}</code></dt>
+              <% return_type = get_annotation(v.type_annotation) %>
+              <dt id="${v.refname}"><code class="name">var ${ident(v.name)}${return_type}</code></dt>
               <dd>${show_desc(v)}</dd>
           % endfor
           </dl>
@@ -226,12 +233,8 @@
           <h3>Instance variables</h3>
           <dl>
           % for v in inst_vars:
-              <%
-                  var_type = show_type_annotations and v.type_annotation(link=link) or ''
-                  if var_type:
-                      var_type = ' ->\N{NBSP}' + var_type
-              %>
-              <dt id="${v.refname}"><code class="name">var ${ident(v.name)}${var_type}</code></dt>
+              <% return_type = get_annotation(v.type_annotation) %>
+              <dt id="${v.refname}"><code class="name">var ${ident(v.name)}${return_type}</code></dt>
               <dd>${show_desc(v)}</dd>
           % endfor
           </dl>

pdoc/test/__init__.py

@@ -818,14 +818,27 @@ def prop(self) -> typing.Optional[int]:
 
     @ignore_warnings
     @unittest.skipIf(sys.version_info < (3, 6), 'variable annotation unsupported in <Py3.6')
-    def test_Variable_type_annotation_py35plus(self):
-        exec('''class Foo:
-                    var: int = 3
-                    """var"""
-        ''')
-        mod = pdoc.Module(pdoc)
-        cls = pdoc.Class('Foobar', mod, locals()['Foo'])
-        self.assertEqual(cls.doc['var'].type_annotation(), 'int')
+    def test_Variable_type_annotation_py36plus(self):
+        with temp_dir() as path:
+            filename = os.path.join(path, 'module36syntax.py')
+            with open(filename, 'w') as f:
+                f.write('''
+var: str = 'x'
+"""dummy"""
+
+class Foo:
+    var: int = 3
+    """dummy"""
+
+    def __init__(self):
+        self.var2: float = 1
+        """dummy"""
+                ''')
+            mod = pdoc.Module(pdoc.import_module(filename))
+            self.assertEqual(mod.doc['var'].type_annotation(), 'str')
+            self.assertEqual(mod.doc['Foo'].doc['var'].type_annotation(), 'int')
+            self.assertIsInstance(mod.doc['Foo'].doc['var2'], pdoc.Variable)
+            self.assertEqual(mod.doc['Foo'].doc['var2'].type_annotation(), '')  # Won't fix
 
     @ignore_warnings
     def test_Class_docstring(self):