Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 14 | .. c:type:: PyBytesObject |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | This subtype of :c:type:`PyObject` represents a Python bytes object. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 17 | |
| 18 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 19 | .. c:var:: PyTypeObject PyBytes_Type |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 20 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 21 | This instance of :c:type:`PyTypeObject` represents the Python bytes type; it |
Georg Brandl | 2aff335 | 2010-10-17 10:59:41 +0000 | [diff] [blame] | 22 | is the same object as :class:`bytes` in the Python layer. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 23 | |
| 24 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 25 | .. c:function:: int PyBytes_Check(PyObject *o) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 31 | .. c:function:: int PyBytes_CheckExact(PyObject *o) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 37 | .. c:function:: PyObject* PyBytes_FromString(const char *v) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 44 | .. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 51 | .. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 52 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 53 | Take a C :c:func:`printf`\ -style *format* string and a variable number of |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 44ea77b | 2013-03-28 13:28:44 +0100 | [diff] [blame] | 65 | .. tabularcolumns:: |l|l|L| |
| 66 | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 67 | +-------------------+---------------+--------------------------------+ |
| 68 | | Format Characters | Type | Comment | |
| 69 | +===================+===============+================================+ |
| 70 | | :attr:`%%` | *n/a* | The literal % character. | |
| 71 | +-------------------+---------------+--------------------------------+ |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 72 | | :attr:`%c` | int | A single byte, | |
| 73 | | | | represented as a C int. | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 74 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 75 | | :attr:`%d` | int | Equivalent to | |
| 76 | | | | ``printf("%d")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 77 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 78 | | :attr:`%u` | unsigned int | Equivalent to | |
| 79 | | | | ``printf("%u")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 80 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 81 | | :attr:`%ld` | long | Equivalent to | |
| 82 | | | | ``printf("%ld")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 83 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 84 | | :attr:`%lu` | unsigned long | Equivalent to | |
| 85 | | | | ``printf("%lu")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 86 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 87 | | :attr:`%zd` | Py_ssize_t | Equivalent to | |
| 88 | | | | ``printf("%zd")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 89 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 90 | | :attr:`%zu` | size_t | Equivalent to | |
| 91 | | | | ``printf("%zu")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 92 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 93 | | :attr:`%i` | int | Equivalent to | |
| 94 | | | | ``printf("%i")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 95 | +-------------------+---------------+--------------------------------+ |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 96 | | :attr:`%x` | int | Equivalent to | |
| 97 | | | | ``printf("%x")``. [1]_ | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 98 | +-------------------+---------------+--------------------------------+ |
Serhiy Storchaka | 84b8e92 | 2017-03-30 10:01:03 +0300 | [diff] [blame] | 99 | | :attr:`%s` | const char\* | A null-terminated C character | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 100 | | | | array. | |
| 101 | +-------------------+---------------+--------------------------------+ |
Serhiy Storchaka | 84b8e92 | 2017-03-30 10:01:03 +0300 | [diff] [blame] | 102 | | :attr:`%p` | const void\* | The hex representation of a C | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 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 |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 112 | copied as-is to the result object, and any extra arguments discarded. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 113 | |
Louie Lu | 88c38b3 | 2017-04-27 11:36:35 +0800 | [diff] [blame] | 114 | .. [1] For integer specifiers (d, u, ld, lu, zd, zu, i, x): the 0-conversion |
| 115 | flag has effect even when a precision is given. |
| 116 | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 117 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 118 | .. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 119 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 120 | Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 121 | arguments. |
| 122 | |
| 123 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 124 | .. c:function:: PyObject* PyBytes_FromObject(PyObject *o) |
Benjamin Peterson | c15a073 | 2008-08-26 16:46:47 +0000 | [diff] [blame] | 125 | |
| 126 | Return the bytes representation of object *o* that implements the buffer |
| 127 | protocol. |
| 128 | |
| 129 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 130 | .. c:function:: Py_ssize_t PyBytes_Size(PyObject *o) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 131 | |
| 132 | Return the length of the bytes in bytes object *o*. |
| 133 | |
| 134 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 135 | .. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 136 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 137 | Macro form of :c:func:`PyBytes_Size` but without error checking. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 138 | |
| 139 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 140 | .. c:function:: char* PyBytes_AsString(PyObject *o) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 141 | |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 142 | Return a pointer to the contents of *o*. The pointer |
| 143 | refers to the internal buffer of *o*, which consists of ``len(o) + 1`` |
| 144 | bytes. The last byte in the buffer is always null, regardless of |
| 145 | whether there are any other null bytes. The data must not be |
| 146 | modified in any way, unless the object was just created using |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 147 | ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 148 | *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL* |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 149 | and raises :exc:`TypeError`. |
| 150 | |
| 151 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 152 | .. c:function:: char* PyBytes_AS_STRING(PyObject *string) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 153 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 154 | Macro form of :c:func:`PyBytes_AsString` but without error checking. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 155 | |
| 156 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 157 | .. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 158 | |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 159 | Return the null-terminated contents of the object *obj* |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 160 | through the output variables *buffer* and *length*. |
| 161 | |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 162 | If *length* is *NULL*, the bytes object |
| 163 | may not contain embedded null bytes; |
Serhiy Storchaka | 6f379f4 | 2016-07-12 09:14:15 +0300 | [diff] [blame] | 164 | if it does, the function returns ``-1`` and a :exc:`ValueError` is raised. |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 165 | |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 166 | The buffer refers to an internal buffer of *obj*, which includes an |
| 167 | additional null byte at the end (not counted in *length*). The data |
| 168 | must not be modified in any way, unless the object was just created using |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 169 | ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 170 | *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize` |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 171 | returns ``-1`` and raises :exc:`TypeError`. |
| 172 | |
Serhiy Storchaka | 6f379f4 | 2016-07-12 09:14:15 +0300 | [diff] [blame] | 173 | .. versionchanged:: 3.5 |
| 174 | Previously, :exc:`TypeError` was raised when embedded null bytes were |
| 175 | encountered in the bytes object. |
| 176 | |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 177 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 178 | .. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 179 | |
| 180 | Create a new bytes object in *\*bytes* containing the contents of *newpart* |
| 181 | appended to *bytes*; the caller will own the new reference. The reference to |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 182 | the old value of *bytes* will be stolen. If the new object cannot be |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 183 | created, the old reference to *bytes* will still be discarded and the value |
| 184 | of *\*bytes* will be set to *NULL*; the appropriate exception will be set. |
| 185 | |
| 186 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 187 | .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 188 | |
R David Murray | 0a560a1 | 2015-05-13 20:31:53 -0400 | [diff] [blame] | 189 | Create a new bytes object in *\*bytes* containing the contents of *newpart* |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 190 | appended to *bytes*. This version decrements the reference count of |
| 191 | *newpart*. |
| 192 | |
| 193 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 194 | .. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize) |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 195 | |
| 196 | A way to resize a bytes object even though it is "immutable". Only use this |
| 197 | to build up a brand new bytes object; don't use this if the bytes may already |
| 198 | be known in other parts of the code. It is an error to call this function if |
| 199 | the refcount on the input bytes object is not one. Pass the address of an |
| 200 | existing bytes object as an lvalue (it may be written into), and the new size |
| 201 | desired. On success, *\*bytes* holds the resized bytes object and ``0`` is |
| 202 | returned; the address in *\*bytes* may differ from its input value. If the |
| 203 | reallocation fails, the original bytes object at *\*bytes* is deallocated, |
Berker Peksag | 4a72a7b | 2016-09-16 17:31:06 +0300 | [diff] [blame] | 204 | *\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is |
Benjamin Peterson | dae32c1 | 2008-05-26 15:01:55 +0000 | [diff] [blame] | 205 | returned. |