Refactoring of the prompt_toolkit.styles.

Author: jonathanslenders

docs/pages/building_prompts.rst

@@ -67,34 +67,55 @@ Colors
 The colors for syntax highlighting are defined by a
 :class:`~prompt_toolkit.styles.Style` instance.  By default, a neutral built-in
 style is used, but any style instance can be passed to the
-:func:`~prompt_toolkit.shortcuts.prompt` function. All Pygments style classes
-can be used as well, when they are wrapped in a
-:class:`~prompt_toolkit.styles.PygmentsStyle`.
+:func:`~prompt_toolkit.shortcuts.prompt` function. A simple way to create a
+style, is by using the :class:`~prompt_toolkit.styles.style_from_dict`
+function:
+
+.. code:: python
+
+    from prompt_toolkit.shortcuts import prompt
+    from prompt_toolkit.styles import style_from_dict
+
+    our_style = style_from_dict({
+        Token.Comment:   '#888888 bold',
+        Token.Keyword:   '#ff88ff bold',
+    })
+
+    text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer),
+                  style=our_style)
+
+
+The style dictionary is very similar to the Pygments ``styles`` dictionary,
+with a few differences:
+
+- The `roman`, `sans`, `mono` and `border` options are not ignored.
+- The style has a few additions: `blink`, `noblink`, `reverse` and `noreverse`.
+- Colors can be in the `#ff0000` format, but they can be one of the built-in
+  ANSI color names as well. In that case, they map directly to the 16 color
+  palette of the terminal.
+
+Using a Pygments style
+^^^^^^^^^^^^^^^^^^^^^^
+
+All Pygments style classes can be used as well, when they are wrapped through
+:func:`~prompt_toolkit.styles.style_from_pygments`.
 
 Suppose we'd like to use a Pygments style, for instance
-``pygments.styles.tango.TangoStyle``. That works when we wrap it inside
-:class:`~prompt_toolkit.styles.PygmentsStyle`, but we would still miss some
-``prompt_toolkit`` specific styling, like the highlighting of selected text and
-the styling of the completion menus. Because of that, we recommend to use the
-:meth:`~prompt_toolkit.styles.PygmentsStyle.from_defaults` method to generate a
-a :class:`~prompt_toolkit.styles.Style` instance.
+``pygments.styles.tango.TangoStyle``, that is possible like this:
 
 Creating a custom style could be done like this:
 
 .. code:: python
 
     from prompt_toolkit.shortcuts import prompt
-    from prompt_toolkit.styles import PygmentsStyle
+    from prompt_toolkit.styles import style_from_pygments
 
-    from pygments.style import Style
     from pygments.styles.tango import TangoStyle
 
-    our_style = PygmentsStyle.from_defaults(
-        pygments_style_cls=TangoStyle,
-        style_dict={
-            Token.Comment:   '#888888 bold',
-            Token.Keyword:   '#ff88ff bold',
-        })
+    our_style = style_from_pygments(TangoStyle, {
+        Token.Comment:   '#888888 bold',
+        Token.Keyword:   '#ff88ff bold',
+    })
 
     text = prompt('Enter HTML: ', lexer=PygmentsLexer(HtmlLexer),
                   style=our_style)
@@ -112,10 +133,9 @@ Each token is a Pygments token and can be styled individually.
 .. code:: python
 
     from prompt_toolkit.shortcuts import prompt
-    from pygments.style import Style
-    from prompt_toolkit.styles import PygmentsStyle
+    from prompt_toolkit.styles import style_from_dict
 
