Improve the `help()` of type alias objects
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 35.9k
- PR merge metrics
- PR metrics pending
Description
Feature or enhancement
EDIT: See https://discuss.python.org/t/runtime-docstrings-for-type-aliases/108901
Proposal:
Consider recording __doc__ on type alias objects.
For instance:
type Pair[T] = tuple[T, T]
"""A pair of values of the same type."""
Now Pair.__doc__ is "A pair of values of the same type.".
Use it in the REPL:
>>> from mymodule import Pair
>>> help(Pair)
Help on type alias Pair in module mymodule:
Pair[T] = tuple[T, T]
| A pair of values of the same type.
|
| Attributes:
|
| __value__
| Lazily evaluated value of the type alias.
|
| evaluate_value
| Evaluation function for __value__.
|
| __type_params__
| Type parameters declared by the type alias.
|
| __parameters__
| Type parameters after expansion.
|
| __name__
| Name of the type alias.
|
| __qualname__
| Qualified name of the type alias.
|
| __module__
| Module in which the type alias was defined.
(I wrote this text by hand, the actual thing could probably be improved.)
I assume IDEs/LSPs already catch it, so this is mainly a runtime feature.
Current help() just shows a slightly confusing help on the type alias type itself:
>>> type x = int
>>> help(x)
Help on TypeAliasType in module __main__ object:
x = class TypeAliasType(builtins.object)
| Type alias.
|
| Type aliases are created through the type statement::
|
...
It is confusing because (1) it reads like TypeAliasType was defined in __main__ (Help on TypeAliasType in module __main__ object), and (2) almost like if i did x = typing.TypeAliasType. (Which could be improved on its own? We could instead say x = instance of class ..., not just x = class ...)
Has this already been discussed elsewhere?
This is a minor feature, which does not need previous discussion elsewhere
Links to previous discussion of this feature:
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the current help(x) output for a type alias in the REPL, then trace help() handling for type alias objects and the runtime type-alias implementation. Done means runtime docstrings can be recorded and help(Pair) presents the alias, its documentation, and relevant attributes without misleadingly describing the alias as the TypeAliasType class.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100