docs: pythonise "Working with Python arrays" (array.rst) (GH-4431)

docs/examples/tutorial/array/clone.py

+from cython.cimports.cpython import array
+import array
+
+int_array_template = cython.declare(array.array, array.array('i', []))
+cython.declare(newarray=array.array)
+
+# create an array with 3 elements with same type as template
+newarray = array.clone(int_array_template, 3, zero=False)

docs/examples/tutorial/array/overhead.py

+from cython.cimports.cpython import array
+import array
+
+a = cython.declare(array.array, array.array('i', [1, 2, 3]))
+ca = cython.declare(cython.int[:], a)
+
+@cython.cfunc
+def overhead(a: cython.object) -> cython.int:
+    ca: cython.int[:] = a
+    return ca[0]
+
+@cython.cfunc
+def no_overhead(ca: cython.int[:]) -> cython.int:
+    return ca[0]
+
+print(overhead(a))  # new memory view will be constructed, overhead
+print(no_overhead(ca))  # ca is already a memory view, so no overhead

docs/examples/tutorial/array/overhead.pyx

@@ -4,10 +4,12 @@ import array
 cdef array.array a = array.array('i', [1, 2, 3])
 cdef int[:] ca = a
 
+
 cdef int overhead(object a):
     cdef int[:] ca = a
     return ca[0]
 
+
 cdef int no_overhead(int[:] ca):
     return ca[0]
 

docs/examples/tutorial/array/resize.py

+from cython.cimports.cpython import array
+import array
+
+a = cython.declare(array.array, array.array('i', [1, 2, 3]))
+b = cython.declare(array.array, array.array('i', [4, 5, 6]))
+
+# extend a with b, resize as needed
+array.extend(a, b)
+# resize a, leaving just original three elements
+array.resize(a, len(a) - len(b))

docs/examples/tutorial/array/safe_usage.py

+from cython.cimports.cpython import array
+import array
+a = cython.declare(array.array, array.array('i', [1, 2, 3]))
+ca = cython.declare(cython.int[:], a)
+
+print(ca[0])

docs/examples/tutorial/array/unsafe_usage.py

+from cython.cimports.cpython import array
+import array
+
+a = cython.declare(array.array, array.array('i', [1, 2, 3]))
+
+# access underlying pointer:
+print(a.data.as_ints[0])
+
+from cython.cimports.libc.string import memset
+
+memset(a.data.as_voidptr, 0, len(a) * cython.sizeof(cython.int))

docs/src/cimport-warning

 .. warning::
 
-    This code uses an external native (non-Python) library through a ``cimport``.
+    The code provided above / on this page uses an external
+    native (non-Python) library through a ``cimport`` (``cython.cimports``).
     Cython compilation enables this, but there is no support for this from
     plain Python. Trying to run this code from Python (without compilation)
     will fail when accessing the external library.

docs/src/tutorial/array.rst

@@ -4,6 +4,9 @@
 Working with Python arrays
 ==========================
 
+.. include::
+    ../two-syntax-variants-used
+
 Python has a builtin array module supporting dynamic 1-dimensional arrays of
 primitive types. It is possible to access the underlying C array of a Python
 array from within Cython. At the same time they are ordinary Python objects
@@ -18,7 +21,16 @@ module is built into both Python and Cython.
 Safe usage with memory views
 ----------------------------
 
-.. literalinclude:: ../../examples/tutorial/array/safe_usage.pyx
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/tutorial/array/safe_usage.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/tutorial/array/safe_usage.pyx
+
 
 NB: the import brings the regular Python array object into the namespace
 while the cimport adds functions accessible from Cython.
@@ -32,7 +44,15 @@ memory view, there will be a slight overhead to construct the memory
 view. However, from that point on the variable can be passed to other
 functions without overhead, so long as it is typed:
 
-.. literalinclude:: ../../examples/tutorial/array/overhead.pyx
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/tutorial/array/overhead.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/tutorial/array/overhead.pyx
 
 
 Zero-overhead, unsafe access to raw C pointer
