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 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 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, ...)¶

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 character,represented as an C int.
%d	int	Exactly equivalent toprintf("%d").
%u	unsigned int	Exactly equivalent toprintf("%u").
%ld	long	Exactly equivalent toprintf("%ld").
%lu	unsigned long	Exactly equivalent toprintf("%lu").
%zd	Py_ssize_t	Exactly equivalent toprintf("%zd").
%zu	size_t	Exactly equivalent toprintf("%zu").
%i	int	Exactly equivalent toprintf("%i").
%x	int	Exactly equivalent toprintf("%x").
%s	char*	A null-terminated C characterarray.
%p	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 string, and any extra arguments discarded.

PyObject*PyBytes_FromFormatV(const char *format, va_list vargs)¶

Identical toPyBytes_FromFormat() except that it takes exactly twoarguments.

PyObject*PyBytes_FromObject(PyObject *o)¶

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 NUL-terminated representation of the contents ofo. The pointerrefers to the internal buffer ofo, not a copy. The data must not bemodified in any way, unless the string was just created usingPyBytes_FromStringAndSize(NULL,size). It must not be deallocated. Ifo is not a string 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 a NUL-terminated representation of the contents of the objectobjthrough the output variablesbuffer andlength.

Iflength isNULL, the resulting buffer may not contain NUL characters;if it does, the function returns-1 and aTypeError is raised.

The buffer refers to an internal string buffer ofobj, not a copy. The datamust not be modified in any way, unless the string was just created usingPyBytes_FromStringAndSize(NULL,size). It must not be deallocated. Ifstring is not a string object at all,PyBytes_AsStringAndSize()returns-1 and raisesTypeError.

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 string 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 string 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, a memory exception is set, and-1 isreturned.