摘要

目前，**kwargs 可以使用类型提示，只要所有由其指定的关键字参数都是相同类型即可。但是，这种行为可能非常有限。因此，在本 PEP 中，我们提出了一种新的方法来启用更精确的 **kwargs 类型提示。新方法围绕使用 TypedDict 来对包含不同类型关键字参数的 **kwargs 进行类型提示。

动机

目前，使用类型 T 对 **kwargs 进行注释意味着 kwargs 类型实际上是 dict[str, T]。例如

def foo(**kwargs: str) -> None: ...

表示 foo 中的所有关键字参数都是字符串（即 kwargs 的类型为 dict[str, str]）。这种行为限制了仅对所有关键字参数都是相同类型的情况进行 **kwargs 类型注释的能力。但是，关键字参数通常由 **kwargs 传递，并且具有不同的类型，这些类型取决于关键字的名称。在这些情况下，无法对 **kwargs 进行类型注释。这对于已经存在的代码库尤其是一个问题，因为为了引入正确的类型注释而重构代码的需求可能被认为不值得付出努力。这反过来又阻止了项目获得类型提示可以提供的所有好处。

此外，**kwargs 可用于减少代码量，在某些情况下，存在一个作为公共 API 一部分的顶级函数，它调用了许多辅助函数，所有这些函数都期望相同的关键字参数。不幸的是，如果这些辅助函数要使用 **kwargs，则如果它们期望的关键字参数类型不同，则无法正确地对其进行类型提示。此外，即使关键字参数类型相同，也无法检查函数是否使用它实际期望的关键字名称进行调用。

如 预期用途 部分所述，使用 **kwargs 并不总是最佳选择。尽管如此，它仍然是一种广泛使用的模式。因此，围绕支持更精确的 **kwargs 类型提示进行了大量讨论，并且它成为对 Python 社区很大一部分有价值的功能。这一点在 mypy GitHub 问题 4441 中得到了最好的体现，该问题包含了许多可以从本提案中受益的实际案例。

另一个值得一提的使用案例是 **kwargs 方便的地方，即当函数应该适应没有默认值的可选关键字参数时。当通常用作默认值以指示没有用户输入的值（如 None）可以由用户传入并应导致有效的非默认行为时，可能会出现对这种模式的需求。例如，此问题 出现在 流行的 httpx 库中。

基本原理

PEP 589 引入了 TypedDict 类型构造器，它支持由字符串键和可能不同类型的值组成的字典类型。由以双星号开头的形式参数（例如 **kwargs）表示的函数的关键字参数作为字典接收。此外，此类函数通常使用解包字典来提供关键字参数。这使得 TypedDict 成为用于更精确的 **kwargs 类型提示的完美候选者。此外，使用 TypedDict，可以在静态类型分析期间考虑关键字名称。但是，使用 TypedDict 指定 **kwargs 类型意味着，如前所述，由 **kwargs 指定的每个关键字参数本身都是一个 TypedDict。例如

class Movie(TypedDict):
    name: str
    year: int

def foo(**kwargs: Movie) -> None: ...

表示 foo 中的每个关键字参数本身都是一个 Movie 字典，该字典具有一个类型值为字符串的 name 键和一个类型值为整数的 year 键。因此，为了支持将 kwargs 类型指定为 TypedDict 而不破坏当前行为，必须引入新的构造。

为了支持此用例，我们建议重用 Unpack，该构造最初在 PEP 646 中引入。这样做有几个原因

• 它的名称非常适合并且直观，适用于 **kwargs 类型提示用例，因为我们的目的是从提供的 TypedDict 中“解包”关键字参数。
• *args 的当前类型提示方式将扩展到 **kwargs，并且它们应该具有类似的行为。
• 无需引入任何新的特殊形式。
• 在本 PEP 中描述的目的使用 Unpack 不会干扰 PEP 646 中描述的使用案例。

规范

使用 Unpack，我们引入了一种新的注释 **kwargs 的方法。继续前面的示例

def foo(**kwargs: Unpack[Movie]) -> None: ...

表示 **kwargs 包含由 Movie 指定的两个关键字参数（即类型为 str 的 name 关键字和类型为 int 的 year 关键字）。这表示应如下调用该函数

kwargs: Movie = {"name": "Life of Brian", "year": 1979}

foo(**kwargs)                               # OK!
foo(name="The Meaning of Life", year=1983)  # OK!

当使用 Unpack 时，类型检查器将函数体内的 kwargs 视为 TypedDict

def foo(**kwargs: Unpack[Movie]) -> None:
    assert_type(kwargs, Movie)  # OK!

使用新的注释不会有任何运行时影响 - 类型检查器应该只考虑它。以下各节中提到的任何错误都与类型检查器错误相关。

def foo(**kwargs: Unpack[Movie]) -> None: ...

movie: dict[str, object] = {"name": "Life of Brian", "year": 1979}
foo(**movie)  # WRONG! Movie is of type dict[str, object]

typed_movie: Movie = {"name": "The Meaning of Life", "year": 1983}
foo(**typed_movie)  # OK!

another_movie = {"name": "Life of Brian", "year": 1979}
foo(**another_movie)  # Depends on the type checker.

def foo(name, **kwargs: Unpack[Movie]) -> None: ...     # WRONG! "name" will
                                                        # always bind to the
                                                        # first parameter.

def foo(name, /, **kwargs: Unpack[Movie]) -> None: ...  # OK! "name" is a
                                                        # positional-only parameter,
                                                        # so **kwargs can contain
                                                        # a "name" keyword.

