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 *]

Перетворення об’єкта Unicode на покажчик C на рядок символів. Покажчик на існуючий рядок зберігається в змінній покажчика символів, адресу якої ви передаєте. Рядок C закінчується NUL. Рядок Python не повинен містити вбудованих нульових кодових точок; якщо це так, виникає виняток ValueError. Об’єкти Unicode перетворюються на рядки C за допомогою кодування 'utf-8. Якщо це перетворення не вдається, виникає помилка UnicodeError.

Catatan

Цей формат не приймає байтоподібні об’єкти. Якщо ви хочете прийняти шляхи до файлової системи та перетворити їх на рядки символів C, бажано використовувати формат O& з PyUnicode_FSConverter() як перетворювач.

Berubah pada versi 3.5: Раніше помилка TypeError виникала, коли в рядку Python зустрічалися вбудовані нульові кодові точки.

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

Цей формат приймає як об’єкти Unicode, так і байтоподібні об’єкти. Він заповнює структуру Py_buffer, надану абонентом. У цьому випадку результуючий рядок C може містити вбудовані байти NUL. Об’єкти Unicode перетворюються на рядки C за допомогою кодування 'utf-8.

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: Раніше помилка TypeError виникала, коли в буфері байтів зустрічалися вбудовані нульові байти.

y* (bytes-like object) [Py_buffer]

Цей варіант s* не приймає об’єкти Unicode, лише байтоподібні об’єкти. Це рекомендований спосіб приймати двійкові дані.

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]

Цей формат приймає будь-який об’єкт, який реалізує інтерфейс буфера читання-запису. Він заповнює структуру Py_buffer, надану абонентом. Буфер може містити вбудовані нульові байти. Виклик має викликати PyBuffer_Release(), коли це буде зроблено з буфером.

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() виділить буфер необхідного розміру, скопіює закодовані дані в цей буфер і налаштує *buffer для посилання на щойно виділене сховище. Виклик відповідає за виклик PyMem_Free(), щоб звільнити виділений буфер після використання.

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:

Якщо *buffer вказує на вказівник NULL, функція виділить буфер необхідного розміру, скопіює закодовані дані в цей буфер і встановить *buffer для посилання на щойно виділене сховище. Виклик відповідає за виклик PyMem_Free(), щоб звільнити виділений буфер після використання.

Якщо *buffer вказує на вказівник, відмінний від NULL (уже виділений буфер), PyArg_ParseTuple() використовуватиме це розташування як буфер та інтерпретуватиме початкове значення *buffer_length як розмір буфера. Потім він скопіює закодовані дані в буфер і завершить його NUL. Якщо буфер недостатньо великий, буде встановлено ValueError.

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]: Перетворіть ціле число Python на 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]: Перетворіть комплексне число Python на структуру C Py_complex.

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]

Перевіряє передане значення на істинність (логічне значення pповторне визначення) і перетворює результат на еквівалентне ціле значення C true/false. Встановлює int на 1, якщо вираз був істинним, і 0, якщо він був false. Це приймає будь-яке дійсне значення Python. Перегляньте Pengujian Kebenaran Nilai для отримання додаткової інформації про те, як Python перевіряє значення на істинність.

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:

|: Вказує, що решта аргументів у списку аргументів Python необов’язкові. Змінні C, які відповідають необов’язковим аргументам, мають бути ініціалізовані значенням за замовчуванням --- коли необов’язковий аргумент не вказано, PyArg_ParseTuple() не торкається вмісту відповідних змінних C.
$: PyArg_ParseTupleAndKeywords() only: вказує, що решта аргументів у списку аргументів Python є лише ключовими словами. Наразі всі аргументи лише для ключових слів також мають бути необов’язковими, тому | завжди потрібно вказувати перед $ у рядку формату.

