解析参数并构建值变量
********************

在创建你自己的扩展函数和方法时，这些函数是有用的。其它的信息和样例见
扩展和嵌入 Python 解释器 。

这些函数描述的前三个，"PyArg_ParseTuple()"，
"PyArg_ParseTupleAndKeywords()"，以及 "PyArg_Parse()"，它们都使用 *格
式化字符串* 来将函数期待的参数告知函数。这些函数都使用相同语法规则的格
式化字符串。


解析参数
========

一个格式化字符串包含0或者更多的格式单元。一个格式单元用来描述一个
Python对象；它通常是一个字符或者由括号括起来的格式单元序列。除了少数例
外，一个非括号序列的格式单元通常对应这些函数的具有单一地址的参数。在接
下来的描述中，双引号内的表达式是格式单元；圆括号()内的是对应这个格式单
元的Python对象类型；方括号[]内的是传递的C变量(变量集)类型。


字符串和缓存区
--------------

这些格式允许将对象按照连续的内存块形式进行访问。你没必要提供返回的
unicode字符或者字节区的原始数据存储。

一般的，当一个表达式设置一个指针指向一个缓冲区，这个缓冲区可以被相应的
Python对象管理，并且这个缓冲区共享这个对象的生存周期。你不需要人为的释
放任何内存空间。除了这些 "es", "es#", "et" and "et#".

然而，当一个 "Py_buffer" 结构被赋值，其包含的缓冲区被锁住，所以调用者
在随后使用这个缓冲区，即使在 "Py_BEGIN_ALLOW_THREADS" 块中，可以避免可
变数据因为调整大小或者被销毁所带来的风险。因此，**你不得不调用**
"PyBuffer_Release()" 在你结束数据的处理时(或者在之前任何中断事件中)

除非另有说明，缓冲区是不会以空终止的。

Some formats require a read-only *bytes-like object*, and set a
pointer instead of a buffer structure.  They work by checking that the
object's "PyBufferProcs.bf_releasebuffer" field is *NULL*, which
disallows mutable objects such as "bytearray".

備註: 所有 "#" 表达式的变式("s#"，"y#"，等等)，长度参数的类型(整型或
  者 "Py_ssize_t")在包含 "Python.h" 头文件之前由 "PY_SSIZE_T_CLEAN" 宏
  的 定义控制。如果这个宏被定义，长度是一个 "Py_ssize_t" Python元大小
  类型 而不是一个 "int" 整型。在未来的Python版本中将会改变，只支持
  "Py_ssize_t" 而放弃支持 "int" 整型。最好一直定义 "PY_SSIZE_T_CLEAN"
  这个宏。

"s" ("str") [const char *]
   将一个Unicode对象转换成一个指向字符串的C指针。一个指针指向一个已经
   存在的字符串，这个字符串存储的是传如的字符指针变量。C字符串是已空结
   束的。Python字符串不能包含嵌入的无效的代码点；如果由，一个
   "ValueError" 异常会被引发。Unicode对象被转化成 "'utf-8'" 编码的C字
   符串。如果转换失败，一个 "UnicodeError" 异常被引发。

   備註: 这个表达式不接受 *bytes-like objects*。如果你想接受文件系统
     路径并 将它们转化成C字符串，建议使用 "O&" 表达式配合
     "PyUnicode_FSConverter()" 作为 *转化函数*。

   3.5 版更變: 以前，当Python字符串中遇到了嵌入的null代码点会引发
   "TypeError" 。

"s*" ("str" or *bytes-like object*) [Py_buffer]
   这个表达式既接受Unicode对象也接受类字节类型对象。它为由调用者提供的
   "Py_buffer" 结构赋值。这里结果的C字符串可能包含嵌入的NUL字节。
   Unicode对象通过 "'utf-8'" 编码转化成C字符串。

"s#" ("str", 只读 *bytes-like object*) [const char *, int or
"Py_ssize_t"]
   像 "s*"，除了它不接受易变的对象。结果存储在两个C 变量中，第一个是指
   向C字符串的指针，第二个是它的长度。字符串可能包含嵌入的null字节。
   Unicode对象都被通过 "'utf-8'" 编码转化成C字符串。

"z" ("str" or "None") [const char *]
   Like "s", but the Python object may also be "None", in which case
   the C pointer is set to *NULL*.

"z*" ("str", *bytes-like object* or "None") [Py_buffer]
   Like "s*", but the Python object may also be "None", in which case
   the "buf" member of the "Py_buffer" structure is set to *NULL*.

