##// END OF EJS Templates
rocky's pydb patch \#4
vivainio -
Show More

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

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