Update unpack TypedDict kwargs forwarding spec + add conformance tests by yangdanny97 · Pull Request #2338 · python/typing

yangdanny97 · 2026-08-11T01:22:50Z

Previously, this section of the spec was not exercised at all in the conformance tests, and also was not implemented by any type checker.

This PR updates the spec to account for closed & extra_items TypedDicts, and adds conformance tests.

There are 3 asserted errors:

open TypedDict kwargs being unpacked into function w/o kwargs (no type checker implements this)
extra_items TypedDict kwargs being unpacked into function w/o kwargs (only ty implements this)
extra_items TypedDict kwargs being unpacked into function w/ incompatibly-typed kwargs (ty, pyright, and zuban implement this)

This would supersede #1960, which proposed that we delete the section of the spec entirely.
@rchen152's comment in https://discuss.python.org/t/typing-spec-inconsistency-for-unpacking-typed-dict-kwargs/79640 favors deletion.

carljm · 2026-08-11T01:45:33Z

This issue is nuanced, because many unpacking behaviors in Python are unsafe. If you unpack a list[int] into a function that takes (int, int) (but not *args: int), every type checker allows that, even though the list could obviously contain fewer or more than two elements. The collective decision seems to be that since length is not part of what the list type encodes, we trust the user rather than erroring.

In ty we made the decision not to error on the first case here, because we saw large mypy-primer fallout if we enforced this rule, and we felt it was analogous to the case of list[int] -- an open TypedDict may contain extra elements (just like a list may contain any number of elements), but the type doesn't explicitly say that it does, so we can be forgiving here.

We decided to be stricter with extra_items, in part because there is no widespread usage yet, so usage will adapt to what type checkers permit, and in part because in this case the user has explicitly declared their intent for the TypedDict to contain extra items, so it feels reasonable to account for that more strictly. This does mean that implicitly open typed dicts are not equivalent to extra_items=ReadOnly[object], which maybe in principle they would be -- but I think this is currently true in all type checkers.

I think ty's compromise is reasonable, but I'm not totally convinced it's the best option, open to other resolutions here. But enforcing this rule on all implicitly open TypedDicts will have a significant impact on existing real-world code.

yangdanny97 · 2026-08-11T02:59:22Z

For Pyrefly my current thought is that this would be off-by-default and enabled in strict mode.

carljm · 2026-08-11T05:13:39Z

That seems reasonable. I'm not sure if behavior that we wouldn't turn on by default in our own type checkers should be encoded as a conformance suite requirement, though?

It seems to me that a strict mode which requires safety in unpacking an open TypedDict should probably also require safety in unpacking a list/Sequence?

yangdanny97 · 2026-08-11T12:40:18Z

So do you think that we should just merge #1960 and delete this section from the typing spec entirely?

Or weaken the first assertion to "may" and "E?"

carljm · 2026-08-11T14:16:00Z

I would probably land this with the first assertion weakened (and discussion of that in the spec also), but that's not a strong preference, it just matches what we decided to do in ty, so naturally it already makes sense to me :) Very open to other opinions here.

…ypedDicts optional

yangdanny97 · 2026-08-12T03:33:35Z

Does it make sense to differentiate between implicitly open and explicitly open (closed=False), by making errors mandatory for the latter?

carljm · 2026-08-12T14:41:59Z

Does it make sense to differentiate between implicitly open and explicitly open (closed=False), by making errors mandatory for the latter?

It might. Currently in ty we only apply the extra strictness with extra_items=, not with closed=False. I think the appeal of this is that keeps closed itself boolean rather than tri-valued (that is, closed=False is the default and providing it explicitly makes no difference), but closed=False alone is not the same thing as explicitly providing an extra_items type -- the latter more explicitly says "I expect there to be extra items in this dict of a particular type". But all of this is a judgment call, there's no clear right or wrong answer. Or rather, the "right" answer in the abstract is probably the universal strictness you initially proposed, it's just a question of whether that's workable in the ecosystem.

JelleZijlstra · 2026-08-13T04:05:04Z

The current TypedDict spec says that closed=False means the TypedDict is open, i.e. consistent with the default. I think we should stick with the TypedDict spec chapter's clear division of TypedDicts into states, and allow unsound behavior only if the TypedDict is open (as defined by the spec; the spec change in this PR should link to the glossary definition for the term).

In the abstract I'd prefer to treat open TypedDicts similar to ones with extra_items=ReadOnly[object], but I agree that's probably a bridge too far right now.

…tly open ones

carljm

Thank you!

carljm · 2026-08-13T15:50:12Z

-would not cause errors at runtime during function invocation. Otherwise, the
-type checker should generate an error.
+Therefore, it is only safe to pass ``kwargs`` hinted with an unpacked, non-:term:`closed` ``TypedDict``
+to another function if that function has ``**kwargs`` in its signature as well. Type checkers should


Should we also explicitly require possible extra-item values to be assignable to the destination's **kwargs annotation? Having **kwargs alone isn't sufficient:

class Open(TypedDict): name: str def target(name: str, **kwargs: int) -> None: ... def forward(**kwargs: Unpack[Open]) -> None: target(**kwargs) # Hidden extra items have type object, not int.

Both ty and pyright reject this, while zuban currently accepts it. I think the optional-error compromise should apply to unexpected keyword names, not to values that are incompatible with an explicitly annotated parameter. Could we spell out that distinction and cover forwarding an open TypedDict into typed **kwargs?

carljm · 2026-08-13T15:50:12Z

+def func10(**kwargs: Unpack[TD5]) -> None:
+    takes_name(**kwargs)  # E: extra items may be present
+    takes_name_str_kwargs(**kwargs)  # E: extra items type is not compatible
+    takes_name_int_kwargs(**kwargs)


