Strings and buffers¶

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

Unless otherwise stated, buffers are not NUL-terminated.

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

• Formats such asy* ands* fill aPy_buffer structure.This locks the underlying buffer so that the caller can subsequently usethe buffer even inside aPy_BEGIN_ALLOW_THREADSblock without the risk of mutable data being resized or destroyed.As a result,you have to callPyBuffer_Release() after you havefinished processing the data (or in any early abort case).

• Thees,es#,et andet# formats allocate the result buffer.You have to callPyMem_Free() after you have finishedprocessing the data (or in any early abort case).

• Other formats take astr or a read-onlybytes-like object,such asbytes, and provide aconstchar* pointer toits buffer.In this case the buffer is “borrowed”: it is managed by the correspondingPython 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’sPyBufferProcs.bf_releasebuffer field must beNULL.This disallows common mutable objects such asbytearray,but also some read-only objects such asmemoryview ofbytes.

  Besides thisbf_releasebuffer requirement, there is no check to verifywhether the input object is immutable (e.g. whether it would honor a requestfor a writable buffer, or whether another thread can mutate the 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 pointervariable whose address you pass. The C string is NUL-terminated.The Python string must not contain embedded null code points; if it does,aValueError exception is raised. Unicode objects are convertedto C strings using'utf-8' encoding. If this conversion fails, aUnicodeError is raised.

Note

This format does not acceptbytes-like objects. If you want to acceptfilesystem paths and convert them to C character strings, it ispreferable to use theO& format withPyUnicode_FSConverter()asconverter.

Changed in version 3.5:Previously,TypeError was raised when embedded null code pointswere encountered in the Python string.

s* (str orbytes-like object) [Py_buffer]

This format accepts Unicode objects as well as bytes-like objects.It fills aPy_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-onlybytes-like object) [const char *,Py_ssize_t]

Likes*, except that it provides aborrowed buffer.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 convertedto C strings using'utf-8' encoding.

z (str orNone) [const char *]

Likes, but the Python object may also beNone, in which case the Cpointer is set toNULL.

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

Likes*, but the Python object may also beNone, in which case thebuf member of thePy_buffer structure is set toNULL.

z# (str, read-onlybytes-like object orNone) [const char *,Py_ssize_t]

Likes#, but the Python object may also beNone, in which case the Cpointer is set toNULL.

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

This format converts a bytes-like object to a C pointer to aborrowed character string;it does not accept Unicode objects. The bytes buffer must notcontain embedded null bytes; if it does, aValueErrorexception is raised.

Changed in version 3.5:Previously,TypeError was raised when embedded null bytes wereencountered in the bytes buffer.

y* (bytes-like object) [Py_buffer]

This variant ons* doesn’t accept Unicode objects, onlybytes-like objects.This is the recommended way to acceptbinary data.

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

This variant ons# doesn’t accept Unicode objects, only bytes-likeobjects.

S (bytes) [PyBytesObject *]

Requires that the Python object is abytes object, withoutattempting any conversion. RaisesTypeError if the object is nota bytes object. The C variable may also be declared asPyObject*.

Y (bytearray) [PyByteArrayObject *]

Requires that the Python object is abytearray object, withoutattempting any conversion. RaisesTypeError if the object is notabytearray object. The C variable may also be declared asPyObject*.

U (str) [PyObject *]

Requires that the Python object is a Unicode object, without attemptingany conversion. RaisesTypeError if the object is not a Unicodeobject. The C variable may also be declared asPyObject*.

w* (read-writebytes-like object) [Py_buffer]

This format accepts any object which implements the read-write bufferinterface. It fills aPy_buffer structure provided by the caller.The buffer may contain embedded null bytes. The caller have to callPyBuffer_Release() when it is done with the buffer.

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

This variant ons 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, andmust be aconstchar* which points to the name of an encoding as aNUL-terminated string, orNULL, in which case'utf-8' encoding is used.An exception is raised if the named encoding is not known to Python. Thesecond argument must be achar**; the value of the pointer itreferences 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() will allocate a buffer of the needed size, copy theencoded data into this buffer and adjust*buffer to reference the newlyallocated storage. The caller is responsible for callingPyMem_Free() tofree the allocated buffer after use.

et (str,bytes orbytearray) [const char *encoding, char **buffer]

Same ases except that byte string objects are passed through withoutrecoding them. Instead, the implementation assumes that the byte string object usesthe encoding passed in as parameter.

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

This variant ons# is used for encoding Unicode into a character buffer.Unlike thees format, this variant allows input data which contains NULcharacters.

