python / python/cpython

Improve the `help()` of type alias objects

Open
#156,925 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

interpreter-core topic-typing type-feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.