Mengurai argumen dan membangun nilai¶

Fungsi-fungsi ini berguna saat membuat fungsi dan metode ekstensi Anda sendiri. Informasi tambahan dan contoh tersedia di Memperluas dan Menggabungkan Interpreter Python.

Tiga fungsi pertama dijelaskan yaitu, PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(), dan PyArg_Parse(), semuanya menggunakan format string yang digunakan untuk memberitahu fungsi tentang expected argumen . Format string menggunakan sintaks yang sama untuk setiap fungsi tersebut.

Mengurai argumen¶

format string terdiri dari nol atau lebih "unit format." Sebuah unit format menjelaskan satu obyek Python; Seringkali adalah sebuah karaketer atau sebuah urutan unit format yang di dalam kurung. Dengan beberapa pengecualian, format unit yang bukan sebuah urutan yang di dalam kurung biasanya berhubungan dengan sebuah argumen yang memanggil fungsi-fungsi ini. Dalam penjelasan berikut ini, bentuk yang dikutip adalah unit format. Entri yang di dalam kurung (bulat) adalah tipe obyek Python yang cocok dengan unit format, dan entri yang di dalam kurung [kotak] adalah tipe variabel C yang perlu dipanggil.

String dan penyangga, buffers¶

Catatan

Pada Python 3.12 dan yang lebih lama, makro PY_SSIZE_T_CLEAN harus didefinisikan sebelum Python.h untuk menggunakan semua varian # dari format (s#, y#, dll.) yang dijelaskan di bawah ini. Ini tidak diperlukan pada Python 3.13 dan yang lebih baru.

Formaty te umożliwiają dostęp do obiektu jako ciągłego fragmentu pamięci. Nie musisz zapewniać nieprzetworzonej pamięci dla zwróconego obszaru unicode lub bajtów.

Kecuali dinyatakan lain, buffer tidak akhiri oleh NUL.

Ada tiga cara string dan buffer dapat dikonversi ke C:

Format seperti y* dan s* mengisi struktur Py_buffer. Hal ini mengunci buffer yang mendasarinya sehingga pemanggil dapat menggunakan buffer tersebut bahkan di dalam blok Py_BEGIN_ALLOW_THREADS tanpa risiko data diubah ukurannya atau dihancurkan. Akibatnya, anda harus memanggil PyBuffer_Release() setelah anda selesai memproses data (atau dalam kasus pembatalan awal).
Format es, es#, et dan et# mengalokasikan buffer hasil. anda harus menghubungi PyMem_Free() setelah anda selesai memproses data (atau dalam kasus pembatalan awal).
Format lain menggunakan str atau read-only bytes-like object, seperti bytes, dan menyediakan penunjuk const char * ke buffer-nya. Dalam kasus ini, buffer "dipinjam": buffer dikelola oleh objek Python yang sesuai, dan berbagi masa pakai dengan objek tersebut. Anda tidak perlu mengeluarkan memori sendiri.

Untuk memastikan bahwa buffer yang mendasari dapat dipinjam dengan aman, bidang PyBufferProcs.bf_releasebuffer objek harus NULL. Hal ini melarang objek umum yang dapat diubah seperti bytearray, tetapi juga beberapa objek yang hanya dapat dibaca seperti memoryview dari bytes.

