Introduce pure Python mode in the "language basics" documentation (GH-4242)

See https://github.com/cython/cython/issues/4187

docs/examples/userguide/extension_types/shrubbery.py

+from __future__ import print_function
+
+@cython.cclass
+class Shrubbery:
+    width: cython.int
+    height: cython.int
+
+    def __init__(self, w, h):
+        self.width = w
+        self.height = h
+
+    def describe(self):
+        print("This shrubbery is", self.width,
+              "by", self.height, "cubits.")

docs/examples/userguide/extension_types/shrubbery.pyx

 from __future__ import print_function
 
+
 cdef class Shrubbery:
-    cdef int width, height
+    cdef int width
+    cdef int height
 
     def __init__(self, w, h):
         self.width = w

docs/examples/userguide/language_basics/casting_python.pxd

+cdef extern from *:
+    ctypedef Py_ssize_t Py_intptr_t

docs/examples/userguide/language_basics/casting_python.py

+from cython.cimports.cpython.ref import PyObject
+
+def main():
+
+    python_string = "foo"
+
+    # Note that the variables below are automatically inferred
+    # as the correct pointer type that is assigned to them.
+    # They do not need to be typed explicitly.
+
+    ptr = cython.cast(cython.p_void, python_string)
+    adress_in_c = cython.cast(Py_intptr_t, ptr)
+    address_from_void = adress_in_c        # address_from_void is a python int
+
+    ptr2 = cython.cast(cython.pointer(PyObject), python_string)
+    address_in_c2 = cython.cast(Py_intptr_t, ptr2)
+    address_from_PyObject = address_in_c2  # address_from_PyObject is a python int
+
+    assert address_from_void == address_from_PyObject == id(python_string)
+
+    print(cython.cast(object, ptr))                     # Prints "foo"
+    print(cython.cast(object, ptr2))                    # prints "foo"

docs/examples/userguide/language_basics/open_file.py

+from cython.cimports.libc.stdio import FILE, fopen
+from cython.cimports.libc.stdlib import malloc, free
+from cython.cimports.cpython.exc import PyErr_SetFromErrnoWithFilenameObject
+
+def open_file():
+    p = fopen("spam.txt", "r")   # The type of "p" is "FILE*", as returned by fopen().
+
+    if p is cython.NULL:
+        PyErr_SetFromErrnoWithFilenameObject(OSError, "spam.txt")
+    ...
+
+
+def allocating_memory(number=10):
+    # Note that the type of the variable "my_array" is automatically inferred from the assignment.
+    my_array = cython.cast(p_double, malloc(number * cython.sizeof(double)))
+    if not my_array:  # same as 'is NULL' above
+        raise MemoryError()
+    ...
+    free(my_array)

docs/examples/userguide/language_basics/optional_subclassing.py

+from __future__ import print_function
+
+@cython.cclass
+class A:
+    @cython.cfunc
+    def foo(self):
+        print("A")
+
+@cython.cclass
+class B(A):
+    @cython.cfunc
+    def foo(self, x=None):
+        print("B", x)
+
+@cython.cclass
+class C(B):
+    @cython.ccall
+    def foo(self, x=True, k:cython.int = 3):
+        print("C", x, k)

docs/examples/userguide/language_basics/optional_subclassing.pyx

 from __future__ import print_function
 
+
 cdef class A:
+
     cdef foo(self):
         print("A")
 
+
 cdef class B(A):
+
     cdef foo(self, x=None):
         print("B", x)
 
+
 cdef class C(B):
+
     cpdef foo(self, x=True, int k=3):
         print("C", x, k)

docs/examples/userguide/language_basics/override.py

+from __future__ import print_function
+
+@cython.cclass
+class A:
+    @cython.cfunc
+    def foo(self):
+        print("A")
+
+@cython.cclass
+class B(A):
+    @cython.ccall
+    def foo(self):
+        print("B")
+
+class C(B):  # NOTE: no cclass decorator
+    def foo(self):
+        print("C")

docs/examples/userguide/language_basics/override.pyx

 from __future__ import print_function
 
+
 cdef class A:
+
     cdef foo(self):
         print("A")
 
+
 cdef class B(A):
+
     cpdef foo(self):
         print("B")
 

docs/examples/userguide/language_basics/parameter_refcount.py

+from __future__ import print_function
+
+from cython.cimports.cpython.ref import PyObject
+
+import sys
+
+python_dict = {"abc": 123}
+python_dict_refcount = sys.getrefcount(python_dict)
+
+@cython.cfunc
+def owned_reference(obj: object):
+    refcount = sys.getrefcount(python_dict)
+    print('Inside owned_reference: {refcount}'.format(refcount=refcount))
+
+@cython.cfunc
+def borrowed_reference(obj: cython.pointer(PyObject)):
+    refcount = obj.ob_refcnt
+    print('Inside borrowed_reference: {refcount}'.format(refcount=refcount))
+
+def main():
+    print('Initial refcount: {refcount}'.format(refcount=python_dict_refcount))
+    owned_reference(python_dict)
+    borrowed_reference(cython.cast(cython.pointer(PyObject), python_dict))

docs/examples/userguide/language_basics/parameter_refcount.pyx

@@ -7,14 +7,17 @@ import sys
 python_dict = {"abc": 123}
 python_dict_refcount = sys.getrefcount(python_dict)
 
+
 cdef owned_reference(object obj):
     refcount = sys.getrefcount(python_dict)
     print('Inside owned_reference: {refcount}'.format(refcount=refcount))
 
+
 cdef borrowed_reference(PyObject * obj):
     refcount = obj.ob_refcnt
     print('Inside borrowed_reference: {refcount}'.format(refcount=refcount))
 
+
 print('Initial refcount: {refcount}'.format(refcount=python_dict_refcount))
 owned_reference(python_dict)
 borrowed_reference(<PyObject *>python_dict)

docs/examples/userguide/language_basics/struct_union_enum.py

+Grail = cython.struct(
+    age=cython.int,
+    volume=cython.float)
+
+Food = cython.union(
+    spam=cython.p_char,
+    eggs=cython.p_float)