From: Antoine Pitrou <solipsis@pitrou.net>
Date: Tue, 28 Sep 2010 21:52:30 +0000 (+0000)
Subject: Discourage use of the old buffer API funcs
X-Git-Tag: v3.2a3~116
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a0b6873d476789270934ddb9d187323f4edbdd2b;p=thirdparty%2FPython%2Fcpython.git

Discourage use of the old buffer API funcs
---

diff --git a/Doc/c-api/objbuffer.rst b/Doc/c-api/objbuffer.rst
index 0973aad19b07..ef4e4ea60669 100644
--- a/Doc/c-api/objbuffer.rst
+++ b/Doc/c-api/objbuffer.rst
@@ -1,6 +1,21 @@
 .. highlightlang:: c
 
-.. _abstract-buffer:
+Old buffer API
+--------------
+
+.. deprecated:: 3.0
+
+These functions were part of the "old buffer protocol" API in Python 2.
+In Python 3, these functions are still exposed for ease of porting code.
+They act as a compatibility wrapper around the :ref:`new buffer API
+<bufferobjects>`, but they don't give you control over the lifetime of
+the resources acquired when a buffer is exported.
+
+Therefore, it is recommended that you call :cfunc:`PyObject_GetBuffer`
+(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
+:cfunc:`PyArg_ParseTuple` family of functions) to get a buffer view over
+an object, and :cfunc:`PyBuffer_Release` when the buffer view can be released.
+
 
 Buffer Protocol
 ===============