##// END OF EJS Templates
remove description of long-dead ipython.el...
Min RK -
Show More
@@ -1,234 +1,184
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 Long Notes
15 Short Long Notes
16 ====== =================================== =====================================================
16 ====== =================================== =====================================================
17 %n,\\# {color.number}{count}{color.prompt} history counter with bolding
17 %n,\\# {color.number}{count}{color.prompt} history counter with bolding
18 \\N {count} history counter without bolding
18 \\N {count} history counter without bolding
19 \\D {dots} series of dots the same width as the history counter
19 \\D {dots} series of dots the same width as the history counter
20 \\T {time} current time
20 \\T {time} current time
21 \\w {cwd} current working directory
21 \\w {cwd} current working directory
22 \\W {cwd_last} basename of CWD
22 \\W {cwd_last} basename of CWD
23 \\Xn {cwd_x[n]} Show the last n terms of the CWD. n=0 means show all.
23 \\Xn {cwd_x[n]} Show the last n terms of the CWD. n=0 means show all.
24 \\Yn {cwd_y[n]} Like \Xn, but show '~' for $HOME
24 \\Yn {cwd_y[n]} Like \Xn, but show '~' for $HOME
25 \\h hostname, up to the first '.'
25 \\h hostname, up to the first '.'
26 \\H full hostname
26 \\H full hostname
27 \\u username (from the $USER environment variable)
27 \\u username (from the $USER environment variable)
28 \\v IPython version
28 \\v IPython version
29 \\$ root symbol ("$" for normal user or "#" for root)
29 \\$ root symbol ("$" for normal user or "#" for root)
30 ``\\`` escaped '\\'
30 ``\\`` escaped '\\'
31 \\n newline
31 \\n newline
32 \\r carriage return
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
162
163 .. code-block:: common-lisp
163 .. code-block:: common-lisp
164
164
165 (defvar server-buffer-clients)
165 (defvar server-buffer-clients)
166 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
166 (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
167 (server-start)
167 (server-start)
168 (defun fp-kill-server-with-buffer-routine ()
168 (defun fp-kill-server-with-buffer-routine ()
169 (and server-buffer-clients (server-done)))
169 (and server-buffer-clients (server-done)))
170 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
170 (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
171
171
172 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
172 Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
173 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.
174
174
175 .. note::
175 With (X)EMacs >= 24, You can enable IPython in python-mode with:
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:
187
176
188 .. code-block:: common-lisp
177 .. code-block:: common-lisp
189
178
190 (require 'ipython)
179 (require 'python)
191
180 (setq python-shell-interpreter "ipython")
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).
231
181
232 .. _`(X)Emacs`: http://www.gnu.org/software/emacs/
182 .. _`(X)Emacs`: http://www.gnu.org/software/emacs/
233 .. _TextMate: http://macromates.com/
183 .. _TextMate: http://macromates.com/
234 .. _vim: http://www.vim.org/
184 .. _vim: http://www.vim.org/
General Comments 0
You need to be logged in to leave comments. Login now