摘要

本文档提出“参数诊所”，这是一种 DSL，用于简化 CPython 实现中内置函数的参数处理。

基本原理和目标

Python 的主要实现“CPython”是用 Python 和 C 的混合语言编写的。CPython 的一个实现细节是所谓的“内置”函数——Python 程序可以使用但用 C 编写的函数。当 Python 程序调用内置函数并传入参数时，必须将这些参数从 Python 值转换为 C 值。此过程称为“解析参数”。

从 CPython 3.3 开始，内置函数几乎总是使用两个函数之一来解析其参数：原始的 PyArg_ParseTuple()，[1] 和更现代的 PyArg_ParseTupleAndKeywords()。 [2] 前者仅处理位置参数；后者还支持关键字和仅限关键字参数，并且在新的代码中更受青睐。

对于这两个函数，调用者都在“格式字符串”中指定了解析参数的转换：[3] 每个参数对应一个“格式单元”，这是一个简短的字符序列，告诉解析函数接受哪些 Python 类型以及如何将其转换为该参数的相应 C 值。

PyArg_ParseTuple() 在最初构思时是合理的。当时只有十几个这样的“格式单元”；每个单元都是不同的，并且易于理解和记忆。但多年来，PyArg_Parse 接口已通过多种方式扩展。现代 API 非常复杂，以至于使用起来有些痛苦。考虑一下

• 现在有 40 个不同的“格式单元”；一些甚至长达三个字符。这使得程序员难以理解格式字符串的内容——或者甚至可能解析它——而不必不断地与文档进行交叉索引。
• 格式字符串中还可能隐藏着六个元格式单元。（它们是："()|$:;"。）
• 添加的格式单元越多，实现者就越不可能为格式单元选择易于使用的助记符，因为选择的字符可能已经被使用。换句话说，我们拥有的格式单元越多，格式单元就变得越模糊。
• 几个格式单元与其他格式单元几乎相同，只有细微的差别。这使得理解格式字符串的确切语义更加困难，并且可能难以确定您到底需要哪个格式单元。
• 文档字符串被指定为静态 C 字符串，这使得读取和编辑稍微麻烦一些，因为它必须遵守 C 字符串引用规则。
• 使用 PyArg_ParseTupleAndKeywords() 向函数添加新参数时，需要修改代码中的六个不同位置：[4]
  • 声明用于存储参数的变量。
  • 在 PyArg_ParseTupleAndKeywords() 中的正确位置传递指向该变量的指针，还要按正确的顺序传递任何“长度”或“转换器”参数。
  • 在传递给 PyArg_ParseTupleAndKeywords() 的“关键字”数组的正确位置添加参数的名称。
  • 在格式字符串的正确位置添加格式单元。
  • 在文档字符串中的原型中添加参数。
  • 在文档字符串中记录参数。
• 目前，内置函数没有机制来提供其“签名”信息（参见 inspect.getfullargspec 和 inspect.Signature）。使用类似于现有 PyArg_Parse 函数的机制添加此信息将需要再次重复自身。

参数诊所的目标是用一种不继承任何这些缺点的机制来替换此 API

• 您只需要指定每个参数一次。
• 所有关于参数的信息都保存在一个地方。
• 对于每个参数，您都指定一个转换函数；参数诊所为您处理从 Python 值到 C 值的转换。
• 参数诊所还允许使用参数化转换函数对参数处理行为进行微调。
• 文档字符串以纯文本编写。函数文档字符串是必需的；鼓励使用每个参数的文档字符串。
• 由此，参数诊所为您生成 CPython 内部需要的全部单调、重复的代码和数据结构。一旦您指定了接口，下一步就是简单地使用本机 C 类型编写您的实现。所有参数解析细节都将为您处理。

参数诊所作为预处理器实现。它直接从 Ned Batchelder 的 [Cog] 中汲取工作流程的灵感。要使用诊所，请在您的 C 源代码中添加一个块注释，该注释以特殊文本字符串开头和结尾，然后在该文件上运行诊所。诊所将找到块注释，处理其内容，并将输出直接写入注释后的 C 源文件中。目的是让诊所的输出成为您源代码的一部分；它被检入版本控制，并与源包一起分发。这意味着 Python 仍然可以随时构建。它确实使开发稍微复杂了一些；为了添加新函数，或使用诊所修改现有函数的参数或文档，您将需要一个可用的 Python 3 解释器。

参数诊所的未来目标包括

• 为内置函数提供签名信息，
• 使 Python 的替代实现能够创建自动库兼容性测试，以及
• 通过改进生成的代码来加快参数解析速度。

DSL 语法摘要

参数诊所 DSL 被指定为嵌入在 C 文件中的注释，如下所示。右侧的“示例”列向您展示了参数诊所 DSL 的示例输入，左侧的“部分”列依次指定了每一行代表的内容。

参数诊所的 DSL 语法模仿了 Python 的 def 语句，使其对 Python 核心开发者具有一定的熟悉感。

