Bytes Objects¶

These functions raiseTypeError when expecting a bytes parameter andcalled 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. 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(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.