Debian Codegraph @

Doc/c-api/memoryview.rst

raw
1 .. highlight:: c
2
3 .. _memoryview-objects:
4
5 .. index::
6 pair: object; memoryview
7
8 MemoryView objects
9 ------------------
10
11 A :class:`memoryview` object exposes the C level :ref:`buffer interface
12 <bufferobjects>` as a Python object which can then be passed around like
13 any other object.
14
15
16 .. c:var:: PyTypeObject PyMemoryView_Type
17
18 This instance of :c:type:`PyTypeObject` represents the Python memoryview
19 type. This is the same object as :class:`memoryview` in the Python layer.
20
21
22 .. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
23
24 Create a memoryview object from an object that provides the buffer interface.
25 If *obj* supports writable buffer exports, the memoryview object will be
26 read/write, otherwise it may be either read-only or read/write at the
27 discretion of the exporter.
28
29
30 .. c:macro:: PyBUF_READ
31
32 Flag to request a readonly buffer.
33
34
35 .. c:macro:: PyBUF_WRITE
36
37 Flag to request a writable buffer.
38
39
40 .. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
41
42 Create a memoryview object using *mem* as the underlying buffer.
43 *flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
44
45 .. versionadded:: 3.3
46
47 .. c:function:: PyObject *PyMemoryView_FromBuffer(const Py_buffer *view)
48
49 Create a memoryview object wrapping the given buffer structure *view*.
50 For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred
51 function.
52
53 .. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
54
55 Create a memoryview object to a :term:`contiguous` chunk of memory (in either
56 'C' or 'F'ortran *order*) from an object that defines the buffer
57 interface. If memory is contiguous, the memoryview object points to the
58 original memory. Otherwise, a copy is made and the memoryview points to a
59 new bytes object.
60
61 *buffertype* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
62
63
64 .. c:function:: int PyMemoryView_Check(PyObject *obj)
65
66 Return true if the object *obj* is a memoryview object. It is not
67 currently allowed to create subclasses of :class:`memoryview`. This
68 function always succeeds.
69
70
71 .. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)
72
73 Return a pointer to the memoryview's private copy of the exporter's buffer.
74 *mview* **must** be a memoryview instance; this macro doesn't check its type,
75 you must do it yourself or you will risk crashes.
76
77 .. c:function:: PyObject *PyMemoryView_GET_BASE(PyObject *mview)
78
79 Return either a pointer to the exporting object that the memoryview is based
80 on or ``NULL`` if the memoryview has been created by one of the functions
81 :c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
82 *mview* **must** be a memoryview instance.