[3.14] gh-141004: Document the `PyPickleBuffer_*` C API (GH-141630) (GH-141632)

gh-141004: Document the `PyPickleBuffer_*` C API (GH-141630)
(cherry picked from commit e33afa7ddbca3fca38f4ec4369b620c37cb092e2)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst
index a5c5a53236c9a478416b49c6fd00913b087997ca..1746fe95eaaca933c46be541bff674f0597c91dc 100644 (file)
--- a/Doc/c-api/concrete.rst
+++ b/Doc/c-api/concrete.rst
@@ -109,6 +109,7 @@ Other Objects
    descriptor.rst
    slice.rst
    memoryview.rst
+   picklebuffer.rst
    weakref.rst
    capsule.rst
    frame.rst

diff --git a/Doc/c-api/picklebuffer.rst b/Doc/c-api/picklebuffer.rst
new file mode 100644 (file)
index 0000000..9e2d923
--- /dev/null
+++ b/Doc/c-api/picklebuffer.rst
@@ -0,0 +1,59 @@
+.. highlight:: c
+
+.. _picklebuffer-objects:
+
+.. index::
+   pair: object; PickleBuffer
+
+Pickle buffer objects
+---------------------
+
+.. versionadded:: 3.8
+
+A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object
+<bufferobjects>` for out-of-band data transfer with the :mod:`pickle` module.
+
+
+.. c:var:: PyTypeObject PyPickleBuffer_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python pickle buffer type.
+   This is the same object as :class:`pickle.PickleBuffer` in the Python layer.
+
+
+.. c:function:: int PyPickleBuffer_Check(PyObject *op)
+
+   Return true if *op* is a pickle buffer instance.
+   This function always succeeds.
+
+
+.. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj)
+
+   Create a pickle buffer from the object *obj*.
+
+   This function will fail if *obj* doesn't support the :ref:`buffer protocol <bufferobjects>`.
+
+   On success, return a new pickle buffer instance.
+   On failure, set an exception and return ``NULL``.
+
+   Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python.
+
+
+.. c:function:: const Py_buffer *PyPickleBuffer_GetBuffer(PyObject *picklebuf)
+
+   Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps.
+
+   The returned pointer is valid as long as *picklebuf* is alive and has not been
+   released. The caller must not modify or free the returned :c:type:`Py_buffer`.
+   If the pickle buffer has been released, raise :exc:`ValueError`.
+
+   On success, return a pointer to the buffer view.
+   On failure, set an exception and return ``NULL``.
+
+
+.. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf)
+
+   Release the underlying buffer held by the pickle buffer.
+
+   Return ``0`` on success. On failure, set an exception and return ``-1``.
+
+   Analogous to calling :meth:`pickle.PickleBuffer.release` in Python.