Debian Codegraph @

Doc/c-api/bytes.rst

raw
1 .. highlight:: c
2
3 .. _bytesobjects:
4
5 Bytes Objects
6 -------------
7
8 These functions raise :exc:`TypeError` when expecting a bytes parameter and
9 called 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 .. note::
127 If the object implements the buffer protocol, then the buffer
128 must not be mutated while the bytes object is being created.
129
130
131 .. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
132
133 Return the length of the bytes in bytes object *o*.
134
135
136 .. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
137
138 Similar to :c:func:`PyBytes_Size`, but without error checking.
139
140
141 .. c:function:: char* PyBytes_AsString(PyObject *o)
142
143 Return a pointer to the contents of *o*. The pointer
144 refers to the internal buffer of *o*, which consists of ``len(o) + 1``
145 bytes. The last byte in the buffer is always null, regardless of
146 whether there are any other null bytes. The data must not be
147 modified in any way, unless the object was just created using
148 ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
149 *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
150 and raises :exc:`TypeError`.
151
152
153 .. c:function:: char* PyBytes_AS_STRING(PyObject *string)
154
155 Similar to :c:func:`PyBytes_AsString`, but without error checking.
156
157
158 .. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
159
160 Return the null-terminated contents of the object *obj*
161 through the output variables *buffer* and *length*.
162 Returns ``0`` on success.
163
164 If *length* is ``NULL``, the bytes object
165 may not contain embedded null bytes;
166 if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
167
168 The buffer refers to an internal buffer of *obj*, which includes an
169 additional null byte at the end (not counted in *length*). The data
170 must not be modified in any way, unless the object was just created using
171 ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
172 *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
173 returns ``-1`` and raises :exc:`TypeError`.
174
175 .. versionchanged:: 3.5
176 Previously, :exc:`TypeError` was raised when embedded null bytes were
177 encountered in the bytes object.
178
179
180 .. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
181
182 Create a new bytes object in *\*bytes* containing the contents of *newpart*
183 appended to *bytes*; the caller will own the new reference. The reference to
184 the old value of *bytes* will be stolen. If the new object cannot be
185 created, the old reference to *bytes* will still be discarded and the value
186 of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
187
188 .. note::
189 If *newpart* implements the buffer protocol, then the buffer
190 must not be mutated while the new bytes object is being created.
191
192 .. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
193
194 Create a new bytes object in *\*bytes* containing the contents of *newpart*
195 appended to *bytes*. This version releases the :term:`strong reference`
196 to *newpart* (i.e. decrements its reference count).
197
198 .. note::
199 If *newpart* implements the buffer protocol, then the buffer
200 must not be mutated while the new bytes object is being created.
201
202
203 .. c:function:: PyObject* PyBytes_Join(PyObject *sep, PyObject *iterable)
204
205 Similar to ``sep.join(iterable)`` in Python.
206
207 *sep* must be Python :class:`bytes` object.
208 (Note that :c:func:`PyUnicode_Join` accepts ``NULL`` separator and treats
209 it as a space, whereas :c:func:`PyBytes_Join` doesn't accept ``NULL``
210 separator.)
211
212 *iterable* must be an iterable object yielding objects that implement the
213 :ref:`buffer protocol <bufferobjects>`.
214
215 On success, return a new :class:`bytes` object.
216 On error, set an exception and return ``NULL``.
217
218 .. versionadded:: 3.14
219
220 .. note::
221 If *iterable* objects implement the buffer protocol, then the buffers
222 must not be mutated while the new bytes object is being created.
223
224 .. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
225
226 Resize a bytes object. *newsize* will be the new length of the bytes object.
227 You can think of it as creating a new bytes object and destroying the old
228 one, only more efficiently.
229 Pass the address of an
230 existing bytes object as an lvalue (it may be written into), and the new size
231 desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
232 returned; the address in *\*bytes* may differ from its input value. If the
233 reallocation fails, the original bytes object at *\*bytes* is deallocated,
234 *\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
235 returned.
236
237
238 .. c:function:: PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
239
240 Get the string representation of *bytes*. This function is currently used to
241 implement :meth:`!bytes.__repr__` in Python.
242
243 This function does not do type checking; it is undefined behavior to pass
244 *bytes* as a non-bytes object or ``NULL``.
245
246 If *smartquotes* is true, the representation will use a double-quoted string
247 instead of single-quoted string when single-quotes are present in *bytes*.
248 For example, the byte string ``'Python'`` would be represented as
249 ``b"'Python'"`` when *smartquotes* is true, or ``b'\'Python\''`` when it is
250 false.
251
252 On success, this function returns a :term:`strong reference` to a
253 :class:`str` object containing the representation. On failure, this
254 returns ``NULL`` with an exception set.
255
256
257 .. c:function:: PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)
258
259 Unescape a backslash-escaped string *s*. *s* must not be ``NULL``.
260 *len* must be the size of *s*.
261
262 *errors* must be one of ``"strict"``, ``"replace"``, or ``"ignore"``. If
263 *errors* is ``NULL``, then ``"strict"`` is used by default.
264
265 On success, this function returns a :term:`strong reference` to a Python
266 :class:`bytes` object containing the unescaped string. On failure, this
267 function returns ``NULL`` with an exception set.
268
269 .. versionchanged:: 3.9
270 *unicode* and *recode_encoding* are now unused.