解析參數(shù)并構(gòu)建值變量?

在創(chuàng)建你自己的擴(kuò)展函數(shù)和方法時(shí)，這些函數(shù)是有用的。其它的信息和樣例見(jiàn) 擴(kuò)展和嵌入 Python 解釋器。

這些函數(shù)描述的前三個(gè)，PyArg_ParseTuple()，PyArg_ParseTupleAndKeywords()，以及 PyArg_Parse()，它們都使用 格式化字符串 來(lái)將函數(shù)期待的參數(shù)告知函數(shù)。這些函數(shù)都使用相同語(yǔ)法規(guī)則的格式化字符串。

解析參數(shù)?

一個(gè)格式化字符串包含0或者更多的格式單元。一個(gè)格式單元用來(lái)描述一個(gè)Python對(duì)象；它通常是一個(gè)字符或者由括號(hào)括起來(lái)的格式單元序列。除了少數(shù)例外，一個(gè)非括號(hào)序列的格式單元通常對(duì)應(yīng)這些函數(shù)的具有單一地址的參數(shù)。在接下來(lái)的描述中，雙引號(hào)內(nèi)的表達(dá)式是格式單元；圓括號(hào)()內(nèi)的是對(duì)應(yīng)這個(gè)格式單元的Python對(duì)象類(lèi)型；方括號(hào)[]內(nèi)的是傳遞的C變量(變量集)類(lèi)型。

字符串和緩存區(qū)?

這些格式允許將對(duì)象按照連續(xù)的內(nèi)存塊形式進(jìn)行訪問(wèn)。你沒(méi)必要提供返回的unicode字符或者字節(jié)區(qū)的原始數(shù)據(jù)存儲(chǔ)。

一般的，當(dāng)一個(gè)表達(dá)式設(shè)置一個(gè)指針指向一個(gè)緩沖區(qū)，這個(gè)緩沖區(qū)可以被相應(yīng)的Python對(duì)象管理，并且這個(gè)緩沖區(qū)共享這個(gè)對(duì)象的生存周期。你不需要人為的釋放任何內(nèi)存空間。除了這些 es, es#, et and et#.

