Annotated: propose better terminology

[JelleZijlstra]

Arising out of: https://discuss.python.org/t/pep-746-typedmetadata-for-type-checking-of-pep-593-annotated/53834/50

Dedicated discussion thread: https://discuss.python.org/t/proposed-spec-changes-for-annotated/55807

[erictraut]

Thanks for doing this. I think the term "metadata" is useful here, and it improves the readability of the spec.

[erictraut]

As I mentioned in discourse, I have misgivings about the term "base type" here. I'd prefer if we simply used the term "type". The problem with "base type" is that it implies that the type is modified by the metadata. First, this isn't the case for static type checkers. Second, metadata doesn't need to (and often doesn't in practice) refer to the type; it can apply to the symbol that the annotation is applied to — or something else completely.

[JelleZijlstra]

I think it's important for clarity to have some term that specifically refers to what I call the base type. Would using "inner type" address your concern?

[erictraut]

I don't think "inner type" is much better than "base type". I think it reads fine without giving it an adjective. Annotated allows one to specify a "type" and some metadata that may or may not have anything to do with the type.

[JelleZijlstra]

I would find it difficult to explain how PEP 746 works without some term specifically for the base type.

[JelleZijlstra]

Another option: We could call it the "base expression". That actually works better than type because the "base type" may be an annotation expression, not a type expression (e.g., x: Annotated[Final[int], "some metadata"] is legal).

[AlexWaygood]

I like "inner type" or "wrapped type" for this. I agree with Eric in not particularly liking "base type"

[erictraut]

annotation expressions can be wrapped in Annotated[] according to the grammar I wrote

Oh, I didn't catch that. I think that's a mistake. The first argument to Annotated must be a valid type. This is spelled out clearly later in the spec. The expression Final[int] is not a valid type, so it doesn't make sense for it to be used in Annotated. I think should be fixed this in the grammar, and type checkers should enforce this rule.

[rchen152]

I think the part of the spec that says that the first argument to Annotated must be a valid type is out-of-date. It looks like that restriction was relaxed in this issue. Elsewhere, the spec says that Final may be wrapped by Annotated (near the bottom of this section) and that Required, NotRequired, and Annotated can appear in any nesting order (here).

[erictraut]

Ah yes, I forgot about those provisions elsewhere in the spec. So yes, it sounds like we have an inconsistency here. I think it would be cleaner to allow only type expressions as the first type argument to Annotated, but I guess that ship has sailed, and it would be disruptive to undo that decision.

[erictraut]

I've updated pyright to honor Final when it's nested in Annotated: microsoft/pyright#8097.

[AlexWaygood]

I like "inner type" or "wrapped type" for this. I agree with Eric in not particularly liking "base type"

[carljm]

This is definitely clearer, thank you!

I would prefer to be a bit more precise in our usage of the word "type" in the typing spec. A type specifies a set of possible runtime values. A type expression specifies a type. An annotation expression specifies more than just a type. int is a type; Final[int] is not a type, it's an annotation (though it does include a type, as well as additional qualifiers). So I would not prefer to use the term "base type" for the leftmost thing in Annotated, or to casually refer to Annotated as wrapping a "type".

[AlexWaygood]

Some minor nitpicks below, but basically this looks great to me. I still prefer "wrapped expression" or "underlying expression" to "base expression", but I think "base expression" is also fine

[carljm]

This looks good to me!

[erictraut]

I left a few minor comments. I don't feel that strongly about any of them. If you decide to ignore them for this PR, that's OK with me.

[erictraut]

I find it a bit odd to say that the "term is deprecated". The typing spec is the source of truth here, so is it necessary to clarify that it deviates in terminology from the PEP or from earlier versions of the spec? We don't do this elsewhere in the spec where we have clarified or updated terminology.

[JelleZijlstra]

I think it's helpful in cases where another term was previously in use. I'm not sure there is any comparable situation elsewhere in the spec.

[JelleZijlstra]

The Typing Council has signed off, so I'm merging this.

[erictraut]

Thanks @JelleZijlstra. I scanned through the changes again to see if they required any modifications or additions to the conformance tests, but I didn't see any.