##// END OF EJS Templates
a = !ls, a = %alias now work (captures output or gets ret val for aliases)...
vivainio -
Show More

The requested changes are too big and content was truncated. Show full diff

@@ -0,0 +1,66 b''
1 # -*- coding: utf-8 -*-
2 """ IPython extension: new prefilters for output grabbing
3
4 Provides
5
6 var = %magic blah blah
7
8 var = !ls
9
10 $Id: genutils.py 1077 2006-01-24 18:15:27Z vivainio $
11
12 """
13
14 import IPython.ipapi
15 from IPython.genutils import *
16
17 ip = IPython.ipapi.get()
18
19 import re
20
21 def hnd_magic(line,mo):
22 """ Handle a = %mymagic blah blah """
23 #cmd = genutils.make_quoted_expr(mo.group('syscmd'))
24 #mag = 'ipmagic
25 #return "%s = %s"
26 var = mo.group('varname')
27 cmd = mo.group('cmd')
28 expr = make_quoted_expr(cmd)
29 return itpl('$var = ipmagic($expr)')
30
31 def hnd_syscmd(line,mo):
32 """ Handle a = !ls """
33 #cmd = genutils.make_quoted_expr(mo.group('syscmd'))
34 #mag = 'ipmagic
35 #return "%s = %s"
36 var = mo.group('varname')
37 cmd = mo.group('cmd')
38 expr = make_quoted_expr(itpl("sc -l =$cmd"))
39 return itpl('$var = ipmagic($expr)')
40
41 def install_re_handler(pat, hnd):
42 ip.meta().re_prefilters.append((re.compile(pat), hnd))
43
44 def init_handlers():
45
46 ip.meta().re_prefilters = []
47
48 install_re_handler('(?P<varname>[\w\.]+)\s*=\s*%(?P<cmd>.*)',
49 hnd_magic
50 )
51
52 install_re_handler('(?P<varname>[\w\.]+)\s*=\s*!(?P<cmd>.*)',
53 hnd_syscmd
54 )
55
56 init_handlers()
57
58 def regex_prefilter_f(self,line):
59 for pat, handler in ip.meta().re_prefilters:
60 mo = pat.match(line)
61 if mo:
62 return handler(line,mo)
63
64 raise IPython.ipapi.TryNext
65
66 ip.set_hook('input_prefilter', regex_prefilter_f) No newline at end of file
@@ -1,19 +1,18 b''
1 1 """ System wide configuration file for IPython.
2 2
3 3 This will be imported by ipython for all users.
4 4
5 5 After this ipy_user_conf.py is imported, user specific configuration
6 6 should reside there.
7 7
8 8 """
9 9
10 10 import IPython.ipapi as ip
11 11
12 12 # add system wide configuration information, import extensions etc. here.
13 13 # nothing here is essential
14 14
15 15 import sys
16 16
17 if sys.version_info >= (2,4):
18 # rehashdir extension requires python 2.4
19 import ext_rehashdir No newline at end of file
17 import ext_rehashdir # %rehashdir magic
18 import ext_rescapture # var = !ls and var = %magic
@@ -1,2824 +1,2839 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3
4 $Id: Magic.py 1077 2006-01-24 18:15:27Z vivainio $"""
4 $Id: Magic.py 1089 2006-01-27 19:04:59Z vivainio $"""
5 5
6 6 #*****************************************************************************
7 7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
8 8 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
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 # Modules and globals
16 16
17 17 from IPython import Release
18 18 __author__ = '%s <%s>\n%s <%s>' % \
19 19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
20 20 __license__ = Release.license
21 21
22 22 # Python standard modules
23 23 import __builtin__
24 24 import bdb
25 25 import inspect
26 26 import os
27 27 import pdb
28 28 import pydoc
29 29 import sys
30 30 import re
31 31 import tempfile
32 32 import time
33 33 import cPickle as pickle
34 34 import textwrap
35 35 from cStringIO import StringIO
36 36 from getopt import getopt
37 37 from pprint import pprint, pformat
38 38
39 39 # profile isn't bundled by default in Debian for license reasons
40 40 try:
41 41 import profile,pstats
42 42 except ImportError:
43 43 profile = pstats = None
44 44
45 45 # Homebrewed
46 46 from IPython import Debugger, OInspect, wildcard
47 47 from IPython.FakeModule import FakeModule
48 48 from IPython.Itpl import Itpl, itpl, printpl,itplns
49 49 from IPython.PyColorize import Parser
50 50 from IPython.ipstruct import Struct
51 51 from IPython.macro import Macro
52 52 from IPython.genutils import *
53 53 from IPython import platutils
54 54
55 55 #***************************************************************************
56 56 # Utility functions
57 57 def on_off(tag):
58 58 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
59 59 return ['OFF','ON'][tag]
60 60
61 61 class Bunch: pass
62 62
63 63 #***************************************************************************
64 64 # Main class implementing Magic functionality
65 65 class Magic:
66 66 """Magic functions for InteractiveShell.
67 67
68 68 Shell functions which can be reached as %function_name. All magic
69 69 functions should accept a string, which they can parse for their own
70 70 needs. This can make some functions easier to type, eg `%cd ../`
71 71 vs. `%cd("../")`
72 72
73 73 ALL definitions MUST begin with the prefix magic_. The user won't need it
74 74 at the command line, but it is is needed in the definition. """
75 75
76 76 # class globals
77 77 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
78 78 'Automagic is ON, % prefix NOT needed for magic functions.']
79 79
80 80 #......................................................................
81 81 # some utility functions
82 82
83 83 def __init__(self,shell):
84 84
85 85 self.options_table = {}
86 86 if profile is None:
87 87 self.magic_prun = self.profile_missing_notice
88 88 self.shell = shell
89 89
90 90 # namespace for holding state we may need
91 91 self._magic_state = Bunch()
92 92
93 93 def profile_missing_notice(self, *args, **kwargs):
94 94 error("""\
95 95 The profile module could not be found. If you are a Debian user,
96 96 it has been removed from the standard Debian package because of its non-free
97 97 license. To use profiling, please install"python2.3-profiler" from non-free.""")
98 98
99 99 def default_option(self,fn,optstr):
100 100 """Make an entry in the options_table for fn, with value optstr"""
101 101
102 102 if fn not in self.lsmagic():
103 103 error("%s is not a magic function" % fn)
104 104 self.options_table[fn] = optstr
105 105
106 106 def lsmagic(self):
107 107 """Return a list of currently available magic functions.
108 108
109 109 Gives a list of the bare names after mangling (['ls','cd', ...], not
110 110 ['magic_ls','magic_cd',...]"""
111 111
112 112 # FIXME. This needs a cleanup, in the way the magics list is built.
113 113
114 114 # magics in class definition
115 115 class_magic = lambda fn: fn.startswith('magic_') and \
116 116 callable(Magic.__dict__[fn])
117 117 # in instance namespace (run-time user additions)
118 118 inst_magic = lambda fn: fn.startswith('magic_') and \
119 119 callable(self.__dict__[fn])
120 120 # and bound magics by user (so they can access self):
121 121 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
122 122 callable(self.__class__.__dict__[fn])
123 123 magics = filter(class_magic,Magic.__dict__.keys()) + \
124 124 filter(inst_magic,self.__dict__.keys()) + \
125 125 filter(inst_bound_magic,self.__class__.__dict__.keys())
126 126 out = []
127 127 for fn in magics:
128 128 out.append(fn.replace('magic_','',1))
129 129 out.sort()
130 130 return out
131 131
132 132 def extract_input_slices(self,slices):
133 133 """Return as a string a set of input history slices.
134 134
135 135 The set of slices is given as a list of strings (like ['1','4:8','9'],
136 136 since this function is for use by magic functions which get their
137 137 arguments as strings.
138 138
139 139 Note that slices can be called with two notations:
140 140
141 141 N:M -> standard python form, means including items N...(M-1).
142 142
143 143 N-M -> include items N..M (closed endpoint)."""
144 144
145 145 cmds = []
146 146 for chunk in slices:
147 147 if ':' in chunk:
148 148 ini,fin = map(int,chunk.split(':'))
149 149 elif '-' in chunk:
150 150 ini,fin = map(int,chunk.split('-'))
151 151 fin += 1
152 152 else:
153 153 ini = int(chunk)
154 154 fin = ini+1
155 155 cmds.append(self.shell.input_hist[ini:fin])
156 156 return cmds
157 157
158 158 def _ofind(self,oname):
159 159 """Find an object in the available namespaces.
160 160
161 161 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
162 162
163 163 Has special code to detect magic functions.
164 164 """
165 165
166 166 oname = oname.strip()
167 167
168 168 # Namespaces to search in:
169 169 user_ns = self.shell.user_ns
170 170 internal_ns = self.shell.internal_ns
171 171 builtin_ns = __builtin__.__dict__
172 172 alias_ns = self.shell.alias_table
173 173
174 174 # Put them in a list. The order is important so that we find things in
175 175 # the same order that Python finds them.
176 176 namespaces = [ ('Interactive',user_ns),
177 177 ('IPython internal',internal_ns),
178 178 ('Python builtin',builtin_ns),
179 179 ('Alias',alias_ns),
180 180 ]
181 181
182 182 # initialize results to 'null'
183 183 found = 0; obj = None; ospace = None; ds = None;
184 184 ismagic = 0; isalias = 0
185 185
186 186 # Look for the given name by splitting it in parts. If the head is
187 187 # found, then we look for all the remaining parts as members, and only
188 188 # declare success if we can find them all.
189 189 oname_parts = oname.split('.')
190 190 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
191 191 for nsname,ns in namespaces:
192 192 try:
193 193 obj = ns[oname_head]
194 194 except KeyError:
195 195 continue
196 196 else:
197 197 for part in oname_rest:
198 198 try:
199 199 obj = getattr(obj,part)
200 200 except:
201 201 # Blanket except b/c some badly implemented objects
202 202 # allow __getattr__ to raise exceptions other than
203 203 # AttributeError, which then crashes IPython.
204 204 break
205 205 else:
206 206 # If we finish the for loop (no break), we got all members
207 207 found = 1
208 208 ospace = nsname
209 209 if ns == alias_ns:
210 210 isalias = 1
211 211 break # namespace loop
212 212
213 213 # Try to see if it's magic
214 214 if not found:
215 215 if oname.startswith(self.shell.ESC_MAGIC):
216 216 oname = oname[1:]
217 217 obj = getattr(self,'magic_'+oname,None)
218 218 if obj is not None:
219 219 found = 1
220 220 ospace = 'IPython internal'
221 221 ismagic = 1
222 222
223 223 # Last try: special-case some literals like '', [], {}, etc:
224 224 if not found and oname_head in ["''",'""','[]','{}','()']:
225 225 obj = eval(oname_head)
226 226 found = 1
227 227 ospace = 'Interactive'
228 228
229 229 return {'found':found, 'obj':obj, 'namespace':ospace,
230 230 'ismagic':ismagic, 'isalias':isalias}
231 231
232 232 def arg_err(self,func):
233 233 """Print docstring if incorrect arguments were passed"""
234 234 print 'Error in arguments:'
235 235 print OInspect.getdoc(func)
236 236
237 237 def format_latex(self,strng):
238 238 """Format a string for latex inclusion."""
239 239
240 240 # Characters that need to be escaped for latex:
241 241 escape_re = re.compile(r'(%|_|\$|#)',re.MULTILINE)
242 242 # Magic command names as headers:
243 243 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
244 244 re.MULTILINE)
245 245 # Magic commands
246 246 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
247 247 re.MULTILINE)
248 248 # Paragraph continue
249 249 par_re = re.compile(r'\\$',re.MULTILINE)
250 250
251 251 # The "\n" symbol
252 252 newline_re = re.compile(r'\\n')
253 253
254 254 # Now build the string for output:
255 255 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
256 256 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
257 257 strng)
258 258 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
259 259 strng = par_re.sub(r'\\\\',strng)
260 260 strng = escape_re.sub(r'\\\1',strng)
261 261 strng = newline_re.sub(r'\\textbackslash{}n',strng)
262 262 return strng
263 263
264 264 def format_screen(self,strng):
265 265 """Format a string for screen printing.
266 266
267 267 This removes some latex-type format codes."""
268 268 # Paragraph continue
269 269 par_re = re.compile(r'\\$',re.MULTILINE)
270 270 strng = par_re.sub('',strng)
271 271 return strng
272 272
273 273 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
274 274 """Parse options passed to an argument string.
275 275
276 276 The interface is similar to that of getopt(), but it returns back a
277 277 Struct with the options as keys and the stripped argument string still
278 278 as a string.
279 279
280 280 arg_str is quoted as a true sys.argv vector by using shlex.split.
281 281 This allows us to easily expand variables, glob files, quote
282 282 arguments, etc.
283 283
284 284 Options:
285 285 -mode: default 'string'. If given as 'list', the argument string is
286 286 returned as a list (split on whitespace) instead of a string.
287 287
288 288 -list_all: put all option values in lists. Normally only options
289 289 appearing more than once are put in a list."""
290 290
291 291 # inject default options at the beginning of the input line
292 292 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
293 293 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
294 294
295 295 mode = kw.get('mode','string')
296 296 if mode not in ['string','list']:
297 297 raise ValueError,'incorrect mode given: %s' % mode
298 298 # Get options
299 299 list_all = kw.get('list_all',0)
300 300
301 301 # Check if we have more than one argument to warrant extra processing:
302 302 odict = {} # Dictionary with options
303 303 args = arg_str.split()
304 304 if len(args) >= 1:
305 305 # If the list of inputs only has 0 or 1 thing in it, there's no
306 306 # need to look for options
307 307 argv = shlex_split(arg_str)
308 308 # Do regular option processing
309 309 opts,args = getopt(argv,opt_str,*long_opts)
310 310 for o,a in opts:
311 311 if o.startswith('--'):
312 312 o = o[2:]
313 313 else:
314 314 o = o[1:]
315 315 try:
316 316 odict[o].append(a)
317 317 except AttributeError:
318 318 odict[o] = [odict[o],a]
319 319 except KeyError:
320 320 if list_all:
321 321 odict[o] = [a]
322 322 else:
323 323 odict[o] = a
324 324
325 325 # Prepare opts,args for return
326 326 opts = Struct(odict)
327 327 if mode == 'string':
328 328 args = ' '.join(args)
329 329
330 330 return opts,args
331 331
332 332 #......................................................................
333 333 # And now the actual magic functions
334 334
335 335 # Functions for IPython shell work (vars,funcs, config, etc)
336 336 def magic_lsmagic(self, parameter_s = ''):
337 337 """List currently available magic functions."""
338 338 mesc = self.shell.ESC_MAGIC
339 339 print 'Available magic functions:\n'+mesc+\
340 340 (' '+mesc).join(self.lsmagic())
341 341 print '\n' + Magic.auto_status[self.shell.rc.automagic]
342 342 return None
343 343
344 344 def magic_magic(self, parameter_s = ''):
345 345 """Print information about the magic function system."""
346 346
347 347 mode = ''
348 348 try:
349 349 if parameter_s.split()[0] == '-latex':
350 350 mode = 'latex'
351 351 except:
352 352 pass
353 353
354 354 magic_docs = []
355 355 for fname in self.lsmagic():
356 356 mname = 'magic_' + fname
357 357 for space in (Magic,self,self.__class__):
358 358 try:
359 359 fn = space.__dict__[mname]
360 360 except KeyError:
361 361 pass
362 362 else:
363 363 break
364 364 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
365 365 fname,fn.__doc__))
366 366 magic_docs = ''.join(magic_docs)
367 367
368 368 if mode == 'latex':
369 369 print self.format_latex(magic_docs)
370 370 return
371 371 else:
372 372 magic_docs = self.format_screen(magic_docs)
373 373
374 374 outmsg = """
375 375 IPython's 'magic' functions
376 376 ===========================
377 377
378 378 The magic function system provides a series of functions which allow you to
379 379 control the behavior of IPython itself, plus a lot of system-type
380 380 features. All these functions are prefixed with a % character, but parameters
381 381 are given without parentheses or quotes.
382 382
383 383 NOTE: If you have 'automagic' enabled (via the command line option or with the
384 384 %automagic function), you don't need to type in the % explicitly. By default,
385 385 IPython ships with automagic on, so you should only rarely need the % escape.
386 386
387 387 Example: typing '%cd mydir' (without the quotes) changes you working directory
388 388 to 'mydir', if it exists.
389 389
390 390 You can define your own magic functions to extend the system. See the supplied
391 391 ipythonrc and example-magic.py files for details (in your ipython
392 392 configuration directory, typically $HOME/.ipython/).
393 393
394 394 You can also define your own aliased names for magic functions. In your
395 395 ipythonrc file, placing a line like:
396 396
397 397 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
398 398
399 399 will define %pf as a new name for %profile.
400 400
401 401 You can also call magics in code using the ipmagic() function, which IPython
402 402 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
403 403
404 404 For a list of the available magic functions, use %lsmagic. For a description
405 405 of any of them, type %magic_name?, e.g. '%cd?'.
406 406
407 407 Currently the magic system has the following functions:\n"""
408 408
409 409 mesc = self.shell.ESC_MAGIC
410 410 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
411 411 "\n\n%s%s\n\n%s" % (outmsg,
412 412 magic_docs,mesc,mesc,
413 413 (' '+mesc).join(self.lsmagic()),
414 414 Magic.auto_status[self.shell.rc.automagic] ) )
415 415
416 416 page(outmsg,screen_lines=self.shell.rc.screen_length)
417 417
418 418 def magic_automagic(self, parameter_s = ''):
419 419 """Make magic functions callable without having to type the initial %.
420 420
421 421 Toggles on/off (when off, you must call it as %automagic, of
422 422 course). Note that magic functions have lowest priority, so if there's
423 423 a variable whose name collides with that of a magic fn, automagic
424 424 won't work for that function (you get the variable instead). However,
425 425 if you delete the variable (del var), the previously shadowed magic
426 426 function becomes visible to automagic again."""
427 427
428 428 rc = self.shell.rc
429 429 rc.automagic = not rc.automagic
430 430 print '\n' + Magic.auto_status[rc.automagic]
431 431
432 432 def magic_autocall(self, parameter_s = ''):
433 433 """Make functions callable without having to type parentheses.
434 434
435 435 Usage:
436 436
437 437 %autocall [mode]
438 438
439 439 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
440 440 value is toggled on and off (remembering the previous state)."""
441 441
442 442 rc = self.shell.rc
443 443
444 444 if parameter_s:
445 445 arg = int(parameter_s)
446 446 else:
447 447 arg = 'toggle'
448 448
449 449 if not arg in (0,1,2,'toggle'):
450 450 error('Valid modes: (0->Off, 1->Smart, 2->Full')
451 451 return
452 452
453 453 if arg in (0,1,2):
454 454 rc.autocall = arg
455 455 else: # toggle
456 456 if rc.autocall:
457 457 self._magic_state.autocall_save = rc.autocall
458 458 rc.autocall = 0
459 459 else:
460 460 try:
461 461 rc.autocall = self._magic_state.autocall_save
462 462 except AttributeError:
463 463 rc.autocall = self._magic_state.autocall_save = 1
464 464
465 465 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
466 466
467 467 def magic_autoindent(self, parameter_s = ''):
468 468 """Toggle autoindent on/off (if available)."""
469 469
470 470 self.shell.set_autoindent()
471 471 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
472 472
473 473 def magic_system_verbose(self, parameter_s = ''):
474 474 """Toggle verbose printing of system calls on/off."""
475 475
476 476 self.shell.rc_set_toggle('system_verbose')
477 477 print "System verbose printing is:",\
478 478 ['OFF','ON'][self.shell.rc.system_verbose]
479 479
480 480 def magic_history(self, parameter_s = ''):
481 481 """Print input history (_i<n> variables), with most recent last.
482 482
483 483 %history -> print at most 40 inputs (some may be multi-line)\\
484 484 %history n -> print at most n inputs\\
485 485 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
486 486
487 487 Each input's number <n> is shown, and is accessible as the
488 488 automatically generated variable _i<n>. Multi-line statements are
489 489 printed starting at a new line for easy copy/paste.
490 490
491 491
492 492 Options:
493 493
494 494 -n: do NOT print line numbers. This is useful if you want to get a
495 495 printout of many lines which can be directly pasted into a text
496 496 editor.
497 497
498 498 This feature is only available if numbered prompts are in use.
499 499
500 500 -r: print the 'raw' history. IPython filters your input and
501 501 converts it all into valid Python source before executing it (things
502 502 like magics or aliases are turned into function calls, for
503 503 example). With this option, you'll see the unfiltered history
504 504 instead of the filtered version: '%cd /' will be seen as '%cd /'
505 505 instead of 'ipmagic("%cd /")'.
506 506 """
507 507
508 508 shell = self.shell
509 509 if not shell.outputcache.do_full_cache:
510 510 print 'This feature is only available if numbered prompts are in use.'
511 511 return
512 512 opts,args = self.parse_options(parameter_s,'nr',mode='list')
513 513
514 514 if opts.has_key('r'):
515 515 input_hist = shell.input_hist_raw
516 516 else:
517 517 input_hist = shell.input_hist
518 518
519 519 default_length = 40
520 520 if len(args) == 0:
521 521 final = len(input_hist)
522 522 init = max(1,final-default_length)
523 523 elif len(args) == 1:
524 524 final = len(input_hist)
525 525 init = max(1,final-int(args[0]))
526 526 elif len(args) == 2:
527 527 init,final = map(int,args)
528 528 else:
529 529 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
530 530 print self.magic_hist.__doc__
531 531 return
532 532 width = len(str(final))
533 533 line_sep = ['','\n']
534 534 print_nums = not opts.has_key('n')
535 535 for in_num in range(init,final):
536 536 inline = input_hist[in_num]
537 537 multiline = int(inline.count('\n') > 1)
538 538 if print_nums:
539 539 print '%s:%s' % (str(in_num).ljust(width),line_sep[multiline]),
540 540 print inline,
541 541
542 542 def magic_hist(self, parameter_s=''):
543 543 """Alternate name for %history."""
544 544 return self.magic_history(parameter_s)
545 545
546 546 def magic_p(self, parameter_s=''):
547 547 """Just a short alias for Python's 'print'."""
548 548 exec 'print ' + parameter_s in self.shell.user_ns
549 549
550 550 def magic_r(self, parameter_s=''):
551 551 """Repeat previous input.
552 552
553 553 If given an argument, repeats the previous command which starts with
554 554 the same string, otherwise it just repeats the previous input.
555 555
556 556 Shell escaped commands (with ! as first character) are not recognized
557 557 by this system, only pure python code and magic commands.
558 558 """
559 559
560 560 start = parameter_s.strip()
561 561 esc_magic = self.shell.ESC_MAGIC
562 562 # Identify magic commands even if automagic is on (which means
563 563 # the in-memory version is different from that typed by the user).
564 564 if self.shell.rc.automagic:
565 565 start_magic = esc_magic+start
566 566 else:
567 567 start_magic = start
568 568 # Look through the input history in reverse
569 569 for n in range(len(self.shell.input_hist)-2,0,-1):
570 570 input = self.shell.input_hist[n]
571 571 # skip plain 'r' lines so we don't recurse to infinity
572 572 if input != 'ipmagic("r")\n' and \
573 573 (input.startswith(start) or input.startswith(start_magic)):
574 574 #print 'match',`input` # dbg
575 575 print 'Executing:',input,
576 576 self.shell.runlines(input)
577 577 return
578 578 print 'No previous input matching `%s` found.' % start
579 579
580 580 def magic_page(self, parameter_s=''):
581 581 """Pretty print the object and display it through a pager.
582 582
583 583 If no parameter is given, use _ (last output)."""
584 584 # After a function contributed by Olivier Aubert, slightly modified.
585 585
586 586 oname = parameter_s and parameter_s or '_'
587 587 info = self._ofind(oname)
588 588 if info['found']:
589 589 page(pformat(info['obj']))
590 590 else:
591 591 print 'Object `%s` not found' % oname
592 592
593 593 def magic_profile(self, parameter_s=''):
594 594 """Print your currently active IPyhton profile."""
595 595 if self.shell.rc.profile:
596 596 printpl('Current IPython profile: $self.shell.rc.profile.')
597 597 else:
598 598 print 'No profile active.'
599 599
600 600 def _inspect(self,meth,oname,**kw):
601 601 """Generic interface to the inspector system.
602 602
603 603 This function is meant to be called by pdef, pdoc & friends."""
604 604
605 605 oname = oname.strip()
606 606 info = Struct(self._ofind(oname))
607 607 if info.found:
608 608 pmethod = getattr(self.shell.inspector,meth)
609 609 formatter = info.ismagic and self.format_screen or None
610 610 if meth == 'pdoc':
611 611 pmethod(info.obj,oname,formatter)
612 612 elif meth == 'pinfo':
613 613 pmethod(info.obj,oname,formatter,info,**kw)
614 614 else:
615 615 pmethod(info.obj,oname)
616 616 else:
617 617 print 'Object `%s` not found.' % oname
618 618 return 'not found' # so callers can take other action
619 619
620 620 def magic_pdef(self, parameter_s=''):
621 621 """Print the definition header for any callable object.
622 622
623 623 If the object is a class, print the constructor information."""
624 624 self._inspect('pdef',parameter_s)
625 625
626 626 def magic_pdoc(self, parameter_s=''):
627 627 """Print the docstring for an object.
628 628
629 629 If the given object is a class, it will print both the class and the
630 630 constructor docstrings."""
631 631 self._inspect('pdoc',parameter_s)
632 632
633 633 def magic_psource(self, parameter_s=''):
634 634 """Print (or run through pager) the source code for an object."""
635 635 self._inspect('psource',parameter_s)
636 636
637 637 def magic_pfile(self, parameter_s=''):
638 638 """Print (or run through pager) the file where an object is defined.
639 639
640 640 The file opens at the line where the object definition begins. IPython
641 641 will honor the environment variable PAGER if set, and otherwise will
642 642 do its best to print the file in a convenient form.
643 643
644 644 If the given argument is not an object currently defined, IPython will
645 645 try to interpret it as a filename (automatically adding a .py extension
646 646 if needed). You can thus use %pfile as a syntax highlighting code
647 647 viewer."""
648 648
649 649 # first interpret argument as an object name
650 650 out = self._inspect('pfile',parameter_s)
651 651 # if not, try the input as a filename
652 652 if out == 'not found':
653 653 try:
654 654 filename = get_py_filename(parameter_s)
655 655 except IOError,msg:
656 656 print msg
657 657 return
658 658 page(self.shell.inspector.format(file(filename).read()))
659 659
660 660 def magic_pinfo(self, parameter_s=''):
661 661 """Provide detailed information about an object.
662 662
663 663 '%pinfo object' is just a synonym for object? or ?object."""
664 664
665 665 #print 'pinfo par: <%s>' % parameter_s # dbg
666 666
667 667 # detail_level: 0 -> obj? , 1 -> obj??
668 668 detail_level = 0
669 669 # We need to detect if we got called as 'pinfo pinfo foo', which can
670 670 # happen if the user types 'pinfo foo?' at the cmd line.
671 671 pinfo,qmark1,oname,qmark2 = \
672 672 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
673 673 if pinfo or qmark1 or qmark2:
674 674 detail_level = 1
675 675 if "*" in oname:
676 676 self.magic_psearch(oname)
677 677 else:
678 678 self._inspect('pinfo',oname,detail_level=detail_level)
679 679
680 680 def magic_psearch(self, parameter_s=''):
681 681 """Search for object in namespaces by wildcard.
682 682
683 683 %psearch [options] PATTERN [OBJECT TYPE]
684 684
685 685 Note: ? can be used as a synonym for %psearch, at the beginning or at
686 686 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
687 687 rest of the command line must be unchanged (options come first), so
688 688 for example the following forms are equivalent
689 689
690 690 %psearch -i a* function
691 691 -i a* function?
692 692 ?-i a* function
693 693
694 694 Arguments:
695 695
696 696 PATTERN
697 697
698 698 where PATTERN is a string containing * as a wildcard similar to its
699 699 use in a shell. The pattern is matched in all namespaces on the
700 700 search path. By default objects starting with a single _ are not
701 701 matched, many IPython generated objects have a single
702 702 underscore. The default is case insensitive matching. Matching is
703 703 also done on the attributes of objects and not only on the objects
704 704 in a module.
705 705
706 706 [OBJECT TYPE]
707 707
708 708 Is the name of a python type from the types module. The name is
709 709 given in lowercase without the ending type, ex. StringType is
710 710 written string. By adding a type here only objects matching the
711 711 given type are matched. Using all here makes the pattern match all
712 712 types (this is the default).
713 713
714 714 Options:
715 715
716 716 -a: makes the pattern match even objects whose names start with a
717 717 single underscore. These names are normally ommitted from the
718 718 search.
719 719
720 720 -i/-c: make the pattern case insensitive/sensitive. If neither of
721 721 these options is given, the default is read from your ipythonrc
722 722 file. The option name which sets this value is
723 723 'wildcards_case_sensitive'. If this option is not specified in your
724 724 ipythonrc file, IPython's internal default is to do a case sensitive
725 725 search.
726 726
727 727 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
728 728 specifiy can be searched in any of the following namespaces:
729 729 'builtin', 'user', 'user_global','internal', 'alias', where
730 730 'builtin' and 'user' are the search defaults. Note that you should
731 731 not use quotes when specifying namespaces.
732 732
733 733 'Builtin' contains the python module builtin, 'user' contains all
734 734 user data, 'alias' only contain the shell aliases and no python
735 735 objects, 'internal' contains objects used by IPython. The
736 736 'user_global' namespace is only used by embedded IPython instances,
737 737 and it contains module-level globals. You can add namespaces to the
738 738 search with -s or exclude them with -e (these options can be given
739 739 more than once).
740 740
741 741 Examples:
742 742
743 743 %psearch a* -> objects beginning with an a
744 744 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
745 745 %psearch a* function -> all functions beginning with an a
746 746 %psearch re.e* -> objects beginning with an e in module re
747 747 %psearch r*.e* -> objects that start with e in modules starting in r
748 748 %psearch r*.* string -> all strings in modules beginning with r
749 749
750 750 Case sensitve search:
751 751
752 752 %psearch -c a* list all object beginning with lower case a
753 753
754 754 Show objects beginning with a single _:
755 755
756 756 %psearch -a _* list objects beginning with a single underscore"""
757 757
758 758 # default namespaces to be searched
759 759 def_search = ['user','builtin']
760 760
761 761 # Process options/args
762 762 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
763 763 opt = opts.get
764 764 shell = self.shell
765 765 psearch = shell.inspector.psearch
766 766
767 767 # select case options
768 768 if opts.has_key('i'):
769 769 ignore_case = True
770 770 elif opts.has_key('c'):
771 771 ignore_case = False
772 772 else:
773 773 ignore_case = not shell.rc.wildcards_case_sensitive
774 774
775 775 # Build list of namespaces to search from user options
776 776 def_search.extend(opt('s',[]))
777 777 ns_exclude = ns_exclude=opt('e',[])
778 778 ns_search = [nm for nm in def_search if nm not in ns_exclude]
779 779
780 780 # Call the actual search
781 781 try:
782 782 psearch(args,shell.ns_table,ns_search,
783 783 show_all=opt('a'),ignore_case=ignore_case)
784 784 except:
785 785 shell.showtraceback()
786 786
787 787 def magic_who_ls(self, parameter_s=''):
788 788 """Return a sorted list of all interactive variables.
789 789
790 790 If arguments are given, only variables of types matching these
791 791 arguments are returned."""
792 792
793 793 user_ns = self.shell.user_ns
794 794 internal_ns = self.shell.internal_ns
795 795 user_config_ns = self.shell.user_config_ns
796 796 out = []
797 797 typelist = parameter_s.split()
798 798
799 799 for i in user_ns:
800 800 if not (i.startswith('_') or i.startswith('_i')) \
801 801 and not (i in internal_ns or i in user_config_ns):
802 802 if typelist:
803 803 if type(user_ns[i]).__name__ in typelist:
804 804 out.append(i)
805 805 else:
806 806 out.append(i)
807 807 out.sort()
808 808 return out
809 809
810 810 def magic_who(self, parameter_s=''):
811 811 """Print all interactive variables, with some minimal formatting.
812 812
813 813 If any arguments are given, only variables whose type matches one of
814 814 these are printed. For example:
815 815
816 816 %who function str
817 817
818 818 will only list functions and strings, excluding all other types of
819 819 variables. To find the proper type names, simply use type(var) at a
820 820 command line to see how python prints type names. For example:
821 821
822 822 In [1]: type('hello')\\
823 823 Out[1]: <type 'str'>
824 824
825 825 indicates that the type name for strings is 'str'.
826 826
827 827 %who always excludes executed names loaded through your configuration
828 828 file and things which are internal to IPython.
829 829
830 830 This is deliberate, as typically you may load many modules and the
831 831 purpose of %who is to show you only what you've manually defined."""
832 832
833 833 varlist = self.magic_who_ls(parameter_s)
834 834 if not varlist:
835 835 print 'Interactive namespace is empty.'
836 836 return
837 837
838 838 # if we have variables, move on...
839 839
840 840 # stupid flushing problem: when prompts have no separators, stdout is
841 841 # getting lost. I'm starting to think this is a python bug. I'm having
842 842 # to force a flush with a print because even a sys.stdout.flush
843 843 # doesn't seem to do anything!
844 844
845 845 count = 0
846 846 for i in varlist:
847 847 print i+'\t',
848 848 count += 1
849 849 if count > 8:
850 850 count = 0
851 851 print
852 852 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
853 853
854 854 print # well, this does force a flush at the expense of an extra \n
855 855
856 856 def magic_whos(self, parameter_s=''):
857 857 """Like %who, but gives some extra information about each variable.
858 858
859 859 The same type filtering of %who can be applied here.
860 860
861 861 For all variables, the type is printed. Additionally it prints:
862 862
863 863 - For {},[],(): their length.
864 864
865 865 - For Numeric arrays, a summary with shape, number of elements,
866 866 typecode and size in memory.
867 867
868 868 - Everything else: a string representation, snipping their middle if
869 869 too long."""
870 870
871 871 varnames = self.magic_who_ls(parameter_s)
872 872 if not varnames:
873 873 print 'Interactive namespace is empty.'
874 874 return
875 875
876 876 # if we have variables, move on...
877 877
878 878 # for these types, show len() instead of data:
879 879 seq_types = [types.DictType,types.ListType,types.TupleType]
880 880
881 881 # for Numeric arrays, display summary info
882 882 try:
883 883 import Numeric
884 884 except ImportError:
885 885 array_type = None
886 886 else:
887 887 array_type = Numeric.ArrayType.__name__
888 888
889 889 # Find all variable names and types so we can figure out column sizes
890 890 get_vars = lambda i: self.shell.user_ns[i]
891 891 type_name = lambda v: type(v).__name__
892 892 varlist = map(get_vars,varnames)
893 893
894 894 typelist = []
895 895 for vv in varlist:
896 896 tt = type_name(vv)
897 897 if tt=='instance':
898 898 typelist.append(str(vv.__class__))
899 899 else:
900 900 typelist.append(tt)
901 901
902 902 # column labels and # of spaces as separator
903 903 varlabel = 'Variable'
904 904 typelabel = 'Type'
905 905 datalabel = 'Data/Info'
906 906 colsep = 3
907 907 # variable format strings
908 908 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
909 909 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
910 910 aformat = "%s: %s elems, type `%s`, %s bytes"
911 911 # find the size of the columns to format the output nicely
912 912 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
913 913 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
914 914 # table header
915 915 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
916 916 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
917 917 # and the table itself
918 918 kb = 1024
919 919 Mb = 1048576 # kb**2
920 920 for vname,var,vtype in zip(varnames,varlist,typelist):
921 921 print itpl(vformat),
922 922 if vtype in seq_types:
923 923 print len(var)
924 924 elif vtype==array_type:
925 925 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
926 926 vsize = Numeric.size(var)
927 927 vbytes = vsize*var.itemsize()
928 928 if vbytes < 100000:
929 929 print aformat % (vshape,vsize,var.typecode(),vbytes)
930 930 else:
931 931 print aformat % (vshape,vsize,var.typecode(),vbytes),
932 932 if vbytes < Mb:
933 933 print '(%s kb)' % (vbytes/kb,)
934 934 else:
935 935 print '(%s Mb)' % (vbytes/Mb,)
936 936 else:
937 937 vstr = str(var).replace('\n','\\n')
938 938 if len(vstr) < 50:
939 939 print vstr
940 940 else:
941 941 printpl(vfmt_short)
942 942
943 943 def magic_reset(self, parameter_s=''):
944 944 """Resets the namespace by removing all names defined by the user.
945 945
946 946 Input/Output history are left around in case you need them."""
947 947
948 948 ans = raw_input(
949 949 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
950 950 if not ans.lower() == 'y':
951 951 print 'Nothing done.'
952 952 return
953 953 user_ns = self.shell.user_ns
954 954 for i in self.magic_who_ls():
955 955 del(user_ns[i])
956 956
957 957 def magic_config(self,parameter_s=''):
958 958 """Show IPython's internal configuration."""
959 959
960 960 page('Current configuration structure:\n'+
961 961 pformat(self.shell.rc.dict()))
962 962
963 963 def magic_logstart(self,parameter_s=''):
964 964 """Start logging anywhere in a session.
965 965
966 966 %logstart [-o|-t] [log_name [log_mode]]
967 967
968 968 If no name is given, it defaults to a file named 'ipython_log.py' in your
969 969 current directory, in 'rotate' mode (see below).
970 970
971 971 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
972 972 history up to that point and then continues logging.
973 973
974 974 %logstart takes a second optional parameter: logging mode. This can be one
975 975 of (note that the modes are given unquoted):\\
976 976 append: well, that says it.\\
977 977 backup: rename (if exists) to name~ and start name.\\
978 978 global: single logfile in your home dir, appended to.\\
979 979 over : overwrite existing log.\\
980 980 rotate: create rotating logs name.1~, name.2~, etc.
981 981
982 982 Options:
983 983
984 984 -o: log also IPython's output. In this mode, all commands which
985 985 generate an Out[NN] prompt are recorded to the logfile, right after
986 986 their corresponding input line. The output lines are always
987 987 prepended with a '#[Out]# ' marker, so that the log remains valid
988 988 Python code.
989 989
990 990 Since this marker is always the same, filtering only the output from
991 991 a log is very easy, using for example a simple awk call:
992 992
993 993 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
994 994
995 995 -t: put timestamps before each input line logged (these are put in
996 996 comments)."""
997 997
998 998 opts,par = self.parse_options(parameter_s,'ot')
999 999 log_output = 'o' in opts
1000 1000 timestamp = 't' in opts
1001 1001
1002 1002 rc = self.shell.rc
1003 1003 logger = self.shell.logger
1004 1004
1005 1005 # if no args are given, the defaults set in the logger constructor by
1006 1006 # ipytohn remain valid
1007 1007 if par:
1008 1008 try:
1009 1009 logfname,logmode = par.split()
1010 1010 except:
1011 1011 logfname = par
1012 1012 logmode = 'backup'
1013 1013 else:
1014 1014 logfname = logger.logfname
1015 1015 logmode = logger.logmode
1016 1016 # put logfname into rc struct as if it had been called on the command
1017 1017 # line, so it ends up saved in the log header Save it in case we need
1018 1018 # to restore it...
1019 1019 old_logfile = rc.opts.get('logfile','')
1020 1020 if logfname:
1021 1021 logfname = os.path.expanduser(logfname)
1022 1022 rc.opts.logfile = logfname
1023 1023 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1024 1024 try:
1025 1025 started = logger.logstart(logfname,loghead,logmode,
1026 1026 log_output,timestamp)
1027 1027 except:
1028 1028 rc.opts.logfile = old_logfile
1029 1029 warn("Couldn't start log: %s" % sys.exc_info()[1])
1030 1030 else:
1031 1031 # log input history up to this point, optionally interleaving
1032 1032 # output if requested
1033 1033
1034 1034 if timestamp:
1035 1035 # disable timestamping for the previous history, since we've
1036 1036 # lost those already (no time machine here).
1037 1037 logger.timestamp = False
1038 1038 if log_output:
1039 1039 log_write = logger.log_write
1040 1040 input_hist = self.shell.input_hist
1041 1041 output_hist = self.shell.output_hist
1042 1042 for n in range(1,len(input_hist)-1):
1043 1043 log_write(input_hist[n].rstrip())
1044 1044 if n in output_hist:
1045 1045 log_write(repr(output_hist[n]),'output')
1046 1046 else:
1047 1047 logger.log_write(self.shell.input_hist[1:])
1048 1048 if timestamp:
1049 1049 # re-enable timestamping
1050 1050 logger.timestamp = True
1051 1051
1052 1052 print ('Activating auto-logging. '
1053 1053 'Current session state plus future input saved.')
1054 1054 logger.logstate()
1055 1055
1056 1056 def magic_logoff(self,parameter_s=''):
1057 1057 """Temporarily stop logging.
1058 1058
1059 1059 You must have previously started logging."""
1060 1060 self.shell.logger.switch_log(0)
1061 1061
1062 1062 def magic_logon(self,parameter_s=''):
1063 1063 """Restart logging.
1064 1064
1065 1065 This function is for restarting logging which you've temporarily
1066 1066 stopped with %logoff. For starting logging for the first time, you
1067 1067 must use the %logstart function, which allows you to specify an
1068 1068 optional log filename."""
1069 1069
1070 1070 self.shell.logger.switch_log(1)
1071 1071
1072 1072 def magic_logstate(self,parameter_s=''):
1073 1073 """Print the status of the logging system."""
1074 1074
1075 1075 self.shell.logger.logstate()
1076 1076
1077 1077 def magic_pdb(self, parameter_s=''):
1078 1078 """Control the calling of the pdb interactive debugger.
1079 1079
1080 1080 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1081 1081 argument it works as a toggle.
1082 1082
1083 1083 When an exception is triggered, IPython can optionally call the
1084 1084 interactive pdb debugger after the traceback printout. %pdb toggles
1085 1085 this feature on and off."""
1086 1086
1087 1087 par = parameter_s.strip().lower()
1088 1088
1089 1089 if par:
1090 1090 try:
1091 1091 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1092 1092 except KeyError:
1093 1093 print ('Incorrect argument. Use on/1, off/0, '
1094 1094 'or nothing for a toggle.')
1095 1095 return
1096 1096 else:
1097 1097 # toggle
1098 1098 new_pdb = not self.shell.InteractiveTB.call_pdb
1099 1099
1100 1100 # set on the shell
1101 1101 self.shell.call_pdb = new_pdb
1102 1102 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1103 1103
1104 1104 def magic_prun(self, parameter_s ='',user_mode=1,
1105 1105 opts=None,arg_lst=None,prog_ns=None):
1106 1106
1107 1107 """Run a statement through the python code profiler.
1108 1108
1109 1109 Usage:\\
1110 1110 %prun [options] statement
1111 1111
1112 1112 The given statement (which doesn't require quote marks) is run via the
1113 1113 python profiler in a manner similar to the profile.run() function.
1114 1114 Namespaces are internally managed to work correctly; profile.run
1115 1115 cannot be used in IPython because it makes certain assumptions about
1116 1116 namespaces which do not hold under IPython.
1117 1117
1118 1118 Options:
1119 1119
1120 1120 -l <limit>: you can place restrictions on what or how much of the
1121 1121 profile gets printed. The limit value can be:
1122 1122
1123 1123 * A string: only information for function names containing this string
1124 1124 is printed.
1125 1125
1126 1126 * An integer: only these many lines are printed.
1127 1127
1128 1128 * A float (between 0 and 1): this fraction of the report is printed
1129 1129 (for example, use a limit of 0.4 to see the topmost 40% only).
1130 1130
1131 1131 You can combine several limits with repeated use of the option. For
1132 1132 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1133 1133 information about class constructors.
1134 1134
1135 1135 -r: return the pstats.Stats object generated by the profiling. This
1136 1136 object has all the information about the profile in it, and you can
1137 1137 later use it for further analysis or in other functions.
1138 1138
1139 1139 Since magic functions have a particular form of calling which prevents
1140 1140 you from writing something like:\\
1141 1141 In [1]: p = %prun -r print 4 # invalid!\\
1142 1142 you must instead use IPython's automatic variables to assign this:\\
1143 1143 In [1]: %prun -r print 4 \\
1144 1144 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1145 1145 In [2]: stats = _
1146 1146
1147 1147 If you really need to assign this value via an explicit function call,
1148 1148 you can always tap directly into the true name of the magic function
1149 1149 by using the ipmagic function (which IPython automatically adds to the
1150 1150 builtins):\\
1151 1151 In [3]: stats = ipmagic('prun','-r print 4')
1152 1152
1153 1153 You can type ipmagic? for more details on ipmagic.
1154 1154
1155 1155 -s <key>: sort profile by given key. You can provide more than one key
1156 1156 by using the option several times: '-s key1 -s key2 -s key3...'. The
1157 1157 default sorting key is 'time'.
1158 1158
1159 1159 The following is copied verbatim from the profile documentation
1160 1160 referenced below:
1161 1161
1162 1162 When more than one key is provided, additional keys are used as
1163 1163 secondary criteria when the there is equality in all keys selected
1164 1164 before them.
1165 1165
1166 1166 Abbreviations can be used for any key names, as long as the
1167 1167 abbreviation is unambiguous. The following are the keys currently
1168 1168 defined:
1169 1169
1170 1170 Valid Arg Meaning\\
1171 1171 "calls" call count\\
1172 1172 "cumulative" cumulative time\\
1173 1173 "file" file name\\
1174 1174 "module" file name\\
1175 1175 "pcalls" primitive call count\\
1176 1176 "line" line number\\
1177 1177 "name" function name\\
1178 1178 "nfl" name/file/line\\
1179 1179 "stdname" standard name\\
1180 1180 "time" internal time
1181 1181
1182 1182 Note that all sorts on statistics are in descending order (placing
1183 1183 most time consuming items first), where as name, file, and line number
1184 1184 searches are in ascending order (i.e., alphabetical). The subtle
1185 1185 distinction between "nfl" and "stdname" is that the standard name is a
1186 1186 sort of the name as printed, which means that the embedded line
1187 1187 numbers get compared in an odd way. For example, lines 3, 20, and 40
1188 1188 would (if the file names were the same) appear in the string order
1189 1189 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1190 1190 line numbers. In fact, sort_stats("nfl") is the same as
1191 1191 sort_stats("name", "file", "line").
1192 1192
1193 1193 -T <filename>: save profile results as shown on screen to a text
1194 1194 file. The profile is still shown on screen.
1195 1195
1196 1196 -D <filename>: save (via dump_stats) profile statistics to given
1197 1197 filename. This data is in a format understod by the pstats module, and
1198 1198 is generated by a call to the dump_stats() method of profile
1199 1199 objects. The profile is still shown on screen.
1200 1200
1201 1201 If you want to run complete programs under the profiler's control, use
1202 1202 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1203 1203 contains profiler specific options as described here.
1204 1204
1205 1205 You can read the complete documentation for the profile module with:\\
1206 1206 In [1]: import profile; profile.help() """
1207 1207
1208 1208 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1209 1209 # protect user quote marks
1210 1210 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1211 1211
1212 1212 if user_mode: # regular user call
1213 1213 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1214 1214 list_all=1)
1215 1215 namespace = self.shell.user_ns
1216 1216 else: # called to run a program by %run -p
1217 1217 try:
1218 1218 filename = get_py_filename(arg_lst[0])
1219 1219 except IOError,msg:
1220 1220 error(msg)
1221 1221 return
1222 1222
1223 1223 arg_str = 'execfile(filename,prog_ns)'
1224 1224 namespace = locals()
1225 1225
1226 1226 opts.merge(opts_def)
1227 1227
1228 1228 prof = profile.Profile()
1229 1229 try:
1230 1230 prof = prof.runctx(arg_str,namespace,namespace)
1231 1231 sys_exit = ''
1232 1232 except SystemExit:
1233 1233 sys_exit = """*** SystemExit exception caught in code being profiled."""
1234 1234
1235 1235 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1236 1236
1237 1237 lims = opts.l
1238 1238 if lims:
1239 1239 lims = [] # rebuild lims with ints/floats/strings
1240 1240 for lim in opts.l:
1241 1241 try:
1242 1242 lims.append(int(lim))
1243 1243 except ValueError:
1244 1244 try:
1245 1245 lims.append(float(lim))
1246 1246 except ValueError:
1247 1247 lims.append(lim)
1248 1248
1249 1249 # trap output
1250 1250 sys_stdout = sys.stdout
1251 1251 stdout_trap = StringIO()
1252 1252 try:
1253 1253 sys.stdout = stdout_trap
1254 1254 stats.print_stats(*lims)
1255 1255 finally:
1256 1256 sys.stdout = sys_stdout
1257 1257 output = stdout_trap.getvalue()
1258 1258 output = output.rstrip()
1259 1259
1260 1260 page(output,screen_lines=self.shell.rc.screen_length)
1261 1261 print sys_exit,
1262 1262
1263 1263 dump_file = opts.D[0]
1264 1264 text_file = opts.T[0]
1265 1265 if dump_file:
1266 1266 prof.dump_stats(dump_file)
1267 1267 print '\n*** Profile stats marshalled to file',\
1268 1268 `dump_file`+'.',sys_exit
1269 1269 if text_file:
1270 1270 file(text_file,'w').write(output)
1271 1271 print '\n*** Profile printout saved to text file',\
1272 1272 `text_file`+'.',sys_exit
1273 1273
1274 1274 if opts.has_key('r'):
1275 1275 return stats
1276 1276 else:
1277 1277 return None
1278 1278
1279 1279 def magic_run(self, parameter_s ='',runner=None):
1280 1280 """Run the named file inside IPython as a program.
1281 1281
1282 1282 Usage:\\
1283 1283 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1284 1284
1285 1285 Parameters after the filename are passed as command-line arguments to
1286 1286 the program (put in sys.argv). Then, control returns to IPython's
1287 1287 prompt.
1288 1288
1289 1289 This is similar to running at a system prompt:\\
1290 1290 $ python file args\\
1291 1291 but with the advantage of giving you IPython's tracebacks, and of
1292 1292 loading all variables into your interactive namespace for further use
1293 1293 (unless -p is used, see below).
1294 1294
1295 1295 The file is executed in a namespace initially consisting only of
1296 1296 __name__=='__main__' and sys.argv constructed as indicated. It thus
1297 1297 sees its environment as if it were being run as a stand-alone
1298 1298 program. But after execution, the IPython interactive namespace gets
1299 1299 updated with all variables defined in the program (except for __name__
1300 1300 and sys.argv). This allows for very convenient loading of code for
1301 1301 interactive work, while giving each program a 'clean sheet' to run in.
1302 1302
1303 1303 Options:
1304 1304
1305 1305 -n: __name__ is NOT set to '__main__', but to the running file's name
1306 1306 without extension (as python does under import). This allows running
1307 1307 scripts and reloading the definitions in them without calling code
1308 1308 protected by an ' if __name__ == "__main__" ' clause.
1309 1309
1310 1310 -i: run the file in IPython's namespace instead of an empty one. This
1311 1311 is useful if you are experimenting with code written in a text editor
1312 1312 which depends on variables defined interactively.
1313 1313
1314 1314 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1315 1315 being run. This is particularly useful if IPython is being used to
1316 1316 run unittests, which always exit with a sys.exit() call. In such
1317 1317 cases you are interested in the output of the test results, not in
1318 1318 seeing a traceback of the unittest module.
1319 1319
1320 1320 -t: print timing information at the end of the run. IPython will give
1321 1321 you an estimated CPU time consumption for your script, which under
1322 1322 Unix uses the resource module to avoid the wraparound problems of
1323 1323 time.clock(). Under Unix, an estimate of time spent on system tasks
1324 1324 is also given (for Windows platforms this is reported as 0.0).
1325 1325
1326 1326 If -t is given, an additional -N<N> option can be given, where <N>
1327 1327 must be an integer indicating how many times you want the script to
1328 1328 run. The final timing report will include total and per run results.
1329 1329
1330 1330 For example (testing the script uniq_stable.py):
1331 1331
1332 1332 In [1]: run -t uniq_stable
1333 1333
1334 1334 IPython CPU timings (estimated):\\
1335 1335 User : 0.19597 s.\\
1336 1336 System: 0.0 s.\\
1337 1337
1338 1338 In [2]: run -t -N5 uniq_stable
1339 1339
1340 1340 IPython CPU timings (estimated):\\
1341 1341 Total runs performed: 5\\
1342 1342 Times : Total Per run\\
1343 1343 User : 0.910862 s, 0.1821724 s.\\
1344 1344 System: 0.0 s, 0.0 s.
1345 1345
1346 1346 -d: run your program under the control of pdb, the Python debugger.
1347 1347 This allows you to execute your program step by step, watch variables,
1348 1348 etc. Internally, what IPython does is similar to calling:
1349 1349
1350 1350 pdb.run('execfile("YOURFILENAME")')
1351 1351
1352 1352 with a breakpoint set on line 1 of your file. You can change the line
1353 1353 number for this automatic breakpoint to be <N> by using the -bN option
1354 1354 (where N must be an integer). For example:
1355 1355
1356 1356 %run -d -b40 myscript
1357 1357
1358 1358 will set the first breakpoint at line 40 in myscript.py. Note that
1359 1359 the first breakpoint must be set on a line which actually does
1360 1360 something (not a comment or docstring) for it to stop execution.
1361 1361
1362 1362 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1363 1363 first enter 'c' (without qoutes) to start execution up to the first
1364 1364 breakpoint.
1365 1365
1366 1366 Entering 'help' gives information about the use of the debugger. You
1367 1367 can easily see pdb's full documentation with "import pdb;pdb.help()"
1368 1368 at a prompt.
1369 1369
1370 1370 -p: run program under the control of the Python profiler module (which
1371 1371 prints a detailed report of execution times, function calls, etc).
1372 1372
1373 1373 You can pass other options after -p which affect the behavior of the
1374 1374 profiler itself. See the docs for %prun for details.
1375 1375
1376 1376 In this mode, the program's variables do NOT propagate back to the
1377 1377 IPython interactive namespace (because they remain in the namespace
1378 1378 where the profiler executes them).
1379 1379
1380 1380 Internally this triggers a call to %prun, see its documentation for
1381 1381 details on the options available specifically for profiling."""
1382 1382
1383 1383 # get arguments and set sys.argv for program to be run.
1384 1384 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1385 1385 mode='list',list_all=1)
1386 1386
1387 1387 try:
1388 1388 filename = get_py_filename(arg_lst[0])
1389 1389 except IndexError:
1390 1390 warn('you must provide at least a filename.')
1391 1391 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1392 1392 return
1393 1393 except IOError,msg:
1394 1394 error(msg)
1395 1395 return
1396 1396
1397 1397 # Control the response to exit() calls made by the script being run
1398 1398 exit_ignore = opts.has_key('e')
1399 1399
1400 1400 # Make sure that the running script gets a proper sys.argv as if it
1401 1401 # were run from a system shell.
1402 1402 save_argv = sys.argv # save it for later restoring
1403 1403 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1404 1404
1405 1405 if opts.has_key('i'):
1406 1406 prog_ns = self.shell.user_ns
1407 1407 __name__save = self.shell.user_ns['__name__']
1408 1408 prog_ns['__name__'] = '__main__'
1409 1409 else:
1410 1410 if opts.has_key('n'):
1411 1411 name = os.path.splitext(os.path.basename(filename))[0]
1412 1412 else:
1413 1413 name = '__main__'
1414 1414 prog_ns = {'__name__':name}
1415 1415
1416 1416 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1417 1417 # set the __file__ global in the script's namespace
1418 1418 prog_ns['__file__'] = filename
1419 1419
1420 1420 # pickle fix. See iplib for an explanation. But we need to make sure
1421 1421 # that, if we overwrite __main__, we replace it at the end
1422 1422 if prog_ns['__name__'] == '__main__':
1423 1423 restore_main = sys.modules['__main__']
1424 1424 else:
1425 1425 restore_main = False
1426 1426
1427 1427 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1428 1428
1429 1429 stats = None
1430 1430 try:
1431 1431 if opts.has_key('p'):
1432 1432 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1433 1433 else:
1434 1434 if opts.has_key('d'):
1435 1435 deb = Debugger.Pdb(self.shell.rc.colors)
1436 1436 # reset Breakpoint state, which is moronically kept
1437 1437 # in a class
1438 1438 bdb.Breakpoint.next = 1
1439 1439 bdb.Breakpoint.bplist = {}
1440 1440 bdb.Breakpoint.bpbynumber = [None]
1441 1441 # Set an initial breakpoint to stop execution
1442 1442 maxtries = 10
1443 1443 bp = int(opts.get('b',[1])[0])
1444 1444 checkline = deb.checkline(filename,bp)
1445 1445 if not checkline:
1446 1446 for bp in range(bp+1,bp+maxtries+1):
1447 1447 if deb.checkline(filename,bp):
1448 1448 break
1449 1449 else:
1450 1450 msg = ("\nI failed to find a valid line to set "
1451 1451 "a breakpoint\n"
1452 1452 "after trying up to line: %s.\n"
1453 1453 "Please set a valid breakpoint manually "
1454 1454 "with the -b option." % bp)
1455 1455 error(msg)
1456 1456 return
1457 1457 # if we find a good linenumber, set the breakpoint
1458 1458 deb.do_break('%s:%s' % (filename,bp))
1459 1459 # Start file run
1460 1460 print "NOTE: Enter 'c' at the",
1461 1461 print "ipdb> prompt to start your script."
1462 1462 try:
1463 1463 deb.run('execfile("%s")' % filename,prog_ns)
1464 1464 except:
1465 1465 etype, value, tb = sys.exc_info()
1466 1466 # Skip three frames in the traceback: the %run one,
1467 1467 # one inside bdb.py, and the command-line typed by the
1468 1468 # user (run by exec in pdb itself).
1469 1469 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1470 1470 else:
1471 1471 if runner is None:
1472 1472 runner = self.shell.safe_execfile
1473 1473 if opts.has_key('t'):
1474 1474 try:
1475 1475 nruns = int(opts['N'][0])
1476 1476 if nruns < 1:
1477 1477 error('Number of runs must be >=1')
1478 1478 return
1479 1479 except (KeyError):
1480 1480 nruns = 1
1481 1481 if nruns == 1:
1482 1482 t0 = clock2()
1483 1483 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1484 1484 t1 = clock2()
1485 1485 t_usr = t1[0]-t0[0]
1486 1486 t_sys = t1[1]-t1[1]
1487 1487 print "\nIPython CPU timings (estimated):"
1488 1488 print " User : %10s s." % t_usr
1489 1489 print " System: %10s s." % t_sys
1490 1490 else:
1491 1491 runs = range(nruns)
1492 1492 t0 = clock2()
1493 1493 for nr in runs:
1494 1494 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1495 1495 t1 = clock2()
1496 1496 t_usr = t1[0]-t0[0]
1497 1497 t_sys = t1[1]-t1[1]
1498 1498 print "\nIPython CPU timings (estimated):"
1499 1499 print "Total runs performed:",nruns
1500 1500 print " Times : %10s %10s" % ('Total','Per run')
1501 1501 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1502 1502 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1503 1503
1504 1504 else:
1505 1505 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1506 1506 if opts.has_key('i'):
1507 1507 self.shell.user_ns['__name__'] = __name__save
1508 1508 else:
1509 1509 # update IPython interactive namespace
1510 1510 del prog_ns['__name__']
1511 1511 self.shell.user_ns.update(prog_ns)
1512 1512 finally:
1513 1513 sys.argv = save_argv
1514 1514 if restore_main:
1515 1515 sys.modules['__main__'] = restore_main
1516 1516 return stats
1517 1517
1518 1518 def magic_runlog(self, parameter_s =''):
1519 1519 """Run files as logs.
1520 1520
1521 1521 Usage:\\
1522 1522 %runlog file1 file2 ...
1523 1523
1524 1524 Run the named files (treating them as log files) in sequence inside
1525 1525 the interpreter, and return to the prompt. This is much slower than
1526 1526 %run because each line is executed in a try/except block, but it
1527 1527 allows running files with syntax errors in them.
1528 1528
1529 1529 Normally IPython will guess when a file is one of its own logfiles, so
1530 1530 you can typically use %run even for logs. This shorthand allows you to
1531 1531 force any file to be treated as a log file."""
1532 1532
1533 1533 for f in parameter_s.split():
1534 1534 self.shell.safe_execfile(f,self.shell.user_ns,
1535 1535 self.shell.user_ns,islog=1)
1536 1536
1537 1537 def magic_time(self,parameter_s = ''):
1538 1538 """Time execution of a Python statement or expression.
1539 1539
1540 1540 The CPU and wall clock times are printed, and the value of the
1541 1541 expression (if any) is returned. Note that under Win32, system time
1542 1542 is always reported as 0, since it can not be measured.
1543 1543
1544 1544 This function provides very basic timing functionality. In Python
1545 1545 2.3, the timeit module offers more control and sophistication, but for
1546 1546 now IPython supports Python 2.2, so we can not rely on timeit being
1547 1547 present.
1548 1548
1549 1549 Some examples:
1550 1550
1551 1551 In [1]: time 2**128
1552 1552 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1553 1553 Wall time: 0.00
1554 1554 Out[1]: 340282366920938463463374607431768211456L
1555 1555
1556 1556 In [2]: n = 1000000
1557 1557
1558 1558 In [3]: time sum(range(n))
1559 1559 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1560 1560 Wall time: 1.37
1561 1561 Out[3]: 499999500000L
1562 1562
1563 1563 In [4]: time print 'hello world'
1564 1564 hello world
1565 1565 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1566 1566 Wall time: 0.00
1567 1567 """
1568 1568
1569 1569 # fail immediately if the given expression can't be compiled
1570 1570 try:
1571 1571 mode = 'eval'
1572 1572 code = compile(parameter_s,'<timed eval>',mode)
1573 1573 except SyntaxError:
1574 1574 mode = 'exec'
1575 1575 code = compile(parameter_s,'<timed exec>',mode)
1576 1576 # skew measurement as little as possible
1577 1577 glob = self.shell.user_ns
1578 1578 clk = clock2
1579 1579 wtime = time.time
1580 1580 # time execution
1581 1581 wall_st = wtime()
1582 1582 if mode=='eval':
1583 1583 st = clk()
1584 1584 out = eval(code,glob)
1585 1585 end = clk()
1586 1586 else:
1587 1587 st = clk()
1588 1588 exec code in glob
1589 1589 end = clk()
1590 1590 out = None
1591 1591 wall_end = wtime()
1592 1592 # Compute actual times and report
1593 1593 wall_time = wall_end-wall_st
1594 1594 cpu_user = end[0]-st[0]
1595 1595 cpu_sys = end[1]-st[1]
1596 1596 cpu_tot = cpu_user+cpu_sys
1597 1597 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1598 1598 (cpu_user,cpu_sys,cpu_tot)
1599 1599 print "Wall time: %.2f" % wall_time
1600 1600 return out
1601 1601
1602 1602 def magic_macro(self,parameter_s = ''):
1603 1603 """Define a set of input lines as a macro for future re-execution.
1604 1604
1605 1605 Usage:\\
1606 1606 %macro name n1-n2 n3-n4 ... n5 .. n6 ...
1607 1607
1608 1608 This will define a global variable called `name` which is a string
1609 1609 made of joining the slices and lines you specify (n1,n2,... numbers
1610 1610 above) from your input history into a single string. This variable
1611 1611 acts like an automatic function which re-executes those lines as if
1612 1612 you had typed them. You just type 'name' at the prompt and the code
1613 1613 executes.
1614 1614
1615 1615 The notation for indicating number ranges is: n1-n2 means 'use line
1616 1616 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1617 1617 using the lines numbered 5,6 and 7.
1618 1618
1619 1619 Note: as a 'hidden' feature, you can also use traditional python slice
1620 1620 notation, where N:M means numbers N through M-1.
1621 1621
1622 1622 For example, if your history contains (%hist prints it):
1623 1623
1624 1624 44: x=1\\
1625 1625 45: y=3\\
1626 1626 46: z=x+y\\
1627 1627 47: print x\\
1628 1628 48: a=5\\
1629 1629 49: print 'x',x,'y',y\\
1630 1630
1631 1631 you can create a macro with lines 44 through 47 (included) and line 49
1632 1632 called my_macro with:
1633 1633
1634 1634 In [51]: %macro my_macro 44-47 49
1635 1635
1636 1636 Now, typing `my_macro` (without quotes) will re-execute all this code
1637 1637 in one pass.
1638 1638
1639 1639 You don't need to give the line-numbers in order, and any given line
1640 1640 number can appear multiple times. You can assemble macros with any
1641 1641 lines from your input history in any order.
1642 1642
1643 1643 The macro is a simple object which holds its value in an attribute,
1644 1644 but IPython's display system checks for macros and executes them as
1645 1645 code instead of printing them when you type their name.
1646 1646
1647 1647 You can view a macro's contents by explicitly printing it with:
1648 1648
1649 1649 'print macro_name'.
1650 1650
1651 1651 For one-off cases which DON'T contain magic function calls in them you
1652 1652 can obtain similar results by explicitly executing slices from your
1653 1653 input history with:
1654 1654
1655 1655 In [60]: exec In[44:48]+In[49]"""
1656 1656
1657 1657 args = parameter_s.split()
1658 1658 name,ranges = args[0], args[1:]
1659 1659 #print 'rng',ranges # dbg
1660 1660 lines = self.extract_input_slices(ranges)
1661 1661 macro = Macro(lines)
1662 1662 self.shell.user_ns.update({name:macro})
1663 1663 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1664 1664 print 'Macro contents:'
1665 1665 print macro,
1666 1666
1667 1667 def magic_save(self,parameter_s = ''):
1668 1668 """Save a set of lines to a given filename.
1669 1669
1670 1670 Usage:\\
1671 1671 %save filename n1-n2 n3-n4 ... n5 .. n6 ...
1672 1672
1673 1673 This function uses the same syntax as %macro for line extraction, but
1674 1674 instead of creating a macro it saves the resulting string to the
1675 1675 filename you specify.
1676 1676
1677 1677 It adds a '.py' extension to the file if you don't do so yourself, and
1678 1678 it asks for confirmation before overwriting existing files."""
1679 1679
1680 1680 args = parameter_s.split()
1681 1681 fname,ranges = args[0], args[1:]
1682 1682 if not fname.endswith('.py'):
1683 1683 fname += '.py'
1684 1684 if os.path.isfile(fname):
1685 1685 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1686 1686 if ans.lower() not in ['y','yes']:
1687 1687 print 'Operation cancelled.'
1688 1688 return
1689 1689 cmds = ''.join(self.extract_input_slices(ranges))
1690 1690 f = file(fname,'w')
1691 1691 f.write(cmds)
1692 1692 f.close()
1693 1693 print 'The following commands were written to file `%s`:' % fname
1694 1694 print cmds
1695 1695
1696 1696 def _edit_macro(self,mname,macro):
1697 1697 """open an editor with the macro data in a file"""
1698 1698 filename = self.shell.mktempfile(macro.value)
1699 1699 self.shell.hooks.editor(filename)
1700 1700
1701 1701 # and make a new macro object, to replace the old one
1702 1702 mfile = open(filename)
1703 1703 mvalue = mfile.read()
1704 1704 mfile.close()
1705 1705 self.shell.user_ns[mname] = Macro(mvalue)
1706 1706
1707 1707 def magic_ed(self,parameter_s=''):
1708 1708 """Alias to %edit."""
1709 1709 return self.magic_edit(parameter_s)
1710 1710
1711 1711 def magic_edit(self,parameter_s='',last_call=['','']):
1712 1712 """Bring up an editor and execute the resulting code.
1713 1713
1714 1714 Usage:
1715 1715 %edit [options] [args]
1716 1716
1717 1717 %edit runs IPython's editor hook. The default version of this hook is
1718 1718 set to call the __IPYTHON__.rc.editor command. This is read from your
1719 1719 environment variable $EDITOR. If this isn't found, it will default to
1720 1720 vi under Linux/Unix and to notepad under Windows. See the end of this
1721 1721 docstring for how to change the editor hook.
1722 1722
1723 1723 You can also set the value of this editor via the command line option
1724 1724 '-editor' or in your ipythonrc file. This is useful if you wish to use
1725 1725 specifically for IPython an editor different from your typical default
1726 1726 (and for Windows users who typically don't set environment variables).
1727 1727
1728 1728 This command allows you to conveniently edit multi-line code right in
1729 1729 your IPython session.
1730 1730
1731 1731 If called without arguments, %edit opens up an empty editor with a
1732 1732 temporary file and will execute the contents of this file when you
1733 1733 close it (don't forget to save it!).
1734 1734
1735 1735
1736 1736 Options:
1737 1737
1738 1738 -p: this will call the editor with the same data as the previous time
1739 1739 it was used, regardless of how long ago (in your current session) it
1740 1740 was.
1741 1741
1742 1742 -x: do not execute the edited code immediately upon exit. This is
1743 1743 mainly useful if you are editing programs which need to be called with
1744 1744 command line arguments, which you can then do using %run.
1745 1745
1746 1746
1747 1747 Arguments:
1748 1748
1749 1749 If arguments are given, the following possibilites exist:
1750 1750
1751 1751 - The arguments are numbers or pairs of colon-separated numbers (like
1752 1752 1 4:8 9). These are interpreted as lines of previous input to be
1753 1753 loaded into the editor. The syntax is the same of the %macro command.
1754 1754
1755 1755 - If the argument doesn't start with a number, it is evaluated as a
1756 1756 variable and its contents loaded into the editor. You can thus edit
1757 1757 any string which contains python code (including the result of
1758 1758 previous edits).
1759 1759
1760 1760 - If the argument is the name of an object (other than a string),
1761 1761 IPython will try to locate the file where it was defined and open the
1762 1762 editor at the point where it is defined. You can use `%edit function`
1763 1763 to load an editor exactly at the point where 'function' is defined,
1764 1764 edit it and have the file be executed automatically.
1765 1765
1766 1766 If the object is a macro (see %macro for details), this opens up your
1767 1767 specified editor with a temporary file containing the macro's data.
1768 1768 Upon exit, the macro is reloaded with the contents of the file.
1769 1769
1770 1770 Note: opening at an exact line is only supported under Unix, and some
1771 1771 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1772 1772 '+NUMBER' parameter necessary for this feature. Good editors like
1773 1773 (X)Emacs, vi, jed, pico and joe all do.
1774 1774
1775 1775 - If the argument is not found as a variable, IPython will look for a
1776 1776 file with that name (adding .py if necessary) and load it into the
1777 1777 editor. It will execute its contents with execfile() when you exit,
1778 1778 loading any code in the file into your interactive namespace.
1779 1779
1780 1780 After executing your code, %edit will return as output the code you
1781 1781 typed in the editor (except when it was an existing file). This way
1782 1782 you can reload the code in further invocations of %edit as a variable,
1783 1783 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1784 1784 the output.
1785 1785
1786 1786 Note that %edit is also available through the alias %ed.
1787 1787
1788 1788 This is an example of creating a simple function inside the editor and
1789 1789 then modifying it. First, start up the editor:
1790 1790
1791 1791 In [1]: ed\\
1792 1792 Editing... done. Executing edited code...\\
1793 1793 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1794 1794
1795 1795 We can then call the function foo():
1796 1796
1797 1797 In [2]: foo()\\
1798 1798 foo() was defined in an editing session
1799 1799
1800 1800 Now we edit foo. IPython automatically loads the editor with the
1801 1801 (temporary) file where foo() was previously defined:
1802 1802
1803 1803 In [3]: ed foo\\
1804 1804 Editing... done. Executing edited code...
1805 1805
1806 1806 And if we call foo() again we get the modified version:
1807 1807
1808 1808 In [4]: foo()\\
1809 1809 foo() has now been changed!
1810 1810
1811 1811 Here is an example of how to edit a code snippet successive
1812 1812 times. First we call the editor:
1813 1813
1814 1814 In [8]: ed\\
1815 1815 Editing... done. Executing edited code...\\
1816 1816 hello\\
1817 1817 Out[8]: "print 'hello'\\n"
1818 1818
1819 1819 Now we call it again with the previous output (stored in _):
1820 1820
1821 1821 In [9]: ed _\\
1822 1822 Editing... done. Executing edited code...\\
1823 1823 hello world\\
1824 1824 Out[9]: "print 'hello world'\\n"
1825 1825
1826 1826 Now we call it with the output #8 (stored in _8, also as Out[8]):
1827 1827
1828 1828 In [10]: ed _8\\
1829 1829 Editing... done. Executing edited code...\\
1830 1830 hello again\\
1831 1831 Out[10]: "print 'hello again'\\n"
1832 1832
1833 1833
1834 1834 Changing the default editor hook:
1835 1835
1836 1836 If you wish to write your own editor hook, you can put it in a
1837 1837 configuration file which you load at startup time. The default hook
1838 1838 is defined in the IPython.hooks module, and you can use that as a
1839 1839 starting example for further modifications. That file also has
1840 1840 general instructions on how to set a new hook for use once you've
1841 1841 defined it."""
1842 1842
1843 1843 # FIXME: This function has become a convoluted mess. It needs a
1844 1844 # ground-up rewrite with clean, simple logic.
1845 1845
1846 1846 def make_filename(arg):
1847 1847 "Make a filename from the given args"
1848 1848 try:
1849 1849 filename = get_py_filename(arg)
1850 1850 except IOError:
1851 1851 if args.endswith('.py'):
1852 1852 filename = arg
1853 1853 else:
1854 1854 filename = None
1855 1855 return filename
1856 1856
1857 1857 # custom exceptions
1858 1858 class DataIsObject(Exception): pass
1859 1859
1860 1860 opts,args = self.parse_options(parameter_s,'px')
1861 1861
1862 1862 # Default line number value
1863 1863 lineno = None
1864 1864 if opts.has_key('p'):
1865 1865 args = '_%s' % last_call[0]
1866 1866 if not self.shell.user_ns.has_key(args):
1867 1867 args = last_call[1]
1868 1868
1869 1869 # use last_call to remember the state of the previous call, but don't
1870 1870 # let it be clobbered by successive '-p' calls.
1871 1871 try:
1872 1872 last_call[0] = self.shell.outputcache.prompt_count
1873 1873 if not opts.has_key('p'):
1874 1874 last_call[1] = parameter_s
1875 1875 except:
1876 1876 pass
1877 1877
1878 1878 # by default this is done with temp files, except when the given
1879 1879 # arg is a filename
1880 1880 use_temp = 1
1881 1881
1882 1882 if re.match(r'\d',args):
1883 1883 # Mode where user specifies ranges of lines, like in %macro.
1884 1884 # This means that you can't edit files whose names begin with
1885 1885 # numbers this way. Tough.
1886 1886 ranges = args.split()
1887 1887 data = ''.join(self.extract_input_slices(ranges))
1888 1888 elif args.endswith('.py'):
1889 1889 filename = make_filename(args)
1890 1890 data = ''
1891 1891 use_temp = 0
1892 1892 elif args:
1893 1893 try:
1894 1894 # Load the parameter given as a variable. If not a string,
1895 1895 # process it as an object instead (below)
1896 1896
1897 1897 #print '*** args',args,'type',type(args) # dbg
1898 1898 data = eval(args,self.shell.user_ns)
1899 1899 if not type(data) in StringTypes:
1900 1900 raise DataIsObject
1901 1901
1902 1902 except (NameError,SyntaxError):
1903 1903 # given argument is not a variable, try as a filename
1904 1904 filename = make_filename(args)
1905 1905 if filename is None:
1906 1906 warn("Argument given (%s) can't be found as a variable "
1907 1907 "or as a filename." % args)
1908 1908 return
1909 1909
1910 1910 data = ''
1911 1911 use_temp = 0
1912 1912 except DataIsObject:
1913 1913
1914 1914 # macros have a special edit function
1915 1915 if isinstance(data,Macro):
1916 1916 self._edit_macro(args,data)
1917 1917 return
1918 1918
1919 1919 # For objects, try to edit the file where they are defined
1920 1920 try:
1921 1921 filename = inspect.getabsfile(data)
1922 1922 datafile = 1
1923 1923 except TypeError:
1924 1924 filename = make_filename(args)
1925 1925 datafile = 1
1926 1926 warn('Could not find file where `%s` is defined.\n'
1927 1927 'Opening a file named `%s`' % (args,filename))
1928 1928 # Now, make sure we can actually read the source (if it was in
1929 1929 # a temp file it's gone by now).
1930 1930 if datafile:
1931 1931 try:
1932 1932 lineno = inspect.getsourcelines(data)[1]
1933 1933 except IOError:
1934 1934 filename = make_filename(args)
1935 1935 if filename is None:
1936 1936 warn('The file `%s` where `%s` was defined cannot '
1937 1937 'be read.' % (filename,data))
1938 1938 return
1939 1939 use_temp = 0
1940 1940 else:
1941 1941 data = ''
1942 1942
1943 1943 if use_temp:
1944 1944 filename = self.shell.mktempfile(data)
1945 1945 print 'IPython will make a temporary file named:',filename
1946 1946
1947 1947 # do actual editing here
1948 1948 print 'Editing...',
1949 1949 sys.stdout.flush()
1950 1950 self.shell.hooks.editor(filename,lineno)
1951 1951 if opts.has_key('x'): # -x prevents actual execution
1952 1952 print
1953 1953 else:
1954 1954 print 'done. Executing edited code...'
1955 1955 self.shell.safe_execfile(filename,self.shell.user_ns)
1956 1956 if use_temp:
1957 1957 try:
1958 1958 return open(filename).read()
1959 1959 except IOError,msg:
1960 1960 if msg.filename == filename:
1961 1961 warn('File not found. Did you forget to save?')
1962 1962 return
1963 1963 else:
1964 1964 self.shell.showtraceback()
1965 1965
1966 1966 def magic_xmode(self,parameter_s = ''):
1967 1967 """Switch modes for the exception handlers.
1968 1968
1969 1969 Valid modes: Plain, Context and Verbose.
1970 1970
1971 1971 If called without arguments, acts as a toggle."""
1972 1972
1973 1973 def xmode_switch_err(name):
1974 1974 warn('Error changing %s exception modes.\n%s' %
1975 1975 (name,sys.exc_info()[1]))
1976 1976
1977 1977 shell = self.shell
1978 1978 new_mode = parameter_s.strip().capitalize()
1979 1979 try:
1980 1980 shell.InteractiveTB.set_mode(mode=new_mode)
1981 1981 print 'Exception reporting mode:',shell.InteractiveTB.mode
1982 1982 except:
1983 1983 xmode_switch_err('user')
1984 1984
1985 1985 # threaded shells use a special handler in sys.excepthook
1986 1986 if shell.isthreaded:
1987 1987 try:
1988 1988 shell.sys_excepthook.set_mode(mode=new_mode)
1989 1989 except:
1990 1990 xmode_switch_err('threaded')
1991 1991
1992 1992 def magic_colors(self,parameter_s = ''):
1993 1993 """Switch color scheme for prompts, info system and exception handlers.
1994 1994
1995 1995 Currently implemented schemes: NoColor, Linux, LightBG.
1996 1996
1997 1997 Color scheme names are not case-sensitive."""
1998 1998
1999 1999 def color_switch_err(name):
2000 2000 warn('Error changing %s color schemes.\n%s' %
2001 2001 (name,sys.exc_info()[1]))
2002 2002
2003 2003
2004 2004 new_scheme = parameter_s.strip()
2005 2005 if not new_scheme:
2006 2006 print 'You must specify a color scheme.'
2007 2007 return
2008 2008 # Under Windows, check for Gary Bishop's readline, which is necessary
2009 2009 # for ANSI coloring
2010 2010 if os.name in ['nt','dos']:
2011 2011 try:
2012 2012 import readline
2013 2013 except ImportError:
2014 2014 has_readline = 0
2015 2015 else:
2016 2016 try:
2017 2017 readline.GetOutputFile()
2018 2018 except AttributeError:
2019 2019 has_readline = 0
2020 2020 else:
2021 2021 has_readline = 1
2022 2022 if not has_readline:
2023 2023 msg = """\
2024 2024 Proper color support under MS Windows requires Gary Bishop's readline library.
2025 2025 You can find it at:
2026 2026 http://sourceforge.net/projects/uncpythontools
2027 2027 Gary's readline needs the ctypes module, from:
2028 2028 http://starship.python.net/crew/theller/ctypes
2029 2029
2030 2030 Defaulting color scheme to 'NoColor'"""
2031 2031 new_scheme = 'NoColor'
2032 2032 warn(msg)
2033 2033 # local shortcut
2034 2034 shell = self.shell
2035 2035
2036 2036 # Set prompt colors
2037 2037 try:
2038 2038 shell.outputcache.set_colors(new_scheme)
2039 2039 except:
2040 2040 color_switch_err('prompt')
2041 2041 else:
2042 2042 shell.rc.colors = \
2043 2043 shell.outputcache.color_table.active_scheme_name
2044 2044 # Set exception colors
2045 2045 try:
2046 2046 shell.InteractiveTB.set_colors(scheme = new_scheme)
2047 2047 shell.SyntaxTB.set_colors(scheme = new_scheme)
2048 2048 except:
2049 2049 color_switch_err('exception')
2050 2050
2051 2051 # threaded shells use a verbose traceback in sys.excepthook
2052 2052 if shell.isthreaded:
2053 2053 try:
2054 2054 shell.sys_excepthook.set_colors(scheme=new_scheme)
2055 2055 except:
2056 2056 color_switch_err('system exception handler')
2057 2057
2058 2058 # Set info (for 'object?') colors
2059 2059 if shell.rc.color_info:
2060 2060 try:
2061 2061 shell.inspector.set_active_scheme(new_scheme)
2062 2062 except:
2063 2063 color_switch_err('object inspector')
2064 2064 else:
2065 2065 shell.inspector.set_active_scheme('NoColor')
2066 2066
2067 2067 def magic_color_info(self,parameter_s = ''):
2068 2068 """Toggle color_info.
2069 2069
2070 2070 The color_info configuration parameter controls whether colors are
2071 2071 used for displaying object details (by things like %psource, %pfile or
2072 2072 the '?' system). This function toggles this value with each call.
2073 2073
2074 2074 Note that unless you have a fairly recent pager (less works better
2075 2075 than more) in your system, using colored object information displays
2076 2076 will not work properly. Test it and see."""
2077 2077
2078 2078 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2079 2079 self.magic_colors(self.shell.rc.colors)
2080 2080 print 'Object introspection functions have now coloring:',
2081 2081 print ['OFF','ON'][self.shell.rc.color_info]
2082 2082
2083 2083 def magic_Pprint(self, parameter_s=''):
2084 2084 """Toggle pretty printing on/off."""
2085 2085
2086 2086 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
2087 2087 print 'Pretty printing has been turned', \
2088 2088 ['OFF','ON'][self.shell.outputcache.Pprint]
2089 2089
2090 2090 def magic_exit(self, parameter_s=''):
2091 2091 """Exit IPython, confirming if configured to do so.
2092 2092
2093 2093 You can configure whether IPython asks for confirmation upon exit by
2094 2094 setting the confirm_exit flag in the ipythonrc file."""
2095 2095
2096 2096 self.shell.exit()
2097 2097
2098 2098 def magic_quit(self, parameter_s=''):
2099 2099 """Exit IPython, confirming if configured to do so (like %exit)"""
2100 2100
2101 2101 self.shell.exit()
2102 2102
2103 2103 def magic_Exit(self, parameter_s=''):
2104 2104 """Exit IPython without confirmation."""
2105 2105
2106 2106 self.shell.exit_now = True
2107 2107
2108 2108 def magic_Quit(self, parameter_s=''):
2109 2109 """Exit IPython without confirmation (like %Exit)."""
2110 2110
2111 2111 self.shell.exit_now = True
2112 2112
2113 2113 #......................................................................
2114 2114 # Functions to implement unix shell-type things
2115 2115
2116 2116 def magic_alias(self, parameter_s = ''):
2117 2117 """Define an alias for a system command.
2118 2118
2119 2119 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2120 2120
2121 2121 Then, typing 'alias_name params' will execute the system command 'cmd
2122 2122 params' (from your underlying operating system).
2123 2123
2124 2124 Aliases have lower precedence than magic functions and Python normal
2125 2125 variables, so if 'foo' is both a Python variable and an alias, the
2126 2126 alias can not be executed until 'del foo' removes the Python variable.
2127 2127
2128 2128 You can use the %l specifier in an alias definition to represent the
2129 2129 whole line when the alias is called. For example:
2130 2130
2131 2131 In [2]: alias all echo "Input in brackets: <%l>"\\
2132 2132 In [3]: all hello world\\
2133 2133 Input in brackets: <hello world>
2134 2134
2135 2135 You can also define aliases with parameters using %s specifiers (one
2136 2136 per parameter):
2137 2137
2138 2138 In [1]: alias parts echo first %s second %s\\
2139 2139 In [2]: %parts A B\\
2140 2140 first A second B\\
2141 2141 In [3]: %parts A\\
2142 2142 Incorrect number of arguments: 2 expected.\\
2143 2143 parts is an alias to: 'echo first %s second %s'
2144 2144
2145 2145 Note that %l and %s are mutually exclusive. You can only use one or
2146 2146 the other in your aliases.
2147 2147
2148 2148 Aliases expand Python variables just like system calls using ! or !!
2149 2149 do: all expressions prefixed with '$' get expanded. For details of
2150 2150 the semantic rules, see PEP-215:
2151 2151 http://www.python.org/peps/pep-0215.html. This is the library used by
2152 2152 IPython for variable expansion. If you want to access a true shell
2153 2153 variable, an extra $ is necessary to prevent its expansion by IPython:
2154 2154
2155 2155 In [6]: alias show echo\\
2156 2156 In [7]: PATH='A Python string'\\
2157 2157 In [8]: show $PATH\\
2158 2158 A Python string\\
2159 2159 In [9]: show $$PATH\\
2160 2160 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2161 2161
2162 2162 You can use the alias facility to acess all of $PATH. See the %rehash
2163 2163 and %rehashx functions, which automatically create aliases for the
2164 2164 contents of your $PATH.
2165 2165
2166 2166 If called with no parameters, %alias prints the current alias table."""
2167 2167
2168 2168 par = parameter_s.strip()
2169 2169 if not par:
2170 2170 if self.shell.rc.automagic:
2171 2171 prechar = ''
2172 2172 else:
2173 2173 prechar = self.shell.ESC_MAGIC
2174 print 'Alias\t\tSystem Command\n'+'-'*30
2174 #print 'Alias\t\tSystem Command\n'+'-'*30
2175 2175 atab = self.shell.alias_table
2176 2176 aliases = atab.keys()
2177 2177 aliases.sort()
2178 res = []
2178 2179 for alias in aliases:
2179 print prechar+alias+'\t\t'+atab[alias][1]
2180 print '-'*30+'\nTotal number of aliases:',len(aliases)
2181 return
2180 res.append((alias, atab[alias][1]))
2181 print "Total number of aliases:",len(aliases)
2182 return res
2182 2183 try:
2183 2184 alias,cmd = par.split(None,1)
2184 2185 except:
2185 2186 print OInspect.getdoc(self.magic_alias)
2186 2187 else:
2187 2188 nargs = cmd.count('%s')
2188 2189 if nargs>0 and cmd.find('%l')>=0:
2189 2190 error('The %s and %l specifiers are mutually exclusive '
2190 2191 'in alias definitions.')
2191 2192 else: # all looks OK
2192 2193 self.shell.alias_table[alias] = (nargs,cmd)
2193 2194 self.shell.alias_table_validate(verbose=1)
2194 2195 # end magic_alias
2195 2196
2196 2197 def magic_unalias(self, parameter_s = ''):
2197 2198 """Remove an alias"""
2198 2199
2199 2200 aname = parameter_s.strip()
2200 2201 if aname in self.shell.alias_table:
2201 2202 del self.shell.alias_table[aname]
2202 2203
2203 2204 def magic_rehash(self, parameter_s = ''):
2204 2205 """Update the alias table with all entries in $PATH.
2205 2206
2206 2207 This version does no checks on execute permissions or whether the
2207 2208 contents of $PATH are truly files (instead of directories or something
2208 2209 else). For such a safer (but slower) version, use %rehashx."""
2209 2210
2210 2211 # This function (and rehashx) manipulate the alias_table directly
2211 2212 # rather than calling magic_alias, for speed reasons. A rehash on a
2212 2213 # typical Linux box involves several thousand entries, so efficiency
2213 2214 # here is a top concern.
2214 2215
2215 2216 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2216 2217 alias_table = self.shell.alias_table
2217 2218 for pdir in path:
2218 2219 for ff in os.listdir(pdir):
2219 2220 # each entry in the alias table must be (N,name), where
2220 2221 # N is the number of positional arguments of the alias.
2221 2222 alias_table[ff] = (0,ff)
2222 2223 # Make sure the alias table doesn't contain keywords or builtins
2223 2224 self.shell.alias_table_validate()
2224 2225 # Call again init_auto_alias() so we get 'rm -i' and other modified
2225 2226 # aliases since %rehash will probably clobber them
2226 2227 self.shell.init_auto_alias()
2227 2228
2228 2229 def magic_rehashx(self, parameter_s = ''):
2229 2230 """Update the alias table with all executable files in $PATH.
2230 2231
2231 2232 This version explicitly checks that every entry in $PATH is a file
2232 2233 with execute access (os.X_OK), so it is much slower than %rehash.
2233 2234
2234 2235 Under Windows, it checks executability as a match agains a
2235 2236 '|'-separated string of extensions, stored in the IPython config
2236 2237 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2237 2238
2238 2239 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2239 2240 alias_table = self.shell.alias_table
2240 2241
2241 2242 if os.name == 'posix':
2242 2243 isexec = lambda fname:os.path.isfile(fname) and \
2243 2244 os.access(fname,os.X_OK)
2244 2245 else:
2245 2246
2246 2247 try:
2247 2248 winext = os.environ['pathext'].replace(';','|').replace('.','')
2248 2249 except KeyError:
2249 2250 winext = 'exe|com|bat'
2250 2251
2251 2252 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2252 2253 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2253 2254 savedir = os.getcwd()
2254 2255 try:
2255 2256 # write the whole loop for posix/Windows so we don't have an if in
2256 2257 # the innermost part
2257 2258 if os.name == 'posix':
2258 2259 for pdir in path:
2259 2260 os.chdir(pdir)
2260 2261 for ff in os.listdir(pdir):
2261 2262 if isexec(ff):
2262 2263 # each entry in the alias table must be (N,name),
2263 2264 # where N is the number of positional arguments of the
2264 2265 # alias.
2265 2266 alias_table[ff] = (0,ff)
2266 2267 else:
2267 2268 for pdir in path:
2268 2269 os.chdir(pdir)
2269 2270 for ff in os.listdir(pdir):
2270 2271 if isexec(ff):
2271 2272 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2272 2273 # Make sure the alias table doesn't contain keywords or builtins
2273 2274 self.shell.alias_table_validate()
2274 2275 # Call again init_auto_alias() so we get 'rm -i' and other
2275 2276 # modified aliases since %rehashx will probably clobber them
2276 2277 self.shell.init_auto_alias()
2277 2278 finally:
2278 2279 os.chdir(savedir)
2279 2280
2280 2281 def magic_pwd(self, parameter_s = ''):
2281 2282 """Return the current working directory path."""
2282 2283 return os.getcwd()
2283 2284
2284 2285 def magic_cd(self, parameter_s=''):
2285 2286 """Change the current working directory.
2286 2287
2287 2288 This command automatically maintains an internal list of directories
2288 2289 you visit during your IPython session, in the variable _dh. The
2289 2290 command %dhist shows this history nicely formatted.
2290 2291
2291 2292 Usage:
2292 2293
2293 2294 cd 'dir': changes to directory 'dir'.
2294 2295
2295 2296 cd -: changes to the last visited directory.
2296 2297
2297 2298 cd -<n>: changes to the n-th directory in the directory history.
2298 2299
2299 2300 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2300 2301 (note: cd <bookmark_name> is enough if there is no
2301 2302 directory <bookmark_name>, but a bookmark with the name exists.)
2302 2303
2303 2304 Options:
2304 2305
2305 2306 -q: quiet. Do not print the working directory after the cd command is
2306 2307 executed. By default IPython's cd command does print this directory,
2307 2308 since the default prompts do not display path information.
2308 2309
2309 2310 Note that !cd doesn't work for this purpose because the shell where
2310 2311 !command runs is immediately discarded after executing 'command'."""
2311 2312
2312 2313 parameter_s = parameter_s.strip()
2313 2314 bkms = self.shell.persist.get("bookmarks",{})
2314 2315
2315 2316 numcd = re.match(r'(-)(\d+)$',parameter_s)
2316 2317 # jump in directory history by number
2317 2318 if numcd:
2318 2319 nn = int(numcd.group(2))
2319 2320 try:
2320 2321 ps = self.shell.user_ns['_dh'][nn]
2321 2322 except IndexError:
2322 2323 print 'The requested directory does not exist in history.'
2323 2324 return
2324 2325 else:
2325 2326 opts = {}
2326 2327 else:
2327 2328 #turn all non-space-escaping backslashes to slashes,
2328 2329 # for c:\windows\directory\names\
2329 2330 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2330 2331 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2331 2332 # jump to previous
2332 2333 if ps == '-':
2333 2334 try:
2334 2335 ps = self.shell.user_ns['_dh'][-2]
2335 2336 except IndexError:
2336 2337 print 'No previous directory to change to.'
2337 2338 return
2338 2339 # jump to bookmark
2339 2340 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2340 2341 if bkms.has_key(ps):
2341 2342 target = bkms[ps]
2342 2343 print '(bookmark:%s) -> %s' % (ps,target)
2343 2344 ps = target
2344 2345 else:
2345 2346 if bkms:
2346 2347 error("Bookmark '%s' not found. "
2347 2348 "Use '%%bookmark -l' to see your bookmarks." % ps)
2348 2349 else:
2349 2350 print "Bookmarks not set - use %bookmark <bookmarkname>"
2350 2351 return
2351 2352
2352 2353 # at this point ps should point to the target dir
2353 2354 if ps:
2354 2355 try:
2355 2356 os.chdir(os.path.expanduser(ps))
2356 2357 ttitle = ("IPy:" + (
2357 2358 os.getcwd() == '/' and '/' or os.path.basename(os.getcwd())))
2358 2359 platutils.set_term_title(ttitle)
2359 2360 except OSError:
2360 2361 print sys.exc_info()[1]
2361 2362 else:
2362 2363 self.shell.user_ns['_dh'].append(os.getcwd())
2363 2364 else:
2364 2365 os.chdir(self.shell.home_dir)
2365 2366 platutils.set_term_title("IPy:~")
2366 2367 self.shell.user_ns['_dh'].append(os.getcwd())
2367 2368 if not 'q' in opts:
2368 2369 print self.shell.user_ns['_dh'][-1]
2369 2370
2370 2371 def magic_dhist(self, parameter_s=''):
2371 2372 """Print your history of visited directories.
2372 2373
2373 2374 %dhist -> print full history\\
2374 2375 %dhist n -> print last n entries only\\
2375 2376 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2376 2377
2377 2378 This history is automatically maintained by the %cd command, and
2378 2379 always available as the global list variable _dh. You can use %cd -<n>
2379 2380 to go to directory number <n>."""
2380 2381
2381 2382 dh = self.shell.user_ns['_dh']
2382 2383 if parameter_s:
2383 2384 try:
2384 2385 args = map(int,parameter_s.split())
2385 2386 except:
2386 2387 self.arg_err(Magic.magic_dhist)
2387 2388 return
2388 2389 if len(args) == 1:
2389 2390 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2390 2391 elif len(args) == 2:
2391 2392 ini,fin = args
2392 2393 else:
2393 2394 self.arg_err(Magic.magic_dhist)
2394 2395 return
2395 2396 else:
2396 2397 ini,fin = 0,len(dh)
2397 2398 nlprint(dh,
2398 2399 header = 'Directory history (kept in _dh)',
2399 2400 start=ini,stop=fin)
2400 2401
2401 2402 def magic_env(self, parameter_s=''):
2402 2403 """List environment variables."""
2403 2404
2404 2405 return os.environ.data
2405 2406
2406 2407 def magic_pushd(self, parameter_s=''):
2407 2408 """Place the current dir on stack and change directory.
2408 2409
2409 2410 Usage:\\
2410 2411 %pushd ['dirname']
2411 2412
2412 2413 %pushd with no arguments does a %pushd to your home directory.
2413 2414 """
2414 2415 if parameter_s == '': parameter_s = '~'
2415 2416 dir_s = self.shell.dir_stack
2416 2417 if len(dir_s)>0 and os.path.expanduser(parameter_s) != \
2417 2418 os.path.expanduser(self.shell.dir_stack[0]):
2418 2419 try:
2419 2420 self.magic_cd(parameter_s)
2420 2421 dir_s.insert(0,os.getcwd().replace(self.home_dir,'~'))
2421 2422 self.magic_dirs()
2422 2423 except:
2423 2424 print 'Invalid directory'
2424 2425 else:
2425 2426 print 'You are already there!'
2426 2427
2427 2428 def magic_popd(self, parameter_s=''):
2428 2429 """Change to directory popped off the top of the stack.
2429 2430 """
2430 2431 if len (self.shell.dir_stack) > 1:
2431 2432 self.shell.dir_stack.pop(0)
2432 2433 self.magic_cd(self.shell.dir_stack[0])
2433 2434 print self.shell.dir_stack[0]
2434 2435 else:
2435 2436 print "You can't remove the starting directory from the stack:",\
2436 2437 self.shell.dir_stack
2437 2438
2438 2439 def magic_dirs(self, parameter_s=''):
2439 2440 """Return the current directory stack."""
2440 2441
2441 2442 return self.shell.dir_stack[:]
2442 2443
2443 2444 def magic_sc(self, parameter_s=''):
2444 2445 """Shell capture - execute a shell command and capture its output.
2445 2446
2447 DEPRECATED. Suboptimal, retained for backwards compatibility.
2448
2449 You should use the form 'var = !command' instead. Example:
2450
2451 "%sc -l myfiles = ls ~" should now be written as
2452
2453 "myfiles = !ls ~"
2454
2455 myfiles.s, myfiles.l and myfiles.n still apply as documented
2456 below.
2457
2458 --
2446 2459 %sc [options] varname=command
2447 2460
2448 2461 IPython will run the given command using commands.getoutput(), and
2449 2462 will then update the user's interactive namespace with a variable
2450 2463 called varname, containing the value of the call. Your command can
2451 2464 contain shell wildcards, pipes, etc.
2452 2465
2453 2466 The '=' sign in the syntax is mandatory, and the variable name you
2454 2467 supply must follow Python's standard conventions for valid names.
2468
2469 (A special format without variable name exists for internal use)
2455 2470
2456 2471 Options:
2457 2472
2458 2473 -l: list output. Split the output on newlines into a list before
2459 2474 assigning it to the given variable. By default the output is stored
2460 2475 as a single string.
2461 2476
2462 2477 -v: verbose. Print the contents of the variable.
2463 2478
2464 2479 In most cases you should not need to split as a list, because the
2465 2480 returned value is a special type of string which can automatically
2466 2481 provide its contents either as a list (split on newlines) or as a
2467 2482 space-separated string. These are convenient, respectively, either
2468 2483 for sequential processing or to be passed to a shell command.
2469 2484
2470 2485 For example:
2471 2486
2472 2487 # Capture into variable a
2473 2488 In [9]: sc a=ls *py
2474 2489
2475 2490 # a is a string with embedded newlines
2476 2491 In [10]: a
2477 2492 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2478 2493
2479 2494 # which can be seen as a list:
2480 2495 In [11]: a.l
2481 2496 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2482 2497
2483 2498 # or as a whitespace-separated string:
2484 2499 In [12]: a.s
2485 2500 Out[12]: 'setup.py win32_manual_post_install.py'
2486 2501
2487 2502 # a.s is useful to pass as a single command line:
2488 2503 In [13]: !wc -l $a.s
2489 2504 146 setup.py
2490 2505 130 win32_manual_post_install.py
2491 2506 276 total
2492 2507
2493 2508 # while the list form is useful to loop over:
2494 2509 In [14]: for f in a.l:
2495 2510 ....: !wc -l $f
2496 2511 ....:
2497 2512 146 setup.py
2498 2513 130 win32_manual_post_install.py
2499 2514
2500 2515 Similiarly, the lists returned by the -l option are also special, in
2501 2516 the sense that you can equally invoke the .s attribute on them to
2502 2517 automatically get a whitespace-separated string from their contents:
2503 2518
2504 2519 In [1]: sc -l b=ls *py
2505 2520
2506 2521 In [2]: b
2507 2522 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2508 2523
2509 2524 In [3]: b.s
2510 2525 Out[3]: 'setup.py win32_manual_post_install.py'
2511 2526
2512 2527 In summary, both the lists and strings used for ouptut capture have
2513 2528 the following special attributes:
2514 2529
2515 2530 .l (or .list) : value as list.
2516 2531 .n (or .nlstr): value as newline-separated string.
2517 2532 .s (or .spstr): value as space-separated string.
2518 2533 """
2519 2534
2520 2535 opts,args = self.parse_options(parameter_s,'lv')
2521 2536 # Try to get a variable name and command to run
2522 2537 try:
2523 2538 # the variable name must be obtained from the parse_options
2524 2539 # output, which uses shlex.split to strip options out.
2525 2540 var,_ = args.split('=',1)
2526 2541 var = var.strip()
2527 2542 # But the the command has to be extracted from the original input
2528 2543 # parameter_s, not on what parse_options returns, to avoid the
2529 2544 # quote stripping which shlex.split performs on it.
2530 2545 _,cmd = parameter_s.split('=',1)
2531 2546 except ValueError:
2532 2547 var,cmd = '',''
2533 if not var:
2534 error('you must specify a variable to assign the command to.')
2535 return
2536 2548 # If all looks ok, proceed
2537 2549 out,err = self.shell.getoutputerror(cmd)
2538 2550 if err:
2539 2551 print >> Term.cerr,err
2540 2552 if opts.has_key('l'):
2541 2553 out = SList(out.split('\n'))
2542 2554 else:
2543 2555 out = LSString(out)
2544 2556 if opts.has_key('v'):
2545 2557 print '%s ==\n%s' % (var,pformat(out))
2546 self.shell.user_ns.update({var:out})
2558 if var:
2559 self.shell.user_ns.update({var:out})
2560 else:
2561 return out
2547 2562
2548 2563 def magic_sx(self, parameter_s=''):
2549 2564 """Shell execute - run a shell command and capture its output.
2550 2565
2551 2566 %sx command
2552 2567
2553 2568 IPython will run the given command using commands.getoutput(), and
2554 2569 return the result formatted as a list (split on '\\n'). Since the
2555 2570 output is _returned_, it will be stored in ipython's regular output
2556 2571 cache Out[N] and in the '_N' automatic variables.
2557 2572
2558 2573 Notes:
2559 2574
2560 2575 1) If an input line begins with '!!', then %sx is automatically
2561 2576 invoked. That is, while:
2562 2577 !ls
2563 2578 causes ipython to simply issue system('ls'), typing
2564 2579 !!ls
2565 2580 is a shorthand equivalent to:
2566 2581 %sx ls
2567 2582
2568 2583 2) %sx differs from %sc in that %sx automatically splits into a list,
2569 2584 like '%sc -l'. The reason for this is to make it as easy as possible
2570 2585 to process line-oriented shell output via further python commands.
2571 2586 %sc is meant to provide much finer control, but requires more
2572 2587 typing.
2573 2588
2574 2589 3) Just like %sc -l, this is a list with special attributes:
2575 2590
2576 2591 .l (or .list) : value as list.
2577 2592 .n (or .nlstr): value as newline-separated string.
2578 2593 .s (or .spstr): value as whitespace-separated string.
2579 2594
2580 2595 This is very useful when trying to use such lists as arguments to
2581 2596 system commands."""
2582 2597
2583 2598 if parameter_s:
2584 2599 out,err = self.shell.getoutputerror(parameter_s)
2585 2600 if err:
2586 2601 print >> Term.cerr,err
2587 2602 return SList(out.split('\n'))
2588 2603
2589 2604 def magic_bg(self, parameter_s=''):
2590 2605 """Run a job in the background, in a separate thread.
2591 2606
2592 2607 For example,
2593 2608
2594 2609 %bg myfunc(x,y,z=1)
2595 2610
2596 2611 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2597 2612 execution starts, a message will be printed indicating the job
2598 2613 number. If your job number is 5, you can use
2599 2614
2600 2615 myvar = jobs.result(5) or myvar = jobs[5].result
2601 2616
2602 2617 to assign this result to variable 'myvar'.
2603 2618
2604 2619 IPython has a job manager, accessible via the 'jobs' object. You can
2605 2620 type jobs? to get more information about it, and use jobs.<TAB> to see
2606 2621 its attributes. All attributes not starting with an underscore are
2607 2622 meant for public use.
2608 2623
2609 2624 In particular, look at the jobs.new() method, which is used to create
2610 2625 new jobs. This magic %bg function is just a convenience wrapper
2611 2626 around jobs.new(), for expression-based jobs. If you want to create a
2612 2627 new job with an explicit function object and arguments, you must call
2613 2628 jobs.new() directly.
2614 2629
2615 2630 The jobs.new docstring also describes in detail several important
2616 2631 caveats associated with a thread-based model for background job
2617 2632 execution. Type jobs.new? for details.
2618 2633
2619 2634 You can check the status of all jobs with jobs.status().
2620 2635
2621 2636 The jobs variable is set by IPython into the Python builtin namespace.
2622 2637 If you ever declare a variable named 'jobs', you will shadow this
2623 2638 name. You can either delete your global jobs variable to regain
2624 2639 access to the job manager, or make a new name and assign it manually
2625 2640 to the manager (stored in IPython's namespace). For example, to
2626 2641 assign the job manager to the Jobs name, use:
2627 2642
2628 2643 Jobs = __builtins__.jobs"""
2629 2644
2630 2645 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2631 2646
2632 2647 def magic_store(self, parameter_s=''):
2633 2648 """Lightweight persistence for python variables.
2634 2649
2635 2650 Example:
2636 2651
2637 2652 ville@badger[~]|1> A = ['hello',10,'world']\\
2638 2653 ville@badger[~]|2> %store A\\
2639 2654 ville@badger[~]|3> Exit
2640 2655
2641 2656 (IPython session is closed and started again...)
2642 2657
2643 2658 ville@badger:~$ ipython -p pysh\\
2644 2659 ville@badger[~]|1> print A
2645 2660
2646 2661 ['hello', 10, 'world']
2647 2662
2648 2663 Usage:
2649 2664
2650 2665 %store - Show list of all variables and their current values\\
2651 2666 %store <var> - Store the *current* value of the variable to disk\\
2652 2667 %store -d <var> - Remove the variable and its value from storage\\
2653 2668 %store -r - Remove all variables from storage
2654 2669
2655 2670 It should be noted that if you change the value of a variable, you
2656 2671 need to %store it again if you want to persist the new value.
2657 2672
2658 2673 Note also that the variables will need to be pickleable; most basic
2659 2674 python types can be safely %stored.
2660 2675 """
2661 2676
2662 2677 opts,args = self.parse_options(parameter_s,'dr',mode='list')
2663 2678 # delete
2664 2679 if opts.has_key('d'):
2665 2680 try:
2666 2681 todel = args[0]
2667 2682 except IndexError:
2668 2683 error('You must provide the variable to forget')
2669 2684 else:
2670 2685 try:
2671 2686 del self.shell.persist['S:' + todel]
2672 2687 except:
2673 2688 error("Can't delete variable '%s'" % todel)
2674 2689 # reset
2675 2690 elif opts.has_key('r'):
2676 2691 for k in self.shell.persist.keys():
2677 2692 if k.startswith('S:'):
2678 2693 del self.shell.persist[k]
2679 2694
2680 2695 # run without arguments -> list variables & values
2681 2696 elif not args:
2682 2697 vars = [v[2:] for v in self.shell.persist.keys()
2683 2698 if v.startswith('S:')]
2684 2699 vars.sort()
2685 2700 if vars:
2686 2701 size = max(map(len,vars))
2687 2702 else:
2688 2703 size = 0
2689 2704
2690 2705 print 'Stored variables and their in-memory values:'
2691 2706 fmt = '%-'+str(size)+'s -> %s'
2692 2707 get = self.shell.user_ns.get
2693 2708 for var in vars:
2694 2709 # print 30 first characters from every var
2695 2710 print fmt % (var,repr(get(var,'<unavailable>'))[:50])
2696 2711
2697 2712 # default action - store the variable
2698 2713 else:
2699 2714 obj = self.shell.user_ns[args[0] ]
2700 2715 if isinstance(inspect.getmodule(obj), FakeModule):
2701 2716 print textwrap.dedent("""\
2702 2717 Warning:%s is %s
2703 2718 Proper storage of interactively declared classes (or instances
2704 2719 of those classes) is not possible! Only instances
2705 2720 of classes in real modules on file system can be %%store'd.
2706 2721 """ % (args[0], obj) )
2707 2722 return
2708 2723 pickled = pickle.dumps(obj)
2709 2724 self.shell.persist[ 'S:' + args[0] ] = pickled
2710 2725 print "Stored '%s' (%d bytes)" % (args[0], len(pickled))
2711 2726
2712 2727 def magic_bookmark(self, parameter_s=''):
2713 2728 """Manage IPython's bookmark system.
2714 2729
2715 2730 %bookmark <name> - set bookmark to current dir
2716 2731 %bookmark <name> <dir> - set bookmark to <dir>
2717 2732 %bookmark -l - list all bookmarks
2718 2733 %bookmark -d <name> - remove bookmark
2719 2734 %bookmark -r - remove all bookmarks
2720 2735
2721 2736 You can later on access a bookmarked folder with:
2722 2737 %cd -b <name>
2723 2738 or simply '%cd <name>' if there is no directory called <name> AND
2724 2739 there is such a bookmark defined.
2725 2740
2726 2741 Your bookmarks persist through IPython sessions, but they are
2727 2742 associated with each profile."""
2728 2743
2729 2744 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2730 2745 if len(args) > 2:
2731 2746 error('You can only give at most two arguments')
2732 2747 return
2733 2748
2734 2749 bkms = self.shell.persist.get('bookmarks',{})
2735 2750
2736 2751 if opts.has_key('d'):
2737 2752 try:
2738 2753 todel = args[0]
2739 2754 except IndexError:
2740 2755 error('You must provide a bookmark to delete')
2741 2756 else:
2742 2757 try:
2743 2758 del bkms[todel]
2744 2759 except:
2745 2760 error("Can't delete bookmark '%s'" % todel)
2746 2761 elif opts.has_key('r'):
2747 2762 bkms = {}
2748 2763 elif opts.has_key('l'):
2749 2764 bks = bkms.keys()
2750 2765 bks.sort()
2751 2766 if bks:
2752 2767 size = max(map(len,bks))
2753 2768 else:
2754 2769 size = 0
2755 2770 fmt = '%-'+str(size)+'s -> %s'
2756 2771 print 'Current bookmarks:'
2757 2772 for bk in bks:
2758 2773 print fmt % (bk,bkms[bk])
2759 2774 else:
2760 2775 if not args:
2761 2776 error("You must specify the bookmark name")
2762 2777 elif len(args)==1:
2763 2778 bkms[args[0]] = os.getcwd()
2764 2779 elif len(args)==2:
2765 2780 bkms[args[0]] = args[1]
2766 2781 self.shell.persist['bookmarks'] = bkms
2767 2782
2768 2783 def magic_pycat(self, parameter_s=''):
2769 2784 """Show a syntax-highlighted file through a pager.
2770 2785
2771 2786 This magic is similar to the cat utility, but it will assume the file
2772 2787 to be Python source and will show it with syntax highlighting. """
2773 2788
2774 2789 filename = get_py_filename(parameter_s)
2775 2790 page(self.shell.pycolorize(file_read(filename)),
2776 2791 screen_lines=self.shell.rc.screen_length)
2777 2792
2778 2793 def magic_cpaste(self, parameter_s=''):
2779 2794 """Allows you to paste & execute a pre-formatted code block from
2780 2795 clipboard.
2781 2796
2782 2797 You must terminate the block with '--' (two minus-signs) alone on the
2783 2798 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
2784 2799 is the new sentinel for this operation)
2785 2800
2786 2801 The block is dedented prior to execution to enable execution of
2787 2802 method definitions. The executed block is also assigned to variable
2788 2803 named 'pasted_block' for later editing with '%edit pasted_block'.
2789 2804
2790 2805 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
2791 2806 This assigns the pasted block to variable 'foo' as string, without
2792 2807 dedenting or executing it.
2793 2808
2794 2809 Do not be alarmed by garbled output on Windows (it's a readline bug).
2795 2810 Just press enter and type -- (and press enter again) and the block
2796 2811 will be what was just pasted.
2797 2812
2798 2813 IPython statements (magics, shell escapes) are not supported (yet).
2799 2814 """
2800 2815 opts,args = self.parse_options(parameter_s,'s:',mode='string')
2801 2816 par = args.strip()
2802 2817 sentinel = opts.get('s','--')
2803 2818
2804 2819 from IPython import iplib
2805 2820 lines = []
2806 2821 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
2807 2822 while 1:
2808 2823 l = iplib.raw_input_original(':')
2809 2824 if l ==sentinel:
2810 2825 break
2811 2826 lines.append(l)
2812 2827 block = "\n".join(lines)
2813 2828 #print "block:\n",block
2814 2829 if not par:
2815 2830 b = textwrap.dedent(block)
2816 2831 exec b in self.user_ns
2817 2832 self.user_ns['pasted_block'] = b
2818 2833 else:
2819 2834 self.user_ns[par] = block
2820 2835 print "Block assigned to '%s'" % par
2821 2836
2822 2837
2823 2838
2824 2839 # end Magic
@@ -1,168 +1,177 b''
1 1 ''' IPython customization API
2 2
3 3 Your one-stop module for configuring & extending ipython
4 4
5 5 The API will probably break when ipython 1.0 is released, but so
6 6 will the other configuration method (rc files).
7 7
8 8 All names prefixed by underscores are for internal use, not part
9 9 of the public api.
10 10
11 11 Below is an example that you can just put to a module and import from ipython.
12 12
13 13 A good practice is to install the config script below as e.g.
14 14
15 15 ~/.ipython/my_private_conf.py
16 16
17 17 And do
18 18
19 19 import_mod my_private_conf
20 20
21 21 in ~/.ipython/ipythonrc
22 22
23 23 That way the module is imported at startup and you can have all your
24 24 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME
25 25 stuff) in there.
26 26
27 27 -----------------------------------------------
28 28 import IPython.ipapi as ip
29 29
30 30 def ankka_f(self, arg):
31 31 print "Ankka",self,"says uppercase:",arg.upper()
32 32
33 33 ip.expose_magic("ankka",ankka_f)
34 34
35 35 ip.magic('alias sayhi echo "Testing, hi ok"')
36 36 ip.magic('alias helloworld echo "Hello world"')
37 37 ip.system('pwd')
38 38
39 39 ip.ex('import re')
40 40 ip.ex("""
41 41 def funcci(a,b):
42 42 print a+b
43 43 print funcci(3,4)
44 44 """)
45 45 ip.ex("funcci(348,9)")
46 46
47 47 def jed_editor(self,filename, linenum=None):
48 48 print "Calling my own editor, jed ... via hook!"
49 49 import os
50 50 if linenum is None: linenum = 0
51 51 os.system('jed +%d %s' % (linenum, filename))
52 52 print "exiting jed"
53 53
54 54 ip.set_hook('editor',jed_editor)
55 55
56 56 o = ip.options()
57 57 o.autocall = 2 # FULL autocall mode
58 58
59 59 print "done!"
60 60
61 61 '''
62 62
63 63
64 64 class TryNext(Exception):
65 65 """ Try next hook exception.
66 66
67 67 Raise this in your hook function to indicate that the next
68 68 hook handler should be used to handle the operation.
69 69 """
70 70
71 71
72 72 # contains the most recently instantiated IPApi
73 73 _recent = None
74 74
75 75 def get():
76 76 """ Get an IPApi object, or None if not running under ipython
77 77
78 78 Running this should be the first thing you do when writing
79 79 extensions that can be imported as normal modules. You can then
80 80 direct all the configuration operations against the returned
81 81 object.
82 82
83 83 """
84 84
85 85 return _recent
86 86
87 87
88 88
89 89 class IPApi:
90 90 """ The actual API class for configuring IPython
91 91
92 92 You should do all of the IPython configuration by getting
93 93 an IPApi object with IPython.ipapi.get() and using the provided
94 94 methods.
95 95
96 96 """
97 97 def __init__(self,ip):
98 98
99 99 self.magic = ip.ipmagic
100 100
101 101 self.system = ip.ipsystem
102 102
103 103 self.set_hook = ip.set_hook
104 104
105 105 self.IP = ip
106 106 global _recent
107 107 _recent = self
108 108
109 109
110 110
111 111 def options(self):
112 112 """ All configurable variables """
113 113 return self.IP.rc
114 114
115 115 def user_ns(self):
116 116 return self.IP.user_ns
117 117
118 118 def expose_magic(self,magicname, func):
119 119 ''' Expose own function as magic function for ipython
120 120
121 121 def foo_impl(self,parameter_s=''):
122 122 """My very own magic!. (Use docstrings, IPython reads them)."""
123 123 print 'Magic function. Passed parameter is between < >: <'+parameter_s+'>'
124 124 print 'The self object is:',self
125 125
126 126 ipapi.expose_magic("foo",foo_impl)
127 127 '''
128 128
129 129 import new
130 130 im = new.instancemethod(func,self.IP, self.IP.__class__)
131 131 setattr(self.IP, "magic_" + magicname, im)
132 132
133 133
134 134 def ex(self,cmd):
135 135 """ Execute a normal python statement in user namespace """
136 136 exec cmd in self.user_ns()
137 137
138 138 def ev(self,expr):
139 139 """ Evaluate python expression expr in user namespace
140 140
141 141 Returns the result of evaluation"""
142 142 return eval(expr,self.user_ns())
143
144 def meta(self):
145 """ Get a session-specific data store
146
147 Object returned by this method can be used to store
148 data that should persist through the ipython session.
149 """
150 return self.IP.meta
151
143 152
144 153 def launch_new_instance(user_ns = None):
145 154 """ Create and start a new ipython instance.
146 155
147 156 This can be called even without having an already initialized
148 157 ipython session running.
149 158
150 159 This is also used as the egg entry point for the 'ipython' script.
151 160
152 161 """
153 162 ses = create_session(user_ns)
154 163 ses.mainloop()
155 164
156 165
157 166 def create_session(user_ns = None):
158 167 """ Creates, but does not launch an IPython session.
159 168
160 169 Later on you can call obj.mainloop() on the returned object.
161 170
162 171 This should *not* be run when a session exists already.
163 172
164 173 """
165 174 if user_ns is not None:
166 175 user_ns["__name__"] = user_ns.get("__name__",'ipy_session')
167 176 import IPython
168 177 return IPython.Shell.start(user_ns = user_ns) No newline at end of file
@@ -1,2249 +1,2251 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.3 or newer.
6 6
7 7 This file contains all the classes and helper functions specific to IPython.
8 8
9 $Id: iplib.py 1088 2006-01-27 17:16:45Z vivainio $
9 $Id: iplib.py 1089 2006-01-27 19:04:59Z vivainio $
10 10 """
11 11
12 12 #*****************************************************************************
13 13 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
14 14 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
15 15 #
16 16 # Distributed under the terms of the BSD License. The full license is in
17 17 # the file COPYING, distributed as part of this software.
18 18 #
19 19 # Note: this code originally subclassed code.InteractiveConsole from the
20 20 # Python standard library. Over time, all of that class has been copied
21 21 # verbatim here for modifications which could not be accomplished by
22 22 # subclassing. At this point, there are no dependencies at all on the code
23 23 # module anymore (it is not even imported). The Python License (sec. 2)
24 24 # allows for this, but it's always nice to acknowledge credit where credit is
25 25 # due.
26 26 #*****************************************************************************
27 27
28 28 #****************************************************************************
29 29 # Modules and globals
30 30
31 31 from __future__ import generators # for 2.2 backwards-compatibility
32 32
33 33 from IPython import Release
34 34 __author__ = '%s <%s>\n%s <%s>' % \
35 35 ( Release.authors['Janko'] + Release.authors['Fernando'] )
36 36 __license__ = Release.license
37 37 __version__ = Release.version
38 38
39 39 # Python standard modules
40 40 import __main__
41 41 import __builtin__
42 42 import StringIO
43 43 import bdb
44 44 import cPickle as pickle
45 45 import codeop
46 46 import exceptions
47 47 import glob
48 48 import inspect
49 49 import keyword
50 50 import new
51 51 import os
52 52 import pdb
53 53 import pydoc
54 54 import re
55 55 import shutil
56 56 import string
57 57 import sys
58 58 import tempfile
59 59 import traceback
60 60 import types
61 61
62 62 from pprint import pprint, pformat
63 63
64 64 # IPython's own modules
65 65 import IPython
66 66 from IPython import OInspect,PyColorize,ultraTB
67 67 from IPython.ColorANSI import ColorScheme,ColorSchemeTable # too long names
68 68 from IPython.FakeModule import FakeModule
69 69 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
70 70 from IPython.Logger import Logger
71 71 from IPython.Magic import Magic
72 72 from IPython.Prompts import CachedOutput
73 73 from IPython.ipstruct import Struct
74 74 from IPython.background_jobs import BackgroundJobManager
75 75 from IPython.usage import cmd_line_usage,interactive_usage
76 76 from IPython.genutils import *
77 77 import IPython.ipapi
78 78
79 79 # Globals
80 80
81 81 # store the builtin raw_input globally, and use this always, in case user code
82 82 # overwrites it (like wx.py.PyShell does)
83 83 raw_input_original = raw_input
84 84
85 85 # compiled regexps for autoindent management
86 86 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
87 87
88 88
89 89 #****************************************************************************
90 90 # Some utility function definitions
91 91
92 92 ini_spaces_re = re.compile(r'^(\s+)')
93 93
94 94 def num_ini_spaces(strng):
95 95 """Return the number of initial spaces in a string"""
96 96
97 97 ini_spaces = ini_spaces_re.match(strng)
98 98 if ini_spaces:
99 99 return ini_spaces.end()
100 100 else:
101 101 return 0
102 102
103 103 def softspace(file, newvalue):
104 104 """Copied from code.py, to remove the dependency"""
105 105
106 106 oldvalue = 0
107 107 try:
108 108 oldvalue = file.softspace
109 109 except AttributeError:
110 110 pass
111 111 try:
112 112 file.softspace = newvalue
113 113 except (AttributeError, TypeError):
114 114 # "attribute-less object" or "read-only attributes"
115 115 pass
116 116 return oldvalue
117 117
118 118
119 119 #****************************************************************************
120 120 # Local use exceptions
121 121 class SpaceInInput(exceptions.Exception): pass
122 122
123 123
124 124 #****************************************************************************
125 125 # Local use classes
126 126 class Bunch: pass
127 127
128 128 class Undefined: pass
129 129
130 130 class InputList(list):
131 131 """Class to store user input.
132 132
133 133 It's basically a list, but slices return a string instead of a list, thus
134 134 allowing things like (assuming 'In' is an instance):
135 135
136 136 exec In[4:7]
137 137
138 138 or
139 139
140 140 exec In[5:9] + In[14] + In[21:25]"""
141 141
142 142 def __getslice__(self,i,j):
143 143 return ''.join(list.__getslice__(self,i,j))
144 144
145 145 class SyntaxTB(ultraTB.ListTB):
146 146 """Extension which holds some state: the last exception value"""
147 147
148 148 def __init__(self,color_scheme = 'NoColor'):
149 149 ultraTB.ListTB.__init__(self,color_scheme)
150 150 self.last_syntax_error = None
151 151
152 152 def __call__(self, etype, value, elist):
153 153 self.last_syntax_error = value
154 154 ultraTB.ListTB.__call__(self,etype,value,elist)
155 155
156 156 def clear_err_state(self):
157 157 """Return the current error state and clear it"""
158 158 e = self.last_syntax_error
159 159 self.last_syntax_error = None
160 160 return e
161 161
162 162 #****************************************************************************
163 163 # Main IPython class
164 164
165 165 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
166 166 # until a full rewrite is made. I've cleaned all cross-class uses of
167 167 # attributes and methods, but too much user code out there relies on the
168 168 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
169 169 #
170 170 # But at least now, all the pieces have been separated and we could, in
171 171 # principle, stop using the mixin. This will ease the transition to the
172 172 # chainsaw branch.
173 173
174 174 # For reference, the following is the list of 'self.foo' uses in the Magic
175 175 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
176 176 # class, to prevent clashes.
177 177
178 178 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
179 179 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
180 180 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
181 181 # 'self.value']
182 182
183 183 class InteractiveShell(object,Magic):
184 184 """An enhanced console for Python."""
185 185
186 186 # class attribute to indicate whether the class supports threads or not.
187 187 # Subclasses with thread support should override this as needed.
188 188 isthreaded = False
189 189
190 190 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
191 191 user_ns = None,user_global_ns=None,banner2='',
192 192 custom_exceptions=((),None),embedded=False):
193 193
194 194 # log system
195 195 self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
196 196
197 197 # Produce a public API instance
198 198
199 199 self.api = IPython.ipapi.IPApi(self)
200 200
201 201 # some minimal strict typechecks. For some core data structures, I
202 202 # want actual basic python types, not just anything that looks like
203 203 # one. This is especially true for namespaces.
204 204 for ns in (user_ns,user_global_ns):
205 205 if ns is not None and type(ns) != types.DictType:
206 206 raise TypeError,'namespace must be a dictionary'
207 207
208 208 # Job manager (for jobs run as background threads)
209 209 self.jobs = BackgroundJobManager()
210 210
211 211 # track which builtins we add, so we can clean up later
212 212 self.builtins_added = {}
213 213 # This method will add the necessary builtins for operation, but
214 214 # tracking what it did via the builtins_added dict.
215 215 self.add_builtins()
216 216
217 217 # Do the intuitively correct thing for quit/exit: we remove the
218 218 # builtins if they exist, and our own magics will deal with this
219 219 try:
220 220 del __builtin__.exit, __builtin__.quit
221 221 except AttributeError:
222 222 pass
223 223
224 224 # Store the actual shell's name
225 225 self.name = name
226 226
227 227 # We need to know whether the instance is meant for embedding, since
228 228 # global/local namespaces need to be handled differently in that case
229 229 self.embedded = embedded
230 230
231 231 # command compiler
232 232 self.compile = codeop.CommandCompiler()
233 233
234 234 # User input buffer
235 235 self.buffer = []
236 236
237 237 # Default name given in compilation of code
238 238 self.filename = '<ipython console>'
239 239
240 240 # Make an empty namespace, which extension writers can rely on both
241 241 # existing and NEVER being used by ipython itself. This gives them a
242 242 # convenient location for storing additional information and state
243 243 # their extensions may require, without fear of collisions with other
244 244 # ipython names that may develop later.
245 self.meta = Bunch()
245 self.meta = Struct()
246 246
247 247 # Create the namespace where the user will operate. user_ns is
248 248 # normally the only one used, and it is passed to the exec calls as
249 249 # the locals argument. But we do carry a user_global_ns namespace
250 250 # given as the exec 'globals' argument, This is useful in embedding
251 251 # situations where the ipython shell opens in a context where the
252 252 # distinction between locals and globals is meaningful.
253 253
254 254 # FIXME. For some strange reason, __builtins__ is showing up at user
255 255 # level as a dict instead of a module. This is a manual fix, but I
256 256 # should really track down where the problem is coming from. Alex
257 257 # Schmolck reported this problem first.
258 258
259 259 # A useful post by Alex Martelli on this topic:
260 260 # Re: inconsistent value from __builtins__
261 261 # Von: Alex Martelli <aleaxit@yahoo.com>
262 262 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
263 263 # Gruppen: comp.lang.python
264 264
265 265 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
266 266 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
267 267 # > <type 'dict'>
268 268 # > >>> print type(__builtins__)
269 269 # > <type 'module'>
270 270 # > Is this difference in return value intentional?
271 271
272 272 # Well, it's documented that '__builtins__' can be either a dictionary
273 273 # or a module, and it's been that way for a long time. Whether it's
274 274 # intentional (or sensible), I don't know. In any case, the idea is
275 275 # that if you need to access the built-in namespace directly, you
276 276 # should start with "import __builtin__" (note, no 's') which will
277 277 # definitely give you a module. Yeah, it's somewhat confusing:-(.
278 278
279 279 if user_ns is None:
280 280 # Set __name__ to __main__ to better match the behavior of the
281 281 # normal interpreter.
282 282 user_ns = {'__name__' :'__main__',
283 283 '__builtins__' : __builtin__,
284 284 }
285 285
286 286 if user_global_ns is None:
287 287 user_global_ns = {}
288 288
289 289 # Assign namespaces
290 290 # This is the namespace where all normal user variables live
291 291 self.user_ns = user_ns
292 292 # Embedded instances require a separate namespace for globals.
293 293 # Normally this one is unused by non-embedded instances.
294 294 self.user_global_ns = user_global_ns
295 295 # A namespace to keep track of internal data structures to prevent
296 296 # them from cluttering user-visible stuff. Will be updated later
297 297 self.internal_ns = {}
298 298
299 299 # Namespace of system aliases. Each entry in the alias
300 300 # table must be a 2-tuple of the form (N,name), where N is the number
301 301 # of positional arguments of the alias.
302 302 self.alias_table = {}
303 303
304 304 # A table holding all the namespaces IPython deals with, so that
305 305 # introspection facilities can search easily.
306 306 self.ns_table = {'user':user_ns,
307 307 'user_global':user_global_ns,
308 308 'alias':self.alias_table,
309 309 'internal':self.internal_ns,
310 310 'builtin':__builtin__.__dict__
311 311 }
312 312
313 313 # The user namespace MUST have a pointer to the shell itself.
314 314 self.user_ns[name] = self
315 315
316 316 # We need to insert into sys.modules something that looks like a
317 317 # module but which accesses the IPython namespace, for shelve and
318 318 # pickle to work interactively. Normally they rely on getting
319 319 # everything out of __main__, but for embedding purposes each IPython
320 320 # instance has its own private namespace, so we can't go shoving
321 321 # everything into __main__.
322 322
323 323 # note, however, that we should only do this for non-embedded
324 324 # ipythons, which really mimic the __main__.__dict__ with their own
325 325 # namespace. Embedded instances, on the other hand, should not do
326 326 # this because they need to manage the user local/global namespaces
327 327 # only, but they live within a 'normal' __main__ (meaning, they
328 328 # shouldn't overtake the execution environment of the script they're
329 329 # embedded in).
330 330
331 331 if not embedded:
332 332 try:
333 333 main_name = self.user_ns['__name__']
334 334 except KeyError:
335 335 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
336 336 else:
337 337 #print "pickle hack in place" # dbg
338 338 #print 'main_name:',main_name # dbg
339 339 sys.modules[main_name] = FakeModule(self.user_ns)
340 340
341 341 # List of input with multi-line handling.
342 342 # Fill its zero entry, user counter starts at 1
343 343 self.input_hist = InputList(['\n'])
344 344 # This one will hold the 'raw' input history, without any
345 345 # pre-processing. This will allow users to retrieve the input just as
346 346 # it was exactly typed in by the user, with %hist -r.
347 347 self.input_hist_raw = InputList(['\n'])
348 348
349 349 # list of visited directories
350 350 try:
351 351 self.dir_hist = [os.getcwd()]
352 352 except IOError, e:
353 353 self.dir_hist = []
354 354
355 355 # dict of output history
356 356 self.output_hist = {}
357 357
358 358 # dict of things NOT to alias (keywords, builtins and some magics)
359 359 no_alias = {}
360 360 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
361 361 for key in keyword.kwlist + no_alias_magics:
362 362 no_alias[key] = 1
363 363 no_alias.update(__builtin__.__dict__)
364 364 self.no_alias = no_alias
365 365
366 366 # make global variables for user access to these
367 367 self.user_ns['_ih'] = self.input_hist
368 368 self.user_ns['_oh'] = self.output_hist
369 369 self.user_ns['_dh'] = self.dir_hist
370 370
371 371 # user aliases to input and output histories
372 372 self.user_ns['In'] = self.input_hist
373 373 self.user_ns['Out'] = self.output_hist
374 374
375 375 # Object variable to store code object waiting execution. This is
376 376 # used mainly by the multithreaded shells, but it can come in handy in
377 377 # other situations. No need to use a Queue here, since it's a single
378 378 # item which gets cleared once run.
379 379 self.code_to_run = None
380 380
381 381 # escapes for automatic behavior on the command line
382 382 self.ESC_SHELL = '!'
383 383 self.ESC_HELP = '?'
384 384 self.ESC_MAGIC = '%'
385 385 self.ESC_QUOTE = ','
386 386 self.ESC_QUOTE2 = ';'
387 387 self.ESC_PAREN = '/'
388 388
389 389 # And their associated handlers
390 390 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
391 391 self.ESC_QUOTE : self.handle_auto,
392 392 self.ESC_QUOTE2 : self.handle_auto,
393 393 self.ESC_MAGIC : self.handle_magic,
394 394 self.ESC_HELP : self.handle_help,
395 395 self.ESC_SHELL : self.handle_shell_escape,
396 396 }
397 397
398 398 # class initializations
399 399 Magic.__init__(self,self)
400 400
401 401 # Python source parser/formatter for syntax highlighting
402 402 pyformat = PyColorize.Parser().format
403 403 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
404 404
405 405 # hooks holds pointers used for user-side customizations
406 406 self.hooks = Struct()
407 407
408 408 # Set all default hooks, defined in the IPython.hooks module.
409 409 hooks = IPython.hooks
410 410 for hook_name in hooks.__all__:
411 411 # default hooks have priority 100, i.e. low; user hooks should have 0-100 priority
412 412 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
413 413 #print "bound hook",hook_name
414 414
415 415 # Flag to mark unconditional exit
416 416 self.exit_now = False
417 417
418 418 self.usage_min = """\
419 419 An enhanced console for Python.
420 420 Some of its features are:
421 421 - Readline support if the readline library is present.
422 422 - Tab completion in the local namespace.
423 423 - Logging of input, see command-line options.
424 424 - System shell escape via ! , eg !ls.
425 425 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
426 426 - Keeps track of locally defined variables via %who, %whos.
427 427 - Show object information with a ? eg ?x or x? (use ?? for more info).
428 428 """
429 429 if usage: self.usage = usage
430 430 else: self.usage = self.usage_min
431 431
432 432 # Storage
433 433 self.rc = rc # This will hold all configuration information
434 434 self.pager = 'less'
435 435 # temporary files used for various purposes. Deleted at exit.
436 436 self.tempfiles = []
437 437
438 438 # Keep track of readline usage (later set by init_readline)
439 439 self.has_readline = False
440 440
441 441 # template for logfile headers. It gets resolved at runtime by the
442 442 # logstart method.
443 443 self.loghead_tpl = \
444 444 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
445 445 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
446 446 #log# opts = %s
447 447 #log# args = %s
448 448 #log# It is safe to make manual edits below here.
449 449 #log#-----------------------------------------------------------------------
450 450 """
451 451 # for pushd/popd management
452 452 try:
453 453 self.home_dir = get_home_dir()
454 454 except HomeDirError,msg:
455 455 fatal(msg)
456 456
457 457 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
458 458
459 459 # Functions to call the underlying shell.
460 460
461 461 # utility to expand user variables via Itpl
462 462 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
463 463 self.user_ns))
464 464 # The first is similar to os.system, but it doesn't return a value,
465 465 # and it allows interpolation of variables in the user's namespace.
466 466 self.system = lambda cmd: shell(self.var_expand(cmd),
467 467 header='IPython system call: ',
468 468 verbose=self.rc.system_verbose)
469 469 # These are for getoutput and getoutputerror:
470 470 self.getoutput = lambda cmd: \
471 471 getoutput(self.var_expand(cmd),
472 472 header='IPython system call: ',
473 473 verbose=self.rc.system_verbose)
474 474 self.getoutputerror = lambda cmd: \
475 475 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
476 476 self.user_ns)),
477 477 header='IPython system call: ',
478 478 verbose=self.rc.system_verbose)
479 479
480 480 # RegExp for splitting line contents into pre-char//first
481 481 # word-method//rest. For clarity, each group in on one line.
482 482
483 483 # WARNING: update the regexp if the above escapes are changed, as they
484 484 # are hardwired in.
485 485
486 486 # Don't get carried away with trying to make the autocalling catch too
487 487 # much: it's better to be conservative rather than to trigger hidden
488 488 # evals() somewhere and end up causing side effects.
489 489
490 490 self.line_split = re.compile(r'^([\s*,;/])'
491 491 r'([\?\w\.]+\w*\s*)'
492 492 r'(\(?.*$)')
493 493
494 494 # Original re, keep around for a while in case changes break something
495 495 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
496 496 # r'(\s*[\?\w\.]+\w*\s*)'
497 497 # r'(\(?.*$)')
498 498
499 499 # RegExp to identify potential function names
500 500 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
501 501
502 502 # RegExp to exclude strings with this start from autocalling. In
503 503 # particular, all binary operators should be excluded, so that if foo
504 504 # is callable, foo OP bar doesn't become foo(OP bar), which is
505 505 # invalid. The characters '!=()' don't need to be checked for, as the
506 506 # _prefilter routine explicitely does so, to catch direct calls and
507 507 # rebindings of existing names.
508 508
509 509 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
510 510 # it affects the rest of the group in square brackets.
511 511 self.re_exclude_auto = re.compile(r'^[<>,&^\|\*/\+-]'
512 512 '|^is |^not |^in |^and |^or ')
513 513
514 514 # try to catch also methods for stuff in lists/tuples/dicts: off
515 515 # (experimental). For this to work, the line_split regexp would need
516 516 # to be modified so it wouldn't break things at '['. That line is
517 517 # nasty enough that I shouldn't change it until I can test it _well_.
518 518 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
519 519
520 520 # keep track of where we started running (mainly for crash post-mortem)
521 521 self.starting_dir = os.getcwd()
522 522
523 523 # Various switches which can be set
524 524 self.CACHELENGTH = 5000 # this is cheap, it's just text
525 525 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
526 526 self.banner2 = banner2
527 527
528 528 # TraceBack handlers:
529 529
530 530 # Syntax error handler.
531 531 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
532 532
533 533 # The interactive one is initialized with an offset, meaning we always
534 534 # want to remove the topmost item in the traceback, which is our own
535 535 # internal code. Valid modes: ['Plain','Context','Verbose']
536 536 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
537 537 color_scheme='NoColor',
538 538 tb_offset = 1)
539 539
540 540 # IPython itself shouldn't crash. This will produce a detailed
541 541 # post-mortem if it does. But we only install the crash handler for
542 542 # non-threaded shells, the threaded ones use a normal verbose reporter
543 543 # and lose the crash handler. This is because exceptions in the main
544 544 # thread (such as in GUI code) propagate directly to sys.excepthook,
545 545 # and there's no point in printing crash dumps for every user exception.
546 546 if self.isthreaded:
547 547 sys.excepthook = ultraTB.FormattedTB()
548 548 else:
549 549 from IPython import CrashHandler
550 550 sys.excepthook = CrashHandler.CrashHandler(self)
551 551
552 552 # The instance will store a pointer to this, so that runtime code
553 553 # (such as magics) can access it. This is because during the
554 554 # read-eval loop, it gets temporarily overwritten (to deal with GUI
555 555 # frameworks).
556 556 self.sys_excepthook = sys.excepthook
557 557
558 558 # and add any custom exception handlers the user may have specified
559 559 self.set_custom_exc(*custom_exceptions)
560 560
561 561 # Object inspector
562 562 self.inspector = OInspect.Inspector(OInspect.InspectColors,
563 563 PyColorize.ANSICodeColors,
564 564 'NoColor')
565 565 # indentation management
566 566 self.autoindent = False
567 567 self.indent_current_nsp = 0
568 568
569 569 # Make some aliases automatically
570 570 # Prepare list of shell aliases to auto-define
571 571 if os.name == 'posix':
572 572 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
573 573 'mv mv -i','rm rm -i','cp cp -i',
574 574 'cat cat','less less','clear clear',
575 575 # a better ls
576 576 'ls ls -F',
577 577 # long ls
578 578 'll ls -lF',
579 579 # color ls
580 580 'lc ls -F -o --color',
581 581 # ls normal files only
582 582 'lf ls -F -o --color %l | grep ^-',
583 583 # ls symbolic links
584 584 'lk ls -F -o --color %l | grep ^l',
585 585 # directories or links to directories,
586 586 'ldir ls -F -o --color %l | grep /$',
587 587 # things which are executable
588 588 'lx ls -F -o --color %l | grep ^-..x',
589 589 )
590 590 elif os.name in ['nt','dos']:
591 591 auto_alias = ('dir dir /on', 'ls dir /on',
592 592 'ddir dir /ad /on', 'ldir dir /ad /on',
593 593 'mkdir mkdir','rmdir rmdir','echo echo',
594 594 'ren ren','cls cls','copy copy')
595 595 else:
596 596 auto_alias = ()
597 597 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
598 598 # Call the actual (public) initializer
599 599 self.init_auto_alias()
600 600 # end __init__
601 601
602 602 def post_config_initialization(self):
603 603 """Post configuration init method
604 604
605 605 This is called after the configuration files have been processed to
606 606 'finalize' the initialization."""
607 607
608 608 rc = self.rc
609 609
610 610 # Load readline proper
611 611 if rc.readline:
612 612 self.init_readline()
613 613
614 614 # local shortcut, this is used a LOT
615 615 self.log = self.logger.log
616 616
617 617 # Initialize cache, set in/out prompts and printing system
618 618 self.outputcache = CachedOutput(self,
619 619 rc.cache_size,
620 620 rc.pprint,
621 621 input_sep = rc.separate_in,
622 622 output_sep = rc.separate_out,
623 623 output_sep2 = rc.separate_out2,
624 624 ps1 = rc.prompt_in1,
625 625 ps2 = rc.prompt_in2,
626 626 ps_out = rc.prompt_out,
627 627 pad_left = rc.prompts_pad_left)
628 628
629 629 # user may have over-ridden the default print hook:
630 630 try:
631 631 self.outputcache.__class__.display = self.hooks.display
632 632 except AttributeError:
633 633 pass
634 634
635 635 # I don't like assigning globally to sys, because it means when embedding
636 636 # instances, each embedded instance overrides the previous choice. But
637 637 # sys.displayhook seems to be called internally by exec, so I don't see a
638 638 # way around it.
639 639 sys.displayhook = self.outputcache
640 640
641 641 # Set user colors (don't do it in the constructor above so that it
642 642 # doesn't crash if colors option is invalid)
643 643 self.magic_colors(rc.colors)
644 644
645 645 # Set calling of pdb on exceptions
646 646 self.call_pdb = rc.pdb
647 647
648 648 # Load user aliases
649 649 for alias in rc.alias:
650 650 self.magic_alias(alias)
651 651
652 652 # dynamic data that survives through sessions
653 653 # XXX make the filename a config option?
654 654 persist_base = 'persist'
655 655 if rc.profile:
656 656 persist_base += '_%s' % rc.profile
657 657 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
658 658
659 659 try:
660 660 self.persist = pickle.load(file(self.persist_fname))
661 661 except:
662 662 self.persist = {}
663 663
664 664
665 665 for (key, value) in [(k[2:],v) for (k,v) in self.persist.items() if k.startswith('S:')]:
666 666 try:
667 667 obj = pickle.loads(value)
668 668 except:
669 669
670 670 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % key
671 671 print "The error was:",sys.exc_info()[0]
672 672 continue
673 673
674 674
675 675 self.user_ns[key] = obj
676 676
677 677 def add_builtins(self):
678 678 """Store ipython references into the builtin namespace.
679 679
680 680 Some parts of ipython operate via builtins injected here, which hold a
681 681 reference to IPython itself."""
682 682
683 683 builtins_new = dict(__IPYTHON__ = self,
684 684 ip_set_hook = self.set_hook,
685 685 jobs = self.jobs,
686 686 ipmagic = self.ipmagic,
687 687 ipalias = self.ipalias,
688 688 ipsystem = self.ipsystem,
689 689 )
690 690 for biname,bival in builtins_new.items():
691 691 try:
692 692 # store the orignal value so we can restore it
693 693 self.builtins_added[biname] = __builtin__.__dict__[biname]
694 694 except KeyError:
695 695 # or mark that it wasn't defined, and we'll just delete it at
696 696 # cleanup
697 697 self.builtins_added[biname] = Undefined
698 698 __builtin__.__dict__[biname] = bival
699 699
700 700 # Keep in the builtins a flag for when IPython is active. We set it
701 701 # with setdefault so that multiple nested IPythons don't clobber one
702 702 # another. Each will increase its value by one upon being activated,
703 703 # which also gives us a way to determine the nesting level.
704 704 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
705 705
706 706 def clean_builtins(self):
707 707 """Remove any builtins which might have been added by add_builtins, or
708 708 restore overwritten ones to their previous values."""
709 709 for biname,bival in self.builtins_added.items():
710 710 if bival is Undefined:
711 711 del __builtin__.__dict__[biname]
712 712 else:
713 713 __builtin__.__dict__[biname] = bival
714 714 self.builtins_added.clear()
715 715
716 716 def set_hook(self,name,hook, priority = 50):
717 717 """set_hook(name,hook) -> sets an internal IPython hook.
718 718
719 719 IPython exposes some of its internal API as user-modifiable hooks. By
720 720 adding your function to one of these hooks, you can modify IPython's
721 721 behavior to call at runtime your own routines."""
722 722
723 723 # At some point in the future, this should validate the hook before it
724 724 # accepts it. Probably at least check that the hook takes the number
725 725 # of args it's supposed to.
726 726 dp = getattr(self.hooks, name, None)
727 if name not in IPython.hooks.__all__:
728 print "Warning! Hook '%s' is not one of %s" % (name, IPython.hooks.__all__ )
727 729 if not dp:
728 730 dp = IPython.hooks.CommandChainDispatcher()
729 731
730 732 f = new.instancemethod(hook,self,self.__class__)
731 733 try:
732 734 dp.add(f,priority)
733 735 except AttributeError:
734 736 # it was not commandchain, plain old func - replace
735 737 dp = f
736 738
737 739 setattr(self.hooks,name, dp)
738 740
739 741
740 742 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
741 743
742 744 def set_custom_exc(self,exc_tuple,handler):
743 745 """set_custom_exc(exc_tuple,handler)
744 746
745 747 Set a custom exception handler, which will be called if any of the
746 748 exceptions in exc_tuple occur in the mainloop (specifically, in the
747 749 runcode() method.
748 750
749 751 Inputs:
750 752
751 753 - exc_tuple: a *tuple* of valid exceptions to call the defined
752 754 handler for. It is very important that you use a tuple, and NOT A
753 755 LIST here, because of the way Python's except statement works. If
754 756 you only want to trap a single exception, use a singleton tuple:
755 757
756 758 exc_tuple == (MyCustomException,)
757 759
758 760 - handler: this must be defined as a function with the following
759 761 basic interface: def my_handler(self,etype,value,tb).
760 762
761 763 This will be made into an instance method (via new.instancemethod)
762 764 of IPython itself, and it will be called if any of the exceptions
763 765 listed in the exc_tuple are caught. If the handler is None, an
764 766 internal basic one is used, which just prints basic info.
765 767
766 768 WARNING: by putting in your own exception handler into IPython's main
767 769 execution loop, you run a very good chance of nasty crashes. This
768 770 facility should only be used if you really know what you are doing."""
769 771
770 772 assert type(exc_tuple)==type(()) , \
771 773 "The custom exceptions must be given AS A TUPLE."
772 774
773 775 def dummy_handler(self,etype,value,tb):
774 776 print '*** Simple custom exception handler ***'
775 777 print 'Exception type :',etype
776 778 print 'Exception value:',value
777 779 print 'Traceback :',tb
778 780 print 'Source code :','\n'.join(self.buffer)
779 781
780 782 if handler is None: handler = dummy_handler
781 783
782 784 self.CustomTB = new.instancemethod(handler,self,self.__class__)
783 785 self.custom_exceptions = exc_tuple
784 786
785 787 def set_custom_completer(self,completer,pos=0):
786 788 """set_custom_completer(completer,pos=0)
787 789
788 790 Adds a new custom completer function.
789 791
790 792 The position argument (defaults to 0) is the index in the completers
791 793 list where you want the completer to be inserted."""
792 794
793 795 newcomp = new.instancemethod(completer,self.Completer,
794 796 self.Completer.__class__)
795 797 self.Completer.matchers.insert(pos,newcomp)
796 798
797 799 def _get_call_pdb(self):
798 800 return self._call_pdb
799 801
800 802 def _set_call_pdb(self,val):
801 803
802 804 if val not in (0,1,False,True):
803 805 raise ValueError,'new call_pdb value must be boolean'
804 806
805 807 # store value in instance
806 808 self._call_pdb = val
807 809
808 810 # notify the actual exception handlers
809 811 self.InteractiveTB.call_pdb = val
810 812 if self.isthreaded:
811 813 try:
812 814 self.sys_excepthook.call_pdb = val
813 815 except:
814 816 warn('Failed to activate pdb for threaded exception handler')
815 817
816 818 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
817 819 'Control auto-activation of pdb at exceptions')
818 820
819 821
820 822 # These special functions get installed in the builtin namespace, to
821 823 # provide programmatic (pure python) access to magics, aliases and system
822 824 # calls. This is important for logging, user scripting, and more.
823 825
824 826 # We are basically exposing, via normal python functions, the three
825 827 # mechanisms in which ipython offers special call modes (magics for
826 828 # internal control, aliases for direct system access via pre-selected
827 829 # names, and !cmd for calling arbitrary system commands).
828 830
829 831 def ipmagic(self,arg_s):
830 832 """Call a magic function by name.
831 833
832 834 Input: a string containing the name of the magic function to call and any
833 835 additional arguments to be passed to the magic.
834 836
835 837 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
836 838 prompt:
837 839
838 840 In[1]: %name -opt foo bar
839 841
840 842 To call a magic without arguments, simply use ipmagic('name').
841 843
842 844 This provides a proper Python function to call IPython's magics in any
843 845 valid Python code you can type at the interpreter, including loops and
844 846 compound statements. It is added by IPython to the Python builtin
845 847 namespace upon initialization."""
846 848
847 849 args = arg_s.split(' ',1)
848 850 magic_name = args[0]
849 851 magic_name = magic_name.lstrip(self.ESC_MAGIC)
850 852
851 853 try:
852 854 magic_args = args[1]
853 855 except IndexError:
854 856 magic_args = ''
855 857 fn = getattr(self,'magic_'+magic_name,None)
856 858 if fn is None:
857 859 error("Magic function `%s` not found." % magic_name)
858 860 else:
859 861 magic_args = self.var_expand(magic_args)
860 862 return fn(magic_args)
861 863
862 864 def ipalias(self,arg_s):
863 865 """Call an alias by name.
864 866
865 867 Input: a string containing the name of the alias to call and any
866 868 additional arguments to be passed to the magic.
867 869
868 870 ipalias('name -opt foo bar') is equivalent to typing at the ipython
869 871 prompt:
870 872
871 873 In[1]: name -opt foo bar
872 874
873 875 To call an alias without arguments, simply use ipalias('name').
874 876
875 877 This provides a proper Python function to call IPython's aliases in any
876 878 valid Python code you can type at the interpreter, including loops and
877 879 compound statements. It is added by IPython to the Python builtin
878 880 namespace upon initialization."""
879 881
880 882 args = arg_s.split(' ',1)
881 883 alias_name = args[0]
882 884 try:
883 885 alias_args = args[1]
884 886 except IndexError:
885 887 alias_args = ''
886 888 if alias_name in self.alias_table:
887 889 self.call_alias(alias_name,alias_args)
888 890 else:
889 891 error("Alias `%s` not found." % alias_name)
890 892
891 893 def ipsystem(self,arg_s):
892 894 """Make a system call, using IPython."""
893 895
894 896 self.system(arg_s)
895 897
896 898 def complete(self,text):
897 899 """Return a sorted list of all possible completions on text.
898 900
899 901 Inputs:
900 902
901 903 - text: a string of text to be completed on.
902 904
903 905 This is a wrapper around the completion mechanism, similar to what
904 906 readline does at the command line when the TAB key is hit. By
905 907 exposing it as a method, it can be used by other non-readline
906 908 environments (such as GUIs) for text completion.
907 909
908 910 Simple usage example:
909 911
910 912 In [1]: x = 'hello'
911 913
912 914 In [2]: __IP.complete('x.l')
913 915 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
914 916
915 917 complete = self.Completer.complete
916 918 state = 0
917 919 # use a dict so we get unique keys, since ipyhton's multiple
918 920 # completers can return duplicates.
919 921 comps = {}
920 922 while True:
921 923 newcomp = complete(text,state)
922 924 if newcomp is None:
923 925 break
924 926 comps[newcomp] = 1
925 927 state += 1
926 928 outcomps = comps.keys()
927 929 outcomps.sort()
928 930 return outcomps
929 931
930 932 def set_completer_frame(self, frame=None):
931 933 if frame:
932 934 self.Completer.namespace = frame.f_locals
933 935 self.Completer.global_namespace = frame.f_globals
934 936 else:
935 937 self.Completer.namespace = self.user_ns
936 938 self.Completer.global_namespace = self.user_global_ns
937 939
938 940 def init_auto_alias(self):
939 941 """Define some aliases automatically.
940 942
941 943 These are ALL parameter-less aliases"""
942 944
943 945 for alias,cmd in self.auto_alias:
944 946 self.alias_table[alias] = (0,cmd)
945 947
946 948 def alias_table_validate(self,verbose=0):
947 949 """Update information about the alias table.
948 950
949 951 In particular, make sure no Python keywords/builtins are in it."""
950 952
951 953 no_alias = self.no_alias
952 954 for k in self.alias_table.keys():
953 955 if k in no_alias:
954 956 del self.alias_table[k]
955 957 if verbose:
956 958 print ("Deleting alias <%s>, it's a Python "
957 959 "keyword or builtin." % k)
958 960
959 961 def set_autoindent(self,value=None):
960 962 """Set the autoindent flag, checking for readline support.
961 963
962 964 If called with no arguments, it acts as a toggle."""
963 965
964 966 if not self.has_readline:
965 967 if os.name == 'posix':
966 968 warn("The auto-indent feature requires the readline library")
967 969 self.autoindent = 0
968 970 return
969 971 if value is None:
970 972 self.autoindent = not self.autoindent
971 973 else:
972 974 self.autoindent = value
973 975
974 976 def rc_set_toggle(self,rc_field,value=None):
975 977 """Set or toggle a field in IPython's rc config. structure.
976 978
977 979 If called with no arguments, it acts as a toggle.
978 980
979 981 If called with a non-existent field, the resulting AttributeError
980 982 exception will propagate out."""
981 983
982 984 rc_val = getattr(self.rc,rc_field)
983 985 if value is None:
984 986 value = not rc_val
985 987 setattr(self.rc,rc_field,value)
986 988
987 989 def user_setup(self,ipythondir,rc_suffix,mode='install'):
988 990 """Install the user configuration directory.
989 991
990 992 Can be called when running for the first time or to upgrade the user's
991 993 .ipython/ directory with the mode parameter. Valid modes are 'install'
992 994 and 'upgrade'."""
993 995
994 996 def wait():
995 997 try:
996 998 raw_input("Please press <RETURN> to start IPython.")
997 999 except EOFError:
998 1000 print >> Term.cout
999 1001 print '*'*70
1000 1002
1001 1003 cwd = os.getcwd() # remember where we started
1002 1004 glb = glob.glob
1003 1005 print '*'*70
1004 1006 if mode == 'install':
1005 1007 print \
1006 1008 """Welcome to IPython. I will try to create a personal configuration directory
1007 1009 where you can customize many aspects of IPython's functionality in:\n"""
1008 1010 else:
1009 1011 print 'I am going to upgrade your configuration in:'
1010 1012
1011 1013 print ipythondir
1012 1014
1013 1015 rcdirend = os.path.join('IPython','UserConfig')
1014 1016 cfg = lambda d: os.path.join(d,rcdirend)
1015 1017 try:
1016 1018 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
1017 1019 except IOError:
1018 1020 warning = """
1019 1021 Installation error. IPython's directory was not found.
1020 1022
1021 1023 Check the following:
1022 1024
1023 1025 The ipython/IPython directory should be in a directory belonging to your
1024 1026 PYTHONPATH environment variable (that is, it should be in a directory
1025 1027 belonging to sys.path). You can copy it explicitly there or just link to it.
1026 1028
1027 1029 IPython will proceed with builtin defaults.
1028 1030 """
1029 1031 warn(warning)
1030 1032 wait()
1031 1033 return
1032 1034
1033 1035 if mode == 'install':
1034 1036 try:
1035 1037 shutil.copytree(rcdir,ipythondir)
1036 1038 os.chdir(ipythondir)
1037 1039 rc_files = glb("ipythonrc*")
1038 1040 for rc_file in rc_files:
1039 1041 os.rename(rc_file,rc_file+rc_suffix)
1040 1042 except:
1041 1043 warning = """
1042 1044
1043 1045 There was a problem with the installation:
1044 1046 %s
1045 1047 Try to correct it or contact the developers if you think it's a bug.
1046 1048 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
1047 1049 warn(warning)
1048 1050 wait()
1049 1051 return
1050 1052
1051 1053 elif mode == 'upgrade':
1052 1054 try:
1053 1055 os.chdir(ipythondir)
1054 1056 except:
1055 1057 print """
1056 1058 Can not upgrade: changing to directory %s failed. Details:
1057 1059 %s
1058 1060 """ % (ipythondir,sys.exc_info()[1])
1059 1061 wait()
1060 1062 return
1061 1063 else:
1062 1064 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
1063 1065 for new_full_path in sources:
1064 1066 new_filename = os.path.basename(new_full_path)
1065 1067 if new_filename.startswith('ipythonrc'):
1066 1068 new_filename = new_filename + rc_suffix
1067 1069 # The config directory should only contain files, skip any
1068 1070 # directories which may be there (like CVS)
1069 1071 if os.path.isdir(new_full_path):
1070 1072 continue
1071 1073 if os.path.exists(new_filename):
1072 1074 old_file = new_filename+'.old'
1073 1075 if os.path.exists(old_file):
1074 1076 os.remove(old_file)
1075 1077 os.rename(new_filename,old_file)
1076 1078 shutil.copy(new_full_path,new_filename)
1077 1079 else:
1078 1080 raise ValueError,'unrecognized mode for install:',`mode`
1079 1081
1080 1082 # Fix line-endings to those native to each platform in the config
1081 1083 # directory.
1082 1084 try:
1083 1085 os.chdir(ipythondir)
1084 1086 except:
1085 1087 print """
1086 1088 Problem: changing to directory %s failed.
1087 1089 Details:
1088 1090 %s
1089 1091
1090 1092 Some configuration files may have incorrect line endings. This should not
1091 1093 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
1092 1094 wait()
1093 1095 else:
1094 1096 for fname in glb('ipythonrc*'):
1095 1097 try:
1096 1098 native_line_ends(fname,backup=0)
1097 1099 except IOError:
1098 1100 pass
1099 1101
1100 1102 if mode == 'install':
1101 1103 print """
1102 1104 Successful installation!
1103 1105
1104 1106 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
1105 1107 IPython manual (there are both HTML and PDF versions supplied with the
1106 1108 distribution) to make sure that your system environment is properly configured
1107 1109 to take advantage of IPython's features.
1108 1110
1109 1111 Important note: the configuration system has changed! The old system is
1110 1112 still in place, but its setting may be partly overridden by the settings in
1111 1113 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file
1112 1114 if some of the new settings bother you.
1113 1115
1114 1116 """
1115 1117 else:
1116 1118 print """
1117 1119 Successful upgrade!
1118 1120
1119 1121 All files in your directory:
1120 1122 %(ipythondir)s
1121 1123 which would have been overwritten by the upgrade were backed up with a .old
1122 1124 extension. If you had made particular customizations in those files you may
1123 1125 want to merge them back into the new files.""" % locals()
1124 1126 wait()
1125 1127 os.chdir(cwd)
1126 1128 # end user_setup()
1127 1129
1128 1130 def atexit_operations(self):
1129 1131 """This will be executed at the time of exit.
1130 1132
1131 1133 Saving of persistent data should be performed here. """
1132 1134
1133 1135 #print '*** IPython exit cleanup ***' # dbg
1134 1136 # input history
1135 1137 self.savehist()
1136 1138
1137 1139 # Cleanup all tempfiles left around
1138 1140 for tfile in self.tempfiles:
1139 1141 try:
1140 1142 os.unlink(tfile)
1141 1143 except OSError:
1142 1144 pass
1143 1145
1144 1146 # save the "persistent data" catch-all dictionary
1145 1147 try:
1146 1148 pickle.dump(self.persist, open(self.persist_fname,"w"))
1147 1149 except:
1148 1150 print "*** ERROR *** persistent data saving failed."
1149 1151
1150 1152 def savehist(self):
1151 1153 """Save input history to a file (via readline library)."""
1152 1154 try:
1153 1155 self.readline.write_history_file(self.histfile)
1154 1156 except:
1155 1157 print 'Unable to save IPython command history to file: ' + \
1156 1158 `self.histfile`
1157 1159
1158 1160 def pre_readline(self):
1159 1161 """readline hook to be used at the start of each line.
1160 1162
1161 1163 Currently it handles auto-indent only."""
1162 1164
1163 1165 #debugx('self.indent_current_nsp','pre_readline:')
1164 1166 self.readline.insert_text(self.indent_current_str())
1165 1167
1166 1168 def init_readline(self):
1167 1169 """Command history completion/saving/reloading."""
1168 1170 try:
1169 1171 import readline
1170 1172 except ImportError:
1171 1173 self.has_readline = 0
1172 1174 self.readline = None
1173 1175 # no point in bugging windows users with this every time:
1174 1176 if os.name == 'posix':
1175 1177 warn('Readline services not available on this platform.')
1176 1178 else:
1177 1179 import atexit
1178 1180 from IPython.completer import IPCompleter
1179 1181 self.Completer = IPCompleter(self,
1180 1182 self.user_ns,
1181 1183 self.user_global_ns,
1182 1184 self.rc.readline_omit__names,
1183 1185 self.alias_table)
1184 1186
1185 1187 # Platform-specific configuration
1186 1188 if os.name == 'nt':
1187 1189 self.readline_startup_hook = readline.set_pre_input_hook
1188 1190 else:
1189 1191 self.readline_startup_hook = readline.set_startup_hook
1190 1192
1191 1193 # Load user's initrc file (readline config)
1192 1194 inputrc_name = os.environ.get('INPUTRC')
1193 1195 if inputrc_name is None:
1194 1196 home_dir = get_home_dir()
1195 1197 if home_dir is not None:
1196 1198 inputrc_name = os.path.join(home_dir,'.inputrc')
1197 1199 if os.path.isfile(inputrc_name):
1198 1200 try:
1199 1201 readline.read_init_file(inputrc_name)
1200 1202 except:
1201 1203 warn('Problems reading readline initialization file <%s>'
1202 1204 % inputrc_name)
1203 1205
1204 1206 self.has_readline = 1
1205 1207 self.readline = readline
1206 1208 # save this in sys so embedded copies can restore it properly
1207 1209 sys.ipcompleter = self.Completer.complete
1208 1210 readline.set_completer(self.Completer.complete)
1209 1211
1210 1212 # Configure readline according to user's prefs
1211 1213 for rlcommand in self.rc.readline_parse_and_bind:
1212 1214 readline.parse_and_bind(rlcommand)
1213 1215
1214 1216 # remove some chars from the delimiters list
1215 1217 delims = readline.get_completer_delims()
1216 1218 delims = delims.translate(string._idmap,
1217 1219 self.rc.readline_remove_delims)
1218 1220 readline.set_completer_delims(delims)
1219 1221 # otherwise we end up with a monster history after a while:
1220 1222 readline.set_history_length(1000)
1221 1223 try:
1222 1224 #print '*** Reading readline history' # dbg
1223 1225 readline.read_history_file(self.histfile)
1224 1226 except IOError:
1225 1227 pass # It doesn't exist yet.
1226 1228
1227 1229 atexit.register(self.atexit_operations)
1228 1230 del atexit
1229 1231
1230 1232 # Configure auto-indent for all platforms
1231 1233 self.set_autoindent(self.rc.autoindent)
1232 1234
1233 1235 def _should_recompile(self,e):
1234 1236 """Utility routine for edit_syntax_error"""
1235 1237
1236 1238 if e.filename in ('<ipython console>','<input>','<string>',
1237 1239 '<console>',None):
1238 1240
1239 1241 return False
1240 1242 try:
1241 1243 if not ask_yes_no('Return to editor to correct syntax error? '
1242 1244 '[Y/n] ','y'):
1243 1245 return False
1244 1246 except EOFError:
1245 1247 return False
1246 1248
1247 1249 def int0(x):
1248 1250 try:
1249 1251 return int(x)
1250 1252 except TypeError:
1251 1253 return 0
1252 1254 # always pass integer line and offset values to editor hook
1253 1255 self.hooks.fix_error_editor(e.filename,
1254 1256 int0(e.lineno),int0(e.offset),e.msg)
1255 1257 return True
1256 1258
1257 1259 def edit_syntax_error(self):
1258 1260 """The bottom half of the syntax error handler called in the main loop.
1259 1261
1260 1262 Loop until syntax error is fixed or user cancels.
1261 1263 """
1262 1264
1263 1265 while self.SyntaxTB.last_syntax_error:
1264 1266 # copy and clear last_syntax_error
1265 1267 err = self.SyntaxTB.clear_err_state()
1266 1268 if not self._should_recompile(err):
1267 1269 return
1268 1270 try:
1269 1271 # may set last_syntax_error again if a SyntaxError is raised
1270 1272 self.safe_execfile(err.filename,self.shell.user_ns)
1271 1273 except:
1272 1274 self.showtraceback()
1273 1275 else:
1274 1276 f = file(err.filename)
1275 1277 try:
1276 1278 sys.displayhook(f.read())
1277 1279 finally:
1278 1280 f.close()
1279 1281
1280 1282 def showsyntaxerror(self, filename=None):
1281 1283 """Display the syntax error that just occurred.
1282 1284
1283 1285 This doesn't display a stack trace because there isn't one.
1284 1286
1285 1287 If a filename is given, it is stuffed in the exception instead
1286 1288 of what was there before (because Python's parser always uses
1287 1289 "<string>" when reading from a string).
1288 1290 """
1289 1291 etype, value, last_traceback = sys.exc_info()
1290 1292 if filename and etype is SyntaxError:
1291 1293 # Work hard to stuff the correct filename in the exception
1292 1294 try:
1293 1295 msg, (dummy_filename, lineno, offset, line) = value
1294 1296 except:
1295 1297 # Not the format we expect; leave it alone
1296 1298 pass
1297 1299 else:
1298 1300 # Stuff in the right filename
1299 1301 try:
1300 1302 # Assume SyntaxError is a class exception
1301 1303 value = SyntaxError(msg, (filename, lineno, offset, line))
1302 1304 except:
1303 1305 # If that failed, assume SyntaxError is a string
1304 1306 value = msg, (filename, lineno, offset, line)
1305 1307 self.SyntaxTB(etype,value,[])
1306 1308
1307 1309 def debugger(self):
1308 1310 """Call the pdb debugger."""
1309 1311
1310 1312 if not self.rc.pdb:
1311 1313 return
1312 1314 pdb.pm()
1313 1315
1314 1316 def showtraceback(self,exc_tuple = None,filename=None):
1315 1317 """Display the exception that just occurred."""
1316 1318
1317 1319 # Though this won't be called by syntax errors in the input line,
1318 1320 # there may be SyntaxError cases whith imported code.
1319 1321 if exc_tuple is None:
1320 1322 type, value, tb = sys.exc_info()
1321 1323 else:
1322 1324 type, value, tb = exc_tuple
1323 1325 if type is SyntaxError:
1324 1326 self.showsyntaxerror(filename)
1325 1327 else:
1326 1328 self.InteractiveTB()
1327 1329 if self.InteractiveTB.call_pdb and self.has_readline:
1328 1330 # pdb mucks up readline, fix it back
1329 1331 self.readline.set_completer(self.Completer.complete)
1330 1332
1331 1333 def mainloop(self,banner=None):
1332 1334 """Creates the local namespace and starts the mainloop.
1333 1335
1334 1336 If an optional banner argument is given, it will override the
1335 1337 internally created default banner."""
1336 1338
1337 1339 if self.rc.c: # Emulate Python's -c option
1338 1340 self.exec_init_cmd()
1339 1341 if banner is None:
1340 1342 if self.rc.banner:
1341 1343 banner = self.BANNER+self.banner2
1342 1344 else:
1343 1345 banner = ''
1344 1346 self.interact(banner)
1345 1347
1346 1348 def exec_init_cmd(self):
1347 1349 """Execute a command given at the command line.
1348 1350
1349 1351 This emulates Python's -c option."""
1350 1352
1351 1353 sys.argv = ['-c']
1352 1354 self.push(self.rc.c)
1353 1355
1354 1356 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1355 1357 """Embeds IPython into a running python program.
1356 1358
1357 1359 Input:
1358 1360
1359 1361 - header: An optional header message can be specified.
1360 1362
1361 1363 - local_ns, global_ns: working namespaces. If given as None, the
1362 1364 IPython-initialized one is updated with __main__.__dict__, so that
1363 1365 program variables become visible but user-specific configuration
1364 1366 remains possible.
1365 1367
1366 1368 - stack_depth: specifies how many levels in the stack to go to
1367 1369 looking for namespaces (when local_ns and global_ns are None). This
1368 1370 allows an intermediate caller to make sure that this function gets
1369 1371 the namespace from the intended level in the stack. By default (0)
1370 1372 it will get its locals and globals from the immediate caller.
1371 1373
1372 1374 Warning: it's possible to use this in a program which is being run by
1373 1375 IPython itself (via %run), but some funny things will happen (a few
1374 1376 globals get overwritten). In the future this will be cleaned up, as
1375 1377 there is no fundamental reason why it can't work perfectly."""
1376 1378
1377 1379 # Get locals and globals from caller
1378 1380 if local_ns is None or global_ns is None:
1379 1381 call_frame = sys._getframe(stack_depth).f_back
1380 1382
1381 1383 if local_ns is None:
1382 1384 local_ns = call_frame.f_locals
1383 1385 if global_ns is None:
1384 1386 global_ns = call_frame.f_globals
1385 1387
1386 1388 # Update namespaces and fire up interpreter
1387 1389
1388 1390 # The global one is easy, we can just throw it in
1389 1391 self.user_global_ns = global_ns
1390 1392
1391 1393 # but the user/local one is tricky: ipython needs it to store internal
1392 1394 # data, but we also need the locals. We'll copy locals in the user
1393 1395 # one, but will track what got copied so we can delete them at exit.
1394 1396 # This is so that a later embedded call doesn't see locals from a
1395 1397 # previous call (which most likely existed in a separate scope).
1396 1398 local_varnames = local_ns.keys()
1397 1399 self.user_ns.update(local_ns)
1398 1400
1399 1401 # Patch for global embedding to make sure that things don't overwrite
1400 1402 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1401 1403 # FIXME. Test this a bit more carefully (the if.. is new)
1402 1404 if local_ns is None and global_ns is None:
1403 1405 self.user_global_ns.update(__main__.__dict__)
1404 1406
1405 1407 # make sure the tab-completer has the correct frame information, so it
1406 1408 # actually completes using the frame's locals/globals
1407 1409 self.set_completer_frame()
1408 1410
1409 1411 # before activating the interactive mode, we need to make sure that
1410 1412 # all names in the builtin namespace needed by ipython point to
1411 1413 # ourselves, and not to other instances.
1412 1414 self.add_builtins()
1413 1415
1414 1416 self.interact(header)
1415 1417
1416 1418 # now, purge out the user namespace from anything we might have added
1417 1419 # from the caller's local namespace
1418 1420 delvar = self.user_ns.pop
1419 1421 for var in local_varnames:
1420 1422 delvar(var,None)
1421 1423 # and clean builtins we may have overridden
1422 1424 self.clean_builtins()
1423 1425
1424 1426 def interact(self, banner=None):
1425 1427 """Closely emulate the interactive Python console.
1426 1428
1427 1429 The optional banner argument specify the banner to print
1428 1430 before the first interaction; by default it prints a banner
1429 1431 similar to the one printed by the real Python interpreter,
1430 1432 followed by the current class name in parentheses (so as not
1431 1433 to confuse this with the real interpreter -- since it's so
1432 1434 close!).
1433 1435
1434 1436 """
1435 1437 cprt = 'Type "copyright", "credits" or "license" for more information.'
1436 1438 if banner is None:
1437 1439 self.write("Python %s on %s\n%s\n(%s)\n" %
1438 1440 (sys.version, sys.platform, cprt,
1439 1441 self.__class__.__name__))
1440 1442 else:
1441 1443 self.write(banner)
1442 1444
1443 1445 more = 0
1444 1446
1445 1447 # Mark activity in the builtins
1446 1448 __builtin__.__dict__['__IPYTHON__active'] += 1
1447 1449
1448 1450 # exit_now is set by a call to %Exit or %Quit
1449 1451 self.exit_now = False
1450 1452 while not self.exit_now:
1451 1453
1452 1454 try:
1453 1455 if more:
1454 1456 prompt = self.outputcache.prompt2
1455 1457 if self.autoindent:
1456 1458 self.readline_startup_hook(self.pre_readline)
1457 1459 else:
1458 1460 prompt = self.outputcache.prompt1
1459 1461 try:
1460 1462 line = self.raw_input(prompt,more)
1461 1463 if self.autoindent:
1462 1464 self.readline_startup_hook(None)
1463 1465 except EOFError:
1464 1466 if self.autoindent:
1465 1467 self.readline_startup_hook(None)
1466 1468 self.write("\n")
1467 1469 self.exit()
1468 1470 except:
1469 1471 # exceptions here are VERY RARE, but they can be triggered
1470 1472 # asynchronously by signal handlers, for example.
1471 1473 self.showtraceback()
1472 1474 else:
1473 1475 more = self.push(line)
1474 1476
1475 1477 if (self.SyntaxTB.last_syntax_error and
1476 1478 self.rc.autoedit_syntax):
1477 1479 self.edit_syntax_error()
1478 1480
1479 1481 except KeyboardInterrupt:
1480 1482 self.write("\nKeyboardInterrupt\n")
1481 1483 self.resetbuffer()
1482 1484 more = 0
1483 1485 # keep cache in sync with the prompt counter:
1484 1486 self.outputcache.prompt_count -= 1
1485 1487
1486 1488 if self.autoindent:
1487 1489 self.indent_current_nsp = 0
1488 1490
1489 1491 except bdb.BdbQuit:
1490 1492 warn("The Python debugger has exited with a BdbQuit exception.\n"
1491 1493 "Because of how pdb handles the stack, it is impossible\n"
1492 1494 "for IPython to properly format this particular exception.\n"
1493 1495 "IPython will resume normal operation.")
1494 1496
1495 1497 # We are off again...
1496 1498 __builtin__.__dict__['__IPYTHON__active'] -= 1
1497 1499
1498 1500 def excepthook(self, type, value, tb):
1499 1501 """One more defense for GUI apps that call sys.excepthook.
1500 1502
1501 1503 GUI frameworks like wxPython trap exceptions and call
1502 1504 sys.excepthook themselves. I guess this is a feature that
1503 1505 enables them to keep running after exceptions that would
1504 1506 otherwise kill their mainloop. This is a bother for IPython
1505 1507 which excepts to catch all of the program exceptions with a try:
1506 1508 except: statement.
1507 1509
1508 1510 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1509 1511 any app directly invokes sys.excepthook, it will look to the user like
1510 1512 IPython crashed. In order to work around this, we can disable the
1511 1513 CrashHandler and replace it with this excepthook instead, which prints a
1512 1514 regular traceback using our InteractiveTB. In this fashion, apps which
1513 1515 call sys.excepthook will generate a regular-looking exception from
1514 1516 IPython, and the CrashHandler will only be triggered by real IPython
1515 1517 crashes.
1516 1518
1517 1519 This hook should be used sparingly, only in places which are not likely
1518 1520 to be true IPython errors.
1519 1521 """
1520 1522
1521 1523 self.InteractiveTB(type, value, tb, tb_offset=0)
1522 1524 if self.InteractiveTB.call_pdb and self.has_readline:
1523 1525 self.readline.set_completer(self.Completer.complete)
1524 1526
1525 1527 def call_alias(self,alias,rest=''):
1526 1528 """Call an alias given its name and the rest of the line.
1527 1529
1528 1530 This function MUST be given a proper alias, because it doesn't make
1529 1531 any checks when looking up into the alias table. The caller is
1530 1532 responsible for invoking it only with a valid alias."""
1531 1533
1532 1534 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1533 1535 nargs,cmd = self.alias_table[alias]
1534 1536 # Expand the %l special to be the user's input line
1535 1537 if cmd.find('%l') >= 0:
1536 1538 cmd = cmd.replace('%l',rest)
1537 1539 rest = ''
1538 1540 if nargs==0:
1539 1541 # Simple, argument-less aliases
1540 1542 cmd = '%s %s' % (cmd,rest)
1541 1543 else:
1542 1544 # Handle aliases with positional arguments
1543 1545 args = rest.split(None,nargs)
1544 1546 if len(args)< nargs:
1545 1547 error('Alias <%s> requires %s arguments, %s given.' %
1546 1548 (alias,nargs,len(args)))
1547 1549 return
1548 1550 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1549 1551 # Now call the macro, evaluating in the user's namespace
1550 1552 try:
1551 1553 self.system(cmd)
1552 1554 except:
1553 1555 self.showtraceback()
1554 1556
1555 1557 def indent_current_str(self):
1556 1558 """return the current level of indentation as a string"""
1557 1559 return self.indent_current_nsp * ' '
1558 1560
1559 1561 def autoindent_update(self,line):
1560 1562 """Keep track of the indent level."""
1561 1563
1562 1564 #debugx('line')
1563 1565 #debugx('self.indent_current_nsp')
1564 1566 if self.autoindent:
1565 1567 if line:
1566 1568 inisp = num_ini_spaces(line)
1567 1569 if inisp < self.indent_current_nsp:
1568 1570 self.indent_current_nsp = inisp
1569 1571
1570 1572 if line[-1] == ':':
1571 1573 self.indent_current_nsp += 4
1572 1574 elif dedent_re.match(line):
1573 1575 self.indent_current_nsp -= 4
1574 1576 else:
1575 1577 self.indent_current_nsp = 0
1576 1578
1577 1579 def runlines(self,lines):
1578 1580 """Run a string of one or more lines of source.
1579 1581
1580 1582 This method is capable of running a string containing multiple source
1581 1583 lines, as if they had been entered at the IPython prompt. Since it
1582 1584 exposes IPython's processing machinery, the given strings can contain
1583 1585 magic calls (%magic), special shell access (!cmd), etc."""
1584 1586
1585 1587 # We must start with a clean buffer, in case this is run from an
1586 1588 # interactive IPython session (via a magic, for example).
1587 1589 self.resetbuffer()
1588 1590 lines = lines.split('\n')
1589 1591 more = 0
1590 1592 for line in lines:
1591 1593 # skip blank lines so we don't mess up the prompt counter, but do
1592 1594 # NOT skip even a blank line if we are in a code block (more is
1593 1595 # true)
1594 1596 if line or more:
1595 1597 more = self.push(self.prefilter(line,more))
1596 1598 # IPython's runsource returns None if there was an error
1597 1599 # compiling the code. This allows us to stop processing right
1598 1600 # away, so the user gets the error message at the right place.
1599 1601 if more is None:
1600 1602 break
1601 1603 # final newline in case the input didn't have it, so that the code
1602 1604 # actually does get executed
1603 1605 if more:
1604 1606 self.push('\n')
1605 1607
1606 1608 def runsource(self, source, filename='<input>', symbol='single'):
1607 1609 """Compile and run some source in the interpreter.
1608 1610
1609 1611 Arguments are as for compile_command().
1610 1612
1611 1613 One several things can happen:
1612 1614
1613 1615 1) The input is incorrect; compile_command() raised an
1614 1616 exception (SyntaxError or OverflowError). A syntax traceback
1615 1617 will be printed by calling the showsyntaxerror() method.
1616 1618
1617 1619 2) The input is incomplete, and more input is required;
1618 1620 compile_command() returned None. Nothing happens.
1619 1621
1620 1622 3) The input is complete; compile_command() returned a code
1621 1623 object. The code is executed by calling self.runcode() (which
1622 1624 also handles run-time exceptions, except for SystemExit).
1623 1625
1624 1626 The return value is:
1625 1627
1626 1628 - True in case 2
1627 1629
1628 1630 - False in the other cases, unless an exception is raised, where
1629 1631 None is returned instead. This can be used by external callers to
1630 1632 know whether to continue feeding input or not.
1631 1633
1632 1634 The return value can be used to decide whether to use sys.ps1 or
1633 1635 sys.ps2 to prompt the next line."""
1634 1636
1635 1637 try:
1636 1638 code = self.compile(source,filename,symbol)
1637 1639 except (OverflowError, SyntaxError, ValueError):
1638 1640 # Case 1
1639 1641 self.showsyntaxerror(filename)
1640 1642 return None
1641 1643
1642 1644 if code is None:
1643 1645 # Case 2
1644 1646 return True
1645 1647
1646 1648 # Case 3
1647 1649 # We store the code object so that threaded shells and
1648 1650 # custom exception handlers can access all this info if needed.
1649 1651 # The source corresponding to this can be obtained from the
1650 1652 # buffer attribute as '\n'.join(self.buffer).
1651 1653 self.code_to_run = code
1652 1654 # now actually execute the code object
1653 1655 if self.runcode(code) == 0:
1654 1656 return False
1655 1657 else:
1656 1658 return None
1657 1659
1658 1660 def runcode(self,code_obj):
1659 1661 """Execute a code object.
1660 1662
1661 1663 When an exception occurs, self.showtraceback() is called to display a
1662 1664 traceback.
1663 1665
1664 1666 Return value: a flag indicating whether the code to be run completed
1665 1667 successfully:
1666 1668
1667 1669 - 0: successful execution.
1668 1670 - 1: an error occurred.
1669 1671 """
1670 1672
1671 1673 # Set our own excepthook in case the user code tries to call it
1672 1674 # directly, so that the IPython crash handler doesn't get triggered
1673 1675 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1674 1676
1675 1677 # we save the original sys.excepthook in the instance, in case config
1676 1678 # code (such as magics) needs access to it.
1677 1679 self.sys_excepthook = old_excepthook
1678 1680 outflag = 1 # happens in more places, so it's easier as default
1679 1681 try:
1680 1682 try:
1681 1683 # Embedded instances require separate global/local namespaces
1682 1684 # so they can see both the surrounding (local) namespace and
1683 1685 # the module-level globals when called inside another function.
1684 1686 if self.embedded:
1685 1687 exec code_obj in self.user_global_ns, self.user_ns
1686 1688 # Normal (non-embedded) instances should only have a single
1687 1689 # namespace for user code execution, otherwise functions won't
1688 1690 # see interactive top-level globals.
1689 1691 else:
1690 1692 exec code_obj in self.user_ns
1691 1693 finally:
1692 1694 # Reset our crash handler in place
1693 1695 sys.excepthook = old_excepthook
1694 1696 except SystemExit:
1695 1697 self.resetbuffer()
1696 1698 self.showtraceback()
1697 1699 warn("Type exit or quit to exit IPython "
1698 1700 "(%Exit or %Quit do so unconditionally).",level=1)
1699 1701 except self.custom_exceptions:
1700 1702 etype,value,tb = sys.exc_info()
1701 1703 self.CustomTB(etype,value,tb)
1702 1704 except:
1703 1705 self.showtraceback()
1704 1706 else:
1705 1707 outflag = 0
1706 1708 if softspace(sys.stdout, 0):
1707 1709 print
1708 1710 # Flush out code object which has been run (and source)
1709 1711 self.code_to_run = None
1710 1712 return outflag
1711 1713
1712 1714 def push(self, line):
1713 1715 """Push a line to the interpreter.
1714 1716
1715 1717 The line should not have a trailing newline; it may have
1716 1718 internal newlines. The line is appended to a buffer and the
1717 1719 interpreter's runsource() method is called with the
1718 1720 concatenated contents of the buffer as source. If this
1719 1721 indicates that the command was executed or invalid, the buffer
1720 1722 is reset; otherwise, the command is incomplete, and the buffer
1721 1723 is left as it was after the line was appended. The return
1722 1724 value is 1 if more input is required, 0 if the line was dealt
1723 1725 with in some way (this is the same as runsource()).
1724 1726 """
1725 1727
1726 1728 # autoindent management should be done here, and not in the
1727 1729 # interactive loop, since that one is only seen by keyboard input. We
1728 1730 # need this done correctly even for code run via runlines (which uses
1729 1731 # push).
1730 1732
1731 1733 #print 'push line: <%s>' % line # dbg
1732 1734 self.autoindent_update(line)
1733 1735
1734 1736 self.buffer.append(line)
1735 1737 more = self.runsource('\n'.join(self.buffer), self.filename)
1736 1738 if not more:
1737 1739 self.resetbuffer()
1738 1740 return more
1739 1741
1740 1742 def resetbuffer(self):
1741 1743 """Reset the input buffer."""
1742 1744 self.buffer[:] = []
1743 1745
1744 1746 def raw_input(self,prompt='',continue_prompt=False):
1745 1747 """Write a prompt and read a line.
1746 1748
1747 1749 The returned line does not include the trailing newline.
1748 1750 When the user enters the EOF key sequence, EOFError is raised.
1749 1751
1750 1752 Optional inputs:
1751 1753
1752 1754 - prompt(''): a string to be printed to prompt the user.
1753 1755
1754 1756 - continue_prompt(False): whether this line is the first one or a
1755 1757 continuation in a sequence of inputs.
1756 1758 """
1757 1759
1758 1760 line = raw_input_original(prompt)
1759 1761 # Try to be reasonably smart about not re-indenting pasted input more
1760 1762 # than necessary. We do this by trimming out the auto-indent initial
1761 1763 # spaces, if the user's actual input started itself with whitespace.
1762 1764 #debugx('self.buffer[-1]')
1763 1765
1764 1766 if self.autoindent:
1765 1767 if num_ini_spaces(line) > self.indent_current_nsp:
1766 1768 line = line[self.indent_current_nsp:]
1767 1769 self.indent_current_nsp = 0
1768 1770
1769 1771 # store the unfiltered input before the user has any chance to modify
1770 1772 # it.
1771 1773 if line.strip():
1772 1774 if continue_prompt:
1773 1775 self.input_hist_raw[-1] += '%s\n' % line
1774 1776 else:
1775 1777 self.input_hist_raw.append('%s\n' % line)
1776 1778
1777 1779 lineout = self.prefilter(line,continue_prompt)
1778 1780 return lineout
1779 1781
1780 1782 def split_user_input(self,line):
1781 1783 """Split user input into pre-char, function part and rest."""
1782 1784
1783 1785 lsplit = self.line_split.match(line)
1784 1786 if lsplit is None: # no regexp match returns None
1785 1787 try:
1786 1788 iFun,theRest = line.split(None,1)
1787 1789 except ValueError:
1788 1790 iFun,theRest = line,''
1789 1791 pre = re.match('^(\s*)(.*)',line).groups()[0]
1790 1792 else:
1791 1793 pre,iFun,theRest = lsplit.groups()
1792 1794
1793 1795 #print 'line:<%s>' % line # dbg
1794 1796 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1795 1797 return pre,iFun.strip(),theRest
1796 1798
1797 1799 def _prefilter(self, line, continue_prompt):
1798 1800 """Calls different preprocessors, depending on the form of line."""
1799 1801
1800 1802 # All handlers *must* return a value, even if it's blank ('').
1801 1803
1802 1804 # Lines are NOT logged here. Handlers should process the line as
1803 1805 # needed, update the cache AND log it (so that the input cache array
1804 1806 # stays synced).
1805 1807
1806 1808 # This function is _very_ delicate, and since it's also the one which
1807 1809 # determines IPython's response to user input, it must be as efficient
1808 1810 # as possible. For this reason it has _many_ returns in it, trying
1809 1811 # always to exit as quickly as it can figure out what it needs to do.
1810 1812
1811 1813 # This function is the main responsible for maintaining IPython's
1812 1814 # behavior respectful of Python's semantics. So be _very_ careful if
1813 1815 # making changes to anything here.
1814 1816
1815 1817 #.....................................................................
1816 1818 # Code begins
1817 1819
1818 1820 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1819 1821
1820 1822 # save the line away in case we crash, so the post-mortem handler can
1821 1823 # record it
1822 1824 self._last_input_line = line
1823 1825
1824 1826 #print '***line: <%s>' % line # dbg
1825 1827
1826 1828 # the input history needs to track even empty lines
1827 1829 stripped = line.strip()
1828 1830
1829 1831 if not stripped:
1830 1832 if not continue_prompt:
1831 1833 self.outputcache.prompt_count -= 1
1832 1834 return self.handle_normal(line,continue_prompt)
1833 1835 #return self.handle_normal('',continue_prompt)
1834 1836
1835 1837 # print '***cont',continue_prompt # dbg
1836 1838 # special handlers are only allowed for single line statements
1837 1839 if continue_prompt and not self.rc.multi_line_specials:
1838 1840 return self.handle_normal(line,continue_prompt)
1839 1841
1840 1842
1841 1843 # For the rest, we need the structure of the input
1842 1844 pre,iFun,theRest = self.split_user_input(line)
1843 1845
1844 1846 # See whether any pre-existing handler can take care of it
1845 1847
1846 1848 rewritten = self.hooks.input_prefilter(stripped)
1847 1849 if rewritten != stripped: # ok, some prefilter did something
1848 1850 rewritten = pre + rewritten # add indentation
1849 1851 return self.handle_normal(rewritten)
1850 1852
1851 1853
1852 1854
1853 1855
1854 1856 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1855 1857
1856 1858 # First check for explicit escapes in the last/first character
1857 1859 handler = None
1858 1860 if line[-1] == self.ESC_HELP:
1859 1861 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1860 1862 if handler is None:
1861 1863 # look at the first character of iFun, NOT of line, so we skip
1862 1864 # leading whitespace in multiline input
1863 1865 handler = self.esc_handlers.get(iFun[0:1])
1864 1866 if handler is not None:
1865 1867 return handler(line,continue_prompt,pre,iFun,theRest)
1866 1868 # Emacs ipython-mode tags certain input lines
1867 1869 if line.endswith('# PYTHON-MODE'):
1868 1870 return self.handle_emacs(line,continue_prompt)
1869 1871
1870 1872 # Next, check if we can automatically execute this thing
1871 1873
1872 1874 # Allow ! in multi-line statements if multi_line_specials is on:
1873 1875 if continue_prompt and self.rc.multi_line_specials and \
1874 1876 iFun.startswith(self.ESC_SHELL):
1875 1877 return self.handle_shell_escape(line,continue_prompt,
1876 1878 pre=pre,iFun=iFun,
1877 1879 theRest=theRest)
1878 1880
1879 1881 # Let's try to find if the input line is a magic fn
1880 1882 oinfo = None
1881 1883 if hasattr(self,'magic_'+iFun):
1882 1884 # WARNING: _ofind uses getattr(), so it can consume generators and
1883 1885 # cause other side effects.
1884 1886 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1885 1887 if oinfo['ismagic']:
1886 1888 # Be careful not to call magics when a variable assignment is
1887 1889 # being made (ls='hi', for example)
1888 1890 if self.rc.automagic and \
1889 1891 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1890 1892 (self.rc.multi_line_specials or not continue_prompt):
1891 1893 return self.handle_magic(line,continue_prompt,
1892 1894 pre,iFun,theRest)
1893 1895 else:
1894 1896 return self.handle_normal(line,continue_prompt)
1895 1897
1896 1898 # If the rest of the line begins with an (in)equality, assginment or
1897 1899 # function call, we should not call _ofind but simply execute it.
1898 1900 # This avoids spurious geattr() accesses on objects upon assignment.
1899 1901 #
1900 1902 # It also allows users to assign to either alias or magic names true
1901 1903 # python variables (the magic/alias systems always take second seat to
1902 1904 # true python code).
1903 1905 if theRest and theRest[0] in '!=()':
1904 1906 return self.handle_normal(line,continue_prompt)
1905 1907
1906 1908 if oinfo is None:
1907 1909 # let's try to ensure that _oinfo is ONLY called when autocall is
1908 1910 # on. Since it has inevitable potential side effects, at least
1909 1911 # having autocall off should be a guarantee to the user that no
1910 1912 # weird things will happen.
1911 1913
1912 1914 if self.rc.autocall:
1913 1915 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1914 1916 else:
1915 1917 # in this case, all that's left is either an alias or
1916 1918 # processing the line normally.
1917 1919 if iFun in self.alias_table:
1918 1920 return self.handle_alias(line,continue_prompt,
1919 1921 pre,iFun,theRest)
1920 1922
1921 1923 else:
1922 1924 return self.handle_normal(line,continue_prompt)
1923 1925
1924 1926 if not oinfo['found']:
1925 1927 return self.handle_normal(line,continue_prompt)
1926 1928 else:
1927 1929 #print 'pre<%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1928 1930 if oinfo['isalias']:
1929 1931 return self.handle_alias(line,continue_prompt,
1930 1932 pre,iFun,theRest)
1931 1933
1932 1934 if (self.rc.autocall
1933 1935 and
1934 1936 (
1935 1937 #only consider exclusion re if not "," or ";" autoquoting
1936 1938 (pre == self.ESC_QUOTE or pre == self.ESC_QUOTE2) or
1937 1939 (not self.re_exclude_auto.match(theRest)))
1938 1940 and
1939 1941 self.re_fun_name.match(iFun) and
1940 1942 callable(oinfo['obj'])) :
1941 1943 #print 'going auto' # dbg
1942 1944 return self.handle_auto(line,continue_prompt,
1943 1945 pre,iFun,theRest,oinfo['obj'])
1944 1946 else:
1945 1947 #print 'was callable?', callable(oinfo['obj']) # dbg
1946 1948 return self.handle_normal(line,continue_prompt)
1947 1949
1948 1950 # If we get here, we have a normal Python line. Log and return.
1949 1951 return self.handle_normal(line,continue_prompt)
1950 1952
1951 1953 def _prefilter_dumb(self, line, continue_prompt):
1952 1954 """simple prefilter function, for debugging"""
1953 1955 return self.handle_normal(line,continue_prompt)
1954 1956
1955 1957 # Set the default prefilter() function (this can be user-overridden)
1956 1958 prefilter = _prefilter
1957 1959
1958 1960 def handle_normal(self,line,continue_prompt=None,
1959 1961 pre=None,iFun=None,theRest=None):
1960 1962 """Handle normal input lines. Use as a template for handlers."""
1961 1963
1962 1964 # With autoindent on, we need some way to exit the input loop, and I
1963 1965 # don't want to force the user to have to backspace all the way to
1964 1966 # clear the line. The rule will be in this case, that either two
1965 1967 # lines of pure whitespace in a row, or a line of pure whitespace but
1966 1968 # of a size different to the indent level, will exit the input loop.
1967 1969
1968 1970 if (continue_prompt and self.autoindent and line.isspace() and
1969 1971 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
1970 1972 (self.buffer[-1]).isspace() )):
1971 1973 line = ''
1972 1974
1973 1975 self.log(line,continue_prompt)
1974 1976 return line
1975 1977
1976 1978 def handle_alias(self,line,continue_prompt=None,
1977 1979 pre=None,iFun=None,theRest=None):
1978 1980 """Handle alias input lines. """
1979 1981
1980 1982 # pre is needed, because it carries the leading whitespace. Otherwise
1981 1983 # aliases won't work in indented sections.
1982 1984 line_out = '%sipalias(%s)' % (pre,make_quoted_expr(iFun + " " + theRest))
1983 1985 self.log(line_out,continue_prompt)
1984 1986 return line_out
1985 1987
1986 1988 def handle_shell_escape(self, line, continue_prompt=None,
1987 1989 pre=None,iFun=None,theRest=None):
1988 1990 """Execute the line in a shell, empty return value"""
1989 1991
1990 1992 #print 'line in :', `line` # dbg
1991 1993 # Example of a special handler. Others follow a similar pattern.
1992 1994 if line.lstrip().startswith('!!'):
1993 1995 # rewrite iFun/theRest to properly hold the call to %sx and
1994 1996 # the actual command to be executed, so handle_magic can work
1995 1997 # correctly
1996 1998 theRest = '%s %s' % (iFun[2:],theRest)
1997 1999 iFun = 'sx'
1998 2000 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,
1999 2001 line.lstrip()[2:]),
2000 2002 continue_prompt,pre,iFun,theRest)
2001 2003 else:
2002 2004 cmd=line.lstrip().lstrip('!')
2003 2005 line_out = '%sipsystem(%s)' % (pre,make_quoted_expr(cmd))
2004 2006 # update cache/log and return
2005 2007 self.log(line_out,continue_prompt)
2006 2008 return line_out
2007 2009
2008 2010 def handle_magic(self, line, continue_prompt=None,
2009 2011 pre=None,iFun=None,theRest=None):
2010 2012 """Execute magic functions."""
2011 2013
2012 2014
2013 2015 cmd = '%sipmagic(%s)' % (pre,make_quoted_expr(iFun + " " + theRest))
2014 2016 self.log(cmd,continue_prompt)
2015 2017 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2016 2018 return cmd
2017 2019
2018 2020 def handle_auto(self, line, continue_prompt=None,
2019 2021 pre=None,iFun=None,theRest=None,obj=None):
2020 2022 """Hande lines which can be auto-executed, quoting if requested."""
2021 2023
2022 2024 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2023 2025
2024 2026 # This should only be active for single-line input!
2025 2027 if continue_prompt:
2026 2028 self.log(line,continue_prompt)
2027 2029 return line
2028 2030
2029 2031 auto_rewrite = True
2030 2032 if pre == self.ESC_QUOTE:
2031 2033 # Auto-quote splitting on whitespace
2032 2034 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2033 2035 elif pre == self.ESC_QUOTE2:
2034 2036 # Auto-quote whole string
2035 2037 newcmd = '%s("%s")' % (iFun,theRest)
2036 2038 else:
2037 2039 # Auto-paren.
2038 2040 # We only apply it to argument-less calls if the autocall
2039 2041 # parameter is set to 2. We only need to check that autocall is <
2040 2042 # 2, since this function isn't called unless it's at least 1.
2041 2043 if not theRest and (self.rc.autocall < 2):
2042 2044 newcmd = '%s %s' % (iFun,theRest)
2043 2045 auto_rewrite = False
2044 2046 else:
2045 2047 if theRest.startswith('['):
2046 2048 if hasattr(obj,'__getitem__'):
2047 2049 # Don't autocall in this case: item access for an object
2048 2050 # which is BOTH callable and implements __getitem__.
2049 2051 newcmd = '%s %s' % (iFun,theRest)
2050 2052 auto_rewrite = False
2051 2053 else:
2052 2054 # if the object doesn't support [] access, go ahead and
2053 2055 # autocall
2054 2056 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2055 2057 elif theRest.endswith(';'):
2056 2058 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2057 2059 else:
2058 2060 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2059 2061
2060 2062 if auto_rewrite:
2061 2063 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
2062 2064 # log what is now valid Python, not the actual user input (without the
2063 2065 # final newline)
2064 2066 self.log(newcmd,continue_prompt)
2065 2067 return newcmd
2066 2068
2067 2069 def handle_help(self, line, continue_prompt=None,
2068 2070 pre=None,iFun=None,theRest=None):
2069 2071 """Try to get some help for the object.
2070 2072
2071 2073 obj? or ?obj -> basic information.
2072 2074 obj?? or ??obj -> more details.
2073 2075 """
2074 2076
2075 2077 # We need to make sure that we don't process lines which would be
2076 2078 # otherwise valid python, such as "x=1 # what?"
2077 2079 try:
2078 2080 codeop.compile_command(line)
2079 2081 except SyntaxError:
2080 2082 # We should only handle as help stuff which is NOT valid syntax
2081 2083 if line[0]==self.ESC_HELP:
2082 2084 line = line[1:]
2083 2085 elif line[-1]==self.ESC_HELP:
2084 2086 line = line[:-1]
2085 2087 self.log('#?'+line)
2086 2088 if line:
2087 2089 self.magic_pinfo(line)
2088 2090 else:
2089 2091 page(self.usage,screen_lines=self.rc.screen_length)
2090 2092 return '' # Empty string is needed here!
2091 2093 except:
2092 2094 # Pass any other exceptions through to the normal handler
2093 2095 return self.handle_normal(line,continue_prompt)
2094 2096 else:
2095 2097 # If the code compiles ok, we should handle it normally
2096 2098 return self.handle_normal(line,continue_prompt)
2097 2099
2098 2100 def handle_emacs(self,line,continue_prompt=None,
2099 2101 pre=None,iFun=None,theRest=None):
2100 2102 """Handle input lines marked by python-mode."""
2101 2103
2102 2104 # Currently, nothing is done. Later more functionality can be added
2103 2105 # here if needed.
2104 2106
2105 2107 # The input cache shouldn't be updated
2106 2108
2107 2109 return line
2108 2110
2109 2111 def mktempfile(self,data=None):
2110 2112 """Make a new tempfile and return its filename.
2111 2113
2112 2114 This makes a call to tempfile.mktemp, but it registers the created
2113 2115 filename internally so ipython cleans it up at exit time.
2114 2116
2115 2117 Optional inputs:
2116 2118
2117 2119 - data(None): if data is given, it gets written out to the temp file
2118 2120 immediately, and the file is closed again."""
2119 2121
2120 2122 filename = tempfile.mktemp('.py','ipython_edit_')
2121 2123 self.tempfiles.append(filename)
2122 2124
2123 2125 if data:
2124 2126 tmp_file = open(filename,'w')
2125 2127 tmp_file.write(data)
2126 2128 tmp_file.close()
2127 2129 return filename
2128 2130
2129 2131 def write(self,data):
2130 2132 """Write a string to the default output"""
2131 2133 Term.cout.write(data)
2132 2134
2133 2135 def write_err(self,data):
2134 2136 """Write a string to the default error output"""
2135 2137 Term.cerr.write(data)
2136 2138
2137 2139 def exit(self):
2138 2140 """Handle interactive exit.
2139 2141
2140 2142 This method sets the exit_now attribute."""
2141 2143
2142 2144 if self.rc.confirm_exit:
2143 2145 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2144 2146 self.exit_now = True
2145 2147 else:
2146 2148 self.exit_now = True
2147 2149 return self.exit_now
2148 2150
2149 2151 def safe_execfile(self,fname,*where,**kw):
2150 2152 fname = os.path.expanduser(fname)
2151 2153
2152 2154 # find things also in current directory
2153 2155 dname = os.path.dirname(fname)
2154 2156 if not sys.path.count(dname):
2155 2157 sys.path.append(dname)
2156 2158
2157 2159 try:
2158 2160 xfile = open(fname)
2159 2161 except:
2160 2162 print >> Term.cerr, \
2161 2163 'Could not open file <%s> for safe execution.' % fname
2162 2164 return None
2163 2165
2164 2166 kw.setdefault('islog',0)
2165 2167 kw.setdefault('quiet',1)
2166 2168 kw.setdefault('exit_ignore',0)
2167 2169 first = xfile.readline()
2168 2170 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2169 2171 xfile.close()
2170 2172 # line by line execution
2171 2173 if first.startswith(loghead) or kw['islog']:
2172 2174 print 'Loading log file <%s> one line at a time...' % fname
2173 2175 if kw['quiet']:
2174 2176 stdout_save = sys.stdout
2175 2177 sys.stdout = StringIO.StringIO()
2176 2178 try:
2177 2179 globs,locs = where[0:2]
2178 2180 except:
2179 2181 try:
2180 2182 globs = locs = where[0]
2181 2183 except:
2182 2184 globs = locs = globals()
2183 2185 badblocks = []
2184 2186
2185 2187 # we also need to identify indented blocks of code when replaying
2186 2188 # logs and put them together before passing them to an exec
2187 2189 # statement. This takes a bit of regexp and look-ahead work in the
2188 2190 # file. It's easiest if we swallow the whole thing in memory
2189 2191 # first, and manually walk through the lines list moving the
2190 2192 # counter ourselves.
2191 2193 indent_re = re.compile('\s+\S')
2192 2194 xfile = open(fname)
2193 2195 filelines = xfile.readlines()
2194 2196 xfile.close()
2195 2197 nlines = len(filelines)
2196 2198 lnum = 0
2197 2199 while lnum < nlines:
2198 2200 line = filelines[lnum]
2199 2201 lnum += 1
2200 2202 # don't re-insert logger status info into cache
2201 2203 if line.startswith('#log#'):
2202 2204 continue
2203 2205 else:
2204 2206 # build a block of code (maybe a single line) for execution
2205 2207 block = line
2206 2208 try:
2207 2209 next = filelines[lnum] # lnum has already incremented
2208 2210 except:
2209 2211 next = None
2210 2212 while next and indent_re.match(next):
2211 2213 block += next
2212 2214 lnum += 1
2213 2215 try:
2214 2216 next = filelines[lnum]
2215 2217 except:
2216 2218 next = None
2217 2219 # now execute the block of one or more lines
2218 2220 try:
2219 2221 exec block in globs,locs
2220 2222 except SystemExit:
2221 2223 pass
2222 2224 except:
2223 2225 badblocks.append(block.rstrip())
2224 2226 if kw['quiet']: # restore stdout
2225 2227 sys.stdout.close()
2226 2228 sys.stdout = stdout_save
2227 2229 print 'Finished replaying log file <%s>' % fname
2228 2230 if badblocks:
2229 2231 print >> sys.stderr, ('\nThe following lines/blocks in file '
2230 2232 '<%s> reported errors:' % fname)
2231 2233
2232 2234 for badline in badblocks:
2233 2235 print >> sys.stderr, badline
2234 2236 else: # regular file execution
2235 2237 try:
2236 2238 execfile(fname,*where)
2237 2239 except SyntaxError:
2238 2240 etype,evalue = sys.exc_info()[:2]
2239 2241 self.SyntaxTB(etype,evalue,[])
2240 2242 warn('Failure executing file: <%s>' % fname)
2241 2243 except SystemExit,status:
2242 2244 if not kw['exit_ignore']:
2243 2245 self.InteractiveTB()
2244 2246 warn('Failure executing file: <%s>' % fname)
2245 2247 except:
2246 2248 self.InteractiveTB()
2247 2249 warn('Failure executing file: <%s>' % fname)
2248 2250
2249 2251 #************************* end of file <iplib.py> *****************************
1 NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
General Comments 0
You need to be logged in to leave comments. Login now