"z#" ("str", 只读 *bytes-like object* or "None") [const char *, int]
   Like "s#", but the Python object may also be "None", in which case
   the C pointer is set to *NULL*.

"y" (read-only *bytes-like object*) [const char *]
   这个表达式将一个类字节类型对象转化成一个指向字符串的C指针；它不接受
   Unicode对象。字节缓存区必须不包含嵌入的null字节；如果包含了null字节
   ，会引发一个 "ValueError" 异常。

   3.5 版更變: 以前，当字节缓冲区中遇到了嵌入的null字节会引发
   "TypeError" 。

"y*" (*bytes-like object*) [Py_buffer]
   "s*" 的变式，不接受Unicode对象，只接受类字节类型变量。**这是接受二
   进制数据的推荐方法**。

"y#" (read-only *bytes-like object*) [const char *, int]
   This variant on "s#" doesn't accept Unicode objects, only bytes-
   like objects.

"S" ("bytes") [PyBytesObject *]
   要求Python对象是一个 "bytes" 类型对象，没有尝试任何的转换。如果不是
   一个字节类型对象会引发 "TypeError" 异常。C变量也可能声明为
   "PyObject*" 类型。

"Y" ("bytearray") [PyByteArrayObject *]
   要求Python对象是一个 "bytearray" 类型对象，没有尝试任何的转换。如果
   不是一个 "bytearray" 类型对象会引发 "TypeError" 异常。C变量也可能声
   明为 "PyObject*" 类型。

"u" ("str") [Py_UNICODE *]
   将一个Python Unicode对象转化成指向一个以空终止的Unicode字符缓冲区的
   指针。你必须传入一个 "Py_UNICODE" 指针变量的地址，存储了一个指向已
   经存在的Unicode缓冲区的指针。请注意一个 "Py_UNICODE" 类型的字符宽度
   取决于编译选项(16位或者32位)。Python字符串必须不能包含嵌入的null代
   码点；如果有，引发一个 "ValueError" 异常。

   3.5 版更變: 以前，当Python字符串中遇到了嵌入的null代码点会引发
   "TypeError" 。

   Deprecated since version 3.3, will be removed in version 4.0: 这是
   旧版样式 "Py_UNICODE" API; 请迁移至 "PyUnicode_AsWideCharString()".

"u#" ("str") [Py_UNICODE *, int]
   "u" 的变式，存储两个C变量，第一个指针指向一个Unicode数据缓存区，第
   二个是它的长度。它允许null代码点。

   Deprecated since version 3.3, will be removed in version 4.0: 这是
   旧版样式 "Py_UNICODE" API; 请迁移至 "PyUnicode_AsWideCharString()".

"Z" ("str" or "None") [Py_UNICODE *]
   Like "u", but the Python object may also be "None", in which case
   the "Py_UNICODE" pointer is set to *NULL*.

   Deprecated since version 3.3, will be removed in version 4.0: 这是
   旧版样式 "Py_UNICODE" API; 请迁移至 "PyUnicode_AsWideCharString()".

"Z#" ("str" or "None") [Py_UNICODE *, int]
   Like "u#", but the Python object may also be "None", in which case
   the "Py_UNICODE" pointer is set to *NULL*.

   Deprecated since version 3.3, will be removed in version 4.0: 这是
   旧版样式 "Py_UNICODE" API; 请迁移至 "PyUnicode_AsWideCharString()".

"U" ("str") [PyObject *]
   要求Python对象是一个Unicode对象，没有尝试任何的转换。如果不是一个
   Unicode对象会引发 "TypeError" 异常。C变量也可能声明为 "PyObject*"
   类型。

"w*" (可读写 *bytes-like object*) [Py_buffer]
   这个表达式接受任何实现可读写缓存区接口的对象。它为调用者提供的
   "Py_buffer" 结构赋值。缓冲区可能存在嵌入的null字节。当缓冲区使用完
   后调用者需要调用 "PyBuffer_Release()"。

"es" ("str") [const char *encoding, char **buffer]
   "s" 的变式，它将编码后的Unicode字符存入字符缓冲区。它只处理没有嵌入
   NUL字节的已编码数据

   This format requires two arguments.  The first is only used as
   input, and must be a "const char*" which points to the name of an
   encoding as a NUL-terminated string, or *NULL*, in which case
   "'utf-8'" encoding is used. An exception is raised if the named
   encoding is not known to Python.  The second argument must be a
   "char**"; the value of the pointer it references will be set to a
   buffer with the contents of the argument text. The text will be
   encoded in the encoding specified by the first argument.

   "PyArg_ParseTuple()" 会分配一个足够大小的缓冲区，将编码后的数据拷贝
   进这个缓冲区并且设置 **buffer* 引用这个新分配的内存空间。调用者有责
   任在使用后调用 "PyMem_Free()" 去释放已经分配的缓冲区。

