##// END OF EJS Templates
FakeModule.py => core/fakemodule.py and updated tests and imports.
Brian Granger -
Show More
@@ -1,311 +1,311 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 %jot magic for lightweight persistence.
4 4
5 5 Stores variables in Struct with some notes in PicleShare database
6 6
7 7
8 8 """
9 9
10 10 from datetime import datetime
11 11 import IPython.ipapi
12 12 ip = IPython.ipapi.get()
13 13
14 14 import pickleshare
15 15
16 16 import inspect,pickle,os,sys,textwrap
17 from IPython.FakeModule import FakeModule
17 from IPython.core.fakemodule import FakeModule
18 18 from IPython.ipstruct import Struct
19 19
20 20
21 21 def refresh_variables(ip, key=None):
22 22 db = ip.db
23 23 if key is None:
24 24 keys = db.keys('jot/*')
25 25 else:
26 26 keys = db.keys('jot/'+key)
27 27 for key in keys:
28 28 # strip autorestore
29 29 justkey = os.path.basename(key)
30 30 print "Restoring from", justkey, "..."
31 31 try:
32 32 obj = db[key]
33 33 except KeyError:
34 34 print "Unable to restore variable '%s', ignoring (use %%jot -d to forget!)" % justkey
35 35 print "The error was:",sys.exc_info()[0]
36 36 else:
37 37 #print "restored",justkey,"=",obj #dbg
38 38 try:
39 39 origname = obj.name
40 40 except:
41 41 ip.user_ns[justkey] = obj
42 42 print "Restored", justkey
43 43 else:
44 44 ip.user_ns[origname] = obj['val']
45 45 print "Restored", origname
46 46
47 47 def read_variables(ip, key=None):
48 48 db = ip.db
49 49 if key is None:
50 50 return None
51 51 else:
52 52 keys = db.keys('jot/'+key)
53 53 for key in keys:
54 54 # strip autorestore
55 55 justkey = os.path.basename(key)
56 56 print "restoring from ", justkey
57 57 try:
58 58 obj = db[key]
59 59 except KeyError:
60 60 print "Unable to read variable '%s', ignoring (use %%jot -d to forget!)" % justkey
61 61 print "The error was:",sys.exc_info()[0]
62 62 else:
63 63 return obj
64 64
65 65
66 66 def detail_variables(ip, key=None):
67 67 db, get = ip.db, ip.db.get
68 68
69 69 if key is None:
70 70 keys = db.keys('jot/*')
71 71 else:
72 72 keys = db.keys('jot/'+key)
73 73 if keys:
74 74 size = max(map(len,keys))
75 75 else:
76 76 size = 0
77 77
78 78 fmthead = '%-'+str(size)+'s [%s]'
79 79 fmtbody = 'Comment:\n %s'
80 80 fmtdata = 'Data:\n %s, %s'
81 81 for key in keys:
82 82 v = get(key,'<unavailable>')
83 83 justkey = os.path.basename(key)
84 84 try:
85 85 print fmthead % (justkey, datetime.ctime(v.get('time','<unavailable>')))
86 86 print fmtbody % (v.get('comment','<unavailable>'))
87 87 d = v.get('val','unavailable')
88 88 print fmtdata % (repr(type(d)), '')
89 89 print repr(d)[0:200]
90 90 print
91 91 print
92 92 except AttributeError:
93 93 print fmt % (justkey, '<unavailable>', '<unavailable>', repr(v)[:50])
94 94
95 95
96 96 def intm(n):
97 97 try:
98 98 return int(n)
99 99 except:
100 100 return 0
101 101
102 102 def jot_obj(self, obj, name, comment=''):
103 103 """
104 104 write obj data to the note database, with whatever that should be noted.
105 105 """
106 106 had = self.db.keys('jot/'+name+'*')
107 107 # if it the same name but a later version, we stupidly add a number to the
108 108 # so the name doesn't collide. Any better idea?
109 109 suffix = ''
110 110 if len(had)>0:
111 111 pre = os.path.commonprefix(had)
112 112 suf = [n.split(pre)[1] for n in had]
113 113 versions = map(intm, suf)
114 114 suffix = str(max(versions)+1)
115 115
116 116 uname = 'jot/'+name+suffix
117 117
118 118 # which one works better?
119 119 #all = ip.IP.shadowhist.all()
120 120 all = ip.IP.shell.input_hist
121 121
122 122 # We may actually want to make snapshot of files that are run-ned.
123 123
124 124 # get the comment
125 125 try:
126 126 comment = ip.IP.magic_edit('-x').strip()
127 127 except:
128 128 print "No comment is recorded."
129 129 comment = ''
130 130
131 131 self.db[uname] = Struct({'val':obj,
132 132 'time' : datetime.now(),
133 133 'hist' : all,
134 134 'name' : name,
135 135 'comment' : comment,})
136 136
137 137 print "Jotted down notes for '%s' (%s)" % (uname, obj.__class__.__name__)
138 138
139 139
140 140
141 141 def magic_jot(self, parameter_s=''):
142 142 """Lightweight persistence for python variables.
143 143
144 144 Example:
145 145
146 146 ville@badger[~]|1> A = ['hello',10,'world']\\
147 147 ville@badger[~]|2> %jot A\\
148 148 ville@badger[~]|3> Exit
149 149
150 150 (IPython session is closed and started again...)
151 151
152 152 ville@badger:~$ ipython -p pysh\\
153 153 ville@badger[~]|1> print A
154 154
155 155 ['hello', 10, 'world']
156 156
157 157 Usage:
158 158
159 159 %jot - Show list of all variables and their current values\\
160 160 %jot -l - Show list of all variables and their current values in detail\\
161 161 %jot -l <var> - Show one variable and its current values in detail\\
162 162 %jot <var> - Store the *current* value of the variable to disk\\
163 163 %jot -d <var> - Remove the variable and its value from storage\\
164 164 %jot -z - Remove all variables from storage (disabled)\\
165 165 %jot -r <var> - Refresh/Load variable from jot (delete current vals)\\
166 166 %jot foo >a.txt - Store value of foo to new file a.txt\\
167 167 %jot foo >>a.txt - Append value of foo to file a.txt\\
168 168
169 169 It should be noted that if you change the value of a variable, you
170 170 need to %note it again if you want to persist the new value.
171 171
172 172 Note also that the variables will need to be pickleable; most basic
173 173 python types can be safely %stored.
174 174
175 175 """
176 176
177 177 opts,argsl = self.parse_options(parameter_s,'drzl',mode='string')
178 178 args = argsl.split(None,1)
179 179 ip = self.getapi()
180 180 db = ip.db
181 181 # delete
182 182 if opts.has_key('d'):
183 183 try:
184 184 todel = args[0]
185 185 except IndexError:
186 186 error('You must provide the variable to forget')
187 187 else:
188 188 try:
189 189 del db['jot/' + todel]
190 190 except:
191 191 error("Can't delete variable '%s'" % todel)
192 192 # reset the whole database
193 193 elif opts.has_key('z'):
194 194 print "reseting the whole database has been disabled."
195 195 #for k in db.keys('autorestore/*'):
196 196 # del db[k]
197 197
198 198 elif opts.has_key('r'):
199 199 try:
200 200 toret = args[0]
201 201 except:
202 202 print "restoring all the variables jotted down..."
203 203 refresh_variables(ip)
204 204 else:
205 205 refresh_variables(ip, toret)
206 206
207 207 elif opts.has_key('l'):
208 208 try:
209 209 tolist = args[0]
210 210 except:
211 211 print "List details for all the items."
212 212 detail_variables(ip)
213 213 else:
214 214 print "Details for", tolist, ":"
215 215 detail_variables(ip, tolist)
216 216
217 217 # run without arguments -> list noted variables & notes
218 218 elif not args:
219 219 vars = self.db.keys('jot/*')
220 220 vars.sort()
221 221 if vars:
222 222 size = max(map(len,vars)) - 4
223 223 else:
224 224 size = 0
225 225
226 226 print 'Variables and their in-db values:'
227 227 fmt = '%-'+str(size)+'s [%s] -> %s'
228 228 get = db.get
229 229 for var in vars:
230 230 justkey = os.path.basename(var)
231 231 v = get(var,'<unavailable>')
232 232 try:
233 233 print fmt % (justkey,\
234 234 datetime.ctime(v.get('time','<unavailable>')),\
235 235 v.get('comment','<unavailable>')[:70].replace('\n',' '),)
236 236 except AttributeError:
237 237 print fmt % (justkey, '<unavailable>', '<unavailable>', repr(v)[:50])
238 238
239 239
240 240 # default action - store the variable
241 241 else:
242 242 # %store foo >file.txt or >>file.txt
243 243 if len(args) > 1 and args[1].startswith('>'):
244 244 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
245 245 if args[1].startswith('>>'):
246 246 fil = open(fnam,'a')
247 247 else:
248 248 fil = open(fnam,'w')
249 249 obj = ip.ev(args[0])
250 250 print "Writing '%s' (%s) to file '%s'." % (args[0],
251 251 obj.__class__.__name__, fnam)
252 252
253 253
254 254 if not isinstance (obj,basestring):
255 255 from pprint import pprint
256 256 pprint(obj,fil)
257 257 else:
258 258 fil.write(obj)
259 259 if not obj.endswith('\n'):
260 260 fil.write('\n')
261 261
262 262 fil.close()
263 263 return
264 264
265 265 # %note foo
266 266 try:
267 267 obj = ip.user_ns[args[0]]
268 268 except KeyError:
269 269 # this should not be alias, for aliases, use %store
270 270 print
271 271 print "Error: %s doesn't exist." % args[0]
272 272 print
273 273 print "Use %note -r <var> to retrieve variables. This should not be used " +\
274 274 "to store alias, for saving aliases, use %store"
275 275 return
276 276 else:
277 277 if isinstance(inspect.getmodule(obj), FakeModule):
278 278 print textwrap.dedent("""\
279 279 Warning:%s is %s
280 280 Proper storage of interactively declared classes (or instances
281 281 of those classes) is not possible! Only instances
282 282 of classes in real modules on file system can be %%store'd.
283 283 """ % (args[0], obj) )
284 284 return
285 285 #pickled = pickle.dumps(obj)
286 286 #self.db[ 'jot/' + args[0] ] = obj
287 287 jot_obj(self, obj, args[0])
288 288
289 289
290 290 def magic_read(self, parameter_s=''):
291 291 """
292 292 %read <var> - Load variable from data that is jotted down.\\
293 293
294 294 """
295 295
296 296 opts,argsl = self.parse_options(parameter_s,'drzl',mode='string')
297 297 args = argsl.split(None,1)
298 298 ip = self.getapi()
299 299 db = ip.db
300 300 #if opts.has_key('r'):
301 301 try:
302 302 toret = args[0]
303 303 except:
304 304 print "which record do you want to read out?"
305 305 return
306 306 else:
307 307 return read_variables(ip, toret)
308 308
309 309
310 310 ip.expose_magic('jot',magic_jot)
311 311 ip.expose_magic('read',magic_read)
@@ -1,182 +1,182 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 %store magic for lightweight persistence.
4 4
5 5 Stores variables, aliases etc. in PickleShare database.
6 6 """
7 7
8 8 import IPython.ipapi
9 9 from IPython.ipapi import UsageError
10 10 ip = IPython.ipapi.get()
11 11
12 12 import pickleshare
13 13
14 14 import inspect,pickle,os,sys,textwrap
15 from IPython.FakeModule import FakeModule
15 from IPython.core.fakemodule import FakeModule
16 16
17 17 def restore_aliases(self):
18 18 ip = self.getapi()
19 19 staliases = ip.db.get('stored_aliases', {})
20 20 for k,v in staliases.items():
21 21 #print "restore alias",k,v # dbg
22 22 #self.alias_table[k] = v
23 23 ip.defalias(k,v)
24 24
25 25
26 26 def refresh_variables(ip):
27 27 db = ip.db
28 28 for key in db.keys('autorestore/*'):
29 29 # strip autorestore
30 30 justkey = os.path.basename(key)
31 31 try:
32 32 obj = db[key]
33 33 except KeyError:
34 34 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey
35 35 print "The error was:",sys.exc_info()[0]
36 36 else:
37 37 #print "restored",justkey,"=",obj #dbg
38 38 ip.user_ns[justkey] = obj
39 39
40 40
41 41 def restore_dhist(ip):
42 42 db = ip.db
43 43 ip.user_ns['_dh'] = db.get('dhist',[])
44 44
45 45 def restore_data(self):
46 46 ip = self.getapi()
47 47 refresh_variables(ip)
48 48 restore_aliases(self)
49 49 restore_dhist(self)
50 50 raise IPython.ipapi.TryNext
51 51
52 52 ip.set_hook('late_startup_hook', restore_data)
53 53
54 54 def magic_store(self, parameter_s=''):
55 55 """Lightweight persistence for python variables.
56 56
57 57 Example:
58 58
59 59 ville@badger[~]|1> A = ['hello',10,'world']\\
60 60 ville@badger[~]|2> %store A\\
61 61 ville@badger[~]|3> Exit
62 62
63 63 (IPython session is closed and started again...)
64 64
65 65 ville@badger:~$ ipython -p pysh\\
66 66 ville@badger[~]|1> print A
67 67
68 68 ['hello', 10, 'world']
69 69
70 70 Usage:
71 71
72 72 %store - Show list of all variables and their current values\\
73 73 %store <var> - Store the *current* value of the variable to disk\\
74 74 %store -d <var> - Remove the variable and its value from storage\\
75 75 %store -z - Remove all variables from storage\\
76 76 %store -r - Refresh all variables from store (delete current vals)\\
77 77 %store foo >a.txt - Store value of foo to new file a.txt\\
78 78 %store foo >>a.txt - Append value of foo to file a.txt\\
79 79
80 80 It should be noted that if you change the value of a variable, you
81 81 need to %store it again if you want to persist the new value.
82 82
83 83 Note also that the variables will need to be pickleable; most basic
84 84 python types can be safely %stored.
85 85
86 86 Also aliases can be %store'd across sessions.
87 87 """
88 88
89 89 opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
90 90 args = argsl.split(None,1)
91 91 ip = self.getapi()
92 92 db = ip.db
93 93 # delete
94 94 if opts.has_key('d'):
95 95 try:
96 96 todel = args[0]
97 97 except IndexError:
98 98 raise UsageError('You must provide the variable to forget')
99 99 else:
100 100 try:
101 101 del db['autorestore/' + todel]
102 102 except:
103 103 raise UsageError("Can't delete variable '%s'" % todel)
104 104 # reset
105 105 elif opts.has_key('z'):
106 106 for k in db.keys('autorestore/*'):
107 107 del db[k]
108 108
109 109 elif opts.has_key('r'):
110 110 refresh_variables(ip)
111 111
112 112
113 113 # run without arguments -> list variables & values
114 114 elif not args:
115 115 vars = self.db.keys('autorestore/*')
116 116 vars.sort()
117 117 if vars:
118 118 size = max(map(len,vars))
119 119 else:
120 120 size = 0
121 121
122 122 print 'Stored variables and their in-db values:'
123 123 fmt = '%-'+str(size)+'s -> %s'
124 124 get = db.get
125 125 for var in vars:
126 126 justkey = os.path.basename(var)
127 127 # print 30 first characters from every var
128 128 print fmt % (justkey,repr(get(var,'<unavailable>'))[:50])
129 129
130 130 # default action - store the variable
131 131 else:
132 132 # %store foo >file.txt or >>file.txt
133 133 if len(args) > 1 and args[1].startswith('>'):
134 134 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
135 135 if args[1].startswith('>>'):
136 136 fil = open(fnam,'a')
137 137 else:
138 138 fil = open(fnam,'w')
139 139 obj = ip.ev(args[0])
140 140 print "Writing '%s' (%s) to file '%s'." % (args[0],
141 141 obj.__class__.__name__, fnam)
142 142
143 143
144 144 if not isinstance (obj,basestring):
145 145 from pprint import pprint
146 146 pprint(obj,fil)
147 147 else:
148 148 fil.write(obj)
149 149 if not obj.endswith('\n'):
150 150 fil.write('\n')
151 151
152 152 fil.close()
153 153 return
154 154
155 155 # %store foo
156 156 try:
157 157 obj = ip.user_ns[args[0]]
158 158 except KeyError:
159 159 # it might be an alias
160 160 if args[0] in self.alias_table:
161 161 staliases = db.get('stored_aliases',{})
162 162 staliases[ args[0] ] = self.alias_table[ args[0] ]
163 163 db['stored_aliases'] = staliases
164 164 print "Alias stored:", args[0], self.alias_table[ args[0] ]
165 165 return
166 166 else:
167 167 raise UsageError("Unknown variable '%s'" % args[0])
168 168
169 169 else:
170 170 if isinstance(inspect.getmodule(obj), FakeModule):
171 171 print textwrap.dedent("""\
172 172 Warning:%s is %s
173 173 Proper storage of interactively declared classes (or instances
174 174 of those classes) is not possible! Only instances
175 175 of classes in real modules on file system can be %%store'd.
176 176 """ % (args[0], obj) )
177 177 return
178 178 #pickled = pickle.dumps(obj)
179 179 self.db[ 'autorestore/' + args[0] ] = obj
180 180 print "Stored '%s' (%s)" % (args[0], obj.__class__.__name__)
181 181
182 182 ip.expose_magic('store',magic_store)
@@ -1,3457 +1,3457 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #*****************************************************************************
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #*****************************************************************************
12 12
13 13 #****************************************************************************
14 14 # Modules and globals
15 15
16 16 # Python standard modules
17 17 import __builtin__
18 18 import bdb
19 19 import inspect
20 20 import os
21 21 import pdb
22 22 import pydoc
23 23 import sys
24 24 import re
25 25 import tempfile
26 26 import time
27 27 import cPickle as pickle
28 28 import textwrap
29 29 from cStringIO import StringIO
30 30 from getopt import getopt,GetoptError
31 31 from pprint import pprint, pformat
32 32
33 33 # cProfile was added in Python2.5
34 34 try:
35 35 import cProfile as profile
36 36 import pstats
37 37 except ImportError:
38 38 # profile isn't bundled by default in Debian for license reasons
39 39 try:
40 40 import profile,pstats
41 41 except ImportError:
42 42 profile = pstats = None
43 43
44 44 # Homebrewed
45 45 import IPython
46 46 from IPython import OInspect, wildcard
47 47 from IPython.core import debugger
48 from IPython.FakeModule import FakeModule
48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.Itpl import Itpl, itpl, printpl,itplns
50 50 from IPython.PyColorize import Parser
51 51 from IPython.ipstruct import Struct
52 52 from IPython.macro import Macro
53 53 from IPython.genutils import *
54 54 from IPython import platutils
55 55 import IPython.generics
56 56 import IPython.ipapi
57 57 from IPython.ipapi import UsageError
58 58 from IPython.testing import decorators as testdec
59 59
60 60 #***************************************************************************
61 61 # Utility functions
62 62 def on_off(tag):
63 63 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
64 64 return ['OFF','ON'][tag]
65 65
66 66 class Bunch: pass
67 67
68 68 def compress_dhist(dh):
69 69 head, tail = dh[:-10], dh[-10:]
70 70
71 71 newhead = []
72 72 done = set()
73 73 for h in head:
74 74 if h in done:
75 75 continue
76 76 newhead.append(h)
77 77 done.add(h)
78 78
79 79 return newhead + tail
80 80
81 81
82 82 #***************************************************************************
83 83 # Main class implementing Magic functionality
84 84 class Magic:
85 85 """Magic functions for InteractiveShell.
86 86
87 87 Shell functions which can be reached as %function_name. All magic
88 88 functions should accept a string, which they can parse for their own
89 89 needs. This can make some functions easier to type, eg `%cd ../`
90 90 vs. `%cd("../")`
91 91
92 92 ALL definitions MUST begin with the prefix magic_. The user won't need it
93 93 at the command line, but it is is needed in the definition. """
94 94
95 95 # class globals
96 96 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
97 97 'Automagic is ON, % prefix NOT needed for magic functions.']
98 98
99 99 #......................................................................
100 100 # some utility functions
101 101
102 102 def __init__(self,shell):
103 103
104 104 self.options_table = {}
105 105 if profile is None:
106 106 self.magic_prun = self.profile_missing_notice
107 107 self.shell = shell
108 108
109 109 # namespace for holding state we may need
110 110 self._magic_state = Bunch()
111 111
112 112 def profile_missing_notice(self, *args, **kwargs):
113 113 error("""\
114 114 The profile module could not be found. It has been removed from the standard
115 115 python packages because of its non-free license. To use profiling, install the
116 116 python-profiler package from non-free.""")
117 117
118 118 def default_option(self,fn,optstr):
119 119 """Make an entry in the options_table for fn, with value optstr"""
120 120
121 121 if fn not in self.lsmagic():
122 122 error("%s is not a magic function" % fn)
123 123 self.options_table[fn] = optstr
124 124
125 125 def lsmagic(self):
126 126 """Return a list of currently available magic functions.
127 127
128 128 Gives a list of the bare names after mangling (['ls','cd', ...], not
129 129 ['magic_ls','magic_cd',...]"""
130 130
131 131 # FIXME. This needs a cleanup, in the way the magics list is built.
132 132
133 133 # magics in class definition
134 134 class_magic = lambda fn: fn.startswith('magic_') and \
135 135 callable(Magic.__dict__[fn])
136 136 # in instance namespace (run-time user additions)
137 137 inst_magic = lambda fn: fn.startswith('magic_') and \
138 138 callable(self.__dict__[fn])
139 139 # and bound magics by user (so they can access self):
140 140 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
141 141 callable(self.__class__.__dict__[fn])
142 142 magics = filter(class_magic,Magic.__dict__.keys()) + \
143 143 filter(inst_magic,self.__dict__.keys()) + \
144 144 filter(inst_bound_magic,self.__class__.__dict__.keys())
145 145 out = []
146 146 for fn in set(magics):
147 147 out.append(fn.replace('magic_','',1))
148 148 out.sort()
149 149 return out
150 150
151 151 def extract_input_slices(self,slices,raw=False):
152 152 """Return as a string a set of input history slices.
153 153
154 154 Inputs:
155 155
156 156 - slices: the set of slices is given as a list of strings (like
157 157 ['1','4:8','9'], since this function is for use by magic functions
158 158 which get their arguments as strings.
159 159
160 160 Optional inputs:
161 161
162 162 - raw(False): by default, the processed input is used. If this is
163 163 true, the raw input history is used instead.
164 164
165 165 Note that slices can be called with two notations:
166 166
167 167 N:M -> standard python form, means including items N...(M-1).
168 168
169 169 N-M -> include items N..M (closed endpoint)."""
170 170
171 171 if raw:
172 172 hist = self.shell.input_hist_raw
173 173 else:
174 174 hist = self.shell.input_hist
175 175
176 176 cmds = []
177 177 for chunk in slices:
178 178 if ':' in chunk:
179 179 ini,fin = map(int,chunk.split(':'))
180 180 elif '-' in chunk:
181 181 ini,fin = map(int,chunk.split('-'))
182 182 fin += 1
183 183 else:
184 184 ini = int(chunk)
185 185 fin = ini+1
186 186 cmds.append(hist[ini:fin])
187 187 return cmds
188 188
189 189 def _ofind(self, oname, namespaces=None):
190 190 """Find an object in the available namespaces.
191 191
192 192 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
193 193
194 194 Has special code to detect magic functions.
195 195 """
196 196
197 197 oname = oname.strip()
198 198
199 199 alias_ns = None
200 200 if namespaces is None:
201 201 # Namespaces to search in:
202 202 # Put them in a list. The order is important so that we
203 203 # find things in the same order that Python finds them.
204 204 namespaces = [ ('Interactive', self.shell.user_ns),
205 205 ('IPython internal', self.shell.internal_ns),
206 206 ('Python builtin', __builtin__.__dict__),
207 207 ('Alias', self.shell.alias_table),
208 208 ]
209 209 alias_ns = self.shell.alias_table
210 210
211 211 # initialize results to 'null'
212 212 found = 0; obj = None; ospace = None; ds = None;
213 213 ismagic = 0; isalias = 0; parent = None
214 214
215 215 # Look for the given name by splitting it in parts. If the head is
216 216 # found, then we look for all the remaining parts as members, and only
217 217 # declare success if we can find them all.
218 218 oname_parts = oname.split('.')
219 219 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
220 220 for nsname,ns in namespaces:
221 221 try:
222 222 obj = ns[oname_head]
223 223 except KeyError:
224 224 continue
225 225 else:
226 226 #print 'oname_rest:', oname_rest # dbg
227 227 for part in oname_rest:
228 228 try:
229 229 parent = obj
230 230 obj = getattr(obj,part)
231 231 except:
232 232 # Blanket except b/c some badly implemented objects
233 233 # allow __getattr__ to raise exceptions other than
234 234 # AttributeError, which then crashes IPython.
235 235 break
236 236 else:
237 237 # If we finish the for loop (no break), we got all members
238 238 found = 1
239 239 ospace = nsname
240 240 if ns == alias_ns:
241 241 isalias = 1
242 242 break # namespace loop
243 243
244 244 # Try to see if it's magic
245 245 if not found:
246 246 if oname.startswith(self.shell.ESC_MAGIC):
247 247 oname = oname[1:]
248 248 obj = getattr(self,'magic_'+oname,None)
249 249 if obj is not None:
250 250 found = 1
251 251 ospace = 'IPython internal'
252 252 ismagic = 1
253 253
254 254 # Last try: special-case some literals like '', [], {}, etc:
255 255 if not found and oname_head in ["''",'""','[]','{}','()']:
256 256 obj = eval(oname_head)
257 257 found = 1
258 258 ospace = 'Interactive'
259 259
260 260 return {'found':found, 'obj':obj, 'namespace':ospace,
261 261 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
262 262
263 263 def arg_err(self,func):
264 264 """Print docstring if incorrect arguments were passed"""
265 265 print 'Error in arguments:'
266 266 print OInspect.getdoc(func)
267 267
268 268 def format_latex(self,strng):
269 269 """Format a string for latex inclusion."""
270 270
271 271 # Characters that need to be escaped for latex:
272 272 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
273 273 # Magic command names as headers:
274 274 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
275 275 re.MULTILINE)
276 276 # Magic commands
277 277 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
278 278 re.MULTILINE)
279 279 # Paragraph continue
280 280 par_re = re.compile(r'\\$',re.MULTILINE)
281 281
282 282 # The "\n" symbol
283 283 newline_re = re.compile(r'\\n')
284 284
285 285 # Now build the string for output:
286 286 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
287 287 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
288 288 strng)
289 289 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
290 290 strng = par_re.sub(r'\\\\',strng)
291 291 strng = escape_re.sub(r'\\\1',strng)
292 292 strng = newline_re.sub(r'\\textbackslash{}n',strng)
293 293 return strng
294 294
295 295 def format_screen(self,strng):
296 296 """Format a string for screen printing.
297 297
298 298 This removes some latex-type format codes."""
299 299 # Paragraph continue
300 300 par_re = re.compile(r'\\$',re.MULTILINE)
301 301 strng = par_re.sub('',strng)
302 302 return strng
303 303
304 304 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
305 305 """Parse options passed to an argument string.
306 306
307 307 The interface is similar to that of getopt(), but it returns back a
308 308 Struct with the options as keys and the stripped argument string still
309 309 as a string.
310 310
311 311 arg_str is quoted as a true sys.argv vector by using shlex.split.
312 312 This allows us to easily expand variables, glob files, quote
313 313 arguments, etc.
314 314
315 315 Options:
316 316 -mode: default 'string'. If given as 'list', the argument string is
317 317 returned as a list (split on whitespace) instead of a string.
318 318
319 319 -list_all: put all option values in lists. Normally only options
320 320 appearing more than once are put in a list.
321 321
322 322 -posix (True): whether to split the input line in POSIX mode or not,
323 323 as per the conventions outlined in the shlex module from the
324 324 standard library."""
325 325
326 326 # inject default options at the beginning of the input line
327 327 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
328 328 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
329 329
330 330 mode = kw.get('mode','string')
331 331 if mode not in ['string','list']:
332 332 raise ValueError,'incorrect mode given: %s' % mode
333 333 # Get options
334 334 list_all = kw.get('list_all',0)
335 335 posix = kw.get('posix',True)
336 336
337 337 # Check if we have more than one argument to warrant extra processing:
338 338 odict = {} # Dictionary with options
339 339 args = arg_str.split()
340 340 if len(args) >= 1:
341 341 # If the list of inputs only has 0 or 1 thing in it, there's no
342 342 # need to look for options
343 343 argv = arg_split(arg_str,posix)
344 344 # Do regular option processing
345 345 try:
346 346 opts,args = getopt(argv,opt_str,*long_opts)
347 347 except GetoptError,e:
348 348 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
349 349 " ".join(long_opts)))
350 350 for o,a in opts:
351 351 if o.startswith('--'):
352 352 o = o[2:]
353 353 else:
354 354 o = o[1:]
355 355 try:
356 356 odict[o].append(a)
357 357 except AttributeError:
358 358 odict[o] = [odict[o],a]
359 359 except KeyError:
360 360 if list_all:
361 361 odict[o] = [a]
362 362 else:
363 363 odict[o] = a
364 364
365 365 # Prepare opts,args for return
366 366 opts = Struct(odict)
367 367 if mode == 'string':
368 368 args = ' '.join(args)
369 369
370 370 return opts,args
371 371
372 372 #......................................................................
373 373 # And now the actual magic functions
374 374
375 375 # Functions for IPython shell work (vars,funcs, config, etc)
376 376 def magic_lsmagic(self, parameter_s = ''):
377 377 """List currently available magic functions."""
378 378 mesc = self.shell.ESC_MAGIC
379 379 print 'Available magic functions:\n'+mesc+\
380 380 (' '+mesc).join(self.lsmagic())
381 381 print '\n' + Magic.auto_status[self.shell.rc.automagic]
382 382 return None
383 383
384 384 def magic_magic(self, parameter_s = ''):
385 385 """Print information about the magic function system.
386 386
387 387 Supported formats: -latex, -brief, -rest
388 388 """
389 389
390 390 mode = ''
391 391 try:
392 392 if parameter_s.split()[0] == '-latex':
393 393 mode = 'latex'
394 394 if parameter_s.split()[0] == '-brief':
395 395 mode = 'brief'
396 396 if parameter_s.split()[0] == '-rest':
397 397 mode = 'rest'
398 398 rest_docs = []
399 399 except:
400 400 pass
401 401
402 402 magic_docs = []
403 403 for fname in self.lsmagic():
404 404 mname = 'magic_' + fname
405 405 for space in (Magic,self,self.__class__):
406 406 try:
407 407 fn = space.__dict__[mname]
408 408 except KeyError:
409 409 pass
410 410 else:
411 411 break
412 412 if mode == 'brief':
413 413 # only first line
414 414 if fn.__doc__:
415 415 fndoc = fn.__doc__.split('\n',1)[0]
416 416 else:
417 417 fndoc = 'No documentation'
418 418 else:
419 419 if fn.__doc__:
420 420 fndoc = fn.__doc__.rstrip()
421 421 else:
422 422 fndoc = 'No documentation'
423 423
424 424
425 425 if mode == 'rest':
426 426 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(self.shell.ESC_MAGIC,
427 427 fname,fndoc))
428 428
429 429 else:
430 430 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
431 431 fname,fndoc))
432 432
433 433 magic_docs = ''.join(magic_docs)
434 434
435 435 if mode == 'rest':
436 436 return "".join(rest_docs)
437 437
438 438 if mode == 'latex':
439 439 print self.format_latex(magic_docs)
440 440 return
441 441 else:
442 442 magic_docs = self.format_screen(magic_docs)
443 443 if mode == 'brief':
444 444 return magic_docs
445 445
446 446 outmsg = """
447 447 IPython's 'magic' functions
448 448 ===========================
449 449
450 450 The magic function system provides a series of functions which allow you to
451 451 control the behavior of IPython itself, plus a lot of system-type
452 452 features. All these functions are prefixed with a % character, but parameters
453 453 are given without parentheses or quotes.
454 454
455 455 NOTE: If you have 'automagic' enabled (via the command line option or with the
456 456 %automagic function), you don't need to type in the % explicitly. By default,
457 457 IPython ships with automagic on, so you should only rarely need the % escape.
458 458
459 459 Example: typing '%cd mydir' (without the quotes) changes you working directory
460 460 to 'mydir', if it exists.
461 461
462 462 You can define your own magic functions to extend the system. See the supplied
463 463 ipythonrc and example-magic.py files for details (in your ipython
464 464 configuration directory, typically $HOME/.ipython/).
465 465
466 466 You can also define your own aliased names for magic functions. In your
467 467 ipythonrc file, placing a line like:
468 468
469 469 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
470 470
471 471 will define %pf as a new name for %profile.
472 472
473 473 You can also call magics in code using the ipmagic() function, which IPython
474 474 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
475 475
476 476 For a list of the available magic functions, use %lsmagic. For a description
477 477 of any of them, type %magic_name?, e.g. '%cd?'.
478 478
479 479 Currently the magic system has the following functions:\n"""
480 480
481 481 mesc = self.shell.ESC_MAGIC
482 482 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
483 483 "\n\n%s%s\n\n%s" % (outmsg,
484 484 magic_docs,mesc,mesc,
485 485 (' '+mesc).join(self.lsmagic()),
486 486 Magic.auto_status[self.shell.rc.automagic] ) )
487 487
488 488 page(outmsg,screen_lines=self.shell.rc.screen_length)
489 489
490 490
491 491 def magic_autoindent(self, parameter_s = ''):
492 492 """Toggle autoindent on/off (if available)."""
493 493
494 494 self.shell.set_autoindent()
495 495 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
496 496
497 497
498 498 def magic_automagic(self, parameter_s = ''):
499 499 """Make magic functions callable without having to type the initial %.
500 500
501 501 Without argumentsl toggles on/off (when off, you must call it as
502 502 %automagic, of course). With arguments it sets the value, and you can
503 503 use any of (case insensitive):
504 504
505 505 - on,1,True: to activate
506 506
507 507 - off,0,False: to deactivate.
508 508
509 509 Note that magic functions have lowest priority, so if there's a
510 510 variable whose name collides with that of a magic fn, automagic won't
511 511 work for that function (you get the variable instead). However, if you
512 512 delete the variable (del var), the previously shadowed magic function
513 513 becomes visible to automagic again."""
514 514
515 515 rc = self.shell.rc
516 516 arg = parameter_s.lower()
517 517 if parameter_s in ('on','1','true'):
518 518 rc.automagic = True
519 519 elif parameter_s in ('off','0','false'):
520 520 rc.automagic = False
521 521 else:
522 522 rc.automagic = not rc.automagic
523 523 print '\n' + Magic.auto_status[rc.automagic]
524 524
525 525 @testdec.skip_doctest
526 526 def magic_autocall(self, parameter_s = ''):
527 527 """Make functions callable without having to type parentheses.
528 528
529 529 Usage:
530 530
531 531 %autocall [mode]
532 532
533 533 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
534 534 value is toggled on and off (remembering the previous state).
535 535
536 536 In more detail, these values mean:
537 537
538 538 0 -> fully disabled
539 539
540 540 1 -> active, but do not apply if there are no arguments on the line.
541 541
542 542 In this mode, you get:
543 543
544 544 In [1]: callable
545 545 Out[1]: <built-in function callable>
546 546
547 547 In [2]: callable 'hello'
548 548 ------> callable('hello')
549 549 Out[2]: False
550 550
551 551 2 -> Active always. Even if no arguments are present, the callable
552 552 object is called:
553 553
554 554 In [2]: float
555 555 ------> float()
556 556 Out[2]: 0.0
557 557
558 558 Note that even with autocall off, you can still use '/' at the start of
559 559 a line to treat the first argument on the command line as a function
560 560 and add parentheses to it:
561 561
562 562 In [8]: /str 43
563 563 ------> str(43)
564 564 Out[8]: '43'
565 565
566 566 # all-random (note for auto-testing)
567 567 """
568 568
569 569 rc = self.shell.rc
570 570
571 571 if parameter_s:
572 572 arg = int(parameter_s)
573 573 else:
574 574 arg = 'toggle'
575 575
576 576 if not arg in (0,1,2,'toggle'):
577 577 error('Valid modes: (0->Off, 1->Smart, 2->Full')
578 578 return
579 579
580 580 if arg in (0,1,2):
581 581 rc.autocall = arg
582 582 else: # toggle
583 583 if rc.autocall:
584 584 self._magic_state.autocall_save = rc.autocall
585 585 rc.autocall = 0
586 586 else:
587 587 try:
588 588 rc.autocall = self._magic_state.autocall_save
589 589 except AttributeError:
590 590 rc.autocall = self._magic_state.autocall_save = 1
591 591
592 592 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
593 593
594 594 def magic_system_verbose(self, parameter_s = ''):
595 595 """Set verbose printing of system calls.
596 596
597 597 If called without an argument, act as a toggle"""
598 598
599 599 if parameter_s:
600 600 val = bool(eval(parameter_s))
601 601 else:
602 602 val = None
603 603
604 604 self.shell.rc_set_toggle('system_verbose',val)
605 605 print "System verbose printing is:",\
606 606 ['OFF','ON'][self.shell.rc.system_verbose]
607 607
608 608
609 609 def magic_page(self, parameter_s=''):
610 610 """Pretty print the object and display it through a pager.
611 611
612 612 %page [options] OBJECT
613 613
614 614 If no object is given, use _ (last output).
615 615
616 616 Options:
617 617
618 618 -r: page str(object), don't pretty-print it."""
619 619
620 620 # After a function contributed by Olivier Aubert, slightly modified.
621 621
622 622 # Process options/args
623 623 opts,args = self.parse_options(parameter_s,'r')
624 624 raw = 'r' in opts
625 625
626 626 oname = args and args or '_'
627 627 info = self._ofind(oname)
628 628 if info['found']:
629 629 txt = (raw and str or pformat)( info['obj'] )
630 630 page(txt)
631 631 else:
632 632 print 'Object `%s` not found' % oname
633 633
634 634 def magic_profile(self, parameter_s=''):
635 635 """Print your currently active IPyhton profile."""
636 636 if self.shell.rc.profile:
637 637 printpl('Current IPython profile: $self.shell.rc.profile.')
638 638 else:
639 639 print 'No profile active.'
640 640
641 641 def magic_pinfo(self, parameter_s='', namespaces=None):
642 642 """Provide detailed information about an object.
643 643
644 644 '%pinfo object' is just a synonym for object? or ?object."""
645 645
646 646 #print 'pinfo par: <%s>' % parameter_s # dbg
647 647
648 648
649 649 # detail_level: 0 -> obj? , 1 -> obj??
650 650 detail_level = 0
651 651 # We need to detect if we got called as 'pinfo pinfo foo', which can
652 652 # happen if the user types 'pinfo foo?' at the cmd line.
653 653 pinfo,qmark1,oname,qmark2 = \
654 654 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
655 655 if pinfo or qmark1 or qmark2:
656 656 detail_level = 1
657 657 if "*" in oname:
658 658 self.magic_psearch(oname)
659 659 else:
660 660 self._inspect('pinfo', oname, detail_level=detail_level,
661 661 namespaces=namespaces)
662 662
663 663 def magic_pdef(self, parameter_s='', namespaces=None):
664 664 """Print the definition header for any callable object.
665 665
666 666 If the object is a class, print the constructor information."""
667 667 self._inspect('pdef',parameter_s, namespaces)
668 668
669 669 def magic_pdoc(self, parameter_s='', namespaces=None):
670 670 """Print the docstring for an object.
671 671
672 672 If the given object is a class, it will print both the class and the
673 673 constructor docstrings."""
674 674 self._inspect('pdoc',parameter_s, namespaces)
675 675
676 676 def magic_psource(self, parameter_s='', namespaces=None):
677 677 """Print (or run through pager) the source code for an object."""
678 678 self._inspect('psource',parameter_s, namespaces)
679 679
680 680 def magic_pfile(self, parameter_s=''):
681 681 """Print (or run through pager) the file where an object is defined.
682 682
683 683 The file opens at the line where the object definition begins. IPython
684 684 will honor the environment variable PAGER if set, and otherwise will
685 685 do its best to print the file in a convenient form.
686 686
687 687 If the given argument is not an object currently defined, IPython will
688 688 try to interpret it as a filename (automatically adding a .py extension
689 689 if needed). You can thus use %pfile as a syntax highlighting code
690 690 viewer."""
691 691
692 692 # first interpret argument as an object name
693 693 out = self._inspect('pfile',parameter_s)
694 694 # if not, try the input as a filename
695 695 if out == 'not found':
696 696 try:
697 697 filename = get_py_filename(parameter_s)
698 698 except IOError,msg:
699 699 print msg
700 700 return
701 701 page(self.shell.inspector.format(file(filename).read()))
702 702
703 703 def _inspect(self,meth,oname,namespaces=None,**kw):
704 704 """Generic interface to the inspector system.
705 705
706 706 This function is meant to be called by pdef, pdoc & friends."""
707 707
708 708 #oname = oname.strip()
709 709 #print '1- oname: <%r>' % oname # dbg
710 710 try:
711 711 oname = oname.strip().encode('ascii')
712 712 #print '2- oname: <%r>' % oname # dbg
713 713 except UnicodeEncodeError:
714 714 print 'Python identifiers can only contain ascii characters.'
715 715 return 'not found'
716 716
717 717 info = Struct(self._ofind(oname, namespaces))
718 718
719 719 if info.found:
720 720 try:
721 721 IPython.generics.inspect_object(info.obj)
722 722 return
723 723 except IPython.ipapi.TryNext:
724 724 pass
725 725 # Get the docstring of the class property if it exists.
726 726 path = oname.split('.')
727 727 root = '.'.join(path[:-1])
728 728 if info.parent is not None:
729 729 try:
730 730 target = getattr(info.parent, '__class__')
731 731 # The object belongs to a class instance.
732 732 try:
733 733 target = getattr(target, path[-1])
734 734 # The class defines the object.
735 735 if isinstance(target, property):
736 736 oname = root + '.__class__.' + path[-1]
737 737 info = Struct(self._ofind(oname))
738 738 except AttributeError: pass
739 739 except AttributeError: pass
740 740
741 741 pmethod = getattr(self.shell.inspector,meth)
742 742 formatter = info.ismagic and self.format_screen or None
743 743 if meth == 'pdoc':
744 744 pmethod(info.obj,oname,formatter)
745 745 elif meth == 'pinfo':
746 746 pmethod(info.obj,oname,formatter,info,**kw)
747 747 else:
748 748 pmethod(info.obj,oname)
749 749 else:
750 750 print 'Object `%s` not found.' % oname
751 751 return 'not found' # so callers can take other action
752 752
753 753 def magic_psearch(self, parameter_s=''):
754 754 """Search for object in namespaces by wildcard.
755 755
756 756 %psearch [options] PATTERN [OBJECT TYPE]
757 757
758 758 Note: ? can be used as a synonym for %psearch, at the beginning or at
759 759 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
760 760 rest of the command line must be unchanged (options come first), so
761 761 for example the following forms are equivalent
762 762
763 763 %psearch -i a* function
764 764 -i a* function?
765 765 ?-i a* function
766 766
767 767 Arguments:
768 768
769 769 PATTERN
770 770
771 771 where PATTERN is a string containing * as a wildcard similar to its
772 772 use in a shell. The pattern is matched in all namespaces on the
773 773 search path. By default objects starting with a single _ are not
774 774 matched, many IPython generated objects have a single
775 775 underscore. The default is case insensitive matching. Matching is
776 776 also done on the attributes of objects and not only on the objects
777 777 in a module.
778 778
779 779 [OBJECT TYPE]
780 780
781 781 Is the name of a python type from the types module. The name is
782 782 given in lowercase without the ending type, ex. StringType is
783 783 written string. By adding a type here only objects matching the
784 784 given type are matched. Using all here makes the pattern match all
785 785 types (this is the default).
786 786
787 787 Options:
788 788
789 789 -a: makes the pattern match even objects whose names start with a
790 790 single underscore. These names are normally ommitted from the
791 791 search.
792 792
793 793 -i/-c: make the pattern case insensitive/sensitive. If neither of
794 794 these options is given, the default is read from your ipythonrc
795 795 file. The option name which sets this value is
796 796 'wildcards_case_sensitive'. If this option is not specified in your
797 797 ipythonrc file, IPython's internal default is to do a case sensitive
798 798 search.
799 799
800 800 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
801 801 specifiy can be searched in any of the following namespaces:
802 802 'builtin', 'user', 'user_global','internal', 'alias', where
803 803 'builtin' and 'user' are the search defaults. Note that you should
804 804 not use quotes when specifying namespaces.
805 805
806 806 'Builtin' contains the python module builtin, 'user' contains all
807 807 user data, 'alias' only contain the shell aliases and no python
808 808 objects, 'internal' contains objects used by IPython. The
809 809 'user_global' namespace is only used by embedded IPython instances,
810 810 and it contains module-level globals. You can add namespaces to the
811 811 search with -s or exclude them with -e (these options can be given
812 812 more than once).
813 813
814 814 Examples:
815 815
816 816 %psearch a* -> objects beginning with an a
817 817 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
818 818 %psearch a* function -> all functions beginning with an a
819 819 %psearch re.e* -> objects beginning with an e in module re
820 820 %psearch r*.e* -> objects that start with e in modules starting in r
821 821 %psearch r*.* string -> all strings in modules beginning with r
822 822
823 823 Case sensitve search:
824 824
825 825 %psearch -c a* list all object beginning with lower case a
826 826
827 827 Show objects beginning with a single _:
828 828
829 829 %psearch -a _* list objects beginning with a single underscore"""
830 830 try:
831 831 parameter_s = parameter_s.encode('ascii')
832 832 except UnicodeEncodeError:
833 833 print 'Python identifiers can only contain ascii characters.'
834 834 return
835 835
836 836 # default namespaces to be searched
837 837 def_search = ['user','builtin']
838 838
839 839 # Process options/args
840 840 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
841 841 opt = opts.get
842 842 shell = self.shell
843 843 psearch = shell.inspector.psearch
844 844
845 845 # select case options
846 846 if opts.has_key('i'):
847 847 ignore_case = True
848 848 elif opts.has_key('c'):
849 849 ignore_case = False
850 850 else:
851 851 ignore_case = not shell.rc.wildcards_case_sensitive
852 852
853 853 # Build list of namespaces to search from user options
854 854 def_search.extend(opt('s',[]))
855 855 ns_exclude = ns_exclude=opt('e',[])
856 856 ns_search = [nm for nm in def_search if nm not in ns_exclude]
857 857
858 858 # Call the actual search
859 859 try:
860 860 psearch(args,shell.ns_table,ns_search,
861 861 show_all=opt('a'),ignore_case=ignore_case)
862 862 except:
863 863 shell.showtraceback()
864 864
865 865 def magic_who_ls(self, parameter_s=''):
866 866 """Return a sorted list of all interactive variables.
867 867
868 868 If arguments are given, only variables of types matching these
869 869 arguments are returned."""
870 870
871 871 user_ns = self.shell.user_ns
872 872 internal_ns = self.shell.internal_ns
873 873 user_config_ns = self.shell.user_config_ns
874 874 out = []
875 875 typelist = parameter_s.split()
876 876
877 877 for i in user_ns:
878 878 if not (i.startswith('_') or i.startswith('_i')) \
879 879 and not (i in internal_ns or i in user_config_ns):
880 880 if typelist:
881 881 if type(user_ns[i]).__name__ in typelist:
882 882 out.append(i)
883 883 else:
884 884 out.append(i)
885 885 out.sort()
886 886 return out
887 887
888 888 def magic_who(self, parameter_s=''):
889 889 """Print all interactive variables, with some minimal formatting.
890 890
891 891 If any arguments are given, only variables whose type matches one of
892 892 these are printed. For example:
893 893
894 894 %who function str
895 895
896 896 will only list functions and strings, excluding all other types of
897 897 variables. To find the proper type names, simply use type(var) at a
898 898 command line to see how python prints type names. For example:
899 899
900 900 In [1]: type('hello')\\
901 901 Out[1]: <type 'str'>
902 902
903 903 indicates that the type name for strings is 'str'.
904 904
905 905 %who always excludes executed names loaded through your configuration
906 906 file and things which are internal to IPython.
907 907
908 908 This is deliberate, as typically you may load many modules and the
909 909 purpose of %who is to show you only what you've manually defined."""
910 910
911 911 varlist = self.magic_who_ls(parameter_s)
912 912 if not varlist:
913 913 if parameter_s:
914 914 print 'No variables match your requested type.'
915 915 else:
916 916 print 'Interactive namespace is empty.'
917 917 return
918 918
919 919 # if we have variables, move on...
920 920 count = 0
921 921 for i in varlist:
922 922 print i+'\t',
923 923 count += 1
924 924 if count > 8:
925 925 count = 0
926 926 print
927 927 print
928 928
929 929 def magic_whos(self, parameter_s=''):
930 930 """Like %who, but gives some extra information about each variable.
931 931
932 932 The same type filtering of %who can be applied here.
933 933
934 934 For all variables, the type is printed. Additionally it prints:
935 935
936 936 - For {},[],(): their length.
937 937
938 938 - For numpy and Numeric arrays, a summary with shape, number of
939 939 elements, typecode and size in memory.
940 940
941 941 - Everything else: a string representation, snipping their middle if
942 942 too long."""
943 943
944 944 varnames = self.magic_who_ls(parameter_s)
945 945 if not varnames:
946 946 if parameter_s:
947 947 print 'No variables match your requested type.'
948 948 else:
949 949 print 'Interactive namespace is empty.'
950 950 return
951 951
952 952 # if we have variables, move on...
953 953
954 954 # for these types, show len() instead of data:
955 955 seq_types = [types.DictType,types.ListType,types.TupleType]
956 956
957 957 # for numpy/Numeric arrays, display summary info
958 958 try:
959 959 import numpy
960 960 except ImportError:
961 961 ndarray_type = None
962 962 else:
963 963 ndarray_type = numpy.ndarray.__name__
964 964 try:
965 965 import Numeric
966 966 except ImportError:
967 967 array_type = None
968 968 else:
969 969 array_type = Numeric.ArrayType.__name__
970 970
971 971 # Find all variable names and types so we can figure out column sizes
972 972 def get_vars(i):
973 973 return self.shell.user_ns[i]
974 974
975 975 # some types are well known and can be shorter
976 976 abbrevs = {'IPython.macro.Macro' : 'Macro'}
977 977 def type_name(v):
978 978 tn = type(v).__name__
979 979 return abbrevs.get(tn,tn)
980 980
981 981 varlist = map(get_vars,varnames)
982 982
983 983 typelist = []
984 984 for vv in varlist:
985 985 tt = type_name(vv)
986 986
987 987 if tt=='instance':
988 988 typelist.append( abbrevs.get(str(vv.__class__),
989 989 str(vv.__class__)))
990 990 else:
991 991 typelist.append(tt)
992 992
993 993 # column labels and # of spaces as separator
994 994 varlabel = 'Variable'
995 995 typelabel = 'Type'
996 996 datalabel = 'Data/Info'
997 997 colsep = 3
998 998 # variable format strings
999 999 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1000 1000 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1001 1001 aformat = "%s: %s elems, type `%s`, %s bytes"
1002 1002 # find the size of the columns to format the output nicely
1003 1003 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1004 1004 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1005 1005 # table header
1006 1006 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1007 1007 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1008 1008 # and the table itself
1009 1009 kb = 1024
1010 1010 Mb = 1048576 # kb**2
1011 1011 for vname,var,vtype in zip(varnames,varlist,typelist):
1012 1012 print itpl(vformat),
1013 1013 if vtype in seq_types:
1014 1014 print len(var)
1015 1015 elif vtype in [array_type,ndarray_type]:
1016 1016 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1017 1017 if vtype==ndarray_type:
1018 1018 # numpy
1019 1019 vsize = var.size
1020 1020 vbytes = vsize*var.itemsize
1021 1021 vdtype = var.dtype
1022 1022 else:
1023 1023 # Numeric
1024 1024 vsize = Numeric.size(var)
1025 1025 vbytes = vsize*var.itemsize()
1026 1026 vdtype = var.typecode()
1027 1027
1028 1028 if vbytes < 100000:
1029 1029 print aformat % (vshape,vsize,vdtype,vbytes)
1030 1030 else:
1031 1031 print aformat % (vshape,vsize,vdtype,vbytes),
1032 1032 if vbytes < Mb:
1033 1033 print '(%s kb)' % (vbytes/kb,)
1034 1034 else:
1035 1035 print '(%s Mb)' % (vbytes/Mb,)
1036 1036 else:
1037 1037 try:
1038 1038 vstr = str(var)
1039 1039 except UnicodeEncodeError:
1040 1040 vstr = unicode(var).encode(sys.getdefaultencoding(),
1041 1041 'backslashreplace')
1042 1042 vstr = vstr.replace('\n','\\n')
1043 1043 if len(vstr) < 50:
1044 1044 print vstr
1045 1045 else:
1046 1046 printpl(vfmt_short)
1047 1047
1048 1048 def magic_reset(self, parameter_s=''):
1049 1049 """Resets the namespace by removing all names defined by the user.
1050 1050
1051 1051 Input/Output history are left around in case you need them.
1052 1052
1053 1053 Parameters
1054 1054 ----------
1055 1055 -y : force reset without asking for confirmation.
1056 1056
1057 1057 Examples
1058 1058 --------
1059 1059 In [6]: a = 1
1060 1060
1061 1061 In [7]: a
1062 1062 Out[7]: 1
1063 1063
1064 1064 In [8]: 'a' in _ip.user_ns
1065 1065 Out[8]: True
1066 1066
1067 1067 In [9]: %reset -f
1068 1068
1069 1069 In [10]: 'a' in _ip.user_ns
1070 1070 Out[10]: False
1071 1071 """
1072 1072
1073 1073 if parameter_s == '-f':
1074 1074 ans = True
1075 1075 else:
1076 1076 ans = self.shell.ask_yes_no(
1077 1077 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1078 1078 if not ans:
1079 1079 print 'Nothing done.'
1080 1080 return
1081 1081 user_ns = self.shell.user_ns
1082 1082 for i in self.magic_who_ls():
1083 1083 del(user_ns[i])
1084 1084
1085 1085 # Also flush the private list of module references kept for script
1086 1086 # execution protection
1087 1087 self.shell.clear_main_mod_cache()
1088 1088
1089 1089 def magic_logstart(self,parameter_s=''):
1090 1090 """Start logging anywhere in a session.
1091 1091
1092 1092 %logstart [-o|-r|-t] [log_name [log_mode]]
1093 1093
1094 1094 If no name is given, it defaults to a file named 'ipython_log.py' in your
1095 1095 current directory, in 'rotate' mode (see below).
1096 1096
1097 1097 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1098 1098 history up to that point and then continues logging.
1099 1099
1100 1100 %logstart takes a second optional parameter: logging mode. This can be one
1101 1101 of (note that the modes are given unquoted):\\
1102 1102 append: well, that says it.\\
1103 1103 backup: rename (if exists) to name~ and start name.\\
1104 1104 global: single logfile in your home dir, appended to.\\
1105 1105 over : overwrite existing log.\\
1106 1106 rotate: create rotating logs name.1~, name.2~, etc.
1107 1107
1108 1108 Options:
1109 1109
1110 1110 -o: log also IPython's output. In this mode, all commands which
1111 1111 generate an Out[NN] prompt are recorded to the logfile, right after
1112 1112 their corresponding input line. The output lines are always
1113 1113 prepended with a '#[Out]# ' marker, so that the log remains valid
1114 1114 Python code.
1115 1115
1116 1116 Since this marker is always the same, filtering only the output from
1117 1117 a log is very easy, using for example a simple awk call:
1118 1118
1119 1119 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1120 1120
1121 1121 -r: log 'raw' input. Normally, IPython's logs contain the processed
1122 1122 input, so that user lines are logged in their final form, converted
1123 1123 into valid Python. For example, %Exit is logged as
1124 1124 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1125 1125 exactly as typed, with no transformations applied.
1126 1126
1127 1127 -t: put timestamps before each input line logged (these are put in
1128 1128 comments)."""
1129 1129
1130 1130 opts,par = self.parse_options(parameter_s,'ort')
1131 1131 log_output = 'o' in opts
1132 1132 log_raw_input = 'r' in opts
1133 1133 timestamp = 't' in opts
1134 1134
1135 1135 rc = self.shell.rc
1136 1136 logger = self.shell.logger
1137 1137
1138 1138 # if no args are given, the defaults set in the logger constructor by
1139 1139 # ipytohn remain valid
1140 1140 if par:
1141 1141 try:
1142 1142 logfname,logmode = par.split()
1143 1143 except:
1144 1144 logfname = par
1145 1145 logmode = 'backup'
1146 1146 else:
1147 1147 logfname = logger.logfname
1148 1148 logmode = logger.logmode
1149 1149 # put logfname into rc struct as if it had been called on the command
1150 1150 # line, so it ends up saved in the log header Save it in case we need
1151 1151 # to restore it...
1152 1152 old_logfile = rc.opts.get('logfile','')
1153 1153 if logfname:
1154 1154 logfname = os.path.expanduser(logfname)
1155 1155 rc.opts.logfile = logfname
1156 1156 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1157 1157 try:
1158 1158 started = logger.logstart(logfname,loghead,logmode,
1159 1159 log_output,timestamp,log_raw_input)
1160 1160 except:
1161 1161 rc.opts.logfile = old_logfile
1162 1162 warn("Couldn't start log: %s" % sys.exc_info()[1])
1163 1163 else:
1164 1164 # log input history up to this point, optionally interleaving
1165 1165 # output if requested
1166 1166
1167 1167 if timestamp:
1168 1168 # disable timestamping for the previous history, since we've
1169 1169 # lost those already (no time machine here).
1170 1170 logger.timestamp = False
1171 1171
1172 1172 if log_raw_input:
1173 1173 input_hist = self.shell.input_hist_raw
1174 1174 else:
1175 1175 input_hist = self.shell.input_hist
1176 1176
1177 1177 if log_output:
1178 1178 log_write = logger.log_write
1179 1179 output_hist = self.shell.output_hist
1180 1180 for n in range(1,len(input_hist)-1):
1181 1181 log_write(input_hist[n].rstrip())
1182 1182 if n in output_hist:
1183 1183 log_write(repr(output_hist[n]),'output')
1184 1184 else:
1185 1185 logger.log_write(input_hist[1:])
1186 1186 if timestamp:
1187 1187 # re-enable timestamping
1188 1188 logger.timestamp = True
1189 1189
1190 1190 print ('Activating auto-logging. '
1191 1191 'Current session state plus future input saved.')
1192 1192 logger.logstate()
1193 1193
1194 1194 def magic_logstop(self,parameter_s=''):
1195 1195 """Fully stop logging and close log file.
1196 1196
1197 1197 In order to start logging again, a new %logstart call needs to be made,
1198 1198 possibly (though not necessarily) with a new filename, mode and other
1199 1199 options."""
1200 1200 self.logger.logstop()
1201 1201
1202 1202 def magic_logoff(self,parameter_s=''):
1203 1203 """Temporarily stop logging.
1204 1204
1205 1205 You must have previously started logging."""
1206 1206 self.shell.logger.switch_log(0)
1207 1207
1208 1208 def magic_logon(self,parameter_s=''):
1209 1209 """Restart logging.
1210 1210
1211 1211 This function is for restarting logging which you've temporarily
1212 1212 stopped with %logoff. For starting logging for the first time, you
1213 1213 must use the %logstart function, which allows you to specify an
1214 1214 optional log filename."""
1215 1215
1216 1216 self.shell.logger.switch_log(1)
1217 1217
1218 1218 def magic_logstate(self,parameter_s=''):
1219 1219 """Print the status of the logging system."""
1220 1220
1221 1221 self.shell.logger.logstate()
1222 1222
1223 1223 def magic_pdb(self, parameter_s=''):
1224 1224 """Control the automatic calling of the pdb interactive debugger.
1225 1225
1226 1226 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1227 1227 argument it works as a toggle.
1228 1228
1229 1229 When an exception is triggered, IPython can optionally call the
1230 1230 interactive pdb debugger after the traceback printout. %pdb toggles
1231 1231 this feature on and off.
1232 1232
1233 1233 The initial state of this feature is set in your ipythonrc
1234 1234 configuration file (the variable is called 'pdb').
1235 1235
1236 1236 If you want to just activate the debugger AFTER an exception has fired,
1237 1237 without having to type '%pdb on' and rerunning your code, you can use
1238 1238 the %debug magic."""
1239 1239
1240 1240 par = parameter_s.strip().lower()
1241 1241
1242 1242 if par:
1243 1243 try:
1244 1244 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1245 1245 except KeyError:
1246 1246 print ('Incorrect argument. Use on/1, off/0, '
1247 1247 'or nothing for a toggle.')
1248 1248 return
1249 1249 else:
1250 1250 # toggle
1251 1251 new_pdb = not self.shell.call_pdb
1252 1252
1253 1253 # set on the shell
1254 1254 self.shell.call_pdb = new_pdb
1255 1255 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1256 1256
1257 1257 def magic_debug(self, parameter_s=''):
1258 1258 """Activate the interactive debugger in post-mortem mode.
1259 1259
1260 1260 If an exception has just occurred, this lets you inspect its stack
1261 1261 frames interactively. Note that this will always work only on the last
1262 1262 traceback that occurred, so you must call this quickly after an
1263 1263 exception that you wish to inspect has fired, because if another one
1264 1264 occurs, it clobbers the previous one.
1265 1265
1266 1266 If you want IPython to automatically do this on every exception, see
1267 1267 the %pdb magic for more details.
1268 1268 """
1269 1269
1270 1270 self.shell.debugger(force=True)
1271 1271
1272 1272 @testdec.skip_doctest
1273 1273 def magic_prun(self, parameter_s ='',user_mode=1,
1274 1274 opts=None,arg_lst=None,prog_ns=None):
1275 1275
1276 1276 """Run a statement through the python code profiler.
1277 1277
1278 1278 Usage:
1279 1279 %prun [options] statement
1280 1280
1281 1281 The given statement (which doesn't require quote marks) is run via the
1282 1282 python profiler in a manner similar to the profile.run() function.
1283 1283 Namespaces are internally managed to work correctly; profile.run
1284 1284 cannot be used in IPython because it makes certain assumptions about
1285 1285 namespaces which do not hold under IPython.
1286 1286
1287 1287 Options:
1288 1288
1289 1289 -l <limit>: you can place restrictions on what or how much of the
1290 1290 profile gets printed. The limit value can be:
1291 1291
1292 1292 * A string: only information for function names containing this string
1293 1293 is printed.
1294 1294
1295 1295 * An integer: only these many lines are printed.
1296 1296
1297 1297 * A float (between 0 and 1): this fraction of the report is printed
1298 1298 (for example, use a limit of 0.4 to see the topmost 40% only).
1299 1299
1300 1300 You can combine several limits with repeated use of the option. For
1301 1301 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1302 1302 information about class constructors.
1303 1303
1304 1304 -r: return the pstats.Stats object generated by the profiling. This
1305 1305 object has all the information about the profile in it, and you can
1306 1306 later use it for further analysis or in other functions.
1307 1307
1308 1308 -s <key>: sort profile by given key. You can provide more than one key
1309 1309 by using the option several times: '-s key1 -s key2 -s key3...'. The
1310 1310 default sorting key is 'time'.
1311 1311
1312 1312 The following is copied verbatim from the profile documentation
1313 1313 referenced below:
1314 1314
1315 1315 When more than one key is provided, additional keys are used as
1316 1316 secondary criteria when the there is equality in all keys selected
1317 1317 before them.
1318 1318
1319 1319 Abbreviations can be used for any key names, as long as the
1320 1320 abbreviation is unambiguous. The following are the keys currently
1321 1321 defined:
1322 1322
1323 1323 Valid Arg Meaning
1324 1324 "calls" call count
1325 1325 "cumulative" cumulative time
1326 1326 "file" file name
1327 1327 "module" file name
1328 1328 "pcalls" primitive call count
1329 1329 "line" line number
1330 1330 "name" function name
1331 1331 "nfl" name/file/line
1332 1332 "stdname" standard name
1333 1333 "time" internal time
1334 1334
1335 1335 Note that all sorts on statistics are in descending order (placing
1336 1336 most time consuming items first), where as name, file, and line number
1337 1337 searches are in ascending order (i.e., alphabetical). The subtle
1338 1338 distinction between "nfl" and "stdname" is that the standard name is a
1339 1339 sort of the name as printed, which means that the embedded line
1340 1340 numbers get compared in an odd way. For example, lines 3, 20, and 40
1341 1341 would (if the file names were the same) appear in the string order
1342 1342 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1343 1343 line numbers. In fact, sort_stats("nfl") is the same as
1344 1344 sort_stats("name", "file", "line").
1345 1345
1346 1346 -T <filename>: save profile results as shown on screen to a text
1347 1347 file. The profile is still shown on screen.
1348 1348
1349 1349 -D <filename>: save (via dump_stats) profile statistics to given
1350 1350 filename. This data is in a format understod by the pstats module, and
1351 1351 is generated by a call to the dump_stats() method of profile
1352 1352 objects. The profile is still shown on screen.
1353 1353
1354 1354 If you want to run complete programs under the profiler's control, use
1355 1355 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1356 1356 contains profiler specific options as described here.
1357 1357
1358 1358 You can read the complete documentation for the profile module with::
1359 1359
1360 1360 In [1]: import profile; profile.help()
1361 1361 """
1362 1362
1363 1363 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1364 1364 # protect user quote marks
1365 1365 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1366 1366
1367 1367 if user_mode: # regular user call
1368 1368 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1369 1369 list_all=1)
1370 1370 namespace = self.shell.user_ns
1371 1371 else: # called to run a program by %run -p
1372 1372 try:
1373 1373 filename = get_py_filename(arg_lst[0])
1374 1374 except IOError,msg:
1375 1375 error(msg)
1376 1376 return
1377 1377
1378 1378 arg_str = 'execfile(filename,prog_ns)'
1379 1379 namespace = locals()
1380 1380
1381 1381 opts.merge(opts_def)
1382 1382
1383 1383 prof = profile.Profile()
1384 1384 try:
1385 1385 prof = prof.runctx(arg_str,namespace,namespace)
1386 1386 sys_exit = ''
1387 1387 except SystemExit:
1388 1388 sys_exit = """*** SystemExit exception caught in code being profiled."""
1389 1389
1390 1390 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1391 1391
1392 1392 lims = opts.l
1393 1393 if lims:
1394 1394 lims = [] # rebuild lims with ints/floats/strings
1395 1395 for lim in opts.l:
1396 1396 try:
1397 1397 lims.append(int(lim))
1398 1398 except ValueError:
1399 1399 try:
1400 1400 lims.append(float(lim))
1401 1401 except ValueError:
1402 1402 lims.append(lim)
1403 1403
1404 1404 # Trap output.
1405 1405 stdout_trap = StringIO()
1406 1406
1407 1407 if hasattr(stats,'stream'):
1408 1408 # In newer versions of python, the stats object has a 'stream'
1409 1409 # attribute to write into.
1410 1410 stats.stream = stdout_trap
1411 1411 stats.print_stats(*lims)
1412 1412 else:
1413 1413 # For older versions, we manually redirect stdout during printing
1414 1414 sys_stdout = sys.stdout
1415 1415 try:
1416 1416 sys.stdout = stdout_trap
1417 1417 stats.print_stats(*lims)
1418 1418 finally:
1419 1419 sys.stdout = sys_stdout
1420 1420
1421 1421 output = stdout_trap.getvalue()
1422 1422 output = output.rstrip()
1423 1423
1424 1424 page(output,screen_lines=self.shell.rc.screen_length)
1425 1425 print sys_exit,
1426 1426
1427 1427 dump_file = opts.D[0]
1428 1428 text_file = opts.T[0]
1429 1429 if dump_file:
1430 1430 prof.dump_stats(dump_file)
1431 1431 print '\n*** Profile stats marshalled to file',\
1432 1432 `dump_file`+'.',sys_exit
1433 1433 if text_file:
1434 1434 pfile = file(text_file,'w')
1435 1435 pfile.write(output)
1436 1436 pfile.close()
1437 1437 print '\n*** Profile printout saved to text file',\
1438 1438 `text_file`+'.',sys_exit
1439 1439
1440 1440 if opts.has_key('r'):
1441 1441 return stats
1442 1442 else:
1443 1443 return None
1444 1444
1445 1445 @testdec.skip_doctest
1446 1446 def magic_run(self, parameter_s ='',runner=None,
1447 1447 file_finder=get_py_filename):
1448 1448 """Run the named file inside IPython as a program.
1449 1449
1450 1450 Usage:\\
1451 1451 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1452 1452
1453 1453 Parameters after the filename are passed as command-line arguments to
1454 1454 the program (put in sys.argv). Then, control returns to IPython's
1455 1455 prompt.
1456 1456
1457 1457 This is similar to running at a system prompt:\\
1458 1458 $ python file args\\
1459 1459 but with the advantage of giving you IPython's tracebacks, and of
1460 1460 loading all variables into your interactive namespace for further use
1461 1461 (unless -p is used, see below).
1462 1462
1463 1463 The file is executed in a namespace initially consisting only of
1464 1464 __name__=='__main__' and sys.argv constructed as indicated. It thus
1465 1465 sees its environment as if it were being run as a stand-alone program
1466 1466 (except for sharing global objects such as previously imported
1467 1467 modules). But after execution, the IPython interactive namespace gets
1468 1468 updated with all variables defined in the program (except for __name__
1469 1469 and sys.argv). This allows for very convenient loading of code for
1470 1470 interactive work, while giving each program a 'clean sheet' to run in.
1471 1471
1472 1472 Options:
1473 1473
1474 1474 -n: __name__ is NOT set to '__main__', but to the running file's name
1475 1475 without extension (as python does under import). This allows running
1476 1476 scripts and reloading the definitions in them without calling code
1477 1477 protected by an ' if __name__ == "__main__" ' clause.
1478 1478
1479 1479 -i: run the file in IPython's namespace instead of an empty one. This
1480 1480 is useful if you are experimenting with code written in a text editor
1481 1481 which depends on variables defined interactively.
1482 1482
1483 1483 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1484 1484 being run. This is particularly useful if IPython is being used to
1485 1485 run unittests, which always exit with a sys.exit() call. In such
1486 1486 cases you are interested in the output of the test results, not in
1487 1487 seeing a traceback of the unittest module.
1488 1488
1489 1489 -t: print timing information at the end of the run. IPython will give
1490 1490 you an estimated CPU time consumption for your script, which under
1491 1491 Unix uses the resource module to avoid the wraparound problems of
1492 1492 time.clock(). Under Unix, an estimate of time spent on system tasks
1493 1493 is also given (for Windows platforms this is reported as 0.0).
1494 1494
1495 1495 If -t is given, an additional -N<N> option can be given, where <N>
1496 1496 must be an integer indicating how many times you want the script to
1497 1497 run. The final timing report will include total and per run results.
1498 1498
1499 1499 For example (testing the script uniq_stable.py):
1500 1500
1501 1501 In [1]: run -t uniq_stable
1502 1502
1503 1503 IPython CPU timings (estimated):\\
1504 1504 User : 0.19597 s.\\
1505 1505 System: 0.0 s.\\
1506 1506
1507 1507 In [2]: run -t -N5 uniq_stable
1508 1508
1509 1509 IPython CPU timings (estimated):\\
1510 1510 Total runs performed: 5\\
1511 1511 Times : Total Per run\\
1512 1512 User : 0.910862 s, 0.1821724 s.\\
1513 1513 System: 0.0 s, 0.0 s.
1514 1514
1515 1515 -d: run your program under the control of pdb, the Python debugger.
1516 1516 This allows you to execute your program step by step, watch variables,
1517 1517 etc. Internally, what IPython does is similar to calling:
1518 1518
1519 1519 pdb.run('execfile("YOURFILENAME")')
1520 1520
1521 1521 with a breakpoint set on line 1 of your file. You can change the line
1522 1522 number for this automatic breakpoint to be <N> by using the -bN option
1523 1523 (where N must be an integer). For example:
1524 1524
1525 1525 %run -d -b40 myscript
1526 1526
1527 1527 will set the first breakpoint at line 40 in myscript.py. Note that
1528 1528 the first breakpoint must be set on a line which actually does
1529 1529 something (not a comment or docstring) for it to stop execution.
1530 1530
1531 1531 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1532 1532 first enter 'c' (without qoutes) to start execution up to the first
1533 1533 breakpoint.
1534 1534
1535 1535 Entering 'help' gives information about the use of the debugger. You
1536 1536 can easily see pdb's full documentation with "import pdb;pdb.help()"
1537 1537 at a prompt.
1538 1538
1539 1539 -p: run program under the control of the Python profiler module (which
1540 1540 prints a detailed report of execution times, function calls, etc).
1541 1541
1542 1542 You can pass other options after -p which affect the behavior of the
1543 1543 profiler itself. See the docs for %prun for details.
1544 1544
1545 1545 In this mode, the program's variables do NOT propagate back to the
1546 1546 IPython interactive namespace (because they remain in the namespace
1547 1547 where the profiler executes them).
1548 1548
1549 1549 Internally this triggers a call to %prun, see its documentation for
1550 1550 details on the options available specifically for profiling.
1551 1551
1552 1552 There is one special usage for which the text above doesn't apply:
1553 1553 if the filename ends with .ipy, the file is run as ipython script,
1554 1554 just as if the commands were written on IPython prompt.
1555 1555 """
1556 1556
1557 1557 # get arguments and set sys.argv for program to be run.
1558 1558 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1559 1559 mode='list',list_all=1)
1560 1560
1561 1561 try:
1562 1562 filename = file_finder(arg_lst[0])
1563 1563 except IndexError:
1564 1564 warn('you must provide at least a filename.')
1565 1565 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1566 1566 return
1567 1567 except IOError,msg:
1568 1568 error(msg)
1569 1569 return
1570 1570
1571 1571 if filename.lower().endswith('.ipy'):
1572 1572 self.api.runlines(open(filename).read())
1573 1573 return
1574 1574
1575 1575 # Control the response to exit() calls made by the script being run
1576 1576 exit_ignore = opts.has_key('e')
1577 1577
1578 1578 # Make sure that the running script gets a proper sys.argv as if it
1579 1579 # were run from a system shell.
1580 1580 save_argv = sys.argv # save it for later restoring
1581 1581 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1582 1582
1583 1583 if opts.has_key('i'):
1584 1584 # Run in user's interactive namespace
1585 1585 prog_ns = self.shell.user_ns
1586 1586 __name__save = self.shell.user_ns['__name__']
1587 1587 prog_ns['__name__'] = '__main__'
1588 1588 main_mod = self.shell.new_main_mod(prog_ns)
1589 1589 else:
1590 1590 # Run in a fresh, empty namespace
1591 1591 if opts.has_key('n'):
1592 1592 name = os.path.splitext(os.path.basename(filename))[0]
1593 1593 else:
1594 1594 name = '__main__'
1595 1595
1596 1596 main_mod = self.shell.new_main_mod()
1597 1597 prog_ns = main_mod.__dict__
1598 1598 prog_ns['__name__'] = name
1599 1599
1600 1600 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1601 1601 # set the __file__ global in the script's namespace
1602 1602 prog_ns['__file__'] = filename
1603 1603
1604 1604 # pickle fix. See iplib for an explanation. But we need to make sure
1605 1605 # that, if we overwrite __main__, we replace it at the end
1606 1606 main_mod_name = prog_ns['__name__']
1607 1607
1608 1608 if main_mod_name == '__main__':
1609 1609 restore_main = sys.modules['__main__']
1610 1610 else:
1611 1611 restore_main = False
1612 1612
1613 1613 # This needs to be undone at the end to prevent holding references to
1614 1614 # every single object ever created.
1615 1615 sys.modules[main_mod_name] = main_mod
1616 1616
1617 1617 stats = None
1618 1618 try:
1619 1619 self.shell.savehist()
1620 1620
1621 1621 if opts.has_key('p'):
1622 1622 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1623 1623 else:
1624 1624 if opts.has_key('d'):
1625 1625 deb = debugger.Pdb(self.shell.rc.colors)
1626 1626 # reset Breakpoint state, which is moronically kept
1627 1627 # in a class
1628 1628 bdb.Breakpoint.next = 1
1629 1629 bdb.Breakpoint.bplist = {}
1630 1630 bdb.Breakpoint.bpbynumber = [None]
1631 1631 # Set an initial breakpoint to stop execution
1632 1632 maxtries = 10
1633 1633 bp = int(opts.get('b',[1])[0])
1634 1634 checkline = deb.checkline(filename,bp)
1635 1635 if not checkline:
1636 1636 for bp in range(bp+1,bp+maxtries+1):
1637 1637 if deb.checkline(filename,bp):
1638 1638 break
1639 1639 else:
1640 1640 msg = ("\nI failed to find a valid line to set "
1641 1641 "a breakpoint\n"
1642 1642 "after trying up to line: %s.\n"
1643 1643 "Please set a valid breakpoint manually "
1644 1644 "with the -b option." % bp)
1645 1645 error(msg)
1646 1646 return
1647 1647 # if we find a good linenumber, set the breakpoint
1648 1648 deb.do_break('%s:%s' % (filename,bp))
1649 1649 # Start file run
1650 1650 print "NOTE: Enter 'c' at the",
1651 1651 print "%s prompt to start your script." % deb.prompt
1652 1652 try:
1653 1653 deb.run('execfile("%s")' % filename,prog_ns)
1654 1654
1655 1655 except:
1656 1656 etype, value, tb = sys.exc_info()
1657 1657 # Skip three frames in the traceback: the %run one,
1658 1658 # one inside bdb.py, and the command-line typed by the
1659 1659 # user (run by exec in pdb itself).
1660 1660 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1661 1661 else:
1662 1662 if runner is None:
1663 1663 runner = self.shell.safe_execfile
1664 1664 if opts.has_key('t'):
1665 1665 # timed execution
1666 1666 try:
1667 1667 nruns = int(opts['N'][0])
1668 1668 if nruns < 1:
1669 1669 error('Number of runs must be >=1')
1670 1670 return
1671 1671 except (KeyError):
1672 1672 nruns = 1
1673 1673 if nruns == 1:
1674 1674 t0 = clock2()
1675 1675 runner(filename,prog_ns,prog_ns,
1676 1676 exit_ignore=exit_ignore)
1677 1677 t1 = clock2()
1678 1678 t_usr = t1[0]-t0[0]
1679 1679 t_sys = t1[1]-t0[1]
1680 1680 print "\nIPython CPU timings (estimated):"
1681 1681 print " User : %10s s." % t_usr
1682 1682 print " System: %10s s." % t_sys
1683 1683 else:
1684 1684 runs = range(nruns)
1685 1685 t0 = clock2()
1686 1686 for nr in runs:
1687 1687 runner(filename,prog_ns,prog_ns,
1688 1688 exit_ignore=exit_ignore)
1689 1689 t1 = clock2()
1690 1690 t_usr = t1[0]-t0[0]
1691 1691 t_sys = t1[1]-t0[1]
1692 1692 print "\nIPython CPU timings (estimated):"
1693 1693 print "Total runs performed:",nruns
1694 1694 print " Times : %10s %10s" % ('Total','Per run')
1695 1695 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1696 1696 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1697 1697
1698 1698 else:
1699 1699 # regular execution
1700 1700 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1701 1701
1702 1702 if opts.has_key('i'):
1703 1703 self.shell.user_ns['__name__'] = __name__save
1704 1704 else:
1705 1705 # The shell MUST hold a reference to prog_ns so after %run
1706 1706 # exits, the python deletion mechanism doesn't zero it out
1707 1707 # (leaving dangling references).
1708 1708 self.shell.cache_main_mod(prog_ns,filename)
1709 1709 # update IPython interactive namespace
1710 1710 del prog_ns['__name__']
1711 1711 self.shell.user_ns.update(prog_ns)
1712 1712 finally:
1713 1713 # It's a bit of a mystery why, but __builtins__ can change from
1714 1714 # being a module to becoming a dict missing some key data after
1715 1715 # %run. As best I can see, this is NOT something IPython is doing
1716 1716 # at all, and similar problems have been reported before:
1717 1717 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1718 1718 # Since this seems to be done by the interpreter itself, the best
1719 1719 # we can do is to at least restore __builtins__ for the user on
1720 1720 # exit.
1721 1721 self.shell.user_ns['__builtins__'] = __builtin__
1722 1722
1723 1723 # Ensure key global structures are restored
1724 1724 sys.argv = save_argv
1725 1725 if restore_main:
1726 1726 sys.modules['__main__'] = restore_main
1727 1727 else:
1728 1728 # Remove from sys.modules the reference to main_mod we'd
1729 1729 # added. Otherwise it will trap references to objects
1730 1730 # contained therein.
1731 1731 del sys.modules[main_mod_name]
1732 1732
1733 1733 self.shell.reloadhist()
1734 1734
1735 1735 return stats
1736 1736
1737 1737 def magic_runlog(self, parameter_s =''):
1738 1738 """Run files as logs.
1739 1739
1740 1740 Usage:\\
1741 1741 %runlog file1 file2 ...
1742 1742
1743 1743 Run the named files (treating them as log files) in sequence inside
1744 1744 the interpreter, and return to the prompt. This is much slower than
1745 1745 %run because each line is executed in a try/except block, but it
1746 1746 allows running files with syntax errors in them.
1747 1747
1748 1748 Normally IPython will guess when a file is one of its own logfiles, so
1749 1749 you can typically use %run even for logs. This shorthand allows you to
1750 1750 force any file to be treated as a log file."""
1751 1751
1752 1752 for f in parameter_s.split():
1753 1753 self.shell.safe_execfile(f,self.shell.user_ns,
1754 1754 self.shell.user_ns,islog=1)
1755 1755
1756 1756 @testdec.skip_doctest
1757 1757 def magic_timeit(self, parameter_s =''):
1758 1758 """Time execution of a Python statement or expression
1759 1759
1760 1760 Usage:\\
1761 1761 %timeit [-n<N> -r<R> [-t|-c]] statement
1762 1762
1763 1763 Time execution of a Python statement or expression using the timeit
1764 1764 module.
1765 1765
1766 1766 Options:
1767 1767 -n<N>: execute the given statement <N> times in a loop. If this value
1768 1768 is not given, a fitting value is chosen.
1769 1769
1770 1770 -r<R>: repeat the loop iteration <R> times and take the best result.
1771 1771 Default: 3
1772 1772
1773 1773 -t: use time.time to measure the time, which is the default on Unix.
1774 1774 This function measures wall time.
1775 1775
1776 1776 -c: use time.clock to measure the time, which is the default on
1777 1777 Windows and measures wall time. On Unix, resource.getrusage is used
1778 1778 instead and returns the CPU user time.
1779 1779
1780 1780 -p<P>: use a precision of <P> digits to display the timing result.
1781 1781 Default: 3
1782 1782
1783 1783
1784 1784 Examples:
1785 1785
1786 1786 In [1]: %timeit pass
1787 1787 10000000 loops, best of 3: 53.3 ns per loop
1788 1788
1789 1789 In [2]: u = None
1790 1790
1791 1791 In [3]: %timeit u is None
1792 1792 10000000 loops, best of 3: 184 ns per loop
1793 1793
1794 1794 In [4]: %timeit -r 4 u == None
1795 1795 1000000 loops, best of 4: 242 ns per loop
1796 1796
1797 1797 In [5]: import time
1798 1798
1799 1799 In [6]: %timeit -n1 time.sleep(2)
1800 1800 1 loops, best of 3: 2 s per loop
1801 1801
1802 1802
1803 1803 The times reported by %timeit will be slightly higher than those
1804 1804 reported by the timeit.py script when variables are accessed. This is
1805 1805 due to the fact that %timeit executes the statement in the namespace
1806 1806 of the shell, compared with timeit.py, which uses a single setup
1807 1807 statement to import function or create variables. Generally, the bias
1808 1808 does not matter as long as results from timeit.py are not mixed with
1809 1809 those from %timeit."""
1810 1810
1811 1811 import timeit
1812 1812 import math
1813 1813
1814 1814 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1815 1815 # certain terminals. Until we figure out a robust way of
1816 1816 # auto-detecting if the terminal can deal with it, use plain 'us' for
1817 1817 # microseconds. I am really NOT happy about disabling the proper
1818 1818 # 'micro' prefix, but crashing is worse... If anyone knows what the
1819 1819 # right solution for this is, I'm all ears...
1820 1820 #
1821 1821 # Note: using
1822 1822 #
1823 1823 # s = u'\xb5'
1824 1824 # s.encode(sys.getdefaultencoding())
1825 1825 #
1826 1826 # is not sufficient, as I've seen terminals where that fails but
1827 1827 # print s
1828 1828 #
1829 1829 # succeeds
1830 1830 #
1831 1831 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1832 1832
1833 1833 #units = [u"s", u"ms",u'\xb5',"ns"]
1834 1834 units = [u"s", u"ms",u'us',"ns"]
1835 1835
1836 1836 scaling = [1, 1e3, 1e6, 1e9]
1837 1837
1838 1838 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1839 1839 posix=False)
1840 1840 if stmt == "":
1841 1841 return
1842 1842 timefunc = timeit.default_timer
1843 1843 number = int(getattr(opts, "n", 0))
1844 1844 repeat = int(getattr(opts, "r", timeit.default_repeat))
1845 1845 precision = int(getattr(opts, "p", 3))
1846 1846 if hasattr(opts, "t"):
1847 1847 timefunc = time.time
1848 1848 if hasattr(opts, "c"):
1849 1849 timefunc = clock
1850 1850
1851 1851 timer = timeit.Timer(timer=timefunc)
1852 1852 # this code has tight coupling to the inner workings of timeit.Timer,
1853 1853 # but is there a better way to achieve that the code stmt has access
1854 1854 # to the shell namespace?
1855 1855
1856 1856 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1857 1857 'setup': "pass"}
1858 1858 # Track compilation time so it can be reported if too long
1859 1859 # Minimum time above which compilation time will be reported
1860 1860 tc_min = 0.1
1861 1861
1862 1862 t0 = clock()
1863 1863 code = compile(src, "<magic-timeit>", "exec")
1864 1864 tc = clock()-t0
1865 1865
1866 1866 ns = {}
1867 1867 exec code in self.shell.user_ns, ns
1868 1868 timer.inner = ns["inner"]
1869 1869
1870 1870 if number == 0:
1871 1871 # determine number so that 0.2 <= total time < 2.0
1872 1872 number = 1
1873 1873 for i in range(1, 10):
1874 1874 if timer.timeit(number) >= 0.2:
1875 1875 break
1876 1876 number *= 10
1877 1877
1878 1878 best = min(timer.repeat(repeat, number)) / number
1879 1879
1880 1880 if best > 0.0:
1881 1881 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1882 1882 else:
1883 1883 order = 3
1884 1884 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1885 1885 precision,
1886 1886 best * scaling[order],
1887 1887 units[order])
1888 1888 if tc > tc_min:
1889 1889 print "Compiler time: %.2f s" % tc
1890 1890
1891 1891 @testdec.skip_doctest
1892 1892 def magic_time(self,parameter_s = ''):
1893 1893 """Time execution of a Python statement or expression.
1894 1894
1895 1895 The CPU and wall clock times are printed, and the value of the
1896 1896 expression (if any) is returned. Note that under Win32, system time
1897 1897 is always reported as 0, since it can not be measured.
1898 1898
1899 1899 This function provides very basic timing functionality. In Python
1900 1900 2.3, the timeit module offers more control and sophistication, so this
1901 1901 could be rewritten to use it (patches welcome).
1902 1902
1903 1903 Some examples:
1904 1904
1905 1905 In [1]: time 2**128
1906 1906 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1907 1907 Wall time: 0.00
1908 1908 Out[1]: 340282366920938463463374607431768211456L
1909 1909
1910 1910 In [2]: n = 1000000
1911 1911
1912 1912 In [3]: time sum(range(n))
1913 1913 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1914 1914 Wall time: 1.37
1915 1915 Out[3]: 499999500000L
1916 1916
1917 1917 In [4]: time print 'hello world'
1918 1918 hello world
1919 1919 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1920 1920 Wall time: 0.00
1921 1921
1922 1922 Note that the time needed by Python to compile the given expression
1923 1923 will be reported if it is more than 0.1s. In this example, the
1924 1924 actual exponentiation is done by Python at compilation time, so while
1925 1925 the expression can take a noticeable amount of time to compute, that
1926 1926 time is purely due to the compilation:
1927 1927
1928 1928 In [5]: time 3**9999;
1929 1929 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1930 1930 Wall time: 0.00 s
1931 1931
1932 1932 In [6]: time 3**999999;
1933 1933 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1934 1934 Wall time: 0.00 s
1935 1935 Compiler : 0.78 s
1936 1936 """
1937 1937
1938 1938 # fail immediately if the given expression can't be compiled
1939 1939
1940 1940 expr = self.shell.prefilter(parameter_s,False)
1941 1941
1942 1942 # Minimum time above which compilation time will be reported
1943 1943 tc_min = 0.1
1944 1944
1945 1945 try:
1946 1946 mode = 'eval'
1947 1947 t0 = clock()
1948 1948 code = compile(expr,'<timed eval>',mode)
1949 1949 tc = clock()-t0
1950 1950 except SyntaxError:
1951 1951 mode = 'exec'
1952 1952 t0 = clock()
1953 1953 code = compile(expr,'<timed exec>',mode)
1954 1954 tc = clock()-t0
1955 1955 # skew measurement as little as possible
1956 1956 glob = self.shell.user_ns
1957 1957 clk = clock2
1958 1958 wtime = time.time
1959 1959 # time execution
1960 1960 wall_st = wtime()
1961 1961 if mode=='eval':
1962 1962 st = clk()
1963 1963 out = eval(code,glob)
1964 1964 end = clk()
1965 1965 else:
1966 1966 st = clk()
1967 1967 exec code in glob
1968 1968 end = clk()
1969 1969 out = None
1970 1970 wall_end = wtime()
1971 1971 # Compute actual times and report
1972 1972 wall_time = wall_end-wall_st
1973 1973 cpu_user = end[0]-st[0]
1974 1974 cpu_sys = end[1]-st[1]
1975 1975 cpu_tot = cpu_user+cpu_sys
1976 1976 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1977 1977 (cpu_user,cpu_sys,cpu_tot)
1978 1978 print "Wall time: %.2f s" % wall_time
1979 1979 if tc > tc_min:
1980 1980 print "Compiler : %.2f s" % tc
1981 1981 return out
1982 1982
1983 1983 @testdec.skip_doctest
1984 1984 def magic_macro(self,parameter_s = ''):
1985 1985 """Define a set of input lines as a macro for future re-execution.
1986 1986
1987 1987 Usage:\\
1988 1988 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1989 1989
1990 1990 Options:
1991 1991
1992 1992 -r: use 'raw' input. By default, the 'processed' history is used,
1993 1993 so that magics are loaded in their transformed version to valid
1994 1994 Python. If this option is given, the raw input as typed as the
1995 1995 command line is used instead.
1996 1996
1997 1997 This will define a global variable called `name` which is a string
1998 1998 made of joining the slices and lines you specify (n1,n2,... numbers
1999 1999 above) from your input history into a single string. This variable
2000 2000 acts like an automatic function which re-executes those lines as if
2001 2001 you had typed them. You just type 'name' at the prompt and the code
2002 2002 executes.
2003 2003
2004 2004 The notation for indicating number ranges is: n1-n2 means 'use line
2005 2005 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2006 2006 using the lines numbered 5,6 and 7.
2007 2007
2008 2008 Note: as a 'hidden' feature, you can also use traditional python slice
2009 2009 notation, where N:M means numbers N through M-1.
2010 2010
2011 2011 For example, if your history contains (%hist prints it):
2012 2012
2013 2013 44: x=1
2014 2014 45: y=3
2015 2015 46: z=x+y
2016 2016 47: print x
2017 2017 48: a=5
2018 2018 49: print 'x',x,'y',y
2019 2019
2020 2020 you can create a macro with lines 44 through 47 (included) and line 49
2021 2021 called my_macro with:
2022 2022
2023 2023 In [55]: %macro my_macro 44-47 49
2024 2024
2025 2025 Now, typing `my_macro` (without quotes) will re-execute all this code
2026 2026 in one pass.
2027 2027
2028 2028 You don't need to give the line-numbers in order, and any given line
2029 2029 number can appear multiple times. You can assemble macros with any
2030 2030 lines from your input history in any order.
2031 2031
2032 2032 The macro is a simple object which holds its value in an attribute,
2033 2033 but IPython's display system checks for macros and executes them as
2034 2034 code instead of printing them when you type their name.
2035 2035
2036 2036 You can view a macro's contents by explicitly printing it with:
2037 2037
2038 2038 'print macro_name'.
2039 2039
2040 2040 For one-off cases which DON'T contain magic function calls in them you
2041 2041 can obtain similar results by explicitly executing slices from your
2042 2042 input history with:
2043 2043
2044 2044 In [60]: exec In[44:48]+In[49]"""
2045 2045
2046 2046 opts,args = self.parse_options(parameter_s,'r',mode='list')
2047 2047 if not args:
2048 2048 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2049 2049 macs.sort()
2050 2050 return macs
2051 2051 if len(args) == 1:
2052 2052 raise UsageError(
2053 2053 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2054 2054 name,ranges = args[0], args[1:]
2055 2055
2056 2056 #print 'rng',ranges # dbg
2057 2057 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2058 2058 macro = Macro(lines)
2059 2059 self.shell.user_ns.update({name:macro})
2060 2060 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2061 2061 print 'Macro contents:'
2062 2062 print macro,
2063 2063
2064 2064 def magic_save(self,parameter_s = ''):
2065 2065 """Save a set of lines to a given filename.
2066 2066
2067 2067 Usage:\\
2068 2068 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2069 2069
2070 2070 Options:
2071 2071
2072 2072 -r: use 'raw' input. By default, the 'processed' history is used,
2073 2073 so that magics are loaded in their transformed version to valid
2074 2074 Python. If this option is given, the raw input as typed as the
2075 2075 command line is used instead.
2076 2076
2077 2077 This function uses the same syntax as %macro for line extraction, but
2078 2078 instead of creating a macro it saves the resulting string to the
2079 2079 filename you specify.
2080 2080
2081 2081 It adds a '.py' extension to the file if you don't do so yourself, and
2082 2082 it asks for confirmation before overwriting existing files."""
2083 2083
2084 2084 opts,args = self.parse_options(parameter_s,'r',mode='list')
2085 2085 fname,ranges = args[0], args[1:]
2086 2086 if not fname.endswith('.py'):
2087 2087 fname += '.py'
2088 2088 if os.path.isfile(fname):
2089 2089 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2090 2090 if ans.lower() not in ['y','yes']:
2091 2091 print 'Operation cancelled.'
2092 2092 return
2093 2093 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2094 2094 f = file(fname,'w')
2095 2095 f.write(cmds)
2096 2096 f.close()
2097 2097 print 'The following commands were written to file `%s`:' % fname
2098 2098 print cmds
2099 2099
2100 2100 def _edit_macro(self,mname,macro):
2101 2101 """open an editor with the macro data in a file"""
2102 2102 filename = self.shell.mktempfile(macro.value)
2103 2103 self.shell.hooks.editor(filename)
2104 2104
2105 2105 # and make a new macro object, to replace the old one
2106 2106 mfile = open(filename)
2107 2107 mvalue = mfile.read()
2108 2108 mfile.close()
2109 2109 self.shell.user_ns[mname] = Macro(mvalue)
2110 2110
2111 2111 def magic_ed(self,parameter_s=''):
2112 2112 """Alias to %edit."""
2113 2113 return self.magic_edit(parameter_s)
2114 2114
2115 2115 @testdec.skip_doctest
2116 2116 def magic_edit(self,parameter_s='',last_call=['','']):
2117 2117 """Bring up an editor and execute the resulting code.
2118 2118
2119 2119 Usage:
2120 2120 %edit [options] [args]
2121 2121
2122 2122 %edit runs IPython's editor hook. The default version of this hook is
2123 2123 set to call the __IPYTHON__.rc.editor command. This is read from your
2124 2124 environment variable $EDITOR. If this isn't found, it will default to
2125 2125 vi under Linux/Unix and to notepad under Windows. See the end of this
2126 2126 docstring for how to change the editor hook.
2127 2127
2128 2128 You can also set the value of this editor via the command line option
2129 2129 '-editor' or in your ipythonrc file. This is useful if you wish to use
2130 2130 specifically for IPython an editor different from your typical default
2131 2131 (and for Windows users who typically don't set environment variables).
2132 2132
2133 2133 This command allows you to conveniently edit multi-line code right in
2134 2134 your IPython session.
2135 2135
2136 2136 If called without arguments, %edit opens up an empty editor with a
2137 2137 temporary file and will execute the contents of this file when you
2138 2138 close it (don't forget to save it!).
2139 2139
2140 2140
2141 2141 Options:
2142 2142
2143 2143 -n <number>: open the editor at a specified line number. By default,
2144 2144 the IPython editor hook uses the unix syntax 'editor +N filename', but
2145 2145 you can configure this by providing your own modified hook if your
2146 2146 favorite editor supports line-number specifications with a different
2147 2147 syntax.
2148 2148
2149 2149 -p: this will call the editor with the same data as the previous time
2150 2150 it was used, regardless of how long ago (in your current session) it
2151 2151 was.
2152 2152
2153 2153 -r: use 'raw' input. This option only applies to input taken from the
2154 2154 user's history. By default, the 'processed' history is used, so that
2155 2155 magics are loaded in their transformed version to valid Python. If
2156 2156 this option is given, the raw input as typed as the command line is
2157 2157 used instead. When you exit the editor, it will be executed by
2158 2158 IPython's own processor.
2159 2159
2160 2160 -x: do not execute the edited code immediately upon exit. This is
2161 2161 mainly useful if you are editing programs which need to be called with
2162 2162 command line arguments, which you can then do using %run.
2163 2163
2164 2164
2165 2165 Arguments:
2166 2166
2167 2167 If arguments are given, the following possibilites exist:
2168 2168
2169 2169 - The arguments are numbers or pairs of colon-separated numbers (like
2170 2170 1 4:8 9). These are interpreted as lines of previous input to be
2171 2171 loaded into the editor. The syntax is the same of the %macro command.
2172 2172
2173 2173 - If the argument doesn't start with a number, it is evaluated as a
2174 2174 variable and its contents loaded into the editor. You can thus edit
2175 2175 any string which contains python code (including the result of
2176 2176 previous edits).
2177 2177
2178 2178 - If the argument is the name of an object (other than a string),
2179 2179 IPython will try to locate the file where it was defined and open the
2180 2180 editor at the point where it is defined. You can use `%edit function`
2181 2181 to load an editor exactly at the point where 'function' is defined,
2182 2182 edit it and have the file be executed automatically.
2183 2183
2184 2184 If the object is a macro (see %macro for details), this opens up your
2185 2185 specified editor with a temporary file containing the macro's data.
2186 2186 Upon exit, the macro is reloaded with the contents of the file.
2187 2187
2188 2188 Note: opening at an exact line is only supported under Unix, and some
2189 2189 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2190 2190 '+NUMBER' parameter necessary for this feature. Good editors like
2191 2191 (X)Emacs, vi, jed, pico and joe all do.
2192 2192
2193 2193 - If the argument is not found as a variable, IPython will look for a
2194 2194 file with that name (adding .py if necessary) and load it into the
2195 2195 editor. It will execute its contents with execfile() when you exit,
2196 2196 loading any code in the file into your interactive namespace.
2197 2197
2198 2198 After executing your code, %edit will return as output the code you
2199 2199 typed in the editor (except when it was an existing file). This way
2200 2200 you can reload the code in further invocations of %edit as a variable,
2201 2201 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2202 2202 the output.
2203 2203
2204 2204 Note that %edit is also available through the alias %ed.
2205 2205
2206 2206 This is an example of creating a simple function inside the editor and
2207 2207 then modifying it. First, start up the editor:
2208 2208
2209 2209 In [1]: ed
2210 2210 Editing... done. Executing edited code...
2211 2211 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2212 2212
2213 2213 We can then call the function foo():
2214 2214
2215 2215 In [2]: foo()
2216 2216 foo() was defined in an editing session
2217 2217
2218 2218 Now we edit foo. IPython automatically loads the editor with the
2219 2219 (temporary) file where foo() was previously defined:
2220 2220
2221 2221 In [3]: ed foo
2222 2222 Editing... done. Executing edited code...
2223 2223
2224 2224 And if we call foo() again we get the modified version:
2225 2225
2226 2226 In [4]: foo()
2227 2227 foo() has now been changed!
2228 2228
2229 2229 Here is an example of how to edit a code snippet successive
2230 2230 times. First we call the editor:
2231 2231
2232 2232 In [5]: ed
2233 2233 Editing... done. Executing edited code...
2234 2234 hello
2235 2235 Out[5]: "print 'hello'n"
2236 2236
2237 2237 Now we call it again with the previous output (stored in _):
2238 2238
2239 2239 In [6]: ed _
2240 2240 Editing... done. Executing edited code...
2241 2241 hello world
2242 2242 Out[6]: "print 'hello world'n"
2243 2243
2244 2244 Now we call it with the output #8 (stored in _8, also as Out[8]):
2245 2245
2246 2246 In [7]: ed _8
2247 2247 Editing... done. Executing edited code...
2248 2248 hello again
2249 2249 Out[7]: "print 'hello again'n"
2250 2250
2251 2251
2252 2252 Changing the default editor hook:
2253 2253
2254 2254 If you wish to write your own editor hook, you can put it in a
2255 2255 configuration file which you load at startup time. The default hook
2256 2256 is defined in the IPython.hooks module, and you can use that as a
2257 2257 starting example for further modifications. That file also has
2258 2258 general instructions on how to set a new hook for use once you've
2259 2259 defined it."""
2260 2260
2261 2261 # FIXME: This function has become a convoluted mess. It needs a
2262 2262 # ground-up rewrite with clean, simple logic.
2263 2263
2264 2264 def make_filename(arg):
2265 2265 "Make a filename from the given args"
2266 2266 try:
2267 2267 filename = get_py_filename(arg)
2268 2268 except IOError:
2269 2269 if args.endswith('.py'):
2270 2270 filename = arg
2271 2271 else:
2272 2272 filename = None
2273 2273 return filename
2274 2274
2275 2275 # custom exceptions
2276 2276 class DataIsObject(Exception): pass
2277 2277
2278 2278 opts,args = self.parse_options(parameter_s,'prxn:')
2279 2279 # Set a few locals from the options for convenience:
2280 2280 opts_p = opts.has_key('p')
2281 2281 opts_r = opts.has_key('r')
2282 2282
2283 2283 # Default line number value
2284 2284 lineno = opts.get('n',None)
2285 2285
2286 2286 if opts_p:
2287 2287 args = '_%s' % last_call[0]
2288 2288 if not self.shell.user_ns.has_key(args):
2289 2289 args = last_call[1]
2290 2290
2291 2291 # use last_call to remember the state of the previous call, but don't
2292 2292 # let it be clobbered by successive '-p' calls.
2293 2293 try:
2294 2294 last_call[0] = self.shell.outputcache.prompt_count
2295 2295 if not opts_p:
2296 2296 last_call[1] = parameter_s
2297 2297 except:
2298 2298 pass
2299 2299
2300 2300 # by default this is done with temp files, except when the given
2301 2301 # arg is a filename
2302 2302 use_temp = 1
2303 2303
2304 2304 if re.match(r'\d',args):
2305 2305 # Mode where user specifies ranges of lines, like in %macro.
2306 2306 # This means that you can't edit files whose names begin with
2307 2307 # numbers this way. Tough.
2308 2308 ranges = args.split()
2309 2309 data = ''.join(self.extract_input_slices(ranges,opts_r))
2310 2310 elif args.endswith('.py'):
2311 2311 filename = make_filename(args)
2312 2312 data = ''
2313 2313 use_temp = 0
2314 2314 elif args:
2315 2315 try:
2316 2316 # Load the parameter given as a variable. If not a string,
2317 2317 # process it as an object instead (below)
2318 2318
2319 2319 #print '*** args',args,'type',type(args) # dbg
2320 2320 data = eval(args,self.shell.user_ns)
2321 2321 if not type(data) in StringTypes:
2322 2322 raise DataIsObject
2323 2323
2324 2324 except (NameError,SyntaxError):
2325 2325 # given argument is not a variable, try as a filename
2326 2326 filename = make_filename(args)
2327 2327 if filename is None:
2328 2328 warn("Argument given (%s) can't be found as a variable "
2329 2329 "or as a filename." % args)
2330 2330 return
2331 2331
2332 2332 data = ''
2333 2333 use_temp = 0
2334 2334 except DataIsObject:
2335 2335
2336 2336 # macros have a special edit function
2337 2337 if isinstance(data,Macro):
2338 2338 self._edit_macro(args,data)
2339 2339 return
2340 2340
2341 2341 # For objects, try to edit the file where they are defined
2342 2342 try:
2343 2343 filename = inspect.getabsfile(data)
2344 2344 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2345 2345 # class created by %edit? Try to find source
2346 2346 # by looking for method definitions instead, the
2347 2347 # __module__ in those classes is FakeModule.
2348 2348 attrs = [getattr(data, aname) for aname in dir(data)]
2349 2349 for attr in attrs:
2350 2350 if not inspect.ismethod(attr):
2351 2351 continue
2352 2352 filename = inspect.getabsfile(attr)
2353 2353 if filename and 'fakemodule' not in filename.lower():
2354 2354 # change the attribute to be the edit target instead
2355 2355 data = attr
2356 2356 break
2357 2357
2358 2358 datafile = 1
2359 2359 except TypeError:
2360 2360 filename = make_filename(args)
2361 2361 datafile = 1
2362 2362 warn('Could not find file where `%s` is defined.\n'
2363 2363 'Opening a file named `%s`' % (args,filename))
2364 2364 # Now, make sure we can actually read the source (if it was in
2365 2365 # a temp file it's gone by now).
2366 2366 if datafile:
2367 2367 try:
2368 2368 if lineno is None:
2369 2369 lineno = inspect.getsourcelines(data)[1]
2370 2370 except IOError:
2371 2371 filename = make_filename(args)
2372 2372 if filename is None:
2373 2373 warn('The file `%s` where `%s` was defined cannot '
2374 2374 'be read.' % (filename,data))
2375 2375 return
2376 2376 use_temp = 0
2377 2377 else:
2378 2378 data = ''
2379 2379
2380 2380 if use_temp:
2381 2381 filename = self.shell.mktempfile(data)
2382 2382 print 'IPython will make a temporary file named:',filename
2383 2383
2384 2384 # do actual editing here
2385 2385 print 'Editing...',
2386 2386 sys.stdout.flush()
2387 2387 try:
2388 2388 self.shell.hooks.editor(filename,lineno)
2389 2389 except IPython.ipapi.TryNext:
2390 2390 warn('Could not open editor')
2391 2391 return
2392 2392
2393 2393 # XXX TODO: should this be generalized for all string vars?
2394 2394 # For now, this is special-cased to blocks created by cpaste
2395 2395 if args.strip() == 'pasted_block':
2396 2396 self.shell.user_ns['pasted_block'] = file_read(filename)
2397 2397
2398 2398 if opts.has_key('x'): # -x prevents actual execution
2399 2399 print
2400 2400 else:
2401 2401 print 'done. Executing edited code...'
2402 2402 if opts_r:
2403 2403 self.shell.runlines(file_read(filename))
2404 2404 else:
2405 2405 self.shell.safe_execfile(filename,self.shell.user_ns,
2406 2406 self.shell.user_ns)
2407 2407
2408 2408
2409 2409 if use_temp:
2410 2410 try:
2411 2411 return open(filename).read()
2412 2412 except IOError,msg:
2413 2413 if msg.filename == filename:
2414 2414 warn('File not found. Did you forget to save?')
2415 2415 return
2416 2416 else:
2417 2417 self.shell.showtraceback()
2418 2418
2419 2419 def magic_xmode(self,parameter_s = ''):
2420 2420 """Switch modes for the exception handlers.
2421 2421
2422 2422 Valid modes: Plain, Context and Verbose.
2423 2423
2424 2424 If called without arguments, acts as a toggle."""
2425 2425
2426 2426 def xmode_switch_err(name):
2427 2427 warn('Error changing %s exception modes.\n%s' %
2428 2428 (name,sys.exc_info()[1]))
2429 2429
2430 2430 shell = self.shell
2431 2431 new_mode = parameter_s.strip().capitalize()
2432 2432 try:
2433 2433 shell.InteractiveTB.set_mode(mode=new_mode)
2434 2434 print 'Exception reporting mode:',shell.InteractiveTB.mode
2435 2435 except:
2436 2436 xmode_switch_err('user')
2437 2437
2438 2438 # threaded shells use a special handler in sys.excepthook
2439 2439 if shell.isthreaded:
2440 2440 try:
2441 2441 shell.sys_excepthook.set_mode(mode=new_mode)
2442 2442 except:
2443 2443 xmode_switch_err('threaded')
2444 2444
2445 2445 def magic_colors(self,parameter_s = ''):
2446 2446 """Switch color scheme for prompts, info system and exception handlers.
2447 2447
2448 2448 Currently implemented schemes: NoColor, Linux, LightBG.
2449 2449
2450 2450 Color scheme names are not case-sensitive."""
2451 2451
2452 2452 def color_switch_err(name):
2453 2453 warn('Error changing %s color schemes.\n%s' %
2454 2454 (name,sys.exc_info()[1]))
2455 2455
2456 2456
2457 2457 new_scheme = parameter_s.strip()
2458 2458 if not new_scheme:
2459 2459 raise UsageError(
2460 2460 "%colors: you must specify a color scheme. See '%colors?'")
2461 2461 return
2462 2462 # local shortcut
2463 2463 shell = self.shell
2464 2464
2465 2465 import IPython.rlineimpl as readline
2466 2466
2467 2467 if not readline.have_readline and sys.platform == "win32":
2468 2468 msg = """\
2469 2469 Proper color support under MS Windows requires the pyreadline library.
2470 2470 You can find it at:
2471 2471 http://ipython.scipy.org/moin/PyReadline/Intro
2472 2472 Gary's readline needs the ctypes module, from:
2473 2473 http://starship.python.net/crew/theller/ctypes
2474 2474 (Note that ctypes is already part of Python versions 2.5 and newer).
2475 2475
2476 2476 Defaulting color scheme to 'NoColor'"""
2477 2477 new_scheme = 'NoColor'
2478 2478 warn(msg)
2479 2479
2480 2480 # readline option is 0
2481 2481 if not shell.has_readline:
2482 2482 new_scheme = 'NoColor'
2483 2483
2484 2484 # Set prompt colors
2485 2485 try:
2486 2486 shell.outputcache.set_colors(new_scheme)
2487 2487 except:
2488 2488 color_switch_err('prompt')
2489 2489 else:
2490 2490 shell.rc.colors = \
2491 2491 shell.outputcache.color_table.active_scheme_name
2492 2492 # Set exception colors
2493 2493 try:
2494 2494 shell.InteractiveTB.set_colors(scheme = new_scheme)
2495 2495 shell.SyntaxTB.set_colors(scheme = new_scheme)
2496 2496 except:
2497 2497 color_switch_err('exception')
2498 2498
2499 2499 # threaded shells use a verbose traceback in sys.excepthook
2500 2500 if shell.isthreaded:
2501 2501 try:
2502 2502 shell.sys_excepthook.set_colors(scheme=new_scheme)
2503 2503 except:
2504 2504 color_switch_err('system exception handler')
2505 2505
2506 2506 # Set info (for 'object?') colors
2507 2507 if shell.rc.color_info:
2508 2508 try:
2509 2509 shell.inspector.set_active_scheme(new_scheme)
2510 2510 except:
2511 2511 color_switch_err('object inspector')
2512 2512 else:
2513 2513 shell.inspector.set_active_scheme('NoColor')
2514 2514
2515 2515 def magic_color_info(self,parameter_s = ''):
2516 2516 """Toggle color_info.
2517 2517
2518 2518 The color_info configuration parameter controls whether colors are
2519 2519 used for displaying object details (by things like %psource, %pfile or
2520 2520 the '?' system). This function toggles this value with each call.
2521 2521
2522 2522 Note that unless you have a fairly recent pager (less works better
2523 2523 than more) in your system, using colored object information displays
2524 2524 will not work properly. Test it and see."""
2525 2525
2526 2526 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2527 2527 self.magic_colors(self.shell.rc.colors)
2528 2528 print 'Object introspection functions have now coloring:',
2529 2529 print ['OFF','ON'][self.shell.rc.color_info]
2530 2530
2531 2531 def magic_Pprint(self, parameter_s=''):
2532 2532 """Toggle pretty printing on/off."""
2533 2533
2534 2534 self.shell.rc.pprint = 1 - self.shell.rc.pprint
2535 2535 print 'Pretty printing has been turned', \
2536 2536 ['OFF','ON'][self.shell.rc.pprint]
2537 2537
2538 2538 def magic_exit(self, parameter_s=''):
2539 2539 """Exit IPython, confirming if configured to do so.
2540 2540
2541 2541 You can configure whether IPython asks for confirmation upon exit by
2542 2542 setting the confirm_exit flag in the ipythonrc file."""
2543 2543
2544 2544 self.shell.exit()
2545 2545
2546 2546 def magic_quit(self, parameter_s=''):
2547 2547 """Exit IPython, confirming if configured to do so (like %exit)"""
2548 2548
2549 2549 self.shell.exit()
2550 2550
2551 2551 def magic_Exit(self, parameter_s=''):
2552 2552 """Exit IPython without confirmation."""
2553 2553
2554 2554 self.shell.ask_exit()
2555 2555
2556 2556 #......................................................................
2557 2557 # Functions to implement unix shell-type things
2558 2558
2559 2559 @testdec.skip_doctest
2560 2560 def magic_alias(self, parameter_s = ''):
2561 2561 """Define an alias for a system command.
2562 2562
2563 2563 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2564 2564
2565 2565 Then, typing 'alias_name params' will execute the system command 'cmd
2566 2566 params' (from your underlying operating system).
2567 2567
2568 2568 Aliases have lower precedence than magic functions and Python normal
2569 2569 variables, so if 'foo' is both a Python variable and an alias, the
2570 2570 alias can not be executed until 'del foo' removes the Python variable.
2571 2571
2572 2572 You can use the %l specifier in an alias definition to represent the
2573 2573 whole line when the alias is called. For example:
2574 2574
2575 2575 In [2]: alias all echo "Input in brackets: <%l>"
2576 2576 In [3]: all hello world
2577 2577 Input in brackets: <hello world>
2578 2578
2579 2579 You can also define aliases with parameters using %s specifiers (one
2580 2580 per parameter):
2581 2581
2582 2582 In [1]: alias parts echo first %s second %s
2583 2583 In [2]: %parts A B
2584 2584 first A second B
2585 2585 In [3]: %parts A
2586 2586 Incorrect number of arguments: 2 expected.
2587 2587 parts is an alias to: 'echo first %s second %s'
2588 2588
2589 2589 Note that %l and %s are mutually exclusive. You can only use one or
2590 2590 the other in your aliases.
2591 2591
2592 2592 Aliases expand Python variables just like system calls using ! or !!
2593 2593 do: all expressions prefixed with '$' get expanded. For details of
2594 2594 the semantic rules, see PEP-215:
2595 2595 http://www.python.org/peps/pep-0215.html. This is the library used by
2596 2596 IPython for variable expansion. If you want to access a true shell
2597 2597 variable, an extra $ is necessary to prevent its expansion by IPython:
2598 2598
2599 2599 In [6]: alias show echo
2600 2600 In [7]: PATH='A Python string'
2601 2601 In [8]: show $PATH
2602 2602 A Python string
2603 2603 In [9]: show $$PATH
2604 2604 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2605 2605
2606 2606 You can use the alias facility to acess all of $PATH. See the %rehash
2607 2607 and %rehashx functions, which automatically create aliases for the
2608 2608 contents of your $PATH.
2609 2609
2610 2610 If called with no parameters, %alias prints the current alias table."""
2611 2611
2612 2612 par = parameter_s.strip()
2613 2613 if not par:
2614 2614 stored = self.db.get('stored_aliases', {} )
2615 2615 atab = self.shell.alias_table
2616 2616 aliases = atab.keys()
2617 2617 aliases.sort()
2618 2618 res = []
2619 2619 showlast = []
2620 2620 for alias in aliases:
2621 2621 special = False
2622 2622 try:
2623 2623 tgt = atab[alias][1]
2624 2624 except (TypeError, AttributeError):
2625 2625 # unsubscriptable? probably a callable
2626 2626 tgt = atab[alias]
2627 2627 special = True
2628 2628 # 'interesting' aliases
2629 2629 if (alias in stored or
2630 2630 special or
2631 2631 alias.lower() != os.path.splitext(tgt)[0].lower() or
2632 2632 ' ' in tgt):
2633 2633 showlast.append((alias, tgt))
2634 2634 else:
2635 2635 res.append((alias, tgt ))
2636 2636
2637 2637 # show most interesting aliases last
2638 2638 res.extend(showlast)
2639 2639 print "Total number of aliases:",len(aliases)
2640 2640 return res
2641 2641 try:
2642 2642 alias,cmd = par.split(None,1)
2643 2643 except:
2644 2644 print OInspect.getdoc(self.magic_alias)
2645 2645 else:
2646 2646 nargs = cmd.count('%s')
2647 2647 if nargs>0 and cmd.find('%l')>=0:
2648 2648 error('The %s and %l specifiers are mutually exclusive '
2649 2649 'in alias definitions.')
2650 2650 else: # all looks OK
2651 2651 self.shell.alias_table[alias] = (nargs,cmd)
2652 2652 self.shell.alias_table_validate(verbose=0)
2653 2653 # end magic_alias
2654 2654
2655 2655 def magic_unalias(self, parameter_s = ''):
2656 2656 """Remove an alias"""
2657 2657
2658 2658 aname = parameter_s.strip()
2659 2659 if aname in self.shell.alias_table:
2660 2660 del self.shell.alias_table[aname]
2661 2661 stored = self.db.get('stored_aliases', {} )
2662 2662 if aname in stored:
2663 2663 print "Removing %stored alias",aname
2664 2664 del stored[aname]
2665 2665 self.db['stored_aliases'] = stored
2666 2666
2667 2667
2668 2668 def magic_rehashx(self, parameter_s = ''):
2669 2669 """Update the alias table with all executable files in $PATH.
2670 2670
2671 2671 This version explicitly checks that every entry in $PATH is a file
2672 2672 with execute access (os.X_OK), so it is much slower than %rehash.
2673 2673
2674 2674 Under Windows, it checks executability as a match agains a
2675 2675 '|'-separated string of extensions, stored in the IPython config
2676 2676 variable win_exec_ext. This defaults to 'exe|com|bat'.
2677 2677
2678 2678 This function also resets the root module cache of module completer,
2679 2679 used on slow filesystems.
2680 2680 """
2681 2681
2682 2682
2683 2683 ip = self.api
2684 2684
2685 2685 # for the benefit of module completer in ipy_completers.py
2686 2686 del ip.db['rootmodules']
2687 2687
2688 2688 path = [os.path.abspath(os.path.expanduser(p)) for p in
2689 2689 os.environ.get('PATH','').split(os.pathsep)]
2690 2690 path = filter(os.path.isdir,path)
2691 2691
2692 2692 alias_table = self.shell.alias_table
2693 2693 syscmdlist = []
2694 2694 if os.name == 'posix':
2695 2695 isexec = lambda fname:os.path.isfile(fname) and \
2696 2696 os.access(fname,os.X_OK)
2697 2697 else:
2698 2698
2699 2699 try:
2700 2700 winext = os.environ['pathext'].replace(';','|').replace('.','')
2701 2701 except KeyError:
2702 2702 winext = 'exe|com|bat|py'
2703 2703 if 'py' not in winext:
2704 2704 winext += '|py'
2705 2705 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2706 2706 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2707 2707 savedir = os.getcwd()
2708 2708 try:
2709 2709 # write the whole loop for posix/Windows so we don't have an if in
2710 2710 # the innermost part
2711 2711 if os.name == 'posix':
2712 2712 for pdir in path:
2713 2713 os.chdir(pdir)
2714 2714 for ff in os.listdir(pdir):
2715 2715 if isexec(ff) and ff not in self.shell.no_alias:
2716 2716 # each entry in the alias table must be (N,name),
2717 2717 # where N is the number of positional arguments of the
2718 2718 # alias.
2719 2719 # Dots will be removed from alias names, since ipython
2720 2720 # assumes names with dots to be python code
2721 2721 alias_table[ff.replace('.','')] = (0,ff)
2722 2722 syscmdlist.append(ff)
2723 2723 else:
2724 2724 for pdir in path:
2725 2725 os.chdir(pdir)
2726 2726 for ff in os.listdir(pdir):
2727 2727 base, ext = os.path.splitext(ff)
2728 2728 if isexec(ff) and base.lower() not in self.shell.no_alias:
2729 2729 if ext.lower() == '.exe':
2730 2730 ff = base
2731 2731 alias_table[base.lower().replace('.','')] = (0,ff)
2732 2732 syscmdlist.append(ff)
2733 2733 # Make sure the alias table doesn't contain keywords or builtins
2734 2734 self.shell.alias_table_validate()
2735 2735 # Call again init_auto_alias() so we get 'rm -i' and other
2736 2736 # modified aliases since %rehashx will probably clobber them
2737 2737
2738 2738 # no, we don't want them. if %rehashx clobbers them, good,
2739 2739 # we'll probably get better versions
2740 2740 # self.shell.init_auto_alias()
2741 2741 db = ip.db
2742 2742 db['syscmdlist'] = syscmdlist
2743 2743 finally:
2744 2744 os.chdir(savedir)
2745 2745
2746 2746 def magic_pwd(self, parameter_s = ''):
2747 2747 """Return the current working directory path."""
2748 2748 return os.getcwd()
2749 2749
2750 2750 def magic_cd(self, parameter_s=''):
2751 2751 """Change the current working directory.
2752 2752
2753 2753 This command automatically maintains an internal list of directories
2754 2754 you visit during your IPython session, in the variable _dh. The
2755 2755 command %dhist shows this history nicely formatted. You can also
2756 2756 do 'cd -<tab>' to see directory history conveniently.
2757 2757
2758 2758 Usage:
2759 2759
2760 2760 cd 'dir': changes to directory 'dir'.
2761 2761
2762 2762 cd -: changes to the last visited directory.
2763 2763
2764 2764 cd -<n>: changes to the n-th directory in the directory history.
2765 2765
2766 2766 cd --foo: change to directory that matches 'foo' in history
2767 2767
2768 2768 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2769 2769 (note: cd <bookmark_name> is enough if there is no
2770 2770 directory <bookmark_name>, but a bookmark with the name exists.)
2771 2771 'cd -b <tab>' allows you to tab-complete bookmark names.
2772 2772
2773 2773 Options:
2774 2774
2775 2775 -q: quiet. Do not print the working directory after the cd command is
2776 2776 executed. By default IPython's cd command does print this directory,
2777 2777 since the default prompts do not display path information.
2778 2778
2779 2779 Note that !cd doesn't work for this purpose because the shell where
2780 2780 !command runs is immediately discarded after executing 'command'."""
2781 2781
2782 2782 parameter_s = parameter_s.strip()
2783 2783 #bkms = self.shell.persist.get("bookmarks",{})
2784 2784
2785 2785 oldcwd = os.getcwd()
2786 2786 numcd = re.match(r'(-)(\d+)$',parameter_s)
2787 2787 # jump in directory history by number
2788 2788 if numcd:
2789 2789 nn = int(numcd.group(2))
2790 2790 try:
2791 2791 ps = self.shell.user_ns['_dh'][nn]
2792 2792 except IndexError:
2793 2793 print 'The requested directory does not exist in history.'
2794 2794 return
2795 2795 else:
2796 2796 opts = {}
2797 2797 elif parameter_s.startswith('--'):
2798 2798 ps = None
2799 2799 fallback = None
2800 2800 pat = parameter_s[2:]
2801 2801 dh = self.shell.user_ns['_dh']
2802 2802 # first search only by basename (last component)
2803 2803 for ent in reversed(dh):
2804 2804 if pat in os.path.basename(ent) and os.path.isdir(ent):
2805 2805 ps = ent
2806 2806 break
2807 2807
2808 2808 if fallback is None and pat in ent and os.path.isdir(ent):
2809 2809 fallback = ent
2810 2810
2811 2811 # if we have no last part match, pick the first full path match
2812 2812 if ps is None:
2813 2813 ps = fallback
2814 2814
2815 2815 if ps is None:
2816 2816 print "No matching entry in directory history"
2817 2817 return
2818 2818 else:
2819 2819 opts = {}
2820 2820
2821 2821
2822 2822 else:
2823 2823 #turn all non-space-escaping backslashes to slashes,
2824 2824 # for c:\windows\directory\names\
2825 2825 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2826 2826 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2827 2827 # jump to previous
2828 2828 if ps == '-':
2829 2829 try:
2830 2830 ps = self.shell.user_ns['_dh'][-2]
2831 2831 except IndexError:
2832 2832 raise UsageError('%cd -: No previous directory to change to.')
2833 2833 # jump to bookmark if needed
2834 2834 else:
2835 2835 if not os.path.isdir(ps) or opts.has_key('b'):
2836 2836 bkms = self.db.get('bookmarks', {})
2837 2837
2838 2838 if bkms.has_key(ps):
2839 2839 target = bkms[ps]
2840 2840 print '(bookmark:%s) -> %s' % (ps,target)
2841 2841 ps = target
2842 2842 else:
2843 2843 if opts.has_key('b'):
2844 2844 raise UsageError("Bookmark '%s' not found. "
2845 2845 "Use '%%bookmark -l' to see your bookmarks." % ps)
2846 2846
2847 2847 # at this point ps should point to the target dir
2848 2848 if ps:
2849 2849 try:
2850 2850 os.chdir(os.path.expanduser(ps))
2851 2851 if self.shell.rc.term_title:
2852 2852 #print 'set term title:',self.shell.rc.term_title # dbg
2853 2853 platutils.set_term_title('IPy ' + abbrev_cwd())
2854 2854 except OSError:
2855 2855 print sys.exc_info()[1]
2856 2856 else:
2857 2857 cwd = os.getcwd()
2858 2858 dhist = self.shell.user_ns['_dh']
2859 2859 if oldcwd != cwd:
2860 2860 dhist.append(cwd)
2861 2861 self.db['dhist'] = compress_dhist(dhist)[-100:]
2862 2862
2863 2863 else:
2864 2864 os.chdir(self.shell.home_dir)
2865 2865 if self.shell.rc.term_title:
2866 2866 platutils.set_term_title("IPy ~")
2867 2867 cwd = os.getcwd()
2868 2868 dhist = self.shell.user_ns['_dh']
2869 2869
2870 2870 if oldcwd != cwd:
2871 2871 dhist.append(cwd)
2872 2872 self.db['dhist'] = compress_dhist(dhist)[-100:]
2873 2873 if not 'q' in opts and self.shell.user_ns['_dh']:
2874 2874 print self.shell.user_ns['_dh'][-1]
2875 2875
2876 2876
2877 2877 def magic_env(self, parameter_s=''):
2878 2878 """List environment variables."""
2879 2879
2880 2880 return os.environ.data
2881 2881
2882 2882 def magic_pushd(self, parameter_s=''):
2883 2883 """Place the current dir on stack and change directory.
2884 2884
2885 2885 Usage:\\
2886 2886 %pushd ['dirname']
2887 2887 """
2888 2888
2889 2889 dir_s = self.shell.dir_stack
2890 2890 tgt = os.path.expanduser(parameter_s)
2891 2891 cwd = os.getcwd().replace(self.home_dir,'~')
2892 2892 if tgt:
2893 2893 self.magic_cd(parameter_s)
2894 2894 dir_s.insert(0,cwd)
2895 2895 return self.magic_dirs()
2896 2896
2897 2897 def magic_popd(self, parameter_s=''):
2898 2898 """Change to directory popped off the top of the stack.
2899 2899 """
2900 2900 if not self.shell.dir_stack:
2901 2901 raise UsageError("%popd on empty stack")
2902 2902 top = self.shell.dir_stack.pop(0)
2903 2903 self.magic_cd(top)
2904 2904 print "popd ->",top
2905 2905
2906 2906 def magic_dirs(self, parameter_s=''):
2907 2907 """Return the current directory stack."""
2908 2908
2909 2909 return self.shell.dir_stack
2910 2910
2911 2911 def magic_dhist(self, parameter_s=''):
2912 2912 """Print your history of visited directories.
2913 2913
2914 2914 %dhist -> print full history\\
2915 2915 %dhist n -> print last n entries only\\
2916 2916 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2917 2917
2918 2918 This history is automatically maintained by the %cd command, and
2919 2919 always available as the global list variable _dh. You can use %cd -<n>
2920 2920 to go to directory number <n>.
2921 2921
2922 2922 Note that most of time, you should view directory history by entering
2923 2923 cd -<TAB>.
2924 2924
2925 2925 """
2926 2926
2927 2927 dh = self.shell.user_ns['_dh']
2928 2928 if parameter_s:
2929 2929 try:
2930 2930 args = map(int,parameter_s.split())
2931 2931 except:
2932 2932 self.arg_err(Magic.magic_dhist)
2933 2933 return
2934 2934 if len(args) == 1:
2935 2935 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2936 2936 elif len(args) == 2:
2937 2937 ini,fin = args
2938 2938 else:
2939 2939 self.arg_err(Magic.magic_dhist)
2940 2940 return
2941 2941 else:
2942 2942 ini,fin = 0,len(dh)
2943 2943 nlprint(dh,
2944 2944 header = 'Directory history (kept in _dh)',
2945 2945 start=ini,stop=fin)
2946 2946
2947 2947 @testdec.skip_doctest
2948 2948 def magic_sc(self, parameter_s=''):
2949 2949 """Shell capture - execute a shell command and capture its output.
2950 2950
2951 2951 DEPRECATED. Suboptimal, retained for backwards compatibility.
2952 2952
2953 2953 You should use the form 'var = !command' instead. Example:
2954 2954
2955 2955 "%sc -l myfiles = ls ~" should now be written as
2956 2956
2957 2957 "myfiles = !ls ~"
2958 2958
2959 2959 myfiles.s, myfiles.l and myfiles.n still apply as documented
2960 2960 below.
2961 2961
2962 2962 --
2963 2963 %sc [options] varname=command
2964 2964
2965 2965 IPython will run the given command using commands.getoutput(), and
2966 2966 will then update the user's interactive namespace with a variable
2967 2967 called varname, containing the value of the call. Your command can
2968 2968 contain shell wildcards, pipes, etc.
2969 2969
2970 2970 The '=' sign in the syntax is mandatory, and the variable name you
2971 2971 supply must follow Python's standard conventions for valid names.
2972 2972
2973 2973 (A special format without variable name exists for internal use)
2974 2974
2975 2975 Options:
2976 2976
2977 2977 -l: list output. Split the output on newlines into a list before
2978 2978 assigning it to the given variable. By default the output is stored
2979 2979 as a single string.
2980 2980
2981 2981 -v: verbose. Print the contents of the variable.
2982 2982
2983 2983 In most cases you should not need to split as a list, because the
2984 2984 returned value is a special type of string which can automatically
2985 2985 provide its contents either as a list (split on newlines) or as a
2986 2986 space-separated string. These are convenient, respectively, either
2987 2987 for sequential processing or to be passed to a shell command.
2988 2988
2989 2989 For example:
2990 2990
2991 2991 # all-random
2992 2992
2993 2993 # Capture into variable a
2994 2994 In [1]: sc a=ls *py
2995 2995
2996 2996 # a is a string with embedded newlines
2997 2997 In [2]: a
2998 2998 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2999 2999
3000 3000 # which can be seen as a list:
3001 3001 In [3]: a.l
3002 3002 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3003 3003
3004 3004 # or as a whitespace-separated string:
3005 3005 In [4]: a.s
3006 3006 Out[4]: 'setup.py win32_manual_post_install.py'
3007 3007
3008 3008 # a.s is useful to pass as a single command line:
3009 3009 In [5]: !wc -l $a.s
3010 3010 146 setup.py
3011 3011 130 win32_manual_post_install.py
3012 3012 276 total
3013 3013
3014 3014 # while the list form is useful to loop over:
3015 3015 In [6]: for f in a.l:
3016 3016 ...: !wc -l $f
3017 3017 ...:
3018 3018 146 setup.py
3019 3019 130 win32_manual_post_install.py
3020 3020
3021 3021 Similiarly, the lists returned by the -l option are also special, in
3022 3022 the sense that you can equally invoke the .s attribute on them to
3023 3023 automatically get a whitespace-separated string from their contents:
3024 3024
3025 3025 In [7]: sc -l b=ls *py
3026 3026
3027 3027 In [8]: b
3028 3028 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3029 3029
3030 3030 In [9]: b.s
3031 3031 Out[9]: 'setup.py win32_manual_post_install.py'
3032 3032
3033 3033 In summary, both the lists and strings used for ouptut capture have
3034 3034 the following special attributes:
3035 3035
3036 3036 .l (or .list) : value as list.
3037 3037 .n (or .nlstr): value as newline-separated string.
3038 3038 .s (or .spstr): value as space-separated string.
3039 3039 """
3040 3040
3041 3041 opts,args = self.parse_options(parameter_s,'lv')
3042 3042 # Try to get a variable name and command to run
3043 3043 try:
3044 3044 # the variable name must be obtained from the parse_options
3045 3045 # output, which uses shlex.split to strip options out.
3046 3046 var,_ = args.split('=',1)
3047 3047 var = var.strip()
3048 3048 # But the the command has to be extracted from the original input
3049 3049 # parameter_s, not on what parse_options returns, to avoid the
3050 3050 # quote stripping which shlex.split performs on it.
3051 3051 _,cmd = parameter_s.split('=',1)
3052 3052 except ValueError:
3053 3053 var,cmd = '',''
3054 3054 # If all looks ok, proceed
3055 3055 out,err = self.shell.getoutputerror(cmd)
3056 3056 if err:
3057 3057 print >> Term.cerr,err
3058 3058 if opts.has_key('l'):
3059 3059 out = SList(out.split('\n'))
3060 3060 else:
3061 3061 out = LSString(out)
3062 3062 if opts.has_key('v'):
3063 3063 print '%s ==\n%s' % (var,pformat(out))
3064 3064 if var:
3065 3065 self.shell.user_ns.update({var:out})
3066 3066 else:
3067 3067 return out
3068 3068
3069 3069 def magic_sx(self, parameter_s=''):
3070 3070 """Shell execute - run a shell command and capture its output.
3071 3071
3072 3072 %sx command
3073 3073
3074 3074 IPython will run the given command using commands.getoutput(), and
3075 3075 return the result formatted as a list (split on '\\n'). Since the
3076 3076 output is _returned_, it will be stored in ipython's regular output
3077 3077 cache Out[N] and in the '_N' automatic variables.
3078 3078
3079 3079 Notes:
3080 3080
3081 3081 1) If an input line begins with '!!', then %sx is automatically
3082 3082 invoked. That is, while:
3083 3083 !ls
3084 3084 causes ipython to simply issue system('ls'), typing
3085 3085 !!ls
3086 3086 is a shorthand equivalent to:
3087 3087 %sx ls
3088 3088
3089 3089 2) %sx differs from %sc in that %sx automatically splits into a list,
3090 3090 like '%sc -l'. The reason for this is to make it as easy as possible
3091 3091 to process line-oriented shell output via further python commands.
3092 3092 %sc is meant to provide much finer control, but requires more
3093 3093 typing.
3094 3094
3095 3095 3) Just like %sc -l, this is a list with special attributes:
3096 3096
3097 3097 .l (or .list) : value as list.
3098 3098 .n (or .nlstr): value as newline-separated string.
3099 3099 .s (or .spstr): value as whitespace-separated string.
3100 3100
3101 3101 This is very useful when trying to use such lists as arguments to
3102 3102 system commands."""
3103 3103
3104 3104 if parameter_s:
3105 3105 out,err = self.shell.getoutputerror(parameter_s)
3106 3106 if err:
3107 3107 print >> Term.cerr,err
3108 3108 return SList(out.split('\n'))
3109 3109
3110 3110 def magic_bg(self, parameter_s=''):
3111 3111 """Run a job in the background, in a separate thread.
3112 3112
3113 3113 For example,
3114 3114
3115 3115 %bg myfunc(x,y,z=1)
3116 3116
3117 3117 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3118 3118 execution starts, a message will be printed indicating the job
3119 3119 number. If your job number is 5, you can use
3120 3120
3121 3121 myvar = jobs.result(5) or myvar = jobs[5].result
3122 3122
3123 3123 to assign this result to variable 'myvar'.
3124 3124
3125 3125 IPython has a job manager, accessible via the 'jobs' object. You can
3126 3126 type jobs? to get more information about it, and use jobs.<TAB> to see
3127 3127 its attributes. All attributes not starting with an underscore are
3128 3128 meant for public use.
3129 3129
3130 3130 In particular, look at the jobs.new() method, which is used to create
3131 3131 new jobs. This magic %bg function is just a convenience wrapper
3132 3132 around jobs.new(), for expression-based jobs. If you want to create a
3133 3133 new job with an explicit function object and arguments, you must call
3134 3134 jobs.new() directly.
3135 3135
3136 3136 The jobs.new docstring also describes in detail several important
3137 3137 caveats associated with a thread-based model for background job
3138 3138 execution. Type jobs.new? for details.
3139 3139
3140 3140 You can check the status of all jobs with jobs.status().
3141 3141
3142 3142 The jobs variable is set by IPython into the Python builtin namespace.
3143 3143 If you ever declare a variable named 'jobs', you will shadow this
3144 3144 name. You can either delete your global jobs variable to regain
3145 3145 access to the job manager, or make a new name and assign it manually
3146 3146 to the manager (stored in IPython's namespace). For example, to
3147 3147 assign the job manager to the Jobs name, use:
3148 3148
3149 3149 Jobs = __builtins__.jobs"""
3150 3150
3151 3151 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3152 3152
3153 3153 def magic_r(self, parameter_s=''):
3154 3154 """Repeat previous input.
3155 3155
3156 3156 Note: Consider using the more powerfull %rep instead!
3157 3157
3158 3158 If given an argument, repeats the previous command which starts with
3159 3159 the same string, otherwise it just repeats the previous input.
3160 3160
3161 3161 Shell escaped commands (with ! as first character) are not recognized
3162 3162 by this system, only pure python code and magic commands.
3163 3163 """
3164 3164
3165 3165 start = parameter_s.strip()
3166 3166 esc_magic = self.shell.ESC_MAGIC
3167 3167 # Identify magic commands even if automagic is on (which means
3168 3168 # the in-memory version is different from that typed by the user).
3169 3169 if self.shell.rc.automagic:
3170 3170 start_magic = esc_magic+start
3171 3171 else:
3172 3172 start_magic = start
3173 3173 # Look through the input history in reverse
3174 3174 for n in range(len(self.shell.input_hist)-2,0,-1):
3175 3175 input = self.shell.input_hist[n]
3176 3176 # skip plain 'r' lines so we don't recurse to infinity
3177 3177 if input != '_ip.magic("r")\n' and \
3178 3178 (input.startswith(start) or input.startswith(start_magic)):
3179 3179 #print 'match',`input` # dbg
3180 3180 print 'Executing:',input,
3181 3181 self.shell.runlines(input)
3182 3182 return
3183 3183 print 'No previous input matching `%s` found.' % start
3184 3184
3185 3185
3186 3186 def magic_bookmark(self, parameter_s=''):
3187 3187 """Manage IPython's bookmark system.
3188 3188
3189 3189 %bookmark <name> - set bookmark to current dir
3190 3190 %bookmark <name> <dir> - set bookmark to <dir>
3191 3191 %bookmark -l - list all bookmarks
3192 3192 %bookmark -d <name> - remove bookmark
3193 3193 %bookmark -r - remove all bookmarks
3194 3194
3195 3195 You can later on access a bookmarked folder with:
3196 3196 %cd -b <name>
3197 3197 or simply '%cd <name>' if there is no directory called <name> AND
3198 3198 there is such a bookmark defined.
3199 3199
3200 3200 Your bookmarks persist through IPython sessions, but they are
3201 3201 associated with each profile."""
3202 3202
3203 3203 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3204 3204 if len(args) > 2:
3205 3205 raise UsageError("%bookmark: too many arguments")
3206 3206
3207 3207 bkms = self.db.get('bookmarks',{})
3208 3208
3209 3209 if opts.has_key('d'):
3210 3210 try:
3211 3211 todel = args[0]
3212 3212 except IndexError:
3213 3213 raise UsageError(
3214 3214 "%bookmark -d: must provide a bookmark to delete")
3215 3215 else:
3216 3216 try:
3217 3217 del bkms[todel]
3218 3218 except KeyError:
3219 3219 raise UsageError(
3220 3220 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3221 3221
3222 3222 elif opts.has_key('r'):
3223 3223 bkms = {}
3224 3224 elif opts.has_key('l'):
3225 3225 bks = bkms.keys()
3226 3226 bks.sort()
3227 3227 if bks:
3228 3228 size = max(map(len,bks))
3229 3229 else:
3230 3230 size = 0
3231 3231 fmt = '%-'+str(size)+'s -> %s'
3232 3232 print 'Current bookmarks:'
3233 3233 for bk in bks:
3234 3234 print fmt % (bk,bkms[bk])
3235 3235 else:
3236 3236 if not args:
3237 3237 raise UsageError("%bookmark: You must specify the bookmark name")
3238 3238 elif len(args)==1:
3239 3239 bkms[args[0]] = os.getcwd()
3240 3240 elif len(args)==2:
3241 3241 bkms[args[0]] = args[1]
3242 3242 self.db['bookmarks'] = bkms
3243 3243
3244 3244 def magic_pycat(self, parameter_s=''):
3245 3245 """Show a syntax-highlighted file through a pager.
3246 3246
3247 3247 This magic is similar to the cat utility, but it will assume the file
3248 3248 to be Python source and will show it with syntax highlighting. """
3249 3249
3250 3250 try:
3251 3251 filename = get_py_filename(parameter_s)
3252 3252 cont = file_read(filename)
3253 3253 except IOError:
3254 3254 try:
3255 3255 cont = eval(parameter_s,self.user_ns)
3256 3256 except NameError:
3257 3257 cont = None
3258 3258 if cont is None:
3259 3259 print "Error: no such file or variable"
3260 3260 return
3261 3261
3262 3262 page(self.shell.pycolorize(cont),
3263 3263 screen_lines=self.shell.rc.screen_length)
3264 3264
3265 3265 def magic_cpaste(self, parameter_s=''):
3266 3266 """Allows you to paste & execute a pre-formatted code block from clipboard.
3267 3267
3268 3268 You must terminate the block with '--' (two minus-signs) alone on the
3269 3269 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3270 3270 is the new sentinel for this operation)
3271 3271
3272 3272 The block is dedented prior to execution to enable execution of method
3273 3273 definitions. '>' and '+' characters at the beginning of a line are
3274 3274 ignored, to allow pasting directly from e-mails, diff files and
3275 3275 doctests (the '...' continuation prompt is also stripped). The
3276 3276 executed block is also assigned to variable named 'pasted_block' for
3277 3277 later editing with '%edit pasted_block'.
3278 3278
3279 3279 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3280 3280 This assigns the pasted block to variable 'foo' as string, without
3281 3281 dedenting or executing it (preceding >>> and + is still stripped)
3282 3282
3283 3283 '%cpaste -r' re-executes the block previously entered by cpaste.
3284 3284
3285 3285 Do not be alarmed by garbled output on Windows (it's a readline bug).
3286 3286 Just press enter and type -- (and press enter again) and the block
3287 3287 will be what was just pasted.
3288 3288
3289 3289 IPython statements (magics, shell escapes) are not supported (yet).
3290 3290 """
3291 3291 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3292 3292 par = args.strip()
3293 3293 if opts.has_key('r'):
3294 3294 b = self.user_ns.get('pasted_block', None)
3295 3295 if b is None:
3296 3296 raise UsageError('No previous pasted block available')
3297 3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3298 3298 exec b in self.user_ns
3299 3299 return
3300 3300
3301 3301 sentinel = opts.get('s','--')
3302 3302
3303 3303 # Regular expressions that declare text we strip from the input:
3304 3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3305 3305 r'^\s*(\s?>)+', # Python input prompt
3306 3306 r'^\s*\.{3,}', # Continuation prompts
3307 3307 r'^\++',
3308 3308 ]
3309 3309
3310 3310 strip_from_start = map(re.compile,strip_re)
3311 3311
3312 3312 from IPython import iplib
3313 3313 lines = []
3314 3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3315 3315 while 1:
3316 3316 l = iplib.raw_input_original(':')
3317 3317 if l ==sentinel:
3318 3318 break
3319 3319
3320 3320 for pat in strip_from_start:
3321 3321 l = pat.sub('',l)
3322 3322 lines.append(l)
3323 3323
3324 3324 block = "\n".join(lines) + '\n'
3325 3325 #print "block:\n",block
3326 3326 if not par:
3327 3327 b = textwrap.dedent(block)
3328 3328 self.user_ns['pasted_block'] = b
3329 3329 exec b in self.user_ns
3330 3330 else:
3331 3331 self.user_ns[par] = SList(block.splitlines())
3332 3332 print "Block assigned to '%s'" % par
3333 3333
3334 3334 def magic_quickref(self,arg):
3335 3335 """ Show a quick reference sheet """
3336 3336 import IPython.usage
3337 3337 qr = IPython.usage.quick_reference + self.magic_magic('-brief')
3338 3338
3339 3339 page(qr)
3340 3340
3341 3341 def magic_upgrade(self,arg):
3342 3342 """ Upgrade your IPython installation
3343 3343
3344 3344 This will copy the config files that don't yet exist in your
3345 3345 ipython dir from the system config dir. Use this after upgrading
3346 3346 IPython if you don't wish to delete your .ipython dir.
3347 3347
3348 3348 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3349 3349 new users)
3350 3350
3351 3351 """
3352 3352 ip = self.getapi()
3353 3353 ipinstallation = path(IPython.__file__).dirname()
3354 3354 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'upgrade_dir.py')
3355 3355 src_config = ipinstallation / 'UserConfig'
3356 3356 userdir = path(ip.options.ipythondir)
3357 3357 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3358 3358 print ">",cmd
3359 3359 shell(cmd)
3360 3360 if arg == '-nolegacy':
3361 3361 legacy = userdir.files('ipythonrc*')
3362 3362 print "Nuking legacy files:",legacy
3363 3363
3364 3364 [p.remove() for p in legacy]
3365 3365 suffix = (sys.platform == 'win32' and '.ini' or '')
3366 3366 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3367 3367
3368 3368
3369 3369 def magic_doctest_mode(self,parameter_s=''):
3370 3370 """Toggle doctest mode on and off.
3371 3371
3372 3372 This mode allows you to toggle the prompt behavior between normal
3373 3373 IPython prompts and ones that are as similar to the default IPython
3374 3374 interpreter as possible.
3375 3375
3376 3376 It also supports the pasting of code snippets that have leading '>>>'
3377 3377 and '...' prompts in them. This means that you can paste doctests from
3378 3378 files or docstrings (even if they have leading whitespace), and the
3379 3379 code will execute correctly. You can then use '%history -tn' to see
3380 3380 the translated history without line numbers; this will give you the
3381 3381 input after removal of all the leading prompts and whitespace, which
3382 3382 can be pasted back into an editor.
3383 3383
3384 3384 With these features, you can switch into this mode easily whenever you
3385 3385 need to do testing and changes to doctests, without having to leave
3386 3386 your existing IPython session.
3387 3387 """
3388 3388
3389 3389 # XXX - Fix this to have cleaner activate/deactivate calls.
3390 3390 from IPython.Extensions import InterpreterPasteInput as ipaste
3391 3391 from IPython.ipstruct import Struct
3392 3392
3393 3393 # Shorthands
3394 3394 shell = self.shell
3395 3395 oc = shell.outputcache
3396 3396 rc = shell.rc
3397 3397 meta = shell.meta
3398 3398 # dstore is a data store kept in the instance metadata bag to track any
3399 3399 # changes we make, so we can undo them later.
3400 3400 dstore = meta.setdefault('doctest_mode',Struct())
3401 3401 save_dstore = dstore.setdefault
3402 3402
3403 3403 # save a few values we'll need to recover later
3404 3404 mode = save_dstore('mode',False)
3405 3405 save_dstore('rc_pprint',rc.pprint)
3406 3406 save_dstore('xmode',shell.InteractiveTB.mode)
3407 3407 save_dstore('rc_separate_out',rc.separate_out)
3408 3408 save_dstore('rc_separate_out2',rc.separate_out2)
3409 3409 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3410 3410 save_dstore('rc_separate_in',rc.separate_in)
3411 3411
3412 3412 if mode == False:
3413 3413 # turn on
3414 3414 ipaste.activate_prefilter()
3415 3415
3416 3416 oc.prompt1.p_template = '>>> '
3417 3417 oc.prompt2.p_template = '... '
3418 3418 oc.prompt_out.p_template = ''
3419 3419
3420 3420 # Prompt separators like plain python
3421 3421 oc.input_sep = oc.prompt1.sep = ''
3422 3422 oc.output_sep = ''
3423 3423 oc.output_sep2 = ''
3424 3424
3425 3425 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3426 3426 oc.prompt_out.pad_left = False
3427 3427
3428 3428 rc.pprint = False
3429 3429
3430 3430 shell.magic_xmode('Plain')
3431 3431
3432 3432 else:
3433 3433 # turn off
3434 3434 ipaste.deactivate_prefilter()
3435 3435
3436 3436 oc.prompt1.p_template = rc.prompt_in1
3437 3437 oc.prompt2.p_template = rc.prompt_in2
3438 3438 oc.prompt_out.p_template = rc.prompt_out
3439 3439
3440 3440 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3441 3441
3442 3442 oc.output_sep = dstore.rc_separate_out
3443 3443 oc.output_sep2 = dstore.rc_separate_out2
3444 3444
3445 3445 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3446 3446 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3447 3447
3448 3448 rc.pprint = dstore.rc_pprint
3449 3449
3450 3450 shell.magic_xmode(dstore.xmode)
3451 3451
3452 3452 # Store new mode and inform
3453 3453 dstore.mode = bool(1-int(mode))
3454 3454 print 'Doctest mode is:',
3455 3455 print ['OFF','ON'][dstore.mode]
3456 3456
3457 3457 # end Magic
1 NO CONTENT: file renamed from IPython/FakeModule.py to IPython/core/fakemodule.py
@@ -1,17 +1,17 b''
1 1 """Tests for the FakeModule objects.
2 2 """
3 3
4 4 import nose.tools as nt
5 5
6 from IPython.FakeModule import FakeModule, init_fakemod_dict
6 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
7 7
8 8 # Make a fakemod and check a few properties
9 9 def test_mk_fakemod():
10 10 fm = FakeModule()
11 11 yield nt.assert_true,fm
12 12 yield nt.assert_true,lambda : hasattr(fm,'__file__')
13 13
14 14 def test_mk_fakemod_fromdict():
15 15 """Test making a FakeModule object with initial data"""
16 16 fm = FakeModule(dict(hello=True))
17 17 nt.assert_true(fm.hello)
@@ -1,11 +1,15 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3
4 4 def test_import_completer():
5 5 from IPython.core import completer
6 6
7 7 def test_import_crashhandler():
8 8 from IPython.core import crashhandler
9 9
10 10 def test_import_debugger():
11 from IPython.core import debugger No newline at end of file
11 from IPython.core import debugger
12
13 def test_import_fakemodule():
14 from IPython.core import fakemodule
15
@@ -1,2863 +1,2863 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.4 or newer.
6 6
7 7 This file contains all the classes and helper functions specific to IPython.
8 8 """
9 9
10 10 #*****************************************************************************
11 11 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
12 12 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
13 13 #
14 14 # Distributed under the terms of the BSD License. The full license is in
15 15 # the file COPYING, distributed as part of this software.
16 16 #
17 17 # Note: this code originally subclassed code.InteractiveConsole from the
18 18 # Python standard library. Over time, all of that class has been copied
19 19 # verbatim here for modifications which could not be accomplished by
20 20 # subclassing. At this point, there are no dependencies at all on the code
21 21 # module anymore (it is not even imported). The Python License (sec. 2)
22 22 # allows for this, but it's always nice to acknowledge credit where credit is
23 23 # due.
24 24 #*****************************************************************************
25 25
26 26 #****************************************************************************
27 27 # Modules and globals
28 28
29 29 # Python standard modules
30 30 import __main__
31 31 import __builtin__
32 32 import StringIO
33 33 import bdb
34 34 import codeop
35 35 import exceptions
36 36 import glob
37 37 import keyword
38 38 import new
39 39 import os
40 40 import re
41 41 import shutil
42 42 import string
43 43 import sys
44 44 import tempfile
45 45
46 46 # IPython's own modules
47 47 #import IPython
48 48 from IPython import OInspect,PyColorize,ultraTB
49 49 from IPython.core import debugger
50 50 from IPython.Extensions import pickleshare
51 from IPython.FakeModule import FakeModule, init_fakemod_dict
51 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
52 52 from IPython.Itpl import ItplNS
53 53 from IPython.Logger import Logger
54 54 from IPython.Magic import Magic
55 55 from IPython.Prompts import CachedOutput
56 56 from IPython.ipstruct import Struct
57 57 from IPython.lib.backgroundjobs import BackgroundJobManager
58 58 from IPython.genutils import *
59 59 from IPython.strdispatch import StrDispatch
60 60 import IPython.ipapi
61 61 import IPython.history
62 62 import IPython.prefilter as prefilter
63 63 import IPython.shadowns
64 64 # Globals
65 65
66 66 # store the builtin raw_input globally, and use this always, in case user code
67 67 # overwrites it (like wx.py.PyShell does)
68 68 raw_input_original = raw_input
69 69
70 70 # compiled regexps for autoindent management
71 71 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
72 72
73 73
74 74 #****************************************************************************
75 75 # Some utility function definitions
76 76
77 77 ini_spaces_re = re.compile(r'^(\s+)')
78 78
79 79 def num_ini_spaces(strng):
80 80 """Return the number of initial spaces in a string"""
81 81
82 82 ini_spaces = ini_spaces_re.match(strng)
83 83 if ini_spaces:
84 84 return ini_spaces.end()
85 85 else:
86 86 return 0
87 87
88 88 def softspace(file, newvalue):
89 89 """Copied from code.py, to remove the dependency"""
90 90
91 91 oldvalue = 0
92 92 try:
93 93 oldvalue = file.softspace
94 94 except AttributeError:
95 95 pass
96 96 try:
97 97 file.softspace = newvalue
98 98 except (AttributeError, TypeError):
99 99 # "attribute-less object" or "read-only attributes"
100 100 pass
101 101 return oldvalue
102 102
103 103
104 104 def user_setup(ipythondir,rc_suffix,mode='install',interactive=True):
105 105 """Install or upgrade the user configuration directory.
106 106
107 107 Can be called when running for the first time or to upgrade the user's
108 108 .ipython/ directory.
109 109
110 110 Parameters
111 111 ----------
112 112 ipythondir : path
113 113 The directory to be used for installation/upgrade. In 'install' mode,
114 114 if this path already exists, the function exits immediately.
115 115
116 116 rc_suffix : str
117 117 Extension for the config files. On *nix platforms it is typically the
118 118 empty string, while Windows normally uses '.ini'.
119 119
120 120 mode : str, optional
121 121 Valid modes are 'install' and 'upgrade'.
122 122
123 123 interactive : bool, optional
124 124 If False, do not wait for user input on any errors. Normally after
125 125 printing its status information, this function waits for the user to
126 126 hit Return before proceeding. This is because the default use case is
127 127 when first installing the IPython configuration, so we want the user to
128 128 acknowledge the initial message, which contains some useful
129 129 information.
130 130 """
131 131
132 132 # For automatic use, deactivate all i/o
133 133 if interactive:
134 134 def wait():
135 135 try:
136 136 raw_input("Please press <RETURN> to start IPython.")
137 137 except EOFError:
138 138 print >> Term.cout
139 139 print '*'*70
140 140
141 141 def printf(s):
142 142 print s
143 143 else:
144 144 wait = lambda : None
145 145 printf = lambda s : None
146 146
147 147 # Install mode should be re-entrant: if the install dir already exists,
148 148 # bail out cleanly.
149 149 # XXX. This is too hasty to return. We need to check to make sure that
150 150 # all the expected config files and directories are actually there. We
151 151 # currently have a failure mode if someone deletes a needed config file
152 152 # but still has the ipythondir.
153 153 if mode == 'install' and os.path.isdir(ipythondir):
154 154 return
155 155
156 156 cwd = os.getcwd() # remember where we started
157 157 glb = glob.glob
158 158
159 159 printf('*'*70)
160 160 if mode == 'install':
161 161 printf(
162 162 """Welcome to IPython. I will try to create a personal configuration directory
163 163 where you can customize many aspects of IPython's functionality in:\n""")
164 164 else:
165 165 printf('I am going to upgrade your configuration in:')
166 166
167 167 printf(ipythondir)
168 168
169 169 rcdirend = os.path.join('IPython','UserConfig')
170 170 cfg = lambda d: os.path.join(d,rcdirend)
171 171 try:
172 172 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
173 173 printf("Initializing from configuration: %s" % rcdir)
174 174 except IndexError:
175 175 warning = """
176 176 Installation error. IPython's directory was not found.
177 177
178 178 Check the following:
179 179
180 180 The ipython/IPython directory should be in a directory belonging to your
181 181 PYTHONPATH environment variable (that is, it should be in a directory
182 182 belonging to sys.path). You can copy it explicitly there or just link to it.
183 183
184 184 IPython will create a minimal default configuration for you.
185 185
186 186 """
187 187 warn(warning)
188 188 wait()
189 189
190 190 if sys.platform =='win32':
191 191 inif = 'ipythonrc.ini'
192 192 else:
193 193 inif = 'ipythonrc'
194 194 minimal_setup = {'ipy_user_conf.py' : 'import ipy_defaults',
195 195 inif : '# intentionally left blank' }
196 196 os.makedirs(ipythondir, mode = 0777)
197 197 for f, cont in minimal_setup.items():
198 198 # In 2.5, this can be more cleanly done using 'with'
199 199 fobj = file(ipythondir + '/' + f,'w')
200 200 fobj.write(cont)
201 201 fobj.close()
202 202
203 203 return
204 204
205 205 if mode == 'install':
206 206 try:
207 207 shutil.copytree(rcdir,ipythondir)
208 208 os.chdir(ipythondir)
209 209 rc_files = glb("ipythonrc*")
210 210 for rc_file in rc_files:
211 211 os.rename(rc_file,rc_file+rc_suffix)
212 212 except:
213 213 warning = """
214 214
215 215 There was a problem with the installation:
216 216 %s
217 217 Try to correct it or contact the developers if you think it's a bug.
218 218 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
219 219 warn(warning)
220 220 wait()
221 221 return
222 222
223 223 elif mode == 'upgrade':
224 224 try:
225 225 os.chdir(ipythondir)
226 226 except:
227 227 printf("""
228 228 Can not upgrade: changing to directory %s failed. Details:
229 229 %s
230 230 """ % (ipythondir,sys.exc_info()[1]) )
231 231 wait()
232 232 return
233 233 else:
234 234 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
235 235 for new_full_path in sources:
236 236 new_filename = os.path.basename(new_full_path)
237 237 if new_filename.startswith('ipythonrc'):
238 238 new_filename = new_filename + rc_suffix
239 239 # The config directory should only contain files, skip any
240 240 # directories which may be there (like CVS)
241 241 if os.path.isdir(new_full_path):
242 242 continue
243 243 if os.path.exists(new_filename):
244 244 old_file = new_filename+'.old'
245 245 if os.path.exists(old_file):
246 246 os.remove(old_file)
247 247 os.rename(new_filename,old_file)
248 248 shutil.copy(new_full_path,new_filename)
249 249 else:
250 250 raise ValueError('unrecognized mode for install: %r' % mode)
251 251
252 252 # Fix line-endings to those native to each platform in the config
253 253 # directory.
254 254 try:
255 255 os.chdir(ipythondir)
256 256 except:
257 257 printf("""
258 258 Problem: changing to directory %s failed.
259 259 Details:
260 260 %s
261 261
262 262 Some configuration files may have incorrect line endings. This should not
263 263 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1]) )
264 264 wait()
265 265 else:
266 266 for fname in glb('ipythonrc*'):
267 267 try:
268 268 native_line_ends(fname,backup=0)
269 269 except IOError:
270 270 pass
271 271
272 272 if mode == 'install':
273 273 printf("""
274 274 Successful installation!
275 275
276 276 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
277 277 IPython manual (there are both HTML and PDF versions supplied with the
278 278 distribution) to make sure that your system environment is properly configured
279 279 to take advantage of IPython's features.
280 280
281 281 Important note: the configuration system has changed! The old system is
282 282 still in place, but its setting may be partly overridden by the settings in
283 283 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file
284 284 if some of the new settings bother you.
285 285
286 286 """)
287 287 else:
288 288 printf("""
289 289 Successful upgrade!
290 290
291 291 All files in your directory:
292 292 %(ipythondir)s
293 293 which would have been overwritten by the upgrade were backed up with a .old
294 294 extension. If you had made particular customizations in those files you may
295 295 want to merge them back into the new files.""" % locals() )
296 296 wait()
297 297 os.chdir(cwd)
298 298
299 299 #****************************************************************************
300 300 # Local use exceptions
301 301 class SpaceInInput(exceptions.Exception): pass
302 302
303 303
304 304 #****************************************************************************
305 305 # Local use classes
306 306 class Bunch: pass
307 307
308 308 class Undefined: pass
309 309
310 310 class Quitter(object):
311 311 """Simple class to handle exit, similar to Python 2.5's.
312 312
313 313 It handles exiting in an ipython-safe manner, which the one in Python 2.5
314 314 doesn't do (obviously, since it doesn't know about ipython)."""
315 315
316 316 def __init__(self,shell,name):
317 317 self.shell = shell
318 318 self.name = name
319 319
320 320 def __repr__(self):
321 321 return 'Type %s() to exit.' % self.name
322 322 __str__ = __repr__
323 323
324 324 def __call__(self):
325 325 self.shell.exit()
326 326
327 327 class InputList(list):
328 328 """Class to store user input.
329 329
330 330 It's basically a list, but slices return a string instead of a list, thus
331 331 allowing things like (assuming 'In' is an instance):
332 332
333 333 exec In[4:7]
334 334
335 335 or
336 336
337 337 exec In[5:9] + In[14] + In[21:25]"""
338 338
339 339 def __getslice__(self,i,j):
340 340 return ''.join(list.__getslice__(self,i,j))
341 341
342 342 class SyntaxTB(ultraTB.ListTB):
343 343 """Extension which holds some state: the last exception value"""
344 344
345 345 def __init__(self,color_scheme = 'NoColor'):
346 346 ultraTB.ListTB.__init__(self,color_scheme)
347 347 self.last_syntax_error = None
348 348
349 349 def __call__(self, etype, value, elist):
350 350 self.last_syntax_error = value
351 351 ultraTB.ListTB.__call__(self,etype,value,elist)
352 352
353 353 def clear_err_state(self):
354 354 """Return the current error state and clear it"""
355 355 e = self.last_syntax_error
356 356 self.last_syntax_error = None
357 357 return e
358 358
359 359 #****************************************************************************
360 360 # Main IPython class
361 361
362 362 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
363 363 # until a full rewrite is made. I've cleaned all cross-class uses of
364 364 # attributes and methods, but too much user code out there relies on the
365 365 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
366 366 #
367 367 # But at least now, all the pieces have been separated and we could, in
368 368 # principle, stop using the mixin. This will ease the transition to the
369 369 # chainsaw branch.
370 370
371 371 # For reference, the following is the list of 'self.foo' uses in the Magic
372 372 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
373 373 # class, to prevent clashes.
374 374
375 375 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
376 376 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
377 377 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
378 378 # 'self.value']
379 379
380 380 class InteractiveShell(object,Magic):
381 381 """An enhanced console for Python."""
382 382
383 383 # class attribute to indicate whether the class supports threads or not.
384 384 # Subclasses with thread support should override this as needed.
385 385 isthreaded = False
386 386
387 387 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
388 388 user_ns=None,user_global_ns=None,banner2='',
389 389 custom_exceptions=((),None),embedded=False):
390 390
391 391 # log system
392 392 self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
393 393
394 394 # Job manager (for jobs run as background threads)
395 395 self.jobs = BackgroundJobManager()
396 396
397 397 # Store the actual shell's name
398 398 self.name = name
399 399 self.more = False
400 400
401 401 # We need to know whether the instance is meant for embedding, since
402 402 # global/local namespaces need to be handled differently in that case
403 403 self.embedded = embedded
404 404 if embedded:
405 405 # Control variable so users can, from within the embedded instance,
406 406 # permanently deactivate it.
407 407 self.embedded_active = True
408 408
409 409 # command compiler
410 410 self.compile = codeop.CommandCompiler()
411 411
412 412 # User input buffer
413 413 self.buffer = []
414 414
415 415 # Default name given in compilation of code
416 416 self.filename = '<ipython console>'
417 417
418 418 # Install our own quitter instead of the builtins. For python2.3-2.4,
419 419 # this brings in behavior like 2.5, and for 2.5 it's identical.
420 420 __builtin__.exit = Quitter(self,'exit')
421 421 __builtin__.quit = Quitter(self,'quit')
422 422
423 423 # Make an empty namespace, which extension writers can rely on both
424 424 # existing and NEVER being used by ipython itself. This gives them a
425 425 # convenient location for storing additional information and state
426 426 # their extensions may require, without fear of collisions with other
427 427 # ipython names that may develop later.
428 428 self.meta = Struct()
429 429
430 430 # Create the namespace where the user will operate. user_ns is
431 431 # normally the only one used, and it is passed to the exec calls as
432 432 # the locals argument. But we do carry a user_global_ns namespace
433 433 # given as the exec 'globals' argument, This is useful in embedding
434 434 # situations where the ipython shell opens in a context where the
435 435 # distinction between locals and globals is meaningful. For
436 436 # non-embedded contexts, it is just the same object as the user_ns dict.
437 437
438 438 # FIXME. For some strange reason, __builtins__ is showing up at user
439 439 # level as a dict instead of a module. This is a manual fix, but I
440 440 # should really track down where the problem is coming from. Alex
441 441 # Schmolck reported this problem first.
442 442
443 443 # A useful post by Alex Martelli on this topic:
444 444 # Re: inconsistent value from __builtins__
445 445 # Von: Alex Martelli <aleaxit@yahoo.com>
446 446 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
447 447 # Gruppen: comp.lang.python
448 448
449 449 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
450 450 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
451 451 # > <type 'dict'>
452 452 # > >>> print type(__builtins__)
453 453 # > <type 'module'>
454 454 # > Is this difference in return value intentional?
455 455
456 456 # Well, it's documented that '__builtins__' can be either a dictionary
457 457 # or a module, and it's been that way for a long time. Whether it's
458 458 # intentional (or sensible), I don't know. In any case, the idea is
459 459 # that if you need to access the built-in namespace directly, you
460 460 # should start with "import __builtin__" (note, no 's') which will
461 461 # definitely give you a module. Yeah, it's somewhat confusing:-(.
462 462
463 463 # These routines return properly built dicts as needed by the rest of
464 464 # the code, and can also be used by extension writers to generate
465 465 # properly initialized namespaces.
466 466 user_ns, user_global_ns = IPython.ipapi.make_user_namespaces(user_ns,
467 467 user_global_ns)
468 468
469 469 # Assign namespaces
470 470 # This is the namespace where all normal user variables live
471 471 self.user_ns = user_ns
472 472 self.user_global_ns = user_global_ns
473 473
474 474 # An auxiliary namespace that checks what parts of the user_ns were
475 475 # loaded at startup, so we can list later only variables defined in
476 476 # actual interactive use. Since it is always a subset of user_ns, it
477 477 # doesn't need to be seaparately tracked in the ns_table
478 478 self.user_config_ns = {}
479 479
480 480 # A namespace to keep track of internal data structures to prevent
481 481 # them from cluttering user-visible stuff. Will be updated later
482 482 self.internal_ns = {}
483 483
484 484 # Namespace of system aliases. Each entry in the alias
485 485 # table must be a 2-tuple of the form (N,name), where N is the number
486 486 # of positional arguments of the alias.
487 487 self.alias_table = {}
488 488
489 489 # Now that FakeModule produces a real module, we've run into a nasty
490 490 # problem: after script execution (via %run), the module where the user
491 491 # code ran is deleted. Now that this object is a true module (needed
492 492 # so docetst and other tools work correctly), the Python module
493 493 # teardown mechanism runs over it, and sets to None every variable
494 494 # present in that module. Top-level references to objects from the
495 495 # script survive, because the user_ns is updated with them. However,
496 496 # calling functions defined in the script that use other things from
497 497 # the script will fail, because the function's closure had references
498 498 # to the original objects, which are now all None. So we must protect
499 499 # these modules from deletion by keeping a cache.
500 500 #
501 501 # To avoid keeping stale modules around (we only need the one from the
502 502 # last run), we use a dict keyed with the full path to the script, so
503 503 # only the last version of the module is held in the cache. Note,
504 504 # however, that we must cache the module *namespace contents* (their
505 505 # __dict__). Because if we try to cache the actual modules, old ones
506 506 # (uncached) could be destroyed while still holding references (such as
507 507 # those held by GUI objects that tend to be long-lived)>
508 508 #
509 509 # The %reset command will flush this cache. See the cache_main_mod()
510 510 # and clear_main_mod_cache() methods for details on use.
511 511
512 512 # This is the cache used for 'main' namespaces
513 513 self._main_ns_cache = {}
514 514 # And this is the single instance of FakeModule whose __dict__ we keep
515 515 # copying and clearing for reuse on each %run
516 516 self._user_main_module = FakeModule()
517 517
518 518 # A table holding all the namespaces IPython deals with, so that
519 519 # introspection facilities can search easily.
520 520 self.ns_table = {'user':user_ns,
521 521 'user_global':user_global_ns,
522 522 'alias':self.alias_table,
523 523 'internal':self.internal_ns,
524 524 'builtin':__builtin__.__dict__
525 525 }
526 526
527 527 # Similarly, track all namespaces where references can be held and that
528 528 # we can safely clear (so it can NOT include builtin). This one can be
529 529 # a simple list.
530 530 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
531 531 self.alias_table, self.internal_ns,
532 532 self._main_ns_cache ]
533 533
534 534 # We need to insert into sys.modules something that looks like a
535 535 # module but which accesses the IPython namespace, for shelve and
536 536 # pickle to work interactively. Normally they rely on getting
537 537 # everything out of __main__, but for embedding purposes each IPython
538 538 # instance has its own private namespace, so we can't go shoving
539 539 # everything into __main__.
540 540
541 541 # note, however, that we should only do this for non-embedded
542 542 # ipythons, which really mimic the __main__.__dict__ with their own
543 543 # namespace. Embedded instances, on the other hand, should not do
544 544 # this because they need to manage the user local/global namespaces
545 545 # only, but they live within a 'normal' __main__ (meaning, they
546 546 # shouldn't overtake the execution environment of the script they're
547 547 # embedded in).
548 548
549 549 if not embedded:
550 550 try:
551 551 main_name = self.user_ns['__name__']
552 552 except KeyError:
553 553 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
554 554 else:
555 555 #print "pickle hack in place" # dbg
556 556 #print 'main_name:',main_name # dbg
557 557 sys.modules[main_name] = FakeModule(self.user_ns)
558 558
559 559 # List of input with multi-line handling.
560 560 self.input_hist = InputList()
561 561 # This one will hold the 'raw' input history, without any
562 562 # pre-processing. This will allow users to retrieve the input just as
563 563 # it was exactly typed in by the user, with %hist -r.
564 564 self.input_hist_raw = InputList()
565 565
566 566 # list of visited directories
567 567 try:
568 568 self.dir_hist = [os.getcwd()]
569 569 except OSError:
570 570 self.dir_hist = []
571 571
572 572 # dict of output history
573 573 self.output_hist = {}
574 574
575 575 # Get system encoding at startup time. Certain terminals (like Emacs
576 576 # under Win32 have it set to None, and we need to have a known valid
577 577 # encoding to use in the raw_input() method
578 578 try:
579 579 self.stdin_encoding = sys.stdin.encoding or 'ascii'
580 580 except AttributeError:
581 581 self.stdin_encoding = 'ascii'
582 582
583 583 # dict of things NOT to alias (keywords, builtins and some magics)
584 584 no_alias = {}
585 585 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
586 586 for key in keyword.kwlist + no_alias_magics:
587 587 no_alias[key] = 1
588 588 no_alias.update(__builtin__.__dict__)
589 589 self.no_alias = no_alias
590 590
591 591 # Object variable to store code object waiting execution. This is
592 592 # used mainly by the multithreaded shells, but it can come in handy in
593 593 # other situations. No need to use a Queue here, since it's a single
594 594 # item which gets cleared once run.
595 595 self.code_to_run = None
596 596
597 597 # escapes for automatic behavior on the command line
598 598 self.ESC_SHELL = '!'
599 599 self.ESC_SH_CAP = '!!'
600 600 self.ESC_HELP = '?'
601 601 self.ESC_MAGIC = '%'
602 602 self.ESC_QUOTE = ','
603 603 self.ESC_QUOTE2 = ';'
604 604 self.ESC_PAREN = '/'
605 605
606 606 # And their associated handlers
607 607 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
608 608 self.ESC_QUOTE : self.handle_auto,
609 609 self.ESC_QUOTE2 : self.handle_auto,
610 610 self.ESC_MAGIC : self.handle_magic,
611 611 self.ESC_HELP : self.handle_help,
612 612 self.ESC_SHELL : self.handle_shell_escape,
613 613 self.ESC_SH_CAP : self.handle_shell_escape,
614 614 }
615 615
616 616 # class initializations
617 617 Magic.__init__(self,self)
618 618
619 619 # Python source parser/formatter for syntax highlighting
620 620 pyformat = PyColorize.Parser().format
621 621 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
622 622
623 623 # hooks holds pointers used for user-side customizations
624 624 self.hooks = Struct()
625 625
626 626 self.strdispatchers = {}
627 627
628 628 # Set all default hooks, defined in the IPython.hooks module.
629 629 hooks = IPython.hooks
630 630 for hook_name in hooks.__all__:
631 631 # default hooks have priority 100, i.e. low; user hooks should have
632 632 # 0-100 priority
633 633 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
634 634 #print "bound hook",hook_name
635 635
636 636 # Flag to mark unconditional exit
637 637 self.exit_now = False
638 638
639 639 self.usage_min = """\
640 640 An enhanced console for Python.
641 641 Some of its features are:
642 642 - Readline support if the readline library is present.
643 643 - Tab completion in the local namespace.
644 644 - Logging of input, see command-line options.
645 645 - System shell escape via ! , eg !ls.
646 646 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
647 647 - Keeps track of locally defined variables via %who, %whos.
648 648 - Show object information with a ? eg ?x or x? (use ?? for more info).
649 649 """
650 650 if usage: self.usage = usage
651 651 else: self.usage = self.usage_min
652 652
653 653 # Storage
654 654 self.rc = rc # This will hold all configuration information
655 655 self.pager = 'less'
656 656 # temporary files used for various purposes. Deleted at exit.
657 657 self.tempfiles = []
658 658
659 659 # Keep track of readline usage (later set by init_readline)
660 660 self.has_readline = False
661 661
662 662 # template for logfile headers. It gets resolved at runtime by the
663 663 # logstart method.
664 664 self.loghead_tpl = \
665 665 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
666 666 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
667 667 #log# opts = %s
668 668 #log# args = %s
669 669 #log# It is safe to make manual edits below here.
670 670 #log#-----------------------------------------------------------------------
671 671 """
672 672 # for pushd/popd management
673 673 try:
674 674 self.home_dir = get_home_dir()
675 675 except HomeDirError,msg:
676 676 fatal(msg)
677 677
678 678 self.dir_stack = []
679 679
680 680 # Functions to call the underlying shell.
681 681
682 682 # The first is similar to os.system, but it doesn't return a value,
683 683 # and it allows interpolation of variables in the user's namespace.
684 684 self.system = lambda cmd: \
685 685 self.hooks.shell_hook(self.var_expand(cmd,depth=2))
686 686
687 687 # These are for getoutput and getoutputerror:
688 688 self.getoutput = lambda cmd: \
689 689 getoutput(self.var_expand(cmd,depth=2),
690 690 header=self.rc.system_header,
691 691 verbose=self.rc.system_verbose)
692 692
693 693 self.getoutputerror = lambda cmd: \
694 694 getoutputerror(self.var_expand(cmd,depth=2),
695 695 header=self.rc.system_header,
696 696 verbose=self.rc.system_verbose)
697 697
698 698
699 699 # keep track of where we started running (mainly for crash post-mortem)
700 700 self.starting_dir = os.getcwd()
701 701
702 702 # Various switches which can be set
703 703 self.CACHELENGTH = 5000 # this is cheap, it's just text
704 704 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
705 705 self.banner2 = banner2
706 706
707 707 # TraceBack handlers:
708 708
709 709 # Syntax error handler.
710 710 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
711 711
712 712 # The interactive one is initialized with an offset, meaning we always
713 713 # want to remove the topmost item in the traceback, which is our own
714 714 # internal code. Valid modes: ['Plain','Context','Verbose']
715 715 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
716 716 color_scheme='NoColor',
717 717 tb_offset = 1)
718 718
719 719 # IPython itself shouldn't crash. This will produce a detailed
720 720 # post-mortem if it does. But we only install the crash handler for
721 721 # non-threaded shells, the threaded ones use a normal verbose reporter
722 722 # and lose the crash handler. This is because exceptions in the main
723 723 # thread (such as in GUI code) propagate directly to sys.excepthook,
724 724 # and there's no point in printing crash dumps for every user exception.
725 725 if self.isthreaded:
726 726 ipCrashHandler = ultraTB.FormattedTB()
727 727 else:
728 728 from IPython.core import crashhandler
729 729 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
730 730 self.set_crash_handler(ipCrashHandler)
731 731
732 732 # and add any custom exception handlers the user may have specified
733 733 self.set_custom_exc(*custom_exceptions)
734 734
735 735 # indentation management
736 736 self.autoindent = False
737 737 self.indent_current_nsp = 0
738 738
739 739 # Make some aliases automatically
740 740 # Prepare list of shell aliases to auto-define
741 741 if os.name == 'posix':
742 742 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
743 743 'mv mv -i','rm rm -i','cp cp -i',
744 744 'cat cat','less less','clear clear',
745 745 # a better ls
746 746 'ls ls -F',
747 747 # long ls
748 748 'll ls -lF')
749 749 # Extra ls aliases with color, which need special treatment on BSD
750 750 # variants
751 751 ls_extra = ( # color ls
752 752 'lc ls -F -o --color',
753 753 # ls normal files only
754 754 'lf ls -F -o --color %l | grep ^-',
755 755 # ls symbolic links
756 756 'lk ls -F -o --color %l | grep ^l',
757 757 # directories or links to directories,
758 758 'ldir ls -F -o --color %l | grep /$',
759 759 # things which are executable
760 760 'lx ls -F -o --color %l | grep ^-..x',
761 761 )
762 762 # The BSDs don't ship GNU ls, so they don't understand the
763 763 # --color switch out of the box
764 764 if 'bsd' in sys.platform:
765 765 ls_extra = ( # ls normal files only
766 766 'lf ls -lF | grep ^-',
767 767 # ls symbolic links
768 768 'lk ls -lF | grep ^l',
769 769 # directories or links to directories,
770 770 'ldir ls -lF | grep /$',
771 771 # things which are executable
772 772 'lx ls -lF | grep ^-..x',
773 773 )
774 774 auto_alias = auto_alias + ls_extra
775 775 elif os.name in ['nt','dos']:
776 776 auto_alias = ('ls dir /on',
777 777 'ddir dir /ad /on', 'ldir dir /ad /on',
778 778 'mkdir mkdir','rmdir rmdir','echo echo',
779 779 'ren ren','cls cls','copy copy')
780 780 else:
781 781 auto_alias = ()
782 782 self.auto_alias = [s.split(None,1) for s in auto_alias]
783 783
784 784 # Produce a public API instance
785 785 self.api = IPython.ipapi.IPApi(self)
786 786
787 787 # Initialize all user-visible namespaces
788 788 self.init_namespaces()
789 789
790 790 # Call the actual (public) initializer
791 791 self.init_auto_alias()
792 792
793 793 # track which builtins we add, so we can clean up later
794 794 self.builtins_added = {}
795 795 # This method will add the necessary builtins for operation, but
796 796 # tracking what it did via the builtins_added dict.
797 797
798 798 #TODO: remove this, redundant
799 799 self.add_builtins()
800 800 # end __init__
801 801
802 802 def var_expand(self,cmd,depth=0):
803 803 """Expand python variables in a string.
804 804
805 805 The depth argument indicates how many frames above the caller should
806 806 be walked to look for the local namespace where to expand variables.
807 807
808 808 The global namespace for expansion is always the user's interactive
809 809 namespace.
810 810 """
811 811
812 812 return str(ItplNS(cmd,
813 813 self.user_ns, # globals
814 814 # Skip our own frame in searching for locals:
815 815 sys._getframe(depth+1).f_locals # locals
816 816 ))
817 817
818 818 def pre_config_initialization(self):
819 819 """Pre-configuration init method
820 820
821 821 This is called before the configuration files are processed to
822 822 prepare the services the config files might need.
823 823
824 824 self.rc already has reasonable default values at this point.
825 825 """
826 826 rc = self.rc
827 827 try:
828 828 self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
829 829 except exceptions.UnicodeDecodeError:
830 830 print "Your ipythondir can't be decoded to unicode!"
831 831 print "Please set HOME environment variable to something that"
832 832 print r"only has ASCII characters, e.g. c:\home"
833 833 print "Now it is",rc.ipythondir
834 834 sys.exit()
835 835 self.shadowhist = IPython.history.ShadowHist(self.db)
836 836
837 837 def post_config_initialization(self):
838 838 """Post configuration init method
839 839
840 840 This is called after the configuration files have been processed to
841 841 'finalize' the initialization."""
842 842
843 843 rc = self.rc
844 844
845 845 # Object inspector
846 846 self.inspector = OInspect.Inspector(OInspect.InspectColors,
847 847 PyColorize.ANSICodeColors,
848 848 'NoColor',
849 849 rc.object_info_string_level)
850 850
851 851 self.rl_next_input = None
852 852 self.rl_do_indent = False
853 853 # Load readline proper
854 854 if rc.readline:
855 855 self.init_readline()
856 856
857 857 # local shortcut, this is used a LOT
858 858 self.log = self.logger.log
859 859
860 860 # Initialize cache, set in/out prompts and printing system
861 861 self.outputcache = CachedOutput(self,
862 862 rc.cache_size,
863 863 rc.pprint,
864 864 input_sep = rc.separate_in,
865 865 output_sep = rc.separate_out,
866 866 output_sep2 = rc.separate_out2,
867 867 ps1 = rc.prompt_in1,
868 868 ps2 = rc.prompt_in2,
869 869 ps_out = rc.prompt_out,
870 870 pad_left = rc.prompts_pad_left)
871 871
872 872 # user may have over-ridden the default print hook:
873 873 try:
874 874 self.outputcache.__class__.display = self.hooks.display
875 875 except AttributeError:
876 876 pass
877 877
878 878 # I don't like assigning globally to sys, because it means when
879 879 # embedding instances, each embedded instance overrides the previous
880 880 # choice. But sys.displayhook seems to be called internally by exec,
881 881 # so I don't see a way around it. We first save the original and then
882 882 # overwrite it.
883 883 self.sys_displayhook = sys.displayhook
884 884 sys.displayhook = self.outputcache
885 885
886 886 # Do a proper resetting of doctest, including the necessary displayhook
887 887 # monkeypatching
888 888 try:
889 889 doctest_reload()
890 890 except ImportError:
891 891 warn("doctest module does not exist.")
892 892
893 893 # Set user colors (don't do it in the constructor above so that it
894 894 # doesn't crash if colors option is invalid)
895 895 self.magic_colors(rc.colors)
896 896
897 897 # Set calling of pdb on exceptions
898 898 self.call_pdb = rc.pdb
899 899
900 900 # Load user aliases
901 901 for alias in rc.alias:
902 902 self.magic_alias(alias)
903 903
904 904 self.hooks.late_startup_hook()
905 905
906 906 for cmd in self.rc.autoexec:
907 907 #print "autoexec>",cmd #dbg
908 908 self.api.runlines(cmd)
909 909
910 910 batchrun = False
911 911 for batchfile in [path(arg) for arg in self.rc.args
912 912 if arg.lower().endswith('.ipy')]:
913 913 if not batchfile.isfile():
914 914 print "No such batch file:", batchfile
915 915 continue
916 916 self.api.runlines(batchfile.text())
917 917 batchrun = True
918 918 # without -i option, exit after running the batch file
919 919 if batchrun and not self.rc.interact:
920 920 self.ask_exit()
921 921
922 922 def init_namespaces(self):
923 923 """Initialize all user-visible namespaces to their minimum defaults.
924 924
925 925 Certain history lists are also initialized here, as they effectively
926 926 act as user namespaces.
927 927
928 928 Note
929 929 ----
930 930 All data structures here are only filled in, they are NOT reset by this
931 931 method. If they were not empty before, data will simply be added to
932 932 therm.
933 933 """
934 934 # The user namespace MUST have a pointer to the shell itself.
935 935 self.user_ns[self.name] = self
936 936
937 937 # Store the public api instance
938 938 self.user_ns['_ip'] = self.api
939 939
940 940 # make global variables for user access to the histories
941 941 self.user_ns['_ih'] = self.input_hist
942 942 self.user_ns['_oh'] = self.output_hist
943 943 self.user_ns['_dh'] = self.dir_hist
944 944
945 945 # user aliases to input and output histories
946 946 self.user_ns['In'] = self.input_hist
947 947 self.user_ns['Out'] = self.output_hist
948 948
949 949 self.user_ns['_sh'] = IPython.shadowns
950 950
951 951 # Fill the history zero entry, user counter starts at 1
952 952 self.input_hist.append('\n')
953 953 self.input_hist_raw.append('\n')
954 954
955 955 def add_builtins(self):
956 956 """Store ipython references into the builtin namespace.
957 957
958 958 Some parts of ipython operate via builtins injected here, which hold a
959 959 reference to IPython itself."""
960 960
961 961 # TODO: deprecate all of these, they are unsafe
962 962 builtins_new = dict(__IPYTHON__ = self,
963 963 ip_set_hook = self.set_hook,
964 964 jobs = self.jobs,
965 965 ipmagic = wrap_deprecated(self.ipmagic,'_ip.magic()'),
966 966 ipalias = wrap_deprecated(self.ipalias),
967 967 ipsystem = wrap_deprecated(self.ipsystem,'_ip.system()'),
968 968 #_ip = self.api
969 969 )
970 970 for biname,bival in builtins_new.items():
971 971 try:
972 972 # store the orignal value so we can restore it
973 973 self.builtins_added[biname] = __builtin__.__dict__[biname]
974 974 except KeyError:
975 975 # or mark that it wasn't defined, and we'll just delete it at
976 976 # cleanup
977 977 self.builtins_added[biname] = Undefined
978 978 __builtin__.__dict__[biname] = bival
979 979
980 980 # Keep in the builtins a flag for when IPython is active. We set it
981 981 # with setdefault so that multiple nested IPythons don't clobber one
982 982 # another. Each will increase its value by one upon being activated,
983 983 # which also gives us a way to determine the nesting level.
984 984 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
985 985
986 986 def clean_builtins(self):
987 987 """Remove any builtins which might have been added by add_builtins, or
988 988 restore overwritten ones to their previous values."""
989 989 for biname,bival in self.builtins_added.items():
990 990 if bival is Undefined:
991 991 del __builtin__.__dict__[biname]
992 992 else:
993 993 __builtin__.__dict__[biname] = bival
994 994 self.builtins_added.clear()
995 995
996 996 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
997 997 """set_hook(name,hook) -> sets an internal IPython hook.
998 998
999 999 IPython exposes some of its internal API as user-modifiable hooks. By
1000 1000 adding your function to one of these hooks, you can modify IPython's
1001 1001 behavior to call at runtime your own routines."""
1002 1002
1003 1003 # At some point in the future, this should validate the hook before it
1004 1004 # accepts it. Probably at least check that the hook takes the number
1005 1005 # of args it's supposed to.
1006 1006
1007 1007 f = new.instancemethod(hook,self,self.__class__)
1008 1008
1009 1009 # check if the hook is for strdispatcher first
1010 1010 if str_key is not None:
1011 1011 sdp = self.strdispatchers.get(name, StrDispatch())
1012 1012 sdp.add_s(str_key, f, priority )
1013 1013 self.strdispatchers[name] = sdp
1014 1014 return
1015 1015 if re_key is not None:
1016 1016 sdp = self.strdispatchers.get(name, StrDispatch())
1017 1017 sdp.add_re(re.compile(re_key), f, priority )
1018 1018 self.strdispatchers[name] = sdp
1019 1019 return
1020 1020
1021 1021 dp = getattr(self.hooks, name, None)
1022 1022 if name not in IPython.hooks.__all__:
1023 1023 print "Warning! Hook '%s' is not one of %s" % (name, IPython.hooks.__all__ )
1024 1024 if not dp:
1025 1025 dp = IPython.hooks.CommandChainDispatcher()
1026 1026
1027 1027 try:
1028 1028 dp.add(f,priority)
1029 1029 except AttributeError:
1030 1030 # it was not commandchain, plain old func - replace
1031 1031 dp = f
1032 1032
1033 1033 setattr(self.hooks,name, dp)
1034 1034
1035 1035
1036 1036 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
1037 1037
1038 1038 def set_crash_handler(self,crashHandler):
1039 1039 """Set the IPython crash handler.
1040 1040
1041 1041 This must be a callable with a signature suitable for use as
1042 1042 sys.excepthook."""
1043 1043
1044 1044 # Install the given crash handler as the Python exception hook
1045 1045 sys.excepthook = crashHandler
1046 1046
1047 1047 # The instance will store a pointer to this, so that runtime code
1048 1048 # (such as magics) can access it. This is because during the
1049 1049 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1050 1050 # frameworks).
1051 1051 self.sys_excepthook = sys.excepthook
1052 1052
1053 1053
1054 1054 def set_custom_exc(self,exc_tuple,handler):
1055 1055 """set_custom_exc(exc_tuple,handler)
1056 1056
1057 1057 Set a custom exception handler, which will be called if any of the
1058 1058 exceptions in exc_tuple occur in the mainloop (specifically, in the
1059 1059 runcode() method.
1060 1060
1061 1061 Inputs:
1062 1062
1063 1063 - exc_tuple: a *tuple* of valid exceptions to call the defined
1064 1064 handler for. It is very important that you use a tuple, and NOT A
1065 1065 LIST here, because of the way Python's except statement works. If
1066 1066 you only want to trap a single exception, use a singleton tuple:
1067 1067
1068 1068 exc_tuple == (MyCustomException,)
1069 1069
1070 1070 - handler: this must be defined as a function with the following
1071 1071 basic interface: def my_handler(self,etype,value,tb).
1072 1072
1073 1073 This will be made into an instance method (via new.instancemethod)
1074 1074 of IPython itself, and it will be called if any of the exceptions
1075 1075 listed in the exc_tuple are caught. If the handler is None, an
1076 1076 internal basic one is used, which just prints basic info.
1077 1077
1078 1078 WARNING: by putting in your own exception handler into IPython's main
1079 1079 execution loop, you run a very good chance of nasty crashes. This
1080 1080 facility should only be used if you really know what you are doing."""
1081 1081
1082 1082 assert type(exc_tuple)==type(()) , \
1083 1083 "The custom exceptions must be given AS A TUPLE."
1084 1084
1085 1085 def dummy_handler(self,etype,value,tb):
1086 1086 print '*** Simple custom exception handler ***'
1087 1087 print 'Exception type :',etype
1088 1088 print 'Exception value:',value
1089 1089 print 'Traceback :',tb
1090 1090 print 'Source code :','\n'.join(self.buffer)
1091 1091
1092 1092 if handler is None: handler = dummy_handler
1093 1093
1094 1094 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1095 1095 self.custom_exceptions = exc_tuple
1096 1096
1097 1097 def set_custom_completer(self,completer,pos=0):
1098 1098 """set_custom_completer(completer,pos=0)
1099 1099
1100 1100 Adds a new custom completer function.
1101 1101
1102 1102 The position argument (defaults to 0) is the index in the completers
1103 1103 list where you want the completer to be inserted."""
1104 1104
1105 1105 newcomp = new.instancemethod(completer,self.Completer,
1106 1106 self.Completer.__class__)
1107 1107 self.Completer.matchers.insert(pos,newcomp)
1108 1108
1109 1109 def set_completer(self):
1110 1110 """reset readline's completer to be our own."""
1111 1111 self.readline.set_completer(self.Completer.complete)
1112 1112
1113 1113 def _get_call_pdb(self):
1114 1114 return self._call_pdb
1115 1115
1116 1116 def _set_call_pdb(self,val):
1117 1117
1118 1118 if val not in (0,1,False,True):
1119 1119 raise ValueError,'new call_pdb value must be boolean'
1120 1120
1121 1121 # store value in instance
1122 1122 self._call_pdb = val
1123 1123
1124 1124 # notify the actual exception handlers
1125 1125 self.InteractiveTB.call_pdb = val
1126 1126 if self.isthreaded:
1127 1127 try:
1128 1128 self.sys_excepthook.call_pdb = val
1129 1129 except:
1130 1130 warn('Failed to activate pdb for threaded exception handler')
1131 1131
1132 1132 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
1133 1133 'Control auto-activation of pdb at exceptions')
1134 1134
1135 1135 # These special functions get installed in the builtin namespace, to
1136 1136 # provide programmatic (pure python) access to magics, aliases and system
1137 1137 # calls. This is important for logging, user scripting, and more.
1138 1138
1139 1139 # We are basically exposing, via normal python functions, the three
1140 1140 # mechanisms in which ipython offers special call modes (magics for
1141 1141 # internal control, aliases for direct system access via pre-selected
1142 1142 # names, and !cmd for calling arbitrary system commands).
1143 1143
1144 1144 def ipmagic(self,arg_s):
1145 1145 """Call a magic function by name.
1146 1146
1147 1147 Input: a string containing the name of the magic function to call and any
1148 1148 additional arguments to be passed to the magic.
1149 1149
1150 1150 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
1151 1151 prompt:
1152 1152
1153 1153 In[1]: %name -opt foo bar
1154 1154
1155 1155 To call a magic without arguments, simply use ipmagic('name').
1156 1156
1157 1157 This provides a proper Python function to call IPython's magics in any
1158 1158 valid Python code you can type at the interpreter, including loops and
1159 1159 compound statements. It is added by IPython to the Python builtin
1160 1160 namespace upon initialization."""
1161 1161
1162 1162 args = arg_s.split(' ',1)
1163 1163 magic_name = args[0]
1164 1164 magic_name = magic_name.lstrip(self.ESC_MAGIC)
1165 1165
1166 1166 try:
1167 1167 magic_args = args[1]
1168 1168 except IndexError:
1169 1169 magic_args = ''
1170 1170 fn = getattr(self,'magic_'+magic_name,None)
1171 1171 if fn is None:
1172 1172 error("Magic function `%s` not found." % magic_name)
1173 1173 else:
1174 1174 magic_args = self.var_expand(magic_args,1)
1175 1175 return fn(magic_args)
1176 1176
1177 1177 def ipalias(self,arg_s):
1178 1178 """Call an alias by name.
1179 1179
1180 1180 Input: a string containing the name of the alias to call and any
1181 1181 additional arguments to be passed to the magic.
1182 1182
1183 1183 ipalias('name -opt foo bar') is equivalent to typing at the ipython
1184 1184 prompt:
1185 1185
1186 1186 In[1]: name -opt foo bar
1187 1187
1188 1188 To call an alias without arguments, simply use ipalias('name').
1189 1189
1190 1190 This provides a proper Python function to call IPython's aliases in any
1191 1191 valid Python code you can type at the interpreter, including loops and
1192 1192 compound statements. It is added by IPython to the Python builtin
1193 1193 namespace upon initialization."""
1194 1194
1195 1195 args = arg_s.split(' ',1)
1196 1196 alias_name = args[0]
1197 1197 try:
1198 1198 alias_args = args[1]
1199 1199 except IndexError:
1200 1200 alias_args = ''
1201 1201 if alias_name in self.alias_table:
1202 1202 self.call_alias(alias_name,alias_args)
1203 1203 else:
1204 1204 error("Alias `%s` not found." % alias_name)
1205 1205
1206 1206 def ipsystem(self,arg_s):
1207 1207 """Make a system call, using IPython."""
1208 1208
1209 1209 self.system(arg_s)
1210 1210
1211 1211 def complete(self,text):
1212 1212 """Return a sorted list of all possible completions on text.
1213 1213
1214 1214 Inputs:
1215 1215
1216 1216 - text: a string of text to be completed on.
1217 1217
1218 1218 This is a wrapper around the completion mechanism, similar to what
1219 1219 readline does at the command line when the TAB key is hit. By
1220 1220 exposing it as a method, it can be used by other non-readline
1221 1221 environments (such as GUIs) for text completion.
1222 1222
1223 1223 Simple usage example:
1224 1224
1225 1225 In [7]: x = 'hello'
1226 1226
1227 1227 In [8]: x
1228 1228 Out[8]: 'hello'
1229 1229
1230 1230 In [9]: print x
1231 1231 hello
1232 1232
1233 1233 In [10]: _ip.IP.complete('x.l')
1234 1234 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1235 1235 """
1236 1236
1237 1237 complete = self.Completer.complete
1238 1238 state = 0
1239 1239 # use a dict so we get unique keys, since ipyhton's multiple
1240 1240 # completers can return duplicates. When we make 2.4 a requirement,
1241 1241 # start using sets instead, which are faster.
1242 1242 comps = {}
1243 1243 while True:
1244 1244 newcomp = complete(text,state,line_buffer=text)
1245 1245 if newcomp is None:
1246 1246 break
1247 1247 comps[newcomp] = 1
1248 1248 state += 1
1249 1249 outcomps = comps.keys()
1250 1250 outcomps.sort()
1251 1251 #print "T:",text,"OC:",outcomps # dbg
1252 1252 #print "vars:",self.user_ns.keys()
1253 1253 return outcomps
1254 1254
1255 1255 def set_completer_frame(self, frame=None):
1256 1256 if frame:
1257 1257 self.Completer.namespace = frame.f_locals
1258 1258 self.Completer.global_namespace = frame.f_globals
1259 1259 else:
1260 1260 self.Completer.namespace = self.user_ns
1261 1261 self.Completer.global_namespace = self.user_global_ns
1262 1262
1263 1263 def init_auto_alias(self):
1264 1264 """Define some aliases automatically.
1265 1265
1266 1266 These are ALL parameter-less aliases"""
1267 1267
1268 1268 for alias,cmd in self.auto_alias:
1269 1269 self.getapi().defalias(alias,cmd)
1270 1270
1271 1271
1272 1272 def alias_table_validate(self,verbose=0):
1273 1273 """Update information about the alias table.
1274 1274
1275 1275 In particular, make sure no Python keywords/builtins are in it."""
1276 1276
1277 1277 no_alias = self.no_alias
1278 1278 for k in self.alias_table.keys():
1279 1279 if k in no_alias:
1280 1280 del self.alias_table[k]
1281 1281 if verbose:
1282 1282 print ("Deleting alias <%s>, it's a Python "
1283 1283 "keyword or builtin." % k)
1284 1284
1285 1285 def set_autoindent(self,value=None):
1286 1286 """Set the autoindent flag, checking for readline support.
1287 1287
1288 1288 If called with no arguments, it acts as a toggle."""
1289 1289
1290 1290 if not self.has_readline:
1291 1291 if os.name == 'posix':
1292 1292 warn("The auto-indent feature requires the readline library")
1293 1293 self.autoindent = 0
1294 1294 return
1295 1295 if value is None:
1296 1296 self.autoindent = not self.autoindent
1297 1297 else:
1298 1298 self.autoindent = value
1299 1299
1300 1300 def rc_set_toggle(self,rc_field,value=None):
1301 1301 """Set or toggle a field in IPython's rc config. structure.
1302 1302
1303 1303 If called with no arguments, it acts as a toggle.
1304 1304
1305 1305 If called with a non-existent field, the resulting AttributeError
1306 1306 exception will propagate out."""
1307 1307
1308 1308 rc_val = getattr(self.rc,rc_field)
1309 1309 if value is None:
1310 1310 value = not rc_val
1311 1311 setattr(self.rc,rc_field,value)
1312 1312
1313 1313 def user_setup(self,ipythondir,rc_suffix,mode='install'):
1314 1314 """Install the user configuration directory.
1315 1315
1316 1316 Note
1317 1317 ----
1318 1318 DEPRECATED: use the top-level user_setup() function instead.
1319 1319 """
1320 1320 return user_setup(ipythondir,rc_suffix,mode)
1321 1321
1322 1322 def atexit_operations(self):
1323 1323 """This will be executed at the time of exit.
1324 1324
1325 1325 Saving of persistent data should be performed here. """
1326 1326
1327 1327 #print '*** IPython exit cleanup ***' # dbg
1328 1328 # input history
1329 1329 self.savehist()
1330 1330
1331 1331 # Cleanup all tempfiles left around
1332 1332 for tfile in self.tempfiles:
1333 1333 try:
1334 1334 os.unlink(tfile)
1335 1335 except OSError:
1336 1336 pass
1337 1337
1338 1338 # Clear all user namespaces to release all references cleanly.
1339 1339 self.reset()
1340 1340
1341 1341 # Run user hooks
1342 1342 self.hooks.shutdown_hook()
1343 1343
1344 1344 def reset(self):
1345 1345 """Clear all internal namespaces.
1346 1346
1347 1347 Note that this is much more aggressive than %reset, since it clears
1348 1348 fully all namespaces, as well as all input/output lists.
1349 1349 """
1350 1350 for ns in self.ns_refs_table:
1351 1351 ns.clear()
1352 1352
1353 1353 # Clear input and output histories
1354 1354 self.input_hist[:] = []
1355 1355 self.input_hist_raw[:] = []
1356 1356 self.output_hist.clear()
1357 1357 # Restore the user namespaces to minimal usability
1358 1358 self.init_namespaces()
1359 1359
1360 1360 def savehist(self):
1361 1361 """Save input history to a file (via readline library)."""
1362 1362
1363 1363 if not self.has_readline:
1364 1364 return
1365 1365
1366 1366 try:
1367 1367 self.readline.write_history_file(self.histfile)
1368 1368 except:
1369 1369 print 'Unable to save IPython command history to file: ' + \
1370 1370 `self.histfile`
1371 1371
1372 1372 def reloadhist(self):
1373 1373 """Reload the input history from disk file."""
1374 1374
1375 1375 if self.has_readline:
1376 1376 try:
1377 1377 self.readline.clear_history()
1378 1378 self.readline.read_history_file(self.shell.histfile)
1379 1379 except AttributeError:
1380 1380 pass
1381 1381
1382 1382
1383 1383 def history_saving_wrapper(self, func):
1384 1384 """ Wrap func for readline history saving
1385 1385
1386 1386 Convert func into callable that saves & restores
1387 1387 history around the call """
1388 1388
1389 1389 if not self.has_readline:
1390 1390 return func
1391 1391
1392 1392 def wrapper():
1393 1393 self.savehist()
1394 1394 try:
1395 1395 func()
1396 1396 finally:
1397 1397 readline.read_history_file(self.histfile)
1398 1398 return wrapper
1399 1399
1400 1400 def pre_readline(self):
1401 1401 """readline hook to be used at the start of each line.
1402 1402
1403 1403 Currently it handles auto-indent only."""
1404 1404
1405 1405 #debugx('self.indent_current_nsp','pre_readline:')
1406 1406
1407 1407 if self.rl_do_indent:
1408 1408 self.readline.insert_text(self.indent_current_str())
1409 1409 if self.rl_next_input is not None:
1410 1410 self.readline.insert_text(self.rl_next_input)
1411 1411 self.rl_next_input = None
1412 1412
1413 1413 def init_readline(self):
1414 1414 """Command history completion/saving/reloading."""
1415 1415
1416 1416
1417 1417 import IPython.rlineimpl as readline
1418 1418
1419 1419 if not readline.have_readline:
1420 1420 self.has_readline = 0
1421 1421 self.readline = None
1422 1422 # no point in bugging windows users with this every time:
1423 1423 warn('Readline services not available on this platform.')
1424 1424 else:
1425 1425 sys.modules['readline'] = readline
1426 1426 import atexit
1427 1427 from IPython.core.completer import IPCompleter
1428 1428 self.Completer = IPCompleter(self,
1429 1429 self.user_ns,
1430 1430 self.user_global_ns,
1431 1431 self.rc.readline_omit__names,
1432 1432 self.alias_table)
1433 1433 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1434 1434 self.strdispatchers['complete_command'] = sdisp
1435 1435 self.Completer.custom_completers = sdisp
1436 1436 # Platform-specific configuration
1437 1437 if os.name == 'nt':
1438 1438 self.readline_startup_hook = readline.set_pre_input_hook
1439 1439 else:
1440 1440 self.readline_startup_hook = readline.set_startup_hook
1441 1441
1442 1442 # Load user's initrc file (readline config)
1443 1443 # Or if libedit is used, load editrc.
1444 1444 inputrc_name = os.environ.get('INPUTRC')
1445 1445 if inputrc_name is None:
1446 1446 home_dir = get_home_dir()
1447 1447 if home_dir is not None:
1448 1448 inputrc_name = '.inputrc'
1449 1449 if readline.uses_libedit:
1450 1450 inputrc_name = '.editrc'
1451 1451 inputrc_name = os.path.join(home_dir, inputrc_name)
1452 1452 if os.path.isfile(inputrc_name):
1453 1453 try:
1454 1454 readline.read_init_file(inputrc_name)
1455 1455 except:
1456 1456 warn('Problems reading readline initialization file <%s>'
1457 1457 % inputrc_name)
1458 1458
1459 1459 self.has_readline = 1
1460 1460 self.readline = readline
1461 1461 # save this in sys so embedded copies can restore it properly
1462 1462 sys.ipcompleter = self.Completer.complete
1463 1463 self.set_completer()
1464 1464
1465 1465 # Configure readline according to user's prefs
1466 1466 # This is only done if GNU readline is being used. If libedit
1467 1467 # is being used (as on Leopard) the readline config is
1468 1468 # not run as the syntax for libedit is different.
1469 1469 if not readline.uses_libedit:
1470 1470 for rlcommand in self.rc.readline_parse_and_bind:
1471 1471 #print "loading rl:",rlcommand # dbg
1472 1472 readline.parse_and_bind(rlcommand)
1473 1473
1474 1474 # Remove some chars from the delimiters list. If we encounter
1475 1475 # unicode chars, discard them.
1476 1476 delims = readline.get_completer_delims().encode("ascii", "ignore")
1477 1477 delims = delims.translate(string._idmap,
1478 1478 self.rc.readline_remove_delims)
1479 1479 readline.set_completer_delims(delims)
1480 1480 # otherwise we end up with a monster history after a while:
1481 1481 readline.set_history_length(1000)
1482 1482 try:
1483 1483 #print '*** Reading readline history' # dbg
1484 1484 readline.read_history_file(self.histfile)
1485 1485 except IOError:
1486 1486 pass # It doesn't exist yet.
1487 1487
1488 1488 atexit.register(self.atexit_operations)
1489 1489 del atexit
1490 1490
1491 1491 # Configure auto-indent for all platforms
1492 1492 self.set_autoindent(self.rc.autoindent)
1493 1493
1494 1494 def ask_yes_no(self,prompt,default=True):
1495 1495 if self.rc.quiet:
1496 1496 return True
1497 1497 return ask_yes_no(prompt,default)
1498 1498
1499 1499 def new_main_mod(self,ns=None):
1500 1500 """Return a new 'main' module object for user code execution.
1501 1501 """
1502 1502 main_mod = self._user_main_module
1503 1503 init_fakemod_dict(main_mod,ns)
1504 1504 return main_mod
1505 1505
1506 1506 def cache_main_mod(self,ns,fname):
1507 1507 """Cache a main module's namespace.
1508 1508
1509 1509 When scripts are executed via %run, we must keep a reference to the
1510 1510 namespace of their __main__ module (a FakeModule instance) around so
1511 1511 that Python doesn't clear it, rendering objects defined therein
1512 1512 useless.
1513 1513
1514 1514 This method keeps said reference in a private dict, keyed by the
1515 1515 absolute path of the module object (which corresponds to the script
1516 1516 path). This way, for multiple executions of the same script we only
1517 1517 keep one copy of the namespace (the last one), thus preventing memory
1518 1518 leaks from old references while allowing the objects from the last
1519 1519 execution to be accessible.
1520 1520
1521 1521 Note: we can not allow the actual FakeModule instances to be deleted,
1522 1522 because of how Python tears down modules (it hard-sets all their
1523 1523 references to None without regard for reference counts). This method
1524 1524 must therefore make a *copy* of the given namespace, to allow the
1525 1525 original module's __dict__ to be cleared and reused.
1526 1526
1527 1527
1528 1528 Parameters
1529 1529 ----------
1530 1530 ns : a namespace (a dict, typically)
1531 1531
1532 1532 fname : str
1533 1533 Filename associated with the namespace.
1534 1534
1535 1535 Examples
1536 1536 --------
1537 1537
1538 1538 In [10]: import IPython
1539 1539
1540 1540 In [11]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1541 1541
1542 1542 In [12]: IPython.__file__ in _ip.IP._main_ns_cache
1543 1543 Out[12]: True
1544 1544 """
1545 1545 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
1546 1546
1547 1547 def clear_main_mod_cache(self):
1548 1548 """Clear the cache of main modules.
1549 1549
1550 1550 Mainly for use by utilities like %reset.
1551 1551
1552 1552 Examples
1553 1553 --------
1554 1554
1555 1555 In [15]: import IPython
1556 1556
1557 1557 In [16]: _ip.IP.cache_main_mod(IPython.__dict__,IPython.__file__)
1558 1558
1559 1559 In [17]: len(_ip.IP._main_ns_cache) > 0
1560 1560 Out[17]: True
1561 1561
1562 1562 In [18]: _ip.IP.clear_main_mod_cache()
1563 1563
1564 1564 In [19]: len(_ip.IP._main_ns_cache) == 0
1565 1565 Out[19]: True
1566 1566 """
1567 1567 self._main_ns_cache.clear()
1568 1568
1569 1569 def _should_recompile(self,e):
1570 1570 """Utility routine for edit_syntax_error"""
1571 1571
1572 1572 if e.filename in ('<ipython console>','<input>','<string>',
1573 1573 '<console>','<BackgroundJob compilation>',
1574 1574 None):
1575 1575
1576 1576 return False
1577 1577 try:
1578 1578 if (self.rc.autoedit_syntax and
1579 1579 not self.ask_yes_no('Return to editor to correct syntax error? '
1580 1580 '[Y/n] ','y')):
1581 1581 return False
1582 1582 except EOFError:
1583 1583 return False
1584 1584
1585 1585 def int0(x):
1586 1586 try:
1587 1587 return int(x)
1588 1588 except TypeError:
1589 1589 return 0
1590 1590 # always pass integer line and offset values to editor hook
1591 1591 try:
1592 1592 self.hooks.fix_error_editor(e.filename,
1593 1593 int0(e.lineno),int0(e.offset),e.msg)
1594 1594 except IPython.ipapi.TryNext:
1595 1595 warn('Could not open editor')
1596 1596 return False
1597 1597 return True
1598 1598
1599 1599 def edit_syntax_error(self):
1600 1600 """The bottom half of the syntax error handler called in the main loop.
1601 1601
1602 1602 Loop until syntax error is fixed or user cancels.
1603 1603 """
1604 1604
1605 1605 while self.SyntaxTB.last_syntax_error:
1606 1606 # copy and clear last_syntax_error
1607 1607 err = self.SyntaxTB.clear_err_state()
1608 1608 if not self._should_recompile(err):
1609 1609 return
1610 1610 try:
1611 1611 # may set last_syntax_error again if a SyntaxError is raised
1612 1612 self.safe_execfile(err.filename,self.user_ns)
1613 1613 except:
1614 1614 self.showtraceback()
1615 1615 else:
1616 1616 try:
1617 1617 f = file(err.filename)
1618 1618 try:
1619 1619 sys.displayhook(f.read())
1620 1620 finally:
1621 1621 f.close()
1622 1622 except:
1623 1623 self.showtraceback()
1624 1624
1625 1625 def showsyntaxerror(self, filename=None):
1626 1626 """Display the syntax error that just occurred.
1627 1627
1628 1628 This doesn't display a stack trace because there isn't one.
1629 1629
1630 1630 If a filename is given, it is stuffed in the exception instead
1631 1631 of what was there before (because Python's parser always uses
1632 1632 "<string>" when reading from a string).
1633 1633 """
1634 1634 etype, value, last_traceback = sys.exc_info()
1635 1635
1636 1636 # See note about these variables in showtraceback() below
1637 1637 sys.last_type = etype
1638 1638 sys.last_value = value
1639 1639 sys.last_traceback = last_traceback
1640 1640
1641 1641 if filename and etype is SyntaxError:
1642 1642 # Work hard to stuff the correct filename in the exception
1643 1643 try:
1644 1644 msg, (dummy_filename, lineno, offset, line) = value
1645 1645 except:
1646 1646 # Not the format we expect; leave it alone
1647 1647 pass
1648 1648 else:
1649 1649 # Stuff in the right filename
1650 1650 try:
1651 1651 # Assume SyntaxError is a class exception
1652 1652 value = SyntaxError(msg, (filename, lineno, offset, line))
1653 1653 except:
1654 1654 # If that failed, assume SyntaxError is a string
1655 1655 value = msg, (filename, lineno, offset, line)
1656 1656 self.SyntaxTB(etype,value,[])
1657 1657
1658 1658 def debugger(self,force=False):
1659 1659 """Call the pydb/pdb debugger.
1660 1660
1661 1661 Keywords:
1662 1662
1663 1663 - force(False): by default, this routine checks the instance call_pdb
1664 1664 flag and does not actually invoke the debugger if the flag is false.
1665 1665 The 'force' option forces the debugger to activate even if the flag
1666 1666 is false.
1667 1667 """
1668 1668
1669 1669 if not (force or self.call_pdb):
1670 1670 return
1671 1671
1672 1672 if not hasattr(sys,'last_traceback'):
1673 1673 error('No traceback has been produced, nothing to debug.')
1674 1674 return
1675 1675
1676 1676 # use pydb if available
1677 1677 if debugger.has_pydb:
1678 1678 from pydb import pm
1679 1679 else:
1680 1680 # fallback to our internal debugger
1681 1681 pm = lambda : self.InteractiveTB.debugger(force=True)
1682 1682 self.history_saving_wrapper(pm)()
1683 1683
1684 1684 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1685 1685 """Display the exception that just occurred.
1686 1686
1687 1687 If nothing is known about the exception, this is the method which
1688 1688 should be used throughout the code for presenting user tracebacks,
1689 1689 rather than directly invoking the InteractiveTB object.
1690 1690
1691 1691 A specific showsyntaxerror() also exists, but this method can take
1692 1692 care of calling it if needed, so unless you are explicitly catching a
1693 1693 SyntaxError exception, don't try to analyze the stack manually and
1694 1694 simply call this method."""
1695 1695
1696 1696
1697 1697 # Though this won't be called by syntax errors in the input line,
1698 1698 # there may be SyntaxError cases whith imported code.
1699 1699
1700 1700 try:
1701 1701 if exc_tuple is None:
1702 1702 etype, value, tb = sys.exc_info()
1703 1703 else:
1704 1704 etype, value, tb = exc_tuple
1705 1705
1706 1706 if etype is SyntaxError:
1707 1707 self.showsyntaxerror(filename)
1708 1708 elif etype is IPython.ipapi.UsageError:
1709 1709 print "UsageError:", value
1710 1710 else:
1711 1711 # WARNING: these variables are somewhat deprecated and not
1712 1712 # necessarily safe to use in a threaded environment, but tools
1713 1713 # like pdb depend on their existence, so let's set them. If we
1714 1714 # find problems in the field, we'll need to revisit their use.
1715 1715 sys.last_type = etype
1716 1716 sys.last_value = value
1717 1717 sys.last_traceback = tb
1718 1718
1719 1719 if etype in self.custom_exceptions:
1720 1720 self.CustomTB(etype,value,tb)
1721 1721 else:
1722 1722 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1723 1723 if self.InteractiveTB.call_pdb and self.has_readline:
1724 1724 # pdb mucks up readline, fix it back
1725 1725 self.set_completer()
1726 1726 except KeyboardInterrupt:
1727 1727 self.write("\nKeyboardInterrupt\n")
1728 1728
1729 1729 def mainloop(self,banner=None):
1730 1730 """Creates the local namespace and starts the mainloop.
1731 1731
1732 1732 If an optional banner argument is given, it will override the
1733 1733 internally created default banner."""
1734 1734
1735 1735 if self.rc.c: # Emulate Python's -c option
1736 1736 self.exec_init_cmd()
1737 1737 if banner is None:
1738 1738 if not self.rc.banner:
1739 1739 banner = ''
1740 1740 # banner is string? Use it directly!
1741 1741 elif isinstance(self.rc.banner,basestring):
1742 1742 banner = self.rc.banner
1743 1743 else:
1744 1744 banner = self.BANNER+self.banner2
1745 1745
1746 1746 # if you run stuff with -c <cmd>, raw hist is not updated
1747 1747 # ensure that it's in sync
1748 1748 if len(self.input_hist) != len (self.input_hist_raw):
1749 1749 self.input_hist_raw = InputList(self.input_hist)
1750 1750
1751 1751 while 1:
1752 1752 try:
1753 1753 self.interact(banner)
1754 1754 #self.interact_with_readline()
1755 1755
1756 1756 # XXX for testing of a readline-decoupled repl loop, call
1757 1757 # interact_with_readline above
1758 1758
1759 1759 break
1760 1760 except KeyboardInterrupt:
1761 1761 # this should not be necessary, but KeyboardInterrupt
1762 1762 # handling seems rather unpredictable...
1763 1763 self.write("\nKeyboardInterrupt in interact()\n")
1764 1764
1765 1765 def exec_init_cmd(self):
1766 1766 """Execute a command given at the command line.
1767 1767
1768 1768 This emulates Python's -c option."""
1769 1769
1770 1770 #sys.argv = ['-c']
1771 1771 self.push(self.prefilter(self.rc.c, False))
1772 1772 if not self.rc.interact:
1773 1773 self.ask_exit()
1774 1774
1775 1775 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1776 1776 """Embeds IPython into a running python program.
1777 1777
1778 1778 Input:
1779 1779
1780 1780 - header: An optional header message can be specified.
1781 1781
1782 1782 - local_ns, global_ns: working namespaces. If given as None, the
1783 1783 IPython-initialized one is updated with __main__.__dict__, so that
1784 1784 program variables become visible but user-specific configuration
1785 1785 remains possible.
1786 1786
1787 1787 - stack_depth: specifies how many levels in the stack to go to
1788 1788 looking for namespaces (when local_ns and global_ns are None). This
1789 1789 allows an intermediate caller to make sure that this function gets
1790 1790 the namespace from the intended level in the stack. By default (0)
1791 1791 it will get its locals and globals from the immediate caller.
1792 1792
1793 1793 Warning: it's possible to use this in a program which is being run by
1794 1794 IPython itself (via %run), but some funny things will happen (a few
1795 1795 globals get overwritten). In the future this will be cleaned up, as
1796 1796 there is no fundamental reason why it can't work perfectly."""
1797 1797
1798 1798 # Get locals and globals from caller
1799 1799 if local_ns is None or global_ns is None:
1800 1800 call_frame = sys._getframe(stack_depth).f_back
1801 1801
1802 1802 if local_ns is None:
1803 1803 local_ns = call_frame.f_locals
1804 1804 if global_ns is None:
1805 1805 global_ns = call_frame.f_globals
1806 1806
1807 1807 # Update namespaces and fire up interpreter
1808 1808
1809 1809 # The global one is easy, we can just throw it in
1810 1810 self.user_global_ns = global_ns
1811 1811
1812 1812 # but the user/local one is tricky: ipython needs it to store internal
1813 1813 # data, but we also need the locals. We'll copy locals in the user
1814 1814 # one, but will track what got copied so we can delete them at exit.
1815 1815 # This is so that a later embedded call doesn't see locals from a
1816 1816 # previous call (which most likely existed in a separate scope).
1817 1817 local_varnames = local_ns.keys()
1818 1818 self.user_ns.update(local_ns)
1819 1819 #self.user_ns['local_ns'] = local_ns # dbg
1820 1820
1821 1821 # Patch for global embedding to make sure that things don't overwrite
1822 1822 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1823 1823 # FIXME. Test this a bit more carefully (the if.. is new)
1824 1824 if local_ns is None and global_ns is None:
1825 1825 self.user_global_ns.update(__main__.__dict__)
1826 1826
1827 1827 # make sure the tab-completer has the correct frame information, so it
1828 1828 # actually completes using the frame's locals/globals
1829 1829 self.set_completer_frame()
1830 1830
1831 1831 # before activating the interactive mode, we need to make sure that
1832 1832 # all names in the builtin namespace needed by ipython point to
1833 1833 # ourselves, and not to other instances.
1834 1834 self.add_builtins()
1835 1835
1836 1836 self.interact(header)
1837 1837
1838 1838 # now, purge out the user namespace from anything we might have added
1839 1839 # from the caller's local namespace
1840 1840 delvar = self.user_ns.pop
1841 1841 for var in local_varnames:
1842 1842 delvar(var,None)
1843 1843 # and clean builtins we may have overridden
1844 1844 self.clean_builtins()
1845 1845
1846 1846 def interact_prompt(self):
1847 1847 """ Print the prompt (in read-eval-print loop)
1848 1848
1849 1849 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1850 1850 used in standard IPython flow.
1851 1851 """
1852 1852 if self.more:
1853 1853 try:
1854 1854 prompt = self.hooks.generate_prompt(True)
1855 1855 except:
1856 1856 self.showtraceback()
1857 1857 if self.autoindent:
1858 1858 self.rl_do_indent = True
1859 1859
1860 1860 else:
1861 1861 try:
1862 1862 prompt = self.hooks.generate_prompt(False)
1863 1863 except:
1864 1864 self.showtraceback()
1865 1865 self.write(prompt)
1866 1866
1867 1867 def interact_handle_input(self,line):
1868 1868 """ Handle the input line (in read-eval-print loop)
1869 1869
1870 1870 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1871 1871 used in standard IPython flow.
1872 1872 """
1873 1873 if line.lstrip() == line:
1874 1874 self.shadowhist.add(line.strip())
1875 1875 lineout = self.prefilter(line,self.more)
1876 1876
1877 1877 if line.strip():
1878 1878 if self.more:
1879 1879 self.input_hist_raw[-1] += '%s\n' % line
1880 1880 else:
1881 1881 self.input_hist_raw.append('%s\n' % line)
1882 1882
1883 1883
1884 1884 self.more = self.push(lineout)
1885 1885 if (self.SyntaxTB.last_syntax_error and
1886 1886 self.rc.autoedit_syntax):
1887 1887 self.edit_syntax_error()
1888 1888
1889 1889 def interact_with_readline(self):
1890 1890 """ Demo of using interact_handle_input, interact_prompt
1891 1891
1892 1892 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1893 1893 it should work like this.
1894 1894 """
1895 1895 self.readline_startup_hook(self.pre_readline)
1896 1896 while not self.exit_now:
1897 1897 self.interact_prompt()
1898 1898 if self.more:
1899 1899 self.rl_do_indent = True
1900 1900 else:
1901 1901 self.rl_do_indent = False
1902 1902 line = raw_input_original().decode(self.stdin_encoding)
1903 1903 self.interact_handle_input(line)
1904 1904
1905 1905
1906 1906 def interact(self, banner=None):
1907 1907 """Closely emulate the interactive Python console.
1908 1908
1909 1909 The optional banner argument specify the banner to print
1910 1910 before the first interaction; by default it prints a banner
1911 1911 similar to the one printed by the real Python interpreter,
1912 1912 followed by the current class name in parentheses (so as not
1913 1913 to confuse this with the real interpreter -- since it's so
1914 1914 close!).
1915 1915
1916 1916 """
1917 1917
1918 1918 if self.exit_now:
1919 1919 # batch run -> do not interact
1920 1920 return
1921 1921 cprt = 'Type "copyright", "credits" or "license" for more information.'
1922 1922 if banner is None:
1923 1923 self.write("Python %s on %s\n%s\n(%s)\n" %
1924 1924 (sys.version, sys.platform, cprt,
1925 1925 self.__class__.__name__))
1926 1926 else:
1927 1927 self.write(banner)
1928 1928
1929 1929 more = 0
1930 1930
1931 1931 # Mark activity in the builtins
1932 1932 __builtin__.__dict__['__IPYTHON__active'] += 1
1933 1933
1934 1934 if self.has_readline:
1935 1935 self.readline_startup_hook(self.pre_readline)
1936 1936 # exit_now is set by a call to %Exit or %Quit, through the
1937 1937 # ask_exit callback.
1938 1938
1939 1939 while not self.exit_now:
1940 1940 self.hooks.pre_prompt_hook()
1941 1941 if more:
1942 1942 try:
1943 1943 prompt = self.hooks.generate_prompt(True)
1944 1944 except:
1945 1945 self.showtraceback()
1946 1946 if self.autoindent:
1947 1947 self.rl_do_indent = True
1948 1948
1949 1949 else:
1950 1950 try:
1951 1951 prompt = self.hooks.generate_prompt(False)
1952 1952 except:
1953 1953 self.showtraceback()
1954 1954 try:
1955 1955 line = self.raw_input(prompt,more)
1956 1956 if self.exit_now:
1957 1957 # quick exit on sys.std[in|out] close
1958 1958 break
1959 1959 if self.autoindent:
1960 1960 self.rl_do_indent = False
1961 1961
1962 1962 except KeyboardInterrupt:
1963 1963 #double-guard against keyboardinterrupts during kbdint handling
1964 1964 try:
1965 1965 self.write('\nKeyboardInterrupt\n')
1966 1966 self.resetbuffer()
1967 1967 # keep cache in sync with the prompt counter:
1968 1968 self.outputcache.prompt_count -= 1
1969 1969
1970 1970 if self.autoindent:
1971 1971 self.indent_current_nsp = 0
1972 1972 more = 0
1973 1973 except KeyboardInterrupt:
1974 1974 pass
1975 1975 except EOFError:
1976 1976 if self.autoindent:
1977 1977 self.rl_do_indent = False
1978 1978 self.readline_startup_hook(None)
1979 1979 self.write('\n')
1980 1980 self.exit()
1981 1981 except bdb.BdbQuit:
1982 1982 warn('The Python debugger has exited with a BdbQuit exception.\n'
1983 1983 'Because of how pdb handles the stack, it is impossible\n'
1984 1984 'for IPython to properly format this particular exception.\n'
1985 1985 'IPython will resume normal operation.')
1986 1986 except:
1987 1987 # exceptions here are VERY RARE, but they can be triggered
1988 1988 # asynchronously by signal handlers, for example.
1989 1989 self.showtraceback()
1990 1990 else:
1991 1991 more = self.push(line)
1992 1992 if (self.SyntaxTB.last_syntax_error and
1993 1993 self.rc.autoedit_syntax):
1994 1994 self.edit_syntax_error()
1995 1995
1996 1996 # We are off again...
1997 1997 __builtin__.__dict__['__IPYTHON__active'] -= 1
1998 1998
1999 1999 def excepthook(self, etype, value, tb):
2000 2000 """One more defense for GUI apps that call sys.excepthook.
2001 2001
2002 2002 GUI frameworks like wxPython trap exceptions and call
2003 2003 sys.excepthook themselves. I guess this is a feature that
2004 2004 enables them to keep running after exceptions that would
2005 2005 otherwise kill their mainloop. This is a bother for IPython
2006 2006 which excepts to catch all of the program exceptions with a try:
2007 2007 except: statement.
2008 2008
2009 2009 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
2010 2010 any app directly invokes sys.excepthook, it will look to the user like
2011 2011 IPython crashed. In order to work around this, we can disable the
2012 2012 CrashHandler and replace it with this excepthook instead, which prints a
2013 2013 regular traceback using our InteractiveTB. In this fashion, apps which
2014 2014 call sys.excepthook will generate a regular-looking exception from
2015 2015 IPython, and the CrashHandler will only be triggered by real IPython
2016 2016 crashes.
2017 2017
2018 2018 This hook should be used sparingly, only in places which are not likely
2019 2019 to be true IPython errors.
2020 2020 """
2021 2021 self.showtraceback((etype,value,tb),tb_offset=0)
2022 2022
2023 2023 def expand_aliases(self,fn,rest):
2024 2024 """ Expand multiple levels of aliases:
2025 2025
2026 2026 if:
2027 2027
2028 2028 alias foo bar /tmp
2029 2029 alias baz foo
2030 2030
2031 2031 then:
2032 2032
2033 2033 baz huhhahhei -> bar /tmp huhhahhei
2034 2034
2035 2035 """
2036 2036 line = fn + " " + rest
2037 2037
2038 2038 done = set()
2039 2039 while 1:
2040 2040 pre,fn,rest = prefilter.splitUserInput(line,
2041 2041 prefilter.shell_line_split)
2042 2042 if fn in self.alias_table:
2043 2043 if fn in done:
2044 2044 warn("Cyclic alias definition, repeated '%s'" % fn)
2045 2045 return ""
2046 2046 done.add(fn)
2047 2047
2048 2048 l2 = self.transform_alias(fn,rest)
2049 2049 # dir -> dir
2050 2050 # print "alias",line, "->",l2 #dbg
2051 2051 if l2 == line:
2052 2052 break
2053 2053 # ls -> ls -F should not recurse forever
2054 2054 if l2.split(None,1)[0] == line.split(None,1)[0]:
2055 2055 line = l2
2056 2056 break
2057 2057
2058 2058 line=l2
2059 2059
2060 2060
2061 2061 # print "al expand to",line #dbg
2062 2062 else:
2063 2063 break
2064 2064
2065 2065 return line
2066 2066
2067 2067 def transform_alias(self, alias,rest=''):
2068 2068 """ Transform alias to system command string.
2069 2069 """
2070 2070 trg = self.alias_table[alias]
2071 2071
2072 2072 nargs,cmd = trg
2073 2073 # print trg #dbg
2074 2074 if ' ' in cmd and os.path.isfile(cmd):
2075 2075 cmd = '"%s"' % cmd
2076 2076
2077 2077 # Expand the %l special to be the user's input line
2078 2078 if cmd.find('%l') >= 0:
2079 2079 cmd = cmd.replace('%l',rest)
2080 2080 rest = ''
2081 2081 if nargs==0:
2082 2082 # Simple, argument-less aliases
2083 2083 cmd = '%s %s' % (cmd,rest)
2084 2084 else:
2085 2085 # Handle aliases with positional arguments
2086 2086 args = rest.split(None,nargs)
2087 2087 if len(args)< nargs:
2088 2088 error('Alias <%s> requires %s arguments, %s given.' %
2089 2089 (alias,nargs,len(args)))
2090 2090 return None
2091 2091 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
2092 2092 # Now call the macro, evaluating in the user's namespace
2093 2093 #print 'new command: <%r>' % cmd # dbg
2094 2094 return cmd
2095 2095
2096 2096 def call_alias(self,alias,rest=''):
2097 2097 """Call an alias given its name and the rest of the line.
2098 2098
2099 2099 This is only used to provide backwards compatibility for users of
2100 2100 ipalias(), use of which is not recommended for anymore."""
2101 2101
2102 2102 # Now call the macro, evaluating in the user's namespace
2103 2103 cmd = self.transform_alias(alias, rest)
2104 2104 try:
2105 2105 self.system(cmd)
2106 2106 except:
2107 2107 self.showtraceback()
2108 2108
2109 2109 def indent_current_str(self):
2110 2110 """return the current level of indentation as a string"""
2111 2111 return self.indent_current_nsp * ' '
2112 2112
2113 2113 def autoindent_update(self,line):
2114 2114 """Keep track of the indent level."""
2115 2115
2116 2116 #debugx('line')
2117 2117 #debugx('self.indent_current_nsp')
2118 2118 if self.autoindent:
2119 2119 if line:
2120 2120 inisp = num_ini_spaces(line)
2121 2121 if inisp < self.indent_current_nsp:
2122 2122 self.indent_current_nsp = inisp
2123 2123
2124 2124 if line[-1] == ':':
2125 2125 self.indent_current_nsp += 4
2126 2126 elif dedent_re.match(line):
2127 2127 self.indent_current_nsp -= 4
2128 2128 else:
2129 2129 self.indent_current_nsp = 0
2130 2130
2131 2131 def runlines(self,lines):
2132 2132 """Run a string of one or more lines of source.
2133 2133
2134 2134 This method is capable of running a string containing multiple source
2135 2135 lines, as if they had been entered at the IPython prompt. Since it
2136 2136 exposes IPython's processing machinery, the given strings can contain
2137 2137 magic calls (%magic), special shell access (!cmd), etc."""
2138 2138
2139 2139 # We must start with a clean buffer, in case this is run from an
2140 2140 # interactive IPython session (via a magic, for example).
2141 2141 self.resetbuffer()
2142 2142 lines = lines.split('\n')
2143 2143 more = 0
2144 2144
2145 2145 for line in lines:
2146 2146 # skip blank lines so we don't mess up the prompt counter, but do
2147 2147 # NOT skip even a blank line if we are in a code block (more is
2148 2148 # true)
2149 2149
2150 2150 if line or more:
2151 2151 # push to raw history, so hist line numbers stay in sync
2152 2152 self.input_hist_raw.append("# " + line + "\n")
2153 2153 more = self.push(self.prefilter(line,more))
2154 2154 # IPython's runsource returns None if there was an error
2155 2155 # compiling the code. This allows us to stop processing right
2156 2156 # away, so the user gets the error message at the right place.
2157 2157 if more is None:
2158 2158 break
2159 2159 else:
2160 2160 self.input_hist_raw.append("\n")
2161 2161 # final newline in case the input didn't have it, so that the code
2162 2162 # actually does get executed
2163 2163 if more:
2164 2164 self.push('\n')
2165 2165
2166 2166 def runsource(self, source, filename='<input>', symbol='single'):
2167 2167 """Compile and run some source in the interpreter.
2168 2168
2169 2169 Arguments are as for compile_command().
2170 2170
2171 2171 One several things can happen:
2172 2172
2173 2173 1) The input is incorrect; compile_command() raised an
2174 2174 exception (SyntaxError or OverflowError). A syntax traceback
2175 2175 will be printed by calling the showsyntaxerror() method.
2176 2176
2177 2177 2) The input is incomplete, and more input is required;
2178 2178 compile_command() returned None. Nothing happens.
2179 2179
2180 2180 3) The input is complete; compile_command() returned a code
2181 2181 object. The code is executed by calling self.runcode() (which
2182 2182 also handles run-time exceptions, except for SystemExit).
2183 2183
2184 2184 The return value is:
2185 2185
2186 2186 - True in case 2
2187 2187
2188 2188 - False in the other cases, unless an exception is raised, where
2189 2189 None is returned instead. This can be used by external callers to
2190 2190 know whether to continue feeding input or not.
2191 2191
2192 2192 The return value can be used to decide whether to use sys.ps1 or
2193 2193 sys.ps2 to prompt the next line."""
2194 2194
2195 2195 # if the source code has leading blanks, add 'if 1:\n' to it
2196 2196 # this allows execution of indented pasted code. It is tempting
2197 2197 # to add '\n' at the end of source to run commands like ' a=1'
2198 2198 # directly, but this fails for more complicated scenarios
2199 2199 source=source.encode(self.stdin_encoding)
2200 2200 if source[:1] in [' ', '\t']:
2201 2201 source = 'if 1:\n%s' % source
2202 2202
2203 2203 try:
2204 2204 code = self.compile(source,filename,symbol)
2205 2205 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2206 2206 # Case 1
2207 2207 self.showsyntaxerror(filename)
2208 2208 return None
2209 2209
2210 2210 if code is None:
2211 2211 # Case 2
2212 2212 return True
2213 2213
2214 2214 # Case 3
2215 2215 # We store the code object so that threaded shells and
2216 2216 # custom exception handlers can access all this info if needed.
2217 2217 # The source corresponding to this can be obtained from the
2218 2218 # buffer attribute as '\n'.join(self.buffer).
2219 2219 self.code_to_run = code
2220 2220 # now actually execute the code object
2221 2221 if self.runcode(code) == 0:
2222 2222 return False
2223 2223 else:
2224 2224 return None
2225 2225
2226 2226 def runcode(self,code_obj):
2227 2227 """Execute a code object.
2228 2228
2229 2229 When an exception occurs, self.showtraceback() is called to display a
2230 2230 traceback.
2231 2231
2232 2232 Return value: a flag indicating whether the code to be run completed
2233 2233 successfully:
2234 2234
2235 2235 - 0: successful execution.
2236 2236 - 1: an error occurred.
2237 2237 """
2238 2238
2239 2239 # Set our own excepthook in case the user code tries to call it
2240 2240 # directly, so that the IPython crash handler doesn't get triggered
2241 2241 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2242 2242
2243 2243 # we save the original sys.excepthook in the instance, in case config
2244 2244 # code (such as magics) needs access to it.
2245 2245 self.sys_excepthook = old_excepthook
2246 2246 outflag = 1 # happens in more places, so it's easier as default
2247 2247 try:
2248 2248 try:
2249 2249 self.hooks.pre_runcode_hook()
2250 2250 exec code_obj in self.user_global_ns, self.user_ns
2251 2251 finally:
2252 2252 # Reset our crash handler in place
2253 2253 sys.excepthook = old_excepthook
2254 2254 except SystemExit:
2255 2255 self.resetbuffer()
2256 2256 self.showtraceback()
2257 2257 warn("Type %exit or %quit to exit IPython "
2258 2258 "(%Exit or %Quit do so unconditionally).",level=1)
2259 2259 except self.custom_exceptions:
2260 2260 etype,value,tb = sys.exc_info()
2261 2261 self.CustomTB(etype,value,tb)
2262 2262 except:
2263 2263 self.showtraceback()
2264 2264 else:
2265 2265 outflag = 0
2266 2266 if softspace(sys.stdout, 0):
2267 2267 print
2268 2268 # Flush out code object which has been run (and source)
2269 2269 self.code_to_run = None
2270 2270 return outflag
2271 2271
2272 2272 def push(self, line):
2273 2273 """Push a line to the interpreter.
2274 2274
2275 2275 The line should not have a trailing newline; it may have
2276 2276 internal newlines. The line is appended to a buffer and the
2277 2277 interpreter's runsource() method is called with the
2278 2278 concatenated contents of the buffer as source. If this
2279 2279 indicates that the command was executed or invalid, the buffer
2280 2280 is reset; otherwise, the command is incomplete, and the buffer
2281 2281 is left as it was after the line was appended. The return
2282 2282 value is 1 if more input is required, 0 if the line was dealt
2283 2283 with in some way (this is the same as runsource()).
2284 2284 """
2285 2285
2286 2286 # autoindent management should be done here, and not in the
2287 2287 # interactive loop, since that one is only seen by keyboard input. We
2288 2288 # need this done correctly even for code run via runlines (which uses
2289 2289 # push).
2290 2290
2291 2291 #print 'push line: <%s>' % line # dbg
2292 2292 for subline in line.splitlines():
2293 2293 self.autoindent_update(subline)
2294 2294 self.buffer.append(line)
2295 2295 more = self.runsource('\n'.join(self.buffer), self.filename)
2296 2296 if not more:
2297 2297 self.resetbuffer()
2298 2298 return more
2299 2299
2300 2300 def split_user_input(self, line):
2301 2301 # This is really a hold-over to support ipapi and some extensions
2302 2302 return prefilter.splitUserInput(line)
2303 2303
2304 2304 def resetbuffer(self):
2305 2305 """Reset the input buffer."""
2306 2306 self.buffer[:] = []
2307 2307
2308 2308 def raw_input(self,prompt='',continue_prompt=False):
2309 2309 """Write a prompt and read a line.
2310 2310
2311 2311 The returned line does not include the trailing newline.
2312 2312 When the user enters the EOF key sequence, EOFError is raised.
2313 2313
2314 2314 Optional inputs:
2315 2315
2316 2316 - prompt(''): a string to be printed to prompt the user.
2317 2317
2318 2318 - continue_prompt(False): whether this line is the first one or a
2319 2319 continuation in a sequence of inputs.
2320 2320 """
2321 2321
2322 2322 # Code run by the user may have modified the readline completer state.
2323 2323 # We must ensure that our completer is back in place.
2324 2324 if self.has_readline:
2325 2325 self.set_completer()
2326 2326
2327 2327 try:
2328 2328 line = raw_input_original(prompt).decode(self.stdin_encoding)
2329 2329 except ValueError:
2330 2330 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2331 2331 " or sys.stdout.close()!\nExiting IPython!")
2332 2332 self.ask_exit()
2333 2333 return ""
2334 2334
2335 2335 # Try to be reasonably smart about not re-indenting pasted input more
2336 2336 # than necessary. We do this by trimming out the auto-indent initial
2337 2337 # spaces, if the user's actual input started itself with whitespace.
2338 2338 #debugx('self.buffer[-1]')
2339 2339
2340 2340 if self.autoindent:
2341 2341 if num_ini_spaces(line) > self.indent_current_nsp:
2342 2342 line = line[self.indent_current_nsp:]
2343 2343 self.indent_current_nsp = 0
2344 2344
2345 2345 # store the unfiltered input before the user has any chance to modify
2346 2346 # it.
2347 2347 if line.strip():
2348 2348 if continue_prompt:
2349 2349 self.input_hist_raw[-1] += '%s\n' % line
2350 2350 if self.has_readline: # and some config option is set?
2351 2351 try:
2352 2352 histlen = self.readline.get_current_history_length()
2353 2353 if histlen > 1:
2354 2354 newhist = self.input_hist_raw[-1].rstrip()
2355 2355 self.readline.remove_history_item(histlen-1)
2356 2356 self.readline.replace_history_item(histlen-2,
2357 2357 newhist.encode(self.stdin_encoding))
2358 2358 except AttributeError:
2359 2359 pass # re{move,place}_history_item are new in 2.4.
2360 2360 else:
2361 2361 self.input_hist_raw.append('%s\n' % line)
2362 2362 # only entries starting at first column go to shadow history
2363 2363 if line.lstrip() == line:
2364 2364 self.shadowhist.add(line.strip())
2365 2365 elif not continue_prompt:
2366 2366 self.input_hist_raw.append('\n')
2367 2367 try:
2368 2368 lineout = self.prefilter(line,continue_prompt)
2369 2369 except:
2370 2370 # blanket except, in case a user-defined prefilter crashes, so it
2371 2371 # can't take all of ipython with it.
2372 2372 self.showtraceback()
2373 2373 return ''
2374 2374 else:
2375 2375 return lineout
2376 2376
2377 2377 def _prefilter(self, line, continue_prompt):
2378 2378 """Calls different preprocessors, depending on the form of line."""
2379 2379
2380 2380 # All handlers *must* return a value, even if it's blank ('').
2381 2381
2382 2382 # Lines are NOT logged here. Handlers should process the line as
2383 2383 # needed, update the cache AND log it (so that the input cache array
2384 2384 # stays synced).
2385 2385
2386 2386 #.....................................................................
2387 2387 # Code begins
2388 2388
2389 2389 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
2390 2390
2391 2391 # save the line away in case we crash, so the post-mortem handler can
2392 2392 # record it
2393 2393 self._last_input_line = line
2394 2394
2395 2395 #print '***line: <%s>' % line # dbg
2396 2396
2397 2397 if not line:
2398 2398 # Return immediately on purely empty lines, so that if the user
2399 2399 # previously typed some whitespace that started a continuation
2400 2400 # prompt, he can break out of that loop with just an empty line.
2401 2401 # This is how the default python prompt works.
2402 2402
2403 2403 # Only return if the accumulated input buffer was just whitespace!
2404 2404 if ''.join(self.buffer).isspace():
2405 2405 self.buffer[:] = []
2406 2406 return ''
2407 2407
2408 2408 line_info = prefilter.LineInfo(line, continue_prompt)
2409 2409
2410 2410 # the input history needs to track even empty lines
2411 2411 stripped = line.strip()
2412 2412
2413 2413 if not stripped:
2414 2414 if not continue_prompt:
2415 2415 self.outputcache.prompt_count -= 1
2416 2416 return self.handle_normal(line_info)
2417 2417
2418 2418 # print '***cont',continue_prompt # dbg
2419 2419 # special handlers are only allowed for single line statements
2420 2420 if continue_prompt and not self.rc.multi_line_specials:
2421 2421 return self.handle_normal(line_info)
2422 2422
2423 2423
2424 2424 # See whether any pre-existing handler can take care of it
2425 2425 rewritten = self.hooks.input_prefilter(stripped)
2426 2426 if rewritten != stripped: # ok, some prefilter did something
2427 2427 rewritten = line_info.pre + rewritten # add indentation
2428 2428 return self.handle_normal(prefilter.LineInfo(rewritten,
2429 2429 continue_prompt))
2430 2430
2431 2431 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2432 2432
2433 2433 return prefilter.prefilter(line_info, self)
2434 2434
2435 2435
2436 2436 def _prefilter_dumb(self, line, continue_prompt):
2437 2437 """simple prefilter function, for debugging"""
2438 2438 return self.handle_normal(line,continue_prompt)
2439 2439
2440 2440
2441 2441 def multiline_prefilter(self, line, continue_prompt):
2442 2442 """ Run _prefilter for each line of input
2443 2443
2444 2444 Covers cases where there are multiple lines in the user entry,
2445 2445 which is the case when the user goes back to a multiline history
2446 2446 entry and presses enter.
2447 2447
2448 2448 """
2449 2449 out = []
2450 2450 for l in line.rstrip('\n').split('\n'):
2451 2451 out.append(self._prefilter(l, continue_prompt))
2452 2452 return '\n'.join(out)
2453 2453
2454 2454 # Set the default prefilter() function (this can be user-overridden)
2455 2455 prefilter = multiline_prefilter
2456 2456
2457 2457 def handle_normal(self,line_info):
2458 2458 """Handle normal input lines. Use as a template for handlers."""
2459 2459
2460 2460 # With autoindent on, we need some way to exit the input loop, and I
2461 2461 # don't want to force the user to have to backspace all the way to
2462 2462 # clear the line. The rule will be in this case, that either two
2463 2463 # lines of pure whitespace in a row, or a line of pure whitespace but
2464 2464 # of a size different to the indent level, will exit the input loop.
2465 2465 line = line_info.line
2466 2466 continue_prompt = line_info.continue_prompt
2467 2467
2468 2468 if (continue_prompt and self.autoindent and line.isspace() and
2469 2469 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
2470 2470 (self.buffer[-1]).isspace() )):
2471 2471 line = ''
2472 2472
2473 2473 self.log(line,line,continue_prompt)
2474 2474 return line
2475 2475
2476 2476 def handle_alias(self,line_info):
2477 2477 """Handle alias input lines. """
2478 2478 tgt = self.alias_table[line_info.iFun]
2479 2479 # print "=>",tgt #dbg
2480 2480 if callable(tgt):
2481 2481 if '$' in line_info.line:
2482 2482 call_meth = '(_ip, _ip.itpl(%s))'
2483 2483 else:
2484 2484 call_meth = '(_ip,%s)'
2485 2485 line_out = ("%s_sh.%s" + call_meth) % (line_info.preWhitespace,
2486 2486 line_info.iFun,
2487 2487 make_quoted_expr(line_info.line))
2488 2488 else:
2489 2489 transformed = self.expand_aliases(line_info.iFun,line_info.theRest)
2490 2490
2491 2491 # pre is needed, because it carries the leading whitespace. Otherwise
2492 2492 # aliases won't work in indented sections.
2493 2493 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2494 2494 make_quoted_expr( transformed ))
2495 2495
2496 2496 self.log(line_info.line,line_out,line_info.continue_prompt)
2497 2497 #print 'line out:',line_out # dbg
2498 2498 return line_out
2499 2499
2500 2500 def handle_shell_escape(self, line_info):
2501 2501 """Execute the line in a shell, empty return value"""
2502 2502 #print 'line in :', `line` # dbg
2503 2503 line = line_info.line
2504 2504 if line.lstrip().startswith('!!'):
2505 2505 # rewrite LineInfo's line, iFun and theRest to properly hold the
2506 2506 # call to %sx and the actual command to be executed, so
2507 2507 # handle_magic can work correctly. Note that this works even if
2508 2508 # the line is indented, so it handles multi_line_specials
2509 2509 # properly.
2510 2510 new_rest = line.lstrip()[2:]
2511 2511 line_info.line = '%ssx %s' % (self.ESC_MAGIC,new_rest)
2512 2512 line_info.iFun = 'sx'
2513 2513 line_info.theRest = new_rest
2514 2514 return self.handle_magic(line_info)
2515 2515 else:
2516 2516 cmd = line.lstrip().lstrip('!')
2517 2517 line_out = '%s_ip.system(%s)' % (line_info.preWhitespace,
2518 2518 make_quoted_expr(cmd))
2519 2519 # update cache/log and return
2520 2520 self.log(line,line_out,line_info.continue_prompt)
2521 2521 return line_out
2522 2522
2523 2523 def handle_magic(self, line_info):
2524 2524 """Execute magic functions."""
2525 2525 iFun = line_info.iFun
2526 2526 theRest = line_info.theRest
2527 2527 cmd = '%s_ip.magic(%s)' % (line_info.preWhitespace,
2528 2528 make_quoted_expr(iFun + " " + theRest))
2529 2529 self.log(line_info.line,cmd,line_info.continue_prompt)
2530 2530 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2531 2531 return cmd
2532 2532
2533 2533 def handle_auto(self, line_info):
2534 2534 """Hande lines which can be auto-executed, quoting if requested."""
2535 2535
2536 2536 line = line_info.line
2537 2537 iFun = line_info.iFun
2538 2538 theRest = line_info.theRest
2539 2539 pre = line_info.pre
2540 2540 continue_prompt = line_info.continue_prompt
2541 2541 obj = line_info.ofind(self)['obj']
2542 2542
2543 2543 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2544 2544
2545 2545 # This should only be active for single-line input!
2546 2546 if continue_prompt:
2547 2547 self.log(line,line,continue_prompt)
2548 2548 return line
2549 2549
2550 2550 force_auto = isinstance(obj, IPython.ipapi.IPyAutocall)
2551 2551 auto_rewrite = True
2552 2552
2553 2553 if pre == self.ESC_QUOTE:
2554 2554 # Auto-quote splitting on whitespace
2555 2555 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2556 2556 elif pre == self.ESC_QUOTE2:
2557 2557 # Auto-quote whole string
2558 2558 newcmd = '%s("%s")' % (iFun,theRest)
2559 2559 elif pre == self.ESC_PAREN:
2560 2560 newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
2561 2561 else:
2562 2562 # Auto-paren.
2563 2563 # We only apply it to argument-less calls if the autocall
2564 2564 # parameter is set to 2. We only need to check that autocall is <
2565 2565 # 2, since this function isn't called unless it's at least 1.
2566 2566 if not theRest and (self.rc.autocall < 2) and not force_auto:
2567 2567 newcmd = '%s %s' % (iFun,theRest)
2568 2568 auto_rewrite = False
2569 2569 else:
2570 2570 if not force_auto and theRest.startswith('['):
2571 2571 if hasattr(obj,'__getitem__'):
2572 2572 # Don't autocall in this case: item access for an object
2573 2573 # which is BOTH callable and implements __getitem__.
2574 2574 newcmd = '%s %s' % (iFun,theRest)
2575 2575 auto_rewrite = False
2576 2576 else:
2577 2577 # if the object doesn't support [] access, go ahead and
2578 2578 # autocall
2579 2579 newcmd = '%s(%s)' % (iFun.rstrip(),theRest)
2580 2580 elif theRest.endswith(';'):
2581 2581 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2582 2582 else:
2583 2583 newcmd = '%s(%s)' % (iFun.rstrip(), theRest)
2584 2584
2585 2585 if auto_rewrite:
2586 2586 rw = self.outputcache.prompt1.auto_rewrite() + newcmd
2587 2587
2588 2588 try:
2589 2589 # plain ascii works better w/ pyreadline, on some machines, so
2590 2590 # we use it and only print uncolored rewrite if we have unicode
2591 2591 rw = str(rw)
2592 2592 print >>Term.cout, rw
2593 2593 except UnicodeEncodeError:
2594 2594 print "-------------->" + newcmd
2595 2595
2596 2596 # log what is now valid Python, not the actual user input (without the
2597 2597 # final newline)
2598 2598 self.log(line,newcmd,continue_prompt)
2599 2599 return newcmd
2600 2600
2601 2601 def handle_help(self, line_info):
2602 2602 """Try to get some help for the object.
2603 2603
2604 2604 obj? or ?obj -> basic information.
2605 2605 obj?? or ??obj -> more details.
2606 2606 """
2607 2607
2608 2608 line = line_info.line
2609 2609 # We need to make sure that we don't process lines which would be
2610 2610 # otherwise valid python, such as "x=1 # what?"
2611 2611 try:
2612 2612 codeop.compile_command(line)
2613 2613 except SyntaxError:
2614 2614 # We should only handle as help stuff which is NOT valid syntax
2615 2615 if line[0]==self.ESC_HELP:
2616 2616 line = line[1:]
2617 2617 elif line[-1]==self.ESC_HELP:
2618 2618 line = line[:-1]
2619 2619 self.log(line,'#?'+line,line_info.continue_prompt)
2620 2620 if line:
2621 2621 #print 'line:<%r>' % line # dbg
2622 2622 self.magic_pinfo(line)
2623 2623 else:
2624 2624 page(self.usage,screen_lines=self.rc.screen_length)
2625 2625 return '' # Empty string is needed here!
2626 2626 except:
2627 2627 # Pass any other exceptions through to the normal handler
2628 2628 return self.handle_normal(line_info)
2629 2629 else:
2630 2630 # If the code compiles ok, we should handle it normally
2631 2631 return self.handle_normal(line_info)
2632 2632
2633 2633 def getapi(self):
2634 2634 """ Get an IPApi object for this shell instance
2635 2635
2636 2636 Getting an IPApi object is always preferable to accessing the shell
2637 2637 directly, but this holds true especially for extensions.
2638 2638
2639 2639 It should always be possible to implement an extension with IPApi
2640 2640 alone. If not, contact maintainer to request an addition.
2641 2641
2642 2642 """
2643 2643 return self.api
2644 2644
2645 2645 def handle_emacs(self, line_info):
2646 2646 """Handle input lines marked by python-mode."""
2647 2647
2648 2648 # Currently, nothing is done. Later more functionality can be added
2649 2649 # here if needed.
2650 2650
2651 2651 # The input cache shouldn't be updated
2652 2652 return line_info.line
2653 2653
2654 2654
2655 2655 def mktempfile(self,data=None):
2656 2656 """Make a new tempfile and return its filename.
2657 2657
2658 2658 This makes a call to tempfile.mktemp, but it registers the created
2659 2659 filename internally so ipython cleans it up at exit time.
2660 2660
2661 2661 Optional inputs:
2662 2662
2663 2663 - data(None): if data is given, it gets written out to the temp file
2664 2664 immediately, and the file is closed again."""
2665 2665
2666 2666 filename = tempfile.mktemp('.py','ipython_edit_')
2667 2667 self.tempfiles.append(filename)
2668 2668
2669 2669 if data:
2670 2670 tmp_file = open(filename,'w')
2671 2671 tmp_file.write(data)
2672 2672 tmp_file.close()
2673 2673 return filename
2674 2674
2675 2675 def write(self,data):
2676 2676 """Write a string to the default output"""
2677 2677 Term.cout.write(data)
2678 2678
2679 2679 def write_err(self,data):
2680 2680 """Write a string to the default error output"""
2681 2681 Term.cerr.write(data)
2682 2682
2683 2683 def ask_exit(self):
2684 2684 """ Call for exiting. Can be overiden and used as a callback. """
2685 2685 self.exit_now = True
2686 2686
2687 2687 def exit(self):
2688 2688 """Handle interactive exit.
2689 2689
2690 2690 This method calls the ask_exit callback."""
2691 2691
2692 2692 if self.rc.confirm_exit:
2693 2693 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2694 2694 self.ask_exit()
2695 2695 else:
2696 2696 self.ask_exit()
2697 2697
2698 2698 def safe_execfile(self,fname,*where,**kw):
2699 2699 """A safe version of the builtin execfile().
2700 2700
2701 2701 This version will never throw an exception, and knows how to handle
2702 2702 ipython logs as well.
2703 2703
2704 2704 :Parameters:
2705 2705 fname : string
2706 2706 Name of the file to be executed.
2707 2707
2708 2708 where : tuple
2709 2709 One or two namespaces, passed to execfile() as (globals,locals).
2710 2710 If only one is given, it is passed as both.
2711 2711
2712 2712 :Keywords:
2713 2713 islog : boolean (False)
2714 2714
2715 2715 quiet : boolean (True)
2716 2716
2717 2717 exit_ignore : boolean (False)
2718 2718 """
2719 2719
2720 2720 def syspath_cleanup():
2721 2721 """Internal cleanup routine for sys.path."""
2722 2722 if add_dname:
2723 2723 try:
2724 2724 sys.path.remove(dname)
2725 2725 except ValueError:
2726 2726 # For some reason the user has already removed it, ignore.
2727 2727 pass
2728 2728
2729 2729 fname = os.path.expanduser(fname)
2730 2730
2731 2731 # Find things also in current directory. This is needed to mimic the
2732 2732 # behavior of running a script from the system command line, where
2733 2733 # Python inserts the script's directory into sys.path
2734 2734 dname = os.path.dirname(os.path.abspath(fname))
2735 2735 add_dname = False
2736 2736 if dname not in sys.path:
2737 2737 sys.path.insert(0,dname)
2738 2738 add_dname = True
2739 2739
2740 2740 try:
2741 2741 xfile = open(fname)
2742 2742 except:
2743 2743 print >> Term.cerr, \
2744 2744 'Could not open file <%s> for safe execution.' % fname
2745 2745 syspath_cleanup()
2746 2746 return None
2747 2747
2748 2748 kw.setdefault('islog',0)
2749 2749 kw.setdefault('quiet',1)
2750 2750 kw.setdefault('exit_ignore',0)
2751 2751
2752 2752 first = xfile.readline()
2753 2753 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2754 2754 xfile.close()
2755 2755 # line by line execution
2756 2756 if first.startswith(loghead) or kw['islog']:
2757 2757 print 'Loading log file <%s> one line at a time...' % fname
2758 2758 if kw['quiet']:
2759 2759 stdout_save = sys.stdout
2760 2760 sys.stdout = StringIO.StringIO()
2761 2761 try:
2762 2762 globs,locs = where[0:2]
2763 2763 except:
2764 2764 try:
2765 2765 globs = locs = where[0]
2766 2766 except:
2767 2767 globs = locs = globals()
2768 2768 badblocks = []
2769 2769
2770 2770 # we also need to identify indented blocks of code when replaying
2771 2771 # logs and put them together before passing them to an exec
2772 2772 # statement. This takes a bit of regexp and look-ahead work in the
2773 2773 # file. It's easiest if we swallow the whole thing in memory
2774 2774 # first, and manually walk through the lines list moving the
2775 2775 # counter ourselves.
2776 2776 indent_re = re.compile('\s+\S')
2777 2777 xfile = open(fname)
2778 2778 filelines = xfile.readlines()
2779 2779 xfile.close()
2780 2780 nlines = len(filelines)
2781 2781 lnum = 0
2782 2782 while lnum < nlines:
2783 2783 line = filelines[lnum]
2784 2784 lnum += 1
2785 2785 # don't re-insert logger status info into cache
2786 2786 if line.startswith('#log#'):
2787 2787 continue
2788 2788 else:
2789 2789 # build a block of code (maybe a single line) for execution
2790 2790 block = line
2791 2791 try:
2792 2792 next = filelines[lnum] # lnum has already incremented
2793 2793 except:
2794 2794 next = None
2795 2795 while next and indent_re.match(next):
2796 2796 block += next
2797 2797 lnum += 1
2798 2798 try:
2799 2799 next = filelines[lnum]
2800 2800 except:
2801 2801 next = None
2802 2802 # now execute the block of one or more lines
2803 2803 try:
2804 2804 exec block in globs,locs
2805 2805 except SystemExit:
2806 2806 pass
2807 2807 except:
2808 2808 badblocks.append(block.rstrip())
2809 2809 if kw['quiet']: # restore stdout
2810 2810 sys.stdout.close()
2811 2811 sys.stdout = stdout_save
2812 2812 print 'Finished replaying log file <%s>' % fname
2813 2813 if badblocks:
2814 2814 print >> sys.stderr, ('\nThe following lines/blocks in file '
2815 2815 '<%s> reported errors:' % fname)
2816 2816
2817 2817 for badline in badblocks:
2818 2818 print >> sys.stderr, badline
2819 2819 else: # regular file execution
2820 2820 try:
2821 2821 if sys.platform == 'win32' and sys.version_info < (2,5,1):
2822 2822 # Work around a bug in Python for Windows. The bug was
2823 2823 # fixed in in Python 2.5 r54159 and 54158, but that's still
2824 2824 # SVN Python as of March/07. For details, see:
2825 2825 # http://projects.scipy.org/ipython/ipython/ticket/123
2826 2826 try:
2827 2827 globs,locs = where[0:2]
2828 2828 except:
2829 2829 try:
2830 2830 globs = locs = where[0]
2831 2831 except:
2832 2832 globs = locs = globals()
2833 2833 exec file(fname) in globs,locs
2834 2834 else:
2835 2835 execfile(fname,*where)
2836 2836 except SyntaxError:
2837 2837 self.showsyntaxerror()
2838 2838 warn('Failure executing file: <%s>' % fname)
2839 2839 except SystemExit,status:
2840 2840 # Code that correctly sets the exit status flag to success (0)
2841 2841 # shouldn't be bothered with a traceback. Note that a plain
2842 2842 # sys.exit() does NOT set the message to 0 (it's empty) so that
2843 2843 # will still get a traceback. Note that the structure of the
2844 2844 # SystemExit exception changed between Python 2.4 and 2.5, so
2845 2845 # the checks must be done in a version-dependent way.
2846 2846 show = False
2847 2847
2848 2848 if sys.version_info[:2] > (2,5):
2849 2849 if status.message!=0 and not kw['exit_ignore']:
2850 2850 show = True
2851 2851 else:
2852 2852 if status.code and not kw['exit_ignore']:
2853 2853 show = True
2854 2854 if show:
2855 2855 self.showtraceback()
2856 2856 warn('Failure executing file: <%s>' % fname)
2857 2857 except:
2858 2858 self.showtraceback()
2859 2859 warn('Failure executing file: <%s>' % fname)
2860 2860
2861 2861 syspath_cleanup()
2862 2862
2863 2863 #************************* end of file <iplib.py> *****************************
@@ -1,300 +1,300 b''
1 1 # -*- coding: utf-8 -*-
2 2 """IPython Test Suite Runner.
3 3
4 4 This module provides a main entry point to a user script to test IPython
5 5 itself from the command line. There are two ways of running this script:
6 6
7 7 1. With the syntax `iptest all`. This runs our entire test suite by
8 8 calling this script (with different arguments) or trial recursively. This
9 9 causes modules and package to be tested in different processes, using nose
10 10 or trial where appropriate.
11 11 2. With the regular nose syntax, like `iptest -vvs IPython`. In this form
12 12 the script simply calls nose, but with special command line flags and
13 13 plugins loaded.
14 14
15 15 For now, this script requires that both nose and twisted are installed. This
16 16 will change in the future.
17 17 """
18 18
19 19 #-----------------------------------------------------------------------------
20 20 # Module imports
21 21 #-----------------------------------------------------------------------------
22 22
23 23 import os
24 24 import os.path as path
25 25 import sys
26 26 import subprocess
27 27 import time
28 28 import warnings
29 29
30 30 import nose.plugins.builtin
31 31 from nose.core import TestProgram
32 32
33 33 from IPython.platutils import find_cmd
34 34 from IPython.testing.plugin.ipdoctest import IPythonDoctest
35 35
36 36 pjoin = path.join
37 37
38 38 #-----------------------------------------------------------------------------
39 39 # Logic for skipping doctests
40 40 #-----------------------------------------------------------------------------
41 41
42 42 def test_for(mod):
43 43 """Test to see if mod is importable."""
44 44 try:
45 45 __import__(mod)
46 46 except ImportError:
47 47 return False
48 48 else:
49 49 return True
50 50
51 51 have_curses = test_for('_curses')
52 52 have_wx = test_for('wx')
53 53 have_zi = test_for('zope.interface')
54 54 have_twisted = test_for('twisted')
55 55 have_foolscap = test_for('foolscap')
56 56 have_objc = test_for('objc')
57 57 have_pexpect = test_for('pexpect')
58 58
59 59 # For the IPythonDoctest plugin, we need to exclude certain patterns that cause
60 60 # testing problems. We should strive to minimize the number of skipped
61 61 # modules, since this means untested code. As the testing machinery
62 62 # solidifies, this list should eventually become empty.
63 63 EXCLUDE = [pjoin('IPython', 'external'),
64 64 pjoin('IPython', 'frontend', 'process', 'winprocess.py'),
65 65 pjoin('IPython_doctest_plugin'),
66 66 pjoin('IPython', 'Gnuplot'),
67 67 pjoin('IPython', 'Extensions', 'ipy_'),
68 68 pjoin('IPython', 'Extensions', 'clearcmd'),
69 69 pjoin('IPython', 'Extensions', 'PhysicalQInteractive'),
70 70 pjoin('IPython', 'Extensions', 'scitedirector'),
71 71 pjoin('IPython', 'Extensions', 'numeric_formats'),
72 72 pjoin('IPython', 'testing', 'attic'),
73 73 pjoin('IPython', 'testing', 'tutils'),
74 74 pjoin('IPython', 'testing', 'tools'),
75 75 pjoin('IPython', 'testing', 'mkdoctests')
76 76 ]
77 77
78 78 if not have_wx:
79 79 EXCLUDE.append(pjoin('IPython', 'Extensions', 'igrid'))
80 80 EXCLUDE.append(pjoin('IPython', 'gui'))
81 81 EXCLUDE.append(pjoin('IPython', 'frontend', 'wx'))
82 82
83 83 if not have_objc:
84 84 EXCLUDE.append(pjoin('IPython', 'frontend', 'cocoa'))
85 85
86 86 if not have_curses:
87 87 EXCLUDE.append(pjoin('IPython', 'Extensions', 'ibrowse'))
88 88
89 89 if not sys.platform == 'win32':
90 90 EXCLUDE.append(pjoin('IPython', 'platutils_win32'))
91 91
92 92 # These have to be skipped on win32 because the use echo, rm, cd, etc.
93 93 # See ticket https://bugs.launchpad.net/bugs/366982
94 94 if sys.platform == 'win32':
95 95 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
96 96 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
97 97
98 98 if not os.name == 'posix':
99 99 EXCLUDE.append(pjoin('IPython', 'platutils_posix'))
100 100
101 101 if not have_pexpect:
102 102 EXCLUDE.append(pjoin('IPython', 'irunner'))
103 103
104 104 # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
105 105 if sys.platform == 'win32':
106 106 EXCLUDE = [s.replace('\\','\\\\') for s in EXCLUDE]
107 107
108 108
109 109 #-----------------------------------------------------------------------------
110 110 # Functions and classes
111 111 #-----------------------------------------------------------------------------
112 112
113 113 def run_iptest():
114 114 """Run the IPython test suite using nose.
115 115
116 116 This function is called when this script is **not** called with the form
117 117 `iptest all`. It simply calls nose with appropriate command line flags
118 118 and accepts all of the standard nose arguments.
119 119 """
120 120
121 121 warnings.filterwarnings('ignore',
122 122 'This will be removed soon. Use IPython.testing.util instead')
123 123
124 124 argv = sys.argv + [
125 125 # Loading ipdoctest causes problems with Twisted.
126 126 # I am removing this as a temporary fix to get the
127 127 # test suite back into working shape. Our nose
128 128 # plugin needs to be gone through with a fine
129 129 # toothed comb to find what is causing the problem.
130 130 '--with-ipdoctest',
131 131 '--ipdoctest-tests','--ipdoctest-extension=txt',
132 132 '--detailed-errors',
133 133
134 134 # We add --exe because of setuptools' imbecility (it
135 135 # blindly does chmod +x on ALL files). Nose does the
136 136 # right thing and it tries to avoid executables,
137 137 # setuptools unfortunately forces our hand here. This
138 138 # has been discussed on the distutils list and the
139 139 # setuptools devs refuse to fix this problem!
140 140 '--exe',
141 141 ]
142 142
143 143 # Detect if any tests were required by explicitly calling an IPython
144 144 # submodule or giving a specific path
145 145 has_tests = False
146 146 for arg in sys.argv:
147 147 if 'IPython' in arg or arg.endswith('.py') or \
148 148 (':' in arg and '.py' in arg):
149 149 has_tests = True
150 150 break
151 151
152 152 # If nothing was specifically requested, test full IPython
153 153 if not has_tests:
154 154 argv.append('IPython')
155 155
156 156 # Construct list of plugins, omitting the existing doctest plugin, which
157 157 # ours replaces (and extends).
158 158 plugins = [IPythonDoctest(EXCLUDE)]
159 159 for p in nose.plugins.builtin.plugins:
160 160 plug = p()
161 161 if plug.name == 'doctest':
162 162 continue
163 163
164 164 #print '*** adding plugin:',plug.name # dbg
165 165 plugins.append(plug)
166 166
167 167 TestProgram(argv=argv,plugins=plugins)
168 168
169 169
170 170 class IPTester(object):
171 171 """Call that calls iptest or trial in a subprocess.
172 172 """
173 173 def __init__(self,runner='iptest',params=None):
174 174 """ """
175 175 if runner == 'iptest':
176 176 self.runner = ['iptest','-v']
177 177 else:
178 178 self.runner = [find_cmd('trial')]
179 179 if params is None:
180 180 params = []
181 181 if isinstance(params,str):
182 182 params = [params]
183 183 self.params = params
184 184
185 185 # Assemble call
186 186 self.call_args = self.runner+self.params
187 187
188 188 def run(self):
189 189 """Run the stored commands"""
190 190 return subprocess.call(self.call_args)
191 191
192 192
193 193 def make_runners():
194 194 """Define the modules and packages that need to be tested.
195 195 """
196 196
197 197 # This omits additional top-level modules that should not be doctested.
198 198 # XXX: Shell.py is also ommited because of a bug in the skip_doctest
199 199 # decorator. See ticket https://bugs.launchpad.net/bugs/366209
200 200 top_mod = \
201 201 ['backgroundjobs.py', 'coloransi.py', 'completer.py', 'configloader.py',
202 202 'crashhandler.py', 'debugger.py', 'deepreload.py', 'demo.py',
203 'DPyGetOpt.py', 'dtutils.py', 'excolors.py', 'FakeModule.py',
203 'DPyGetOpt.py', 'dtutils.py', 'excolors.py', 'fakemodule.py',
204 204 'generics.py', 'genutils.py', 'history.py', 'hooks.py', 'ipapi.py',
205 205 'iplib.py', 'ipmaker.py', 'ipstruct.py', 'Itpl.py',
206 206 'Logger.py', 'macro.py', 'Magic.py', 'OInspect.py',
207 207 'OutputTrap.py', 'platutils.py', 'prefilter.py', 'Prompts.py',
208 208 'PyColorize.py', 'Release.py', 'rlineimpl.py', 'shadowns.py',
209 209 'shellglobals.py', 'strdispatch.py', 'twshell.py',
210 210 'ultraTB.py', 'upgrade_dir.py', 'usage.py', 'wildcard.py',
211 211 # See note above for why this is skipped
212 212 # 'Shell.py',
213 213 'winconsole.py']
214 214
215 215 if have_pexpect:
216 216 top_mod.append('irunner.py')
217 217
218 218 if sys.platform == 'win32':
219 219 top_mod.append('platutils_win32.py')
220 220 elif os.name == 'posix':
221 221 top_mod.append('platutils_posix.py')
222 222 else:
223 223 top_mod.append('platutils_dummy.py')
224 224
225 225 # These are tested by nose, so skip IPython.kernel
226 226 top_pack = ['config','Extensions','frontend',
227 227 'testing','tests','tools','UserConfig']
228 228
229 229 if have_wx:
230 230 top_pack.append('gui')
231 231
232 232 modules = ['IPython.%s' % m[:-3] for m in top_mod ]
233 233 packages = ['IPython.%s' % m for m in top_pack ]
234 234
235 235 # Make runners
236 236 runners = dict(zip(top_pack, [IPTester(params=v) for v in packages]))
237 237
238 238 # Test IPython.kernel using trial if twisted is installed
239 239 if have_zi and have_twisted and have_foolscap:
240 240 runners['trial'] = IPTester('trial',['IPython'])
241 241
242 242 runners['modules'] = IPTester(params=modules)
243 243
244 244 return runners
245 245
246 246
247 247 def run_iptestall():
248 248 """Run the entire IPython test suite by calling nose and trial.
249 249
250 250 This function constructs :class:`IPTester` instances for all IPython
251 251 modules and package and then runs each of them. This causes the modules
252 252 and packages of IPython to be tested each in their own subprocess using
253 253 nose or twisted.trial appropriately.
254 254 """
255 255 runners = make_runners()
256 256 # Run all test runners, tracking execution time
257 257 failed = {}
258 258 t_start = time.time()
259 259 for name,runner in runners.iteritems():
260 260 print '*'*77
261 261 print 'IPython test set:',name
262 262 res = runner.run()
263 263 if res:
264 264 failed[name] = res
265 265 t_end = time.time()
266 266 t_tests = t_end - t_start
267 267 nrunners = len(runners)
268 268 nfail = len(failed)
269 269 # summarize results
270 270 print
271 271 print '*'*77
272 272 print 'Ran %s test sets in %.3fs' % (nrunners, t_tests)
273 273 print
274 274 if not failed:
275 275 print 'OK'
276 276 else:
277 277 # If anything went wrong, point out what command to rerun manually to
278 278 # see the actual errors and individual summary
279 279 print 'ERROR - %s out of %s test sets failed.' % (nfail, nrunners)
280 280 for name in failed:
281 281 failed_runner = runners[name]
282 282 print '-'*40
283 283 print 'Runner failed:',name
284 284 print 'You may wish to rerun this one individually, with:'
285 285 print ' '.join(failed_runner.call_args)
286 286 print
287 287
288 288
289 289 def main():
290 290 if len(sys.argv) == 1:
291 291 run_iptestall()
292 292 else:
293 293 if sys.argv[1] == 'all':
294 294 run_iptestall()
295 295 else:
296 296 run_iptest()
297 297
298 298
299 299 if __name__ == '__main__':
300 300 main() No newline at end of file
@@ -1,248 +1,247 b''
1 1 =============================
2 2 IPython module reorganization
3 3 =============================
4 4
5 5 Currently, IPython has many top-level modules that serve many different purposes.
6 6 The lack of organization make it very difficult for developers to work on IPython
7 7 and understand its design. This document contains notes about how we will reorganize
8 8 the modules into sub-packages.
9 9
10 10 .. warning::
11 11
12 12 This effort will possibly break third party packages that use IPython as
13 13 a library or hack on the IPython internals.
14 14
15 15 .. warning::
16 16
17 17 This effort will result in the removal from IPython of certain modules
18 18 that are not used anymore, don't currently work, are unmaintained, etc.
19 19
20 20
21 21 Current subpackges
22 22 ==================
23 23
24 24 IPython currently has the following sub-packages:
25 25
26 26 * :mod:`IPython.config`
27 27
28 28 * :mod:`IPython.Extensions`
29 29
30 30 * :mod:`IPython.external`
31 31
32 32 * :mod:`IPython.frontend`
33 33
34 34 * :mod:`IPython.gui`
35 35
36 36 * :mod:`IPython.kernel`
37 37
38 38 * :mod:`IPython.testing`
39 39
40 40 * :mod:`IPython.tests`
41 41
42 42 * :mod:`IPython.tools`
43 43
44 44 * :mod:`IPython.UserConfig`
45 45
46 46 New Subpackages to be created
47 47 =============================
48 48
49 49 We propose to create the following new sub-packages:
50 50
51 51 * :mod:`IPython.core`. This sub-package will contain the core of the IPython
52 52 interpreter, but none of its extended capabilities.
53 53
54 54 * :mod:`IPython.lib`. IPython has many extended capabilities that are not part
55 55 of the IPython core. These things will go here. Any better names than
56 56 :mod:`IPython.lib`?
57 57
58 58 * :mod:`IPython.utils`. This sub-package will contain anything that might
59 59 eventually be found in the Python standard library, like things in
60 60 :mod:`genutils`. Each sub-module in this sub-package should contain
61 61 functions and classes that serve a single purpose.
62 62
63 63 * :mod:`IPython.deathrow`. This is for code that is untested and/or rotting
64 64 and needs to be removed from IPython. Eventually all this code will either
65 65 i) be revived by someone willing to maintain it with tests and docs and
66 66 re-included into IPython or 2) be removed from IPython proper, but put into
67 67 a separate top-level (not IPython) package that we keep around. No new code
68 68 will be allowed here.
69 69
70 70 * :mod:`IPython.quarantine`. This is for code that doesn't meet IPython's
71 71 standards, but that we plan on keeping. To be moved out of this sub-package
72 72 a module needs to have a maintainer, tests and documentation.
73 73
74 74 Prodecure
75 75 =========
76 76
77 77 1. Move the file to its new location with its new name.
78 78 2. Rename all import statements to reflect the change.
79 79 3. Run PyFlakes on each changes module.
80 80 3. Add tests/test_imports.py to test it.
81 81
82 82 Need to modify iptests to properly skip modules that are no longer top
83 83 level modules.
84 84
85 85 Need to update the top level IPython/__init__.py file.
86 86
87 87 Where things will be moved
88 88 ==========================
89 89
90 90 * :file:`background_jobs.py`. Move to :file:`IPython/lib/backgroundjobs.py`.
91 91
92 92 * :file:`ColorANSI.py`. Move to :file:`IPython/utils/coloransi.py`.
93 93
94 94 * :file:`completer.py`. Move to :file:`IPython/core/completer.py`.
95 95
96 96 * :file:`ConfigLoader.py`. Move to :file:`IPython/config/configloader.py`.
97 97
98 98 * :file:`CrashHandler.py`. Move to :file:`IPython/core/crashhandler`.
99 99
100 100 * :file:`Debugger.py`. Move to :file:`IPython/core/debugger.py`.
101 101
102 102 * :file:`deep_reload.py`. Move to :file:`IPython/lib/deepreload.py`.
103 103
104 104 * :file:`demo.py`. Move to :file:`IPython/lib/demo.py`.
105 105
106 106 * :file:`DPyGetOpt.py`. Move to :mod:`IPython.utils` and replace with newer options parser.
107 107
108 * :file:`dtutils.py`. Remove or move to :file:`IPython.testing` or
109 :file:`IPython.lib`.
108 * :file:`dtutils.py`. Move to :file:`IPython.deathrow`.
110 109
110 * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`.
111 111
112 112
113 113 * :file:`Extensions`. This needs to be gone through separately. Minimally,
114 114 the package should be renamed to :file:`extensions`.
115 115
116 * :file:`FakeModule.py`. Move to :file:`IPython/core/fakemodule.py`.
117 116
118 117 * :file:`Gnuplot2.py`. Move to :file:`IPython.sandbox`.
119 118
120 119 * :file:`GnuplotInteractive.py`. Move to :file:`IPython.sandbox`.
121 120
122 121 * :file:`GnuplotRuntime.py`. Move to :file:`IPython.sandbox`.
123 122
124 123 * :file:`Itpl.py`. Remove. Version already in :file:`IPython.external`.
125 124
126 125 * :file:`Logger.py`. Move to :file:`IPython/core/logger.py`.
127 126
128 127 * :file:`Magic.py`. Move to :file:`IPython/core/magic.py`.
129 128
130 129 * :file:`OInspect.py`. Move to :file:`IPython/core/oinspect.py`.
131 130
132 131 * :file:`OutputTrap.py`. Move to :file:`IPython/core/outputtrap.py`.
133 132
134 133 * :file:`Prompts.py`. Move to :file:`IPython/core/prompts.py` or
135 134 :file:`IPython/frontend/prompts.py`.
136 135
137 136 * :file:`PyColorize.py`. Replace with pygments? If not, move to
138 137 :file:`IPython/core/pycolorize.py`. Maybe move to :mod:`IPython.lib` or
139 138 :mod:`IPython.python`?
140 139
141 140 * :file:`Release.py`. Move to ??? or remove?
142 141
143 142 * :file:`Shell.py`. Move to :file:`IPython.core.shell.py` or
144 143 :file:`IPython/frontend/shell.py`.
145 144
146 145 * :file:`UserConfig`. Move to a subdirectory of :file:`IPython.config`.
147 146
148 147
149 148
150 149
151 150 * :file:`config`. Good where it is!
152 151
153 152
154 153
155 154
156 155 * :file:`excolors.py`. Move to :file:`IPython.core` or :file:`IPython.config`.
157 156 Maybe move to :mod:`IPython.lib` or :mod:`IPython.python`?
158 157
159 158 * :file:`external`. Good where it is!
160 159
161 160 * :file:`frontend`. Good where it is!
162 161
163 162 * :file:`generics.py`. Move to :file:`IPython.python`.
164 163
165 164 * :file:`genutils.py`. Move to :file:`IPython.python` and break up into different
166 165 modules.
167 166
168 167 * :file:`gui`. Eventually this should be moved to a subdir of
169 168 :file:`IPython.frontend`.
170 169
171 170 * :file:`history.py`. Move to :file:`IPython.core`.
172 171
173 172 * :file:`hooks.py`. Move to :file:`IPython.core`.
174 173
175 174 * :file:`ipapi.py`. Move to :file:`IPython.core`.
176 175
177 176 * :file:`iplib.py`. Move to :file:`IPython.core`.
178 177
179 178 * :file:`ipmaker.py`: Move to :file:`IPython.core`.
180 179
181 180 * :file:`ipstruct.py`. Move to :file:`IPython.python`.
182 181
183 182 * :file:`irunner.py`. Move to :file:`IPython.scripts`.
184 183
185 184 * :file:`kernel`. Good where it is.
186 185
187 186 * :file:`macro.py`. Move to :file:`IPython.core`.
188 187
189 188 * :file:`numutils.py`. Move to :file:`IPython.sandbox`.
190 189
191 190 * :file:`platutils.py`. Move to :file:`IPython.python`.
192 191
193 192 * :file:`platutils_dummy.py`. Move to :file:`IPython.python`.
194 193
195 194 * :file:`platutils_posix.py`. Move to :file:`IPython.python`.
196 195
197 196 * :file:`platutils_win32.py`. Move to :file:`IPython.python`.
198 197
199 198 * :file:`prefilter.py`: Move to :file:`IPython.core`.
200 199
201 200 * :file:`rlineimpl.py`. Move to :file:`IPython.core`.
202 201
203 202 * :file:`shadowns.py`. Move to :file:`IPython.core`.
204 203
205 204 * :file:`shellglobals.py`. Move to :file:`IPython.core`.
206 205
207 206 * :file:`strdispatch.py`. Move to :file:`IPython.python`.
208 207
209 208 * :file:`testing`. Good where it is.
210 209
211 210 * :file:`tests`. Good where it is.
212 211
213 212 * :file:`tools`. Things in here need to be looked at and moved elsewhere like
214 213 :file:`IPython.python`.
215 214
216 215 * :file:`twshell.py`. Move to :file:`IPython.sandbox`.
217 216
218 217 * :file:`ultraTB.py`. Move to :file:`IPython/core/ultratb.py`.
219 218
220 219 * :file:`upgrade_dir.py`. Move to :file:`IPython/python/upgradedir.py`.
221 220
222 221 * :file:`usage.py`. Move to :file:`IPython.core`.
223 222
224 223 * :file:`wildcard.py`. Move to :file:`IPython.python` or :file:`IPython.core`.
225 224
226 225 * :file:`winconsole.py`. Move to :file:`IPython.lib`.
227 226
228 227 Other things
229 228 ============
230 229
231 230 When these files are moved around, a number of other things will happen at the same time:
232 231
233 232 1. Test files will be created for each module in IPython. Minimally, all
234 233 modules will be imported as a part of the test. This will serve as a
235 234 test of the module reorganization. These tests will be put into new
236 235 :file:`tests` subdirectories that each package will have.
237 236
238 237 2. PyFlakes and other code checkers will be run to look for problems.
239 238
240 239 3. Modules will be renamed to comply with PEP 8 naming conventions: all
241 240 lowercase and no special characters like ``-`` or ``_``.
242 241
243 242 4. Existing tests will be moved to the appropriate :file:`tests`
244 243 subdirectories.
245 244
246 245
247 246
248 247
General Comments 0
You need to be logged in to leave comments. Login now