[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

Honestly I think pydoc is already too verbose. It would be better if the class 
header looked more like what was written in the source code -- that is the most 
compact way to render it. I say open a separate issue since this issue is about 
functions.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Changes by Guido van Rossum :


--
resolution:  -> fixed
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Roundup Robot]

Roundup Robot added the comment:

New changeset dc030d15f80d by Guido van Rossum in branch '3.5':
Issue #27989: Tweak inspect.formatannotation() to improve pydoc rendering of 
function annotations. Ivan L.
https://hg.python.org/cpython/rev/dc030d15f80d

New changeset 3937502c149d by Guido van Rossum in branch '3.6':
Issue #27989: Tweak inspect.formatannotation() to improve pydoc rendering of 
function annotations. Ivan L. (3.5->3.6)
https://hg.python.org/cpython/rev/3937502c149d

New changeset 62127e60e7b0 by Guido van Rossum in branch 'default':
Issue #27989: Tweak inspect.formatannotation() to improve pydoc rendering of 
function annotations. Ivan L. (3.6->3.7)
https://hg.python.org/cpython/rev/62127e60e7b0

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Ivan Levkivskyi]

Ivan Levkivskyi added the comment:

Actually, for classes, it is probably worth adding a separate section "Generic 
type info" that will render information using __orig_bases__, __parameters__, 
and __args__. At the same time the "header" will be the same as now, listing 
runtime __bases__.

What do you think about this? Should I open a separate issue?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

OK, sounds good then. I guess most of the work was in typing.py, not in 
inspect. :-)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Ivan Levkivskyi]

Ivan Levkivskyi added the comment:

For function annotations I did as originally proposed. In my previous comment I 
was talking about documentation for classes. For example:

class C(Generic[T], Mapping[int, str]): ...
pydoc.render_doc(C)

will show "class C(typing.Mapping)".

while for function annotations typing is indeed much more common so that 
pydoc.render_doc(foo) will show

foo(data: List[Any]) -> Iterator[Tuple[int, Any]]

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

Hm, I actually like the original proposal better. Perhaps 
collections.abc.Mapping is more common than typing.Mapping, but is it more 
common *in function annotations*? I don't think so.

Also, I like showing e.g. Iterator[Tuple[int, Any]] rather than just Iterator. 
This is documentation we're talking about, and the parameter types are very 
useful as documentation. (However, abbreviating List[Any] as List is fine, 
since they mean the same thing.)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Ivan Levkivskyi]

Ivan Levkivskyi added the comment:

Here is the patch according to the discussion (modifying inspect).

I didn't change the rendering of docs for classes (neither stripped 'typing.' 
nor changed __bases__ to __orig_bases__). First, collections.abc.X are widely 
used as base classes, so that plain Mapping could be confused with 
collections.abc.Mapping. Second, seeing the actual runtime type-erased bases 
suggests that one should use isinstance() and issubclass() with those (not 
with, e.g.,  Mapping[int, str], the latter will raise TypeError).

--
keywords: +patch
nosy: +yselivanov
Added file: http://bugs.python.org/file45188/typing-pydoc.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[David E. Franco G.]

David E. Franco G. added the comment:

I think that removing the "typing." is for the best, with the example above 

>>> help(foo)
Help on function foo in module __main__:

foo(data:typing.List[typing.Any]) -> typing.Iterator[typing.Tuple[int, 
typing.Any]]

>>> 


leaving the "typing." produce result that I think are ugly and distracting, not 
only that, is unnecessary long to convey the same information that can be in a 
more neat way without it, and more so while more complicated/long the signature 
is. 

just compare the above with this

>>> help(foo)
Help on function foo in module __main__:

foo(data:List[Any]) -> Iterator[Tuple[int, Any]]:

>>> 

which is a clear winner to me.

Or perhaps alongside modifying inspect.formatannotation also change the 
__repr__ in typing to exclude the `typing.` or like with for instance TypeVar 
produce a repr that include some marker instead, like ~ and in that way 
indicate that one is using typing object resulting in something like this

>>> help(foo)
Help on function foo in module __main__:

foo(data:~List[Any]) -> ~Iterator[~Tuple[int, ~Any]]:

>>> 

which is a little weird but still neat

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Ivan Levkivskyi]

Changes by Ivan Levkivskyi :


--
nosy: +levkivskyi

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

I've lost you -- why don't you upload a patch?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Spencer Brown]

Spencer Brown added the comment:

It might be better to just change the if statement to 'if 
isinstance(annotation, type) and type(annotation).__repr__ is type.__repr__:'. 
That would make it fallback for any metaclass which overrides repr, instead of 
special-casing typing. That also ensures 'typing.' is still in the name, since 
these aren't builtins.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

That sounds a fine solution (except the elif should just test for `in
'typing'`). Can one of you prepare a patch? I think it should be fine
to fix this in 3.5 as well.

There should be a unit test for this.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[David E. Franco G.]

David E. Franco G. added the comment:

as that is the case, how about this as a solution:

def formatannotation(annotation, base_module=None):
if isinstance(annotation, type):
if annotation.__module__ in ('builtins', base_module):
return annotation.__qualname__
elif annotation.__module__ in ('typing', base_module):   
return repr(annotation).replace("typing.","")
return annotation.__module__+'.'+annotation.__qualname__
return repr(annotation)

the same way that it check for builtins, do it for typing and clean up a 
little. 

With that change the result with the example is

>>> help(foo)
Help on function foo in module __main__:

foo(data:List[Any]) -> Iterator[Tuple[int, Any]]

>>>

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Spencer Brown]

Spencer Brown added the comment:

More precisely, the issue is with inspect.formatannotation(), which 
overrides/ignores the repr if the annotation is an instance of type. Perhaps 
that should be changed to also check that __repr__ is type's repr.

--
nosy: +Spencer Brown

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[Guido van Rossum]

Guido van Rossum added the comment:

It seems the output produced here is generated by inspect.signature(), which is 
called by pydoc in this case (in both versions of docroutine()).

I don't know if the right thing to do is to change inspect.signature() here, or 
to change pydoc to use something else to format the argument list.

--
nosy: +gvanrossum

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue27989] incomplete signature with help function using typing

[David E. Franco G.]

New submission from David E. Franco G.:

the issue is that when calling help on a function annotated with typing, all 
the relevant information is lost, for example

from typing import List, Any, Iterator, Tuple

def foo(data:List[Any]) -> Iterator[ Tuple[int,Any] ]:
...
 
when calling help on that

>>> help(foo)
Help on function foo in module __main__:

foo(data:typing.List) -> typing.Iterator

>>> 

all the information is lost, the output should look like this

>>> help(foo)
Help on function foo in module __main__:

foo(data:List[Any]) -> Iterator[ Tuple[int, Any] ]:

>>> 

where all the information that I put in the annotation is preserved and the 
typing.* are eliminated since they only add unnecessary noise

while reporting this issue in the typing module 
(https://github.com/python/typing/issues/279) I was told that is a bug with the 
inspect module and that help may need modification.

Thank for your time.

--
components: Library (Lib)
messages: 274702
nosy: David E. Franco G.
priority: normal
severity: normal
status: open
title: incomplete signature with help function using typing
type: behavior
versions: Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com