Show More
This diff has been collapsed as it changes many lines, (2523 lines changed) Show them Hide them | |||
@@ -1,5026 +1,5029 b'' | |||
|
1 | 1 | .. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008. |
|
2 | 2 | You can adapt this file completely to your liking, but it should at least |
|
3 | 3 | contain the root 'toctree' directive. |
|
4 | 4 | |
|
5 | 5 | Welcome to IPython's documentation! |
|
6 | 6 | =================================== |
|
7 | 7 | |
|
8 | 8 | Contents: |
|
9 | 9 | |
|
10 | 10 | .. toctree:: |
|
11 | 11 | :maxdepth: 2 |
|
12 | 12 | |
|
13 | 13 | Indices and tables |
|
14 | 14 | ================== |
|
15 | 15 | |
|
16 | 16 | * :ref:`genindex` |
|
17 | 17 | * :ref:`modindex` |
|
18 | 18 | * :ref:`search` |
|
19 | 19 | |
|
20 | 20 | Overview |
|
21 | 21 | ======== |
|
22 | 22 | |
|
23 | 23 | One of Python's most useful features is its interactive interpreter. |
|
24 | 24 | This system allows very fast testing of ideas without the overhead of |
|
25 | 25 | creating test files as is typical in most programming languages. |
|
26 | 26 | However, the interpreter supplied with the standard Python distribution |
|
27 | 27 | is somewhat limited for extended interactive use. |
|
28 | 28 | |
|
29 | 29 | IPython is a free software project (released under the BSD license) |
|
30 | 30 | which tries to: |
|
31 | 31 | |
|
32 | 32 | 1. Provide an interactive shell superior to Python's default. IPython |
|
33 | 33 | has many features for object introspection, system shell access, |
|
34 | 34 | and its own special command system for adding functionality when |
|
35 | 35 | working interactively. It tries to be a very efficient environment |
|
36 | 36 | both for Python code development and for exploration of problems |
|
37 | 37 | using Python objects (in situations like data analysis). |
|
38 | 38 | 2. Serve as an embeddable, ready to use interpreter for your own |
|
39 | 39 | programs. IPython can be started with a single call from inside |
|
40 | 40 | another program, providing access to the current namespace. This |
|
41 | 41 | can be very useful both for debugging purposes and for situations |
|
42 | 42 | where a blend of batch-processing and interactive exploration are |
|
43 | 43 | needed. |
|
44 | 44 | 3. Offer a flexible framework which can be used as the base |
|
45 | 45 | environment for other systems with Python as the underlying |
|
46 | 46 | language. Specifically scientific environments like Mathematica, |
|
47 | 47 | IDL and Matlab inspired its design, but similar ideas can be |
|
48 | 48 | useful in many fields. |
|
49 | 49 | 4. Allow interactive testing of threaded graphical toolkits. IPython |
|
50 | 50 | has support for interactive, non-blocking control of GTK, Qt and |
|
51 | 51 | WX applications via special threading flags. The normal Python |
|
52 | 52 | shell can only do this for Tkinter applications. |
|
53 | 53 | |
|
54 | 54 | |
|
55 | 55 | Main features |
|
56 | 56 | |
|
57 | 57 | * Dynamic object introspection. One can access docstrings, function |
|
58 | 58 | definition prototypes, source code, source files and other details |
|
59 | 59 | of any object accessible to the interpreter with a single |
|
60 | 60 | keystroke ('?', and using '??' provides additional detail). |
|
61 | 61 | * Searching through modules and namespaces with '*' wildcards, both |
|
62 | 62 | when using the '?' system and via the %psearch command. |
|
63 | 63 | * Completion in the local namespace, by typing TAB at the prompt. |
|
64 | 64 | This works for keywords, methods, variables and files in the |
|
65 | 65 | current directory. This is supported via the readline library, and |
|
66 | 66 | full access to configuring readline's behavior is provided. |
|
67 | 67 | * Numbered input/output prompts with command history (persistent |
|
68 | 68 | across sessions and tied to each profile), full searching in this |
|
69 | 69 | history and caching of all input and output. |
|
70 | 70 | * User-extensible 'magic' commands. A set of commands prefixed with |
|
71 | 71 | % is available for controlling IPython itself and provides |
|
72 | 72 | directory control, namespace information and many aliases to |
|
73 | 73 | common system shell commands. |
|
74 | 74 | * Alias facility for defining your own system aliases. |
|
75 | 75 | * Complete system shell access. Lines starting with ! are passed |
|
76 | 76 | directly to the system shell, and using !! captures shell output |
|
77 | 77 | into python variables for further use. |
|
78 | 78 | * Background execution of Python commands in a separate thread. |
|
79 | 79 | IPython has an internal job manager called jobs, and a |
|
80 | 80 | conveninence backgrounding magic function called %bg. |
|
81 | 81 | * The ability to expand python variables when calling the system |
|
82 | 82 | shell. In a shell command, any python variable prefixed with $ is |
|
83 | 83 | expanded. A double $$ allows passing a literal $ to the shell (for |
|
84 | 84 | access to shell and environment variables like $PATH). |
|
85 | 85 | * Filesystem navigation, via a magic %cd command, along with a |
|
86 | 86 | persistent bookmark system (using %bookmark) for fast access to |
|
87 | 87 | frequently visited directories. |
|
88 | 88 | * A lightweight persistence framework via the %store command, which |
|
89 | 89 | allows you to save arbitrary Python variables. These get restored |
|
90 | 90 | automatically when your session restarts. |
|
91 | 91 | * Automatic indentation (optional) of code as you type (through the |
|
92 | 92 | readline library). |
|
93 | 93 | * Macro system for quickly re-executing multiple lines of previous |
|
94 | 94 | input with a single name. Macros can be stored persistently via |
|
95 | 95 | %store and edited via %edit. |
|
96 | 96 | * Session logging (you can then later use these logs as code in your |
|
97 | 97 | programs). Logs can optionally timestamp all input, and also store |
|
98 | 98 | session output (marked as comments, so the log remains valid |
|
99 | 99 | Python source code). |
|
100 | 100 | * Session restoring: logs can be replayed to restore a previous |
|
101 | 101 | session to the state where you left it. |
|
102 | 102 | * Verbose and colored exception traceback printouts. Easier to parse |
|
103 | 103 | visually, and in verbose mode they produce a lot of useful |
|
104 | 104 | debugging information (basically a terminal version of the cgitb |
|
105 | 105 | module). |
|
106 | 106 | * Auto-parentheses: callable objects can be executed without |
|
107 | 107 | parentheses: 'sin 3' is automatically converted to 'sin(3)'. |
|
108 | 108 | * Auto-quoting: using ',' or ';' as the first character forces |
|
109 | 109 | auto-quoting of the rest of the line: ',my_function a b' becomes |
|
110 | 110 | automatically 'my_function("a","b")', while ';my_function a b' |
|
111 | 111 | becomes 'my_function("a b")'. |
|
112 | 112 | * Extensible input syntax. You can define filters that pre-process |
|
113 | 113 | user input to simplify input in special situations. This allows |
|
114 | 114 | for example pasting multi-line code fragments which start with |
|
115 | 115 | '>>>' or '...' such as those from other python sessions or the |
|
116 | 116 | standard Python documentation. |
|
117 | 117 | * Flexible configuration system. It uses a configuration file which |
|
118 | 118 | allows permanent setting of all command-line options, module |
|
119 | 119 | loading, code and file execution. The system allows recursive file |
|
120 | 120 | inclusion, so you can have a base file with defaults and layers |
|
121 | 121 | which load other customizations for particular projects. |
|
122 | 122 | * Embeddable. You can call IPython as a python shell inside your own |
|
123 | 123 | python programs. This can be used both for debugging code or for |
|
124 | 124 | providing interactive abilities to your programs with knowledge |
|
125 | 125 | about the local namespaces (very useful in debugging and data |
|
126 | 126 | analysis situations). |
|
127 | 127 | * Easy debugger access. You can set IPython to call up an enhanced |
|
128 | 128 | version of the Python debugger (pdb) every time there is an |
|
129 | 129 | uncaught exception. This drops you inside the code which triggered |
|
130 | 130 | the exception with all the data live and it is possible to |
|
131 | 131 | navigate the stack to rapidly isolate the source of a bug. The |
|
132 | 132 | %run magic command -with the -d option- can run any script under |
|
133 | 133 | pdb's control, automatically setting initial breakpoints for you. |
|
134 | 134 | This version of pdb has IPython-specific improvements, including |
|
135 | 135 | tab-completion and traceback coloring support. |
|
136 | 136 | * Profiler support. You can run single statements (similar to |
|
137 | 137 | profile.run()) or complete programs under the profiler's control. |
|
138 | 138 | While this is possible with standard cProfile or profile modules, |
|
139 | 139 | IPython wraps this functionality with magic commands (see '%prun' |
|
140 | 140 | and '%run -p') convenient for rapid interactive work. |
|
141 | 141 | * Doctest support. The special %doctest_mode command toggles a mode |
|
142 | 142 | that allows you to paste existing doctests (with leading '>>>' |
|
143 | 143 | prompts and whitespace) and uses doctest-compatible prompts and |
|
144 | 144 | output, so you can use IPython sessions as doctest code. |
|
145 | 145 | |
|
146 | 146 | |
|
147 | 147 | Portability and Python requirements |
|
148 | 148 | ----------------------------------- |
|
149 | 149 | |
|
150 | 150 | Python requirements: IPython requires with Python version 2.3 or newer. |
|
151 | 151 | If you are still using Python 2.2 and can not upgrade, the last version |
|
152 | 152 | of IPython which worked with Python 2.2 was 0.6.15, so you will have to |
|
153 | 153 | use that. |
|
154 | 154 | |
|
155 | 155 | IPython is developed under Linux, but it should work in any reasonable |
|
156 | 156 | Unix-type system (tested OK under Solaris and the BSD family, for which |
|
157 | 157 | a port exists thanks to Dryice Liu). |
|
158 | 158 | |
|
159 | 159 | Mac OS X: it works, apparently without any problems (thanks to Jim Boyle |
|
160 | 160 | at Lawrence Livermore for the information). Thanks to Andrea Riciputi, |
|
161 | 161 | Fink support is available. |
|
162 | 162 | |
|
163 | 163 | CygWin: it works mostly OK, though some users have reported problems |
|
164 | 164 | with prompt coloring. No satisfactory solution to this has been found so |
|
165 | 165 | far, you may want to disable colors permanently in the ipythonrc |
|
166 | 166 | configuration file if you experience problems. If you have proper color |
|
167 | 167 | support under cygwin, please post to the IPython mailing list so this |
|
168 | 168 | issue can be resolved for all users. |
|
169 | 169 | |
|
170 | 170 | Windows: it works well under Windows XP/2k, and I suspect NT should |
|
171 | 171 | behave similarly. Section 2.3 <node2.html#sub:Under-Windows> describes |
|
172 | 172 | installation details for Windows, including some additional tools needed |
|
173 | 173 | on this platform. |
|
174 | 174 | |
|
175 | 175 | Windows 9x support is present, and has been reported to work fine (at |
|
176 | 176 | least on WinME). |
|
177 | 177 | |
|
178 | 178 | Note, that I have very little access to and experience with Windows |
|
179 | 179 | development. However, an excellent group of Win32 users (led by Ville |
|
180 | 180 | Vainio), consistently contribute bugfixes and platform-specific |
|
181 | 181 | enhancements, so they more than make up for my deficiencies on that |
|
182 | 182 | front. In fact, Win32 users report using IPython as a system shell (see |
|
183 | 183 | Sec. 12 <node12.html#sec:IPython-as-shell> for details), as it offers a |
|
184 | 184 | level of control and features which the default cmd.exe doesn't provide. |
|
185 | 185 | |
|
186 | 186 | |
|
187 | 187 | Location |
|
188 | 188 | ======== |
|
189 | 189 | |
|
190 | 190 | IPython is generously hosted at http://ipython.scipy.org by the |
|
191 | 191 | Enthought, Inc and the SciPy project. This site offers downloads, |
|
192 | 192 | subversion access, mailing lists and a bug tracking system. I am very |
|
193 | 193 | grateful to Enthought (http://www.enthought.com) and all of the SciPy |
|
194 | 194 | team for their contribution. |
|
195 | 195 | |
|
196 | 196 | Installation |
|
197 | 197 | ============ |
|
198 | 198 | |
|
199 | 199 | Instant instructions |
|
200 | 200 | -------------------- |
|
201 | 201 | |
|
202 | 202 | If you are of the impatient kind, under Linux/Unix simply untar/unzip |
|
203 | 203 | the download, then install with 'python setup.py install'. Under |
|
204 | 204 | Windows, double-click on the provided .exe binary installer. |
|
205 | 205 | |
|
206 | 206 | Then, take a look at Sections 3 <node3.html#sec:good_config> for |
|
207 | 207 | configuring things optimally and 4 <node4.html#sec:quick_tips> for quick |
|
208 | 208 | tips on efficient use of IPython. You can later refer to the rest of the |
|
209 | 209 | manual for all the gory details. |
|
210 | 210 | |
|
211 | 211 | See the notes in sec. 2.4 <#sec:upgrade> for upgrading IPython versions. |
|
212 | 212 | |
|
213 | 213 | |
|
214 | 214 | Detailed Unix instructions (Linux, Mac OS X, etc.) |
|
215 | 215 | |
|
216 | 216 | For RPM based systems, simply install the supplied package in the usual |
|
217 | 217 | manner. If you download the tar archive, the process is: |
|
218 | 218 | |
|
219 | 219 | 1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is |
|
220 | 220 | the version number). It will make a directory called ipython-XXX. |
|
221 | 221 | Change into that directory where you will find the files README |
|
222 | 222 | and setup.py. Once you've completed the installation, you can |
|
223 | 223 | safely remove this directory. |
|
224 | 224 | 2. If you are installing over a previous installation of version |
|
225 | 225 | 0.2.0 or earlier, first remove your $HOME/.ipython directory, |
|
226 | 226 | since the configuration file format has changed somewhat (the '=' |
|
227 | 227 | were removed from all option specifications). Or you can call |
|
228 | 228 | ipython with the -upgrade option and it will do this automatically |
|
229 | 229 | for you. |
|
230 | 230 | 3. IPython uses distutils, so you can install it by simply typing at |
|
231 | 231 | the system prompt (don't type the $) |
|
232 | 232 | $ python setup.py install |
|
233 | 233 | Note that this assumes you have root access to your machine. If |
|
234 | 234 | you don't have root access or don't want IPython to go in the |
|
235 | 235 | default python directories, you'll need to use the |--home| option |
|
236 | 236 | (or |--prefix|). For example: |
|
237 | 237 | |$ python setup.py install --home $HOME/local| |
|
238 | 238 | will install IPython into $HOME/local and its subdirectories |
|
239 | 239 | (creating them if necessary). |
|
240 | 240 | You can type |
|
241 | 241 | |$ python setup.py --help| |
|
242 | 242 | for more details. |
|
243 | 243 | Note that if you change the default location for |--home| at |
|
244 | 244 | installation, IPython may end up installed at a location which is |
|
245 | 245 | not part of your $PYTHONPATH environment variable. In this case, |
|
246 | 246 | you'll need to configure this variable to include the actual |
|
247 | 247 | directory where the IPython/ directory ended (typically the value |
|
248 | 248 | you give to |--home| plus /lib/python). |
|
249 | 249 | |
|
250 | 250 | |
|
251 | 251 | Mac OSX information |
|
252 | 252 | ------------------- |
|
253 | 253 | |
|
254 | 254 | Under OSX, there is a choice you need to make. Apple ships its own build |
|
255 | 255 | of Python, which lives in the core OSX filesystem hierarchy. You can |
|
256 | 256 | also manually install a separate Python, either purely by hand |
|
257 | 257 | (typically in /usr/local) or by using Fink, which puts everything under |
|
258 | 258 | /sw. Which route to follow is a matter of personal preference, as I've |
|
259 | 259 | seen users who favor each of the approaches. Here I will simply list the |
|
260 | 260 | known installation issues under OSX, along with their solutions. |
|
261 | 261 | |
|
262 | 262 | This page: http://geosci.uchicago.edu/~tobis/pylab.html contains |
|
263 | 263 | information on this topic, with additional details on how to make |
|
264 | 264 | IPython and matplotlib play nicely under OSX. |
|
265 | 265 | |
|
266 | 266 | |
|
267 | 267 | GUI problems |
|
268 | 268 | ------------ |
|
269 | 269 | |
|
270 | 270 | The following instructions apply to an install of IPython under OSX from |
|
271 | 271 | unpacking the .tar.gz distribution and installing it for the default |
|
272 | 272 | Python interpreter shipped by Apple. If you are using a fink install, |
|
273 | 273 | fink will take care of these details for you, by installing IPython |
|
274 | 274 | against fink's Python. |
|
275 | 275 | |
|
276 | 276 | IPython offers various forms of support for interacting with graphical |
|
277 | 277 | applications from the command line, from simple Tk apps (which are in |
|
278 | 278 | principle always supported by Python) to interactive control of WX, Qt |
|
279 | 279 | and GTK apps. Under OSX, however, this requires that ipython is |
|
280 | 280 | installed by calling the special pythonw script at installation time, |
|
281 | 281 | which takes care of coordinating things with Apple's graphical environment. |
|
282 | 282 | |
|
283 | 283 | So when installing under OSX, it is best to use the following command: |
|
284 | 284 | | $ sudo pythonw setup.py install --install-scripts=/usr/local/bin| |
|
285 | 285 | or |
|
286 | 286 | | $ sudo pythonw setup.py install --install-scripts=/usr/bin| |
|
287 | 287 | depending on where you like to keep hand-installed executables. |
|
288 | 288 | |
|
289 | 289 | The resulting script will have an appropriate shebang line (the first |
|
290 | 290 | line in the script whic begins with #!...) such that the ipython |
|
291 | 291 | interpreter can interact with the OS X GUI. If the installed version |
|
292 | 292 | does not work and has a shebang line that points to, for example, just |
|
293 | 293 | /usr/bin/python, then you might have a stale, cached version in your |
|
294 | 294 | build/scripts-<python-version> directory. Delete that directory and |
|
295 | 295 | rerun the setup.py. |
|
296 | 296 | |
|
297 | 297 | It is also a good idea to use the special flag |--install-scripts| as |
|
298 | 298 | indicated above, to ensure that the ipython scripts end up in a location |
|
299 | 299 | which is part of your $PATH. Otherwise Apple's Python will put the |
|
300 | 300 | scripts in an internal directory not available by default at the command |
|
301 | 301 | line (if you use /usr/local/bin, you need to make sure this is in your |
|
302 | 302 | $PATH, which may not be true by default). |
|
303 | 303 | |
|
304 | 304 | |
|
305 | 305 | Readline problems |
|
306 | 306 | ----------------- |
|
307 | 307 | |
|
308 | 308 | By default, the Python version shipped by Apple does not include the |
|
309 | 309 | readline library, so central to IPython's behavior. If you install |
|
310 | 310 | IPython against Apple's Python, you will not have arrow keys, tab |
|
311 | 311 | completion, etc. For Mac OSX 10.3 (Panther), you can find a prebuilt |
|
312 | 312 | readline library here: |
|
313 | 313 | http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip |
|
314 | 314 | |
|
315 | 315 | If you are using OSX 10.4 (Tiger), after installing this package you |
|
316 | 316 | need to either: |
|
317 | 317 | |
|
318 | 318 | 1. move readline.so from /Library/Python/2.3 to |
|
319 | 319 | /Library/Python/2.3/site-packages, or |
|
320 | 320 | 2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip |
|
321 | 321 | |
|
322 | 322 | Users installing against Fink's Python or a properly hand-built one |
|
323 | 323 | should not have this problem. |
|
324 | 324 | |
|
325 | 325 | |
|
326 | 326 | DarwinPorts |
|
327 | 327 | ----------- |
|
328 | 328 | |
|
329 | 329 | I report here a message from an OSX user, who suggests an alternative |
|
330 | 330 | means of using IPython under this operating system with good results. |
|
331 | 331 | Please let me know of any updates that may be useful for this section. |
|
332 | 332 | His message is reproduced verbatim below: |
|
333 | 333 | |
|
334 | 334 | From: Markus Banfi <markus.banfi-AT-mospheira.net> |
|
335 | 335 | |
|
336 | 336 | As a MacOS X (10.4.2) user I prefer to install software using |
|
337 | 337 | DawinPorts instead of Fink. I had no problems installing ipython |
|
338 | 338 | with DarwinPorts. It's just: |
|
339 | 339 | |
|
340 | 340 | sudo port install py-ipython |
|
341 | 341 | |
|
342 | 342 | It automatically resolved all dependencies (python24, readline, |
|
343 | 343 | py-readline). So far I did not encounter any problems with the |
|
344 | 344 | DarwinPorts port of ipython. |
|
345 | 345 | |
|
346 | 346 | |
|
347 | 347 | |
|
348 | 348 | Windows instructions |
|
349 | 349 | -------------------- |
|
350 | 350 | |
|
351 | 351 | Some of IPython's very useful features are: |
|
352 | 352 | |
|
353 | 353 | * Integrated readline support (Tab-based file, object and attribute |
|
354 | 354 | completion, input history across sessions, editable command line, |
|
355 | 355 | etc.) |
|
356 | 356 | * Coloring of prompts, code and tracebacks. |
|
357 | 357 | |
|
358 | 358 | These, by default, are only available under Unix-like operating systems. |
|
359 | 359 | However, thanks to Gary Bishop's work, Windows XP/2k users can also |
|
360 | 360 | benefit from them. His readline library originally implemented both GNU |
|
361 | 361 | readline functionality and color support, so that IPython under Windows |
|
362 | 362 | XP/2k can be as friendly and powerful as under Unix-like environments. |
|
363 | 363 | |
|
364 | 364 | This library, now named PyReadline, has been absorbed by the IPython |
|
365 | 365 | team (Jörgen Stenarson, in particular), and it continues to be developed |
|
366 | 366 | with new features, as well as being distributed directly from the |
|
367 | 367 | IPython site. |
|
368 | 368 | |
|
369 | 369 | The PyReadline extension requires CTypes and the windows IPython |
|
370 | 370 | installer needs PyWin32, so in all you need: |
|
371 | 371 | |
|
372 | 372 | 1. PyWin32 from http://sourceforge.net/projects/pywin32. |
|
373 | 373 | 2. PyReadline for Windows from |
|
374 | 374 | http://ipython.scipy.org/moin/PyReadline/Intro. That page contains |
|
375 | 375 | further details on using and configuring the system to your liking. |
|
376 | 376 | 3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes |
|
377 | 377 | from http://starship.python.net/crew/theller/ctypes(you must use |
|
378 | 378 | version 0.9.1 or newer). This package is included in Python 2.5, |
|
379 | 379 | so you don't need to manually get it if your Python version is 2.5 |
|
380 | 380 | or newer. |
|
381 | 381 | |
|
382 | 382 | Warning about a broken readline-like library: several users have |
|
383 | 383 | reported problems stemming from using the pseudo-readline library at |
|
384 | 384 | http://newcenturycomputers.net/projects/readline.html. This is a broken |
|
385 | 385 | library which, while called readline, only implements an incomplete |
|
386 | 386 | subset of the readline API. Since it is still called readline, it fools |
|
387 | 387 | IPython's detection mechanisms and causes unpredictable crashes later. |
|
388 | 388 | If you wish to use IPython under Windows, you must NOT use this library, |
|
389 | 389 | which for all purposes is (at least as of version 1.6) terminally broken. |
|
390 | 390 | |
|
391 | 391 | |
|
392 | 392 | Installation procedure |
|
393 | 393 | ---------------------- |
|
394 | 394 | |
|
395 | 395 | Once you have the above installed, from the IPython download directory |
|
396 | 396 | grab the ipython-XXX.win32.exe file, where XXX represents the version |
|
397 | 397 | number. This is a regular windows executable installer, which you can |
|
398 | 398 | simply double-click to install. It will add an entry for IPython to your |
|
399 | 399 | Start Menu, as well as registering IPython in the Windows list of |
|
400 | 400 | applications, so you can later uninstall it from the Control Panel. |
|
401 | 401 | |
|
402 | 402 | IPython tries to install the configuration information in a directory |
|
403 | 403 | named .ipython (_ipython under Windows) located in your 'home' |
|
404 | 404 | directory. IPython sets this directory by looking for a HOME environment |
|
405 | 405 | variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH |
|
406 | 406 | (these are always defined by Windows). This typically gives something |
|
407 | 407 | like C:\Documents and Settings\YourUserName, but your local details may |
|
408 | 408 | vary. In this directory you will find all the files that configure |
|
409 | 409 | IPython's defaults, and you can put there your profiles and extensions. |
|
410 | 410 | This directory is automatically added by IPython to sys.path, so |
|
411 | 411 | anything you place there can be found by import statements. |
|
412 | 412 | |
|
413 | 413 | |
|
414 | 414 | Upgrading |
|
415 | 415 | --------- |
|
416 | 416 | |
|
417 | 417 | For an IPython upgrade, you should first uninstall the previous version. |
|
418 | 418 | This will ensure that all files and directories (such as the |
|
419 | 419 | documentation) which carry embedded version strings in their names are |
|
420 | 420 | properly removed. |
|
421 | 421 | |
|
422 | 422 | |
|
423 | 423 | Manual installation under Win32 |
|
424 | 424 | ------------------------------- |
|
425 | 425 | |
|
426 | 426 | In case the automatic installer does not work for some reason, you can |
|
427 | 427 | download the ipython-XXX.tar.gz file, which contains the full IPython |
|
428 | 428 | source distribution (the popular WinZip can read .tar.gz files). After |
|
429 | 429 | uncompressing the archive, you can install it at a command terminal just |
|
430 | 430 | like any other Python module, by using 'python setup.py install'. |
|
431 | 431 | |
|
432 | 432 | After the installation, run the supplied win32_manual_post_install.py |
|
433 | 433 | script, which creates the necessary Start Menu shortcuts for you. |
|
434 | 434 | |
|
435 | 435 | |
|
436 | 436 | |
|
437 | 437 | Upgrading from a previous version |
|
438 | 438 | --------------------------------- |
|
439 | 439 | |
|
440 | 440 | If you are upgrading from a previous version of IPython, after doing the |
|
441 | 441 | routine installation described above, you should call IPython with the |
|
442 | 442 | -upgrade option the first time you run your new copy. This will |
|
443 | 443 | automatically update your configuration directory while preserving |
|
444 | 444 | copies of your old files. You can then later merge back any personal |
|
445 | 445 | customizations you may have made into the new files. It is a good idea |
|
446 | 446 | to do this as there may be new options available in the new |
|
447 | 447 | configuration files which you will not have. |
|
448 | 448 | |
|
449 | 449 | Under Windows, if you don't know how to call python scripts with |
|
450 | 450 | arguments from a command line, simply delete the old config directory |
|
451 | 451 | and IPython will make a new one. Win2k and WinXP users will find it in |
|
452 | 452 | C:\Documents and Settings\YourUserName\_ipython, and Win 9x users under |
|
453 | 453 | C:\Program Files\IPython\_ipython. |
|
454 | 454 | |
|
455 | 455 | Initial configuration of your environment |
|
456 | 456 | ========================================= |
|
457 | 457 | |
|
458 | 458 | This section will help you set various things in your environment for |
|
459 | 459 | your IPython sessions to be as efficient as possible. All of IPython's |
|
460 | 460 | configuration information, along with several example files, is stored |
|
461 | 461 | in a directory named by default $HOME/.ipython. You can change this by |
|
462 | 462 | defining the environment variable IPYTHONDIR, or at runtime with the |
|
463 | 463 | command line option -ipythondir. |
|
464 | 464 | |
|
465 | 465 | If all goes well, the first time you run IPython it should automatically |
|
466 | 466 | create a user copy of the config directory for you, based on its builtin |
|
467 | 467 | defaults. You can look at the files it creates to learn more about |
|
468 | 468 | configuring the system. The main file you will modify to configure |
|
469 | 469 | IPython's behavior is called ipythonrc (with a .ini extension under |
|
470 | 470 | Windows), included for reference in Sec. 7.1 |
|
471 | 471 | <node7.html#sec:ipytonrc-sample>. This file is very commented and has |
|
472 | 472 | many variables you can change to suit your taste, you can find more |
|
473 | 473 | details in Sec. 7 <node7.html#sec:customization>. Here we discuss the |
|
474 | 474 | basic things you will want to make sure things are working properly from |
|
475 | 475 | the beginning. |
|
476 | 476 | |
|
477 | 477 | |
|
478 | 478 | |
|
479 | 479 | Access to the Python help system |
|
480 | 480 | -------------------------------- |
|
481 | 481 | |
|
482 | 482 | This is true for Python in general (not just for IPython): you should |
|
483 | 483 | have an environment variable called PYTHONDOCS pointing to the directory |
|
484 | 484 | where your HTML Python documentation lives. In my system it's |
|
485 | 485 | /usr/share/doc/python-docs-2.3.4/html, check your local details or ask |
|
486 | 486 | your systems administrator. |
|
487 | 487 | |
|
488 | 488 | This is the directory which holds the HTML version of the Python |
|
489 | 489 | manuals. Unfortunately it seems that different Linux distributions |
|
490 | 490 | package these files differently, so you may have to look around a bit. |
|
491 | 491 | Below I show the contents of this directory on my system for reference:: |
|
492 | 492 | |
|
493 | 493 | [html]> ls |
|
494 | 494 | about.dat acks.html dist/ ext/ index.html lib/ modindex.html |
|
495 | 495 | stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css |
|
496 | 496 | |
|
497 | 497 | You should really make sure this variable is correctly set so that |
|
498 | 498 | Python's pydoc-based help system works. It is a powerful and convenient |
|
499 | 499 | system with full access to the Python manuals and all modules accessible |
|
500 | 500 | to you. |
|
501 | 501 | |
|
502 | 502 | Under Windows it seems that pydoc finds the documentation automatically, |
|
503 | 503 | so no extra setup appears necessary. |
|
504 | 504 | |
|
505 | 505 | |
|
506 | 506 | Editor |
|
507 | 507 | ------ |
|
508 | 508 | |
|
509 | 509 | The %edit command (and its alias %ed) will invoke the editor set in your |
|
510 | 510 | environment as EDITOR. If this variable is not set, it will default to |
|
511 | 511 | vi under Linux/Unix and to notepad under Windows. You may want to set |
|
512 | 512 | this variable properly and to a lightweight editor which doesn't take |
|
513 | 513 | too long to start (that is, something other than a new instance of |
|
514 | 514 | Emacs). This way you can edit multi-line code quickly and with the power |
|
515 | 515 | of a real editor right inside IPython. |
|
516 | 516 | |
|
517 | 517 | If you are a dedicated Emacs user, you should set up the Emacs server so |
|
518 | 518 | that new requests are handled by the original process. This means that |
|
519 | 519 | almost no time is spent in handling the request (assuming an Emacs |
|
520 | 520 | process is already running). For this to work, you need to set your |
|
521 | 521 | EDITOR environment variable to 'emacsclient'. The code below, supplied |
|
522 | 522 | by Francois Pinard, can then be used in your .emacs file to enable the |
|
523 | 523 | server:: |
|
524 | 524 | |
|
525 | 525 | (defvar server-buffer-clients) |
|
526 | 526 | (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) |
|
527 | 527 | (server-start) |
|
528 | 528 | (defun fp-kill-server-with-buffer-routine () |
|
529 | 529 | (and server-buffer-clients (server-done))) |
|
530 | 530 | (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine)) |
|
531 | 531 | |
|
532 | 532 | You can also set the value of this editor via the commmand-line option |
|
533 | 533 | '-editor' or in your ipythonrc file. This is useful if you wish to use |
|
534 | 534 | specifically for IPython an editor different from your typical default |
|
535 | 535 | (and for Windows users who tend to use fewer environment variables). |
|
536 | 536 | |
|
537 | 537 | |
|
538 | 538 | Color |
|
539 | 539 | ----- |
|
540 | 540 | |
|
541 | 541 | The default IPython configuration has most bells and whistles turned on |
|
542 | 542 | (they're pretty safe). But there's one that may cause problems on some |
|
543 | 543 | systems: the use of color on screen for displaying information. This is |
|
544 | 544 | very useful, since IPython can show prompts and exception tracebacks |
|
545 | 545 | with various colors, display syntax-highlighted source code, and in |
|
546 | 546 | general make it easier to visually parse information. |
|
547 | 547 | |
|
548 | 548 | The following terminals seem to handle the color sequences fine: |
|
549 | 549 | |
|
550 | 550 | * Linux main text console, KDE Konsole, Gnome Terminal, E-term, |
|
551 | 551 | rxvt, xterm. |
|
552 | 552 | * CDE terminal (tested under Solaris). This one boldfaces light colors. |
|
553 | 553 | * (X)Emacs buffers. See sec.3.4 <#sec:emacs> for more details on |
|
554 | 554 | using IPython with (X)Emacs. |
|
555 | 555 | * A Windows (XP/2k) command prompt with Gary Bishop's support |
|
556 | 556 | extensions. Gary's extensions are discussed in Sec. 2.3 |
|
557 | 557 | <node2.html#sub:Under-Windows>. |
|
558 | 558 | * A Windows (XP/2k) CygWin shell. Although some users have reported |
|
559 | 559 | problems; it is not clear whether there is an issue for everyone |
|
560 | 560 | or only under specific configurations. If you have full color |
|
561 | 561 | support under cygwin, please post to the IPython mailing list so |
|
562 | 562 | this issue can be resolved for all users. |
|
563 | 563 | |
|
564 | 564 | These have shown problems: |
|
565 | 565 | |
|
566 | 566 | * Windows command prompt in WinXP/2k logged into a Linux machine via |
|
567 | 567 | telnet or ssh. |
|
568 | 568 | * Windows native command prompt in WinXP/2k, without Gary Bishop's |
|
569 | 569 | extensions. Once Gary's readline library is installed, the normal |
|
570 | 570 | WinXP/2k command prompt works perfectly. |
|
571 | 571 | |
|
572 | 572 | Currently the following color schemes are available: |
|
573 | 573 | |
|
574 | 574 | * NoColor: uses no color escapes at all (all escapes are empty '' '' |
|
575 | 575 | strings). This 'scheme' is thus fully safe to use in any terminal. |
|
576 | 576 | * Linux: works well in Linux console type environments: dark |
|
577 | 577 | background with light fonts. It uses bright colors for |
|
578 | 578 | information, so it is difficult to read if you have a light |
|
579 | 579 | colored background. |
|
580 | 580 | * LightBG: the basic colors are similar to those in the Linux scheme |
|
581 | 581 | but darker. It is easy to read in terminals with light backgrounds. |
|
582 | 582 | |
|
583 | 583 | IPython uses colors for two main groups of things: prompts and |
|
584 | 584 | tracebacks which are directly printed to the terminal, and the object |
|
585 | 585 | introspection system which passes large sets of data through a pager. |
|
586 | 586 | |
|
587 | 587 | |
|
588 | 588 | Input/Output prompts and exception tracebacks |
|
589 | 589 | --------------------------------------------- |
|
590 | 590 | |
|
591 | 591 | You can test whether the colored prompts and tracebacks work on your |
|
592 | 592 | system interactively by typing '%colors Linux' at the prompt (use |
|
593 | 593 | '%colors LightBG' if your terminal has a light background). If the input |
|
594 | 594 | prompt shows garbage like: |
|
595 | 595 | [0;32mIn [[1;32m1[0;32m]: [0;00m |
|
596 | 596 | instead of (in color) something like: |
|
597 | 597 | In [1]: |
|
598 | 598 | this means that your terminal doesn't properly handle color escape |
|
599 | 599 | sequences. You can go to a 'no color' mode by typing '%colors NoColor'. |
|
600 | 600 | |
|
601 | 601 | You can try using a different terminal emulator program (Emacs users, |
|
602 | 602 | see below). To permanently set your color preferences, edit the file |
|
603 | 603 | $HOME/.ipython/ipythonrc and set the colors option to the desired value. |
|
604 | 604 | |
|
605 | 605 | |
|
606 | 606 | Object details (types, docstrings, source code, etc.) |
|
607 | 607 | ----------------------------------------------------- |
|
608 | 608 | |
|
609 | 609 | IPython has a set of special functions for studying the objects you are |
|
610 | 610 | working with, discussed in detail in Sec. 6.4 |
|
611 | 611 | <node6.html#sec:dyn-object-info>. But this system relies on passing |
|
612 | 612 | information which is longer than your screen through a data pager, such |
|
613 | 613 | as the common Unix less and more programs. In order to be able to see |
|
614 | 614 | this information in color, your pager needs to be properly configured. I |
|
615 | 615 | strongly recommend using less instead of more, as it seems that more |
|
616 | 616 | simply can not understand colored text correctly. |
|
617 | 617 | |
|
618 | 618 | In order to configure less as your default pager, do the following: |
|
619 | 619 | |
|
620 | 620 | 1. Set the environment PAGER variable to less. |
|
621 | 621 | 2. Set the environment LESS variable to -r (plus any other options |
|
622 | 622 | you always want to pass to less by default). This tells less to |
|
623 | 623 | properly interpret control sequences, which is how color |
|
624 | 624 | information is given to your terminal. |
|
625 | 625 | |
|
626 | 626 | For the csh or tcsh shells, add to your ~/.cshrc file the lines:: |
|
627 | 627 | |
|
628 | 628 | setenv PAGER less |
|
629 | 629 | setenv LESS -r |
|
630 | 630 | |
|
631 | 631 | There is similar syntax for other Unix shells, look at your system |
|
632 | 632 | documentation for details. |
|
633 | 633 | |
|
634 | 634 | If you are on a system which lacks proper data pagers (such as Windows), |
|
635 | 635 | IPython will use a very limited builtin pager. |
|
636 | 636 | |
|
637 | 637 | (X)Emacs configuration |
|
638 | 638 | ---------------------- |
|
639 | 639 | |
|
640 | 640 | Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, |
|
641 | 641 | currently (X)Emacs and IPython get along very well. |
|
642 | 642 | |
|
643 | 643 | Important note: You will need to use a recent enough version of |
|
644 | 644 | python-mode.el, along with the file ipython.el. You can check that the |
|
645 | 645 | version you have of python-mode.el is new enough by either looking at |
|
646 | 646 | the revision number in the file itself, or asking for it in (X)Emacs via |
|
647 | 647 | M-x py-version. Versions 4.68 and newer contain the necessary fixes for |
|
648 | 648 | proper IPython support. |
|
649 | 649 | |
|
650 | 650 | The file ipython.el is included with the IPython distribution, in the |
|
651 | 651 | documentation directory (where this manual resides in PDF and HTML |
|
652 | 652 | formats). |
|
653 | 653 | |
|
654 | 654 | Once you put these files in your Emacs path, all you need in your .emacs |
|
655 | 655 | file is:: |
|
656 | 656 | |
|
657 | 657 | (require 'ipython) |
|
658 | 658 | |
|
659 | 659 | This should give you full support for executing code snippets via |
|
660 | 660 | IPython, opening IPython as your Python shell via C-c !, etc. |
|
661 | 661 | |
|
662 | 662 | If you happen to get garbage instead of colored prompts as described in |
|
663 | 663 | the previous section, you may need to set also in your .emacs file:: |
|
664 | 664 | |
|
665 | 665 | (setq ansi-color-for-comint-mode t) |
|
666 | 666 | |
|
667 | 667 | |
|
668 | 668 | Notes:: |
|
669 | 669 | |
|
670 | 670 | * There is one caveat you should be aware of: you must start the |
|
671 | 671 | IPython shell before attempting to execute any code regions via |
|
672 | 672 | C-c |. Simply type C-c ! to start IPython before passing any code |
|
673 | 673 | regions to the interpreter, and you shouldn't experience any |
|
674 | 674 | problems. |
|
675 | 675 | This is due to a bug in Python itself, which has been fixed for |
|
676 | 676 | Python 2.3, but exists as of Python 2.2.2 (reported as SF bug [ |
|
677 | 677 | 737947 ]). |
|
678 | 678 | * The (X)Emacs support is maintained by Alexander Schmolck, so all |
|
679 | 679 | comments/requests should be directed to him through the IPython |
|
680 | 680 | mailing lists. |
|
681 | 681 | * This code is still somewhat experimental so it's a bit rough |
|
682 | 682 | around the edges (although in practice, it works quite well). |
|
683 | 683 | * Be aware that if you customize py-python-command previously, this |
|
684 | 684 | value will override what ipython.el does (because loading the |
|
685 | 685 | customization variables comes later). |
|
686 | 686 | |
|
687 | 687 | Quick tips |
|
688 | 688 | ========== |
|
689 | 689 | |
|
690 | 690 | IPython can be used as an improved replacement for the Python prompt, |
|
691 | 691 | and for that you don't really need to read any more of this manual. But |
|
692 | 692 | in this section we'll try to summarize a few tips on how to make the |
|
693 | 693 | most effective use of it for everyday Python development, highlighting |
|
694 | 694 | things you might miss in the rest of the manual (which is getting long). |
|
695 | 695 | We'll give references to parts in the manual which provide more detail |
|
696 | 696 | when appropriate. |
|
697 | 697 | |
|
698 | 698 | The following article by Jeremy Jones provides an introductory tutorial |
|
699 | 699 | about IPython: |
|
700 | 700 | http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html |
|
701 | 701 | |
|
702 | 702 | * The TAB key. TAB-completion, especially for attributes, is a |
|
703 | 703 | convenient way to explore the structure of any object you're |
|
704 | 704 | dealing with. Simply type object_name.<TAB> and a list of the |
|
705 | 705 | object's attributes will be printed (see sec. 6.5 |
|
706 | 706 | <node6.html#sec:readline> for more). Tab completion also works on |
|
707 | 707 | file and directory names, which combined with IPython's alias |
|
708 | 708 | system allows you to do from within IPython many of the things you |
|
709 | 709 | normally would need the system shell for. |
|
710 | 710 | * Explore your objects. Typing object_name? will print all sorts of |
|
711 | 711 | details about any object, including docstrings, function |
|
712 | 712 | definition lines (for call arguments) and constructor details for |
|
713 | 713 | classes. The magic commands %pdoc, %pdef, %psource and %pfile will |
|
714 | 714 | respectively print the docstring, function definition line, full |
|
715 | 715 | source code and the complete file for any object (when they can be |
|
716 | 716 | found). If automagic is on (it is by default), you don't need to |
|
717 | 717 | type the '%' explicitly. See sec. 6.4 |
|
718 | 718 | <node6.html#sec:dyn-object-info> for more. |
|
719 | 719 | * The %run magic command allows you to run any python script and |
|
720 | 720 | load all of its data directly into the interactive namespace. |
|
721 | 721 | Since the file is re-read from disk each time, changes you make to |
|
722 | 722 | it are reflected immediately (in contrast to the behavior of |
|
723 | 723 | import). I rarely use import for code I am testing, relying on |
|
724 | 724 | %run instead. See sec. 6.2 <node6.html#sec:magic> for more on this |
|
725 | 725 | and other magic commands, or type the name of any magic command |
|
726 | 726 | and ? to get details on it. See also sec. 6.9 |
|
727 | 727 | <node6.html#sec:dreload> for a recursive reload command. |
|
728 | 728 | %run also has special flags for timing the execution of your |
|
729 | 729 | scripts (-t) and for executing them under the control of either |
|
730 | 730 | Python's pdb debugger (-d) or profiler (-p). With all of these, |
|
731 | 731 | %run can be used as the main tool for efficient interactive |
|
732 | 732 | development of code which you write in your editor of choice. |
|
733 | 733 | * Use the Python debugger, pdb^2 <footnode.html#foot360>. The %pdb |
|
734 | 734 | command allows you to toggle on and off the automatic invocation |
|
735 | 735 | of an IPython-enhanced pdb debugger (with coloring, tab completion |
|
736 | 736 | and more) at any uncaught exception. The advantage of this is that |
|
737 | 737 | pdb starts inside the function where the exception occurred, with |
|
738 | 738 | all data still available. You can print variables, see code, |
|
739 | 739 | execute statements and even walk up and down the call stack to |
|
740 | 740 | track down the true source of the problem (which often is many |
|
741 | 741 | layers in the stack above where the exception gets triggered). |
|
742 | 742 | Running programs with %run and pdb active can be an efficient to |
|
743 | 743 | develop and debug code, in many cases eliminating the need for |
|
744 | 744 | print statements or external debugging tools. I often simply put a |
|
745 | 745 | 1/0 in a place where I want to take a look so that pdb gets |
|
746 | 746 | called, quickly view whatever variables I need to or test various |
|
747 | 747 | pieces of code and then remove the 1/0. |
|
748 | 748 | Note also that '%run -d' activates pdb and automatically sets |
|
749 | 749 | initial breakpoints for you to step through your code, watch |
|
750 | 750 | variables, etc. See Sec. 6.12 <node6.html#sec:cache_output> for |
|
751 | 751 | details. |
|
752 | 752 | * Use the output cache. All output results are automatically stored |
|
753 | 753 | in a global dictionary named Out and variables named _1, _2, etc. |
|
754 | 754 | alias them. For example, the result of input line 4 is available |
|
755 | 755 | either as Out[4] or as _4. Additionally, three variables named _, |
|
756 | 756 | __ and ___ are always kept updated with the for the last three |
|
757 | 757 | results. This allows you to recall any previous result and further |
|
758 | 758 | use it for new calculations. See Sec. 6.12 |
|
759 | 759 | <node6.html#sec:cache_output> for more. |
|
760 | 760 | * Put a ';' at the end of a line to supress the printing of output. |
|
761 | 761 | This is useful when doing calculations which generate long output |
|
762 | 762 | you are not interested in seeing. The _* variables and the Out[] |
|
763 | 763 | list do get updated with the contents of the output, even if it is |
|
764 | 764 | not printed. You can thus still access the generated results this |
|
765 | 765 | way for further processing. |
|
766 | 766 | * A similar system exists for caching input. All input is stored in |
|
767 | 767 | a global list called In , so you can re-execute lines 22 through |
|
768 | 768 | 28 plus line 34 by typing 'exec In[22:29]+In[34]' (using Python |
|
769 | 769 | slicing notation). If you need to execute the same set of lines |
|
770 | 770 | often, you can assign them to a macro with the %macro function. |
|
771 | 771 | See sec. 6.11 <node6.html#sec:cache_input> for more. |
|
772 | 772 | * Use your input history. The %hist command can show you all |
|
773 | 773 | previous input, without line numbers if desired (option -n) so you |
|
774 | 774 | can directly copy and paste code either back in IPython or in a |
|
775 | 775 | text editor. You can also save all your history by turning on |
|
776 | 776 | logging via %logstart; these logs can later be either reloaded as |
|
777 | 777 | IPython sessions or used as code for your programs. |
|
778 | 778 | * Define your own system aliases. Even though IPython gives you |
|
779 | 779 | access to your system shell via the ! prefix, it is convenient to |
|
780 | 780 | have aliases to the system commands you use most often. This |
|
781 | 781 | allows you to work seamlessly from inside IPython with the same |
|
782 | 782 | commands you are used to in your system shell. |
|
783 | 783 | IPython comes with some pre-defined aliases and a complete system |
|
784 | 784 | for changing directories, both via a stack (see %pushd, %popd and |
|
785 | 785 | %dhist) and via direct %cd. The latter keeps a history of visited |
|
786 | 786 | directories and allows you to go to any previously visited one. |
|
787 | 787 | * Use Python to manipulate the results of system commands. The '!!' |
|
788 | 788 | special syntax, and the %sc and %sx magic commands allow you to |
|
789 | 789 | capture system output into Python variables. |
|
790 | 790 | * Expand python variables when calling the shell (either via '!' and |
|
791 | 791 | '!!' or via aliases) by prepending a $ in front of them. You can |
|
792 | 792 | also expand complete python expressions. See sec. 6.7 |
|
793 | 793 | <node6.html#sub:System-shell-access> for more. |
|
794 | 794 | * Use profiles to maintain different configurations (modules to |
|
795 | 795 | load, function definitions, option settings) for particular tasks. |
|
796 | 796 | You can then have customized versions of IPython for specific |
|
797 | 797 | purposes. See sec. 7.3 <node7.html#sec:profiles> for more. |
|
798 | 798 | * Embed IPython in your programs. A few lines of code are enough to |
|
799 | 799 | load a complete IPython inside your own programs, giving you the |
|
800 | 800 | ability to work with your data interactively after automatic |
|
801 | 801 | processing has been completed. See sec. 9 <node9.html#sec:embed> |
|
802 | 802 | for more. |
|
803 | 803 | * Use the Python profiler. When dealing with performance issues, the |
|
804 | 804 | %run command with a -p option allows you to run complete programs |
|
805 | 805 | under the control of the Python profiler. The %prun command does a |
|
806 | 806 | similar job for single Python expressions (like function calls). |
|
807 | 807 | * Use the IPython.demo.Demo class to load any Python script as an |
|
808 | 808 | interactive demo. With a minimal amount of simple markup, you can |
|
809 | 809 | control the execution of the script, stopping as needed. See |
|
810 | 810 | sec. 14 <node14.html#sec:interactive-demos> for more. |
|
811 | 811 | * Run your doctests from within IPython for development and |
|
812 | 812 | debugging. The special %doctest_mode command toggles a mode where |
|
813 | 813 | the prompt, output and exceptions display matches as closely as |
|
814 | 814 | possible that of the default Python interpreter. In addition, this |
|
815 | 815 | mode allows you to directly paste in code that contains leading |
|
816 | 816 | '>>>' prompts, even if they have extra leading whitespace (as is |
|
817 | 817 | common in doctest files). This combined with the '%history -tn' |
|
818 | 818 | call to see your translated history (with these extra prompts |
|
819 | 819 | removed and no line numbers) allows for an easy doctest workflow, |
|
820 | 820 | where you can go from doctest to interactive execution to pasting |
|
821 | 821 | into valid Python code as needed. |
|
822 | 822 | |
|
823 | 823 | |
|
824 | 824 | Source code handling tips |
|
825 | 825 | ------------------------- |
|
826 | 826 | |
|
827 | 827 | IPython is a line-oriented program, without full control of the |
|
828 | 828 | terminal. Therefore, it doesn't support true multiline editing. However, |
|
829 | 829 | it has a number of useful tools to help you in dealing effectively with |
|
830 | 830 | more complex editing. |
|
831 | 831 | |
|
832 | 832 | The %edit command gives a reasonable approximation of multiline editing, |
|
833 | 833 | by invoking your favorite editor on the spot. IPython will execute the |
|
834 | 834 | code you type in there as if it were typed interactively. Type %edit? |
|
835 | 835 | for the full details on the edit command. |
|
836 | 836 | |
|
837 | 837 | If you have typed various commands during a session, which you'd like to |
|
838 | 838 | reuse, IPython provides you with a number of tools. Start by using %hist |
|
839 | 839 | to see your input history, so you can see the line numbers of all input. |
|
840 | 840 | Let us say that you'd like to reuse lines 10 through 20, plus lines 24 |
|
841 | 841 | and 28. All the commands below can operate on these with the syntax:: |
|
842 | 842 | |
|
843 | 843 | %command 10-20 24 28 |
|
844 | 844 | |
|
845 | 845 | where the command given can be: |
|
846 | 846 | |
|
847 | 847 | * %macro <macroname>: this stores the lines into a variable which, |
|
848 | 848 | when called at the prompt, re-executes the input. Macros can be |
|
849 | 849 | edited later using '%edit macroname', and they can be stored |
|
850 | 850 | persistently across sessions with '%store macroname' (the storage |
|
851 | 851 | system is per-profile). The combination of quick macros, |
|
852 | 852 | persistent storage and editing, allows you to easily refine |
|
853 | 853 | quick-and-dirty interactive input into permanent utilities, always |
|
854 | 854 | available both in IPython and as files for general reuse. |
|
855 | 855 | * %edit: this will open a text editor with those lines pre-loaded |
|
856 | 856 | for further modification. It will then execute the resulting |
|
857 | 857 | file's contents as if you had typed it at the prompt. |
|
858 | 858 | * %save <filename>: this saves the lines directly to a named file on |
|
859 | 859 | disk. |
|
860 | 860 | |
|
861 | 861 | While %macro saves input lines into memory for interactive re-execution, |
|
862 | 862 | sometimes you'd like to save your input directly to a file. The %save |
|
863 | 863 | magic does this: its input sytnax is the same as %macro, but it saves |
|
864 | 864 | your input directly to a Python file. Note that the %logstart command |
|
865 | 865 | also saves input, but it logs all input to disk (though you can |
|
866 | 866 | temporarily suspend it and reactivate it with %logoff/%logon); %save |
|
867 | 867 | allows you to select which lines of input you need to save. |
|
868 | 868 | |
|
869 | 869 | |
|
870 | 870 | Lightweight 'version control' |
|
871 | 871 | ----------------------------- |
|
872 | 872 | |
|
873 | 873 | When you call %edit with no arguments, IPython opens an empty editor |
|
874 | 874 | with a temporary file, and it returns the contents of your editing |
|
875 | 875 | session as a string variable. Thanks to IPython's output caching |
|
876 | 876 | mechanism, this is automatically stored:: |
|
877 | 877 | |
|
878 | 878 | In [1]: %edit |
|
879 | 879 | |
|
880 | 880 | IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py |
|
881 | 881 | |
|
882 | 882 | Editing... done. Executing edited code... |
|
883 | 883 | |
|
884 | 884 | hello - this is a temporary file |
|
885 | 885 | |
|
886 | 886 | Out[1]: "print 'hello - this is a temporary file'\n" |
|
887 | 887 | |
|
888 | 888 | Now, if you call '%edit -p', IPython tries to open an editor with the |
|
889 | 889 | same data as the last time you used %edit. So if you haven't used %edit |
|
890 | 890 | in the meantime, this same contents will reopen; however, it will be |
|
891 | 891 | done in a new file. This means that if you make changes and you later |
|
892 | 892 | want to find an old version, you can always retrieve it by using its |
|
893 | 893 | output number, via '%edit _NN', where NN is the number of the output |
|
894 | 894 | prompt. |
|
895 | 895 | |
|
896 | 896 | Continuing with the example above, this should illustrate this idea:: |
|
897 | 897 | |
|
898 | 898 | In [2]: edit -p |
|
899 | 899 | |
|
900 | 900 | IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py |
|
901 | 901 | |
|
902 | 902 | Editing... done. Executing edited code... |
|
903 | 903 | |
|
904 | 904 | hello - now I made some changes |
|
905 | 905 | |
|
906 | 906 | Out[2]: "print 'hello - now I made some changes'\n" |
|
907 | 907 | |
|
908 | 908 | In [3]: edit _1 |
|
909 | 909 | |
|
910 | 910 | IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py |
|
911 | 911 | |
|
912 | 912 | Editing... done. Executing edited code... |
|
913 | 913 | |
|
914 | 914 | hello - this is a temporary file |
|
915 | 915 | |
|
916 | 916 | IPython version control at work :) |
|
917 | 917 | |
|
918 | 918 | Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n" |
|
919 | 919 | |
|
920 | 920 | |
|
921 | 921 | This section was written after a contribution by Alexander Belchenko on |
|
922 | 922 | the IPython user list. |
|
923 | 923 | |
|
924 | 924 | |
|
925 | 925 | Effective logging |
|
926 | 926 | ----------------- |
|
927 | 927 | |
|
928 | 928 | A very useful suggestion sent in by Robert Kern follows: |
|
929 | 929 | |
|
930 | 930 | I recently happened on a nifty way to keep tidy per-project log files. I |
|
931 | 931 | made a profile for my project (which is called "parkfield"). |
|
932 | 932 | |
|
933 | 933 | include ipythonrc |
|
934 | 934 | |
|
935 | 935 | # cancel earlier logfile invocation: |
|
936 | 936 | |
|
937 | 937 | logfile '' |
|
938 | 938 | |
|
939 | 939 | execute import time |
|
940 | 940 | |
|
941 | 941 | execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate' |
|
942 | 942 | |
|
943 | 943 | execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d')) |
|
944 | 944 | |
|
945 | 945 | I also added a shell alias for convenience: |
|
946 | 946 | |
|
947 | 947 | alias parkfield="ipython -pylab -profile parkfield" |
|
948 | 948 | |
|
949 | 949 | Now I have a nice little directory with everything I ever type in, |
|
950 | 950 | organized by project and date. |
|
951 | 951 | |
|
952 | 952 | Contribute your own: If you have your own favorite tip on using IPython |
|
953 | 953 | efficiently for a certain task (especially things which can't be done in |
|
954 | 954 | the normal Python interpreter), don't hesitate to send it! |
|
955 | 955 | |
|
956 | 956 | Command-line use |
|
957 | 957 | ================ |
|
958 | 958 | |
|
959 | 959 | You start IPython with the command:: |
|
960 | 960 | |
|
961 | 961 | $ ipython [options] files |
|
962 | 962 | |
|
963 | 963 | If invoked with no options, it executes all the files listed in sequence |
|
964 | 964 | and drops you into the interpreter while still acknowledging any options |
|
965 | 965 | you may have set in your ipythonrc file. This behavior is different from |
|
966 | 966 | standard Python, which when called as python -i will only execute one |
|
967 | 967 | file and ignore your configuration setup. |
|
968 | 968 | |
|
969 | 969 | Please note that some of the configuration options are not available at |
|
970 | 970 | the command line, simply because they are not practical here. Look into |
|
971 | 971 | your ipythonrc configuration file for details on those. This file |
|
972 | 972 | typically installed in the $HOME/.ipython directory. For Windows users, |
|
973 | 973 | $HOME resolves to C:\\Documents and Settings\\YourUserName in most |
|
974 | 974 | instances. In the rest of this text, we will refer to this directory as |
|
975 | 975 | IPYTHONDIR. |
|
976 | 976 | |
|
977 | 977 | |
|
978 | 978 | Special Threading Options |
|
979 | 979 | |
|
980 | 980 | The following special options are ONLY valid at the beginning of the |
|
981 | 981 | command line, and not later. This is because they control the initial- |
|
982 | 982 | ization of ipython itself, before the normal option-handling mechanism |
|
983 | 983 | is active. |
|
984 | 984 | |
|
985 | 985 | * [-gthread, -qthread, -q4thread, -wthread, -pylab:] Only one of |
|
986 | 986 | these can be given, and it can only be given as the first option |
|
987 | 987 | passed to IPython (it will have no effect in any other position). |
|
988 | 988 | They provide threading support for the GTK, Qt (versions 3 and 4) |
|
989 | 989 | and WXPython toolkits, and for the matplotlib library. |
|
990 | 990 | * [ ] With any of the first four options, IPython starts running a |
|
991 | 991 | separate thread for the graphical toolkit's operation, so that you |
|
992 | 992 | can open and control graphical elements from within an IPython |
|
993 | 993 | command line, without blocking. All four provide essentially the |
|
994 | 994 | same functionality, respectively for GTK, Qt3, Qt4 and WXWidgets |
|
995 | 995 | (via their Python interfaces). |
|
996 | 996 | * [ ] Note that with -wthread, you can additionally use the |
|
997 | 997 | -wxversion option to request a specific version of wx to be used. |
|
998 | 998 | This requires that you have the wxversion Python module installed, |
|
999 | 999 | which is part of recent wxPython distributions. |
|
1000 | 1000 | * [ ] If -pylab is given, IPython loads special support for the mat |
|
1001 | 1001 | plotlib library (http://matplotlib.sourceforge.net), allowing |
|
1002 | 1002 | interactive usage of any of its backends as defined in the user's |
|
1003 | 1003 | ~/.matplotlib/matplotlibrc file. It automatically activates GTK, |
|
1004 | 1004 | Qt or WX threading for IPyhton if the choice of matplotlib backend |
|
1005 | 1005 | requires it. It also modifies the %run command to correctly |
|
1006 | 1006 | execute (without blocking) any matplotlib-based script which calls |
|
1007 | 1007 | show() at the end. |
|
1008 | 1008 | * [-tk] The -g/q/q4/wthread options, and -pylab (if matplotlib is |
|
1009 | 1009 | configured to use GTK, Qt3, Qt4 or WX), will normally block Tk |
|
1010 | 1010 | graphical interfaces. This means that when either GTK, Qt or WX |
|
1011 | 1011 | threading is active, any attempt to open a Tk GUI will result in a |
|
1012 | 1012 | dead window, and possibly cause the Python interpreter to crash. |
|
1013 | 1013 | An extra option, -tk, is available to address this issue. It can |
|
1014 | 1014 | only be given as a second option after any of the above (-gthread, |
|
1015 | 1015 | -wthread or -pylab). |
|
1016 | 1016 | * [ ] If -tk is given, IPython will try to coordinate Tk threading |
|
1017 | 1017 | with GTK, Qt or WX. This is however potentially unreliable, and |
|
1018 | 1018 | you will have to test on your platform and Python configuration to |
|
1019 | 1019 | determine whether it works for you. Debian users have reported |
|
1020 | 1020 | success, apparently due to the fact that Debian builds all of Tcl, |
|
1021 | 1021 | Tk, Tkinter and Python with pthreads support. Under other Linux |
|
1022 | 1022 | environments (such as Fedora Core 2/3), this option has caused |
|
1023 | 1023 | random crashes and lockups of the Python interpreter. Under other |
|
1024 | 1024 | operating systems (Mac OSX and Windows), you'll need to try it to |
|
1025 | 1025 | find out, since currently no user reports are available. |
|
1026 | 1026 | * [ ] There is unfortunately no way for IPython to determine at run |
|
1027 | 1027 | time whether -tk will work reliably or not, so you will need to do |
|
1028 | 1028 | some experiments before relying on it for regular work. |
|
1029 | 1029 | |
|
1030 | 1030 | |
|
1031 | 1031 | |
|
1032 | 1032 | Regular Options |
|
1033 | 1033 | --------------- |
|
1034 | 1034 | |
|
1035 | 1035 | After the above threading options have been given, regular options can |
|
1036 | 1036 | follow in any order. All options can be abbreviated to their shortest |
|
1037 | 1037 | non-ambiguous form and are case-sensitive. One or two dashes can be |
|
1038 | used. Some options have an alternate short form, indicated after a |. | |
|
1038 | used. Some options have an alternate short form, indicated after a ``|``. | |
|
1039 | 1039 | |
|
1040 | 1040 | Most options can also be set from your ipythonrc configuration file. See |
|
1041 | 1041 | the provided example for more details on what the options do. Options |
|
1042 | 1042 | given at the command line override the values set in the ipythonrc file. |
|
1043 | 1043 | |
|
1044 | 1044 | All options with a [no] prepended can be specified in negated form |
|
1045 | 1045 | (-nooption instead of -option) to turn the feature off. |
|
1046 | 1046 | |
|
1047 | 1047 | * [-help:] print a help message and exit. |
|
1048 | 1048 | * [-pylab:] this can only be given as the first option passed to |
|
1049 | 1049 | IPython (it will have no effect in any other position). It adds |
|
1050 | 1050 | special support for the matplotlib library |
|
1051 | 1051 | (http://matplotlib.sourceforge.net |
|
1052 | 1052 | http://matplotlib.sourceforge.net), allowing interactive usage of |
|
1053 | 1053 | any of its backends as defined in the user's .matplotlibrc file. |
|
1054 | 1054 | It automatically activates GTK or WX threading for IPyhton if the |
|
1055 | 1055 | choice of matplotlib backend requires it. It also modifies the |
|
1056 | 1056 | %run command to correctly execute (without blocking) any |
|
1057 | 1057 | matplotlib-based script which calls show() at the end. See Sec. 15 |
|
1058 | 1058 | <node15.html#sec:matplotlib-support> for more details. |
|
1059 | 1059 | * [-autocall] <val>: Make IPython automatically call any callable |
|
1060 | 1060 | object even if you didn't type explicit parentheses. For example, |
|
1061 | 1061 | 'str 43' becomes 'str(43)' automatically. The value can be '0' to |
|
1062 | 1062 | disable the feature, '1' for smart autocall, where it is not |
|
1063 | 1063 | applied if there are no more arguments on the line, and '2' for |
|
1064 | 1064 | full autocall, where all callable objects are automatically called |
|
1065 | 1065 | (even if no arguments are present). The default is '1'. |
|
1066 | 1066 | * [-[no]autoindent:] Turn automatic indentation on/off. |
|
1067 | 1067 | * [-[no]automagic:] make magic commands automatic (without needing |
|
1068 | 1068 | their first character to be %). Type %magic at the IPython prompt |
|
1069 | 1069 | for more information. |
|
1070 | 1070 | * [-[no]autoedit_syntax:] When a syntax error occurs after editing a |
|
1071 | 1071 | file, automatically open the file to the trouble causing line for |
|
1072 | 1072 | convenient fixing. |
|
1073 | 1073 | * [-[no]banner:] Print the initial information banner (default on). |
|
1074 | 1074 | * [-c <command>:] execute the given command string, and set sys.argv |
|
1075 | 1075 | to ['c']. This is similar to the -c option in the normal Python |
|
1076 | 1076 | interpreter. |
|
1077 | 1077 | * [-cache_size|cs <n>:] size of the output cache (maximum number of |
|
1078 | 1078 | entries to hold in memory). The default is 1000, you can change it |
|
1079 | 1079 | permanently in your config file. Setting it to 0 completely |
|
1080 | 1080 | disables the caching system, and the minimum value accepted is 20 |
|
1081 | 1081 | (if you provide a value less than 20, it is reset to 0 and a |
|
1082 | 1082 | warning is issued) This limit is defined because otherwise you'll |
|
1083 | 1083 | spend more time re-flushing a too small cache than working. |
|
1084 | 1084 | * [-classic|cl:] Gives IPython a similar feel to the classic Python |
|
1085 | 1085 | prompt. |
|
1086 | 1086 | * [-colors <scheme>:] Color scheme for prompts and exception |
|
1087 | 1087 | reporting. Currently implemented: NoColor, Linux and LightBG. |
|
1088 | 1088 | * [-[no]color_info:] IPython can display information about objects |
|
1089 | 1089 | via a set of functions, and optionally can use colors for this, |
|
1090 | 1090 | syntax highlighting source code and various other elements. |
|
1091 | 1091 | However, because this information is passed through a pager (like |
|
1092 | 1092 | 'less') and many pagers get confused with color codes, this option |
|
1093 | 1093 | is off by default. You can test it and turn it on permanently in |
|
1094 | 1094 | your ipythonrc file if it works for you. As a reference, the |
|
1095 | 1095 | 'less' pager supplied with Mandrake 8.2 works ok, but that in |
|
1096 | 1096 | RedHat 7.2 doesn't. |
|
1097 | 1097 | * [ ] Test it and turn it on permanently if it works with your |
|
1098 | 1098 | system. The magic function %color_info allows you to toggle this |
|
1099 | 1099 | interactively for testing. |
|
1100 | 1100 | * [-[no]debug:] Show information about the loading process. Very |
|
1101 | 1101 | useful to pin down problems with your configuration files or to |
|
1102 | 1102 | get details about session restores. |
|
1103 | 1103 | * [-[no]deep_reload:] IPython can use the deep_reload module which |
|
1104 | 1104 | reloads changes in modules recursively (it replaces the reload() |
|
1105 | 1105 | function, so you don't need to change anything to use it). |
|
1106 | 1106 | deep_reload() forces a full reload of modules whose code may have |
|
1107 | 1107 | changed, which the default reload() function does not. |
|
1108 | 1108 | * [ ] When deep_reload is off, IPython will use the normal reload(), |
|
1109 | 1109 | but deep_reload will still be available as dreload(). This feature |
|
1110 | 1110 | is off by default [which means that you have both normal reload() |
|
1111 | 1111 | and dreload()]. |
|
1112 | 1112 | * [-editor <name>:] Which editor to use with the %edit command. By |
|
1113 | 1113 | default, IPython will honor your EDITOR environment variable (if |
|
1114 | 1114 | not set, vi is the Unix default and notepad the Windows one). |
|
1115 | 1115 | Since this editor is invoked on the fly by IPython and is meant |
|
1116 | 1116 | for editing small code snippets, you may want to use a small, |
|
1117 | 1117 | lightweight editor here (in case your default EDITOR is something |
|
1118 | 1118 | like Emacs). |
|
1119 | 1119 | * [-ipythondir <name>:] name of your IPython configuration directory |
|
1120 | 1120 | IPYTHONDIR. This can also be specified through the environment |
|
1121 | 1121 | variable IPYTHONDIR. |
|
1122 | 1122 | * [-log|l:] generate a log file of all input. The file is named |
|
1123 | 1123 | ipython_log.py in your current directory (which prevents logs from |
|
1124 | 1124 | multiple IPython sessions from trampling each other). You can use |
|
1125 | 1125 | this to later restore a session by loading your logfile as a file |
|
1126 | 1126 | to be executed with option -logplay (see below). |
|
1127 | 1127 | * [-logfile|lf <name>:] specify the name of your logfile. |
|
1128 | 1128 | * [-logplay|lp <name>:] you can replay a previous log. For restoring |
|
1129 | 1129 | a session as close as possible to the state you left it in, use |
|
1130 | 1130 | this option (don't just run the logfile). With -logplay, IPython |
|
1131 | 1131 | will try to reconstruct the previous working environment in full, |
|
1132 | 1132 | not just execute the commands in the logfile. |
|
1133 | 1133 | * [ ] When a session is restored, logging is automatically turned on |
|
1134 | 1134 | again with the name of the logfile it was invoked with (it is read |
|
1135 | 1135 | from the log header). So once you've turned logging on for a |
|
1136 | 1136 | session, you can quit IPython and reload it as many times as you |
|
1137 | 1137 | want and it will continue to log its history and restore from the |
|
1138 | 1138 | beginning every time. |
|
1139 | 1139 | * [ ] Caveats: there are limitations in this option. The history |
|
1140 | 1140 | variables _i*,_* and _dh don't get restored properly. In the |
|
1141 | 1141 | future we will try to implement full session saving by writing and |
|
1142 | 1142 | retrieving a 'snapshot' of the memory state of IPython. But our |
|
1143 | 1143 | first attempts failed because of inherent limitations of Python's |
|
1144 | 1144 | Pickle module, so this may have to wait. |
|
1145 | 1145 | * [-[no]messages:] Print messages which IPython collects about its |
|
1146 | 1146 | startup process (default on). |
|
1147 | 1147 | * [-[no]pdb:] Automatically call the pdb debugger after every |
|
1148 | 1148 | uncaught exception. If you are used to debugging using pdb, this |
|
1149 | 1149 | puts you automatically inside of it after any call (either in |
|
1150 | 1150 | IPython or in code called by it) which triggers an exception which |
|
1151 | 1151 | goes uncaught. |
|
1152 | 1152 | * [-[no]pprint:] ipython can optionally use the pprint (pretty |
|
1153 | 1153 | printer) module for displaying results. pprint tends to give a |
|
1154 | 1154 | nicer display of nested data structures. If you like it, you can |
|
1155 | 1155 | turn it on permanently in your config file (default off). |
|
1156 | 1156 | * [-profile|p] <name>: assume that your config file is |
|
1157 | 1157 | ipythonrc-<name> (looks in current dir first, then in IPYTHONDIR). |
|
1158 | 1158 | This is a quick way to keep and load multiple config files for |
|
1159 | 1159 | different tasks, especially if you use the include option of |
|
1160 | 1160 | config files. You can keep a basic IPYTHONDIR/ipythonrc file and |
|
1161 | 1161 | then have other 'profiles' which include this one and load extra |
|
1162 | 1162 | things for particular tasks. For example: |
|
1163 | 1163 | * [ ] 1. $HOME/.ipython/ipythonrc : load basic things you always want. |
|
1164 | 1164 | * [ ] 2. $HOME/.ipython/ipythonrc-math : load (1) and basic |
|
1165 | 1165 | math-related modules. |
|
1166 | 1166 | * [ ] 3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and |
|
1167 | 1167 | plotting modules. |
|
1168 | 1168 | * [ ] Since it is possible to create an endless loop by having |
|
1169 | 1169 | circular file inclusions, IPython will stop if it reaches 15 |
|
1170 | 1170 | recursive inclusions. |
|
1171 | 1171 | * [-prompt_in1|pi1 <string>:] Specify the string used for input |
|
1172 | 1172 | prompts. Note that if you are using numbered prompts, the number |
|
1173 | 1173 | is represented with a '\#' in the string. Don't forget to quote |
|
1174 | 1174 | strings with spaces embedded in them. Default: 'In [\#]:'. |
|
1175 | 1175 | Sec. 7.2 <node7.html#sec:prompts> discusses in detail all the |
|
1176 | 1176 | available escapes to customize your prompts. |
|
1177 | 1177 | * [-prompt_in2|pi2 <string>:] Similar to the previous option, but |
|
1178 | 1178 | used for the continuation prompts. The special sequence '\D' is |
|
1179 | 1179 | similar to '\#', but with all digits replaced dots (so you can |
|
1180 | 1180 | have your continuation prompt aligned with your input prompt). |
|
1181 | 1181 | Default: ' .\D.:' (note three spaces at the start for alignment |
|
1182 | 1182 | with 'In [\#]'). |
|
1183 | 1183 | * [-prompt_out|po <string>:] String used for output prompts, also |
|
1184 | 1184 | uses numbers like prompt_in1. Default: 'Out[\#]:' |
|
1185 | 1185 | * [-quick:] start in bare bones mode (no config file loaded). |
|
1186 | 1186 | * [-rcfile <name>:] name of your IPython resource configuration |
|
1187 | 1187 | file. Normally IPython loads ipythonrc (from current directory) or |
|
1188 | 1188 | IPYTHONDIR/ipythonrc. |
|
1189 | 1189 | * [ ] If the loading of your config file fails, IPython starts with |
|
1190 | 1190 | a bare bones configuration (no modules loaded at all). |
|
1191 | 1191 | * [-[no]readline:] use the readline library, which is needed to |
|
1192 | 1192 | support name completion and command history, among other things. |
|
1193 | 1193 | It is enabled by default, but may cause problems for users of |
|
1194 | 1194 | X/Emacs in Python comint or shell buffers. |
|
1195 | 1195 | * [ ] Note that X/Emacs 'eterm' buffers (opened with M-x term) |
|
1196 | 1196 | support IPython's readline and syntax coloring fine, only 'emacs' |
|
1197 | 1197 | (M-x shell and C-c !) buffers do not. |
|
1198 | 1198 | * [-screen_length|sl <n>:] number of lines of your screen. This is |
|
1199 | 1199 | used to control printing of very long strings. Strings longer than |
|
1200 | 1200 | this number of lines will be sent through a pager instead of |
|
1201 | 1201 | directly printed. |
|
1202 | 1202 | * [ ] The default value for this is 0, which means IPython will |
|
1203 | 1203 | auto-detect your screen size every time it needs to print certain |
|
1204 | 1204 | potentially long strings (this doesn't change the behavior of the |
|
1205 | 1205 | 'print' keyword, it's only triggered internally). If for some |
|
1206 | 1206 | reason this isn't working well (it needs curses support), specify |
|
1207 | 1207 | it yourself. Otherwise don't change the default. |
|
1208 | 1208 | * [-separate_in|si <string>:] separator before input prompts. |
|
1209 | 1209 | Default: '\n' |
|
1210 | 1210 | * [-separate_out|so <string>:] separator before output prompts. |
|
1211 | 1211 | Default: nothing. |
|
1212 | 1212 | * [-separate_out2|so2 <string>:] separator after output prompts. |
|
1213 | 1213 | Default: nothing. |
|
1214 | 1214 | * [ ] For these three options, use the value 0 to specify no separator. |
|
1215 | 1215 | * [-nosep:] shorthand for '-SeparateIn 0 -SeparateOut 0 |
|
1216 | 1216 | -SeparateOut2 0'. Simply removes all input/output separators. |
|
1217 | 1217 | * [-upgrade:] allows you to upgrade your IPYTHONDIR configuration |
|
1218 | 1218 | when you install a new version of IPython. Since new versions may |
|
1219 | 1219 | include new command line options or example files, this copies |
|
1220 | 1220 | updated ipythonrc-type files. However, it backs up (with a .old |
|
1221 | 1221 | extension) all files which it overwrites so that you can merge |
|
1222 | 1222 | back any customizations you might have in your personal files. |
|
1223 | 1223 | * [-Version:] print version information and exit. |
|
1224 | 1224 | * [-wxversion <string>:] Select a specific version of wxPython (used |
|
1225 | 1225 | in conjunction with -wthread). Requires the wxversion module, part |
|
1226 | 1226 | of recent wxPython distributions |
|
1227 | 1227 | * [-xmode <modename>:] Mode for exception reporting. |
|
1228 | 1228 | * [ ] Valid modes: Plain, Context and Verbose. |
|
1229 | 1229 | * [ ] Plain: similar to python's normal traceback printing. |
|
1230 | 1230 | * [ ] Context: prints 5 lines of context source code around each |
|
1231 | 1231 | line in the traceback. |
|
1232 | 1232 | * [ ] Verbose: similar to Context, but additionally prints the |
|
1233 | 1233 | variables currently visible where the exception happened |
|
1234 | 1234 | (shortening their strings if too long). This can potentially be |
|
1235 | 1235 | very slow, if you happen to have a huge data structure whose |
|
1236 | 1236 | string representation is complex to compute. Your computer may |
|
1237 | 1237 | appear to freeze for a while with cpu usage at 100%. If this |
|
1238 | 1238 | occurs, you can cancel the traceback with Ctrl-C (maybe hitting it |
|
1239 | 1239 | more than once). |
|
1240 | 1240 | |
|
1241 | 1241 | Interactive use |
|
1242 | 1242 | =============== |
|
1243 | 1243 | |
|
1244 | 1244 | Warning: IPython relies on the existence of a global variable called |
|
1245 | 1245 | __IP which controls the shell itself. If you redefine __IP to anything, |
|
1246 | 1246 | bizarre behavior will quickly occur. |
|
1247 | 1247 | |
|
1248 | 1248 | Other than the above warning, IPython is meant to work as a drop-in |
|
1249 | 1249 | replacement for the standard interactive interpreter. As such, any code |
|
1250 | 1250 | which is valid python should execute normally under IPython (cases where |
|
1251 | 1251 | this is not true should be reported as bugs). It does, however, offer |
|
1252 | 1252 | many features which are not available at a standard python prompt. What |
|
1253 | 1253 | follows is a list of these. |
|
1254 | 1254 | |
|
1255 | 1255 | |
|
1256 | 1256 | Caution for Windows users |
|
1257 | 1257 | ------------------------- |
|
1258 | 1258 | |
|
1259 | 1259 | Windows, unfortunately, uses the '\' character as a path separator. This |
|
1260 | 1260 | is a terrible choice, because '\' also represents the escape character |
|
1261 | 1261 | in most modern programming languages, including Python. For this reason, |
|
1262 | 1262 | issuing many of the commands discussed below (especially magics which |
|
1263 | 1263 | affect the filesystem) with '\' in them will cause strange errors. |
|
1264 | 1264 | |
|
1265 | 1265 | A partial solution is to use instead the '/' character as a path |
|
1266 | 1266 | separator, which Windows recognizes in most situations. However, in |
|
1267 | 1267 | Windows commands '/' flags options, so you can not use it for the root |
|
1268 | 1268 | directory. This means that paths beginning at the root must be typed in |
|
1269 | 1269 | a contrived manner like: |
|
1270 | 1270 | %copy \opt/foo/bar.txt \tmp |
|
1271 | 1271 | |
|
1272 | 1272 | There is no sensible thing IPython can do to truly work around this flaw |
|
1273 | 1273 | in Windows^3 <footnode.html#foot878>. |
|
1274 | 1274 | |
|
1275 | 1275 | |
|
1276 | 1276 | |
|
1277 | 1277 | Magic command system |
|
1278 | 1278 | -------------------- |
|
1279 | 1279 | |
|
1280 | 1280 | IPython will treat any line whose first character is a % as a special |
|
1281 | 1281 | call to a 'magic' function. These allow you to control the behavior of |
|
1282 | 1282 | IPython itself, plus a lot of system-type features. They are all |
|
1283 | 1283 | prefixed with a % character, but parameters are given without |
|
1284 | 1284 | parentheses or quotes. |
|
1285 | 1285 | |
|
1286 | 1286 | Example: typing '%cd mydir' (without the quotes) changes you working |
|
1287 | 1287 | directory to 'mydir', if it exists. |
|
1288 | 1288 | |
|
1289 | 1289 | If you have 'automagic' enabled (in your ipythonrc file, via the command |
|
1290 | 1290 | line option -automagic or with the %automagic function), you don't need |
|
1291 | 1291 | to type in the % explicitly. IPython will scan its internal list of |
|
1292 | 1292 | magic functions and call one if it exists. With automagic on you can |
|
1293 | 1293 | then just type 'cd mydir' to go to directory 'mydir'. The automagic |
|
1294 | 1294 | system has the lowest possible precedence in name searches, so defining |
|
1295 | 1295 | an identifier with the same name as an existing magic function will |
|
1296 | 1296 | shadow it for automagic use. You can still access the shadowed magic |
|
1297 | 1297 | function by explicitly using the % character at the beginning of the line. |
|
1298 | 1298 | |
|
1299 | 1299 | An example (with automagic on) should clarify all this:: |
|
1300 | 1300 | |
|
1301 | 1301 | In [1]: cd ipython # %cd is called by automagic |
|
1302 | 1302 | |
|
1303 | 1303 | /home/fperez/ipython |
|
1304 | 1304 | |
|
1305 | 1305 | In [2]: cd=1 # now cd is just a variable |
|
1306 | 1306 | |
|
1307 | 1307 | In [3]: cd .. # and doesn't work as a function anymore |
|
1308 | 1308 | |
|
1309 | 1309 | ------------------------------ |
|
1310 | 1310 | |
|
1311 | 1311 | File "<console>", line 1 |
|
1312 | 1312 | |
|
1313 | 1313 | cd .. |
|
1314 | 1314 | |
|
1315 | 1315 | ^ |
|
1316 | 1316 | |
|
1317 | 1317 | SyntaxError: invalid syntax |
|
1318 | 1318 | |
|
1319 | 1319 | In [4]: %cd .. # but %cd always works |
|
1320 | 1320 | |
|
1321 | 1321 | /home/fperez |
|
1322 | 1322 | |
|
1323 | 1323 | In [5]: del cd # if you remove the cd variable |
|
1324 | 1324 | |
|
1325 | 1325 | In [6]: cd ipython # automagic can work again |
|
1326 | 1326 | |
|
1327 | 1327 | /home/fperez/ipython |
|
1328 | 1328 | |
|
1329 | 1329 | You can define your own magic functions to extend the system. The |
|
1330 | 1330 | following example defines a new magic command, %impall:: |
|
1331 | 1331 | |
|
1332 | 1332 | import IPython.ipapi |
|
1333 | 1333 | |
|
1334 | 1334 | ip = IPython.ipapi.get() |
|
1335 | 1335 | |
|
1336 | 1336 | def doimp(self, arg): |
|
1337 | 1337 | |
|
1338 | 1338 | ip = self.api |
|
1339 | 1339 | |
|
1340 | 1340 | ip.ex("import %s; reload(%s); from %s import *" % ( |
|
1341 | 1341 | |
|
1342 | 1342 | arg,arg,arg) |
|
1343 | 1343 | |
|
1344 | 1344 | ) |
|
1345 | 1345 | |
|
1346 | 1346 | ip.expose_magic('impall', doimp) |
|
1347 | 1347 | |
|
1348 | 1348 | You can also define your own aliased names for magic functions. In your |
|
1349 | 1349 | ipythonrc file, placing a line like: |
|
1350 | 1350 | |
|
1351 | 1351 | execute __IP.magic_cl = __IP.magic_clear |
|
1352 | 1352 | |
|
1353 | 1353 | will define %cl as a new name for %clear. |
|
1354 | 1354 | |
|
1355 | 1355 | Type %magic for more information, including a list of all available |
|
1356 | 1356 | magic functions at any time and their docstrings. You can also type |
|
1357 | 1357 | %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for |
|
1358 | 1358 | information on the '?' system) to get information about any particular |
|
1359 | 1359 | magic function you are interested in. |
|
1360 | 1360 | |
|
1361 | 1361 | |
|
1362 | 1362 | Magic commands |
|
1363 | 1363 | -------------- |
|
1364 | 1364 | |
|
1365 | 1365 | The rest of this section is automatically generated for each release |
|
1366 | 1366 | from the docstrings in the IPython code. Therefore the formatting is |
|
1367 | 1367 | somewhat minimal, but this method has the advantage of having |
|
1368 | 1368 | information always in sync with the code. |
|
1369 | 1369 | |
|
1370 | 1370 | A list of all the magic commands available in IPython's default |
|
1371 | 1371 | installation follows. This is similar to what you'll see by simply |
|
1372 | 1372 | typing %magic at the prompt, but that will also give you information |
|
1373 | 1373 | about magic commands you may have added as part of your personal |
|
1374 | 1374 | customizations. |
|
1375 | 1375 | |
|
1376 | ||
|
1377 | %Exit: Exit IPython without confirmation. | |
|
1378 | ||
|
1379 | ||
|
1380 | %Pprint: Toggle pretty printing on/off. | |
|
1381 | ||
|
1382 | ||
|
1383 | %alias: Define an alias for a system command. | |
|
1384 | ||
|
1385 | '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd' | |
|
1386 | ||
|
1387 | Then, typing 'alias_name params' will execute the system command 'cmd | |
|
1388 | params' (from your underlying operating system). | |
|
1389 | ||
|
1390 | Aliases have lower precedence than magic functions and Python normal | |
|
1391 | variables, so if 'foo' is both a Python variable and an alias, the alias | |
|
1392 | can not be executed until 'del foo' removes the Python variable. | |
|
1393 | ||
|
1394 | You can use the %l specifier in an alias definition to represent the | |
|
1395 | whole line when the alias is called. For example: | |
|
1396 | ||
|
1397 | In [2]: alias all echo "Input in brackets: <%l>" | |
|
1398 | In [3]: all hello world | |
|
1399 | Input in brackets: <hello world> | |
|
1400 | ||
|
1401 | You can also define aliases with parameters using %s specifiers (one per | |
|
1402 | parameter): | |
|
1403 | ||
|
1404 | In [1]: alias parts echo first %s second %s | |
|
1405 | In [2]: %parts A B | |
|
1406 | first A second B | |
|
1407 | In [3]: %parts A | |
|
1408 | Incorrect number of arguments: 2 expected. | |
|
1409 | parts is an alias to: 'echo first %s second %s' | |
|
1410 | ||
|
1411 | Note that %l and %s are mutually exclusive. You can only use one or the | |
|
1412 | other in your aliases. | |
|
1413 | ||
|
1414 | Aliases expand Python variables just like system calls using ! or !! do: | |
|
1415 | all expressions prefixed with '$' get expanded. For details of the | |
|
1416 | semantic rules, see PEP-215: http://www.python.org/peps/pep-0215.html. | |
|
1417 | This is the library used by IPython for variable expansion. If you want | |
|
1418 | to access a true shell variable, an extra $ is necessary to prevent its | |
|
1419 | expansion by IPython: | |
|
1420 | ||
|
1421 | In [6]: alias show echo | |
|
1422 | In [7]: PATH='A Python string' | |
|
1423 | In [8]: show $PATH | |
|
1424 | A Python string | |
|
1425 | In [9]: show $$PATH | |
|
1426 | /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:... | |
|
1427 | ||
|
1428 | You can use the alias facility to acess all of $PATH. See the %rehash | |
|
1429 | and %rehashx functions, which automatically create aliases for the | |
|
1430 | contents of your $PATH. | |
|
1431 | ||
|
1432 | If called with no parameters, %alias prints the current alias table. | |
|
1433 | ||
|
1434 | ||
|
1435 | %autocall: Make functions callable without having to type parentheses. | |
|
1436 | ||
|
1437 | Usage: | |
|
1438 | ||
|
1439 | %autocall [mode] | |
|
1440 | ||
|
1441 | The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the | |
|
1442 | value is toggled on and off (remembering the previous state). | |
|
1443 | ||
|
1444 | In more detail, these values mean: | |
|
1445 | ||
|
1446 | 0 -> fully disabled | |
|
1447 | ||
|
1448 | 1 -> active, but do not apply if there are no arguments on the line. | |
|
1449 | ||
|
1450 | In this mode, you get: | |
|
1451 | ||
|
1452 | In [1]: callable Out[1]: <built-in function callable> | |
|
1453 | ||
|
1454 | In [2]: callable 'hello' ---> callable('hello') Out[2]: False | |
|
1455 | ||
|
1456 | 2 -> Active always. Even if no arguments are present, the callable | |
|
1457 | object is called: | |
|
1458 | ||
|
1459 | In [4]: callable ---> callable() | |
|
1460 | ||
|
1461 | Note that even with autocall off, you can still use '/' at the start of | |
|
1462 | a line to treat the first argument on the command line as a function and | |
|
1463 | add parentheses to it: | |
|
1464 | ||
|
1465 | In [8]: /str 43 ---> str(43) Out[8]: '43' | |
|
1466 | ||
|
1467 | ||
|
1468 | %autoindent: Toggle autoindent on/off (if available). | |
|
1469 | ||
|
1470 | ||
|
1471 | %automagic: Make magic functions callable without having to type the | |
|
1472 | initial %. | |
|
1473 | ||
|
1474 | Without argumentsl toggles on/off (when off, you must call it as | |
|
1475 | %automagic, of course). With arguments it sets the value, and you can | |
|
1476 | use any of (case insensitive): | |
|
1477 | ||
|
1478 | - on,1,True: to activate | |
|
1479 | ||
|
1480 | - off,0,False: to deactivate. | |
|
1481 | ||
|
1482 | Note that magic functions have lowest priority, so if there's a variable | |
|
1483 | whose name collides with that of a magic fn, automagic won't work for | |
|
1484 | that function (you get the variable instead). However, if you delete the | |
|
1485 | variable (del var), the previously shadowed magic function becomes | |
|
1486 | visible to automagic again. | |
|
1487 | ||
|
1488 | ||
|
1489 | %bg: Run a job in the background, in a separate thread. | |
|
1490 | ||
|
1491 | For example, | |
|
1492 | ||
|
1493 | %bg myfunc(x,y,z=1) | |
|
1494 | ||
|
1495 | will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the | |
|
1496 | execution starts, a message will be printed indicating the job number. | |
|
1497 | If your job number is 5, you can use | |
|
1498 | ||
|
1499 | myvar = jobs.result(5) or myvar = jobs[5].result | |
|
1500 | ||
|
1501 | to assign this result to variable 'myvar'. | |
|
1502 | ||
|
1503 | IPython has a job manager, accessible via the 'jobs' object. You can | |
|
1504 | type jobs? to get more information about it, and use jobs.<TAB> to see | |
|
1505 | its attributes. All attributes not starting with an underscore are meant | |
|
1506 | for public use. | |
|
1507 | ||
|
1508 | In particular, look at the jobs.new() method, which is used to create | |
|
1509 | new jobs. This magic %bg function is just a convenience wrapper around | |
|
1510 | jobs.new(), for expression-based jobs. If you want to create a new job | |
|
1511 | with an explicit function object and arguments, you must call jobs.new() | |
|
1512 | directly. | |
|
1513 | ||
|
1514 | The jobs.new docstring also describes in detail several important | |
|
1515 | caveats associated with a thread-based model for background job | |
|
1516 | execution. Type jobs.new? for details. | |
|
1517 | ||
|
1518 | You can check the status of all jobs with jobs.status(). | |
|
1519 | ||
|
1520 | The jobs variable is set by IPython into the Python builtin namespace. | |
|
1521 | If you ever declare a variable named 'jobs', you will shadow this name. | |
|
1522 | You can either delete your global jobs variable to regain access to the | |
|
1523 | job manager, or make a new name and assign it manually to the manager | |
|
1524 | (stored in IPython's namespace). For example, to assign the job manager | |
|
1525 | to the Jobs name, use: | |
|
1526 | ||
|
1527 | Jobs = __builtins__.jobs | |
|
1528 | ||
|
1529 | ||
|
1530 | %bookmark: Manage IPython's bookmark system. | |
|
1531 | ||
|
1532 | %bookmark <name> - set bookmark to current dir %bookmark <name> <dir> - | |
|
1533 | set bookmark to <dir> %bookmark -l - list all bookmarks %bookmark -d | |
|
1534 |
|
|
|
1535 | ||
|
1536 | You can later on access a bookmarked folder with: %cd -b <name> or | |
|
1537 | simply '%cd <name>' if there is no directory called <name> AND there is | |
|
1538 | such a bookmark defined. | |
|
1539 | ||
|
1540 | Your bookmarks persist through IPython sessions, but they are associated | |
|
1541 | with each profile. | |
|
1542 | ||
|
1543 | ||
|
1544 | %cd: Change the current working directory. | |
|
1545 | ||
|
1546 | This command automatically maintains an internal list of directories you | |
|
1547 | visit during your IPython session, in the variable _dh. The command | |
|
1548 | %dhist shows this history nicely formatted. You can also do 'cd -<tab>' | |
|
1549 | to see directory history conveniently. | |
|
1550 | ||
|
1551 | Usage: | |
|
1552 | ||
|
1553 | cd 'dir': changes to directory 'dir'. | |
|
1554 | ||
|
1555 | cd -: changes to the last visited directory. | |
|
1556 | ||
|
1557 | cd -<n>: changes to the n-th directory in the directory history. | |
|
1558 | ||
|
1559 | cd -b <bookmark_name>: jump to a bookmark set by %bookmark (note: cd | |
|
1560 | <bookmark_name> is enough if there is no directory <bookmark_name>, but | |
|
1561 | a bookmark with the name exists.) 'cd -b <tab>' allows you to | |
|
1562 | tab-complete bookmark names. | |
|
1563 | ||
|
1564 | Options: | |
|
1565 | ||
|
1566 | -q: quiet. Do not print the working directory after the cd command is | |
|
1567 | executed. By default IPython's cd command does print this directory, | |
|
1568 | since the default prompts do not display path information. | |
|
1569 | ||
|
1570 | Note that !cd doesn't work for this purpose because the shell where | |
|
1571 | !command runs is immediately discarded after executing 'command'. | |
|
1572 | ||
|
1573 | ||
|
1574 | %color_info: Toggle color_info. | |
|
1575 | ||
|
1576 | The color_info configuration parameter controls whether colors are used | |
|
1577 | for displaying object details (by things like %psource, %pfile or the | |
|
1578 | '?' system). This function toggles this value with each call. | |
|
1579 | ||
|
1580 | Note that unless you have a fairly recent pager (less works better than | |
|
1581 | more) in your system, using colored object information displays will not | |
|
1582 | work properly. Test it and see. | |
|
1583 | ||
|
1584 | ||
|
1585 | %colors: Switch color scheme for prompts, info system and exception | |
|
1586 | handlers. | |
|
1587 | ||
|
1588 | Currently implemented schemes: NoColor, Linux, LightBG. | |
|
1589 | ||
|
1590 | Color scheme names are not case-sensitive. | |
|
1591 | ||
|
1592 | ||
|
1593 | %cpaste: Allows you to paste & execute a pre-formatted code block from | |
|
1594 | clipboard | |
|
1595 | ||
|
1596 | You must terminate the block with '-' (two minus-signs) alone on the | |
|
1597 | line. You can also provide your own sentinel with '%paste -s %%' ('%%' | |
|
1598 | is the new sentinel for this operation) | |
|
1599 | ||
|
1600 | The block is dedented prior to execution to enable execution of method | |
|
1601 | definitions. '>' and '+' characters at the beginning of a line are | |
|
1602 | ignored, to allow pasting directly from e-mails or diff files. The | |
|
1603 | executed block is also assigned to variable named 'pasted_block' for | |
|
1604 | later editing with '%edit pasted_block'. | |
|
1605 | ||
|
1606 | You can also pass a variable name as an argument, e.g. '%cpaste foo'. | |
|
1607 | This assigns the pasted block to variable 'foo' as string, without | |
|
1608 | dedenting or executing it. | |
|
1609 | ||
|
1610 | Do not be alarmed by garbled output on Windows (it's a readline bug). | |
|
1611 | Just press enter and type - (and press enter again) and the block will | |
|
1612 | be what was just pasted. | |
|
1613 | ||
|
1614 | IPython statements (magics, shell escapes) are not supported (yet). | |
|
1615 | ||
|
1616 | ||
|
1617 | %debug: Activate the interactive debugger in post-mortem mode. | |
|
1618 | ||
|
1619 | If an exception has just occurred, this lets you inspect its stack | |
|
1620 | frames interactively. Note that this will always work only on the last | |
|
1621 | traceback that occurred, so you must call this quickly after an | |
|
1622 | exception that you wish to inspect has fired, because if another one | |
|
1623 | occurs, it clobbers the previous one. | |
|
1624 | ||
|
1625 | If you want IPython to automatically do this on every exception, see the | |
|
1626 | %pdb magic for more details. | |
|
1627 | ||
|
1628 | ||
|
1629 | %dhist: Print your history of visited directories. | |
|
1630 | ||
|
1631 | %dhist -> print full history | |
|
1632 |
%dhist |
|
|
1633 | %dhist n1 n2 -> print entries between n1 and n2 (n1 not included) | |
|
1634 | ||
|
1635 | This history is automatically maintained by the %cd command, and always | |
|
1636 | available as the global list variable _dh. You can use %cd -<n> to go to | |
|
1637 | directory number <n>. | |
|
1638 | ||
|
1639 | Note that most of time, you should view directory history by entering cd | |
|
1640 | -<TAB>. | |
|
1641 | ||
|
1642 | ||
|
1643 | %dirs: Return the current directory stack. | |
|
1644 | ||
|
1645 | ||
|
1646 | %doctest_mode: Toggle doctest mode on and off. | |
|
1647 | ||
|
1648 | This mode allows you to toggle the prompt behavior between normal | |
|
1649 | IPython prompts and ones that are as similar to the default IPython | |
|
1650 | interpreter as possible. | |
|
1651 | ||
|
1652 | It also supports the pasting of code snippets that have leading '»>' and | |
|
1653 | '...' prompts in them. This means that you can paste doctests from files | |
|
1654 | or docstrings (even if they have leading whitespace), and the code will | |
|
1655 | execute correctly. You can then use '%history -tn' to see the translated | |
|
1656 | history without line numbers; this will give you the input after removal | |
|
1657 | of all the leading prompts and whitespace, which can be pasted back into | |
|
1658 | an editor. | |
|
1659 | ||
|
1660 | With these features, you can switch into this mode easily whenever you | |
|
1661 | need to do testing and changes to doctests, without having to leave your | |
|
1662 | existing IPython session. | |
|
1663 | ||
|
1664 | ||
|
1665 | %ed: Alias to %edit. | |
|
1666 | ||
|
1667 | ||
|
1668 | %edit: Bring up an editor and execute the resulting code. | |
|
1669 | ||
|
1670 | Usage: %edit [options] [args] | |
|
1671 | ||
|
1672 | %edit runs IPython's editor hook. The default version of this hook is | |
|
1673 | set to call the __IPYTHON__.rc.editor command. This is read from your | |
|
1674 | environment variable $EDITOR. If this isn't found, it will default to vi | |
|
1675 | under Linux/Unix and to notepad under Windows. See the end of this | |
|
1676 | docstring for how to change the editor hook. | |
|
1677 | ||
|
1678 | You can also set the value of this editor via the command line option | |
|
1679 | '-editor' or in your ipythonrc file. This is useful if you wish to use | |
|
1680 | specifically for IPython an editor different from your typical default | |
|
1681 | (and for Windows users who typically don't set environment variables). | |
|
1682 | ||
|
1683 | This command allows you to conveniently edit multi-line code right in | |
|
1684 | your IPython session. | |
|
1685 | ||
|
1686 | If called without arguments, %edit opens up an empty editor with a | |
|
1687 | temporary file and will execute the contents of this file when you close | |
|
1688 | it (don't forget to save it!). | |
|
1689 | ||
|
1690 | Options: | |
|
1691 | ||
|
1692 | -n <number>: open the editor at a specified line number. By default, the | |
|
1693 | IPython editor hook uses the unix syntax 'editor +N filename', but you | |
|
1694 | can configure this by providing your own modified hook if your favorite | |
|
1695 | editor supports line-number specifications with a different syntax. | |
|
1696 | ||
|
1697 | -p: this will call the editor with the same data as the previous time it | |
|
1698 | was used, regardless of how long ago (in your current session) it was. | |
|
1699 | ||
|
1700 | -r: use 'raw' input. This option only applies to input taken from the | |
|
1701 | user's history. By default, the 'processed' history is used, so that | |
|
1702 | magics are loaded in their transformed version to valid Python. If this | |
|
1703 | option is given, the raw input as typed as the command line is used | |
|
1704 | instead. When you exit the editor, it will be executed by IPython's own | |
|
1705 | processor. | |
|
1706 | ||
|
1707 | -x: do not execute the edited code immediately upon exit. This is mainly | |
|
1708 | useful if you are editing programs which need to be called with command | |
|
1709 | line arguments, which you can then do using %run. | |
|
1710 | ||
|
1711 | Arguments: | |
|
1712 | ||
|
1713 | If arguments are given, the following possibilites exist: | |
|
1714 | ||
|
1715 | - The arguments are numbers or pairs of colon-separated numbers (like 1 | |
|
1716 | 4:8 9). These are interpreted as lines of previous input to be loaded | |
|
1717 | into the editor. The syntax is the same of the %macro command. | |
|
1718 | ||
|
1719 | - If the argument doesn't start with a number, it is evaluated as a | |
|
1720 | variable and its contents loaded into the editor. You can thus edit any | |
|
1721 | string which contains python code (including the result of previous edits). | |
|
1722 | ||
|
1723 | - If the argument is the name of an object (other than a string), | |
|
1724 | IPython will try to locate the file where it was defined and open the | |
|
1725 | editor at the point where it is defined. You can use '%edit function' to | |
|
1726 |
|
|
|
1727 | and have the file be executed automatically. | |
|
1728 | ||
|
1729 | If the object is a macro (see %macro for details), this opens up your | |
|
1730 | specified editor with a temporary file containing the macro's data. Upon | |
|
1731 | exit, the macro is reloaded with the contents of the file. | |
|
1732 | ||
|
1733 | Note: opening at an exact line is only supported under Unix, and some | |
|
1734 | editors (like kedit and gedit up to Gnome 2.8) do not understand the | |
|
1735 | '+NUMBER' parameter necessary for this feature. Good editors like | |
|
1736 | (X)Emacs, vi, jed, pico and joe all do. | |
|
1737 | ||
|
1738 | - If the argument is not found as a variable, IPython will look for a | |
|
1739 | file with that name (adding .py if necessary) and load it into the | |
|
1740 | editor. It will execute its contents with execfile() when you exit, | |
|
1741 | loading any code in the file into your interactive namespace. | |
|
1742 | ||
|
1743 | After executing your code, %edit will return as output the code you | |
|
1744 | typed in the editor (except when it was an existing file). This way you | |
|
1745 | can reload the code in further invocations of %edit as a variable, via | |
|
1746 | _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the | |
|
1747 | output. | |
|
1748 | ||
|
1749 | Note that %edit is also available through the alias %ed. | |
|
1750 | ||
|
1751 | This is an example of creating a simple function inside the editor and | |
|
1752 | then modifying it. First, start up the editor:: | |
|
1753 | ||
|
1754 | In [1]: ed | |
|
1755 | Editing... done. Executing edited code... | |
|
1756 | Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n' | |
|
1757 | ||
|
1758 | We can then call the function foo(): | |
|
1759 | ||
|
1760 | In [2]: foo() | |
|
1761 | foo() was defined in an editing session | |
|
1762 | ||
|
1763 | Now we edit foo. IPython automatically loads the editor with the | |
|
1764 | (temporary) file where foo() was previously defined: | |
|
1765 | ||
|
1766 | In [3]: ed foo | |
|
1767 | Editing... done. Executing edited code... | |
|
1768 | ||
|
1769 | And if we call foo() again we get the modified version: | |
|
1770 | ||
|
1771 | In [4]: foo() | |
|
1772 | foo() has now been changed! | |
|
1773 | ||
|
1774 | Here is an example of how to edit a code snippet successive times. First | |
|
1775 | we call the editor: | |
|
1776 | ||
|
1777 | In [8]: ed | |
|
1778 | Editing... done. Executing edited code... | |
|
1779 | hello | |
|
1780 | Out[8]: "print 'hello'\n" | |
|
1781 | ||
|
1782 | Now we call it again with the previous output (stored in _): | |
|
1783 | ||
|
1784 | In [9]: ed _ | |
|
1785 | Editing... done. Executing edited code... | |
|
1786 | hello world | |
|
1787 |
|
|
|
1788 | ||
|
1789 | Now we call it with the output #8 (stored in _8, also as Out[8]): | |
|
1790 | ||
|
1791 | In [10]: ed _8 | |
|
1792 | Editing... done. Executing edited code... | |
|
1793 | hello again | |
|
1794 | Out[10]: "print 'hello again'\n" | |
|
1795 | ||
|
1796 | Changing the default editor hook: | |
|
1797 | ||
|
1798 | If you wish to write your own editor hook, you can put it in a | |
|
1799 | configuration file which you load at startup time. The default hook is | |
|
1800 | defined in the IPython.hooks module, and you can use that as a starting | |
|
1801 | example for further modifications. That file also has general | |
|
1802 | instructions on how to set a new hook for use once you've defined it. | |
|
1803 | ||
|
1804 | ||
|
1805 | %env: List environment variables. | |
|
1806 | ||
|
1807 | ||
|
1808 | %exit: Exit IPython, confirming if configured to do so. | |
|
1809 | ||
|
1810 | You can configure whether IPython asks for confirmation upon exit by | |
|
1811 | setting the confirm_exit flag in the ipythonrc file. | |
|
1812 | ||
|
1813 | ||
|
1814 | %logoff: Temporarily stop logging. | |
|
1815 | ||
|
1816 | You must have previously started logging. | |
|
1817 | ||
|
1818 | ||
|
1819 | %logon: Restart logging. | |
|
1820 | ||
|
1821 | This function is for restarting logging which you've temporarily stopped | |
|
1822 | with %logoff. For starting logging for the first time, you must use the | |
|
1823 | %logstart function, which allows you to specify an optional log filename. | |
|
1824 | ||
|
1825 | ||
|
1826 | %logstart: Start logging anywhere in a session. | |
|
1827 | ||
|
1828 | %logstart [-o|-r|-t] [log_name [log_mode]] | |
|
1829 | ||
|
1830 | If no name is given, it defaults to a file named 'ipython_log.py' in | |
|
1831 | your current directory, in 'rotate' mode (see below). | |
|
1832 | ||
|
1833 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your | |
|
1834 | history up to that point and then continues logging. | |
|
1835 | ||
|
1836 | %logstart takes a second optional parameter: logging mode. This can be | |
|
1837 | one of (note that the modes are given unquoted): | |
|
1838 | append: well, that says it. | |
|
1839 | backup: rename (if exists) to name and start name. | |
|
1840 | global: single logfile in your home dir, appended to. | |
|
1841 | over : overwrite existing log. | |
|
1842 | rotate: create rotating logs name.1 , name.2 , etc. | |
|
1843 | ||
|
1844 | Options: | |
|
1845 | ||
|
1846 | -o: log also IPython's output. In this mode, all commands which generate | |
|
1847 | an Out[NN] prompt are recorded to the logfile, right after their | |
|
1848 | corresponding input line. The output lines are always prepended with a | |
|
1849 | '#[Out]# ' marker, so that the log remains valid Python code. | |
|
1850 | ||
|
1851 | Since this marker is always the same, filtering only the output from a | |
|
1852 | log is very easy, using for example a simple awk call: | |
|
1853 | ||
|
1854 | awk -F'# | |
|
1855 | ||
|
1856 | \begin{displaymath}Out\end{displaymath} | |
|
1857 | ||
|
1858 | # ' 'if($2) print $2' ipython_log.py | |
|
1859 | ||
|
1860 | -r: log 'raw' input. Normally, IPython's logs contain the processed | |
|
1861 | input, so that user lines are logged in their final form, converted into | |
|
1862 | valid Python. For example, %Exit is logged as '_ip.magic("Exit"). If the | |
|
1863 | -r flag is given, all input is logged exactly as typed, with no | |
|
1864 | transformations applied. | |
|
1865 | ||
|
1866 | -t: put timestamps before each input line logged (these are put in | |
|
1867 | comments). | |
|
1868 | ||
|
1869 | ||
|
1870 | %logstate: Print the status of the logging system. | |
|
1871 | ||
|
1872 | ||
|
1873 | %logstop: Fully stop logging and close log file. | |
|
1874 | ||
|
1875 | In order to start logging again, a new %logstart call needs to be made, | |
|
1876 | possibly (though not necessarily) with a new filename, mode and other | |
|
1877 | options. | |
|
1878 | ||
|
1879 | ||
|
1880 | %lsmagic: List currently available magic functions. | |
|
1881 | ||
|
1882 | ||
|
1883 | %macro: Define a set of input lines as a macro for future re-execution. | |
|
1884 | ||
|
1885 | Usage: | |
|
1886 | %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ... | |
|
1887 | ||
|
1888 | Options: | |
|
1889 | ||
|
1890 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
1891 | that magics are loaded in their transformed version to valid Python. If | |
|
1892 | this option is given, the raw input as typed as the command line is used | |
|
1893 | instead. | |
|
1894 | ||
|
1895 | This will define a global variable called 'name' which is a string made | |
|
1896 | of joining the slices and lines you specify (n1,n2,... numbers above) | |
|
1897 | from your input history into a single string. This variable acts like an | |
|
1898 | automatic function which re-executes those lines as if you had typed | |
|
1899 | them. You just type 'name' at the prompt and the code executes. | |
|
1900 | ||
|
1901 | The notation for indicating number ranges is: n1-n2 means 'use line | |
|
1902 | numbers n1,...n2' (the endpoint is included). That is, '5-7' means using | |
|
1903 | the lines numbered 5,6 and 7. | |
|
1904 | ||
|
1905 | Note: as a 'hidden' feature, you can also use traditional python slice | |
|
1906 | notation, where N:M means numbers N through M-1. | |
|
1907 | ||
|
1908 | For example, if your history contains (%hist prints it): | |
|
1909 | ||
|
1910 | 44: x=1 | |
|
1911 | 45: y=3 | |
|
1912 | 46: z=x+y | |
|
1913 | 47: print x | |
|
1914 | 48: a=5 | |
|
1915 | 49: print 'x',x,'y',y | |
|
1916 | ||
|
1917 | you can create a macro with lines 44 through 47 (included) and line 49 | |
|
1918 | called my_macro with: | |
|
1919 | ||
|
1920 | In [51]: %macro my_macro 44-47 49 | |
|
1921 | ||
|
1922 | Now, typing 'my_macro' (without quotes) will re-execute all this code in | |
|
1923 | one pass. | |
|
1924 | ||
|
1925 | You don't need to give the line-numbers in order, and any given line | |
|
1926 | number can appear multiple times. You can assemble macros with any lines | |
|
1927 | from your input history in any order. | |
|
1928 | ||
|
1929 | The macro is a simple object which holds its value in an attribute, but | |
|
1930 | IPython's display system checks for macros and executes them as code | |
|
1931 | instead of printing them when you type their name. | |
|
1932 | ||
|
1933 | You can view a macro's contents by explicitly printing it with: | |
|
1934 | ||
|
1935 | 'print macro_name'. | |
|
1936 | ||
|
1937 | For one-off cases which DON'T contain magic function calls in them you | |
|
1938 | can obtain similar results by explicitly executing slices from your | |
|
1939 | input history with: | |
|
1940 | ||
|
1941 | In [60]: exec In[44:48]+In[49] | |
|
1942 | ||
|
1943 | ||
|
1944 | %magic: Print information about the magic function system. | |
|
1945 | ||
|
1946 | ||
|
1947 | %page: Pretty print the object and display it through a pager. | |
|
1948 | ||
|
1949 | %page [options] OBJECT | |
|
1950 | ||
|
1951 | If no object is given, use _ (last output). | |
|
1952 | ||
|
1953 | Options: | |
|
1954 | ||
|
1955 | -r: page str(object), don't pretty-print it. | |
|
1956 | ||
|
1957 | ||
|
1958 | %pdb: Control the automatic calling of the pdb interactive debugger. | |
|
1959 | ||
|
1960 | Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without | |
|
1961 | argument it works as a toggle. | |
|
1962 | ||
|
1963 | When an exception is triggered, IPython can optionally call the | |
|
1964 | interactive pdb debugger after the traceback printout. %pdb toggles this | |
|
1965 | feature on and off. | |
|
1966 | ||
|
1967 | The initial state of this feature is set in your ipythonrc configuration | |
|
1968 | file (the variable is called 'pdb'). | |
|
1969 | ||
|
1970 | If you want to just activate the debugger AFTER an exception has fired, | |
|
1971 | without having to type '%pdb on' and rerunning your code, you can use | |
|
1972 | the %debug magic. | |
|
1973 | ||
|
1974 | ||
|
1975 | %pdef: Print the definition header for any callable object. | |
|
1976 | ||
|
1977 | If the object is a class, print the constructor information. | |
|
1978 | ||
|
1979 | ||
|
1980 | %pdoc: Print the docstring for an object. | |
|
1981 | ||
|
1982 | If the given object is a class, it will print both the class and the | |
|
1983 | constructor docstrings. | |
|
1984 | ||
|
1985 | ||
|
1986 | %pfile: Print (or run through pager) the file where an object is defined. | |
|
1987 | ||
|
1988 | The file opens at the line where the object definition begins. IPython | |
|
1989 | will honor the environment variable PAGER if set, and otherwise will do | |
|
1990 | its best to print the file in a convenient form. | |
|
1991 | ||
|
1992 | If the given argument is not an object currently defined, IPython will | |
|
1993 | try to interpret it as a filename (automatically adding a .py extension | |
|
1994 | if needed). You can thus use %pfile as a syntax highlighting code viewer. | |
|
1995 | ||
|
1996 | ||
|
1997 | %pinfo: Provide detailed information about an object. | |
|
1998 | ||
|
1999 | '%pinfo object' is just a synonym for object? or ?object. | |
|
2000 | ||
|
2001 | ||
|
2002 | %popd: Change to directory popped off the top of the stack. | |
|
2003 | ||
|
2004 | ||
|
2005 | %profile: Print your currently active IPyhton profile. | |
|
2006 | ||
|
2007 | ||
|
2008 | %prun: Run a statement through the python code profiler. | |
|
2009 | ||
|
2010 | Usage: | |
|
2011 | %prun [options] statement | |
|
2012 | ||
|
2013 | The given statement (which doesn't require quote marks) is run via the | |
|
2014 | python profiler in a manner similar to the profile.run() function. | |
|
2015 | Namespaces are internally managed to work correctly; profile.run cannot | |
|
2016 | be used in IPython because it makes certain assumptions about namespaces | |
|
2017 | which do not hold under IPython. | |
|
2018 | ||
|
2019 | Options: | |
|
2020 | ||
|
2021 | -l <limit>: you can place restrictions on what or how much of the | |
|
2022 | profile gets printed. The limit value can be: | |
|
2023 | ||
|
2024 | * A string: only information for function names containing this string | |
|
2025 | is printed. | |
|
2026 | ||
|
2027 | * An integer: only these many lines are printed. | |
|
2028 | ||
|
2029 | * A float (between 0 and 1): this fraction of the report is printed (for | |
|
2030 | example, use a limit of 0.4 to see the topmost 40% only). | |
|
2031 | ||
|
2032 | You can combine several limits with repeated use of the option. For | |
|
2033 | example, '-l __init__ -l 5' will print only the topmost 5 lines of | |
|
2034 | information about class constructors. | |
|
2035 | ||
|
2036 | -r: return the pstats.Stats object generated by the profiling. This | |
|
2037 | object has all the information about the profile in it, and you can | |
|
2038 | later use it for further analysis or in other functions. | |
|
2039 | ||
|
2040 | -s <key>: sort profile by given key. You can provide more than one key | |
|
2041 | by using the option several times: '-s key1 -s key2 -s key3...'. The | |
|
2042 | default sorting key is 'time'. | |
|
2043 | ||
|
2044 | The following is copied verbatim from the profile documentation | |
|
2045 | referenced below: | |
|
2046 | ||
|
2047 | When more than one key is provided, additional keys are used as | |
|
2048 | secondary criteria when the there is equality in all keys selected | |
|
2049 | before them. | |
|
2050 | ||
|
2051 | Abbreviations can be used for any key names, as long as the abbreviation | |
|
2052 | is unambiguous. The following are the keys currently defined: | |
|
2053 | ||
|
2054 | Valid Arg Meaning | |
|
2055 | "calls" call count | |
|
2056 | "cumulative" cumulative time | |
|
2057 | "file" file name | |
|
2058 |
|
|
|
2059 | "pcalls" primitive call count | |
|
2060 | "line" line number | |
|
2061 | "name" function name | |
|
2062 | "nfl" name/file/line | |
|
2063 | "stdname" standard name | |
|
2064 | "time" internal time | |
|
2065 | ||
|
2066 | Note that all sorts on statistics are in descending order (placing most | |
|
2067 | time consuming items first), where as name, file, and line number | |
|
2068 | searches are in ascending order (i.e., alphabetical). The subtle | |
|
2069 | distinction between "nfl" and "stdname" is that the standard name is a | |
|
2070 | sort of the name as printed, which means that the embedded line numbers | |
|
2071 | get compared in an odd way. For example, lines 3, 20, and 40 would (if | |
|
2072 | the file names were the same) appear in the string order "20" "3" and | |
|
2073 | "40". In contrast, "nfl" does a numeric compare of the line numbers. In | |
|
2074 | fact, sort_stats("nfl") is the same as sort_stats("name", "file", "line"). | |
|
2075 | ||
|
2076 | -T <filename>: save profile results as shown on screen to a text file. | |
|
2077 | The profile is still shown on screen. | |
|
2078 | ||
|
2079 | -D <filename>: save (via dump_stats) profile statistics to given | |
|
2080 | filename. This data is in a format understod by the pstats module, and | |
|
2081 | is generated by a call to the dump_stats() method of profile objects. | |
|
2082 | The profile is still shown on screen. | |
|
2083 | ||
|
2084 | If you want to run complete programs under the profiler's control, use | |
|
2085 | '%run -p [prof_opts] filename.py [args to program]' where prof_opts | |
|
2086 | contains profiler specific options as described here. | |
|
2087 | ||
|
2088 | You can read the complete documentation for the profile module with: | |
|
2089 | In [1]: import profile; profile.help() | |
|
2090 | ||
|
2091 | ||
|
2092 | %psearch: Search for object in namespaces by wildcard. | |
|
2093 | ||
|
2094 | %psearch [options] PATTERN [OBJECT TYPE] | |
|
2095 | ||
|
2096 | Note: ? can be used as a synonym for %psearch, at the beginning or at | |
|
2097 | the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the | |
|
2098 | rest of the command line must be unchanged (options come first), so for | |
|
2099 | example the following forms are equivalent | |
|
2100 | ||
|
2101 | %psearch -i a* function -i a* function? ?-i a* function | |
|
2102 | ||
|
2103 | Arguments: | |
|
2104 | ||
|
2105 | PATTERN | |
|
2106 | ||
|
2107 | where PATTERN is a string containing * as a wildcard similar to its use | |
|
2108 | in a shell. The pattern is matched in all namespaces on the search path. | |
|
2109 | By default objects starting with a single _ are not matched, many | |
|
2110 | IPython generated objects have a single underscore. The default is case | |
|
2111 | insensitive matching. Matching is also done on the attributes of objects | |
|
2112 | and not only on the objects in a module. | |
|
2113 | ||
|
2114 | [OBJECT TYPE] | |
|
2115 | ||
|
2116 | Is the name of a python type from the types module. The name is given in | |
|
2117 | lowercase without the ending type, ex. StringType is written string. By | |
|
2118 | adding a type here only objects matching the given type are matched. | |
|
2119 | Using all here makes the pattern match all types (this is the default). | |
|
2120 | ||
|
2121 | Options: | |
|
2122 | ||
|
2123 | -a: makes the pattern match even objects whose names start with a single | |
|
2124 | underscore. These names are normally ommitted from the search. | |
|
2125 | ||
|
2126 | -i/-c: make the pattern case insensitive/sensitive. If neither of these | |
|
2127 | options is given, the default is read from your ipythonrc file. The | |
|
2128 | option name which sets this value is 'wildcards_case_sensitive'. If this | |
|
2129 | option is not specified in your ipythonrc file, IPython's internal | |
|
2130 | default is to do a case sensitive search. | |
|
2131 | ||
|
2132 | -e/-s NAMESPACE: exclude/search a given namespace. The pattern you | |
|
2133 | specifiy can be searched in any of the following namespaces: 'builtin', | |
|
2134 | 'user', 'user_global','internal', 'alias', where 'builtin' and 'user' | |
|
2135 | are the search defaults. Note that you should not use quotes when | |
|
2136 | specifying namespaces. | |
|
2137 | ||
|
2138 | 'Builtin' contains the python module builtin, 'user' contains all user | |
|
2139 | data, 'alias' only contain the shell aliases and no python objects, | |
|
2140 | 'internal' contains objects used by IPython. The 'user_global' namespace | |
|
2141 | is only used by embedded IPython instances, and it contains module-level | |
|
2142 | globals. You can add namespaces to the search with -s or exclude them | |
|
2143 | with -e (these options can be given more than once). | |
|
2144 | ||
|
2145 | Examples: | |
|
2146 | ||
|
2147 | %psearch a* -> objects beginning with an a %psearch -e builtin a* -> | |
|
2148 | objects NOT in the builtin space starting in a %psearch a* function -> | |
|
2149 | all functions beginning with an a %psearch re.e* -> objects beginning | |
|
2150 | with an e in module re %psearch r*.e* -> objects that start with e in | |
|
2151 | modules starting in r %psearch r*.* string -> all strings in modules | |
|
2152 | beginning with r | |
|
2153 | ||
|
2154 | Case sensitve search: | |
|
2155 | ||
|
2156 | %psearch -c a* list all object beginning with lower case a | |
|
2157 | ||
|
2158 | Show objects beginning with a single _: | |
|
2159 | ||
|
2160 | %psearch -a _* list objects beginning with a single underscore | |
|
2161 | ||
|
2162 | ||
|
2163 | %psource: Print (or run through pager) the source code for an object. | |
|
2164 | ||
|
2165 | ||
|
2166 | %pushd: Place the current dir on stack and change directory. | |
|
2167 | ||
|
2168 | Usage: | |
|
2169 | %pushd ['dirname'] | |
|
2170 | ||
|
2171 | ||
|
2172 | %pwd: Return the current working directory path. | |
|
2173 | ||
|
2174 | ||
|
2175 | %pycat: Show a syntax-highlighted file through a pager. | |
|
2176 | ||
|
2177 | This magic is similar to the cat utility, but it will assume the file to | |
|
2178 | be Python source and will show it with syntax highlighting. | |
|
2179 | ||
|
2180 | ||
|
2181 | %quickref: Show a quick reference sheet | |
|
2182 | ||
|
2183 | ||
|
2184 | %quit: Exit IPython, confirming if configured to do so (like %exit) | |
|
2185 | ||
|
2186 | ||
|
2187 | %r: Repeat previous input. | |
|
2188 | ||
|
2189 | Note: Consider using the more powerfull %rep instead! | |
|
2190 | ||
|
2191 | If given an argument, repeats the previous command which starts with the | |
|
2192 | same string, otherwise it just repeats the previous input. | |
|
2193 | ||
|
2194 | Shell escaped commands (with ! as first character) are not recognized by | |
|
2195 | this system, only pure python code and magic commands. | |
|
2196 | ||
|
2197 | ||
|
2198 | %rehashx: Update the alias table with all executable files in $PATH. | |
|
2199 | ||
|
2200 | This version explicitly checks that every entry in $PATH is a file with | |
|
2201 | execute access (os.X_OK), so it is much slower than %rehash. | |
|
2202 | ||
|
2203 | Under Windows, it checks executability as a match agains a '|'-separated | |
|
2204 | string of extensions, stored in the IPython config variable | |
|
2205 | win_exec_ext. This defaults to 'exe|com|bat'. | |
|
2206 | ||
|
2207 | This function also resets the root module cache of module completer, | |
|
2208 | used on slow filesystems. | |
|
2209 | ||
|
2210 | ||
|
2211 | %reset: Resets the namespace by removing all names defined by the user. | |
|
2212 | ||
|
2213 | Input/Output history are left around in case you need them. | |
|
2214 | ||
|
2215 | ||
|
2216 | %run: Run the named file inside IPython as a program. | |
|
2217 | ||
|
2218 | Usage: | |
|
2219 | %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args] | |
|
2220 | ||
|
2221 | Parameters after the filename are passed as command-line arguments to | |
|
2222 | the program (put in sys.argv). Then, control returns to IPython's prompt. | |
|
2223 | ||
|
2224 | This is similar to running at a system prompt: | |
|
2225 | $ python file args | |
|
2226 | but with the advantage of giving you IPython's tracebacks, and of | |
|
2227 | loading all variables into your interactive namespace for further use | |
|
2228 | (unless -p is used, see below). | |
|
2229 | ||
|
2230 | The file is executed in a namespace initially consisting only of | |
|
2231 | __name__=='__main__' and sys.argv constructed as indicated. It thus sees | |
|
2232 | its environment as if it were being run as a stand-alone program (except | |
|
2233 | for sharing global objects such as previously imported modules). But | |
|
2234 | after execution, the IPython interactive namespace gets updated with all | |
|
2235 | variables defined in the program (except for __name__ and sys.argv). | |
|
2236 | This allows for very convenient loading of code for interactive work, | |
|
2237 | while giving each program a 'clean sheet' to run in. | |
|
2238 | ||
|
2239 | Options: | |
|
2240 | ||
|
2241 | -n: __name__ is NOT set to '__main__', but to the running file's name | |
|
2242 | without extension (as python does under import). This allows running | |
|
2243 | scripts and reloading the definitions in them without calling code | |
|
2244 | protected by an ' if __name__ == "__main__" ' clause. | |
|
2245 | ||
|
2246 | -i: run the file in IPython's namespace instead of an empty one. This is | |
|
2247 | useful if you are experimenting with code written in a text editor which | |
|
2248 | depends on variables defined interactively. | |
|
2249 | ||
|
2250 | -e: ignore sys.exit() calls or SystemExit exceptions in the script being | |
|
2251 | run. This is particularly useful if IPython is being used to run | |
|
2252 | unittests, which always exit with a sys.exit() call. In such cases you | |
|
2253 | are interested in the output of the test results, not in seeing a | |
|
2254 | traceback of the unittest module. | |
|
2255 | ||
|
2256 | -t: print timing information at the end of the run. IPython will give | |
|
2257 | you an estimated CPU time consumption for your script, which under Unix | |
|
2258 | uses the resource module to avoid the wraparound problems of | |
|
2259 | time.clock(). Under Unix, an estimate of time spent on system tasks is | |
|
2260 | also given (for Windows platforms this is reported as 0.0). | |
|
2261 | ||
|
2262 | If -t is given, an additional -N<N> option can be given, where <N> must | |
|
2263 | be an integer indicating how many times you want the script to run. The | |
|
2264 | final timing report will include total and per run results. | |
|
2265 | ||
|
2266 | For example (testing the script uniq_stable.py): | |
|
2267 | ||
|
2268 | In [1]: run -t uniq_stable | |
|
2269 | ||
|
2270 | IPython CPU timings (estimated): | |
|
2271 | User : 0.19597 s. | |
|
2272 | System: 0.0 s. | |
|
2273 | ||
|
2274 | In [2]: run -t -N5 uniq_stable | |
|
2275 | ||
|
2276 | IPython CPU timings (estimated): | |
|
2277 | Total runs performed: 5 | |
|
2278 | Times : Total Per run | |
|
2279 | User : 0.910862 s, 0.1821724 s. | |
|
2280 |
|
|
|
2281 | ||
|
2282 | -d: run your program under the control of pdb, the Python debugger. This | |
|
2283 | allows you to execute your program step by step, watch variables, etc. | |
|
2284 | Internally, what IPython does is similar to calling: | |
|
2285 | ||
|
2286 | pdb.run('execfile("YOURFILENAME")') | |
|
2287 | ||
|
2288 | with a breakpoint set on line 1 of your file. You can change the line | |
|
2289 | number for this automatic breakpoint to be <N> by using the -bN option | |
|
2290 | (where N must be an integer). For example: | |
|
2291 | ||
|
2292 | %run -d -b40 myscript | |
|
2293 | ||
|
2294 | will set the first breakpoint at line 40 in myscript.py. Note that the | |
|
2295 | first breakpoint must be set on a line which actually does something | |
|
2296 | (not a comment or docstring) for it to stop execution. | |
|
2297 | ||
|
2298 | When the pdb debugger starts, you will see a (Pdb) prompt. You must | |
|
2299 | first enter 'c' (without qoutes) to start execution up to the first | |
|
2300 | breakpoint. | |
|
2301 | ||
|
2302 | Entering 'help' gives information about the use of the debugger. You can | |
|
2303 | easily see pdb's full documentation with "import pdb;pdb.help()" at a | |
|
2304 | prompt. | |
|
2305 | ||
|
2306 | -p: run program under the control of the Python profiler module (which | |
|
2307 | prints a detailed report of execution times, function calls, etc). | |
|
2308 | ||
|
2309 | You can pass other options after -p which affect the behavior of the | |
|
2310 | profiler itself. See the docs for %prun for details. | |
|
2311 | ||
|
2312 | In this mode, the program's variables do NOT propagate back to the | |
|
2313 | IPython interactive namespace (because they remain in the namespace | |
|
2314 | where the profiler executes them). | |
|
2315 | ||
|
2316 | Internally this triggers a call to %prun, see its documentation for | |
|
2317 | details on the options available specifically for profiling. | |
|
2318 | ||
|
2319 | There is one special usage for which the text above doesn't apply: if | |
|
2320 | the filename ends with .ipy, the file is run as ipython script, just as | |
|
2321 | if the commands were written on IPython prompt. | |
|
2322 | ||
|
2323 | ||
|
2324 | %runlog: Run files as logs. | |
|
2325 | ||
|
2326 | Usage: | |
|
2327 | %runlog file1 file2 ... | |
|
2328 | ||
|
2329 | Run the named files (treating them as log files) in sequence inside the | |
|
2330 | interpreter, and return to the prompt. This is much slower than %run | |
|
2331 | because each line is executed in a try/except block, but it allows | |
|
2332 | running files with syntax errors in them. | |
|
2333 | ||
|
2334 | Normally IPython will guess when a file is one of its own logfiles, so | |
|
2335 | you can typically use %run even for logs. This shorthand allows you to | |
|
2336 | force any file to be treated as a log file. | |
|
2337 | ||
|
2338 | ||
|
2339 | %save: Save a set of lines to a given filename. | |
|
2340 | ||
|
2341 | Usage: | |
|
2342 | %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ... | |
|
2343 | ||
|
2344 | Options: | |
|
2345 | ||
|
2346 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
2347 | that magics are loaded in their transformed version to valid Python. If | |
|
2348 | this option is given, the raw input as typed as the command line is used | |
|
2349 | instead. | |
|
2350 | ||
|
2351 | This function uses the same syntax as %macro for line extraction, but | |
|
2352 | instead of creating a macro it saves the resulting string to the | |
|
2353 | filename you specify. | |
|
2354 | ||
|
2355 | It adds a '.py' extension to the file if you don't do so yourself, and | |
|
2356 | it asks for confirmation before overwriting existing files. | |
|
2357 | ||
|
2358 | ||
|
2359 | %sc: Shell capture - execute a shell command and capture its output. | |
|
2360 | ||
|
2361 | DEPRECATED. Suboptimal, retained for backwards compatibility. | |
|
2362 | ||
|
2363 | You should use the form 'var = !command' instead. Example: | |
|
2364 | ||
|
2365 | "%sc -l myfiles = ls " should now be written as | |
|
2366 | ||
|
2367 | "myfiles = !ls " | |
|
2368 | ||
|
2369 | myfiles.s, myfiles.l and myfiles.n still apply as documented below. | |
|
2370 | ||
|
2371 | - %sc [options] varname=command | |
|
2372 | ||
|
2373 | IPython will run the given command using commands.getoutput(), and will | |
|
2374 | then update the user's interactive namespace with a variable called | |
|
2375 | varname, containing the value of the call. Your command can contain | |
|
2376 | shell wildcards, pipes, etc. | |
|
2377 | ||
|
2378 | The '=' sign in the syntax is mandatory, and the variable name you | |
|
2379 | supply must follow Python's standard conventions for valid names. | |
|
2380 | ||
|
2381 | (A special format without variable name exists for internal use) | |
|
2382 | ||
|
2383 | Options: | |
|
2384 | ||
|
2385 | -l: list output. Split the output on newlines into a list before | |
|
2386 | assigning it to the given variable. By default the output is stored as a | |
|
2387 | single string. | |
|
2388 | ||
|
2389 | -v: verbose. Print the contents of the variable. | |
|
2390 | ||
|
2391 | In most cases you should not need to split as a list, because the | |
|
2392 | returned value is a special type of string which can automatically | |
|
2393 | provide its contents either as a list (split on newlines) or as a | |
|
2394 | space-separated string. These are convenient, respectively, either for | |
|
2395 | sequential processing or to be passed to a shell command. | |
|
2396 | ||
|
2397 | For example: | |
|
2398 | ||
|
2399 | # Capture into variable a In [9]: sc a=ls *py | |
|
2400 | ||
|
2401 | # a is a string with embedded newlines In [10]: a Out[10]: 'setup.py | |
|
2402 | win32_manual_post_install.py' | |
|
2403 | ||
|
2404 | # which can be seen as a list: In [11]: a.l Out[11]: ['setup.py', | |
|
2405 | 'win32_manual_post_install.py'] | |
|
2406 | ||
|
2407 | # or as a whitespace-separated string: In [12]: a.s Out[12]: 'setup.py | |
|
2408 | win32_manual_post_install.py' | |
|
2409 | ||
|
2410 | # a.s is useful to pass as a single command line: In [13]: !wc -l $a.s | |
|
2411 | 146 setup.py 130 win32_manual_post_install.py 276 total | |
|
2412 | ||
|
2413 | # while the list form is useful to loop over: In [14]: for f in a.l: | |
|
2414 | ....: !wc -l $f ....: 146 setup.py 130 win32_manual_post_install.py | |
|
2415 | ||
|
2416 | Similiarly, the lists returned by the -l option are also special, in the | |
|
2417 | sense that you can equally invoke the .s attribute on them to | |
|
2418 | automatically get a whitespace-separated string from their contents: | |
|
2419 | ||
|
2420 | In [1]: sc -l b=ls *py | |
|
2421 | ||
|
2422 | In [2]: b Out[2]: ['setup.py', 'win32_manual_post_install.py'] | |
|
2423 | ||
|
2424 | In [3]: b.s Out[3]: 'setup.py win32_manual_post_install.py' | |
|
2425 | ||
|
2426 | In summary, both the lists and strings used for ouptut capture have the | |
|
2427 | following special attributes: | |
|
2428 | ||
|
2429 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2430 | newline-separated string. .s (or .spstr): value as space-separated string. | |
|
2431 | ||
|
2432 | ||
|
2433 | %sx: Shell execute - run a shell command and capture its output. | |
|
2434 | ||
|
2435 | %sx command | |
|
2436 | ||
|
2437 | IPython will run the given command using commands.getoutput(), and | |
|
2438 | return the result formatted as a list (split on '\n'). Since the output | |
|
2439 | is _returned_, it will be stored in ipython's regular output cache | |
|
2440 | Out[N] and in the '_N' automatic variables. | |
|
2441 | ||
|
2442 | Notes: | |
|
2443 | ||
|
2444 | 1) If an input line begins with '!!', then %sx is automatically invoked. | |
|
2445 | That is, while: !ls causes ipython to simply issue system('ls'), typing | |
|
2446 | !!ls is a shorthand equivalent to: %sx ls | |
|
2447 | ||
|
2448 | 2) %sx differs from %sc in that %sx automatically splits into a list, | |
|
2449 | like '%sc -l'. The reason for this is to make it as easy as possible to | |
|
2450 | process line-oriented shell output via further python commands. %sc is | |
|
2451 | meant to provide much finer control, but requires more typing. | |
|
2452 | ||
|
2453 | 3) Just like %sc -l, this is a list with special attributes: | |
|
2454 | ||
|
2455 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2456 | newline-separated string. .s (or .spstr): value as whitespace-separated | |
|
2457 | string. | |
|
2458 | ||
|
2459 | This is very useful when trying to use such lists as arguments to system | |
|
2460 | commands. | |
|
2461 | ||
|
2462 | ||
|
2463 | %system_verbose: Set verbose printing of system calls. | |
|
2464 | ||
|
2465 | If called without an argument, act as a toggle | |
|
2466 | ||
|
2467 | ||
|
2468 | %time: Time execution of a Python statement or expression. | |
|
2469 | ||
|
2470 | The CPU and wall clock times are printed, and the value of the | |
|
2471 | expression (if any) is returned. Note that under Win32, system time is | |
|
2472 | always reported as 0, since it can not be measured. | |
|
2473 | ||
|
2474 | This function provides very basic timing functionality. In Python 2.3, | |
|
2475 | the timeit module offers more control and sophistication, so this could | |
|
2476 | be rewritten to use it (patches welcome). | |
|
2477 | ||
|
2478 | Some examples: | |
|
2479 | ||
|
2480 | In [1]: time 2**128 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2481 | Wall time: 0.00 Out[1]: 340282366920938463463374607431768211456L | |
|
2482 | ||
|
2483 | In [2]: n = 1000000 | |
|
2484 | ||
|
2485 | In [3]: time sum(range(n)) CPU times: user 1.20 s, sys: 0.05 s, total: | |
|
2486 | 1.25 s Wall time: 1.37 Out[3]: 499999500000L | |
|
2487 | ||
|
2488 | In [4]: time print 'hello world' hello world CPU times: user 0.00 s, | |
|
2489 | sys: 0.00 s, total: 0.00 s Wall time: 0.00 | |
|
2490 | ||
|
2491 | Note that the time needed by Python to compile the given expression will | |
|
2492 | be reported if it is more than 0.1s. In this example, the actual | |
|
2493 | exponentiation is done by Python at compilation time, so while the | |
|
2494 | expression can take a noticeable amount of time to compute, that time is | |
|
2495 | purely due to the compilation: | |
|
2496 | ||
|
2497 | In [5]: time 3**9999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2498 | Wall time: 0.00 s | |
|
2499 | ||
|
2500 | In [6]: time 3**999999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 | |
|
2501 | s Wall time: 0.00 s Compiler : 0.78 s | |
|
2502 | ||
|
2503 | ||
|
2504 | %timeit: Time execution of a Python statement or expression | |
|
2505 | ||
|
2506 | Usage: | |
|
2507 | %timeit [-n<N> -r<R> [-t|-c]] statement | |
|
2508 | ||
|
2509 | Time execution of a Python statement or expression using the timeit module. | |
|
2510 | ||
|
2511 | Options: -n<N>: execute the given statement <N> times in a loop. If this | |
|
2512 | value is not given, a fitting value is chosen. | |
|
2513 | ||
|
2514 | -r<R>: repeat the loop iteration <R> times and take the best result. | |
|
2515 | Default: 3 | |
|
2516 | ||
|
2517 | -t: use time.time to measure the time, which is the default on Unix. | |
|
2518 | This function measures wall time. | |
|
2519 | ||
|
2520 | -c: use time.clock to measure the time, which is the default on Windows | |
|
2521 | and measures wall time. On Unix, resource.getrusage is used instead and | |
|
2522 | returns the CPU user time. | |
|
2523 | ||
|
2524 | -p<P>: use a precision of <P> digits to display the timing result. | |
|
2525 | Default: 3 | |
|
2526 | ||
|
2527 | Examples: | |
|
2528 | In [1]: %timeit pass 10000000 loops, best of 3: 53.3 ns per loop | |
|
2529 | ||
|
2530 | In [2]: u = None | |
|
2531 | ||
|
2532 | In [3]: %timeit u is None 10000000 loops, best of 3: 184 ns per loop | |
|
2533 | ||
|
2534 | In [4]: %timeit -r 4 u == None 1000000 loops, best of 4: 242 ns per loop | |
|
2535 | ||
|
2536 | In [5]: import time | |
|
2537 | ||
|
2538 | In [6]: %timeit -n1 time.sleep(2) 1 loops, best of 3: 2 s per loop | |
|
2539 | ||
|
2540 | The times reported by %timeit will be slightly higher than those | |
|
2541 | reported by the timeit.py script when variables are accessed. This is | |
|
2542 | due to the fact that %timeit executes the statement in the namespace of | |
|
2543 | the shell, compared with timeit.py, which uses a single setup statement | |
|
2544 | to import function or create variables. Generally, the bias does not | |
|
2545 | matter as long as results from timeit.py are not mixed with those from | |
|
2546 | %timeit. | |
|
2547 | ||
|
2548 | ||
|
2549 | %unalias: Remove an alias | |
|
2550 | ||
|
2551 | ||
|
2552 | %upgrade: Upgrade your IPython installation | |
|
2553 | ||
|
2554 | This will copy the config files that don't yet exist in your ipython dir | |
|
2555 | from the system config dir. Use this after upgrading IPython if you | |
|
2556 | don't wish to delete your .ipython dir. | |
|
2557 | ||
|
2558 | Call with -nolegacy to get rid of ipythonrc* files (recommended for new | |
|
2559 | users) | |
|
2560 | ||
|
2561 | ||
|
2562 | %who: Print all interactive variables, with some minimal formatting. | |
|
2563 | ||
|
2564 | If any arguments are given, only variables whose type matches one of | |
|
2565 | these are printed. For example: | |
|
2566 | ||
|
2567 | %who function str | |
|
2568 | ||
|
2569 | will only list functions and strings, excluding all other types of | |
|
2570 | variables. To find the proper type names, simply use type(var) at a | |
|
2571 | command line to see how python prints type names. For example: | |
|
2572 | ||
|
2573 | In [1]: type('hello') | |
|
2574 | Out[1]: <type 'str'> | |
|
2575 | ||
|
2576 | indicates that the type name for strings is 'str'. | |
|
2577 | ||
|
2578 | %who always excludes executed names loaded through your configuration | |
|
2579 | file and things which are internal to IPython. | |
|
2580 | ||
|
2581 | This is deliberate, as typically you may load many modules and the | |
|
2582 | purpose of %who is to show you only what you've manually defined. | |
|
2583 | ||
|
2584 | ||
|
2585 | %who_ls: Return a sorted list of all interactive variables. | |
|
2586 | ||
|
2587 | If arguments are given, only variables of types matching these arguments | |
|
2588 | are returned. | |
|
2589 | ||
|
2590 | ||
|
2591 | %whos: Like %who, but gives some extra information about each variable. | |
|
2592 | ||
|
2593 | The same type filtering of %who can be applied here. | |
|
2594 | ||
|
2595 | For all variables, the type is printed. Additionally it prints: | |
|
2596 | ||
|
2597 | - For ,[],(): their length. | |
|
2598 | ||
|
2599 | - For numpy and Numeric arrays, a summary with shape, number of | |
|
2600 | elements, typecode and size in memory. | |
|
2601 | ||
|
2602 | - Everything else: a string representation, snipping their middle if too | |
|
2603 | long. | |
|
2604 | ||
|
2605 | ||
|
2606 | %xmode: Switch modes for the exception handlers. | |
|
2607 | ||
|
2608 | Valid modes: Plain, Context and Verbose. | |
|
2609 | ||
|
2610 | If called without arguments, acts as a toggle. | |
|
2611 | ||
|
2612 | ||
|
2613 | Access to the standard Python help | |
|
1376 | :: | |
|
1377 | ||
|
1378 | %Exit: Exit IPython without confirmation. | |
|
1379 | ||
|
1380 | ||
|
1381 | %Pprint: Toggle pretty printing on/off. | |
|
1382 | ||
|
1383 | ||
|
1384 | %alias: Define an alias for a system command. | |
|
1385 | ||
|
1386 | '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd' | |
|
1387 | ||
|
1388 | Then, typing 'alias_name params' will execute the system command 'cmd | |
|
1389 | params' (from your underlying operating system). | |
|
1390 | ||
|
1391 | Aliases have lower precedence than magic functions and Python normal | |
|
1392 | variables, so if 'foo' is both a Python variable and an alias, the alias | |
|
1393 | can not be executed until 'del foo' removes the Python variable. | |
|
1394 | ||
|
1395 | You can use the %l specifier in an alias definition to represent the | |
|
1396 | whole line when the alias is called. For example: | |
|
1397 | ||
|
1398 | In [2]: alias all echo "Input in brackets: <%l>" | |
|
1399 | In [3]: all hello world | |
|
1400 | Input in brackets: <hello world> | |
|
1401 | ||
|
1402 | You can also define aliases with parameters using %s specifiers (one per | |
|
1403 | parameter): | |
|
1404 | ||
|
1405 | In [1]: alias parts echo first %s second %s | |
|
1406 | In [2]: %parts A B | |
|
1407 | first A second B | |
|
1408 | In [3]: %parts A | |
|
1409 | Incorrect number of arguments: 2 expected. | |
|
1410 | parts is an alias to: 'echo first %s second %s' | |
|
1411 | ||
|
1412 | Note that %l and %s are mutually exclusive. You can only use one or the | |
|
1413 | other in your aliases. | |
|
1414 | ||
|
1415 | Aliases expand Python variables just like system calls using ! or !! do: | |
|
1416 | all expressions prefixed with '$' get expanded. For details of the | |
|
1417 | semantic rules, see PEP-215: http://www.python.org/peps/pep-0215.html. | |
|
1418 | This is the library used by IPython for variable expansion. If you want | |
|
1419 | to access a true shell variable, an extra $ is necessary to prevent its | |
|
1420 | expansion by IPython: | |
|
1421 | ||
|
1422 | In [6]: alias show echo | |
|
1423 | In [7]: PATH='A Python string' | |
|
1424 | In [8]: show $PATH | |
|
1425 | A Python string | |
|
1426 | In [9]: show $$PATH | |
|
1427 | /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:... | |
|
1428 | ||
|
1429 | You can use the alias facility to acess all of $PATH. See the %rehash | |
|
1430 | and %rehashx functions, which automatically create aliases for the | |
|
1431 | contents of your $PATH. | |
|
1432 | ||
|
1433 | If called with no parameters, %alias prints the current alias table. | |
|
1434 | ||
|
1435 | ||
|
1436 | %autocall: Make functions callable without having to type parentheses. | |
|
1437 | ||
|
1438 | Usage: | |
|
1439 | ||
|
1440 | %autocall [mode] | |
|
1441 | ||
|
1442 | The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the | |
|
1443 | value is toggled on and off (remembering the previous state). | |
|
1444 | ||
|
1445 | In more detail, these values mean: | |
|
1446 | ||
|
1447 | 0 -> fully disabled | |
|
1448 | ||
|
1449 | 1 -> active, but do not apply if there are no arguments on the line. | |
|
1450 | ||
|
1451 | In this mode, you get: | |
|
1452 | ||
|
1453 | In [1]: callable Out[1]: <built-in function callable> | |
|
1454 | ||
|
1455 | In [2]: callable 'hello' ---> callable('hello') Out[2]: False | |
|
1456 | ||
|
1457 | 2 -> Active always. Even if no arguments are present, the callable | |
|
1458 | object is called: | |
|
1459 | ||
|
1460 | In [4]: callable ---> callable() | |
|
1461 | ||
|
1462 | Note that even with autocall off, you can still use '/' at the start of | |
|
1463 | a line to treat the first argument on the command line as a function and | |
|
1464 | add parentheses to it: | |
|
1465 | ||
|
1466 | In [8]: /str 43 ---> str(43) Out[8]: '43' | |
|
1467 | ||
|
1468 | ||
|
1469 | %autoindent: Toggle autoindent on/off (if available). | |
|
1470 | ||
|
1471 | ||
|
1472 | %automagic: Make magic functions callable without having to type the | |
|
1473 | initial %. | |
|
1474 | ||
|
1475 | Without argumentsl toggles on/off (when off, you must call it as | |
|
1476 | %automagic, of course). With arguments it sets the value, and you can | |
|
1477 | use any of (case insensitive): | |
|
1478 | ||
|
1479 | - on,1,True: to activate | |
|
1480 | ||
|
1481 | - off,0,False: to deactivate. | |
|
1482 | ||
|
1483 | Note that magic functions have lowest priority, so if there's a variable | |
|
1484 | whose name collides with that of a magic fn, automagic won't work for | |
|
1485 | that function (you get the variable instead). However, if you delete the | |
|
1486 | variable (del var), the previously shadowed magic function becomes | |
|
1487 | visible to automagic again. | |
|
1488 | ||
|
1489 | ||
|
1490 | %bg: Run a job in the background, in a separate thread. | |
|
1491 | ||
|
1492 | For example, | |
|
1493 | ||
|
1494 | %bg myfunc(x,y,z=1) | |
|
1495 | ||
|
1496 | will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the | |
|
1497 | execution starts, a message will be printed indicating the job number. | |
|
1498 | If your job number is 5, you can use | |
|
1499 | ||
|
1500 | myvar = jobs.result(5) or myvar = jobs[5].result | |
|
1501 | ||
|
1502 | to assign this result to variable 'myvar'. | |
|
1503 | ||
|
1504 | IPython has a job manager, accessible via the 'jobs' object. You can | |
|
1505 | type jobs? to get more information about it, and use jobs.<TAB> to see | |
|
1506 | its attributes. All attributes not starting with an underscore are meant | |
|
1507 | for public use. | |
|
1508 | ||
|
1509 | In particular, look at the jobs.new() method, which is used to create | |
|
1510 | new jobs. This magic %bg function is just a convenience wrapper around | |
|
1511 | jobs.new(), for expression-based jobs. If you want to create a new job | |
|
1512 | with an explicit function object and arguments, you must call jobs.new() | |
|
1513 | directly. | |
|
1514 | ||
|
1515 | The jobs.new docstring also describes in detail several important | |
|
1516 | caveats associated with a thread-based model for background job | |
|
1517 | execution. Type jobs.new? for details. | |
|
1518 | ||
|
1519 | You can check the status of all jobs with jobs.status(). | |
|
1520 | ||
|
1521 | The jobs variable is set by IPython into the Python builtin namespace. | |
|
1522 | If you ever declare a variable named 'jobs', you will shadow this name. | |
|
1523 | You can either delete your global jobs variable to regain access to the | |
|
1524 | job manager, or make a new name and assign it manually to the manager | |
|
1525 | (stored in IPython's namespace). For example, to assign the job manager | |
|
1526 | to the Jobs name, use: | |
|
1527 | ||
|
1528 | Jobs = __builtins__.jobs | |
|
1529 | ||
|
1530 | ||
|
1531 | %bookmark: Manage IPython's bookmark system. | |
|
1532 | ||
|
1533 | %bookmark <name> - set bookmark to current dir %bookmark <name> <dir> - | |
|
1534 | set bookmark to <dir> %bookmark -l - list all bookmarks %bookmark -d | |
|
1535 | <name> - remove bookmark %bookmark -r - remove all bookmarks | |
|
1536 | ||
|
1537 | You can later on access a bookmarked folder with: %cd -b <name> or | |
|
1538 | simply '%cd <name>' if there is no directory called <name> AND there is | |
|
1539 | such a bookmark defined. | |
|
1540 | ||
|
1541 | Your bookmarks persist through IPython sessions, but they are associated | |
|
1542 | with each profile. | |
|
1543 | ||
|
1544 | ||
|
1545 | %cd: Change the current working directory. | |
|
1546 | ||
|
1547 | This command automatically maintains an internal list of directories you | |
|
1548 | visit during your IPython session, in the variable _dh. The command | |
|
1549 | %dhist shows this history nicely formatted. You can also do 'cd -<tab>' | |
|
1550 | to see directory history conveniently. | |
|
1551 | ||
|
1552 | Usage: | |
|
1553 | ||
|
1554 | cd 'dir': changes to directory 'dir'. | |
|
1555 | ||
|
1556 | cd -: changes to the last visited directory. | |
|
1557 | ||
|
1558 | cd -<n>: changes to the n-th directory in the directory history. | |
|
1559 | ||
|
1560 | cd -b <bookmark_name>: jump to a bookmark set by %bookmark (note: cd | |
|
1561 | <bookmark_name> is enough if there is no directory <bookmark_name>, but | |
|
1562 | a bookmark with the name exists.) 'cd -b <tab>' allows you to | |
|
1563 | tab-complete bookmark names. | |
|
1564 | ||
|
1565 | Options: | |
|
1566 | ||
|
1567 | -q: quiet. Do not print the working directory after the cd command is | |
|
1568 | executed. By default IPython's cd command does print this directory, | |
|
1569 | since the default prompts do not display path information. | |
|
1570 | ||
|
1571 | Note that !cd doesn't work for this purpose because the shell where | |
|
1572 | !command runs is immediately discarded after executing 'command'. | |
|
1573 | ||
|
1574 | ||
|
1575 | %color_info: Toggle color_info. | |
|
1576 | ||
|
1577 | The color_info configuration parameter controls whether colors are used | |
|
1578 | for displaying object details (by things like %psource, %pfile or the | |
|
1579 | '?' system). This function toggles this value with each call. | |
|
1580 | ||
|
1581 | Note that unless you have a fairly recent pager (less works better than | |
|
1582 | more) in your system, using colored object information displays will not | |
|
1583 | work properly. Test it and see. | |
|
1584 | ||
|
1585 | ||
|
1586 | %colors: Switch color scheme for prompts, info system and exception | |
|
1587 | handlers. | |
|
1588 | ||
|
1589 | Currently implemented schemes: NoColor, Linux, LightBG. | |
|
1590 | ||
|
1591 | Color scheme names are not case-sensitive. | |
|
1592 | ||
|
1593 | ||
|
1594 | %cpaste: Allows you to paste & execute a pre-formatted code block from | |
|
1595 | clipboard | |
|
1596 | ||
|
1597 | You must terminate the block with '-' (two minus-signs) alone on the | |
|
1598 | line. You can also provide your own sentinel with '%paste -s %%' ('%%' | |
|
1599 | is the new sentinel for this operation) | |
|
1600 | ||
|
1601 | The block is dedented prior to execution to enable execution of method | |
|
1602 | definitions. '>' and '+' characters at the beginning of a line are | |
|
1603 | ignored, to allow pasting directly from e-mails or diff files. The | |
|
1604 | executed block is also assigned to variable named 'pasted_block' for | |
|
1605 | later editing with '%edit pasted_block'. | |
|
1606 | ||
|
1607 | You can also pass a variable name as an argument, e.g. '%cpaste foo'. | |
|
1608 | This assigns the pasted block to variable 'foo' as string, without | |
|
1609 | dedenting or executing it. | |
|
1610 | ||
|
1611 | Do not be alarmed by garbled output on Windows (it's a readline bug). | |
|
1612 | Just press enter and type - (and press enter again) and the block will | |
|
1613 | be what was just pasted. | |
|
1614 | ||
|
1615 | IPython statements (magics, shell escapes) are not supported (yet). | |
|
1616 | ||
|
1617 | ||
|
1618 | %debug: Activate the interactive debugger in post-mortem mode. | |
|
1619 | ||
|
1620 | If an exception has just occurred, this lets you inspect its stack | |
|
1621 | frames interactively. Note that this will always work only on the last | |
|
1622 | traceback that occurred, so you must call this quickly after an | |
|
1623 | exception that you wish to inspect has fired, because if another one | |
|
1624 | occurs, it clobbers the previous one. | |
|
1625 | ||
|
1626 | If you want IPython to automatically do this on every exception, see the | |
|
1627 | %pdb magic for more details. | |
|
1628 | ||
|
1629 | ||
|
1630 | %dhist: Print your history of visited directories. | |
|
1631 | ||
|
1632 | %dhist -> print full history | |
|
1633 | %dhist n -> print last n entries only | |
|
1634 | %dhist n1 n2 -> print entries between n1 and n2 (n1 not included) | |
|
1635 | ||
|
1636 | This history is automatically maintained by the %cd command, and always | |
|
1637 | available as the global list variable _dh. You can use %cd -<n> to go to | |
|
1638 | directory number <n>. | |
|
1639 | ||
|
1640 | Note that most of time, you should view directory history by entering cd | |
|
1641 | -<TAB>. | |
|
1642 | ||
|
1643 | ||
|
1644 | %dirs: Return the current directory stack. | |
|
1645 | ||
|
1646 | ||
|
1647 | %doctest_mode: Toggle doctest mode on and off. | |
|
1648 | ||
|
1649 | This mode allows you to toggle the prompt behavior between normal | |
|
1650 | IPython prompts and ones that are as similar to the default IPython | |
|
1651 | interpreter as possible. | |
|
1652 | ||
|
1653 | It also supports the pasting of code snippets that have leading '»>' and | |
|
1654 | '...' prompts in them. This means that you can paste doctests from files | |
|
1655 | or docstrings (even if they have leading whitespace), and the code will | |
|
1656 | execute correctly. You can then use '%history -tn' to see the translated | |
|
1657 | history without line numbers; this will give you the input after removal | |
|
1658 | of all the leading prompts and whitespace, which can be pasted back into | |
|
1659 | an editor. | |
|
1660 | ||
|
1661 | With these features, you can switch into this mode easily whenever you | |
|
1662 | need to do testing and changes to doctests, without having to leave your | |
|
1663 | existing IPython session. | |
|
1664 | ||
|
1665 | ||
|
1666 | %ed: Alias to %edit. | |
|
1667 | ||
|
1668 | ||
|
1669 | %edit: Bring up an editor and execute the resulting code. | |
|
1670 | ||
|
1671 | Usage: %edit [options] [args] | |
|
1672 | ||
|
1673 | %edit runs IPython's editor hook. The default version of this hook is | |
|
1674 | set to call the __IPYTHON__.rc.editor command. This is read from your | |
|
1675 | environment variable $EDITOR. If this isn't found, it will default to vi | |
|
1676 | under Linux/Unix and to notepad under Windows. See the end of this | |
|
1677 | docstring for how to change the editor hook. | |
|
1678 | ||
|
1679 | You can also set the value of this editor via the command line option | |
|
1680 | '-editor' or in your ipythonrc file. This is useful if you wish to use | |
|
1681 | specifically for IPython an editor different from your typical default | |
|
1682 | (and for Windows users who typically don't set environment variables). | |
|
1683 | ||
|
1684 | This command allows you to conveniently edit multi-line code right in | |
|
1685 | your IPython session. | |
|
1686 | ||
|
1687 | If called without arguments, %edit opens up an empty editor with a | |
|
1688 | temporary file and will execute the contents of this file when you close | |
|
1689 | it (don't forget to save it!). | |
|
1690 | ||
|
1691 | Options: | |
|
1692 | ||
|
1693 | -n <number>: open the editor at a specified line number. By default, the | |
|
1694 | IPython editor hook uses the unix syntax 'editor +N filename', but you | |
|
1695 | can configure this by providing your own modified hook if your favorite | |
|
1696 | editor supports line-number specifications with a different syntax. | |
|
1697 | ||
|
1698 | -p: this will call the editor with the same data as the previous time it | |
|
1699 | was used, regardless of how long ago (in your current session) it was. | |
|
1700 | ||
|
1701 | -r: use 'raw' input. This option only applies to input taken from the | |
|
1702 | user's history. By default, the 'processed' history is used, so that | |
|
1703 | magics are loaded in their transformed version to valid Python. If this | |
|
1704 | option is given, the raw input as typed as the command line is used | |
|
1705 | instead. When you exit the editor, it will be executed by IPython's own | |
|
1706 | processor. | |
|
1707 | ||
|
1708 | -x: do not execute the edited code immediately upon exit. This is mainly | |
|
1709 | useful if you are editing programs which need to be called with command | |
|
1710 | line arguments, which you can then do using %run. | |
|
1711 | ||
|
1712 | Arguments: | |
|
1713 | ||
|
1714 | If arguments are given, the following possibilites exist: | |
|
1715 | ||
|
1716 | - The arguments are numbers or pairs of dash-separated numbers (like 1 | |
|
1717 | 4-8 9). These are interpreted as lines of previous input to be loaded | |
|
1718 | into the editor. The syntax is the same of the %macro command. | |
|
1719 | ||
|
1720 | - If the argument doesn't start with a number, it is evaluated as a | |
|
1721 | variable and its contents loaded into the editor. You can thus edit any | |
|
1722 | string which contains python code (including the result of previous edits). | |
|
1723 | ||
|
1724 | - If the argument is the name of an object (other than a string), | |
|
1725 | IPython will try to locate the file where it was defined and open the | |
|
1726 | editor at the point where it is defined. You can use '%edit function' to | |
|
1727 | load an editor exactly at the point where 'function' is defined, edit it | |
|
1728 | and have the file be executed automatically. | |
|
1729 | ||
|
1730 | If the object is a macro (see %macro for details), this opens up your | |
|
1731 | specified editor with a temporary file containing the macro's data. Upon | |
|
1732 | exit, the macro is reloaded with the contents of the file. | |
|
1733 | ||
|
1734 | Note: opening at an exact line is only supported under Unix, and some | |
|
1735 | editors (like kedit and gedit up to Gnome 2.8) do not understand the | |
|
1736 | '+NUMBER' parameter necessary for this feature. Good editors like | |
|
1737 | (X)Emacs, vi, jed, pico and joe all do. | |
|
1738 | ||
|
1739 | If the argument is not found as a variable, IPython will look for a | |
|
1740 | file with that name (adding .py if necessary) and load it into the | |
|
1741 | editor. It will execute its contents with execfile() when you exit, | |
|
1742 | loading any code in the file into your interactive namespace. | |
|
1743 | ||
|
1744 | After executing your code, %edit will return as output the code you | |
|
1745 | typed in the editor (except when it was an existing file). This way you | |
|
1746 | can reload the code in further invocations of %edit as a variable, via | |
|
1747 | _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the | |
|
1748 | output. | |
|
1749 | ||
|
1750 | Note that %edit is also available through the alias %ed. | |
|
1751 | ||
|
1752 | This is an example of creating a simple function inside the editor and | |
|
1753 | then modifying it. First, start up the editor:: | |
|
1754 | ||
|
1755 | In [1]: ed | |
|
1756 | Editing... done. Executing edited code... | |
|
1757 | Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n' | |
|
1758 | ||
|
1759 | We can then call the function foo(): | |
|
1760 | ||
|
1761 | In [2]: foo() | |
|
1762 | foo() was defined in an editing session | |
|
1763 | ||
|
1764 | Now we edit foo. IPython automatically loads the editor with the | |
|
1765 | (temporary) file where foo() was previously defined: | |
|
1766 | ||
|
1767 | In [3]: ed foo | |
|
1768 | Editing... done. Executing edited code... | |
|
1769 | ||
|
1770 | And if we call foo() again we get the modified version: | |
|
1771 | ||
|
1772 | In [4]: foo() | |
|
1773 | foo() has now been changed! | |
|
1774 | ||
|
1775 | Here is an example of how to edit a code snippet successive times. First | |
|
1776 | we call the editor: | |
|
1777 | ||
|
1778 | In [8]: ed | |
|
1779 | Editing... done. Executing edited code... | |
|
1780 | hello | |
|
1781 | Out[8]: "print 'hello'\n" | |
|
1782 | ||
|
1783 | Now we call it again with the previous output (stored in _): | |
|
1784 | ||
|
1785 | In [9]: ed _ | |
|
1786 | Editing... done. Executing edited code... | |
|
1787 | hello world | |
|
1788 | Out[9]: "print 'hello world'\n" | |
|
1789 | ||
|
1790 | Now we call it with the output #8 (stored in _8, also as Out[8]): | |
|
1791 | ||
|
1792 | In [10]: ed _8 | |
|
1793 | Editing... done. Executing edited code... | |
|
1794 | hello again | |
|
1795 | Out[10]: "print 'hello again'\n" | |
|
1796 | ||
|
1797 | Changing the default editor hook: | |
|
1798 | ||
|
1799 | If you wish to write your own editor hook, you can put it in a | |
|
1800 | configuration file which you load at startup time. The default hook is | |
|
1801 | defined in the IPython.hooks module, and you can use that as a starting | |
|
1802 | example for further modifications. That file also has general | |
|
1803 | instructions on how to set a new hook for use once you've defined it. | |
|
1804 | ||
|
1805 | ||
|
1806 | %env: List environment variables. | |
|
1807 | ||
|
1808 | ||
|
1809 | %exit: Exit IPython, confirming if configured to do so. | |
|
1810 | ||
|
1811 | You can configure whether IPython asks for confirmation upon exit by | |
|
1812 | setting the confirm_exit flag in the ipythonrc file. | |
|
1813 | ||
|
1814 | ||
|
1815 | %logoff: Temporarily stop logging. | |
|
1816 | ||
|
1817 | You must have previously started logging. | |
|
1818 | ||
|
1819 | ||
|
1820 | %logon: Restart logging. | |
|
1821 | ||
|
1822 | This function is for restarting logging which you've temporarily stopped | |
|
1823 | with %logoff. For starting logging for the first time, you must use the | |
|
1824 | %logstart function, which allows you to specify an optional log filename. | |
|
1825 | ||
|
1826 | ||
|
1827 | %logstart: Start logging anywhere in a session. | |
|
1828 | ||
|
1829 | %logstart [-o|-r|-t] [log_name [log_mode]] | |
|
1830 | ||
|
1831 | If no name is given, it defaults to a file named 'ipython_log.py' in | |
|
1832 | your current directory, in 'rotate' mode (see below). | |
|
1833 | ||
|
1834 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your | |
|
1835 | history up to that point and then continues logging. | |
|
1836 | ||
|
1837 | %logstart takes a second optional parameter: logging mode. This can be | |
|
1838 | one of (note that the modes are given unquoted): | |
|
1839 | append: well, that says it. | |
|
1840 | backup: rename (if exists) to name and start name. | |
|
1841 | global: single logfile in your home dir, appended to. | |
|
1842 | over : overwrite existing log. | |
|
1843 | rotate: create rotating logs name.1 , name.2 , etc. | |
|
1844 | ||
|
1845 | Options: | |
|
1846 | ||
|
1847 | -o: log also IPython's output. In this mode, all commands which generate | |
|
1848 | an Out[NN] prompt are recorded to the logfile, right after their | |
|
1849 | corresponding input line. The output lines are always prepended with a | |
|
1850 | '#[Out]# ' marker, so that the log remains valid Python code. | |
|
1851 | ||
|
1852 | Since this marker is always the same, filtering only the output from a | |
|
1853 | log is very easy, using for example a simple awk call: | |
|
1854 | ||
|
1855 | awk -F'# | |
|
1856 | ||
|
1857 | \begin{displaymath}Out\end{displaymath} | |
|
1858 | ||
|
1859 | # ' 'if($2) print $2' ipython_log.py | |
|
1860 | ||
|
1861 | -r: log 'raw' input. Normally, IPython's logs contain the processed | |
|
1862 | input, so that user lines are logged in their final form, converted into | |
|
1863 | valid Python. For example, %Exit is logged as '_ip.magic("Exit"). If the | |
|
1864 | -r flag is given, all input is logged exactly as typed, with no | |
|
1865 | transformations applied. | |
|
1866 | ||
|
1867 | -t: put timestamps before each input line logged (these are put in | |
|
1868 | comments). | |
|
1869 | ||
|
1870 | ||
|
1871 | %logstate: Print the status of the logging system. | |
|
1872 | ||
|
1873 | ||
|
1874 | %logstop: Fully stop logging and close log file. | |
|
1875 | ||
|
1876 | In order to start logging again, a new %logstart call needs to be made, | |
|
1877 | possibly (though not necessarily) with a new filename, mode and other | |
|
1878 | options. | |
|
1879 | ||
|
1880 | ||
|
1881 | %lsmagic: List currently available magic functions. | |
|
1882 | ||
|
1883 | ||
|
1884 | %macro: Define a set of input lines as a macro for future re-execution. | |
|
1885 | ||
|
1886 | Usage: | |
|
1887 | %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ... | |
|
1888 | ||
|
1889 | Options: | |
|
1890 | ||
|
1891 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
1892 | that magics are loaded in their transformed version to valid Python. If | |
|
1893 | this option is given, the raw input as typed as the command line is used | |
|
1894 | instead. | |
|
1895 | ||
|
1896 | This will define a global variable called 'name' which is a string made | |
|
1897 | of joining the slices and lines you specify (n1,n2,... numbers above) | |
|
1898 | from your input history into a single string. This variable acts like an | |
|
1899 | automatic function which re-executes those lines as if you had typed | |
|
1900 | them. You just type 'name' at the prompt and the code executes. | |
|
1901 | ||
|
1902 | The notation for indicating number ranges is: n1-n2 means 'use line | |
|
1903 | numbers n1,...n2' (the endpoint is included). That is, '5-7' means using | |
|
1904 | the lines numbered 5,6 and 7. | |
|
1905 | ||
|
1906 | Note: as a 'hidden' feature, you can also use traditional python slice | |
|
1907 | notation, where N:M means numbers N through M-1. | |
|
1908 | ||
|
1909 | For example, if your history contains (%hist prints it): | |
|
1910 | ||
|
1911 | 44: x=1 | |
|
1912 | 45: y=3 | |
|
1913 | 46: z=x+y | |
|
1914 | 47: print x | |
|
1915 | 48: a=5 | |
|
1916 | 49: print 'x',x,'y',y | |
|
1917 | ||
|
1918 | you can create a macro with lines 44 through 47 (included) and line 49 | |
|
1919 | called my_macro with: | |
|
1920 | ||
|
1921 | In [51]: %macro my_macro 44-47 49 | |
|
1922 | ||
|
1923 | Now, typing 'my_macro' (without quotes) will re-execute all this code in | |
|
1924 | one pass. | |
|
1925 | ||
|
1926 | You don't need to give the line-numbers in order, and any given line | |
|
1927 | number can appear multiple times. You can assemble macros with any lines | |
|
1928 | from your input history in any order. | |
|
1929 | ||
|
1930 | The macro is a simple object which holds its value in an attribute, but | |
|
1931 | IPython's display system checks for macros and executes them as code | |
|
1932 | instead of printing them when you type their name. | |
|
1933 | ||
|
1934 | You can view a macro's contents by explicitly printing it with: | |
|
1935 | ||
|
1936 | 'print macro_name'. | |
|
1937 | ||
|
1938 | For one-off cases which DON'T contain magic function calls in them you | |
|
1939 | can obtain similar results by explicitly executing slices from your | |
|
1940 | input history with: | |
|
1941 | ||
|
1942 | In [60]: exec In[44:48]+In[49] | |
|
1943 | ||
|
1944 | ||
|
1945 | %magic: Print information about the magic function system. | |
|
1946 | ||
|
1947 | ||
|
1948 | %page: Pretty print the object and display it through a pager. | |
|
1949 | ||
|
1950 | %page [options] OBJECT | |
|
1951 | ||
|
1952 | If no object is given, use _ (last output). | |
|
1953 | ||
|
1954 | Options: | |
|
1955 | ||
|
1956 | -r: page str(object), don't pretty-print it. | |
|
1957 | ||
|
1958 | ||
|
1959 | %pdb: Control the automatic calling of the pdb interactive debugger. | |
|
1960 | ||
|
1961 | Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without | |
|
1962 | argument it works as a toggle. | |
|
1963 | ||
|
1964 | When an exception is triggered, IPython can optionally call the | |
|
1965 | interactive pdb debugger after the traceback printout. %pdb toggles this | |
|
1966 | feature on and off. | |
|
1967 | ||
|
1968 | The initial state of this feature is set in your ipythonrc configuration | |
|
1969 | file (the variable is called 'pdb'). | |
|
1970 | ||
|
1971 | If you want to just activate the debugger AFTER an exception has fired, | |
|
1972 | without having to type '%pdb on' and rerunning your code, you can use | |
|
1973 | the %debug magic. | |
|
1974 | ||
|
1975 | ||
|
1976 | %pdef: Print the definition header for any callable object. | |
|
1977 | ||
|
1978 | If the object is a class, print the constructor information. | |
|
1979 | ||
|
1980 | ||
|
1981 | %pdoc: Print the docstring for an object. | |
|
1982 | ||
|
1983 | If the given object is a class, it will print both the class and the | |
|
1984 | constructor docstrings. | |
|
1985 | ||
|
1986 | ||
|
1987 | %pfile: Print (or run through pager) the file where an object is defined. | |
|
1988 | ||
|
1989 | The file opens at the line where the object definition begins. IPython | |
|
1990 | will honor the environment variable PAGER if set, and otherwise will do | |
|
1991 | its best to print the file in a convenient form. | |
|
1992 | ||
|
1993 | If the given argument is not an object currently defined, IPython will | |
|
1994 | try to interpret it as a filename (automatically adding a .py extension | |
|
1995 | if needed). You can thus use %pfile as a syntax highlighting code viewer. | |
|
1996 | ||
|
1997 | ||
|
1998 | %pinfo: Provide detailed information about an object. | |
|
1999 | ||
|
2000 | '%pinfo object' is just a synonym for object? or ?object. | |
|
2001 | ||
|
2002 | ||
|
2003 | %popd: Change to directory popped off the top of the stack. | |
|
2004 | ||
|
2005 | ||
|
2006 | %profile: Print your currently active IPyhton profile. | |
|
2007 | ||
|
2008 | ||
|
2009 | %prun: Run a statement through the python code profiler. | |
|
2010 | ||
|
2011 | Usage: | |
|
2012 | %prun [options] statement | |
|
2013 | ||
|
2014 | The given statement (which doesn't require quote marks) is run via the | |
|
2015 | python profiler in a manner similar to the profile.run() function. | |
|
2016 | Namespaces are internally managed to work correctly; profile.run cannot | |
|
2017 | be used in IPython because it makes certain assumptions about namespaces | |
|
2018 | which do not hold under IPython. | |
|
2019 | ||
|
2020 | Options: | |
|
2021 | ||
|
2022 | -l <limit>: you can place restrictions on what or how much of the | |
|
2023 | profile gets printed. The limit value can be: | |
|
2024 | ||
|
2025 | * A string: only information for function names containing this string | |
|
2026 | is printed. | |
|
2027 | ||
|
2028 | * An integer: only these many lines are printed. | |
|
2029 | ||
|
2030 | * A float (between 0 and 1): this fraction of the report is printed (for | |
|
2031 | example, use a limit of 0.4 to see the topmost 40% only). | |
|
2032 | ||
|
2033 | You can combine several limits with repeated use of the option. For | |
|
2034 | example, '-l __init__ -l 5' will print only the topmost 5 lines of | |
|
2035 | information about class constructors. | |
|
2036 | ||
|
2037 | -r: return the pstats.Stats object generated by the profiling. This | |
|
2038 | object has all the information about the profile in it, and you can | |
|
2039 | later use it for further analysis or in other functions. | |
|
2040 | ||
|
2041 | -s <key>: sort profile by given key. You can provide more than one key | |
|
2042 | by using the option several times: '-s key1 -s key2 -s key3...'. The | |
|
2043 | default sorting key is 'time'. | |
|
2044 | ||
|
2045 | The following is copied verbatim from the profile documentation | |
|
2046 | referenced below: | |
|
2047 | ||
|
2048 | When more than one key is provided, additional keys are used as | |
|
2049 | secondary criteria when the there is equality in all keys selected | |
|
2050 | before them. | |
|
2051 | ||
|
2052 | Abbreviations can be used for any key names, as long as the abbreviation | |
|
2053 | is unambiguous. The following are the keys currently defined: | |
|
2054 | ||
|
2055 | Valid Arg Meaning | |
|
2056 | "calls" call count | |
|
2057 | "cumulative" cumulative time | |
|
2058 | "file" file name | |
|
2059 | "module" file name | |
|
2060 | "pcalls" primitive call count | |
|
2061 | "line" line number | |
|
2062 | "name" function name | |
|
2063 | "nfl" name/file/line | |
|
2064 | "stdname" standard name | |
|
2065 | "time" internal time | |
|
2066 | ||
|
2067 | Note that all sorts on statistics are in descending order (placing most | |
|
2068 | time consuming items first), where as name, file, and line number | |
|
2069 | searches are in ascending order (i.e., alphabetical). The subtle | |
|
2070 | distinction between "nfl" and "stdname" is that the standard name is a | |
|
2071 | sort of the name as printed, which means that the embedded line numbers | |
|
2072 | get compared in an odd way. For example, lines 3, 20, and 40 would (if | |
|
2073 | the file names were the same) appear in the string order "20" "3" and | |
|
2074 | "40". In contrast, "nfl" does a numeric compare of the line numbers. In | |
|
2075 | fact, sort_stats("nfl") is the same as sort_stats("name", "file", "line"). | |
|
2076 | ||
|
2077 | -T <filename>: save profile results as shown on screen to a text file. | |
|
2078 | The profile is still shown on screen. | |
|
2079 | ||
|
2080 | -D <filename>: save (via dump_stats) profile statistics to given | |
|
2081 | filename. This data is in a format understod by the pstats module, and | |
|
2082 | is generated by a call to the dump_stats() method of profile objects. | |
|
2083 | The profile is still shown on screen. | |
|
2084 | ||
|
2085 | If you want to run complete programs under the profiler's control, use | |
|
2086 | '%run -p [prof_opts] filename.py [args to program]' where prof_opts | |
|
2087 | contains profiler specific options as described here. | |
|
2088 | ||
|
2089 | You can read the complete documentation for the profile module with: | |
|
2090 | In [1]: import profile; profile.help() | |
|
2091 | ||
|
2092 | ||
|
2093 | %psearch: Search for object in namespaces by wildcard. | |
|
2094 | ||
|
2095 | %psearch [options] PATTERN [OBJECT TYPE] | |
|
2096 | ||
|
2097 | Note: ? can be used as a synonym for %psearch, at the beginning or at | |
|
2098 | the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the | |
|
2099 | rest of the command line must be unchanged (options come first), so for | |
|
2100 | example the following forms are equivalent | |
|
2101 | ||
|
2102 | %psearch -i a* function -i a* function? ?-i a* function | |
|
2103 | ||
|
2104 | Arguments: | |
|
2105 | ||
|
2106 | PATTERN | |
|
2107 | ||
|
2108 | where PATTERN is a string containing * as a wildcard similar to its use | |
|
2109 | in a shell. The pattern is matched in all namespaces on the search path. | |
|
2110 | By default objects starting with a single _ are not matched, many | |
|
2111 | IPython generated objects have a single underscore. The default is case | |
|
2112 | insensitive matching. Matching is also done on the attributes of objects | |
|
2113 | and not only on the objects in a module. | |
|
2114 | ||
|
2115 | [OBJECT TYPE] | |
|
2116 | ||
|
2117 | Is the name of a python type from the types module. The name is given in | |
|
2118 | lowercase without the ending type, ex. StringType is written string. By | |
|
2119 | adding a type here only objects matching the given type are matched. | |
|
2120 | Using all here makes the pattern match all types (this is the default). | |
|
2121 | ||
|
2122 | Options: | |
|
2123 | ||
|
2124 | -a: makes the pattern match even objects whose names start with a single | |
|
2125 | underscore. These names are normally ommitted from the search. | |
|
2126 | ||
|
2127 | -i/-c: make the pattern case insensitive/sensitive. If neither of these | |
|
2128 | options is given, the default is read from your ipythonrc file. The | |
|
2129 | option name which sets this value is 'wildcards_case_sensitive'. If this | |
|
2130 | option is not specified in your ipythonrc file, IPython's internal | |
|
2131 | default is to do a case sensitive search. | |
|
2132 | ||
|
2133 | -e/-s NAMESPACE: exclude/search a given namespace. The pattern you | |
|
2134 | specifiy can be searched in any of the following namespaces: 'builtin', | |
|
2135 | 'user', 'user_global','internal', 'alias', where 'builtin' and 'user' | |
|
2136 | are the search defaults. Note that you should not use quotes when | |
|
2137 | specifying namespaces. | |
|
2138 | ||
|
2139 | 'Builtin' contains the python module builtin, 'user' contains all user | |
|
2140 | data, 'alias' only contain the shell aliases and no python objects, | |
|
2141 | 'internal' contains objects used by IPython. The 'user_global' namespace | |
|
2142 | is only used by embedded IPython instances, and it contains module-level | |
|
2143 | globals. You can add namespaces to the search with -s or exclude them | |
|
2144 | with -e (these options can be given more than once). | |
|
2145 | ||
|
2146 | Examples: | |
|
2147 | ||
|
2148 | %psearch a* -> objects beginning with an a %psearch -e builtin a* -> | |
|
2149 | objects NOT in the builtin space starting in a %psearch a* function -> | |
|
2150 | all functions beginning with an a %psearch re.e* -> objects beginning | |
|
2151 | with an e in module re %psearch r*.e* -> objects that start with e in | |
|
2152 | modules starting in r %psearch r*.* string -> all strings in modules | |
|
2153 | beginning with r | |
|
2154 | ||
|
2155 | Case sensitve search: | |
|
2156 | ||
|
2157 | %psearch -c a* list all object beginning with lower case a | |
|
2158 | ||
|
2159 | Show objects beginning with a single _: | |
|
2160 | ||
|
2161 | %psearch -a _* list objects beginning with a single underscore | |
|
2162 | ||
|
2163 | ||
|
2164 | %psource: Print (or run through pager) the source code for an object. | |
|
2165 | ||
|
2166 | ||
|
2167 | %pushd: Place the current dir on stack and change directory. | |
|
2168 | ||
|
2169 | Usage: | |
|
2170 | %pushd ['dirname'] | |
|
2171 | ||
|
2172 | ||
|
2173 | %pwd: Return the current working directory path. | |
|
2174 | ||
|
2175 | ||
|
2176 | %pycat: Show a syntax-highlighted file through a pager. | |
|
2177 | ||
|
2178 | This magic is similar to the cat utility, but it will assume the file to | |
|
2179 | be Python source and will show it with syntax highlighting. | |
|
2180 | ||
|
2181 | ||
|
2182 | %quickref: Show a quick reference sheet | |
|
2183 | ||
|
2184 | ||
|
2185 | %quit: Exit IPython, confirming if configured to do so (like %exit) | |
|
2186 | ||
|
2187 | ||
|
2188 | %r: Repeat previous input. | |
|
2189 | ||
|
2190 | Note: Consider using the more powerfull %rep instead! | |
|
2191 | ||
|
2192 | If given an argument, repeats the previous command which starts with the | |
|
2193 | same string, otherwise it just repeats the previous input. | |
|
2194 | ||
|
2195 | Shell escaped commands (with ! as first character) are not recognized by | |
|
2196 | this system, only pure python code and magic commands. | |
|
2197 | ||
|
2198 | ||
|
2199 | %rehashx: Update the alias table with all executable files in $PATH. | |
|
2200 | ||
|
2201 | This version explicitly checks that every entry in $PATH is a file with | |
|
2202 | execute access (os.X_OK), so it is much slower than %rehash. | |
|
2203 | ||
|
2204 | Under Windows, it checks executability as a match agains a ``|``-separated | |
|
2205 | string of extensions, stored in the IPython config variable | |
|
2206 | win_exec_ext. This defaults to ``exe|com|bat``. | |
|
2207 | ||
|
2208 | This function also resets the root module cache of module completer, | |
|
2209 | used on slow filesystems. | |
|
2210 | ||
|
2211 | ||
|
2212 | %reset: Resets the namespace by removing all names defined by the user. | |
|
2213 | ||
|
2214 | Input/Output history are left around in case you need them. | |
|
2215 | ||
|
2216 | ||
|
2217 | %run: Run the named file inside IPython as a program. | |
|
2218 | ||
|
2219 | Usage: | |
|
2220 | %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args] | |
|
2221 | ||
|
2222 | Parameters after the filename are passed as command-line arguments to | |
|
2223 | the program (put in sys.argv). Then, control returns to IPython's prompt. | |
|
2224 | ||
|
2225 | This is similar to running at a system prompt: | |
|
2226 | $ python file args | |
|
2227 | but with the advantage of giving you IPython's tracebacks, and of | |
|
2228 | loading all variables into your interactive namespace for further use | |
|
2229 | (unless -p is used, see below). | |
|
2230 | ||
|
2231 | The file is executed in a namespace initially consisting only of | |
|
2232 | __name__=='__main__' and sys.argv constructed as indicated. It thus sees | |
|
2233 | its environment as if it were being run as a stand-alone program (except | |
|
2234 | for sharing global objects such as previously imported modules). But | |
|
2235 | after execution, the IPython interactive namespace gets updated with all | |
|
2236 | variables defined in the program (except for __name__ and sys.argv). | |
|
2237 | This allows for very convenient loading of code for interactive work, | |
|
2238 | while giving each program a 'clean sheet' to run in. | |
|
2239 | ||
|
2240 | Options: | |
|
2241 | ||
|
2242 | -n: __name__ is NOT set to '__main__', but to the running file's name | |
|
2243 | without extension (as python does under import). This allows running | |
|
2244 | scripts and reloading the definitions in them without calling code | |
|
2245 | protected by an ' if __name__ == "__main__" ' clause. | |
|
2246 | ||
|
2247 | -i: run the file in IPython's namespace instead of an empty one. This is | |
|
2248 | useful if you are experimenting with code written in a text editor which | |
|
2249 | depends on variables defined interactively. | |
|
2250 | ||
|
2251 | -e: ignore sys.exit() calls or SystemExit exceptions in the script being | |
|
2252 | run. This is particularly useful if IPython is being used to run | |
|
2253 | unittests, which always exit with a sys.exit() call. In such cases you | |
|
2254 | are interested in the output of the test results, not in seeing a | |
|
2255 | traceback of the unittest module. | |
|
2256 | ||
|
2257 | -t: print timing information at the end of the run. IPython will give | |
|
2258 | you an estimated CPU time consumption for your script, which under Unix | |
|
2259 | uses the resource module to avoid the wraparound problems of | |
|
2260 | time.clock(). Under Unix, an estimate of time spent on system tasks is | |
|
2261 | also given (for Windows platforms this is reported as 0.0). | |
|
2262 | ||
|
2263 | If -t is given, an additional -N<N> option can be given, where <N> must | |
|
2264 | be an integer indicating how many times you want the script to run. The | |
|
2265 | final timing report will include total and per run results. | |
|
2266 | ||
|
2267 | For example (testing the script uniq_stable.py): | |
|
2268 | ||
|
2269 | In [1]: run -t uniq_stable | |
|
2270 | ||
|
2271 | IPython CPU timings (estimated): | |
|
2272 | User : 0.19597 s. | |
|
2273 | System: 0.0 s. | |
|
2274 | ||
|
2275 | In [2]: run -t -N5 uniq_stable | |
|
2276 | ||
|
2277 | IPython CPU timings (estimated): | |
|
2278 | Total runs performed: 5 | |
|
2279 | Times : Total Per run | |
|
2280 | User : 0.910862 s, 0.1821724 s. | |
|
2281 | System: 0.0 s, 0.0 s. | |
|
2282 | ||
|
2283 | -d: run your program under the control of pdb, the Python debugger. This | |
|
2284 | allows you to execute your program step by step, watch variables, etc. | |
|
2285 | Internally, what IPython does is similar to calling: | |
|
2286 | ||
|
2287 | pdb.run('execfile("YOURFILENAME")') | |
|
2288 | ||
|
2289 | with a breakpoint set on line 1 of your file. You can change the line | |
|
2290 | number for this automatic breakpoint to be <N> by using the -bN option | |
|
2291 | (where N must be an integer). For example: | |
|
2292 | ||
|
2293 | %run -d -b40 myscript | |
|
2294 | ||
|
2295 | will set the first breakpoint at line 40 in myscript.py. Note that the | |
|
2296 | first breakpoint must be set on a line which actually does something | |
|
2297 | (not a comment or docstring) for it to stop execution. | |
|
2298 | ||
|
2299 | When the pdb debugger starts, you will see a (Pdb) prompt. You must | |
|
2300 | first enter 'c' (without qoutes) to start execution up to the first | |
|
2301 | breakpoint. | |
|
2302 | ||
|
2303 | Entering 'help' gives information about the use of the debugger. You can | |
|
2304 | easily see pdb's full documentation with "import pdb;pdb.help()" at a | |
|
2305 | prompt. | |
|
2306 | ||
|
2307 | -p: run program under the control of the Python profiler module (which | |
|
2308 | prints a detailed report of execution times, function calls, etc). | |
|
2309 | ||
|
2310 | You can pass other options after -p which affect the behavior of the | |
|
2311 | profiler itself. See the docs for %prun for details. | |
|
2312 | ||
|
2313 | In this mode, the program's variables do NOT propagate back to the | |
|
2314 | IPython interactive namespace (because they remain in the namespace | |
|
2315 | where the profiler executes them). | |
|
2316 | ||
|
2317 | Internally this triggers a call to %prun, see its documentation for | |
|
2318 | details on the options available specifically for profiling. | |
|
2319 | ||
|
2320 | There is one special usage for which the text above doesn't apply: if | |
|
2321 | the filename ends with .ipy, the file is run as ipython script, just as | |
|
2322 | if the commands were written on IPython prompt. | |
|
2323 | ||
|
2324 | ||
|
2325 | %runlog: Run files as logs. | |
|
2326 | ||
|
2327 | Usage: | |
|
2328 | %runlog file1 file2 ... | |
|
2329 | ||
|
2330 | Run the named files (treating them as log files) in sequence inside the | |
|
2331 | interpreter, and return to the prompt. This is much slower than %run | |
|
2332 | because each line is executed in a try/except block, but it allows | |
|
2333 | running files with syntax errors in them. | |
|
2334 | ||
|
2335 | Normally IPython will guess when a file is one of its own logfiles, so | |
|
2336 | you can typically use %run even for logs. This shorthand allows you to | |
|
2337 | force any file to be treated as a log file. | |
|
2338 | ||
|
2339 | ||
|
2340 | %save: Save a set of lines to a given filename. | |
|
2341 | ||
|
2342 | Usage: | |
|
2343 | %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ... | |
|
2344 | ||
|
2345 | Options: | |
|
2346 | ||
|
2347 | -r: use 'raw' input. By default, the 'processed' history is used, so | |
|
2348 | that magics are loaded in their transformed version to valid Python. If | |
|
2349 | this option is given, the raw input as typed as the command line is used | |
|
2350 | instead. | |
|
2351 | ||
|
2352 | This function uses the same syntax as %macro for line extraction, but | |
|
2353 | instead of creating a macro it saves the resulting string to the | |
|
2354 | filename you specify. | |
|
2355 | ||
|
2356 | It adds a '.py' extension to the file if you don't do so yourself, and | |
|
2357 | it asks for confirmation before overwriting existing files. | |
|
2358 | ||
|
2359 | ||
|
2360 | %sc: Shell capture - execute a shell command and capture its output. | |
|
2361 | ||
|
2362 | DEPRECATED. Suboptimal, retained for backwards compatibility. | |
|
2363 | ||
|
2364 | You should use the form 'var = !command' instead. Example: | |
|
2365 | ||
|
2366 | "%sc -l myfiles = ls " should now be written as | |
|
2367 | ||
|
2368 | "myfiles = !ls " | |
|
2369 | ||
|
2370 | myfiles.s, myfiles.l and myfiles.n still apply as documented below. | |
|
2371 | ||
|
2372 | - %sc [options] varname=command | |
|
2373 | ||
|
2374 | IPython will run the given command using commands.getoutput(), and will | |
|
2375 | then update the user's interactive namespace with a variable called | |
|
2376 | varname, containing the value of the call. Your command can contain | |
|
2377 | shell wildcards, pipes, etc. | |
|
2378 | ||
|
2379 | The '=' sign in the syntax is mandatory, and the variable name you | |
|
2380 | supply must follow Python's standard conventions for valid names. | |
|
2381 | ||
|
2382 | (A special format without variable name exists for internal use) | |
|
2383 | ||
|
2384 | Options: | |
|
2385 | ||
|
2386 | -l: list output. Split the output on newlines into a list before | |
|
2387 | assigning it to the given variable. By default the output is stored as a | |
|
2388 | single string. | |
|
2389 | ||
|
2390 | -v: verbose. Print the contents of the variable. | |
|
2391 | ||
|
2392 | In most cases you should not need to split as a list, because the | |
|
2393 | returned value is a special type of string which can automatically | |
|
2394 | provide its contents either as a list (split on newlines) or as a | |
|
2395 | space-separated string. These are convenient, respectively, either for | |
|
2396 | sequential processing or to be passed to a shell command. | |
|
2397 | ||
|
2398 | For example: | |
|
2399 | ||
|
2400 | # Capture into variable a In [9]: sc a=ls *py | |
|
2401 | ||
|
2402 | # a is a string with embedded newlines In [10]: a Out[10]: 'setup.py | |
|
2403 | win32_manual_post_install.py' | |
|
2404 | ||
|
2405 | # which can be seen as a list: In [11]: a.l Out[11]: ['setup.py', | |
|
2406 | 'win32_manual_post_install.py'] | |
|
2407 | ||
|
2408 | # or as a whitespace-separated string: In [12]: a.s Out[12]: 'setup.py | |
|
2409 | win32_manual_post_install.py' | |
|
2410 | ||
|
2411 | # a.s is useful to pass as a single command line: In [13]: !wc -l $a.s | |
|
2412 | 146 setup.py 130 win32_manual_post_install.py 276 total | |
|
2413 | ||
|
2414 | # while the list form is useful to loop over: In [14]: for f in a.l: | |
|
2415 | ....: !wc -l $f ....: 146 setup.py 130 win32_manual_post_install.py | |
|
2416 | ||
|
2417 | Similiarly, the lists returned by the -l option are also special, in the | |
|
2418 | sense that you can equally invoke the .s attribute on them to | |
|
2419 | automatically get a whitespace-separated string from their contents: | |
|
2420 | ||
|
2421 | In [1]: sc -l b=ls *py | |
|
2422 | ||
|
2423 | In [2]: b Out[2]: ['setup.py', 'win32_manual_post_install.py'] | |
|
2424 | ||
|
2425 | In [3]: b.s Out[3]: 'setup.py win32_manual_post_install.py' | |
|
2426 | ||
|
2427 | In summary, both the lists and strings used for ouptut capture have the | |
|
2428 | following special attributes: | |
|
2429 | ||
|
2430 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2431 | newline-separated string. .s (or .spstr): value as space-separated string. | |
|
2432 | ||
|
2433 | ||
|
2434 | %sx: Shell execute - run a shell command and capture its output. | |
|
2435 | ||
|
2436 | %sx command | |
|
2437 | ||
|
2438 | IPython will run the given command using commands.getoutput(), and | |
|
2439 | return the result formatted as a list (split on '\n'). Since the output | |
|
2440 | is _returned_, it will be stored in ipython's regular output cache | |
|
2441 | Out[N] and in the '_N' automatic variables. | |
|
2442 | ||
|
2443 | Notes: | |
|
2444 | ||
|
2445 | 1) If an input line begins with '!!', then %sx is automatically invoked. | |
|
2446 | That is, while: !ls causes ipython to simply issue system('ls'), typing | |
|
2447 | !!ls is a shorthand equivalent to: %sx ls | |
|
2448 | ||
|
2449 | 2) %sx differs from %sc in that %sx automatically splits into a list, | |
|
2450 | like '%sc -l'. The reason for this is to make it as easy as possible to | |
|
2451 | process line-oriented shell output via further python commands. %sc is | |
|
2452 | meant to provide much finer control, but requires more typing. | |
|
2453 | ||
|
2454 | 3) Just like %sc -l, this is a list with special attributes: | |
|
2455 | ||
|
2456 | .l (or .list) : value as list. .n (or .nlstr): value as | |
|
2457 | newline-separated string. .s (or .spstr): value as whitespace-separated | |
|
2458 | string. | |
|
2459 | ||
|
2460 | This is very useful when trying to use such lists as arguments to system | |
|
2461 | commands. | |
|
2462 | ||
|
2463 | ||
|
2464 | %system_verbose: Set verbose printing of system calls. | |
|
2465 | ||
|
2466 | If called without an argument, act as a toggle | |
|
2467 | ||
|
2468 | ||
|
2469 | %time: Time execution of a Python statement or expression. | |
|
2470 | ||
|
2471 | The CPU and wall clock times are printed, and the value of the | |
|
2472 | expression (if any) is returned. Note that under Win32, system time is | |
|
2473 | always reported as 0, since it can not be measured. | |
|
2474 | ||
|
2475 | This function provides very basic timing functionality. In Python 2.3, | |
|
2476 | the timeit module offers more control and sophistication, so this could | |
|
2477 | be rewritten to use it (patches welcome). | |
|
2478 | ||
|
2479 | Some examples: | |
|
2480 | ||
|
2481 | In [1]: time 2**128 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2482 | Wall time: 0.00 Out[1]: 340282366920938463463374607431768211456L | |
|
2483 | ||
|
2484 | In [2]: n = 1000000 | |
|
2485 | ||
|
2486 | In [3]: time sum(range(n)) CPU times: user 1.20 s, sys: 0.05 s, total: | |
|
2487 | 1.25 s Wall time: 1.37 Out[3]: 499999500000L | |
|
2488 | ||
|
2489 | In [4]: time print 'hello world' hello world CPU times: user 0.00 s, | |
|
2490 | sys: 0.00 s, total: 0.00 s Wall time: 0.00 | |
|
2491 | ||
|
2492 | Note that the time needed by Python to compile the given expression will | |
|
2493 | be reported if it is more than 0.1s. In this example, the actual | |
|
2494 | exponentiation is done by Python at compilation time, so while the | |
|
2495 | expression can take a noticeable amount of time to compute, that time is | |
|
2496 | purely due to the compilation: | |
|
2497 | ||
|
2498 | In [5]: time 3**9999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s | |
|
2499 | Wall time: 0.00 s | |
|
2500 | ||
|
2501 | In [6]: time 3**999999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 | |
|
2502 | s Wall time: 0.00 s Compiler : 0.78 s | |
|
2503 | ||
|
2504 | ||
|
2505 | %timeit: Time execution of a Python statement or expression | |
|
2506 | ||
|
2507 | Usage: | |
|
2508 | %timeit [-n<N> -r<R> [-t|-c]] statement | |
|
2509 | ||
|
2510 | Time execution of a Python statement or expression using the timeit module. | |
|
2511 | ||
|
2512 | Options: -n<N>: execute the given statement <N> times in a loop. If this | |
|
2513 | value is not given, a fitting value is chosen. | |
|
2514 | ||
|
2515 | -r<R>: repeat the loop iteration <R> times and take the best result. | |
|
2516 | Default: 3 | |
|
2517 | ||
|
2518 | -t: use time.time to measure the time, which is the default on Unix. | |
|
2519 | This function measures wall time. | |
|
2520 | ||
|
2521 | -c: use time.clock to measure the time, which is the default on Windows | |
|
2522 | and measures wall time. On Unix, resource.getrusage is used instead and | |
|
2523 | returns the CPU user time. | |
|
2524 | ||
|
2525 | -p<P>: use a precision of <P> digits to display the timing result. | |
|
2526 | Default: 3 | |
|
2527 | ||
|
2528 | Examples: | |
|
2529 | In [1]: %timeit pass 10000000 loops, best of 3: 53.3 ns per loop | |
|
2530 | ||
|
2531 | In [2]: u = None | |
|
2532 | ||
|
2533 | In [3]: %timeit u is None 10000000 loops, best of 3: 184 ns per loop | |
|
2534 | ||
|
2535 | In [4]: %timeit -r 4 u == None 1000000 loops, best of 4: 242 ns per loop | |
|
2536 | ||
|
2537 | In [5]: import time | |
|
2538 | ||
|
2539 | In [6]: %timeit -n1 time.sleep(2) 1 loops, best of 3: 2 s per loop | |
|
2540 | ||
|
2541 | The times reported by %timeit will be slightly higher than those | |
|
2542 | reported by the timeit.py script when variables are accessed. This is | |
|
2543 | due to the fact that %timeit executes the statement in the namespace of | |
|
2544 | the shell, compared with timeit.py, which uses a single setup statement | |
|
2545 | to import function or create variables. Generally, the bias does not | |
|
2546 | matter as long as results from timeit.py are not mixed with those from | |
|
2547 | %timeit. | |
|
2548 | ||
|
2549 | ||
|
2550 | %unalias: Remove an alias | |
|
2551 | ||
|
2552 | ||
|
2553 | %upgrade: Upgrade your IPython installation | |
|
2554 | ||
|
2555 | This will copy the config files that don't yet exist in your ipython dir | |
|
2556 | from the system config dir. Use this after upgrading IPython if you | |
|
2557 | don't wish to delete your .ipython dir. | |
|
2558 | ||
|
2559 | Call with -nolegacy to get rid of ipythonrc* files (recommended for new | |
|
2560 | users) | |
|
2561 | ||
|
2562 | ||
|
2563 | %who: Print all interactive variables, with some minimal formatting. | |
|
2564 | ||
|
2565 | If any arguments are given, only variables whose type matches one of | |
|
2566 | these are printed. For example: | |
|
2567 | ||
|
2568 | %who function str | |
|
2569 | ||
|
2570 | will only list functions and strings, excluding all other types of | |
|
2571 | variables. To find the proper type names, simply use type(var) at a | |
|
2572 | command line to see how python prints type names. For example: | |
|
2573 | ||
|
2574 | In [1]: type('hello') | |
|
2575 | Out[1]: <type 'str'> | |
|
2576 | ||
|
2577 | indicates that the type name for strings is 'str'. | |
|
2578 | ||
|
2579 | %who always excludes executed names loaded through your configuration | |
|
2580 | file and things which are internal to IPython. | |
|
2581 | ||
|
2582 | This is deliberate, as typically you may load many modules and the | |
|
2583 | purpose of %who is to show you only what you've manually defined. | |
|
2584 | ||
|
2585 | ||
|
2586 | %who_ls: Return a sorted list of all interactive variables. | |
|
2587 | ||
|
2588 | If arguments are given, only variables of types matching these arguments | |
|
2589 | are returned. | |
|
2590 | ||
|
2591 | ||
|
2592 | %whos: Like %who, but gives some extra information about each variable. | |
|
2593 | ||
|
2594 | The same type filtering of %who can be applied here. | |
|
2595 | ||
|
2596 | For all variables, the type is printed. Additionally it prints: | |
|
2597 | ||
|
2598 | - For ,[],(): their length. | |
|
2599 | ||
|
2600 | - For numpy and Numeric arrays, a summary with shape, number of | |
|
2601 | elements, typecode and size in memory. | |
|
2602 | ||
|
2603 | - Everything else: a string representation, snipping their middle if too | |
|
2604 | long. | |
|
2605 | ||
|
2606 | ||
|
2607 | %xmode: Switch modes for the exception handlers. | |
|
2608 | ||
|
2609 | Valid modes: Plain, Context and Verbose. | |
|
2610 | ||
|
2611 | If called without arguments, acts as a toggle. | |
|
2612 | ||
|
2613 | ||
|
2614 | Access to the standard Python help | |
|
2615 | ---------------------------------- | |
|
2614 | 2616 | |
|
2615 | 2617 | As of Python 2.1, a help system is available with access to object |
|
2616 | 2618 | docstrings and the Python manuals. Simply type 'help' (no quotes) to |
|
2617 | 2619 | access it. You can also type help(object) to obtain information about a |
|
2618 | 2620 | given object, and help('keyword') for information on a keyword. As noted |
|
2619 | 2621 | in sec. 3.1 <node3.html#sec:help-access>, you need to properly configure |
|
2620 | 2622 | your environment variable PYTHONDOCS for this feature to work correctly. |
|
2621 | 2623 | |
|
2622 | 2624 | |
|
2623 | 2625 | |
|
2624 |
|
|
|
2626 | Dynamic object information | |
|
2627 | -------------------------- | |
|
2625 | 2628 | |
|
2626 | 2629 | Typing ?word or word? prints detailed information about an object. If |
|
2627 | 2630 | certain strings in the object are too long (docstrings, code, etc.) they |
|
2628 | 2631 | get snipped in the center for brevity. This system gives access variable |
|
2629 | 2632 | types and values, full source code for any object (if available), |
|
2630 | 2633 | function prototypes and other useful information. |
|
2631 | 2634 | |
|
2632 | 2635 | Typing ??word or word?? gives access to the full information without |
|
2633 | 2636 | snipping long strings. Long strings are sent to the screen through the |
|
2634 | 2637 | less pager if longer than the screen and printed otherwise. On systems |
|
2635 | 2638 | lacking the less command, IPython uses a very basic internal pager. |
|
2636 | 2639 | |
|
2637 | 2640 | The following magic functions are particularly useful for gathering |
|
2638 | 2641 | information about your working environment. You can get more details by |
|
2639 | 2642 | typing %magic or querying them individually (use %function_name? with or |
|
2640 | 2643 | without the %), this is just a summary: |
|
2641 | 2644 | |
|
2642 | 2645 | * [%pdoc <object>:] Print (or run through a pager if too long) the |
|
2643 | 2646 | docstring for an object. If the given object is a class, it will |
|
2644 | 2647 | print both the class and the constructor docstrings. |
|
2645 | 2648 | * [%pdef <object>:] Print the definition header for any callable |
|
2646 | 2649 | object. If the object is a class, print the constructor information. |
|
2647 | 2650 | * [%psource <object>:] Print (or run through a pager if too long) |
|
2648 | 2651 | the source code for an object. |
|
2649 | 2652 | * [%pfile <object>:] Show the entire source file where an object was |
|
2650 | 2653 | defined via a pager, opening it at the line where the object |
|
2651 | 2654 | definition begins. |
|
2652 | 2655 | * [%who/%whos:] These functions give information about identifiers |
|
2653 | 2656 | you have defined interactively (not things you loaded or defined |
|
2654 | 2657 | in your configuration files). %who just prints a list of |
|
2655 | 2658 | identifiers and %whos prints a table with some basic details about |
|
2656 | 2659 | each identifier. |
|
2657 | 2660 | |
|
2658 | 2661 | Note that the dynamic object information functions (?/??, %pdoc, %pfile, |
|
2659 | 2662 | %pdef, %psource) give you access to documentation even on things which |
|
2660 | 2663 | are not really defined as separate identifiers. Try for example typing |
|
2661 | 2664 | {}.get? or after doing import os, type os.path.abspath??. |
|
2662 | 2665 | |
|
2663 | 2666 | |
|
2664 | 2667 | |
|
2665 |
|
|
|
2668 | Readline-based features | |
|
2669 | ----------------------- | |
|
2666 | 2670 | |
|
2667 | 2671 | These features require the GNU readline library, so they won't work if |
|
2668 | 2672 | your Python installation lacks readline support. We will first describe |
|
2669 | 2673 | the default behavior IPython uses, and then how to change it to suit |
|
2670 | 2674 | your preferences. |
|
2671 | 2675 | |
|
2672 | 2676 | |
|
2673 | 2677 | Command line completion |
|
2674 | 2678 | ----------------------- |
|
2675 | 2679 | |
|
2676 | 2680 | At any time, hitting TAB will complete any available python commands or |
|
2677 | 2681 | variable names, and show you a list of the possible completions if |
|
2678 | 2682 | there's no unambiguous one. It will also complete filenames in the |
|
2679 | 2683 | current directory if no python names match what you've typed so far. |
|
2680 | 2684 | |
|
2681 | 2685 | |
|
2682 | 2686 | Search command history |
|
2683 | 2687 | ---------------------- |
|
2684 | 2688 | |
|
2685 | 2689 | IPython provides two ways for searching through previous input and thus |
|
2686 | 2690 | reduce the need for repetitive typing: |
|
2687 | 2691 | |
|
2688 | 2692 | 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n |
|
2689 | 2693 | (next,down) to search through only the history items that match |
|
2690 | 2694 | what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank |
|
2691 | 2695 | prompt, they just behave like normal arrow keys. |
|
2692 | 2696 | 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system |
|
2693 | 2697 | searches your history for lines that contain what you've typed so |
|
2694 | 2698 | far, completing as much as it can. |
|
2695 | 2699 | |
|
2696 | 2700 | |
|
2697 | 2701 | Persistent command history across sessions |
|
2698 | 2702 | ------------------------------------------ |
|
2699 | 2703 | |
|
2700 | 2704 | IPython will save your input history when it leaves and reload it next |
|
2701 | 2705 | time you restart it. By default, the history file is named |
|
2702 | 2706 | $IPYTHONDIR/history, but if you've loaded a named profile, |
|
2703 | 2707 | '-PROFILE_NAME' is appended to the name. This allows you to keep |
|
2704 | 2708 | separate histories related to various tasks: commands related to |
|
2705 | 2709 | numerical work will not be clobbered by a system shell history, for |
|
2706 | 2710 | example. |
|
2707 | 2711 | |
|
2708 | 2712 | |
|
2709 | 2713 | Autoindent |
|
2710 | 2714 | ---------- |
|
2711 | 2715 | |
|
2712 | 2716 | IPython can recognize lines ending in ':' and indent the next line, |
|
2713 | 2717 | while also un-indenting automatically after 'raise' or 'return'. |
|
2714 | 2718 | |
|
2715 | 2719 | This feature uses the readline library, so it will honor your ~/.inputrc |
|
2716 | 2720 | configuration (or whatever file your INPUTRC variable points to). Adding |
|
2717 | 2721 | the following lines to your .inputrc file can make indenting/unindenting |
|
2718 | 2722 | more convenient (M-i indents, M-u unindents):: |
|
2719 | 2723 | |
|
2720 | 2724 | $if Python |
|
2721 | 2725 | "\M-i": " " |
|
2722 | 2726 | "\M-u": "\d\d\d\d" |
|
2723 | 2727 | $endif |
|
2724 | 2728 | |
|
2725 | 2729 | Note that there are 4 spaces between the quote marks after "M-i" above. |
|
2726 | 2730 | |
|
2727 | 2731 | Warning: this feature is ON by default, but it can cause problems with |
|
2728 | 2732 | the pasting of multi-line indented code (the pasted code gets |
|
2729 | 2733 | re-indented on each line). A magic function %autoindent allows you to |
|
2730 | 2734 | toggle it on/off at runtime. You can also disable it permanently on in |
|
2731 | 2735 | your ipythonrc file (set autoindent 0). |
|
2732 | 2736 | |
|
2733 | 2737 | |
|
2734 | 2738 | Customizing readline behavior |
|
2735 | 2739 | ----------------------------- |
|
2736 | 2740 | |
|
2737 | 2741 | All these features are based on the GNU readline library, which has an |
|
2738 | 2742 | extremely customizable interface. Normally, readline is configured via a |
|
2739 | 2743 | file which defines the behavior of the library; the details of the |
|
2740 | 2744 | syntax for this can be found in the readline documentation available |
|
2741 | 2745 | with your system or on the Internet. IPython doesn't read this file (if |
|
2742 | 2746 | it exists) directly, but it does support passing to readline valid |
|
2743 | 2747 | options via a simple interface. In brief, you can customize readline by |
|
2744 | 2748 | setting the following options in your ipythonrc configuration file (note |
|
2745 | 2749 | that these options can not be specified at the command line): |
|
2746 | 2750 | |
|
2747 | 2751 | * [readline_parse_and_bind:] this option can appear as many times as |
|
2748 | 2752 | you want, each time defining a string to be executed via a |
|
2749 | 2753 | readline.parse_and_bind() command. The syntax for valid commands |
|
2750 | 2754 | of this kind can be found by reading the documentation for the GNU |
|
2751 | 2755 | readline library, as these commands are of the kind which readline |
|
2752 | 2756 | accepts in its configuration file. |
|
2753 | 2757 | * [readline_remove_delims:] a string of characters to be removed |
|
2754 | 2758 | from the default word-delimiters list used by readline, so that |
|
2755 | 2759 | completions may be performed on strings which contain them. Do not |
|
2756 | 2760 | change the default value unless you know what you're doing. |
|
2757 | 2761 | * [readline_omit__names:] when tab-completion is enabled, hitting |
|
2758 | 2762 | <tab> after a '.' in a name will complete all attributes of an |
|
2759 | 2763 | object, including all the special methods whose names include |
|
2760 | 2764 | double underscores (like __getitem__ or __class__). If you'd |
|
2761 | 2765 | rather not see these names by default, you can set this option to |
|
2762 | 2766 | 1. Note that even when this option is set, you can still see those |
|
2763 | 2767 | names by explicitly typing a _ after the period and hitting <tab>: |
|
2764 | 2768 | 'name._<tab>' will always complete attribute names starting with '_'. |
|
2765 | 2769 | * [ ] This option is off by default so that new users see all |
|
2766 | 2770 | attributes of any objects they are dealing with. |
|
2767 | 2771 | |
|
2768 | 2772 | You will find the default values along with a corresponding detailed |
|
2769 | 2773 | explanation in your ipythonrc file. |
|
2770 | 2774 | |
|
2771 | 2775 | |
|
2772 | 2776 | Session logging and restoring |
|
2773 | 2777 | ----------------------------- |
|
2774 | 2778 | |
|
2775 | 2779 | You can log all input from a session either by starting IPython with the |
|
2776 | 2780 | command line switches -log or -logfile (see sec. 5.2 |
|
2777 | 2781 | <node5.html#sec:cmd-line-opts>)or by activating the logging at any |
|
2778 | 2782 | moment with the magic function %logstart. |
|
2779 | 2783 | |
|
2780 | 2784 | Log files can later be reloaded with the -logplay option and IPython |
|
2781 | 2785 | will attempt to 'replay' the log by executing all the lines in it, thus |
|
2782 | 2786 | restoring the state of a previous session. This feature is not quite |
|
2783 | 2787 | perfect, but can still be useful in many cases. |
|
2784 | 2788 | |
|
2785 | 2789 | The log files can also be used as a way to have a permanent record of |
|
2786 | 2790 | any code you wrote while experimenting. Log files are regular text files |
|
2787 | 2791 | which you can later open in your favorite text editor to extract code or |
|
2788 | 2792 | to 'clean them up' before using them to replay a session. |
|
2789 | 2793 | |
|
2790 | 2794 | The %logstart function for activating logging in mid-session is used as |
|
2791 | 2795 | follows: |
|
2792 | 2796 | |
|
2793 | 2797 | %logstart [log_name [log_mode]] |
|
2794 | 2798 | |
|
2795 | 2799 | If no name is given, it defaults to a file named 'log' in your |
|
2796 | 2800 | IPYTHONDIR directory, in 'rotate' mode (see below). |
|
2797 | 2801 | |
|
2798 | 2802 | '%logstart name' saves to file 'name' in 'backup' mode. It saves your |
|
2799 | 2803 | history up to that point and then continues logging. |
|
2800 | 2804 | |
|
2801 | 2805 | %logstart takes a second optional parameter: logging mode. This can be |
|
2802 | 2806 | one of (note that the modes are given unquoted): |
|
2803 | 2807 | |
|
2804 | 2808 | * [over:] overwrite existing log_name. |
|
2805 | 2809 | * [backup:] rename (if exists) to log_name~ and start log_name. |
|
2806 | 2810 | * [append:] well, that says it. |
|
2807 | 2811 | * [rotate:] create rotating logs log_name.1~, log_name.2~, etc. |
|
2808 | 2812 | |
|
2809 | 2813 | The %logoff and %logon functions allow you to temporarily stop and |
|
2810 | 2814 | resume logging to a file which had previously been started with |
|
2811 | 2815 | %logstart. They will fail (with an explanation) if you try to use them |
|
2812 | 2816 | before logging has been started. |
|
2813 | 2817 | |
|
2814 | 2818 | |
|
2815 | 2819 | |
|
2816 | 2820 | System shell access |
|
2817 | 2821 | ------------------- |
|
2818 | 2822 | |
|
2819 | 2823 | Any input line beginning with a ! character is passed verbatim (minus |
|
2820 | 2824 | the !, of course) to the underlying operating system. For example, |
|
2821 | 2825 | typing !ls will run 'ls' in the current directory. |
|
2822 | 2826 | |
|
2823 | 2827 | |
|
2824 | 2828 | Manual capture of command output |
|
2825 | 2829 | -------------------------------- |
|
2826 | 2830 | |
|
2827 | 2831 | If the input line begins with two exclamation marks, !!, the command is |
|
2828 | 2832 | executed but its output is captured and returned as a python list, split |
|
2829 | 2833 | on newlines. Any output sent by the subprocess to standard error is |
|
2830 | 2834 | printed separately, so that the resulting list only captures standard |
|
2831 | 2835 | output. The !! syntax is a shorthand for the %sx magic command. |
|
2832 | 2836 | |
|
2833 | 2837 | Finally, the %sc magic (short for 'shell capture') is similar to %sx, |
|
2834 | 2838 | but allowing more fine-grained control of the capture details, and |
|
2835 | 2839 | storing the result directly into a named variable. |
|
2836 | 2840 | |
|
2837 | 2841 | See Sec. 6.2 <#sec:magic> for details on the magics %sc and %sx, or use |
|
2838 | 2842 | IPython's own help (sc? and sx?) for further details. |
|
2839 | 2843 | |
|
2840 | 2844 | IPython also allows you to expand the value of python variables when |
|
2841 | 2845 | making system calls. Any python variable or expression which you prepend |
|
2842 | 2846 | with $ will get expanded before the system call is made:: |
|
2843 | 2847 | |
|
2844 | 2848 | In [1]: pyvar='Hello world' |
|
2845 | 2849 | In [2]: !echo "A python variable: $pyvar" |
|
2846 | 2850 | A python variable: Hello world |
|
2847 | 2851 | |
|
2848 | 2852 | If you want the shell to actually see a literal $, you need to type it |
|
2849 | 2853 | twice:: |
|
2850 | 2854 | |
|
2851 | 2855 | In [3]: !echo "A system variable: $$HOME" |
|
2852 | 2856 | A system variable: /home/fperez |
|
2853 | 2857 | |
|
2854 | 2858 | You can pass arbitrary expressions, though you'll need to delimit them |
|
2855 | 2859 | with {} if there is ambiguity as to the extent of the expression:: |
|
2856 | 2860 | |
|
2857 | 2861 | In [5]: x=10 |
|
2858 | 2862 | In [6]: y=20 |
|
2859 | 2863 | In [13]: !echo $x+y |
|
2860 | 2864 | 10+y |
|
2861 | 2865 | In [7]: !echo ${x+y} |
|
2862 | 2866 | 30 |
|
2863 | 2867 | |
|
2864 | 2868 | Even object attributes can be expanded:: |
|
2865 | 2869 | |
|
2866 | 2870 | In [12]: !echo $sys.argv |
|
2867 | 2871 | [/home/fperez/usr/bin/ipython] |
|
2868 | 2872 | |
|
2869 | 2873 | |
|
2870 | 2874 | System command aliases |
|
2871 | 2875 | ---------------------- |
|
2872 | 2876 | |
|
2873 | 2877 | The %alias magic function and the alias option in the ipythonrc |
|
2874 | 2878 | configuration file allow you to define magic functions which are in fact |
|
2875 | 2879 | system shell commands. These aliases can have parameters. |
|
2876 | 2880 | |
|
2877 | 2881 | '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd' |
|
2878 | 2882 | |
|
2879 | 2883 | Then, typing '%alias_name params' will execute the system command 'cmd |
|
2880 | 2884 | params' (from your underlying operating system). |
|
2881 | 2885 | |
|
2882 | 2886 | You can also define aliases with parameters using %s specifiers (one per |
|
2883 | 2887 | parameter). The following example defines the %parts function as an |
|
2884 | 2888 | alias to the command 'echo first %s second %s' where each %s will be |
|
2885 | 2889 | replaced by a positional parameter to the call to %parts:: |
|
2886 | 2890 | |
|
2887 | 2891 | In [1]: alias parts echo first %s second %s |
|
2888 | 2892 | In [2]: %parts A B |
|
2889 | 2893 | first A second B |
|
2890 | 2894 | In [3]: %parts A |
|
2891 | 2895 | Incorrect number of arguments: 2 expected. |
|
2892 | 2896 | parts is an alias to: 'echo first %s second %s' |
|
2893 | 2897 | |
|
2894 | 2898 | If called with no parameters, %alias prints the table of currently |
|
2895 | 2899 | defined aliases. |
|
2896 | 2900 | |
|
2897 | 2901 | The %rehash/rehashx magics allow you to load your entire $PATH as |
|
2898 | 2902 | ipython aliases. See their respective docstrings (or sec. 6.2 |
|
2899 | 2903 | <#sec:magic> for further details). |
|
2900 | 2904 | |
|
2901 | 2905 | |
|
2902 | 2906 | |
|
2903 | 2907 | Recursive reload |
|
2904 | 2908 | ---------------- |
|
2905 | 2909 | |
|
2906 | 2910 | The dreload function does a recursive reload of a module: changes made |
|
2907 | 2911 | to the module since you imported will actually be available without |
|
2908 | 2912 | having to exit. |
|
2909 | 2913 | |
|
2910 | 2914 | |
|
2911 | 2915 | Verbose and colored exception traceback printouts |
|
2912 | 2916 | ------------------------------------------------- |
|
2913 | 2917 | |
|
2914 | 2918 | IPython provides the option to see very detailed exception tracebacks, |
|
2915 | 2919 | which can be especially useful when debugging large programs. You can |
|
2916 | 2920 | run any Python file with the %run function to benefit from these |
|
2917 | 2921 | detailed tracebacks. Furthermore, both normal and verbose tracebacks can |
|
2918 | 2922 | be colored (if your terminal supports it) which makes them much easier |
|
2919 | 2923 | to parse visually. |
|
2920 | 2924 | |
|
2921 | 2925 | See the magic xmode and colors functions for details (just type %magic). |
|
2922 | 2926 | |
|
2923 | 2927 | These features are basically a terminal version of Ka-Ping Yee's cgitb |
|
2924 | 2928 | module, now part of the standard Python library. |
|
2925 | 2929 | |
|
2926 | 2930 | |
|
2927 | 2931 | |
|
2928 | 2932 | Input caching system |
|
2929 | 2933 | -------------------- |
|
2930 | 2934 | |
|
2931 | 2935 | IPython offers numbered prompts (In/Out) with input and output caching. |
|
2932 | 2936 | All input is saved and can be retrieved as variables (besides the usual |
|
2933 | 2937 | arrow key recall). |
|
2934 | 2938 | |
|
2935 | 2939 | The following GLOBAL variables always exist (so don't overwrite them!): |
|
2936 | 2940 | _i: stores previous input. _ii: next previous. _iii: next-next previous. |
|
2937 | 2941 | _ih : a list of all input _ih[n] is the input from line n and this list |
|
2938 | 2942 | is aliased to the global variable In. If you overwrite In with a |
|
2939 | 2943 | variable of your own, you can remake the assignment to the internal list |
|
2940 | 2944 | with a simple 'In=_ih'. |
|
2941 | 2945 | |
|
2942 | 2946 | Additionally, global variables named _i<n> are dynamically created (<n> |
|
2943 | 2947 | being the prompt counter), such that |
|
2944 | 2948 | _i<n> == _ih[<n>] == In[<n>]. |
|
2945 | 2949 | |
|
2946 | 2950 | For example, what you typed at prompt 14 is available as _i14, _ih[14] |
|
2947 | 2951 | and In[14]. |
|
2948 | 2952 | |
|
2949 | 2953 | This allows you to easily cut and paste multi line interactive prompts |
|
2950 | 2954 | by printing them out: they print like a clean string, without prompt |
|
2951 | 2955 | characters. You can also manipulate them like regular variables (they |
|
2952 | 2956 | are strings), modify or exec them (typing 'exec _i9' will re-execute the |
|
2953 | 2957 | contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines |
|
2954 | 2958 | 9 through 13 and line 18). |
|
2955 | 2959 | |
|
2956 | 2960 | You can also re-execute multiple lines of input easily by using the |
|
2957 | 2961 | magic %macro function (which automates the process and allows |
|
2958 | 2962 | re-execution without having to type 'exec' every time). The macro system |
|
2959 | 2963 | also allows you to re-execute previous lines which include magic |
|
2960 | 2964 | function calls (which require special processing). Type %macro? or see |
|
2961 | 2965 | sec. 6.2 <#sec:magic> for more details on the macro system. |
|
2962 | 2966 | |
|
2963 | 2967 | A history function %hist allows you to see any part of your input |
|
2964 | 2968 | history by printing a range of the _i variables. |
|
2965 | 2969 | |
|
2966 | 2970 | Output caching system |
|
2967 | 2971 | --------------------- |
|
2968 | 2972 | |
|
2969 | 2973 | For output that is returned from actions, a system similar to the input |
|
2970 | 2974 | cache exists but using _ instead of _i. Only actions that produce a |
|
2971 | 2975 | result (NOT assignments, for example) are cached. If you are familiar |
|
2972 | 2976 | with Mathematica, IPython's _ variables behave exactly like |
|
2973 | 2977 | Mathematica's % variables. |
|
2974 | 2978 | |
|
2975 | 2979 | The following GLOBAL variables always exist (so don't overwrite them!): |
|
2976 | 2980 | |
|
2977 | 2981 | * [_] (a single underscore) : stores previous output, like Python's |
|
2978 | 2982 | default interpreter. |
|
2979 | 2983 | * [__] (two underscores): next previous. |
|
2980 | 2984 | * [___] (three underscores): next-next previous. |
|
2981 | 2985 | |
|
2982 | 2986 | Additionally, global variables named _<n> are dynamically created (<n> |
|
2983 | 2987 | being the prompt counter), such that the result of output <n> is always |
|
2984 | 2988 | available as _<n> (don't use the angle brackets, just the number, e.g. |
|
2985 | 2989 | _21). |
|
2986 | 2990 | |
|
2987 | 2991 | These global variables are all stored in a global dictionary (not a |
|
2988 | 2992 | list, since it only has entries for lines which returned a result) |
|
2989 | 2993 | available under the names _oh and Out (similar to _ih and In). So the |
|
2990 | 2994 | output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you |
|
2991 | 2995 | accidentally overwrite the Out variable you can recover it by typing |
|
2992 | 2996 | 'Out=_oh' at the prompt. |
|
2993 | 2997 | |
|
2994 | 2998 | This system obviously can potentially put heavy memory demands on your |
|
2995 | 2999 | system, since it prevents Python's garbage collector from removing any |
|
2996 | 3000 | previously computed results. You can control how many results are kept |
|
2997 | 3001 | in memory with the option (at the command line or in your ipythonrc |
|
2998 | 3002 | file) cache_size. If you set it to 0, the whole system is completely |
|
2999 | 3003 | disabled and the prompts revert to the classic '>>>' of normal Python. |
|
3000 | 3004 | |
|
3001 | 3005 | |
|
3002 | 3006 | Directory history |
|
3003 | 3007 | ----------------- |
|
3004 | 3008 | |
|
3005 | 3009 | Your history of visited directories is kept in the global list _dh, and |
|
3006 | 3010 | the magic %cd command can be used to go to any entry in that list. The |
|
3007 | 3011 | %dhist command allows you to view this history. |
|
3008 | 3012 | |
|
3009 | 3013 | |
|
3010 | 3014 | Automatic parentheses and quotes |
|
3011 | 3015 | -------------------------------- |
|
3012 | 3016 | |
|
3013 | 3017 | These features were adapted from Nathan Gray's LazyPython. They are |
|
3014 | 3018 | meant to allow less typing for common situations. |
|
3015 | 3019 | |
|
3016 | 3020 | |
|
3017 | 3021 | Automatic parentheses |
|
3018 | 3022 | --------------------- |
|
3019 | 3023 | |
|
3020 | 3024 | Callable objects (i.e. functions, methods, etc) can be invoked like this |
|
3021 | 3025 | (notice the commas between the arguments):: |
|
3022 | 3026 | |
|
3023 | 3027 | >>> callable_ob arg1, arg2, arg3 |
|
3024 | 3028 | |
|
3025 | 3029 | and the input will be translated to this:: |
|
3026 | 3030 | |
|
3027 | 3031 | -> callable_ob(arg1, arg2, arg3) |
|
3028 | 3032 | |
|
3029 | 3033 | You can force automatic parentheses by using '/' as the first character |
|
3030 | 3034 | of a line. For example:: |
|
3031 | 3035 | |
|
3032 | 3036 | >>> /globals # becomes 'globals()' |
|
3033 | 3037 | |
|
3034 | 3038 | Note that the '/' MUST be the first character on the line! This won't work:: |
|
3035 | 3039 | |
|
3036 | 3040 | >>> print /globals # syntax error |
|
3037 | 3041 | |
|
3038 | 3042 | In most cases the automatic algorithm should work, so you should rarely |
|
3039 | 3043 | need to explicitly invoke /. One notable exception is if you are trying |
|
3040 | 3044 | to call a function with a list of tuples as arguments (the parenthesis |
|
3041 | 3045 | will confuse IPython):: |
|
3042 | 3046 | |
|
3043 | 3047 | In [1]: zip (1,2,3),(4,5,6) # won't work |
|
3044 | 3048 | |
|
3045 | 3049 | but this will work:: |
|
3046 | 3050 | |
|
3047 | 3051 | In [2]: /zip (1,2,3),(4,5,6) |
|
3048 | 3052 | ---> zip ((1,2,3),(4,5,6)) |
|
3049 | 3053 | Out[2]= [(1, 4), (2, 5), (3, 6)] |
|
3050 | 3054 | |
|
3051 | 3055 | IPython tells you that it has altered your command line by displaying |
|
3052 | 3056 | the new command line preceded by ->. e.g.:: |
|
3053 | 3057 | |
|
3054 | 3058 | In [18]: callable list |
|
3055 | 3059 | ----> callable (list) |
|
3056 | 3060 | |
|
3057 | 3061 | |
|
3058 | 3062 | Automatic quoting |
|
3059 | 3063 | ----------------- |
|
3060 | 3064 | |
|
3061 | 3065 | You can force automatic quoting of a function's arguments by using ',' |
|
3062 | 3066 | or ';' as the first character of a line. For example:: |
|
3063 | 3067 | |
|
3064 | 3068 | >>> ,my_function /home/me # becomes my_function("/home/me") |
|
3065 | 3069 | |
|
3066 | 3070 | If you use ';' instead, the whole argument is quoted as a single string |
|
3067 | 3071 | (while ',' splits on whitespace):: |
|
3068 | 3072 | |
|
3069 | 3073 | >>> ,my_function a b c # becomes my_function("a","b","c") |
|
3070 | 3074 | |
|
3071 | 3075 | >>> ;my_function a b c # becomes my_function("a b c") |
|
3072 | 3076 | |
|
3073 | 3077 | Note that the ',' or ';' MUST be the first character on the line! This |
|
3074 | 3078 | won't work:: |
|
3075 | 3079 | |
|
3076 | 3080 | >>> x = ,my_function /home/me # syntax error |
|
3077 | 3081 | |
|
3078 | 3082 | Customization |
|
3079 | 3083 | ============= |
|
3080 | 3084 | |
|
3081 | 3085 | As we've already mentioned, IPython reads a configuration file which can |
|
3082 | 3086 | be specified at the command line (-rcfile) or which by default is |
|
3083 | 3087 | assumed to be called ipythonrc. Such a file is looked for in the current |
|
3084 | 3088 | directory where IPython is started and then in your IPYTHONDIR, which |
|
3085 | 3089 | allows you to have local configuration files for specific projects. In |
|
3086 | 3090 | this section we will call these types of configuration files simply |
|
3087 | 3091 | rcfiles (short for resource configuration file). |
|
3088 | 3092 | |
|
3089 | 3093 | The syntax of an rcfile is one of key-value pairs separated by |
|
3090 | 3094 | whitespace, one per line. Lines beginning with a # are ignored as |
|
3091 | 3095 | comments, but comments can not be put on lines with data (the parser is |
|
3092 | 3096 | fairly primitive). Note that these are not python files, and this is |
|
3093 | 3097 | deliberate, because it allows us to do some things which would be quite |
|
3094 | 3098 | tricky to implement if they were normal python files. |
|
3095 | 3099 | |
|
3096 | 3100 | First, an rcfile can contain permanent default values for almost all |
|
3097 | 3101 | command line options (except things like -help or -Version). Sec 5.2 |
|
3098 | 3102 | <node5.html#sec:cmd-line-opts> contains a description of all |
|
3099 | 3103 | command-line options. However, values you explicitly specify at the |
|
3100 | 3104 | command line override the values defined in the rcfile. |
|
3101 | 3105 | |
|
3102 | 3106 | Besides command line option values, the rcfile can specify values for |
|
3103 | 3107 | certain extra special options which are not available at the command |
|
3104 | 3108 | line. These options are briefly described below. |
|
3105 | 3109 | |
|
3106 | 3110 | Each of these options may appear as many times as you need it in the file. |
|
3107 | 3111 | |
|
3108 | 3112 | * [include <file1> <file2> ...:] you can name other rcfiles you want |
|
3109 | 3113 | to recursively load up to 15 levels (don't use the <> brackets in |
|
3110 | 3114 | your names!). This feature allows you to define a 'base' rcfile |
|
3111 | 3115 | with general options and special-purpose files which can be loaded |
|
3112 | 3116 | only when needed with particular configuration options. To make |
|
3113 | 3117 | this more convenient, IPython accepts the -profile <name> option |
|
3114 | 3118 | (abbreviates to -p <name>) which tells it to look for an rcfile |
|
3115 | 3119 | named ipythonrc-<name>. |
|
3116 | 3120 | * [import_mod <mod1> <mod2> ...:] import modules with 'import |
|
3117 | 3121 | <mod1>,<mod2>,...' |
|
3118 | 3122 | * [import_some <mod> <f1> <f2> ...:] import functions with 'from |
|
3119 | 3123 | <mod> import <f1>,<f2>,...' |
|
3120 | 3124 | * [import_all <mod1> <mod2> ...:] for each module listed import |
|
3121 |
functions with |
|
|
3125 | functions with ``from <mod> import *``. | |
|
3122 | 3126 | * [execute <python code>:] give any single-line python code to be |
|
3123 | 3127 | executed. |
|
3124 | 3128 | * [execfile <filename>:] execute the python file given with an |
|
3125 | 3129 | 'execfile(filename)' command. Username expansion is performed on |
|
3126 | 3130 | the given names. So if you need any amount of extra fancy |
|
3127 | 3131 | customization that won't fit in any of the above 'canned' options, |
|
3128 | 3132 | you can just put it in a separate python file and execute it. |
|
3129 | 3133 | * [alias <alias_def>:] this is equivalent to calling |
|
3130 | 3134 | '%alias <alias_def>' at the IPython command line. This way, from |
|
3131 | 3135 | within IPython you can do common system tasks without having to |
|
3132 | 3136 | exit it or use the ! escape. IPython isn't meant to be a shell |
|
3133 | 3137 | replacement, but it is often very useful to be able to do things |
|
3134 | 3138 | with files while testing code. This gives you the flexibility to |
|
3135 | 3139 | have within IPython any aliases you may be used to under your |
|
3136 | 3140 | normal system shell. |
|
3137 | 3141 | |
|
3138 | 3142 | |
|
3139 | 3143 | |
|
3140 | 3144 | Sample ipythonrc file |
|
3141 | 3145 | --------------------- |
|
3142 | 3146 | |
|
3143 | 3147 | The default rcfile, called ipythonrc and supplied in your IPYTHONDIR |
|
3144 | 3148 | directory contains lots of comments on all of these options. We |
|
3145 | 3149 | reproduce it here for reference:: |
|
3146 | 3150 | |
|
3147 | 3151 | |
|
3148 | 3152 | # -*- Mode: Shell-Script -*- Not really, but shows comments correctly |
|
3149 | 3153 | # $Id: ipythonrc 2156 2007-03-19 02:32:19Z fperez $ |
|
3150 | 3154 | |
|
3151 | 3155 | #*************************************************************************** |
|
3152 | 3156 | # |
|
3153 | 3157 | # Configuration file for IPython -- ipythonrc format |
|
3154 | 3158 | # |
|
3155 | 3159 | # =========================================================== |
|
3156 | 3160 | # Deprecation note: you should look into modifying ipy_user_conf.py (located |
|
3157 | 3161 | # in ~/.ipython or ~/_ipython, depending on your platform) instead, it's a |
|
3158 | 3162 | # more flexible and robust (and better supported!) configuration |
|
3159 | 3163 | # method. |
|
3160 | 3164 | # =========================================================== |
|
3161 | 3165 | # |
|
3162 | 3166 | # The format of this file is simply one of 'key value' lines. |
|
3163 | 3167 | # Lines containing only whitespace at the beginning and then a # are ignored |
|
3164 | 3168 | # as comments. But comments can NOT be put on lines with data. |
|
3165 | 3169 | |
|
3166 | 3170 | # The meaning and use of each key are explained below. |
|
3167 | 3171 | |
|
3168 | 3172 | #--------------------------------------------------------------------------- |
|
3169 | 3173 | # Section: included files |
|
3170 | 3174 | |
|
3171 | 3175 | # Put one or more *config* files (with the syntax of this file) you want to |
|
3172 | 3176 | # include. For keys with a unique value the outermost file has precedence. For |
|
3173 | 3177 | # keys with multiple values, they all get assembled into a list which then |
|
3174 | 3178 | # gets loaded by IPython. |
|
3175 | 3179 | |
|
3176 | 3180 | # In this file, all lists of things should simply be space-separated. |
|
3177 | 3181 | |
|
3178 | 3182 | # This allows you to build hierarchies of files which recursively load |
|
3179 | 3183 | # lower-level services. If this is your main ~/.ipython/ipythonrc file, you |
|
3180 | 3184 | # should only keep here basic things you always want available. Then you can |
|
3181 | 3185 | # include it in every other special-purpose config file you create. |
|
3182 | 3186 | include |
|
3183 | 3187 | |
|
3184 | 3188 | #--------------------------------------------------------------------------- |
|
3185 | 3189 | # Section: startup setup |
|
3186 | 3190 | |
|
3187 | 3191 | # These are mostly things which parallel a command line option of the same |
|
3188 | 3192 | # name. |
|
3189 | 3193 | |
|
3190 | 3194 | # Keys in this section should only appear once. If any key from this section |
|
3191 | 3195 | # is encountered more than once, the last value remains, all earlier ones get |
|
3192 | 3196 | # discarded. |
|
3193 | 3197 | |
|
3194 | 3198 | |
|
3195 | 3199 | # Automatic calling of callable objects. If set to 1 or 2, callable objects |
|
3196 | 3200 | # are automatically called when invoked at the command line, even if you don't |
|
3197 | 3201 | # type parentheses. IPython adds the parentheses for you. For example: |
|
3198 | 3202 | |
|
3199 | 3203 | #In [1]: str 45 |
|
3200 | 3204 | #------> str(45) |
|
3201 | 3205 | #Out[1]: '45' |
|
3202 | 3206 | |
|
3203 | 3207 | # IPython reprints your line with '---->' indicating that it added |
|
3204 | 3208 | # parentheses. While this option is very convenient for interactive use, it |
|
3205 | 3209 | # may occasionally cause problems with objects which have side-effects if |
|
3206 | 3210 | # called unexpectedly. |
|
3207 | 3211 | |
|
3208 | 3212 | # The valid values for autocall are: |
|
3209 | 3213 | |
|
3210 | 3214 | # autocall 0 -> disabled (you can toggle it at runtime with the %autocall magic) |
|
3211 | 3215 | |
|
3212 | 3216 | # autocall 1 -> active, but do not apply if there are no arguments on the line. |
|
3213 | 3217 | |
|
3214 | 3218 | # In this mode, you get: |
|
3215 | 3219 | |
|
3216 | 3220 | #In [1]: callable |
|
3217 | 3221 | #Out[1]: <built-in function callable> |
|
3218 | 3222 | |
|
3219 | 3223 | #In [2]: callable 'hello' |
|
3220 | 3224 | #------> callable('hello') |
|
3221 | 3225 | #Out[2]: False |
|
3222 | 3226 | |
|
3223 | 3227 | # 2 -> Active always. Even if no arguments are present, the callable object |
|
3224 | 3228 | # is called: |
|
3225 | 3229 | |
|
3226 | 3230 | #In [4]: callable |
|
3227 | 3231 | #------> callable() |
|
3228 | 3232 | |
|
3229 | 3233 | # Note that even with autocall off, you can still use '/' at the start of a |
|
3230 | 3234 | # line to treat the first argument on the command line as a function and add |
|
3231 | 3235 | # parentheses to it: |
|
3232 | 3236 | |
|
3233 | 3237 | #In [8]: /str 43 |
|
3234 | 3238 | #------> str(43) |
|
3235 | 3239 | #Out[8]: '43' |
|
3236 | 3240 | |
|
3237 | 3241 | autocall 1 |
|
3238 | 3242 | |
|
3239 | 3243 | # Auto-edit syntax errors. When you use the %edit magic in ipython to edit |
|
3240 | 3244 | # source code (see the 'editor' variable below), it is possible that you save |
|
3241 | 3245 | # a file with syntax errors in it. If this variable is true, IPython will ask |
|
3242 | 3246 | # you whether to re-open the editor immediately to correct such an error. |
|
3243 | 3247 | |
|
3244 | 3248 | autoedit_syntax 0 |
|
3245 | 3249 | |
|
3246 | 3250 | # Auto-indent. IPython can recognize lines ending in ':' and indent the next |
|
3247 | 3251 | # line, while also un-indenting automatically after 'raise' or 'return'. |
|
3248 | 3252 | |
|
3249 | 3253 | # This feature uses the readline library, so it will honor your ~/.inputrc |
|
3250 | 3254 | # configuration (or whatever file your INPUTRC variable points to). Adding |
|
3251 | 3255 | # the following lines to your .inputrc file can make indent/unindenting more |
|
3252 | 3256 | # convenient (M-i indents, M-u unindents): |
|
3253 | 3257 | |
|
3254 | 3258 | # $if Python |
|
3255 | 3259 | # "\M-i": " " |
|
3256 | 3260 | # "\M-u": "\d\d\d\d" |
|
3257 | 3261 | # $endif |
|
3258 | 3262 | |
|
3259 | 3263 | # The feature is potentially a bit dangerous, because it can cause problems |
|
3260 | 3264 | # with pasting of indented code (the pasted code gets re-indented on each |
|
3261 | 3265 | # line). But it's a huge time-saver when working interactively. The magic |
|
3262 | 3266 | # function %autoindent allows you to toggle it on/off at runtime. |
|
3263 | 3267 | |
|
3264 | 3268 | autoindent 1 |
|
3265 | 3269 | |
|
3266 | 3270 | # Auto-magic. This gives you access to all the magic functions without having |
|
3267 | 3271 | # to prepend them with an % sign. If you define a variable with the same name |
|
3268 | 3272 | # as a magic function (say who=1), you will need to access the magic function |
|
3269 | 3273 | # with % (%who in this example). However, if later you delete your variable |
|
3270 | 3274 | # (del who), you'll recover the automagic calling form. |
|
3271 | 3275 | |
|
3272 | 3276 | # Considering that many magic functions provide a lot of shell-like |
|
3273 | 3277 | # functionality, automagic gives you something close to a full Python+system |
|
3274 | 3278 | # shell environment (and you can extend it further if you want). |
|
3275 | 3279 | |
|
3276 | 3280 | automagic 1 |
|
3277 | 3281 | |
|
3278 | 3282 | # Size of the output cache. After this many entries are stored, the cache will |
|
3279 | 3283 | # get flushed. Depending on the size of your intermediate calculations, you |
|
3280 | 3284 | # may have memory problems if you make it too big, since keeping things in the |
|
3281 | 3285 | # cache prevents Python from reclaiming the memory for old results. Experiment |
|
3282 | 3286 | # with a value that works well for you. |
|
3283 | 3287 | |
|
3284 | 3288 | # If you choose cache_size 0 IPython will revert to python's regular >>> |
|
3285 | 3289 | # unnumbered prompt. You will still have _, __ and ___ for your last three |
|
3286 | 3290 | # results, but that will be it. No dynamic _1, _2, etc. will be created. If |
|
3287 | 3291 | # you are running on a slow machine or with very limited memory, this may |
|
3288 | 3292 | # help. |
|
3289 | 3293 | |
|
3290 | 3294 | cache_size 1000 |
|
3291 | 3295 | |
|
3292 | 3296 | # Classic mode: Setting 'classic 1' you lose many of IPython niceties, |
|
3293 | 3297 | # but that's your choice! Classic 1 -> same as IPython -classic. |
|
3294 | 3298 | # Note that this is _not_ the normal python interpreter, it's simply |
|
3295 | 3299 | # IPython emulating most of the classic interpreter's behavior. |
|
3296 | 3300 | classic 0 |
|
3297 | 3301 | |
|
3298 | 3302 | # colors - Coloring option for prompts and traceback printouts. |
|
3299 | 3303 | |
|
3300 | 3304 | # Currently available schemes: NoColor, Linux, LightBG. |
|
3301 | 3305 | |
|
3302 | 3306 | # This option allows coloring the prompts and traceback printouts. This |
|
3303 | 3307 | # requires a terminal which can properly handle color escape sequences. If you |
|
3304 | 3308 | # are having problems with this, use the NoColor scheme (uses no color escapes |
|
3305 | 3309 | # at all). |
|
3306 | 3310 | |
|
3307 | 3311 | # The Linux option works well in linux console type environments: dark |
|
3308 | 3312 | # background with light fonts. |
|
3309 | 3313 | |
|
3310 | 3314 | # LightBG is similar to Linux but swaps dark/light colors to be more readable |
|
3311 | 3315 | # in light background terminals. |
|
3312 | 3316 | |
|
3313 | 3317 | # keep uncommented only the one you want: |
|
3314 | 3318 | colors Linux |
|
3315 | 3319 | #colors LightBG |
|
3316 | 3320 | #colors NoColor |
|
3317 | 3321 | |
|
3318 | 3322 | ######################## |
|
3319 | 3323 | # Note to Windows users |
|
3320 | 3324 | # |
|
3321 | 3325 | # Color and readline support is avaialble to Windows users via Gary Bishop's |
|
3322 | 3326 | # readline library. You can find Gary's tools at |
|
3323 | 3327 | # http://sourceforge.net/projects/uncpythontools. |
|
3324 | 3328 | # Note that his readline module requires in turn the ctypes library, available |
|
3325 | 3329 | # at http://starship.python.net/crew/theller/ctypes. |
|
3326 | 3330 | ######################## |
|
3327 | 3331 | |
|
3328 | 3332 | # color_info: IPython can display information about objects via a set of |
|
3329 | 3333 | # functions, and optionally can use colors for this, syntax highlighting |
|
3330 | 3334 | # source code and various other elements. This information is passed through a |
|
3331 | 3335 | # pager (it defaults to 'less' if $PAGER is not set). |
|
3332 | 3336 | |
|
3333 | 3337 | # If your pager has problems, try to setting it to properly handle escapes |
|
3334 | 3338 | # (see the less manpage for detail), or disable this option. The magic |
|
3335 | 3339 | # function %color_info allows you to toggle this interactively for testing. |
|
3336 | 3340 | |
|
3337 | 3341 | color_info 1 |
|
3338 | 3342 | |
|
3339 | 3343 | # confirm_exit: set to 1 if you want IPython to confirm when you try to exit |
|
3340 | 3344 | # with an EOF (Control-d in Unix, Control-Z/Enter in Windows). Note that using |
|
3341 | 3345 | # the magic functions %Exit or %Quit you can force a direct exit, bypassing |
|
3342 | 3346 | # any confirmation. |
|
3343 | 3347 | |
|
3344 | 3348 | confirm_exit 1 |
|
3345 | 3349 | |
|
3346 | 3350 | # Use deep_reload() as a substitute for reload() by default. deep_reload() is |
|
3347 | 3351 | # still available as dreload() and appears as a builtin. |
|
3348 | 3352 | |
|
3349 | 3353 | deep_reload 0 |
|
3350 | 3354 | |
|
3351 | 3355 | # Which editor to use with the %edit command. If you leave this at 0, IPython |
|
3352 | 3356 | # will honor your EDITOR environment variable. Since this editor is invoked on |
|
3353 | 3357 | # the fly by ipython and is meant for editing small code snippets, you may |
|
3354 | 3358 | # want to use a small, lightweight editor here. |
|
3355 | 3359 | |
|
3356 | 3360 | # For Emacs users, setting up your Emacs server properly as described in the |
|
3357 | 3361 | # manual is a good idea. An alternative is to use jed, a very light editor |
|
3358 | 3362 | # with much of the feel of Emacs (though not as powerful for heavy-duty work). |
|
3359 | 3363 | |
|
3360 | 3364 | editor 0 |
|
3361 | 3365 | |
|
3362 | 3366 | # log 1 -> same as ipython -log. This automatically logs to ./ipython.log |
|
3363 | 3367 | log 0 |
|
3364 | 3368 | |
|
3365 | 3369 | # Same as ipython -Logfile YourLogfileName. |
|
3366 | 3370 | # Don't use with log 1 (use one or the other) |
|
3367 | 3371 | logfile '' |
|
3368 | 3372 | |
|
3369 | 3373 | # banner 0 -> same as ipython -nobanner |
|
3370 | 3374 | banner 1 |
|
3371 | 3375 | |
|
3372 | 3376 | # messages 0 -> same as ipython -nomessages |
|
3373 | 3377 | messages 1 |
|
3374 | 3378 | |
|
3375 | 3379 | # Automatically call the pdb debugger after every uncaught exception. If you |
|
3376 | 3380 | # are used to debugging using pdb, this puts you automatically inside of it |
|
3377 | 3381 | # after any call (either in IPython or in code called by it) which triggers an |
|
3378 | 3382 | # exception which goes uncaught. |
|
3379 | 3383 | pdb 0 |
|
3380 | 3384 | |
|
3381 | 3385 | # Enable the pprint module for printing. pprint tends to give a more readable |
|
3382 | 3386 | # display (than print) for complex nested data structures. |
|
3383 | 3387 | pprint 1 |
|
3384 | 3388 | |
|
3385 | 3389 | # Prompt strings |
|
3386 | 3390 | |
|
3387 | 3391 | # Most bash-like escapes can be used to customize IPython's prompts, as well as |
|
3388 | 3392 | # a few additional ones which are IPython-specific. All valid prompt escapes |
|
3389 | 3393 | # are described in detail in the Customization section of the IPython HTML/PDF |
|
3390 | 3394 | # manual. |
|
3391 | 3395 | |
|
3392 | 3396 | # Use \# to represent the current prompt number, and quote them to protect |
|
3393 | 3397 | # spaces. |
|
3394 | 3398 | prompt_in1 'In [\#]: ' |
|
3395 | 3399 | |
|
3396 | 3400 | # \D is replaced by as many dots as there are digits in the |
|
3397 | 3401 | # current value of \#. |
|
3398 | 3402 | prompt_in2 ' .\D.: ' |
|
3399 | 3403 | |
|
3400 | 3404 | prompt_out 'Out[\#]: ' |
|
3401 | 3405 | |
|
3402 | 3406 | # Select whether to left-pad the output prompts to match the length of the |
|
3403 | 3407 | # input ones. This allows you for example to use a simple '>' as an output |
|
3404 | 3408 | # prompt, and yet have the output line up with the input. If set to false, |
|
3405 | 3409 | # the output prompts will be unpadded (flush left). |
|
3406 | 3410 | prompts_pad_left 1 |
|
3407 | 3411 | |
|
3408 | 3412 | # Pylab support: when ipython is started with the -pylab switch, by default it |
|
3409 | 3413 | # executes 'from matplotlib.pylab import *'. Set this variable to false if you |
|
3410 | 3414 | # want to disable this behavior. |
|
3411 | 3415 | |
|
3412 | 3416 | # For details on pylab, see the matplotlib website: |
|
3413 | 3417 | # http://matplotlib.sf.net |
|
3414 | 3418 | pylab_import_all 1 |
|
3415 | 3419 | |
|
3416 | 3420 | |
|
3417 | 3421 | # quick 1 -> same as ipython -quick |
|
3418 | 3422 | quick 0 |
|
3419 | 3423 | |
|
3420 | 3424 | # Use the readline library (1) or not (0). Most users will want this on, but |
|
3421 | 3425 | # if you experience strange problems with line management (mainly when using |
|
3422 | 3426 | # IPython inside Emacs buffers) you may try disabling it. Not having it on |
|
3423 | 3427 | # prevents you from getting command history with the arrow keys, searching and |
|
3424 | 3428 | # name completion using TAB. |
|
3425 | 3429 | |
|
3426 | 3430 | readline 1 |
|
3427 | 3431 | |
|
3428 | 3432 | # Screen Length: number of lines of your screen. This is used to control |
|
3429 | 3433 | # printing of very long strings. Strings longer than this number of lines will |
|
3430 | 3434 | # be paged with the less command instead of directly printed. |
|
3431 | 3435 | |
|
3432 | 3436 | # The default value for this is 0, which means IPython will auto-detect your |
|
3433 | 3437 | # screen size every time it needs to print. If for some reason this isn't |
|
3434 | 3438 | # working well (it needs curses support), specify it yourself. Otherwise don't |
|
3435 | 3439 | # change the default. |
|
3436 | 3440 | |
|
3437 | 3441 | screen_length 0 |
|
3438 | 3442 | |
|
3439 | 3443 | # Prompt separators for input and output. |
|
3440 | 3444 | # Use \n for newline explicitly, without quotes. |
|
3441 | 3445 | # Use 0 (like at the cmd line) to turn off a given separator. |
|
3442 | 3446 | |
|
3443 | 3447 | # The structure of prompt printing is: |
|
3444 | 3448 | # (SeparateIn)Input.... |
|
3445 | 3449 | # (SeparateOut)Output... |
|
3446 | 3450 | # (SeparateOut2), # that is, no newline is printed after Out2 |
|
3447 | 3451 | # By choosing these you can organize your output any way you want. |
|
3448 | 3452 | |
|
3449 | 3453 | separate_in \n |
|
3450 | 3454 | separate_out 0 |
|
3451 | 3455 | separate_out2 0 |
|
3452 | 3456 | |
|
3453 | 3457 | # 'nosep 1' is a shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'. |
|
3454 | 3458 | # Simply removes all input/output separators, overriding the choices above. |
|
3455 | 3459 | nosep 0 |
|
3456 | 3460 | |
|
3457 | 3461 | # Wildcard searches - IPython has a system for searching names using |
|
3458 | 3462 | # shell-like wildcards; type %psearch? for details. This variables sets |
|
3459 | 3463 | # whether by default such searches should be case sensitive or not. You can |
|
3460 | 3464 | # always override the default at the system command line or the IPython |
|
3461 | 3465 | # prompt. |
|
3462 | 3466 | |
|
3463 | 3467 | wildcards_case_sensitive 1 |
|
3464 | 3468 | |
|
3465 | 3469 | # Object information: at what level of detail to display the string form of an |
|
3466 | 3470 | # object. If set to 0, ipython will compute the string form of any object X, |
|
3467 | 3471 | # by calling str(X), when X? is typed. If set to 1, str(X) will only be |
|
3468 | 3472 | # computed when X?? is given, and if set to 2 or higher, it will never be |
|
3469 | 3473 | # computed (there is no X??? level of detail). This is mostly of use to |
|
3470 | 3474 | # people who frequently manipulate objects whose string representation is |
|
3471 | 3475 | # extremely expensive to compute. |
|
3472 | 3476 | |
|
3473 | 3477 | object_info_string_level 0 |
|
3474 | 3478 | |
|
3475 | 3479 | # xmode - Exception reporting mode. |
|
3476 | 3480 | |
|
3477 | 3481 | # Valid modes: Plain, Context and Verbose. |
|
3478 | 3482 | |
|
3479 | 3483 | # Plain: similar to python's normal traceback printing. |
|
3480 | 3484 | |
|
3481 | 3485 | # Context: prints 5 lines of context source code around each line in the |
|
3482 | 3486 | # traceback. |
|
3483 | 3487 | |
|
3484 | 3488 | # Verbose: similar to Context, but additionally prints the variables currently |
|
3485 | 3489 | # visible where the exception happened (shortening their strings if too |
|
3486 | 3490 | # long). This can potentially be very slow, if you happen to have a huge data |
|
3487 | 3491 | # structure whose string representation is complex to compute. Your computer |
|
3488 | 3492 | # may appear to freeze for a while with cpu usage at 100%. If this occurs, you |
|
3489 | 3493 | # can cancel the traceback with Ctrl-C (maybe hitting it more than once). |
|
3490 | 3494 | |
|
3491 | 3495 | #xmode Plain |
|
3492 | 3496 | xmode Context |
|
3493 | 3497 | #xmode Verbose |
|
3494 | 3498 | |
|
3495 | 3499 | # multi_line_specials: if true, allow magics, aliases and shell escapes (via |
|
3496 | 3500 | # !cmd) to be used in multi-line input (like for loops). For example, if you |
|
3497 | 3501 | # have this active, the following is valid in IPython: |
|
3498 | 3502 | # |
|
3499 | 3503 | #In [17]: for i in range(3): |
|
3500 | 3504 | # ....: mkdir $i |
|
3501 | 3505 | # ....: !touch $i/hello |
|
3502 | 3506 | # ....: ls -l $i |
|
3503 | 3507 | |
|
3504 | 3508 | multi_line_specials 1 |
|
3505 | 3509 | |
|
3506 | 3510 | |
|
3507 | 3511 | # System calls: When IPython makes system calls (e.g. via special syntax like |
|
3508 | 3512 | # !cmd or !!cmd, or magics like %sc or %sx), it can print the command it is |
|
3509 | 3513 | # executing to standard output, prefixed by a header string. |
|
3510 | 3514 | |
|
3511 | 3515 | system_header "IPython system call: " |
|
3512 | 3516 | |
|
3513 | 3517 | system_verbose 1 |
|
3514 | 3518 | |
|
3515 | 3519 | # wxversion: request a specific wxPython version (used for -wthread) |
|
3516 | 3520 | |
|
3517 | 3521 | # Set this to the value of wxPython you want to use, but note that this |
|
3518 | 3522 | # feature requires you to have the wxversion Python module to work. If you |
|
3519 | 3523 | # don't have the wxversion module (try 'import wxversion' at the prompt to |
|
3520 | 3524 | # check) or simply want to leave the system to pick up the default, leave this |
|
3521 | 3525 | # variable at 0. |
|
3522 | 3526 | |
|
3523 | 3527 | wxversion 0 |
|
3524 | 3528 | |
|
3525 | 3529 | #--------------------------------------------------------------------------- |
|
3526 | 3530 | # Section: Readline configuration (readline is not available for MS-Windows) |
|
3527 | 3531 | |
|
3528 | 3532 | # This is done via the following options: |
|
3529 | 3533 | |
|
3530 | 3534 | # (i) readline_parse_and_bind: this option can appear as many times as you |
|
3531 | 3535 | # want, each time defining a string to be executed via a |
|
3532 | 3536 | # readline.parse_and_bind() command. The syntax for valid commands of this |
|
3533 | 3537 | # kind can be found by reading the documentation for the GNU readline library, |
|
3534 | 3538 | # as these commands are of the kind which readline accepts in its |
|
3535 | 3539 | # configuration file. |
|
3536 | 3540 | |
|
3537 | 3541 | # The TAB key can be used to complete names at the command line in one of two |
|
3538 | 3542 | # ways: 'complete' and 'menu-complete'. The difference is that 'complete' only |
|
3539 | 3543 | # completes as much as possible while 'menu-complete' cycles through all |
|
3540 | 3544 | # possible completions. Leave the one you prefer uncommented. |
|
3541 | 3545 | |
|
3542 | 3546 | readline_parse_and_bind tab: complete |
|
3543 | 3547 | #readline_parse_and_bind tab: menu-complete |
|
3544 | 3548 | |
|
3545 | 3549 | # This binds Control-l to printing the list of all possible completions when |
|
3546 | 3550 | # there is more than one (what 'complete' does when hitting TAB twice, or at |
|
3547 | 3551 | # the first TAB if show-all-if-ambiguous is on) |
|
3548 | 3552 | readline_parse_and_bind "\C-l": possible-completions |
|
3549 | 3553 | |
|
3550 | 3554 | # This forces readline to automatically print the above list when tab |
|
3551 | 3555 | # completion is set to 'complete'. You can still get this list manually by |
|
3552 | 3556 | # using the key bound to 'possible-completions' (Control-l by default) or by |
|
3553 | 3557 | # hitting TAB twice. Turning this on makes the printing happen at the first |
|
3554 | 3558 | # TAB. |
|
3555 | 3559 | readline_parse_and_bind set show-all-if-ambiguous on |
|
3556 | 3560 | |
|
3557 | 3561 | # If you have TAB set to complete names, you can rebind any key (Control-o by |
|
3558 | 3562 | # default) to insert a true TAB character. |
|
3559 | 3563 | readline_parse_and_bind "\C-o": tab-insert |
|
3560 | 3564 | |
|
3561 | 3565 | # These commands allow you to indent/unindent easily, with the 4-space |
|
3562 | 3566 | # convention of the Python coding standards. Since IPython's internal |
|
3563 | 3567 | # auto-indent system also uses 4 spaces, you should not change the number of |
|
3564 | 3568 | # spaces in the code below. |
|
3565 | 3569 | readline_parse_and_bind "\M-i": " " |
|
3566 | 3570 | readline_parse_and_bind "\M-o": "\d\d\d\d" |
|
3567 | 3571 | readline_parse_and_bind "\M-I": "\d\d\d\d" |
|
3568 | 3572 | |
|
3569 | 3573 | # Bindings for incremental searches in the history. These searches use the |
|
3570 | 3574 | # string typed so far on the command line and search anything in the previous |
|
3571 | 3575 | # input history containing them. |
|
3572 | 3576 | readline_parse_and_bind "\C-r": reverse-search-history |
|
3573 | 3577 | readline_parse_and_bind "\C-s": forward-search-history |
|
3574 | 3578 | |
|
3575 | 3579 | # Bindings for completing the current line in the history of previous |
|
3576 | 3580 | # commands. This allows you to recall any previous command by typing its first |
|
3577 | 3581 | # few letters and hitting Control-p, bypassing all intermediate commands which |
|
3578 | 3582 | # may be in the history (much faster than hitting up-arrow 50 times!) |
|
3579 | 3583 | readline_parse_and_bind "\C-p": history-search-backward |
|
3580 | 3584 | readline_parse_and_bind "\C-n": history-search-forward |
|
3581 | 3585 | |
|
3582 | 3586 | # I also like to have the same functionality on the plain arrow keys. If you'd |
|
3583 | 3587 | # rather have the arrows use all the history (and not just match what you've |
|
3584 | 3588 | # typed so far), comment out or delete the next two lines. |
|
3585 | 3589 | readline_parse_and_bind "\e[A": history-search-backward |
|
3586 | 3590 | readline_parse_and_bind "\e[B": history-search-forward |
|
3587 | 3591 | |
|
3588 | 3592 | # These are typically on by default under *nix, but not win32. |
|
3589 | 3593 | readline_parse_and_bind "\C-k": kill-line |
|
3590 | 3594 | readline_parse_and_bind "\C-u": unix-line-discard |
|
3591 | 3595 | |
|
3592 | 3596 | # (ii) readline_remove_delims: a string of characters to be removed from the |
|
3593 | 3597 | # default word-delimiters list used by readline, so that completions may be |
|
3594 | 3598 | # performed on strings which contain them. |
|
3595 | 3599 | |
|
3596 | 3600 | readline_remove_delims -/~ |
|
3597 | 3601 | |
|
3598 | 3602 | # (iii) readline_merge_completions: whether to merge the result of all |
|
3599 | 3603 | # possible completions or not. If true, IPython will complete filenames, |
|
3600 | 3604 | # python names and aliases and return all possible completions. If you set it |
|
3601 | 3605 | # to false, each completer is used at a time, and only if it doesn't return |
|
3602 | 3606 | # any completions is the next one used. |
|
3603 | 3607 | |
|
3604 | 3608 | # The default order is: [python_matches, file_matches, alias_matches] |
|
3605 | 3609 | |
|
3606 | 3610 | readline_merge_completions 1 |
|
3607 | 3611 | |
|
3608 | 3612 | # (iv) readline_omit__names: normally hitting <tab> after a '.' in a name |
|
3609 | 3613 | # will complete all attributes of an object, including all the special methods |
|
3610 | 3614 | # whose names start with single or double underscores (like __getitem__ or |
|
3611 | 3615 | # __class__). |
|
3612 | 3616 | |
|
3613 | 3617 | # This variable allows you to control this completion behavior: |
|
3614 | 3618 | |
|
3615 | 3619 | # readline_omit__names 1 -> completion will omit showing any names starting |
|
3616 | 3620 | # with two __, but it will still show names starting with one _. |
|
3617 | 3621 | |
|
3618 | 3622 | # readline_omit__names 2 -> completion will omit all names beginning with one |
|
3619 | 3623 | # _ (which obviously means filtering out the double __ ones). |
|
3620 | 3624 | |
|
3621 | 3625 | # Even when this option is set, you can still see those names by explicitly |
|
3622 | 3626 | # typing a _ after the period and hitting <tab>: 'name._<tab>' will always |
|
3623 | 3627 | # complete attribute names starting with '_'. |
|
3624 | 3628 | |
|
3625 | 3629 | # This option is off by default so that new users see all attributes of any |
|
3626 | 3630 | # objects they are dealing with. |
|
3627 | 3631 | |
|
3628 | 3632 | readline_omit__names 0 |
|
3629 | 3633 | |
|
3630 | 3634 | #--------------------------------------------------------------------------- |
|
3631 | 3635 | # Section: modules to be loaded with 'import ...' |
|
3632 | 3636 | |
|
3633 | 3637 | # List, separated by spaces, the names of the modules you want to import |
|
3634 | 3638 | |
|
3635 | 3639 | # Example: |
|
3636 | 3640 | # import_mod sys os |
|
3637 | 3641 | # will produce internally the statements |
|
3638 | 3642 | # import sys |
|
3639 | 3643 | # import os |
|
3640 | 3644 | |
|
3641 | 3645 | # Each import is executed in its own try/except block, so if one module |
|
3642 | 3646 | # fails to load the others will still be ok. |
|
3643 | 3647 | |
|
3644 | 3648 | import_mod |
|
3645 | 3649 | |
|
3646 | 3650 | #--------------------------------------------------------------------------- |
|
3647 | 3651 | # Section: modules to import some functions from: 'from ... import ...' |
|
3648 | 3652 | |
|
3649 | 3653 | # List, one per line, the modules for which you want only to import some |
|
3650 | 3654 | # functions. Give the module name first and then the name of functions to be |
|
3651 | 3655 | # imported from that module. |
|
3652 | 3656 | |
|
3653 | 3657 | # Example: |
|
3654 | 3658 | |
|
3655 | 3659 | # import_some IPython.genutils timing timings |
|
3656 | 3660 | # will produce internally the statement |
|
3657 | 3661 | # from IPython.genutils import timing, timings |
|
3658 | 3662 | |
|
3659 | 3663 | # timing() and timings() are two IPython utilities for timing the execution of |
|
3660 | 3664 | # your own functions, which you may find useful. Just commment out the above |
|
3661 | 3665 | # line if you want to test them. |
|
3662 | 3666 | |
|
3663 | 3667 | # If you have more than one modules_some line, each gets its own try/except |
|
3664 | 3668 | # block (like modules, see above). |
|
3665 | 3669 | |
|
3666 | 3670 | import_some |
|
3667 | 3671 | |
|
3668 | 3672 | #--------------------------------------------------------------------------- |
|
3669 | 3673 | # Section: modules to import all from : 'from ... import *' |
|
3670 | 3674 | |
|
3671 | 3675 | # List (same syntax as import_mod above) those modules for which you want to |
|
3672 | 3676 | # import all functions. Remember, this is a potentially dangerous thing to do, |
|
3673 | 3677 | # since it is very easy to overwrite names of things you need. Use with |
|
3674 | 3678 | # caution. |
|
3675 | 3679 | |
|
3676 | 3680 | # Example: |
|
3677 | 3681 | # import_all sys os |
|
3678 | 3682 | # will produce internally the statements |
|
3679 | 3683 | # from sys import * |
|
3680 | 3684 | # from os import * |
|
3681 | 3685 | |
|
3682 | 3686 | # As before, each will be called in a separate try/except block. |
|
3683 | 3687 | |
|
3684 | 3688 | import_all |
|
3685 | 3689 | |
|
3686 | 3690 | #--------------------------------------------------------------------------- |
|
3687 | 3691 | # Section: Python code to execute. |
|
3688 | 3692 | |
|
3689 | 3693 | # Put here code to be explicitly executed (keep it simple!) |
|
3690 | 3694 | # Put one line of python code per line. All whitespace is removed (this is a |
|
3691 | 3695 | # feature, not a bug), so don't get fancy building loops here. |
|
3692 | 3696 | # This is just for quick convenient creation of things you want available. |
|
3693 | 3697 | |
|
3694 | 3698 | # Example: |
|
3695 | 3699 | # execute x = 1 |
|
3696 | 3700 | # execute print 'hello world'; y = z = 'a' |
|
3697 | 3701 | # will produce internally |
|
3698 | 3702 | # x = 1 |
|
3699 | 3703 | # print 'hello world'; y = z = 'a' |
|
3700 | 3704 | # and each *line* (not each statement, we don't do python syntax parsing) is |
|
3701 | 3705 | # executed in its own try/except block. |
|
3702 | 3706 | |
|
3703 | 3707 | execute |
|
3704 | 3708 | |
|
3705 | 3709 | # Note for the adventurous: you can use this to define your own names for the |
|
3706 | 3710 | # magic functions, by playing some namespace tricks: |
|
3707 | 3711 | |
|
3708 | 3712 | # execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile |
|
3709 | 3713 | |
|
3710 | 3714 | # defines %pf as a new name for %profile. |
|
3711 | 3715 | |
|
3712 | 3716 | #--------------------------------------------------------------------------- |
|
3713 | 3717 | # Section: Pyhton files to load and execute. |
|
3714 | 3718 | |
|
3715 | 3719 | # Put here the full names of files you want executed with execfile(file). If |
|
3716 | 3720 | # you want complicated initialization, just write whatever you want in a |
|
3717 | 3721 | # regular python file and load it from here. |
|
3718 | 3722 | |
|
3719 | 3723 | # Filenames defined here (which *must* include the extension) are searched for |
|
3720 | 3724 | # through all of sys.path. Since IPython adds your .ipython directory to |
|
3721 | 3725 | # sys.path, they can also be placed in your .ipython dir and will be |
|
3722 | 3726 | # found. Otherwise (if you want to execute things not in .ipyton nor in |
|
3723 | 3727 | # sys.path) give a full path (you can use ~, it gets expanded) |
|
3724 | 3728 | |
|
3725 | 3729 | # Example: |
|
3726 | 3730 | # execfile file1.py ~/file2.py |
|
3727 | 3731 | # will generate |
|
3728 | 3732 | # execfile('file1.py') |
|
3729 | 3733 | # execfile('_path_to_your_home/file2.py') |
|
3730 | 3734 | |
|
3731 | 3735 | # As before, each file gets its own try/except block. |
|
3732 | 3736 | |
|
3733 | 3737 | execfile |
|
3734 | 3738 | |
|
3735 | 3739 | # If you are feeling adventurous, you can even add functionality to IPython |
|
3736 | 3740 | # through here. IPython works through a global variable called __ip which |
|
3737 | 3741 | # exists at the time when these files are read. If you know what you are doing |
|
3738 | 3742 | # (read the source) you can add functions to __ip in files loaded here. |
|
3739 | 3743 | |
|
3740 | 3744 | # The file example-magic.py contains a simple but correct example. Try it: |
|
3741 | 3745 | |
|
3742 | 3746 | # execfile example-magic.py |
|
3743 | 3747 | |
|
3744 | 3748 | # Look at the examples in IPython/iplib.py for more details on how these magic |
|
3745 | 3749 | # functions need to process their arguments. |
|
3746 | 3750 | |
|
3747 | 3751 | #--------------------------------------------------------------------------- |
|
3748 | 3752 | # Section: aliases for system shell commands |
|
3749 | 3753 | |
|
3750 | 3754 | # Here you can define your own names for system commands. The syntax is |
|
3751 | 3755 | # similar to that of the builtin %alias function: |
|
3752 | 3756 | |
|
3753 | 3757 | # alias alias_name command_string |
|
3754 | 3758 | |
|
3755 | 3759 | # The resulting aliases are auto-generated magic functions (hence usable as |
|
3756 | 3760 | # %alias_name) |
|
3757 | 3761 | |
|
3758 | 3762 | # For example: |
|
3759 | 3763 | |
|
3760 | 3764 | # alias myls ls -la |
|
3761 | 3765 | |
|
3762 | 3766 | # will define 'myls' as an alias for executing the system command 'ls -la'. |
|
3763 | 3767 | # This allows you to customize IPython's environment to have the same aliases |
|
3764 | 3768 | # you are accustomed to from your own shell. |
|
3765 | 3769 | |
|
3766 | 3770 | # You can also define aliases with parameters using %s specifiers (one per |
|
3767 | 3771 | # parameter): |
|
3768 | 3772 | |
|
3769 | 3773 | # alias parts echo first %s second %s |
|
3770 | 3774 | |
|
3771 | 3775 | # will give you in IPython: |
|
3772 | 3776 | # >>> %parts A B |
|
3773 | 3777 | # first A second B |
|
3774 | 3778 | |
|
3775 | 3779 | # Use one 'alias' statement per alias you wish to define. |
|
3776 | 3780 | |
|
3777 | 3781 | # alias |
|
3778 | 3782 | |
|
3779 | 3783 | #************************* end of file <ipythonrc> ************************ |
|
3780 | 3784 | |
|
3781 | 3785 | |
|
3782 | 3786 | |
|
3783 | 3787 | Fine-tuning your prompt |
|
3784 | 3788 | ----------------------- |
|
3785 | 3789 | |
|
3786 | 3790 | IPython's prompts can be customized using a syntax similar to that of |
|
3787 | 3791 | the bash shell. Many of bash's escapes are supported, as well as a few |
|
3788 | 3792 | additional ones. We list them below: |
|
3789 | 3793 | |
|
3790 | 3794 | *\#* |
|
3791 | 3795 | the prompt/history count number. This escape is automatically |
|
3792 | 3796 | wrapped in the coloring codes for the currently active color scheme. |
|
3793 | 3797 | *\N* |
|
3794 | 3798 | the 'naked' prompt/history count number: this is just the number |
|
3795 | 3799 | itself, without any coloring applied to it. This lets you produce |
|
3796 | 3800 | numbered prompts with your own colors. |
|
3797 | 3801 | *\D* |
|
3798 | 3802 | the prompt/history count, with the actual digits replaced by dots. |
|
3799 | 3803 | Used mainly in continuation prompts (prompt_in2) |
|
3800 | 3804 | *\w* |
|
3801 | 3805 | the current working directory |
|
3802 | 3806 | *\W* |
|
3803 | 3807 | the basename of current working directory |
|
3804 | 3808 | *\Xn* |
|
3805 | 3809 | where $n=0\ldots5.$ The current working directory, with $HOME |
|
3806 | 3810 | replaced by ~, and filtered out to contain only $n$ path elements |
|
3807 | 3811 | *\Yn* |
|
3808 | 3812 | Similar to \Xn, but with the $n+1$ element included if it is ~ (this |
|
3809 | 3813 | is similar to the behavior of the %cn escapes in tcsh) |
|
3810 | 3814 | *\u* |
|
3811 | 3815 | the username of the current user |
|
3812 | 3816 | *\$* |
|
3813 | 3817 | if the effective UID is 0, a #, otherwise a $ |
|
3814 | 3818 | *\h* |
|
3815 | 3819 | the hostname up to the first '.' |
|
3816 | 3820 | *\H* |
|
3817 | 3821 | the hostname |
|
3818 | 3822 | *\n* |
|
3819 | 3823 | a newline |
|
3820 | 3824 | *\r* |
|
3821 | 3825 | a carriage return |
|
3822 | 3826 | *\v* |
|
3823 | 3827 | IPython version string |
|
3824 | 3828 | |
|
3825 | 3829 | In addition to these, ANSI color escapes can be insterted into the |
|
3826 | 3830 | prompts, as \C_ColorName. The list of valid color names is: Black, Blue, |
|
3827 | 3831 | Brown, Cyan, DarkGray, Green, LightBlue, LightCyan, LightGray, |
|
3828 | 3832 | LightGreen, LightPurple, LightRed, NoColor, Normal, Purple, Red, White, |
|
3829 | 3833 | Yellow. |
|
3830 | 3834 | |
|
3831 | 3835 | Finally, IPython supports the evaluation of arbitrary expressions in |
|
3832 | 3836 | your prompt string. The prompt strings are evaluated through the syntax |
|
3833 | 3837 | of PEP 215, but basically you can use $x.y to expand the value of x.y, |
|
3834 | 3838 | and for more complicated expressions you can use braces: ${foo()+x} will |
|
3835 | 3839 | call function foo and add to it the value of x, before putting the |
|
3836 | 3840 | result into your prompt. For example, using |
|
3837 | 3841 | prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' |
|
3838 | 3842 | will print the result of the uptime command on each prompt (assuming the |
|
3839 | 3843 | commands module has been imported in your ipythonrc file). |
|
3840 | 3844 | |
|
3841 | 3845 | |
|
3842 | 3846 | Prompt examples |
|
3843 | 3847 | |
|
3844 | 3848 | The following options in an ipythonrc file will give you IPython's |
|
3845 | 3849 | default prompts:: |
|
3846 | 3850 | |
|
3847 | 3851 | prompt_in1 'In [\#]:' |
|
3848 | 3852 | prompt_in2 ' .\D.:' |
|
3849 | 3853 | prompt_out 'Out[\#]:' |
|
3850 | 3854 | |
|
3851 | which look like this: | |
|
3855 | which look like this:: | |
|
3852 | 3856 | |
|
3853 | 3857 | In [1]: 1+2 |
|
3854 | 3858 | Out[1]: 3 |
|
3855 | 3859 | |
|
3856 | 3860 | In [2]: for i in (1,2,3): |
|
3857 | 3861 | ...: print i, |
|
3858 | 3862 | ...: |
|
3859 | 3863 | 1 2 3 |
|
3860 | 3864 | |
|
3861 | 3865 | These will give you a very colorful prompt with path information:: |
|
3862 | 3866 | |
|
3863 | 3867 | #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' |
|
3864 | 3868 | prompt_in2 ' ..\D>' |
|
3865 | 3869 | prompt_out '<\#>' |
|
3866 | 3870 | |
|
3867 | 3871 | which look like this:: |
|
3868 | 3872 | |
|
3869 | 3873 | fperez[~/ipython]1> 1+2 |
|
3870 | 3874 | <1> 3 |
|
3871 | 3875 | fperez[~/ipython]2> for i in (1,2,3): |
|
3872 | 3876 | ...> print i, |
|
3873 | 3877 | ...> |
|
3874 | 3878 | 1 2 3 |
|
3875 | 3879 | |
|
3876 | 3880 | |
|
3877 | 3881 | |
|
3878 | 3882 | IPython profiles |
|
3879 | 3883 | ---------------- |
|
3880 | 3884 | |
|
3881 | 3885 | As we already mentioned, IPython supports the -profile command-line |
|
3882 | 3886 | option (see sec. 5.2 <node5.html#sec:cmd-line-opts>). A profile is |
|
3883 | 3887 | nothing more than a particular configuration file like your basic |
|
3884 | 3888 | ipythonrc one, but with particular customizations for a specific |
|
3885 | 3889 | purpose. When you start IPython with 'ipython -profile <name>', it |
|
3886 | 3890 | assumes that in your IPYTHONDIR there is a file called ipythonrc-<name>, |
|
3887 | 3891 | and loads it instead of the normal ipythonrc. |
|
3888 | 3892 | |
|
3889 | 3893 | This system allows you to maintain multiple configurations which load |
|
3890 | 3894 | modules, set options, define functions, etc. suitable for different |
|
3891 | 3895 | tasks and activate them in a very simple manner. In order to avoid |
|
3892 | 3896 | having to repeat all of your basic options (common things that don't |
|
3893 | 3897 | change such as your color preferences, for example), any profile can |
|
3894 | 3898 | include another configuration file. The most common way to use profiles |
|
3895 | 3899 | is then to have each one include your basic ipythonrc file as a starting |
|
3896 | 3900 | point, and then add further customizations. |
|
3897 | 3901 | |
|
3898 | 3902 | In sections 11 <node11.html#sec:syntax-extensions> and 16 |
|
3899 | 3903 | <node16.html#sec:Gnuplot> we discuss some particular profiles which come |
|
3900 | 3904 | as part of the standard IPython distribution. You may also look in your |
|
3901 | 3905 | IPYTHONDIR directory, any file whose name begins with ipythonrc- is a |
|
3902 | 3906 | profile. You can use those as examples for further customizations to |
|
3903 | 3907 | suit your own needs. |
|
3904 | 3908 | |
|
3905 | 3909 | IPython as your default Python environment |
|
3906 | 3910 | ========================================== |
|
3907 | 3911 | |
|
3908 | 3912 | Python honors the environment variable PYTHONSTARTUP and will execute at |
|
3909 | 3913 | startup the file referenced by this variable. If you put at the end of |
|
3910 | 3914 | this file the following two lines of code:: |
|
3911 | 3915 | |
|
3912 | 3916 | import IPython |
|
3913 | 3917 | IPython.Shell.IPShell().mainloop(sys_exit=1) |
|
3914 | 3918 | |
|
3915 | 3919 | then IPython will be your working environment anytime you start Python. |
|
3916 | 3920 | The sys_exit=1 is needed to have IPython issue a call to sys.exit() when |
|
3917 | 3921 | it finishes, otherwise you'll be back at the normal Python '>>>' |
|
3918 | 3922 | prompt^4 <footnode.html#foot2368>. |
|
3919 | 3923 | |
|
3920 | 3924 | This is probably useful to developers who manage multiple Python |
|
3921 | 3925 | versions and don't want to have correspondingly multiple IPython |
|
3922 | 3926 | versions. Note that in this mode, there is no way to pass IPython any |
|
3923 | 3927 | command-line options, as those are trapped first by Python itself. |
|
3924 | 3928 | |
|
3925 | 3929 | Embedding IPython |
|
3926 | 3930 | ================= |
|
3927 | 3931 | |
|
3928 | 3932 | It is possible to start an IPython instance inside your own Python |
|
3929 | 3933 | programs. This allows you to evaluate dynamically the state of your |
|
3930 | 3934 | code, operate with your variables, analyze them, etc. Note however that |
|
3931 | 3935 | any changes you make to values while in the shell do not propagate back |
|
3932 | 3936 | to the running code, so it is safe to modify your values because you |
|
3933 | 3937 | won't break your code in bizarre ways by doing so. |
|
3934 | 3938 | |
|
3935 | 3939 | This feature allows you to easily have a fully functional python |
|
3936 | 3940 | environment for doing object introspection anywhere in your code with a |
|
3937 | 3941 | simple function call. In some cases a simple print statement is enough, |
|
3938 | 3942 | but if you need to do more detailed analysis of a code fragment this |
|
3939 | 3943 | feature can be very valuable. |
|
3940 | 3944 | |
|
3941 | 3945 | It can also be useful in scientific computing situations where it is |
|
3942 | 3946 | common to need to do some automatic, computationally intensive part and |
|
3943 | 3947 | then stop to look at data, plots, etc^5 <footnode.html#foot3206>. |
|
3944 | 3948 | Opening an IPython instance will give you full access to your data and |
|
3945 | 3949 | functions, and you can resume program execution once you are done with |
|
3946 | 3950 | the interactive part (perhaps to stop again later, as many times as |
|
3947 | 3951 | needed). |
|
3948 | 3952 | |
|
3949 | 3953 | The following code snippet is the bare minimum you need to include in |
|
3950 | 3954 | your Python programs for this to work (detailed examples follow later):: |
|
3951 | 3955 | |
|
3952 | 3956 | from IPython.Shell import IPShellEmbed |
|
3953 | 3957 | |
|
3954 | 3958 | ipshell = IPShellEmbed() |
|
3955 | 3959 | |
|
3956 | 3960 | ipshell() # this call anywhere in your program will start IPython |
|
3957 | 3961 | |
|
3958 | 3962 | You can run embedded instances even in code which is itself being run at |
|
3959 | 3963 | the IPython interactive prompt with '%run <filename>'. Since it's easy |
|
3960 | 3964 | to get lost as to where you are (in your top-level IPython or in your |
|
3961 | 3965 | embedded one), it's a good idea in such cases to set the in/out prompts |
|
3962 | 3966 | to something different for the embedded instances. The code examples |
|
3963 | 3967 | below illustrate this. |
|
3964 | 3968 | |
|
3965 | 3969 | You can also have multiple IPython instances in your program and open |
|
3966 | 3970 | them separately, for example with different options for data |
|
3967 | 3971 | presentation. If you close and open the same instance multiple times, |
|
3968 | 3972 | its prompt counters simply continue from each execution to the next. |
|
3969 | 3973 | |
|
3970 | 3974 | Please look at the docstrings in the Shell.py module for more details on |
|
3971 | 3975 | the use of this system. |
|
3972 | 3976 | |
|
3973 | 3977 | The following sample file illustrating how to use the embedding |
|
3974 | 3978 | functionality is provided in the examples directory as example-embed.py. |
|
3975 | 3979 | It should be fairly self-explanatory:: |
|
3976 | 3980 | |
|
3977 | 3981 | |
|
3978 | 3982 | #!/usr/bin/env python |
|
3979 | 3983 | |
|
3980 | 3984 | """An example of how to embed an IPython shell into a running program. |
|
3981 | 3985 | |
|
3982 | 3986 | Please see the documentation in the IPython.Shell module for more details. |
|
3983 | 3987 | |
|
3984 | 3988 | The accompanying file example-embed-short.py has quick code fragments for |
|
3985 | 3989 | embedding which you can cut and paste in your code once you understand how |
|
3986 | 3990 | things work. |
|
3987 | 3991 | |
|
3988 | 3992 | The code in this file is deliberately extra-verbose, meant for learning.""" |
|
3989 | 3993 | |
|
3990 | 3994 | # The basics to get you going: |
|
3991 | 3995 | |
|
3992 | 3996 | # IPython sets the __IPYTHON__ variable so you can know if you have nested |
|
3993 | 3997 | # copies running. |
|
3994 | 3998 | |
|
3995 | 3999 | # Try running this code both at the command line and from inside IPython (with |
|
3996 | 4000 | # %run example-embed.py) |
|
3997 | 4001 | try: |
|
3998 | 4002 | __IPYTHON__ |
|
3999 | 4003 | except NameError: |
|
4000 | 4004 | nested = 0 |
|
4001 | 4005 | args = [''] |
|
4002 | 4006 | else: |
|
4003 | 4007 | print "Running nested copies of IPython." |
|
4004 | 4008 | print "The prompts for the nested copy have been modified" |
|
4005 | 4009 | nested = 1 |
|
4006 | 4010 | # what the embedded instance will see as sys.argv: |
|
4007 | 4011 | args = ['-pi1','In <\\#>: ','-pi2',' .\\D.: ', |
|
4008 | 4012 | '-po','Out<\\#>: ','-nosep'] |
|
4009 | 4013 | |
|
4010 | 4014 | # First import the embeddable shell class |
|
4011 | 4015 | from IPython.Shell import IPShellEmbed |
|
4012 | 4016 | |
|
4013 | 4017 | # Now create an instance of the embeddable shell. The first argument is a |
|
4014 | 4018 | # string with options exactly as you would type them if you were starting |
|
4015 | 4019 | # IPython at the system command line. Any parameters you want to define for |
|
4016 | 4020 | # configuration can thus be specified here. |
|
4017 | 4021 | ipshell = IPShellEmbed(args, |
|
4018 | 4022 | banner = 'Dropping into IPython', |
|
4019 | 4023 | exit_msg = 'Leaving Interpreter, back to program.') |
|
4020 | 4024 | |
|
4021 | 4025 | # Make a second instance, you can have as many as you want. |
|
4022 | 4026 | if nested: |
|
4023 | 4027 | args[1] = 'In2<\\#>' |
|
4024 | 4028 | else: |
|
4025 | 4029 | args = ['-pi1','In2<\\#>: ','-pi2',' .\\D.: ', |
|
4026 | 4030 | '-po','Out<\\#>: ','-nosep'] |
|
4027 | 4031 | ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.') |
|
4028 | 4032 | |
|
4029 | 4033 | print '\nHello. This is printed from the main controller program.\n' |
|
4030 | 4034 | |
|
4031 | 4035 | # You can then call ipshell() anywhere you need it (with an optional |
|
4032 | 4036 | # message): |
|
4033 | 4037 | ipshell('***Called from top level. ' |
|
4034 | 4038 | 'Hit Ctrl-D to exit interpreter and continue program.\n' |
|
4035 | 4039 | 'Note that if you use %kill_embedded, you can fully deactivate\n' |
|
4036 | 4040 | 'This embedded instance so it will never turn on again') |
|
4037 | 4041 | |
|
4038 | 4042 | print '\nBack in caller program, moving along...\n' |
|
4039 | 4043 | |
|
4040 | 4044 | #--------------------------------------------------------------------------- |
|
4041 | 4045 | # More details: |
|
4042 | 4046 | |
|
4043 | 4047 | # IPShellEmbed instances don't print the standard system banner and |
|
4044 | 4048 | # messages. The IPython banner (which actually may contain initialization |
|
4045 | 4049 | # messages) is available as <instance>.IP.BANNER in case you want it. |
|
4046 | 4050 | |
|
4047 | 4051 | # IPShellEmbed instances print the following information everytime they |
|
4048 | 4052 | # start: |
|
4049 | 4053 | |
|
4050 | 4054 | # - A global startup banner. |
|
4051 | 4055 | |
|
4052 | 4056 | # - A call-specific header string, which you can use to indicate where in the |
|
4053 | 4057 | # execution flow the shell is starting. |
|
4054 | 4058 | |
|
4055 | 4059 | # They also print an exit message every time they exit. |
|
4056 | 4060 | |
|
4057 | 4061 | # Both the startup banner and the exit message default to None, and can be set |
|
4058 | 4062 | # either at the instance constructor or at any other time with the |
|
4059 | 4063 | # set_banner() and set_exit_msg() methods. |
|
4060 | 4064 | |
|
4061 | 4065 | # The shell instance can be also put in 'dummy' mode globally or on a per-call |
|
4062 | 4066 | # basis. This gives you fine control for debugging without having to change |
|
4063 | 4067 | # code all over the place. |
|
4064 | 4068 | |
|
4065 | 4069 | # The code below illustrates all this. |
|
4066 | 4070 | |
|
4067 | 4071 | |
|
4068 | 4072 | # This is how the global banner and exit_msg can be reset at any point |
|
4069 | 4073 | ipshell.set_banner('Entering interpreter - New Banner') |
|
4070 | 4074 | ipshell.set_exit_msg('Leaving interpreter - New exit_msg') |
|
4071 | 4075 | |
|
4072 | 4076 | def foo(m): |
|
4073 | 4077 | s = 'spam' |
|
4074 | 4078 | ipshell('***In foo(). Try @whos, or print s or m:') |
|
4075 | 4079 | print 'foo says m = ',m |
|
4076 | 4080 | |
|
4077 | 4081 | def bar(n): |
|
4078 | 4082 | s = 'eggs' |
|
4079 | 4083 | ipshell('***In bar(). Try @whos, or print s or n:') |
|
4080 | 4084 | print 'bar says n = ',n |
|
4081 | 4085 | |
|
4082 | 4086 | # Some calls to the above functions which will trigger IPython: |
|
4083 | 4087 | print 'Main program calling foo("eggs")\n' |
|
4084 | 4088 | foo('eggs') |
|
4085 | 4089 | |
|
4086 | 4090 | # The shell can be put in 'dummy' mode where calls to it silently return. This |
|
4087 | 4091 | # allows you, for example, to globally turn off debugging for a program with a |
|
4088 | 4092 | # single call. |
|
4089 | 4093 | ipshell.set_dummy_mode(1) |
|
4090 | 4094 | print '\nTrying to call IPython which is now "dummy":' |
|
4091 | 4095 | ipshell() |
|
4092 | 4096 | print 'Nothing happened...' |
|
4093 | 4097 | # The global 'dummy' mode can still be overridden for a single call |
|
4094 | 4098 | print '\nOverriding dummy mode manually:' |
|
4095 | 4099 | ipshell(dummy=0) |
|
4096 | 4100 | |
|
4097 | 4101 | # Reactivate the IPython shell |
|
4098 | 4102 | ipshell.set_dummy_mode(0) |
|
4099 | 4103 | |
|
4100 | 4104 | print 'You can even have multiple embedded instances:' |
|
4101 | 4105 | ipshell2() |
|
4102 | 4106 | |
|
4103 | 4107 | print '\nMain program calling bar("spam")\n' |
|
4104 | 4108 | bar('spam') |
|
4105 | 4109 | |
|
4106 | 4110 | print 'Main program finished. Bye!' |
|
4107 | 4111 | |
|
4108 | 4112 | #********************** End of file <example-embed.py> *********************** |
|
4109 | 4113 | |
|
4110 | 4114 | Once you understand how the system functions, you can use the following |
|
4111 | 4115 | code fragments in your programs which are ready for cut and paste:: |
|
4112 | 4116 | |
|
4113 | 4117 | |
|
4114 | 4118 | """Quick code snippets for embedding IPython into other programs. |
|
4115 | 4119 | |
|
4116 | 4120 | See example-embed.py for full details, this file has the bare minimum code for |
|
4117 | 4121 | cut and paste use once you understand how to use the system.""" |
|
4118 | 4122 | |
|
4119 | 4123 | #--------------------------------------------------------------------------- |
|
4120 | 4124 | # This code loads IPython but modifies a few things if it detects it's running |
|
4121 | 4125 | # embedded in another IPython session (helps avoid confusion) |
|
4122 | 4126 | |
|
4123 | 4127 | try: |
|
4124 | 4128 | __IPYTHON__ |
|
4125 | 4129 | except NameError: |
|
4126 | 4130 | argv = [''] |
|
4127 | 4131 | banner = exit_msg = '' |
|
4128 | 4132 | else: |
|
4129 | 4133 | # Command-line options for IPython (a list like sys.argv) |
|
4130 | 4134 | argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:'] |
|
4131 | 4135 | banner = '*** Nested interpreter ***' |
|
4132 | 4136 | exit_msg = '*** Back in main IPython ***' |
|
4133 | 4137 | |
|
4134 | 4138 | # First import the embeddable shell class |
|
4135 | 4139 | from IPython.Shell import IPShellEmbed |
|
4136 | 4140 | # Now create the IPython shell instance. Put ipshell() anywhere in your code |
|
4137 | 4141 | # where you want it to open. |
|
4138 | 4142 | ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg) |
|
4139 | 4143 | |
|
4140 | 4144 | #--------------------------------------------------------------------------- |
|
4141 | 4145 | # This code will load an embeddable IPython shell always with no changes for |
|
4142 | 4146 | # nested embededings. |
|
4143 | 4147 | |
|
4144 | 4148 | from IPython.Shell import IPShellEmbed |
|
4145 | 4149 | ipshell = IPShellEmbed() |
|
4146 | 4150 | # Now ipshell() will open IPython anywhere in the code. |
|
4147 | 4151 | |
|
4148 | 4152 | #--------------------------------------------------------------------------- |
|
4149 | 4153 | # This code loads an embeddable shell only if NOT running inside |
|
4150 | 4154 | # IPython. Inside IPython, the embeddable shell variable ipshell is just a |
|
4151 | 4155 | # dummy function. |
|
4152 | 4156 | |
|
4153 | 4157 | try: |
|
4154 | 4158 | __IPYTHON__ |
|
4155 | 4159 | except NameError: |
|
4156 | 4160 | from IPython.Shell import IPShellEmbed |
|
4157 | 4161 | ipshell = IPShellEmbed() |
|
4158 | 4162 | # Now ipshell() will open IPython anywhere in the code |
|
4159 | 4163 | else: |
|
4160 | 4164 | # Define a dummy ipshell() so the same code doesn't crash inside an |
|
4161 | 4165 | # interactive IPython |
|
4162 | 4166 | def ipshell(): pass |
|
4163 | 4167 | |
|
4164 | 4168 | #******************* End of file <example-embed-short.py> ******************** |
|
4165 | 4169 | |
|
4166 | 4170 | Using the Python debugger (pdb) |
|
4167 | 4171 | =============================== |
|
4168 | 4172 | |
|
4169 | 4173 | |
|
4170 | 4174 | Running entire programs via pdb |
|
4171 | 4175 | ------------------------------- |
|
4172 | 4176 | |
|
4173 | 4177 | pdb, the Python debugger, is a powerful interactive debugger which |
|
4174 | 4178 | allows you to step through code, set breakpoints, watch variables, etc. |
|
4175 | 4179 | IPython makes it very easy to start any script under the control of pdb, |
|
4176 | 4180 | regardless of whether you have wrapped it into a 'main()' function or |
|
4177 | 4181 | not. For this, simply type '%run -d myscript' at an IPython prompt. See |
|
4178 | 4182 | the %run command's documentation (via '%run?' or in Sec. 6.2 |
|
4179 | 4183 | <node6.html#sec:magic>) for more details, including how to control where |
|
4180 | 4184 | pdb will stop execution first. |
|
4181 | 4185 | |
|
4182 | 4186 | For more information on the use of the pdb debugger, read the included |
|
4183 | 4187 | pdb.doc file (part of the standard Python distribution). On a stock |
|
4184 | 4188 | Linux system it is located at /usr/lib/python2.3/pdb.doc, but the |
|
4185 | 4189 | easiest way to read it is by using the help() function of the pdb module |
|
4186 | 4190 | as follows (in an IPython prompt): |
|
4187 | 4191 | |
|
4188 | 4192 | In [1]: import pdb |
|
4189 | 4193 | In [2]: pdb.help() |
|
4190 | 4194 | |
|
4191 | 4195 | This will load the pdb.doc document in a file viewer for you automatically. |
|
4192 | 4196 | |
|
4193 | 4197 | |
|
4194 | 4198 | Automatic invocation of pdb on exceptions |
|
4195 | 4199 | ----------------------------------------- |
|
4196 | 4200 | |
|
4197 | 4201 | IPython, if started with the -pdb option (or if the option is set in |
|
4198 | 4202 | your rc file) can call the Python pdb debugger every time your code |
|
4199 | 4203 | triggers an uncaught exception^6 <footnode.html#foot2403>. This feature |
|
4200 | 4204 | can also be toggled at any time with the %pdb magic command. This can be |
|
4201 | 4205 | extremely useful in order to find the origin of subtle bugs, because pdb |
|
4202 | 4206 | opens up at the point in your code which triggered the exception, and |
|
4203 | 4207 | while your program is at this point 'dead', all the data is still |
|
4204 | 4208 | available and you can walk up and down the stack frame and understand |
|
4205 | 4209 | the origin of the problem. |
|
4206 | 4210 | |
|
4207 | 4211 | Furthermore, you can use these debugging facilities both with the |
|
4208 | 4212 | embedded IPython mode and without IPython at all. For an embedded shell |
|
4209 | 4213 | (see sec. 9 <node9.html#sec:embed>), simply call the constructor with |
|
4210 | 4214 | '-pdb' in the argument string and automatically pdb will be called if an |
|
4211 | 4215 | uncaught exception is triggered by your code. |
|
4212 | 4216 | |
|
4213 | 4217 | For stand-alone use of the feature in your programs which do not use |
|
4214 | 4218 | IPython at all, put the following lines toward the top of your 'main' |
|
4215 | 4219 | routine: |
|
4216 | 4220 | |
|
4217 | 4221 | import sys,IPython.ultraTB |
|
4218 | 4222 | sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose', |
|
4219 | 4223 | color_scheme='Linux', call_pdb=1) |
|
4220 | 4224 | |
|
4221 | 4225 | The mode keyword can be either 'Verbose' or 'Plain', giving either very |
|
4222 | 4226 | detailed or normal tracebacks respectively. The color_scheme keyword can |
|
4223 | 4227 | be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same |
|
4224 | 4228 | options which can be set in IPython with -colors and -xmode. |
|
4225 | 4229 | |
|
4226 | 4230 | This will give any of your programs detailed, colored tracebacks with |
|
4227 | 4231 | automatic invocation of pdb. |
|
4228 | 4232 | |
|
4229 | 4233 | |
|
4230 | 4234 | Extensions for syntax processing |
|
4231 | 4235 | ================================ |
|
4232 | 4236 | |
|
4233 | 4237 | This isn't for the faint of heart, because the potential for breaking |
|
4234 | 4238 | things is quite high. But it can be a very powerful and useful feature. |
|
4235 | 4239 | In a nutshell, you can redefine the way IPython processes the user input |
|
4236 | 4240 | line to accept new, special extensions to the syntax without needing to |
|
4237 | 4241 | change any of IPython's own code. |
|
4238 | 4242 | |
|
4239 | 4243 | In the IPython/Extensions directory you will find some examples |
|
4240 | 4244 | supplied, which we will briefly describe now. These can be used 'as is' |
|
4241 | 4245 | (and both provide very useful functionality), or you can use them as a |
|
4242 | 4246 | starting point for writing your own extensions. |
|
4243 | 4247 | |
|
4244 | 4248 | |
|
4245 | 4249 | Pasting of code starting with '»> ' or '... ' |
|
4246 | 4250 | ---------------------------------------------- |
|
4247 | 4251 | |
|
4248 | 4252 | In the python tutorial it is common to find code examples which have |
|
4249 | 4253 | been taken from real python sessions. The problem with those is that all |
|
4250 | 4254 | the lines begin with either '>>> ' or '... ', which makes it impossible |
|
4251 | 4255 | to paste them all at once. One must instead do a line by line manual |
|
4252 | 4256 | copying, carefully removing the leading extraneous characters. |
|
4253 | 4257 | |
|
4254 | 4258 | This extension identifies those starting characters and removes them |
|
4255 | 4259 | from the input automatically, so that one can paste multi-line examples |
|
4256 | 4260 | directly into IPython, saving a lot of time. Please look at the file |
|
4257 | 4261 | InterpreterPasteInput.py in the IPython/Extensions directory for details |
|
4258 | 4262 | on how this is done. |
|
4259 | 4263 | |
|
4260 | 4264 | IPython comes with a special profile enabling this feature, called |
|
4261 | 4265 | tutorial. Simply start IPython via 'ipython -p tutorial' and the feature |
|
4262 | 4266 | will be available. In a normal IPython session you can activate the |
|
4263 | 4267 | feature by importing the corresponding module with: |
|
4264 | 4268 | In [1]: import IPython.Extensions.InterpreterPasteInput |
|
4265 | 4269 | |
|
4266 | 4270 | The following is a 'screenshot' of how things work when this extension |
|
4267 | 4271 | is on, copying an example from the standard tutorial:: |
|
4268 | 4272 | |
|
4269 | 4273 | IPython profile: tutorial |
|
4270 | 4274 | |
|
4271 | 4275 | *** Pasting of code with ">>>" or "..." has been enabled. |
|
4272 | 4276 | |
|
4273 | 4277 | In [1]: >>> def fib2(n): # return Fibonacci series up to n |
|
4274 | 4278 | ...: ... """Return a list containing the Fibonacci series up to |
|
4275 | 4279 | n.""" |
|
4276 | 4280 | ...: ... result = [] |
|
4277 | 4281 | ...: ... a, b = 0, 1 |
|
4278 | 4282 | ...: ... while b < n: |
|
4279 | 4283 | ...: ... result.append(b) # see below |
|
4280 | 4284 | ...: ... a, b = b, a+b |
|
4281 | 4285 | ...: ... return result |
|
4282 | 4286 | ...: |
|
4283 | 4287 | |
|
4284 | 4288 | In [2]: fib2(10) |
|
4285 | 4289 | Out[2]: [1, 1, 2, 3, 5, 8] |
|
4286 | 4290 | |
|
4287 | 4291 | Note that as currently written, this extension does not recognize |
|
4288 | 4292 | IPython's prompts for pasting. Those are more complicated, since the |
|
4289 | 4293 | user can change them very easily, they involve numbers and can vary in |
|
4290 | 4294 | length. One could however extract all the relevant information from the |
|
4291 | 4295 | IPython instance and build an appropriate regular expression. This is |
|
4292 | 4296 | left as an exercise for the reader. |
|
4293 | 4297 | |
|
4294 | 4298 | |
|
4295 | 4299 | Input of physical quantities with units |
|
4296 | 4300 | --------------------------------------- |
|
4297 | 4301 | |
|
4298 | 4302 | The module PhysicalQInput allows a simplified form of input for physical |
|
4299 | 4303 | quantities with units. This file is meant to be used in conjunction with |
|
4300 | 4304 | the PhysicalQInteractive module (in the same directory) and |
|
4301 | 4305 | Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython |
|
4302 | 4306 | (http://dirac.cnrs-orleans.fr/ScientificPython/). |
|
4303 | 4307 | |
|
4304 | 4308 | The Physics.PhysicalQuantities module defines PhysicalQuantity objects, |
|
4305 | 4309 | but these must be declared as instances of a class. For example, to |
|
4306 | 4310 | define v as a velocity of 3 m/s, normally you would write:: |
|
4311 | ||
|
4307 | 4312 | In [1]: v = PhysicalQuantity(3,'m/s') |
|
4308 | 4313 | |
|
4309 | 4314 | Using the PhysicalQ_Input extension this can be input instead as: |
|
4310 | 4315 | In [1]: v = 3 m/s |
|
4311 | 4316 | which is much more convenient for interactive use (even though it is |
|
4312 | 4317 | blatantly invalid Python syntax). |
|
4313 | 4318 | |
|
4314 | 4319 | The physics profile supplied with IPython (enabled via 'ipython -p |
|
4315 | 4320 | physics') uses these extensions, which you can also activate with: |
|
4316 | 4321 | |
|
4317 | 4322 | from math import * # math MUST be imported BEFORE PhysicalQInteractive |
|
4318 | 4323 | from IPython.Extensions.PhysicalQInteractive import * |
|
4319 | 4324 | import IPython.Extensions.PhysicalQInput |
|
4320 | 4325 | |
|
4321 | 4326 | IPython as a system shell |
|
4322 | 4327 | ========================= |
|
4323 | 4328 | |
|
4324 | 4329 | IPython ships with a special profile called pysh, which you can activate |
|
4325 | 4330 | at the command line as 'ipython -p pysh'. This loads InterpreterExec, |
|
4326 | 4331 | along with some additional facilities and a prompt customized for |
|
4327 | 4332 | filesystem navigation. |
|
4328 | 4333 | |
|
4329 | 4334 | Note that this does not make IPython a full-fledged system shell. In |
|
4330 | 4335 | particular, it has no job control, so if you type Ctrl-Z (under Unix), |
|
4331 | 4336 | you'll suspend pysh itself, not the process you just started. |
|
4332 | 4337 | |
|
4333 | 4338 | What the shell profile allows you to do is to use the convenient and |
|
4334 | 4339 | powerful syntax of Python to do quick scripting at the command line. |
|
4335 | 4340 | Below we describe some of its features. |
|
4336 | 4341 | |
|
4337 | 4342 | |
|
4338 | 4343 | Aliases |
|
4339 | 4344 | ------- |
|
4340 | 4345 | |
|
4341 | 4346 | All of your $PATH has been loaded as IPython aliases, so you should be |
|
4342 | 4347 | able to type any normal system command and have it executed. See %alias? |
|
4343 | 4348 | and %unalias? for details on the alias facilities. See also %rehash? and |
|
4344 | 4349 | %rehashx? for details on the mechanism used to load $PATH. |
|
4345 | 4350 | |
|
4346 | 4351 | |
|
4347 | 4352 | Special syntax |
|
4348 | 4353 | -------------- |
|
4349 | 4354 | |
|
4350 | 4355 | Any lines which begin with '~', '/' and '.' will be executed as shell |
|
4351 | 4356 | commands instead of as Python code. The special escapes below are also |
|
4352 | 4357 | recognized. !cmd is valid in single or multi-line input, all others are |
|
4353 | 4358 | only valid in single-line input:: |
|
4354 | 4359 | |
|
4355 |
|
|
|
4356 | pass 'cmd' directly to the shell | |
|
4357 |
|
|
|
4358 | execute 'cmd' and return output as a list (split on '\n') | |
|
4359 |
|
|
|
4360 | capture output of cmd into var, as a string list | |
|
4361 | ||
|
4362 | The $/$$ syntaxes make Python variables from system output, which you | |
|
4363 | can later use for further scripting. The converse is also possible: when | |
|
4364 | executing an alias or calling to the system via !/!!, you can expand any | |
|
4365 | python variable or expression by prepending it with $. Full details of | |
|
4366 | the allowed syntax can be found in Python's PEP 215. | |
|
4360 | !cmd | |
|
4361 | pass 'cmd' directly to the shell | |
|
4362 | !!cmd* | |
|
4363 | execute 'cmd' and return output as a list (split on '\n') | |
|
4364 | var=!cmd | |
|
4365 | capture output of cmd into var, as a string list | |
|
4367 | 4366 | |
|
4368 | 4367 | A few brief examples will illustrate these (note that the indentation |
|
4369 | 4368 | below may be incorrectly displayed):: |
|
4370 | 4369 | |
|
4371 | 4370 | fperez[~/test]|3> !ls *s.py |
|
4372 | 4371 | scopes.py strings.py |
|
4373 | 4372 | |
|
4374 | 4373 | ls is an internal alias, so there's no need to use !:: |
|
4375 | 4374 | |
|
4376 | 4375 | fperez[~/test]|4> ls *s.py |
|
4377 | 4376 | scopes.py* strings.py |
|
4378 | 4377 | |
|
4379 | 4378 | !!ls will return the output into a Python variable FIXME!!!:: |
|
4380 | 4379 | |
|
4381 | 4380 | fperez[~/test]|5> !!ls *s.py |
|
4382 | 4381 | <5> ['scopes.py', 'strings.py'] |
|
4383 | 4382 | fperez[~/test]|6> print _5 |
|
4384 | 4383 | ['scopes.py', 'strings.py'] |
|
4385 | 4384 | |
|
4386 | 4385 | $ and $$ allow direct capture to named variables: |
|
4387 | 4386 | |
|
4388 | 4387 | fperez[~/test]|7> $astr = ls *s.py |
|
4389 | 4388 | fperez[~/test]|8> astr |
|
4390 | 4389 | <8> 'scopes.py\nstrings.py' |
|
4391 | 4390 | |
|
4392 | 4391 | fperez[~/test]|9> $$alist = ls *s.py |
|
4393 | 4392 | fperez[~/test]|10> alist |
|
4394 | 4393 | <10> ['scopes.py', 'strings.py'] |
|
4395 | 4394 | |
|
4396 | 4395 | alist is now a normal python list you can loop over. Using $ will expand |
|
4397 | 4396 | back the python values when alias calls are made: |
|
4398 | 4397 | |
|
4399 | 4398 | fperez[~/test]|11> for f in alist: |
|
4400 | 4399 | |..> print 'file',f, |
|
4401 | 4400 | |..> wc -l $f |
|
4402 | 4401 | |..> |
|
4403 | 4402 | file scopes.py 13 scopes.py |
|
4404 | 4403 | file strings.py 4 strings.py |
|
4405 | 4404 | |
|
4406 | 4405 | Note that you may need to protect your variables with braces if you want |
|
4407 | 4406 | to append strings to their names. To copy all files in alist to .bak |
|
4408 | 4407 | extensions, you must use:: |
|
4409 | 4408 | |
|
4410 | 4409 | fperez[~/test]|12> for f in alist: |
|
4411 | 4410 | |..> cp $f ${f}.bak |
|
4412 | 4411 | |
|
4413 | 4412 | If you try using $f.bak, you'll get an AttributeError exception saying |
|
4414 | 4413 | that your string object doesn't have a .bak attribute. This is because |
|
4415 | 4414 | the $ expansion mechanism allows you to expand full Python expressions:: |
|
4416 | 4415 | |
|
4417 | 4416 | fperez[~/test]|13> echo "sys.platform is: $sys.platform" |
|
4418 | 4417 | sys.platform is: linux2 |
|
4419 | 4418 | |
|
4420 | 4419 | IPython's input history handling is still active, which allows you to |
|
4421 | 4420 | rerun a single block of multi-line input by simply using exec:: |
|
4422 | 4421 | |
|
4423 | 4422 | fperez[~/test]|14> $$alist = ls *.eps |
|
4424 | 4423 | fperez[~/test]|15> exec _i11 |
|
4425 | 4424 | file image2.eps 921 image2.eps |
|
4426 | 4425 | file image.eps 921 image.eps |
|
4427 | 4426 | |
|
4428 | 4427 | While these are new special-case syntaxes, they are designed to allow |
|
4429 | 4428 | very efficient use of the shell with minimal typing. At an interactive |
|
4430 | 4429 | shell prompt, conciseness of expression wins over readability. |
|
4431 | 4430 | |
|
4432 | 4431 | |
|
4433 | 4432 | Useful functions and modules |
|
4434 | 4433 | ---------------------------- |
|
4435 | 4434 | |
|
4436 | 4435 | The os, sys and shutil modules from the Python standard library are |
|
4437 | 4436 | automatically loaded. Some additional functions, useful for shell usage, |
|
4438 | 4437 | are listed below. You can request more help about them with '?'. |
|
4439 | 4438 | |
|
4440 | 4439 | *shell* |
|
4441 | 4440 | - execute a command in the underlying system shell |
|
4442 | 4441 | *system* |
|
4443 | 4442 | - like shell(), but return the exit status of the command |
|
4444 | 4443 | *sout* |
|
4445 | 4444 | - capture the output of a command as a string |
|
4446 | 4445 | *lout* |
|
4447 | 4446 | - capture the output of a command as a list (split on '\n') |
|
4448 | 4447 | *getoutputerror* |
|
4449 | 4448 | - capture (output,error) of a shell commandss |
|
4450 | 4449 | |
|
4451 | 4450 | sout/lout are the functional equivalents of $/$$. They are provided to |
|
4452 | 4451 | allow you to capture system output in the middle of true python code, |
|
4453 | 4452 | function definitions, etc (where $ and $$ are invalid). |
|
4454 | 4453 | |
|
4455 | 4454 | |
|
4456 | 4455 | Directory management |
|
4457 | 4456 | -------------------- |
|
4458 | 4457 | |
|
4459 | 4458 | Since each command passed by pysh to the underlying system is executed |
|
4460 | 4459 | in a subshell which exits immediately, you can NOT use !cd to navigate |
|
4461 | 4460 | the filesystem. |
|
4462 | 4461 | |
|
4463 | 4462 | Pysh provides its own builtin '%cd' magic command to move in the |
|
4464 | 4463 | filesystem (the % is not required with automagic on). It also maintains |
|
4465 | 4464 | a list of visited directories (use %dhist to see it) and allows direct |
|
4466 | 4465 | switching to any of them. Type 'cd?' for more details. |
|
4467 | 4466 | |
|
4468 | 4467 | %pushd, %popd and %dirs are provided for directory stack handling. |
|
4469 | 4468 | |
|
4470 | 4469 | |
|
4471 |
|
|
|
4470 | Prompt customization | |
|
4471 | -------------------- | |
|
4472 | 4472 | |
|
4473 |
The supplied ipy |
|
|
4473 | The supplied ipy_profile_sh.py profile comes with an example of a very | |
|
4474 | 4474 | colored and detailed prompt, mainly to serve as an illustration. The |
|
4475 | 4475 | valid escape sequences, besides color names, are: |
|
4476 | 4476 | |
|
4477 | 4477 | *\#* |
|
4478 | 4478 | - Prompt number, wrapped in the color escapes for the input prompt |
|
4479 | (determined by the current color scheme). | |
|
4479 | (determined by the current color scheme). | |
|
4480 | 4480 | *\N* |
|
4481 | 4481 | - Just the prompt counter number, without any coloring wrappers. You |
|
4482 | can thus customize the actual prompt colors manually. | |
|
4482 | can thus customize the actual prompt colors manually. | |
|
4483 | 4483 | *\D* |
|
4484 | 4484 | - Dots, as many as there are digits in \# (so they align). |
|
4485 | 4485 | *\w* |
|
4486 | 4486 | - Current working directory (cwd). |
|
4487 | 4487 | *\W* |
|
4488 | 4488 | - Basename of current working directory. |
|
4489 | 4489 | *\XN* |
|
4490 | 4490 | - Where N=0..5. N terms of the cwd, with $HOME written as ~. |
|
4491 | 4491 | *\YN* |
|
4492 | 4492 | - Where N=0..5. Like XN, but if ~ is term N+1 it's also shown. |
|
4493 | 4493 | *\u* |
|
4494 | 4494 | - Username. |
|
4495 | 4495 | *\H* |
|
4496 | 4496 | - Full hostname. |
|
4497 | 4497 | *\h* |
|
4498 | 4498 | - Hostname up to first '.' |
|
4499 | 4499 | *\$* |
|
4500 | 4500 | - Root symbol ($ or #). |
|
4501 | 4501 | *\t* |
|
4502 | 4502 | - Current time, in H:M:S format. |
|
4503 | 4503 | *\v* |
|
4504 | 4504 | - IPython release version. |
|
4505 | 4505 | *\n* |
|
4506 | 4506 | - Newline. |
|
4507 | 4507 | *\r* |
|
4508 | 4508 | - Carriage return. |
|
4509 | 4509 | *\\* |
|
4510 | 4510 | - An explicitly escaped '\'. |
|
4511 | 4511 | |
|
4512 | 4512 | You can configure your prompt colors using any ANSI color escape. Each |
|
4513 | 4513 | color escape sets the color for any subsequent text, until another |
|
4514 | 4514 | escape comes in and changes things. The valid color escapes are: |
|
4515 | 4515 | |
|
4516 | 4516 | *\C_Black* |
|
4517 | 4517 | |
|
4518 | 4518 | *\C_Blue* |
|
4519 | 4519 | |
|
4520 | 4520 | *\C_Brown* |
|
4521 | 4521 | |
|
4522 | 4522 | *\C_Cyan* |
|
4523 | 4523 | |
|
4524 | 4524 | *\C_DarkGray* |
|
4525 | 4525 | |
|
4526 | 4526 | *\C_Green* |
|
4527 | 4527 | |
|
4528 | 4528 | *\C_LightBlue* |
|
4529 | 4529 | |
|
4530 | 4530 | *\C_LightCyan* |
|
4531 | 4531 | |
|
4532 | 4532 | *\C_LightGray* |
|
4533 | 4533 | |
|
4534 | 4534 | *\C_LightGreen* |
|
4535 | 4535 | |
|
4536 | 4536 | *\C_LightPurple* |
|
4537 | 4537 | |
|
4538 | 4538 | *\C_LightRed* |
|
4539 | 4539 | |
|
4540 | 4540 | *\C_Purple* |
|
4541 | 4541 | |
|
4542 | 4542 | *\C_Red* |
|
4543 | 4543 | |
|
4544 | 4544 | *\C_White* |
|
4545 | 4545 | |
|
4546 | 4546 | *\C_Yellow* |
|
4547 | 4547 | |
|
4548 | 4548 | *\C_Normal* |
|
4549 | 4549 | Stop coloring, defaults to your terminal settings. |
|
4550 | 4550 | |
|
4551 | 4551 | Threading support |
|
4552 | 4552 | ================= |
|
4553 | 4553 | |
|
4554 | 4554 | WARNING: The threading support is still somewhat experimental, and it |
|
4555 | 4555 | has only seen reasonable testing under Linux. Threaded code is |
|
4556 | 4556 | particularly tricky to debug, and it tends to show extremely |
|
4557 | 4557 | platform-dependent behavior. Since I only have access to Linux machines, |
|
4558 | 4558 | I will have to rely on user's experiences and assistance for this area |
|
4559 | 4559 | of IPython to improve under other platforms. |
|
4560 | 4560 | |
|
4561 | 4561 | IPython, via the -gthread , -qthread, -q4thread and -wthread options |
|
4562 | 4562 | (described in Sec. 5.1 <node5.html#sec:threading-opts>), can run in |
|
4563 | 4563 | multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications |
|
4564 | 4564 | respectively. These GUI toolkits need to control the python main loop of |
|
4565 | 4565 | execution, so under a normal Python interpreter, starting a pyGTK, Qt3, |
|
4566 | 4566 | Qt4 or WXPython application will immediately freeze the shell. |
|
4567 | 4567 | |
|
4568 | 4568 | IPython, with one of these options (you can only use one at a time), |
|
4569 | 4569 | separates the graphical loop and IPython's code execution run into |
|
4570 | 4570 | different threads. This allows you to test interactively (with %run, for |
|
4571 | 4571 | example) your GUI code without blocking. |
|
4572 | 4572 | |
|
4573 | 4573 | A nice mini-tutorial on using IPython along with the Qt Designer |
|
4574 | 4574 | application is available at the SciPy wiki: |
|
4575 | 4575 | http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer. |
|
4576 | 4576 | |
|
4577 | 4577 | |
|
4578 | 4578 | Tk issues |
|
4579 | 4579 | --------- |
|
4580 | 4580 | |
|
4581 | 4581 | As indicated in Sec. 5.1 <node5.html#sec:threading-opts>, a special -tk |
|
4582 | 4582 | option is provided to try and allow Tk graphical applications to coexist |
|
4583 | 4583 | interactively with WX, Qt or GTK ones. Whether this works at all, |
|
4584 | 4584 | however, is very platform and configuration dependent. Please experiment |
|
4585 | 4585 | with simple test cases before committing to using this combination of Tk |
|
4586 | 4586 | and GTK/Qt/WX threading in a production environment. |
|
4587 | 4587 | |
|
4588 | 4588 | |
|
4589 | 4589 | I/O pitfalls |
|
4590 | 4590 | ------------ |
|
4591 | 4591 | |
|
4592 | 4592 | Be mindful that the Python interpreter switches between threads every |
|
4593 | 4593 | $N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This |
|
4594 | 4594 | value can be read by using the sys.getcheckinterval() function, and it |
|
4595 | 4595 | can be reset via sys.setcheckinterval(N). This switching of threads can |
|
4596 | 4596 | cause subtly confusing effects if one of your threads is doing file I/O. |
|
4597 | 4597 | In text mode, most systems only flush file buffers when they encounter a |
|
4598 | '\n'. An instruction as simple as | |
|
4598 | '\n'. An instruction as simple as:: | |
|
4599 | ||
|
4599 | 4600 | print >> filehandle, ''hello world'' |
|
4601 | ||
|
4600 | 4602 | actually consists of several bytecodes, so it is possible that the |
|
4601 | 4603 | newline does not reach your file before the next thread switch. |
|
4602 | 4604 | Similarly, if you are writing to a file in binary mode, the file won't |
|
4603 | 4605 | be flushed until the buffer fills, and your other thread may see |
|
4604 | 4606 | apparently truncated files. |
|
4605 | 4607 | |
|
4606 | 4608 | For this reason, if you are using IPython's thread support and have (for |
|
4607 | 4609 | example) a GUI application which will read data generated by files |
|
4608 | 4610 | written to from the IPython thread, the safest approach is to open all |
|
4609 | 4611 | of your files in unbuffered mode (the third argument to the file/open |
|
4610 | 4612 | function is the buffering value):: |
|
4613 | ||
|
4611 | 4614 | filehandle = open(filename,mode,0) |
|
4612 | 4615 | |
|
4613 | 4616 | This is obviously a brute force way of avoiding race conditions with the |
|
4614 | 4617 | file buffering. If you want to do it cleanly, and you have a resource |
|
4615 | 4618 | which is being shared by the interactive IPython loop and your GUI |
|
4616 | 4619 | thread, you should really handle it with thread locking and |
|
4617 | 4620 | syncrhonization properties. The Python documentation discusses these. |
|
4618 | 4621 | |
|
4619 | 4622 | Interactive demos with IPython |
|
4620 | 4623 | ============================== |
|
4621 | 4624 | |
|
4622 | 4625 | IPython ships with a basic system for running scripts interactively in |
|
4623 | 4626 | sections, useful when presenting code to audiences. A few tags embedded |
|
4624 | 4627 | in comments (so that the script remains valid Python code) divide a file |
|
4625 | 4628 | into separate blocks, and the demo can be run one block at a time, with |
|
4626 | 4629 | IPython printing (with syntax highlighting) the block before executing |
|
4627 | 4630 | it, and returning to the interactive prompt after each block. The |
|
4628 | 4631 | interactive namespace is updated after each block is run with the |
|
4629 | 4632 | contents of the demo's namespace. |
|
4630 | 4633 | |
|
4631 | 4634 | This allows you to show a piece of code, run it and then execute |
|
4632 | 4635 | interactively commands based on the variables just created. Once you |
|
4633 | 4636 | want to continue, you simply execute the next block of the demo. The |
|
4634 | 4637 | following listing shows the markup necessary for dividing a script into |
|
4635 | 4638 | sections for execution as a demo:: |
|
4636 | 4639 | |
|
4637 | 4640 | |
|
4638 | 4641 | """A simple interactive demo to illustrate the use of IPython's Demo class. |
|
4639 | 4642 | |
|
4640 | 4643 | Any python script can be run as a demo, but that does little more than showing |
|
4641 | 4644 | it on-screen, syntax-highlighted in one shot. If you add a little simple |
|
4642 | 4645 | markup, you can stop at specified intervals and return to the ipython prompt, |
|
4643 | 4646 | resuming execution later. |
|
4644 | 4647 | """ |
|
4645 | 4648 | |
|
4646 | 4649 | print 'Hello, welcome to an interactive IPython demo.' |
|
4647 | 4650 | print 'Executing this block should require confirmation before proceeding,' |
|
4648 | 4651 | print 'unless auto_all has been set to true in the demo object' |
|
4649 | 4652 | |
|
4650 | 4653 | # The mark below defines a block boundary, which is a point where IPython will |
|
4651 | 4654 | # stop execution and return to the interactive prompt. |
|
4652 | 4655 | # Note that in actual interactive execution, |
|
4653 | 4656 | # <demo> --- stop --- |
|
4654 | 4657 | |
|
4655 | 4658 | x = 1 |
|
4656 | 4659 | y = 2 |
|
4657 | 4660 | |
|
4658 | 4661 | # <demo> --- stop --- |
|
4659 | 4662 | |
|
4660 | 4663 | # the mark below makes this block as silent |
|
4661 | 4664 | # <demo> silent |
|
4662 | 4665 | |
|
4663 | 4666 | print 'This is a silent block, which gets executed but not printed.' |
|
4664 | 4667 | |
|
4665 | 4668 | # <demo> --- stop --- |
|
4666 | 4669 | # <demo> auto |
|
4667 | 4670 | print 'This is an automatic block.' |
|
4668 | 4671 | print 'It is executed without asking for confirmation, but printed.' |
|
4669 | 4672 | z = x+y |
|
4670 | 4673 | |
|
4671 | 4674 | print 'z=',x |
|
4672 | 4675 | |
|
4673 | 4676 | # <demo> --- stop --- |
|
4674 | 4677 | # This is just another normal block. |
|
4675 | 4678 | print 'z is now:', z |
|
4676 | 4679 | |
|
4677 | 4680 | print 'bye!' |
|
4678 | 4681 | |
|
4679 | 4682 | In order to run a file as a demo, you must first make a Demo object out |
|
4680 | 4683 | of it. If the file is named myscript.py, the following code will make a |
|
4681 | 4684 | demo:: |
|
4682 | 4685 | |
|
4683 | 4686 | from IPython.demo import Demo |
|
4684 | 4687 | |
|
4685 | 4688 | mydemo = Demo('myscript.py') |
|
4686 | 4689 | |
|
4687 | 4690 | This creates the mydemo object, whose blocks you run one at a time by |
|
4688 | 4691 | simply calling the object with no arguments. If you have autocall active |
|
4689 | 4692 | in IPython (the default), all you need to do is type:: |
|
4690 | 4693 | |
|
4691 | 4694 | mydemo |
|
4692 | 4695 | |
|
4693 | 4696 | and IPython will call it, executing each block. Demo objects can be |
|
4694 | 4697 | restarted, you can move forward or back skipping blocks, re-execute the |
|
4695 | 4698 | last block, etc. Simply use the Tab key on a demo object to see its |
|
4696 | 4699 | methods, and call '?' on them to see their docstrings for more usage |
|
4697 | 4700 | details. In addition, the demo module itself contains a comprehensive |
|
4698 | 4701 | docstring, which you can access via:: |
|
4699 | 4702 | |
|
4700 | 4703 | from IPython import demo |
|
4701 | 4704 | |
|
4702 | 4705 | demo? |
|
4703 | 4706 | |
|
4704 | 4707 | Limitations: It is important to note that these demos are limited to |
|
4705 | 4708 | fairly simple uses. In particular, you can not put division marks in |
|
4706 | 4709 | indented code (loops, if statements, function definitions, etc.) |
|
4707 | 4710 | Supporting something like this would basically require tracking the |
|
4708 | 4711 | internal execution state of the Python interpreter, so only top-level |
|
4709 | 4712 | divisions are allowed. If you want to be able to open an IPython |
|
4710 | 4713 | instance at an arbitrary point in a program, you can use IPython's |
|
4711 | 4714 | embedding facilities, described in detail in Sec. 9 |
|
4712 | 4715 | |
|
4713 | 4716 | |
|
4714 | 4717 | Plotting with matplotlib |
|
4715 | 4718 | ======================== |
|
4716 | 4719 | |
|
4717 | 4720 | The matplotlib library (http://matplotlib.sourceforge.net |
|
4718 | 4721 | http://matplotlib.sourceforge.net) provides high quality 2D plotting for |
|
4719 | 4722 | Python. Matplotlib can produce plots on screen using a variety of GUI |
|
4720 | 4723 | toolkits, including Tk, GTK and WXPython. It also provides a number of |
|
4721 | 4724 | commands useful for scientific computing, all with a syntax compatible |
|
4722 | 4725 | with that of the popular Matlab program. |
|
4723 | 4726 | |
|
4724 | 4727 | IPython accepts the special option -pylab (Sec. 5.2 |
|
4725 | 4728 | <node5.html#sec:cmd-line-opts>). This configures it to support |
|
4726 | 4729 | matplotlib, honoring the settings in the .matplotlibrc file. IPython |
|
4727 | 4730 | will detect the user's choice of matplotlib GUI backend, and |
|
4728 | 4731 | automatically select the proper threading model to prevent blocking. It |
|
4729 | 4732 | also sets matplotlib in interactive mode and modifies %run slightly, so |
|
4730 | 4733 | that any matplotlib-based script can be executed using %run and the |
|
4731 | 4734 | final show() command does not block the interactive shell. |
|
4732 | 4735 | |
|
4733 | 4736 | The -pylab option must be given first in order for IPython to configure |
|
4734 | 4737 | its threading mode. However, you can still issue other options |
|
4735 | 4738 | afterwards. This allows you to have a matplotlib-based environment |
|
4736 | 4739 | customized with additional modules using the standard IPython profile |
|
4737 | 4740 | mechanism (Sec. 7.3 <node7.html#sec:profiles>): ''ipython -pylab -p |
|
4738 | 4741 | myprofile'' will load the profile defined in ipythonrc-myprofile after |
|
4739 | 4742 | configuring matplotlib. |
|
4740 | 4743 | |
|
4741 | 4744 | Reporting bugs |
|
4742 | 4745 | ============== |
|
4743 | 4746 | |
|
4744 | 4747 | Automatic crash reports |
|
4745 | 4748 | ----------------------- |
|
4746 | 4749 | |
|
4747 | 4750 | Ideally, IPython itself shouldn't crash. It will catch exceptions |
|
4748 | 4751 | produced by you, but bugs in its internals will still crash it. |
|
4749 | 4752 | |
|
4750 | 4753 | In such a situation, IPython will leave a file named |
|
4751 | 4754 | IPython_crash_report.txt in your IPYTHONDIR directory (that way if |
|
4752 | 4755 | crashes happen several times it won't litter many directories, the |
|
4753 | 4756 | post-mortem file is always located in the same place and new occurrences |
|
4754 | 4757 | just overwrite the previous one). If you can mail this file to the |
|
4755 | 4758 | developers (see sec. 20 <node20.html#sec:credits> for names and |
|
4756 | 4759 | addresses), it will help us a lot in understanding the cause of the |
|
4757 | 4760 | problem and fixing it sooner. |
|
4758 | 4761 | |
|
4759 | 4762 | |
|
4760 | 4763 | The bug tracker |
|
4761 | 4764 | --------------- |
|
4762 | 4765 | |
|
4763 | 4766 | IPython also has an online bug-tracker, located at |
|
4764 | 4767 | http://projects.scipy.org/ipython/ipython/report/1. In addition to |
|
4765 | 4768 | mailing the developers, it would be a good idea to file a bug report |
|
4766 | 4769 | here. This will ensure that the issue is properly followed to |
|
4767 | 4770 | conclusion. To report new bugs you will have to register first. |
|
4768 | 4771 | |
|
4769 | 4772 | You can also use this bug tracker to file feature requests. |
|
4770 | 4773 | |
|
4771 | 4774 | Brief history |
|
4772 | 4775 | ============= |
|
4773 | 4776 | |
|
4774 | 4777 | |
|
4775 | 4778 | Origins |
|
4776 | 4779 | |
|
4777 | 4780 | The current IPython system grew out of the following three projects: |
|
4778 | 4781 | |
|
4779 | 4782 | * [ipython] by Fernando Pérez. I was working on adding |
|
4780 | 4783 | Mathematica-type prompts and a flexible configuration system |
|
4781 | 4784 | (something better than $PYTHONSTARTUP) to the standard Python |
|
4782 | 4785 | interactive interpreter. |
|
4783 | 4786 | * [IPP] by Janko Hauser. Very well organized, great usability. Had |
|
4784 | 4787 | an old help system. IPP was used as the 'container' code into |
|
4785 | 4788 | which I added the functionality from ipython and LazyPython. |
|
4786 | 4789 | * [LazyPython] by Nathan Gray. Simple but very powerful. The quick |
|
4787 | 4790 | syntax (auto parens, auto quotes) and verbose/colored tracebacks |
|
4788 | 4791 | were all taken from here. |
|
4789 | 4792 | |
|
4790 | 4793 | When I found out (see sec. 20 <node20.html#figgins>) about IPP and |
|
4791 | 4794 | LazyPython I tried to join all three into a unified system. I thought |
|
4792 | 4795 | this could provide a very nice working environment, both for regular |
|
4793 | 4796 | programming and scientific computing: shell-like features, IDL/Matlab |
|
4794 | 4797 | numerics, Mathematica-type prompt history and great object introspection |
|
4795 | 4798 | and help facilities. I think it worked reasonably well, though it was a |
|
4796 | 4799 | lot more work than I had initially planned. |
|
4797 | 4800 | |
|
4798 | 4801 | |
|
4799 | 4802 | Current status |
|
4800 | 4803 | -------------- |
|
4801 | 4804 | |
|
4802 | 4805 | The above listed features work, and quite well for the most part. But |
|
4803 | 4806 | until a major internal restructuring is done (see below), only bug |
|
4804 | 4807 | fixing will be done, no other features will be added (unless very minor |
|
4805 | 4808 | and well localized in the cleaner parts of the code). |
|
4806 | 4809 | |
|
4807 | 4810 | IPython consists of some 18000 lines of pure python code, of which |
|
4808 | 4811 | roughly two thirds is reasonably clean. The rest is, messy code which |
|
4809 | 4812 | needs a massive restructuring before any further major work is done. |
|
4810 | 4813 | Even the messy code is fairly well documented though, and most of the |
|
4811 | 4814 | problems in the (non-existent) class design are well pointed to by a |
|
4812 | 4815 | PyChecker run. So the rewriting work isn't that bad, it will just be |
|
4813 | 4816 | time-consuming. |
|
4814 | 4817 | |
|
4815 | 4818 | |
|
4816 | 4819 | Future |
|
4817 | 4820 | ------ |
|
4818 | 4821 | |
|
4819 | 4822 | See the separate new_design document for details. Ultimately, I would |
|
4820 | 4823 | like to see IPython become part of the standard Python distribution as a |
|
4821 | 4824 | 'big brother with batteries' to the standard Python interactive |
|
4822 | 4825 | interpreter. But that will never happen with the current state of the |
|
4823 | 4826 | code, so all contributions are welcome. |
|
4824 | 4827 | |
|
4825 | 4828 | License |
|
4826 | 4829 | ======= |
|
4827 | 4830 | |
|
4828 | 4831 | IPython is released under the terms of the BSD license, whose general |
|
4829 | 4832 | form can be found at: |
|
4830 | 4833 | http://www.opensource.org/licenses/bsd-license.php. The full text of the |
|
4831 | 4834 | IPython license is reproduced below:: |
|
4832 | 4835 | |
|
4833 | 4836 | IPython is released under a BSD-type license. |
|
4834 | 4837 | |
|
4835 | 4838 | Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez |
|
4836 | 4839 | <fperez@colorado.edu>. |
|
4837 | 4840 | |
|
4838 | 4841 | Copyright (c) 2001 Janko Hauser <jhauser@zscout.de> and |
|
4839 | 4842 | Nathaniel Gray <n8gray@caltech.edu>. |
|
4840 | 4843 | |
|
4841 | 4844 | All rights reserved. |
|
4842 | 4845 | |
|
4843 | 4846 | Redistribution and use in source and binary forms, with or without |
|
4844 | 4847 | modification, are permitted provided that the following conditions |
|
4845 | 4848 | are met: |
|
4846 | 4849 | |
|
4847 | 4850 | a. Redistributions of source code must retain the above copyright |
|
4848 | 4851 | notice, this list of conditions and the following disclaimer. |
|
4849 | 4852 | |
|
4850 | 4853 | b. Redistributions in binary form must reproduce the above copyright |
|
4851 | 4854 | notice, this list of conditions and the following disclaimer in the |
|
4852 | 4855 | documentation and/or other materials provided with the distribution. |
|
4853 | 4856 | |
|
4854 | 4857 | c. Neither the name of the copyright holders nor the names of any |
|
4855 | 4858 | contributors to this software may be used to endorse or promote |
|
4856 | 4859 | products derived from this software without specific prior written |
|
4857 | 4860 | permission. |
|
4858 | 4861 | |
|
4859 | 4862 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
4860 | 4863 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
4861 | 4864 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS |
|
4862 | 4865 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE |
|
4863 | 4866 | REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, |
|
4864 | 4867 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
|
4865 | 4868 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
|
4866 | 4869 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER |
|
4867 | 4870 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
|
4868 | 4871 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN |
|
4869 | 4872 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
|
4870 | 4873 | POSSIBILITY OF SUCH DAMAGE. |
|
4871 | 4874 | |
|
4872 | 4875 | Individual authors are the holders of the copyright for their code and |
|
4873 | 4876 | are listed in each file. |
|
4874 | 4877 | |
|
4875 | 4878 | Some files (DPyGetOpt.py, for example) may be licensed under different |
|
4876 | 4879 | conditions. Ultimately each file indicates clearly the conditions under |
|
4877 | 4880 | which its author/authors have decided to publish the code. |
|
4878 | 4881 | |
|
4879 | 4882 | Versions of IPython up to and including 0.6.3 were released under the |
|
4880 | 4883 | GNU Lesser General Public License (LGPL), available at |
|
4881 | 4884 | http://www.gnu.org/copyleft/lesser.html. |
|
4882 | 4885 | |
|
4883 | 4886 | Credits |
|
4884 | 4887 | ======= |
|
4885 | 4888 | |
|
4886 | 4889 | IPython is mainly developed by Fernando Pérez |
|
4887 | 4890 | <Fernando.Perez@colorado.edu>, but the project was born from mixing in |
|
4888 | 4891 | Fernando's code with the IPP project by Janko Hauser |
|
4889 | 4892 | <jhauser-AT-zscout.de> and LazyPython by Nathan Gray |
|
4890 | 4893 | <n8gray-AT-caltech.edu>. For all IPython-related requests, please |
|
4891 | 4894 | contact Fernando. |
|
4892 | 4895 | |
|
4893 | 4896 | As of early 2006, the following developers have joined the core team: |
|
4894 | 4897 | |
|
4895 | 4898 | * [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005 |
|
4896 | 4899 | Google Summer of Code project to develop python interactive |
|
4897 | 4900 | notebooks (XML documents) and graphical interface. This project |
|
4898 | 4901 | was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and |
|
4899 | 4902 | Toni Alatalo <antont-AT-an.org> |
|
4900 | 4903 | * [Brian Granger] <bgranger-AT-scu.edu>: extending IPython to allow |
|
4901 | 4904 | support for interactive parallel computing. |
|
4902 | 4905 | * [Ville Vainio] <vivainio-AT-gmail.com>: Ville is the new |
|
4903 | 4906 | maintainer for the main trunk of IPython after version 0.7.1. |
|
4904 | 4907 | |
|
4905 | 4908 | User or development help should be requested via the IPython mailing lists: |
|
4906 | 4909 | |
|
4907 | 4910 | *User list:* |
|
4908 | 4911 | http://scipy.net/mailman/listinfo/ipython-user |
|
4909 | 4912 | *Developer's list:* |
|
4910 | 4913 | http://scipy.net/mailman/listinfo/ipython-dev |
|
4911 | 4914 | |
|
4912 | 4915 | The IPython project is also very grateful to^7 <footnode.html#foot2913>: |
|
4913 | 4916 | |
|
4914 | 4917 | Bill Bumgarner <bbum-AT-friday.com>: for providing the DPyGetOpt module |
|
4915 | 4918 | which gives very powerful and convenient handling of command-line |
|
4916 | 4919 | options (light years ahead of what Python 2.1.1's getopt module does). |
|
4917 | 4920 | |
|
4918 | 4921 | Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for |
|
4919 | 4922 | convenient and powerful string interpolation with a much nicer syntax |
|
4920 | 4923 | than formatting through the '%' operator. |
|
4921 | 4924 | |
|
4922 | 4925 | Arnd Baecker <baecker-AT-physik.tu-dresden.de>: for his many very useful |
|
4923 | 4926 | suggestions and comments, and lots of help with testing and |
|
4924 | 4927 | documentation checking. Many of IPython's newer features are a result of |
|
4925 | 4928 | discussions with him (bugs are still my fault, not his). |
|
4926 | 4929 | |
|
4927 | 4930 | Obviously Guido van Rossum and the whole Python development team, that |
|
4928 | 4931 | goes without saying. |
|
4929 | 4932 | |
|
4930 | 4933 | IPython's website is generously hosted at http://ipython.scipy.orgby |
|
4931 | 4934 | Enthought (http://www.enthought.com). I am very grateful to them and all |
|
4932 | 4935 | of the SciPy team for their contribution. |
|
4933 | 4936 | |
|
4934 | 4937 | Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>, |
|
4935 | 4938 | an O'Reilly Python editor. His Oct/11/2001 article about IPP and |
|
4936 | 4939 | LazyPython, was what got this project started. You can read it at: |
|
4937 | 4940 | http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html. |
|
4938 | 4941 | |
|
4939 | 4942 | And last but not least, all the kind IPython users who have emailed new |
|
4940 | 4943 | code, bug reports, fixes, comments and ideas. A brief list follows, |
|
4941 | 4944 | please let me know if I have ommitted your name by accident: |
|
4942 | 4945 | |
|
4943 | 4946 | * [Jack Moffit] <jack-AT-xiph.org> Bug fixes, including the infamous |
|
4944 | 4947 | color problem. This bug alone caused many lost hours and |
|
4945 | 4948 | frustration, many thanks to him for the fix. I've always been a |
|
4946 | 4949 | fan of Ogg & friends, now I have one more reason to like these folks. |
|
4947 | 4950 | Jack is also contributing with Debian packaging and many other |
|
4948 | 4951 | things. |
|
4949 | 4952 | * [Alexander Schmolck] <a.schmolck-AT-gmx.net> Emacs work, bug |
|
4950 | 4953 | reports, bug fixes, ideas, lots more. The ipython.el mode for |
|
4951 | 4954 | (X)Emacs is Alex's code, providing full support for IPython under |
|
4952 | 4955 | (X)Emacs. |
|
4953 | 4956 | * [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX |
|
4954 | 4957 | information, Fink package management. |
|
4955 | 4958 | * [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work |
|
4956 | 4959 | around the exception handling idiosyncracies of WxPython. Readline |
|
4957 | 4960 | and color support for Windows. |
|
4958 | 4961 | * [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much |
|
4959 | 4962 | improved readline support, including fixes for Python 2.3. |
|
4960 | 4963 | * [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port. |
|
4961 | 4964 | * [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG> |
|
4962 | 4965 | * [Christopher Hart] <hart-AT-caltech.edu> PDB integration. |
|
4963 | 4966 | * [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info. |
|
4964 | 4967 | * [Philip Hisley] <compsys-AT-starpower.net> |
|
4965 | 4968 | * [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots |
|
4966 | 4969 | more. |
|
4967 | 4970 | * [Robin Siebler] <robinsiebler-AT-starband.net> |
|
4968 | 4971 | * [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de> |
|
4969 | 4972 | * [Thorsten Kampe] <thorsten-AT-thorstenkampe.de> |
|
4970 | 4973 | * [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup. |
|
4971 | 4974 | * [Syver Enstad] <syver-en-AT-online.no> Windows setup. |
|
4972 | 4975 | * [Richard] <rxe-AT-renre-europe.com> Global embedding. |
|
4973 | 4976 | * [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6 |
|
4974 | 4977 | compatibility. |
|
4975 | 4978 | * [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows |
|
4976 | 4979 | installation. |
|
4977 | 4980 | * [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes. |
|
4978 | 4981 | * [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and |
|
4979 | 4982 | documentation fixes. |
|
4980 | 4983 | * [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows |
|
4981 | 4984 | ideas. Patches for Windows installer. |
|
4982 | 4985 | * [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics. |
|
4983 | 4986 | * [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch. |
|
4984 | 4987 | * [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for |
|
4985 | 4988 | Win32/CygWin. |
|
4986 | 4989 | * [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for |
|
4987 | 4990 | nice, lightweight string interpolation. |
|
4988 | 4991 | * [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas. |
|
4989 | 4992 | * [Gever Tulley] <gever-AT-helium.com> Code contributions. |
|
4990 | 4993 | * [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes. |
|
4991 | 4994 | * [Oliver Sander] <osander-AT-gmx.de> Bug reports. |
|
4992 | 4995 | * [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to |
|
4993 | 4996 | logging module. |
|
4994 | 4997 | * [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net> |
|
4995 | 4998 | Fixes, enhancement suggestions for system shell use. |
|
4996 | 4999 | * [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and |
|
4997 | 5000 | reports on Windows installation issues. Contributed a true Windows |
|
4998 | 5001 | binary installer. |
|
4999 | 5002 | * [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related |
|
5000 | 5003 | to traceback printing. |
|
5001 | 5004 | * [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like |
|
5002 | 5005 | prompt specials. |
|
5003 | 5006 | * [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for |
|
5004 | 5007 | the multithreaded IPython. |
|
5005 | 5008 | * [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib |
|
5006 | 5009 | author, helped with all the development of support for matplotlib |
|
5007 | 5010 | in IPyhton, including making necessary changes to matplotlib itself. |
|
5008 | 5011 | * [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea. |
|
5009 | 5012 | * [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help |
|
5010 | 5013 | with (X)Emacs support, threading patches, ideas... |
|
5011 | 5014 | * [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian |
|
5012 | 5015 | packaging and distribution. |
|
5013 | 5016 | * [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for |
|
5014 | 5017 | tab-completing named arguments of user-defined functions. |
|
5015 | 5018 | * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard |
|
5016 | 5019 | support implementation for searching namespaces. |
|
5017 | 5020 | * [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements, |
|
5018 | 5021 | so that when pdb is activated from within IPython, coloring, tab |
|
5019 | 5022 | completion and other features continue to work seamlessly. |
|
5020 | 5023 | * [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic |
|
5021 | 5024 | editor invocation on syntax errors (see |
|
5022 | 5025 | http://www.scipy.net/roundup/ipython/issue36). |
|
5023 | 5026 | * [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32 |
|
5024 | 5027 | paging system. |
|
5025 | 5028 | * [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port. |
|
5026 | 5029 |
General Comments 0
You need to be logged in to leave comments.
Login now