"et" ("str", "bytes" or "bytearray") [const char *encoding, char
**buffer]
   和 "es" 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参
   数是编码后的字符串类型。

"es#" ("str") [const char *encoding, char **buffer, int
*buffer_length]
   "s#" 的变式，它将已编码的Unicode字符存入字符缓冲区。不像 "es" 表达
   式，它允许传入的数据包含NUL字符。

   It requires three arguments.  The first is only used as input, and
   must be a "const char*" which points to the name of an encoding as
   a NUL-terminated string, or *NULL*, in which case "'utf-8'"
   encoding is used. An exception is raised if the named encoding is
   not known to Python.  The second argument must be a "char**"; the
   value of the pointer it references will be set to a buffer with the
   contents of the argument text. The text will be encoded in the
   encoding specified by the first argument. The third argument must
   be a pointer to an integer; the referenced integer will be set to
   the number of bytes in the output buffer.

   有两种操作方式：

   If **buffer* points a *NULL* pointer, the function will allocate a
   buffer of the needed size, copy the encoded data into this buffer
   and set **buffer* to reference the newly allocated storage.  The
   caller is responsible for calling "PyMem_Free()" to free the
   allocated buffer after usage.

   If **buffer* points to a non-*NULL* pointer (an already allocated
   buffer), "PyArg_ParseTuple()" will use this location as the buffer
   and interpret the initial value of **buffer_length* as the buffer
   size.  It will then copy the encoded data into the buffer and NUL-
   terminate it.  If the buffer is not large enough, a "ValueError"
   will be set.

   在这两个例子中，**buffer_length* 被设置为编码后结尾不为NUL的数据的
   长度。

"et#" ("str", "bytes" or "bytearray") [const char *encoding, char
**buffer, int *buffer_length]
   和 "es#" 相同，除了不用重编码传入的字符串对象。相反，它假设传入的参
   数是编码后的字符串类型。


數字
----

"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 int" 无符号长整型，并不
   检查溢出问题。

"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" Python元大小类型。

"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" Python复数类型。


其他对象
--------

"O" (object) [PyObject *]
   Store a Python object (without any conversion) in a C object
   pointer.  The C program thus receives the actual object that was
   passed.  The object's reference count is not increased.  The
   pointer stored is not *NULL*.

"O!" (object) [*typeobject*, PyObject *]
   将一个Python对象存入一个C指针。和 "O" 类似，但是需要两个C参数：第一
   个是Python类型对象的地址，第二个是存储对象指针的C变量( "PyObject*"
   变量)的地址。如果Python对象类型不对，会抛出 "TypeError" 异常。

"O&" (object) [*converter*, *anything*]
   通过一个 *converter* 函数将一个Python对象转换成一个C变量。这需要两
   个参数：第一个是一个函数，第二个是一个C变量的地址(任意类型的)，转化
   为 "void *" 类型。*converter* 函数像这样被调用：

      status = converter(object, address);

   *object*是待转化的Python对象并且 *address* 是传入 "PyArg_Parse*()"
   函数的 "void*" 类型参数。返回的 *status* 是1代表转换成功，0代表转换
   失败。当转换失败，*converter*函数会引发一个异常并且不会修改
   *address* 的内容。

   If the *converter* returns "Py_CLEANUP_SUPPORTED", it may get
   called a second time if the argument parsing eventually fails,
   giving the converter a chance to release any memory that it had
   already allocated. In this second call, the *object* parameter will
   be NULL; *address* will have the same value as in the original
   call.

   3.1 版更變: "Py_CLEANUP_SUPPORTED" 被添加。

"p" ("bool") [int]
   测试传入的值是否为真(一个布尔判断)并且将结果转化为相对应的C
   true/false整型值。如果表达式为真置``1``，假则置``0``。它接受任何合
   法的Python值。参见 逻辑值检测 获取更多关于Python如何测试值为真的信
   息。

   3.3 版新加入.

"(items)" ("tuple") [*matching-items*]
   对象必须是Python序列，它的长度是 *items* 中格式单元的数量。C参数必
   须对应 *items* 中每一个独立的格式单元。序列中的格式单元可能有嵌套。

