##// END OF EJS Templates
Merging -r 1181 from lp:ipython....
Brian Granger -
r2128:edd2e623 merge
parent child Browse files
Show More
@@ -0,0 +1,56 b''
1 """ Utilities for accessing the platform's clipboard.
2 """
3
4 import subprocess
5 import sys
6
7 from IPython.ipapi import TryNext
8
9
10 def win32_clipboard_get():
11 """ Get the current clipboard's text on Windows.
12
13 Requires Mark Hammond's pywin32 extensions.
14 """
15 try:
16 import win32clipboard
17 except ImportError:
18 message = ("Getting text from the clipboard requires the pywin32 "
19 "extensions: http://sourceforge.net/projects/pywin32/")
20 raise TryNext(message)
21 win32clipboard.OpenClipboard()
22 text = win32clipboard.GetClipboardData(win32clipboard.CF_TEXT)
23 # FIXME: convert \r\n to \n?
24 win32clipboard.CloseClipboard()
25 return text
26
27 def osx_clipboard_get():
28 """ Get the clipboard's text on OS X.
29 """
30 p = subprocess.Popen(['pbpaste', '-Prefer', 'ascii'],
31 stdout=subprocess.PIPE)
32 text, stderr = p.communicate()
33 # Text comes in with old Mac \r line endings. Change them to \n.
34 text = text.replace('\r', '\n')
35 return text
36
37 def tkinter_clipboard_get():
38 """ Get the clipboard's text using Tkinter.
39
40 This is the default on systems that are not Windows or OS X. It may
41 interfere with other UI toolkits and should be replaced with an
42 implementation that uses that toolkit.
43 """
44 try:
45 import Tkinter
46 except ImportError:
47 message = ("Getting text from the clipboard on this platform "
48 "requires Tkinter.")
49 raise TryNext(message)
50 root = Tkinter.Tk()
51 root.withdraw()
52 text = root.clipboard_get()
53 root.destroy()
54 return text
55
56
@@ -1,247 +1,266 b''
1 1 """hooks for IPython.
2 2
3 3 In Python, it is possible to overwrite any method of any object if you really
4 4 want to. But IPython exposes a few 'hooks', methods which are _designed_ to
5 5 be overwritten by users for customization purposes. This module defines the
6 6 default versions of all such hooks, which get used by IPython if not
7 7 overridden by the user.
8 8
9 9 hooks are simple functions, but they should be declared with 'self' as their
10 10 first argument, because when activated they are registered into IPython as
11 11 instance methods. The self argument will be the IPython running instance
12 12 itself, so hooks have full access to the entire IPython object.
13 13
14 14 If you wish to define a new hook and activate it, you need to put the
15 15 necessary code into a python file which can be either imported or execfile()'d
16 16 from within your ipythonrc configuration.
17 17
18 18 For example, suppose that you have a module called 'myiphooks' in your
19 19 PYTHONPATH, which contains the following definition:
20 20
21 21 import os
22 22 from IPython.core import ipapi
23 23 ip = ipapi.get()
24 24
25 25 def calljed(self,filename, linenum):
26 26 "My editor hook calls the jed editor directly."
27 27 print "Calling my own editor, jed ..."
28 28 if os.system('jed +%d %s' % (linenum,filename)) != 0:
29 29 raise ipapi.TryNext()
30 30
31 31 ip.set_hook('editor', calljed)
32 32
33 33 You can then enable the functionality by doing 'import myiphooks'
34 34 somewhere in your configuration files or ipython command line.
35 35 """
36 36
37 37 #*****************************************************************************
38 38 # Copyright (C) 2005 Fernando Perez. <fperez@colorado.edu>
39 39 #
40 40 # Distributed under the terms of the BSD License. The full license is in
41 41 # the file COPYING, distributed as part of this software.
42 42 #*****************************************************************************
43 43
44 44 from IPython.core import ipapi
45 45
46 import os,bisect
47 from IPython.utils.genutils import Term,shell
46 import os, bisect
47 import sys
48 from IPython.utils.genutils import Term, shell
48 49 from pprint import PrettyPrinter
49 50
50 51 # List here all the default hooks. For now it's just the editor functions
51 52 # but over time we'll move here all the public API for user-accessible things.
52 53 # vds: >>
53 54 __all__ = ['editor', 'fix_error_editor', 'synchronize_with_editor', 'result_display',
54 55 'input_prefilter', 'shutdown_hook', 'late_startup_hook',
55 56 'generate_prompt', 'generate_output_prompt','shell_hook',
56 'show_in_pager','pre_prompt_hook', 'pre_runcode_hook']
57 'show_in_pager','pre_prompt_hook', 'pre_runcode_hook',
58 'clipboard_get']
57 59 # vds: <<
58 60
59 61 pformat = PrettyPrinter().pformat
60 62
61 63 def editor(self,filename, linenum=None):
62 64 """Open the default editor at the given filename and linenumber.
63 65
64 66 This is IPython's default editor hook, you can use it as an example to
65 67 write your own modified one. To set your own editor function as the
66 68 new editor hook, call ip.set_hook('editor',yourfunc)."""
67 69
68 70 # IPython configures a default editor at startup by reading $EDITOR from
69 71 # the environment, and falling back on vi (unix) or notepad (win32).
70 72 editor = self.rc.editor
71 73
72 74 # marker for at which line to open the file (for existing objects)
73 75 if linenum is None or editor=='notepad':
74 76 linemark = ''
75 77 else:
76 78 linemark = '+%d' % int(linenum)
77 79
78 80 # Enclose in quotes if necessary and legal
79 81 if ' ' in editor and os.path.isfile(editor) and editor[0] != '"':
80 82 editor = '"%s"' % editor
81 83
82 84 # Call the actual editor
83 85 if os.system('%s %s %s' % (editor,linemark,filename)) != 0:
84 86 raise ipapi.TryNext()
85 87
86 88 import tempfile
87 89 def fix_error_editor(self,filename,linenum,column,msg):
88 90 """Open the editor at the given filename, linenumber, column and
89 91 show an error message. This is used for correcting syntax errors.
90 92 The current implementation only has special support for the VIM editor,
91 93 and falls back on the 'editor' hook if VIM is not used.
92 94
93 95 Call ip.set_hook('fix_error_editor',youfunc) to use your own function,
94 96 """
95 97 def vim_quickfix_file():
96 98 t = tempfile.NamedTemporaryFile()
97 99 t.write('%s:%d:%d:%s\n' % (filename,linenum,column,msg))
98 100 t.flush()
99 101 return t
100 102 if os.path.basename(self.rc.editor) != 'vim':
101 103 self.hooks.editor(filename,linenum)
102 104 return
103 105 t = vim_quickfix_file()
104 106 try:
105 107 if os.system('vim --cmd "set errorformat=%f:%l:%c:%m" -q ' + t.name):
106 108 raise ipapi.TryNext()
107 109 finally:
108 110 t.close()
109 111
110 112 # vds: >>
111 113 def synchronize_with_editor(self, filename, linenum, column):
112 114 pass
113 115 # vds: <<
114 116
115 117 class CommandChainDispatcher:
116 118 """ Dispatch calls to a chain of commands until some func can handle it
117 119
118 120 Usage: instantiate, execute "add" to add commands (with optional
119 121 priority), execute normally via f() calling mechanism.
120 122
121 123 """
122 124 def __init__(self,commands=None):
123 125 if commands is None:
124 126 self.chain = []
125 127 else:
126 128 self.chain = commands
127 129
128 130
129 131 def __call__(self,*args, **kw):
130 132 """ Command chain is called just like normal func.
131 133
132 134 This will call all funcs in chain with the same args as were given to this
133 135 function, and return the result of first func that didn't raise
134 136 TryNext """
135 137
136 138 for prio,cmd in self.chain:
137 139 #print "prio",prio,"cmd",cmd #dbg
138 140 try:
139 141 ret = cmd(*args, **kw)
140 142 return ret
141 143 except ipapi.TryNext, exc:
142 144 if exc.args or exc.kwargs:
143 145 args = exc.args
144 146 kw = exc.kwargs
145 147 # if no function will accept it, raise TryNext up to the caller
146 148 raise ipapi.TryNext
147 149
148 150 def __str__(self):
149 151 return str(self.chain)
150 152
151 153 def add(self, func, priority=0):
152 154 """ Add a func to the cmd chain with given priority """
153 155 bisect.insort(self.chain,(priority,func))
154 156
155 157 def __iter__(self):
156 158 """ Return all objects in chain.
157 159
158 160 Handy if the objects are not callable.
159 161 """
160 162 return iter(self.chain)
161 163
162 164 def result_display(self,arg):
163 165 """ Default display hook.
164 166
165 167 Called for displaying the result to the user.
166 168 """
167 169
168 170 if self.rc.pprint:
169 171 out = pformat(arg)
170 172 if '\n' in out:
171 173 # So that multi-line strings line up with the left column of
172 174 # the screen, instead of having the output prompt mess up
173 175 # their first line.
174 176 Term.cout.write('\n')
175 177 print >>Term.cout, out
176 178 else:
177 179 # By default, the interactive prompt uses repr() to display results,
178 180 # so we should honor this. Users who'd rather use a different
179 181 # mechanism can easily override this hook.
180 182 print >>Term.cout, repr(arg)
181 183 # the default display hook doesn't manipulate the value to put in history
182 184 return None
183 185
184 186 def input_prefilter(self,line):
185 187 """ Default input prefilter
186 188
187 189 This returns the line as unchanged, so that the interpreter
188 190 knows that nothing was done and proceeds with "classic" prefiltering
189 191 (%magics, !shell commands etc.).
190 192
191 193 Note that leading whitespace is not passed to this hook. Prefilter
192 194 can't alter indentation.
193 195
194 196 """
195 197 #print "attempt to rewrite",line #dbg
196 198 return line
197 199
198 200 def shutdown_hook(self):
199 201 """ default shutdown hook
200 202
201 203 Typically, shotdown hooks should raise TryNext so all shutdown ops are done
202 204 """
203 205
204 206 #print "default shutdown hook ok" # dbg
205 207 return
206 208
207 209 def late_startup_hook(self):
208 210 """ Executed after ipython has been constructed and configured
209 211
210 212 """
211 213 #print "default startup hook ok" # dbg
212 214
213 215 def generate_prompt(self, is_continuation):
214 216 """ calculate and return a string with the prompt to display """
215 217 ip = self.api
216 218 if is_continuation:
217 219 return str(ip.IP.outputcache.prompt2)
218 220 return str(ip.IP.outputcache.prompt1)
219 221
220 222 def generate_output_prompt(self):
221 223 ip = self.api
222 224 return str(ip.IP.outputcache.prompt_out)
223 225
224 226 def shell_hook(self,cmd):
225 227 """ Run system/shell command a'la os.system() """
226 228
227 229 shell(cmd, header=self.rc.system_header, verbose=self.rc.system_verbose)
228 230
229 231 def show_in_pager(self,s):
230 232 """ Run a string through pager """
231 233 # raising TryNext here will use the default paging functionality
232 234 raise ipapi.TryNext
233 235
234 236 def pre_prompt_hook(self):
235 237 """ Run before displaying the next prompt
236 238
237 239 Use this e.g. to display output from asynchronous operations (in order
238 240 to not mess up text entry)
239 241 """
240 242
241 243 return None
242 244
243 245 def pre_runcode_hook(self):
244 246 """ Executed before running the (prefiltered) code in IPython """
245 247 return None
246
247 248
249 def clipboard_get(self):
250 """ Get text from the clipboard.
251 """
252 from IPython.lib.clipboard import (
253 osx_clipboard_get, tkinter_clipboard_get,
254 win32_clipboard_get
255 )
256 if sys.platform == 'win32':
257 chain = [win32_clipboard_get, tkinter_clipboard_get]
258 elif sys.platform == 'darwin':
259 chain = [osx_clipboard_get, tkinter_clipboard_get]
260 else:
261 chain = [tkinter_clipboard_get]
262 dispatcher = CommandChainDispatcher()
263 for func in chain:
264 dispatcher.add(func)
265 text = dispatcher()
266 return text
@@ -1,3457 +1,3522 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.utils import wildcard
47 47 from IPython.core import debugger, oinspect
48 48 from IPython.core.fakemodule import FakeModule
49 49 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
50 50 from IPython.utils.PyColorize import Parser
51 51 from IPython.utils.ipstruct import Struct
52 52 from IPython.core.macro import Macro
53 53 from IPython.utils.genutils import *
54 54 from IPython.utils 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.core.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.utils.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 def _rerun_pasted(self):
3266 """ Rerun a previously pasted command.
3267 """
3268 b = self.user_ns.get('pasted_block', None)
3269 if b is None:
3270 raise UsageError('No previous pasted block available')
3271 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3272 exec b in self.user_ns
3273
3274 def _get_pasted_lines(self, sentinel):
3275 """ Yield pasted lines until the user enters the given sentinel value.
3276 """
3277 from IPython.core import iplib
3278 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3279 while True:
3280 l = iplib.raw_input_original(':')
3281 if l == sentinel:
3282 return
3283 else:
3284 yield l
3285
3286 def _strip_pasted_lines_for_code(self, raw_lines):
3287 """ Strip non-code parts of a sequence of lines to return a block of
3288 code.
3289 """
3290 # Regular expressions that declare text we strip from the input:
3291 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3292 r'^\s*(\s?>)+', # Python input prompt
3293 r'^\s*\.{3,}', # Continuation prompts
3294 r'^\++',
3295 ]
3296
3297 strip_from_start = map(re.compile,strip_re)
3298
3299 lines = []
3300 for l in raw_lines:
3301 for pat in strip_from_start:
3302 l = pat.sub('',l)
3303 lines.append(l)
3304
3305 block = "\n".join(lines) + '\n'
3306 #print "block:\n",block
3307 return block
3308
3309 def _execute_block(self, block, par):
3310 """ Execute a block, or store it in a variable, per the user's request.
3311 """
3312 if not par:
3313 b = textwrap.dedent(block)
3314 self.user_ns['pasted_block'] = b
3315 exec b in self.user_ns
3316 else:
3317 self.user_ns[par] = SList(block.splitlines())
3318 print "Block assigned to '%s'" % par
3319
3265 3320 def magic_cpaste(self, parameter_s=''):
3266 3321 """Allows you to paste & execute a pre-formatted code block from clipboard.
3267 3322
3268 3323 You must terminate the block with '--' (two minus-signs) alone on the
3269 3324 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3270 3325 is the new sentinel for this operation)
3271 3326
3272 3327 The block is dedented prior to execution to enable execution of method
3273 3328 definitions. '>' and '+' characters at the beginning of a line are
3274 3329 ignored, to allow pasting directly from e-mails, diff files and
3275 3330 doctests (the '...' continuation prompt is also stripped). The
3276 3331 executed block is also assigned to variable named 'pasted_block' for
3277 3332 later editing with '%edit pasted_block'.
3278 3333
3279 3334 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3280 3335 This assigns the pasted block to variable 'foo' as string, without
3281 3336 dedenting or executing it (preceding >>> and + is still stripped)
3282 3337
3283 3338 '%cpaste -r' re-executes the block previously entered by cpaste.
3284 3339
3285 3340 Do not be alarmed by garbled output on Windows (it's a readline bug).
3286 3341 Just press enter and type -- (and press enter again) and the block
3287 3342 will be what was just pasted.
3288 3343
3289 3344 IPython statements (magics, shell escapes) are not supported (yet).
3345
3346 See also
3347 --------
3348 %paste: automatically pull code from clipboard.
3290 3349 """
3350
3291 3351 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3292 3352 par = args.strip()
3293 3353 if opts.has_key('r'):
3294 b = self.user_ns.get('pasted_block', None)
3295 if b is None:
3296 raise UsageError('No previous pasted block available')
3297 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3298 exec b in self.user_ns
3354 self._rerun_pasted()
3299 3355 return
3300 3356
3301 3357 sentinel = opts.get('s','--')
3302 3358
3303 # Regular expressions that declare text we strip from the input:
3304 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3305 r'^\s*(\s?>)+', # Python input prompt
3306 r'^\s*\.{3,}', # Continuation prompts
3307 r'^\++',
3308 ]
3359 block = self._strip_pasted_lines_for_code(
3360 self._get_pasted_lines(sentinel))
3309 3361
3310 strip_from_start = map(re.compile,strip_re)
3362 self._execute_block(block, par)
3363
3364 def magic_paste(self, parameter_s=''):
3365 """Allows you to paste & execute a pre-formatted code block from clipboard.
3311 3366
3312 from IPython.core import iplib
3313 lines = []
3314 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3315 while 1:
3316 l = iplib.raw_input_original(':')
3317 if l ==sentinel:
3318 break
3319
3320 for pat in strip_from_start:
3321 l = pat.sub('',l)
3322 lines.append(l)
3323
3324 block = "\n".join(lines) + '\n'
3325 #print "block:\n",block
3326 if not par:
3327 b = textwrap.dedent(block)
3328 self.user_ns['pasted_block'] = b
3329 exec b in self.user_ns
3330 else:
3331 self.user_ns[par] = SList(block.splitlines())
3332 print "Block assigned to '%s'" % par
3333
3367 The text is pulled directly from the clipboard without user
3368 intervention.
3369
3370 The block is dedented prior to execution to enable execution of method
3371 definitions. '>' and '+' characters at the beginning of a line are
3372 ignored, to allow pasting directly from e-mails, diff files and
3373 doctests (the '...' continuation prompt is also stripped). The
3374 executed block is also assigned to variable named 'pasted_block' for
3375 later editing with '%edit pasted_block'.
3376
3377 You can also pass a variable name as an argument, e.g. '%paste foo'.
3378 This assigns the pasted block to variable 'foo' as string, without
3379 dedenting or executing it (preceding >>> and + is still stripped)
3380
3381 '%paste -r' re-executes the block previously entered by cpaste.
3382
3383 IPython statements (magics, shell escapes) are not supported (yet).
3384
3385 See also
3386 --------
3387 %cpaste: manually paste code into terminal until you mark its end.
3388 """
3389 opts,args = self.parse_options(parameter_s,'r:',mode='string')
3390 par = args.strip()
3391 if opts.has_key('r'):
3392 self._rerun_pasted()
3393 return
3394
3395 text = self.shell.hooks.clipboard_get()
3396 block = self._strip_pasted_lines_for_code(text.splitlines())
3397 self._execute_block(block, par)
3398
3334 3399 def magic_quickref(self,arg):
3335 3400 """ Show a quick reference sheet """
3336 3401 import IPython.core.usage
3337 3402 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3338 3403
3339 3404 page(qr)
3340 3405
3341 3406 def magic_upgrade(self,arg):
3342 3407 """ Upgrade your IPython installation
3343 3408
3344 3409 This will copy the config files that don't yet exist in your
3345 3410 ipython dir from the system config dir. Use this after upgrading
3346 3411 IPython if you don't wish to delete your .ipython dir.
3347 3412
3348 3413 Call with -nolegacy to get rid of ipythonrc* files (recommended for
3349 3414 new users)
3350 3415
3351 3416 """
3352 3417 ip = self.getapi()
3353 3418 ipinstallation = path(IPython.__file__).dirname()
3354 3419 upgrade_script = '%s "%s"' % (sys.executable,ipinstallation / 'utils' / 'upgradedir.py')
3355 3420 src_config = ipinstallation / 'config' / 'userconfig'
3356 3421 userdir = path(ip.options.ipythondir)
3357 3422 cmd = '%s "%s" "%s"' % (upgrade_script, src_config, userdir)
3358 3423 print ">",cmd
3359 3424 shell(cmd)
3360 3425 if arg == '-nolegacy':
3361 3426 legacy = userdir.files('ipythonrc*')
3362 3427 print "Nuking legacy files:",legacy
3363 3428
3364 3429 [p.remove() for p in legacy]
3365 3430 suffix = (sys.platform == 'win32' and '.ini' or '')
3366 3431 (userdir / ('ipythonrc' + suffix)).write_text('# Empty, see ipy_user_conf.py\n')
3367 3432
3368 3433
3369 3434 def magic_doctest_mode(self,parameter_s=''):
3370 3435 """Toggle doctest mode on and off.
3371 3436
3372 3437 This mode allows you to toggle the prompt behavior between normal
3373 3438 IPython prompts and ones that are as similar to the default IPython
3374 3439 interpreter as possible.
3375 3440
3376 3441 It also supports the pasting of code snippets that have leading '>>>'
3377 3442 and '...' prompts in them. This means that you can paste doctests from
3378 3443 files or docstrings (even if they have leading whitespace), and the
3379 3444 code will execute correctly. You can then use '%history -tn' to see
3380 3445 the translated history without line numbers; this will give you the
3381 3446 input after removal of all the leading prompts and whitespace, which
3382 3447 can be pasted back into an editor.
3383 3448
3384 3449 With these features, you can switch into this mode easily whenever you
3385 3450 need to do testing and changes to doctests, without having to leave
3386 3451 your existing IPython session.
3387 3452 """
3388 3453
3389 3454 # XXX - Fix this to have cleaner activate/deactivate calls.
3390 3455 from IPython.extensions import InterpreterPasteInput as ipaste
3391 3456 from IPython.utils.ipstruct import Struct
3392 3457
3393 3458 # Shorthands
3394 3459 shell = self.shell
3395 3460 oc = shell.outputcache
3396 3461 rc = shell.rc
3397 3462 meta = shell.meta
3398 3463 # dstore is a data store kept in the instance metadata bag to track any
3399 3464 # changes we make, so we can undo them later.
3400 3465 dstore = meta.setdefault('doctest_mode',Struct())
3401 3466 save_dstore = dstore.setdefault
3402 3467
3403 3468 # save a few values we'll need to recover later
3404 3469 mode = save_dstore('mode',False)
3405 3470 save_dstore('rc_pprint',rc.pprint)
3406 3471 save_dstore('xmode',shell.InteractiveTB.mode)
3407 3472 save_dstore('rc_separate_out',rc.separate_out)
3408 3473 save_dstore('rc_separate_out2',rc.separate_out2)
3409 3474 save_dstore('rc_prompts_pad_left',rc.prompts_pad_left)
3410 3475 save_dstore('rc_separate_in',rc.separate_in)
3411 3476
3412 3477 if mode == False:
3413 3478 # turn on
3414 3479 ipaste.activate_prefilter()
3415 3480
3416 3481 oc.prompt1.p_template = '>>> '
3417 3482 oc.prompt2.p_template = '... '
3418 3483 oc.prompt_out.p_template = ''
3419 3484
3420 3485 # Prompt separators like plain python
3421 3486 oc.input_sep = oc.prompt1.sep = ''
3422 3487 oc.output_sep = ''
3423 3488 oc.output_sep2 = ''
3424 3489
3425 3490 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3426 3491 oc.prompt_out.pad_left = False
3427 3492
3428 3493 rc.pprint = False
3429 3494
3430 3495 shell.magic_xmode('Plain')
3431 3496
3432 3497 else:
3433 3498 # turn off
3434 3499 ipaste.deactivate_prefilter()
3435 3500
3436 3501 oc.prompt1.p_template = rc.prompt_in1
3437 3502 oc.prompt2.p_template = rc.prompt_in2
3438 3503 oc.prompt_out.p_template = rc.prompt_out
3439 3504
3440 3505 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3441 3506
3442 3507 oc.output_sep = dstore.rc_separate_out
3443 3508 oc.output_sep2 = dstore.rc_separate_out2
3444 3509
3445 3510 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3446 3511 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3447 3512
3448 3513 rc.pprint = dstore.rc_pprint
3449 3514
3450 3515 shell.magic_xmode(dstore.xmode)
3451 3516
3452 3517 # Store new mode and inform
3453 3518 dstore.mode = bool(1-int(mode))
3454 3519 print 'Doctest mode is:',
3455 3520 print ['OFF','ON'][dstore.mode]
3456 3521
3457 3522 # end Magic
@@ -1,254 +1,290 b''
1 1 """Tests for various magic functions.
2 2
3 3 Needs to be run by nose (to make ipython session available).
4 4 """
5 5
6 6 import os
7 7 import sys
8 8 import tempfile
9 9 import types
10 10
11 11 import nose.tools as nt
12 12
13 13 from IPython.utils.platutils import find_cmd, get_long_path_name
14 14 from IPython.testing import decorators as dec
15 15 from IPython.testing import tools as tt
16 16
17 17 #-----------------------------------------------------------------------------
18 18 # Test functions begin
19 19
20 20 def test_rehashx():
21 21 # clear up everything
22 22 _ip.IP.alias_table.clear()
23 23 del _ip.db['syscmdlist']
24 24
25 25 _ip.magic('rehashx')
26 26 # Practically ALL ipython development systems will have more than 10 aliases
27 27
28 28 yield (nt.assert_true, len(_ip.IP.alias_table) > 10)
29 29 for key, val in _ip.IP.alias_table.items():
30 30 # we must strip dots from alias names
31 31 nt.assert_true('.' not in key)
32 32
33 33 # rehashx must fill up syscmdlist
34 34 scoms = _ip.db['syscmdlist']
35 35 yield (nt.assert_true, len(scoms) > 10)
36 36
37 37
38 38 def doctest_hist_f():
39 39 """Test %hist -f with temporary filename.
40 40
41 41 In [9]: import tempfile
42 42
43 43 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
44 44
45 45 In [11]: %hist -n -f $tfile 3
46 46
47 47 """
48 48
49 49
50 50 def doctest_hist_r():
51 51 """Test %hist -r
52 52
53 53 XXX - This test is not recording the output correctly. Not sure why...
54 54
55 55 In [20]: 'hist' in _ip.IP.lsmagic()
56 56 Out[20]: True
57 57
58 58 In [6]: x=1
59 59
60 60 In [7]: %hist -n -r 2
61 61 x=1 # random
62 62 hist -n -r 2 # random
63 63 """
64 64
65 65 # This test is known to fail on win32.
66 66 # See ticket https://bugs.launchpad.net/bugs/366334
67 67 def test_obj_del():
68 68 """Test that object's __del__ methods are called on exit."""
69 69 test_dir = os.path.dirname(__file__)
70 70 del_file = os.path.join(test_dir,'obj_del.py')
71 71 ipython_cmd = find_cmd('ipython')
72 72 out = _ip.IP.getoutput('%s %s' % (ipython_cmd, del_file))
73 73 nt.assert_equals(out,'obj_del.py: object A deleted')
74 74
75 75
76 76 def test_shist():
77 77 # Simple tests of ShadowHist class - test generator.
78 78 import os, shutil, tempfile
79 79
80 80 from IPython.extensions import pickleshare
81 81 from IPython.core.history import ShadowHist
82 82
83 83 tfile = tempfile.mktemp('','tmp-ipython-')
84 84
85 85 db = pickleshare.PickleShareDB(tfile)
86 86 s = ShadowHist(db)
87 87 s.add('hello')
88 88 s.add('world')
89 89 s.add('hello')
90 90 s.add('hello')
91 91 s.add('karhu')
92 92
93 93 yield nt.assert_equals,s.all(),[(1, 'hello'), (2, 'world'), (3, 'karhu')]
94 94
95 95 yield nt.assert_equal,s.get(2),'world'
96 96
97 97 shutil.rmtree(tfile)
98 98
99 99 @dec.skipif_not_numpy
100 100 def test_numpy_clear_array_undec():
101 101 from IPython.extensions import clearcmd
102 102
103 103 _ip.ex('import numpy as np')
104 104 _ip.ex('a = np.empty(2)')
105 105 yield (nt.assert_true, 'a' in _ip.user_ns)
106 106 _ip.magic('clear array')
107 107 yield (nt.assert_false, 'a' in _ip.user_ns)
108 108
109 109
110 110 @dec.skip()
111 111 def test_fail_dec(*a,**k):
112 112 yield nt.assert_true, False
113 113
114 114 @dec.skip('This one shouldn not run')
115 115 def test_fail_dec2(*a,**k):
116 116 yield nt.assert_true, False
117 117
118 118 @dec.skipknownfailure
119 119 def test_fail_dec3(*a,**k):
120 120 yield nt.assert_true, False
121 121
122 122
123 123 def doctest_refbug():
124 124 """Very nasty problem with references held by multiple runs of a script.
125 125 See: https://bugs.launchpad.net/ipython/+bug/269966
126 126
127 127 In [1]: _ip.IP.clear_main_mod_cache()
128 128
129 129 In [2]: run refbug
130 130
131 131 In [3]: call_f()
132 132 lowercased: hello
133 133
134 134 In [4]: run refbug
135 135
136 136 In [5]: call_f()
137 137 lowercased: hello
138 138 lowercased: hello
139 139 """
140 140
141 141 #-----------------------------------------------------------------------------
142 142 # Tests for %run
143 143 #-----------------------------------------------------------------------------
144 144
145 145 # %run is critical enough that it's a good idea to have a solid collection of
146 146 # tests for it, some as doctests and some as normal tests.
147 147
148 148 def doctest_run_ns():
149 149 """Classes declared %run scripts must be instantiable afterwards.
150 150
151 151 In [11]: run tclass foo
152 152
153 153 In [12]: isinstance(f(),foo)
154 154 Out[12]: True
155 155 """
156 156
157 157
158 158 def doctest_run_ns2():
159 159 """Classes declared %run scripts must be instantiable afterwards.
160 160
161 161 In [4]: run tclass C-first_pass
162 162
163 163 In [5]: run tclass C-second_pass
164 164 tclass.py: deleting object: C-first_pass
165 165 """
166 166
167 167 @dec.skip_win32
168 168 def doctest_run_builtins():
169 169 """Check that %run doesn't damage __builtins__ via a doctest.
170 170
171 171 This is similar to the test_run_builtins, but I want *both* forms of the
172 172 test to catch any possible glitches in our testing machinery, since that
173 173 modifies %run somewhat. So for this, we have both a normal test (below)
174 174 and a doctest (this one).
175 175
176 176 In [1]: import tempfile
177 177
178 178 In [2]: bid1 = id(__builtins__)
179 179
180 180 In [3]: f = tempfile.NamedTemporaryFile()
181 181
182 182 In [4]: f.write('pass\\n')
183 183
184 184 In [5]: f.flush()
185 185
186 186 In [6]: print 'B1:',type(__builtins__)
187 187 B1: <type 'module'>
188 188
189 189 In [7]: %run $f.name
190 190
191 191 In [8]: bid2 = id(__builtins__)
192 192
193 193 In [9]: print 'B2:',type(__builtins__)
194 194 B2: <type 'module'>
195 195
196 196 In [10]: bid1 == bid2
197 197 Out[10]: True
198 198 """
199 199
200 200 # For some tests, it will be handy to organize them in a class with a common
201 201 # setup that makes a temp file
202 202
203 203 class TestMagicRun(object):
204 204
205 205 def setup(self):
206 206 """Make a valid python temp file."""
207 207 f = tempfile.NamedTemporaryFile()
208 208 f.write('pass\n')
209 209 f.flush()
210 210 self.tmpfile = f
211 211
212 212 def run_tmpfile(self):
213 213 # This fails on Windows if self.tmpfile.name has spaces or "~" in it.
214 214 # See below and ticket https://bugs.launchpad.net/bugs/366353
215 215 _ip.magic('run %s' % self.tmpfile.name)
216 216
217 217 # See https://bugs.launchpad.net/bugs/366353
218 218 @dec.skip_if_not_win32
219 219 def test_run_tempfile_path(self):
220 220 tt.assert_equals(True,False,"%run doesn't work with tempfile paths on win32.")
221 221
222 222 # See https://bugs.launchpad.net/bugs/366353
223 223 @dec.skip_win32
224 224 def test_builtins_id(self):
225 225 """Check that %run doesn't damage __builtins__ """
226 226
227 227 # Test that the id of __builtins__ is not modified by %run
228 228 bid1 = id(_ip.user_ns['__builtins__'])
229 229 self.run_tmpfile()
230 230 bid2 = id(_ip.user_ns['__builtins__'])
231 231 tt.assert_equals(bid1, bid2)
232 232
233 233 # See https://bugs.launchpad.net/bugs/366353
234 234 @dec.skip_win32
235 235 def test_builtins_type(self):
236 236 """Check that the type of __builtins__ doesn't change with %run.
237 237
238 238 However, the above could pass if __builtins__ was already modified to
239 239 be a dict (it should be a module) by a previous use of %run. So we
240 240 also check explicitly that it really is a module:
241 241 """
242 242 self.run_tmpfile()
243 243 tt.assert_equals(type(_ip.user_ns['__builtins__']),type(sys))
244 244
245 245 # See https://bugs.launchpad.net/bugs/366353
246 246 @dec.skip_win32
247 247 def test_prompts(self):
248 248 """Test that prompts correctly generate after %run"""
249 249 self.run_tmpfile()
250 250 p2 = str(_ip.IP.outputcache.prompt2).strip()
251 251 nt.assert_equals(p2[:3], '...')
252 252
253 253 def teardown(self):
254 254 self.tmpfile.close()
255
256 # Multiple tests for clipboard pasting
257 def test_paste():
258
259 def paste(txt):
260 hooks.clipboard_get = lambda : txt
261 _ip.magic('paste')
262
263 # Inject fake clipboard hook but save original so we can restore it later
264 hooks = _ip.IP.hooks
265 user_ns = _ip.user_ns
266 original_clip = hooks.clipboard_get
267
268 try:
269 # Run tests with fake clipboard function
270 user_ns.pop('x', None)
271 paste('x=1')
272 yield (nt.assert_equal, user_ns['x'], 1)
273
274 user_ns.pop('x', None)
275 paste('>>> x=2')
276 yield (nt.assert_equal, user_ns['x'], 2)
277
278 paste("""
279 >>> x = [1,2,3]
280 >>> y = []
281 >>> for i in x:
282 ... y.append(i**2)
283 ...
284 """)
285 yield (nt.assert_equal, user_ns['x'], [1,2,3])
286 yield (nt.assert_equal, user_ns['y'], [1,4,9])
287
288 finally:
289 # Restore original hook
290 hooks.clipboard_get = original_clip
General Comments 0
You need to be logged in to leave comments. Login now