Debian Codegraph @

Doc/c-api/picklebuffer.rst

raw
1 .. highlight:: c
2
3 .. _picklebuffer-objects:
4
5 .. index::
6 pair: object; PickleBuffer
7
8 Pickle buffer objects
9 ---------------------
10
11 .. versionadded:: 3.8
12
13 A :class:`pickle.PickleBuffer` object wraps a :ref:`buffer-providing object
14 <bufferobjects>` for out-of-band data transfer with the :mod:`pickle` module.
15
16
17 .. c:var:: PyTypeObject PyPickleBuffer_Type
18
19 This instance of :c:type:`PyTypeObject` represents the Python pickle buffer type.
20 This is the same object as :class:`pickle.PickleBuffer` in the Python layer.
21
22
23 .. c:function:: int PyPickleBuffer_Check(PyObject *op)
24
25 Return true if *op* is a pickle buffer instance.
26 This function always succeeds.
27
28
29 .. c:function:: PyObject *PyPickleBuffer_FromObject(PyObject *obj)
30
31 Create a pickle buffer from the object *obj*.
32
33 This function will fail if *obj* doesn't support the :ref:`buffer protocol <bufferobjects>`.
34
35 On success, return a new pickle buffer instance.
36 On failure, set an exception and return ``NULL``.
37
38 Analogous to calling :class:`pickle.PickleBuffer` with *obj* in Python.
39
40
41 .. c:function:: const Py_buffer *PyPickleBuffer_GetBuffer(PyObject *picklebuf)
42
43 Get a pointer to the underlying :c:type:`Py_buffer` that the pickle buffer wraps.
44
45 The returned pointer is valid as long as *picklebuf* is alive and has not been
46 released. The caller must not modify or free the returned :c:type:`Py_buffer`.
47 If the pickle buffer has been released, raise :exc:`ValueError`.
48
49 On success, return a pointer to the buffer view.
50 On failure, set an exception and return ``NULL``.
51
52
53 .. c:function:: int PyPickleBuffer_Release(PyObject *picklebuf)
54
55 Release the underlying buffer held by the pickle buffer.
56
57 Return ``0`` on success. On failure, set an exception and return ``-1``.
58
59 Analogous to calling :meth:`pickle.PickleBuffer.release` in Python.