1 .. highlightlang:: c 2 3 .. _bytesobjects: 4 5 Bytes Objects 6 ------------- 7 8 These functions raise :exc:`TypeError` when expecting a bytes parameter and are 9 called with a non-bytes parameter. 10 11 .. index:: 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. 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. 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 .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated 62 .. % because not all compilers support the %z width modifier -- we fake it 63 .. % when necessary via interpolating PY_FORMAT_SIZE_T. 64 65 .. tabularcolumns:: |l|l|L| 66 67 +-------------------+---------------+--------------------------------+ 68 | Format Characters | Type | Comment | 69 +===================+===============+================================+ 70 | :attr:`%%` | *n/a* | The literal % character. | 71 +-------------------+---------------+--------------------------------+ 72 | :attr:`%c` | int | A single byte, | 73 | | | represented as a C int. | 74 +-------------------+---------------+--------------------------------+ 75 | :attr:`%d` | int | Exactly equivalent to | 76 | | | ``printf("%d")``. | 77 +-------------------+---------------+--------------------------------+ 78 | :attr:`%u` | unsigned int | Exactly equivalent to | 79 | | | ``printf("%u")``. | 80 +-------------------+---------------+--------------------------------+ 81 | :attr:`%ld` | long | Exactly equivalent to | 82 | | | ``printf("%ld")``. | 83 +-------------------+---------------+--------------------------------+ 84 | :attr:`%lu` | unsigned long | Exactly equivalent to | 85 | | | ``printf("%lu")``. | 86 +-------------------+---------------+--------------------------------+ 87 | :attr:`%zd` | Py_ssize_t | Exactly equivalent to | 88 | | | ``printf("%zd")``. | 89 +-------------------+---------------+--------------------------------+ 90 | :attr:`%zu` | size_t | Exactly equivalent to | 91 | | | ``printf("%zu")``. | 92 +-------------------+---------------+--------------------------------+ 93 | :attr:`%i` | int | Exactly equivalent to | 94 | | | ``printf("%i")``. | 95 +-------------------+---------------+--------------------------------+ 96 | :attr:`%x` | int | Exactly equivalent to | 97 | | | ``printf("%x")``. | 98 +-------------------+---------------+--------------------------------+ 99 | :attr:`%s` | char\* | A null-terminated C character | 100 | | | array. | 101 +-------------------+---------------+--------------------------------+ 102 | :attr:`%p` | void\* | The hex representation of a C | 103 | | | pointer. Mostly equivalent to | 104 | | | ``printf("%p")`` except that | 105 | | | it is guaranteed to start with | 106 | | | the literal ``0x`` regardless | 107 | | | of what the platform's | 108 | | | ``printf`` yields. | 109 +-------------------+---------------+--------------------------------+ 110 111 An unrecognized format character causes all the rest of the format string to be 112 copied as-is to the result object, and any extra arguments discarded. 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 Macro form of :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 Macro form of :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 159 If *length* is *NULL*, the bytes object 160 may not contain embedded null bytes; 161 if it does, the function returns ``-1`` and a :exc:`ValueError` is raised. 162 163 The buffer refers to an internal buffer of *obj*, which includes an 164 additional null byte at the end (not counted in *length*). The data 165 must not be modified in any way, unless the object was just created using 166 ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If 167 *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` 168 returns ``-1`` and raises :exc:`TypeError`. 169 170 .. versionchanged:: 3.5 171 Previously, :exc:`TypeError` was raised when embedded null bytes were 172 encountered in the bytes object. 173 174 175 .. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart) 176 177 Create a new bytes object in *\*bytes* containing the contents of *newpart* 178 appended to *bytes*; the caller will own the new reference. The reference to 179 the old value of *bytes* will be stolen. If the new object cannot be 180 created, the old reference to *bytes* will still be discarded and the value 181 of *\*bytes* will be set to *NULL*; the appropriate exception will be set. 182 183 184 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart) 185 186 Create a new bytes object in *\*bytes* containing the contents of *newpart* 187 appended to *bytes*. This version decrements the reference count of 188 *newpart*. 189 190 191 .. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize) 192 193 A way to resize a bytes object even though it is "immutable". Only use this 194 to build up a brand new bytes object; don't use this if the bytes may already 195 be known in other parts of the code. It is an error to call this function if 196 the refcount on the input bytes object is not one. Pass the address of an 197 existing bytes object as an lvalue (it may be written into), and the new size 198 desired. On success, *\*bytes* holds the resized bytes object and ``0`` is 199 returned; the address in *\*bytes* may differ from its input value. If the 200 reallocation fails, the original bytes object at *\*bytes* is deallocated, 201 *\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is 202 returned. 203
