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