help() appears confused about the module of typing.Annotated

[AlexWaygood]

BPO	45380
Nosy	@gvanrossum, @jack1142, @Fidget-Spinner, @AlexWaygood

^{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 2021-10-05.18:29:03.194>
labels = ['type-bug', '3.9', '3.10', '3.11', 'library', 'docs']
title = 'help() appears confused about the module of typing.Annotated'
updated_at = <Date 2022-02-03.23:18:38.705>
user = 'https://github.com/AlexWaygood'

bugs.python.org fields:

activity = <Date 2022-02-03.23:18:38.705>
actor = 'gvanrossum'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Library (Lib)']
creation = <Date 2021-10-05.18:29:03.194>
creator = 'AlexWaygood'
dependencies = []
files = []
hgrepos = []
issue_num = 45380
keywords = []
message_count = 3.0
messages = ['403258', '403602', '412485']
nosy_count = 5.0
nosy_names = ['gvanrossum', 'docs@python', 'jack1142', 'kj', 'AlexWaygood']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue45380'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[AlexWaygood]

help() appears confused about the module of typing.Annotated. If you call help() on a parameterised "instance" of typing.Annotated, it will claim that Annotated belongs to whatever module the annotated type is from. Additionally, help() appears not to know about the __metadata__ attribute of typing.Annotated.

>>> from typing import Annotated, Callable
>>> t = Annotated[int | str, "Some metadata"]
>>> help(t)
Help on _AnnotatedAlias in module types:

Annotated = int | str
>>> u = Annotated[Callable[[int], str], "Some metadata"]
>>> help(u)
Help on _AnnotatedAlias in module typing:

Annotated = typing.Callable[[int], str]
>>> s = Annotated[int, "Some metadata"]
Help on _AnnotatedAlias in module builtins:

Annotated = class int(object)
 |  int([x]) -> integer
 |  int(x, base=10) -> integer

# (etc., giving the entire output of help() for `int`)

[AlexWaygood]

It actually appears as though there is no documented way to retrieve the metadata from an annotated alias. Is this intentional?

The metadata is stored in a __metadata__ attribute of a typing._AnnotatedAlias instance. But the __metadata__ attribute is undocumented -- there is no mention of it in the docstring for _AnnotatedAlias, in the documentation for typing.Annotated (https://docs.python.org/3.11/library/typing.html#typing.Annotated), or PEP-593, which introduced typing.Annotated (https://www.python.org/dev/peps/pep-0593/).

The documentation says: "Passing include_extras=True to get_type_hints() lets one access the extra annotations at runtime." However, this is misleading. Calling get_type_hints on a function/class where an argument/attribute is annotated with an _AnnotatedAlias instance is a way of retrieving the type hints for the function/class with the _AnnotatedAlias instance unresolved. However, if you call get_type_hints on the _AnnotatedAlias instance directly, this fails.