然而，當(dāng)一個(gè) Py_buffer 結(jié)構(gòu)被賦值，其包含的緩沖區(qū)被鎖住，所以調(diào)用者在隨后使用這個(gè)緩沖區(qū)，即使在 Py_BEGIN_ALLOW_THREADS 塊中，可以避免可變數(shù)據(jù)因?yàn)檎{(diào)整大小或者被銷(xiāo)毀所帶來(lái)的風(fēng)險(xiǎn)。因此，你不得不調(diào)用 PyBuffer_Release() 在你結(jié)束數(shù)據(jù)的處理時(shí)(或者在之前任何中斷事件中)

除非另有說(shuō)明，緩沖區(qū)是不會(huì)以空終止的。

某些格式需要只讀的 bytes-like object，并設(shè)置指針而不是緩沖區(qū)結(jié)構(gòu)。他們通過(guò)檢查對(duì)象的 PyBufferProcs.bf_releasebuffer 字段是否為 NULL 來(lái)發(fā)揮作用，該字段不允許為 bytearray 這樣的可變對(duì)象。

注解

所有 # 表達(dá)式的變式(s#，y#，等等)，長(zhǎng)度參數(shù)的類(lèi)型(整型或者 Py_ssize_t)在包含 Python.h 頭文件之前由 PY_SSIZE_T_CLEAN 宏的定義控制。如果這個(gè)宏被定義，長(zhǎng)度是一個(gè) Py_ssize_t Python元大小類(lèi)型而不是一個(gè) int 整型。在未來(lái)的Python版本中將會(huì)改變，只支持 Py_ssize_t 而放棄支持 int 整型。最好一直定義 PY_SSIZE_T_CLEAN 這個(gè)宏。

s (str) [const char *]

將一個(gè)Unicode對(duì)象轉(zhuǎn)換成一個(gè)指向字符串的C指針。一個(gè)指針指向一個(gè)已經(jīng)存在的字符串，這個(gè)字符串存儲(chǔ)的是傳如的字符指針變量。C字符串是已空結(jié)束的。Python字符串不能包含嵌入的無(wú)效的代碼點(diǎn)；如果由，一個(gè) ValueError 異常會(huì)被引發(fā)。Unicode對(duì)象被轉(zhuǎn)化成 'utf-8' 編碼的C字符串。如果轉(zhuǎn)換失敗，一個(gè) UnicodeError 異常被引發(fā)。

注解

這個(gè)表達(dá)式不接受 bytes-like objects。如果你想接受文件系統(tǒng)路徑并將它們轉(zhuǎn)化成C字符串，建議使用 O& 表達(dá)式配合 PyUnicode_FSConverter() 作為 轉(zhuǎn)化函數(shù)。

在 3.5 版更改: 以前，當(dāng)Python字符串中遇到了嵌入的null代碼點(diǎn)會(huì)引發(fā) TypeError 。

s* (str or bytes-like object) [Py_buffer]

這個(gè)表達(dá)式既接受Unicode對(duì)象也接受類(lèi)字節(jié)類(lèi)型對(duì)象。它為由調(diào)用者提供的 Py_buffer 結(jié)構(gòu)賦值。這里結(jié)果的C字符串可能包含嵌入的NUL字節(jié)。Unicode對(duì)象通過(guò) 'utf-8' 編碼轉(zhuǎn)化成C字符串。

s# (str, 只讀 bytes-like object) [const char *, int or Py_ssize_t]

像 s*，除了它不接受易變的對(duì)象。結(jié)果存儲(chǔ)在兩個(gè)C 變量中，第一個(gè)是指向C字符串的指針，第二個(gè)是它的長(zhǎng)度。字符串可能包含嵌入的null字節(jié)。Unicode對(duì)象都被通過(guò) 'utf-8' 編碼轉(zhuǎn)化成C字符串。

z (str or None) [const char *]

與 s 類(lèi)似，但 Python 對(duì)象也可能為 None，在這種情況下，C 指針設(shè)置為 NULL。

z* (str, bytes-like object or None) [Py_buffer]

與 s* 類(lèi)似，但 Python 對(duì)象也可能為 None，在這種情況下，Py_buffer 結(jié)構(gòu)的 buf 成員設(shè)置為 NULL。

z# (str, 只讀 bytes-like object 或 None) [const char *, int or Py_ssize_t]

與 s# 類(lèi)似，但 Python 對(duì)象也可能為 None，在這種情況下，C 指針設(shè)置為 NULL。

y (read-only bytes-like object) [const char *]

這個(gè)表達(dá)式將一個(gè)類(lèi)字節(jié)類(lèi)型對(duì)象轉(zhuǎn)化成一個(gè)指向字符串的C指針；它不接受Unicode對(duì)象。字節(jié)緩存區(qū)必須不包含嵌入的null字節(jié)；如果包含了null字節(jié)，會(huì)引發(fā)一個(gè) ValueError 異常。

在 3.5 版更改: 以前，當(dāng)字節(jié)緩沖區(qū)中遇到了嵌入的null字節(jié)會(huì)引發(fā) TypeError 。

y* (bytes-like object) [Py_buffer]

s* 的變式，不接受Unicode對(duì)象，只接受類(lèi)字節(jié)類(lèi)型變量。這是接受二進(jìn)制數(shù)據(jù)的推薦方法。

y# (只讀 bytes-like object) [const char *, int or Py_ssize_t]

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

S (bytes) [PyBytesObject *]

要求Python對(duì)象是一個(gè) bytes 類(lèi)型對(duì)象，沒(méi)有嘗試任何的轉(zhuǎn)換。如果不是一個(gè)字節(jié)類(lèi)型對(duì)象會(huì)引發(fā) TypeError 異常。C變量也可能聲明為 PyObject* 類(lèi)型。

Y (bytearray) [PyByteArrayObject *]

要求Python對(duì)象是一個(gè) bytearray 類(lèi)型對(duì)象，沒(méi)有嘗試任何的轉(zhuǎn)換。如果不是一個(gè) bytearray 類(lèi)型對(duì)象會(huì)引發(fā) TypeError 異常。C變量也可能聲明為 PyObject* 類(lèi)型。

u (str) [const Py_UNICODE *]

將一個(gè)Python Unicode對(duì)象轉(zhuǎn)化成指向一個(gè)以空終止的Unicode字符緩沖區(qū)的指針。你必須傳入一個(gè) Py_UNICODE 指針變量的地址，存儲(chǔ)了一個(gè)指向已經(jīng)存在的Unicode緩沖區(qū)的指針。請(qǐng)注意一個(gè) Py_UNICODE 類(lèi)型的字符寬度取決于編譯選項(xiàng)(16位或者32位)。Python字符串必須不能包含嵌入的null代碼點(diǎn)；如果有，引發(fā)一個(gè) ValueError 異常。

在 3.5 版更改: 以前，當(dāng)Python字符串中遇到了嵌入的null代碼點(diǎn)會(huì)引發(fā) TypeError 。

Deprecated since version 3.3, will be removed in version 4.0: 這是舊版樣式 Py_UNICODE API; 請(qǐng)遷移至 PyUnicode_AsWideCharString().

u# (str) [const Py_UNICODE *, int 或 Py_ssize_t]

u 的變式，存儲(chǔ)兩個(gè)C變量，第一個(gè)指針指向一個(gè)Unicode數(shù)據(jù)緩存區(qū)，第二個(gè)是它的長(zhǎng)度。它允許null代碼點(diǎn)。

Deprecated since version 3.3, will be removed in version 4.0: 這是舊版樣式 Py_UNICODE API; 請(qǐng)遷移至 PyUnicode_AsWideCharString().

Z (str 或 None) [const Py_UNICODE *]

與 u 類(lèi)似，但 Python 對(duì)象也可能為 None，在這種情況下 Py_UNICODE 指針設(shè)置為 NULL。

Deprecated since version 3.3, will be removed in version 4.0: 這是舊版樣式 Py_UNICODE API; 請(qǐng)遷移至 PyUnicode_AsWideCharString().

Z# (str 或 None) [const Py_UNICODE *, int 或 Py_ssize_t]

與 u# 類(lèi)似，但 Python 對(duì)象也可能為 None，在這種情況下 Py_UNICODE 指針設(shè)置為 NULL。

Deprecated since version 3.3, will be removed in version 4.0: 這是舊版樣式 Py_UNICODE API; 請(qǐng)遷移至 PyUnicode_AsWideCharString().

U (str) [PyObject *]

要求Python對(duì)象是一個(gè)Unicode對(duì)象，沒(méi)有嘗試任何的轉(zhuǎn)換。如果不是一個(gè)Unicode對(duì)象會(huì)引發(fā) TypeError 異常。C變量也可能聲明為 PyObject* 類(lèi)型。

w* (可讀寫(xiě) bytes-like object) [Py_buffer]

這個(gè)表達(dá)式接受任何實(shí)現(xiàn)可讀寫(xiě)緩存區(qū)接口的對(duì)象。它為調(diào)用者提供的 Py_buffer 結(jié)構(gòu)賦值。緩沖區(qū)可能存在嵌入的null字節(jié)。當(dāng)緩沖區(qū)使用完后調(diào)用者需要調(diào)用 PyBuffer_Release()。

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

s 的變式，它將編碼后的Unicode字符存入字符緩沖區(qū)。它只處理沒(méi)有嵌入NUL字節(jié)的已編碼數(shù)據(jù)

此格式需要兩個(gè)參數(shù)。第一個(gè)僅用作輸入，并且必須是 const char*，該名稱(chēng)將編碼的名稱(chēng)指向 NUL 終止字符串或"NULL"，在這種情況下，使用 'utf-8' 編碼。如果 Python 不知道命名編碼，則引發(fā)異常。第二個(gè)參數(shù)必須為 char** 它引用的指針的值將設(shè)置為包含參數(shù)文本內(nèi)容的緩沖區(qū)。文本將以第一個(gè)參數(shù)指定的編碼進(jìn)行編碼。

PyArg_ParseTuple() 會(huì)分配一個(gè)足夠大小的緩沖區(qū)，將編碼后的數(shù)據(jù)拷貝進(jìn)這個(gè)緩沖區(qū)并且設(shè)置 *buffer 引用這個(gè)新分配的內(nèi)存空間。調(diào)用者有責(zé)任在使用后調(diào)用 PyMem_Free() 去釋放已經(jīng)分配的緩沖區(qū)。

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

和 es 相同，除了不用重編碼傳入的字符串對(duì)象。相反，它假設(shè)傳入的參數(shù)是編碼后的字符串類(lèi)型。

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

s# 的變式，它將已編碼的Unicode字符存入字符緩沖區(qū)。不像 es 表達(dá)式，它允許傳入的數(shù)據(jù)包含NUL字符。

它需要三個(gè)參數(shù)。第一個(gè)僅用作輸入，并且必須為 const char*，該對(duì)象指向一個(gè)編碼格式名稱(chēng)，形式為以 NUL 結(jié)束的字符串或 NULL，在后一種情況下將使用 'utf-8' 編碼格式。如果編碼格式名稱(chēng)無(wú)法被 Python 識(shí)別則會(huì)引發(fā)異常。第二個(gè)參數(shù)必須為 char**；它所引用的指針的值將被設(shè)為包含參數(shù)文本內(nèi)容的緩沖區(qū)。文本將以第一個(gè)參數(shù)所指定的編碼格式進(jìn)行編碼。第三個(gè)參數(shù)必須是指向一個(gè)整數(shù)的指針；所引用的整數(shù)將被設(shè)為輸出緩沖區(qū)中的字節(jié)數(shù)。

有兩種操作方式：

如果 *buffer 指向 NULL 指針，則函數(shù)將分配所需大小的緩沖區(qū)，將編碼的數(shù)據(jù)復(fù)制到此緩沖區(qū)，并設(shè)置 *buffer 以引用新分配的存儲(chǔ)。呼叫者負(fù)責(zé)調(diào)用 PyMem_Free() 以在使用后釋放分配的緩沖區(qū)。

如果 *buffer 指向非 NULL 指針（已分配的緩沖區(qū)），則 PyArg_ParseTuple() 將使用此位置作為緩沖區(qū)，并將 *buffer_length 的初始值解釋為緩沖區(qū)大小。然后，它將將編碼的數(shù)據(jù)復(fù)制到緩沖區(qū)，并終止它。如果緩沖區(qū)不夠大，將設(shè)置一個(gè) ValueError。

在這兩個(gè)例子中，*buffer_length 被設(shè)置為編碼后結(jié)尾不為NUL的數(shù)據(jù)的長(zhǎng)度。

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

和 es# 相同，除了不用重編碼傳入的字符串對(duì)象。相反，它假設(shè)傳入的參數(shù)是編碼后的字符串類(lèi)型。

數(shù)字?

b (int) [unsigned char]: 將一個(gè)非負(fù)的Python整型轉(zhuǎn)化成一個(gè)無(wú)符號(hào)的微整型，存儲(chǔ)在一個(gè)C unsigned char 類(lèi)型中。
B (int) [unsigned char]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)微整型并不檢查溢出問(wèn)題，存儲(chǔ)在一個(gè)C unsigned char 類(lèi)型中。
h (int) [short int]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C short int 短整型。
H (int) [unsigned short int]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C unsigned short int 無(wú)符號(hào)短整型，并不檢查溢出問(wèn)題。
i (int) [int]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C int 整型。
I (int) [unsigned int]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C unsigned int 無(wú)符號(hào)整型，并不檢查溢出問(wèn)題。
l (int) [long int]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C long int 長(zhǎng)整型。
k (int) [unsigned long]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C unsigned long int 無(wú)符號(hào)長(zhǎng)整型，并不檢查溢出問(wèn)題。
L (int) [long long]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C long long 長(zhǎng)長(zhǎng)整型。
K (int) [unsigned long long]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C unsigned long long 無(wú)符號(hào)長(zhǎng)長(zhǎng)整型，并不檢查溢出問(wèn)題。
n (int) [Py_ssize_t]: 將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C Py_ssize_t Python元大小類(lèi)型。
c (bytes 或者 bytearray 長(zhǎng)度為1) [char]: 將一個(gè)Python字節(jié)類(lèi)型，如一個(gè)長(zhǎng)度為1的 bytes 或者 bytearray 對(duì)象，轉(zhuǎn)化成一個(gè)C char 字符類(lèi)型。

