docs/advanced.md

@@ -157,4 +157,4 @@ Beyond the C# [limitations](https://learn.microsoft.com/visualstudio/debugger/su
 - Changing the name of a function
 - Changing the name of a module
 
-The Hot Reload feature is useful for iterating on the __body__ of a Python function, without having to restart the debugger or application.
+The Hot Reload feature is useful for iterating on the __body__ of a Python function, without having to restart the debugger or application.

docs/async_support.md

@@ -0,0 +1,52 @@
+# Async support
+
+Python async functions will be generated into async C# methods. The generated C# method will return a `Task<T>` depending on the return type of the Python function. 
+
+CSnakes requires strict typing for async functions. This means that the return type of the Python function must be annotated with the `typing.Coroutine[TYield, TSend, TReturn]` type hint:
+
+```python
+import asyncio
+from typing import Coroutine
+
+async def async_function() -> Coroutine[int, None, None]:
+    await asyncio.sleep(1)
+    return 42
+```
+
+The generated C# method will have this signature:
+
+
+```csharp
+public async Task<int> AsyncFunction();
+```
+
+Python async functions can be awaited in C# code.
+
+## TSend and TResult
+
+CSnakes only supports `Task<TYield>` where `TYield` is `Coroutine[TYield, ..., ...]`. You cannot send values back into the coroutine object.
+
+## Implementation Details
+
+The [C# Async model](https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and the Python Async models have some important differences:
+
+- C# creates a task pool and tasks are scheduled on this pool. Python uses a single-threaded event loop.
+- Python event loops belong to the thread that created them. C# tasks can be scheduled on any thread.
+- Python async functions are coroutines that are scheduled on the event loop. C# async functions are tasks that are scheduled on the task pool.
+
+To converge these two models, CSnakes creates a Python event-loop for each C# thread that calls into Python. This event loop is created when the first Python function is called and is destroyed when the thread is disposed. This event loop is used to schedule the Python async functions.
+Because C# reuses threads in the Task pool, the event loop is reused and kept as a thread-local variable.
+
+The behavior is abstracted away from the user, but it is important to understand that the Python event loop is created and destroyed for each C# thread that calls into Python. This is important to understand when debugging or profiling your application.
+
+## Parallelism considerations
+
+Event though C# uses a thread-pool to schedule tasks, the Python Global Interpreter Lock (GIL) will prevent multiple Python threads from running in parallel.
+This means that even if you use parallel LINQ or other parallel constructs in C#, CPU-bound Python code will mostly run in a single thread at a time.
+
+Python 3.13 and above have a feature called "free-threading mode" which allows the Python interpreter to run in a multi-threaded environment without the Global Interpreter Lock (GIL). This is a significant change to the Python runtime and can have a big impact on the performance of Python code running in a multi-threaded environment.
+See [Free-Threading Mode](advanced.md#free-threading-mode) for more information.
+
+## Cancellation Tokens
+
+Coroutine objects have an `AsTask<TYield>(CancellationToken?)` API, but the source generator does not yet propagate the cancellation token argument to the generated interfaces, if you want to use cancellation tokens, please raise an issue with your use case.

docs/reference.md

@@ -21,9 +21,9 @@ CSnakes supports the following typed scenarios:
 | `typing.Optional[T]`   | `T?`              |
 | `typing.Generator[TYield, TSend, TReturn]` | `IGeneratorIterator<TYield, TSend, TReturn>` [1](#generators) |
 | `typing.Buffer`        | `IPyBuffer` [2](buffers.md) |
+| `typing.Coroutine[TYield, TSend, TReturn]` | `Task<TYield>` [3](async_support.md) |
 | `None` (Return)        | `void`            |
 
-
 ### Return types
 
 The same type conversion applies for the return type of the Python function, with the additional feature that functions which explicitly return type `None` are declared as `void` in C#.
@@ -294,3 +294,41 @@ The type of `.Send` is the `TSend` type parameter of the `Generator` type annota
 var generator = env.ExampleGenerator(5);
 string nextValue= generator.Send(10);
 ```
+
+
+## Running any Python code
+
+Sometimes you may want to run Python code that doesn't have type annotations or is not part of a module. You can use the `Run` method on the `IPythonEnvironment` to execute any Python code.
+
+Python has two ways to do, this "expressions" and "statements". Expressions return a value and are a single line. You can use the `ExecuteExpression` method to run an expression and get the result back:
+
+```csharp
+env.ExecuteExpression("1+1").As<int>() ; // 2
+```
+
+You can pass a dictionary of local and/or global variables:
+
+```csharp
+var locals = new Dictionary<string, PyObject>
+{
+    ["a"] = PyObject.From(101)
+};
+using var result = env.ExecuteExpression("a+1", locals); // 102
+```
+
+To execute a series of statements, you can use the `Execute` method, which also takes globals and locals:
+```csharp
+var c = """
+a = 101
+b = c + a
+""";
+var locals = new Dictionary<string, PyObject>
+{
+    ["c"] = PyObject.From(101)
+};
+var globals = new Dictionary<string, PyObject>
+{
+    ["d"] = PyObject.From(100)
+};
+using var result = env.Execute(c, locals, globals);
+```

mkdocs.yml

@@ -4,6 +4,7 @@ nav:
   - Getting Started: getting-started.md
   - Reference: reference.md
   - Environment and Package Management: environments.md
+  - Asynchronous Functions: async_support.md
   - Buffer Protocol and NumPy Arrays: buffers.md
   - Advanced Usage: advanced.md
   - Limitations: limitations.md

src/CSnakes.Runtime.Tests/Python/RunTests.cs

@@ -0,0 +1,63 @@
+using CSnakes.Runtime.Python;
+
+namespace CSnakes.Runtime.Tests.Python;
+public class RunTests : RuntimeTestBase
+{
+    [Fact]
+    public void TestSimpleString()
+    {
+        using var result = env.ExecuteExpression("1+1");
+        Assert.Equal("2", result.ToString());
+    }
+
+    [Fact]
+    public void TestBadString()
+    {
+        Assert.Throws<PythonInvocationException>(() => env.ExecuteExpression("1+"));
+    }
+
+    [Fact]
+    public void TestSimpleStringWithLocals()
+    {
+        var locals = new Dictionary<string, PyObject>
+        {
+            ["a"] = PyObject.From(101)
+        };
+        using var result = env.ExecuteExpression("a+1", locals);
+        Assert.Equal("102", result.ToString());
+    }
+
+    [Fact]
+    public void TestSimpleStringWithLocalsAndGlobals()
+    {
+        var locals = new Dictionary<string, PyObject>
+        {
+            ["a"] = PyObject.From(101)
+        };
+        var globals = new Dictionary<string, PyObject>
+        {
+            ["b"] = PyObject.From(100)
+        };
+        using var result = env.ExecuteExpression("a+b+1", locals, globals);
+        Assert.Equal("202", result.ToString());
+    }
+
+    [Fact]
+    public void TestMultilineInput()
+    {
+        var c = """
+a = 101
+b = c + a
+""";
+        var locals = new Dictionary<string, PyObject>
+        {
+            ["c"] = PyObject.From(101)
+        };
+        var globals = new Dictionary<string, PyObject>
+        {
+            ["d"] = PyObject.From(100)
+        };
+        using var result = env.Execute(c, locals, globals);
+        Assert.Equal("None", result.ToString());
+    }
+}

src/CSnakes.Runtime.Tests/RuntimeTestBase.cs

@@ -11,7 +11,7 @@ public class RuntimeTestBase : IDisposable
 
     public RuntimeTestBase()
     {
-        string pythonVersionWindows = Environment.GetEnvironmentVariable("PYTHON_VERSION") ?? "3.12.4";
+        string pythonVersionWindows = Environment.GetEnvironmentVariable("PYTHON_VERSION") ?? "3.12.9";
         string pythonVersionMacOS = Environment.GetEnvironmentVariable("PYTHON_VERSION") ?? "3.12";
         string pythonVersionLinux = Environment.GetEnvironmentVariable("PYTHON_VERSION") ?? "3.12";
         bool freeThreaded = Environment.GetEnvironmentVariable("PYTHON_FREETHREADED") == "true";
@@ -25,6 +25,7 @@ public RuntimeTestBase()
                 pb
                   .FromNuGet(pythonVersionWindows)
                   .FromMacOSInstallerLocator(pythonVersionMacOS, freeThreaded)
+                  .FromWindowsStore("3.12")
                   .FromEnvironmentVariable("Python3_ROOT_DIR", pythonVersionLinux); // This last one is for GitHub Actions
 
                 services.AddLogging(builder => builder.AddXUnit());

src/CSnakes.Runtime/CPython/Coroutine.cs

@@ -0,0 +1,94 @@
+using CSnakes.Runtime.Python;
+using System.Collections.Concurrent;
+
+namespace CSnakes.Runtime.CPython;
+internal unsafe partial class CPythonAPI
+{
+    internal static bool IsPyCoroutine(PyObject p)
+    {
+        return HasAttr(p, "__await__");
+    }
+
+    internal class EventLoop : IDisposable
+    {
+        private readonly PyObject? loop = null;
+
+        public EventLoop()
+        {
+            if (NewEventLoopFactory is null)
+            {
+                throw new InvalidOperationException("NewEventLoopFactory not initialized");
+            }
+            loop = NewEventLoopFactory.Call();
+        }
+
+        public bool IsDisposed { get; private set; }
+
+        private void Close()
+        {
+            if (loop is null)
+            {
+                throw new InvalidOperationException("Event loop not initialized");
+            }
+            using var close = loop.GetAttr("close");
+            close?.Call();
+        }
+
+        public void Dispose()
+        {
+            ObjectDisposedException.ThrowIf(IsDisposed, this);
+            Close();
+            loop?.Dispose();
+            IsDisposed = true;
+        }
+
+        public PyObject RunTaskUntilComplete(PyObject coroutine, CancellationToken? cancellationToken = null)
+        {
+            if (loop is null)
+            {
+                throw new InvalidOperationException("Event loop not initialized");
+            }
+            using PyObject taskFunc = loop.GetAttr("create_task");
+            using PyObject task = taskFunc.Call(coroutine);
+            using PyObject runUntilComplete = loop.GetAttr("run_until_complete");
+
+            // On cancellation, call task cancellation in Python
+            cancellationToken?.Register(() =>
+                {
+                    using PyObject cancel = task.GetAttr("cancel");
+                    // TODO : send optional message
+                    cancel.Call();
+                });
+
+            return runUntilComplete.Call(task);
+        }
+    }
+
+    private static ConcurrentBag<EventLoop> eventLoops = [];
+    [ThreadStatic] private static EventLoop? currentEventLoop = null;
+    private static PyObject? AsyncioModule = null;
+    private static PyObject? NewEventLoopFactory = null;
+
+    internal static EventLoop GetEventLoop()
+    {
+        if (AsyncioModule is null)
+        {
+            throw new InvalidOperationException("Asyncio module not initialized");
+        }
+        if (currentEventLoop is null || currentEventLoop.IsDisposed)
+        {
+            currentEventLoop = new EventLoop();
+            eventLoops.Add(currentEventLoop);
+        }
+        return currentEventLoop!;
+    }
+
+    internal static void CloseEventLoops()
+    {
+        foreach (var eventLoop in eventLoops)
+        {
+            eventLoop.Dispose();
+        }
+        eventLoops.Clear();
+    }
+}