Show More
@@ -1,234 +1,184 b'' | |||
|
1 | 1 | ======================= |
|
2 | 2 | Specific config details |
|
3 | 3 | ======================= |
|
4 | 4 | |
|
5 | 5 | Prompts |
|
6 | 6 | ======= |
|
7 | 7 | |
|
8 | 8 | In the terminal, the format of the input and output prompts can be |
|
9 | 9 | customised. This does not currently affect other frontends. |
|
10 | 10 | |
|
11 | 11 | The following codes in the prompt string will be substituted into the |
|
12 | 12 | prompt string: |
|
13 | 13 | |
|
14 | 14 | ====== =================================== ===================================================== |
|
15 | 15 | Short Long Notes |
|
16 | 16 | ====== =================================== ===================================================== |
|
17 | 17 | %n,\\# {color.number}{count}{color.prompt} history counter with bolding |
|
18 | 18 | \\N {count} history counter without bolding |
|
19 | 19 | \\D {dots} series of dots the same width as the history counter |
|
20 | 20 | \\T {time} current time |
|
21 | 21 | \\w {cwd} current working directory |
|
22 | 22 | \\W {cwd_last} basename of CWD |
|
23 | 23 | \\Xn {cwd_x[n]} Show the last n terms of the CWD. n=0 means show all. |
|
24 | 24 | \\Yn {cwd_y[n]} Like \Xn, but show '~' for $HOME |
|
25 | 25 | \\h hostname, up to the first '.' |
|
26 | 26 | \\H full hostname |
|
27 | 27 | \\u username (from the $USER environment variable) |
|
28 | 28 | \\v IPython version |
|
29 | 29 | \\$ root symbol ("$" for normal user or "#" for root) |
|
30 | 30 | ``\\`` escaped '\\' |
|
31 | 31 | \\n newline |
|
32 | 32 | \\r carriage return |
|
33 | 33 | n/a {color.<Name>} set terminal colour - see below for list of names |
|
34 | 34 | ====== =================================== ===================================================== |
|
35 | 35 | |
|
36 | 36 | Available colour names are: Black, BlinkBlack, BlinkBlue, BlinkCyan, |
|
37 | 37 | BlinkGreen, BlinkLightGray, BlinkPurple, BlinkRed, BlinkYellow, Blue, |
|
38 | 38 | Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, LightGreen, |
|
39 | 39 | LightPurple, LightRed, Purple, Red, White, Yellow. The selected colour |
|
40 | 40 | scheme also defines the names *prompt* and *number*. Finally, the name |
|
41 | 41 | *normal* resets the terminal to its default colour. |
|
42 | 42 | |
|
43 | 43 | So, this config:: |
|
44 | 44 | |
|
45 | 45 | c.PromptManager.in_template = "{color.LightGreen}{time}{color.Yellow} \u{color.normal}>>>" |
|
46 | 46 | |
|
47 | 47 | will produce input prompts with the time in light green, your username |
|
48 | 48 | in yellow, and a ``>>>`` prompt in the default terminal colour. |
|
49 | 49 | |
|
50 | 50 | |
|
51 | 51 | .. _termcolour: |
|
52 | 52 | |
|
53 | 53 | Terminal Colors |
|
54 | 54 | =============== |
|
55 | 55 | |
|
56 | 56 | The default IPython configuration has most bells and whistles turned on |
|
57 | 57 | (they're pretty safe). But there's one that may cause problems on some |
|
58 | 58 | systems: the use of color on screen for displaying information. This is |
|
59 | 59 | very useful, since IPython can show prompts and exception tracebacks |
|
60 | 60 | with various colors, display syntax-highlighted source code, and in |
|
61 | 61 | general make it easier to visually parse information. |
|
62 | 62 | |
|
63 | 63 | The following terminals seem to handle the color sequences fine: |
|
64 | 64 | |
|
65 | 65 | * Linux main text console, KDE Konsole, Gnome Terminal, E-term, |
|
66 | 66 | rxvt, xterm. |
|
67 | 67 | * CDE terminal (tested under Solaris). This one boldfaces light colors. |
|
68 | 68 | * (X)Emacs buffers. See the :ref:`emacs` section for more details on |
|
69 | 69 | using IPython with (X)Emacs. |
|
70 | 70 | * A Windows (XP/2k) command prompt with pyreadline_. |
|
71 | 71 | * A Windows (XP/2k) CygWin shell. Although some users have reported |
|
72 | 72 | problems; it is not clear whether there is an issue for everyone |
|
73 | 73 | or only under specific configurations. If you have full color |
|
74 | 74 | support under cygwin, please post to the IPython mailing list so |
|
75 | 75 | this issue can be resolved for all users. |
|
76 | 76 | |
|
77 | 77 | .. _pyreadline: https://code.launchpad.net/pyreadline |
|
78 | 78 | |
|
79 | 79 | These have shown problems: |
|
80 | 80 | |
|
81 | 81 | * Windows command prompt in WinXP/2k logged into a Linux machine via |
|
82 | 82 | telnet or ssh. |
|
83 | 83 | * Windows native command prompt in WinXP/2k, without Gary Bishop's |
|
84 | 84 | extensions. Once Gary's readline library is installed, the normal |
|
85 | 85 | WinXP/2k command prompt works perfectly. |
|
86 | 86 | |
|
87 | 87 | Currently the following color schemes are available: |
|
88 | 88 | |
|
89 | 89 | * NoColor: uses no color escapes at all (all escapes are empty '' '' |
|
90 | 90 | strings). This 'scheme' is thus fully safe to use in any terminal. |
|
91 | 91 | * Linux: works well in Linux console type environments: dark |
|
92 | 92 | background with light fonts. It uses bright colors for |
|
93 | 93 | information, so it is difficult to read if you have a light |
|
94 | 94 | colored background. |
|
95 | 95 | * LightBG: the basic colors are similar to those in the Linux scheme |
|
96 | 96 | but darker. It is easy to read in terminals with light backgrounds. |
|
97 | 97 | |
|
98 | 98 | IPython uses colors for two main groups of things: prompts and |
|
99 | 99 | tracebacks which are directly printed to the terminal, and the object |
|
100 | 100 | introspection system which passes large sets of data through a pager. |
|
101 | 101 | |
|
102 | 102 | If you are seeing garbage sequences in your terminal and no colour, you |
|
103 | 103 | may need to disable colours: run ``%colors NoColor`` inside IPython, or |
|
104 | 104 | add this to a config file:: |
|
105 | 105 | |
|
106 | 106 | c.InteractiveShell.colors = 'NoColor' |
|
107 | 107 | |
|
108 | 108 | Colors in the pager |
|
109 | 109 | ------------------- |
|
110 | 110 | |
|
111 | 111 | On some systems, the default pager has problems with ANSI colour codes. |
|
112 | 112 | To configure your default pager to allow these: |
|
113 | 113 | |
|
114 | 114 | 1. Set the environment PAGER variable to ``less``. |
|
115 | 115 | 2. Set the environment LESS variable to ``-r`` (plus any other options |
|
116 | 116 | you always want to pass to less by default). This tells less to |
|
117 | 117 | properly interpret control sequences, which is how color |
|
118 | 118 | information is given to your terminal. |
|
119 | 119 | |
|
120 | 120 | .. _editors: |
|
121 | 121 | |
|
122 | 122 | Editor configuration |
|
123 | 123 | ==================== |
|
124 | 124 | |
|
125 | 125 | IPython can integrate with text editors in a number of different ways: |
|
126 | 126 | |
|
127 | 127 | * Editors (such as `(X)Emacs`_, vim_ and TextMate_) can |
|
128 | 128 | send code to IPython for execution. |
|
129 | 129 | |
|
130 | 130 | * IPython's ``%edit`` magic command can open an editor of choice to edit |
|
131 | 131 | a code block. |
|
132 | 132 | |
|
133 | 133 | The %edit command (and its alias %ed) will invoke the editor set in your |
|
134 | 134 | environment as :envvar:`EDITOR`. If this variable is not set, it will default |
|
135 | 135 | to vi under Linux/Unix and to notepad under Windows. You may want to set this |
|
136 | 136 | variable properly and to a lightweight editor which doesn't take too long to |
|
137 | 137 | start (that is, something other than a new instance of Emacs). This way you |
|
138 | 138 | can edit multi-line code quickly and with the power of a real editor right |
|
139 | 139 | inside IPython. |
|
140 | 140 | |
|
141 | 141 | You can also control the editor by setting :attr:`TerminalInteractiveShell.editor` |
|
142 | 142 | in :file:`ipython_config.py`. |
|
143 | 143 | |
|
144 | 144 | Vim |
|
145 | 145 | --- |
|
146 | 146 | |
|
147 | 147 | Paul Ivanov's `vim-ipython <https://github.com/ivanov/vim-ipython>`_ provides |
|
148 | 148 | powerful IPython integration for vim. |
|
149 | 149 | |
|
150 | 150 | .. _emacs: |
|
151 | 151 | |
|
152 | 152 | (X)Emacs |
|
153 | 153 | -------- |
|
154 | 154 | |
|
155 | 155 | If you are a dedicated Emacs user, and want to use Emacs when IPython's |
|
156 | 156 | ``%edit`` magic command is called you should set up the Emacs server so that |
|
157 | 157 | new requests are handled by the original process. This means that almost no |
|
158 | 158 | time is spent in handling the request (assuming an Emacs process is already |
|
159 | 159 | running). For this to work, you need to set your EDITOR environment variable |
|
160 | 160 | to 'emacsclient'. The code below, supplied by Francois Pinard, can then be |
|
161 | 161 | used in your :file:`.emacs` file to enable the server: |
|
162 | 162 | |
|
163 | 163 | .. code-block:: common-lisp |
|
164 | 164 | |
|
165 | 165 | (defvar server-buffer-clients) |
|
166 | 166 | (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) |
|
167 | 167 | (server-start) |
|
168 | 168 | (defun fp-kill-server-with-buffer-routine () |
|
169 | 169 | (and server-buffer-clients (server-done))) |
|
170 | 170 | (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) |
|
171 | 171 | |
|
172 | 172 | Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, |
|
173 | 173 | currently (X)Emacs and IPython get along very well in other ways. |
|
174 | 174 | |
|
175 | .. note:: | |
|
176 | ||
|
177 | You will need to use a recent enough version of :file:`python-mode.el`, | |
|
178 | along with the file :file:`ipython.el`. You can check that the version you | |
|
179 | have of :file:`python-mode.el` is new enough by either looking at the | |
|
180 | revision number in the file itself, or asking for it in (X)Emacs via ``M-x | |
|
181 | py-version``. Versions 4.68 and newer contain the necessary fixes for | |
|
182 | proper IPython support. | |
|
183 | ||
|
184 | The file :file:`ipython.el` is included with the IPython distribution, in the | |
|
185 | directory :file:`docs/emacs`. Once you put these files in your Emacs path, all | |
|
186 | you need in your :file:`.emacs` file is: | |
|
175 | With (X)EMacs >= 24, You can enable IPython in python-mode with: | |
|
187 | 176 | |
|
188 | 177 | .. code-block:: common-lisp |
|
189 | 178 | |
|
190 |
(require ' |
|
|
191 | ||
|
192 | This should give you full support for executing code snippets via | |
|
193 | IPython, opening IPython as your Python shell via ``C-c !``, etc. | |
|
194 | ||
|
195 | You can customize the arguments passed to the IPython instance at startup by | |
|
196 | setting the ``py-python-command-args`` variable. For example, to start always | |
|
197 | with ``matplotlib`` integration and hardcoded light-background colors, you can use: | |
|
198 | ||
|
199 | .. code-block:: common-lisp | |
|
200 | ||
|
201 | (setq py-python-command-args '("--matplotlib" "--colors" "LightBG")) | |
|
202 | ||
|
203 | If you happen to get garbage instead of colored prompts as described in | |
|
204 | the previous section, you may need to set also in your :file:`.emacs` file: | |
|
205 | ||
|
206 | .. code-block:: common-lisp | |
|
207 | ||
|
208 | (setq ansi-color-for-comint-mode t) | |
|
209 | ||
|
210 | Notes on emacs support: | |
|
211 | ||
|
212 | .. This looks hopelessly out of date - can someone update it? | |
|
213 | ||
|
214 | * There is one caveat you should be aware of: you must start the IPython shell | |
|
215 | before attempting to execute any code regions via ``C-c |``. Simply type | |
|
216 | ``C-c !`` to start IPython before passing any code regions to the | |
|
217 | interpreter, and you shouldn't experience any problems. This is due to a bug | |
|
218 | in Python itself, which has been fixed for Python 2.3, but exists as of | |
|
219 | Python 2.2.2 (reported as SF bug [ 737947 ]). | |
|
220 | ||
|
221 | * The (X)Emacs support is maintained by Alexander Schmolck, so all | |
|
222 | comments/requests should be directed to him through the IPython mailing | |
|
223 | lists. | |
|
224 | ||
|
225 | * This code is still somewhat experimental so it's a bit rough around the | |
|
226 | edges (although in practice, it works quite well). | |
|
227 | ||
|
228 | * Be aware that if you customized ``py-python-command`` previously, this value | |
|
229 | will override what :file:`ipython.el` does (because loading the customization | |
|
230 | variables comes later). | |
|
179 | (require 'python) | |
|
180 | (setq python-shell-interpreter "ipython") | |
|
231 | 181 |
|
|
232 | 182 | .. _`(X)Emacs`: http://www.gnu.org/software/emacs/ |
|
233 | 183 | .. _TextMate: http://macromates.com/ |
|
234 | 184 | .. _vim: http://www.vim.org/ |
General Comments 0
You need to be logged in to leave comments.
Login now