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