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

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

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

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

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

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

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

s (str) [const char *]

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

備注

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

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

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

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

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

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

z (str or None) [const char *]

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

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

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

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

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

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

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

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

y* (bytes-like object) [Py_buffer]

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

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

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

U (str) [PyObject *]

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

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

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

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

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

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

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

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

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

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

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

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

有兩種操作方式：

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

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

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

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

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

數(shù)字?

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 字節(jié)類型，如一個長度為 1 的 bytes 或者 bytearray 對象，轉化成一個 C char 字符類型。

在 3.3 版更改: 允許 bytearray 類型的對象。

C (str 長度為 1) [int]

將一個 Python 字符，如一個長度為 1 的 str 字符串對象，轉化成一個 C int 整型類型。

f (float) [float]

將一個 Python 浮點數(shù)轉化成一個 C float 浮點數(shù)。

d (float) [double]

將一個Python浮點數(shù)轉化成一個C double 雙精度浮點數(shù)。

D (complex) [Py_complex]

將一個 Python 復數(shù)類型轉化成一個 C Py_complex Python 復數(shù)類型。

其他對象?

O (object) [PyObject *]

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

O! (object) [typeobject, PyObject *]

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

O& (object) [converter, anything]

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

status = converter(object, address);

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

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

在 3.1 版更改: Py_CLEANUP_SUPPORTED 被添加。

p (bool) [int]

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

3.3 新版功能.

(items) (tuple) [matching-items]

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

傳遞 "long" 整型(整型的值超過了平臺的 LONG_MAX 限制)是可能的，然而沒有進行適當?shù)姆秶鷻z測——當接收字段太小而接收不到值時，最重要的位被靜默地截斷(實際上，C 語言會在語義繼承的基礎上強制類型轉換——期望的值可能會發(fā)生變化)。

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

|

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

$

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

3.3 新版功能.

:

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

;

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

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

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

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

API 函數(shù)?

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

分析將位置參數(shù)和關鍵字參數(shù)同時轉換為局部變量的函數(shù)的參數(shù)。 keywords 參數(shù)是關鍵字參數(shù)名稱的 NULL 終止數(shù)組。 空名稱表示 positional-only parameters。成功時返回 true;發(fā)生故障時，它將返回 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() 相同，然而它接受一個va_list類型的參數(shù)而不是可變數(shù)量的參數(shù)集。

int PyArg_ValidateKeywordArguments(PyObject*)?

Part of the Stable ABI.

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

3.2 新版功能.

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

這是一個使用此函數(shù)的示例，取自 _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)