解析参数和构建值¶

这些函数在创建您自己的扩展函数和方法时非常有用。更多信息和示例可以在扩展和嵌入 Python 解释器中找到。

前三个描述的函数，PyArg_ParseTuple()、PyArg_ParseTupleAndKeywords()和PyArg_Parse()，都使用格式字符串来告知函数有关预期参数的信息。这些函数的格式字符串使用相同的语法。

解析参数¶

格式字符串由零个或多个“格式单元”组成。格式单元描述一个 Python 对象；它通常是一个字符或一个带括号的格式单元序列。除少数例外，非带括号序列的格式单元通常对应于这些函数的单个地址参数。在以下描述中，带引号的形式是格式单元；(圆)括号中的条目是与格式单元匹配的 Python 对象类型；[方]括号中的条目是应传递其地址的 C 变量的类型。

字符串和缓冲区¶

注意

在 Python 3.12 及更早版本中，必须在包含 Python.h 之前定义宏 PY_SSIZE_T_CLEAN，才能使用下面解释的所有格式的 # 变体（s#、y# 等）。这在 Python 3.13 及更高版本中不是必需的。

这些格式允许将对象作为连续的内存块访问。您无需为返回的 Unicode 或字节区域提供原始存储。

除非另有说明，否则缓冲区不是以 NUL 结尾的。

有三种方法可以将字符串和缓冲区转换为 C

诸如 y* 和 s* 之类的格式会填充 Py_buffer 结构。这会锁定底层缓冲区，以便调用者随后可以使用该缓冲区，即使在 Py_BEGIN_ALLOW_THREADS 块内，也不会有可变数据被调整大小或销毁的风险。因此，**您必须调用** PyBuffer_Release()，在您完成处理数据之后（或在任何提前中止的情况下）。
es、es#、et 和 et# 格式分配结果缓冲区。 **您必须调用** PyMem_Free()，在您完成处理数据之后（或在任何提前中止的情况下）。
其他格式接受 str 或只读的类字节对象，例如 bytes，并为其缓冲区提供一个 const char * 指针。在这种情况下，缓冲区是“借用”的：它由相应的 Python 对象管理，并共享此对象的生命周期。您无需自己释放任何内存。

为确保可以安全地借用底层缓冲区，对象的 PyBufferProcs.bf_releasebuffer 字段必须为 NULL。这不允许使用常见的可变对象，例如 bytearray，但也禁止使用某些只读对象，例如 bytes 的 memoryview。

除了此 bf_releasebuffer 要求之外，没有检查来验证输入对象是否是不可变的（例如，它是否会响应可写缓冲区的请求，或者另一个线程是否可以更改数据）。

s (str) [const char *]

将 Unicode 对象转换为指向字符字符串的 C 指针。指向现有字符串的指针存储在您传递其地址的字符指针变量中。 C 字符串以 NUL 结尾。Python 字符串不得包含嵌入的空代码点；如果包含，则会引发 ValueError 异常。Unicode 对象使用 'utf-8' 编码转换为 C 字符串。如果此转换失败，则会引发 UnicodeError。

注意

此格式不接受类字节对象。如果您想接受文件系统路径并将它们转换为 C 字符字符串，则最好使用带有 PyUnicode_FSConverter() 作为*转换器*的 O& 格式。

在 3.5 版本中更改：之前，当在 Python 字符串中遇到嵌入的空代码点时，会引发 TypeError。

s* (str 或类字节对象) [Py_buffer]

此格式接受 Unicode 对象以及类字节对象。它会填充调用者提供的 Py_buffer 结构。在这种情况下，生成的 C 字符串可能包含嵌入的 NUL 字节。 Unicode 对象使用 'utf-8' 编码转换为 C 字符串。

s# (str, 只读的类字节对象) [const char *, Py_ssize_t]

类似于 s*，但它提供一个借用的缓冲区。结果存储到两个 C 变量中，第一个是指向 C 字符串的指针，第二个是其长度。该字符串可能包含嵌入的空字节。Unicode 对象使用 'utf-8' 编码转换为 C 字符串。

