##// END OF EJS Templates
Make running PYTHONSTARTUP optional...
Thomas Kluyver -
Show More
@@ -1,419 +1,424 b''
1 1 # encoding: utf-8
2 2 """
3 3 A mixin for :class:`~IPython.core.application.Application` classes that
4 4 launch InteractiveShell instances, load extensions, etc.
5 5
6 6 Authors
7 7 -------
8 8
9 9 * Min Ragan-Kelley
10 10 """
11 11
12 12 #-----------------------------------------------------------------------------
13 13 # Copyright (C) 2008-2011 The IPython Development Team
14 14 #
15 15 # Distributed under the terms of the BSD License. The full license is in
16 16 # the file COPYING, distributed as part of this software.
17 17 #-----------------------------------------------------------------------------
18 18
19 19 #-----------------------------------------------------------------------------
20 20 # Imports
21 21 #-----------------------------------------------------------------------------
22 22
23 23 from __future__ import absolute_import
24 24 from __future__ import print_function
25 25
26 26 import glob
27 27 import os
28 28 import sys
29 29
30 30 from IPython.config.application import boolean_flag
31 31 from IPython.config.configurable import Configurable
32 32 from IPython.config.loader import Config
33 33 from IPython.core import pylabtools
34 34 from IPython.utils import py3compat
35 35 from IPython.utils.contexts import preserve_keys
36 36 from IPython.utils.path import filefind
37 37 from IPython.utils.traitlets import (
38 38 Unicode, Instance, List, Bool, CaselessStrEnum, Dict
39 39 )
40 40 from IPython.lib.inputhook import guis
41 41
42 42 #-----------------------------------------------------------------------------
43 43 # Aliases and Flags
44 44 #-----------------------------------------------------------------------------
45 45
46 46 gui_keys = tuple(sorted([ key for key in guis if key is not None ]))
47 47
48 48 backend_keys = sorted(pylabtools.backends.keys())
49 49 backend_keys.insert(0, 'auto')
50 50
51 51 shell_flags = {}
52 52
53 53 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
54 54 addflag('autoindent', 'InteractiveShell.autoindent',
55 55 'Turn on autoindenting.', 'Turn off autoindenting.'
56 56 )
57 57 addflag('automagic', 'InteractiveShell.automagic',
58 58 """Turn on the auto calling of magic commands. Type %%magic at the
59 59 IPython prompt for more information.""",
60 60 'Turn off the auto calling of magic commands.'
61 61 )
62 62 addflag('pdb', 'InteractiveShell.pdb',
63 63 "Enable auto calling the pdb debugger after every exception.",
64 64 "Disable auto calling the pdb debugger after every exception."
65 65 )
66 66 # pydb flag doesn't do any config, as core.debugger switches on import,
67 67 # which is before parsing. This just allows the flag to be passed.
68 68 shell_flags.update(dict(
69 69 pydb = ({},
70 70 """Use the third party 'pydb' package as debugger, instead of pdb.
71 71 Requires that pydb is installed."""
72 72 )
73 73 ))
74 74 addflag('pprint', 'PlainTextFormatter.pprint',
75 75 "Enable auto pretty printing of results.",
76 76 "Disable auto pretty printing of results."
77 77 )
78 78 addflag('color-info', 'InteractiveShell.color_info',
79 79 """IPython can display information about objects via a set of func-
80 80 tions, and optionally can use colors for this, syntax highlighting
81 81 source code and various other elements. However, because this
82 82 information is passed through a pager (like 'less') and many pagers get
83 83 confused with color codes, this option is off by default. You can test
84 84 it and turn it on permanently in your ipython_config.py file if it
85 85 works for you. Test it and turn it on permanently if it works with
86 86 your system. The magic function %%color_info allows you to toggle this
87 87 interactively for testing.""",
88 88 "Disable using colors for info related things."
89 89 )
90 90 addflag('deep-reload', 'InteractiveShell.deep_reload',
91 91 """Enable deep (recursive) reloading by default. IPython can use the
92 92 deep_reload module which reloads changes in modules recursively (it
93 93 replaces the reload() function, so you don't need to change anything to
94 94 use it). deep_reload() forces a full reload of modules whose code may
95 95 have changed, which the default reload() function does not. When
96 96 deep_reload is off, IPython will use the normal reload(), but
97 97 deep_reload will still be available as dreload(). This feature is off
98 98 by default [which means that you have both normal reload() and
99 99 dreload()].""",
100 100 "Disable deep (recursive) reloading by default."
101 101 )
102 102 nosep_config = Config()
103 103 nosep_config.InteractiveShell.separate_in = ''
104 104 nosep_config.InteractiveShell.separate_out = ''
105 105 nosep_config.InteractiveShell.separate_out2 = ''
106 106
107 107 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
108 108 shell_flags['pylab'] = (
109 109 {'InteractiveShellApp' : {'pylab' : 'auto'}},
110 110 """Pre-load matplotlib and numpy for interactive use with
111 111 the default matplotlib backend."""
112 112 )
113 113 shell_flags['matplotlib'] = (
114 114 {'InteractiveShellApp' : {'matplotlib' : 'auto'}},
115 115 """Configure matplotlib for interactive use with
116 116 the default matplotlib backend."""
117 117 )
118 118
119 119 # it's possible we don't want short aliases for *all* of these:
120 120 shell_aliases = dict(
121 121 autocall='InteractiveShell.autocall',
122 122 colors='InteractiveShell.colors',
123 123 logfile='InteractiveShell.logfile',
124 124 logappend='InteractiveShell.logappend',
125 125 c='InteractiveShellApp.code_to_run',
126 126 m='InteractiveShellApp.module_to_run',
127 127 ext='InteractiveShellApp.extra_extension',
128 128 gui='InteractiveShellApp.gui',
129 129 pylab='InteractiveShellApp.pylab',
130 130 matplotlib='InteractiveShellApp.matplotlib',
131 131 )
132 132 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
133 133
134 134 #-----------------------------------------------------------------------------
135 135 # Main classes and functions
136 136 #-----------------------------------------------------------------------------
137 137
138 138 class InteractiveShellApp(Configurable):
139 139 """A Mixin for applications that start InteractiveShell instances.
140 140
141 141 Provides configurables for loading extensions and executing files
142 142 as part of configuring a Shell environment.
143 143
144 144 The following methods should be called by the :meth:`initialize` method
145 145 of the subclass:
146 146
147 147 - :meth:`init_path`
148 148 - :meth:`init_shell` (to be implemented by the subclass)
149 149 - :meth:`init_gui_pylab`
150 150 - :meth:`init_extensions`
151 151 - :meth:`init_code`
152 152 """
153 153 extensions = List(Unicode, config=True,
154 154 help="A list of dotted module names of IPython extensions to load."
155 155 )
156 156 extra_extension = Unicode('', config=True,
157 157 help="dotted module name of an IPython extension to load."
158 158 )
159 159 def _extra_extension_changed(self, name, old, new):
160 160 if new:
161 161 # add to self.extensions
162 162 self.extensions.append(new)
163 163
164 164 # Extensions that are always loaded (not configurable)
165 165 default_extensions = List(Unicode, [u'storemagic'], config=False)
166 166
167 167 hide_initial_ns = Bool(True, config=True,
168 168 help="""Should variables loaded at startup (by startup files, exec_lines, etc.)
169 169 be hidden from tools like %who?"""
170 170 )
171 171
172 172 exec_files = List(Unicode, config=True,
173 173 help="""List of files to run at IPython startup."""
174 174 )
175 exec_PYTHONSTARTUP = Bool(True, config=True,
176 help="""Run the file referenced by the PYTHONSTARTUP environment
177 variable at IPython startup."""
178 )
175 179 file_to_run = Unicode('', config=True,
176 180 help="""A file to be run""")
177 181
178 182 exec_lines = List(Unicode, config=True,
179 183 help="""lines of code to run at IPython startup."""
180 184 )
181 185 code_to_run = Unicode('', config=True,
182 186 help="Execute the given command string."
183 187 )
184 188 module_to_run = Unicode('', config=True,
185 189 help="Run the module as a script."
186 190 )
187 191 gui = CaselessStrEnum(gui_keys, config=True,
188 192 help="Enable GUI event loop integration with any of {0}.".format(gui_keys)
189 193 )
190 194 matplotlib = CaselessStrEnum(backend_keys,
191 195 config=True,
192 196 help="""Configure matplotlib for interactive use with
193 197 the default matplotlib backend."""
194 198 )
195 199 pylab = CaselessStrEnum(backend_keys,
196 200 config=True,
197 201 help="""Pre-load matplotlib and numpy for interactive use,
198 202 selecting a particular matplotlib backend and loop integration.
199 203 """
200 204 )
201 205 pylab_import_all = Bool(True, config=True,
202 206 help="""If true, IPython will populate the user namespace with numpy, pylab, etc.
203 207 and an ``import *`` is done from numpy and pylab, when using pylab mode.
204 208
205 209 When False, pylab mode should not import any names into the user namespace.
206 210 """
207 211 )
208 212 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
209 213
210 214 user_ns = Instance(dict, args=None, allow_none=True)
211 215 def _user_ns_changed(self, name, old, new):
212 216 if self.shell is not None:
213 217 self.shell.user_ns = new
214 218 self.shell.init_user_ns()
215 219
216 220 def init_path(self):
217 221 """Add current working directory, '', to sys.path"""
218 222 if sys.path[0] != '':
219 223 sys.path.insert(0, '')
220 224
221 225 def init_shell(self):
222 226 raise NotImplementedError("Override in subclasses")
223 227
224 228 def init_gui_pylab(self):
225 229 """Enable GUI event loop integration, taking pylab into account."""
226 230 enable = False
227 231 shell = self.shell
228 232 if self.pylab:
229 233 enable = lambda key: shell.enable_pylab(key, import_all=self.pylab_import_all)
230 234 key = self.pylab
231 235 elif self.matplotlib:
232 236 enable = shell.enable_matplotlib
233 237 key = self.matplotlib
234 238 elif self.gui:
235 239 enable = shell.enable_gui
236 240 key = self.gui
237 241
238 242 if not enable:
239 243 return
240 244
241 245 try:
242 246 r = enable(key)
243 247 except ImportError:
244 248 self.log.warn("Eventloop or matplotlib integration failed. Is matplotlib installed?")
245 249 self.shell.showtraceback()
246 250 return
247 251 except Exception:
248 252 self.log.warn("GUI event loop or pylab initialization failed")
249 253 self.shell.showtraceback()
250 254 return
251 255
252 256 if isinstance(r, tuple):
253 257 gui, backend = r[:2]
254 258 self.log.info("Enabling GUI event loop integration, "
255 259 "eventloop=%s, matplotlib=%s", gui, backend)
256 260 if key == "auto":
257 261 print("Using matplotlib backend: %s" % backend)
258 262 else:
259 263 gui = r
260 264 self.log.info("Enabling GUI event loop integration, "
261 265 "eventloop=%s", gui)
262 266
263 267 def init_extensions(self):
264 268 """Load all IPython extensions in IPythonApp.extensions.
265 269
266 270 This uses the :meth:`ExtensionManager.load_extensions` to load all
267 271 the extensions listed in ``self.extensions``.
268 272 """
269 273 try:
270 274 self.log.debug("Loading IPython extensions...")
271 275 extensions = self.default_extensions + self.extensions
272 276 for ext in extensions:
273 277 try:
274 278 self.log.info("Loading IPython extension: %s" % ext)
275 279 self.shell.extension_manager.load_extension(ext)
276 280 except:
277 281 self.log.warn("Error in loading extension: %s" % ext +
278 282 "\nCheck your config files in %s" % self.profile_dir.location
279 283 )
280 284 self.shell.showtraceback()
281 285 except:
282 286 self.log.warn("Unknown error in loading extensions:")
283 287 self.shell.showtraceback()
284 288
285 289 def init_code(self):
286 290 """run the pre-flight code, specified via exec_lines"""
287 291 self._run_startup_files()
288 292 self._run_exec_lines()
289 293 self._run_exec_files()
290 294
291 295 # Hide variables defined here from %who etc.
292 296 if self.hide_initial_ns:
293 297 self.shell.user_ns_hidden.update(self.shell.user_ns)
294 298
295 299 # command-line execution (ipython -i script.py, ipython -m module)
296 300 # should *not* be excluded from %whos
297 301 self._run_cmd_line_code()
298 302 self._run_module()
299 303
300 304 # flush output, so itwon't be attached to the first cell
301 305 sys.stdout.flush()
302 306 sys.stderr.flush()
303 307
304 308 def _run_exec_lines(self):
305 309 """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
306 310 if not self.exec_lines:
307 311 return
308 312 try:
309 313 self.log.debug("Running code from IPythonApp.exec_lines...")
310 314 for line in self.exec_lines:
311 315 try:
312 316 self.log.info("Running code in user namespace: %s" %
313 317 line)
314 318 self.shell.run_cell(line, store_history=False)
315 319 except:
316 320 self.log.warn("Error in executing line in user "
317 321 "namespace: %s" % line)
318 322 self.shell.showtraceback()
319 323 except:
320 324 self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
321 325 self.shell.showtraceback()
322 326
323 327 def _exec_file(self, fname):
324 328 try:
325 329 full_filename = filefind(fname, [u'.', self.ipython_dir])
326 330 except IOError as e:
327 331 self.log.warn("File not found: %r"%fname)
328 332 return
329 333 # Make sure that the running script gets a proper sys.argv as if it
330 334 # were run from a system shell.
331 335 save_argv = sys.argv
332 336 sys.argv = [full_filename] + self.extra_args[1:]
333 337 # protect sys.argv from potential unicode strings on Python 2:
334 338 if not py3compat.PY3:
335 339 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
336 340 try:
337 341 if os.path.isfile(full_filename):
338 342 self.log.info("Running file in user namespace: %s" %
339 343 full_filename)
340 344 # Ensure that __file__ is always defined to match Python
341 345 # behavior.
342 346 with preserve_keys(self.shell.user_ns, '__file__'):
343 347 self.shell.user_ns['__file__'] = fname
344 348 if full_filename.endswith('.ipy'):
345 349 self.shell.safe_execfile_ipy(full_filename)
346 350 else:
347 351 # default to python, even without extension
348 352 self.shell.safe_execfile(full_filename,
349 353 self.shell.user_ns)
350 354 finally:
351 355 sys.argv = save_argv
352 356
353 357 def _run_startup_files(self):
354 358 """Run files from profile startup directory"""
355 359 startup_dir = self.profile_dir.startup_dir
356 360 startup_files = []
361 if self.exec_PYTHONSTARTUP:
357 362 if os.environ.get('PYTHONSTARTUP', False):
358 363 startup_files.append(os.environ['PYTHONSTARTUP'])
359 364 startup_files += glob.glob(os.path.join(startup_dir, '*.py'))
360 365 startup_files += glob.glob(os.path.join(startup_dir, '*.ipy'))
361 366 if not startup_files:
362 367 return
363 368
364 369 self.log.debug("Running startup files from %s...", startup_dir)
365 370 try:
366 371 for fname in sorted(startup_files):
367 372 self._exec_file(fname)
368 373 except:
369 374 self.log.warn("Unknown error in handling startup files:")
370 375 self.shell.showtraceback()
371 376
372 377 def _run_exec_files(self):
373 378 """Run files from IPythonApp.exec_files"""
374 379 if not self.exec_files:
375 380 return
376 381
377 382 self.log.debug("Running files in IPythonApp.exec_files...")
378 383 try:
379 384 for fname in self.exec_files:
380 385 self._exec_file(fname)
381 386 except:
382 387 self.log.warn("Unknown error in handling IPythonApp.exec_files:")
383 388 self.shell.showtraceback()
384 389
385 390 def _run_cmd_line_code(self):
386 391 """Run code or file specified at the command-line"""
387 392 if self.code_to_run:
388 393 line = self.code_to_run
389 394 try:
390 395 self.log.info("Running code given at command line (c=): %s" %
391 396 line)
392 397 self.shell.run_cell(line, store_history=False)
393 398 except:
394 399 self.log.warn("Error in executing line in user namespace: %s" %
395 400 line)
396 401 self.shell.showtraceback()
397 402
398 403 # Like Python itself, ignore the second if the first of these is present
399 404 elif self.file_to_run:
400 405 fname = self.file_to_run
401 406 try:
402 407 self._exec_file(fname)
403 408 except:
404 409 self.log.warn("Error in executing file in user namespace: %s" %
405 410 fname)
406 411 self.shell.showtraceback()
407 412
408 413 def _run_module(self):
409 414 """Run module specified at the command-line."""
410 415 if self.module_to_run:
411 416 # Make sure that the module gets a proper sys.argv as if it were
412 417 # run using `python -m`.
413 418 save_argv = sys.argv
414 419 sys.argv = [sys.executable] + self.extra_args
415 420 try:
416 421 self.shell.safe_run_module(self.module_to_run,
417 422 self.shell.user_ns)
418 423 finally:
419 424 sys.argv = save_argv
@@ -1,1164 +1,1169 b''
1 1 =================
2 2 IPython reference
3 3 =================
4 4
5 5 .. _command_line_options:
6 6
7 7 Command-line usage
8 8 ==================
9 9
10 10 You start IPython with the command::
11 11
12 12 $ ipython [options] files
13 13
14 14 .. note::
15 15
16 16 For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
17 17
18 18 If invoked with no options, it executes all the files listed in sequence
19 19 and drops you into the interpreter while still acknowledging any options
20 20 you may have set in your ipython_config.py. This behavior is different from
21 21 standard Python, which when called as python -i will only execute one
22 22 file and ignore your configuration setup.
23 23
24 24 Please note that some of the configuration options are not available at
25 25 the command line, simply because they are not practical here. Look into
26 26 your configuration files for details on those. There are separate configuration
27 27 files for each profile, and the files look like "ipython_config.py" or
28 28 "ipython_config_<frontendname>.py". Profile directories look like
29 29 "profile_profilename" and are typically installed in the IPYTHONDIR directory,
30 30 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
31 31 resolves to :file:`C:\\Documents and Settings\\YourUserName` in most
32 32 instances.
33 33
34 34
35 35 Eventloop integration
36 36 ---------------------
37 37
38 38 Previously IPython had command line options for controlling GUI event loop
39 39 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
40 40 version 0.11, these have been removed. Please see the new ``%gui``
41 41 magic command or :ref:`this section <gui_support>` for details on the new
42 42 interface, or specify the gui at the commandline::
43 43
44 44 $ ipython --gui=qt
45 45
46 46
47 47 Command-line Options
48 48 --------------------
49 49
50 50 To see the options IPython accepts, use ``ipython --help`` (and you probably
51 51 should run the output through a pager such as ``ipython --help | less`` for
52 52 more convenient reading). This shows all the options that have a single-word
53 53 alias to control them, but IPython lets you configure all of its objects from
54 54 the command-line by passing the full class name and a corresponding value; type
55 55 ``ipython --help-all`` to see this full list. For example::
56 56
57 57 ipython --matplotlib qt
58 58
59 59 is equivalent to::
60 60
61 61 ipython --TerminalIPythonApp.matplotlib='qt'
62 62
63 63 Note that in the second form, you *must* use the equal sign, as the expression
64 64 is evaluated as an actual Python assignment. While in the above example the
65 65 short form is more convenient, only the most common options have a short form,
66 66 while any configurable variable in IPython can be set at the command-line by
67 67 using the long form. This long form is the same syntax used in the
68 68 configuration files, if you want to set these options permanently.
69 69
70 70
71 71 Interactive use
72 72 ===============
73 73
74 74 IPython is meant to work as a drop-in replacement for the standard interactive
75 75 interpreter. As such, any code which is valid python should execute normally
76 76 under IPython (cases where this is not true should be reported as bugs). It
77 77 does, however, offer many features which are not available at a standard python
78 78 prompt. What follows is a list of these.
79 79
80 80
81 81 Caution for Windows users
82 82 -------------------------
83 83
84 84 Windows, unfortunately, uses the '\\' character as a path separator. This is a
85 85 terrible choice, because '\\' also represents the escape character in most
86 86 modern programming languages, including Python. For this reason, using '/'
87 87 character is recommended if you have problems with ``\``. However, in Windows
88 88 commands '/' flags options, so you can not use it for the root directory. This
89 89 means that paths beginning at the root must be typed in a contrived manner
90 90 like: ``%copy \opt/foo/bar.txt \tmp``
91 91
92 92 .. _magic:
93 93
94 94 Magic command system
95 95 --------------------
96 96
97 97 IPython will treat any line whose first character is a % as a special
98 98 call to a 'magic' function. These allow you to control the behavior of
99 99 IPython itself, plus a lot of system-type features. They are all
100 100 prefixed with a % character, but parameters are given without
101 101 parentheses or quotes.
102 102
103 103 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
104 104 only the rest of the current line, but all lines below them as well, in the
105 105 current execution block. Cell magics can in fact make arbitrary modifications
106 106 to the input they receive, which need not even be valid Python code at all.
107 107 They receive the whole block as a single string.
108 108
109 109 As a line magic example, the ``%cd`` magic works just like the OS command of
110 110 the same name::
111 111
112 112 In [8]: %cd
113 113 /home/fperez
114 114
115 115 The following uses the builtin ``timeit`` in cell mode::
116 116
117 117 In [10]: %%timeit x = range(10000)
118 118 ...: min(x)
119 119 ...: max(x)
120 120 ...:
121 121 1000 loops, best of 3: 438 us per loop
122 122
123 123 In this case, ``x = range(10000)`` is called as the line argument, and the
124 124 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
125 125 ``timeit`` magic receives both.
126 126
127 127 If you have 'automagic' enabled (as it by default), you don't need to type in
128 128 the single ``%`` explicitly for line magics; IPython will scan its internal
129 129 list of magic functions and call one if it exists. With automagic on you can
130 130 then just type ``cd mydir`` to go to directory 'mydir'::
131 131
132 132 In [9]: cd mydir
133 133 /home/fperez/mydir
134 134
135 135 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
136 136 calling only works for line magics.
137 137
138 138 The automagic system has the lowest possible precedence in name searches, so
139 139 defining an identifier with the same name as an existing magic function will
140 140 shadow it for automagic use. You can still access the shadowed magic function
141 141 by explicitly using the ``%`` character at the beginning of the line.
142 142
143 143 An example (with automagic on) should clarify all this:
144 144
145 145 .. sourcecode:: ipython
146 146
147 147 In [1]: cd ipython # %cd is called by automagic
148 148 /home/fperez/ipython
149 149
150 150 In [2]: cd=1 # now cd is just a variable
151 151
152 152 In [3]: cd .. # and doesn't work as a function anymore
153 153 File "<ipython-input-3-9fedb3aff56c>", line 1
154 154 cd ..
155 155 ^
156 156 SyntaxError: invalid syntax
157 157
158 158
159 159 In [4]: %cd .. # but %cd always works
160 160 /home/fperez
161 161
162 162 In [5]: del cd # if you remove the cd variable, automagic works again
163 163
164 164 In [6]: cd ipython
165 165
166 166 /home/fperez/ipython
167 167
168 168 Defining your own magics
169 169 ++++++++++++++++++++++++
170 170
171 171 There are two main ways to define your own magic functions: from standalone
172 172 functions and by inheriting from a base class provided by IPython:
173 173 :class:`IPython.core.magic.Magics`. Below we show code you can place in a file
174 174 that you load from your configuration, such as any file in the ``startup``
175 175 subdirectory of your default IPython profile.
176 176
177 177 First, let us see the simplest case. The following shows how to create a line
178 178 magic, a cell one and one that works in both modes, using just plain functions:
179 179
180 180 .. sourcecode:: python
181 181
182 182 from IPython.core.magic import (register_line_magic, register_cell_magic,
183 183 register_line_cell_magic)
184 184
185 185 @register_line_magic
186 186 def lmagic(line):
187 187 "my line magic"
188 188 return line
189 189
190 190 @register_cell_magic
191 191 def cmagic(line, cell):
192 192 "my cell magic"
193 193 return line, cell
194 194
195 195 @register_line_cell_magic
196 196 def lcmagic(line, cell=None):
197 197 "Magic that works both as %lcmagic and as %%lcmagic"
198 198 if cell is None:
199 199 print "Called as line magic"
200 200 return line
201 201 else:
202 202 print "Called as cell magic"
203 203 return line, cell
204 204
205 205 # We delete these to avoid name conflicts for automagic to work
206 206 del lmagic, lcmagic
207 207
208 208
209 209 You can also create magics of all three kinds by inheriting from the
210 210 :class:`IPython.core.magic.Magics` class. This lets you create magics that can
211 211 potentially hold state in between calls, and that have full access to the main
212 212 IPython object:
213 213
214 214 .. sourcecode:: python
215 215
216 216 # This code can be put in any Python module, it does not require IPython
217 217 # itself to be running already. It only creates the magics subclass but
218 218 # doesn't instantiate it yet.
219 219 from IPython.core.magic import (Magics, magics_class, line_magic,
220 220 cell_magic, line_cell_magic)
221 221
222 222 # The class MUST call this class decorator at creation time
223 223 @magics_class
224 224 class MyMagics(Magics):
225 225
226 226 @line_magic
227 227 def lmagic(self, line):
228 228 "my line magic"
229 229 print "Full access to the main IPython object:", self.shell
230 230 print "Variables in the user namespace:", self.shell.user_ns.keys()
231 231 return line
232 232
233 233 @cell_magic
234 234 def cmagic(self, line, cell):
235 235 "my cell magic"
236 236 return line, cell
237 237
238 238 @line_cell_magic
239 239 def lcmagic(self, line, cell=None):
240 240 "Magic that works both as %lcmagic and as %%lcmagic"
241 241 if cell is None:
242 242 print "Called as line magic"
243 243 return line
244 244 else:
245 245 print "Called as cell magic"
246 246 return line, cell
247 247
248 248
249 249 # In order to actually use these magics, you must register them with a
250 250 # running IPython. This code must be placed in a file that is loaded once
251 251 # IPython is up and running:
252 252 ip = get_ipython()
253 253 # You can register the class itself without instantiating it. IPython will
254 254 # call the default constructor on it.
255 255 ip.register_magics(MyMagics)
256 256
257 257 If you want to create a class with a different constructor that holds
258 258 additional state, then you should always call the parent constructor and
259 259 instantiate the class yourself before registration:
260 260
261 261 .. sourcecode:: python
262 262
263 263 @magics_class
264 264 class StatefulMagics(Magics):
265 265 "Magics that hold additional state"
266 266
267 267 def __init__(self, shell, data):
268 268 # You must call the parent constructor
269 269 super(StatefulMagics, self).__init__(shell)
270 270 self.data = data
271 271
272 272 # etc...
273 273
274 274 # This class must then be registered with a manually created instance,
275 275 # since its constructor has different arguments from the default:
276 276 ip = get_ipython()
277 277 magics = StatefulMagics(ip, some_data)
278 278 ip.register_magics(magics)
279 279
280 280
281 281 In earlier versions, IPython had an API for the creation of line magics (cell
282 282 magics did not exist at the time) that required you to create functions with a
283 283 method-looking signature and to manually pass both the function and the name.
284 284 While this API is no longer recommended, it remains indefinitely supported for
285 285 backwards compatibility purposes. With the old API, you'd create a magic as
286 286 follows:
287 287
288 288 .. sourcecode:: python
289 289
290 290 def func(self, line):
291 291 print "Line magic called with line:", line
292 292 print "IPython object:", self.shell
293 293
294 294 ip = get_ipython()
295 295 # Declare this function as the magic %mycommand
296 296 ip.define_magic('mycommand', func)
297 297
298 298 Type ``%magic`` for more information, including a list of all available magic
299 299 functions at any time and their docstrings. You can also type
300 300 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
301 301 information on the '?' system) to get information about any particular magic
302 302 function you are interested in.
303 303
304 304 The API documentation for the :mod:`IPython.core.magic` module contains the full
305 305 docstrings of all currently available magic commands.
306 306
307 307
308 308 Access to the standard Python help
309 309 ----------------------------------
310 310
311 311 Simply type ``help()`` to access Python's standard help system. You can
312 312 also type ``help(object)`` for information about a given object, or
313 313 ``help('keyword')`` for information on a keyword. You may need to configure your
314 314 PYTHONDOCS environment variable for this feature to work correctly.
315 315
316 316 .. _dynamic_object_info:
317 317
318 318 Dynamic object information
319 319 --------------------------
320 320
321 321 Typing ``?word`` or ``word?`` prints detailed information about an object. If
322 322 certain strings in the object are too long (e.g. function signatures) they get
323 323 snipped in the center for brevity. This system gives access variable types and
324 324 values, docstrings, function prototypes and other useful information.
325 325
326 326 If the information will not fit in the terminal, it is displayed in a pager
327 327 (``less`` if available, otherwise a basic internal pager).
328 328
329 329 Typing ``??word`` or ``word??`` gives access to the full information, including
330 330 the source code where possible. Long strings are not snipped.
331 331
332 332 The following magic functions are particularly useful for gathering
333 333 information about your working environment. You can get more details by
334 334 typing ``%magic`` or querying them individually (``%function_name?``);
335 335 this is just a summary:
336 336
337 337 * **%pdoc <object>**: Print (or run through a pager if too long) the
338 338 docstring for an object. If the given object is a class, it will
339 339 print both the class and the constructor docstrings.
340 340 * **%pdef <object>**: Print the call signature for any callable
341 341 object. If the object is a class, print the constructor information.
342 342 * **%psource <object>**: Print (or run through a pager if too long)
343 343 the source code for an object.
344 344 * **%pfile <object>**: Show the entire source file where an object was
345 345 defined via a pager, opening it at the line where the object
346 346 definition begins.
347 347 * **%who/%whos**: These functions give information about identifiers
348 348 you have defined interactively (not things you loaded or defined
349 349 in your configuration files). %who just prints a list of
350 350 identifiers and %whos prints a table with some basic details about
351 351 each identifier.
352 352
353 353 Note that the dynamic object information functions (?/??, ``%pdoc``,
354 354 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
355 355 directly on variables. For example, after doing ``import os``, you can use
356 356 ``os.path.abspath??``.
357 357
358 358 .. _readline:
359 359
360 360 Readline-based features
361 361 -----------------------
362 362
363 363 These features require the GNU readline library, so they won't work if your
364 364 Python installation lacks readline support. We will first describe the default
365 365 behavior IPython uses, and then how to change it to suit your preferences.
366 366
367 367
368 368 Command line completion
369 369 +++++++++++++++++++++++
370 370
371 371 At any time, hitting TAB will complete any available python commands or
372 372 variable names, and show you a list of the possible completions if
373 373 there's no unambiguous one. It will also complete filenames in the
374 374 current directory if no python names match what you've typed so far.
375 375
376 376
377 377 Search command history
378 378 ++++++++++++++++++++++
379 379
380 380 IPython provides two ways for searching through previous input and thus
381 381 reduce the need for repetitive typing:
382 382
383 383 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
384 384 (next,down) to search through only the history items that match
385 385 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
386 386 prompt, they just behave like normal arrow keys.
387 387 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
388 388 searches your history for lines that contain what you've typed so
389 389 far, completing as much as it can.
390 390
391 391
392 392 Persistent command history across sessions
393 393 ++++++++++++++++++++++++++++++++++++++++++
394 394
395 395 IPython will save your input history when it leaves and reload it next
396 396 time you restart it. By default, the history file is named
397 397 $IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
398 398 separate histories related to various tasks: commands related to
399 399 numerical work will not be clobbered by a system shell history, for
400 400 example.
401 401
402 402
403 403 Autoindent
404 404 ++++++++++
405 405
406 406 IPython can recognize lines ending in ':' and indent the next line,
407 407 while also un-indenting automatically after 'raise' or 'return'.
408 408
409 409 This feature uses the readline library, so it will honor your
410 410 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
411 411 to). Adding the following lines to your :file:`.inputrc` file can make
412 412 indenting/unindenting more convenient (M-i indents, M-u unindents)::
413 413
414 414 # if you don't already have a ~/.inputrc file, you need this include:
415 415 $include /etc/inputrc
416 416
417 417 $if Python
418 418 "\M-i": " "
419 419 "\M-u": "\d\d\d\d"
420 420 $endif
421 421
422 422 Note that there are 4 spaces between the quote marks after "M-i" above.
423 423
424 424 .. warning::
425 425
426 426 Setting the above indents will cause problems with unicode text entry in
427 427 the terminal.
428 428
429 429 .. warning::
430 430
431 431 Autoindent is ON by default, but it can cause problems with the pasting of
432 432 multi-line indented code (the pasted code gets re-indented on each line). A
433 433 magic function %autoindent allows you to toggle it on/off at runtime. You
434 434 can also disable it permanently on in your :file:`ipython_config.py` file
435 435 (set TerminalInteractiveShell.autoindent=False).
436 436
437 437 If you want to paste multiple lines in the terminal, it is recommended that
438 438 you use ``%paste``.
439 439
440 440
441 441 Customizing readline behavior
442 442 +++++++++++++++++++++++++++++
443 443
444 444 All these features are based on the GNU readline library, which has an
445 445 extremely customizable interface. Normally, readline is configured via a
446 446 file which defines the behavior of the library; the details of the
447 447 syntax for this can be found in the readline documentation available
448 448 with your system or on the Internet. IPython doesn't read this file (if
449 449 it exists) directly, but it does support passing to readline valid
450 450 options via a simple interface. In brief, you can customize readline by
451 451 setting the following options in your configuration file (note
452 452 that these options can not be specified at the command line):
453 453
454 454 * **readline_parse_and_bind**: this holds a list of strings to be executed
455 455 via a readline.parse_and_bind() command. The syntax for valid commands
456 456 of this kind can be found by reading the documentation for the GNU
457 457 readline library, as these commands are of the kind which readline
458 458 accepts in its configuration file.
459 459 * **readline_remove_delims**: a string of characters to be removed
460 460 from the default word-delimiters list used by readline, so that
461 461 completions may be performed on strings which contain them. Do not
462 462 change the default value unless you know what you're doing.
463 463
464 464 You will find the default values in your configuration file.
465 465
466 466
467 467 Session logging and restoring
468 468 -----------------------------
469 469
470 470 You can log all input from a session either by starting IPython with the
471 471 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
472 472 or by activating the logging at any moment with the magic function %logstart.
473 473
474 474 Log files can later be reloaded by running them as scripts and IPython
475 475 will attempt to 'replay' the log by executing all the lines in it, thus
476 476 restoring the state of a previous session. This feature is not quite
477 477 perfect, but can still be useful in many cases.
478 478
479 479 The log files can also be used as a way to have a permanent record of
480 480 any code you wrote while experimenting. Log files are regular text files
481 481 which you can later open in your favorite text editor to extract code or
482 482 to 'clean them up' before using them to replay a session.
483 483
484 484 The `%logstart` function for activating logging in mid-session is used as
485 485 follows::
486 486
487 487 %logstart [log_name [log_mode]]
488 488
489 489 If no name is given, it defaults to a file named 'ipython_log.py' in your
490 490 current working directory, in 'rotate' mode (see below).
491 491
492 492 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
493 493 history up to that point and then continues logging.
494 494
495 495 %logstart takes a second optional parameter: logging mode. This can be
496 496 one of (note that the modes are given unquoted):
497 497
498 498 * [over:] overwrite existing log_name.
499 499 * [backup:] rename (if exists) to log_name~ and start log_name.
500 500 * [append:] well, that says it.
501 501 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
502 502
503 503 The %logoff and %logon functions allow you to temporarily stop and
504 504 resume logging to a file which had previously been started with
505 505 %logstart. They will fail (with an explanation) if you try to use them
506 506 before logging has been started.
507 507
508 508 .. _system_shell_access:
509 509
510 510 System shell access
511 511 -------------------
512 512
513 513 Any input line beginning with a ! character is passed verbatim (minus
514 514 the !, of course) to the underlying operating system. For example,
515 515 typing ``!ls`` will run 'ls' in the current directory.
516 516
517 517 Manual capture of command output
518 518 --------------------------------
519 519
520 520 You can assign the result of a system command to a Python variable with the
521 521 syntax ``myfiles = !ls``. This gets machine readable output from stdout
522 522 (e.g. without colours), and splits on newlines. To explicitly get this sort of
523 523 output without assigning to a variable, use two exclamation marks (``!!ls``) or
524 524 the ``%sx`` magic command.
525 525
526 526 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
527 527 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
528 528 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
529 529 See :ref:`string_lists` for details.
530 530
531 531 IPython also allows you to expand the value of python variables when
532 532 making system calls. Wrap variables or expressions in {braces}::
533 533
534 534 In [1]: pyvar = 'Hello world'
535 535 In [2]: !echo "A python variable: {pyvar}"
536 536 A python variable: Hello world
537 537 In [3]: import math
538 538 In [4]: x = 8
539 539 In [5]: !echo {math.factorial(x)}
540 540 40320
541 541
542 542 For simple cases, you can alternatively prepend $ to a variable name::
543 543
544 544 In [6]: !echo $sys.argv
545 545 [/home/fperez/usr/bin/ipython]
546 546 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
547 547 A system variable: /home/fperez
548 548
549 549 System command aliases
550 550 ----------------------
551 551
552 552 The %alias magic function allows you to define magic functions which are in fact
553 553 system shell commands. These aliases can have parameters.
554 554
555 555 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
556 556
557 557 Then, typing ``alias_name params`` will execute the system command 'cmd
558 558 params' (from your underlying operating system).
559 559
560 560 You can also define aliases with parameters using %s specifiers (one per
561 561 parameter). The following example defines the parts function as an
562 562 alias to the command 'echo first %s second %s' where each %s will be
563 563 replaced by a positional parameter to the call to %parts::
564 564
565 565 In [1]: %alias parts echo first %s second %s
566 566 In [2]: parts A B
567 567 first A second B
568 568 In [3]: parts A
569 569 ERROR: Alias <parts> requires 2 arguments, 1 given.
570 570
571 571 If called with no parameters, %alias prints the table of currently
572 572 defined aliases.
573 573
574 574 The %rehashx magic allows you to load your entire $PATH as
575 575 ipython aliases. See its docstring for further details.
576 576
577 577
578 578 .. _dreload:
579 579
580 580 Recursive reload
581 581 ----------------
582 582
583 583 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
584 584 module: changes made to any of its dependencies will be reloaded without
585 585 having to exit. To start using it, do::
586 586
587 587 from IPython.lib.deepreload import reload as dreload
588 588
589 589
590 590 Verbose and colored exception traceback printouts
591 591 -------------------------------------------------
592 592
593 593 IPython provides the option to see very detailed exception tracebacks,
594 594 which can be especially useful when debugging large programs. You can
595 595 run any Python file with the %run function to benefit from these
596 596 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
597 597 be colored (if your terminal supports it) which makes them much easier
598 598 to parse visually.
599 599
600 600 See the magic xmode and colors functions for details (just type %magic).
601 601
602 602 These features are basically a terminal version of Ka-Ping Yee's cgitb
603 603 module, now part of the standard Python library.
604 604
605 605
606 606 .. _input_caching:
607 607
608 608 Input caching system
609 609 --------------------
610 610
611 611 IPython offers numbered prompts (In/Out) with input and output caching
612 612 (also referred to as 'input history'). All input is saved and can be
613 613 retrieved as variables (besides the usual arrow key recall), in
614 614 addition to the %rep magic command that brings a history entry
615 615 up for editing on the next command line.
616 616
617 617 The following GLOBAL variables always exist (so don't overwrite them!):
618 618
619 619 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
620 620 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
621 621 overwrite In with a variable of your own, you can remake the assignment to the
622 622 internal list with a simple ``In=_ih``.
623 623
624 624 Additionally, global variables named _i<n> are dynamically created (<n>
625 625 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
626 626
627 627 For example, what you typed at prompt 14 is available as _i14, _ih[14]
628 628 and In[14].
629 629
630 630 This allows you to easily cut and paste multi line interactive prompts
631 631 by printing them out: they print like a clean string, without prompt
632 632 characters. You can also manipulate them like regular variables (they
633 633 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
634 634 contents of input prompt 9.
635 635
636 636 You can also re-execute multiple lines of input easily by using the
637 637 magic %rerun or %macro functions. The macro system also allows you to re-execute
638 638 previous lines which include magic function calls (which require special
639 639 processing). Type %macro? for more details on the macro system.
640 640
641 641 A history function %hist allows you to see any part of your input
642 642 history by printing a range of the _i variables.
643 643
644 644 You can also search ('grep') through your history by typing
645 645 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
646 646 etc. You can bring history entries listed by '%hist -g' up for editing
647 647 with the %recall command, or run them immediately with %rerun.
648 648
649 649 .. _output_caching:
650 650
651 651 Output caching system
652 652 ---------------------
653 653
654 654 For output that is returned from actions, a system similar to the input
655 655 cache exists but using _ instead of _i. Only actions that produce a
656 656 result (NOT assignments, for example) are cached. If you are familiar
657 657 with Mathematica, IPython's _ variables behave exactly like
658 658 Mathematica's % variables.
659 659
660 660 The following GLOBAL variables always exist (so don't overwrite them!):
661 661
662 662 * [_] (a single underscore) : stores previous output, like Python's
663 663 default interpreter.
664 664 * [__] (two underscores): next previous.
665 665 * [___] (three underscores): next-next previous.
666 666
667 667 Additionally, global variables named _<n> are dynamically created (<n>
668 668 being the prompt counter), such that the result of output <n> is always
669 669 available as _<n> (don't use the angle brackets, just the number, e.g.
670 670 _21).
671 671
672 672 These variables are also stored in a global dictionary (not a
673 673 list, since it only has entries for lines which returned a result)
674 674 available under the names _oh and Out (similar to _ih and In). So the
675 675 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
676 676 accidentally overwrite the Out variable you can recover it by typing
677 677 'Out=_oh' at the prompt.
678 678
679 679 This system obviously can potentially put heavy memory demands on your
680 680 system, since it prevents Python's garbage collector from removing any
681 681 previously computed results. You can control how many results are kept
682 682 in memory with the option (at the command line or in your configuration
683 683 file) cache_size. If you set it to 0, the whole system is completely
684 684 disabled and the prompts revert to the classic '>>>' of normal Python.
685 685
686 686
687 687 Directory history
688 688 -----------------
689 689
690 690 Your history of visited directories is kept in the global list _dh, and
691 691 the magic %cd command can be used to go to any entry in that list. The
692 692 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
693 693 conveniently view the directory history.
694 694
695 695
696 696 Automatic parentheses and quotes
697 697 --------------------------------
698 698
699 699 These features were adapted from Nathan Gray's LazyPython. They are
700 700 meant to allow less typing for common situations.
701 701
702 702
703 703 Automatic parentheses
704 704 +++++++++++++++++++++
705 705
706 706 Callable objects (i.e. functions, methods, etc) can be invoked like this
707 707 (notice the commas between the arguments)::
708 708
709 709 In [1]: callable_ob arg1, arg2, arg3
710 710 ------> callable_ob(arg1, arg2, arg3)
711 711
712 712 You can force automatic parentheses by using '/' as the first character
713 713 of a line. For example::
714 714
715 715 In [2]: /globals # becomes 'globals()'
716 716
717 717 Note that the '/' MUST be the first character on the line! This won't work::
718 718
719 719 In [3]: print /globals # syntax error
720 720
721 721 In most cases the automatic algorithm should work, so you should rarely
722 722 need to explicitly invoke /. One notable exception is if you are trying
723 723 to call a function with a list of tuples as arguments (the parenthesis
724 724 will confuse IPython)::
725 725
726 726 In [4]: zip (1,2,3),(4,5,6) # won't work
727 727
728 728 but this will work::
729 729
730 730 In [5]: /zip (1,2,3),(4,5,6)
731 731 ------> zip ((1,2,3),(4,5,6))
732 732 Out[5]: [(1, 4), (2, 5), (3, 6)]
733 733
734 734 IPython tells you that it has altered your command line by displaying
735 735 the new command line preceded by ->. e.g.::
736 736
737 737 In [6]: callable list
738 738 ------> callable(list)
739 739
740 740
741 741 Automatic quoting
742 742 +++++++++++++++++
743 743
744 744 You can force automatic quoting of a function's arguments by using ','
745 745 or ';' as the first character of a line. For example::
746 746
747 747 In [1]: ,my_function /home/me # becomes my_function("/home/me")
748 748
749 749 If you use ';' the whole argument is quoted as a single string, while ',' splits
750 750 on whitespace::
751 751
752 752 In [2]: ,my_function a b c # becomes my_function("a","b","c")
753 753
754 754 In [3]: ;my_function a b c # becomes my_function("a b c")
755 755
756 756 Note that the ',' or ';' MUST be the first character on the line! This
757 757 won't work::
758 758
759 759 In [4]: x = ,my_function /home/me # syntax error
760 760
761 761 IPython as your default Python environment
762 762 ==========================================
763 763
764 Python honors the environment variable PYTHONSTARTUP and will execute at
765 startup the file referenced by this variable. If you put the following code at
766 the end of that file, then IPython will be your working environment anytime you
767 start Python::
764 Python honors the environment variable :envvar:`PYTHONSTARTUP` and will
765 execute at startup the file referenced by this variable. If you put the
766 following code at the end of that file, then IPython will be your working
767 environment anytime you start Python::
768 768
769 769 from IPython.frontend.terminal.ipapp import launch_new_instance
770 770 launch_new_instance()
771 771 raise SystemExit
772 772
773 773 The ``raise SystemExit`` is needed to exit Python when
774 774 it finishes, otherwise you'll be back at the normal Python '>>>'
775 775 prompt.
776 776
777 You'll also need to set the config option
778 ``InteractiveShellApp.exec_PYTHONSTARTUP = False``, otherwise IPython
779 will try to run :envvar:`PYTHONSTARTUP` again, sending it into an
780 infinite loop.
781
777 782 This is probably useful to developers who manage multiple Python
778 783 versions and don't want to have correspondingly multiple IPython
779 784 versions. Note that in this mode, there is no way to pass IPython any
780 785 command-line options, as those are trapped first by Python itself.
781 786
782 787 .. _Embedding:
783 788
784 789 Embedding IPython
785 790 =================
786 791
787 792 You can start a regular IPython session with
788 793
789 794 .. sourcecode:: python
790 795
791 796 import IPython
792 797 IPython.start_ipython()
793 798
794 799 at any point in your program. This will load IPython configuration,
795 800 startup files, and everything, just as if it were a normal IPython session.
796 801 In addition to this,
797 802 it is possible to embed an IPython instance inside your own Python programs.
798 803 This allows you to evaluate dynamically the state of your code,
799 804 operate with your variables, analyze them, etc. Note however that
800 805 any changes you make to values while in the shell do not propagate back
801 806 to the running code, so it is safe to modify your values because you
802 807 won't break your code in bizarre ways by doing so.
803 808
804 809 .. note::
805 810
806 811 At present, embedding IPython cannot be done from inside IPython.
807 812 Run the code samples below outside IPython.
808 813
809 814 This feature allows you to easily have a fully functional python
810 815 environment for doing object introspection anywhere in your code with a
811 816 simple function call. In some cases a simple print statement is enough,
812 817 but if you need to do more detailed analysis of a code fragment this
813 818 feature can be very valuable.
814 819
815 820 It can also be useful in scientific computing situations where it is
816 821 common to need to do some automatic, computationally intensive part and
817 822 then stop to look at data, plots, etc.
818 823 Opening an IPython instance will give you full access to your data and
819 824 functions, and you can resume program execution once you are done with
820 825 the interactive part (perhaps to stop again later, as many times as
821 826 needed).
822 827
823 828 The following code snippet is the bare minimum you need to include in
824 829 your Python programs for this to work (detailed examples follow later)::
825 830
826 831 from IPython import embed
827 832
828 833 embed() # this call anywhere in your program will start IPython
829 834
830 835 .. note::
831 836
832 837 As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
833 838 etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
834 839 It should function just the same as regular embed, but you connect
835 840 an external frontend rather than IPython starting up in the local
836 841 terminal.
837 842
838 843 You can run embedded instances even in code which is itself being run at
839 844 the IPython interactive prompt with '%run <filename>'. Since it's easy
840 845 to get lost as to where you are (in your top-level IPython or in your
841 846 embedded one), it's a good idea in such cases to set the in/out prompts
842 847 to something different for the embedded instances. The code examples
843 848 below illustrate this.
844 849
845 850 You can also have multiple IPython instances in your program and open
846 851 them separately, for example with different options for data
847 852 presentation. If you close and open the same instance multiple times,
848 853 its prompt counters simply continue from each execution to the next.
849 854
850 855 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
851 856 module for more details on the use of this system.
852 857
853 858 The following sample file illustrating how to use the embedding
854 859 functionality is provided in the examples directory as example-embed.py.
855 860 It should be fairly self-explanatory:
856 861
857 862 .. literalinclude:: ../../../examples/core/example-embed.py
858 863 :language: python
859 864
860 865 Once you understand how the system functions, you can use the following
861 866 code fragments in your programs which are ready for cut and paste:
862 867
863 868 .. literalinclude:: ../../../examples/core/example-embed-short.py
864 869 :language: python
865 870
866 871 Using the Python debugger (pdb)
867 872 ===============================
868 873
869 874 Running entire programs via pdb
870 875 -------------------------------
871 876
872 877 pdb, the Python debugger, is a powerful interactive debugger which
873 878 allows you to step through code, set breakpoints, watch variables,
874 879 etc. IPython makes it very easy to start any script under the control
875 880 of pdb, regardless of whether you have wrapped it into a 'main()'
876 881 function or not. For this, simply type '%run -d myscript' at an
877 882 IPython prompt. See the %run command's documentation (via '%run?' or
878 883 in Sec. magic_ for more details, including how to control where pdb
879 884 will stop execution first.
880 885
881 886 For more information on the use of the pdb debugger, read the included
882 887 pdb.doc file (part of the standard Python distribution). On a stock
883 888 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
884 889 easiest way to read it is by using the help() function of the pdb module
885 890 as follows (in an IPython prompt)::
886 891
887 892 In [1]: import pdb
888 893 In [2]: pdb.help()
889 894
890 895 This will load the pdb.doc document in a file viewer for you automatically.
891 896
892 897
893 898 Automatic invocation of pdb on exceptions
894 899 -----------------------------------------
895 900
896 901 IPython, if started with the ``--pdb`` option (or if the option is set in
897 902 your config file) can call the Python pdb debugger every time your code
898 903 triggers an uncaught exception. This feature
899 904 can also be toggled at any time with the %pdb magic command. This can be
900 905 extremely useful in order to find the origin of subtle bugs, because pdb
901 906 opens up at the point in your code which triggered the exception, and
902 907 while your program is at this point 'dead', all the data is still
903 908 available and you can walk up and down the stack frame and understand
904 909 the origin of the problem.
905 910
906 911 Furthermore, you can use these debugging facilities both with the
907 912 embedded IPython mode and without IPython at all. For an embedded shell
908 913 (see sec. Embedding_), simply call the constructor with
909 914 ``--pdb`` in the argument string and pdb will automatically be called if an
910 915 uncaught exception is triggered by your code.
911 916
912 917 For stand-alone use of the feature in your programs which do not use
913 918 IPython at all, put the following lines toward the top of your 'main'
914 919 routine::
915 920
916 921 import sys
917 922 from IPython.core import ultratb
918 923 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
919 924 color_scheme='Linux', call_pdb=1)
920 925
921 926 The mode keyword can be either 'Verbose' or 'Plain', giving either very
922 927 detailed or normal tracebacks respectively. The color_scheme keyword can
923 928 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
924 929 options which can be set in IPython with ``--colors`` and ``--xmode``.
925 930
926 931 This will give any of your programs detailed, colored tracebacks with
927 932 automatic invocation of pdb.
928 933
929 934
930 935 Extensions for syntax processing
931 936 ================================
932 937
933 938 This isn't for the faint of heart, because the potential for breaking
934 939 things is quite high. But it can be a very powerful and useful feature.
935 940 In a nutshell, you can redefine the way IPython processes the user input
936 941 line to accept new, special extensions to the syntax without needing to
937 942 change any of IPython's own code.
938 943
939 944 In the IPython/extensions directory you will find some examples
940 945 supplied, which we will briefly describe now. These can be used 'as is'
941 946 (and both provide very useful functionality), or you can use them as a
942 947 starting point for writing your own extensions.
943 948
944 949 .. _pasting_with_prompts:
945 950
946 951 Pasting of code starting with Python or IPython prompts
947 952 -------------------------------------------------------
948 953
949 954 IPython is smart enough to filter out input prompts, be they plain Python ones
950 955 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
951 956 therefore copy and paste from existing interactive sessions without worry.
952 957
953 958 The following is a 'screenshot' of how things work, copying an example from the
954 959 standard Python tutorial::
955 960
956 961 In [1]: >>> # Fibonacci series:
957 962
958 963 In [2]: ... # the sum of two elements defines the next
959 964
960 965 In [3]: ... a, b = 0, 1
961 966
962 967 In [4]: >>> while b < 10:
963 968 ...: ... print b
964 969 ...: ... a, b = b, a+b
965 970 ...:
966 971 1
967 972 1
968 973 2
969 974 3
970 975 5
971 976 8
972 977
973 978 And pasting from IPython sessions works equally well::
974 979
975 980 In [1]: In [5]: def f(x):
976 981 ...: ...: "A simple function"
977 982 ...: ...: return x**2
978 983 ...: ...:
979 984
980 985 In [2]: f(3)
981 986 Out[2]: 9
982 987
983 988 .. _gui_support:
984 989
985 990 GUI event loop support
986 991 ======================
987 992
988 993 .. versionadded:: 0.11
989 994 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
990 995
991 996 IPython has excellent support for working interactively with Graphical User
992 997 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
993 998 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
994 999 is extremely robust compared to our previous thread-based version. The
995 1000 advantages of this are:
996 1001
997 1002 * GUIs can be enabled and disabled dynamically at runtime.
998 1003 * The active GUI can be switched dynamically at runtime.
999 1004 * In some cases, multiple GUIs can run simultaneously with no problems.
1000 1005 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
1001 1006 all of these things.
1002 1007
1003 1008 For users, enabling GUI event loop integration is simple. You simple use the
1004 1009 ``%gui`` magic as follows::
1005 1010
1006 1011 %gui [GUINAME]
1007 1012
1008 1013 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
1009 1014 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
1010 1015
1011 1016 Thus, to use wxPython interactively and create a running :class:`wx.App`
1012 1017 object, do::
1013 1018
1014 1019 %gui wx
1015 1020
1016 1021 For information on IPython's matplotlib_ integration (and the ``matplotlib``
1017 1022 mode) see :ref:`this section <matplotlib_support>`.
1018 1023
1019 1024 For developers that want to use IPython's GUI event loop integration in the
1020 1025 form of a library, these capabilities are exposed in library form in the
1021 1026 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
1022 1027 Interested developers should see the module docstrings for more information,
1023 1028 but there are a few points that should be mentioned here.
1024 1029
1025 1030 First, the ``PyOSInputHook`` approach only works in command line settings
1026 1031 where readline is activated. The integration with various eventloops
1027 1032 is handled somewhat differently (and more simply) when using the standalone
1028 1033 kernel, as in the qtconsole and notebook.
1029 1034
1030 1035 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1031 1036 *not* start its event loop. Instead all of this is handled by the
1032 1037 ``PyOSInputHook``. This means that applications that are meant to be used both
1033 1038 in IPython and as standalone apps need to have special code to detects how the
1034 1039 application is being run. We highly recommend using IPython's support for this.
1035 1040 Since the details vary slightly between toolkits, we point you to the various
1036 1041 examples in our source directory :file:`examples/lib` that demonstrate
1037 1042 these capabilities.
1038 1043
1039 1044 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1040 1045 them with no-ops) the event loops. This is done to allow applications that
1041 1046 actually need to run the real event loops to do so. This is often needed to
1042 1047 process pending events at critical points.
1043 1048
1044 1049 Finally, we also have a number of examples in our source directory
1045 1050 :file:`examples/lib` that demonstrate these capabilities.
1046 1051
1047 1052 PyQt and PySide
1048 1053 ---------------
1049 1054
1050 1055 .. attempt at explanation of the complete mess that is Qt support
1051 1056
1052 1057 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
1053 1058 PyQt4 or PySide. There are three options for configuration here, because
1054 1059 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
1055 1060 Python 2, and the more natural v2, which is the only API supported by PySide.
1056 1061 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
1057 1062 uses v2, but you can still use any interface in your code, since the
1058 1063 Qt frontend is in a different process.
1059 1064
1060 1065 The default will be to import PyQt4 without configuration of the APIs, thus
1061 1066 matching what most applications would expect. It will fall back of PySide if
1062 1067 PyQt4 is unavailable.
1063 1068
1064 1069 If specified, IPython will respect the environment variable ``QT_API`` used
1065 1070 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
1066 1071 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
1067 1072 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
1068 1073 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
1069 1074
1070 1075 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
1071 1076 then IPython will ask matplotlib which Qt library to use (only if QT_API is
1072 1077 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
1073 1078 older, then IPython will always use PyQt4 without setting the v2 APIs, since
1074 1079 neither v2 PyQt nor PySide work.
1075 1080
1076 1081 .. warning::
1077 1082
1078 1083 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
1079 1084 to work with IPython's qt integration, because otherwise PyQt4 will be
1080 1085 loaded in an incompatible mode.
1081 1086
1082 1087 It also means that you must *not* have ``QT_API`` set if you want to
1083 1088 use ``--gui=qt`` with code that requires PyQt4 API v1.
1084 1089
1085 1090
1086 1091 .. _matplotlib_support:
1087 1092
1088 1093 Plotting with matplotlib
1089 1094 ========================
1090 1095
1091 1096 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
1092 1097 can produce plots on screen using a variety of GUI toolkits, including Tk,
1093 1098 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
1094 1099 scientific computing, all with a syntax compatible with that of the popular
1095 1100 Matlab program.
1096 1101
1097 1102 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
1098 1103 IPython is already running, you can run the ``%matplotlib`` magic. If no
1099 1104 arguments are given, IPython will automatically detect your choice of
1100 1105 matplotlib backend. You can also request a specific backend with
1101 1106 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
1102 1107 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
1103 1108 backend value, which produces static figures inlined inside the application
1104 1109 window instead of matplotlib's interactive figures that live in separate
1105 1110 windows.
1106 1111
1107 1112 .. _interactive_demos:
1108 1113
1109 1114 Interactive demos with IPython
1110 1115 ==============================
1111 1116
1112 1117 IPython ships with a basic system for running scripts interactively in
1113 1118 sections, useful when presenting code to audiences. A few tags embedded
1114 1119 in comments (so that the script remains valid Python code) divide a file
1115 1120 into separate blocks, and the demo can be run one block at a time, with
1116 1121 IPython printing (with syntax highlighting) the block before executing
1117 1122 it, and returning to the interactive prompt after each block. The
1118 1123 interactive namespace is updated after each block is run with the
1119 1124 contents of the demo's namespace.
1120 1125
1121 1126 This allows you to show a piece of code, run it and then execute
1122 1127 interactively commands based on the variables just created. Once you
1123 1128 want to continue, you simply execute the next block of the demo. The
1124 1129 following listing shows the markup necessary for dividing a script into
1125 1130 sections for execution as a demo:
1126 1131
1127 1132 .. literalinclude:: ../../../examples/lib/example-demo.py
1128 1133 :language: python
1129 1134
1130 1135 In order to run a file as a demo, you must first make a Demo object out
1131 1136 of it. If the file is named myscript.py, the following code will make a
1132 1137 demo::
1133 1138
1134 1139 from IPython.lib.demo import Demo
1135 1140
1136 1141 mydemo = Demo('myscript.py')
1137 1142
1138 1143 This creates the mydemo object, whose blocks you run one at a time by
1139 1144 simply calling the object with no arguments. If you have autocall active
1140 1145 in IPython (the default), all you need to do is type::
1141 1146
1142 1147 mydemo
1143 1148
1144 1149 and IPython will call it, executing each block. Demo objects can be
1145 1150 restarted, you can move forward or back skipping blocks, re-execute the
1146 1151 last block, etc. Simply use the Tab key on a demo object to see its
1147 1152 methods, and call '?' on them to see their docstrings for more usage
1148 1153 details. In addition, the demo module itself contains a comprehensive
1149 1154 docstring, which you can access via::
1150 1155
1151 1156 from IPython.lib import demo
1152 1157
1153 1158 demo?
1154 1159
1155 1160 Limitations: It is important to note that these demos are limited to
1156 1161 fairly simple uses. In particular, you cannot break up sections within
1157 1162 indented code (loops, if statements, function definitions, etc.)
1158 1163 Supporting something like this would basically require tracking the
1159 1164 internal execution state of the Python interpreter, so only top-level
1160 1165 divisions are allowed. If you want to be able to open an IPython
1161 1166 instance at an arbitrary point in a program, you can use IPython's
1162 1167 embedding facilities, see :func:`IPython.embed` for details.
1163 1168
1164 1169 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now