解析参数和构建值

这些函数在创建自己的扩展Function和方法时很有用。 扩展和嵌入 Python 解释器中提供了其他信息和示例。

所描述的这些函数的前三个PyArg_ParseTuple()，PyArg_ParseTupleAndKeywords()和PyArg_Parse()都使用* format 字符串*，用于将预期参数告知Function。格式字符串对每个函数使用相同的语法。

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

这些格式允许将对象作为连续的内存块进行访问。您不必为返回的 unicode 或字节区域提供原始存储。此外，除了es，es#，et和et#格式外，您无需释放任何内存。

从 Python 2.5 开始，可以pass在包含Python.h之前定义宏PY_SSIZE_T_CLEAN来控制 length 参数的类型。如果定义了宏，则长度为Py_ssize_t而不是整数。

2.6 版的新Function。

2.6 版的新Function。

此格式需要两个参数。第一个仅用作 Importing，并且必须是const char*，它指向以 NUL 终止的字符串的编码名称，或者* NULL *，在这种情况下，将使用默认编码。如果 Python 未知命名的编码，则会引发异常。第二个参数必须为char**；它所引用的指针的值将被设置为带有参数文本内容的缓冲区。文本将按照第一个参数指定的编码进行编码。

PyArg_ParseTuple()将分配所需大小的缓冲区，将编码后的数据复制到此缓冲区中，并调整“缓冲区”以引用新分配的存储。调用方负责使用后调用PyMem_Free()以释放分配的缓冲区。

它需要三个参数。第一个仅用作 Importing，并且必须是const char*，它指向以 NUL 终止的字符串的编码名称，或者* NULL *，在这种情况下，将使用默认编码。如果 Python 未知命名的编码，则会引发异常。第二个参数必须为char**；它所引用的指针的值将被设置为带有参数文本内容的缓冲区。文本将按照第一个参数指定的编码进行编码。第三个参数必须是指向整数的指针；引用的整数将设置为输出缓冲区中的字节数。

有两种操作模式：

如果 *buffer 指向 NULL 指针，则该函数将分配所需大小的缓冲区，将编码后的数据复制到该缓冲区中，并设置 buffer *来引用新分配的存储。调用方负责在使用后调用PyMem_Free()以释放分配的缓冲区。

如果 *buffer 指向非 NULL 指针(已分配的缓冲区)，则PyArg_ParseTuple()将使用此位置作为缓冲区，并将 buffer_length *的初始值解释为缓冲区大小。然后它将编码后的数据复制到缓冲区中并对其进行 NUL 终止。如果缓冲区不够大，将设置TypeError。注意：从 Python 3.6 开始，将设置ValueError。

在这两种情况下，** buffer_length *都设置为没有尾随 NUL 字节的编码数据的长度。

2.3 版的新Function。

2.3 版的新Function。

2.3 版的新Function。

2.3 版的新Function。

2.3 版的新Function。

2.5 版的新Function。

status = converter(object, address);

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

2.6 版的新Function。

Note

在 Python 1.5.2 版之前，此格式说明符仅接受包含单个参数的 Tuples，而不接受任意序列。以前导致TypeError在此处引发的代码现在可以毫无 exception 地 continue 执行。对于现有代码而言，这不会成为问题。

可以在需要整数的地方传递 Python 长整数。但是，不会进行适当的范围检查-当接收字段太小而无法接收该值时，最高有效位会被静默截断(实际上，语义是从 C 语言的向下转换继承的，您的里程可能会有所不同)。

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

请注意，提供给调用方的任何 Python 对象引用都是“借用”引用；不要减少其参考计数！

传递给这些函数的其他参数必须是类型由格式字符串确定的变量的地址；这些用于存储来自 ImportingTuples 的值。如上述格式单位列表中所述，在某些情况下，这些参数将用作 Importing 值。在这种情况下，它们应与为相应格式单位指定的内容匹配。

为了使转换成功，* arg *对象必须与格式匹配，并且格式必须用尽。成功时，PyArg_Parse*()函数返回 true，否则返回 false 并引发适当的异常。当PyArg_Parse*()函数由于其中一种格式单位的转换失败而失败时，与该格式单位和以下格式单位对应的地址处的变量将保持不变。

这是使用此Function的一个示例，该示例取自_weakref helper 模块的来源，以获取弱引用：

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)

2.2 版中的新Function。

在版本 2.5 中更改：此函数对 *min 和 max *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

根据类似于PyArg_Parse*()系列函数接受的格式字符串和值序列创建一个新值。如果有错误，则返回值或* NULL ；如果返回 NULL *，将引发异常。

Py_BuildValue()并不总是构建一个 Tuples。仅当其格式字符串包含两个或多个格式单位时，才会构建 Tuples。如果格式字符串为空，则返回None;如果它仅包含一个格式单元，则返回该格式单元描述的任何对象。要强制其返回大小为0或一个的 Tuples，请在格式字符串后加上括号。

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

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

在格式字符串中会忽略字符空格，制表符，冒号和逗号(但不能在格式单位(例如s#)内)。这可用于使长格式字符串更具可读性。

2.5 版的新Function。

如果格式字符串中有错误，则设置SystemErrorexception，并返回* NULL *。

首页