What happens when an extra item binds an explicitly declared optional parameter instead of the variadic parameter? For example:

def target( name: str, *, label: str = "", **kwargs: int ) -> None: ... def forward(**kwargs: Unpack[TD5]) -> None: target(**kwargs) # TD5 could supply label=1.

The variadic parameter accepts int, but label does not. ty and zuban reject this; pyright currently accepts it. Could we cover both incompatible and compatible optional parameters, and maybe the corresponding ReadOnly[int] extra-items case?

carljm · 2026-08-13T15:50:12Z

-conformant = "Pass"
+conformant = "Partial"
+notes = """
+Does not reject passing unpacked kwargs typed with a non-closed TypedDict to a callable that has no `**kwargs`.


Should we remove this note here and from the other checker results? The updated spec explicitly allows an open TypedDict to be forwarded without an error, and the corresponding test is marked E?, so accepting that case isn't a conformance failure. (The separate note about explicitly declared extra_items still makes sense.)

carljm · 2026-08-13T15:50:12Z

 In cases similar to the ``bar`` function above the problem could be worked
-around by explicitly dereferencing desired fields and using them as arguments
-to perform the function call::
+around by marking ``Animal`` with ``closed=True``, or by explicitly dereferencing desired


I think the same closed-TypedDict distinction also affects the earlier callable-assignment rule in this chapter, which currently says a callable without **kwargs can never be assigned to a destination with **kwargs: Unpack[TypedDict]. For example:

class Closed(TypedDict, closed=True): name: str class AcceptsClosed(Protocol): def __call__(self, **kwargs: Unpack[Closed]) -> None: ... def takes_name(*, name: str) -> None: ... callback: AcceptsClosed = takes_name

Both ty and pyright accept this assignment, and the hidden-key rationale doesn't apply because Closed cannot contain extra keys. Would it make sense to update that earlier rule and add closed-assignment coverage while we're clarifying this? extra_items=Never should behave the same way.

Yep, I can add that and add some tests

carljm · 2026-08-13T15:50:12Z

+# > should error if the ``TypedDict`` has ``extra_items``, and may error if the ``TypedDict`` is open.
+
+def func8(**kwargs: Unpack[TD3]) -> None:
+    takes_name(**kwargs)  # E?: a subtype may contain unknown keys


Should we also cover directly unpacking ordinary TypedDict-annotated parameters or locals, not just a function's own **kwargs? The existing spec already demonstrates this with baz(animal: Animal), and the same rules should apply regardless of where the TypedDict came from:

def forward_direct(value: TD5) -> None: takes_name(**value) # E: extra items may be present takes_name_str_kwargs(**value) # E: int is incompatible with str

It would be useful to include the corresponding open and closed cases too, so a checker can't pass by special-casing **kwargs provenance.

carljm · 2026-08-13T16:00:05Z

 notes = """
 Allows callable without kwargs to be assigned to callable with unpacked kwargs.
+Does not support the `closed` and `extra_items` TypedDict class arguments.
+Does not reject passing unpacked kwargs typed with a non-closed TypedDict to a callable that has no `**kwargs`.


Remove this note? Accepting an open TypedDict here is explicitly permitted by the updated spec, and the corresponding test is marked E?. The separate extra_items note is the actual conformance issue.

carljm · 2026-08-13T16:00:06Z

-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Does not reject passing unpacked kwargs typed with a non-closed TypedDict to a callable that has no `**kwargs`.


carljm · 2026-08-13T16:00:06Z

-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Does not reject passing unpacked kwargs typed with a non-closed TypedDict to a callable that has no `**kwargs`.


carljm · 2026-08-13T16:00:07Z

-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Does not reject passing unpacked kwargs typed with a non-closed TypedDict to a callable that has no `**kwargs`.


carljm · 2026-08-13T16:08:42Z

-to has ``**kwargs`` in its signature as well, because then additional keywords
-would not cause errors at runtime during function invocation. Otherwise, the
-type checker should generate an error.
+Therefore, it is only safe to pass ``kwargs`` hinted with an unpacked, non-:term:`closed` ``TypedDict``


This rule shouldn't be specific to forwarding kwargs -- but I guess that would imply a larger rewrite of this whole section. (Which I think we should do, but maybe not in this PR.) The existing text is way too focused on specific cases rather than outlining the general principles.

I can reword this part a little bit in this PR, but let's save a bigger rewrite for later

update typeddict kwarg forwarding test

59c2a2c

yangdanny97 changed the title ~~Add tests for unpack TypedDict kwargs forwarding~~ Update unpack TypedDict kwargs forwarding spec + add conformance tests Aug 11, 2026

update spec wording and results to make erroring on implicitly open T…

8368356

…ypedDicts optional

link to terms & handle implicitly open typeddicts the same as explici…

2678723

…tly open ones

carljm reviewed Aug 13, 2026

View reviewed changes

yangdanny97 added 3 commits August 13, 2026 15:39

address reviewer comments, revise spec and add a bunch of test cases

846feb7

modify notes

b140018

merge main

b0ac496

Uh oh!

Conversation

yangdanny97 commented Aug 11, 2026

Uh oh!

carljm commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yangdanny97 commented Aug 11, 2026

Uh oh!

carljm commented Aug 11, 2026

Uh oh!

yangdanny97 commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

carljm commented Aug 11, 2026

Uh oh!

yangdanny97 commented Aug 12, 2026

Uh oh!

carljm commented Aug 12, 2026

Uh oh!

JelleZijlstra commented Aug 13, 2026

Uh oh!

carljm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carljm Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

carljm commented Aug 11, 2026 •

edited

Loading

yangdanny97 commented Aug 11, 2026 •

edited

Loading

carljm Aug 13, 2026 •

edited

Loading