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.

[gvanrossum]

It looks like __metadata__ was *meant* to be a public attribute, but somehow overseen when the PEP and docs were written. :-(

I don't know anything about this class, really.

[martindemello]

looks like #96080 fixed this

[Jackenmen]

__metadata__ attribute appears to still not be documented so if it's not tracked elsewhere, it would make sense to make an issue for tracking the documentation about runtime inspection of Annotated.

[martindemello]

also for x = Annotated[int | str, "some metadata"], help(x) returns

Help on _AnnotatedAlias in module typing:

Annotated = int | str

which is less than ideal.

[AlexWaygood]

__metadata__ attribute appears to still not be documented so if it's not tracked elsewhere, it would make sense to make an issue for tracking the documentation about runtime inspection of Annotated.

(To update on this: the __metadata__ field is now documented; see the PRs attached to #97797.)