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