z (str 或 None) [const char *]

类似于 s，但 Python 对象也可能是 None，在这种情况下，C 指针设置为 NULL。

z* (str、类字节对象或 None) [Py_buffer]

类似于 s*，但 Python 对象也可能是 None，在这种情况下，Py_buffer 结构的 buf 成员设置为 NULL。

z# (str、只读的类字节对象或 None) [const char *, Py_ssize_t]

类似于 s#，但 Python 对象也可以是 None，在这种情况下，C 指针会被设置为 NULL。

y (只读的类字节对象) [const char *]

此格式将类字节对象转换为 C 指针，指向一个借用的字符串；它不接受 Unicode 对象。字节缓冲区不能包含嵌入的空字节；如果包含，则会引发 ValueError 异常。

在 3.5 版本中更改: 之前，如果在字节缓冲区中遇到嵌入的空字节，会引发 TypeError。

y* (类字节对象) [Py_buffer]

此 s* 的变体不接受 Unicode 对象，只接受类字节对象。这是接受二进制数据的推荐方式。

y# (只读的类字节对象) [const char *, Py_ssize_t]

此 s# 的变体不接受 Unicode 对象，只接受类字节对象。

S (bytes) [PyBytesObject *]

要求 Python 对象是 bytes 对象，不尝试任何转换。如果对象不是 bytes 对象，则会引发 TypeError。C 变量也可以声明为 PyObject*。

Y (bytearray) [PyByteArrayObject *]

要求 Python 对象是 bytearray 对象，不尝试任何转换。如果对象不是 bytearray 对象，则会引发 TypeError。C 变量也可以声明为 PyObject*。

U (str) [PyObject *]

要求 Python 对象是 Unicode 对象，不尝试任何转换。如果对象不是 Unicode 对象，则会引发 TypeError。C 变量也可以声明为 PyObject*。

w* (可读写的类字节对象) [Py_buffer]

此格式接受任何实现可读写缓冲区接口的对象。它会填充调用者提供的 Py_buffer 结构。缓冲区可能包含嵌入的空字节。调用者在完成缓冲区操作后必须调用 PyBuffer_Release()。

es (str) [const char *encoding, char **buffer]

此 s 的变体用于将 Unicode 编码为字符缓冲区。它只适用于不包含嵌入 NUL 字节的编码数据。

此格式需要两个参数。第一个参数仅用作输入，必须是一个指向以 NUL 结尾的编码名称字符串的 const char*，或者为 NULL，在这种情况下会使用 'utf-8' 编码。如果 Python 不知道指定的编码，则会引发异常。第二个参数必须是 char**；它引用的指针的值将被设置为包含参数文本内容的缓冲区。文本将使用第一个参数指定的编码进行编码。

PyArg_ParseTuple() 将分配所需大小的缓冲区，将编码数据复制到此缓冲区，并调整 *buffer 以引用新分配的存储空间。调用者有责任在使用后调用 PyMem_Free() 来释放已分配的缓冲区。

et (str, bytes 或 bytearray) [const char *encoding, char **buffer]

与 es 相同，不同之处在于字节字符串对象会直接传递，不进行重新编码。相反，实现会假定字节字符串对象使用作为参数传入的编码。

es# (str) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

此 s# 的变体用于将 Unicode 编码为字符缓冲区。与 es 格式不同，此变体允许输入包含 NUL 字符的数据。

它需要三个参数。第一个参数仅用作输入，必须是一个指向以 NUL 结尾的编码名称字符串的 const char*，或者为 NULL，在这种情况下会使用 'utf-8' 编码。如果 Python 不知道指定的编码，则会引发异常。第二个参数必须是 char**；它引用的指针的值将被设置为包含参数文本内容的缓冲区。文本将使用第一个参数指定的编码进行编码。第三个参数必须是指向整数的指针；引用的整数将被设置为输出缓冲区中的字节数。

有两种操作模式

