##// END OF EJS Templates
fix highlighting_style typo
dongweiming -
Show More
@@ -1,195 +1,195
1 =======================
1 =======================
2 Specific config details
2 Specific config details
3 =======================
3 =======================
4
4
5 .. _custom_prompts:
5 .. _custom_prompts:
6
6
7 Custom Prompts
7 Custom Prompts
8 ==============
8 ==============
9
9
10 .. versionchanged:: 5.0
10 .. versionchanged:: 5.0
11
11
12 From IPython 5, prompts are produced as a list of Pygments tokens, which are
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
13 tuples of (token_type, text). You can customise prompts by writing a method
14 which generates a list of tokens.
14 which generates a list of tokens.
15
15
16 There are four kinds of prompt:
16 There are four kinds of prompt:
17
17
18 * The **in** prompt is shown before the first line of input
18 * The **in** prompt is shown before the first line of input
19 (default like ``In [1]:``).
19 (default like ``In [1]:``).
20 * The **continuation** prompt is shown before further lines of input
20 * The **continuation** prompt is shown before further lines of input
21 (default like ``...:``).
21 (default like ``...:``).
22 * The **rewrite** prompt is shown to highlight how special syntax has been
22 * The **rewrite** prompt is shown to highlight how special syntax has been
23 interpreted (default like ``----->``).
23 interpreted (default like ``----->``).
24 * The **out** prompt is shown before the result from evaluating the input
24 * The **out** prompt is shown before the result from evaluating the input
25 (default like ``Out[1]:``).
25 (default like ``Out[1]:``).
26
26
27 Custom prompts are supplied together as a class. If you want to customise only
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`,
28 some of the prompts, inherit from :class:`IPython.terminal.prompts.Prompts`,
29 which defines the defaults. The required interface is like this:
29 which defines the defaults. The required interface is like this:
30
30
31 .. class:: MyPrompts(shell)
31 .. class:: MyPrompts(shell)
32
32
33 Prompt style definition. *shell* is a reference to the
33 Prompt style definition. *shell* is a reference to the
34 :class:`~.TerminalInteractiveShell` instance.
34 :class:`~.TerminalInteractiveShell` instance.
35
35
36 .. method:: in_prompt_tokens(cli=None)
36 .. method:: in_prompt_tokens(cli=None)
37 continuation_prompt_tokens(self, cli=None, width=None)
37 continuation_prompt_tokens(self, cli=None, width=None)
38 rewrite_prompt_tokens()
38 rewrite_prompt_tokens()
39 out_prompt_tokens()
39 out_prompt_tokens()
40
40
41 Return the respective prompts as lists of ``(token_type, text)`` tuples.
41 Return the respective prompts as lists of ``(token_type, text)`` tuples.
42
42
43 For continuation prompts, *width* is an integer representing the width of
43 For continuation prompts, *width* is an integer representing the width of
44 the prompt area in terminal columns.
44 the prompt area in terminal columns.
45
45
46 *cli*, where used, is the prompt_toolkit ``CommandLineInterface`` instance.
46 *cli*, where used, is the prompt_toolkit ``CommandLineInterface`` instance.
47 This is mainly for compatibility with the API prompt_toolkit expects.
47 This is mainly for compatibility with the API prompt_toolkit expects.
48
48
49 Inside IPython or in a startup script, you can use a custom prompts class
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.
50 by setting ``get_ipython().prompts`` to an *instance* of the class.
51 In configuration, ``TerminalInteractiveShell.prompts_class`` may be set to
51 In configuration, ``TerminalInteractiveShell.prompts_class`` may be set to
52 either the class object, or a string of its full importable name.
52 either the class object, or a string of its full importable name.
53
53
54 .. _termcolour:
54 .. _termcolour:
55
55
56 Terminal Colors
56 Terminal Colors
57 ===============
57 ===============
58
58
59 .. versionchanged:: 5.0
59 .. versionchanged:: 5.0
60
60
61 There are two main configuration options controlling colours.
61 There are two main configuration options controlling colours.
62
62
63 ``InteractiveShell.colors`` sets the colour of tracebacks and object info (the
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
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:
65 is set to ``'legacy'``. It has four case-insensitive values:
66 ``'nocolor', 'neutral', 'linux', 'lightbg'``. The default is *neutral*, which
66 ``'nocolor', 'neutral', 'linux', 'lightbg'``. The default is *neutral*, which
67 should be legible on either dark or light terminal backgrounds. *linux* is
67 should be legible on either dark or light terminal backgrounds. *linux* is
68 optimised for dark backgrounds and *lightbg* for light ones.
68 optimised for dark backgrounds and *lightbg* for light ones.
69
69
70 ``TerminalInteractiveShell.highlight_style`` determines prompt colours and syntax
70 ``TerminalInteractiveShell.highlighting_style`` determines prompt colours and syntax
71 highlighting. It takes the name of a Pygments style as a string, or the special
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``.
72 value ``'legacy'`` to pick a style in accordance with ``InteractiveShell.colors``.
73
73
74 You can see the Pygments styles available on your system by running::
74 You can see the Pygments styles available on your system by running::
75
75
76 import pygments
76 import pygments
77 list(pygments.styles.get_all_styles())
77 list(pygments.styles.get_all_styles())
78
78
79 Additionally, ``TerminalInteractiveShell.highlight_style_overrides`` can override
79 Additionally, ``TerminalInteractiveShell.highlighting_style_overrides`` can override
80 specific styles in the highlighting. It should be a dictionary mapping Pygments
80 specific styles in the highlighting. It should be a dictionary mapping Pygments
81 token types to strings defining the style. See `Pygments' documentation
81 token types to strings defining the style. See `Pygments' documentation
82 <http://pygments.org/docs/styles/#creating-own-styles>`__ for the language used
82 <http://pygments.org/docs/styles/#creating-own-styles>`__ for the language used
83 to define styles.
83 to define styles.
84
84
85 Colors in the pager
85 Colors in the pager
86 -------------------
86 -------------------
87
87
88 On some systems, the default pager has problems with ANSI colour codes.
88 On some systems, the default pager has problems with ANSI colour codes.
89 To configure your default pager to allow these:
89 To configure your default pager to allow these:
90
90
91 1. Set the environment PAGER variable to ``less``.
91 1. Set the environment PAGER variable to ``less``.
92 2. Set the environment LESS variable to ``-r`` (plus any other options
92 2. Set the environment LESS variable to ``-r`` (plus any other options
93 you always want to pass to less by default). This tells less to
93 you always want to pass to less by default). This tells less to
94 properly interpret control sequences, which is how color
94 properly interpret control sequences, which is how color
95 information is given to your terminal.
95 information is given to your terminal.
96
96
97 .. _editors:
97 .. _editors:
98
98
99 Editor configuration
99 Editor configuration
100 ====================
100 ====================
101
101
102 IPython can integrate with text editors in a number of different ways:
102 IPython can integrate with text editors in a number of different ways:
103
103
104 * Editors (such as `(X)Emacs`_, vim_ and TextMate_) can
104 * Editors (such as `(X)Emacs`_, vim_ and TextMate_) can
105 send code to IPython for execution.
105 send code to IPython for execution.
106
106
107 * IPython's ``%edit`` magic command can open an editor of choice to edit
107 * IPython's ``%edit`` magic command can open an editor of choice to edit
108 a code block.
108 a code block.
109
109
110 The %edit command (and its alias %ed) will invoke the editor set in your
110 The %edit command (and its alias %ed) will invoke the editor set in your
111 environment as :envvar:`EDITOR`. If this variable is not set, it will default
111 environment as :envvar:`EDITOR`. If this variable is not set, it will default
112 to vi under Linux/Unix and to notepad under Windows. You may want to set this
112 to vi under Linux/Unix and to notepad under Windows. You may want to set this
113 variable properly and to a lightweight editor which doesn't take too long to
113 variable properly and to a lightweight editor which doesn't take too long to
114 start (that is, something other than a new instance of Emacs). This way you
114 start (that is, something other than a new instance of Emacs). This way you
115 can edit multi-line code quickly and with the power of a real editor right
115 can edit multi-line code quickly and with the power of a real editor right
116 inside IPython.
116 inside IPython.
117
117
118 You can also control the editor by setting :attr:`TerminalInteractiveShell.editor`
118 You can also control the editor by setting :attr:`TerminalInteractiveShell.editor`
119 in :file:`ipython_config.py`.
119 in :file:`ipython_config.py`.
120
120
121 Vim
121 Vim
122 ---
122 ---
123
123
124 Paul Ivanov's `vim-ipython <https://github.com/ivanov/vim-ipython>`_ provides
124 Paul Ivanov's `vim-ipython <https://github.com/ivanov/vim-ipython>`_ provides
125 powerful IPython integration for vim.
125 powerful IPython integration for vim.
126
126
127 .. _emacs:
127 .. _emacs:
128
128
129 (X)Emacs
129 (X)Emacs
130 --------
130 --------
131
131
132 If you are a dedicated Emacs user, and want to use Emacs when IPython's
132 If you are a dedicated Emacs user, and want to use Emacs when IPython's
133 ``%edit`` magic command is called you should set up the Emacs server so that
133 ``%edit`` magic command is called you should set up the Emacs server so that
134 new requests are handled by the original process. This means that almost no
134 new requests are handled by the original process. This means that almost no
135 time is spent in handling the request (assuming an Emacs process is already
135 time is spent in handling the request (assuming an Emacs process is already
136 running). For this to work, you need to set your EDITOR environment variable
136 running). For this to work, you need to set your EDITOR environment variable
137 to 'emacsclient'. The code below, supplied by Francois Pinard, can then be
137 to 'emacsclient'. The code below, supplied by Francois Pinard, can then be
138 used in your :file:`.emacs` file to enable the server:
138 used in your :file:`.emacs` file to enable the server:
139
139
140 .. code-block:: common-lisp
140 .. code-block:: common-lisp
141
141
142 (defvar server-buffer-clients)
142 (defvar server-buffer-clients)
143 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
143 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
144 (server-start)
144 (server-start)
145 (defun fp-kill-server-with-buffer-routine ()
145 (defun fp-kill-server-with-buffer-routine ()
146 (and server-buffer-clients (server-done)))
146 (and server-buffer-clients (server-done)))
147 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
147 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
148
148
149 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
149 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
150 currently (X)Emacs and IPython get along very well in other ways.
150 currently (X)Emacs and IPython get along very well in other ways.
151
151
152 With (X)EMacs >= 24, You can enable IPython in python-mode with:
152 With (X)EMacs >= 24, You can enable IPython in python-mode with:
153
153
154 .. code-block:: common-lisp
154 .. code-block:: common-lisp
155
155
156 (require 'python)
156 (require 'python)
157 (setq python-shell-interpreter "ipython")
157 (setq python-shell-interpreter "ipython")
158
158
159 .. _`(X)Emacs`: http://www.gnu.org/software/emacs/
159 .. _`(X)Emacs`: http://www.gnu.org/software/emacs/
160 .. _TextMate: http://macromates.com/
160 .. _TextMate: http://macromates.com/
161 .. _vim: http://www.vim.org/
161 .. _vim: http://www.vim.org/
162
162
163 .. _custom_keyboard_shortcuts
163 .. _custom_keyboard_shortcuts
164
164
165 Keyboard Shortcuts
165 Keyboard Shortcuts
166 ==================
166 ==================
167
167
168 .. versionchanged:: 5.0
168 .. versionchanged:: 5.0
169
169
170 You can customise keyboard shortcuts for terminal IPython. Put code like this in
170 You can customise keyboard shortcuts for terminal IPython. Put code like this in
171 a :ref:`startup file <startup_files>`::
171 a :ref:`startup file <startup_files>`::
172
172
173 from IPython import get_ipython
173 from IPython import get_ipython
174 from prompt_toolkit.enums import DEFAULT_BUFFER
174 from prompt_toolkit.enums import DEFAULT_BUFFER
175 from prompt_toolkit.keys import Keys
175 from prompt_toolkit.keys import Keys
176 from prompt_toolkit.filters import HasFocus, HasSelection, ViInsertMode, EmacsInsertMode
176 from prompt_toolkit.filters import HasFocus, HasSelection, ViInsertMode, EmacsInsertMode
177
177
178 ip = get_ipython()
178 ip = get_ipython()
179 insert_mode = ViInsertMode() | EmacsInsertMode()
179 insert_mode = ViInsertMode() | EmacsInsertMode()
180
180
181 def insert_unexpected(event):
181 def insert_unexpected(event):
182 buf = event.current_buffer
182 buf = event.current_buffer
183 buf.insert_text('The Spanish Inquisition')
183 buf.insert_text('The Spanish Inquisition')
184
184
185 # Register the shortcut if IPython is using prompt_toolkit
185 # Register the shortcut if IPython is using prompt_toolkit
186 if getattr(ip, 'pt_cli'):
186 if getattr(ip, 'pt_cli'):
187 registry = ip.pt_cli.application.key_bindings_registry
187 registry = ip.pt_cli.application.key_bindings_registry
188 registry.add_binding(Keys.ControlN,
188 registry.add_binding(Keys.ControlN,
189 filter=(HasFocus(DEFAULT_BUFFER)
189 filter=(HasFocus(DEFAULT_BUFFER)
190 & ~HasSelection()
190 & ~HasSelection()
191 & insert_mode))(insert_unexpected)
191 & insert_mode))(insert_unexpected)
192
192
193 For more information on filters and what you can do with the ``event`` object,
193 For more information on filters and what you can do with the ``event`` object,
194 `see the prompt_toolkit docs
194 `see the prompt_toolkit docs
195 <http://python-prompt-toolkit.readthedocs.io/en/latest/pages/building_prompts.html#adding-custom-key-bindings>`__.
195 <http://python-prompt-toolkit.readthedocs.io/en/latest/pages/building_prompts.html#adding-custom-key-bindings>`__.
General Comments 0
You need to be logged in to leave comments. Login now