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