Description

SimpleArt

opened on Feb 3, 2023

Issue body actions

Feature or enhancement

When using help(...), annotations should be unstringified and displayed without typing.ForwardRef.

Pitch

Current behavior displays string annotations with quotes as follows:

def foo(x: List["A"], y: "B") -> None:
    ...

help(foo)
"""
Help on function foo in module ...:

foo(x: List[ForwardRef('A')], y: 'B') -> None

"""

It should be fairly obvious how clunky this is to users, and that the desirable behavior should be something like:

help(foo)
"""
Help on function foo in module ...:

foo(x: List[A], y: B) -> None

"""

#84171 is related, but whereas the suggestion there is to actually evaluate the annotations using typing.get_type_hints or similar, this proposal aims to only remove quotations and typing.ForwardRef(...) from the outputted documentation.

This means that the resulting documentation may not be 100% accurate but will not require evaluating the annotation, which can avoid issues such as annotations which cannot be evaluated for some reason.

For example:

import typing

if typing.TYPE_CHECKING:
    import numpy as np

def foo(x: "np.ndarray") -> None:
    ...

help(foo)
"""
Help on function foo in module ...:

foo(x: np.ndarray) -> None

"""

Note that the np.ndarray is not expanded out into its fully qualified name numpy.ndarray.

There are also some additional edge cases to consider, such as "ForwardRef('A')". Ideally this should be changed to A, but I don't think there's much impact if it is purposefully left as that, and leaving it as-is avoids other problems e.g. ForwardRef is not actually typing.ForwardRef in that example.

Linked PRs

• gh-101552: Allow pydoc to display signatures in source format #124669

Reacted by Benjamin Kirkbride

Activity

1. SimpleArt

   added

   type-featureA feature request or enhancementA feature request or enhancement

   on Feb 3, 2023
2. AlexWaygood

   added

   topic-typing

   on Feb 3, 2023
3. JelleZijlstra commented on Sep 26, 2024

   

   JelleZijlstra

   on Sep 26, 2024

   Member

   More actions

   In Python 3.14, we can address this by using the STRING format for annotationlib.get_annotations. However, pydoc uses inspect.signature, and there's no way to pass the annotation format to inspect.signature.

   So I'd like to add a format=Format.VALUE parameter to inspect.signature to support this use case. cc @larryhastings

   Reacted by Alex Waygood and sobolevn
4. JelleZijlstra

   added a commit that references this issue on Sep 27, 2024

   pythongh-101552: Add format argument to inspect.signature

   f806791
5. carljm commented on Sep 27, 2024

   

   carljm

   on Sep 27, 2024

   Member

   More actions

   So I'd like to add a format=Format.VALUE parameter to inspect.signature to support this use case

   Perhaps the parameter should be named more explicitly (annotation_format), given that it's not a "format" for the entire signature, but rather for the annotations specifically.

   Reacted by Alex Waygood
6. JelleZijlstra commented on Sep 27, 2024

   

   JelleZijlstra

   on Sep 27, 2024

   Member

   More actions

   Yes, especially since there is also a Signature.format method that formats the entire signature.

   Reacted by Carl Meyer
7. JelleZijlstra

   added a commit that references this issue on Oct 9, 2024

   gh-101552: Allow pydoc to display signatures in source format (#124669)

   7840638
8. efimov-mikhail

   added a commit that references this issue on Oct 9, 2024

   pythongh-101552: Allow pydoc to display signatures in source format (p…

   8192c63
9. hugovk commented on Jan 29, 2025

   

   hugovk

   on Jan 29, 2025

   Member

   More actions

   It should be fairly obvious how clunky this is to users, and that the desirable behavior should be something like:

   help(foo)
   """
   Help on function foo in module ...:
   
   foo(x: List[A], y: B) -> None
   
   """

   The output in 3.14 is now:

   Help on function foo in module ...:
   
   foo(x: List['A'], y: B) -> None

   Thanks all, let's close.
10. hugovk

    closed this as completedon Jan 29, 2025

Issue actions