Show More
|
1 | NO CONTENT: new file 100644, binary diff hidden |
@@ -250,7 +250,7 b' class InteractiveShell(SingletonConfigurable):' | |||
|
250 | 250 | ).tag(config=True) |
|
251 | 251 | colors = CaselessStrEnum(('Neutral', 'NoColor','LightBG','Linux'), |
|
252 | 252 | default_value='Neutral', |
|
253 | help="Set the color scheme (NoColor, Linux, or LightBG)." | |
|
253 | help="Set the color scheme (NoColor, Neutral, Linux, or LightBG)." | |
|
254 | 254 | ).tag(config=True) |
|
255 | 255 | colors_force = Bool(False, help= |
|
256 | 256 | """ |
@@ -2,89 +2,85 b'' | |||
|
2 | 2 | Specific config details |
|
3 | 3 | ======================= |
|
4 | 4 | |
|
5 | .. _custom_prompts: | |
|
6 | ||
|
7 | Custom Prompts | |
|
8 | ============== | |
|
9 | ||
|
10 | .. versionchanged:: 5.0 | |
|
11 | ||
|
12 | From IPython 5, prompts are produced as a list of Pygments tokens, which are | |
|
13 | tuples of (token_type, text). You can customise prompts by writing a method | |
|
14 | which generates a list of tokens. | |
|
15 | ||
|
16 | There are four kinds of prompt: | |
|
17 | ||
|
18 | * The **in** prompt is shown before the first line of input | |
|
19 | (default like ``In [1]:``). | |
|
20 | * The **continuation** prompt is shown before further lines of input | |
|
21 | (default like ``...:``). | |
|
22 | * The **rewrite** prompt is shown to highlight how special syntax has been | |
|
23 | interpreted (default like ``----->``). | |
|
24 | * The **out** prompt is shown before the result from evaluating the input | |
|
25 | (default like ``Out[1]:``). | |
|
26 | ||
|
27 | Custom prompts are supplied together as a class. If you want to customise only | |
|
28 | some of the prompts, inherit from :class:`IPython.terminal.prompts.Prompts`, | |
|
29 | which defines the defaults. The required interface is like this: | |
|
30 | ||
|
31 | .. class:: MyPrompts(shell) | |
|
32 | ||
|
33 | Prompt style definition. *shell* is a reference to the | |
|
34 | :class:`~.TerminalInteractiveShell` instance. | |
|
35 | ||
|
36 | .. method:: in_prompt_tokens(cli=None) | |
|
37 | continuation_prompt_tokens(self, cli=None, width=None) | |
|
38 | rewrite_prompt_tokens() | |
|
39 | out_prompt_tokens() | |
|
40 | ||
|
41 | Return the respective prompts as lists of ``(token_type, text)`` tuples. | |
|
42 | ||
|
43 | For continuation prompts, *width* is an integer representing the width of | |
|
44 | the prompt area in terminal columns. | |
|
45 | ||
|
46 | *cli*, where used, is the prompt_toolkit ``CommandLineInterface`` instance. | |
|
47 | This is mainly for compatibility with the API prompt_toolkit expects. | |
|
48 | ||
|
49 | Inside IPython or in a startup script, you can use a custom prompts class | |
|
50 | by setting ``get_ipython().prompts`` to an *instance* of the class. | |
|
51 | In configuration, ``TerminalInteractiveShell.prompts_class`` may be set to | |
|
52 | either the class object, or a string of its full importable name. | |
|
53 | ||
|
5 | 54 | .. _termcolour: |
|
6 | 55 | |
|
7 | 56 | Terminal Colors |
|
8 | 57 | =============== |
|
9 | 58 | |
|
10 | The default IPython configuration has most bells and whistles turned on | |
|
11 | (they're pretty safe). But there's one that may cause problems on some | |
|
12 | systems: the use of color on screen for displaying information. This is | |
|
13 | very useful, since IPython can show prompts and exception tracebacks | |
|
14 | with various colors, display syntax-highlighted source code, and in | |
|
15 | general make it easier to visually parse information. | |
|
16 | ||
|
17 | The following terminals seem to handle the color sequences fine: | |
|
18 | ||
|
19 | * Linux main text console, KDE Konsole, Gnome Terminal, E-term, | |
|
20 | rxvt, xterm. | |
|
21 | * CDE terminal (tested under Solaris). This one boldfaces light colors. | |
|
22 | * (X)Emacs buffers. See the :ref:`emacs` section for more details on | |
|
23 | using IPython with (X)Emacs. | |
|
24 | * A Windows (XP/2k) CygWin shell. Although some users have reported | |
|
25 | problems; it is not clear whether there is an issue for everyone | |
|
26 | or only under specific configurations. If you have full color | |
|
27 | support under cygwin, please post to the IPython mailing list so | |
|
28 | this issue can be resolved for all users. | |
|
29 | ||
|
30 | These have shown problems: | |
|
31 | ||
|
32 | * Windows command prompt in WinXP/2k logged into a Linux machine via | |
|
33 | telnet or ssh. | |
|
34 | * Windows native command prompt in WinXP/2k, without Gary Bishop's | |
|
35 | extensions. Once Gary's readline library is installed, the normal | |
|
36 | WinXP/2k command prompt works perfectly. | |
|
37 | ||
|
38 | IPython uses colors for various groups of things that may be | |
|
39 | controlled by different configuration options: prompts, tracebacks, "as | |
|
40 | you type" in the terminal, and the object introspection system which | |
|
41 | passes large sets of data through a pager. There are various way to | |
|
42 | change the colors. | |
|
43 | ||
|
44 | We can distinguish the coloration into 2 main categories: | |
|
45 | ||
|
46 | - The one that affects only the terminal client. | |
|
47 | - The ones that also affect clients connected through the Jupyter | |
|
48 | protocol. | |
|
49 | ||
|
50 | Traceback, debugger, and pager are highlighted kernel-side so they fall | |
|
51 | into the second category. For historical reasons they are often | |
|
52 | governed by a ``colors`` attribute or configuration option that can | |
|
53 | take one of 3 case insensitive values: ``NoColors``, ``Linux`` and | |
|
54 | ``LightBG``. | |
|
55 | ||
|
56 | Colors that affect only the terminal client are governed mainly by | |
|
57 | ``TerminalInteractiveShell.highlight_style`` taking the name of a | |
|
58 | ``Pygments`` style. | |
|
59 | ||
|
60 | As of IPython 5.0 the color configuration works as follows: | |
|
61 | ||
|
62 | - by default, ``TerminalInteractiveShell.highlight_style`` is set to | |
|
63 | ``legacy`` which **trys to** emulate the colors of IPython pre 5.0 | |
|
64 | and respect the ``.color`` configuration option. | |
|
65 | The emulation is an approximation of the current version of Pygments | |
|
66 | (2.1) and only supports extended ANSI escape sequence, hence the | |
|
67 | theme cannot adapt to your terminal custom mapping if you have | |
|
68 | one. | |
|
69 | ||
|
70 | The last extra difference being that the "as you type" coloration | |
|
71 | is present using the theme "default" if `color` is `LightBG`, and | |
|
72 | using the theme "monokai" if `Linux`. | |
|
73 | ||
|
74 | - if ``TerminalInteractiveShell.highlight_style`` is set to any other | |
|
75 | themes, this theme is used for "as you type" highlighting. The | |
|
76 | prompt highlighting is then governed by | |
|
77 | ``--TerminalInteractiveShell.highlighting_style_overrides`` | |
|
78 | ||
|
79 | As a summary, by default IPython 5.0 should mostly behave unchanged | |
|
80 | from IPython 4.x and before. Use | |
|
81 | ``TerminalInteractiveShell.highlight_style`` and | |
|
82 | ``--TerminalInteractiveShell.highlighting_style_overrides`` for extra | |
|
83 | flexibility. | |
|
84 | ||
|
85 | With default configuration `--colors=[nocolors|linux|ightbg]` as well | |
|
86 | as the `%colors` magic should behave identically as before. | |
|
59 | .. versionchanged:: 5.0 | |
|
60 | ||
|
61 | There are two main configuration options controlling colours. | |
|
62 | ||
|
63 | ``InteractiveShell.colors`` sets the colour of tracebacks and object info (the | |
|
64 | output from e.g. ``zip?``). It may also affect other things if the option below | |
|
65 | is set to ``'legacy'``. It has four case-insensitive values: | |
|
66 | ``'nocolor', 'neutral', 'linux', 'lightbg'``. The default is *neutral*, which | |
|
67 | should be legible on either dark or light terminal backgrounds. *linux* is | |
|
68 | optimised for dark backgrounds and *lightbg* for light ones. | |
|
69 | ||
|
70 | ``TerminalInteractiveShell.highlight_style`` determines prompt colours and syntax | |
|
71 | highlighting. It takes the name of a Pygments style as a string, or the special | |
|
72 | value ``'legacy'`` to pick a style in accordance with ``InteractiveShell.colors``. | |
|
87 | 73 | |
|
74 | You can see the Pygments styles available on your system by running:: | |
|
75 | ||
|
76 | import pygments | |
|
77 | list(pygments.styles.get_all_styles()) | |
|
78 | ||
|
79 | Additionally, ``TerminalInteractiveShell.highlight_style_overrides`` can override | |
|
80 | specific styles in the highlighting. It should be a dictionary mapping Pygments | |
|
81 | token types to strings defining the style. See `Pygments' documentation | |
|
82 | <http://pygments.org/docs/styles/#creating-own-styles>`__ for the language used | |
|
83 | to define styles. | |
|
88 | 84 | |
|
89 | 85 | Colors in the pager |
|
90 | 86 | ------------------- |
@@ -98,9 +94,6 b' To configure your default pager to allow these:' | |||
|
98 | 94 | properly interpret control sequences, which is how color |
|
99 | 95 | information is given to your terminal. |
|
100 | 96 | |
|
101 | ||
|
102 | ||
|
103 | ||
|
104 | 97 | .. _editors: |
|
105 | 98 | |
|
106 | 99 | Editor configuration |
@@ -5,10 +5,27 b'' | |||
|
5 | 5 | IPython 5.0 |
|
6 | 6 | =========== |
|
7 | 7 | |
|
8 |
Released Ju |
|
|
8 | Released July, 2016 | |
|
9 | 9 | |
|
10 | IPython 5.0 now uses ``prompt-toolkit`` for the command line interface, thus | |
|
11 | allowing real multi-line editing and syntactic coloration as you type. | |
|
10 | New terminal interface | |
|
11 | ---------------------- | |
|
12 | ||
|
13 | IPython 5 features a major upgrade to the terminal interface, bringing live | |
|
14 | syntax highlighting as you type, proper multiline editing and multiline paste, | |
|
15 | and tab completions that don't clutter up your history. | |
|
16 | ||
|
17 | .. image:: ../_images/ptshell_features.png | |
|
18 | :alt: New terminal interface features | |
|
19 | :align: center | |
|
20 | :target: ../_images/ptshell_features.png | |
|
21 | ||
|
22 | These features are provided by the Python library `prompt_toolkit | |
|
23 | <http://python-prompt-toolkit.readthedocs.io/en/stable/>`__, which replaces | |
|
24 | ``readline`` throughout our terminal interface. | |
|
25 | ||
|
26 | Relying on this pure-Python, cross platform module also makes it simpler to | |
|
27 | install IPython. We have removed dependencies on ``pyreadline`` for Windows and | |
|
28 | ``gnureadline`` for Mac. | |
|
12 | 29 | |
|
13 | 30 | |
|
14 | 31 | When using IPython as a subprocess, like for emacs inferior-shell, IPython can |
@@ -19,57 +36,44 b' disabled.' | |||
|
19 | 36 | Backwards incompatible changes |
|
20 | 37 | ------------------------------ |
|
21 | 38 | |
|
22 | ||
|
23 | The `install_ext magic` function which was deprecated since 4.0 has now been deleted. | |
|
24 | You can still distribute and install extensions as packages on PyPI. | |
|
25 | ||
|
26 | Update IPython event triggering to ensure callback registration and | |
|
27 | unregistration will only affect the set of callbacks the *next* time that event is | |
|
28 | triggered. See :ghissue:`9447` and :ghpull:`9453`. | |
|
29 | ||
|
30 | This is a change to the existing semantics, wherein one callback registering a | |
|
31 | second callback when triggered for an event would previously be invoked for | |
|
32 | that same event. | |
|
33 | ||
|
34 | Integration with pydb has been removed since pydb development has been stopped | |
|
35 | since 2012, and pydb is not installable from PyPI. | |
|
36 | ||
|
37 | ||
|
38 | ||
|
39 | Replacement of readline in TerminalInteractiveShell and PDB | |
|
40 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
|
41 | ||
|
42 | IPython 5.0 now uses ``prompt_toolkit``. The | |
|
43 | ``IPython.terminal.interactiveshell.TerminalInteractiveShell`` now uses | |
|
44 | ``prompt_toolkit``. It is an almost complete rewrite, so many settings have | |
|
45 | thus changed or disappeared. The class keep the same name to avoid breaking | |
|
46 | user configuration for the options with names that are unchanged. | |
|
47 | ||
|
48 | The usage of ``prompt_toolkit`` is accompanied by a complete removal of all | |
|
49 | code, using ``readline``. A particular effect of not using `readline` anymore | |
|
50 | is that `.inputrc` settings are note effective anymore. Options having similar | |
|
51 | effects have likely been replaced by a configuration option on IPython itself | |
|
52 | (e.g: vi input mode). | |
|
53 | ||
|
54 | The `PromptManager` class have been removed, and the prompt machinery simplified. | |
|
55 | See `TerminalInteractiveShell.prompts` configurable for how to setup your prompts. | |
|
56 | ||
|
57 | .. note:: | |
|
58 | ||
|
59 | During development and beta cycle, ``TerminalInteractiveShell`` was | |
|
60 | temporarly moved to ``IPython.terminal.ptshell``. | |
|
61 | ||
|
62 | ||
|
63 | Most of the above remarks also affect `IPython.core.debugger.Pdb`, the `%debug` | |
|
64 | and `%pdb` magic which do not use readline anymore either. | |
|
65 | ||
|
66 | The color handling has been slightly changed and is now exposed, | |
|
67 | in particular the colors of prompts and as you type | |
|
68 | highlighting can be affected by : | |
|
69 | ``TerminalInteractiveShell.highlight_style``. With default | |
|
70 | configuration the ``--colors`` flag and ``%colors`` magic behavior | |
|
71 | should be mostly unchanged. See the `colors <termcolour>`_ section of | |
|
72 | our documentation | |
|
39 | - The ``%install_ext`` magic function, deprecated since 4.0, has now been deleted. | |
|
40 | You can distribute and install extensions as packages on PyPI. | |
|
41 | - Callbacks registered while an event is being handled will now only be called | |
|
42 | for subsequent events; previously they could be called for the current event. | |
|
43 | Similarly, callbacks removed while handling an event *will* always get that | |
|
44 | event. See :ghissue:`9447` and :ghpull:`9453`. | |
|
45 | - Integration with pydb has been removed since pydb development has been stopped | |
|
46 | since 2012, and pydb is not installable from PyPI. | |
|
47 | - The ``autoedit_syntax`` option has apparently been broken for many years. | |
|
48 | It has been removed. | |
|
49 | ||
|
50 | New terminal interface | |
|
51 | ~~~~~~~~~~~~~~~~~~~~~~ | |
|
52 | ||
|
53 | The overhaul of the terminal interface will probably cause a range of minor issues; | |
|
54 | this is inevitable for such a significant change. These are some that we're aware of: | |
|
55 | ||
|
56 | IPython no longer uses readline configuration (``~/.inputrc``). We hope that | |
|
57 | the functionality you want (e.g. vi input mode) will be available by configuring | |
|
58 | IPython directly (see :doc:`/config/options/terminal`). | |
|
59 | If something's missing, please file an issue. | |
|
60 | ||
|
61 | The ``PromptManager`` class has been removed, and the prompt machinery simplified. | |
|
62 | See :ref:`custom_prompts` to customise prompts with the new machinery. | |
|
63 | ||
|
64 | :mod:`IPython.core.debugger` now provides a plainer interface. | |
|
65 | :mod:`IPython.terminal.debugger` contains the terminal debugger using | |
|
66 | prompt_toolkit. | |
|
67 | ||
|
68 | There are new options to configure the colours used in syntax highlighting. | |
|
69 | We have tried to integrate them with our classic ``--colors`` option and | |
|
70 | ``%colors`` magic, but there's a mismatch in possibilities, so some configurations | |
|
71 | may produce unexpected results. See :ref:`termcolour` for more information. | |
|
72 | ||
|
73 | The new interface is not compatible with Emacs 'inferior-shell' feature. To | |
|
74 | continue using this, add the ``--simple-prompt`` flag to the command Emacs | |
|
75 | runs. This flag disables most IPython features, relying on Emacs to provide | |
|
76 | things like tab completion. | |
|
73 | 77 | |
|
74 | 78 | Provisional Changes |
|
75 | 79 | ------------------- |
@@ -116,12 +120,6 b' widgets... As stated above this is nightly experimental feature with a lot of' | |||
|
116 | 120 | it. |
|
117 | 121 | |
|
118 | 122 | |
|
119 | Removed Feature | |
|
120 | --------------- | |
|
121 | ||
|
122 | - ``TerminalInteractiveShell.autoedit_syntax`` Has been broken for many years now | |
|
123 | apparently. It has been removed. | |
|
124 | ||
|
125 | 123 | |
|
126 | 124 | Deprecated Features |
|
127 | 125 | ------------------- |
General Comments 0
You need to be logged in to leave comments.
Login now