Add support for functions returning variadic tuples (tuple[T, ...])

[atifaziz]

In PR #669, the parser recognised variadic tuples (tuple[T, ...], variable-length tuples with homogeneous element types, but that was about it. This PR adds full support for Python functions that return tuples of unknown length but known element type, such as tuple[int, ...] or tuple[tuple[int, str], ...].

Design

The implementation introduces a new Python type construct VariadicTupleType that represents tuples with an ellipsis syntax (tuple[T, ...]). Unlike fixed-length tuples (TupleType) which have a known number of elements with potentially different types, variadic tuples have a variable number of elements where all elements are of the same type.

Note that variadic tuples are only supported in return position. This PR does not support variadic tuples in argument position, which is something that can be added in the future. Meanwhile, returning variadic tuples seems a lot more common & useful in Python.

Key Design Decisions:

1. Immutable Collections: Variadic tuples are mapped to .NET's ImmutableArray<T> rather than IReadOnlyList<T> to provide better performance and immutability guarantees that match Python's tuple semantics. Another option would be to return a regular array since the immutability does not need to be strictly maintained on the C# side.

2. Type Safety: The implementation preserves full type safety by generating strongly-typed importer classes that handle the conversion from Python tuples to .NET immutable arrays.

3. Consistent API: The feature integrates seamlessly with the existing type system and follows the same patterns as other collection types (sequences, dictionaries, etc.). Behaviourally, however, the tuple elements are marshaled and converted eagerly (which can be seen as a feature).

Technical Implementation

Core Components

1. Type System Extensions

• VariadicTupleType: A new record type in PythonTypeSpec.cs representing tuple[T, ...] syntax
• Type Reflection: Extended TypeReflection.AsPredefinedType() to map VariadicTupleType to ImmutableArray<T> for FromPython conversions
• Parser Support: See PR Add PythonTypeSpec subclasses for recognised Python types #669.

2. Runtime Support

• VarTuple<T, TImporter>: A new importer class in PyObjectImporters.cs that handles the conversion from Python tuple objects to ImmutableArray<T>
• Efficient Conversion: Uses ImmutableArray.CreateBuilder<T>() for optimal performance when converting variable-length Python tuples, including dimensioning the array to the correct capacity.

3. Code Generation

• Result Conversion: Extended ResultConversionCodeGenerator to generate appropriate conversion code for variadic tuple return types
• Method Signatures: Generated C# methods return ImmutableArray<T> for variadic tuple results

Example Usage

Python Code

def get_coordinate_pairs(points: list[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
    return tuple(points)

def get_names() -> tuple[str, ...]:
    return ("Alice", "Bob", "Charlie")

Generated C# Interface

public interface IMyModule
{
    ImmutableArray<(long, long)> GetCoordinatePairs(IReadOnlyList<(long, long)> points);
    ImmutableArray<string> GetNames();
}

Breaking Changes

None. This is a pure additive feature that doesn't affect existing APIs or functionality.