@@ -42,7 +62,16 @@ functions, it is possible to access the underlying contiguous array as a
 pointer. There is no type or bounds checking, so be careful to use the
 right type and signedness.
 
-.. literalinclude:: ../../examples/tutorial/array/unsafe_usage.pyx
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/tutorial/array/unsafe_usage.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/tutorial/array/unsafe_usage.pyx
+
 
 Note that any length-changing operation on the array object may invalidate the
 pointer.
@@ -55,13 +84,30 @@ it is possible to create a new array with the same type as a template,
 and preallocate a given number of elements. The array is initialized to
 zero when requested.
 
-.. literalinclude:: ../../examples/tutorial/array/clone.pyx
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/tutorial/array/clone.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/tutorial/array/clone.pyx
+
 
 An array can also be extended and resized; this avoids repeated memory
 reallocation which would occur if elements would be appended or removed
 one by one.
 
-.. literalinclude:: ../../examples/tutorial/array/resize.pyx
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/tutorial/array/resize.py
+
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/tutorial/array/resize.pyx
 
 
 API reference
@@ -94,48 +140,142 @@ e.g., ``myarray.data.as_ints``.
 
 Functions
 ~~~~~~~~~
-The following functions are available to Cython from the array module::
+The following functions are available to Cython from the array module
+
+.. tabs::
+    .. group-tab:: Pure Python
 
-    int resize(array self, Py_ssize_t n) except -1
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.exceptval(-1)
+            def resize(self: array.array, n: cython.Py_ssize_t) -> cython.int
+
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef int resize(array.array self, Py_ssize_t n) except -1
 
 Fast resize / realloc. Not suitable for repeated, small increments; resizes
 underlying array to exactly the requested amount.
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.exceptval(-1)
+            def resize_smart(self: array.array, n: cython.Py_ssize_t) -> cython.int
 
-    int resize_smart(array self, Py_ssize_t n) except -1
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef int resize_smart(array.array self, Py_ssize_t n) except -1
 
 Efficient for small increments; uses growth pattern that delivers
 amortized linear-time appends.
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.inline
+            def clone(template: array.array, length: cython.Py_ssize_t, zero: cython.bint) -> array.array
+
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef inline array.array clone(array.array template, Py_ssize_t length, bint zero)
 
-    cdef inline array clone(array template, Py_ssize_t length, bint zero)
 
 Fast creation of a new array, given a template array. Type will be same as
 ``template``. If zero is ``True``, new array will be initialized with zeroes.
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.inline
+            def copy(self: array.array) -> array.array
 
-    cdef inline array copy(array self)
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef inline array.array copy(array.array self)
 
 Make a copy of an array.
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
 
-    cdef inline int extend_buffer(array self, char* stuff, Py_ssize_t n) except -1
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.inline
+            @cython.exceptval(-1)
+            def extend_buffer(self: array.array, stuff: cython.p_char, n: cython.Py_ssize_t) -> cython.int
+
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef inline int extend_buffer(array.array self, char* stuff, Py_ssize_t n) except -1
 
 Efficient appending of new data of same type (e.g. of same array type)
 ``n``: number of elements (not number of bytes!)
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.inline
+            @cython.exceptval(-1)
+            def extend(self: array.array, other: array.array) -> cython.int
 
-    cdef inline int extend(array self, array other) except -1
+    .. group-tab:: Cython
+
+        .. code-block:: cython
+
+            cdef inline int extend(array.array self, array.array other) except -1
 
 Extend array with data from another array; types must match.
 
-::
+----
+
+.. tabs::
+    .. group-tab:: Pure Python
+
+        .. code-block:: python
+
+            @cython.cfunc
+            @cython.inline
+            def zero(self: array.array) -> cython.void
+
+    .. group-tab:: Cython
+
+        .. code-block:: cython
 
-    cdef inline void zero(array self)
+            cdef inline void zero(array.array self)
 
 Set all elements of array to zero.