如果 *buffer 指向一个 NULL 指针，函数将分配所需大小的缓冲区，将编码数据复制到此缓冲区，并将 *buffer 设置为引用新分配的存储空间。调用者有责任在使用后调用 PyMem_Free() 来释放已分配的缓冲区。

如果 *buffer 指向一个非 NULL 指针（已分配的缓冲区），PyArg_ParseTuple() 将使用此位置作为缓冲区，并将 *buffer_length 的初始值解释为缓冲区大小。然后，它会将编码数据复制到缓冲区并以 NUL 结尾。如果缓冲区不够大，则会设置 ValueError。

在这两种情况下，*buffer_length 都会被设置为编码数据的长度，不包括结尾的 NUL 字节。

et# (str, bytes 或 bytearray) [const char *encoding, char **buffer, Py_ssize_t *buffer_length]

与 es# 相同，不同之处在于字节字符串对象会直接传递，不进行重新编码。相反，实现会假定字节字符串对象使用作为参数传入的编码。

在 3.12 版本中更改: 删除了 u、 u#、 Z 和 Z#，因为它们使用了旧式的 Py_UNICODE* 表示形式。

数字¶

b (int) [unsigned char]: 将一个非负 Python 整数转换为一个无符号的小整数，存储在 C unsigned char 中。
B (int) [unsigned char]: 将一个 Python 整数转换为一个小整数，不进行溢出检查，存储在 C unsigned char 中。
h (int) [short int]: 将 Python 整数转换为 C short int。
H (int) [unsigned short int]: 将 Python 整数转换为 C unsigned short int，不进行溢出检查。
i (int) [int]: 将 Python 整数转换为普通的 C int。
I (int) [unsigned int]: 将 Python 整数转换为 C unsigned int，不进行溢出检查。
l (int) [long int]: 将 Python 整数转换为 C long int。
k (int) [unsigned long]: 将 Python 整数转换为 C unsigned long，不进行溢出检查。
L (int) [long long]: 将 Python 整数转换为 C long long。
K (int) [unsigned long long]: 将 Python 整数转换为 C unsigned long long，不进行溢出检查。
n (int) [Py_ssize_t]: 将 Python 整数转换为 C Py_ssize_t。
c (bytes 或 bytearray，长度为 1) [char]: 将一个 Python 字节（表示为长度为 1 的 bytes 或 bytearray 对象）转换为 C char。

3.3 版本更改: 允许使用 bytearray 对象。
C (str，长度为 1) [int]: 将一个 Python 字符（表示为长度为 1 的 str 对象）转换为 C int。
f (float) [float]: 将 Python 浮点数转换为 C float。
d (float) [double]: 将 Python 浮点数转换为 C double。
D (complex) [Py_complex]: 将 Python 复数转换为 C Py_complex 结构体。

其他对象¶

O (对象) [PyObject *]: 将 Python 对象（不进行任何转换）存储在 C 对象指针中。因此，C 程序接收到传递的实际对象。不会创建对该对象新的强引用（即其引用计数不会增加）。存储的指针不为 NULL。
O! (对象) [typeobject, PyObject *]: 将 Python 对象存储在 C 对象指针中。这与 O 类似，但需要两个 C 参数：第一个是 Python 类型对象的地址，第二个是存储对象指针的 C 变量（类型为 PyObject*）的地址。如果 Python 对象不具有所需的类型，则会引发 TypeError。

O& (对象) [converter, anything]

通过 converter 函数将 Python 对象转换为 C 变量。这需要两个参数：第一个是函数，第二个是 C 变量（任意类型）的地址，转换为 void*。converter 函数依次调用如下

status = converter(object, address);

其中 object 是要转换的 Python 对象，address 是传递给 PyArg_Parse* 函数的 void* 参数。返回的 status 对于成功转换应为 1，如果转换失败则为 0。当转换失败时，converter 函数应引发异常，并保持 address 的内容不变。

