# Parsing arguments and building values {#arg-parsing}

These functions are useful when creating your own extension functions and methods. Additional information and examples are available in `extending-index`{.interpreted-text role="ref"}.

The first three of these functions described, `PyArg_ParseTuple`{.interpreted-text role="c:func"}, `PyArg_ParseTupleAndKeywords`{.interpreted-text role="c:func"}, and `PyArg_Parse`{.interpreted-text role="c:func"}, all use *format strings* which are used to tell the function about the expected arguments. The format strings use the same syntax for each of these functions.

## Parsing arguments

A format string consists of zero or more \"format units.\" A format unit describes one Python object; it is usually a single character or a parenthesized sequence of format units. With a few exceptions, a format unit that is not a parenthesized sequence normally corresponds to a single address argument to these functions. In the following description, the quoted form is the format unit; the entry in (round) parentheses is the Python object type that matches the format unit; and the entry in \[square\] brackets is the type of the C variable(s) whose address should be passed.

### Strings and buffers {#arg-parsing-string-and-buffers}

:::: note
::: title
Note
:::

On Python 3.12 and older, the macro `!PY_SSIZE_T_CLEAN`{.interpreted-text role="c:macro"} must be defined before including `Python.h`{.interpreted-text role="file"} to use all `#` variants of formats (`s#`, `y#`, etc.) explained below. This is not necessary on Python 3.13 and later.
::::

These formats allow accessing an object as a contiguous chunk of memory. You don\'t have to provide raw storage for the returned unicode or bytes area.

Unless otherwise stated, buffers are not NUL-terminated.

There are three ways strings and buffers can be converted to C:

- Formats such as `y*` and `s*` fill a `Py_buffer`{.interpreted-text role="c:type"} structure. This locks the underlying buffer so that the caller can subsequently use the buffer even inside a `Py_BEGIN_ALLOW_THREADS`{.interpreted-text role="c:type"} block without the risk of mutable data being resized or destroyed. As a result, **you have to call** `PyBuffer_Release`{.interpreted-text role="c:func"} after you have finished processing the data (or in any early abort case).

- The `es`, `es#`, `et` and `et#` formats allocate the result buffer. **You have to call** `PyMem_Free`{.interpreted-text role="c:func"} after you have finished processing the data (or in any early abort case).

- ::: {#c-arg-borrowed-buffer}
  Other formats take a `str`{.interpreted-text role="class"} or a read-only `bytes-like object`{.interpreted-text role="term"}, such as `bytes`{.interpreted-text role="class"}, and provide a `const char *` pointer to its buffer. In this case the buffer is \"borrowed\": it is managed by the corresponding Python object, and shares the lifetime of this object. You won\'t have to release any memory yourself.
  :::

  To ensure that the underlying buffer may be safely borrowed, the object\'s `PyBufferProcs.bf_releasebuffer`{.interpreted-text role="c:member"} field must be `NULL`. This disallows common mutable objects such as `bytearray`{.interpreted-text role="class"}, but also some read-only objects such as `memoryview`{.interpreted-text role="class"} of `bytes`{.interpreted-text role="class"}.

  Besides this `bf_releasebuffer` requirement, there is no check to verify whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data).