It requires three arguments. The first is only used as input, and must be aconstchar* which points to the name of an encoding as aNUL-terminated string, orNULL, in which case'utf-8' encoding is used.An exception is raised if the named encoding is not known to Python. Thesecond argument must be achar**; the value of the pointer itreferences 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 integerwill be set to the number of bytes in the output buffer.

There are two modes of operation:

If*buffer points aNULL pointer, the function will allocate a buffer ofthe needed size, copy the encoded data into this buffer and set*buffer toreference the newly allocated storage. The caller is responsible for callingPyMem_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 theinitial value of*buffer_length as the buffer size. It will then copy theencoded data into the buffer and NUL-terminate it. If the buffer is not largeenough, aValueError will be set.

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

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

Same ases# except that byte string objects are passed through without recodingthem. Instead, the implementation assumes that the byte string object uses theencoding passed in as parameter.

Numbers¶

These formats allow representing Python numbers or single characters as C numbers.Formats that requireint,float orcomplex canalso use the corresponding special methods__index__(),__float__() or__complex__() to convertthe Python object to the required type.

For signed integer formats,OverflowError is raised if the valueis out of range for the C type.For unsigned integer formats, no range checking is done — themost significant bits are silently truncated when the receiving field is toosmall to receive the value.

b (int) [unsigned char]

Convert a nonnegative Python integer to an unsigned tiny integer, stored in a Cunsignedchar.

B (int) [unsigned char]

Convert a Python integer to a tiny integer without overflow checking, stored in a Cunsignedchar.

h (int) [short int]

Convert a Python integer to a Cshortint.

H (int) [unsigned short int]

Convert a Python integer to a Cunsignedshortint, without overflowchecking.

i (int) [int]

Convert a Python integer to a plain Cint.

I (int) [unsigned int]

Convert a Python integer to a Cunsignedint, without overflowchecking.

l (int) [long int]

Convert a Python integer to a Clongint.

k (int) [unsigned long]

Convert a Python integer to a Cunsignedlong withoutoverflow checking.

L (int) [long long]

Convert a Python integer to a Clonglong.

K (int) [unsigned long long]

Convert a Python integer to a Cunsignedlonglongwithout overflow checking.

n (int) [Py_ssize_t]

Convert a Python integer to a CPy_ssize_t.

c (bytes orbytearray of length 1) [char]

Convert a Python byte, represented as abytes orbytearray object of length 1, to a Cchar.

Changed in version 3.3:Allowbytearray objects.

C (str of length 1) [int]

Convert a Python character, represented as astr object oflength 1, to a Cint.

f (float) [float]

Convert a Python floating-point number to a Cfloat.

d (float) [double]

Convert a Python floating-point number to a Cdouble.

D (complex) [Py_complex]

Convert a Python complex number to a CPy_complex structure.

Other objects¶

O (object) [PyObject *]

Store a Python object (without any conversion) in a C object pointer. The Cprogram thus receives the actual object that was passed. A newstrong reference to the object is not created(i.e. its reference count is not increased).The pointer stored is notNULL.

O! (object) [typeobject, PyObject *]

Store a Python object in a C object pointer. This is similar toO, buttakes two C arguments: the first is the address of a Python type object, thesecond is the address of the C variable (of typePyObject*) into whichthe object pointer is stored. If the Python object does not have the requiredtype,TypeError is raised.

O& (object) [converter,address]

Convert a Python object to a C variable through aconverter function. Thistakes two arguments: the first is a function, the second is the address of a Cvariable (of arbitrary type), converted tovoid*. Theconverterfunction in turn is called as follows:

status=converter(object,address);

whereobject is the Python object to be converted andaddress is thevoid* argument that was passed to thePyArg_Parse* function.The returnedstatus should be1 for a successful conversion and0 ifthe conversion has failed. When the conversion fails, theconverter functionshould raise an exception and leave the content ofaddress unmodified.

If theconverter returnsPy_CLEANUP_SUPPORTED, it may get called asecond time if the argument parsing eventually fails, giving the converter achance to release any memory that it had already allocated. In this secondcall, theobject parameter will beNULL;address will have the same valueas in the original call.

Examples of converters:PyUnicode_FSConverter() andPyUnicode_FSDecoder().

Changed in version 3.1:Py_CLEANUP_SUPPORTED was added.

p (bool) [int]

Tests the value passed in for truth (a booleanpredicate) and convertsthe result to its equivalent C true/false integer value.Sets the int to1 if the expression was true and0 if it was false.This accepts any valid Python value. SeeTruth Value Testing for moreinformation about how Python tests values for truth.

Added in version 3.3.

(items) (tuple) [matching-items]

The object must be a Python sequence whose length is the number of format unitsinitems. The C arguments must correspond to the individual format units initems. Format units for sequences may be nested.

