Prototype support for typed `**kwargs`

[erictraut]

Many people have requested support for a way to type **kwargs with a TypedDict. There have been proposals to support this using the Unpack type introduced in the recently-accepted PEP 646.

It would be good to prototype this to uncover any potential issues.

• How to handle required fields that are not supplied by the caller?
• How to handle function assignment when the source type contains one of these unpacked TypedDicts?
• Is it necessary/desirable to support unions of TypedDicts? This adds significant complexity.
• Should it support * unpack operator introduced in PEP 646?
• How to handle references to kwargs within the function implementation? Is it the same as any other TypedDict reference?
• How do we deal with the case where a keyword parameter has a name that overlaps with an entry in the TypedDict?
• Should it be an error if an unpacked mapping (with unknown keys) is passed to the function?

[erictraut]

References to recent conversations about this topic:

python/typing#569 (comment)
https://mail.python.org/archives/list/typing-sig@python.org/thread/IUCXT2IQT4YPRN6O56QEVKN24YJG6JSU/#IUCXT2IQT4YPRN6O56QEVKN24YJG6JSU
https://mail.python.org/archives/list/typing-sig@python.org/thread/FGXUFMMUVBT4J4O4LB4WOYRMUANOPWFS/#Z2QXL5ROAMYPEUDYJYLA5PUNEKWGKENS
python/mypy#4441

[JelleZijlstra]

There is also a new typing-sig thread about this. I'm glad you're planning to prototype support for this; it's going to be a useful new feature.

Here are my thoughts on the questions you posed:

How to handle required fields that are not supplied by the caller?

This should be an error.

How to handle function assignment when the source type contains one of these unpacked TypeVarTuples?

I assume you mean TypedDict, not TypeVarTuple. I think we should treat it equivalently to a function with the equivalent explicit parameters. For example, these two functions should be equivalent for the purposes of assignabiliity:

class TD(TypedDict):
    a: int
    b: NotRequired[str]

def f1(**kwargs: Unpack[TD]): ...
def f2(*, a: int, b: str = ...): ...

Is it necessary/desirable to support unions of TypedDicts? This adds significant complexity.

Probably not; it adds a lot of complexity and I don't see a compelling use case.

Should it support * unpack operator introduced in PEP 646?

PEP 646's syntactic changes will not make **kwargs: *TD legal, and in any case the more obvious syntax is **kwargs: **TD. That would require another syntax change in CPythoon.

How to handle references to kwargs within the function implementation? Is it the same as any other TypedDict reference?

I think so. We should treat this new feature the same as any other TypedDict as much as possible, so the type system is more internally consistent.

How do we deal with the case where a keyword parameter has a name that overlaps with an entry in the TypedDict?

This should be an error.

Should it be an error if an unpacked mapping (with unknown keys) is passed to the function? Should this be an error?

I think it should be treated the same as a regular assignment. So if x: TD = {some: mapping} is illegal, then the corresponding call f(**{some: mapping) (with def f(**kwargs: **TD)) should also be illegal.

[erictraut]

This functionality will be included in the next release.

[erictraut]

This is included in pyright 1.1.222, which I just published. It will also be included in the next release of pylance.

[PatrickBourdon]

Pylance v2022.2.3 was published on 17/02/2022 two days ago.
Reading the issue thread, I was expecting that something like the following may then be typed and checked correctly:

from typing import TypedDict, Unpack
class MyFuncKwargs(TypedDict):
    a: str
    b: int
def my_func(**kwargs: Unpack[MyFuncKwargs]) -> None:
    return
my_func(a='a', b=1)

But obviously I did miss something. (Unpack is unknown).

[erictraut]

Unpack is new to Python 3.11 and hasn't yet been incorporated in the latest pre-alpha releases of 3.11. You'll need to import it from typing_extensions in the meantime.

from typing import TypedDict
from typing_extensions import Unpack

class MyFuncKwargs(TypedDict):
    a: str
    b: int

def my_func(**kwargs: Unpack[MyFuncKwargs]) -> None:
    return

my_func(a="a", b=1)