如果 converter 返回 Py_CLEANUP_SUPPORTED，则如果参数解析最终失败，它可能会被第二次调用，从而使转换器有机会释放它已经分配的任何内存。在第二次调用中，object 参数将为 NULL；address 将具有与原始调用相同的值。

3.1 版本更改: 添加了 Py_CLEANUP_SUPPORTED。

p (bool) [int]

测试传入值的真值（布尔 **p**redicate），并将结果转换为等效的 C 真/假整数值。如果表达式为真，则将 int 设置为 1，如果为假，则设置为 0。这接受任何有效的 Python 值。有关 Python 如何测试值的真值，请参阅真值测试。

3.3 版本新增。

(items) (tuple) [matching-items]

该对象必须是 Python 序列，其长度是 items 中格式单元的数量。C 参数必须与 items 中的各个格式单元相对应。序列的格式单元可以是嵌套的。

可以传递 “long” 整数（其值超过平台 LONG_MAX 的整数），但是不进行适当的范围检查——当接收字段太小而无法接收该值时，最高有效位会被静默截断（实际上，语义是从 C 中的向下转换继承的——你的结果可能会有所不同）。

在格式字符串中，其他几个字符具有含义。这些字符可能不会出现在嵌套的括号内。它们是：

|: 指示 Python 参数列表中剩余的参数是可选的。与可选参数对应的 C 变量应初始化为它们的默认值——当未指定可选参数时，PyArg_ParseTuple() 不会触及相应的 C 变量的内容。
$: PyArg_ParseTupleAndKeywords() 专用：指示 Python 参数列表中剩余的参数是仅关键字的。目前，所有仅关键字的参数也必须是可选参数，因此在格式字符串中，$ 之前必须始终指定 |。

3.3 版本新增。
:: 格式单元列表在此处结束；冒号后的字符串用作错误消息中的函数名称（PyArg_ParseTuple() 引发的异常的 “关联值”）。
;: 格式单元列表在此处结束；分号后的字符串用作错误消息，*代替*默认错误消息。: 和 ; 相互排斥。

请注意，提供给调用者的任何 Python 对象引用都是*借用*的引用；请不要释放它们（即，不要减少它们的引用计数）！

传递给这些函数的附加参数必须是变量的地址，这些变量的类型由格式字符串确定；它们用于存储来自输入元组的值。在上面格式单元列表中描述的少数情况下，这些参数用作输入值；在这种情况下，它们应与相应格式单元指定的内容匹配。

为了成功转换，arg 对象必须与格式匹配，并且格式必须耗尽。成功时，PyArg_Parse* 函数返回 true，否则返回 false 并引发适当的异常。当 PyArg_Parse* 函数由于某个格式单元的转换失败而失败时，与该格式单元及其后续格式单元对应的地址处的变量将保持不变。

API 函数¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: 属于稳定 ABI 的一部分。
将仅接受位置参数的函数的参数解析为局部变量。成功时返回 true；失败时，返回 false 并引发适当的异常。

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: 属于稳定 ABI 的一部分。
与 PyArg_ParseTuple() 相同，但它接受 va_list 而不是可变数量的参数。

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: 属于稳定 ABI 的一部分。
将接受位置参数和关键字参数的函数的参数解析为局部变量。keywords 参数是一个以 NULL 结尾的关键字参数名称数组，指定为以 null 结尾的 ASCII 或 UTF-8 编码的 C 字符串。空名称表示仅限位置参数。成功时返回 true；失败时，返回 false 并引发适当的异常。

注意

keywords 参数声明在 C 中为 char *const*，在 C++ 中为 const char *const*。这可以使用 PY_CXX_CONST 宏覆盖。

在 3.6 版本中更改: 添加了对仅限位置参数的支持。

在 3.13 版本中更改: keywords 参数现在在 C 中的类型为 char *const*，在 C++ 中的类型为 const char *const*，而不是 char**。添加了对非 ASCII 关键字参数名称的支持。

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: 属于稳定 ABI 的一部分。
与 PyArg_ParseTupleAndKeywords() 相同，但它接受 va_list 而不是可变数量的参数。

