bpo-46066: Deprecate kwargs syntax for TypedDict definitions

[97littleleaf11]

Closes python/typing#981

https://bugs.python.org/issue46066

[AlexWaygood]

Surely this is a breaking change — even if type-checkers only understand the literal-dict assignment-based syntax, I'm not sure we can change the runtime behaviour like this without a deprecation period.

[97littleleaf11]

Yeah, it changes the typing module. However I seldom see this syntax in real-world projects since we already have class based one.

[97littleleaf11]

I am not really familiar with the cpython developing period. It's not a big deal since neither mypy nor other widely-used type checkers implement this feature and I barely see this syntax in real world projects.

[AlexWaygood]

Yeah, it changes the typing module. However I seldom see this syntax in real-world projects since we already have class based one.

I appreciate that — but given that this is a change to the stdlib, I think the standard deprecation policy probably still applies :)

[97littleleaf11]

I think the standard deprecation policy probably still applies :)

Thanks for pointing out!

[AlexWaygood]

For now, I think I would:

• Change the docs to state that this is deprecated in 3.11, will be removed in 3.13, and probably won't be understood by type checkers like mypy.
• Change the runtime behaviour to emit a warning if a user tries to construct a TypedDict with the kwargs-based syntax.

Here's an example of a previous PR deprecating features, that you could look to as an example: #23064

[AlexWaygood]

It feels absurd to bring this up (sorry!!), but: I think "Jingchen Ye" should go before "Ka-Ping Yee", if we're keeping this list alphabetised.

[AlexWaygood]

Also, it looks like there's some trailing whitespace in some of the documentation changes you've made, which is making the documentation-related tests fail -- could you possibly fix those issues?

[97littleleaf11]

@AlexWaygood Thanks for your reviews! btw, it seems that CI reports wrong line number about the trailing whitespace.

[AlexWaygood]

@AlexWaygood Thanks for your reviews!

No worries, it's a good PR!

btw, it seems that CI reports wrong line number about the trailing whitespace.

Huh — no idea what might be causing that :)

[AlexWaygood]

LGTM

[AlexWaygood]

As this is a deprecation of an existing feature, I think it probably warrants a mention in "What's New in Python 3.11". I think @JelleZijlstra is planning on doing a PR for that document mentioning a bunch of recent changes to typing, though, so perhaps he'll be kind enough to include a mention of this as well :)

[AlexWaygood]

@gvanrossum, could we possibly get the full test suite run on this PR, please? :)

[gvanrossum]

I can't stand "firstly" and "secondly" for some reason. :-(

[97littleleaf11]

I can't stand "firstly" and "secondly" for some reason. :-(

How about "The first one" and "The other one"?

[arhadthedev]

How about "The first one" and "The other one"?

Probably, a bullet list will be better. Like this:

[...] syntactic forms:

• using a literal dict as the second argument:

  Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
  

• using keyword arguments:

  Point2D = TypedDict('Point2D', x=int, y=int, label=str)
  

[JelleZijlstra]

Here's a concrete wording suggestion that avoids "Firstly" and "Secondly"

[JelleZijlstra]

I'd suggest just writing "a TypedDict may be created using a functional form". This parallels https://docs.python.org/3.10/library/enum.html#functional-api

[97littleleaf11]

Thanks for this!

[JelleZijlstra]

Suggested change

	Secondly, using keyword arguments::
	Keyword arguments may also be used::

[gvanrossum]

I was just hoping to see “first“ and “second”. No “ly” needed, these are flat adverbs.

[gvanrossum]

In a few days Jelle can likely merge this himself. :-)

[gvanrossum]

Congrats Jelle!

[AlexWaygood]

And congrats @97littleleaf11 on your first CPython contribution!