##// END OF EJS Templates
First semi-complete support for -pylab and %pylab....
Fernando Perez -
Show More
@@ -0,0 +1,146 b''
1 # -*- coding: utf-8 -*-
2 """Pylab (matplotlib) support utilities.
3
4 Authors
5 -------
6 Fernando Perez.
7 """
8
9 #-----------------------------------------------------------------------------
10 # Copyright (C) 2009 The IPython Development Team
11 #
12 # Distributed under the terms of the BSD License. The full license is in
13 # the file COPYING, distributed as part of this software.
14 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 # Imports
17 #-----------------------------------------------------------------------------
18 from IPython.utils.genutils import flag_calls
19
20 #-----------------------------------------------------------------------------
21 # Main classes and functions
22 #-----------------------------------------------------------------------------
23
24 def pylab_activate(user_ns, gui=None, import_all=True):
25 """Activate pylab mode in the user's namespace.
26
27 Loads and initializes numpy, matplotlib and friends for interactive use.
28
29 Parameters
30 ----------
31 user_ns : dict
32 Namespace where the imports will occur.
33
34 gui : optional, string
35 A valid gui name following the conventions of the %gui magic.
36
37 import_all : optional, boolean
38 If true, an 'import *' is done from numpy and pylab.
39
40 Returns
41 -------
42 The actual gui used (if not given as input, it was obtained from matplotlib
43 itself, and will be needed next to configure IPython's gui integration.
44 """
45
46 # Initialize matplotlib to interactive mode always
47 import matplotlib
48
49 # If user specifies a GUI, that dictates the backend, otherwise we read the
50 # user's mpl default from the mpl rc structure
51 g2b = {'tk': 'TkAgg',
52 'gtk': 'GTKAgg',
53 'wx': 'WXAgg',
54 'qt': 'Qt4Agg', # qt3 not supported
55 'qt4': 'Qt4Agg' }
56
57 if gui:
58 # select backend based on requested gui
59 backend = g2b[gui]
60 else:
61 backend = matplotlib.rcParams['backend']
62 # In this case, we need to find what the appropriate gui selection call
63 # should be for IPython, so we can activate inputhook accordingly
64 b2g = dict(zip(g2b.values(),g2b.keys()))
65 gui = b2g[backend]
66
67 # We must set the desired backend before importing pylab
68 matplotlib.use(backend)
69
70 # This must be imported last in the matplotlib series, after
71 # backend/interactivity choices have been made
72 import matplotlib.pylab as pylab
73
74 # XXX For now leave this commented out, but depending on discussions with
75 # mpl-dev, we may be able to allow interactive switching...
76 #import matplotlib.pyplot
77 #matplotlib.pyplot.switch_backend(backend)
78
79 pylab.show._needmain = False
80 # We need to detect at runtime whether show() is called by the user.
81 # For this, we wrap it into a decorator which adds a 'called' flag.
82 pylab.draw_if_interactive = flag_calls(pylab.draw_if_interactive)
83
84 # Import numpy as np/pyplot as plt are conventions we're trying to
85 # somewhat standardize on. Making them available to users by default
86 # will greatly help this.
87 exec ("import numpy\n"
88 "import matplotlib\n"
89 "from matplotlib import pylab, mlab, pyplot\n"
90 "np = numpy\n"
91 "plt = pyplot\n"
92 ) in user_ns
93
94 if import_all:
95 exec("from matplotlib.pylab import *\n"
96 "from numpy import *\n") in user_ns
97
98 matplotlib.interactive(True)
99
100 print """
101 Welcome to pylab, a matplotlib-based Python environment.
102 Backend in use: %s
103 For more information, type 'help(pylab)'.""" % backend
104
105 return gui
106
107 # We need a little factory function here to create the closure where
108 # safe_execfile can live.
109 def mpl_runner(safe_execfile):
110 """Factory to return a matplotlib-enabled runner for %run.
111
112 Parameters
113 ----------
114 safe_execfile : function
115 This must be a function with the same interface as the
116 :meth:`safe_execfile` method of IPython.
117
118 Returns
119 -------
120 A function suitable for use as the ``runner`` argument of the %run magic
121 function.
122 """
123
124 def mpl_execfile(fname,*where,**kw):
125 """matplotlib-aware wrapper around safe_execfile.
126
127 Its interface is identical to that of the :func:`execfile` builtin.
128
129 This is ultimately a call to execfile(), but wrapped in safeties to
130 properly handle interactive rendering."""
131
132 import matplotlib
133 import matplotlib.pylab as pylab
134
135 #print '*** Matplotlib runner ***' # dbg
136 # turn off rendering until end of script
137 is_interactive = matplotlib.rcParams['interactive']
138 matplotlib.interactive(False)
139 safe_execfile(fname,*where,**kw)
140 matplotlib.interactive(is_interactive)
141 # make rendering call now, if the user tried to do it
142 if pylab.draw_if_interactive.called:
143 pylab.draw()
144 pylab.draw_if_interactive.called = False
145
146 return mpl_execfile
@@ -1,565 +1,555 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 The :class:`~IPython.core.application.Application` object for the command
5 5 line :command:`ipython` program.
6 6
7 7 Authors:
8 8
9 9 * Brian Granger
10 10 * Fernando Perez
11 11
12 12 Notes
13 13 -----
14 14 """
15 15
16 16 #-----------------------------------------------------------------------------
17 17 # Copyright (C) 2008-2009 The IPython Development Team
18 18 #
19 19 # Distributed under the terms of the BSD License. The full license is in
20 20 # the file COPYING, distributed as part of this software.
21 21 #-----------------------------------------------------------------------------
22 22
23 23 #-----------------------------------------------------------------------------
24 24 # Imports
25 25 #-----------------------------------------------------------------------------
26 26
27 27 import logging
28 28 import os
29 29 import sys
30 import warnings
31 30
32 from IPython.core.application import Application, BaseAppArgParseConfigLoader
33 31 from IPython.core import release
32 from IPython.core.application import Application, BaseAppArgParseConfigLoader
33 from IPython.core.error import UsageError
34 34 from IPython.core.iplib import InteractiveShell
35 from IPython.core.pylabtools import pylab_activate
35 36 from IPython.config.loader import (
36 37 NoConfigDefault,
37 38 Config,
38 39 PyFileConfigLoader
39 40 )
40
41 41 from IPython.lib import inputhook
42
43 42 from IPython.utils.genutils import filefind, get_ipython_dir
44 43
45 44 #-----------------------------------------------------------------------------
46 45 # Utilities and helpers
47 46 #-----------------------------------------------------------------------------
48 47
49
50 48 ipython_desc = """
51 49 A Python shell with automatic history (input and output), dynamic object
52 50 introspection, easier configuration, command completion, access to the system
53 51 shell and more.
54 52 """
55 53
56 def pylab_warning():
57 msg = """
58
59 IPython's -pylab mode has been disabled until matplotlib supports this version
60 of IPython. This version of IPython has greatly improved GUI integration that
61 matplotlib will soon be able to take advantage of. This will eventually
62 result in greater stability and a richer API for matplotlib under IPython.
63 However during this transition, you will either need to use an older version
64 of IPython, or do the following to use matplotlib interactively::
65
66 import matplotlib
67 matplotlib.interactive(True)
68 matplotlib.use('wxagg') # adjust for your backend
69 %gui -a wx # adjust for your GUI
70 from matplotlib import pyplot as plt
71
72 See the %gui magic for information on the new interface.
73 """
74 warnings.warn(msg, category=DeprecationWarning, stacklevel=1)
75
76
77 54 #-----------------------------------------------------------------------------
78 55 # Main classes and functions
79 56 #-----------------------------------------------------------------------------
80 57
81 58 cl_args = (
82 59 (('--autocall',), dict(
83 60 type=int, dest='InteractiveShell.autocall', default=NoConfigDefault,
84 61 help='Set the autocall value (0,1,2).',
85 62 metavar='InteractiveShell.autocall')
86 63 ),
87 64 (('--autoindent',), dict(
88 65 action='store_true', dest='InteractiveShell.autoindent', default=NoConfigDefault,
89 66 help='Turn on autoindenting.')
90 67 ),
91 68 (('--no-autoindent',), dict(
92 69 action='store_false', dest='InteractiveShell.autoindent', default=NoConfigDefault,
93 70 help='Turn off autoindenting.')
94 71 ),
95 72 (('--automagic',), dict(
96 73 action='store_true', dest='InteractiveShell.automagic', default=NoConfigDefault,
97 74 help='Turn on the auto calling of magic commands.')
98 75 ),
99 76 (('--no-automagic',), dict(
100 77 action='store_false', dest='InteractiveShell.automagic', default=NoConfigDefault,
101 78 help='Turn off the auto calling of magic commands.')
102 79 ),
103 80 (('--autoedit-syntax',), dict(
104 81 action='store_true', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
105 82 help='Turn on auto editing of files with syntax errors.')
106 83 ),
107 84 (('--no-autoedit-syntax',), dict(
108 85 action='store_false', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
109 86 help='Turn off auto editing of files with syntax errors.')
110 87 ),
111 88 (('--banner',), dict(
112 89 action='store_true', dest='Global.display_banner', default=NoConfigDefault,
113 90 help='Display a banner upon starting IPython.')
114 91 ),
115 92 (('--no-banner',), dict(
116 93 action='store_false', dest='Global.display_banner', default=NoConfigDefault,
117 94 help="Don't display a banner upon starting IPython.")
118 95 ),
119 96 (('--cache-size',), dict(
120 97 type=int, dest='InteractiveShell.cache_size', default=NoConfigDefault,
121 98 help="Set the size of the output cache.",
122 99 metavar='InteractiveShell.cache_size')
123 100 ),
124 101 (('--classic',), dict(
125 102 action='store_true', dest='Global.classic', default=NoConfigDefault,
126 103 help="Gives IPython a similar feel to the classic Python prompt.")
127 104 ),
128 105 (('--colors',), dict(
129 106 type=str, dest='InteractiveShell.colors', default=NoConfigDefault,
130 107 help="Set the color scheme (NoColor, Linux, and LightBG).",
131 108 metavar='InteractiveShell.colors')
132 109 ),
133 110 (('--color-info',), dict(
134 111 action='store_true', dest='InteractiveShell.color_info', default=NoConfigDefault,
135 112 help="Enable using colors for info related things.")
136 113 ),
137 114 (('--no-color-info',), dict(
138 115 action='store_false', dest='InteractiveShell.color_info', default=NoConfigDefault,
139 116 help="Disable using colors for info related things.")
140 117 ),
141 118 (('--confirm-exit',), dict(
142 119 action='store_true', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
143 120 help="Prompt the user when existing.")
144 121 ),
145 122 (('--no-confirm-exit',), dict(
146 123 action='store_false', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
147 124 help="Don't prompt the user when existing.")
148 125 ),
149 126 (('--deep-reload',), dict(
150 127 action='store_true', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
151 128 help="Enable deep (recursive) reloading by default.")
152 129 ),
153 130 (('--no-deep-reload',), dict(
154 131 action='store_false', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
155 132 help="Disable deep (recursive) reloading by default.")
156 133 ),
157 134 (('--editor',), dict(
158 135 type=str, dest='InteractiveShell.editor', default=NoConfigDefault,
159 136 help="Set the editor used by IPython (default to $EDITOR/vi/notepad).",
160 137 metavar='InteractiveShell.editor')
161 138 ),
162 139 (('--log','-l'), dict(
163 140 action='store_true', dest='InteractiveShell.logstart', default=NoConfigDefault,
164 141 help="Start logging to the default file (./ipython_log.py).")
165 142 ),
166 143 (('--logfile','-lf'), dict(
167 144 type=unicode, dest='InteractiveShell.logfile', default=NoConfigDefault,
168 145 help="Start logging to logfile.",
169 146 metavar='InteractiveShell.logfile')
170 147 ),
171 148 (('--log-append','-la'), dict(
172 149 type=unicode, dest='InteractiveShell.logappend', default=NoConfigDefault,
173 150 help="Start logging to the give file in append mode.",
174 151 metavar='InteractiveShell.logfile')
175 152 ),
176 153 (('--pdb',), dict(
177 154 action='store_true', dest='InteractiveShell.pdb', default=NoConfigDefault,
178 155 help="Enable auto calling the pdb debugger after every exception.")
179 156 ),
180 157 (('--no-pdb',), dict(
181 158 action='store_false', dest='InteractiveShell.pdb', default=NoConfigDefault,
182 159 help="Disable auto calling the pdb debugger after every exception.")
183 160 ),
184 161 (('--pprint',), dict(
185 162 action='store_true', dest='InteractiveShell.pprint', default=NoConfigDefault,
186 163 help="Enable auto pretty printing of results.")
187 164 ),
188 165 (('--no-pprint',), dict(
189 166 action='store_false', dest='InteractiveShell.pprint', default=NoConfigDefault,
190 167 help="Disable auto auto pretty printing of results.")
191 168 ),
192 169 (('--prompt-in1','-pi1'), dict(
193 170 type=str, dest='InteractiveShell.prompt_in1', default=NoConfigDefault,
194 171 help="Set the main input prompt ('In [\#]: ')",
195 172 metavar='InteractiveShell.prompt_in1')
196 173 ),
197 174 (('--prompt-in2','-pi2'), dict(
198 175 type=str, dest='InteractiveShell.prompt_in2', default=NoConfigDefault,
199 176 help="Set the secondary input prompt (' .\D.: ')",
200 177 metavar='InteractiveShell.prompt_in2')
201 178 ),
202 179 (('--prompt-out','-po'), dict(
203 180 type=str, dest='InteractiveShell.prompt_out', default=NoConfigDefault,
204 181 help="Set the output prompt ('Out[\#]:')",
205 182 metavar='InteractiveShell.prompt_out')
206 183 ),
207 184 (('--quick',), dict(
208 185 action='store_true', dest='Global.quick', default=NoConfigDefault,
209 186 help="Enable quick startup with no config files.")
210 187 ),
211 188 (('--readline',), dict(
212 189 action='store_true', dest='InteractiveShell.readline_use', default=NoConfigDefault,
213 190 help="Enable readline for command line usage.")
214 191 ),
215 192 (('--no-readline',), dict(
216 193 action='store_false', dest='InteractiveShell.readline_use', default=NoConfigDefault,
217 194 help="Disable readline for command line usage.")
218 195 ),
219 196 (('--screen-length','-sl'), dict(
220 197 type=int, dest='InteractiveShell.screen_length', default=NoConfigDefault,
221 198 help='Number of lines on screen, used to control printing of long strings.',
222 199 metavar='InteractiveShell.screen_length')
223 200 ),
224 201 (('--separate-in','-si'), dict(
225 202 type=str, dest='InteractiveShell.separate_in', default=NoConfigDefault,
226 203 help="Separator before input prompts. Default '\n'.",
227 204 metavar='InteractiveShell.separate_in')
228 205 ),
229 206 (('--separate-out','-so'), dict(
230 207 type=str, dest='InteractiveShell.separate_out', default=NoConfigDefault,
231 208 help="Separator before output prompts. Default 0 (nothing).",
232 209 metavar='InteractiveShell.separate_out')
233 210 ),
234 211 (('--separate-out2','-so2'), dict(
235 212 type=str, dest='InteractiveShell.separate_out2', default=NoConfigDefault,
236 213 help="Separator after output prompts. Default 0 (nonight).",
237 214 metavar='InteractiveShell.separate_out2')
238 215 ),
239 216 (('-no-sep',), dict(
240 217 action='store_true', dest='Global.nosep', default=NoConfigDefault,
241 218 help="Eliminate all spacing between prompts.")
242 219 ),
243 220 (('--term-title',), dict(
244 221 action='store_true', dest='InteractiveShell.term_title', default=NoConfigDefault,
245 222 help="Enable auto setting the terminal title.")
246 223 ),
247 224 (('--no-term-title',), dict(
248 225 action='store_false', dest='InteractiveShell.term_title', default=NoConfigDefault,
249 226 help="Disable auto setting the terminal title.")
250 227 ),
251 228 (('--xmode',), dict(
252 229 type=str, dest='InteractiveShell.xmode', default=NoConfigDefault,
253 230 help="Exception mode ('Plain','Context','Verbose')",
254 231 metavar='InteractiveShell.xmode')
255 232 ),
256 233 (('--ext',), dict(
257 234 type=str, dest='Global.extra_extension', default=NoConfigDefault,
258 235 help="The dotted module name of an IPython extension to load.",
259 236 metavar='Global.extra_extension')
260 237 ),
261 238 (('-c',), dict(
262 239 type=str, dest='Global.code_to_run', default=NoConfigDefault,
263 240 help="Execute the given command string.",
264 241 metavar='Global.code_to_run')
265 242 ),
266 243 (('-i',), dict(
267 244 action='store_true', dest='Global.force_interact', default=NoConfigDefault,
268 245 help="If running code from the command line, become interactive afterwards.")
269 246 ),
270 (('--wthread',), dict(
247 (('--wthread','-wthread'), dict(
271 248 action='store_true', dest='Global.wthread', default=NoConfigDefault,
272 249 help="Enable wxPython event loop integration.")
273 250 ),
274 (('--q4thread','--qthread'), dict(
251 (('--q4thread','--qthread','-q4thread','-qthread'), dict(
275 252 action='store_true', dest='Global.q4thread', default=NoConfigDefault,
276 253 help="Enable Qt4 event loop integration. Qt3 is no longer supported.")
277 254 ),
278 (('--gthread',), dict(
255 (('--gthread','-gthread'), dict(
279 256 action='store_true', dest='Global.gthread', default=NoConfigDefault,
280 257 help="Enable GTK event loop integration.")
281 258 ),
282 # # These are only here to get the proper deprecation warnings
283 259 (('--pylab',), dict(
284 260 action='store_true', dest='Global.pylab', default=NoConfigDefault,
285 help="Disabled. Pylab has been disabled until matplotlib "
286 "supports this version of IPython.")
261 help="Pre-load matplotlib and numpy for interactive use.")
287 262 )
288 263 )
289 264
290 265
291 266 class IPythonAppCLConfigLoader(BaseAppArgParseConfigLoader):
292 267
293 268 arguments = cl_args
294 269
295 270 def load_config(self):
296 271 """Do actions just before loading the command line config."""
297 272
298 273 # Special hack: there are countless uses of 'ipython -pylab' (with one
299 274 # dash) in the wild, including in printed books. Since argparse does
300 275 # will interpret -pylab as '-p ylab', sending us in a search for a
301 276 # profile named 'ylab', instead we special-case here -pylab as the
302 277 # first or second option only (this is how old ipython used to work)
303 278 # and convert this use to --pylab. Ugly, but needed for this one
304 279 # very widely used case.
305 280 firstargs = sys.argv[:3]
306 281 try:
307 282 idx = firstargs.index('-pylab')
308 283 except ValueError:
309 284 pass
310 285 else:
311 286 sys.argv[idx] = '--pylab'
312 287 return super(IPythonAppCLConfigLoader, self).load_config()
313 288
314 289 default_config_file_name = u'ipython_config.py'
315 290
316 291
317 292 class IPythonApp(Application):
318 293 name = u'ipython'
319 294 description = 'IPython: an enhanced interactive Python shell.'
320 295 config_file_name = default_config_file_name
321 296
322 297 def create_default_config(self):
323 298 super(IPythonApp, self).create_default_config()
324 299 # Eliminate multiple lookups
325 300 Global = self.default_config.Global
326 301 # Set all default values
327 302 Global.display_banner = True
328 303
329 304 # If the -c flag is given or a file is given to run at the cmd line
330 305 # like "ipython foo.py", normally we exit without starting the main
331 306 # loop. The force_interact config variable allows a user to override
332 307 # this and interact. It is also set by the -i cmd line flag, just
333 308 # like Python.
334 309 Global.force_interact = False
335 310
336 311 # By default always interact by starting the IPython mainloop.
337 312 Global.interact = True
338 313
339 314 # No GUI integration by default
340 315 Global.wthread = False
341 316 Global.q4thread = False
342 317 Global.gthread = False
343 318
319 # Pylab off by default
320 Global.pylab = False
321
344 322 def create_command_line_config(self):
345 323 """Create and return a command line config loader."""
346 324 return IPythonAppCLConfigLoader(
347 325 description=self.description,
348 326 version=release.version
349 327 )
350 328
351 def post_load_command_line_config(self):
352 """Do actions after loading cl config."""
353 clc = self.command_line_config
354
355 # Display the deprecation warnings about threaded shells
356 if hasattr(clc.Global, 'pylab'):
357 pylab_warning()
358 del clc.Global['pylab']
359 329
360 330 def load_file_config(self):
361 331 if hasattr(self.command_line_config.Global, 'quick'):
362 332 if self.command_line_config.Global.quick:
363 333 self.file_config = Config()
364 334 return
365 335 super(IPythonApp, self).load_file_config()
366 336
367 337 def post_load_file_config(self):
368 338 if hasattr(self.command_line_config.Global, 'extra_extension'):
369 339 if not hasattr(self.file_config.Global, 'extensions'):
370 340 self.file_config.Global.extensions = []
371 341 self.file_config.Global.extensions.append(
372 342 self.command_line_config.Global.extra_extension)
373 343 del self.command_line_config.Global.extra_extension
374 344
375 345 def pre_construct(self):
376 346 config = self.master_config
377 347
378 348 if hasattr(config.Global, 'classic'):
379 349 if config.Global.classic:
380 350 config.InteractiveShell.cache_size = 0
381 351 config.InteractiveShell.pprint = 0
382 352 config.InteractiveShell.prompt_in1 = '>>> '
383 353 config.InteractiveShell.prompt_in2 = '... '
384 354 config.InteractiveShell.prompt_out = ''
385 355 config.InteractiveShell.separate_in = \
386 356 config.InteractiveShell.separate_out = \
387 357 config.InteractiveShell.separate_out2 = ''
388 358 config.InteractiveShell.colors = 'NoColor'
389 359 config.InteractiveShell.xmode = 'Plain'
390 360
391 361 if hasattr(config.Global, 'nosep'):
392 362 if config.Global.nosep:
393 363 config.InteractiveShell.separate_in = \
394 364 config.InteractiveShell.separate_out = \
395 365 config.InteractiveShell.separate_out2 = ''
396 366
397 367 # if there is code of files to run from the cmd line, don't interact
398 368 # unless the -i flag (Global.force_interact) is true.
399 369 code_to_run = config.Global.get('code_to_run','')
400 370 file_to_run = False
401 371 if len(self.extra_args)>=1:
402 372 if self.extra_args[0]:
403 373 file_to_run = True
404 374 if file_to_run or code_to_run:
405 375 if not config.Global.force_interact:
406 376 config.Global.interact = False
407 377
408 378 def construct(self):
409 379 # I am a little hesitant to put these into InteractiveShell itself.
410 380 # But that might be the place for them
411 381 sys.path.insert(0, '')
412 382
413 383 # Create an InteractiveShell instance
414 384 self.shell = InteractiveShell(
415 385 parent=None,
416 386 config=self.master_config
417 387 )
418 388
419 389 def post_construct(self):
420 390 """Do actions after construct, but before starting the app."""
421 391 config = self.master_config
422 392
423 393 # shell.display_banner should always be False for the terminal
424 394 # based app, because we call shell.show_banner() by hand below
425 395 # so the banner shows *before* all extension loading stuff.
426 396 self.shell.display_banner = False
427 397
428 398 if config.Global.display_banner and \
429 399 config.Global.interact:
430 400 self.shell.show_banner()
431 401
432 402 # Make sure there is a space below the banner.
433 403 if self.log_level <= logging.INFO: print
434 404
435 405 # Now a variety of things that happen after the banner is printed.
436 self._enable_gui()
406 self._enable_gui_pylab()
437 407 self._load_extensions()
438 408 self._run_exec_lines()
439 409 self._run_exec_files()
440 410 self._run_cmd_line_code()
411 self._configure_xmode()
412
413 def _enable_gui_pylab(self):
414 """Enable GUI event loop integration, taking pylab into account."""
415 Global = self.master_config.Global
416
417 # Select which gui to use
418 if Global.wthread:
419 gui = inputhook.GUI_WX
420 elif Global.q4thread:
421 gui = inputhook.GUI_QT
422 elif Global.gthread:
423 gui = inputhook.GUI_GTK
424 else:
425 gui = None
441 426
442 def _enable_gui(self):
443 """Enable GUI event loop integration."""
444 config = self.master_config
427 if Global.pylab:
428 activate = self.shell.enable_pylab
429 else:
430 # Enable only GUI integration, no pylab
431 activate = inputhook.enable_gui
432
433 if gui or Global.pylab:
445 434 try:
446 # Enable GUI integration
447 if config.Global.wthread:
448 self.log.info("Enabling wx GUI event loop integration")
449 inputhook.enable_wx(app=True)
450 elif config.Global.q4thread:
451 self.log.info("Enabling Qt4 GUI event loop integration")
452 inputhook.enable_qt4(app=True)
453 elif config.Global.gthread:
454 self.log.info("Enabling GTK GUI event loop integration")
455 inputhook.enable_gtk(app=True)
435 m = "Enabling GUI event loop integration, toolkit=%s, pylab=%s"\
436 % (gui, Global.pylab)
437 self.log.info(m)
438 activate(gui)
456 439 except:
457 440 self.log.warn("Error in enabling GUI event loop integration:")
458 441 self.shell.showtraceback()
459 442
443
460 444 def _load_extensions(self):
461 445 """Load all IPython extensions in Global.extensions.
462 446
463 447 This uses the :meth:`InteractiveShell.load_extensions` to load all
464 448 the extensions listed in ``self.master_config.Global.extensions``.
465 449 """
466 450 try:
467 451 if hasattr(self.master_config.Global, 'extensions'):
468 452 self.log.debug("Loading IPython extensions...")
469 453 extensions = self.master_config.Global.extensions
470 454 for ext in extensions:
471 455 try:
472 456 self.log.info("Loading IPython extension: %s" % ext)
473 457 self.shell.load_extension(ext)
474 458 except:
475 459 self.log.warn("Error in loading extension: %s" % ext)
476 460 self.shell.showtraceback()
477 461 except:
478 462 self.log.warn("Unknown error in loading extensions:")
479 463 self.shell.showtraceback()
480 464
481 465 def _run_exec_lines(self):
482 466 """Run lines of code in Global.exec_lines in the user's namespace."""
483 467 try:
484 468 if hasattr(self.master_config.Global, 'exec_lines'):
485 469 self.log.debug("Running code from Global.exec_lines...")
486 470 exec_lines = self.master_config.Global.exec_lines
487 471 for line in exec_lines:
488 472 try:
489 473 self.log.info("Running code in user namespace: %s" % line)
490 474 self.shell.runlines(line)
491 475 except:
492 476 self.log.warn("Error in executing line in user namespace: %s" % line)
493 477 self.shell.showtraceback()
494 478 except:
495 479 self.log.warn("Unknown error in handling Global.exec_lines:")
496 480 self.shell.showtraceback()
497 481
498 482 def _exec_file(self, fname):
499 483 full_filename = filefind(fname, [u'.', self.ipython_dir])
500 484 if os.path.isfile(full_filename):
501 485 if full_filename.endswith(u'.py'):
502 486 self.log.info("Running file in user namespace: %s" % full_filename)
503 487 self.shell.safe_execfile(full_filename, self.shell.user_ns)
504 488 elif full_filename.endswith('.ipy'):
505 489 self.log.info("Running file in user namespace: %s" % full_filename)
506 490 self.shell.safe_execfile_ipy(full_filename)
507 491 else:
508 492 self.log.warn("File does not have a .py or .ipy extension: <%s>" % full_filename)
509 493
510 494 def _run_exec_files(self):
511 495 try:
512 496 if hasattr(self.master_config.Global, 'exec_files'):
513 497 self.log.debug("Running files in Global.exec_files...")
514 498 exec_files = self.master_config.Global.exec_files
515 499 for fname in exec_files:
516 500 self._exec_file(fname)
517 501 except:
518 502 self.log.warn("Unknown error in handling Global.exec_files:")
519 503 self.shell.showtraceback()
520 504
521 505 def _run_cmd_line_code(self):
522 506 if hasattr(self.master_config.Global, 'code_to_run'):
523 507 line = self.master_config.Global.code_to_run
524 508 try:
525 509 self.log.info("Running code given at command line (-c): %s" % line)
526 510 self.shell.runlines(line)
527 511 except:
528 512 self.log.warn("Error in executing line in user namespace: %s" % line)
529 513 self.shell.showtraceback()
530 514 return
531 515 # Like Python itself, ignore the second if the first of these is present
532 516 try:
533 517 fname = self.extra_args[0]
534 518 except:
535 519 pass
536 520 else:
537 521 try:
538 522 self._exec_file(fname)
539 523 except:
540 524 self.log.warn("Error in executing file in user namespace: %s" % fname)
541 525 self.shell.showtraceback()
542 526
527 def _configure_xmode(self):
528 # XXX - shouldn't this be read from the config? I'm still a little
529 # lost with all the details of handling the new config guys...
530 self.shell.InteractiveTB.set_mode(mode=self.shell.xmode)
531
543 532 def start_app(self):
544 533 if self.master_config.Global.interact:
545 534 self.log.debug("Starting IPython's mainloop...")
546 535 self.shell.mainloop()
547 536
548 537
538
549 539 def load_default_config(ipython_dir=None):
550 540 """Load the default config file from the default ipython_dir.
551 541
552 542 This is useful for embedded shells.
553 543 """
554 544 if ipython_dir is None:
555 545 ipython_dir = get_ipython_dir()
556 546 cl = PyFileConfigLoader(default_config_file_name, ipython_dir)
557 547 config = cl.load_config()
558 548 return config
559 549
560 550
561 551 def launch_new_instance():
562 552 """Create and run a full blown IPython instance"""
563 553 app = IPythonApp()
564 554 app.start()
565 555
@@ -1,2488 +1,2500 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 Main IPython Component
4 4 """
5 5
6 6 #-----------------------------------------------------------------------------
7 7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
8 8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
9 9 # Copyright (C) 2008-2009 The IPython Development Team
10 10 #
11 11 # Distributed under the terms of the BSD License. The full license is in
12 12 # the file COPYING, distributed as part of this software.
13 13 #-----------------------------------------------------------------------------
14 14
15 15 #-----------------------------------------------------------------------------
16 16 # Imports
17 17 #-----------------------------------------------------------------------------
18 18
19 19 from __future__ import with_statement
20 20
21 21 import __builtin__
22 22 import StringIO
23 23 import bdb
24 24 import codeop
25 25 import exceptions
26 26 import new
27 27 import os
28 28 import re
29 29 import string
30 30 import sys
31 31 import tempfile
32 32 from contextlib import nested
33 33
34 from IPython.core import ultratb
35 34 from IPython.core import debugger, oinspect
36 from IPython.core import shadowns
37 35 from IPython.core import history as ipcorehist
38 36 from IPython.core import prefilter
37 from IPython.core import shadowns
38 from IPython.core import ultratb
39 39 from IPython.core.alias import AliasManager
40 40 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.component import Component
41 42 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.error import TryNext, UsageError
42 44 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
43 45 from IPython.core.logger import Logger
44 46 from IPython.core.magic import Magic
45 from IPython.core.prompts import CachedOutput
46 47 from IPython.core.prefilter import PrefilterManager
47 from IPython.core.component import Component
48 from IPython.core.prompts import CachedOutput
49 from IPython.core.pylabtools import pylab_activate
48 50 from IPython.core.usage import interactive_usage, default_banner
49 from IPython.core.error import TryNext, UsageError
50
51 from IPython.utils import pickleshare
52 51 from IPython.external.Itpl import ItplNS
52 from IPython.lib.inputhook import enable_gui
53 53 from IPython.lib.backgroundjobs import BackgroundJobManager
54 from IPython.utils.ipstruct import Struct
55 54 from IPython.utils import PyColorize
56 from IPython.utils.genutils import *
55 from IPython.utils import pickleshare
57 56 from IPython.utils.genutils import get_ipython_dir
57 from IPython.utils.ipstruct import Struct
58 58 from IPython.utils.platutils import toggle_set_term_title, set_term_title
59 59 from IPython.utils.strdispatch import StrDispatch
60 60 from IPython.utils.syspathcontext import prepended_to_syspath
61 61
62 # XXX - need to clean up this import * line
63 from IPython.utils.genutils import *
64
62 65 # from IPython.utils import growl
63 66 # growl.start("IPython")
64 67
65 68 from IPython.utils.traitlets import (
66 69 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode
67 70 )
68 71
69 72 #-----------------------------------------------------------------------------
70 73 # Globals
71 74 #-----------------------------------------------------------------------------
72 75
73
74 76 # store the builtin raw_input globally, and use this always, in case user code
75 77 # overwrites it (like wx.py.PyShell does)
76 78 raw_input_original = raw_input
77 79
78 80 # compiled regexps for autoindent management
79 81 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
80 82
81
82 83 #-----------------------------------------------------------------------------
83 84 # Utilities
84 85 #-----------------------------------------------------------------------------
85 86
86
87 87 ini_spaces_re = re.compile(r'^(\s+)')
88 88
89 89
90 90 def num_ini_spaces(strng):
91 91 """Return the number of initial spaces in a string"""
92 92
93 93 ini_spaces = ini_spaces_re.match(strng)
94 94 if ini_spaces:
95 95 return ini_spaces.end()
96 96 else:
97 97 return 0
98 98
99 99
100 100 def softspace(file, newvalue):
101 101 """Copied from code.py, to remove the dependency"""
102 102
103 103 oldvalue = 0
104 104 try:
105 105 oldvalue = file.softspace
106 106 except AttributeError:
107 107 pass
108 108 try:
109 109 file.softspace = newvalue
110 110 except (AttributeError, TypeError):
111 111 # "attribute-less object" or "read-only attributes"
112 112 pass
113 113 return oldvalue
114 114
115 115
116 116 class SpaceInInput(exceptions.Exception): pass
117 117
118 118 class Bunch: pass
119 119
120 120 class InputList(list):
121 121 """Class to store user input.
122 122
123 123 It's basically a list, but slices return a string instead of a list, thus
124 124 allowing things like (assuming 'In' is an instance):
125 125
126 126 exec In[4:7]
127 127
128 128 or
129 129
130 130 exec In[5:9] + In[14] + In[21:25]"""
131 131
132 132 def __getslice__(self,i,j):
133 133 return ''.join(list.__getslice__(self,i,j))
134 134
135 135
136 136 class SyntaxTB(ultratb.ListTB):
137 137 """Extension which holds some state: the last exception value"""
138 138
139 139 def __init__(self,color_scheme = 'NoColor'):
140 140 ultratb.ListTB.__init__(self,color_scheme)
141 141 self.last_syntax_error = None
142 142
143 143 def __call__(self, etype, value, elist):
144 144 self.last_syntax_error = value
145 145 ultratb.ListTB.__call__(self,etype,value,elist)
146 146
147 147 def clear_err_state(self):
148 148 """Return the current error state and clear it"""
149 149 e = self.last_syntax_error
150 150 self.last_syntax_error = None
151 151 return e
152 152
153 153
154 154 def get_default_editor():
155 155 try:
156 156 ed = os.environ['EDITOR']
157 157 except KeyError:
158 158 if os.name == 'posix':
159 159 ed = 'vi' # the only one guaranteed to be there!
160 160 else:
161 161 ed = 'notepad' # same in Windows!
162 162 return ed
163 163
164 164
165 165 def get_default_colors():
166 166 if sys.platform=='darwin':
167 167 return "LightBG"
168 168 elif os.name=='nt':
169 169 return 'Linux'
170 170 else:
171 171 return 'Linux'
172 172
173 173
174 174 class SeparateStr(Str):
175 175 """A Str subclass to validate separate_in, separate_out, etc.
176 176
177 177 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
178 178 """
179 179
180 180 def validate(self, obj, value):
181 181 if value == '0': value = ''
182 182 value = value.replace('\\n','\n')
183 183 return super(SeparateStr, self).validate(obj, value)
184 184
185 185
186 186 #-----------------------------------------------------------------------------
187 187 # Main IPython class
188 188 #-----------------------------------------------------------------------------
189 189
190 190
191 191 class InteractiveShell(Component, Magic):
192 192 """An enhanced, interactive shell for Python."""
193 193
194 194 autocall = Enum((0,1,2), default_value=1, config=True)
195 195 autoedit_syntax = CBool(False, config=True)
196 196 autoindent = CBool(True, config=True)
197 197 automagic = CBool(True, config=True)
198 198 banner = Str('')
199 199 banner1 = Str(default_banner, config=True)
200 200 banner2 = Str('', config=True)
201 201 cache_size = Int(1000, config=True)
202 202 color_info = CBool(True, config=True)
203 203 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
204 204 default_value=get_default_colors(), config=True)
205 205 confirm_exit = CBool(True, config=True)
206 206 debug = CBool(False, config=True)
207 207 deep_reload = CBool(False, config=True)
208 208 # This display_banner only controls whether or not self.show_banner()
209 209 # is called when mainloop/interact are called. The default is False
210 210 # because for the terminal based application, the banner behavior
211 211 # is controlled by Global.display_banner, which IPythonApp looks at
212 212 # to determine if *it* should call show_banner() by hand or not.
213 213 display_banner = CBool(False) # This isn't configurable!
214 214 embedded = CBool(False)
215 215 embedded_active = CBool(False)
216 216 editor = Str(get_default_editor(), config=True)
217 217 filename = Str("<ipython console>")
218 218 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
219 219 logstart = CBool(False, config=True)
220 220 logfile = Str('', config=True)
221 221 logappend = Str('', config=True)
222 222 object_info_string_level = Enum((0,1,2), default_value=0,
223 223 config=True)
224 224 pager = Str('less', config=True)
225 225 pdb = CBool(False, config=True)
226 226 pprint = CBool(True, config=True)
227 227 profile = Str('', config=True)
228 228 prompt_in1 = Str('In [\\#]: ', config=True)
229 229 prompt_in2 = Str(' .\\D.: ', config=True)
230 230 prompt_out = Str('Out[\\#]: ', config=True)
231 231 prompts_pad_left = CBool(True, config=True)
232 232 quiet = CBool(False, config=True)
233 233
234 234 readline_use = CBool(True, config=True)
235 235 readline_merge_completions = CBool(True, config=True)
236 236 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
237 237 readline_remove_delims = Str('-/~', config=True)
238 238 readline_parse_and_bind = List([
239 239 'tab: complete',
240 240 '"\C-l": possible-completions',
241 241 'set show-all-if-ambiguous on',
242 242 '"\C-o": tab-insert',
243 243 '"\M-i": " "',
244 244 '"\M-o": "\d\d\d\d"',
245 245 '"\M-I": "\d\d\d\d"',
246 246 '"\C-r": reverse-search-history',
247 247 '"\C-s": forward-search-history',
248 248 '"\C-p": history-search-backward',
249 249 '"\C-n": history-search-forward',
250 250 '"\e[A": history-search-backward',
251 251 '"\e[B": history-search-forward',
252 252 '"\C-k": kill-line',
253 253 '"\C-u": unix-line-discard',
254 254 ], allow_none=False, config=True)
255 255
256 256 screen_length = Int(0, config=True)
257 257
258 258 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
259 259 separate_in = SeparateStr('\n', config=True)
260 260 separate_out = SeparateStr('', config=True)
261 261 separate_out2 = SeparateStr('', config=True)
262 262
263 263 system_header = Str('IPython system call: ', config=True)
264 264 system_verbose = CBool(False, config=True)
265 265 term_title = CBool(False, config=True)
266 266 wildcards_case_sensitive = CBool(True, config=True)
267 267 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
268 268 default_value='Context', config=True)
269 269
270 270 autoexec = List(allow_none=False)
271 271
272 272 # class attribute to indicate whether the class supports threads or not.
273 273 # Subclasses with thread support should override this as needed.
274 274 isthreaded = False
275 275
276 276 def __init__(self, parent=None, config=None, ipython_dir=None, usage=None,
277 277 user_ns=None, user_global_ns=None,
278 278 banner1=None, banner2=None, display_banner=None,
279 279 custom_exceptions=((),None)):
280 280
281 281 # This is where traitlets with a config_key argument are updated
282 282 # from the values on config.
283 283 super(InteractiveShell, self).__init__(parent, config=config)
284 284
285 285 # These are relatively independent and stateless
286 286 self.init_ipython_dir(ipython_dir)
287 287 self.init_instance_attrs()
288 288 self.init_term_title()
289 289 self.init_usage(usage)
290 290 self.init_banner(banner1, banner2, display_banner)
291 291
292 292 # Create namespaces (user_ns, user_global_ns, etc.)
293 293 self.init_create_namespaces(user_ns, user_global_ns)
294 294 # This has to be done after init_create_namespaces because it uses
295 295 # something in self.user_ns, but before init_sys_modules, which
296 296 # is the first thing to modify sys.
297 297 self.save_sys_module_state()
298 298 self.init_sys_modules()
299 299
300 300 self.init_history()
301 301 self.init_encoding()
302 302 self.init_prefilter()
303 303
304 304 Magic.__init__(self, self)
305 305
306 306 self.init_syntax_highlighting()
307 307 self.init_hooks()
308 308 self.init_pushd_popd_magic()
309 309 self.init_traceback_handlers(custom_exceptions)
310 310 self.init_user_ns()
311 311 self.init_logger()
312 312 self.init_alias()
313 313 self.init_builtins()
314 314
315 315 # pre_config_initialization
316 316 self.init_shadow_hist()
317 317
318 318 # The next section should contain averything that was in ipmaker.
319 319 self.init_logstart()
320 320
321 321 # The following was in post_config_initialization
322 322 self.init_inspector()
323 323 self.init_readline()
324 324 self.init_prompts()
325 325 self.init_displayhook()
326 326 self.init_reload_doctest()
327 327 self.init_magics()
328 328 self.init_pdb()
329 329 self.hooks.late_startup_hook()
330 330
331 331 def get_ipython(self):
332 332 return self
333 333
334 334 #-------------------------------------------------------------------------
335 335 # Traitlet changed handlers
336 336 #-------------------------------------------------------------------------
337 337
338 338 def _banner1_changed(self):
339 339 self.compute_banner()
340 340
341 341 def _banner2_changed(self):
342 342 self.compute_banner()
343 343
344 344 def _ipython_dir_changed(self, name, new):
345 345 if not os.path.isdir(new):
346 346 os.makedirs(new, mode = 0777)
347 347 if not os.path.isdir(self.ipython_extension_dir):
348 348 os.makedirs(self.ipython_extension_dir, mode = 0777)
349 349
350 350 @property
351 351 def ipython_extension_dir(self):
352 352 return os.path.join(self.ipython_dir, 'extensions')
353 353
354 354 @property
355 355 def usable_screen_length(self):
356 356 if self.screen_length == 0:
357 357 return 0
358 358 else:
359 359 num_lines_bot = self.separate_in.count('\n')+1
360 360 return self.screen_length - num_lines_bot
361 361
362 362 def _term_title_changed(self, name, new_value):
363 363 self.init_term_title()
364 364
365 365 def set_autoindent(self,value=None):
366 366 """Set the autoindent flag, checking for readline support.
367 367
368 368 If called with no arguments, it acts as a toggle."""
369 369
370 370 if not self.has_readline:
371 371 if os.name == 'posix':
372 372 warn("The auto-indent feature requires the readline library")
373 373 self.autoindent = 0
374 374 return
375 375 if value is None:
376 376 self.autoindent = not self.autoindent
377 377 else:
378 378 self.autoindent = value
379 379
380 380 #-------------------------------------------------------------------------
381 381 # init_* methods called by __init__
382 382 #-------------------------------------------------------------------------
383 383
384 384 def init_ipython_dir(self, ipython_dir):
385 385 if ipython_dir is not None:
386 386 self.ipython_dir = ipython_dir
387 387 self.config.Global.ipython_dir = self.ipython_dir
388 388 return
389 389
390 390 if hasattr(self.config.Global, 'ipython_dir'):
391 391 self.ipython_dir = self.config.Global.ipython_dir
392 392 else:
393 393 self.ipython_dir = get_ipython_dir()
394 394
395 395 # All children can just read this
396 396 self.config.Global.ipython_dir = self.ipython_dir
397 397
398 398 def init_instance_attrs(self):
399 399 self.jobs = BackgroundJobManager()
400 400 self.more = False
401 401
402 402 # command compiler
403 403 self.compile = codeop.CommandCompiler()
404 404
405 405 # User input buffer
406 406 self.buffer = []
407 407
408 408 # Make an empty namespace, which extension writers can rely on both
409 409 # existing and NEVER being used by ipython itself. This gives them a
410 410 # convenient location for storing additional information and state
411 411 # their extensions may require, without fear of collisions with other
412 412 # ipython names that may develop later.
413 413 self.meta = Struct()
414 414
415 415 # Object variable to store code object waiting execution. This is
416 416 # used mainly by the multithreaded shells, but it can come in handy in
417 417 # other situations. No need to use a Queue here, since it's a single
418 418 # item which gets cleared once run.
419 419 self.code_to_run = None
420 420
421 421 # Flag to mark unconditional exit
422 422 self.exit_now = False
423 423
424 424 # Temporary files used for various purposes. Deleted at exit.
425 425 self.tempfiles = []
426 426
427 427 # Keep track of readline usage (later set by init_readline)
428 428 self.has_readline = False
429 429
430 430 # keep track of where we started running (mainly for crash post-mortem)
431 431 # This is not being used anywhere currently.
432 432 self.starting_dir = os.getcwd()
433 433
434 434 # Indentation management
435 435 self.indent_current_nsp = 0
436 436
437 437 def init_term_title(self):
438 438 # Enable or disable the terminal title.
439 439 if self.term_title:
440 440 toggle_set_term_title(True)
441 441 set_term_title('IPython: ' + abbrev_cwd())
442 442 else:
443 443 toggle_set_term_title(False)
444 444
445 445 def init_usage(self, usage=None):
446 446 if usage is None:
447 447 self.usage = interactive_usage
448 448 else:
449 449 self.usage = usage
450 450
451 451 def init_encoding(self):
452 452 # Get system encoding at startup time. Certain terminals (like Emacs
453 453 # under Win32 have it set to None, and we need to have a known valid
454 454 # encoding to use in the raw_input() method
455 455 try:
456 456 self.stdin_encoding = sys.stdin.encoding or 'ascii'
457 457 except AttributeError:
458 458 self.stdin_encoding = 'ascii'
459 459
460 460 def init_syntax_highlighting(self):
461 461 # Python source parser/formatter for syntax highlighting
462 462 pyformat = PyColorize.Parser().format
463 463 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
464 464
465 465 def init_pushd_popd_magic(self):
466 466 # for pushd/popd management
467 467 try:
468 468 self.home_dir = get_home_dir()
469 469 except HomeDirError, msg:
470 470 fatal(msg)
471 471
472 472 self.dir_stack = []
473 473
474 474 def init_logger(self):
475 475 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
476 476 # local shortcut, this is used a LOT
477 477 self.log = self.logger.log
478 478
479 479 def init_logstart(self):
480 480 if self.logappend:
481 481 self.magic_logstart(self.logappend + ' append')
482 482 elif self.logfile:
483 483 self.magic_logstart(self.logfile)
484 484 elif self.logstart:
485 485 self.magic_logstart()
486 486
487 487 def init_builtins(self):
488 488 self.builtin_trap = BuiltinTrap(self)
489 489
490 490 def init_inspector(self):
491 491 # Object inspector
492 492 self.inspector = oinspect.Inspector(oinspect.InspectColors,
493 493 PyColorize.ANSICodeColors,
494 494 'NoColor',
495 495 self.object_info_string_level)
496 496
497 497 def init_prompts(self):
498 498 # Initialize cache, set in/out prompts and printing system
499 499 self.outputcache = CachedOutput(self,
500 500 self.cache_size,
501 501 self.pprint,
502 502 input_sep = self.separate_in,
503 503 output_sep = self.separate_out,
504 504 output_sep2 = self.separate_out2,
505 505 ps1 = self.prompt_in1,
506 506 ps2 = self.prompt_in2,
507 507 ps_out = self.prompt_out,
508 508 pad_left = self.prompts_pad_left)
509 509
510 510 # user may have over-ridden the default print hook:
511 511 try:
512 512 self.outputcache.__class__.display = self.hooks.display
513 513 except AttributeError:
514 514 pass
515 515
516 516 def init_displayhook(self):
517 517 self.display_trap = DisplayTrap(self, self.outputcache)
518 518
519 519 def init_reload_doctest(self):
520 520 # Do a proper resetting of doctest, including the necessary displayhook
521 521 # monkeypatching
522 522 try:
523 523 doctest_reload()
524 524 except ImportError:
525 525 warn("doctest module does not exist.")
526 526
527 527 #-------------------------------------------------------------------------
528 528 # Things related to the banner
529 529 #-------------------------------------------------------------------------
530 530
531 531 def init_banner(self, banner1, banner2, display_banner):
532 532 if banner1 is not None:
533 533 self.banner1 = banner1
534 534 if banner2 is not None:
535 535 self.banner2 = banner2
536 536 if display_banner is not None:
537 537 self.display_banner = display_banner
538 538 self.compute_banner()
539 539
540 540 def show_banner(self, banner=None):
541 541 if banner is None:
542 542 banner = self.banner
543 543 self.write(banner)
544 544
545 545 def compute_banner(self):
546 546 self.banner = self.banner1 + '\n'
547 547 if self.profile:
548 548 self.banner += '\nIPython profile: %s\n' % self.profile
549 549 if self.banner2:
550 550 self.banner += '\n' + self.banner2 + '\n'
551 551
552 552 #-------------------------------------------------------------------------
553 553 # Things related to injections into the sys module
554 554 #-------------------------------------------------------------------------
555 555
556 556 def save_sys_module_state(self):
557 557 """Save the state of hooks in the sys module.
558 558
559 559 This has to be called after self.user_ns is created.
560 560 """
561 561 self._orig_sys_module_state = {}
562 562 self._orig_sys_module_state['stdin'] = sys.stdin
563 563 self._orig_sys_module_state['stdout'] = sys.stdout
564 564 self._orig_sys_module_state['stderr'] = sys.stderr
565 565 self._orig_sys_module_state['excepthook'] = sys.excepthook
566 566 try:
567 567 self._orig_sys_modules_main_name = self.user_ns['__name__']
568 568 except KeyError:
569 569 pass
570 570
571 571 def restore_sys_module_state(self):
572 572 """Restore the state of the sys module."""
573 573 try:
574 574 for k, v in self._orig_sys_module_state.items():
575 575 setattr(sys, k, v)
576 576 except AttributeError:
577 577 pass
578 578 try:
579 579 delattr(sys, 'ipcompleter')
580 580 except AttributeError:
581 581 pass
582 582 # Reset what what done in self.init_sys_modules
583 583 try:
584 584 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
585 585 except (AttributeError, KeyError):
586 586 pass
587 587
588 588 #-------------------------------------------------------------------------
589 589 # Things related to hooks
590 590 #-------------------------------------------------------------------------
591 591
592 592 def init_hooks(self):
593 593 # hooks holds pointers used for user-side customizations
594 594 self.hooks = Struct()
595 595
596 596 self.strdispatchers = {}
597 597
598 598 # Set all default hooks, defined in the IPython.hooks module.
599 599 import IPython.core.hooks
600 600 hooks = IPython.core.hooks
601 601 for hook_name in hooks.__all__:
602 602 # default hooks have priority 100, i.e. low; user hooks should have
603 603 # 0-100 priority
604 604 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
605 605
606 606 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
607 607 """set_hook(name,hook) -> sets an internal IPython hook.
608 608
609 609 IPython exposes some of its internal API as user-modifiable hooks. By
610 610 adding your function to one of these hooks, you can modify IPython's
611 611 behavior to call at runtime your own routines."""
612 612
613 613 # At some point in the future, this should validate the hook before it
614 614 # accepts it. Probably at least check that the hook takes the number
615 615 # of args it's supposed to.
616 616
617 617 f = new.instancemethod(hook,self,self.__class__)
618 618
619 619 # check if the hook is for strdispatcher first
620 620 if str_key is not None:
621 621 sdp = self.strdispatchers.get(name, StrDispatch())
622 622 sdp.add_s(str_key, f, priority )
623 623 self.strdispatchers[name] = sdp
624 624 return
625 625 if re_key is not None:
626 626 sdp = self.strdispatchers.get(name, StrDispatch())
627 627 sdp.add_re(re.compile(re_key), f, priority )
628 628 self.strdispatchers[name] = sdp
629 629 return
630 630
631 631 dp = getattr(self.hooks, name, None)
632 632 if name not in IPython.core.hooks.__all__:
633 633 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
634 634 if not dp:
635 635 dp = IPython.core.hooks.CommandChainDispatcher()
636 636
637 637 try:
638 638 dp.add(f,priority)
639 639 except AttributeError:
640 640 # it was not commandchain, plain old func - replace
641 641 dp = f
642 642
643 643 setattr(self.hooks,name, dp)
644 644
645 645 #-------------------------------------------------------------------------
646 646 # Things related to the "main" module
647 647 #-------------------------------------------------------------------------
648 648
649 649 def new_main_mod(self,ns=None):
650 650 """Return a new 'main' module object for user code execution.
651 651 """
652 652 main_mod = self._user_main_module
653 653 init_fakemod_dict(main_mod,ns)
654 654 return main_mod
655 655
656 656 def cache_main_mod(self,ns,fname):
657 657 """Cache a main module's namespace.
658 658
659 659 When scripts are executed via %run, we must keep a reference to the
660 660 namespace of their __main__ module (a FakeModule instance) around so
661 661 that Python doesn't clear it, rendering objects defined therein
662 662 useless.
663 663
664 664 This method keeps said reference in a private dict, keyed by the
665 665 absolute path of the module object (which corresponds to the script
666 666 path). This way, for multiple executions of the same script we only
667 667 keep one copy of the namespace (the last one), thus preventing memory
668 668 leaks from old references while allowing the objects from the last
669 669 execution to be accessible.
670 670
671 671 Note: we can not allow the actual FakeModule instances to be deleted,
672 672 because of how Python tears down modules (it hard-sets all their
673 673 references to None without regard for reference counts). This method
674 674 must therefore make a *copy* of the given namespace, to allow the
675 675 original module's __dict__ to be cleared and reused.
676 676
677 677
678 678 Parameters
679 679 ----------
680 680 ns : a namespace (a dict, typically)
681 681
682 682 fname : str
683 683 Filename associated with the namespace.
684 684
685 685 Examples
686 686 --------
687 687
688 688 In [10]: import IPython
689 689
690 690 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
691 691
692 692 In [12]: IPython.__file__ in _ip._main_ns_cache
693 693 Out[12]: True
694 694 """
695 695 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
696 696
697 697 def clear_main_mod_cache(self):
698 698 """Clear the cache of main modules.
699 699
700 700 Mainly for use by utilities like %reset.
701 701
702 702 Examples
703 703 --------
704 704
705 705 In [15]: import IPython
706 706
707 707 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
708 708
709 709 In [17]: len(_ip._main_ns_cache) > 0
710 710 Out[17]: True
711 711
712 712 In [18]: _ip.clear_main_mod_cache()
713 713
714 714 In [19]: len(_ip._main_ns_cache) == 0
715 715 Out[19]: True
716 716 """
717 717 self._main_ns_cache.clear()
718 718
719 719 #-------------------------------------------------------------------------
720 720 # Things related to debugging
721 721 #-------------------------------------------------------------------------
722 722
723 723 def init_pdb(self):
724 724 # Set calling of pdb on exceptions
725 725 # self.call_pdb is a property
726 726 self.call_pdb = self.pdb
727 727
728 728 def _get_call_pdb(self):
729 729 return self._call_pdb
730 730
731 731 def _set_call_pdb(self,val):
732 732
733 733 if val not in (0,1,False,True):
734 734 raise ValueError,'new call_pdb value must be boolean'
735 735
736 736 # store value in instance
737 737 self._call_pdb = val
738 738
739 739 # notify the actual exception handlers
740 740 self.InteractiveTB.call_pdb = val
741 741 if self.isthreaded:
742 742 try:
743 743 self.sys_excepthook.call_pdb = val
744 744 except:
745 745 warn('Failed to activate pdb for threaded exception handler')
746 746
747 747 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
748 748 'Control auto-activation of pdb at exceptions')
749 749
750 750 def debugger(self,force=False):
751 751 """Call the pydb/pdb debugger.
752 752
753 753 Keywords:
754 754
755 755 - force(False): by default, this routine checks the instance call_pdb
756 756 flag and does not actually invoke the debugger if the flag is false.
757 757 The 'force' option forces the debugger to activate even if the flag
758 758 is false.
759 759 """
760 760
761 761 if not (force or self.call_pdb):
762 762 return
763 763
764 764 if not hasattr(sys,'last_traceback'):
765 765 error('No traceback has been produced, nothing to debug.')
766 766 return
767 767
768 768 # use pydb if available
769 769 if debugger.has_pydb:
770 770 from pydb import pm
771 771 else:
772 772 # fallback to our internal debugger
773 773 pm = lambda : self.InteractiveTB.debugger(force=True)
774 774 self.history_saving_wrapper(pm)()
775 775
776 776 #-------------------------------------------------------------------------
777 777 # Things related to IPython's various namespaces
778 778 #-------------------------------------------------------------------------
779 779
780 780 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
781 781 # Create the namespace where the user will operate. user_ns is
782 782 # normally the only one used, and it is passed to the exec calls as
783 783 # the locals argument. But we do carry a user_global_ns namespace
784 784 # given as the exec 'globals' argument, This is useful in embedding
785 785 # situations where the ipython shell opens in a context where the
786 786 # distinction between locals and globals is meaningful. For
787 787 # non-embedded contexts, it is just the same object as the user_ns dict.
788 788
789 789 # FIXME. For some strange reason, __builtins__ is showing up at user
790 790 # level as a dict instead of a module. This is a manual fix, but I
791 791 # should really track down where the problem is coming from. Alex
792 792 # Schmolck reported this problem first.
793 793
794 794 # A useful post by Alex Martelli on this topic:
795 795 # Re: inconsistent value from __builtins__
796 796 # Von: Alex Martelli <aleaxit@yahoo.com>
797 797 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
798 798 # Gruppen: comp.lang.python
799 799
800 800 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
801 801 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
802 802 # > <type 'dict'>
803 803 # > >>> print type(__builtins__)
804 804 # > <type 'module'>
805 805 # > Is this difference in return value intentional?
806 806
807 807 # Well, it's documented that '__builtins__' can be either a dictionary
808 808 # or a module, and it's been that way for a long time. Whether it's
809 809 # intentional (or sensible), I don't know. In any case, the idea is
810 810 # that if you need to access the built-in namespace directly, you
811 811 # should start with "import __builtin__" (note, no 's') which will
812 812 # definitely give you a module. Yeah, it's somewhat confusing:-(.
813 813
814 814 # These routines return properly built dicts as needed by the rest of
815 815 # the code, and can also be used by extension writers to generate
816 816 # properly initialized namespaces.
817 817 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
818 818 user_global_ns)
819 819
820 820 # Assign namespaces
821 821 # This is the namespace where all normal user variables live
822 822 self.user_ns = user_ns
823 823 self.user_global_ns = user_global_ns
824 824
825 825 # An auxiliary namespace that checks what parts of the user_ns were
826 826 # loaded at startup, so we can list later only variables defined in
827 827 # actual interactive use. Since it is always a subset of user_ns, it
828 828 # doesn't need to be seaparately tracked in the ns_table
829 829 self.user_config_ns = {}
830 830
831 831 # A namespace to keep track of internal data structures to prevent
832 832 # them from cluttering user-visible stuff. Will be updated later
833 833 self.internal_ns = {}
834 834
835 835 # Now that FakeModule produces a real module, we've run into a nasty
836 836 # problem: after script execution (via %run), the module where the user
837 837 # code ran is deleted. Now that this object is a true module (needed
838 838 # so docetst and other tools work correctly), the Python module
839 839 # teardown mechanism runs over it, and sets to None every variable
840 840 # present in that module. Top-level references to objects from the
841 841 # script survive, because the user_ns is updated with them. However,
842 842 # calling functions defined in the script that use other things from
843 843 # the script will fail, because the function's closure had references
844 844 # to the original objects, which are now all None. So we must protect
845 845 # these modules from deletion by keeping a cache.
846 846 #
847 847 # To avoid keeping stale modules around (we only need the one from the
848 848 # last run), we use a dict keyed with the full path to the script, so
849 849 # only the last version of the module is held in the cache. Note,
850 850 # however, that we must cache the module *namespace contents* (their
851 851 # __dict__). Because if we try to cache the actual modules, old ones
852 852 # (uncached) could be destroyed while still holding references (such as
853 853 # those held by GUI objects that tend to be long-lived)>
854 854 #
855 855 # The %reset command will flush this cache. See the cache_main_mod()
856 856 # and clear_main_mod_cache() methods for details on use.
857 857
858 858 # This is the cache used for 'main' namespaces
859 859 self._main_ns_cache = {}
860 860 # And this is the single instance of FakeModule whose __dict__ we keep
861 861 # copying and clearing for reuse on each %run
862 862 self._user_main_module = FakeModule()
863 863
864 864 # A table holding all the namespaces IPython deals with, so that
865 865 # introspection facilities can search easily.
866 866 self.ns_table = {'user':user_ns,
867 867 'user_global':user_global_ns,
868 868 'internal':self.internal_ns,
869 869 'builtin':__builtin__.__dict__
870 870 }
871 871
872 872 # Similarly, track all namespaces where references can be held and that
873 873 # we can safely clear (so it can NOT include builtin). This one can be
874 874 # a simple list.
875 875 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
876 876 self.internal_ns, self._main_ns_cache ]
877 877
878 878 def init_sys_modules(self):
879 879 # We need to insert into sys.modules something that looks like a
880 880 # module but which accesses the IPython namespace, for shelve and
881 881 # pickle to work interactively. Normally they rely on getting
882 882 # everything out of __main__, but for embedding purposes each IPython
883 883 # instance has its own private namespace, so we can't go shoving
884 884 # everything into __main__.
885 885
886 886 # note, however, that we should only do this for non-embedded
887 887 # ipythons, which really mimic the __main__.__dict__ with their own
888 888 # namespace. Embedded instances, on the other hand, should not do
889 889 # this because they need to manage the user local/global namespaces
890 890 # only, but they live within a 'normal' __main__ (meaning, they
891 891 # shouldn't overtake the execution environment of the script they're
892 892 # embedded in).
893 893
894 894 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
895 895
896 896 try:
897 897 main_name = self.user_ns['__name__']
898 898 except KeyError:
899 899 raise KeyError('user_ns dictionary MUST have a "__name__" key')
900 900 else:
901 901 sys.modules[main_name] = FakeModule(self.user_ns)
902 902
903 903 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
904 904 """Return a valid local and global user interactive namespaces.
905 905
906 906 This builds a dict with the minimal information needed to operate as a
907 907 valid IPython user namespace, which you can pass to the various
908 908 embedding classes in ipython. The default implementation returns the
909 909 same dict for both the locals and the globals to allow functions to
910 910 refer to variables in the namespace. Customized implementations can
911 911 return different dicts. The locals dictionary can actually be anything
912 912 following the basic mapping protocol of a dict, but the globals dict
913 913 must be a true dict, not even a subclass. It is recommended that any
914 914 custom object for the locals namespace synchronize with the globals
915 915 dict somehow.
916 916
917 917 Raises TypeError if the provided globals namespace is not a true dict.
918 918
919 919 :Parameters:
920 920 user_ns : dict-like, optional
921 921 The current user namespace. The items in this namespace should
922 922 be included in the output. If None, an appropriate blank
923 923 namespace should be created.
924 924 user_global_ns : dict, optional
925 925 The current user global namespace. The items in this namespace
926 926 should be included in the output. If None, an appropriate
927 927 blank namespace should be created.
928 928
929 929 :Returns:
930 930 A tuple pair of dictionary-like object to be used as the local namespace
931 931 of the interpreter and a dict to be used as the global namespace.
932 932 """
933 933
934 934 if user_ns is None:
935 935 # Set __name__ to __main__ to better match the behavior of the
936 936 # normal interpreter.
937 937 user_ns = {'__name__' :'__main__',
938 938 '__builtins__' : __builtin__,
939 939 }
940 940 else:
941 941 user_ns.setdefault('__name__','__main__')
942 942 user_ns.setdefault('__builtins__',__builtin__)
943 943
944 944 if user_global_ns is None:
945 945 user_global_ns = user_ns
946 946 if type(user_global_ns) is not dict:
947 947 raise TypeError("user_global_ns must be a true dict; got %r"
948 948 % type(user_global_ns))
949 949
950 950 return user_ns, user_global_ns
951 951
952 952 def init_user_ns(self):
953 953 """Initialize all user-visible namespaces to their minimum defaults.
954 954
955 955 Certain history lists are also initialized here, as they effectively
956 956 act as user namespaces.
957 957
958 958 Notes
959 959 -----
960 960 All data structures here are only filled in, they are NOT reset by this
961 961 method. If they were not empty before, data will simply be added to
962 962 therm.
963 963 """
964 964 # Store myself as the public api!!!
965 965 self.user_ns['get_ipython'] = self.get_ipython
966 966
967 967 # make global variables for user access to the histories
968 968 self.user_ns['_ih'] = self.input_hist
969 969 self.user_ns['_oh'] = self.output_hist
970 970 self.user_ns['_dh'] = self.dir_hist
971 971
972 972 # user aliases to input and output histories
973 973 self.user_ns['In'] = self.input_hist
974 974 self.user_ns['Out'] = self.output_hist
975 975
976 976 self.user_ns['_sh'] = shadowns
977 977
978 978 # Put 'help' in the user namespace
979 979 try:
980 980 from site import _Helper
981 981 self.user_ns['help'] = _Helper()
982 982 except ImportError:
983 983 warn('help() not available - check site.py')
984 984
985 985 def reset(self):
986 986 """Clear all internal namespaces.
987 987
988 988 Note that this is much more aggressive than %reset, since it clears
989 989 fully all namespaces, as well as all input/output lists.
990 990 """
991 991 for ns in self.ns_refs_table:
992 992 ns.clear()
993 993
994 994 self.alias_manager.clear_aliases()
995 995
996 996 # Clear input and output histories
997 997 self.input_hist[:] = []
998 998 self.input_hist_raw[:] = []
999 999 self.output_hist.clear()
1000 1000
1001 1001 # Restore the user namespaces to minimal usability
1002 1002 self.init_user_ns()
1003 1003
1004 1004 # Restore the default and user aliases
1005 1005 self.alias_manager.init_aliases()
1006 1006
1007 1007 def push(self, variables, interactive=True):
1008 1008 """Inject a group of variables into the IPython user namespace.
1009 1009
1010 1010 Parameters
1011 1011 ----------
1012 1012 variables : dict, str or list/tuple of str
1013 1013 The variables to inject into the user's namespace. If a dict,
1014 1014 a simple update is done. If a str, the string is assumed to
1015 1015 have variable names separated by spaces. A list/tuple of str
1016 1016 can also be used to give the variable names. If just the variable
1017 1017 names are give (list/tuple/str) then the variable values looked
1018 1018 up in the callers frame.
1019 1019 interactive : bool
1020 1020 If True (default), the variables will be listed with the ``who``
1021 1021 magic.
1022 1022 """
1023 1023 vdict = None
1024 1024
1025 1025 # We need a dict of name/value pairs to do namespace updates.
1026 1026 if isinstance(variables, dict):
1027 1027 vdict = variables
1028 1028 elif isinstance(variables, (basestring, list, tuple)):
1029 1029 if isinstance(variables, basestring):
1030 1030 vlist = variables.split()
1031 1031 else:
1032 1032 vlist = variables
1033 1033 vdict = {}
1034 1034 cf = sys._getframe(1)
1035 1035 for name in vlist:
1036 1036 try:
1037 1037 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1038 1038 except:
1039 1039 print ('Could not get variable %s from %s' %
1040 1040 (name,cf.f_code.co_name))
1041 1041 else:
1042 1042 raise ValueError('variables must be a dict/str/list/tuple')
1043 1043
1044 1044 # Propagate variables to user namespace
1045 1045 self.user_ns.update(vdict)
1046 1046
1047 1047 # And configure interactive visibility
1048 1048 config_ns = self.user_config_ns
1049 1049 if interactive:
1050 1050 for name, val in vdict.iteritems():
1051 1051 config_ns.pop(name, None)
1052 1052 else:
1053 1053 for name,val in vdict.iteritems():
1054 1054 config_ns[name] = val
1055 1055
1056 1056 #-------------------------------------------------------------------------
1057 1057 # Things related to history management
1058 1058 #-------------------------------------------------------------------------
1059 1059
1060 1060 def init_history(self):
1061 1061 # List of input with multi-line handling.
1062 1062 self.input_hist = InputList()
1063 1063 # This one will hold the 'raw' input history, without any
1064 1064 # pre-processing. This will allow users to retrieve the input just as
1065 1065 # it was exactly typed in by the user, with %hist -r.
1066 1066 self.input_hist_raw = InputList()
1067 1067
1068 1068 # list of visited directories
1069 1069 try:
1070 1070 self.dir_hist = [os.getcwd()]
1071 1071 except OSError:
1072 1072 self.dir_hist = []
1073 1073
1074 1074 # dict of output history
1075 1075 self.output_hist = {}
1076 1076
1077 1077 # Now the history file
1078 1078 if self.profile:
1079 1079 histfname = 'history-%s' % self.profile
1080 1080 else:
1081 1081 histfname = 'history'
1082 1082 self.histfile = os.path.join(self.ipython_dir, histfname)
1083 1083
1084 1084 # Fill the history zero entry, user counter starts at 1
1085 1085 self.input_hist.append('\n')
1086 1086 self.input_hist_raw.append('\n')
1087 1087
1088 1088 def init_shadow_hist(self):
1089 1089 try:
1090 1090 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1091 1091 except exceptions.UnicodeDecodeError:
1092 1092 print "Your ipython_dir can't be decoded to unicode!"
1093 1093 print "Please set HOME environment variable to something that"
1094 1094 print r"only has ASCII characters, e.g. c:\home"
1095 1095 print "Now it is", self.ipython_dir
1096 1096 sys.exit()
1097 1097 self.shadowhist = ipcorehist.ShadowHist(self.db)
1098 1098
1099 1099 def savehist(self):
1100 1100 """Save input history to a file (via readline library)."""
1101 1101
1102 1102 if not self.has_readline:
1103 1103 return
1104 1104
1105 1105 try:
1106 1106 self.readline.write_history_file(self.histfile)
1107 1107 except:
1108 1108 print 'Unable to save IPython command history to file: ' + \
1109 1109 `self.histfile`
1110 1110
1111 1111 def reloadhist(self):
1112 1112 """Reload the input history from disk file."""
1113 1113
1114 1114 if self.has_readline:
1115 1115 try:
1116 1116 self.readline.clear_history()
1117 1117 self.readline.read_history_file(self.shell.histfile)
1118 1118 except AttributeError:
1119 1119 pass
1120 1120
1121 1121 def history_saving_wrapper(self, func):
1122 1122 """ Wrap func for readline history saving
1123 1123
1124 1124 Convert func into callable that saves & restores
1125 1125 history around the call """
1126 1126
1127 1127 if not self.has_readline:
1128 1128 return func
1129 1129
1130 1130 def wrapper():
1131 1131 self.savehist()
1132 1132 try:
1133 1133 func()
1134 1134 finally:
1135 1135 readline.read_history_file(self.histfile)
1136 1136 return wrapper
1137 1137
1138 1138 #-------------------------------------------------------------------------
1139 1139 # Things related to exception handling and tracebacks (not debugging)
1140 1140 #-------------------------------------------------------------------------
1141 1141
1142 1142 def init_traceback_handlers(self, custom_exceptions):
1143 1143 # Syntax error handler.
1144 1144 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
1145 1145
1146 1146 # The interactive one is initialized with an offset, meaning we always
1147 1147 # want to remove the topmost item in the traceback, which is our own
1148 1148 # internal code. Valid modes: ['Plain','Context','Verbose']
1149 1149 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1150 1150 color_scheme='NoColor',
1151 1151 tb_offset = 1)
1152 1152
1153 1153 # IPython itself shouldn't crash. This will produce a detailed
1154 1154 # post-mortem if it does. But we only install the crash handler for
1155 1155 # non-threaded shells, the threaded ones use a normal verbose reporter
1156 1156 # and lose the crash handler. This is because exceptions in the main
1157 1157 # thread (such as in GUI code) propagate directly to sys.excepthook,
1158 1158 # and there's no point in printing crash dumps for every user exception.
1159 1159 if self.isthreaded:
1160 1160 ipCrashHandler = ultratb.FormattedTB()
1161 1161 else:
1162 1162 from IPython.core import crashhandler
1163 1163 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
1164 1164 self.set_crash_handler(ipCrashHandler)
1165 1165
1166 1166 # and add any custom exception handlers the user may have specified
1167 1167 self.set_custom_exc(*custom_exceptions)
1168 1168
1169 1169 def set_crash_handler(self, crashHandler):
1170 1170 """Set the IPython crash handler.
1171 1171
1172 1172 This must be a callable with a signature suitable for use as
1173 1173 sys.excepthook."""
1174 1174
1175 1175 # Install the given crash handler as the Python exception hook
1176 1176 sys.excepthook = crashHandler
1177 1177
1178 1178 # The instance will store a pointer to this, so that runtime code
1179 1179 # (such as magics) can access it. This is because during the
1180 1180 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1181 1181 # frameworks).
1182 1182 self.sys_excepthook = sys.excepthook
1183 1183
1184 1184 def set_custom_exc(self,exc_tuple,handler):
1185 1185 """set_custom_exc(exc_tuple,handler)
1186 1186
1187 1187 Set a custom exception handler, which will be called if any of the
1188 1188 exceptions in exc_tuple occur in the mainloop (specifically, in the
1189 1189 runcode() method.
1190 1190
1191 1191 Inputs:
1192 1192
1193 1193 - exc_tuple: a *tuple* of valid exceptions to call the defined
1194 1194 handler for. It is very important that you use a tuple, and NOT A
1195 1195 LIST here, because of the way Python's except statement works. If
1196 1196 you only want to trap a single exception, use a singleton tuple:
1197 1197
1198 1198 exc_tuple == (MyCustomException,)
1199 1199
1200 1200 - handler: this must be defined as a function with the following
1201 1201 basic interface: def my_handler(self,etype,value,tb).
1202 1202
1203 1203 This will be made into an instance method (via new.instancemethod)
1204 1204 of IPython itself, and it will be called if any of the exceptions
1205 1205 listed in the exc_tuple are caught. If the handler is None, an
1206 1206 internal basic one is used, which just prints basic info.
1207 1207
1208 1208 WARNING: by putting in your own exception handler into IPython's main
1209 1209 execution loop, you run a very good chance of nasty crashes. This
1210 1210 facility should only be used if you really know what you are doing."""
1211 1211
1212 1212 assert type(exc_tuple)==type(()) , \
1213 1213 "The custom exceptions must be given AS A TUPLE."
1214 1214
1215 1215 def dummy_handler(self,etype,value,tb):
1216 1216 print '*** Simple custom exception handler ***'
1217 1217 print 'Exception type :',etype
1218 1218 print 'Exception value:',value
1219 1219 print 'Traceback :',tb
1220 1220 print 'Source code :','\n'.join(self.buffer)
1221 1221
1222 1222 if handler is None: handler = dummy_handler
1223 1223
1224 1224 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1225 1225 self.custom_exceptions = exc_tuple
1226 1226
1227 1227 def excepthook(self, etype, value, tb):
1228 1228 """One more defense for GUI apps that call sys.excepthook.
1229 1229
1230 1230 GUI frameworks like wxPython trap exceptions and call
1231 1231 sys.excepthook themselves. I guess this is a feature that
1232 1232 enables them to keep running after exceptions that would
1233 1233 otherwise kill their mainloop. This is a bother for IPython
1234 1234 which excepts to catch all of the program exceptions with a try:
1235 1235 except: statement.
1236 1236
1237 1237 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1238 1238 any app directly invokes sys.excepthook, it will look to the user like
1239 1239 IPython crashed. In order to work around this, we can disable the
1240 1240 CrashHandler and replace it with this excepthook instead, which prints a
1241 1241 regular traceback using our InteractiveTB. In this fashion, apps which
1242 1242 call sys.excepthook will generate a regular-looking exception from
1243 1243 IPython, and the CrashHandler will only be triggered by real IPython
1244 1244 crashes.
1245 1245
1246 1246 This hook should be used sparingly, only in places which are not likely
1247 1247 to be true IPython errors.
1248 1248 """
1249 1249 self.showtraceback((etype,value,tb),tb_offset=0)
1250 1250
1251 1251 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1252 1252 """Display the exception that just occurred.
1253 1253
1254 1254 If nothing is known about the exception, this is the method which
1255 1255 should be used throughout the code for presenting user tracebacks,
1256 1256 rather than directly invoking the InteractiveTB object.
1257 1257
1258 1258 A specific showsyntaxerror() also exists, but this method can take
1259 1259 care of calling it if needed, so unless you are explicitly catching a
1260 1260 SyntaxError exception, don't try to analyze the stack manually and
1261 1261 simply call this method."""
1262 1262
1263 1263
1264 1264 # Though this won't be called by syntax errors in the input line,
1265 1265 # there may be SyntaxError cases whith imported code.
1266 1266
1267 1267 try:
1268 1268 if exc_tuple is None:
1269 1269 etype, value, tb = sys.exc_info()
1270 1270 else:
1271 1271 etype, value, tb = exc_tuple
1272 1272
1273 1273 if etype is SyntaxError:
1274 1274 self.showsyntaxerror(filename)
1275 1275 elif etype is UsageError:
1276 1276 print "UsageError:", value
1277 1277 else:
1278 1278 # WARNING: these variables are somewhat deprecated and not
1279 1279 # necessarily safe to use in a threaded environment, but tools
1280 1280 # like pdb depend on their existence, so let's set them. If we
1281 1281 # find problems in the field, we'll need to revisit their use.
1282 1282 sys.last_type = etype
1283 1283 sys.last_value = value
1284 1284 sys.last_traceback = tb
1285 1285
1286 1286 if etype in self.custom_exceptions:
1287 1287 self.CustomTB(etype,value,tb)
1288 1288 else:
1289 1289 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1290 1290 if self.InteractiveTB.call_pdb and self.has_readline:
1291 1291 # pdb mucks up readline, fix it back
1292 1292 self.set_completer()
1293 1293 except KeyboardInterrupt:
1294 1294 self.write("\nKeyboardInterrupt\n")
1295 1295
1296 1296 def showsyntaxerror(self, filename=None):
1297 1297 """Display the syntax error that just occurred.
1298 1298
1299 1299 This doesn't display a stack trace because there isn't one.
1300 1300
1301 1301 If a filename is given, it is stuffed in the exception instead
1302 1302 of what was there before (because Python's parser always uses
1303 1303 "<string>" when reading from a string).
1304 1304 """
1305 1305 etype, value, last_traceback = sys.exc_info()
1306 1306
1307 1307 # See note about these variables in showtraceback() below
1308 1308 sys.last_type = etype
1309 1309 sys.last_value = value
1310 1310 sys.last_traceback = last_traceback
1311 1311
1312 1312 if filename and etype is SyntaxError:
1313 1313 # Work hard to stuff the correct filename in the exception
1314 1314 try:
1315 1315 msg, (dummy_filename, lineno, offset, line) = value
1316 1316 except:
1317 1317 # Not the format we expect; leave it alone
1318 1318 pass
1319 1319 else:
1320 1320 # Stuff in the right filename
1321 1321 try:
1322 1322 # Assume SyntaxError is a class exception
1323 1323 value = SyntaxError(msg, (filename, lineno, offset, line))
1324 1324 except:
1325 1325 # If that failed, assume SyntaxError is a string
1326 1326 value = msg, (filename, lineno, offset, line)
1327 1327 self.SyntaxTB(etype,value,[])
1328 1328
1329 1329 def edit_syntax_error(self):
1330 1330 """The bottom half of the syntax error handler called in the main loop.
1331 1331
1332 1332 Loop until syntax error is fixed or user cancels.
1333 1333 """
1334 1334
1335 1335 while self.SyntaxTB.last_syntax_error:
1336 1336 # copy and clear last_syntax_error
1337 1337 err = self.SyntaxTB.clear_err_state()
1338 1338 if not self._should_recompile(err):
1339 1339 return
1340 1340 try:
1341 1341 # may set last_syntax_error again if a SyntaxError is raised
1342 1342 self.safe_execfile(err.filename,self.user_ns)
1343 1343 except:
1344 1344 self.showtraceback()
1345 1345 else:
1346 1346 try:
1347 1347 f = file(err.filename)
1348 1348 try:
1349 1349 # This should be inside a display_trap block and I
1350 1350 # think it is.
1351 1351 sys.displayhook(f.read())
1352 1352 finally:
1353 1353 f.close()
1354 1354 except:
1355 1355 self.showtraceback()
1356 1356
1357 1357 def _should_recompile(self,e):
1358 1358 """Utility routine for edit_syntax_error"""
1359 1359
1360 1360 if e.filename in ('<ipython console>','<input>','<string>',
1361 1361 '<console>','<BackgroundJob compilation>',
1362 1362 None):
1363 1363
1364 1364 return False
1365 1365 try:
1366 1366 if (self.autoedit_syntax and
1367 1367 not self.ask_yes_no('Return to editor to correct syntax error? '
1368 1368 '[Y/n] ','y')):
1369 1369 return False
1370 1370 except EOFError:
1371 1371 return False
1372 1372
1373 1373 def int0(x):
1374 1374 try:
1375 1375 return int(x)
1376 1376 except TypeError:
1377 1377 return 0
1378 1378 # always pass integer line and offset values to editor hook
1379 1379 try:
1380 1380 self.hooks.fix_error_editor(e.filename,
1381 1381 int0(e.lineno),int0(e.offset),e.msg)
1382 1382 except TryNext:
1383 1383 warn('Could not open editor')
1384 1384 return False
1385 1385 return True
1386 1386
1387 1387 #-------------------------------------------------------------------------
1388 1388 # Things related to tab completion
1389 1389 #-------------------------------------------------------------------------
1390 1390
1391 1391 def complete(self, text):
1392 1392 """Return a sorted list of all possible completions on text.
1393 1393
1394 1394 Inputs:
1395 1395
1396 1396 - text: a string of text to be completed on.
1397 1397
1398 1398 This is a wrapper around the completion mechanism, similar to what
1399 1399 readline does at the command line when the TAB key is hit. By
1400 1400 exposing it as a method, it can be used by other non-readline
1401 1401 environments (such as GUIs) for text completion.
1402 1402
1403 1403 Simple usage example:
1404 1404
1405 1405 In [7]: x = 'hello'
1406 1406
1407 1407 In [8]: x
1408 1408 Out[8]: 'hello'
1409 1409
1410 1410 In [9]: print x
1411 1411 hello
1412 1412
1413 1413 In [10]: _ip.complete('x.l')
1414 1414 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1415 1415 """
1416 1416
1417 1417 # Inject names into __builtin__ so we can complete on the added names.
1418 1418 with self.builtin_trap:
1419 1419 complete = self.Completer.complete
1420 1420 state = 0
1421 1421 # use a dict so we get unique keys, since ipyhton's multiple
1422 1422 # completers can return duplicates. When we make 2.4 a requirement,
1423 1423 # start using sets instead, which are faster.
1424 1424 comps = {}
1425 1425 while True:
1426 1426 newcomp = complete(text,state,line_buffer=text)
1427 1427 if newcomp is None:
1428 1428 break
1429 1429 comps[newcomp] = 1
1430 1430 state += 1
1431 1431 outcomps = comps.keys()
1432 1432 outcomps.sort()
1433 1433 #print "T:",text,"OC:",outcomps # dbg
1434 1434 #print "vars:",self.user_ns.keys()
1435 1435 return outcomps
1436 1436
1437 1437 def set_custom_completer(self,completer,pos=0):
1438 1438 """Adds a new custom completer function.
1439 1439
1440 1440 The position argument (defaults to 0) is the index in the completers
1441 1441 list where you want the completer to be inserted."""
1442 1442
1443 1443 newcomp = new.instancemethod(completer,self.Completer,
1444 1444 self.Completer.__class__)
1445 1445 self.Completer.matchers.insert(pos,newcomp)
1446 1446
1447 1447 def set_completer(self):
1448 1448 """Reset readline's completer to be our own."""
1449 1449 self.readline.set_completer(self.Completer.complete)
1450 1450
1451 1451 def set_completer_frame(self, frame=None):
1452 1452 """Set the frame of the completer."""
1453 1453 if frame:
1454 1454 self.Completer.namespace = frame.f_locals
1455 1455 self.Completer.global_namespace = frame.f_globals
1456 1456 else:
1457 1457 self.Completer.namespace = self.user_ns
1458 1458 self.Completer.global_namespace = self.user_global_ns
1459 1459
1460 1460 #-------------------------------------------------------------------------
1461 1461 # Things related to readline
1462 1462 #-------------------------------------------------------------------------
1463 1463
1464 1464 def init_readline(self):
1465 1465 """Command history completion/saving/reloading."""
1466 1466
1467 1467 self.rl_next_input = None
1468 1468 self.rl_do_indent = False
1469 1469
1470 1470 if not self.readline_use:
1471 1471 return
1472 1472
1473 1473 import IPython.utils.rlineimpl as readline
1474 1474
1475 1475 if not readline.have_readline:
1476 1476 self.has_readline = 0
1477 1477 self.readline = None
1478 1478 # no point in bugging windows users with this every time:
1479 1479 warn('Readline services not available on this platform.')
1480 1480 else:
1481 1481 sys.modules['readline'] = readline
1482 1482 import atexit
1483 1483 from IPython.core.completer import IPCompleter
1484 1484 self.Completer = IPCompleter(self,
1485 1485 self.user_ns,
1486 1486 self.user_global_ns,
1487 1487 self.readline_omit__names,
1488 1488 self.alias_manager.alias_table)
1489 1489 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1490 1490 self.strdispatchers['complete_command'] = sdisp
1491 1491 self.Completer.custom_completers = sdisp
1492 1492 # Platform-specific configuration
1493 1493 if os.name == 'nt':
1494 1494 self.readline_startup_hook = readline.set_pre_input_hook
1495 1495 else:
1496 1496 self.readline_startup_hook = readline.set_startup_hook
1497 1497
1498 1498 # Load user's initrc file (readline config)
1499 1499 # Or if libedit is used, load editrc.
1500 1500 inputrc_name = os.environ.get('INPUTRC')
1501 1501 if inputrc_name is None:
1502 1502 home_dir = get_home_dir()
1503 1503 if home_dir is not None:
1504 1504 inputrc_name = '.inputrc'
1505 1505 if readline.uses_libedit:
1506 1506 inputrc_name = '.editrc'
1507 1507 inputrc_name = os.path.join(home_dir, inputrc_name)
1508 1508 if os.path.isfile(inputrc_name):
1509 1509 try:
1510 1510 readline.read_init_file(inputrc_name)
1511 1511 except:
1512 1512 warn('Problems reading readline initialization file <%s>'
1513 1513 % inputrc_name)
1514 1514
1515 1515 self.has_readline = 1
1516 1516 self.readline = readline
1517 1517 # save this in sys so embedded copies can restore it properly
1518 1518 sys.ipcompleter = self.Completer.complete
1519 1519 self.set_completer()
1520 1520
1521 1521 # Configure readline according to user's prefs
1522 1522 # This is only done if GNU readline is being used. If libedit
1523 1523 # is being used (as on Leopard) the readline config is
1524 1524 # not run as the syntax for libedit is different.
1525 1525 if not readline.uses_libedit:
1526 1526 for rlcommand in self.readline_parse_and_bind:
1527 1527 #print "loading rl:",rlcommand # dbg
1528 1528 readline.parse_and_bind(rlcommand)
1529 1529
1530 1530 # Remove some chars from the delimiters list. If we encounter
1531 1531 # unicode chars, discard them.
1532 1532 delims = readline.get_completer_delims().encode("ascii", "ignore")
1533 1533 delims = delims.translate(string._idmap,
1534 1534 self.readline_remove_delims)
1535 1535 readline.set_completer_delims(delims)
1536 1536 # otherwise we end up with a monster history after a while:
1537 1537 readline.set_history_length(1000)
1538 1538 try:
1539 1539 #print '*** Reading readline history' # dbg
1540 1540 readline.read_history_file(self.histfile)
1541 1541 except IOError:
1542 1542 pass # It doesn't exist yet.
1543 1543
1544 1544 atexit.register(self.atexit_operations)
1545 1545 del atexit
1546 1546
1547 1547 # Configure auto-indent for all platforms
1548 1548 self.set_autoindent(self.autoindent)
1549 1549
1550 1550 def set_next_input(self, s):
1551 1551 """ Sets the 'default' input string for the next command line.
1552 1552
1553 1553 Requires readline.
1554 1554
1555 1555 Example:
1556 1556
1557 1557 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1558 1558 [D:\ipython]|2> Hello Word_ # cursor is here
1559 1559 """
1560 1560
1561 1561 self.rl_next_input = s
1562 1562
1563 1563 def pre_readline(self):
1564 1564 """readline hook to be used at the start of each line.
1565 1565
1566 1566 Currently it handles auto-indent only."""
1567 1567
1568 1568 #debugx('self.indent_current_nsp','pre_readline:')
1569 1569
1570 1570 if self.rl_do_indent:
1571 1571 self.readline.insert_text(self._indent_current_str())
1572 1572 if self.rl_next_input is not None:
1573 1573 self.readline.insert_text(self.rl_next_input)
1574 1574 self.rl_next_input = None
1575 1575
1576 1576 def _indent_current_str(self):
1577 1577 """return the current level of indentation as a string"""
1578 1578 return self.indent_current_nsp * ' '
1579 1579
1580 1580 #-------------------------------------------------------------------------
1581 1581 # Things related to magics
1582 1582 #-------------------------------------------------------------------------
1583 1583
1584 1584 def init_magics(self):
1585 1585 # Set user colors (don't do it in the constructor above so that it
1586 1586 # doesn't crash if colors option is invalid)
1587 1587 self.magic_colors(self.colors)
1588 1588
1589 1589 def magic(self,arg_s):
1590 1590 """Call a magic function by name.
1591 1591
1592 1592 Input: a string containing the name of the magic function to call and any
1593 1593 additional arguments to be passed to the magic.
1594 1594
1595 1595 magic('name -opt foo bar') is equivalent to typing at the ipython
1596 1596 prompt:
1597 1597
1598 1598 In[1]: %name -opt foo bar
1599 1599
1600 1600 To call a magic without arguments, simply use magic('name').
1601 1601
1602 1602 This provides a proper Python function to call IPython's magics in any
1603 1603 valid Python code you can type at the interpreter, including loops and
1604 1604 compound statements.
1605 1605 """
1606 1606
1607 1607 args = arg_s.split(' ',1)
1608 1608 magic_name = args[0]
1609 1609 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1610 1610
1611 1611 try:
1612 1612 magic_args = args[1]
1613 1613 except IndexError:
1614 1614 magic_args = ''
1615 1615 fn = getattr(self,'magic_'+magic_name,None)
1616 1616 if fn is None:
1617 1617 error("Magic function `%s` not found." % magic_name)
1618 1618 else:
1619 1619 magic_args = self.var_expand(magic_args,1)
1620 1620 with nested(self.builtin_trap,):
1621 1621 result = fn(magic_args)
1622 1622 return result
1623 1623
1624 1624 def define_magic(self, magicname, func):
1625 1625 """Expose own function as magic function for ipython
1626 1626
1627 1627 def foo_impl(self,parameter_s=''):
1628 1628 'My very own magic!. (Use docstrings, IPython reads them).'
1629 1629 print 'Magic function. Passed parameter is between < >:'
1630 1630 print '<%s>' % parameter_s
1631 1631 print 'The self object is:',self
1632 1632
1633 1633 self.define_magic('foo',foo_impl)
1634 1634 """
1635 1635
1636 1636 import new
1637 1637 im = new.instancemethod(func,self, self.__class__)
1638 1638 old = getattr(self, "magic_" + magicname, None)
1639 1639 setattr(self, "magic_" + magicname, im)
1640 1640 return old
1641 1641
1642 1642 #-------------------------------------------------------------------------
1643 1643 # Things related to macros
1644 1644 #-------------------------------------------------------------------------
1645 1645
1646 1646 def define_macro(self, name, themacro):
1647 1647 """Define a new macro
1648 1648
1649 1649 Parameters
1650 1650 ----------
1651 1651 name : str
1652 1652 The name of the macro.
1653 1653 themacro : str or Macro
1654 1654 The action to do upon invoking the macro. If a string, a new
1655 1655 Macro object is created by passing the string to it.
1656 1656 """
1657 1657
1658 1658 from IPython.core import macro
1659 1659
1660 1660 if isinstance(themacro, basestring):
1661 1661 themacro = macro.Macro(themacro)
1662 1662 if not isinstance(themacro, macro.Macro):
1663 1663 raise ValueError('A macro must be a string or a Macro instance.')
1664 1664 self.user_ns[name] = themacro
1665 1665
1666 1666 #-------------------------------------------------------------------------
1667 1667 # Things related to the running of system commands
1668 1668 #-------------------------------------------------------------------------
1669 1669
1670 1670 def system(self, cmd):
1671 1671 """Make a system call, using IPython."""
1672 1672 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1673 1673
1674 1674 #-------------------------------------------------------------------------
1675 1675 # Things related to aliases
1676 1676 #-------------------------------------------------------------------------
1677 1677
1678 1678 def init_alias(self):
1679 1679 self.alias_manager = AliasManager(self, config=self.config)
1680 1680 self.ns_table['alias'] = self.alias_manager.alias_table,
1681 1681
1682 1682 #-------------------------------------------------------------------------
1683 1683 # Things related to the running of code
1684 1684 #-------------------------------------------------------------------------
1685 1685
1686 1686 def ex(self, cmd):
1687 1687 """Execute a normal python statement in user namespace."""
1688 1688 with nested(self.builtin_trap,):
1689 1689 exec cmd in self.user_global_ns, self.user_ns
1690 1690
1691 1691 def ev(self, expr):
1692 1692 """Evaluate python expression expr in user namespace.
1693 1693
1694 1694 Returns the result of evaluation
1695 1695 """
1696 1696 with nested(self.builtin_trap,):
1697 1697 return eval(expr, self.user_global_ns, self.user_ns)
1698 1698
1699 1699 def mainloop(self, display_banner=None):
1700 1700 """Start the mainloop.
1701 1701
1702 1702 If an optional banner argument is given, it will override the
1703 1703 internally created default banner.
1704 1704 """
1705 1705
1706 1706 with nested(self.builtin_trap, self.display_trap):
1707 1707
1708 1708 # if you run stuff with -c <cmd>, raw hist is not updated
1709 1709 # ensure that it's in sync
1710 1710 if len(self.input_hist) != len (self.input_hist_raw):
1711 1711 self.input_hist_raw = InputList(self.input_hist)
1712 1712
1713 1713 while 1:
1714 1714 try:
1715 1715 self.interact(display_banner=display_banner)
1716 1716 #self.interact_with_readline()
1717 1717 # XXX for testing of a readline-decoupled repl loop, call
1718 1718 # interact_with_readline above
1719 1719 break
1720 1720 except KeyboardInterrupt:
1721 1721 # this should not be necessary, but KeyboardInterrupt
1722 1722 # handling seems rather unpredictable...
1723 1723 self.write("\nKeyboardInterrupt in interact()\n")
1724 1724
1725 1725 def interact_prompt(self):
1726 1726 """ Print the prompt (in read-eval-print loop)
1727 1727
1728 1728 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1729 1729 used in standard IPython flow.
1730 1730 """
1731 1731 if self.more:
1732 1732 try:
1733 1733 prompt = self.hooks.generate_prompt(True)
1734 1734 except:
1735 1735 self.showtraceback()
1736 1736 if self.autoindent:
1737 1737 self.rl_do_indent = True
1738 1738
1739 1739 else:
1740 1740 try:
1741 1741 prompt = self.hooks.generate_prompt(False)
1742 1742 except:
1743 1743 self.showtraceback()
1744 1744 self.write(prompt)
1745 1745
1746 1746 def interact_handle_input(self,line):
1747 1747 """ Handle the input line (in read-eval-print loop)
1748 1748
1749 1749 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1750 1750 used in standard IPython flow.
1751 1751 """
1752 1752 if line.lstrip() == line:
1753 1753 self.shadowhist.add(line.strip())
1754 1754 lineout = self.prefilter_manager.prefilter_lines(line,self.more)
1755 1755
1756 1756 if line.strip():
1757 1757 if self.more:
1758 1758 self.input_hist_raw[-1] += '%s\n' % line
1759 1759 else:
1760 1760 self.input_hist_raw.append('%s\n' % line)
1761 1761
1762 1762
1763 1763 self.more = self.push_line(lineout)
1764 1764 if (self.SyntaxTB.last_syntax_error and
1765 1765 self.autoedit_syntax):
1766 1766 self.edit_syntax_error()
1767 1767
1768 1768 def interact_with_readline(self):
1769 1769 """ Demo of using interact_handle_input, interact_prompt
1770 1770
1771 1771 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1772 1772 it should work like this.
1773 1773 """
1774 1774 self.readline_startup_hook(self.pre_readline)
1775 1775 while not self.exit_now:
1776 1776 self.interact_prompt()
1777 1777 if self.more:
1778 1778 self.rl_do_indent = True
1779 1779 else:
1780 1780 self.rl_do_indent = False
1781 1781 line = raw_input_original().decode(self.stdin_encoding)
1782 1782 self.interact_handle_input(line)
1783 1783
1784 1784 def interact(self, display_banner=None):
1785 1785 """Closely emulate the interactive Python console."""
1786 1786
1787 1787 # batch run -> do not interact
1788 1788 if self.exit_now:
1789 1789 return
1790 1790
1791 1791 if display_banner is None:
1792 1792 display_banner = self.display_banner
1793 1793 if display_banner:
1794 1794 self.show_banner()
1795 1795
1796 1796 more = 0
1797 1797
1798 1798 # Mark activity in the builtins
1799 1799 __builtin__.__dict__['__IPYTHON__active'] += 1
1800 1800
1801 1801 if self.has_readline:
1802 1802 self.readline_startup_hook(self.pre_readline)
1803 1803 # exit_now is set by a call to %Exit or %Quit, through the
1804 1804 # ask_exit callback.
1805 1805
1806 1806 while not self.exit_now:
1807 1807 self.hooks.pre_prompt_hook()
1808 1808 if more:
1809 1809 try:
1810 1810 prompt = self.hooks.generate_prompt(True)
1811 1811 except:
1812 1812 self.showtraceback()
1813 1813 if self.autoindent:
1814 1814 self.rl_do_indent = True
1815 1815
1816 1816 else:
1817 1817 try:
1818 1818 prompt = self.hooks.generate_prompt(False)
1819 1819 except:
1820 1820 self.showtraceback()
1821 1821 try:
1822 1822 line = self.raw_input(prompt, more)
1823 1823 if self.exit_now:
1824 1824 # quick exit on sys.std[in|out] close
1825 1825 break
1826 1826 if self.autoindent:
1827 1827 self.rl_do_indent = False
1828 1828
1829 1829 except KeyboardInterrupt:
1830 1830 #double-guard against keyboardinterrupts during kbdint handling
1831 1831 try:
1832 1832 self.write('\nKeyboardInterrupt\n')
1833 1833 self.resetbuffer()
1834 1834 # keep cache in sync with the prompt counter:
1835 1835 self.outputcache.prompt_count -= 1
1836 1836
1837 1837 if self.autoindent:
1838 1838 self.indent_current_nsp = 0
1839 1839 more = 0
1840 1840 except KeyboardInterrupt:
1841 1841 pass
1842 1842 except EOFError:
1843 1843 if self.autoindent:
1844 1844 self.rl_do_indent = False
1845 1845 self.readline_startup_hook(None)
1846 1846 self.write('\n')
1847 1847 self.exit()
1848 1848 except bdb.BdbQuit:
1849 1849 warn('The Python debugger has exited with a BdbQuit exception.\n'
1850 1850 'Because of how pdb handles the stack, it is impossible\n'
1851 1851 'for IPython to properly format this particular exception.\n'
1852 1852 'IPython will resume normal operation.')
1853 1853 except:
1854 1854 # exceptions here are VERY RARE, but they can be triggered
1855 1855 # asynchronously by signal handlers, for example.
1856 1856 self.showtraceback()
1857 1857 else:
1858 1858 more = self.push_line(line)
1859 1859 if (self.SyntaxTB.last_syntax_error and
1860 1860 self.autoedit_syntax):
1861 1861 self.edit_syntax_error()
1862 1862
1863 1863 # We are off again...
1864 1864 __builtin__.__dict__['__IPYTHON__active'] -= 1
1865 1865
1866 1866 def safe_execfile(self, fname, *where, **kw):
1867 1867 """A safe version of the builtin execfile().
1868 1868
1869 1869 This version will never throw an exception, but instead print
1870 1870 helpful error messages to the screen. This only works on pure
1871 1871 Python files with the .py extension.
1872 1872
1873 1873 Parameters
1874 1874 ----------
1875 1875 fname : string
1876 1876 The name of the file to be executed.
1877 1877 where : tuple
1878 1878 One or two namespaces, passed to execfile() as (globals,locals).
1879 1879 If only one is given, it is passed as both.
1880 1880 exit_ignore : bool (False)
1881 1881 If True, then don't print errors for non-zero exit statuses.
1882 1882 """
1883 1883 kw.setdefault('exit_ignore', False)
1884 1884
1885 1885 fname = os.path.abspath(os.path.expanduser(fname))
1886 1886
1887 1887 # Make sure we have a .py file
1888 1888 if not fname.endswith('.py'):
1889 1889 warn('File must end with .py to be run using execfile: <%s>' % fname)
1890 1890
1891 1891 # Make sure we can open the file
1892 1892 try:
1893 1893 with open(fname) as thefile:
1894 1894 pass
1895 1895 except:
1896 1896 warn('Could not open file <%s> for safe execution.' % fname)
1897 1897 return
1898 1898
1899 1899 # Find things also in current directory. This is needed to mimic the
1900 1900 # behavior of running a script from the system command line, where
1901 1901 # Python inserts the script's directory into sys.path
1902 1902 dname = os.path.dirname(fname)
1903 1903
1904 1904 with prepended_to_syspath(dname):
1905 1905 try:
1906 1906 if sys.platform == 'win32' and sys.version_info < (2,5,1):
1907 1907 # Work around a bug in Python for Windows. The bug was
1908 1908 # fixed in in Python 2.5 r54159 and 54158, but that's still
1909 1909 # SVN Python as of March/07. For details, see:
1910 1910 # http://projects.scipy.org/ipython/ipython/ticket/123
1911 1911 try:
1912 1912 globs,locs = where[0:2]
1913 1913 except:
1914 1914 try:
1915 1915 globs = locs = where[0]
1916 1916 except:
1917 1917 globs = locs = globals()
1918 1918 exec file(fname) in globs,locs
1919 1919 else:
1920 1920 execfile(fname,*where)
1921 1921 except SyntaxError:
1922 1922 self.showsyntaxerror()
1923 1923 warn('Failure executing file: <%s>' % fname)
1924 1924 except SystemExit, status:
1925 1925 # Code that correctly sets the exit status flag to success (0)
1926 1926 # shouldn't be bothered with a traceback. Note that a plain
1927 1927 # sys.exit() does NOT set the message to 0 (it's empty) so that
1928 1928 # will still get a traceback. Note that the structure of the
1929 1929 # SystemExit exception changed between Python 2.4 and 2.5, so
1930 1930 # the checks must be done in a version-dependent way.
1931 1931 show = False
1932 1932 if status.args[0]==0 and not kw['exit_ignore']:
1933 1933 show = True
1934 1934 if show:
1935 1935 self.showtraceback()
1936 1936 warn('Failure executing file: <%s>' % fname)
1937 1937 except:
1938 1938 self.showtraceback()
1939 1939 warn('Failure executing file: <%s>' % fname)
1940 1940
1941 1941 def safe_execfile_ipy(self, fname):
1942 1942 """Like safe_execfile, but for .ipy files with IPython syntax.
1943 1943
1944 1944 Parameters
1945 1945 ----------
1946 1946 fname : str
1947 1947 The name of the file to execute. The filename must have a
1948 1948 .ipy extension.
1949 1949 """
1950 1950 fname = os.path.abspath(os.path.expanduser(fname))
1951 1951
1952 1952 # Make sure we have a .py file
1953 1953 if not fname.endswith('.ipy'):
1954 1954 warn('File must end with .py to be run using execfile: <%s>' % fname)
1955 1955
1956 1956 # Make sure we can open the file
1957 1957 try:
1958 1958 with open(fname) as thefile:
1959 1959 pass
1960 1960 except:
1961 1961 warn('Could not open file <%s> for safe execution.' % fname)
1962 1962 return
1963 1963
1964 1964 # Find things also in current directory. This is needed to mimic the
1965 1965 # behavior of running a script from the system command line, where
1966 1966 # Python inserts the script's directory into sys.path
1967 1967 dname = os.path.dirname(fname)
1968 1968
1969 1969 with prepended_to_syspath(dname):
1970 1970 try:
1971 1971 with open(fname) as thefile:
1972 1972 script = thefile.read()
1973 1973 # self.runlines currently captures all exceptions
1974 1974 # raise in user code. It would be nice if there were
1975 1975 # versions of runlines, execfile that did raise, so
1976 1976 # we could catch the errors.
1977 1977 self.runlines(script, clean=True)
1978 1978 except:
1979 1979 self.showtraceback()
1980 1980 warn('Unknown failure executing file: <%s>' % fname)
1981 1981
1982 1982 def _is_secondary_block_start(self, s):
1983 1983 if not s.endswith(':'):
1984 1984 return False
1985 1985 if (s.startswith('elif') or
1986 1986 s.startswith('else') or
1987 1987 s.startswith('except') or
1988 1988 s.startswith('finally')):
1989 1989 return True
1990 1990
1991 1991 def cleanup_ipy_script(self, script):
1992 1992 """Make a script safe for self.runlines()
1993 1993
1994 1994 Currently, IPython is lines based, with blocks being detected by
1995 1995 empty lines. This is a problem for block based scripts that may
1996 1996 not have empty lines after blocks. This script adds those empty
1997 1997 lines to make scripts safe for running in the current line based
1998 1998 IPython.
1999 1999 """
2000 2000 res = []
2001 2001 lines = script.splitlines()
2002 2002 level = 0
2003 2003
2004 2004 for l in lines:
2005 2005 lstripped = l.lstrip()
2006 2006 stripped = l.strip()
2007 2007 if not stripped:
2008 2008 continue
2009 2009 newlevel = len(l) - len(lstripped)
2010 2010 if level > 0 and newlevel == 0 and \
2011 2011 not self._is_secondary_block_start(stripped):
2012 2012 # add empty line
2013 2013 res.append('')
2014 2014 res.append(l)
2015 2015 level = newlevel
2016 2016
2017 2017 return '\n'.join(res) + '\n'
2018 2018
2019 2019 def runlines(self, lines, clean=False):
2020 2020 """Run a string of one or more lines of source.
2021 2021
2022 2022 This method is capable of running a string containing multiple source
2023 2023 lines, as if they had been entered at the IPython prompt. Since it
2024 2024 exposes IPython's processing machinery, the given strings can contain
2025 2025 magic calls (%magic), special shell access (!cmd), etc.
2026 2026 """
2027 2027
2028 2028 if isinstance(lines, (list, tuple)):
2029 2029 lines = '\n'.join(lines)
2030 2030
2031 2031 if clean:
2032 2032 lines = self.cleanup_ipy_script(lines)
2033 2033
2034 2034 # We must start with a clean buffer, in case this is run from an
2035 2035 # interactive IPython session (via a magic, for example).
2036 2036 self.resetbuffer()
2037 2037 lines = lines.splitlines()
2038 2038 more = 0
2039 2039
2040 2040 with nested(self.builtin_trap, self.display_trap):
2041 2041 for line in lines:
2042 2042 # skip blank lines so we don't mess up the prompt counter, but do
2043 2043 # NOT skip even a blank line if we are in a code block (more is
2044 2044 # true)
2045 2045
2046 2046 if line or more:
2047 2047 # push to raw history, so hist line numbers stay in sync
2048 2048 self.input_hist_raw.append("# " + line + "\n")
2049 2049 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
2050 2050 more = self.push_line(prefiltered)
2051 2051 # IPython's runsource returns None if there was an error
2052 2052 # compiling the code. This allows us to stop processing right
2053 2053 # away, so the user gets the error message at the right place.
2054 2054 if more is None:
2055 2055 break
2056 2056 else:
2057 2057 self.input_hist_raw.append("\n")
2058 2058 # final newline in case the input didn't have it, so that the code
2059 2059 # actually does get executed
2060 2060 if more:
2061 2061 self.push_line('\n')
2062 2062
2063 2063 def runsource(self, source, filename='<input>', symbol='single'):
2064 2064 """Compile and run some source in the interpreter.
2065 2065
2066 2066 Arguments are as for compile_command().
2067 2067
2068 2068 One several things can happen:
2069 2069
2070 2070 1) The input is incorrect; compile_command() raised an
2071 2071 exception (SyntaxError or OverflowError). A syntax traceback
2072 2072 will be printed by calling the showsyntaxerror() method.
2073 2073
2074 2074 2) The input is incomplete, and more input is required;
2075 2075 compile_command() returned None. Nothing happens.
2076 2076
2077 2077 3) The input is complete; compile_command() returned a code
2078 2078 object. The code is executed by calling self.runcode() (which
2079 2079 also handles run-time exceptions, except for SystemExit).
2080 2080
2081 2081 The return value is:
2082 2082
2083 2083 - True in case 2
2084 2084
2085 2085 - False in the other cases, unless an exception is raised, where
2086 2086 None is returned instead. This can be used by external callers to
2087 2087 know whether to continue feeding input or not.
2088 2088
2089 2089 The return value can be used to decide whether to use sys.ps1 or
2090 2090 sys.ps2 to prompt the next line."""
2091 2091
2092 2092 # if the source code has leading blanks, add 'if 1:\n' to it
2093 2093 # this allows execution of indented pasted code. It is tempting
2094 2094 # to add '\n' at the end of source to run commands like ' a=1'
2095 2095 # directly, but this fails for more complicated scenarios
2096 2096 source=source.encode(self.stdin_encoding)
2097 2097 if source[:1] in [' ', '\t']:
2098 2098 source = 'if 1:\n%s' % source
2099 2099
2100 2100 try:
2101 2101 code = self.compile(source,filename,symbol)
2102 2102 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2103 2103 # Case 1
2104 2104 self.showsyntaxerror(filename)
2105 2105 return None
2106 2106
2107 2107 if code is None:
2108 2108 # Case 2
2109 2109 return True
2110 2110
2111 2111 # Case 3
2112 2112 # We store the code object so that threaded shells and
2113 2113 # custom exception handlers can access all this info if needed.
2114 2114 # The source corresponding to this can be obtained from the
2115 2115 # buffer attribute as '\n'.join(self.buffer).
2116 2116 self.code_to_run = code
2117 2117 # now actually execute the code object
2118 2118 if self.runcode(code) == 0:
2119 2119 return False
2120 2120 else:
2121 2121 return None
2122 2122
2123 2123 def runcode(self,code_obj):
2124 2124 """Execute a code object.
2125 2125
2126 2126 When an exception occurs, self.showtraceback() is called to display a
2127 2127 traceback.
2128 2128
2129 2129 Return value: a flag indicating whether the code to be run completed
2130 2130 successfully:
2131 2131
2132 2132 - 0: successful execution.
2133 2133 - 1: an error occurred.
2134 2134 """
2135 2135
2136 2136 # Set our own excepthook in case the user code tries to call it
2137 2137 # directly, so that the IPython crash handler doesn't get triggered
2138 2138 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2139 2139
2140 2140 # we save the original sys.excepthook in the instance, in case config
2141 2141 # code (such as magics) needs access to it.
2142 2142 self.sys_excepthook = old_excepthook
2143 2143 outflag = 1 # happens in more places, so it's easier as default
2144 2144 try:
2145 2145 try:
2146 2146 self.hooks.pre_runcode_hook()
2147 2147 exec code_obj in self.user_global_ns, self.user_ns
2148 2148 finally:
2149 2149 # Reset our crash handler in place
2150 2150 sys.excepthook = old_excepthook
2151 2151 except SystemExit:
2152 2152 self.resetbuffer()
2153 2153 self.showtraceback()
2154 2154 warn("Type %exit or %quit to exit IPython "
2155 2155 "(%Exit or %Quit do so unconditionally).",level=1)
2156 2156 except self.custom_exceptions:
2157 2157 etype,value,tb = sys.exc_info()
2158 2158 self.CustomTB(etype,value,tb)
2159 2159 except:
2160 2160 self.showtraceback()
2161 2161 else:
2162 2162 outflag = 0
2163 2163 if softspace(sys.stdout, 0):
2164 2164 print
2165 2165 # Flush out code object which has been run (and source)
2166 2166 self.code_to_run = None
2167 2167 return outflag
2168 2168
2169 2169 def push_line(self, line):
2170 2170 """Push a line to the interpreter.
2171 2171
2172 2172 The line should not have a trailing newline; it may have
2173 2173 internal newlines. The line is appended to a buffer and the
2174 2174 interpreter's runsource() method is called with the
2175 2175 concatenated contents of the buffer as source. If this
2176 2176 indicates that the command was executed or invalid, the buffer
2177 2177 is reset; otherwise, the command is incomplete, and the buffer
2178 2178 is left as it was after the line was appended. The return
2179 2179 value is 1 if more input is required, 0 if the line was dealt
2180 2180 with in some way (this is the same as runsource()).
2181 2181 """
2182 2182
2183 2183 # autoindent management should be done here, and not in the
2184 2184 # interactive loop, since that one is only seen by keyboard input. We
2185 2185 # need this done correctly even for code run via runlines (which uses
2186 2186 # push).
2187 2187
2188 2188 #print 'push line: <%s>' % line # dbg
2189 2189 for subline in line.splitlines():
2190 2190 self._autoindent_update(subline)
2191 2191 self.buffer.append(line)
2192 2192 more = self.runsource('\n'.join(self.buffer), self.filename)
2193 2193 if not more:
2194 2194 self.resetbuffer()
2195 2195 return more
2196 2196
2197 2197 def _autoindent_update(self,line):
2198 2198 """Keep track of the indent level."""
2199 2199
2200 2200 #debugx('line')
2201 2201 #debugx('self.indent_current_nsp')
2202 2202 if self.autoindent:
2203 2203 if line:
2204 2204 inisp = num_ini_spaces(line)
2205 2205 if inisp < self.indent_current_nsp:
2206 2206 self.indent_current_nsp = inisp
2207 2207
2208 2208 if line[-1] == ':':
2209 2209 self.indent_current_nsp += 4
2210 2210 elif dedent_re.match(line):
2211 2211 self.indent_current_nsp -= 4
2212 2212 else:
2213 2213 self.indent_current_nsp = 0
2214 2214
2215 2215 def resetbuffer(self):
2216 2216 """Reset the input buffer."""
2217 2217 self.buffer[:] = []
2218 2218
2219 2219 def raw_input(self,prompt='',continue_prompt=False):
2220 2220 """Write a prompt and read a line.
2221 2221
2222 2222 The returned line does not include the trailing newline.
2223 2223 When the user enters the EOF key sequence, EOFError is raised.
2224 2224
2225 2225 Optional inputs:
2226 2226
2227 2227 - prompt(''): a string to be printed to prompt the user.
2228 2228
2229 2229 - continue_prompt(False): whether this line is the first one or a
2230 2230 continuation in a sequence of inputs.
2231 2231 """
2232 2232 # growl.notify("raw_input: ", "prompt = %r\ncontinue_prompt = %s" % (prompt, continue_prompt))
2233 2233
2234 2234 # Code run by the user may have modified the readline completer state.
2235 2235 # We must ensure that our completer is back in place.
2236 2236
2237 2237 if self.has_readline:
2238 2238 self.set_completer()
2239 2239
2240 2240 try:
2241 2241 line = raw_input_original(prompt).decode(self.stdin_encoding)
2242 2242 except ValueError:
2243 2243 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2244 2244 " or sys.stdout.close()!\nExiting IPython!")
2245 2245 self.ask_exit()
2246 2246 return ""
2247 2247
2248 2248 # Try to be reasonably smart about not re-indenting pasted input more
2249 2249 # than necessary. We do this by trimming out the auto-indent initial
2250 2250 # spaces, if the user's actual input started itself with whitespace.
2251 2251 #debugx('self.buffer[-1]')
2252 2252
2253 2253 if self.autoindent:
2254 2254 if num_ini_spaces(line) > self.indent_current_nsp:
2255 2255 line = line[self.indent_current_nsp:]
2256 2256 self.indent_current_nsp = 0
2257 2257
2258 2258 # store the unfiltered input before the user has any chance to modify
2259 2259 # it.
2260 2260 if line.strip():
2261 2261 if continue_prompt:
2262 2262 self.input_hist_raw[-1] += '%s\n' % line
2263 2263 if self.has_readline and self.readline_use:
2264 2264 try:
2265 2265 histlen = self.readline.get_current_history_length()
2266 2266 if histlen > 1:
2267 2267 newhist = self.input_hist_raw[-1].rstrip()
2268 2268 self.readline.remove_history_item(histlen-1)
2269 2269 self.readline.replace_history_item(histlen-2,
2270 2270 newhist.encode(self.stdin_encoding))
2271 2271 except AttributeError:
2272 2272 pass # re{move,place}_history_item are new in 2.4.
2273 2273 else:
2274 2274 self.input_hist_raw.append('%s\n' % line)
2275 2275 # only entries starting at first column go to shadow history
2276 2276 if line.lstrip() == line:
2277 2277 self.shadowhist.add(line.strip())
2278 2278 elif not continue_prompt:
2279 2279 self.input_hist_raw.append('\n')
2280 2280 try:
2281 2281 lineout = self.prefilter_manager.prefilter_lines(line,continue_prompt)
2282 2282 except:
2283 2283 # blanket except, in case a user-defined prefilter crashes, so it
2284 2284 # can't take all of ipython with it.
2285 2285 self.showtraceback()
2286 2286 return ''
2287 2287 else:
2288 2288 return lineout
2289 2289
2290 2290 #-------------------------------------------------------------------------
2291 2291 # Working with components
2292 2292 #-------------------------------------------------------------------------
2293 2293
2294 2294 def get_component(self, name=None, klass=None):
2295 2295 """Fetch a component by name and klass in my tree."""
2296 2296 c = Component.get_instances(root=self, name=name, klass=klass)
2297 2297 if len(c) == 0:
2298 2298 return None
2299 2299 if len(c) == 1:
2300 2300 return c[0]
2301 2301 else:
2302 2302 return c
2303 2303
2304 2304 #-------------------------------------------------------------------------
2305 2305 # IPython extensions
2306 2306 #-------------------------------------------------------------------------
2307 2307
2308 2308 def load_extension(self, module_str):
2309 2309 """Load an IPython extension by its module name.
2310 2310
2311 2311 An IPython extension is an importable Python module that has
2312 2312 a function with the signature::
2313 2313
2314 2314 def load_ipython_extension(ipython):
2315 2315 # Do things with ipython
2316 2316
2317 2317 This function is called after your extension is imported and the
2318 2318 currently active :class:`InteractiveShell` instance is passed as
2319 2319 the only argument. You can do anything you want with IPython at
2320 2320 that point, including defining new magic and aliases, adding new
2321 2321 components, etc.
2322 2322
2323 2323 The :func:`load_ipython_extension` will be called again is you
2324 2324 load or reload the extension again. It is up to the extension
2325 2325 author to add code to manage that.
2326 2326
2327 2327 You can put your extension modules anywhere you want, as long as
2328 2328 they can be imported by Python's standard import mechanism. However,
2329 2329 to make it easy to write extensions, you can also put your extensions
2330 2330 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
2331 2331 is added to ``sys.path`` automatically.
2332 2332 """
2333 2333 from IPython.utils.syspathcontext import prepended_to_syspath
2334 2334
2335 2335 if module_str not in sys.modules:
2336 2336 with prepended_to_syspath(self.ipython_extension_dir):
2337 2337 __import__(module_str)
2338 2338 mod = sys.modules[module_str]
2339 2339 self._call_load_ipython_extension(mod)
2340 2340
2341 2341 def unload_extension(self, module_str):
2342 2342 """Unload an IPython extension by its module name.
2343 2343
2344 2344 This function looks up the extension's name in ``sys.modules`` and
2345 2345 simply calls ``mod.unload_ipython_extension(self)``.
2346 2346 """
2347 2347 if module_str in sys.modules:
2348 2348 mod = sys.modules[module_str]
2349 2349 self._call_unload_ipython_extension(mod)
2350 2350
2351 2351 def reload_extension(self, module_str):
2352 2352 """Reload an IPython extension by calling reload.
2353 2353
2354 2354 If the module has not been loaded before,
2355 2355 :meth:`InteractiveShell.load_extension` is called. Otherwise
2356 2356 :func:`reload` is called and then the :func:`load_ipython_extension`
2357 2357 function of the module, if it exists is called.
2358 2358 """
2359 2359 from IPython.utils.syspathcontext import prepended_to_syspath
2360 2360
2361 2361 with prepended_to_syspath(self.ipython_extension_dir):
2362 2362 if module_str in sys.modules:
2363 2363 mod = sys.modules[module_str]
2364 2364 reload(mod)
2365 2365 self._call_load_ipython_extension(mod)
2366 2366 else:
2367 2367 self.load_extension(module_str)
2368 2368
2369 2369 def _call_load_ipython_extension(self, mod):
2370 2370 if hasattr(mod, 'load_ipython_extension'):
2371 2371 mod.load_ipython_extension(self)
2372 2372
2373 2373 def _call_unload_ipython_extension(self, mod):
2374 2374 if hasattr(mod, 'unload_ipython_extension'):
2375 2375 mod.unload_ipython_extension(self)
2376 2376
2377 2377 #-------------------------------------------------------------------------
2378 2378 # Things related to the prefilter
2379 2379 #-------------------------------------------------------------------------
2380 2380
2381 2381 def init_prefilter(self):
2382 2382 self.prefilter_manager = PrefilterManager(self, config=self.config)
2383 2383
2384 2384 #-------------------------------------------------------------------------
2385 2385 # Utilities
2386 2386 #-------------------------------------------------------------------------
2387 2387
2388 2388 def getoutput(self, cmd):
2389 2389 return getoutput(self.var_expand(cmd,depth=2),
2390 2390 header=self.system_header,
2391 2391 verbose=self.system_verbose)
2392 2392
2393 2393 def getoutputerror(self, cmd):
2394 2394 return getoutputerror(self.var_expand(cmd,depth=2),
2395 2395 header=self.system_header,
2396 2396 verbose=self.system_verbose)
2397 2397
2398 2398 def var_expand(self,cmd,depth=0):
2399 2399 """Expand python variables in a string.
2400 2400
2401 2401 The depth argument indicates how many frames above the caller should
2402 2402 be walked to look for the local namespace where to expand variables.
2403 2403
2404 2404 The global namespace for expansion is always the user's interactive
2405 2405 namespace.
2406 2406 """
2407 2407
2408 2408 return str(ItplNS(cmd,
2409 2409 self.user_ns, # globals
2410 2410 # Skip our own frame in searching for locals:
2411 2411 sys._getframe(depth+1).f_locals # locals
2412 2412 ))
2413 2413
2414 2414 def mktempfile(self,data=None):
2415 2415 """Make a new tempfile and return its filename.
2416 2416
2417 2417 This makes a call to tempfile.mktemp, but it registers the created
2418 2418 filename internally so ipython cleans it up at exit time.
2419 2419
2420 2420 Optional inputs:
2421 2421
2422 2422 - data(None): if data is given, it gets written out to the temp file
2423 2423 immediately, and the file is closed again."""
2424 2424
2425 2425 filename = tempfile.mktemp('.py','ipython_edit_')
2426 2426 self.tempfiles.append(filename)
2427 2427
2428 2428 if data:
2429 2429 tmp_file = open(filename,'w')
2430 2430 tmp_file.write(data)
2431 2431 tmp_file.close()
2432 2432 return filename
2433 2433
2434 2434 def write(self,data):
2435 2435 """Write a string to the default output"""
2436 2436 Term.cout.write(data)
2437 2437
2438 2438 def write_err(self,data):
2439 2439 """Write a string to the default error output"""
2440 2440 Term.cerr.write(data)
2441 2441
2442 2442 def ask_yes_no(self,prompt,default=True):
2443 2443 if self.quiet:
2444 2444 return True
2445 2445 return ask_yes_no(prompt,default)
2446 2446
2447 2447 #-------------------------------------------------------------------------
2448 # Things related to GUI support and pylab
2449 #-------------------------------------------------------------------------
2450
2451 def enable_pylab(self, gui=None):
2452 """
2453 """
2454 gui = pylab_activate(self.user_ns, gui)
2455 enable_gui(gui)
2456 self.magic_run = self._pylab_magic_run
2457
2458
2459 #-------------------------------------------------------------------------
2448 2460 # Things related to IPython exiting
2449 2461 #-------------------------------------------------------------------------
2450 2462
2451 2463 def ask_exit(self):
2452 2464 """ Call for exiting. Can be overiden and used as a callback. """
2453 2465 self.exit_now = True
2454 2466
2455 2467 def exit(self):
2456 2468 """Handle interactive exit.
2457 2469
2458 2470 This method calls the ask_exit callback."""
2459 2471 if self.confirm_exit:
2460 2472 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2461 2473 self.ask_exit()
2462 2474 else:
2463 2475 self.ask_exit()
2464 2476
2465 2477 def atexit_operations(self):
2466 2478 """This will be executed at the time of exit.
2467 2479
2468 2480 Saving of persistent data should be performed here.
2469 2481 """
2470 2482 self.savehist()
2471 2483
2472 2484 # Cleanup all tempfiles left around
2473 2485 for tfile in self.tempfiles:
2474 2486 try:
2475 2487 os.unlink(tfile)
2476 2488 except OSError:
2477 2489 pass
2478 2490
2479 2491 # Clear all user namespaces to release all references cleanly.
2480 2492 self.reset()
2481 2493
2482 2494 # Run user hooks
2483 2495 self.hooks.shutdown_hook()
2484 2496
2485 2497 def cleanup(self):
2486 2498 self.restore_sys_module_state()
2487 2499
2488 2500
@@ -1,3765 +1,3626 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #*****************************************************************************
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #*****************************************************************************
12 12
13 13 #****************************************************************************
14 14 # Modules and globals
15 15
16 16 # Python standard modules
17 17 import __builtin__
18 18 import bdb
19 19 import inspect
20 20 import os
21 21 import pdb
22 22 import pydoc
23 23 import sys
24 24 import shutil
25 25 import re
26 26 import tempfile
27 27 import time
28 28 import cPickle as pickle
29 29 import textwrap
30 30 from cStringIO import StringIO
31 31 from getopt import getopt,GetoptError
32 32 from pprint import pprint, pformat
33 33
34 34 # cProfile was added in Python2.5
35 35 try:
36 36 import cProfile as profile
37 37 import pstats
38 38 except ImportError:
39 39 # profile isn't bundled by default in Debian for license reasons
40 40 try:
41 41 import profile,pstats
42 42 except ImportError:
43 43 profile = pstats = None
44 44
45 45 # Homebrewed
46 46 import IPython
47 from IPython.utils import wildcard
47 import IPython.utils.generics
48
48 49 from IPython.core import debugger, oinspect
49 50 from IPython.core.error import TryNext
51 from IPython.core.error import UsageError
50 52 from IPython.core.fakemodule import FakeModule
53 from IPython.core.macro import Macro
54 from IPython.core.page import page
51 55 from IPython.core.prefilter import ESC_MAGIC
56 from IPython.core.pylabtools import mpl_runner
57 from IPython.lib.inputhook import enable_gui
52 58 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
59 from IPython.testing import decorators as testdec
60 from IPython.utils import platutils
61 from IPython.utils import wildcard
53 62 from IPython.utils.PyColorize import Parser
54 63 from IPython.utils.ipstruct import Struct
55 from IPython.core.macro import Macro
64
65 # XXX - We need to switch to explicit imports here with genutils
56 66 from IPython.utils.genutils import *
57 from IPython.core.page import page
58 from IPython.utils import platutils
59 import IPython.utils.generics
60 from IPython.core.error import UsageError
61 from IPython.testing import decorators as testdec
62 67
63 68 #***************************************************************************
64 69 # Utility functions
65 70 def on_off(tag):
66 71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
67 72 return ['OFF','ON'][tag]
68 73
69 74 class Bunch: pass
70 75
71 76 def compress_dhist(dh):
72 77 head, tail = dh[:-10], dh[-10:]
73 78
74 79 newhead = []
75 80 done = set()
76 81 for h in head:
77 82 if h in done:
78 83 continue
79 84 newhead.append(h)
80 85 done.add(h)
81 86
82 87 return newhead + tail
83 88
84 89
85 def pylab_activate(user_ns, gui=None, import_all=True):
86 """Activate pylab mode in the user's namespace.
87
88 Loads and initializes numpy, matplotlib and friends for interactive use.
89
90 Parameters
91 ----------
92 user_ns : dict
93 Namespace where the imports will occur.
94
95 gui : optional, string
96 A valid gui name following the conventions of the %gui magic.
97
98 import_all : optional, boolean
99 If true, an 'import *' is done from numpy and pylab.
100
101 Returns
102 -------
103 The actual gui used (if not given as input, it was obtained from matplotlib
104 itself, and will be needed next to configure IPython's gui integration.
105 """
106
107 # Initialize matplotlib to interactive mode always
108 import matplotlib
109
110 # If user specifies a GUI, that dictates the backend, otherwise we read the
111 # user's mpl default from the mpl rc structure
112 g2b = {'tk': 'TkAgg',
113 'gtk': 'GTKAgg',
114 'wx': 'WXAgg',
115 'qt': 'Qt4Agg', # qt3 not supported
116 'qt4': 'Qt4Agg' }
117
118 if gui:
119 # select backend based on requested gui
120 backend = g2b[gui]
121 else:
122 backend = matplotlib.rcParams['backend']
123 # In this case, we need to find what the appropriate gui selection call
124 # should be for IPython, so we can activate inputhook accordingly
125 b2g = dict(zip(g2b.values(),g2b.keys()))
126 gui = b2g[backend]
127
128 # We must set the desired backend before importing pylab
129 matplotlib.use(backend)
130
131 # This must be imported last in the matplotlib series, after
132 # backend/interactivity choices have been made
133 import matplotlib.pylab as pylab
134
135 # XXX For now leave this commented out, but depending on discussions with
136 # mpl-dev, we may be able to allow interactive switching...
137 #import matplotlib.pyplot
138 #matplotlib.pyplot.switch_backend(backend)
139
140 pylab.show._needmain = False
141 # We need to detect at runtime whether show() is called by the user.
142 # For this, we wrap it into a decorator which adds a 'called' flag.
143 pylab.draw_if_interactive = flag_calls(pylab.draw_if_interactive)
144
145 # Import numpy as np/pyplot as plt are conventions we're trying to
146 # somewhat standardize on. Making them available to users by default
147 # will greatly help this.
148 exec ("import numpy\n"
149 "import numpy as np\n"
150 "import matplotlib\n"
151 "from matplotlib import pylab, mlab, pyplot as plt\n"
152 ) in user_ns
153
154 if import_all:
155 exec("from matplotlib.pylab import *\n"
156 "from numpy import *\n") in user_ns
157
158 matplotlib.interactive(True)
159
160 print """
161 Welcome to pylab, a matplotlib-based Python environment.
162 Backend in use: %s
163 For more information, type 'help(pylab)'.""" % backend
164
165 return gui
166
167 # We need a little factory function here to create the closure where
168 # safe_execfile can live.
169 def mpl_runner(safe_execfile):
170 """Factory to return a matplotlib-enabled runner for %run.
171
172 Parameters
173 ----------
174 safe_execfile : function
175 This must be a function with the same interface as the
176 :meth:`safe_execfile` method of IPython.
177
178 Returns
179 -------
180 A function suitable for use as the ``runner`` argument of the %run magic
181 function.
182 """
183
184 def mpl_execfile(fname,*where,**kw):
185 """matplotlib-aware wrapper around safe_execfile.
186
187 Its interface is identical to that of the :func:`execfile` builtin.
188
189 This is ultimately a call to execfile(), but wrapped in safeties to
190 properly handle interactive rendering."""
191
192 import matplotlib
193 import matplotlib.pylab as pylab
194
195 #print '*** Matplotlib runner ***' # dbg
196 # turn off rendering until end of script
197 is_interactive = matplotlib.rcParams['interactive']
198 matplotlib.interactive(False)
199 safe_execfile(fname,*where,**kw)
200 matplotlib.interactive(is_interactive)
201 # make rendering call now, if the user tried to do it
202 if pylab.draw_if_interactive.called:
203 pylab.draw()
204 pylab.draw_if_interactive.called = False
205
206 return mpl_execfile
207
208
209 90 #***************************************************************************
210 91 # Main class implementing Magic functionality
211 92
212 93 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
213 94 # on construction of the main InteractiveShell object. Something odd is going
214 95 # on with super() calls, Component and the MRO... For now leave it as-is, but
215 96 # eventually this needs to be clarified.
216 97
217 98 class Magic:
218 99 """Magic functions for InteractiveShell.
219 100
220 101 Shell functions which can be reached as %function_name. All magic
221 102 functions should accept a string, which they can parse for their own
222 103 needs. This can make some functions easier to type, eg `%cd ../`
223 104 vs. `%cd("../")`
224 105
225 106 ALL definitions MUST begin with the prefix magic_. The user won't need it
226 107 at the command line, but it is is needed in the definition. """
227 108
228 109 # class globals
229 110 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
230 111 'Automagic is ON, % prefix NOT needed for magic functions.']
231 112
232 113 #......................................................................
233 114 # some utility functions
234 115
235 116 def __init__(self,shell):
236 117
237 118 self.options_table = {}
238 119 if profile is None:
239 120 self.magic_prun = self.profile_missing_notice
240 121 self.shell = shell
241 122
242 123 # namespace for holding state we may need
243 124 self._magic_state = Bunch()
244 125
245 126 def profile_missing_notice(self, *args, **kwargs):
246 127 error("""\
247 128 The profile module could not be found. It has been removed from the standard
248 129 python packages because of its non-free license. To use profiling, install the
249 130 python-profiler package from non-free.""")
250 131
251 132 def default_option(self,fn,optstr):
252 133 """Make an entry in the options_table for fn, with value optstr"""
253 134
254 135 if fn not in self.lsmagic():
255 136 error("%s is not a magic function" % fn)
256 137 self.options_table[fn] = optstr
257 138
258 139 def lsmagic(self):
259 140 """Return a list of currently available magic functions.
260 141
261 142 Gives a list of the bare names after mangling (['ls','cd', ...], not
262 143 ['magic_ls','magic_cd',...]"""
263 144
264 145 # FIXME. This needs a cleanup, in the way the magics list is built.
265 146
266 147 # magics in class definition
267 148 class_magic = lambda fn: fn.startswith('magic_') and \
268 149 callable(Magic.__dict__[fn])
269 150 # in instance namespace (run-time user additions)
270 151 inst_magic = lambda fn: fn.startswith('magic_') and \
271 152 callable(self.__dict__[fn])
272 153 # and bound magics by user (so they can access self):
273 154 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
274 155 callable(self.__class__.__dict__[fn])
275 156 magics = filter(class_magic,Magic.__dict__.keys()) + \
276 157 filter(inst_magic,self.__dict__.keys()) + \
277 158 filter(inst_bound_magic,self.__class__.__dict__.keys())
278 159 out = []
279 160 for fn in set(magics):
280 161 out.append(fn.replace('magic_','',1))
281 162 out.sort()
282 163 return out
283 164
284 165 def extract_input_slices(self,slices,raw=False):
285 166 """Return as a string a set of input history slices.
286 167
287 168 Inputs:
288 169
289 170 - slices: the set of slices is given as a list of strings (like
290 171 ['1','4:8','9'], since this function is for use by magic functions
291 172 which get their arguments as strings.
292 173
293 174 Optional inputs:
294 175
295 176 - raw(False): by default, the processed input is used. If this is
296 177 true, the raw input history is used instead.
297 178
298 179 Note that slices can be called with two notations:
299 180
300 181 N:M -> standard python form, means including items N...(M-1).
301 182
302 183 N-M -> include items N..M (closed endpoint)."""
303 184
304 185 if raw:
305 186 hist = self.shell.input_hist_raw
306 187 else:
307 188 hist = self.shell.input_hist
308 189
309 190 cmds = []
310 191 for chunk in slices:
311 192 if ':' in chunk:
312 193 ini,fin = map(int,chunk.split(':'))
313 194 elif '-' in chunk:
314 195 ini,fin = map(int,chunk.split('-'))
315 196 fin += 1
316 197 else:
317 198 ini = int(chunk)
318 199 fin = ini+1
319 200 cmds.append(hist[ini:fin])
320 201 return cmds
321 202
322 203 def _ofind(self, oname, namespaces=None):
323 204 """Find an object in the available namespaces.
324 205
325 206 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
326 207
327 208 Has special code to detect magic functions.
328 209 """
329 210
330 211 oname = oname.strip()
331 212
332 213 alias_ns = None
333 214 if namespaces is None:
334 215 # Namespaces to search in:
335 216 # Put them in a list. The order is important so that we
336 217 # find things in the same order that Python finds them.
337 218 namespaces = [ ('Interactive', self.shell.user_ns),
338 219 ('IPython internal', self.shell.internal_ns),
339 220 ('Python builtin', __builtin__.__dict__),
340 221 ('Alias', self.shell.alias_manager.alias_table),
341 222 ]
342 223 alias_ns = self.shell.alias_manager.alias_table
343 224
344 225 # initialize results to 'null'
345 226 found = 0; obj = None; ospace = None; ds = None;
346 227 ismagic = 0; isalias = 0; parent = None
347 228
348 229 # Look for the given name by splitting it in parts. If the head is
349 230 # found, then we look for all the remaining parts as members, and only
350 231 # declare success if we can find them all.
351 232 oname_parts = oname.split('.')
352 233 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
353 234 for nsname,ns in namespaces:
354 235 try:
355 236 obj = ns[oname_head]
356 237 except KeyError:
357 238 continue
358 239 else:
359 240 #print 'oname_rest:', oname_rest # dbg
360 241 for part in oname_rest:
361 242 try:
362 243 parent = obj
363 244 obj = getattr(obj,part)
364 245 except:
365 246 # Blanket except b/c some badly implemented objects
366 247 # allow __getattr__ to raise exceptions other than
367 248 # AttributeError, which then crashes IPython.
368 249 break
369 250 else:
370 251 # If we finish the for loop (no break), we got all members
371 252 found = 1
372 253 ospace = nsname
373 254 if ns == alias_ns:
374 255 isalias = 1
375 256 break # namespace loop
376 257
377 258 # Try to see if it's magic
378 259 if not found:
379 260 if oname.startswith(ESC_MAGIC):
380 261 oname = oname[1:]
381 262 obj = getattr(self,'magic_'+oname,None)
382 263 if obj is not None:
383 264 found = 1
384 265 ospace = 'IPython internal'
385 266 ismagic = 1
386 267
387 268 # Last try: special-case some literals like '', [], {}, etc:
388 269 if not found and oname_head in ["''",'""','[]','{}','()']:
389 270 obj = eval(oname_head)
390 271 found = 1
391 272 ospace = 'Interactive'
392 273
393 274 return {'found':found, 'obj':obj, 'namespace':ospace,
394 275 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
395 276
396 277 def arg_err(self,func):
397 278 """Print docstring if incorrect arguments were passed"""
398 279 print 'Error in arguments:'
399 280 print OInspect.getdoc(func)
400 281
401 282 def format_latex(self,strng):
402 283 """Format a string for latex inclusion."""
403 284
404 285 # Characters that need to be escaped for latex:
405 286 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
406 287 # Magic command names as headers:
407 288 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
408 289 re.MULTILINE)
409 290 # Magic commands
410 291 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
411 292 re.MULTILINE)
412 293 # Paragraph continue
413 294 par_re = re.compile(r'\\$',re.MULTILINE)
414 295
415 296 # The "\n" symbol
416 297 newline_re = re.compile(r'\\n')
417 298
418 299 # Now build the string for output:
419 300 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
420 301 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
421 302 strng)
422 303 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
423 304 strng = par_re.sub(r'\\\\',strng)
424 305 strng = escape_re.sub(r'\\\1',strng)
425 306 strng = newline_re.sub(r'\\textbackslash{}n',strng)
426 307 return strng
427 308
428 309 def format_screen(self,strng):
429 310 """Format a string for screen printing.
430 311
431 312 This removes some latex-type format codes."""
432 313 # Paragraph continue
433 314 par_re = re.compile(r'\\$',re.MULTILINE)
434 315 strng = par_re.sub('',strng)
435 316 return strng
436 317
437 318 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
438 319 """Parse options passed to an argument string.
439 320
440 321 The interface is similar to that of getopt(), but it returns back a
441 322 Struct with the options as keys and the stripped argument string still
442 323 as a string.
443 324
444 325 arg_str is quoted as a true sys.argv vector by using shlex.split.
445 326 This allows us to easily expand variables, glob files, quote
446 327 arguments, etc.
447 328
448 329 Options:
449 330 -mode: default 'string'. If given as 'list', the argument string is
450 331 returned as a list (split on whitespace) instead of a string.
451 332
452 333 -list_all: put all option values in lists. Normally only options
453 334 appearing more than once are put in a list.
454 335
455 336 -posix (True): whether to split the input line in POSIX mode or not,
456 337 as per the conventions outlined in the shlex module from the
457 338 standard library."""
458 339
459 340 # inject default options at the beginning of the input line
460 341 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
461 342 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
462 343
463 344 mode = kw.get('mode','string')
464 345 if mode not in ['string','list']:
465 346 raise ValueError,'incorrect mode given: %s' % mode
466 347 # Get options
467 348 list_all = kw.get('list_all',0)
468 349 posix = kw.get('posix',True)
469 350
470 351 # Check if we have more than one argument to warrant extra processing:
471 352 odict = {} # Dictionary with options
472 353 args = arg_str.split()
473 354 if len(args) >= 1:
474 355 # If the list of inputs only has 0 or 1 thing in it, there's no
475 356 # need to look for options
476 357 argv = arg_split(arg_str,posix)
477 358 # Do regular option processing
478 359 try:
479 360 opts,args = getopt(argv,opt_str,*long_opts)
480 361 except GetoptError,e:
481 362 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
482 363 " ".join(long_opts)))
483 364 for o,a in opts:
484 365 if o.startswith('--'):
485 366 o = o[2:]
486 367 else:
487 368 o = o[1:]
488 369 try:
489 370 odict[o].append(a)
490 371 except AttributeError:
491 372 odict[o] = [odict[o],a]
492 373 except KeyError:
493 374 if list_all:
494 375 odict[o] = [a]
495 376 else:
496 377 odict[o] = a
497 378
498 379 # Prepare opts,args for return
499 380 opts = Struct(odict)
500 381 if mode == 'string':
501 382 args = ' '.join(args)
502 383
503 384 return opts,args
504 385
505 386 #......................................................................
506 387 # And now the actual magic functions
507 388
508 389 # Functions for IPython shell work (vars,funcs, config, etc)
509 390 def magic_lsmagic(self, parameter_s = ''):
510 391 """List currently available magic functions."""
511 392 mesc = ESC_MAGIC
512 393 print 'Available magic functions:\n'+mesc+\
513 394 (' '+mesc).join(self.lsmagic())
514 395 print '\n' + Magic.auto_status[self.shell.automagic]
515 396 return None
516 397
517 398 def magic_magic(self, parameter_s = ''):
518 399 """Print information about the magic function system.
519 400
520 401 Supported formats: -latex, -brief, -rest
521 402 """
522 403
523 404 mode = ''
524 405 try:
525 406 if parameter_s.split()[0] == '-latex':
526 407 mode = 'latex'
527 408 if parameter_s.split()[0] == '-brief':
528 409 mode = 'brief'
529 410 if parameter_s.split()[0] == '-rest':
530 411 mode = 'rest'
531 412 rest_docs = []
532 413 except:
533 414 pass
534 415
535 416 magic_docs = []
536 417 for fname in self.lsmagic():
537 418 mname = 'magic_' + fname
538 419 for space in (Magic,self,self.__class__):
539 420 try:
540 421 fn = space.__dict__[mname]
541 422 except KeyError:
542 423 pass
543 424 else:
544 425 break
545 426 if mode == 'brief':
546 427 # only first line
547 428 if fn.__doc__:
548 429 fndoc = fn.__doc__.split('\n',1)[0]
549 430 else:
550 431 fndoc = 'No documentation'
551 432 else:
552 433 if fn.__doc__:
553 434 fndoc = fn.__doc__.rstrip()
554 435 else:
555 436 fndoc = 'No documentation'
556 437
557 438
558 439 if mode == 'rest':
559 440 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
560 441 fname,fndoc))
561 442
562 443 else:
563 444 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
564 445 fname,fndoc))
565 446
566 447 magic_docs = ''.join(magic_docs)
567 448
568 449 if mode == 'rest':
569 450 return "".join(rest_docs)
570 451
571 452 if mode == 'latex':
572 453 print self.format_latex(magic_docs)
573 454 return
574 455 else:
575 456 magic_docs = self.format_screen(magic_docs)
576 457 if mode == 'brief':
577 458 return magic_docs
578 459
579 460 outmsg = """
580 461 IPython's 'magic' functions
581 462 ===========================
582 463
583 464 The magic function system provides a series of functions which allow you to
584 465 control the behavior of IPython itself, plus a lot of system-type
585 466 features. All these functions are prefixed with a % character, but parameters
586 467 are given without parentheses or quotes.
587 468
588 469 NOTE: If you have 'automagic' enabled (via the command line option or with the
589 470 %automagic function), you don't need to type in the % explicitly. By default,
590 471 IPython ships with automagic on, so you should only rarely need the % escape.
591 472
592 473 Example: typing '%cd mydir' (without the quotes) changes you working directory
593 474 to 'mydir', if it exists.
594 475
595 476 You can define your own magic functions to extend the system. See the supplied
596 477 ipythonrc and example-magic.py files for details (in your ipython
597 478 configuration directory, typically $HOME/.ipython/).
598 479
599 480 You can also define your own aliased names for magic functions. In your
600 481 ipythonrc file, placing a line like:
601 482
602 483 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
603 484
604 485 will define %pf as a new name for %profile.
605 486
606 487 You can also call magics in code using the magic() function, which IPython
607 488 automatically adds to the builtin namespace. Type 'magic?' for details.
608 489
609 490 For a list of the available magic functions, use %lsmagic. For a description
610 491 of any of them, type %magic_name?, e.g. '%cd?'.
611 492
612 493 Currently the magic system has the following functions:\n"""
613 494
614 495 mesc = ESC_MAGIC
615 496 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
616 497 "\n\n%s%s\n\n%s" % (outmsg,
617 498 magic_docs,mesc,mesc,
618 499 (' '+mesc).join(self.lsmagic()),
619 500 Magic.auto_status[self.shell.automagic] ) )
620 501
621 502 page(outmsg,screen_lines=self.shell.usable_screen_length)
622 503
623 504
624 505 def magic_autoindent(self, parameter_s = ''):
625 506 """Toggle autoindent on/off (if available)."""
626 507
627 508 self.shell.set_autoindent()
628 509 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
629 510
630 511
631 512 def magic_automagic(self, parameter_s = ''):
632 513 """Make magic functions callable without having to type the initial %.
633 514
634 515 Without argumentsl toggles on/off (when off, you must call it as
635 516 %automagic, of course). With arguments it sets the value, and you can
636 517 use any of (case insensitive):
637 518
638 519 - on,1,True: to activate
639 520
640 521 - off,0,False: to deactivate.
641 522
642 523 Note that magic functions have lowest priority, so if there's a
643 524 variable whose name collides with that of a magic fn, automagic won't
644 525 work for that function (you get the variable instead). However, if you
645 526 delete the variable (del var), the previously shadowed magic function
646 527 becomes visible to automagic again."""
647 528
648 529 arg = parameter_s.lower()
649 530 if parameter_s in ('on','1','true'):
650 531 self.shell.automagic = True
651 532 elif parameter_s in ('off','0','false'):
652 533 self.shell.automagic = False
653 534 else:
654 535 self.shell.automagic = not self.shell.automagic
655 536 print '\n' + Magic.auto_status[self.shell.automagic]
656 537
657 538 @testdec.skip_doctest
658 539 def magic_autocall(self, parameter_s = ''):
659 540 """Make functions callable without having to type parentheses.
660 541
661 542 Usage:
662 543
663 544 %autocall [mode]
664 545
665 546 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
666 547 value is toggled on and off (remembering the previous state).
667 548
668 549 In more detail, these values mean:
669 550
670 551 0 -> fully disabled
671 552
672 553 1 -> active, but do not apply if there are no arguments on the line.
673 554
674 555 In this mode, you get:
675 556
676 557 In [1]: callable
677 558 Out[1]: <built-in function callable>
678 559
679 560 In [2]: callable 'hello'
680 561 ------> callable('hello')
681 562 Out[2]: False
682 563
683 564 2 -> Active always. Even if no arguments are present, the callable
684 565 object is called:
685 566
686 567 In [2]: float
687 568 ------> float()
688 569 Out[2]: 0.0
689 570
690 571 Note that even with autocall off, you can still use '/' at the start of
691 572 a line to treat the first argument on the command line as a function
692 573 and add parentheses to it:
693 574
694 575 In [8]: /str 43
695 576 ------> str(43)
696 577 Out[8]: '43'
697 578
698 579 # all-random (note for auto-testing)
699 580 """
700 581
701 582 if parameter_s:
702 583 arg = int(parameter_s)
703 584 else:
704 585 arg = 'toggle'
705 586
706 587 if not arg in (0,1,2,'toggle'):
707 588 error('Valid modes: (0->Off, 1->Smart, 2->Full')
708 589 return
709 590
710 591 if arg in (0,1,2):
711 592 self.shell.autocall = arg
712 593 else: # toggle
713 594 if self.shell.autocall:
714 595 self._magic_state.autocall_save = self.shell.autocall
715 596 self.shell.autocall = 0
716 597 else:
717 598 try:
718 599 self.shell.autocall = self._magic_state.autocall_save
719 600 except AttributeError:
720 601 self.shell.autocall = self._magic_state.autocall_save = 1
721 602
722 603 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
723 604
724 605 def magic_system_verbose(self, parameter_s = ''):
725 606 """Set verbose printing of system calls.
726 607
727 608 If called without an argument, act as a toggle"""
728 609
729 610 if parameter_s:
730 611 val = bool(eval(parameter_s))
731 612 else:
732 613 val = None
733 614
734 615 if self.shell.system_verbose:
735 616 self.shell.system_verbose = False
736 617 else:
737 618 self.shell.system_verbose = True
738 619 print "System verbose printing is:",\
739 620 ['OFF','ON'][self.shell.system_verbose]
740 621
741 622
742 623 def magic_page(self, parameter_s=''):
743 624 """Pretty print the object and display it through a pager.
744 625
745 626 %page [options] OBJECT
746 627
747 628 If no object is given, use _ (last output).
748 629
749 630 Options:
750 631
751 632 -r: page str(object), don't pretty-print it."""
752 633
753 634 # After a function contributed by Olivier Aubert, slightly modified.
754 635
755 636 # Process options/args
756 637 opts,args = self.parse_options(parameter_s,'r')
757 638 raw = 'r' in opts
758 639
759 640 oname = args and args or '_'
760 641 info = self._ofind(oname)
761 642 if info['found']:
762 643 txt = (raw and str or pformat)( info['obj'] )
763 644 page(txt)
764 645 else:
765 646 print 'Object `%s` not found' % oname
766 647
767 648 def magic_profile(self, parameter_s=''):
768 649 """Print your currently active IPyhton profile."""
769 650 if self.shell.profile:
770 651 printpl('Current IPython profile: $self.shell.profile.')
771 652 else:
772 653 print 'No profile active.'
773 654
774 655 def magic_pinfo(self, parameter_s='', namespaces=None):
775 656 """Provide detailed information about an object.
776 657
777 658 '%pinfo object' is just a synonym for object? or ?object."""
778 659
779 660 #print 'pinfo par: <%s>' % parameter_s # dbg
780 661
781 662
782 663 # detail_level: 0 -> obj? , 1 -> obj??
783 664 detail_level = 0
784 665 # We need to detect if we got called as 'pinfo pinfo foo', which can
785 666 # happen if the user types 'pinfo foo?' at the cmd line.
786 667 pinfo,qmark1,oname,qmark2 = \
787 668 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
788 669 if pinfo or qmark1 or qmark2:
789 670 detail_level = 1
790 671 if "*" in oname:
791 672 self.magic_psearch(oname)
792 673 else:
793 674 self._inspect('pinfo', oname, detail_level=detail_level,
794 675 namespaces=namespaces)
795 676
796 677 def magic_pdef(self, parameter_s='', namespaces=None):
797 678 """Print the definition header for any callable object.
798 679
799 680 If the object is a class, print the constructor information."""
800 681 self._inspect('pdef',parameter_s, namespaces)
801 682
802 683 def magic_pdoc(self, parameter_s='', namespaces=None):
803 684 """Print the docstring for an object.
804 685
805 686 If the given object is a class, it will print both the class and the
806 687 constructor docstrings."""
807 688 self._inspect('pdoc',parameter_s, namespaces)
808 689
809 690 def magic_psource(self, parameter_s='', namespaces=None):
810 691 """Print (or run through pager) the source code for an object."""
811 692 self._inspect('psource',parameter_s, namespaces)
812 693
813 694 def magic_pfile(self, parameter_s=''):
814 695 """Print (or run through pager) the file where an object is defined.
815 696
816 697 The file opens at the line where the object definition begins. IPython
817 698 will honor the environment variable PAGER if set, and otherwise will
818 699 do its best to print the file in a convenient form.
819 700
820 701 If the given argument is not an object currently defined, IPython will
821 702 try to interpret it as a filename (automatically adding a .py extension
822 703 if needed). You can thus use %pfile as a syntax highlighting code
823 704 viewer."""
824 705
825 706 # first interpret argument as an object name
826 707 out = self._inspect('pfile',parameter_s)
827 708 # if not, try the input as a filename
828 709 if out == 'not found':
829 710 try:
830 711 filename = get_py_filename(parameter_s)
831 712 except IOError,msg:
832 713 print msg
833 714 return
834 715 page(self.shell.inspector.format(file(filename).read()))
835 716
836 717 def _inspect(self,meth,oname,namespaces=None,**kw):
837 718 """Generic interface to the inspector system.
838 719
839 720 This function is meant to be called by pdef, pdoc & friends."""
840 721
841 722 #oname = oname.strip()
842 723 #print '1- oname: <%r>' % oname # dbg
843 724 try:
844 725 oname = oname.strip().encode('ascii')
845 726 #print '2- oname: <%r>' % oname # dbg
846 727 except UnicodeEncodeError:
847 728 print 'Python identifiers can only contain ascii characters.'
848 729 return 'not found'
849 730
850 731 info = Struct(self._ofind(oname, namespaces))
851 732
852 733 if info.found:
853 734 try:
854 735 IPython.utils.generics.inspect_object(info.obj)
855 736 return
856 737 except TryNext:
857 738 pass
858 739 # Get the docstring of the class property if it exists.
859 740 path = oname.split('.')
860 741 root = '.'.join(path[:-1])
861 742 if info.parent is not None:
862 743 try:
863 744 target = getattr(info.parent, '__class__')
864 745 # The object belongs to a class instance.
865 746 try:
866 747 target = getattr(target, path[-1])
867 748 # The class defines the object.
868 749 if isinstance(target, property):
869 750 oname = root + '.__class__.' + path[-1]
870 751 info = Struct(self._ofind(oname))
871 752 except AttributeError: pass
872 753 except AttributeError: pass
873 754
874 755 pmethod = getattr(self.shell.inspector,meth)
875 756 formatter = info.ismagic and self.format_screen or None
876 757 if meth == 'pdoc':
877 758 pmethod(info.obj,oname,formatter)
878 759 elif meth == 'pinfo':
879 760 pmethod(info.obj,oname,formatter,info,**kw)
880 761 else:
881 762 pmethod(info.obj,oname)
882 763 else:
883 764 print 'Object `%s` not found.' % oname
884 765 return 'not found' # so callers can take other action
885 766
886 767 def magic_psearch(self, parameter_s=''):
887 768 """Search for object in namespaces by wildcard.
888 769
889 770 %psearch [options] PATTERN [OBJECT TYPE]
890 771
891 772 Note: ? can be used as a synonym for %psearch, at the beginning or at
892 773 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
893 774 rest of the command line must be unchanged (options come first), so
894 775 for example the following forms are equivalent
895 776
896 777 %psearch -i a* function
897 778 -i a* function?
898 779 ?-i a* function
899 780
900 781 Arguments:
901 782
902 783 PATTERN
903 784
904 785 where PATTERN is a string containing * as a wildcard similar to its
905 786 use in a shell. The pattern is matched in all namespaces on the
906 787 search path. By default objects starting with a single _ are not
907 788 matched, many IPython generated objects have a single
908 789 underscore. The default is case insensitive matching. Matching is
909 790 also done on the attributes of objects and not only on the objects
910 791 in a module.
911 792
912 793 [OBJECT TYPE]
913 794
914 795 Is the name of a python type from the types module. The name is
915 796 given in lowercase without the ending type, ex. StringType is
916 797 written string. By adding a type here only objects matching the
917 798 given type are matched. Using all here makes the pattern match all
918 799 types (this is the default).
919 800
920 801 Options:
921 802
922 803 -a: makes the pattern match even objects whose names start with a
923 804 single underscore. These names are normally ommitted from the
924 805 search.
925 806
926 807 -i/-c: make the pattern case insensitive/sensitive. If neither of
927 808 these options is given, the default is read from your ipythonrc
928 809 file. The option name which sets this value is
929 810 'wildcards_case_sensitive'. If this option is not specified in your
930 811 ipythonrc file, IPython's internal default is to do a case sensitive
931 812 search.
932 813
933 814 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
934 815 specifiy can be searched in any of the following namespaces:
935 816 'builtin', 'user', 'user_global','internal', 'alias', where
936 817 'builtin' and 'user' are the search defaults. Note that you should
937 818 not use quotes when specifying namespaces.
938 819
939 820 'Builtin' contains the python module builtin, 'user' contains all
940 821 user data, 'alias' only contain the shell aliases and no python
941 822 objects, 'internal' contains objects used by IPython. The
942 823 'user_global' namespace is only used by embedded IPython instances,
943 824 and it contains module-level globals. You can add namespaces to the
944 825 search with -s or exclude them with -e (these options can be given
945 826 more than once).
946 827
947 828 Examples:
948 829
949 830 %psearch a* -> objects beginning with an a
950 831 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
951 832 %psearch a* function -> all functions beginning with an a
952 833 %psearch re.e* -> objects beginning with an e in module re
953 834 %psearch r*.e* -> objects that start with e in modules starting in r
954 835 %psearch r*.* string -> all strings in modules beginning with r
955 836
956 837 Case sensitve search:
957 838
958 839 %psearch -c a* list all object beginning with lower case a
959 840
960 841 Show objects beginning with a single _:
961 842
962 843 %psearch -a _* list objects beginning with a single underscore"""
963 844 try:
964 845 parameter_s = parameter_s.encode('ascii')
965 846 except UnicodeEncodeError:
966 847 print 'Python identifiers can only contain ascii characters.'
967 848 return
968 849
969 850 # default namespaces to be searched
970 851 def_search = ['user','builtin']
971 852
972 853 # Process options/args
973 854 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
974 855 opt = opts.get
975 856 shell = self.shell
976 857 psearch = shell.inspector.psearch
977 858
978 859 # select case options
979 860 if opts.has_key('i'):
980 861 ignore_case = True
981 862 elif opts.has_key('c'):
982 863 ignore_case = False
983 864 else:
984 865 ignore_case = not shell.wildcards_case_sensitive
985 866
986 867 # Build list of namespaces to search from user options
987 868 def_search.extend(opt('s',[]))
988 869 ns_exclude = ns_exclude=opt('e',[])
989 870 ns_search = [nm for nm in def_search if nm not in ns_exclude]
990 871
991 872 # Call the actual search
992 873 try:
993 874 psearch(args,shell.ns_table,ns_search,
994 875 show_all=opt('a'),ignore_case=ignore_case)
995 876 except:
996 877 shell.showtraceback()
997 878
998 879 def magic_who_ls(self, parameter_s=''):
999 880 """Return a sorted list of all interactive variables.
1000 881
1001 882 If arguments are given, only variables of types matching these
1002 883 arguments are returned."""
1003 884
1004 885 user_ns = self.shell.user_ns
1005 886 internal_ns = self.shell.internal_ns
1006 887 user_config_ns = self.shell.user_config_ns
1007 888 out = []
1008 889 typelist = parameter_s.split()
1009 890
1010 891 for i in user_ns:
1011 892 if not (i.startswith('_') or i.startswith('_i')) \
1012 893 and not (i in internal_ns or i in user_config_ns):
1013 894 if typelist:
1014 895 if type(user_ns[i]).__name__ in typelist:
1015 896 out.append(i)
1016 897 else:
1017 898 out.append(i)
1018 899 out.sort()
1019 900 return out
1020 901
1021 902 def magic_who(self, parameter_s=''):
1022 903 """Print all interactive variables, with some minimal formatting.
1023 904
1024 905 If any arguments are given, only variables whose type matches one of
1025 906 these are printed. For example:
1026 907
1027 908 %who function str
1028 909
1029 910 will only list functions and strings, excluding all other types of
1030 911 variables. To find the proper type names, simply use type(var) at a
1031 912 command line to see how python prints type names. For example:
1032 913
1033 914 In [1]: type('hello')\\
1034 915 Out[1]: <type 'str'>
1035 916
1036 917 indicates that the type name for strings is 'str'.
1037 918
1038 919 %who always excludes executed names loaded through your configuration
1039 920 file and things which are internal to IPython.
1040 921
1041 922 This is deliberate, as typically you may load many modules and the
1042 923 purpose of %who is to show you only what you've manually defined."""
1043 924
1044 925 varlist = self.magic_who_ls(parameter_s)
1045 926 if not varlist:
1046 927 if parameter_s:
1047 928 print 'No variables match your requested type.'
1048 929 else:
1049 930 print 'Interactive namespace is empty.'
1050 931 return
1051 932
1052 933 # if we have variables, move on...
1053 934 count = 0
1054 935 for i in varlist:
1055 936 print i+'\t',
1056 937 count += 1
1057 938 if count > 8:
1058 939 count = 0
1059 940 print
1060 941 print
1061 942
1062 943 def magic_whos(self, parameter_s=''):
1063 944 """Like %who, but gives some extra information about each variable.
1064 945
1065 946 The same type filtering of %who can be applied here.
1066 947
1067 948 For all variables, the type is printed. Additionally it prints:
1068 949
1069 950 - For {},[],(): their length.
1070 951
1071 952 - For numpy and Numeric arrays, a summary with shape, number of
1072 953 elements, typecode and size in memory.
1073 954
1074 955 - Everything else: a string representation, snipping their middle if
1075 956 too long."""
1076 957
1077 958 varnames = self.magic_who_ls(parameter_s)
1078 959 if not varnames:
1079 960 if parameter_s:
1080 961 print 'No variables match your requested type.'
1081 962 else:
1082 963 print 'Interactive namespace is empty.'
1083 964 return
1084 965
1085 966 # if we have variables, move on...
1086 967
1087 968 # for these types, show len() instead of data:
1088 969 seq_types = [types.DictType,types.ListType,types.TupleType]
1089 970
1090 971 # for numpy/Numeric arrays, display summary info
1091 972 try:
1092 973 import numpy
1093 974 except ImportError:
1094 975 ndarray_type = None
1095 976 else:
1096 977 ndarray_type = numpy.ndarray.__name__
1097 978 try:
1098 979 import Numeric
1099 980 except ImportError:
1100 981 array_type = None
1101 982 else:
1102 983 array_type = Numeric.ArrayType.__name__
1103 984
1104 985 # Find all variable names and types so we can figure out column sizes
1105 986 def get_vars(i):
1106 987 return self.shell.user_ns[i]
1107 988
1108 989 # some types are well known and can be shorter
1109 990 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
1110 991 def type_name(v):
1111 992 tn = type(v).__name__
1112 993 return abbrevs.get(tn,tn)
1113 994
1114 995 varlist = map(get_vars,varnames)
1115 996
1116 997 typelist = []
1117 998 for vv in varlist:
1118 999 tt = type_name(vv)
1119 1000
1120 1001 if tt=='instance':
1121 1002 typelist.append( abbrevs.get(str(vv.__class__),
1122 1003 str(vv.__class__)))
1123 1004 else:
1124 1005 typelist.append(tt)
1125 1006
1126 1007 # column labels and # of spaces as separator
1127 1008 varlabel = 'Variable'
1128 1009 typelabel = 'Type'
1129 1010 datalabel = 'Data/Info'
1130 1011 colsep = 3
1131 1012 # variable format strings
1132 1013 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1133 1014 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1134 1015 aformat = "%s: %s elems, type `%s`, %s bytes"
1135 1016 # find the size of the columns to format the output nicely
1136 1017 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1137 1018 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1138 1019 # table header
1139 1020 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1140 1021 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1141 1022 # and the table itself
1142 1023 kb = 1024
1143 1024 Mb = 1048576 # kb**2
1144 1025 for vname,var,vtype in zip(varnames,varlist,typelist):
1145 1026 print itpl(vformat),
1146 1027 if vtype in seq_types:
1147 1028 print len(var)
1148 1029 elif vtype in [array_type,ndarray_type]:
1149 1030 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1150 1031 if vtype==ndarray_type:
1151 1032 # numpy
1152 1033 vsize = var.size
1153 1034 vbytes = vsize*var.itemsize
1154 1035 vdtype = var.dtype
1155 1036 else:
1156 1037 # Numeric
1157 1038 vsize = Numeric.size(var)
1158 1039 vbytes = vsize*var.itemsize()
1159 1040 vdtype = var.typecode()
1160 1041
1161 1042 if vbytes < 100000:
1162 1043 print aformat % (vshape,vsize,vdtype,vbytes)
1163 1044 else:
1164 1045 print aformat % (vshape,vsize,vdtype,vbytes),
1165 1046 if vbytes < Mb:
1166 1047 print '(%s kb)' % (vbytes/kb,)
1167 1048 else:
1168 1049 print '(%s Mb)' % (vbytes/Mb,)
1169 1050 else:
1170 1051 try:
1171 1052 vstr = str(var)
1172 1053 except UnicodeEncodeError:
1173 1054 vstr = unicode(var).encode(sys.getdefaultencoding(),
1174 1055 'backslashreplace')
1175 1056 vstr = vstr.replace('\n','\\n')
1176 1057 if len(vstr) < 50:
1177 1058 print vstr
1178 1059 else:
1179 1060 printpl(vfmt_short)
1180 1061
1181 1062 def magic_reset(self, parameter_s=''):
1182 1063 """Resets the namespace by removing all names defined by the user.
1183 1064
1184 1065 Input/Output history are left around in case you need them.
1185 1066
1186 1067 Parameters
1187 1068 ----------
1188 1069 -y : force reset without asking for confirmation.
1189 1070
1190 1071 Examples
1191 1072 --------
1192 1073 In [6]: a = 1
1193 1074
1194 1075 In [7]: a
1195 1076 Out[7]: 1
1196 1077
1197 1078 In [8]: 'a' in _ip.user_ns
1198 1079 Out[8]: True
1199 1080
1200 1081 In [9]: %reset -f
1201 1082
1202 1083 In [10]: 'a' in _ip.user_ns
1203 1084 Out[10]: False
1204 1085 """
1205 1086
1206 1087 if parameter_s == '-f':
1207 1088 ans = True
1208 1089 else:
1209 1090 ans = self.shell.ask_yes_no(
1210 1091 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1211 1092 if not ans:
1212 1093 print 'Nothing done.'
1213 1094 return
1214 1095 user_ns = self.shell.user_ns
1215 1096 for i in self.magic_who_ls():
1216 1097 del(user_ns[i])
1217 1098
1218 1099 # Also flush the private list of module references kept for script
1219 1100 # execution protection
1220 1101 self.shell.clear_main_mod_cache()
1221 1102
1222 1103 def magic_logstart(self,parameter_s=''):
1223 1104 """Start logging anywhere in a session.
1224 1105
1225 1106 %logstart [-o|-r|-t] [log_name [log_mode]]
1226 1107
1227 1108 If no name is given, it defaults to a file named 'ipython_log.py' in your
1228 1109 current directory, in 'rotate' mode (see below).
1229 1110
1230 1111 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1231 1112 history up to that point and then continues logging.
1232 1113
1233 1114 %logstart takes a second optional parameter: logging mode. This can be one
1234 1115 of (note that the modes are given unquoted):\\
1235 1116 append: well, that says it.\\
1236 1117 backup: rename (if exists) to name~ and start name.\\
1237 1118 global: single logfile in your home dir, appended to.\\
1238 1119 over : overwrite existing log.\\
1239 1120 rotate: create rotating logs name.1~, name.2~, etc.
1240 1121
1241 1122 Options:
1242 1123
1243 1124 -o: log also IPython's output. In this mode, all commands which
1244 1125 generate an Out[NN] prompt are recorded to the logfile, right after
1245 1126 their corresponding input line. The output lines are always
1246 1127 prepended with a '#[Out]# ' marker, so that the log remains valid
1247 1128 Python code.
1248 1129
1249 1130 Since this marker is always the same, filtering only the output from
1250 1131 a log is very easy, using for example a simple awk call:
1251 1132
1252 1133 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1253 1134
1254 1135 -r: log 'raw' input. Normally, IPython's logs contain the processed
1255 1136 input, so that user lines are logged in their final form, converted
1256 1137 into valid Python. For example, %Exit is logged as
1257 1138 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1258 1139 exactly as typed, with no transformations applied.
1259 1140
1260 1141 -t: put timestamps before each input line logged (these are put in
1261 1142 comments)."""
1262 1143
1263 1144 opts,par = self.parse_options(parameter_s,'ort')
1264 1145 log_output = 'o' in opts
1265 1146 log_raw_input = 'r' in opts
1266 1147 timestamp = 't' in opts
1267 1148
1268 1149 logger = self.shell.logger
1269 1150
1270 1151 # if no args are given, the defaults set in the logger constructor by
1271 1152 # ipytohn remain valid
1272 1153 if par:
1273 1154 try:
1274 1155 logfname,logmode = par.split()
1275 1156 except:
1276 1157 logfname = par
1277 1158 logmode = 'backup'
1278 1159 else:
1279 1160 logfname = logger.logfname
1280 1161 logmode = logger.logmode
1281 1162 # put logfname into rc struct as if it had been called on the command
1282 1163 # line, so it ends up saved in the log header Save it in case we need
1283 1164 # to restore it...
1284 1165 old_logfile = self.shell.logfile
1285 1166 if logfname:
1286 1167 logfname = os.path.expanduser(logfname)
1287 1168 self.shell.logfile = logfname
1288 1169
1289 1170 loghead = '# IPython log file\n\n'
1290 1171 try:
1291 1172 started = logger.logstart(logfname,loghead,logmode,
1292 1173 log_output,timestamp,log_raw_input)
1293 1174 except:
1294 1175 rc.opts.logfile = old_logfile
1295 1176 warn("Couldn't start log: %s" % sys.exc_info()[1])
1296 1177 else:
1297 1178 # log input history up to this point, optionally interleaving
1298 1179 # output if requested
1299 1180
1300 1181 if timestamp:
1301 1182 # disable timestamping for the previous history, since we've
1302 1183 # lost those already (no time machine here).
1303 1184 logger.timestamp = False
1304 1185
1305 1186 if log_raw_input:
1306 1187 input_hist = self.shell.input_hist_raw
1307 1188 else:
1308 1189 input_hist = self.shell.input_hist
1309 1190
1310 1191 if log_output:
1311 1192 log_write = logger.log_write
1312 1193 output_hist = self.shell.output_hist
1313 1194 for n in range(1,len(input_hist)-1):
1314 1195 log_write(input_hist[n].rstrip())
1315 1196 if n in output_hist:
1316 1197 log_write(repr(output_hist[n]),'output')
1317 1198 else:
1318 1199 logger.log_write(input_hist[1:])
1319 1200 if timestamp:
1320 1201 # re-enable timestamping
1321 1202 logger.timestamp = True
1322 1203
1323 1204 print ('Activating auto-logging. '
1324 1205 'Current session state plus future input saved.')
1325 1206 logger.logstate()
1326 1207
1327 1208 def magic_logstop(self,parameter_s=''):
1328 1209 """Fully stop logging and close log file.
1329 1210
1330 1211 In order to start logging again, a new %logstart call needs to be made,
1331 1212 possibly (though not necessarily) with a new filename, mode and other
1332 1213 options."""
1333 1214 self.logger.logstop()
1334 1215
1335 1216 def magic_logoff(self,parameter_s=''):
1336 1217 """Temporarily stop logging.
1337 1218
1338 1219 You must have previously started logging."""
1339 1220 self.shell.logger.switch_log(0)
1340 1221
1341 1222 def magic_logon(self,parameter_s=''):
1342 1223 """Restart logging.
1343 1224
1344 1225 This function is for restarting logging which you've temporarily
1345 1226 stopped with %logoff. For starting logging for the first time, you
1346 1227 must use the %logstart function, which allows you to specify an
1347 1228 optional log filename."""
1348 1229
1349 1230 self.shell.logger.switch_log(1)
1350 1231
1351 1232 def magic_logstate(self,parameter_s=''):
1352 1233 """Print the status of the logging system."""
1353 1234
1354 1235 self.shell.logger.logstate()
1355 1236
1356 1237 def magic_pdb(self, parameter_s=''):
1357 1238 """Control the automatic calling of the pdb interactive debugger.
1358 1239
1359 1240 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1360 1241 argument it works as a toggle.
1361 1242
1362 1243 When an exception is triggered, IPython can optionally call the
1363 1244 interactive pdb debugger after the traceback printout. %pdb toggles
1364 1245 this feature on and off.
1365 1246
1366 1247 The initial state of this feature is set in your ipythonrc
1367 1248 configuration file (the variable is called 'pdb').
1368 1249
1369 1250 If you want to just activate the debugger AFTER an exception has fired,
1370 1251 without having to type '%pdb on' and rerunning your code, you can use
1371 1252 the %debug magic."""
1372 1253
1373 1254 par = parameter_s.strip().lower()
1374 1255
1375 1256 if par:
1376 1257 try:
1377 1258 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1378 1259 except KeyError:
1379 1260 print ('Incorrect argument. Use on/1, off/0, '
1380 1261 'or nothing for a toggle.')
1381 1262 return
1382 1263 else:
1383 1264 # toggle
1384 1265 new_pdb = not self.shell.call_pdb
1385 1266
1386 1267 # set on the shell
1387 1268 self.shell.call_pdb = new_pdb
1388 1269 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1389 1270
1390 1271 def magic_debug(self, parameter_s=''):
1391 1272 """Activate the interactive debugger in post-mortem mode.
1392 1273
1393 1274 If an exception has just occurred, this lets you inspect its stack
1394 1275 frames interactively. Note that this will always work only on the last
1395 1276 traceback that occurred, so you must call this quickly after an
1396 1277 exception that you wish to inspect has fired, because if another one
1397 1278 occurs, it clobbers the previous one.
1398 1279
1399 1280 If you want IPython to automatically do this on every exception, see
1400 1281 the %pdb magic for more details.
1401 1282 """
1402 1283 self.shell.debugger(force=True)
1403 1284
1404 1285 @testdec.skip_doctest
1405 1286 def magic_prun(self, parameter_s ='',user_mode=1,
1406 1287 opts=None,arg_lst=None,prog_ns=None):
1407 1288
1408 1289 """Run a statement through the python code profiler.
1409 1290
1410 1291 Usage:
1411 1292 %prun [options] statement
1412 1293
1413 1294 The given statement (which doesn't require quote marks) is run via the
1414 1295 python profiler in a manner similar to the profile.run() function.
1415 1296 Namespaces are internally managed to work correctly; profile.run
1416 1297 cannot be used in IPython because it makes certain assumptions about
1417 1298 namespaces which do not hold under IPython.
1418 1299
1419 1300 Options:
1420 1301
1421 1302 -l <limit>: you can place restrictions on what or how much of the
1422 1303 profile gets printed. The limit value can be:
1423 1304
1424 1305 * A string: only information for function names containing this string
1425 1306 is printed.
1426 1307
1427 1308 * An integer: only these many lines are printed.
1428 1309
1429 1310 * A float (between 0 and 1): this fraction of the report is printed
1430 1311 (for example, use a limit of 0.4 to see the topmost 40% only).
1431 1312
1432 1313 You can combine several limits with repeated use of the option. For
1433 1314 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1434 1315 information about class constructors.
1435 1316
1436 1317 -r: return the pstats.Stats object generated by the profiling. This
1437 1318 object has all the information about the profile in it, and you can
1438 1319 later use it for further analysis or in other functions.
1439 1320
1440 1321 -s <key>: sort profile by given key. You can provide more than one key
1441 1322 by using the option several times: '-s key1 -s key2 -s key3...'. The
1442 1323 default sorting key is 'time'.
1443 1324
1444 1325 The following is copied verbatim from the profile documentation
1445 1326 referenced below:
1446 1327
1447 1328 When more than one key is provided, additional keys are used as
1448 1329 secondary criteria when the there is equality in all keys selected
1449 1330 before them.
1450 1331
1451 1332 Abbreviations can be used for any key names, as long as the
1452 1333 abbreviation is unambiguous. The following are the keys currently
1453 1334 defined:
1454 1335
1455 1336 Valid Arg Meaning
1456 1337 "calls" call count
1457 1338 "cumulative" cumulative time
1458 1339 "file" file name
1459 1340 "module" file name
1460 1341 "pcalls" primitive call count
1461 1342 "line" line number
1462 1343 "name" function name
1463 1344 "nfl" name/file/line
1464 1345 "stdname" standard name
1465 1346 "time" internal time
1466 1347
1467 1348 Note that all sorts on statistics are in descending order (placing
1468 1349 most time consuming items first), where as name, file, and line number
1469 1350 searches are in ascending order (i.e., alphabetical). The subtle
1470 1351 distinction between "nfl" and "stdname" is that the standard name is a
1471 1352 sort of the name as printed, which means that the embedded line
1472 1353 numbers get compared in an odd way. For example, lines 3, 20, and 40
1473 1354 would (if the file names were the same) appear in the string order
1474 1355 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1475 1356 line numbers. In fact, sort_stats("nfl") is the same as
1476 1357 sort_stats("name", "file", "line").
1477 1358
1478 1359 -T <filename>: save profile results as shown on screen to a text
1479 1360 file. The profile is still shown on screen.
1480 1361
1481 1362 -D <filename>: save (via dump_stats) profile statistics to given
1482 1363 filename. This data is in a format understod by the pstats module, and
1483 1364 is generated by a call to the dump_stats() method of profile
1484 1365 objects. The profile is still shown on screen.
1485 1366
1486 1367 If you want to run complete programs under the profiler's control, use
1487 1368 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1488 1369 contains profiler specific options as described here.
1489 1370
1490 1371 You can read the complete documentation for the profile module with::
1491 1372
1492 1373 In [1]: import profile; profile.help()
1493 1374 """
1494 1375
1495 1376 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1496 1377 # protect user quote marks
1497 1378 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1498 1379
1499 1380 if user_mode: # regular user call
1500 1381 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1501 1382 list_all=1)
1502 1383 namespace = self.shell.user_ns
1503 1384 else: # called to run a program by %run -p
1504 1385 try:
1505 1386 filename = get_py_filename(arg_lst[0])
1506 1387 except IOError,msg:
1507 1388 error(msg)
1508 1389 return
1509 1390
1510 1391 arg_str = 'execfile(filename,prog_ns)'
1511 1392 namespace = locals()
1512 1393
1513 1394 opts.merge(opts_def)
1514 1395
1515 1396 prof = profile.Profile()
1516 1397 try:
1517 1398 prof = prof.runctx(arg_str,namespace,namespace)
1518 1399 sys_exit = ''
1519 1400 except SystemExit:
1520 1401 sys_exit = """*** SystemExit exception caught in code being profiled."""
1521 1402
1522 1403 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1523 1404
1524 1405 lims = opts.l
1525 1406 if lims:
1526 1407 lims = [] # rebuild lims with ints/floats/strings
1527 1408 for lim in opts.l:
1528 1409 try:
1529 1410 lims.append(int(lim))
1530 1411 except ValueError:
1531 1412 try:
1532 1413 lims.append(float(lim))
1533 1414 except ValueError:
1534 1415 lims.append(lim)
1535 1416
1536 1417 # Trap output.
1537 1418 stdout_trap = StringIO()
1538 1419
1539 1420 if hasattr(stats,'stream'):
1540 1421 # In newer versions of python, the stats object has a 'stream'
1541 1422 # attribute to write into.
1542 1423 stats.stream = stdout_trap
1543 1424 stats.print_stats(*lims)
1544 1425 else:
1545 1426 # For older versions, we manually redirect stdout during printing
1546 1427 sys_stdout = sys.stdout
1547 1428 try:
1548 1429 sys.stdout = stdout_trap
1549 1430 stats.print_stats(*lims)
1550 1431 finally:
1551 1432 sys.stdout = sys_stdout
1552 1433
1553 1434 output = stdout_trap.getvalue()
1554 1435 output = output.rstrip()
1555 1436
1556 1437 page(output,screen_lines=self.shell.usable_screen_length)
1557 1438 print sys_exit,
1558 1439
1559 1440 dump_file = opts.D[0]
1560 1441 text_file = opts.T[0]
1561 1442 if dump_file:
1562 1443 prof.dump_stats(dump_file)
1563 1444 print '\n*** Profile stats marshalled to file',\
1564 1445 `dump_file`+'.',sys_exit
1565 1446 if text_file:
1566 1447 pfile = file(text_file,'w')
1567 1448 pfile.write(output)
1568 1449 pfile.close()
1569 1450 print '\n*** Profile printout saved to text file',\
1570 1451 `text_file`+'.',sys_exit
1571 1452
1572 1453 if opts.has_key('r'):
1573 1454 return stats
1574 1455 else:
1575 1456 return None
1576 1457
1577 1458 @testdec.skip_doctest
1578 1459 def magic_run(self, parameter_s ='',runner=None,
1579 1460 file_finder=get_py_filename):
1580 1461 """Run the named file inside IPython as a program.
1581 1462
1582 1463 Usage:\\
1583 1464 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1584 1465
1585 1466 Parameters after the filename are passed as command-line arguments to
1586 1467 the program (put in sys.argv). Then, control returns to IPython's
1587 1468 prompt.
1588 1469
1589 1470 This is similar to running at a system prompt:\\
1590 1471 $ python file args\\
1591 1472 but with the advantage of giving you IPython's tracebacks, and of
1592 1473 loading all variables into your interactive namespace for further use
1593 1474 (unless -p is used, see below).
1594 1475
1595 1476 The file is executed in a namespace initially consisting only of
1596 1477 __name__=='__main__' and sys.argv constructed as indicated. It thus
1597 1478 sees its environment as if it were being run as a stand-alone program
1598 1479 (except for sharing global objects such as previously imported
1599 1480 modules). But after execution, the IPython interactive namespace gets
1600 1481 updated with all variables defined in the program (except for __name__
1601 1482 and sys.argv). This allows for very convenient loading of code for
1602 1483 interactive work, while giving each program a 'clean sheet' to run in.
1603 1484
1604 1485 Options:
1605 1486
1606 1487 -n: __name__ is NOT set to '__main__', but to the running file's name
1607 1488 without extension (as python does under import). This allows running
1608 1489 scripts and reloading the definitions in them without calling code
1609 1490 protected by an ' if __name__ == "__main__" ' clause.
1610 1491
1611 1492 -i: run the file in IPython's namespace instead of an empty one. This
1612 1493 is useful if you are experimenting with code written in a text editor
1613 1494 which depends on variables defined interactively.
1614 1495
1615 1496 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1616 1497 being run. This is particularly useful if IPython is being used to
1617 1498 run unittests, which always exit with a sys.exit() call. In such
1618 1499 cases you are interested in the output of the test results, not in
1619 1500 seeing a traceback of the unittest module.
1620 1501
1621 1502 -t: print timing information at the end of the run. IPython will give
1622 1503 you an estimated CPU time consumption for your script, which under
1623 1504 Unix uses the resource module to avoid the wraparound problems of
1624 1505 time.clock(). Under Unix, an estimate of time spent on system tasks
1625 1506 is also given (for Windows platforms this is reported as 0.0).
1626 1507
1627 1508 If -t is given, an additional -N<N> option can be given, where <N>
1628 1509 must be an integer indicating how many times you want the script to
1629 1510 run. The final timing report will include total and per run results.
1630 1511
1631 1512 For example (testing the script uniq_stable.py):
1632 1513
1633 1514 In [1]: run -t uniq_stable
1634 1515
1635 1516 IPython CPU timings (estimated):\\
1636 1517 User : 0.19597 s.\\
1637 1518 System: 0.0 s.\\
1638 1519
1639 1520 In [2]: run -t -N5 uniq_stable
1640 1521
1641 1522 IPython CPU timings (estimated):\\
1642 1523 Total runs performed: 5\\
1643 1524 Times : Total Per run\\
1644 1525 User : 0.910862 s, 0.1821724 s.\\
1645 1526 System: 0.0 s, 0.0 s.
1646 1527
1647 1528 -d: run your program under the control of pdb, the Python debugger.
1648 1529 This allows you to execute your program step by step, watch variables,
1649 1530 etc. Internally, what IPython does is similar to calling:
1650 1531
1651 1532 pdb.run('execfile("YOURFILENAME")')
1652 1533
1653 1534 with a breakpoint set on line 1 of your file. You can change the line
1654 1535 number for this automatic breakpoint to be <N> by using the -bN option
1655 1536 (where N must be an integer). For example:
1656 1537
1657 1538 %run -d -b40 myscript
1658 1539
1659 1540 will set the first breakpoint at line 40 in myscript.py. Note that
1660 1541 the first breakpoint must be set on a line which actually does
1661 1542 something (not a comment or docstring) for it to stop execution.
1662 1543
1663 1544 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1664 1545 first enter 'c' (without qoutes) to start execution up to the first
1665 1546 breakpoint.
1666 1547
1667 1548 Entering 'help' gives information about the use of the debugger. You
1668 1549 can easily see pdb's full documentation with "import pdb;pdb.help()"
1669 1550 at a prompt.
1670 1551
1671 1552 -p: run program under the control of the Python profiler module (which
1672 1553 prints a detailed report of execution times, function calls, etc).
1673 1554
1674 1555 You can pass other options after -p which affect the behavior of the
1675 1556 profiler itself. See the docs for %prun for details.
1676 1557
1677 1558 In this mode, the program's variables do NOT propagate back to the
1678 1559 IPython interactive namespace (because they remain in the namespace
1679 1560 where the profiler executes them).
1680 1561
1681 1562 Internally this triggers a call to %prun, see its documentation for
1682 1563 details on the options available specifically for profiling.
1683 1564
1684 1565 There is one special usage for which the text above doesn't apply:
1685 1566 if the filename ends with .ipy, the file is run as ipython script,
1686 1567 just as if the commands were written on IPython prompt.
1687 1568 """
1688 1569
1689 1570 # get arguments and set sys.argv for program to be run.
1690 1571 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1691 1572 mode='list',list_all=1)
1692 1573
1693 1574 try:
1694 1575 filename = file_finder(arg_lst[0])
1695 1576 except IndexError:
1696 1577 warn('you must provide at least a filename.')
1697 1578 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1698 1579 return
1699 1580 except IOError,msg:
1700 1581 error(msg)
1701 1582 return
1702 1583
1703 1584 if filename.lower().endswith('.ipy'):
1704 1585 self.shell.safe_execfile_ipy(filename)
1705 1586 return
1706 1587
1707 1588 # Control the response to exit() calls made by the script being run
1708 1589 exit_ignore = opts.has_key('e')
1709 1590
1710 1591 # Make sure that the running script gets a proper sys.argv as if it
1711 1592 # were run from a system shell.
1712 1593 save_argv = sys.argv # save it for later restoring
1713 1594 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1714 1595
1715 1596 if opts.has_key('i'):
1716 1597 # Run in user's interactive namespace
1717 1598 prog_ns = self.shell.user_ns
1718 1599 __name__save = self.shell.user_ns['__name__']
1719 1600 prog_ns['__name__'] = '__main__'
1720 1601 main_mod = self.shell.new_main_mod(prog_ns)
1721 1602 else:
1722 1603 # Run in a fresh, empty namespace
1723 1604 if opts.has_key('n'):
1724 1605 name = os.path.splitext(os.path.basename(filename))[0]
1725 1606 else:
1726 1607 name = '__main__'
1727 1608
1728 1609 main_mod = self.shell.new_main_mod()
1729 1610 prog_ns = main_mod.__dict__
1730 1611 prog_ns['__name__'] = name
1731 1612
1732 1613 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1733 1614 # set the __file__ global in the script's namespace
1734 1615 prog_ns['__file__'] = filename
1735 1616
1736 1617 # pickle fix. See iplib for an explanation. But we need to make sure
1737 1618 # that, if we overwrite __main__, we replace it at the end
1738 1619 main_mod_name = prog_ns['__name__']
1739 1620
1740 1621 if main_mod_name == '__main__':
1741 1622 restore_main = sys.modules['__main__']
1742 1623 else:
1743 1624 restore_main = False
1744 1625
1745 1626 # This needs to be undone at the end to prevent holding references to
1746 1627 # every single object ever created.
1747 1628 sys.modules[main_mod_name] = main_mod
1748 1629
1749 1630 stats = None
1750 1631 try:
1751 1632 self.shell.savehist()
1752 1633
1753 1634 if opts.has_key('p'):
1754 1635 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1755 1636 else:
1756 1637 if opts.has_key('d'):
1757 1638 deb = debugger.Pdb(self.shell.colors)
1758 1639 # reset Breakpoint state, which is moronically kept
1759 1640 # in a class
1760 1641 bdb.Breakpoint.next = 1
1761 1642 bdb.Breakpoint.bplist = {}
1762 1643 bdb.Breakpoint.bpbynumber = [None]
1763 1644 # Set an initial breakpoint to stop execution
1764 1645 maxtries = 10
1765 1646 bp = int(opts.get('b',[1])[0])
1766 1647 checkline = deb.checkline(filename,bp)
1767 1648 if not checkline:
1768 1649 for bp in range(bp+1,bp+maxtries+1):
1769 1650 if deb.checkline(filename,bp):
1770 1651 break
1771 1652 else:
1772 1653 msg = ("\nI failed to find a valid line to set "
1773 1654 "a breakpoint\n"
1774 1655 "after trying up to line: %s.\n"
1775 1656 "Please set a valid breakpoint manually "
1776 1657 "with the -b option." % bp)
1777 1658 error(msg)
1778 1659 return
1779 1660 # if we find a good linenumber, set the breakpoint
1780 1661 deb.do_break('%s:%s' % (filename,bp))
1781 1662 # Start file run
1782 1663 print "NOTE: Enter 'c' at the",
1783 1664 print "%s prompt to start your script." % deb.prompt
1784 1665 try:
1785 1666 deb.run('execfile("%s")' % filename,prog_ns)
1786 1667
1787 1668 except:
1788 1669 etype, value, tb = sys.exc_info()
1789 1670 # Skip three frames in the traceback: the %run one,
1790 1671 # one inside bdb.py, and the command-line typed by the
1791 1672 # user (run by exec in pdb itself).
1792 1673 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1793 1674 else:
1794 1675 if runner is None:
1795 1676 runner = self.shell.safe_execfile
1796 1677 if opts.has_key('t'):
1797 1678 # timed execution
1798 1679 try:
1799 1680 nruns = int(opts['N'][0])
1800 1681 if nruns < 1:
1801 1682 error('Number of runs must be >=1')
1802 1683 return
1803 1684 except (KeyError):
1804 1685 nruns = 1
1805 1686 if nruns == 1:
1806 1687 t0 = clock2()
1807 1688 runner(filename,prog_ns,prog_ns,
1808 1689 exit_ignore=exit_ignore)
1809 1690 t1 = clock2()
1810 1691 t_usr = t1[0]-t0[0]
1811 1692 t_sys = t1[1]-t0[1]
1812 1693 print "\nIPython CPU timings (estimated):"
1813 1694 print " User : %10s s." % t_usr
1814 1695 print " System: %10s s." % t_sys
1815 1696 else:
1816 1697 runs = range(nruns)
1817 1698 t0 = clock2()
1818 1699 for nr in runs:
1819 1700 runner(filename,prog_ns,prog_ns,
1820 1701 exit_ignore=exit_ignore)
1821 1702 t1 = clock2()
1822 1703 t_usr = t1[0]-t0[0]
1823 1704 t_sys = t1[1]-t0[1]
1824 1705 print "\nIPython CPU timings (estimated):"
1825 1706 print "Total runs performed:",nruns
1826 1707 print " Times : %10s %10s" % ('Total','Per run')
1827 1708 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1828 1709 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1829 1710
1830 1711 else:
1831 1712 # regular execution
1832 1713 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1833 1714
1834 1715 if opts.has_key('i'):
1835 1716 self.shell.user_ns['__name__'] = __name__save
1836 1717 else:
1837 1718 # The shell MUST hold a reference to prog_ns so after %run
1838 1719 # exits, the python deletion mechanism doesn't zero it out
1839 1720 # (leaving dangling references).
1840 1721 self.shell.cache_main_mod(prog_ns,filename)
1841 1722 # update IPython interactive namespace
1842 1723
1843 1724 # Some forms of read errors on the file may mean the
1844 1725 # __name__ key was never set; using pop we don't have to
1845 1726 # worry about a possible KeyError.
1846 1727 prog_ns.pop('__name__', None)
1847 1728
1848 1729 self.shell.user_ns.update(prog_ns)
1849 1730 finally:
1850 1731 # It's a bit of a mystery why, but __builtins__ can change from
1851 1732 # being a module to becoming a dict missing some key data after
1852 1733 # %run. As best I can see, this is NOT something IPython is doing
1853 1734 # at all, and similar problems have been reported before:
1854 1735 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1855 1736 # Since this seems to be done by the interpreter itself, the best
1856 1737 # we can do is to at least restore __builtins__ for the user on
1857 1738 # exit.
1858 1739 self.shell.user_ns['__builtins__'] = __builtin__
1859 1740
1860 1741 # Ensure key global structures are restored
1861 1742 sys.argv = save_argv
1862 1743 if restore_main:
1863 1744 sys.modules['__main__'] = restore_main
1864 1745 else:
1865 1746 # Remove from sys.modules the reference to main_mod we'd
1866 1747 # added. Otherwise it will trap references to objects
1867 1748 # contained therein.
1868 1749 del sys.modules[main_mod_name]
1869 1750
1870 1751 self.shell.reloadhist()
1871 1752
1872 1753 return stats
1873 1754
1874 1755 @testdec.skip_doctest
1875 1756 def magic_timeit(self, parameter_s =''):
1876 1757 """Time execution of a Python statement or expression
1877 1758
1878 1759 Usage:\\
1879 1760 %timeit [-n<N> -r<R> [-t|-c]] statement
1880 1761
1881 1762 Time execution of a Python statement or expression using the timeit
1882 1763 module.
1883 1764
1884 1765 Options:
1885 1766 -n<N>: execute the given statement <N> times in a loop. If this value
1886 1767 is not given, a fitting value is chosen.
1887 1768
1888 1769 -r<R>: repeat the loop iteration <R> times and take the best result.
1889 1770 Default: 3
1890 1771
1891 1772 -t: use time.time to measure the time, which is the default on Unix.
1892 1773 This function measures wall time.
1893 1774
1894 1775 -c: use time.clock to measure the time, which is the default on
1895 1776 Windows and measures wall time. On Unix, resource.getrusage is used
1896 1777 instead and returns the CPU user time.
1897 1778
1898 1779 -p<P>: use a precision of <P> digits to display the timing result.
1899 1780 Default: 3
1900 1781
1901 1782
1902 1783 Examples:
1903 1784
1904 1785 In [1]: %timeit pass
1905 1786 10000000 loops, best of 3: 53.3 ns per loop
1906 1787
1907 1788 In [2]: u = None
1908 1789
1909 1790 In [3]: %timeit u is None
1910 1791 10000000 loops, best of 3: 184 ns per loop
1911 1792
1912 1793 In [4]: %timeit -r 4 u == None
1913 1794 1000000 loops, best of 4: 242 ns per loop
1914 1795
1915 1796 In [5]: import time
1916 1797
1917 1798 In [6]: %timeit -n1 time.sleep(2)
1918 1799 1 loops, best of 3: 2 s per loop
1919 1800
1920 1801
1921 1802 The times reported by %timeit will be slightly higher than those
1922 1803 reported by the timeit.py script when variables are accessed. This is
1923 1804 due to the fact that %timeit executes the statement in the namespace
1924 1805 of the shell, compared with timeit.py, which uses a single setup
1925 1806 statement to import function or create variables. Generally, the bias
1926 1807 does not matter as long as results from timeit.py are not mixed with
1927 1808 those from %timeit."""
1928 1809
1929 1810 import timeit
1930 1811 import math
1931 1812
1932 1813 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1933 1814 # certain terminals. Until we figure out a robust way of
1934 1815 # auto-detecting if the terminal can deal with it, use plain 'us' for
1935 1816 # microseconds. I am really NOT happy about disabling the proper
1936 1817 # 'micro' prefix, but crashing is worse... If anyone knows what the
1937 1818 # right solution for this is, I'm all ears...
1938 1819 #
1939 1820 # Note: using
1940 1821 #
1941 1822 # s = u'\xb5'
1942 1823 # s.encode(sys.getdefaultencoding())
1943 1824 #
1944 1825 # is not sufficient, as I've seen terminals where that fails but
1945 1826 # print s
1946 1827 #
1947 1828 # succeeds
1948 1829 #
1949 1830 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1950 1831
1951 1832 #units = [u"s", u"ms",u'\xb5',"ns"]
1952 1833 units = [u"s", u"ms",u'us',"ns"]
1953 1834
1954 1835 scaling = [1, 1e3, 1e6, 1e9]
1955 1836
1956 1837 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1957 1838 posix=False)
1958 1839 if stmt == "":
1959 1840 return
1960 1841 timefunc = timeit.default_timer
1961 1842 number = int(getattr(opts, "n", 0))
1962 1843 repeat = int(getattr(opts, "r", timeit.default_repeat))
1963 1844 precision = int(getattr(opts, "p", 3))
1964 1845 if hasattr(opts, "t"):
1965 1846 timefunc = time.time
1966 1847 if hasattr(opts, "c"):
1967 1848 timefunc = clock
1968 1849
1969 1850 timer = timeit.Timer(timer=timefunc)
1970 1851 # this code has tight coupling to the inner workings of timeit.Timer,
1971 1852 # but is there a better way to achieve that the code stmt has access
1972 1853 # to the shell namespace?
1973 1854
1974 1855 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1975 1856 'setup': "pass"}
1976 1857 # Track compilation time so it can be reported if too long
1977 1858 # Minimum time above which compilation time will be reported
1978 1859 tc_min = 0.1
1979 1860
1980 1861 t0 = clock()
1981 1862 code = compile(src, "<magic-timeit>", "exec")
1982 1863 tc = clock()-t0
1983 1864
1984 1865 ns = {}
1985 1866 exec code in self.shell.user_ns, ns
1986 1867 timer.inner = ns["inner"]
1987 1868
1988 1869 if number == 0:
1989 1870 # determine number so that 0.2 <= total time < 2.0
1990 1871 number = 1
1991 1872 for i in range(1, 10):
1992 1873 if timer.timeit(number) >= 0.2:
1993 1874 break
1994 1875 number *= 10
1995 1876
1996 1877 best = min(timer.repeat(repeat, number)) / number
1997 1878
1998 1879 if best > 0.0:
1999 1880 order = min(-int(math.floor(math.log10(best)) // 3), 3)
2000 1881 else:
2001 1882 order = 3
2002 1883 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
2003 1884 precision,
2004 1885 best * scaling[order],
2005 1886 units[order])
2006 1887 if tc > tc_min:
2007 1888 print "Compiler time: %.2f s" % tc
2008 1889
2009 1890 @testdec.skip_doctest
2010 1891 def magic_time(self,parameter_s = ''):
2011 1892 """Time execution of a Python statement or expression.
2012 1893
2013 1894 The CPU and wall clock times are printed, and the value of the
2014 1895 expression (if any) is returned. Note that under Win32, system time
2015 1896 is always reported as 0, since it can not be measured.
2016 1897
2017 1898 This function provides very basic timing functionality. In Python
2018 1899 2.3, the timeit module offers more control and sophistication, so this
2019 1900 could be rewritten to use it (patches welcome).
2020 1901
2021 1902 Some examples:
2022 1903
2023 1904 In [1]: time 2**128
2024 1905 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2025 1906 Wall time: 0.00
2026 1907 Out[1]: 340282366920938463463374607431768211456L
2027 1908
2028 1909 In [2]: n = 1000000
2029 1910
2030 1911 In [3]: time sum(range(n))
2031 1912 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2032 1913 Wall time: 1.37
2033 1914 Out[3]: 499999500000L
2034 1915
2035 1916 In [4]: time print 'hello world'
2036 1917 hello world
2037 1918 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2038 1919 Wall time: 0.00
2039 1920
2040 1921 Note that the time needed by Python to compile the given expression
2041 1922 will be reported if it is more than 0.1s. In this example, the
2042 1923 actual exponentiation is done by Python at compilation time, so while
2043 1924 the expression can take a noticeable amount of time to compute, that
2044 1925 time is purely due to the compilation:
2045 1926
2046 1927 In [5]: time 3**9999;
2047 1928 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2048 1929 Wall time: 0.00 s
2049 1930
2050 1931 In [6]: time 3**999999;
2051 1932 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2052 1933 Wall time: 0.00 s
2053 1934 Compiler : 0.78 s
2054 1935 """
2055 1936
2056 1937 # fail immediately if the given expression can't be compiled
2057 1938
2058 1939 expr = self.shell.prefilter(parameter_s,False)
2059 1940
2060 1941 # Minimum time above which compilation time will be reported
2061 1942 tc_min = 0.1
2062 1943
2063 1944 try:
2064 1945 mode = 'eval'
2065 1946 t0 = clock()
2066 1947 code = compile(expr,'<timed eval>',mode)
2067 1948 tc = clock()-t0
2068 1949 except SyntaxError:
2069 1950 mode = 'exec'
2070 1951 t0 = clock()
2071 1952 code = compile(expr,'<timed exec>',mode)
2072 1953 tc = clock()-t0
2073 1954 # skew measurement as little as possible
2074 1955 glob = self.shell.user_ns
2075 1956 clk = clock2
2076 1957 wtime = time.time
2077 1958 # time execution
2078 1959 wall_st = wtime()
2079 1960 if mode=='eval':
2080 1961 st = clk()
2081 1962 out = eval(code,glob)
2082 1963 end = clk()
2083 1964 else:
2084 1965 st = clk()
2085 1966 exec code in glob
2086 1967 end = clk()
2087 1968 out = None
2088 1969 wall_end = wtime()
2089 1970 # Compute actual times and report
2090 1971 wall_time = wall_end-wall_st
2091 1972 cpu_user = end[0]-st[0]
2092 1973 cpu_sys = end[1]-st[1]
2093 1974 cpu_tot = cpu_user+cpu_sys
2094 1975 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2095 1976 (cpu_user,cpu_sys,cpu_tot)
2096 1977 print "Wall time: %.2f s" % wall_time
2097 1978 if tc > tc_min:
2098 1979 print "Compiler : %.2f s" % tc
2099 1980 return out
2100 1981
2101 1982 @testdec.skip_doctest
2102 1983 def magic_macro(self,parameter_s = ''):
2103 1984 """Define a set of input lines as a macro for future re-execution.
2104 1985
2105 1986 Usage:\\
2106 1987 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2107 1988
2108 1989 Options:
2109 1990
2110 1991 -r: use 'raw' input. By default, the 'processed' history is used,
2111 1992 so that magics are loaded in their transformed version to valid
2112 1993 Python. If this option is given, the raw input as typed as the
2113 1994 command line is used instead.
2114 1995
2115 1996 This will define a global variable called `name` which is a string
2116 1997 made of joining the slices and lines you specify (n1,n2,... numbers
2117 1998 above) from your input history into a single string. This variable
2118 1999 acts like an automatic function which re-executes those lines as if
2119 2000 you had typed them. You just type 'name' at the prompt and the code
2120 2001 executes.
2121 2002
2122 2003 The notation for indicating number ranges is: n1-n2 means 'use line
2123 2004 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2124 2005 using the lines numbered 5,6 and 7.
2125 2006
2126 2007 Note: as a 'hidden' feature, you can also use traditional python slice
2127 2008 notation, where N:M means numbers N through M-1.
2128 2009
2129 2010 For example, if your history contains (%hist prints it):
2130 2011
2131 2012 44: x=1
2132 2013 45: y=3
2133 2014 46: z=x+y
2134 2015 47: print x
2135 2016 48: a=5
2136 2017 49: print 'x',x,'y',y
2137 2018
2138 2019 you can create a macro with lines 44 through 47 (included) and line 49
2139 2020 called my_macro with:
2140 2021
2141 2022 In [55]: %macro my_macro 44-47 49
2142 2023
2143 2024 Now, typing `my_macro` (without quotes) will re-execute all this code
2144 2025 in one pass.
2145 2026
2146 2027 You don't need to give the line-numbers in order, and any given line
2147 2028 number can appear multiple times. You can assemble macros with any
2148 2029 lines from your input history in any order.
2149 2030
2150 2031 The macro is a simple object which holds its value in an attribute,
2151 2032 but IPython's display system checks for macros and executes them as
2152 2033 code instead of printing them when you type their name.
2153 2034
2154 2035 You can view a macro's contents by explicitly printing it with:
2155 2036
2156 2037 'print macro_name'.
2157 2038
2158 2039 For one-off cases which DON'T contain magic function calls in them you
2159 2040 can obtain similar results by explicitly executing slices from your
2160 2041 input history with:
2161 2042
2162 2043 In [60]: exec In[44:48]+In[49]"""
2163 2044
2164 2045 opts,args = self.parse_options(parameter_s,'r',mode='list')
2165 2046 if not args:
2166 2047 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2167 2048 macs.sort()
2168 2049 return macs
2169 2050 if len(args) == 1:
2170 2051 raise UsageError(
2171 2052 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2172 2053 name,ranges = args[0], args[1:]
2173 2054
2174 2055 #print 'rng',ranges # dbg
2175 2056 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2176 2057 macro = Macro(lines)
2177 2058 self.shell.define_macro(name, macro)
2178 2059 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2179 2060 print 'Macro contents:'
2180 2061 print macro,
2181 2062
2182 2063 def magic_save(self,parameter_s = ''):
2183 2064 """Save a set of lines to a given filename.
2184 2065
2185 2066 Usage:\\
2186 2067 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2187 2068
2188 2069 Options:
2189 2070
2190 2071 -r: use 'raw' input. By default, the 'processed' history is used,
2191 2072 so that magics are loaded in their transformed version to valid
2192 2073 Python. If this option is given, the raw input as typed as the
2193 2074 command line is used instead.
2194 2075
2195 2076 This function uses the same syntax as %macro for line extraction, but
2196 2077 instead of creating a macro it saves the resulting string to the
2197 2078 filename you specify.
2198 2079
2199 2080 It adds a '.py' extension to the file if you don't do so yourself, and
2200 2081 it asks for confirmation before overwriting existing files."""
2201 2082
2202 2083 opts,args = self.parse_options(parameter_s,'r',mode='list')
2203 2084 fname,ranges = args[0], args[1:]
2204 2085 if not fname.endswith('.py'):
2205 2086 fname += '.py'
2206 2087 if os.path.isfile(fname):
2207 2088 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2208 2089 if ans.lower() not in ['y','yes']:
2209 2090 print 'Operation cancelled.'
2210 2091 return
2211 2092 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2212 2093 f = file(fname,'w')
2213 2094 f.write(cmds)
2214 2095 f.close()
2215 2096 print 'The following commands were written to file `%s`:' % fname
2216 2097 print cmds
2217 2098
2218 2099 def _edit_macro(self,mname,macro):
2219 2100 """open an editor with the macro data in a file"""
2220 2101 filename = self.shell.mktempfile(macro.value)
2221 2102 self.shell.hooks.editor(filename)
2222 2103
2223 2104 # and make a new macro object, to replace the old one
2224 2105 mfile = open(filename)
2225 2106 mvalue = mfile.read()
2226 2107 mfile.close()
2227 2108 self.shell.user_ns[mname] = Macro(mvalue)
2228 2109
2229 2110 def magic_ed(self,parameter_s=''):
2230 2111 """Alias to %edit."""
2231 2112 return self.magic_edit(parameter_s)
2232 2113
2233 2114 @testdec.skip_doctest
2234 2115 def magic_edit(self,parameter_s='',last_call=['','']):
2235 2116 """Bring up an editor and execute the resulting code.
2236 2117
2237 2118 Usage:
2238 2119 %edit [options] [args]
2239 2120
2240 2121 %edit runs IPython's editor hook. The default version of this hook is
2241 2122 set to call the __IPYTHON__.rc.editor command. This is read from your
2242 2123 environment variable $EDITOR. If this isn't found, it will default to
2243 2124 vi under Linux/Unix and to notepad under Windows. See the end of this
2244 2125 docstring for how to change the editor hook.
2245 2126
2246 2127 You can also set the value of this editor via the command line option
2247 2128 '-editor' or in your ipythonrc file. This is useful if you wish to use
2248 2129 specifically for IPython an editor different from your typical default
2249 2130 (and for Windows users who typically don't set environment variables).
2250 2131
2251 2132 This command allows you to conveniently edit multi-line code right in
2252 2133 your IPython session.
2253 2134
2254 2135 If called without arguments, %edit opens up an empty editor with a
2255 2136 temporary file and will execute the contents of this file when you
2256 2137 close it (don't forget to save it!).
2257 2138
2258 2139
2259 2140 Options:
2260 2141
2261 2142 -n <number>: open the editor at a specified line number. By default,
2262 2143 the IPython editor hook uses the unix syntax 'editor +N filename', but
2263 2144 you can configure this by providing your own modified hook if your
2264 2145 favorite editor supports line-number specifications with a different
2265 2146 syntax.
2266 2147
2267 2148 -p: this will call the editor with the same data as the previous time
2268 2149 it was used, regardless of how long ago (in your current session) it
2269 2150 was.
2270 2151
2271 2152 -r: use 'raw' input. This option only applies to input taken from the
2272 2153 user's history. By default, the 'processed' history is used, so that
2273 2154 magics are loaded in their transformed version to valid Python. If
2274 2155 this option is given, the raw input as typed as the command line is
2275 2156 used instead. When you exit the editor, it will be executed by
2276 2157 IPython's own processor.
2277 2158
2278 2159 -x: do not execute the edited code immediately upon exit. This is
2279 2160 mainly useful if you are editing programs which need to be called with
2280 2161 command line arguments, which you can then do using %run.
2281 2162
2282 2163
2283 2164 Arguments:
2284 2165
2285 2166 If arguments are given, the following possibilites exist:
2286 2167
2287 2168 - The arguments are numbers or pairs of colon-separated numbers (like
2288 2169 1 4:8 9). These are interpreted as lines of previous input to be
2289 2170 loaded into the editor. The syntax is the same of the %macro command.
2290 2171
2291 2172 - If the argument doesn't start with a number, it is evaluated as a
2292 2173 variable and its contents loaded into the editor. You can thus edit
2293 2174 any string which contains python code (including the result of
2294 2175 previous edits).
2295 2176
2296 2177 - If the argument is the name of an object (other than a string),
2297 2178 IPython will try to locate the file where it was defined and open the
2298 2179 editor at the point where it is defined. You can use `%edit function`
2299 2180 to load an editor exactly at the point where 'function' is defined,
2300 2181 edit it and have the file be executed automatically.
2301 2182
2302 2183 If the object is a macro (see %macro for details), this opens up your
2303 2184 specified editor with a temporary file containing the macro's data.
2304 2185 Upon exit, the macro is reloaded with the contents of the file.
2305 2186
2306 2187 Note: opening at an exact line is only supported under Unix, and some
2307 2188 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2308 2189 '+NUMBER' parameter necessary for this feature. Good editors like
2309 2190 (X)Emacs, vi, jed, pico and joe all do.
2310 2191
2311 2192 - If the argument is not found as a variable, IPython will look for a
2312 2193 file with that name (adding .py if necessary) and load it into the
2313 2194 editor. It will execute its contents with execfile() when you exit,
2314 2195 loading any code in the file into your interactive namespace.
2315 2196
2316 2197 After executing your code, %edit will return as output the code you
2317 2198 typed in the editor (except when it was an existing file). This way
2318 2199 you can reload the code in further invocations of %edit as a variable,
2319 2200 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2320 2201 the output.
2321 2202
2322 2203 Note that %edit is also available through the alias %ed.
2323 2204
2324 2205 This is an example of creating a simple function inside the editor and
2325 2206 then modifying it. First, start up the editor:
2326 2207
2327 2208 In [1]: ed
2328 2209 Editing... done. Executing edited code...
2329 2210 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2330 2211
2331 2212 We can then call the function foo():
2332 2213
2333 2214 In [2]: foo()
2334 2215 foo() was defined in an editing session
2335 2216
2336 2217 Now we edit foo. IPython automatically loads the editor with the
2337 2218 (temporary) file where foo() was previously defined:
2338 2219
2339 2220 In [3]: ed foo
2340 2221 Editing... done. Executing edited code...
2341 2222
2342 2223 And if we call foo() again we get the modified version:
2343 2224
2344 2225 In [4]: foo()
2345 2226 foo() has now been changed!
2346 2227
2347 2228 Here is an example of how to edit a code snippet successive
2348 2229 times. First we call the editor:
2349 2230
2350 2231 In [5]: ed
2351 2232 Editing... done. Executing edited code...
2352 2233 hello
2353 2234 Out[5]: "print 'hello'n"
2354 2235
2355 2236 Now we call it again with the previous output (stored in _):
2356 2237
2357 2238 In [6]: ed _
2358 2239 Editing... done. Executing edited code...
2359 2240 hello world
2360 2241 Out[6]: "print 'hello world'n"
2361 2242
2362 2243 Now we call it with the output #8 (stored in _8, also as Out[8]):
2363 2244
2364 2245 In [7]: ed _8
2365 2246 Editing... done. Executing edited code...
2366 2247 hello again
2367 2248 Out[7]: "print 'hello again'n"
2368 2249
2369 2250
2370 2251 Changing the default editor hook:
2371 2252
2372 2253 If you wish to write your own editor hook, you can put it in a
2373 2254 configuration file which you load at startup time. The default hook
2374 2255 is defined in the IPython.core.hooks module, and you can use that as a
2375 2256 starting example for further modifications. That file also has
2376 2257 general instructions on how to set a new hook for use once you've
2377 2258 defined it."""
2378 2259
2379 2260 # FIXME: This function has become a convoluted mess. It needs a
2380 2261 # ground-up rewrite with clean, simple logic.
2381 2262
2382 2263 def make_filename(arg):
2383 2264 "Make a filename from the given args"
2384 2265 try:
2385 2266 filename = get_py_filename(arg)
2386 2267 except IOError:
2387 2268 if args.endswith('.py'):
2388 2269 filename = arg
2389 2270 else:
2390 2271 filename = None
2391 2272 return filename
2392 2273
2393 2274 # custom exceptions
2394 2275 class DataIsObject(Exception): pass
2395 2276
2396 2277 opts,args = self.parse_options(parameter_s,'prxn:')
2397 2278 # Set a few locals from the options for convenience:
2398 2279 opts_p = opts.has_key('p')
2399 2280 opts_r = opts.has_key('r')
2400 2281
2401 2282 # Default line number value
2402 2283 lineno = opts.get('n',None)
2403 2284
2404 2285 if opts_p:
2405 2286 args = '_%s' % last_call[0]
2406 2287 if not self.shell.user_ns.has_key(args):
2407 2288 args = last_call[1]
2408 2289
2409 2290 # use last_call to remember the state of the previous call, but don't
2410 2291 # let it be clobbered by successive '-p' calls.
2411 2292 try:
2412 2293 last_call[0] = self.shell.outputcache.prompt_count
2413 2294 if not opts_p:
2414 2295 last_call[1] = parameter_s
2415 2296 except:
2416 2297 pass
2417 2298
2418 2299 # by default this is done with temp files, except when the given
2419 2300 # arg is a filename
2420 2301 use_temp = 1
2421 2302
2422 2303 if re.match(r'\d',args):
2423 2304 # Mode where user specifies ranges of lines, like in %macro.
2424 2305 # This means that you can't edit files whose names begin with
2425 2306 # numbers this way. Tough.
2426 2307 ranges = args.split()
2427 2308 data = ''.join(self.extract_input_slices(ranges,opts_r))
2428 2309 elif args.endswith('.py'):
2429 2310 filename = make_filename(args)
2430 2311 data = ''
2431 2312 use_temp = 0
2432 2313 elif args:
2433 2314 try:
2434 2315 # Load the parameter given as a variable. If not a string,
2435 2316 # process it as an object instead (below)
2436 2317
2437 2318 #print '*** args',args,'type',type(args) # dbg
2438 2319 data = eval(args,self.shell.user_ns)
2439 2320 if not type(data) in StringTypes:
2440 2321 raise DataIsObject
2441 2322
2442 2323 except (NameError,SyntaxError):
2443 2324 # given argument is not a variable, try as a filename
2444 2325 filename = make_filename(args)
2445 2326 if filename is None:
2446 2327 warn("Argument given (%s) can't be found as a variable "
2447 2328 "or as a filename." % args)
2448 2329 return
2449 2330
2450 2331 data = ''
2451 2332 use_temp = 0
2452 2333 except DataIsObject:
2453 2334
2454 2335 # macros have a special edit function
2455 2336 if isinstance(data,Macro):
2456 2337 self._edit_macro(args,data)
2457 2338 return
2458 2339
2459 2340 # For objects, try to edit the file where they are defined
2460 2341 try:
2461 2342 filename = inspect.getabsfile(data)
2462 2343 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2463 2344 # class created by %edit? Try to find source
2464 2345 # by looking for method definitions instead, the
2465 2346 # __module__ in those classes is FakeModule.
2466 2347 attrs = [getattr(data, aname) for aname in dir(data)]
2467 2348 for attr in attrs:
2468 2349 if not inspect.ismethod(attr):
2469 2350 continue
2470 2351 filename = inspect.getabsfile(attr)
2471 2352 if filename and 'fakemodule' not in filename.lower():
2472 2353 # change the attribute to be the edit target instead
2473 2354 data = attr
2474 2355 break
2475 2356
2476 2357 datafile = 1
2477 2358 except TypeError:
2478 2359 filename = make_filename(args)
2479 2360 datafile = 1
2480 2361 warn('Could not find file where `%s` is defined.\n'
2481 2362 'Opening a file named `%s`' % (args,filename))
2482 2363 # Now, make sure we can actually read the source (if it was in
2483 2364 # a temp file it's gone by now).
2484 2365 if datafile:
2485 2366 try:
2486 2367 if lineno is None:
2487 2368 lineno = inspect.getsourcelines(data)[1]
2488 2369 except IOError:
2489 2370 filename = make_filename(args)
2490 2371 if filename is None:
2491 2372 warn('The file `%s` where `%s` was defined cannot '
2492 2373 'be read.' % (filename,data))
2493 2374 return
2494 2375 use_temp = 0
2495 2376 else:
2496 2377 data = ''
2497 2378
2498 2379 if use_temp:
2499 2380 filename = self.shell.mktempfile(data)
2500 2381 print 'IPython will make a temporary file named:',filename
2501 2382
2502 2383 # do actual editing here
2503 2384 print 'Editing...',
2504 2385 sys.stdout.flush()
2505 2386 try:
2506 2387 self.shell.hooks.editor(filename,lineno)
2507 2388 except TryNext:
2508 2389 warn('Could not open editor')
2509 2390 return
2510 2391
2511 2392 # XXX TODO: should this be generalized for all string vars?
2512 2393 # For now, this is special-cased to blocks created by cpaste
2513 2394 if args.strip() == 'pasted_block':
2514 2395 self.shell.user_ns['pasted_block'] = file_read(filename)
2515 2396
2516 2397 if opts.has_key('x'): # -x prevents actual execution
2517 2398 print
2518 2399 else:
2519 2400 print 'done. Executing edited code...'
2520 2401 if opts_r:
2521 2402 self.shell.runlines(file_read(filename))
2522 2403 else:
2523 2404 self.shell.safe_execfile(filename,self.shell.user_ns,
2524 2405 self.shell.user_ns)
2525 2406
2526 2407
2527 2408 if use_temp:
2528 2409 try:
2529 2410 return open(filename).read()
2530 2411 except IOError,msg:
2531 2412 if msg.filename == filename:
2532 2413 warn('File not found. Did you forget to save?')
2533 2414 return
2534 2415 else:
2535 2416 self.shell.showtraceback()
2536 2417
2537 2418 def magic_xmode(self,parameter_s = ''):
2538 2419 """Switch modes for the exception handlers.
2539 2420
2540 2421 Valid modes: Plain, Context and Verbose.
2541 2422
2542 2423 If called without arguments, acts as a toggle."""
2543 2424
2544 2425 def xmode_switch_err(name):
2545 2426 warn('Error changing %s exception modes.\n%s' %
2546 2427 (name,sys.exc_info()[1]))
2547 2428
2548 2429 shell = self.shell
2549 2430 new_mode = parameter_s.strip().capitalize()
2550 2431 try:
2551 2432 shell.InteractiveTB.set_mode(mode=new_mode)
2552 2433 print 'Exception reporting mode:',shell.InteractiveTB.mode
2553 2434 except:
2554 2435 xmode_switch_err('user')
2555 2436
2556 2437 # threaded shells use a special handler in sys.excepthook
2557 2438 if shell.isthreaded:
2558 2439 try:
2559 2440 shell.sys_excepthook.set_mode(mode=new_mode)
2560 2441 except:
2561 2442 xmode_switch_err('threaded')
2562 2443
2563 2444 def magic_colors(self,parameter_s = ''):
2564 2445 """Switch color scheme for prompts, info system and exception handlers.
2565 2446
2566 2447 Currently implemented schemes: NoColor, Linux, LightBG.
2567 2448
2568 2449 Color scheme names are not case-sensitive."""
2569 2450
2570 2451 def color_switch_err(name):
2571 2452 warn('Error changing %s color schemes.\n%s' %
2572 2453 (name,sys.exc_info()[1]))
2573 2454
2574 2455
2575 2456 new_scheme = parameter_s.strip()
2576 2457 if not new_scheme:
2577 2458 raise UsageError(
2578 2459 "%colors: you must specify a color scheme. See '%colors?'")
2579 2460 return
2580 2461 # local shortcut
2581 2462 shell = self.shell
2582 2463
2583 2464 import IPython.utils.rlineimpl as readline
2584 2465
2585 2466 if not readline.have_readline and sys.platform == "win32":
2586 2467 msg = """\
2587 2468 Proper color support under MS Windows requires the pyreadline library.
2588 2469 You can find it at:
2589 2470 http://ipython.scipy.org/moin/PyReadline/Intro
2590 2471 Gary's readline needs the ctypes module, from:
2591 2472 http://starship.python.net/crew/theller/ctypes
2592 2473 (Note that ctypes is already part of Python versions 2.5 and newer).
2593 2474
2594 2475 Defaulting color scheme to 'NoColor'"""
2595 2476 new_scheme = 'NoColor'
2596 2477 warn(msg)
2597 2478
2598 2479 # readline option is 0
2599 2480 if not shell.has_readline:
2600 2481 new_scheme = 'NoColor'
2601 2482
2602 2483 # Set prompt colors
2603 2484 try:
2604 2485 shell.outputcache.set_colors(new_scheme)
2605 2486 except:
2606 2487 color_switch_err('prompt')
2607 2488 else:
2608 2489 shell.colors = \
2609 2490 shell.outputcache.color_table.active_scheme_name
2610 2491 # Set exception colors
2611 2492 try:
2612 2493 shell.InteractiveTB.set_colors(scheme = new_scheme)
2613 2494 shell.SyntaxTB.set_colors(scheme = new_scheme)
2614 2495 except:
2615 2496 color_switch_err('exception')
2616 2497
2617 2498 # threaded shells use a verbose traceback in sys.excepthook
2618 2499 if shell.isthreaded:
2619 2500 try:
2620 2501 shell.sys_excepthook.set_colors(scheme=new_scheme)
2621 2502 except:
2622 2503 color_switch_err('system exception handler')
2623 2504
2624 2505 # Set info (for 'object?') colors
2625 2506 if shell.color_info:
2626 2507 try:
2627 2508 shell.inspector.set_active_scheme(new_scheme)
2628 2509 except:
2629 2510 color_switch_err('object inspector')
2630 2511 else:
2631 2512 shell.inspector.set_active_scheme('NoColor')
2632 2513
2633 2514 def magic_color_info(self,parameter_s = ''):
2634 2515 """Toggle color_info.
2635 2516
2636 2517 The color_info configuration parameter controls whether colors are
2637 2518 used for displaying object details (by things like %psource, %pfile or
2638 2519 the '?' system). This function toggles this value with each call.
2639 2520
2640 2521 Note that unless you have a fairly recent pager (less works better
2641 2522 than more) in your system, using colored object information displays
2642 2523 will not work properly. Test it and see."""
2643 2524
2644 2525 self.shell.color_info = not self.shell.color_info
2645 2526 self.magic_colors(self.shell.colors)
2646 2527 print 'Object introspection functions have now coloring:',
2647 2528 print ['OFF','ON'][int(self.shell.color_info)]
2648 2529
2649 2530 def magic_Pprint(self, parameter_s=''):
2650 2531 """Toggle pretty printing on/off."""
2651 2532
2652 2533 self.shell.pprint = 1 - self.shell.pprint
2653 2534 print 'Pretty printing has been turned', \
2654 2535 ['OFF','ON'][self.shell.pprint]
2655 2536
2656 2537 def magic_exit(self, parameter_s=''):
2657 2538 """Exit IPython, confirming if configured to do so.
2658 2539
2659 2540 You can configure whether IPython asks for confirmation upon exit by
2660 2541 setting the confirm_exit flag in the ipythonrc file."""
2661 2542
2662 2543 self.shell.exit()
2663 2544
2664 2545 def magic_quit(self, parameter_s=''):
2665 2546 """Exit IPython, confirming if configured to do so (like %exit)"""
2666 2547
2667 2548 self.shell.exit()
2668 2549
2669 2550 def magic_Exit(self, parameter_s=''):
2670 2551 """Exit IPython without confirmation."""
2671 2552
2672 2553 self.shell.ask_exit()
2673 2554
2674 2555 #......................................................................
2675 2556 # Functions to implement unix shell-type things
2676 2557
2677 2558 @testdec.skip_doctest
2678 2559 def magic_alias(self, parameter_s = ''):
2679 2560 """Define an alias for a system command.
2680 2561
2681 2562 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2682 2563
2683 2564 Then, typing 'alias_name params' will execute the system command 'cmd
2684 2565 params' (from your underlying operating system).
2685 2566
2686 2567 Aliases have lower precedence than magic functions and Python normal
2687 2568 variables, so if 'foo' is both a Python variable and an alias, the
2688 2569 alias can not be executed until 'del foo' removes the Python variable.
2689 2570
2690 2571 You can use the %l specifier in an alias definition to represent the
2691 2572 whole line when the alias is called. For example:
2692 2573
2693 2574 In [2]: alias all echo "Input in brackets: <%l>"
2694 2575 In [3]: all hello world
2695 2576 Input in brackets: <hello world>
2696 2577
2697 2578 You can also define aliases with parameters using %s specifiers (one
2698 2579 per parameter):
2699 2580
2700 2581 In [1]: alias parts echo first %s second %s
2701 2582 In [2]: %parts A B
2702 2583 first A second B
2703 2584 In [3]: %parts A
2704 2585 Incorrect number of arguments: 2 expected.
2705 2586 parts is an alias to: 'echo first %s second %s'
2706 2587
2707 2588 Note that %l and %s are mutually exclusive. You can only use one or
2708 2589 the other in your aliases.
2709 2590
2710 2591 Aliases expand Python variables just like system calls using ! or !!
2711 2592 do: all expressions prefixed with '$' get expanded. For details of
2712 2593 the semantic rules, see PEP-215:
2713 2594 http://www.python.org/peps/pep-0215.html. This is the library used by
2714 2595 IPython for variable expansion. If you want to access a true shell
2715 2596 variable, an extra $ is necessary to prevent its expansion by IPython:
2716 2597
2717 2598 In [6]: alias show echo
2718 2599 In [7]: PATH='A Python string'
2719 2600 In [8]: show $PATH
2720 2601 A Python string
2721 2602 In [9]: show $$PATH
2722 2603 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2723 2604
2724 2605 You can use the alias facility to acess all of $PATH. See the %rehash
2725 2606 and %rehashx functions, which automatically create aliases for the
2726 2607 contents of your $PATH.
2727 2608
2728 2609 If called with no parameters, %alias prints the current alias table."""
2729 2610
2730 2611 par = parameter_s.strip()
2731 2612 if not par:
2732 2613 stored = self.db.get('stored_aliases', {} )
2733 2614 aliases = sorted(self.shell.alias_manager.aliases)
2734 2615 # for k, v in stored:
2735 2616 # atab.append(k, v[0])
2736 2617
2737 2618 print "Total number of aliases:", len(aliases)
2738 2619 return aliases
2739 2620
2740 2621 # Now try to define a new one
2741 2622 try:
2742 2623 alias,cmd = par.split(None, 1)
2743 2624 except:
2744 2625 print oinspect.getdoc(self.magic_alias)
2745 2626 else:
2746 2627 self.shell.alias_manager.soft_define_alias(alias, cmd)
2747 2628 # end magic_alias
2748 2629
2749 2630 def magic_unalias(self, parameter_s = ''):
2750 2631 """Remove an alias"""
2751 2632
2752 2633 aname = parameter_s.strip()
2753 2634 self.shell.alias_manager.undefine_alias(aname)
2754 2635 stored = self.db.get('stored_aliases', {} )
2755 2636 if aname in stored:
2756 2637 print "Removing %stored alias",aname
2757 2638 del stored[aname]
2758 2639 self.db['stored_aliases'] = stored
2759 2640
2760 2641
2761 2642 def magic_rehashx(self, parameter_s = ''):
2762 2643 """Update the alias table with all executable files in $PATH.
2763 2644
2764 2645 This version explicitly checks that every entry in $PATH is a file
2765 2646 with execute access (os.X_OK), so it is much slower than %rehash.
2766 2647
2767 2648 Under Windows, it checks executability as a match agains a
2768 2649 '|'-separated string of extensions, stored in the IPython config
2769 2650 variable win_exec_ext. This defaults to 'exe|com|bat'.
2770 2651
2771 2652 This function also resets the root module cache of module completer,
2772 2653 used on slow filesystems.
2773 2654 """
2774 2655 from IPython.core.alias import InvalidAliasError
2775 2656
2776 2657 # for the benefit of module completer in ipy_completers.py
2777 2658 del self.db['rootmodules']
2778 2659
2779 2660 path = [os.path.abspath(os.path.expanduser(p)) for p in
2780 2661 os.environ.get('PATH','').split(os.pathsep)]
2781 2662 path = filter(os.path.isdir,path)
2782 2663
2783 2664 syscmdlist = []
2784 2665 # Now define isexec in a cross platform manner.
2785 2666 if os.name == 'posix':
2786 2667 isexec = lambda fname:os.path.isfile(fname) and \
2787 2668 os.access(fname,os.X_OK)
2788 2669 else:
2789 2670 try:
2790 2671 winext = os.environ['pathext'].replace(';','|').replace('.','')
2791 2672 except KeyError:
2792 2673 winext = 'exe|com|bat|py'
2793 2674 if 'py' not in winext:
2794 2675 winext += '|py'
2795 2676 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2796 2677 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2797 2678 savedir = os.getcwd()
2798 2679
2799 2680 # Now walk the paths looking for executables to alias.
2800 2681 try:
2801 2682 # write the whole loop for posix/Windows so we don't have an if in
2802 2683 # the innermost part
2803 2684 if os.name == 'posix':
2804 2685 for pdir in path:
2805 2686 os.chdir(pdir)
2806 2687 for ff in os.listdir(pdir):
2807 2688 if isexec(ff):
2808 2689 try:
2809 2690 # Removes dots from the name since ipython
2810 2691 # will assume names with dots to be python.
2811 2692 self.shell.alias_manager.define_alias(
2812 2693 ff.replace('.',''), ff)
2813 2694 except InvalidAliasError:
2814 2695 pass
2815 2696 else:
2816 2697 syscmdlist.append(ff)
2817 2698 else:
2818 2699 for pdir in path:
2819 2700 os.chdir(pdir)
2820 2701 for ff in os.listdir(pdir):
2821 2702 base, ext = os.path.splitext(ff)
2822 2703 if isexec(ff) and base.lower() not in self.shell.no_alias:
2823 2704 if ext.lower() == '.exe':
2824 2705 ff = base
2825 2706 try:
2826 2707 # Removes dots from the name since ipython
2827 2708 # will assume names with dots to be python.
2828 2709 self.shell.alias_manager.define_alias(
2829 2710 base.lower().replace('.',''), ff)
2830 2711 except InvalidAliasError:
2831 2712 pass
2832 2713 syscmdlist.append(ff)
2833 2714 db = self.db
2834 2715 db['syscmdlist'] = syscmdlist
2835 2716 finally:
2836 2717 os.chdir(savedir)
2837 2718
2838 2719 def magic_pwd(self, parameter_s = ''):
2839 2720 """Return the current working directory path."""
2840 2721 return os.getcwd()
2841 2722
2842 2723 def magic_cd(self, parameter_s=''):
2843 2724 """Change the current working directory.
2844 2725
2845 2726 This command automatically maintains an internal list of directories
2846 2727 you visit during your IPython session, in the variable _dh. The
2847 2728 command %dhist shows this history nicely formatted. You can also
2848 2729 do 'cd -<tab>' to see directory history conveniently.
2849 2730
2850 2731 Usage:
2851 2732
2852 2733 cd 'dir': changes to directory 'dir'.
2853 2734
2854 2735 cd -: changes to the last visited directory.
2855 2736
2856 2737 cd -<n>: changes to the n-th directory in the directory history.
2857 2738
2858 2739 cd --foo: change to directory that matches 'foo' in history
2859 2740
2860 2741 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2861 2742 (note: cd <bookmark_name> is enough if there is no
2862 2743 directory <bookmark_name>, but a bookmark with the name exists.)
2863 2744 'cd -b <tab>' allows you to tab-complete bookmark names.
2864 2745
2865 2746 Options:
2866 2747
2867 2748 -q: quiet. Do not print the working directory after the cd command is
2868 2749 executed. By default IPython's cd command does print this directory,
2869 2750 since the default prompts do not display path information.
2870 2751
2871 2752 Note that !cd doesn't work for this purpose because the shell where
2872 2753 !command runs is immediately discarded after executing 'command'."""
2873 2754
2874 2755 parameter_s = parameter_s.strip()
2875 2756 #bkms = self.shell.persist.get("bookmarks",{})
2876 2757
2877 2758 oldcwd = os.getcwd()
2878 2759 numcd = re.match(r'(-)(\d+)$',parameter_s)
2879 2760 # jump in directory history by number
2880 2761 if numcd:
2881 2762 nn = int(numcd.group(2))
2882 2763 try:
2883 2764 ps = self.shell.user_ns['_dh'][nn]
2884 2765 except IndexError:
2885 2766 print 'The requested directory does not exist in history.'
2886 2767 return
2887 2768 else:
2888 2769 opts = {}
2889 2770 elif parameter_s.startswith('--'):
2890 2771 ps = None
2891 2772 fallback = None
2892 2773 pat = parameter_s[2:]
2893 2774 dh = self.shell.user_ns['_dh']
2894 2775 # first search only by basename (last component)
2895 2776 for ent in reversed(dh):
2896 2777 if pat in os.path.basename(ent) and os.path.isdir(ent):
2897 2778 ps = ent
2898 2779 break
2899 2780
2900 2781 if fallback is None and pat in ent and os.path.isdir(ent):
2901 2782 fallback = ent
2902 2783
2903 2784 # if we have no last part match, pick the first full path match
2904 2785 if ps is None:
2905 2786 ps = fallback
2906 2787
2907 2788 if ps is None:
2908 2789 print "No matching entry in directory history"
2909 2790 return
2910 2791 else:
2911 2792 opts = {}
2912 2793
2913 2794
2914 2795 else:
2915 2796 #turn all non-space-escaping backslashes to slashes,
2916 2797 # for c:\windows\directory\names\
2917 2798 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2918 2799 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2919 2800 # jump to previous
2920 2801 if ps == '-':
2921 2802 try:
2922 2803 ps = self.shell.user_ns['_dh'][-2]
2923 2804 except IndexError:
2924 2805 raise UsageError('%cd -: No previous directory to change to.')
2925 2806 # jump to bookmark if needed
2926 2807 else:
2927 2808 if not os.path.isdir(ps) or opts.has_key('b'):
2928 2809 bkms = self.db.get('bookmarks', {})
2929 2810
2930 2811 if bkms.has_key(ps):
2931 2812 target = bkms[ps]
2932 2813 print '(bookmark:%s) -> %s' % (ps,target)
2933 2814 ps = target
2934 2815 else:
2935 2816 if opts.has_key('b'):
2936 2817 raise UsageError("Bookmark '%s' not found. "
2937 2818 "Use '%%bookmark -l' to see your bookmarks." % ps)
2938 2819
2939 2820 # at this point ps should point to the target dir
2940 2821 if ps:
2941 2822 try:
2942 2823 os.chdir(os.path.expanduser(ps))
2943 2824 if self.shell.term_title:
2944 2825 platutils.set_term_title('IPython: ' + abbrev_cwd())
2945 2826 except OSError:
2946 2827 print sys.exc_info()[1]
2947 2828 else:
2948 2829 cwd = os.getcwd()
2949 2830 dhist = self.shell.user_ns['_dh']
2950 2831 if oldcwd != cwd:
2951 2832 dhist.append(cwd)
2952 2833 self.db['dhist'] = compress_dhist(dhist)[-100:]
2953 2834
2954 2835 else:
2955 2836 os.chdir(self.shell.home_dir)
2956 2837 if self.shell.term_title:
2957 2838 platutils.set_term_title('IPython: ' + '~')
2958 2839 cwd = os.getcwd()
2959 2840 dhist = self.shell.user_ns['_dh']
2960 2841
2961 2842 if oldcwd != cwd:
2962 2843 dhist.append(cwd)
2963 2844 self.db['dhist'] = compress_dhist(dhist)[-100:]
2964 2845 if not 'q' in opts and self.shell.user_ns['_dh']:
2965 2846 print self.shell.user_ns['_dh'][-1]
2966 2847
2967 2848
2968 2849 def magic_env(self, parameter_s=''):
2969 2850 """List environment variables."""
2970 2851
2971 2852 return os.environ.data
2972 2853
2973 2854 def magic_pushd(self, parameter_s=''):
2974 2855 """Place the current dir on stack and change directory.
2975 2856
2976 2857 Usage:\\
2977 2858 %pushd ['dirname']
2978 2859 """
2979 2860
2980 2861 dir_s = self.shell.dir_stack
2981 2862 tgt = os.path.expanduser(parameter_s)
2982 2863 cwd = os.getcwd().replace(self.home_dir,'~')
2983 2864 if tgt:
2984 2865 self.magic_cd(parameter_s)
2985 2866 dir_s.insert(0,cwd)
2986 2867 return self.magic_dirs()
2987 2868
2988 2869 def magic_popd(self, parameter_s=''):
2989 2870 """Change to directory popped off the top of the stack.
2990 2871 """
2991 2872 if not self.shell.dir_stack:
2992 2873 raise UsageError("%popd on empty stack")
2993 2874 top = self.shell.dir_stack.pop(0)
2994 2875 self.magic_cd(top)
2995 2876 print "popd ->",top
2996 2877
2997 2878 def magic_dirs(self, parameter_s=''):
2998 2879 """Return the current directory stack."""
2999 2880
3000 2881 return self.shell.dir_stack
3001 2882
3002 2883 def magic_dhist(self, parameter_s=''):
3003 2884 """Print your history of visited directories.
3004 2885
3005 2886 %dhist -> print full history\\
3006 2887 %dhist n -> print last n entries only\\
3007 2888 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
3008 2889
3009 2890 This history is automatically maintained by the %cd command, and
3010 2891 always available as the global list variable _dh. You can use %cd -<n>
3011 2892 to go to directory number <n>.
3012 2893
3013 2894 Note that most of time, you should view directory history by entering
3014 2895 cd -<TAB>.
3015 2896
3016 2897 """
3017 2898
3018 2899 dh = self.shell.user_ns['_dh']
3019 2900 if parameter_s:
3020 2901 try:
3021 2902 args = map(int,parameter_s.split())
3022 2903 except:
3023 2904 self.arg_err(Magic.magic_dhist)
3024 2905 return
3025 2906 if len(args) == 1:
3026 2907 ini,fin = max(len(dh)-(args[0]),0),len(dh)
3027 2908 elif len(args) == 2:
3028 2909 ini,fin = args
3029 2910 else:
3030 2911 self.arg_err(Magic.magic_dhist)
3031 2912 return
3032 2913 else:
3033 2914 ini,fin = 0,len(dh)
3034 2915 nlprint(dh,
3035 2916 header = 'Directory history (kept in _dh)',
3036 2917 start=ini,stop=fin)
3037 2918
3038 2919 @testdec.skip_doctest
3039 2920 def magic_sc(self, parameter_s=''):
3040 2921 """Shell capture - execute a shell command and capture its output.
3041 2922
3042 2923 DEPRECATED. Suboptimal, retained for backwards compatibility.
3043 2924
3044 2925 You should use the form 'var = !command' instead. Example:
3045 2926
3046 2927 "%sc -l myfiles = ls ~" should now be written as
3047 2928
3048 2929 "myfiles = !ls ~"
3049 2930
3050 2931 myfiles.s, myfiles.l and myfiles.n still apply as documented
3051 2932 below.
3052 2933
3053 2934 --
3054 2935 %sc [options] varname=command
3055 2936
3056 2937 IPython will run the given command using commands.getoutput(), and
3057 2938 will then update the user's interactive namespace with a variable
3058 2939 called varname, containing the value of the call. Your command can
3059 2940 contain shell wildcards, pipes, etc.
3060 2941
3061 2942 The '=' sign in the syntax is mandatory, and the variable name you
3062 2943 supply must follow Python's standard conventions for valid names.
3063 2944
3064 2945 (A special format without variable name exists for internal use)
3065 2946
3066 2947 Options:
3067 2948
3068 2949 -l: list output. Split the output on newlines into a list before
3069 2950 assigning it to the given variable. By default the output is stored
3070 2951 as a single string.
3071 2952
3072 2953 -v: verbose. Print the contents of the variable.
3073 2954
3074 2955 In most cases you should not need to split as a list, because the
3075 2956 returned value is a special type of string which can automatically
3076 2957 provide its contents either as a list (split on newlines) or as a
3077 2958 space-separated string. These are convenient, respectively, either
3078 2959 for sequential processing or to be passed to a shell command.
3079 2960
3080 2961 For example:
3081 2962
3082 2963 # all-random
3083 2964
3084 2965 # Capture into variable a
3085 2966 In [1]: sc a=ls *py
3086 2967
3087 2968 # a is a string with embedded newlines
3088 2969 In [2]: a
3089 2970 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3090 2971
3091 2972 # which can be seen as a list:
3092 2973 In [3]: a.l
3093 2974 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3094 2975
3095 2976 # or as a whitespace-separated string:
3096 2977 In [4]: a.s
3097 2978 Out[4]: 'setup.py win32_manual_post_install.py'
3098 2979
3099 2980 # a.s is useful to pass as a single command line:
3100 2981 In [5]: !wc -l $a.s
3101 2982 146 setup.py
3102 2983 130 win32_manual_post_install.py
3103 2984 276 total
3104 2985
3105 2986 # while the list form is useful to loop over:
3106 2987 In [6]: for f in a.l:
3107 2988 ...: !wc -l $f
3108 2989 ...:
3109 2990 146 setup.py
3110 2991 130 win32_manual_post_install.py
3111 2992
3112 2993 Similiarly, the lists returned by the -l option are also special, in
3113 2994 the sense that you can equally invoke the .s attribute on them to
3114 2995 automatically get a whitespace-separated string from their contents:
3115 2996
3116 2997 In [7]: sc -l b=ls *py
3117 2998
3118 2999 In [8]: b
3119 3000 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3120 3001
3121 3002 In [9]: b.s
3122 3003 Out[9]: 'setup.py win32_manual_post_install.py'
3123 3004
3124 3005 In summary, both the lists and strings used for ouptut capture have
3125 3006 the following special attributes:
3126 3007
3127 3008 .l (or .list) : value as list.
3128 3009 .n (or .nlstr): value as newline-separated string.
3129 3010 .s (or .spstr): value as space-separated string.
3130 3011 """
3131 3012
3132 3013 opts,args = self.parse_options(parameter_s,'lv')
3133 3014 # Try to get a variable name and command to run
3134 3015 try:
3135 3016 # the variable name must be obtained from the parse_options
3136 3017 # output, which uses shlex.split to strip options out.
3137 3018 var,_ = args.split('=',1)
3138 3019 var = var.strip()
3139 3020 # But the the command has to be extracted from the original input
3140 3021 # parameter_s, not on what parse_options returns, to avoid the
3141 3022 # quote stripping which shlex.split performs on it.
3142 3023 _,cmd = parameter_s.split('=',1)
3143 3024 except ValueError:
3144 3025 var,cmd = '',''
3145 3026 # If all looks ok, proceed
3146 3027 out,err = self.shell.getoutputerror(cmd)
3147 3028 if err:
3148 3029 print >> Term.cerr,err
3149 3030 if opts.has_key('l'):
3150 3031 out = SList(out.split('\n'))
3151 3032 else:
3152 3033 out = LSString(out)
3153 3034 if opts.has_key('v'):
3154 3035 print '%s ==\n%s' % (var,pformat(out))
3155 3036 if var:
3156 3037 self.shell.user_ns.update({var:out})
3157 3038 else:
3158 3039 return out
3159 3040
3160 3041 def magic_sx(self, parameter_s=''):
3161 3042 """Shell execute - run a shell command and capture its output.
3162 3043
3163 3044 %sx command
3164 3045
3165 3046 IPython will run the given command using commands.getoutput(), and
3166 3047 return the result formatted as a list (split on '\\n'). Since the
3167 3048 output is _returned_, it will be stored in ipython's regular output
3168 3049 cache Out[N] and in the '_N' automatic variables.
3169 3050
3170 3051 Notes:
3171 3052
3172 3053 1) If an input line begins with '!!', then %sx is automatically
3173 3054 invoked. That is, while:
3174 3055 !ls
3175 3056 causes ipython to simply issue system('ls'), typing
3176 3057 !!ls
3177 3058 is a shorthand equivalent to:
3178 3059 %sx ls
3179 3060
3180 3061 2) %sx differs from %sc in that %sx automatically splits into a list,
3181 3062 like '%sc -l'. The reason for this is to make it as easy as possible
3182 3063 to process line-oriented shell output via further python commands.
3183 3064 %sc is meant to provide much finer control, but requires more
3184 3065 typing.
3185 3066
3186 3067 3) Just like %sc -l, this is a list with special attributes:
3187 3068
3188 3069 .l (or .list) : value as list.
3189 3070 .n (or .nlstr): value as newline-separated string.
3190 3071 .s (or .spstr): value as whitespace-separated string.
3191 3072
3192 3073 This is very useful when trying to use such lists as arguments to
3193 3074 system commands."""
3194 3075
3195 3076 if parameter_s:
3196 3077 out,err = self.shell.getoutputerror(parameter_s)
3197 3078 if err:
3198 3079 print >> Term.cerr,err
3199 3080 return SList(out.split('\n'))
3200 3081
3201 3082 def magic_bg(self, parameter_s=''):
3202 3083 """Run a job in the background, in a separate thread.
3203 3084
3204 3085 For example,
3205 3086
3206 3087 %bg myfunc(x,y,z=1)
3207 3088
3208 3089 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3209 3090 execution starts, a message will be printed indicating the job
3210 3091 number. If your job number is 5, you can use
3211 3092
3212 3093 myvar = jobs.result(5) or myvar = jobs[5].result
3213 3094
3214 3095 to assign this result to variable 'myvar'.
3215 3096
3216 3097 IPython has a job manager, accessible via the 'jobs' object. You can
3217 3098 type jobs? to get more information about it, and use jobs.<TAB> to see
3218 3099 its attributes. All attributes not starting with an underscore are
3219 3100 meant for public use.
3220 3101
3221 3102 In particular, look at the jobs.new() method, which is used to create
3222 3103 new jobs. This magic %bg function is just a convenience wrapper
3223 3104 around jobs.new(), for expression-based jobs. If you want to create a
3224 3105 new job with an explicit function object and arguments, you must call
3225 3106 jobs.new() directly.
3226 3107
3227 3108 The jobs.new docstring also describes in detail several important
3228 3109 caveats associated with a thread-based model for background job
3229 3110 execution. Type jobs.new? for details.
3230 3111
3231 3112 You can check the status of all jobs with jobs.status().
3232 3113
3233 3114 The jobs variable is set by IPython into the Python builtin namespace.
3234 3115 If you ever declare a variable named 'jobs', you will shadow this
3235 3116 name. You can either delete your global jobs variable to regain
3236 3117 access to the job manager, or make a new name and assign it manually
3237 3118 to the manager (stored in IPython's namespace). For example, to
3238 3119 assign the job manager to the Jobs name, use:
3239 3120
3240 3121 Jobs = __builtins__.jobs"""
3241 3122
3242 3123 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3243 3124
3244 3125 def magic_r(self, parameter_s=''):
3245 3126 """Repeat previous input.
3246 3127
3247 3128 Note: Consider using the more powerfull %rep instead!
3248 3129
3249 3130 If given an argument, repeats the previous command which starts with
3250 3131 the same string, otherwise it just repeats the previous input.
3251 3132
3252 3133 Shell escaped commands (with ! as first character) are not recognized
3253 3134 by this system, only pure python code and magic commands.
3254 3135 """
3255 3136
3256 3137 start = parameter_s.strip()
3257 3138 esc_magic = ESC_MAGIC
3258 3139 # Identify magic commands even if automagic is on (which means
3259 3140 # the in-memory version is different from that typed by the user).
3260 3141 if self.shell.automagic:
3261 3142 start_magic = esc_magic+start
3262 3143 else:
3263 3144 start_magic = start
3264 3145 # Look through the input history in reverse
3265 3146 for n in range(len(self.shell.input_hist)-2,0,-1):
3266 3147 input = self.shell.input_hist[n]
3267 3148 # skip plain 'r' lines so we don't recurse to infinity
3268 3149 if input != '_ip.magic("r")\n' and \
3269 3150 (input.startswith(start) or input.startswith(start_magic)):
3270 3151 #print 'match',`input` # dbg
3271 3152 print 'Executing:',input,
3272 3153 self.shell.runlines(input)
3273 3154 return
3274 3155 print 'No previous input matching `%s` found.' % start
3275 3156
3276 3157
3277 3158 def magic_bookmark(self, parameter_s=''):
3278 3159 """Manage IPython's bookmark system.
3279 3160
3280 3161 %bookmark <name> - set bookmark to current dir
3281 3162 %bookmark <name> <dir> - set bookmark to <dir>
3282 3163 %bookmark -l - list all bookmarks
3283 3164 %bookmark -d <name> - remove bookmark
3284 3165 %bookmark -r - remove all bookmarks
3285 3166
3286 3167 You can later on access a bookmarked folder with:
3287 3168 %cd -b <name>
3288 3169 or simply '%cd <name>' if there is no directory called <name> AND
3289 3170 there is such a bookmark defined.
3290 3171
3291 3172 Your bookmarks persist through IPython sessions, but they are
3292 3173 associated with each profile."""
3293 3174
3294 3175 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3295 3176 if len(args) > 2:
3296 3177 raise UsageError("%bookmark: too many arguments")
3297 3178
3298 3179 bkms = self.db.get('bookmarks',{})
3299 3180
3300 3181 if opts.has_key('d'):
3301 3182 try:
3302 3183 todel = args[0]
3303 3184 except IndexError:
3304 3185 raise UsageError(
3305 3186 "%bookmark -d: must provide a bookmark to delete")
3306 3187 else:
3307 3188 try:
3308 3189 del bkms[todel]
3309 3190 except KeyError:
3310 3191 raise UsageError(
3311 3192 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3312 3193
3313 3194 elif opts.has_key('r'):
3314 3195 bkms = {}
3315 3196 elif opts.has_key('l'):
3316 3197 bks = bkms.keys()
3317 3198 bks.sort()
3318 3199 if bks:
3319 3200 size = max(map(len,bks))
3320 3201 else:
3321 3202 size = 0
3322 3203 fmt = '%-'+str(size)+'s -> %s'
3323 3204 print 'Current bookmarks:'
3324 3205 for bk in bks:
3325 3206 print fmt % (bk,bkms[bk])
3326 3207 else:
3327 3208 if not args:
3328 3209 raise UsageError("%bookmark: You must specify the bookmark name")
3329 3210 elif len(args)==1:
3330 3211 bkms[args[0]] = os.getcwd()
3331 3212 elif len(args)==2:
3332 3213 bkms[args[0]] = args[1]
3333 3214 self.db['bookmarks'] = bkms
3334 3215
3335 3216 def magic_pycat(self, parameter_s=''):
3336 3217 """Show a syntax-highlighted file through a pager.
3337 3218
3338 3219 This magic is similar to the cat utility, but it will assume the file
3339 3220 to be Python source and will show it with syntax highlighting. """
3340 3221
3341 3222 try:
3342 3223 filename = get_py_filename(parameter_s)
3343 3224 cont = file_read(filename)
3344 3225 except IOError:
3345 3226 try:
3346 3227 cont = eval(parameter_s,self.user_ns)
3347 3228 except NameError:
3348 3229 cont = None
3349 3230 if cont is None:
3350 3231 print "Error: no such file or variable"
3351 3232 return
3352 3233
3353 3234 page(self.shell.pycolorize(cont),
3354 3235 screen_lines=self.shell.usable_screen_length)
3355 3236
3356 3237 def _rerun_pasted(self):
3357 3238 """ Rerun a previously pasted command.
3358 3239 """
3359 3240 b = self.user_ns.get('pasted_block', None)
3360 3241 if b is None:
3361 3242 raise UsageError('No previous pasted block available')
3362 3243 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3363 3244 exec b in self.user_ns
3364 3245
3365 3246 def _get_pasted_lines(self, sentinel):
3366 3247 """ Yield pasted lines until the user enters the given sentinel value.
3367 3248 """
3368 3249 from IPython.core import iplib
3369 3250 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3370 3251 while True:
3371 3252 l = iplib.raw_input_original(':')
3372 3253 if l == sentinel:
3373 3254 return
3374 3255 else:
3375 3256 yield l
3376 3257
3377 3258 def _strip_pasted_lines_for_code(self, raw_lines):
3378 3259 """ Strip non-code parts of a sequence of lines to return a block of
3379 3260 code.
3380 3261 """
3381 3262 # Regular expressions that declare text we strip from the input:
3382 3263 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3383 3264 r'^\s*(\s?>)+', # Python input prompt
3384 3265 r'^\s*\.{3,}', # Continuation prompts
3385 3266 r'^\++',
3386 3267 ]
3387 3268
3388 3269 strip_from_start = map(re.compile,strip_re)
3389 3270
3390 3271 lines = []
3391 3272 for l in raw_lines:
3392 3273 for pat in strip_from_start:
3393 3274 l = pat.sub('',l)
3394 3275 lines.append(l)
3395 3276
3396 3277 block = "\n".join(lines) + '\n'
3397 3278 #print "block:\n",block
3398 3279 return block
3399 3280
3400 3281 def _execute_block(self, block, par):
3401 3282 """ Execute a block, or store it in a variable, per the user's request.
3402 3283 """
3403 3284 if not par:
3404 3285 b = textwrap.dedent(block)
3405 3286 self.user_ns['pasted_block'] = b
3406 3287 exec b in self.user_ns
3407 3288 else:
3408 3289 self.user_ns[par] = SList(block.splitlines())
3409 3290 print "Block assigned to '%s'" % par
3410 3291
3411 3292 def magic_cpaste(self, parameter_s=''):
3412 3293 """Allows you to paste & execute a pre-formatted code block from clipboard.
3413 3294
3414 3295 You must terminate the block with '--' (two minus-signs) alone on the
3415 3296 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3416 3297 is the new sentinel for this operation)
3417 3298
3418 3299 The block is dedented prior to execution to enable execution of method
3419 3300 definitions. '>' and '+' characters at the beginning of a line are
3420 3301 ignored, to allow pasting directly from e-mails, diff files and
3421 3302 doctests (the '...' continuation prompt is also stripped). The
3422 3303 executed block is also assigned to variable named 'pasted_block' for
3423 3304 later editing with '%edit pasted_block'.
3424 3305
3425 3306 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3426 3307 This assigns the pasted block to variable 'foo' as string, without
3427 3308 dedenting or executing it (preceding >>> and + is still stripped)
3428 3309
3429 3310 '%cpaste -r' re-executes the block previously entered by cpaste.
3430 3311
3431 3312 Do not be alarmed by garbled output on Windows (it's a readline bug).
3432 3313 Just press enter and type -- (and press enter again) and the block
3433 3314 will be what was just pasted.
3434 3315
3435 3316 IPython statements (magics, shell escapes) are not supported (yet).
3436 3317
3437 3318 See also
3438 3319 --------
3439 3320 paste: automatically pull code from clipboard.
3440 3321 """
3441 3322
3442 3323 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3443 3324 par = args.strip()
3444 3325 if opts.has_key('r'):
3445 3326 self._rerun_pasted()
3446 3327 return
3447 3328
3448 3329 sentinel = opts.get('s','--')
3449 3330
3450 3331 block = self._strip_pasted_lines_for_code(
3451 3332 self._get_pasted_lines(sentinel))
3452 3333
3453 3334 self._execute_block(block, par)
3454 3335
3455 3336 def magic_paste(self, parameter_s=''):
3456 3337 """Allows you to paste & execute a pre-formatted code block from clipboard.
3457 3338
3458 3339 The text is pulled directly from the clipboard without user
3459 3340 intervention and printed back on the screen before execution (unless
3460 3341 the -q flag is given to force quiet mode).
3461 3342
3462 3343 The block is dedented prior to execution to enable execution of method
3463 3344 definitions. '>' and '+' characters at the beginning of a line are
3464 3345 ignored, to allow pasting directly from e-mails, diff files and
3465 3346 doctests (the '...' continuation prompt is also stripped). The
3466 3347 executed block is also assigned to variable named 'pasted_block' for
3467 3348 later editing with '%edit pasted_block'.
3468 3349
3469 3350 You can also pass a variable name as an argument, e.g. '%paste foo'.
3470 3351 This assigns the pasted block to variable 'foo' as string, without
3471 3352 dedenting or executing it (preceding >>> and + is still stripped)
3472 3353
3473 3354 Options
3474 3355 -------
3475 3356
3476 3357 -r: re-executes the block previously entered by cpaste.
3477 3358
3478 3359 -q: quiet mode: do not echo the pasted text back to the terminal.
3479 3360
3480 3361 IPython statements (magics, shell escapes) are not supported (yet).
3481 3362
3482 3363 See also
3483 3364 --------
3484 3365 cpaste: manually paste code into terminal until you mark its end.
3485 3366 """
3486 3367 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3487 3368 par = args.strip()
3488 3369 if opts.has_key('r'):
3489 3370 self._rerun_pasted()
3490 3371 return
3491 3372
3492 3373 text = self.shell.hooks.clipboard_get()
3493 3374 block = self._strip_pasted_lines_for_code(text.splitlines())
3494 3375
3495 3376 # By default, echo back to terminal unless quiet mode is requested
3496 3377 if not opts.has_key('q'):
3497 3378 write = self.shell.write
3498 3379 write(self.shell.pycolorize(block))
3499 3380 if not block.endswith('\n'):
3500 3381 write('\n')
3501 3382 write("## -- End pasted text --\n")
3502 3383
3503 3384 self._execute_block(block, par)
3504 3385
3505 3386 def magic_quickref(self,arg):
3506 3387 """ Show a quick reference sheet """
3507 3388 import IPython.core.usage
3508 3389 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3509 3390
3510 3391 page(qr)
3511 3392
3512 3393 def magic_doctest_mode(self,parameter_s=''):
3513 3394 """Toggle doctest mode on and off.
3514 3395
3515 3396 This mode allows you to toggle the prompt behavior between normal
3516 3397 IPython prompts and ones that are as similar to the default IPython
3517 3398 interpreter as possible.
3518 3399
3519 3400 It also supports the pasting of code snippets that have leading '>>>'
3520 3401 and '...' prompts in them. This means that you can paste doctests from
3521 3402 files or docstrings (even if they have leading whitespace), and the
3522 3403 code will execute correctly. You can then use '%history -tn' to see
3523 3404 the translated history without line numbers; this will give you the
3524 3405 input after removal of all the leading prompts and whitespace, which
3525 3406 can be pasted back into an editor.
3526 3407
3527 3408 With these features, you can switch into this mode easily whenever you
3528 3409 need to do testing and changes to doctests, without having to leave
3529 3410 your existing IPython session.
3530 3411 """
3531 3412
3532 3413 # XXX - Fix this to have cleaner activate/deactivate calls.
3533 3414 from IPython.extensions import InterpreterPasteInput as ipaste
3534 3415 from IPython.utils.ipstruct import Struct
3535 3416
3536 3417 # Shorthands
3537 3418 shell = self.shell
3538 3419 oc = shell.outputcache
3539 3420 meta = shell.meta
3540 3421 # dstore is a data store kept in the instance metadata bag to track any
3541 3422 # changes we make, so we can undo them later.
3542 3423 dstore = meta.setdefault('doctest_mode',Struct())
3543 3424 save_dstore = dstore.setdefault
3544 3425
3545 3426 # save a few values we'll need to recover later
3546 3427 mode = save_dstore('mode',False)
3547 3428 save_dstore('rc_pprint',shell.pprint)
3548 3429 save_dstore('xmode',shell.InteractiveTB.mode)
3549 3430 save_dstore('rc_separate_out',shell.separate_out)
3550 3431 save_dstore('rc_separate_out2',shell.separate_out2)
3551 3432 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3552 3433 save_dstore('rc_separate_in',shell.separate_in)
3553 3434
3554 3435 if mode == False:
3555 3436 # turn on
3556 3437 ipaste.activate_prefilter()
3557 3438
3558 3439 oc.prompt1.p_template = '>>> '
3559 3440 oc.prompt2.p_template = '... '
3560 3441 oc.prompt_out.p_template = ''
3561 3442
3562 3443 # Prompt separators like plain python
3563 3444 oc.input_sep = oc.prompt1.sep = ''
3564 3445 oc.output_sep = ''
3565 3446 oc.output_sep2 = ''
3566 3447
3567 3448 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3568 3449 oc.prompt_out.pad_left = False
3569 3450
3570 3451 shell.pprint = False
3571 3452
3572 3453 shell.magic_xmode('Plain')
3573 3454
3574 3455 else:
3575 3456 # turn off
3576 3457 ipaste.deactivate_prefilter()
3577 3458
3578 3459 oc.prompt1.p_template = shell.prompt_in1
3579 3460 oc.prompt2.p_template = shell.prompt_in2
3580 3461 oc.prompt_out.p_template = shell.prompt_out
3581 3462
3582 3463 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3583 3464
3584 3465 oc.output_sep = dstore.rc_separate_out
3585 3466 oc.output_sep2 = dstore.rc_separate_out2
3586 3467
3587 3468 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3588 3469 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3589 3470
3590 3471 rc.pprint = dstore.rc_pprint
3591 3472
3592 3473 shell.magic_xmode(dstore.xmode)
3593 3474
3594 3475 # Store new mode and inform
3595 3476 dstore.mode = bool(1-int(mode))
3596 3477 print 'Doctest mode is:',
3597 3478 print ['OFF','ON'][dstore.mode]
3598 3479
3599 3480 def magic_gui(self, parameter_s=''):
3600 3481 """Enable or disable IPython GUI event loop integration.
3601 3482
3602 3483 %gui [-a] [GUINAME]
3603 3484
3604 3485 This magic replaces IPython's threaded shells that were activated
3605 3486 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3606 3487 can now be enabled, disabled and swtiched at runtime and keyboard
3607 3488 interrupts should work without any problems. The following toolkits
3608 3489 are supported: wxPython, PyQt4, PyGTK, and Tk::
3609 3490
3610 3491 %gui wx # enable wxPython event loop integration
3611 3492 %gui qt4|qt # enable PyQt4 event loop integration
3612 3493 %gui gtk # enable PyGTK event loop integration
3613 3494 %gui tk # enable Tk event loop integration
3614 3495 %gui # disable all event loop integration
3615 3496
3616 3497 WARNING: after any of these has been called you can simply create
3617 3498 an application object, but DO NOT start the event loop yourself, as
3618 3499 we have already handled that.
3619 3500
3620 3501 If you want us to create an appropriate application object add the
3621 3502 "-a" flag to your command::
3622 3503
3623 3504 %gui -a wx
3624 3505
3625 3506 This is highly recommended for most users.
3626 3507 """
3627 from IPython.lib import inputhook
3628
3629 3508 opts, arg = self.parse_options(parameter_s,'a')
3630 if not arg:
3631 inputhook.clear_inputhook()
3632 return
3633
3634 guis = {'tk': inputhook.enable_tk,
3635 'gtk':inputhook.enable_gtk,
3636 'wx': inputhook.enable_wx,
3637 'qt': inputhook.enable_qt4, # qt3 not supported
3638 'qt4': inputhook.enable_qt4 }
3639 try:
3640 gui = guis[arg]
3641 except KeyError:
3642 e="Invalid GUI request %r, valid ones are:%s" % (arg, guis.keys())
3643 raise UsageError(e)
3644
3645 #print 'Switching IPython gui support to:', arg, 'a' in opts # dbg
3646 return gui('a' in opts)
3509 if arg=='': arg = None
3510 return enable_gui(arg, 'a' in opts)
3647 3511
3648 3512 def magic_load_ext(self, module_str):
3649 3513 """Load an IPython extension by its module name."""
3650 3514 self.load_extension(module_str)
3651 3515
3652 3516 def magic_unload_ext(self, module_str):
3653 3517 """Unload an IPython extension by its module name."""
3654 3518 self.unload_extension(module_str)
3655 3519
3656 3520 def magic_reload_ext(self, module_str):
3657 3521 """Reload an IPython extension by its module name."""
3658 3522 self.reload_extension(module_str)
3659 3523
3660 3524 def magic_install_profiles(self, s):
3661 3525 """Install the default IPython profiles into the .ipython dir.
3662 3526
3663 3527 If the default profiles have already been installed, they will not
3664 3528 be overwritten. You can force overwriting them by using the ``-o``
3665 3529 option::
3666 3530
3667 3531 In [1]: %install_profiles -o
3668 3532 """
3669 3533 if '-o' in s:
3670 3534 overwrite = True
3671 3535 else:
3672 3536 overwrite = False
3673 3537 from IPython.config import profile
3674 3538 profile_dir = os.path.split(profile.__file__)[0]
3675 3539 ipython_dir = self.ipython_dir
3676 3540 files = os.listdir(profile_dir)
3677 3541
3678 3542 to_install = []
3679 3543 for f in files:
3680 3544 if f.startswith('ipython_config'):
3681 3545 src = os.path.join(profile_dir, f)
3682 3546 dst = os.path.join(ipython_dir, f)
3683 3547 if (not os.path.isfile(dst)) or overwrite:
3684 3548 to_install.append((f, src, dst))
3685 3549 if len(to_install)>0:
3686 3550 print "Installing profiles to: ", ipython_dir
3687 3551 for (f, src, dst) in to_install:
3688 3552 shutil.copy(src, dst)
3689 3553 print " %s" % f
3690 3554
3691 3555 def magic_install_default_config(self, s):
3692 3556 """Install IPython's default config file into the .ipython dir.
3693 3557
3694 3558 If the default config file (:file:`ipython_config.py`) is already
3695 3559 installed, it will not be overwritten. You can force overwriting
3696 3560 by using the ``-o`` option::
3697 3561
3698 3562 In [1]: %install_default_config
3699 3563 """
3700 3564 if '-o' in s:
3701 3565 overwrite = True
3702 3566 else:
3703 3567 overwrite = False
3704 3568 from IPython.config import default
3705 3569 config_dir = os.path.split(default.__file__)[0]
3706 3570 ipython_dir = self.ipython_dir
3707 3571 default_config_file_name = 'ipython_config.py'
3708 3572 src = os.path.join(config_dir, default_config_file_name)
3709 3573 dst = os.path.join(ipython_dir, default_config_file_name)
3710 3574 if (not os.path.isfile(dst)) or overwrite:
3711 3575 shutil.copy(src, dst)
3712 3576 print "Installing default config file: %s" % dst
3713 3577
3714 3578 # Pylab support: simple wrappers that activate pylab, load gui input
3715 3579 # handling and modify slightly %run
3716 3580
3717 3581 @testdec.skip_doctest
3718 3582 def _pylab_magic_run(self, parameter_s=''):
3719 3583 Magic.magic_run(self, parameter_s,
3720 3584 runner=mpl_runner(self.shell.safe_execfile))
3721 3585
3722 3586 _pylab_magic_run.__doc__ = magic_run.__doc__
3723 3587
3724 3588 @testdec.skip_doctest
3725 3589 def magic_pylab(self, s):
3726 3590 """Load numpy and matplotlib to work interactively.
3727 3591
3728 3592 %pylab [GUINAME]
3729 3593
3730 3594 This function lets you activate pylab (matplotlib, numpy and
3731 3595 interactive support) at any point during an IPython session.
3732 3596
3733 3597 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3734 3598 pylab and mlab, as well as all names from numpy and pylab.
3735 3599
3736 3600 Parameters
3737 3601 ----------
3738 3602 guiname : optional
3739 3603 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3740 3604 'tk'). If given, the corresponding Matplotlib backend is used,
3741 3605 otherwise matplotlib's default (which you can override in your
3742 3606 matplotlib config file) is used.
3743 3607
3744 3608 Examples
3745 3609 --------
3746 3610 In this case, where the MPL default is TkAgg:
3747 3611 In [2]: %pylab
3748 3612
3749 3613 Welcome to pylab, a matplotlib-based Python environment.
3750 3614 Backend in use: TkAgg
3751 3615 For more information, type 'help(pylab)'.
3752 3616
3753 3617 But you can explicitly request a different backend:
3754 3618 In [3]: %pylab qt
3755 3619
3756 3620 Welcome to pylab, a matplotlib-based Python environment.
3757 3621 Backend in use: Qt4Agg
3758 3622 For more information, type 'help(pylab)'.
3759 3623 """
3760
3761 gui = pylab_activate(self.shell.user_ns, s)
3762 self.shell.magic_gui('-a %s' % gui)
3763 self.shell.magic_run = self._pylab_magic_run
3624 self.shell.enable_pylab(s)
3764 3625
3765 3626 # end Magic
@@ -1,525 +1,571 b''
1 1 #!/usr/bin/env python
2 # encoding: utf-8
2 # coding: utf-8
3 3 """
4 4 Inputhook management for GUI event loop integration.
5 5 """
6 6
7 7 #-----------------------------------------------------------------------------
8 8 # Copyright (C) 2008-2009 The IPython Development Team
9 9 #
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Imports
16 16 #-----------------------------------------------------------------------------
17 17
18 18 import ctypes
19 19 import sys
20 20
21 21 #-----------------------------------------------------------------------------
22 22 # Constants
23 23 #-----------------------------------------------------------------------------
24 24
25 25 # Constants for identifying the GUI toolkits.
26 26 GUI_WX = 'wx'
27 GUI_QT = 'qt'
27 28 GUI_QT4 = 'qt4'
28 29 GUI_GTK = 'gtk'
29 30 GUI_TK = 'tk'
30 31
31 32 #-----------------------------------------------------------------------------
32 33 # Utility classes
33 34 #-----------------------------------------------------------------------------
34 35
35 36
36 37 class _DummyMainloop(object):
37 38 """A special manager to hijack GUI mainloops that is mostly a no-op.
38 39
39 40 We are not using this class currently as it breaks GUI code that calls
40 41 a mainloop function after the app has started to process pending events.
41 42 """
42 43 def __init__(self, ml, ihm, gui_type):
43 44 self.ml = ml
44 45 self.ihm = ihm
45 46 self.gui_type = gui_type
46 47
47 48 def __call__(self, *args, **kw):
48 49 if self.ihm.current_gui() == self.gui_type:
49 50 pass
50 51 else:
51 52 self.ml(*args, **kw)
52 53
53 54
54 55 #-----------------------------------------------------------------------------
55 56 # Appstart and spin functions
56 57 #-----------------------------------------------------------------------------
57 58
58 59
59 60 def appstart_qt4(app):
60 61 """Start the qt4 event loop in a way that plays with IPython.
61 62
62 63 When a qt4 app is run interactively in IPython, the event loop should
63 64 not be started. This function checks to see if IPython's qt4 integration
64 65 is activated and if so, it passes. If not, it will call the :meth:`exec_`
65 66 method of the main qt4 app.
66 67
67 68 This function should be used by users who want their qt4 scripts to work
68 69 both at the command line and in IPython. These users should put the
69 70 following logic at the bottom on their script, after they create a
70 71 :class:`QApplication` instance (called ``app`` here)::
71 72
72 73 try:
73 74 from IPython.lib.inputhook import appstart_qt4
74 75 appstart_qt4(app)
75 76 except ImportError:
76 77 app.exec_()
77 78 """
78 79 from PyQt4 import QtCore, QtGui
79 80
80 81 assert isinstance(app, QtCore.QCoreApplication)
81 82 if app is not None:
82 83 if current_gui() == GUI_QT4:
83 84 pass
84 85 else:
85 86 app.exec_()
86 87
87 88
88 89 def appstart_wx(app):
89 90 """Start the wx event loop in a way that plays with IPython.
90 91
91 92 When a wx app is run interactively in IPython, the event loop should
92 93 not be started. This function checks to see if IPython's wx integration
93 94 is activated and if so, it passes. If not, it will call the
94 95 :meth:`MainLoop` method of the main qt4 app.
95 96
96 97 This function should be used by users who want their wx scripts to work
97 98 both at the command line and in IPython. These users should put the
98 99 following logic at the bottom on their script, after they create a
99 100 :class:`App` instance (called ``app`` here)::
100 101
101 102 try:
102 103 from IPython.lib.inputhook import appstart_wx
103 104 appstart_wx(app)
104 105 except ImportError:
105 106 app.MainLoop()
106 107 """
107 108 import wx
108 109
109 110 assert isinstance(app, wx.App)
110 111 if app is not None:
111 112 if current_gui() == GUI_WX:
112 113 pass
113 114 else:
114 115 app.MainLoop()
115 116
116 117
117 118 def appstart_tk(app):
118 119 """Start the tk event loop in a way that plays with IPython.
119 120
120 121 When a tk app is run interactively in IPython, the event loop should
121 122 not be started. This function checks to see if IPython's tk integration
122 123 is activated and if so, it passes. If not, it will call the
123 124 :meth:`mainloop` method of the tk object passed to this method.
124 125
125 126 This function should be used by users who want their tk scripts to work
126 127 both at the command line and in IPython. These users should put the
127 128 following logic at the bottom on their script, after they create a
128 129 :class:`Tk` instance (called ``app`` here)::
129 130
130 131 try:
131 132 from IPython.lib.inputhook import appstart_tk
132 133 appstart_tk(app)
133 134 except ImportError:
134 135 app.mainloop()
135 136 """
136 137 if app is not None:
137 138 if current_gui() == GUI_TK:
138 139 pass
139 140 else:
140 141 app.mainloop()
141 142
142 143 def appstart_gtk():
143 144 """Start the gtk event loop in a way that plays with IPython.
144 145
145 146 When a gtk app is run interactively in IPython, the event loop should
146 147 not be started. This function checks to see if IPython's gtk integration
147 148 is activated and if so, it passes. If not, it will call
148 149 :func:`gtk.main`. Unlike the other appstart implementations, this does
149 150 not take an ``app`` argument.
150 151
151 152 This function should be used by users who want their gtk scripts to work
152 153 both at the command line and in IPython. These users should put the
153 154 following logic at the bottom on their script::
154 155
155 156 try:
156 157 from IPython.lib.inputhook import appstart_gtk
157 158 appstart_gtk()
158 159 except ImportError:
159 160 gtk.main()
160 161 """
161 162 import gtk
162 163 if current_gui() == GUI_GTK:
163 164 pass
164 165 else:
165 166 gtk.main()
166 167
167 168 #-----------------------------------------------------------------------------
168 169 # Main InputHookManager class
169 170 #-----------------------------------------------------------------------------
170 171
171 172
172 173 class InputHookManager(object):
173 174 """Manage PyOS_InputHook for different GUI toolkits.
174 175
175 176 This class installs various hooks under ``PyOSInputHook`` to handle
176 177 GUI event loop integration.
177 178 """
178 179
179 180 def __init__(self):
180 181 self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
181 182 self._apps = {}
182 183 self._spinner_dict = {
183 184 GUI_QT4 : self._spin_qt4,
184 185 GUI_WX : self._spin_wx,
185 186 GUI_GTK : self._spin_gtk,
186 187 GUI_TK : self._spin_tk}
187 188 self._reset()
188 189
189 190 def _reset(self):
190 191 self._callback_pyfunctype = None
191 192 self._callback = None
192 193 self._installed = False
193 194 self._current_gui = None
194 195
195 196 def _hijack_wx(self):
196 197 """Hijack the wx mainloop so a user calling it won't cause badness.
197 198
198 199 We are not currently using this as it breaks GUI code that calls a
199 200 mainloop at anytime but startup.
200 201 """
201 202 import wx
202 203 if hasattr(wx, '_core_'): core = getattr(wx, '_core_')
203 204 elif hasattr(wx, '_core'): core = getattr(wx, '_core')
204 205 else: raise AttributeError('Could not find wx core module')
205 206 orig_mainloop = core.PyApp_MainLoop
206 207 core.PyApp_MainLoop = _DummyMainloop
207 208 return orig_mainloop
208 209
209 210 def _hijack_qt4(self):
210 211 """Hijack the qt4 mainloop so a user calling it won't cause badness.
211 212
212 213 We are not currently using this as it breaks GUI code that calls a
213 214 mainloop at anytime but startup.
214 215 """
215 216 from PyQt4 import QtGui, QtCore
216 217 orig_mainloop = QtGui.qApp.exec_
217 218 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_QT4)
218 219 QtGui.qApp.exec_ = dumb_ml
219 220 QtGui.QApplication.exec_ = dumb_ml
220 221 QtCore.QCoreApplication.exec_ = dumb_ml
221 222 return orig_mainloop
222 223
223 224 def _hijack_gtk(self):
224 225 """Hijack the gtk mainloop so a user calling it won't cause badness.
225 226
226 227 We are not currently using this as it breaks GUI code that calls a
227 228 mainloop at anytime but startup.
228 229 """
229 230 import gtk
230 231 orig_mainloop = gtk.main
231 232 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_GTK)
232 233 gtk.mainloop = dumb_ml
233 234 gtk.main = dumb_ml
234 235 return orig_mainloop
235 236
236 237 def _hijack_tk(self):
237 238 """Hijack the tk mainloop so a user calling it won't cause badness.
238 239
239 240 We are not currently using this as it breaks GUI code that calls a
240 241 mainloop at anytime but startup.
241 242 """
242 243 import Tkinter
243 244 orig_mainloop = gtk.main
244 245 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_TK)
245 246 Tkinter.Misc.mainloop = dumb_ml
246 247 Tkinter.mainloop = dumb_ml
247 248
248 249 def _spin_qt4(self):
249 250 """Process all pending events in the qt4 event loop.
250 251
251 252 This is for internal IPython use only and user code should not call this.
252 253 Instead, they should issue the raw GUI calls themselves.
253 254 """
254 255 from PyQt4 import QtCore, QtGui
255 256
256 257 app = QtCore.QCoreApplication.instance()
257 258 if app is not None:
258 259 QtCore.QCoreApplication.processEvents(QtCore.QEventLoop.AllEvents)
259 260
260 261 def _spin_wx(self):
261 262 """Process all pending events in the wx event loop.
262 263
263 264 This is for internal IPython use only and user code should not call this.
264 265 Instead, they should issue the raw GUI calls themselves.
265 266 """
266 267 import wx
267 268 app = wx.GetApp()
268 269 if app is not None and wx.Thread_IsMain():
269 270 evtloop = wx.EventLoop()
270 271 ea = wx.EventLoopActivator(evtloop)
271 272 while evtloop.Pending():
272 273 evtloop.Dispatch()
273 274 app.ProcessIdle()
274 275 del ea
275 276
276 277 def _spin_gtk(self):
277 278 """Process all pending events in the gtk event loop.
278 279
279 280 This is for internal IPython use only and user code should not call this.
280 281 Instead, they should issue the raw GUI calls themselves.
281 282 """
282 283 import gtk
283 284 gtk.gdk.threads_enter()
284 285 while gtk.events_pending():
285 286 gtk.main_iteration(False)
286 287 gtk.gdk.flush()
287 288 gtk.gdk.threads_leave()
288 289
289 290 def _spin_tk(self):
290 291 """Process all pending events in the tk event loop.
291 292
292 293 This is for internal IPython use only and user code should not call this.
293 294 Instead, they should issue the raw GUI calls themselves.
294 295 """
295 296 app = self._apps.get(GUI_TK)
296 297 if app is not None:
297 298 app.update()
298 299
299 300 def spin(self):
300 301 """Process pending events in the current gui.
301 302
302 303 This method is just provided for IPython to use internally if needed
303 304 for things like testing. Third party projects should not call this
304 305 method, but instead should call the underlying GUI toolkit methods
305 306 that we are calling.
306 307 """
307 308 spinner = self._spinner_dict.get(self._current_gui, lambda: None)
308 309 spinner()
309 310
310 311 def get_pyos_inputhook(self):
311 312 """Return the current PyOS_InputHook as a ctypes.c_void_p."""
312 313 return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
313 314
314 315 def get_pyos_inputhook_as_func(self):
315 316 """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE."""
316 317 return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
317 318
318 319 def set_inputhook(self, callback):
319 320 """Set PyOS_InputHook to callback and return the previous one."""
320 321 self._callback = callback
321 322 self._callback_pyfunctype = self.PYFUNC(callback)
322 323 pyos_inputhook_ptr = self.get_pyos_inputhook()
323 324 original = self.get_pyos_inputhook_as_func()
324 325 pyos_inputhook_ptr.value = \
325 326 ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
326 327 self._installed = True
327 328 return original
328 329
329 def clear_inputhook(self):
330 """Set PyOS_InputHook to NULL and return the previous one."""
330 def clear_inputhook(self, app=None):
331 """Set PyOS_InputHook to NULL and return the previous one.
332
333 Parameters
334 ----------
335 app : optional, ignored
336 This parameter is allowed only so that clear_inputhook() can be
337 called with a similar interface as all the ``enable_*`` methods. But
338 the actual value of the parameter is ignored. This uniform interface
339 makes it easier to have user-level entry points in the main IPython
340 app like :meth:`enable_gui`."""
331 341 pyos_inputhook_ptr = self.get_pyos_inputhook()
332 342 original = self.get_pyos_inputhook_as_func()
333 343 pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
334 344 self._reset()
335 345 return original
336 346
337 347 def clear_app_refs(self, gui=None):
338 348 """Clear IPython's internal reference to an application instance.
339 349
340 350 Whenever we create an app for a user on qt4 or wx, we hold a
341 351 reference to the app. This is needed because in some cases bad things
342 352 can happen if a user doesn't hold a reference themselves. This
343 353 method is provided to clear the references we are holding.
344 354
345 355 Parameters
346 356 ----------
347 357 gui : None or str
348 358 If None, clear all app references. If ('wx', 'qt4') clear
349 359 the app for that toolkit. References are not held for gtk or tk
350 360 as those toolkits don't have the notion of an app.
351 361 """
352 362 if gui is None:
353 363 self._apps = {}
354 364 elif self._apps.has_key(gui):
355 365 del self._apps[gui]
356 366
357 367 def enable_wx(self, app=False):
358 368 """Enable event loop integration with wxPython.
359 369
360 370 Parameters
361 371 ----------
362 372 app : bool
363 373 Create a running application object or not.
364 374
365 375 Notes
366 376 -----
367 377 This methods sets the ``PyOS_InputHook`` for wxPython, which allows
368 378 the wxPython to integrate with terminal based applications like
369 379 IPython.
370 380
371 381 If ``app`` is True, we create an :class:`wx.App` as follows::
372 382
373 383 import wx
374 384 app = wx.App(redirect=False, clearSigInt=False)
375 385
376 386 Both options this constructor are important for things to work
377 387 properly in an interactive context.
378 388
379 389 But, we first check to see if an application has already been
380 390 created. If so, we simply return that instance.
381 391 """
382 392 from IPython.lib.inputhookwx import inputhook_wx
383 393 self.set_inputhook(inputhook_wx)
384 394 self._current_gui = GUI_WX
385 395 if app:
386 396 import wx
387 397 app = wx.GetApp()
388 398 if app is None:
389 399 app = wx.App(redirect=False, clearSigInt=False)
390 400 self._apps[GUI_WX] = app
391 401 return app
392 402
393 403 def disable_wx(self):
394 404 """Disable event loop integration with wxPython.
395 405
396 406 This merely sets PyOS_InputHook to NULL.
397 407 """
398 408 self.clear_inputhook()
399 409
400 410 def enable_qt4(self, app=False):
401 411 """Enable event loop integration with PyQt4.
402 412
403 413 Parameters
404 414 ----------
405 415 app : bool
406 416 Create a running application object or not.
407 417
408 418 Notes
409 419 -----
410 420 This methods sets the PyOS_InputHook for PyQt4, which allows
411 421 the PyQt4 to integrate with terminal based applications like
412 422 IPython.
413 423
414 424 If ``app`` is True, we create an :class:`QApplication` as follows::
415 425
416 426 from PyQt4 import QtCore
417 427 app = QtGui.QApplication(sys.argv)
418 428
419 429 But, we first check to see if an application has already been
420 430 created. If so, we simply return that instance.
421 431 """
422 432 from PyQt4 import QtCore
423 433 # PyQt4 has had this since 4.3.1. In version 4.2, PyOS_InputHook
424 434 # was set when QtCore was imported, but if it ever got removed,
425 435 # you couldn't reset it. For earlier versions we can
426 436 # probably implement a ctypes version.
427 437 try:
428 438 QtCore.pyqtRestoreInputHook()
429 439 except AttributeError:
430 440 pass
431 441 self._current_gui = GUI_QT4
432 442 if app:
433 443 from PyQt4 import QtGui
434 444 app = QtCore.QCoreApplication.instance()
435 445 if app is None:
436 446 app = QtGui.QApplication(sys.argv)
437 447 self._apps[GUI_QT4] = app
438 448 return app
439 449
440 450 def disable_qt4(self):
441 451 """Disable event loop integration with PyQt4.
442 452
443 453 This merely sets PyOS_InputHook to NULL.
444 454 """
445 455 self.clear_inputhook()
446 456
447 457 def enable_gtk(self, app=False):
448 458 """Enable event loop integration with PyGTK.
449 459
450 460 Parameters
451 461 ----------
452 462 app : bool
453 463 Create a running application object or not. Because gtk does't
454 464 have an app class, this does nothing.
455 465
456 466 Notes
457 467 -----
458 468 This methods sets the PyOS_InputHook for PyGTK, which allows
459 469 the PyGTK to integrate with terminal based applications like
460 470 IPython.
461 471 """
462 472 import gtk
463 473 try:
464 474 gtk.set_interactive(True)
465 475 self._current_gui = GUI_GTK
466 476 except AttributeError:
467 477 # For older versions of gtk, use our own ctypes version
468 478 from IPython.lib.inputhookgtk import inputhook_gtk
469 479 self.set_inputhook(inputhook_gtk)
470 480 self._current_gui = GUI_GTK
471 481
472 482 def disable_gtk(self):
473 483 """Disable event loop integration with PyGTK.
474 484
475 485 This merely sets PyOS_InputHook to NULL.
476 486 """
477 487 self.clear_inputhook()
478 488
479 489 def enable_tk(self, app=False):
480 490 """Enable event loop integration with Tk.
481 491
482 492 Parameters
483 493 ----------
484 494 app : bool
485 495 Create a running application object or not.
486 496
487 497 Notes
488 498 -----
489 499 Currently this is a no-op as creating a :class:`Tkinter.Tk` object
490 500 sets ``PyOS_InputHook``.
491 501 """
492 502 self._current_gui = GUI_TK
493 503 if app:
494 504 import Tkinter
495 505 app = Tkinter.Tk()
496 506 app.withdraw()
497 507 self._apps[GUI_TK] = app
498 508 return app
499 509
500 510 def disable_tk(self):
501 511 """Disable event loop integration with Tkinter.
502 512
503 513 This merely sets PyOS_InputHook to NULL.
504 514 """
505 515 self.clear_inputhook()
506 516
507 517 def current_gui(self):
508 518 """Return a string indicating the currently active GUI or None."""
509 519 return self._current_gui
510 520
511 521 inputhook_manager = InputHookManager()
512 522
513 523 enable_wx = inputhook_manager.enable_wx
514 524 disable_wx = inputhook_manager.disable_wx
515 525 enable_qt4 = inputhook_manager.enable_qt4
516 526 disable_qt4 = inputhook_manager.disable_qt4
517 527 enable_gtk = inputhook_manager.enable_gtk
518 528 disable_gtk = inputhook_manager.disable_gtk
519 529 enable_tk = inputhook_manager.enable_tk
520 530 disable_tk = inputhook_manager.disable_tk
521 531 clear_inputhook = inputhook_manager.clear_inputhook
522 532 set_inputhook = inputhook_manager.set_inputhook
523 533 current_gui = inputhook_manager.current_gui
524 534 clear_app_refs = inputhook_manager.clear_app_refs
525 535 spin = inputhook_manager.spin
536
537
538 # Convenience function to switch amongst them
539 def enable_gui(gui=None, app=True):
540 """Switch amongst GUI input hooks by name.
541
542 This is just a utility wrapper around the methods of the InputHookManager
543 object.
544
545 Parameters
546 ----------
547 gui : optional, string or None
548 If None, clears input hook, otherwise it must be one of the recognized
549 GUI names (see ``GUI_*`` constants in module).
550
551 app : optional, bool
552 If true, create an app object and return it.
553
554 Returns
555 -------
556 The output of the underlying gui switch routine, typically the actual
557 PyOS_InputHook wrapper object or the GUI toolkit app created, if there was
558 one.
559 """
560 guis = {None: clear_inputhook,
561 GUI_TK: enable_tk,
562 GUI_GTK: enable_gtk,
563 GUI_WX: enable_wx,
564 GUI_QT: enable_qt4, # qt3 not supported
565 GUI_QT4: enable_qt4 }
566 try:
567 gui_hook = guis[gui]
568 except KeyError:
569 e="Invalid GUI request %r, valid ones are:%s" % (gui, guis.keys())
570 raise ValueError(e)
571 return gui_hook(app)
General Comments 0
You need to be logged in to leave comments. Login now