Added in version 3.3.
:: Тут список одиниць формату закінчується; рядок після двокрапки використовується як ім’я функції в повідомленнях про помилки ("пов’язане значення" винятку, яке викликає PyArg_ParseTuple()).
;: 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.
Проаналізуйте параметри функції, яка приймає лише позиційні параметри в локальні змінні. Повертає true в разі успіху; у разі невдачі повертає false і викликає відповідний виняток.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: Part of the Stable ABI.
Ідентичний PyArg_ParseTuple(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

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: Додано підтримку позиційних параметрів.

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.
Ідентичний PyArg_ParseTupleAndKeywords(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

int PyArg_ValidateKeywordArguments(PyObject*)¶: Part of the Stable ABI.
Переконайтеся, що ключі в словнику аргументів ключових слів є рядками. Це потрібно, лише якщо PyArg_ParseTupleAndKeywords() не використовується, оскільки останній вже виконує цю перевірку.

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

Виклик PyArg_UnpackTuple() у цьому прикладі повністю еквівалентний виклику 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() не завжди створює кортеж. Він створює кортеж, лише якщо його рядок формату містить дві або більше одиниць формату. Якщо рядок формату порожній, повертається None; якщо він містить рівно одну одиницю формату, він повертає будь-який об’єкт, описаний цією одиницею формату. Щоб змусити його повертати кортеж розміром 0 або одиницю, візьміть рядок формату в дужки.

Коли буфери пам’яті передаються як параметри для надання даних для створення об’єктів, як і для форматів s і s#, необхідні дані копіюються. Об’єкти, створені Py_BuildValue(), ніколи не посилаються на буфери, надані абонентом. Іншими словами, якщо ваш код викликає malloc() і передає виділену пам’ять Py_BuildValue(), ваш код відповідальний за виклик free() для цієї пам’яті один раз Py_BuildValue() повертає.

У наступному описі форма в лапках є одиницею формату; запис у (круглих) дужках — це тип об’єкта Python, який поверне блок формату; і запис у [квадратних] дужках є типом значень C, які потрібно передати.

Символи пробілу, табуляції, двокрапки та коми ігноруються в рядках форматування (але не в одиницях форматування, таких як s#). Це можна використати, щоб зробити рядки довгого формату трохи більш читабельними.

s (str atau None) [const char *]: Перетворіть рядок C із нульовим закінченням на об’єкт Python str за допомогою кодування 'utf-8'. Якщо вказівник на рядок C має значення NULL, використовується None.
s# (str atau None) [const char *, Py_ssize_t]: Перетворіть рядок C та його довжину на об’єкт Python str за допомогою кодування 'utf-8'. Якщо покажчик рядка C має значення NULL, довжина ігнорується і повертається None.
y (bytes) [const char *]: Це перетворює рядок C на об’єкт Python bytes. Якщо вказівник на рядок C має значення NULL, повертається None.
y# (bytes) [const char *, Py_ssize_t]: Це перетворює рядок C та його довжину на об’єкт Python. Якщо вказівник на рядок C має значення NULL, повертається None.
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]: Перетворіть буфер даних Unicode (UTF-16 або UCS-4) і його довжину на об’єкт Python Unicode. Якщо покажчик буфера Unicode має значення NULL, довжина ігнорується і повертається None.
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]

Перетворіть C Py_ssize_t на ціле число Python.

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 *]

Перетворіть структуру C Py_complex на комплексне число Python.

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]

Перетворіть послідовність значень C на кортеж Python із такою ж кількістю елементів.

[items] (list) [matching-items]

Перетворіть послідовність значень C на список Python з такою ж кількістю елементів.

{items} (dict) [matching-items]

Перетворіть послідовність значень C у словник Python. Кожна пара послідовних значень C додає один елемент до словника, який виконує функції ключа та значення відповідно.

Якщо в рядку формату є помилка, встановлюється виняток SystemError і повертається NULL.

PyObject *Py_VaBuildValue(const char *format, va_list vargs)¶: Return value: New reference. Part of the Stable ABI.
Ідентичний Py_BuildValue(), за винятком того, що він приймає va_list, а не змінну кількість аргументів.

Mengurai argumen dan membangun nilai¶