##// END OF EJS Templates
Implement hard reset with '%reset -h' call....
Thomas Kluyver -
Show More
@@ -1,327 +1,330 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Displayhook for IPython.
2 """Displayhook for IPython.
3
3
4 This defines a callable class that IPython uses for `sys.displayhook`.
4 This defines a callable class that IPython uses for `sys.displayhook`.
5
5
6 Authors:
6 Authors:
7
7
8 * Fernando Perez
8 * Fernando Perez
9 * Brian Granger
9 * Brian Granger
10 * Robert Kern
10 * Robert Kern
11 """
11 """
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Copyright (C) 2008-2010 The IPython Development Team
14 # Copyright (C) 2008-2010 The IPython Development Team
15 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
15 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
16 #
16 #
17 # Distributed under the terms of the BSD License. The full license is in
17 # Distributed under the terms of the BSD License. The full license is in
18 # the file COPYING, distributed as part of this software.
18 # the file COPYING, distributed as part of this software.
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20
20
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22 # Imports
22 # Imports
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24
24
25 import __builtin__
25 import __builtin__
26
26
27 from IPython.config.configurable import Configurable
27 from IPython.config.configurable import Configurable
28 from IPython.core import prompts
28 from IPython.core import prompts
29 import IPython.utils.generics
29 import IPython.utils.generics
30 import IPython.utils.io
30 import IPython.utils.io
31 from IPython.utils.traitlets import Instance, List
31 from IPython.utils.traitlets import Instance, List
32 from IPython.utils.warn import warn
32 from IPython.utils.warn import warn
33
33
34 #-----------------------------------------------------------------------------
34 #-----------------------------------------------------------------------------
35 # Main displayhook class
35 # Main displayhook class
36 #-----------------------------------------------------------------------------
36 #-----------------------------------------------------------------------------
37
37
38 # TODO: The DisplayHook class should be split into two classes, one that
38 # TODO: The DisplayHook class should be split into two classes, one that
39 # manages the prompts and their synchronization and another that just does the
39 # manages the prompts and their synchronization and another that just does the
40 # displayhook logic and calls into the prompt manager.
40 # displayhook logic and calls into the prompt manager.
41
41
42 # TODO: Move the various attributes (cache_size, colors, input_sep,
42 # TODO: Move the various attributes (cache_size, colors, input_sep,
43 # output_sep, output_sep2, ps1, ps2, ps_out, pad_left). Some of these are also
43 # output_sep, output_sep2, ps1, ps2, ps_out, pad_left). Some of these are also
44 # attributes of InteractiveShell. They should be on ONE object only and the
44 # attributes of InteractiveShell. They should be on ONE object only and the
45 # other objects should ask that one object for their values.
45 # other objects should ask that one object for their values.
46
46
47 class DisplayHook(Configurable):
47 class DisplayHook(Configurable):
48 """The custom IPython displayhook to replace sys.displayhook.
48 """The custom IPython displayhook to replace sys.displayhook.
49
49
50 This class does many things, but the basic idea is that it is a callable
50 This class does many things, but the basic idea is that it is a callable
51 that gets called anytime user code returns a value.
51 that gets called anytime user code returns a value.
52
52
53 Currently this class does more than just the displayhook logic and that
53 Currently this class does more than just the displayhook logic and that
54 extra logic should eventually be moved out of here.
54 extra logic should eventually be moved out of here.
55 """
55 """
56
56
57 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
57 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
58
58
59 def __init__(self, shell=None, cache_size=1000,
59 def __init__(self, shell=None, cache_size=1000,
60 colors='NoColor', input_sep='\n',
60 colors='NoColor', input_sep='\n',
61 output_sep='\n', output_sep2='',
61 output_sep='\n', output_sep2='',
62 ps1 = None, ps2 = None, ps_out = None, pad_left=True,
62 ps1 = None, ps2 = None, ps_out = None, pad_left=True,
63 config=None):
63 config=None):
64 super(DisplayHook, self).__init__(shell=shell, config=config)
64 super(DisplayHook, self).__init__(shell=shell, config=config)
65
65
66 cache_size_min = 3
66 cache_size_min = 3
67 if cache_size <= 0:
67 if cache_size <= 0:
68 self.do_full_cache = 0
68 self.do_full_cache = 0
69 cache_size = 0
69 cache_size = 0
70 elif cache_size < cache_size_min:
70 elif cache_size < cache_size_min:
71 self.do_full_cache = 0
71 self.do_full_cache = 0
72 cache_size = 0
72 cache_size = 0
73 warn('caching was disabled (min value for cache size is %s).' %
73 warn('caching was disabled (min value for cache size is %s).' %
74 cache_size_min,level=3)
74 cache_size_min,level=3)
75 else:
75 else:
76 self.do_full_cache = 1
76 self.do_full_cache = 1
77
77
78 self.cache_size = cache_size
78 self.cache_size = cache_size
79 self.input_sep = input_sep
79 self.input_sep = input_sep
80
80
81 # we need a reference to the user-level namespace
81 # we need a reference to the user-level namespace
82 self.shell = shell
82 self.shell = shell
83
83
84 # Set input prompt strings and colors
84 # Set input prompt strings and colors
85 if cache_size == 0:
85 if cache_size == 0:
86 if ps1.find('%n') > -1 or ps1.find(r'\#') > -1 \
86 if ps1.find('%n') > -1 or ps1.find(r'\#') > -1 \
87 or ps1.find(r'\N') > -1:
87 or ps1.find(r'\N') > -1:
88 ps1 = '>>> '
88 ps1 = '>>> '
89 if ps2.find('%n') > -1 or ps2.find(r'\#') > -1 \
89 if ps2.find('%n') > -1 or ps2.find(r'\#') > -1 \
90 or ps2.find(r'\N') > -1:
90 or ps2.find(r'\N') > -1:
91 ps2 = '... '
91 ps2 = '... '
92 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
92 self.ps1_str = self._set_prompt_str(ps1,'In [\\#]: ','>>> ')
93 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
93 self.ps2_str = self._set_prompt_str(ps2,' .\\D.: ','... ')
94 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
94 self.ps_out_str = self._set_prompt_str(ps_out,'Out[\\#]: ','')
95
95
96 self.color_table = prompts.PromptColors
96 self.color_table = prompts.PromptColors
97 self.prompt1 = prompts.Prompt1(self,sep=input_sep,prompt=self.ps1_str,
97 self.prompt1 = prompts.Prompt1(self,sep=input_sep,prompt=self.ps1_str,
98 pad_left=pad_left)
98 pad_left=pad_left)
99 self.prompt2 = prompts.Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
99 self.prompt2 = prompts.Prompt2(self,prompt=self.ps2_str,pad_left=pad_left)
100 self.prompt_out = prompts.PromptOut(self,sep='',prompt=self.ps_out_str,
100 self.prompt_out = prompts.PromptOut(self,sep='',prompt=self.ps_out_str,
101 pad_left=pad_left)
101 pad_left=pad_left)
102 self.set_colors(colors)
102 self.set_colors(colors)
103
103
104 # Store the last prompt string each time, we need it for aligning
104 # Store the last prompt string each time, we need it for aligning
105 # continuation and auto-rewrite prompts
105 # continuation and auto-rewrite prompts
106 self.last_prompt = ''
106 self.last_prompt = ''
107 self.output_sep = output_sep
107 self.output_sep = output_sep
108 self.output_sep2 = output_sep2
108 self.output_sep2 = output_sep2
109 self._,self.__,self.___ = '','',''
109 self._,self.__,self.___ = '','',''
110
110
111 # these are deliberately global:
111 # these are deliberately global:
112 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
112 to_user_ns = {'_':self._,'__':self.__,'___':self.___}
113 self.shell.user_ns.update(to_user_ns)
113 self.shell.user_ns.update(to_user_ns)
114
114
115 @property
115 @property
116 def prompt_count(self):
116 def prompt_count(self):
117 return self.shell.execution_count
117 return self.shell.execution_count
118
118
119 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
119 def _set_prompt_str(self,p_str,cache_def,no_cache_def):
120 if p_str is None:
120 if p_str is None:
121 if self.do_full_cache:
121 if self.do_full_cache:
122 return cache_def
122 return cache_def
123 else:
123 else:
124 return no_cache_def
124 return no_cache_def
125 else:
125 else:
126 return p_str
126 return p_str
127
127
128 def set_colors(self, colors):
128 def set_colors(self, colors):
129 """Set the active color scheme and configure colors for the three
129 """Set the active color scheme and configure colors for the three
130 prompt subsystems."""
130 prompt subsystems."""
131
131
132 # FIXME: This modifying of the global prompts.prompt_specials needs
132 # FIXME: This modifying of the global prompts.prompt_specials needs
133 # to be fixed. We need to refactor all of the prompts stuff to use
133 # to be fixed. We need to refactor all of the prompts stuff to use
134 # proper configuration and traits notifications.
134 # proper configuration and traits notifications.
135 if colors.lower()=='nocolor':
135 if colors.lower()=='nocolor':
136 prompts.prompt_specials = prompts.prompt_specials_nocolor
136 prompts.prompt_specials = prompts.prompt_specials_nocolor
137 else:
137 else:
138 prompts.prompt_specials = prompts.prompt_specials_color
138 prompts.prompt_specials = prompts.prompt_specials_color
139
139
140 self.color_table.set_active_scheme(colors)
140 self.color_table.set_active_scheme(colors)
141 self.prompt1.set_colors()
141 self.prompt1.set_colors()
142 self.prompt2.set_colors()
142 self.prompt2.set_colors()
143 self.prompt_out.set_colors()
143 self.prompt_out.set_colors()
144
144
145 #-------------------------------------------------------------------------
145 #-------------------------------------------------------------------------
146 # Methods used in __call__. Override these methods to modify the behavior
146 # Methods used in __call__. Override these methods to modify the behavior
147 # of the displayhook.
147 # of the displayhook.
148 #-------------------------------------------------------------------------
148 #-------------------------------------------------------------------------
149
149
150 def check_for_underscore(self):
150 def check_for_underscore(self):
151 """Check if the user has set the '_' variable by hand."""
151 """Check if the user has set the '_' variable by hand."""
152 # If something injected a '_' variable in __builtin__, delete
152 # If something injected a '_' variable in __builtin__, delete
153 # ipython's automatic one so we don't clobber that. gettext() in
153 # ipython's automatic one so we don't clobber that. gettext() in
154 # particular uses _, so we need to stay away from it.
154 # particular uses _, so we need to stay away from it.
155 if '_' in __builtin__.__dict__:
155 if '_' in __builtin__.__dict__:
156 try:
156 try:
157 del self.shell.user_ns['_']
157 del self.shell.user_ns['_']
158 except KeyError:
158 except KeyError:
159 pass
159 pass
160
160
161 def quiet(self):
161 def quiet(self):
162 """Should we silence the display hook because of ';'?"""
162 """Should we silence the display hook because of ';'?"""
163 # do not print output if input ends in ';'
163 # do not print output if input ends in ';'
164 try:
164 try:
165 if self.shell.history_manager.input_hist_parsed[self.prompt_count].endswith(';\n'):
165 if self.shell.history_manager.input_hist_parsed[self.prompt_count].endswith(';\n'):
166 return True
166 return True
167 except IndexError:
167 except IndexError:
168 # some uses of ipshellembed may fail here
168 # some uses of ipshellembed may fail here
169 pass
169 pass
170 return False
170 return False
171
171
172 def start_displayhook(self):
172 def start_displayhook(self):
173 """Start the displayhook, initializing resources."""
173 """Start the displayhook, initializing resources."""
174 pass
174 pass
175
175
176 def write_output_prompt(self):
176 def write_output_prompt(self):
177 """Write the output prompt.
177 """Write the output prompt.
178
178
179 The default implementation simply writes the prompt to
179 The default implementation simply writes the prompt to
180 ``io.Term.cout``.
180 ``io.Term.cout``.
181 """
181 """
182 # Use write, not print which adds an extra space.
182 # Use write, not print which adds an extra space.
183 IPython.utils.io.Term.cout.write(self.output_sep)
183 IPython.utils.io.Term.cout.write(self.output_sep)
184 outprompt = str(self.prompt_out)
184 outprompt = str(self.prompt_out)
185 if self.do_full_cache:
185 if self.do_full_cache:
186 IPython.utils.io.Term.cout.write(outprompt)
186 IPython.utils.io.Term.cout.write(outprompt)
187
187
188 def compute_format_data(self, result):
188 def compute_format_data(self, result):
189 """Compute format data of the object to be displayed.
189 """Compute format data of the object to be displayed.
190
190
191 The format data is a generalization of the :func:`repr` of an object.
191 The format data is a generalization of the :func:`repr` of an object.
192 In the default implementation the format data is a :class:`dict` of
192 In the default implementation the format data is a :class:`dict` of
193 key value pair where the keys are valid MIME types and the values
193 key value pair where the keys are valid MIME types and the values
194 are JSON'able data structure containing the raw data for that MIME
194 are JSON'able data structure containing the raw data for that MIME
195 type. It is up to frontends to determine pick a MIME to to use and
195 type. It is up to frontends to determine pick a MIME to to use and
196 display that data in an appropriate manner.
196 display that data in an appropriate manner.
197
197
198 This method only computes the format data for the object and should
198 This method only computes the format data for the object and should
199 NOT actually print or write that to a stream.
199 NOT actually print or write that to a stream.
200
200
201 Parameters
201 Parameters
202 ----------
202 ----------
203 result : object
203 result : object
204 The Python object passed to the display hook, whose format will be
204 The Python object passed to the display hook, whose format will be
205 computed.
205 computed.
206
206
207 Returns
207 Returns
208 -------
208 -------
209 format_data : dict
209 format_data : dict
210 A :class:`dict` whose keys are valid MIME types and values are
210 A :class:`dict` whose keys are valid MIME types and values are
211 JSON'able raw data for that MIME type. It is recommended that
211 JSON'able raw data for that MIME type. It is recommended that
212 all return values of this should always include the "text/plain"
212 all return values of this should always include the "text/plain"
213 MIME type representation of the object.
213 MIME type representation of the object.
214 """
214 """
215 return self.shell.display_formatter.format(result)
215 return self.shell.display_formatter.format(result)
216
216
217 def write_format_data(self, format_dict):
217 def write_format_data(self, format_dict):
218 """Write the format data dict to the frontend.
218 """Write the format data dict to the frontend.
219
219
220 This default version of this method simply writes the plain text
220 This default version of this method simply writes the plain text
221 representation of the object to ``io.Term.cout``. Subclasses should
221 representation of the object to ``io.Term.cout``. Subclasses should
222 override this method to send the entire `format_dict` to the
222 override this method to send the entire `format_dict` to the
223 frontends.
223 frontends.
224
224
225 Parameters
225 Parameters
226 ----------
226 ----------
227 format_dict : dict
227 format_dict : dict
228 The format dict for the object passed to `sys.displayhook`.
228 The format dict for the object passed to `sys.displayhook`.
229 """
229 """
230 # We want to print because we want to always make sure we have a
230 # We want to print because we want to always make sure we have a
231 # newline, even if all the prompt separators are ''. This is the
231 # newline, even if all the prompt separators are ''. This is the
232 # standard IPython behavior.
232 # standard IPython behavior.
233 result_repr = format_dict['text/plain']
233 result_repr = format_dict['text/plain']
234 if '\n' in result_repr:
234 if '\n' in result_repr:
235 # So that multi-line strings line up with the left column of
235 # So that multi-line strings line up with the left column of
236 # the screen, instead of having the output prompt mess up
236 # the screen, instead of having the output prompt mess up
237 # their first line.
237 # their first line.
238 # We use the ps_out_str template instead of the expanded prompt
238 # We use the ps_out_str template instead of the expanded prompt
239 # because the expansion may add ANSI escapes that will interfere
239 # because the expansion may add ANSI escapes that will interfere
240 # with our ability to determine whether or not we should add
240 # with our ability to determine whether or not we should add
241 # a newline.
241 # a newline.
242 if self.ps_out_str and not self.ps_out_str.endswith('\n'):
242 if self.ps_out_str and not self.ps_out_str.endswith('\n'):
243 # But avoid extraneous empty lines.
243 # But avoid extraneous empty lines.
244 result_repr = '\n' + result_repr
244 result_repr = '\n' + result_repr
245
245
246 print >>IPython.utils.io.Term.cout, result_repr
246 print >>IPython.utils.io.Term.cout, result_repr
247
247
248 def update_user_ns(self, result):
248 def update_user_ns(self, result):
249 """Update user_ns with various things like _, __, _1, etc."""
249 """Update user_ns with various things like _, __, _1, etc."""
250
250
251 # Avoid recursive reference when displaying _oh/Out
251 # Avoid recursive reference when displaying _oh/Out
252 if result is not self.shell.user_ns['_oh']:
252 if result is not self.shell.user_ns['_oh']:
253 if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
253 if len(self.shell.user_ns['_oh']) >= self.cache_size and self.do_full_cache:
254 warn('Output cache limit (currently '+
254 warn('Output cache limit (currently '+
255 `self.cache_size`+' entries) hit.\n'
255 `self.cache_size`+' entries) hit.\n'
256 'Flushing cache and resetting history counter...\n'
256 'Flushing cache and resetting history counter...\n'
257 'The only history variables available will be _,__,___ and _1\n'
257 'The only history variables available will be _,__,___ and _1\n'
258 'with the current result.')
258 'with the current result.')
259
259
260 self.flush()
260 self.flush()
261 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
261 # Don't overwrite '_' and friends if '_' is in __builtin__ (otherwise
262 # we cause buggy behavior for things like gettext).
262 # we cause buggy behavior for things like gettext).
263
263
264 if '_' not in __builtin__.__dict__:
264 if '_' not in __builtin__.__dict__:
265 self.___ = self.__
265 self.___ = self.__
266 self.__ = self._
266 self.__ = self._
267 self._ = result
267 self._ = result
268 self.shell.user_ns.update({'_':self._,
268 self.shell.user_ns.update({'_':self._,
269 '__':self.__,
269 '__':self.__,
270 '___':self.___})
270 '___':self.___})
271
271
272 # hackish access to top-level namespace to create _1,_2... dynamically
272 # hackish access to top-level namespace to create _1,_2... dynamically
273 to_main = {}
273 to_main = {}
274 if self.do_full_cache:
274 if self.do_full_cache:
275 new_result = '_'+`self.prompt_count`
275 new_result = '_'+`self.prompt_count`
276 to_main[new_result] = result
276 to_main[new_result] = result
277 self.shell.user_ns.update(to_main)
277 self.shell.user_ns.update(to_main)
278 self.shell.user_ns['_oh'][self.prompt_count] = result
278 self.shell.user_ns['_oh'][self.prompt_count] = result
279
279
280 def log_output(self, format_dict):
280 def log_output(self, format_dict):
281 """Log the output."""
281 """Log the output."""
282 if self.shell.logger.log_output:
282 if self.shell.logger.log_output:
283 self.shell.logger.log_write(format_dict['text/plain'], 'output')
283 self.shell.logger.log_write(format_dict['text/plain'], 'output')
284 # This is a defaultdict of lists, so we can always append
284 # This is a defaultdict of lists, so we can always append
285 self.shell.history_manager.output_hist_reprs[self.prompt_count]\
285 self.shell.history_manager.output_hist_reprs[self.prompt_count]\
286 .append(format_dict['text/plain'])
286 .append(format_dict['text/plain'])
287
287
288 def finish_displayhook(self):
288 def finish_displayhook(self):
289 """Finish up all displayhook activities."""
289 """Finish up all displayhook activities."""
290 IPython.utils.io.Term.cout.write(self.output_sep2)
290 IPython.utils.io.Term.cout.write(self.output_sep2)
291 IPython.utils.io.Term.cout.flush()
291 IPython.utils.io.Term.cout.flush()
292
292
293 def __call__(self, result=None):
293 def __call__(self, result=None):
294 """Printing with history cache management.
294 """Printing with history cache management.
295
295
296 This is invoked everytime the interpreter needs to print, and is
296 This is invoked everytime the interpreter needs to print, and is
297 activated by setting the variable sys.displayhook to it.
297 activated by setting the variable sys.displayhook to it.
298 """
298 """
299 self.check_for_underscore()
299 self.check_for_underscore()
300 if result is not None and not self.quiet():
300 if result is not None and not self.quiet():
301 self.start_displayhook()
301 self.start_displayhook()
302 self.write_output_prompt()
302 self.write_output_prompt()
303 format_dict = self.compute_format_data(result)
303 format_dict = self.compute_format_data(result)
304 self.write_format_data(format_dict)
304 self.write_format_data(format_dict)
305 self.update_user_ns(result)
305 self.update_user_ns(result)
306 self.log_output(format_dict)
306 self.log_output(format_dict)
307 self.finish_displayhook()
307 self.finish_displayhook()
308
308
309 def flush(self):
309 def flush(self):
310 if not self.do_full_cache:
310 if not self.do_full_cache:
311 raise ValueError,"You shouldn't have reached the cache flush "\
311 raise ValueError,"You shouldn't have reached the cache flush "\
312 "if full caching is not enabled!"
312 "if full caching is not enabled!"
313 # delete auto-generated vars from global namespace
313 # delete auto-generated vars from global namespace
314
314
315 for n in range(1,self.prompt_count + 1):
315 for n in range(1,self.prompt_count + 1):
316 key = '_'+`n`
316 key = '_'+`n`
317 try:
317 try:
318 del self.shell.user_ns[key]
318 del self.shell.user_ns[key]
319 except: pass
319 except: pass
320 self.shell.user_ns['_oh'].clear()
320 self.shell.user_ns['_oh'].clear()
321
321
322 # Release our own references to objects:
323 self._, self.__, self.___ = '', '', ''
324
322 if '_' not in __builtin__.__dict__:
325 if '_' not in __builtin__.__dict__:
323 self.shell.user_ns.update({'_':None,'__':None, '___':None})
326 self.shell.user_ns.update({'_':None,'__':None, '___':None})
324 import gc
327 import gc
325 # TODO: Is this really needed?
328 # TODO: Is this really needed?
326 gc.collect()
329 gc.collect()
327
330
@@ -1,2613 +1,2620 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19
19
20 import __builtin__
20 import __builtin__
21 import __future__
21 import __future__
22 import abc
22 import abc
23 import atexit
23 import atexit
24 import codeop
24 import codeop
25 import inspect
25 import inspect
26 import os
26 import os
27 import re
27 import re
28 import sys
28 import sys
29 import tempfile
29 import tempfile
30 import types
30 import types
31 from contextlib import nested
31 from contextlib import nested
32
32
33 from IPython.config.configurable import Configurable
33 from IPython.config.configurable import Configurable
34 from IPython.core import debugger, oinspect
34 from IPython.core import debugger, oinspect
35 from IPython.core import history as ipcorehist
35 from IPython.core import history as ipcorehist
36 from IPython.core import page
36 from IPython.core import page
37 from IPython.core import prefilter
37 from IPython.core import prefilter
38 from IPython.core import shadowns
38 from IPython.core import shadowns
39 from IPython.core import ultratb
39 from IPython.core import ultratb
40 from IPython.core.alias import AliasManager
40 from IPython.core.alias import AliasManager
41 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.builtin_trap import BuiltinTrap
42 from IPython.core.compilerop import CachingCompiler
42 from IPython.core.compilerop import CachingCompiler
43 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.display_trap import DisplayTrap
44 from IPython.core.displayhook import DisplayHook
44 from IPython.core.displayhook import DisplayHook
45 from IPython.core.displaypub import DisplayPublisher
45 from IPython.core.displaypub import DisplayPublisher
46 from IPython.core.error import TryNext, UsageError
46 from IPython.core.error import TryNext, UsageError
47 from IPython.core.extensions import ExtensionManager
47 from IPython.core.extensions import ExtensionManager
48 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
48 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
49 from IPython.core.formatters import DisplayFormatter
49 from IPython.core.formatters import DisplayFormatter
50 from IPython.core.history import HistoryManager
50 from IPython.core.history import HistoryManager
51 from IPython.core.inputsplitter import IPythonInputSplitter
51 from IPython.core.inputsplitter import IPythonInputSplitter
52 from IPython.core.logger import Logger
52 from IPython.core.logger import Logger
53 from IPython.core.macro import Macro
53 from IPython.core.macro import Macro
54 from IPython.core.magic import Magic
54 from IPython.core.magic import Magic
55 from IPython.core.payload import PayloadManager
55 from IPython.core.payload import PayloadManager
56 from IPython.core.plugin import PluginManager
56 from IPython.core.plugin import PluginManager
57 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
57 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
58 from IPython.external.Itpl import ItplNS
58 from IPython.external.Itpl import ItplNS
59 from IPython.utils import PyColorize
59 from IPython.utils import PyColorize
60 from IPython.utils import io
60 from IPython.utils import io
61 from IPython.utils.doctestreload import doctest_reload
61 from IPython.utils.doctestreload import doctest_reload
62 from IPython.utils.io import ask_yes_no, rprint
62 from IPython.utils.io import ask_yes_no, rprint
63 from IPython.utils.ipstruct import Struct
63 from IPython.utils.ipstruct import Struct
64 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
64 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
65 from IPython.utils.pickleshare import PickleShareDB
65 from IPython.utils.pickleshare import PickleShareDB
66 from IPython.utils.process import system, getoutput
66 from IPython.utils.process import system, getoutput
67 from IPython.utils.strdispatch import StrDispatch
67 from IPython.utils.strdispatch import StrDispatch
68 from IPython.utils.syspathcontext import prepended_to_syspath
68 from IPython.utils.syspathcontext import prepended_to_syspath
69 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
69 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
70 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
70 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
71 List, Unicode, Instance, Type)
71 List, Unicode, Instance, Type)
72 from IPython.utils.warn import warn, error, fatal
72 from IPython.utils.warn import warn, error, fatal
73 import IPython.core.hooks
73 import IPython.core.hooks
74
74
75 #-----------------------------------------------------------------------------
75 #-----------------------------------------------------------------------------
76 # Globals
76 # Globals
77 #-----------------------------------------------------------------------------
77 #-----------------------------------------------------------------------------
78
78
79 # compiled regexps for autoindent management
79 # compiled regexps for autoindent management
80 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
80 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # Utilities
83 # Utilities
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86 # store the builtin raw_input globally, and use this always, in case user code
86 # store the builtin raw_input globally, and use this always, in case user code
87 # overwrites it (like wx.py.PyShell does)
87 # overwrites it (like wx.py.PyShell does)
88 raw_input_original = raw_input
88 raw_input_original = raw_input
89
89
90 def softspace(file, newvalue):
90 def softspace(file, newvalue):
91 """Copied from code.py, to remove the dependency"""
91 """Copied from code.py, to remove the dependency"""
92
92
93 oldvalue = 0
93 oldvalue = 0
94 try:
94 try:
95 oldvalue = file.softspace
95 oldvalue = file.softspace
96 except AttributeError:
96 except AttributeError:
97 pass
97 pass
98 try:
98 try:
99 file.softspace = newvalue
99 file.softspace = newvalue
100 except (AttributeError, TypeError):
100 except (AttributeError, TypeError):
101 # "attribute-less object" or "read-only attributes"
101 # "attribute-less object" or "read-only attributes"
102 pass
102 pass
103 return oldvalue
103 return oldvalue
104
104
105
105
106 def no_op(*a, **kw): pass
106 def no_op(*a, **kw): pass
107
107
108 class SpaceInInput(Exception): pass
108 class SpaceInInput(Exception): pass
109
109
110 class Bunch: pass
110 class Bunch: pass
111
111
112
112
113 def get_default_colors():
113 def get_default_colors():
114 if sys.platform=='darwin':
114 if sys.platform=='darwin':
115 return "LightBG"
115 return "LightBG"
116 elif os.name=='nt':
116 elif os.name=='nt':
117 return 'Linux'
117 return 'Linux'
118 else:
118 else:
119 return 'Linux'
119 return 'Linux'
120
120
121
121
122 class SeparateStr(Str):
122 class SeparateStr(Str):
123 """A Str subclass to validate separate_in, separate_out, etc.
123 """A Str subclass to validate separate_in, separate_out, etc.
124
124
125 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
125 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
126 """
126 """
127
127
128 def validate(self, obj, value):
128 def validate(self, obj, value):
129 if value == '0': value = ''
129 if value == '0': value = ''
130 value = value.replace('\\n','\n')
130 value = value.replace('\\n','\n')
131 return super(SeparateStr, self).validate(obj, value)
131 return super(SeparateStr, self).validate(obj, value)
132
132
133 class MultipleInstanceError(Exception):
133 class MultipleInstanceError(Exception):
134 pass
134 pass
135
135
136 class ReadlineNoRecord(object):
136 class ReadlineNoRecord(object):
137 """Context manager to execute some code, then reload readline history
137 """Context manager to execute some code, then reload readline history
138 so that interactive input to the code doesn't appear when pressing up."""
138 so that interactive input to the code doesn't appear when pressing up."""
139 def __init__(self, shell):
139 def __init__(self, shell):
140 self.shell = shell
140 self.shell = shell
141 self._nested_level = 0
141 self._nested_level = 0
142
142
143 def __enter__(self):
143 def __enter__(self):
144 if self._nested_level == 0:
144 if self._nested_level == 0:
145 self.orig_length = self.current_length()
145 self.orig_length = self.current_length()
146 self.readline_tail = self.get_readline_tail()
146 self.readline_tail = self.get_readline_tail()
147 self._nested_level += 1
147 self._nested_level += 1
148
148
149 def __exit__(self, type, value, traceback):
149 def __exit__(self, type, value, traceback):
150 self._nested_level -= 1
150 self._nested_level -= 1
151 if self._nested_level == 0:
151 if self._nested_level == 0:
152 # Try clipping the end if it's got longer
152 # Try clipping the end if it's got longer
153 e = self.current_length() - self.orig_length
153 e = self.current_length() - self.orig_length
154 if e > 0:
154 if e > 0:
155 for _ in range(e):
155 for _ in range(e):
156 self.shell.readline.remove_history_item(self.orig_length)
156 self.shell.readline.remove_history_item(self.orig_length)
157
157
158 # If it still doesn't match, just reload readline history.
158 # If it still doesn't match, just reload readline history.
159 if self.current_length() != self.orig_length \
159 if self.current_length() != self.orig_length \
160 or self.get_readline_tail() != self.readline_tail:
160 or self.get_readline_tail() != self.readline_tail:
161 self.shell.refill_readline_hist()
161 self.shell.refill_readline_hist()
162 # Returning False will cause exceptions to propagate
162 # Returning False will cause exceptions to propagate
163 return False
163 return False
164
164
165 def current_length(self):
165 def current_length(self):
166 return self.shell.readline.get_current_history_length()
166 return self.shell.readline.get_current_history_length()
167
167
168 def get_readline_tail(self, n=10):
168 def get_readline_tail(self, n=10):
169 """Get the last n items in readline history."""
169 """Get the last n items in readline history."""
170 end = self.shell.readline.get_current_history_length() + 1
170 end = self.shell.readline.get_current_history_length() + 1
171 start = max(end-n, 1)
171 start = max(end-n, 1)
172 ghi = self.shell.readline.get_history_item
172 ghi = self.shell.readline.get_history_item
173 return [ghi(x) for x in range(start, end)]
173 return [ghi(x) for x in range(start, end)]
174
174
175
175
176 #-----------------------------------------------------------------------------
176 #-----------------------------------------------------------------------------
177 # Main IPython class
177 # Main IPython class
178 #-----------------------------------------------------------------------------
178 #-----------------------------------------------------------------------------
179
179
180 class InteractiveShell(Configurable, Magic):
180 class InteractiveShell(Configurable, Magic):
181 """An enhanced, interactive shell for Python."""
181 """An enhanced, interactive shell for Python."""
182
182
183 _instance = None
183 _instance = None
184 autocall = Enum((0,1,2), default_value=1, config=True)
184 autocall = Enum((0,1,2), default_value=1, config=True)
185 # TODO: remove all autoindent logic and put into frontends.
185 # TODO: remove all autoindent logic and put into frontends.
186 # We can't do this yet because even runlines uses the autoindent.
186 # We can't do this yet because even runlines uses the autoindent.
187 autoindent = CBool(True, config=True)
187 autoindent = CBool(True, config=True)
188 automagic = CBool(True, config=True)
188 automagic = CBool(True, config=True)
189 cache_size = Int(1000, config=True)
189 cache_size = Int(1000, config=True)
190 color_info = CBool(True, config=True)
190 color_info = CBool(True, config=True)
191 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
191 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
192 default_value=get_default_colors(), config=True)
192 default_value=get_default_colors(), config=True)
193 debug = CBool(False, config=True)
193 debug = CBool(False, config=True)
194 deep_reload = CBool(False, config=True)
194 deep_reload = CBool(False, config=True)
195 display_formatter = Instance(DisplayFormatter)
195 display_formatter = Instance(DisplayFormatter)
196 displayhook_class = Type(DisplayHook)
196 displayhook_class = Type(DisplayHook)
197 display_pub_class = Type(DisplayPublisher)
197 display_pub_class = Type(DisplayPublisher)
198
198
199 exit_now = CBool(False)
199 exit_now = CBool(False)
200 # Monotonically increasing execution counter
200 # Monotonically increasing execution counter
201 execution_count = Int(1)
201 execution_count = Int(1)
202 filename = Unicode("<ipython console>")
202 filename = Unicode("<ipython console>")
203 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
203 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
204
204
205 # Input splitter, to split entire cells of input into either individual
205 # Input splitter, to split entire cells of input into either individual
206 # interactive statements or whole blocks.
206 # interactive statements or whole blocks.
207 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
207 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
208 (), {})
208 (), {})
209 logstart = CBool(False, config=True)
209 logstart = CBool(False, config=True)
210 logfile = Unicode('', config=True)
210 logfile = Unicode('', config=True)
211 logappend = Unicode('', config=True)
211 logappend = Unicode('', config=True)
212 object_info_string_level = Enum((0,1,2), default_value=0,
212 object_info_string_level = Enum((0,1,2), default_value=0,
213 config=True)
213 config=True)
214 pdb = CBool(False, config=True)
214 pdb = CBool(False, config=True)
215
215
216 profile = Unicode('', config=True)
216 profile = Unicode('', config=True)
217 prompt_in1 = Str('In [\\#]: ', config=True)
217 prompt_in1 = Str('In [\\#]: ', config=True)
218 prompt_in2 = Str(' .\\D.: ', config=True)
218 prompt_in2 = Str(' .\\D.: ', config=True)
219 prompt_out = Str('Out[\\#]: ', config=True)
219 prompt_out = Str('Out[\\#]: ', config=True)
220 prompts_pad_left = CBool(True, config=True)
220 prompts_pad_left = CBool(True, config=True)
221 quiet = CBool(False, config=True)
221 quiet = CBool(False, config=True)
222
222
223 history_length = Int(10000, config=True)
223 history_length = Int(10000, config=True)
224
224
225 # The readline stuff will eventually be moved to the terminal subclass
225 # The readline stuff will eventually be moved to the terminal subclass
226 # but for now, we can't do that as readline is welded in everywhere.
226 # but for now, we can't do that as readline is welded in everywhere.
227 readline_use = CBool(True, config=True)
227 readline_use = CBool(True, config=True)
228 readline_merge_completions = CBool(True, config=True)
228 readline_merge_completions = CBool(True, config=True)
229 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
229 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
230 readline_remove_delims = Str('-/~', config=True)
230 readline_remove_delims = Str('-/~', config=True)
231 readline_parse_and_bind = List([
231 readline_parse_and_bind = List([
232 'tab: complete',
232 'tab: complete',
233 '"\C-l": clear-screen',
233 '"\C-l": clear-screen',
234 'set show-all-if-ambiguous on',
234 'set show-all-if-ambiguous on',
235 '"\C-o": tab-insert',
235 '"\C-o": tab-insert',
236 # See bug gh-58 - with \M-i enabled, chars 0x9000-0x9fff
236 # See bug gh-58 - with \M-i enabled, chars 0x9000-0x9fff
237 # crash IPython.
237 # crash IPython.
238 '"\M-o": "\d\d\d\d"',
238 '"\M-o": "\d\d\d\d"',
239 '"\M-I": "\d\d\d\d"',
239 '"\M-I": "\d\d\d\d"',
240 '"\C-r": reverse-search-history',
240 '"\C-r": reverse-search-history',
241 '"\C-s": forward-search-history',
241 '"\C-s": forward-search-history',
242 '"\C-p": history-search-backward',
242 '"\C-p": history-search-backward',
243 '"\C-n": history-search-forward',
243 '"\C-n": history-search-forward',
244 '"\e[A": history-search-backward',
244 '"\e[A": history-search-backward',
245 '"\e[B": history-search-forward',
245 '"\e[B": history-search-forward',
246 '"\C-k": kill-line',
246 '"\C-k": kill-line',
247 '"\C-u": unix-line-discard',
247 '"\C-u": unix-line-discard',
248 ], allow_none=False, config=True)
248 ], allow_none=False, config=True)
249
249
250 # TODO: this part of prompt management should be moved to the frontends.
250 # TODO: this part of prompt management should be moved to the frontends.
251 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
251 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
252 separate_in = SeparateStr('\n', config=True)
252 separate_in = SeparateStr('\n', config=True)
253 separate_out = SeparateStr('', config=True)
253 separate_out = SeparateStr('', config=True)
254 separate_out2 = SeparateStr('', config=True)
254 separate_out2 = SeparateStr('', config=True)
255 wildcards_case_sensitive = CBool(True, config=True)
255 wildcards_case_sensitive = CBool(True, config=True)
256 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
256 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
257 default_value='Context', config=True)
257 default_value='Context', config=True)
258
258
259 # Subcomponents of InteractiveShell
259 # Subcomponents of InteractiveShell
260 alias_manager = Instance('IPython.core.alias.AliasManager')
260 alias_manager = Instance('IPython.core.alias.AliasManager')
261 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
261 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
262 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
262 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
263 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
263 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
264 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
264 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
265 plugin_manager = Instance('IPython.core.plugin.PluginManager')
265 plugin_manager = Instance('IPython.core.plugin.PluginManager')
266 payload_manager = Instance('IPython.core.payload.PayloadManager')
266 payload_manager = Instance('IPython.core.payload.PayloadManager')
267 history_manager = Instance('IPython.core.history.HistoryManager')
267 history_manager = Instance('IPython.core.history.HistoryManager')
268
268
269 # Private interface
269 # Private interface
270 _post_execute = set()
270 _post_execute = set()
271
271
272 def __init__(self, config=None, ipython_dir=None,
272 def __init__(self, config=None, ipython_dir=None,
273 user_ns=None, user_global_ns=None,
273 user_ns=None, user_global_ns=None,
274 custom_exceptions=((), None)):
274 custom_exceptions=((), None)):
275
275
276 # This is where traits with a config_key argument are updated
276 # This is where traits with a config_key argument are updated
277 # from the values on config.
277 # from the values on config.
278 super(InteractiveShell, self).__init__(config=config)
278 super(InteractiveShell, self).__init__(config=config)
279
279
280 # These are relatively independent and stateless
280 # These are relatively independent and stateless
281 self.init_ipython_dir(ipython_dir)
281 self.init_ipython_dir(ipython_dir)
282 self.init_instance_attrs()
282 self.init_instance_attrs()
283 self.init_environment()
283 self.init_environment()
284
284
285 # Create namespaces (user_ns, user_global_ns, etc.)
285 # Create namespaces (user_ns, user_global_ns, etc.)
286 self.init_create_namespaces(user_ns, user_global_ns)
286 self.init_create_namespaces(user_ns, user_global_ns)
287 # This has to be done after init_create_namespaces because it uses
287 # This has to be done after init_create_namespaces because it uses
288 # something in self.user_ns, but before init_sys_modules, which
288 # something in self.user_ns, but before init_sys_modules, which
289 # is the first thing to modify sys.
289 # is the first thing to modify sys.
290 # TODO: When we override sys.stdout and sys.stderr before this class
290 # TODO: When we override sys.stdout and sys.stderr before this class
291 # is created, we are saving the overridden ones here. Not sure if this
291 # is created, we are saving the overridden ones here. Not sure if this
292 # is what we want to do.
292 # is what we want to do.
293 self.save_sys_module_state()
293 self.save_sys_module_state()
294 self.init_sys_modules()
294 self.init_sys_modules()
295
295
296 # While we're trying to have each part of the code directly access what
296 # While we're trying to have each part of the code directly access what
297 # it needs without keeping redundant references to objects, we have too
297 # it needs without keeping redundant references to objects, we have too
298 # much legacy code that expects ip.db to exist.
298 # much legacy code that expects ip.db to exist.
299 self.db = PickleShareDB(os.path.join(self.ipython_dir, 'db'))
299 self.db = PickleShareDB(os.path.join(self.ipython_dir, 'db'))
300
300
301 self.init_history()
301 self.init_history()
302 self.init_encoding()
302 self.init_encoding()
303 self.init_prefilter()
303 self.init_prefilter()
304
304
305 Magic.__init__(self, self)
305 Magic.__init__(self, self)
306
306
307 self.init_syntax_highlighting()
307 self.init_syntax_highlighting()
308 self.init_hooks()
308 self.init_hooks()
309 self.init_pushd_popd_magic()
309 self.init_pushd_popd_magic()
310 # self.init_traceback_handlers use to be here, but we moved it below
310 # self.init_traceback_handlers use to be here, but we moved it below
311 # because it and init_io have to come after init_readline.
311 # because it and init_io have to come after init_readline.
312 self.init_user_ns()
312 self.init_user_ns()
313 self.init_logger()
313 self.init_logger()
314 self.init_alias()
314 self.init_alias()
315 self.init_builtins()
315 self.init_builtins()
316
316
317 # pre_config_initialization
317 # pre_config_initialization
318
318
319 # The next section should contain everything that was in ipmaker.
319 # The next section should contain everything that was in ipmaker.
320 self.init_logstart()
320 self.init_logstart()
321
321
322 # The following was in post_config_initialization
322 # The following was in post_config_initialization
323 self.init_inspector()
323 self.init_inspector()
324 # init_readline() must come before init_io(), because init_io uses
324 # init_readline() must come before init_io(), because init_io uses
325 # readline related things.
325 # readline related things.
326 self.init_readline()
326 self.init_readline()
327 # init_completer must come after init_readline, because it needs to
327 # init_completer must come after init_readline, because it needs to
328 # know whether readline is present or not system-wide to configure the
328 # know whether readline is present or not system-wide to configure the
329 # completers, since the completion machinery can now operate
329 # completers, since the completion machinery can now operate
330 # independently of readline (e.g. over the network)
330 # independently of readline (e.g. over the network)
331 self.init_completer()
331 self.init_completer()
332 # TODO: init_io() needs to happen before init_traceback handlers
332 # TODO: init_io() needs to happen before init_traceback handlers
333 # because the traceback handlers hardcode the stdout/stderr streams.
333 # because the traceback handlers hardcode the stdout/stderr streams.
334 # This logic in in debugger.Pdb and should eventually be changed.
334 # This logic in in debugger.Pdb and should eventually be changed.
335 self.init_io()
335 self.init_io()
336 self.init_traceback_handlers(custom_exceptions)
336 self.init_traceback_handlers(custom_exceptions)
337 self.init_prompts()
337 self.init_prompts()
338 self.init_display_formatter()
338 self.init_display_formatter()
339 self.init_display_pub()
339 self.init_display_pub()
340 self.init_displayhook()
340 self.init_displayhook()
341 self.init_reload_doctest()
341 self.init_reload_doctest()
342 self.init_magics()
342 self.init_magics()
343 self.init_pdb()
343 self.init_pdb()
344 self.init_extension_manager()
344 self.init_extension_manager()
345 self.init_plugin_manager()
345 self.init_plugin_manager()
346 self.init_payload()
346 self.init_payload()
347 self.hooks.late_startup_hook()
347 self.hooks.late_startup_hook()
348 atexit.register(self.atexit_operations)
348 atexit.register(self.atexit_operations)
349
349
350 @classmethod
350 @classmethod
351 def instance(cls, *args, **kwargs):
351 def instance(cls, *args, **kwargs):
352 """Returns a global InteractiveShell instance."""
352 """Returns a global InteractiveShell instance."""
353 if cls._instance is None:
353 if cls._instance is None:
354 inst = cls(*args, **kwargs)
354 inst = cls(*args, **kwargs)
355 # Now make sure that the instance will also be returned by
355 # Now make sure that the instance will also be returned by
356 # the subclasses instance attribute.
356 # the subclasses instance attribute.
357 for subclass in cls.mro():
357 for subclass in cls.mro():
358 if issubclass(cls, subclass) and \
358 if issubclass(cls, subclass) and \
359 issubclass(subclass, InteractiveShell):
359 issubclass(subclass, InteractiveShell):
360 subclass._instance = inst
360 subclass._instance = inst
361 else:
361 else:
362 break
362 break
363 if isinstance(cls._instance, cls):
363 if isinstance(cls._instance, cls):
364 return cls._instance
364 return cls._instance
365 else:
365 else:
366 raise MultipleInstanceError(
366 raise MultipleInstanceError(
367 'Multiple incompatible subclass instances of '
367 'Multiple incompatible subclass instances of '
368 'InteractiveShell are being created.'
368 'InteractiveShell are being created.'
369 )
369 )
370
370
371 @classmethod
371 @classmethod
372 def initialized(cls):
372 def initialized(cls):
373 return hasattr(cls, "_instance")
373 return hasattr(cls, "_instance")
374
374
375 def get_ipython(self):
375 def get_ipython(self):
376 """Return the currently running IPython instance."""
376 """Return the currently running IPython instance."""
377 return self
377 return self
378
378
379 #-------------------------------------------------------------------------
379 #-------------------------------------------------------------------------
380 # Trait changed handlers
380 # Trait changed handlers
381 #-------------------------------------------------------------------------
381 #-------------------------------------------------------------------------
382
382
383 def _ipython_dir_changed(self, name, new):
383 def _ipython_dir_changed(self, name, new):
384 if not os.path.isdir(new):
384 if not os.path.isdir(new):
385 os.makedirs(new, mode = 0777)
385 os.makedirs(new, mode = 0777)
386
386
387 def set_autoindent(self,value=None):
387 def set_autoindent(self,value=None):
388 """Set the autoindent flag, checking for readline support.
388 """Set the autoindent flag, checking for readline support.
389
389
390 If called with no arguments, it acts as a toggle."""
390 If called with no arguments, it acts as a toggle."""
391
391
392 if not self.has_readline:
392 if not self.has_readline:
393 if os.name == 'posix':
393 if os.name == 'posix':
394 warn("The auto-indent feature requires the readline library")
394 warn("The auto-indent feature requires the readline library")
395 self.autoindent = 0
395 self.autoindent = 0
396 return
396 return
397 if value is None:
397 if value is None:
398 self.autoindent = not self.autoindent
398 self.autoindent = not self.autoindent
399 else:
399 else:
400 self.autoindent = value
400 self.autoindent = value
401
401
402 #-------------------------------------------------------------------------
402 #-------------------------------------------------------------------------
403 # init_* methods called by __init__
403 # init_* methods called by __init__
404 #-------------------------------------------------------------------------
404 #-------------------------------------------------------------------------
405
405
406 def init_ipython_dir(self, ipython_dir):
406 def init_ipython_dir(self, ipython_dir):
407 if ipython_dir is not None:
407 if ipython_dir is not None:
408 self.ipython_dir = ipython_dir
408 self.ipython_dir = ipython_dir
409 self.config.Global.ipython_dir = self.ipython_dir
409 self.config.Global.ipython_dir = self.ipython_dir
410 return
410 return
411
411
412 if hasattr(self.config.Global, 'ipython_dir'):
412 if hasattr(self.config.Global, 'ipython_dir'):
413 self.ipython_dir = self.config.Global.ipython_dir
413 self.ipython_dir = self.config.Global.ipython_dir
414 else:
414 else:
415 self.ipython_dir = get_ipython_dir()
415 self.ipython_dir = get_ipython_dir()
416
416
417 # All children can just read this
417 # All children can just read this
418 self.config.Global.ipython_dir = self.ipython_dir
418 self.config.Global.ipython_dir = self.ipython_dir
419
419
420 def init_instance_attrs(self):
420 def init_instance_attrs(self):
421 self.more = False
421 self.more = False
422
422
423 # command compiler
423 # command compiler
424 self.compile = CachingCompiler()
424 self.compile = CachingCompiler()
425
425
426 # User input buffers
426 # User input buffers
427 # NOTE: these variables are slated for full removal, once we are 100%
427 # NOTE: these variables are slated for full removal, once we are 100%
428 # sure that the new execution logic is solid. We will delte runlines,
428 # sure that the new execution logic is solid. We will delte runlines,
429 # push_line and these buffers, as all input will be managed by the
429 # push_line and these buffers, as all input will be managed by the
430 # frontends via an inputsplitter instance.
430 # frontends via an inputsplitter instance.
431 self.buffer = []
431 self.buffer = []
432 self.buffer_raw = []
432 self.buffer_raw = []
433
433
434 # Make an empty namespace, which extension writers can rely on both
434 # Make an empty namespace, which extension writers can rely on both
435 # existing and NEVER being used by ipython itself. This gives them a
435 # existing and NEVER being used by ipython itself. This gives them a
436 # convenient location for storing additional information and state
436 # convenient location for storing additional information and state
437 # their extensions may require, without fear of collisions with other
437 # their extensions may require, without fear of collisions with other
438 # ipython names that may develop later.
438 # ipython names that may develop later.
439 self.meta = Struct()
439 self.meta = Struct()
440
440
441 # Object variable to store code object waiting execution. This is
441 # Object variable to store code object waiting execution. This is
442 # used mainly by the multithreaded shells, but it can come in handy in
442 # used mainly by the multithreaded shells, but it can come in handy in
443 # other situations. No need to use a Queue here, since it's a single
443 # other situations. No need to use a Queue here, since it's a single
444 # item which gets cleared once run.
444 # item which gets cleared once run.
445 self.code_to_run = None
445 self.code_to_run = None
446
446
447 # Temporary files used for various purposes. Deleted at exit.
447 # Temporary files used for various purposes. Deleted at exit.
448 self.tempfiles = []
448 self.tempfiles = []
449
449
450 # Keep track of readline usage (later set by init_readline)
450 # Keep track of readline usage (later set by init_readline)
451 self.has_readline = False
451 self.has_readline = False
452
452
453 # keep track of where we started running (mainly for crash post-mortem)
453 # keep track of where we started running (mainly for crash post-mortem)
454 # This is not being used anywhere currently.
454 # This is not being used anywhere currently.
455 self.starting_dir = os.getcwd()
455 self.starting_dir = os.getcwd()
456
456
457 # Indentation management
457 # Indentation management
458 self.indent_current_nsp = 0
458 self.indent_current_nsp = 0
459
459
460 def init_environment(self):
460 def init_environment(self):
461 """Any changes we need to make to the user's environment."""
461 """Any changes we need to make to the user's environment."""
462 pass
462 pass
463
463
464 def init_encoding(self):
464 def init_encoding(self):
465 # Get system encoding at startup time. Certain terminals (like Emacs
465 # Get system encoding at startup time. Certain terminals (like Emacs
466 # under Win32 have it set to None, and we need to have a known valid
466 # under Win32 have it set to None, and we need to have a known valid
467 # encoding to use in the raw_input() method
467 # encoding to use in the raw_input() method
468 try:
468 try:
469 self.stdin_encoding = sys.stdin.encoding or 'ascii'
469 self.stdin_encoding = sys.stdin.encoding or 'ascii'
470 except AttributeError:
470 except AttributeError:
471 self.stdin_encoding = 'ascii'
471 self.stdin_encoding = 'ascii'
472
472
473 def init_syntax_highlighting(self):
473 def init_syntax_highlighting(self):
474 # Python source parser/formatter for syntax highlighting
474 # Python source parser/formatter for syntax highlighting
475 pyformat = PyColorize.Parser().format
475 pyformat = PyColorize.Parser().format
476 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
476 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
477
477
478 def init_pushd_popd_magic(self):
478 def init_pushd_popd_magic(self):
479 # for pushd/popd management
479 # for pushd/popd management
480 try:
480 try:
481 self.home_dir = get_home_dir()
481 self.home_dir = get_home_dir()
482 except HomeDirError, msg:
482 except HomeDirError, msg:
483 fatal(msg)
483 fatal(msg)
484
484
485 self.dir_stack = []
485 self.dir_stack = []
486
486
487 def init_logger(self):
487 def init_logger(self):
488 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
488 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
489 logmode='rotate')
489 logmode='rotate')
490
490
491 def init_logstart(self):
491 def init_logstart(self):
492 """Initialize logging in case it was requested at the command line.
492 """Initialize logging in case it was requested at the command line.
493 """
493 """
494 if self.logappend:
494 if self.logappend:
495 self.magic_logstart(self.logappend + ' append')
495 self.magic_logstart(self.logappend + ' append')
496 elif self.logfile:
496 elif self.logfile:
497 self.magic_logstart(self.logfile)
497 self.magic_logstart(self.logfile)
498 elif self.logstart:
498 elif self.logstart:
499 self.magic_logstart()
499 self.magic_logstart()
500
500
501 def init_builtins(self):
501 def init_builtins(self):
502 self.builtin_trap = BuiltinTrap(shell=self)
502 self.builtin_trap = BuiltinTrap(shell=self)
503
503
504 def init_inspector(self):
504 def init_inspector(self):
505 # Object inspector
505 # Object inspector
506 self.inspector = oinspect.Inspector(oinspect.InspectColors,
506 self.inspector = oinspect.Inspector(oinspect.InspectColors,
507 PyColorize.ANSICodeColors,
507 PyColorize.ANSICodeColors,
508 'NoColor',
508 'NoColor',
509 self.object_info_string_level)
509 self.object_info_string_level)
510
510
511 def init_io(self):
511 def init_io(self):
512 # This will just use sys.stdout and sys.stderr. If you want to
512 # This will just use sys.stdout and sys.stderr. If you want to
513 # override sys.stdout and sys.stderr themselves, you need to do that
513 # override sys.stdout and sys.stderr themselves, you need to do that
514 # *before* instantiating this class, because Term holds onto
514 # *before* instantiating this class, because Term holds onto
515 # references to the underlying streams.
515 # references to the underlying streams.
516 if sys.platform == 'win32' and self.has_readline:
516 if sys.platform == 'win32' and self.has_readline:
517 Term = io.IOTerm(cout=self.readline._outputfile,
517 Term = io.IOTerm(cout=self.readline._outputfile,
518 cerr=self.readline._outputfile)
518 cerr=self.readline._outputfile)
519 else:
519 else:
520 Term = io.IOTerm()
520 Term = io.IOTerm()
521 io.Term = Term
521 io.Term = Term
522
522
523 def init_prompts(self):
523 def init_prompts(self):
524 # TODO: This is a pass for now because the prompts are managed inside
524 # TODO: This is a pass for now because the prompts are managed inside
525 # the DisplayHook. Once there is a separate prompt manager, this
525 # the DisplayHook. Once there is a separate prompt manager, this
526 # will initialize that object and all prompt related information.
526 # will initialize that object and all prompt related information.
527 pass
527 pass
528
528
529 def init_display_formatter(self):
529 def init_display_formatter(self):
530 self.display_formatter = DisplayFormatter(config=self.config)
530 self.display_formatter = DisplayFormatter(config=self.config)
531
531
532 def init_display_pub(self):
532 def init_display_pub(self):
533 self.display_pub = self.display_pub_class(config=self.config)
533 self.display_pub = self.display_pub_class(config=self.config)
534
534
535 def init_displayhook(self):
535 def init_displayhook(self):
536 # Initialize displayhook, set in/out prompts and printing system
536 # Initialize displayhook, set in/out prompts and printing system
537 self.displayhook = self.displayhook_class(
537 self.displayhook = self.displayhook_class(
538 config=self.config,
538 config=self.config,
539 shell=self,
539 shell=self,
540 cache_size=self.cache_size,
540 cache_size=self.cache_size,
541 input_sep = self.separate_in,
541 input_sep = self.separate_in,
542 output_sep = self.separate_out,
542 output_sep = self.separate_out,
543 output_sep2 = self.separate_out2,
543 output_sep2 = self.separate_out2,
544 ps1 = self.prompt_in1,
544 ps1 = self.prompt_in1,
545 ps2 = self.prompt_in2,
545 ps2 = self.prompt_in2,
546 ps_out = self.prompt_out,
546 ps_out = self.prompt_out,
547 pad_left = self.prompts_pad_left
547 pad_left = self.prompts_pad_left
548 )
548 )
549 # This is a context manager that installs/revmoes the displayhook at
549 # This is a context manager that installs/revmoes the displayhook at
550 # the appropriate time.
550 # the appropriate time.
551 self.display_trap = DisplayTrap(hook=self.displayhook)
551 self.display_trap = DisplayTrap(hook=self.displayhook)
552
552
553 def init_reload_doctest(self):
553 def init_reload_doctest(self):
554 # Do a proper resetting of doctest, including the necessary displayhook
554 # Do a proper resetting of doctest, including the necessary displayhook
555 # monkeypatching
555 # monkeypatching
556 try:
556 try:
557 doctest_reload()
557 doctest_reload()
558 except ImportError:
558 except ImportError:
559 warn("doctest module does not exist.")
559 warn("doctest module does not exist.")
560
560
561 #-------------------------------------------------------------------------
561 #-------------------------------------------------------------------------
562 # Things related to injections into the sys module
562 # Things related to injections into the sys module
563 #-------------------------------------------------------------------------
563 #-------------------------------------------------------------------------
564
564
565 def save_sys_module_state(self):
565 def save_sys_module_state(self):
566 """Save the state of hooks in the sys module.
566 """Save the state of hooks in the sys module.
567
567
568 This has to be called after self.user_ns is created.
568 This has to be called after self.user_ns is created.
569 """
569 """
570 self._orig_sys_module_state = {}
570 self._orig_sys_module_state = {}
571 self._orig_sys_module_state['stdin'] = sys.stdin
571 self._orig_sys_module_state['stdin'] = sys.stdin
572 self._orig_sys_module_state['stdout'] = sys.stdout
572 self._orig_sys_module_state['stdout'] = sys.stdout
573 self._orig_sys_module_state['stderr'] = sys.stderr
573 self._orig_sys_module_state['stderr'] = sys.stderr
574 self._orig_sys_module_state['excepthook'] = sys.excepthook
574 self._orig_sys_module_state['excepthook'] = sys.excepthook
575 try:
575 try:
576 self._orig_sys_modules_main_name = self.user_ns['__name__']
576 self._orig_sys_modules_main_name = self.user_ns['__name__']
577 except KeyError:
577 except KeyError:
578 pass
578 pass
579
579
580 def restore_sys_module_state(self):
580 def restore_sys_module_state(self):
581 """Restore the state of the sys module."""
581 """Restore the state of the sys module."""
582 try:
582 try:
583 for k, v in self._orig_sys_module_state.iteritems():
583 for k, v in self._orig_sys_module_state.iteritems():
584 setattr(sys, k, v)
584 setattr(sys, k, v)
585 except AttributeError:
585 except AttributeError:
586 pass
586 pass
587 # Reset what what done in self.init_sys_modules
587 # Reset what what done in self.init_sys_modules
588 try:
588 try:
589 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
589 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
590 except (AttributeError, KeyError):
590 except (AttributeError, KeyError):
591 pass
591 pass
592
592
593 #-------------------------------------------------------------------------
593 #-------------------------------------------------------------------------
594 # Things related to hooks
594 # Things related to hooks
595 #-------------------------------------------------------------------------
595 #-------------------------------------------------------------------------
596
596
597 def init_hooks(self):
597 def init_hooks(self):
598 # hooks holds pointers used for user-side customizations
598 # hooks holds pointers used for user-side customizations
599 self.hooks = Struct()
599 self.hooks = Struct()
600
600
601 self.strdispatchers = {}
601 self.strdispatchers = {}
602
602
603 # Set all default hooks, defined in the IPython.hooks module.
603 # Set all default hooks, defined in the IPython.hooks module.
604 hooks = IPython.core.hooks
604 hooks = IPython.core.hooks
605 for hook_name in hooks.__all__:
605 for hook_name in hooks.__all__:
606 # default hooks have priority 100, i.e. low; user hooks should have
606 # default hooks have priority 100, i.e. low; user hooks should have
607 # 0-100 priority
607 # 0-100 priority
608 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
608 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
609
609
610 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
610 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
611 """set_hook(name,hook) -> sets an internal IPython hook.
611 """set_hook(name,hook) -> sets an internal IPython hook.
612
612
613 IPython exposes some of its internal API as user-modifiable hooks. By
613 IPython exposes some of its internal API as user-modifiable hooks. By
614 adding your function to one of these hooks, you can modify IPython's
614 adding your function to one of these hooks, you can modify IPython's
615 behavior to call at runtime your own routines."""
615 behavior to call at runtime your own routines."""
616
616
617 # At some point in the future, this should validate the hook before it
617 # At some point in the future, this should validate the hook before it
618 # accepts it. Probably at least check that the hook takes the number
618 # accepts it. Probably at least check that the hook takes the number
619 # of args it's supposed to.
619 # of args it's supposed to.
620
620
621 f = types.MethodType(hook,self)
621 f = types.MethodType(hook,self)
622
622
623 # check if the hook is for strdispatcher first
623 # check if the hook is for strdispatcher first
624 if str_key is not None:
624 if str_key is not None:
625 sdp = self.strdispatchers.get(name, StrDispatch())
625 sdp = self.strdispatchers.get(name, StrDispatch())
626 sdp.add_s(str_key, f, priority )
626 sdp.add_s(str_key, f, priority )
627 self.strdispatchers[name] = sdp
627 self.strdispatchers[name] = sdp
628 return
628 return
629 if re_key is not None:
629 if re_key is not None:
630 sdp = self.strdispatchers.get(name, StrDispatch())
630 sdp = self.strdispatchers.get(name, StrDispatch())
631 sdp.add_re(re.compile(re_key), f, priority )
631 sdp.add_re(re.compile(re_key), f, priority )
632 self.strdispatchers[name] = sdp
632 self.strdispatchers[name] = sdp
633 return
633 return
634
634
635 dp = getattr(self.hooks, name, None)
635 dp = getattr(self.hooks, name, None)
636 if name not in IPython.core.hooks.__all__:
636 if name not in IPython.core.hooks.__all__:
637 print "Warning! Hook '%s' is not one of %s" % \
637 print "Warning! Hook '%s' is not one of %s" % \
638 (name, IPython.core.hooks.__all__ )
638 (name, IPython.core.hooks.__all__ )
639 if not dp:
639 if not dp:
640 dp = IPython.core.hooks.CommandChainDispatcher()
640 dp = IPython.core.hooks.CommandChainDispatcher()
641
641
642 try:
642 try:
643 dp.add(f,priority)
643 dp.add(f,priority)
644 except AttributeError:
644 except AttributeError:
645 # it was not commandchain, plain old func - replace
645 # it was not commandchain, plain old func - replace
646 dp = f
646 dp = f
647
647
648 setattr(self.hooks,name, dp)
648 setattr(self.hooks,name, dp)
649
649
650 def register_post_execute(self, func):
650 def register_post_execute(self, func):
651 """Register a function for calling after code execution.
651 """Register a function for calling after code execution.
652 """
652 """
653 if not callable(func):
653 if not callable(func):
654 raise ValueError('argument %s must be callable' % func)
654 raise ValueError('argument %s must be callable' % func)
655 self._post_execute.add(func)
655 self._post_execute.add(func)
656
656
657 #-------------------------------------------------------------------------
657 #-------------------------------------------------------------------------
658 # Things related to the "main" module
658 # Things related to the "main" module
659 #-------------------------------------------------------------------------
659 #-------------------------------------------------------------------------
660
660
661 def new_main_mod(self,ns=None):
661 def new_main_mod(self,ns=None):
662 """Return a new 'main' module object for user code execution.
662 """Return a new 'main' module object for user code execution.
663 """
663 """
664 main_mod = self._user_main_module
664 main_mod = self._user_main_module
665 init_fakemod_dict(main_mod,ns)
665 init_fakemod_dict(main_mod,ns)
666 return main_mod
666 return main_mod
667
667
668 def cache_main_mod(self,ns,fname):
668 def cache_main_mod(self,ns,fname):
669 """Cache a main module's namespace.
669 """Cache a main module's namespace.
670
670
671 When scripts are executed via %run, we must keep a reference to the
671 When scripts are executed via %run, we must keep a reference to the
672 namespace of their __main__ module (a FakeModule instance) around so
672 namespace of their __main__ module (a FakeModule instance) around so
673 that Python doesn't clear it, rendering objects defined therein
673 that Python doesn't clear it, rendering objects defined therein
674 useless.
674 useless.
675
675
676 This method keeps said reference in a private dict, keyed by the
676 This method keeps said reference in a private dict, keyed by the
677 absolute path of the module object (which corresponds to the script
677 absolute path of the module object (which corresponds to the script
678 path). This way, for multiple executions of the same script we only
678 path). This way, for multiple executions of the same script we only
679 keep one copy of the namespace (the last one), thus preventing memory
679 keep one copy of the namespace (the last one), thus preventing memory
680 leaks from old references while allowing the objects from the last
680 leaks from old references while allowing the objects from the last
681 execution to be accessible.
681 execution to be accessible.
682
682
683 Note: we can not allow the actual FakeModule instances to be deleted,
683 Note: we can not allow the actual FakeModule instances to be deleted,
684 because of how Python tears down modules (it hard-sets all their
684 because of how Python tears down modules (it hard-sets all their
685 references to None without regard for reference counts). This method
685 references to None without regard for reference counts). This method
686 must therefore make a *copy* of the given namespace, to allow the
686 must therefore make a *copy* of the given namespace, to allow the
687 original module's __dict__ to be cleared and reused.
687 original module's __dict__ to be cleared and reused.
688
688
689
689
690 Parameters
690 Parameters
691 ----------
691 ----------
692 ns : a namespace (a dict, typically)
692 ns : a namespace (a dict, typically)
693
693
694 fname : str
694 fname : str
695 Filename associated with the namespace.
695 Filename associated with the namespace.
696
696
697 Examples
697 Examples
698 --------
698 --------
699
699
700 In [10]: import IPython
700 In [10]: import IPython
701
701
702 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
702 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
703
703
704 In [12]: IPython.__file__ in _ip._main_ns_cache
704 In [12]: IPython.__file__ in _ip._main_ns_cache
705 Out[12]: True
705 Out[12]: True
706 """
706 """
707 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
707 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
708
708
709 def clear_main_mod_cache(self):
709 def clear_main_mod_cache(self):
710 """Clear the cache of main modules.
710 """Clear the cache of main modules.
711
711
712 Mainly for use by utilities like %reset.
712 Mainly for use by utilities like %reset.
713
713
714 Examples
714 Examples
715 --------
715 --------
716
716
717 In [15]: import IPython
717 In [15]: import IPython
718
718
719 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
719 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
720
720
721 In [17]: len(_ip._main_ns_cache) > 0
721 In [17]: len(_ip._main_ns_cache) > 0
722 Out[17]: True
722 Out[17]: True
723
723
724 In [18]: _ip.clear_main_mod_cache()
724 In [18]: _ip.clear_main_mod_cache()
725
725
726 In [19]: len(_ip._main_ns_cache) == 0
726 In [19]: len(_ip._main_ns_cache) == 0
727 Out[19]: True
727 Out[19]: True
728 """
728 """
729 self._main_ns_cache.clear()
729 self._main_ns_cache.clear()
730
730
731 #-------------------------------------------------------------------------
731 #-------------------------------------------------------------------------
732 # Things related to debugging
732 # Things related to debugging
733 #-------------------------------------------------------------------------
733 #-------------------------------------------------------------------------
734
734
735 def init_pdb(self):
735 def init_pdb(self):
736 # Set calling of pdb on exceptions
736 # Set calling of pdb on exceptions
737 # self.call_pdb is a property
737 # self.call_pdb is a property
738 self.call_pdb = self.pdb
738 self.call_pdb = self.pdb
739
739
740 def _get_call_pdb(self):
740 def _get_call_pdb(self):
741 return self._call_pdb
741 return self._call_pdb
742
742
743 def _set_call_pdb(self,val):
743 def _set_call_pdb(self,val):
744
744
745 if val not in (0,1,False,True):
745 if val not in (0,1,False,True):
746 raise ValueError,'new call_pdb value must be boolean'
746 raise ValueError,'new call_pdb value must be boolean'
747
747
748 # store value in instance
748 # store value in instance
749 self._call_pdb = val
749 self._call_pdb = val
750
750
751 # notify the actual exception handlers
751 # notify the actual exception handlers
752 self.InteractiveTB.call_pdb = val
752 self.InteractiveTB.call_pdb = val
753
753
754 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
754 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
755 'Control auto-activation of pdb at exceptions')
755 'Control auto-activation of pdb at exceptions')
756
756
757 def debugger(self,force=False):
757 def debugger(self,force=False):
758 """Call the pydb/pdb debugger.
758 """Call the pydb/pdb debugger.
759
759
760 Keywords:
760 Keywords:
761
761
762 - force(False): by default, this routine checks the instance call_pdb
762 - force(False): by default, this routine checks the instance call_pdb
763 flag and does not actually invoke the debugger if the flag is false.
763 flag and does not actually invoke the debugger if the flag is false.
764 The 'force' option forces the debugger to activate even if the flag
764 The 'force' option forces the debugger to activate even if the flag
765 is false.
765 is false.
766 """
766 """
767
767
768 if not (force or self.call_pdb):
768 if not (force or self.call_pdb):
769 return
769 return
770
770
771 if not hasattr(sys,'last_traceback'):
771 if not hasattr(sys,'last_traceback'):
772 error('No traceback has been produced, nothing to debug.')
772 error('No traceback has been produced, nothing to debug.')
773 return
773 return
774
774
775 # use pydb if available
775 # use pydb if available
776 if debugger.has_pydb:
776 if debugger.has_pydb:
777 from pydb import pm
777 from pydb import pm
778 else:
778 else:
779 # fallback to our internal debugger
779 # fallback to our internal debugger
780 pm = lambda : self.InteractiveTB.debugger(force=True)
780 pm = lambda : self.InteractiveTB.debugger(force=True)
781
781
782 with self.readline_no_record:
782 with self.readline_no_record:
783 pm()
783 pm()
784
784
785 #-------------------------------------------------------------------------
785 #-------------------------------------------------------------------------
786 # Things related to IPython's various namespaces
786 # Things related to IPython's various namespaces
787 #-------------------------------------------------------------------------
787 #-------------------------------------------------------------------------
788
788
789 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
789 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
790 # Create the namespace where the user will operate. user_ns is
790 # Create the namespace where the user will operate. user_ns is
791 # normally the only one used, and it is passed to the exec calls as
791 # normally the only one used, and it is passed to the exec calls as
792 # the locals argument. But we do carry a user_global_ns namespace
792 # the locals argument. But we do carry a user_global_ns namespace
793 # given as the exec 'globals' argument, This is useful in embedding
793 # given as the exec 'globals' argument, This is useful in embedding
794 # situations where the ipython shell opens in a context where the
794 # situations where the ipython shell opens in a context where the
795 # distinction between locals and globals is meaningful. For
795 # distinction between locals and globals is meaningful. For
796 # non-embedded contexts, it is just the same object as the user_ns dict.
796 # non-embedded contexts, it is just the same object as the user_ns dict.
797
797
798 # FIXME. For some strange reason, __builtins__ is showing up at user
798 # FIXME. For some strange reason, __builtins__ is showing up at user
799 # level as a dict instead of a module. This is a manual fix, but I
799 # level as a dict instead of a module. This is a manual fix, but I
800 # should really track down where the problem is coming from. Alex
800 # should really track down where the problem is coming from. Alex
801 # Schmolck reported this problem first.
801 # Schmolck reported this problem first.
802
802
803 # A useful post by Alex Martelli on this topic:
803 # A useful post by Alex Martelli on this topic:
804 # Re: inconsistent value from __builtins__
804 # Re: inconsistent value from __builtins__
805 # Von: Alex Martelli <aleaxit@yahoo.com>
805 # Von: Alex Martelli <aleaxit@yahoo.com>
806 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
806 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
807 # Gruppen: comp.lang.python
807 # Gruppen: comp.lang.python
808
808
809 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
809 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
810 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
810 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
811 # > <type 'dict'>
811 # > <type 'dict'>
812 # > >>> print type(__builtins__)
812 # > >>> print type(__builtins__)
813 # > <type 'module'>
813 # > <type 'module'>
814 # > Is this difference in return value intentional?
814 # > Is this difference in return value intentional?
815
815
816 # Well, it's documented that '__builtins__' can be either a dictionary
816 # Well, it's documented that '__builtins__' can be either a dictionary
817 # or a module, and it's been that way for a long time. Whether it's
817 # or a module, and it's been that way for a long time. Whether it's
818 # intentional (or sensible), I don't know. In any case, the idea is
818 # intentional (or sensible), I don't know. In any case, the idea is
819 # that if you need to access the built-in namespace directly, you
819 # that if you need to access the built-in namespace directly, you
820 # should start with "import __builtin__" (note, no 's') which will
820 # should start with "import __builtin__" (note, no 's') which will
821 # definitely give you a module. Yeah, it's somewhat confusing:-(.
821 # definitely give you a module. Yeah, it's somewhat confusing:-(.
822
822
823 # These routines return properly built dicts as needed by the rest of
823 # These routines return properly built dicts as needed by the rest of
824 # the code, and can also be used by extension writers to generate
824 # the code, and can also be used by extension writers to generate
825 # properly initialized namespaces.
825 # properly initialized namespaces.
826 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
826 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
827 user_global_ns)
827 user_global_ns)
828
828
829 # Assign namespaces
829 # Assign namespaces
830 # This is the namespace where all normal user variables live
830 # This is the namespace where all normal user variables live
831 self.user_ns = user_ns
831 self.user_ns = user_ns
832 self.user_global_ns = user_global_ns
832 self.user_global_ns = user_global_ns
833
833
834 # An auxiliary namespace that checks what parts of the user_ns were
834 # An auxiliary namespace that checks what parts of the user_ns were
835 # loaded at startup, so we can list later only variables defined in
835 # loaded at startup, so we can list later only variables defined in
836 # actual interactive use. Since it is always a subset of user_ns, it
836 # actual interactive use. Since it is always a subset of user_ns, it
837 # doesn't need to be separately tracked in the ns_table.
837 # doesn't need to be separately tracked in the ns_table.
838 self.user_ns_hidden = {}
838 self.user_ns_hidden = {}
839
839
840 # A namespace to keep track of internal data structures to prevent
840 # A namespace to keep track of internal data structures to prevent
841 # them from cluttering user-visible stuff. Will be updated later
841 # them from cluttering user-visible stuff. Will be updated later
842 self.internal_ns = {}
842 self.internal_ns = {}
843
843
844 # Now that FakeModule produces a real module, we've run into a nasty
844 # Now that FakeModule produces a real module, we've run into a nasty
845 # problem: after script execution (via %run), the module where the user
845 # problem: after script execution (via %run), the module where the user
846 # code ran is deleted. Now that this object is a true module (needed
846 # code ran is deleted. Now that this object is a true module (needed
847 # so docetst and other tools work correctly), the Python module
847 # so docetst and other tools work correctly), the Python module
848 # teardown mechanism runs over it, and sets to None every variable
848 # teardown mechanism runs over it, and sets to None every variable
849 # present in that module. Top-level references to objects from the
849 # present in that module. Top-level references to objects from the
850 # script survive, because the user_ns is updated with them. However,
850 # script survive, because the user_ns is updated with them. However,
851 # calling functions defined in the script that use other things from
851 # calling functions defined in the script that use other things from
852 # the script will fail, because the function's closure had references
852 # the script will fail, because the function's closure had references
853 # to the original objects, which are now all None. So we must protect
853 # to the original objects, which are now all None. So we must protect
854 # these modules from deletion by keeping a cache.
854 # these modules from deletion by keeping a cache.
855 #
855 #
856 # To avoid keeping stale modules around (we only need the one from the
856 # To avoid keeping stale modules around (we only need the one from the
857 # last run), we use a dict keyed with the full path to the script, so
857 # last run), we use a dict keyed with the full path to the script, so
858 # only the last version of the module is held in the cache. Note,
858 # only the last version of the module is held in the cache. Note,
859 # however, that we must cache the module *namespace contents* (their
859 # however, that we must cache the module *namespace contents* (their
860 # __dict__). Because if we try to cache the actual modules, old ones
860 # __dict__). Because if we try to cache the actual modules, old ones
861 # (uncached) could be destroyed while still holding references (such as
861 # (uncached) could be destroyed while still holding references (such as
862 # those held by GUI objects that tend to be long-lived)>
862 # those held by GUI objects that tend to be long-lived)>
863 #
863 #
864 # The %reset command will flush this cache. See the cache_main_mod()
864 # The %reset command will flush this cache. See the cache_main_mod()
865 # and clear_main_mod_cache() methods for details on use.
865 # and clear_main_mod_cache() methods for details on use.
866
866
867 # This is the cache used for 'main' namespaces
867 # This is the cache used for 'main' namespaces
868 self._main_ns_cache = {}
868 self._main_ns_cache = {}
869 # And this is the single instance of FakeModule whose __dict__ we keep
869 # And this is the single instance of FakeModule whose __dict__ we keep
870 # copying and clearing for reuse on each %run
870 # copying and clearing for reuse on each %run
871 self._user_main_module = FakeModule()
871 self._user_main_module = FakeModule()
872
872
873 # A table holding all the namespaces IPython deals with, so that
873 # A table holding all the namespaces IPython deals with, so that
874 # introspection facilities can search easily.
874 # introspection facilities can search easily.
875 self.ns_table = {'user':user_ns,
875 self.ns_table = {'user':user_ns,
876 'user_global':user_global_ns,
876 'user_global':user_global_ns,
877 'internal':self.internal_ns,
877 'internal':self.internal_ns,
878 'builtin':__builtin__.__dict__
878 'builtin':__builtin__.__dict__
879 }
879 }
880
880
881 # Similarly, track all namespaces where references can be held and that
881 # Similarly, track all namespaces where references can be held and that
882 # we can safely clear (so it can NOT include builtin). This one can be
882 # we can safely clear (so it can NOT include builtin). This one can be
883 # a simple list. Note that the main execution namespaces, user_ns and
883 # a simple list. Note that the main execution namespaces, user_ns and
884 # user_global_ns, can NOT be listed here, as clearing them blindly
884 # user_global_ns, can NOT be listed here, as clearing them blindly
885 # causes errors in object __del__ methods. Instead, the reset() method
885 # causes errors in object __del__ methods. Instead, the reset() method
886 # clears them manually and carefully.
886 # clears them manually and carefully.
887 self.ns_refs_table = [ self.user_ns_hidden,
887 self.ns_refs_table = [ self.user_ns_hidden,
888 self.internal_ns, self._main_ns_cache ]
888 self.internal_ns, self._main_ns_cache ]
889
889
890 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
890 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
891 """Return a valid local and global user interactive namespaces.
891 """Return a valid local and global user interactive namespaces.
892
892
893 This builds a dict with the minimal information needed to operate as a
893 This builds a dict with the minimal information needed to operate as a
894 valid IPython user namespace, which you can pass to the various
894 valid IPython user namespace, which you can pass to the various
895 embedding classes in ipython. The default implementation returns the
895 embedding classes in ipython. The default implementation returns the
896 same dict for both the locals and the globals to allow functions to
896 same dict for both the locals and the globals to allow functions to
897 refer to variables in the namespace. Customized implementations can
897 refer to variables in the namespace. Customized implementations can
898 return different dicts. The locals dictionary can actually be anything
898 return different dicts. The locals dictionary can actually be anything
899 following the basic mapping protocol of a dict, but the globals dict
899 following the basic mapping protocol of a dict, but the globals dict
900 must be a true dict, not even a subclass. It is recommended that any
900 must be a true dict, not even a subclass. It is recommended that any
901 custom object for the locals namespace synchronize with the globals
901 custom object for the locals namespace synchronize with the globals
902 dict somehow.
902 dict somehow.
903
903
904 Raises TypeError if the provided globals namespace is not a true dict.
904 Raises TypeError if the provided globals namespace is not a true dict.
905
905
906 Parameters
906 Parameters
907 ----------
907 ----------
908 user_ns : dict-like, optional
908 user_ns : dict-like, optional
909 The current user namespace. The items in this namespace should
909 The current user namespace. The items in this namespace should
910 be included in the output. If None, an appropriate blank
910 be included in the output. If None, an appropriate blank
911 namespace should be created.
911 namespace should be created.
912 user_global_ns : dict, optional
912 user_global_ns : dict, optional
913 The current user global namespace. The items in this namespace
913 The current user global namespace. The items in this namespace
914 should be included in the output. If None, an appropriate
914 should be included in the output. If None, an appropriate
915 blank namespace should be created.
915 blank namespace should be created.
916
916
917 Returns
917 Returns
918 -------
918 -------
919 A pair of dictionary-like object to be used as the local namespace
919 A pair of dictionary-like object to be used as the local namespace
920 of the interpreter and a dict to be used as the global namespace.
920 of the interpreter and a dict to be used as the global namespace.
921 """
921 """
922
922
923
923
924 # We must ensure that __builtin__ (without the final 's') is always
924 # We must ensure that __builtin__ (without the final 's') is always
925 # available and pointing to the __builtin__ *module*. For more details:
925 # available and pointing to the __builtin__ *module*. For more details:
926 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
926 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
927
927
928 if user_ns is None:
928 if user_ns is None:
929 # Set __name__ to __main__ to better match the behavior of the
929 # Set __name__ to __main__ to better match the behavior of the
930 # normal interpreter.
930 # normal interpreter.
931 user_ns = {'__name__' :'__main__',
931 user_ns = {'__name__' :'__main__',
932 '__builtin__' : __builtin__,
932 '__builtin__' : __builtin__,
933 '__builtins__' : __builtin__,
933 '__builtins__' : __builtin__,
934 }
934 }
935 else:
935 else:
936 user_ns.setdefault('__name__','__main__')
936 user_ns.setdefault('__name__','__main__')
937 user_ns.setdefault('__builtin__',__builtin__)
937 user_ns.setdefault('__builtin__',__builtin__)
938 user_ns.setdefault('__builtins__',__builtin__)
938 user_ns.setdefault('__builtins__',__builtin__)
939
939
940 if user_global_ns is None:
940 if user_global_ns is None:
941 user_global_ns = user_ns
941 user_global_ns = user_ns
942 if type(user_global_ns) is not dict:
942 if type(user_global_ns) is not dict:
943 raise TypeError("user_global_ns must be a true dict; got %r"
943 raise TypeError("user_global_ns must be a true dict; got %r"
944 % type(user_global_ns))
944 % type(user_global_ns))
945
945
946 return user_ns, user_global_ns
946 return user_ns, user_global_ns
947
947
948 def init_sys_modules(self):
948 def init_sys_modules(self):
949 # We need to insert into sys.modules something that looks like a
949 # We need to insert into sys.modules something that looks like a
950 # module but which accesses the IPython namespace, for shelve and
950 # module but which accesses the IPython namespace, for shelve and
951 # pickle to work interactively. Normally they rely on getting
951 # pickle to work interactively. Normally they rely on getting
952 # everything out of __main__, but for embedding purposes each IPython
952 # everything out of __main__, but for embedding purposes each IPython
953 # instance has its own private namespace, so we can't go shoving
953 # instance has its own private namespace, so we can't go shoving
954 # everything into __main__.
954 # everything into __main__.
955
955
956 # note, however, that we should only do this for non-embedded
956 # note, however, that we should only do this for non-embedded
957 # ipythons, which really mimic the __main__.__dict__ with their own
957 # ipythons, which really mimic the __main__.__dict__ with their own
958 # namespace. Embedded instances, on the other hand, should not do
958 # namespace. Embedded instances, on the other hand, should not do
959 # this because they need to manage the user local/global namespaces
959 # this because they need to manage the user local/global namespaces
960 # only, but they live within a 'normal' __main__ (meaning, they
960 # only, but they live within a 'normal' __main__ (meaning, they
961 # shouldn't overtake the execution environment of the script they're
961 # shouldn't overtake the execution environment of the script they're
962 # embedded in).
962 # embedded in).
963
963
964 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
964 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
965
965
966 try:
966 try:
967 main_name = self.user_ns['__name__']
967 main_name = self.user_ns['__name__']
968 except KeyError:
968 except KeyError:
969 raise KeyError('user_ns dictionary MUST have a "__name__" key')
969 raise KeyError('user_ns dictionary MUST have a "__name__" key')
970 else:
970 else:
971 sys.modules[main_name] = FakeModule(self.user_ns)
971 sys.modules[main_name] = FakeModule(self.user_ns)
972
972
973 def init_user_ns(self):
973 def init_user_ns(self):
974 """Initialize all user-visible namespaces to their minimum defaults.
974 """Initialize all user-visible namespaces to their minimum defaults.
975
975
976 Certain history lists are also initialized here, as they effectively
976 Certain history lists are also initialized here, as they effectively
977 act as user namespaces.
977 act as user namespaces.
978
978
979 Notes
979 Notes
980 -----
980 -----
981 All data structures here are only filled in, they are NOT reset by this
981 All data structures here are only filled in, they are NOT reset by this
982 method. If they were not empty before, data will simply be added to
982 method. If they were not empty before, data will simply be added to
983 therm.
983 therm.
984 """
984 """
985 # This function works in two parts: first we put a few things in
985 # This function works in two parts: first we put a few things in
986 # user_ns, and we sync that contents into user_ns_hidden so that these
986 # user_ns, and we sync that contents into user_ns_hidden so that these
987 # initial variables aren't shown by %who. After the sync, we add the
987 # initial variables aren't shown by %who. After the sync, we add the
988 # rest of what we *do* want the user to see with %who even on a new
988 # rest of what we *do* want the user to see with %who even on a new
989 # session (probably nothing, so theye really only see their own stuff)
989 # session (probably nothing, so theye really only see their own stuff)
990
990
991 # The user dict must *always* have a __builtin__ reference to the
991 # The user dict must *always* have a __builtin__ reference to the
992 # Python standard __builtin__ namespace, which must be imported.
992 # Python standard __builtin__ namespace, which must be imported.
993 # This is so that certain operations in prompt evaluation can be
993 # This is so that certain operations in prompt evaluation can be
994 # reliably executed with builtins. Note that we can NOT use
994 # reliably executed with builtins. Note that we can NOT use
995 # __builtins__ (note the 's'), because that can either be a dict or a
995 # __builtins__ (note the 's'), because that can either be a dict or a
996 # module, and can even mutate at runtime, depending on the context
996 # module, and can even mutate at runtime, depending on the context
997 # (Python makes no guarantees on it). In contrast, __builtin__ is
997 # (Python makes no guarantees on it). In contrast, __builtin__ is
998 # always a module object, though it must be explicitly imported.
998 # always a module object, though it must be explicitly imported.
999
999
1000 # For more details:
1000 # For more details:
1001 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1001 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1002 ns = dict(__builtin__ = __builtin__)
1002 ns = dict(__builtin__ = __builtin__)
1003
1003
1004 # Put 'help' in the user namespace
1004 # Put 'help' in the user namespace
1005 try:
1005 try:
1006 from site import _Helper
1006 from site import _Helper
1007 ns['help'] = _Helper()
1007 ns['help'] = _Helper()
1008 except ImportError:
1008 except ImportError:
1009 warn('help() not available - check site.py')
1009 warn('help() not available - check site.py')
1010
1010
1011 # make global variables for user access to the histories
1011 # make global variables for user access to the histories
1012 ns['_ih'] = self.history_manager.input_hist_parsed
1012 ns['_ih'] = self.history_manager.input_hist_parsed
1013 ns['_oh'] = self.history_manager.output_hist
1013 ns['_oh'] = self.history_manager.output_hist
1014 ns['_dh'] = self.history_manager.dir_hist
1014 ns['_dh'] = self.history_manager.dir_hist
1015
1015
1016 ns['_sh'] = shadowns
1016 ns['_sh'] = shadowns
1017
1017
1018 # user aliases to input and output histories. These shouldn't show up
1018 # user aliases to input and output histories. These shouldn't show up
1019 # in %who, as they can have very large reprs.
1019 # in %who, as they can have very large reprs.
1020 ns['In'] = self.history_manager.input_hist_parsed
1020 ns['In'] = self.history_manager.input_hist_parsed
1021 ns['Out'] = self.history_manager.output_hist
1021 ns['Out'] = self.history_manager.output_hist
1022
1022
1023 # Store myself as the public api!!!
1023 # Store myself as the public api!!!
1024 ns['get_ipython'] = self.get_ipython
1024 ns['get_ipython'] = self.get_ipython
1025
1025
1026 # Sync what we've added so far to user_ns_hidden so these aren't seen
1026 # Sync what we've added so far to user_ns_hidden so these aren't seen
1027 # by %who
1027 # by %who
1028 self.user_ns_hidden.update(ns)
1028 self.user_ns_hidden.update(ns)
1029
1029
1030 # Anything put into ns now would show up in %who. Think twice before
1030 # Anything put into ns now would show up in %who. Think twice before
1031 # putting anything here, as we really want %who to show the user their
1031 # putting anything here, as we really want %who to show the user their
1032 # stuff, not our variables.
1032 # stuff, not our variables.
1033
1033
1034 # Finally, update the real user's namespace
1034 # Finally, update the real user's namespace
1035 self.user_ns.update(ns)
1035 self.user_ns.update(ns)
1036
1036
1037 def reset(self, new_session=True):
1037 def reset(self, new_session=True):
1038 """Clear all internal namespaces.
1038 """Clear all internal namespaces.
1039
1039
1040 Note that this is much more aggressive than %reset, since it clears
1040 Note that this is much more aggressive than %reset, since it clears
1041 fully all namespaces, as well as all input/output lists.
1041 fully all namespaces, as well as all input/output lists.
1042
1042
1043 If new_session is True, a new history session will be opened.
1043 If new_session is True, a new history session will be opened.
1044 """
1044 """
1045 # Clear histories
1045 # Clear histories
1046 self.history_manager.reset(new_session)
1046 self.history_manager.reset(new_session)
1047
1048 # Flush cached output items
1049 self.displayhook.flush()
1047
1050
1048 # Reset counter used to index all histories
1051 # Reset counter used to index all histories
1049 self.execution_count = 0
1052 self.execution_count = 0
1050
1053
1051 # Restore the user namespaces to minimal usability
1054 # Restore the user namespaces to minimal usability
1052 for ns in self.ns_refs_table:
1055 for ns in self.ns_refs_table:
1053 ns.clear()
1056 ns.clear()
1054
1057
1055 # The main execution namespaces must be cleared very carefully,
1058 # The main execution namespaces must be cleared very carefully,
1056 # skipping the deletion of the builtin-related keys, because doing so
1059 # skipping the deletion of the builtin-related keys, because doing so
1057 # would cause errors in many object's __del__ methods.
1060 # would cause errors in many object's __del__ methods.
1058 for ns in [self.user_ns, self.user_global_ns]:
1061 for ns in [self.user_ns, self.user_global_ns]:
1059 drop_keys = set(ns.keys())
1062 drop_keys = set(ns.keys())
1060 drop_keys.discard('__builtin__')
1063 drop_keys.discard('__builtin__')
1061 drop_keys.discard('__builtins__')
1064 drop_keys.discard('__builtins__')
1062 for k in drop_keys:
1065 for k in drop_keys:
1063 del ns[k]
1066 del ns[k]
1064
1067
1065 # Restore the user namespaces to minimal usability
1068 # Restore the user namespaces to minimal usability
1066 self.init_user_ns()
1069 self.init_user_ns()
1067
1070
1068 # Restore the default and user aliases
1071 # Restore the default and user aliases
1069 self.alias_manager.clear_aliases()
1072 self.alias_manager.clear_aliases()
1070 self.alias_manager.init_aliases()
1073 self.alias_manager.init_aliases()
1074
1075 # Flush the private list of module references kept for script
1076 # execution protection
1077 self.clear_main_mod_cache()
1071
1078
1072 def reset_selective(self, regex=None):
1079 def reset_selective(self, regex=None):
1073 """Clear selective variables from internal namespaces based on a
1080 """Clear selective variables from internal namespaces based on a
1074 specified regular expression.
1081 specified regular expression.
1075
1082
1076 Parameters
1083 Parameters
1077 ----------
1084 ----------
1078 regex : string or compiled pattern, optional
1085 regex : string or compiled pattern, optional
1079 A regular expression pattern that will be used in searching
1086 A regular expression pattern that will be used in searching
1080 variable names in the users namespaces.
1087 variable names in the users namespaces.
1081 """
1088 """
1082 if regex is not None:
1089 if regex is not None:
1083 try:
1090 try:
1084 m = re.compile(regex)
1091 m = re.compile(regex)
1085 except TypeError:
1092 except TypeError:
1086 raise TypeError('regex must be a string or compiled pattern')
1093 raise TypeError('regex must be a string or compiled pattern')
1087 # Search for keys in each namespace that match the given regex
1094 # Search for keys in each namespace that match the given regex
1088 # If a match is found, delete the key/value pair.
1095 # If a match is found, delete the key/value pair.
1089 for ns in self.ns_refs_table:
1096 for ns in self.ns_refs_table:
1090 for var in ns:
1097 for var in ns:
1091 if m.search(var):
1098 if m.search(var):
1092 del ns[var]
1099 del ns[var]
1093
1100
1094 def push(self, variables, interactive=True):
1101 def push(self, variables, interactive=True):
1095 """Inject a group of variables into the IPython user namespace.
1102 """Inject a group of variables into the IPython user namespace.
1096
1103
1097 Parameters
1104 Parameters
1098 ----------
1105 ----------
1099 variables : dict, str or list/tuple of str
1106 variables : dict, str or list/tuple of str
1100 The variables to inject into the user's namespace. If a dict, a
1107 The variables to inject into the user's namespace. If a dict, a
1101 simple update is done. If a str, the string is assumed to have
1108 simple update is done. If a str, the string is assumed to have
1102 variable names separated by spaces. A list/tuple of str can also
1109 variable names separated by spaces. A list/tuple of str can also
1103 be used to give the variable names. If just the variable names are
1110 be used to give the variable names. If just the variable names are
1104 give (list/tuple/str) then the variable values looked up in the
1111 give (list/tuple/str) then the variable values looked up in the
1105 callers frame.
1112 callers frame.
1106 interactive : bool
1113 interactive : bool
1107 If True (default), the variables will be listed with the ``who``
1114 If True (default), the variables will be listed with the ``who``
1108 magic.
1115 magic.
1109 """
1116 """
1110 vdict = None
1117 vdict = None
1111
1118
1112 # We need a dict of name/value pairs to do namespace updates.
1119 # We need a dict of name/value pairs to do namespace updates.
1113 if isinstance(variables, dict):
1120 if isinstance(variables, dict):
1114 vdict = variables
1121 vdict = variables
1115 elif isinstance(variables, (basestring, list, tuple)):
1122 elif isinstance(variables, (basestring, list, tuple)):
1116 if isinstance(variables, basestring):
1123 if isinstance(variables, basestring):
1117 vlist = variables.split()
1124 vlist = variables.split()
1118 else:
1125 else:
1119 vlist = variables
1126 vlist = variables
1120 vdict = {}
1127 vdict = {}
1121 cf = sys._getframe(1)
1128 cf = sys._getframe(1)
1122 for name in vlist:
1129 for name in vlist:
1123 try:
1130 try:
1124 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1131 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1125 except:
1132 except:
1126 print ('Could not get variable %s from %s' %
1133 print ('Could not get variable %s from %s' %
1127 (name,cf.f_code.co_name))
1134 (name,cf.f_code.co_name))
1128 else:
1135 else:
1129 raise ValueError('variables must be a dict/str/list/tuple')
1136 raise ValueError('variables must be a dict/str/list/tuple')
1130
1137
1131 # Propagate variables to user namespace
1138 # Propagate variables to user namespace
1132 self.user_ns.update(vdict)
1139 self.user_ns.update(vdict)
1133
1140
1134 # And configure interactive visibility
1141 # And configure interactive visibility
1135 config_ns = self.user_ns_hidden
1142 config_ns = self.user_ns_hidden
1136 if interactive:
1143 if interactive:
1137 for name, val in vdict.iteritems():
1144 for name, val in vdict.iteritems():
1138 config_ns.pop(name, None)
1145 config_ns.pop(name, None)
1139 else:
1146 else:
1140 for name,val in vdict.iteritems():
1147 for name,val in vdict.iteritems():
1141 config_ns[name] = val
1148 config_ns[name] = val
1142
1149
1143 #-------------------------------------------------------------------------
1150 #-------------------------------------------------------------------------
1144 # Things related to object introspection
1151 # Things related to object introspection
1145 #-------------------------------------------------------------------------
1152 #-------------------------------------------------------------------------
1146
1153
1147 def _ofind(self, oname, namespaces=None):
1154 def _ofind(self, oname, namespaces=None):
1148 """Find an object in the available namespaces.
1155 """Find an object in the available namespaces.
1149
1156
1150 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1157 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1151
1158
1152 Has special code to detect magic functions.
1159 Has special code to detect magic functions.
1153 """
1160 """
1154 #oname = oname.strip()
1161 #oname = oname.strip()
1155 #print '1- oname: <%r>' % oname # dbg
1162 #print '1- oname: <%r>' % oname # dbg
1156 try:
1163 try:
1157 oname = oname.strip().encode('ascii')
1164 oname = oname.strip().encode('ascii')
1158 #print '2- oname: <%r>' % oname # dbg
1165 #print '2- oname: <%r>' % oname # dbg
1159 except UnicodeEncodeError:
1166 except UnicodeEncodeError:
1160 print 'Python identifiers can only contain ascii characters.'
1167 print 'Python identifiers can only contain ascii characters.'
1161 return dict(found=False)
1168 return dict(found=False)
1162
1169
1163 alias_ns = None
1170 alias_ns = None
1164 if namespaces is None:
1171 if namespaces is None:
1165 # Namespaces to search in:
1172 # Namespaces to search in:
1166 # Put them in a list. The order is important so that we
1173 # Put them in a list. The order is important so that we
1167 # find things in the same order that Python finds them.
1174 # find things in the same order that Python finds them.
1168 namespaces = [ ('Interactive', self.user_ns),
1175 namespaces = [ ('Interactive', self.user_ns),
1169 ('IPython internal', self.internal_ns),
1176 ('IPython internal', self.internal_ns),
1170 ('Python builtin', __builtin__.__dict__),
1177 ('Python builtin', __builtin__.__dict__),
1171 ('Alias', self.alias_manager.alias_table),
1178 ('Alias', self.alias_manager.alias_table),
1172 ]
1179 ]
1173 alias_ns = self.alias_manager.alias_table
1180 alias_ns = self.alias_manager.alias_table
1174
1181
1175 # initialize results to 'null'
1182 # initialize results to 'null'
1176 found = False; obj = None; ospace = None; ds = None;
1183 found = False; obj = None; ospace = None; ds = None;
1177 ismagic = False; isalias = False; parent = None
1184 ismagic = False; isalias = False; parent = None
1178
1185
1179 # We need to special-case 'print', which as of python2.6 registers as a
1186 # We need to special-case 'print', which as of python2.6 registers as a
1180 # function but should only be treated as one if print_function was
1187 # function but should only be treated as one if print_function was
1181 # loaded with a future import. In this case, just bail.
1188 # loaded with a future import. In this case, just bail.
1182 if (oname == 'print' and not (self.compile.compiler_flags &
1189 if (oname == 'print' and not (self.compile.compiler_flags &
1183 __future__.CO_FUTURE_PRINT_FUNCTION)):
1190 __future__.CO_FUTURE_PRINT_FUNCTION)):
1184 return {'found':found, 'obj':obj, 'namespace':ospace,
1191 return {'found':found, 'obj':obj, 'namespace':ospace,
1185 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1192 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1186
1193
1187 # Look for the given name by splitting it in parts. If the head is
1194 # Look for the given name by splitting it in parts. If the head is
1188 # found, then we look for all the remaining parts as members, and only
1195 # found, then we look for all the remaining parts as members, and only
1189 # declare success if we can find them all.
1196 # declare success if we can find them all.
1190 oname_parts = oname.split('.')
1197 oname_parts = oname.split('.')
1191 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1198 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1192 for nsname,ns in namespaces:
1199 for nsname,ns in namespaces:
1193 try:
1200 try:
1194 obj = ns[oname_head]
1201 obj = ns[oname_head]
1195 except KeyError:
1202 except KeyError:
1196 continue
1203 continue
1197 else:
1204 else:
1198 #print 'oname_rest:', oname_rest # dbg
1205 #print 'oname_rest:', oname_rest # dbg
1199 for part in oname_rest:
1206 for part in oname_rest:
1200 try:
1207 try:
1201 parent = obj
1208 parent = obj
1202 obj = getattr(obj,part)
1209 obj = getattr(obj,part)
1203 except:
1210 except:
1204 # Blanket except b/c some badly implemented objects
1211 # Blanket except b/c some badly implemented objects
1205 # allow __getattr__ to raise exceptions other than
1212 # allow __getattr__ to raise exceptions other than
1206 # AttributeError, which then crashes IPython.
1213 # AttributeError, which then crashes IPython.
1207 break
1214 break
1208 else:
1215 else:
1209 # If we finish the for loop (no break), we got all members
1216 # If we finish the for loop (no break), we got all members
1210 found = True
1217 found = True
1211 ospace = nsname
1218 ospace = nsname
1212 if ns == alias_ns:
1219 if ns == alias_ns:
1213 isalias = True
1220 isalias = True
1214 break # namespace loop
1221 break # namespace loop
1215
1222
1216 # Try to see if it's magic
1223 # Try to see if it's magic
1217 if not found:
1224 if not found:
1218 if oname.startswith(ESC_MAGIC):
1225 if oname.startswith(ESC_MAGIC):
1219 oname = oname[1:]
1226 oname = oname[1:]
1220 obj = getattr(self,'magic_'+oname,None)
1227 obj = getattr(self,'magic_'+oname,None)
1221 if obj is not None:
1228 if obj is not None:
1222 found = True
1229 found = True
1223 ospace = 'IPython internal'
1230 ospace = 'IPython internal'
1224 ismagic = True
1231 ismagic = True
1225
1232
1226 # Last try: special-case some literals like '', [], {}, etc:
1233 # Last try: special-case some literals like '', [], {}, etc:
1227 if not found and oname_head in ["''",'""','[]','{}','()']:
1234 if not found and oname_head in ["''",'""','[]','{}','()']:
1228 obj = eval(oname_head)
1235 obj = eval(oname_head)
1229 found = True
1236 found = True
1230 ospace = 'Interactive'
1237 ospace = 'Interactive'
1231
1238
1232 return {'found':found, 'obj':obj, 'namespace':ospace,
1239 return {'found':found, 'obj':obj, 'namespace':ospace,
1233 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1240 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1234
1241
1235 def _ofind_property(self, oname, info):
1242 def _ofind_property(self, oname, info):
1236 """Second part of object finding, to look for property details."""
1243 """Second part of object finding, to look for property details."""
1237 if info.found:
1244 if info.found:
1238 # Get the docstring of the class property if it exists.
1245 # Get the docstring of the class property if it exists.
1239 path = oname.split('.')
1246 path = oname.split('.')
1240 root = '.'.join(path[:-1])
1247 root = '.'.join(path[:-1])
1241 if info.parent is not None:
1248 if info.parent is not None:
1242 try:
1249 try:
1243 target = getattr(info.parent, '__class__')
1250 target = getattr(info.parent, '__class__')
1244 # The object belongs to a class instance.
1251 # The object belongs to a class instance.
1245 try:
1252 try:
1246 target = getattr(target, path[-1])
1253 target = getattr(target, path[-1])
1247 # The class defines the object.
1254 # The class defines the object.
1248 if isinstance(target, property):
1255 if isinstance(target, property):
1249 oname = root + '.__class__.' + path[-1]
1256 oname = root + '.__class__.' + path[-1]
1250 info = Struct(self._ofind(oname))
1257 info = Struct(self._ofind(oname))
1251 except AttributeError: pass
1258 except AttributeError: pass
1252 except AttributeError: pass
1259 except AttributeError: pass
1253
1260
1254 # We return either the new info or the unmodified input if the object
1261 # We return either the new info or the unmodified input if the object
1255 # hadn't been found
1262 # hadn't been found
1256 return info
1263 return info
1257
1264
1258 def _object_find(self, oname, namespaces=None):
1265 def _object_find(self, oname, namespaces=None):
1259 """Find an object and return a struct with info about it."""
1266 """Find an object and return a struct with info about it."""
1260 inf = Struct(self._ofind(oname, namespaces))
1267 inf = Struct(self._ofind(oname, namespaces))
1261 return Struct(self._ofind_property(oname, inf))
1268 return Struct(self._ofind_property(oname, inf))
1262
1269
1263 def _inspect(self, meth, oname, namespaces=None, **kw):
1270 def _inspect(self, meth, oname, namespaces=None, **kw):
1264 """Generic interface to the inspector system.
1271 """Generic interface to the inspector system.
1265
1272
1266 This function is meant to be called by pdef, pdoc & friends."""
1273 This function is meant to be called by pdef, pdoc & friends."""
1267 info = self._object_find(oname)
1274 info = self._object_find(oname)
1268 if info.found:
1275 if info.found:
1269 pmethod = getattr(self.inspector, meth)
1276 pmethod = getattr(self.inspector, meth)
1270 formatter = format_screen if info.ismagic else None
1277 formatter = format_screen if info.ismagic else None
1271 if meth == 'pdoc':
1278 if meth == 'pdoc':
1272 pmethod(info.obj, oname, formatter)
1279 pmethod(info.obj, oname, formatter)
1273 elif meth == 'pinfo':
1280 elif meth == 'pinfo':
1274 pmethod(info.obj, oname, formatter, info, **kw)
1281 pmethod(info.obj, oname, formatter, info, **kw)
1275 else:
1282 else:
1276 pmethod(info.obj, oname)
1283 pmethod(info.obj, oname)
1277 else:
1284 else:
1278 print 'Object `%s` not found.' % oname
1285 print 'Object `%s` not found.' % oname
1279 return 'not found' # so callers can take other action
1286 return 'not found' # so callers can take other action
1280
1287
1281 def object_inspect(self, oname):
1288 def object_inspect(self, oname):
1282 info = self._object_find(oname)
1289 info = self._object_find(oname)
1283 if info.found:
1290 if info.found:
1284 return self.inspector.info(info.obj, oname, info=info)
1291 return self.inspector.info(info.obj, oname, info=info)
1285 else:
1292 else:
1286 return oinspect.object_info(name=oname, found=False)
1293 return oinspect.object_info(name=oname, found=False)
1287
1294
1288 #-------------------------------------------------------------------------
1295 #-------------------------------------------------------------------------
1289 # Things related to history management
1296 # Things related to history management
1290 #-------------------------------------------------------------------------
1297 #-------------------------------------------------------------------------
1291
1298
1292 def init_history(self):
1299 def init_history(self):
1293 """Sets up the command history, and starts regular autosaves."""
1300 """Sets up the command history, and starts regular autosaves."""
1294 self.history_manager = HistoryManager(shell=self, config=self.config)
1301 self.history_manager = HistoryManager(shell=self, config=self.config)
1295
1302
1296 #-------------------------------------------------------------------------
1303 #-------------------------------------------------------------------------
1297 # Things related to exception handling and tracebacks (not debugging)
1304 # Things related to exception handling and tracebacks (not debugging)
1298 #-------------------------------------------------------------------------
1305 #-------------------------------------------------------------------------
1299
1306
1300 def init_traceback_handlers(self, custom_exceptions):
1307 def init_traceback_handlers(self, custom_exceptions):
1301 # Syntax error handler.
1308 # Syntax error handler.
1302 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1309 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1303
1310
1304 # The interactive one is initialized with an offset, meaning we always
1311 # The interactive one is initialized with an offset, meaning we always
1305 # want to remove the topmost item in the traceback, which is our own
1312 # want to remove the topmost item in the traceback, which is our own
1306 # internal code. Valid modes: ['Plain','Context','Verbose']
1313 # internal code. Valid modes: ['Plain','Context','Verbose']
1307 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1314 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1308 color_scheme='NoColor',
1315 color_scheme='NoColor',
1309 tb_offset = 1,
1316 tb_offset = 1,
1310 check_cache=self.compile.check_cache)
1317 check_cache=self.compile.check_cache)
1311
1318
1312 # The instance will store a pointer to the system-wide exception hook,
1319 # The instance will store a pointer to the system-wide exception hook,
1313 # so that runtime code (such as magics) can access it. This is because
1320 # so that runtime code (such as magics) can access it. This is because
1314 # during the read-eval loop, it may get temporarily overwritten.
1321 # during the read-eval loop, it may get temporarily overwritten.
1315 self.sys_excepthook = sys.excepthook
1322 self.sys_excepthook = sys.excepthook
1316
1323
1317 # and add any custom exception handlers the user may have specified
1324 # and add any custom exception handlers the user may have specified
1318 self.set_custom_exc(*custom_exceptions)
1325 self.set_custom_exc(*custom_exceptions)
1319
1326
1320 # Set the exception mode
1327 # Set the exception mode
1321 self.InteractiveTB.set_mode(mode=self.xmode)
1328 self.InteractiveTB.set_mode(mode=self.xmode)
1322
1329
1323 def set_custom_exc(self, exc_tuple, handler):
1330 def set_custom_exc(self, exc_tuple, handler):
1324 """set_custom_exc(exc_tuple,handler)
1331 """set_custom_exc(exc_tuple,handler)
1325
1332
1326 Set a custom exception handler, which will be called if any of the
1333 Set a custom exception handler, which will be called if any of the
1327 exceptions in exc_tuple occur in the mainloop (specifically, in the
1334 exceptions in exc_tuple occur in the mainloop (specifically, in the
1328 run_code() method.
1335 run_code() method.
1329
1336
1330 Inputs:
1337 Inputs:
1331
1338
1332 - exc_tuple: a *tuple* of valid exceptions to call the defined
1339 - exc_tuple: a *tuple* of valid exceptions to call the defined
1333 handler for. It is very important that you use a tuple, and NOT A
1340 handler for. It is very important that you use a tuple, and NOT A
1334 LIST here, because of the way Python's except statement works. If
1341 LIST here, because of the way Python's except statement works. If
1335 you only want to trap a single exception, use a singleton tuple:
1342 you only want to trap a single exception, use a singleton tuple:
1336
1343
1337 exc_tuple == (MyCustomException,)
1344 exc_tuple == (MyCustomException,)
1338
1345
1339 - handler: this must be defined as a function with the following
1346 - handler: this must be defined as a function with the following
1340 basic interface::
1347 basic interface::
1341
1348
1342 def my_handler(self, etype, value, tb, tb_offset=None)
1349 def my_handler(self, etype, value, tb, tb_offset=None)
1343 ...
1350 ...
1344 # The return value must be
1351 # The return value must be
1345 return structured_traceback
1352 return structured_traceback
1346
1353
1347 This will be made into an instance method (via types.MethodType)
1354 This will be made into an instance method (via types.MethodType)
1348 of IPython itself, and it will be called if any of the exceptions
1355 of IPython itself, and it will be called if any of the exceptions
1349 listed in the exc_tuple are caught. If the handler is None, an
1356 listed in the exc_tuple are caught. If the handler is None, an
1350 internal basic one is used, which just prints basic info.
1357 internal basic one is used, which just prints basic info.
1351
1358
1352 WARNING: by putting in your own exception handler into IPython's main
1359 WARNING: by putting in your own exception handler into IPython's main
1353 execution loop, you run a very good chance of nasty crashes. This
1360 execution loop, you run a very good chance of nasty crashes. This
1354 facility should only be used if you really know what you are doing."""
1361 facility should only be used if you really know what you are doing."""
1355
1362
1356 assert type(exc_tuple)==type(()) , \
1363 assert type(exc_tuple)==type(()) , \
1357 "The custom exceptions must be given AS A TUPLE."
1364 "The custom exceptions must be given AS A TUPLE."
1358
1365
1359 def dummy_handler(self,etype,value,tb):
1366 def dummy_handler(self,etype,value,tb):
1360 print '*** Simple custom exception handler ***'
1367 print '*** Simple custom exception handler ***'
1361 print 'Exception type :',etype
1368 print 'Exception type :',etype
1362 print 'Exception value:',value
1369 print 'Exception value:',value
1363 print 'Traceback :',tb
1370 print 'Traceback :',tb
1364 print 'Source code :','\n'.join(self.buffer)
1371 print 'Source code :','\n'.join(self.buffer)
1365
1372
1366 if handler is None: handler = dummy_handler
1373 if handler is None: handler = dummy_handler
1367
1374
1368 self.CustomTB = types.MethodType(handler,self)
1375 self.CustomTB = types.MethodType(handler,self)
1369 self.custom_exceptions = exc_tuple
1376 self.custom_exceptions = exc_tuple
1370
1377
1371 def excepthook(self, etype, value, tb):
1378 def excepthook(self, etype, value, tb):
1372 """One more defense for GUI apps that call sys.excepthook.
1379 """One more defense for GUI apps that call sys.excepthook.
1373
1380
1374 GUI frameworks like wxPython trap exceptions and call
1381 GUI frameworks like wxPython trap exceptions and call
1375 sys.excepthook themselves. I guess this is a feature that
1382 sys.excepthook themselves. I guess this is a feature that
1376 enables them to keep running after exceptions that would
1383 enables them to keep running after exceptions that would
1377 otherwise kill their mainloop. This is a bother for IPython
1384 otherwise kill their mainloop. This is a bother for IPython
1378 which excepts to catch all of the program exceptions with a try:
1385 which excepts to catch all of the program exceptions with a try:
1379 except: statement.
1386 except: statement.
1380
1387
1381 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1388 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1382 any app directly invokes sys.excepthook, it will look to the user like
1389 any app directly invokes sys.excepthook, it will look to the user like
1383 IPython crashed. In order to work around this, we can disable the
1390 IPython crashed. In order to work around this, we can disable the
1384 CrashHandler and replace it with this excepthook instead, which prints a
1391 CrashHandler and replace it with this excepthook instead, which prints a
1385 regular traceback using our InteractiveTB. In this fashion, apps which
1392 regular traceback using our InteractiveTB. In this fashion, apps which
1386 call sys.excepthook will generate a regular-looking exception from
1393 call sys.excepthook will generate a regular-looking exception from
1387 IPython, and the CrashHandler will only be triggered by real IPython
1394 IPython, and the CrashHandler will only be triggered by real IPython
1388 crashes.
1395 crashes.
1389
1396
1390 This hook should be used sparingly, only in places which are not likely
1397 This hook should be used sparingly, only in places which are not likely
1391 to be true IPython errors.
1398 to be true IPython errors.
1392 """
1399 """
1393 self.showtraceback((etype,value,tb),tb_offset=0)
1400 self.showtraceback((etype,value,tb),tb_offset=0)
1394
1401
1395 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1402 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1396 exception_only=False):
1403 exception_only=False):
1397 """Display the exception that just occurred.
1404 """Display the exception that just occurred.
1398
1405
1399 If nothing is known about the exception, this is the method which
1406 If nothing is known about the exception, this is the method which
1400 should be used throughout the code for presenting user tracebacks,
1407 should be used throughout the code for presenting user tracebacks,
1401 rather than directly invoking the InteractiveTB object.
1408 rather than directly invoking the InteractiveTB object.
1402
1409
1403 A specific showsyntaxerror() also exists, but this method can take
1410 A specific showsyntaxerror() also exists, but this method can take
1404 care of calling it if needed, so unless you are explicitly catching a
1411 care of calling it if needed, so unless you are explicitly catching a
1405 SyntaxError exception, don't try to analyze the stack manually and
1412 SyntaxError exception, don't try to analyze the stack manually and
1406 simply call this method."""
1413 simply call this method."""
1407
1414
1408 try:
1415 try:
1409 if exc_tuple is None:
1416 if exc_tuple is None:
1410 etype, value, tb = sys.exc_info()
1417 etype, value, tb = sys.exc_info()
1411 else:
1418 else:
1412 etype, value, tb = exc_tuple
1419 etype, value, tb = exc_tuple
1413
1420
1414 if etype is None:
1421 if etype is None:
1415 if hasattr(sys, 'last_type'):
1422 if hasattr(sys, 'last_type'):
1416 etype, value, tb = sys.last_type, sys.last_value, \
1423 etype, value, tb = sys.last_type, sys.last_value, \
1417 sys.last_traceback
1424 sys.last_traceback
1418 else:
1425 else:
1419 self.write_err('No traceback available to show.\n')
1426 self.write_err('No traceback available to show.\n')
1420 return
1427 return
1421
1428
1422 if etype is SyntaxError:
1429 if etype is SyntaxError:
1423 # Though this won't be called by syntax errors in the input
1430 # Though this won't be called by syntax errors in the input
1424 # line, there may be SyntaxError cases whith imported code.
1431 # line, there may be SyntaxError cases whith imported code.
1425 self.showsyntaxerror(filename)
1432 self.showsyntaxerror(filename)
1426 elif etype is UsageError:
1433 elif etype is UsageError:
1427 print "UsageError:", value
1434 print "UsageError:", value
1428 else:
1435 else:
1429 # WARNING: these variables are somewhat deprecated and not
1436 # WARNING: these variables are somewhat deprecated and not
1430 # necessarily safe to use in a threaded environment, but tools
1437 # necessarily safe to use in a threaded environment, but tools
1431 # like pdb depend on their existence, so let's set them. If we
1438 # like pdb depend on their existence, so let's set them. If we
1432 # find problems in the field, we'll need to revisit their use.
1439 # find problems in the field, we'll need to revisit their use.
1433 sys.last_type = etype
1440 sys.last_type = etype
1434 sys.last_value = value
1441 sys.last_value = value
1435 sys.last_traceback = tb
1442 sys.last_traceback = tb
1436
1443
1437 if etype in self.custom_exceptions:
1444 if etype in self.custom_exceptions:
1438 # FIXME: Old custom traceback objects may just return a
1445 # FIXME: Old custom traceback objects may just return a
1439 # string, in that case we just put it into a list
1446 # string, in that case we just put it into a list
1440 stb = self.CustomTB(etype, value, tb, tb_offset)
1447 stb = self.CustomTB(etype, value, tb, tb_offset)
1441 if isinstance(ctb, basestring):
1448 if isinstance(ctb, basestring):
1442 stb = [stb]
1449 stb = [stb]
1443 else:
1450 else:
1444 if exception_only:
1451 if exception_only:
1445 stb = ['An exception has occurred, use %tb to see '
1452 stb = ['An exception has occurred, use %tb to see '
1446 'the full traceback.\n']
1453 'the full traceback.\n']
1447 stb.extend(self.InteractiveTB.get_exception_only(etype,
1454 stb.extend(self.InteractiveTB.get_exception_only(etype,
1448 value))
1455 value))
1449 else:
1456 else:
1450 stb = self.InteractiveTB.structured_traceback(etype,
1457 stb = self.InteractiveTB.structured_traceback(etype,
1451 value, tb, tb_offset=tb_offset)
1458 value, tb, tb_offset=tb_offset)
1452 # FIXME: the pdb calling should be done by us, not by
1459 # FIXME: the pdb calling should be done by us, not by
1453 # the code computing the traceback.
1460 # the code computing the traceback.
1454 if self.InteractiveTB.call_pdb:
1461 if self.InteractiveTB.call_pdb:
1455 # pdb mucks up readline, fix it back
1462 # pdb mucks up readline, fix it back
1456 self.set_readline_completer()
1463 self.set_readline_completer()
1457
1464
1458 # Actually show the traceback
1465 # Actually show the traceback
1459 self._showtraceback(etype, value, stb)
1466 self._showtraceback(etype, value, stb)
1460
1467
1461 except KeyboardInterrupt:
1468 except KeyboardInterrupt:
1462 self.write_err("\nKeyboardInterrupt\n")
1469 self.write_err("\nKeyboardInterrupt\n")
1463
1470
1464 def _showtraceback(self, etype, evalue, stb):
1471 def _showtraceback(self, etype, evalue, stb):
1465 """Actually show a traceback.
1472 """Actually show a traceback.
1466
1473
1467 Subclasses may override this method to put the traceback on a different
1474 Subclasses may override this method to put the traceback on a different
1468 place, like a side channel.
1475 place, like a side channel.
1469 """
1476 """
1470 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1477 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1471
1478
1472 def showsyntaxerror(self, filename=None):
1479 def showsyntaxerror(self, filename=None):
1473 """Display the syntax error that just occurred.
1480 """Display the syntax error that just occurred.
1474
1481
1475 This doesn't display a stack trace because there isn't one.
1482 This doesn't display a stack trace because there isn't one.
1476
1483
1477 If a filename is given, it is stuffed in the exception instead
1484 If a filename is given, it is stuffed in the exception instead
1478 of what was there before (because Python's parser always uses
1485 of what was there before (because Python's parser always uses
1479 "<string>" when reading from a string).
1486 "<string>" when reading from a string).
1480 """
1487 """
1481 etype, value, last_traceback = sys.exc_info()
1488 etype, value, last_traceback = sys.exc_info()
1482
1489
1483 # See note about these variables in showtraceback() above
1490 # See note about these variables in showtraceback() above
1484 sys.last_type = etype
1491 sys.last_type = etype
1485 sys.last_value = value
1492 sys.last_value = value
1486 sys.last_traceback = last_traceback
1493 sys.last_traceback = last_traceback
1487
1494
1488 if filename and etype is SyntaxError:
1495 if filename and etype is SyntaxError:
1489 # Work hard to stuff the correct filename in the exception
1496 # Work hard to stuff the correct filename in the exception
1490 try:
1497 try:
1491 msg, (dummy_filename, lineno, offset, line) = value
1498 msg, (dummy_filename, lineno, offset, line) = value
1492 except:
1499 except:
1493 # Not the format we expect; leave it alone
1500 # Not the format we expect; leave it alone
1494 pass
1501 pass
1495 else:
1502 else:
1496 # Stuff in the right filename
1503 # Stuff in the right filename
1497 try:
1504 try:
1498 # Assume SyntaxError is a class exception
1505 # Assume SyntaxError is a class exception
1499 value = SyntaxError(msg, (filename, lineno, offset, line))
1506 value = SyntaxError(msg, (filename, lineno, offset, line))
1500 except:
1507 except:
1501 # If that failed, assume SyntaxError is a string
1508 # If that failed, assume SyntaxError is a string
1502 value = msg, (filename, lineno, offset, line)
1509 value = msg, (filename, lineno, offset, line)
1503 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1510 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1504 self._showtraceback(etype, value, stb)
1511 self._showtraceback(etype, value, stb)
1505
1512
1506 #-------------------------------------------------------------------------
1513 #-------------------------------------------------------------------------
1507 # Things related to readline
1514 # Things related to readline
1508 #-------------------------------------------------------------------------
1515 #-------------------------------------------------------------------------
1509
1516
1510 def init_readline(self):
1517 def init_readline(self):
1511 """Command history completion/saving/reloading."""
1518 """Command history completion/saving/reloading."""
1512
1519
1513 if self.readline_use:
1520 if self.readline_use:
1514 import IPython.utils.rlineimpl as readline
1521 import IPython.utils.rlineimpl as readline
1515
1522
1516 self.rl_next_input = None
1523 self.rl_next_input = None
1517 self.rl_do_indent = False
1524 self.rl_do_indent = False
1518
1525
1519 if not self.readline_use or not readline.have_readline:
1526 if not self.readline_use or not readline.have_readline:
1520 self.has_readline = False
1527 self.has_readline = False
1521 self.readline = None
1528 self.readline = None
1522 # Set a number of methods that depend on readline to be no-op
1529 # Set a number of methods that depend on readline to be no-op
1523 self.set_readline_completer = no_op
1530 self.set_readline_completer = no_op
1524 self.set_custom_completer = no_op
1531 self.set_custom_completer = no_op
1525 self.set_completer_frame = no_op
1532 self.set_completer_frame = no_op
1526 warn('Readline services not available or not loaded.')
1533 warn('Readline services not available or not loaded.')
1527 else:
1534 else:
1528 self.has_readline = True
1535 self.has_readline = True
1529 self.readline = readline
1536 self.readline = readline
1530 sys.modules['readline'] = readline
1537 sys.modules['readline'] = readline
1531
1538
1532 # Platform-specific configuration
1539 # Platform-specific configuration
1533 if os.name == 'nt':
1540 if os.name == 'nt':
1534 # FIXME - check with Frederick to see if we can harmonize
1541 # FIXME - check with Frederick to see if we can harmonize
1535 # naming conventions with pyreadline to avoid this
1542 # naming conventions with pyreadline to avoid this
1536 # platform-dependent check
1543 # platform-dependent check
1537 self.readline_startup_hook = readline.set_pre_input_hook
1544 self.readline_startup_hook = readline.set_pre_input_hook
1538 else:
1545 else:
1539 self.readline_startup_hook = readline.set_startup_hook
1546 self.readline_startup_hook = readline.set_startup_hook
1540
1547
1541 # Load user's initrc file (readline config)
1548 # Load user's initrc file (readline config)
1542 # Or if libedit is used, load editrc.
1549 # Or if libedit is used, load editrc.
1543 inputrc_name = os.environ.get('INPUTRC')
1550 inputrc_name = os.environ.get('INPUTRC')
1544 if inputrc_name is None:
1551 if inputrc_name is None:
1545 home_dir = get_home_dir()
1552 home_dir = get_home_dir()
1546 if home_dir is not None:
1553 if home_dir is not None:
1547 inputrc_name = '.inputrc'
1554 inputrc_name = '.inputrc'
1548 if readline.uses_libedit:
1555 if readline.uses_libedit:
1549 inputrc_name = '.editrc'
1556 inputrc_name = '.editrc'
1550 inputrc_name = os.path.join(home_dir, inputrc_name)
1557 inputrc_name = os.path.join(home_dir, inputrc_name)
1551 if os.path.isfile(inputrc_name):
1558 if os.path.isfile(inputrc_name):
1552 try:
1559 try:
1553 readline.read_init_file(inputrc_name)
1560 readline.read_init_file(inputrc_name)
1554 except:
1561 except:
1555 warn('Problems reading readline initialization file <%s>'
1562 warn('Problems reading readline initialization file <%s>'
1556 % inputrc_name)
1563 % inputrc_name)
1557
1564
1558 # Configure readline according to user's prefs
1565 # Configure readline according to user's prefs
1559 # This is only done if GNU readline is being used. If libedit
1566 # This is only done if GNU readline is being used. If libedit
1560 # is being used (as on Leopard) the readline config is
1567 # is being used (as on Leopard) the readline config is
1561 # not run as the syntax for libedit is different.
1568 # not run as the syntax for libedit is different.
1562 if not readline.uses_libedit:
1569 if not readline.uses_libedit:
1563 for rlcommand in self.readline_parse_and_bind:
1570 for rlcommand in self.readline_parse_and_bind:
1564 #print "loading rl:",rlcommand # dbg
1571 #print "loading rl:",rlcommand # dbg
1565 readline.parse_and_bind(rlcommand)
1572 readline.parse_and_bind(rlcommand)
1566
1573
1567 # Remove some chars from the delimiters list. If we encounter
1574 # Remove some chars from the delimiters list. If we encounter
1568 # unicode chars, discard them.
1575 # unicode chars, discard them.
1569 delims = readline.get_completer_delims().encode("ascii", "ignore")
1576 delims = readline.get_completer_delims().encode("ascii", "ignore")
1570 delims = delims.translate(None, self.readline_remove_delims)
1577 delims = delims.translate(None, self.readline_remove_delims)
1571 delims = delims.replace(ESC_MAGIC, '')
1578 delims = delims.replace(ESC_MAGIC, '')
1572 readline.set_completer_delims(delims)
1579 readline.set_completer_delims(delims)
1573 # otherwise we end up with a monster history after a while:
1580 # otherwise we end up with a monster history after a while:
1574 readline.set_history_length(self.history_length)
1581 readline.set_history_length(self.history_length)
1575
1582
1576 self.refill_readline_hist()
1583 self.refill_readline_hist()
1577 self.readline_no_record = ReadlineNoRecord(self)
1584 self.readline_no_record = ReadlineNoRecord(self)
1578
1585
1579 # Configure auto-indent for all platforms
1586 # Configure auto-indent for all platforms
1580 self.set_autoindent(self.autoindent)
1587 self.set_autoindent(self.autoindent)
1581
1588
1582 def refill_readline_hist(self):
1589 def refill_readline_hist(self):
1583 # Load the last 1000 lines from history
1590 # Load the last 1000 lines from history
1584 self.readline.clear_history()
1591 self.readline.clear_history()
1585 stdin_encoding = sys.stdin.encoding or "utf-8"
1592 stdin_encoding = sys.stdin.encoding or "utf-8"
1586 for _, _, cell in self.history_manager.get_tail(1000,
1593 for _, _, cell in self.history_manager.get_tail(1000,
1587 include_latest=True):
1594 include_latest=True):
1588 if cell.strip(): # Ignore blank lines
1595 if cell.strip(): # Ignore blank lines
1589 for line in cell.splitlines():
1596 for line in cell.splitlines():
1590 self.readline.add_history(line.encode(stdin_encoding))
1597 self.readline.add_history(line.encode(stdin_encoding))
1591
1598
1592 def set_next_input(self, s):
1599 def set_next_input(self, s):
1593 """ Sets the 'default' input string for the next command line.
1600 """ Sets the 'default' input string for the next command line.
1594
1601
1595 Requires readline.
1602 Requires readline.
1596
1603
1597 Example:
1604 Example:
1598
1605
1599 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1606 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1600 [D:\ipython]|2> Hello Word_ # cursor is here
1607 [D:\ipython]|2> Hello Word_ # cursor is here
1601 """
1608 """
1602
1609
1603 self.rl_next_input = s
1610 self.rl_next_input = s
1604
1611
1605 # Maybe move this to the terminal subclass?
1612 # Maybe move this to the terminal subclass?
1606 def pre_readline(self):
1613 def pre_readline(self):
1607 """readline hook to be used at the start of each line.
1614 """readline hook to be used at the start of each line.
1608
1615
1609 Currently it handles auto-indent only."""
1616 Currently it handles auto-indent only."""
1610
1617
1611 if self.rl_do_indent:
1618 if self.rl_do_indent:
1612 self.readline.insert_text(self._indent_current_str())
1619 self.readline.insert_text(self._indent_current_str())
1613 if self.rl_next_input is not None:
1620 if self.rl_next_input is not None:
1614 self.readline.insert_text(self.rl_next_input)
1621 self.readline.insert_text(self.rl_next_input)
1615 self.rl_next_input = None
1622 self.rl_next_input = None
1616
1623
1617 def _indent_current_str(self):
1624 def _indent_current_str(self):
1618 """return the current level of indentation as a string"""
1625 """return the current level of indentation as a string"""
1619 return self.input_splitter.indent_spaces * ' '
1626 return self.input_splitter.indent_spaces * ' '
1620
1627
1621 #-------------------------------------------------------------------------
1628 #-------------------------------------------------------------------------
1622 # Things related to text completion
1629 # Things related to text completion
1623 #-------------------------------------------------------------------------
1630 #-------------------------------------------------------------------------
1624
1631
1625 def init_completer(self):
1632 def init_completer(self):
1626 """Initialize the completion machinery.
1633 """Initialize the completion machinery.
1627
1634
1628 This creates completion machinery that can be used by client code,
1635 This creates completion machinery that can be used by client code,
1629 either interactively in-process (typically triggered by the readline
1636 either interactively in-process (typically triggered by the readline
1630 library), programatically (such as in test suites) or out-of-prcess
1637 library), programatically (such as in test suites) or out-of-prcess
1631 (typically over the network by remote frontends).
1638 (typically over the network by remote frontends).
1632 """
1639 """
1633 from IPython.core.completer import IPCompleter
1640 from IPython.core.completer import IPCompleter
1634 from IPython.core.completerlib import (module_completer,
1641 from IPython.core.completerlib import (module_completer,
1635 magic_run_completer, cd_completer)
1642 magic_run_completer, cd_completer)
1636
1643
1637 self.Completer = IPCompleter(self,
1644 self.Completer = IPCompleter(self,
1638 self.user_ns,
1645 self.user_ns,
1639 self.user_global_ns,
1646 self.user_global_ns,
1640 self.readline_omit__names,
1647 self.readline_omit__names,
1641 self.alias_manager.alias_table,
1648 self.alias_manager.alias_table,
1642 self.has_readline)
1649 self.has_readline)
1643
1650
1644 # Add custom completers to the basic ones built into IPCompleter
1651 # Add custom completers to the basic ones built into IPCompleter
1645 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1652 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1646 self.strdispatchers['complete_command'] = sdisp
1653 self.strdispatchers['complete_command'] = sdisp
1647 self.Completer.custom_completers = sdisp
1654 self.Completer.custom_completers = sdisp
1648
1655
1649 self.set_hook('complete_command', module_completer, str_key = 'import')
1656 self.set_hook('complete_command', module_completer, str_key = 'import')
1650 self.set_hook('complete_command', module_completer, str_key = 'from')
1657 self.set_hook('complete_command', module_completer, str_key = 'from')
1651 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1658 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1652 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1659 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1653
1660
1654 # Only configure readline if we truly are using readline. IPython can
1661 # Only configure readline if we truly are using readline. IPython can
1655 # do tab-completion over the network, in GUIs, etc, where readline
1662 # do tab-completion over the network, in GUIs, etc, where readline
1656 # itself may be absent
1663 # itself may be absent
1657 if self.has_readline:
1664 if self.has_readline:
1658 self.set_readline_completer()
1665 self.set_readline_completer()
1659
1666
1660 def complete(self, text, line=None, cursor_pos=None):
1667 def complete(self, text, line=None, cursor_pos=None):
1661 """Return the completed text and a list of completions.
1668 """Return the completed text and a list of completions.
1662
1669
1663 Parameters
1670 Parameters
1664 ----------
1671 ----------
1665
1672
1666 text : string
1673 text : string
1667 A string of text to be completed on. It can be given as empty and
1674 A string of text to be completed on. It can be given as empty and
1668 instead a line/position pair are given. In this case, the
1675 instead a line/position pair are given. In this case, the
1669 completer itself will split the line like readline does.
1676 completer itself will split the line like readline does.
1670
1677
1671 line : string, optional
1678 line : string, optional
1672 The complete line that text is part of.
1679 The complete line that text is part of.
1673
1680
1674 cursor_pos : int, optional
1681 cursor_pos : int, optional
1675 The position of the cursor on the input line.
1682 The position of the cursor on the input line.
1676
1683
1677 Returns
1684 Returns
1678 -------
1685 -------
1679 text : string
1686 text : string
1680 The actual text that was completed.
1687 The actual text that was completed.
1681
1688
1682 matches : list
1689 matches : list
1683 A sorted list with all possible completions.
1690 A sorted list with all possible completions.
1684
1691
1685 The optional arguments allow the completion to take more context into
1692 The optional arguments allow the completion to take more context into
1686 account, and are part of the low-level completion API.
1693 account, and are part of the low-level completion API.
1687
1694
1688 This is a wrapper around the completion mechanism, similar to what
1695 This is a wrapper around the completion mechanism, similar to what
1689 readline does at the command line when the TAB key is hit. By
1696 readline does at the command line when the TAB key is hit. By
1690 exposing it as a method, it can be used by other non-readline
1697 exposing it as a method, it can be used by other non-readline
1691 environments (such as GUIs) for text completion.
1698 environments (such as GUIs) for text completion.
1692
1699
1693 Simple usage example:
1700 Simple usage example:
1694
1701
1695 In [1]: x = 'hello'
1702 In [1]: x = 'hello'
1696
1703
1697 In [2]: _ip.complete('x.l')
1704 In [2]: _ip.complete('x.l')
1698 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1705 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1699 """
1706 """
1700
1707
1701 # Inject names into __builtin__ so we can complete on the added names.
1708 # Inject names into __builtin__ so we can complete on the added names.
1702 with self.builtin_trap:
1709 with self.builtin_trap:
1703 return self.Completer.complete(text, line, cursor_pos)
1710 return self.Completer.complete(text, line, cursor_pos)
1704
1711
1705 def set_custom_completer(self, completer, pos=0):
1712 def set_custom_completer(self, completer, pos=0):
1706 """Adds a new custom completer function.
1713 """Adds a new custom completer function.
1707
1714
1708 The position argument (defaults to 0) is the index in the completers
1715 The position argument (defaults to 0) is the index in the completers
1709 list where you want the completer to be inserted."""
1716 list where you want the completer to be inserted."""
1710
1717
1711 newcomp = types.MethodType(completer,self.Completer)
1718 newcomp = types.MethodType(completer,self.Completer)
1712 self.Completer.matchers.insert(pos,newcomp)
1719 self.Completer.matchers.insert(pos,newcomp)
1713
1720
1714 def set_readline_completer(self):
1721 def set_readline_completer(self):
1715 """Reset readline's completer to be our own."""
1722 """Reset readline's completer to be our own."""
1716 self.readline.set_completer(self.Completer.rlcomplete)
1723 self.readline.set_completer(self.Completer.rlcomplete)
1717
1724
1718 def set_completer_frame(self, frame=None):
1725 def set_completer_frame(self, frame=None):
1719 """Set the frame of the completer."""
1726 """Set the frame of the completer."""
1720 if frame:
1727 if frame:
1721 self.Completer.namespace = frame.f_locals
1728 self.Completer.namespace = frame.f_locals
1722 self.Completer.global_namespace = frame.f_globals
1729 self.Completer.global_namespace = frame.f_globals
1723 else:
1730 else:
1724 self.Completer.namespace = self.user_ns
1731 self.Completer.namespace = self.user_ns
1725 self.Completer.global_namespace = self.user_global_ns
1732 self.Completer.global_namespace = self.user_global_ns
1726
1733
1727 #-------------------------------------------------------------------------
1734 #-------------------------------------------------------------------------
1728 # Things related to magics
1735 # Things related to magics
1729 #-------------------------------------------------------------------------
1736 #-------------------------------------------------------------------------
1730
1737
1731 def init_magics(self):
1738 def init_magics(self):
1732 # FIXME: Move the color initialization to the DisplayHook, which
1739 # FIXME: Move the color initialization to the DisplayHook, which
1733 # should be split into a prompt manager and displayhook. We probably
1740 # should be split into a prompt manager and displayhook. We probably
1734 # even need a centralize colors management object.
1741 # even need a centralize colors management object.
1735 self.magic_colors(self.colors)
1742 self.magic_colors(self.colors)
1736 # History was moved to a separate module
1743 # History was moved to a separate module
1737 from . import history
1744 from . import history
1738 history.init_ipython(self)
1745 history.init_ipython(self)
1739
1746
1740 def magic(self,arg_s):
1747 def magic(self,arg_s):
1741 """Call a magic function by name.
1748 """Call a magic function by name.
1742
1749
1743 Input: a string containing the name of the magic function to call and
1750 Input: a string containing the name of the magic function to call and
1744 any additional arguments to be passed to the magic.
1751 any additional arguments to be passed to the magic.
1745
1752
1746 magic('name -opt foo bar') is equivalent to typing at the ipython
1753 magic('name -opt foo bar') is equivalent to typing at the ipython
1747 prompt:
1754 prompt:
1748
1755
1749 In[1]: %name -opt foo bar
1756 In[1]: %name -opt foo bar
1750
1757
1751 To call a magic without arguments, simply use magic('name').
1758 To call a magic without arguments, simply use magic('name').
1752
1759
1753 This provides a proper Python function to call IPython's magics in any
1760 This provides a proper Python function to call IPython's magics in any
1754 valid Python code you can type at the interpreter, including loops and
1761 valid Python code you can type at the interpreter, including loops and
1755 compound statements.
1762 compound statements.
1756 """
1763 """
1757 args = arg_s.split(' ',1)
1764 args = arg_s.split(' ',1)
1758 magic_name = args[0]
1765 magic_name = args[0]
1759 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1766 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1760
1767
1761 try:
1768 try:
1762 magic_args = args[1]
1769 magic_args = args[1]
1763 except IndexError:
1770 except IndexError:
1764 magic_args = ''
1771 magic_args = ''
1765 fn = getattr(self,'magic_'+magic_name,None)
1772 fn = getattr(self,'magic_'+magic_name,None)
1766 if fn is None:
1773 if fn is None:
1767 error("Magic function `%s` not found." % magic_name)
1774 error("Magic function `%s` not found." % magic_name)
1768 else:
1775 else:
1769 magic_args = self.var_expand(magic_args,1)
1776 magic_args = self.var_expand(magic_args,1)
1770 # Grab local namespace if we need it:
1777 # Grab local namespace if we need it:
1771 if getattr(fn, "needs_local_scope", False):
1778 if getattr(fn, "needs_local_scope", False):
1772 self._magic_locals = sys._getframe(1).f_locals
1779 self._magic_locals = sys._getframe(1).f_locals
1773 with nested(self.builtin_trap,):
1780 with nested(self.builtin_trap,):
1774 result = fn(magic_args)
1781 result = fn(magic_args)
1775 # Ensure we're not keeping object references around:
1782 # Ensure we're not keeping object references around:
1776 self._magic_locals = {}
1783 self._magic_locals = {}
1777 return result
1784 return result
1778
1785
1779 def define_magic(self, magicname, func):
1786 def define_magic(self, magicname, func):
1780 """Expose own function as magic function for ipython
1787 """Expose own function as magic function for ipython
1781
1788
1782 def foo_impl(self,parameter_s=''):
1789 def foo_impl(self,parameter_s=''):
1783 'My very own magic!. (Use docstrings, IPython reads them).'
1790 'My very own magic!. (Use docstrings, IPython reads them).'
1784 print 'Magic function. Passed parameter is between < >:'
1791 print 'Magic function. Passed parameter is between < >:'
1785 print '<%s>' % parameter_s
1792 print '<%s>' % parameter_s
1786 print 'The self object is:',self
1793 print 'The self object is:',self
1787
1794
1788 self.define_magic('foo',foo_impl)
1795 self.define_magic('foo',foo_impl)
1789 """
1796 """
1790
1797
1791 import new
1798 import new
1792 im = types.MethodType(func,self)
1799 im = types.MethodType(func,self)
1793 old = getattr(self, "magic_" + magicname, None)
1800 old = getattr(self, "magic_" + magicname, None)
1794 setattr(self, "magic_" + magicname, im)
1801 setattr(self, "magic_" + magicname, im)
1795 return old
1802 return old
1796
1803
1797 #-------------------------------------------------------------------------
1804 #-------------------------------------------------------------------------
1798 # Things related to macros
1805 # Things related to macros
1799 #-------------------------------------------------------------------------
1806 #-------------------------------------------------------------------------
1800
1807
1801 def define_macro(self, name, themacro):
1808 def define_macro(self, name, themacro):
1802 """Define a new macro
1809 """Define a new macro
1803
1810
1804 Parameters
1811 Parameters
1805 ----------
1812 ----------
1806 name : str
1813 name : str
1807 The name of the macro.
1814 The name of the macro.
1808 themacro : str or Macro
1815 themacro : str or Macro
1809 The action to do upon invoking the macro. If a string, a new
1816 The action to do upon invoking the macro. If a string, a new
1810 Macro object is created by passing the string to it.
1817 Macro object is created by passing the string to it.
1811 """
1818 """
1812
1819
1813 from IPython.core import macro
1820 from IPython.core import macro
1814
1821
1815 if isinstance(themacro, basestring):
1822 if isinstance(themacro, basestring):
1816 themacro = macro.Macro(themacro)
1823 themacro = macro.Macro(themacro)
1817 if not isinstance(themacro, macro.Macro):
1824 if not isinstance(themacro, macro.Macro):
1818 raise ValueError('A macro must be a string or a Macro instance.')
1825 raise ValueError('A macro must be a string or a Macro instance.')
1819 self.user_ns[name] = themacro
1826 self.user_ns[name] = themacro
1820
1827
1821 #-------------------------------------------------------------------------
1828 #-------------------------------------------------------------------------
1822 # Things related to the running of system commands
1829 # Things related to the running of system commands
1823 #-------------------------------------------------------------------------
1830 #-------------------------------------------------------------------------
1824
1831
1825 def system(self, cmd):
1832 def system(self, cmd):
1826 """Call the given cmd in a subprocess.
1833 """Call the given cmd in a subprocess.
1827
1834
1828 Parameters
1835 Parameters
1829 ----------
1836 ----------
1830 cmd : str
1837 cmd : str
1831 Command to execute (can not end in '&', as bacground processes are
1838 Command to execute (can not end in '&', as bacground processes are
1832 not supported.
1839 not supported.
1833 """
1840 """
1834 # We do not support backgrounding processes because we either use
1841 # We do not support backgrounding processes because we either use
1835 # pexpect or pipes to read from. Users can always just call
1842 # pexpect or pipes to read from. Users can always just call
1836 # os.system() if they really want a background process.
1843 # os.system() if they really want a background process.
1837 if cmd.endswith('&'):
1844 if cmd.endswith('&'):
1838 raise OSError("Background processes not supported.")
1845 raise OSError("Background processes not supported.")
1839
1846
1840 return system(self.var_expand(cmd, depth=2))
1847 return system(self.var_expand(cmd, depth=2))
1841
1848
1842 def getoutput(self, cmd, split=True):
1849 def getoutput(self, cmd, split=True):
1843 """Get output (possibly including stderr) from a subprocess.
1850 """Get output (possibly including stderr) from a subprocess.
1844
1851
1845 Parameters
1852 Parameters
1846 ----------
1853 ----------
1847 cmd : str
1854 cmd : str
1848 Command to execute (can not end in '&', as background processes are
1855 Command to execute (can not end in '&', as background processes are
1849 not supported.
1856 not supported.
1850 split : bool, optional
1857 split : bool, optional
1851
1858
1852 If True, split the output into an IPython SList. Otherwise, an
1859 If True, split the output into an IPython SList. Otherwise, an
1853 IPython LSString is returned. These are objects similar to normal
1860 IPython LSString is returned. These are objects similar to normal
1854 lists and strings, with a few convenience attributes for easier
1861 lists and strings, with a few convenience attributes for easier
1855 manipulation of line-based output. You can use '?' on them for
1862 manipulation of line-based output. You can use '?' on them for
1856 details.
1863 details.
1857 """
1864 """
1858 if cmd.endswith('&'):
1865 if cmd.endswith('&'):
1859 raise OSError("Background processes not supported.")
1866 raise OSError("Background processes not supported.")
1860 out = getoutput(self.var_expand(cmd, depth=2))
1867 out = getoutput(self.var_expand(cmd, depth=2))
1861 if split:
1868 if split:
1862 out = SList(out.splitlines())
1869 out = SList(out.splitlines())
1863 else:
1870 else:
1864 out = LSString(out)
1871 out = LSString(out)
1865 return out
1872 return out
1866
1873
1867 #-------------------------------------------------------------------------
1874 #-------------------------------------------------------------------------
1868 # Things related to aliases
1875 # Things related to aliases
1869 #-------------------------------------------------------------------------
1876 #-------------------------------------------------------------------------
1870
1877
1871 def init_alias(self):
1878 def init_alias(self):
1872 self.alias_manager = AliasManager(shell=self, config=self.config)
1879 self.alias_manager = AliasManager(shell=self, config=self.config)
1873 self.ns_table['alias'] = self.alias_manager.alias_table,
1880 self.ns_table['alias'] = self.alias_manager.alias_table,
1874
1881
1875 #-------------------------------------------------------------------------
1882 #-------------------------------------------------------------------------
1876 # Things related to extensions and plugins
1883 # Things related to extensions and plugins
1877 #-------------------------------------------------------------------------
1884 #-------------------------------------------------------------------------
1878
1885
1879 def init_extension_manager(self):
1886 def init_extension_manager(self):
1880 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1887 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1881
1888
1882 def init_plugin_manager(self):
1889 def init_plugin_manager(self):
1883 self.plugin_manager = PluginManager(config=self.config)
1890 self.plugin_manager = PluginManager(config=self.config)
1884
1891
1885 #-------------------------------------------------------------------------
1892 #-------------------------------------------------------------------------
1886 # Things related to payloads
1893 # Things related to payloads
1887 #-------------------------------------------------------------------------
1894 #-------------------------------------------------------------------------
1888
1895
1889 def init_payload(self):
1896 def init_payload(self):
1890 self.payload_manager = PayloadManager(config=self.config)
1897 self.payload_manager = PayloadManager(config=self.config)
1891
1898
1892 #-------------------------------------------------------------------------
1899 #-------------------------------------------------------------------------
1893 # Things related to the prefilter
1900 # Things related to the prefilter
1894 #-------------------------------------------------------------------------
1901 #-------------------------------------------------------------------------
1895
1902
1896 def init_prefilter(self):
1903 def init_prefilter(self):
1897 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1904 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1898 # Ultimately this will be refactored in the new interpreter code, but
1905 # Ultimately this will be refactored in the new interpreter code, but
1899 # for now, we should expose the main prefilter method (there's legacy
1906 # for now, we should expose the main prefilter method (there's legacy
1900 # code out there that may rely on this).
1907 # code out there that may rely on this).
1901 self.prefilter = self.prefilter_manager.prefilter_lines
1908 self.prefilter = self.prefilter_manager.prefilter_lines
1902
1909
1903 def auto_rewrite_input(self, cmd):
1910 def auto_rewrite_input(self, cmd):
1904 """Print to the screen the rewritten form of the user's command.
1911 """Print to the screen the rewritten form of the user's command.
1905
1912
1906 This shows visual feedback by rewriting input lines that cause
1913 This shows visual feedback by rewriting input lines that cause
1907 automatic calling to kick in, like::
1914 automatic calling to kick in, like::
1908
1915
1909 /f x
1916 /f x
1910
1917
1911 into::
1918 into::
1912
1919
1913 ------> f(x)
1920 ------> f(x)
1914
1921
1915 after the user's input prompt. This helps the user understand that the
1922 after the user's input prompt. This helps the user understand that the
1916 input line was transformed automatically by IPython.
1923 input line was transformed automatically by IPython.
1917 """
1924 """
1918 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1925 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1919
1926
1920 try:
1927 try:
1921 # plain ascii works better w/ pyreadline, on some machines, so
1928 # plain ascii works better w/ pyreadline, on some machines, so
1922 # we use it and only print uncolored rewrite if we have unicode
1929 # we use it and only print uncolored rewrite if we have unicode
1923 rw = str(rw)
1930 rw = str(rw)
1924 print >> IPython.utils.io.Term.cout, rw
1931 print >> IPython.utils.io.Term.cout, rw
1925 except UnicodeEncodeError:
1932 except UnicodeEncodeError:
1926 print "------> " + cmd
1933 print "------> " + cmd
1927
1934
1928 #-------------------------------------------------------------------------
1935 #-------------------------------------------------------------------------
1929 # Things related to extracting values/expressions from kernel and user_ns
1936 # Things related to extracting values/expressions from kernel and user_ns
1930 #-------------------------------------------------------------------------
1937 #-------------------------------------------------------------------------
1931
1938
1932 def _simple_error(self):
1939 def _simple_error(self):
1933 etype, value = sys.exc_info()[:2]
1940 etype, value = sys.exc_info()[:2]
1934 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1941 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1935
1942
1936 def user_variables(self, names):
1943 def user_variables(self, names):
1937 """Get a list of variable names from the user's namespace.
1944 """Get a list of variable names from the user's namespace.
1938
1945
1939 Parameters
1946 Parameters
1940 ----------
1947 ----------
1941 names : list of strings
1948 names : list of strings
1942 A list of names of variables to be read from the user namespace.
1949 A list of names of variables to be read from the user namespace.
1943
1950
1944 Returns
1951 Returns
1945 -------
1952 -------
1946 A dict, keyed by the input names and with the repr() of each value.
1953 A dict, keyed by the input names and with the repr() of each value.
1947 """
1954 """
1948 out = {}
1955 out = {}
1949 user_ns = self.user_ns
1956 user_ns = self.user_ns
1950 for varname in names:
1957 for varname in names:
1951 try:
1958 try:
1952 value = repr(user_ns[varname])
1959 value = repr(user_ns[varname])
1953 except:
1960 except:
1954 value = self._simple_error()
1961 value = self._simple_error()
1955 out[varname] = value
1962 out[varname] = value
1956 return out
1963 return out
1957
1964
1958 def user_expressions(self, expressions):
1965 def user_expressions(self, expressions):
1959 """Evaluate a dict of expressions in the user's namespace.
1966 """Evaluate a dict of expressions in the user's namespace.
1960
1967
1961 Parameters
1968 Parameters
1962 ----------
1969 ----------
1963 expressions : dict
1970 expressions : dict
1964 A dict with string keys and string values. The expression values
1971 A dict with string keys and string values. The expression values
1965 should be valid Python expressions, each of which will be evaluated
1972 should be valid Python expressions, each of which will be evaluated
1966 in the user namespace.
1973 in the user namespace.
1967
1974
1968 Returns
1975 Returns
1969 -------
1976 -------
1970 A dict, keyed like the input expressions dict, with the repr() of each
1977 A dict, keyed like the input expressions dict, with the repr() of each
1971 value.
1978 value.
1972 """
1979 """
1973 out = {}
1980 out = {}
1974 user_ns = self.user_ns
1981 user_ns = self.user_ns
1975 global_ns = self.user_global_ns
1982 global_ns = self.user_global_ns
1976 for key, expr in expressions.iteritems():
1983 for key, expr in expressions.iteritems():
1977 try:
1984 try:
1978 value = repr(eval(expr, global_ns, user_ns))
1985 value = repr(eval(expr, global_ns, user_ns))
1979 except:
1986 except:
1980 value = self._simple_error()
1987 value = self._simple_error()
1981 out[key] = value
1988 out[key] = value
1982 return out
1989 return out
1983
1990
1984 #-------------------------------------------------------------------------
1991 #-------------------------------------------------------------------------
1985 # Things related to the running of code
1992 # Things related to the running of code
1986 #-------------------------------------------------------------------------
1993 #-------------------------------------------------------------------------
1987
1994
1988 def ex(self, cmd):
1995 def ex(self, cmd):
1989 """Execute a normal python statement in user namespace."""
1996 """Execute a normal python statement in user namespace."""
1990 with nested(self.builtin_trap,):
1997 with nested(self.builtin_trap,):
1991 exec cmd in self.user_global_ns, self.user_ns
1998 exec cmd in self.user_global_ns, self.user_ns
1992
1999
1993 def ev(self, expr):
2000 def ev(self, expr):
1994 """Evaluate python expression expr in user namespace.
2001 """Evaluate python expression expr in user namespace.
1995
2002
1996 Returns the result of evaluation
2003 Returns the result of evaluation
1997 """
2004 """
1998 with nested(self.builtin_trap,):
2005 with nested(self.builtin_trap,):
1999 return eval(expr, self.user_global_ns, self.user_ns)
2006 return eval(expr, self.user_global_ns, self.user_ns)
2000
2007
2001 def safe_execfile(self, fname, *where, **kw):
2008 def safe_execfile(self, fname, *where, **kw):
2002 """A safe version of the builtin execfile().
2009 """A safe version of the builtin execfile().
2003
2010
2004 This version will never throw an exception, but instead print
2011 This version will never throw an exception, but instead print
2005 helpful error messages to the screen. This only works on pure
2012 helpful error messages to the screen. This only works on pure
2006 Python files with the .py extension.
2013 Python files with the .py extension.
2007
2014
2008 Parameters
2015 Parameters
2009 ----------
2016 ----------
2010 fname : string
2017 fname : string
2011 The name of the file to be executed.
2018 The name of the file to be executed.
2012 where : tuple
2019 where : tuple
2013 One or two namespaces, passed to execfile() as (globals,locals).
2020 One or two namespaces, passed to execfile() as (globals,locals).
2014 If only one is given, it is passed as both.
2021 If only one is given, it is passed as both.
2015 exit_ignore : bool (False)
2022 exit_ignore : bool (False)
2016 If True, then silence SystemExit for non-zero status (it is always
2023 If True, then silence SystemExit for non-zero status (it is always
2017 silenced for zero status, as it is so common).
2024 silenced for zero status, as it is so common).
2018 """
2025 """
2019 kw.setdefault('exit_ignore', False)
2026 kw.setdefault('exit_ignore', False)
2020
2027
2021 fname = os.path.abspath(os.path.expanduser(fname))
2028 fname = os.path.abspath(os.path.expanduser(fname))
2022 # Make sure we have a .py file
2029 # Make sure we have a .py file
2023 if not fname.endswith('.py'):
2030 if not fname.endswith('.py'):
2024 warn('File must end with .py to be run using execfile: <%s>' % fname)
2031 warn('File must end with .py to be run using execfile: <%s>' % fname)
2025
2032
2026 # Make sure we can open the file
2033 # Make sure we can open the file
2027 try:
2034 try:
2028 with open(fname) as thefile:
2035 with open(fname) as thefile:
2029 pass
2036 pass
2030 except:
2037 except:
2031 warn('Could not open file <%s> for safe execution.' % fname)
2038 warn('Could not open file <%s> for safe execution.' % fname)
2032 return
2039 return
2033
2040
2034 # Find things also in current directory. This is needed to mimic the
2041 # Find things also in current directory. This is needed to mimic the
2035 # behavior of running a script from the system command line, where
2042 # behavior of running a script from the system command line, where
2036 # Python inserts the script's directory into sys.path
2043 # Python inserts the script's directory into sys.path
2037 dname = os.path.dirname(fname)
2044 dname = os.path.dirname(fname)
2038
2045
2039 if isinstance(fname, unicode):
2046 if isinstance(fname, unicode):
2040 # execfile uses default encoding instead of filesystem encoding
2047 # execfile uses default encoding instead of filesystem encoding
2041 # so unicode filenames will fail
2048 # so unicode filenames will fail
2042 fname = fname.encode(sys.getfilesystemencoding() or sys.getdefaultencoding())
2049 fname = fname.encode(sys.getfilesystemencoding() or sys.getdefaultencoding())
2043
2050
2044 with prepended_to_syspath(dname):
2051 with prepended_to_syspath(dname):
2045 try:
2052 try:
2046 execfile(fname,*where)
2053 execfile(fname,*where)
2047 except SystemExit, status:
2054 except SystemExit, status:
2048 # If the call was made with 0 or None exit status (sys.exit(0)
2055 # If the call was made with 0 or None exit status (sys.exit(0)
2049 # or sys.exit() ), don't bother showing a traceback, as both of
2056 # or sys.exit() ), don't bother showing a traceback, as both of
2050 # these are considered normal by the OS:
2057 # these are considered normal by the OS:
2051 # > python -c'import sys;sys.exit(0)'; echo $?
2058 # > python -c'import sys;sys.exit(0)'; echo $?
2052 # 0
2059 # 0
2053 # > python -c'import sys;sys.exit()'; echo $?
2060 # > python -c'import sys;sys.exit()'; echo $?
2054 # 0
2061 # 0
2055 # For other exit status, we show the exception unless
2062 # For other exit status, we show the exception unless
2056 # explicitly silenced, but only in short form.
2063 # explicitly silenced, but only in short form.
2057 if status.code not in (0, None) and not kw['exit_ignore']:
2064 if status.code not in (0, None) and not kw['exit_ignore']:
2058 self.showtraceback(exception_only=True)
2065 self.showtraceback(exception_only=True)
2059 except:
2066 except:
2060 self.showtraceback()
2067 self.showtraceback()
2061
2068
2062 def safe_execfile_ipy(self, fname):
2069 def safe_execfile_ipy(self, fname):
2063 """Like safe_execfile, but for .ipy files with IPython syntax.
2070 """Like safe_execfile, but for .ipy files with IPython syntax.
2064
2071
2065 Parameters
2072 Parameters
2066 ----------
2073 ----------
2067 fname : str
2074 fname : str
2068 The name of the file to execute. The filename must have a
2075 The name of the file to execute. The filename must have a
2069 .ipy extension.
2076 .ipy extension.
2070 """
2077 """
2071 fname = os.path.abspath(os.path.expanduser(fname))
2078 fname = os.path.abspath(os.path.expanduser(fname))
2072
2079
2073 # Make sure we have a .py file
2080 # Make sure we have a .py file
2074 if not fname.endswith('.ipy'):
2081 if not fname.endswith('.ipy'):
2075 warn('File must end with .py to be run using execfile: <%s>' % fname)
2082 warn('File must end with .py to be run using execfile: <%s>' % fname)
2076
2083
2077 # Make sure we can open the file
2084 # Make sure we can open the file
2078 try:
2085 try:
2079 with open(fname) as thefile:
2086 with open(fname) as thefile:
2080 pass
2087 pass
2081 except:
2088 except:
2082 warn('Could not open file <%s> for safe execution.' % fname)
2089 warn('Could not open file <%s> for safe execution.' % fname)
2083 return
2090 return
2084
2091
2085 # Find things also in current directory. This is needed to mimic the
2092 # Find things also in current directory. This is needed to mimic the
2086 # behavior of running a script from the system command line, where
2093 # behavior of running a script from the system command line, where
2087 # Python inserts the script's directory into sys.path
2094 # Python inserts the script's directory into sys.path
2088 dname = os.path.dirname(fname)
2095 dname = os.path.dirname(fname)
2089
2096
2090 with prepended_to_syspath(dname):
2097 with prepended_to_syspath(dname):
2091 try:
2098 try:
2092 with open(fname) as thefile:
2099 with open(fname) as thefile:
2093 # self.run_cell currently captures all exceptions
2100 # self.run_cell currently captures all exceptions
2094 # raised in user code. It would be nice if there were
2101 # raised in user code. It would be nice if there were
2095 # versions of runlines, execfile that did raise, so
2102 # versions of runlines, execfile that did raise, so
2096 # we could catch the errors.
2103 # we could catch the errors.
2097 self.run_cell(thefile.read(), store_history=False)
2104 self.run_cell(thefile.read(), store_history=False)
2098 except:
2105 except:
2099 self.showtraceback()
2106 self.showtraceback()
2100 warn('Unknown failure executing file: <%s>' % fname)
2107 warn('Unknown failure executing file: <%s>' % fname)
2101
2108
2102 def run_cell(self, cell, store_history=True):
2109 def run_cell(self, cell, store_history=True):
2103 """Run the contents of an entire multiline 'cell' of code, and store it
2110 """Run the contents of an entire multiline 'cell' of code, and store it
2104 in the history.
2111 in the history.
2105
2112
2106 The cell is split into separate blocks which can be executed
2113 The cell is split into separate blocks which can be executed
2107 individually. Then, based on how many blocks there are, they are
2114 individually. Then, based on how many blocks there are, they are
2108 executed as follows:
2115 executed as follows:
2109
2116
2110 - A single block: 'single' mode. If it is also a single line, dynamic
2117 - A single block: 'single' mode. If it is also a single line, dynamic
2111 transformations, including automagic and macros, will be applied.
2118 transformations, including automagic and macros, will be applied.
2112
2119
2113 If there's more than one block, it depends:
2120 If there's more than one block, it depends:
2114
2121
2115 - if the last one is no more than two lines long, run all but the last
2122 - if the last one is no more than two lines long, run all but the last
2116 in 'exec' mode and the very last one in 'single' mode. This makes it
2123 in 'exec' mode and the very last one in 'single' mode. This makes it
2117 easy to type simple expressions at the end to see computed values. -
2124 easy to type simple expressions at the end to see computed values. -
2118 otherwise (last one is also multiline), run all in 'exec' mode
2125 otherwise (last one is also multiline), run all in 'exec' mode
2119
2126
2120 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2127 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2121 results are displayed and output prompts are computed. In 'exec' mode,
2128 results are displayed and output prompts are computed. In 'exec' mode,
2122 no results are displayed unless :func:`print` is called explicitly;
2129 no results are displayed unless :func:`print` is called explicitly;
2123 this mode is more akin to running a script.
2130 this mode is more akin to running a script.
2124
2131
2125 Parameters
2132 Parameters
2126 ----------
2133 ----------
2127 cell : str
2134 cell : str
2128 A single or multiline string.
2135 A single or multiline string.
2129 """
2136 """
2130 # Store the untransformed code
2137 # Store the untransformed code
2131 raw_cell = cell
2138 raw_cell = cell
2132
2139
2133 # Code transformation and execution must take place with our
2140 # Code transformation and execution must take place with our
2134 # modifications to builtins.
2141 # modifications to builtins.
2135 with self.builtin_trap:
2142 with self.builtin_trap:
2136
2143
2137 # We need to break up the input into executable blocks that can
2144 # We need to break up the input into executable blocks that can
2138 # be runin 'single' mode, to provide comfortable user behavior.
2145 # be runin 'single' mode, to provide comfortable user behavior.
2139 blocks = self.input_splitter.split_blocks(cell)
2146 blocks = self.input_splitter.split_blocks(cell)
2140
2147
2141 if not blocks: # Blank cell
2148 if not blocks: # Blank cell
2142 return
2149 return
2143
2150
2144 # We only do dynamic transforms on a single line. But a macro
2151 # We only do dynamic transforms on a single line. But a macro
2145 # can be expanded to several lines, so we need to split it
2152 # can be expanded to several lines, so we need to split it
2146 # into input blocks again.
2153 # into input blocks again.
2147 if len(cell.splitlines()) <= 1:
2154 if len(cell.splitlines()) <= 1:
2148 cell = self.prefilter_manager.prefilter_line(blocks[0])
2155 cell = self.prefilter_manager.prefilter_line(blocks[0])
2149 blocks = self.input_splitter.split_blocks(cell)
2156 blocks = self.input_splitter.split_blocks(cell)
2150
2157
2151 # Store the 'ipython' version of the cell as well, since
2158 # Store the 'ipython' version of the cell as well, since
2152 # that's what needs to go into the translated history and get
2159 # that's what needs to go into the translated history and get
2153 # executed (the original cell may contain non-python syntax).
2160 # executed (the original cell may contain non-python syntax).
2154 cell = ''.join(blocks)
2161 cell = ''.join(blocks)
2155
2162
2156 # Store raw and processed history
2163 # Store raw and processed history
2157 if store_history:
2164 if store_history:
2158 self.history_manager.store_inputs(self.execution_count,
2165 self.history_manager.store_inputs(self.execution_count,
2159 cell, raw_cell)
2166 cell, raw_cell)
2160
2167
2161 self.logger.log(cell, raw_cell)
2168 self.logger.log(cell, raw_cell)
2162
2169
2163 # All user code execution should take place with our
2170 # All user code execution should take place with our
2164 # modified displayhook.
2171 # modified displayhook.
2165 with self.display_trap:
2172 with self.display_trap:
2166 # Single-block input should behave like an interactive prompt
2173 # Single-block input should behave like an interactive prompt
2167 if len(blocks) == 1:
2174 if len(blocks) == 1:
2168 out = self.run_source(blocks[0])
2175 out = self.run_source(blocks[0])
2169 # Write output to the database. Does nothing unless
2176 # Write output to the database. Does nothing unless
2170 # history output logging is enabled.
2177 # history output logging is enabled.
2171 if store_history:
2178 if store_history:
2172 self.history_manager.store_output(self.execution_count)
2179 self.history_manager.store_output(self.execution_count)
2173 # Since we return here, we need to update the
2180 # Since we return here, we need to update the
2174 # execution count
2181 # execution count
2175 self.execution_count += 1
2182 self.execution_count += 1
2176 return out
2183 return out
2177
2184
2178 # In multi-block input, if the last block is a simple (one-two
2185 # In multi-block input, if the last block is a simple (one-two
2179 # lines) expression, run it in single mode so it produces output.
2186 # lines) expression, run it in single mode so it produces output.
2180 # Otherwise just run it all in 'exec' mode. This seems like a
2187 # Otherwise just run it all in 'exec' mode. This seems like a
2181 # reasonable usability design.
2188 # reasonable usability design.
2182 last = blocks[-1]
2189 last = blocks[-1]
2183 last_nlines = len(last.splitlines())
2190 last_nlines = len(last.splitlines())
2184
2191
2185 if last_nlines < 2:
2192 if last_nlines < 2:
2186 # Here we consider the cell split between 'body' and 'last',
2193 # Here we consider the cell split between 'body' and 'last',
2187 # store all history and execute 'body', and if successful, then
2194 # store all history and execute 'body', and if successful, then
2188 # proceed to execute 'last'.
2195 # proceed to execute 'last'.
2189
2196
2190 # Get the main body to run as a cell
2197 # Get the main body to run as a cell
2191 ipy_body = ''.join(blocks[:-1])
2198 ipy_body = ''.join(blocks[:-1])
2192 retcode = self.run_source(ipy_body, symbol='exec',
2199 retcode = self.run_source(ipy_body, symbol='exec',
2193 post_execute=False)
2200 post_execute=False)
2194 if retcode==0:
2201 if retcode==0:
2195 # Last expression compiled as 'single' so it
2202 # Last expression compiled as 'single' so it
2196 # produces output
2203 # produces output
2197 self.run_source(last)
2204 self.run_source(last)
2198 else:
2205 else:
2199 # Run the whole cell as one entity, storing both raw and
2206 # Run the whole cell as one entity, storing both raw and
2200 # processed input in history
2207 # processed input in history
2201 self.run_source(cell, symbol='exec')
2208 self.run_source(cell, symbol='exec')
2202
2209
2203 # Write output to the database. Does nothing unless
2210 # Write output to the database. Does nothing unless
2204 # history output logging is enabled.
2211 # history output logging is enabled.
2205 if store_history:
2212 if store_history:
2206 self.history_manager.store_output(self.execution_count)
2213 self.history_manager.store_output(self.execution_count)
2207 # Each cell is a *single* input, regardless of how many lines it has
2214 # Each cell is a *single* input, regardless of how many lines it has
2208 self.execution_count += 1
2215 self.execution_count += 1
2209
2216
2210 # PENDING REMOVAL: this method is slated for deletion, once our new
2217 # PENDING REMOVAL: this method is slated for deletion, once our new
2211 # input logic has been 100% moved to frontends and is stable.
2218 # input logic has been 100% moved to frontends and is stable.
2212 def runlines(self, lines, clean=False):
2219 def runlines(self, lines, clean=False):
2213 """Run a string of one or more lines of source.
2220 """Run a string of one or more lines of source.
2214
2221
2215 This method is capable of running a string containing multiple source
2222 This method is capable of running a string containing multiple source
2216 lines, as if they had been entered at the IPython prompt. Since it
2223 lines, as if they had been entered at the IPython prompt. Since it
2217 exposes IPython's processing machinery, the given strings can contain
2224 exposes IPython's processing machinery, the given strings can contain
2218 magic calls (%magic), special shell access (!cmd), etc.
2225 magic calls (%magic), special shell access (!cmd), etc.
2219 """
2226 """
2220
2227
2221 if not isinstance(lines, (list, tuple)):
2228 if not isinstance(lines, (list, tuple)):
2222 lines = lines.splitlines()
2229 lines = lines.splitlines()
2223
2230
2224 if clean:
2231 if clean:
2225 lines = self._cleanup_ipy_script(lines)
2232 lines = self._cleanup_ipy_script(lines)
2226
2233
2227 # We must start with a clean buffer, in case this is run from an
2234 # We must start with a clean buffer, in case this is run from an
2228 # interactive IPython session (via a magic, for example).
2235 # interactive IPython session (via a magic, for example).
2229 self.reset_buffer()
2236 self.reset_buffer()
2230
2237
2231 # Since we will prefilter all lines, store the user's raw input too
2238 # Since we will prefilter all lines, store the user's raw input too
2232 # before we apply any transformations
2239 # before we apply any transformations
2233 self.buffer_raw[:] = [ l+'\n' for l in lines]
2240 self.buffer_raw[:] = [ l+'\n' for l in lines]
2234
2241
2235 more = False
2242 more = False
2236 prefilter_lines = self.prefilter_manager.prefilter_lines
2243 prefilter_lines = self.prefilter_manager.prefilter_lines
2237 with nested(self.builtin_trap, self.display_trap):
2244 with nested(self.builtin_trap, self.display_trap):
2238 for line in lines:
2245 for line in lines:
2239 # skip blank lines so we don't mess up the prompt counter, but
2246 # skip blank lines so we don't mess up the prompt counter, but
2240 # do NOT skip even a blank line if we are in a code block (more
2247 # do NOT skip even a blank line if we are in a code block (more
2241 # is true)
2248 # is true)
2242
2249
2243 if line or more:
2250 if line or more:
2244 more = self.push_line(prefilter_lines(line, more))
2251 more = self.push_line(prefilter_lines(line, more))
2245 # IPython's run_source returns None if there was an error
2252 # IPython's run_source returns None if there was an error
2246 # compiling the code. This allows us to stop processing
2253 # compiling the code. This allows us to stop processing
2247 # right away, so the user gets the error message at the
2254 # right away, so the user gets the error message at the
2248 # right place.
2255 # right place.
2249 if more is None:
2256 if more is None:
2250 break
2257 break
2251 # final newline in case the input didn't have it, so that the code
2258 # final newline in case the input didn't have it, so that the code
2252 # actually does get executed
2259 # actually does get executed
2253 if more:
2260 if more:
2254 self.push_line('\n')
2261 self.push_line('\n')
2255
2262
2256 def run_source(self, source, filename=None,
2263 def run_source(self, source, filename=None,
2257 symbol='single', post_execute=True):
2264 symbol='single', post_execute=True):
2258 """Compile and run some source in the interpreter.
2265 """Compile and run some source in the interpreter.
2259
2266
2260 Arguments are as for compile_command().
2267 Arguments are as for compile_command().
2261
2268
2262 One several things can happen:
2269 One several things can happen:
2263
2270
2264 1) The input is incorrect; compile_command() raised an
2271 1) The input is incorrect; compile_command() raised an
2265 exception (SyntaxError or OverflowError). A syntax traceback
2272 exception (SyntaxError or OverflowError). A syntax traceback
2266 will be printed by calling the showsyntaxerror() method.
2273 will be printed by calling the showsyntaxerror() method.
2267
2274
2268 2) The input is incomplete, and more input is required;
2275 2) The input is incomplete, and more input is required;
2269 compile_command() returned None. Nothing happens.
2276 compile_command() returned None. Nothing happens.
2270
2277
2271 3) The input is complete; compile_command() returned a code
2278 3) The input is complete; compile_command() returned a code
2272 object. The code is executed by calling self.run_code() (which
2279 object. The code is executed by calling self.run_code() (which
2273 also handles run-time exceptions, except for SystemExit).
2280 also handles run-time exceptions, except for SystemExit).
2274
2281
2275 The return value is:
2282 The return value is:
2276
2283
2277 - True in case 2
2284 - True in case 2
2278
2285
2279 - False in the other cases, unless an exception is raised, where
2286 - False in the other cases, unless an exception is raised, where
2280 None is returned instead. This can be used by external callers to
2287 None is returned instead. This can be used by external callers to
2281 know whether to continue feeding input or not.
2288 know whether to continue feeding input or not.
2282
2289
2283 The return value can be used to decide whether to use sys.ps1 or
2290 The return value can be used to decide whether to use sys.ps1 or
2284 sys.ps2 to prompt the next line."""
2291 sys.ps2 to prompt the next line."""
2285
2292
2286 # We need to ensure that the source is unicode from here on.
2293 # We need to ensure that the source is unicode from here on.
2287 if type(source)==str:
2294 if type(source)==str:
2288 usource = source.decode(self.stdin_encoding)
2295 usource = source.decode(self.stdin_encoding)
2289 else:
2296 else:
2290 usource = source
2297 usource = source
2291
2298
2292 if False: # dbg
2299 if False: # dbg
2293 print 'Source:', repr(source) # dbg
2300 print 'Source:', repr(source) # dbg
2294 print 'USource:', repr(usource) # dbg
2301 print 'USource:', repr(usource) # dbg
2295 print 'type:', type(source) # dbg
2302 print 'type:', type(source) # dbg
2296 print 'encoding', self.stdin_encoding # dbg
2303 print 'encoding', self.stdin_encoding # dbg
2297
2304
2298 try:
2305 try:
2299 code = self.compile(usource, symbol, self.execution_count)
2306 code = self.compile(usource, symbol, self.execution_count)
2300 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2307 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2301 # Case 1
2308 # Case 1
2302 self.showsyntaxerror(filename)
2309 self.showsyntaxerror(filename)
2303 return None
2310 return None
2304
2311
2305 if code is None:
2312 if code is None:
2306 # Case 2
2313 # Case 2
2307 return True
2314 return True
2308
2315
2309 # Case 3
2316 # Case 3
2310 # We store the code object so that threaded shells and
2317 # We store the code object so that threaded shells and
2311 # custom exception handlers can access all this info if needed.
2318 # custom exception handlers can access all this info if needed.
2312 # The source corresponding to this can be obtained from the
2319 # The source corresponding to this can be obtained from the
2313 # buffer attribute as '\n'.join(self.buffer).
2320 # buffer attribute as '\n'.join(self.buffer).
2314 self.code_to_run = code
2321 self.code_to_run = code
2315 # now actually execute the code object
2322 # now actually execute the code object
2316 if self.run_code(code, post_execute) == 0:
2323 if self.run_code(code, post_execute) == 0:
2317 return False
2324 return False
2318 else:
2325 else:
2319 return None
2326 return None
2320
2327
2321 # For backwards compatibility
2328 # For backwards compatibility
2322 runsource = run_source
2329 runsource = run_source
2323
2330
2324 def run_code(self, code_obj, post_execute=True):
2331 def run_code(self, code_obj, post_execute=True):
2325 """Execute a code object.
2332 """Execute a code object.
2326
2333
2327 When an exception occurs, self.showtraceback() is called to display a
2334 When an exception occurs, self.showtraceback() is called to display a
2328 traceback.
2335 traceback.
2329
2336
2330 Return value: a flag indicating whether the code to be run completed
2337 Return value: a flag indicating whether the code to be run completed
2331 successfully:
2338 successfully:
2332
2339
2333 - 0: successful execution.
2340 - 0: successful execution.
2334 - 1: an error occurred.
2341 - 1: an error occurred.
2335 """
2342 """
2336
2343
2337 # Set our own excepthook in case the user code tries to call it
2344 # Set our own excepthook in case the user code tries to call it
2338 # directly, so that the IPython crash handler doesn't get triggered
2345 # directly, so that the IPython crash handler doesn't get triggered
2339 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2346 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2340
2347
2341 # we save the original sys.excepthook in the instance, in case config
2348 # we save the original sys.excepthook in the instance, in case config
2342 # code (such as magics) needs access to it.
2349 # code (such as magics) needs access to it.
2343 self.sys_excepthook = old_excepthook
2350 self.sys_excepthook = old_excepthook
2344 outflag = 1 # happens in more places, so it's easier as default
2351 outflag = 1 # happens in more places, so it's easier as default
2345 try:
2352 try:
2346 try:
2353 try:
2347 self.hooks.pre_run_code_hook()
2354 self.hooks.pre_run_code_hook()
2348 #rprint('Running code', repr(code_obj)) # dbg
2355 #rprint('Running code', repr(code_obj)) # dbg
2349 exec code_obj in self.user_global_ns, self.user_ns
2356 exec code_obj in self.user_global_ns, self.user_ns
2350 finally:
2357 finally:
2351 # Reset our crash handler in place
2358 # Reset our crash handler in place
2352 sys.excepthook = old_excepthook
2359 sys.excepthook = old_excepthook
2353 except SystemExit:
2360 except SystemExit:
2354 self.reset_buffer()
2361 self.reset_buffer()
2355 self.showtraceback(exception_only=True)
2362 self.showtraceback(exception_only=True)
2356 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2363 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2357 except self.custom_exceptions:
2364 except self.custom_exceptions:
2358 etype,value,tb = sys.exc_info()
2365 etype,value,tb = sys.exc_info()
2359 self.CustomTB(etype,value,tb)
2366 self.CustomTB(etype,value,tb)
2360 except:
2367 except:
2361 self.showtraceback()
2368 self.showtraceback()
2362 else:
2369 else:
2363 outflag = 0
2370 outflag = 0
2364 if softspace(sys.stdout, 0):
2371 if softspace(sys.stdout, 0):
2365 print
2372 print
2366
2373
2367 # Execute any registered post-execution functions. Here, any errors
2374 # Execute any registered post-execution functions. Here, any errors
2368 # are reported only minimally and just on the terminal, because the
2375 # are reported only minimally and just on the terminal, because the
2369 # main exception channel may be occupied with a user traceback.
2376 # main exception channel may be occupied with a user traceback.
2370 # FIXME: we need to think this mechanism a little more carefully.
2377 # FIXME: we need to think this mechanism a little more carefully.
2371 if post_execute:
2378 if post_execute:
2372 for func in self._post_execute:
2379 for func in self._post_execute:
2373 try:
2380 try:
2374 func()
2381 func()
2375 except:
2382 except:
2376 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2383 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2377 func
2384 func
2378 print >> io.Term.cout, head
2385 print >> io.Term.cout, head
2379 print >> io.Term.cout, self._simple_error()
2386 print >> io.Term.cout, self._simple_error()
2380 print >> io.Term.cout, 'Removing from post_execute'
2387 print >> io.Term.cout, 'Removing from post_execute'
2381 self._post_execute.remove(func)
2388 self._post_execute.remove(func)
2382
2389
2383 # Flush out code object which has been run (and source)
2390 # Flush out code object which has been run (and source)
2384 self.code_to_run = None
2391 self.code_to_run = None
2385 return outflag
2392 return outflag
2386
2393
2387 # For backwards compatibility
2394 # For backwards compatibility
2388 runcode = run_code
2395 runcode = run_code
2389
2396
2390 # PENDING REMOVAL: this method is slated for deletion, once our new
2397 # PENDING REMOVAL: this method is slated for deletion, once our new
2391 # input logic has been 100% moved to frontends and is stable.
2398 # input logic has been 100% moved to frontends and is stable.
2392 def push_line(self, line):
2399 def push_line(self, line):
2393 """Push a line to the interpreter.
2400 """Push a line to the interpreter.
2394
2401
2395 The line should not have a trailing newline; it may have
2402 The line should not have a trailing newline; it may have
2396 internal newlines. The line is appended to a buffer and the
2403 internal newlines. The line is appended to a buffer and the
2397 interpreter's run_source() method is called with the
2404 interpreter's run_source() method is called with the
2398 concatenated contents of the buffer as source. If this
2405 concatenated contents of the buffer as source. If this
2399 indicates that the command was executed or invalid, the buffer
2406 indicates that the command was executed or invalid, the buffer
2400 is reset; otherwise, the command is incomplete, and the buffer
2407 is reset; otherwise, the command is incomplete, and the buffer
2401 is left as it was after the line was appended. The return
2408 is left as it was after the line was appended. The return
2402 value is 1 if more input is required, 0 if the line was dealt
2409 value is 1 if more input is required, 0 if the line was dealt
2403 with in some way (this is the same as run_source()).
2410 with in some way (this is the same as run_source()).
2404 """
2411 """
2405
2412
2406 # autoindent management should be done here, and not in the
2413 # autoindent management should be done here, and not in the
2407 # interactive loop, since that one is only seen by keyboard input. We
2414 # interactive loop, since that one is only seen by keyboard input. We
2408 # need this done correctly even for code run via runlines (which uses
2415 # need this done correctly even for code run via runlines (which uses
2409 # push).
2416 # push).
2410
2417
2411 #print 'push line: <%s>' % line # dbg
2418 #print 'push line: <%s>' % line # dbg
2412 self.buffer.append(line)
2419 self.buffer.append(line)
2413 full_source = '\n'.join(self.buffer)
2420 full_source = '\n'.join(self.buffer)
2414 more = self.run_source(full_source, self.filename)
2421 more = self.run_source(full_source, self.filename)
2415 if not more:
2422 if not more:
2416 self.history_manager.store_inputs(self.execution_count,
2423 self.history_manager.store_inputs(self.execution_count,
2417 '\n'.join(self.buffer_raw), full_source)
2424 '\n'.join(self.buffer_raw), full_source)
2418 self.reset_buffer()
2425 self.reset_buffer()
2419 self.execution_count += 1
2426 self.execution_count += 1
2420 return more
2427 return more
2421
2428
2422 def reset_buffer(self):
2429 def reset_buffer(self):
2423 """Reset the input buffer."""
2430 """Reset the input buffer."""
2424 self.buffer[:] = []
2431 self.buffer[:] = []
2425 self.buffer_raw[:] = []
2432 self.buffer_raw[:] = []
2426 self.input_splitter.reset()
2433 self.input_splitter.reset()
2427
2434
2428 # For backwards compatibility
2435 # For backwards compatibility
2429 resetbuffer = reset_buffer
2436 resetbuffer = reset_buffer
2430
2437
2431 def _is_secondary_block_start(self, s):
2438 def _is_secondary_block_start(self, s):
2432 if not s.endswith(':'):
2439 if not s.endswith(':'):
2433 return False
2440 return False
2434 if (s.startswith('elif') or
2441 if (s.startswith('elif') or
2435 s.startswith('else') or
2442 s.startswith('else') or
2436 s.startswith('except') or
2443 s.startswith('except') or
2437 s.startswith('finally')):
2444 s.startswith('finally')):
2438 return True
2445 return True
2439
2446
2440 def _cleanup_ipy_script(self, script):
2447 def _cleanup_ipy_script(self, script):
2441 """Make a script safe for self.runlines()
2448 """Make a script safe for self.runlines()
2442
2449
2443 Currently, IPython is lines based, with blocks being detected by
2450 Currently, IPython is lines based, with blocks being detected by
2444 empty lines. This is a problem for block based scripts that may
2451 empty lines. This is a problem for block based scripts that may
2445 not have empty lines after blocks. This script adds those empty
2452 not have empty lines after blocks. This script adds those empty
2446 lines to make scripts safe for running in the current line based
2453 lines to make scripts safe for running in the current line based
2447 IPython.
2454 IPython.
2448 """
2455 """
2449 res = []
2456 res = []
2450 lines = script.splitlines()
2457 lines = script.splitlines()
2451 level = 0
2458 level = 0
2452
2459
2453 for l in lines:
2460 for l in lines:
2454 lstripped = l.lstrip()
2461 lstripped = l.lstrip()
2455 stripped = l.strip()
2462 stripped = l.strip()
2456 if not stripped:
2463 if not stripped:
2457 continue
2464 continue
2458 newlevel = len(l) - len(lstripped)
2465 newlevel = len(l) - len(lstripped)
2459 if level > 0 and newlevel == 0 and \
2466 if level > 0 and newlevel == 0 and \
2460 not self._is_secondary_block_start(stripped):
2467 not self._is_secondary_block_start(stripped):
2461 # add empty line
2468 # add empty line
2462 res.append('')
2469 res.append('')
2463 res.append(l)
2470 res.append(l)
2464 level = newlevel
2471 level = newlevel
2465
2472
2466 return '\n'.join(res) + '\n'
2473 return '\n'.join(res) + '\n'
2467
2474
2468 #-------------------------------------------------------------------------
2475 #-------------------------------------------------------------------------
2469 # Things related to GUI support and pylab
2476 # Things related to GUI support and pylab
2470 #-------------------------------------------------------------------------
2477 #-------------------------------------------------------------------------
2471
2478
2472 def enable_pylab(self, gui=None):
2479 def enable_pylab(self, gui=None):
2473 raise NotImplementedError('Implement enable_pylab in a subclass')
2480 raise NotImplementedError('Implement enable_pylab in a subclass')
2474
2481
2475 #-------------------------------------------------------------------------
2482 #-------------------------------------------------------------------------
2476 # Utilities
2483 # Utilities
2477 #-------------------------------------------------------------------------
2484 #-------------------------------------------------------------------------
2478
2485
2479 def var_expand(self,cmd,depth=0):
2486 def var_expand(self,cmd,depth=0):
2480 """Expand python variables in a string.
2487 """Expand python variables in a string.
2481
2488
2482 The depth argument indicates how many frames above the caller should
2489 The depth argument indicates how many frames above the caller should
2483 be walked to look for the local namespace where to expand variables.
2490 be walked to look for the local namespace where to expand variables.
2484
2491
2485 The global namespace for expansion is always the user's interactive
2492 The global namespace for expansion is always the user's interactive
2486 namespace.
2493 namespace.
2487 """
2494 """
2488 res = ItplNS(cmd, self.user_ns, # globals
2495 res = ItplNS(cmd, self.user_ns, # globals
2489 # Skip our own frame in searching for locals:
2496 # Skip our own frame in searching for locals:
2490 sys._getframe(depth+1).f_locals # locals
2497 sys._getframe(depth+1).f_locals # locals
2491 )
2498 )
2492 return str(res).decode(res.codec)
2499 return str(res).decode(res.codec)
2493
2500
2494 def mktempfile(self, data=None, prefix='ipython_edit_'):
2501 def mktempfile(self, data=None, prefix='ipython_edit_'):
2495 """Make a new tempfile and return its filename.
2502 """Make a new tempfile and return its filename.
2496
2503
2497 This makes a call to tempfile.mktemp, but it registers the created
2504 This makes a call to tempfile.mktemp, but it registers the created
2498 filename internally so ipython cleans it up at exit time.
2505 filename internally so ipython cleans it up at exit time.
2499
2506
2500 Optional inputs:
2507 Optional inputs:
2501
2508
2502 - data(None): if data is given, it gets written out to the temp file
2509 - data(None): if data is given, it gets written out to the temp file
2503 immediately, and the file is closed again."""
2510 immediately, and the file is closed again."""
2504
2511
2505 filename = tempfile.mktemp('.py', prefix)
2512 filename = tempfile.mktemp('.py', prefix)
2506 self.tempfiles.append(filename)
2513 self.tempfiles.append(filename)
2507
2514
2508 if data:
2515 if data:
2509 tmp_file = open(filename,'w')
2516 tmp_file = open(filename,'w')
2510 tmp_file.write(data)
2517 tmp_file.write(data)
2511 tmp_file.close()
2518 tmp_file.close()
2512 return filename
2519 return filename
2513
2520
2514 # TODO: This should be removed when Term is refactored.
2521 # TODO: This should be removed when Term is refactored.
2515 def write(self,data):
2522 def write(self,data):
2516 """Write a string to the default output"""
2523 """Write a string to the default output"""
2517 io.Term.cout.write(data)
2524 io.Term.cout.write(data)
2518
2525
2519 # TODO: This should be removed when Term is refactored.
2526 # TODO: This should be removed when Term is refactored.
2520 def write_err(self,data):
2527 def write_err(self,data):
2521 """Write a string to the default error output"""
2528 """Write a string to the default error output"""
2522 io.Term.cerr.write(data)
2529 io.Term.cerr.write(data)
2523
2530
2524 def ask_yes_no(self,prompt,default=True):
2531 def ask_yes_no(self,prompt,default=True):
2525 if self.quiet:
2532 if self.quiet:
2526 return True
2533 return True
2527 return ask_yes_no(prompt,default)
2534 return ask_yes_no(prompt,default)
2528
2535
2529 def show_usage(self):
2536 def show_usage(self):
2530 """Show a usage message"""
2537 """Show a usage message"""
2531 page.page(IPython.core.usage.interactive_usage)
2538 page.page(IPython.core.usage.interactive_usage)
2532
2539
2533 def find_user_code(self, target, raw=True):
2540 def find_user_code(self, target, raw=True):
2534 """Get a code string from history, file, or a string or macro.
2541 """Get a code string from history, file, or a string or macro.
2535
2542
2536 This is mainly used by magic functions.
2543 This is mainly used by magic functions.
2537
2544
2538 Parameters
2545 Parameters
2539 ----------
2546 ----------
2540 target : str
2547 target : str
2541 A string specifying code to retrieve. This will be tried respectively
2548 A string specifying code to retrieve. This will be tried respectively
2542 as: ranges of input history (see %history for syntax), a filename, or
2549 as: ranges of input history (see %history for syntax), a filename, or
2543 an expression evaluating to a string or Macro in the user namespace.
2550 an expression evaluating to a string or Macro in the user namespace.
2544 raw : bool
2551 raw : bool
2545 If true (default), retrieve raw history. Has no effect on the other
2552 If true (default), retrieve raw history. Has no effect on the other
2546 retrieval mechanisms.
2553 retrieval mechanisms.
2547
2554
2548 Returns
2555 Returns
2549 -------
2556 -------
2550 A string of code.
2557 A string of code.
2551
2558
2552 ValueError is raised if nothing is found, and TypeError if it evaluates
2559 ValueError is raised if nothing is found, and TypeError if it evaluates
2553 to an object of another type. In each case, .args[0] is a printable
2560 to an object of another type. In each case, .args[0] is a printable
2554 message.
2561 message.
2555 """
2562 """
2556 code = self.extract_input_lines(target, raw=raw) # Grab history
2563 code = self.extract_input_lines(target, raw=raw) # Grab history
2557 if code:
2564 if code:
2558 return code
2565 return code
2559 if os.path.isfile(target): # Read file
2566 if os.path.isfile(target): # Read file
2560 return open(target, "r").read()
2567 return open(target, "r").read()
2561
2568
2562 try: # User namespace
2569 try: # User namespace
2563 codeobj = eval(target, self.user_ns)
2570 codeobj = eval(target, self.user_ns)
2564 except Exception:
2571 except Exception:
2565 raise ValueError(("'%s' was not found in history, as a file, nor in"
2572 raise ValueError(("'%s' was not found in history, as a file, nor in"
2566 " the user namespace.") % target)
2573 " the user namespace.") % target)
2567 if isinstance(codeobj, basestring):
2574 if isinstance(codeobj, basestring):
2568 return codeobj
2575 return codeobj
2569 elif isinstance(codeobj, Macro):
2576 elif isinstance(codeobj, Macro):
2570 return codeobj.value
2577 return codeobj.value
2571
2578
2572 raise TypeError("%s is neither a string nor a macro." % target,
2579 raise TypeError("%s is neither a string nor a macro." % target,
2573 codeobj)
2580 codeobj)
2574
2581
2575 #-------------------------------------------------------------------------
2582 #-------------------------------------------------------------------------
2576 # Things related to IPython exiting
2583 # Things related to IPython exiting
2577 #-------------------------------------------------------------------------
2584 #-------------------------------------------------------------------------
2578 def atexit_operations(self):
2585 def atexit_operations(self):
2579 """This will be executed at the time of exit.
2586 """This will be executed at the time of exit.
2580
2587
2581 Cleanup operations and saving of persistent data that is done
2588 Cleanup operations and saving of persistent data that is done
2582 unconditionally by IPython should be performed here.
2589 unconditionally by IPython should be performed here.
2583
2590
2584 For things that may depend on startup flags or platform specifics (such
2591 For things that may depend on startup flags or platform specifics (such
2585 as having readline or not), register a separate atexit function in the
2592 as having readline or not), register a separate atexit function in the
2586 code that has the appropriate information, rather than trying to
2593 code that has the appropriate information, rather than trying to
2587 clutter
2594 clutter
2588 """
2595 """
2589 # Cleanup all tempfiles left around
2596 # Cleanup all tempfiles left around
2590 for tfile in self.tempfiles:
2597 for tfile in self.tempfiles:
2591 try:
2598 try:
2592 os.unlink(tfile)
2599 os.unlink(tfile)
2593 except OSError:
2600 except OSError:
2594 pass
2601 pass
2595
2602
2596 # Close the history session (this stores the end time and line count)
2603 # Close the history session (this stores the end time and line count)
2597 self.history_manager.end_session()
2604 self.history_manager.end_session()
2598
2605
2599 # Clear all user namespaces to release all references cleanly.
2606 # Clear all user namespaces to release all references cleanly.
2600 self.reset(new_session=False)
2607 self.reset(new_session=False)
2601
2608
2602 # Run user hooks
2609 # Run user hooks
2603 self.hooks.shutdown_hook()
2610 self.hooks.shutdown_hook()
2604
2611
2605 def cleanup(self):
2612 def cleanup(self):
2606 self.restore_sys_module_state()
2613 self.restore_sys_module_state()
2607
2614
2608
2615
2609 class InteractiveShellABC(object):
2616 class InteractiveShellABC(object):
2610 """An abstract base class for InteractiveShell."""
2617 """An abstract base class for InteractiveShell."""
2611 __metaclass__ = abc.ABCMeta
2618 __metaclass__ = abc.ABCMeta
2612
2619
2613 InteractiveShellABC.register(InteractiveShell)
2620 InteractiveShellABC.register(InteractiveShell)
@@ -1,3472 +1,3476 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #-----------------------------------------------------------------------------
5 #-----------------------------------------------------------------------------
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2007 Fernando Perez <fperez@colorado.edu>
8 # Copyright (C) 2008-2009 The IPython Development Team
8 # Copyright (C) 2008-2009 The IPython Development Team
9
9
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 import __builtin__
18 import __builtin__
19 import __future__
19 import __future__
20 import bdb
20 import bdb
21 import inspect
21 import inspect
22 import os
22 import os
23 import sys
23 import sys
24 import shutil
24 import shutil
25 import re
25 import re
26 import time
26 import time
27 import textwrap
27 import textwrap
28 from cStringIO import StringIO
28 from cStringIO import StringIO
29 from getopt import getopt,GetoptError
29 from getopt import getopt,GetoptError
30 from pprint import pformat
30 from pprint import pformat
31 from xmlrpclib import ServerProxy
31 from xmlrpclib import ServerProxy
32
32
33 # cProfile was added in Python2.5
33 # cProfile was added in Python2.5
34 try:
34 try:
35 import cProfile as profile
35 import cProfile as profile
36 import pstats
36 import pstats
37 except ImportError:
37 except ImportError:
38 # profile isn't bundled by default in Debian for license reasons
38 # profile isn't bundled by default in Debian for license reasons
39 try:
39 try:
40 import profile,pstats
40 import profile,pstats
41 except ImportError:
41 except ImportError:
42 profile = pstats = None
42 profile = pstats = None
43
43
44 import IPython
44 import IPython
45 from IPython.core import debugger, oinspect
45 from IPython.core import debugger, oinspect
46 from IPython.core.error import TryNext
46 from IPython.core.error import TryNext
47 from IPython.core.error import UsageError
47 from IPython.core.error import UsageError
48 from IPython.core.fakemodule import FakeModule
48 from IPython.core.fakemodule import FakeModule
49 from IPython.core.macro import Macro
49 from IPython.core.macro import Macro
50 from IPython.core import page
50 from IPython.core import page
51 from IPython.core.prefilter import ESC_MAGIC
51 from IPython.core.prefilter import ESC_MAGIC
52 from IPython.lib.pylabtools import mpl_runner
52 from IPython.lib.pylabtools import mpl_runner
53 from IPython.external.Itpl import itpl, printpl
53 from IPython.external.Itpl import itpl, printpl
54 from IPython.testing import decorators as testdec
54 from IPython.testing import decorators as testdec
55 from IPython.utils.io import file_read, nlprint
55 from IPython.utils.io import file_read, nlprint
56 import IPython.utils.io
56 import IPython.utils.io
57 from IPython.utils.path import get_py_filename
57 from IPython.utils.path import get_py_filename
58 from IPython.utils.process import arg_split, abbrev_cwd
58 from IPython.utils.process import arg_split, abbrev_cwd
59 from IPython.utils.terminal import set_term_title
59 from IPython.utils.terminal import set_term_title
60 from IPython.utils.text import LSString, SList, format_screen
60 from IPython.utils.text import LSString, SList, format_screen
61 from IPython.utils.timing import clock, clock2
61 from IPython.utils.timing import clock, clock2
62 from IPython.utils.warn import warn, error
62 from IPython.utils.warn import warn, error
63 from IPython.utils.ipstruct import Struct
63 from IPython.utils.ipstruct import Struct
64 import IPython.utils.generics
64 import IPython.utils.generics
65
65
66 #-----------------------------------------------------------------------------
66 #-----------------------------------------------------------------------------
67 # Utility functions
67 # Utility functions
68 #-----------------------------------------------------------------------------
68 #-----------------------------------------------------------------------------
69
69
70 def on_off(tag):
70 def on_off(tag):
71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
72 return ['OFF','ON'][tag]
72 return ['OFF','ON'][tag]
73
73
74 class Bunch: pass
74 class Bunch: pass
75
75
76 def compress_dhist(dh):
76 def compress_dhist(dh):
77 head, tail = dh[:-10], dh[-10:]
77 head, tail = dh[:-10], dh[-10:]
78
78
79 newhead = []
79 newhead = []
80 done = set()
80 done = set()
81 for h in head:
81 for h in head:
82 if h in done:
82 if h in done:
83 continue
83 continue
84 newhead.append(h)
84 newhead.append(h)
85 done.add(h)
85 done.add(h)
86
86
87 return newhead + tail
87 return newhead + tail
88
88
89 def needs_local_scope(func):
89 def needs_local_scope(func):
90 """Decorator to mark magic functions which need to local scope to run."""
90 """Decorator to mark magic functions which need to local scope to run."""
91 func.needs_local_scope = True
91 func.needs_local_scope = True
92 return func
92 return func
93
93
94 #***************************************************************************
94 #***************************************************************************
95 # Main class implementing Magic functionality
95 # Main class implementing Magic functionality
96
96
97 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
97 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
98 # on construction of the main InteractiveShell object. Something odd is going
98 # on construction of the main InteractiveShell object. Something odd is going
99 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
99 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
100 # eventually this needs to be clarified.
100 # eventually this needs to be clarified.
101 # BG: This is because InteractiveShell inherits from this, but is itself a
101 # BG: This is because InteractiveShell inherits from this, but is itself a
102 # Configurable. This messes up the MRO in some way. The fix is that we need to
102 # Configurable. This messes up the MRO in some way. The fix is that we need to
103 # make Magic a configurable that InteractiveShell does not subclass.
103 # make Magic a configurable that InteractiveShell does not subclass.
104
104
105 class Magic:
105 class Magic:
106 """Magic functions for InteractiveShell.
106 """Magic functions for InteractiveShell.
107
107
108 Shell functions which can be reached as %function_name. All magic
108 Shell functions which can be reached as %function_name. All magic
109 functions should accept a string, which they can parse for their own
109 functions should accept a string, which they can parse for their own
110 needs. This can make some functions easier to type, eg `%cd ../`
110 needs. This can make some functions easier to type, eg `%cd ../`
111 vs. `%cd("../")`
111 vs. `%cd("../")`
112
112
113 ALL definitions MUST begin with the prefix magic_. The user won't need it
113 ALL definitions MUST begin with the prefix magic_. The user won't need it
114 at the command line, but it is is needed in the definition. """
114 at the command line, but it is is needed in the definition. """
115
115
116 # class globals
116 # class globals
117 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
117 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
118 'Automagic is ON, % prefix NOT needed for magic functions.']
118 'Automagic is ON, % prefix NOT needed for magic functions.']
119
119
120 #......................................................................
120 #......................................................................
121 # some utility functions
121 # some utility functions
122
122
123 def __init__(self,shell):
123 def __init__(self,shell):
124
124
125 self.options_table = {}
125 self.options_table = {}
126 if profile is None:
126 if profile is None:
127 self.magic_prun = self.profile_missing_notice
127 self.magic_prun = self.profile_missing_notice
128 self.shell = shell
128 self.shell = shell
129
129
130 # namespace for holding state we may need
130 # namespace for holding state we may need
131 self._magic_state = Bunch()
131 self._magic_state = Bunch()
132
132
133 def profile_missing_notice(self, *args, **kwargs):
133 def profile_missing_notice(self, *args, **kwargs):
134 error("""\
134 error("""\
135 The profile module could not be found. It has been removed from the standard
135 The profile module could not be found. It has been removed from the standard
136 python packages because of its non-free license. To use profiling, install the
136 python packages because of its non-free license. To use profiling, install the
137 python-profiler package from non-free.""")
137 python-profiler package from non-free.""")
138
138
139 def default_option(self,fn,optstr):
139 def default_option(self,fn,optstr):
140 """Make an entry in the options_table for fn, with value optstr"""
140 """Make an entry in the options_table for fn, with value optstr"""
141
141
142 if fn not in self.lsmagic():
142 if fn not in self.lsmagic():
143 error("%s is not a magic function" % fn)
143 error("%s is not a magic function" % fn)
144 self.options_table[fn] = optstr
144 self.options_table[fn] = optstr
145
145
146 def lsmagic(self):
146 def lsmagic(self):
147 """Return a list of currently available magic functions.
147 """Return a list of currently available magic functions.
148
148
149 Gives a list of the bare names after mangling (['ls','cd', ...], not
149 Gives a list of the bare names after mangling (['ls','cd', ...], not
150 ['magic_ls','magic_cd',...]"""
150 ['magic_ls','magic_cd',...]"""
151
151
152 # FIXME. This needs a cleanup, in the way the magics list is built.
152 # FIXME. This needs a cleanup, in the way the magics list is built.
153
153
154 # magics in class definition
154 # magics in class definition
155 class_magic = lambda fn: fn.startswith('magic_') and \
155 class_magic = lambda fn: fn.startswith('magic_') and \
156 callable(Magic.__dict__[fn])
156 callable(Magic.__dict__[fn])
157 # in instance namespace (run-time user additions)
157 # in instance namespace (run-time user additions)
158 inst_magic = lambda fn: fn.startswith('magic_') and \
158 inst_magic = lambda fn: fn.startswith('magic_') and \
159 callable(self.__dict__[fn])
159 callable(self.__dict__[fn])
160 # and bound magics by user (so they can access self):
160 # and bound magics by user (so they can access self):
161 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
161 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
162 callable(self.__class__.__dict__[fn])
162 callable(self.__class__.__dict__[fn])
163 magics = filter(class_magic,Magic.__dict__.keys()) + \
163 magics = filter(class_magic,Magic.__dict__.keys()) + \
164 filter(inst_magic,self.__dict__.keys()) + \
164 filter(inst_magic,self.__dict__.keys()) + \
165 filter(inst_bound_magic,self.__class__.__dict__.keys())
165 filter(inst_bound_magic,self.__class__.__dict__.keys())
166 out = []
166 out = []
167 for fn in set(magics):
167 for fn in set(magics):
168 out.append(fn.replace('magic_','',1))
168 out.append(fn.replace('magic_','',1))
169 out.sort()
169 out.sort()
170 return out
170 return out
171
171
172 def extract_input_lines(self, range_str, raw=False):
172 def extract_input_lines(self, range_str, raw=False):
173 """Return as a string a set of input history slices.
173 """Return as a string a set of input history slices.
174
174
175 Inputs:
175 Inputs:
176
176
177 - range_str: the set of slices is given as a string, like
177 - range_str: the set of slices is given as a string, like
178 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
178 "~5/6-~4/2 4:8 9", since this function is for use by magic functions
179 which get their arguments as strings. The number before the / is the
179 which get their arguments as strings. The number before the / is the
180 session number: ~n goes n back from the current session.
180 session number: ~n goes n back from the current session.
181
181
182 Optional inputs:
182 Optional inputs:
183
183
184 - raw(False): by default, the processed input is used. If this is
184 - raw(False): by default, the processed input is used. If this is
185 true, the raw input history is used instead.
185 true, the raw input history is used instead.
186
186
187 Note that slices can be called with two notations:
187 Note that slices can be called with two notations:
188
188
189 N:M -> standard python form, means including items N...(M-1).
189 N:M -> standard python form, means including items N...(M-1).
190
190
191 N-M -> include items N..M (closed endpoint)."""
191 N-M -> include items N..M (closed endpoint)."""
192 lines = self.shell.history_manager.\
192 lines = self.shell.history_manager.\
193 get_range_by_str(range_str, raw=raw)
193 get_range_by_str(range_str, raw=raw)
194 return "\n".join(x for _, _, x in lines)
194 return "\n".join(x for _, _, x in lines)
195
195
196 def arg_err(self,func):
196 def arg_err(self,func):
197 """Print docstring if incorrect arguments were passed"""
197 """Print docstring if incorrect arguments were passed"""
198 print 'Error in arguments:'
198 print 'Error in arguments:'
199 print oinspect.getdoc(func)
199 print oinspect.getdoc(func)
200
200
201 def format_latex(self,strng):
201 def format_latex(self,strng):
202 """Format a string for latex inclusion."""
202 """Format a string for latex inclusion."""
203
203
204 # Characters that need to be escaped for latex:
204 # Characters that need to be escaped for latex:
205 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
205 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
206 # Magic command names as headers:
206 # Magic command names as headers:
207 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
207 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
208 re.MULTILINE)
208 re.MULTILINE)
209 # Magic commands
209 # Magic commands
210 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
210 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
211 re.MULTILINE)
211 re.MULTILINE)
212 # Paragraph continue
212 # Paragraph continue
213 par_re = re.compile(r'\\$',re.MULTILINE)
213 par_re = re.compile(r'\\$',re.MULTILINE)
214
214
215 # The "\n" symbol
215 # The "\n" symbol
216 newline_re = re.compile(r'\\n')
216 newline_re = re.compile(r'\\n')
217
217
218 # Now build the string for output:
218 # Now build the string for output:
219 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
219 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
220 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
220 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
221 strng)
221 strng)
222 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
222 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
223 strng = par_re.sub(r'\\\\',strng)
223 strng = par_re.sub(r'\\\\',strng)
224 strng = escape_re.sub(r'\\\1',strng)
224 strng = escape_re.sub(r'\\\1',strng)
225 strng = newline_re.sub(r'\\textbackslash{}n',strng)
225 strng = newline_re.sub(r'\\textbackslash{}n',strng)
226 return strng
226 return strng
227
227
228 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
228 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
229 """Parse options passed to an argument string.
229 """Parse options passed to an argument string.
230
230
231 The interface is similar to that of getopt(), but it returns back a
231 The interface is similar to that of getopt(), but it returns back a
232 Struct with the options as keys and the stripped argument string still
232 Struct with the options as keys and the stripped argument string still
233 as a string.
233 as a string.
234
234
235 arg_str is quoted as a true sys.argv vector by using shlex.split.
235 arg_str is quoted as a true sys.argv vector by using shlex.split.
236 This allows us to easily expand variables, glob files, quote
236 This allows us to easily expand variables, glob files, quote
237 arguments, etc.
237 arguments, etc.
238
238
239 Options:
239 Options:
240 -mode: default 'string'. If given as 'list', the argument string is
240 -mode: default 'string'. If given as 'list', the argument string is
241 returned as a list (split on whitespace) instead of a string.
241 returned as a list (split on whitespace) instead of a string.
242
242
243 -list_all: put all option values in lists. Normally only options
243 -list_all: put all option values in lists. Normally only options
244 appearing more than once are put in a list.
244 appearing more than once are put in a list.
245
245
246 -posix (True): whether to split the input line in POSIX mode or not,
246 -posix (True): whether to split the input line in POSIX mode or not,
247 as per the conventions outlined in the shlex module from the
247 as per the conventions outlined in the shlex module from the
248 standard library."""
248 standard library."""
249
249
250 # inject default options at the beginning of the input line
250 # inject default options at the beginning of the input line
251 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
251 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
252 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
252 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
253
253
254 mode = kw.get('mode','string')
254 mode = kw.get('mode','string')
255 if mode not in ['string','list']:
255 if mode not in ['string','list']:
256 raise ValueError,'incorrect mode given: %s' % mode
256 raise ValueError,'incorrect mode given: %s' % mode
257 # Get options
257 # Get options
258 list_all = kw.get('list_all',0)
258 list_all = kw.get('list_all',0)
259 posix = kw.get('posix', os.name == 'posix')
259 posix = kw.get('posix', os.name == 'posix')
260
260
261 # Check if we have more than one argument to warrant extra processing:
261 # Check if we have more than one argument to warrant extra processing:
262 odict = {} # Dictionary with options
262 odict = {} # Dictionary with options
263 args = arg_str.split()
263 args = arg_str.split()
264 if len(args) >= 1:
264 if len(args) >= 1:
265 # If the list of inputs only has 0 or 1 thing in it, there's no
265 # If the list of inputs only has 0 or 1 thing in it, there's no
266 # need to look for options
266 # need to look for options
267 argv = arg_split(arg_str,posix)
267 argv = arg_split(arg_str,posix)
268 # Do regular option processing
268 # Do regular option processing
269 try:
269 try:
270 opts,args = getopt(argv,opt_str,*long_opts)
270 opts,args = getopt(argv,opt_str,*long_opts)
271 except GetoptError,e:
271 except GetoptError,e:
272 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
272 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
273 " ".join(long_opts)))
273 " ".join(long_opts)))
274 for o,a in opts:
274 for o,a in opts:
275 if o.startswith('--'):
275 if o.startswith('--'):
276 o = o[2:]
276 o = o[2:]
277 else:
277 else:
278 o = o[1:]
278 o = o[1:]
279 try:
279 try:
280 odict[o].append(a)
280 odict[o].append(a)
281 except AttributeError:
281 except AttributeError:
282 odict[o] = [odict[o],a]
282 odict[o] = [odict[o],a]
283 except KeyError:
283 except KeyError:
284 if list_all:
284 if list_all:
285 odict[o] = [a]
285 odict[o] = [a]
286 else:
286 else:
287 odict[o] = a
287 odict[o] = a
288
288
289 # Prepare opts,args for return
289 # Prepare opts,args for return
290 opts = Struct(odict)
290 opts = Struct(odict)
291 if mode == 'string':
291 if mode == 'string':
292 args = ' '.join(args)
292 args = ' '.join(args)
293
293
294 return opts,args
294 return opts,args
295
295
296 #......................................................................
296 #......................................................................
297 # And now the actual magic functions
297 # And now the actual magic functions
298
298
299 # Functions for IPython shell work (vars,funcs, config, etc)
299 # Functions for IPython shell work (vars,funcs, config, etc)
300 def magic_lsmagic(self, parameter_s = ''):
300 def magic_lsmagic(self, parameter_s = ''):
301 """List currently available magic functions."""
301 """List currently available magic functions."""
302 mesc = ESC_MAGIC
302 mesc = ESC_MAGIC
303 print 'Available magic functions:\n'+mesc+\
303 print 'Available magic functions:\n'+mesc+\
304 (' '+mesc).join(self.lsmagic())
304 (' '+mesc).join(self.lsmagic())
305 print '\n' + Magic.auto_status[self.shell.automagic]
305 print '\n' + Magic.auto_status[self.shell.automagic]
306 return None
306 return None
307
307
308 def magic_magic(self, parameter_s = ''):
308 def magic_magic(self, parameter_s = ''):
309 """Print information about the magic function system.
309 """Print information about the magic function system.
310
310
311 Supported formats: -latex, -brief, -rest
311 Supported formats: -latex, -brief, -rest
312 """
312 """
313
313
314 mode = ''
314 mode = ''
315 try:
315 try:
316 if parameter_s.split()[0] == '-latex':
316 if parameter_s.split()[0] == '-latex':
317 mode = 'latex'
317 mode = 'latex'
318 if parameter_s.split()[0] == '-brief':
318 if parameter_s.split()[0] == '-brief':
319 mode = 'brief'
319 mode = 'brief'
320 if parameter_s.split()[0] == '-rest':
320 if parameter_s.split()[0] == '-rest':
321 mode = 'rest'
321 mode = 'rest'
322 rest_docs = []
322 rest_docs = []
323 except:
323 except:
324 pass
324 pass
325
325
326 magic_docs = []
326 magic_docs = []
327 for fname in self.lsmagic():
327 for fname in self.lsmagic():
328 mname = 'magic_' + fname
328 mname = 'magic_' + fname
329 for space in (Magic,self,self.__class__):
329 for space in (Magic,self,self.__class__):
330 try:
330 try:
331 fn = space.__dict__[mname]
331 fn = space.__dict__[mname]
332 except KeyError:
332 except KeyError:
333 pass
333 pass
334 else:
334 else:
335 break
335 break
336 if mode == 'brief':
336 if mode == 'brief':
337 # only first line
337 # only first line
338 if fn.__doc__:
338 if fn.__doc__:
339 fndoc = fn.__doc__.split('\n',1)[0]
339 fndoc = fn.__doc__.split('\n',1)[0]
340 else:
340 else:
341 fndoc = 'No documentation'
341 fndoc = 'No documentation'
342 else:
342 else:
343 if fn.__doc__:
343 if fn.__doc__:
344 fndoc = fn.__doc__.rstrip()
344 fndoc = fn.__doc__.rstrip()
345 else:
345 else:
346 fndoc = 'No documentation'
346 fndoc = 'No documentation'
347
347
348
348
349 if mode == 'rest':
349 if mode == 'rest':
350 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
350 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
351 fname,fndoc))
351 fname,fndoc))
352
352
353 else:
353 else:
354 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
354 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
355 fname,fndoc))
355 fname,fndoc))
356
356
357 magic_docs = ''.join(magic_docs)
357 magic_docs = ''.join(magic_docs)
358
358
359 if mode == 'rest':
359 if mode == 'rest':
360 return "".join(rest_docs)
360 return "".join(rest_docs)
361
361
362 if mode == 'latex':
362 if mode == 'latex':
363 print self.format_latex(magic_docs)
363 print self.format_latex(magic_docs)
364 return
364 return
365 else:
365 else:
366 magic_docs = format_screen(magic_docs)
366 magic_docs = format_screen(magic_docs)
367 if mode == 'brief':
367 if mode == 'brief':
368 return magic_docs
368 return magic_docs
369
369
370 outmsg = """
370 outmsg = """
371 IPython's 'magic' functions
371 IPython's 'magic' functions
372 ===========================
372 ===========================
373
373
374 The magic function system provides a series of functions which allow you to
374 The magic function system provides a series of functions which allow you to
375 control the behavior of IPython itself, plus a lot of system-type
375 control the behavior of IPython itself, plus a lot of system-type
376 features. All these functions are prefixed with a % character, but parameters
376 features. All these functions are prefixed with a % character, but parameters
377 are given without parentheses or quotes.
377 are given without parentheses or quotes.
378
378
379 NOTE: If you have 'automagic' enabled (via the command line option or with the
379 NOTE: If you have 'automagic' enabled (via the command line option or with the
380 %automagic function), you don't need to type in the % explicitly. By default,
380 %automagic function), you don't need to type in the % explicitly. By default,
381 IPython ships with automagic on, so you should only rarely need the % escape.
381 IPython ships with automagic on, so you should only rarely need the % escape.
382
382
383 Example: typing '%cd mydir' (without the quotes) changes you working directory
383 Example: typing '%cd mydir' (without the quotes) changes you working directory
384 to 'mydir', if it exists.
384 to 'mydir', if it exists.
385
385
386 You can define your own magic functions to extend the system. See the supplied
386 You can define your own magic functions to extend the system. See the supplied
387 ipythonrc and example-magic.py files for details (in your ipython
387 ipythonrc and example-magic.py files for details (in your ipython
388 configuration directory, typically $HOME/.config/ipython on Linux or $HOME/.ipython elsewhere).
388 configuration directory, typically $HOME/.config/ipython on Linux or $HOME/.ipython elsewhere).
389
389
390 You can also define your own aliased names for magic functions. In your
390 You can also define your own aliased names for magic functions. In your
391 ipythonrc file, placing a line like:
391 ipythonrc file, placing a line like:
392
392
393 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
393 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
394
394
395 will define %pf as a new name for %profile.
395 will define %pf as a new name for %profile.
396
396
397 You can also call magics in code using the magic() function, which IPython
397 You can also call magics in code using the magic() function, which IPython
398 automatically adds to the builtin namespace. Type 'magic?' for details.
398 automatically adds to the builtin namespace. Type 'magic?' for details.
399
399
400 For a list of the available magic functions, use %lsmagic. For a description
400 For a list of the available magic functions, use %lsmagic. For a description
401 of any of them, type %magic_name?, e.g. '%cd?'.
401 of any of them, type %magic_name?, e.g. '%cd?'.
402
402
403 Currently the magic system has the following functions:\n"""
403 Currently the magic system has the following functions:\n"""
404
404
405 mesc = ESC_MAGIC
405 mesc = ESC_MAGIC
406 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
406 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
407 "\n\n%s%s\n\n%s" % (outmsg,
407 "\n\n%s%s\n\n%s" % (outmsg,
408 magic_docs,mesc,mesc,
408 magic_docs,mesc,mesc,
409 (' '+mesc).join(self.lsmagic()),
409 (' '+mesc).join(self.lsmagic()),
410 Magic.auto_status[self.shell.automagic] ) )
410 Magic.auto_status[self.shell.automagic] ) )
411 page.page(outmsg)
411 page.page(outmsg)
412
412
413 def magic_automagic(self, parameter_s = ''):
413 def magic_automagic(self, parameter_s = ''):
414 """Make magic functions callable without having to type the initial %.
414 """Make magic functions callable without having to type the initial %.
415
415
416 Without argumentsl toggles on/off (when off, you must call it as
416 Without argumentsl toggles on/off (when off, you must call it as
417 %automagic, of course). With arguments it sets the value, and you can
417 %automagic, of course). With arguments it sets the value, and you can
418 use any of (case insensitive):
418 use any of (case insensitive):
419
419
420 - on,1,True: to activate
420 - on,1,True: to activate
421
421
422 - off,0,False: to deactivate.
422 - off,0,False: to deactivate.
423
423
424 Note that magic functions have lowest priority, so if there's a
424 Note that magic functions have lowest priority, so if there's a
425 variable whose name collides with that of a magic fn, automagic won't
425 variable whose name collides with that of a magic fn, automagic won't
426 work for that function (you get the variable instead). However, if you
426 work for that function (you get the variable instead). However, if you
427 delete the variable (del var), the previously shadowed magic function
427 delete the variable (del var), the previously shadowed magic function
428 becomes visible to automagic again."""
428 becomes visible to automagic again."""
429
429
430 arg = parameter_s.lower()
430 arg = parameter_s.lower()
431 if parameter_s in ('on','1','true'):
431 if parameter_s in ('on','1','true'):
432 self.shell.automagic = True
432 self.shell.automagic = True
433 elif parameter_s in ('off','0','false'):
433 elif parameter_s in ('off','0','false'):
434 self.shell.automagic = False
434 self.shell.automagic = False
435 else:
435 else:
436 self.shell.automagic = not self.shell.automagic
436 self.shell.automagic = not self.shell.automagic
437 print '\n' + Magic.auto_status[self.shell.automagic]
437 print '\n' + Magic.auto_status[self.shell.automagic]
438
438
439 @testdec.skip_doctest
439 @testdec.skip_doctest
440 def magic_autocall(self, parameter_s = ''):
440 def magic_autocall(self, parameter_s = ''):
441 """Make functions callable without having to type parentheses.
441 """Make functions callable without having to type parentheses.
442
442
443 Usage:
443 Usage:
444
444
445 %autocall [mode]
445 %autocall [mode]
446
446
447 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
447 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
448 value is toggled on and off (remembering the previous state).
448 value is toggled on and off (remembering the previous state).
449
449
450 In more detail, these values mean:
450 In more detail, these values mean:
451
451
452 0 -> fully disabled
452 0 -> fully disabled
453
453
454 1 -> active, but do not apply if there are no arguments on the line.
454 1 -> active, but do not apply if there are no arguments on the line.
455
455
456 In this mode, you get:
456 In this mode, you get:
457
457
458 In [1]: callable
458 In [1]: callable
459 Out[1]: <built-in function callable>
459 Out[1]: <built-in function callable>
460
460
461 In [2]: callable 'hello'
461 In [2]: callable 'hello'
462 ------> callable('hello')
462 ------> callable('hello')
463 Out[2]: False
463 Out[2]: False
464
464
465 2 -> Active always. Even if no arguments are present, the callable
465 2 -> Active always. Even if no arguments are present, the callable
466 object is called:
466 object is called:
467
467
468 In [2]: float
468 In [2]: float
469 ------> float()
469 ------> float()
470 Out[2]: 0.0
470 Out[2]: 0.0
471
471
472 Note that even with autocall off, you can still use '/' at the start of
472 Note that even with autocall off, you can still use '/' at the start of
473 a line to treat the first argument on the command line as a function
473 a line to treat the first argument on the command line as a function
474 and add parentheses to it:
474 and add parentheses to it:
475
475
476 In [8]: /str 43
476 In [8]: /str 43
477 ------> str(43)
477 ------> str(43)
478 Out[8]: '43'
478 Out[8]: '43'
479
479
480 # all-random (note for auto-testing)
480 # all-random (note for auto-testing)
481 """
481 """
482
482
483 if parameter_s:
483 if parameter_s:
484 arg = int(parameter_s)
484 arg = int(parameter_s)
485 else:
485 else:
486 arg = 'toggle'
486 arg = 'toggle'
487
487
488 if not arg in (0,1,2,'toggle'):
488 if not arg in (0,1,2,'toggle'):
489 error('Valid modes: (0->Off, 1->Smart, 2->Full')
489 error('Valid modes: (0->Off, 1->Smart, 2->Full')
490 return
490 return
491
491
492 if arg in (0,1,2):
492 if arg in (0,1,2):
493 self.shell.autocall = arg
493 self.shell.autocall = arg
494 else: # toggle
494 else: # toggle
495 if self.shell.autocall:
495 if self.shell.autocall:
496 self._magic_state.autocall_save = self.shell.autocall
496 self._magic_state.autocall_save = self.shell.autocall
497 self.shell.autocall = 0
497 self.shell.autocall = 0
498 else:
498 else:
499 try:
499 try:
500 self.shell.autocall = self._magic_state.autocall_save
500 self.shell.autocall = self._magic_state.autocall_save
501 except AttributeError:
501 except AttributeError:
502 self.shell.autocall = self._magic_state.autocall_save = 1
502 self.shell.autocall = self._magic_state.autocall_save = 1
503
503
504 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
504 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
505
505
506
506
507 def magic_page(self, parameter_s=''):
507 def magic_page(self, parameter_s=''):
508 """Pretty print the object and display it through a pager.
508 """Pretty print the object and display it through a pager.
509
509
510 %page [options] OBJECT
510 %page [options] OBJECT
511
511
512 If no object is given, use _ (last output).
512 If no object is given, use _ (last output).
513
513
514 Options:
514 Options:
515
515
516 -r: page str(object), don't pretty-print it."""
516 -r: page str(object), don't pretty-print it."""
517
517
518 # After a function contributed by Olivier Aubert, slightly modified.
518 # After a function contributed by Olivier Aubert, slightly modified.
519
519
520 # Process options/args
520 # Process options/args
521 opts,args = self.parse_options(parameter_s,'r')
521 opts,args = self.parse_options(parameter_s,'r')
522 raw = 'r' in opts
522 raw = 'r' in opts
523
523
524 oname = args and args or '_'
524 oname = args and args or '_'
525 info = self._ofind(oname)
525 info = self._ofind(oname)
526 if info['found']:
526 if info['found']:
527 txt = (raw and str or pformat)( info['obj'] )
527 txt = (raw and str or pformat)( info['obj'] )
528 page.page(txt)
528 page.page(txt)
529 else:
529 else:
530 print 'Object `%s` not found' % oname
530 print 'Object `%s` not found' % oname
531
531
532 def magic_profile(self, parameter_s=''):
532 def magic_profile(self, parameter_s=''):
533 """Print your currently active IPython profile."""
533 """Print your currently active IPython profile."""
534 if self.shell.profile:
534 if self.shell.profile:
535 printpl('Current IPython profile: $self.shell.profile.')
535 printpl('Current IPython profile: $self.shell.profile.')
536 else:
536 else:
537 print 'No profile active.'
537 print 'No profile active.'
538
538
539 def magic_pinfo(self, parameter_s='', namespaces=None):
539 def magic_pinfo(self, parameter_s='', namespaces=None):
540 """Provide detailed information about an object.
540 """Provide detailed information about an object.
541
541
542 '%pinfo object' is just a synonym for object? or ?object."""
542 '%pinfo object' is just a synonym for object? or ?object."""
543
543
544 #print 'pinfo par: <%s>' % parameter_s # dbg
544 #print 'pinfo par: <%s>' % parameter_s # dbg
545
545
546
546
547 # detail_level: 0 -> obj? , 1 -> obj??
547 # detail_level: 0 -> obj? , 1 -> obj??
548 detail_level = 0
548 detail_level = 0
549 # We need to detect if we got called as 'pinfo pinfo foo', which can
549 # We need to detect if we got called as 'pinfo pinfo foo', which can
550 # happen if the user types 'pinfo foo?' at the cmd line.
550 # happen if the user types 'pinfo foo?' at the cmd line.
551 pinfo,qmark1,oname,qmark2 = \
551 pinfo,qmark1,oname,qmark2 = \
552 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
552 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
553 if pinfo or qmark1 or qmark2:
553 if pinfo or qmark1 or qmark2:
554 detail_level = 1
554 detail_level = 1
555 if "*" in oname:
555 if "*" in oname:
556 self.magic_psearch(oname)
556 self.magic_psearch(oname)
557 else:
557 else:
558 self.shell._inspect('pinfo', oname, detail_level=detail_level,
558 self.shell._inspect('pinfo', oname, detail_level=detail_level,
559 namespaces=namespaces)
559 namespaces=namespaces)
560
560
561 def magic_pinfo2(self, parameter_s='', namespaces=None):
561 def magic_pinfo2(self, parameter_s='', namespaces=None):
562 """Provide extra detailed information about an object.
562 """Provide extra detailed information about an object.
563
563
564 '%pinfo2 object' is just a synonym for object?? or ??object."""
564 '%pinfo2 object' is just a synonym for object?? or ??object."""
565 self.shell._inspect('pinfo', parameter_s, detail_level=1,
565 self.shell._inspect('pinfo', parameter_s, detail_level=1,
566 namespaces=namespaces)
566 namespaces=namespaces)
567
567
568 @testdec.skip_doctest
568 @testdec.skip_doctest
569 def magic_pdef(self, parameter_s='', namespaces=None):
569 def magic_pdef(self, parameter_s='', namespaces=None):
570 """Print the definition header for any callable object.
570 """Print the definition header for any callable object.
571
571
572 If the object is a class, print the constructor information.
572 If the object is a class, print the constructor information.
573
573
574 Examples
574 Examples
575 --------
575 --------
576 ::
576 ::
577
577
578 In [3]: %pdef urllib.urlopen
578 In [3]: %pdef urllib.urlopen
579 urllib.urlopen(url, data=None, proxies=None)
579 urllib.urlopen(url, data=None, proxies=None)
580 """
580 """
581 self._inspect('pdef',parameter_s, namespaces)
581 self._inspect('pdef',parameter_s, namespaces)
582
582
583 def magic_pdoc(self, parameter_s='', namespaces=None):
583 def magic_pdoc(self, parameter_s='', namespaces=None):
584 """Print the docstring for an object.
584 """Print the docstring for an object.
585
585
586 If the given object is a class, it will print both the class and the
586 If the given object is a class, it will print both the class and the
587 constructor docstrings."""
587 constructor docstrings."""
588 self._inspect('pdoc',parameter_s, namespaces)
588 self._inspect('pdoc',parameter_s, namespaces)
589
589
590 def magic_psource(self, parameter_s='', namespaces=None):
590 def magic_psource(self, parameter_s='', namespaces=None):
591 """Print (or run through pager) the source code for an object."""
591 """Print (or run through pager) the source code for an object."""
592 self._inspect('psource',parameter_s, namespaces)
592 self._inspect('psource',parameter_s, namespaces)
593
593
594 def magic_pfile(self, parameter_s=''):
594 def magic_pfile(self, parameter_s=''):
595 """Print (or run through pager) the file where an object is defined.
595 """Print (or run through pager) the file where an object is defined.
596
596
597 The file opens at the line where the object definition begins. IPython
597 The file opens at the line where the object definition begins. IPython
598 will honor the environment variable PAGER if set, and otherwise will
598 will honor the environment variable PAGER if set, and otherwise will
599 do its best to print the file in a convenient form.
599 do its best to print the file in a convenient form.
600
600
601 If the given argument is not an object currently defined, IPython will
601 If the given argument is not an object currently defined, IPython will
602 try to interpret it as a filename (automatically adding a .py extension
602 try to interpret it as a filename (automatically adding a .py extension
603 if needed). You can thus use %pfile as a syntax highlighting code
603 if needed). You can thus use %pfile as a syntax highlighting code
604 viewer."""
604 viewer."""
605
605
606 # first interpret argument as an object name
606 # first interpret argument as an object name
607 out = self._inspect('pfile',parameter_s)
607 out = self._inspect('pfile',parameter_s)
608 # if not, try the input as a filename
608 # if not, try the input as a filename
609 if out == 'not found':
609 if out == 'not found':
610 try:
610 try:
611 filename = get_py_filename(parameter_s)
611 filename = get_py_filename(parameter_s)
612 except IOError,msg:
612 except IOError,msg:
613 print msg
613 print msg
614 return
614 return
615 page.page(self.shell.inspector.format(file(filename).read()))
615 page.page(self.shell.inspector.format(file(filename).read()))
616
616
617 def magic_psearch(self, parameter_s=''):
617 def magic_psearch(self, parameter_s=''):
618 """Search for object in namespaces by wildcard.
618 """Search for object in namespaces by wildcard.
619
619
620 %psearch [options] PATTERN [OBJECT TYPE]
620 %psearch [options] PATTERN [OBJECT TYPE]
621
621
622 Note: ? can be used as a synonym for %psearch, at the beginning or at
622 Note: ? can be used as a synonym for %psearch, at the beginning or at
623 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
623 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
624 rest of the command line must be unchanged (options come first), so
624 rest of the command line must be unchanged (options come first), so
625 for example the following forms are equivalent
625 for example the following forms are equivalent
626
626
627 %psearch -i a* function
627 %psearch -i a* function
628 -i a* function?
628 -i a* function?
629 ?-i a* function
629 ?-i a* function
630
630
631 Arguments:
631 Arguments:
632
632
633 PATTERN
633 PATTERN
634
634
635 where PATTERN is a string containing * as a wildcard similar to its
635 where PATTERN is a string containing * as a wildcard similar to its
636 use in a shell. The pattern is matched in all namespaces on the
636 use in a shell. The pattern is matched in all namespaces on the
637 search path. By default objects starting with a single _ are not
637 search path. By default objects starting with a single _ are not
638 matched, many IPython generated objects have a single
638 matched, many IPython generated objects have a single
639 underscore. The default is case insensitive matching. Matching is
639 underscore. The default is case insensitive matching. Matching is
640 also done on the attributes of objects and not only on the objects
640 also done on the attributes of objects and not only on the objects
641 in a module.
641 in a module.
642
642
643 [OBJECT TYPE]
643 [OBJECT TYPE]
644
644
645 Is the name of a python type from the types module. The name is
645 Is the name of a python type from the types module. The name is
646 given in lowercase without the ending type, ex. StringType is
646 given in lowercase without the ending type, ex. StringType is
647 written string. By adding a type here only objects matching the
647 written string. By adding a type here only objects matching the
648 given type are matched. Using all here makes the pattern match all
648 given type are matched. Using all here makes the pattern match all
649 types (this is the default).
649 types (this is the default).
650
650
651 Options:
651 Options:
652
652
653 -a: makes the pattern match even objects whose names start with a
653 -a: makes the pattern match even objects whose names start with a
654 single underscore. These names are normally ommitted from the
654 single underscore. These names are normally ommitted from the
655 search.
655 search.
656
656
657 -i/-c: make the pattern case insensitive/sensitive. If neither of
657 -i/-c: make the pattern case insensitive/sensitive. If neither of
658 these options is given, the default is read from your ipythonrc
658 these options is given, the default is read from your ipythonrc
659 file. The option name which sets this value is
659 file. The option name which sets this value is
660 'wildcards_case_sensitive'. If this option is not specified in your
660 'wildcards_case_sensitive'. If this option is not specified in your
661 ipythonrc file, IPython's internal default is to do a case sensitive
661 ipythonrc file, IPython's internal default is to do a case sensitive
662 search.
662 search.
663
663
664 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
664 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
665 specifiy can be searched in any of the following namespaces:
665 specifiy can be searched in any of the following namespaces:
666 'builtin', 'user', 'user_global','internal', 'alias', where
666 'builtin', 'user', 'user_global','internal', 'alias', where
667 'builtin' and 'user' are the search defaults. Note that you should
667 'builtin' and 'user' are the search defaults. Note that you should
668 not use quotes when specifying namespaces.
668 not use quotes when specifying namespaces.
669
669
670 'Builtin' contains the python module builtin, 'user' contains all
670 'Builtin' contains the python module builtin, 'user' contains all
671 user data, 'alias' only contain the shell aliases and no python
671 user data, 'alias' only contain the shell aliases and no python
672 objects, 'internal' contains objects used by IPython. The
672 objects, 'internal' contains objects used by IPython. The
673 'user_global' namespace is only used by embedded IPython instances,
673 'user_global' namespace is only used by embedded IPython instances,
674 and it contains module-level globals. You can add namespaces to the
674 and it contains module-level globals. You can add namespaces to the
675 search with -s or exclude them with -e (these options can be given
675 search with -s or exclude them with -e (these options can be given
676 more than once).
676 more than once).
677
677
678 Examples:
678 Examples:
679
679
680 %psearch a* -> objects beginning with an a
680 %psearch a* -> objects beginning with an a
681 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
681 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
682 %psearch a* function -> all functions beginning with an a
682 %psearch a* function -> all functions beginning with an a
683 %psearch re.e* -> objects beginning with an e in module re
683 %psearch re.e* -> objects beginning with an e in module re
684 %psearch r*.e* -> objects that start with e in modules starting in r
684 %psearch r*.e* -> objects that start with e in modules starting in r
685 %psearch r*.* string -> all strings in modules beginning with r
685 %psearch r*.* string -> all strings in modules beginning with r
686
686
687 Case sensitve search:
687 Case sensitve search:
688
688
689 %psearch -c a* list all object beginning with lower case a
689 %psearch -c a* list all object beginning with lower case a
690
690
691 Show objects beginning with a single _:
691 Show objects beginning with a single _:
692
692
693 %psearch -a _* list objects beginning with a single underscore"""
693 %psearch -a _* list objects beginning with a single underscore"""
694 try:
694 try:
695 parameter_s = parameter_s.encode('ascii')
695 parameter_s = parameter_s.encode('ascii')
696 except UnicodeEncodeError:
696 except UnicodeEncodeError:
697 print 'Python identifiers can only contain ascii characters.'
697 print 'Python identifiers can only contain ascii characters.'
698 return
698 return
699
699
700 # default namespaces to be searched
700 # default namespaces to be searched
701 def_search = ['user','builtin']
701 def_search = ['user','builtin']
702
702
703 # Process options/args
703 # Process options/args
704 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
704 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
705 opt = opts.get
705 opt = opts.get
706 shell = self.shell
706 shell = self.shell
707 psearch = shell.inspector.psearch
707 psearch = shell.inspector.psearch
708
708
709 # select case options
709 # select case options
710 if opts.has_key('i'):
710 if opts.has_key('i'):
711 ignore_case = True
711 ignore_case = True
712 elif opts.has_key('c'):
712 elif opts.has_key('c'):
713 ignore_case = False
713 ignore_case = False
714 else:
714 else:
715 ignore_case = not shell.wildcards_case_sensitive
715 ignore_case = not shell.wildcards_case_sensitive
716
716
717 # Build list of namespaces to search from user options
717 # Build list of namespaces to search from user options
718 def_search.extend(opt('s',[]))
718 def_search.extend(opt('s',[]))
719 ns_exclude = ns_exclude=opt('e',[])
719 ns_exclude = ns_exclude=opt('e',[])
720 ns_search = [nm for nm in def_search if nm not in ns_exclude]
720 ns_search = [nm for nm in def_search if nm not in ns_exclude]
721
721
722 # Call the actual search
722 # Call the actual search
723 try:
723 try:
724 psearch(args,shell.ns_table,ns_search,
724 psearch(args,shell.ns_table,ns_search,
725 show_all=opt('a'),ignore_case=ignore_case)
725 show_all=opt('a'),ignore_case=ignore_case)
726 except:
726 except:
727 shell.showtraceback()
727 shell.showtraceback()
728
728
729 @testdec.skip_doctest
729 @testdec.skip_doctest
730 def magic_who_ls(self, parameter_s=''):
730 def magic_who_ls(self, parameter_s=''):
731 """Return a sorted list of all interactive variables.
731 """Return a sorted list of all interactive variables.
732
732
733 If arguments are given, only variables of types matching these
733 If arguments are given, only variables of types matching these
734 arguments are returned.
734 arguments are returned.
735
735
736 Examples
736 Examples
737 --------
737 --------
738
738
739 Define two variables and list them with who_ls::
739 Define two variables and list them with who_ls::
740
740
741 In [1]: alpha = 123
741 In [1]: alpha = 123
742
742
743 In [2]: beta = 'test'
743 In [2]: beta = 'test'
744
744
745 In [3]: %who_ls
745 In [3]: %who_ls
746 Out[3]: ['alpha', 'beta']
746 Out[3]: ['alpha', 'beta']
747
747
748 In [4]: %who_ls int
748 In [4]: %who_ls int
749 Out[4]: ['alpha']
749 Out[4]: ['alpha']
750
750
751 In [5]: %who_ls str
751 In [5]: %who_ls str
752 Out[5]: ['beta']
752 Out[5]: ['beta']
753 """
753 """
754
754
755 user_ns = self.shell.user_ns
755 user_ns = self.shell.user_ns
756 internal_ns = self.shell.internal_ns
756 internal_ns = self.shell.internal_ns
757 user_ns_hidden = self.shell.user_ns_hidden
757 user_ns_hidden = self.shell.user_ns_hidden
758 out = [ i for i in user_ns
758 out = [ i for i in user_ns
759 if not i.startswith('_') \
759 if not i.startswith('_') \
760 and not (i in internal_ns or i in user_ns_hidden) ]
760 and not (i in internal_ns or i in user_ns_hidden) ]
761
761
762 typelist = parameter_s.split()
762 typelist = parameter_s.split()
763 if typelist:
763 if typelist:
764 typeset = set(typelist)
764 typeset = set(typelist)
765 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
765 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
766
766
767 out.sort()
767 out.sort()
768 return out
768 return out
769
769
770 @testdec.skip_doctest
770 @testdec.skip_doctest
771 def magic_who(self, parameter_s=''):
771 def magic_who(self, parameter_s=''):
772 """Print all interactive variables, with some minimal formatting.
772 """Print all interactive variables, with some minimal formatting.
773
773
774 If any arguments are given, only variables whose type matches one of
774 If any arguments are given, only variables whose type matches one of
775 these are printed. For example:
775 these are printed. For example:
776
776
777 %who function str
777 %who function str
778
778
779 will only list functions and strings, excluding all other types of
779 will only list functions and strings, excluding all other types of
780 variables. To find the proper type names, simply use type(var) at a
780 variables. To find the proper type names, simply use type(var) at a
781 command line to see how python prints type names. For example:
781 command line to see how python prints type names. For example:
782
782
783 In [1]: type('hello')\\
783 In [1]: type('hello')\\
784 Out[1]: <type 'str'>
784 Out[1]: <type 'str'>
785
785
786 indicates that the type name for strings is 'str'.
786 indicates that the type name for strings is 'str'.
787
787
788 %who always excludes executed names loaded through your configuration
788 %who always excludes executed names loaded through your configuration
789 file and things which are internal to IPython.
789 file and things which are internal to IPython.
790
790
791 This is deliberate, as typically you may load many modules and the
791 This is deliberate, as typically you may load many modules and the
792 purpose of %who is to show you only what you've manually defined.
792 purpose of %who is to show you only what you've manually defined.
793
793
794 Examples
794 Examples
795 --------
795 --------
796
796
797 Define two variables and list them with who::
797 Define two variables and list them with who::
798
798
799 In [1]: alpha = 123
799 In [1]: alpha = 123
800
800
801 In [2]: beta = 'test'
801 In [2]: beta = 'test'
802
802
803 In [3]: %who
803 In [3]: %who
804 alpha beta
804 alpha beta
805
805
806 In [4]: %who int
806 In [4]: %who int
807 alpha
807 alpha
808
808
809 In [5]: %who str
809 In [5]: %who str
810 beta
810 beta
811 """
811 """
812
812
813 varlist = self.magic_who_ls(parameter_s)
813 varlist = self.magic_who_ls(parameter_s)
814 if not varlist:
814 if not varlist:
815 if parameter_s:
815 if parameter_s:
816 print 'No variables match your requested type.'
816 print 'No variables match your requested type.'
817 else:
817 else:
818 print 'Interactive namespace is empty.'
818 print 'Interactive namespace is empty.'
819 return
819 return
820
820
821 # if we have variables, move on...
821 # if we have variables, move on...
822 count = 0
822 count = 0
823 for i in varlist:
823 for i in varlist:
824 print i+'\t',
824 print i+'\t',
825 count += 1
825 count += 1
826 if count > 8:
826 if count > 8:
827 count = 0
827 count = 0
828 print
828 print
829 print
829 print
830
830
831 @testdec.skip_doctest
831 @testdec.skip_doctest
832 def magic_whos(self, parameter_s=''):
832 def magic_whos(self, parameter_s=''):
833 """Like %who, but gives some extra information about each variable.
833 """Like %who, but gives some extra information about each variable.
834
834
835 The same type filtering of %who can be applied here.
835 The same type filtering of %who can be applied here.
836
836
837 For all variables, the type is printed. Additionally it prints:
837 For all variables, the type is printed. Additionally it prints:
838
838
839 - For {},[],(): their length.
839 - For {},[],(): their length.
840
840
841 - For numpy arrays, a summary with shape, number of
841 - For numpy arrays, a summary with shape, number of
842 elements, typecode and size in memory.
842 elements, typecode and size in memory.
843
843
844 - Everything else: a string representation, snipping their middle if
844 - Everything else: a string representation, snipping their middle if
845 too long.
845 too long.
846
846
847 Examples
847 Examples
848 --------
848 --------
849
849
850 Define two variables and list them with whos::
850 Define two variables and list them with whos::
851
851
852 In [1]: alpha = 123
852 In [1]: alpha = 123
853
853
854 In [2]: beta = 'test'
854 In [2]: beta = 'test'
855
855
856 In [3]: %whos
856 In [3]: %whos
857 Variable Type Data/Info
857 Variable Type Data/Info
858 --------------------------------
858 --------------------------------
859 alpha int 123
859 alpha int 123
860 beta str test
860 beta str test
861 """
861 """
862
862
863 varnames = self.magic_who_ls(parameter_s)
863 varnames = self.magic_who_ls(parameter_s)
864 if not varnames:
864 if not varnames:
865 if parameter_s:
865 if parameter_s:
866 print 'No variables match your requested type.'
866 print 'No variables match your requested type.'
867 else:
867 else:
868 print 'Interactive namespace is empty.'
868 print 'Interactive namespace is empty.'
869 return
869 return
870
870
871 # if we have variables, move on...
871 # if we have variables, move on...
872
872
873 # for these types, show len() instead of data:
873 # for these types, show len() instead of data:
874 seq_types = ['dict', 'list', 'tuple']
874 seq_types = ['dict', 'list', 'tuple']
875
875
876 # for numpy/Numeric arrays, display summary info
876 # for numpy/Numeric arrays, display summary info
877 try:
877 try:
878 import numpy
878 import numpy
879 except ImportError:
879 except ImportError:
880 ndarray_type = None
880 ndarray_type = None
881 else:
881 else:
882 ndarray_type = numpy.ndarray.__name__
882 ndarray_type = numpy.ndarray.__name__
883 try:
883 try:
884 import Numeric
884 import Numeric
885 except ImportError:
885 except ImportError:
886 array_type = None
886 array_type = None
887 else:
887 else:
888 array_type = Numeric.ArrayType.__name__
888 array_type = Numeric.ArrayType.__name__
889
889
890 # Find all variable names and types so we can figure out column sizes
890 # Find all variable names and types so we can figure out column sizes
891 def get_vars(i):
891 def get_vars(i):
892 return self.shell.user_ns[i]
892 return self.shell.user_ns[i]
893
893
894 # some types are well known and can be shorter
894 # some types are well known and can be shorter
895 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
895 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
896 def type_name(v):
896 def type_name(v):
897 tn = type(v).__name__
897 tn = type(v).__name__
898 return abbrevs.get(tn,tn)
898 return abbrevs.get(tn,tn)
899
899
900 varlist = map(get_vars,varnames)
900 varlist = map(get_vars,varnames)
901
901
902 typelist = []
902 typelist = []
903 for vv in varlist:
903 for vv in varlist:
904 tt = type_name(vv)
904 tt = type_name(vv)
905
905
906 if tt=='instance':
906 if tt=='instance':
907 typelist.append( abbrevs.get(str(vv.__class__),
907 typelist.append( abbrevs.get(str(vv.__class__),
908 str(vv.__class__)))
908 str(vv.__class__)))
909 else:
909 else:
910 typelist.append(tt)
910 typelist.append(tt)
911
911
912 # column labels and # of spaces as separator
912 # column labels and # of spaces as separator
913 varlabel = 'Variable'
913 varlabel = 'Variable'
914 typelabel = 'Type'
914 typelabel = 'Type'
915 datalabel = 'Data/Info'
915 datalabel = 'Data/Info'
916 colsep = 3
916 colsep = 3
917 # variable format strings
917 # variable format strings
918 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
918 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
919 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
919 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
920 aformat = "%s: %s elems, type `%s`, %s bytes"
920 aformat = "%s: %s elems, type `%s`, %s bytes"
921 # find the size of the columns to format the output nicely
921 # find the size of the columns to format the output nicely
922 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
922 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
923 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
923 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
924 # table header
924 # table header
925 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
925 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
926 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
926 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
927 # and the table itself
927 # and the table itself
928 kb = 1024
928 kb = 1024
929 Mb = 1048576 # kb**2
929 Mb = 1048576 # kb**2
930 for vname,var,vtype in zip(varnames,varlist,typelist):
930 for vname,var,vtype in zip(varnames,varlist,typelist):
931 print itpl(vformat),
931 print itpl(vformat),
932 if vtype in seq_types:
932 if vtype in seq_types:
933 print "n="+str(len(var))
933 print "n="+str(len(var))
934 elif vtype in [array_type,ndarray_type]:
934 elif vtype in [array_type,ndarray_type]:
935 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
935 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
936 if vtype==ndarray_type:
936 if vtype==ndarray_type:
937 # numpy
937 # numpy
938 vsize = var.size
938 vsize = var.size
939 vbytes = vsize*var.itemsize
939 vbytes = vsize*var.itemsize
940 vdtype = var.dtype
940 vdtype = var.dtype
941 else:
941 else:
942 # Numeric
942 # Numeric
943 vsize = Numeric.size(var)
943 vsize = Numeric.size(var)
944 vbytes = vsize*var.itemsize()
944 vbytes = vsize*var.itemsize()
945 vdtype = var.typecode()
945 vdtype = var.typecode()
946
946
947 if vbytes < 100000:
947 if vbytes < 100000:
948 print aformat % (vshape,vsize,vdtype,vbytes)
948 print aformat % (vshape,vsize,vdtype,vbytes)
949 else:
949 else:
950 print aformat % (vshape,vsize,vdtype,vbytes),
950 print aformat % (vshape,vsize,vdtype,vbytes),
951 if vbytes < Mb:
951 if vbytes < Mb:
952 print '(%s kb)' % (vbytes/kb,)
952 print '(%s kb)' % (vbytes/kb,)
953 else:
953 else:
954 print '(%s Mb)' % (vbytes/Mb,)
954 print '(%s Mb)' % (vbytes/Mb,)
955 else:
955 else:
956 try:
956 try:
957 vstr = str(var)
957 vstr = str(var)
958 except UnicodeEncodeError:
958 except UnicodeEncodeError:
959 vstr = unicode(var).encode(sys.getdefaultencoding(),
959 vstr = unicode(var).encode(sys.getdefaultencoding(),
960 'backslashreplace')
960 'backslashreplace')
961 vstr = vstr.replace('\n','\\n')
961 vstr = vstr.replace('\n','\\n')
962 if len(vstr) < 50:
962 if len(vstr) < 50:
963 print vstr
963 print vstr
964 else:
964 else:
965 printpl(vfmt_short)
965 printpl(vfmt_short)
966
966
967 def magic_reset(self, parameter_s=''):
967 def magic_reset(self, parameter_s=''):
968 """Resets the namespace by removing all names defined by the user.
968 """Resets the namespace by removing all names defined by the user.
969
969
970 Input/Output history are left around in case you need them.
971
972 Parameters
970 Parameters
973 ----------
971 ----------
974 -f : force reset without asking for confirmation.
972 -f : force reset without asking for confirmation.
975
973
974 -h : 'Hard' reset: gives you a new session and removes all
975 references to objects from the current session. By default, we
976 do a 'soft' reset, which only clears out your namespace, and
977 leaves input and output history around.
978
976 Examples
979 Examples
977 --------
980 --------
978 In [6]: a = 1
981 In [6]: a = 1
979
982
980 In [7]: a
983 In [7]: a
981 Out[7]: 1
984 Out[7]: 1
982
985
983 In [8]: 'a' in _ip.user_ns
986 In [8]: 'a' in _ip.user_ns
984 Out[8]: True
987 Out[8]: True
985
988
986 In [9]: %reset -f
989 In [9]: %reset -f
987
990
988 In [10]: 'a' in _ip.user_ns
991 In [10]: 'a' in _ip.user_ns
989 Out[10]: False
992 Out[10]: False
990 """
993 """
991
994 opts, args = self.parse_options(parameter_s,'fh')
992 if parameter_s == '-f':
995 if 'f' in opts:
993 ans = True
996 ans = True
994 else:
997 else:
995 ans = self.shell.ask_yes_no(
998 ans = self.shell.ask_yes_no(
996 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
999 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
997 if not ans:
1000 if not ans:
998 print 'Nothing done.'
1001 print 'Nothing done.'
999 return
1002 return
1000 user_ns = self.shell.user_ns
1001 for i in self.magic_who_ls():
1002 del(user_ns[i])
1003
1003
1004 # Also flush the private list of module references kept for script
1004 if 'h' in opts: # Hard reset
1005 # execution protection
1005 self.shell.reset(new_session = True)
1006 self.shell.clear_main_mod_cache()
1006
1007 else: # Soft reset
1008 user_ns = self.shell.user_ns
1009 for i in self.magic_who_ls():
1010 del(user_ns[i])
1007
1011
1008 def magic_reset_selective(self, parameter_s=''):
1012 def magic_reset_selective(self, parameter_s=''):
1009 """Resets the namespace by removing names defined by the user.
1013 """Resets the namespace by removing names defined by the user.
1010
1014
1011 Input/Output history are left around in case you need them.
1015 Input/Output history are left around in case you need them.
1012
1016
1013 %reset_selective [-f] regex
1017 %reset_selective [-f] regex
1014
1018
1015 No action is taken if regex is not included
1019 No action is taken if regex is not included
1016
1020
1017 Options
1021 Options
1018 -f : force reset without asking for confirmation.
1022 -f : force reset without asking for confirmation.
1019
1023
1020 Examples
1024 Examples
1021 --------
1025 --------
1022
1026
1023 We first fully reset the namespace so your output looks identical to
1027 We first fully reset the namespace so your output looks identical to
1024 this example for pedagogical reasons; in practice you do not need a
1028 this example for pedagogical reasons; in practice you do not need a
1025 full reset.
1029 full reset.
1026
1030
1027 In [1]: %reset -f
1031 In [1]: %reset -f
1028
1032
1029 Now, with a clean namespace we can make a few variables and use
1033 Now, with a clean namespace we can make a few variables and use
1030 %reset_selective to only delete names that match our regexp:
1034 %reset_selective to only delete names that match our regexp:
1031
1035
1032 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1036 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1033
1037
1034 In [3]: who_ls
1038 In [3]: who_ls
1035 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1039 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1036
1040
1037 In [4]: %reset_selective -f b[2-3]m
1041 In [4]: %reset_selective -f b[2-3]m
1038
1042
1039 In [5]: who_ls
1043 In [5]: who_ls
1040 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1044 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1041
1045
1042 In [6]: %reset_selective -f d
1046 In [6]: %reset_selective -f d
1043
1047
1044 In [7]: who_ls
1048 In [7]: who_ls
1045 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1049 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1046
1050
1047 In [8]: %reset_selective -f c
1051 In [8]: %reset_selective -f c
1048
1052
1049 In [9]: who_ls
1053 In [9]: who_ls
1050 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1054 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1051
1055
1052 In [10]: %reset_selective -f b
1056 In [10]: %reset_selective -f b
1053
1057
1054 In [11]: who_ls
1058 In [11]: who_ls
1055 Out[11]: ['a']
1059 Out[11]: ['a']
1056 """
1060 """
1057
1061
1058 opts, regex = self.parse_options(parameter_s,'f')
1062 opts, regex = self.parse_options(parameter_s,'f')
1059
1063
1060 if opts.has_key('f'):
1064 if opts.has_key('f'):
1061 ans = True
1065 ans = True
1062 else:
1066 else:
1063 ans = self.shell.ask_yes_no(
1067 ans = self.shell.ask_yes_no(
1064 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1068 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1065 if not ans:
1069 if not ans:
1066 print 'Nothing done.'
1070 print 'Nothing done.'
1067 return
1071 return
1068 user_ns = self.shell.user_ns
1072 user_ns = self.shell.user_ns
1069 if not regex:
1073 if not regex:
1070 print 'No regex pattern specified. Nothing done.'
1074 print 'No regex pattern specified. Nothing done.'
1071 return
1075 return
1072 else:
1076 else:
1073 try:
1077 try:
1074 m = re.compile(regex)
1078 m = re.compile(regex)
1075 except TypeError:
1079 except TypeError:
1076 raise TypeError('regex must be a string or compiled pattern')
1080 raise TypeError('regex must be a string or compiled pattern')
1077 for i in self.magic_who_ls():
1081 for i in self.magic_who_ls():
1078 if m.search(i):
1082 if m.search(i):
1079 del(user_ns[i])
1083 del(user_ns[i])
1080
1084
1081 def magic_logstart(self,parameter_s=''):
1085 def magic_logstart(self,parameter_s=''):
1082 """Start logging anywhere in a session.
1086 """Start logging anywhere in a session.
1083
1087
1084 %logstart [-o|-r|-t] [log_name [log_mode]]
1088 %logstart [-o|-r|-t] [log_name [log_mode]]
1085
1089
1086 If no name is given, it defaults to a file named 'ipython_log.py' in your
1090 If no name is given, it defaults to a file named 'ipython_log.py' in your
1087 current directory, in 'rotate' mode (see below).
1091 current directory, in 'rotate' mode (see below).
1088
1092
1089 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1093 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1090 history up to that point and then continues logging.
1094 history up to that point and then continues logging.
1091
1095
1092 %logstart takes a second optional parameter: logging mode. This can be one
1096 %logstart takes a second optional parameter: logging mode. This can be one
1093 of (note that the modes are given unquoted):\\
1097 of (note that the modes are given unquoted):\\
1094 append: well, that says it.\\
1098 append: well, that says it.\\
1095 backup: rename (if exists) to name~ and start name.\\
1099 backup: rename (if exists) to name~ and start name.\\
1096 global: single logfile in your home dir, appended to.\\
1100 global: single logfile in your home dir, appended to.\\
1097 over : overwrite existing log.\\
1101 over : overwrite existing log.\\
1098 rotate: create rotating logs name.1~, name.2~, etc.
1102 rotate: create rotating logs name.1~, name.2~, etc.
1099
1103
1100 Options:
1104 Options:
1101
1105
1102 -o: log also IPython's output. In this mode, all commands which
1106 -o: log also IPython's output. In this mode, all commands which
1103 generate an Out[NN] prompt are recorded to the logfile, right after
1107 generate an Out[NN] prompt are recorded to the logfile, right after
1104 their corresponding input line. The output lines are always
1108 their corresponding input line. The output lines are always
1105 prepended with a '#[Out]# ' marker, so that the log remains valid
1109 prepended with a '#[Out]# ' marker, so that the log remains valid
1106 Python code.
1110 Python code.
1107
1111
1108 Since this marker is always the same, filtering only the output from
1112 Since this marker is always the same, filtering only the output from
1109 a log is very easy, using for example a simple awk call:
1113 a log is very easy, using for example a simple awk call:
1110
1114
1111 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1115 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1112
1116
1113 -r: log 'raw' input. Normally, IPython's logs contain the processed
1117 -r: log 'raw' input. Normally, IPython's logs contain the processed
1114 input, so that user lines are logged in their final form, converted
1118 input, so that user lines are logged in their final form, converted
1115 into valid Python. For example, %Exit is logged as
1119 into valid Python. For example, %Exit is logged as
1116 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1120 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1117 exactly as typed, with no transformations applied.
1121 exactly as typed, with no transformations applied.
1118
1122
1119 -t: put timestamps before each input line logged (these are put in
1123 -t: put timestamps before each input line logged (these are put in
1120 comments)."""
1124 comments)."""
1121
1125
1122 opts,par = self.parse_options(parameter_s,'ort')
1126 opts,par = self.parse_options(parameter_s,'ort')
1123 log_output = 'o' in opts
1127 log_output = 'o' in opts
1124 log_raw_input = 'r' in opts
1128 log_raw_input = 'r' in opts
1125 timestamp = 't' in opts
1129 timestamp = 't' in opts
1126
1130
1127 logger = self.shell.logger
1131 logger = self.shell.logger
1128
1132
1129 # if no args are given, the defaults set in the logger constructor by
1133 # if no args are given, the defaults set in the logger constructor by
1130 # ipytohn remain valid
1134 # ipytohn remain valid
1131 if par:
1135 if par:
1132 try:
1136 try:
1133 logfname,logmode = par.split()
1137 logfname,logmode = par.split()
1134 except:
1138 except:
1135 logfname = par
1139 logfname = par
1136 logmode = 'backup'
1140 logmode = 'backup'
1137 else:
1141 else:
1138 logfname = logger.logfname
1142 logfname = logger.logfname
1139 logmode = logger.logmode
1143 logmode = logger.logmode
1140 # put logfname into rc struct as if it had been called on the command
1144 # put logfname into rc struct as if it had been called on the command
1141 # line, so it ends up saved in the log header Save it in case we need
1145 # line, so it ends up saved in the log header Save it in case we need
1142 # to restore it...
1146 # to restore it...
1143 old_logfile = self.shell.logfile
1147 old_logfile = self.shell.logfile
1144 if logfname:
1148 if logfname:
1145 logfname = os.path.expanduser(logfname)
1149 logfname = os.path.expanduser(logfname)
1146 self.shell.logfile = logfname
1150 self.shell.logfile = logfname
1147
1151
1148 loghead = '# IPython log file\n\n'
1152 loghead = '# IPython log file\n\n'
1149 try:
1153 try:
1150 started = logger.logstart(logfname,loghead,logmode,
1154 started = logger.logstart(logfname,loghead,logmode,
1151 log_output,timestamp,log_raw_input)
1155 log_output,timestamp,log_raw_input)
1152 except:
1156 except:
1153 self.shell.logfile = old_logfile
1157 self.shell.logfile = old_logfile
1154 warn("Couldn't start log: %s" % sys.exc_info()[1])
1158 warn("Couldn't start log: %s" % sys.exc_info()[1])
1155 else:
1159 else:
1156 # log input history up to this point, optionally interleaving
1160 # log input history up to this point, optionally interleaving
1157 # output if requested
1161 # output if requested
1158
1162
1159 if timestamp:
1163 if timestamp:
1160 # disable timestamping for the previous history, since we've
1164 # disable timestamping for the previous history, since we've
1161 # lost those already (no time machine here).
1165 # lost those already (no time machine here).
1162 logger.timestamp = False
1166 logger.timestamp = False
1163
1167
1164 if log_raw_input:
1168 if log_raw_input:
1165 input_hist = self.shell.history_manager.input_hist_raw
1169 input_hist = self.shell.history_manager.input_hist_raw
1166 else:
1170 else:
1167 input_hist = self.shell.history_manager.input_hist_parsed
1171 input_hist = self.shell.history_manager.input_hist_parsed
1168
1172
1169 if log_output:
1173 if log_output:
1170 log_write = logger.log_write
1174 log_write = logger.log_write
1171 output_hist = self.shell.history_manager.output_hist
1175 output_hist = self.shell.history_manager.output_hist
1172 for n in range(1,len(input_hist)-1):
1176 for n in range(1,len(input_hist)-1):
1173 log_write(input_hist[n].rstrip())
1177 log_write(input_hist[n].rstrip())
1174 if n in output_hist:
1178 if n in output_hist:
1175 log_write(repr(output_hist[n]),'output')
1179 log_write(repr(output_hist[n]),'output')
1176 else:
1180 else:
1177 logger.log_write(''.join(input_hist[1:]))
1181 logger.log_write(''.join(input_hist[1:]))
1178 if timestamp:
1182 if timestamp:
1179 # re-enable timestamping
1183 # re-enable timestamping
1180 logger.timestamp = True
1184 logger.timestamp = True
1181
1185
1182 print ('Activating auto-logging. '
1186 print ('Activating auto-logging. '
1183 'Current session state plus future input saved.')
1187 'Current session state plus future input saved.')
1184 logger.logstate()
1188 logger.logstate()
1185
1189
1186 def magic_logstop(self,parameter_s=''):
1190 def magic_logstop(self,parameter_s=''):
1187 """Fully stop logging and close log file.
1191 """Fully stop logging and close log file.
1188
1192
1189 In order to start logging again, a new %logstart call needs to be made,
1193 In order to start logging again, a new %logstart call needs to be made,
1190 possibly (though not necessarily) with a new filename, mode and other
1194 possibly (though not necessarily) with a new filename, mode and other
1191 options."""
1195 options."""
1192 self.logger.logstop()
1196 self.logger.logstop()
1193
1197
1194 def magic_logoff(self,parameter_s=''):
1198 def magic_logoff(self,parameter_s=''):
1195 """Temporarily stop logging.
1199 """Temporarily stop logging.
1196
1200
1197 You must have previously started logging."""
1201 You must have previously started logging."""
1198 self.shell.logger.switch_log(0)
1202 self.shell.logger.switch_log(0)
1199
1203
1200 def magic_logon(self,parameter_s=''):
1204 def magic_logon(self,parameter_s=''):
1201 """Restart logging.
1205 """Restart logging.
1202
1206
1203 This function is for restarting logging which you've temporarily
1207 This function is for restarting logging which you've temporarily
1204 stopped with %logoff. For starting logging for the first time, you
1208 stopped with %logoff. For starting logging for the first time, you
1205 must use the %logstart function, which allows you to specify an
1209 must use the %logstart function, which allows you to specify an
1206 optional log filename."""
1210 optional log filename."""
1207
1211
1208 self.shell.logger.switch_log(1)
1212 self.shell.logger.switch_log(1)
1209
1213
1210 def magic_logstate(self,parameter_s=''):
1214 def magic_logstate(self,parameter_s=''):
1211 """Print the status of the logging system."""
1215 """Print the status of the logging system."""
1212
1216
1213 self.shell.logger.logstate()
1217 self.shell.logger.logstate()
1214
1218
1215 def magic_pdb(self, parameter_s=''):
1219 def magic_pdb(self, parameter_s=''):
1216 """Control the automatic calling of the pdb interactive debugger.
1220 """Control the automatic calling of the pdb interactive debugger.
1217
1221
1218 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1222 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1219 argument it works as a toggle.
1223 argument it works as a toggle.
1220
1224
1221 When an exception is triggered, IPython can optionally call the
1225 When an exception is triggered, IPython can optionally call the
1222 interactive pdb debugger after the traceback printout. %pdb toggles
1226 interactive pdb debugger after the traceback printout. %pdb toggles
1223 this feature on and off.
1227 this feature on and off.
1224
1228
1225 The initial state of this feature is set in your ipythonrc
1229 The initial state of this feature is set in your ipythonrc
1226 configuration file (the variable is called 'pdb').
1230 configuration file (the variable is called 'pdb').
1227
1231
1228 If you want to just activate the debugger AFTER an exception has fired,
1232 If you want to just activate the debugger AFTER an exception has fired,
1229 without having to type '%pdb on' and rerunning your code, you can use
1233 without having to type '%pdb on' and rerunning your code, you can use
1230 the %debug magic."""
1234 the %debug magic."""
1231
1235
1232 par = parameter_s.strip().lower()
1236 par = parameter_s.strip().lower()
1233
1237
1234 if par:
1238 if par:
1235 try:
1239 try:
1236 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1240 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1237 except KeyError:
1241 except KeyError:
1238 print ('Incorrect argument. Use on/1, off/0, '
1242 print ('Incorrect argument. Use on/1, off/0, '
1239 'or nothing for a toggle.')
1243 'or nothing for a toggle.')
1240 return
1244 return
1241 else:
1245 else:
1242 # toggle
1246 # toggle
1243 new_pdb = not self.shell.call_pdb
1247 new_pdb = not self.shell.call_pdb
1244
1248
1245 # set on the shell
1249 # set on the shell
1246 self.shell.call_pdb = new_pdb
1250 self.shell.call_pdb = new_pdb
1247 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1251 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1248
1252
1249 def magic_debug(self, parameter_s=''):
1253 def magic_debug(self, parameter_s=''):
1250 """Activate the interactive debugger in post-mortem mode.
1254 """Activate the interactive debugger in post-mortem mode.
1251
1255
1252 If an exception has just occurred, this lets you inspect its stack
1256 If an exception has just occurred, this lets you inspect its stack
1253 frames interactively. Note that this will always work only on the last
1257 frames interactively. Note that this will always work only on the last
1254 traceback that occurred, so you must call this quickly after an
1258 traceback that occurred, so you must call this quickly after an
1255 exception that you wish to inspect has fired, because if another one
1259 exception that you wish to inspect has fired, because if another one
1256 occurs, it clobbers the previous one.
1260 occurs, it clobbers the previous one.
1257
1261
1258 If you want IPython to automatically do this on every exception, see
1262 If you want IPython to automatically do this on every exception, see
1259 the %pdb magic for more details.
1263 the %pdb magic for more details.
1260 """
1264 """
1261 self.shell.debugger(force=True)
1265 self.shell.debugger(force=True)
1262
1266
1263 @testdec.skip_doctest
1267 @testdec.skip_doctest
1264 def magic_prun(self, parameter_s ='',user_mode=1,
1268 def magic_prun(self, parameter_s ='',user_mode=1,
1265 opts=None,arg_lst=None,prog_ns=None):
1269 opts=None,arg_lst=None,prog_ns=None):
1266
1270
1267 """Run a statement through the python code profiler.
1271 """Run a statement through the python code profiler.
1268
1272
1269 Usage:
1273 Usage:
1270 %prun [options] statement
1274 %prun [options] statement
1271
1275
1272 The given statement (which doesn't require quote marks) is run via the
1276 The given statement (which doesn't require quote marks) is run via the
1273 python profiler in a manner similar to the profile.run() function.
1277 python profiler in a manner similar to the profile.run() function.
1274 Namespaces are internally managed to work correctly; profile.run
1278 Namespaces are internally managed to work correctly; profile.run
1275 cannot be used in IPython because it makes certain assumptions about
1279 cannot be used in IPython because it makes certain assumptions about
1276 namespaces which do not hold under IPython.
1280 namespaces which do not hold under IPython.
1277
1281
1278 Options:
1282 Options:
1279
1283
1280 -l <limit>: you can place restrictions on what or how much of the
1284 -l <limit>: you can place restrictions on what or how much of the
1281 profile gets printed. The limit value can be:
1285 profile gets printed. The limit value can be:
1282
1286
1283 * A string: only information for function names containing this string
1287 * A string: only information for function names containing this string
1284 is printed.
1288 is printed.
1285
1289
1286 * An integer: only these many lines are printed.
1290 * An integer: only these many lines are printed.
1287
1291
1288 * A float (between 0 and 1): this fraction of the report is printed
1292 * A float (between 0 and 1): this fraction of the report is printed
1289 (for example, use a limit of 0.4 to see the topmost 40% only).
1293 (for example, use a limit of 0.4 to see the topmost 40% only).
1290
1294
1291 You can combine several limits with repeated use of the option. For
1295 You can combine several limits with repeated use of the option. For
1292 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1296 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1293 information about class constructors.
1297 information about class constructors.
1294
1298
1295 -r: return the pstats.Stats object generated by the profiling. This
1299 -r: return the pstats.Stats object generated by the profiling. This
1296 object has all the information about the profile in it, and you can
1300 object has all the information about the profile in it, and you can
1297 later use it for further analysis or in other functions.
1301 later use it for further analysis or in other functions.
1298
1302
1299 -s <key>: sort profile by given key. You can provide more than one key
1303 -s <key>: sort profile by given key. You can provide more than one key
1300 by using the option several times: '-s key1 -s key2 -s key3...'. The
1304 by using the option several times: '-s key1 -s key2 -s key3...'. The
1301 default sorting key is 'time'.
1305 default sorting key is 'time'.
1302
1306
1303 The following is copied verbatim from the profile documentation
1307 The following is copied verbatim from the profile documentation
1304 referenced below:
1308 referenced below:
1305
1309
1306 When more than one key is provided, additional keys are used as
1310 When more than one key is provided, additional keys are used as
1307 secondary criteria when the there is equality in all keys selected
1311 secondary criteria when the there is equality in all keys selected
1308 before them.
1312 before them.
1309
1313
1310 Abbreviations can be used for any key names, as long as the
1314 Abbreviations can be used for any key names, as long as the
1311 abbreviation is unambiguous. The following are the keys currently
1315 abbreviation is unambiguous. The following are the keys currently
1312 defined:
1316 defined:
1313
1317
1314 Valid Arg Meaning
1318 Valid Arg Meaning
1315 "calls" call count
1319 "calls" call count
1316 "cumulative" cumulative time
1320 "cumulative" cumulative time
1317 "file" file name
1321 "file" file name
1318 "module" file name
1322 "module" file name
1319 "pcalls" primitive call count
1323 "pcalls" primitive call count
1320 "line" line number
1324 "line" line number
1321 "name" function name
1325 "name" function name
1322 "nfl" name/file/line
1326 "nfl" name/file/line
1323 "stdname" standard name
1327 "stdname" standard name
1324 "time" internal time
1328 "time" internal time
1325
1329
1326 Note that all sorts on statistics are in descending order (placing
1330 Note that all sorts on statistics are in descending order (placing
1327 most time consuming items first), where as name, file, and line number
1331 most time consuming items first), where as name, file, and line number
1328 searches are in ascending order (i.e., alphabetical). The subtle
1332 searches are in ascending order (i.e., alphabetical). The subtle
1329 distinction between "nfl" and "stdname" is that the standard name is a
1333 distinction between "nfl" and "stdname" is that the standard name is a
1330 sort of the name as printed, which means that the embedded line
1334 sort of the name as printed, which means that the embedded line
1331 numbers get compared in an odd way. For example, lines 3, 20, and 40
1335 numbers get compared in an odd way. For example, lines 3, 20, and 40
1332 would (if the file names were the same) appear in the string order
1336 would (if the file names were the same) appear in the string order
1333 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1337 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1334 line numbers. In fact, sort_stats("nfl") is the same as
1338 line numbers. In fact, sort_stats("nfl") is the same as
1335 sort_stats("name", "file", "line").
1339 sort_stats("name", "file", "line").
1336
1340
1337 -T <filename>: save profile results as shown on screen to a text
1341 -T <filename>: save profile results as shown on screen to a text
1338 file. The profile is still shown on screen.
1342 file. The profile is still shown on screen.
1339
1343
1340 -D <filename>: save (via dump_stats) profile statistics to given
1344 -D <filename>: save (via dump_stats) profile statistics to given
1341 filename. This data is in a format understod by the pstats module, and
1345 filename. This data is in a format understod by the pstats module, and
1342 is generated by a call to the dump_stats() method of profile
1346 is generated by a call to the dump_stats() method of profile
1343 objects. The profile is still shown on screen.
1347 objects. The profile is still shown on screen.
1344
1348
1345 If you want to run complete programs under the profiler's control, use
1349 If you want to run complete programs under the profiler's control, use
1346 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1350 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1347 contains profiler specific options as described here.
1351 contains profiler specific options as described here.
1348
1352
1349 You can read the complete documentation for the profile module with::
1353 You can read the complete documentation for the profile module with::
1350
1354
1351 In [1]: import profile; profile.help()
1355 In [1]: import profile; profile.help()
1352 """
1356 """
1353
1357
1354 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1358 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1355 # protect user quote marks
1359 # protect user quote marks
1356 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1360 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1357
1361
1358 if user_mode: # regular user call
1362 if user_mode: # regular user call
1359 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1363 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1360 list_all=1)
1364 list_all=1)
1361 namespace = self.shell.user_ns
1365 namespace = self.shell.user_ns
1362 else: # called to run a program by %run -p
1366 else: # called to run a program by %run -p
1363 try:
1367 try:
1364 filename = get_py_filename(arg_lst[0])
1368 filename = get_py_filename(arg_lst[0])
1365 except IOError,msg:
1369 except IOError,msg:
1366 error(msg)
1370 error(msg)
1367 return
1371 return
1368
1372
1369 arg_str = 'execfile(filename,prog_ns)'
1373 arg_str = 'execfile(filename,prog_ns)'
1370 namespace = locals()
1374 namespace = locals()
1371
1375
1372 opts.merge(opts_def)
1376 opts.merge(opts_def)
1373
1377
1374 prof = profile.Profile()
1378 prof = profile.Profile()
1375 try:
1379 try:
1376 prof = prof.runctx(arg_str,namespace,namespace)
1380 prof = prof.runctx(arg_str,namespace,namespace)
1377 sys_exit = ''
1381 sys_exit = ''
1378 except SystemExit:
1382 except SystemExit:
1379 sys_exit = """*** SystemExit exception caught in code being profiled."""
1383 sys_exit = """*** SystemExit exception caught in code being profiled."""
1380
1384
1381 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1385 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1382
1386
1383 lims = opts.l
1387 lims = opts.l
1384 if lims:
1388 if lims:
1385 lims = [] # rebuild lims with ints/floats/strings
1389 lims = [] # rebuild lims with ints/floats/strings
1386 for lim in opts.l:
1390 for lim in opts.l:
1387 try:
1391 try:
1388 lims.append(int(lim))
1392 lims.append(int(lim))
1389 except ValueError:
1393 except ValueError:
1390 try:
1394 try:
1391 lims.append(float(lim))
1395 lims.append(float(lim))
1392 except ValueError:
1396 except ValueError:
1393 lims.append(lim)
1397 lims.append(lim)
1394
1398
1395 # Trap output.
1399 # Trap output.
1396 stdout_trap = StringIO()
1400 stdout_trap = StringIO()
1397
1401
1398 if hasattr(stats,'stream'):
1402 if hasattr(stats,'stream'):
1399 # In newer versions of python, the stats object has a 'stream'
1403 # In newer versions of python, the stats object has a 'stream'
1400 # attribute to write into.
1404 # attribute to write into.
1401 stats.stream = stdout_trap
1405 stats.stream = stdout_trap
1402 stats.print_stats(*lims)
1406 stats.print_stats(*lims)
1403 else:
1407 else:
1404 # For older versions, we manually redirect stdout during printing
1408 # For older versions, we manually redirect stdout during printing
1405 sys_stdout = sys.stdout
1409 sys_stdout = sys.stdout
1406 try:
1410 try:
1407 sys.stdout = stdout_trap
1411 sys.stdout = stdout_trap
1408 stats.print_stats(*lims)
1412 stats.print_stats(*lims)
1409 finally:
1413 finally:
1410 sys.stdout = sys_stdout
1414 sys.stdout = sys_stdout
1411
1415
1412 output = stdout_trap.getvalue()
1416 output = stdout_trap.getvalue()
1413 output = output.rstrip()
1417 output = output.rstrip()
1414
1418
1415 page.page(output)
1419 page.page(output)
1416 print sys_exit,
1420 print sys_exit,
1417
1421
1418 dump_file = opts.D[0]
1422 dump_file = opts.D[0]
1419 text_file = opts.T[0]
1423 text_file = opts.T[0]
1420 if dump_file:
1424 if dump_file:
1421 prof.dump_stats(dump_file)
1425 prof.dump_stats(dump_file)
1422 print '\n*** Profile stats marshalled to file',\
1426 print '\n*** Profile stats marshalled to file',\
1423 `dump_file`+'.',sys_exit
1427 `dump_file`+'.',sys_exit
1424 if text_file:
1428 if text_file:
1425 pfile = file(text_file,'w')
1429 pfile = file(text_file,'w')
1426 pfile.write(output)
1430 pfile.write(output)
1427 pfile.close()
1431 pfile.close()
1428 print '\n*** Profile printout saved to text file',\
1432 print '\n*** Profile printout saved to text file',\
1429 `text_file`+'.',sys_exit
1433 `text_file`+'.',sys_exit
1430
1434
1431 if opts.has_key('r'):
1435 if opts.has_key('r'):
1432 return stats
1436 return stats
1433 else:
1437 else:
1434 return None
1438 return None
1435
1439
1436 @testdec.skip_doctest
1440 @testdec.skip_doctest
1437 def magic_run(self, parameter_s ='',runner=None,
1441 def magic_run(self, parameter_s ='',runner=None,
1438 file_finder=get_py_filename):
1442 file_finder=get_py_filename):
1439 """Run the named file inside IPython as a program.
1443 """Run the named file inside IPython as a program.
1440
1444
1441 Usage:\\
1445 Usage:\\
1442 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1446 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1443
1447
1444 Parameters after the filename are passed as command-line arguments to
1448 Parameters after the filename are passed as command-line arguments to
1445 the program (put in sys.argv). Then, control returns to IPython's
1449 the program (put in sys.argv). Then, control returns to IPython's
1446 prompt.
1450 prompt.
1447
1451
1448 This is similar to running at a system prompt:\\
1452 This is similar to running at a system prompt:\\
1449 $ python file args\\
1453 $ python file args\\
1450 but with the advantage of giving you IPython's tracebacks, and of
1454 but with the advantage of giving you IPython's tracebacks, and of
1451 loading all variables into your interactive namespace for further use
1455 loading all variables into your interactive namespace for further use
1452 (unless -p is used, see below).
1456 (unless -p is used, see below).
1453
1457
1454 The file is executed in a namespace initially consisting only of
1458 The file is executed in a namespace initially consisting only of
1455 __name__=='__main__' and sys.argv constructed as indicated. It thus
1459 __name__=='__main__' and sys.argv constructed as indicated. It thus
1456 sees its environment as if it were being run as a stand-alone program
1460 sees its environment as if it were being run as a stand-alone program
1457 (except for sharing global objects such as previously imported
1461 (except for sharing global objects such as previously imported
1458 modules). But after execution, the IPython interactive namespace gets
1462 modules). But after execution, the IPython interactive namespace gets
1459 updated with all variables defined in the program (except for __name__
1463 updated with all variables defined in the program (except for __name__
1460 and sys.argv). This allows for very convenient loading of code for
1464 and sys.argv). This allows for very convenient loading of code for
1461 interactive work, while giving each program a 'clean sheet' to run in.
1465 interactive work, while giving each program a 'clean sheet' to run in.
1462
1466
1463 Options:
1467 Options:
1464
1468
1465 -n: __name__ is NOT set to '__main__', but to the running file's name
1469 -n: __name__ is NOT set to '__main__', but to the running file's name
1466 without extension (as python does under import). This allows running
1470 without extension (as python does under import). This allows running
1467 scripts and reloading the definitions in them without calling code
1471 scripts and reloading the definitions in them without calling code
1468 protected by an ' if __name__ == "__main__" ' clause.
1472 protected by an ' if __name__ == "__main__" ' clause.
1469
1473
1470 -i: run the file in IPython's namespace instead of an empty one. This
1474 -i: run the file in IPython's namespace instead of an empty one. This
1471 is useful if you are experimenting with code written in a text editor
1475 is useful if you are experimenting with code written in a text editor
1472 which depends on variables defined interactively.
1476 which depends on variables defined interactively.
1473
1477
1474 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1478 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1475 being run. This is particularly useful if IPython is being used to
1479 being run. This is particularly useful if IPython is being used to
1476 run unittests, which always exit with a sys.exit() call. In such
1480 run unittests, which always exit with a sys.exit() call. In such
1477 cases you are interested in the output of the test results, not in
1481 cases you are interested in the output of the test results, not in
1478 seeing a traceback of the unittest module.
1482 seeing a traceback of the unittest module.
1479
1483
1480 -t: print timing information at the end of the run. IPython will give
1484 -t: print timing information at the end of the run. IPython will give
1481 you an estimated CPU time consumption for your script, which under
1485 you an estimated CPU time consumption for your script, which under
1482 Unix uses the resource module to avoid the wraparound problems of
1486 Unix uses the resource module to avoid the wraparound problems of
1483 time.clock(). Under Unix, an estimate of time spent on system tasks
1487 time.clock(). Under Unix, an estimate of time spent on system tasks
1484 is also given (for Windows platforms this is reported as 0.0).
1488 is also given (for Windows platforms this is reported as 0.0).
1485
1489
1486 If -t is given, an additional -N<N> option can be given, where <N>
1490 If -t is given, an additional -N<N> option can be given, where <N>
1487 must be an integer indicating how many times you want the script to
1491 must be an integer indicating how many times you want the script to
1488 run. The final timing report will include total and per run results.
1492 run. The final timing report will include total and per run results.
1489
1493
1490 For example (testing the script uniq_stable.py):
1494 For example (testing the script uniq_stable.py):
1491
1495
1492 In [1]: run -t uniq_stable
1496 In [1]: run -t uniq_stable
1493
1497
1494 IPython CPU timings (estimated):\\
1498 IPython CPU timings (estimated):\\
1495 User : 0.19597 s.\\
1499 User : 0.19597 s.\\
1496 System: 0.0 s.\\
1500 System: 0.0 s.\\
1497
1501
1498 In [2]: run -t -N5 uniq_stable
1502 In [2]: run -t -N5 uniq_stable
1499
1503
1500 IPython CPU timings (estimated):\\
1504 IPython CPU timings (estimated):\\
1501 Total runs performed: 5\\
1505 Total runs performed: 5\\
1502 Times : Total Per run\\
1506 Times : Total Per run\\
1503 User : 0.910862 s, 0.1821724 s.\\
1507 User : 0.910862 s, 0.1821724 s.\\
1504 System: 0.0 s, 0.0 s.
1508 System: 0.0 s, 0.0 s.
1505
1509
1506 -d: run your program under the control of pdb, the Python debugger.
1510 -d: run your program under the control of pdb, the Python debugger.
1507 This allows you to execute your program step by step, watch variables,
1511 This allows you to execute your program step by step, watch variables,
1508 etc. Internally, what IPython does is similar to calling:
1512 etc. Internally, what IPython does is similar to calling:
1509
1513
1510 pdb.run('execfile("YOURFILENAME")')
1514 pdb.run('execfile("YOURFILENAME")')
1511
1515
1512 with a breakpoint set on line 1 of your file. You can change the line
1516 with a breakpoint set on line 1 of your file. You can change the line
1513 number for this automatic breakpoint to be <N> by using the -bN option
1517 number for this automatic breakpoint to be <N> by using the -bN option
1514 (where N must be an integer). For example:
1518 (where N must be an integer). For example:
1515
1519
1516 %run -d -b40 myscript
1520 %run -d -b40 myscript
1517
1521
1518 will set the first breakpoint at line 40 in myscript.py. Note that
1522 will set the first breakpoint at line 40 in myscript.py. Note that
1519 the first breakpoint must be set on a line which actually does
1523 the first breakpoint must be set on a line which actually does
1520 something (not a comment or docstring) for it to stop execution.
1524 something (not a comment or docstring) for it to stop execution.
1521
1525
1522 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1526 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1523 first enter 'c' (without qoutes) to start execution up to the first
1527 first enter 'c' (without qoutes) to start execution up to the first
1524 breakpoint.
1528 breakpoint.
1525
1529
1526 Entering 'help' gives information about the use of the debugger. You
1530 Entering 'help' gives information about the use of the debugger. You
1527 can easily see pdb's full documentation with "import pdb;pdb.help()"
1531 can easily see pdb's full documentation with "import pdb;pdb.help()"
1528 at a prompt.
1532 at a prompt.
1529
1533
1530 -p: run program under the control of the Python profiler module (which
1534 -p: run program under the control of the Python profiler module (which
1531 prints a detailed report of execution times, function calls, etc).
1535 prints a detailed report of execution times, function calls, etc).
1532
1536
1533 You can pass other options after -p which affect the behavior of the
1537 You can pass other options after -p which affect the behavior of the
1534 profiler itself. See the docs for %prun for details.
1538 profiler itself. See the docs for %prun for details.
1535
1539
1536 In this mode, the program's variables do NOT propagate back to the
1540 In this mode, the program's variables do NOT propagate back to the
1537 IPython interactive namespace (because they remain in the namespace
1541 IPython interactive namespace (because they remain in the namespace
1538 where the profiler executes them).
1542 where the profiler executes them).
1539
1543
1540 Internally this triggers a call to %prun, see its documentation for
1544 Internally this triggers a call to %prun, see its documentation for
1541 details on the options available specifically for profiling.
1545 details on the options available specifically for profiling.
1542
1546
1543 There is one special usage for which the text above doesn't apply:
1547 There is one special usage for which the text above doesn't apply:
1544 if the filename ends with .ipy, the file is run as ipython script,
1548 if the filename ends with .ipy, the file is run as ipython script,
1545 just as if the commands were written on IPython prompt.
1549 just as if the commands were written on IPython prompt.
1546 """
1550 """
1547
1551
1548 # get arguments and set sys.argv for program to be run.
1552 # get arguments and set sys.argv for program to be run.
1549 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1553 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1550 mode='list',list_all=1)
1554 mode='list',list_all=1)
1551
1555
1552 try:
1556 try:
1553 filename = file_finder(arg_lst[0])
1557 filename = file_finder(arg_lst[0])
1554 except IndexError:
1558 except IndexError:
1555 warn('you must provide at least a filename.')
1559 warn('you must provide at least a filename.')
1556 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1560 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1557 return
1561 return
1558 except IOError,msg:
1562 except IOError,msg:
1559 error(msg)
1563 error(msg)
1560 return
1564 return
1561
1565
1562 if filename.lower().endswith('.ipy'):
1566 if filename.lower().endswith('.ipy'):
1563 self.shell.safe_execfile_ipy(filename)
1567 self.shell.safe_execfile_ipy(filename)
1564 return
1568 return
1565
1569
1566 # Control the response to exit() calls made by the script being run
1570 # Control the response to exit() calls made by the script being run
1567 exit_ignore = opts.has_key('e')
1571 exit_ignore = opts.has_key('e')
1568
1572
1569 # Make sure that the running script gets a proper sys.argv as if it
1573 # Make sure that the running script gets a proper sys.argv as if it
1570 # were run from a system shell.
1574 # were run from a system shell.
1571 save_argv = sys.argv # save it for later restoring
1575 save_argv = sys.argv # save it for later restoring
1572 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1576 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1573
1577
1574 if opts.has_key('i'):
1578 if opts.has_key('i'):
1575 # Run in user's interactive namespace
1579 # Run in user's interactive namespace
1576 prog_ns = self.shell.user_ns
1580 prog_ns = self.shell.user_ns
1577 __name__save = self.shell.user_ns['__name__']
1581 __name__save = self.shell.user_ns['__name__']
1578 prog_ns['__name__'] = '__main__'
1582 prog_ns['__name__'] = '__main__'
1579 main_mod = self.shell.new_main_mod(prog_ns)
1583 main_mod = self.shell.new_main_mod(prog_ns)
1580 else:
1584 else:
1581 # Run in a fresh, empty namespace
1585 # Run in a fresh, empty namespace
1582 if opts.has_key('n'):
1586 if opts.has_key('n'):
1583 name = os.path.splitext(os.path.basename(filename))[0]
1587 name = os.path.splitext(os.path.basename(filename))[0]
1584 else:
1588 else:
1585 name = '__main__'
1589 name = '__main__'
1586
1590
1587 main_mod = self.shell.new_main_mod()
1591 main_mod = self.shell.new_main_mod()
1588 prog_ns = main_mod.__dict__
1592 prog_ns = main_mod.__dict__
1589 prog_ns['__name__'] = name
1593 prog_ns['__name__'] = name
1590
1594
1591 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1595 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1592 # set the __file__ global in the script's namespace
1596 # set the __file__ global in the script's namespace
1593 prog_ns['__file__'] = filename
1597 prog_ns['__file__'] = filename
1594
1598
1595 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1599 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1596 # that, if we overwrite __main__, we replace it at the end
1600 # that, if we overwrite __main__, we replace it at the end
1597 main_mod_name = prog_ns['__name__']
1601 main_mod_name = prog_ns['__name__']
1598
1602
1599 if main_mod_name == '__main__':
1603 if main_mod_name == '__main__':
1600 restore_main = sys.modules['__main__']
1604 restore_main = sys.modules['__main__']
1601 else:
1605 else:
1602 restore_main = False
1606 restore_main = False
1603
1607
1604 # This needs to be undone at the end to prevent holding references to
1608 # This needs to be undone at the end to prevent holding references to
1605 # every single object ever created.
1609 # every single object ever created.
1606 sys.modules[main_mod_name] = main_mod
1610 sys.modules[main_mod_name] = main_mod
1607
1611
1608 try:
1612 try:
1609 stats = None
1613 stats = None
1610 with self.readline_no_record:
1614 with self.readline_no_record:
1611 if opts.has_key('p'):
1615 if opts.has_key('p'):
1612 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1616 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1613 else:
1617 else:
1614 if opts.has_key('d'):
1618 if opts.has_key('d'):
1615 deb = debugger.Pdb(self.shell.colors)
1619 deb = debugger.Pdb(self.shell.colors)
1616 # reset Breakpoint state, which is moronically kept
1620 # reset Breakpoint state, which is moronically kept
1617 # in a class
1621 # in a class
1618 bdb.Breakpoint.next = 1
1622 bdb.Breakpoint.next = 1
1619 bdb.Breakpoint.bplist = {}
1623 bdb.Breakpoint.bplist = {}
1620 bdb.Breakpoint.bpbynumber = [None]
1624 bdb.Breakpoint.bpbynumber = [None]
1621 # Set an initial breakpoint to stop execution
1625 # Set an initial breakpoint to stop execution
1622 maxtries = 10
1626 maxtries = 10
1623 bp = int(opts.get('b',[1])[0])
1627 bp = int(opts.get('b',[1])[0])
1624 checkline = deb.checkline(filename,bp)
1628 checkline = deb.checkline(filename,bp)
1625 if not checkline:
1629 if not checkline:
1626 for bp in range(bp+1,bp+maxtries+1):
1630 for bp in range(bp+1,bp+maxtries+1):
1627 if deb.checkline(filename,bp):
1631 if deb.checkline(filename,bp):
1628 break
1632 break
1629 else:
1633 else:
1630 msg = ("\nI failed to find a valid line to set "
1634 msg = ("\nI failed to find a valid line to set "
1631 "a breakpoint\n"
1635 "a breakpoint\n"
1632 "after trying up to line: %s.\n"
1636 "after trying up to line: %s.\n"
1633 "Please set a valid breakpoint manually "
1637 "Please set a valid breakpoint manually "
1634 "with the -b option." % bp)
1638 "with the -b option." % bp)
1635 error(msg)
1639 error(msg)
1636 return
1640 return
1637 # if we find a good linenumber, set the breakpoint
1641 # if we find a good linenumber, set the breakpoint
1638 deb.do_break('%s:%s' % (filename,bp))
1642 deb.do_break('%s:%s' % (filename,bp))
1639 # Start file run
1643 # Start file run
1640 print "NOTE: Enter 'c' at the",
1644 print "NOTE: Enter 'c' at the",
1641 print "%s prompt to start your script." % deb.prompt
1645 print "%s prompt to start your script." % deb.prompt
1642 try:
1646 try:
1643 deb.run('execfile("%s")' % filename,prog_ns)
1647 deb.run('execfile("%s")' % filename,prog_ns)
1644
1648
1645 except:
1649 except:
1646 etype, value, tb = sys.exc_info()
1650 etype, value, tb = sys.exc_info()
1647 # Skip three frames in the traceback: the %run one,
1651 # Skip three frames in the traceback: the %run one,
1648 # one inside bdb.py, and the command-line typed by the
1652 # one inside bdb.py, and the command-line typed by the
1649 # user (run by exec in pdb itself).
1653 # user (run by exec in pdb itself).
1650 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1654 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1651 else:
1655 else:
1652 if runner is None:
1656 if runner is None:
1653 runner = self.shell.safe_execfile
1657 runner = self.shell.safe_execfile
1654 if opts.has_key('t'):
1658 if opts.has_key('t'):
1655 # timed execution
1659 # timed execution
1656 try:
1660 try:
1657 nruns = int(opts['N'][0])
1661 nruns = int(opts['N'][0])
1658 if nruns < 1:
1662 if nruns < 1:
1659 error('Number of runs must be >=1')
1663 error('Number of runs must be >=1')
1660 return
1664 return
1661 except (KeyError):
1665 except (KeyError):
1662 nruns = 1
1666 nruns = 1
1663 if nruns == 1:
1667 if nruns == 1:
1664 t0 = clock2()
1668 t0 = clock2()
1665 runner(filename,prog_ns,prog_ns,
1669 runner(filename,prog_ns,prog_ns,
1666 exit_ignore=exit_ignore)
1670 exit_ignore=exit_ignore)
1667 t1 = clock2()
1671 t1 = clock2()
1668 t_usr = t1[0]-t0[0]
1672 t_usr = t1[0]-t0[0]
1669 t_sys = t1[1]-t0[1]
1673 t_sys = t1[1]-t0[1]
1670 print "\nIPython CPU timings (estimated):"
1674 print "\nIPython CPU timings (estimated):"
1671 print " User : %10s s." % t_usr
1675 print " User : %10s s." % t_usr
1672 print " System: %10s s." % t_sys
1676 print " System: %10s s." % t_sys
1673 else:
1677 else:
1674 runs = range(nruns)
1678 runs = range(nruns)
1675 t0 = clock2()
1679 t0 = clock2()
1676 for nr in runs:
1680 for nr in runs:
1677 runner(filename,prog_ns,prog_ns,
1681 runner(filename,prog_ns,prog_ns,
1678 exit_ignore=exit_ignore)
1682 exit_ignore=exit_ignore)
1679 t1 = clock2()
1683 t1 = clock2()
1680 t_usr = t1[0]-t0[0]
1684 t_usr = t1[0]-t0[0]
1681 t_sys = t1[1]-t0[1]
1685 t_sys = t1[1]-t0[1]
1682 print "\nIPython CPU timings (estimated):"
1686 print "\nIPython CPU timings (estimated):"
1683 print "Total runs performed:",nruns
1687 print "Total runs performed:",nruns
1684 print " Times : %10s %10s" % ('Total','Per run')
1688 print " Times : %10s %10s" % ('Total','Per run')
1685 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1689 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1686 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1690 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1687
1691
1688 else:
1692 else:
1689 # regular execution
1693 # regular execution
1690 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1694 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1691
1695
1692 if opts.has_key('i'):
1696 if opts.has_key('i'):
1693 self.shell.user_ns['__name__'] = __name__save
1697 self.shell.user_ns['__name__'] = __name__save
1694 else:
1698 else:
1695 # The shell MUST hold a reference to prog_ns so after %run
1699 # The shell MUST hold a reference to prog_ns so after %run
1696 # exits, the python deletion mechanism doesn't zero it out
1700 # exits, the python deletion mechanism doesn't zero it out
1697 # (leaving dangling references).
1701 # (leaving dangling references).
1698 self.shell.cache_main_mod(prog_ns,filename)
1702 self.shell.cache_main_mod(prog_ns,filename)
1699 # update IPython interactive namespace
1703 # update IPython interactive namespace
1700
1704
1701 # Some forms of read errors on the file may mean the
1705 # Some forms of read errors on the file may mean the
1702 # __name__ key was never set; using pop we don't have to
1706 # __name__ key was never set; using pop we don't have to
1703 # worry about a possible KeyError.
1707 # worry about a possible KeyError.
1704 prog_ns.pop('__name__', None)
1708 prog_ns.pop('__name__', None)
1705
1709
1706 self.shell.user_ns.update(prog_ns)
1710 self.shell.user_ns.update(prog_ns)
1707 finally:
1711 finally:
1708 # It's a bit of a mystery why, but __builtins__ can change from
1712 # It's a bit of a mystery why, but __builtins__ can change from
1709 # being a module to becoming a dict missing some key data after
1713 # being a module to becoming a dict missing some key data after
1710 # %run. As best I can see, this is NOT something IPython is doing
1714 # %run. As best I can see, this is NOT something IPython is doing
1711 # at all, and similar problems have been reported before:
1715 # at all, and similar problems have been reported before:
1712 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1716 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1713 # Since this seems to be done by the interpreter itself, the best
1717 # Since this seems to be done by the interpreter itself, the best
1714 # we can do is to at least restore __builtins__ for the user on
1718 # we can do is to at least restore __builtins__ for the user on
1715 # exit.
1719 # exit.
1716 self.shell.user_ns['__builtins__'] = __builtin__
1720 self.shell.user_ns['__builtins__'] = __builtin__
1717
1721
1718 # Ensure key global structures are restored
1722 # Ensure key global structures are restored
1719 sys.argv = save_argv
1723 sys.argv = save_argv
1720 if restore_main:
1724 if restore_main:
1721 sys.modules['__main__'] = restore_main
1725 sys.modules['__main__'] = restore_main
1722 else:
1726 else:
1723 # Remove from sys.modules the reference to main_mod we'd
1727 # Remove from sys.modules the reference to main_mod we'd
1724 # added. Otherwise it will trap references to objects
1728 # added. Otherwise it will trap references to objects
1725 # contained therein.
1729 # contained therein.
1726 del sys.modules[main_mod_name]
1730 del sys.modules[main_mod_name]
1727
1731
1728 return stats
1732 return stats
1729
1733
1730 @testdec.skip_doctest
1734 @testdec.skip_doctest
1731 def magic_timeit(self, parameter_s =''):
1735 def magic_timeit(self, parameter_s =''):
1732 """Time execution of a Python statement or expression
1736 """Time execution of a Python statement or expression
1733
1737
1734 Usage:\\
1738 Usage:\\
1735 %timeit [-n<N> -r<R> [-t|-c]] statement
1739 %timeit [-n<N> -r<R> [-t|-c]] statement
1736
1740
1737 Time execution of a Python statement or expression using the timeit
1741 Time execution of a Python statement or expression using the timeit
1738 module.
1742 module.
1739
1743
1740 Options:
1744 Options:
1741 -n<N>: execute the given statement <N> times in a loop. If this value
1745 -n<N>: execute the given statement <N> times in a loop. If this value
1742 is not given, a fitting value is chosen.
1746 is not given, a fitting value is chosen.
1743
1747
1744 -r<R>: repeat the loop iteration <R> times and take the best result.
1748 -r<R>: repeat the loop iteration <R> times and take the best result.
1745 Default: 3
1749 Default: 3
1746
1750
1747 -t: use time.time to measure the time, which is the default on Unix.
1751 -t: use time.time to measure the time, which is the default on Unix.
1748 This function measures wall time.
1752 This function measures wall time.
1749
1753
1750 -c: use time.clock to measure the time, which is the default on
1754 -c: use time.clock to measure the time, which is the default on
1751 Windows and measures wall time. On Unix, resource.getrusage is used
1755 Windows and measures wall time. On Unix, resource.getrusage is used
1752 instead and returns the CPU user time.
1756 instead and returns the CPU user time.
1753
1757
1754 -p<P>: use a precision of <P> digits to display the timing result.
1758 -p<P>: use a precision of <P> digits to display the timing result.
1755 Default: 3
1759 Default: 3
1756
1760
1757
1761
1758 Examples:
1762 Examples:
1759
1763
1760 In [1]: %timeit pass
1764 In [1]: %timeit pass
1761 10000000 loops, best of 3: 53.3 ns per loop
1765 10000000 loops, best of 3: 53.3 ns per loop
1762
1766
1763 In [2]: u = None
1767 In [2]: u = None
1764
1768
1765 In [3]: %timeit u is None
1769 In [3]: %timeit u is None
1766 10000000 loops, best of 3: 184 ns per loop
1770 10000000 loops, best of 3: 184 ns per loop
1767
1771
1768 In [4]: %timeit -r 4 u == None
1772 In [4]: %timeit -r 4 u == None
1769 1000000 loops, best of 4: 242 ns per loop
1773 1000000 loops, best of 4: 242 ns per loop
1770
1774
1771 In [5]: import time
1775 In [5]: import time
1772
1776
1773 In [6]: %timeit -n1 time.sleep(2)
1777 In [6]: %timeit -n1 time.sleep(2)
1774 1 loops, best of 3: 2 s per loop
1778 1 loops, best of 3: 2 s per loop
1775
1779
1776
1780
1777 The times reported by %timeit will be slightly higher than those
1781 The times reported by %timeit will be slightly higher than those
1778 reported by the timeit.py script when variables are accessed. This is
1782 reported by the timeit.py script when variables are accessed. This is
1779 due to the fact that %timeit executes the statement in the namespace
1783 due to the fact that %timeit executes the statement in the namespace
1780 of the shell, compared with timeit.py, which uses a single setup
1784 of the shell, compared with timeit.py, which uses a single setup
1781 statement to import function or create variables. Generally, the bias
1785 statement to import function or create variables. Generally, the bias
1782 does not matter as long as results from timeit.py are not mixed with
1786 does not matter as long as results from timeit.py are not mixed with
1783 those from %timeit."""
1787 those from %timeit."""
1784
1788
1785 import timeit
1789 import timeit
1786 import math
1790 import math
1787
1791
1788 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1792 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1789 # certain terminals. Until we figure out a robust way of
1793 # certain terminals. Until we figure out a robust way of
1790 # auto-detecting if the terminal can deal with it, use plain 'us' for
1794 # auto-detecting if the terminal can deal with it, use plain 'us' for
1791 # microseconds. I am really NOT happy about disabling the proper
1795 # microseconds. I am really NOT happy about disabling the proper
1792 # 'micro' prefix, but crashing is worse... If anyone knows what the
1796 # 'micro' prefix, but crashing is worse... If anyone knows what the
1793 # right solution for this is, I'm all ears...
1797 # right solution for this is, I'm all ears...
1794 #
1798 #
1795 # Note: using
1799 # Note: using
1796 #
1800 #
1797 # s = u'\xb5'
1801 # s = u'\xb5'
1798 # s.encode(sys.getdefaultencoding())
1802 # s.encode(sys.getdefaultencoding())
1799 #
1803 #
1800 # is not sufficient, as I've seen terminals where that fails but
1804 # is not sufficient, as I've seen terminals where that fails but
1801 # print s
1805 # print s
1802 #
1806 #
1803 # succeeds
1807 # succeeds
1804 #
1808 #
1805 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1809 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1806
1810
1807 #units = [u"s", u"ms",u'\xb5',"ns"]
1811 #units = [u"s", u"ms",u'\xb5',"ns"]
1808 units = [u"s", u"ms",u'us',"ns"]
1812 units = [u"s", u"ms",u'us',"ns"]
1809
1813
1810 scaling = [1, 1e3, 1e6, 1e9]
1814 scaling = [1, 1e3, 1e6, 1e9]
1811
1815
1812 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1816 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1813 posix=False)
1817 posix=False)
1814 if stmt == "":
1818 if stmt == "":
1815 return
1819 return
1816 timefunc = timeit.default_timer
1820 timefunc = timeit.default_timer
1817 number = int(getattr(opts, "n", 0))
1821 number = int(getattr(opts, "n", 0))
1818 repeat = int(getattr(opts, "r", timeit.default_repeat))
1822 repeat = int(getattr(opts, "r", timeit.default_repeat))
1819 precision = int(getattr(opts, "p", 3))
1823 precision = int(getattr(opts, "p", 3))
1820 if hasattr(opts, "t"):
1824 if hasattr(opts, "t"):
1821 timefunc = time.time
1825 timefunc = time.time
1822 if hasattr(opts, "c"):
1826 if hasattr(opts, "c"):
1823 timefunc = clock
1827 timefunc = clock
1824
1828
1825 timer = timeit.Timer(timer=timefunc)
1829 timer = timeit.Timer(timer=timefunc)
1826 # this code has tight coupling to the inner workings of timeit.Timer,
1830 # this code has tight coupling to the inner workings of timeit.Timer,
1827 # but is there a better way to achieve that the code stmt has access
1831 # but is there a better way to achieve that the code stmt has access
1828 # to the shell namespace?
1832 # to the shell namespace?
1829
1833
1830 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1834 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1831 'setup': "pass"}
1835 'setup': "pass"}
1832 # Track compilation time so it can be reported if too long
1836 # Track compilation time so it can be reported if too long
1833 # Minimum time above which compilation time will be reported
1837 # Minimum time above which compilation time will be reported
1834 tc_min = 0.1
1838 tc_min = 0.1
1835
1839
1836 t0 = clock()
1840 t0 = clock()
1837 code = compile(src, "<magic-timeit>", "exec")
1841 code = compile(src, "<magic-timeit>", "exec")
1838 tc = clock()-t0
1842 tc = clock()-t0
1839
1843
1840 ns = {}
1844 ns = {}
1841 exec code in self.shell.user_ns, ns
1845 exec code in self.shell.user_ns, ns
1842 timer.inner = ns["inner"]
1846 timer.inner = ns["inner"]
1843
1847
1844 if number == 0:
1848 if number == 0:
1845 # determine number so that 0.2 <= total time < 2.0
1849 # determine number so that 0.2 <= total time < 2.0
1846 number = 1
1850 number = 1
1847 for i in range(1, 10):
1851 for i in range(1, 10):
1848 if timer.timeit(number) >= 0.2:
1852 if timer.timeit(number) >= 0.2:
1849 break
1853 break
1850 number *= 10
1854 number *= 10
1851
1855
1852 best = min(timer.repeat(repeat, number)) / number
1856 best = min(timer.repeat(repeat, number)) / number
1853
1857
1854 if best > 0.0 and best < 1000.0:
1858 if best > 0.0 and best < 1000.0:
1855 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1859 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1856 elif best >= 1000.0:
1860 elif best >= 1000.0:
1857 order = 0
1861 order = 0
1858 else:
1862 else:
1859 order = 3
1863 order = 3
1860 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1864 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1861 precision,
1865 precision,
1862 best * scaling[order],
1866 best * scaling[order],
1863 units[order])
1867 units[order])
1864 if tc > tc_min:
1868 if tc > tc_min:
1865 print "Compiler time: %.2f s" % tc
1869 print "Compiler time: %.2f s" % tc
1866
1870
1867 @testdec.skip_doctest
1871 @testdec.skip_doctest
1868 @needs_local_scope
1872 @needs_local_scope
1869 def magic_time(self,parameter_s = ''):
1873 def magic_time(self,parameter_s = ''):
1870 """Time execution of a Python statement or expression.
1874 """Time execution of a Python statement or expression.
1871
1875
1872 The CPU and wall clock times are printed, and the value of the
1876 The CPU and wall clock times are printed, and the value of the
1873 expression (if any) is returned. Note that under Win32, system time
1877 expression (if any) is returned. Note that under Win32, system time
1874 is always reported as 0, since it can not be measured.
1878 is always reported as 0, since it can not be measured.
1875
1879
1876 This function provides very basic timing functionality. In Python
1880 This function provides very basic timing functionality. In Python
1877 2.3, the timeit module offers more control and sophistication, so this
1881 2.3, the timeit module offers more control and sophistication, so this
1878 could be rewritten to use it (patches welcome).
1882 could be rewritten to use it (patches welcome).
1879
1883
1880 Some examples:
1884 Some examples:
1881
1885
1882 In [1]: time 2**128
1886 In [1]: time 2**128
1883 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1887 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1884 Wall time: 0.00
1888 Wall time: 0.00
1885 Out[1]: 340282366920938463463374607431768211456L
1889 Out[1]: 340282366920938463463374607431768211456L
1886
1890
1887 In [2]: n = 1000000
1891 In [2]: n = 1000000
1888
1892
1889 In [3]: time sum(range(n))
1893 In [3]: time sum(range(n))
1890 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1894 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1891 Wall time: 1.37
1895 Wall time: 1.37
1892 Out[3]: 499999500000L
1896 Out[3]: 499999500000L
1893
1897
1894 In [4]: time print 'hello world'
1898 In [4]: time print 'hello world'
1895 hello world
1899 hello world
1896 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1900 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1897 Wall time: 0.00
1901 Wall time: 0.00
1898
1902
1899 Note that the time needed by Python to compile the given expression
1903 Note that the time needed by Python to compile the given expression
1900 will be reported if it is more than 0.1s. In this example, the
1904 will be reported if it is more than 0.1s. In this example, the
1901 actual exponentiation is done by Python at compilation time, so while
1905 actual exponentiation is done by Python at compilation time, so while
1902 the expression can take a noticeable amount of time to compute, that
1906 the expression can take a noticeable amount of time to compute, that
1903 time is purely due to the compilation:
1907 time is purely due to the compilation:
1904
1908
1905 In [5]: time 3**9999;
1909 In [5]: time 3**9999;
1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1910 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 Wall time: 0.00 s
1911 Wall time: 0.00 s
1908
1912
1909 In [6]: time 3**999999;
1913 In [6]: time 3**999999;
1910 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1914 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1911 Wall time: 0.00 s
1915 Wall time: 0.00 s
1912 Compiler : 0.78 s
1916 Compiler : 0.78 s
1913 """
1917 """
1914
1918
1915 # fail immediately if the given expression can't be compiled
1919 # fail immediately if the given expression can't be compiled
1916
1920
1917 expr = self.shell.prefilter(parameter_s,False)
1921 expr = self.shell.prefilter(parameter_s,False)
1918
1922
1919 # Minimum time above which compilation time will be reported
1923 # Minimum time above which compilation time will be reported
1920 tc_min = 0.1
1924 tc_min = 0.1
1921
1925
1922 try:
1926 try:
1923 mode = 'eval'
1927 mode = 'eval'
1924 t0 = clock()
1928 t0 = clock()
1925 code = compile(expr,'<timed eval>',mode)
1929 code = compile(expr,'<timed eval>',mode)
1926 tc = clock()-t0
1930 tc = clock()-t0
1927 except SyntaxError:
1931 except SyntaxError:
1928 mode = 'exec'
1932 mode = 'exec'
1929 t0 = clock()
1933 t0 = clock()
1930 code = compile(expr,'<timed exec>',mode)
1934 code = compile(expr,'<timed exec>',mode)
1931 tc = clock()-t0
1935 tc = clock()-t0
1932 # skew measurement as little as possible
1936 # skew measurement as little as possible
1933 glob = self.shell.user_ns
1937 glob = self.shell.user_ns
1934 locs = self._magic_locals
1938 locs = self._magic_locals
1935 clk = clock2
1939 clk = clock2
1936 wtime = time.time
1940 wtime = time.time
1937 # time execution
1941 # time execution
1938 wall_st = wtime()
1942 wall_st = wtime()
1939 if mode=='eval':
1943 if mode=='eval':
1940 st = clk()
1944 st = clk()
1941 out = eval(code, glob, locs)
1945 out = eval(code, glob, locs)
1942 end = clk()
1946 end = clk()
1943 else:
1947 else:
1944 st = clk()
1948 st = clk()
1945 exec code in glob, locs
1949 exec code in glob, locs
1946 end = clk()
1950 end = clk()
1947 out = None
1951 out = None
1948 wall_end = wtime()
1952 wall_end = wtime()
1949 # Compute actual times and report
1953 # Compute actual times and report
1950 wall_time = wall_end-wall_st
1954 wall_time = wall_end-wall_st
1951 cpu_user = end[0]-st[0]
1955 cpu_user = end[0]-st[0]
1952 cpu_sys = end[1]-st[1]
1956 cpu_sys = end[1]-st[1]
1953 cpu_tot = cpu_user+cpu_sys
1957 cpu_tot = cpu_user+cpu_sys
1954 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1958 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1955 (cpu_user,cpu_sys,cpu_tot)
1959 (cpu_user,cpu_sys,cpu_tot)
1956 print "Wall time: %.2f s" % wall_time
1960 print "Wall time: %.2f s" % wall_time
1957 if tc > tc_min:
1961 if tc > tc_min:
1958 print "Compiler : %.2f s" % tc
1962 print "Compiler : %.2f s" % tc
1959 return out
1963 return out
1960
1964
1961 @testdec.skip_doctest
1965 @testdec.skip_doctest
1962 def magic_macro(self,parameter_s = ''):
1966 def magic_macro(self,parameter_s = ''):
1963 """Define a macro for future re-execution. It accepts ranges of history,
1967 """Define a macro for future re-execution. It accepts ranges of history,
1964 filenames or string objects.
1968 filenames or string objects.
1965
1969
1966 Usage:\\
1970 Usage:\\
1967 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1971 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1968
1972
1969 Options:
1973 Options:
1970
1974
1971 -r: use 'raw' input. By default, the 'processed' history is used,
1975 -r: use 'raw' input. By default, the 'processed' history is used,
1972 so that magics are loaded in their transformed version to valid
1976 so that magics are loaded in their transformed version to valid
1973 Python. If this option is given, the raw input as typed as the
1977 Python. If this option is given, the raw input as typed as the
1974 command line is used instead.
1978 command line is used instead.
1975
1979
1976 This will define a global variable called `name` which is a string
1980 This will define a global variable called `name` which is a string
1977 made of joining the slices and lines you specify (n1,n2,... numbers
1981 made of joining the slices and lines you specify (n1,n2,... numbers
1978 above) from your input history into a single string. This variable
1982 above) from your input history into a single string. This variable
1979 acts like an automatic function which re-executes those lines as if
1983 acts like an automatic function which re-executes those lines as if
1980 you had typed them. You just type 'name' at the prompt and the code
1984 you had typed them. You just type 'name' at the prompt and the code
1981 executes.
1985 executes.
1982
1986
1983 The syntax for indicating input ranges is described in %history.
1987 The syntax for indicating input ranges is described in %history.
1984
1988
1985 Note: as a 'hidden' feature, you can also use traditional python slice
1989 Note: as a 'hidden' feature, you can also use traditional python slice
1986 notation, where N:M means numbers N through M-1.
1990 notation, where N:M means numbers N through M-1.
1987
1991
1988 For example, if your history contains (%hist prints it):
1992 For example, if your history contains (%hist prints it):
1989
1993
1990 44: x=1
1994 44: x=1
1991 45: y=3
1995 45: y=3
1992 46: z=x+y
1996 46: z=x+y
1993 47: print x
1997 47: print x
1994 48: a=5
1998 48: a=5
1995 49: print 'x',x,'y',y
1999 49: print 'x',x,'y',y
1996
2000
1997 you can create a macro with lines 44 through 47 (included) and line 49
2001 you can create a macro with lines 44 through 47 (included) and line 49
1998 called my_macro with:
2002 called my_macro with:
1999
2003
2000 In [55]: %macro my_macro 44-47 49
2004 In [55]: %macro my_macro 44-47 49
2001
2005
2002 Now, typing `my_macro` (without quotes) will re-execute all this code
2006 Now, typing `my_macro` (without quotes) will re-execute all this code
2003 in one pass.
2007 in one pass.
2004
2008
2005 You don't need to give the line-numbers in order, and any given line
2009 You don't need to give the line-numbers in order, and any given line
2006 number can appear multiple times. You can assemble macros with any
2010 number can appear multiple times. You can assemble macros with any
2007 lines from your input history in any order.
2011 lines from your input history in any order.
2008
2012
2009 The macro is a simple object which holds its value in an attribute,
2013 The macro is a simple object which holds its value in an attribute,
2010 but IPython's display system checks for macros and executes them as
2014 but IPython's display system checks for macros and executes them as
2011 code instead of printing them when you type their name.
2015 code instead of printing them when you type their name.
2012
2016
2013 You can view a macro's contents by explicitly printing it with:
2017 You can view a macro's contents by explicitly printing it with:
2014
2018
2015 'print macro_name'.
2019 'print macro_name'.
2016
2020
2017 """
2021 """
2018
2022
2019 opts,args = self.parse_options(parameter_s,'r',mode='list')
2023 opts,args = self.parse_options(parameter_s,'r',mode='list')
2020 if not args: # List existing macros
2024 if not args: # List existing macros
2021 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2025 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2022 isinstance(v, Macro))
2026 isinstance(v, Macro))
2023 if len(args) == 1:
2027 if len(args) == 1:
2024 raise UsageError(
2028 raise UsageError(
2025 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2029 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2026 name, codefrom = args[0], " ".join(args[1:])
2030 name, codefrom = args[0], " ".join(args[1:])
2027
2031
2028 #print 'rng',ranges # dbg
2032 #print 'rng',ranges # dbg
2029 try:
2033 try:
2030 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2034 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2031 except (ValueError, TypeError) as e:
2035 except (ValueError, TypeError) as e:
2032 print e.args[0]
2036 print e.args[0]
2033 return
2037 return
2034 macro = Macro(lines)
2038 macro = Macro(lines)
2035 self.shell.define_macro(name, macro)
2039 self.shell.define_macro(name, macro)
2036 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2040 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2037 print '=== Macro contents: ==='
2041 print '=== Macro contents: ==='
2038 print macro,
2042 print macro,
2039
2043
2040 def magic_save(self,parameter_s = ''):
2044 def magic_save(self,parameter_s = ''):
2041 """Save a set of lines or a macro to a given filename.
2045 """Save a set of lines or a macro to a given filename.
2042
2046
2043 Usage:\\
2047 Usage:\\
2044 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2048 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2045
2049
2046 Options:
2050 Options:
2047
2051
2048 -r: use 'raw' input. By default, the 'processed' history is used,
2052 -r: use 'raw' input. By default, the 'processed' history is used,
2049 so that magics are loaded in their transformed version to valid
2053 so that magics are loaded in their transformed version to valid
2050 Python. If this option is given, the raw input as typed as the
2054 Python. If this option is given, the raw input as typed as the
2051 command line is used instead.
2055 command line is used instead.
2052
2056
2053 This function uses the same syntax as %history for input ranges,
2057 This function uses the same syntax as %history for input ranges,
2054 then saves the lines to the filename you specify.
2058 then saves the lines to the filename you specify.
2055
2059
2056 It adds a '.py' extension to the file if you don't do so yourself, and
2060 It adds a '.py' extension to the file if you don't do so yourself, and
2057 it asks for confirmation before overwriting existing files."""
2061 it asks for confirmation before overwriting existing files."""
2058
2062
2059 opts,args = self.parse_options(parameter_s,'r',mode='list')
2063 opts,args = self.parse_options(parameter_s,'r',mode='list')
2060 fname, codefrom = args[0], " ".join(args[1:])
2064 fname, codefrom = args[0], " ".join(args[1:])
2061 if not fname.endswith('.py'):
2065 if not fname.endswith('.py'):
2062 fname += '.py'
2066 fname += '.py'
2063 if os.path.isfile(fname):
2067 if os.path.isfile(fname):
2064 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2068 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2065 if ans.lower() not in ['y','yes']:
2069 if ans.lower() not in ['y','yes']:
2066 print 'Operation cancelled.'
2070 print 'Operation cancelled.'
2067 return
2071 return
2068 try:
2072 try:
2069 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2073 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2070 except (TypeError, ValueError) as e:
2074 except (TypeError, ValueError) as e:
2071 print e.args[0]
2075 print e.args[0]
2072 return
2076 return
2073 if isinstance(cmds, unicode):
2077 if isinstance(cmds, unicode):
2074 cmds = cmds.encode("utf-8")
2078 cmds = cmds.encode("utf-8")
2075 with open(fname,'w') as f:
2079 with open(fname,'w') as f:
2076 f.write("# coding: utf-8\n")
2080 f.write("# coding: utf-8\n")
2077 f.write(cmds)
2081 f.write(cmds)
2078 print 'The following commands were written to file `%s`:' % fname
2082 print 'The following commands were written to file `%s`:' % fname
2079 print cmds
2083 print cmds
2080
2084
2081 def magic_pastebin(self, parameter_s = ''):
2085 def magic_pastebin(self, parameter_s = ''):
2082 """Upload code to the 'Lodge it' paste bin, returning the URL."""
2086 """Upload code to the 'Lodge it' paste bin, returning the URL."""
2083 try:
2087 try:
2084 code = self.shell.find_user_code(parameter_s)
2088 code = self.shell.find_user_code(parameter_s)
2085 except (ValueError, TypeError) as e:
2089 except (ValueError, TypeError) as e:
2086 print e.args[0]
2090 print e.args[0]
2087 return
2091 return
2088 pbserver = ServerProxy('http://paste.pocoo.org/xmlrpc/')
2092 pbserver = ServerProxy('http://paste.pocoo.org/xmlrpc/')
2089 id = pbserver.pastes.newPaste("python", code)
2093 id = pbserver.pastes.newPaste("python", code)
2090 return "http://paste.pocoo.org/show/" + id
2094 return "http://paste.pocoo.org/show/" + id
2091
2095
2092 def _edit_macro(self,mname,macro):
2096 def _edit_macro(self,mname,macro):
2093 """open an editor with the macro data in a file"""
2097 """open an editor with the macro data in a file"""
2094 filename = self.shell.mktempfile(macro.value)
2098 filename = self.shell.mktempfile(macro.value)
2095 self.shell.hooks.editor(filename)
2099 self.shell.hooks.editor(filename)
2096
2100
2097 # and make a new macro object, to replace the old one
2101 # and make a new macro object, to replace the old one
2098 mfile = open(filename)
2102 mfile = open(filename)
2099 mvalue = mfile.read()
2103 mvalue = mfile.read()
2100 mfile.close()
2104 mfile.close()
2101 self.shell.user_ns[mname] = Macro(mvalue)
2105 self.shell.user_ns[mname] = Macro(mvalue)
2102
2106
2103 def magic_ed(self,parameter_s=''):
2107 def magic_ed(self,parameter_s=''):
2104 """Alias to %edit."""
2108 """Alias to %edit."""
2105 return self.magic_edit(parameter_s)
2109 return self.magic_edit(parameter_s)
2106
2110
2107 @testdec.skip_doctest
2111 @testdec.skip_doctest
2108 def magic_edit(self,parameter_s='',last_call=['','']):
2112 def magic_edit(self,parameter_s='',last_call=['','']):
2109 """Bring up an editor and execute the resulting code.
2113 """Bring up an editor and execute the resulting code.
2110
2114
2111 Usage:
2115 Usage:
2112 %edit [options] [args]
2116 %edit [options] [args]
2113
2117
2114 %edit runs IPython's editor hook. The default version of this hook is
2118 %edit runs IPython's editor hook. The default version of this hook is
2115 set to call the __IPYTHON__.rc.editor command. This is read from your
2119 set to call the __IPYTHON__.rc.editor command. This is read from your
2116 environment variable $EDITOR. If this isn't found, it will default to
2120 environment variable $EDITOR. If this isn't found, it will default to
2117 vi under Linux/Unix and to notepad under Windows. See the end of this
2121 vi under Linux/Unix and to notepad under Windows. See the end of this
2118 docstring for how to change the editor hook.
2122 docstring for how to change the editor hook.
2119
2123
2120 You can also set the value of this editor via the command line option
2124 You can also set the value of this editor via the command line option
2121 '-editor' or in your ipythonrc file. This is useful if you wish to use
2125 '-editor' or in your ipythonrc file. This is useful if you wish to use
2122 specifically for IPython an editor different from your typical default
2126 specifically for IPython an editor different from your typical default
2123 (and for Windows users who typically don't set environment variables).
2127 (and for Windows users who typically don't set environment variables).
2124
2128
2125 This command allows you to conveniently edit multi-line code right in
2129 This command allows you to conveniently edit multi-line code right in
2126 your IPython session.
2130 your IPython session.
2127
2131
2128 If called without arguments, %edit opens up an empty editor with a
2132 If called without arguments, %edit opens up an empty editor with a
2129 temporary file and will execute the contents of this file when you
2133 temporary file and will execute the contents of this file when you
2130 close it (don't forget to save it!).
2134 close it (don't forget to save it!).
2131
2135
2132
2136
2133 Options:
2137 Options:
2134
2138
2135 -n <number>: open the editor at a specified line number. By default,
2139 -n <number>: open the editor at a specified line number. By default,
2136 the IPython editor hook uses the unix syntax 'editor +N filename', but
2140 the IPython editor hook uses the unix syntax 'editor +N filename', but
2137 you can configure this by providing your own modified hook if your
2141 you can configure this by providing your own modified hook if your
2138 favorite editor supports line-number specifications with a different
2142 favorite editor supports line-number specifications with a different
2139 syntax.
2143 syntax.
2140
2144
2141 -p: this will call the editor with the same data as the previous time
2145 -p: this will call the editor with the same data as the previous time
2142 it was used, regardless of how long ago (in your current session) it
2146 it was used, regardless of how long ago (in your current session) it
2143 was.
2147 was.
2144
2148
2145 -r: use 'raw' input. This option only applies to input taken from the
2149 -r: use 'raw' input. This option only applies to input taken from the
2146 user's history. By default, the 'processed' history is used, so that
2150 user's history. By default, the 'processed' history is used, so that
2147 magics are loaded in their transformed version to valid Python. If
2151 magics are loaded in their transformed version to valid Python. If
2148 this option is given, the raw input as typed as the command line is
2152 this option is given, the raw input as typed as the command line is
2149 used instead. When you exit the editor, it will be executed by
2153 used instead. When you exit the editor, it will be executed by
2150 IPython's own processor.
2154 IPython's own processor.
2151
2155
2152 -x: do not execute the edited code immediately upon exit. This is
2156 -x: do not execute the edited code immediately upon exit. This is
2153 mainly useful if you are editing programs which need to be called with
2157 mainly useful if you are editing programs which need to be called with
2154 command line arguments, which you can then do using %run.
2158 command line arguments, which you can then do using %run.
2155
2159
2156
2160
2157 Arguments:
2161 Arguments:
2158
2162
2159 If arguments are given, the following possibilites exist:
2163 If arguments are given, the following possibilites exist:
2160
2164
2161 - If the argument is a filename, IPython will load that into the
2165 - If the argument is a filename, IPython will load that into the
2162 editor. It will execute its contents with execfile() when you exit,
2166 editor. It will execute its contents with execfile() when you exit,
2163 loading any code in the file into your interactive namespace.
2167 loading any code in the file into your interactive namespace.
2164
2168
2165 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2169 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2166 The syntax is the same as in the %history magic.
2170 The syntax is the same as in the %history magic.
2167
2171
2168 - If the argument is a string variable, its contents are loaded
2172 - If the argument is a string variable, its contents are loaded
2169 into the editor. You can thus edit any string which contains
2173 into the editor. You can thus edit any string which contains
2170 python code (including the result of previous edits).
2174 python code (including the result of previous edits).
2171
2175
2172 - If the argument is the name of an object (other than a string),
2176 - If the argument is the name of an object (other than a string),
2173 IPython will try to locate the file where it was defined and open the
2177 IPython will try to locate the file where it was defined and open the
2174 editor at the point where it is defined. You can use `%edit function`
2178 editor at the point where it is defined. You can use `%edit function`
2175 to load an editor exactly at the point where 'function' is defined,
2179 to load an editor exactly at the point where 'function' is defined,
2176 edit it and have the file be executed automatically.
2180 edit it and have the file be executed automatically.
2177
2181
2178 If the object is a macro (see %macro for details), this opens up your
2182 If the object is a macro (see %macro for details), this opens up your
2179 specified editor with a temporary file containing the macro's data.
2183 specified editor with a temporary file containing the macro's data.
2180 Upon exit, the macro is reloaded with the contents of the file.
2184 Upon exit, the macro is reloaded with the contents of the file.
2181
2185
2182 Note: opening at an exact line is only supported under Unix, and some
2186 Note: opening at an exact line is only supported under Unix, and some
2183 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2187 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2184 '+NUMBER' parameter necessary for this feature. Good editors like
2188 '+NUMBER' parameter necessary for this feature. Good editors like
2185 (X)Emacs, vi, jed, pico and joe all do.
2189 (X)Emacs, vi, jed, pico and joe all do.
2186
2190
2187 After executing your code, %edit will return as output the code you
2191 After executing your code, %edit will return as output the code you
2188 typed in the editor (except when it was an existing file). This way
2192 typed in the editor (except when it was an existing file). This way
2189 you can reload the code in further invocations of %edit as a variable,
2193 you can reload the code in further invocations of %edit as a variable,
2190 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2194 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2191 the output.
2195 the output.
2192
2196
2193 Note that %edit is also available through the alias %ed.
2197 Note that %edit is also available through the alias %ed.
2194
2198
2195 This is an example of creating a simple function inside the editor and
2199 This is an example of creating a simple function inside the editor and
2196 then modifying it. First, start up the editor:
2200 then modifying it. First, start up the editor:
2197
2201
2198 In [1]: ed
2202 In [1]: ed
2199 Editing... done. Executing edited code...
2203 Editing... done. Executing edited code...
2200 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2204 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2201
2205
2202 We can then call the function foo():
2206 We can then call the function foo():
2203
2207
2204 In [2]: foo()
2208 In [2]: foo()
2205 foo() was defined in an editing session
2209 foo() was defined in an editing session
2206
2210
2207 Now we edit foo. IPython automatically loads the editor with the
2211 Now we edit foo. IPython automatically loads the editor with the
2208 (temporary) file where foo() was previously defined:
2212 (temporary) file where foo() was previously defined:
2209
2213
2210 In [3]: ed foo
2214 In [3]: ed foo
2211 Editing... done. Executing edited code...
2215 Editing... done. Executing edited code...
2212
2216
2213 And if we call foo() again we get the modified version:
2217 And if we call foo() again we get the modified version:
2214
2218
2215 In [4]: foo()
2219 In [4]: foo()
2216 foo() has now been changed!
2220 foo() has now been changed!
2217
2221
2218 Here is an example of how to edit a code snippet successive
2222 Here is an example of how to edit a code snippet successive
2219 times. First we call the editor:
2223 times. First we call the editor:
2220
2224
2221 In [5]: ed
2225 In [5]: ed
2222 Editing... done. Executing edited code...
2226 Editing... done. Executing edited code...
2223 hello
2227 hello
2224 Out[5]: "print 'hello'n"
2228 Out[5]: "print 'hello'n"
2225
2229
2226 Now we call it again with the previous output (stored in _):
2230 Now we call it again with the previous output (stored in _):
2227
2231
2228 In [6]: ed _
2232 In [6]: ed _
2229 Editing... done. Executing edited code...
2233 Editing... done. Executing edited code...
2230 hello world
2234 hello world
2231 Out[6]: "print 'hello world'n"
2235 Out[6]: "print 'hello world'n"
2232
2236
2233 Now we call it with the output #8 (stored in _8, also as Out[8]):
2237 Now we call it with the output #8 (stored in _8, also as Out[8]):
2234
2238
2235 In [7]: ed _8
2239 In [7]: ed _8
2236 Editing... done. Executing edited code...
2240 Editing... done. Executing edited code...
2237 hello again
2241 hello again
2238 Out[7]: "print 'hello again'n"
2242 Out[7]: "print 'hello again'n"
2239
2243
2240
2244
2241 Changing the default editor hook:
2245 Changing the default editor hook:
2242
2246
2243 If you wish to write your own editor hook, you can put it in a
2247 If you wish to write your own editor hook, you can put it in a
2244 configuration file which you load at startup time. The default hook
2248 configuration file which you load at startup time. The default hook
2245 is defined in the IPython.core.hooks module, and you can use that as a
2249 is defined in the IPython.core.hooks module, and you can use that as a
2246 starting example for further modifications. That file also has
2250 starting example for further modifications. That file also has
2247 general instructions on how to set a new hook for use once you've
2251 general instructions on how to set a new hook for use once you've
2248 defined it."""
2252 defined it."""
2249
2253
2250 # FIXME: This function has become a convoluted mess. It needs a
2254 # FIXME: This function has become a convoluted mess. It needs a
2251 # ground-up rewrite with clean, simple logic.
2255 # ground-up rewrite with clean, simple logic.
2252
2256
2253 def make_filename(arg):
2257 def make_filename(arg):
2254 "Make a filename from the given args"
2258 "Make a filename from the given args"
2255 try:
2259 try:
2256 filename = get_py_filename(arg)
2260 filename = get_py_filename(arg)
2257 except IOError:
2261 except IOError:
2258 if args.endswith('.py'):
2262 if args.endswith('.py'):
2259 filename = arg
2263 filename = arg
2260 else:
2264 else:
2261 filename = None
2265 filename = None
2262 return filename
2266 return filename
2263
2267
2264 # custom exceptions
2268 # custom exceptions
2265 class DataIsObject(Exception): pass
2269 class DataIsObject(Exception): pass
2266
2270
2267 opts,args = self.parse_options(parameter_s,'prxn:')
2271 opts,args = self.parse_options(parameter_s,'prxn:')
2268 # Set a few locals from the options for convenience:
2272 # Set a few locals from the options for convenience:
2269 opts_prev = 'p' in opts
2273 opts_prev = 'p' in opts
2270 opts_raw = 'r' in opts
2274 opts_raw = 'r' in opts
2271
2275
2272 # Default line number value
2276 # Default line number value
2273 lineno = opts.get('n',None)
2277 lineno = opts.get('n',None)
2274
2278
2275 if opts_prev:
2279 if opts_prev:
2276 args = '_%s' % last_call[0]
2280 args = '_%s' % last_call[0]
2277 if not self.shell.user_ns.has_key(args):
2281 if not self.shell.user_ns.has_key(args):
2278 args = last_call[1]
2282 args = last_call[1]
2279
2283
2280 # use last_call to remember the state of the previous call, but don't
2284 # use last_call to remember the state of the previous call, but don't
2281 # let it be clobbered by successive '-p' calls.
2285 # let it be clobbered by successive '-p' calls.
2282 try:
2286 try:
2283 last_call[0] = self.shell.displayhook.prompt_count
2287 last_call[0] = self.shell.displayhook.prompt_count
2284 if not opts_prev:
2288 if not opts_prev:
2285 last_call[1] = parameter_s
2289 last_call[1] = parameter_s
2286 except:
2290 except:
2287 pass
2291 pass
2288
2292
2289 # by default this is done with temp files, except when the given
2293 # by default this is done with temp files, except when the given
2290 # arg is a filename
2294 # arg is a filename
2291 use_temp = True
2295 use_temp = True
2292
2296
2293 data = ''
2297 data = ''
2294 if args.endswith('.py'):
2298 if args.endswith('.py'):
2295 filename = make_filename(args)
2299 filename = make_filename(args)
2296 use_temp = False
2300 use_temp = False
2297 elif args:
2301 elif args:
2298 # Mode where user specifies ranges of lines, like in %macro.
2302 # Mode where user specifies ranges of lines, like in %macro.
2299 data = self.extract_input_lines(args, opts_raw)
2303 data = self.extract_input_lines(args, opts_raw)
2300 if not data:
2304 if not data:
2301 try:
2305 try:
2302 # Load the parameter given as a variable. If not a string,
2306 # Load the parameter given as a variable. If not a string,
2303 # process it as an object instead (below)
2307 # process it as an object instead (below)
2304
2308
2305 #print '*** args',args,'type',type(args) # dbg
2309 #print '*** args',args,'type',type(args) # dbg
2306 data = eval(args, self.shell.user_ns)
2310 data = eval(args, self.shell.user_ns)
2307 if not isinstance(data, basestring):
2311 if not isinstance(data, basestring):
2308 raise DataIsObject
2312 raise DataIsObject
2309
2313
2310 except (NameError,SyntaxError):
2314 except (NameError,SyntaxError):
2311 # given argument is not a variable, try as a filename
2315 # given argument is not a variable, try as a filename
2312 filename = make_filename(args)
2316 filename = make_filename(args)
2313 if filename is None:
2317 if filename is None:
2314 warn("Argument given (%s) can't be found as a variable "
2318 warn("Argument given (%s) can't be found as a variable "
2315 "or as a filename." % args)
2319 "or as a filename." % args)
2316 return
2320 return
2317 use_temp = False
2321 use_temp = False
2318
2322
2319 except DataIsObject:
2323 except DataIsObject:
2320 # macros have a special edit function
2324 # macros have a special edit function
2321 if isinstance(data, Macro):
2325 if isinstance(data, Macro):
2322 self._edit_macro(args,data)
2326 self._edit_macro(args,data)
2323 return
2327 return
2324
2328
2325 # For objects, try to edit the file where they are defined
2329 # For objects, try to edit the file where they are defined
2326 try:
2330 try:
2327 filename = inspect.getabsfile(data)
2331 filename = inspect.getabsfile(data)
2328 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2332 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2329 # class created by %edit? Try to find source
2333 # class created by %edit? Try to find source
2330 # by looking for method definitions instead, the
2334 # by looking for method definitions instead, the
2331 # __module__ in those classes is FakeModule.
2335 # __module__ in those classes is FakeModule.
2332 attrs = [getattr(data, aname) for aname in dir(data)]
2336 attrs = [getattr(data, aname) for aname in dir(data)]
2333 for attr in attrs:
2337 for attr in attrs:
2334 if not inspect.ismethod(attr):
2338 if not inspect.ismethod(attr):
2335 continue
2339 continue
2336 filename = inspect.getabsfile(attr)
2340 filename = inspect.getabsfile(attr)
2337 if filename and 'fakemodule' not in filename.lower():
2341 if filename and 'fakemodule' not in filename.lower():
2338 # change the attribute to be the edit target instead
2342 # change the attribute to be the edit target instead
2339 data = attr
2343 data = attr
2340 break
2344 break
2341
2345
2342 datafile = 1
2346 datafile = 1
2343 except TypeError:
2347 except TypeError:
2344 filename = make_filename(args)
2348 filename = make_filename(args)
2345 datafile = 1
2349 datafile = 1
2346 warn('Could not find file where `%s` is defined.\n'
2350 warn('Could not find file where `%s` is defined.\n'
2347 'Opening a file named `%s`' % (args,filename))
2351 'Opening a file named `%s`' % (args,filename))
2348 # Now, make sure we can actually read the source (if it was in
2352 # Now, make sure we can actually read the source (if it was in
2349 # a temp file it's gone by now).
2353 # a temp file it's gone by now).
2350 if datafile:
2354 if datafile:
2351 try:
2355 try:
2352 if lineno is None:
2356 if lineno is None:
2353 lineno = inspect.getsourcelines(data)[1]
2357 lineno = inspect.getsourcelines(data)[1]
2354 except IOError:
2358 except IOError:
2355 filename = make_filename(args)
2359 filename = make_filename(args)
2356 if filename is None:
2360 if filename is None:
2357 warn('The file `%s` where `%s` was defined cannot '
2361 warn('The file `%s` where `%s` was defined cannot '
2358 'be read.' % (filename,data))
2362 'be read.' % (filename,data))
2359 return
2363 return
2360 use_temp = False
2364 use_temp = False
2361
2365
2362 if use_temp:
2366 if use_temp:
2363 filename = self.shell.mktempfile(data)
2367 filename = self.shell.mktempfile(data)
2364 print 'IPython will make a temporary file named:',filename
2368 print 'IPython will make a temporary file named:',filename
2365
2369
2366 # do actual editing here
2370 # do actual editing here
2367 print 'Editing...',
2371 print 'Editing...',
2368 sys.stdout.flush()
2372 sys.stdout.flush()
2369 try:
2373 try:
2370 # Quote filenames that may have spaces in them
2374 # Quote filenames that may have spaces in them
2371 if ' ' in filename:
2375 if ' ' in filename:
2372 filename = "%s" % filename
2376 filename = "%s" % filename
2373 self.shell.hooks.editor(filename,lineno)
2377 self.shell.hooks.editor(filename,lineno)
2374 except TryNext:
2378 except TryNext:
2375 warn('Could not open editor')
2379 warn('Could not open editor')
2376 return
2380 return
2377
2381
2378 # XXX TODO: should this be generalized for all string vars?
2382 # XXX TODO: should this be generalized for all string vars?
2379 # For now, this is special-cased to blocks created by cpaste
2383 # For now, this is special-cased to blocks created by cpaste
2380 if args.strip() == 'pasted_block':
2384 if args.strip() == 'pasted_block':
2381 self.shell.user_ns['pasted_block'] = file_read(filename)
2385 self.shell.user_ns['pasted_block'] = file_read(filename)
2382
2386
2383 if 'x' in opts: # -x prevents actual execution
2387 if 'x' in opts: # -x prevents actual execution
2384 print
2388 print
2385 else:
2389 else:
2386 print 'done. Executing edited code...'
2390 print 'done. Executing edited code...'
2387 if opts_raw:
2391 if opts_raw:
2388 self.shell.run_cell(file_read(filename),
2392 self.shell.run_cell(file_read(filename),
2389 store_history=False)
2393 store_history=False)
2390 else:
2394 else:
2391 self.shell.safe_execfile(filename,self.shell.user_ns,
2395 self.shell.safe_execfile(filename,self.shell.user_ns,
2392 self.shell.user_ns)
2396 self.shell.user_ns)
2393
2397
2394
2398
2395 if use_temp:
2399 if use_temp:
2396 try:
2400 try:
2397 return open(filename).read()
2401 return open(filename).read()
2398 except IOError,msg:
2402 except IOError,msg:
2399 if msg.filename == filename:
2403 if msg.filename == filename:
2400 warn('File not found. Did you forget to save?')
2404 warn('File not found. Did you forget to save?')
2401 return
2405 return
2402 else:
2406 else:
2403 self.shell.showtraceback()
2407 self.shell.showtraceback()
2404
2408
2405 def magic_xmode(self,parameter_s = ''):
2409 def magic_xmode(self,parameter_s = ''):
2406 """Switch modes for the exception handlers.
2410 """Switch modes for the exception handlers.
2407
2411
2408 Valid modes: Plain, Context and Verbose.
2412 Valid modes: Plain, Context and Verbose.
2409
2413
2410 If called without arguments, acts as a toggle."""
2414 If called without arguments, acts as a toggle."""
2411
2415
2412 def xmode_switch_err(name):
2416 def xmode_switch_err(name):
2413 warn('Error changing %s exception modes.\n%s' %
2417 warn('Error changing %s exception modes.\n%s' %
2414 (name,sys.exc_info()[1]))
2418 (name,sys.exc_info()[1]))
2415
2419
2416 shell = self.shell
2420 shell = self.shell
2417 new_mode = parameter_s.strip().capitalize()
2421 new_mode = parameter_s.strip().capitalize()
2418 try:
2422 try:
2419 shell.InteractiveTB.set_mode(mode=new_mode)
2423 shell.InteractiveTB.set_mode(mode=new_mode)
2420 print 'Exception reporting mode:',shell.InteractiveTB.mode
2424 print 'Exception reporting mode:',shell.InteractiveTB.mode
2421 except:
2425 except:
2422 xmode_switch_err('user')
2426 xmode_switch_err('user')
2423
2427
2424 def magic_colors(self,parameter_s = ''):
2428 def magic_colors(self,parameter_s = ''):
2425 """Switch color scheme for prompts, info system and exception handlers.
2429 """Switch color scheme for prompts, info system and exception handlers.
2426
2430
2427 Currently implemented schemes: NoColor, Linux, LightBG.
2431 Currently implemented schemes: NoColor, Linux, LightBG.
2428
2432
2429 Color scheme names are not case-sensitive.
2433 Color scheme names are not case-sensitive.
2430
2434
2431 Examples
2435 Examples
2432 --------
2436 --------
2433 To get a plain black and white terminal::
2437 To get a plain black and white terminal::
2434
2438
2435 %colors nocolor
2439 %colors nocolor
2436 """
2440 """
2437
2441
2438 def color_switch_err(name):
2442 def color_switch_err(name):
2439 warn('Error changing %s color schemes.\n%s' %
2443 warn('Error changing %s color schemes.\n%s' %
2440 (name,sys.exc_info()[1]))
2444 (name,sys.exc_info()[1]))
2441
2445
2442
2446
2443 new_scheme = parameter_s.strip()
2447 new_scheme = parameter_s.strip()
2444 if not new_scheme:
2448 if not new_scheme:
2445 raise UsageError(
2449 raise UsageError(
2446 "%colors: you must specify a color scheme. See '%colors?'")
2450 "%colors: you must specify a color scheme. See '%colors?'")
2447 return
2451 return
2448 # local shortcut
2452 # local shortcut
2449 shell = self.shell
2453 shell = self.shell
2450
2454
2451 import IPython.utils.rlineimpl as readline
2455 import IPython.utils.rlineimpl as readline
2452
2456
2453 if not readline.have_readline and sys.platform == "win32":
2457 if not readline.have_readline and sys.platform == "win32":
2454 msg = """\
2458 msg = """\
2455 Proper color support under MS Windows requires the pyreadline library.
2459 Proper color support under MS Windows requires the pyreadline library.
2456 You can find it at:
2460 You can find it at:
2457 http://ipython.scipy.org/moin/PyReadline/Intro
2461 http://ipython.scipy.org/moin/PyReadline/Intro
2458 Gary's readline needs the ctypes module, from:
2462 Gary's readline needs the ctypes module, from:
2459 http://starship.python.net/crew/theller/ctypes
2463 http://starship.python.net/crew/theller/ctypes
2460 (Note that ctypes is already part of Python versions 2.5 and newer).
2464 (Note that ctypes is already part of Python versions 2.5 and newer).
2461
2465
2462 Defaulting color scheme to 'NoColor'"""
2466 Defaulting color scheme to 'NoColor'"""
2463 new_scheme = 'NoColor'
2467 new_scheme = 'NoColor'
2464 warn(msg)
2468 warn(msg)
2465
2469
2466 # readline option is 0
2470 # readline option is 0
2467 if not shell.has_readline:
2471 if not shell.has_readline:
2468 new_scheme = 'NoColor'
2472 new_scheme = 'NoColor'
2469
2473
2470 # Set prompt colors
2474 # Set prompt colors
2471 try:
2475 try:
2472 shell.displayhook.set_colors(new_scheme)
2476 shell.displayhook.set_colors(new_scheme)
2473 except:
2477 except:
2474 color_switch_err('prompt')
2478 color_switch_err('prompt')
2475 else:
2479 else:
2476 shell.colors = \
2480 shell.colors = \
2477 shell.displayhook.color_table.active_scheme_name
2481 shell.displayhook.color_table.active_scheme_name
2478 # Set exception colors
2482 # Set exception colors
2479 try:
2483 try:
2480 shell.InteractiveTB.set_colors(scheme = new_scheme)
2484 shell.InteractiveTB.set_colors(scheme = new_scheme)
2481 shell.SyntaxTB.set_colors(scheme = new_scheme)
2485 shell.SyntaxTB.set_colors(scheme = new_scheme)
2482 except:
2486 except:
2483 color_switch_err('exception')
2487 color_switch_err('exception')
2484
2488
2485 # Set info (for 'object?') colors
2489 # Set info (for 'object?') colors
2486 if shell.color_info:
2490 if shell.color_info:
2487 try:
2491 try:
2488 shell.inspector.set_active_scheme(new_scheme)
2492 shell.inspector.set_active_scheme(new_scheme)
2489 except:
2493 except:
2490 color_switch_err('object inspector')
2494 color_switch_err('object inspector')
2491 else:
2495 else:
2492 shell.inspector.set_active_scheme('NoColor')
2496 shell.inspector.set_active_scheme('NoColor')
2493
2497
2494 def magic_pprint(self, parameter_s=''):
2498 def magic_pprint(self, parameter_s=''):
2495 """Toggle pretty printing on/off."""
2499 """Toggle pretty printing on/off."""
2496 ptformatter = self.shell.display_formatter.formatters['text/plain']
2500 ptformatter = self.shell.display_formatter.formatters['text/plain']
2497 ptformatter.pprint = bool(1 - ptformatter.pprint)
2501 ptformatter.pprint = bool(1 - ptformatter.pprint)
2498 print 'Pretty printing has been turned', \
2502 print 'Pretty printing has been turned', \
2499 ['OFF','ON'][ptformatter.pprint]
2503 ['OFF','ON'][ptformatter.pprint]
2500
2504
2501 def magic_Exit(self, parameter_s=''):
2505 def magic_Exit(self, parameter_s=''):
2502 """Exit IPython."""
2506 """Exit IPython."""
2503
2507
2504 self.shell.ask_exit()
2508 self.shell.ask_exit()
2505
2509
2506 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2510 # Add aliases as magics so all common forms work: exit, quit, Exit, Quit.
2507 magic_exit = magic_quit = magic_Quit = magic_Exit
2511 magic_exit = magic_quit = magic_Quit = magic_Exit
2508
2512
2509 #......................................................................
2513 #......................................................................
2510 # Functions to implement unix shell-type things
2514 # Functions to implement unix shell-type things
2511
2515
2512 @testdec.skip_doctest
2516 @testdec.skip_doctest
2513 def magic_alias(self, parameter_s = ''):
2517 def magic_alias(self, parameter_s = ''):
2514 """Define an alias for a system command.
2518 """Define an alias for a system command.
2515
2519
2516 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2520 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2517
2521
2518 Then, typing 'alias_name params' will execute the system command 'cmd
2522 Then, typing 'alias_name params' will execute the system command 'cmd
2519 params' (from your underlying operating system).
2523 params' (from your underlying operating system).
2520
2524
2521 Aliases have lower precedence than magic functions and Python normal
2525 Aliases have lower precedence than magic functions and Python normal
2522 variables, so if 'foo' is both a Python variable and an alias, the
2526 variables, so if 'foo' is both a Python variable and an alias, the
2523 alias can not be executed until 'del foo' removes the Python variable.
2527 alias can not be executed until 'del foo' removes the Python variable.
2524
2528
2525 You can use the %l specifier in an alias definition to represent the
2529 You can use the %l specifier in an alias definition to represent the
2526 whole line when the alias is called. For example:
2530 whole line when the alias is called. For example:
2527
2531
2528 In [2]: alias bracket echo "Input in brackets: <%l>"
2532 In [2]: alias bracket echo "Input in brackets: <%l>"
2529 In [3]: bracket hello world
2533 In [3]: bracket hello world
2530 Input in brackets: <hello world>
2534 Input in brackets: <hello world>
2531
2535
2532 You can also define aliases with parameters using %s specifiers (one
2536 You can also define aliases with parameters using %s specifiers (one
2533 per parameter):
2537 per parameter):
2534
2538
2535 In [1]: alias parts echo first %s second %s
2539 In [1]: alias parts echo first %s second %s
2536 In [2]: %parts A B
2540 In [2]: %parts A B
2537 first A second B
2541 first A second B
2538 In [3]: %parts A
2542 In [3]: %parts A
2539 Incorrect number of arguments: 2 expected.
2543 Incorrect number of arguments: 2 expected.
2540 parts is an alias to: 'echo first %s second %s'
2544 parts is an alias to: 'echo first %s second %s'
2541
2545
2542 Note that %l and %s are mutually exclusive. You can only use one or
2546 Note that %l and %s are mutually exclusive. You can only use one or
2543 the other in your aliases.
2547 the other in your aliases.
2544
2548
2545 Aliases expand Python variables just like system calls using ! or !!
2549 Aliases expand Python variables just like system calls using ! or !!
2546 do: all expressions prefixed with '$' get expanded. For details of
2550 do: all expressions prefixed with '$' get expanded. For details of
2547 the semantic rules, see PEP-215:
2551 the semantic rules, see PEP-215:
2548 http://www.python.org/peps/pep-0215.html. This is the library used by
2552 http://www.python.org/peps/pep-0215.html. This is the library used by
2549 IPython for variable expansion. If you want to access a true shell
2553 IPython for variable expansion. If you want to access a true shell
2550 variable, an extra $ is necessary to prevent its expansion by IPython:
2554 variable, an extra $ is necessary to prevent its expansion by IPython:
2551
2555
2552 In [6]: alias show echo
2556 In [6]: alias show echo
2553 In [7]: PATH='A Python string'
2557 In [7]: PATH='A Python string'
2554 In [8]: show $PATH
2558 In [8]: show $PATH
2555 A Python string
2559 A Python string
2556 In [9]: show $$PATH
2560 In [9]: show $$PATH
2557 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2561 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2558
2562
2559 You can use the alias facility to acess all of $PATH. See the %rehash
2563 You can use the alias facility to acess all of $PATH. See the %rehash
2560 and %rehashx functions, which automatically create aliases for the
2564 and %rehashx functions, which automatically create aliases for the
2561 contents of your $PATH.
2565 contents of your $PATH.
2562
2566
2563 If called with no parameters, %alias prints the current alias table."""
2567 If called with no parameters, %alias prints the current alias table."""
2564
2568
2565 par = parameter_s.strip()
2569 par = parameter_s.strip()
2566 if not par:
2570 if not par:
2567 stored = self.db.get('stored_aliases', {} )
2571 stored = self.db.get('stored_aliases', {} )
2568 aliases = sorted(self.shell.alias_manager.aliases)
2572 aliases = sorted(self.shell.alias_manager.aliases)
2569 # for k, v in stored:
2573 # for k, v in stored:
2570 # atab.append(k, v[0])
2574 # atab.append(k, v[0])
2571
2575
2572 print "Total number of aliases:", len(aliases)
2576 print "Total number of aliases:", len(aliases)
2573 sys.stdout.flush()
2577 sys.stdout.flush()
2574 return aliases
2578 return aliases
2575
2579
2576 # Now try to define a new one
2580 # Now try to define a new one
2577 try:
2581 try:
2578 alias,cmd = par.split(None, 1)
2582 alias,cmd = par.split(None, 1)
2579 except:
2583 except:
2580 print oinspect.getdoc(self.magic_alias)
2584 print oinspect.getdoc(self.magic_alias)
2581 else:
2585 else:
2582 self.shell.alias_manager.soft_define_alias(alias, cmd)
2586 self.shell.alias_manager.soft_define_alias(alias, cmd)
2583 # end magic_alias
2587 # end magic_alias
2584
2588
2585 def magic_unalias(self, parameter_s = ''):
2589 def magic_unalias(self, parameter_s = ''):
2586 """Remove an alias"""
2590 """Remove an alias"""
2587
2591
2588 aname = parameter_s.strip()
2592 aname = parameter_s.strip()
2589 self.shell.alias_manager.undefine_alias(aname)
2593 self.shell.alias_manager.undefine_alias(aname)
2590 stored = self.db.get('stored_aliases', {} )
2594 stored = self.db.get('stored_aliases', {} )
2591 if aname in stored:
2595 if aname in stored:
2592 print "Removing %stored alias",aname
2596 print "Removing %stored alias",aname
2593 del stored[aname]
2597 del stored[aname]
2594 self.db['stored_aliases'] = stored
2598 self.db['stored_aliases'] = stored
2595
2599
2596 def magic_rehashx(self, parameter_s = ''):
2600 def magic_rehashx(self, parameter_s = ''):
2597 """Update the alias table with all executable files in $PATH.
2601 """Update the alias table with all executable files in $PATH.
2598
2602
2599 This version explicitly checks that every entry in $PATH is a file
2603 This version explicitly checks that every entry in $PATH is a file
2600 with execute access (os.X_OK), so it is much slower than %rehash.
2604 with execute access (os.X_OK), so it is much slower than %rehash.
2601
2605
2602 Under Windows, it checks executability as a match agains a
2606 Under Windows, it checks executability as a match agains a
2603 '|'-separated string of extensions, stored in the IPython config
2607 '|'-separated string of extensions, stored in the IPython config
2604 variable win_exec_ext. This defaults to 'exe|com|bat'.
2608 variable win_exec_ext. This defaults to 'exe|com|bat'.
2605
2609
2606 This function also resets the root module cache of module completer,
2610 This function also resets the root module cache of module completer,
2607 used on slow filesystems.
2611 used on slow filesystems.
2608 """
2612 """
2609 from IPython.core.alias import InvalidAliasError
2613 from IPython.core.alias import InvalidAliasError
2610
2614
2611 # for the benefit of module completer in ipy_completers.py
2615 # for the benefit of module completer in ipy_completers.py
2612 del self.db['rootmodules']
2616 del self.db['rootmodules']
2613
2617
2614 path = [os.path.abspath(os.path.expanduser(p)) for p in
2618 path = [os.path.abspath(os.path.expanduser(p)) for p in
2615 os.environ.get('PATH','').split(os.pathsep)]
2619 os.environ.get('PATH','').split(os.pathsep)]
2616 path = filter(os.path.isdir,path)
2620 path = filter(os.path.isdir,path)
2617
2621
2618 syscmdlist = []
2622 syscmdlist = []
2619 # Now define isexec in a cross platform manner.
2623 # Now define isexec in a cross platform manner.
2620 if os.name == 'posix':
2624 if os.name == 'posix':
2621 isexec = lambda fname:os.path.isfile(fname) and \
2625 isexec = lambda fname:os.path.isfile(fname) and \
2622 os.access(fname,os.X_OK)
2626 os.access(fname,os.X_OK)
2623 else:
2627 else:
2624 try:
2628 try:
2625 winext = os.environ['pathext'].replace(';','|').replace('.','')
2629 winext = os.environ['pathext'].replace(';','|').replace('.','')
2626 except KeyError:
2630 except KeyError:
2627 winext = 'exe|com|bat|py'
2631 winext = 'exe|com|bat|py'
2628 if 'py' not in winext:
2632 if 'py' not in winext:
2629 winext += '|py'
2633 winext += '|py'
2630 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2634 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2631 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2635 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2632 savedir = os.getcwd()
2636 savedir = os.getcwd()
2633
2637
2634 # Now walk the paths looking for executables to alias.
2638 # Now walk the paths looking for executables to alias.
2635 try:
2639 try:
2636 # write the whole loop for posix/Windows so we don't have an if in
2640 # write the whole loop for posix/Windows so we don't have an if in
2637 # the innermost part
2641 # the innermost part
2638 if os.name == 'posix':
2642 if os.name == 'posix':
2639 for pdir in path:
2643 for pdir in path:
2640 os.chdir(pdir)
2644 os.chdir(pdir)
2641 for ff in os.listdir(pdir):
2645 for ff in os.listdir(pdir):
2642 if isexec(ff):
2646 if isexec(ff):
2643 try:
2647 try:
2644 # Removes dots from the name since ipython
2648 # Removes dots from the name since ipython
2645 # will assume names with dots to be python.
2649 # will assume names with dots to be python.
2646 self.shell.alias_manager.define_alias(
2650 self.shell.alias_manager.define_alias(
2647 ff.replace('.',''), ff)
2651 ff.replace('.',''), ff)
2648 except InvalidAliasError:
2652 except InvalidAliasError:
2649 pass
2653 pass
2650 else:
2654 else:
2651 syscmdlist.append(ff)
2655 syscmdlist.append(ff)
2652 else:
2656 else:
2653 no_alias = self.shell.alias_manager.no_alias
2657 no_alias = self.shell.alias_manager.no_alias
2654 for pdir in path:
2658 for pdir in path:
2655 os.chdir(pdir)
2659 os.chdir(pdir)
2656 for ff in os.listdir(pdir):
2660 for ff in os.listdir(pdir):
2657 base, ext = os.path.splitext(ff)
2661 base, ext = os.path.splitext(ff)
2658 if isexec(ff) and base.lower() not in no_alias:
2662 if isexec(ff) and base.lower() not in no_alias:
2659 if ext.lower() == '.exe':
2663 if ext.lower() == '.exe':
2660 ff = base
2664 ff = base
2661 try:
2665 try:
2662 # Removes dots from the name since ipython
2666 # Removes dots from the name since ipython
2663 # will assume names with dots to be python.
2667 # will assume names with dots to be python.
2664 self.shell.alias_manager.define_alias(
2668 self.shell.alias_manager.define_alias(
2665 base.lower().replace('.',''), ff)
2669 base.lower().replace('.',''), ff)
2666 except InvalidAliasError:
2670 except InvalidAliasError:
2667 pass
2671 pass
2668 syscmdlist.append(ff)
2672 syscmdlist.append(ff)
2669 db = self.db
2673 db = self.db
2670 db['syscmdlist'] = syscmdlist
2674 db['syscmdlist'] = syscmdlist
2671 finally:
2675 finally:
2672 os.chdir(savedir)
2676 os.chdir(savedir)
2673
2677
2674 @testdec.skip_doctest
2678 @testdec.skip_doctest
2675 def magic_pwd(self, parameter_s = ''):
2679 def magic_pwd(self, parameter_s = ''):
2676 """Return the current working directory path.
2680 """Return the current working directory path.
2677
2681
2678 Examples
2682 Examples
2679 --------
2683 --------
2680 ::
2684 ::
2681
2685
2682 In [9]: pwd
2686 In [9]: pwd
2683 Out[9]: '/home/tsuser/sprint/ipython'
2687 Out[9]: '/home/tsuser/sprint/ipython'
2684 """
2688 """
2685 return os.getcwd()
2689 return os.getcwd()
2686
2690
2687 @testdec.skip_doctest
2691 @testdec.skip_doctest
2688 def magic_cd(self, parameter_s=''):
2692 def magic_cd(self, parameter_s=''):
2689 """Change the current working directory.
2693 """Change the current working directory.
2690
2694
2691 This command automatically maintains an internal list of directories
2695 This command automatically maintains an internal list of directories
2692 you visit during your IPython session, in the variable _dh. The
2696 you visit during your IPython session, in the variable _dh. The
2693 command %dhist shows this history nicely formatted. You can also
2697 command %dhist shows this history nicely formatted. You can also
2694 do 'cd -<tab>' to see directory history conveniently.
2698 do 'cd -<tab>' to see directory history conveniently.
2695
2699
2696 Usage:
2700 Usage:
2697
2701
2698 cd 'dir': changes to directory 'dir'.
2702 cd 'dir': changes to directory 'dir'.
2699
2703
2700 cd -: changes to the last visited directory.
2704 cd -: changes to the last visited directory.
2701
2705
2702 cd -<n>: changes to the n-th directory in the directory history.
2706 cd -<n>: changes to the n-th directory in the directory history.
2703
2707
2704 cd --foo: change to directory that matches 'foo' in history
2708 cd --foo: change to directory that matches 'foo' in history
2705
2709
2706 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2710 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2707 (note: cd <bookmark_name> is enough if there is no
2711 (note: cd <bookmark_name> is enough if there is no
2708 directory <bookmark_name>, but a bookmark with the name exists.)
2712 directory <bookmark_name>, but a bookmark with the name exists.)
2709 'cd -b <tab>' allows you to tab-complete bookmark names.
2713 'cd -b <tab>' allows you to tab-complete bookmark names.
2710
2714
2711 Options:
2715 Options:
2712
2716
2713 -q: quiet. Do not print the working directory after the cd command is
2717 -q: quiet. Do not print the working directory after the cd command is
2714 executed. By default IPython's cd command does print this directory,
2718 executed. By default IPython's cd command does print this directory,
2715 since the default prompts do not display path information.
2719 since the default prompts do not display path information.
2716
2720
2717 Note that !cd doesn't work for this purpose because the shell where
2721 Note that !cd doesn't work for this purpose because the shell where
2718 !command runs is immediately discarded after executing 'command'.
2722 !command runs is immediately discarded after executing 'command'.
2719
2723
2720 Examples
2724 Examples
2721 --------
2725 --------
2722 ::
2726 ::
2723
2727
2724 In [10]: cd parent/child
2728 In [10]: cd parent/child
2725 /home/tsuser/parent/child
2729 /home/tsuser/parent/child
2726 """
2730 """
2727
2731
2728 parameter_s = parameter_s.strip()
2732 parameter_s = parameter_s.strip()
2729 #bkms = self.shell.persist.get("bookmarks",{})
2733 #bkms = self.shell.persist.get("bookmarks",{})
2730
2734
2731 oldcwd = os.getcwd()
2735 oldcwd = os.getcwd()
2732 numcd = re.match(r'(-)(\d+)$',parameter_s)
2736 numcd = re.match(r'(-)(\d+)$',parameter_s)
2733 # jump in directory history by number
2737 # jump in directory history by number
2734 if numcd:
2738 if numcd:
2735 nn = int(numcd.group(2))
2739 nn = int(numcd.group(2))
2736 try:
2740 try:
2737 ps = self.shell.user_ns['_dh'][nn]
2741 ps = self.shell.user_ns['_dh'][nn]
2738 except IndexError:
2742 except IndexError:
2739 print 'The requested directory does not exist in history.'
2743 print 'The requested directory does not exist in history.'
2740 return
2744 return
2741 else:
2745 else:
2742 opts = {}
2746 opts = {}
2743 elif parameter_s.startswith('--'):
2747 elif parameter_s.startswith('--'):
2744 ps = None
2748 ps = None
2745 fallback = None
2749 fallback = None
2746 pat = parameter_s[2:]
2750 pat = parameter_s[2:]
2747 dh = self.shell.user_ns['_dh']
2751 dh = self.shell.user_ns['_dh']
2748 # first search only by basename (last component)
2752 # first search only by basename (last component)
2749 for ent in reversed(dh):
2753 for ent in reversed(dh):
2750 if pat in os.path.basename(ent) and os.path.isdir(ent):
2754 if pat in os.path.basename(ent) and os.path.isdir(ent):
2751 ps = ent
2755 ps = ent
2752 break
2756 break
2753
2757
2754 if fallback is None and pat in ent and os.path.isdir(ent):
2758 if fallback is None and pat in ent and os.path.isdir(ent):
2755 fallback = ent
2759 fallback = ent
2756
2760
2757 # if we have no last part match, pick the first full path match
2761 # if we have no last part match, pick the first full path match
2758 if ps is None:
2762 if ps is None:
2759 ps = fallback
2763 ps = fallback
2760
2764
2761 if ps is None:
2765 if ps is None:
2762 print "No matching entry in directory history"
2766 print "No matching entry in directory history"
2763 return
2767 return
2764 else:
2768 else:
2765 opts = {}
2769 opts = {}
2766
2770
2767
2771
2768 else:
2772 else:
2769 #turn all non-space-escaping backslashes to slashes,
2773 #turn all non-space-escaping backslashes to slashes,
2770 # for c:\windows\directory\names\
2774 # for c:\windows\directory\names\
2771 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2775 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2772 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2776 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2773 # jump to previous
2777 # jump to previous
2774 if ps == '-':
2778 if ps == '-':
2775 try:
2779 try:
2776 ps = self.shell.user_ns['_dh'][-2]
2780 ps = self.shell.user_ns['_dh'][-2]
2777 except IndexError:
2781 except IndexError:
2778 raise UsageError('%cd -: No previous directory to change to.')
2782 raise UsageError('%cd -: No previous directory to change to.')
2779 # jump to bookmark if needed
2783 # jump to bookmark if needed
2780 else:
2784 else:
2781 if not os.path.isdir(ps) or opts.has_key('b'):
2785 if not os.path.isdir(ps) or opts.has_key('b'):
2782 bkms = self.db.get('bookmarks', {})
2786 bkms = self.db.get('bookmarks', {})
2783
2787
2784 if bkms.has_key(ps):
2788 if bkms.has_key(ps):
2785 target = bkms[ps]
2789 target = bkms[ps]
2786 print '(bookmark:%s) -> %s' % (ps,target)
2790 print '(bookmark:%s) -> %s' % (ps,target)
2787 ps = target
2791 ps = target
2788 else:
2792 else:
2789 if opts.has_key('b'):
2793 if opts.has_key('b'):
2790 raise UsageError("Bookmark '%s' not found. "
2794 raise UsageError("Bookmark '%s' not found. "
2791 "Use '%%bookmark -l' to see your bookmarks." % ps)
2795 "Use '%%bookmark -l' to see your bookmarks." % ps)
2792
2796
2793 # at this point ps should point to the target dir
2797 # at this point ps should point to the target dir
2794 if ps:
2798 if ps:
2795 try:
2799 try:
2796 os.chdir(os.path.expanduser(ps))
2800 os.chdir(os.path.expanduser(ps))
2797 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2801 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2798 set_term_title('IPython: ' + abbrev_cwd())
2802 set_term_title('IPython: ' + abbrev_cwd())
2799 except OSError:
2803 except OSError:
2800 print sys.exc_info()[1]
2804 print sys.exc_info()[1]
2801 else:
2805 else:
2802 cwd = os.getcwd()
2806 cwd = os.getcwd()
2803 dhist = self.shell.user_ns['_dh']
2807 dhist = self.shell.user_ns['_dh']
2804 if oldcwd != cwd:
2808 if oldcwd != cwd:
2805 dhist.append(cwd)
2809 dhist.append(cwd)
2806 self.db['dhist'] = compress_dhist(dhist)[-100:]
2810 self.db['dhist'] = compress_dhist(dhist)[-100:]
2807
2811
2808 else:
2812 else:
2809 os.chdir(self.shell.home_dir)
2813 os.chdir(self.shell.home_dir)
2810 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2814 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2811 set_term_title('IPython: ' + '~')
2815 set_term_title('IPython: ' + '~')
2812 cwd = os.getcwd()
2816 cwd = os.getcwd()
2813 dhist = self.shell.user_ns['_dh']
2817 dhist = self.shell.user_ns['_dh']
2814
2818
2815 if oldcwd != cwd:
2819 if oldcwd != cwd:
2816 dhist.append(cwd)
2820 dhist.append(cwd)
2817 self.db['dhist'] = compress_dhist(dhist)[-100:]
2821 self.db['dhist'] = compress_dhist(dhist)[-100:]
2818 if not 'q' in opts and self.shell.user_ns['_dh']:
2822 if not 'q' in opts and self.shell.user_ns['_dh']:
2819 print self.shell.user_ns['_dh'][-1]
2823 print self.shell.user_ns['_dh'][-1]
2820
2824
2821
2825
2822 def magic_env(self, parameter_s=''):
2826 def magic_env(self, parameter_s=''):
2823 """List environment variables."""
2827 """List environment variables."""
2824
2828
2825 return os.environ.data
2829 return os.environ.data
2826
2830
2827 def magic_pushd(self, parameter_s=''):
2831 def magic_pushd(self, parameter_s=''):
2828 """Place the current dir on stack and change directory.
2832 """Place the current dir on stack and change directory.
2829
2833
2830 Usage:\\
2834 Usage:\\
2831 %pushd ['dirname']
2835 %pushd ['dirname']
2832 """
2836 """
2833
2837
2834 dir_s = self.shell.dir_stack
2838 dir_s = self.shell.dir_stack
2835 tgt = os.path.expanduser(parameter_s)
2839 tgt = os.path.expanduser(parameter_s)
2836 cwd = os.getcwd().replace(self.home_dir,'~')
2840 cwd = os.getcwd().replace(self.home_dir,'~')
2837 if tgt:
2841 if tgt:
2838 self.magic_cd(parameter_s)
2842 self.magic_cd(parameter_s)
2839 dir_s.insert(0,cwd)
2843 dir_s.insert(0,cwd)
2840 return self.magic_dirs()
2844 return self.magic_dirs()
2841
2845
2842 def magic_popd(self, parameter_s=''):
2846 def magic_popd(self, parameter_s=''):
2843 """Change to directory popped off the top of the stack.
2847 """Change to directory popped off the top of the stack.
2844 """
2848 """
2845 if not self.shell.dir_stack:
2849 if not self.shell.dir_stack:
2846 raise UsageError("%popd on empty stack")
2850 raise UsageError("%popd on empty stack")
2847 top = self.shell.dir_stack.pop(0)
2851 top = self.shell.dir_stack.pop(0)
2848 self.magic_cd(top)
2852 self.magic_cd(top)
2849 print "popd ->",top
2853 print "popd ->",top
2850
2854
2851 def magic_dirs(self, parameter_s=''):
2855 def magic_dirs(self, parameter_s=''):
2852 """Return the current directory stack."""
2856 """Return the current directory stack."""
2853
2857
2854 return self.shell.dir_stack
2858 return self.shell.dir_stack
2855
2859
2856 def magic_dhist(self, parameter_s=''):
2860 def magic_dhist(self, parameter_s=''):
2857 """Print your history of visited directories.
2861 """Print your history of visited directories.
2858
2862
2859 %dhist -> print full history\\
2863 %dhist -> print full history\\
2860 %dhist n -> print last n entries only\\
2864 %dhist n -> print last n entries only\\
2861 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2865 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2862
2866
2863 This history is automatically maintained by the %cd command, and
2867 This history is automatically maintained by the %cd command, and
2864 always available as the global list variable _dh. You can use %cd -<n>
2868 always available as the global list variable _dh. You can use %cd -<n>
2865 to go to directory number <n>.
2869 to go to directory number <n>.
2866
2870
2867 Note that most of time, you should view directory history by entering
2871 Note that most of time, you should view directory history by entering
2868 cd -<TAB>.
2872 cd -<TAB>.
2869
2873
2870 """
2874 """
2871
2875
2872 dh = self.shell.user_ns['_dh']
2876 dh = self.shell.user_ns['_dh']
2873 if parameter_s:
2877 if parameter_s:
2874 try:
2878 try:
2875 args = map(int,parameter_s.split())
2879 args = map(int,parameter_s.split())
2876 except:
2880 except:
2877 self.arg_err(Magic.magic_dhist)
2881 self.arg_err(Magic.magic_dhist)
2878 return
2882 return
2879 if len(args) == 1:
2883 if len(args) == 1:
2880 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2884 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2881 elif len(args) == 2:
2885 elif len(args) == 2:
2882 ini,fin = args
2886 ini,fin = args
2883 else:
2887 else:
2884 self.arg_err(Magic.magic_dhist)
2888 self.arg_err(Magic.magic_dhist)
2885 return
2889 return
2886 else:
2890 else:
2887 ini,fin = 0,len(dh)
2891 ini,fin = 0,len(dh)
2888 nlprint(dh,
2892 nlprint(dh,
2889 header = 'Directory history (kept in _dh)',
2893 header = 'Directory history (kept in _dh)',
2890 start=ini,stop=fin)
2894 start=ini,stop=fin)
2891
2895
2892 @testdec.skip_doctest
2896 @testdec.skip_doctest
2893 def magic_sc(self, parameter_s=''):
2897 def magic_sc(self, parameter_s=''):
2894 """Shell capture - execute a shell command and capture its output.
2898 """Shell capture - execute a shell command and capture its output.
2895
2899
2896 DEPRECATED. Suboptimal, retained for backwards compatibility.
2900 DEPRECATED. Suboptimal, retained for backwards compatibility.
2897
2901
2898 You should use the form 'var = !command' instead. Example:
2902 You should use the form 'var = !command' instead. Example:
2899
2903
2900 "%sc -l myfiles = ls ~" should now be written as
2904 "%sc -l myfiles = ls ~" should now be written as
2901
2905
2902 "myfiles = !ls ~"
2906 "myfiles = !ls ~"
2903
2907
2904 myfiles.s, myfiles.l and myfiles.n still apply as documented
2908 myfiles.s, myfiles.l and myfiles.n still apply as documented
2905 below.
2909 below.
2906
2910
2907 --
2911 --
2908 %sc [options] varname=command
2912 %sc [options] varname=command
2909
2913
2910 IPython will run the given command using commands.getoutput(), and
2914 IPython will run the given command using commands.getoutput(), and
2911 will then update the user's interactive namespace with a variable
2915 will then update the user's interactive namespace with a variable
2912 called varname, containing the value of the call. Your command can
2916 called varname, containing the value of the call. Your command can
2913 contain shell wildcards, pipes, etc.
2917 contain shell wildcards, pipes, etc.
2914
2918
2915 The '=' sign in the syntax is mandatory, and the variable name you
2919 The '=' sign in the syntax is mandatory, and the variable name you
2916 supply must follow Python's standard conventions for valid names.
2920 supply must follow Python's standard conventions for valid names.
2917
2921
2918 (A special format without variable name exists for internal use)
2922 (A special format without variable name exists for internal use)
2919
2923
2920 Options:
2924 Options:
2921
2925
2922 -l: list output. Split the output on newlines into a list before
2926 -l: list output. Split the output on newlines into a list before
2923 assigning it to the given variable. By default the output is stored
2927 assigning it to the given variable. By default the output is stored
2924 as a single string.
2928 as a single string.
2925
2929
2926 -v: verbose. Print the contents of the variable.
2930 -v: verbose. Print the contents of the variable.
2927
2931
2928 In most cases you should not need to split as a list, because the
2932 In most cases you should not need to split as a list, because the
2929 returned value is a special type of string which can automatically
2933 returned value is a special type of string which can automatically
2930 provide its contents either as a list (split on newlines) or as a
2934 provide its contents either as a list (split on newlines) or as a
2931 space-separated string. These are convenient, respectively, either
2935 space-separated string. These are convenient, respectively, either
2932 for sequential processing or to be passed to a shell command.
2936 for sequential processing or to be passed to a shell command.
2933
2937
2934 For example:
2938 For example:
2935
2939
2936 # all-random
2940 # all-random
2937
2941
2938 # Capture into variable a
2942 # Capture into variable a
2939 In [1]: sc a=ls *py
2943 In [1]: sc a=ls *py
2940
2944
2941 # a is a string with embedded newlines
2945 # a is a string with embedded newlines
2942 In [2]: a
2946 In [2]: a
2943 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2947 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2944
2948
2945 # which can be seen as a list:
2949 # which can be seen as a list:
2946 In [3]: a.l
2950 In [3]: a.l
2947 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2951 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2948
2952
2949 # or as a whitespace-separated string:
2953 # or as a whitespace-separated string:
2950 In [4]: a.s
2954 In [4]: a.s
2951 Out[4]: 'setup.py win32_manual_post_install.py'
2955 Out[4]: 'setup.py win32_manual_post_install.py'
2952
2956
2953 # a.s is useful to pass as a single command line:
2957 # a.s is useful to pass as a single command line:
2954 In [5]: !wc -l $a.s
2958 In [5]: !wc -l $a.s
2955 146 setup.py
2959 146 setup.py
2956 130 win32_manual_post_install.py
2960 130 win32_manual_post_install.py
2957 276 total
2961 276 total
2958
2962
2959 # while the list form is useful to loop over:
2963 # while the list form is useful to loop over:
2960 In [6]: for f in a.l:
2964 In [6]: for f in a.l:
2961 ...: !wc -l $f
2965 ...: !wc -l $f
2962 ...:
2966 ...:
2963 146 setup.py
2967 146 setup.py
2964 130 win32_manual_post_install.py
2968 130 win32_manual_post_install.py
2965
2969
2966 Similiarly, the lists returned by the -l option are also special, in
2970 Similiarly, the lists returned by the -l option are also special, in
2967 the sense that you can equally invoke the .s attribute on them to
2971 the sense that you can equally invoke the .s attribute on them to
2968 automatically get a whitespace-separated string from their contents:
2972 automatically get a whitespace-separated string from their contents:
2969
2973
2970 In [7]: sc -l b=ls *py
2974 In [7]: sc -l b=ls *py
2971
2975
2972 In [8]: b
2976 In [8]: b
2973 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2977 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2974
2978
2975 In [9]: b.s
2979 In [9]: b.s
2976 Out[9]: 'setup.py win32_manual_post_install.py'
2980 Out[9]: 'setup.py win32_manual_post_install.py'
2977
2981
2978 In summary, both the lists and strings used for ouptut capture have
2982 In summary, both the lists and strings used for ouptut capture have
2979 the following special attributes:
2983 the following special attributes:
2980
2984
2981 .l (or .list) : value as list.
2985 .l (or .list) : value as list.
2982 .n (or .nlstr): value as newline-separated string.
2986 .n (or .nlstr): value as newline-separated string.
2983 .s (or .spstr): value as space-separated string.
2987 .s (or .spstr): value as space-separated string.
2984 """
2988 """
2985
2989
2986 opts,args = self.parse_options(parameter_s,'lv')
2990 opts,args = self.parse_options(parameter_s,'lv')
2987 # Try to get a variable name and command to run
2991 # Try to get a variable name and command to run
2988 try:
2992 try:
2989 # the variable name must be obtained from the parse_options
2993 # the variable name must be obtained from the parse_options
2990 # output, which uses shlex.split to strip options out.
2994 # output, which uses shlex.split to strip options out.
2991 var,_ = args.split('=',1)
2995 var,_ = args.split('=',1)
2992 var = var.strip()
2996 var = var.strip()
2993 # But the the command has to be extracted from the original input
2997 # But the the command has to be extracted from the original input
2994 # parameter_s, not on what parse_options returns, to avoid the
2998 # parameter_s, not on what parse_options returns, to avoid the
2995 # quote stripping which shlex.split performs on it.
2999 # quote stripping which shlex.split performs on it.
2996 _,cmd = parameter_s.split('=',1)
3000 _,cmd = parameter_s.split('=',1)
2997 except ValueError:
3001 except ValueError:
2998 var,cmd = '',''
3002 var,cmd = '',''
2999 # If all looks ok, proceed
3003 # If all looks ok, proceed
3000 split = 'l' in opts
3004 split = 'l' in opts
3001 out = self.shell.getoutput(cmd, split=split)
3005 out = self.shell.getoutput(cmd, split=split)
3002 if opts.has_key('v'):
3006 if opts.has_key('v'):
3003 print '%s ==\n%s' % (var,pformat(out))
3007 print '%s ==\n%s' % (var,pformat(out))
3004 if var:
3008 if var:
3005 self.shell.user_ns.update({var:out})
3009 self.shell.user_ns.update({var:out})
3006 else:
3010 else:
3007 return out
3011 return out
3008
3012
3009 def magic_sx(self, parameter_s=''):
3013 def magic_sx(self, parameter_s=''):
3010 """Shell execute - run a shell command and capture its output.
3014 """Shell execute - run a shell command and capture its output.
3011
3015
3012 %sx command
3016 %sx command
3013
3017
3014 IPython will run the given command using commands.getoutput(), and
3018 IPython will run the given command using commands.getoutput(), and
3015 return the result formatted as a list (split on '\\n'). Since the
3019 return the result formatted as a list (split on '\\n'). Since the
3016 output is _returned_, it will be stored in ipython's regular output
3020 output is _returned_, it will be stored in ipython's regular output
3017 cache Out[N] and in the '_N' automatic variables.
3021 cache Out[N] and in the '_N' automatic variables.
3018
3022
3019 Notes:
3023 Notes:
3020
3024
3021 1) If an input line begins with '!!', then %sx is automatically
3025 1) If an input line begins with '!!', then %sx is automatically
3022 invoked. That is, while:
3026 invoked. That is, while:
3023 !ls
3027 !ls
3024 causes ipython to simply issue system('ls'), typing
3028 causes ipython to simply issue system('ls'), typing
3025 !!ls
3029 !!ls
3026 is a shorthand equivalent to:
3030 is a shorthand equivalent to:
3027 %sx ls
3031 %sx ls
3028
3032
3029 2) %sx differs from %sc in that %sx automatically splits into a list,
3033 2) %sx differs from %sc in that %sx automatically splits into a list,
3030 like '%sc -l'. The reason for this is to make it as easy as possible
3034 like '%sc -l'. The reason for this is to make it as easy as possible
3031 to process line-oriented shell output via further python commands.
3035 to process line-oriented shell output via further python commands.
3032 %sc is meant to provide much finer control, but requires more
3036 %sc is meant to provide much finer control, but requires more
3033 typing.
3037 typing.
3034
3038
3035 3) Just like %sc -l, this is a list with special attributes:
3039 3) Just like %sc -l, this is a list with special attributes:
3036
3040
3037 .l (or .list) : value as list.
3041 .l (or .list) : value as list.
3038 .n (or .nlstr): value as newline-separated string.
3042 .n (or .nlstr): value as newline-separated string.
3039 .s (or .spstr): value as whitespace-separated string.
3043 .s (or .spstr): value as whitespace-separated string.
3040
3044
3041 This is very useful when trying to use such lists as arguments to
3045 This is very useful when trying to use such lists as arguments to
3042 system commands."""
3046 system commands."""
3043
3047
3044 if parameter_s:
3048 if parameter_s:
3045 return self.shell.getoutput(parameter_s)
3049 return self.shell.getoutput(parameter_s)
3046
3050
3047
3051
3048 def magic_bookmark(self, parameter_s=''):
3052 def magic_bookmark(self, parameter_s=''):
3049 """Manage IPython's bookmark system.
3053 """Manage IPython's bookmark system.
3050
3054
3051 %bookmark <name> - set bookmark to current dir
3055 %bookmark <name> - set bookmark to current dir
3052 %bookmark <name> <dir> - set bookmark to <dir>
3056 %bookmark <name> <dir> - set bookmark to <dir>
3053 %bookmark -l - list all bookmarks
3057 %bookmark -l - list all bookmarks
3054 %bookmark -d <name> - remove bookmark
3058 %bookmark -d <name> - remove bookmark
3055 %bookmark -r - remove all bookmarks
3059 %bookmark -r - remove all bookmarks
3056
3060
3057 You can later on access a bookmarked folder with:
3061 You can later on access a bookmarked folder with:
3058 %cd -b <name>
3062 %cd -b <name>
3059 or simply '%cd <name>' if there is no directory called <name> AND
3063 or simply '%cd <name>' if there is no directory called <name> AND
3060 there is such a bookmark defined.
3064 there is such a bookmark defined.
3061
3065
3062 Your bookmarks persist through IPython sessions, but they are
3066 Your bookmarks persist through IPython sessions, but they are
3063 associated with each profile."""
3067 associated with each profile."""
3064
3068
3065 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3069 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3066 if len(args) > 2:
3070 if len(args) > 2:
3067 raise UsageError("%bookmark: too many arguments")
3071 raise UsageError("%bookmark: too many arguments")
3068
3072
3069 bkms = self.db.get('bookmarks',{})
3073 bkms = self.db.get('bookmarks',{})
3070
3074
3071 if opts.has_key('d'):
3075 if opts.has_key('d'):
3072 try:
3076 try:
3073 todel = args[0]
3077 todel = args[0]
3074 except IndexError:
3078 except IndexError:
3075 raise UsageError(
3079 raise UsageError(
3076 "%bookmark -d: must provide a bookmark to delete")
3080 "%bookmark -d: must provide a bookmark to delete")
3077 else:
3081 else:
3078 try:
3082 try:
3079 del bkms[todel]
3083 del bkms[todel]
3080 except KeyError:
3084 except KeyError:
3081 raise UsageError(
3085 raise UsageError(
3082 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3086 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3083
3087
3084 elif opts.has_key('r'):
3088 elif opts.has_key('r'):
3085 bkms = {}
3089 bkms = {}
3086 elif opts.has_key('l'):
3090 elif opts.has_key('l'):
3087 bks = bkms.keys()
3091 bks = bkms.keys()
3088 bks.sort()
3092 bks.sort()
3089 if bks:
3093 if bks:
3090 size = max(map(len,bks))
3094 size = max(map(len,bks))
3091 else:
3095 else:
3092 size = 0
3096 size = 0
3093 fmt = '%-'+str(size)+'s -> %s'
3097 fmt = '%-'+str(size)+'s -> %s'
3094 print 'Current bookmarks:'
3098 print 'Current bookmarks:'
3095 for bk in bks:
3099 for bk in bks:
3096 print fmt % (bk,bkms[bk])
3100 print fmt % (bk,bkms[bk])
3097 else:
3101 else:
3098 if not args:
3102 if not args:
3099 raise UsageError("%bookmark: You must specify the bookmark name")
3103 raise UsageError("%bookmark: You must specify the bookmark name")
3100 elif len(args)==1:
3104 elif len(args)==1:
3101 bkms[args[0]] = os.getcwd()
3105 bkms[args[0]] = os.getcwd()
3102 elif len(args)==2:
3106 elif len(args)==2:
3103 bkms[args[0]] = args[1]
3107 bkms[args[0]] = args[1]
3104 self.db['bookmarks'] = bkms
3108 self.db['bookmarks'] = bkms
3105
3109
3106 def magic_pycat(self, parameter_s=''):
3110 def magic_pycat(self, parameter_s=''):
3107 """Show a syntax-highlighted file through a pager.
3111 """Show a syntax-highlighted file through a pager.
3108
3112
3109 This magic is similar to the cat utility, but it will assume the file
3113 This magic is similar to the cat utility, but it will assume the file
3110 to be Python source and will show it with syntax highlighting. """
3114 to be Python source and will show it with syntax highlighting. """
3111
3115
3112 try:
3116 try:
3113 filename = get_py_filename(parameter_s)
3117 filename = get_py_filename(parameter_s)
3114 cont = file_read(filename)
3118 cont = file_read(filename)
3115 except IOError:
3119 except IOError:
3116 try:
3120 try:
3117 cont = eval(parameter_s,self.user_ns)
3121 cont = eval(parameter_s,self.user_ns)
3118 except NameError:
3122 except NameError:
3119 cont = None
3123 cont = None
3120 if cont is None:
3124 if cont is None:
3121 print "Error: no such file or variable"
3125 print "Error: no such file or variable"
3122 return
3126 return
3123
3127
3124 page.page(self.shell.pycolorize(cont))
3128 page.page(self.shell.pycolorize(cont))
3125
3129
3126 def _rerun_pasted(self):
3130 def _rerun_pasted(self):
3127 """ Rerun a previously pasted command.
3131 """ Rerun a previously pasted command.
3128 """
3132 """
3129 b = self.user_ns.get('pasted_block', None)
3133 b = self.user_ns.get('pasted_block', None)
3130 if b is None:
3134 if b is None:
3131 raise UsageError('No previous pasted block available')
3135 raise UsageError('No previous pasted block available')
3132 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3136 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3133 exec b in self.user_ns
3137 exec b in self.user_ns
3134
3138
3135 def _get_pasted_lines(self, sentinel):
3139 def _get_pasted_lines(self, sentinel):
3136 """ Yield pasted lines until the user enters the given sentinel value.
3140 """ Yield pasted lines until the user enters the given sentinel value.
3137 """
3141 """
3138 from IPython.core import interactiveshell
3142 from IPython.core import interactiveshell
3139 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3143 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3140 while True:
3144 while True:
3141 l = interactiveshell.raw_input_original(':')
3145 l = interactiveshell.raw_input_original(':')
3142 if l == sentinel:
3146 if l == sentinel:
3143 return
3147 return
3144 else:
3148 else:
3145 yield l
3149 yield l
3146
3150
3147 def _strip_pasted_lines_for_code(self, raw_lines):
3151 def _strip_pasted_lines_for_code(self, raw_lines):
3148 """ Strip non-code parts of a sequence of lines to return a block of
3152 """ Strip non-code parts of a sequence of lines to return a block of
3149 code.
3153 code.
3150 """
3154 """
3151 # Regular expressions that declare text we strip from the input:
3155 # Regular expressions that declare text we strip from the input:
3152 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3156 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3153 r'^\s*(\s?>)+', # Python input prompt
3157 r'^\s*(\s?>)+', # Python input prompt
3154 r'^\s*\.{3,}', # Continuation prompts
3158 r'^\s*\.{3,}', # Continuation prompts
3155 r'^\++',
3159 r'^\++',
3156 ]
3160 ]
3157
3161
3158 strip_from_start = map(re.compile,strip_re)
3162 strip_from_start = map(re.compile,strip_re)
3159
3163
3160 lines = []
3164 lines = []
3161 for l in raw_lines:
3165 for l in raw_lines:
3162 for pat in strip_from_start:
3166 for pat in strip_from_start:
3163 l = pat.sub('',l)
3167 l = pat.sub('',l)
3164 lines.append(l)
3168 lines.append(l)
3165
3169
3166 block = "\n".join(lines) + '\n'
3170 block = "\n".join(lines) + '\n'
3167 #print "block:\n",block
3171 #print "block:\n",block
3168 return block
3172 return block
3169
3173
3170 def _execute_block(self, block, par):
3174 def _execute_block(self, block, par):
3171 """ Execute a block, or store it in a variable, per the user's request.
3175 """ Execute a block, or store it in a variable, per the user's request.
3172 """
3176 """
3173 if not par:
3177 if not par:
3174 b = textwrap.dedent(block)
3178 b = textwrap.dedent(block)
3175 self.user_ns['pasted_block'] = b
3179 self.user_ns['pasted_block'] = b
3176 exec b in self.user_ns
3180 exec b in self.user_ns
3177 else:
3181 else:
3178 self.user_ns[par] = SList(block.splitlines())
3182 self.user_ns[par] = SList(block.splitlines())
3179 print "Block assigned to '%s'" % par
3183 print "Block assigned to '%s'" % par
3180
3184
3181 def magic_quickref(self,arg):
3185 def magic_quickref(self,arg):
3182 """ Show a quick reference sheet """
3186 """ Show a quick reference sheet """
3183 import IPython.core.usage
3187 import IPython.core.usage
3184 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3188 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3185
3189
3186 page.page(qr)
3190 page.page(qr)
3187
3191
3188 def magic_doctest_mode(self,parameter_s=''):
3192 def magic_doctest_mode(self,parameter_s=''):
3189 """Toggle doctest mode on and off.
3193 """Toggle doctest mode on and off.
3190
3194
3191 This mode is intended to make IPython behave as much as possible like a
3195 This mode is intended to make IPython behave as much as possible like a
3192 plain Python shell, from the perspective of how its prompts, exceptions
3196 plain Python shell, from the perspective of how its prompts, exceptions
3193 and output look. This makes it easy to copy and paste parts of a
3197 and output look. This makes it easy to copy and paste parts of a
3194 session into doctests. It does so by:
3198 session into doctests. It does so by:
3195
3199
3196 - Changing the prompts to the classic ``>>>`` ones.
3200 - Changing the prompts to the classic ``>>>`` ones.
3197 - Changing the exception reporting mode to 'Plain'.
3201 - Changing the exception reporting mode to 'Plain'.
3198 - Disabling pretty-printing of output.
3202 - Disabling pretty-printing of output.
3199
3203
3200 Note that IPython also supports the pasting of code snippets that have
3204 Note that IPython also supports the pasting of code snippets that have
3201 leading '>>>' and '...' prompts in them. This means that you can paste
3205 leading '>>>' and '...' prompts in them. This means that you can paste
3202 doctests from files or docstrings (even if they have leading
3206 doctests from files or docstrings (even if they have leading
3203 whitespace), and the code will execute correctly. You can then use
3207 whitespace), and the code will execute correctly. You can then use
3204 '%history -t' to see the translated history; this will give you the
3208 '%history -t' to see the translated history; this will give you the
3205 input after removal of all the leading prompts and whitespace, which
3209 input after removal of all the leading prompts and whitespace, which
3206 can be pasted back into an editor.
3210 can be pasted back into an editor.
3207
3211
3208 With these features, you can switch into this mode easily whenever you
3212 With these features, you can switch into this mode easily whenever you
3209 need to do testing and changes to doctests, without having to leave
3213 need to do testing and changes to doctests, without having to leave
3210 your existing IPython session.
3214 your existing IPython session.
3211 """
3215 """
3212
3216
3213 from IPython.utils.ipstruct import Struct
3217 from IPython.utils.ipstruct import Struct
3214
3218
3215 # Shorthands
3219 # Shorthands
3216 shell = self.shell
3220 shell = self.shell
3217 oc = shell.displayhook
3221 oc = shell.displayhook
3218 meta = shell.meta
3222 meta = shell.meta
3219 disp_formatter = self.shell.display_formatter
3223 disp_formatter = self.shell.display_formatter
3220 ptformatter = disp_formatter.formatters['text/plain']
3224 ptformatter = disp_formatter.formatters['text/plain']
3221 # dstore is a data store kept in the instance metadata bag to track any
3225 # dstore is a data store kept in the instance metadata bag to track any
3222 # changes we make, so we can undo them later.
3226 # changes we make, so we can undo them later.
3223 dstore = meta.setdefault('doctest_mode',Struct())
3227 dstore = meta.setdefault('doctest_mode',Struct())
3224 save_dstore = dstore.setdefault
3228 save_dstore = dstore.setdefault
3225
3229
3226 # save a few values we'll need to recover later
3230 # save a few values we'll need to recover later
3227 mode = save_dstore('mode',False)
3231 mode = save_dstore('mode',False)
3228 save_dstore('rc_pprint',ptformatter.pprint)
3232 save_dstore('rc_pprint',ptformatter.pprint)
3229 save_dstore('xmode',shell.InteractiveTB.mode)
3233 save_dstore('xmode',shell.InteractiveTB.mode)
3230 save_dstore('rc_separate_out',shell.separate_out)
3234 save_dstore('rc_separate_out',shell.separate_out)
3231 save_dstore('rc_separate_out2',shell.separate_out2)
3235 save_dstore('rc_separate_out2',shell.separate_out2)
3232 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3236 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3233 save_dstore('rc_separate_in',shell.separate_in)
3237 save_dstore('rc_separate_in',shell.separate_in)
3234 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3238 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3235
3239
3236 if mode == False:
3240 if mode == False:
3237 # turn on
3241 # turn on
3238 oc.prompt1.p_template = '>>> '
3242 oc.prompt1.p_template = '>>> '
3239 oc.prompt2.p_template = '... '
3243 oc.prompt2.p_template = '... '
3240 oc.prompt_out.p_template = ''
3244 oc.prompt_out.p_template = ''
3241
3245
3242 # Prompt separators like plain python
3246 # Prompt separators like plain python
3243 oc.input_sep = oc.prompt1.sep = ''
3247 oc.input_sep = oc.prompt1.sep = ''
3244 oc.output_sep = ''
3248 oc.output_sep = ''
3245 oc.output_sep2 = ''
3249 oc.output_sep2 = ''
3246
3250
3247 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3251 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3248 oc.prompt_out.pad_left = False
3252 oc.prompt_out.pad_left = False
3249
3253
3250 ptformatter.pprint = False
3254 ptformatter.pprint = False
3251 disp_formatter.plain_text_only = True
3255 disp_formatter.plain_text_only = True
3252
3256
3253 shell.magic_xmode('Plain')
3257 shell.magic_xmode('Plain')
3254 else:
3258 else:
3255 # turn off
3259 # turn off
3256 oc.prompt1.p_template = shell.prompt_in1
3260 oc.prompt1.p_template = shell.prompt_in1
3257 oc.prompt2.p_template = shell.prompt_in2
3261 oc.prompt2.p_template = shell.prompt_in2
3258 oc.prompt_out.p_template = shell.prompt_out
3262 oc.prompt_out.p_template = shell.prompt_out
3259
3263
3260 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3264 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3261
3265
3262 oc.output_sep = dstore.rc_separate_out
3266 oc.output_sep = dstore.rc_separate_out
3263 oc.output_sep2 = dstore.rc_separate_out2
3267 oc.output_sep2 = dstore.rc_separate_out2
3264
3268
3265 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3269 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3266 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3270 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3267
3271
3268 ptformatter.pprint = dstore.rc_pprint
3272 ptformatter.pprint = dstore.rc_pprint
3269 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3273 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3270
3274
3271 shell.magic_xmode(dstore.xmode)
3275 shell.magic_xmode(dstore.xmode)
3272
3276
3273 # Store new mode and inform
3277 # Store new mode and inform
3274 dstore.mode = bool(1-int(mode))
3278 dstore.mode = bool(1-int(mode))
3275 mode_label = ['OFF','ON'][dstore.mode]
3279 mode_label = ['OFF','ON'][dstore.mode]
3276 print 'Doctest mode is:', mode_label
3280 print 'Doctest mode is:', mode_label
3277
3281
3278 def magic_gui(self, parameter_s=''):
3282 def magic_gui(self, parameter_s=''):
3279 """Enable or disable IPython GUI event loop integration.
3283 """Enable or disable IPython GUI event loop integration.
3280
3284
3281 %gui [GUINAME]
3285 %gui [GUINAME]
3282
3286
3283 This magic replaces IPython's threaded shells that were activated
3287 This magic replaces IPython's threaded shells that were activated
3284 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3288 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3285 can now be enabled, disabled and swtiched at runtime and keyboard
3289 can now be enabled, disabled and swtiched at runtime and keyboard
3286 interrupts should work without any problems. The following toolkits
3290 interrupts should work without any problems. The following toolkits
3287 are supported: wxPython, PyQt4, PyGTK, and Tk::
3291 are supported: wxPython, PyQt4, PyGTK, and Tk::
3288
3292
3289 %gui wx # enable wxPython event loop integration
3293 %gui wx # enable wxPython event loop integration
3290 %gui qt4|qt # enable PyQt4 event loop integration
3294 %gui qt4|qt # enable PyQt4 event loop integration
3291 %gui gtk # enable PyGTK event loop integration
3295 %gui gtk # enable PyGTK event loop integration
3292 %gui tk # enable Tk event loop integration
3296 %gui tk # enable Tk event loop integration
3293 %gui # disable all event loop integration
3297 %gui # disable all event loop integration
3294
3298
3295 WARNING: after any of these has been called you can simply create
3299 WARNING: after any of these has been called you can simply create
3296 an application object, but DO NOT start the event loop yourself, as
3300 an application object, but DO NOT start the event loop yourself, as
3297 we have already handled that.
3301 we have already handled that.
3298 """
3302 """
3299 from IPython.lib.inputhook import enable_gui
3303 from IPython.lib.inputhook import enable_gui
3300 opts, arg = self.parse_options(parameter_s, '')
3304 opts, arg = self.parse_options(parameter_s, '')
3301 if arg=='': arg = None
3305 if arg=='': arg = None
3302 return enable_gui(arg)
3306 return enable_gui(arg)
3303
3307
3304 def magic_load_ext(self, module_str):
3308 def magic_load_ext(self, module_str):
3305 """Load an IPython extension by its module name."""
3309 """Load an IPython extension by its module name."""
3306 return self.extension_manager.load_extension(module_str)
3310 return self.extension_manager.load_extension(module_str)
3307
3311
3308 def magic_unload_ext(self, module_str):
3312 def magic_unload_ext(self, module_str):
3309 """Unload an IPython extension by its module name."""
3313 """Unload an IPython extension by its module name."""
3310 self.extension_manager.unload_extension(module_str)
3314 self.extension_manager.unload_extension(module_str)
3311
3315
3312 def magic_reload_ext(self, module_str):
3316 def magic_reload_ext(self, module_str):
3313 """Reload an IPython extension by its module name."""
3317 """Reload an IPython extension by its module name."""
3314 self.extension_manager.reload_extension(module_str)
3318 self.extension_manager.reload_extension(module_str)
3315
3319
3316 @testdec.skip_doctest
3320 @testdec.skip_doctest
3317 def magic_install_profiles(self, s):
3321 def magic_install_profiles(self, s):
3318 """Install the default IPython profiles into the .ipython dir.
3322 """Install the default IPython profiles into the .ipython dir.
3319
3323
3320 If the default profiles have already been installed, they will not
3324 If the default profiles have already been installed, they will not
3321 be overwritten. You can force overwriting them by using the ``-o``
3325 be overwritten. You can force overwriting them by using the ``-o``
3322 option::
3326 option::
3323
3327
3324 In [1]: %install_profiles -o
3328 In [1]: %install_profiles -o
3325 """
3329 """
3326 if '-o' in s:
3330 if '-o' in s:
3327 overwrite = True
3331 overwrite = True
3328 else:
3332 else:
3329 overwrite = False
3333 overwrite = False
3330 from IPython.config import profile
3334 from IPython.config import profile
3331 profile_dir = os.path.split(profile.__file__)[0]
3335 profile_dir = os.path.split(profile.__file__)[0]
3332 ipython_dir = self.ipython_dir
3336 ipython_dir = self.ipython_dir
3333 files = os.listdir(profile_dir)
3337 files = os.listdir(profile_dir)
3334
3338
3335 to_install = []
3339 to_install = []
3336 for f in files:
3340 for f in files:
3337 if f.startswith('ipython_config'):
3341 if f.startswith('ipython_config'):
3338 src = os.path.join(profile_dir, f)
3342 src = os.path.join(profile_dir, f)
3339 dst = os.path.join(ipython_dir, f)
3343 dst = os.path.join(ipython_dir, f)
3340 if (not os.path.isfile(dst)) or overwrite:
3344 if (not os.path.isfile(dst)) or overwrite:
3341 to_install.append((f, src, dst))
3345 to_install.append((f, src, dst))
3342 if len(to_install)>0:
3346 if len(to_install)>0:
3343 print "Installing profiles to: ", ipython_dir
3347 print "Installing profiles to: ", ipython_dir
3344 for (f, src, dst) in to_install:
3348 for (f, src, dst) in to_install:
3345 shutil.copy(src, dst)
3349 shutil.copy(src, dst)
3346 print " %s" % f
3350 print " %s" % f
3347
3351
3348 def magic_install_default_config(self, s):
3352 def magic_install_default_config(self, s):
3349 """Install IPython's default config file into the .ipython dir.
3353 """Install IPython's default config file into the .ipython dir.
3350
3354
3351 If the default config file (:file:`ipython_config.py`) is already
3355 If the default config file (:file:`ipython_config.py`) is already
3352 installed, it will not be overwritten. You can force overwriting
3356 installed, it will not be overwritten. You can force overwriting
3353 by using the ``-o`` option::
3357 by using the ``-o`` option::
3354
3358
3355 In [1]: %install_default_config
3359 In [1]: %install_default_config
3356 """
3360 """
3357 if '-o' in s:
3361 if '-o' in s:
3358 overwrite = True
3362 overwrite = True
3359 else:
3363 else:
3360 overwrite = False
3364 overwrite = False
3361 from IPython.config import default
3365 from IPython.config import default
3362 config_dir = os.path.split(default.__file__)[0]
3366 config_dir = os.path.split(default.__file__)[0]
3363 ipython_dir = self.ipython_dir
3367 ipython_dir = self.ipython_dir
3364 default_config_file_name = 'ipython_config.py'
3368 default_config_file_name = 'ipython_config.py'
3365 src = os.path.join(config_dir, default_config_file_name)
3369 src = os.path.join(config_dir, default_config_file_name)
3366 dst = os.path.join(ipython_dir, default_config_file_name)
3370 dst = os.path.join(ipython_dir, default_config_file_name)
3367 if (not os.path.isfile(dst)) or overwrite:
3371 if (not os.path.isfile(dst)) or overwrite:
3368 shutil.copy(src, dst)
3372 shutil.copy(src, dst)
3369 print "Installing default config file: %s" % dst
3373 print "Installing default config file: %s" % dst
3370
3374
3371 # Pylab support: simple wrappers that activate pylab, load gui input
3375 # Pylab support: simple wrappers that activate pylab, load gui input
3372 # handling and modify slightly %run
3376 # handling and modify slightly %run
3373
3377
3374 @testdec.skip_doctest
3378 @testdec.skip_doctest
3375 def _pylab_magic_run(self, parameter_s=''):
3379 def _pylab_magic_run(self, parameter_s=''):
3376 Magic.magic_run(self, parameter_s,
3380 Magic.magic_run(self, parameter_s,
3377 runner=mpl_runner(self.shell.safe_execfile))
3381 runner=mpl_runner(self.shell.safe_execfile))
3378
3382
3379 _pylab_magic_run.__doc__ = magic_run.__doc__
3383 _pylab_magic_run.__doc__ = magic_run.__doc__
3380
3384
3381 @testdec.skip_doctest
3385 @testdec.skip_doctest
3382 def magic_pylab(self, s):
3386 def magic_pylab(self, s):
3383 """Load numpy and matplotlib to work interactively.
3387 """Load numpy and matplotlib to work interactively.
3384
3388
3385 %pylab [GUINAME]
3389 %pylab [GUINAME]
3386
3390
3387 This function lets you activate pylab (matplotlib, numpy and
3391 This function lets you activate pylab (matplotlib, numpy and
3388 interactive support) at any point during an IPython session.
3392 interactive support) at any point during an IPython session.
3389
3393
3390 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3394 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3391 pylab and mlab, as well as all names from numpy and pylab.
3395 pylab and mlab, as well as all names from numpy and pylab.
3392
3396
3393 Parameters
3397 Parameters
3394 ----------
3398 ----------
3395 guiname : optional
3399 guiname : optional
3396 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk', 'osx' or
3400 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk', 'osx' or
3397 'tk'). If given, the corresponding Matplotlib backend is used,
3401 'tk'). If given, the corresponding Matplotlib backend is used,
3398 otherwise matplotlib's default (which you can override in your
3402 otherwise matplotlib's default (which you can override in your
3399 matplotlib config file) is used.
3403 matplotlib config file) is used.
3400
3404
3401 Examples
3405 Examples
3402 --------
3406 --------
3403 In this case, where the MPL default is TkAgg:
3407 In this case, where the MPL default is TkAgg:
3404 In [2]: %pylab
3408 In [2]: %pylab
3405
3409
3406 Welcome to pylab, a matplotlib-based Python environment.
3410 Welcome to pylab, a matplotlib-based Python environment.
3407 Backend in use: TkAgg
3411 Backend in use: TkAgg
3408 For more information, type 'help(pylab)'.
3412 For more information, type 'help(pylab)'.
3409
3413
3410 But you can explicitly request a different backend:
3414 But you can explicitly request a different backend:
3411 In [3]: %pylab qt
3415 In [3]: %pylab qt
3412
3416
3413 Welcome to pylab, a matplotlib-based Python environment.
3417 Welcome to pylab, a matplotlib-based Python environment.
3414 Backend in use: Qt4Agg
3418 Backend in use: Qt4Agg
3415 For more information, type 'help(pylab)'.
3419 For more information, type 'help(pylab)'.
3416 """
3420 """
3417 self.shell.enable_pylab(s)
3421 self.shell.enable_pylab(s)
3418
3422
3419 def magic_tb(self, s):
3423 def magic_tb(self, s):
3420 """Print the last traceback with the currently active exception mode.
3424 """Print the last traceback with the currently active exception mode.
3421
3425
3422 See %xmode for changing exception reporting modes."""
3426 See %xmode for changing exception reporting modes."""
3423 self.shell.showtraceback()
3427 self.shell.showtraceback()
3424
3428
3425 @testdec.skip_doctest
3429 @testdec.skip_doctest
3426 def magic_precision(self, s=''):
3430 def magic_precision(self, s=''):
3427 """Set floating point precision for pretty printing.
3431 """Set floating point precision for pretty printing.
3428
3432
3429 Can set either integer precision or a format string.
3433 Can set either integer precision or a format string.
3430
3434
3431 If numpy has been imported and precision is an int,
3435 If numpy has been imported and precision is an int,
3432 numpy display precision will also be set, via ``numpy.set_printoptions``.
3436 numpy display precision will also be set, via ``numpy.set_printoptions``.
3433
3437
3434 If no argument is given, defaults will be restored.
3438 If no argument is given, defaults will be restored.
3435
3439
3436 Examples
3440 Examples
3437 --------
3441 --------
3438 ::
3442 ::
3439
3443
3440 In [1]: from math import pi
3444 In [1]: from math import pi
3441
3445
3442 In [2]: %precision 3
3446 In [2]: %precision 3
3443 Out[2]: '%.3f'
3447 Out[2]: '%.3f'
3444
3448
3445 In [3]: pi
3449 In [3]: pi
3446 Out[3]: 3.142
3450 Out[3]: 3.142
3447
3451
3448 In [4]: %precision %i
3452 In [4]: %precision %i
3449 Out[4]: '%i'
3453 Out[4]: '%i'
3450
3454
3451 In [5]: pi
3455 In [5]: pi
3452 Out[5]: 3
3456 Out[5]: 3
3453
3457
3454 In [6]: %precision %e
3458 In [6]: %precision %e
3455 Out[6]: '%e'
3459 Out[6]: '%e'
3456
3460
3457 In [7]: pi**10
3461 In [7]: pi**10
3458 Out[7]: 9.364805e+04
3462 Out[7]: 9.364805e+04
3459
3463
3460 In [8]: %precision
3464 In [8]: %precision
3461 Out[8]: '%r'
3465 Out[8]: '%r'
3462
3466
3463 In [9]: pi**10
3467 In [9]: pi**10
3464 Out[9]: 93648.047476082982
3468 Out[9]: 93648.047476082982
3465
3469
3466 """
3470 """
3467
3471
3468 ptformatter = self.shell.display_formatter.formatters['text/plain']
3472 ptformatter = self.shell.display_formatter.formatters['text/plain']
3469 ptformatter.float_precision = s
3473 ptformatter.float_precision = s
3470 return ptformatter.float_format
3474 return ptformatter.float_format
3471
3475
3472 # end Magic
3476 # end Magic
General Comments 0
You need to be logged in to leave comments. Login now