Replace uncomprehensible types by correctly modeled concepts

One of the goals of using type hints is to better document code and make maintenance and API use easier.

Types like tuple[list[OtbApp], list[Union[OtbApp, list[OtbApp]]], list[I2LabelT]] found here fail to achieve this goal.

Several cases of these have been added recently and merged into develop.

I am sorry to say that we can’t accept merging this kind of code. We need to strive for clarity and avoid obfuscation. Type signatures containing tuples of lists of unions should be banned.

In general, a tuple with more than 2 elements having different types is a bad design for a return type. In these cases, a dataclass is better, since the class name documents the concept being modelled and the field names document the parts composing the concept. In the above example, what is the meaning of the return type? Given the function name, one would expect a list of applications, but we get a tuple, and, what is the meaning of the first and second elements? Why are we returning a list of labels?

Also, types like list[Union[OtbApp, list[OtbApp]]] put too much burden on the API user (and therefore any future iota2 developer). I suppose that the idea here is to model an OTB application pipeline. And I understand that one can compose pipelines by pipeline concatenation, and therefore, if a pipeline is a list of applications, a composite pipeline may be a list of lists of applications. In my opinion, this means that we need an AppPipeline class that has a concatenation method which flattens the lists so that any composite pipeline is just a list of apps.