The description of `typing.Annotated` has contradictory statements

[gabrieldemarmiesse]

Documentation

Here is the problematic part: https://docs.python.org/3/library/typing.html#typing.Annotated

We have two contradictory statements. Both cannot be true at the same time (or maybe I just don't understand the docs and then we may want some rephrasing this part).

Metadata added using Annotated can be used by static analysis tools or at runtime.

and

Using Annotated[T, x] as an annotation still allows for static typechecking of T, as type checkers will simply ignore the metadata x.

Since static type checkers are static analysis tools, the first sentence is saying that they can use Annotated metadata but the second sentence says that they will ignore it. This causes quite some misunderstanding among users, for example here: https://discuss.python.org/t/pep-7xx-dataclasses-annotated-support-for-field-as-metainformation/30153/11

[ericvsmith]

But not all static analysis tools are type checkers. At least that’s my reading of it: there exist static tools that use the metadata, but type checkers do ignore it.

[gabrieldemarmiesse]

Thanks for the clarification! Then one or two sentences about it in the docs could help clarify it. Something along the lines of "Static type checkers are forbidden to read the metadata of typing.Annotated".

This would help because the PEP 593 doesn't says anywhere that static type checkers are forbidden to use the metadata of typing.Annotated. My reading of the PEP is that it's up to the person implementing the type checker to read the metadata or not.

It only states:

Ultimately, the responsibility of how to interpret the annotations (if at all) is the responsibility of the tool or library encountering the Annotated type

[TeamSpen210]

It seems a little pointless to prohibit type checkers from analysing metadata. It might be better to say that currently there isn't any standard typing-related meanings defined for metadata, so type checkers don't need to check it. In the future it seems quite reasonable that we might want to assign meaning for some annotation.

[PIG208]

Maybe instead of

Using Annotated[T, x] as an annotation still allows for static typechecking of T, as type checkers will simply ignore the metadata x.

We should mention that (in the current state);

Using Annotated[T, x] as an annotation still allows for static typechecking of T. Currently, the metadata x has no standard typing-related meaning to type checkers and they will simply ignore it.

Then, if at any time in the future, the metadata starts to affect type checking, we just update this accordingly.

[gabrieldemarmiesse]

I'm not sure that we should provide information about what the community is currently doing in the documentation. As you said, we will need to change the documentation later if we do this. Furthermore, we don't know everything the community is doing. The python ecosystem is large and some of it is private. We should rather focus on explaining what the PEP is saying in the simplest way possible.