From 771e4b920e33a44c118759eb7949930bfbe1e14b 2016-06-30 07:54:32 From: Min RK Date: 2016-06-30 07:54:32 Subject: [PATCH] Merge pull request #9677 from takluyver/docs-5-polish Some docs work to prepare for 5.0 --- diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py index 481f1e9..a4adebe 100644 --- a/IPython/core/interactiveshell.py +++ b/IPython/core/interactiveshell.py @@ -250,7 +250,7 @@ class InteractiveShell(SingletonConfigurable): ).tag(config=True) colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'), default_value='Neutral', - help="Set the color scheme (NoColor, Linux, or LightBG)." + help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)." ).tag(config=True) colors_force = Bool(False, help= """ diff --git a/IPython/terminal/pt_inputhooks/__init__.py b/IPython/terminal/pt_inputhooks/__init__.py index e98ea2e..0f37b13 100644 --- a/IPython/terminal/pt_inputhooks/__init__.py +++ b/IPython/terminal/pt_inputhooks/__init__.py @@ -15,6 +15,12 @@ backends = [ 'osx', ] +registered = {} + +def register(name, inputhook): + """Register the function *inputhook* as an event loop integration.""" + registered[name] = inputhook + class UnknownBackend(KeyError): def __init__(self, name): self.name = name @@ -22,9 +28,12 @@ class UnknownBackend(KeyError): def __str__(self): return ("No event loop integration for {!r}. " "Supported event loops are: {}").format(self.name, - ', '.join(backends)) + ', '.join(backends + sorted(registered))) def get_inputhook_func(gui): + if gui in registered: + return registered[gui] + if gui not in backends: raise UnknownBackend(gui) diff --git a/docs/autogen_config.py b/docs/autogen_config.py index f2f6f66..1579d5f 100755 --- a/docs/autogen_config.py +++ b/docs/autogen_config.py @@ -11,7 +11,8 @@ generated = join(options, 'config-generated.txt') def write_doc(name, title, app, preamble=None): - with open(generated, 'a') as f: + filename = join(options, name+'.rst') + with open(filename, 'w') as f: f.write(title + '\n') f.write(('=' * len(title)) + '\n') f.write('\n') @@ -21,7 +22,7 @@ def write_doc(name, title, app, preamble=None): if __name__ == '__main__': - # create empty file + # Touch this file for the make target with open(generated, 'w'): pass diff --git a/docs/source/_images/ptshell_features.png b/docs/source/_images/ptshell_features.png new file mode 100644 index 0000000000000000000000000000000000000000..79d4b0025764f72a7d38a09af2eef353f749b49d GIT binary patch literal 13520 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. +* The **out** prompt is shown before the result from evaluating the input + (default like ``Out[1]:``). + +Custom prompts are supplied together as a class. If you want to customise only +some of the prompts, inherit from :class:`IPython.terminal.prompts.Prompts`, +which defines the defaults. The required interface is like this: + +.. class:: MyPrompts(shell) + + Prompt style definition. *shell* is a reference to the + :class:`~.TerminalInteractiveShell` instance. + + .. method:: in_prompt_tokens(cli=None) + continuation_prompt_tokens(self, cli=None, width=None) + rewrite_prompt_tokens() + out_prompt_tokens() + + Return the respective prompts as lists of ``(token_type, text)`` tuples. + + For continuation prompts, *width* is an integer representing the width of + the prompt area in terminal columns. + + *cli*, where used, is the prompt_toolkit ``CommandLineInterface`` instance. + This is mainly for compatibility with the API prompt_toolkit expects. + +Inside IPython or in a startup script, you can use a custom prompts class +by setting ``get_ipython().prompts`` to an *instance* of the class. +In configuration, ``TerminalInteractiveShell.prompts_class`` may be set to +either the class object, or a string of its full importable name. + .. _termcolour: Terminal Colors =============== -The default IPython configuration has most bells and whistles turned on -(they're pretty safe). But there's one that may cause problems on some -systems: the use of color on screen for displaying information. This is -very useful, since IPython can show prompts and exception tracebacks -with various colors, display syntax-highlighted source code, and in -general make it easier to visually parse information. - -The following terminals seem to handle the color sequences fine: - - * Linux main text console, KDE Konsole, Gnome Terminal, E-term, - rxvt, xterm. - * CDE terminal (tested under Solaris). This one boldfaces light colors. - * (X)Emacs buffers. See the :ref:`emacs` section for more details on - using IPython with (X)Emacs. - * A Windows (XP/2k) CygWin shell. Although some users have reported - problems; it is not clear whether there is an issue for everyone - or only under specific configurations. If you have full color - support under cygwin, please post to the IPython mailing list so - this issue can be resolved for all users. - -These have shown problems: - - * Windows command prompt in WinXP/2k logged into a Linux machine via - telnet or ssh. - * Windows native command prompt in WinXP/2k, without Gary Bishop's - extensions. Once Gary's readline library is installed, the normal - WinXP/2k command prompt works perfectly. - -IPython uses colors for various groups of things that may be -controlled by different configuration options: prompts, tracebacks, "as -you type" in the terminal, and the object introspection system which -passes large sets of data through a pager. There are various way to -change the colors. - -We can distinguish the coloration into 2 main categories: - -- The one that affects only the terminal client. -- The ones that also affect clients connected through the Jupyter - protocol. - -Traceback, debugger, and pager are highlighted kernel-side so they fall -into the second category. For historical reasons they are often -governed by a ``colors`` attribute or configuration option that can -take one of 3 case insensitive values: ``NoColors``, ``Linux`` and -``LightBG``. - -Colors that affect only the terminal client are governed mainly by -``TerminalInteractiveShell.highlight_style`` taking the name of a -``Pygments`` style. - -As of IPython 5.0 the color configuration works as follows: - - - by default, ``TerminalInteractiveShell.highlight_style`` is set to - ``legacy`` which **trys to** emulate the colors of IPython pre 5.0 - and respect the ``.color`` configuration option. - The emulation is an approximation of the current version of Pygments - (2.1) and only supports extended ANSI escape sequence, hence the - theme cannot adapt to your terminal custom mapping if you have - one. - - The last extra difference being that the "as you type" coloration - is present using the theme "default" if `color` is `LightBG`, and - using the theme "monokai" if `Linux`. - - - if ``TerminalInteractiveShell.highlight_style`` is set to any other - themes, this theme is used for "as you type" highlighting. The - prompt highlighting is then governed by - ``--TerminalInteractiveShell.highlighting_style_overrides`` - -As a summary, by default IPython 5.0 should mostly behave unchanged -from IPython 4.x and before. Use -``TerminalInteractiveShell.highlight_style`` and -``--TerminalInteractiveShell.highlighting_style_overrides`` for extra -flexibility. - -With default configuration `--colors=[nocolors|linux|ightbg]` as well -as the `%colors` magic should behave identically as before. +.. versionchanged:: 5.0 + +There are two main configuration options controlling colours. + +``InteractiveShell.colors`` sets the colour of tracebacks and object info (the +output from e.g. ``zip?``). It may also affect other things if the option below +is set to ``'legacy'``. It has four case-insensitive values: +``'nocolor', 'neutral', 'linux', 'lightbg'``. The default is *neutral*, which +should be legible on either dark or light terminal backgrounds. *linux* is +optimised for dark backgrounds and *lightbg* for light ones. + +``TerminalInteractiveShell.highlight_style`` determines prompt colours and syntax +highlighting. It takes the name of a Pygments style as a string, or the special +value ``'legacy'`` to pick a style in accordance with ``InteractiveShell.colors``. +You can see the Pygments styles available on your system by running:: + + import pygments + list(pygments.styles.get_all_styles()) + +Additionally, ``TerminalInteractiveShell.highlight_style_overrides`` can override +specific styles in the highlighting. It should be a dictionary mapping Pygments +token types to strings defining the style. See `Pygments' documentation +`__ for the language used +to define styles. Colors in the pager ------------------- @@ -98,9 +94,6 @@ To configure your default pager to allow these: properly interpret control sequences, which is how color information is given to your terminal. - - - .. _editors: Editor configuration diff --git a/docs/source/config/eventloops.rst b/docs/source/config/eventloops.rst index 79eb86f..da13d0a 100644 --- a/docs/source/config/eventloops.rst +++ b/docs/source/config/eventloops.rst @@ -13,47 +13,39 @@ so different steps are needed to integrate with each. Event loops in the terminal --------------------------- -In the terminal, IPython uses a blocking Python function to wait for user input. -However, the Python C API provides a hook, :c:func:`PyOS_InputHook`, which is -called frequently while waiting for input. This can be set to a function which -briefly runs the event loop and then returns. - -IPython provides Python level wrappers for setting and resetting this hook. To -use them, subclass :class:`IPython.lib.inputhook.InputHookBase`, and define -an ``enable(app=None)`` method, which initialises the event loop and calls -``self.manager.set_inputhook(f)`` with a function which will briefly run the -event loop before exiting. Decorate the class with a call to -:func:`IPython.lib.inputhook.register`:: - - from IPython.lib.inputhook import register, InputHookBase - - @register('clutter') - class ClutterInputHook(InputHookBase): - def enable(self, app=None): - self.manager.set_inputhook(inputhook_clutter) - -You can also optionally define a ``disable()`` method, taking no arguments, if -there are extra steps needed to clean up. IPython will take care of resetting -the hook, whether or not you provide a disable method. - -The simplest way to define the hook function is just to run one iteration of the -event loop, or to run until no events are pending. Most event loops provide some -mechanism to do one of these things. However, the GUI may lag slightly, -because the hook is only called every 0.1 seconds. Alternatively, the hook can -keep running the event loop until there is input ready on stdin. IPython -provides a function to facilitate this: - -.. currentmodule:: IPython.lib.inputhook - -.. function:: stdin_ready() - - Returns True if there is something ready to read on stdin. - - If this is the case, the hook function should return immediately. - - This is implemented for Windows and POSIX systems - on other platforms, it - always returns True, so that the hook always gives Python a chance to check - for input. +.. versionchanged:: 5.0 + + There is a new API for event loop integration using prompt_toolkit. + +In the terminal, IPython uses prompt_toolkit to prompt the user for input. +prompt_toolkit provides hooks to integrate with an external event loop. + +To integrate an event loop, define a function which runs the GUI event loop +until there is input waiting for prompt_toolkit to process. There are two ways +to detect this condition:: + + # Polling for input. + def inputhook(context): + while not context.input_is_ready(): + # Replace this with the appropriate call for the event loop: + iterate_loop_once() + + # Using a file descriptor to notify the event loop to stop. + def inputhook2(context): + fd = context.fileno() + # Replace the functions below with those for the event loop. + add_file_reader(fd, callback=stop_the_loop) + run_the_loop() + +Once you have defined this function, register it with IPython: + +.. currentmodule:: IPython.terminal.pt_inputhooks + +.. function:: register(name, inputhook) + + Register the function *inputhook* as the event loop integration for the + GUI *name*. If ``name='foo'``, then the user can enable this integration + by running ``%gui foo``. Event loops in the kernel diff --git a/docs/source/config/options/index.rst b/docs/source/config/options/index.rst index 7090799..a0f38e2 100644 --- a/docs/source/config/options/index.rst +++ b/docs/source/config/options/index.rst @@ -6,4 +6,7 @@ Any of the options listed here can be set in config files, at the command line, or from inside IPython. See :ref:`setting_config` for details. -.. include:: config-generated.txt +.. toctree:: + + terminal + kernel diff --git a/docs/source/whatsnew/version5.rst b/docs/source/whatsnew/version5.rst index e425aad..7df2224 100644 --- a/docs/source/whatsnew/version5.rst +++ b/docs/source/whatsnew/version5.rst @@ -5,71 +5,72 @@ IPython 5.0 =========== -Released June, 2016 +Released July, 2016 -IPython 5.0 now uses ``prompt-toolkit`` for the command line interface, thus -allowing real multi-line editing and syntactic coloration as you type. +New terminal interface +---------------------- +IPython 5 features a major upgrade to the terminal interface, bringing live +syntax highlighting as you type, proper multiline editing and multiline paste, +and tab completions that don't clutter up your history. -When using IPython as a subprocess, like for emacs inferior-shell, IPython can -be started with a ``--simple-prompt`` flag, which will bypass the prompt_toolkit -input layer. In this mode, prompt color and many other features are -disabled. +.. image:: ../_images/ptshell_features.png + :alt: New terminal interface features + :align: center + :target: ../_images/ptshell_features.png -Backwards incompatible changes ------------------------------- - - -The `install_ext magic` function which was deprecated since 4.0 has now been deleted. -You can still distribute and install extensions as packages on PyPI. - -Update IPython event triggering to ensure callback registration and -unregistration will only affect the set of callbacks the *next* time that event is -triggered. See :ghissue:`9447` and :ghpull:`9453`. - -This is a change to the existing semantics, wherein one callback registering a -second callback when triggered for an event would previously be invoked for -that same event. - -Integration with pydb has been removed since pydb development has been stopped -since 2012, and pydb is not installable from PyPI. - - - -Replacement of readline in TerminalInteractiveShell and PDB -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +These features are provided by the Python library `prompt_toolkit +`__, which replaces +``readline`` throughout our terminal interface. -IPython 5.0 now uses ``prompt_toolkit``. The -``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses -``prompt_toolkit``. It is an almost complete rewrite, so many settings have -thus changed or disappeared. The class keep the same name to avoid breaking -user configuration for the options with names that are unchanged. +Relying on this pure-Python, cross platform module also makes it simpler to +install IPython. We have removed dependencies on ``pyreadline`` for Windows and +``gnureadline`` for Mac. -The usage of ``prompt_toolkit`` is accompanied by a complete removal of all -code, using ``readline``. A particular effect of not using `readline` anymore -is that `.inputrc` settings are note effective anymore. Options having similar -effects have likely been replaced by a configuration option on IPython itself -(e.g: vi input mode). - -The `PromptManager` class have been removed, and the prompt machinery simplified. -See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts. - -.. note:: - - During development and beta cycle, ``TerminalInteractiveShell`` was - temporarly moved to ``IPython.terminal.ptshell``. - - -Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug` -and `%pdb` magic which do not use readline anymore either. +Backwards incompatible changes +------------------------------ -The color handling has been slightly changed and is now exposed, -in particular the colors of prompts and as you type -highlighting can be affected by : -``TerminalInteractiveShell.highlight_style``. With default -configuration the ``--colors`` flag and ``%colors`` magic behavior -should be mostly unchanged. See the `colors `_ section of -our documentation +- The ``%install_ext`` magic function, deprecated since 4.0, has now been deleted. + You can distribute and install extensions as packages on PyPI. +- Callbacks registered while an event is being handled will now only be called + for subsequent events; previously they could be called for the current event. + Similarly, callbacks removed while handling an event *will* always get that + event. See :ghissue:`9447` and :ghpull:`9453`. +- Integration with pydb has been removed since pydb development has been stopped + since 2012, and pydb is not installable from PyPI. +- The ``autoedit_syntax`` option has apparently been broken for many years. + It has been removed. + +New terminal interface +~~~~~~~~~~~~~~~~~~~~~~ + +The overhaul of the terminal interface will probably cause a range of minor +issues for existing users. +This is inevitable for such a significant change, and we've done our best to +minimise these issues. +Some changes that we're aware of, with suggestions on how to handle them: + +IPython no longer uses readline configuration (``~/.inputrc``). We hope that +the functionality you want (e.g. vi input mode) will be available by configuring +IPython directly (see :doc:`/config/options/terminal`). +If something's missing, please file an issue. + +The ``PromptManager`` class has been removed, and the prompt machinery simplified. +See :ref:`custom_prompts` to customise prompts with the new machinery. + +:mod:`IPython.core.debugger` now provides a plainer interface. +:mod:`IPython.terminal.debugger` contains the terminal debugger using +prompt_toolkit. + +There are new options to configure the colours used in syntax highlighting. +We have tried to integrate them with our classic ``--colors`` option and +``%colors`` magic, but there's a mismatch in possibilities, so some configurations +may produce unexpected results. See :ref:`termcolour` for more information. + +The new interface is not compatible with Emacs 'inferior-shell' feature. To +continue using this, add the ``--simple-prompt`` flag to the command Emacs +runs. This flag disables most IPython features, relying on Emacs to provide +things like tab completion. Provisional Changes ------------------- @@ -116,12 +117,6 @@ widgets... As stated above this is nightly experimental feature with a lot of it. -Removed Feature ---------------- - -- ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now - apparently. It has been removed. - Deprecated Features -------------------