bpo-45459: Add Py_buffer to limited API

Doc/data/stable_abi.dat

@@ -10,6 +10,23 @@ function,PyArg_ValidateKeywordArguments,3.2,
 var,PyBaseObject_Type,3.2,
 function,PyBool_FromLong,3.2,
 var,PyBool_Type,3.2,
+function,PyBuffer_FillContiguousStrides,3.11,
+function,PyBuffer_FillInfo,3.11,
+function,PyBuffer_FillInfoEx,3.11,
+function,PyBuffer_Free,3.11,
+function,PyBuffer_FromContiguous,3.11,
+function,PyBuffer_GetInternal,3.11,
+function,PyBuffer_GetItemSize,3.11,
+function,PyBuffer_GetLayout,3.11,
+function,PyBuffer_GetLength,3.11,
+function,PyBuffer_GetObject,3.11,
+function,PyBuffer_GetPointer,3.11,
+function,PyBuffer_IsContiguous,3.11,
+function,PyBuffer_IsReadonly,3.11,
+function,PyBuffer_New,3.11,
+function,PyBuffer_Release,3.11,
+function,PyBuffer_SizeFromFormat,3.11,
+function,PyBuffer_ToContiguous,3.11,
 var,PyByteArrayIter_Type,3.2,
 function,PyByteArray_AsString,3.2,
 function,PyByteArray_Concat,3.2,
@@ -475,8 +492,10 @@ function,PyObject_CallMethodObjArgs,3.2,
 function,PyObject_CallNoArgs,3.10,
 function,PyObject_CallObject,3.2,
 function,PyObject_Calloc,3.7,
+function,PyObject_CheckBuffer,3.11,
 function,PyObject_CheckReadBuffer,3.2,
 function,PyObject_ClearWeakRefs,3.2,
+function,PyObject_CopyData,3.11,
 function,PyObject_DelItem,3.2,
 function,PyObject_DelItemString,3.2,
 function,PyObject_Dir,3.2,
@@ -494,6 +513,7 @@ function,PyObject_GenericSetDict,3.7,
 function,PyObject_GetAIter,3.10,
 function,PyObject_GetAttr,3.2,
 function,PyObject_GetAttrString,3.2,
+function,PyObject_GetBuffer,3.11,
 function,PyObject_GetItem,3.2,
 function,PyObject_GetIter,3.2,
 function,PyObject_HasAttr,3.2,

Include/Python.h

@@ -48,6 +48,7 @@
 #include "longobject.h"
 #include "cpython/longintrepr.h"
 #include "boolobject.h"
+#include "buffer.h"
 #include "floatobject.h"
 #include "complexobject.h"
 #include "rangeobject.h"

Include/buffer.h

