[Python-checkins] r85084 - in python/branches/py3k/Doc/c-api: buffer.rst concrete.rst memoryview.rst

Wed Sep 29 01:59:51 CEST 2010

Author: antoine.pitrou
Date: Wed Sep 29 01:59:51 2010
New Revision: 85084
Log:
Give a dedicated page to memoryview objects, so that they can be part
of the concrete objects layer, while the buffer protocol is part of
the abstract objects layer.
Added:
 python/branches/py3k/Doc/c-api/memoryview.rst
Modified:
 python/branches/py3k/Doc/c-api/buffer.rst
 python/branches/py3k/Doc/c-api/concrete.rst
Modified: python/branches/py3k/Doc/c-api/buffer.rst
==============================================================================

--- python/branches/py3k/Doc/c-api/buffer.rst	(original)
+++ python/branches/py3k/Doc/c-api/buffer.rst	Wed Sep 29 01:59:51 2010
@@ -65,7 +65,7 @@
 Contrary to most data types exposed by the Python interpreter, buffers
 are not :ctype:`PyObject` pointers but rather simple C structures. This
 allows them to be created and copied very simply. When a generic wrapper
-around a buffer is needed, a :ref:`memoryview <memoryviewobjects>` object
+around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
 can be created.
 
 
@@ -154,7 +154,7 @@
 value.
 
 
-Buffer related functions
+Buffer-related functions
 ========================
 
 
@@ -330,49 +330,3 @@
 only share a contiguous chunk of memory of "unsigned bytes" of the given
 length. Return 0 on success and -1 (with raising an error) on error.
 
-
-.. index::
- object: memoryview
-
-.. _memoryviewobjects:
-
-MemoryView objects
-==================
-
-A :class:`memoryview` object exposes the C level buffer interface as a
-Python object which can then be passed around like any other object.
-
-
-.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)
-
- Create a memoryview object from an object that defines the 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.
Modified: python/branches/py3k/Doc/c-api/concrete.rst
==============================================================================
--- python/branches/py3k/Doc/c-api/concrete.rst	(original)
+++ python/branches/py3k/Doc/c-api/concrete.rst	Wed Sep 29 01:59:51 2010
@@ -99,6 +99,7 @@
 iterator.rst
 descriptor.rst
 slice.rst
+ memoryview.rst
 weakref.rst
 capsule.rst
 cell.rst
Added: python/branches/py3k/Doc/c-api/memoryview.rst
==============================================================================
--- (empty file)
+++ python/branches/py3k/Doc/c-api/memoryview.rst	Wed Sep 29 01:59:51 2010
@@ -0,0 +1,52 @@
+.. highlightlang:: c
+
+.. _memoryview-objects:
+
+.. index::
+ object: memoryview
+
+MemoryView objects
+------------------
+
+A :class:`memoryview` object exposes the C level :ref:`buffer interface
+<bufferobjects>` as a Python object which can then be passed around like
+any other object.
+
+
+.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)
+
+ Create a memoryview object from an object that provides the buffer interface.
+ If *obj* supports writable buffer exports, the memoryview object will be
+ readable and writable, other it will be read-only.
+
+
+.. cfunction:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+ Create a memoryview object wrapping the given buffer structure *view*.
+ The memoryview object then owns the buffer represented by *view*, which
+ means you shouldn't try to call :cfunc:`PyBuffer_Release` yourself: it
+ will be done 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 structure wrapped by the given
+ memoryview 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.
+