在 3.3 版更改: 允許 bytearray 類(lèi)型的對(duì)象。
C (str 長(zhǎng)度為1) [int]: 將一個(gè)Python字符，如一個(gè)長(zhǎng)度為1的 str 字符串對(duì)象，轉(zhuǎn)化成一個(gè)C int 整型類(lèi)型。
f (float) [float]: 將一個(gè)Python浮點(diǎn)數(shù)轉(zhuǎn)化成一個(gè)C float 浮點(diǎn)數(shù)。
d (float) [double]: 將一個(gè)Python浮點(diǎn)數(shù)轉(zhuǎn)化成一個(gè)C double 雙精度浮點(diǎn)數(shù)。
D (complex) [Py_complex]: 將一個(gè)Python復(fù)數(shù)類(lèi)型轉(zhuǎn)化成一個(gè)C Py_complex Python復(fù)數(shù)類(lèi)型。

其他對(duì)象?

O (object) [PyObject *]: 將 Python 對(duì)象（不進(jìn)行任何轉(zhuǎn)換）存儲(chǔ)在 C 對(duì)象指針中。因此，C 程序接收已傳遞的實(shí)際對(duì)象。對(duì)象的引用計(jì)數(shù)不會(huì)增加。存儲(chǔ)的指針不是 NULL。
O! (object) [typeobject, PyObject *]: 將一個(gè)Python對(duì)象存入一個(gè)C指針。和 O 類(lèi)似，但是需要兩個(gè)C參數(shù)：第一個(gè)是Python類(lèi)型對(duì)象的地址，第二個(gè)是存儲(chǔ)對(duì)象指針的C變量( PyObject* 變量)的地址。如果Python對(duì)象類(lèi)型不對(duì)，會(huì)拋出 TypeError 異常。

