WiP: Add support for PEP 484 type hints

.gitignore

@@ -3,6 +3,7 @@ build
 *.eggs/*
 *.egg-info
 *.py[cod]
+/.eggs/
 
 pdoc/_version.py
 

pdoc/__init__.py

@@ -353,7 +353,9 @@ def recursive_htmls(mod):
 from functools import lru_cache, reduce
 from itertools import tee, groupby
 from types import ModuleType
-from typing import Dict, Iterable, List, Set, Type, TypeVar, Union, Tuple, Generator, Callable
+from typing import Dict, List, Set, Tuple
+from typing import Optional, Union, Type, TypeVar
+from typing import Callable, Iterable, Generator
 from warnings import warn
 
 from mako.lookup import TemplateLookup
@@ -1310,6 +1312,52 @@ def _link_inheritance(self):
         del self._super_members
 
 
+class Parameter(inspect.Parameter):
+    """Representation of a function parameter, incl. type hint & default value."""
+
+    POSITIONAL = (
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        inspect.Parameter.VAR_POSITIONAL,
+    )
+
+    KEYWORD = (
+        inspect.Parameter.KEYWORD_ONLY,
+        inspect.Parameter.VAR_KEYWORD
+    )
+
+    STARS = {
+        inspect.Parameter.VAR_POSITIONAL: '*',
+        inspect.Parameter.VAR_KEYWORD:    '**',
+    }
+
+    @property
+    def should_show(self) -> bool:
+        return _is_public(self.name) or self.default is Parameter.empty
+
+    def __str__(self) -> str:
+        r = Parameter.STARS.get(self.kind, '')
+        r += self.name
+
+        if self.annotation is not Parameter.empty:
+            r += ': '
+
+            if isinstance(self.annotation, str):
+                r += self.annotation
+            elif hasattr(self.annotation, '__name__'):
+                r += self.annotation.__name__
+            else:
+                r += repr(self.annotation)
+
+        if self.default is not Parameter.empty:
+            r += ' = ' + repr(self.default)
+
+        return r
+
+    def of_inspect(p: inspect.Parameter) -> 'Parameter':
+        return Parameter(p.name, p.kind, default=p.default, annotation=p.annotation)
+
+
 class Function(Doc):
     """
     Representation of documentation for a function or method.
@@ -1366,62 +1414,30 @@ def _is_async(self):
             return False
 
     @lru_cache()
-    def params(self) -> List[str]:
+    def params(self) -> List[Union[str, Parameter]]:
         """
-        Returns a list where each element is a nicely formatted
-        parameter of this function. This includes argument lists,
-        keyword arguments and default values, and it doesn't include any
+        Returns a list representing each parameter of this function, with a
+        nicely-formatted string conversion. This includes argument lists,
+        keyword arguments, and default values, and it doesn't include any
         optional arguments whose names begin with an underscore.
         """
         try:
-            s = inspect.getfullargspec(inspect.unwrap(self.obj))
+            sig = inspect.signature(inspect.unwrap(self.obj))
         except TypeError:
             # I guess this is for C builtin functions?
-            return ["..."]
+            return [Parameter('...', None, None)]
 
-        params = []
-        for i, param in enumerate(s.args):
-            if s.defaults is not None and len(s.args) - i <= len(s.defaults):
-                defind = len(s.defaults) - (len(s.args) - i)
-                params.append("%s=%s" % (param, repr(s.defaults[defind])))
-            else:
-                params.append(param)
-        if s.varargs is not None:
-            params.append("*%s" % s.varargs)
-
-        kwonlyargs = getattr(s, "kwonlyargs", None)
-        if kwonlyargs:
-            if s.varargs is None:
-                params.append("*")
-            for param in kwonlyargs:
-                try:
-                    params.append("%s=%s" % (param, repr(s.kwonlydefaults[param])))
-                except KeyError:
-                    params.append(param)
-
-        keywords = getattr(s, "varkw", getattr(s, "keywords", None))
-        if keywords is not None:
-            params.append("**%s" % keywords)
-
-        # Remove "_private" params following catch-all *args and from the end
-        iter_params = iter(params)
-        params = []
-        for p in iter_params:
-            params.append(p)
-            if p.startswith('*'):
-                break
-        while len(params) > 1 and not _is_public(params[-2]) and '=' in params[-2]:
-            params.pop(-2)
-        for p in iter_params:
-            if _is_public(p.lstrip('*')):
-                params.append(p)
-        while params and not _is_public(params[-1]) and '=' in params[-1]:
-            params.pop(-1)
-        if params and params[-1] == '*':
-            params.pop(-1)
-
-        # TODO: The only thing now missing for Python 3 are type annotations
-        return params
+
+        parameters = [ Parameter.of_inspect(p) for p in sig.parameters.values() ]
+        pos_params = [ p for p in parameters
+                       if p.should_show and p.kind in Parameter.POSITIONAL ]
+        kw_params = [ p for p in parameters
+                      if p.should_show and p.kind in Parameter.KEYWORD ]
+
+        if not pos_params and kw_params:
+            return ['*'] + kw_params
+
+        return pos_params + kw_params
 
     def __lt__(self, other):
         # Push __init__ to the top.

pdoc/templates/html.mako

@@ -103,7 +103,7 @@
 
   <%def name="show_func(f)">
     <dt id="${f.refname}"><code class="name flex">
-        <span>${f.funcdef()} ${ident(f.name)}</span>(<span>${', '.join(f.params()) | h})</span>
+        <span>${f.funcdef()} ${ident(f.name)}</span>(<span>${', '.join(map(str, f.params())) | h})</span>
     </code></dt>
     <dd>${show_desc(f)}</dd>
   </%def>

pdoc/templates/text.mako

@@ -12,7 +12,7 @@
 </%def>
 
 <%def name="function(func)" buffered="True">
-`${func.name}(${", ".join(func.params())})`
+`${func.name}(${", ".join(map(str, func.params()))})`
 ${func.docstring | deflist}
 </%def>
 

pdoc/test/__init__.py

@@ -132,7 +132,7 @@ def test_html(self):
             '>sys.version<',
             'B.CONST docstring',
             'B.var docstring',
-            'b=1',
+            'b: int = 1',
             '*args',
             '**kwargs',
             '__init__ docstring',
@@ -264,7 +264,7 @@ def test_text(self):
             '__init__ docstring',
             'instance_var',
             'instance var docstring',
-            'b=1',
+            'b: int = 1',
             '*args',
             '**kwargs',
             'B.f docstring',
@@ -511,15 +511,15 @@ def test_context(self):
     def test_Function_private_params(self):
         func = pdoc.Function('f', pdoc.Module(pdoc),
                              lambda a, _a, _b=None: None)
-        self.assertEqual(func.params(), ['a', '_a'])
+        self.assertEqual([str(p) for p in func.params()], ['a', '_a'])
 
         func = pdoc.Function('f', pdoc.Module(pdoc),
                              lambda _ok, a, _a, *args, _b=None, c=None, _d=None: None)
-        self.assertEqual(func.params(), ['_ok', 'a', '_a', '*args', 'c=None'])
+        self.assertEqual([str(p) for p in func.params()], ['_ok', 'a', '_a', '*args', 'c = None'])
 
         func = pdoc.Function('f', pdoc.Module(pdoc),
                              lambda a, b, *, _c=1: None)
-        self.assertEqual(func.params(), ['a', 'b'])
+        self.assertEqual([str(p) for p in func.params()], ['a', 'b'])
 
     def test_url(self):
         mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))