+-----------------------+-----------------------------------------------------------------+
| Section               | Example                                                         |
+-----------------------+-----------------------------------------------------------------+
| Clinic DSL start      | /*[clinic]                                                      |
| Module declaration    | module module_name                                              |
| Class declaration     | class module_name.class_name                                    |
| Function declaration  | module_name.function_name  -> return_annotation                 |
| Parameter declaration |       name : converter(param=value)                             |
| Parameter docstring   |           Lorem ipsum dolor sit amet, consectetur               |
|                       |           adipisicing elit, sed do eiusmod tempor               |
| Function docstring    | Lorem ipsum dolor sit amet, consectetur adipisicing             |
|                       | elit, sed do eiusmod tempor incididunt ut labore et             |
| Clinic DSL end        | [clinic]*/                                                      |
| Clinic output         | ...                                                             |
| Clinic output end     | /*[clinic end output:<checksum>]*/                              |
+-----------------------+-----------------------------------------------------------------+

为了让大家对建议的 DSL 语法有所了解，以下是一些诊所代码块示例。第一个代码块反映了通常首选的样式，包括参数和每个参数的文档字符串之间的空行。它还包括一个在本地创建的用户定义转换器（path_t）

/*[clinic]
os.stat as os_stat_fn -> stat result

   path: path_t(allow_fd=1)
       Path to be examined; can be string, bytes, or open-file-descriptor int.

   *

   dir_fd: OS_STAT_DIR_FD_CONVERTER = DEFAULT_DIR_FD
       If not None, it should be a file descriptor open to a directory,
       and path should be a relative string; path will then be relative to
       that directory.

   follow_symlinks: bool = True
       If False, and the last element of the path is a symbolic link,
       stat will examine the symbolic link itself instead of the file
       the link points to.

Perform a stat system call on the given path.

{parameters}

dir_fd and follow_symlinks may not be implemented
  on your platform.  If they are unavailable, using them will raise a
  NotImplementedError.

It's an error to use dir_fd or follow_symlinks when specifying path as
  an open file descriptor.

[clinic]*/

第二个示例显示了一个最小的诊所代码块，省略了所有参数文档字符串和不重要的空行

/*[clinic]
os.access
   path: path
   mode: int
   *
   dir_fd: OS_ACCESS_DIR_FD_CONVERTER = 1
   effective_ids: bool = False
   follow_symlinks: bool = True
Use the real uid/gid to test for access to a path.
Returns True if granted, False otherwise.

{parameters}

dir_fd, effective_ids, and follow_symlinks may not be implemented
  on your platform.  If they are unavailable, using them will raise a
  NotImplementedError.

Note that most operations will use the effective uid/gid, therefore this
  routine can be used in a suid/sgid environment to test if the invoking user
  has the specified access to the path.

[clinic]*/

最后一个示例显示了一个处理可选参数组的诊所代码块，包括左侧的参数

/*[clinic]
curses.window.addch

   [
   y: int
     Y-coordinate.

   x: int
     X-coordinate.
   ]

   ch: char
     Character to add.

   [
   attr: long
     Attributes for the character.
   ]

   /

Paint character ch at (y, x) with attributes attr,
overwriting any character previously painter at that location.
By default, the character position and attributes are the
current settings for the window object.
[clinic]*/

module module_name

class module_name.class_name

dotted.name [ as legal_c_id ] [ -> return_annotation ]

name: converter [ (parameter=value [, parameter2=value2]) ] [ = default]

foo : "i"

directive_name [argument [second_argument [ ... ]]]

Python 代码

Argument Clinic 还允许在 C 文件中嵌入 Python 代码，当 Argument Clinic 处理文件时，该代码会在原地执行。嵌入代码如下所示

/*[python]

# this is python code!
print("/" + "* Hello world! *" + "/")

[python]*/
/* Hello world! */
/*[python end:da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

上面的"/* Hello world! */"行是通过运行前一个注释中的 Python 代码生成的。

任何 Python 代码都是有效的。Argument Clinic 中的 Python 代码部分也可用于直接与 Clinic 交互；请参见Argument Clinic 程序化接口。

输出

Argument Clinic 将其输出内联写入 C 文件，紧跟在 Clinic 代码段之后。对于“python”部分，输出是使用builtins.print打印的所有内容。对于“clinic”部分，输出是有效的 C 代码，包括

• 提供函数的正确methoddef结构的#define
• “impl”函数的原型——这就是您将编写的实现此函数的内容
• 处理所有参数处理的函数，该函数调用您的“impl”函数
• “impl”函数的定义行
• 以及指示输出结束的注释。

我们的意图是让你在输出之后立即编写 impl 函数的主体——也就是说，在输出结束注释之后立即写一个左花括号，并在那里实现内建函数。（一开始有点奇怪，但奇怪地很方便。）

Argument Clinic 会为你定义 impl 函数的参数。该函数将接收最初传入的“self”参数、你定义的所有参数，以及一些可能生成的额外参数（“length”参数；还有“group”参数，参见下一节）。