@@ -0,0 +1,147 @@
+/* Public Py_buffer API */
+
+#ifndef Py_BUFFER_H
+#define Py_BUFFER_H
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* === New Buffer API ============================================
+ * Limited API since Python 3.11
+ */
+
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000
+
+typedef struct bufferinfo Py_buffer;
+
+/* Return 1 if the getbuffer function is available, otherwise return 0. */
+PyAPI_FUNC(int) PyObject_CheckBuffer(PyObject *obj);
+
+/* This is a C-API version of the getbuffer function call.  It checks
+   to make sure object has the required function pointer and issues the
+   call.
+
+   Returns -1 and raises an error on failure and returns 0 on success. */
+PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
+                                   int flags);
+
+/* Get the memory area pointed to by the indices for the buffer given.
+   Note that view->ndim is the assumed size of indices. */
+PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
+
+/* Return the implied itemsize of the data-format area from a
+   struct-style description. */
+PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format);
+
+/* Implementation in memoryobject.c */
+PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
+                                      Py_ssize_t len, char order);
+
+PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
+                                        Py_ssize_t len, char order);
+
+/* Copy len bytes of data from the contiguous chunk of memory
+   pointed to by buf into the buffer exported by obj.  Return
+   0 on success and return -1 and raise a PyBuffer_Error on
+   error (i.e. the object does not have a buffer interface or
+   it is not working).
+
+   If fort is 'F', then if the object is multi-dimensional,
+   then the data will be copied into the array in
+   Fortran-style (first dimension varies the fastest).  If
+   fort is 'C', then the data will be copied into the array
+   in C-style (last dimension varies the fastest).  If fort
+   is 'A', then it does not matter and the copy will be made
+   in whatever way is more efficient. */
+PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
+
+/* Copy the data from the src buffer to the buffer of destination. */
+PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
+
+/*Fill the strides array with byte-strides of a contiguous
+  (Fortran-style if fort is 'F' or C-style otherwise)
+  array of the given shape with the given number of bytes
+  per element. */
+PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
+                                               Py_ssize_t *shape,
+                                               Py_ssize_t *strides,
+                                               int itemsize,
+                                               char fort);
+
+/* Fills in a buffer-info structure correctly for an exporter
+   that can only share a contiguous chunk of memory of
+   "unsigned bytes" of the given length.
+
+   Returns 0 on success and -1 (with raising an error) on error. */
+PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
+                                  Py_ssize_t len, int readonly,
+                                  int flags);
+
+PyAPI_FUNC(int) PyBuffer_FillInfoEx(Py_buffer *view, PyObject *obj, void *buf,
+                                    Py_ssize_t len, int readonly, int flags,
+                                    Py_ssize_t itemsize, int ndim,
+                                    char *format, Py_ssize_t *shape,
+                                    Py_ssize_t *strides, Py_ssize_t *suboffsets,
+                                    void *internal);
+
+/* Allocate a new buffer struct on the heap. */
+PyAPI_FUNC(Py_buffer *) PyBuffer_New(void);
+
+/* Release and free buffer struct which has been allocated
+    by PyBuffer_New(). */
+PyAPI_FUNC(void) PyBuffer_Free(Py_buffer *view);
+
+/* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */
+PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
+
+PyAPI_FUNC(PyObject *) PyBuffer_GetObject(Py_buffer *view);
+PyAPI_FUNC(Py_ssize_t) PyBuffer_GetLength(Py_buffer *view);
+PyAPI_FUNC(Py_ssize_t) PyBuffer_GetItemSize(Py_buffer *view);
+PyAPI_FUNC(int) PyBuffer_IsReadonly(Py_buffer *view);
+PyAPI_FUNC(void *) PyBuffer_GetInternal(Py_buffer *view);
+PyAPI_FUNC(int) PyBuffer_GetLayout(Py_buffer *view, char **format,
+                                   Py_ssize_t **shape, Py_ssize_t **strides,
+                                   Py_ssize_t **suboffsets);
+
+/* Maximum number of dimensions */
+#define PyBUF_MAX_NDIM 64
+
+/* Flags for getting buffers */
+#define PyBUF_SIMPLE 0
+#define PyBUF_WRITABLE 0x0001
+
+#ifndef Py_LIMITED_API
+/*  we used to include an E, backwards compatible alias */
+#define PyBUF_WRITEABLE PyBUF_WRITABLE
+#endif
+
+#define PyBUF_FORMAT 0x0004
+#define PyBUF_ND 0x0008
+#define PyBUF_STRIDES (0x0010 | PyBUF_ND)
+#define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES)
+#define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES)
+#define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES)
+#define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES)
+
+#define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE)
+#define PyBUF_CONTIG_RO (PyBUF_ND)
+
+#define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE)
+#define PyBUF_STRIDED_RO (PyBUF_STRIDES)
+
+#define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT)
+#define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT)
+
+#define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT)
+#define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT)
+
+
+#define PyBUF_READ  0x100
+#define PyBUF_WRITE 0x200
+
+#endif /* Py_LIMITED_API */
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* Py_BUFFER_H */

Include/cpython/abstract.h

@@ -168,74 +168,6 @@ PyAPI_FUNC(int) _PyObject_HasLen(PyObject *o);
    value.  If one of the calls fails, this function returns -1. */
 PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
 
