解析自变量和构建值 ¶

这些函数在创建自己的扩展函数和方法时很有用。额外信息和范例可用于扩展和嵌入 Python 解释器 .

描述这些函数中的前 3， PyArg_ParseTuple() , PyArg_ParseTupleAndKeywords() ，和 PyArg_Parse() ，全部使用 格式字符串 用于告诉函数有关期望自变量。格式字符串使用相同句法，对于这些函数中的每个而言。

剖析自变量 ¶

A format string consists of zero or more “format units.” A format unit describes one Python object; it is usually a single character or a parenthesized sequence of format units. With a few exceptions, a format unit that is not a parenthesized sequence normally corresponds to a single address argument to these functions. In the following description, the quoted form is the format unit; the entry in (round) parentheses is the Python object type that matches the format unit; and the entry in [square] brackets is the type of the C variable(s) whose address should be passed.

字符串和缓冲 ¶

注意

On Python 3.12 and older, the macro PY_SSIZE_T_CLEAN must be defined before including Python.h to use all # variants of formats ( s# , y# , etc.) explained below. This is not necessary on Python 3.13 and later.

These formats allow accessing an object as a contiguous chunk of memory. You don’t have to provide raw storage for the returned unicode or bytes area.

除非另有说明，缓冲不以 NULL 结尾。

There are three ways strings and buffers can be converted to C:

Formats such as y* and s* fill a Py_buffer structure. This locks the underlying buffer so that the caller can subsequently use the buffer even inside a Py_BEGIN_ALLOW_THREADS block without the risk of mutable data being resized or destroyed. As a result, you have to call PyBuffer_Release() after you have finished processing the data (or in any early abort case).
The es , es# , et and et# formats allocate the result buffer. You have to call PyMem_Free() after you have finished processing the data (or in any early abort case).
Other formats take a str or a read-only 像字节对象，譬如 bytes , and provide a const char * pointer to its buffer. In this case the buffer is “borrowed”: it is managed by the corresponding Python object, and shares the lifetime of this object. You won’t have to release any memory yourself.

To ensure that the underlying buffer may be safely borrowed, the object’s PyBufferProcs.bf_releasebuffer field must be NULL . This disallows common mutable objects such as bytearray , but also some read-only objects such as memoryview of bytes .

Besides this bf_releasebuffer requirement, there is no check to verify whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data).

s ( str ) [const char *]

Convert a Unicode object to a C pointer to a character string. A pointer to an existing string is stored in the character pointer variable whose address you pass. The C string is NUL-terminated. The Python string must not contain embedded null code points; if it does, a ValueError exception is raised. Unicode objects are converted to C strings using 'utf-8' encoding. If this conversion fails, a UnicodeError 被引发。

注意

这种格式不接受像字节对象 . If you want to accept filesystem paths and convert them to C character strings, it is preferable to use the O& format with PyUnicode_FSConverter() as converter .

3.5 版改变：先前， TypeError was raised when embedded null code points were encountered in the Python string.

s* ( str or 像字节对象 ) [Py_buffer]

This format accepts Unicode objects as well as bytes-like objects. It fills a Py_buffer structure provided by the caller. In this case the resulting C string may contain embedded NUL bytes. Unicode objects are converted to C strings using 'utf-8' 编码。

s# ( str , read-only 像字节对象 ) [const char *, Py_ssize_t ]

像 s* , except that it provides a borrowed buffer . The result is stored into two C variables, the first one a pointer to a C string, the second one its length. The string may contain embedded null bytes. Unicode objects are converted to C strings using 'utf-8' 编码。

z ( str or None ) [const char *]

像 s , but the Python object may also be None , in which case the C pointer is set to NULL .

z* ( str , 像字节对象 or None ) [Py_buffer]

像 s* , but the Python object may also be None , in which case the buf 成员对于 Py_buffer structure is set to NULL .

z# ( str , read-only 像字节对象 or None ) [const char *, Py_ssize_t ]

像 s# , but the Python object may also be None , in which case the C pointer is set to NULL .

y (read-only 像字节对象 ) [const char *]

This format converts a bytes-like object to a C pointer to a borrowed character string; it does not accept Unicode objects. The bytes buffer must not contain embedded null bytes; if it does, a ValueError 异常被引发。

3.5 版改变：先前， TypeError was raised when embedded null bytes were encountered in the bytes buffer.

y*

( 像字节对象 ) [Py_buffer]

This variant on s* doesn’t accept Unicode objects, only bytes-like objects. This is the recommended way to accept binary data.

y#

(read-only 像字节对象 ) [const char *,


Py_ssize_t

]

This variant on s# doesn’t accept Unicode objects, only bytes-like objects.

(


bytes

) [PyBytesObject *]

Requires that the Python object is a bytes object, without attempting any conversion. Raises TypeError if the object is not a bytes object. The C variable may also be declared as PyObject * .

(


bytearray

) [PyByteArrayObject *]

Requires that the Python object is a bytearray object, without attempting any conversion. Raises TypeError if the object is not a bytearray object. The C variable may also be declared as PyObject * .

(

str

) [PyObject *]

Requires that the Python object is a Unicode object, without attempting any conversion. Raises TypeError if the object is not a Unicode object. The C variable may also be declared as PyObject * .

w*

(read-write 像字节对象 ) [Py_buffer]

