Remove InhomogeneousTupleVariable (pyccel#1838)

Remove the `InhomogeneousTupleVariable` class. Fixes pyccel#1583 There is now
enough information in the types to make this class unnecessary. Removing
it allows inhomogeneous tuples to be used in classes (as it was
previously not possible to combine `DottedVariable` and
`InhomogeneousTupleVariable`).

**Commit Summary**
- Use the `symbolic_alias` category in a `Scope` to map an indexed
element of an inhomogeneous tuple to the equivalent variable.
- Create `_build_X` functions for functions which accept inhomogeneous
tuple arguments (created `SemanticParser._build_PythonTupleFunction` and
`SemanticParser._build_NumpyArray`). This allows the variables to be
collected from the scope during the building process
- Allow a `PyccelUnarySub` to be used as an index (to facilitate
indexing with literals)
- Add a `is_literal_integer` function to determine if an expression is a
literal integer
- Recognise inhomogeneous tuples via their class type
- Remove `InhomogeneousTupleVariable`
- Ensure `IndexedElement` can handle inhomogeneous tuple objects.
- Don't declare inhomogeneous tuples (their elements are now already
present in the scope)
- Clarify use of dtype/class type in `FCodePrinter._print_Declare`
- Correct type annotation printing in Python (quotes are no longer
present to be removed)
- Raise a warning if trying to wrap tuples
- Clean up tuple handling in `_visit_Assign`. Fixes pyccel#1392 
- Extract printed inhomogenous tuple variables into `PythonTuple` at the
semantic stage
- Increase coverage
- Add a test for inhomogeneous tuples in classes

Author: EmilyBourne

CHANGELOG.md

@@ -31,6 +31,7 @@ All notable changes to this project will be documented in this file.
 -   #1936 : Add missing C output for inline decorator example in documentation
 -   #1937 : Optimise `pyccel.ast.basic.PyccelAstNode.substitute` method.
 -   #1544 : Add support for `typing.TypeAlias`.
+-   #1583 : Allow inhomogeneous tuples in classes.
 -   \[INTERNALS\] Added `container_rank` property to `ast.datatypes.PyccelType` objects.
 -   \[DEVELOPER\] Added an improved traceback to the developer-mode errors for errors in function calls.
 

developer_docs/tuples.md

@@ -0,0 +1,8 @@
+# Tuples
+
+In Pyccel tuples require special handling. There are 2 main use cases. The first use case is tuples as a small collection of objects of the same type. This case is handled by homogeneous tuples (for more details see the [user docs](../docs/containers.md)). This case is relatively easy to handle as it works similarly to all other containers. The second case is much more tricky. In this case a tuple is an object which allows objects of different types to be grouped together. In this case Pyccel must treat the objects symbolically.
+
+In order to handle the translation of inhomogeneous tuples Pyccel creates variables for each of the elements of the inhomogeneous tuples. The names of these elements are chosen to keep the code as close to the original as possible. Therefore for a tuple stored in a variable `var` the element `var[0]` is usually translated to a variable called `var_0`. This handling of tuples is mostly made possible via the `Scope`.
+Whenever a variable representing a tuple element is created it must be associated with the `IndexedElement` via the `Scope`. This is done by calling the function `Scope.insert_symbolic_alias` (e.g. `insertion_scope.insert_symbolic_alias(IndexedElement(lhs, i), v)`).
+Once the symbolic alias has been created the function `Scope.collect_tuple_element` allows the variable to be retrieved from the `IndexedElement`.
+The `IndexedElement` representation of the inhomogeneous tuple element is a purely symbolic object and should not appear in generated code. Care must therefore be taken to ensure that `Scope.collect_tuple_element` is used whenever elements are extracted from a tuple.

docs/containers.md

