Show More
@@ -1,1261 +1,1262 b'' | |||||
1 | ================= |
|
1 | ================= | |
2 | IPython reference |
|
2 | IPython reference | |
3 | ================= |
|
3 | ================= | |
4 |
|
4 | |||
5 | .. _command_line_options: |
|
5 | .. _command_line_options: | |
6 |
|
6 | |||
7 | Command-line usage |
|
7 | Command-line usage | |
8 | ================== |
|
8 | ================== | |
9 |
|
9 | |||
10 | You start IPython with the command:: |
|
10 | You start IPython with the command:: | |
11 |
|
11 | |||
12 | $ ipython [options] files |
|
12 | $ ipython [options] files | |
13 |
|
13 | |||
14 | .. note:: |
|
14 | .. note:: | |
15 |
|
15 | |||
16 | For IPython on Python 3, use ``ipython3`` in place of ``ipython``. |
|
16 | For IPython on Python 3, use ``ipython3`` in place of ``ipython``. | |
17 |
|
17 | |||
18 | If invoked with no options, it executes all the files listed in sequence |
|
18 | If invoked with no options, it executes all the files listed in sequence | |
19 | and drops you into the interpreter while still acknowledging any options |
|
19 | and drops you into the interpreter while still acknowledging any options | |
20 | you may have set in your ipython_config.py. This behavior is different from |
|
20 | you may have set in your ipython_config.py. This behavior is different from | |
21 | standard Python, which when called as python -i will only execute one |
|
21 | standard Python, which when called as python -i will only execute one | |
22 | file and ignore your configuration setup. |
|
22 | file and ignore your configuration setup. | |
23 |
|
23 | |||
24 | Please note that some of the configuration options are not available at |
|
24 | Please note that some of the configuration options are not available at | |
25 | the command line, simply because they are not practical here. Look into |
|
25 | the command line, simply because they are not practical here. Look into | |
26 | your configuration files for details on those. There are separate configuration |
|
26 | your configuration files for details on those. There are separate configuration | |
27 | files for each profile, and the files look like "ipython_config.py" or |
|
27 | files for each profile, and the files look like "ipython_config.py" or | |
28 | "ipython_config_<frontendname>.py". Profile directories look like |
|
28 | "ipython_config_<frontendname>.py". Profile directories look like | |
29 | "profile_profilename" and are typically installed in the IPYTHON_DIR directory. |
|
29 | "profile_profilename" and are typically installed in the IPYTHON_DIR directory. | |
30 | For Linux users, this will be $HOME/.config/ipython, and for other users it |
|
30 | For Linux users, this will be $HOME/.config/ipython, and for other users it | |
31 | will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and |
|
31 | will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and | |
32 | Settings\\YourUserName in most instances. |
|
32 | Settings\\YourUserName in most instances. | |
33 |
|
33 | |||
34 |
|
34 | |||
35 | Eventloop integration |
|
35 | Eventloop integration | |
36 | --------------------- |
|
36 | --------------------- | |
37 |
|
37 | |||
38 | Previously IPython had command line options for controlling GUI event loop |
|
38 | Previously IPython had command line options for controlling GUI event loop | |
39 | integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython |
|
39 | integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython | |
40 | version 0.11, these have been removed. Please see the new ``%gui`` |
|
40 | version 0.11, these have been removed. Please see the new ``%gui`` | |
41 | magic command or :ref:`this section <gui_support>` for details on the new |
|
41 | magic command or :ref:`this section <gui_support>` for details on the new | |
42 | interface, or specify the gui at the commandline:: |
|
42 | interface, or specify the gui at the commandline:: | |
43 |
|
43 | |||
44 | $ ipython --gui=qt |
|
44 | $ ipython --gui=qt | |
45 |
|
45 | |||
46 |
|
46 | |||
47 | Regular Options |
|
47 | Regular Options | |
48 | --------------- |
|
48 | --------------- | |
49 |
|
49 | |||
50 | After the above threading options have been given, regular options can |
|
50 | After the above threading options have been given, regular options can | |
51 | follow in any order. All options can be abbreviated to their shortest |
|
51 | follow in any order. All options can be abbreviated to their shortest | |
52 | non-ambiguous form and are case-sensitive. |
|
52 | non-ambiguous form and are case-sensitive. | |
53 |
|
53 | |||
54 | Most options can also be set from your configuration file. See the provided |
|
54 | Most options can also be set from your configuration file. See the provided | |
55 | example for more details on what the options do. Options given at the command |
|
55 | example for more details on what the options do. Options given at the command | |
56 | line override the values set in the configuration file. |
|
56 | line override the values set in the configuration file. | |
57 |
|
57 | |||
58 | All options with a [no] prepended can be specified in negated form |
|
58 | All options with a [no] prepended can be specified in negated form | |
59 | (--no-option instead of --option) to turn the feature off. |
|
59 | (--no-option instead of --option) to turn the feature off. | |
60 |
|
60 | |||
61 | ``-h, --help`` print a help message and exit. |
|
61 | ``-h, --help`` print a help message and exit. | |
62 |
|
62 | |||
63 | ``--pylab, pylab=<name>`` |
|
63 | ``--pylab, pylab=<name>`` | |
64 | See :ref:`Matplotlib support <matplotlib_support>` |
|
64 | See :ref:`Matplotlib support <matplotlib_support>` | |
65 | for more details. |
|
65 | for more details. | |
66 |
|
66 | |||
67 | ``--autocall=<val>`` |
|
67 | ``--autocall=<val>`` | |
68 | Make IPython automatically call any callable object even if you |
|
68 | Make IPython automatically call any callable object even if you | |
69 | didn't type explicit parentheses. For example, 'str 43' becomes |
|
69 | didn't type explicit parentheses. For example, 'str 43' becomes | |
70 | 'str(43)' automatically. The value can be '0' to disable the feature, |
|
70 | 'str(43)' automatically. The value can be '0' to disable the feature, | |
71 | '1' for smart autocall, where it is not applied if there are no more |
|
71 | '1' for smart autocall, where it is not applied if there are no more | |
72 | arguments on the line, and '2' for full autocall, where all callable |
|
72 | arguments on the line, and '2' for full autocall, where all callable | |
73 | objects are automatically called (even if no arguments are |
|
73 | objects are automatically called (even if no arguments are | |
74 | present). The default is '1'. |
|
74 | present). The default is '1'. | |
75 |
|
75 | |||
76 | ``--[no-]autoindent`` |
|
76 | ``--[no-]autoindent`` | |
77 | Turn automatic indentation on/off. |
|
77 | Turn automatic indentation on/off. | |
78 |
|
78 | |||
79 | ``--[no-]automagic`` |
|
79 | ``--[no-]automagic`` | |
80 | make magic commands automatic (without needing their first character |
|
80 | make magic commands automatic (without needing their first character | |
81 | to be %). Type %magic at the IPython prompt for more information. |
|
81 | to be %). Type %magic at the IPython prompt for more information. | |
82 |
|
82 | |||
83 | ``--[no-]autoedit_syntax`` |
|
83 | ``--[no-]autoedit_syntax`` | |
84 | When a syntax error occurs after editing a file, automatically |
|
84 | When a syntax error occurs after editing a file, automatically | |
85 | open the file to the trouble causing line for convenient |
|
85 | open the file to the trouble causing line for convenient | |
86 | fixing. |
|
86 | fixing. | |
87 |
|
87 | |||
88 | ``--[no-]banner`` |
|
88 | ``--[no-]banner`` | |
89 | Print the initial information banner (default on). |
|
89 | Print the initial information banner (default on). | |
90 |
|
90 | |||
91 | ``-c <command>`` |
|
91 | ``-c <command>`` | |
92 | execute the given command string. This is similar to the -c |
|
92 | execute the given command string. This is similar to the -c | |
93 | option in the normal Python interpreter. |
|
93 | option in the normal Python interpreter. | |
94 |
|
94 | |||
95 | ``--cache-size=<n>`` |
|
95 | ``--cache-size=<n>`` | |
96 | size of the output cache (maximum number of entries to hold in |
|
96 | size of the output cache (maximum number of entries to hold in | |
97 | memory). The default is 1000, you can change it permanently in your |
|
97 | memory). The default is 1000, you can change it permanently in your | |
98 | config file. Setting it to 0 completely disables the caching system, |
|
98 | config file. Setting it to 0 completely disables the caching system, | |
99 | and the minimum value accepted is 20 (if you provide a value less than |
|
99 | and the minimum value accepted is 20 (if you provide a value less than | |
100 | 20, it is reset to 0 and a warning is issued) This limit is defined |
|
100 | 20, it is reset to 0 and a warning is issued) This limit is defined | |
101 | because otherwise you'll spend more time re-flushing a too small cache |
|
101 | because otherwise you'll spend more time re-flushing a too small cache | |
102 | than working. |
|
102 | than working. | |
103 |
|
103 | |||
104 | ``--classic`` |
|
104 | ``--classic`` | |
105 | Gives IPython a similar feel to the classic Python |
|
105 | Gives IPython a similar feel to the classic Python | |
106 | prompt. |
|
106 | prompt. | |
107 |
|
107 | |||
108 | ``--colors=<scheme>`` |
|
108 | ``--colors=<scheme>`` | |
109 | Color scheme for prompts and exception reporting. Currently |
|
109 | Color scheme for prompts and exception reporting. Currently | |
110 | implemented: NoColor, Linux and LightBG. |
|
110 | implemented: NoColor, Linux and LightBG. | |
111 |
|
111 | |||
112 | ``--[no-]color_info`` |
|
112 | ``--[no-]color_info`` | |
113 | IPython can display information about objects via a set of functions, |
|
113 | IPython can display information about objects via a set of functions, | |
114 | and optionally can use colors for this, syntax highlighting source |
|
114 | and optionally can use colors for this, syntax highlighting source | |
115 | code and various other elements. However, because this information is |
|
115 | code and various other elements. However, because this information is | |
116 | passed through a pager (like 'less') and many pagers get confused with |
|
116 | passed through a pager (like 'less') and many pagers get confused with | |
117 | color codes, this option is off by default. You can test it and turn |
|
117 | color codes, this option is off by default. You can test it and turn | |
118 | it on permanently in your configuration file if it works for you. As a |
|
118 | it on permanently in your configuration file if it works for you. As a | |
119 | reference, the 'less' pager supplied with Mandrake 8.2 works ok, but |
|
119 | reference, the 'less' pager supplied with Mandrake 8.2 works ok, but | |
120 | that in RedHat 7.2 doesn't. |
|
120 | that in RedHat 7.2 doesn't. | |
121 |
|
121 | |||
122 | Test it and turn it on permanently if it works with your |
|
122 | Test it and turn it on permanently if it works with your | |
123 | system. The magic function %color_info allows you to toggle this |
|
123 | system. The magic function %color_info allows you to toggle this | |
124 | interactively for testing. |
|
124 | interactively for testing. | |
125 |
|
125 | |||
126 | ``--[no-]debug`` |
|
126 | ``--[no-]debug`` | |
127 | Show information about the loading process. Very useful to pin down |
|
127 | Show information about the loading process. Very useful to pin down | |
128 | problems with your configuration files or to get details about |
|
128 | problems with your configuration files or to get details about | |
129 | session restores. |
|
129 | session restores. | |
130 |
|
130 | |||
131 | ``--[no-]deep_reload`` |
|
131 | ``--[no-]deep_reload`` | |
132 | IPython can use the deep_reload module which reloads changes in |
|
132 | IPython can use the deep_reload module which reloads changes in | |
133 | modules recursively (it replaces the reload() function, so you don't |
|
133 | modules recursively (it replaces the reload() function, so you don't | |
134 | need to change anything to use it). deep_reload() forces a full |
|
134 | need to change anything to use it). deep_reload() forces a full | |
135 | reload of modules whose code may have changed, which the default |
|
135 | reload of modules whose code may have changed, which the default | |
136 | reload() function does not. |
|
136 | reload() function does not. | |
137 |
|
137 | |||
138 | When deep_reload is off, IPython will use the normal reload(), |
|
138 | When deep_reload is off, IPython will use the normal reload(), | |
139 | but deep_reload will still be available as dreload(). This |
|
139 | but deep_reload will still be available as dreload(). This | |
140 | feature is off by default [which means that you have both |
|
140 | feature is off by default [which means that you have both | |
141 | normal reload() and dreload()]. |
|
141 | normal reload() and dreload()]. | |
142 |
|
142 | |||
143 | ``--editor=<name>`` |
|
143 | ``--editor=<name>`` | |
144 | Which editor to use with the %edit command. By default, |
|
144 | Which editor to use with the %edit command. By default, | |
145 | IPython will honor your EDITOR environment variable (if not |
|
145 | IPython will honor your EDITOR environment variable (if not | |
146 | set, vi is the Unix default and notepad the Windows one). |
|
146 | set, vi is the Unix default and notepad the Windows one). | |
147 | Since this editor is invoked on the fly by IPython and is |
|
147 | Since this editor is invoked on the fly by IPython and is | |
148 | meant for editing small code snippets, you may want to use a |
|
148 | meant for editing small code snippets, you may want to use a | |
149 | small, lightweight editor here (in case your default EDITOR is |
|
149 | small, lightweight editor here (in case your default EDITOR is | |
150 | something like Emacs). |
|
150 | something like Emacs). | |
151 |
|
151 | |||
152 | ``--ipython_dir=<name>`` |
|
152 | ``--ipython_dir=<name>`` | |
153 | name of your IPython configuration directory IPYTHON_DIR. This |
|
153 | name of your IPython configuration directory IPYTHON_DIR. This | |
154 | can also be specified through the environment variable |
|
154 | can also be specified through the environment variable | |
155 | IPYTHON_DIR. |
|
155 | IPYTHON_DIR. | |
156 |
|
156 | |||
157 | ``--logfile=<name>`` |
|
157 | ``--logfile=<name>`` | |
158 | specify the name of your logfile. |
|
158 | specify the name of your logfile. | |
159 |
|
159 | |||
160 | This implies ``%logstart`` at the beginning of your session |
|
160 | This implies ``%logstart`` at the beginning of your session | |
161 |
|
161 | |||
162 | generate a log file of all input. The file is named |
|
162 | generate a log file of all input. The file is named | |
163 | ipython_log.py in your current directory (which prevents logs |
|
163 | ipython_log.py in your current directory (which prevents logs | |
164 | from multiple IPython sessions from trampling each other). You |
|
164 | from multiple IPython sessions from trampling each other). You | |
165 | can use this to later restore a session by loading your |
|
165 | can use this to later restore a session by loading your | |
166 | logfile with ``ipython -i ipython_log.py`` |
|
166 | logfile with ``ipython -i ipython_log.py`` | |
167 |
|
167 | |||
168 | ``--logplay=<name>`` |
|
168 | ``--logplay=<name>`` | |
169 |
|
169 | |||
170 | NOT AVAILABLE in 0.11 |
|
170 | NOT AVAILABLE in 0.11 | |
171 |
|
171 | |||
172 | you can replay a previous log. For restoring a session as close as |
|
172 | you can replay a previous log. For restoring a session as close as | |
173 | possible to the state you left it in, use this option (don't just run |
|
173 | possible to the state you left it in, use this option (don't just run | |
174 | the logfile). With -logplay, IPython will try to reconstruct the |
|
174 | the logfile). With -logplay, IPython will try to reconstruct the | |
175 | previous working environment in full, not just execute the commands in |
|
175 | previous working environment in full, not just execute the commands in | |
176 | the logfile. |
|
176 | the logfile. | |
177 |
|
177 | |||
178 | When a session is restored, logging is automatically turned on |
|
178 | When a session is restored, logging is automatically turned on | |
179 | again with the name of the logfile it was invoked with (it is |
|
179 | again with the name of the logfile it was invoked with (it is | |
180 | read from the log header). So once you've turned logging on for |
|
180 | read from the log header). So once you've turned logging on for | |
181 | a session, you can quit IPython and reload it as many times as |
|
181 | a session, you can quit IPython and reload it as many times as | |
182 | you want and it will continue to log its history and restore |
|
182 | you want and it will continue to log its history and restore | |
183 | from the beginning every time. |
|
183 | from the beginning every time. | |
184 |
|
184 | |||
185 | Caveats: there are limitations in this option. The history |
|
185 | Caveats: there are limitations in this option. The history | |
186 | variables _i*,_* and _dh don't get restored properly. In the |
|
186 | variables _i*,_* and _dh don't get restored properly. In the | |
187 | future we will try to implement full session saving by writing |
|
187 | future we will try to implement full session saving by writing | |
188 | and retrieving a 'snapshot' of the memory state of IPython. But |
|
188 | and retrieving a 'snapshot' of the memory state of IPython. But | |
189 | our first attempts failed because of inherent limitations of |
|
189 | our first attempts failed because of inherent limitations of | |
190 | Python's Pickle module, so this may have to wait. |
|
190 | Python's Pickle module, so this may have to wait. | |
191 |
|
191 | |||
192 | ``--[no-]messages`` |
|
192 | ``--[no-]messages`` | |
193 | Print messages which IPython collects about its startup |
|
193 | Print messages which IPython collects about its startup | |
194 | process (default on). |
|
194 | process (default on). | |
195 |
|
195 | |||
196 | ``--[no-]pdb`` |
|
196 | ``--[no-]pdb`` | |
197 | Automatically call the pdb debugger after every uncaught |
|
197 | Automatically call the pdb debugger after every uncaught | |
198 | exception. If you are used to debugging using pdb, this puts |
|
198 | exception. If you are used to debugging using pdb, this puts | |
199 | you automatically inside of it after any call (either in |
|
199 | you automatically inside of it after any call (either in | |
200 | IPython or in code called by it) which triggers an exception |
|
200 | IPython or in code called by it) which triggers an exception | |
201 | which goes uncaught. |
|
201 | which goes uncaught. | |
202 |
|
202 | |||
203 | ``--[no-]pprint`` |
|
203 | ``--[no-]pprint`` | |
204 | ipython can optionally use the pprint (pretty printer) module |
|
204 | ipython can optionally use the pprint (pretty printer) module | |
205 | for displaying results. pprint tends to give a nicer display |
|
205 | for displaying results. pprint tends to give a nicer display | |
206 | of nested data structures. If you like it, you can turn it on |
|
206 | of nested data structures. If you like it, you can turn it on | |
207 | permanently in your config file (default off). |
|
207 | permanently in your config file (default off). | |
208 |
|
208 | |||
209 | ``--profile=<name>`` |
|
209 | ``--profile=<name>`` | |
210 |
|
210 | |||
211 | Select the IPython profile by name. |
|
211 | Select the IPython profile by name. | |
212 |
|
212 | |||
213 | This is a quick way to keep and load multiple |
|
213 | This is a quick way to keep and load multiple | |
214 | config files for different tasks, especially if you use the |
|
214 | config files for different tasks, especially if you use the | |
215 | include option of config files. You can keep a basic |
|
215 | include option of config files. You can keep a basic | |
216 | :file:`IPYTHON_DIR/profile_default/ipython_config.py` file |
|
216 | :file:`IPYTHON_DIR/profile_default/ipython_config.py` file | |
217 | and then have other 'profiles' which |
|
217 | and then have other 'profiles' which | |
218 | include this one and load extra things for particular |
|
218 | include this one and load extra things for particular | |
219 | tasks. For example: |
|
219 | tasks. For example: | |
220 |
|
220 | |||
221 | 1. $IPYTHON_DIR/profile_default : load basic things you always want. |
|
221 | 1. $IPYTHON_DIR/profile_default : load basic things you always want. | |
222 | 2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules. |
|
222 | 2. $IPYTHON_DIR/profile_math : load (1) and basic math-related modules. | |
223 | 3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules. |
|
223 | 3. $IPYTHON_DIR/profile_numeric : load (1) and Numeric and plotting modules. | |
224 |
|
224 | |||
225 | Since it is possible to create an endless loop by having |
|
225 | Since it is possible to create an endless loop by having | |
226 | circular file inclusions, IPython will stop if it reaches 15 |
|
226 | circular file inclusions, IPython will stop if it reaches 15 | |
227 | recursive inclusions. |
|
227 | recursive inclusions. | |
228 |
|
228 | |||
229 | ``InteractiveShell.prompt_in1=<string>`` |
|
229 | ``InteractiveShell.prompt_in1=<string>`` | |
230 |
|
230 | |||
231 | Specify the string used for input prompts. Note that if you are using |
|
231 | Specify the string used for input prompts. Note that if you are using | |
232 | numbered prompts, the number is represented with a '\#' in the |
|
232 | numbered prompts, the number is represented with a '\#' in the | |
233 | string. Don't forget to quote strings with spaces embedded in |
|
233 | string. Don't forget to quote strings with spaces embedded in | |
234 | them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>` |
|
234 | them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>` | |
235 | discusses in detail all the available escapes to customize your |
|
235 | discusses in detail all the available escapes to customize your | |
236 | prompts. |
|
236 | prompts. | |
237 |
|
237 | |||
238 | ``InteractiveShell.prompt_in2=<string>`` |
|
238 | ``InteractiveShell.prompt_in2=<string>`` | |
239 | Similar to the previous option, but used for the continuation |
|
239 | Similar to the previous option, but used for the continuation | |
240 | prompts. The special sequence '\D' is similar to '\#', but |
|
240 | prompts. The special sequence '\D' is similar to '\#', but | |
241 | with all digits replaced dots (so you can have your |
|
241 | with all digits replaced dots (so you can have your | |
242 | continuation prompt aligned with your input prompt). Default: |
|
242 | continuation prompt aligned with your input prompt). Default: | |
243 | ' .\D.:' (note three spaces at the start for alignment with |
|
243 | ' .\D.:' (note three spaces at the start for alignment with | |
244 | 'In [\#]'). |
|
244 | 'In [\#]'). | |
245 |
|
245 | |||
246 | ``InteractiveShell.prompt_out=<string>`` |
|
246 | ``InteractiveShell.prompt_out=<string>`` | |
247 | String used for output prompts, also uses numbers like |
|
247 | String used for output prompts, also uses numbers like | |
248 | prompt_in1. Default: 'Out[\#]:' |
|
248 | prompt_in1. Default: 'Out[\#]:' | |
249 |
|
249 | |||
250 | ``--quick`` |
|
250 | ``--quick`` | |
251 | start in bare bones mode (no config file loaded). |
|
251 | start in bare bones mode (no config file loaded). | |
252 |
|
252 | |||
253 | ``config_file=<name>`` |
|
253 | ``config_file=<name>`` | |
254 | name of your IPython resource configuration file. Normally |
|
254 | name of your IPython resource configuration file. Normally | |
255 | IPython loads ipython_config.py (from current directory) or |
|
255 | IPython loads ipython_config.py (from current directory) or | |
256 | IPYTHON_DIR/profile_default. |
|
256 | IPYTHON_DIR/profile_default. | |
257 |
|
257 | |||
258 | If the loading of your config file fails, IPython starts with |
|
258 | If the loading of your config file fails, IPython starts with | |
259 | a bare bones configuration (no modules loaded at all). |
|
259 | a bare bones configuration (no modules loaded at all). | |
260 |
|
260 | |||
261 | ``--[no-]readline`` |
|
261 | ``--[no-]readline`` | |
262 | use the readline library, which is needed to support name |
|
262 | use the readline library, which is needed to support name | |
263 | completion and command history, among other things. It is |
|
263 | completion and command history, among other things. It is | |
264 | enabled by default, but may cause problems for users of |
|
264 | enabled by default, but may cause problems for users of | |
265 | X/Emacs in Python comint or shell buffers. |
|
265 | X/Emacs in Python comint or shell buffers. | |
266 |
|
266 | |||
267 | Note that X/Emacs 'eterm' buffers (opened with M-x term) support |
|
267 | Note that X/Emacs 'eterm' buffers (opened with M-x term) support | |
268 | IPython's readline and syntax coloring fine, only 'emacs' (M-x |
|
268 | IPython's readline and syntax coloring fine, only 'emacs' (M-x | |
269 | shell and C-c !) buffers do not. |
|
269 | shell and C-c !) buffers do not. | |
270 |
|
270 | |||
271 | ``--TerminalInteractiveShell.screen_length=<n>`` |
|
271 | ``--TerminalInteractiveShell.screen_length=<n>`` | |
272 | number of lines of your screen. This is used to control |
|
272 | number of lines of your screen. This is used to control | |
273 | printing of very long strings. Strings longer than this number |
|
273 | printing of very long strings. Strings longer than this number | |
274 | of lines will be sent through a pager instead of directly |
|
274 | of lines will be sent through a pager instead of directly | |
275 | printed. |
|
275 | printed. | |
276 |
|
276 | |||
277 | The default value for this is 0, which means IPython will |
|
277 | The default value for this is 0, which means IPython will | |
278 | auto-detect your screen size every time it needs to print certain |
|
278 | auto-detect your screen size every time it needs to print certain | |
279 | potentially long strings (this doesn't change the behavior of the |
|
279 | potentially long strings (this doesn't change the behavior of the | |
280 | 'print' keyword, it's only triggered internally). If for some |
|
280 | 'print' keyword, it's only triggered internally). If for some | |
281 | reason this isn't working well (it needs curses support), specify |
|
281 | reason this isn't working well (it needs curses support), specify | |
282 | it yourself. Otherwise don't change the default. |
|
282 | it yourself. Otherwise don't change the default. | |
283 |
|
283 | |||
284 | ``--TerminalInteractiveShell.separate_in=<string>`` |
|
284 | ``--TerminalInteractiveShell.separate_in=<string>`` | |
285 |
|
285 | |||
286 | separator before input prompts. |
|
286 | separator before input prompts. | |
287 | Default: '\n' |
|
287 | Default: '\n' | |
288 |
|
288 | |||
289 | ``--TerminalInteractiveShell.separate_out=<string>`` |
|
289 | ``--TerminalInteractiveShell.separate_out=<string>`` | |
290 | separator before output prompts. |
|
290 | separator before output prompts. | |
291 | Default: nothing. |
|
291 | Default: nothing. | |
292 |
|
292 | |||
293 | ``--TerminalInteractiveShell.separate_out2=<string>`` |
|
293 | ``--TerminalInteractiveShell.separate_out2=<string>`` | |
294 | separator after output prompts. |
|
294 | separator after output prompts. | |
295 | Default: nothing. |
|
295 | Default: nothing. | |
296 | For these three options, use the value 0 to specify no separator. |
|
296 | For these three options, use the value 0 to specify no separator. | |
297 |
|
297 | |||
298 | ``--nosep`` |
|
298 | ``--nosep`` | |
299 | shorthand for setting the above separators to empty strings. |
|
299 | shorthand for setting the above separators to empty strings. | |
300 |
|
300 | |||
301 | Simply removes all input/output separators. |
|
301 | Simply removes all input/output separators. | |
302 |
|
302 | |||
303 | ``--init`` |
|
303 | ``--init`` | |
304 | allows you to initialize a profile dir for configuration when you |
|
304 | allows you to initialize a profile dir for configuration when you | |
305 | install a new version of IPython or want to use a new profile. |
|
305 | install a new version of IPython or want to use a new profile. | |
306 | Since new versions may include new command line options or example |
|
306 | Since new versions may include new command line options or example | |
307 | files, this copies updated config files. Note that you should probably |
|
307 | files, this copies updated config files. Note that you should probably | |
308 | use %upgrade instead,it's a safer alternative. |
|
308 | use %upgrade instead,it's a safer alternative. | |
309 |
|
309 | |||
310 | ``--version`` print version information and exit. |
|
310 | ``--version`` print version information and exit. | |
311 |
|
311 | |||
312 | ``--xmode=<modename>`` |
|
312 | ``--xmode=<modename>`` | |
313 |
|
313 | |||
314 | Mode for exception reporting. |
|
314 | Mode for exception reporting. | |
315 |
|
315 | |||
316 | Valid modes: Plain, Context and Verbose. |
|
316 | Valid modes: Plain, Context and Verbose. | |
317 |
|
317 | |||
318 | * Plain: similar to python's normal traceback printing. |
|
318 | * Plain: similar to python's normal traceback printing. | |
319 | * Context: prints 5 lines of context source code around each |
|
319 | * Context: prints 5 lines of context source code around each | |
320 | line in the traceback. |
|
320 | line in the traceback. | |
321 | * Verbose: similar to Context, but additionally prints the |
|
321 | * Verbose: similar to Context, but additionally prints the | |
322 | variables currently visible where the exception happened |
|
322 | variables currently visible where the exception happened | |
323 | (shortening their strings if too long). This can potentially be |
|
323 | (shortening their strings if too long). This can potentially be | |
324 | very slow, if you happen to have a huge data structure whose |
|
324 | very slow, if you happen to have a huge data structure whose | |
325 | string representation is complex to compute. Your computer may |
|
325 | string representation is complex to compute. Your computer may | |
326 | appear to freeze for a while with cpu usage at 100%. If this |
|
326 | appear to freeze for a while with cpu usage at 100%. If this | |
327 | occurs, you can cancel the traceback with Ctrl-C (maybe hitting it |
|
327 | occurs, you can cancel the traceback with Ctrl-C (maybe hitting it | |
328 | more than once). |
|
328 | more than once). | |
329 |
|
329 | |||
330 | Interactive use |
|
330 | Interactive use | |
331 | =============== |
|
331 | =============== | |
332 |
|
332 | |||
333 | IPython is meant to work as a drop-in replacement for the standard interactive |
|
333 | IPython is meant to work as a drop-in replacement for the standard interactive | |
334 | interpreter. As such, any code which is valid python should execute normally |
|
334 | interpreter. As such, any code which is valid python should execute normally | |
335 | under IPython (cases where this is not true should be reported as bugs). It |
|
335 | under IPython (cases where this is not true should be reported as bugs). It | |
336 | does, however, offer many features which are not available at a standard python |
|
336 | does, however, offer many features which are not available at a standard python | |
337 | prompt. What follows is a list of these. |
|
337 | prompt. What follows is a list of these. | |
338 |
|
338 | |||
339 |
|
339 | |||
340 | Caution for Windows users |
|
340 | Caution for Windows users | |
341 | ------------------------- |
|
341 | ------------------------- | |
342 |
|
342 | |||
343 | Windows, unfortunately, uses the '\\' character as a path separator. This is a |
|
343 | Windows, unfortunately, uses the '\\' character as a path separator. This is a | |
344 | terrible choice, because '\\' also represents the escape character in most |
|
344 | terrible choice, because '\\' also represents the escape character in most | |
345 | modern programming languages, including Python. For this reason, using '/' |
|
345 | modern programming languages, including Python. For this reason, using '/' | |
346 | character is recommended if you have problems with ``\``. However, in Windows |
|
346 | character is recommended if you have problems with ``\``. However, in Windows | |
347 | commands '/' flags options, so you can not use it for the root directory. This |
|
347 | commands '/' flags options, so you can not use it for the root directory. This | |
348 | means that paths beginning at the root must be typed in a contrived manner |
|
348 | means that paths beginning at the root must be typed in a contrived manner | |
349 | like: ``%copy \opt/foo/bar.txt \tmp`` |
|
349 | like: ``%copy \opt/foo/bar.txt \tmp`` | |
350 |
|
350 | |||
351 | .. _magic: |
|
351 | .. _magic: | |
352 |
|
352 | |||
353 | Magic command system |
|
353 | Magic command system | |
354 | -------------------- |
|
354 | -------------------- | |
355 |
|
355 | |||
356 | IPython will treat any line whose first character is a % as a special |
|
356 | IPython will treat any line whose first character is a % as a special | |
357 | call to a 'magic' function. These allow you to control the behavior of |
|
357 | call to a 'magic' function. These allow you to control the behavior of | |
358 | IPython itself, plus a lot of system-type features. They are all |
|
358 | IPython itself, plus a lot of system-type features. They are all | |
359 | prefixed with a % character, but parameters are given without |
|
359 | prefixed with a % character, but parameters are given without | |
360 | parentheses or quotes. |
|
360 | parentheses or quotes. | |
361 |
|
361 | |||
362 | Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it |
|
362 | Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it | |
363 | exists. |
|
363 | exists. | |
364 |
|
364 | |||
365 | If you have 'automagic' enabled (as it by default), you don't need |
|
365 | If you have 'automagic' enabled (as it by default), you don't need | |
366 | to type in the % explicitly. IPython will scan its internal list of |
|
366 | to type in the % explicitly. IPython will scan its internal list of | |
367 | magic functions and call one if it exists. With automagic on you can |
|
367 | magic functions and call one if it exists. With automagic on you can | |
368 | then just type ``cd mydir`` to go to directory 'mydir'. The automagic |
|
368 | then just type ``cd mydir`` to go to directory 'mydir'. The automagic | |
369 | system has the lowest possible precedence in name searches, so defining |
|
369 | system has the lowest possible precedence in name searches, so defining | |
370 | an identifier with the same name as an existing magic function will |
|
370 | an identifier with the same name as an existing magic function will | |
371 | shadow it for automagic use. You can still access the shadowed magic |
|
371 | shadow it for automagic use. You can still access the shadowed magic | |
372 | function by explicitly using the % character at the beginning of the line. |
|
372 | function by explicitly using the % character at the beginning of the line. | |
373 |
|
373 | |||
374 | An example (with automagic on) should clarify all this: |
|
374 | An example (with automagic on) should clarify all this: | |
375 |
|
375 | |||
376 | .. sourcecode:: ipython |
|
376 | .. sourcecode:: ipython | |
377 |
|
377 | |||
378 | In [1]: cd ipython # %cd is called by automagic |
|
378 | In [1]: cd ipython # %cd is called by automagic | |
379 | /home/fperez/ipython |
|
379 | /home/fperez/ipython | |
380 |
|
380 | |||
381 | In [2]: cd=1 # now cd is just a variable |
|
381 | In [2]: cd=1 # now cd is just a variable | |
382 |
|
382 | |||
383 | In [3]: cd .. # and doesn't work as a function anymore |
|
383 | In [3]: cd .. # and doesn't work as a function anymore | |
384 | File "<ipython-input-3-9fedb3aff56c>", line 1 |
|
384 | File "<ipython-input-3-9fedb3aff56c>", line 1 | |
385 | cd .. |
|
385 | cd .. | |
386 | ^ |
|
386 | ^ | |
387 | SyntaxError: invalid syntax |
|
387 | SyntaxError: invalid syntax | |
388 |
|
388 | |||
389 |
|
389 | |||
390 | In [4]: %cd .. # but %cd always works |
|
390 | In [4]: %cd .. # but %cd always works | |
391 | /home/fperez |
|
391 | /home/fperez | |
392 |
|
392 | |||
393 | In [5]: del cd # if you remove the cd variable, automagic works again |
|
393 | In [5]: del cd # if you remove the cd variable, automagic works again | |
394 |
|
394 | |||
395 | In [6]: cd ipython |
|
395 | In [6]: cd ipython | |
396 |
|
396 | |||
397 | /home/fperez/ipython |
|
397 | /home/fperez/ipython | |
398 |
|
398 | |||
399 | You can define your own magic functions to extend the system. The |
|
399 | You can define your own magic functions to extend the system. The | |
400 | following example defines a new magic command, %impall: |
|
400 | following example defines a new magic command, %impall: | |
401 |
|
401 | |||
402 | .. sourcecode:: python |
|
402 | .. sourcecode:: python | |
403 |
|
403 | |||
404 | ip = get_ipython() |
|
404 | ip = get_ipython() | |
405 |
|
405 | |||
406 | def doimp(self, arg): |
|
406 | def doimp(self, arg): | |
407 | ip = self.api |
|
407 | ip = self.api | |
408 | ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) ) |
|
408 | ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) ) | |
409 |
|
409 | |||
410 | ip.define_magic('impall', doimp) |
|
410 | ip.define_magic('impall', doimp) | |
411 |
|
411 | |||
412 | Type ``%magic`` for more information, including a list of all available magic |
|
412 | Type ``%magic`` for more information, including a list of all available magic | |
413 | functions at any time and their docstrings. You can also type |
|
413 | functions at any time and their docstrings. You can also type | |
414 | ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on |
|
414 | ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on | |
415 | the '?' system) to get information about any particular magic function you are |
|
415 | the '?' system) to get information about any particular magic function you are | |
416 | interested in. |
|
416 | interested in. | |
417 |
|
417 | |||
418 | The API documentation for the :mod:`IPython.core.magic` module contains the full |
|
418 | The API documentation for the :mod:`IPython.core.magic` module contains the full | |
419 | docstrings of all currently available magic commands. |
|
419 | docstrings of all currently available magic commands. | |
420 |
|
420 | |||
421 |
|
421 | |||
422 | Access to the standard Python help |
|
422 | Access to the standard Python help | |
423 | ---------------------------------- |
|
423 | ---------------------------------- | |
424 |
|
424 | |||
425 | Simply type ``help()`` to access Python's standard help system. You can |
|
425 | Simply type ``help()`` to access Python's standard help system. You can | |
426 | also type ``help(object)`` for information about a given object, or |
|
426 | also type ``help(object)`` for information about a given object, or | |
427 | ``help('keyword')`` for information on a keyword. You may need to configure your |
|
427 | ``help('keyword')`` for information on a keyword. You may need to configure your | |
428 | PYTHONDOCS environment variable for this feature to work correctly. |
|
428 | PYTHONDOCS environment variable for this feature to work correctly. | |
429 |
|
429 | |||
430 | .. _dynamic_object_info: |
|
430 | .. _dynamic_object_info: | |
431 |
|
431 | |||
432 | Dynamic object information |
|
432 | Dynamic object information | |
433 | -------------------------- |
|
433 | -------------------------- | |
434 |
|
434 | |||
435 | Typing ``?word`` or ``word?`` prints detailed information about an object. If |
|
435 | Typing ``?word`` or ``word?`` prints detailed information about an object. If | |
436 | certain strings in the object are too long (e.g. function signatures) they get |
|
436 | certain strings in the object are too long (e.g. function signatures) they get | |
437 | snipped in the center for brevity. This system gives access variable types and |
|
437 | snipped in the center for brevity. This system gives access variable types and | |
438 | values, docstrings, function prototypes and other useful information. |
|
438 | values, docstrings, function prototypes and other useful information. | |
439 |
|
439 | |||
440 | If the information will not fit in the terminal, it is displayed in a pager |
|
440 | If the information will not fit in the terminal, it is displayed in a pager | |
441 | (``less`` if available, otherwise a basic internal pager). |
|
441 | (``less`` if available, otherwise a basic internal pager). | |
442 |
|
442 | |||
443 | Typing ``??word`` or ``word??`` gives access to the full information, including |
|
443 | Typing ``??word`` or ``word??`` gives access to the full information, including | |
444 | the source code where possible. Long strings are not snipped. |
|
444 | the source code where possible. Long strings are not snipped. | |
445 |
|
445 | |||
446 | The following magic functions are particularly useful for gathering |
|
446 | The following magic functions are particularly useful for gathering | |
447 | information about your working environment. You can get more details by |
|
447 | information about your working environment. You can get more details by | |
448 | typing ``%magic`` or querying them individually (``%function_name?``); |
|
448 | typing ``%magic`` or querying them individually (``%function_name?``); | |
449 | this is just a summary: |
|
449 | this is just a summary: | |
450 |
|
450 | |||
451 | * **%pdoc <object>**: Print (or run through a pager if too long) the |
|
451 | * **%pdoc <object>**: Print (or run through a pager if too long) the | |
452 | docstring for an object. If the given object is a class, it will |
|
452 | docstring for an object. If the given object is a class, it will | |
453 | print both the class and the constructor docstrings. |
|
453 | print both the class and the constructor docstrings. | |
454 | * **%pdef <object>**: Print the definition header for any callable |
|
454 | * **%pdef <object>**: Print the definition header for any callable | |
455 | object. If the object is a class, print the constructor information. |
|
455 | object. If the object is a class, print the constructor information. | |
456 | * **%psource <object>**: Print (or run through a pager if too long) |
|
456 | * **%psource <object>**: Print (or run through a pager if too long) | |
457 | the source code for an object. |
|
457 | the source code for an object. | |
458 | * **%pfile <object>**: Show the entire source file where an object was |
|
458 | * **%pfile <object>**: Show the entire source file where an object was | |
459 | defined via a pager, opening it at the line where the object |
|
459 | defined via a pager, opening it at the line where the object | |
460 | definition begins. |
|
460 | definition begins. | |
461 | * **%who/%whos**: These functions give information about identifiers |
|
461 | * **%who/%whos**: These functions give information about identifiers | |
462 | you have defined interactively (not things you loaded or defined |
|
462 | you have defined interactively (not things you loaded or defined | |
463 | in your configuration files). %who just prints a list of |
|
463 | in your configuration files). %who just prints a list of | |
464 | identifiers and %whos prints a table with some basic details about |
|
464 | identifiers and %whos prints a table with some basic details about | |
465 | each identifier. |
|
465 | each identifier. | |
466 |
|
466 | |||
467 | Note that the dynamic object information functions (?/??, ``%pdoc``, |
|
467 | Note that the dynamic object information functions (?/??, ``%pdoc``, | |
468 | ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as |
|
468 | ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as | |
469 | directly on variables. For example, after doing ``import os``, you can use |
|
469 | directly on variables. For example, after doing ``import os``, you can use | |
470 | ``os.path.abspath??``. |
|
470 | ``os.path.abspath??``. | |
471 |
|
471 | |||
472 | .. _readline: |
|
472 | .. _readline: | |
473 |
|
473 | |||
474 | Readline-based features |
|
474 | Readline-based features | |
475 | ----------------------- |
|
475 | ----------------------- | |
476 |
|
476 | |||
477 | These features require the GNU readline library, so they won't work if your |
|
477 | These features require the GNU readline library, so they won't work if your | |
478 | Python installation lacks readline support. We will first describe the default |
|
478 | Python installation lacks readline support. We will first describe the default | |
479 | behavior IPython uses, and then how to change it to suit your preferences. |
|
479 | behavior IPython uses, and then how to change it to suit your preferences. | |
480 |
|
480 | |||
481 |
|
481 | |||
482 | Command line completion |
|
482 | Command line completion | |
483 | +++++++++++++++++++++++ |
|
483 | +++++++++++++++++++++++ | |
484 |
|
484 | |||
485 | At any time, hitting TAB will complete any available python commands or |
|
485 | At any time, hitting TAB will complete any available python commands or | |
486 | variable names, and show you a list of the possible completions if |
|
486 | variable names, and show you a list of the possible completions if | |
487 | there's no unambiguous one. It will also complete filenames in the |
|
487 | there's no unambiguous one. It will also complete filenames in the | |
488 | current directory if no python names match what you've typed so far. |
|
488 | current directory if no python names match what you've typed so far. | |
489 |
|
489 | |||
490 |
|
490 | |||
491 | Search command history |
|
491 | Search command history | |
492 | ++++++++++++++++++++++ |
|
492 | ++++++++++++++++++++++ | |
493 |
|
493 | |||
494 | IPython provides two ways for searching through previous input and thus |
|
494 | IPython provides two ways for searching through previous input and thus | |
495 | reduce the need for repetitive typing: |
|
495 | reduce the need for repetitive typing: | |
496 |
|
496 | |||
497 | 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n |
|
497 | 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n | |
498 | (next,down) to search through only the history items that match |
|
498 | (next,down) to search through only the history items that match | |
499 | what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank |
|
499 | what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank | |
500 | prompt, they just behave like normal arrow keys. |
|
500 | prompt, they just behave like normal arrow keys. | |
501 | 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system |
|
501 | 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system | |
502 | searches your history for lines that contain what you've typed so |
|
502 | searches your history for lines that contain what you've typed so | |
503 | far, completing as much as it can. |
|
503 | far, completing as much as it can. | |
504 |
|
504 | |||
505 |
|
505 | |||
506 | Persistent command history across sessions |
|
506 | Persistent command history across sessions | |
507 | ++++++++++++++++++++++++++++++++++++++++++ |
|
507 | ++++++++++++++++++++++++++++++++++++++++++ | |
508 |
|
508 | |||
509 | IPython will save your input history when it leaves and reload it next |
|
509 | IPython will save your input history when it leaves and reload it next | |
510 | time you restart it. By default, the history file is named |
|
510 | time you restart it. By default, the history file is named | |
511 | $IPYTHON_DIR/profile_<name>/history.sqlite. This allows you to keep |
|
511 | $IPYTHON_DIR/profile_<name>/history.sqlite. This allows you to keep | |
512 | separate histories related to various tasks: commands related to |
|
512 | separate histories related to various tasks: commands related to | |
513 | numerical work will not be clobbered by a system shell history, for |
|
513 | numerical work will not be clobbered by a system shell history, for | |
514 | example. |
|
514 | example. | |
515 |
|
515 | |||
516 |
|
516 | |||
517 | Autoindent |
|
517 | Autoindent | |
518 | ++++++++++ |
|
518 | ++++++++++ | |
519 |
|
519 | |||
520 | IPython can recognize lines ending in ':' and indent the next line, |
|
520 | IPython can recognize lines ending in ':' and indent the next line, | |
521 | while also un-indenting automatically after 'raise' or 'return'. |
|
521 | while also un-indenting automatically after 'raise' or 'return'. | |
522 |
|
522 | |||
523 | This feature uses the readline library, so it will honor your |
|
523 | This feature uses the readline library, so it will honor your | |
524 | :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points |
|
524 | :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points | |
525 | to). Adding the following lines to your :file:`.inputrc` file can make |
|
525 | to). Adding the following lines to your :file:`.inputrc` file can make | |
526 | indenting/unindenting more convenient (M-i indents, M-u unindents):: |
|
526 | indenting/unindenting more convenient (M-i indents, M-u unindents):: | |
527 |
|
527 | |||
528 | $if Python |
|
528 | $if Python | |
529 | "\M-i": " " |
|
529 | "\M-i": " " | |
530 | "\M-u": "\d\d\d\d" |
|
530 | "\M-u": "\d\d\d\d" | |
531 | $endif |
|
531 | $endif | |
532 |
|
532 | |||
533 | Note that there are 4 spaces between the quote marks after "M-i" above. |
|
533 | Note that there are 4 spaces between the quote marks after "M-i" above. | |
534 |
|
534 | |||
535 | .. warning:: |
|
535 | .. warning:: | |
536 |
|
536 | |||
537 | Setting the above indents will cause problems with unicode text entry in |
|
537 | Setting the above indents will cause problems with unicode text entry in | |
538 | the terminal. |
|
538 | the terminal. | |
539 |
|
539 | |||
540 | .. warning:: |
|
540 | .. warning:: | |
541 |
|
541 | |||
542 | Autoindent is ON by default, but it can cause problems with the pasting of |
|
542 | Autoindent is ON by default, but it can cause problems with the pasting of | |
543 | multi-line indented code (the pasted code gets re-indented on each line). A |
|
543 | multi-line indented code (the pasted code gets re-indented on each line). A | |
544 | magic function %autoindent allows you to toggle it on/off at runtime. You |
|
544 | magic function %autoindent allows you to toggle it on/off at runtime. You | |
545 | can also disable it permanently on in your :file:`ipython_config.py` file |
|
545 | can also disable it permanently on in your :file:`ipython_config.py` file | |
546 | (set TerminalInteractiveShell.autoindent=False). |
|
546 | (set TerminalInteractiveShell.autoindent=False). | |
547 |
|
547 | |||
548 | If you want to paste multiple lines in the terminal, it is recommended that |
|
548 | If you want to paste multiple lines in the terminal, it is recommended that | |
549 | you use ``%paste``. |
|
549 | you use ``%paste``. | |
550 |
|
550 | |||
551 |
|
551 | |||
552 | Customizing readline behavior |
|
552 | Customizing readline behavior | |
553 | +++++++++++++++++++++++++++++ |
|
553 | +++++++++++++++++++++++++++++ | |
554 |
|
554 | |||
555 | All these features are based on the GNU readline library, which has an |
|
555 | All these features are based on the GNU readline library, which has an | |
556 | extremely customizable interface. Normally, readline is configured via a |
|
556 | extremely customizable interface. Normally, readline is configured via a | |
557 | file which defines the behavior of the library; the details of the |
|
557 | file which defines the behavior of the library; the details of the | |
558 | syntax for this can be found in the readline documentation available |
|
558 | syntax for this can be found in the readline documentation available | |
559 | with your system or on the Internet. IPython doesn't read this file (if |
|
559 | with your system or on the Internet. IPython doesn't read this file (if | |
560 | it exists) directly, but it does support passing to readline valid |
|
560 | it exists) directly, but it does support passing to readline valid | |
561 | options via a simple interface. In brief, you can customize readline by |
|
561 | options via a simple interface. In brief, you can customize readline by | |
562 | setting the following options in your configuration file (note |
|
562 | setting the following options in your configuration file (note | |
563 | that these options can not be specified at the command line): |
|
563 | that these options can not be specified at the command line): | |
564 |
|
564 | |||
565 | * **readline_parse_and_bind**: this holds a list of strings to be executed |
|
565 | * **readline_parse_and_bind**: this holds a list of strings to be executed | |
566 | via a readline.parse_and_bind() command. The syntax for valid commands |
|
566 | via a readline.parse_and_bind() command. The syntax for valid commands | |
567 | of this kind can be found by reading the documentation for the GNU |
|
567 | of this kind can be found by reading the documentation for the GNU | |
568 | readline library, as these commands are of the kind which readline |
|
568 | readline library, as these commands are of the kind which readline | |
569 | accepts in its configuration file. |
|
569 | accepts in its configuration file. | |
570 | * **readline_remove_delims**: a string of characters to be removed |
|
570 | * **readline_remove_delims**: a string of characters to be removed | |
571 | from the default word-delimiters list used by readline, so that |
|
571 | from the default word-delimiters list used by readline, so that | |
572 | completions may be performed on strings which contain them. Do not |
|
572 | completions may be performed on strings which contain them. Do not | |
573 | change the default value unless you know what you're doing. |
|
573 | change the default value unless you know what you're doing. | |
574 |
|
574 | |||
575 | You will find the default values in your configuration file. |
|
575 | You will find the default values in your configuration file. | |
576 |
|
576 | |||
577 |
|
577 | |||
578 | Session logging and restoring |
|
578 | Session logging and restoring | |
579 | ----------------------------- |
|
579 | ----------------------------- | |
580 |
|
580 | |||
581 | You can log all input from a session either by starting IPython with the |
|
581 | You can log all input from a session either by starting IPython with the | |
582 | command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`) |
|
582 | command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`) | |
583 | or by activating the logging at any moment with the magic function %logstart. |
|
583 | or by activating the logging at any moment with the magic function %logstart. | |
584 |
|
584 | |||
585 | Log files can later be reloaded by running them as scripts and IPython |
|
585 | Log files can later be reloaded by running them as scripts and IPython | |
586 | will attempt to 'replay' the log by executing all the lines in it, thus |
|
586 | will attempt to 'replay' the log by executing all the lines in it, thus | |
587 | restoring the state of a previous session. This feature is not quite |
|
587 | restoring the state of a previous session. This feature is not quite | |
588 | perfect, but can still be useful in many cases. |
|
588 | perfect, but can still be useful in many cases. | |
589 |
|
589 | |||
590 | The log files can also be used as a way to have a permanent record of |
|
590 | The log files can also be used as a way to have a permanent record of | |
591 | any code you wrote while experimenting. Log files are regular text files |
|
591 | any code you wrote while experimenting. Log files are regular text files | |
592 | which you can later open in your favorite text editor to extract code or |
|
592 | which you can later open in your favorite text editor to extract code or | |
593 | to 'clean them up' before using them to replay a session. |
|
593 | to 'clean them up' before using them to replay a session. | |
594 |
|
594 | |||
595 | The `%logstart` function for activating logging in mid-session is used as |
|
595 | The `%logstart` function for activating logging in mid-session is used as | |
596 | follows:: |
|
596 | follows:: | |
597 |
|
597 | |||
598 | %logstart [log_name [log_mode]] |
|
598 | %logstart [log_name [log_mode]] | |
599 |
|
599 | |||
600 | If no name is given, it defaults to a file named 'ipython_log.py' in your |
|
600 | If no name is given, it defaults to a file named 'ipython_log.py' in your | |
601 | current working directory, in 'rotate' mode (see below). |
|
601 | current working directory, in 'rotate' mode (see below). | |
602 |
|
602 | |||
603 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your |
|
603 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your | |
604 | history up to that point and then continues logging. |
|
604 | history up to that point and then continues logging. | |
605 |
|
605 | |||
606 | %logstart takes a second optional parameter: logging mode. This can be |
|
606 | %logstart takes a second optional parameter: logging mode. This can be | |
607 | one of (note that the modes are given unquoted): |
|
607 | one of (note that the modes are given unquoted): | |
608 |
|
608 | |||
609 | * [over:] overwrite existing log_name. |
|
609 | * [over:] overwrite existing log_name. | |
610 | * [backup:] rename (if exists) to log_name~ and start log_name. |
|
610 | * [backup:] rename (if exists) to log_name~ and start log_name. | |
611 | * [append:] well, that says it. |
|
611 | * [append:] well, that says it. | |
612 | * [rotate:] create rotating logs log_name.1~, log_name.2~, etc. |
|
612 | * [rotate:] create rotating logs log_name.1~, log_name.2~, etc. | |
613 |
|
613 | |||
614 | The %logoff and %logon functions allow you to temporarily stop and |
|
614 | The %logoff and %logon functions allow you to temporarily stop and | |
615 | resume logging to a file which had previously been started with |
|
615 | resume logging to a file which had previously been started with | |
616 | %logstart. They will fail (with an explanation) if you try to use them |
|
616 | %logstart. They will fail (with an explanation) if you try to use them | |
617 | before logging has been started. |
|
617 | before logging has been started. | |
618 |
|
618 | |||
619 | .. _system_shell_access: |
|
619 | .. _system_shell_access: | |
620 |
|
620 | |||
621 | System shell access |
|
621 | System shell access | |
622 | ------------------- |
|
622 | ------------------- | |
623 |
|
623 | |||
624 | Any input line beginning with a ! character is passed verbatim (minus |
|
624 | Any input line beginning with a ! character is passed verbatim (minus | |
625 | the !, of course) to the underlying operating system. For example, |
|
625 | the !, of course) to the underlying operating system. For example, | |
626 | typing ``!ls`` will run 'ls' in the current directory. |
|
626 | typing ``!ls`` will run 'ls' in the current directory. | |
627 |
|
627 | |||
628 | Manual capture of command output |
|
628 | Manual capture of command output | |
629 | -------------------------------- |
|
629 | -------------------------------- | |
630 |
|
630 | |||
631 | You can assign the result of a system command to a Python variable with the |
|
631 | You can assign the result of a system command to a Python variable with the | |
632 | syntax ``myfiles = !ls``. This gets machine readable output from stdout |
|
632 | syntax ``myfiles = !ls``. This gets machine readable output from stdout | |
633 | (e.g. without colours), and splits on newlines. To explicitly get this sort of |
|
633 | (e.g. without colours), and splits on newlines. To explicitly get this sort of | |
634 | output without assigning to a variable, use two exclamation marks (``!!ls``) or |
|
634 | output without assigning to a variable, use two exclamation marks (``!!ls``) or | |
635 | the ``%sx`` magic command. |
|
635 | the ``%sx`` magic command. | |
636 |
|
636 | |||
637 | The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s`` |
|
637 | The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s`` | |
638 | returns a string delimited by newlines or spaces, respectively. ``myfiles.p`` |
|
638 | returns a string delimited by newlines or spaces, respectively. ``myfiles.p`` | |
639 | produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items. |
|
639 | produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items. | |
|
640 | See :ref:`string_lists` for details. | |||
640 |
|
641 | |||
641 | IPython also allows you to expand the value of python variables when |
|
642 | IPython also allows you to expand the value of python variables when | |
642 | making system calls. Wrap variables or expressions in {braces}:: |
|
643 | making system calls. Wrap variables or expressions in {braces}:: | |
643 |
|
644 | |||
644 | In [1]: pyvar = 'Hello world' |
|
645 | In [1]: pyvar = 'Hello world' | |
645 | In [2]: !echo "A python variable: {pyvar}" |
|
646 | In [2]: !echo "A python variable: {pyvar}" | |
646 | A python variable: Hello world |
|
647 | A python variable: Hello world | |
647 | In [3]: import math |
|
648 | In [3]: import math | |
648 | In [4]: x = 8 |
|
649 | In [4]: x = 8 | |
649 | In [5]: !echo {math.factorial(x)} |
|
650 | In [5]: !echo {math.factorial(x)} | |
650 | 40320 |
|
651 | 40320 | |
651 |
|
652 | |||
652 | For simple cases, you can alternatively prepend $ to a variable name:: |
|
653 | For simple cases, you can alternatively prepend $ to a variable name:: | |
653 |
|
654 | |||
654 | In [6]: !echo $sys.argv |
|
655 | In [6]: !echo $sys.argv | |
655 | [/home/fperez/usr/bin/ipython] |
|
656 | [/home/fperez/usr/bin/ipython] | |
656 | In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $ |
|
657 | In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $ | |
657 | A system variable: /home/fperez |
|
658 | A system variable: /home/fperez | |
658 |
|
659 | |||
659 | System command aliases |
|
660 | System command aliases | |
660 | ---------------------- |
|
661 | ---------------------- | |
661 |
|
662 | |||
662 | The %alias magic function allows you to define magic functions which are in fact |
|
663 | The %alias magic function allows you to define magic functions which are in fact | |
663 | system shell commands. These aliases can have parameters. |
|
664 | system shell commands. These aliases can have parameters. | |
664 |
|
665 | |||
665 | ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd' |
|
666 | ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd' | |
666 |
|
667 | |||
667 | Then, typing ``alias_name params`` will execute the system command 'cmd |
|
668 | Then, typing ``alias_name params`` will execute the system command 'cmd | |
668 | params' (from your underlying operating system). |
|
669 | params' (from your underlying operating system). | |
669 |
|
670 | |||
670 | You can also define aliases with parameters using %s specifiers (one per |
|
671 | You can also define aliases with parameters using %s specifiers (one per | |
671 | parameter). The following example defines the parts function as an |
|
672 | parameter). The following example defines the parts function as an | |
672 | alias to the command 'echo first %s second %s' where each %s will be |
|
673 | alias to the command 'echo first %s second %s' where each %s will be | |
673 | replaced by a positional parameter to the call to %parts:: |
|
674 | replaced by a positional parameter to the call to %parts:: | |
674 |
|
675 | |||
675 | In [1]: %alias parts echo first %s second %s |
|
676 | In [1]: %alias parts echo first %s second %s | |
676 | In [2]: parts A B |
|
677 | In [2]: parts A B | |
677 | first A second B |
|
678 | first A second B | |
678 | In [3]: parts A |
|
679 | In [3]: parts A | |
679 | ERROR: Alias <parts> requires 2 arguments, 1 given. |
|
680 | ERROR: Alias <parts> requires 2 arguments, 1 given. | |
680 |
|
681 | |||
681 | If called with no parameters, %alias prints the table of currently |
|
682 | If called with no parameters, %alias prints the table of currently | |
682 | defined aliases. |
|
683 | defined aliases. | |
683 |
|
684 | |||
684 | The %rehashx magic allows you to load your entire $PATH as |
|
685 | The %rehashx magic allows you to load your entire $PATH as | |
685 | ipython aliases. See its docstring for further details. |
|
686 | ipython aliases. See its docstring for further details. | |
686 |
|
687 | |||
687 |
|
688 | |||
688 | .. _dreload: |
|
689 | .. _dreload: | |
689 |
|
690 | |||
690 | Recursive reload |
|
691 | Recursive reload | |
691 | ---------------- |
|
692 | ---------------- | |
692 |
|
693 | |||
693 | The :mod:`IPython.lib.deepreload` module allows you to recursively reload a |
|
694 | The :mod:`IPython.lib.deepreload` module allows you to recursively reload a | |
694 | module: changes made to any of its dependencies will be reloaded without |
|
695 | module: changes made to any of its dependencies will be reloaded without | |
695 | having to exit. To start using it, do:: |
|
696 | having to exit. To start using it, do:: | |
696 |
|
697 | |||
697 | from IPython.lib.deepreload import reload as dreload |
|
698 | from IPython.lib.deepreload import reload as dreload | |
698 |
|
699 | |||
699 |
|
700 | |||
700 | Verbose and colored exception traceback printouts |
|
701 | Verbose and colored exception traceback printouts | |
701 | ------------------------------------------------- |
|
702 | ------------------------------------------------- | |
702 |
|
703 | |||
703 | IPython provides the option to see very detailed exception tracebacks, |
|
704 | IPython provides the option to see very detailed exception tracebacks, | |
704 | which can be especially useful when debugging large programs. You can |
|
705 | which can be especially useful when debugging large programs. You can | |
705 | run any Python file with the %run function to benefit from these |
|
706 | run any Python file with the %run function to benefit from these | |
706 | detailed tracebacks. Furthermore, both normal and verbose tracebacks can |
|
707 | detailed tracebacks. Furthermore, both normal and verbose tracebacks can | |
707 | be colored (if your terminal supports it) which makes them much easier |
|
708 | be colored (if your terminal supports it) which makes them much easier | |
708 | to parse visually. |
|
709 | to parse visually. | |
709 |
|
710 | |||
710 | See the magic xmode and colors functions for details (just type %magic). |
|
711 | See the magic xmode and colors functions for details (just type %magic). | |
711 |
|
712 | |||
712 | These features are basically a terminal version of Ka-Ping Yee's cgitb |
|
713 | These features are basically a terminal version of Ka-Ping Yee's cgitb | |
713 | module, now part of the standard Python library. |
|
714 | module, now part of the standard Python library. | |
714 |
|
715 | |||
715 |
|
716 | |||
716 | .. _input_caching: |
|
717 | .. _input_caching: | |
717 |
|
718 | |||
718 | Input caching system |
|
719 | Input caching system | |
719 | -------------------- |
|
720 | -------------------- | |
720 |
|
721 | |||
721 | IPython offers numbered prompts (In/Out) with input and output caching |
|
722 | IPython offers numbered prompts (In/Out) with input and output caching | |
722 | (also referred to as 'input history'). All input is saved and can be |
|
723 | (also referred to as 'input history'). All input is saved and can be | |
723 | retrieved as variables (besides the usual arrow key recall), in |
|
724 | retrieved as variables (besides the usual arrow key recall), in | |
724 | addition to the %rep magic command that brings a history entry |
|
725 | addition to the %rep magic command that brings a history entry | |
725 | up for editing on the next command line. |
|
726 | up for editing on the next command line. | |
726 |
|
727 | |||
727 | The following GLOBAL variables always exist (so don't overwrite them!): |
|
728 | The following GLOBAL variables always exist (so don't overwrite them!): | |
728 |
|
729 | |||
729 | * _i, _ii, _iii: store previous, next previous and next-next previous inputs. |
|
730 | * _i, _ii, _iii: store previous, next previous and next-next previous inputs. | |
730 | * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you |
|
731 | * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you | |
731 | overwrite In with a variable of your own, you can remake the assignment to the |
|
732 | overwrite In with a variable of your own, you can remake the assignment to the | |
732 | internal list with a simple ``In=_ih``. |
|
733 | internal list with a simple ``In=_ih``. | |
733 |
|
734 | |||
734 | Additionally, global variables named _i<n> are dynamically created (<n> |
|
735 | Additionally, global variables named _i<n> are dynamically created (<n> | |
735 | being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``. |
|
736 | being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``. | |
736 |
|
737 | |||
737 | For example, what you typed at prompt 14 is available as _i14, _ih[14] |
|
738 | For example, what you typed at prompt 14 is available as _i14, _ih[14] | |
738 | and In[14]. |
|
739 | and In[14]. | |
739 |
|
740 | |||
740 | This allows you to easily cut and paste multi line interactive prompts |
|
741 | This allows you to easily cut and paste multi line interactive prompts | |
741 | by printing them out: they print like a clean string, without prompt |
|
742 | by printing them out: they print like a clean string, without prompt | |
742 | characters. You can also manipulate them like regular variables (they |
|
743 | characters. You can also manipulate them like regular variables (they | |
743 | are strings), modify or exec them (typing ``exec _i9`` will re-execute the |
|
744 | are strings), modify or exec them (typing ``exec _i9`` will re-execute the | |
744 | contents of input prompt 9. |
|
745 | contents of input prompt 9. | |
745 |
|
746 | |||
746 | You can also re-execute multiple lines of input easily by using the |
|
747 | You can also re-execute multiple lines of input easily by using the | |
747 | magic %rerun or %macro functions. The macro system also allows you to re-execute |
|
748 | magic %rerun or %macro functions. The macro system also allows you to re-execute | |
748 | previous lines which include magic function calls (which require special |
|
749 | previous lines which include magic function calls (which require special | |
749 | processing). Type %macro? for more details on the macro system. |
|
750 | processing). Type %macro? for more details on the macro system. | |
750 |
|
751 | |||
751 | A history function %hist allows you to see any part of your input |
|
752 | A history function %hist allows you to see any part of your input | |
752 | history by printing a range of the _i variables. |
|
753 | history by printing a range of the _i variables. | |
753 |
|
754 | |||
754 | You can also search ('grep') through your history by typing |
|
755 | You can also search ('grep') through your history by typing | |
755 | ``%hist -g somestring``. This is handy for searching for URLs, IP addresses, |
|
756 | ``%hist -g somestring``. This is handy for searching for URLs, IP addresses, | |
756 | etc. You can bring history entries listed by '%hist -g' up for editing |
|
757 | etc. You can bring history entries listed by '%hist -g' up for editing | |
757 | with the %recall command, or run them immediately with %rerun. |
|
758 | with the %recall command, or run them immediately with %rerun. | |
758 |
|
759 | |||
759 | .. _output_caching: |
|
760 | .. _output_caching: | |
760 |
|
761 | |||
761 | Output caching system |
|
762 | Output caching system | |
762 | --------------------- |
|
763 | --------------------- | |
763 |
|
764 | |||
764 | For output that is returned from actions, a system similar to the input |
|
765 | For output that is returned from actions, a system similar to the input | |
765 | cache exists but using _ instead of _i. Only actions that produce a |
|
766 | cache exists but using _ instead of _i. Only actions that produce a | |
766 | result (NOT assignments, for example) are cached. If you are familiar |
|
767 | result (NOT assignments, for example) are cached. If you are familiar | |
767 | with Mathematica, IPython's _ variables behave exactly like |
|
768 | with Mathematica, IPython's _ variables behave exactly like | |
768 | Mathematica's % variables. |
|
769 | Mathematica's % variables. | |
769 |
|
770 | |||
770 | The following GLOBAL variables always exist (so don't overwrite them!): |
|
771 | The following GLOBAL variables always exist (so don't overwrite them!): | |
771 |
|
772 | |||
772 | * [_] (a single underscore) : stores previous output, like Python's |
|
773 | * [_] (a single underscore) : stores previous output, like Python's | |
773 | default interpreter. |
|
774 | default interpreter. | |
774 | * [__] (two underscores): next previous. |
|
775 | * [__] (two underscores): next previous. | |
775 | * [___] (three underscores): next-next previous. |
|
776 | * [___] (three underscores): next-next previous. | |
776 |
|
777 | |||
777 | Additionally, global variables named _<n> are dynamically created (<n> |
|
778 | Additionally, global variables named _<n> are dynamically created (<n> | |
778 | being the prompt counter), such that the result of output <n> is always |
|
779 | being the prompt counter), such that the result of output <n> is always | |
779 | available as _<n> (don't use the angle brackets, just the number, e.g. |
|
780 | available as _<n> (don't use the angle brackets, just the number, e.g. | |
780 | _21). |
|
781 | _21). | |
781 |
|
782 | |||
782 | These variables are also stored in a global dictionary (not a |
|
783 | These variables are also stored in a global dictionary (not a | |
783 | list, since it only has entries for lines which returned a result) |
|
784 | list, since it only has entries for lines which returned a result) | |
784 | available under the names _oh and Out (similar to _ih and In). So the |
|
785 | available under the names _oh and Out (similar to _ih and In). So the | |
785 | output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you |
|
786 | output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you | |
786 | accidentally overwrite the Out variable you can recover it by typing |
|
787 | accidentally overwrite the Out variable you can recover it by typing | |
787 | 'Out=_oh' at the prompt. |
|
788 | 'Out=_oh' at the prompt. | |
788 |
|
789 | |||
789 | This system obviously can potentially put heavy memory demands on your |
|
790 | This system obviously can potentially put heavy memory demands on your | |
790 | system, since it prevents Python's garbage collector from removing any |
|
791 | system, since it prevents Python's garbage collector from removing any | |
791 | previously computed results. You can control how many results are kept |
|
792 | previously computed results. You can control how many results are kept | |
792 | in memory with the option (at the command line or in your configuration |
|
793 | in memory with the option (at the command line or in your configuration | |
793 | file) cache_size. If you set it to 0, the whole system is completely |
|
794 | file) cache_size. If you set it to 0, the whole system is completely | |
794 | disabled and the prompts revert to the classic '>>>' of normal Python. |
|
795 | disabled and the prompts revert to the classic '>>>' of normal Python. | |
795 |
|
796 | |||
796 |
|
797 | |||
797 | Directory history |
|
798 | Directory history | |
798 | ----------------- |
|
799 | ----------------- | |
799 |
|
800 | |||
800 | Your history of visited directories is kept in the global list _dh, and |
|
801 | Your history of visited directories is kept in the global list _dh, and | |
801 | the magic %cd command can be used to go to any entry in that list. The |
|
802 | the magic %cd command can be used to go to any entry in that list. The | |
802 | %dhist command allows you to view this history. Do ``cd -<TAB>`` to |
|
803 | %dhist command allows you to view this history. Do ``cd -<TAB>`` to | |
803 | conveniently view the directory history. |
|
804 | conveniently view the directory history. | |
804 |
|
805 | |||
805 |
|
806 | |||
806 | Automatic parentheses and quotes |
|
807 | Automatic parentheses and quotes | |
807 | -------------------------------- |
|
808 | -------------------------------- | |
808 |
|
809 | |||
809 | These features were adapted from Nathan Gray's LazyPython. They are |
|
810 | These features were adapted from Nathan Gray's LazyPython. They are | |
810 | meant to allow less typing for common situations. |
|
811 | meant to allow less typing for common situations. | |
811 |
|
812 | |||
812 |
|
813 | |||
813 | Automatic parentheses |
|
814 | Automatic parentheses | |
814 | +++++++++++++++++++++ |
|
815 | +++++++++++++++++++++ | |
815 |
|
816 | |||
816 | Callable objects (i.e. functions, methods, etc) can be invoked like this |
|
817 | Callable objects (i.e. functions, methods, etc) can be invoked like this | |
817 | (notice the commas between the arguments):: |
|
818 | (notice the commas between the arguments):: | |
818 |
|
819 | |||
819 | In [1]: callable_ob arg1, arg2, arg3 |
|
820 | In [1]: callable_ob arg1, arg2, arg3 | |
820 | ------> callable_ob(arg1, arg2, arg3) |
|
821 | ------> callable_ob(arg1, arg2, arg3) | |
821 |
|
822 | |||
822 | You can force automatic parentheses by using '/' as the first character |
|
823 | You can force automatic parentheses by using '/' as the first character | |
823 | of a line. For example:: |
|
824 | of a line. For example:: | |
824 |
|
825 | |||
825 | In [2]: /globals # becomes 'globals()' |
|
826 | In [2]: /globals # becomes 'globals()' | |
826 |
|
827 | |||
827 | Note that the '/' MUST be the first character on the line! This won't work:: |
|
828 | Note that the '/' MUST be the first character on the line! This won't work:: | |
828 |
|
829 | |||
829 | In [3]: print /globals # syntax error |
|
830 | In [3]: print /globals # syntax error | |
830 |
|
831 | |||
831 | In most cases the automatic algorithm should work, so you should rarely |
|
832 | In most cases the automatic algorithm should work, so you should rarely | |
832 | need to explicitly invoke /. One notable exception is if you are trying |
|
833 | need to explicitly invoke /. One notable exception is if you are trying | |
833 | to call a function with a list of tuples as arguments (the parenthesis |
|
834 | to call a function with a list of tuples as arguments (the parenthesis | |
834 | will confuse IPython):: |
|
835 | will confuse IPython):: | |
835 |
|
836 | |||
836 | In [4]: zip (1,2,3),(4,5,6) # won't work |
|
837 | In [4]: zip (1,2,3),(4,5,6) # won't work | |
837 |
|
838 | |||
838 | but this will work:: |
|
839 | but this will work:: | |
839 |
|
840 | |||
840 | In [5]: /zip (1,2,3),(4,5,6) |
|
841 | In [5]: /zip (1,2,3),(4,5,6) | |
841 | ------> zip ((1,2,3),(4,5,6)) |
|
842 | ------> zip ((1,2,3),(4,5,6)) | |
842 | Out[5]: [(1, 4), (2, 5), (3, 6)] |
|
843 | Out[5]: [(1, 4), (2, 5), (3, 6)] | |
843 |
|
844 | |||
844 | IPython tells you that it has altered your command line by displaying |
|
845 | IPython tells you that it has altered your command line by displaying | |
845 | the new command line preceded by ->. e.g.:: |
|
846 | the new command line preceded by ->. e.g.:: | |
846 |
|
847 | |||
847 | In [6]: callable list |
|
848 | In [6]: callable list | |
848 | ------> callable(list) |
|
849 | ------> callable(list) | |
849 |
|
850 | |||
850 |
|
851 | |||
851 | Automatic quoting |
|
852 | Automatic quoting | |
852 | +++++++++++++++++ |
|
853 | +++++++++++++++++ | |
853 |
|
854 | |||
854 | You can force automatic quoting of a function's arguments by using ',' |
|
855 | You can force automatic quoting of a function's arguments by using ',' | |
855 | or ';' as the first character of a line. For example:: |
|
856 | or ';' as the first character of a line. For example:: | |
856 |
|
857 | |||
857 | In [1]: ,my_function /home/me # becomes my_function("/home/me") |
|
858 | In [1]: ,my_function /home/me # becomes my_function("/home/me") | |
858 |
|
859 | |||
859 | If you use ';' the whole argument is quoted as a single string, while ',' splits |
|
860 | If you use ';' the whole argument is quoted as a single string, while ',' splits | |
860 | on whitespace:: |
|
861 | on whitespace:: | |
861 |
|
862 | |||
862 | In [2]: ,my_function a b c # becomes my_function("a","b","c") |
|
863 | In [2]: ,my_function a b c # becomes my_function("a","b","c") | |
863 |
|
864 | |||
864 | In [3]: ;my_function a b c # becomes my_function("a b c") |
|
865 | In [3]: ;my_function a b c # becomes my_function("a b c") | |
865 |
|
866 | |||
866 | Note that the ',' or ';' MUST be the first character on the line! This |
|
867 | Note that the ',' or ';' MUST be the first character on the line! This | |
867 | won't work:: |
|
868 | won't work:: | |
868 |
|
869 | |||
869 | In [4]: x = ,my_function /home/me # syntax error |
|
870 | In [4]: x = ,my_function /home/me # syntax error | |
870 |
|
871 | |||
871 | IPython as your default Python environment |
|
872 | IPython as your default Python environment | |
872 | ========================================== |
|
873 | ========================================== | |
873 |
|
874 | |||
874 | Python honors the environment variable PYTHONSTARTUP and will execute at |
|
875 | Python honors the environment variable PYTHONSTARTUP and will execute at | |
875 | startup the file referenced by this variable. If you put the following code at |
|
876 | startup the file referenced by this variable. If you put the following code at | |
876 | the end of that file, then IPython will be your working environment anytime you |
|
877 | the end of that file, then IPython will be your working environment anytime you | |
877 | start Python:: |
|
878 | start Python:: | |
878 |
|
879 | |||
879 | from IPython.frontend.terminal.ipapp import launch_new_instance |
|
880 | from IPython.frontend.terminal.ipapp import launch_new_instance | |
880 | launch_new_instance() |
|
881 | launch_new_instance() | |
881 | raise SystemExit |
|
882 | raise SystemExit | |
882 |
|
883 | |||
883 | The ``raise SystemExit`` is needed to exit Python when |
|
884 | The ``raise SystemExit`` is needed to exit Python when | |
884 | it finishes, otherwise you'll be back at the normal Python '>>>' |
|
885 | it finishes, otherwise you'll be back at the normal Python '>>>' | |
885 | prompt. |
|
886 | prompt. | |
886 |
|
887 | |||
887 | This is probably useful to developers who manage multiple Python |
|
888 | This is probably useful to developers who manage multiple Python | |
888 | versions and don't want to have correspondingly multiple IPython |
|
889 | versions and don't want to have correspondingly multiple IPython | |
889 | versions. Note that in this mode, there is no way to pass IPython any |
|
890 | versions. Note that in this mode, there is no way to pass IPython any | |
890 | command-line options, as those are trapped first by Python itself. |
|
891 | command-line options, as those are trapped first by Python itself. | |
891 |
|
892 | |||
892 | .. _Embedding: |
|
893 | .. _Embedding: | |
893 |
|
894 | |||
894 | Embedding IPython |
|
895 | Embedding IPython | |
895 | ================= |
|
896 | ================= | |
896 |
|
897 | |||
897 | It is possible to start an IPython instance inside your own Python |
|
898 | It is possible to start an IPython instance inside your own Python | |
898 | programs. This allows you to evaluate dynamically the state of your |
|
899 | programs. This allows you to evaluate dynamically the state of your | |
899 | code, operate with your variables, analyze them, etc. Note however that |
|
900 | code, operate with your variables, analyze them, etc. Note however that | |
900 | any changes you make to values while in the shell do not propagate back |
|
901 | any changes you make to values while in the shell do not propagate back | |
901 | to the running code, so it is safe to modify your values because you |
|
902 | to the running code, so it is safe to modify your values because you | |
902 | won't break your code in bizarre ways by doing so. |
|
903 | won't break your code in bizarre ways by doing so. | |
903 |
|
904 | |||
904 | .. note:: |
|
905 | .. note:: | |
905 |
|
906 | |||
906 | At present, trying to embed IPython from inside IPython causes problems. Run |
|
907 | At present, trying to embed IPython from inside IPython causes problems. Run | |
907 | the code samples below outside IPython. |
|
908 | the code samples below outside IPython. | |
908 |
|
909 | |||
909 | This feature allows you to easily have a fully functional python |
|
910 | This feature allows you to easily have a fully functional python | |
910 | environment for doing object introspection anywhere in your code with a |
|
911 | environment for doing object introspection anywhere in your code with a | |
911 | simple function call. In some cases a simple print statement is enough, |
|
912 | simple function call. In some cases a simple print statement is enough, | |
912 | but if you need to do more detailed analysis of a code fragment this |
|
913 | but if you need to do more detailed analysis of a code fragment this | |
913 | feature can be very valuable. |
|
914 | feature can be very valuable. | |
914 |
|
915 | |||
915 | It can also be useful in scientific computing situations where it is |
|
916 | It can also be useful in scientific computing situations where it is | |
916 | common to need to do some automatic, computationally intensive part and |
|
917 | common to need to do some automatic, computationally intensive part and | |
917 | then stop to look at data, plots, etc. |
|
918 | then stop to look at data, plots, etc. | |
918 | Opening an IPython instance will give you full access to your data and |
|
919 | Opening an IPython instance will give you full access to your data and | |
919 | functions, and you can resume program execution once you are done with |
|
920 | functions, and you can resume program execution once you are done with | |
920 | the interactive part (perhaps to stop again later, as many times as |
|
921 | the interactive part (perhaps to stop again later, as many times as | |
921 | needed). |
|
922 | needed). | |
922 |
|
923 | |||
923 | The following code snippet is the bare minimum you need to include in |
|
924 | The following code snippet is the bare minimum you need to include in | |
924 | your Python programs for this to work (detailed examples follow later):: |
|
925 | your Python programs for this to work (detailed examples follow later):: | |
925 |
|
926 | |||
926 | from IPython import embed |
|
927 | from IPython import embed | |
927 |
|
928 | |||
928 | embed() # this call anywhere in your program will start IPython |
|
929 | embed() # this call anywhere in your program will start IPython | |
929 |
|
930 | |||
930 | You can run embedded instances even in code which is itself being run at |
|
931 | You can run embedded instances even in code which is itself being run at | |
931 | the IPython interactive prompt with '%run <filename>'. Since it's easy |
|
932 | the IPython interactive prompt with '%run <filename>'. Since it's easy | |
932 | to get lost as to where you are (in your top-level IPython or in your |
|
933 | to get lost as to where you are (in your top-level IPython or in your | |
933 | embedded one), it's a good idea in such cases to set the in/out prompts |
|
934 | embedded one), it's a good idea in such cases to set the in/out prompts | |
934 | to something different for the embedded instances. The code examples |
|
935 | to something different for the embedded instances. The code examples | |
935 | below illustrate this. |
|
936 | below illustrate this. | |
936 |
|
937 | |||
937 | You can also have multiple IPython instances in your program and open |
|
938 | You can also have multiple IPython instances in your program and open | |
938 | them separately, for example with different options for data |
|
939 | them separately, for example with different options for data | |
939 | presentation. If you close and open the same instance multiple times, |
|
940 | presentation. If you close and open the same instance multiple times, | |
940 | its prompt counters simply continue from each execution to the next. |
|
941 | its prompt counters simply continue from each execution to the next. | |
941 |
|
942 | |||
942 | Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed` |
|
943 | Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed` | |
943 | module for more details on the use of this system. |
|
944 | module for more details on the use of this system. | |
944 |
|
945 | |||
945 | The following sample file illustrating how to use the embedding |
|
946 | The following sample file illustrating how to use the embedding | |
946 | functionality is provided in the examples directory as example-embed.py. |
|
947 | functionality is provided in the examples directory as example-embed.py. | |
947 | It should be fairly self-explanatory: |
|
948 | It should be fairly self-explanatory: | |
948 |
|
949 | |||
949 | .. literalinclude:: ../../examples/core/example-embed.py |
|
950 | .. literalinclude:: ../../examples/core/example-embed.py | |
950 | :language: python |
|
951 | :language: python | |
951 |
|
952 | |||
952 | Once you understand how the system functions, you can use the following |
|
953 | Once you understand how the system functions, you can use the following | |
953 | code fragments in your programs which are ready for cut and paste: |
|
954 | code fragments in your programs which are ready for cut and paste: | |
954 |
|
955 | |||
955 | .. literalinclude:: ../../examples/core/example-embed-short.py |
|
956 | .. literalinclude:: ../../examples/core/example-embed-short.py | |
956 | :language: python |
|
957 | :language: python | |
957 |
|
958 | |||
958 | Using the Python debugger (pdb) |
|
959 | Using the Python debugger (pdb) | |
959 | =============================== |
|
960 | =============================== | |
960 |
|
961 | |||
961 | Running entire programs via pdb |
|
962 | Running entire programs via pdb | |
962 | ------------------------------- |
|
963 | ------------------------------- | |
963 |
|
964 | |||
964 | pdb, the Python debugger, is a powerful interactive debugger which |
|
965 | pdb, the Python debugger, is a powerful interactive debugger which | |
965 | allows you to step through code, set breakpoints, watch variables, |
|
966 | allows you to step through code, set breakpoints, watch variables, | |
966 | etc. IPython makes it very easy to start any script under the control |
|
967 | etc. IPython makes it very easy to start any script under the control | |
967 | of pdb, regardless of whether you have wrapped it into a 'main()' |
|
968 | of pdb, regardless of whether you have wrapped it into a 'main()' | |
968 | function or not. For this, simply type '%run -d myscript' at an |
|
969 | function or not. For this, simply type '%run -d myscript' at an | |
969 | IPython prompt. See the %run command's documentation (via '%run?' or |
|
970 | IPython prompt. See the %run command's documentation (via '%run?' or | |
970 | in Sec. magic_ for more details, including how to control where pdb |
|
971 | in Sec. magic_ for more details, including how to control where pdb | |
971 | will stop execution first. |
|
972 | will stop execution first. | |
972 |
|
973 | |||
973 | For more information on the use of the pdb debugger, read the included |
|
974 | For more information on the use of the pdb debugger, read the included | |
974 | pdb.doc file (part of the standard Python distribution). On a stock |
|
975 | pdb.doc file (part of the standard Python distribution). On a stock | |
975 | Linux system it is located at /usr/lib/python2.3/pdb.doc, but the |
|
976 | Linux system it is located at /usr/lib/python2.3/pdb.doc, but the | |
976 | easiest way to read it is by using the help() function of the pdb module |
|
977 | easiest way to read it is by using the help() function of the pdb module | |
977 | as follows (in an IPython prompt):: |
|
978 | as follows (in an IPython prompt):: | |
978 |
|
979 | |||
979 | In [1]: import pdb |
|
980 | In [1]: import pdb | |
980 | In [2]: pdb.help() |
|
981 | In [2]: pdb.help() | |
981 |
|
982 | |||
982 | This will load the pdb.doc document in a file viewer for you automatically. |
|
983 | This will load the pdb.doc document in a file viewer for you automatically. | |
983 |
|
984 | |||
984 |
|
985 | |||
985 | Automatic invocation of pdb on exceptions |
|
986 | Automatic invocation of pdb on exceptions | |
986 | ----------------------------------------- |
|
987 | ----------------------------------------- | |
987 |
|
988 | |||
988 | IPython, if started with the ``--pdb`` option (or if the option is set in |
|
989 | IPython, if started with the ``--pdb`` option (or if the option is set in | |
989 | your config file) can call the Python pdb debugger every time your code |
|
990 | your config file) can call the Python pdb debugger every time your code | |
990 | triggers an uncaught exception. This feature |
|
991 | triggers an uncaught exception. This feature | |
991 | can also be toggled at any time with the %pdb magic command. This can be |
|
992 | can also be toggled at any time with the %pdb magic command. This can be | |
992 | extremely useful in order to find the origin of subtle bugs, because pdb |
|
993 | extremely useful in order to find the origin of subtle bugs, because pdb | |
993 | opens up at the point in your code which triggered the exception, and |
|
994 | opens up at the point in your code which triggered the exception, and | |
994 | while your program is at this point 'dead', all the data is still |
|
995 | while your program is at this point 'dead', all the data is still | |
995 | available and you can walk up and down the stack frame and understand |
|
996 | available and you can walk up and down the stack frame and understand | |
996 | the origin of the problem. |
|
997 | the origin of the problem. | |
997 |
|
998 | |||
998 | Furthermore, you can use these debugging facilities both with the |
|
999 | Furthermore, you can use these debugging facilities both with the | |
999 | embedded IPython mode and without IPython at all. For an embedded shell |
|
1000 | embedded IPython mode and without IPython at all. For an embedded shell | |
1000 | (see sec. Embedding_), simply call the constructor with |
|
1001 | (see sec. Embedding_), simply call the constructor with | |
1001 | ``--pdb`` in the argument string and pdb will automatically be called if an |
|
1002 | ``--pdb`` in the argument string and pdb will automatically be called if an | |
1002 | uncaught exception is triggered by your code. |
|
1003 | uncaught exception is triggered by your code. | |
1003 |
|
1004 | |||
1004 | For stand-alone use of the feature in your programs which do not use |
|
1005 | For stand-alone use of the feature in your programs which do not use | |
1005 | IPython at all, put the following lines toward the top of your 'main' |
|
1006 | IPython at all, put the following lines toward the top of your 'main' | |
1006 | routine:: |
|
1007 | routine:: | |
1007 |
|
1008 | |||
1008 | import sys |
|
1009 | import sys | |
1009 | from IPython.core import ultratb |
|
1010 | from IPython.core import ultratb | |
1010 | sys.excepthook = ultratb.FormattedTB(mode='Verbose', |
|
1011 | sys.excepthook = ultratb.FormattedTB(mode='Verbose', | |
1011 | color_scheme='Linux', call_pdb=1) |
|
1012 | color_scheme='Linux', call_pdb=1) | |
1012 |
|
1013 | |||
1013 | The mode keyword can be either 'Verbose' or 'Plain', giving either very |
|
1014 | The mode keyword can be either 'Verbose' or 'Plain', giving either very | |
1014 | detailed or normal tracebacks respectively. The color_scheme keyword can |
|
1015 | detailed or normal tracebacks respectively. The color_scheme keyword can | |
1015 | be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same |
|
1016 | be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same | |
1016 | options which can be set in IPython with ``--colors`` and ``--xmode``. |
|
1017 | options which can be set in IPython with ``--colors`` and ``--xmode``. | |
1017 |
|
1018 | |||
1018 | This will give any of your programs detailed, colored tracebacks with |
|
1019 | This will give any of your programs detailed, colored tracebacks with | |
1019 | automatic invocation of pdb. |
|
1020 | automatic invocation of pdb. | |
1020 |
|
1021 | |||
1021 |
|
1022 | |||
1022 | Extensions for syntax processing |
|
1023 | Extensions for syntax processing | |
1023 | ================================ |
|
1024 | ================================ | |
1024 |
|
1025 | |||
1025 | This isn't for the faint of heart, because the potential for breaking |
|
1026 | This isn't for the faint of heart, because the potential for breaking | |
1026 | things is quite high. But it can be a very powerful and useful feature. |
|
1027 | things is quite high. But it can be a very powerful and useful feature. | |
1027 | In a nutshell, you can redefine the way IPython processes the user input |
|
1028 | In a nutshell, you can redefine the way IPython processes the user input | |
1028 | line to accept new, special extensions to the syntax without needing to |
|
1029 | line to accept new, special extensions to the syntax without needing to | |
1029 | change any of IPython's own code. |
|
1030 | change any of IPython's own code. | |
1030 |
|
1031 | |||
1031 | In the IPython/extensions directory you will find some examples |
|
1032 | In the IPython/extensions directory you will find some examples | |
1032 | supplied, which we will briefly describe now. These can be used 'as is' |
|
1033 | supplied, which we will briefly describe now. These can be used 'as is' | |
1033 | (and both provide very useful functionality), or you can use them as a |
|
1034 | (and both provide very useful functionality), or you can use them as a | |
1034 | starting point for writing your own extensions. |
|
1035 | starting point for writing your own extensions. | |
1035 |
|
1036 | |||
1036 | .. _pasting_with_prompts: |
|
1037 | .. _pasting_with_prompts: | |
1037 |
|
1038 | |||
1038 | Pasting of code starting with Python or IPython prompts |
|
1039 | Pasting of code starting with Python or IPython prompts | |
1039 | ------------------------------------------------------- |
|
1040 | ------------------------------------------------------- | |
1040 |
|
1041 | |||
1041 | IPython is smart enough to filter out input prompts, be they plain Python ones |
|
1042 | IPython is smart enough to filter out input prompts, be they plain Python ones | |
1042 | (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can |
|
1043 | (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can | |
1043 | therefore copy and paste from existing interactive sessions without worry. |
|
1044 | therefore copy and paste from existing interactive sessions without worry. | |
1044 |
|
1045 | |||
1045 | The following is a 'screenshot' of how things work, copying an example from the |
|
1046 | The following is a 'screenshot' of how things work, copying an example from the | |
1046 | standard Python tutorial:: |
|
1047 | standard Python tutorial:: | |
1047 |
|
1048 | |||
1048 | In [1]: >>> # Fibonacci series: |
|
1049 | In [1]: >>> # Fibonacci series: | |
1049 |
|
1050 | |||
1050 | In [2]: ... # the sum of two elements defines the next |
|
1051 | In [2]: ... # the sum of two elements defines the next | |
1051 |
|
1052 | |||
1052 | In [3]: ... a, b = 0, 1 |
|
1053 | In [3]: ... a, b = 0, 1 | |
1053 |
|
1054 | |||
1054 | In [4]: >>> while b < 10: |
|
1055 | In [4]: >>> while b < 10: | |
1055 | ...: ... print b |
|
1056 | ...: ... print b | |
1056 | ...: ... a, b = b, a+b |
|
1057 | ...: ... a, b = b, a+b | |
1057 | ...: |
|
1058 | ...: | |
1058 | 1 |
|
1059 | 1 | |
1059 | 1 |
|
1060 | 1 | |
1060 | 2 |
|
1061 | 2 | |
1061 | 3 |
|
1062 | 3 | |
1062 | 5 |
|
1063 | 5 | |
1063 | 8 |
|
1064 | 8 | |
1064 |
|
1065 | |||
1065 | And pasting from IPython sessions works equally well:: |
|
1066 | And pasting from IPython sessions works equally well:: | |
1066 |
|
1067 | |||
1067 | In [1]: In [5]: def f(x): |
|
1068 | In [1]: In [5]: def f(x): | |
1068 | ...: ...: "A simple function" |
|
1069 | ...: ...: "A simple function" | |
1069 | ...: ...: return x**2 |
|
1070 | ...: ...: return x**2 | |
1070 | ...: ...: |
|
1071 | ...: ...: | |
1071 |
|
1072 | |||
1072 | In [2]: f(3) |
|
1073 | In [2]: f(3) | |
1073 | Out[2]: 9 |
|
1074 | Out[2]: 9 | |
1074 |
|
1075 | |||
1075 | .. _gui_support: |
|
1076 | .. _gui_support: | |
1076 |
|
1077 | |||
1077 | GUI event loop support |
|
1078 | GUI event loop support | |
1078 | ====================== |
|
1079 | ====================== | |
1079 |
|
1080 | |||
1080 | .. versionadded:: 0.11 |
|
1081 | .. versionadded:: 0.11 | |
1081 | The ``%gui`` magic and :mod:`IPython.lib.inputhook`. |
|
1082 | The ``%gui`` magic and :mod:`IPython.lib.inputhook`. | |
1082 |
|
1083 | |||
1083 | IPython has excellent support for working interactively with Graphical User |
|
1084 | IPython has excellent support for working interactively with Graphical User | |
1084 | Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is |
|
1085 | Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is | |
1085 | implemented using Python's builtin ``PyOSInputHook`` hook. This implementation |
|
1086 | implemented using Python's builtin ``PyOSInputHook`` hook. This implementation | |
1086 | is extremely robust compared to our previous thread-based version. The |
|
1087 | is extremely robust compared to our previous thread-based version. The | |
1087 | advantages of this are: |
|
1088 | advantages of this are: | |
1088 |
|
1089 | |||
1089 | * GUIs can be enabled and disabled dynamically at runtime. |
|
1090 | * GUIs can be enabled and disabled dynamically at runtime. | |
1090 | * The active GUI can be switched dynamically at runtime. |
|
1091 | * The active GUI can be switched dynamically at runtime. | |
1091 | * In some cases, multiple GUIs can run simultaneously with no problems. |
|
1092 | * In some cases, multiple GUIs can run simultaneously with no problems. | |
1092 | * There is a developer API in :mod:`IPython.lib.inputhook` for customizing |
|
1093 | * There is a developer API in :mod:`IPython.lib.inputhook` for customizing | |
1093 | all of these things. |
|
1094 | all of these things. | |
1094 |
|
1095 | |||
1095 | For users, enabling GUI event loop integration is simple. You simple use the |
|
1096 | For users, enabling GUI event loop integration is simple. You simple use the | |
1096 | ``%gui`` magic as follows:: |
|
1097 | ``%gui`` magic as follows:: | |
1097 |
|
1098 | |||
1098 | %gui [GUINAME] |
|
1099 | %gui [GUINAME] | |
1099 |
|
1100 | |||
1100 | With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME`` |
|
1101 | With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME`` | |
1101 | arguments are ``wx``, ``qt``, ``gtk`` and ``tk``. |
|
1102 | arguments are ``wx``, ``qt``, ``gtk`` and ``tk``. | |
1102 |
|
1103 | |||
1103 | Thus, to use wxPython interactively and create a running :class:`wx.App` |
|
1104 | Thus, to use wxPython interactively and create a running :class:`wx.App` | |
1104 | object, do:: |
|
1105 | object, do:: | |
1105 |
|
1106 | |||
1106 | %gui wx |
|
1107 | %gui wx | |
1107 |
|
1108 | |||
1108 | For information on IPython's Matplotlib integration (and the ``pylab`` mode) |
|
1109 | For information on IPython's Matplotlib integration (and the ``pylab`` mode) | |
1109 | see :ref:`this section <matplotlib_support>`. |
|
1110 | see :ref:`this section <matplotlib_support>`. | |
1110 |
|
1111 | |||
1111 | For developers that want to use IPython's GUI event loop integration in the |
|
1112 | For developers that want to use IPython's GUI event loop integration in the | |
1112 | form of a library, these capabilities are exposed in library form in the |
|
1113 | form of a library, these capabilities are exposed in library form in the | |
1113 | :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules. |
|
1114 | :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules. | |
1114 | Interested developers should see the module docstrings for more information, |
|
1115 | Interested developers should see the module docstrings for more information, | |
1115 | but there are a few points that should be mentioned here. |
|
1116 | but there are a few points that should be mentioned here. | |
1116 |
|
1117 | |||
1117 | First, the ``PyOSInputHook`` approach only works in command line settings |
|
1118 | First, the ``PyOSInputHook`` approach only works in command line settings | |
1118 | where readline is activated. The integration with various eventloops |
|
1119 | where readline is activated. The integration with various eventloops | |
1119 | is handled somewhat differently (and more simply) when using the standalone |
|
1120 | is handled somewhat differently (and more simply) when using the standalone | |
1120 | kernel, as in the qtconsole and notebook. |
|
1121 | kernel, as in the qtconsole and notebook. | |
1121 |
|
1122 | |||
1122 | Second, when using the ``PyOSInputHook`` approach, a GUI application should |
|
1123 | Second, when using the ``PyOSInputHook`` approach, a GUI application should | |
1123 | *not* start its event loop. Instead all of this is handled by the |
|
1124 | *not* start its event loop. Instead all of this is handled by the | |
1124 | ``PyOSInputHook``. This means that applications that are meant to be used both |
|
1125 | ``PyOSInputHook``. This means that applications that are meant to be used both | |
1125 | in IPython and as standalone apps need to have special code to detects how the |
|
1126 | in IPython and as standalone apps need to have special code to detects how the | |
1126 | application is being run. We highly recommend using IPython's support for this. |
|
1127 | application is being run. We highly recommend using IPython's support for this. | |
1127 | Since the details vary slightly between toolkits, we point you to the various |
|
1128 | Since the details vary slightly between toolkits, we point you to the various | |
1128 | examples in our source directory :file:`docs/examples/lib` that demonstrate |
|
1129 | examples in our source directory :file:`docs/examples/lib` that demonstrate | |
1129 | these capabilities. |
|
1130 | these capabilities. | |
1130 |
|
1131 | |||
1131 | .. warning:: |
|
1132 | .. warning:: | |
1132 |
|
1133 | |||
1133 | The WX version of this is currently broken. While ``--pylab=wx`` works |
|
1134 | The WX version of this is currently broken. While ``--pylab=wx`` works | |
1134 | fine, standalone WX apps do not. See |
|
1135 | fine, standalone WX apps do not. See | |
1135 | https://github.com/ipython/ipython/issues/645 for details of our progress on |
|
1136 | https://github.com/ipython/ipython/issues/645 for details of our progress on | |
1136 | this issue. |
|
1137 | this issue. | |
1137 |
|
1138 | |||
1138 |
|
1139 | |||
1139 | Third, unlike previous versions of IPython, we no longer "hijack" (replace |
|
1140 | Third, unlike previous versions of IPython, we no longer "hijack" (replace | |
1140 | them with no-ops) the event loops. This is done to allow applications that |
|
1141 | them with no-ops) the event loops. This is done to allow applications that | |
1141 | actually need to run the real event loops to do so. This is often needed to |
|
1142 | actually need to run the real event loops to do so. This is often needed to | |
1142 | process pending events at critical points. |
|
1143 | process pending events at critical points. | |
1143 |
|
1144 | |||
1144 | Finally, we also have a number of examples in our source directory |
|
1145 | Finally, we also have a number of examples in our source directory | |
1145 | :file:`docs/examples/lib` that demonstrate these capabilities. |
|
1146 | :file:`docs/examples/lib` that demonstrate these capabilities. | |
1146 |
|
1147 | |||
1147 | PyQt and PySide |
|
1148 | PyQt and PySide | |
1148 | --------------- |
|
1149 | --------------- | |
1149 |
|
1150 | |||
1150 | .. attempt at explanation of the complete mess that is Qt support |
|
1151 | .. attempt at explanation of the complete mess that is Qt support | |
1151 |
|
1152 | |||
1152 | When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either |
|
1153 | When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either | |
1153 | PyQt4 or PySide. There are three options for configuration here, because |
|
1154 | PyQt4 or PySide. There are three options for configuration here, because | |
1154 | PyQt4 has two APIs for QString and QVariant - v1, which is the default on |
|
1155 | PyQt4 has two APIs for QString and QVariant - v1, which is the default on | |
1155 | Python 2, and the more natural v2, which is the only API supported by PySide. |
|
1156 | Python 2, and the more natural v2, which is the only API supported by PySide. | |
1156 | v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole |
|
1157 | v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole | |
1157 | uses v2, but you can still use any interface in your code, since the |
|
1158 | uses v2, but you can still use any interface in your code, since the | |
1158 | Qt frontend is in a different process. |
|
1159 | Qt frontend is in a different process. | |
1159 |
|
1160 | |||
1160 | The default will be to import PyQt4 without configuration of the APIs, thus |
|
1161 | The default will be to import PyQt4 without configuration of the APIs, thus | |
1161 | matching what most applications would expect. It will fall back of PySide if |
|
1162 | matching what most applications would expect. It will fall back of PySide if | |
1162 | PyQt4 is unavailable. |
|
1163 | PyQt4 is unavailable. | |
1163 |
|
1164 | |||
1164 | If specified, IPython will respect the environment variable ``QT_API`` used |
|
1165 | If specified, IPython will respect the environment variable ``QT_API`` used | |
1165 | by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires |
|
1166 | by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires | |
1166 | PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used, |
|
1167 | PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used, | |
1167 | and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for |
|
1168 | and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for | |
1168 | QString and QVariant, so ETS codes like MayaVi will also work with IPython. |
|
1169 | QString and QVariant, so ETS codes like MayaVi will also work with IPython. | |
1169 |
|
1170 | |||
1170 | If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython |
|
1171 | If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython | |
1171 | will ask matplotlib which Qt library to use (only if QT_API is *not set*), via |
|
1172 | will ask matplotlib which Qt library to use (only if QT_API is *not set*), via | |
1172 | the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then |
|
1173 | the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then | |
1173 | IPython will always use PyQt4 without setting the v2 APIs, since neither v2 |
|
1174 | IPython will always use PyQt4 without setting the v2 APIs, since neither v2 | |
1174 | PyQt nor PySide work. |
|
1175 | PyQt nor PySide work. | |
1175 |
|
1176 | |||
1176 | .. warning:: |
|
1177 | .. warning:: | |
1177 |
|
1178 | |||
1178 | Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set |
|
1179 | Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set | |
1179 | to work with IPython's qt integration, because otherwise PyQt4 will be |
|
1180 | to work with IPython's qt integration, because otherwise PyQt4 will be | |
1180 | loaded in an incompatible mode. |
|
1181 | loaded in an incompatible mode. | |
1181 |
|
1182 | |||
1182 | It also means that you must *not* have ``QT_API`` set if you want to |
|
1183 | It also means that you must *not* have ``QT_API`` set if you want to | |
1183 | use ``--gui=qt`` with code that requires PyQt4 API v1. |
|
1184 | use ``--gui=qt`` with code that requires PyQt4 API v1. | |
1184 |
|
1185 | |||
1185 |
|
1186 | |||
1186 | .. _matplotlib_support: |
|
1187 | .. _matplotlib_support: | |
1187 |
|
1188 | |||
1188 | Plotting with matplotlib |
|
1189 | Plotting with matplotlib | |
1189 | ======================== |
|
1190 | ======================== | |
1190 |
|
1191 | |||
1191 | `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib |
|
1192 | `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib | |
1192 | can produce plots on screen using a variety of GUI toolkits, including Tk, |
|
1193 | can produce plots on screen using a variety of GUI toolkits, including Tk, | |
1193 | PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for |
|
1194 | PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for | |
1194 | scientific computing, all with a syntax compatible with that of the popular |
|
1195 | scientific computing, all with a syntax compatible with that of the popular | |
1195 | Matlab program. |
|
1196 | Matlab program. | |
1196 |
|
1197 | |||
1197 | To start IPython with matplotlib support, use the ``--pylab`` switch. If no |
|
1198 | To start IPython with matplotlib support, use the ``--pylab`` switch. If no | |
1198 | arguments are given, IPython will automatically detect your choice of |
|
1199 | arguments are given, IPython will automatically detect your choice of | |
1199 | matplotlib backend. You can also request a specific backend with |
|
1200 | matplotlib backend. You can also request a specific backend with | |
1200 | ``--pylab=backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', |
|
1201 | ``--pylab=backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', | |
1201 | 'osx'. |
|
1202 | 'osx'. | |
1202 |
|
1203 | |||
1203 | .. _Matplotlib: http://matplotlib.sourceforge.net |
|
1204 | .. _Matplotlib: http://matplotlib.sourceforge.net | |
1204 |
|
1205 | |||
1205 | .. _interactive_demos: |
|
1206 | .. _interactive_demos: | |
1206 |
|
1207 | |||
1207 | Interactive demos with IPython |
|
1208 | Interactive demos with IPython | |
1208 | ============================== |
|
1209 | ============================== | |
1209 |
|
1210 | |||
1210 | IPython ships with a basic system for running scripts interactively in |
|
1211 | IPython ships with a basic system for running scripts interactively in | |
1211 | sections, useful when presenting code to audiences. A few tags embedded |
|
1212 | sections, useful when presenting code to audiences. A few tags embedded | |
1212 | in comments (so that the script remains valid Python code) divide a file |
|
1213 | in comments (so that the script remains valid Python code) divide a file | |
1213 | into separate blocks, and the demo can be run one block at a time, with |
|
1214 | into separate blocks, and the demo can be run one block at a time, with | |
1214 | IPython printing (with syntax highlighting) the block before executing |
|
1215 | IPython printing (with syntax highlighting) the block before executing | |
1215 | it, and returning to the interactive prompt after each block. The |
|
1216 | it, and returning to the interactive prompt after each block. The | |
1216 | interactive namespace is updated after each block is run with the |
|
1217 | interactive namespace is updated after each block is run with the | |
1217 | contents of the demo's namespace. |
|
1218 | contents of the demo's namespace. | |
1218 |
|
1219 | |||
1219 | This allows you to show a piece of code, run it and then execute |
|
1220 | This allows you to show a piece of code, run it and then execute | |
1220 | interactively commands based on the variables just created. Once you |
|
1221 | interactively commands based on the variables just created. Once you | |
1221 | want to continue, you simply execute the next block of the demo. The |
|
1222 | want to continue, you simply execute the next block of the demo. The | |
1222 | following listing shows the markup necessary for dividing a script into |
|
1223 | following listing shows the markup necessary for dividing a script into | |
1223 | sections for execution as a demo: |
|
1224 | sections for execution as a demo: | |
1224 |
|
1225 | |||
1225 | .. literalinclude:: ../../examples/lib/example-demo.py |
|
1226 | .. literalinclude:: ../../examples/lib/example-demo.py | |
1226 | :language: python |
|
1227 | :language: python | |
1227 |
|
1228 | |||
1228 | In order to run a file as a demo, you must first make a Demo object out |
|
1229 | In order to run a file as a demo, you must first make a Demo object out | |
1229 | of it. If the file is named myscript.py, the following code will make a |
|
1230 | of it. If the file is named myscript.py, the following code will make a | |
1230 | demo:: |
|
1231 | demo:: | |
1231 |
|
1232 | |||
1232 | from IPython.lib.demo import Demo |
|
1233 | from IPython.lib.demo import Demo | |
1233 |
|
1234 | |||
1234 | mydemo = Demo('myscript.py') |
|
1235 | mydemo = Demo('myscript.py') | |
1235 |
|
1236 | |||
1236 | This creates the mydemo object, whose blocks you run one at a time by |
|
1237 | This creates the mydemo object, whose blocks you run one at a time by | |
1237 | simply calling the object with no arguments. If you have autocall active |
|
1238 | simply calling the object with no arguments. If you have autocall active | |
1238 | in IPython (the default), all you need to do is type:: |
|
1239 | in IPython (the default), all you need to do is type:: | |
1239 |
|
1240 | |||
1240 | mydemo |
|
1241 | mydemo | |
1241 |
|
1242 | |||
1242 | and IPython will call it, executing each block. Demo objects can be |
|
1243 | and IPython will call it, executing each block. Demo objects can be | |
1243 | restarted, you can move forward or back skipping blocks, re-execute the |
|
1244 | restarted, you can move forward or back skipping blocks, re-execute the | |
1244 | last block, etc. Simply use the Tab key on a demo object to see its |
|
1245 | last block, etc. Simply use the Tab key on a demo object to see its | |
1245 | methods, and call '?' on them to see their docstrings for more usage |
|
1246 | methods, and call '?' on them to see their docstrings for more usage | |
1246 | details. In addition, the demo module itself contains a comprehensive |
|
1247 | details. In addition, the demo module itself contains a comprehensive | |
1247 | docstring, which you can access via:: |
|
1248 | docstring, which you can access via:: | |
1248 |
|
1249 | |||
1249 | from IPython.lib import demo |
|
1250 | from IPython.lib import demo | |
1250 |
|
1251 | |||
1251 | demo? |
|
1252 | demo? | |
1252 |
|
1253 | |||
1253 | Limitations: It is important to note that these demos are limited to |
|
1254 | Limitations: It is important to note that these demos are limited to | |
1254 | fairly simple uses. In particular, you cannot break up sections within |
|
1255 | fairly simple uses. In particular, you cannot break up sections within | |
1255 | indented code (loops, if statements, function definitions, etc.) |
|
1256 | indented code (loops, if statements, function definitions, etc.) | |
1256 | Supporting something like this would basically require tracking the |
|
1257 | Supporting something like this would basically require tracking the | |
1257 | internal execution state of the Python interpreter, so only top-level |
|
1258 | internal execution state of the Python interpreter, so only top-level | |
1258 | divisions are allowed. If you want to be able to open an IPython |
|
1259 | divisions are allowed. If you want to be able to open an IPython | |
1259 | instance at an arbitrary point in a program, you can use IPython's |
|
1260 | instance at an arbitrary point in a program, you can use IPython's | |
1260 | embedding facilities, see :func:`IPython.embed` for details. |
|
1261 | embedding facilities, see :func:`IPython.embed` for details. | |
1261 |
|
1262 |
@@ -1,294 +1,293 b'' | |||||
1 | .. _ipython_as_shell: |
|
1 | .. _ipython_as_shell: | |
2 |
|
2 | |||
3 | ========================= |
|
3 | ========================= | |
4 | IPython as a system shell |
|
4 | IPython as a system shell | |
5 | ========================= |
|
5 | ========================= | |
6 |
|
6 | |||
7 | .. warning:: |
|
7 | .. warning:: | |
8 |
|
8 | |||
9 | As of the 0.11 version of IPython, most of the APIs used by the shell |
|
9 | As of the 0.11 version of IPython, most of the APIs used by the shell | |
10 | profile have been changed, so the profile currently does very little |
|
10 | profile have been changed, so the profile currently does very little | |
11 | beyond changing the IPython prompt. To help restore the shell |
|
11 | beyond changing the IPython prompt. To help restore the shell | |
12 | profile to past functionality described here, the old code is found in |
|
12 | profile to past functionality described here, the old code is found in | |
13 | :file:`IPython/deathrow`, which needs to be updated to use the |
|
13 | :file:`IPython/deathrow`, which needs to be updated to use the | |
14 | APIs in 0.11. |
|
14 | APIs in 0.11. | |
15 |
|
15 | |||
16 | Overview |
|
16 | Overview | |
17 | ======== |
|
17 | ======== | |
18 |
|
18 | |||
19 | The 'sh' profile optimizes IPython for system shell usage. Apart from |
|
19 | The 'sh' profile optimizes IPython for system shell usage. Apart from | |
20 | certain job control functionality that is present in unix (ctrl+z does |
|
20 | certain job control functionality that is present in unix (ctrl+z does | |
21 | "suspend"), the sh profile should provide you with most of the |
|
21 | "suspend"), the sh profile should provide you with most of the | |
22 | functionality you use daily in system shell, and more. Invoke IPython |
|
22 | functionality you use daily in system shell, and more. Invoke IPython | |
23 | in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching |
|
23 | in 'sh' profile by doing 'ipython -p sh', or (in win32) by launching | |
24 | the "pysh" shortcut in start menu. |
|
24 | the "pysh" shortcut in start menu. | |
25 |
|
25 | |||
26 | If you want to use the features of sh profile as your defaults (which |
|
26 | If you want to use the features of sh profile as your defaults (which | |
27 | might be a good idea if you use other profiles a lot of the time but |
|
27 | might be a good idea if you use other profiles a lot of the time but | |
28 | still want the convenience of sh profile), add ``import ipy_profile_sh`` |
|
28 | still want the convenience of sh profile), add ``import ipy_profile_sh`` | |
29 | to your $IPYTHON_DIR/ipy_user_conf.py. |
|
29 | to your $IPYTHON_DIR/ipy_user_conf.py. | |
30 |
|
30 | |||
31 | The 'sh' profile is different from the default profile in that: |
|
31 | The 'sh' profile is different from the default profile in that: | |
32 |
|
32 | |||
33 | * Prompt shows the current directory |
|
33 | * Prompt shows the current directory | |
34 | * Spacing between prompts and input is more compact (no padding with |
|
34 | * Spacing between prompts and input is more compact (no padding with | |
35 | empty lines). The startup banner is more compact as well. |
|
35 | empty lines). The startup banner is more compact as well. | |
36 | * System commands are directly available (in alias table) without |
|
36 | * System commands are directly available (in alias table) without | |
37 | requesting %rehashx - however, if you install new programs along |
|
37 | requesting %rehashx - however, if you install new programs along | |
38 | your PATH, you might want to run %rehashx to update the persistent |
|
38 | your PATH, you might want to run %rehashx to update the persistent | |
39 | alias table |
|
39 | alias table | |
40 | * Macros are stored in raw format by default. That is, instead of |
|
40 | * Macros are stored in raw format by default. That is, instead of | |
41 | '_ip.system("cat foo"), the macro will contain text 'cat foo') |
|
41 | '_ip.system("cat foo"), the macro will contain text 'cat foo') | |
42 | * Autocall is in full mode |
|
42 | * Autocall is in full mode | |
43 | * Calling "up" does "cd .." |
|
43 | * Calling "up" does "cd .." | |
44 |
|
44 | |||
45 | The 'sh' profile is different from the now-obsolete (and unavailable) |
|
45 | The 'sh' profile is different from the now-obsolete (and unavailable) | |
46 | 'pysh' profile in that: |
|
46 | 'pysh' profile in that the ``$$var = command`` and ``$var = command`` syntax is | |
47 |
|
47 | not supported anymore. Use ``var = !command`` instead (which is available in all | ||
48 | * '$$var = command' and '$var = command' syntax is not supported |
|
48 | IPython profiles). | |
49 | * anymore. Use 'var = !command' instead (incidentally, this is |
|
|||
50 | * available in all IPython profiles). Note that !!command *will* |
|
|||
51 | * work. |
|
|||
52 |
|
49 | |||
53 | Aliases |
|
50 | Aliases | |
54 | ======= |
|
51 | ======= | |
55 |
|
52 | |||
56 | All of your $PATH has been loaded as IPython aliases, so you should be |
|
53 | All of your $PATH has been loaded as IPython aliases, so you should be | |
57 | able to type any normal system command and have it executed. See |
|
54 | able to type any normal system command and have it executed. See | |
58 | %alias? and %unalias? for details on the alias facilities. See also |
|
55 | %alias? and %unalias? for details on the alias facilities. See also | |
59 | %rehashx? for details on the mechanism used to load $PATH. |
|
56 | %rehashx? for details on the mechanism used to load $PATH. | |
60 |
|
57 | |||
61 |
|
58 | |||
62 | Directory management |
|
59 | Directory management | |
63 | ==================== |
|
60 | ==================== | |
64 |
|
61 | |||
65 | Since each command passed by ipython to the underlying system is executed |
|
62 | Since each command passed by ipython to the underlying system is executed | |
66 | in a subshell which exits immediately, you can NOT use !cd to navigate |
|
63 | in a subshell which exits immediately, you can NOT use !cd to navigate | |
67 | the filesystem. |
|
64 | the filesystem. | |
68 |
|
65 | |||
69 | IPython provides its own builtin '%cd' magic command to move in the |
|
66 | IPython provides its own builtin '%cd' magic command to move in the | |
70 | filesystem (the % is not required with automagic on). It also maintains |
|
67 | filesystem (the % is not required with automagic on). It also maintains | |
71 | a list of visited directories (use %dhist to see it) and allows direct |
|
68 | a list of visited directories (use %dhist to see it) and allows direct | |
72 | switching to any of them. Type 'cd?' for more details. |
|
69 | switching to any of them. Type 'cd?' for more details. | |
73 |
|
70 | |||
74 | %pushd, %popd and %dirs are provided for directory stack handling. |
|
71 | %pushd, %popd and %dirs are provided for directory stack handling. | |
75 |
|
72 | |||
76 |
|
73 | |||
77 | Enabled extensions |
|
74 | Enabled extensions | |
78 | ================== |
|
75 | ================== | |
79 |
|
76 | |||
80 | Some extensions, listed below, are enabled as default in this profile. |
|
77 | Some extensions, listed below, are enabled as default in this profile. | |
81 |
|
78 | |||
82 | envpersist |
|
79 | envpersist | |
83 | ---------- |
|
80 | ---------- | |
84 |
|
81 | |||
85 | %env can be used to "remember" environment variable manipulations. Examples:: |
|
82 | %env can be used to "remember" environment variable manipulations. Examples:: | |
86 |
|
83 | |||
87 | %env - Show all environment variables |
|
84 | %env - Show all environment variables | |
88 | %env VISUAL=jed - set VISUAL to jed |
|
85 | %env VISUAL=jed - set VISUAL to jed | |
89 | %env PATH+=;/foo - append ;foo to PATH |
|
86 | %env PATH+=;/foo - append ;foo to PATH | |
90 | %env PATH+=;/bar - also append ;bar to PATH |
|
87 | %env PATH+=;/bar - also append ;bar to PATH | |
91 | %env PATH-=/wbin; - prepend /wbin; to PATH |
|
88 | %env PATH-=/wbin; - prepend /wbin; to PATH | |
92 | %env -d VISUAL - forget VISUAL persistent val |
|
89 | %env -d VISUAL - forget VISUAL persistent val | |
93 | %env -p - print all persistent env modifications |
|
90 | %env -p - print all persistent env modifications | |
94 |
|
91 | |||
95 | ipy_which |
|
92 | ipy_which | |
96 | --------- |
|
93 | --------- | |
97 |
|
94 | |||
98 | %which magic command. Like 'which' in unix, but knows about ipython aliases. |
|
95 | %which magic command. Like 'which' in unix, but knows about ipython aliases. | |
99 |
|
96 | |||
100 | Example:: |
|
97 | Example:: | |
101 |
|
98 | |||
102 | [C:/ipython]|14> %which st |
|
99 | [C:/ipython]|14> %which st | |
103 | st -> start . |
|
100 | st -> start . | |
104 | [C:/ipython]|15> %which d |
|
101 | [C:/ipython]|15> %which d | |
105 | d -> dir /w /og /on |
|
102 | d -> dir /w /og /on | |
106 | [C:/ipython]|16> %which cp |
|
103 | [C:/ipython]|16> %which cp | |
107 | cp -> cp |
|
104 | cp -> cp | |
108 | == c:\bin\cp.exe |
|
105 | == c:\bin\cp.exe | |
109 | c:\bin\cp.exe |
|
106 | c:\bin\cp.exe | |
110 |
|
107 | |||
111 | ipy_app_completers |
|
108 | ipy_app_completers | |
112 | ------------------ |
|
109 | ------------------ | |
113 |
|
110 | |||
114 | Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu. |
|
111 | Custom tab completers for some apps like svn, hg, bzr, apt-get. Try 'apt-get install <TAB>' in debian/ubuntu. | |
115 |
|
112 | |||
116 | ipy_rehashdir |
|
113 | ipy_rehashdir | |
117 | ------------- |
|
114 | ------------- | |
118 |
|
115 | |||
119 | Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir:: |
|
116 | Allows you to add system command aliases for commands that are not along your path. Let's say that you just installed Putty and want to be able to invoke it without adding it to path, you can create the alias for it with rehashdir:: | |
120 |
|
117 | |||
121 | [~]|22> cd c:/opt/PuTTY/ |
|
118 | [~]|22> cd c:/opt/PuTTY/ | |
122 | [c:opt/PuTTY]|23> rehashdir . |
|
119 | [c:opt/PuTTY]|23> rehashdir . | |
123 | <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000'] |
|
120 | <23> ['pageant', 'plink', 'pscp', 'psftp', 'putty', 'puttygen', 'unins000'] | |
124 |
|
121 | |||
125 | Now, you can execute any of those commams directly:: |
|
122 | Now, you can execute any of those commams directly:: | |
126 |
|
123 | |||
127 | [c:opt/PuTTY]|24> cd |
|
124 | [c:opt/PuTTY]|24> cd | |
128 | [~]|25> putty |
|
125 | [~]|25> putty | |
129 |
|
126 | |||
130 | (the putty window opens). |
|
127 | (the putty window opens). | |
131 |
|
128 | |||
132 | If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop:: |
|
129 | If you want to store the alias so that it will always be available, do '%store putty'. If you want to %store all these aliases persistently, just do it in a for loop:: | |
133 |
|
130 | |||
134 | [~]|27> for a in _23: |
|
131 | [~]|27> for a in _23: | |
135 | |..> %store $a |
|
132 | |..> %store $a | |
136 | |..> |
|
133 | |..> | |
137 | |..> |
|
134 | |..> | |
138 | Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe') |
|
135 | Alias stored: pageant (0, 'c:\\opt\\PuTTY\\pageant.exe') | |
139 | Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe') |
|
136 | Alias stored: plink (0, 'c:\\opt\\PuTTY\\plink.exe') | |
140 | Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe') |
|
137 | Alias stored: pscp (0, 'c:\\opt\\PuTTY\\pscp.exe') | |
141 | Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe') |
|
138 | Alias stored: psftp (0, 'c:\\opt\\PuTTY\\psftp.exe') | |
142 | ... |
|
139 | ... | |
143 |
|
140 | |||
144 | mglob |
|
141 | mglob | |
145 | ----- |
|
142 | ----- | |
146 |
|
143 | |||
147 | Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples:: |
|
144 | Provide the magic function %mglob, which makes it easier (than the 'find' command) to collect (possibly recursive) file lists. Examples:: | |
148 |
|
145 | |||
149 | [c:/ipython]|9> mglob *.py |
|
146 | [c:/ipython]|9> mglob *.py | |
150 | [c:/ipython]|10> mglob *.py rec:*.txt |
|
147 | [c:/ipython]|10> mglob *.py rec:*.txt | |
151 | [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:. |
|
148 | [c:/ipython]|19> workfiles = %mglob !.svn/ !.hg/ !*_Data/ !*.bak rec:. | |
152 |
|
149 | |||
153 | Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'. |
|
150 | Note that the first 2 calls will put the file list in result history (_, _9, _10), and the last one will assign it to 'workfiles'. | |
154 |
|
151 | |||
155 |
|
152 | |||
156 | Prompt customization |
|
153 | Prompt customization | |
157 | ==================== |
|
154 | ==================== | |
158 |
|
155 | |||
159 | The sh profile uses the following prompt configurations:: |
|
156 | The sh profile uses the following prompt configurations:: | |
160 |
|
157 | |||
161 | o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>' |
|
158 | o.prompt_in1= r'\C_LightBlue[\C_LightCyan\Y2\C_LightBlue]\C_Green|\#>' | |
162 | o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>' |
|
159 | o.prompt_in2= r'\C_Green|\C_LightGreen\D\C_Green>' | |
163 |
|
160 | |||
164 | You can change the prompt configuration to your liking by editing |
|
161 | You can change the prompt configuration to your liking by editing | |
165 |
ipy |
|
162 | ipython_config.py. | |
|
163 | ||||
|
164 | .. _string_lists: | |||
166 |
|
165 | |||
167 | String lists |
|
166 | String lists | |
168 | ============ |
|
167 | ============ | |
169 |
|
168 | |||
170 | String lists (IPython.utils.text.SList) are handy way to process output |
|
169 | String lists (IPython.utils.text.SList) are handy way to process output | |
171 | from system commands. They are produced by ``var = !cmd`` syntax. |
|
170 | from system commands. They are produced by ``var = !cmd`` syntax. | |
172 |
|
171 | |||
173 | First, we acquire the output of 'ls -l':: |
|
172 | First, we acquire the output of 'ls -l':: | |
174 |
|
173 | |||
175 | [Q:doc/examples]|2> lines = !ls -l |
|
174 | [Q:doc/examples]|2> lines = !ls -l | |
176 | == |
|
175 | == | |
177 | ['total 23', |
|
176 | ['total 23', | |
178 | '-rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py', |
|
177 | '-rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py', | |
179 | '-rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py', |
|
178 | '-rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py', | |
180 | '-rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py', |
|
179 | '-rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py', | |
181 | '-rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py', |
|
180 | '-rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py', | |
182 | '-rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py', |
|
181 | '-rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py', | |
183 | '-rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py', |
|
182 | '-rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py', | |
184 | '-rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc'] |
|
183 | '-rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc'] | |
185 |
|
184 | |||
186 | Now, let's take a look at the contents of 'lines' (the first number is |
|
185 | Now, let's take a look at the contents of 'lines' (the first number is | |
187 | the list element number):: |
|
186 | the list element number):: | |
188 |
|
187 | |||
189 | [Q:doc/examples]|3> lines |
|
188 | [Q:doc/examples]|3> lines | |
190 | <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: |
|
189 | <3> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: | |
191 |
|
190 | |||
192 | 0: total 23 |
|
191 | 0: total 23 | |
193 | 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py |
|
192 | 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py | |
194 | 2: -rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py |
|
193 | 2: -rw-rw-rw- 1 ville None 1927 Sep 30 2006 example-embed-short.py | |
195 | 3: -rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py |
|
194 | 3: -rwxrwxrwx 1 ville None 4606 Sep 1 17:15 example-embed.py | |
196 | 4: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py |
|
195 | 4: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py | |
197 | 5: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py |
|
196 | 5: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py | |
198 | 6: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py |
|
197 | 6: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py | |
199 | 7: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc |
|
198 | 7: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc | |
200 |
|
199 | |||
201 | Now, let's filter out the 'embed' lines:: |
|
200 | Now, let's filter out the 'embed' lines:: | |
202 |
|
201 | |||
203 | [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1) |
|
202 | [Q:doc/examples]|4> l2 = lines.grep('embed',prune=1) | |
204 | [Q:doc/examples]|5> l2 |
|
203 | [Q:doc/examples]|5> l2 | |
205 | <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: |
|
204 | <5> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: | |
206 |
|
205 | |||
207 | 0: total 23 |
|
206 | 0: total 23 | |
208 | 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py |
|
207 | 1: -rw-rw-rw- 1 ville None 1163 Sep 30 2006 example-demo.py | |
209 | 2: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py |
|
208 | 2: -rwxrwxrwx 1 ville None 1017 Sep 30 2006 example-gnuplot.py | |
210 | 3: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py |
|
209 | 3: -rwxrwxrwx 1 ville None 339 Jun 11 18:01 extension.py | |
211 | 4: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py |
|
210 | 4: -rwxrwxrwx 1 ville None 113 Dec 20 2006 seteditor.py | |
212 | 5: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc |
|
211 | 5: -rwxrwxrwx 1 ville None 245 Dec 12 2006 seteditor.pyc | |
213 |
|
212 | |||
214 | Now, we want strings having just file names and permissions:: |
|
213 | Now, we want strings having just file names and permissions:: | |
215 |
|
214 | |||
216 | [Q:doc/examples]|6> l2.fields(8,0) |
|
215 | [Q:doc/examples]|6> l2.fields(8,0) | |
217 | <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: |
|
216 | <6> SList (.p, .n, .l, .s, .grep(), .fields() available). Value: | |
218 |
|
217 | |||
219 | 0: total |
|
218 | 0: total | |
220 | 1: example-demo.py -rw-rw-rw- |
|
219 | 1: example-demo.py -rw-rw-rw- | |
221 | 2: example-gnuplot.py -rwxrwxrwx |
|
220 | 2: example-gnuplot.py -rwxrwxrwx | |
222 | 3: extension.py -rwxrwxrwx |
|
221 | 3: extension.py -rwxrwxrwx | |
223 | 4: seteditor.py -rwxrwxrwx |
|
222 | 4: seteditor.py -rwxrwxrwx | |
224 | 5: seteditor.pyc -rwxrwxrwx |
|
223 | 5: seteditor.pyc -rwxrwxrwx | |
225 |
|
224 | |||
226 | Note how the line with 'total' does not raise IndexError. |
|
225 | Note how the line with 'total' does not raise IndexError. | |
227 |
|
226 | |||
228 | If you want to split these (yielding lists), call fields() without |
|
227 | If you want to split these (yielding lists), call fields() without | |
229 | arguments:: |
|
228 | arguments:: | |
230 |
|
229 | |||
231 | [Q:doc/examples]|7> _.fields() |
|
230 | [Q:doc/examples]|7> _.fields() | |
232 | <7> |
|
231 | <7> | |
233 | [['total'], |
|
232 | [['total'], | |
234 | ['example-demo.py', '-rw-rw-rw-'], |
|
233 | ['example-demo.py', '-rw-rw-rw-'], | |
235 | ['example-gnuplot.py', '-rwxrwxrwx'], |
|
234 | ['example-gnuplot.py', '-rwxrwxrwx'], | |
236 | ['extension.py', '-rwxrwxrwx'], |
|
235 | ['extension.py', '-rwxrwxrwx'], | |
237 | ['seteditor.py', '-rwxrwxrwx'], |
|
236 | ['seteditor.py', '-rwxrwxrwx'], | |
238 | ['seteditor.pyc', '-rwxrwxrwx']] |
|
237 | ['seteditor.pyc', '-rwxrwxrwx']] | |
239 |
|
238 | |||
240 | If you want to pass these separated with spaces to a command (typical |
|
239 | If you want to pass these separated with spaces to a command (typical | |
241 | for lists if files), use the .s property:: |
|
240 | for lists if files), use the .s property:: | |
242 |
|
241 | |||
243 |
|
242 | |||
244 | [Q:doc/examples]|13> files = l2.fields(8).s |
|
243 | [Q:doc/examples]|13> files = l2.fields(8).s | |
245 | [Q:doc/examples]|14> files |
|
244 | [Q:doc/examples]|14> files | |
246 | <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc' |
|
245 | <14> 'example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc' | |
247 | [Q:doc/examples]|15> ls $files |
|
246 | [Q:doc/examples]|15> ls $files | |
248 | example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc |
|
247 | example-demo.py example-gnuplot.py extension.py seteditor.py seteditor.pyc | |
249 |
|
248 | |||
250 | SLists are inherited from normal python lists, so every list method is |
|
249 | SLists are inherited from normal python lists, so every list method is | |
251 | available:: |
|
250 | available:: | |
252 |
|
251 | |||
253 | [Q:doc/examples]|21> lines.append('hey') |
|
252 | [Q:doc/examples]|21> lines.append('hey') | |
254 |
|
253 | |||
255 |
|
254 | |||
256 | Real world example: remove all files outside version control |
|
255 | Real world example: remove all files outside version control | |
257 | ============================================================ |
|
256 | ------------------------------------------------------------ | |
258 |
|
257 | |||
259 | First, capture output of "hg status":: |
|
258 | First, capture output of "hg status":: | |
260 |
|
259 | |||
261 | [Q:/ipython]|28> out = !hg status |
|
260 | [Q:/ipython]|28> out = !hg status | |
262 | == |
|
261 | == | |
263 | ['M IPython\\extensions\\ipy_kitcfg.py', |
|
262 | ['M IPython\\extensions\\ipy_kitcfg.py', | |
264 | 'M IPython\\extensions\\ipy_rehashdir.py', |
|
263 | 'M IPython\\extensions\\ipy_rehashdir.py', | |
265 | ... |
|
264 | ... | |
266 | '? build\\lib\\IPython\\Debugger.py', |
|
265 | '? build\\lib\\IPython\\Debugger.py', | |
267 | '? build\\lib\\IPython\\extensions\\InterpreterExec.py', |
|
266 | '? build\\lib\\IPython\\extensions\\InterpreterExec.py', | |
268 | '? build\\lib\\IPython\\extensions\\InterpreterPasteInput.py', |
|
267 | '? build\\lib\\IPython\\extensions\\InterpreterPasteInput.py', | |
269 | ... |
|
268 | ... | |
270 |
|
269 | |||
271 | (lines starting with ? are not under version control). |
|
270 | (lines starting with ? are not under version control). | |
272 |
|
271 | |||
273 | :: |
|
272 | :: | |
274 |
|
273 | |||
275 | [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1) |
|
274 | [Q:/ipython]|35> junk = out.grep(r'^\?').fields(1) | |
276 | [Q:/ipython]|36> junk |
|
275 | [Q:/ipython]|36> junk | |
277 | <36> SList (.p, .n, .l, .s, .grep(), .fields() availab |
|
276 | <36> SList (.p, .n, .l, .s, .grep(), .fields() availab | |
278 | ... |
|
277 | ... | |
279 | 10: build\bdist.win32\winexe\temp\_ctypes.py |
|
278 | 10: build\bdist.win32\winexe\temp\_ctypes.py | |
280 | 11: build\bdist.win32\winexe\temp\_hashlib.py |
|
279 | 11: build\bdist.win32\winexe\temp\_hashlib.py | |
281 | 12: build\bdist.win32\winexe\temp\_socket.py |
|
280 | 12: build\bdist.win32\winexe\temp\_socket.py | |
282 |
|
281 | |||
283 | Now we can just remove these files by doing 'rm $junk.s'. |
|
282 | Now we can just remove these files by doing 'rm $junk.s'. | |
284 |
|
283 | |||
285 | The .s, .n, .p properties |
|
284 | The .s, .n, .p properties | |
286 | ========================= |
|
285 | ------------------------- | |
287 |
|
286 | |||
288 |
The |
|
287 | The ``.s`` property returns one string where lines are separated by | |
289 |
single space (for convenient passing to system commands). The |
|
288 | single space (for convenient passing to system commands). The ``.n`` | |
290 |
property return one string where the lines are separated by |
|
289 | property return one string where the lines are separated by a newline | |
291 | (i.e. the original output of the function). If the items in string |
|
290 | (i.e. the original output of the function). If the items in string | |
292 |
list are file names, |
|
291 | list are file names, ``.p`` can be used to get a list of "path" objects | |
293 | for convenient file manipulation. |
|
292 | for convenient file manipulation. | |
294 |
|
293 |
General Comments 0
You need to be logged in to leave comments.
Login now