Implement PEP 728: TypedDict with Typed Extra Items

[JelleZijlstra]

Feature or enhancement

Proposal:

PEP-728 was just accepted by the Steering Council, so we get to implement it in CPython!

The implementation can likely be largely copied from typing-extensions.

cc @PIG208.

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

No response

Linked PRs

• gh-137840: Implement PEP 728 (closed and extra_items in typing.TypedDict) #137933
• gh-137840: Document PEP 728 #149207

[angela-tarantula]

I’d be happy to take this on and finish it, if that works for you, @JelleZijlstra and @PIG208. I’m really excited about this upgrade and would like to keep contributing to CPython.

Plan

• Port the core extra_items functionality from typing_extensions into stdlib typing.
• Exclude extensions-only code:

  • Backwards-compatibility paths (e.g. __extra_items__ special annotation).
  • The TypedDict[{...}] special form (_TypedDictSpecialForm), which the PEP does not specify.
• Introduce typing.NoExtraItems as a C-level immortal singleton (mirroring NoDefault), to be exported via _typing.

  • Ensures process-wide singleton identity, consistency across typing, etc.
• Update _TypedDictMeta and TypedDict to accept closed and extra_items, and set __closed__ and __extra_items__ on the resulting type.
• Port the relevant tests from test_typing_extensions: test_closed_values, test_extra_items_class_arg, test_closed_inheritance, test_implicit_extra_items, test_cannot_combine_closed_and_extra_items, plus test_typed_dict_signature (adjusted to remove kwargs).
• Update documentation, maybe in a separate PR?

Open question about closed:

• Should the runtime error for whenclosed and extra_items are "used at the same time" also trigger when closed=False is passed explicitly, or only when closed=True?

[PIG208]

Should the runtime error for whenclosed and extra_items are "used at the same time" also trigger when closed=False is passed explicitly, or only when closed=True?

There should be an error whenever both are specified at the same time, according to the section for closed:

It is a runtime error to use the closed and extra_items parameters in the same TypedDict definition.

[angela-tarantula]

Thanks. I'll prepare a PR!

[JelleZijlstra]

The TypedDict[{...}] special form (_TypedDictSpecialForm), which the PEP does not specify.

Yes, this is a separate PEP, which hasn't been accepted yet.

[hugovk]

What's left to do for implementing PEP 728? At least docs and What's New are still needed.

[StanFromIreland]

A little ping @JelleZijlstra.