diff options
| author | Jonathan Slenders <jonathan@slenders.be> | 2018-05-20 16:37:58 +0200 |
|---|---|---|
| committer | Jonathan Slenders <jonathan@slenders.be> | 2018-05-20 16:42:11 +0200 |
| commit | 72fb6f09ef4f2871bca4ff08fd0be81ff9b6234d (patch) | |
| tree | 0fcceba6b0ab5189c193fe88fa432d84d4ef359a | |
| parent | 7e6077bcc835b6dae875df6b725cb05a85ef5e92 (diff) | |
Improved documentation.
| -rw-r--r-- | CHANGELOG | 5 | ||||
| -rw-r--r-- | docs/pages/advanced_topics/key_bindings.rst | 15 | ||||
| -rw-r--r-- | docs/pages/advanced_topics/rendering_flow.rst | 9 | ||||
| -rw-r--r-- | docs/pages/asking_for_input.rst | 45 | ||||
| -rw-r--r-- | docs/pages/full_screen_apps.rst | 9 | ||||
| -rw-r--r-- | docs/pages/reference.rst | 7 | ||||
| -rw-r--r-- | docs/pages/tutorials/repl.rst | 6 | ||||
| -rwxr-xr-x | examples/tutorial/sqlite-cli.py | 2 | ||||
| -rw-r--r-- | prompt_toolkit/patch_stdout.py | 5 |
9 files changed, 87 insertions, 16 deletions
@@ -180,6 +180,11 @@ Changes: wait for all the completions to be generated, before displaying the first one. The completion menus are updated as soon as new completions arrive. +- Changes regarding input validation: + + * Added the `Validator.from_callable` class method for easy creation of + new validators. + - Changes regarding the `History` classes: * The `History` base class has a different interface. This was needed for diff --git a/docs/pages/advanced_topics/key_bindings.rst b/docs/pages/advanced_topics/key_bindings.rst index 3ada5ac5..aa9ec1b0 100644 --- a/docs/pages/advanced_topics/key_bindings.rst +++ b/docs/pages/advanced_topics/key_bindings.rst @@ -173,3 +173,18 @@ There are two timeout settings that effect the handling of keys. don't know what will follow. This timeout is the maximum amount of time that we wait until we call the handlers anyway. Pass `None` to disable this timeout. + + +Recording macros +---------------- + +Both Emacs and Vi mode allow macro recording. By default, all key presses are +recorded during a macro, but it is possible to exclude certain keys by setting +the `record_in_macro` parameter to `False`: + +.. code:: python + + @bindings.add('c-t', record_in_macro=False) + def _(event): + # ... + pass diff --git a/docs/pages/advanced_topics/rendering_flow.rst b/docs/pages/advanced_topics/rendering_flow.rst index 41f438df..52acfbde 100644 --- a/docs/pages/advanced_topics/rendering_flow.rst +++ b/docs/pages/advanced_topics/rendering_flow.rst @@ -54,13 +54,14 @@ The visualisation happens in several steps: 2. First, the buffer's text is passed to the :meth:`~prompt_toolkit.lexers.Lexer.lex_document` method of a :class:`~prompt_toolkit.lexers.Lexer`. This returns a function which - for a given line number, returns a token list for that line (that's a - list of ``(Token, text)`` tuples). + for a given line number, returns a "formatted text list" for that line + (that's a list of ``(style_string, text)`` tuples). - 3. The token list is passed through a list of + 3. This list is passed through a list of :class:`~prompt_toolkit.layout.processors.Processor` objects. Each processor can do a transformation for each line. - (For instance, they can insert or replace some text.) + (For instance, they can insert or replace some text, highlight the + selection or search string, etc...) 4. The :class:`~prompt_toolkit.layout.UIControl` returns a :class:`~prompt_toolkit.layout.UIContent` instance which diff --git a/docs/pages/asking_for_input.rst b/docs/pages/asking_for_input.rst index 3d254648..c36a294d 100644 --- a/docs/pages/asking_for_input.rst +++ b/docs/pages/asking_for_input.rst @@ -242,13 +242,13 @@ Autocompletion Autocompletion can be added by passing a ``completer`` parameter. This should be an instance of the :class:`~prompt_toolkit.completion.Completer` abstract -base class. ``WordCompleter`` is an example of a completer that implements that -interface. +base class. :class:`~prompt_toolkit.completion.WordCompleter` is an example of +a completer that implements that interface. .. code:: python from prompt_toolkit import prompt - from prompt_toolkit.contrib.completers import WordCompleter + from prompt_toolkit.completion import WordCompleter html_completer = WordCompleter(['<html>', '<body>', '<head>', '<title>']) text = prompt('Enter HTML: ', completer=html_completer) @@ -410,6 +410,37 @@ If the input validation contains some heavy CPU intensive code, but you don't want to block the event loop, then it's recommended to wrap the validator class in a :class:`~prompt_toolkit.validation.ThreadedValidator`. +Validator from a callable +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Instead of implementing the :class:`~prompt_toolkit.validation.Validator` +abstract base class, it is also possible to start from a simple function and +use the :meth:`~prompt_toolkit.validation.Validator.from_callable` classmethod. +This is easier and sufficient for probably 90% of the validators. It looks as +follows: + +.. code:: python + + from prompt_toolkit.validation import Validator + from prompt_toolkit import prompt + + def is_number(text): + return text.isdigit() + + validator = Validator.from_callable( + is_number, + error_message='This input contains non-numeric characters', + move_cursor_to_end=True) + + number = int(prompt('Give a number: ', validator=validator)) + print('You said: %i' % number) + +We define a function that takes a string, and tells whether it's valid input or +not by returning a boolean. +:meth:`~prompt_toolkit.validation.Validator.from_callable` turns that into a +:class:`~prompt_toolkit.validation.Validator` instance. Notice that setting the +cursor position is not possible this way. + History ------- @@ -738,7 +769,7 @@ margin is defined by the prompt.) .. code:: python - def prompt_continuation(width): + def prompt_continuation(width, line_number, is_soft_wrap): return '.' * width # Or: return [('', '.' * width)] @@ -834,6 +865,6 @@ prompting the user for input is as simple as calling result = await prompt('Say something: ', async_=True) print('You said: %s' % result) -The ``patch_stdout()`` context manager is optional, but it's recommended, -because other coroutines could print to stdout. This ensures that other output -won't destroy the prompt. +The :func:`~prompt_toolkit.patch_stdout.patch_stdout` context manager is +optional, but it's recommended, because other coroutines could print to stdout. +This ensures that other output won't destroy the prompt. diff --git a/docs/pages/full_screen_apps.rst b/docs/pages/full_screen_apps.rst index d35c88a5..8fe45bb5 100644 --- a/docs/pages/full_screen_apps.rst +++ b/docs/pages/full_screen_apps.rst @@ -13,7 +13,8 @@ them together. Before going through this page, it could be helpful to go through :ref:`asking for input <asking_for_input>` (prompts) first. Many things that apply to an -input prompt also apply to full screen applications. +input prompt, like styling, key bindings and so on, also apply to full screen +applications. .. note:: @@ -217,6 +218,8 @@ vertical line: app = Application(layout=layout, full_screen=True) app.run() # You won't be able to Exit this app +Notice that if you execute this right now, there is no way to quit this +application yet. This is something we explain in the next section below. More complex layouts can be achieved by nesting multiple :class:`~prompt_toolkit.layout.VSplit`, @@ -252,6 +255,8 @@ for getting the active application. # Now focus it. get_app().layout.focus(w) +Changing the focus is something which is typically done in a key binding, so +read on to see how to define key bindings. Key bindings ------------ @@ -312,6 +317,8 @@ the key handler: The callback function is named ``exit_`` for clarity, but it could have been named ``_`` (underscore) as well, because the we won't refer to this name. +:ref:`Read more about key bindings ...<key_bindings>` + Modal containers ^^^^^^^^^^^^^^^^ diff --git a/docs/pages/reference.rst b/docs/pages/reference.rst index 885b4cb7..948d9c3b 100644 --- a/docs/pages/reference.rst +++ b/docs/pages/reference.rst @@ -260,3 +260,10 @@ Output .. automodule:: prompt_toolkit.output.win32 :members: + + +Patch stdout +------------ + +.. automodule:: prompt_toolkit.patch_stdout + :members: patch_stdout, StdoutProxy diff --git a/docs/pages/tutorials/repl.rst b/docs/pages/tutorials/repl.rst index 4667af9e..6aac7a51 100644 --- a/docs/pages/tutorials/repl.rst +++ b/docs/pages/tutorials/repl.rst @@ -134,7 +134,7 @@ Like the lexer, this ``sql_completer`` instance can be passed to either the from __future__ import unicode_literals from prompt_toolkit import PromptSession - from prompt_toolkit.contrib.completers import WordCompleter + from prompt_toolkit.completion import WordCompleter from prompt_toolkit.lexers import PygmentsLexer from pygments.lexers import SqlLexer @@ -178,7 +178,7 @@ function. from __future__ import unicode_literals from prompt_toolkit import PromptSession - from prompt_toolkit.contrib.completers import WordCompleter + from prompt_toolkit.completion import WordCompleter from prompt_toolkit.lexers import PygmentsLexer from prompt_toolkit.styles import Style from pygments.lexers import SqlLexer @@ -233,7 +233,7 @@ gives a good idea of how to get started. import sqlite3 from prompt_toolkit import PromptSession - from prompt_toolkit.contrib.completers import WordCompleter + from prompt_toolkit.completion import WordCompleter from prompt_toolkit.styles import Style from pygments.lexers import SqlLexer diff --git a/examples/tutorial/sqlite-cli.py b/examples/tutorial/sqlite-cli.py index 25f450e4..da9abda9 100755 --- a/examples/tutorial/sqlite-cli.py +++ b/examples/tutorial/sqlite-cli.py @@ -4,7 +4,7 @@ import sys import sqlite3 from prompt_toolkit import PromptSession -from prompt_toolkit.contrib.completers import WordCompleter +from prompt_toolkit.completion import WordCompleter from prompt_toolkit.styles import Style from prompt_toolkit.lexers import PygmentsLexer diff --git a/prompt_toolkit/patch_stdout.py b/prompt_toolkit/patch_stdout.py index 1860f928..54cc8bae 100644 --- a/prompt_toolkit/patch_stdout.py +++ b/prompt_toolkit/patch_stdout.py @@ -25,6 +25,11 @@ from contextlib import contextmanager import threading import sys +__all__ = [ + 'patch_stdout', + 'StdoutProxy', +] + @contextmanager def patch_stdout(raw=False): |