[Python-checkins] r85068 - in python/branches/release27-maint: Doc/c-api/buffer.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Tue Sep 28 17:35:18 2010
New Revision: 85068

Log:
Merged revisions 85066 via svnmerge from 
svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r85066 | antoine.pitrou | 2010-09-28 17:29:16 +0200 (mar., 28 sept. 2010) | 3 lines
  
  Issue #9970: improve C API documentation for memoryview objects
........


Modified:
   python/branches/release27-maint/   (props changed)
   python/branches/release27-maint/Doc/c-api/buffer.rst

Modified: python/branches/release27-maint/Doc/c-api/buffer.rst
==============================================================================
--- python/branches/release27-maint/Doc/c-api/buffer.rst	(original)
+++ python/branches/release27-maint/Doc/c-api/buffer.rst	Tue Sep 28 17:35:18 2010
@@ -304,14 +304,45 @@
 MemoryView objects
 ==================
 
-A memoryview object is an extended buffer object that could replace the buffer
-object (but doesn't have to as that could be kept as a simple 1-d memoryview
-object).  It, unlike :ctype:`Py_buffer`, is a Python object (exposed as
-:class:`memoryview` in :mod:`builtins`), so it can be used with Python code.
+.. versionadded:: 2.7
 
-.. cfunction:: PyObject* PyMemoryView_FromObject(PyObject *obj)
+A :class:`memoryview` object exposes the new C level buffer interface as a
+Python object which can then be passed around like any other object.
 
-   Return a memoryview object from an object that defines the buffer interface.
+.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)
+
+   Create a memoryview object from an object that defines the new buffer
+   interface.
+
+
+.. cfunction:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+   Create a memoryview object wrapping the given buffer-info structure *view*.
+   The memoryview object then owns the buffer, which means you shouldn't
+   try to release it yourself: it will be released on deallocation of the
+   memoryview object.
+
+
+.. cfunction:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
+
+   Create a memoryview object to a contiguous chunk of memory (in either
+   'C' or 'F'ortran *order*) from an object that defines the buffer
+   interface. If memory is contiguous, the memoryview object points to the
+   original memory. Otherwise copy is made and the memoryview points to a
+   new bytes object.
+
+
+.. cfunction:: int PyMemoryView_Check(PyObject *obj)
+
+   Return true if the object *obj* is a memoryview object.  It is not
+   currently allowed to create subclasses of :class:`memoryview`.
+
+
+.. cfunction:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)
+
+   Return a pointer to the buffer-info structure wrapped by the given
+   object.  The object **must** be a memoryview instance; this macro doesn't
+   check its type, you must do it yourself or you will risk crashes.
 
 
 Old-style buffer objects