bpo-41103: Resurrect the old buffer protocol. (GH-27437) (GH-27441)
Revert "bpo-41103: Remove old buffer protocol support (GH-21117)"
This reverts commit 6f8a6ee59cb7f99f68df8ee9c3e8c8cf19af3eed.
(cherry picked from commit ce5e1a6809b714eb0383219190a076d9f883e008)
Co-authored-by: Inada Naoki <songofacandy@gmail.com>
diff --git a/Doc/c-api/abstract.rst b/Doc/c-api/abstract.rst
index f5df09f..1823f9d 100644
--- a/Doc/c-api/abstract.rst
+++ b/Doc/c-api/abstract.rst
@@ -24,3 +24,4 @@
mapping.rst
iter.rst
buffer.rst
+ objbuffer.rst
diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst
new file mode 100644
index 0000000..6b82a64
--- /dev/null
+++ b/Doc/c-api/objbuffer.rst
@@ -0,0 +1,55 @@
+.. highlight:: c
+
+Old Buffer Protocol
+-------------------
+
+.. deprecated:: 3.0
+
+These functions were part of the "old buffer protocol" API in Python 2.
+In Python 3, this protocol doesn't exist anymore but the functions are still
+exposed to ease porting 2.x code. They act as a compatibility wrapper
+around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
+you control over the lifetime of the resources acquired when a buffer is
+exported.
+
+Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
+(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
+:c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
+an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
+
+
+.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a read-only memory location usable as character-based
+ input. The *obj* argument must support the single-segment character buffer
+ interface. On success, returns ``0``, sets *buffer* to the memory location
+ and *buffer_len* to the buffer length. Returns ``-1`` and sets a
+ :exc:`TypeError` on error.
+
+
+.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a read-only memory location containing arbitrary data.
+ The *obj* argument must support the single-segment readable buffer
+ interface. On success, returns ``0``, sets *buffer* to the memory location
+ and *buffer_len* to the buffer length. Returns ``-1`` and sets a
+ :exc:`TypeError` on error.
+
+
+.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
+
+ Returns ``1`` if *o* supports the single-segment readable buffer interface.
+ Otherwise returns ``0``. This function always succeeds.
+
+ Note that this function tries to get and release a buffer, and exceptions
+ which occur while calling corresponding functions will get suppressed.
+ To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
+
+
+.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+ Returns a pointer to a writable memory location. The *obj* argument must
+ support the single-segment, character buffer interface. On success,
+ returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
+ buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
+
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 29cd89e..f5e2131 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -1571,6 +1571,21 @@
PyObject_ASCII:PyObject*::+1:
PyObject_ASCII:PyObject*:o:0:
+PyObject_AsCharBuffer:int:::
+PyObject_AsCharBuffer:PyObject*:obj:0:
+PyObject_AsCharBuffer:const char**:buffer::
+PyObject_AsCharBuffer:Py_ssize_t*:buffer_len::
+
+PyObject_AsReadBuffer:int:::
+PyObject_AsReadBuffer:PyObject*:obj:0:
+PyObject_AsReadBuffer:const void**:buffer::
+PyObject_AsReadBuffer:Py_ssize_t*:buffer_len::
+
+PyObject_AsWriteBuffer:int:::
+PyObject_AsWriteBuffer:PyObject*:obj:0:
+PyObject_AsWriteBuffer:void**:buffer::
+PyObject_AsWriteBuffer:Py_ssize_t*:buffer_len::
+
PyObject_Bytes:PyObject*::+1:
PyObject_Bytes:PyObject*:o:0:
@@ -1606,6 +1621,9 @@
PyObject_CheckBuffer:int:::
PyObject_CheckBuffer:PyObject*:obj:0:
+PyObject_CheckReadBuffer:int:::
+PyObject_CheckReadBuffer:PyObject*:o:0:
+
PyObject_DelAttr:int:::
PyObject_DelAttr:PyObject*:o:0:
PyObject_DelAttr:PyObject*:attr_name:0:
diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
index e373e23..be9225b 100644
--- a/Doc/data/stable_abi.dat
+++ b/Doc/data/stable_abi.dat
@@ -462,7 +462,10 @@
function,PyOS_vsnprintf,3.2,
type,PyObject,3.2,
function,PyObject_ASCII,3.2,
+function,PyObject_AsCharBuffer,3.2,
function,PyObject_AsFileDescriptor,3.2,
+function,PyObject_AsReadBuffer,3.2,
+function,PyObject_AsWriteBuffer,3.2,
function,PyObject_Bytes,3.2,
function,PyObject_Call,3.2,
function,PyObject_CallFunction,3.2,
@@ -472,6 +475,7 @@
function,PyObject_CallNoArgs,3.10,
function,PyObject_CallObject,3.2,
function,PyObject_Calloc,3.7,
+function,PyObject_CheckReadBuffer,3.2,
function,PyObject_ClearWeakRefs,3.2,
function,PyObject_DelItem,3.2,
function,PyObject_DelItemString,3.2,
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index d84ee13..5af1693 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -2109,11 +2109,6 @@
Removed
-------
-* ``PyObject_AsCharBuffer()``, ``PyObject_AsReadBuffer()``, ``PyObject_CheckReadBuffer()``,
- and ``PyObject_AsWriteBuffer()`` are removed. Please migrate to new buffer protocol;
- :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`.
- (Contributed by Inada Naoki in :issue:`41103`.)
-
* Removed ``Py_UNICODE_str*`` functions manipulating ``Py_UNICODE*`` strings.
(Contributed by Inada Naoki in :issue:`41123`.)