##// END OF EJS Templates
Work on the user focused GUI event loop interface....
Brian Granger -
Show More
@@ -1,771 +1,790 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.1 or better.
6 6
7 7 This file contains the main make_IPython() starter function.
8 8 """
9 9
10 10 #*****************************************************************************
11 11 # Copyright (C) 2008-2009 The IPython Development Team
12 12 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
13 13 #
14 14 # Distributed under the terms of the BSD License. The full license is in
15 15 # the file COPYING, distributed as part of this software.
16 16 #*****************************************************************************
17 17
18 18 try:
19 19 credits._Printer__data = """
20 20 Python: %s
21 21
22 22 IPython: The IPython Development Team.
23 23 See http://ipython.scipy.org for more information.""" \
24 24 % credits._Printer__data
25 25
26 26 copyright._Printer__data += """
27 27
28 28 Copyright (c) 2008-2009 The IPython Development Team.
29 29 Copyright (c) 2001-2007 Fernando Perez, Janko Hauser, Nathan Gray.
30 30 All Rights Reserved."""
31 31 except NameError:
32 32 # Can happen if ipython was started with 'python -S', so that site.py is
33 33 # not loaded
34 34 pass
35 35
36 36 #****************************************************************************
37 37 # Required modules
38 38
39 39 # From the standard library
40 40 import __main__
41 41 import __builtin__
42 42 import os
43 43 import sys
44 44 from pprint import pprint
45 import warnings
45 46
46 47 # Our own
47 48 from IPython.utils import DPyGetOpt
48 49 from IPython.core import release
49 50 from IPython.utils.ipstruct import Struct
50 51 from IPython.core.outputtrap import OutputTrap
51 52 from IPython.config.configloader import ConfigLoader
52 53 from IPython.core.iplib import InteractiveShell
53 54 from IPython.core.usage import cmd_line_usage, interactive_usage
54 55 from IPython.utils.genutils import *
55 56
57
56 58 def force_import(modname,force_reload=False):
57 59 if modname in sys.modules and force_reload:
58 60 info("reloading: %s" % modname)
59 61 reload(sys.modules[modname])
60 62 else:
61 63 __import__(modname)
62 64
63 65
66 def threaded_shell_warning():
67 msg = """
68
69 The IPython threaded shells and their associated command line
70 arguments (pylab/wthread/gthread/qthread/q4thread) have been
71 deprecated. See the %gui magic for information on the new interface.
72 """
73 warnings.warn(msg, category=DeprecationWarning, stacklevel=1)
74
75
64 76 #-----------------------------------------------------------------------------
65 77 def make_IPython(argv=None,user_ns=None,user_global_ns=None,debug=1,
66 78 rc_override=None,shell_class=InteractiveShell,
67 79 embedded=False,**kw):
68 80 """This is a dump of IPython into a single function.
69 81
70 82 Later it will have to be broken up in a sensible manner.
71 83
72 84 Arguments:
73 85
74 86 - argv: a list similar to sys.argv[1:]. It should NOT contain the desired
75 87 script name, b/c DPyGetOpt strips the first argument only for the real
76 88 sys.argv.
77 89
78 90 - user_ns: a dict to be used as the user's namespace."""
79 91
80 92 #----------------------------------------------------------------------
81 93 # Defaults and initialization
82 94
83 95 # For developer debugging, deactivates crash handler and uses pdb.
84 96 DEVDEBUG = False
85 97
86 98 if argv is None:
87 99 argv = sys.argv
88 100
89 101 # __IP is the main global that lives throughout and represents the whole
90 102 # application. If the user redefines it, all bets are off as to what
91 103 # happens.
92 104
93 105 # __IP is the name of he global which the caller will have accessible as
94 106 # __IP.name. We set its name via the first parameter passed to
95 107 # InteractiveShell:
96 108
97 109 IP = shell_class('__IP',user_ns=user_ns,user_global_ns=user_global_ns,
98 110 embedded=embedded,**kw)
99 111
100 112 # Put 'help' in the user namespace
101 113 try:
102 114 from site import _Helper
103 115 IP.user_ns['help'] = _Helper()
104 116 except ImportError:
105 117 warn('help() not available - check site.py')
106 118
107 119 if DEVDEBUG:
108 120 # For developer debugging only (global flag)
109 121 from IPython.core import ultratb
110 122 sys.excepthook = ultratb.VerboseTB(call_pdb=1)
111 123
112 124 IP.BANNER_PARTS = ['Python %s\n'
113 125 'Type "copyright", "credits" or "license" '
114 126 'for more information.\n'
115 127 % (sys.version.split('\n')[0],),
116 128 "IPython %s -- An enhanced Interactive Python."
117 129 % (release.version,),
118 130 """\
119 131 ? -> Introduction and overview of IPython's features.
120 132 %quickref -> Quick reference.
121 133 help -> Python's own help system.
122 134 object? -> Details about 'object'. ?object also works, ?? prints more.
123 135 """ ]
124 136
125 137 IP.usage = interactive_usage
126 138
127 139 # Platform-dependent suffix.
128 140 if os.name == 'posix':
129 141 rc_suffix = ''
130 142 else:
131 143 rc_suffix = '.ini'
132 144
133 145 # default directory for configuration
134 146 ipythondir_def = get_ipython_dir()
135 147
136 148 sys.path.insert(0, '') # add . to sys.path. Fix from Prabhu Ramachandran
137 149
138 150 # we need the directory where IPython itself is installed
139 151 import IPython
140 152 IPython_dir = os.path.dirname(IPython.__file__)
141 153 del IPython
142 154
143 155 #-------------------------------------------------------------------------
144 156 # Command line handling
145 157
146 158 # Valid command line options (uses DPyGetOpt syntax, like Perl's
147 159 # GetOpt::Long)
148 160
149 161 # Any key not listed here gets deleted even if in the file (like session
150 162 # or profile). That's deliberate, to maintain the rc namespace clean.
151 163
152 164 # Each set of options appears twice: under _conv only the names are
153 165 # listed, indicating which type they must be converted to when reading the
154 166 # ipythonrc file. And under DPyGetOpt they are listed with the regular
155 167 # DPyGetOpt syntax (=s,=i,:f,etc).
156 168
157 169 # Make sure there's a space before each end of line (they get auto-joined!)
158 170 cmdline_opts = ('autocall=i autoindent! automagic! banner! cache_size|cs=i '
159 171 'c=s classic|cl color_info! colors=s confirm_exit! '
160 172 'debug! deep_reload! editor=s log|l messages! nosep '
161 173 'object_info_string_level=i pdb! '
162 174 'pprint! prompt_in1|pi1=s prompt_in2|pi2=s prompt_out|po=s '
163 175 'pydb! '
164 176 'pylab_import_all! '
165 177 'quick screen_length|sl=i prompts_pad_left=i '
166 178 'logfile|lf=s logplay|lp=s profile|p=s '
167 179 'readline! readline_merge_completions! '
168 180 'readline_omit__names! '
169 181 'rcfile=s separate_in|si=s separate_out|so=s '
170 182 'separate_out2|so2=s xmode=s wildcards_case_sensitive! '
171 183 'magic_docstrings system_verbose! '
172 184 'multi_line_specials! '
173 185 'term_title! wxversion=s '
174 186 'autoedit_syntax!')
175 187
176 188 # Options that can *only* appear at the cmd line (not in rcfiles).
177 189
178 190 cmdline_only = ('help interact|i ipythondir=s Version upgrade '
179 191 'gthread! qthread! q4thread! wthread! tkthread! pylab! tk! '
180 192 # 'twisted!' # disabled for now.
181 193 )
182 194
183 195 # Build the actual name list to be used by DPyGetOpt
184 196 opts_names = qw(cmdline_opts) + qw(cmdline_only)
185 197
186 198 # Set sensible command line defaults.
187 199 # This should have everything from cmdline_opts and cmdline_only
188 200 opts_def = Struct(autocall = 1,
189 201 autoedit_syntax = 0,
190 202 autoindent = 0,
191 203 automagic = 1,
192 204 autoexec = [],
193 205 banner = 1,
194 206 c = '',
195 207 cache_size = 1000,
196 208 classic = 0,
197 209 color_info = 0,
198 210 colors = 'NoColor',
199 211 confirm_exit = 1,
200 212 debug = 0,
201 213 deep_reload = 0,
202 214 editor = '0',
203 215 gthread = 0,
204 216 help = 0,
205 217 interact = 0,
206 218 ipythondir = ipythondir_def,
207 219 log = 0,
208 220 logfile = '',
209 221 logplay = '',
210 222 messages = 1,
211 223 multi_line_specials = 1,
212 224 nosep = 0,
213 225 object_info_string_level = 0,
214 226 pdb = 0,
215 227 pprint = 0,
216 228 profile = '',
217 229 prompt_in1 = 'In [\\#]: ',
218 230 prompt_in2 = ' .\\D.: ',
219 231 prompt_out = 'Out[\\#]: ',
220 232 prompts_pad_left = 1,
221 233 pydb = 0,
222 234 pylab = 0,
223 235 pylab_import_all = 1,
224 236 q4thread = 0,
225 237 qthread = 0,
226 238 quick = 0,
227 239 quiet = 0,
228 240 rcfile = 'ipythonrc' + rc_suffix,
229 241 readline = 1,
230 242 readline_merge_completions = 1,
231 243 readline_omit__names = 0,
232 244 screen_length = 0,
233 245 separate_in = '\n',
234 246 separate_out = '\n',
235 247 separate_out2 = '',
236 248 system_header = 'IPython system call: ',
237 249 system_verbose = 0,
238 250 term_title = 1,
239 251 tk = 0,
240 252 #twisted= 0, # disabled for now
241 253 upgrade = 0,
242 254 Version = 0,
243 255 wildcards_case_sensitive = 1,
244 256 wthread = 0,
245 257 wxversion = '0',
246 258 xmode = 'Context',
247 259 magic_docstrings = 0, # undocumented, for doc generation
248 260 )
249 261
250 262 # Things that will *only* appear in rcfiles (not at the command line).
251 263 # Make sure there's a space before each end of line (they get auto-joined!)
252 264 rcfile_opts = { qwflat: 'include import_mod import_all execfile ',
253 265 qw_lol: 'import_some ',
254 266 # for things with embedded whitespace:
255 267 list_strings:'execute alias readline_parse_and_bind ',
256 268 # Regular strings need no conversion:
257 269 None:'readline_remove_delims ',
258 270 }
259 271 # Default values for these
260 272 rc_def = Struct(include = [],
261 273 import_mod = [],
262 274 import_all = [],
263 275 import_some = [[]],
264 276 execute = [],
265 277 execfile = [],
266 278 alias = [],
267 279 readline_parse_and_bind = [],
268 280 readline_remove_delims = '',
269 281 )
270 282
271 283 # Build the type conversion dictionary from the above tables:
272 284 typeconv = rcfile_opts.copy()
273 285 typeconv.update(optstr2types(cmdline_opts))
274 286
275 287 # FIXME: the None key appears in both, put that back together by hand. Ugly!
276 288 typeconv[None] += ' ' + rcfile_opts[None]
277 289
278 290 # Remove quotes at ends of all strings (used to protect spaces)
279 291 typeconv[unquote_ends] = typeconv[None]
280 292 del typeconv[None]
281 293
282 294 # Build the list we'll use to make all config decisions with defaults:
283 295 opts_all = opts_def.copy()
284 296 opts_all.update(rc_def)
285 297
286 298 # Build conflict resolver for recursive loading of config files:
287 299 # - preserve means the outermost file maintains the value, it is not
288 300 # overwritten if an included file has the same key.
289 301 # - add_flip applies + to the two values, so it better make sense to add
290 302 # those types of keys. But it flips them first so that things loaded
291 303 # deeper in the inclusion chain have lower precedence.
292 304 conflict = {'preserve': ' '.join([ typeconv[int],
293 305 typeconv[unquote_ends] ]),
294 306 'add_flip': ' '.join([ typeconv[qwflat],
295 307 typeconv[qw_lol],
296 308 typeconv[list_strings] ])
297 309 }
298 310
299 311 # Now actually process the command line
300 312 getopt = DPyGetOpt.DPyGetOpt()
301 313 getopt.setIgnoreCase(0)
302 314
303 315 getopt.parseConfiguration(opts_names)
304 316
305 317 try:
306 318 getopt.processArguments(argv)
307 319 except DPyGetOpt.ArgumentError, exc:
308 320 print cmd_line_usage
309 321 warn('\nError in Arguments: "%s"' % exc)
310 322 sys.exit(1)
311 323
312 324 # convert the options dict to a struct for much lighter syntax later
313 325 opts = Struct(getopt.optionValues)
314 326 args = getopt.freeValues
315 327
316 328 # this is the struct (which has default values at this point) with which
317 329 # we make all decisions:
318 330 opts_all.update(opts)
319 331
320 332 # Options that force an immediate exit
321 333 if opts_all.help:
322 334 page(cmd_line_usage)
323 335 sys.exit()
324 336
325 337 if opts_all.Version:
326 338 print release.version
327 339 sys.exit()
328 340
329 341 if opts_all.magic_docstrings:
330 342 IP.magic_magic('-latex')
331 343 sys.exit()
332 344
345 # Display the deprecation warnings about threaded shells
346 if opts_all.pylab == 1: threaded_shell_warning()
347 if opts_all.wthread == 1: threaded_shell_warning()
348 if opts_all.qthread == 1: threaded_shell_warning()
349 if opts_all.q4thread == 1: threaded_shell_warning()
350 if opts_all.gthread == 1: threaded_shell_warning()
351
333 352 # add personal ipythondir to sys.path so that users can put things in
334 353 # there for customization
335 354 sys.path.append(os.path.abspath(opts_all.ipythondir))
336 355
337 356 # Create user config directory if it doesn't exist. This must be done
338 357 # *after* getting the cmd line options.
339 358 if not os.path.isdir(opts_all.ipythondir):
340 359 IP.user_setup(opts_all.ipythondir,rc_suffix,'install')
341 360
342 361 # upgrade user config files while preserving a copy of the originals
343 362 if opts_all.upgrade:
344 363 IP.user_setup(opts_all.ipythondir,rc_suffix,'upgrade')
345 364
346 365 # check mutually exclusive options in the *original* command line
347 366 mutex_opts(opts,[qw('log logfile'),qw('rcfile profile'),
348 367 qw('classic profile'),qw('classic rcfile')])
349 368
350 369 #---------------------------------------------------------------------------
351 370 # Log replay
352 371
353 372 # if -logplay, we need to 'become' the other session. That basically means
354 373 # replacing the current command line environment with that of the old
355 374 # session and moving on.
356 375
357 376 # this is needed so that later we know we're in session reload mode, as
358 377 # opts_all will get overwritten:
359 378 load_logplay = 0
360 379
361 380 if opts_all.logplay:
362 381 load_logplay = opts_all.logplay
363 382 opts_debug_save = opts_all.debug
364 383 try:
365 384 logplay = open(opts_all.logplay)
366 385 except IOError:
367 386 if opts_all.debug: IP.InteractiveTB()
368 387 warn('Could not open logplay file '+`opts_all.logplay`)
369 388 # restore state as if nothing had happened and move on, but make
370 389 # sure that later we don't try to actually load the session file
371 390 logplay = None
372 391 load_logplay = 0
373 392 del opts_all.logplay
374 393 else:
375 394 try:
376 395 logplay.readline()
377 396 logplay.readline();
378 397 # this reloads that session's command line
379 398 cmd = logplay.readline()[6:]
380 399 exec cmd
381 400 # restore the true debug flag given so that the process of
382 401 # session loading itself can be monitored.
383 402 opts.debug = opts_debug_save
384 403 # save the logplay flag so later we don't overwrite the log
385 404 opts.logplay = load_logplay
386 405 # now we must update our own structure with defaults
387 406 opts_all.update(opts)
388 407 # now load args
389 408 cmd = logplay.readline()[6:]
390 409 exec cmd
391 410 logplay.close()
392 411 except:
393 412 logplay.close()
394 413 if opts_all.debug: IP.InteractiveTB()
395 414 warn("Logplay file lacking full configuration information.\n"
396 415 "I'll try to read it, but some things may not work.")
397 416
398 417 #-------------------------------------------------------------------------
399 418 # set up output traps: catch all output from files, being run, modules
400 419 # loaded, etc. Then give it to the user in a clean form at the end.
401 420
402 421 msg_out = 'Output messages. '
403 422 msg_err = 'Error messages. '
404 423 msg_sep = '\n'
405 424 msg = Struct(config = OutputTrap('Configuration Loader',msg_out,
406 425 msg_err,msg_sep,debug,
407 426 quiet_out=1),
408 427 user_exec = OutputTrap('User File Execution',msg_out,
409 428 msg_err,msg_sep,debug),
410 429 logplay = OutputTrap('Log Loader',msg_out,
411 430 msg_err,msg_sep,debug),
412 431 summary = ''
413 432 )
414 433
415 434 #-------------------------------------------------------------------------
416 435 # Process user ipythonrc-type configuration files
417 436
418 437 # turn on output trapping and log to msg.config
419 438 # remember that with debug on, trapping is actually disabled
420 439 msg.config.trap_all()
421 440
422 441 # look for rcfile in current or default directory
423 442 try:
424 443 opts_all.rcfile = filefind(opts_all.rcfile,opts_all.ipythondir)
425 444 except IOError:
426 445 if opts_all.debug: IP.InteractiveTB()
427 446 warn('Configuration file %s not found. Ignoring request.'
428 447 % (opts_all.rcfile) )
429 448
430 449 # 'profiles' are a shorthand notation for config filenames
431 450 profile_handled_by_legacy = False
432 451 if opts_all.profile:
433 452
434 453 try:
435 454 opts_all.rcfile = filefind('ipythonrc-' + opts_all.profile
436 455 + rc_suffix,
437 456 opts_all.ipythondir)
438 457 profile_handled_by_legacy = True
439 458 except IOError:
440 459 if opts_all.debug: IP.InteractiveTB()
441 460 opts.profile = '' # remove profile from options if invalid
442 461 # We won't warn anymore, primary method is ipy_profile_PROFNAME
443 462 # which does trigger a warning.
444 463
445 464 # load the config file
446 465 rcfiledata = None
447 466 if opts_all.quick:
448 467 print 'Launching IPython in quick mode. No config file read.'
449 468 elif opts_all.rcfile:
450 469 try:
451 470 cfg_loader = ConfigLoader(conflict)
452 471 rcfiledata = cfg_loader.load(opts_all.rcfile,typeconv,
453 472 'include',opts_all.ipythondir,
454 473 purge = 1,
455 474 unique = conflict['preserve'])
456 475 except:
457 476 IP.InteractiveTB()
458 477 warn('Problems loading configuration file '+
459 478 `opts_all.rcfile`+
460 479 '\nStarting with default -bare bones- configuration.')
461 480 else:
462 481 warn('No valid configuration file found in either currrent directory\n'+
463 482 'or in the IPython config. directory: '+`opts_all.ipythondir`+
464 483 '\nProceeding with internal defaults.')
465 484
466 485 #------------------------------------------------------------------------
467 486 # Set exception handlers in mode requested by user.
468 487 otrap = OutputTrap(trap_out=1) # trap messages from magic_xmode
469 488 IP.magic_xmode(opts_all.xmode)
470 489 otrap.release_out()
471 490
472 491 #------------------------------------------------------------------------
473 492 # Execute user config
474 493
475 494 # Create a valid config structure with the right precedence order:
476 495 # defaults < rcfile < command line. This needs to be in the instance, so
477 496 # that method calls below that rely on it find it.
478 497 IP.rc = rc_def.copy()
479 498
480 499 # Work with a local alias inside this routine to avoid unnecessary
481 500 # attribute lookups.
482 501 IP_rc = IP.rc
483 502
484 503 IP_rc.update(opts_def)
485 504 if rcfiledata:
486 505 # now we can update
487 506 IP_rc.update(rcfiledata)
488 507 IP_rc.update(opts)
489 508 IP_rc.update(rc_override)
490 509
491 510 # Store the original cmd line for reference:
492 511 IP_rc.opts = opts
493 512 IP_rc.args = args
494 513
495 514 # create a *runtime* Struct like rc for holding parameters which may be
496 515 # created and/or modified by runtime user extensions.
497 516 IP.runtime_rc = Struct()
498 517
499 518 # from this point on, all config should be handled through IP_rc,
500 519 # opts* shouldn't be used anymore.
501 520
502 521
503 522 # update IP_rc with some special things that need manual
504 523 # tweaks. Basically options which affect other options. I guess this
505 524 # should just be written so that options are fully orthogonal and we
506 525 # wouldn't worry about this stuff!
507 526
508 527 if IP_rc.classic:
509 528 IP_rc.quick = 1
510 529 IP_rc.cache_size = 0
511 530 IP_rc.pprint = 0
512 531 IP_rc.prompt_in1 = '>>> '
513 532 IP_rc.prompt_in2 = '... '
514 533 IP_rc.prompt_out = ''
515 534 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
516 535 IP_rc.colors = 'NoColor'
517 536 IP_rc.xmode = 'Plain'
518 537
519 538 IP.pre_config_initialization()
520 539 # configure readline
521 540
522 541 # update exception handlers with rc file status
523 542 otrap.trap_out() # I don't want these messages ever.
524 543 IP.magic_xmode(IP_rc.xmode)
525 544 otrap.release_out()
526 545
527 546 # activate logging if requested and not reloading a log
528 547 if IP_rc.logplay:
529 548 IP.magic_logstart(IP_rc.logplay + ' append')
530 549 elif IP_rc.logfile:
531 550 IP.magic_logstart(IP_rc.logfile)
532 551 elif IP_rc.log:
533 552 IP.magic_logstart()
534 553
535 554 # find user editor so that it we don't have to look it up constantly
536 555 if IP_rc.editor.strip()=='0':
537 556 try:
538 557 ed = os.environ['EDITOR']
539 558 except KeyError:
540 559 if os.name == 'posix':
541 560 ed = 'vi' # the only one guaranteed to be there!
542 561 else:
543 562 ed = 'notepad' # same in Windows!
544 563 IP_rc.editor = ed
545 564
546 565 # Keep track of whether this is an embedded instance or not (useful for
547 566 # post-mortems).
548 567 IP_rc.embedded = IP.embedded
549 568
550 569 # Recursive reload
551 570 try:
552 571 from IPython.lib import deepreload
553 572 if IP_rc.deep_reload:
554 573 __builtin__.reload = deepreload.reload
555 574 else:
556 575 __builtin__.dreload = deepreload.reload
557 576 del deepreload
558 577 except ImportError:
559 578 pass
560 579
561 580 # Save the current state of our namespace so that the interactive shell
562 581 # can later know which variables have been created by us from config files
563 582 # and loading. This way, loading a file (in any way) is treated just like
564 583 # defining things on the command line, and %who works as expected.
565 584
566 585 # DON'T do anything that affects the namespace beyond this point!
567 586 IP.internal_ns.update(__main__.__dict__)
568 587
569 588 #IP.internal_ns.update(locals()) # so our stuff doesn't show up in %who
570 589
571 590 # Now run through the different sections of the users's config
572 591 if IP_rc.debug:
573 592 print 'Trying to execute the following configuration structure:'
574 593 print '(Things listed first are deeper in the inclusion tree and get'
575 594 print 'loaded first).\n'
576 595 pprint(IP_rc.__dict__)
577 596
578 597 for mod in IP_rc.import_mod:
579 598 try:
580 599 exec 'import '+mod in IP.user_ns
581 600 except :
582 601 IP.InteractiveTB()
583 602 import_fail_info(mod)
584 603
585 604 for mod_fn in IP_rc.import_some:
586 605 if not mod_fn == []:
587 606 mod,fn = mod_fn[0],','.join(mod_fn[1:])
588 607 try:
589 608 exec 'from '+mod+' import '+fn in IP.user_ns
590 609 except :
591 610 IP.InteractiveTB()
592 611 import_fail_info(mod,fn)
593 612
594 613 for mod in IP_rc.import_all:
595 614 try:
596 615 exec 'from '+mod+' import *' in IP.user_ns
597 616 except :
598 617 IP.InteractiveTB()
599 618 import_fail_info(mod)
600 619
601 620 for code in IP_rc.execute:
602 621 try:
603 622 exec code in IP.user_ns
604 623 except:
605 624 IP.InteractiveTB()
606 625 warn('Failure executing code: ' + `code`)
607 626
608 627 # Execute the files the user wants in ipythonrc
609 628 for file in IP_rc.execfile:
610 629 try:
611 630 file = filefind(file,sys.path+[IPython_dir])
612 631 except IOError:
613 632 warn(itpl('File $file not found. Skipping it.'))
614 633 else:
615 634 IP.safe_execfile(os.path.expanduser(file),IP.user_ns)
616 635
617 636 # finally, try importing ipy_*_conf for final configuration
618 637 try:
619 638 import ipy_system_conf
620 639 except ImportError:
621 640 if opts_all.debug: IP.InteractiveTB()
622 641 warn("Could not import 'ipy_system_conf'")
623 642 except:
624 643 IP.InteractiveTB()
625 644 import_fail_info('ipy_system_conf')
626 645
627 646 # only import prof module if ipythonrc-PROF was not found
628 647 if opts_all.profile and not profile_handled_by_legacy:
629 648 profmodname = 'ipy_profile_' + opts_all.profile
630 649 try:
631 650 force_import(profmodname)
632 651 except:
633 652 IP.InteractiveTB()
634 653 print "Error importing",profmodname,\
635 654 "- perhaps you should run %upgrade?"
636 655 import_fail_info(profmodname)
637 656 else:
638 657 opts.profile = opts_all.profile
639 658 else:
640 659 force_import('ipy_profile_none')
641 660 # XXX - this is wrong: ipy_user_conf should not be loaded unconditionally,
642 661 # since the user could have specified a config file path by hand.
643 662 try:
644 663 force_import('ipy_user_conf')
645 664 except:
646 665 conf = opts_all.ipythondir + "/ipy_user_conf.py"
647 666 IP.InteractiveTB()
648 667 if not os.path.isfile(conf):
649 668 warn(conf + ' does not exist, please run %upgrade!')
650 669
651 670 import_fail_info("ipy_user_conf")
652 671
653 672 # Define the history file for saving commands in between sessions
654 673 try:
655 674 histfname = 'history-%s' % opts.profile
656 675 except AttributeError:
657 676 histfname = 'history'
658 677 IP.histfile = os.path.join(opts_all.ipythondir,histfname)
659 678
660 679 # finally, push the argv to options again to ensure highest priority
661 680 IP_rc.update(opts)
662 681
663 682 # release stdout and stderr and save config log into a global summary
664 683 msg.config.release_all()
665 684 if IP_rc.messages:
666 685 msg.summary += msg.config.summary_all()
667 686
668 687 #------------------------------------------------------------------------
669 688 # Setup interactive session
670 689
671 690 # Now we should be fully configured. We can then execute files or load
672 691 # things only needed for interactive use. Then we'll open the shell.
673 692
674 693 # Take a snapshot of the user namespace before opening the shell. That way
675 694 # we'll be able to identify which things were interactively defined and
676 695 # which were defined through config files.
677 696 IP.user_config_ns.update(IP.user_ns)
678 697
679 698 # Force reading a file as if it were a session log. Slower but safer.
680 699 if load_logplay:
681 700 print 'Replaying log...'
682 701 try:
683 702 if IP_rc.debug:
684 703 logplay_quiet = 0
685 704 else:
686 705 logplay_quiet = 1
687 706
688 707 msg.logplay.trap_all()
689 708 IP.safe_execfile(load_logplay,IP.user_ns,
690 709 islog = 1, quiet = logplay_quiet)
691 710 msg.logplay.release_all()
692 711 if IP_rc.messages:
693 712 msg.summary += msg.logplay.summary_all()
694 713 except:
695 714 warn('Problems replaying logfile %s.' % load_logplay)
696 715 IP.InteractiveTB()
697 716
698 717 # Load remaining files in command line
699 718 msg.user_exec.trap_all()
700 719
701 720 # Do NOT execute files named in the command line as scripts to be loaded
702 721 # by embedded instances. Doing so has the potential for an infinite
703 722 # recursion if there are exceptions thrown in the process.
704 723
705 724 # XXX FIXME: the execution of user files should be moved out to after
706 725 # ipython is fully initialized, just as if they were run via %run at the
707 726 # ipython prompt. This would also give them the benefit of ipython's
708 727 # nice tracebacks.
709 728
710 729 if (not embedded and IP_rc.args and
711 730 not IP_rc.args[0].lower().endswith('.ipy')):
712 731 name_save = IP.user_ns['__name__']
713 732 IP.user_ns['__name__'] = '__main__'
714 733 # Set our own excepthook in case the user code tries to call it
715 734 # directly. This prevents triggering the IPython crash handler.
716 735 old_excepthook,sys.excepthook = sys.excepthook, IP.excepthook
717 736
718 737 save_argv = sys.argv[1:] # save it for later restoring
719 738
720 739 sys.argv = args
721 740
722 741 try:
723 742 IP.safe_execfile(args[0], IP.user_ns)
724 743 finally:
725 744 # Reset our crash handler in place
726 745 sys.excepthook = old_excepthook
727 746 sys.argv[:] = save_argv
728 747 IP.user_ns['__name__'] = name_save
729 748
730 749 msg.user_exec.release_all()
731 750
732 751 if IP_rc.messages:
733 752 msg.summary += msg.user_exec.summary_all()
734 753
735 754 # since we can't specify a null string on the cmd line, 0 is the equivalent:
736 755 if IP_rc.nosep:
737 756 IP_rc.separate_in = IP_rc.separate_out = IP_rc.separate_out2 = '0'
738 757 if IP_rc.separate_in == '0': IP_rc.separate_in = ''
739 758 if IP_rc.separate_out == '0': IP_rc.separate_out = ''
740 759 if IP_rc.separate_out2 == '0': IP_rc.separate_out2 = ''
741 760 IP_rc.separate_in = IP_rc.separate_in.replace('\\n','\n')
742 761 IP_rc.separate_out = IP_rc.separate_out.replace('\\n','\n')
743 762 IP_rc.separate_out2 = IP_rc.separate_out2.replace('\\n','\n')
744 763
745 764 # Determine how many lines at the bottom of the screen are needed for
746 765 # showing prompts, so we can know wheter long strings are to be printed or
747 766 # paged:
748 767 num_lines_bot = IP_rc.separate_in.count('\n')+1
749 768 IP_rc.screen_length = IP_rc.screen_length - num_lines_bot
750 769
751 770 # configure startup banner
752 771 if IP_rc.c: # regular python doesn't print the banner with -c
753 772 IP_rc.banner = 0
754 773 if IP_rc.banner:
755 774 BANN_P = IP.BANNER_PARTS
756 775 else:
757 776 BANN_P = []
758 777
759 778 if IP_rc.profile: BANN_P.append('IPython profile: %s\n' % IP_rc.profile)
760 779
761 780 # add message log (possibly empty)
762 781 if msg.summary: BANN_P.append(msg.summary)
763 782 # Final banner is a string
764 783 IP.BANNER = '\n'.join(BANN_P)
765 784
766 785 # Finalize the IPython instance. This assumes the rc structure is fully
767 786 # in place.
768 787 IP.post_config_initialization()
769 788
770 789 return IP
771 790 #************************ end of file <ipmaker.py> **************************
@@ -1,3527 +1,3570 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 re
25 25 import tempfile
26 26 import time
27 27 import cPickle as pickle
28 28 import textwrap
29 29 from cStringIO import StringIO
30 30 from getopt import getopt,GetoptError
31 31 from pprint import pprint, pformat
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 # Homebrewed
45 45 import IPython
46 46 from IPython.utils import wildcard
47 47 from IPython.core import debugger, oinspect
48 48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 50 from IPython.utils.PyColorize import Parser
51 51 from IPython.utils.ipstruct import Struct
52 52 from IPython.core.macro import Macro
53 53 from IPython.utils.genutils import *
54 54 from IPython.utils import platutils
55 55 import IPython.utils.generics
56 56 from IPython.core import ipapi
57 57 from IPython.core.ipapi import UsageError
58 58 from IPython.testing import decorators as testdec
59 59
60 60 #***************************************************************************
61 61 # Utility functions
62 62 def on_off(tag):
63 63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 64 return ['OFF','ON'][tag]
65 65
66 66 class Bunch: pass
67 67
68 68 def compress_dhist(dh):
69 69 head, tail = dh[:-10], dh[-10:]
70 70
71 71 newhead = []
72 72 done = set()
73 73 for h in head:
74 74 if h in done:
75 75 continue
76 76 newhead.append(h)
77 77 done.add(h)
78 78
79 79 return newhead + tail
80 80
81 81
82 82 #***************************************************************************
83 83 # Main class implementing Magic functionality
84 84 class Magic:
85 85 """Magic functions for InteractiveShell.
86 86
87 87 Shell functions which can be reached as %function_name. All magic
88 88 functions should accept a string, which they can parse for their own
89 89 needs. This can make some functions easier to type, eg `%cd ../`
90 90 vs. `%cd("../")`
91 91
92 92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 93 at the command line, but it is is needed in the definition. """
94 94
95 95 # class globals
96 96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 97 'Automagic is ON, % prefix NOT needed for magic functions.']
98 98
99 99 #......................................................................
100 100 # some utility functions
101 101
102 102 def __init__(self,shell):
103 103
104 104 self.options_table = {}
105 105 if profile is None:
106 106 self.magic_prun = self.profile_missing_notice
107 107 self.shell = shell
108 108
109 109 # namespace for holding state we may need
110 110 self._magic_state = Bunch()
111 111
112 112 def profile_missing_notice(self, *args, **kwargs):
113 113 error("""\
114 114 The profile module could not be found. It has been removed from the standard
115 115 python packages because of its non-free license. To use profiling, install the
116 116 python-profiler package from non-free.""")
117 117
118 118 def default_option(self,fn,optstr):
119 119 """Make an entry in the options_table for fn, with value optstr"""
120 120
121 121 if fn not in self.lsmagic():
122 122 error("%s is not a magic function" % fn)
123 123 self.options_table[fn] = optstr
124 124
125 125 def lsmagic(self):
126 126 """Return a list of currently available magic functions.
127 127
128 128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 129 ['magic_ls','magic_cd',...]"""
130 130
131 131 # FIXME. This needs a cleanup, in the way the magics list is built.
132 132
133 133 # magics in class definition
134 134 class_magic = lambda fn: fn.startswith('magic_') and \
135 135 callable(Magic.__dict__[fn])
136 136 # in instance namespace (run-time user additions)
137 137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 138 callable(self.__dict__[fn])
139 139 # and bound magics by user (so they can access self):
140 140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 141 callable(self.__class__.__dict__[fn])
142 142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 143 filter(inst_magic,self.__dict__.keys()) + \
144 144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 145 out = []
146 146 for fn in set(magics):
147 147 out.append(fn.replace('magic_','',1))
148 148 out.sort()
149 149 return out
150 150
151 151 def extract_input_slices(self,slices,raw=False):
152 152 """Return as a string a set of input history slices.
153 153
154 154 Inputs:
155 155
156 156 - slices: the set of slices is given as a list of strings (like
157 157 ['1','4:8','9'], since this function is for use by magic functions
158 158 which get their arguments as strings.
159 159
160 160 Optional inputs:
161 161
162 162 - raw(False): by default, the processed input is used. If this is
163 163 true, the raw input history is used instead.
164 164
165 165 Note that slices can be called with two notations:
166 166
167 167 N:M -> standard python form, means including items N...(M-1).
168 168
169 169 N-M -> include items N..M (closed endpoint)."""
170 170
171 171 if raw:
172 172 hist = self.shell.input_hist_raw
173 173 else:
174 174 hist = self.shell.input_hist
175 175
176 176 cmds = []
177 177 for chunk in slices:
178 178 if ':' in chunk:
179 179 ini,fin = map(int,chunk.split(':'))
180 180 elif '-' in chunk:
181 181 ini,fin = map(int,chunk.split('-'))
182 182 fin += 1
183 183 else:
184 184 ini = int(chunk)
185 185 fin = ini+1
186 186 cmds.append(hist[ini:fin])
187 187 return cmds
188 188
189 189 def _ofind(self, oname, namespaces=None):
190 190 """Find an object in the available namespaces.
191 191
192 192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193 193
194 194 Has special code to detect magic functions.
195 195 """
196 196
197 197 oname = oname.strip()
198 198
199 199 alias_ns = None
200 200 if namespaces is None:
201 201 # Namespaces to search in:
202 202 # Put them in a list. The order is important so that we
203 203 # find things in the same order that Python finds them.
204 204 namespaces = [ ('Interactive', self.shell.user_ns),
205 205 ('IPython internal', self.shell.internal_ns),
206 206 ('Python builtin', __builtin__.__dict__),
207 207 ('Alias', self.shell.alias_table),
208 208 ]
209 209 alias_ns = self.shell.alias_table
210 210
211 211 # initialize results to 'null'
212 212 found = 0; obj = None; ospace = None; ds = None;
213 213 ismagic = 0; isalias = 0; parent = None
214 214
215 215 # Look for the given name by splitting it in parts. If the head is
216 216 # found, then we look for all the remaining parts as members, and only
217 217 # declare success if we can find them all.
218 218 oname_parts = oname.split('.')
219 219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 220 for nsname,ns in namespaces:
221 221 try:
222 222 obj = ns[oname_head]
223 223 except KeyError:
224 224 continue
225 225 else:
226 226 #print 'oname_rest:', oname_rest # dbg
227 227 for part in oname_rest:
228 228 try:
229 229 parent = obj
230 230 obj = getattr(obj,part)
231 231 except:
232 232 # Blanket except b/c some badly implemented objects
233 233 # allow __getattr__ to raise exceptions other than
234 234 # AttributeError, which then crashes IPython.
235 235 break
236 236 else:
237 237 # If we finish the for loop (no break), we got all members
238 238 found = 1
239 239 ospace = nsname
240 240 if ns == alias_ns:
241 241 isalias = 1
242 242 break # namespace loop
243 243
244 244 # Try to see if it's magic
245 245 if not found:
246 246 if oname.startswith(self.shell.ESC_MAGIC):
247 247 oname = oname[1:]
248 248 obj = getattr(self,'magic_'+oname,None)
249 249 if obj is not None:
250 250 found = 1
251 251 ospace = 'IPython internal'
252 252 ismagic = 1
253 253
254 254 # Last try: special-case some literals like '', [], {}, etc:
255 255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 256 obj = eval(oname_head)
257 257 found = 1
258 258 ospace = 'Interactive'
259 259
260 260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262 262
263 263 def arg_err(self,func):
264 264 """Print docstring if incorrect arguments were passed"""
265 265 print 'Error in arguments:'
266 266 print OInspect.getdoc(func)
267 267
268 268 def format_latex(self,strng):
269 269 """Format a string for latex inclusion."""
270 270
271 271 # Characters that need to be escaped for latex:
272 272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 273 # Magic command names as headers:
274 274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 275 re.MULTILINE)
276 276 # Magic commands
277 277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 278 re.MULTILINE)
279 279 # Paragraph continue
280 280 par_re = re.compile(r'\\$',re.MULTILINE)
281 281
282 282 # The "\n" symbol
283 283 newline_re = re.compile(r'\\n')
284 284
285 285 # Now build the string for output:
286 286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 288 strng)
289 289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 290 strng = par_re.sub(r'\\\\',strng)
291 291 strng = escape_re.sub(r'\\\1',strng)
292 292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 293 return strng
294 294
295 295 def format_screen(self,strng):
296 296 """Format a string for screen printing.
297 297
298 298 This removes some latex-type format codes."""
299 299 # Paragraph continue
300 300 par_re = re.compile(r'\\$',re.MULTILINE)
301 301 strng = par_re.sub('',strng)
302 302 return strng
303 303
304 304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 305 """Parse options passed to an argument string.
306 306
307 307 The interface is similar to that of getopt(), but it returns back a
308 308 Struct with the options as keys and the stripped argument string still
309 309 as a string.
310 310
311 311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 312 This allows us to easily expand variables, glob files, quote
313 313 arguments, etc.
314 314
315 315 Options:
316 316 -mode: default 'string'. If given as 'list', the argument string is
317 317 returned as a list (split on whitespace) instead of a string.
318 318
319 319 -list_all: put all option values in lists. Normally only options
320 320 appearing more than once are put in a list.
321 321
322 322 -posix (True): whether to split the input line in POSIX mode or not,
323 323 as per the conventions outlined in the shlex module from the
324 324 standard library."""
325 325
326 326 # inject default options at the beginning of the input line
327 327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329 329
330 330 mode = kw.get('mode','string')
331 331 if mode not in ['string','list']:
332 332 raise ValueError,'incorrect mode given: %s' % mode
333 333 # Get options
334 334 list_all = kw.get('list_all',0)
335 335 posix = kw.get('posix',True)
336 336
337 337 # Check if we have more than one argument to warrant extra processing:
338 338 odict = {} # Dictionary with options
339 339 args = arg_str.split()
340 340 if len(args) >= 1:
341 341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 342 # need to look for options
343 343 argv = arg_split(arg_str,posix)
344 344 # Do regular option processing
345 345 try:
346 346 opts,args = getopt(argv,opt_str,*long_opts)
347 347 except GetoptError,e:
348 348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 349 " ".join(long_opts)))
350 350 for o,a in opts:
351 351 if o.startswith('--'):
352 352 o = o[2:]
353 353 else:
354 354 o = o[1:]
355 355 try:
356 356 odict[o].append(a)
357 357 except AttributeError:
358 358 odict[o] = [odict[o],a]
359 359 except KeyError:
360 360 if list_all:
361 361 odict[o] = [a]
362 362 else:
363 363 odict[o] = a
364 364
365 365 # Prepare opts,args for return
366 366 opts = Struct(odict)
367 367 if mode == 'string':
368 368 args = ' '.join(args)
369 369
370 370 return opts,args
371 371
372 372 #......................................................................
373 373 # And now the actual magic functions
374 374
375 375 # Functions for IPython shell work (vars,funcs, config, etc)
376 376 def magic_lsmagic(self, parameter_s = ''):
377 377 """List currently available magic functions."""
378 378 mesc = self.shell.ESC_MAGIC
379 379 print 'Available magic functions:\n'+mesc+\
380 380 (' '+mesc).join(self.lsmagic())
381 381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
382 382 return None
383 383
384 384 def magic_magic(self, parameter_s = ''):
385 385 """Print information about the magic function system.
386 386
387 387 Supported formats: -latex, -brief, -rest
388 388 """
389 389
390 390 mode = ''
391 391 try:
392 392 if parameter_s.split()[0] == '-latex':
393 393 mode = 'latex'
394 394 if parameter_s.split()[0] == '-brief':
395 395 mode = 'brief'
396 396 if parameter_s.split()[0] == '-rest':
397 397 mode = 'rest'
398 398 rest_docs = []
399 399 except:
400 400 pass
401 401
402 402 magic_docs = []
403 403 for fname in self.lsmagic():
404 404 mname = 'magic_' + fname
405 405 for space in (Magic,self,self.__class__):
406 406 try:
407 407 fn = space.__dict__[mname]
408 408 except KeyError:
409 409 pass
410 410 else:
411 411 break
412 412 if mode == 'brief':
413 413 # only first line
414 414 if fn.__doc__:
415 415 fndoc = fn.__doc__.split('\n',1)[0]
416 416 else:
417 417 fndoc = 'No documentation'
418 418 else:
419 419 if fn.__doc__:
420 420 fndoc = fn.__doc__.rstrip()
421 421 else:
422 422 fndoc = 'No documentation'
423 423
424 424
425 425 if mode == 'rest':
426 426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 427 fname,fndoc))
428 428
429 429 else:
430 430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 431 fname,fndoc))
432 432
433 433 magic_docs = ''.join(magic_docs)
434 434
435 435 if mode == 'rest':
436 436 return "".join(rest_docs)
437 437
438 438 if mode == 'latex':
439 439 print self.format_latex(magic_docs)
440 440 return
441 441 else:
442 442 magic_docs = self.format_screen(magic_docs)
443 443 if mode == 'brief':
444 444 return magic_docs
445 445
446 446 outmsg = """
447 447 IPython's 'magic' functions
448 448 ===========================
449 449
450 450 The magic function system provides a series of functions which allow you to
451 451 control the behavior of IPython itself, plus a lot of system-type
452 452 features. All these functions are prefixed with a % character, but parameters
453 453 are given without parentheses or quotes.
454 454
455 455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 456 %automagic function), you don't need to type in the % explicitly. By default,
457 457 IPython ships with automagic on, so you should only rarely need the % escape.
458 458
459 459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 460 to 'mydir', if it exists.
461 461
462 462 You can define your own magic functions to extend the system. See the supplied
463 463 ipythonrc and example-magic.py files for details (in your ipython
464 464 configuration directory, typically $HOME/.ipython/).
465 465
466 466 You can also define your own aliased names for magic functions. In your
467 467 ipythonrc file, placing a line like:
468 468
469 469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470 470
471 471 will define %pf as a new name for %profile.
472 472
473 473 You can also call magics in code using the ipmagic() function, which IPython
474 474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475 475
476 476 For a list of the available magic functions, use %lsmagic. For a description
477 477 of any of them, type %magic_name?, e.g. '%cd?'.
478 478
479 479 Currently the magic system has the following functions:\n"""
480 480
481 481 mesc = self.shell.ESC_MAGIC
482 482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 483 "\n\n%s%s\n\n%s" % (outmsg,
484 484 magic_docs,mesc,mesc,
485 485 (' '+mesc).join(self.lsmagic()),
486 486 Magic.auto_status[self.shell.rc.automagic] ) )
487 487
488 488 page(outmsg,screen_lines=self.shell.rc.screen_length)
489 489
490 490
491 491 def magic_autoindent(self, parameter_s = ''):
492 492 """Toggle autoindent on/off (if available)."""
493 493
494 494 self.shell.set_autoindent()
495 495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496 496
497 497
498 498 def magic_automagic(self, parameter_s = ''):
499 499 """Make magic functions callable without having to type the initial %.
500 500
501 501 Without argumentsl toggles on/off (when off, you must call it as
502 502 %automagic, of course). With arguments it sets the value, and you can
503 503 use any of (case insensitive):
504 504
505 505 - on,1,True: to activate
506 506
507 507 - off,0,False: to deactivate.
508 508
509 509 Note that magic functions have lowest priority, so if there's a
510 510 variable whose name collides with that of a magic fn, automagic won't
511 511 work for that function (you get the variable instead). However, if you
512 512 delete the variable (del var), the previously shadowed magic function
513 513 becomes visible to automagic again."""
514 514
515 515 rc = self.shell.rc
516 516 arg = parameter_s.lower()
517 517 if parameter_s in ('on','1','true'):
518 518 rc.automagic = True
519 519 elif parameter_s in ('off','0','false'):
520 520 rc.automagic = False
521 521 else:
522 522 rc.automagic = not rc.automagic
523 523 print '\n' + Magic.auto_status[rc.automagic]
524 524
525 525 @testdec.skip_doctest
526 526 def magic_autocall(self, parameter_s = ''):
527 527 """Make functions callable without having to type parentheses.
528 528
529 529 Usage:
530 530
531 531 %autocall [mode]
532 532
533 533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 534 value is toggled on and off (remembering the previous state).
535 535
536 536 In more detail, these values mean:
537 537
538 538 0 -> fully disabled
539 539
540 540 1 -> active, but do not apply if there are no arguments on the line.
541 541
542 542 In this mode, you get:
543 543
544 544 In [1]: callable
545 545 Out[1]: <built-in function callable>
546 546
547 547 In [2]: callable 'hello'
548 548 ------> callable('hello')
549 549 Out[2]: False
550 550
551 551 2 -> Active always. Even if no arguments are present, the callable
552 552 object is called:
553 553
554 554 In [2]: float
555 555 ------> float()
556 556 Out[2]: 0.0
557 557
558 558 Note that even with autocall off, you can still use '/' at the start of
559 559 a line to treat the first argument on the command line as a function
560 560 and add parentheses to it:
561 561
562 562 In [8]: /str 43
563 563 ------> str(43)
564 564 Out[8]: '43'
565 565
566 566 # all-random (note for auto-testing)
567 567 """
568 568
569 569 rc = self.shell.rc
570 570
571 571 if parameter_s:
572 572 arg = int(parameter_s)
573 573 else:
574 574 arg = 'toggle'
575 575
576 576 if not arg in (0,1,2,'toggle'):
577 577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
578 578 return
579 579
580 580 if arg in (0,1,2):
581 581 rc.autocall = arg
582 582 else: # toggle
583 583 if rc.autocall:
584 584 self._magic_state.autocall_save = rc.autocall
585 585 rc.autocall = 0
586 586 else:
587 587 try:
588 588 rc.autocall = self._magic_state.autocall_save
589 589 except AttributeError:
590 590 rc.autocall = self._magic_state.autocall_save = 1
591 591
592 592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
593 593
594 594 def magic_system_verbose(self, parameter_s = ''):
595 595 """Set verbose printing of system calls.
596 596
597 597 If called without an argument, act as a toggle"""
598 598
599 599 if parameter_s:
600 600 val = bool(eval(parameter_s))
601 601 else:
602 602 val = None
603 603
604 604 self.shell.rc_set_toggle('system_verbose',val)
605 605 print "System verbose printing is:",\
606 606 ['OFF','ON'][self.shell.rc.system_verbose]
607 607
608 608
609 609 def magic_page(self, parameter_s=''):
610 610 """Pretty print the object and display it through a pager.
611 611
612 612 %page [options] OBJECT
613 613
614 614 If no object is given, use _ (last output).
615 615
616 616 Options:
617 617
618 618 -r: page str(object), don't pretty-print it."""
619 619
620 620 # After a function contributed by Olivier Aubert, slightly modified.
621 621
622 622 # Process options/args
623 623 opts,args = self.parse_options(parameter_s,'r')
624 624 raw = 'r' in opts
625 625
626 626 oname = args and args or '_'
627 627 info = self._ofind(oname)
628 628 if info['found']:
629 629 txt = (raw and str or pformat)( info['obj'] )
630 630 page(txt)
631 631 else:
632 632 print 'Object `%s` not found' % oname
633 633
634 634 def magic_profile(self, parameter_s=''):
635 635 """Print your currently active IPyhton profile."""
636 636 if self.shell.rc.profile:
637 637 printpl('Current IPython profile: $self.shell.rc.profile.')
638 638 else:
639 639 print 'No profile active.'
640 640
641 641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 642 """Provide detailed information about an object.
643 643
644 644 '%pinfo object' is just a synonym for object? or ?object."""
645 645
646 646 #print 'pinfo par: <%s>' % parameter_s # dbg
647 647
648 648
649 649 # detail_level: 0 -> obj? , 1 -> obj??
650 650 detail_level = 0
651 651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 652 # happen if the user types 'pinfo foo?' at the cmd line.
653 653 pinfo,qmark1,oname,qmark2 = \
654 654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 655 if pinfo or qmark1 or qmark2:
656 656 detail_level = 1
657 657 if "*" in oname:
658 658 self.magic_psearch(oname)
659 659 else:
660 660 self._inspect('pinfo', oname, detail_level=detail_level,
661 661 namespaces=namespaces)
662 662
663 663 def magic_pdef(self, parameter_s='', namespaces=None):
664 664 """Print the definition header for any callable object.
665 665
666 666 If the object is a class, print the constructor information."""
667 667 self._inspect('pdef',parameter_s, namespaces)
668 668
669 669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 670 """Print the docstring for an object.
671 671
672 672 If the given object is a class, it will print both the class and the
673 673 constructor docstrings."""
674 674 self._inspect('pdoc',parameter_s, namespaces)
675 675
676 676 def magic_psource(self, parameter_s='', namespaces=None):
677 677 """Print (or run through pager) the source code for an object."""
678 678 self._inspect('psource',parameter_s, namespaces)
679 679
680 680 def magic_pfile(self, parameter_s=''):
681 681 """Print (or run through pager) the file where an object is defined.
682 682
683 683 The file opens at the line where the object definition begins. IPython
684 684 will honor the environment variable PAGER if set, and otherwise will
685 685 do its best to print the file in a convenient form.
686 686
687 687 If the given argument is not an object currently defined, IPython will
688 688 try to interpret it as a filename (automatically adding a .py extension
689 689 if needed). You can thus use %pfile as a syntax highlighting code
690 690 viewer."""
691 691
692 692 # first interpret argument as an object name
693 693 out = self._inspect('pfile',parameter_s)
694 694 # if not, try the input as a filename
695 695 if out == 'not found':
696 696 try:
697 697 filename = get_py_filename(parameter_s)
698 698 except IOError,msg:
699 699 print msg
700 700 return
701 701 page(self.shell.inspector.format(file(filename).read()))
702 702
703 703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 704 """Generic interface to the inspector system.
705 705
706 706 This function is meant to be called by pdef, pdoc & friends."""
707 707
708 708 #oname = oname.strip()
709 709 #print '1- oname: <%r>' % oname # dbg
710 710 try:
711 711 oname = oname.strip().encode('ascii')
712 712 #print '2- oname: <%r>' % oname # dbg
713 713 except UnicodeEncodeError:
714 714 print 'Python identifiers can only contain ascii characters.'
715 715 return 'not found'
716 716
717 717 info = Struct(self._ofind(oname, namespaces))
718 718
719 719 if info.found:
720 720 try:
721 721 IPython.utils.generics.inspect_object(info.obj)
722 722 return
723 723 except ipapi.TryNext:
724 724 pass
725 725 # Get the docstring of the class property if it exists.
726 726 path = oname.split('.')
727 727 root = '.'.join(path[:-1])
728 728 if info.parent is not None:
729 729 try:
730 730 target = getattr(info.parent, '__class__')
731 731 # The object belongs to a class instance.
732 732 try:
733 733 target = getattr(target, path[-1])
734 734 # The class defines the object.
735 735 if isinstance(target, property):
736 736 oname = root + '.__class__.' + path[-1]
737 737 info = Struct(self._ofind(oname))
738 738 except AttributeError: pass
739 739 except AttributeError: pass
740 740
741 741 pmethod = getattr(self.shell.inspector,meth)
742 742 formatter = info.ismagic and self.format_screen or None
743 743 if meth == 'pdoc':
744 744 pmethod(info.obj,oname,formatter)
745 745 elif meth == 'pinfo':
746 746 pmethod(info.obj,oname,formatter,info,**kw)
747 747 else:
748 748 pmethod(info.obj,oname)
749 749 else:
750 750 print 'Object `%s` not found.' % oname
751 751 return 'not found' # so callers can take other action
752 752
753 753 def magic_psearch(self, parameter_s=''):
754 754 """Search for object in namespaces by wildcard.
755 755
756 756 %psearch [options] PATTERN [OBJECT TYPE]
757 757
758 758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 760 rest of the command line must be unchanged (options come first), so
761 761 for example the following forms are equivalent
762 762
763 763 %psearch -i a* function
764 764 -i a* function?
765 765 ?-i a* function
766 766
767 767 Arguments:
768 768
769 769 PATTERN
770 770
771 771 where PATTERN is a string containing * as a wildcard similar to its
772 772 use in a shell. The pattern is matched in all namespaces on the
773 773 search path. By default objects starting with a single _ are not
774 774 matched, many IPython generated objects have a single
775 775 underscore. The default is case insensitive matching. Matching is
776 776 also done on the attributes of objects and not only on the objects
777 777 in a module.
778 778
779 779 [OBJECT TYPE]
780 780
781 781 Is the name of a python type from the types module. The name is
782 782 given in lowercase without the ending type, ex. StringType is
783 783 written string. By adding a type here only objects matching the
784 784 given type are matched. Using all here makes the pattern match all
785 785 types (this is the default).
786 786
787 787 Options:
788 788
789 789 -a: makes the pattern match even objects whose names start with a
790 790 single underscore. These names are normally ommitted from the
791 791 search.
792 792
793 793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 794 these options is given, the default is read from your ipythonrc
795 795 file. The option name which sets this value is
796 796 'wildcards_case_sensitive'. If this option is not specified in your
797 797 ipythonrc file, IPython's internal default is to do a case sensitive
798 798 search.
799 799
800 800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 801 specifiy can be searched in any of the following namespaces:
802 802 'builtin', 'user', 'user_global','internal', 'alias', where
803 803 'builtin' and 'user' are the search defaults. Note that you should
804 804 not use quotes when specifying namespaces.
805 805
806 806 'Builtin' contains the python module builtin, 'user' contains all
807 807 user data, 'alias' only contain the shell aliases and no python
808 808 objects, 'internal' contains objects used by IPython. The
809 809 'user_global' namespace is only used by embedded IPython instances,
810 810 and it contains module-level globals. You can add namespaces to the
811 811 search with -s or exclude them with -e (these options can be given
812 812 more than once).
813 813
814 814 Examples:
815 815
816 816 %psearch a* -> objects beginning with an a
817 817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 818 %psearch a* function -> all functions beginning with an a
819 819 %psearch re.e* -> objects beginning with an e in module re
820 820 %psearch r*.e* -> objects that start with e in modules starting in r
821 821 %psearch r*.* string -> all strings in modules beginning with r
822 822
823 823 Case sensitve search:
824 824
825 825 %psearch -c a* list all object beginning with lower case a
826 826
827 827 Show objects beginning with a single _:
828 828
829 829 %psearch -a _* list objects beginning with a single underscore"""
830 830 try:
831 831 parameter_s = parameter_s.encode('ascii')
832 832 except UnicodeEncodeError:
833 833 print 'Python identifiers can only contain ascii characters.'
834 834 return
835 835
836 836 # default namespaces to be searched
837 837 def_search = ['user','builtin']
838 838
839 839 # Process options/args
840 840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 841 opt = opts.get
842 842 shell = self.shell
843 843 psearch = shell.inspector.psearch
844 844
845 845 # select case options
846 846 if opts.has_key('i'):
847 847 ignore_case = True
848 848 elif opts.has_key('c'):
849 849 ignore_case = False
850 850 else:
851 851 ignore_case = not shell.rc.wildcards_case_sensitive
852 852
853 853 # Build list of namespaces to search from user options
854 854 def_search.extend(opt('s',[]))
855 855 ns_exclude = ns_exclude=opt('e',[])
856 856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857 857
858 858 # Call the actual search
859 859 try:
860 860 psearch(args,shell.ns_table,ns_search,
861 861 show_all=opt('a'),ignore_case=ignore_case)
862 862 except:
863 863 shell.showtraceback()
864 864
865 865 def magic_who_ls(self, parameter_s=''):
866 866 """Return a sorted list of all interactive variables.
867 867
868 868 If arguments are given, only variables of types matching these
869 869 arguments are returned."""
870 870
871 871 user_ns = self.shell.user_ns
872 872 internal_ns = self.shell.internal_ns
873 873 user_config_ns = self.shell.user_config_ns
874 874 out = []
875 875 typelist = parameter_s.split()
876 876
877 877 for i in user_ns:
878 878 if not (i.startswith('_') or i.startswith('_i')) \
879 879 and not (i in internal_ns or i in user_config_ns):
880 880 if typelist:
881 881 if type(user_ns[i]).__name__ in typelist:
882 882 out.append(i)
883 883 else:
884 884 out.append(i)
885 885 out.sort()
886 886 return out
887 887
888 888 def magic_who(self, parameter_s=''):
889 889 """Print all interactive variables, with some minimal formatting.
890 890
891 891 If any arguments are given, only variables whose type matches one of
892 892 these are printed. For example:
893 893
894 894 %who function str
895 895
896 896 will only list functions and strings, excluding all other types of
897 897 variables. To find the proper type names, simply use type(var) at a
898 898 command line to see how python prints type names. For example:
899 899
900 900 In [1]: type('hello')\\
901 901 Out[1]: <type 'str'>
902 902
903 903 indicates that the type name for strings is 'str'.
904 904
905 905 %who always excludes executed names loaded through your configuration
906 906 file and things which are internal to IPython.
907 907
908 908 This is deliberate, as typically you may load many modules and the
909 909 purpose of %who is to show you only what you've manually defined."""
910 910
911 911 varlist = self.magic_who_ls(parameter_s)
912 912 if not varlist:
913 913 if parameter_s:
914 914 print 'No variables match your requested type.'
915 915 else:
916 916 print 'Interactive namespace is empty.'
917 917 return
918 918
919 919 # if we have variables, move on...
920 920 count = 0
921 921 for i in varlist:
922 922 print i+'\t',
923 923 count += 1
924 924 if count > 8:
925 925 count = 0
926 926 print
927 927 print
928 928
929 929 def magic_whos(self, parameter_s=''):
930 930 """Like %who, but gives some extra information about each variable.
931 931
932 932 The same type filtering of %who can be applied here.
933 933
934 934 For all variables, the type is printed. Additionally it prints:
935 935
936 936 - For {},[],(): their length.
937 937
938 938 - For numpy and Numeric arrays, a summary with shape, number of
939 939 elements, typecode and size in memory.
940 940
941 941 - Everything else: a string representation, snipping their middle if
942 942 too long."""
943 943
944 944 varnames = self.magic_who_ls(parameter_s)
945 945 if not varnames:
946 946 if parameter_s:
947 947 print 'No variables match your requested type.'
948 948 else:
949 949 print 'Interactive namespace is empty.'
950 950 return
951 951
952 952 # if we have variables, move on...
953 953
954 954 # for these types, show len() instead of data:
955 955 seq_types = [types.DictType,types.ListType,types.TupleType]
956 956
957 957 # for numpy/Numeric arrays, display summary info
958 958 try:
959 959 import numpy
960 960 except ImportError:
961 961 ndarray_type = None
962 962 else:
963 963 ndarray_type = numpy.ndarray.__name__
964 964 try:
965 965 import Numeric
966 966 except ImportError:
967 967 array_type = None
968 968 else:
969 969 array_type = Numeric.ArrayType.__name__
970 970
971 971 # Find all variable names and types so we can figure out column sizes
972 972 def get_vars(i):
973 973 return self.shell.user_ns[i]
974 974
975 975 # some types are well known and can be shorter
976 976 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
977 977 def type_name(v):
978 978 tn = type(v).__name__
979 979 return abbrevs.get(tn,tn)
980 980
981 981 varlist = map(get_vars,varnames)
982 982
983 983 typelist = []
984 984 for vv in varlist:
985 985 tt = type_name(vv)
986 986
987 987 if tt=='instance':
988 988 typelist.append( abbrevs.get(str(vv.__class__),
989 989 str(vv.__class__)))
990 990 else:
991 991 typelist.append(tt)
992 992
993 993 # column labels and # of spaces as separator
994 994 varlabel = 'Variable'
995 995 typelabel = 'Type'
996 996 datalabel = 'Data/Info'
997 997 colsep = 3
998 998 # variable format strings
999 999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 1002 # find the size of the columns to format the output nicely
1003 1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 1005 # table header
1006 1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 1008 # and the table itself
1009 1009 kb = 1024
1010 1010 Mb = 1048576 # kb**2
1011 1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 1012 print itpl(vformat),
1013 1013 if vtype in seq_types:
1014 1014 print len(var)
1015 1015 elif vtype in [array_type,ndarray_type]:
1016 1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 1017 if vtype==ndarray_type:
1018 1018 # numpy
1019 1019 vsize = var.size
1020 1020 vbytes = vsize*var.itemsize
1021 1021 vdtype = var.dtype
1022 1022 else:
1023 1023 # Numeric
1024 1024 vsize = Numeric.size(var)
1025 1025 vbytes = vsize*var.itemsize()
1026 1026 vdtype = var.typecode()
1027 1027
1028 1028 if vbytes < 100000:
1029 1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 1030 else:
1031 1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 1032 if vbytes < Mb:
1033 1033 print '(%s kb)' % (vbytes/kb,)
1034 1034 else:
1035 1035 print '(%s Mb)' % (vbytes/Mb,)
1036 1036 else:
1037 1037 try:
1038 1038 vstr = str(var)
1039 1039 except UnicodeEncodeError:
1040 1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 1041 'backslashreplace')
1042 1042 vstr = vstr.replace('\n','\\n')
1043 1043 if len(vstr) < 50:
1044 1044 print vstr
1045 1045 else:
1046 1046 printpl(vfmt_short)
1047 1047
1048 1048 def magic_reset(self, parameter_s=''):
1049 1049 """Resets the namespace by removing all names defined by the user.
1050 1050
1051 1051 Input/Output history are left around in case you need them.
1052 1052
1053 1053 Parameters
1054 1054 ----------
1055 1055 -y : force reset without asking for confirmation.
1056 1056
1057 1057 Examples
1058 1058 --------
1059 1059 In [6]: a = 1
1060 1060
1061 1061 In [7]: a
1062 1062 Out[7]: 1
1063 1063
1064 1064 In [8]: 'a' in _ip.user_ns
1065 1065 Out[8]: True
1066 1066
1067 1067 In [9]: %reset -f
1068 1068
1069 1069 In [10]: 'a' in _ip.user_ns
1070 1070 Out[10]: False
1071 1071 """
1072 1072
1073 1073 if parameter_s == '-f':
1074 1074 ans = True
1075 1075 else:
1076 1076 ans = self.shell.ask_yes_no(
1077 1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 1078 if not ans:
1079 1079 print 'Nothing done.'
1080 1080 return
1081 1081 user_ns = self.shell.user_ns
1082 1082 for i in self.magic_who_ls():
1083 1083 del(user_ns[i])
1084 1084
1085 1085 # Also flush the private list of module references kept for script
1086 1086 # execution protection
1087 1087 self.shell.clear_main_mod_cache()
1088 1088
1089 1089 def magic_logstart(self,parameter_s=''):
1090 1090 """Start logging anywhere in a session.
1091 1091
1092 1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093 1093
1094 1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 1095 current directory, in 'rotate' mode (see below).
1096 1096
1097 1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 1098 history up to that point and then continues logging.
1099 1099
1100 1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 1101 of (note that the modes are given unquoted):\\
1102 1102 append: well, that says it.\\
1103 1103 backup: rename (if exists) to name~ and start name.\\
1104 1104 global: single logfile in your home dir, appended to.\\
1105 1105 over : overwrite existing log.\\
1106 1106 rotate: create rotating logs name.1~, name.2~, etc.
1107 1107
1108 1108 Options:
1109 1109
1110 1110 -o: log also IPython's output. In this mode, all commands which
1111 1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 1112 their corresponding input line. The output lines are always
1113 1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 1114 Python code.
1115 1115
1116 1116 Since this marker is always the same, filtering only the output from
1117 1117 a log is very easy, using for example a simple awk call:
1118 1118
1119 1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120 1120
1121 1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 1122 input, so that user lines are logged in their final form, converted
1123 1123 into valid Python. For example, %Exit is logged as
1124 1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 1125 exactly as typed, with no transformations applied.
1126 1126
1127 1127 -t: put timestamps before each input line logged (these are put in
1128 1128 comments)."""
1129 1129
1130 1130 opts,par = self.parse_options(parameter_s,'ort')
1131 1131 log_output = 'o' in opts
1132 1132 log_raw_input = 'r' in opts
1133 1133 timestamp = 't' in opts
1134 1134
1135 1135 rc = self.shell.rc
1136 1136 logger = self.shell.logger
1137 1137
1138 1138 # if no args are given, the defaults set in the logger constructor by
1139 1139 # ipytohn remain valid
1140 1140 if par:
1141 1141 try:
1142 1142 logfname,logmode = par.split()
1143 1143 except:
1144 1144 logfname = par
1145 1145 logmode = 'backup'
1146 1146 else:
1147 1147 logfname = logger.logfname
1148 1148 logmode = logger.logmode
1149 1149 # put logfname into rc struct as if it had been called on the command
1150 1150 # line, so it ends up saved in the log header Save it in case we need
1151 1151 # to restore it...
1152 1152 old_logfile = rc.opts.get('logfile','')
1153 1153 if logfname:
1154 1154 logfname = os.path.expanduser(logfname)
1155 1155 rc.opts.logfile = logfname
1156 1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1157 1157 try:
1158 1158 started = logger.logstart(logfname,loghead,logmode,
1159 1159 log_output,timestamp,log_raw_input)
1160 1160 except:
1161 1161 rc.opts.logfile = old_logfile
1162 1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1163 1163 else:
1164 1164 # log input history up to this point, optionally interleaving
1165 1165 # output if requested
1166 1166
1167 1167 if timestamp:
1168 1168 # disable timestamping for the previous history, since we've
1169 1169 # lost those already (no time machine here).
1170 1170 logger.timestamp = False
1171 1171
1172 1172 if log_raw_input:
1173 1173 input_hist = self.shell.input_hist_raw
1174 1174 else:
1175 1175 input_hist = self.shell.input_hist
1176 1176
1177 1177 if log_output:
1178 1178 log_write = logger.log_write
1179 1179 output_hist = self.shell.output_hist
1180 1180 for n in range(1,len(input_hist)-1):
1181 1181 log_write(input_hist[n].rstrip())
1182 1182 if n in output_hist:
1183 1183 log_write(repr(output_hist[n]),'output')
1184 1184 else:
1185 1185 logger.log_write(input_hist[1:])
1186 1186 if timestamp:
1187 1187 # re-enable timestamping
1188 1188 logger.timestamp = True
1189 1189
1190 1190 print ('Activating auto-logging. '
1191 1191 'Current session state plus future input saved.')
1192 1192 logger.logstate()
1193 1193
1194 1194 def magic_logstop(self,parameter_s=''):
1195 1195 """Fully stop logging and close log file.
1196 1196
1197 1197 In order to start logging again, a new %logstart call needs to be made,
1198 1198 possibly (though not necessarily) with a new filename, mode and other
1199 1199 options."""
1200 1200 self.logger.logstop()
1201 1201
1202 1202 def magic_logoff(self,parameter_s=''):
1203 1203 """Temporarily stop logging.
1204 1204
1205 1205 You must have previously started logging."""
1206 1206 self.shell.logger.switch_log(0)
1207 1207
1208 1208 def magic_logon(self,parameter_s=''):
1209 1209 """Restart logging.
1210 1210
1211 1211 This function is for restarting logging which you've temporarily
1212 1212 stopped with %logoff. For starting logging for the first time, you
1213 1213 must use the %logstart function, which allows you to specify an
1214 1214 optional log filename."""
1215 1215
1216 1216 self.shell.logger.switch_log(1)
1217 1217
1218 1218 def magic_logstate(self,parameter_s=''):
1219 1219 """Print the status of the logging system."""
1220 1220
1221 1221 self.shell.logger.logstate()
1222 1222
1223 1223 def magic_pdb(self, parameter_s=''):
1224 1224 """Control the automatic calling of the pdb interactive debugger.
1225 1225
1226 1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1227 1227 argument it works as a toggle.
1228 1228
1229 1229 When an exception is triggered, IPython can optionally call the
1230 1230 interactive pdb debugger after the traceback printout. %pdb toggles
1231 1231 this feature on and off.
1232 1232
1233 1233 The initial state of this feature is set in your ipythonrc
1234 1234 configuration file (the variable is called 'pdb').
1235 1235
1236 1236 If you want to just activate the debugger AFTER an exception has fired,
1237 1237 without having to type '%pdb on' and rerunning your code, you can use
1238 1238 the %debug magic."""
1239 1239
1240 1240 par = parameter_s.strip().lower()
1241 1241
1242 1242 if par:
1243 1243 try:
1244 1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1245 1245 except KeyError:
1246 1246 print ('Incorrect argument. Use on/1, off/0, '
1247 1247 'or nothing for a toggle.')
1248 1248 return
1249 1249 else:
1250 1250 # toggle
1251 1251 new_pdb = not self.shell.call_pdb
1252 1252
1253 1253 # set on the shell
1254 1254 self.shell.call_pdb = new_pdb
1255 1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1256 1256
1257 1257 def magic_debug(self, parameter_s=''):
1258 1258 """Activate the interactive debugger in post-mortem mode.
1259 1259
1260 1260 If an exception has just occurred, this lets you inspect its stack
1261 1261 frames interactively. Note that this will always work only on the last
1262 1262 traceback that occurred, so you must call this quickly after an
1263 1263 exception that you wish to inspect has fired, because if another one
1264 1264 occurs, it clobbers the previous one.
1265 1265
1266 1266 If you want IPython to automatically do this on every exception, see
1267 1267 the %pdb magic for more details.
1268 1268 """
1269 1269
1270 1270 self.shell.debugger(force=True)
1271 1271
1272 1272 @testdec.skip_doctest
1273 1273 def magic_prun(self, parameter_s ='',user_mode=1,
1274 1274 opts=None,arg_lst=None,prog_ns=None):
1275 1275
1276 1276 """Run a statement through the python code profiler.
1277 1277
1278 1278 Usage:
1279 1279 %prun [options] statement
1280 1280
1281 1281 The given statement (which doesn't require quote marks) is run via the
1282 1282 python profiler in a manner similar to the profile.run() function.
1283 1283 Namespaces are internally managed to work correctly; profile.run
1284 1284 cannot be used in IPython because it makes certain assumptions about
1285 1285 namespaces which do not hold under IPython.
1286 1286
1287 1287 Options:
1288 1288
1289 1289 -l <limit>: you can place restrictions on what or how much of the
1290 1290 profile gets printed. The limit value can be:
1291 1291
1292 1292 * A string: only information for function names containing this string
1293 1293 is printed.
1294 1294
1295 1295 * An integer: only these many lines are printed.
1296 1296
1297 1297 * A float (between 0 and 1): this fraction of the report is printed
1298 1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1299 1299
1300 1300 You can combine several limits with repeated use of the option. For
1301 1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1302 1302 information about class constructors.
1303 1303
1304 1304 -r: return the pstats.Stats object generated by the profiling. This
1305 1305 object has all the information about the profile in it, and you can
1306 1306 later use it for further analysis or in other functions.
1307 1307
1308 1308 -s <key>: sort profile by given key. You can provide more than one key
1309 1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1310 1310 default sorting key is 'time'.
1311 1311
1312 1312 The following is copied verbatim from the profile documentation
1313 1313 referenced below:
1314 1314
1315 1315 When more than one key is provided, additional keys are used as
1316 1316 secondary criteria when the there is equality in all keys selected
1317 1317 before them.
1318 1318
1319 1319 Abbreviations can be used for any key names, as long as the
1320 1320 abbreviation is unambiguous. The following are the keys currently
1321 1321 defined:
1322 1322
1323 1323 Valid Arg Meaning
1324 1324 "calls" call count
1325 1325 "cumulative" cumulative time
1326 1326 "file" file name
1327 1327 "module" file name
1328 1328 "pcalls" primitive call count
1329 1329 "line" line number
1330 1330 "name" function name
1331 1331 "nfl" name/file/line
1332 1332 "stdname" standard name
1333 1333 "time" internal time
1334 1334
1335 1335 Note that all sorts on statistics are in descending order (placing
1336 1336 most time consuming items first), where as name, file, and line number
1337 1337 searches are in ascending order (i.e., alphabetical). The subtle
1338 1338 distinction between "nfl" and "stdname" is that the standard name is a
1339 1339 sort of the name as printed, which means that the embedded line
1340 1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1341 1341 would (if the file names were the same) appear in the string order
1342 1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1343 1343 line numbers. In fact, sort_stats("nfl") is the same as
1344 1344 sort_stats("name", "file", "line").
1345 1345
1346 1346 -T <filename>: save profile results as shown on screen to a text
1347 1347 file. The profile is still shown on screen.
1348 1348
1349 1349 -D <filename>: save (via dump_stats) profile statistics to given
1350 1350 filename. This data is in a format understod by the pstats module, and
1351 1351 is generated by a call to the dump_stats() method of profile
1352 1352 objects. The profile is still shown on screen.
1353 1353
1354 1354 If you want to run complete programs under the profiler's control, use
1355 1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1356 1356 contains profiler specific options as described here.
1357 1357
1358 1358 You can read the complete documentation for the profile module with::
1359 1359
1360 1360 In [1]: import profile; profile.help()
1361 1361 """
1362 1362
1363 1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1364 1364 # protect user quote marks
1365 1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1366 1366
1367 1367 if user_mode: # regular user call
1368 1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1369 1369 list_all=1)
1370 1370 namespace = self.shell.user_ns
1371 1371 else: # called to run a program by %run -p
1372 1372 try:
1373 1373 filename = get_py_filename(arg_lst[0])
1374 1374 except IOError,msg:
1375 1375 error(msg)
1376 1376 return
1377 1377
1378 1378 arg_str = 'execfile(filename,prog_ns)'
1379 1379 namespace = locals()
1380 1380
1381 1381 opts.merge(opts_def)
1382 1382
1383 1383 prof = profile.Profile()
1384 1384 try:
1385 1385 prof = prof.runctx(arg_str,namespace,namespace)
1386 1386 sys_exit = ''
1387 1387 except SystemExit:
1388 1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1389 1389
1390 1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1391 1391
1392 1392 lims = opts.l
1393 1393 if lims:
1394 1394 lims = [] # rebuild lims with ints/floats/strings
1395 1395 for lim in opts.l:
1396 1396 try:
1397 1397 lims.append(int(lim))
1398 1398 except ValueError:
1399 1399 try:
1400 1400 lims.append(float(lim))
1401 1401 except ValueError:
1402 1402 lims.append(lim)
1403 1403
1404 1404 # Trap output.
1405 1405 stdout_trap = StringIO()
1406 1406
1407 1407 if hasattr(stats,'stream'):
1408 1408 # In newer versions of python, the stats object has a 'stream'
1409 1409 # attribute to write into.
1410 1410 stats.stream = stdout_trap
1411 1411 stats.print_stats(*lims)
1412 1412 else:
1413 1413 # For older versions, we manually redirect stdout during printing
1414 1414 sys_stdout = sys.stdout
1415 1415 try:
1416 1416 sys.stdout = stdout_trap
1417 1417 stats.print_stats(*lims)
1418 1418 finally:
1419 1419 sys.stdout = sys_stdout
1420 1420
1421 1421 output = stdout_trap.getvalue()
1422 1422 output = output.rstrip()
1423 1423
1424 1424 page(output,screen_lines=self.shell.rc.screen_length)
1425 1425 print sys_exit,
1426 1426
1427 1427 dump_file = opts.D[0]
1428 1428 text_file = opts.T[0]
1429 1429 if dump_file:
1430 1430 prof.dump_stats(dump_file)
1431 1431 print '\n*** Profile stats marshalled to file',\
1432 1432 `dump_file`+'.',sys_exit
1433 1433 if text_file:
1434 1434 pfile = file(text_file,'w')
1435 1435 pfile.write(output)
1436 1436 pfile.close()
1437 1437 print '\n*** Profile printout saved to text file',\
1438 1438 `text_file`+'.',sys_exit
1439 1439
1440 1440 if opts.has_key('r'):
1441 1441 return stats
1442 1442 else:
1443 1443 return None
1444 1444
1445 1445 @testdec.skip_doctest
1446 1446 def magic_run(self, parameter_s ='',runner=None,
1447 1447 file_finder=get_py_filename):
1448 1448 """Run the named file inside IPython as a program.
1449 1449
1450 1450 Usage:\\
1451 1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1452 1452
1453 1453 Parameters after the filename are passed as command-line arguments to
1454 1454 the program (put in sys.argv). Then, control returns to IPython's
1455 1455 prompt.
1456 1456
1457 1457 This is similar to running at a system prompt:\\
1458 1458 $ python file args\\
1459 1459 but with the advantage of giving you IPython's tracebacks, and of
1460 1460 loading all variables into your interactive namespace for further use
1461 1461 (unless -p is used, see below).
1462 1462
1463 1463 The file is executed in a namespace initially consisting only of
1464 1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1465 1465 sees its environment as if it were being run as a stand-alone program
1466 1466 (except for sharing global objects such as previously imported
1467 1467 modules). But after execution, the IPython interactive namespace gets
1468 1468 updated with all variables defined in the program (except for __name__
1469 1469 and sys.argv). This allows for very convenient loading of code for
1470 1470 interactive work, while giving each program a 'clean sheet' to run in.
1471 1471
1472 1472 Options:
1473 1473
1474 1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1475 1475 without extension (as python does under import). This allows running
1476 1476 scripts and reloading the definitions in them without calling code
1477 1477 protected by an ' if __name__ == "__main__" ' clause.
1478 1478
1479 1479 -i: run the file in IPython's namespace instead of an empty one. This
1480 1480 is useful if you are experimenting with code written in a text editor
1481 1481 which depends on variables defined interactively.
1482 1482
1483 1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1484 1484 being run. This is particularly useful if IPython is being used to
1485 1485 run unittests, which always exit with a sys.exit() call. In such
1486 1486 cases you are interested in the output of the test results, not in
1487 1487 seeing a traceback of the unittest module.
1488 1488
1489 1489 -t: print timing information at the end of the run. IPython will give
1490 1490 you an estimated CPU time consumption for your script, which under
1491 1491 Unix uses the resource module to avoid the wraparound problems of
1492 1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1493 1493 is also given (for Windows platforms this is reported as 0.0).
1494 1494
1495 1495 If -t is given, an additional -N<N> option can be given, where <N>
1496 1496 must be an integer indicating how many times you want the script to
1497 1497 run. The final timing report will include total and per run results.
1498 1498
1499 1499 For example (testing the script uniq_stable.py):
1500 1500
1501 1501 In [1]: run -t uniq_stable
1502 1502
1503 1503 IPython CPU timings (estimated):\\
1504 1504 User : 0.19597 s.\\
1505 1505 System: 0.0 s.\\
1506 1506
1507 1507 In [2]: run -t -N5 uniq_stable
1508 1508
1509 1509 IPython CPU timings (estimated):\\
1510 1510 Total runs performed: 5\\
1511 1511 Times : Total Per run\\
1512 1512 User : 0.910862 s, 0.1821724 s.\\
1513 1513 System: 0.0 s, 0.0 s.
1514 1514
1515 1515 -d: run your program under the control of pdb, the Python debugger.
1516 1516 This allows you to execute your program step by step, watch variables,
1517 1517 etc. Internally, what IPython does is similar to calling:
1518 1518
1519 1519 pdb.run('execfile("YOURFILENAME")')
1520 1520
1521 1521 with a breakpoint set on line 1 of your file. You can change the line
1522 1522 number for this automatic breakpoint to be <N> by using the -bN option
1523 1523 (where N must be an integer). For example:
1524 1524
1525 1525 %run -d -b40 myscript
1526 1526
1527 1527 will set the first breakpoint at line 40 in myscript.py. Note that
1528 1528 the first breakpoint must be set on a line which actually does
1529 1529 something (not a comment or docstring) for it to stop execution.
1530 1530
1531 1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1532 1532 first enter 'c' (without qoutes) to start execution up to the first
1533 1533 breakpoint.
1534 1534
1535 1535 Entering 'help' gives information about the use of the debugger. You
1536 1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1537 1537 at a prompt.
1538 1538
1539 1539 -p: run program under the control of the Python profiler module (which
1540 1540 prints a detailed report of execution times, function calls, etc).
1541 1541
1542 1542 You can pass other options after -p which affect the behavior of the
1543 1543 profiler itself. See the docs for %prun for details.
1544 1544
1545 1545 In this mode, the program's variables do NOT propagate back to the
1546 1546 IPython interactive namespace (because they remain in the namespace
1547 1547 where the profiler executes them).
1548 1548
1549 1549 Internally this triggers a call to %prun, see its documentation for
1550 1550 details on the options available specifically for profiling.
1551 1551
1552 1552 There is one special usage for which the text above doesn't apply:
1553 1553 if the filename ends with .ipy, the file is run as ipython script,
1554 1554 just as if the commands were written on IPython prompt.
1555 1555 """
1556 1556
1557 1557 # get arguments and set sys.argv for program to be run.
1558 1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1559 1559 mode='list',list_all=1)
1560 1560
1561 1561 try:
1562 1562 filename = file_finder(arg_lst[0])
1563 1563 except IndexError:
1564 1564 warn('you must provide at least a filename.')
1565 1565 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1566 1566 return
1567 1567 except IOError,msg:
1568 1568 error(msg)
1569 1569 return
1570 1570
1571 1571 if filename.lower().endswith('.ipy'):
1572 1572 self.api.runlines(open(filename).read())
1573 1573 return
1574 1574
1575 1575 # Control the response to exit() calls made by the script being run
1576 1576 exit_ignore = opts.has_key('e')
1577 1577
1578 1578 # Make sure that the running script gets a proper sys.argv as if it
1579 1579 # were run from a system shell.
1580 1580 save_argv = sys.argv # save it for later restoring
1581 1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1582 1582
1583 1583 if opts.has_key('i'):
1584 1584 # Run in user's interactive namespace
1585 1585 prog_ns = self.shell.user_ns
1586 1586 __name__save = self.shell.user_ns['__name__']
1587 1587 prog_ns['__name__'] = '__main__'
1588 1588 main_mod = self.shell.new_main_mod(prog_ns)
1589 1589 else:
1590 1590 # Run in a fresh, empty namespace
1591 1591 if opts.has_key('n'):
1592 1592 name = os.path.splitext(os.path.basename(filename))[0]
1593 1593 else:
1594 1594 name = '__main__'
1595 1595
1596 1596 main_mod = self.shell.new_main_mod()
1597 1597 prog_ns = main_mod.__dict__
1598 1598 prog_ns['__name__'] = name
1599 1599
1600 1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1601 1601 # set the __file__ global in the script's namespace
1602 1602 prog_ns['__file__'] = filename
1603 1603
1604 1604 # pickle fix. See iplib for an explanation. But we need to make sure
1605 1605 # that, if we overwrite __main__, we replace it at the end
1606 1606 main_mod_name = prog_ns['__name__']
1607 1607
1608 1608 if main_mod_name == '__main__':
1609 1609 restore_main = sys.modules['__main__']
1610 1610 else:
1611 1611 restore_main = False
1612 1612
1613 1613 # This needs to be undone at the end to prevent holding references to
1614 1614 # every single object ever created.
1615 1615 sys.modules[main_mod_name] = main_mod
1616 1616
1617 1617 stats = None
1618 1618 try:
1619 1619 self.shell.savehist()
1620 1620
1621 1621 if opts.has_key('p'):
1622 1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1623 1623 else:
1624 1624 if opts.has_key('d'):
1625 1625 deb = debugger.Pdb(self.shell.rc.colors)
1626 1626 # reset Breakpoint state, which is moronically kept
1627 1627 # in a class
1628 1628 bdb.Breakpoint.next = 1
1629 1629 bdb.Breakpoint.bplist = {}
1630 1630 bdb.Breakpoint.bpbynumber = [None]
1631 1631 # Set an initial breakpoint to stop execution
1632 1632 maxtries = 10
1633 1633 bp = int(opts.get('b',[1])[0])
1634 1634 checkline = deb.checkline(filename,bp)
1635 1635 if not checkline:
1636 1636 for bp in range(bp+1,bp+maxtries+1):
1637 1637 if deb.checkline(filename,bp):
1638 1638 break
1639 1639 else:
1640 1640 msg = ("\nI failed to find a valid line to set "
1641 1641 "a breakpoint\n"
1642 1642 "after trying up to line: %s.\n"
1643 1643 "Please set a valid breakpoint manually "
1644 1644 "with the -b option." % bp)
1645 1645 error(msg)
1646 1646 return
1647 1647 # if we find a good linenumber, set the breakpoint
1648 1648 deb.do_break('%s:%s' % (filename,bp))
1649 1649 # Start file run
1650 1650 print "NOTE: Enter 'c' at the",
1651 1651 print "%s prompt to start your script." % deb.prompt
1652 1652 try:
1653 1653 deb.run('execfile("%s")' % filename,prog_ns)
1654 1654
1655 1655 except:
1656 1656 etype, value, tb = sys.exc_info()
1657 1657 # Skip three frames in the traceback: the %run one,
1658 1658 # one inside bdb.py, and the command-line typed by the
1659 1659 # user (run by exec in pdb itself).
1660 1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1661 1661 else:
1662 1662 if runner is None:
1663 1663 runner = self.shell.safe_execfile
1664 1664 if opts.has_key('t'):
1665 1665 # timed execution
1666 1666 try:
1667 1667 nruns = int(opts['N'][0])
1668 1668 if nruns < 1:
1669 1669 error('Number of runs must be >=1')
1670 1670 return
1671 1671 except (KeyError):
1672 1672 nruns = 1
1673 1673 if nruns == 1:
1674 1674 t0 = clock2()
1675 1675 runner(filename,prog_ns,prog_ns,
1676 1676 exit_ignore=exit_ignore)
1677 1677 t1 = clock2()
1678 1678 t_usr = t1[0]-t0[0]
1679 1679 t_sys = t1[1]-t0[1]
1680 1680 print "\nIPython CPU timings (estimated):"
1681 1681 print " User : %10s s." % t_usr
1682 1682 print " System: %10s s." % t_sys
1683 1683 else:
1684 1684 runs = range(nruns)
1685 1685 t0 = clock2()
1686 1686 for nr in runs:
1687 1687 runner(filename,prog_ns,prog_ns,
1688 1688 exit_ignore=exit_ignore)
1689 1689 t1 = clock2()
1690 1690 t_usr = t1[0]-t0[0]
1691 1691 t_sys = t1[1]-t0[1]
1692 1692 print "\nIPython CPU timings (estimated):"
1693 1693 print "Total runs performed:",nruns
1694 1694 print " Times : %10s %10s" % ('Total','Per run')
1695 1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1696 1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1697 1697
1698 1698 else:
1699 1699 # regular execution
1700 1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1701 1701
1702 1702 if opts.has_key('i'):
1703 1703 self.shell.user_ns['__name__'] = __name__save
1704 1704 else:
1705 1705 # The shell MUST hold a reference to prog_ns so after %run
1706 1706 # exits, the python deletion mechanism doesn't zero it out
1707 1707 # (leaving dangling references).
1708 1708 self.shell.cache_main_mod(prog_ns,filename)
1709 1709 # update IPython interactive namespace
1710 1710
1711 1711 # Some forms of read errors on the file may mean the
1712 1712 # __name__ key was never set; using pop we don't have to
1713 1713 # worry about a possible KeyError.
1714 1714 prog_ns.pop('__name__', None)
1715 1715
1716 1716 self.shell.user_ns.update(prog_ns)
1717 1717 finally:
1718 1718 # It's a bit of a mystery why, but __builtins__ can change from
1719 1719 # being a module to becoming a dict missing some key data after
1720 1720 # %run. As best I can see, this is NOT something IPython is doing
1721 1721 # at all, and similar problems have been reported before:
1722 1722 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1723 1723 # Since this seems to be done by the interpreter itself, the best
1724 1724 # we can do is to at least restore __builtins__ for the user on
1725 1725 # exit.
1726 1726 self.shell.user_ns['__builtins__'] = __builtin__
1727 1727
1728 1728 # Ensure key global structures are restored
1729 1729 sys.argv = save_argv
1730 1730 if restore_main:
1731 1731 sys.modules['__main__'] = restore_main
1732 1732 else:
1733 1733 # Remove from sys.modules the reference to main_mod we'd
1734 1734 # added. Otherwise it will trap references to objects
1735 1735 # contained therein.
1736 1736 del sys.modules[main_mod_name]
1737 1737
1738 1738 self.shell.reloadhist()
1739 1739
1740 1740 return stats
1741 1741
1742 1742 def magic_runlog(self, parameter_s =''):
1743 1743 """Run files as logs.
1744 1744
1745 1745 Usage:\\
1746 1746 %runlog file1 file2 ...
1747 1747
1748 1748 Run the named files (treating them as log files) in sequence inside
1749 1749 the interpreter, and return to the prompt. This is much slower than
1750 1750 %run because each line is executed in a try/except block, but it
1751 1751 allows running files with syntax errors in them.
1752 1752
1753 1753 Normally IPython will guess when a file is one of its own logfiles, so
1754 1754 you can typically use %run even for logs. This shorthand allows you to
1755 1755 force any file to be treated as a log file."""
1756 1756
1757 1757 for f in parameter_s.split():
1758 1758 self.shell.safe_execfile(f,self.shell.user_ns,
1759 1759 self.shell.user_ns,islog=1)
1760 1760
1761 1761 @testdec.skip_doctest
1762 1762 def magic_timeit(self, parameter_s =''):
1763 1763 """Time execution of a Python statement or expression
1764 1764
1765 1765 Usage:\\
1766 1766 %timeit [-n<N> -r<R> [-t|-c]] statement
1767 1767
1768 1768 Time execution of a Python statement or expression using the timeit
1769 1769 module.
1770 1770
1771 1771 Options:
1772 1772 -n<N>: execute the given statement <N> times in a loop. If this value
1773 1773 is not given, a fitting value is chosen.
1774 1774
1775 1775 -r<R>: repeat the loop iteration <R> times and take the best result.
1776 1776 Default: 3
1777 1777
1778 1778 -t: use time.time to measure the time, which is the default on Unix.
1779 1779 This function measures wall time.
1780 1780
1781 1781 -c: use time.clock to measure the time, which is the default on
1782 1782 Windows and measures wall time. On Unix, resource.getrusage is used
1783 1783 instead and returns the CPU user time.
1784 1784
1785 1785 -p<P>: use a precision of <P> digits to display the timing result.
1786 1786 Default: 3
1787 1787
1788 1788
1789 1789 Examples:
1790 1790
1791 1791 In [1]: %timeit pass
1792 1792 10000000 loops, best of 3: 53.3 ns per loop
1793 1793
1794 1794 In [2]: u = None
1795 1795
1796 1796 In [3]: %timeit u is None
1797 1797 10000000 loops, best of 3: 184 ns per loop
1798 1798
1799 1799 In [4]: %timeit -r 4 u == None
1800 1800 1000000 loops, best of 4: 242 ns per loop
1801 1801
1802 1802 In [5]: import time
1803 1803
1804 1804 In [6]: %timeit -n1 time.sleep(2)
1805 1805 1 loops, best of 3: 2 s per loop
1806 1806
1807 1807
1808 1808 The times reported by %timeit will be slightly higher than those
1809 1809 reported by the timeit.py script when variables are accessed. This is
1810 1810 due to the fact that %timeit executes the statement in the namespace
1811 1811 of the shell, compared with timeit.py, which uses a single setup
1812 1812 statement to import function or create variables. Generally, the bias
1813 1813 does not matter as long as results from timeit.py are not mixed with
1814 1814 those from %timeit."""
1815 1815
1816 1816 import timeit
1817 1817 import math
1818 1818
1819 1819 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1820 1820 # certain terminals. Until we figure out a robust way of
1821 1821 # auto-detecting if the terminal can deal with it, use plain 'us' for
1822 1822 # microseconds. I am really NOT happy about disabling the proper
1823 1823 # 'micro' prefix, but crashing is worse... If anyone knows what the
1824 1824 # right solution for this is, I'm all ears...
1825 1825 #
1826 1826 # Note: using
1827 1827 #
1828 1828 # s = u'\xb5'
1829 1829 # s.encode(sys.getdefaultencoding())
1830 1830 #
1831 1831 # is not sufficient, as I've seen terminals where that fails but
1832 1832 # print s
1833 1833 #
1834 1834 # succeeds
1835 1835 #
1836 1836 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1837 1837
1838 1838 #units = [u"s", u"ms",u'\xb5',"ns"]
1839 1839 units = [u"s", u"ms",u'us',"ns"]
1840 1840
1841 1841 scaling = [1, 1e3, 1e6, 1e9]
1842 1842
1843 1843 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1844 1844 posix=False)
1845 1845 if stmt == "":
1846 1846 return
1847 1847 timefunc = timeit.default_timer
1848 1848 number = int(getattr(opts, "n", 0))
1849 1849 repeat = int(getattr(opts, "r", timeit.default_repeat))
1850 1850 precision = int(getattr(opts, "p", 3))
1851 1851 if hasattr(opts, "t"):
1852 1852 timefunc = time.time
1853 1853 if hasattr(opts, "c"):
1854 1854 timefunc = clock
1855 1855
1856 1856 timer = timeit.Timer(timer=timefunc)
1857 1857 # this code has tight coupling to the inner workings of timeit.Timer,
1858 1858 # but is there a better way to achieve that the code stmt has access
1859 1859 # to the shell namespace?
1860 1860
1861 1861 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1862 1862 'setup': "pass"}
1863 1863 # Track compilation time so it can be reported if too long
1864 1864 # Minimum time above which compilation time will be reported
1865 1865 tc_min = 0.1
1866 1866
1867 1867 t0 = clock()
1868 1868 code = compile(src, "<magic-timeit>", "exec")
1869 1869 tc = clock()-t0
1870 1870
1871 1871 ns = {}
1872 1872 exec code in self.shell.user_ns, ns
1873 1873 timer.inner = ns["inner"]
1874 1874
1875 1875 if number == 0:
1876 1876 # determine number so that 0.2 <= total time < 2.0
1877 1877 number = 1
1878 1878 for i in range(1, 10):
1879 1879 if timer.timeit(number) >= 0.2:
1880 1880 break
1881 1881 number *= 10
1882 1882
1883 1883 best = min(timer.repeat(repeat, number)) / number
1884 1884
1885 1885 if best > 0.0:
1886 1886 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1887 1887 else:
1888 1888 order = 3
1889 1889 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1890 1890 precision,
1891 1891 best * scaling[order],
1892 1892 units[order])
1893 1893 if tc > tc_min:
1894 1894 print "Compiler time: %.2f s" % tc
1895 1895
1896 1896 @testdec.skip_doctest
1897 1897 def magic_time(self,parameter_s = ''):
1898 1898 """Time execution of a Python statement or expression.
1899 1899
1900 1900 The CPU and wall clock times are printed, and the value of the
1901 1901 expression (if any) is returned. Note that under Win32, system time
1902 1902 is always reported as 0, since it can not be measured.
1903 1903
1904 1904 This function provides very basic timing functionality. In Python
1905 1905 2.3, the timeit module offers more control and sophistication, so this
1906 1906 could be rewritten to use it (patches welcome).
1907 1907
1908 1908 Some examples:
1909 1909
1910 1910 In [1]: time 2**128
1911 1911 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1912 1912 Wall time: 0.00
1913 1913 Out[1]: 340282366920938463463374607431768211456L
1914 1914
1915 1915 In [2]: n = 1000000
1916 1916
1917 1917 In [3]: time sum(range(n))
1918 1918 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1919 1919 Wall time: 1.37
1920 1920 Out[3]: 499999500000L
1921 1921
1922 1922 In [4]: time print 'hello world'
1923 1923 hello world
1924 1924 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1925 1925 Wall time: 0.00
1926 1926
1927 1927 Note that the time needed by Python to compile the given expression
1928 1928 will be reported if it is more than 0.1s. In this example, the
1929 1929 actual exponentiation is done by Python at compilation time, so while
1930 1930 the expression can take a noticeable amount of time to compute, that
1931 1931 time is purely due to the compilation:
1932 1932
1933 1933 In [5]: time 3**9999;
1934 1934 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1935 1935 Wall time: 0.00 s
1936 1936
1937 1937 In [6]: time 3**999999;
1938 1938 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1939 1939 Wall time: 0.00 s
1940 1940 Compiler : 0.78 s
1941 1941 """
1942 1942
1943 1943 # fail immediately if the given expression can't be compiled
1944 1944
1945 1945 expr = self.shell.prefilter(parameter_s,False)
1946 1946
1947 1947 # Minimum time above which compilation time will be reported
1948 1948 tc_min = 0.1
1949 1949
1950 1950 try:
1951 1951 mode = 'eval'
1952 1952 t0 = clock()
1953 1953 code = compile(expr,'<timed eval>',mode)
1954 1954 tc = clock()-t0
1955 1955 except SyntaxError:
1956 1956 mode = 'exec'
1957 1957 t0 = clock()
1958 1958 code = compile(expr,'<timed exec>',mode)
1959 1959 tc = clock()-t0
1960 1960 # skew measurement as little as possible
1961 1961 glob = self.shell.user_ns
1962 1962 clk = clock2
1963 1963 wtime = time.time
1964 1964 # time execution
1965 1965 wall_st = wtime()
1966 1966 if mode=='eval':
1967 1967 st = clk()
1968 1968 out = eval(code,glob)
1969 1969 end = clk()
1970 1970 else:
1971 1971 st = clk()
1972 1972 exec code in glob
1973 1973 end = clk()
1974 1974 out = None
1975 1975 wall_end = wtime()
1976 1976 # Compute actual times and report
1977 1977 wall_time = wall_end-wall_st
1978 1978 cpu_user = end[0]-st[0]
1979 1979 cpu_sys = end[1]-st[1]
1980 1980 cpu_tot = cpu_user+cpu_sys
1981 1981 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1982 1982 (cpu_user,cpu_sys,cpu_tot)
1983 1983 print "Wall time: %.2f s" % wall_time
1984 1984 if tc > tc_min:
1985 1985 print "Compiler : %.2f s" % tc
1986 1986 return out
1987 1987
1988 1988 @testdec.skip_doctest
1989 1989 def magic_macro(self,parameter_s = ''):
1990 1990 """Define a set of input lines as a macro for future re-execution.
1991 1991
1992 1992 Usage:\\
1993 1993 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1994 1994
1995 1995 Options:
1996 1996
1997 1997 -r: use 'raw' input. By default, the 'processed' history is used,
1998 1998 so that magics are loaded in their transformed version to valid
1999 1999 Python. If this option is given, the raw input as typed as the
2000 2000 command line is used instead.
2001 2001
2002 2002 This will define a global variable called `name` which is a string
2003 2003 made of joining the slices and lines you specify (n1,n2,... numbers
2004 2004 above) from your input history into a single string. This variable
2005 2005 acts like an automatic function which re-executes those lines as if
2006 2006 you had typed them. You just type 'name' at the prompt and the code
2007 2007 executes.
2008 2008
2009 2009 The notation for indicating number ranges is: n1-n2 means 'use line
2010 2010 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2011 2011 using the lines numbered 5,6 and 7.
2012 2012
2013 2013 Note: as a 'hidden' feature, you can also use traditional python slice
2014 2014 notation, where N:M means numbers N through M-1.
2015 2015
2016 2016 For example, if your history contains (%hist prints it):
2017 2017
2018 2018 44: x=1
2019 2019 45: y=3
2020 2020 46: z=x+y
2021 2021 47: print x
2022 2022 48: a=5
2023 2023 49: print 'x',x,'y',y
2024 2024
2025 2025 you can create a macro with lines 44 through 47 (included) and line 49
2026 2026 called my_macro with:
2027 2027
2028 2028 In [55]: %macro my_macro 44-47 49
2029 2029
2030 2030 Now, typing `my_macro` (without quotes) will re-execute all this code
2031 2031 in one pass.
2032 2032
2033 2033 You don't need to give the line-numbers in order, and any given line
2034 2034 number can appear multiple times. You can assemble macros with any
2035 2035 lines from your input history in any order.
2036 2036
2037 2037 The macro is a simple object which holds its value in an attribute,
2038 2038 but IPython's display system checks for macros and executes them as
2039 2039 code instead of printing them when you type their name.
2040 2040
2041 2041 You can view a macro's contents by explicitly printing it with:
2042 2042
2043 2043 'print macro_name'.
2044 2044
2045 2045 For one-off cases which DON'T contain magic function calls in them you
2046 2046 can obtain similar results by explicitly executing slices from your
2047 2047 input history with:
2048 2048
2049 2049 In [60]: exec In[44:48]+In[49]"""
2050 2050
2051 2051 opts,args = self.parse_options(parameter_s,'r',mode='list')
2052 2052 if not args:
2053 2053 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2054 2054 macs.sort()
2055 2055 return macs
2056 2056 if len(args) == 1:
2057 2057 raise UsageError(
2058 2058 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2059 2059 name,ranges = args[0], args[1:]
2060 2060
2061 2061 #print 'rng',ranges # dbg
2062 2062 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2063 2063 macro = Macro(lines)
2064 2064 self.shell.user_ns.update({name:macro})
2065 2065 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2066 2066 print 'Macro contents:'
2067 2067 print macro,
2068 2068
2069 2069 def magic_save(self,parameter_s = ''):
2070 2070 """Save a set of lines to a given filename.
2071 2071
2072 2072 Usage:\\
2073 2073 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2074 2074
2075 2075 Options:
2076 2076
2077 2077 -r: use 'raw' input. By default, the 'processed' history is used,
2078 2078 so that magics are loaded in their transformed version to valid
2079 2079 Python. If this option is given, the raw input as typed as the
2080 2080 command line is used instead.
2081 2081
2082 2082 This function uses the same syntax as %macro for line extraction, but
2083 2083 instead of creating a macro it saves the resulting string to the
2084 2084 filename you specify.
2085 2085
2086 2086 It adds a '.py' extension to the file if you don't do so yourself, and
2087 2087 it asks for confirmation before overwriting existing files."""
2088 2088
2089 2089 opts,args = self.parse_options(parameter_s,'r',mode='list')
2090 2090 fname,ranges = args[0], args[1:]
2091 2091 if not fname.endswith('.py'):
2092 2092 fname += '.py'
2093 2093 if os.path.isfile(fname):
2094 2094 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2095 2095 if ans.lower() not in ['y','yes']:
2096 2096 print 'Operation cancelled.'
2097 2097 return
2098 2098 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2099 2099 f = file(fname,'w')
2100 2100 f.write(cmds)
2101 2101 f.close()
2102 2102 print 'The following commands were written to file `%s`:' % fname
2103 2103 print cmds
2104 2104
2105 2105 def _edit_macro(self,mname,macro):
2106 2106 """open an editor with the macro data in a file"""
2107 2107 filename = self.shell.mktempfile(macro.value)
2108 2108 self.shell.hooks.editor(filename)
2109 2109
2110 2110 # and make a new macro object, to replace the old one
2111 2111 mfile = open(filename)
2112 2112 mvalue = mfile.read()
2113 2113 mfile.close()
2114 2114 self.shell.user_ns[mname] = Macro(mvalue)
2115 2115
2116 2116 def magic_ed(self,parameter_s=''):
2117 2117 """Alias to %edit."""
2118 2118 return self.magic_edit(parameter_s)
2119 2119
2120 2120 @testdec.skip_doctest
2121 2121 def magic_edit(self,parameter_s='',last_call=['','']):
2122 2122 """Bring up an editor and execute the resulting code.
2123 2123
2124 2124 Usage:
2125 2125 %edit [options] [args]
2126 2126
2127 2127 %edit runs IPython's editor hook. The default version of this hook is
2128 2128 set to call the __IPYTHON__.rc.editor command. This is read from your
2129 2129 environment variable $EDITOR. If this isn't found, it will default to
2130 2130 vi under Linux/Unix and to notepad under Windows. See the end of this
2131 2131 docstring for how to change the editor hook.
2132 2132
2133 2133 You can also set the value of this editor via the command line option
2134 2134 '-editor' or in your ipythonrc file. This is useful if you wish to use
2135 2135 specifically for IPython an editor different from your typical default
2136 2136 (and for Windows users who typically don't set environment variables).
2137 2137
2138 2138 This command allows you to conveniently edit multi-line code right in
2139 2139 your IPython session.
2140 2140
2141 2141 If called without arguments, %edit opens up an empty editor with a
2142 2142 temporary file and will execute the contents of this file when you
2143 2143 close it (don't forget to save it!).
2144 2144
2145 2145
2146 2146 Options:
2147 2147
2148 2148 -n <number>: open the editor at a specified line number. By default,
2149 2149 the IPython editor hook uses the unix syntax 'editor +N filename', but
2150 2150 you can configure this by providing your own modified hook if your
2151 2151 favorite editor supports line-number specifications with a different
2152 2152 syntax.
2153 2153
2154 2154 -p: this will call the editor with the same data as the previous time
2155 2155 it was used, regardless of how long ago (in your current session) it
2156 2156 was.
2157 2157
2158 2158 -r: use 'raw' input. This option only applies to input taken from the
2159 2159 user's history. By default, the 'processed' history is used, so that
2160 2160 magics are loaded in their transformed version to valid Python. If
2161 2161 this option is given, the raw input as typed as the command line is
2162 2162 used instead. When you exit the editor, it will be executed by
2163 2163 IPython's own processor.
2164 2164
2165 2165 -x: do not execute the edited code immediately upon exit. This is
2166 2166 mainly useful if you are editing programs which need to be called with
2167 2167 command line arguments, which you can then do using %run.
2168 2168
2169 2169
2170 2170 Arguments:
2171 2171
2172 2172 If arguments are given, the following possibilites exist:
2173 2173
2174 2174 - The arguments are numbers or pairs of colon-separated numbers (like
2175 2175 1 4:8 9). These are interpreted as lines of previous input to be
2176 2176 loaded into the editor. The syntax is the same of the %macro command.
2177 2177
2178 2178 - If the argument doesn't start with a number, it is evaluated as a
2179 2179 variable and its contents loaded into the editor. You can thus edit
2180 2180 any string which contains python code (including the result of
2181 2181 previous edits).
2182 2182
2183 2183 - If the argument is the name of an object (other than a string),
2184 2184 IPython will try to locate the file where it was defined and open the
2185 2185 editor at the point where it is defined. You can use `%edit function`
2186 2186 to load an editor exactly at the point where 'function' is defined,
2187 2187 edit it and have the file be executed automatically.
2188 2188
2189 2189 If the object is a macro (see %macro for details), this opens up your
2190 2190 specified editor with a temporary file containing the macro's data.
2191 2191 Upon exit, the macro is reloaded with the contents of the file.
2192 2192
2193 2193 Note: opening at an exact line is only supported under Unix, and some
2194 2194 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2195 2195 '+NUMBER' parameter necessary for this feature. Good editors like
2196 2196 (X)Emacs, vi, jed, pico and joe all do.
2197 2197
2198 2198 - If the argument is not found as a variable, IPython will look for a
2199 2199 file with that name (adding .py if necessary) and load it into the
2200 2200 editor. It will execute its contents with execfile() when you exit,
2201 2201 loading any code in the file into your interactive namespace.
2202 2202
2203 2203 After executing your code, %edit will return as output the code you
2204 2204 typed in the editor (except when it was an existing file). This way
2205 2205 you can reload the code in further invocations of %edit as a variable,
2206 2206 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2207 2207 the output.
2208 2208
2209 2209 Note that %edit is also available through the alias %ed.
2210 2210
2211 2211 This is an example of creating a simple function inside the editor and
2212 2212 then modifying it. First, start up the editor:
2213 2213
2214 2214 In [1]: ed
2215 2215 Editing... done. Executing edited code...
2216 2216 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2217 2217
2218 2218 We can then call the function foo():
2219 2219
2220 2220 In [2]: foo()
2221 2221 foo() was defined in an editing session
2222 2222
2223 2223 Now we edit foo. IPython automatically loads the editor with the
2224 2224 (temporary) file where foo() was previously defined:
2225 2225
2226 2226 In [3]: ed foo
2227 2227 Editing... done. Executing edited code...
2228 2228
2229 2229 And if we call foo() again we get the modified version:
2230 2230
2231 2231 In [4]: foo()
2232 2232 foo() has now been changed!
2233 2233
2234 2234 Here is an example of how to edit a code snippet successive
2235 2235 times. First we call the editor:
2236 2236
2237 2237 In [5]: ed
2238 2238 Editing... done. Executing edited code...
2239 2239 hello
2240 2240 Out[5]: "print 'hello'n"
2241 2241
2242 2242 Now we call it again with the previous output (stored in _):
2243 2243
2244 2244 In [6]: ed _
2245 2245 Editing... done. Executing edited code...
2246 2246 hello world
2247 2247 Out[6]: "print 'hello world'n"
2248 2248
2249 2249 Now we call it with the output #8 (stored in _8, also as Out[8]):
2250 2250
2251 2251 In [7]: ed _8
2252 2252 Editing... done. Executing edited code...
2253 2253 hello again
2254 2254 Out[7]: "print 'hello again'n"
2255 2255
2256 2256
2257 2257 Changing the default editor hook:
2258 2258
2259 2259 If you wish to write your own editor hook, you can put it in a
2260 2260 configuration file which you load at startup time. The default hook
2261 2261 is defined in the IPython.core.hooks module, and you can use that as a
2262 2262 starting example for further modifications. That file also has
2263 2263 general instructions on how to set a new hook for use once you've
2264 2264 defined it."""
2265 2265
2266 2266 # FIXME: This function has become a convoluted mess. It needs a
2267 2267 # ground-up rewrite with clean, simple logic.
2268 2268
2269 2269 def make_filename(arg):
2270 2270 "Make a filename from the given args"
2271 2271 try:
2272 2272 filename = get_py_filename(arg)
2273 2273 except IOError:
2274 2274 if args.endswith('.py'):
2275 2275 filename = arg
2276 2276 else:
2277 2277 filename = None
2278 2278 return filename
2279 2279
2280 2280 # custom exceptions
2281 2281 class DataIsObject(Exception): pass
2282 2282
2283 2283 opts,args = self.parse_options(parameter_s,'prxn:')
2284 2284 # Set a few locals from the options for convenience:
2285 2285 opts_p = opts.has_key('p')
2286 2286 opts_r = opts.has_key('r')
2287 2287
2288 2288 # Default line number value
2289 2289 lineno = opts.get('n',None)
2290 2290
2291 2291 if opts_p:
2292 2292 args = '_%s' % last_call[0]
2293 2293 if not self.shell.user_ns.has_key(args):
2294 2294 args = last_call[1]
2295 2295
2296 2296 # use last_call to remember the state of the previous call, but don't
2297 2297 # let it be clobbered by successive '-p' calls.
2298 2298 try:
2299 2299 last_call[0] = self.shell.outputcache.prompt_count
2300 2300 if not opts_p:
2301 2301 last_call[1] = parameter_s
2302 2302 except:
2303 2303 pass
2304 2304
2305 2305 # by default this is done with temp files, except when the given
2306 2306 # arg is a filename
2307 2307 use_temp = 1
2308 2308
2309 2309 if re.match(r'\d',args):
2310 2310 # Mode where user specifies ranges of lines, like in %macro.
2311 2311 # This means that you can't edit files whose names begin with
2312 2312 # numbers this way. Tough.
2313 2313 ranges = args.split()
2314 2314 data = ''.join(self.extract_input_slices(ranges,opts_r))
2315 2315 elif args.endswith('.py'):
2316 2316 filename = make_filename(args)
2317 2317 data = ''
2318 2318 use_temp = 0
2319 2319 elif args:
2320 2320 try:
2321 2321 # Load the parameter given as a variable. If not a string,
2322 2322 # process it as an object instead (below)
2323 2323
2324 2324 #print '*** args',args,'type',type(args) # dbg
2325 2325 data = eval(args,self.shell.user_ns)
2326 2326 if not type(data) in StringTypes:
2327 2327 raise DataIsObject
2328 2328
2329 2329 except (NameError,SyntaxError):
2330 2330 # given argument is not a variable, try as a filename
2331 2331 filename = make_filename(args)
2332 2332 if filename is None:
2333 2333 warn("Argument given (%s) can't be found as a variable "
2334 2334 "or as a filename." % args)
2335 2335 return
2336 2336
2337 2337 data = ''
2338 2338 use_temp = 0
2339 2339 except DataIsObject:
2340 2340
2341 2341 # macros have a special edit function
2342 2342 if isinstance(data,Macro):
2343 2343 self._edit_macro(args,data)
2344 2344 return
2345 2345
2346 2346 # For objects, try to edit the file where they are defined
2347 2347 try:
2348 2348 filename = inspect.getabsfile(data)
2349 2349 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2350 2350 # class created by %edit? Try to find source
2351 2351 # by looking for method definitions instead, the
2352 2352 # __module__ in those classes is FakeModule.
2353 2353 attrs = [getattr(data, aname) for aname in dir(data)]
2354 2354 for attr in attrs:
2355 2355 if not inspect.ismethod(attr):
2356 2356 continue
2357 2357 filename = inspect.getabsfile(attr)
2358 2358 if filename and 'fakemodule' not in filename.lower():
2359 2359 # change the attribute to be the edit target instead
2360 2360 data = attr
2361 2361 break
2362 2362
2363 2363 datafile = 1
2364 2364 except TypeError:
2365 2365 filename = make_filename(args)
2366 2366 datafile = 1
2367 2367 warn('Could not find file where `%s` is defined.\n'
2368 2368 'Opening a file named `%s`' % (args,filename))
2369 2369 # Now, make sure we can actually read the source (if it was in
2370 2370 # a temp file it's gone by now).
2371 2371 if datafile:
2372 2372 try:
2373 2373 if lineno is None:
2374 2374 lineno = inspect.getsourcelines(data)[1]
2375 2375 except IOError:
2376 2376 filename = make_filename(args)
2377 2377 if filename is None:
2378 2378 warn('The file `%s` where `%s` was defined cannot '
2379 2379 'be read.' % (filename,data))
2380 2380 return
2381 2381 use_temp = 0
2382 2382 else:
2383 2383 data = ''
2384 2384
2385 2385 if use_temp:
2386 2386 filename = self.shell.mktempfile(data)
2387 2387 print 'IPython will make a temporary file named:',filename
2388 2388
2389 2389 # do actual editing here
2390 2390 print 'Editing...',
2391 2391 sys.stdout.flush()
2392 2392 try:
2393 2393 self.shell.hooks.editor(filename,lineno)
2394 2394 except ipapi.TryNext:
2395 2395 warn('Could not open editor')
2396 2396 return
2397 2397
2398 2398 # XXX TODO: should this be generalized for all string vars?
2399 2399 # For now, this is special-cased to blocks created by cpaste
2400 2400 if args.strip() == 'pasted_block':
2401 2401 self.shell.user_ns['pasted_block'] = file_read(filename)
2402 2402
2403 2403 if opts.has_key('x'): # -x prevents actual execution
2404 2404 print
2405 2405 else:
2406 2406 print 'done. Executing edited code...'
2407 2407 if opts_r:
2408 2408 self.shell.runlines(file_read(filename))
2409 2409 else:
2410 2410 self.shell.safe_execfile(filename,self.shell.user_ns,
2411 2411 self.shell.user_ns)
2412 2412
2413 2413
2414 2414 if use_temp:
2415 2415 try:
2416 2416 return open(filename).read()
2417 2417 except IOError,msg:
2418 2418 if msg.filename == filename:
2419 2419 warn('File not found. Did you forget to save?')
2420 2420 return
2421 2421 else:
2422 2422 self.shell.showtraceback()
2423 2423
2424 2424 def magic_xmode(self,parameter_s = ''):
2425 2425 """Switch modes for the exception handlers.
2426 2426
2427 2427 Valid modes: Plain, Context and Verbose.
2428 2428
2429 2429 If called without arguments, acts as a toggle."""
2430 2430
2431 2431 def xmode_switch_err(name):
2432 2432 warn('Error changing %s exception modes.\n%s' %
2433 2433 (name,sys.exc_info()[1]))
2434 2434
2435 2435 shell = self.shell
2436 2436 new_mode = parameter_s.strip().capitalize()
2437 2437 try:
2438 2438 shell.InteractiveTB.set_mode(mode=new_mode)
2439 2439 print 'Exception reporting mode:',shell.InteractiveTB.mode
2440 2440 except:
2441 2441 xmode_switch_err('user')
2442 2442
2443 2443 # threaded shells use a special handler in sys.excepthook
2444 2444 if shell.isthreaded:
2445 2445 try:
2446 2446 shell.sys_excepthook.set_mode(mode=new_mode)
2447 2447 except:
2448 2448 xmode_switch_err('threaded')
2449 2449
2450 2450 def magic_colors(self,parameter_s = ''):
2451 2451 """Switch color scheme for prompts, info system and exception handlers.
2452 2452
2453 2453 Currently implemented schemes: NoColor, Linux, LightBG.
2454 2454
2455 2455 Color scheme names are not case-sensitive."""
2456 2456
2457 2457 def color_switch_err(name):
2458 2458 warn('Error changing %s color schemes.\n%s' %
2459 2459 (name,sys.exc_info()[1]))
2460 2460
2461 2461
2462 2462 new_scheme = parameter_s.strip()
2463 2463 if not new_scheme:
2464 2464 raise UsageError(
2465 2465 "%colors: you must specify a color scheme. See '%colors?'")
2466 2466 return
2467 2467 # local shortcut
2468 2468 shell = self.shell
2469 2469
2470 2470 import IPython.utils.rlineimpl as readline
2471 2471
2472 2472 if not readline.have_readline and sys.platform == "win32":
2473 2473 msg = """\
2474 2474 Proper color support under MS Windows requires the pyreadline library.
2475 2475 You can find it at:
2476 2476 http://ipython.scipy.org/moin/PyReadline/Intro
2477 2477 Gary's readline needs the ctypes module, from:
2478 2478 http://starship.python.net/crew/theller/ctypes
2479 2479 (Note that ctypes is already part of Python versions 2.5 and newer).
2480 2480
2481 2481 Defaulting color scheme to 'NoColor'"""
2482 2482 new_scheme = 'NoColor'
2483 2483 warn(msg)
2484 2484
2485 2485 # readline option is 0
2486 2486 if not shell.has_readline:
2487 2487 new_scheme = 'NoColor'
2488 2488
2489 2489 # Set prompt colors
2490 2490 try:
2491 2491 shell.outputcache.set_colors(new_scheme)
2492 2492 except:
2493 2493 color_switch_err('prompt')
2494 2494 else:
2495 2495 shell.rc.colors = \
2496 2496 shell.outputcache.color_table.active_scheme_name
2497 2497 # Set exception colors
2498 2498 try:
2499 2499 shell.InteractiveTB.set_colors(scheme = new_scheme)
2500 2500 shell.SyntaxTB.set_colors(scheme = new_scheme)
2501 2501 except:
2502 2502 color_switch_err('exception')
2503 2503
2504 2504 # threaded shells use a verbose traceback in sys.excepthook
2505 2505 if shell.isthreaded:
2506 2506 try:
2507 2507 shell.sys_excepthook.set_colors(scheme=new_scheme)
2508 2508 except:
2509 2509 color_switch_err('system exception handler')
2510 2510
2511 2511 # Set info (for 'object?') colors
2512 2512 if shell.rc.color_info:
2513 2513 try:
2514 2514 shell.inspector.set_active_scheme(new_scheme)
2515 2515 except:
2516 2516 color_switch_err('object inspector')
2517 2517 else:
2518 2518 shell.inspector.set_active_scheme('NoColor')
2519 2519
2520 2520 def magic_color_info(self,parameter_s = ''):
2521 2521 """Toggle color_info.
2522 2522
2523 2523 The color_info configuration parameter controls whether colors are
2524 2524 used for displaying object details (by things like %psource, %pfile or
2525 2525 the '?' system). This function toggles this value with each call.
2526 2526
2527 2527 Note that unless you have a fairly recent pager (less works better
2528 2528 than more) in your system, using colored object information displays
2529 2529 will not work properly. Test it and see."""
2530 2530
2531 2531 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2532 2532 self.magic_colors(self.shell.rc.colors)
2533 2533 print 'Object introspection functions have now coloring:',
2534 2534 print ['OFF','ON'][self.shell.rc.color_info]
2535 2535
2536 2536 def magic_Pprint(self, parameter_s=''):
2537 2537 """Toggle pretty printing on/off."""
2538 2538
2539 2539 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2540 2540 print 'Pretty printing has been turned', \
2541 2541 ['OFF','ON'][self.shell.rc.pprint]
2542 2542
2543 2543 def magic_exit(self, parameter_s=''):
2544 2544 """Exit IPython, confirming if configured to do so.
2545 2545
2546 2546 You can configure whether IPython asks for confirmation upon exit by
2547 2547 setting the confirm_exit flag in the ipythonrc file."""
2548 2548
2549 2549 self.shell.exit()
2550 2550
2551 2551 def magic_quit(self, parameter_s=''):
2552 2552 """Exit IPython, confirming if configured to do so (like %exit)"""
2553 2553
2554 2554 self.shell.exit()
2555 2555
2556 2556 def magic_Exit(self, parameter_s=''):
2557 2557 """Exit IPython without confirmation."""
2558 2558
2559 2559 self.shell.ask_exit()
2560 2560
2561 2561 #......................................................................
2562 2562 # Functions to implement unix shell-type things
2563 2563
2564 2564 @testdec.skip_doctest
2565 2565 def magic_alias(self, parameter_s = ''):
2566 2566 """Define an alias for a system command.
2567 2567
2568 2568 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2569 2569
2570 2570 Then, typing 'alias_name params' will execute the system command 'cmd
2571 2571 params' (from your underlying operating system).
2572 2572
2573 2573 Aliases have lower precedence than magic functions and Python normal
2574 2574 variables, so if 'foo' is both a Python variable and an alias, the
2575 2575 alias can not be executed until 'del foo' removes the Python variable.
2576 2576
2577 2577 You can use the %l specifier in an alias definition to represent the
2578 2578 whole line when the alias is called. For example:
2579 2579
2580 2580 In [2]: alias all echo "Input in brackets: <%l>"
2581 2581 In [3]: all hello world
2582 2582 Input in brackets: <hello world>
2583 2583
2584 2584 You can also define aliases with parameters using %s specifiers (one
2585 2585 per parameter):
2586 2586
2587 2587 In [1]: alias parts echo first %s second %s
2588 2588 In [2]: %parts A B
2589 2589 first A second B
2590 2590 In [3]: %parts A
2591 2591 Incorrect number of arguments: 2 expected.
2592 2592 parts is an alias to: 'echo first %s second %s'
2593 2593
2594 2594 Note that %l and %s are mutually exclusive. You can only use one or
2595 2595 the other in your aliases.
2596 2596
2597 2597 Aliases expand Python variables just like system calls using ! or !!
2598 2598 do: all expressions prefixed with '$' get expanded. For details of
2599 2599 the semantic rules, see PEP-215:
2600 2600 http://www.python.org/peps/pep-0215.html. This is the library used by
2601 2601 IPython for variable expansion. If you want to access a true shell
2602 2602 variable, an extra $ is necessary to prevent its expansion by IPython:
2603 2603
2604 2604 In [6]: alias show echo
2605 2605 In [7]: PATH='A Python string'
2606 2606 In [8]: show $PATH
2607 2607 A Python string
2608 2608 In [9]: show $$PATH
2609 2609 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2610 2610
2611 2611 You can use the alias facility to acess all of $PATH. See the %rehash
2612 2612 and %rehashx functions, which automatically create aliases for the
2613 2613 contents of your $PATH.
2614 2614
2615 2615 If called with no parameters, %alias prints the current alias table."""
2616 2616
2617 2617 par = parameter_s.strip()
2618 2618 if not par:
2619 2619 stored = self.db.get('stored_aliases', {} )
2620 2620 atab = self.shell.alias_table
2621 2621 aliases = atab.keys()
2622 2622 aliases.sort()
2623 2623 res = []
2624 2624 showlast = []
2625 2625 for alias in aliases:
2626 2626 special = False
2627 2627 try:
2628 2628 tgt = atab[alias][1]
2629 2629 except (TypeError, AttributeError):
2630 2630 # unsubscriptable? probably a callable
2631 2631 tgt = atab[alias]
2632 2632 special = True
2633 2633 # 'interesting' aliases
2634 2634 if (alias in stored or
2635 2635 special or
2636 2636 alias.lower() != os.path.splitext(tgt)[0].lower() or
2637 2637 ' ' in tgt):
2638 2638 showlast.append((alias, tgt))
2639 2639 else:
2640 2640 res.append((alias, tgt ))
2641 2641
2642 2642 # show most interesting aliases last
2643 2643 res.extend(showlast)
2644 2644 print "Total number of aliases:",len(aliases)
2645 2645 return res
2646 2646 try:
2647 2647 alias,cmd = par.split(None,1)
2648 2648 except:
2649 2649 print oinspect.getdoc(self.magic_alias)
2650 2650 else:
2651 2651 nargs = cmd.count('%s')
2652 2652 if nargs>0 and cmd.find('%l')>=0:
2653 2653 error('The %s and %l specifiers are mutually exclusive '
2654 2654 'in alias definitions.')
2655 2655 else: # all looks OK
2656 2656 self.shell.alias_table[alias] = (nargs,cmd)
2657 2657 self.shell.alias_table_validate(verbose=0)
2658 2658 # end magic_alias
2659 2659
2660 2660 def magic_unalias(self, parameter_s = ''):
2661 2661 """Remove an alias"""
2662 2662
2663 2663 aname = parameter_s.strip()
2664 2664 if aname in self.shell.alias_table:
2665 2665 del self.shell.alias_table[aname]
2666 2666 stored = self.db.get('stored_aliases', {} )
2667 2667 if aname in stored:
2668 2668 print "Removing %stored alias",aname
2669 2669 del stored[aname]
2670 2670 self.db['stored_aliases'] = stored
2671 2671
2672 2672
2673 2673 def magic_rehashx(self, parameter_s = ''):
2674 2674 """Update the alias table with all executable files in $PATH.
2675 2675
2676 2676 This version explicitly checks that every entry in $PATH is a file
2677 2677 with execute access (os.X_OK), so it is much slower than %rehash.
2678 2678
2679 2679 Under Windows, it checks executability as a match agains a
2680 2680 '|'-separated string of extensions, stored in the IPython config
2681 2681 variable win_exec_ext. This defaults to 'exe|com|bat'.
2682 2682
2683 2683 This function also resets the root module cache of module completer,
2684 2684 used on slow filesystems.
2685 2685 """
2686 2686
2687 2687
2688 2688 ip = self.api
2689 2689
2690 2690 # for the benefit of module completer in ipy_completers.py
2691 2691 del ip.db['rootmodules']
2692 2692
2693 2693 path = [os.path.abspath(os.path.expanduser(p)) for p in
2694 2694 os.environ.get('PATH','').split(os.pathsep)]
2695 2695 path = filter(os.path.isdir,path)
2696 2696
2697 2697 alias_table = self.shell.alias_table
2698 2698 syscmdlist = []
2699 2699 if os.name == 'posix':
2700 2700 isexec = lambda fname:os.path.isfile(fname) and \
2701 2701 os.access(fname,os.X_OK)
2702 2702 else:
2703 2703
2704 2704 try:
2705 2705 winext = os.environ['pathext'].replace(';','|').replace('.','')
2706 2706 except KeyError:
2707 2707 winext = 'exe|com|bat|py'
2708 2708 if 'py' not in winext:
2709 2709 winext += '|py'
2710 2710 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2711 2711 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2712 2712 savedir = os.getcwd()
2713 2713 try:
2714 2714 # write the whole loop for posix/Windows so we don't have an if in
2715 2715 # the innermost part
2716 2716 if os.name == 'posix':
2717 2717 for pdir in path:
2718 2718 os.chdir(pdir)
2719 2719 for ff in os.listdir(pdir):
2720 2720 if isexec(ff) and ff not in self.shell.no_alias:
2721 2721 # each entry in the alias table must be (N,name),
2722 2722 # where N is the number of positional arguments of the
2723 2723 # alias.
2724 2724 # Dots will be removed from alias names, since ipython
2725 2725 # assumes names with dots to be python code
2726 2726 alias_table[ff.replace('.','')] = (0,ff)
2727 2727 syscmdlist.append(ff)
2728 2728 else:
2729 2729 for pdir in path:
2730 2730 os.chdir(pdir)
2731 2731 for ff in os.listdir(pdir):
2732 2732 base, ext = os.path.splitext(ff)
2733 2733 if isexec(ff) and base.lower() not in self.shell.no_alias:
2734 2734 if ext.lower() == '.exe':
2735 2735 ff = base
2736 2736 alias_table[base.lower().replace('.','')] = (0,ff)
2737 2737 syscmdlist.append(ff)
2738 2738 # Make sure the alias table doesn't contain keywords or builtins
2739 2739 self.shell.alias_table_validate()
2740 2740 # Call again init_auto_alias() so we get 'rm -i' and other
2741 2741 # modified aliases since %rehashx will probably clobber them
2742 2742
2743 2743 # no, we don't want them. if %rehashx clobbers them, good,
2744 2744 # we'll probably get better versions
2745 2745 # self.shell.init_auto_alias()
2746 2746 db = ip.db
2747 2747 db['syscmdlist'] = syscmdlist
2748 2748 finally:
2749 2749 os.chdir(savedir)
2750 2750
2751 2751 def magic_pwd(self, parameter_s = ''):
2752 2752 """Return the current working directory path."""
2753 2753 return os.getcwd()
2754 2754
2755 2755 def magic_cd(self, parameter_s=''):
2756 2756 """Change the current working directory.
2757 2757
2758 2758 This command automatically maintains an internal list of directories
2759 2759 you visit during your IPython session, in the variable _dh. The
2760 2760 command %dhist shows this history nicely formatted. You can also
2761 2761 do 'cd -<tab>' to see directory history conveniently.
2762 2762
2763 2763 Usage:
2764 2764
2765 2765 cd 'dir': changes to directory 'dir'.
2766 2766
2767 2767 cd -: changes to the last visited directory.
2768 2768
2769 2769 cd -<n>: changes to the n-th directory in the directory history.
2770 2770
2771 2771 cd --foo: change to directory that matches 'foo' in history
2772 2772
2773 2773 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2774 2774 (note: cd <bookmark_name> is enough if there is no
2775 2775 directory <bookmark_name>, but a bookmark with the name exists.)
2776 2776 'cd -b <tab>' allows you to tab-complete bookmark names.
2777 2777
2778 2778 Options:
2779 2779
2780 2780 -q: quiet. Do not print the working directory after the cd command is
2781 2781 executed. By default IPython's cd command does print this directory,
2782 2782 since the default prompts do not display path information.
2783 2783
2784 2784 Note that !cd doesn't work for this purpose because the shell where
2785 2785 !command runs is immediately discarded after executing 'command'."""
2786 2786
2787 2787 parameter_s = parameter_s.strip()
2788 2788 #bkms = self.shell.persist.get("bookmarks",{})
2789 2789
2790 2790 oldcwd = os.getcwd()
2791 2791 numcd = re.match(r'(-)(\d+)$',parameter_s)
2792 2792 # jump in directory history by number
2793 2793 if numcd:
2794 2794 nn = int(numcd.group(2))
2795 2795 try:
2796 2796 ps = self.shell.user_ns['_dh'][nn]
2797 2797 except IndexError:
2798 2798 print 'The requested directory does not exist in history.'
2799 2799 return
2800 2800 else:
2801 2801 opts = {}
2802 2802 elif parameter_s.startswith('--'):
2803 2803 ps = None
2804 2804 fallback = None
2805 2805 pat = parameter_s[2:]
2806 2806 dh = self.shell.user_ns['_dh']
2807 2807 # first search only by basename (last component)
2808 2808 for ent in reversed(dh):
2809 2809 if pat in os.path.basename(ent) and os.path.isdir(ent):
2810 2810 ps = ent
2811 2811 break
2812 2812
2813 2813 if fallback is None and pat in ent and os.path.isdir(ent):
2814 2814 fallback = ent
2815 2815
2816 2816 # if we have no last part match, pick the first full path match
2817 2817 if ps is None:
2818 2818 ps = fallback
2819 2819
2820 2820 if ps is None:
2821 2821 print "No matching entry in directory history"
2822 2822 return
2823 2823 else:
2824 2824 opts = {}
2825 2825
2826 2826
2827 2827 else:
2828 2828 #turn all non-space-escaping backslashes to slashes,
2829 2829 # for c:\windows\directory\names\
2830 2830 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2831 2831 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2832 2832 # jump to previous
2833 2833 if ps == '-':
2834 2834 try:
2835 2835 ps = self.shell.user_ns['_dh'][-2]
2836 2836 except IndexError:
2837 2837 raise UsageError('%cd -: No previous directory to change to.')
2838 2838 # jump to bookmark if needed
2839 2839 else:
2840 2840 if not os.path.isdir(ps) or opts.has_key('b'):
2841 2841 bkms = self.db.get('bookmarks', {})
2842 2842
2843 2843 if bkms.has_key(ps):
2844 2844 target = bkms[ps]
2845 2845 print '(bookmark:%s) -> %s' % (ps,target)
2846 2846 ps = target
2847 2847 else:
2848 2848 if opts.has_key('b'):
2849 2849 raise UsageError("Bookmark '%s' not found. "
2850 2850 "Use '%%bookmark -l' to see your bookmarks." % ps)
2851 2851
2852 2852 # at this point ps should point to the target dir
2853 2853 if ps:
2854 2854 try:
2855 2855 os.chdir(os.path.expanduser(ps))
2856 2856 if self.shell.rc.term_title:
2857 2857 #print 'set term title:',self.shell.rc.term_title # dbg
2858 2858 platutils.set_term_title('IPy ' + abbrev_cwd())
2859 2859 except OSError:
2860 2860 print sys.exc_info()[1]
2861 2861 else:
2862 2862 cwd = os.getcwd()
2863 2863 dhist = self.shell.user_ns['_dh']
2864 2864 if oldcwd != cwd:
2865 2865 dhist.append(cwd)
2866 2866 self.db['dhist'] = compress_dhist(dhist)[-100:]
2867 2867
2868 2868 else:
2869 2869 os.chdir(self.shell.home_dir)
2870 2870 if self.shell.rc.term_title:
2871 2871 platutils.set_term_title("IPy ~")
2872 2872 cwd = os.getcwd()
2873 2873 dhist = self.shell.user_ns['_dh']
2874 2874
2875 2875 if oldcwd != cwd:
2876 2876 dhist.append(cwd)
2877 2877 self.db['dhist'] = compress_dhist(dhist)[-100:]
2878 2878 if not 'q' in opts and self.shell.user_ns['_dh']:
2879 2879 print self.shell.user_ns['_dh'][-1]
2880 2880
2881 2881
2882 2882 def magic_env(self, parameter_s=''):
2883 2883 """List environment variables."""
2884 2884
2885 2885 return os.environ.data
2886 2886
2887 2887 def magic_pushd(self, parameter_s=''):
2888 2888 """Place the current dir on stack and change directory.
2889 2889
2890 2890 Usage:\\
2891 2891 %pushd ['dirname']
2892 2892 """
2893 2893
2894 2894 dir_s = self.shell.dir_stack
2895 2895 tgt = os.path.expanduser(parameter_s)
2896 2896 cwd = os.getcwd().replace(self.home_dir,'~')
2897 2897 if tgt:
2898 2898 self.magic_cd(parameter_s)
2899 2899 dir_s.insert(0,cwd)
2900 2900 return self.magic_dirs()
2901 2901
2902 2902 def magic_popd(self, parameter_s=''):
2903 2903 """Change to directory popped off the top of the stack.
2904 2904 """
2905 2905 if not self.shell.dir_stack:
2906 2906 raise UsageError("%popd on empty stack")
2907 2907 top = self.shell.dir_stack.pop(0)
2908 2908 self.magic_cd(top)
2909 2909 print "popd ->",top
2910 2910
2911 2911 def magic_dirs(self, parameter_s=''):
2912 2912 """Return the current directory stack."""
2913 2913
2914 2914 return self.shell.dir_stack
2915 2915
2916 2916 def magic_dhist(self, parameter_s=''):
2917 2917 """Print your history of visited directories.
2918 2918
2919 2919 %dhist -> print full history\\
2920 2920 %dhist n -> print last n entries only\\
2921 2921 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2922 2922
2923 2923 This history is automatically maintained by the %cd command, and
2924 2924 always available as the global list variable _dh. You can use %cd -<n>
2925 2925 to go to directory number <n>.
2926 2926
2927 2927 Note that most of time, you should view directory history by entering
2928 2928 cd -<TAB>.
2929 2929
2930 2930 """
2931 2931
2932 2932 dh = self.shell.user_ns['_dh']
2933 2933 if parameter_s:
2934 2934 try:
2935 2935 args = map(int,parameter_s.split())
2936 2936 except:
2937 2937 self.arg_err(Magic.magic_dhist)
2938 2938 return
2939 2939 if len(args) == 1:
2940 2940 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2941 2941 elif len(args) == 2:
2942 2942 ini,fin = args
2943 2943 else:
2944 2944 self.arg_err(Magic.magic_dhist)
2945 2945 return
2946 2946 else:
2947 2947 ini,fin = 0,len(dh)
2948 2948 nlprint(dh,
2949 2949 header = 'Directory history (kept in _dh)',
2950 2950 start=ini,stop=fin)
2951 2951
2952 2952 @testdec.skip_doctest
2953 2953 def magic_sc(self, parameter_s=''):
2954 2954 """Shell capture - execute a shell command and capture its output.
2955 2955
2956 2956 DEPRECATED. Suboptimal, retained for backwards compatibility.
2957 2957
2958 2958 You should use the form 'var = !command' instead. Example:
2959 2959
2960 2960 "%sc -l myfiles = ls ~" should now be written as
2961 2961
2962 2962 "myfiles = !ls ~"
2963 2963
2964 2964 myfiles.s, myfiles.l and myfiles.n still apply as documented
2965 2965 below.
2966 2966
2967 2967 --
2968 2968 %sc [options] varname=command
2969 2969
2970 2970 IPython will run the given command using commands.getoutput(), and
2971 2971 will then update the user's interactive namespace with a variable
2972 2972 called varname, containing the value of the call. Your command can
2973 2973 contain shell wildcards, pipes, etc.
2974 2974
2975 2975 The '=' sign in the syntax is mandatory, and the variable name you
2976 2976 supply must follow Python's standard conventions for valid names.
2977 2977
2978 2978 (A special format without variable name exists for internal use)
2979 2979
2980 2980 Options:
2981 2981
2982 2982 -l: list output. Split the output on newlines into a list before
2983 2983 assigning it to the given variable. By default the output is stored
2984 2984 as a single string.
2985 2985
2986 2986 -v: verbose. Print the contents of the variable.
2987 2987
2988 2988 In most cases you should not need to split as a list, because the
2989 2989 returned value is a special type of string which can automatically
2990 2990 provide its contents either as a list (split on newlines) or as a
2991 2991 space-separated string. These are convenient, respectively, either
2992 2992 for sequential processing or to be passed to a shell command.
2993 2993
2994 2994 For example:
2995 2995
2996 2996 # all-random
2997 2997
2998 2998 # Capture into variable a
2999 2999 In [1]: sc a=ls *py
3000 3000
3001 3001 # a is a string with embedded newlines
3002 3002 In [2]: a
3003 3003 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3004 3004
3005 3005 # which can be seen as a list:
3006 3006 In [3]: a.l
3007 3007 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3008 3008
3009 3009 # or as a whitespace-separated string:
3010 3010 In [4]: a.s
3011 3011 Out[4]: 'setup.py win32_manual_post_install.py'
3012 3012
3013 3013 # a.s is useful to pass as a single command line:
3014 3014 In [5]: !wc -l $a.s
3015 3015 146 setup.py
3016 3016 130 win32_manual_post_install.py
3017 3017 276 total
3018 3018
3019 3019 # while the list form is useful to loop over:
3020 3020 In [6]: for f in a.l:
3021 3021 ...: !wc -l $f
3022 3022 ...:
3023 3023 146 setup.py
3024 3024 130 win32_manual_post_install.py
3025 3025
3026 3026 Similiarly, the lists returned by the -l option are also special, in
3027 3027 the sense that you can equally invoke the .s attribute on them to
3028 3028 automatically get a whitespace-separated string from their contents:
3029 3029
3030 3030 In [7]: sc -l b=ls *py
3031 3031
3032 3032 In [8]: b
3033 3033 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3034 3034
3035 3035 In [9]: b.s
3036 3036 Out[9]: 'setup.py win32_manual_post_install.py'
3037 3037
3038 3038 In summary, both the lists and strings used for ouptut capture have
3039 3039 the following special attributes:
3040 3040
3041 3041 .l (or .list) : value as list.
3042 3042 .n (or .nlstr): value as newline-separated string.
3043 3043 .s (or .spstr): value as space-separated string.
3044 3044 """
3045 3045
3046 3046 opts,args = self.parse_options(parameter_s,'lv')
3047 3047 # Try to get a variable name and command to run
3048 3048 try:
3049 3049 # the variable name must be obtained from the parse_options
3050 3050 # output, which uses shlex.split to strip options out.
3051 3051 var,_ = args.split('=',1)
3052 3052 var = var.strip()
3053 3053 # But the the command has to be extracted from the original input
3054 3054 # parameter_s, not on what parse_options returns, to avoid the
3055 3055 # quote stripping which shlex.split performs on it.
3056 3056 _,cmd = parameter_s.split('=',1)
3057 3057 except ValueError:
3058 3058 var,cmd = '',''
3059 3059 # If all looks ok, proceed
3060 3060 out,err = self.shell.getoutputerror(cmd)
3061 3061 if err:
3062 3062 print >> Term.cerr,err
3063 3063 if opts.has_key('l'):
3064 3064 out = SList(out.split('\n'))
3065 3065 else:
3066 3066 out = LSString(out)
3067 3067 if opts.has_key('v'):
3068 3068 print '%s ==\n%s' % (var,pformat(out))
3069 3069 if var:
3070 3070 self.shell.user_ns.update({var:out})
3071 3071 else:
3072 3072 return out
3073 3073
3074 3074 def magic_sx(self, parameter_s=''):
3075 3075 """Shell execute - run a shell command and capture its output.
3076 3076
3077 3077 %sx command
3078 3078
3079 3079 IPython will run the given command using commands.getoutput(), and
3080 3080 return the result formatted as a list (split on '\\n'). Since the
3081 3081 output is _returned_, it will be stored in ipython's regular output
3082 3082 cache Out[N] and in the '_N' automatic variables.
3083 3083
3084 3084 Notes:
3085 3085
3086 3086 1) If an input line begins with '!!', then %sx is automatically
3087 3087 invoked. That is, while:
3088 3088 !ls
3089 3089 causes ipython to simply issue system('ls'), typing
3090 3090 !!ls
3091 3091 is a shorthand equivalent to:
3092 3092 %sx ls
3093 3093
3094 3094 2) %sx differs from %sc in that %sx automatically splits into a list,
3095 3095 like '%sc -l'. The reason for this is to make it as easy as possible
3096 3096 to process line-oriented shell output via further python commands.
3097 3097 %sc is meant to provide much finer control, but requires more
3098 3098 typing.
3099 3099
3100 3100 3) Just like %sc -l, this is a list with special attributes:
3101 3101
3102 3102 .l (or .list) : value as list.
3103 3103 .n (or .nlstr): value as newline-separated string.
3104 3104 .s (or .spstr): value as whitespace-separated string.
3105 3105
3106 3106 This is very useful when trying to use such lists as arguments to
3107 3107 system commands."""
3108 3108
3109 3109 if parameter_s:
3110 3110 out,err = self.shell.getoutputerror(parameter_s)
3111 3111 if err:
3112 3112 print >> Term.cerr,err
3113 3113 return SList(out.split('\n'))
3114 3114
3115 3115 def magic_bg(self, parameter_s=''):
3116 3116 """Run a job in the background, in a separate thread.
3117 3117
3118 3118 For example,
3119 3119
3120 3120 %bg myfunc(x,y,z=1)
3121 3121
3122 3122 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3123 3123 execution starts, a message will be printed indicating the job
3124 3124 number. If your job number is 5, you can use
3125 3125
3126 3126 myvar = jobs.result(5) or myvar = jobs[5].result
3127 3127
3128 3128 to assign this result to variable 'myvar'.
3129 3129
3130 3130 IPython has a job manager, accessible via the 'jobs' object. You can
3131 3131 type jobs? to get more information about it, and use jobs.<TAB> to see
3132 3132 its attributes. All attributes not starting with an underscore are
3133 3133 meant for public use.
3134 3134
3135 3135 In particular, look at the jobs.new() method, which is used to create
3136 3136 new jobs. This magic %bg function is just a convenience wrapper
3137 3137 around jobs.new(), for expression-based jobs. If you want to create a
3138 3138 new job with an explicit function object and arguments, you must call
3139 3139 jobs.new() directly.
3140 3140
3141 3141 The jobs.new docstring also describes in detail several important
3142 3142 caveats associated with a thread-based model for background job
3143 3143 execution. Type jobs.new? for details.
3144 3144
3145 3145 You can check the status of all jobs with jobs.status().
3146 3146
3147 3147 The jobs variable is set by IPython into the Python builtin namespace.
3148 3148 If you ever declare a variable named 'jobs', you will shadow this
3149 3149 name. You can either delete your global jobs variable to regain
3150 3150 access to the job manager, or make a new name and assign it manually
3151 3151 to the manager (stored in IPython's namespace). For example, to
3152 3152 assign the job manager to the Jobs name, use:
3153 3153
3154 3154 Jobs = __builtins__.jobs"""
3155 3155
3156 3156 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3157 3157
3158 3158 def magic_r(self, parameter_s=''):
3159 3159 """Repeat previous input.
3160 3160
3161 3161 Note: Consider using the more powerfull %rep instead!
3162 3162
3163 3163 If given an argument, repeats the previous command which starts with
3164 3164 the same string, otherwise it just repeats the previous input.
3165 3165
3166 3166 Shell escaped commands (with ! as first character) are not recognized
3167 3167 by this system, only pure python code and magic commands.
3168 3168 """
3169 3169
3170 3170 start = parameter_s.strip()
3171 3171 esc_magic = self.shell.ESC_MAGIC
3172 3172 # Identify magic commands even if automagic is on (which means
3173 3173 # the in-memory version is different from that typed by the user).
3174 3174 if self.shell.rc.automagic:
3175 3175 start_magic = esc_magic+start
3176 3176 else:
3177 3177 start_magic = start
3178 3178 # Look through the input history in reverse
3179 3179 for n in range(len(self.shell.input_hist)-2,0,-1):
3180 3180 input = self.shell.input_hist[n]
3181 3181 # skip plain 'r' lines so we don't recurse to infinity
3182 3182 if input != '_ip.magic("r")\n' and \
3183 3183 (input.startswith(start) or input.startswith(start_magic)):
3184 3184 #print 'match',`input` # dbg
3185 3185 print 'Executing:',input,
3186 3186 self.shell.runlines(input)
3187 3187 return
3188 3188 print 'No previous input matching `%s` found.' % start
3189 3189
3190 3190
3191 3191 def magic_bookmark(self, parameter_s=''):
3192 3192 """Manage IPython's bookmark system.
3193 3193
3194 3194 %bookmark <name> - set bookmark to current dir
3195 3195 %bookmark <name> <dir> - set bookmark to <dir>
3196 3196 %bookmark -l - list all bookmarks
3197 3197 %bookmark -d <name> - remove bookmark
3198 3198 %bookmark -r - remove all bookmarks
3199 3199
3200 3200 You can later on access a bookmarked folder with:
3201 3201 %cd -b <name>
3202 3202 or simply '%cd <name>' if there is no directory called <name> AND
3203 3203 there is such a bookmark defined.
3204 3204
3205 3205 Your bookmarks persist through IPython sessions, but they are
3206 3206 associated with each profile."""
3207 3207
3208 3208 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3209 3209 if len(args) > 2:
3210 3210 raise UsageError("%bookmark: too many arguments")
3211 3211
3212 3212 bkms = self.db.get('bookmarks',{})
3213 3213
3214 3214 if opts.has_key('d'):
3215 3215 try:
3216 3216 todel = args[0]
3217 3217 except IndexError:
3218 3218 raise UsageError(
3219 3219 "%bookmark -d: must provide a bookmark to delete")
3220 3220 else:
3221 3221 try:
3222 3222 del bkms[todel]
3223 3223 except KeyError:
3224 3224 raise UsageError(
3225 3225 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3226 3226
3227 3227 elif opts.has_key('r'):
3228 3228 bkms = {}
3229 3229 elif opts.has_key('l'):
3230 3230 bks = bkms.keys()
3231 3231 bks.sort()
3232 3232 if bks:
3233 3233 size = max(map(len,bks))
3234 3234 else:
3235 3235 size = 0
3236 3236 fmt = '%-'+str(size)+'s -> %s'
3237 3237 print 'Current bookmarks:'
3238 3238 for bk in bks:
3239 3239 print fmt % (bk,bkms[bk])
3240 3240 else:
3241 3241 if not args:
3242 3242 raise UsageError("%bookmark: You must specify the bookmark name")
3243 3243 elif len(args)==1:
3244 3244 bkms[args[0]] = os.getcwd()
3245 3245 elif len(args)==2:
3246 3246 bkms[args[0]] = args[1]
3247 3247 self.db['bookmarks'] = bkms
3248 3248
3249 3249 def magic_pycat(self, parameter_s=''):
3250 3250 """Show a syntax-highlighted file through a pager.
3251 3251
3252 3252 This magic is similar to the cat utility, but it will assume the file
3253 3253 to be Python source and will show it with syntax highlighting. """
3254 3254
3255 3255 try:
3256 3256 filename = get_py_filename(parameter_s)
3257 3257 cont = file_read(filename)
3258 3258 except IOError:
3259 3259 try:
3260 3260 cont = eval(parameter_s,self.user_ns)
3261 3261 except NameError:
3262 3262 cont = None
3263 3263 if cont is None:
3264 3264 print "Error: no such file or variable"
3265 3265 return
3266 3266
3267 3267 page(self.shell.pycolorize(cont),
3268 3268 screen_lines=self.shell.rc.screen_length)
3269 3269
3270 3270 def _rerun_pasted(self):
3271 3271 """ Rerun a previously pasted command.
3272 3272 """
3273 3273 b = self.user_ns.get('pasted_block', None)
3274 3274 if b is None:
3275 3275 raise UsageError('No previous pasted block available')
3276 3276 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3277 3277 exec b in self.user_ns
3278 3278
3279 3279 def _get_pasted_lines(self, sentinel):
3280 3280 """ Yield pasted lines until the user enters the given sentinel value.
3281 3281 """
3282 3282 from IPython.core import iplib
3283 3283 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3284 3284 while True:
3285 3285 l = iplib.raw_input_original(':')
3286 3286 if l == sentinel:
3287 3287 return
3288 3288 else:
3289 3289 yield l
3290 3290
3291 3291 def _strip_pasted_lines_for_code(self, raw_lines):
3292 3292 """ Strip non-code parts of a sequence of lines to return a block of
3293 3293 code.
3294 3294 """
3295 3295 # Regular expressions that declare text we strip from the input:
3296 3296 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3297 3297 r'^\s*(\s?>)+', # Python input prompt
3298 3298 r'^\s*\.{3,}', # Continuation prompts
3299 3299 r'^\++',
3300 3300 ]
3301 3301
3302 3302 strip_from_start = map(re.compile,strip_re)
3303 3303
3304 3304 lines = []
3305 3305 for l in raw_lines:
3306 3306 for pat in strip_from_start:
3307 3307 l = pat.sub('',l)
3308 3308 lines.append(l)
3309 3309
3310 3310 block = "\n".join(lines) + '\n'
3311 3311 #print "block:\n",block
3312 3312 return block
3313 3313
3314 3314 def _execute_block(self, block, par):
3315 3315 """ Execute a block, or store it in a variable, per the user's request.
3316 3316 """
3317 3317 if not par:
3318 3318 b = textwrap.dedent(block)
3319 3319 self.user_ns['pasted_block'] = b
3320 3320 exec b in self.user_ns
3321 3321 else:
3322 3322 self.user_ns[par] = SList(block.splitlines())
3323 3323 print "Block assigned to '%s'" % par
3324 3324
3325 3325 def magic_cpaste(self, parameter_s=''):
3326 3326 """Allows you to paste & execute a pre-formatted code block from clipboard.
3327 3327
3328 3328 You must terminate the block with '--' (two minus-signs) alone on the
3329 3329 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3330 3330 is the new sentinel for this operation)
3331 3331
3332 3332 The block is dedented prior to execution to enable execution of method
3333 3333 definitions. '>' and '+' characters at the beginning of a line are
3334 3334 ignored, to allow pasting directly from e-mails, diff files and
3335 3335 doctests (the '...' continuation prompt is also stripped). The
3336 3336 executed block is also assigned to variable named 'pasted_block' for
3337 3337 later editing with '%edit pasted_block'.
3338 3338
3339 3339 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3340 3340 This assigns the pasted block to variable 'foo' as string, without
3341 3341 dedenting or executing it (preceding >>> and + is still stripped)
3342 3342
3343 3343 '%cpaste -r' re-executes the block previously entered by cpaste.
3344 3344
3345 3345 Do not be alarmed by garbled output on Windows (it's a readline bug).
3346 3346 Just press enter and type -- (and press enter again) and the block
3347 3347 will be what was just pasted.
3348 3348
3349 3349 IPython statements (magics, shell escapes) are not supported (yet).
3350 3350
3351 3351 See also
3352 3352 --------
3353 3353 paste: automatically pull code from clipboard.
3354 3354 """
3355 3355
3356 3356 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3357 3357 par = args.strip()
3358 3358 if opts.has_key('r'):
3359 3359 self._rerun_pasted()
3360 3360 return
3361 3361
3362 3362 sentinel = opts.get('s','--')
3363 3363
3364 3364 block = self._strip_pasted_lines_for_code(
3365 3365 self._get_pasted_lines(sentinel))
3366 3366
3367 3367 self._execute_block(block, par)
3368 3368
3369 3369 def magic_paste(self, parameter_s=''):
3370 3370 """Allows you to paste & execute a pre-formatted code block from clipboard.
3371 3371
3372 3372 The text is pulled directly from the clipboard without user
3373 3373 intervention.
3374 3374
3375 3375 The block is dedented prior to execution to enable execution of method
3376 3376 definitions. '>' and '+' characters at the beginning of a line are
3377 3377 ignored, to allow pasting directly from e-mails, diff files and
3378 3378 doctests (the '...' continuation prompt is also stripped). The
3379 3379 executed block is also assigned to variable named 'pasted_block' for
3380 3380 later editing with '%edit pasted_block'.
3381 3381
3382 3382 You can also pass a variable name as an argument, e.g. '%paste foo'.
3383 3383 This assigns the pasted block to variable 'foo' as string, without
3384 3384 dedenting or executing it (preceding >>> and + is still stripped)
3385 3385
3386 3386 '%paste -r' re-executes the block previously entered by cpaste.
3387 3387
3388 3388 IPython statements (magics, shell escapes) are not supported (yet).
3389 3389
3390 3390 See also
3391 3391 --------
3392 3392 cpaste: manually paste code into terminal until you mark its end.
3393 3393 """
3394 3394 opts,args = self.parse_options(parameter_s,'r:',mode='string')
3395 3395 par = args.strip()
3396 3396 if opts.has_key('r'):
3397 3397 self._rerun_pasted()
3398 3398 return
3399 3399
3400 3400 text = self.shell.hooks.clipboard_get()
3401 3401 block = self._strip_pasted_lines_for_code(text.splitlines())
3402 3402 self._execute_block(block, par)
3403 3403
3404 3404 def magic_quickref(self,arg):
3405 3405 """ Show a quick reference sheet """
3406 3406 import IPython.core.usage
3407 3407 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3408 3408
3409 3409 page(qr)
3410 3410
3411 3411 def magic_upgrade(self,arg):
3412 3412 """ Upgrade your IPython installation
3413 3413
3414 3414 This will copy the config files that don't yet exist in your
3415 3415 ipython dir from the system config dir. Use this after upgrading
3416 3416 IPython if you don't wish to delete your .ipython dir.
3417 3417
3418 3418 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3419 3419 new users)
3420 3420
3421 3421 """
3422 3422 ip = self.getapi()
3423 3423 ipinstallation = path(IPython.__file__).dirname()
3424 3424 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3425 3425 src_config = ipinstallation / 'config' / 'userconfig'
3426 3426 userdir = path(ip.options.ipythondir)
3427 3427 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3428 3428 print ">",cmd
3429 3429 shell(cmd)
3430 3430 if arg == '-nolegacy':
3431 3431 legacy = userdir.files('ipythonrc*')
3432 3432 print "Nuking legacy files:",legacy
3433 3433
3434 3434 [p.remove() for p in legacy]
3435 3435 suffix = (sys.platform == 'win32' and '.ini' or '')
3436 3436 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3437 3437
3438 3438
3439 3439 def magic_doctest_mode(self,parameter_s=''):
3440 3440 """Toggle doctest mode on and off.
3441 3441
3442 3442 This mode allows you to toggle the prompt behavior between normal
3443 3443 IPython prompts and ones that are as similar to the default IPython
3444 3444 interpreter as possible.
3445 3445
3446 3446 It also supports the pasting of code snippets that have leading '>>>'
3447 3447 and '...' prompts in them. This means that you can paste doctests from
3448 3448 files or docstrings (even if they have leading whitespace), and the
3449 3449 code will execute correctly. You can then use '%history -tn' to see
3450 3450 the translated history without line numbers; this will give you the
3451 3451 input after removal of all the leading prompts and whitespace, which
3452 3452 can be pasted back into an editor.
3453 3453
3454 3454 With these features, you can switch into this mode easily whenever you
3455 3455 need to do testing and changes to doctests, without having to leave
3456 3456 your existing IPython session.
3457 3457 """
3458 3458
3459 3459 # XXX - Fix this to have cleaner activate/deactivate calls.
3460 3460 from IPython.extensions import InterpreterPasteInput as ipaste
3461 3461 from IPython.utils.ipstruct import Struct
3462 3462
3463 3463 # Shorthands
3464 3464 shell = self.shell
3465 3465 oc = shell.outputcache
3466 3466 rc = shell.rc
3467 3467 meta = shell.meta
3468 3468 # dstore is a data store kept in the instance metadata bag to track any
3469 3469 # changes we make, so we can undo them later.
3470 3470 dstore = meta.setdefault('doctest_mode',Struct())
3471 3471 save_dstore = dstore.setdefault
3472 3472
3473 3473 # save a few values we'll need to recover later
3474 3474 mode = save_dstore('mode',False)
3475 3475 save_dstore('rc_pprint',rc.pprint)
3476 3476 save_dstore('xmode',shell.InteractiveTB.mode)
3477 3477 save_dstore('rc_separate_out',rc.separate_out)
3478 3478 save_dstore('rc_separate_out2',rc.separate_out2)
3479 3479 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3480 3480 save_dstore('rc_separate_in',rc.separate_in)
3481 3481
3482 3482 if mode == False:
3483 3483 # turn on
3484 3484 ipaste.activate_prefilter()
3485 3485
3486 3486 oc.prompt1.p_template = '>>> '
3487 3487 oc.prompt2.p_template = '... '
3488 3488 oc.prompt_out.p_template = ''
3489 3489
3490 3490 # Prompt separators like plain python
3491 3491 oc.input_sep = oc.prompt1.sep = ''
3492 3492 oc.output_sep = ''
3493 3493 oc.output_sep2 = ''
3494 3494
3495 3495 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3496 3496 oc.prompt_out.pad_left = False
3497 3497
3498 3498 rc.pprint = False
3499 3499
3500 3500 shell.magic_xmode('Plain')
3501 3501
3502 3502 else:
3503 3503 # turn off
3504 3504 ipaste.deactivate_prefilter()
3505 3505
3506 3506 oc.prompt1.p_template = rc.prompt_in1
3507 3507 oc.prompt2.p_template = rc.prompt_in2
3508 3508 oc.prompt_out.p_template = rc.prompt_out
3509 3509
3510 3510 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3511 3511
3512 3512 oc.output_sep = dstore.rc_separate_out
3513 3513 oc.output_sep2 = dstore.rc_separate_out2
3514 3514
3515 3515 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3516 3516 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3517 3517
3518 3518 rc.pprint = dstore.rc_pprint
3519 3519
3520 3520 shell.magic_xmode(dstore.xmode)
3521 3521
3522 3522 # Store new mode and inform
3523 3523 dstore.mode = bool(1-int(mode))
3524 3524 print 'Doctest mode is:',
3525 3525 print ['OFF','ON'][dstore.mode]
3526 3526
3527 def magic_gui(self, parameter_s=''):
3528 """Enable or disable IPython GUI event loop integration.
3529
3530 This magic replaces IPython's threaded shells that were activated
3531 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3532 can now be enabled, disabled and swtiched at runtime and keyboard
3533 interrupts should work without any problems. The following toolkits
3534 are supports: wxPython, PyQt4, PyGTK, and Tk::
3535
3536 %gui wx # enable wxPython event loop integration
3537 %gui qt4 # enable PyQt4 event loop integration
3538 %gui gtk # enable PyGTK event loop integration
3539 %gui tk # enable Tk event loop integration
3540 %gui # disable all event loop integration
3541
3542 WARNING: after any of these has been called you can simply create
3543 an application object, but DO NOT start the event loop yourself, as
3544 we have already handled that.
3545
3546 If you want us to create an appropriate application object add the
3547 "-a" flag to your command::
3548
3549 %gui -a wx
3550
3551 This is highly recommended for most users.
3552 """
3553 from IPython.lib import inputhook
3554 if "-a" in parameter_s:
3555 app = True
3556 else:
3557 app = False
3558 if not parameter_s:
3559 inputhook.clear_inputhook()
3560 elif 'wx' in parameter_s:
3561 return inputhook.enable_wx(app)
3562 elif 'qt4' in parameter_s:
3563 return inputhook.enable_qt4(app)
3564 elif 'gtk' in parameter_s:
3565 return inputhook.enable_gtk(app)
3566 elif 'tk' in parameter_s:
3567 return inputhook.enable_tk(app)
3568
3569
3527 3570 # end Magic
@@ -1,172 +1,181 b''
1 1 #!/usr/bin/env python
2 2 # encoding: 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 import sys
19 20
20 21 #-----------------------------------------------------------------------------
21 22 # Code
22 23 #-----------------------------------------------------------------------------
23 24
24 25
25 26 class InputHookManager(object):
26 27 """Manage PyOS_InputHook for different GUI toolkits."""
27 28
28 29 def __init__(self):
29 30 self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
30 31 self._reset()
31 32
32 33 def _reset(self):
33 34 self._callback_pyfunctype = None
34 35 self._callback = None
35 36 self._installed = False
36 37
37 38 def get_pyos_inputhook(self):
38 39 """Return the current PyOS_InputHook as a ctypes.c_void_p.
39 40 """
40 41 return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
41 42
42 43 def get_pyos_inputhook_as_func(self):
43 44 """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE.
44 45 """
45 46 return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
46 47
47 48 def set_inputhook(self, callback):
48 49 """Set PyOS_InputHook to callback and return the previous one.
49 50 """
50 51 self._callback = callback
51 52 self._callback_pyfunctype = self.PYFUNC(callback)
52 53 pyos_inputhook_ptr = self.get_pyos_inputhook()
53 54 original = self.get_pyos_inputhook_as_func()
54 55 pyos_inputhook_ptr.value = \
55 56 ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
56 57 self._installed = True
57 58 return original
58 59
59 60 def clear_inputhook(self):
60 61 """Set PyOS_InputHook to NULL and return the previous one.
61 62 """
62 63 pyos_inputhook_ptr = self.get_pyos_inputhook()
63 64 original = self.get_pyos_inputhook_as_func()
64 65 pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
65 66 self._reset()
66 67 return original
67 68
68 def enable_wx(self):
69 def enable_wx(self, app=False):
69 70 """Enable event loop integration with wxPython.
70 71
71 72 This methods sets the PyOS_InputHook for wxPython, which allows
72 73 the wxPython to integrate with terminal based applications like
73 74 IPython.
74 75
75 76 Once this has been called, you can use wx interactively by doing::
76 77
77 78 >>> import wx
78 79 >>> app = wx.App(redirect=False, clearSigInt=False)
79 80
80 81 Both options this constructor are important for things to work
81 82 properly in an interactive context.
82 83
83 84 But, *don't start the event loop*. That is handled automatically by
84 85 PyOS_InputHook.
85 86 """
86 87 from IPython.lib.inputhookwx import inputhook_wx
87 88 self.set_inputhook(inputhook_wx)
89 if app:
90 import wx
91 app = wx.App(redirect=False, clearSigInt=False)
92 return app
88 93
89 94 def disable_wx(self):
90 95 """Disable event loop integration with wxPython.
91 96
92 97 This merely sets PyOS_InputHook to NULL.
93 98 """
94 99 self.clear_inputhook()
95 100
96 def enable_qt4(self):
101 def enable_qt4(self, app=False):
97 102 """Enable event loop integration with PyQt4.
98 103
99 104 This methods sets the PyOS_InputHook for wxPython, which allows
100 105 the PyQt4 to integrate with terminal based applications like
101 106 IPython.
102 107
103 108 Once this has been called, you can simply create a QApplication and
104 109 use it. But, *don't start the event loop*. That is handled
105 110 automatically by PyOS_InputHook.
106 111 """
107 112 from PyQt4 import QtCore
108 113 # PyQt4 has had this since 4.3.1. In version 4.2, PyOS_InputHook
109 114 # was set when QtCore was imported, but if it ever got removed,
110 115 # you couldn't reset it. For earlier versions we can
111 116 # probably implement a ctypes version.
112 117 try:
113 118 QtCore.pyqtRestoreInputHook()
114 119 except AttributeError:
115 120 pass
121 if app:
122 from PyQt4 import QtGui
123 app = QtGui.QApplication(sys.argv)
124 return app
116 125
117 126 def disable_qt4(self):
118 127 """Disable event loop integration with PyQt4.
119 128
120 129 This merely sets PyOS_InputHook to NULL.
121 130 """
122 131 self.clear_inputhook()
123 132
124 def enable_gtk(self):
133 def enable_gtk(self, app=False):
125 134 """Enable event loop integration with PyGTK.
126 135
127 136 This methods sets the PyOS_InputHook for PyGTK, which allows
128 137 the PyGTK to integrate with terminal based applications like
129 138 IPython.
130 139
131 140 Once this has been called, you can simple create PyGTK objects and
132 141 use them. But, *don't start the event loop*. That is handled
133 142 automatically by PyOS_InputHook.
134 143 """
135 144 import gtk
136 145 try:
137 146 gtk.set_interactive(True)
138 147 except AttributeError:
139 148 # For older versions of gtk, use our own ctypes version
140 149 from IPython.lib.inputhookgtk import inputhook_gtk
141 150 add_inputhook(inputhook_gtk)
142 151
143 152 def disable_gtk(self):
144 153 """Disable event loop integration with PyGTK.
145 154
146 155 This merely sets PyOS_InputHook to NULL.
147 156 """
148 157 self.clear_inputhook()
149 158
150 def enable_tk(self):
159 def enable_tk(self, app=False):
151 160 # Creating a Tkinter.Tk object sets PyOS_InputHook()
152 161 pass
153 162
154 163 def disable_tk(self):
155 164 """Disable event loop integration with Tkinter.
156 165
157 166 This merely sets PyOS_InputHook to NULL.
158 167 """
159 168 self.clear_inputhook()
160 169
161 170 inputhook_manager = InputHookManager()
162 171
163 172 enable_wx = inputhook_manager.enable_wx
164 173 disable_wx = inputhook_manager.disable_wx
165 174 enable_qt4 = inputhook_manager.enable_qt4
166 175 disable_qt4 = inputhook_manager.disable_qt4
167 176 enable_gtk = inputhook_manager.enable_gtk
168 177 disable_gtk = inputhook_manager.disable_gtk
169 178 enable_tk = inputhook_manager.enable_tk
170 179 disable_tk = inputhook_manager.disable_tk
171 180 clear_inputhook = inputhook_manager.clear_inputhook
172 181 set_inputhook = inputhook_manager.set_inputhook No newline at end of file
General Comments 0
You need to be logged in to leave comments. Login now