From 6ec5ed22b2e5b4429ad9e130ecaad7fa16fde691 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Wed, 29 Sep 2010 00:01:41 +0000 Subject: [PATCH] Merged revisions 85084 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r85084 | antoine.pitrou | 2010-09-29 01:59:51 +0200 (mer., 29 sept. 2010) | 5 lines 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. ........ --- Doc/c-api/buffer.rst | 50 ++------------------------------------ Doc/c-api/concrete.rst | 1 + Doc/c-api/memoryview.rst | 52 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 48 deletions(-) create mode 100644 Doc/c-api/memoryview.rst diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index ce782d2107..db5c185d7f 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -65,7 +65,7 @@ in its native, in-memory format. 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 ` object +around a buffer is needed, a :ref:`memoryview ` object can be created. @@ -154,7 +154,7 @@ can be created. value. -Buffer related functions +Buffer-related functions ======================== @@ -330,49 +330,3 @@ Buffer related functions 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. diff --git a/Doc/c-api/concrete.rst b/Doc/c-api/concrete.rst index 23f79b7cd3..d72859989f 100644 --- a/Doc/c-api/concrete.rst +++ b/Doc/c-api/concrete.rst @@ -99,6 +99,7 @@ Other Objects iterator.rst descriptor.rst slice.rst + memoryview.rst weakref.rst capsule.rst cobject.rst diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst new file mode 100644 index 0000000000..9003d3e26d --- /dev/null +++ b/Doc/c-api/memoryview.rst @@ -0,0 +1,52 @@ +.. highlightlang:: c + +.. _memoryview-objects: + +.. index:: + object: memoryview + +MemoryView objects +------------------ + +A :class:`memoryview` object exposes the C level :ref:`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 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. + -- 2.40.0