1.. highlight:: c 2 3.. _bytesobjects: 4 5Bytes Objects 6------------- 7 8These functions raise :exc:`TypeError` when expecting a bytes parameter and 9called with a non-bytes parameter. 10 11.. index:: pair: object; bytes 12 13 14.. c:type:: PyBytesObject 15 16 This subtype of :c:type:`PyObject` represents a Python bytes object. 17 18 19.. c:var:: PyTypeObject PyBytes_Type 20 21 This instance of :c:type:`PyTypeObject` represents the Python bytes type; it 22 is the same object as :class:`bytes` in the Python layer. 23 24 25.. c:function:: int PyBytes_Check(PyObject *o) 26 27 Return true if the object *o* is a bytes object or an instance of a subtype 28 of the bytes type. This function always succeeds. 29 30 31.. c:function:: int PyBytes_CheckExact(PyObject *o) 32 33 Return true if the object *o* is a bytes object, but not an instance of a 34 subtype of the bytes type. This function always succeeds. 35 36 37.. c:function:: PyObject* PyBytes_FromString(const char *v) 38 39 Return a new bytes object with a copy of the string *v* as value on success, 40 and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be 41 checked. 42 43 44.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len) 45 46 Return a new bytes object with a copy of the string *v* as value and length 47 *len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of 48 the bytes object are uninitialized. 49 50 51.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...) 52 53 Take a C :c:func:`printf`\ -style *format* string and a variable number of 54 arguments, calculate the size of the resulting Python bytes object and return 55 a bytes object with the values formatted into it. The variable arguments 56 must be C types and must correspond exactly to the format characters in the 57 *format* string. The following format characters are allowed: 58 59 .. % XXX: This should be exactly the same as the table in PyErr_Format. 60 .. % One should just refer to the other. 61 62 .. tabularcolumns:: |l|l|L| 63 64 +-------------------+---------------+--------------------------------+ 65 | Format Characters | Type | Comment | 66 +===================+===============+================================+ 67 | ``%%`` | *n/a* | The literal % character. | 68 +-------------------+---------------+--------------------------------+ 69 | ``%c`` | int | A single byte, | 70 | | | represented as a C int. | 71 +-------------------+---------------+--------------------------------+ 72 | ``%d`` | int | Equivalent to | 73 | | | ``printf("%d")``. [1]_ | 74 +-------------------+---------------+--------------------------------+ 75 | ``%u`` | unsigned int | Equivalent to | 76 | | | ``printf("%u")``. [1]_ | 77 +-------------------+---------------+--------------------------------+ 78 | ``%ld`` | long | Equivalent to | 79 | | | ``printf("%ld")``. [1]_ | 80 +-------------------+---------------+--------------------------------+ 81 | ``%lu`` | unsigned long | Equivalent to | 82 | | | ``printf("%lu")``. [1]_ | 83 +-------------------+---------------+--------------------------------+ 84 | ``%zd`` | :c:type:`\ | Equivalent to | 85 | | Py_ssize_t` | ``printf("%zd")``. [1]_ | 86 +-------------------+---------------+--------------------------------+ 87 | ``%zu`` | size_t | Equivalent to | 88 | | | ``printf("%zu")``. [1]_ | 89 +-------------------+---------------+--------------------------------+ 90 | ``%i`` | int | Equivalent to | 91 | | | ``printf("%i")``. [1]_ | 92 +-------------------+---------------+--------------------------------+ 93 | ``%x`` | int | Equivalent to | 94 | | | ``printf("%x")``. [1]_ | 95 +-------------------+---------------+--------------------------------+ 96 | ``%s`` | const char\* | A null-terminated C character | 97 | | | array. | 98 +-------------------+---------------+--------------------------------+ 99 | ``%p`` | const void\* | The hex representation of a C | 100 | | | pointer. Mostly equivalent to | 101 | | | ``printf("%p")`` except that | 102 | | | it is guaranteed to start with | 103 | | | the literal ``0x`` regardless | 104 | | | of what the platform's | 105 | | | ``printf`` yields. | 106 +-------------------+---------------+--------------------------------+ 107 108 An unrecognized format character causes all the rest of the format string to be 109 copied as-is to the result object, and any extra arguments discarded. 110 111 .. [1] For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion 112 flag has effect even when a precision is given. 113 114 115.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs) 116 117 Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two 118 arguments. 119 120 121.. c:function:: PyObject* PyBytes_FromObject(PyObject *o) 122 123 Return the bytes representation of object *o* that implements the buffer 124 protocol. 125 126 127.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o) 128 129 Return the length of the bytes in bytes object *o*. 130 131 132.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o) 133 134 Similar to :c:func:`PyBytes_Size`, but without error checking. 135 136 137.. c:function:: char* PyBytes_AsString(PyObject *o) 138 139 Return a pointer to the contents of *o*. The pointer 140 refers to the internal buffer of *o*, which consists of ``len(o) + 1`` 141 bytes. The last byte in the buffer is always null, regardless of 142 whether there are any other null bytes. The data must not be 143 modified in any way, unless the object was just created using 144 ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If 145 *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL`` 146 and raises :exc:`TypeError`. 147 148 149.. c:function:: char* PyBytes_AS_STRING(PyObject *string) 150 151 Similar to :c:func:`PyBytes_AsString`, but without error checking. 152 153 154.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) 155 156 Return the null-terminated contents of the object *obj* 157 through the output variables *buffer* and *length*. 158 Returns ``0`` on success. 159 160 If *length* is ``NULL``, the bytes object 161 may not contain embedded null bytes; 162 if it does, the function returns ``-1`` and a :exc:`ValueError` is raised. 163 164 The buffer refers to an internal buffer of *obj*, which includes an 165 additional null byte at the end (not counted in *length*). The data 166 must not be modified in any way, unless the object was just created using 167 ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If 168 *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` 169 returns ``-1`` and raises :exc:`TypeError`. 170 171 .. versionchanged:: 3.5 172 Previously, :exc:`TypeError` was raised when embedded null bytes were 173 encountered in the bytes object. 174 175 176.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart) 177 178 Create a new bytes object in *\*bytes* containing the contents of *newpart* 179 appended to *bytes*; the caller will own the new reference. The reference to 180 the old value of *bytes* will be stolen. If the new object cannot be 181 created, the old reference to *bytes* will still be discarded and the value 182 of *\*bytes* will be set to ``NULL``; the appropriate exception will be set. 183 184 185.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart) 186 187 Create a new bytes object in *\*bytes* containing the contents of *newpart* 188 appended to *bytes*. This version releases the :term:`strong reference` 189 to *newpart* (i.e. decrements its reference count). 190 191 192.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize) 193 194 Resize a bytes object. *newsize* will be the new length of the bytes object. 195 You can think of it as creating a new bytes object and destroying the old 196 one, only more efficiently. 197 Pass the address of an 198 existing bytes object as an lvalue (it may be written into), and the new size 199 desired. On success, *\*bytes* holds the resized bytes object and ``0`` is 200 returned; the address in *\*bytes* may differ from its input value. If the 201 reallocation fails, the original bytes object at *\*bytes* is deallocated, 202 *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is 203 returned. 204