-/* === New Buffer API ============================================ */
-
-/* Return 1 if the getbuffer function is available, otherwise return 0. */
-PyAPI_FUNC(int) PyObject_CheckBuffer(PyObject *obj);
-
-/* This is a C-API version of the getbuffer function call.  It checks
-   to make sure object has the required function pointer and issues the
-   call.
-
-   Returns -1 and raises an error on failure and returns 0 on success. */
-PyAPI_FUNC(int) PyObject_GetBuffer(PyObject *obj, Py_buffer *view,
-                                   int flags);
-
-/* Get the memory area pointed to by the indices for the buffer given.
-   Note that view->ndim is the assumed size of indices. */
-PyAPI_FUNC(void *) PyBuffer_GetPointer(Py_buffer *view, Py_ssize_t *indices);
-
-/* Return the implied itemsize of the data-format area from a
-   struct-style description. */
-PyAPI_FUNC(Py_ssize_t) PyBuffer_SizeFromFormat(const char *format);
-
-/* Implementation in memoryobject.c */
-PyAPI_FUNC(int) PyBuffer_ToContiguous(void *buf, Py_buffer *view,
-                                      Py_ssize_t len, char order);
-
-PyAPI_FUNC(int) PyBuffer_FromContiguous(Py_buffer *view, void *buf,
-                                        Py_ssize_t len, char order);
-
-/* Copy len bytes of data from the contiguous chunk of memory
-   pointed to by buf into the buffer exported by obj.  Return
-   0 on success and return -1 and raise a PyBuffer_Error on
-   error (i.e. the object does not have a buffer interface or
-   it is not working).
-
-   If fort is 'F', then if the object is multi-dimensional,
-   then the data will be copied into the array in
-   Fortran-style (first dimension varies the fastest).  If
-   fort is 'C', then the data will be copied into the array
-   in C-style (last dimension varies the fastest).  If fort
-   is 'A', then it does not matter and the copy will be made
-   in whatever way is more efficient. */
-PyAPI_FUNC(int) PyObject_CopyData(PyObject *dest, PyObject *src);
-
-/* Copy the data from the src buffer to the buffer of destination. */
-PyAPI_FUNC(int) PyBuffer_IsContiguous(const Py_buffer *view, char fort);
-
-/*Fill the strides array with byte-strides of a contiguous
-  (Fortran-style if fort is 'F' or C-style otherwise)
-  array of the given shape with the given number of bytes
-  per element. */
-PyAPI_FUNC(void) PyBuffer_FillContiguousStrides(int ndims,
-                                               Py_ssize_t *shape,
-                                               Py_ssize_t *strides,
-                                               int itemsize,
-                                               char fort);
-
-/* Fills in a buffer-info structure correctly for an exporter
-   that can only share a contiguous chunk of memory of
-   "unsigned bytes" of the given length.
-
-   Returns 0 on success and -1 (with raising an error) on error. */
-PyAPI_FUNC(int) PyBuffer_FillInfo(Py_buffer *view, PyObject *o, void *buf,
-                                  Py_ssize_t len, int readonly,
-                                  int flags);
-
-/* Releases a Py_buffer obtained from getbuffer ParseTuple's "s*". */
-PyAPI_FUNC(void) PyBuffer_Release(Py_buffer *view);
-
 /* === Sequence protocol ================================================ */
 
 /* Assume tp_as_sequence and sq_item exist and that 'i' does not

Include/cpython/object.h

@@ -63,43 +63,11 @@ typedef struct bufferinfo {
 
 typedef int (*getbufferproc)(PyObject *, Py_buffer *, int);
 typedef void (*releasebufferproc)(PyObject *, Py_buffer *);
+/* End buffer interface */
 
 typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args,
                                     size_t nargsf, PyObject *kwnames);
 
