##// END OF EJS Templates
Grand Persistence Overhaul, featuring PickleShare. startup...
vivainio -
Show More

The requested changes are too big and content was truncated. Show full diff

@@ -0,0 +1,267 b''
1 #!/usr/bin/env python
2
3 """ PickleShare - a small 'shelve' like datastore with concurrency support
4
5 Like shelve, a PickleShareDB object acts like a normal dictionary. Unlike
6 shelve, many processes can access the database simultaneously. Changing a
7 value in database is immediately visible to other processes accessing the
8 same database.
9
10 Concurrency is possible because the values are stored in separate files. Hence
11 the "database" is a directory where *all* files are governed by PickleShare.
12
13 Example usage::
14
15 from pickleshare import *
16 db = PickleShareDB('~/testpickleshare')
17 db.clear()
18 print "Should be empty:",db.items()
19 db['hello'] = 15
20 db['aku ankka'] = [1,2,313]
21 db['paths/are/ok/key'] = [1,(5,46)]
22 print db.keys()
23 del db['aku ankka']
24
25 This module is certainly not ZODB, but can be used for low-load
26 (non-mission-critical) situations where tiny code size trumps the
27 advanced features of a "real" object database.
28
29 Installation guide: easy_install pickleshare
30
31 Author: Ville Vainio <vivainio@gmail.com>
32 License: MIT open source license.
33
34 """
35
36 from path import path as Path
37 import os,stat,time
38 import cPickle as pickle
39 import UserDict
40 import warnings
41 import glob
42
43 class PickleShareDB(UserDict.DictMixin):
44 """ The main 'connection' object for PickleShare database """
45 def __init__(self,root):
46 """ Return a db object that will manage the specied directory"""
47 self.root = Path(root).expanduser().abspath()
48 if not self.root.isdir():
49 self.root.makedirs()
50 # cache has { 'key' : (obj, orig_mod_time) }
51 self.cache = {}
52
53 def __getitem__(self,key):
54 """ db['key'] reading """
55 fil = self.root / key
56 try:
57 mtime = (fil.stat()[stat.ST_MTIME])
58 except OSError:
59 raise KeyError(key)
60
61 if fil in self.cache and mtime == self.cache[fil][1]:
62 return self.cache[fil][0]
63 try:
64 # The cached item has expired, need to read
65 obj = pickle.load(fil.open())
66 except:
67 raise KeyError(key)
68
69 self.cache[fil] = (obj,mtime)
70 return obj
71
72 def __setitem__(self,key,value):
73 """ db['key'] = 5 """
74 fil = self.root / key
75 parent = fil.parent
76 if parent and not parent.isdir():
77 parent.makedirs()
78 pickled = pickle.dump(value,fil.open('w'))
79 try:
80 self.cache[fil] = (value,fil.mtime)
81 except OSError,e:
82 if e.errno != 2:
83 raise
84
85 def __delitem__(self,key):
86 """ del db["key"] """
87 fil = self.root / key
88 self.cache.pop(fil,None)
89 try:
90 fil.remove()
91 except OSError:
92 # notfound and permission denied are ok - we
93 # lost, the other process wins the conflict
94 pass
95
96 def _normalized(self, p):
97 """ Make a key suitable for user's eyes """
98 return str(self.root.relpathto(p)).replace('\\','/')
99
100 def keys(self, globpat = None):
101 """ All keys in DB, or all keys matching a glob"""
102
103 if globpat is None:
104 files = self.root.walkfiles()
105 else:
106 files = [Path(p) for p in glob.glob(self.root/globpat)]
107 return [self._normalized(p) for p in files if p.isfile()]
108
109 def uncache(self,*items):
110 """ Removes all, or specified items from cache
111
112 Use this after reading a large amount of large objects
113 to free up memory, when you won't be needing the objects
114 for a while.
115
116 """
117 if not items:
118 self.cache = {}
119 for it in items:
120 self.cache.pop(it,None)
121
122 def waitget(self,key, maxwaittime = 60 ):
123 """ Wait (poll) for a key to get a value
124
125 Will wait for `maxwaittime` seconds before raising a KeyError.
126 The call exits normally if the `key` field in db gets a value
127 within the timeout period.
128
129 Use this for synchronizing different processes or for ensuring
130 that an unfortunately timed "db['key'] = newvalue" operation
131 in another process (which causes all 'get' operation to cause a
132 KeyError for the duration of pickling) won't screw up your program
133 logic.
134 """
135
136 wtimes = [0.2] * 3 + [0.5] * 2 + [1]
137 tries = 0
138 waited = 0
139 while 1:
140 try:
141 val = self[key]
142 return val
143 except KeyError:
144 pass
145
146 if waited > maxwaittime:
147 raise KeyError(key)
148
149 time.sleep(wtimes[tries])
150 waited+=wtimes[tries]
151 if tries < len(wtimes) -1:
152 tries+=1
153
154 def getlink(self,folder):
155 """ Get a convenient link for accessing items """
156 return PickleShareLink(self, folder)
157
158 def __repr__(self):
159 return "PickleShareDB('%s')" % self.root
160
161
162
163 class PickleShareLink:
164 """ A shortdand for accessing nested PickleShare data conveniently.
165
166 Created through PickleShareDB.getlink(), example::
167
168 lnk = db.getlink('myobjects/test')
169 lnk.foo = 2
170 lnk.bar = lnk.foo + 5
171
172 """
173 def __init__(self, db, keydir ):
174 self.__dict__.update(locals())
175
176 def __getattr__(self,key):
177 return self.__dict__['db'][self.__dict__['keydir']+'/' + key]
178 def __setattr__(self,key,val):
179 self.db[self.keydir+'/' + key] = val
180 def __repr__(self):
181 db = self.__dict__['db']
182 keys = db.keys( self.__dict__['keydir'] +"/*")
183 return "<PickleShareLink '%s': %s>" % (
184 self.__dict__['keydir'],
185 ";".join([Path(k).basename() for k in keys]))
186
187
188 def test():
189 db = PickleShareDB('~/testpickleshare')
190 db.clear()
191 print "Should be empty:",db.items()
192 db['hello'] = 15
193 db['aku ankka'] = [1,2,313]
194 db['paths/nest/ok/keyname'] = [1,(5,46)]
195 print db.keys()
196 print db.keys('paths/nest/ok/k*')
197 print dict(db) # snapsot of whole db
198 db.uncache() # frees memory, causes re-reads later
199
200 # shorthand for accessing deeply nested files
201 lnk = db.getlink('myobjects/test')
202 lnk.foo = 2
203 lnk.bar = lnk.foo + 5
204 print lnk.bar # 7
205
206 def stress():
207 db = PickleShareDB('~/fsdbtest')
208 import time,sys
209 for i in range(1000):
210 for j in range(300):
211 if i % 15 == 0 and i < 200:
212 if str(j) in db:
213 del db[str(j)]
214 continue
215
216 if j%33 == 0:
217 time.sleep(0.02)
218
219 db[str(j)] = db.get(str(j), []) + [(i,j,"proc %d" % os.getpid())]
220 print i,
221 sys.stdout.flush()
222 if i % 10 == 0:
223 db.uncache()
224
225 def main():
226 import textwrap
227 usage = textwrap.dedent("""\
228 pickleshare - manage PickleShare databases
229
230 Usage:
231
232 pickleshare dump /path/to/db > dump.txt
233 pickleshare load /path/to/db < dump.txt
234 pickleshare test /path/to/db
235 """)
236 DB = PickleShareDB
237 import sys
238 if len(sys.argv) < 2:
239 print usage
240 return
241
242 cmd = sys.argv[1]
243 args = sys.argv[2:]
244 if cmd == 'dump':
245 if not args: args= ['.']
246 db = DB(args[0])
247 import pprint
248 pprint.pprint(db.items())
249 elif cmd == 'load':
250 cont = sys.stdin.read()
251 db = DB(args[0])
252 data = eval(cont)
253 db.clear()
254 for k,v in db.items():
255 db[k] = v
256 elif cmd == 'testwait':
257 db = DB(args[0])
258 db.clear()
259 print db.waitget('250')
260 elif cmd == 'test':
261 test()
262 stress()
263
264 if __name__== "__main__":
265 main()
266
267 No newline at end of file
@@ -0,0 +1,149 b''
1 import IPython.ipapi
2 ip = IPython.ipapi.get()
3
4 import pickleshare
5
6 import inspect,pickle,os,textwrap
7 from IPython.FakeModule import FakeModule
8
9 def refresh_variables(ip):
10 db = ip.getdb()
11 for key in db.keys('autorestore/*'):
12 # strip autorestore
13 justkey = os.path.basename(key)
14 try:
15 obj = db[key]
16 except KeyError:
17 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % justkey
18 print "The error was:",sys.exc_info()[0]
19 else:
20 #print "restored",justkey,"=",obj #dbg
21 ip.user_ns()[justkey] = obj
22
23
24
25 def restore_data(self):
26 #o = ip.options()
27 #self.db = pickleshare.PickleShareDB(o.ipythondir + "/db")
28 #print "restoring ps data" # dbg
29
30 ip = self.getapi()
31 refresh_variables(ip)
32 raise IPython.ipapi.TryNext
33
34
35 ip.set_hook('late_startup_hook', restore_data)
36
37 def magic_store(self, parameter_s=''):
38 """Lightweight persistence for python variables.
39
40 Example:
41
42 ville@badger[~]|1> A = ['hello',10,'world']\\
43 ville@badger[~]|2> %store A\\
44 ville@badger[~]|3> Exit
45
46 (IPython session is closed and started again...)
47
48 ville@badger:~$ ipython -p pysh\\
49 ville@badger[~]|1> print A
50
51 ['hello', 10, 'world']
52
53 Usage:
54
55 %store - Show list of all variables and their current values\\
56 %store <var> - Store the *current* value of the variable to disk\\
57 %store -d <var> - Remove the variable and its value from storage\\
58 %store -z - Remove all variables from storage\\
59 %store -r - Refresh all variables from store (delete current vals)\\
60 %store foo >a.txt - Store value of foo to new file a.txt\\
61 %store foo >>a.txt - Append value of foo to file a.txt\\
62
63 It should be noted that if you change the value of a variable, you
64 need to %store it again if you want to persist the new value.
65
66 Note also that the variables will need to be pickleable; most basic
67 python types can be safely %stored.
68 """
69
70 opts,argsl = self.parse_options(parameter_s,'drz',mode='string')
71 args = argsl.split(None,1)
72 ip = self.getapi()
73 # delete
74 if opts.has_key('d'):
75 try:
76 todel = args[0]
77 except IndexError:
78 error('You must provide the variable to forget')
79 else:
80 try:
81 del self.db['autorestore/' + todel]
82 except:
83 error("Can't delete variable '%s'" % todel)
84 # reset
85 elif opts.has_key('z'):
86 for k in self.db.keys('autorestore/*'):
87 del self.db[k]
88
89 elif opts.has_key('r'):
90 refresh_variables(ip)
91
92
93 # run without arguments -> list variables & values
94 elif not args:
95 vars = self.db.keys('autorestore/*')
96 vars.sort()
97 if vars:
98 size = max(map(len,vars))
99 else:
100 size = 0
101
102 print 'Stored variables and their in-db values:'
103 fmt = '%-'+str(size)+'s -> %s'
104 get = self.db.get
105 for var in vars:
106 justkey = os.path.basename(var)
107 # print 30 first characters from every var
108 print fmt % (justkey,repr(get(var,'<unavailable>'))[:50])
109
110 # default action - store the variable
111 else:
112 # %store foo >file.txt or >>file.txt
113 if len(args) > 1 and args[1].startswith('>'):
114 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
115 if args[1].startswith('>>'):
116 fil = open(fnam,'a')
117 else:
118 fil = open(fnam,'w')
119 obj = ip.ev(args[0])
120 print "Writing '%s' (%s) to file '%s'." % (args[0],
121 obj.__class__.__name__, fnam)
122
123
124 if not isinstance (obj,basestring):
125 pprint(obj,fil)
126 else:
127 fil.write(obj)
128 if not obj.endswith('\n'):
129 fil.write('\n')
130
131 fil.close()
132 return
133
134 # %store foo
135 obj = ip.ev(args[0])
136 if isinstance(inspect.getmodule(obj), FakeModule):
137 print textwrap.dedent("""\
138 Warning:%s is %s
139 Proper storage of interactively declared classes (or instances
140 of those classes) is not possible! Only instances
141 of classes in real modules on file system can be %%store'd.
142 """ % (args[0], obj) )
143 return
144 #pickled = pickle.dumps(obj)
145 self.db[ 'autorestore/' + args[0] ] = obj
146 print "Stored '%s' (%s)" % (args[0], obj.__class__.__name__)
147
148 ip.expose_magic('store',magic_store)
149 No newline at end of file
@@ -1,18 +1,19 b''
1 1 """ System wide configuration file for IPython.
2 2
3 3 This will be imported by ipython for all users.
4 4
5 5 After this ipy_user_conf.py is imported, user specific configuration
6 6 should reside there.
7 7
8 8 """
9 9
10 10 import IPython.ipapi as ip
11 11
12 12 # add system wide configuration information, import extensions etc. here.
13 13 # nothing here is essential
14 14
15 15 import sys
16 16
17 17 import ext_rehashdir # %rehashdir magic
18 18 import ext_rescapture # var = !ls and var = %magic
19 import pspersistence # %store magic No newline at end of file
@@ -1,2859 +1,2754 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Magic functions for InteractiveShell.
3 3
4 $Id: Magic.py 1099 2006-01-29 21:05:57Z vivainio $"""
4 $Id: Magic.py 1107 2006-01-30 19:02:20Z vivainio $"""
5 5
6 6 #*****************************************************************************
7 7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
8 8 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
9 9 #
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #*****************************************************************************
13 13
14 14 #****************************************************************************
15 15 # Modules and globals
16 16
17 17 from IPython import Release
18 18 __author__ = '%s <%s>\n%s <%s>' % \
19 19 ( Release.authors['Janko'] + Release.authors['Fernando'] )
20 20 __license__ = Release.license
21 21
22 22 # Python standard modules
23 23 import __builtin__
24 24 import bdb
25 25 import inspect
26 26 import os
27 27 import pdb
28 28 import pydoc
29 29 import sys
30 30 import re
31 31 import tempfile
32 32 import time
33 33 import cPickle as pickle
34 34 import textwrap
35 35 from cStringIO import StringIO
36 36 from getopt import getopt,GetoptError
37 37 from pprint import pprint, pformat
38 38
39 39 # profile isn't bundled by default in Debian for license reasons
40 40 try:
41 41 import profile,pstats
42 42 except ImportError:
43 43 profile = pstats = None
44 44
45 45 # Homebrewed
46 46 from IPython import Debugger, OInspect, wildcard
47 47 from IPython.FakeModule import FakeModule
48 48 from IPython.Itpl import Itpl, itpl, printpl,itplns
49 49 from IPython.PyColorize import Parser
50 50 from IPython.ipstruct import Struct
51 51 from IPython.macro import Macro
52 52 from IPython.genutils import *
53 53 from IPython import platutils
54 54
55 55 #***************************************************************************
56 56 # Utility functions
57 57 def on_off(tag):
58 58 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
59 59 return ['OFF','ON'][tag]
60 60
61 61 class Bunch: pass
62 62
63 63 #***************************************************************************
64 64 # Main class implementing Magic functionality
65 65 class Magic:
66 66 """Magic functions for InteractiveShell.
67 67
68 68 Shell functions which can be reached as %function_name. All magic
69 69 functions should accept a string, which they can parse for their own
70 70 needs. This can make some functions easier to type, eg `%cd ../`
71 71 vs. `%cd("../")`
72 72
73 73 ALL definitions MUST begin with the prefix magic_. The user won't need it
74 74 at the command line, but it is is needed in the definition. """
75 75
76 76 # class globals
77 77 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
78 78 'Automagic is ON, % prefix NOT needed for magic functions.']
79 79
80 80 #......................................................................
81 81 # some utility functions
82 82
83 83 def __init__(self,shell):
84 84
85 85 self.options_table = {}
86 86 if profile is None:
87 87 self.magic_prun = self.profile_missing_notice
88 88 self.shell = shell
89 89
90 90 # namespace for holding state we may need
91 91 self._magic_state = Bunch()
92 92
93 93 def profile_missing_notice(self, *args, **kwargs):
94 94 error("""\
95 95 The profile module could not be found. If you are a Debian user,
96 96 it has been removed from the standard Debian package because of its non-free
97 97 license. To use profiling, please install"python2.3-profiler" from non-free.""")
98 98
99 99 def default_option(self,fn,optstr):
100 100 """Make an entry in the options_table for fn, with value optstr"""
101 101
102 102 if fn not in self.lsmagic():
103 103 error("%s is not a magic function" % fn)
104 104 self.options_table[fn] = optstr
105 105
106 106 def lsmagic(self):
107 107 """Return a list of currently available magic functions.
108 108
109 109 Gives a list of the bare names after mangling (['ls','cd', ...], not
110 110 ['magic_ls','magic_cd',...]"""
111 111
112 112 # FIXME. This needs a cleanup, in the way the magics list is built.
113 113
114 114 # magics in class definition
115 115 class_magic = lambda fn: fn.startswith('magic_') and \
116 116 callable(Magic.__dict__[fn])
117 117 # in instance namespace (run-time user additions)
118 118 inst_magic = lambda fn: fn.startswith('magic_') and \
119 119 callable(self.__dict__[fn])
120 120 # and bound magics by user (so they can access self):
121 121 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
122 122 callable(self.__class__.__dict__[fn])
123 123 magics = filter(class_magic,Magic.__dict__.keys()) + \
124 124 filter(inst_magic,self.__dict__.keys()) + \
125 125 filter(inst_bound_magic,self.__class__.__dict__.keys())
126 126 out = []
127 127 for fn in magics:
128 128 out.append(fn.replace('magic_','',1))
129 129 out.sort()
130 130 return out
131 131
132 132 def extract_input_slices(self,slices):
133 133 """Return as a string a set of input history slices.
134 134
135 135 The set of slices is given as a list of strings (like ['1','4:8','9'],
136 136 since this function is for use by magic functions which get their
137 137 arguments as strings.
138 138
139 139 Note that slices can be called with two notations:
140 140
141 141 N:M -> standard python form, means including items N...(M-1).
142 142
143 143 N-M -> include items N..M (closed endpoint)."""
144 144
145 145 cmds = []
146 146 for chunk in slices:
147 147 if ':' in chunk:
148 148 ini,fin = map(int,chunk.split(':'))
149 149 elif '-' in chunk:
150 150 ini,fin = map(int,chunk.split('-'))
151 151 fin += 1
152 152 else:
153 153 ini = int(chunk)
154 154 fin = ini+1
155 155 cmds.append(self.shell.input_hist[ini:fin])
156 156 return cmds
157 157
158 158 def _ofind(self,oname):
159 159 """Find an object in the available namespaces.
160 160
161 161 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
162 162
163 163 Has special code to detect magic functions.
164 164 """
165 165
166 166 oname = oname.strip()
167 167
168 168 # Namespaces to search in:
169 169 user_ns = self.shell.user_ns
170 170 internal_ns = self.shell.internal_ns
171 171 builtin_ns = __builtin__.__dict__
172 172 alias_ns = self.shell.alias_table
173 173
174 174 # Put them in a list. The order is important so that we find things in
175 175 # the same order that Python finds them.
176 176 namespaces = [ ('Interactive',user_ns),
177 177 ('IPython internal',internal_ns),
178 178 ('Python builtin',builtin_ns),
179 179 ('Alias',alias_ns),
180 180 ]
181 181
182 182 # initialize results to 'null'
183 183 found = 0; obj = None; ospace = None; ds = None;
184 184 ismagic = 0; isalias = 0
185 185
186 186 # Look for the given name by splitting it in parts. If the head is
187 187 # found, then we look for all the remaining parts as members, and only
188 188 # declare success if we can find them all.
189 189 oname_parts = oname.split('.')
190 190 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
191 191 for nsname,ns in namespaces:
192 192 try:
193 193 obj = ns[oname_head]
194 194 except KeyError:
195 195 continue
196 196 else:
197 197 for part in oname_rest:
198 198 try:
199 199 obj = getattr(obj,part)
200 200 except:
201 201 # Blanket except b/c some badly implemented objects
202 202 # allow __getattr__ to raise exceptions other than
203 203 # AttributeError, which then crashes IPython.
204 204 break
205 205 else:
206 206 # If we finish the for loop (no break), we got all members
207 207 found = 1
208 208 ospace = nsname
209 209 if ns == alias_ns:
210 210 isalias = 1
211 211 break # namespace loop
212 212
213 213 # Try to see if it's magic
214 214 if not found:
215 215 if oname.startswith(self.shell.ESC_MAGIC):
216 216 oname = oname[1:]
217 217 obj = getattr(self,'magic_'+oname,None)
218 218 if obj is not None:
219 219 found = 1
220 220 ospace = 'IPython internal'
221 221 ismagic = 1
222 222
223 223 # Last try: special-case some literals like '', [], {}, etc:
224 224 if not found and oname_head in ["''",'""','[]','{}','()']:
225 225 obj = eval(oname_head)
226 226 found = 1
227 227 ospace = 'Interactive'
228 228
229 229 return {'found':found, 'obj':obj, 'namespace':ospace,
230 230 'ismagic':ismagic, 'isalias':isalias}
231 231
232 232 def arg_err(self,func):
233 233 """Print docstring if incorrect arguments were passed"""
234 234 print 'Error in arguments:'
235 235 print OInspect.getdoc(func)
236 236
237 237 def format_latex(self,strng):
238 238 """Format a string for latex inclusion."""
239 239
240 240 # Characters that need to be escaped for latex:
241 241 escape_re = re.compile(r'(%|_|\$|#)',re.MULTILINE)
242 242 # Magic command names as headers:
243 243 cmd_name_re = re.compile(r'^(%s.*?):' % self.shell.ESC_MAGIC,
244 244 re.MULTILINE)
245 245 # Magic commands
246 246 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % self.shell.ESC_MAGIC,
247 247 re.MULTILINE)
248 248 # Paragraph continue
249 249 par_re = re.compile(r'\\$',re.MULTILINE)
250 250
251 251 # The "\n" symbol
252 252 newline_re = re.compile(r'\\n')
253 253
254 254 # Now build the string for output:
255 255 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
256 256 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
257 257 strng)
258 258 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
259 259 strng = par_re.sub(r'\\\\',strng)
260 260 strng = escape_re.sub(r'\\\1',strng)
261 261 strng = newline_re.sub(r'\\textbackslash{}n',strng)
262 262 return strng
263 263
264 264 def format_screen(self,strng):
265 265 """Format a string for screen printing.
266 266
267 267 This removes some latex-type format codes."""
268 268 # Paragraph continue
269 269 par_re = re.compile(r'\\$',re.MULTILINE)
270 270 strng = par_re.sub('',strng)
271 271 return strng
272 272
273 273 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
274 274 """Parse options passed to an argument string.
275 275
276 276 The interface is similar to that of getopt(), but it returns back a
277 277 Struct with the options as keys and the stripped argument string still
278 278 as a string.
279 279
280 280 arg_str is quoted as a true sys.argv vector by using shlex.split.
281 281 This allows us to easily expand variables, glob files, quote
282 282 arguments, etc.
283 283
284 284 Options:
285 285 -mode: default 'string'. If given as 'list', the argument string is
286 286 returned as a list (split on whitespace) instead of a string.
287 287
288 288 -list_all: put all option values in lists. Normally only options
289 289 appearing more than once are put in a list."""
290 290
291 291 # inject default options at the beginning of the input line
292 292 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
293 293 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
294 294
295 295 mode = kw.get('mode','string')
296 296 if mode not in ['string','list']:
297 297 raise ValueError,'incorrect mode given: %s' % mode
298 298 # Get options
299 299 list_all = kw.get('list_all',0)
300 300
301 301 # Check if we have more than one argument to warrant extra processing:
302 302 odict = {} # Dictionary with options
303 303 args = arg_str.split()
304 304 if len(args) >= 1:
305 305 # If the list of inputs only has 0 or 1 thing in it, there's no
306 306 # need to look for options
307 307 argv = shlex_split(arg_str)
308 308 # Do regular option processing
309 309 try:
310 310 opts,args = getopt(argv,opt_str,*long_opts)
311 311 except GetoptError,e:
312 312 raise GetoptError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
313 313 " ".join(long_opts)))
314 314 for o,a in opts:
315 315 if o.startswith('--'):
316 316 o = o[2:]
317 317 else:
318 318 o = o[1:]
319 319 try:
320 320 odict[o].append(a)
321 321 except AttributeError:
322 322 odict[o] = [odict[o],a]
323 323 except KeyError:
324 324 if list_all:
325 325 odict[o] = [a]
326 326 else:
327 327 odict[o] = a
328 328
329 329 # Prepare opts,args for return
330 330 opts = Struct(odict)
331 331 if mode == 'string':
332 332 args = ' '.join(args)
333 333
334 334 return opts,args
335 335
336 336 #......................................................................
337 337 # And now the actual magic functions
338 338
339 339 # Functions for IPython shell work (vars,funcs, config, etc)
340 340 def magic_lsmagic(self, parameter_s = ''):
341 341 """List currently available magic functions."""
342 342 mesc = self.shell.ESC_MAGIC
343 343 print 'Available magic functions:\n'+mesc+\
344 344 (' '+mesc).join(self.lsmagic())
345 345 print '\n' + Magic.auto_status[self.shell.rc.automagic]
346 346 return None
347 347
348 348 def magic_magic(self, parameter_s = ''):
349 349 """Print information about the magic function system."""
350 350
351 351 mode = ''
352 352 try:
353 353 if parameter_s.split()[0] == '-latex':
354 354 mode = 'latex'
355 355 except:
356 356 pass
357 357
358 358 magic_docs = []
359 359 for fname in self.lsmagic():
360 360 mname = 'magic_' + fname
361 361 for space in (Magic,self,self.__class__):
362 362 try:
363 363 fn = space.__dict__[mname]
364 364 except KeyError:
365 365 pass
366 366 else:
367 367 break
368 368 magic_docs.append('%s%s:\n\t%s\n' %(self.shell.ESC_MAGIC,
369 369 fname,fn.__doc__))
370 370 magic_docs = ''.join(magic_docs)
371 371
372 372 if mode == 'latex':
373 373 print self.format_latex(magic_docs)
374 374 return
375 375 else:
376 376 magic_docs = self.format_screen(magic_docs)
377 377
378 378 outmsg = """
379 379 IPython's 'magic' functions
380 380 ===========================
381 381
382 382 The magic function system provides a series of functions which allow you to
383 383 control the behavior of IPython itself, plus a lot of system-type
384 384 features. All these functions are prefixed with a % character, but parameters
385 385 are given without parentheses or quotes.
386 386
387 387 NOTE: If you have 'automagic' enabled (via the command line option or with the
388 388 %automagic function), you don't need to type in the % explicitly. By default,
389 389 IPython ships with automagic on, so you should only rarely need the % escape.
390 390
391 391 Example: typing '%cd mydir' (without the quotes) changes you working directory
392 392 to 'mydir', if it exists.
393 393
394 394 You can define your own magic functions to extend the system. See the supplied
395 395 ipythonrc and example-magic.py files for details (in your ipython
396 396 configuration directory, typically $HOME/.ipython/).
397 397
398 398 You can also define your own aliased names for magic functions. In your
399 399 ipythonrc file, placing a line like:
400 400
401 401 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
402 402
403 403 will define %pf as a new name for %profile.
404 404
405 405 You can also call magics in code using the ipmagic() function, which IPython
406 406 automatically adds to the builtin namespace. Type 'ipmagic?' for details.
407 407
408 408 For a list of the available magic functions, use %lsmagic. For a description
409 409 of any of them, type %magic_name?, e.g. '%cd?'.
410 410
411 411 Currently the magic system has the following functions:\n"""
412 412
413 413 mesc = self.shell.ESC_MAGIC
414 414 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
415 415 "\n\n%s%s\n\n%s" % (outmsg,
416 416 magic_docs,mesc,mesc,
417 417 (' '+mesc).join(self.lsmagic()),
418 418 Magic.auto_status[self.shell.rc.automagic] ) )
419 419
420 420 page(outmsg,screen_lines=self.shell.rc.screen_length)
421 421
422 422 def magic_automagic(self, parameter_s = ''):
423 423 """Make magic functions callable without having to type the initial %.
424 424
425 425 Toggles on/off (when off, you must call it as %automagic, of
426 426 course). Note that magic functions have lowest priority, so if there's
427 427 a variable whose name collides with that of a magic fn, automagic
428 428 won't work for that function (you get the variable instead). However,
429 429 if you delete the variable (del var), the previously shadowed magic
430 430 function becomes visible to automagic again."""
431 431
432 432 rc = self.shell.rc
433 433 rc.automagic = not rc.automagic
434 434 print '\n' + Magic.auto_status[rc.automagic]
435 435
436 436 def magic_autocall(self, parameter_s = ''):
437 437 """Make functions callable without having to type parentheses.
438 438
439 439 Usage:
440 440
441 441 %autocall [mode]
442 442
443 443 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
444 444 value is toggled on and off (remembering the previous state)."""
445 445
446 446 rc = self.shell.rc
447 447
448 448 if parameter_s:
449 449 arg = int(parameter_s)
450 450 else:
451 451 arg = 'toggle'
452 452
453 453 if not arg in (0,1,2,'toggle'):
454 454 error('Valid modes: (0->Off, 1->Smart, 2->Full')
455 455 return
456 456
457 457 if arg in (0,1,2):
458 458 rc.autocall = arg
459 459 else: # toggle
460 460 if rc.autocall:
461 461 self._magic_state.autocall_save = rc.autocall
462 462 rc.autocall = 0
463 463 else:
464 464 try:
465 465 rc.autocall = self._magic_state.autocall_save
466 466 except AttributeError:
467 467 rc.autocall = self._magic_state.autocall_save = 1
468 468
469 469 print "Automatic calling is:",['OFF','Smart','Full'][rc.autocall]
470 470
471 471 def magic_autoindent(self, parameter_s = ''):
472 472 """Toggle autoindent on/off (if available)."""
473 473
474 474 self.shell.set_autoindent()
475 475 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
476 476
477 477 def magic_system_verbose(self, parameter_s = ''):
478 478 """Toggle verbose printing of system calls on/off."""
479 479
480 480 self.shell.rc_set_toggle('system_verbose')
481 481 print "System verbose printing is:",\
482 482 ['OFF','ON'][self.shell.rc.system_verbose]
483 483
484 484 def magic_history(self, parameter_s = ''):
485 485 """Print input history (_i<n> variables), with most recent last.
486 486
487 487 %history -> print at most 40 inputs (some may be multi-line)\\
488 488 %history n -> print at most n inputs\\
489 489 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\\
490 490
491 491 Each input's number <n> is shown, and is accessible as the
492 492 automatically generated variable _i<n>. Multi-line statements are
493 493 printed starting at a new line for easy copy/paste.
494 494
495 495
496 496 Options:
497 497
498 498 -n: do NOT print line numbers. This is useful if you want to get a
499 499 printout of many lines which can be directly pasted into a text
500 500 editor.
501 501
502 502 This feature is only available if numbered prompts are in use.
503 503
504 504 -r: print the 'raw' history. IPython filters your input and
505 505 converts it all into valid Python source before executing it (things
506 506 like magics or aliases are turned into function calls, for
507 507 example). With this option, you'll see the unfiltered history
508 508 instead of the filtered version: '%cd /' will be seen as '%cd /'
509 509 instead of '_ip.magic("%cd /")'.
510 510 """
511 511
512 512 shell = self.shell
513 513 if not shell.outputcache.do_full_cache:
514 514 print 'This feature is only available if numbered prompts are in use.'
515 515 return
516 516 opts,args = self.parse_options(parameter_s,'nr',mode='list')
517 517
518 518 if opts.has_key('r'):
519 519 input_hist = shell.input_hist_raw
520 520 else:
521 521 input_hist = shell.input_hist
522 522
523 523 default_length = 40
524 524 if len(args) == 0:
525 525 final = len(input_hist)
526 526 init = max(1,final-default_length)
527 527 elif len(args) == 1:
528 528 final = len(input_hist)
529 529 init = max(1,final-int(args[0]))
530 530 elif len(args) == 2:
531 531 init,final = map(int,args)
532 532 else:
533 533 warn('%hist takes 0, 1 or 2 arguments separated by spaces.')
534 534 print self.magic_hist.__doc__
535 535 return
536 536 width = len(str(final))
537 537 line_sep = ['','\n']
538 538 print_nums = not opts.has_key('n')
539 539 for in_num in range(init,final):
540 540 inline = input_hist[in_num]
541 541 multiline = int(inline.count('\n') > 1)
542 542 if print_nums:
543 543 print '%s:%s' % (str(in_num).ljust(width),line_sep[multiline]),
544 544 print inline,
545 545
546 546 def magic_hist(self, parameter_s=''):
547 547 """Alternate name for %history."""
548 548 return self.magic_history(parameter_s)
549 549
550 550 def magic_p(self, parameter_s=''):
551 551 """Just a short alias for Python's 'print'."""
552 552 exec 'print ' + parameter_s in self.shell.user_ns
553 553
554 554 def magic_r(self, parameter_s=''):
555 555 """Repeat previous input.
556 556
557 557 If given an argument, repeats the previous command which starts with
558 558 the same string, otherwise it just repeats the previous input.
559 559
560 560 Shell escaped commands (with ! as first character) are not recognized
561 561 by this system, only pure python code and magic commands.
562 562 """
563 563
564 564 start = parameter_s.strip()
565 565 esc_magic = self.shell.ESC_MAGIC
566 566 # Identify magic commands even if automagic is on (which means
567 567 # the in-memory version is different from that typed by the user).
568 568 if self.shell.rc.automagic:
569 569 start_magic = esc_magic+start
570 570 else:
571 571 start_magic = start
572 572 # Look through the input history in reverse
573 573 for n in range(len(self.shell.input_hist)-2,0,-1):
574 574 input = self.shell.input_hist[n]
575 575 # skip plain 'r' lines so we don't recurse to infinity
576 576 if input != '_ip.magic("r")\n' and \
577 577 (input.startswith(start) or input.startswith(start_magic)):
578 578 #print 'match',`input` # dbg
579 579 print 'Executing:',input,
580 580 self.shell.runlines(input)
581 581 return
582 582 print 'No previous input matching `%s` found.' % start
583 583
584 584 def magic_page(self, parameter_s=''):
585 585 """Pretty print the object and display it through a pager.
586 586
587 587 If no parameter is given, use _ (last output)."""
588 588 # After a function contributed by Olivier Aubert, slightly modified.
589 589
590 590 oname = parameter_s and parameter_s or '_'
591 591 info = self._ofind(oname)
592 592 if info['found']:
593 593 page(pformat(info['obj']))
594 594 else:
595 595 print 'Object `%s` not found' % oname
596 596
597 597 def magic_profile(self, parameter_s=''):
598 598 """Print your currently active IPyhton profile."""
599 599 if self.shell.rc.profile:
600 600 printpl('Current IPython profile: $self.shell.rc.profile.')
601 601 else:
602 602 print 'No profile active.'
603 603
604 604 def _inspect(self,meth,oname,**kw):
605 605 """Generic interface to the inspector system.
606 606
607 607 This function is meant to be called by pdef, pdoc & friends."""
608 608
609 609 oname = oname.strip()
610 610 info = Struct(self._ofind(oname))
611 611 if info.found:
612 612 pmethod = getattr(self.shell.inspector,meth)
613 613 formatter = info.ismagic and self.format_screen or None
614 614 if meth == 'pdoc':
615 615 pmethod(info.obj,oname,formatter)
616 616 elif meth == 'pinfo':
617 617 pmethod(info.obj,oname,formatter,info,**kw)
618 618 else:
619 619 pmethod(info.obj,oname)
620 620 else:
621 621 print 'Object `%s` not found.' % oname
622 622 return 'not found' # so callers can take other action
623 623
624 624 def magic_pdef(self, parameter_s=''):
625 625 """Print the definition header for any callable object.
626 626
627 627 If the object is a class, print the constructor information."""
628 628 self._inspect('pdef',parameter_s)
629 629
630 630 def magic_pdoc(self, parameter_s=''):
631 631 """Print the docstring for an object.
632 632
633 633 If the given object is a class, it will print both the class and the
634 634 constructor docstrings."""
635 635 self._inspect('pdoc',parameter_s)
636 636
637 637 def magic_psource(self, parameter_s=''):
638 638 """Print (or run through pager) the source code for an object."""
639 639 self._inspect('psource',parameter_s)
640 640
641 641 def magic_pfile(self, parameter_s=''):
642 642 """Print (or run through pager) the file where an object is defined.
643 643
644 644 The file opens at the line where the object definition begins. IPython
645 645 will honor the environment variable PAGER if set, and otherwise will
646 646 do its best to print the file in a convenient form.
647 647
648 648 If the given argument is not an object currently defined, IPython will
649 649 try to interpret it as a filename (automatically adding a .py extension
650 650 if needed). You can thus use %pfile as a syntax highlighting code
651 651 viewer."""
652 652
653 653 # first interpret argument as an object name
654 654 out = self._inspect('pfile',parameter_s)
655 655 # if not, try the input as a filename
656 656 if out == 'not found':
657 657 try:
658 658 filename = get_py_filename(parameter_s)
659 659 except IOError,msg:
660 660 print msg
661 661 return
662 662 page(self.shell.inspector.format(file(filename).read()))
663 663
664 664 def magic_pinfo(self, parameter_s=''):
665 665 """Provide detailed information about an object.
666 666
667 667 '%pinfo object' is just a synonym for object? or ?object."""
668 668
669 669 #print 'pinfo par: <%s>' % parameter_s # dbg
670 670
671 671 # detail_level: 0 -> obj? , 1 -> obj??
672 672 detail_level = 0
673 673 # We need to detect if we got called as 'pinfo pinfo foo', which can
674 674 # happen if the user types 'pinfo foo?' at the cmd line.
675 675 pinfo,qmark1,oname,qmark2 = \
676 676 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
677 677 if pinfo or qmark1 or qmark2:
678 678 detail_level = 1
679 679 if "*" in oname:
680 680 self.magic_psearch(oname)
681 681 else:
682 682 self._inspect('pinfo',oname,detail_level=detail_level)
683 683
684 684 def magic_psearch(self, parameter_s=''):
685 685 """Search for object in namespaces by wildcard.
686 686
687 687 %psearch [options] PATTERN [OBJECT TYPE]
688 688
689 689 Note: ? can be used as a synonym for %psearch, at the beginning or at
690 690 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
691 691 rest of the command line must be unchanged (options come first), so
692 692 for example the following forms are equivalent
693 693
694 694 %psearch -i a* function
695 695 -i a* function?
696 696 ?-i a* function
697 697
698 698 Arguments:
699 699
700 700 PATTERN
701 701
702 702 where PATTERN is a string containing * as a wildcard similar to its
703 703 use in a shell. The pattern is matched in all namespaces on the
704 704 search path. By default objects starting with a single _ are not
705 705 matched, many IPython generated objects have a single
706 706 underscore. The default is case insensitive matching. Matching is
707 707 also done on the attributes of objects and not only on the objects
708 708 in a module.
709 709
710 710 [OBJECT TYPE]
711 711
712 712 Is the name of a python type from the types module. The name is
713 713 given in lowercase without the ending type, ex. StringType is
714 714 written string. By adding a type here only objects matching the
715 715 given type are matched. Using all here makes the pattern match all
716 716 types (this is the default).
717 717
718 718 Options:
719 719
720 720 -a: makes the pattern match even objects whose names start with a
721 721 single underscore. These names are normally ommitted from the
722 722 search.
723 723
724 724 -i/-c: make the pattern case insensitive/sensitive. If neither of
725 725 these options is given, the default is read from your ipythonrc
726 726 file. The option name which sets this value is
727 727 'wildcards_case_sensitive'. If this option is not specified in your
728 728 ipythonrc file, IPython's internal default is to do a case sensitive
729 729 search.
730 730
731 731 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
732 732 specifiy can be searched in any of the following namespaces:
733 733 'builtin', 'user', 'user_global','internal', 'alias', where
734 734 'builtin' and 'user' are the search defaults. Note that you should
735 735 not use quotes when specifying namespaces.
736 736
737 737 'Builtin' contains the python module builtin, 'user' contains all
738 738 user data, 'alias' only contain the shell aliases and no python
739 739 objects, 'internal' contains objects used by IPython. The
740 740 'user_global' namespace is only used by embedded IPython instances,
741 741 and it contains module-level globals. You can add namespaces to the
742 742 search with -s or exclude them with -e (these options can be given
743 743 more than once).
744 744
745 745 Examples:
746 746
747 747 %psearch a* -> objects beginning with an a
748 748 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
749 749 %psearch a* function -> all functions beginning with an a
750 750 %psearch re.e* -> objects beginning with an e in module re
751 751 %psearch r*.e* -> objects that start with e in modules starting in r
752 752 %psearch r*.* string -> all strings in modules beginning with r
753 753
754 754 Case sensitve search:
755 755
756 756 %psearch -c a* list all object beginning with lower case a
757 757
758 758 Show objects beginning with a single _:
759 759
760 760 %psearch -a _* list objects beginning with a single underscore"""
761 761
762 762 # default namespaces to be searched
763 763 def_search = ['user','builtin']
764 764
765 765 # Process options/args
766 766 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
767 767 opt = opts.get
768 768 shell = self.shell
769 769 psearch = shell.inspector.psearch
770 770
771 771 # select case options
772 772 if opts.has_key('i'):
773 773 ignore_case = True
774 774 elif opts.has_key('c'):
775 775 ignore_case = False
776 776 else:
777 777 ignore_case = not shell.rc.wildcards_case_sensitive
778 778
779 779 # Build list of namespaces to search from user options
780 780 def_search.extend(opt('s',[]))
781 781 ns_exclude = ns_exclude=opt('e',[])
782 782 ns_search = [nm for nm in def_search if nm not in ns_exclude]
783 783
784 784 # Call the actual search
785 785 try:
786 786 psearch(args,shell.ns_table,ns_search,
787 787 show_all=opt('a'),ignore_case=ignore_case)
788 788 except:
789 789 shell.showtraceback()
790 790
791 791 def magic_who_ls(self, parameter_s=''):
792 792 """Return a sorted list of all interactive variables.
793 793
794 794 If arguments are given, only variables of types matching these
795 795 arguments are returned."""
796 796
797 797 user_ns = self.shell.user_ns
798 798 internal_ns = self.shell.internal_ns
799 799 user_config_ns = self.shell.user_config_ns
800 800 out = []
801 801 typelist = parameter_s.split()
802 802
803 803 for i in user_ns:
804 804 if not (i.startswith('_') or i.startswith('_i')) \
805 805 and not (i in internal_ns or i in user_config_ns):
806 806 if typelist:
807 807 if type(user_ns[i]).__name__ in typelist:
808 808 out.append(i)
809 809 else:
810 810 out.append(i)
811 811 out.sort()
812 812 return out
813 813
814 814 def magic_who(self, parameter_s=''):
815 815 """Print all interactive variables, with some minimal formatting.
816 816
817 817 If any arguments are given, only variables whose type matches one of
818 818 these are printed. For example:
819 819
820 820 %who function str
821 821
822 822 will only list functions and strings, excluding all other types of
823 823 variables. To find the proper type names, simply use type(var) at a
824 824 command line to see how python prints type names. For example:
825 825
826 826 In [1]: type('hello')\\
827 827 Out[1]: <type 'str'>
828 828
829 829 indicates that the type name for strings is 'str'.
830 830
831 831 %who always excludes executed names loaded through your configuration
832 832 file and things which are internal to IPython.
833 833
834 834 This is deliberate, as typically you may load many modules and the
835 835 purpose of %who is to show you only what you've manually defined."""
836 836
837 837 varlist = self.magic_who_ls(parameter_s)
838 838 if not varlist:
839 839 print 'Interactive namespace is empty.'
840 840 return
841 841
842 842 # if we have variables, move on...
843 843
844 844 # stupid flushing problem: when prompts have no separators, stdout is
845 845 # getting lost. I'm starting to think this is a python bug. I'm having
846 846 # to force a flush with a print because even a sys.stdout.flush
847 847 # doesn't seem to do anything!
848 848
849 849 count = 0
850 850 for i in varlist:
851 851 print i+'\t',
852 852 count += 1
853 853 if count > 8:
854 854 count = 0
855 855 print
856 856 sys.stdout.flush() # FIXME. Why the hell isn't this flushing???
857 857
858 858 print # well, this does force a flush at the expense of an extra \n
859 859
860 860 def magic_whos(self, parameter_s=''):
861 861 """Like %who, but gives some extra information about each variable.
862 862
863 863 The same type filtering of %who can be applied here.
864 864
865 865 For all variables, the type is printed. Additionally it prints:
866 866
867 867 - For {},[],(): their length.
868 868
869 869 - For Numeric arrays, a summary with shape, number of elements,
870 870 typecode and size in memory.
871 871
872 872 - Everything else: a string representation, snipping their middle if
873 873 too long."""
874 874
875 875 varnames = self.magic_who_ls(parameter_s)
876 876 if not varnames:
877 877 print 'Interactive namespace is empty.'
878 878 return
879 879
880 880 # if we have variables, move on...
881 881
882 882 # for these types, show len() instead of data:
883 883 seq_types = [types.DictType,types.ListType,types.TupleType]
884 884
885 885 # for Numeric arrays, display summary info
886 886 try:
887 887 import Numeric
888 888 except ImportError:
889 889 array_type = None
890 890 else:
891 891 array_type = Numeric.ArrayType.__name__
892 892
893 893 # Find all variable names and types so we can figure out column sizes
894 894 get_vars = lambda i: self.shell.user_ns[i]
895 895 type_name = lambda v: type(v).__name__
896 896 varlist = map(get_vars,varnames)
897 897
898 898 typelist = []
899 899 for vv in varlist:
900 900 tt = type_name(vv)
901 901 if tt=='instance':
902 902 typelist.append(str(vv.__class__))
903 903 else:
904 904 typelist.append(tt)
905 905
906 906 # column labels and # of spaces as separator
907 907 varlabel = 'Variable'
908 908 typelabel = 'Type'
909 909 datalabel = 'Data/Info'
910 910 colsep = 3
911 911 # variable format strings
912 912 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
913 913 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
914 914 aformat = "%s: %s elems, type `%s`, %s bytes"
915 915 # find the size of the columns to format the output nicely
916 916 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
917 917 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
918 918 # table header
919 919 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
920 920 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
921 921 # and the table itself
922 922 kb = 1024
923 923 Mb = 1048576 # kb**2
924 924 for vname,var,vtype in zip(varnames,varlist,typelist):
925 925 print itpl(vformat),
926 926 if vtype in seq_types:
927 927 print len(var)
928 928 elif vtype==array_type:
929 929 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
930 930 vsize = Numeric.size(var)
931 931 vbytes = vsize*var.itemsize()
932 932 if vbytes < 100000:
933 933 print aformat % (vshape,vsize,var.typecode(),vbytes)
934 934 else:
935 935 print aformat % (vshape,vsize,var.typecode(),vbytes),
936 936 if vbytes < Mb:
937 937 print '(%s kb)' % (vbytes/kb,)
938 938 else:
939 939 print '(%s Mb)' % (vbytes/Mb,)
940 940 else:
941 941 vstr = str(var).replace('\n','\\n')
942 942 if len(vstr) < 50:
943 943 print vstr
944 944 else:
945 945 printpl(vfmt_short)
946 946
947 947 def magic_reset(self, parameter_s=''):
948 948 """Resets the namespace by removing all names defined by the user.
949 949
950 950 Input/Output history are left around in case you need them."""
951 951
952 952 ans = raw_input(
953 953 "Once deleted, variables cannot be recovered. Proceed (y/n)? ")
954 954 if not ans.lower() == 'y':
955 955 print 'Nothing done.'
956 956 return
957 957 user_ns = self.shell.user_ns
958 958 for i in self.magic_who_ls():
959 959 del(user_ns[i])
960 960
961 961 def magic_config(self,parameter_s=''):
962 962 """Show IPython's internal configuration."""
963 963
964 964 page('Current configuration structure:\n'+
965 965 pformat(self.shell.rc.dict()))
966 966
967 967 def magic_logstart(self,parameter_s=''):
968 968 """Start logging anywhere in a session.
969 969
970 970 %logstart [-o|-t] [log_name [log_mode]]
971 971
972 972 If no name is given, it defaults to a file named 'ipython_log.py' in your
973 973 current directory, in 'rotate' mode (see below).
974 974
975 975 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
976 976 history up to that point and then continues logging.
977 977
978 978 %logstart takes a second optional parameter: logging mode. This can be one
979 979 of (note that the modes are given unquoted):\\
980 980 append: well, that says it.\\
981 981 backup: rename (if exists) to name~ and start name.\\
982 982 global: single logfile in your home dir, appended to.\\
983 983 over : overwrite existing log.\\
984 984 rotate: create rotating logs name.1~, name.2~, etc.
985 985
986 986 Options:
987 987
988 988 -o: log also IPython's output. In this mode, all commands which
989 989 generate an Out[NN] prompt are recorded to the logfile, right after
990 990 their corresponding input line. The output lines are always
991 991 prepended with a '#[Out]# ' marker, so that the log remains valid
992 992 Python code.
993 993
994 994 Since this marker is always the same, filtering only the output from
995 995 a log is very easy, using for example a simple awk call:
996 996
997 997 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
998 998
999 999 -t: put timestamps before each input line logged (these are put in
1000 1000 comments)."""
1001 1001
1002 1002 opts,par = self.parse_options(parameter_s,'ot')
1003 1003 log_output = 'o' in opts
1004 1004 timestamp = 't' in opts
1005 1005
1006 1006 rc = self.shell.rc
1007 1007 logger = self.shell.logger
1008 1008
1009 1009 # if no args are given, the defaults set in the logger constructor by
1010 1010 # ipytohn remain valid
1011 1011 if par:
1012 1012 try:
1013 1013 logfname,logmode = par.split()
1014 1014 except:
1015 1015 logfname = par
1016 1016 logmode = 'backup'
1017 1017 else:
1018 1018 logfname = logger.logfname
1019 1019 logmode = logger.logmode
1020 1020 # put logfname into rc struct as if it had been called on the command
1021 1021 # line, so it ends up saved in the log header Save it in case we need
1022 1022 # to restore it...
1023 1023 old_logfile = rc.opts.get('logfile','')
1024 1024 if logfname:
1025 1025 logfname = os.path.expanduser(logfname)
1026 1026 rc.opts.logfile = logfname
1027 1027 loghead = self.shell.loghead_tpl % (rc.opts,rc.args)
1028 1028 try:
1029 1029 started = logger.logstart(logfname,loghead,logmode,
1030 1030 log_output,timestamp)
1031 1031 except:
1032 1032 rc.opts.logfile = old_logfile
1033 1033 warn("Couldn't start log: %s" % sys.exc_info()[1])
1034 1034 else:
1035 1035 # log input history up to this point, optionally interleaving
1036 1036 # output if requested
1037 1037
1038 1038 if timestamp:
1039 1039 # disable timestamping for the previous history, since we've
1040 1040 # lost those already (no time machine here).
1041 1041 logger.timestamp = False
1042 1042 if log_output:
1043 1043 log_write = logger.log_write
1044 1044 input_hist = self.shell.input_hist
1045 1045 output_hist = self.shell.output_hist
1046 1046 for n in range(1,len(input_hist)-1):
1047 1047 log_write(input_hist[n].rstrip())
1048 1048 if n in output_hist:
1049 1049 log_write(repr(output_hist[n]),'output')
1050 1050 else:
1051 1051 logger.log_write(self.shell.input_hist[1:])
1052 1052 if timestamp:
1053 1053 # re-enable timestamping
1054 1054 logger.timestamp = True
1055 1055
1056 1056 print ('Activating auto-logging. '
1057 1057 'Current session state plus future input saved.')
1058 1058 logger.logstate()
1059 1059
1060 1060 def magic_logoff(self,parameter_s=''):
1061 1061 """Temporarily stop logging.
1062 1062
1063 1063 You must have previously started logging."""
1064 1064 self.shell.logger.switch_log(0)
1065 1065
1066 1066 def magic_logon(self,parameter_s=''):
1067 1067 """Restart logging.
1068 1068
1069 1069 This function is for restarting logging which you've temporarily
1070 1070 stopped with %logoff. For starting logging for the first time, you
1071 1071 must use the %logstart function, which allows you to specify an
1072 1072 optional log filename."""
1073 1073
1074 1074 self.shell.logger.switch_log(1)
1075 1075
1076 1076 def magic_logstate(self,parameter_s=''):
1077 1077 """Print the status of the logging system."""
1078 1078
1079 1079 self.shell.logger.logstate()
1080 1080
1081 1081 def magic_pdb(self, parameter_s=''):
1082 1082 """Control the calling of the pdb interactive debugger.
1083 1083
1084 1084 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1085 1085 argument it works as a toggle.
1086 1086
1087 1087 When an exception is triggered, IPython can optionally call the
1088 1088 interactive pdb debugger after the traceback printout. %pdb toggles
1089 1089 this feature on and off."""
1090 1090
1091 1091 par = parameter_s.strip().lower()
1092 1092
1093 1093 if par:
1094 1094 try:
1095 1095 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1096 1096 except KeyError:
1097 1097 print ('Incorrect argument. Use on/1, off/0, '
1098 1098 'or nothing for a toggle.')
1099 1099 return
1100 1100 else:
1101 1101 # toggle
1102 1102 new_pdb = not self.shell.InteractiveTB.call_pdb
1103 1103
1104 1104 # set on the shell
1105 1105 self.shell.call_pdb = new_pdb
1106 1106 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1107 1107
1108 1108 def magic_prun(self, parameter_s ='',user_mode=1,
1109 1109 opts=None,arg_lst=None,prog_ns=None):
1110 1110
1111 1111 """Run a statement through the python code profiler.
1112 1112
1113 1113 Usage:\\
1114 1114 %prun [options] statement
1115 1115
1116 1116 The given statement (which doesn't require quote marks) is run via the
1117 1117 python profiler in a manner similar to the profile.run() function.
1118 1118 Namespaces are internally managed to work correctly; profile.run
1119 1119 cannot be used in IPython because it makes certain assumptions about
1120 1120 namespaces which do not hold under IPython.
1121 1121
1122 1122 Options:
1123 1123
1124 1124 -l <limit>: you can place restrictions on what or how much of the
1125 1125 profile gets printed. The limit value can be:
1126 1126
1127 1127 * A string: only information for function names containing this string
1128 1128 is printed.
1129 1129
1130 1130 * An integer: only these many lines are printed.
1131 1131
1132 1132 * A float (between 0 and 1): this fraction of the report is printed
1133 1133 (for example, use a limit of 0.4 to see the topmost 40% only).
1134 1134
1135 1135 You can combine several limits with repeated use of the option. For
1136 1136 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1137 1137 information about class constructors.
1138 1138
1139 1139 -r: return the pstats.Stats object generated by the profiling. This
1140 1140 object has all the information about the profile in it, and you can
1141 1141 later use it for further analysis or in other functions.
1142 1142
1143 1143 Since magic functions have a particular form of calling which prevents
1144 1144 you from writing something like:\\
1145 1145 In [1]: p = %prun -r print 4 # invalid!\\
1146 1146 you must instead use IPython's automatic variables to assign this:\\
1147 1147 In [1]: %prun -r print 4 \\
1148 1148 Out[1]: <pstats.Stats instance at 0x8222cec>\\
1149 1149 In [2]: stats = _
1150 1150
1151 1151 If you really need to assign this value via an explicit function call,
1152 1152 you can always tap directly into the true name of the magic function
1153 1153 by using the _ip.magic function:\\
1154 1154 In [3]: stats = _ip.magic('prun','-r print 4')
1155 1155
1156 1156 You can type _ip.magic? for more details.
1157 1157
1158 1158 -s <key>: sort profile by given key. You can provide more than one key
1159 1159 by using the option several times: '-s key1 -s key2 -s key3...'. The
1160 1160 default sorting key is 'time'.
1161 1161
1162 1162 The following is copied verbatim from the profile documentation
1163 1163 referenced below:
1164 1164
1165 1165 When more than one key is provided, additional keys are used as
1166 1166 secondary criteria when the there is equality in all keys selected
1167 1167 before them.
1168 1168
1169 1169 Abbreviations can be used for any key names, as long as the
1170 1170 abbreviation is unambiguous. The following are the keys currently
1171 1171 defined:
1172 1172
1173 1173 Valid Arg Meaning\\
1174 1174 "calls" call count\\
1175 1175 "cumulative" cumulative time\\
1176 1176 "file" file name\\
1177 1177 "module" file name\\
1178 1178 "pcalls" primitive call count\\
1179 1179 "line" line number\\
1180 1180 "name" function name\\
1181 1181 "nfl" name/file/line\\
1182 1182 "stdname" standard name\\
1183 1183 "time" internal time
1184 1184
1185 1185 Note that all sorts on statistics are in descending order (placing
1186 1186 most time consuming items first), where as name, file, and line number
1187 1187 searches are in ascending order (i.e., alphabetical). The subtle
1188 1188 distinction between "nfl" and "stdname" is that the standard name is a
1189 1189 sort of the name as printed, which means that the embedded line
1190 1190 numbers get compared in an odd way. For example, lines 3, 20, and 40
1191 1191 would (if the file names were the same) appear in the string order
1192 1192 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1193 1193 line numbers. In fact, sort_stats("nfl") is the same as
1194 1194 sort_stats("name", "file", "line").
1195 1195
1196 1196 -T <filename>: save profile results as shown on screen to a text
1197 1197 file. The profile is still shown on screen.
1198 1198
1199 1199 -D <filename>: save (via dump_stats) profile statistics to given
1200 1200 filename. This data is in a format understod by the pstats module, and
1201 1201 is generated by a call to the dump_stats() method of profile
1202 1202 objects. The profile is still shown on screen.
1203 1203
1204 1204 If you want to run complete programs under the profiler's control, use
1205 1205 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1206 1206 contains profiler specific options as described here.
1207 1207
1208 1208 You can read the complete documentation for the profile module with:\\
1209 1209 In [1]: import profile; profile.help() """
1210 1210
1211 1211 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1212 1212 # protect user quote marks
1213 1213 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1214 1214
1215 1215 if user_mode: # regular user call
1216 1216 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1217 1217 list_all=1)
1218 1218 namespace = self.shell.user_ns
1219 1219 else: # called to run a program by %run -p
1220 1220 try:
1221 1221 filename = get_py_filename(arg_lst[0])
1222 1222 except IOError,msg:
1223 1223 error(msg)
1224 1224 return
1225 1225
1226 1226 arg_str = 'execfile(filename,prog_ns)'
1227 1227 namespace = locals()
1228 1228
1229 1229 opts.merge(opts_def)
1230 1230
1231 1231 prof = profile.Profile()
1232 1232 try:
1233 1233 prof = prof.runctx(arg_str,namespace,namespace)
1234 1234 sys_exit = ''
1235 1235 except SystemExit:
1236 1236 sys_exit = """*** SystemExit exception caught in code being profiled."""
1237 1237
1238 1238 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1239 1239
1240 1240 lims = opts.l
1241 1241 if lims:
1242 1242 lims = [] # rebuild lims with ints/floats/strings
1243 1243 for lim in opts.l:
1244 1244 try:
1245 1245 lims.append(int(lim))
1246 1246 except ValueError:
1247 1247 try:
1248 1248 lims.append(float(lim))
1249 1249 except ValueError:
1250 1250 lims.append(lim)
1251 1251
1252 1252 # trap output
1253 1253 sys_stdout = sys.stdout
1254 1254 stdout_trap = StringIO()
1255 1255 try:
1256 1256 sys.stdout = stdout_trap
1257 1257 stats.print_stats(*lims)
1258 1258 finally:
1259 1259 sys.stdout = sys_stdout
1260 1260 output = stdout_trap.getvalue()
1261 1261 output = output.rstrip()
1262 1262
1263 1263 page(output,screen_lines=self.shell.rc.screen_length)
1264 1264 print sys_exit,
1265 1265
1266 1266 dump_file = opts.D[0]
1267 1267 text_file = opts.T[0]
1268 1268 if dump_file:
1269 1269 prof.dump_stats(dump_file)
1270 1270 print '\n*** Profile stats marshalled to file',\
1271 1271 `dump_file`+'.',sys_exit
1272 1272 if text_file:
1273 1273 file(text_file,'w').write(output)
1274 1274 print '\n*** Profile printout saved to text file',\
1275 1275 `text_file`+'.',sys_exit
1276 1276
1277 1277 if opts.has_key('r'):
1278 1278 return stats
1279 1279 else:
1280 1280 return None
1281 1281
1282 1282 def magic_run(self, parameter_s ='',runner=None):
1283 1283 """Run the named file inside IPython as a program.
1284 1284
1285 1285 Usage:\\
1286 1286 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1287 1287
1288 1288 Parameters after the filename are passed as command-line arguments to
1289 1289 the program (put in sys.argv). Then, control returns to IPython's
1290 1290 prompt.
1291 1291
1292 1292 This is similar to running at a system prompt:\\
1293 1293 $ python file args\\
1294 1294 but with the advantage of giving you IPython's tracebacks, and of
1295 1295 loading all variables into your interactive namespace for further use
1296 1296 (unless -p is used, see below).
1297 1297
1298 1298 The file is executed in a namespace initially consisting only of
1299 1299 __name__=='__main__' and sys.argv constructed as indicated. It thus
1300 1300 sees its environment as if it were being run as a stand-alone
1301 1301 program. But after execution, the IPython interactive namespace gets
1302 1302 updated with all variables defined in the program (except for __name__
1303 1303 and sys.argv). This allows for very convenient loading of code for
1304 1304 interactive work, while giving each program a 'clean sheet' to run in.
1305 1305
1306 1306 Options:
1307 1307
1308 1308 -n: __name__ is NOT set to '__main__', but to the running file's name
1309 1309 without extension (as python does under import). This allows running
1310 1310 scripts and reloading the definitions in them without calling code
1311 1311 protected by an ' if __name__ == "__main__" ' clause.
1312 1312
1313 1313 -i: run the file in IPython's namespace instead of an empty one. This
1314 1314 is useful if you are experimenting with code written in a text editor
1315 1315 which depends on variables defined interactively.
1316 1316
1317 1317 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1318 1318 being run. This is particularly useful if IPython is being used to
1319 1319 run unittests, which always exit with a sys.exit() call. In such
1320 1320 cases you are interested in the output of the test results, not in
1321 1321 seeing a traceback of the unittest module.
1322 1322
1323 1323 -t: print timing information at the end of the run. IPython will give
1324 1324 you an estimated CPU time consumption for your script, which under
1325 1325 Unix uses the resource module to avoid the wraparound problems of
1326 1326 time.clock(). Under Unix, an estimate of time spent on system tasks
1327 1327 is also given (for Windows platforms this is reported as 0.0).
1328 1328
1329 1329 If -t is given, an additional -N<N> option can be given, where <N>
1330 1330 must be an integer indicating how many times you want the script to
1331 1331 run. The final timing report will include total and per run results.
1332 1332
1333 1333 For example (testing the script uniq_stable.py):
1334 1334
1335 1335 In [1]: run -t uniq_stable
1336 1336
1337 1337 IPython CPU timings (estimated):\\
1338 1338 User : 0.19597 s.\\
1339 1339 System: 0.0 s.\\
1340 1340
1341 1341 In [2]: run -t -N5 uniq_stable
1342 1342
1343 1343 IPython CPU timings (estimated):\\
1344 1344 Total runs performed: 5\\
1345 1345 Times : Total Per run\\
1346 1346 User : 0.910862 s, 0.1821724 s.\\
1347 1347 System: 0.0 s, 0.0 s.
1348 1348
1349 1349 -d: run your program under the control of pdb, the Python debugger.
1350 1350 This allows you to execute your program step by step, watch variables,
1351 1351 etc. Internally, what IPython does is similar to calling:
1352 1352
1353 1353 pdb.run('execfile("YOURFILENAME")')
1354 1354
1355 1355 with a breakpoint set on line 1 of your file. You can change the line
1356 1356 number for this automatic breakpoint to be <N> by using the -bN option
1357 1357 (where N must be an integer). For example:
1358 1358
1359 1359 %run -d -b40 myscript
1360 1360
1361 1361 will set the first breakpoint at line 40 in myscript.py. Note that
1362 1362 the first breakpoint must be set on a line which actually does
1363 1363 something (not a comment or docstring) for it to stop execution.
1364 1364
1365 1365 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1366 1366 first enter 'c' (without qoutes) to start execution up to the first
1367 1367 breakpoint.
1368 1368
1369 1369 Entering 'help' gives information about the use of the debugger. You
1370 1370 can easily see pdb's full documentation with "import pdb;pdb.help()"
1371 1371 at a prompt.
1372 1372
1373 1373 -p: run program under the control of the Python profiler module (which
1374 1374 prints a detailed report of execution times, function calls, etc).
1375 1375
1376 1376 You can pass other options after -p which affect the behavior of the
1377 1377 profiler itself. See the docs for %prun for details.
1378 1378
1379 1379 In this mode, the program's variables do NOT propagate back to the
1380 1380 IPython interactive namespace (because they remain in the namespace
1381 1381 where the profiler executes them).
1382 1382
1383 1383 Internally this triggers a call to %prun, see its documentation for
1384 1384 details on the options available specifically for profiling."""
1385 1385
1386 1386 # get arguments and set sys.argv for program to be run.
1387 1387 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1388 1388 mode='list',list_all=1)
1389 1389
1390 1390 try:
1391 1391 filename = get_py_filename(arg_lst[0])
1392 1392 except IndexError:
1393 1393 warn('you must provide at least a filename.')
1394 1394 print '\n%run:\n',OInspect.getdoc(self.magic_run)
1395 1395 return
1396 1396 except IOError,msg:
1397 1397 error(msg)
1398 1398 return
1399 1399
1400 1400 # Control the response to exit() calls made by the script being run
1401 1401 exit_ignore = opts.has_key('e')
1402 1402
1403 1403 # Make sure that the running script gets a proper sys.argv as if it
1404 1404 # were run from a system shell.
1405 1405 save_argv = sys.argv # save it for later restoring
1406 1406 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1407 1407
1408 1408 if opts.has_key('i'):
1409 1409 prog_ns = self.shell.user_ns
1410 1410 __name__save = self.shell.user_ns['__name__']
1411 1411 prog_ns['__name__'] = '__main__'
1412 1412 else:
1413 1413 if opts.has_key('n'):
1414 1414 name = os.path.splitext(os.path.basename(filename))[0]
1415 1415 else:
1416 1416 name = '__main__'
1417 1417 prog_ns = {'__name__':name}
1418 1418
1419 1419 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1420 1420 # set the __file__ global in the script's namespace
1421 1421 prog_ns['__file__'] = filename
1422 1422
1423 1423 # pickle fix. See iplib for an explanation. But we need to make sure
1424 1424 # that, if we overwrite __main__, we replace it at the end
1425 1425 if prog_ns['__name__'] == '__main__':
1426 1426 restore_main = sys.modules['__main__']
1427 1427 else:
1428 1428 restore_main = False
1429 1429
1430 1430 sys.modules[prog_ns['__name__']] = FakeModule(prog_ns)
1431 1431
1432 1432 stats = None
1433 1433 try:
1434 1434 if opts.has_key('p'):
1435 1435 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1436 1436 else:
1437 1437 if opts.has_key('d'):
1438 1438 deb = Debugger.Pdb(self.shell.rc.colors)
1439 1439 # reset Breakpoint state, which is moronically kept
1440 1440 # in a class
1441 1441 bdb.Breakpoint.next = 1
1442 1442 bdb.Breakpoint.bplist = {}
1443 1443 bdb.Breakpoint.bpbynumber = [None]
1444 1444 # Set an initial breakpoint to stop execution
1445 1445 maxtries = 10
1446 1446 bp = int(opts.get('b',[1])[0])
1447 1447 checkline = deb.checkline(filename,bp)
1448 1448 if not checkline:
1449 1449 for bp in range(bp+1,bp+maxtries+1):
1450 1450 if deb.checkline(filename,bp):
1451 1451 break
1452 1452 else:
1453 1453 msg = ("\nI failed to find a valid line to set "
1454 1454 "a breakpoint\n"
1455 1455 "after trying up to line: %s.\n"
1456 1456 "Please set a valid breakpoint manually "
1457 1457 "with the -b option." % bp)
1458 1458 error(msg)
1459 1459 return
1460 1460 # if we find a good linenumber, set the breakpoint
1461 1461 deb.do_break('%s:%s' % (filename,bp))
1462 1462 # Start file run
1463 1463 print "NOTE: Enter 'c' at the",
1464 1464 print "ipdb> prompt to start your script."
1465 1465 try:
1466 1466 deb.run('execfile("%s")' % filename,prog_ns)
1467 1467 except:
1468 1468 etype, value, tb = sys.exc_info()
1469 1469 # Skip three frames in the traceback: the %run one,
1470 1470 # one inside bdb.py, and the command-line typed by the
1471 1471 # user (run by exec in pdb itself).
1472 1472 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1473 1473 else:
1474 1474 if runner is None:
1475 1475 runner = self.shell.safe_execfile
1476 1476 if opts.has_key('t'):
1477 1477 try:
1478 1478 nruns = int(opts['N'][0])
1479 1479 if nruns < 1:
1480 1480 error('Number of runs must be >=1')
1481 1481 return
1482 1482 except (KeyError):
1483 1483 nruns = 1
1484 1484 if nruns == 1:
1485 1485 t0 = clock2()
1486 1486 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1487 1487 t1 = clock2()
1488 1488 t_usr = t1[0]-t0[0]
1489 1489 t_sys = t1[1]-t1[1]
1490 1490 print "\nIPython CPU timings (estimated):"
1491 1491 print " User : %10s s." % t_usr
1492 1492 print " System: %10s s." % t_sys
1493 1493 else:
1494 1494 runs = range(nruns)
1495 1495 t0 = clock2()
1496 1496 for nr in runs:
1497 1497 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1498 1498 t1 = clock2()
1499 1499 t_usr = t1[0]-t0[0]
1500 1500 t_sys = t1[1]-t1[1]
1501 1501 print "\nIPython CPU timings (estimated):"
1502 1502 print "Total runs performed:",nruns
1503 1503 print " Times : %10s %10s" % ('Total','Per run')
1504 1504 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1505 1505 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1506 1506
1507 1507 else:
1508 1508 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1509 1509 if opts.has_key('i'):
1510 1510 self.shell.user_ns['__name__'] = __name__save
1511 1511 else:
1512 1512 # update IPython interactive namespace
1513 1513 del prog_ns['__name__']
1514 1514 self.shell.user_ns.update(prog_ns)
1515 1515 finally:
1516 1516 sys.argv = save_argv
1517 1517 if restore_main:
1518 1518 sys.modules['__main__'] = restore_main
1519 1519 return stats
1520 1520
1521 1521 def magic_runlog(self, parameter_s =''):
1522 1522 """Run files as logs.
1523 1523
1524 1524 Usage:\\
1525 1525 %runlog file1 file2 ...
1526 1526
1527 1527 Run the named files (treating them as log files) in sequence inside
1528 1528 the interpreter, and return to the prompt. This is much slower than
1529 1529 %run because each line is executed in a try/except block, but it
1530 1530 allows running files with syntax errors in them.
1531 1531
1532 1532 Normally IPython will guess when a file is one of its own logfiles, so
1533 1533 you can typically use %run even for logs. This shorthand allows you to
1534 1534 force any file to be treated as a log file."""
1535 1535
1536 1536 for f in parameter_s.split():
1537 1537 self.shell.safe_execfile(f,self.shell.user_ns,
1538 1538 self.shell.user_ns,islog=1)
1539 1539
1540 1540 def magic_time(self,parameter_s = ''):
1541 1541 """Time execution of a Python statement or expression.
1542 1542
1543 1543 The CPU and wall clock times are printed, and the value of the
1544 1544 expression (if any) is returned. Note that under Win32, system time
1545 1545 is always reported as 0, since it can not be measured.
1546 1546
1547 1547 This function provides very basic timing functionality. In Python
1548 1548 2.3, the timeit module offers more control and sophistication, but for
1549 1549 now IPython supports Python 2.2, so we can not rely on timeit being
1550 1550 present.
1551 1551
1552 1552 Some examples:
1553 1553
1554 1554 In [1]: time 2**128
1555 1555 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1556 1556 Wall time: 0.00
1557 1557 Out[1]: 340282366920938463463374607431768211456L
1558 1558
1559 1559 In [2]: n = 1000000
1560 1560
1561 1561 In [3]: time sum(range(n))
1562 1562 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1563 1563 Wall time: 1.37
1564 1564 Out[3]: 499999500000L
1565 1565
1566 1566 In [4]: time print 'hello world'
1567 1567 hello world
1568 1568 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1569 1569 Wall time: 0.00
1570 1570 """
1571 1571
1572 1572 # fail immediately if the given expression can't be compiled
1573 1573 try:
1574 1574 mode = 'eval'
1575 1575 code = compile(parameter_s,'<timed eval>',mode)
1576 1576 except SyntaxError:
1577 1577 mode = 'exec'
1578 1578 code = compile(parameter_s,'<timed exec>',mode)
1579 1579 # skew measurement as little as possible
1580 1580 glob = self.shell.user_ns
1581 1581 clk = clock2
1582 1582 wtime = time.time
1583 1583 # time execution
1584 1584 wall_st = wtime()
1585 1585 if mode=='eval':
1586 1586 st = clk()
1587 1587 out = eval(code,glob)
1588 1588 end = clk()
1589 1589 else:
1590 1590 st = clk()
1591 1591 exec code in glob
1592 1592 end = clk()
1593 1593 out = None
1594 1594 wall_end = wtime()
1595 1595 # Compute actual times and report
1596 1596 wall_time = wall_end-wall_st
1597 1597 cpu_user = end[0]-st[0]
1598 1598 cpu_sys = end[1]-st[1]
1599 1599 cpu_tot = cpu_user+cpu_sys
1600 1600 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1601 1601 (cpu_user,cpu_sys,cpu_tot)
1602 1602 print "Wall time: %.2f" % wall_time
1603 1603 return out
1604 1604
1605 1605 def magic_macro(self,parameter_s = ''):
1606 1606 """Define a set of input lines as a macro for future re-execution.
1607 1607
1608 1608 Usage:\\
1609 1609 %macro name n1-n2 n3-n4 ... n5 .. n6 ...
1610 1610
1611 1611 This will define a global variable called `name` which is a string
1612 1612 made of joining the slices and lines you specify (n1,n2,... numbers
1613 1613 above) from your input history into a single string. This variable
1614 1614 acts like an automatic function which re-executes those lines as if
1615 1615 you had typed them. You just type 'name' at the prompt and the code
1616 1616 executes.
1617 1617
1618 1618 The notation for indicating number ranges is: n1-n2 means 'use line
1619 1619 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1620 1620 using the lines numbered 5,6 and 7.
1621 1621
1622 1622 Note: as a 'hidden' feature, you can also use traditional python slice
1623 1623 notation, where N:M means numbers N through M-1.
1624 1624
1625 1625 For example, if your history contains (%hist prints it):
1626 1626
1627 1627 44: x=1\\
1628 1628 45: y=3\\
1629 1629 46: z=x+y\\
1630 1630 47: print x\\
1631 1631 48: a=5\\
1632 1632 49: print 'x',x,'y',y\\
1633 1633
1634 1634 you can create a macro with lines 44 through 47 (included) and line 49
1635 1635 called my_macro with:
1636 1636
1637 1637 In [51]: %macro my_macro 44-47 49
1638 1638
1639 1639 Now, typing `my_macro` (without quotes) will re-execute all this code
1640 1640 in one pass.
1641 1641
1642 1642 You don't need to give the line-numbers in order, and any given line
1643 1643 number can appear multiple times. You can assemble macros with any
1644 1644 lines from your input history in any order.
1645 1645
1646 1646 The macro is a simple object which holds its value in an attribute,
1647 1647 but IPython's display system checks for macros and executes them as
1648 1648 code instead of printing them when you type their name.
1649 1649
1650 1650 You can view a macro's contents by explicitly printing it with:
1651 1651
1652 1652 'print macro_name'.
1653 1653
1654 1654 For one-off cases which DON'T contain magic function calls in them you
1655 1655 can obtain similar results by explicitly executing slices from your
1656 1656 input history with:
1657 1657
1658 1658 In [60]: exec In[44:48]+In[49]"""
1659 1659
1660 1660 args = parameter_s.split()
1661 1661 name,ranges = args[0], args[1:]
1662 1662 #print 'rng',ranges # dbg
1663 1663 lines = self.extract_input_slices(ranges)
1664 1664 macro = Macro(lines)
1665 1665 self.shell.user_ns.update({name:macro})
1666 1666 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
1667 1667 print 'Macro contents:'
1668 1668 print macro,
1669 1669
1670 1670 def magic_save(self,parameter_s = ''):
1671 1671 """Save a set of lines to a given filename.
1672 1672
1673 1673 Usage:\\
1674 1674 %save filename n1-n2 n3-n4 ... n5 .. n6 ...
1675 1675
1676 1676 This function uses the same syntax as %macro for line extraction, but
1677 1677 instead of creating a macro it saves the resulting string to the
1678 1678 filename you specify.
1679 1679
1680 1680 It adds a '.py' extension to the file if you don't do so yourself, and
1681 1681 it asks for confirmation before overwriting existing files."""
1682 1682
1683 1683 args = parameter_s.split()
1684 1684 fname,ranges = args[0], args[1:]
1685 1685 if not fname.endswith('.py'):
1686 1686 fname += '.py'
1687 1687 if os.path.isfile(fname):
1688 1688 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
1689 1689 if ans.lower() not in ['y','yes']:
1690 1690 print 'Operation cancelled.'
1691 1691 return
1692 1692 cmds = ''.join(self.extract_input_slices(ranges))
1693 1693 f = file(fname,'w')
1694 1694 f.write(cmds)
1695 1695 f.close()
1696 1696 print 'The following commands were written to file `%s`:' % fname
1697 1697 print cmds
1698 1698
1699 1699 def _edit_macro(self,mname,macro):
1700 1700 """open an editor with the macro data in a file"""
1701 1701 filename = self.shell.mktempfile(macro.value)
1702 1702 self.shell.hooks.editor(filename)
1703 1703
1704 1704 # and make a new macro object, to replace the old one
1705 1705 mfile = open(filename)
1706 1706 mvalue = mfile.read()
1707 1707 mfile.close()
1708 1708 self.shell.user_ns[mname] = Macro(mvalue)
1709 1709
1710 1710 def magic_ed(self,parameter_s=''):
1711 1711 """Alias to %edit."""
1712 1712 return self.magic_edit(parameter_s)
1713 1713
1714 1714 def magic_edit(self,parameter_s='',last_call=['','']):
1715 1715 """Bring up an editor and execute the resulting code.
1716 1716
1717 1717 Usage:
1718 1718 %edit [options] [args]
1719 1719
1720 1720 %edit runs IPython's editor hook. The default version of this hook is
1721 1721 set to call the __IPYTHON__.rc.editor command. This is read from your
1722 1722 environment variable $EDITOR. If this isn't found, it will default to
1723 1723 vi under Linux/Unix and to notepad under Windows. See the end of this
1724 1724 docstring for how to change the editor hook.
1725 1725
1726 1726 You can also set the value of this editor via the command line option
1727 1727 '-editor' or in your ipythonrc file. This is useful if you wish to use
1728 1728 specifically for IPython an editor different from your typical default
1729 1729 (and for Windows users who typically don't set environment variables).
1730 1730
1731 1731 This command allows you to conveniently edit multi-line code right in
1732 1732 your IPython session.
1733 1733
1734 1734 If called without arguments, %edit opens up an empty editor with a
1735 1735 temporary file and will execute the contents of this file when you
1736 1736 close it (don't forget to save it!).
1737 1737
1738 1738
1739 1739 Options:
1740 1740
1741 1741 -p: this will call the editor with the same data as the previous time
1742 1742 it was used, regardless of how long ago (in your current session) it
1743 1743 was.
1744 1744
1745 1745 -x: do not execute the edited code immediately upon exit. This is
1746 1746 mainly useful if you are editing programs which need to be called with
1747 1747 command line arguments, which you can then do using %run.
1748 1748
1749 1749
1750 1750 Arguments:
1751 1751
1752 1752 If arguments are given, the following possibilites exist:
1753 1753
1754 1754 - The arguments are numbers or pairs of colon-separated numbers (like
1755 1755 1 4:8 9). These are interpreted as lines of previous input to be
1756 1756 loaded into the editor. The syntax is the same of the %macro command.
1757 1757
1758 1758 - If the argument doesn't start with a number, it is evaluated as a
1759 1759 variable and its contents loaded into the editor. You can thus edit
1760 1760 any string which contains python code (including the result of
1761 1761 previous edits).
1762 1762
1763 1763 - If the argument is the name of an object (other than a string),
1764 1764 IPython will try to locate the file where it was defined and open the
1765 1765 editor at the point where it is defined. You can use `%edit function`
1766 1766 to load an editor exactly at the point where 'function' is defined,
1767 1767 edit it and have the file be executed automatically.
1768 1768
1769 1769 If the object is a macro (see %macro for details), this opens up your
1770 1770 specified editor with a temporary file containing the macro's data.
1771 1771 Upon exit, the macro is reloaded with the contents of the file.
1772 1772
1773 1773 Note: opening at an exact line is only supported under Unix, and some
1774 1774 editors (like kedit and gedit up to Gnome 2.8) do not understand the
1775 1775 '+NUMBER' parameter necessary for this feature. Good editors like
1776 1776 (X)Emacs, vi, jed, pico and joe all do.
1777 1777
1778 1778 - If the argument is not found as a variable, IPython will look for a
1779 1779 file with that name (adding .py if necessary) and load it into the
1780 1780 editor. It will execute its contents with execfile() when you exit,
1781 1781 loading any code in the file into your interactive namespace.
1782 1782
1783 1783 After executing your code, %edit will return as output the code you
1784 1784 typed in the editor (except when it was an existing file). This way
1785 1785 you can reload the code in further invocations of %edit as a variable,
1786 1786 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
1787 1787 the output.
1788 1788
1789 1789 Note that %edit is also available through the alias %ed.
1790 1790
1791 1791 This is an example of creating a simple function inside the editor and
1792 1792 then modifying it. First, start up the editor:
1793 1793
1794 1794 In [1]: ed\\
1795 1795 Editing... done. Executing edited code...\\
1796 1796 Out[1]: 'def foo():\\n print "foo() was defined in an editing session"\\n'
1797 1797
1798 1798 We can then call the function foo():
1799 1799
1800 1800 In [2]: foo()\\
1801 1801 foo() was defined in an editing session
1802 1802
1803 1803 Now we edit foo. IPython automatically loads the editor with the
1804 1804 (temporary) file where foo() was previously defined:
1805 1805
1806 1806 In [3]: ed foo\\
1807 1807 Editing... done. Executing edited code...
1808 1808
1809 1809 And if we call foo() again we get the modified version:
1810 1810
1811 1811 In [4]: foo()\\
1812 1812 foo() has now been changed!
1813 1813
1814 1814 Here is an example of how to edit a code snippet successive
1815 1815 times. First we call the editor:
1816 1816
1817 1817 In [8]: ed\\
1818 1818 Editing... done. Executing edited code...\\
1819 1819 hello\\
1820 1820 Out[8]: "print 'hello'\\n"
1821 1821
1822 1822 Now we call it again with the previous output (stored in _):
1823 1823
1824 1824 In [9]: ed _\\
1825 1825 Editing... done. Executing edited code...\\
1826 1826 hello world\\
1827 1827 Out[9]: "print 'hello world'\\n"
1828 1828
1829 1829 Now we call it with the output #8 (stored in _8, also as Out[8]):
1830 1830
1831 1831 In [10]: ed _8\\
1832 1832 Editing... done. Executing edited code...\\
1833 1833 hello again\\
1834 1834 Out[10]: "print 'hello again'\\n"
1835 1835
1836 1836
1837 1837 Changing the default editor hook:
1838 1838
1839 1839 If you wish to write your own editor hook, you can put it in a
1840 1840 configuration file which you load at startup time. The default hook
1841 1841 is defined in the IPython.hooks module, and you can use that as a
1842 1842 starting example for further modifications. That file also has
1843 1843 general instructions on how to set a new hook for use once you've
1844 1844 defined it."""
1845 1845
1846 1846 # FIXME: This function has become a convoluted mess. It needs a
1847 1847 # ground-up rewrite with clean, simple logic.
1848 1848
1849 1849 def make_filename(arg):
1850 1850 "Make a filename from the given args"
1851 1851 try:
1852 1852 filename = get_py_filename(arg)
1853 1853 except IOError:
1854 1854 if args.endswith('.py'):
1855 1855 filename = arg
1856 1856 else:
1857 1857 filename = None
1858 1858 return filename
1859 1859
1860 1860 # custom exceptions
1861 1861 class DataIsObject(Exception): pass
1862 1862
1863 1863 opts,args = self.parse_options(parameter_s,'px')
1864 1864
1865 1865 # Default line number value
1866 1866 lineno = None
1867 1867 if opts.has_key('p'):
1868 1868 args = '_%s' % last_call[0]
1869 1869 if not self.shell.user_ns.has_key(args):
1870 1870 args = last_call[1]
1871 1871
1872 1872 # use last_call to remember the state of the previous call, but don't
1873 1873 # let it be clobbered by successive '-p' calls.
1874 1874 try:
1875 1875 last_call[0] = self.shell.outputcache.prompt_count
1876 1876 if not opts.has_key('p'):
1877 1877 last_call[1] = parameter_s
1878 1878 except:
1879 1879 pass
1880 1880
1881 1881 # by default this is done with temp files, except when the given
1882 1882 # arg is a filename
1883 1883 use_temp = 1
1884 1884
1885 1885 if re.match(r'\d',args):
1886 1886 # Mode where user specifies ranges of lines, like in %macro.
1887 1887 # This means that you can't edit files whose names begin with
1888 1888 # numbers this way. Tough.
1889 1889 ranges = args.split()
1890 1890 data = ''.join(self.extract_input_slices(ranges))
1891 1891 elif args.endswith('.py'):
1892 1892 filename = make_filename(args)
1893 1893 data = ''
1894 1894 use_temp = 0
1895 1895 elif args:
1896 1896 try:
1897 1897 # Load the parameter given as a variable. If not a string,
1898 1898 # process it as an object instead (below)
1899 1899
1900 1900 #print '*** args',args,'type',type(args) # dbg
1901 1901 data = eval(args,self.shell.user_ns)
1902 1902 if not type(data) in StringTypes:
1903 1903 raise DataIsObject
1904 1904
1905 1905 except (NameError,SyntaxError):
1906 1906 # given argument is not a variable, try as a filename
1907 1907 filename = make_filename(args)
1908 1908 if filename is None:
1909 1909 warn("Argument given (%s) can't be found as a variable "
1910 1910 "or as a filename." % args)
1911 1911 return
1912 1912
1913 1913 data = ''
1914 1914 use_temp = 0
1915 1915 except DataIsObject:
1916 1916
1917 1917 # macros have a special edit function
1918 1918 if isinstance(data,Macro):
1919 1919 self._edit_macro(args,data)
1920 1920 return
1921 1921
1922 1922 # For objects, try to edit the file where they are defined
1923 1923 try:
1924 1924 filename = inspect.getabsfile(data)
1925 1925 datafile = 1
1926 1926 except TypeError:
1927 1927 filename = make_filename(args)
1928 1928 datafile = 1
1929 1929 warn('Could not find file where `%s` is defined.\n'
1930 1930 'Opening a file named `%s`' % (args,filename))
1931 1931 # Now, make sure we can actually read the source (if it was in
1932 1932 # a temp file it's gone by now).
1933 1933 if datafile:
1934 1934 try:
1935 1935 lineno = inspect.getsourcelines(data)[1]
1936 1936 except IOError:
1937 1937 filename = make_filename(args)
1938 1938 if filename is None:
1939 1939 warn('The file `%s` where `%s` was defined cannot '
1940 1940 'be read.' % (filename,data))
1941 1941 return
1942 1942 use_temp = 0
1943 1943 else:
1944 1944 data = ''
1945 1945
1946 1946 if use_temp:
1947 1947 filename = self.shell.mktempfile(data)
1948 1948 print 'IPython will make a temporary file named:',filename
1949 1949
1950 1950 # do actual editing here
1951 1951 print 'Editing...',
1952 1952 sys.stdout.flush()
1953 1953 self.shell.hooks.editor(filename,lineno)
1954 1954 if opts.has_key('x'): # -x prevents actual execution
1955 1955 print
1956 1956 else:
1957 1957 print 'done. Executing edited code...'
1958 1958 self.shell.safe_execfile(filename,self.shell.user_ns)
1959 1959 if use_temp:
1960 1960 try:
1961 1961 return open(filename).read()
1962 1962 except IOError,msg:
1963 1963 if msg.filename == filename:
1964 1964 warn('File not found. Did you forget to save?')
1965 1965 return
1966 1966 else:
1967 1967 self.shell.showtraceback()
1968 1968
1969 1969 def magic_xmode(self,parameter_s = ''):
1970 1970 """Switch modes for the exception handlers.
1971 1971
1972 1972 Valid modes: Plain, Context and Verbose.
1973 1973
1974 1974 If called without arguments, acts as a toggle."""
1975 1975
1976 1976 def xmode_switch_err(name):
1977 1977 warn('Error changing %s exception modes.\n%s' %
1978 1978 (name,sys.exc_info()[1]))
1979 1979
1980 1980 shell = self.shell
1981 1981 new_mode = parameter_s.strip().capitalize()
1982 1982 try:
1983 1983 shell.InteractiveTB.set_mode(mode=new_mode)
1984 1984 print 'Exception reporting mode:',shell.InteractiveTB.mode
1985 1985 except:
1986 1986 xmode_switch_err('user')
1987 1987
1988 1988 # threaded shells use a special handler in sys.excepthook
1989 1989 if shell.isthreaded:
1990 1990 try:
1991 1991 shell.sys_excepthook.set_mode(mode=new_mode)
1992 1992 except:
1993 1993 xmode_switch_err('threaded')
1994 1994
1995 1995 def magic_colors(self,parameter_s = ''):
1996 1996 """Switch color scheme for prompts, info system and exception handlers.
1997 1997
1998 1998 Currently implemented schemes: NoColor, Linux, LightBG.
1999 1999
2000 2000 Color scheme names are not case-sensitive."""
2001 2001
2002 2002 def color_switch_err(name):
2003 2003 warn('Error changing %s color schemes.\n%s' %
2004 2004 (name,sys.exc_info()[1]))
2005 2005
2006 2006
2007 2007 new_scheme = parameter_s.strip()
2008 2008 if not new_scheme:
2009 2009 print 'You must specify a color scheme.'
2010 2010 return
2011 2011 import IPython.rlineimpl as readline
2012 2012 if not readline.have_readline:
2013 2013 msg = """\
2014 2014 Proper color support under MS Windows requires Gary Bishop's readline library.
2015 2015 You can find it at:
2016 2016 http://sourceforge.net/projects/uncpythontools
2017 2017 Gary's readline needs the ctypes module, from:
2018 2018 http://starship.python.net/crew/theller/ctypes
2019 2019
2020 2020 Defaulting color scheme to 'NoColor'"""
2021 2021 new_scheme = 'NoColor'
2022 2022 warn(msg)
2023 2023 # local shortcut
2024 2024 shell = self.shell
2025 2025
2026 2026 # Set prompt colors
2027 2027 try:
2028 2028 shell.outputcache.set_colors(new_scheme)
2029 2029 except:
2030 2030 color_switch_err('prompt')
2031 2031 else:
2032 2032 shell.rc.colors = \
2033 2033 shell.outputcache.color_table.active_scheme_name
2034 2034 # Set exception colors
2035 2035 try:
2036 2036 shell.InteractiveTB.set_colors(scheme = new_scheme)
2037 2037 shell.SyntaxTB.set_colors(scheme = new_scheme)
2038 2038 except:
2039 2039 color_switch_err('exception')
2040 2040
2041 2041 # threaded shells use a verbose traceback in sys.excepthook
2042 2042 if shell.isthreaded:
2043 2043 try:
2044 2044 shell.sys_excepthook.set_colors(scheme=new_scheme)
2045 2045 except:
2046 2046 color_switch_err('system exception handler')
2047 2047
2048 2048 # Set info (for 'object?') colors
2049 2049 if shell.rc.color_info:
2050 2050 try:
2051 2051 shell.inspector.set_active_scheme(new_scheme)
2052 2052 except:
2053 2053 color_switch_err('object inspector')
2054 2054 else:
2055 2055 shell.inspector.set_active_scheme('NoColor')
2056 2056
2057 2057 def magic_color_info(self,parameter_s = ''):
2058 2058 """Toggle color_info.
2059 2059
2060 2060 The color_info configuration parameter controls whether colors are
2061 2061 used for displaying object details (by things like %psource, %pfile or
2062 2062 the '?' system). This function toggles this value with each call.
2063 2063
2064 2064 Note that unless you have a fairly recent pager (less works better
2065 2065 than more) in your system, using colored object information displays
2066 2066 will not work properly. Test it and see."""
2067 2067
2068 2068 self.shell.rc.color_info = 1 - self.shell.rc.color_info
2069 2069 self.magic_colors(self.shell.rc.colors)
2070 2070 print 'Object introspection functions have now coloring:',
2071 2071 print ['OFF','ON'][self.shell.rc.color_info]
2072 2072
2073 2073 def magic_Pprint(self, parameter_s=''):
2074 2074 """Toggle pretty printing on/off."""
2075 2075
2076 2076 self.shell.outputcache.Pprint = 1 - self.shell.outputcache.Pprint
2077 2077 print 'Pretty printing has been turned', \
2078 2078 ['OFF','ON'][self.shell.outputcache.Pprint]
2079 2079
2080 2080 def magic_exit(self, parameter_s=''):
2081 2081 """Exit IPython, confirming if configured to do so.
2082 2082
2083 2083 You can configure whether IPython asks for confirmation upon exit by
2084 2084 setting the confirm_exit flag in the ipythonrc file."""
2085 2085
2086 2086 self.shell.exit()
2087 2087
2088 2088 def magic_quit(self, parameter_s=''):
2089 2089 """Exit IPython, confirming if configured to do so (like %exit)"""
2090 2090
2091 2091 self.shell.exit()
2092 2092
2093 2093 def magic_Exit(self, parameter_s=''):
2094 2094 """Exit IPython without confirmation."""
2095 2095
2096 2096 self.shell.exit_now = True
2097 2097
2098 2098 def magic_Quit(self, parameter_s=''):
2099 2099 """Exit IPython without confirmation (like %Exit)."""
2100 2100
2101 2101 self.shell.exit_now = True
2102 2102
2103 2103 #......................................................................
2104 2104 # Functions to implement unix shell-type things
2105 2105
2106 2106 def magic_alias(self, parameter_s = ''):
2107 2107 """Define an alias for a system command.
2108 2108
2109 2109 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2110 2110
2111 2111 Then, typing 'alias_name params' will execute the system command 'cmd
2112 2112 params' (from your underlying operating system).
2113 2113
2114 2114 Aliases have lower precedence than magic functions and Python normal
2115 2115 variables, so if 'foo' is both a Python variable and an alias, the
2116 2116 alias can not be executed until 'del foo' removes the Python variable.
2117 2117
2118 2118 You can use the %l specifier in an alias definition to represent the
2119 2119 whole line when the alias is called. For example:
2120 2120
2121 2121 In [2]: alias all echo "Input in brackets: <%l>"\\
2122 2122 In [3]: all hello world\\
2123 2123 Input in brackets: <hello world>
2124 2124
2125 2125 You can also define aliases with parameters using %s specifiers (one
2126 2126 per parameter):
2127 2127
2128 2128 In [1]: alias parts echo first %s second %s\\
2129 2129 In [2]: %parts A B\\
2130 2130 first A second B\\
2131 2131 In [3]: %parts A\\
2132 2132 Incorrect number of arguments: 2 expected.\\
2133 2133 parts is an alias to: 'echo first %s second %s'
2134 2134
2135 2135 Note that %l and %s are mutually exclusive. You can only use one or
2136 2136 the other in your aliases.
2137 2137
2138 2138 Aliases expand Python variables just like system calls using ! or !!
2139 2139 do: all expressions prefixed with '$' get expanded. For details of
2140 2140 the semantic rules, see PEP-215:
2141 2141 http://www.python.org/peps/pep-0215.html. This is the library used by
2142 2142 IPython for variable expansion. If you want to access a true shell
2143 2143 variable, an extra $ is necessary to prevent its expansion by IPython:
2144 2144
2145 2145 In [6]: alias show echo\\
2146 2146 In [7]: PATH='A Python string'\\
2147 2147 In [8]: show $PATH\\
2148 2148 A Python string\\
2149 2149 In [9]: show $$PATH\\
2150 2150 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2151 2151
2152 2152 You can use the alias facility to acess all of $PATH. See the %rehash
2153 2153 and %rehashx functions, which automatically create aliases for the
2154 2154 contents of your $PATH.
2155 2155
2156 2156 If called with no parameters, %alias prints the current alias table."""
2157 2157
2158 2158 par = parameter_s.strip()
2159 2159 if not par:
2160 2160 if self.shell.rc.automagic:
2161 2161 prechar = ''
2162 2162 else:
2163 2163 prechar = self.shell.ESC_MAGIC
2164 2164 #print 'Alias\t\tSystem Command\n'+'-'*30
2165 2165 atab = self.shell.alias_table
2166 2166 aliases = atab.keys()
2167 2167 aliases.sort()
2168 2168 res = []
2169 2169 for alias in aliases:
2170 2170 res.append((alias, atab[alias][1]))
2171 2171 print "Total number of aliases:",len(aliases)
2172 2172 return res
2173 2173 try:
2174 2174 alias,cmd = par.split(None,1)
2175 2175 except:
2176 2176 print OInspect.getdoc(self.magic_alias)
2177 2177 else:
2178 2178 nargs = cmd.count('%s')
2179 2179 if nargs>0 and cmd.find('%l')>=0:
2180 2180 error('The %s and %l specifiers are mutually exclusive '
2181 2181 'in alias definitions.')
2182 2182 else: # all looks OK
2183 2183 self.shell.alias_table[alias] = (nargs,cmd)
2184 2184 self.shell.alias_table_validate(verbose=1)
2185 2185 # end magic_alias
2186 2186
2187 2187 def magic_unalias(self, parameter_s = ''):
2188 2188 """Remove an alias"""
2189 2189
2190 2190 aname = parameter_s.strip()
2191 2191 if aname in self.shell.alias_table:
2192 2192 del self.shell.alias_table[aname]
2193 2193
2194 2194 def magic_rehash(self, parameter_s = ''):
2195 2195 """Update the alias table with all entries in $PATH.
2196 2196
2197 2197 This version does no checks on execute permissions or whether the
2198 2198 contents of $PATH are truly files (instead of directories or something
2199 2199 else). For such a safer (but slower) version, use %rehashx."""
2200 2200
2201 2201 # This function (and rehashx) manipulate the alias_table directly
2202 2202 # rather than calling magic_alias, for speed reasons. A rehash on a
2203 2203 # typical Linux box involves several thousand entries, so efficiency
2204 2204 # here is a top concern.
2205 2205
2206 2206 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2207 2207 alias_table = self.shell.alias_table
2208 2208 for pdir in path:
2209 2209 for ff in os.listdir(pdir):
2210 2210 # each entry in the alias table must be (N,name), where
2211 2211 # N is the number of positional arguments of the alias.
2212 2212 alias_table[ff] = (0,ff)
2213 2213 # Make sure the alias table doesn't contain keywords or builtins
2214 2214 self.shell.alias_table_validate()
2215 2215 # Call again init_auto_alias() so we get 'rm -i' and other modified
2216 2216 # aliases since %rehash will probably clobber them
2217 2217 self.shell.init_auto_alias()
2218 2218
2219 2219 def magic_rehashx(self, parameter_s = ''):
2220 2220 """Update the alias table with all executable files in $PATH.
2221 2221
2222 2222 This version explicitly checks that every entry in $PATH is a file
2223 2223 with execute access (os.X_OK), so it is much slower than %rehash.
2224 2224
2225 2225 Under Windows, it checks executability as a match agains a
2226 2226 '|'-separated string of extensions, stored in the IPython config
2227 2227 variable win_exec_ext. This defaults to 'exe|com|bat'. """
2228 2228
2229 2229 path = filter(os.path.isdir,os.environ['PATH'].split(os.pathsep))
2230 2230 alias_table = self.shell.alias_table
2231 2231
2232 2232 if os.name == 'posix':
2233 2233 isexec = lambda fname:os.path.isfile(fname) and \
2234 2234 os.access(fname,os.X_OK)
2235 2235 else:
2236 2236
2237 2237 try:
2238 2238 winext = os.environ['pathext'].replace(';','|').replace('.','')
2239 2239 except KeyError:
2240 2240 winext = 'exe|com|bat'
2241 2241
2242 2242 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2243 2243 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2244 2244 savedir = os.getcwd()
2245 2245 try:
2246 2246 # write the whole loop for posix/Windows so we don't have an if in
2247 2247 # the innermost part
2248 2248 if os.name == 'posix':
2249 2249 for pdir in path:
2250 2250 os.chdir(pdir)
2251 2251 for ff in os.listdir(pdir):
2252 2252 if isexec(ff):
2253 2253 # each entry in the alias table must be (N,name),
2254 2254 # where N is the number of positional arguments of the
2255 2255 # alias.
2256 2256 alias_table[ff] = (0,ff)
2257 2257 else:
2258 2258 for pdir in path:
2259 2259 os.chdir(pdir)
2260 2260 for ff in os.listdir(pdir):
2261 2261 if isexec(ff):
2262 2262 alias_table[execre.sub(r'\1',ff)] = (0,ff)
2263 2263 # Make sure the alias table doesn't contain keywords or builtins
2264 2264 self.shell.alias_table_validate()
2265 2265 # Call again init_auto_alias() so we get 'rm -i' and other
2266 2266 # modified aliases since %rehashx will probably clobber them
2267 2267 self.shell.init_auto_alias()
2268 2268 finally:
2269 2269 os.chdir(savedir)
2270 2270
2271 2271 def magic_pwd(self, parameter_s = ''):
2272 2272 """Return the current working directory path."""
2273 2273 return os.getcwd()
2274 2274
2275 2275 def magic_cd(self, parameter_s=''):
2276 2276 """Change the current working directory.
2277 2277
2278 2278 This command automatically maintains an internal list of directories
2279 2279 you visit during your IPython session, in the variable _dh. The
2280 2280 command %dhist shows this history nicely formatted.
2281 2281
2282 2282 Usage:
2283 2283
2284 2284 cd 'dir': changes to directory 'dir'.
2285 2285
2286 2286 cd -: changes to the last visited directory.
2287 2287
2288 2288 cd -<n>: changes to the n-th directory in the directory history.
2289 2289
2290 2290 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2291 2291 (note: cd <bookmark_name> is enough if there is no
2292 2292 directory <bookmark_name>, but a bookmark with the name exists.)
2293 2293
2294 2294 Options:
2295 2295
2296 2296 -q: quiet. Do not print the working directory after the cd command is
2297 2297 executed. By default IPython's cd command does print this directory,
2298 2298 since the default prompts do not display path information.
2299 2299
2300 2300 Note that !cd doesn't work for this purpose because the shell where
2301 2301 !command runs is immediately discarded after executing 'command'."""
2302 2302
2303 2303 parameter_s = parameter_s.strip()
2304 bkms = self.shell.persist.get("bookmarks",{})
2304 #bkms = self.shell.persist.get("bookmarks",{})
2305 2305
2306 2306 numcd = re.match(r'(-)(\d+)$',parameter_s)
2307 2307 # jump in directory history by number
2308 2308 if numcd:
2309 2309 nn = int(numcd.group(2))
2310 2310 try:
2311 2311 ps = self.shell.user_ns['_dh'][nn]
2312 2312 except IndexError:
2313 2313 print 'The requested directory does not exist in history.'
2314 2314 return
2315 2315 else:
2316 2316 opts = {}
2317 2317 else:
2318 2318 #turn all non-space-escaping backslashes to slashes,
2319 2319 # for c:\windows\directory\names\
2320 2320 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2321 2321 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2322 2322 # jump to previous
2323 2323 if ps == '-':
2324 2324 try:
2325 2325 ps = self.shell.user_ns['_dh'][-2]
2326 2326 except IndexError:
2327 2327 print 'No previous directory to change to.'
2328 2328 return
2329 # jump to bookmark
2330 elif opts.has_key('b') or (bkms.has_key(ps) and not os.path.isdir(ps)):
2331 if bkms.has_key(ps):
2332 target = bkms[ps]
2333 print '(bookmark:%s) -> %s' % (ps,target)
2334 ps = target
2335 else:
2336 if bkms:
2337 error("Bookmark '%s' not found. "
2338 "Use '%%bookmark -l' to see your bookmarks." % ps)
2329 # jump to bookmark if needed
2330 else:
2331 if not os.path.isdir(ps) or opts.has_key('b'):
2332 bkms = self.db.get('bookmarks', {})
2333
2334 if bkms.has_key(ps):
2335 target = bkms[ps]
2336 print '(bookmark:%s) -> %s' % (ps,target)
2337 ps = target
2339 2338 else:
2340 print "Bookmarks not set - use %bookmark <bookmarkname>"
2341 return
2339 if opts.has_key('b'):
2340 error("Bookmark '%s' not found. "
2341 "Use '%%bookmark -l' to see your bookmarks." % ps)
2342 return
2342 2343
2343 2344 # at this point ps should point to the target dir
2344 2345 if ps:
2345 2346 try:
2346 2347 os.chdir(os.path.expanduser(ps))
2347 2348 ttitle = ("IPy:" + (
2348 2349 os.getcwd() == '/' and '/' or os.path.basename(os.getcwd())))
2349 2350 platutils.set_term_title(ttitle)
2350 2351 except OSError:
2351 2352 print sys.exc_info()[1]
2352 2353 else:
2353 2354 self.shell.user_ns['_dh'].append(os.getcwd())
2354 2355 else:
2355 2356 os.chdir(self.shell.home_dir)
2356 2357 platutils.set_term_title("IPy:~")
2357 2358 self.shell.user_ns['_dh'].append(os.getcwd())
2358 2359 if not 'q' in opts:
2359 2360 print self.shell.user_ns['_dh'][-1]
2360 2361
2361 2362 def magic_dhist(self, parameter_s=''):
2362 2363 """Print your history of visited directories.
2363 2364
2364 2365 %dhist -> print full history\\
2365 2366 %dhist n -> print last n entries only\\
2366 2367 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2367 2368
2368 2369 This history is automatically maintained by the %cd command, and
2369 2370 always available as the global list variable _dh. You can use %cd -<n>
2370 2371 to go to directory number <n>."""
2371 2372
2372 2373 dh = self.shell.user_ns['_dh']
2373 2374 if parameter_s:
2374 2375 try:
2375 2376 args = map(int,parameter_s.split())
2376 2377 except:
2377 2378 self.arg_err(Magic.magic_dhist)
2378 2379 return
2379 2380 if len(args) == 1:
2380 2381 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2381 2382 elif len(args) == 2:
2382 2383 ini,fin = args
2383 2384 else:
2384 2385 self.arg_err(Magic.magic_dhist)
2385 2386 return
2386 2387 else:
2387 2388 ini,fin = 0,len(dh)
2388 2389 nlprint(dh,
2389 2390 header = 'Directory history (kept in _dh)',
2390 2391 start=ini,stop=fin)
2391 2392
2392 2393 def magic_env(self, parameter_s=''):
2393 2394 """List environment variables."""
2394 2395
2395 2396 return os.environ.data
2396 2397
2397 2398 def magic_pushd(self, parameter_s=''):
2398 2399 """Place the current dir on stack and change directory.
2399 2400
2400 2401 Usage:\\
2401 2402 %pushd ['dirname']
2402 2403
2403 2404 %pushd with no arguments does a %pushd to your home directory.
2404 2405 """
2405 2406 if parameter_s == '': parameter_s = '~'
2406 2407 dir_s = self.shell.dir_stack
2407 2408 if len(dir_s)>0 and os.path.expanduser(parameter_s) != \
2408 2409 os.path.expanduser(self.shell.dir_stack[0]):
2409 2410 try:
2410 2411 self.magic_cd(parameter_s)
2411 2412 dir_s.insert(0,os.getcwd().replace(self.home_dir,'~'))
2412 2413 self.magic_dirs()
2413 2414 except:
2414 2415 print 'Invalid directory'
2415 2416 else:
2416 2417 print 'You are already there!'
2417 2418
2418 2419 def magic_popd(self, parameter_s=''):
2419 2420 """Change to directory popped off the top of the stack.
2420 2421 """
2421 2422 if len (self.shell.dir_stack) > 1:
2422 2423 self.shell.dir_stack.pop(0)
2423 2424 self.magic_cd(self.shell.dir_stack[0])
2424 2425 print self.shell.dir_stack[0]
2425 2426 else:
2426 2427 print "You can't remove the starting directory from the stack:",\
2427 2428 self.shell.dir_stack
2428 2429
2429 2430 def magic_dirs(self, parameter_s=''):
2430 2431 """Return the current directory stack."""
2431 2432
2432 2433 return self.shell.dir_stack[:]
2433 2434
2434 2435 def magic_sc(self, parameter_s=''):
2435 2436 """Shell capture - execute a shell command and capture its output.
2436 2437
2437 2438 DEPRECATED. Suboptimal, retained for backwards compatibility.
2438 2439
2439 2440 You should use the form 'var = !command' instead. Example:
2440 2441
2441 2442 "%sc -l myfiles = ls ~" should now be written as
2442 2443
2443 2444 "myfiles = !ls ~"
2444 2445
2445 2446 myfiles.s, myfiles.l and myfiles.n still apply as documented
2446 2447 below.
2447 2448
2448 2449 --
2449 2450 %sc [options] varname=command
2450 2451
2451 2452 IPython will run the given command using commands.getoutput(), and
2452 2453 will then update the user's interactive namespace with a variable
2453 2454 called varname, containing the value of the call. Your command can
2454 2455 contain shell wildcards, pipes, etc.
2455 2456
2456 2457 The '=' sign in the syntax is mandatory, and the variable name you
2457 2458 supply must follow Python's standard conventions for valid names.
2458 2459
2459 2460 (A special format without variable name exists for internal use)
2460 2461
2461 2462 Options:
2462 2463
2463 2464 -l: list output. Split the output on newlines into a list before
2464 2465 assigning it to the given variable. By default the output is stored
2465 2466 as a single string.
2466 2467
2467 2468 -v: verbose. Print the contents of the variable.
2468 2469
2469 2470 In most cases you should not need to split as a list, because the
2470 2471 returned value is a special type of string which can automatically
2471 2472 provide its contents either as a list (split on newlines) or as a
2472 2473 space-separated string. These are convenient, respectively, either
2473 2474 for sequential processing or to be passed to a shell command.
2474 2475
2475 2476 For example:
2476 2477
2477 2478 # Capture into variable a
2478 2479 In [9]: sc a=ls *py
2479 2480
2480 2481 # a is a string with embedded newlines
2481 2482 In [10]: a
2482 2483 Out[10]: 'setup.py\nwin32_manual_post_install.py'
2483 2484
2484 2485 # which can be seen as a list:
2485 2486 In [11]: a.l
2486 2487 Out[11]: ['setup.py', 'win32_manual_post_install.py']
2487 2488
2488 2489 # or as a whitespace-separated string:
2489 2490 In [12]: a.s
2490 2491 Out[12]: 'setup.py win32_manual_post_install.py'
2491 2492
2492 2493 # a.s is useful to pass as a single command line:
2493 2494 In [13]: !wc -l $a.s
2494 2495 146 setup.py
2495 2496 130 win32_manual_post_install.py
2496 2497 276 total
2497 2498
2498 2499 # while the list form is useful to loop over:
2499 2500 In [14]: for f in a.l:
2500 2501 ....: !wc -l $f
2501 2502 ....:
2502 2503 146 setup.py
2503 2504 130 win32_manual_post_install.py
2504 2505
2505 2506 Similiarly, the lists returned by the -l option are also special, in
2506 2507 the sense that you can equally invoke the .s attribute on them to
2507 2508 automatically get a whitespace-separated string from their contents:
2508 2509
2509 2510 In [1]: sc -l b=ls *py
2510 2511
2511 2512 In [2]: b
2512 2513 Out[2]: ['setup.py', 'win32_manual_post_install.py']
2513 2514
2514 2515 In [3]: b.s
2515 2516 Out[3]: 'setup.py win32_manual_post_install.py'
2516 2517
2517 2518 In summary, both the lists and strings used for ouptut capture have
2518 2519 the following special attributes:
2519 2520
2520 2521 .l (or .list) : value as list.
2521 2522 .n (or .nlstr): value as newline-separated string.
2522 2523 .s (or .spstr): value as space-separated string.
2523 2524 """
2524 2525
2525 2526 opts,args = self.parse_options(parameter_s,'lv')
2526 2527 # Try to get a variable name and command to run
2527 2528 try:
2528 2529 # the variable name must be obtained from the parse_options
2529 2530 # output, which uses shlex.split to strip options out.
2530 2531 var,_ = args.split('=',1)
2531 2532 var = var.strip()
2532 2533 # But the the command has to be extracted from the original input
2533 2534 # parameter_s, not on what parse_options returns, to avoid the
2534 2535 # quote stripping which shlex.split performs on it.
2535 2536 _,cmd = parameter_s.split('=',1)
2536 2537 except ValueError:
2537 2538 var,cmd = '',''
2538 2539 # If all looks ok, proceed
2539 2540 out,err = self.shell.getoutputerror(cmd)
2540 2541 if err:
2541 2542 print >> Term.cerr,err
2542 2543 if opts.has_key('l'):
2543 2544 out = SList(out.split('\n'))
2544 2545 else:
2545 2546 out = LSString(out)
2546 2547 if opts.has_key('v'):
2547 2548 print '%s ==\n%s' % (var,pformat(out))
2548 2549 if var:
2549 2550 self.shell.user_ns.update({var:out})
2550 2551 else:
2551 2552 return out
2552 2553
2553 2554 def magic_sx(self, parameter_s=''):
2554 2555 """Shell execute - run a shell command and capture its output.
2555 2556
2556 2557 %sx command
2557 2558
2558 2559 IPython will run the given command using commands.getoutput(), and
2559 2560 return the result formatted as a list (split on '\\n'). Since the
2560 2561 output is _returned_, it will be stored in ipython's regular output
2561 2562 cache Out[N] and in the '_N' automatic variables.
2562 2563
2563 2564 Notes:
2564 2565
2565 2566 1) If an input line begins with '!!', then %sx is automatically
2566 2567 invoked. That is, while:
2567 2568 !ls
2568 2569 causes ipython to simply issue system('ls'), typing
2569 2570 !!ls
2570 2571 is a shorthand equivalent to:
2571 2572 %sx ls
2572 2573
2573 2574 2) %sx differs from %sc in that %sx automatically splits into a list,
2574 2575 like '%sc -l'. The reason for this is to make it as easy as possible
2575 2576 to process line-oriented shell output via further python commands.
2576 2577 %sc is meant to provide much finer control, but requires more
2577 2578 typing.
2578 2579
2579 2580 3) Just like %sc -l, this is a list with special attributes:
2580 2581
2581 2582 .l (or .list) : value as list.
2582 2583 .n (or .nlstr): value as newline-separated string.
2583 2584 .s (or .spstr): value as whitespace-separated string.
2584 2585
2585 2586 This is very useful when trying to use such lists as arguments to
2586 2587 system commands."""
2587 2588
2588 2589 if parameter_s:
2589 2590 out,err = self.shell.getoutputerror(parameter_s)
2590 2591 if err:
2591 2592 print >> Term.cerr,err
2592 2593 return SList(out.split('\n'))
2593 2594
2594 2595 def magic_bg(self, parameter_s=''):
2595 2596 """Run a job in the background, in a separate thread.
2596 2597
2597 2598 For example,
2598 2599
2599 2600 %bg myfunc(x,y,z=1)
2600 2601
2601 2602 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
2602 2603 execution starts, a message will be printed indicating the job
2603 2604 number. If your job number is 5, you can use
2604 2605
2605 2606 myvar = jobs.result(5) or myvar = jobs[5].result
2606 2607
2607 2608 to assign this result to variable 'myvar'.
2608 2609
2609 2610 IPython has a job manager, accessible via the 'jobs' object. You can
2610 2611 type jobs? to get more information about it, and use jobs.<TAB> to see
2611 2612 its attributes. All attributes not starting with an underscore are
2612 2613 meant for public use.
2613 2614
2614 2615 In particular, look at the jobs.new() method, which is used to create
2615 2616 new jobs. This magic %bg function is just a convenience wrapper
2616 2617 around jobs.new(), for expression-based jobs. If you want to create a
2617 2618 new job with an explicit function object and arguments, you must call
2618 2619 jobs.new() directly.
2619 2620
2620 2621 The jobs.new docstring also describes in detail several important
2621 2622 caveats associated with a thread-based model for background job
2622 2623 execution. Type jobs.new? for details.
2623 2624
2624 2625 You can check the status of all jobs with jobs.status().
2625 2626
2626 2627 The jobs variable is set by IPython into the Python builtin namespace.
2627 2628 If you ever declare a variable named 'jobs', you will shadow this
2628 2629 name. You can either delete your global jobs variable to regain
2629 2630 access to the job manager, or make a new name and assign it manually
2630 2631 to the manager (stored in IPython's namespace). For example, to
2631 2632 assign the job manager to the Jobs name, use:
2632 2633
2633 2634 Jobs = __builtins__.jobs"""
2634 2635
2635 2636 self.shell.jobs.new(parameter_s,self.shell.user_ns)
2636 2637
2637 def magic_store(self, parameter_s=''):
2638 """Lightweight persistence for python variables.
2639
2640 Example:
2641
2642 ville@badger[~]|1> A = ['hello',10,'world']\\
2643 ville@badger[~]|2> %store A\\
2644 ville@badger[~]|3> Exit
2645
2646 (IPython session is closed and started again...)
2647
2648 ville@badger:~$ ipython -p pysh\\
2649 ville@badger[~]|1> print A
2650
2651 ['hello', 10, 'world']
2652
2653 Usage:
2654
2655 %store - Show list of all variables and their current values\\
2656 %store <var> - Store the *current* value of the variable to disk\\
2657 %store -d <var> - Remove the variable and its value from storage\\
2658 %store -r - Remove all variables from storage\\
2659 %store foo >a.txt - Store value of foo to new file a.txt\\
2660 %store foo >>a.txt - Append value of foo to file a.txt\\
2661
2662 It should be noted that if you change the value of a variable, you
2663 need to %store it again if you want to persist the new value.
2664
2665 Note also that the variables will need to be pickleable; most basic
2666 python types can be safely %stored.
2667 """
2668
2669 opts,argsl = self.parse_options(parameter_s,'dr',mode='string')
2670 args = argsl.split(None,1)
2671 ip = self.getapi()
2672 # delete
2673 if opts.has_key('d'):
2674 try:
2675 todel = args[0]
2676 except IndexError:
2677 error('You must provide the variable to forget')
2678 else:
2679 try:
2680 del self.shell.persist['S:' + todel]
2681 except:
2682 error("Can't delete variable '%s'" % todel)
2683 # reset
2684 elif opts.has_key('r'):
2685 for k in self.shell.persist.keys():
2686 if k.startswith('S:'):
2687 del self.shell.persist[k]
2688
2689 # run without arguments -> list variables & values
2690 elif not args:
2691 vars = [v[2:] for v in self.shell.persist.keys()
2692 if v.startswith('S:')]
2693 vars.sort()
2694 if vars:
2695 size = max(map(len,vars))
2696 else:
2697 size = 0
2698
2699 print 'Stored variables and their in-memory values:'
2700 fmt = '%-'+str(size)+'s -> %s'
2701 get = self.shell.user_ns.get
2702 for var in vars:
2703 # print 30 first characters from every var
2704 print fmt % (var,repr(get(var,'<unavailable>'))[:50])
2705
2706 # default action - store the variable
2707 else:
2708 # %store foo >file.txt or >>file.txt
2709 if len(args) > 1 and args[1].startswith('>'):
2710 fnam = os.path.expanduser(args[1].lstrip('>').lstrip())
2711 if args[1].startswith('>>'):
2712 fil = open(fnam,'a')
2713 else:
2714 fil = open(fnam,'w')
2715 obj = ip.ev(args[0])
2716 print "Writing '%s' (%s) to file '%s'." % (args[0],
2717 obj.__class__.__name__, fnam)
2718
2719
2720 if not isinstance (obj,basestring):
2721 pprint(obj,fil)
2722 else:
2723 fil.write(obj)
2724 if not obj.endswith('\n'):
2725 fil.write('\n')
2726
2727 fil.close()
2728 return
2729
2730 # %store foo
2731 obj = self.shell.user_ns[args[0] ]
2732 if isinstance(inspect.getmodule(obj), FakeModule):
2733 print textwrap.dedent("""\
2734 Warning:%s is %s
2735 Proper storage of interactively declared classes (or instances
2736 of those classes) is not possible! Only instances
2737 of classes in real modules on file system can be %%store'd.
2738 """ % (args[0], obj) )
2739 return
2740 pickled = pickle.dumps(obj)
2741 self.shell.persist[ 'S:' + args[0] ] = pickled
2742 print "Stored '%s' (%s, %d bytes)" % (args[0], obj.__class__.__name__,len(pickled))
2743 2638
2744 2639 def magic_bookmark(self, parameter_s=''):
2745 2640 """Manage IPython's bookmark system.
2746 2641
2747 2642 %bookmark <name> - set bookmark to current dir
2748 2643 %bookmark <name> <dir> - set bookmark to <dir>
2749 2644 %bookmark -l - list all bookmarks
2750 2645 %bookmark -d <name> - remove bookmark
2751 2646 %bookmark -r - remove all bookmarks
2752 2647
2753 2648 You can later on access a bookmarked folder with:
2754 2649 %cd -b <name>
2755 2650 or simply '%cd <name>' if there is no directory called <name> AND
2756 2651 there is such a bookmark defined.
2757 2652
2758 2653 Your bookmarks persist through IPython sessions, but they are
2759 2654 associated with each profile."""
2760 2655
2761 2656 opts,args = self.parse_options(parameter_s,'drl',mode='list')
2762 2657 if len(args) > 2:
2763 2658 error('You can only give at most two arguments')
2764 2659 return
2765 2660
2766 bkms = self.shell.persist.get('bookmarks',{})
2661 bkms = self.db.get('bookmarks',{})
2767 2662
2768 2663 if opts.has_key('d'):
2769 2664 try:
2770 2665 todel = args[0]
2771 2666 except IndexError:
2772 2667 error('You must provide a bookmark to delete')
2773 2668 else:
2774 2669 try:
2775 2670 del bkms[todel]
2776 2671 except:
2777 2672 error("Can't delete bookmark '%s'" % todel)
2778 2673 elif opts.has_key('r'):
2779 2674 bkms = {}
2780 2675 elif opts.has_key('l'):
2781 2676 bks = bkms.keys()
2782 2677 bks.sort()
2783 2678 if bks:
2784 2679 size = max(map(len,bks))
2785 2680 else:
2786 2681 size = 0
2787 2682 fmt = '%-'+str(size)+'s -> %s'
2788 2683 print 'Current bookmarks:'
2789 2684 for bk in bks:
2790 2685 print fmt % (bk,bkms[bk])
2791 2686 else:
2792 2687 if not args:
2793 2688 error("You must specify the bookmark name")
2794 2689 elif len(args)==1:
2795 2690 bkms[args[0]] = os.getcwd()
2796 2691 elif len(args)==2:
2797 2692 bkms[args[0]] = args[1]
2798 self.shell.persist['bookmarks'] = bkms
2693 self.db['bookmarks'] = bkms
2799 2694
2800 2695 def magic_pycat(self, parameter_s=''):
2801 2696 """Show a syntax-highlighted file through a pager.
2802 2697
2803 2698 This magic is similar to the cat utility, but it will assume the file
2804 2699 to be Python source and will show it with syntax highlighting. """
2805 2700
2806 2701 filename = get_py_filename(parameter_s)
2807 2702 page(self.shell.pycolorize(file_read(filename)),
2808 2703 screen_lines=self.shell.rc.screen_length)
2809 2704
2810 2705 def magic_cpaste(self, parameter_s=''):
2811 2706 """Allows you to paste & execute a pre-formatted code block from
2812 2707 clipboard.
2813 2708
2814 2709 You must terminate the block with '--' (two minus-signs) alone on the
2815 2710 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
2816 2711 is the new sentinel for this operation)
2817 2712
2818 2713 The block is dedented prior to execution to enable execution of
2819 2714 method definitions. The executed block is also assigned to variable
2820 2715 named 'pasted_block' for later editing with '%edit pasted_block'.
2821 2716
2822 2717 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
2823 2718 This assigns the pasted block to variable 'foo' as string, without
2824 2719 dedenting or executing it.
2825 2720
2826 2721 Do not be alarmed by garbled output on Windows (it's a readline bug).
2827 2722 Just press enter and type -- (and press enter again) and the block
2828 2723 will be what was just pasted.
2829 2724
2830 2725 IPython statements (magics, shell escapes) are not supported (yet).
2831 2726 """
2832 2727 opts,args = self.parse_options(parameter_s,'s:',mode='string')
2833 2728 par = args.strip()
2834 2729 sentinel = opts.get('s','--')
2835 2730
2836 2731 from IPython import iplib
2837 2732 lines = []
2838 2733 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
2839 2734 while 1:
2840 2735 l = iplib.raw_input_original(':')
2841 2736 if l ==sentinel:
2842 2737 break
2843 2738 lines.append(l)
2844 2739 block = "\n".join(lines) + '\n'
2845 2740 #print "block:\n",block
2846 2741 if not par:
2847 2742 b = textwrap.dedent(block)
2848 2743 exec b in self.user_ns
2849 2744 self.user_ns['pasted_block'] = b
2850 2745 else:
2851 2746 self.user_ns[par] = block
2852 2747 print "Block assigned to '%s'" % par
2853 2748 def magic_quickref(self,arg):
2854 2749 import IPython.usage
2855 2750 page(IPython.usage.quick_reference)
2856 2751 del IPython.usage
2857 2752
2858 2753
2859 2754 # end Magic
@@ -1,169 +1,184 b''
1 1 """hooks for IPython.
2 2
3 3 In Python, it is possible to overwrite any method of any object if you really
4 4 want to. But IPython exposes a few 'hooks', methods which are _designed_ to
5 5 be overwritten by users for customization purposes. This module defines the
6 6 default versions of all such hooks, which get used by IPython if not
7 7 overridden by the user.
8 8
9 9 hooks are simple functions, but they should be declared with 'self' as their
10 10 first argument, because when activated they are registered into IPython as
11 11 instance methods. The self argument will be the IPython running instance
12 12 itself, so hooks have full access to the entire IPython object.
13 13
14 14 If you wish to define a new hook and activate it, you need to put the
15 15 necessary code into a python file which can be either imported or execfile()'d
16 16 from within your ipythonrc configuration.
17 17
18 18 For example, suppose that you have a module called 'myiphooks' in your
19 19 PYTHONPATH, which contains the following definition:
20 20
21 21 import os
22 22 import IPython.ipapi
23 23 ip = IPython.ipapi.get()
24 24
25 25 def calljed(self,filename, linenum):
26 26 "My editor hook calls the jed editor directly."
27 27 print "Calling my own editor, jed ..."
28 28 os.system('jed +%d %s' % (linenum,filename))
29 29
30 30 ip.set_hook('editor', calljed)
31 31
32 32 You can then enable the functionality by doing 'import myiphooks'
33 33 somewhere in your configuration files or ipython command line.
34 34
35 $Id: hooks.py 1095 2006-01-28 19:43:56Z vivainio $"""
35 $Id: hooks.py 1107 2006-01-30 19:02:20Z vivainio $"""
36 36
37 37 #*****************************************************************************
38 38 # Copyright (C) 2005 Fernando Perez. <fperez@colorado.edu>
39 39 #
40 40 # Distributed under the terms of the BSD License. The full license is in
41 41 # the file COPYING, distributed as part of this software.
42 42 #*****************************************************************************
43 43
44 44 from IPython import Release
45 45 from IPython import ipapi
46 46 __author__ = '%s <%s>' % Release.authors['Fernando']
47 47 __license__ = Release.license
48 48 __version__ = Release.version
49 49
50 50 import os,bisect
51 51 from genutils import Term
52 52 from pprint import pformat
53 53
54 54 # List here all the default hooks. For now it's just the editor functions
55 55 # but over time we'll move here all the public API for user-accessible things.
56 56 __all__ = ['editor', 'fix_error_editor', 'result_display',
57 'input_prefilter']
57 'input_prefilter', 'shutdown_hook', 'late_startup_hook']
58 58
59 59 def editor(self,filename, linenum=None):
60 60 """Open the default editor at the given filename and linenumber.
61 61
62 62 This is IPython's default editor hook, you can use it as an example to
63 63 write your own modified one. To set your own editor function as the
64 64 new editor hook, call ip.set_hook('editor',yourfunc)."""
65 65
66 66 # IPython configures a default editor at startup by reading $EDITOR from
67 67 # the environment, and falling back on vi (unix) or notepad (win32).
68 68 editor = self.rc.editor
69 69
70 70 # marker for at which line to open the file (for existing objects)
71 71 if linenum is None or editor=='notepad':
72 72 linemark = ''
73 73 else:
74 74 linemark = '+%d' % linenum
75 75 # Call the actual editor
76 76 os.system('%s %s %s' % (editor,linemark,filename))
77 77
78 78 import tempfile
79 79 def fix_error_editor(self,filename,linenum,column,msg):
80 80 """Open the editor at the given filename, linenumber, column and
81 81 show an error message. This is used for correcting syntax errors.
82 82 The current implementation only has special support for the VIM editor,
83 83 and falls back on the 'editor' hook if VIM is not used.
84 84
85 85 Call ip.set_hook('fix_error_editor',youfunc) to use your own function,
86 86 """
87 87 def vim_quickfix_file():
88 88 t = tempfile.NamedTemporaryFile()
89 89 t.write('%s:%d:%d:%s\n' % (filename,linenum,column,msg))
90 90 t.flush()
91 91 return t
92 92 if os.path.basename(self.rc.editor) != 'vim':
93 93 self.hooks.editor(filename,linenum)
94 94 return
95 95 t = vim_quickfix_file()
96 96 try:
97 97 os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name)
98 98 finally:
99 99 t.close()
100 100
101 101
102 102 class CommandChainDispatcher:
103 103 """ Dispatch calls to a chain of commands until some func can handle it
104 104
105 105 Usage: instantiate, execute "add" to add commands (with optional
106 106 priority), execute normally via f() calling mechanism.
107 107
108 108 """
109 109 def __init__(self,commands=None):
110 110 if commands is None:
111 111 self.chain = []
112 112 else:
113 113 self.chain = commands
114 114
115 115
116 116 def __call__(self,*args, **kw):
117 117 """ Command chain is called just like normal func.
118 118
119 119 This will call all funcs in chain with the same args as were given to this
120 120 function, and return the result of first func that didn't raise
121 121 TryNext """
122 122
123 123 for prio,cmd in self.chain:
124 124 #print "prio",prio,"cmd",cmd #dbg
125 125 try:
126 126 ret = cmd(*args, **kw)
127 127 return ret
128 128 except ipapi.TryNext:
129 129 pass
130 130
131 131 def __str__(self):
132 132 return str(self.chain)
133 133
134 134 def add(self, func, priority=0):
135 135 """ Add a func to the cmd chain with given priority """
136 136 bisect.insort(self.chain,(priority,func))
137 137
138 138 def result_display(self,arg):
139 139 """ Default display hook.
140 140
141 141 Called for displaying the result to the user.
142 142 """
143 143
144 144 if self.rc.pprint:
145 145 out = pformat(arg)
146 146 if '\n' in out:
147 147 # So that multi-line strings line up with the left column of
148 148 # the screen, instead of having the output prompt mess up
149 149 # their first line.
150 150 Term.cout.write('\n')
151 151 print >>Term.cout, out
152 152 else:
153 153 print >>Term.cout, arg
154 154 # the default display hook doesn't manipulate the value to put in history
155 155 return None
156 156
157 157 def input_prefilter(self,line):
158 158 """ Default input prefilter
159 159
160 160 This returns the line as unchanged, so that the interpreter
161 161 knows that nothing was done and proceeds with "classic" prefiltering
162 162 (%magics, !shell commands etc.).
163 163
164 164 Note that leading whitespace is not passed to this hook. Prefilter
165 165 can't alter indentation.
166 166
167 167 """
168 168 #print "attempt to rewrite",line #dbg
169 return line No newline at end of file
169 return line
170
171 def shutdown_hook(self):
172 """ default shutdown hook
173
174 Typically, shotdown hooks should raise TryNext so all shutdown ops are done
175 """
176
177 #print "default shutdown hook ok" # dbg
178 return
179
180 def late_startup_hook(self):
181 """ Executed after ipython has been constructed and configured
182
183 """
184 #print "default startup hook ok" # dbg No newline at end of file
@@ -1,177 +1,184 b''
1 1 ''' IPython customization API
2 2
3 3 Your one-stop module for configuring & extending ipython
4 4
5 5 The API will probably break when ipython 1.0 is released, but so
6 6 will the other configuration method (rc files).
7 7
8 8 All names prefixed by underscores are for internal use, not part
9 9 of the public api.
10 10
11 11 Below is an example that you can just put to a module and import from ipython.
12 12
13 13 A good practice is to install the config script below as e.g.
14 14
15 15 ~/.ipython/my_private_conf.py
16 16
17 17 And do
18 18
19 19 import_mod my_private_conf
20 20
21 21 in ~/.ipython/ipythonrc
22 22
23 23 That way the module is imported at startup and you can have all your
24 24 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME
25 25 stuff) in there.
26 26
27 27 -----------------------------------------------
28 28 import IPython.ipapi as ip
29 29
30 30 def ankka_f(self, arg):
31 31 print "Ankka",self,"says uppercase:",arg.upper()
32 32
33 33 ip.expose_magic("ankka",ankka_f)
34 34
35 35 ip.magic('alias sayhi echo "Testing, hi ok"')
36 36 ip.magic('alias helloworld echo "Hello world"')
37 37 ip.system('pwd')
38 38
39 39 ip.ex('import re')
40 40 ip.ex("""
41 41 def funcci(a,b):
42 42 print a+b
43 43 print funcci(3,4)
44 44 """)
45 45 ip.ex("funcci(348,9)")
46 46
47 47 def jed_editor(self,filename, linenum=None):
48 48 print "Calling my own editor, jed ... via hook!"
49 49 import os
50 50 if linenum is None: linenum = 0
51 51 os.system('jed +%d %s' % (linenum, filename))
52 52 print "exiting jed"
53 53
54 54 ip.set_hook('editor',jed_editor)
55 55
56 56 o = ip.options()
57 57 o.autocall = 2 # FULL autocall mode
58 58
59 59 print "done!"
60 60
61 61 '''
62 62
63 63
64 64 class TryNext(Exception):
65 65 """ Try next hook exception.
66 66
67 67 Raise this in your hook function to indicate that the next
68 68 hook handler should be used to handle the operation.
69 69 """
70 70
71 71
72 72 # contains the most recently instantiated IPApi
73 73 _recent = None
74 74
75 75 def get():
76 76 """ Get an IPApi object, or None if not running under ipython
77 77
78 78 Running this should be the first thing you do when writing
79 79 extensions that can be imported as normal modules. You can then
80 80 direct all the configuration operations against the returned
81 81 object.
82 82
83 83 """
84 84
85 85 return _recent
86 86
87 87
88 88
89 89 class IPApi:
90 90 """ The actual API class for configuring IPython
91 91
92 92 You should do all of the IPython configuration by getting
93 93 an IPApi object with IPython.ipapi.get() and using the provided
94 94 methods.
95 95
96 96 """
97 97 def __init__(self,ip):
98 98
99 99 self.magic = ip.ipmagic
100 100
101 101 self.system = ip.ipsystem
102 102
103 103 self.set_hook = ip.set_hook
104 104
105 105 self.IP = ip
106 106 global _recent
107 107 _recent = self
108 108
109 109
110 110
111 111 def options(self):
112 112 """ All configurable variables """
113 113 return self.IP.rc
114 114
115 115 def user_ns(self):
116 116 return self.IP.user_ns
117 117
118 118 def expose_magic(self,magicname, func):
119 119 ''' Expose own function as magic function for ipython
120 120
121 121 def foo_impl(self,parameter_s=''):
122 122 """My very own magic!. (Use docstrings, IPython reads them)."""
123 123 print 'Magic function. Passed parameter is between < >: <'+parameter_s+'>'
124 124 print 'The self object is:',self
125 125
126 126 ipapi.expose_magic("foo",foo_impl)
127 127 '''
128 128
129 129 import new
130 130 im = new.instancemethod(func,self.IP, self.IP.__class__)
131 131 setattr(self.IP, "magic_" + magicname, im)
132 132
133 133
134 134 def ex(self,cmd):
135 135 """ Execute a normal python statement in user namespace """
136 136 exec cmd in self.user_ns()
137 137
138 138 def ev(self,expr):
139 139 """ Evaluate python expression expr in user namespace
140 140
141 141 Returns the result of evaluation"""
142 142 return eval(expr,self.user_ns())
143 143
144 144 def meta(self):
145 145 """ Get a session-specific data store
146 146
147 147 Object returned by this method can be used to store
148 148 data that should persist through the ipython session.
149 149 """
150 150 return self.IP.meta
151
152 def getdb(self):
153 """ Return a handle to persistent dict-like database
154
155 Return a PickleShareDB object.
156 """
157 return self.IP.db
151 158
152 159
153 160 def launch_new_instance(user_ns = None):
154 161 """ Create and start a new ipython instance.
155 162
156 163 This can be called even without having an already initialized
157 164 ipython session running.
158 165
159 166 This is also used as the egg entry point for the 'ipython' script.
160 167
161 168 """
162 169 ses = create_session(user_ns)
163 170 ses.mainloop()
164 171
165 172
166 173 def create_session(user_ns = None):
167 174 """ Creates, but does not launch an IPython session.
168 175
169 176 Later on you can call obj.mainloop() on the returned object.
170 177
171 178 This should *not* be run when a session exists already.
172 179
173 180 """
174 181 if user_ns is not None:
175 182 user_ns["__name__"] = user_ns.get("__name__",'ipy_session')
176 183 import IPython
177 184 return IPython.Shell.start(user_ns = user_ns) No newline at end of file
@@ -1,2267 +1,2244 b''
1 1 # -*- coding: utf-8 -*-
2 2 """
3 3 IPython -- An enhanced Interactive Python
4 4
5 5 Requires Python 2.3 or newer.
6 6
7 7 This file contains all the classes and helper functions specific to IPython.
8 8
9 $Id: iplib.py 1102 2006-01-30 06:08:16Z fperez $
9 $Id: iplib.py 1107 2006-01-30 19:02:20Z vivainio $
10 10 """
11 11
12 12 #*****************************************************************************
13 13 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
14 14 # Copyright (C) 2001-2006 Fernando Perez. <fperez@colorado.edu>
15 15 #
16 16 # Distributed under the terms of the BSD License. The full license is in
17 17 # the file COPYING, distributed as part of this software.
18 18 #
19 19 # Note: this code originally subclassed code.InteractiveConsole from the
20 20 # Python standard library. Over time, all of that class has been copied
21 21 # verbatim here for modifications which could not be accomplished by
22 22 # subclassing. At this point, there are no dependencies at all on the code
23 23 # module anymore (it is not even imported). The Python License (sec. 2)
24 24 # allows for this, but it's always nice to acknowledge credit where credit is
25 25 # due.
26 26 #*****************************************************************************
27 27
28 28 #****************************************************************************
29 29 # Modules and globals
30 30
31 31 from __future__ import generators # for 2.2 backwards-compatibility
32 32
33 33 from IPython import Release
34 34 __author__ = '%s <%s>\n%s <%s>' % \
35 35 ( Release.authors['Janko'] + Release.authors['Fernando'] )
36 36 __license__ = Release.license
37 37 __version__ = Release.version
38 38
39 39 # Python standard modules
40 40 import __main__
41 41 import __builtin__
42 42 import StringIO
43 43 import bdb
44 44 import cPickle as pickle
45 45 import codeop
46 46 import exceptions
47 47 import glob
48 48 import inspect
49 49 import keyword
50 50 import new
51 51 import os
52 52 import pdb
53 53 import pydoc
54 54 import re
55 55 import shutil
56 56 import string
57 57 import sys
58 58 import tempfile
59 59 import traceback
60 60 import types
61 import pickleshare
61 62
62 63 from pprint import pprint, pformat
63 64
64 65 # IPython's own modules
65 66 import IPython
66 67 from IPython import OInspect,PyColorize,ultraTB
67 68 from IPython.ColorANSI import ColorScheme,ColorSchemeTable # too long names
68 69 from IPython.FakeModule import FakeModule
69 70 from IPython.Itpl import Itpl,itpl,printpl,ItplNS,itplns
70 71 from IPython.Logger import Logger
71 72 from IPython.Magic import Magic
72 73 from IPython.Prompts import CachedOutput
73 74 from IPython.ipstruct import Struct
74 75 from IPython.background_jobs import BackgroundJobManager
75 76 from IPython.usage import cmd_line_usage,interactive_usage
76 77 from IPython.genutils import *
77 78 import IPython.ipapi
78 79
79 80 # Globals
80 81
81 82 # store the builtin raw_input globally, and use this always, in case user code
82 83 # overwrites it (like wx.py.PyShell does)
83 84 raw_input_original = raw_input
84 85
85 86 # compiled regexps for autoindent management
86 87 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
87 88
88 89
89 90 #****************************************************************************
90 91 # Some utility function definitions
91 92
92 93 ini_spaces_re = re.compile(r'^(\s+)')
93 94
94 95 def num_ini_spaces(strng):
95 96 """Return the number of initial spaces in a string"""
96 97
97 98 ini_spaces = ini_spaces_re.match(strng)
98 99 if ini_spaces:
99 100 return ini_spaces.end()
100 101 else:
101 102 return 0
102 103
103 104 def softspace(file, newvalue):
104 105 """Copied from code.py, to remove the dependency"""
105 106
106 107 oldvalue = 0
107 108 try:
108 109 oldvalue = file.softspace
109 110 except AttributeError:
110 111 pass
111 112 try:
112 113 file.softspace = newvalue
113 114 except (AttributeError, TypeError):
114 115 # "attribute-less object" or "read-only attributes"
115 116 pass
116 117 return oldvalue
117 118
118 119
119 120 #****************************************************************************
120 121 # Local use exceptions
121 122 class SpaceInInput(exceptions.Exception): pass
122 123
123 124
124 125 #****************************************************************************
125 126 # Local use classes
126 127 class Bunch: pass
127 128
128 129 class Undefined: pass
129 130
130 131 class InputList(list):
131 132 """Class to store user input.
132 133
133 134 It's basically a list, but slices return a string instead of a list, thus
134 135 allowing things like (assuming 'In' is an instance):
135 136
136 137 exec In[4:7]
137 138
138 139 or
139 140
140 141 exec In[5:9] + In[14] + In[21:25]"""
141 142
142 143 def __getslice__(self,i,j):
143 144 return ''.join(list.__getslice__(self,i,j))
144 145
145 146 class SyntaxTB(ultraTB.ListTB):
146 147 """Extension which holds some state: the last exception value"""
147 148
148 149 def __init__(self,color_scheme = 'NoColor'):
149 150 ultraTB.ListTB.__init__(self,color_scheme)
150 151 self.last_syntax_error = None
151 152
152 153 def __call__(self, etype, value, elist):
153 154 self.last_syntax_error = value
154 155 ultraTB.ListTB.__call__(self,etype,value,elist)
155 156
156 157 def clear_err_state(self):
157 158 """Return the current error state and clear it"""
158 159 e = self.last_syntax_error
159 160 self.last_syntax_error = None
160 161 return e
161 162
162 163 #****************************************************************************
163 164 # Main IPython class
164 165
165 166 # FIXME: the Magic class is a mixin for now, and will unfortunately remain so
166 167 # until a full rewrite is made. I've cleaned all cross-class uses of
167 168 # attributes and methods, but too much user code out there relies on the
168 169 # equlity %foo == __IP.magic_foo, so I can't actually remove the mixin usage.
169 170 #
170 171 # But at least now, all the pieces have been separated and we could, in
171 172 # principle, stop using the mixin. This will ease the transition to the
172 173 # chainsaw branch.
173 174
174 175 # For reference, the following is the list of 'self.foo' uses in the Magic
175 176 # class as of 2005-12-28. These are names we CAN'T use in the main ipython
176 177 # class, to prevent clashes.
177 178
178 179 # ['self.__class__', 'self.__dict__', 'self._inspect', 'self._ofind',
179 180 # 'self.arg_err', 'self.extract_input', 'self.format_', 'self.lsmagic',
180 181 # 'self.magic_', 'self.options_table', 'self.parse', 'self.shell',
181 182 # 'self.value']
182 183
183 184 class InteractiveShell(object,Magic):
184 185 """An enhanced console for Python."""
185 186
186 187 # class attribute to indicate whether the class supports threads or not.
187 188 # Subclasses with thread support should override this as needed.
188 189 isthreaded = False
189 190
190 191 def __init__(self,name,usage=None,rc=Struct(opts=None,args=None),
191 192 user_ns = None,user_global_ns=None,banner2='',
192 193 custom_exceptions=((),None),embedded=False):
193 194
195
194 196 # log system
195 197 self.logger = Logger(self,logfname='ipython_log.py',logmode='rotate')
196 198
197 199 # Produce a public API instance
198 200
199 201 self.api = IPython.ipapi.IPApi(self)
200 202
201 203 # some minimal strict typechecks. For some core data structures, I
202 204 # want actual basic python types, not just anything that looks like
203 205 # one. This is especially true for namespaces.
204 206 for ns in (user_ns,user_global_ns):
205 207 if ns is not None and type(ns) != types.DictType:
206 208 raise TypeError,'namespace must be a dictionary'
207 209
208 210 # Job manager (for jobs run as background threads)
209 211 self.jobs = BackgroundJobManager()
210 212
211 213 # track which builtins we add, so we can clean up later
212 214 self.builtins_added = {}
213 215 # This method will add the necessary builtins for operation, but
214 216 # tracking what it did via the builtins_added dict.
215 217 self.add_builtins()
216 218
217 219 # Do the intuitively correct thing for quit/exit: we remove the
218 220 # builtins if they exist, and our own magics will deal with this
219 221 try:
220 222 del __builtin__.exit, __builtin__.quit
221 223 except AttributeError:
222 224 pass
223 225
224 226 # Store the actual shell's name
225 227 self.name = name
226 228
227 229 # We need to know whether the instance is meant for embedding, since
228 230 # global/local namespaces need to be handled differently in that case
229 231 self.embedded = embedded
230 232
231 233 # command compiler
232 234 self.compile = codeop.CommandCompiler()
233 235
234 236 # User input buffer
235 237 self.buffer = []
236 238
237 239 # Default name given in compilation of code
238 240 self.filename = '<ipython console>'
239 241
240 242 # Make an empty namespace, which extension writers can rely on both
241 243 # existing and NEVER being used by ipython itself. This gives them a
242 244 # convenient location for storing additional information and state
243 245 # their extensions may require, without fear of collisions with other
244 246 # ipython names that may develop later.
245 247 self.meta = Struct()
246 248
247 249 # Create the namespace where the user will operate. user_ns is
248 250 # normally the only one used, and it is passed to the exec calls as
249 251 # the locals argument. But we do carry a user_global_ns namespace
250 252 # given as the exec 'globals' argument, This is useful in embedding
251 253 # situations where the ipython shell opens in a context where the
252 254 # distinction between locals and globals is meaningful.
253 255
254 256 # FIXME. For some strange reason, __builtins__ is showing up at user
255 257 # level as a dict instead of a module. This is a manual fix, but I
256 258 # should really track down where the problem is coming from. Alex
257 259 # Schmolck reported this problem first.
258 260
259 261 # A useful post by Alex Martelli on this topic:
260 262 # Re: inconsistent value from __builtins__
261 263 # Von: Alex Martelli <aleaxit@yahoo.com>
262 264 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
263 265 # Gruppen: comp.lang.python
264 266
265 267 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
266 268 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
267 269 # > <type 'dict'>
268 270 # > >>> print type(__builtins__)
269 271 # > <type 'module'>
270 272 # > Is this difference in return value intentional?
271 273
272 274 # Well, it's documented that '__builtins__' can be either a dictionary
273 275 # or a module, and it's been that way for a long time. Whether it's
274 276 # intentional (or sensible), I don't know. In any case, the idea is
275 277 # that if you need to access the built-in namespace directly, you
276 278 # should start with "import __builtin__" (note, no 's') which will
277 279 # definitely give you a module. Yeah, it's somewhat confusing:-(.
278 280
279 281 if user_ns is None:
280 282 # Set __name__ to __main__ to better match the behavior of the
281 283 # normal interpreter.
282 284 user_ns = {'__name__' :'__main__',
283 285 '__builtins__' : __builtin__,
284 286 }
285 287
286 288 if user_global_ns is None:
287 289 user_global_ns = {}
288 290
289 291 # Assign namespaces
290 292 # This is the namespace where all normal user variables live
291 293 self.user_ns = user_ns
292 294 # Embedded instances require a separate namespace for globals.
293 295 # Normally this one is unused by non-embedded instances.
294 296 self.user_global_ns = user_global_ns
295 297 # A namespace to keep track of internal data structures to prevent
296 298 # them from cluttering user-visible stuff. Will be updated later
297 299 self.internal_ns = {}
298 300
299 301 # Namespace of system aliases. Each entry in the alias
300 302 # table must be a 2-tuple of the form (N,name), where N is the number
301 303 # of positional arguments of the alias.
302 304 self.alias_table = {}
303 305
304 306 # A table holding all the namespaces IPython deals with, so that
305 307 # introspection facilities can search easily.
306 308 self.ns_table = {'user':user_ns,
307 309 'user_global':user_global_ns,
308 310 'alias':self.alias_table,
309 311 'internal':self.internal_ns,
310 312 'builtin':__builtin__.__dict__
311 313 }
312 314
313 315 # The user namespace MUST have a pointer to the shell itself.
314 316 self.user_ns[name] = self
315 317
316 318 # We need to insert into sys.modules something that looks like a
317 319 # module but which accesses the IPython namespace, for shelve and
318 320 # pickle to work interactively. Normally they rely on getting
319 321 # everything out of __main__, but for embedding purposes each IPython
320 322 # instance has its own private namespace, so we can't go shoving
321 323 # everything into __main__.
322 324
323 325 # note, however, that we should only do this for non-embedded
324 326 # ipythons, which really mimic the __main__.__dict__ with their own
325 327 # namespace. Embedded instances, on the other hand, should not do
326 328 # this because they need to manage the user local/global namespaces
327 329 # only, but they live within a 'normal' __main__ (meaning, they
328 330 # shouldn't overtake the execution environment of the script they're
329 331 # embedded in).
330 332
331 333 if not embedded:
332 334 try:
333 335 main_name = self.user_ns['__name__']
334 336 except KeyError:
335 337 raise KeyError,'user_ns dictionary MUST have a "__name__" key'
336 338 else:
337 339 #print "pickle hack in place" # dbg
338 340 #print 'main_name:',main_name # dbg
339 341 sys.modules[main_name] = FakeModule(self.user_ns)
340 342
341 343 # List of input with multi-line handling.
342 344 # Fill its zero entry, user counter starts at 1
343 345 self.input_hist = InputList(['\n'])
344 346 # This one will hold the 'raw' input history, without any
345 347 # pre-processing. This will allow users to retrieve the input just as
346 348 # it was exactly typed in by the user, with %hist -r.
347 349 self.input_hist_raw = InputList(['\n'])
348 350
349 351 # list of visited directories
350 352 try:
351 353 self.dir_hist = [os.getcwd()]
352 354 except IOError, e:
353 355 self.dir_hist = []
354 356
355 357 # dict of output history
356 358 self.output_hist = {}
357 359
358 360 # dict of things NOT to alias (keywords, builtins and some magics)
359 361 no_alias = {}
360 362 no_alias_magics = ['cd','popd','pushd','dhist','alias','unalias']
361 363 for key in keyword.kwlist + no_alias_magics:
362 364 no_alias[key] = 1
363 365 no_alias.update(__builtin__.__dict__)
364 366 self.no_alias = no_alias
365 367
366 368 # make global variables for user access to these
367 369 self.user_ns['_ih'] = self.input_hist
368 370 self.user_ns['_oh'] = self.output_hist
369 371 self.user_ns['_dh'] = self.dir_hist
370 372
371 373 # user aliases to input and output histories
372 374 self.user_ns['In'] = self.input_hist
373 375 self.user_ns['Out'] = self.output_hist
374 376
375 377 # Object variable to store code object waiting execution. This is
376 378 # used mainly by the multithreaded shells, but it can come in handy in
377 379 # other situations. No need to use a Queue here, since it's a single
378 380 # item which gets cleared once run.
379 381 self.code_to_run = None
380 382
381 383 # escapes for automatic behavior on the command line
382 384 self.ESC_SHELL = '!'
383 385 self.ESC_HELP = '?'
384 386 self.ESC_MAGIC = '%'
385 387 self.ESC_QUOTE = ','
386 388 self.ESC_QUOTE2 = ';'
387 389 self.ESC_PAREN = '/'
388 390
389 391 # And their associated handlers
390 392 self.esc_handlers = {self.ESC_PAREN : self.handle_auto,
391 393 self.ESC_QUOTE : self.handle_auto,
392 394 self.ESC_QUOTE2 : self.handle_auto,
393 395 self.ESC_MAGIC : self.handle_magic,
394 396 self.ESC_HELP : self.handle_help,
395 397 self.ESC_SHELL : self.handle_shell_escape,
396 398 }
397 399
398 400 # class initializations
399 401 Magic.__init__(self,self)
400 402
401 403 # Python source parser/formatter for syntax highlighting
402 404 pyformat = PyColorize.Parser().format
403 405 self.pycolorize = lambda src: pyformat(src,'str',self.rc['colors'])
404 406
405 407 # hooks holds pointers used for user-side customizations
406 408 self.hooks = Struct()
407 409
408 410 # Set all default hooks, defined in the IPython.hooks module.
409 411 hooks = IPython.hooks
410 412 for hook_name in hooks.__all__:
411 413 # default hooks have priority 100, i.e. low; user hooks should have 0-100 priority
412 414 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
413 415 #print "bound hook",hook_name
414 416
415 417 # Flag to mark unconditional exit
416 418 self.exit_now = False
417 419
418 420 self.usage_min = """\
419 421 An enhanced console for Python.
420 422 Some of its features are:
421 423 - Readline support if the readline library is present.
422 424 - Tab completion in the local namespace.
423 425 - Logging of input, see command-line options.
424 426 - System shell escape via ! , eg !ls.
425 427 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
426 428 - Keeps track of locally defined variables via %who, %whos.
427 429 - Show object information with a ? eg ?x or x? (use ?? for more info).
428 430 """
429 431 if usage: self.usage = usage
430 432 else: self.usage = self.usage_min
431 433
432 434 # Storage
433 435 self.rc = rc # This will hold all configuration information
434 436 self.pager = 'less'
435 437 # temporary files used for various purposes. Deleted at exit.
436 438 self.tempfiles = []
437 439
438 440 # Keep track of readline usage (later set by init_readline)
439 441 self.has_readline = False
440 442
441 443 # template for logfile headers. It gets resolved at runtime by the
442 444 # logstart method.
443 445 self.loghead_tpl = \
444 446 """#log# Automatic Logger file. *** THIS MUST BE THE FIRST LINE ***
445 447 #log# DO NOT CHANGE THIS LINE OR THE TWO BELOW
446 448 #log# opts = %s
447 449 #log# args = %s
448 450 #log# It is safe to make manual edits below here.
449 451 #log#-----------------------------------------------------------------------
450 452 """
451 453 # for pushd/popd management
452 454 try:
453 455 self.home_dir = get_home_dir()
454 456 except HomeDirError,msg:
455 457 fatal(msg)
456 458
457 459 self.dir_stack = [os.getcwd().replace(self.home_dir,'~')]
458 460
459 461 # Functions to call the underlying shell.
460 462
461 463 # utility to expand user variables via Itpl
462 464 self.var_expand = lambda cmd: str(ItplNS(cmd.replace('#','\#'),
463 465 self.user_ns))
464 466 # The first is similar to os.system, but it doesn't return a value,
465 467 # and it allows interpolation of variables in the user's namespace.
466 468 self.system = lambda cmd: shell(self.var_expand(cmd),
467 469 header='IPython system call: ',
468 470 verbose=self.rc.system_verbose)
469 471 # These are for getoutput and getoutputerror:
470 472 self.getoutput = lambda cmd: \
471 473 getoutput(self.var_expand(cmd),
472 474 header='IPython system call: ',
473 475 verbose=self.rc.system_verbose)
474 476 self.getoutputerror = lambda cmd: \
475 477 getoutputerror(str(ItplNS(cmd.replace('#','\#'),
476 478 self.user_ns)),
477 479 header='IPython system call: ',
478 480 verbose=self.rc.system_verbose)
479 481
480 482 # RegExp for splitting line contents into pre-char//first
481 483 # word-method//rest. For clarity, each group in on one line.
482 484
483 485 # WARNING: update the regexp if the above escapes are changed, as they
484 486 # are hardwired in.
485 487
486 488 # Don't get carried away with trying to make the autocalling catch too
487 489 # much: it's better to be conservative rather than to trigger hidden
488 490 # evals() somewhere and end up causing side effects.
489 491
490 492 self.line_split = re.compile(r'^([\s*,;/])'
491 493 r'([\?\w\.]+\w*\s*)'
492 494 r'(\(?.*$)')
493 495
494 496 # Original re, keep around for a while in case changes break something
495 497 #self.line_split = re.compile(r'(^[\s*!\?%,/]?)'
496 498 # r'(\s*[\?\w\.]+\w*\s*)'
497 499 # r'(\(?.*$)')
498 500
499 501 # RegExp to identify potential function names
500 502 self.re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
501 503
502 504 # RegExp to exclude strings with this start from autocalling. In
503 505 # particular, all binary operators should be excluded, so that if foo
504 506 # is callable, foo OP bar doesn't become foo(OP bar), which is
505 507 # invalid. The characters '!=()' don't need to be checked for, as the
506 508 # _prefilter routine explicitely does so, to catch direct calls and
507 509 # rebindings of existing names.
508 510
509 511 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
510 512 # it affects the rest of the group in square brackets.
511 513 self.re_exclude_auto = re.compile(r'^[<>,&^\|\*/\+-]'
512 514 '|^is |^not |^in |^and |^or ')
513 515
514 516 # try to catch also methods for stuff in lists/tuples/dicts: off
515 517 # (experimental). For this to work, the line_split regexp would need
516 518 # to be modified so it wouldn't break things at '['. That line is
517 519 # nasty enough that I shouldn't change it until I can test it _well_.
518 520 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
519 521
520 522 # keep track of where we started running (mainly for crash post-mortem)
521 523 self.starting_dir = os.getcwd()
522 524
523 525 # Various switches which can be set
524 526 self.CACHELENGTH = 5000 # this is cheap, it's just text
525 527 self.BANNER = "Python %(version)s on %(platform)s\n" % sys.__dict__
526 528 self.banner2 = banner2
527 529
528 530 # TraceBack handlers:
529 531
530 532 # Syntax error handler.
531 533 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
532 534
533 535 # The interactive one is initialized with an offset, meaning we always
534 536 # want to remove the topmost item in the traceback, which is our own
535 537 # internal code. Valid modes: ['Plain','Context','Verbose']
536 538 self.InteractiveTB = ultraTB.AutoFormattedTB(mode = 'Plain',
537 539 color_scheme='NoColor',
538 540 tb_offset = 1)
539 541
540 542 # IPython itself shouldn't crash. This will produce a detailed
541 543 # post-mortem if it does. But we only install the crash handler for
542 544 # non-threaded shells, the threaded ones use a normal verbose reporter
543 545 # and lose the crash handler. This is because exceptions in the main
544 546 # thread (such as in GUI code) propagate directly to sys.excepthook,
545 547 # and there's no point in printing crash dumps for every user exception.
546 548 if self.isthreaded:
547 549 sys.excepthook = ultraTB.FormattedTB()
548 550 else:
549 551 from IPython import CrashHandler
550 552 sys.excepthook = CrashHandler.CrashHandler(self)
551 553
552 554 # The instance will store a pointer to this, so that runtime code
553 555 # (such as magics) can access it. This is because during the
554 556 # read-eval loop, it gets temporarily overwritten (to deal with GUI
555 557 # frameworks).
556 558 self.sys_excepthook = sys.excepthook
557 559
558 560 # and add any custom exception handlers the user may have specified
559 561 self.set_custom_exc(*custom_exceptions)
560 562
561 563 # Object inspector
562 564 self.inspector = OInspect.Inspector(OInspect.InspectColors,
563 565 PyColorize.ANSICodeColors,
564 566 'NoColor')
565 567 # indentation management
566 568 self.autoindent = False
567 569 self.indent_current_nsp = 0
568 570
569 571 # Make some aliases automatically
570 572 # Prepare list of shell aliases to auto-define
571 573 if os.name == 'posix':
572 574 auto_alias = ('mkdir mkdir', 'rmdir rmdir',
573 575 'mv mv -i','rm rm -i','cp cp -i',
574 576 'cat cat','less less','clear clear',
575 577 # a better ls
576 578 'ls ls -F',
577 579 # long ls
578 580 'll ls -lF',
579 581 # color ls
580 582 'lc ls -F -o --color',
581 583 # ls normal files only
582 584 'lf ls -F -o --color %l | grep ^-',
583 585 # ls symbolic links
584 586 'lk ls -F -o --color %l | grep ^l',
585 587 # directories or links to directories,
586 588 'ldir ls -F -o --color %l | grep /$',
587 589 # things which are executable
588 590 'lx ls -F -o --color %l | grep ^-..x',
589 591 )
590 592 elif os.name in ['nt','dos']:
591 593 auto_alias = ('dir dir /on', 'ls dir /on',
592 594 'ddir dir /ad /on', 'ldir dir /ad /on',
593 595 'mkdir mkdir','rmdir rmdir','echo echo',
594 596 'ren ren','cls cls','copy copy')
595 597 else:
596 598 auto_alias = ()
597 599 self.auto_alias = map(lambda s:s.split(None,1),auto_alias)
598 600 # Call the actual (public) initializer
599 601 self.init_auto_alias()
600 602 # end __init__
601 603
602 604 def post_config_initialization(self):
603 605 """Post configuration init method
604 606
605 607 This is called after the configuration files have been processed to
606 608 'finalize' the initialization."""
607 609
608 610 rc = self.rc
609 611
612 self.db = pickleshare.PickleShareDB(rc.ipythondir + "/db")
610 613 # Load readline proper
611 614 if rc.readline:
612 615 self.init_readline()
613 616
614 617 # local shortcut, this is used a LOT
615 618 self.log = self.logger.log
616 619
617 620 # Initialize cache, set in/out prompts and printing system
618 621 self.outputcache = CachedOutput(self,
619 622 rc.cache_size,
620 623 rc.pprint,
621 624 input_sep = rc.separate_in,
622 625 output_sep = rc.separate_out,
623 626 output_sep2 = rc.separate_out2,
624 627 ps1 = rc.prompt_in1,
625 628 ps2 = rc.prompt_in2,
626 629 ps_out = rc.prompt_out,
627 630 pad_left = rc.prompts_pad_left)
628 631
629 632 # user may have over-ridden the default print hook:
630 633 try:
631 634 self.outputcache.__class__.display = self.hooks.display
632 635 except AttributeError:
633 636 pass
634 637
635 638 # I don't like assigning globally to sys, because it means when embedding
636 639 # instances, each embedded instance overrides the previous choice. But
637 640 # sys.displayhook seems to be called internally by exec, so I don't see a
638 641 # way around it.
639 642 sys.displayhook = self.outputcache
640 643
641 644 # Set user colors (don't do it in the constructor above so that it
642 645 # doesn't crash if colors option is invalid)
643 646 self.magic_colors(rc.colors)
644 647
645 648 # Set calling of pdb on exceptions
646 649 self.call_pdb = rc.pdb
647 650
648 651 # Load user aliases
649 652 for alias in rc.alias:
650 653 self.magic_alias(alias)
651
652 # dynamic data that survives through sessions
653 # XXX make the filename a config option?
654 persist_base = 'persist'
655 if rc.profile:
656 persist_base += '_%s' % rc.profile
657 self.persist_fname = os.path.join(rc.ipythondir,persist_base)
658
659 try:
660 self.persist = pickle.load(file(self.persist_fname))
661 except:
662 self.persist = {}
663
654 self.hooks.late_startup_hook()
664 655
665 for (key, value) in [(k[2:],v) for (k,v) in self.persist.items() if k.startswith('S:')]:
666 try:
667 obj = pickle.loads(value)
668 except:
669
670 print "Unable to restore variable '%s', ignoring (use %%store -d to forget!)" % key
671 print "The error was:",sys.exc_info()[0]
672 continue
673
674
675 self.user_ns[key] = obj
676 656
677 657 def add_builtins(self):
678 658 """Store ipython references into the builtin namespace.
679 659
680 660 Some parts of ipython operate via builtins injected here, which hold a
681 661 reference to IPython itself."""
682 662
683 663 # TODO: deprecate all except _ip; 'jobs' should be installed
684 664 # by an extension and the rest are under _ip
685 665 builtins_new = dict(__IPYTHON__ = self,
686 666 ip_set_hook = self.set_hook,
687 667 jobs = self.jobs,
688 668 ipmagic = self.ipmagic,
689 669 ipalias = self.ipalias,
690 670 ipsystem = self.ipsystem,
691 671 _ip = self.api
692 672 )
693 673 for biname,bival in builtins_new.items():
694 674 try:
695 675 # store the orignal value so we can restore it
696 676 self.builtins_added[biname] = __builtin__.__dict__[biname]
697 677 except KeyError:
698 678 # or mark that it wasn't defined, and we'll just delete it at
699 679 # cleanup
700 680 self.builtins_added[biname] = Undefined
701 681 __builtin__.__dict__[biname] = bival
702 682
703 683 # Keep in the builtins a flag for when IPython is active. We set it
704 684 # with setdefault so that multiple nested IPythons don't clobber one
705 685 # another. Each will increase its value by one upon being activated,
706 686 # which also gives us a way to determine the nesting level.
707 687 __builtin__.__dict__.setdefault('__IPYTHON__active',0)
708 688
709 689 def clean_builtins(self):
710 690 """Remove any builtins which might have been added by add_builtins, or
711 691 restore overwritten ones to their previous values."""
712 692 for biname,bival in self.builtins_added.items():
713 693 if bival is Undefined:
714 694 del __builtin__.__dict__[biname]
715 695 else:
716 696 __builtin__.__dict__[biname] = bival
717 697 self.builtins_added.clear()
718 698
719 699 def set_hook(self,name,hook, priority = 50):
720 700 """set_hook(name,hook) -> sets an internal IPython hook.
721 701
722 702 IPython exposes some of its internal API as user-modifiable hooks. By
723 703 adding your function to one of these hooks, you can modify IPython's
724 704 behavior to call at runtime your own routines."""
725 705
726 706 # At some point in the future, this should validate the hook before it
727 707 # accepts it. Probably at least check that the hook takes the number
728 708 # of args it's supposed to.
729 709 dp = getattr(self.hooks, name, None)
730 710 if name not in IPython.hooks.__all__:
731 711 print "Warning! Hook '%s' is not one of %s" % (name, IPython.hooks.__all__ )
732 712 if not dp:
733 713 dp = IPython.hooks.CommandChainDispatcher()
734 714
735 715 f = new.instancemethod(hook,self,self.__class__)
736 716 try:
737 717 dp.add(f,priority)
738 718 except AttributeError:
739 719 # it was not commandchain, plain old func - replace
740 720 dp = f
741 721
742 722 setattr(self.hooks,name, dp)
743 723
744 724
745 725 #setattr(self.hooks,name,new.instancemethod(hook,self,self.__class__))
746 726
747 727 def set_custom_exc(self,exc_tuple,handler):
748 728 """set_custom_exc(exc_tuple,handler)
749 729
750 730 Set a custom exception handler, which will be called if any of the
751 731 exceptions in exc_tuple occur in the mainloop (specifically, in the
752 732 runcode() method.
753 733
754 734 Inputs:
755 735
756 736 - exc_tuple: a *tuple* of valid exceptions to call the defined
757 737 handler for. It is very important that you use a tuple, and NOT A
758 738 LIST here, because of the way Python's except statement works. If
759 739 you only want to trap a single exception, use a singleton tuple:
760 740
761 741 exc_tuple == (MyCustomException,)
762 742
763 743 - handler: this must be defined as a function with the following
764 744 basic interface: def my_handler(self,etype,value,tb).
765 745
766 746 This will be made into an instance method (via new.instancemethod)
767 747 of IPython itself, and it will be called if any of the exceptions
768 748 listed in the exc_tuple are caught. If the handler is None, an
769 749 internal basic one is used, which just prints basic info.
770 750
771 751 WARNING: by putting in your own exception handler into IPython's main
772 752 execution loop, you run a very good chance of nasty crashes. This
773 753 facility should only be used if you really know what you are doing."""
774 754
775 755 assert type(exc_tuple)==type(()) , \
776 756 "The custom exceptions must be given AS A TUPLE."
777 757
778 758 def dummy_handler(self,etype,value,tb):
779 759 print '*** Simple custom exception handler ***'
780 760 print 'Exception type :',etype
781 761 print 'Exception value:',value
782 762 print 'Traceback :',tb
783 763 print 'Source code :','\n'.join(self.buffer)
784 764
785 765 if handler is None: handler = dummy_handler
786 766
787 767 self.CustomTB = new.instancemethod(handler,self,self.__class__)
788 768 self.custom_exceptions = exc_tuple
789 769
790 770 def set_custom_completer(self,completer,pos=0):
791 771 """set_custom_completer(completer,pos=0)
792 772
793 773 Adds a new custom completer function.
794 774
795 775 The position argument (defaults to 0) is the index in the completers
796 776 list where you want the completer to be inserted."""
797 777
798 778 newcomp = new.instancemethod(completer,self.Completer,
799 779 self.Completer.__class__)
800 780 self.Completer.matchers.insert(pos,newcomp)
801 781
802 782 def _get_call_pdb(self):
803 783 return self._call_pdb
804 784
805 785 def _set_call_pdb(self,val):
806 786
807 787 if val not in (0,1,False,True):
808 788 raise ValueError,'new call_pdb value must be boolean'
809 789
810 790 # store value in instance
811 791 self._call_pdb = val
812 792
813 793 # notify the actual exception handlers
814 794 self.InteractiveTB.call_pdb = val
815 795 if self.isthreaded:
816 796 try:
817 797 self.sys_excepthook.call_pdb = val
818 798 except:
819 799 warn('Failed to activate pdb for threaded exception handler')
820 800
821 801 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
822 802 'Control auto-activation of pdb at exceptions')
823 803
824 804
825 805 # These special functions get installed in the builtin namespace, to
826 806 # provide programmatic (pure python) access to magics, aliases and system
827 807 # calls. This is important for logging, user scripting, and more.
828 808
829 809 # We are basically exposing, via normal python functions, the three
830 810 # mechanisms in which ipython offers special call modes (magics for
831 811 # internal control, aliases for direct system access via pre-selected
832 812 # names, and !cmd for calling arbitrary system commands).
833 813
834 814 def ipmagic(self,arg_s):
835 815 """Call a magic function by name.
836 816
837 817 Input: a string containing the name of the magic function to call and any
838 818 additional arguments to be passed to the magic.
839 819
840 820 ipmagic('name -opt foo bar') is equivalent to typing at the ipython
841 821 prompt:
842 822
843 823 In[1]: %name -opt foo bar
844 824
845 825 To call a magic without arguments, simply use ipmagic('name').
846 826
847 827 This provides a proper Python function to call IPython's magics in any
848 828 valid Python code you can type at the interpreter, including loops and
849 829 compound statements. It is added by IPython to the Python builtin
850 830 namespace upon initialization."""
851 831
852 832 args = arg_s.split(' ',1)
853 833 magic_name = args[0]
854 834 magic_name = magic_name.lstrip(self.ESC_MAGIC)
855 835
856 836 try:
857 837 magic_args = args[1]
858 838 except IndexError:
859 839 magic_args = ''
860 840 fn = getattr(self,'magic_'+magic_name,None)
861 841 if fn is None:
862 842 error("Magic function `%s` not found." % magic_name)
863 843 else:
864 844 magic_args = self.var_expand(magic_args)
865 845 return fn(magic_args)
866 846
867 847 def ipalias(self,arg_s):
868 848 """Call an alias by name.
869 849
870 850 Input: a string containing the name of the alias to call and any
871 851 additional arguments to be passed to the magic.
872 852
873 853 ipalias('name -opt foo bar') is equivalent to typing at the ipython
874 854 prompt:
875 855
876 856 In[1]: name -opt foo bar
877 857
878 858 To call an alias without arguments, simply use ipalias('name').
879 859
880 860 This provides a proper Python function to call IPython's aliases in any
881 861 valid Python code you can type at the interpreter, including loops and
882 862 compound statements. It is added by IPython to the Python builtin
883 863 namespace upon initialization."""
884 864
885 865 args = arg_s.split(' ',1)
886 866 alias_name = args[0]
887 867 try:
888 868 alias_args = args[1]
889 869 except IndexError:
890 870 alias_args = ''
891 871 if alias_name in self.alias_table:
892 872 self.call_alias(alias_name,alias_args)
893 873 else:
894 874 error("Alias `%s` not found." % alias_name)
895 875
896 876 def ipsystem(self,arg_s):
897 877 """Make a system call, using IPython."""
898 878
899 879 self.system(arg_s)
900 880
901 881 def complete(self,text):
902 882 """Return a sorted list of all possible completions on text.
903 883
904 884 Inputs:
905 885
906 886 - text: a string of text to be completed on.
907 887
908 888 This is a wrapper around the completion mechanism, similar to what
909 889 readline does at the command line when the TAB key is hit. By
910 890 exposing it as a method, it can be used by other non-readline
911 891 environments (such as GUIs) for text completion.
912 892
913 893 Simple usage example:
914 894
915 895 In [1]: x = 'hello'
916 896
917 897 In [2]: __IP.complete('x.l')
918 898 Out[2]: ['x.ljust', 'x.lower', 'x.lstrip']"""
919 899
920 900 complete = self.Completer.complete
921 901 state = 0
922 902 # use a dict so we get unique keys, since ipyhton's multiple
923 903 # completers can return duplicates.
924 904 comps = {}
925 905 while True:
926 906 newcomp = complete(text,state)
927 907 if newcomp is None:
928 908 break
929 909 comps[newcomp] = 1
930 910 state += 1
931 911 outcomps = comps.keys()
932 912 outcomps.sort()
933 913 return outcomps
934 914
935 915 def set_completer_frame(self, frame=None):
936 916 if frame:
937 917 self.Completer.namespace = frame.f_locals
938 918 self.Completer.global_namespace = frame.f_globals
939 919 else:
940 920 self.Completer.namespace = self.user_ns
941 921 self.Completer.global_namespace = self.user_global_ns
942 922
943 923 def init_auto_alias(self):
944 924 """Define some aliases automatically.
945 925
946 926 These are ALL parameter-less aliases"""
947 927
948 928 for alias,cmd in self.auto_alias:
949 929 self.alias_table[alias] = (0,cmd)
950 930
951 931 def alias_table_validate(self,verbose=0):
952 932 """Update information about the alias table.
953 933
954 934 In particular, make sure no Python keywords/builtins are in it."""
955 935
956 936 no_alias = self.no_alias
957 937 for k in self.alias_table.keys():
958 938 if k in no_alias:
959 939 del self.alias_table[k]
960 940 if verbose:
961 941 print ("Deleting alias <%s>, it's a Python "
962 942 "keyword or builtin." % k)
963 943
964 944 def set_autoindent(self,value=None):
965 945 """Set the autoindent flag, checking for readline support.
966 946
967 947 If called with no arguments, it acts as a toggle."""
968 948
969 949 if not self.has_readline:
970 950 if os.name == 'posix':
971 951 warn("The auto-indent feature requires the readline library")
972 952 self.autoindent = 0
973 953 return
974 954 if value is None:
975 955 self.autoindent = not self.autoindent
976 956 else:
977 957 self.autoindent = value
978 958
979 959 def rc_set_toggle(self,rc_field,value=None):
980 960 """Set or toggle a field in IPython's rc config. structure.
981 961
982 962 If called with no arguments, it acts as a toggle.
983 963
984 964 If called with a non-existent field, the resulting AttributeError
985 965 exception will propagate out."""
986 966
987 967 rc_val = getattr(self.rc,rc_field)
988 968 if value is None:
989 969 value = not rc_val
990 970 setattr(self.rc,rc_field,value)
991 971
992 972 def user_setup(self,ipythondir,rc_suffix,mode='install'):
993 973 """Install the user configuration directory.
994 974
995 975 Can be called when running for the first time or to upgrade the user's
996 976 .ipython/ directory with the mode parameter. Valid modes are 'install'
997 977 and 'upgrade'."""
998 978
999 979 def wait():
1000 980 try:
1001 981 raw_input("Please press <RETURN> to start IPython.")
1002 982 except EOFError:
1003 983 print >> Term.cout
1004 984 print '*'*70
1005 985
1006 986 cwd = os.getcwd() # remember where we started
1007 987 glb = glob.glob
1008 988 print '*'*70
1009 989 if mode == 'install':
1010 990 print \
1011 991 """Welcome to IPython. I will try to create a personal configuration directory
1012 992 where you can customize many aspects of IPython's functionality in:\n"""
1013 993 else:
1014 994 print 'I am going to upgrade your configuration in:'
1015 995
1016 996 print ipythondir
1017 997
1018 998 rcdirend = os.path.join('IPython','UserConfig')
1019 999 cfg = lambda d: os.path.join(d,rcdirend)
1020 1000 try:
1021 1001 rcdir = filter(os.path.isdir,map(cfg,sys.path))[0]
1022 1002 except IOError:
1023 1003 warning = """
1024 1004 Installation error. IPython's directory was not found.
1025 1005
1026 1006 Check the following:
1027 1007
1028 1008 The ipython/IPython directory should be in a directory belonging to your
1029 1009 PYTHONPATH environment variable (that is, it should be in a directory
1030 1010 belonging to sys.path). You can copy it explicitly there or just link to it.
1031 1011
1032 1012 IPython will proceed with builtin defaults.
1033 1013 """
1034 1014 warn(warning)
1035 1015 wait()
1036 1016 return
1037 1017
1038 1018 if mode == 'install':
1039 1019 try:
1040 1020 shutil.copytree(rcdir,ipythondir)
1041 1021 os.chdir(ipythondir)
1042 1022 rc_files = glb("ipythonrc*")
1043 1023 for rc_file in rc_files:
1044 1024 os.rename(rc_file,rc_file+rc_suffix)
1045 1025 except:
1046 1026 warning = """
1047 1027
1048 1028 There was a problem with the installation:
1049 1029 %s
1050 1030 Try to correct it or contact the developers if you think it's a bug.
1051 1031 IPython will proceed with builtin defaults.""" % sys.exc_info()[1]
1052 1032 warn(warning)
1053 1033 wait()
1054 1034 return
1055 1035
1056 1036 elif mode == 'upgrade':
1057 1037 try:
1058 1038 os.chdir(ipythondir)
1059 1039 except:
1060 1040 print """
1061 1041 Can not upgrade: changing to directory %s failed. Details:
1062 1042 %s
1063 1043 """ % (ipythondir,sys.exc_info()[1])
1064 1044 wait()
1065 1045 return
1066 1046 else:
1067 1047 sources = glb(os.path.join(rcdir,'[A-Za-z]*'))
1068 1048 for new_full_path in sources:
1069 1049 new_filename = os.path.basename(new_full_path)
1070 1050 if new_filename.startswith('ipythonrc'):
1071 1051 new_filename = new_filename + rc_suffix
1072 1052 # The config directory should only contain files, skip any
1073 1053 # directories which may be there (like CVS)
1074 1054 if os.path.isdir(new_full_path):
1075 1055 continue
1076 1056 if os.path.exists(new_filename):
1077 1057 old_file = new_filename+'.old'
1078 1058 if os.path.exists(old_file):
1079 1059 os.remove(old_file)
1080 1060 os.rename(new_filename,old_file)
1081 1061 shutil.copy(new_full_path,new_filename)
1082 1062 else:
1083 1063 raise ValueError,'unrecognized mode for install:',`mode`
1084 1064
1085 1065 # Fix line-endings to those native to each platform in the config
1086 1066 # directory.
1087 1067 try:
1088 1068 os.chdir(ipythondir)
1089 1069 except:
1090 1070 print """
1091 1071 Problem: changing to directory %s failed.
1092 1072 Details:
1093 1073 %s
1094 1074
1095 1075 Some configuration files may have incorrect line endings. This should not
1096 1076 cause any problems during execution. """ % (ipythondir,sys.exc_info()[1])
1097 1077 wait()
1098 1078 else:
1099 1079 for fname in glb('ipythonrc*'):
1100 1080 try:
1101 1081 native_line_ends(fname,backup=0)
1102 1082 except IOError:
1103 1083 pass
1104 1084
1105 1085 if mode == 'install':
1106 1086 print """
1107 1087 Successful installation!
1108 1088
1109 1089 Please read the sections 'Initial Configuration' and 'Quick Tips' in the
1110 1090 IPython manual (there are both HTML and PDF versions supplied with the
1111 1091 distribution) to make sure that your system environment is properly configured
1112 1092 to take advantage of IPython's features.
1113 1093
1114 1094 Important note: the configuration system has changed! The old system is
1115 1095 still in place, but its setting may be partly overridden by the settings in
1116 1096 "~/.ipython/ipy_user_conf.py" config file. Please take a look at the file
1117 1097 if some of the new settings bother you.
1118 1098
1119 1099 """
1120 1100 else:
1121 1101 print """
1122 1102 Successful upgrade!
1123 1103
1124 1104 All files in your directory:
1125 1105 %(ipythondir)s
1126 1106 which would have been overwritten by the upgrade were backed up with a .old
1127 1107 extension. If you had made particular customizations in those files you may
1128 1108 want to merge them back into the new files.""" % locals()
1129 1109 wait()
1130 1110 os.chdir(cwd)
1131 1111 # end user_setup()
1132 1112
1133 1113 def atexit_operations(self):
1134 1114 """This will be executed at the time of exit.
1135 1115
1136 1116 Saving of persistent data should be performed here. """
1137 1117
1138 1118 #print '*** IPython exit cleanup ***' # dbg
1139 1119 # input history
1140 1120 self.savehist()
1141 1121
1142 1122 # Cleanup all tempfiles left around
1143 1123 for tfile in self.tempfiles:
1144 1124 try:
1145 1125 os.unlink(tfile)
1146 1126 except OSError:
1147 1127 pass
1148 1128
1149 1129 # save the "persistent data" catch-all dictionary
1150 try:
1151 pickle.dump(self.persist, open(self.persist_fname,"w"))
1152 except:
1153 print "*** ERROR *** persistent data saving failed."
1130 self.hooks.shutdown_hook()
1154 1131
1155 1132 def savehist(self):
1156 1133 """Save input history to a file (via readline library)."""
1157 1134 try:
1158 1135 self.readline.write_history_file(self.histfile)
1159 1136 except:
1160 1137 print 'Unable to save IPython command history to file: ' + \
1161 1138 `self.histfile`
1162 1139
1163 1140 def pre_readline(self):
1164 1141 """readline hook to be used at the start of each line.
1165 1142
1166 1143 Currently it handles auto-indent only."""
1167 1144
1168 1145 #debugx('self.indent_current_nsp','pre_readline:')
1169 1146 self.readline.insert_text(self.indent_current_str())
1170 1147
1171 1148 def init_readline(self):
1172 1149 """Command history completion/saving/reloading."""
1173 1150
1174 1151 import IPython.rlineimpl as readline
1175 1152 if not readline.have_readline:
1176 1153 self.has_readline = 0
1177 1154 self.readline = None
1178 1155 # no point in bugging windows users with this every time:
1179 1156 warn('Readline services not available on this platform.')
1180 1157 else:
1181 1158 sys.modules['readline'] = readline
1182 1159 import atexit
1183 1160 from IPython.completer import IPCompleter
1184 1161 self.Completer = IPCompleter(self,
1185 1162 self.user_ns,
1186 1163 self.user_global_ns,
1187 1164 self.rc.readline_omit__names,
1188 1165 self.alias_table)
1189 1166
1190 1167 # Platform-specific configuration
1191 1168 if os.name == 'nt':
1192 1169 self.readline_startup_hook = readline.set_pre_input_hook
1193 1170 else:
1194 1171 self.readline_startup_hook = readline.set_startup_hook
1195 1172
1196 1173 # Load user's initrc file (readline config)
1197 1174 inputrc_name = os.environ.get('INPUTRC')
1198 1175 if inputrc_name is None:
1199 1176 home_dir = get_home_dir()
1200 1177 if home_dir is not None:
1201 1178 inputrc_name = os.path.join(home_dir,'.inputrc')
1202 1179 if os.path.isfile(inputrc_name):
1203 1180 try:
1204 1181 readline.read_init_file(inputrc_name)
1205 1182 except:
1206 1183 warn('Problems reading readline initialization file <%s>'
1207 1184 % inputrc_name)
1208 1185
1209 1186 self.has_readline = 1
1210 1187 self.readline = readline
1211 1188 # save this in sys so embedded copies can restore it properly
1212 1189 sys.ipcompleter = self.Completer.complete
1213 1190 readline.set_completer(self.Completer.complete)
1214 1191
1215 1192 # Configure readline according to user's prefs
1216 1193 for rlcommand in self.rc.readline_parse_and_bind:
1217 1194 readline.parse_and_bind(rlcommand)
1218 1195
1219 1196 # remove some chars from the delimiters list
1220 1197 delims = readline.get_completer_delims()
1221 1198 delims = delims.translate(string._idmap,
1222 1199 self.rc.readline_remove_delims)
1223 1200 readline.set_completer_delims(delims)
1224 1201 # otherwise we end up with a monster history after a while:
1225 1202 readline.set_history_length(1000)
1226 1203 try:
1227 1204 #print '*** Reading readline history' # dbg
1228 1205 readline.read_history_file(self.histfile)
1229 1206 except IOError:
1230 1207 pass # It doesn't exist yet.
1231 1208
1232 1209 atexit.register(self.atexit_operations)
1233 1210 del atexit
1234 1211
1235 1212 # Configure auto-indent for all platforms
1236 1213 self.set_autoindent(self.rc.autoindent)
1237 1214
1238 1215 def _should_recompile(self,e):
1239 1216 """Utility routine for edit_syntax_error"""
1240 1217
1241 1218 if e.filename in ('<ipython console>','<input>','<string>',
1242 1219 '<console>',None):
1243 1220
1244 1221 return False
1245 1222 try:
1246 1223 if (self.rc.autoedit_syntax != 2 and
1247 1224 not ask_yes_no('Return to editor to correct syntax error? '
1248 1225 '[Y/n] ','y')):
1249 1226 return False
1250 1227 except EOFError:
1251 1228 return False
1252 1229
1253 1230 def int0(x):
1254 1231 try:
1255 1232 return int(x)
1256 1233 except TypeError:
1257 1234 return 0
1258 1235 # always pass integer line and offset values to editor hook
1259 1236 self.hooks.fix_error_editor(e.filename,
1260 1237 int0(e.lineno),int0(e.offset),e.msg)
1261 1238 return True
1262 1239
1263 1240 def edit_syntax_error(self):
1264 1241 """The bottom half of the syntax error handler called in the main loop.
1265 1242
1266 1243 Loop until syntax error is fixed or user cancels.
1267 1244 """
1268 1245
1269 1246 while self.SyntaxTB.last_syntax_error:
1270 1247 # copy and clear last_syntax_error
1271 1248 err = self.SyntaxTB.clear_err_state()
1272 1249 if not self._should_recompile(err):
1273 1250 return
1274 1251 try:
1275 1252 # may set last_syntax_error again if a SyntaxError is raised
1276 1253 self.safe_execfile(err.filename,self.shell.user_ns)
1277 1254 except:
1278 1255 self.showtraceback()
1279 1256 else:
1280 1257 f = file(err.filename)
1281 1258 try:
1282 1259 sys.displayhook(f.read())
1283 1260 finally:
1284 1261 f.close()
1285 1262
1286 1263 def showsyntaxerror(self, filename=None):
1287 1264 """Display the syntax error that just occurred.
1288 1265
1289 1266 This doesn't display a stack trace because there isn't one.
1290 1267
1291 1268 If a filename is given, it is stuffed in the exception instead
1292 1269 of what was there before (because Python's parser always uses
1293 1270 "<string>" when reading from a string).
1294 1271 """
1295 1272 etype, value, last_traceback = sys.exc_info()
1296 1273 if filename and etype is SyntaxError:
1297 1274 # Work hard to stuff the correct filename in the exception
1298 1275 try:
1299 1276 msg, (dummy_filename, lineno, offset, line) = value
1300 1277 except:
1301 1278 # Not the format we expect; leave it alone
1302 1279 pass
1303 1280 else:
1304 1281 # Stuff in the right filename
1305 1282 try:
1306 1283 # Assume SyntaxError is a class exception
1307 1284 value = SyntaxError(msg, (filename, lineno, offset, line))
1308 1285 except:
1309 1286 # If that failed, assume SyntaxError is a string
1310 1287 value = msg, (filename, lineno, offset, line)
1311 1288 self.SyntaxTB(etype,value,[])
1312 1289
1313 1290 def debugger(self):
1314 1291 """Call the pdb debugger."""
1315 1292
1316 1293 if not self.rc.pdb:
1317 1294 return
1318 1295 pdb.pm()
1319 1296
1320 1297 def showtraceback(self,exc_tuple = None,filename=None):
1321 1298 """Display the exception that just occurred."""
1322 1299
1323 1300 # Though this won't be called by syntax errors in the input line,
1324 1301 # there may be SyntaxError cases whith imported code.
1325 1302 if exc_tuple is None:
1326 1303 type, value, tb = sys.exc_info()
1327 1304 else:
1328 1305 type, value, tb = exc_tuple
1329 1306 if type is SyntaxError:
1330 1307 self.showsyntaxerror(filename)
1331 1308 else:
1332 1309 self.InteractiveTB()
1333 1310 if self.InteractiveTB.call_pdb and self.has_readline:
1334 1311 # pdb mucks up readline, fix it back
1335 1312 self.readline.set_completer(self.Completer.complete)
1336 1313
1337 1314 def mainloop(self,banner=None):
1338 1315 """Creates the local namespace and starts the mainloop.
1339 1316
1340 1317 If an optional banner argument is given, it will override the
1341 1318 internally created default banner."""
1342 1319
1343 1320 if self.rc.c: # Emulate Python's -c option
1344 1321 self.exec_init_cmd()
1345 1322 if banner is None:
1346 1323 if self.rc.banner:
1347 1324 banner = self.BANNER+self.banner2
1348 1325 else:
1349 1326 banner = ''
1350 1327 self.interact(banner)
1351 1328
1352 1329 def exec_init_cmd(self):
1353 1330 """Execute a command given at the command line.
1354 1331
1355 1332 This emulates Python's -c option."""
1356 1333
1357 1334 #sys.argv = ['-c']
1358 1335 self.push(self.rc.c)
1359 1336
1360 1337 def embed_mainloop(self,header='',local_ns=None,global_ns=None,stack_depth=0):
1361 1338 """Embeds IPython into a running python program.
1362 1339
1363 1340 Input:
1364 1341
1365 1342 - header: An optional header message can be specified.
1366 1343
1367 1344 - local_ns, global_ns: working namespaces. If given as None, the
1368 1345 IPython-initialized one is updated with __main__.__dict__, so that
1369 1346 program variables become visible but user-specific configuration
1370 1347 remains possible.
1371 1348
1372 1349 - stack_depth: specifies how many levels in the stack to go to
1373 1350 looking for namespaces (when local_ns and global_ns are None). This
1374 1351 allows an intermediate caller to make sure that this function gets
1375 1352 the namespace from the intended level in the stack. By default (0)
1376 1353 it will get its locals and globals from the immediate caller.
1377 1354
1378 1355 Warning: it's possible to use this in a program which is being run by
1379 1356 IPython itself (via %run), but some funny things will happen (a few
1380 1357 globals get overwritten). In the future this will be cleaned up, as
1381 1358 there is no fundamental reason why it can't work perfectly."""
1382 1359
1383 1360 # Get locals and globals from caller
1384 1361 if local_ns is None or global_ns is None:
1385 1362 call_frame = sys._getframe(stack_depth).f_back
1386 1363
1387 1364 if local_ns is None:
1388 1365 local_ns = call_frame.f_locals
1389 1366 if global_ns is None:
1390 1367 global_ns = call_frame.f_globals
1391 1368
1392 1369 # Update namespaces and fire up interpreter
1393 1370
1394 1371 # The global one is easy, we can just throw it in
1395 1372 self.user_global_ns = global_ns
1396 1373
1397 1374 # but the user/local one is tricky: ipython needs it to store internal
1398 1375 # data, but we also need the locals. We'll copy locals in the user
1399 1376 # one, but will track what got copied so we can delete them at exit.
1400 1377 # This is so that a later embedded call doesn't see locals from a
1401 1378 # previous call (which most likely existed in a separate scope).
1402 1379 local_varnames = local_ns.keys()
1403 1380 self.user_ns.update(local_ns)
1404 1381
1405 1382 # Patch for global embedding to make sure that things don't overwrite
1406 1383 # user globals accidentally. Thanks to Richard <rxe@renre-europe.com>
1407 1384 # FIXME. Test this a bit more carefully (the if.. is new)
1408 1385 if local_ns is None and global_ns is None:
1409 1386 self.user_global_ns.update(__main__.__dict__)
1410 1387
1411 1388 # make sure the tab-completer has the correct frame information, so it
1412 1389 # actually completes using the frame's locals/globals
1413 1390 self.set_completer_frame()
1414 1391
1415 1392 # before activating the interactive mode, we need to make sure that
1416 1393 # all names in the builtin namespace needed by ipython point to
1417 1394 # ourselves, and not to other instances.
1418 1395 self.add_builtins()
1419 1396
1420 1397 self.interact(header)
1421 1398
1422 1399 # now, purge out the user namespace from anything we might have added
1423 1400 # from the caller's local namespace
1424 1401 delvar = self.user_ns.pop
1425 1402 for var in local_varnames:
1426 1403 delvar(var,None)
1427 1404 # and clean builtins we may have overridden
1428 1405 self.clean_builtins()
1429 1406
1430 1407 def interact(self, banner=None):
1431 1408 """Closely emulate the interactive Python console.
1432 1409
1433 1410 The optional banner argument specify the banner to print
1434 1411 before the first interaction; by default it prints a banner
1435 1412 similar to the one printed by the real Python interpreter,
1436 1413 followed by the current class name in parentheses (so as not
1437 1414 to confuse this with the real interpreter -- since it's so
1438 1415 close!).
1439 1416
1440 1417 """
1441 1418 cprt = 'Type "copyright", "credits" or "license" for more information.'
1442 1419 if banner is None:
1443 1420 self.write("Python %s on %s\n%s\n(%s)\n" %
1444 1421 (sys.version, sys.platform, cprt,
1445 1422 self.__class__.__name__))
1446 1423 else:
1447 1424 self.write(banner)
1448 1425
1449 1426 more = 0
1450 1427
1451 1428 # Mark activity in the builtins
1452 1429 __builtin__.__dict__['__IPYTHON__active'] += 1
1453 1430
1454 1431 # exit_now is set by a call to %Exit or %Quit
1455 1432 self.exit_now = False
1456 1433 while not self.exit_now:
1457 1434 if more:
1458 1435 prompt = self.outputcache.prompt2
1459 1436 if self.autoindent:
1460 1437 self.readline_startup_hook(self.pre_readline)
1461 1438 else:
1462 1439 prompt = self.outputcache.prompt1
1463 1440 try:
1464 1441 line = self.raw_input(prompt,more)
1465 1442 if self.autoindent:
1466 1443 self.readline_startup_hook(None)
1467 1444 except KeyboardInterrupt:
1468 1445 self.write('\nKeyboardInterrupt\n')
1469 1446 self.resetbuffer()
1470 1447 # keep cache in sync with the prompt counter:
1471 1448 self.outputcache.prompt_count -= 1
1472 1449
1473 1450 if self.autoindent:
1474 1451 self.indent_current_nsp = 0
1475 1452 more = 0
1476 1453 except EOFError:
1477 1454 if self.autoindent:
1478 1455 self.readline_startup_hook(None)
1479 1456 self.write('\n')
1480 1457 self.exit()
1481 1458 except bdb.BdbQuit:
1482 1459 warn('The Python debugger has exited with a BdbQuit exception.\n'
1483 1460 'Because of how pdb handles the stack, it is impossible\n'
1484 1461 'for IPython to properly format this particular exception.\n'
1485 1462 'IPython will resume normal operation.')
1486 1463 except:
1487 1464 # exceptions here are VERY RARE, but they can be triggered
1488 1465 # asynchronously by signal handlers, for example.
1489 1466 self.showtraceback()
1490 1467 else:
1491 1468 more = self.push(line)
1492 1469 if (self.SyntaxTB.last_syntax_error and
1493 1470 self.rc.autoedit_syntax):
1494 1471 self.edit_syntax_error()
1495 1472
1496 1473 # We are off again...
1497 1474 __builtin__.__dict__['__IPYTHON__active'] -= 1
1498 1475
1499 1476 def excepthook(self, type, value, tb):
1500 1477 """One more defense for GUI apps that call sys.excepthook.
1501 1478
1502 1479 GUI frameworks like wxPython trap exceptions and call
1503 1480 sys.excepthook themselves. I guess this is a feature that
1504 1481 enables them to keep running after exceptions that would
1505 1482 otherwise kill their mainloop. This is a bother for IPython
1506 1483 which excepts to catch all of the program exceptions with a try:
1507 1484 except: statement.
1508 1485
1509 1486 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1510 1487 any app directly invokes sys.excepthook, it will look to the user like
1511 1488 IPython crashed. In order to work around this, we can disable the
1512 1489 CrashHandler and replace it with this excepthook instead, which prints a
1513 1490 regular traceback using our InteractiveTB. In this fashion, apps which
1514 1491 call sys.excepthook will generate a regular-looking exception from
1515 1492 IPython, and the CrashHandler will only be triggered by real IPython
1516 1493 crashes.
1517 1494
1518 1495 This hook should be used sparingly, only in places which are not likely
1519 1496 to be true IPython errors.
1520 1497 """
1521 1498
1522 1499 self.InteractiveTB(type, value, tb, tb_offset=0)
1523 1500 if self.InteractiveTB.call_pdb and self.has_readline:
1524 1501 self.readline.set_completer(self.Completer.complete)
1525 1502
1526 1503 def call_alias(self,alias,rest=''):
1527 1504 """Call an alias given its name and the rest of the line.
1528 1505
1529 1506 This function MUST be given a proper alias, because it doesn't make
1530 1507 any checks when looking up into the alias table. The caller is
1531 1508 responsible for invoking it only with a valid alias."""
1532 1509
1533 1510 #print 'ALIAS: <%s>+<%s>' % (alias,rest) # dbg
1534 1511 nargs,cmd = self.alias_table[alias]
1535 1512 # Expand the %l special to be the user's input line
1536 1513 if cmd.find('%l') >= 0:
1537 1514 cmd = cmd.replace('%l',rest)
1538 1515 rest = ''
1539 1516 if nargs==0:
1540 1517 # Simple, argument-less aliases
1541 1518 cmd = '%s %s' % (cmd,rest)
1542 1519 else:
1543 1520 # Handle aliases with positional arguments
1544 1521 args = rest.split(None,nargs)
1545 1522 if len(args)< nargs:
1546 1523 error('Alias <%s> requires %s arguments, %s given.' %
1547 1524 (alias,nargs,len(args)))
1548 1525 return
1549 1526 cmd = '%s %s' % (cmd % tuple(args[:nargs]),' '.join(args[nargs:]))
1550 1527 # Now call the macro, evaluating in the user's namespace
1551 1528 try:
1552 1529 self.system(cmd)
1553 1530 except:
1554 1531 self.showtraceback()
1555 1532
1556 1533 def indent_current_str(self):
1557 1534 """return the current level of indentation as a string"""
1558 1535 return self.indent_current_nsp * ' '
1559 1536
1560 1537 def autoindent_update(self,line):
1561 1538 """Keep track of the indent level."""
1562 1539
1563 1540 #debugx('line')
1564 1541 #debugx('self.indent_current_nsp')
1565 1542 if self.autoindent:
1566 1543 if line:
1567 1544 inisp = num_ini_spaces(line)
1568 1545 if inisp < self.indent_current_nsp:
1569 1546 self.indent_current_nsp = inisp
1570 1547
1571 1548 if line[-1] == ':':
1572 1549 self.indent_current_nsp += 4
1573 1550 elif dedent_re.match(line):
1574 1551 self.indent_current_nsp -= 4
1575 1552 else:
1576 1553 self.indent_current_nsp = 0
1577 1554
1578 1555 def runlines(self,lines):
1579 1556 """Run a string of one or more lines of source.
1580 1557
1581 1558 This method is capable of running a string containing multiple source
1582 1559 lines, as if they had been entered at the IPython prompt. Since it
1583 1560 exposes IPython's processing machinery, the given strings can contain
1584 1561 magic calls (%magic), special shell access (!cmd), etc."""
1585 1562
1586 1563 # We must start with a clean buffer, in case this is run from an
1587 1564 # interactive IPython session (via a magic, for example).
1588 1565 self.resetbuffer()
1589 1566 lines = lines.split('\n')
1590 1567 more = 0
1591 1568 for line in lines:
1592 1569 # skip blank lines so we don't mess up the prompt counter, but do
1593 1570 # NOT skip even a blank line if we are in a code block (more is
1594 1571 # true)
1595 1572 if line or more:
1596 1573 more = self.push(self.prefilter(line,more))
1597 1574 # IPython's runsource returns None if there was an error
1598 1575 # compiling the code. This allows us to stop processing right
1599 1576 # away, so the user gets the error message at the right place.
1600 1577 if more is None:
1601 1578 break
1602 1579 # final newline in case the input didn't have it, so that the code
1603 1580 # actually does get executed
1604 1581 if more:
1605 1582 self.push('\n')
1606 1583
1607 1584 def runsource(self, source, filename='<input>', symbol='single'):
1608 1585 """Compile and run some source in the interpreter.
1609 1586
1610 1587 Arguments are as for compile_command().
1611 1588
1612 1589 One several things can happen:
1613 1590
1614 1591 1) The input is incorrect; compile_command() raised an
1615 1592 exception (SyntaxError or OverflowError). A syntax traceback
1616 1593 will be printed by calling the showsyntaxerror() method.
1617 1594
1618 1595 2) The input is incomplete, and more input is required;
1619 1596 compile_command() returned None. Nothing happens.
1620 1597
1621 1598 3) The input is complete; compile_command() returned a code
1622 1599 object. The code is executed by calling self.runcode() (which
1623 1600 also handles run-time exceptions, except for SystemExit).
1624 1601
1625 1602 The return value is:
1626 1603
1627 1604 - True in case 2
1628 1605
1629 1606 - False in the other cases, unless an exception is raised, where
1630 1607 None is returned instead. This can be used by external callers to
1631 1608 know whether to continue feeding input or not.
1632 1609
1633 1610 The return value can be used to decide whether to use sys.ps1 or
1634 1611 sys.ps2 to prompt the next line."""
1635 1612
1636 1613 try:
1637 1614 code = self.compile(source,filename,symbol)
1638 1615 except (OverflowError, SyntaxError, ValueError):
1639 1616 # Case 1
1640 1617 self.showsyntaxerror(filename)
1641 1618 return None
1642 1619
1643 1620 if code is None:
1644 1621 # Case 2
1645 1622 return True
1646 1623
1647 1624 # Case 3
1648 1625 # We store the code object so that threaded shells and
1649 1626 # custom exception handlers can access all this info if needed.
1650 1627 # The source corresponding to this can be obtained from the
1651 1628 # buffer attribute as '\n'.join(self.buffer).
1652 1629 self.code_to_run = code
1653 1630 # now actually execute the code object
1654 1631 if self.runcode(code) == 0:
1655 1632 return False
1656 1633 else:
1657 1634 return None
1658 1635
1659 1636 def runcode(self,code_obj):
1660 1637 """Execute a code object.
1661 1638
1662 1639 When an exception occurs, self.showtraceback() is called to display a
1663 1640 traceback.
1664 1641
1665 1642 Return value: a flag indicating whether the code to be run completed
1666 1643 successfully:
1667 1644
1668 1645 - 0: successful execution.
1669 1646 - 1: an error occurred.
1670 1647 """
1671 1648
1672 1649 # Set our own excepthook in case the user code tries to call it
1673 1650 # directly, so that the IPython crash handler doesn't get triggered
1674 1651 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
1675 1652
1676 1653 # we save the original sys.excepthook in the instance, in case config
1677 1654 # code (such as magics) needs access to it.
1678 1655 self.sys_excepthook = old_excepthook
1679 1656 outflag = 1 # happens in more places, so it's easier as default
1680 1657 try:
1681 1658 try:
1682 1659 # Embedded instances require separate global/local namespaces
1683 1660 # so they can see both the surrounding (local) namespace and
1684 1661 # the module-level globals when called inside another function.
1685 1662 if self.embedded:
1686 1663 exec code_obj in self.user_global_ns, self.user_ns
1687 1664 # Normal (non-embedded) instances should only have a single
1688 1665 # namespace for user code execution, otherwise functions won't
1689 1666 # see interactive top-level globals.
1690 1667 else:
1691 1668 exec code_obj in self.user_ns
1692 1669 finally:
1693 1670 # Reset our crash handler in place
1694 1671 sys.excepthook = old_excepthook
1695 1672 except SystemExit:
1696 1673 self.resetbuffer()
1697 1674 self.showtraceback()
1698 1675 warn("Type exit or quit to exit IPython "
1699 1676 "(%Exit or %Quit do so unconditionally).",level=1)
1700 1677 except self.custom_exceptions:
1701 1678 etype,value,tb = sys.exc_info()
1702 1679 self.CustomTB(etype,value,tb)
1703 1680 except:
1704 1681 self.showtraceback()
1705 1682 else:
1706 1683 outflag = 0
1707 1684 if softspace(sys.stdout, 0):
1708 1685 print
1709 1686 # Flush out code object which has been run (and source)
1710 1687 self.code_to_run = None
1711 1688 return outflag
1712 1689
1713 1690 def push(self, line):
1714 1691 """Push a line to the interpreter.
1715 1692
1716 1693 The line should not have a trailing newline; it may have
1717 1694 internal newlines. The line is appended to a buffer and the
1718 1695 interpreter's runsource() method is called with the
1719 1696 concatenated contents of the buffer as source. If this
1720 1697 indicates that the command was executed or invalid, the buffer
1721 1698 is reset; otherwise, the command is incomplete, and the buffer
1722 1699 is left as it was after the line was appended. The return
1723 1700 value is 1 if more input is required, 0 if the line was dealt
1724 1701 with in some way (this is the same as runsource()).
1725 1702 """
1726 1703
1727 1704 # autoindent management should be done here, and not in the
1728 1705 # interactive loop, since that one is only seen by keyboard input. We
1729 1706 # need this done correctly even for code run via runlines (which uses
1730 1707 # push).
1731 1708
1732 1709 #print 'push line: <%s>' % line # dbg
1733 1710 self.autoindent_update(line)
1734 1711
1735 1712 self.buffer.append(line)
1736 1713 more = self.runsource('\n'.join(self.buffer), self.filename)
1737 1714 if not more:
1738 1715 self.resetbuffer()
1739 1716 return more
1740 1717
1741 1718 def resetbuffer(self):
1742 1719 """Reset the input buffer."""
1743 1720 self.buffer[:] = []
1744 1721
1745 1722 def raw_input(self,prompt='',continue_prompt=False):
1746 1723 """Write a prompt and read a line.
1747 1724
1748 1725 The returned line does not include the trailing newline.
1749 1726 When the user enters the EOF key sequence, EOFError is raised.
1750 1727
1751 1728 Optional inputs:
1752 1729
1753 1730 - prompt(''): a string to be printed to prompt the user.
1754 1731
1755 1732 - continue_prompt(False): whether this line is the first one or a
1756 1733 continuation in a sequence of inputs.
1757 1734 """
1758 1735
1759 1736 line = raw_input_original(prompt)
1760 1737
1761 1738 # Try to be reasonably smart about not re-indenting pasted input more
1762 1739 # than necessary. We do this by trimming out the auto-indent initial
1763 1740 # spaces, if the user's actual input started itself with whitespace.
1764 1741 #debugx('self.buffer[-1]')
1765 1742
1766 1743 if self.autoindent:
1767 1744 if num_ini_spaces(line) > self.indent_current_nsp:
1768 1745 line = line[self.indent_current_nsp:]
1769 1746 self.indent_current_nsp = 0
1770 1747
1771 1748 # store the unfiltered input before the user has any chance to modify
1772 1749 # it.
1773 1750 if line.strip():
1774 1751 if continue_prompt:
1775 1752 self.input_hist_raw[-1] += '%s\n' % line
1776 1753 else:
1777 1754 self.input_hist_raw.append('%s\n' % line)
1778 1755
1779 1756 lineout = self.prefilter(line,continue_prompt)
1780 1757 return lineout
1781 1758
1782 1759 def split_user_input(self,line):
1783 1760 """Split user input into pre-char, function part and rest."""
1784 1761
1785 1762 lsplit = self.line_split.match(line)
1786 1763 if lsplit is None: # no regexp match returns None
1787 1764 try:
1788 1765 iFun,theRest = line.split(None,1)
1789 1766 except ValueError:
1790 1767 iFun,theRest = line,''
1791 1768 pre = re.match('^(\s*)(.*)',line).groups()[0]
1792 1769 else:
1793 1770 pre,iFun,theRest = lsplit.groups()
1794 1771
1795 1772 #print 'line:<%s>' % line # dbg
1796 1773 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun.strip(),theRest) # dbg
1797 1774 return pre,iFun.strip(),theRest
1798 1775
1799 1776 def _prefilter(self, line, continue_prompt):
1800 1777 """Calls different preprocessors, depending on the form of line."""
1801 1778
1802 1779 # All handlers *must* return a value, even if it's blank ('').
1803 1780
1804 1781 # Lines are NOT logged here. Handlers should process the line as
1805 1782 # needed, update the cache AND log it (so that the input cache array
1806 1783 # stays synced).
1807 1784
1808 1785 # This function is _very_ delicate, and since it's also the one which
1809 1786 # determines IPython's response to user input, it must be as efficient
1810 1787 # as possible. For this reason it has _many_ returns in it, trying
1811 1788 # always to exit as quickly as it can figure out what it needs to do.
1812 1789
1813 1790 # This function is the main responsible for maintaining IPython's
1814 1791 # behavior respectful of Python's semantics. So be _very_ careful if
1815 1792 # making changes to anything here.
1816 1793
1817 1794 #.....................................................................
1818 1795 # Code begins
1819 1796
1820 1797 #if line.startswith('%crash'): raise RuntimeError,'Crash now!' # dbg
1821 1798
1822 1799 # save the line away in case we crash, so the post-mortem handler can
1823 1800 # record it
1824 1801 self._last_input_line = line
1825 1802
1826 1803 #print '***line: <%s>' % line # dbg
1827 1804
1828 1805 # the input history needs to track even empty lines
1829 1806 stripped = line.strip()
1830 1807
1831 1808 if not stripped:
1832 1809 if not continue_prompt:
1833 1810 self.outputcache.prompt_count -= 1
1834 1811 return self.handle_normal(line,continue_prompt)
1835 1812 #return self.handle_normal('',continue_prompt)
1836 1813
1837 1814 # print '***cont',continue_prompt # dbg
1838 1815 # special handlers are only allowed for single line statements
1839 1816 if continue_prompt and not self.rc.multi_line_specials:
1840 1817 return self.handle_normal(line,continue_prompt)
1841 1818
1842 1819
1843 1820 # For the rest, we need the structure of the input
1844 1821 pre,iFun,theRest = self.split_user_input(line)
1845 1822
1846 1823 # See whether any pre-existing handler can take care of it
1847 1824
1848 1825 rewritten = self.hooks.input_prefilter(stripped)
1849 1826 if rewritten != stripped: # ok, some prefilter did something
1850 1827 rewritten = pre + rewritten # add indentation
1851 1828 return self.handle_normal(rewritten)
1852 1829
1853 1830
1854 1831
1855 1832
1856 1833 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1857 1834
1858 1835 # First check for explicit escapes in the last/first character
1859 1836 handler = None
1860 1837 if line[-1] == self.ESC_HELP:
1861 1838 handler = self.esc_handlers.get(line[-1]) # the ? can be at the end
1862 1839 if handler is None:
1863 1840 # look at the first character of iFun, NOT of line, so we skip
1864 1841 # leading whitespace in multiline input
1865 1842 handler = self.esc_handlers.get(iFun[0:1])
1866 1843 if handler is not None:
1867 1844 return handler(line,continue_prompt,pre,iFun,theRest)
1868 1845 # Emacs ipython-mode tags certain input lines
1869 1846 if line.endswith('# PYTHON-MODE'):
1870 1847 return self.handle_emacs(line,continue_prompt)
1871 1848
1872 1849 # Next, check if we can automatically execute this thing
1873 1850
1874 1851 # Allow ! in multi-line statements if multi_line_specials is on:
1875 1852 if continue_prompt and self.rc.multi_line_specials and \
1876 1853 iFun.startswith(self.ESC_SHELL):
1877 1854 return self.handle_shell_escape(line,continue_prompt,
1878 1855 pre=pre,iFun=iFun,
1879 1856 theRest=theRest)
1880 1857
1881 1858 # Let's try to find if the input line is a magic fn
1882 1859 oinfo = None
1883 1860 if hasattr(self,'magic_'+iFun):
1884 1861 # WARNING: _ofind uses getattr(), so it can consume generators and
1885 1862 # cause other side effects.
1886 1863 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1887 1864 if oinfo['ismagic']:
1888 1865 # Be careful not to call magics when a variable assignment is
1889 1866 # being made (ls='hi', for example)
1890 1867 if self.rc.automagic and \
1891 1868 (len(theRest)==0 or theRest[0] not in '!=()<>,') and \
1892 1869 (self.rc.multi_line_specials or not continue_prompt):
1893 1870 return self.handle_magic(line,continue_prompt,
1894 1871 pre,iFun,theRest)
1895 1872 else:
1896 1873 return self.handle_normal(line,continue_prompt)
1897 1874
1898 1875 # If the rest of the line begins with an (in)equality, assginment or
1899 1876 # function call, we should not call _ofind but simply execute it.
1900 1877 # This avoids spurious geattr() accesses on objects upon assignment.
1901 1878 #
1902 1879 # It also allows users to assign to either alias or magic names true
1903 1880 # python variables (the magic/alias systems always take second seat to
1904 1881 # true python code).
1905 1882 if theRest and theRest[0] in '!=()':
1906 1883 return self.handle_normal(line,continue_prompt)
1907 1884
1908 1885 if oinfo is None:
1909 1886 # let's try to ensure that _oinfo is ONLY called when autocall is
1910 1887 # on. Since it has inevitable potential side effects, at least
1911 1888 # having autocall off should be a guarantee to the user that no
1912 1889 # weird things will happen.
1913 1890
1914 1891 if self.rc.autocall:
1915 1892 oinfo = self._ofind(iFun) # FIXME - _ofind is part of Magic
1916 1893 else:
1917 1894 # in this case, all that's left is either an alias or
1918 1895 # processing the line normally.
1919 1896 if iFun in self.alias_table:
1920 1897 return self.handle_alias(line,continue_prompt,
1921 1898 pre,iFun,theRest)
1922 1899
1923 1900 else:
1924 1901 return self.handle_normal(line,continue_prompt)
1925 1902
1926 1903 if not oinfo['found']:
1927 1904 return self.handle_normal(line,continue_prompt)
1928 1905 else:
1929 1906 #print 'pre<%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
1930 1907 if oinfo['isalias']:
1931 1908 return self.handle_alias(line,continue_prompt,
1932 1909 pre,iFun,theRest)
1933 1910
1934 1911 if (self.rc.autocall
1935 1912 and
1936 1913 (
1937 1914 #only consider exclusion re if not "," or ";" autoquoting
1938 1915 (pre == self.ESC_QUOTE or pre == self.ESC_QUOTE2
1939 1916 or pre == self.ESC_PAREN) or
1940 1917 (not self.re_exclude_auto.match(theRest)))
1941 1918 and
1942 1919 self.re_fun_name.match(iFun) and
1943 1920 callable(oinfo['obj'])) :
1944 1921 #print 'going auto' # dbg
1945 1922 return self.handle_auto(line,continue_prompt,
1946 1923 pre,iFun,theRest,oinfo['obj'])
1947 1924 else:
1948 1925 #print 'was callable?', callable(oinfo['obj']) # dbg
1949 1926 return self.handle_normal(line,continue_prompt)
1950 1927
1951 1928 # If we get here, we have a normal Python line. Log and return.
1952 1929 return self.handle_normal(line,continue_prompt)
1953 1930
1954 1931 def _prefilter_dumb(self, line, continue_prompt):
1955 1932 """simple prefilter function, for debugging"""
1956 1933 return self.handle_normal(line,continue_prompt)
1957 1934
1958 1935 # Set the default prefilter() function (this can be user-overridden)
1959 1936 prefilter = _prefilter
1960 1937
1961 1938 def handle_normal(self,line,continue_prompt=None,
1962 1939 pre=None,iFun=None,theRest=None):
1963 1940 """Handle normal input lines. Use as a template for handlers."""
1964 1941
1965 1942 # With autoindent on, we need some way to exit the input loop, and I
1966 1943 # don't want to force the user to have to backspace all the way to
1967 1944 # clear the line. The rule will be in this case, that either two
1968 1945 # lines of pure whitespace in a row, or a line of pure whitespace but
1969 1946 # of a size different to the indent level, will exit the input loop.
1970 1947
1971 1948 if (continue_prompt and self.autoindent and line.isspace() and
1972 1949 (0 < abs(len(line) - self.indent_current_nsp) <= 2 or
1973 1950 (self.buffer[-1]).isspace() )):
1974 1951 line = ''
1975 1952
1976 1953 self.log(line,continue_prompt)
1977 1954 return line
1978 1955
1979 1956 def handle_alias(self,line,continue_prompt=None,
1980 1957 pre=None,iFun=None,theRest=None):
1981 1958 """Handle alias input lines. """
1982 1959
1983 1960 # pre is needed, because it carries the leading whitespace. Otherwise
1984 1961 # aliases won't work in indented sections.
1985 1962 line_out = '%sipalias(%s)' % (pre,make_quoted_expr(iFun + " " + theRest))
1986 1963 self.log(line_out,continue_prompt)
1987 1964 return line_out
1988 1965
1989 1966 def handle_shell_escape(self, line, continue_prompt=None,
1990 1967 pre=None,iFun=None,theRest=None):
1991 1968 """Execute the line in a shell, empty return value"""
1992 1969
1993 1970 #print 'line in :', `line` # dbg
1994 1971 # Example of a special handler. Others follow a similar pattern.
1995 1972 if line.lstrip().startswith('!!'):
1996 1973 # rewrite iFun/theRest to properly hold the call to %sx and
1997 1974 # the actual command to be executed, so handle_magic can work
1998 1975 # correctly
1999 1976 theRest = '%s %s' % (iFun[2:],theRest)
2000 1977 iFun = 'sx'
2001 1978 return self.handle_magic('%ssx %s' % (self.ESC_MAGIC,
2002 1979 line.lstrip()[2:]),
2003 1980 continue_prompt,pre,iFun,theRest)
2004 1981 else:
2005 1982 cmd=line.lstrip().lstrip('!')
2006 1983 line_out = '%s_ip.system(%s)' % (pre,make_quoted_expr(cmd))
2007 1984 # update cache/log and return
2008 1985 self.log(line_out,continue_prompt)
2009 1986 return line_out
2010 1987
2011 1988 def handle_magic(self, line, continue_prompt=None,
2012 1989 pre=None,iFun=None,theRest=None):
2013 1990 """Execute magic functions."""
2014 1991
2015 1992
2016 1993 cmd = '%s_ip.magic(%s)' % (pre,make_quoted_expr(iFun + " " + theRest))
2017 1994 self.log(cmd,continue_prompt)
2018 1995 #print 'in handle_magic, cmd=<%s>' % cmd # dbg
2019 1996 return cmd
2020 1997
2021 1998 def handle_auto(self, line, continue_prompt=None,
2022 1999 pre=None,iFun=None,theRest=None,obj=None):
2023 2000 """Hande lines which can be auto-executed, quoting if requested."""
2024 2001
2025 2002 #print 'pre <%s> iFun <%s> rest <%s>' % (pre,iFun,theRest) # dbg
2026 2003
2027 2004 # This should only be active for single-line input!
2028 2005 if continue_prompt:
2029 2006 self.log(line,continue_prompt)
2030 2007 return line
2031 2008
2032 2009 auto_rewrite = True
2033 2010
2034 2011 if pre == self.ESC_QUOTE:
2035 2012 # Auto-quote splitting on whitespace
2036 2013 newcmd = '%s("%s")' % (iFun,'", "'.join(theRest.split()) )
2037 2014 elif pre == self.ESC_QUOTE2:
2038 2015 # Auto-quote whole string
2039 2016 newcmd = '%s("%s")' % (iFun,theRest)
2040 2017 elif pre == self.ESC_PAREN:
2041 2018 newcmd = '%s(%s)' % (iFun,",".join(theRest.split()))
2042 2019 else:
2043 2020 # Auto-paren.
2044 2021 # We only apply it to argument-less calls if the autocall
2045 2022 # parameter is set to 2. We only need to check that autocall is <
2046 2023 # 2, since this function isn't called unless it's at least 1.
2047 2024 if not theRest and (self.rc.autocall < 2):
2048 2025 newcmd = '%s %s' % (iFun,theRest)
2049 2026 auto_rewrite = False
2050 2027 else:
2051 2028 if theRest.startswith('['):
2052 2029 if hasattr(obj,'__getitem__'):
2053 2030 # Don't autocall in this case: item access for an object
2054 2031 # which is BOTH callable and implements __getitem__.
2055 2032 newcmd = '%s %s' % (iFun,theRest)
2056 2033 auto_rewrite = False
2057 2034 else:
2058 2035 # if the object doesn't support [] access, go ahead and
2059 2036 # autocall
2060 2037 newcmd = '%s(%s)' % (iFun.rstrip(),",".join(theRest.split()))
2061 2038 elif theRest.endswith(';'):
2062 2039 newcmd = '%s(%s);' % (iFun.rstrip(),theRest[:-1])
2063 2040 else:
2064 2041 newcmd = '%s(%s)' % (iFun.rstrip(),",".join(theRest.split()))
2065 2042
2066 2043 if auto_rewrite:
2067 2044 print >>Term.cout, self.outputcache.prompt1.auto_rewrite() + newcmd
2068 2045 # log what is now valid Python, not the actual user input (without the
2069 2046 # final newline)
2070 2047 self.log(newcmd,continue_prompt)
2071 2048 return newcmd
2072 2049
2073 2050 def handle_help(self, line, continue_prompt=None,
2074 2051 pre=None,iFun=None,theRest=None):
2075 2052 """Try to get some help for the object.
2076 2053
2077 2054 obj? or ?obj -> basic information.
2078 2055 obj?? or ??obj -> more details.
2079 2056 """
2080 2057
2081 2058 # We need to make sure that we don't process lines which would be
2082 2059 # otherwise valid python, such as "x=1 # what?"
2083 2060 try:
2084 2061 codeop.compile_command(line)
2085 2062 except SyntaxError:
2086 2063 # We should only handle as help stuff which is NOT valid syntax
2087 2064 if line[0]==self.ESC_HELP:
2088 2065 line = line[1:]
2089 2066 elif line[-1]==self.ESC_HELP:
2090 2067 line = line[:-1]
2091 2068 self.log('#?'+line)
2092 2069 if line:
2093 2070 self.magic_pinfo(line)
2094 2071 else:
2095 2072 page(self.usage,screen_lines=self.rc.screen_length)
2096 2073 return '' # Empty string is needed here!
2097 2074 except:
2098 2075 # Pass any other exceptions through to the normal handler
2099 2076 return self.handle_normal(line,continue_prompt)
2100 2077 else:
2101 2078 # If the code compiles ok, we should handle it normally
2102 2079 return self.handle_normal(line,continue_prompt)
2103 2080
2104 2081 def getapi(self):
2105 2082 """ Get an IPApi object for this shell instance
2106 2083
2107 2084 Getting an IPApi object is always preferable to accessing the shell
2108 2085 directly, but this holds true especially for extensions.
2109 2086
2110 2087 It should always be possible to implement an extension with IPApi
2111 2088 alone. If not, contact maintainer to request an addition.
2112 2089
2113 2090 """
2114 2091 return self.api
2115 2092
2116 2093 def handle_emacs(self,line,continue_prompt=None,
2117 2094 pre=None,iFun=None,theRest=None):
2118 2095 """Handle input lines marked by python-mode."""
2119 2096
2120 2097 # Currently, nothing is done. Later more functionality can be added
2121 2098 # here if needed.
2122 2099
2123 2100 # The input cache shouldn't be updated
2124 2101
2125 2102 return line
2126 2103
2127 2104 def mktempfile(self,data=None):
2128 2105 """Make a new tempfile and return its filename.
2129 2106
2130 2107 This makes a call to tempfile.mktemp, but it registers the created
2131 2108 filename internally so ipython cleans it up at exit time.
2132 2109
2133 2110 Optional inputs:
2134 2111
2135 2112 - data(None): if data is given, it gets written out to the temp file
2136 2113 immediately, and the file is closed again."""
2137 2114
2138 2115 filename = tempfile.mktemp('.py','ipython_edit_')
2139 2116 self.tempfiles.append(filename)
2140 2117
2141 2118 if data:
2142 2119 tmp_file = open(filename,'w')
2143 2120 tmp_file.write(data)
2144 2121 tmp_file.close()
2145 2122 return filename
2146 2123
2147 2124 def write(self,data):
2148 2125 """Write a string to the default output"""
2149 2126 Term.cout.write(data)
2150 2127
2151 2128 def write_err(self,data):
2152 2129 """Write a string to the default error output"""
2153 2130 Term.cerr.write(data)
2154 2131
2155 2132 def exit(self):
2156 2133 """Handle interactive exit.
2157 2134
2158 2135 This method sets the exit_now attribute."""
2159 2136
2160 2137 if self.rc.confirm_exit:
2161 2138 if ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2162 2139 self.exit_now = True
2163 2140 else:
2164 2141 self.exit_now = True
2165 2142 return self.exit_now
2166 2143
2167 2144 def safe_execfile(self,fname,*where,**kw):
2168 2145 fname = os.path.expanduser(fname)
2169 2146
2170 2147 # find things also in current directory
2171 2148 dname = os.path.dirname(fname)
2172 2149 if not sys.path.count(dname):
2173 2150 sys.path.append(dname)
2174 2151
2175 2152 try:
2176 2153 xfile = open(fname)
2177 2154 except:
2178 2155 print >> Term.cerr, \
2179 2156 'Could not open file <%s> for safe execution.' % fname
2180 2157 return None
2181 2158
2182 2159 kw.setdefault('islog',0)
2183 2160 kw.setdefault('quiet',1)
2184 2161 kw.setdefault('exit_ignore',0)
2185 2162 first = xfile.readline()
2186 2163 loghead = str(self.loghead_tpl).split('\n',1)[0].strip()
2187 2164 xfile.close()
2188 2165 # line by line execution
2189 2166 if first.startswith(loghead) or kw['islog']:
2190 2167 print 'Loading log file <%s> one line at a time...' % fname
2191 2168 if kw['quiet']:
2192 2169 stdout_save = sys.stdout
2193 2170 sys.stdout = StringIO.StringIO()
2194 2171 try:
2195 2172 globs,locs = where[0:2]
2196 2173 except:
2197 2174 try:
2198 2175 globs = locs = where[0]
2199 2176 except:
2200 2177 globs = locs = globals()
2201 2178 badblocks = []
2202 2179
2203 2180 # we also need to identify indented blocks of code when replaying
2204 2181 # logs and put them together before passing them to an exec
2205 2182 # statement. This takes a bit of regexp and look-ahead work in the
2206 2183 # file. It's easiest if we swallow the whole thing in memory
2207 2184 # first, and manually walk through the lines list moving the
2208 2185 # counter ourselves.
2209 2186 indent_re = re.compile('\s+\S')
2210 2187 xfile = open(fname)
2211 2188 filelines = xfile.readlines()
2212 2189 xfile.close()
2213 2190 nlines = len(filelines)
2214 2191 lnum = 0
2215 2192 while lnum < nlines:
2216 2193 line = filelines[lnum]
2217 2194 lnum += 1
2218 2195 # don't re-insert logger status info into cache
2219 2196 if line.startswith('#log#'):
2220 2197 continue
2221 2198 else:
2222 2199 # build a block of code (maybe a single line) for execution
2223 2200 block = line
2224 2201 try:
2225 2202 next = filelines[lnum] # lnum has already incremented
2226 2203 except:
2227 2204 next = None
2228 2205 while next and indent_re.match(next):
2229 2206 block += next
2230 2207 lnum += 1
2231 2208 try:
2232 2209 next = filelines[lnum]
2233 2210 except:
2234 2211 next = None
2235 2212 # now execute the block of one or more lines
2236 2213 try:
2237 2214 exec block in globs,locs
2238 2215 except SystemExit:
2239 2216 pass
2240 2217 except:
2241 2218 badblocks.append(block.rstrip())
2242 2219 if kw['quiet']: # restore stdout
2243 2220 sys.stdout.close()
2244 2221 sys.stdout = stdout_save
2245 2222 print 'Finished replaying log file <%s>' % fname
2246 2223 if badblocks:
2247 2224 print >> sys.stderr, ('\nThe following lines/blocks in file '
2248 2225 '<%s> reported errors:' % fname)
2249 2226
2250 2227 for badline in badblocks:
2251 2228 print >> sys.stderr, badline
2252 2229 else: # regular file execution
2253 2230 try:
2254 2231 execfile(fname,*where)
2255 2232 except SyntaxError:
2256 2233 etype,evalue = sys.exc_info()[:2]
2257 2234 self.SyntaxTB(etype,evalue,[])
2258 2235 warn('Failure executing file: <%s>' % fname)
2259 2236 except SystemExit,status:
2260 2237 if not kw['exit_ignore']:
2261 2238 self.InteractiveTB()
2262 2239 warn('Failure executing file: <%s>' % fname)
2263 2240 except:
2264 2241 self.InteractiveTB()
2265 2242 warn('Failure executing file: <%s>' % fname)
2266 2243
2267 2244 #************************* end of file <iplib.py> *****************************
1 NO CONTENT: modified file
The requested commit or file is too big and content was truncated. Show full diff
General Comments 0
You need to be logged in to leave comments. Login now