Argument Clinic 还会为输出部分编写一个校验和。这是一个有价值的安全特性：如果你手动修改输出，Clinic 会注意到校验和不匹配，并拒绝覆盖文件。（你可以使用“-f”命令行参数强制 Clinic 覆盖；Clinic 在使用“-o”命令行参数时也会忽略校验和。）

最后，Argument Clinic 还可以发出为已定义的类和模块生成的 PyMethodDef 数组的样板定义。

具有仅限位置参数的函数

很大一部分用 C 实现的 Python 内建函数使用较旧的仅限位置的 API 来处理参数（PyArg_ParseTuple()）。在某些情况下，这些内建函数会根据传入的参数数量以不同的方式解析其参数。这可以提供一些令人费解的灵活性：可能存在一组可选参数，这些参数必须全部指定或都不指定。偶尔，这些组在左边！（一个代表性的例子：curses.window.addch()。）

Argument Clinic 通过允许你按组指定参数来支持这些遗留用例。每组可选参数都用方括号标记。请注意，这些组允许位于任何必需参数的右侧或左侧！

Clinic 生成的 impl 函数将为每组添加一个额外的参数，“int group_{left|right}_<x>”，其中 x 是分配给每个组的单调递增数字，因为它从必需参数构建。如果该组在此调用中指定，则此参数将不为零，否则为零。

请注意，在这种模式下，你无法指定默认参数。

另外，请注意，可以为函数指定一组组，使得从参数数量到有效组集存在多个有效映射。如果发生这种情况，Clinic 将中止并显示错误消息。这应该不是问题，因为仅限位置的操作仅用于遗留用例，并且所有使用这种奇特行为的遗留函数都具有明确的映射。

当前状态

在撰写本文时，在线提供了一个可用的 Argument Clinic 原型实现（尽管在你阅读本文时，语法可能已过时）。[6] 该原型使用现有的 PyArg_Parse API 生成代码。它支持翻译到所有当前格式单元，除了神秘的 "w*"。使用 Argument Clinic 的示例函数练习了所有主要功能，包括仅限位置的参数解析。

注释/待定

• 为内建函数提供 inspect.Signature 元数据的 API 目前正在讨论中。Argument Clinic 在其变得可行时将添加对原型的支持。
• Alyssa Coghlan 建议我们 a) 每个函数最多只支持一个左可选组，以及 b) 在出现歧义的情况下，优先选择左组而不是右组。这将解决我们所有现有的用例，包括 range()。
• 理想情况下，我们希望 Argument Clinic 作为正常 Python 构建过程的一部分自动运行。但这会带来一个引导问题；如果你没有系统 Python 3，你需要一个 Python 3 可执行文件来构建 Python 3。我相信这是一个可以解决的问题，但我不知道最佳解决方案是什么。（支持这一点还需要为 Windows 提供并行解决方案。）
• 相关说明：inspect.Signature 无法表示参数块，例如 curses.window.addch 的 y 和 x 的左可选块。在支持这种公认的异常参数范式方面，我们要走多远？
• 在 PyCon US 2013 语言峰会上，讨论了让 Argument Clinic 也生成函数的实际文档（以 ReST 格式，由 Sphinx 处理）。这方面的细节尚待确定，但这需要以 ReST 格式编写文档字符串，并需要 Python 附带一个 ReST -> ascii 转换器。最好在我们开始将 CPython 源代码树大规模转换为使用 Clinic 之前做出关于此事的决定。
• Guido 建议将“函数文档字符串”手动内联编写，位于输出的中间，如下所示

  /*[clinic]
    ... prototype and parameters (including parameter docstrings) go here
  [clinic]*/
  ... some output ...
  /*[clinic docstring start]*/
  ... hand-edited function docstring goes here   <-- you edit this by hand!
  /*[clinic docstring end]*/
  ... more output
  /*[clinic output end]*/
  

  我尝试过这种方法，但不喜欢——我认为它很笨拙。我更希望你编写的所有内容都放在一个地方，而不是在 DSL 输出的中间有一个手动编辑的内容岛。

• Argument Clinic 不支持自动元组解包（PyArg_ParseTuple() 的“(OOO)”样式格式字符串）。
• Argument Clinic 去除了一些动态性/灵活性。使用 PyArg_ParseTuple()，理论上可以在运行时为“es”/“et”格式单元传递不同的编码。据我所知，CPython 本身并没有这样做，但外部用户可能会这样做。（琐事：regrtest 没有使用“es”，并且所有使用的“et”都在 socketmodule.c 中，除了 _ssl.c 中的一个。它们都是静态的，指定编码 "idna"。）

致谢

PEP 作者感谢 Ned Batchelder 允许他厚颜无耻地抄袭他为 Cog 设计的巧妙设计——“我从未用过的我最喜欢的工具”。还要感谢所有在 [bugtracker 问题] 和 python-dev 上提供反馈的人。特别感谢 Alyssa (Nick) Coghlan 和 Guido van Rossum 在 PyCon US 2013 上就该主题进行了为时两小时的现场深入探讨。

参考文献

版权

本文档已置于公有领域。