This format accepts any object which implements the read-write buffer interface. It fills a Py_buffer structure provided by the caller. The buffer may contain embedded null bytes. The caller have to call PyBuffer_Release() when it is done with the buffer.

es

(

str

) [const char *encoding, char **buffer]

This variant on s is used for encoding Unicode into a character buffer. It only works for encoded data without embedded NUL bytes.

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 ，在这种情况下 '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() will allocate a buffer of the needed size, copy the encoded data into this buffer and adjust *buffer to reference the newly allocated storage. The caller is responsible for calling PyMem_Free() to free the allocated buffer after use.

et

(

str


bytes


bytearray

) [const char *encoding, char **buffer]

如同 es except that byte string objects are passed through without recoding them. Instead, the implementation assumes that the byte string object uses the encoding passed in as parameter.

es#

(

str

) [const char *encoding, char **buffer,


Py_ssize_t

*buffer_length]

This variant on s# is used for encoding Unicode into a character buffer. Unlike the es format, this variant allows input data which contains NUL characters.

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 ，在这种情况下 '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.

There are two modes of operation:

若 *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.

若 *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.

In both cases, *buffer_length is set to the length of the encoded data without the trailing NUL byte.

et#

(

str


bytes


bytearray

) [const char *encoding, char **buffer,


Py_ssize_t

*buffer_length]

如同 es# except that byte string objects are passed through without recoding them. Instead, the implementation assumes that the byte string object uses the encoding passed in as parameter.

3.12 版改变： u , u# , Z ，和 Z# are removed because they used a legacy Py_UNICODE* 表示。

// 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 ... }

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; }

构建值 ¶

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

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) .

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 被返回。

Py_BuildValue() does not always build a tuple. It builds a tuple only if its format string contains two or more format units. If the format string is empty, it returns None ; if it contains exactly one format unit, it returns whatever object is described by that format unit. To force it to return a tuple of size 0 or one, parenthesize the format string.

When memory buffers are passed as parameters to supply data to build objects, as for the s and s# formats, the required data is copied. Buffers provided by the caller are never referenced by the objects created by Py_BuildValue() . In other words, if your code invokes malloc() and passes the allocated memory to Py_BuildValue() , your code is responsible for calling free() for that memory once Py_BuildValue() 返回。

In the following description, the quoted form is the format unit; the entry in (round) parentheses is the Python object type that the format unit will return; and the entry in [square] brackets is the type of the C value(s) to be passed.

The characters space, tab, colon and comma are ignored in format strings (but not within format units such as s# ). This can be used to make long format strings a tad more readable.

s ( str or None ) [const char *]: 转换 Null 结尾 C 字符串成 Python str 对象使用 'utf-8' 编码。若 C 字符串指针是 NULL , None 被使用。
s# ( str or None ) [const char *, Py_ssize_t ]: 转换 C 字符串及其长度为 Python str 对象使用 'utf-8' 编码。若 C 字符串指针是 NULL ，长度被忽略和 None 被返回。
y ( bytes ) [const char *]: 这将 C 字符串转换成 Python bytes 对象。若 C 字符串指针是 NULL , None 被返回。
y# ( bytes ) [const char *, Py_ssize_t ]: This converts a C string and its lengths to a Python object. If the C string pointer is NULL , None 被返回。
z ( str or None ) [const char *]: 如同 s .
z# ( str or None ) [const char *, Py_ssize_t ]: 如同 s# .
u ( str ) [const wchar_t *]: 转换 Null 结尾 wchar_t buffer of Unicode (UTF-16 or UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is NULL , None 被返回。
u# ( str ) [const wchar_t *, Py_ssize_t ]: 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 ，长度被忽略和 None 被返回。
U ( str or None ) [const char *]: 如同 s .
U# ( str or 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 ( bytes of length 1) [char]: 转换 C int representing a byte to a Python bytes object of length 1.
C ( str of length 1) [int]: 转换 C int representing a character to Python str object of length 1.
d ( float ) [double]: 转换 C double to a Python floating-point number.
f ( float ) [float]: 转换 C float to a Python floating-point number.
D ( complex ) [Py_complex *]: 转换 C Py_complex structure to a Python complex number.
O (object) [PyObject *]: Pass a Python object untouched but create a new 强引用 to it (i.e. its reference count 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() 将返回 NULL but won’t raise an exception. If no exception has been raised yet, SystemError 有设置。
S (object) [PyObject *]: 如同 O .
N (object) [PyObject *]: 如同 O , except it doesn’t create a new 强引用 . Useful when the object is created by a call to an object constructor in the argument list.
O& (object) [ converter , anything ]: 转换 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 若出现错误。
(items) ( tuple ) [ matching-items ]: Convert a sequence of C values to a Python tuple with the same number of items.
[items] ( list ) [ matching-items ]: Convert a sequence of C values to a Python list with the same number of items.
{items} ( dict ) [ matching-items ]: Convert a sequence of C values to a Python dictionary. Each pair of consecutive C values adds one item to the dictionary, serving as key and value, respectively.

若格式字符串中有错误， SystemError 异常被设置和 NULL 被返回。

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

返回值：新引用。 属于稳定 ABI (应用程序二进制接口) .

等同于 Py_BuildValue() ，除了它接受 va_list 而不是可变数自变量。

解析自变量和构建值 ¶

剖析自变量 ¶

字符串和缓冲 ¶

数字 ¶

其它对象 ¶

API 函数 ¶

构建值 ¶

内容表

上一话题

下一话题

本页