-/* Maximum number of dimensions */
-#define PyBUF_MAX_NDIM 64
-
-/* Flags for getting buffers */
-#define PyBUF_SIMPLE 0
-#define PyBUF_WRITABLE 0x0001
-/*  we used to include an E, backwards compatible alias  */
-#define PyBUF_WRITEABLE PyBUF_WRITABLE
-#define PyBUF_FORMAT 0x0004
-#define PyBUF_ND 0x0008
-#define PyBUF_STRIDES (0x0010 | PyBUF_ND)
-#define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES)
-#define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES)
-#define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES)
-#define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES)
-
-#define PyBUF_CONTIG (PyBUF_ND | PyBUF_WRITABLE)
-#define PyBUF_CONTIG_RO (PyBUF_ND)
-
-#define PyBUF_STRIDED (PyBUF_STRIDES | PyBUF_WRITABLE)
-#define PyBUF_STRIDED_RO (PyBUF_STRIDES)
-
-#define PyBUF_RECORDS (PyBUF_STRIDES | PyBUF_WRITABLE | PyBUF_FORMAT)
-#define PyBUF_RECORDS_RO (PyBUF_STRIDES | PyBUF_FORMAT)
-
-#define PyBUF_FULL (PyBUF_INDIRECT | PyBUF_WRITABLE | PyBUF_FORMAT)
-#define PyBUF_FULL_RO (PyBUF_INDIRECT | PyBUF_FORMAT)
-
-
-#define PyBUF_READ  0x100
-#define PyBUF_WRITE 0x200
-/* End buffer interface */
-
 
 typedef struct {
     /* Number implementations must check *both*

Include/typeslots.h

@@ -1,12 +1,6 @@
 /* Do not renumber the file; these numbers are part of the stable ABI. */
-#if defined(Py_LIMITED_API)
-/* Disabled, see #10181 */
-#undef Py_bf_getbuffer
-#undef Py_bf_releasebuffer
-#else
 #define Py_bf_getbuffer 1
 #define Py_bf_releasebuffer 2
-#endif
 #define Py_mp_ass_subscript 3
 #define Py_mp_length 4
 #define Py_mp_subscript 5

Makefile.pre.in

@@ -1125,6 +1125,7 @@ PYTHON_HEADERS= \
 		$(srcdir)/Include/abstract.h \
 		$(srcdir)/Include/bltinmodule.h \
 		$(srcdir)/Include/boolobject.h \
+		$(srcdir)/Include/buffer.h \
 		$(srcdir)/Include/bytearrayobject.h \
 		$(srcdir)/Include/bytesobject.h \
 		$(srcdir)/Include/ceval.h \

Misc/NEWS.d/next/C API/2021-10-18-16-54-24.bpo-45459.Y1pEZs.rst

@@ -0,0 +1 @@
+Add :c:type:`Py_buffer` to limited API / stable ABI.

Misc/stable_abi.txt

@@ -2150,5 +2150,47 @@ function PyType_GetName
 function PyType_GetQualName
     added 3.11
 
+# Add stable Py_buffer API in Python 3.11 (https://bugs.python.org/issue45459)
+function PyObject_CheckBuffer
+    added 3.11
+function PyObject_GetBuffer
+    added 3.11
+function PyBuffer_GetPointer
+    added 3.11
+function PyBuffer_SizeFromFormat
+    added 3.11
+function PyBuffer_ToContiguous
+    added 3.11
+function PyBuffer_FromContiguous
+    added 3.11
+function PyObject_CopyData
+    added 3.11
+function PyBuffer_IsContiguous
+    added 3.11
+function PyBuffer_FillContiguousStrides
+    added 3.11
+function PyBuffer_FillInfo
+    added 3.11
+function PyBuffer_FillInfoEx
+    added 3.11
+function PyBuffer_New
+    added 3.11
+function PyBuffer_Free
+    added 3.11
+function PyBuffer_Release
+    added 3.11
+function PyBuffer_GetObject
+    added 3.11
+function PyBuffer_GetLength
+    added 3.11
+function PyBuffer_GetItemSize
+    added 3.11
+function PyBuffer_IsReadonly
+    added 3.11
+function PyBuffer_GetInternal
+    added 3.11
+function PyBuffer_GetLayout
+    added 3.11
+
 # (Detailed comments aren't really needed for further entries: from here on
 #  we can use version control logs.)