help should evaluate forward reference

[McSinyx]

BPO	39990
Nosy	@McSinyx, @FFY00
PRs	bpo-39990: try resolving type hints in pydoc #19874

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-03-17.09:21:34.766>
labels = ['type-feature', 'docs']
title = 'help should evaluate forward reference'
updated_at = <Date 2020-05-03.00:45:50.648>
user = 'https://github.com/McSinyx'

bugs.python.org fields:

activity = <Date 2020-05-03.00:45:50.648>
actor = 'FFY00'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-03-17.09:21:34.766>
creator = 'McSinyx'
dependencies = []
files = []
hgrepos = []
issue_num = 39990
keywords = ['patch']
message_count = 3.0
messages = ['364399', '364431', '367949']
nosy_count = 3.0
nosy_names = ['docs@python', 'McSinyx', 'FFY00']
pr_nums = ['19874']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue39990'
versions = []

[McSinyx]

With PEP-563, it is legal to annotate a function as follows

def foo(bar: 'int') -> 'bool': pass

Currently, help(foo) would print the exact signature in foo.__annotations__ and it's not really pretty. My proposal is to use the type hints from typing.get_type_hints to make documentations more readable from the user's perspective. I might not be aware of all use cases and disadvantages of this proposal however.

[McSinyx]

I traced it down to inspect.formatannotation(annotation). Before checking for isinstance(annotation, type), IMHO we should do something like

import typing

if isinstance(annotation, str):
    annotation = typing.ForwardRef(str)._evaluate(annotation)

However, is is not aware of globals and especially locals of help caller, so I guess more sophisticated solution is required.

[FFY00]

typing.get_type_hints can be used for this, it resolves the annotation string.

>>> def foo(bar: 'int') -> 'bool': pass
...
>>> typing.get_type_hints(foo)
{'bar': <class 'int'>, 'return': <class 'bool'>}

[JelleZijlstra]

This is fixed in 3.14 thanks to some of the PEP-649 changes. Using the OP's example:

Help on function foo in module __main__:

foo(bar: int) -> bool