From 7f68a9046929222dddb9053ffbaaa0fb43a83490 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 16 Nov 2025 18:07:18 +0000 Subject: [PATCH 1/4] Commit --- Doc/c-api/concrete.rst | 1 + Doc/c-api/picklebuffer.rst | 59 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 Doc/c-api/picklebuffer.rst diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index a5c5a53236c9a4..1746fe95eaaca9 100644 --- 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 index 00000000000000..d0cb697fa6d388 --- /dev/null +++ b/Doc/c-api/picklebuffer.rst @@ -0,0 +1,59 @@ +.. highlight:: c + +.. _picklebuffer-objects: + +.. index:: + pair: object; PickleBuffer + +PickleBuffer objects +-------------------- + +.. versionadded:: 3.8 + +A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object +` 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 PickleBuffer 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 PickleBuffer instance. + This function always succeeds. + + +.. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj) + + Create a PickleBuffer from the object *obj*. + *obj* must support the :ref:`buffer protocol `. + + On success, return a new PickleBuffer 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 PickleBuffer wraps. + *picklebuf* must be a PickleBuffer instance. + + On success, return a pointer to the buffer view. + 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`. + + On failure, set an exception and return ``NULL``. + If the PickleBuffer has been released, raise :exc:`ValueError`. + + +.. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf) + + Release the underlying buffer held by the PickleBuffer. + + Return ``0`` on success. On failure, set an exception and return ``-1``. + + Analogous to calling :meth:`pickle.PickleBuffer.release` in Python. From f8bb55d9e6500f2df5c5f99324b1ba4956ee1f9f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 16 Nov 2025 18:34:22 +0000 Subject: [PATCH 2/4] Review --- Doc/c-api/picklebuffer.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/picklebuffer.rst b/Doc/c-api/picklebuffer.rst index d0cb697fa6d388..0aec3b079c1e02 100644 --- a/Doc/c-api/picklebuffer.rst +++ b/Doc/c-api/picklebuffer.rst @@ -16,22 +16,22 @@ A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object .. c:var:: PyTypeObject PyPickleBuffer_Type - This instance of :c:type:`PyTypeObject` represents the Python PickleBuffer 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 PickleBuffer instance. + Return true if *op* is a pickle buffer instance. This function always succeeds. .. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj) - Create a PickleBuffer from the object *obj*. - *obj* must support the :ref:`buffer protocol `. + Create a pickle buffer from the object *obj*. + This function will fail if *obj* doesn't support the :ref:`buffer protocol `. - On success, return a new PickleBuffer instance. + 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. @@ -39,20 +39,19 @@ A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object .. c:function:: const Py_buffer *PyPickleBuffer_GetBuffer(PyObject *picklebuf) - Get a pointer to the underlying :c:type:`Py_buffer` that the PickleBuffer wraps. - *picklebuf* must be a PickleBuffer instance. + Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps. On success, return a pointer to the buffer view. 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`. On failure, set an exception and return ``NULL``. - If the PickleBuffer has been released, raise :exc:`ValueError`. + If the pickle buffer has been released, raise :exc:`ValueError`. .. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf) - Release the underlying buffer held by the PickleBuffer. + Release the underlying buffer held by the pickle buffer. Return ``0`` on success. On failure, set an exception and return ``-1``. From 1512ebd1342486137a33cf195b0be2e57a390fb2 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Sun, 16 Nov 2025 18:34:33 +0000 Subject: [PATCH 3/4] Update Doc/c-api/picklebuffer.rst Co-authored-by: Peter Bierma --- Doc/c-api/picklebuffer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/picklebuffer.rst b/Doc/c-api/picklebuffer.rst index 0aec3b079c1e02..c39a01de6972ad 100644 --- a/Doc/c-api/picklebuffer.rst +++ b/Doc/c-api/picklebuffer.rst @@ -41,10 +41,10 @@ A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps. - On success, return a pointer to the buffer view. 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`. + On success, return a pointer to the buffer view. On failure, set an exception and return ``NULL``. If the pickle buffer has been released, raise :exc:`ValueError`. From 1076cfb5b5ffb40a0b9b41bb3cdcb02b89b8cbd4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 16 Nov 2025 18:42:52 +0000 Subject: [PATCH 4/4] Tweaks --- Doc/c-api/picklebuffer.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/picklebuffer.rst b/Doc/c-api/picklebuffer.rst index c39a01de6972ad..9e2d92341b0f93 100644 --- a/Doc/c-api/picklebuffer.rst +++ b/Doc/c-api/picklebuffer.rst @@ -5,8 +5,8 @@ .. index:: pair: object; PickleBuffer -PickleBuffer objects --------------------- +Pickle buffer objects +--------------------- .. versionadded:: 3.8 @@ -29,6 +29,7 @@ A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object .. 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 `. On success, return a new pickle buffer instance. @@ -43,10 +44,10 @@ A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object 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``. - If the pickle buffer has been released, raise :exc:`ValueError`. .. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf)