8000 gh-85275: Remove old buffer APIs (#105137) · python/cpython@37498fc · GitHub
[go: up one dir, main page]
Skip to content

Commit 37498fc

Browse files
methanevstinner
methane
and
vstinner
authored
gh-85275: Remove old buffer APIs (#105137)
They are now abi-only. Co-authored-by: Victor Stinner <vstinner@python.org>
1 parent ef30093 commit 37498fc

File tree

9 files changed

+79
-133
lines changed

9 files changed

+79
-133
lines changed

‎Doc/c-api/abstract.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,3 @@ but whose items have not been set to some non-\ ``NULL`` value yet.
2424
mapping.rst
2525
iter.rst
2626
buffer.rst
27-
objbuffer.rst

‎Doc/c-api/objbuffer.rst

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎Doc/data/refcounts.dat

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1578,21 +1578,6 @@ PyOS_FSPath:PyObject*:path:0:
15781578
PyObject_ASCII:PyObject*::+1:
15791579
PyObject_ASCII:PyObject*:o:0:
15801580

1581-
PyObject_AsCharBuffer:int:::
1582-
PyObject_AsCharBuffer:PyObject*:obj:0:
1583-
PyObject_AsCharBuffer:const char**:buffer::
1584-
PyObject_AsCharBuffer:Py_ssize_t*:buffer_len::
1585-
1586-
PyObject_AsReadBuffer:int:::
1587-
PyObject_AsReadBuffer:PyObject*:obj:0:
1588-
PyObject_AsReadBuffer:const void**:buffer::
1589-
PyObject_AsReadBuffer:Py_ssize_t*:buffer_len::
1590-
1591-
PyObject_AsWriteBuffer:int:::
1592-
PyObject_AsWriteBuffer:PyObject*:obj:0:
1593-
PyObject_AsWriteBuffer:void**:buffer::
1594-
PyObject_AsWriteBuffer:Py_ssize_t*:buffer_len::
1595-
15961581
PyObject_Bytes:PyObject*::+1:
15971582
PyObject_Bytes:PyObject*:o:0:
15981583

‎Doc/data/stable_abi.dat

Lines changed: 0 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Doc/whatsnew/3.13.rst

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -395,6 +395,42 @@ Removed
395395

396396
(Contributed by Victor Stinner in :gh:`105107`.)
397397

398+
* Remove old buffer protocols deprecated in Python 3.0. Use :ref:`bufferobjects` instead.
399+
400+
* :c:func:`!PyObject_CheckReadBuffer`: Use :c:func:`PyObject_CheckBuffer` to
401+
test if the object supports the buffer protocol.
402+
Note that :c:func:`PyObject_CheckBuffer` doesn't guarantee that
403+
:c:func:`PyObject_GetBuffer` will succeed.
404+
To test if the object is actually readable, see the next example
405+
of :c:func:`PyObject_GetBuffer`.
406+
407+
* :c:func:`!PyObject_AsCharBuffer`, :c:func:`!PyObject_AsReadBuffer`:
408+
:c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
409+
410+
.. code-block:: c
411+
412+
Py_buffer view;
413+
if (PyObject_GetBuffer(obj, &view, PyBUF_SIMPLE) < 0) {
414+
return NULL;
415+
}
416+
// Use `view.buf` and `view.len` to read from the buffer.
417+
// You may need to cast buf as `(const char*)view.buf`.
418+
PyBuffer_Release(&view);
419+
420+
* :c:func:`!PyObject_AsWriteBuffer`: Use
421+
:c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release` instead:
422+
423+
.. code-block:: c
424+
425+
Py_buffer view;
426+
if (PyObject_GetBuffer(obj, &view, PyBUF_WRITABLE) < 0) {
427+
return NULL;
428+
}
429+
// Use `view.buf` and `view.len` to write to the buffer.
430+
PyBuffer_Release(&view);
431+
432+
(Contributed by Inada Naoki in :gh:`85275`.)
433+
398434
* Remove the following old functions to configure the Python initialization,
399435
deprecated in Python 3.11:
400436

‎Include/abstract.h

Lines changed: 0 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -320,55 +320,6 @@ PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
320320
PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
321321

322322

323-
/* === Old Buffer API ============================================ */
324-
325-
/* FIXME: usage of these should all be replaced in Python itself
326-
but for backwards compatibility we will implement them.
327-
Their usage without a corresponding "unlock" mechanism
328-
may create issues (but they would already be there). */
329-
330-
/* Takes an arbitrary object which must support the (character, single segment)
331-
buffer interface and returns a pointer to a read-only memory location
332-
usable as character based input for subsequent processing.
333-
334-
Return 0 on success. buffer and buffer_len are only set in case no error
335-
occurs. Otherwise, -1 is returned and an exception set. */
336-
Py_DEPRECATED(3.0)
337-
PyAPI_FUNC(int) PyObject_AsCharBuffer(PyObject *obj,
338-
const char **buffer,
339-
Py_ssize_t *buffer_len);
340-
341-
/* Checks whether an arbitrary object supports the (character, single segment)
342-
buffer interface.
343-
344-
Returns 1 on success, 0 on failure. */
345-
Py_DEPRECATED(3.0) PyAPI_FUNC(int) PyObject_CheckReadBuffer(PyObject *obj);
346-
347-
/* Same as PyObject_AsCharBuffer() except that this API expects (readable,
348-
single segment) buffer interface and returns a pointer to a read-only memory
349-
location which can contain arbitrary data.
350-
351-
0 is returned on success. buffer and buffer_len are only set in case no
352-
error occurs. Otherwise, -1 is returned and an exception set. */
353-
Py_DEPRECATED(3.0)
354-
PyAPI_FUNC(int) PyObject_AsReadBuffer(PyObject *obj,
355-
const void **buffer,
356-
Py_ssize_t *buffer_len);
357-
358-
/* Takes an arbitrary object which must support the (writable, single segment)
359-
buffer interface and returns a pointer to a writable memory location in
360-
buffer of size 'buffer_len'.
361-
362-
Return 0 on success. buffer and buffer_len are only set in case no error
363-
occurs. Otherwise, -1 is returned and an exception set. */
364-
Py_DEPRECATED(3.0)
365-
PyAPI_FUNC(int) PyObject_AsWriteBuffer(PyObject *obj,
366-
void **buffer,
367-
Py_ssize_t *buffer_len);
368-
369-
370-
/* === New Buffer API ============================================ */
371-
372323
/* Takes an arbitrary object and returns the result of calling
373324
obj.__format__(format_spec). */
374325
PyAPI_FUNC(PyObject *) PyObject_Format(PyObject *obj,

‎Misc/NEWS.d/next/C API/2023-05-31-19-38-45.gh-issue-85275.doojgE.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
``PyObject_AsCharBuffer()``, ``PyObject_AsReadBuffer()``,
2+
``PyObject_CheckReadBuffer()``, and ``PyObject_AsWriteBuffer()`` are
3+
removed. Please migrate to new buffer protocol; :c:func:`PyObject_GetBuffer`
4+
and :c:func:`PyBuffer_Release`.

‎Misc/stable_abi.toml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1755,12 +1755,16 @@
17551755

17561756
[function.PyObject_AsCharBuffer]
17571757
added = '3.2'
1758+
abi_only = true
17581759
[function.PyObject_AsReadBuffer]
17591760
added = '3.2'
1761+
abi_only = true
17601762
[function.PyObject_AsWriteBuffer]
17611763
added = '3.2'
1764+
abi_only = true
17621765
[function.PyObject_CheckReadBuffer]
17631766
added = '3.2'
1767+
abi_only = true
17641768

17651769
# Flags are implicitly part of the ABI:
17661770

‎Objects/abstract.c

Lines changed: 35 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -294,11 +294,17 @@ PyObject_CheckBuffer(PyObject *obj)
294294
return (tp_as_buffer != NULL && tp_as_buffer->bf_getbuffer != NULL);
295295
}
296296

297+
// Old buffer protocols (deprecated, abi only)
297298

298-
/* We release the buffer right after use of this function which could
299+
/* Checks whether an arbitrary object supports the (character, single segment)
300+
buffer interface.
301+
302+
Returns 1 on success, 0 on failure.
303+
304+
We release the buffer right after use of this function which could
299305
cause issues later on. Don't use these functions in new code.
300306
*/
301-
int
307+
PyAPI_FUNC(int) /* abi_only */
302308
PyObject_CheckReadBuffer(PyObject *obj)
303309
{
304310
PyBufferProcs *pb = Py_TYPE(obj)->tp_as_buffer;
@@ -333,24 +339,44 @@ as_read_buffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
333339
return 0;
334340
}
335341

336-
int
342+
/* Takes an arbitrary object which must support the (character, single segment)
343+
buffer interface and returns a pointer to a read-only memory location
344+
usable as character based input for subsequent processing.
345+
346+
Return 0 on success. buffer and buffer_len are only set in case no error
347+
occurs. Otherwise, -1 is returned and an exception set. */
348+
PyAPI_FUNC(int) /* abi_only */
337349
PyObject_AsCharBuffer(PyObject *obj,
338350
const char **buffer,
339351
Py_ssize_t *buffer_len)
340352
{
341353
return as_read_buffer(obj, (const void **)buffer, buffer_len);
342354
}
343355

344-
int PyObject_AsReadBuffer(PyObject *obj,
345-
const void **buffer,
346-
Py_ssize_t *buffer_len)
356+
/* Same as PyObject_AsCharBuffer() except that this API expects (readable,
357+
single segment) buffer interface and returns a pointer to a read-only memory
358+
location which can contain arbitrary data.
359+
360+
0 is returned on success. buffer and buffer_len are only set in case no
361+
error occurs. Otherwise, -1 is returned and an exception set. */
362+
PyAPI_FUNC(int) /* abi_only */
363+
PyObject_AsReadBuffer(PyObject *obj,
364+
const void **buffer,
365+
Py_ssize_t *buffer_len)
347366
{
348367
return as_read_buffer(obj, buffer, buffer_len);
349368
}
350369

351-
int PyObject_AsWriteBuffer(PyObject *obj,
352-
void **buffer,
353-
Py_ssize_t *buffer_len)
370+
/* Takes an arbitrary object which must support the (writable, single segment)
371+
buffer interface and returns a pointer to a writable memory location in
372+
buffer of size 'buffer_len'.
373+
374+
Return 0 on success. buffer and buffer_len are only set in case no error
375+
occurs. Otherwise, -1 is returned and an exception set. */
376+
PyAPI_FUNC(int) /* abi_only */
377+
PyObject_AsWriteBuffer(PyObject *obj,
378+
void **buffer,
379+
Py_ssize_t *buffer_len)
354380
{
355381
PyBufferProcs *pb;
356382
Py_buffer view;

0 commit comments

Comments
 (0)
0