Implement .NET async interop: await Task/ValueTask, async for IAsyncEnumerable, CancelledError

mikasoukhov · mikasoukhov · commit a1c16059450d · 2026-02-24T16:02:52.000+03:00
- Add TaskAwaitable/ValueTaskAwaitable wrappers enabling `await` on
  Task, Task&lt;T&gt;, ValueTask and ValueTask&lt;T&gt; from Python async code
- Add AsyncEnumerableWrapper enabling `async for` over IAsyncEnumerable&lt;T&gt;
- Map OperationCanceledException to new CancelledError Python exception
- Add __await__, __aiter__, __anext__ resolvers in PythonTypeInfo
- Add bridge methods in InstanceOps for the resolver pattern
- ValueTask/IAsyncEnumerable support gated behind #if NET (requires .NET Core)
- Handle Task&lt;VoidTaskResult&gt; (internal type arg) by falling back to
  non-generic TaskAwaitable via IsVisible check
diff --git a/eng/scripts/generate_exceptions.py b/eng/scripts/generate_exceptions.py
@@ -85,6 +85,7 @@ def MakeNewException(self):
         ExceptionInfo('Exception', 'IronPython.Runtime.Exceptions.PythonException', None, (), (
                 ExceptionInfo('StopIteration', 'IronPython.Runtime.Exceptions.StopIterationException', None, ('value',), ()),
                 ExceptionInfo('StopAsyncIteration', 'IronPython.Runtime.Exceptions.StopAsyncIterationException', None, ('value',), ()),
+                ExceptionInfo('CancelledError', 'System.OperationCanceledException', None, (), ()),
                 ExceptionInfo('ArithmeticError', 'System.ArithmeticException', None, (), (
                         ExceptionInfo('FloatingPointError', 'IronPython.Runtime.Exceptions.FloatingPointException', None, (), ()),
                         ExceptionInfo('OverflowError', 'System.OverflowException', None, (), ()),
diff --git a/src/core/IronPython/Modules/Builtin.Generated.cs b/src/core/IronPython/Modules/Builtin.Generated.cs
@@ -20,6 +20,7 @@ public static partial class Builtin {
         public static PythonType Exception => PythonExceptions.Exception;
         public static PythonType StopIteration => PythonExceptions.StopIteration;
         public static PythonType StopAsyncIteration => PythonExceptions.StopAsyncIteration;
+        public static PythonType CancelledError => PythonExceptions.CancelledError;
         public static PythonType ArithmeticError => PythonExceptions.ArithmeticError;
         public static PythonType FloatingPointError => PythonExceptions.FloatingPointError;
         public static PythonType OverflowError => PythonExceptions.OverflowError;
diff --git a/src/core/IronPython/Runtime/AsyncEnumerableWrapper.cs b/src/core/IronPython/Runtime/AsyncEnumerableWrapper.cs
@@ -0,0 +1,74 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+// IAsyncEnumerable<T> / IAsyncEnumerator<T> require .NET Core 3.0+
+#if NET
+
+#nullable enable
+
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+using Microsoft.Scripting.Runtime;
+
+using IronPython.Runtime.Exceptions;
+using IronPython.Runtime.Operations;
+using IronPython.Runtime.Types;
+
+namespace IronPython.Runtime {
+    /// <summary>
+    /// Wraps <see cref="IAsyncEnumerator{T}"/> to implement the Python
+    /// async iterator protocol (__aiter__, __anext__).
+    /// Returned by <see cref="InstanceOps.AsyncIterMethod{T}"/>.
+    /// </summary>
+    [PythonType("async_enumerator_wrapper")]
+    public sealed class AsyncEnumeratorWrapper<T> {
+        private readonly IAsyncEnumerator<T> _enumerator;
+
+        internal AsyncEnumeratorWrapper(IAsyncEnumerator<T> enumerator) {
+            _enumerator = enumerator;
+        }
+
+        public AsyncEnumeratorWrapper<T> __aiter__() => this;
+
+        /// <summary>
+        /// Returns an awaitable that, when awaited, advances the async enumerator
+        /// and returns the next value or raises StopAsyncIteration.
+        /// </summary>
+        public object __anext__() {
+            return new AsyncEnumeratorAwaitable<T>(_enumerator);
+        }
+    }
+
+    /// <summary>
+    /// The awaitable object returned by <see cref="AsyncEnumeratorWrapper{T}.__anext__"/>.
+    /// Implements both __await__ and __iter__/__next__ (the yield-from protocol) to
+    /// block on MoveNextAsync and return the current value via StopIteration.
+    /// </summary>
+    [PythonType("async_enumerator_awaitable")]
+    public sealed class AsyncEnumeratorAwaitable<T> {
+        private readonly IAsyncEnumerator<T> _enumerator;
+
+        internal AsyncEnumeratorAwaitable(IAsyncEnumerator<T> enumerator) {
+            _enumerator = enumerator;
+        }
+
+        public AsyncEnumeratorAwaitable<T> __await__() => this;
+
+        public AsyncEnumeratorAwaitable<T> __iter__() => this;
+
+        [LightThrowing]
+        public object __next__() {
+            bool hasNext = _enumerator.MoveNextAsync().AsTask().GetAwaiter().GetResult();
+            if (!hasNext) {
+                return LightExceptions.Throw(
+                    new PythonExceptions._StopAsyncIteration().InitAndGetClrException());
+            }
+            return LightExceptions.Throw(
+                new PythonExceptions._StopIteration().InitAndGetClrException(_enumerator.Current!));
+        }
+    }
+}
+
+#endif
diff --git a/src/core/IronPython/Runtime/Exceptions/PythonExceptions.Generated.cs b/src/core/IronPython/Runtime/Exceptions/PythonExceptions.Generated.cs
@@ -114,6 +114,17 @@ public _StopAsyncIteration(PythonType type) : base(type) { }
             public object value { get; set; }
         }
 
+        [MultiRuntimeAware]
+        private static PythonType CancelledErrorStorage;
+        public static PythonType CancelledError {
+            get {
+                if (CancelledErrorStorage == null) {
+                    Interlocked.CompareExchange(ref CancelledErrorStorage, CreateSubType(Exception, "CancelledError", (msg, innerException) => new System.OperationCanceledException(msg, innerException)), null);
+                }
+                return CancelledErrorStorage;
+            }
+        }
+
         [MultiRuntimeAware]
         private static PythonType ArithmeticErrorStorage;
         public static PythonType ArithmeticError {
@@ -935,6 +946,7 @@ public static PythonType ResourceWarning {
             if (clrException is StopAsyncIterationException) return new PythonExceptions._StopAsyncIteration();
             if (clrException is StopIterationException) return new PythonExceptions._StopIteration();
             if (clrException is SyntaxErrorException) return new PythonExceptions._SyntaxError();
+            if (clrException is OperationCanceledException) return new PythonExceptions.BaseException(PythonExceptions.CancelledError);
             if (clrException is SystemException) return new PythonExceptions.BaseException(PythonExceptions.SystemError);
             if (clrException is SystemExitException) return new PythonExceptions._SystemExit();
             if (clrException is UnboundNameException) return new PythonExceptions.BaseException(PythonExceptions.NameError);
diff --git a/src/core/IronPython/Runtime/Operations/InstanceOps.cs b/src/core/IronPython/Runtime/Operations/InstanceOps.cs
@@ -205,6 +205,47 @@ public static object NextMethod(object self) {
 
         #endregion
 
+        #region Async Interop
+
+        /// <summary>
+        /// Provides the implementation of __await__ for <see cref="System.Threading.Tasks.Task"/>.
+        /// </summary>
+        public static object TaskAwaitMethod(System.Threading.Tasks.Task self) {
+            return new TaskAwaitable(self);
+        }
+
+        /// <summary>
+        /// Provides the implementation of __await__ for <see cref="System.Threading.Tasks.Task{T}"/>.
+        /// </summary>
+        public static object TaskAwaitMethodGeneric<T>(System.Threading.Tasks.Task<T> self) {
+            return new TaskAwaitable<T>(self);
+        }
+
+#if NET
+        /// <summary>
+        /// Provides the implementation of __await__ for <see cref="System.Threading.Tasks.ValueTask"/>.
+        /// </summary>
+        public static object ValueTaskAwaitMethod(System.Threading.Tasks.ValueTask self) {
+            return new ValueTaskAwaitable(self);
+        }
+
+        /// <summary>
+        /// Provides the implementation of __await__ for <see cref="System.Threading.Tasks.ValueTask{T}"/>.
+        /// </summary>
+        public static object ValueTaskAwaitMethodGeneric<T>(System.Threading.Tasks.ValueTask<T> self) {
+            return new ValueTaskAwaitable<T>(self);
+        }
+
+        /// <summary>
+        /// Provides the implementation of __aiter__ for <see cref="IAsyncEnumerable{T}"/>.
+        /// </summary>
+        public static object AsyncIterMethod<T>(System.Collections.Generic.IAsyncEnumerable<T> self) {
+            return new AsyncEnumeratorWrapper<T>(self.GetAsyncEnumerator());
+        }
+#endif
+
+        #endregion
+
         /// <summary>
         /// __dir__(self) -> Returns the list of members defined on a foreign IDynamicMetaObjectProvider.
         /// </summary>
diff --git a/src/core/IronPython/Runtime/Operations/PythonOps.Generated.cs b/src/core/IronPython/Runtime/Operations/PythonOps.Generated.cs
@@ -125,6 +125,9 @@ public static partial class PythonOps {
         internal static Exception ModuleNotFoundError(string message) => new ModuleNotFoundException(message);
         public static Exception ModuleNotFoundError(string format, params object?[] args) => new ModuleNotFoundException(string.Format(format, args));
 
+        internal static Exception CancelledError(string message) => new System.OperationCanceledException(message);
+        public static Exception CancelledError(string format, params object?[] args) => new System.OperationCanceledException(string.Format(format, args));
+
         // *** END GENERATED CODE ***
 
         #endregion
diff --git a/src/core/IronPython/Runtime/TaskAwaitable.cs b/src/core/IronPython/Runtime/TaskAwaitable.cs
@@ -0,0 +1,110 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+#nullable enable
+
+using System.Threading.Tasks;
+
+using Microsoft.Scripting.Runtime;
+
+using IronPython.Runtime.Exceptions;
+using IronPython.Runtime.Types;
+
+namespace IronPython.Runtime {
+    /// <summary>
+    /// Provides an __await__ protocol wrapper for <see cref="Task"/>,
+    /// enabling <c>await task</c> from Python async code.
+    /// Blocks on the task and returns None via StopIteration.
+    /// </summary>
+    [PythonType("task_awaitable")]
+    public sealed class TaskAwaitable {
+        private readonly Task _task;
+
+        internal TaskAwaitable(Task task) {
+            _task = task;
+        }
+
+        public TaskAwaitable __await__() => this;
+
+        public TaskAwaitable __iter__() => this;
+
+        [LightThrowing]
+        public object __next__() {
+            _task.GetAwaiter().GetResult();
+            return LightExceptions.Throw(new PythonExceptions._StopIteration().InitAndGetClrException());
+        }
+    }
+
+    /// <summary>
+    /// Provides an __await__ protocol wrapper for <see cref="Task{T}"/>,
+    /// enabling <c>result = await task</c> from Python async code.
+    /// Blocks on the task and returns the result via StopIteration.value.
+    /// </summary>
+    [PythonType("task_awaitable")]
+    public sealed class TaskAwaitable<T> {
+        private readonly Task<T> _task;
+
+        internal TaskAwaitable(Task<T> task) {
+            _task = task;
+        }
+
+        public TaskAwaitable<T> __await__() => this;
+
+        public TaskAwaitable<T> __iter__() => this;
+
+        [LightThrowing]
+        public object __next__() {
+            T result = _task.GetAwaiter().GetResult();
+            return LightExceptions.Throw(new PythonExceptions._StopIteration().InitAndGetClrException(result!));
+        }
+    }
+
+#if NET
+    /// <summary>
+    /// Provides an __await__ protocol wrapper for <see cref="ValueTask"/>,
+    /// enabling <c>await valuetask</c> from Python async code.
+    /// </summary>
+    [PythonType("task_awaitable")]
+    public sealed class ValueTaskAwaitable {
+        private readonly ValueTask _task;
+
+        internal ValueTaskAwaitable(ValueTask task) {
+            _task = task;
+        }
+
+        public ValueTaskAwaitable __await__() => this;
+
+        public ValueTaskAwaitable __iter__() => this;
+
+        [LightThrowing]
+        public object __next__() {
+            _task.AsTask().GetAwaiter().GetResult();
+            return LightExceptions.Throw(new PythonExceptions._StopIteration().InitAndGetClrException());
+        }
+    }
+
+    /// <summary>
+    /// Provides an __await__ protocol wrapper for <see cref="ValueTask{T}"/>,
+    /// enabling <c>result = await valuetask</c> from Python async code.
+    /// </summary>
+    [PythonType("task_awaitable")]
+    public sealed class ValueTaskAwaitable<T> {
+        private readonly ValueTask<T> _task;
+
+        internal ValueTaskAwaitable(ValueTask<T> task) {
+            _task = task;
+        }
+
+        public ValueTaskAwaitable<T> __await__() => this;
+
+        public ValueTaskAwaitable<T> __iter__() => this;
+
+        [LightThrowing]
+        public object __next__() {
+            T result = _task.AsTask().GetAwaiter().GetResult();
+            return LightExceptions.Throw(new PythonExceptions._StopIteration().InitAndGetClrException(result!));
+        }
+    }
+#endif
+}
diff --git a/src/core/IronPython/Runtime/Types/PythonTypeInfo.cs b/src/core/IronPython/Runtime/Types/PythonTypeInfo.cs
@@ -10,6 +10,7 @@
 using System.Linq;
 using System.Numerics;
 using System.Reflection;
+using System.Threading.Tasks;
 
 using Microsoft.Scripting;
 using Microsoft.Scripting.Actions;
@@ -672,6 +673,9 @@ private class ProtectedMemberResolver : MemberResolver {
                 new OneOffResolver("__len__", LengthResolver),
                 new OneOffResolver("__format__", FormatResolver),
                 new OneOffResolver("__next__", NextResolver),
+                new OneOffResolver("__await__", AwaitResolver),
+                new OneOffResolver("__aiter__", AsyncIterResolver),
+                new OneOffResolver("__anext__", AsyncNextResolver),
 
                 new OneOffResolver("__complex__", ComplexResolver),
                 new OneOffResolver("__float__", FloatResolver),
@@ -965,6 +969,83 @@ internal static MemberGroup GetExtensionMemberGroup(Type type, MemberInfo[] news
             return MemberGroup.EmptyGroup;
         }
 
+        /// <summary>
+        /// Provides a resolution for __await__ on Task, Task&lt;T&gt;, ValueTask and ValueTask&lt;T&gt;.
+        /// </summary>
+        private static MemberGroup/*!*/ AwaitResolver(MemberBinder/*!*/ binder, Type/*!*/ type) {
+            foreach (Type t in binder.GetContributingTypes(type)) {
+                if (t.GetMember("__await__").Length > 0) {
+                    return MemberGroup.EmptyGroup;
+                }
+            }
+
+            if (typeof(Task).IsAssignableFrom(type)) {
+                if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Task<>)) {
+                    // Only use the generic TaskAwaitable<T> if the result type is visible
+                    // (e.g. Task.CompletedTask is Task<VoidTaskResult> at runtime where
+                    // VoidTaskResult is internal — fall back to non-generic TaskAwaitable)
+                    Type resultType = type.GetGenericArguments()[0];
+                    if (resultType.IsVisible) {
+                        MethodInfo genMeth = typeof(InstanceOps).GetMethod(nameof(InstanceOps.TaskAwaitMethodGeneric));
+                        return new MemberGroup(
+                            MethodTracker.FromMemberInfo(genMeth.MakeGenericMethod(type.GetGenericArguments()), type)
+                        );
+                    }
+                }
+                return GetInstanceOpsMethod(type, nameof(InstanceOps.TaskAwaitMethod));
+            }
+
+#if NET
+            if (type.IsGenericType) {
+                Type genDef = type.GetGenericTypeDefinition();
+                if (genDef == typeof(ValueTask<>)) {
+                    MethodInfo genMeth = typeof(InstanceOps).GetMethod(nameof(InstanceOps.ValueTaskAwaitMethodGeneric));
+                    return new MemberGroup(
+                        MethodTracker.FromMemberInfo(genMeth.MakeGenericMethod(type.GetGenericArguments()), type)
+                    );
+                }
+            }
+
+            if (type == typeof(ValueTask)) {
+                return GetInstanceOpsMethod(type, nameof(InstanceOps.ValueTaskAwaitMethod));
+            }
+#endif
+
+            return MemberGroup.EmptyGroup;
+        }
+
+        /// <summary>
+        /// Provides a resolution for __aiter__ on IAsyncEnumerable&lt;T&gt;.
+        /// </summary>
+        private static MemberGroup/*!*/ AsyncIterResolver(MemberBinder/*!*/ binder, Type/*!*/ type) {
+#if NET
+            foreach (Type t in binder.GetContributingTypes(type)) {
+                if (t.GetMember("__aiter__").Length > 0) {
+                    return MemberGroup.EmptyGroup;
+                }
+            }
+
+            foreach (Type t in binder.GetInterfaces(type)) {
+                if (t.IsGenericType && t.GetGenericTypeDefinition() == typeof(IAsyncEnumerable<>)) {
+                    MethodInfo genMeth = typeof(InstanceOps).GetMethod(nameof(InstanceOps.AsyncIterMethod));
+                    return new MemberGroup(
+                        MethodTracker.FromMemberInfo(genMeth.MakeGenericMethod(t.GetGenericArguments()), type)
+                    );
+                }
+            }
+#endif
+
+            return MemberGroup.EmptyGroup;
+        }
+
+        /// <summary>
+        /// Provides a resolution for __anext__ on AsyncEnumeratorWrapper&lt;T&gt;.
+        /// Not auto-mapped from interfaces; the wrapper class provides __anext__ directly.
+        /// </summary>
+        private static MemberGroup/*!*/ AsyncNextResolver(MemberBinder/*!*/ binder, Type/*!*/ type) {
+            return MemberGroup.EmptyGroup;
+        }
+
         /// <summary>
         /// Provides a resolution for __len__
         /// </summary>
diff --git a/tests/IronPython.Tests/AsyncInteropHelpers.cs b/tests/IronPython.Tests/AsyncInteropHelpers.cs
diff --git a/tests/suite/test_async.py b/tests/suite/test_async.py
