diff options
Diffstat (limited to 'Doc/c-api/objbuffer.rst')
| -rw-r--r-- | Doc/c-api/objbuffer.rst | 49 |
1 files changed, 30 insertions, 19 deletions
diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst index 6b82a64..c5228c6 100644 --- a/Doc/c-api/objbuffer.rst +++ b/Doc/c-api/objbuffer.rst @@ -1,21 +1,16 @@ -.. highlight:: c +.. highlightlang:: c -Old Buffer Protocol -------------------- +.. _abstract-buffer: -.. 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. +Old Buffer Protocol +=================== -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. +This section describes the legacy buffer protocol, which has been introduced +in Python 1.6. It is still supported but deprecated in the Python 2.x series. +Python 3 introduces a new buffer protocol which fixes weaknesses and +shortcomings of the protocol, and has been backported to Python 2.6. See +:ref:`bufferobjects` for more information. .. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len) @@ -26,6 +21,12 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released. and *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error. + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. + .. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len) @@ -35,21 +36,31 @@ an object, and :c:func:`PyBuffer_Release` when the buffer view can be released. and *buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error. + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. + .. 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. + Otherwise returns ``0``. - 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. + .. versionadded:: 2.2 .. 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 + Returns a pointer to a writeable 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. + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. + |