WiP: Add support for PEP 484 type hints #7

nicoonoclaste · 2019-01-23T15:12:33Z

Fixes #6.

I started by refactoring Function.params to produce a list of Parameter objects.
This was necessary, as type hints aren't represented the same way in text and HTML (due to linking).

Feel free to comment on the refactor, but type hints themselves are very much a work in progress (the pushed version just adds the necessary field to Parameter, that's all).

Refactor Function.params.
Render type hints for function parameters (in plain text);
Render type hints for function return values.
Render type hints for instance variables & properties.

This is a readability improvement, especially one type hints get added.

nicoonoclaste · 2019-01-23T15:46:35Z

Ah, I used language features only available with 3.6 and later. Is that an issue?

kernc · 2019-01-23T16:32:48Z

At first look, I find this far too abstracted for what is gained or what pdoc is meant to accomplish. While this sure looks correct, I'd honestly much prefer simpler:

def annotated_params(self) -> List[Tuple[str, str, str]]

with, by wrapping:

def foo(_a, b: str, *args, c: int = None, _d=2, **kwargs): pass

returning:

[('_a',       None,  None),
 ('b',        'str', None),
 ('*args',    None,  None),
 ('c',        'int', 'None'),
 ('**kwargs', None,  None)]

Maybe as simple namedtuples. Then you can extend Function.params(include_types=False) and the whole thing remains backwards-compatible, with templates needing just pass a simple config option to params() call. Some type hints can be very complexly nested and meant primarily for linters to verify, so inclusion should certainly be optional up to each project.

Also, Python 3.5, so no variable type annotations, dataclasses, or f-strings, unfortunately.

nicoonoclaste · 2019-01-23T20:46:05Z

@kernc FWIW, there's a dataclasses implementation in PyPy which works with Py<3.7, but I don't think it makes sense if I can't have variable type annotations anyway ;)

nicoonoclaste · 2019-01-23T21:01:43Z

def annotated_params(self) -> List[Tuple[str, str, str]]

The Union was something I forgot to remove while working on the PR, it was meant to just be List[Parameter]. Anyway, making Parameter a NamedTuple, as requested.

aomader · 2019-01-27T15:33:33Z

How is this coming along? I really would like to see this feature. Do you need help or anything @nbraud ?

aomader · 2019-01-27T15:34:42Z

pdoc/__init__.py

@@ -636,11 +638,16 @@ def _var_docstrings(doc_obj: Union['Module', 'Class'], *,
    return vs


-def _is_public(ident_name):
+def _is_public(ident):
    """
    Returns `True` if `ident_name` matches the export criteria for an


Should be ident

nicoonoclaste · 2019-02-01T13:46:52Z

@b52 I had some medical stuff happen and was entirely-useless this week.

For what it's worth, I started rewriting this PR to use inspect.signature instead:

it seems like a much more convenient way to get to the necessary (meta)data;
it addresses @kernc's concerns about abstraction: we just get the right abstractions from the standard library instead of rolling our own;
getfullargspec, which is currently used, was deprecated in favour of it.

kernc · 2019-03-03T12:30:20Z

@nbraud Hate to sound insensitive to your personal issues, but love for you to continue this. 🌞

nicoonoclaste · 2019-03-16T17:11:19Z

@kernc It's fine, I appreciate it's been a while. I finally had the time & energy to look into it again, though it's not yet complete as I broke some tests in the process.

The good news is that Function.params got much less complicated :)

It's impossible for a positional parameter with no default value to follow one which has a default value: >>> def f(x, y=1, z): pass SyntaxError: non-default argument follows default argument

nicoonoclaste · 2019-03-16T17:32:25Z

@kernc OK, I think I got minimum, viable PEP484 support going, but a seemingly-unrelated test fails:

======================================================================
ERROR: test_http (pdoc.test.HttpTest) (url='/csv.ext')
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/nicoo/devel/py/ppb/pdoc/pdoc/test/__init__.py", line 891, in test_http
    with urlopen(url + 'csv.ext', timeout=3) as resp:
  File "/usr/lib/python3.7/urllib/request.py", line 222, in urlopen
    return opener.open(url, data, timeout)
  File "/usr/lib/python3.7/urllib/request.py", line 531, in open
    response = meth(req, response)
  File "/usr/lib/python3.7/urllib/request.py", line 641, in http_response
    'http', request, response, code, msg, hdrs)
  File "/usr/lib/python3.7/urllib/request.py", line 569, in error
    return self._call_chain(*args)
  File "/usr/lib/python3.7/urllib/request.py", line 503, in _call_chain
    result = func(*args)
  File "/usr/lib/python3.7/urllib/request.py", line 649, in http_error_default
    raise HTTPError(req.full_url, code, msg, hdrs, fp)
urllib.error.HTTPError: HTTP Error 404: Not Found

Interestingly, the same test doesn't fail in master, so I definitely did something.

kernc

Thanks!

Besides the breaking test, there are some Python styling issues flake8 warns about.

kernc · 2019-03-17T15:28:04Z

.gitignore

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


Is this line necessary with *.eggs/* already specified three lines above?

kernc · 2019-03-17T16:48:56Z

pdoc/test/__init__.py


        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'])


PEP 8 suggests to use spaces around equals sign only when type is specified:

def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...

kernc · 2019-03-17T22:13:36Z

pdoc/__init__.py

@@ -1366,62 +1414,30 @@ def _is_async(self):
            return False

    @lru_cache()
-    def params(self) -> List[str]:
+    def params(self) -> List[Union[str, Parameter]]:


I'm strongly opposed to breaking established API by returning something else than strings. It makes no sense, really, as any code that were to do something more than str(param) will have to instance check.

Maybe is better:

def params(self, *, types: bool = False) -> List[str]

with types=True returning the strings interpolated with typing info?

pdoc API-wise, I think it's easy enough to let the user do on their own if needed:

inspect.signature(pdoc_func_obj.obj)

In that way, class Parameter(inspect.Parameter) is not even required, in exchange for some of the former complexity of this method (should be much less with inspect API).

types= parameter can then be a template tunable in config.mako:

pdoc/pdoc/templates/config.mako

Lines 1 to 12 in a1f0a15

<%!

# Template configuration. Copy over and adapt as required.

html_lang = 'en'

show_inherited_members = False

extract_module_toc_into_sidebar = True

list_class_variables_in_index = True

sort_identifiers = True

# Set the style keyword such as 'atom-one-light' or 'github-gist'

# Options: https://github.com/highlightjs/highlight.js/tree/master/src/styles

# Demo: https://highlightjs.org/static/demo/

hljs_style = 'github'

%>

kernc · 2019-04-01T01:32:14Z

@nbraud Do you agree with my comments? I'd love to see this brought to completion.

kernc · 2019-04-21T14:12:21Z

Replaced with 5df06cd. Thanks anyway, @nbraud. I'd appreciate feedback whether the result is adequate.

Use spacing for default arguments

a9ff196

This is a readability improvement, especially one type hints get added.

nicoonoclaste added 3 commits January 23, 2019 22:34

Function.params: Refactor to keep names and defaults separate

5b5053d

git: Ignore the .eggs directory

0700277

WiP: Support PEP 484 type hints

9977ffe

aomader reviewed Jan 27, 2019

View reviewed changes

kernc mentioned this pull request Jan 28, 2019

Support PEP 484 type hints #6

Closed

kernc force-pushed the master branch from 9279966 to bb59d80 Compare February 17, 2019 23:50

kernc added this to the 0.6.0 milestone Mar 3, 2019

pdoc: Refactor Parameters and Function.params to use the inspect API

aebd820

nicoonoclaste added 4 commits March 16, 2019 18:12

pdoc.Function.params: Simplify computing positional parameters

c9dbec0

It's impossible for a positional parameter with no default value to follow one which has a default value: >>> def f(x, y=1, z): pass SyntaxError: non-default argument follows default argument

Merge branch 'master' into type-hints

22dd8ad

pdoc.Parameter.__repr__: Handle more complex types

d7d061a

pdoc.test: Update for PEP484 type hints support

1cef049

kernc reviewed Mar 17, 2019

View reviewed changes

kernc closed this in 5df06cd Apr 21, 2019

	<%!
	# Template configuration. Copy over and adapt as required.
	html_lang = 'en'
	show_inherited_members = False
	extract_module_toc_into_sidebar = True
	list_class_variables_in_index = True
	sort_identifiers = True
	# Set the style keyword such as 'atom-one-light' or 'github-gist'
	# Options: https://github.com/highlightjs/highlight.js/tree/master/src/styles
	# Demo: https://highlightjs.org/static/demo/
	hljs_style = 'github'
	%>

Uh oh!

WiP: Add support for PEP 484 type hints #7

WiP: Add support for PEP 484 type hints #7

Uh oh!

Conversation

nicoonoclaste commented Jan 23, 2019 • edited by kernc Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicoonoclaste commented Jan 23, 2019

Uh oh!

kernc commented Jan 23, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nicoonoclaste commented Jan 23, 2019

Uh oh!

nicoonoclaste commented Jan 23, 2019

Uh oh!

aomader commented Jan 27, 2019

Uh oh!

aomader Jan 27, 2019

Choose a reason for hiding this comment

Uh oh!

nicoonoclaste commented Feb 1, 2019

Uh oh!

kernc commented Mar 3, 2019

Uh oh!

nicoonoclaste commented Mar 16, 2019

Uh oh!

nicoonoclaste commented Mar 16, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kernc left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kernc Mar 17, 2019

Choose a reason for hiding this comment

Uh oh!

kernc Mar 17, 2019

Choose a reason for hiding this comment

Uh oh!

kernc Mar 17, 2019

Choose a reason for hiding this comment

Uh oh!

kernc Mar 17, 2019

Choose a reason for hiding this comment

Uh oh!

kernc commented Apr 1, 2019

Uh oh!

kernc commented Apr 21, 2019

Uh oh!

Uh oh!

nicoonoclaste commented Jan 23, 2019 •

edited by kernc

Loading

kernc commented Jan 23, 2019 •

edited

Loading

nicoonoclaste commented Mar 16, 2019 •

edited

Loading

kernc left a comment •

edited

Loading