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