字符串和緩存區?

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

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

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

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

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

s (str) [const char *]

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

備注

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

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

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

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

s# (str, read-only bytes-like object) [const char *, Py_ssize_t]

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

z (str or None) [const char *]

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

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

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

z# (str, read-only bytes-like object 或者 None) [const char *, Py_ssize_t]

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

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

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

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

y* (bytes-like object) [Py_buffer]

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

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

s# 的變式，不接受 Unicode 對象，只接受類(lèi)字節類(lèi)型變量。

S (bytes) [PyBytesObject *]

要求 Python 對象為 bytes 對象，不嘗試進(jìn)行任何轉換。 如果該對象不為 bytes 對象則會(huì )引發(fā) TypeError。 C 變量也可被聲明為 PyObject* 類(lèi)型。

Y (bytearray) [PyByteArrayObject *]

要求 Python 對象為 bytearray 對象，不嘗試進(jìn)行任何轉換。 如果該對象不為 bytearray 對象則會(huì )引發(fā) TypeError。 C 變量也可被聲明為 PyObject* 類(lèi)型。

U (str) [PyObject *]

要求 Python 對象為 Unicode 對象，不嘗試進(jìn)行任何轉換。 如果該對象不為 Unicode 對象則會(huì )引發(fā) TypeError。 C 變量也可被聲明為 PyObject*。

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

這個(gè)表達式接受任何實(shí)現可讀寫(xiě)緩存區接口的對象。它為調用者提供的 Py_buffer 結構賦值。緩沖區可能存在嵌入的 null 字節。當緩沖區使用完后調用者需要調用 PyBuffer_Release()。

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

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

此格式需要兩個(gè)參數。 第一個(gè)僅用作輸入，并且必須為 const char*，它指向一個(gè)以 NUL 結束的字符串表示的編碼格式名稱(chēng)，或者為 NULL，這表示使用 'utf-8' 編碼格式。 如果為 Python 無(wú)法識別的編碼格式名稱(chēng)則會(huì )引發(fā)異常。 第二個(gè)參數必須為 char**；它所引用的指針值將被設為帶有參數文本內容的緩沖區。 文本將以第一個(gè)參數所指定的編碼格式進(jìn)行編碼。

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

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

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

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

s# 的變式，它將已編碼的 Unicode 字符存入字符緩沖區。不像 es 表達式，它允許傳入的數據包含 NUL 字符。

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

有兩種操作方式：

如果 *buffer 指向 NULL 指針，則函數將分配所需大小的緩沖區，將編碼的數據復制到此緩沖區，并設置 *buffer 以引用新分配的存儲。 呼叫者負責調用 PyMem_Free() 以在使用后釋放分配的緩沖區。

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

在這兩個(gè)例子中，*buffer_length 被設置為編碼后結尾不為 NUL 的數據的長(cháng)度。

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

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

數字?

b (int) [unsigned char]

將一個(gè)非負的 Python 整型轉化成一個(gè)無(wú)符號的微整型，存儲在一個(gè) C unsigned char 類(lèi)型中。

B (int) [unsigned char]

將一個(gè) Python 整型轉化成一個(gè)微整型并不檢查溢出問(wèn)題，存儲在一個(gè) C unsigned char 類(lèi)型中。

h (int) [short int]

將一個(gè) Python 整型轉化成一個(gè) C short int 短整型。

H (int) [unsigned short int]

將一個(gè) Python 整型轉化成一個(gè) C unsigned short int 無(wú)符號短整型，并不檢查溢出問(wèn)題。

i (int) [int]

將一個(gè) Python 整型轉化成一個(gè) C int 整型。

I (int) [unsigned int]

將一個(gè) Python 整型轉化成一個(gè) C unsigned int 無(wú)符號整型，并不檢查溢出問(wèn)題。

l (int) [long int]

將一個(gè) Python 整型轉化成一個(gè) C long int 長(cháng)整型。

k (int) [unsigned long]

將一個(gè)Python整型轉化成一個(gè)C unsigned long int 無(wú)符號長(cháng)整型，并不檢查溢出問(wèn)題。

L (int) [long long]

將一個(gè) Python 整型轉化成一個(gè) C long long 長(cháng)長(cháng)整型。

K (int) [unsigned long long]

將一個(gè) Python 整型轉化成一個(gè) C unsigned long long 無(wú)符號長(cháng)長(cháng)整型，并不檢查溢出問(wèn)題。

n (int) [Py_ssize_t]

將一個(gè) Python 整型轉化成一個(gè) C Py_ssize_t Python 元大小類(lèi)型。

c (bytes 或者 bytearray 長(cháng)度為 1) [char]

將一個(gè) Python 字節類(lèi)型，如一個(gè)長(cháng)度為 1 的 bytes 或者 bytearray 對象，轉化成一個(gè) C char 字符類(lèi)型。

在 3.3 版更改: 允許 bytearray 類(lèi)型的對象。

C (str 長(cháng)度為 1) [int]

將一個(gè) Python 字符，如一個(gè)長(cháng)度為 1 的 str 字符串對象，轉化成一個(gè) C int 整型類(lèi)型。

f (float) [float]

將一個(gè) Python 浮點(diǎn)數轉化成一個(gè) C float 浮點(diǎn)數。

d (float) [double]

將一個(gè)Python浮點(diǎn)數轉化成一個(gè)C double 雙精度浮點(diǎn)數。

D (complex) [Py_complex]

將一個(gè) Python 復數類(lèi)型轉化成一個(gè) C Py_complex Python 復數類(lèi)型。

其他對象?

O (object) [PyObject *]

將 Python 對象（不進(jìn)行任何轉換）存儲在 C 對象指針中。 因此，C 程序接收已傳遞的實(shí)際對象。 對象的引用計數不會(huì )增加。 存儲的指針不是 NULL。

