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.

In general, when a format sets a pointer to a buffer, the buffer ismanaged by the corresponding Python object, and the buffer sharesthe lifetime of this object. You won’t have to release any memory yourself.The only exceptions arees,es#,et andet#.

However, when aPy_buffer structure gets filled, the underlyingbuffer is locked so that the caller can subsequently use the buffer eveninside aPy_BEGIN_ALLOW_THREADS block without the risk of mutable databeing resized or destroyed. As a result,you have to callPyBuffer_Release() after you have finished processing the data (orin any early abort case).

Unless otherwise stated, buffers are not NUL-terminated.

Some formats require a read-onlybytes-like object, and set apointer instead of a buffer structure. They work by checking thatthe object’sPyBufferProcs.bf_releasebuffer field isNULL,which disallows mutable objects such asbytearray.

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 *, int orPy_ssize_t]

Likes*, except that it doesn’t accept mutable objects.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 *, int orPy_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 a characterstring; 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 *, int orPy_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) [const Py_UNICODE *]

Convert a Python Unicode object to a C pointer to a NUL-terminated buffer ofUnicode characters. You must pass the address of aPy_UNICODEpointer variable, which will be filled with the pointer to an existingUnicode buffer. Please note that the width of aPy_UNICODEcharacter depends on compilation options (it is either 16 or 32 bits).The Python string must not contain embedded null code points; if it does,aValueError exception is raised.

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

Deprecated since version 3.3, will be removed in version 3.12:Part of the old-stylePy_UNICODE API; please migrate to usingPyUnicode_AsWideCharString().

u# (str) [const Py_UNICODE *, int orPy_ssize_t]

This variant onu stores into two C variables, the first one a pointer to aUnicode data buffer, the second one its length. This variant allowsnull code points.

Deprecated since version 3.3, will be removed in version 3.12:Part of the old-stylePy_UNICODE API; please migrate to usingPyUnicode_AsWideCharString().

Z (str orNone) [const Py_UNICODE *]

Likeu, but the Python object may also beNone, in which case thePy_UNICODE pointer is set toNULL.

Deprecated since version 3.3, will be removed in version 3.12:Part of the old-stylePy_UNICODE API; please migrate to usingPyUnicode_AsWideCharString().

Z# (str orNone) [const Py_UNICODE *, int orPy_ssize_t]

Likeu#, but the Python object may also beNone, in which case thePy_UNICODE pointer is set toNULL.

Deprecated since version 3.3, will be removed in version 3.12:Part of the old-stylePy_UNICODE API; please migrate to usingPyUnicode_AsWideCharString().

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, int orPy_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, int orPy_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¶

b (int) [unsigned char]

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

B (int) [unsigned char]

Convert a Python integer to a tiny int 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. The object’s referencecount 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,anything]

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.

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.

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

It is possible to pass “long” integers (integers whose value exceeds theplatform’sLONG_MAX) however no proper range checking is done — themost significant bits are silently truncated when the receiving field is toosmall to receive the value (actually, the semantics are inherited from downcastsin C — your mileage may vary).

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.

New 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 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, const char *format, ...)¶

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, const char *format, va_list vargs)¶

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

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

Parse the parameters of a function that takes both positional and keywordparameters into local variables. Thekeywords argument is aNULL-terminated array of keyword parameter names. Empty names denotepositional-only parameters.Returns true on success; on failure, it returns false and raises theappropriate exception.

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

intPyArg_VaParseTupleAndKeywords(PyObject *args,PyObject *kw, const char *format, char *keywords[], va_list vargs)¶

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

intPyArg_ValidateKeywordArguments(PyObject *)¶

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.

New in version 3.2.

intPyArg_Parse(PyObject *args, const char *format, ...)¶

Function used to deconstruct the argument lists of “old-style” functions —these are functions which use theMETH_OLDARGS parameter parsingmethod, which has been removed in Python 3. This is not recommended for usein parameter parsing in new code, and most code in the standard interpreterhas been modified to no longer use this for that purpose. It does remain aconvenient way to decompose other tuples, however, and may continue to beused for that purpose.

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

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 contain borrowed 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)