Document `Annotated.__origin__`

[ncoghlan]

The typing module docs cover using Annotated.__metadata__ to retrieve the annotations, but they do not currently cover the use of Annotated.__origin__ to retrieve the underlying type hint that is being annotated.

>>> from typing import Annotated
>>> Annotated[int, ""].__metadata__
('',)
>>> Annotated[int, ""].__origin__
<class 'int'>

Linked PRs

• gh-124120: Document Annotated.__origin__ #124125
• [3.13] gh-124120: Document Annotated.__origin__ (GH-124125) #124416
• [3.12] gh-124120: Document Annotated.__origin__ (GH-124125) #124417

[JelleZijlstra]

You should not use this directly, but use typing.get_origin instead. However, we could document this explicitly.

[JelleZijlstra]

Actually, looking at the code some more this is not true. For some reason there is a special case where .__origin__ and get_origin() (as well as __args__ and get_args()) are not aligned for Annotated.

>>> a = Annotated[int, "x"]
>>> a.__origin__
<class 'int'>
>>> a.__args__
(<class 'int'>,)
>>> typing.get_origin(a)
<class 'typing.Annotated'>
>>> typing.get_args(a)
(<class 'int'>, 'x')

This aligns with the documentation, which promises that for X[Y, ...], get_origin() will return X. However, it is confusing that it does not also align with the __origin_ attribute.

Since __origin__ is otherwise undocumented, it's probably best to document it specifically for Annotated as @ncoghlan originally suggested.

[sobolevn]

I made this mistake in the first version of #124125

But, then I realized the same thing as in #124120 (comment)

Why? Because of these two lines:

cpython/Lib/typing.py

Lines 2507 to 2508 in 9aa1f60

	if isinstance(tp, _AnnotatedAlias):
	return Annotated

I think that it makes sense:

Get the unsubscripted version of a type.

So, Annotated is the unsubscripted version of a type. And any T wrapped by it is just the first type arg.

[ncoghlan]

Backports have been merged, so marking this as complete. Thanks, folks!