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