class Movie(TypedDict):
    title: str
    year: NotRequired[int]

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def accept_animal(**kwargs: Unpack[Animal]): ...
def accept_dog(**kwargs: Unpack[Dog]): ...

accept_dog = accept_animal  # OK! Expression of type Dog can be
                            # assigned to a variable of type Animal.

accept_animal = accept_dog  # WRONG! Expression of type Animal
                            # cannot be assigned to a variable of type Dog.

class Example(TypedDict):
    animal: Animal
    string: str
    number: NotRequired[int]

def src(**kwargs: Unpack[Example]): ...
def dest(*, animal: Dog, string: str, number: int = ...): ...

dest = src  # OK!

def dest(dog: Dog, string: str, number: int = ...): ...

dog: Dog = {"name": "Daisy", "breed": "labrador"}

dest(dog, "some string")  # OK!

dest = src                # Type checker error!
dest(dog, "some string")  # The same call fails at
                          # runtime now because 'src' expects
                          # keyword arguments.

def dest(**kwargs: Unpack[Animal]): ...
def src(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

dest = src      # WRONG!
dest(**animal)  # Fails at runtime.

def src(**kwargs): ...
def dest(**kwargs: Unpack[Movie]): ...

dest = src  # OK!

class Vehicle:
    ...

class Car(Vehicle):
    ...

class Motorcycle(Vehicle):
    ...

class Vehicles(TypedDict):
    car: Car
    moto: Motorcycle

def dest(**kwargs: Unpack[Vehicles]): ...
def src(**kwargs: Vehicle): ...

dest = src  # OK!

class Animal(TypedDict):
    name: str

class Dog(Animal):
    breed: str

def takes_name(name: str): ...

dog: Dog = {"name": "Daisy", "breed": "Labrador"}
animal: Animal = dog

def foo(**kwargs: Unpack[Animal]):
    print(kwargs["name"].capitalize())

def bar(**kwargs: Unpack[Animal]):
    takes_name(**kwargs)

def baz(animal: Animal):
    takes_name(**animal)

def spam(**kwargs: Unpack[Animal]):
    baz(kwargs)

foo(**animal)   # OK! foo only expects and uses keywords of 'Animal'.

bar(**animal)   # WRONG! This will fail at runtime because 'breed' keyword
                # will be passed to 'takes_name' as well.

spam(**animal)  # WRONG! Again, 'breed' keyword will be eventually passed
                # to 'takes_name'.

def bar(**kwargs: Unpack[Animal]):
    name = kwargs["name"]
    takes_name(name)

>>> Unpack[Movie]
*<class '__main__.Movie'>

预期用途

本提案的预期用例在 动机 部分进行了描述。总之，更精确的 **kwargs 键入可以为已经存在的代码库带来好处，这些代码库最初决定使用 **kwargs，但现在已经足够成熟，可以通过类型提示使用更严格的契约。使用 **kwargs 还可以帮助减少代码重复和复制粘贴的数量，当有一堆函数需要相同的关键字参数集时。最后，**kwargs 对于函数需要方便没有明显默认值的可选关键字参数的情况很有用。

但是，必须指出的是，在某些情况下，与本 PEP 中提出的使用 TypedDict 键入 **kwargs 相比，还有更好的工具可供选择。例如，在编写新代码时，如果所有关键字参数都是必需的或具有默认值，那么显式地编写所有内容都比使用 **kwargs 和 TypedDict 更好。

def foo(name: str, year: int): ...     # Preferred way.
def foo(**kwargs: Unpack[Movie]): ...

类似地，当通过存根为第三方库键入类型时，最好显式地声明函数签名 - 这是键入此类函数的唯一方法，如果它有默认参数。在这种情况下尝试使用 TypedDict 为函数键入类型时，可能会出现另一个问题，即某些标准函数参数可能会被视为仅限关键字参数。

def foo(name, year): ...              # Function in a third party library.

def foo(Unpack[Movie]): ...           # Function signature in a stub file.

foo("Life of Brian", 1979)            # This would be now failing type
                                      # checking but is fine.

foo(name="Life of Brian", year=1979)  # This would be the only way to call
                                      # the function now that passes type
                                      # checking.

因此，在这种情况下，最好再次显式地键入此类函数，如下所示：

def foo(name: str, year: int): ...

此外，为了使 IDE 和文档页面受益，公共 API 中的函数应尽可能优先使用显式关键字参数。

如何教授

本 PEP 可以链接到 typing 模块的文档中。此外，可以在上述文档中添加一个关于使用 Unpack 的新部分。类似的部分也可以添加到 mypy 文档 和 typing RTD 文档 中。

参考实现

mypy 类型检查器 已经 支持 使用 Unpack 进行更精确的 **kwargs 键入。

Pyright 类型检查器 也 提供了临时支持 此功能。

被拒绝的想法

class Book(TypedDict):
    genre: str
    pages: int

TypedDictUnion = Movie | Book

def foo(**kwargs: Unpack[TypedDictUnion]) -> None: ...  # WRONG! Unsupported use
                                                        # of a union of
                                                        # TypedDicts to type
                                                        # **kwargs

@overload
def foo(**kwargs: Unpack[Movie]): ...

@overload
def foo(**kwargs: Unpack[Book]): ...

def foo(**kwargs: **Movie): ...

def foo(**kwargs: Unpack[Movie]): ...

版权

本文档置于公共领域或根据 CC0-1.0-Universal 许可证，以两者中许可范围更宽者为准。