传递 “长”整型(整型的值超过了平台的 "LONG_MAX" 限制)是可能的，然而没有
进行适当的范围检测——当接收字段太小而接收不到值时，最重要的位被静默地截
断(实际上，C语言会在语义继承的基础上强制类型转换——期望的值可能会发生变
化)。

格式化字符串中还有一些其他的字符具有特殊的涵义。这些可能并不嵌套在圆括
号中。它们是：

"|"
   表明在Python参数列表中剩下的参数都是可选的。C变量对应的可选参数需要
   初始化为默认值——当一个可选参数没有指定时， "PyArg_ParseTuple()"  不
   能访问相应的C变量(变量集)的内容。

"$"
   "PyArg_ParseTupleAndKeywords()" only：表明在Python参数列表中剩下的
   参数都是强制关键字参数。当前，所有强制关键字参数都必须也是可选参数
   ，所以格式化字符串中  "|" 必须一直在 "$" 前面。

   3.3 版新加入.

":"
   格式单元的列表结束标志；冒号后的字符串被用来作为错误消息中的函数名
   ("PyArg_ParseTuple()" 函数引发的“关联值”异常)。

";"
   格式单元的列表结束标志；分号后的字符串被用来作为错误消息取代默认的
   错误消息。 ":" 和 ";" 相互排斥。

注意任何由调用者提供的Python对象引用是 *借来的* 引用；不要递减它们的引
用计数！

传递给这些函数的附加参数必须是由格式化字符串确定的变量的地址；这些都是
用来存储输入元组的值。有一些情况，如上面的格式单元列表中所描述的，这些
参数作为输入值使用；在这种情况下，它们应该匹配指定的相应的格式单元。

为了转换成功，*arg* 对象必须匹配格式并且格式必须用尽。成功的话，
"PyArg_Parse*()" 函数返回true，反之它们返回false并且引发一个合适的异常
。当 "PyArg_Parse*()" 函数因为某一个格式单元转化失败而失败时，对应的以
及后续的格式单元地址内的变量都不会被使用。


API 函数
--------

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

   解析一个函数的参数，表达式中的参数按参数位置顺序存入局部变量中。成
   功返回true；失败返回false并且引发相应的异常。

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

   和 "PyArg_ParseTuple()" 相同，然而它接受一个va_list类型的参数而不是
   可变数量的参数集。

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

   Parse the parameters of a function that takes both positional and
   keyword parameters into local variables.  The *keywords* argument
   is a *NULL*-terminated array of keyword parameter names.  Empty
   names denote positional-only parameters. Returns true on success;
   on failure, it returns false and raises the appropriate exception.

   3.6 版更變: 添加了 positional-only parameters 的支持。

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

   和 "PyArg_ParseTupleAndKeywords()" 相同，然而它接受一个va_list类型
   的参数而不是可变数量的参数集。

int PyArg_ValidateKeywordArguments(PyObject *)

   确保字典中的关键字参数都是字符串。这个函数只被使用于
   "PyArg_ParseTupleAndKeywords()" 不被使用的情况下，后者已经不再做这
   样的检查。

   3.2 版新加入.

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

   函数被用来析构“旧类型”函数的参数列表——这些函数使用的 "METH_OLDARGS"
   参数解析方法已从Python 3中移除。这不被推荐用于新代码的参数解析，并
   且在标准解释器中的大多数代码已被修改，已不再用于该目的。它仍然方便
   于分解其他元组，然而可能因为这个目的被继续使用。

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

   一个不使用格式化字符串指定参数类型的简单形式的参数检索。使用这种方
   法来检索参数的函数应该在函数或者方法表中声明 "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)


创建变量
========