O& (object) [converter, anything]

通過(guò)一個(gè) converter 函數(shù)將一個(gè)Python對(duì)象轉(zhuǎn)換成一個(gè)C變量。這需要兩個(gè)參數(shù)：第一個(gè)是一個(gè)函數(shù)，第二個(gè)是一個(gè)C變量的地址(任意類(lèi)型的)，轉(zhuǎn)化為 void * 類(lèi)型。converter 函數(shù)像這樣被調(diào)用：

status = converter(object, address);

object*是待轉(zhuǎn)化的Python對(duì)象并且 *address 是傳入 PyArg_Parse*() 函數(shù)的 void* 類(lèi)型參數(shù)。返回的 status 是1代表轉(zhuǎn)換成功，0代表轉(zhuǎn)換失敗。當(dāng)轉(zhuǎn)換失敗，converter*函數(shù)會(huì)引發(fā)一個(gè)異常并且不會(huì)修改 *address 的內(nèi)容。

如果 converter 返回 Py_CLEANUP_SUPPORTED，則如果參數(shù)解析最終失敗，它可能會(huì)再次調(diào)用該函數(shù)，從而使轉(zhuǎn)換器有機(jī)會(huì)釋放已分配的任何內(nèi)存。在第二個(gè)調(diào)用中，object 參數(shù)將為 NULL;因此，該參數(shù)將為 NULL;因此，該參數(shù)將為 NULL，因此，該參數(shù)將為 NULL``（如果值）為 ``NULL address 的值與原始呼叫中的值相同。

