.. _upgrading_2_0:

Upgrading to prompt_toolkit 2.0
===============================

Prompt_toolkit 2.0 is not compatible with 1.0, however you probably want to
upgrade your applications. This page explains why we have these differences and
how to upgrade.

If you experience some difficulties or you feel that some information is
missing from this page, don't hesitate to open a GitHub issue for help.


Why all these breaking changes?
-------------------------------

After more and more custom prompt_toolkit applications were developed, it
became clear that prompt_toolkit 1.0 was not flexible enough for certain use
cases. Mostly, the development of full screen applications was not really
natural. All the important components, like the rendering, key bindings, input
and output handling were present, but the API was in the first place designed
for simple command line prompts. This was mostly notably in the following two
places:

- First, there was the focus which was always pointing to a
  :class:`~prompt_toolkit.buffer.Buffer` (or text input widget), but in full
  screen applications there are other widgets, like menus and buttons which
  can be focused.
- And secondly, it was impossible to make reusable UI components. All the key
  bindings for the entire applications were stored together in one
  ``KeyBindings`` object, and similar, all
  :class:`~prompt_toolkit.buffer.Buffer` objects were stored together in one
  dictionary. This didn't work well. You want reusable components to define
  their own key bindings and everything. It's the idea of encapsulation.

For simple prompts, the changes wouldn't be that invasive, but given that there
would be some, I took the opportunity to fix a couple of other things. For
instance:

- In prompt_toolkit 1.0, we translated `\\r` into `\\n` during the input
  processing. This was not a good idea, because some people wanted to handle
  these keys individually. This makes sense if you keep in mind that they
  correspond to `Control-M` and `Control-J`. However, we couldn't fix this
  without breaking everyone's enter key, which happens to be the most important
  key in prompts.

Given that we were going to break compatibility anyway, we changed a couple of
other important things that effect both simple prompt applications and
full screen applications. These are the most important:

- We no longer depend on Pygments for styling. While we like Pygments, it was
  not flexible enough to provide all the styling options that we need, and the
  Pygments tokens were not ideal for styling anything besides tokenized text.

  Instead we created something similar to CSS. All UI components can attach
  classnames to themselves, as well as define an inline style. The final style is
  then computed by combining the inline styles, the classnames and the style
  sheet.

  There are still adaptors available for using Pygments lexers as well as for
  Pygments styles.

- The way that key bindings were defined was too complex.
  ``KeyBindingsManager`` was too complex and no longer exists. Every set of key
  bindings is now a
  :class:`~prompt_toolkit.key_binding.KeyBindings` object and multiple of these
  can be merged together at any time. The runtime performance remains the same,
  but it's now easier for users.

- The separation between the ``CommandLineInterface`` and
  :class:`~prompt_toolkit.application.Application` class was confusing and in
  the end, didn't really had an advantage. These two are now merged together in
  one :class:`~prompt_toolkit.application.Application` class.

- We no longer pass around the active ``CommandLineInterface``. This was one of
  the most annoying things. Key bindings need it in order to change anything
  and filters need it in order to evaluate their state. It was pretty annoying,
  especially because there was usually only one application active at a time.
  So, :class:`~prompt_toolkit.application.Application` became a ``TaskLocal``.
  That is like a global variable, but scoped in the current coroutine or
  context. The way this works is still not 100% correct, but good enough for
  the projects that need it (like Pymux), and hopefully Python will get support
  for this in the future thanks to PEP521, PEP550 or PEP555.

All of these changes have been tested for many months, and I can say with
confidence that prompt_toolkit 2.0 is a better prompt_toolkit.


Some new features
-----------------

Apart from the breaking changes above, there are also some exciting new
features.

- We now support vt100 escape codes for Windows consoles on Windows 10. This
  means much faster rendering, and full color support.

- We have a concept of formatted text. This is an object that evaluates to
  styled text. Every input that expects some text, like the message in a
  prompt, or the text in a toolbar, can take any kind of formatted text as input.
  This means you can pass in a plain string, but also a list of `(style,
  text)` tuples (similar to a Pygments tokenized string), or an
  :class:`~prompt_toolkit.formatted_text.HTML` object. This simplifies many
  APIs.