@@ -0,0 +1,87 @@
+# Container types in Pyccel
+
+Pyccel provides support for some container types with certain limits. The types that are currently supported are:
+-   NumPy arrays
+-   Tuples
+
+## NumPy arrays
+
+NumPy arrays are provided as part of the NumPy support. There is dedicated documentation which explains the limitations and implementation details. See [N-dimensional array](./ndarrays.md) for more details.
+
+## Tuples
+
+In Pyccel tuples are divided into two types: homogeneous and inhomogeneous. Homogeneous tuples are objects where all elements of the container have the same type while inhomogeneous tuples can contain objects of different types. These two types are handled differently and therefore have very different restrictions.
+
+Currently Pyccel cannot wrap tuples so they can be used in functions but cannot yet be exposed to Python.
+
+### Homogeneous tuples
+
+Homogeneous tuples are handled as though they were arrays. This means that they have the same restrictions and advantages as NumPy arrays. In particular they can be indexed at an arbitrary point.
+
+Elements of a homogeneous tuple should have the same type, the same number of dimensions, and (if relevant) the same NumPy ordering. If any of these constraints is not respected then you may unexpectedly find yourself using the more inflexible inhomogeneous tuples. Further tuples containing pointers to other objects cannot always be stored in a homogeneous tuple.
+
+### Inhomogeneous tuples
+
+Inhomogeneous tuples are handled symbolically. This means that an inhomogeneous tuple is treated as a collection of translatable objects. Each of these objects is then handled individually. In particular this means that tuples can only be indexed by compile-time constants.
+
+For example the following code:
+```python
+def f():
+    a = (1, True, 3.0)
+    print(a)
+    b = a[0]+2
+    return a[2]
+```
+is translated to the following C code:
+```c
+double f(void)
+{
+    int64_t a_0;
+    bool a_1;
+    double a_2;
+    int64_t b;
+    a_0 = INT64_C(1);
+    a_1 = 1;
+    a_2 = 3.0;
+    printf("%s%"PRId64"%s%s%s%.15lf%s\n", "(", a_0, ", ", a_1 ? "True" : "False", ", ", a_2, ")");
+    b = a_0 + INT64_C(2);
+    return a_2;
+}
+```
+and the following Fortran code:
+```fortran
+  function f() result(Out_0001)
+
+    implicit none
+
+    real(f64) :: Out_0001
+    integer(i64) :: a_0
+    logical(b1) :: a_1
+    real(f64) :: a_2
+    integer(i64) :: b
+
+    a_0 = 1_i64
+    a_1 = .True._b1
+    a_2 = 3.0_f64
+    write(stdout, '(A, I0, A, A, A, F0.15, A)', advance="no") '(' , a_0 &
+          , ', ' , merge("True ", "False", a_1) , ', ' , a_2 , ')'
+    write(stdout, '()', advance="yes")
+    b = a_0 + 2_i64
+    Out_0001 = a_2
+    return
+
+  end function f
+```
+
+But the following code will raise an error:
+```python
+def f():
+    a = (1, True, 3.0)
+    i = 2
+    print(a[i])
+```
+```
+ERROR at annotation (semantic) stage
+pyccel:
+ |fatal [semantic]: foo.py [4,10]| Inhomogeneous tuples must be indexed with constant integers for the type inference to work (a)
+```

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. Internally we handle homogeneous tuples as thought 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.
+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.
 
 To declare a homogeneous tuple the syntax is as follows:
 ```python

pyccel/ast/builtins.py

@@ -27,7 +27,7 @@
 from .literals  import LiteralString
 from .operators import PyccelAdd, PyccelAnd, PyccelMul, PyccelIsNot
 from .operators import PyccelMinus, PyccelUnarySub, PyccelNot
-from .variable  import IndexedElement, Variable, InhomogeneousTupleVariable
+from .variable  import IndexedElement, Variable
 
 pyccel_stage = PyccelStage()
 
@@ -606,24 +606,12 @@ class PythonTupleFunction(TypedAstNode):
     different to the `(,)` syntax as it only takes one argument
     and unpacks any variables.
 
-    Parameters
-    ----------
-    arg : TypedAstNode
-        The argument passed to the function call.
+    This class should not be used to create an instance, it is
+    simply a place-holder to indicate the class to the semantic parser.
     """
     __slots__ = ()
     _attribute_nodes = ()
 
-    def __new__(cls, arg):
-        if isinstance(arg, PythonTuple):
-            return arg
-        elif isinstance(arg, (PythonList, InhomogeneousTupleVariable)):
-            return PythonTuple(*arg)
-        elif isinstance(arg.shape[0], LiteralInteger):
-            return PythonTuple(*[arg[i] for i in range(arg.shape[0])])
-        else:
-            raise TypeError(f"Can't unpack {arg} into a tuple")
-
 #==============================================================================
 class PythonLen(PyccelFunction):
     """
@@ -1377,7 +1365,7 @@ class PythonType(PyccelFunction):
     __slots__ = ('_type','_obj')
     _attribute_nodes = ('_obj',)
     _class_type = SymbolicType()
-    _shape = ()
+    _shape = None
 
     def __init__(self, obj):
         if not isinstance (obj, TypedAstNode):

pyccel/ast/numpyext.py

@@ -697,30 +697,8 @@ class NumpyArray(NumpyNewArray):
 
     def __init__(self, arg, dtype=None, order='K', ndmin=None):
 
-        if not isinstance(arg, (PythonTuple, PythonList, Variable, IndexedElement)):
-            raise TypeError(f'Unknown type of  {type(arg)}')
-
-        is_homogeneous_tuple = isinstance(arg.class_type, HomogeneousTupleType)
-        # Inhomogeneous tuples can contain homogeneous data if it is inhomogeneous due to pointers
-        if isinstance(arg.class_type, InhomogeneousTupleType):
-            is_homogeneous_tuple = isinstance(arg.dtype, FixedSizeNumericType) and len(set(a.rank for a in arg))
-            if not isinstance(arg, PythonTuple):
-                arg = PythonTuple(*arg)
-
-        # TODO: treat inhomogenous lists and tuples when they have mixed ordering
-        if not (is_homogeneous_tuple or isinstance(arg.class_type, HomogeneousContainerType)):
-            raise TypeError('we only accept homogeneous arguments')
-
-        if not isinstance(order, (LiteralString, str)):
-            raise TypeError("The order must be specified explicitly with a string.")
-        elif isinstance(order, LiteralString):
-            order = order.python_value
-
-        if ndmin is not None:
-            if not isinstance(ndmin, (LiteralInteger, int)):
-                raise TypeError("The minimum number of dimensions must be specified explicitly with an integer.")
-            elif isinstance(ndmin, LiteralInteger):
-                ndmin = ndmin.python_value
+        assert isinstance(arg, (PythonTuple, PythonList, Variable, IndexedElement))
+        assert isinstance(order, str)
 
         init_dtype = dtype
 

pyccel/ast/operators.py

@@ -358,6 +358,9 @@ class PyccelUnarySub(PyccelUnary):
     def __repr__(self):
         return f'-{repr(self.args[0])}'
 
+    def __index__(self):
+        return -int(self.args[0])
+
 #==============================================================================
 
 class PyccelNot(PyccelUnaryOperator):

pyccel/ast/utilities.py

@@ -19,7 +19,7 @@
 from .builtins      import (builtin_functions_dict,
                             PythonRange, PythonList, PythonTuple, PythonSet)
 from .cmathext      import cmath_mod
-from .datatypes     import HomogeneousTupleType, PythonNativeInt
+from .datatypes     import HomogeneousTupleType, InhomogeneousTupleType, PythonNativeInt
 from .internals     import PyccelFunction, Slice
 from .itertoolsext  import itertools_mod
 from .literals      import LiteralInteger, LiteralEllipsis, Nil
@@ -29,9 +29,10 @@
 from .numpyext      import (NumpyEmpty, NumpyArray, numpy_mod,
                             NumpyTranspose, NumpyLinspace)
 from .operators     import PyccelAdd, PyccelMul, PyccelIs, PyccelArithmeticOperator
+from .operators     import PyccelUnarySub
 from .scipyext      import scipy_mod
 from .typingext     import typing_mod
-from .variable      import (Variable, IndexedElement, InhomogeneousTupleVariable )
+from .variable      import Variable, IndexedElement
 
 from .c_concepts import ObjectAddress
 
@@ -732,8 +733,8 @@ def expand_inhomog_tuple_assignments(block, language_has_vectors = False):
         block.substitute(allocs_to_unravel, new_allocs)
 
     assigns = [a for a in block.get_attribute_nodes(Assign) \
-                if isinstance(a.lhs, InhomogeneousTupleVariable) \
-                and isinstance(a.rhs, (PythonTuple, InhomogeneousTupleVariable))]
+                if isinstance(a.lhs.class_type, InhomogeneousTupleType) \
+                and isinstance(a.rhs, (PythonTuple, Variable))]
     if len(assigns) != 0:
         new_assigns = [[Assign(l,r) for l,r in zip(a.lhs, a.rhs)] for a in assigns]
         block.substitute(assigns, new_assigns)
@@ -796,3 +797,25 @@ def expand_to_loops(block, new_index, scope, language_has_vectors = False):
     body = [bi for b in body for bi in b]
 
     return body
+
+#==============================================================================
+def is_literal_integer(expr):
+    """
+    Determine whether the expression is a literal integer.
+
+    Determine whether the expression is a literal integer. A literal integer
+    can be described by a LiteralInteger, a PyccelUnarySub(LiteralInteger) or
+    a Constant.
+
+    Parameters
+    ----------
+    expr : object
+        Any Python object which should be analysed to determine whether it is an integer.
+
+    Returns
+    -------
+    bool
+        True if the object represents a literal integer, false otherwise.
+    """
+    return isinstance(expr, (int, LiteralInteger)) or \
+        isinstance(expr, PyccelUnarySub) and isinstance(expr.args[0], (int, LiteralInteger))