Accept asyncio coroutines as key binding handlers.

Also fix a bug in the system toolbar: execution of system commands was broken.

Author: jonathanslenders

docs/pages/advanced_topics/key_bindings.rst

@@ -282,6 +282,33 @@ called, even if there's an active `ab` binding.
 
 This is mainly useful in order to conditionally override another binding.
 
+Asyncio coroutines
+------------------
+
+Key binding handlers can be asyncio coroutines.
+
+.. code:: python
+
+    from prompt_toolkit.application import in_terminal
+
+    @bindings.add('x')
+    async def print_hello(event):
+        """
+        Pressing 'x' will print 5 times "hello" in the background above the
+        prompt.
+        """
+        for i in range(5):
+            # Print hello above the current prompt.
+            async with in_terminal():
+                print('hello')
+
+            # Sleep, but allow further input editing in the meantime.
+            await asyncio.sleep(1)
+
+If the user accepts the input on the prompt, while this coroutine is not yet
+finished , an `asyncio.CancelledError` exception will be thrown in this
+coroutine.
+
 
 Timeouts
 --------

examples/prompts/custom-key-binding.py

@@ -2,8 +2,10 @@
 """
 Example of adding a custom key binding to a prompt.
 """
+import asyncio
+
 from prompt_toolkit import prompt
-from prompt_toolkit.application import run_in_terminal
+from prompt_toolkit.application import in_terminal, run_in_terminal
 from prompt_toolkit.key_binding import KeyBindings
 
 
@@ -52,6 +54,19 @@ def print_hello():
 
         run_in_terminal(print_hello)
 
+    @bindings.add("c-k")
+    async def _(event):
+        """
+        Example of asyncio coroutine as a key binding.
+        """
+        try:
+            for i in range(5):
+                async with in_terminal():
+                    print("hello")
+                await asyncio.sleep(1)
+        except asyncio.CancelledError:
+            print("Prompt terminated before we completed.")
+
     # Read input.
     print('Press F4 to insert "hello world", type "xy" to insert "z":')
     text = prompt("> ", key_bindings=bindings)

prompt_toolkit/key_binding/key_bindings.py

@@ -37,6 +37,7 @@ def my_key_binding(event):
 from abc import ABCMeta, abstractmethod, abstractproperty
 from typing import (
     TYPE_CHECKING,
+    Awaitable,
     Callable,
     Hashable,
     List,
@@ -67,7 +68,7 @@ def my_key_binding(event):
     "GlobalOnlyKeyBindings",
 ]
 
-KeyHandlerCallable = Callable[["KeyPressEvent"], None]
+KeyHandlerCallable = Callable[["KeyPressEvent"], Union[None, Awaitable[None]]]
 
 
 class Binding:
@@ -98,7 +99,11 @@ def __init__(
         self.record_in_macro = to_filter(record_in_macro)
 
     def call(self, event: "KeyPressEvent") -> None:
-        self.handler(event)
+        result = self.handler(event)
+
+        # If the handler is a coroutine, create an asyncio task.
+        if result is not None:
+            event.app.create_background_task(result)
 
     def __repr__(self) -> str:
         return "%s(keys=%r, handler=%r)" % (

prompt_toolkit/widgets/toolbars.py

@@ -127,9 +127,9 @@ def _cancel(event: E) -> None:
             event.app.layout.focus_last()
 
         @handle("enter", filter=focused)
-        def _accept(event: E) -> None:
+        async def _accept(event: E) -> None:
             " Run system command. "
-            event.app.run_system_command(
+            await event.app.run_system_command(
                 self.system_buffer.text,
                 display_before_text=self._get_display_before_text(),
             )
@@ -149,7 +149,7 @@ def _cancel_vi(event: E) -> None:
             event.app.layout.focus_last()
 
         @handle("enter", filter=focused)
-        def _accept_vi(event: E) -> None:
+        async def _accept_vi(event: E) -> None:
             " Run system command. "
             event.app.vi_state.input_mode = InputMode.NAVIGATION
             event.app.run_system_command(