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