在 3.1 版更改: Py_CLEANUP_SUPPORTED 被添加。

p (bool) [int]

測(cè)試傳入的值是否為真(一個(gè)布爾判斷)并且將結(jié)果轉(zhuǎn)化為相對(duì)應(yīng)的C true/false整型值。如果表達(dá)式為真置``1``，假則置``0``。它接受任何合法的Python值。參見(jiàn) 邏輯值檢測(cè) 獲取更多關(guān)于Python如何測(cè)試值為真的信息。

3.3 新版功能.

(items) (tuple) [matching-items]

對(duì)象必須是Python序列，它的長(zhǎng)度是 items 中格式單元的數(shù)量。C參數(shù)必須對(duì)應(yīng) items 中每一個(gè)獨(dú)立的格式單元。序列中的格式單元可能有嵌套。

傳遞 “長(zhǎng)”整型(整型的值超過(guò)了平臺(tái)的 LONG_MAX 限制)是可能的，然而沒(méi)有進(jìn)行適當(dāng)?shù)姆秶鷻z測(cè)——當(dāng)接收字段太小而接收不到值時(shí)，最重要的位被靜默地截?cái)?實(shí)際上，C語(yǔ)言會(huì)在語(yǔ)義繼承的基礎(chǔ)上強(qiáng)制類(lèi)型轉(zhuǎn)換——期望的值可能會(huì)發(fā)生變化)。

格式化字符串中還有一些其他的字符具有特殊的涵義。這些可能并不嵌套在圓括號(hào)中。它們是：

|: 表明在Python參數(shù)列表中剩下的參數(shù)都是可選的。C變量對(duì)應(yīng)的可選參數(shù)需要初始化為默認(rèn)值——當(dāng)一個(gè)可選參數(shù)沒(méi)有指定時(shí)， PyArg_ParseTuple() 不能訪問(wèn)相應(yīng)的C變量(變量集)的內(nèi)容。
$: PyArg_ParseTupleAndKeywords() only：表明在Python參數(shù)列表中剩下的參數(shù)都是強(qiáng)制關(guān)鍵字參數(shù)。當(dāng)前，所有強(qiáng)制關(guān)鍵字參數(shù)都必須也是可選參數(shù)，所以格式化字符串中 | 必須一直在 $ 前面。

3.3 新版功能.
:: 格式單元的列表結(jié)束標(biāo)志；冒號(hào)后的字符串被用來(lái)作為錯(cuò)誤消息中的函數(shù)名(PyArg_ParseTuple() 函數(shù)引發(fā)的“關(guān)聯(lián)值”異常)。
;: 格式單元的列表結(jié)束標(biāo)志；分號(hào)后的字符串被用來(lái)作為錯(cuò)誤消息取代默認(rèn)的錯(cuò)誤消息。 : 和 ; 相互排斥。

