ENH: Better format typing.NewType annotations (#254)

* ENH: Show new type names for function signatures

Fixes: #253

* Fixup pdoc/__init__.py

Author: TristanCacqueray

pdoc/__init__.py

@@ -1167,6 +1167,20 @@ def _link_inheritance(self):
         del self._super_members
 
 
+def _formatannotation(annot):
+    """
+    Format annotation, properly handling NewType types
+
+    >>> _formatannotation(NewType('MyType', str))
+    'MyType'
+    """
+    is_new_type = (getattr(annot, '__qualname__', '').startswith('NewType.') and
+                   getattr(annot, '__module__', '') == 'typing')
+    if is_new_type:
+        return annot.__name__
+    return inspect.formatannotation(annot)
+
+
 class Function(Doc):
     """
     Representation of documentation for a function or method.
@@ -1265,7 +1279,7 @@ def return_annotation(self, *, link=None) -> str:
         if isinstance(annot, str):
             s = annot
         else:
-            s = inspect.formatannotation(annot)
+            s = _formatannotation(annot)
             s = re.sub(r'\b(typing\.)?ForwardRef\((?P<quot>[\"\'])(?P<str>.*?)(?P=quot)\)',
                        r'\g<str>', s)
         s = s.replace(' ', '\N{NBSP}')  # Better line breaks in html signatures
@@ -1371,7 +1385,7 @@ def __repr__(self):
 
             formatted = p.name
             if p.annotation is not EMPTY:
-                annotation = inspect.formatannotation(p.annotation).replace(' ', '\N{NBSP}')
+                annotation = _formatannotation(p.annotation).replace(' ', '\N{NBSP}')
                 # "Eval" forward-declarations (typing string literals)
                 if isinstance(p.annotation, str):
                     annotation = annotation.strip("'")

pdoc/test/__init__.py

@@ -841,6 +841,16 @@ def bug130_str_annotation(a: "str"):
         self.assertEqual(pdoc.Function('bug130', mod, bug130_str_annotation).params(annotate=True),
                          ['a:\N{NBSP}str'])
 
+        # typed, NewType
+        CustomType = typing.NewType('CustomType', bool)
+
+        def bug253_newtype_annotation(a: CustomType):
+            return
+
+        self.assertEqual(
+            pdoc.Function('bug253', mod, bug253_newtype_annotation).params(annotate=True),
+            ['a:\N{NBSP}CustomType'])
+
         # builtin callables with signatures in docstrings
         from itertools import repeat
         self.assertEqual(pdoc.Function('repeat', mod, repeat).params(), ['object', 'times'])