int PyArg_ValidateKeywordArguments(PyObject*)¶: 属于稳定 ABI 的一部分。
确保关键字参数字典中的键是字符串。只有在不使用 PyArg_ParseTupleAndKeywords() 时才需要这样做，因为后者已经执行此检查。

在 3.2 版本中添加。

int PyArg_Parse(PyObject *args, const char *format, ...)¶

属于稳定 ABI 的一部分。

将接受单个位置参数的函数的参数解析为局部变量。成功时返回 true；失败时，返回 false 并引发适当的异常。

示例

// Function using METH_O calling convention
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... use value ...
}

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)¶

属于稳定 ABI 的一部分。

一种更简单的参数检索形式，它不使用格式字符串来指定参数的类型。使用此方法检索其参数的函数应在函数或方法表中声明为 METH_VARARGS。包含实际参数的元组应作为 args 传递；它实际上必须是一个元组。元组的长度必须至少为 min，且不超过 max；min 和 max 可以相等。必须将附加参数传递给函数，其中每个参数都应是指向 PyObject* 变量的指针；这些变量将用来自 args 的值填充；它们将包含借用引用。与 args 未给出的可选参数对应的变量将不会被填充；这些变量应由调用者初始化。此函数在成功时返回 true，如果 args 不是元组或包含错误数量的元素，则返回 false；如果出现故障，则会设置异常。

这是使用此函数的示例，取自弱引用的 _weakref 帮助模块的源代码

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

在此示例中调用 PyArg_UnpackTuple() 完全等效于此调用 PyArg_ParseTuple()

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

PY_CXX_CONST¶: 在 PyArg_ParseTupleAndKeywords() 和 PyArg_VaParseTupleAndKeywords() 的 keywords 参数声明中，在 char *const* 前要插入的值（如果有）。C 语言默认为空，C++ 语言默认为 const (const char *const*)。要覆盖此默认值，请在包含 Python.h 之前将其定义为所需的值。

3.13 版本中新增。

构建值¶

PyObject *Py_BuildValue(const char *format, ...)¶

返回值：新引用。属于稳定 ABI 的一部分。

基于类似于 PyArg_Parse* 系列函数所接受的格式字符串和一系列值创建一个新值。如果发生错误，则返回该值或 NULL；如果返回 NULL，则会引发异常。

Py_BuildValue() 并非总是构建一个元组。仅当其格式字符串包含两个或更多格式单元时，它才会构建一个元组。如果格式字符串为空，则返回 None；如果它恰好包含一个格式单元，则返回该格式单元所描述的任何对象。要强制它返回大小为 0 或 1 的元组，请将格式字符串用括号括起来。

当内存缓冲区作为参数传递以提供构建对象的数据时（例如对于 s 和 s# 格式），会复制所需的数据。调用者提供的缓冲区永远不会被 Py_BuildValue() 创建的对象引用。换句话说，如果您的代码调用 malloc() 并将分配的内存传递给 Py_BuildValue()，则您的代码负责在 Py_BuildValue() 返回后为该内存调用 free()。

在以下描述中，带引号的形式是格式单元；圆括号中的条目是格式单元将返回的 Python 对象类型；方括号中的条目是要传递的 C 值类型。

空格、制表符、冒号和逗号在格式字符串中会被忽略（但在 s# 等格式单元内则不会）。这可以用来使长格式字符串更具可读性。

