Allow homogeneous tuples as function arguments (pyccel#1850)

Allow 1D homogeneous tuples as function arguments. Fixes pyccel#738.
Homogeneous tuples as arguments already worked in the low level code as
homogeneous tuples are handled as arrays, however the wrapper was
missing which meant that such functions couldn't be called from Python.
In order to handle multi-level tuples some reorganisation of the wrapper
was necessary. Namely the introduction of the
`_extract_X_FunctionDefArgument` functions. However Python multi-level
tuples may have different lengths in the elements. It proved difficult
to check the size of the elements in a generic way so this was left for
later work (the obvious solution is to use lists to support this).

**Commit Summary**
- Update docs
- Update `BindCFunctionDefArgument` to handle tuples as strideless
arrays
- Add descriptions of more tuple functions from `Python.h`. Group these
functions together in `ast.cwrapper`
- Make `dtype` a searchable attribute of `SyntacticTypeAnnotation`
- Fix filter for used template type annotations so it also searches
through indexed elements to find objects in a tuple annotation.
- Add tests for tuples as arguments
- Rename `_get_check_function`->`_get_type_check_condition`.
- Allow `_get_type_check_condition` to return a condition which is not a
function call (e.g. a Variable)
- Add `body` argument to `_get_type_check_condition` to allow additional
commands to be run before determining if the type is correct.
- Add type checks for homogeneous tuples
- Introduce `_extract_X_FunctionDefArgument` functions to describe
container unpacking recursively
- Add `_extract_HomogeneousTupleType_FunctionDefArgument` function to
unpack 1D homogeneous tuples.
- Ensure errors are raised for multi-D tuples.

Author: EmilyBourne

CHANGELOG.md

@@ -43,6 +43,7 @@ All notable changes to this project will be documented in this file.
 -   #1937 : Optimise `pyccel.ast.basic.PyccelAstNode.substitute` method.
 -   #1544 : Add support for `typing.TypeAlias`.
 -   #1583 : Allow inhomogeneous tuples in classes.
+-   #738 : Add support for homogeneous tuples with scalar elements as arguments.
 -   Add a warning about containers in lists.
 -   \[INTERNALS\] Add abstract class `SetMethod` to handle calls to various set methods.
 -   \[INTERNALS\] Added `container_rank` property to `ast.datatypes.PyccelType` objects.

developer_docs/wrapper_stage.md

@@ -376,15 +376,17 @@ PyObject* func_name(PyObject* self, PyObject* args, PyObject* kwargs);
 
 The arguments and keyword arguments are unpacked into individual `PyObject` pointers.
 Each of these objects is checked to verify the type. If the type does not match the expected type then an error is raised as described in the [C-API documentation](https://docs.python.org/3/c-api/intro.html#exceptions).
-If the type does match then the value is unpacked into a C object. This is done using custom functions defined in `pyccel/stdlib/cwrapper/` or `pyccel/stdlib/cwrapper_ndarrays/` (see these files for more details).
+If the type does match then the value is unpacked into a C object. This is done using custom functions defined in `pyccel/stdlib/cwrapper/` or `pyccel/stdlib/cwrapper_ndarrays/` (see these files for more details) or using functions provided by `Python.h`.
+
+In order to create all the nodes necessary to describe the unpacking of the arguments we use functions named `_extract_X_FunctionDefArgument` where `X` is the type of the object being extracted from the `FunctionDefArgument`. This allows such functions to call each other recursively. This is notably useful for container types (tuples, lists, etc) whose elements may themselves be container types. The types of scalars are checked in the same way regardless of whether they are arguments or elements of a container so this also reduces code duplication.
 
 Once C objects have been retrieved the function is called normally.
 
 Finally all the arguments are packed into a Python tuple stored in a `PyObject` and are returned.
 
 The wrapper is attached to the module via a `PyMethodDef` (see C-API [docs](https://docs.python.org/3/c-api/structures.html#c.PyMethodDef)).
 
-#### Example
+#### Example 1
 
 The following Python code:
 ```python
@@ -543,6 +545,77 @@ PyObject* f_wrapper(PyObject* self, PyObject* args, PyObject* kwargs)
 }
 ```
 
+#### Example 2 : function with tuple arguments
+
+The following Python code:
+```python
+def get_first_element_of_tuple(a : 'tuple[int,...]'):
+    return a[0]
+```
+
+leads to C code with the following prototype (as homogeneous tuples are treated like arrays):
+```c
+int64_t get_first_element_of_tuple(t_ndarray a);
+```
+
+which is then wrapped as follows:
+```c
+static PyObject* get_first_element_of_tuple_wrapper(PyObject* self, PyObject* args, PyObject* kwargs)
+{
+    PyObject* a_obj;
+    t_ndarray a = {.shape = NULL};
+    int Dummy_0000;
+    int64_t a_size;
+    PyObject* Dummy_0001;
+    bool is_homog_tuple;
+    int64_t size;
+    int Dummy_0002;
+    PyObject* Dummy_0003;
+    int64_t Out_0001;
+    PyObject* Out_0001_obj;
+    static char *kwlist[] = {
+        "a",
+        NULL
+    };
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O", kwlist, &a_obj))
+    {
+        return NULL;
+    }
+    if (PyTuple_Check(a_obj))
+    {
+        size = PyTuple_Size(a_obj);
+        is_homog_tuple = 1;
+        for (Dummy_0002 = INT64_C(0); Dummy_0002 < size; Dummy_0002 += INT64_C(1))
+        {
+            Dummy_0003 = PyTuple_GetItem(a_obj, Dummy_0002);
+            is_homog_tuple = is_homog_tuple && PyIs_NativeInt(Dummy_0003);
+        }
+    }
+    else
+    {
+        is_homog_tuple = 0;
+    }
+    if (is_homog_tuple)
+    {
+        a_size = PyTuple_Size(a_obj);
+        a = array_create(1, (int64_t[]){a_size}, nd_int64, false, order_c);
+        for (Dummy_0000 = INT64_C(0); Dummy_0000 < a_size; Dummy_0000 += INT64_C(1))
+        {
+            Dummy_0001 = PyTuple_GetItem(a_obj, Dummy_0000);
+            GET_ELEMENT(a, nd_int64, (int64_t)Dummy_0000) = PyInt64_to_Int64(Dummy_0001);
+        }
+    }
+    else
+    {
+        PyErr_SetString(PyExc_TypeError, "Expected an argument of type tuple[int, ...] for argument a");
+        return NULL;
+    }
+    Out_0001 = get_first_element_of_tuple(a);
+    Out_0001_obj = Int64_to_PyLong(&Out_0001);
+    return Out_0001_obj;
+}
+```
+
 ### Interfaces
 
 Interfaces are functions which accept more than one type.

docs/type_annotations.md

@@ -41,7 +41,7 @@ In general string type hints must be used to provide Pyccel with information abo
 
 ## Tuples
 
-Currently tuples are supported locally in Pyccel but cannot be passed as arguments or returned. The implementation of the type annotations (as a first step to adding the missing support) is in progress. Currently homogeneous tuple type annotations are supported for local variables. See [Container types in Pyccel](./containers.md#tuples) for more information about tuple handling. When creating multiple dimensional tuples it is therefore important to ensure that all objects have compatible sizes otherwise they will be handled as inhomogeneous tuples.
+Currently Pyccel supports tuples used locally in functions and in certain cases as arguments, but not as returned objects or module variables. The implementation of the type annotations (including adding the missing support) is in progress. Currently homogeneous tuple type annotations are supported for local variables and function arguments (if the tuples contain scalar objects). Internally we handle homogeneous tuples as though they were NumPy arrays. When creating multiple dimensional tuples it is therefore important to ensure that all objects have compatible sizes otherwise they will be handled as inhomogeneous tuples.
 
 To declare a homogeneous tuple the syntax is as follows:
 ```python

pyccel/ast/bind_c.py

@@ -13,9 +13,13 @@
 from pyccel.ast.core import FunctionDef, ClassDef
 from pyccel.ast.core import FunctionDefArgument, FunctionDefResult
 from pyccel.ast.datatypes import FixedSizeType, PythonNativeInt
+from pyccel.ast.numpytypes import NumpyNDArrayType
 from pyccel.ast.variable import Variable
+from pyccel.errors.errors     import Errors
 from pyccel.utilities.metaclasses import Singleton
 
+errors = Errors()
+
 __all__ = (
     'BindCArrayVariable',
     'BindCClassDef',
@@ -203,9 +207,15 @@ def __init__(self, var, scope, original_arg_var, wrapping_bound_argument, **kwar
         shape   = [scope.get_temporary_variable(PythonNativeInt(),
                             name=f'{name}_shape_{i+1}')
                    for i in range(self._rank)]
-        strides = [scope.get_temporary_variable(PythonNativeInt(),
-                            name=f'{name}_stride_{i+1}')
-                   for i in range(self._rank)]
+        if isinstance(original_arg_var.class_type, NumpyNDArrayType):
+            strides = [scope.get_temporary_variable(PythonNativeInt(),
+                                name=f'{name}_stride_{i+1}')
+                       for i in range(self._rank)]
+        else:
+            if original_arg_var.rank > 1:
+                errors.report("Wrapping multi-level tuples is not yet supported",
+                        severity='fatal', symbol=original_arg_var)
+            strides = []
         self._shape = shape
         self._strides = strides
         self._original_arg_var = original_arg_var

pyccel/ast/cwrapper.py

@@ -971,21 +971,6 @@ def declarations(self):
                         arguments = [FunctionDefArgument(Variable(StringType(), name='_'))],
                         results = [FunctionDefResult(Variable(PyccelPyObject(), name='o', memory_handling='alias'))])
 
-# https://docs.python.org/3/c-api/list.html#c.PyList_GetItem
-PyList_GetItem = FunctionDef(name = 'PyList_GetItem',
-                        body = [],
-                        arguments = [FunctionDefArgument(Variable(PyccelPyObject(), name='l', memory_handling='alias')),
-                                     FunctionDefArgument(Variable(CNativeInt(), name='i'))],
-                        results = [FunctionDefResult(Variable(PyccelPyObject(), name='o', memory_handling='alias'))])
-
-# https://docs.python.org/3/c-api/list.html#c.PyList_SetItem
-PyList_SetItem = FunctionDef(name = 'PyList_SetItem',
-                        body = [],
-                        arguments = [FunctionDefArgument(Variable(PyccelPyObject(), name='l', memory_handling='alias')),
-                                     FunctionDefArgument(Variable(CNativeInt(), name='i')),
-                                     FunctionDefArgument(Variable(PyccelPyObject(), name='new_item', memory_handling='alias'))],
-                        results = [])
-
 #-------------------------------------------------------------------
 
 #using the documentation of PyArg_ParseTuple() and Py_BuildValue https://docs.python.org/3/c-api/arg.html
@@ -1084,28 +1069,73 @@ def C_to_Python(c_object):
             results = [FunctionDefResult(Variable(PythonNativeBool(), 'r'))],
             body = [])
 
+#-------------------------------------------------------------------
+#                          List functions
+#-------------------------------------------------------------------
+
+# https://docs.python.org/3/c-api/list.html#c.PyList_New
 PyList_New = FunctionDef(name = 'PyList_New',
                     arguments = [FunctionDefArgument(Variable(PythonNativeInt(), 'size'), value = LiteralInteger(0))],
                     results = [FunctionDefResult(Variable(PyccelPyObject(), 'r', memory_handling='alias'))],
                     body = [])
 
+# https://docs.python.org/3/c-api/list.html#c.PyList_Append
 PyList_Append = FunctionDef(name = 'PyList_Append',
                     arguments = [FunctionDefArgument(Variable(PyccelPyObject(), 'list', memory_handling='alias')),
                                  FunctionDefArgument(Variable(PyccelPyObject(), 'item', memory_handling='alias'))],
                     results = [FunctionDefResult(Variable(CNativeInt(), 'i'))],
                     body = [])
 
+# https://docs.python.org/3/c-api/list.html#c.PyList_GetItem
 PyList_GetItem = FunctionDef(name = 'PyList_GetItem',
                     arguments = [FunctionDefArgument(Variable(PyccelPyObject(), 'list', memory_handling='alias')),
                                  FunctionDefArgument(Variable(PythonNativeInt(), 'i'))],
                     results = [FunctionDefResult(Variable(PyccelPyObject(), 'item', memory_handling='alias'))],
                     body = [])
 
+# https://docs.python.org/3/c-api/list.html#c.PyList_Size
 PyList_Size = FunctionDef(name = 'PyList_Size',
                     arguments = [FunctionDefArgument(Variable(PyccelPyObject(), 'list', memory_handling='alias'))],
                     results = [FunctionDefResult(Variable(PythonNativeInt(), 'i'))],
                     body = [])
 
+# https://docs.python.org/3/c-api/list.html#c.PyList_SetItem
+PyList_SetItem = FunctionDef(name = 'PyList_SetItem',
+                        body = [],
+                        arguments = [FunctionDefArgument(Variable(PyccelPyObject(), name='l', memory_handling='alias')),
+                                     FunctionDefArgument(Variable(PythonNativeInt(), name='i')),
+                                     FunctionDefArgument(Variable(PyccelPyObject(), name='new_item', memory_handling='alias'))],
+                        results = [])
+
+#-------------------------------------------------------------------
+#                         Tuple functions
+#-------------------------------------------------------------------
+
+# https://docs.python.org/3/c-api/tuple.html#c.PyTuple_New
+PyTuple_New = FunctionDef(name = 'PyTuple_New',
+                    arguments = [FunctionDefArgument(Variable(PythonNativeInt(), 'size'), value = LiteralInteger(0))],
+                    results = [FunctionDefResult(Variable(PyccelPyObject(), 'tuple', memory_handling='alias'))],
+                    body = [])
+
+# https://docs.python.org/3/c-api/tuple.html#c.PyTuple_Check
+PyTuple_Check = FunctionDef(name = 'PyTuple_Check',
+                    arguments = [FunctionDefArgument(Variable(PyccelPyObject(), 'tuple', memory_handling='alias'))],
+                    results = [FunctionDefResult(Variable(CNativeInt(), 'i'))],
+                    body = [])
+
+# https://docs.python.org/3/c-api/tuple.html#c.PyTuple_Size
+PyTuple_Size = FunctionDef(name = 'PyTuple_Size',
+                    arguments = [FunctionDefArgument(Variable(PyccelPyObject(), 'tuple', memory_handling='alias'))],
+                    results = [FunctionDefResult(Variable(PythonNativeInt(), 'i'))],
+                    body = [])
+
+# https://docs.python.org/3/c-api/tuple.html#c.PyTuple_GetItem
+PyTuple_GetItem = FunctionDef(name = 'PyTuple_GetItem',
+                        body = [],
+                        arguments = [FunctionDefArgument(Variable(PyccelPyObject(), name='tuple', memory_handling='alias')),
+                                     FunctionDefArgument(Variable(PythonNativeInt(), name='i'))],
+                        results = [FunctionDefResult(Variable(PyccelPyObject(), name='o', memory_handling='alias'))])
+
 
 # Functions definitions are defined in pyccel/stdlib/cwrapper/cwrapper.c
 check_type_registry = {

pyccel/ast/datatypes.py

@@ -768,7 +768,7 @@ def __init__(self, element_type):
         super().__init__()
 
     def __str__(self):
-        return f'{self._name}[{self._element_type}, ...]'
+        return f'tuple[{self._element_type}, ...]'
 
 class HomogeneousListType(HomogeneousContainerType, metaclass = ArgumentSingleton):
     """

pyccel/ast/type_annotations.py

@@ -262,7 +262,7 @@ class SyntacticTypeAnnotation(PyccelAstNode):
         The order requested in the type annotation.
     """
     __slots__ = ('_dtype', '_order')
-    _attribute_nodes = ()
+    _attribute_nodes = ('_dtype',)
     def __init__(self, dtype, order = None):
         if not isinstance(dtype, (str, DottedName, IndexedElement)):
             raise ValueError("Syntactic datatypes should be strings")

pyccel/codegen/printing/ccode.py

@@ -1652,7 +1652,7 @@ def _print_Allocate(self, expr):
         variable = expr.variable
         if isinstance(variable.class_type, (HomogeneousListType, HomogeneousSetType, DictType)):
             return ''
-        if variable.rank > 0:
+        if isinstance(variable.class_type, (NumpyNDArrayType, HomogeneousTupleType)):
             #free the array if its already allocated and checking if its not null if the status is unknown
             if  (expr.status == 'unknown'):
                 shape_var = DottedVariable(VoidType(), 'shape', lhs = variable)
@@ -1679,7 +1679,10 @@ def _print_Allocate(self, expr):
             var_code = self._print(ObjectAddress(variable))
             if expr.like:
                 declaration_type = self.get_declare_type(expr.like)
-                return f'{var_code} = malloc(sizeof({declaration_type}));\n'
+                malloc_size = f'sizeof({declaration_type})'
+                if variable.rank:
+                    malloc_size = ' * '.join([malloc_size, *(self._print(s) for s in expr.shape)])
+                return f'{var_code} = malloc({malloc_size});\n'
             else:
                 raise NotImplementedError(f"Allocate not implemented for {variable}")
         else:

pyccel/codegen/printing/cwrappercode.py

@@ -86,7 +86,7 @@ def is_c_pointer(self, a):
         --------
         CCodePrinter.is_c_pointer : The extended function.
         """
-        if isinstance(a.dtype, (WrapperCustomDataType, BindCPointer)):
+        if isinstance(a.class_type, (WrapperCustomDataType, BindCPointer, CStackArray)):
             return True
         elif isinstance(a, (PyBuildValueNode, PyCapsule_New, PyCapsule_Import, PyModule_Create, LiteralString)):
             return True