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