- New utilities were added. We now have function for printing formatted text
  and an experimental module for displaying progress bars.

- Autocompletion, input validation, and auto suggestion can now either be
  asynchronous or synchronous. By default they are synchronous, but by wrapping
  them in :class:`~prompt_toolkit.completion.ThreadedCompleter`,
  :class:`~prompt_toolkit.validation.ThreadedValidator` or
  :class:`~prompt_toolkit.auto_suggest.ThreadedAutoSuggest`, they will become
  asynchronous by running in a background thread.

  Further, if the autocompletion code runs in a background thread, we will show
  the completions as soon as they arrive. This means that the autocompletion
  algorithm could for instance first yield the most trivial completions and then
  take time to produce the completions that take more time.


Upgrading
---------

More guidelines on how to upgrade will follow.


`AbortAction` has been removed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prompt_toolkit 1.0 had an argument ``abort_action`` for both the
``Application`` class as well as for the ``prompt`` function. This has been
removed. The recommended way to handle this now is by capturing
``KeyboardInterrupt`` and ``EOFError`` manually.


Calling `create_eventloop` usually not required anymore
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prompt_toolkit 2.0 will automatically create the appropriate event loop when
it's needed for the first time. There is no need to create one and pass it
around. If you want to run an application on top of asyncio (without using an
executor), it still needs to be activated by calling
:func:`~prompt_toolkit.eventloop.use_asyncio_event_loop` at the beginning.


Pygments styles and tokens
^^^^^^^^^^^^^^^^^^^^^^^^^^

prompt_toolkit 2.0 no longer depends on `Pygments <http://pygments.org/>`_, but
that definitely doesn't mean that you can't use any Pygments functionality
anymore. The only difference is that Pygments stuff needs to be wrapped in an
adaptor to make it compatible with the native prompt_toolkit objects.

- For instance, if you have a list of ``(pygments.Token, text)`` tuples for
  formatting, then this needs to be wrapped in a
  :class:`~prompt_toolkit.formatted_text.PygmentsTokens` object. This is an
  adaptor that turns it into prompt_toolkit "formatted text". Feel free to keep
  using this.

- Pygments lexers need to be wrapped in a
  :class:`~prompt_toolkit.lexers.PygmentsLexer`. This will convert the list of
  Pygments tokens into prompt_toolkit formatted text.

- If you have a Pygments style, then this needs to be converted as well. A
  Pygments style class can be converted in a prompt_toolkit
  :class:`~prompt_toolkit.styles.Style` with the
  :func:`~prompt_toolkit.styles.pygments.style_from_pygments_cls` function
  (which used to be called ``style_from_pygments``). A Pygments style
  dictionary can be converted using
  :func:`~prompt_toolkit.styles.pygments.style_from_pygments_dict`.

  Multiple styles can be merged together using
  :func:`~prompt_toolkit.styles.merge_styles`.


Wordcompleter
^^^^^^^^^^^^^

`WordCompleter` was moved from
:class:`prompt_toolkit.contrib.completers.base.WordCompleter` to
:class:`prompt_toolkit.completion.word_completer.WordCompleter`.


Asynchronous autocompletion
^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, prompt_toolkit 2.0 completion is now synchronous. If you still want
asynchronous auto completion (which is often good thing), then you have to wrap
the completer in a :class:`~prompt_toolkit.completion.ThreadedCompleter`.


Filters
^^^^^^^

We don't distinguish anymore between `CLIFilter` and `SimpleFilter`, because the
application object is no longer passed around. This means that all filters are
a `Filter` from now on.

All filters have been turned into functions. For instance, `IsDone` became
`is_done` and `HasCompletions` became `has_completions`.

This was done because almost all classes were called without any arguments in
the `__init__` causing additional braces everywhere. This means that
`HasCompletions()` has to be replaced by `has_completions` (without
parenthesis).

The few filters that took arguments as input, became functions, but still have
to be called with the given arguments.

For new filters, it is recommended to use the `@Condition` decorator,
rather then inheriting from `Filter`. For instance:

.. code:: python

    from prompt_toolkit.filters import Condition

    @Condition
    def my_filter();
        return True  # Or False