PyObject* Py_BuildValue(const char *format, ...)
    *Return value: New reference.*

   Create a new value based on a format string similar to those
   accepted by the "PyArg_Parse*()" family of functions and a sequence
   of values.  Returns the value or *NULL* in the case of an error; an
   exception will be raised if *NULL* is returned.

   "Py_BuildValue()" 并不一直创建一个元组。只有当它的格式化字符串包含
   两个或更多的格式单元才会创建一个元组。如果格式化字符串是空，它返回
   "None"；如果它包含一个格式单元，它返回由格式单元描述的的任一对象。
   用圆括号包裹格式化字符串可以强制它返回一个大小为0或者1的元组

   当内存缓存区的数据以参数形式传递用来构建对象时，如 "s" 和 "s#" 格式
   单元，会拷贝需要的数据。调用者提供的缓冲区从来都不会被由
   "Py_BuildValue()" 创建的对象来引用。换句话说，如果你的代码调用
   "malloc()" 并且将分配的内存空间传递给 "Py_BuildValue()"，你的代码就
   有责任在 "Py_BuildValue()" 返回时调用 "free()" 。

   在下面的描述中，双引号的表达式使格式单元；圆括号()内的是格式单元将
   要返回的Python对象类型；方括号[]内的是传递的C变量(变量集)的类型

   字符例如空格，制表符，冒号和逗号在格式化字符串中会被忽略(但是不包括
   格式单元，如 "s#")。这可以使很长的格式化字符串具有更好的可读性。

   "s" ("str" or "None") [char *]
      Convert a null-terminated C string to a Python "str" object
      using "'utf-8'" encoding. If the C string pointer is *NULL*,
      "None" is used.

   "s#" ("str" or "None") [char *, int]
      Convert a C string and its length to a Python "str" object using
      "'utf-8'" encoding. If the C string pointer is *NULL*, the
      length is ignored and "None" is returned.

   "y" ("bytes") [char *]
      This converts a C string to a Python "bytes" object.  If the C
      string pointer is *NULL*, "None" is returned.

   "y#" ("bytes") [char *, int]
      This converts a C string and its lengths to a Python object.  If
      the C string pointer is *NULL*, "None" is returned.

   "z" ("str" or "None") [char *]
      和``s``一样。

   "z#" ("str" or "None") [char *, int]
      和``s#``一样。

   "u" ("str") [wchar_t *]
      Convert a null-terminated "wchar_t" buffer of Unicode (UTF-16 or
      UCS-4) data to a Python Unicode object.  If the Unicode buffer
      pointer is *NULL*, "None" is returned.

   "u#" ("str") [wchar_t *, int]
      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length
      to a Python Unicode object.   If the Unicode buffer pointer is
      *NULL*, the length is ignored and "None" is returned.

   "U" ("str" or "None") [char *]
      和``s``一样。

   "U#" ("str" or "None") [char *, int]
      和``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 long" 无符号短整型转化成Python整型对象。

   "I" ("int") [unsigned int]
      将一个C "unsigned long" 无符号整型转化成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" ("bytes" 长度为1 ) [char]
      将一个C "int" 整型代表的字符转化为Python "bytes" 长度为1的字节对
      象。

   "C" ("str" 长度为1) [int]
      将一个C "int" 整型代表的字符转化为Python "str" 长度为1的字符串对
      象。

   "d" ("float") [double]
      将一个C "double" 双精度浮点数转化为Python浮点数类型数字。

   "f" ("float") [float]
      将一个C "float" 单精度浮点数转化为Python浮点数类型数字。

   "D" ("复数") [Py_complex *]
      将一个C "Py_complex" 类型的结构转化为Python复数类型。

   "O" (object) [PyObject *]
      Pass a Python object untouched (except for its reference count,
      which is incremented by one).  If the object passed in is a
      *NULL* pointer, it is assumed that this was caused because the
      call producing the argument found an error and set an exception.
      Therefore, "Py_BuildValue()" will return *NULL* but won't raise
      an exception.  If no exception has been raised yet,
      "SystemError" is set.

   "S" (object) [PyObject *]
      和``O``相同。

   "N" (object) [PyObject *]
      和``O``相同，然而它并不增加对象的引用计数。当通过调用参数列表中
      的对象构造器创建对象时很实用。

   "O&" (object) [*converter*, *anything*]
      Convert *anything* to a Python object through a *converter*
      function.  The function is called with *anything* (which should
      be compatible with "void *") as its argument and should return a
      "new" Python object, or *NULL* if an error occurred.

   "(items)" ("tuple") [*matching-items*]
      将一个C变量序列转换成Python元组并保持相同的元素数量

   "[items]" ("list") [*相关的元素*]
      将一个C变量序列转换成Python列表并保持相同的元素数量

   "{items}" ("dict") [*相关的元素*]
      将一个C变量序列转换成Python字典。每一对连续的C变量对作为一个元素
      插入字典中，分别作为关键字和值。

   If there is an error in the format string, the "SystemError"
   exception is set and *NULL* returned.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

   和 "Py_BuildValue()" 相同，然而它接受一个va_list类型的参数而不是可
   变数量的参数集。