`s` (`str`{.interpreted-text role="class"}) \[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`{.interpreted-text role="exc"} exception is raised. Unicode objects are converted to C strings using `'utf-8'` encoding. If this conversion fails, a `UnicodeError`{.interpreted-text role="exc"} is raised.

    :::: note
    ::: title
    Note
    :::

    This format does not accept `bytes-like objects
    <bytes-like object>`{.interpreted-text role="term"}. 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`{.interpreted-text role="c:func"} as *converter*.
    ::::

    ::: versionchanged
    3.5 Previously, `TypeError`{.interpreted-text role="exc"} was raised when embedded null code points were encountered in the Python string.
    :::

`s*` (`str`{.interpreted-text role="class"} or `bytes-like object`{.interpreted-text role="term"}) \[Py_buffer\]

:   This format accepts Unicode objects as well as bytes-like objects. It fills a `Py_buffer`{.interpreted-text role="c:type"} 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`{.interpreted-text role="class"}, read-only `bytes-like object`{.interpreted-text role="term"}) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]

:   Like `s*`, except that it provides a `borrowed buffer <c-arg-borrowed-buffer>`{.interpreted-text role="ref"}. The result is stored into two C variables, the first one a pointer to a C string, the second one its length. The string may contain embedded null bytes. Unicode objects are converted to C strings using `'utf-8'` encoding.

`z` (`str`{.interpreted-text role="class"} or `None`) \[const char \*\]

:   Like `s`, but the Python object may also be `None`, in which case the C pointer is set to `NULL`.

`z*` (`str`{.interpreted-text role="class"}, `bytes-like object`{.interpreted-text role="term"} or `None`) \[Py_buffer\]

:   Like `s*`, but the Python object may also be `None`, in which case the `buf` member of the `Py_buffer`{.interpreted-text role="c:type"} structure is set to `NULL`.

`z#` (`str`{.interpreted-text role="class"}, read-only `bytes-like object`{.interpreted-text role="term"} or `None`) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]

:   Like `s#`, but the Python object may also be `None`, in which case the C pointer is set to `NULL`.

`y` (read-only `bytes-like object`{.interpreted-text role="term"}) \[const char \*\]

:   This format converts a bytes-like object to a C pointer to a `borrowed <c-arg-borrowed-buffer>`{.interpreted-text role="ref"} character string; it does not accept Unicode objects. The bytes buffer must not contain embedded null bytes; if it does, a `ValueError`{.interpreted-text role="exc"} exception is raised.

    ::: versionchanged
    3.5 Previously, `TypeError`{.interpreted-text role="exc"} was raised when embedded null bytes were encountered in the bytes buffer.
    :::

`y*` (`bytes-like object`{.interpreted-text role="term"}) \[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`{.interpreted-text role="term"}) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]

:   This variant on `s#` doesn\'t accept Unicode objects, only bytes-like objects.

`S` (`bytes`{.interpreted-text role="class"}) \[PyBytesObject \*\]

:   Requires that the Python object is a `bytes`{.interpreted-text role="class"} object, without attempting any conversion. Raises `TypeError`{.interpreted-text role="exc"} if the object is not a bytes object. The C variable may also be declared as `PyObject*`{.interpreted-text role="c:expr"}.

`Y` (`bytearray`{.interpreted-text role="class"}) \[PyByteArrayObject \*\]

:   Requires that the Python object is a `bytearray`{.interpreted-text role="class"} object, without attempting any conversion. Raises `TypeError`{.interpreted-text role="exc"} if the object is not a `bytearray`{.interpreted-text role="class"} object. The C variable may also be declared as `PyObject*`{.interpreted-text role="c:expr"}.

`U` (`str`{.interpreted-text role="class"}) \[PyObject \*\]

:   Requires that the Python object is a Unicode object, without attempting any conversion. Raises `TypeError`{.interpreted-text role="exc"} if the object is not a Unicode object. The C variable may also be declared as `PyObject*`{.interpreted-text role="c:expr"}.

`w*` (read-write `bytes-like object`{.interpreted-text role="term"}) \[Py_buffer\]

:   This format accepts any object which implements the read-write buffer interface. It fills a `Py_buffer`{.interpreted-text role="c:type"} structure provided by the caller. The buffer may contain embedded null bytes. The caller has to call `PyBuffer_Release`{.interpreted-text role="c:func"} when it is done with the buffer.

`es` (`str`{.interpreted-text role="class"}) \[const char \*encoding, char \*\*buffer\]

:   This variant on `s` is used for encoding Unicode into a character buffer. It only works for encoded data without embedded NUL bytes.

    This format requires two arguments. The first is only used as input, and must be a `const char*`{.interpreted-text role="c:expr"} which points to the name of an encoding as a NUL-terminated string, or `NULL`, in which case `'utf-8'` encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a `char**`{.interpreted-text role="c:expr"}; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument.

    `PyArg_ParseTuple`{.interpreted-text role="c:func"} 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`{.interpreted-text role="c:func"} to free the allocated buffer after use.

`et` (`str`{.interpreted-text role="class"}, `bytes`{.interpreted-text role="class"} or `bytearray`{.interpreted-text role="class"}) \[const char \*encoding, char \*\*buffer\]

:   Same as `es` except that byte string objects are passed through without recoding them. Instead, the implementation assumes that the byte string object uses the encoding passed in as parameter.

`es#` (`str`{.interpreted-text role="class"}) \[const char \*encoding, char \*\*buffer, `Py_ssize_t`{.interpreted-text role="c:type"} \*buffer_length\]

:   This variant on `s#` is used for encoding Unicode into a character buffer. Unlike the `es` format, this variant allows input data which contains NUL characters.

    It requires three arguments. The first is only used as input, and must be a `const char*`{.interpreted-text role="c:expr"} which points to the name of an encoding as a NUL-terminated string, or `NULL`, in which case `'utf-8'` encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a `char**`{.interpreted-text role="c:expr"}; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument. The third argument must be a pointer to an integer; the referenced integer will be set to the number of bytes in the output buffer.

    There are two modes of operation:

    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`{.interpreted-text role="c:func"} to free the allocated buffer after usage.

    If *\*buffer* points to a non-`NULL` pointer (an already allocated buffer), `PyArg_ParseTuple`{.interpreted-text role="c:func"} 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`{.interpreted-text role="exc"} will be set.

    In both cases, *\*buffer_length* is set to the length of the encoded data without the trailing NUL byte.

`et#` (`str`{.interpreted-text role="class"}, `bytes`{.interpreted-text role="class"} or `bytearray`{.interpreted-text role="class"}) \[const char \*encoding, char \*\*buffer, `Py_ssize_t`{.interpreted-text role="c:type"} \*buffer_length\]

:   Same as `es#` except that byte string objects are passed through without recoding them. Instead, the implementation assumes that the byte string object uses the encoding passed in as parameter.

::: versionchanged
3.12 `u`, `u#`, `Z`, and `Z#` are removed because they used a legacy `Py_UNICODE*` representation.
:::

### Numbers

These formats allow representing Python numbers or single characters as C numbers. Formats that require `int`{.interpreted-text role="class"}, `float`{.interpreted-text role="class"} or `complex`{.interpreted-text role="class"} can also use the corresponding special methods `~object.__index__`{.interpreted-text role="meth"}, `~object.__float__`{.interpreted-text role="meth"} or `~object.__complex__`{.interpreted-text role="meth"} to convert the Python object to the required type.

For signed integer formats, `OverflowError`{.interpreted-text role="exc"} 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`{.interpreted-text role="exc"} 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`{.interpreted-text role="class"}) \[unsigned char\]

:   Convert a nonnegative Python integer to an unsigned tiny integer, stored in a C `unsigned char`{.interpreted-text role="c:expr"}.

`B` (`int`{.interpreted-text role="class"}) \[unsigned char\]

:   Convert a Python integer to a tiny integer without overflow checking, stored in a C `unsigned char`{.interpreted-text role="c:expr"}. Convert a Python integer to a C `unsigned char`{.interpreted-text role="c:expr"}.

`h` (`int`{.interpreted-text role="class"}) \[short int\]

:   Convert a Python integer to a C `short int`{.interpreted-text role="c:expr"}.

`H` (`int`{.interpreted-text role="class"}) \[unsigned short int\]

:   Convert a Python integer to a C `unsigned short int`{.interpreted-text role="c:expr"}.

`i` (`int`{.interpreted-text role="class"}) \[int\]

:   Convert a Python integer to a plain C `int`{.interpreted-text role="c:expr"}.

`I` (`int`{.interpreted-text role="class"}) \[unsigned int\]

:   Convert a Python integer to a C `unsigned int`{.interpreted-text role="c:expr"}.

`l` (`int`{.interpreted-text role="class"}) \[long int\]

:   Convert a Python integer to a C `long int`{.interpreted-text role="c:expr"}.

`k` (`int`{.interpreted-text role="class"}) \[unsigned long\]

:   Convert a Python integer to a C `unsigned long`{.interpreted-text role="c:expr"}.

    ::: versionchanged
    3.14 Use `~object.__index__`{.interpreted-text role="meth"} if available.
    :::

`L` (`int`{.interpreted-text role="class"}) \[long long\]

:   Convert a Python integer to a C `long long`{.interpreted-text role="c:expr"}.

`K` (`int`{.interpreted-text role="class"}) \[unsigned long long\]

:   Convert a Python integer to a C `unsigned long long`{.interpreted-text role="c:expr"}.

    ::: versionchanged
    3.14 Use `~object.__index__`{.interpreted-text role="meth"} if available.
    :::

`n` (`int`{.interpreted-text role="class"}) \[`Py_ssize_t`{.interpreted-text role="c:type"}\]

:   Convert a Python integer to a C `Py_ssize_t`{.interpreted-text role="c:type"}.

`c` (`bytes`{.interpreted-text role="class"} or `bytearray`{.interpreted-text role="class"} of length 1) \[char\]

:   Convert a Python byte, represented as a `bytes`{.interpreted-text role="class"} or `bytearray`{.interpreted-text role="class"} object of length 1, to a C `char`{.interpreted-text role="c:expr"}.

    ::: versionchanged
    3.3 Allow `bytearray`{.interpreted-text role="class"} objects.
    :::

`C` (`str`{.interpreted-text role="class"} of length 1) \[int\]

:   Convert a Python character, represented as a `str`{.interpreted-text role="class"} object of length 1, to a C `int`{.interpreted-text role="c:expr"}.

`f` (`float`{.interpreted-text role="class"}) \[float\]

:   Convert a Python floating-point number to a C `float`{.interpreted-text role="c:expr"}.

`d` (`float`{.interpreted-text role="class"}) \[double\]

:   Convert a Python floating-point number to a C `double`{.interpreted-text role="c:expr"}.

`D` (`complex`{.interpreted-text role="class"}) \[Py_complex\]

:   Convert a Python complex number to a C `Py_complex`{.interpreted-text role="c:type"} structure.

::: deprecated
3.15

For unsigned integer formats `B`, `H`, `I`, `k` and `K`, `DeprecationWarning`{.interpreted-text role="exc"} 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.
:::

### Other objects

`O` (object) \[PyObject \*\]

:   Store a Python object (without any conversion) in a C object pointer. The C program thus receives the actual object that was passed. A new `strong reference`{.interpreted-text role="term"} to the object is not created (i.e. its reference count is not increased). The pointer stored is not `NULL`.

`O!` (object) \[*typeobject*, PyObject \*\]

:   Store a Python object in a C object pointer. This is similar to `O`, but takes two C arguments: the first is the address of a Python type object, the second is the address of the C variable (of type `PyObject*`{.interpreted-text role="c:expr"}) into which the object pointer is stored. If the Python object does not have the required type, `TypeError`{.interpreted-text role="exc"} is raised.

::: {#o_ampersand}

`O&` (object) \[*converter*, *address*\]

:   Convert a Python object to a C variable through a *converter* function. This takes two arguments: the first is a function, the second is the address of a C variable (of arbitrary type), converted to `void *`{.interpreted-text role="c:expr"}. The *converter* function in turn is called as follows:

    ``` c
    status = converter(object, address);
    ```

    where *object* is the Python object to be converted and *address* is the `void*`{.interpreted-text role="c:expr"} argument that was passed to the `PyArg_Parse*` function. The returned *status* should be `1` for a successful conversion and `0` if the conversion has failed. When the conversion fails, the *converter* function should raise an exception and leave the content of *address* unmodified.

    If the *converter* returns `!Py_CLEANUP_SUPPORTED`{.interpreted-text role="c:macro"}, it may get called a second time if the argument parsing eventually fails, giving the converter a chance to release any memory that it had already allocated. In this second call, the *object* parameter will be `NULL`; *address* will have the same value as in the original call.

    Examples of converters: `PyUnicode_FSConverter`{.interpreted-text role="c:func"} and `PyUnicode_FSDecoder`{.interpreted-text role="c:func"}.

    ::: versionchanged
    3.1 `!Py_CLEANUP_SUPPORTED`{.interpreted-text role="c:macro"} was added.
    :::

`p` (`bool`{.interpreted-text role="class"}) \[int\]

:   Tests the value passed in for truth (a boolean **p**redicate) 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 `truth`{.interpreted-text role="ref"} for more information about how Python tests values for truth.

    ::: versionadded
    3.3
    :::

`(items)` (sequence) \[*matching-items*\]

:   The object must be a Python sequence (except `str`{.interpreted-text role="class"}, `bytes`{.interpreted-text role="class"} or `bytearray`{.interpreted-text role="class"}) whose length is the number of format units in *items*. The C arguments must correspond to the individual format units in *items*. Format units for sequences may be nested.

    If *items* contains format units which store a `borrowed buffer
    <c-arg-borrowed-buffer>`{.interpreted-text role="ref"} (`s`, `s#`, `z`, `z#`, `y`, or `y#`) or a `borrowed reference`{.interpreted-text role="term"} (`S`, `Y`, `U`, `O`, or `O!`), the object must be a Python tuple. The *converter* for the `O&` format unit in *items* must not store a borrowed buffer or a borrowed reference.

    ::: versionchanged
    3.14 `str`{.interpreted-text role="class"} and `bytearray`{.interpreted-text role="class"} objects no longer accepted as a sequence.
    :::

    ::: deprecated
    3.14 Non-tuple sequences are deprecated if *items* contains format units which store a borrowed buffer or a borrowed reference.
    :::
:::

A few other characters have a meaning in a format string. These may not occur inside nested parentheses. They are:

`|`

:   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`{.interpreted-text role="c:func"} does not touch the contents of the corresponding C variable(s).

`$`

:   `PyArg_ParseTupleAndKeywords`{.interpreted-text role="c:func"} 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.

    ::: versionadded
    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`{.interpreted-text role="c:func"} raises).

`;`

:   The list of format units ends here; the string after the semicolon is used as the error message *instead* of the default error message. `:` and `;` mutually exclude each other.

Note that any Python object references which are provided to the caller are *borrowed* references; do not release them (i.e. do not decrement their reference count)!

Additional arguments passed to these functions must be addresses of variables whose type is determined by the format string; these are used to store values from the input tuple. There are a few cases, as described in the list of format units above, where these parameters are used as input values; they should match what is specified for the corresponding format unit in that case.

For the conversion to succeed, the *arg* object must match the format and the format must be exhausted. On success, the `PyArg_Parse*` functions return true, otherwise they return false and raise an appropriate exception. When the `PyArg_Parse*` functions fail due to conversion failure in one of the format units, the variables at the addresses corresponding to that and the following format units are left untouched.

### API Functions

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

> Identical to `PyArg_ParseTuple`{.interpreted-text role="c:func"}, except that it accepts a va_list rather than a variable number of arguments.

> Parse the parameters of a function that takes both positional and keyword parameters into local variables. The *keywords* argument is a `NULL`-terminated array of keyword parameter names specified as null-terminated ASCII or UTF-8 encoded C strings. Empty names denote `positional-only parameters <positional-only_parameter>`{.interpreted-text role="ref"}. Returns true on success; on failure, it returns false and raises the appropriate exception.
>
> :::: note
> ::: title
> Note
> :::
>
> The *keywords* parameter declaration is `char * const *`{.interpreted-text role="c:expr"} in C and `const char * const *`{.interpreted-text role="c:expr"} in C++. This can be overridden with the `PY_CXX_CONST`{.interpreted-text role="c:macro"} macro.
> ::::
>
> ::: versionchanged
> 3.6 Added support for `positional-only parameters
> <positional-only_parameter>`{.interpreted-text role="ref"}.
> :::
>
> ::: versionchanged
> 3.13 The *keywords* parameter has now type `char * const *`{.interpreted-text role="c:expr"} in C and `const char * const *`{.interpreted-text role="c:expr"} in C++, instead of `char **`{.interpreted-text role="c:expr"}. Added support for non-ASCII keyword parameter names.
> :::

> Identical to `PyArg_ParseTupleAndKeywords`{.interpreted-text role="c:func"}, except that it accepts a va_list rather than a variable number of arguments.

> Ensure that the keys in the keywords argument dictionary are strings. This is only needed if `PyArg_ParseTupleAndKeywords`{.interpreted-text role="c:func"} is not used, since the latter already does this check.
>
> ::: versionadded
> 3.2
> :::

> Parse the parameter of a function that takes a single positional parameter into a local variable. Returns true on success; on failure, it returns false and raises the appropriate exception.
>
> Example:
>
> ``` c
> // Function using METH_O calling convention
> static PyObject*
> my_function(PyObject *module, PyObject *arg)
> {
>     int value;
>     if (!PyArg_Parse(arg, "i:my_function", &value)) {
>         return NULL;
>     }
>     // ... use value ...
> }
> ```

> A simpler form of parameter retrieval which does not use a format string to specify the types of the arguments. Functions which use this method to retrieve their parameters should be declared as `METH_VARARGS`{.interpreted-text role="c:macro"} in function or method tables. The tuple containing the actual parameters should be passed as *args*; it must actually be a tuple. The length of the tuple must be at least *min* and no more than *max*; *min* and *max* may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a `PyObject*`{.interpreted-text role="c:expr"} variable; these will be filled in with the values from *args*; they will contain `borrowed references <borrowed reference>`{.interpreted-text role="term"}. The variables which correspond to optional parameters not given by *args* will not be filled in; these should be initialized by the caller. This function returns true on success and false if *args* is not a tuple or contains the wrong number of elements; an exception will be set if there was a failure.
>
> This is an example of the use of this function, taken from the sources for the `!_weakref`{.interpreted-text role="mod"} helper module for weak references:
>
> ``` c
> 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;
> }
> ```
>
> The call to `PyArg_UnpackTuple`{.interpreted-text role="c:func"} in this example is entirely equivalent to this call to `PyArg_ParseTuple`{.interpreted-text role="c:func"}:
>
> ``` c
> PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
> ```

> The value to be inserted, if any, before `char * const *`{.interpreted-text role="c:expr"} in the *keywords* parameter declaration of `PyArg_ParseTupleAndKeywords`{.interpreted-text role="c:func"} and `PyArg_VaParseTupleAndKeywords`{.interpreted-text role="c:func"}. Default empty for C and `const` for C++ (`const char * const *`{.interpreted-text role="c:expr"}). To override, define it to the desired value before including `Python.h`{.interpreted-text role="file"}.
>
> ::: versionadded
> 3.13
> :::

## Building values

> Create a new value based on a format string similar to those accepted by the `PyArg_Parse*` family of functions and a sequence of values. Returns the value or `NULL` in the case of an error; an exception will be raised if `NULL` is returned.
>
> `Py_BuildValue`{.interpreted-text role="c:func"} 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`{.interpreted-text role="c:func"}. In other words, if your code invokes `malloc`{.interpreted-text role="c:func"} and passes the allocated memory to `Py_BuildValue`{.interpreted-text role="c:func"}, your code is responsible for calling `free`{.interpreted-text role="c:func"} for that memory once `Py_BuildValue`{.interpreted-text role="c:func"} 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`{.interpreted-text role="class"} or `None`) \[const char \*\]
>
> :   Convert a null-terminated C string to a Python `str`{.interpreted-text role="class"} object using `'utf-8'` encoding. If the C string pointer is `NULL`, `None` is used.
>
> `s#` (`str`{.interpreted-text role="class"} or `None`) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   Convert a C string and its length to a Python `str`{.interpreted-text role="class"} object using `'utf-8'` encoding. If the C string pointer is `NULL`, the length is ignored and `None` is returned.
>
> `y` (`bytes`{.interpreted-text role="class"}) \[const char \*\]
>
> :   This converts a C string to a Python `bytes`{.interpreted-text role="class"} object. If the C string pointer is `NULL`, `None` is returned.
>
> `y#` (`bytes`{.interpreted-text role="class"}) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   This converts a C string and its lengths to a Python object. If the C string pointer is `NULL`, `None` is returned.
>
> `z` (`str`{.interpreted-text role="class"} or `None`) \[const char \*\]
>
> :   Same as `s`.
>
> `z#` (`str`{.interpreted-text role="class"} or `None`) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   Same as `s#`.
>
> `u` (`str`{.interpreted-text role="class"}) \[const wchar_t \*\]
>
> :   Convert a null-terminated `wchar_t`{.interpreted-text role="c:type"} buffer of Unicode (UTF-16 or UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is `NULL`, `None` is returned.
>
> `u#` (`str`{.interpreted-text role="class"}) \[const wchar_t \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   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`{.interpreted-text role="class"} or `None`) \[const char \*\]
>
> :   Same as `s`.
>
> `U#` (`str`{.interpreted-text role="class"} or `None`) \[const char \*, `Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   Same as `s#`.
>
> `i` (`int`{.interpreted-text role="class"}) \[int\]
>
> :   Convert a plain C `int`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `b` (`int`{.interpreted-text role="class"}) \[char\]
>
> :   Convert a plain C `char`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `h` (`int`{.interpreted-text role="class"}) \[short int\]
>
> :   Convert a plain C `short int`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `l` (`int`{.interpreted-text role="class"}) \[long int\]
>
> :   Convert a C `long int`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `B` (`int`{.interpreted-text role="class"}) \[unsigned char\]
>
> :   Convert a C `unsigned char`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `H` (`int`{.interpreted-text role="class"}) \[unsigned short int\]
>
> :   Convert a C `unsigned short int`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `I` (`int`{.interpreted-text role="class"}) \[unsigned int\]
>
> :   Convert a C `unsigned int`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `k` (`int`{.interpreted-text role="class"}) \[unsigned long\]
>
> :   Convert a C `unsigned long`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `L` (`int`{.interpreted-text role="class"}) \[long long\]
>
> :   Convert a C `long long`{.interpreted-text role="c:expr"} to a Python integer object.
>
> ::: {#capi-py-buildvalue-format-K}
>
> `K` (`int`{.interpreted-text role="class"}) \[unsigned long long\]
>
> :   Convert a C `unsigned long long`{.interpreted-text role="c:expr"} to a Python integer object.
>
> `n` (`int`{.interpreted-text role="class"}) \[`Py_ssize_t`{.interpreted-text role="c:type"}\]
>
> :   Convert a C `Py_ssize_t`{.interpreted-text role="c:type"} to a Python integer.
>
> `p` (`bool`{.interpreted-text role="class"}) \[int\]
>
> :   Convert a C `int`{.interpreted-text role="c:expr"} to a Python `bool`{.interpreted-text role="class"} object.
>
>     Be aware that this format requires an `int` argument. Unlike most other contexts in C, variadic arguments are not coerced to a suitable type automatically. You can convert another type (for example, a pointer or a float) to a suitable `int` value using `(x) ? 1 : 0` or `!!x`.
>
>     ::: versionadded
>     3.14
>     :::
>
> `c` (`bytes`{.interpreted-text role="class"} of length 1) \[char\]
>
> :   Convert a C `int`{.interpreted-text role="c:expr"} representing a byte to a Python `bytes`{.interpreted-text role="class"} object of length 1.
>
> `C` (`str`{.interpreted-text role="class"} of length 1) \[int\]
>
> :   Convert a C `int`{.interpreted-text role="c:expr"} representing a character to Python `str`{.interpreted-text role="class"} object of length 1.
>
> `d` (`float`{.interpreted-text role="class"}) \[double\]
>
> :   Convert a C `double`{.interpreted-text role="c:expr"} to a Python floating-point number.
>
> `f` (`float`{.interpreted-text role="class"}) \[float\]
>
> :   Convert a C `float`{.interpreted-text role="c:expr"} to a Python floating-point number.
>
> `D` (`complex`{.interpreted-text role="class"}) \[Py_complex \*\]
>
> :   Convert a C `Py_complex`{.interpreted-text role="c:type"} structure to a Python complex number.
>
> `O` (object) \[PyObject \*\]
>
> :   Pass a Python object untouched but create a new `strong reference`{.interpreted-text role="term"} to it (i.e. its reference count is incremented by one). If the object passed in is a `NULL` pointer, it is assumed that this was caused because the call producing the argument found an error and set an exception. Therefore, `Py_BuildValue`{.interpreted-text role="c:func"} will return `NULL` but won\'t raise an exception. If no exception has been raised yet, `SystemError`{.interpreted-text role="exc"} is set.
>
> `S` (object) \[PyObject \*\]
>
> :   Same as `O`.
>
> `N` (object) \[PyObject \*\]
>
> :   Same as `O`, except it doesn\'t create a new `strong reference`{.interpreted-text role="term"}. Useful when the object is created by a call to an object constructor in the argument list.
>
> `O&` (object) \[*converter*, *anything*\]
>
> :   Convert *anything* to a Python object through a *converter* function. The function is called with *anything* (which should be compatible with `void*`{.interpreted-text role="c:expr"}) as its argument and should return a \"new\" Python object, or `NULL` if an error occurred.
>
> `(items)` (`tuple`{.interpreted-text role="class"}) \[*matching-items*\]
>
> :   Convert a sequence of C values to a Python tuple with the same number of items.
>
> `[items]` (`list`{.interpreted-text role="class"}) \[*matching-items*\]
>
> :   Convert a sequence of C values to a Python list with the same number of items.
>
> `{items}` (`dict`{.interpreted-text role="class"}) \[*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`{.interpreted-text role="exc"} exception is set and `NULL` returned.

> Identical to `Py_BuildValue`{.interpreted-text role="c:func"}, except that it accepts a va_list rather than a variable number of arguments.