注意任何由調(diào)用者提供的Python對(duì)象引用是 借來(lái)的 引用；不要遞減它們的引用計(jì)數(shù)！

傳遞給這些函數(shù)的附加參數(shù)必須是由格式化字符串確定的變量的地址；這些都是用來(lái)存儲(chǔ)輸入元組的值。有一些情況，如上面的格式單元列表中所描述的，這些參數(shù)作為輸入值使用；在這種情況下，它們應(yīng)該匹配指定的相應(yīng)的格式單元。

為了轉(zhuǎn)換成功，arg 對(duì)象必須匹配格式并且格式必須用盡。成功的話，PyArg_Parse*() 函數(shù)返回true，反之它們返回false并且引發(fā)一個(gè)合適的異常。當(dāng) PyArg_Parse*() 函數(shù)因?yàn)槟骋粋€(gè)格式單元轉(zhuǎn)化失敗而失敗時(shí)，對(duì)應(yīng)的以及后續(xù)的格式單元地址內(nèi)的變量都不會(huì)被使用。

API 函數(shù)?

int PyArg_ParseTuple(PyObject?*args, const char?*format, ...)?: 解析一個(gè)函數(shù)的參數(shù)，表達(dá)式中的參數(shù)按參數(shù)位置順序存入局部變量中。成功返回true；失敗返回false并且引發(fā)相應(yīng)的異常。

int PyArg_VaParse(PyObject?*args, const char?*format, va_list?vargs)?: 和 PyArg_ParseTuple() 相同，然而它接受一個(gè)va_list類(lèi)型的參數(shù)而不是可變數(shù)量的參數(shù)集。

int PyArg_ParseTupleAndKeywords(PyObject?*args, PyObject?*kw, const char?*format, char?*keywords[], ...)?: 分析將位置參數(shù)和關(guān)鍵字參數(shù)同時(shí)轉(zhuǎn)換為局部變量的函數(shù)的參數(shù)。 keywords 參數(shù)是關(guān)鍵字參數(shù)名稱(chēng)的 NULL 終止數(shù)組。空名稱(chēng)表示 positional-only parameters。成功時(shí)返回 true;發(fā)生故障時(shí)，它將返回 false 并引發(fā)相應(yīng)的異常。

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

int PyArg_VaParseTupleAndKeywords(PyObject?*args, PyObject?*kw, const char?*format, char?*keywords[], va_list?vargs)?: 和 PyArg_ParseTupleAndKeywords() 相同，然而它接受一個(gè)va_list類(lèi)型的參數(shù)而不是可變數(shù)量的參數(shù)集。

int PyArg_ValidateKeywordArguments(PyObject?*)?: 確保字典中的關(guān)鍵字參數(shù)都是字符串。這個(gè)函數(shù)只被使用于 PyArg_ParseTupleAndKeywords() 不被使用的情況下，后者已經(jīng)不再做這樣的檢查。

3.2 新版功能.

int PyArg_Parse(PyObject?*args, const char?*format, ...)?: 函數(shù)被用來(lái)析構(gòu)“舊類(lèi)型”函數(shù)的參數(shù)列表——這些函數(shù)使用的 METH_OLDARGS 參數(shù)解析方法已從Python 3中移除。這不被推薦用于新代碼的參數(shù)解析，并且在標(biāo)準(zhǔn)解釋器中的大多數(shù)代碼已被修改，已不再用于該目的。它仍然方便于分解其他元組，然而可能因?yàn)檫@個(gè)目的被繼續(xù)使用。

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

一個(gè)不使用格式化字符串指定參數(shù)類(lèi)型的簡(jiǎn)單形式的參數(shù)檢索。使用這種方法來(lái)檢索參數(shù)的函數(shù)應(yīng)該在函數(shù)或者方法表中聲明 METH_VARARGS。包含實(shí)際參數(shù)的元組應(yīng)該以 args 形式被傳入；它必須是一個(gè)實(shí)際的元組。元組的長(zhǎng)度必須至少是 min 并且不超過(guò) max； min 和 max 可能相同。額外的參數(shù)必須傳遞給函數(shù)，每一個(gè)參數(shù)必須是一個(gè)指向 PyObject* 類(lèi)型變量的指針；它們將被賦值為 args 的值；它們將包含借來(lái)的引用。不在 args 里面的可選參數(shù)不會(huì)被賦值；由調(diào)用者完成初始化。函數(shù)成功則返回true并且如果 args 不是元組或者包含錯(cuò)誤數(shù)量的元素則返回false；如果失敗了會(huì)引發(fā)一個(gè)異常。