O! (object) [typeobject, PyObject *]

將一個(gè) Python 對象存入一個(gè) C 對象指針。 這類(lèi)似于 O，但是接受兩個(gè) C 參數：第一個(gè)是 Python 類(lèi)型對象的地址，第二個(gè)是存儲對象指針的 C 變量 (類(lèi)型為 PyObject*) 的地址。 如果 Python 對象不具有所要求的類(lèi)型，則會(huì )引發(fā) TypeError。

O& (object) [converter, anything]

通過(guò)一個(gè) converter 函數將一個(gè) Python 對象轉換為一個(gè) C 變量。 此函數接受兩個(gè)參數：第一個(gè)是函數，第二個(gè)是 C 變量 (類(lèi)型任意) 的地址，轉換為 void* 類(lèi)型。 converter 函數將以如下方式被調用:

status = converter(object, address);

其中 object 是待轉換的 Python 對象而 address 為傳給 PyArg_Parse* 函數的 void* 參數。 返回的 status 應當以 1 代表轉換成功而以 0 代表轉換失敗。 當轉換失敗時(shí)，converter 函數應當引發(fā)異常并且會(huì )讓 address 的內容保持未修改狀態(tài)。

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

在 3.1 版更改: Py_CLEANUP_SUPPORTED 被添加。

p (bool) [int]

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

3.3 新版功能.

(items) (tuple) [matching-items]

對象必須是 Python 序列，它的長(cháng)度是 items 中格式單元的數量。C 參數必須對應 items 中每一個(gè)獨立的格式單元。序列中的格式單元可能有嵌套。

傳遞 "long" 整型(整型的值超過(guò)了平臺的 LONG_MAX 限制)是可能的，然而沒(méi)有進(jìn)行適當的范圍檢測——當接收字段太小而接收不到值時(shí)，最重要的位被靜默地截斷(實(shí)際上，C 語(yǔ)言會(huì )在語(yǔ)義繼承的基礎上強制類(lèi)型轉換——期望的值可能會(huì )發(fā)生變化)。

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

|

表明在 Python 參數列表中剩下的參數都是可選的。C 變量對應的可選參數需要初始化為默認值——當一個(gè)可選參數沒(méi)有指定時(shí)， PyArg_ParseTuple() 不能訪(fǎng)問(wèn)相應的 C 變量(變量集)的內容。

$

PyArg_ParseTupleAndKeywords() only：表明在 Python 參數列表中剩下的參數都是強制關(guān)鍵字參數。當前，所有強制關(guān)鍵字參數都必須也是可選參數，所以格式化字符串中 | 必須一直在 $ 前面。

3.3 新版功能.

:

格式單元的列表結束標志；冒號后的字符串被用來(lái)作為錯誤消息中的函數名(PyArg_ParseTuple() 函數引發(fā)的“關(guān)聯(lián)值”異常)。

;

格式單元的列表結束標志；分號后的字符串被用來(lái)作為錯誤消息取代默認的錯誤消息。 : 和 ; 相互排斥。

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

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

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

API 函數?

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

Part of the Stable ABI.

解析一個(gè)函數的參數，表達式中的參數按參數位置順序存入局部變量中。成功返回 true；失敗返回 false 并且引發(fā)相應的異常。

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

Part of the Stable ABI.

和 PyArg_ParseTuple() 相同，然而它接受一個(gè) va_list 類(lèi)型的參數而不是可變數量的參數集。

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

Part of the Stable ABI.

分析將位置參數和關(guān)鍵字參數同時(shí)轉換為局部變量的函數的參數。 keywords 參數是關(guān)鍵字參數名稱(chēng)的 NULL 終止數組。 空名稱(chēng)表示 positional-only parameters。成功時(shí)返回 true;發(fā)生故障時(shí)，它將返回 false 并引發(fā)相應的異常。

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

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

Part of the Stable ABI.

和 PyArg_ParseTupleAndKeywords() 相同，然而它接受一個(gè)va_list類(lèi)型的參數而不是可變數量的參數集。

int PyArg_ValidateKeywordArguments(PyObject*)?

Part of the Stable ABI.

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

3.2 新版功能.

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

Part of the Stable ABI.

函數被用來(lái)析構“舊類(lèi)型”函數的參數列表——這些函數使用的 METH_OLDARGS 參數解析方法已從 Python 3 中移除。這不被推薦用于新代碼的參數解析，并且在標準解釋器中的大多數代碼已被修改，已不再用于該目的。它仍然方便于分解其他元組，然而可能因為這個(gè)目的被繼續使用。

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

Part of the Stable ABI.

一個(gè)更簡(jiǎn)單的參數摘取方式，它不使用格式字符串來(lái)指定參數類(lèi)型。 使用這種方法來(lái)提取參數的函數應當在函數或方法表中聲明為 METH_VARARGS。 包含實(shí)際參數的元組應當作為 args 傳入；它必須確實(shí)是一個(gè)元組。 元組的長(cháng)度必須至少為 min 并且不超過(guò) max； min 和 max 可能相等。 額外的參數必須被傳入函數，每個(gè)參數必須是一個(gè)指向 PyObject* 變量的指針；它們將以來(lái)自 args 的值填充；它們將包含 借入引用。 對應于可選參數的變量不會(huì )由 args 給出的值填充；它們將由調用者來(lái)初始化。 此函數執行成功時(shí)返回真值，如果 args 不是元組或者包含錯誤數量的元素則返回假值；如果執行失敗則將設置一個(gè)異常。

這是一個(gè)使用此函數的示例，取自 _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è)例子中調用 PyArg_UnpackTuple() 完全等價(jià)于調用 PyArg_ParseTuple():

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