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

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

這些格式允許將對(duì)象按照連續(xù)的內(nèi)存塊形式進(jìn)行訪問。你沒必要提供返回的 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)整大小或者被銷毀所帶來的風(fēng)險(xiǎn)。因此，你不得不調(diào)用 PyBuffer_Release() 在你結(jié)束數(shù)據(jù)的處理時(shí)(或者在之前任何中斷事件中)

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

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

s (str) [const char *]

將一個(gè) Unicode 對(duì)象轉(zhuǎn)換成一個(gè)指向字符串的 C 指針。一個(gè)指針指向一個(gè)已經(jīng)存在的字符串，這個(gè)字符串存儲(chǔ)的是傳如的字符指針變量。C 字符串是已空結(jié)束的。Python 字符串不能包含嵌入的無效的代碼點(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ì)象也接受類字節(jié)類型對(duì)象。它為由調(diào)用者提供的 Py_buffer 結(jié)構(gòu)賦值。這里結(jié)果的 C 字符串可能包含嵌入的 NUL 字節(jié)。Unicode 對(duì)象通過 'utf-8' 編碼轉(zhuǎn)化成 C 字符串。

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

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

z (str or None) [const char *]

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

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

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

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

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

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

這個(gè)表達(dá)式將一個(gè)類字節(jié)類型對(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ì)象，只接受類字節(jié)類型變量。這是接受二進(jìn)制數(shù)據(jù)的推薦方法。

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

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

U (str) [PyObject *]

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

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

這個(gè)表達(dá)式接受任何實(shí)現(xiàn)可讀寫緩存區(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ū)。它只處理沒有嵌 NUL 字節(jié)的已編碼數(shù)據(jù)。

此格式需要兩個(gè)參數(shù)。 第一個(gè)僅用作輸入，并且必須為 const char*，它指向一個(gè)以 NUL 結(jié)束的字符串表示的編碼格式名稱，或者為 NULL，這表示使用 'utf-8' 編碼格式。 如果為 Python 無法識(shí)別的編碼格式名稱則會(huì)引發(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ù)是編碼后的字符串類型。

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

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

它需要三個(gè)參數(shù)。 第一個(gè)僅用作輸入，并且必須為 const char*，它指向一個(gè)編碼格式名稱，形式為以 NUL 結(jié)束的字符串或 NULL，在后一種情況下將使用 'utf-8' 編碼格式。 如果編碼格式名稱無法被 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ù)的長度。

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

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

數(shù)字?

b (int) [unsigned char]

將一個(gè)非負(fù)的 Python 整型轉(zhuǎn)化成一個(gè)無符號(hào)的微整型，存儲(chǔ)在一個(gè) C unsigned char 類型中。

B (int) [unsigned char]

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

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 無符號(hào)短整型，并不檢查溢出問題。

i (int) [int]

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

I (int) [unsigned int]

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

l (int) [long int]

將一個(gè) Python 整型轉(zhuǎn)化成一個(gè) C long int 長整型。

k (int) [unsigned long]

將一個(gè)Python整型轉(zhuǎn)化成一個(gè)C unsigned long int 無符號(hào)長整型，并不檢查溢出問題。

L (int) [long long]

將一個(gè) Python 整型轉(zhuǎn)化成一個(gè) C long long 長長整型。

K (int) [unsigned long long]

將一個(gè) Python 整型轉(zhuǎn)化成一個(gè) C unsigned long long 無符號(hào)長長整型，并不檢查溢出問題。

n (int) [Py_ssize_t]

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

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

將一個(gè) Python 字節(jié)類型，如一個(gè)長度為 1 的 bytes 或者 bytearray 對(duì)象，轉(zhuǎn)化成一個(gè) C char 字符類型。

在 3.3 版更改: 允許 bytearray 類型的對(duì)象。

C (str 長度為 1) [int]

將一個(gè) Python 字符，如一個(gè)長度為 1 的 str 字符串對(duì)象，轉(zhuǎn)化成一個(gè) C int 整型類型。

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ù)類型轉(zhuǎn)化成一個(gè) C Py_complex Python 復(fù)數(shù)類型。

其他對(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 對(duì)象指針。 這類似于 O，但是接受兩個(gè) C 參數(shù)：第一個(gè)是 Python 類型對(duì)象的地址，第二個(gè)是存儲(chǔ)對(duì)象指針的 C 變量 (類型為 PyObject*) 的地址。 如果 Python 對(duì)象不具有所要求的類型，則會(huì)引發(fā) TypeError。

O& (object) [converter, anything]

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

status = converter(object, address);

其中 object 是待轉(zhuǎn)換的 Python 對(duì)象而 address 為傳給 PyArg_Parse* 函數(shù)的 void* 參數(shù)。 返回的 status 應(yīng)當(dāng)以 1 代表轉(zhuǎn)換成功而以 0 代表轉(zhuǎn)換失敗。 當(dāng)轉(zhuǎn)換失敗時(shí)，converter 函數(shù)應(yīng)當(dāng)引發(fā)異常并且會(huì)讓 address 的內(nèi)容保持未修改狀態(tà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]

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

3.3 新版功能.

(items) (tuple) [matching-items]

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

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

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

|

表明在 Python 參數(shù)列表中剩下的參數(shù)都是可選的。C 變量對(duì)應(yīng)的可選參數(shù)需要初始化為默認(rèn)值——當(dāng)一個(gè)可選參數(shù)沒有指定時(shí)， PyArg_ParseTuple() 不能訪問相應(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)后的字符串被用來作為錯(cuò)誤消息中的函數(shù)名(PyArg_ParseTuple() 函數(shù)引發(fā)的“關(guān)聯(lián)值”異常)。

;

格式單元的列表結(jié)束標(biāo)志；分號(hào)后的字符串被用來作為錯(cuò)誤消息取代默認(rèn)的錯(cuò)誤消息。 : 和 ; 相互排斥。

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

傳遞給這些函數(shù)的附加參數(shù)必須是由格式化字符串確定的變量的地址；這些都是用來存儲(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, ...)?

Part of the Stable ABI.

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

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

Part of the Stable ABI.

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

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

Part of the Stable ABI.

分析將位置參數(shù)和關(guān)鍵字參數(shù)同時(shí)轉(zhuǎn)換為局部變量的函數(shù)的參數(shù)。 keywords 參數(shù)是關(guān)鍵字參數(shù)名稱的 NULL 終止數(shù)組。 空名稱表示 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)?

Part of the Stable ABI.

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

int PyArg_ValidateKeywordArguments(PyObject*)?

Part of the Stable ABI.

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

3.2 新版功能.

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

Part of the Stable ABI.

函數(shù)被用來析構(gòu)“舊類型”函數(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, ...)?

Part of the Stable ABI.

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

這是一個(gè)使用此函數(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;
}

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

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