Bytes Objects

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

PyBytesObject

This subtype ofPyObject represents a Python bytes object.

PyTypeObjectPyBytes_Type

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.

intPyBytes_CheckExact(PyObject *o)

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

PyObject*PyBytes_FromString(const char *v)
Return value: New reference.

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(const char *v, Py_ssize_t len)
Return value: New reference.

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(const char *format, ...)
Return value: New reference.

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(const char *format, va_list vargs)
Return value: New reference.

Identical toPyBytes_FromFormat() except that it takes exactly twoarguments.

PyObject*PyBytes_FromObject(PyObject *o)
Return value: New reference.

Return the bytes representation of objecto that implements the bufferprotocol.

Py_ssize_tPyBytes_Size(PyObject *o)

Return the length of the bytes in bytes objecto.

Py_ssize_tPyBytes_GET_SIZE(PyObject *o)

Macro form ofPyBytes_Size() but without error checking.

char*PyBytes_AsString(PyObject *o)

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)

Macro form ofPyBytes_AsString() but without error checking.

intPyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

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

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)

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)

Create a new bytes object in*bytes containing the contents ofnewpartappended tobytes. This version decrements the reference count ofnewpart.

int_PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

A way to resize a bytes object even though it is “immutable”. Only use thisto build up a brand new bytes object; don’t use this if the bytes may alreadybe known in other parts of the code. It is an error to call this function ifthe refcount on the input bytes object is not one. 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.