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