Bytes Objects

These functions raiseTypeError when expecting a bytes parameter andcalled with a non-bytes parameter.

typePyBytesObject

This subtype ofPyObject represents a Python bytes object.

PyTypeObjectPyBytes_Type
Part of theStable ABI.

This instance ofPyTypeObject represents the Python bytes type; itis the same object asbytes in the Python layer.

intPyBytes_Check(PyObject*o)

Return true if the objecto is a bytes object or an instance of a subtypeof the bytes type. This function always succeeds.

intPyBytes_CheckExact(PyObject*o)

Return true if the objecto is a bytes object, but not an instance of asubtype of the bytes type. This function always succeeds.

PyObject*PyBytes_FromString(constchar*v)
Return value: New reference. Part of theStable ABI.

Return a new bytes object with a copy of the stringv as value on success,andNULL on failure. The parameterv must not beNULL; it will not bechecked.

PyObject*PyBytes_FromStringAndSize(constchar*v,Py_ssize_tlen)
Return value: New reference. Part of theStable ABI.

Return a new bytes object with a copy of the stringv as value and lengthlen on success, andNULL on failure. Ifv isNULL, the contents ofthe bytes object are uninitialized.

PyObject*PyBytes_FromFormat(constchar*format,...)
Return value: New reference. Part of theStable ABI.

Take a Cprintf()-styleformat string and a variable number ofarguments, calculate the size of the resulting Python bytes object and returna bytes object with the values formatted into it. The variable argumentsmust be C types and must correspond exactly to the format characters in theformat string. The following format characters are allowed:

Format Characters

Type

Comment

%%

n/a

The literal % character.

%c

int

A single byte,represented as a C int.

%d

int

Equivalent toprintf("%d").[1]

%u

unsigned int

Equivalent toprintf("%u").[1]

%ld

long

Equivalent toprintf("%ld").[1]

%lu

unsigned long

Equivalent toprintf("%lu").[1]

%zd

Py_ssize_t

Equivalent toprintf("%zd").[1]

%zu

size_t

Equivalent toprintf("%zu").[1]

%i

int

Equivalent toprintf("%i").[1]

%x

int

Equivalent toprintf("%x").[1]

%s

const char*

A null-terminated C characterarray.

%p

const void*

The hex representation of a Cpointer. Mostly equivalent toprintf("%p") except thatit is guaranteed to start withthe literal0x regardlessof what the platform’sprintf yields.

An unrecognized format character causes all the rest of the format string to becopied as-is to the result object, and any extra arguments discarded.

[1](1,2,3,4,5,6,7,8)

For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversionflag has effect even when a precision is given.

PyObject*PyBytes_FromFormatV(constchar*format,va_listvargs)
Return value: New reference. Part of theStable ABI.

Identical toPyBytes_FromFormat() except that it takes exactly twoarguments.

PyObject*PyBytes_FromObject(PyObject*o)
Return value: New reference. Part of theStable ABI.

Return the bytes representation of objecto that implements the bufferprotocol.

Py_ssize_tPyBytes_Size(PyObject*o)
Part of theStable ABI.

Return the length of the bytes in bytes objecto.

Py_ssize_tPyBytes_GET_SIZE(PyObject*o)

Similar toPyBytes_Size(), but without error checking.

char*PyBytes_AsString(PyObject*o)
Part of theStable ABI.

Return a pointer to the contents ofo. The pointerrefers to the internal buffer ofo, which consists oflen(o)+1bytes. The last byte in the buffer is always null, regardless ofwhether there are any other null bytes. The data must not bemodified in any way, unless the object was just created usingPyBytes_FromStringAndSize(NULL,size). It must not be deallocated. Ifo is not a bytes object at all,PyBytes_AsString() returnsNULLand raisesTypeError.

char*PyBytes_AS_STRING(PyObject*string)

Similar toPyBytes_AsString(), but without error checking.

intPyBytes_AsStringAndSize(PyObject*obj,char**buffer,Py_ssize_t*length)
Part of theStable ABI.

Return the null-terminated contents of the objectobjthrough the output variablesbuffer andlength.Returns0 on success.

Iflength isNULL, the bytes objectmay not contain embedded null bytes;if it does, the function returns-1 and aValueError is raised.

The buffer refers to an internal buffer ofobj, which includes anadditional null byte at the end (not counted inlength). The datamust not be modified in any way, unless the object was just created usingPyBytes_FromStringAndSize(NULL,size). It must not be deallocated. Ifobj is not a bytes object at all,PyBytes_AsStringAndSize()returns-1 and raisesTypeError.

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

voidPyBytes_Concat(PyObject**bytes,PyObject*newpart)
Part of theStable ABI.

Create a new bytes object in*bytes containing the contents ofnewpartappended tobytes; the caller will own the new reference. The reference tothe old value ofbytes will be stolen. If the new object cannot becreated, the old reference tobytes will still be discarded and the valueof*bytes will be set toNULL; the appropriate exception will be set.

voidPyBytes_ConcatAndDel(PyObject**bytes,PyObject*newpart)
Part of theStable ABI.

Create a new bytes object in*bytes containing the contents ofnewpartappended tobytes. This version releases thestrong referencetonewpart (i.e. decrements its reference count).

int_PyBytes_Resize(PyObject**bytes,Py_ssize_tnewsize)

Resize a bytes object.newsize will be the new length of the bytes object.You can think of it as creating a new bytes object and destroying the oldone, only more efficiently.Pass the address of anexisting bytes object as an lvalue (it may be written into), and the new sizedesired. On success,*bytes holds the resized bytes object and0 isreturned; the address in*bytes may differ from its input value. If thereallocation fails, the original bytes object at*bytes is deallocated,*bytes is set toNULL,MemoryError is set, and-1 isreturned.