-    example_style = PygmentsStyle.from_defaults({
+    example_style = style_from_dict({
         # User input.
         Token:          '#ff0066',
 
@@ -159,7 +179,7 @@ is simple with the :func:`~prompt_toolkit.shortcuts.print_tokens` function.
 .. code:: python
 
     # Create a stylesheet.
-    style = PygmentsStyle.from_defaults(style_dict={
+    style = style_from_dict({
         Token.Hello: '#ff0066',
         Token.World: '#44ff44 italic',
     })

examples/bottom-toolbar.py

@@ -5,7 +5,7 @@
 from __future__ import unicode_literals
 from prompt_toolkit import prompt
 from prompt_toolkit.styles import PygmentsStyle
-from pygments.token import Token
+from prompt_toolkit.token import Token
 
 
 test_style = PygmentsStyle.from_defaults({

examples/clock-input.py

@@ -3,14 +3,14 @@
 Example of a 'dynamic' prompt. On that shows the current time in the prompt.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.interface import CommandLineInterface
 from prompt_toolkit.application import Application
+from prompt_toolkit.interface import CommandLineInterface
 from prompt_toolkit.layout import Window
 from prompt_toolkit.layout.controls import BufferControl
 from prompt_toolkit.layout.processors import BeforeInput
 from prompt_toolkit.shortcuts import create_eventloop
+from prompt_toolkit.token import Token
 from prompt_toolkit.utils import Callback
-from pygments.token import Token
 
 import datetime
 import time

examples/colored-prompt.py

@@ -5,11 +5,11 @@
 from __future__ import unicode_literals
 
 from prompt_toolkit import prompt
-from prompt_toolkit.styles import PygmentsStyle
-from pygments.token import Token
+from prompt_toolkit.styles import style_from_dict
+from prompt_toolkit.token import Token
 
 
-example_style = PygmentsStyle.from_defaults(style_dict={
+example_style = style_from_dict({
     # User input.
     Token:          '#ff0066',
 
@@ -20,6 +20,10 @@
     Token.Pound:    '#00aa00',
     Token.Host:     '#000088 bg:#aaaaff',
     Token.Path:     '#884444 underline',
+
+    # Make a selection reverse/underlined.
+    # (Use Control-Space to select.)
+    Token.SelectedText: 'reverse underline',
 })
 
 

examples/full-screen-layout.py

@@ -17,8 +17,7 @@
 from prompt_toolkit.layout.controls import BufferControl, FillControl, TokenListControl
 from prompt_toolkit.layout.dimension import LayoutDimension as D
 from prompt_toolkit.shortcuts import create_eventloop
-
-from pygments.token import Token
+from prompt_toolkit.token import Token
 
 
 # 1. First we create the layout

examples/get-multiline-input.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 from __future__ import unicode_literals
 from prompt_toolkit import prompt
-from pygments.token import Token
+from prompt_toolkit.token import Token
+
 
 def continuation_tokens(cli, width):
     " The continuation: display dots before all the following lines. "

examples/html-input.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 """
 Simple example of a syntax-highlighted HTML input line.
+(This requires Pygments to be installed.)
 """
 from __future__ import unicode_literals
 from pygments.lexers import HtmlLexer

examples/regular-language.py

@@ -21,8 +21,7 @@
 from prompt_toolkit.contrib.regular_languages.lexer import GrammarLexer
 from prompt_toolkit.layout.lexers import SimpleLexer
 from prompt_toolkit.styles import PygmentsStyle
-
-from pygments.token import Token
+from prompt_toolkit.token import Token
 
 import math
 

prompt_toolkit/shortcuts.py

@@ -54,8 +54,10 @@
 
 try:
     from pygments.lexer import Lexer as pygments_Lexer
+    from pygments.style import Style as pygments_Style
 except ImportError:
     pygments_Lexer = None
+    pygments_Style = None
 
 if is_windows():
     from .terminal.win32_output import Win32Output
@@ -213,7 +215,7 @@ def create_prompt_layout(message='', lexer=None, is_password=False,
     # class is given, turn it into a PygmentsLexer. (Important for
     # backwards-compatibility.)
     try:
-        if pygments_Lexer and issubclass(lexer, pygments.lexer.Lexer):
+        if pygments_Lexer and issubclass(lexer, pygments_Lexer):
             lexer = PygmentsLexer(lexer)
     except TypeError: # Happens when lexer is `None` or an instance of something else.
         pass
@@ -418,7 +420,7 @@ def create_prompt_application(
 
     # Accept Pygments styles as well for backwards compatibility.
     try:
-        if issubclass(style, pygments.style.Style):
+        if pygments_Style and issubclass(style, pygments_Style):
             style = PygmentsStyle(style)
     except TypeError:  # Happens when style is `None` or an instance of something else.
         pass