Selain persyaratan bf_releasebuffer ini, tidak ada pemeriksaan untuk memverifikasi apakah objek input tidak dapat diubah (misalnya apakah ia akan memenuhi permintaan buffer yang dapat ditulis, atau apakah thread lain dapat mengubah 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 is raised.

Catatan

This format does not accept bytes-like objects. 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.

Berubah pada versi 3.5: Previously, TypeError was raised when embedded null code points were encountered in the Python string.

s* (str atau bytes-like object) [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' encoding.

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

Seperti s*, kecuali bahwa ia menyediakan buffer pinjaman. Hasilnya disimpan ke dalam dua variabel C, yang pertama adalah penunjuk ke sebuah string C, yang kedua adalah panjangnya. String tersebut dapat berisi byte null yang disematkan. Objek Unicode dikonversi ke string C menggunakan pengkodean 'utf-8'.

z (str atau None) [const char *]

Seperti s, tetapi objek Python juga dapat berupa None, dalam hal ini penunjuk C disetel ke NULL.

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

Seperti s*, tetapi objek Python juga dapat berupa None, dalam hal ini anggota buf dari struktur Py_buffer disetel ke NULL.

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

Seperti s#, tetapi objek Python juga dapat berupa None, dalam hal ini penunjuk C disetel ke NULL.

y (baca-saja bytes-like object) [const char *]

Format ini mengkonversi objek bytes-like ke C-pointer ke string karakter :ref:` yang dipinjam dari <c-arg-borrowed-buffer>`; format ini tidak menerima objek Unicode. Buffer byte tidak boleh berisi byte null yang disematkan; jika ya, pengecualian ValueError akan dimunculkan.

Berubah pada versi 3.5: Previously, TypeError was raised when embedded null bytes were encountered in the bytes buffer.

y* (bytes-like object) [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 bytes-like object) [const char *, Py_ssize_t]

Varian pada s# ini tidak menerima objek Unicode, hanya objek yang seperti byte.

S (bytes) [PyBytesObject *]

Mengharuskan objek Python adalah objek bytes, tanpa mencoba melakukan perubahan apa pun. Memunculkan TypeError jika objek tersebut bukan objek byte. Variabel C juga dapat dideklarasikan sebagai PyObject*.

Y (bytearray) [PyByteArrayObject *]

Memerlukan bahwa objek Python adalah objek bytearray, tanpa mencoba melakukan konversi apa pun. Memunculkan TypeError jika objek tersebut bukan merupakan objek bytearray. Variabel C juga dapat dideklarasikan sebagai PyObject*.

U (str) [PyObject *]

Memerlukan bahwa objek Python adalah objek Unicode, tanpa mencoba melakukan konversi apa pun. Memunculkan TypeError jika objek bukan objek Unicode. Variabel C juga dapat dideklarasikan sebagai PyObject*.

w* (baca-tulis bytes-like object) [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]

Ten wariant s jest używany do zakodowania Unicode w buforze znaków. To działa tylko dla zakodowanych danych bez osadzonych znaków NUL.

Format ini membutuhkan dua argumen. Yang pertama hanya digunakan sebagai masukan, dan harus berupa const char* yang menunjuk pada nama pengkodean sebagai string yang diakhiri dengan NUL, atau NULL, dalam hal ini pengkodean 'utf-8' yang digunakan. Pengecualian akan muncul jika pengkodean yang disebutkan tidak dikenal oleh Python. Argumen kedua harus berupa char**; nilai pointer yang direferensikan akan diset ke buffer dengan isi teks argumen. Teks akan dikodekan dalam pengkodean yang ditentukan oleh argumen pertama.

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 atau bytearray) [const char *encoding, char **buffer]

Podobnie jak es z wyjątkiem tego, że obiekty ciągów znaków są przekazywane dalej bez ich zapisywania. Zamiast tego implementacja zakłada, że obiekt łańcucha znaków wykorzystuje kodowanie przekazane jako parametr.

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

Ten wariant s# używany jest do kodowania Unicode w buforze znaków. W przeciwieństwie do formatu es, ten wariant pozwala wprowadzać dane zawierające znaki NUL.

Ini membutuhkan tiga argumen. Yang pertama hanya digunakan sebagai masukan, dan harus berupa const char* yang menunjuk pada nama pengkodean sebagai string yang diakhiri dengan NUL, atau NULL, dalam hal ini pengkodean 'utf-8' yang digunakan. Pengecualian akan muncul jika pengkodean yang disebutkan tidak dikenal oleh Python. Argumen kedua harus berupa char**; nilai pointer yang direferensikan akan disetel ke buffer dengan isi teks argumen. Teks akan dikodekan dalam pengkodean yang ditentukan oleh argumen pertama. Argumen ketiga harus berupa penunjuk ke sebuah bilangan bulat; bilangan bulat yang direferensikan akan diset ke jumlah byte dalam buffer keluaran.

Ada dua mode operasi:

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

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

W obu przypadkach, *buffer_length jest ustawiany na długość zakodowanych danych z pominięciem zakańczającego znaku NUL.

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

Tak samo, jak w es# oprócz tego, że obiekty ciągu bajtów są przekazywane do funkcji bez ich zapisywania. Zamiast tego, implementacja zakłada że obiekt ciągu bajtów używa kodowania przekazywanego w parametrze.

Berubah pada versi 3.12: u, u#,``Z``, dan Z# dihapus karena menggunakan representasi Py_UNICODE*.

Angka¶

Format-format ini memungkinkan untuk merepresentasikan angka Python atau karakter tunggal sebagai angka C. Format yang memerlukan int, float atau complex juga dapat menggunakan metode khusus __index__(), __float__() atau __complex__() untuk mengonversi objek Python ke jenis yang diperlukan.

For signed integer formats, OverflowError is raised if the value is out of range for the C type. For unsigned integer formats, the most significant bits are silently truncated when the receiving field is too small to receive the value, and DeprecationWarning is emitted when the value is larger than the maximal value for the C type or less than the minimal value for the corresponding signed integer type of the same size.

b (int) [unsigned char]: Mengonversi bilangan bulat Python nonnegatif menjadi bilangan bulat kecil unsigned, disimpan dalam C: c: expr: unsigned char.
B (int) [unsigned char]: Convert a Python integer to a tiny integer without overflow checking, stored in a C unsigned char. Convert a Python integer to a C unsigned char.
h (int) [short int]: Mengonversi bilangan bulat Python menjadi C: c: expr: short int.
H (int) [unsigned short int]: Convert a Python integer to a C unsigned short int.
i (int) [int]: Mengonversi bilangan bulat Python ke bahasa C biasa int.
I (int) [unsigned int]: Convert a Python integer to a C unsigned int.
l (int) [long int]: Mengonversi bilangan bulat Python menjadi C: c: expr: long int.
k (int) [unsigned long]: Convert a Python integer to a C unsigned long.

Berubah pada versi 3.14: Gunakan __index__() jika tersedia.
L (int) [long long]: Mengonversi bilangan bulat Python menjadi C long long.
K (int) [unsigned long long]: Convert a Python integer to a C unsigned long long.

Berubah pada versi 3.14: Gunakan __index__() jika tersedia.
n (int) [Py_ssize_t]: Convert a Python integer to a C Py_ssize_t.
c (bytes atau bytearray dengan panjang 1) [char]: Mengonversi byte Python, direpresentasikan sebagai objek bytes atau bytearray dengan panjang 1, ke C char.

Berubah pada versi 3.3: Izinkan objek bytearray.
C (str dengan panjang 1) [int]: Mengonversi karakter Python, direpresentasikan sebagai objek str dengan panjang 1, menjadi C int.
f (float) [float]: Mengonversi angka floating-point Python ke C float.
d (float) [double]: Mengonversi angka floating-point Python ke C double.
D (complex) [Py_complex]: Convert a Python complex number to a C Py_complex structure.

Ditinggalkan sejak versi 3.15.0a0 (unreleased): For unsigned integer formats B, H, I, k and K, DeprecationWarning is emitted when the value is larger than the maximal value for the C type or less than the minimal value for the corresponding signed integer type of the same size.

Objek lain¶

O (object) [PyObject *]: Menyimpan objek Python (tanpa konversi apa pun) dalam penunjuk objek C. Program C dengan demikian menerima objek aktual yang telah diberikan. Sebuah strong reference baru ke objek tidak dibuat (yaitu jumlah referensinya tidak bertambah). Pointer yang disimpan tidak NULL.
O! (object) [typeobject, PyObject *]: Menyimpan objek Python dalam penunjuk objek C. Ini mirip dengan O, tetapi membutuhkan dua argumen C: yang pertama adalah alamat objek tipe Python, yang kedua adalah alamat variabel C (bertipe PyObject*) tempat penunjuk objek disimpan. Jika objek Python tidak memiliki tipe yang dibutuhkan, TypeError akan ditampilkan.

O& (objek) [converter, adress]

Mengonversi objek Python ke variabel C melalui fungsi converter. Ini membutuhkan dua argumen: yang pertama adalah fungsi, yang kedua adalah alamat variabel C (dari tipe sembarang), yang dikonversi menjadi void*. Fungsi converter pada gilirannya dipanggil sebagai berikut:

status = converter(objek, adress);

di mana object adalah objek Python yang akan dikonversi dan address adalah argumen void* yang diteruskan ke fungsi PyArg_Parse*. status yang dikembalikan harus 1 untuk konversi yang berhasil dan 0 jika konversi gagal. Ketika konversi gagal, fungsi converter akan memunculkan pengecualian dan membiarkan konten address tidak diubah.

Jika converter mengembalikan Py_CLEANUP_SUPPORTED, ia mungkin akan dipanggil untuk kedua kalinya jika penguraian argumen pada akhirnya gagal, memberikan kesempatan kepada konverter untuk melepaskan memori yang telah dialokasikan. Pada pemanggilan kedua ini, parameter object akan menjadi NULL; address akan memiliki nilai yang sama dengan pemanggilan pertama.

Contoh konverter: PyUnicode_FSConverter() dan PyUnicode_FSDecoder().

Berubah pada versi 3.1: Py_CLEANUP_SUPPORTED ditambahkan.

p (bool) [int]

Tests the value passed in for truth (a boolean predicate) and converts the result to its equivalent C true/false integer value. Sets the int to 1 if the expression was true and 0 if it was false. This accepts any valid Python value. See Pengujian Kebenaran Nilai for more information about how Python tests values for truth.

Added in version 3.3.

(items) (sequence) [matching-items]

Objek harus berupa urutan Python (kecuali str, bytes atau bytearray) yang panjangnya adalah jumlah unit format dalam items. Argumen C harus sesuai dengan unit format individual dalam items. Unit format untuk urutan mungkin menetap.

Jika items berisi unit format yang menyimpan borrowed buffer (s, s#, z, z#, y, atau y#) atau borrowed reference (S, Y, U, O, atau O!), maka objek tersebut haruslah sebuah tuple Python. converter untuk unit format O& dalam items tidak boleh menyimpan buffer yang dipinjam atau referensi yang dipinjam.

Berubah pada versi 3.14: str dan bytearray tidak lagi diterima sebagai sebuah urutan.

Ditinggalkan sejak versi 3.14: Urutan non-tuple tidak digunakan lagi jika item berisi unit format yang menyimpan buffer yang dipinjam atau referensi yang dipinjam.

Kilka innych znaków ma jeszcze znaczenie w ciągu formatu. Nie mogą one wystąpić wewnątrz zagnieżdżonych nawiasach okrągłych. Są to:

|: Indicates that the remaining arguments in the Python argument list are optional. The C variables corresponding to optional arguments should be initialized to their default value --- when an optional argument is not specified, PyArg_ParseTuple() does not touch the contents of the corresponding C variable(s).
$: PyArg_ParseTupleAndKeywords() only: Indicates that the remaining arguments in the Python argument list are keyword-only. Currently, all keyword-only arguments must also be optional arguments, so | must always be specified before $ in the format string.

Added in version 3.3.
:: The list of format units ends here; the string after the colon is used as the function name in error messages (the "associated value" of the exception that PyArg_ParseTuple() raises).
;: Na tym kończy się lista jednostek formatu; ciąg po średniku jest traktowany jako informacja o błędzie do użycia zamiast automatycznej wiadomości o błędzie. Znaki dwukropka : i średnika ; wzajemnie się wykluczają.

Perhatikan bahwa setiap referensi objek Python yang diberikan kepada pemanggil adalah referensi borrowed; jangan lepaskan mereka (yaitu jangan mengurangi jumlah referensi mereka)!

Dodatkowe parametry przekazywane do tych funkcji muszą być adresami zmiennych których typ jest określany przez ciąg formatu; są one używane do przechowywania wartości z krotki wejściowej. Jest parę przypadków, jak opisuje to lista jednostek formatu powyżej, gdzie te parametry są używane jako wprowadzane wartości; w takich przypadku powinny one odpowiadać temu, co jest określone we właściwych im jednostach formatu.

Agar konversi berhasil, objek arg harus sesuai dengan format dan formatnya harus habis. Jika berhasil, fungsi PyArg_Parse* akan mengembalikan nilai true, jika tidak maka akan mengembalikan nilai false dan memunculkan pengecualian yang sesuai. Ketika fungsi PyArg_Parse* gagal karena kegagalan konversi pada salah satu unit format, variabel pada alamat yang sesuai dengan itu dan unit format berikutnya tidak disentuh.

Fungsi-fungsi API¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: Part of the Stable ABI.
Parse the parameters of a function that takes only positional parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Part of the Stable ABI.
Identical to PyArg_ParseTuple(), except that it accepts a va_list rather than a variable number of arguments.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: Part of the Stable ABI.
Mengurai parameter fungsi yang mengambil parameter posisi dan kata kunci ke dalam variabel lokal. Argumen * kata kunci * adalah larik NULL-terminated dari nama parameter kata kunci yang ditentukan sebagai string C yang dikodekan dengan ASCII atau UTF-8 yang diakhiri dengan nol. Nama-nama kosong menunjukkan :ref:` parameter khusus posisi <positional-only_parameter>`. Mengembalikan nilai true jika berhasil; jika gagal, mengembalikan nilai false dan memunculkan pengecualian yang sesuai.

Catatan

Deklarasi parameter keywords adalah char *const* di C dan const char *const* di C++. Hal ini dapat digantikan dengan makro PY_CXX_CONST.

Berubah pada versi 3.6: Added support for positional-only parameters.

Berubah pada versi 3.13: Parameter keywords sekarang memiliki tipe char *const* di C dan const char *const* di C++, alih-alih char**. Menambahkan dukungan untuk nama parameter kata kunci non-ASCII.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: Part of the Stable ABI.
Identical to PyArg_ParseTupleAndKeywords(), except that it accepts a va_list rather than a variable number of arguments.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Part of the Stable ABI.
Ensure that the keys in the keywords argument dictionary are strings. This is only needed if PyArg_ParseTupleAndKeywords() is not used, since the latter already does this check.

Added in version 3.2.

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

Part of the Stable ABI.

Mengurai parameter fungsi yang mengambil parameter posisi tunggal menjadi variabel lokal. Mengembalikan nilai true jika berhasil; jika gagal, mengembalikan nilai false dan memunculkan pengecualian yang sesuai.

Contoh:

// Fungsi yang menggunakan konvensi pemanggilan METH_O
static PyObject * PyObject
my_function(PyObject * modul, PyObject * arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... gunakan nilai ...
}

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

Part of the Stable ABI.

Bentuk pengambilan parameter yang lebih sederhana yang tidak menggunakan string format untuk menentukan jenis argumen. Fungsi yang menggunakan metode ini untuk mengambil parameter harus dideklarasikan sebagai METH_VARARGS dalam tabel fungsi atau metode. Tuple yang berisi parameter aktual harus diberikan sebagai * args*; harus benar-benar sebuah tuple. Panjang tuple harus setidaknya min dan tidak lebih dari max; nilsi min dan max boleh sama. Argumen tambahan harus dilewatkan ke fungsi, yang masing-masing harus berupa penunjuk ke variabel PyObject*; ini akan diisi dengan nilai dari args; mereka akan berisi :term: referensi yang dipinjam <borrowed reference>. Variabel-variabel yang berhubungan dengan parameter opsional yang tidak diberikan oleh args tidak akan diisi; variabel-variabel ini harus diinisialisasi oleh pemanggil. Fungsi ini mengembalikan nilai true jika berhasil dan false jika args bukan sebuah tuple atau berisi jumlah elemen yang salah; sebuah pengecualian akan ditetapkan jika terjadi kegagalan.

Ini adalah contoh penggunaan fungsi berikut, yang diambil dari sumber untuk modul pembantu _weakref untuk referensi yang lemah

static PyObject * 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;
}

The call to PyArg_UnpackTuple() in this example is entirely equivalent to this call to PyArg_ParseTuple():

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

PY_CXX_CONST¶: Nilai yang akan disisipkan, jika ada, sebelum char *const* dalam deklarasi parameter keywords dari PyArg_ParseTupleAndKeywords() dan PyArg_VaParseTupleAndKeywords(). Defaultnya kosong untuk C dan const untuk C++ (const char *const*). Untuk mengganti, definisikan dengan nilai yang diinginkan sebelum menyertakan Python.h.

Added in version 3.13.

Membangun nilai¶

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

Return value: New reference. Part of the Stable ABI.

Membuat nilai baru berdasarkan string format yang mirip dengan yang diterima oleh keluarga fungsi PyArg_Parse* dan urutan nilai. Mengembalikan nilai atau NULL jika terjadi kesalahan; pengecualian akan dimunculkan jika NULL dikembalikan.

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() returns.

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 atau None) [const char *]: Convert a null-terminated C string to a Python str object using 'utf-8' encoding. If the C string pointer is NULL, None is used.
s# (str atau None) [const char *, Py_ssize_t]: Convert a C string and its length to a Python str object using 'utf-8' encoding. If the C string pointer is NULL, the length is ignored and None is returned.
y (bytes) [const char *]: This converts a C string to a Python bytes object. If the C string pointer is NULL, None is returned.
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 is returned.
z (str atau None) [const char *]: Sama seperti s.
z# (str atau None) [const char *, Py_ssize_t]: Sama seperti s#.
u (str) [const wchar_t *]: Mengonversi buffer wchar_t yang diakhiri dengan nol dari data Unicode (UTF-16 atau UCS-4) menjadi objek Python Unicode. Jika penunjuk buffer Unicode adalah NULL, None akan dikembalikan.
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, the length is ignored and None is returned.
U (str atau None) [const char *]: Sama seperti s.
U# (str atau None) [const char *, Py_ssize_t]: Sama seperti s#.
i (int) [int]: Mengonversi C biasa int ke objek bilangan bulat Python.
b (int) [char]: Mengonversi C biasa char ke objek bilangan bulat Python.
h (int) [short int]: Mengkonversi C biasa: c:expr:short int menjadi objek bilangan bulat Python.
l (int) [long int]: Mengonversi C long int menjadi objek bilangan bulat Python.
B (int) [unsigned char]: Mengonversi C: c: expr: unsigned char menjadi objek bilangan bulat Python.
H (int) [unsigned short int]: Mengkonversi C unsigned short int menjadi objek integer Python.
I (int) [unsigned int]: Mengonversi C unsigned int menjadi objek bilangan bulat Python.
k (int) [unsigned long]: Mengonversi C unsigned long menjadi objek integer Python.
L (int) [long long]: Mengonversi C long long menjadi objek bilangan bulat Python.

