Python 中仅位置参数语义的历史

Python 最初支持仅位置参数。该语言的早期版本无法通过名称绑定参数来调用函数。大约在 Python 1.0 时，参数语义改为位置或关键字。从那时起，用户就可以通过位置或函数定义中指定的关键字名称向函数提供参数。

在当前版本的 Python 中，许多 CPython “内置”和标准库函数只接受仅位置参数。通过使用关键字参数调用其中一个函数，可以很容易地观察到结果语义

>>> help(pow)
...
pow(x, y, z=None, /)
...

>>> pow(x=5, y=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pow() takes no keyword arguments

pow() 通过 / 标记表示其参数是仅位置参数。然而，这只是一个文档约定；Python 开发人员无法在代码中使用此语法。

还有一些函数具有其他有趣的语义

• range()，一个重载函数，在其必需参数的 左侧 接受一个可选参数。[4]
• dict()，其映射/迭代器参数是可选的，并且在语义上必须是仅位置参数。该参数的任何外部可见名称都会遮盖进入 **kwarg 关键字可变参数字典的名称。[3]

可以在 Python 代码中通过接受 (*args, **kwargs) 并手动解析参数来模拟这些语义。然而，这导致函数定义与函数合同接受的内容之间脱节。函数定义与参数处理的逻辑不匹配。

此外，/ 语法在 CPython 之外也被用于指定类似的语义（即，[1] [2]）；因此，表明这些场景并非 CPython 和标准库所独有。

没有仅位置参数的问题

如果没有仅位置参数，库作者和 API 用户都会面临挑战。以下小节概述了每个实体遇到的问题。

仅位置参数的优点

仅位置参数赋予库作者更多的控制权，以更好地表达 API 的预期用法，并允许 API 以安全、向后兼容的方式演进。此外，它使 Python 语言与现有文档以及各种“内置”和标准库函数的行为更加一致。

def as_my_type(x):
    ...

def add_to_queue(item: QueueItem):
    ...

def add_to_queue(items: Union[QueueItem, List[QueueItem]]):
    ...

def add_to_queue(*items: QueueItem):
    ...

io.FileIO.write(self=f, b=b"data")

>>> help(io.FileIO.write)
Help on method_descriptor:

write(self, b, /)
    Write buffer b to file, return number of bytes written.

性能

除了上述优点之外，仅位置参数的解析和处理速度更快。这种性能优势可以在这个关于将关键字参数转换为位置参数的线程中得到证明：[11]。由于这种加速，最近出现了一种将内置函数从关键字参数中移除的趋势：最近，对 bool、float、list、int、tuple 不兼容地进行了更改，以禁止关键字参数。

可维护性

提供一种在 Python 中指定仅位置参数的方法将使维护 C 模块的纯 Python 实现变得更容易。此外，定义函数的库作者将可以选择仅位置参数，如果他们认为传递关键字参数没有提供额外的清晰度。

这是一个在 Python 邮件列表中讨论充分、反复出现的话题

• 2018年9月：Anders Hovmöller: [Python-ideas] 仅位置参数
• 2017年2月：Victor Stinner: [Python-ideas] 仅位置参数，3月继续讨论
• 2017年2月：[9]
• 2012年3月：[8]
• 2007年5月：George Sakkis: [Python-ideas] 仅位置参数
• 2006年5月：Benji York: [Python-Dev] 仅位置参数

逻辑顺序

仅位置参数还有（次要的）好处，即在调用使用它们的接口时强制执行某些逻辑顺序。例如，range 函数将其所有参数按位置接受，并禁止以下形式

range(stop=5, start=0, step=2)
range(stop=5, step=2, start=0)
range(step=2, start=0, stop=5)
range(step=2, stop=5, start=0)

代价是禁止将关键字参数用于（唯一）预期的顺序

range(start=0, stop=5, step=2)

纯 Python 和 C 模块的兼容性

仅位置参数的另一个关键动机是 PEP 399：纯 Python/C 加速器模块兼容性要求。此 PEP 指出

此 PEP 要求在这些情况下，C 代码必须通过用于纯 Python 代码的测试套件，以尽可能合理地作为即插即用替代品

如果 C 代码是使用现有功能通过参数诊所和相关机制来实现仅位置参数，那么纯 Python 对应项不可能匹配提供的接口和要求。这导致 CPython 标准库中某些函数和类的接口与其他 Python 实现之间存在差异。例如

$ python3 # CPython 3.7.2
>>> import binascii; binascii.crc32(data=b'data')
TypeError: crc32() takes no keyword arguments

$ pypy3 # PyPy 6.0.0
>>>> import binascii; binascii.crc32(data=b'data')
2918445923

其他 Python 实现可以手动复制 CPython API，但这违背了 PEP 399 的精神，即通过强制添加到 Python 标准库的所有模块 必须 具有相同接口和语义的纯 Python 实现来避免重复工作。

子类中的一致性

仅位置参数提供好处的另一个场景发生在子类重写基类方法并更改预期为位置参数的参数名称时

class Base:
    def meth(self, arg: int) -> str:
        ...

class Sub(Base):
    def meth(self, other_arg: int) -> str:
        ...

def func(x: Base):
    x.meth(arg=12)

func(Sub())  # Runtime error

这种情况可能被认为是 Liskov 违反——子类不能在预期基类实例的上下文中使用。在重载方法时重命名参数可能会发生在子类有理由为特定子类领域使用不同的参数名称选择时（例如，当子类化 Mapping 以实现 DNS 查找缓存时，派生类可能不想使用通用参数名称“key”和“value”，而是使用“host”和“address”）。使用仅位置参数的函数定义可以避免这个问题，因为用户将无法使用关键字参数调用接口。通常，为子类化进行设计通常涉及预测尚未编写且作者无法控制的代码。拥有可以促进接口向后兼容演进的措施对库作者将很有用。

优化

支持仅位置参数的最后一个论点是它们允许进行一些新的优化，例如参数诊所中已经存在的优化，因为参数预期以严格的顺序传递。例如，CPython 的内部 METH_FASTCALL 调用约定最近已专门针对仅位置参数的函数进行了优化，以消除处理空关键字的成本。由于仅位置参数，在创建 Python 函数的评估帧时可以应用类似的性能改进。

语法和语义

从“万英尺高空”的角度看，省略 *args 和 **kwargs 以进行说明，函数定义的语法将如下所示

def name(positional_or_keyword_parameters, *, keyword_only_parameters):

在此示例的基础上，函数定义的新语法将如下所示

def name(positional_only_parameters, /, positional_or_keyword_parameters,
         *, keyword_only_parameters):

以下适用

• / 左侧的所有参数都被视为仅位置参数。
• 如果函数定义中未指定 /，则该函数不接受任何仅位置参数。
• 仅位置参数的可选值逻辑与位置或关键字参数的逻辑相同。
• 一旦仅位置参数指定了默认值，则后续的仅位置参数和位置或关键字参数也需要具有默认值。
• 没有默认值的仅位置参数是 必需 的仅位置参数。

因此，以下是有效的函数定义

def name(p1, p2, /, p_or_kw, *, kw):
def name(p1, p2=None, /, p_or_kw=None, *, kw):
def name(p1, p2=None, /, *, kw):
def name(p1, p2=None, /):
def name(p1, p2, /, p_or_kw):
def name(p1, p2, /):

就像今天一样，以下是有效的函数定义

def name(p_or_kw, *, kw):
def name(*, kw):

而以下将是无效的

def name(p1, p2=None, /, p_or_kw, *, kw):
def name(p1=None, p2, /, p_or_kw=None, *, kw):
def name(p1=None, p2, /):

完整语法规范

所提议语法规范的简化视图是

typedargslist:
  tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [','  # and so on

varargslist:
  vfpdef ['=' test] (',' vfpdef ['=' test])* ',' '/' [','  # and so on

根据此 PEP 中的参考实现，typedarglist 的新规则将是

typedargslist: (tfpdef ['=' test] (',' tfpdef ['=' test])* ',' '/' [',' [tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [
        '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
      | '**' tfpdef [',']]]
  | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
  | '**' tfpdef [',']] ] )| (
   tfpdef ['=' test] (',' tfpdef ['=' test])* [',' [
        '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
      | '**' tfpdef [',']]]
 | '*' [tfpdef] (',' tfpdef ['=' test])* [',' ['**' tfpdef [',']]]
 | '**' tfpdef [','])

对于 varargslist 将是

varargslist: vfpdef ['=' test ](',' vfpdef ['=' test])* ',' '/' [',' [ (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [
        '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
      | '**' vfpdef [',']]]
  | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
  | '**' vfpdef [',']) ]] | (vfpdef ['=' test] (',' vfpdef ['=' test])* [',' [
        '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
      | '**' vfpdef [',']]]
  | '*' [vfpdef] (',' vfpdef ['=' test])* [',' ['**' vfpdef [',']]]
  | '**' vfpdef [',']
)

语义的特殊情况

以下是规范的一个有趣的推论。考虑这个函数定义

def foo(name, **kwds):
    return 'name' in kwds

没有可能的调用会使其返回 True。例如

>>> foo(1, **{'name': 2})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: foo() got multiple values for argument 'name'
>>>

但是使用 / 我们可以支持这个

def foo(name, /, **kwds):
    return 'name' in kwds

现在上面的调用将返回 True。

换句话说，仅位置参数的名称可以在 **kwds 中使用而不会产生歧义。（作为另一个例子，这有利于 dict() 和 dict.update() 的签名。）

“/”作为分隔符的由来

使用 / 作为分隔符最初由 Guido van Rossum 在 2012 年提出 [8]

替代提议：使用“/”怎么样？它有点像“*”的反面，后者表示“关键字参数”，而“/”不是一个新字符。

位置或关键字参数

如果函数定义中不存在 / 和 *，则参数可以通过位置或关键字传递给函数。

仅位置参数

更详细地来看，可以将某些参数标记为 仅位置。如果是 仅位置，则参数的顺序很重要，并且参数不能通过关键字传递。仅位置参数将放置在 /（正斜杠）之前。/ 用于在逻辑上将仅位置参数与其余参数分开。如果函数定义中没有 /，则没有仅位置参数。

/ 后面的参数可以是 位置或关键字 或 仅关键字。

仅限关键字参数

要将参数标记为 仅关键字，表示参数必须通过关键字参数传递，请在参数列表中的第一个 仅关键字 参数之前放置一个 *。

函数示例

考虑以下示例函数定义，密切注意标记 / 和 *

>>> def standard_arg(arg):
...     print(arg)
...
>>> def pos_only_arg(arg, /):
...     print(arg)
...
>>> def kwd_only_arg(*, arg):
...     print(arg)
...
>>> def combined_example(pos_only, /, standard, *, kwd_only):
...     print(pos_only, standard, kwd_only)

第一个函数定义 standard_arg 是最常见的形式，它对调用约定没有任何限制，参数可以通过位置或关键字传递

>>> standard_arg(2)
2

>>> standard_arg(arg=2)
2

第二个函数 pos_only_arg 仅限于使用位置参数，因为函数定义中有一个 /

>>> pos_only_arg(1)
1

>>> pos_only_arg(arg=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: pos_only_arg() got an unexpected keyword argument 'arg'

第三个函数 kwd_only_args 仅允许关键字参数，如函数定义中的 * 所示

>>> kwd_only_arg(3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: kwd_only_arg() takes 0 positional arguments but 1 was given

>>> kwd_only_arg(arg=3)
3

最后一个在同一个函数定义中使用了所有三种调用约定

>>> combined_example(1, 2, 3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() takes 2 positional arguments but 3 were given

>>> combined_example(1, 2, kwd_only=3)
1 2 3

>>> combined_example(1, standard=2, kwd_only=3)
1 2 3

>>> combined_example(pos_only=1, standard=2, kwd_only=3)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: combined_example() got an unexpected keyword argument 'pos_only'

总结

用例将决定在函数定义中使用哪些参数

def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

作为指导

• 如果名称不重要或没有意义，并且只有少量参数将始终以相同顺序传递，则使用仅位置参数。
• 当名称有意义并且函数定义通过明确名称更容易理解时，使用仅关键字参数。

不做任何事

总是一个选择——现状。虽然这已被考虑，但上述优点值得添加到语言中。

装饰器

有人在 python-ideas [9] 上建议为此功能提供一个用 Python 编写的装饰器。

这种方法的优点是不会用额外的语法污染函数定义。然而，我们决定拒绝这个想法，因为

• 它引入了参数行为声明方式的不对称性。
• 它使得静态分析器和类型检查器难以安全地识别仅位置参数。它们需要查询 AST 以获取装饰器列表，并通过名称或额外的启发式方法识别正确的装饰器，而仅关键字参数直接暴露在 AST 中。为了工具能够正确识别仅位置参数，它们需要执行模块以访问装饰器设置的任何元数据。
• 任何声明错误都只会在运行时报告。
• 在长函数定义中识别仅位置参数可能更困难，因为它迫使用户数数以了解受装饰器影响的最后一个参数是哪个。
• / 语法已为 C 函数引入。这种不一致性将使实现任何处理此语法的工具和模块更具挑战性——包括但不限于参数诊所、inspect 模块和 ast 模块。
• 装饰器实现可能会带来运行时性能成本，特别是与直接添加到解释器中的支持相比。

逐参数标记

逐参数标记是另一种语言内在选项。该方法为每个参数添加一个标记，以指示它们是仅位置参数，并要求这些参数放置在一起。示例

def (.arg1, .arg2, arg3):

注意 .arg1 和 .arg2 上的点（即 .）。虽然这种方法可能更容易阅读，但它已被拒绝，因为 / 作为显式标记与仅关键字参数的 * 一致，并且不易出错。

应该指出，一些库已经使用前导下划线 [12] 来约定性地指示参数为仅位置参数。

使用“__”作为逐参数标记

一些库和应用程序（如 mypy 或 jinja）使用以双下划线（即 __）开头的名称作为约定来指示仅位置参数。我们拒绝了引入 __ 作为新语法的想法，因为

• 这是一个向后不兼容的更改。
• 它与当前声明仅关键字参数的方式不对称。
• 查询 AST 以获取仅位置参数将需要检查普通参数并检查它们的名称，而仅关键字参数具有与之关联的属性（FunctionDef.args.kwonlyargs）。
• 每个参数都需要检查以知道仅位置参数何时结束。
• 标记更冗长，强制标记每个仅位置参数。
• 它与其他双下划线前缀的用途冲突，例如在类中调用名称修饰。

用括号对仅位置参数进行分组

元组参数解包是 Python 2 的一个特性，它允许在函数定义中使用元组作为参数。它允许序列参数自动解包。一个例子是

def fxn(a, (b, c), d):
    pass

元组参数解包在 Python 3 中被移除 (PEP 3113)。曾有人提议重用此语法来实现仅位置参数。我们拒绝了这种用于指示仅位置参数的语法，原因如下

• 该语法相对于仅关键字参数的声明方式不对称。
• Python 2 使用此语法，可能会引起对此语法行为的混淆。这对于移植使用此功能的 Python 2 代码库的用户来说会很令人惊讶。
• 此语法与元组字面量非常相似。这可能会引起额外的混淆，因为它可能与元组声明混淆。

分隔符提议之后

在 / 之后标记位置参数是另一个考虑过的想法。然而，我们未能找到一种可以修改标记后参数的方法。否则，会强制标记前的参数也为仅位置参数。例如

def (x, y, /, z):

如果我们定义 / 将 z 标记为仅位置参数，则无法将 x 和 y 指定为关键字参数。鉴于目前关键字参数不能后跟位置参数，找到一种解决此限制的方法会增加混淆。因此，/ 会使前面的参数和后面的参数都成为仅位置参数。