迟早，您会阅读像 def handler(*args, **kwargs) 这样的函数并想知道它接受什么。 Python *args 和 **kwargs 让函数接受灵活数量的参数。它们为装饰器、包装器和许多库 API 提供支持。

本指南介绍了它们如何在两个方向上工作，以及 Python 让您控制函数调用方式的新方法。我们在 Python 3.13 上运行每个示例，显示的输出来自该运行。

*args 的作用是什么

用一颗星编写的参数将所有额外的位置参数收集到一个元组中：

def total(*args):
    print(type(args).__name__, args)
    return sum(args)

print(total(1, 2, 3))
# tuple (1, 2, 3)
# 6

print(total())
# tuple ()
# 0

如果没有参数，您只需得到一个空元组，因此该函数仍然有效。名称 args 是一种约定。 *numbers 的行为是相同的，并且更具描述性的名称通常更好。

**kwargs 做什么

两颗星将所有额外的关键字参数收集到字典中：

def describe(**kwargs):
    print(type(kwargs).__name__, kwargs)

describe(name="Asha", city="Pune")
# dict {'name': 'Asha', 'city': 'Pune'}

因为它是一个普通的 字典 ，所以您可以循环它，使用 get() 查找键并将其传递。密钥保持其传递的顺序。

参数顺序

当混合各种参数时，Python 需要特定的顺序：

1. 常规位置参数
2. *参数
3. 仅限关键字参数
4. **夸格

def order(item, qty=1, *extras, priority=False, **notes):
    print(item, qty, extras, priority, notes)

order("pen")
# pen 1 () False {}

order("pen", 2, "gift wrap", "card", priority=True, note="leave at door")
# pen 2 ('gift wrap', 'card') True {'note': 'leave at door'}

注意priority。因为它位于 *extras 之后，所以只能通过名称设置，因此杂散的位置参数永远不会意外设置它。不允许将 **kwargs 放在前面，我们的测试提出了 SyntaxError：“参数不能跟随 var-keyword 参数”。

打电话时拆箱

相同的星星在呼叫站点以相反的方式工作。一颗星将列表或元组扩展为位置参数，两颗星将字典扩展为关键字参数：

nums = [4, 5, 6]
total(*nums)            # same as total(4, 5, 6) -> 15

settings = {"name": "Ben", "city": "Delhi"}
describe(**settings)    # same as describe(name="Ben", city="Delhi")

解包适用于任何函数，而不仅仅是那些使用 *args 和 **kwargs 的函数。当配置以字典形式出现时，这很方便：

def connect(host, port, timeout=5):
    return f"{host}:{port} (timeout {timeout})"

connect(**{"host": "db.local", "port": 5432})
# 'db.local:5432 (timeout 5)'

connect(**{"host": "db.local", "port": 5432, "ssl": True})
# TypeError: connect() got an unexpected keyword argument 'ssl'

这个错误很有用。没有 **kwargs 的函数会拒绝未知选项，因此设置名称中的拼写错误会大声失败，而不是被默默地忽略。

仅关键字参数

签名中的裸 * 没有名称，表示“此后的所有内容都必须通过关键字传递”：

def make_user(name, *, admin=False):
    return name, admin

make_user("Asha", admin=True)
# ('Asha', True)

make_user("Asha", True)
# TypeError: make_user() takes 1 positional argument but 2 were given

这是保护布尔标志的好方法。像 make_user("Asha", True) 这样的调用迫使读者猜测 True 的含义。要求 admin=True 使每个调用都不言自明。

仅位置参数

从Python 3.8开始，a /标记只能按位置传递的参数：

def area(width, height, /):
    return width * height

area(3, 4)                 # 12
area(width=3, height=4)
# TypeError: area() got some positional-only arguments
#   passed as keyword arguments: 'width, height'

这使得库可以在以后重命名这些参数而不会破坏任何人的代码，因为没有人可以依赖这些名称。一些内置函数就是这样工作的。例如，len(obj=[1]) 不起作用。

装饰器和包装器

这是同时使用两者的主要原因。包装器通常需要接受原始函数采用的任何参数，并将它们原封不动地传递：

import functools, time