K (int) [unsigned long long]

Mengkonversi C unsigned long long menjadi objek integer Python.

n (int) [Py_ssize_t]

Convert a C Py_ssize_t to a Python integer.

p (bool) [int]

Mengonversi C int ke objek Python bool.

Perlu diketahui bahwa format ini membutuhkan argumen int. Tidak seperti kebanyakan konteks lain dalam C, argumen variadic tidak dipaksa ke tipe yang sesuai secara otomatis. Anda dapat mengkonversi tipe lain (misalnya, pointer atau float) ke nilai int yang sesuai dengan menggunakan (x) ? 1 : 0 atau !!x.

Added in version 3.14.

c (bytes dengan panjang 1) [char]

Mengonversi C int yang mewakili byte menjadi objek Python bytes dengan panjang 1.

C (str dengan panjang 1) [int]

Mengonversi C int yang mewakili karakter ke objek Python str dengan panjang 1.

d (float) [double]

Mengonversi C double ke angka floating-point Python.

f (float) [float]

Mengonversi C float ke angka floating-point Python.

D (complex) [Py_complex *]

Convert a C Py_complex structure to a Python complex number.

O (object) [PyObject *]

Mengoper objek Python tanpa disentuh tetapi membuat referensi kuat baru ke objek tersebut (misalnya, jumlah referensinya bertambah satu). Jika objek yang dioper adalah sebuah penunjuk NULL, diasumsikan bahwa hal ini disebabkan karena pemanggilan yang menghasilkan argumen tersebut menemukan kesalahan dan membuat pengecualian. Oleh karena itu, Py_BuildValue() akan mengembalikan NULL tetapi tidak akan memunculkan pengecualian. Jika tidak ada pengecualian yang dibangkitkan, SystemError akan di-set.

S (object) [PyObject *]

Sama seperti O.

N (object) [PyObject *]

Sama seperti O, kecuali tidak membuat strong reference yang baru. Berguna ketika objek dibuat dengan pemanggilan ke konstruktor objek dalam daftar argumen.

O& (object) [converter, anything]

Mengonversi anything menjadi objek Python melalui fungsi converter. Fungsi ini dipanggil dengan anything (yang seharusnya kompatibel dengan void*) sebagai argumennya dan akan mengembalikan objek Python "new", atau NULL jika terjadi kesalahan.

(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.

If there is an error in the format string, the SystemError exception is set and NULL returned.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Return value: New reference. Part of the Stable ABI.
Identical to Py_BuildValue(), except that it accepts a va_list rather than a variable number of arguments.

Mengurai argumen dan membangun nilai¶