gh-91243: Add typing.Required and NotRequired (PEP 655)

[JelleZijlstra]

I talked to @davidfstr and I offered to implement the runtime part of PEP 655
to make sure we can get it in before the feature freeze. We're going to defer
the documentation to a separate PR, because it can wait until after the feature
freeze.

The runtime implementation conveniently already exists in typing-extensions,
so I largely copied that.

Co-authored-by: David Foster david@dafoster.net

https://bugs.python.org/issue47087

[gvanrossum]

LGTM.

[JelleZijlstra]

Suggested change

	by Jelle Zijlstra.
	by David Foster and Jelle Zijlstra.

@davidfstr wrote the original code in typing-extensions so I shouldn't claim sole credit.

[gvanrossum]

@davidfstr wrote the original code in typing-extensions so I shouldn't claim sole credit.

Then also add a Contributed-by header (or whatever it's called) to the commit message?

[JelleZijlstra]

I put it in the PR header and I'll add it to the commit message when I merge this. (I'll give it some more time though, to give other people a chance to give feedback.)

[davidfstr]

Some comments below. Sorry for any unusual formatting; am writing while mobile:

class C(type(Required)):

Perhaps checking just “Required” as a superclass and not only “type(Required)” would be useful?

for annotation_key, annotation_type in own_annotations.items():

This implementation recognizes both “Required[T]” and “Annotated[Required[T], A]”, but does not recognize multiply-nested Annotateds like ““Annotated[Annotated[Required[T], A1], A2]”. I’m guessing we probably want to support nested Annotateds?

f'{self._name} accepts only single type')

Nit: Accepts only a single type?

Also, is this error message necessarily accurate? That is, could you reasonably get it if you did something other than “pass multiple types”?

Is there a test case for this error message? (I don’t remember one.)

[JelleZijlstra]

Some comments below. Sorry for any unusual formatting; am writing while mobile:

Thanks for the useful feedback!

class C(type(Required)):

Perhaps checking just “Required” as a superclass and not only “type(Required)” would be useful?

Added

for annotation_key, annotation_type in own_annotations.items():

This implementation recognizes both “Required[T]” and “Annotated[Required[T], A]”, but does not recognize multiply-nested Annotateds like ““Annotated[Annotated[Required[T], A1], A2]”. I’m guessing we probably want to support nested Annotateds?

Added a few tests. This already works because the runtime collapses multiple levels of Annotated.

f'{self._name} accepts only single type')

Nit: Accepts only a single type?

Also, is this error message necessarily accurate? That is, could you reasonably get it if you did something other than “pass multiple types”?

Fixed the wording. The message only gets used if the type is a tuple, so it is indeed accurate.

Is there a test case for this error message? (I don’t remember one.)

There is a test for Required[int, str] that triggers this error:

>>> Required[int, str]
<snip>
TypeError: Required accepts only single type. Got (<class 'int'>, <class 'str'>).

[davidfstr]

Last question:

• I see that a period was added to the end of the error messages. Is that consistent with convention for other parts of the typing module (and/or the stdlib)? (I do not know myself.)

Otherwise LGTM.

[JelleZijlstra]

• I see that a period was added to the end of the error messages. Is that consistent with convention for other parts of the typing module (and/or the stdlib)? (I do not know myself.)

These errors get formatted with a second sentence. For example, Final[int, str] will throw TypeError: typing.Final accepts only single type. Got (<class 'int'>, <class 'str'>).. If we don't add the period, that message looks broken.

We should perhaps change those messages (at least, Final should say "a single type"), but we should do it for all types, not just the new ones, and it's better done in a separate PR.

[davidfstr]

If we don't add the period, that message looks broken.

Makes sense.

We should perhaps change those messages (at least, Final should say "a single type"), but we should do it for all types, not just the new ones, and it's better done in a separate PR.

+1 to make the change. +1 to do it in a separate PR.

As mentioned before, everything else LGTM!

[JelleZijlstra]

Thanks! Since Guido and Ken already approved I'm merging this now.