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