這是一個(gè)使用此函數(shù)的示例，取自 _weakref 幫助模塊用來(lái)弱化引用的源代碼：

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

這個(gè)例子中調(diào)用 PyArg_UnpackTuple() 完全等價(jià)于調(diào)用 PyArg_ParseTuple():

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

創(chuàng)建變量?

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

Return value: New reference.

基于類(lèi)似于 PyArg_Parse*() 函數(shù)系列和一系列值的格式字符串創(chuàng)建新值。在出現(xiàn)錯(cuò)誤時(shí)返回值或 NULL;如果返回 NULL，將引發(fā)異常。

Py_BuildValue() 并不一直創(chuàng)建一個(gè)元組。只有當(dāng)它的格式化字符串包含兩個(gè)或更多的格式單元才會(huì)創(chuàng)建一個(gè)元組。如果格式化字符串是空，它返回 None；如果它包含一個(gè)格式單元，它返回由格式單元描述的的任一對(duì)象。用圓括號(hào)包裹格式化字符串可以強(qiáng)制它返回一個(gè)大小為0或者1的元組

當(dāng)內(nèi)存緩存區(qū)的數(shù)據(jù)以參數(shù)形式傳遞用來(lái)構(gòu)建對(duì)象時(shí)，如 s 和 s# 格式單元，會(huì)拷貝需要的數(shù)據(jù)。調(diào)用者提供的緩沖區(qū)從來(lái)都不會(huì)被由 Py_BuildValue() 創(chuàng)建的對(duì)象來(lái)引用。換句話說(shuō)，如果你的代碼調(diào)用 malloc() 并且將分配的內(nèi)存空間傳遞給 Py_BuildValue()，你的代碼就有責(zé)任在 Py_BuildValue() 返回時(shí)調(diào)用 free() 。

在下面的描述中，雙引號(hào)的表達(dá)式使格式單元；圓括號(hào)()內(nèi)的是格式單元將要返回的Python對(duì)象類(lèi)型；方括號(hào)[]內(nèi)的是傳遞的C變量(變量集)的類(lèi)型

