Prompt_toolkit 3.0 documentation improvements.

Author: jonathanslenders

docs/pages/advanced_topics/asyncio.rst

@@ -3,52 +3,28 @@
 Running on top of the `asyncio` event loop
 ==========================================
 
-Prompt_toolkit has a built-in event loop of its own. However, in modern
-applications, you probably want to use `asyncio
-<https://docs.python.org/3/library/asyncio.html>`_ for everything. With just
-one line of code, it is possible to run prompt_toolkit on top of asyncio:
+.. note::
 
-.. code::
+ New in prompt_toolkit 3.0. (In prompt_toolkit 2.0 this was possible using a
+ work-around).
 
- from prompt_toolkit.eventloop import use_asyncio_event_loop
+Prompt_toolkit 3.0 uses asyncio natively. Calling ``Application.run()`` will
+automatically run the asyncio event loop.
 
- use_asyncio_event_loop()
-
-This will create an adaptor between the asyncio event loop and prompt_toolkit,
-and register it as the underlying event loop for the prompt_toolkit
-application.
-
-When doing this, remember that prompt_toolkit still has its own implementation
-of futures (and coroutines). A prompt_toolkit `Future` needs to be converted to
-an asyncio `Future` for use in an asyncio context, like asyncio's
-``run_until_complete``. The cleanest way is to call
-:meth:`~prompt_toolkit.eventloop.Future.to_asyncio_future`.
-
-So,the typical boilerplace for an asyncio application looks like this:
+If however you want to run a prompt_toolkit ``Application`` within an asyncio
+environment, you have to call the ``prompt_async`` method, like this:
 
 .. code:: python
 
- from prompt_toolkit.eventloop import use_asyncio_event_loop
  from prompt_toolkit.application import Application
 
- # Tell prompt_toolkit to use asyncio for the event loop.
- use_asyncio_event_loop()
-
- # Define application.
- application = Application(
- ...
- )
-
- # Run the application, and wait for it to finish.
- asyncio.get_event_loop().run_until_complete(
- application.run_async().to_asyncio_future())
-
-.. warning::
+ async def main():
+ # Define application.
+ application = Application(
+ ...
+ )
 
- If you want to use coroutines in your application, then using asyncio is
- the preferred way. It's better to avoid the built-in coroutines, because
- they make debugging the application much more difficult. Unless of course
- Python 2 support is still required.
+ result = await application.run_async()
+ print(result)
 
- At some point, when we drop Python 2 support, prompt_toolkit will probably
- use asyncio natively.
+ asyncio.get_event_loop().run_until_complete(main())

docs/pages/reference.rst

@@ -227,9 +227,8 @@ Eventloop
 .. automodule:: prompt_toolkit.eventloop
  :members: EventLoop, get_traceback_from_context, From, Return,
  ensure_future, create_event_loop, create_asyncio_event_loop,
- use_asyncio_event_loop, get_event_loop, set_event_loop,
- run_in_executor, call_from_executor, run_until_complete, Future,
- InvalidStateError
+ get_event_loop, set_event_loop, run_in_executor, call_from_executor,
+ run_until_complete, Future, InvalidStateError
 
 .. automodule:: prompt_toolkit.eventloop.posix
  :members:

docs/pages/upgrading/3.0.rst

@@ -58,6 +58,36 @@ There are some changes to the eventloop API:
 +-----------------------------------+--------------------------------------+
 
 
+Running on top of asyncio
+-------------------------
+
+For 2.0, you had tell prompt_toolkit to run on top of the asyncio event loop.
+Now it's the default. So, you can simply remove the following two lines:
+
+.. code::
+
+ from prompt_toolkit.eventloop.defaults import use_asyncio_event_loop
+ use_asyncio_event_loop()
+
+There is a few little breaking changes though. The following:
+
+.. code::
+
+ # For 2.0
+ result = await PromptSession().prompt('Say something: ', async_=True)
+
+has to be changed into:
+
+.. code::
+
+ # For 3.0
+ result = await PromptSession().prompt_async('Say something: ')
+
+Further, it's impossible to call the `prompt()` function within an asyncio
+application (within a coroutine), because it will try to run the event loop
+again. In that case, always use `prompt_async()`.
+
+
 Changes to the the dialog functions
 -----------------------------------