# 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 has 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: 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_ParseArray( PyObject *const *args, Py_ssize_t nargs, const char *format, ...)

  Parse the parameters of a function that takes only array parameters into local variables (that is, a function using the `METH_FASTCALL` calling convention). Returns true on success; on failure, it returns false and raises the appropriate exception.

  Added in version 3.15.

int PyArg_ParseArrayAndKeywords( PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)

  Parse the parameters of a function that takes both array and keyword parameters into local variables (that is, a function using the `METH_FASTCALL` `|` `METH_KEYWORDS` calling convention). Returns true on success; on failure, it returns false and raises the appropriate exception.

  Added in version 3.15.

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.