s ( str 或 None) [const char *]: 使用 'utf-8' 编码将以 null 结尾的 C 字符串转换为 Python str 对象。如果 C 字符串指针为 NULL，则使用 None。
s# ( str 或 None) [const char *, Py_ssize_t]: 使用 'utf-8' 编码将 C 字符串及其长度转换为 Python str 对象。如果 C 字符串指针为 NULL，则忽略长度并返回 None。
y ( bytes) [const char *]: 这将 C 字符串转换为 Python bytes 对象。如果 C 字符串指针为 NULL，则返回 None。
y# ( bytes) [const char *, Py_ssize_t]: 这将 C 字符串及其长度转换为 Python 对象。如果 C 字符串指针为 NULL，则返回 None。
z (str 或 None) [const char *]: 与 s 相同。
z# ( str 或 None) [const char *, Py_ssize_t]: 与 s# 相同。
u ( str) [const wchar_t *]: 将以 null 结尾的 Unicode（UTF-16 或 UCS-4）数据的 wchar_t 缓冲区转换为 Python Unicode 对象。如果 Unicode 缓冲区指针为 NULL，则返回 None。
u# ( str) [const wchar_t *, Py_ssize_t]: 将 Unicode（UTF-16 或 UCS-4）数据缓冲区及其长度转换为 Python Unicode 对象。如果 Unicode 缓冲区指针为 NULL，则忽略长度并返回 None。
U ( str 或 None) [const char *]: 与 s 相同。
U# ( str 或 None) [const char *, Py_ssize_t]: 与 s# 相同。
i (int) [int]: 将普通 C int 转换为 Python 整数对象。
b ( int) [char]: 将普通 C char 转换为 Python 整数对象。
h (int) [short int]: 将普通 C short int 转换为 Python 整数对象。
l (int) [long int]: 将 C long int 转换为 Python 整数对象。
B (int) [unsigned char]: 将 C unsigned char 转换为 Python 整数对象。
H (int) [unsigned short int]: 将 C unsigned short int 转换为 Python 整数对象。
I (int) [unsigned int]: 将 C unsigned int 转换为 Python 整数对象。
k (int) [unsigned long]: 将 C unsigned long 转换为 Python 整数对象。
L (int) [long long]: 将 C long long 转换为 Python 整数对象。
K (int) [unsigned long long]: 将 C unsigned long long 转换为 Python 整数对象。
n (int) [Py_ssize_t]: 将 C Py_ssize_t 转换为 Python 整数。
c (长度为 1 的 bytes) [char]: 将表示字节的 C int 转换为长度为 1 的 Python bytes 对象。
C (str，长度为 1) [int]: 将表示字符的 C int 转换为长度为 1 的 Python str 对象。
d (float) [double]: 将 C double 转换为 Python 浮点数。
f (float) [float]: 将 C float 转换为 Python 浮点数。
D (complex) [Py_complex *]: 将 C Py_complex 结构体转换为 Python 复数。
O (对象) [PyObject *]: 传递一个 Python 对象，不做任何修改，但创建一个新的强引用（即其引用计数加一）。如果传入的对象是 NULL 指针，则假定这是因为产生该参数的调用发现了一个错误并设置了异常。因此，Py_BuildValue() 将返回 NULL 但不会引发异常。如果尚未引发任何异常，则会设置 SystemError。
S (对象) [PyObject *]: 与 O 相同。
N (对象) [PyObject *]: 与 O 相同，但它不创建新的强引用。当对象是由参数列表中的对象构造函数的调用创建时，此项很有用。
O& (对象) [converter, anything]: 通过 *转换器* 函数将 *任何内容* 转换为 Python 对象。该函数使用 *任何内容*（应与 void* 兼容）作为其参数进行调用，并应返回一个“新”Python 对象，如果发生错误，则返回 NULL。
(items) (tuple) [matching-items]: 将一系列 C 值转换为具有相同数量项的 Python 元组。
[items] (list) [匹配项]: 将一系列 C 值转换为具有相同数量项的 Python 列表。
{items} (dict) [匹配项]: 将一系列 C 值转换为 Python 字典。每对连续的 C 值都会向字典添加一项，分别作为键和值。

如果格式字符串中存在错误，则会设置 SystemError 异常并返回 NULL。

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: 返回值：新引用。属于稳定 ABI 的一部分。
与 Py_BuildValue() 相同，只不过它接受 va_list 而不是可变数量的参数。

解析参数和构建值¶

解析参数¶

字符串和缓冲区¶

数字¶

其他对象¶

API 函数¶

构建值¶

目录

上一主题

下一主题

本页