字符例如空格，制表符，冒號(hào)和逗號(hào)在格式化字符串中會(huì)被忽略(但是不包括格式單元，如 s#)。這可以使很長(zhǎng)的格式化字符串具有更好的可讀性。

s (str 或 None) [const char *]: 使用 'utf-8' 編碼將空終止的 C 字符串轉(zhuǎn)換為 Python str 對(duì)象。如果 C 字符串指針為 NULL，則使用 None。
s# (str 或 None) [const char *, int 或 Py_ssize_t]: 使用 'utf-8' 編碼將 C 字符串及其長(zhǎng)度轉(zhuǎn)換為 Python str 對(duì)象。如果 C 字符串指針為 NULL，則長(zhǎng)度將被忽略，并返回 None。
y (bytes) [const char *]: 這將 C 字符串轉(zhuǎn)換為 Python bytes 對(duì)象。如果 C 字符串指針為 NULL，則返回 None。
y# (bytes) [const char *, int 或 Py_ssize_t]: 這會(huì)將 C 字符串及其長(zhǎng)度轉(zhuǎn)換為一個(gè) Python 對(duì)象。如果該 C 字符串指針為 NULL，則返回 None。
z (str or None) [const char *]: 和``s``一樣。
z# (str 或 None) [const char *, int 或 Py_ssize_t]: 和``s#``一樣。
u (str) [const wchar_t *]: 將空終止的 wchar_t 的 Unicode （UTF-16 或 UCS-4）數(shù)據(jù)緩沖區(qū)轉(zhuǎn)換為 Python Unicode 對(duì)象。如果 Unicode 緩沖區(qū)指針為 NULL，則返回 None。
u# (str) [const wchar_t *, int 或 Py_ssize_t]: 將 Unicode （UTF-16 或 UCS-4）數(shù)據(jù)緩沖區(qū)及其長(zhǎng)度轉(zhuǎn)換為 Python Unicode 對(duì)象。如果 Unicode 緩沖區(qū)指針為 NULL，則長(zhǎng)度將被忽略，并返回 None。
U (str 或 None) [const char *]: 和``s``一樣。
U# (str 或 None) [const char *, int 或 Py_ssize_t]: 和``s#``一樣。
i (int) [int]: 將一個(gè)C int 整型轉(zhuǎn)化成Python整型對(duì)象。
b (int) [char]: 將一個(gè)C char 字符型轉(zhuǎn)化成Python整型對(duì)象。
h (int) [short int]: 將一個(gè)C short int 短整型轉(zhuǎn)化成Python整型對(duì)象。
l (int) [long int]: 將一個(gè)C long int 長(zhǎng)整型轉(zhuǎn)化成Python整型對(duì)象。
B (int) [unsigned char]: 將一個(gè)C unsigned char 無(wú)符號(hào)字符型轉(zhuǎn)化成Python整型對(duì)象。
H (int) [unsigned short int]: 將一個(gè)C unsigned long 無(wú)符號(hào)短整型轉(zhuǎn)化成Python整型對(duì)象。
I (int) [unsigned int]: 將一個(gè)C unsigned long 無(wú)符號(hào)整型轉(zhuǎn)化成Python整型對(duì)象。
k (int) [unsigned long]: 將一個(gè)C unsigned long 無(wú)符號(hào)長(zhǎng)整型轉(zhuǎn)化成Python整型對(duì)象。
L (int) [long long]: 將一個(gè)C long long 長(zhǎng)長(zhǎng)整形轉(zhuǎn)化成Python整形對(duì)象。
K (int) [unsigned long long]: 將一個(gè)C unsigned long long 無(wú)符號(hào)長(zhǎng)長(zhǎng)整型轉(zhuǎn)化成Python整型對(duì)象。
n (int) [Py_ssize_t]: 將一個(gè)C Py_ssize_t 類(lèi)型轉(zhuǎn)化為Python整型。
c (bytes 長(zhǎng)度為1 ) [char]: 將一個(gè)C int 整型代表的字符轉(zhuǎn)化為Python bytes 長(zhǎng)度為1的字節(jié)對(duì)象。
C (str 長(zhǎng)度為1) [int]: 將一個(gè)C int 整型代表的字符轉(zhuǎn)化為Python str 長(zhǎng)度為1的字符串對(duì)象。
d (float) [double]: 將一個(gè)C double 雙精度浮點(diǎn)數(shù)轉(zhuǎn)化為Python浮點(diǎn)數(shù)類(lèi)型數(shù)字。
f (float) [float]: 將一個(gè)C float 單精度浮點(diǎn)數(shù)轉(zhuǎn)化為Python浮點(diǎn)數(shù)類(lèi)型數(shù)字。
D (復(fù)數(shù)) [Py_complex *]: 將一個(gè)C Py_complex 類(lèi)型的結(jié)構(gòu)轉(zhuǎn)化為Python復(fù)數(shù)類(lèi)型。
O (object) [PyObject *]: 將 Python 對(duì)象傳遞不變（其引用計(jì)數(shù)除外，該計(jì)數(shù)由 1 遞增）。如果傳入的對(duì)象是 NULL 指針，則假定這是由于生成參數(shù)的調(diào)用發(fā)現(xiàn)錯(cuò)誤并設(shè)置異常而引起的。因此，Py_BuildValue() 將返回 NULL，但不會(huì)引發(fā)異常。如果尚未引發(fā)異常，則設(shè)置 SystemError。
S (object) [PyObject *]: 和``O``相同。
N (object) [PyObject *]: 和``O``相同，然而它并不增加對(duì)象的引用計(jì)數(shù)。當(dāng)通過(guò)調(diào)用參數(shù)列表中的對(duì)象構(gòu)造器創(chuàng)建對(duì)象時(shí)很實(shí)用。
O& (object) [converter, anything]: 通過(guò) converter 函數(shù)將 anything 轉(zhuǎn)換為 Python 對(duì)象。該函數(shù)以 anything （應(yīng)與 void * 兼容）作為其參數(shù)，應(yīng)返回 "new" Python 對(duì)象，如果發(fā)生錯(cuò)誤，則應(yīng)返回 NULL。
(items) (tuple) [matching-items]: 將一個(gè)C變量序列轉(zhuǎn)換成Python元組并保持相同的元素?cái)?shù)量
[items] (list) [相關(guān)的元素]: 將一個(gè)C變量序列轉(zhuǎn)換成Python列表并保持相同的元素?cái)?shù)量
{items} (dict) [相關(guān)的元素]: 將一個(gè)C變量序列轉(zhuǎn)換成Python字典。每一對(duì)連續(xù)的C變量對(duì)作為一個(gè)元素插入字典中，分別作為關(guān)鍵字和值。

如果格式字符串中出現(xiàn)錯(cuò)誤，則設(shè)置 SystemError 異常并返回 NULL。

PyObject* Py_VaBuildValue(const char?*format, va_list?vargs)?: Return value: New reference.
和 Py_BuildValue() 相同，然而它接受一個(gè)va_list類(lèi)型的參數(shù)而不是可變數(shù)量的參數(shù)集。

解析參數(shù)并構(gòu)建值變量?