def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        print(f"{func.__name__} took {time.perf_counter() - start:.4f}s")
        return result
    return wrapper

@timed
def slow_add(a, b, delay=0.01):
    time.sleep(delay)
    return a + b

print(slow_add(2, 3, delay=0.02))
# slow_add took 0.0205s
# 5

包装器根本不需要知道 slow_add 的参数，因此它适用于任何函数。您的时间数字会略有不同。我们的 Python 装饰器 指南解释了 functools.wraps 和其他细节。

合并选项

** 也适用于字典文字，它提供了一种在默认值之上应用覆盖的巧妙方法：

defaults = {"theme": "light", "lang": "en"}

def build(**overrides):
    return {**defaults, **overrides}

build(theme="dark")
# {'theme': 'dark', 'lang': 'en'}

后来的键获胜，因此覆盖替换默认值。子类也使用此模式（如 super().__init__(*args, **kwargs) 中所示）将额外的参数传递给父类。有关 super() 的更多信息，请参阅 Python 类和对象 。

备忘单

何时避免它们

灵活性是有代价的。定义为 def create(**kwargs) 的函数不会告诉读者存在哪些选项，并且编辑器无法自动完成它们。在任何失败之前，打字错误可能会悄悄地通过几层。

因此，当您知道函数需要什么时，更喜欢显式参数。当您真正需要灵活性时，请使用 *args 和 **kwargs：包装器、装饰器、将参数转发到另一个函数，或像 total(*numbers) 这样的真正的可变长度输入。如果一个函数需要很多命名选项，dataclass也可以更清晰。

常见错误

使用可变默认值

这与星星无关，但它经常出现在星星附近。默认值在定义函数时创建一次，然后在调用之间共享：

def bad(items=[]):
    items.append(1)
    return items

print(bad(), bad())
# [1, 1] [1, 1]

两次调用都返回了完全相同的列表，其中包含两个项目。使用 items=None 并在函数内创建一个新列表。

其他错误

• 忘记解压。调用total(nums)传递一个列表而不是三个数字。写total(*nums)。
• 吞掉拼写错误。 接受 **kwargs 但忽略未知键的函数会隐藏拼写错误的选项。验证它们，或者避免**kwargs。
• 两次传递相同的参数。 f(1, **{"a": 2})（其中 a 是第一个参数）会引发“多值”错误。
• 不在包装器中转发。 调用 func(args, kwargs) 传递一个元组和一个字典。正确的形式是func(*args, **kwargs)。

*args 和 **kwargs 的类型提示

*args 和 **kwargs 上的类型提示描述每个单独的值，而不是整个集合。这让很多人感到惊讶：

def total(*prices: float) -> float:
    return sum(prices)      # prices is tuple[float, ...]

def tag(**attrs: str) -> str:
    return " ".join(f'{k}="{v}"' for k, v in attrs.items())   # dict[str, str]

total(1.5, 2.5)                  # 4.0
tag(id="x", role="button")       # id="x" role="button"

这里 prices 被视为浮点数元组，attrs 被视为字符串字典。当关键字参数具有不同类型时，Python 3.12 添加了一个精确选项：TypedDict 与 Unpack 组合。

from typing import TypedDict, Unpack

class Options(TypedDict, total=False):
    timeout: float
    retries: int

def fetch(url: str, **opts: Unpack[Options]) -> None: ...

然后，诸如 mypy 或 Pyright 之类的类型检查器可以拒绝 fetch(url, retries="3") 或拼写错误的选项名称，而普通的 **kwargs 永远无法做到这一点。但运行时行为不会改变。当我们在 Python 3.13 下运行 fetch("u", retries="3") 时，它执行时没有任何抱怨，因为 Python 本身不强制执行类型提示。

如果您发现自己记录了 **kwargs 的一长串可接受的键，请考虑用显式的仅关键字参数替换它们。然后编辑可以自动完成它们，并且错误会立即被发现。

最后的话

记住两个方向。在定义中，星星聚集。在通话中，他们打开行李。添加仅关键字参数以使调用更清晰，并为真正转发参数的代码保留 **kwargs。为了练习，编写一个小的装饰器来记录每个调用的参数，并将其用于几个不同的函数。

常见问题

继续学习