A few other characters have a meaning in a format string. These may not occurinside 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 totheir default value — when an optional argument is not specified,PyArg_ParseTuple() does not touch the contents of the corresponding Cvariable(s).

$

PyArg_ParseTupleAndKeywords() only:Indicates that the remaining arguments in the Python argument list arekeyword-only. Currently, all keyword-only arguments must also be optionalarguments, so| must always be specified before$ in the formatstring.

Added in version 3.3.

:

The list of format units ends here; the string after the colon is used as thefunction name in error messages (the “associated value” of the exception thatPyArg_ParseTuple() raises).

;

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

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

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

For the conversion to succeed, thearg object must match the formatand the format must be exhausted. On success, thePyArg_Parse* functions return true, otherwise they returnfalse and raise an appropriate exception. When thePyArg_Parse* functions fail due to conversion failure in oneof the format units, the variables at the addresses corresponding to thatand the following format units are left untouched.

API Functions¶

intPyArg_ParseTuple(PyObject*args,constchar*format,...)¶

Part of theStable ABI.

Parse the parameters of a function that takes only positional parameters intolocal variables. Returns true on success; on failure, it returns false andraises the appropriate exception.

intPyArg_VaParse(PyObject*args,constchar*format,va_listvargs)¶

Part of theStable ABI.

Identical toPyArg_ParseTuple(), except that it accepts a va_list ratherthan a variable number of arguments.

intPyArg_ParseTupleAndKeywords(PyObject*args,PyObject*kw,constchar*format,char*const*keywords,...)¶

Part of theStable ABI.

Parse the parameters of a function that takes both positional and keywordparameters into local variables.Thekeywords argument is aNULL-terminated array of keyword parameternames specified as null-terminated ASCII or UTF-8 encoded C strings.Empty names denotepositional-only parameters.Returns true on success; on failure, it returns false and raises theappropriate exception.

Note

Thekeywords parameter declaration ischar*const* in C andconstchar*const* in C++.This can be overridden with thePY_CXX_CONST macro.

Changed in version 3.6:Added support forpositional-only parameters.

Changed in version 3.13:Thekeywords parameter has now typechar*const* in C andconstchar*const* in C++, instead ofchar**.Added support for non-ASCII keyword parameter names.

intPyArg_VaParseTupleAndKeywords(PyObject*args,PyObject*kw,constchar*format,char*const*keywords,va_listvargs)¶

Part of theStable ABI.

Identical toPyArg_ParseTupleAndKeywords(), except that it accepts ava_list rather than a variable number of arguments.

intPyArg_ValidateKeywordArguments(PyObject*)¶

Part of theStable ABI.

Ensure that the keys in the keywords argument dictionary are strings. Thisis only needed ifPyArg_ParseTupleAndKeywords() is not used, since thelatter already does this check.

Added in version 3.2.

intPyArg_Parse(PyObject*args,constchar*format,...)¶

Part of theStable ABI.

Parse the parameter of a function that takes a single positional parameterinto a local variable. Returns true on success; on failure, it returnsfalse and raises the appropriate exception.

Example:

// Function using METH_O calling conventionstaticPyObject*my_function(PyObject*module,PyObject*arg){intvalue;if(!PyArg_Parse(arg,"i:my_function",&value)){returnNULL;}// ... use value ...}

intPyArg_UnpackTuple(PyObject*args,constchar*name,Py_ssize_tmin,Py_ssize_tmax,...)¶

Part of theStable ABI.

A simpler form of parameter retrieval which does not use a format string tospecify the types of the arguments. Functions which use this method to retrievetheir parameters should be declared asMETH_VARARGS in function ormethod tables. The tuple containing the actual parameters should be passed asargs; it must actually be a tuple. The length of the tuple must be at leastmin and no more thanmax;min andmax may be equal. Additionalarguments must be passed to the function, each of which should be a pointer to aPyObject* variable; these will be filled in with the values fromargs; they will containborrowed references.The variables which correspondto optional parameters not given byargs will not be filled in; these shouldbe initialized by the caller. This function returns true on success and false ifargs is not a tuple or contains the wrong number of elements; an exceptionwill be set if there was a failure.

This is an example of the use of this function, taken from the sources for the_weakref helper module for weak references:

staticPyObject*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);}returnresult;}

The call toPyArg_UnpackTuple() in this example is entirely equivalent tothis call toPyArg_ParseTuple():

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

PY_CXX_CONST¶

The value to be inserted, if any, beforechar*const*in thekeywords parameter declaration ofPyArg_ParseTupleAndKeywords() andPyArg_VaParseTupleAndKeywords().Default empty for C andconst for C++(constchar*const*).To override, define it to the desired value before includingPython.h.

Added in version 3.13.