##// END OF EJS Templates
Massive amount of work to improve the test suite, restores doctests....
Fernando Perez -
Show More
@@ -0,0 +1,185 b''
1 """Tests for code execution (%run and related), which is particularly tricky.
2
3 Because of how %run manages namespaces, and the fact that we are trying here to
4 verify subtle object deletion and reference counting issues, the %run tests
5 will be kept in this separate file. This makes it easier to aggregate in one
6 place the tricks needed to handle it; most other magics are much easier to test
7 and we do so in a common test_magic file.
8 """
9 from __future__ import absolute_import
10
11 #-----------------------------------------------------------------------------
12 # Imports
13 #-----------------------------------------------------------------------------
14
15 # stdlib
16 import os
17 import sys
18 import tempfile
19
20 # third-party
21 import nose.tools as nt
22
23 # our own
24 from IPython.utils.platutils import find_cmd
25 from IPython.utils import genutils
26 from IPython.testing import decorators as dec
27 from IPython.testing import tools as tt
28
29 #-----------------------------------------------------------------------------
30 # Test functions begin
31 #-----------------------------------------------------------------------------
32
33 def doctest_refbug():
34 """Very nasty problem with references held by multiple runs of a script.
35 See: https://bugs.launchpad.net/ipython/+bug/269966
36
37 In [1]: _ip.clear_main_mod_cache()
38 # random
39
40 In [2]: %run refbug
41
42 In [3]: call_f()
43 lowercased: hello
44
45 In [4]: %run refbug
46
47 In [5]: call_f()
48 lowercased: hello
49 lowercased: hello
50 """
51
52
53 def doctest_run_builtins():
54 r"""Check that %run doesn't damage __builtins__.
55
56 In [1]: import tempfile
57
58 In [2]: bid1 = id(__builtins__)
59
60 In [3]: fname = tempfile.mkstemp('.py')[1]
61
62 In [3]: f = open(fname,'w')
63
64 In [4]: f.write('pass\n')
65
66 In [5]: f.flush()
67
68 In [6]: t1 = type(__builtins__)
69
70 In [7]: %run "$fname"
71
72 In [7]: f.close()
73
74 In [8]: bid2 = id(__builtins__)
75
76 In [9]: t2 = type(__builtins__)
77
78 In [10]: t1 == t2
79 Out[10]: True
80
81 In [10]: bid1 == bid2
82 Out[10]: True
83
84 In [12]: try:
85 ....: os.unlink(fname)
86 ....: except:
87 ....: pass
88 ....:
89 """
90
91 # For some tests, it will be handy to organize them in a class with a common
92 # setup that makes a temp file
93
94 class TempFileMixin(object):
95 def mktmp(self, src, ext='.py'):
96 """Make a valid python temp file."""
97 fname, f = tt.temp_pyfile(src, ext)
98 self.tmpfile = f
99 self.fname = fname
100
101 def teardown(self):
102 self.tmpfile.close()
103 try:
104 os.unlink(self.fname)
105 except:
106 # On Windows, even though we close the file, we still can't delete
107 # it. I have no clue why
108 pass
109
110
111 class TestMagicRunPass(TempFileMixin):
112
113 def setup(self):
114 """Make a valid python temp file."""
115 self.mktmp('pass\n')
116
117 def run_tmpfile(self):
118 _ip = get_ipython()
119 # This fails on Windows if self.tmpfile.name has spaces or "~" in it.
120 # See below and ticket https://bugs.launchpad.net/bugs/366353
121 _ip.magic('run "%s"' % self.fname)
122
123 def test_builtins_id(self):
124 """Check that %run doesn't damage __builtins__ """
125 _ip = get_ipython()
126 # Test that the id of __builtins__ is not modified by %run
127 bid1 = id(_ip.user_ns['__builtins__'])
128 self.run_tmpfile()
129 bid2 = id(_ip.user_ns['__builtins__'])
130 tt.assert_equals(bid1, bid2)
131
132 def test_builtins_type(self):
133 """Check that the type of __builtins__ doesn't change with %run.
134
135 However, the above could pass if __builtins__ was already modified to
136 be a dict (it should be a module) by a previous use of %run. So we
137 also check explicitly that it really is a module:
138 """
139 _ip = get_ipython()
140 self.run_tmpfile()
141 tt.assert_equals(type(_ip.user_ns['__builtins__']),type(sys))
142
143 def test_prompts(self):
144 """Test that prompts correctly generate after %run"""
145 self.run_tmpfile()
146 _ip = get_ipython()
147 p2 = str(_ip.outputcache.prompt2).strip()
148 nt.assert_equals(p2[:3], '...')
149
150
151 class TestMagicRunSimple(TempFileMixin):
152
153 def test_simpledef(self):
154 """Test that simple class definitions work."""
155 src = ("class foo: pass\n"
156 "def f(): return foo()")
157 self.mktmp(src)
158 _ip.magic('run "%s"' % self.fname)
159 _ip.runlines('t = isinstance(f(), foo)')
160 nt.assert_true(_ip.user_ns['t'])
161
162 def test_obj_del(self):
163 """Test that object's __del__ methods are called on exit."""
164
165 # This test is known to fail on win32.
166 # See ticket https://bugs.launchpad.net/bugs/366334
167 src = ("class A(object):\n"
168 " def __del__(self):\n"
169 " print 'object A deleted'\n"
170 "a = A()\n")
171 self.mktmp(src)
172 tt.ipexec_validate(self.fname, 'object A deleted')
173
174 def test_tclass(self):
175 mydir = os.path.dirname(__file__)
176 tc = os.path.join(mydir, 'tclass')
177 src = ("%%run '%s' C-first\n"
178 "%%run '%s' C-second\n") % (tc, tc)
179 self.mktmp(src, '.ipy')
180 out = """\
181 ARGV 1-: ['C-first']
182 ARGV 1-: ['C-second']
183 tclass.py: deleting object: C-first
184 """
185 tt.ipexec_validate(self.fname, out)
@@ -1,3611 +1,3612 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 shutil
25 25 import re
26 26 import tempfile
27 27 import time
28 28 import cPickle as pickle
29 29 import textwrap
30 30 from cStringIO import StringIO
31 31 from getopt import getopt,GetoptError
32 32 from pprint import pprint, pformat
33 33
34 34 # cProfile was added in Python2.5
35 35 try:
36 36 import cProfile as profile
37 37 import pstats
38 38 except ImportError:
39 39 # profile isn't bundled by default in Debian for license reasons
40 40 try:
41 41 import profile,pstats
42 42 except ImportError:
43 43 profile = pstats = None
44 44
45 45 # Homebrewed
46 46 import IPython
47 47 import IPython.utils.generics
48 48
49 49 from IPython.core import debugger, oinspect
50 50 from IPython.core.error import TryNext
51 51 from IPython.core.error import UsageError
52 52 from IPython.core.fakemodule import FakeModule
53 53 from IPython.core.macro import Macro
54 54 from IPython.core.page import page
55 55 from IPython.core.prefilter import ESC_MAGIC
56 56 from IPython.core.pylabtools import mpl_runner
57 57 from IPython.lib.inputhook import enable_gui
58 58 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
59 59 from IPython.testing import decorators as testdec
60 60 from IPython.utils import platutils
61 61 from IPython.utils import wildcard
62 62 from IPython.utils.PyColorize import Parser
63 63 from IPython.utils.ipstruct import Struct
64 64
65 65 # XXX - We need to switch to explicit imports here with genutils
66 66 from IPython.utils.genutils import *
67 67
68 68 #***************************************************************************
69 69 # Utility functions
70 70 def on_off(tag):
71 71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
72 72 return ['OFF','ON'][tag]
73 73
74 74 class Bunch: pass
75 75
76 76 def compress_dhist(dh):
77 77 head, tail = dh[:-10], dh[-10:]
78 78
79 79 newhead = []
80 80 done = set()
81 81 for h in head:
82 82 if h in done:
83 83 continue
84 84 newhead.append(h)
85 85 done.add(h)
86 86
87 87 return newhead + tail
88 88
89 89
90 90 #***************************************************************************
91 91 # Main class implementing Magic functionality
92 92
93 93 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
94 94 # on construction of the main InteractiveShell object. Something odd is going
95 95 # on with super() calls, Component and the MRO... For now leave it as-is, but
96 96 # eventually this needs to be clarified.
97 97
98 98 class Magic:
99 99 """Magic functions for InteractiveShell.
100 100
101 101 Shell functions which can be reached as %function_name. All magic
102 102 functions should accept a string, which they can parse for their own
103 103 needs. This can make some functions easier to type, eg `%cd ../`
104 104 vs. `%cd("../")`
105 105
106 106 ALL definitions MUST begin with the prefix magic_. The user won't need it
107 107 at the command line, but it is is needed in the definition. """
108 108
109 109 # class globals
110 110 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
111 111 'Automagic is ON, % prefix NOT needed for magic functions.']
112 112
113 113 #......................................................................
114 114 # some utility functions
115 115
116 116 def __init__(self,shell):
117 117
118 118 self.options_table = {}
119 119 if profile is None:
120 120 self.magic_prun = self.profile_missing_notice
121 121 self.shell = shell
122 122
123 123 # namespace for holding state we may need
124 124 self._magic_state = Bunch()
125 125
126 126 def profile_missing_notice(self, *args, **kwargs):
127 127 error("""\
128 128 The profile module could not be found. It has been removed from the standard
129 129 python packages because of its non-free license. To use profiling, install the
130 130 python-profiler package from non-free.""")
131 131
132 132 def default_option(self,fn,optstr):
133 133 """Make an entry in the options_table for fn, with value optstr"""
134 134
135 135 if fn not in self.lsmagic():
136 136 error("%s is not a magic function" % fn)
137 137 self.options_table[fn] = optstr
138 138
139 139 def lsmagic(self):
140 140 """Return a list of currently available magic functions.
141 141
142 142 Gives a list of the bare names after mangling (['ls','cd', ...], not
143 143 ['magic_ls','magic_cd',...]"""
144 144
145 145 # FIXME. This needs a cleanup, in the way the magics list is built.
146 146
147 147 # magics in class definition
148 148 class_magic = lambda fn: fn.startswith('magic_') and \
149 149 callable(Magic.__dict__[fn])
150 150 # in instance namespace (run-time user additions)
151 151 inst_magic = lambda fn: fn.startswith('magic_') and \
152 152 callable(self.__dict__[fn])
153 153 # and bound magics by user (so they can access self):
154 154 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
155 155 callable(self.__class__.__dict__[fn])
156 156 magics = filter(class_magic,Magic.__dict__.keys()) + \
157 157 filter(inst_magic,self.__dict__.keys()) + \
158 158 filter(inst_bound_magic,self.__class__.__dict__.keys())
159 159 out = []
160 160 for fn in set(magics):
161 161 out.append(fn.replace('magic_','',1))
162 162 out.sort()
163 163 return out
164 164
165 165 def extract_input_slices(self,slices,raw=False):
166 166 """Return as a string a set of input history slices.
167 167
168 168 Inputs:
169 169
170 170 - slices: the set of slices is given as a list of strings (like
171 171 ['1','4:8','9'], since this function is for use by magic functions
172 172 which get their arguments as strings.
173 173
174 174 Optional inputs:
175 175
176 176 - raw(False): by default, the processed input is used. If this is
177 177 true, the raw input history is used instead.
178 178
179 179 Note that slices can be called with two notations:
180 180
181 181 N:M -> standard python form, means including items N...(M-1).
182 182
183 183 N-M -> include items N..M (closed endpoint)."""
184 184
185 185 if raw:
186 186 hist = self.shell.input_hist_raw
187 187 else:
188 188 hist = self.shell.input_hist
189 189
190 190 cmds = []
191 191 for chunk in slices:
192 192 if ':' in chunk:
193 193 ini,fin = map(int,chunk.split(':'))
194 194 elif '-' in chunk:
195 195 ini,fin = map(int,chunk.split('-'))
196 196 fin += 1
197 197 else:
198 198 ini = int(chunk)
199 199 fin = ini+1
200 200 cmds.append(hist[ini:fin])
201 201 return cmds
202 202
203 203 def _ofind(self, oname, namespaces=None):
204 204 """Find an object in the available namespaces.
205 205
206 206 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
207 207
208 208 Has special code to detect magic functions.
209 209 """
210 210
211 211 oname = oname.strip()
212 212
213 213 alias_ns = None
214 214 if namespaces is None:
215 215 # Namespaces to search in:
216 216 # Put them in a list. The order is important so that we
217 217 # find things in the same order that Python finds them.
218 218 namespaces = [ ('Interactive', self.shell.user_ns),
219 219 ('IPython internal', self.shell.internal_ns),
220 220 ('Python builtin', __builtin__.__dict__),
221 221 ('Alias', self.shell.alias_manager.alias_table),
222 222 ]
223 223 alias_ns = self.shell.alias_manager.alias_table
224 224
225 225 # initialize results to 'null'
226 226 found = 0; obj = None; ospace = None; ds = None;
227 227 ismagic = 0; isalias = 0; parent = None
228 228
229 229 # Look for the given name by splitting it in parts. If the head is
230 230 # found, then we look for all the remaining parts as members, and only
231 231 # declare success if we can find them all.
232 232 oname_parts = oname.split('.')
233 233 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
234 234 for nsname,ns in namespaces:
235 235 try:
236 236 obj = ns[oname_head]
237 237 except KeyError:
238 238 continue
239 239 else:
240 240 #print 'oname_rest:', oname_rest # dbg
241 241 for part in oname_rest:
242 242 try:
243 243 parent = obj
244 244 obj = getattr(obj,part)
245 245 except:
246 246 # Blanket except b/c some badly implemented objects
247 247 # allow __getattr__ to raise exceptions other than
248 248 # AttributeError, which then crashes IPython.
249 249 break
250 250 else:
251 251 # If we finish the for loop (no break), we got all members
252 252 found = 1
253 253 ospace = nsname
254 254 if ns == alias_ns:
255 255 isalias = 1
256 256 break # namespace loop
257 257
258 258 # Try to see if it's magic
259 259 if not found:
260 260 if oname.startswith(ESC_MAGIC):
261 261 oname = oname[1:]
262 262 obj = getattr(self,'magic_'+oname,None)
263 263 if obj is not None:
264 264 found = 1
265 265 ospace = 'IPython internal'
266 266 ismagic = 1
267 267
268 268 # Last try: special-case some literals like '', [], {}, etc:
269 269 if not found and oname_head in ["''",'""','[]','{}','()']:
270 270 obj = eval(oname_head)
271 271 found = 1
272 272 ospace = 'Interactive'
273 273
274 274 return {'found':found, 'obj':obj, 'namespace':ospace,
275 275 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
276 276
277 277 def arg_err(self,func):
278 278 """Print docstring if incorrect arguments were passed"""
279 279 print 'Error in arguments:'
280 280 print OInspect.getdoc(func)
281 281
282 282 def format_latex(self,strng):
283 283 """Format a string for latex inclusion."""
284 284
285 285 # Characters that need to be escaped for latex:
286 286 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
287 287 # Magic command names as headers:
288 288 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
289 289 re.MULTILINE)
290 290 # Magic commands
291 291 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
292 292 re.MULTILINE)
293 293 # Paragraph continue
294 294 par_re = re.compile(r'\\$',re.MULTILINE)
295 295
296 296 # The "\n" symbol
297 297 newline_re = re.compile(r'\\n')
298 298
299 299 # Now build the string for output:
300 300 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
301 301 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
302 302 strng)
303 303 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
304 304 strng = par_re.sub(r'\\\\',strng)
305 305 strng = escape_re.sub(r'\\\1',strng)
306 306 strng = newline_re.sub(r'\\textbackslash{}n',strng)
307 307 return strng
308 308
309 309 def format_screen(self,strng):
310 310 """Format a string for screen printing.
311 311
312 312 This removes some latex-type format codes."""
313 313 # Paragraph continue
314 314 par_re = re.compile(r'\\$',re.MULTILINE)
315 315 strng = par_re.sub('',strng)
316 316 return strng
317 317
318 318 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
319 319 """Parse options passed to an argument string.
320 320
321 321 The interface is similar to that of getopt(), but it returns back a
322 322 Struct with the options as keys and the stripped argument string still
323 323 as a string.
324 324
325 325 arg_str is quoted as a true sys.argv vector by using shlex.split.
326 326 This allows us to easily expand variables, glob files, quote
327 327 arguments, etc.
328 328
329 329 Options:
330 330 -mode: default 'string'. If given as 'list', the argument string is
331 331 returned as a list (split on whitespace) instead of a string.
332 332
333 333 -list_all: put all option values in lists. Normally only options
334 334 appearing more than once are put in a list.
335 335
336 336 -posix (True): whether to split the input line in POSIX mode or not,
337 337 as per the conventions outlined in the shlex module from the
338 338 standard library."""
339 339
340 340 # inject default options at the beginning of the input line
341 341 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
342 342 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
343 343
344 344 mode = kw.get('mode','string')
345 345 if mode not in ['string','list']:
346 346 raise ValueError,'incorrect mode given: %s' % mode
347 347 # Get options
348 348 list_all = kw.get('list_all',0)
349 349 posix = kw.get('posix',True)
350 350
351 351 # Check if we have more than one argument to warrant extra processing:
352 352 odict = {} # Dictionary with options
353 353 args = arg_str.split()
354 354 if len(args) >= 1:
355 355 # If the list of inputs only has 0 or 1 thing in it, there's no
356 356 # need to look for options
357 357 argv = arg_split(arg_str,posix)
358 358 # Do regular option processing
359 359 try:
360 360 opts,args = getopt(argv,opt_str,*long_opts)
361 361 except GetoptError,e:
362 362 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
363 363 " ".join(long_opts)))
364 364 for o,a in opts:
365 365 if o.startswith('--'):
366 366 o = o[2:]
367 367 else:
368 368 o = o[1:]
369 369 try:
370 370 odict[o].append(a)
371 371 except AttributeError:
372 372 odict[o] = [odict[o],a]
373 373 except KeyError:
374 374 if list_all:
375 375 odict[o] = [a]
376 376 else:
377 377 odict[o] = a
378 378
379 379 # Prepare opts,args for return
380 380 opts = Struct(odict)
381 381 if mode == 'string':
382 382 args = ' '.join(args)
383 383
384 384 return opts,args
385 385
386 386 #......................................................................
387 387 # And now the actual magic functions
388 388
389 389 # Functions for IPython shell work (vars,funcs, config, etc)
390 390 def magic_lsmagic(self, parameter_s = ''):
391 391 """List currently available magic functions."""
392 392 mesc = ESC_MAGIC
393 393 print 'Available magic functions:\n'+mesc+\
394 394 (' '+mesc).join(self.lsmagic())
395 395 print '\n' + Magic.auto_status[self.shell.automagic]
396 396 return None
397 397
398 398 def magic_magic(self, parameter_s = ''):
399 399 """Print information about the magic function system.
400 400
401 401 Supported formats: -latex, -brief, -rest
402 402 """
403 403
404 404 mode = ''
405 405 try:
406 406 if parameter_s.split()[0] == '-latex':
407 407 mode = 'latex'
408 408 if parameter_s.split()[0] == '-brief':
409 409 mode = 'brief'
410 410 if parameter_s.split()[0] == '-rest':
411 411 mode = 'rest'
412 412 rest_docs = []
413 413 except:
414 414 pass
415 415
416 416 magic_docs = []
417 417 for fname in self.lsmagic():
418 418 mname = 'magic_' + fname
419 419 for space in (Magic,self,self.__class__):
420 420 try:
421 421 fn = space.__dict__[mname]
422 422 except KeyError:
423 423 pass
424 424 else:
425 425 break
426 426 if mode == 'brief':
427 427 # only first line
428 428 if fn.__doc__:
429 429 fndoc = fn.__doc__.split('\n',1)[0]
430 430 else:
431 431 fndoc = 'No documentation'
432 432 else:
433 433 if fn.__doc__:
434 434 fndoc = fn.__doc__.rstrip()
435 435 else:
436 436 fndoc = 'No documentation'
437 437
438 438
439 439 if mode == 'rest':
440 440 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
441 441 fname,fndoc))
442 442
443 443 else:
444 444 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
445 445 fname,fndoc))
446 446
447 447 magic_docs = ''.join(magic_docs)
448 448
449 449 if mode == 'rest':
450 450 return "".join(rest_docs)
451 451
452 452 if mode == 'latex':
453 453 print self.format_latex(magic_docs)
454 454 return
455 455 else:
456 456 magic_docs = self.format_screen(magic_docs)
457 457 if mode == 'brief':
458 458 return magic_docs
459 459
460 460 outmsg = """
461 461 IPython's 'magic' functions
462 462 ===========================
463 463
464 464 The magic function system provides a series of functions which allow you to
465 465 control the behavior of IPython itself, plus a lot of system-type
466 466 features. All these functions are prefixed with a % character, but parameters
467 467 are given without parentheses or quotes.
468 468
469 469 NOTE: If you have 'automagic' enabled (via the command line option or with the
470 470 %automagic function), you don't need to type in the % explicitly. By default,
471 471 IPython ships with automagic on, so you should only rarely need the % escape.
472 472
473 473 Example: typing '%cd mydir' (without the quotes) changes you working directory
474 474 to 'mydir', if it exists.
475 475
476 476 You can define your own magic functions to extend the system. See the supplied
477 477 ipythonrc and example-magic.py files for details (in your ipython
478 478 configuration directory, typically $HOME/.ipython/).
479 479
480 480 You can also define your own aliased names for magic functions. In your
481 481 ipythonrc file, placing a line like:
482 482
483 483 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
484 484
485 485 will define %pf as a new name for %profile.
486 486
487 487 You can also call magics in code using the magic() function, which IPython
488 488 automatically adds to the builtin namespace. Type 'magic?' for details.
489 489
490 490 For a list of the available magic functions, use %lsmagic. For a description
491 491 of any of them, type %magic_name?, e.g. '%cd?'.
492 492
493 493 Currently the magic system has the following functions:\n"""
494 494
495 495 mesc = ESC_MAGIC
496 496 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
497 497 "\n\n%s%s\n\n%s" % (outmsg,
498 498 magic_docs,mesc,mesc,
499 499 (' '+mesc).join(self.lsmagic()),
500 500 Magic.auto_status[self.shell.automagic] ) )
501 501
502 502 page(outmsg,screen_lines=self.shell.usable_screen_length)
503 503
504 504
505 505 def magic_autoindent(self, parameter_s = ''):
506 506 """Toggle autoindent on/off (if available)."""
507 507
508 508 self.shell.set_autoindent()
509 509 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
510 510
511 511
512 512 def magic_automagic(self, parameter_s = ''):
513 513 """Make magic functions callable without having to type the initial %.
514 514
515 515 Without argumentsl toggles on/off (when off, you must call it as
516 516 %automagic, of course). With arguments it sets the value, and you can
517 517 use any of (case insensitive):
518 518
519 519 - on,1,True: to activate
520 520
521 521 - off,0,False: to deactivate.
522 522
523 523 Note that magic functions have lowest priority, so if there's a
524 524 variable whose name collides with that of a magic fn, automagic won't
525 525 work for that function (you get the variable instead). However, if you
526 526 delete the variable (del var), the previously shadowed magic function
527 527 becomes visible to automagic again."""
528 528
529 529 arg = parameter_s.lower()
530 530 if parameter_s in ('on','1','true'):
531 531 self.shell.automagic = True
532 532 elif parameter_s in ('off','0','false'):
533 533 self.shell.automagic = False
534 534 else:
535 535 self.shell.automagic = not self.shell.automagic
536 536 print '\n' + Magic.auto_status[self.shell.automagic]
537 537
538 538 @testdec.skip_doctest
539 539 def magic_autocall(self, parameter_s = ''):
540 540 """Make functions callable without having to type parentheses.
541 541
542 542 Usage:
543 543
544 544 %autocall [mode]
545 545
546 546 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
547 547 value is toggled on and off (remembering the previous state).
548 548
549 549 In more detail, these values mean:
550 550
551 551 0 -> fully disabled
552 552
553 553 1 -> active, but do not apply if there are no arguments on the line.
554 554
555 555 In this mode, you get:
556 556
557 557 In [1]: callable
558 558 Out[1]: <built-in function callable>
559 559
560 560 In [2]: callable 'hello'
561 561 ------> callable('hello')
562 562 Out[2]: False
563 563
564 564 2 -> Active always. Even if no arguments are present, the callable
565 565 object is called:
566 566
567 567 In [2]: float
568 568 ------> float()
569 569 Out[2]: 0.0
570 570
571 571 Note that even with autocall off, you can still use '/' at the start of
572 572 a line to treat the first argument on the command line as a function
573 573 and add parentheses to it:
574 574
575 575 In [8]: /str 43
576 576 ------> str(43)
577 577 Out[8]: '43'
578 578
579 579 # all-random (note for auto-testing)
580 580 """
581 581
582 582 if parameter_s:
583 583 arg = int(parameter_s)
584 584 else:
585 585 arg = 'toggle'
586 586
587 587 if not arg in (0,1,2,'toggle'):
588 588 error('Valid modes: (0->Off, 1->Smart, 2->Full')
589 589 return
590 590
591 591 if arg in (0,1,2):
592 592 self.shell.autocall = arg
593 593 else: # toggle
594 594 if self.shell.autocall:
595 595 self._magic_state.autocall_save = self.shell.autocall
596 596 self.shell.autocall = 0
597 597 else:
598 598 try:
599 599 self.shell.autocall = self._magic_state.autocall_save
600 600 except AttributeError:
601 601 self.shell.autocall = self._magic_state.autocall_save = 1
602 602
603 603 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
604 604
605 605 def magic_system_verbose(self, parameter_s = ''):
606 606 """Set verbose printing of system calls.
607 607
608 608 If called without an argument, act as a toggle"""
609 609
610 610 if parameter_s:
611 611 val = bool(eval(parameter_s))
612 612 else:
613 613 val = None
614 614
615 615 if self.shell.system_verbose:
616 616 self.shell.system_verbose = False
617 617 else:
618 618 self.shell.system_verbose = True
619 619 print "System verbose printing is:",\
620 620 ['OFF','ON'][self.shell.system_verbose]
621 621
622 622
623 623 def magic_page(self, parameter_s=''):
624 624 """Pretty print the object and display it through a pager.
625 625
626 626 %page [options] OBJECT
627 627
628 628 If no object is given, use _ (last output).
629 629
630 630 Options:
631 631
632 632 -r: page str(object), don't pretty-print it."""
633 633
634 634 # After a function contributed by Olivier Aubert, slightly modified.
635 635
636 636 # Process options/args
637 637 opts,args = self.parse_options(parameter_s,'r')
638 638 raw = 'r' in opts
639 639
640 640 oname = args and args or '_'
641 641 info = self._ofind(oname)
642 642 if info['found']:
643 643 txt = (raw and str or pformat)( info['obj'] )
644 644 page(txt)
645 645 else:
646 646 print 'Object `%s` not found' % oname
647 647
648 648 def magic_profile(self, parameter_s=''):
649 649 """Print your currently active IPyhton profile."""
650 650 if self.shell.profile:
651 651 printpl('Current IPython profile: $self.shell.profile.')
652 652 else:
653 653 print 'No profile active.'
654 654
655 655 def magic_pinfo(self, parameter_s='', namespaces=None):
656 656 """Provide detailed information about an object.
657 657
658 658 '%pinfo object' is just a synonym for object? or ?object."""
659 659
660 660 #print 'pinfo par: <%s>' % parameter_s # dbg
661 661
662 662
663 663 # detail_level: 0 -> obj? , 1 -> obj??
664 664 detail_level = 0
665 665 # We need to detect if we got called as 'pinfo pinfo foo', which can
666 666 # happen if the user types 'pinfo foo?' at the cmd line.
667 667 pinfo,qmark1,oname,qmark2 = \
668 668 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
669 669 if pinfo or qmark1 or qmark2:
670 670 detail_level = 1
671 671 if "*" in oname:
672 672 self.magic_psearch(oname)
673 673 else:
674 674 self._inspect('pinfo', oname, detail_level=detail_level,
675 675 namespaces=namespaces)
676 676
677 677 def magic_pdef(self, parameter_s='', namespaces=None):
678 678 """Print the definition header for any callable object.
679 679
680 680 If the object is a class, print the constructor information."""
681 681 self._inspect('pdef',parameter_s, namespaces)
682 682
683 683 def magic_pdoc(self, parameter_s='', namespaces=None):
684 684 """Print the docstring for an object.
685 685
686 686 If the given object is a class, it will print both the class and the
687 687 constructor docstrings."""
688 688 self._inspect('pdoc',parameter_s, namespaces)
689 689
690 690 def magic_psource(self, parameter_s='', namespaces=None):
691 691 """Print (or run through pager) the source code for an object."""
692 692 self._inspect('psource',parameter_s, namespaces)
693 693
694 694 def magic_pfile(self, parameter_s=''):
695 695 """Print (or run through pager) the file where an object is defined.
696 696
697 697 The file opens at the line where the object definition begins. IPython
698 698 will honor the environment variable PAGER if set, and otherwise will
699 699 do its best to print the file in a convenient form.
700 700
701 701 If the given argument is not an object currently defined, IPython will
702 702 try to interpret it as a filename (automatically adding a .py extension
703 703 if needed). You can thus use %pfile as a syntax highlighting code
704 704 viewer."""
705 705
706 706 # first interpret argument as an object name
707 707 out = self._inspect('pfile',parameter_s)
708 708 # if not, try the input as a filename
709 709 if out == 'not found':
710 710 try:
711 711 filename = get_py_filename(parameter_s)
712 712 except IOError,msg:
713 713 print msg
714 714 return
715 715 page(self.shell.inspector.format(file(filename).read()))
716 716
717 717 def _inspect(self,meth,oname,namespaces=None,**kw):
718 718 """Generic interface to the inspector system.
719 719
720 720 This function is meant to be called by pdef, pdoc & friends."""
721 721
722 722 #oname = oname.strip()
723 723 #print '1- oname: <%r>' % oname # dbg
724 724 try:
725 725 oname = oname.strip().encode('ascii')
726 726 #print '2- oname: <%r>' % oname # dbg
727 727 except UnicodeEncodeError:
728 728 print 'Python identifiers can only contain ascii characters.'
729 729 return 'not found'
730 730
731 731 info = Struct(self._ofind(oname, namespaces))
732 732
733 733 if info.found:
734 734 try:
735 735 IPython.utils.generics.inspect_object(info.obj)
736 736 return
737 737 except TryNext:
738 738 pass
739 739 # Get the docstring of the class property if it exists.
740 740 path = oname.split('.')
741 741 root = '.'.join(path[:-1])
742 742 if info.parent is not None:
743 743 try:
744 744 target = getattr(info.parent, '__class__')
745 745 # The object belongs to a class instance.
746 746 try:
747 747 target = getattr(target, path[-1])
748 748 # The class defines the object.
749 749 if isinstance(target, property):
750 750 oname = root + '.__class__.' + path[-1]
751 751 info = Struct(self._ofind(oname))
752 752 except AttributeError: pass
753 753 except AttributeError: pass
754 754
755 755 pmethod = getattr(self.shell.inspector,meth)
756 756 formatter = info.ismagic and self.format_screen or None
757 757 if meth == 'pdoc':
758 758 pmethod(info.obj,oname,formatter)
759 759 elif meth == 'pinfo':
760 760 pmethod(info.obj,oname,formatter,info,**kw)
761 761 else:
762 762 pmethod(info.obj,oname)
763 763 else:
764 764 print 'Object `%s` not found.' % oname
765 765 return 'not found' # so callers can take other action
766 766
767 767 def magic_psearch(self, parameter_s=''):
768 768 """Search for object in namespaces by wildcard.
769 769
770 770 %psearch [options] PATTERN [OBJECT TYPE]
771 771
772 772 Note: ? can be used as a synonym for %psearch, at the beginning or at
773 773 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
774 774 rest of the command line must be unchanged (options come first), so
775 775 for example the following forms are equivalent
776 776
777 777 %psearch -i a* function
778 778 -i a* function?
779 779 ?-i a* function
780 780
781 781 Arguments:
782 782
783 783 PATTERN
784 784
785 785 where PATTERN is a string containing * as a wildcard similar to its
786 786 use in a shell. The pattern is matched in all namespaces on the
787 787 search path. By default objects starting with a single _ are not
788 788 matched, many IPython generated objects have a single
789 789 underscore. The default is case insensitive matching. Matching is
790 790 also done on the attributes of objects and not only on the objects
791 791 in a module.
792 792
793 793 [OBJECT TYPE]
794 794
795 795 Is the name of a python type from the types module. The name is
796 796 given in lowercase without the ending type, ex. StringType is
797 797 written string. By adding a type here only objects matching the
798 798 given type are matched. Using all here makes the pattern match all
799 799 types (this is the default).
800 800
801 801 Options:
802 802
803 803 -a: makes the pattern match even objects whose names start with a
804 804 single underscore. These names are normally ommitted from the
805 805 search.
806 806
807 807 -i/-c: make the pattern case insensitive/sensitive. If neither of
808 808 these options is given, the default is read from your ipythonrc
809 809 file. The option name which sets this value is
810 810 'wildcards_case_sensitive'. If this option is not specified in your
811 811 ipythonrc file, IPython's internal default is to do a case sensitive
812 812 search.
813 813
814 814 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
815 815 specifiy can be searched in any of the following namespaces:
816 816 'builtin', 'user', 'user_global','internal', 'alias', where
817 817 'builtin' and 'user' are the search defaults. Note that you should
818 818 not use quotes when specifying namespaces.
819 819
820 820 'Builtin' contains the python module builtin, 'user' contains all
821 821 user data, 'alias' only contain the shell aliases and no python
822 822 objects, 'internal' contains objects used by IPython. The
823 823 'user_global' namespace is only used by embedded IPython instances,
824 824 and it contains module-level globals. You can add namespaces to the
825 825 search with -s or exclude them with -e (these options can be given
826 826 more than once).
827 827
828 828 Examples:
829 829
830 830 %psearch a* -> objects beginning with an a
831 831 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
832 832 %psearch a* function -> all functions beginning with an a
833 833 %psearch re.e* -> objects beginning with an e in module re
834 834 %psearch r*.e* -> objects that start with e in modules starting in r
835 835 %psearch r*.* string -> all strings in modules beginning with r
836 836
837 837 Case sensitve search:
838 838
839 839 %psearch -c a* list all object beginning with lower case a
840 840
841 841 Show objects beginning with a single _:
842 842
843 843 %psearch -a _* list objects beginning with a single underscore"""
844 844 try:
845 845 parameter_s = parameter_s.encode('ascii')
846 846 except UnicodeEncodeError:
847 847 print 'Python identifiers can only contain ascii characters.'
848 848 return
849 849
850 850 # default namespaces to be searched
851 851 def_search = ['user','builtin']
852 852
853 853 # Process options/args
854 854 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
855 855 opt = opts.get
856 856 shell = self.shell
857 857 psearch = shell.inspector.psearch
858 858
859 859 # select case options
860 860 if opts.has_key('i'):
861 861 ignore_case = True
862 862 elif opts.has_key('c'):
863 863 ignore_case = False
864 864 else:
865 865 ignore_case = not shell.wildcards_case_sensitive
866 866
867 867 # Build list of namespaces to search from user options
868 868 def_search.extend(opt('s',[]))
869 869 ns_exclude = ns_exclude=opt('e',[])
870 870 ns_search = [nm for nm in def_search if nm not in ns_exclude]
871 871
872 872 # Call the actual search
873 873 try:
874 874 psearch(args,shell.ns_table,ns_search,
875 875 show_all=opt('a'),ignore_case=ignore_case)
876 876 except:
877 877 shell.showtraceback()
878 878
879 879 def magic_who_ls(self, parameter_s=''):
880 880 """Return a sorted list of all interactive variables.
881 881
882 882 If arguments are given, only variables of types matching these
883 883 arguments are returned."""
884 884
885 885 user_ns = self.shell.user_ns
886 886 internal_ns = self.shell.internal_ns
887 887 user_config_ns = self.shell.user_config_ns
888 888 out = [ i for i in user_ns
889 889 if not i.startswith('_') \
890 890 and not (i in internal_ns or i in user_config_ns) ]
891 891
892 892 typelist = parameter_s.split()
893 893 if typelist:
894 894 typeset = set(typelist)
895 895 out = [i for i in out if type(i).__name__ in typeset]
896 896
897 897 out.sort()
898 898 return out
899 899
900 900 def magic_who(self, parameter_s=''):
901 901 """Print all interactive variables, with some minimal formatting.
902 902
903 903 If any arguments are given, only variables whose type matches one of
904 904 these are printed. For example:
905 905
906 906 %who function str
907 907
908 908 will only list functions and strings, excluding all other types of
909 909 variables. To find the proper type names, simply use type(var) at a
910 910 command line to see how python prints type names. For example:
911 911
912 912 In [1]: type('hello')\\
913 913 Out[1]: <type 'str'>
914 914
915 915 indicates that the type name for strings is 'str'.
916 916
917 917 %who always excludes executed names loaded through your configuration
918 918 file and things which are internal to IPython.
919 919
920 920 This is deliberate, as typically you may load many modules and the
921 921 purpose of %who is to show you only what you've manually defined."""
922 922
923 923 varlist = self.magic_who_ls(parameter_s)
924 924 if not varlist:
925 925 if parameter_s:
926 926 print 'No variables match your requested type.'
927 927 else:
928 928 print 'Interactive namespace is empty.'
929 929 return
930 930
931 931 # if we have variables, move on...
932 932 count = 0
933 933 for i in varlist:
934 934 print i+'\t',
935 935 count += 1
936 936 if count > 8:
937 937 count = 0
938 938 print
939 939 print
940 940
941 941 def magic_whos(self, parameter_s=''):
942 942 """Like %who, but gives some extra information about each variable.
943 943
944 944 The same type filtering of %who can be applied here.
945 945
946 946 For all variables, the type is printed. Additionally it prints:
947 947
948 948 - For {},[],(): their length.
949 949
950 950 - For numpy and Numeric arrays, a summary with shape, number of
951 951 elements, typecode and size in memory.
952 952
953 953 - Everything else: a string representation, snipping their middle if
954 954 too long."""
955 955
956 956 varnames = self.magic_who_ls(parameter_s)
957 957 if not varnames:
958 958 if parameter_s:
959 959 print 'No variables match your requested type.'
960 960 else:
961 961 print 'Interactive namespace is empty.'
962 962 return
963 963
964 964 # if we have variables, move on...
965 965
966 966 # for these types, show len() instead of data:
967 967 seq_types = [types.DictType,types.ListType,types.TupleType]
968 968
969 969 # for numpy/Numeric arrays, display summary info
970 970 try:
971 971 import numpy
972 972 except ImportError:
973 973 ndarray_type = None
974 974 else:
975 975 ndarray_type = numpy.ndarray.__name__
976 976 try:
977 977 import Numeric
978 978 except ImportError:
979 979 array_type = None
980 980 else:
981 981 array_type = Numeric.ArrayType.__name__
982 982
983 983 # Find all variable names and types so we can figure out column sizes
984 984 def get_vars(i):
985 985 return self.shell.user_ns[i]
986 986
987 987 # some types are well known and can be shorter
988 988 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
989 989 def type_name(v):
990 990 tn = type(v).__name__
991 991 return abbrevs.get(tn,tn)
992 992
993 993 varlist = map(get_vars,varnames)
994 994
995 995 typelist = []
996 996 for vv in varlist:
997 997 tt = type_name(vv)
998 998
999 999 if tt=='instance':
1000 1000 typelist.append( abbrevs.get(str(vv.__class__),
1001 1001 str(vv.__class__)))
1002 1002 else:
1003 1003 typelist.append(tt)
1004 1004
1005 1005 # column labels and # of spaces as separator
1006 1006 varlabel = 'Variable'
1007 1007 typelabel = 'Type'
1008 1008 datalabel = 'Data/Info'
1009 1009 colsep = 3
1010 1010 # variable format strings
1011 1011 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1012 1012 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1013 1013 aformat = "%s: %s elems, type `%s`, %s bytes"
1014 1014 # find the size of the columns to format the output nicely
1015 1015 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1016 1016 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1017 1017 # table header
1018 1018 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1019 1019 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1020 1020 # and the table itself
1021 1021 kb = 1024
1022 1022 Mb = 1048576 # kb**2
1023 1023 for vname,var,vtype in zip(varnames,varlist,typelist):
1024 1024 print itpl(vformat),
1025 1025 if vtype in seq_types:
1026 1026 print len(var)
1027 1027 elif vtype in [array_type,ndarray_type]:
1028 1028 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1029 1029 if vtype==ndarray_type:
1030 1030 # numpy
1031 1031 vsize = var.size
1032 1032 vbytes = vsize*var.itemsize
1033 1033 vdtype = var.dtype
1034 1034 else:
1035 1035 # Numeric
1036 1036 vsize = Numeric.size(var)
1037 1037 vbytes = vsize*var.itemsize()
1038 1038 vdtype = var.typecode()
1039 1039
1040 1040 if vbytes < 100000:
1041 1041 print aformat % (vshape,vsize,vdtype,vbytes)
1042 1042 else:
1043 1043 print aformat % (vshape,vsize,vdtype,vbytes),
1044 1044 if vbytes < Mb:
1045 1045 print '(%s kb)' % (vbytes/kb,)
1046 1046 else:
1047 1047 print '(%s Mb)' % (vbytes/Mb,)
1048 1048 else:
1049 1049 try:
1050 1050 vstr = str(var)
1051 1051 except UnicodeEncodeError:
1052 1052 vstr = unicode(var).encode(sys.getdefaultencoding(),
1053 1053 'backslashreplace')
1054 1054 vstr = vstr.replace('\n','\\n')
1055 1055 if len(vstr) < 50:
1056 1056 print vstr
1057 1057 else:
1058 1058 printpl(vfmt_short)
1059 1059
1060 1060 def magic_reset(self, parameter_s=''):
1061 1061 """Resets the namespace by removing all names defined by the user.
1062 1062
1063 1063 Input/Output history are left around in case you need them.
1064 1064
1065 1065 Parameters
1066 1066 ----------
1067 1067 -y : force reset without asking for confirmation.
1068 1068
1069 1069 Examples
1070 1070 --------
1071 1071 In [6]: a = 1
1072 1072
1073 1073 In [7]: a
1074 1074 Out[7]: 1
1075 1075
1076 1076 In [8]: 'a' in _ip.user_ns
1077 1077 Out[8]: True
1078 1078
1079 1079 In [9]: %reset -f
1080 1080
1081 1081 In [10]: 'a' in _ip.user_ns
1082 1082 Out[10]: False
1083 1083 """
1084 1084
1085 1085 if parameter_s == '-f':
1086 1086 ans = True
1087 1087 else:
1088 1088 ans = self.shell.ask_yes_no(
1089 1089 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1090 1090 if not ans:
1091 1091 print 'Nothing done.'
1092 1092 return
1093 1093 user_ns = self.shell.user_ns
1094 1094 for i in self.magic_who_ls():
1095 1095 del(user_ns[i])
1096 1096
1097 1097 # Also flush the private list of module references kept for script
1098 1098 # execution protection
1099 1099 self.shell.clear_main_mod_cache()
1100 1100
1101 1101 def magic_logstart(self,parameter_s=''):
1102 1102 """Start logging anywhere in a session.
1103 1103
1104 1104 %logstart [-o|-r|-t] [log_name [log_mode]]
1105 1105
1106 1106 If no name is given, it defaults to a file named 'ipython_log.py' in your
1107 1107 current directory, in 'rotate' mode (see below).
1108 1108
1109 1109 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1110 1110 history up to that point and then continues logging.
1111 1111
1112 1112 %logstart takes a second optional parameter: logging mode. This can be one
1113 1113 of (note that the modes are given unquoted):\\
1114 1114 append: well, that says it.\\
1115 1115 backup: rename (if exists) to name~ and start name.\\
1116 1116 global: single logfile in your home dir, appended to.\\
1117 1117 over : overwrite existing log.\\
1118 1118 rotate: create rotating logs name.1~, name.2~, etc.
1119 1119
1120 1120 Options:
1121 1121
1122 1122 -o: log also IPython's output. In this mode, all commands which
1123 1123 generate an Out[NN] prompt are recorded to the logfile, right after
1124 1124 their corresponding input line. The output lines are always
1125 1125 prepended with a '#[Out]# ' marker, so that the log remains valid
1126 1126 Python code.
1127 1127
1128 1128 Since this marker is always the same, filtering only the output from
1129 1129 a log is very easy, using for example a simple awk call:
1130 1130
1131 1131 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1132 1132
1133 1133 -r: log 'raw' input. Normally, IPython's logs contain the processed
1134 1134 input, so that user lines are logged in their final form, converted
1135 1135 into valid Python. For example, %Exit is logged as
1136 1136 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1137 1137 exactly as typed, with no transformations applied.
1138 1138
1139 1139 -t: put timestamps before each input line logged (these are put in
1140 1140 comments)."""
1141 1141
1142 1142 opts,par = self.parse_options(parameter_s,'ort')
1143 1143 log_output = 'o' in opts
1144 1144 log_raw_input = 'r' in opts
1145 1145 timestamp = 't' in opts
1146 1146
1147 1147 logger = self.shell.logger
1148 1148
1149 1149 # if no args are given, the defaults set in the logger constructor by
1150 1150 # ipytohn remain valid
1151 1151 if par:
1152 1152 try:
1153 1153 logfname,logmode = par.split()
1154 1154 except:
1155 1155 logfname = par
1156 1156 logmode = 'backup'
1157 1157 else:
1158 1158 logfname = logger.logfname
1159 1159 logmode = logger.logmode
1160 1160 # put logfname into rc struct as if it had been called on the command
1161 1161 # line, so it ends up saved in the log header Save it in case we need
1162 1162 # to restore it...
1163 1163 old_logfile = self.shell.logfile
1164 1164 if logfname:
1165 1165 logfname = os.path.expanduser(logfname)
1166 1166 self.shell.logfile = logfname
1167 1167
1168 1168 loghead = '# IPython log file\n\n'
1169 1169 try:
1170 1170 started = logger.logstart(logfname,loghead,logmode,
1171 1171 log_output,timestamp,log_raw_input)
1172 1172 except:
1173 1173 rc.opts.logfile = old_logfile
1174 1174 warn("Couldn't start log: %s" % sys.exc_info()[1])
1175 1175 else:
1176 1176 # log input history up to this point, optionally interleaving
1177 1177 # output if requested
1178 1178
1179 1179 if timestamp:
1180 1180 # disable timestamping for the previous history, since we've
1181 1181 # lost those already (no time machine here).
1182 1182 logger.timestamp = False
1183 1183
1184 1184 if log_raw_input:
1185 1185 input_hist = self.shell.input_hist_raw
1186 1186 else:
1187 1187 input_hist = self.shell.input_hist
1188 1188
1189 1189 if log_output:
1190 1190 log_write = logger.log_write
1191 1191 output_hist = self.shell.output_hist
1192 1192 for n in range(1,len(input_hist)-1):
1193 1193 log_write(input_hist[n].rstrip())
1194 1194 if n in output_hist:
1195 1195 log_write(repr(output_hist[n]),'output')
1196 1196 else:
1197 1197 logger.log_write(input_hist[1:])
1198 1198 if timestamp:
1199 1199 # re-enable timestamping
1200 1200 logger.timestamp = True
1201 1201
1202 1202 print ('Activating auto-logging. '
1203 1203 'Current session state plus future input saved.')
1204 1204 logger.logstate()
1205 1205
1206 1206 def magic_logstop(self,parameter_s=''):
1207 1207 """Fully stop logging and close log file.
1208 1208
1209 1209 In order to start logging again, a new %logstart call needs to be made,
1210 1210 possibly (though not necessarily) with a new filename, mode and other
1211 1211 options."""
1212 1212 self.logger.logstop()
1213 1213
1214 1214 def magic_logoff(self,parameter_s=''):
1215 1215 """Temporarily stop logging.
1216 1216
1217 1217 You must have previously started logging."""
1218 1218 self.shell.logger.switch_log(0)
1219 1219
1220 1220 def magic_logon(self,parameter_s=''):
1221 1221 """Restart logging.
1222 1222
1223 1223 This function is for restarting logging which you've temporarily
1224 1224 stopped with %logoff. For starting logging for the first time, you
1225 1225 must use the %logstart function, which allows you to specify an
1226 1226 optional log filename."""
1227 1227
1228 1228 self.shell.logger.switch_log(1)
1229 1229
1230 1230 def magic_logstate(self,parameter_s=''):
1231 1231 """Print the status of the logging system."""
1232 1232
1233 1233 self.shell.logger.logstate()
1234 1234
1235 1235 def magic_pdb(self, parameter_s=''):
1236 1236 """Control the automatic calling of the pdb interactive debugger.
1237 1237
1238 1238 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1239 1239 argument it works as a toggle.
1240 1240
1241 1241 When an exception is triggered, IPython can optionally call the
1242 1242 interactive pdb debugger after the traceback printout. %pdb toggles
1243 1243 this feature on and off.
1244 1244
1245 1245 The initial state of this feature is set in your ipythonrc
1246 1246 configuration file (the variable is called 'pdb').
1247 1247
1248 1248 If you want to just activate the debugger AFTER an exception has fired,
1249 1249 without having to type '%pdb on' and rerunning your code, you can use
1250 1250 the %debug magic."""
1251 1251
1252 1252 par = parameter_s.strip().lower()
1253 1253
1254 1254 if par:
1255 1255 try:
1256 1256 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1257 1257 except KeyError:
1258 1258 print ('Incorrect argument. Use on/1, off/0, '
1259 1259 'or nothing for a toggle.')
1260 1260 return
1261 1261 else:
1262 1262 # toggle
1263 1263 new_pdb = not self.shell.call_pdb
1264 1264
1265 1265 # set on the shell
1266 1266 self.shell.call_pdb = new_pdb
1267 1267 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1268 1268
1269 1269 def magic_debug(self, parameter_s=''):
1270 1270 """Activate the interactive debugger in post-mortem mode.
1271 1271
1272 1272 If an exception has just occurred, this lets you inspect its stack
1273 1273 frames interactively. Note that this will always work only on the last
1274 1274 traceback that occurred, so you must call this quickly after an
1275 1275 exception that you wish to inspect has fired, because if another one
1276 1276 occurs, it clobbers the previous one.
1277 1277
1278 1278 If you want IPython to automatically do this on every exception, see
1279 1279 the %pdb magic for more details.
1280 1280 """
1281 1281 self.shell.debugger(force=True)
1282 1282
1283 1283 @testdec.skip_doctest
1284 1284 def magic_prun(self, parameter_s ='',user_mode=1,
1285 1285 opts=None,arg_lst=None,prog_ns=None):
1286 1286
1287 1287 """Run a statement through the python code profiler.
1288 1288
1289 1289 Usage:
1290 1290 %prun [options] statement
1291 1291
1292 1292 The given statement (which doesn't require quote marks) is run via the
1293 1293 python profiler in a manner similar to the profile.run() function.
1294 1294 Namespaces are internally managed to work correctly; profile.run
1295 1295 cannot be used in IPython because it makes certain assumptions about
1296 1296 namespaces which do not hold under IPython.
1297 1297
1298 1298 Options:
1299 1299
1300 1300 -l <limit>: you can place restrictions on what or how much of the
1301 1301 profile gets printed. The limit value can be:
1302 1302
1303 1303 * A string: only information for function names containing this string
1304 1304 is printed.
1305 1305
1306 1306 * An integer: only these many lines are printed.
1307 1307
1308 1308 * A float (between 0 and 1): this fraction of the report is printed
1309 1309 (for example, use a limit of 0.4 to see the topmost 40% only).
1310 1310
1311 1311 You can combine several limits with repeated use of the option. For
1312 1312 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1313 1313 information about class constructors.
1314 1314
1315 1315 -r: return the pstats.Stats object generated by the profiling. This
1316 1316 object has all the information about the profile in it, and you can
1317 1317 later use it for further analysis or in other functions.
1318 1318
1319 1319 -s <key>: sort profile by given key. You can provide more than one key
1320 1320 by using the option several times: '-s key1 -s key2 -s key3...'. The
1321 1321 default sorting key is 'time'.
1322 1322
1323 1323 The following is copied verbatim from the profile documentation
1324 1324 referenced below:
1325 1325
1326 1326 When more than one key is provided, additional keys are used as
1327 1327 secondary criteria when the there is equality in all keys selected
1328 1328 before them.
1329 1329
1330 1330 Abbreviations can be used for any key names, as long as the
1331 1331 abbreviation is unambiguous. The following are the keys currently
1332 1332 defined:
1333 1333
1334 1334 Valid Arg Meaning
1335 1335 "calls" call count
1336 1336 "cumulative" cumulative time
1337 1337 "file" file name
1338 1338 "module" file name
1339 1339 "pcalls" primitive call count
1340 1340 "line" line number
1341 1341 "name" function name
1342 1342 "nfl" name/file/line
1343 1343 "stdname" standard name
1344 1344 "time" internal time
1345 1345
1346 1346 Note that all sorts on statistics are in descending order (placing
1347 1347 most time consuming items first), where as name, file, and line number
1348 1348 searches are in ascending order (i.e., alphabetical). The subtle
1349 1349 distinction between "nfl" and "stdname" is that the standard name is a
1350 1350 sort of the name as printed, which means that the embedded line
1351 1351 numbers get compared in an odd way. For example, lines 3, 20, and 40
1352 1352 would (if the file names were the same) appear in the string order
1353 1353 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1354 1354 line numbers. In fact, sort_stats("nfl") is the same as
1355 1355 sort_stats("name", "file", "line").
1356 1356
1357 1357 -T <filename>: save profile results as shown on screen to a text
1358 1358 file. The profile is still shown on screen.
1359 1359
1360 1360 -D <filename>: save (via dump_stats) profile statistics to given
1361 1361 filename. This data is in a format understod by the pstats module, and
1362 1362 is generated by a call to the dump_stats() method of profile
1363 1363 objects. The profile is still shown on screen.
1364 1364
1365 1365 If you want to run complete programs under the profiler's control, use
1366 1366 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1367 1367 contains profiler specific options as described here.
1368 1368
1369 1369 You can read the complete documentation for the profile module with::
1370 1370
1371 1371 In [1]: import profile; profile.help()
1372 1372 """
1373 1373
1374 1374 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1375 1375 # protect user quote marks
1376 1376 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1377 1377
1378 1378 if user_mode: # regular user call
1379 1379 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1380 1380 list_all=1)
1381 1381 namespace = self.shell.user_ns
1382 1382 else: # called to run a program by %run -p
1383 1383 try:
1384 1384 filename = get_py_filename(arg_lst[0])
1385 1385 except IOError,msg:
1386 1386 error(msg)
1387 1387 return
1388 1388
1389 1389 arg_str = 'execfile(filename,prog_ns)'
1390 1390 namespace = locals()
1391 1391
1392 1392 opts.merge(opts_def)
1393 1393
1394 1394 prof = profile.Profile()
1395 1395 try:
1396 1396 prof = prof.runctx(arg_str,namespace,namespace)
1397 1397 sys_exit = ''
1398 1398 except SystemExit:
1399 1399 sys_exit = """*** SystemExit exception caught in code being profiled."""
1400 1400
1401 1401 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1402 1402
1403 1403 lims = opts.l
1404 1404 if lims:
1405 1405 lims = [] # rebuild lims with ints/floats/strings
1406 1406 for lim in opts.l:
1407 1407 try:
1408 1408 lims.append(int(lim))
1409 1409 except ValueError:
1410 1410 try:
1411 1411 lims.append(float(lim))
1412 1412 except ValueError:
1413 1413 lims.append(lim)
1414 1414
1415 1415 # Trap output.
1416 1416 stdout_trap = StringIO()
1417 1417
1418 1418 if hasattr(stats,'stream'):
1419 1419 # In newer versions of python, the stats object has a 'stream'
1420 1420 # attribute to write into.
1421 1421 stats.stream = stdout_trap
1422 1422 stats.print_stats(*lims)
1423 1423 else:
1424 1424 # For older versions, we manually redirect stdout during printing
1425 1425 sys_stdout = sys.stdout
1426 1426 try:
1427 1427 sys.stdout = stdout_trap
1428 1428 stats.print_stats(*lims)
1429 1429 finally:
1430 1430 sys.stdout = sys_stdout
1431 1431
1432 1432 output = stdout_trap.getvalue()
1433 1433 output = output.rstrip()
1434 1434
1435 1435 page(output,screen_lines=self.shell.usable_screen_length)
1436 1436 print sys_exit,
1437 1437
1438 1438 dump_file = opts.D[0]
1439 1439 text_file = opts.T[0]
1440 1440 if dump_file:
1441 1441 prof.dump_stats(dump_file)
1442 1442 print '\n*** Profile stats marshalled to file',\
1443 1443 `dump_file`+'.',sys_exit
1444 1444 if text_file:
1445 1445 pfile = file(text_file,'w')
1446 1446 pfile.write(output)
1447 1447 pfile.close()
1448 1448 print '\n*** Profile printout saved to text file',\
1449 1449 `text_file`+'.',sys_exit
1450 1450
1451 1451 if opts.has_key('r'):
1452 1452 return stats
1453 1453 else:
1454 1454 return None
1455 1455
1456 1456 @testdec.skip_doctest
1457 1457 def magic_run(self, parameter_s ='',runner=None,
1458 1458 file_finder=get_py_filename):
1459 1459 """Run the named file inside IPython as a program.
1460 1460
1461 1461 Usage:\\
1462 1462 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1463 1463
1464 1464 Parameters after the filename are passed as command-line arguments to
1465 1465 the program (put in sys.argv). Then, control returns to IPython's
1466 1466 prompt.
1467 1467
1468 1468 This is similar to running at a system prompt:\\
1469 1469 $ python file args\\
1470 1470 but with the advantage of giving you IPython's tracebacks, and of
1471 1471 loading all variables into your interactive namespace for further use
1472 1472 (unless -p is used, see below).
1473 1473
1474 1474 The file is executed in a namespace initially consisting only of
1475 1475 __name__=='__main__' and sys.argv constructed as indicated. It thus
1476 1476 sees its environment as if it were being run as a stand-alone program
1477 1477 (except for sharing global objects such as previously imported
1478 1478 modules). But after execution, the IPython interactive namespace gets
1479 1479 updated with all variables defined in the program (except for __name__
1480 1480 and sys.argv). This allows for very convenient loading of code for
1481 1481 interactive work, while giving each program a 'clean sheet' to run in.
1482 1482
1483 1483 Options:
1484 1484
1485 1485 -n: __name__ is NOT set to '__main__', but to the running file's name
1486 1486 without extension (as python does under import). This allows running
1487 1487 scripts and reloading the definitions in them without calling code
1488 1488 protected by an ' if __name__ == "__main__" ' clause.
1489 1489
1490 1490 -i: run the file in IPython's namespace instead of an empty one. This
1491 1491 is useful if you are experimenting with code written in a text editor
1492 1492 which depends on variables defined interactively.
1493 1493
1494 1494 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1495 1495 being run. This is particularly useful if IPython is being used to
1496 1496 run unittests, which always exit with a sys.exit() call. In such
1497 1497 cases you are interested in the output of the test results, not in
1498 1498 seeing a traceback of the unittest module.
1499 1499
1500 1500 -t: print timing information at the end of the run. IPython will give
1501 1501 you an estimated CPU time consumption for your script, which under
1502 1502 Unix uses the resource module to avoid the wraparound problems of
1503 1503 time.clock(). Under Unix, an estimate of time spent on system tasks
1504 1504 is also given (for Windows platforms this is reported as 0.0).
1505 1505
1506 1506 If -t is given, an additional -N<N> option can be given, where <N>
1507 1507 must be an integer indicating how many times you want the script to
1508 1508 run. The final timing report will include total and per run results.
1509 1509
1510 1510 For example (testing the script uniq_stable.py):
1511 1511
1512 1512 In [1]: run -t uniq_stable
1513 1513
1514 1514 IPython CPU timings (estimated):\\
1515 1515 User : 0.19597 s.\\
1516 1516 System: 0.0 s.\\
1517 1517
1518 1518 In [2]: run -t -N5 uniq_stable
1519 1519
1520 1520 IPython CPU timings (estimated):\\
1521 1521 Total runs performed: 5\\
1522 1522 Times : Total Per run\\
1523 1523 User : 0.910862 s, 0.1821724 s.\\
1524 1524 System: 0.0 s, 0.0 s.
1525 1525
1526 1526 -d: run your program under the control of pdb, the Python debugger.
1527 1527 This allows you to execute your program step by step, watch variables,
1528 1528 etc. Internally, what IPython does is similar to calling:
1529 1529
1530 1530 pdb.run('execfile("YOURFILENAME")')
1531 1531
1532 1532 with a breakpoint set on line 1 of your file. You can change the line
1533 1533 number for this automatic breakpoint to be <N> by using the -bN option
1534 1534 (where N must be an integer). For example:
1535 1535
1536 1536 %run -d -b40 myscript
1537 1537
1538 1538 will set the first breakpoint at line 40 in myscript.py. Note that
1539 1539 the first breakpoint must be set on a line which actually does
1540 1540 something (not a comment or docstring) for it to stop execution.
1541 1541
1542 1542 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1543 1543 first enter 'c' (without qoutes) to start execution up to the first
1544 1544 breakpoint.
1545 1545
1546 1546 Entering 'help' gives information about the use of the debugger. You
1547 1547 can easily see pdb's full documentation with "import pdb;pdb.help()"
1548 1548 at a prompt.
1549 1549
1550 1550 -p: run program under the control of the Python profiler module (which
1551 1551 prints a detailed report of execution times, function calls, etc).
1552 1552
1553 1553 You can pass other options after -p which affect the behavior of the
1554 1554 profiler itself. See the docs for %prun for details.
1555 1555
1556 1556 In this mode, the program's variables do NOT propagate back to the
1557 1557 IPython interactive namespace (because they remain in the namespace
1558 1558 where the profiler executes them).
1559 1559
1560 1560 Internally this triggers a call to %prun, see its documentation for
1561 1561 details on the options available specifically for profiling.
1562 1562
1563 1563 There is one special usage for which the text above doesn't apply:
1564 1564 if the filename ends with .ipy, the file is run as ipython script,
1565 1565 just as if the commands were written on IPython prompt.
1566 1566 """
1567 1567
1568 1568 # get arguments and set sys.argv for program to be run.
1569 1569 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1570 1570 mode='list',list_all=1)
1571 1571
1572 1572 try:
1573 1573 filename = file_finder(arg_lst[0])
1574 1574 except IndexError:
1575 1575 warn('you must provide at least a filename.')
1576 1576 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1577 1577 return
1578 1578 except IOError,msg:
1579 1579 error(msg)
1580 1580 return
1581 1581
1582 1582 if filename.lower().endswith('.ipy'):
1583 1583 self.shell.safe_execfile_ipy(filename)
1584 1584 return
1585 1585
1586 1586 # Control the response to exit() calls made by the script being run
1587 1587 exit_ignore = opts.has_key('e')
1588 1588
1589 1589 # Make sure that the running script gets a proper sys.argv as if it
1590 1590 # were run from a system shell.
1591 1591 save_argv = sys.argv # save it for later restoring
1592 1592 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1593 1593
1594 1594 if opts.has_key('i'):
1595 1595 # Run in user's interactive namespace
1596 1596 prog_ns = self.shell.user_ns
1597 1597 __name__save = self.shell.user_ns['__name__']
1598 1598 prog_ns['__name__'] = '__main__'
1599 1599 main_mod = self.shell.new_main_mod(prog_ns)
1600 1600 else:
1601 1601 # Run in a fresh, empty namespace
1602 1602 if opts.has_key('n'):
1603 1603 name = os.path.splitext(os.path.basename(filename))[0]
1604 1604 else:
1605 1605 name = '__main__'
1606 1606
1607 1607 main_mod = self.shell.new_main_mod()
1608 1608 prog_ns = main_mod.__dict__
1609 1609 prog_ns['__name__'] = name
1610 1610
1611 1611 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1612 1612 # set the __file__ global in the script's namespace
1613 1613 prog_ns['__file__'] = filename
1614 1614
1615 1615 # pickle fix. See iplib for an explanation. But we need to make sure
1616 1616 # that, if we overwrite __main__, we replace it at the end
1617 1617 main_mod_name = prog_ns['__name__']
1618 1618
1619 1619 if main_mod_name == '__main__':
1620 1620 restore_main = sys.modules['__main__']
1621 1621 else:
1622 1622 restore_main = False
1623 1623
1624 1624 # This needs to be undone at the end to prevent holding references to
1625 1625 # every single object ever created.
1626 1626 sys.modules[main_mod_name] = main_mod
1627 1627
1628 1628 stats = None
1629 1629 try:
1630 1630 self.shell.savehist()
1631 1631
1632 1632 if opts.has_key('p'):
1633 1633 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1634 1634 else:
1635 1635 if opts.has_key('d'):
1636 1636 deb = debugger.Pdb(self.shell.colors)
1637 1637 # reset Breakpoint state, which is moronically kept
1638 1638 # in a class
1639 1639 bdb.Breakpoint.next = 1
1640 1640 bdb.Breakpoint.bplist = {}
1641 1641 bdb.Breakpoint.bpbynumber = [None]
1642 1642 # Set an initial breakpoint to stop execution
1643 1643 maxtries = 10
1644 1644 bp = int(opts.get('b',[1])[0])
1645 1645 checkline = deb.checkline(filename,bp)
1646 1646 if not checkline:
1647 1647 for bp in range(bp+1,bp+maxtries+1):
1648 1648 if deb.checkline(filename,bp):
1649 1649 break
1650 1650 else:
1651 1651 msg = ("\nI failed to find a valid line to set "
1652 1652 "a breakpoint\n"
1653 1653 "after trying up to line: %s.\n"
1654 1654 "Please set a valid breakpoint manually "
1655 1655 "with the -b option." % bp)
1656 1656 error(msg)
1657 1657 return
1658 1658 # if we find a good linenumber, set the breakpoint
1659 1659 deb.do_break('%s:%s' % (filename,bp))
1660 1660 # Start file run
1661 1661 print "NOTE: Enter 'c' at the",
1662 1662 print "%s prompt to start your script." % deb.prompt
1663 1663 try:
1664 1664 deb.run('execfile("%s")' % filename,prog_ns)
1665 1665
1666 1666 except:
1667 1667 etype, value, tb = sys.exc_info()
1668 1668 # Skip three frames in the traceback: the %run one,
1669 1669 # one inside bdb.py, and the command-line typed by the
1670 1670 # user (run by exec in pdb itself).
1671 1671 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1672 1672 else:
1673 1673 if runner is None:
1674 1674 runner = self.shell.safe_execfile
1675 1675 if opts.has_key('t'):
1676 1676 # timed execution
1677 1677 try:
1678 1678 nruns = int(opts['N'][0])
1679 1679 if nruns < 1:
1680 1680 error('Number of runs must be >=1')
1681 1681 return
1682 1682 except (KeyError):
1683 1683 nruns = 1
1684 1684 if nruns == 1:
1685 1685 t0 = clock2()
1686 1686 runner(filename,prog_ns,prog_ns,
1687 1687 exit_ignore=exit_ignore)
1688 1688 t1 = clock2()
1689 1689 t_usr = t1[0]-t0[0]
1690 1690 t_sys = t1[1]-t0[1]
1691 1691 print "\nIPython CPU timings (estimated):"
1692 1692 print " User : %10s s." % t_usr
1693 1693 print " System: %10s s." % t_sys
1694 1694 else:
1695 1695 runs = range(nruns)
1696 1696 t0 = clock2()
1697 1697 for nr in runs:
1698 1698 runner(filename,prog_ns,prog_ns,
1699 1699 exit_ignore=exit_ignore)
1700 1700 t1 = clock2()
1701 1701 t_usr = t1[0]-t0[0]
1702 1702 t_sys = t1[1]-t0[1]
1703 1703 print "\nIPython CPU timings (estimated):"
1704 1704 print "Total runs performed:",nruns
1705 1705 print " Times : %10s %10s" % ('Total','Per run')
1706 1706 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1707 1707 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1708 1708
1709 1709 else:
1710 1710 # regular execution
1711 1711 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1712 1712
1713 1713 if opts.has_key('i'):
1714 1714 self.shell.user_ns['__name__'] = __name__save
1715 1715 else:
1716 1716 # The shell MUST hold a reference to prog_ns so after %run
1717 1717 # exits, the python deletion mechanism doesn't zero it out
1718 1718 # (leaving dangling references).
1719 1719 self.shell.cache_main_mod(prog_ns,filename)
1720 1720 # update IPython interactive namespace
1721 1721
1722 1722 # Some forms of read errors on the file may mean the
1723 1723 # __name__ key was never set; using pop we don't have to
1724 1724 # worry about a possible KeyError.
1725 1725 prog_ns.pop('__name__', None)
1726 1726
1727 1727 self.shell.user_ns.update(prog_ns)
1728 1728 finally:
1729 1729 # It's a bit of a mystery why, but __builtins__ can change from
1730 1730 # being a module to becoming a dict missing some key data after
1731 1731 # %run. As best I can see, this is NOT something IPython is doing
1732 1732 # at all, and similar problems have been reported before:
1733 1733 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1734 1734 # Since this seems to be done by the interpreter itself, the best
1735 1735 # we can do is to at least restore __builtins__ for the user on
1736 1736 # exit.
1737 1737 self.shell.user_ns['__builtins__'] = __builtin__
1738 1738
1739 1739 # Ensure key global structures are restored
1740 1740 sys.argv = save_argv
1741 1741 if restore_main:
1742 1742 sys.modules['__main__'] = restore_main
1743 1743 else:
1744 1744 # Remove from sys.modules the reference to main_mod we'd
1745 1745 # added. Otherwise it will trap references to objects
1746 1746 # contained therein.
1747 1747 del sys.modules[main_mod_name]
1748 1748
1749 1749 self.shell.reloadhist()
1750 1750
1751 1751 return stats
1752 1752
1753 1753 @testdec.skip_doctest
1754 1754 def magic_timeit(self, parameter_s =''):
1755 1755 """Time execution of a Python statement or expression
1756 1756
1757 1757 Usage:\\
1758 1758 %timeit [-n<N> -r<R> [-t|-c]] statement
1759 1759
1760 1760 Time execution of a Python statement or expression using the timeit
1761 1761 module.
1762 1762
1763 1763 Options:
1764 1764 -n<N>: execute the given statement <N> times in a loop. If this value
1765 1765 is not given, a fitting value is chosen.
1766 1766
1767 1767 -r<R>: repeat the loop iteration <R> times and take the best result.
1768 1768 Default: 3
1769 1769
1770 1770 -t: use time.time to measure the time, which is the default on Unix.
1771 1771 This function measures wall time.
1772 1772
1773 1773 -c: use time.clock to measure the time, which is the default on
1774 1774 Windows and measures wall time. On Unix, resource.getrusage is used
1775 1775 instead and returns the CPU user time.
1776 1776
1777 1777 -p<P>: use a precision of <P> digits to display the timing result.
1778 1778 Default: 3
1779 1779
1780 1780
1781 1781 Examples:
1782 1782
1783 1783 In [1]: %timeit pass
1784 1784 10000000 loops, best of 3: 53.3 ns per loop
1785 1785
1786 1786 In [2]: u = None
1787 1787
1788 1788 In [3]: %timeit u is None
1789 1789 10000000 loops, best of 3: 184 ns per loop
1790 1790
1791 1791 In [4]: %timeit -r 4 u == None
1792 1792 1000000 loops, best of 4: 242 ns per loop
1793 1793
1794 1794 In [5]: import time
1795 1795
1796 1796 In [6]: %timeit -n1 time.sleep(2)
1797 1797 1 loops, best of 3: 2 s per loop
1798 1798
1799 1799
1800 1800 The times reported by %timeit will be slightly higher than those
1801 1801 reported by the timeit.py script when variables are accessed. This is
1802 1802 due to the fact that %timeit executes the statement in the namespace
1803 1803 of the shell, compared with timeit.py, which uses a single setup
1804 1804 statement to import function or create variables. Generally, the bias
1805 1805 does not matter as long as results from timeit.py are not mixed with
1806 1806 those from %timeit."""
1807 1807
1808 1808 import timeit
1809 1809 import math
1810 1810
1811 1811 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1812 1812 # certain terminals. Until we figure out a robust way of
1813 1813 # auto-detecting if the terminal can deal with it, use plain 'us' for
1814 1814 # microseconds. I am really NOT happy about disabling the proper
1815 1815 # 'micro' prefix, but crashing is worse... If anyone knows what the
1816 1816 # right solution for this is, I'm all ears...
1817 1817 #
1818 1818 # Note: using
1819 1819 #
1820 1820 # s = u'\xb5'
1821 1821 # s.encode(sys.getdefaultencoding())
1822 1822 #
1823 1823 # is not sufficient, as I've seen terminals where that fails but
1824 1824 # print s
1825 1825 #
1826 1826 # succeeds
1827 1827 #
1828 1828 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1829 1829
1830 1830 #units = [u"s", u"ms",u'\xb5',"ns"]
1831 1831 units = [u"s", u"ms",u'us',"ns"]
1832 1832
1833 1833 scaling = [1, 1e3, 1e6, 1e9]
1834 1834
1835 1835 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1836 1836 posix=False)
1837 1837 if stmt == "":
1838 1838 return
1839 1839 timefunc = timeit.default_timer
1840 1840 number = int(getattr(opts, "n", 0))
1841 1841 repeat = int(getattr(opts, "r", timeit.default_repeat))
1842 1842 precision = int(getattr(opts, "p", 3))
1843 1843 if hasattr(opts, "t"):
1844 1844 timefunc = time.time
1845 1845 if hasattr(opts, "c"):
1846 1846 timefunc = clock
1847 1847
1848 1848 timer = timeit.Timer(timer=timefunc)
1849 1849 # this code has tight coupling to the inner workings of timeit.Timer,
1850 1850 # but is there a better way to achieve that the code stmt has access
1851 1851 # to the shell namespace?
1852 1852
1853 1853 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1854 1854 'setup': "pass"}
1855 1855 # Track compilation time so it can be reported if too long
1856 1856 # Minimum time above which compilation time will be reported
1857 1857 tc_min = 0.1
1858 1858
1859 1859 t0 = clock()
1860 1860 code = compile(src, "<magic-timeit>", "exec")
1861 1861 tc = clock()-t0
1862 1862
1863 1863 ns = {}
1864 1864 exec code in self.shell.user_ns, ns
1865 1865 timer.inner = ns["inner"]
1866 1866
1867 1867 if number == 0:
1868 1868 # determine number so that 0.2 <= total time < 2.0
1869 1869 number = 1
1870 1870 for i in range(1, 10):
1871 1871 if timer.timeit(number) >= 0.2:
1872 1872 break
1873 1873 number *= 10
1874 1874
1875 1875 best = min(timer.repeat(repeat, number)) / number
1876 1876
1877 1877 if best > 0.0:
1878 1878 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1879 1879 else:
1880 1880 order = 3
1881 1881 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1882 1882 precision,
1883 1883 best * scaling[order],
1884 1884 units[order])
1885 1885 if tc > tc_min:
1886 1886 print "Compiler time: %.2f s" % tc
1887 1887
1888 1888 @testdec.skip_doctest
1889 1889 def magic_time(self,parameter_s = ''):
1890 1890 """Time execution of a Python statement or expression.
1891 1891
1892 1892 The CPU and wall clock times are printed, and the value of the
1893 1893 expression (if any) is returned. Note that under Win32, system time
1894 1894 is always reported as 0, since it can not be measured.
1895 1895
1896 1896 This function provides very basic timing functionality. In Python
1897 1897 2.3, the timeit module offers more control and sophistication, so this
1898 1898 could be rewritten to use it (patches welcome).
1899 1899
1900 1900 Some examples:
1901 1901
1902 1902 In [1]: time 2**128
1903 1903 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1904 1904 Wall time: 0.00
1905 1905 Out[1]: 340282366920938463463374607431768211456L
1906 1906
1907 1907 In [2]: n = 1000000
1908 1908
1909 1909 In [3]: time sum(range(n))
1910 1910 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1911 1911 Wall time: 1.37
1912 1912 Out[3]: 499999500000L
1913 1913
1914 1914 In [4]: time print 'hello world'
1915 1915 hello world
1916 1916 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1917 1917 Wall time: 0.00
1918 1918
1919 1919 Note that the time needed by Python to compile the given expression
1920 1920 will be reported if it is more than 0.1s. In this example, the
1921 1921 actual exponentiation is done by Python at compilation time, so while
1922 1922 the expression can take a noticeable amount of time to compute, that
1923 1923 time is purely due to the compilation:
1924 1924
1925 1925 In [5]: time 3**9999;
1926 1926 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1927 1927 Wall time: 0.00 s
1928 1928
1929 1929 In [6]: time 3**999999;
1930 1930 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1931 1931 Wall time: 0.00 s
1932 1932 Compiler : 0.78 s
1933 1933 """
1934 1934
1935 1935 # fail immediately if the given expression can't be compiled
1936 1936
1937 1937 expr = self.shell.prefilter(parameter_s,False)
1938 1938
1939 1939 # Minimum time above which compilation time will be reported
1940 1940 tc_min = 0.1
1941 1941
1942 1942 try:
1943 1943 mode = 'eval'
1944 1944 t0 = clock()
1945 1945 code = compile(expr,'<timed eval>',mode)
1946 1946 tc = clock()-t0
1947 1947 except SyntaxError:
1948 1948 mode = 'exec'
1949 1949 t0 = clock()
1950 1950 code = compile(expr,'<timed exec>',mode)
1951 1951 tc = clock()-t0
1952 1952 # skew measurement as little as possible
1953 1953 glob = self.shell.user_ns
1954 1954 clk = clock2
1955 1955 wtime = time.time
1956 1956 # time execution
1957 1957 wall_st = wtime()
1958 1958 if mode=='eval':
1959 1959 st = clk()
1960 1960 out = eval(code,glob)
1961 1961 end = clk()
1962 1962 else:
1963 1963 st = clk()
1964 1964 exec code in glob
1965 1965 end = clk()
1966 1966 out = None
1967 1967 wall_end = wtime()
1968 1968 # Compute actual times and report
1969 1969 wall_time = wall_end-wall_st
1970 1970 cpu_user = end[0]-st[0]
1971 1971 cpu_sys = end[1]-st[1]
1972 1972 cpu_tot = cpu_user+cpu_sys
1973 1973 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1974 1974 (cpu_user,cpu_sys,cpu_tot)
1975 1975 print "Wall time: %.2f s" % wall_time
1976 1976 if tc > tc_min:
1977 1977 print "Compiler : %.2f s" % tc
1978 1978 return out
1979 1979
1980 1980 @testdec.skip_doctest
1981 1981 def magic_macro(self,parameter_s = ''):
1982 1982 """Define a set of input lines as a macro for future re-execution.
1983 1983
1984 1984 Usage:\\
1985 1985 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1986 1986
1987 1987 Options:
1988 1988
1989 1989 -r: use 'raw' input. By default, the 'processed' history is used,
1990 1990 so that magics are loaded in their transformed version to valid
1991 1991 Python. If this option is given, the raw input as typed as the
1992 1992 command line is used instead.
1993 1993
1994 1994 This will define a global variable called `name` which is a string
1995 1995 made of joining the slices and lines you specify (n1,n2,... numbers
1996 1996 above) from your input history into a single string. This variable
1997 1997 acts like an automatic function which re-executes those lines as if
1998 1998 you had typed them. You just type 'name' at the prompt and the code
1999 1999 executes.
2000 2000
2001 2001 The notation for indicating number ranges is: n1-n2 means 'use line
2002 2002 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2003 2003 using the lines numbered 5,6 and 7.
2004 2004
2005 2005 Note: as a 'hidden' feature, you can also use traditional python slice
2006 2006 notation, where N:M means numbers N through M-1.
2007 2007
2008 2008 For example, if your history contains (%hist prints it):
2009 2009
2010 2010 44: x=1
2011 2011 45: y=3
2012 2012 46: z=x+y
2013 2013 47: print x
2014 2014 48: a=5
2015 2015 49: print 'x',x,'y',y
2016 2016
2017 2017 you can create a macro with lines 44 through 47 (included) and line 49
2018 2018 called my_macro with:
2019 2019
2020 2020 In [55]: %macro my_macro 44-47 49
2021 2021
2022 2022 Now, typing `my_macro` (without quotes) will re-execute all this code
2023 2023 in one pass.
2024 2024
2025 2025 You don't need to give the line-numbers in order, and any given line
2026 2026 number can appear multiple times. You can assemble macros with any
2027 2027 lines from your input history in any order.
2028 2028
2029 2029 The macro is a simple object which holds its value in an attribute,
2030 2030 but IPython's display system checks for macros and executes them as
2031 2031 code instead of printing them when you type their name.
2032 2032
2033 2033 You can view a macro's contents by explicitly printing it with:
2034 2034
2035 2035 'print macro_name'.
2036 2036
2037 2037 For one-off cases which DON'T contain magic function calls in them you
2038 2038 can obtain similar results by explicitly executing slices from your
2039 2039 input history with:
2040 2040
2041 2041 In [60]: exec In[44:48]+In[49]"""
2042 2042
2043 2043 opts,args = self.parse_options(parameter_s,'r',mode='list')
2044 2044 if not args:
2045 2045 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2046 2046 macs.sort()
2047 2047 return macs
2048 2048 if len(args) == 1:
2049 2049 raise UsageError(
2050 2050 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2051 2051 name,ranges = args[0], args[1:]
2052 2052
2053 2053 #print 'rng',ranges # dbg
2054 2054 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2055 2055 macro = Macro(lines)
2056 2056 self.shell.define_macro(name, macro)
2057 2057 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2058 2058 print 'Macro contents:'
2059 2059 print macro,
2060 2060
2061 2061 def magic_save(self,parameter_s = ''):
2062 2062 """Save a set of lines to a given filename.
2063 2063
2064 2064 Usage:\\
2065 2065 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2066 2066
2067 2067 Options:
2068 2068
2069 2069 -r: use 'raw' input. By default, the 'processed' history is used,
2070 2070 so that magics are loaded in their transformed version to valid
2071 2071 Python. If this option is given, the raw input as typed as the
2072 2072 command line is used instead.
2073 2073
2074 2074 This function uses the same syntax as %macro for line extraction, but
2075 2075 instead of creating a macro it saves the resulting string to the
2076 2076 filename you specify.
2077 2077
2078 2078 It adds a '.py' extension to the file if you don't do so yourself, and
2079 2079 it asks for confirmation before overwriting existing files."""
2080 2080
2081 2081 opts,args = self.parse_options(parameter_s,'r',mode='list')
2082 2082 fname,ranges = args[0], args[1:]
2083 2083 if not fname.endswith('.py'):
2084 2084 fname += '.py'
2085 2085 if os.path.isfile(fname):
2086 2086 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2087 2087 if ans.lower() not in ['y','yes']:
2088 2088 print 'Operation cancelled.'
2089 2089 return
2090 2090 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2091 2091 f = file(fname,'w')
2092 2092 f.write(cmds)
2093 2093 f.close()
2094 2094 print 'The following commands were written to file `%s`:' % fname
2095 2095 print cmds
2096 2096
2097 2097 def _edit_macro(self,mname,macro):
2098 2098 """open an editor with the macro data in a file"""
2099 2099 filename = self.shell.mktempfile(macro.value)
2100 2100 self.shell.hooks.editor(filename)
2101 2101
2102 2102 # and make a new macro object, to replace the old one
2103 2103 mfile = open(filename)
2104 2104 mvalue = mfile.read()
2105 2105 mfile.close()
2106 2106 self.shell.user_ns[mname] = Macro(mvalue)
2107 2107
2108 2108 def magic_ed(self,parameter_s=''):
2109 2109 """Alias to %edit."""
2110 2110 return self.magic_edit(parameter_s)
2111 2111
2112 2112 @testdec.skip_doctest
2113 2113 def magic_edit(self,parameter_s='',last_call=['','']):
2114 2114 """Bring up an editor and execute the resulting code.
2115 2115
2116 2116 Usage:
2117 2117 %edit [options] [args]
2118 2118
2119 2119 %edit runs IPython's editor hook. The default version of this hook is
2120 2120 set to call the __IPYTHON__.rc.editor command. This is read from your
2121 2121 environment variable $EDITOR. If this isn't found, it will default to
2122 2122 vi under Linux/Unix and to notepad under Windows. See the end of this
2123 2123 docstring for how to change the editor hook.
2124 2124
2125 2125 You can also set the value of this editor via the command line option
2126 2126 '-editor' or in your ipythonrc file. This is useful if you wish to use
2127 2127 specifically for IPython an editor different from your typical default
2128 2128 (and for Windows users who typically don't set environment variables).
2129 2129
2130 2130 This command allows you to conveniently edit multi-line code right in
2131 2131 your IPython session.
2132 2132
2133 2133 If called without arguments, %edit opens up an empty editor with a
2134 2134 temporary file and will execute the contents of this file when you
2135 2135 close it (don't forget to save it!).
2136 2136
2137 2137
2138 2138 Options:
2139 2139
2140 2140 -n <number>: open the editor at a specified line number. By default,
2141 2141 the IPython editor hook uses the unix syntax 'editor +N filename', but
2142 2142 you can configure this by providing your own modified hook if your
2143 2143 favorite editor supports line-number specifications with a different
2144 2144 syntax.
2145 2145
2146 2146 -p: this will call the editor with the same data as the previous time
2147 2147 it was used, regardless of how long ago (in your current session) it
2148 2148 was.
2149 2149
2150 2150 -r: use 'raw' input. This option only applies to input taken from the
2151 2151 user's history. By default, the 'processed' history is used, so that
2152 2152 magics are loaded in their transformed version to valid Python. If
2153 2153 this option is given, the raw input as typed as the command line is
2154 2154 used instead. When you exit the editor, it will be executed by
2155 2155 IPython's own processor.
2156 2156
2157 2157 -x: do not execute the edited code immediately upon exit. This is
2158 2158 mainly useful if you are editing programs which need to be called with
2159 2159 command line arguments, which you can then do using %run.
2160 2160
2161 2161
2162 2162 Arguments:
2163 2163
2164 2164 If arguments are given, the following possibilites exist:
2165 2165
2166 2166 - The arguments are numbers or pairs of colon-separated numbers (like
2167 2167 1 4:8 9). These are interpreted as lines of previous input to be
2168 2168 loaded into the editor. The syntax is the same of the %macro command.
2169 2169
2170 2170 - If the argument doesn't start with a number, it is evaluated as a
2171 2171 variable and its contents loaded into the editor. You can thus edit
2172 2172 any string which contains python code (including the result of
2173 2173 previous edits).
2174 2174
2175 2175 - If the argument is the name of an object (other than a string),
2176 2176 IPython will try to locate the file where it was defined and open the
2177 2177 editor at the point where it is defined. You can use `%edit function`
2178 2178 to load an editor exactly at the point where 'function' is defined,
2179 2179 edit it and have the file be executed automatically.
2180 2180
2181 2181 If the object is a macro (see %macro for details), this opens up your
2182 2182 specified editor with a temporary file containing the macro's data.
2183 2183 Upon exit, the macro is reloaded with the contents of the file.
2184 2184
2185 2185 Note: opening at an exact line is only supported under Unix, and some
2186 2186 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2187 2187 '+NUMBER' parameter necessary for this feature. Good editors like
2188 2188 (X)Emacs, vi, jed, pico and joe all do.
2189 2189
2190 2190 - If the argument is not found as a variable, IPython will look for a
2191 2191 file with that name (adding .py if necessary) and load it into the
2192 2192 editor. It will execute its contents with execfile() when you exit,
2193 2193 loading any code in the file into your interactive namespace.
2194 2194
2195 2195 After executing your code, %edit will return as output the code you
2196 2196 typed in the editor (except when it was an existing file). This way
2197 2197 you can reload the code in further invocations of %edit as a variable,
2198 2198 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2199 2199 the output.
2200 2200
2201 2201 Note that %edit is also available through the alias %ed.
2202 2202
2203 2203 This is an example of creating a simple function inside the editor and
2204 2204 then modifying it. First, start up the editor:
2205 2205
2206 2206 In [1]: ed
2207 2207 Editing... done. Executing edited code...
2208 2208 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2209 2209
2210 2210 We can then call the function foo():
2211 2211
2212 2212 In [2]: foo()
2213 2213 foo() was defined in an editing session
2214 2214
2215 2215 Now we edit foo. IPython automatically loads the editor with the
2216 2216 (temporary) file where foo() was previously defined:
2217 2217
2218 2218 In [3]: ed foo
2219 2219 Editing... done. Executing edited code...
2220 2220
2221 2221 And if we call foo() again we get the modified version:
2222 2222
2223 2223 In [4]: foo()
2224 2224 foo() has now been changed!
2225 2225
2226 2226 Here is an example of how to edit a code snippet successive
2227 2227 times. First we call the editor:
2228 2228
2229 2229 In [5]: ed
2230 2230 Editing... done. Executing edited code...
2231 2231 hello
2232 2232 Out[5]: "print 'hello'n"
2233 2233
2234 2234 Now we call it again with the previous output (stored in _):
2235 2235
2236 2236 In [6]: ed _
2237 2237 Editing... done. Executing edited code...
2238 2238 hello world
2239 2239 Out[6]: "print 'hello world'n"
2240 2240
2241 2241 Now we call it with the output #8 (stored in _8, also as Out[8]):
2242 2242
2243 2243 In [7]: ed _8
2244 2244 Editing... done. Executing edited code...
2245 2245 hello again
2246 2246 Out[7]: "print 'hello again'n"
2247 2247
2248 2248
2249 2249 Changing the default editor hook:
2250 2250
2251 2251 If you wish to write your own editor hook, you can put it in a
2252 2252 configuration file which you load at startup time. The default hook
2253 2253 is defined in the IPython.core.hooks module, and you can use that as a
2254 2254 starting example for further modifications. That file also has
2255 2255 general instructions on how to set a new hook for use once you've
2256 2256 defined it."""
2257 2257
2258 2258 # FIXME: This function has become a convoluted mess. It needs a
2259 2259 # ground-up rewrite with clean, simple logic.
2260 2260
2261 2261 def make_filename(arg):
2262 2262 "Make a filename from the given args"
2263 2263 try:
2264 2264 filename = get_py_filename(arg)
2265 2265 except IOError:
2266 2266 if args.endswith('.py'):
2267 2267 filename = arg
2268 2268 else:
2269 2269 filename = None
2270 2270 return filename
2271 2271
2272 2272 # custom exceptions
2273 2273 class DataIsObject(Exception): pass
2274 2274
2275 2275 opts,args = self.parse_options(parameter_s,'prxn:')
2276 2276 # Set a few locals from the options for convenience:
2277 2277 opts_p = opts.has_key('p')
2278 2278 opts_r = opts.has_key('r')
2279 2279
2280 2280 # Default line number value
2281 2281 lineno = opts.get('n',None)
2282 2282
2283 2283 if opts_p:
2284 2284 args = '_%s' % last_call[0]
2285 2285 if not self.shell.user_ns.has_key(args):
2286 2286 args = last_call[1]
2287 2287
2288 2288 # use last_call to remember the state of the previous call, but don't
2289 2289 # let it be clobbered by successive '-p' calls.
2290 2290 try:
2291 2291 last_call[0] = self.shell.outputcache.prompt_count
2292 2292 if not opts_p:
2293 2293 last_call[1] = parameter_s
2294 2294 except:
2295 2295 pass
2296 2296
2297 2297 # by default this is done with temp files, except when the given
2298 2298 # arg is a filename
2299 2299 use_temp = 1
2300 2300
2301 2301 if re.match(r'\d',args):
2302 2302 # Mode where user specifies ranges of lines, like in %macro.
2303 2303 # This means that you can't edit files whose names begin with
2304 2304 # numbers this way. Tough.
2305 2305 ranges = args.split()
2306 2306 data = ''.join(self.extract_input_slices(ranges,opts_r))
2307 2307 elif args.endswith('.py'):
2308 2308 filename = make_filename(args)
2309 2309 data = ''
2310 2310 use_temp = 0
2311 2311 elif args:
2312 2312 try:
2313 2313 # Load the parameter given as a variable. If not a string,
2314 2314 # process it as an object instead (below)
2315 2315
2316 2316 #print '*** args',args,'type',type(args) # dbg
2317 2317 data = eval(args,self.shell.user_ns)
2318 2318 if not type(data) in StringTypes:
2319 2319 raise DataIsObject
2320 2320
2321 2321 except (NameError,SyntaxError):
2322 2322 # given argument is not a variable, try as a filename
2323 2323 filename = make_filename(args)
2324 2324 if filename is None:
2325 2325 warn("Argument given (%s) can't be found as a variable "
2326 2326 "or as a filename." % args)
2327 2327 return
2328 2328
2329 2329 data = ''
2330 2330 use_temp = 0
2331 2331 except DataIsObject:
2332 2332
2333 2333 # macros have a special edit function
2334 2334 if isinstance(data,Macro):
2335 2335 self._edit_macro(args,data)
2336 2336 return
2337 2337
2338 2338 # For objects, try to edit the file where they are defined
2339 2339 try:
2340 2340 filename = inspect.getabsfile(data)
2341 2341 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2342 2342 # class created by %edit? Try to find source
2343 2343 # by looking for method definitions instead, the
2344 2344 # __module__ in those classes is FakeModule.
2345 2345 attrs = [getattr(data, aname) for aname in dir(data)]
2346 2346 for attr in attrs:
2347 2347 if not inspect.ismethod(attr):
2348 2348 continue
2349 2349 filename = inspect.getabsfile(attr)
2350 2350 if filename and 'fakemodule' not in filename.lower():
2351 2351 # change the attribute to be the edit target instead
2352 2352 data = attr
2353 2353 break
2354 2354
2355 2355 datafile = 1
2356 2356 except TypeError:
2357 2357 filename = make_filename(args)
2358 2358 datafile = 1
2359 2359 warn('Could not find file where `%s` is defined.\n'
2360 2360 'Opening a file named `%s`' % (args,filename))
2361 2361 # Now, make sure we can actually read the source (if it was in
2362 2362 # a temp file it's gone by now).
2363 2363 if datafile:
2364 2364 try:
2365 2365 if lineno is None:
2366 2366 lineno = inspect.getsourcelines(data)[1]
2367 2367 except IOError:
2368 2368 filename = make_filename(args)
2369 2369 if filename is None:
2370 2370 warn('The file `%s` where `%s` was defined cannot '
2371 2371 'be read.' % (filename,data))
2372 2372 return
2373 2373 use_temp = 0
2374 2374 else:
2375 2375 data = ''
2376 2376
2377 2377 if use_temp:
2378 2378 filename = self.shell.mktempfile(data)
2379 2379 print 'IPython will make a temporary file named:',filename
2380 2380
2381 2381 # do actual editing here
2382 2382 print 'Editing...',
2383 2383 sys.stdout.flush()
2384 2384 try:
2385 2385 self.shell.hooks.editor(filename,lineno)
2386 2386 except TryNext:
2387 2387 warn('Could not open editor')
2388 2388 return
2389 2389
2390 2390 # XXX TODO: should this be generalized for all string vars?
2391 2391 # For now, this is special-cased to blocks created by cpaste
2392 2392 if args.strip() == 'pasted_block':
2393 2393 self.shell.user_ns['pasted_block'] = file_read(filename)
2394 2394
2395 2395 if opts.has_key('x'): # -x prevents actual execution
2396 2396 print
2397 2397 else:
2398 2398 print 'done. Executing edited code...'
2399 2399 if opts_r:
2400 2400 self.shell.runlines(file_read(filename))
2401 2401 else:
2402 2402 self.shell.safe_execfile(filename,self.shell.user_ns,
2403 2403 self.shell.user_ns)
2404 2404
2405 2405
2406 2406 if use_temp:
2407 2407 try:
2408 2408 return open(filename).read()
2409 2409 except IOError,msg:
2410 2410 if msg.filename == filename:
2411 2411 warn('File not found. Did you forget to save?')
2412 2412 return
2413 2413 else:
2414 2414 self.shell.showtraceback()
2415 2415
2416 2416 def magic_xmode(self,parameter_s = ''):
2417 2417 """Switch modes for the exception handlers.
2418 2418
2419 2419 Valid modes: Plain, Context and Verbose.
2420 2420
2421 2421 If called without arguments, acts as a toggle."""
2422 2422
2423 2423 def xmode_switch_err(name):
2424 2424 warn('Error changing %s exception modes.\n%s' %
2425 2425 (name,sys.exc_info()[1]))
2426 2426
2427 2427 shell = self.shell
2428 2428 new_mode = parameter_s.strip().capitalize()
2429 2429 try:
2430 2430 shell.InteractiveTB.set_mode(mode=new_mode)
2431 2431 print 'Exception reporting mode:',shell.InteractiveTB.mode
2432 2432 except:
2433 2433 xmode_switch_err('user')
2434 2434
2435 2435 # threaded shells use a special handler in sys.excepthook
2436 2436 if shell.isthreaded:
2437 2437 try:
2438 2438 shell.sys_excepthook.set_mode(mode=new_mode)
2439 2439 except:
2440 2440 xmode_switch_err('threaded')
2441 2441
2442 2442 def magic_colors(self,parameter_s = ''):
2443 2443 """Switch color scheme for prompts, info system and exception handlers.
2444 2444
2445 2445 Currently implemented schemes: NoColor, Linux, LightBG.
2446 2446
2447 2447 Color scheme names are not case-sensitive."""
2448 2448
2449 2449 def color_switch_err(name):
2450 2450 warn('Error changing %s color schemes.\n%s' %
2451 2451 (name,sys.exc_info()[1]))
2452 2452
2453 2453
2454 2454 new_scheme = parameter_s.strip()
2455 2455 if not new_scheme:
2456 2456 raise UsageError(
2457 2457 "%colors: you must specify a color scheme. See '%colors?'")
2458 2458 return
2459 2459 # local shortcut
2460 2460 shell = self.shell
2461 2461
2462 2462 import IPython.utils.rlineimpl as readline
2463 2463
2464 2464 if not readline.have_readline and sys.platform == "win32":
2465 2465 msg = """\
2466 2466 Proper color support under MS Windows requires the pyreadline library.
2467 2467 You can find it at:
2468 2468 http://ipython.scipy.org/moin/PyReadline/Intro
2469 2469 Gary's readline needs the ctypes module, from:
2470 2470 http://starship.python.net/crew/theller/ctypes
2471 2471 (Note that ctypes is already part of Python versions 2.5 and newer).
2472 2472
2473 2473 Defaulting color scheme to 'NoColor'"""
2474 2474 new_scheme = 'NoColor'
2475 2475 warn(msg)
2476 2476
2477 2477 # readline option is 0
2478 2478 if not shell.has_readline:
2479 2479 new_scheme = 'NoColor'
2480 2480
2481 2481 # Set prompt colors
2482 2482 try:
2483 2483 shell.outputcache.set_colors(new_scheme)
2484 2484 except:
2485 2485 color_switch_err('prompt')
2486 2486 else:
2487 2487 shell.colors = \
2488 2488 shell.outputcache.color_table.active_scheme_name
2489 2489 # Set exception colors
2490 2490 try:
2491 2491 shell.InteractiveTB.set_colors(scheme = new_scheme)
2492 2492 shell.SyntaxTB.set_colors(scheme = new_scheme)
2493 2493 except:
2494 2494 color_switch_err('exception')
2495 2495
2496 2496 # threaded shells use a verbose traceback in sys.excepthook
2497 2497 if shell.isthreaded:
2498 2498 try:
2499 2499 shell.sys_excepthook.set_colors(scheme=new_scheme)
2500 2500 except:
2501 2501 color_switch_err('system exception handler')
2502 2502
2503 2503 # Set info (for 'object?') colors
2504 2504 if shell.color_info:
2505 2505 try:
2506 2506 shell.inspector.set_active_scheme(new_scheme)
2507 2507 except:
2508 2508 color_switch_err('object inspector')
2509 2509 else:
2510 2510 shell.inspector.set_active_scheme('NoColor')
2511 2511
2512 2512 def magic_color_info(self,parameter_s = ''):
2513 2513 """Toggle color_info.
2514 2514
2515 2515 The color_info configuration parameter controls whether colors are
2516 2516 used for displaying object details (by things like %psource, %pfile or
2517 2517 the '?' system). This function toggles this value with each call.
2518 2518
2519 2519 Note that unless you have a fairly recent pager (less works better
2520 2520 than more) in your system, using colored object information displays
2521 2521 will not work properly. Test it and see."""
2522 2522
2523 2523 self.shell.color_info = not self.shell.color_info
2524 2524 self.magic_colors(self.shell.colors)
2525 2525 print 'Object introspection functions have now coloring:',
2526 2526 print ['OFF','ON'][int(self.shell.color_info)]
2527 2527
2528 2528 def magic_Pprint(self, parameter_s=''):
2529 2529 """Toggle pretty printing on/off."""
2530 2530
2531 2531 self.shell.pprint = 1 - self.shell.pprint
2532 2532 print 'Pretty printing has been turned', \
2533 2533 ['OFF','ON'][self.shell.pprint]
2534 2534
2535 2535 def magic_Exit(self, parameter_s=''):
2536 2536 """Exit IPython without confirmation."""
2537 2537
2538 2538 self.shell.ask_exit()
2539 2539
2540 2540 #......................................................................
2541 2541 # Functions to implement unix shell-type things
2542 2542
2543 2543 @testdec.skip_doctest
2544 2544 def magic_alias(self, parameter_s = ''):
2545 2545 """Define an alias for a system command.
2546 2546
2547 2547 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2548 2548
2549 2549 Then, typing 'alias_name params' will execute the system command 'cmd
2550 2550 params' (from your underlying operating system).
2551 2551
2552 2552 Aliases have lower precedence than magic functions and Python normal
2553 2553 variables, so if 'foo' is both a Python variable and an alias, the
2554 2554 alias can not be executed until 'del foo' removes the Python variable.
2555 2555
2556 2556 You can use the %l specifier in an alias definition to represent the
2557 2557 whole line when the alias is called. For example:
2558 2558
2559 2559 In [2]: alias all echo "Input in brackets: <%l>"
2560 2560 In [3]: all hello world
2561 2561 Input in brackets: <hello world>
2562 2562
2563 2563 You can also define aliases with parameters using %s specifiers (one
2564 2564 per parameter):
2565 2565
2566 2566 In [1]: alias parts echo first %s second %s
2567 2567 In [2]: %parts A B
2568 2568 first A second B
2569 2569 In [3]: %parts A
2570 2570 Incorrect number of arguments: 2 expected.
2571 2571 parts is an alias to: 'echo first %s second %s'
2572 2572
2573 2573 Note that %l and %s are mutually exclusive. You can only use one or
2574 2574 the other in your aliases.
2575 2575
2576 2576 Aliases expand Python variables just like system calls using ! or !!
2577 2577 do: all expressions prefixed with '$' get expanded. For details of
2578 2578 the semantic rules, see PEP-215:
2579 2579 http://www.python.org/peps/pep-0215.html. This is the library used by
2580 2580 IPython for variable expansion. If you want to access a true shell
2581 2581 variable, an extra $ is necessary to prevent its expansion by IPython:
2582 2582
2583 2583 In [6]: alias show echo
2584 2584 In [7]: PATH='A Python string'
2585 2585 In [8]: show $PATH
2586 2586 A Python string
2587 2587 In [9]: show $$PATH
2588 2588 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2589 2589
2590 2590 You can use the alias facility to acess all of $PATH. See the %rehash
2591 2591 and %rehashx functions, which automatically create aliases for the
2592 2592 contents of your $PATH.
2593 2593
2594 2594 If called with no parameters, %alias prints the current alias table."""
2595 2595
2596 2596 par = parameter_s.strip()
2597 2597 if not par:
2598 2598 stored = self.db.get('stored_aliases', {} )
2599 2599 aliases = sorted(self.shell.alias_manager.aliases)
2600 2600 # for k, v in stored:
2601 2601 # atab.append(k, v[0])
2602 2602
2603 2603 print "Total number of aliases:", len(aliases)
2604 2604 return aliases
2605 2605
2606 2606 # Now try to define a new one
2607 2607 try:
2608 2608 alias,cmd = par.split(None, 1)
2609 2609 except:
2610 2610 print oinspect.getdoc(self.magic_alias)
2611 2611 else:
2612 2612 self.shell.alias_manager.soft_define_alias(alias, cmd)
2613 2613 # end magic_alias
2614 2614
2615 2615 def magic_unalias(self, parameter_s = ''):
2616 2616 """Remove an alias"""
2617 2617
2618 2618 aname = parameter_s.strip()
2619 2619 self.shell.alias_manager.undefine_alias(aname)
2620 2620 stored = self.db.get('stored_aliases', {} )
2621 2621 if aname in stored:
2622 2622 print "Removing %stored alias",aname
2623 2623 del stored[aname]
2624 2624 self.db['stored_aliases'] = stored
2625 2625
2626 2626
2627 2627 def magic_rehashx(self, parameter_s = ''):
2628 2628 """Update the alias table with all executable files in $PATH.
2629 2629
2630 2630 This version explicitly checks that every entry in $PATH is a file
2631 2631 with execute access (os.X_OK), so it is much slower than %rehash.
2632 2632
2633 2633 Under Windows, it checks executability as a match agains a
2634 2634 '|'-separated string of extensions, stored in the IPython config
2635 2635 variable win_exec_ext. This defaults to 'exe|com|bat'.
2636 2636
2637 2637 This function also resets the root module cache of module completer,
2638 2638 used on slow filesystems.
2639 2639 """
2640 2640 from IPython.core.alias import InvalidAliasError
2641 2641
2642 2642 # for the benefit of module completer in ipy_completers.py
2643 2643 del self.db['rootmodules']
2644 2644
2645 2645 path = [os.path.abspath(os.path.expanduser(p)) for p in
2646 2646 os.environ.get('PATH','').split(os.pathsep)]
2647 2647 path = filter(os.path.isdir,path)
2648 2648
2649 2649 syscmdlist = []
2650 2650 # Now define isexec in a cross platform manner.
2651 2651 if os.name == 'posix':
2652 2652 isexec = lambda fname:os.path.isfile(fname) and \
2653 2653 os.access(fname,os.X_OK)
2654 2654 else:
2655 2655 try:
2656 2656 winext = os.environ['pathext'].replace(';','|').replace('.','')
2657 2657 except KeyError:
2658 2658 winext = 'exe|com|bat|py'
2659 2659 if 'py' not in winext:
2660 2660 winext += '|py'
2661 2661 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2662 2662 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2663 2663 savedir = os.getcwd()
2664 2664
2665 2665 # Now walk the paths looking for executables to alias.
2666 2666 try:
2667 2667 # write the whole loop for posix/Windows so we don't have an if in
2668 2668 # the innermost part
2669 2669 if os.name == 'posix':
2670 2670 for pdir in path:
2671 2671 os.chdir(pdir)
2672 2672 for ff in os.listdir(pdir):
2673 2673 if isexec(ff):
2674 2674 try:
2675 2675 # Removes dots from the name since ipython
2676 2676 # will assume names with dots to be python.
2677 2677 self.shell.alias_manager.define_alias(
2678 2678 ff.replace('.',''), ff)
2679 2679 except InvalidAliasError:
2680 2680 pass
2681 2681 else:
2682 2682 syscmdlist.append(ff)
2683 2683 else:
2684 2684 for pdir in path:
2685 2685 os.chdir(pdir)
2686 2686 for ff in os.listdir(pdir):
2687 2687 base, ext = os.path.splitext(ff)
2688 2688 if isexec(ff) and base.lower() not in self.shell.no_alias:
2689 2689 if ext.lower() == '.exe':
2690 2690 ff = base
2691 2691 try:
2692 2692 # Removes dots from the name since ipython
2693 2693 # will assume names with dots to be python.
2694 2694 self.shell.alias_manager.define_alias(
2695 2695 base.lower().replace('.',''), ff)
2696 2696 except InvalidAliasError:
2697 2697 pass
2698 2698 syscmdlist.append(ff)
2699 2699 db = self.db
2700 2700 db['syscmdlist'] = syscmdlist
2701 2701 finally:
2702 2702 os.chdir(savedir)
2703 2703
2704 2704 def magic_pwd(self, parameter_s = ''):
2705 2705 """Return the current working directory path."""
2706 2706 return os.getcwd()
2707 2707
2708 2708 def magic_cd(self, parameter_s=''):
2709 2709 """Change the current working directory.
2710 2710
2711 2711 This command automatically maintains an internal list of directories
2712 2712 you visit during your IPython session, in the variable _dh. The
2713 2713 command %dhist shows this history nicely formatted. You can also
2714 2714 do 'cd -<tab>' to see directory history conveniently.
2715 2715
2716 2716 Usage:
2717 2717
2718 2718 cd 'dir': changes to directory 'dir'.
2719 2719
2720 2720 cd -: changes to the last visited directory.
2721 2721
2722 2722 cd -<n>: changes to the n-th directory in the directory history.
2723 2723
2724 2724 cd --foo: change to directory that matches 'foo' in history
2725 2725
2726 2726 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2727 2727 (note: cd <bookmark_name> is enough if there is no
2728 2728 directory <bookmark_name>, but a bookmark with the name exists.)
2729 2729 'cd -b <tab>' allows you to tab-complete bookmark names.
2730 2730
2731 2731 Options:
2732 2732
2733 2733 -q: quiet. Do not print the working directory after the cd command is
2734 2734 executed. By default IPython's cd command does print this directory,
2735 2735 since the default prompts do not display path information.
2736 2736
2737 2737 Note that !cd doesn't work for this purpose because the shell where
2738 2738 !command runs is immediately discarded after executing 'command'."""
2739 2739
2740 2740 parameter_s = parameter_s.strip()
2741 2741 #bkms = self.shell.persist.get("bookmarks",{})
2742 2742
2743 2743 oldcwd = os.getcwd()
2744 2744 numcd = re.match(r'(-)(\d+)$',parameter_s)
2745 2745 # jump in directory history by number
2746 2746 if numcd:
2747 2747 nn = int(numcd.group(2))
2748 2748 try:
2749 2749 ps = self.shell.user_ns['_dh'][nn]
2750 2750 except IndexError:
2751 2751 print 'The requested directory does not exist in history.'
2752 2752 return
2753 2753 else:
2754 2754 opts = {}
2755 2755 elif parameter_s.startswith('--'):
2756 2756 ps = None
2757 2757 fallback = None
2758 2758 pat = parameter_s[2:]
2759 2759 dh = self.shell.user_ns['_dh']
2760 2760 # first search only by basename (last component)
2761 2761 for ent in reversed(dh):
2762 2762 if pat in os.path.basename(ent) and os.path.isdir(ent):
2763 2763 ps = ent
2764 2764 break
2765 2765
2766 2766 if fallback is None and pat in ent and os.path.isdir(ent):
2767 2767 fallback = ent
2768 2768
2769 2769 # if we have no last part match, pick the first full path match
2770 2770 if ps is None:
2771 2771 ps = fallback
2772 2772
2773 2773 if ps is None:
2774 2774 print "No matching entry in directory history"
2775 2775 return
2776 2776 else:
2777 2777 opts = {}
2778 2778
2779 2779
2780 2780 else:
2781 2781 #turn all non-space-escaping backslashes to slashes,
2782 2782 # for c:\windows\directory\names\
2783 2783 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2784 2784 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2785 2785 # jump to previous
2786 2786 if ps == '-':
2787 2787 try:
2788 2788 ps = self.shell.user_ns['_dh'][-2]
2789 2789 except IndexError:
2790 2790 raise UsageError('%cd -: No previous directory to change to.')
2791 2791 # jump to bookmark if needed
2792 2792 else:
2793 2793 if not os.path.isdir(ps) or opts.has_key('b'):
2794 2794 bkms = self.db.get('bookmarks', {})
2795 2795
2796 2796 if bkms.has_key(ps):
2797 2797 target = bkms[ps]
2798 2798 print '(bookmark:%s) -> %s' % (ps,target)
2799 2799 ps = target
2800 2800 else:
2801 2801 if opts.has_key('b'):
2802 2802 raise UsageError("Bookmark '%s' not found. "
2803 2803 "Use '%%bookmark -l' to see your bookmarks." % ps)
2804 2804
2805 2805 # at this point ps should point to the target dir
2806 2806 if ps:
2807 2807 try:
2808 2808 os.chdir(os.path.expanduser(ps))
2809 2809 if self.shell.term_title:
2810 2810 platutils.set_term_title('IPython: ' + abbrev_cwd())
2811 2811 except OSError:
2812 2812 print sys.exc_info()[1]
2813 2813 else:
2814 2814 cwd = os.getcwd()
2815 2815 dhist = self.shell.user_ns['_dh']
2816 2816 if oldcwd != cwd:
2817 2817 dhist.append(cwd)
2818 2818 self.db['dhist'] = compress_dhist(dhist)[-100:]
2819 2819
2820 2820 else:
2821 2821 os.chdir(self.shell.home_dir)
2822 2822 if self.shell.term_title:
2823 2823 platutils.set_term_title('IPython: ' + '~')
2824 2824 cwd = os.getcwd()
2825 2825 dhist = self.shell.user_ns['_dh']
2826 2826
2827 2827 if oldcwd != cwd:
2828 2828 dhist.append(cwd)
2829 2829 self.db['dhist'] = compress_dhist(dhist)[-100:]
2830 2830 if not 'q' in opts and self.shell.user_ns['_dh']:
2831 2831 print self.shell.user_ns['_dh'][-1]
2832 2832
2833 2833
2834 2834 def magic_env(self, parameter_s=''):
2835 2835 """List environment variables."""
2836 2836
2837 2837 return os.environ.data
2838 2838
2839 2839 def magic_pushd(self, parameter_s=''):
2840 2840 """Place the current dir on stack and change directory.
2841 2841
2842 2842 Usage:\\
2843 2843 %pushd ['dirname']
2844 2844 """
2845 2845
2846 2846 dir_s = self.shell.dir_stack
2847 2847 tgt = os.path.expanduser(parameter_s)
2848 2848 cwd = os.getcwd().replace(self.home_dir,'~')
2849 2849 if tgt:
2850 2850 self.magic_cd(parameter_s)
2851 2851 dir_s.insert(0,cwd)
2852 2852 return self.magic_dirs()
2853 2853
2854 2854 def magic_popd(self, parameter_s=''):
2855 2855 """Change to directory popped off the top of the stack.
2856 2856 """
2857 2857 if not self.shell.dir_stack:
2858 2858 raise UsageError("%popd on empty stack")
2859 2859 top = self.shell.dir_stack.pop(0)
2860 2860 self.magic_cd(top)
2861 2861 print "popd ->",top
2862 2862
2863 2863 def magic_dirs(self, parameter_s=''):
2864 2864 """Return the current directory stack."""
2865 2865
2866 2866 return self.shell.dir_stack
2867 2867
2868 2868 def magic_dhist(self, parameter_s=''):
2869 2869 """Print your history of visited directories.
2870 2870
2871 2871 %dhist -> print full history\\
2872 2872 %dhist n -> print last n entries only\\
2873 2873 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2874 2874
2875 2875 This history is automatically maintained by the %cd command, and
2876 2876 always available as the global list variable _dh. You can use %cd -<n>
2877 2877 to go to directory number <n>.
2878 2878
2879 2879 Note that most of time, you should view directory history by entering
2880 2880 cd -<TAB>.
2881 2881
2882 2882 """
2883 2883
2884 2884 dh = self.shell.user_ns['_dh']
2885 2885 if parameter_s:
2886 2886 try:
2887 2887 args = map(int,parameter_s.split())
2888 2888 except:
2889 2889 self.arg_err(Magic.magic_dhist)
2890 2890 return
2891 2891 if len(args) == 1:
2892 2892 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2893 2893 elif len(args) == 2:
2894 2894 ini,fin = args
2895 2895 else:
2896 2896 self.arg_err(Magic.magic_dhist)
2897 2897 return
2898 2898 else:
2899 2899 ini,fin = 0,len(dh)
2900 2900 nlprint(dh,
2901 2901 header = 'Directory history (kept in _dh)',
2902 2902 start=ini,stop=fin)
2903 2903
2904 2904 @testdec.skip_doctest
2905 2905 def magic_sc(self, parameter_s=''):
2906 2906 """Shell capture - execute a shell command and capture its output.
2907 2907
2908 2908 DEPRECATED. Suboptimal, retained for backwards compatibility.
2909 2909
2910 2910 You should use the form 'var = !command' instead. Example:
2911 2911
2912 2912 "%sc -l myfiles = ls ~" should now be written as
2913 2913
2914 2914 "myfiles = !ls ~"
2915 2915
2916 2916 myfiles.s, myfiles.l and myfiles.n still apply as documented
2917 2917 below.
2918 2918
2919 2919 --
2920 2920 %sc [options] varname=command
2921 2921
2922 2922 IPython will run the given command using commands.getoutput(), and
2923 2923 will then update the user's interactive namespace with a variable
2924 2924 called varname, containing the value of the call. Your command can
2925 2925 contain shell wildcards, pipes, etc.
2926 2926
2927 2927 The '=' sign in the syntax is mandatory, and the variable name you
2928 2928 supply must follow Python's standard conventions for valid names.
2929 2929
2930 2930 (A special format without variable name exists for internal use)
2931 2931
2932 2932 Options:
2933 2933
2934 2934 -l: list output. Split the output on newlines into a list before
2935 2935 assigning it to the given variable. By default the output is stored
2936 2936 as a single string.
2937 2937
2938 2938 -v: verbose. Print the contents of the variable.
2939 2939
2940 2940 In most cases you should not need to split as a list, because the
2941 2941 returned value is a special type of string which can automatically
2942 2942 provide its contents either as a list (split on newlines) or as a
2943 2943 space-separated string. These are convenient, respectively, either
2944 2944 for sequential processing or to be passed to a shell command.
2945 2945
2946 2946 For example:
2947 2947
2948 2948 # all-random
2949 2949
2950 2950 # Capture into variable a
2951 2951 In [1]: sc a=ls *py
2952 2952
2953 2953 # a is a string with embedded newlines
2954 2954 In [2]: a
2955 2955 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2956 2956
2957 2957 # which can be seen as a list:
2958 2958 In [3]: a.l
2959 2959 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2960 2960
2961 2961 # or as a whitespace-separated string:
2962 2962 In [4]: a.s
2963 2963 Out[4]: 'setup.py win32_manual_post_install.py'
2964 2964
2965 2965 # a.s is useful to pass as a single command line:
2966 2966 In [5]: !wc -l $a.s
2967 2967 146 setup.py
2968 2968 130 win32_manual_post_install.py
2969 2969 276 total
2970 2970
2971 2971 # while the list form is useful to loop over:
2972 2972 In [6]: for f in a.l:
2973 2973 ...: !wc -l $f
2974 2974 ...:
2975 2975 146 setup.py
2976 2976 130 win32_manual_post_install.py
2977 2977
2978 2978 Similiarly, the lists returned by the -l option are also special, in
2979 2979 the sense that you can equally invoke the .s attribute on them to
2980 2980 automatically get a whitespace-separated string from their contents:
2981 2981
2982 2982 In [7]: sc -l b=ls *py
2983 2983
2984 2984 In [8]: b
2985 2985 Out[8]: ['setup.py', 'win32_manual_post_install.py']
2986 2986
2987 2987 In [9]: b.s
2988 2988 Out[9]: 'setup.py win32_manual_post_install.py'
2989 2989
2990 2990 In summary, both the lists and strings used for ouptut capture have
2991 2991 the following special attributes:
2992 2992
2993 2993 .l (or .list) : value as list.
2994 2994 .n (or .nlstr): value as newline-separated string.
2995 2995 .s (or .spstr): value as space-separated string.
2996 2996 """
2997 2997
2998 2998 opts,args = self.parse_options(parameter_s,'lv')
2999 2999 # Try to get a variable name and command to run
3000 3000 try:
3001 3001 # the variable name must be obtained from the parse_options
3002 3002 # output, which uses shlex.split to strip options out.
3003 3003 var,_ = args.split('=',1)
3004 3004 var = var.strip()
3005 3005 # But the the command has to be extracted from the original input
3006 3006 # parameter_s, not on what parse_options returns, to avoid the
3007 3007 # quote stripping which shlex.split performs on it.
3008 3008 _,cmd = parameter_s.split('=',1)
3009 3009 except ValueError:
3010 3010 var,cmd = '',''
3011 3011 # If all looks ok, proceed
3012 3012 out,err = self.shell.getoutputerror(cmd)
3013 3013 if err:
3014 3014 print >> Term.cerr,err
3015 3015 if opts.has_key('l'):
3016 3016 out = SList(out.split('\n'))
3017 3017 else:
3018 3018 out = LSString(out)
3019 3019 if opts.has_key('v'):
3020 3020 print '%s ==\n%s' % (var,pformat(out))
3021 3021 if var:
3022 3022 self.shell.user_ns.update({var:out})
3023 3023 else:
3024 3024 return out
3025 3025
3026 3026 def magic_sx(self, parameter_s=''):
3027 3027 """Shell execute - run a shell command and capture its output.
3028 3028
3029 3029 %sx command
3030 3030
3031 3031 IPython will run the given command using commands.getoutput(), and
3032 3032 return the result formatted as a list (split on '\\n'). Since the
3033 3033 output is _returned_, it will be stored in ipython's regular output
3034 3034 cache Out[N] and in the '_N' automatic variables.
3035 3035
3036 3036 Notes:
3037 3037
3038 3038 1) If an input line begins with '!!', then %sx is automatically
3039 3039 invoked. That is, while:
3040 3040 !ls
3041 3041 causes ipython to simply issue system('ls'), typing
3042 3042 !!ls
3043 3043 is a shorthand equivalent to:
3044 3044 %sx ls
3045 3045
3046 3046 2) %sx differs from %sc in that %sx automatically splits into a list,
3047 3047 like '%sc -l'. The reason for this is to make it as easy as possible
3048 3048 to process line-oriented shell output via further python commands.
3049 3049 %sc is meant to provide much finer control, but requires more
3050 3050 typing.
3051 3051
3052 3052 3) Just like %sc -l, this is a list with special attributes:
3053 3053
3054 3054 .l (or .list) : value as list.
3055 3055 .n (or .nlstr): value as newline-separated string.
3056 3056 .s (or .spstr): value as whitespace-separated string.
3057 3057
3058 3058 This is very useful when trying to use such lists as arguments to
3059 3059 system commands."""
3060 3060
3061 3061 if parameter_s:
3062 3062 out,err = self.shell.getoutputerror(parameter_s)
3063 3063 if err:
3064 3064 print >> Term.cerr,err
3065 3065 return SList(out.split('\n'))
3066 3066
3067 3067 def magic_bg(self, parameter_s=''):
3068 3068 """Run a job in the background, in a separate thread.
3069 3069
3070 3070 For example,
3071 3071
3072 3072 %bg myfunc(x,y,z=1)
3073 3073
3074 3074 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3075 3075 execution starts, a message will be printed indicating the job
3076 3076 number. If your job number is 5, you can use
3077 3077
3078 3078 myvar = jobs.result(5) or myvar = jobs[5].result
3079 3079
3080 3080 to assign this result to variable 'myvar'.
3081 3081
3082 3082 IPython has a job manager, accessible via the 'jobs' object. You can
3083 3083 type jobs? to get more information about it, and use jobs.<TAB> to see
3084 3084 its attributes. All attributes not starting with an underscore are
3085 3085 meant for public use.
3086 3086
3087 3087 In particular, look at the jobs.new() method, which is used to create
3088 3088 new jobs. This magic %bg function is just a convenience wrapper
3089 3089 around jobs.new(), for expression-based jobs. If you want to create a
3090 3090 new job with an explicit function object and arguments, you must call
3091 3091 jobs.new() directly.
3092 3092
3093 3093 The jobs.new docstring also describes in detail several important
3094 3094 caveats associated with a thread-based model for background job
3095 3095 execution. Type jobs.new? for details.
3096 3096
3097 3097 You can check the status of all jobs with jobs.status().
3098 3098
3099 3099 The jobs variable is set by IPython into the Python builtin namespace.
3100 3100 If you ever declare a variable named 'jobs', you will shadow this
3101 3101 name. You can either delete your global jobs variable to regain
3102 3102 access to the job manager, or make a new name and assign it manually
3103 3103 to the manager (stored in IPython's namespace). For example, to
3104 3104 assign the job manager to the Jobs name, use:
3105 3105
3106 3106 Jobs = __builtins__.jobs"""
3107 3107
3108 3108 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3109 3109
3110 3110 def magic_r(self, parameter_s=''):
3111 3111 """Repeat previous input.
3112 3112
3113 3113 Note: Consider using the more powerfull %rep instead!
3114 3114
3115 3115 If given an argument, repeats the previous command which starts with
3116 3116 the same string, otherwise it just repeats the previous input.
3117 3117
3118 3118 Shell escaped commands (with ! as first character) are not recognized
3119 3119 by this system, only pure python code and magic commands.
3120 3120 """
3121 3121
3122 3122 start = parameter_s.strip()
3123 3123 esc_magic = ESC_MAGIC
3124 3124 # Identify magic commands even if automagic is on (which means
3125 3125 # the in-memory version is different from that typed by the user).
3126 3126 if self.shell.automagic:
3127 3127 start_magic = esc_magic+start
3128 3128 else:
3129 3129 start_magic = start
3130 3130 # Look through the input history in reverse
3131 3131 for n in range(len(self.shell.input_hist)-2,0,-1):
3132 3132 input = self.shell.input_hist[n]
3133 3133 # skip plain 'r' lines so we don't recurse to infinity
3134 3134 if input != '_ip.magic("r")\n' and \
3135 3135 (input.startswith(start) or input.startswith(start_magic)):
3136 3136 #print 'match',`input` # dbg
3137 3137 print 'Executing:',input,
3138 3138 self.shell.runlines(input)
3139 3139 return
3140 3140 print 'No previous input matching `%s` found.' % start
3141 3141
3142 3142
3143 3143 def magic_bookmark(self, parameter_s=''):
3144 3144 """Manage IPython's bookmark system.
3145 3145
3146 3146 %bookmark <name> - set bookmark to current dir
3147 3147 %bookmark <name> <dir> - set bookmark to <dir>
3148 3148 %bookmark -l - list all bookmarks
3149 3149 %bookmark -d <name> - remove bookmark
3150 3150 %bookmark -r - remove all bookmarks
3151 3151
3152 3152 You can later on access a bookmarked folder with:
3153 3153 %cd -b <name>
3154 3154 or simply '%cd <name>' if there is no directory called <name> AND
3155 3155 there is such a bookmark defined.
3156 3156
3157 3157 Your bookmarks persist through IPython sessions, but they are
3158 3158 associated with each profile."""
3159 3159
3160 3160 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3161 3161 if len(args) > 2:
3162 3162 raise UsageError("%bookmark: too many arguments")
3163 3163
3164 3164 bkms = self.db.get('bookmarks',{})
3165 3165
3166 3166 if opts.has_key('d'):
3167 3167 try:
3168 3168 todel = args[0]
3169 3169 except IndexError:
3170 3170 raise UsageError(
3171 3171 "%bookmark -d: must provide a bookmark to delete")
3172 3172 else:
3173 3173 try:
3174 3174 del bkms[todel]
3175 3175 except KeyError:
3176 3176 raise UsageError(
3177 3177 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3178 3178
3179 3179 elif opts.has_key('r'):
3180 3180 bkms = {}
3181 3181 elif opts.has_key('l'):
3182 3182 bks = bkms.keys()
3183 3183 bks.sort()
3184 3184 if bks:
3185 3185 size = max(map(len,bks))
3186 3186 else:
3187 3187 size = 0
3188 3188 fmt = '%-'+str(size)+'s -> %s'
3189 3189 print 'Current bookmarks:'
3190 3190 for bk in bks:
3191 3191 print fmt % (bk,bkms[bk])
3192 3192 else:
3193 3193 if not args:
3194 3194 raise UsageError("%bookmark: You must specify the bookmark name")
3195 3195 elif len(args)==1:
3196 3196 bkms[args[0]] = os.getcwd()
3197 3197 elif len(args)==2:
3198 3198 bkms[args[0]] = args[1]
3199 3199 self.db['bookmarks'] = bkms
3200 3200
3201 3201 def magic_pycat(self, parameter_s=''):
3202 3202 """Show a syntax-highlighted file through a pager.
3203 3203
3204 3204 This magic is similar to the cat utility, but it will assume the file
3205 3205 to be Python source and will show it with syntax highlighting. """
3206 3206
3207 3207 try:
3208 3208 filename = get_py_filename(parameter_s)
3209 3209 cont = file_read(filename)
3210 3210 except IOError:
3211 3211 try:
3212 3212 cont = eval(parameter_s,self.user_ns)
3213 3213 except NameError:
3214 3214 cont = None
3215 3215 if cont is None:
3216 3216 print "Error: no such file or variable"
3217 3217 return
3218 3218
3219 3219 page(self.shell.pycolorize(cont),
3220 3220 screen_lines=self.shell.usable_screen_length)
3221 3221
3222 3222 def _rerun_pasted(self):
3223 3223 """ Rerun a previously pasted command.
3224 3224 """
3225 3225 b = self.user_ns.get('pasted_block', None)
3226 3226 if b is None:
3227 3227 raise UsageError('No previous pasted block available')
3228 3228 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3229 3229 exec b in self.user_ns
3230 3230
3231 3231 def _get_pasted_lines(self, sentinel):
3232 3232 """ Yield pasted lines until the user enters the given sentinel value.
3233 3233 """
3234 3234 from IPython.core import iplib
3235 3235 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3236 3236 while True:
3237 3237 l = iplib.raw_input_original(':')
3238 3238 if l == sentinel:
3239 3239 return
3240 3240 else:
3241 3241 yield l
3242 3242
3243 3243 def _strip_pasted_lines_for_code(self, raw_lines):
3244 3244 """ Strip non-code parts of a sequence of lines to return a block of
3245 3245 code.
3246 3246 """
3247 3247 # Regular expressions that declare text we strip from the input:
3248 3248 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3249 3249 r'^\s*(\s?>)+', # Python input prompt
3250 3250 r'^\s*\.{3,}', # Continuation prompts
3251 3251 r'^\++',
3252 3252 ]
3253 3253
3254 3254 strip_from_start = map(re.compile,strip_re)
3255 3255
3256 3256 lines = []
3257 3257 for l in raw_lines:
3258 3258 for pat in strip_from_start:
3259 3259 l = pat.sub('',l)
3260 3260 lines.append(l)
3261 3261
3262 3262 block = "\n".join(lines) + '\n'
3263 3263 #print "block:\n",block
3264 3264 return block
3265 3265
3266 3266 def _execute_block(self, block, par):
3267 3267 """ Execute a block, or store it in a variable, per the user's request.
3268 3268 """
3269 3269 if not par:
3270 3270 b = textwrap.dedent(block)
3271 3271 self.user_ns['pasted_block'] = b
3272 3272 exec b in self.user_ns
3273 3273 else:
3274 3274 self.user_ns[par] = SList(block.splitlines())
3275 3275 print "Block assigned to '%s'" % par
3276 3276
3277 3277 def magic_cpaste(self, parameter_s=''):
3278 3278 """Allows you to paste & execute a pre-formatted code block from clipboard.
3279 3279
3280 3280 You must terminate the block with '--' (two minus-signs) alone on the
3281 3281 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3282 3282 is the new sentinel for this operation)
3283 3283
3284 3284 The block is dedented prior to execution to enable execution of method
3285 3285 definitions. '>' and '+' characters at the beginning of a line are
3286 3286 ignored, to allow pasting directly from e-mails, diff files and
3287 3287 doctests (the '...' continuation prompt is also stripped). The
3288 3288 executed block is also assigned to variable named 'pasted_block' for
3289 3289 later editing with '%edit pasted_block'.
3290 3290
3291 3291 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3292 3292 This assigns the pasted block to variable 'foo' as string, without
3293 3293 dedenting or executing it (preceding >>> and + is still stripped)
3294 3294
3295 3295 '%cpaste -r' re-executes the block previously entered by cpaste.
3296 3296
3297 3297 Do not be alarmed by garbled output on Windows (it's a readline bug).
3298 3298 Just press enter and type -- (and press enter again) and the block
3299 3299 will be what was just pasted.
3300 3300
3301 3301 IPython statements (magics, shell escapes) are not supported (yet).
3302 3302
3303 3303 See also
3304 3304 --------
3305 3305 paste: automatically pull code from clipboard.
3306 3306 """
3307 3307
3308 3308 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3309 3309 par = args.strip()
3310 3310 if opts.has_key('r'):
3311 3311 self._rerun_pasted()
3312 3312 return
3313 3313
3314 3314 sentinel = opts.get('s','--')
3315 3315
3316 3316 block = self._strip_pasted_lines_for_code(
3317 3317 self._get_pasted_lines(sentinel))
3318 3318
3319 3319 self._execute_block(block, par)
3320 3320
3321 3321 def magic_paste(self, parameter_s=''):
3322 3322 """Allows you to paste & execute a pre-formatted code block from clipboard.
3323 3323
3324 3324 The text is pulled directly from the clipboard without user
3325 3325 intervention and printed back on the screen before execution (unless
3326 3326 the -q flag is given to force quiet mode).
3327 3327
3328 3328 The block is dedented prior to execution to enable execution of method
3329 3329 definitions. '>' and '+' characters at the beginning of a line are
3330 3330 ignored, to allow pasting directly from e-mails, diff files and
3331 3331 doctests (the '...' continuation prompt is also stripped). The
3332 3332 executed block is also assigned to variable named 'pasted_block' for
3333 3333 later editing with '%edit pasted_block'.
3334 3334
3335 3335 You can also pass a variable name as an argument, e.g. '%paste foo'.
3336 3336 This assigns the pasted block to variable 'foo' as string, without
3337 3337 dedenting or executing it (preceding >>> and + is still stripped)
3338 3338
3339 3339 Options
3340 3340 -------
3341 3341
3342 3342 -r: re-executes the block previously entered by cpaste.
3343 3343
3344 3344 -q: quiet mode: do not echo the pasted text back to the terminal.
3345 3345
3346 3346 IPython statements (magics, shell escapes) are not supported (yet).
3347 3347
3348 3348 See also
3349 3349 --------
3350 3350 cpaste: manually paste code into terminal until you mark its end.
3351 3351 """
3352 3352 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3353 3353 par = args.strip()
3354 3354 if opts.has_key('r'):
3355 3355 self._rerun_pasted()
3356 3356 return
3357 3357
3358 3358 text = self.shell.hooks.clipboard_get()
3359 3359 block = self._strip_pasted_lines_for_code(text.splitlines())
3360 3360
3361 3361 # By default, echo back to terminal unless quiet mode is requested
3362 3362 if not opts.has_key('q'):
3363 3363 write = self.shell.write
3364 3364 write(self.shell.pycolorize(block))
3365 3365 if not block.endswith('\n'):
3366 3366 write('\n')
3367 3367 write("## -- End pasted text --\n")
3368 3368
3369 3369 self._execute_block(block, par)
3370 3370
3371 3371 def magic_quickref(self,arg):
3372 3372 """ Show a quick reference sheet """
3373 3373 import IPython.core.usage
3374 3374 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3375 3375
3376 3376 page(qr)
3377 3377
3378 3378 def magic_doctest_mode(self,parameter_s=''):
3379 3379 """Toggle doctest mode on and off.
3380 3380
3381 3381 This mode allows you to toggle the prompt behavior between normal
3382 3382 IPython prompts and ones that are as similar to the default IPython
3383 3383 interpreter as possible.
3384 3384
3385 3385 It also supports the pasting of code snippets that have leading '>>>'
3386 3386 and '...' prompts in them. This means that you can paste doctests from
3387 3387 files or docstrings (even if they have leading whitespace), and the
3388 3388 code will execute correctly. You can then use '%history -tn' to see
3389 3389 the translated history without line numbers; this will give you the
3390 3390 input after removal of all the leading prompts and whitespace, which
3391 3391 can be pasted back into an editor.
3392 3392
3393 3393 With these features, you can switch into this mode easily whenever you
3394 3394 need to do testing and changes to doctests, without having to leave
3395 3395 your existing IPython session.
3396 3396 """
3397 3397
3398 3398 # XXX - Fix this to have cleaner activate/deactivate calls.
3399 3399 from IPython.extensions import InterpreterPasteInput as ipaste
3400 3400 from IPython.utils.ipstruct import Struct
3401 3401
3402 3402 # Shorthands
3403 3403 shell = self.shell
3404 3404 oc = shell.outputcache
3405 3405 meta = shell.meta
3406 3406 # dstore is a data store kept in the instance metadata bag to track any
3407 3407 # changes we make, so we can undo them later.
3408 3408 dstore = meta.setdefault('doctest_mode',Struct())
3409 3409 save_dstore = dstore.setdefault
3410 3410
3411 3411 # save a few values we'll need to recover later
3412 3412 mode = save_dstore('mode',False)
3413 3413 save_dstore('rc_pprint',shell.pprint)
3414 3414 save_dstore('xmode',shell.InteractiveTB.mode)
3415 3415 save_dstore('rc_separate_out',shell.separate_out)
3416 3416 save_dstore('rc_separate_out2',shell.separate_out2)
3417 3417 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3418 3418 save_dstore('rc_separate_in',shell.separate_in)
3419 3419
3420 3420 if mode == False:
3421 3421 # turn on
3422 3422 ipaste.activate_prefilter()
3423 3423
3424 3424 oc.prompt1.p_template = '>>> '
3425 3425 oc.prompt2.p_template = '... '
3426 3426 oc.prompt_out.p_template = ''
3427 3427
3428 3428 # Prompt separators like plain python
3429 3429 oc.input_sep = oc.prompt1.sep = ''
3430 3430 oc.output_sep = ''
3431 3431 oc.output_sep2 = ''
3432 3432
3433 3433 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3434 3434 oc.prompt_out.pad_left = False
3435 3435
3436 3436 shell.pprint = False
3437 3437
3438 3438 shell.magic_xmode('Plain')
3439 3439
3440 3440 else:
3441 3441 # turn off
3442 3442 ipaste.deactivate_prefilter()
3443 3443
3444 3444 oc.prompt1.p_template = shell.prompt_in1
3445 3445 oc.prompt2.p_template = shell.prompt_in2
3446 3446 oc.prompt_out.p_template = shell.prompt_out
3447 3447
3448 3448 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3449 3449
3450 3450 oc.output_sep = dstore.rc_separate_out
3451 3451 oc.output_sep2 = dstore.rc_separate_out2
3452 3452
3453 3453 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3454 3454 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3455 3455
3456 3456 rc.pprint = dstore.rc_pprint
3457 3457
3458 3458 shell.magic_xmode(dstore.xmode)
3459 3459
3460 3460 # Store new mode and inform
3461 3461 dstore.mode = bool(1-int(mode))
3462 3462 print 'Doctest mode is:',
3463 3463 print ['OFF','ON'][dstore.mode]
3464 3464
3465 3465 def magic_gui(self, parameter_s=''):
3466 3466 """Enable or disable IPython GUI event loop integration.
3467 3467
3468 3468 %gui [-a] [GUINAME]
3469 3469
3470 3470 This magic replaces IPython's threaded shells that were activated
3471 3471 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3472 3472 can now be enabled, disabled and swtiched at runtime and keyboard
3473 3473 interrupts should work without any problems. The following toolkits
3474 3474 are supported: wxPython, PyQt4, PyGTK, and Tk::
3475 3475
3476 3476 %gui wx # enable wxPython event loop integration
3477 3477 %gui qt4|qt # enable PyQt4 event loop integration
3478 3478 %gui gtk # enable PyGTK event loop integration
3479 3479 %gui tk # enable Tk event loop integration
3480 3480 %gui # disable all event loop integration
3481 3481
3482 3482 WARNING: after any of these has been called you can simply create
3483 3483 an application object, but DO NOT start the event loop yourself, as
3484 3484 we have already handled that.
3485 3485
3486 3486 If you want us to create an appropriate application object add the
3487 3487 "-a" flag to your command::
3488 3488
3489 3489 %gui -a wx
3490 3490
3491 3491 This is highly recommended for most users.
3492 3492 """
3493 3493 opts, arg = self.parse_options(parameter_s,'a')
3494 3494 if arg=='': arg = None
3495 3495 return enable_gui(arg, 'a' in opts)
3496 3496
3497 3497 def magic_load_ext(self, module_str):
3498 3498 """Load an IPython extension by its module name."""
3499 3499 self.load_extension(module_str)
3500 3500
3501 3501 def magic_unload_ext(self, module_str):
3502 3502 """Unload an IPython extension by its module name."""
3503 3503 self.unload_extension(module_str)
3504 3504
3505 3505 def magic_reload_ext(self, module_str):
3506 3506 """Reload an IPython extension by its module name."""
3507 3507 self.reload_extension(module_str)
3508 3508
3509 @testdec.skip_doctest
3509 3510 def magic_install_profiles(self, s):
3510 3511 """Install the default IPython profiles into the .ipython dir.
3511 3512
3512 3513 If the default profiles have already been installed, they will not
3513 3514 be overwritten. You can force overwriting them by using the ``-o``
3514 3515 option::
3515 3516
3516 3517 In [1]: %install_profiles -o
3517 3518 """
3518 3519 if '-o' in s:
3519 3520 overwrite = True
3520 3521 else:
3521 3522 overwrite = False
3522 3523 from IPython.config import profile
3523 3524 profile_dir = os.path.split(profile.__file__)[0]
3524 3525 ipython_dir = self.ipython_dir
3525 3526 files = os.listdir(profile_dir)
3526 3527
3527 3528 to_install = []
3528 3529 for f in files:
3529 3530 if f.startswith('ipython_config'):
3530 3531 src = os.path.join(profile_dir, f)
3531 3532 dst = os.path.join(ipython_dir, f)
3532 3533 if (not os.path.isfile(dst)) or overwrite:
3533 3534 to_install.append((f, src, dst))
3534 3535 if len(to_install)>0:
3535 3536 print "Installing profiles to: ", ipython_dir
3536 3537 for (f, src, dst) in to_install:
3537 3538 shutil.copy(src, dst)
3538 3539 print " %s" % f
3539 3540
3540 3541 def magic_install_default_config(self, s):
3541 3542 """Install IPython's default config file into the .ipython dir.
3542 3543
3543 3544 If the default config file (:file:`ipython_config.py`) is already
3544 3545 installed, it will not be overwritten. You can force overwriting
3545 3546 by using the ``-o`` option::
3546 3547
3547 3548 In [1]: %install_default_config
3548 3549 """
3549 3550 if '-o' in s:
3550 3551 overwrite = True
3551 3552 else:
3552 3553 overwrite = False
3553 3554 from IPython.config import default
3554 3555 config_dir = os.path.split(default.__file__)[0]
3555 3556 ipython_dir = self.ipython_dir
3556 3557 default_config_file_name = 'ipython_config.py'
3557 3558 src = os.path.join(config_dir, default_config_file_name)
3558 3559 dst = os.path.join(ipython_dir, default_config_file_name)
3559 3560 if (not os.path.isfile(dst)) or overwrite:
3560 3561 shutil.copy(src, dst)
3561 3562 print "Installing default config file: %s" % dst
3562 3563
3563 3564 # Pylab support: simple wrappers that activate pylab, load gui input
3564 3565 # handling and modify slightly %run
3565 3566
3566 3567 @testdec.skip_doctest
3567 3568 def _pylab_magic_run(self, parameter_s=''):
3568 3569 Magic.magic_run(self, parameter_s,
3569 3570 runner=mpl_runner(self.shell.safe_execfile))
3570 3571
3571 3572 _pylab_magic_run.__doc__ = magic_run.__doc__
3572 3573
3573 3574 @testdec.skip_doctest
3574 3575 def magic_pylab(self, s):
3575 3576 """Load numpy and matplotlib to work interactively.
3576 3577
3577 3578 %pylab [GUINAME]
3578 3579
3579 3580 This function lets you activate pylab (matplotlib, numpy and
3580 3581 interactive support) at any point during an IPython session.
3581 3582
3582 3583 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3583 3584 pylab and mlab, as well as all names from numpy and pylab.
3584 3585
3585 3586 Parameters
3586 3587 ----------
3587 3588 guiname : optional
3588 3589 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3589 3590 'tk'). If given, the corresponding Matplotlib backend is used,
3590 3591 otherwise matplotlib's default (which you can override in your
3591 3592 matplotlib config file) is used.
3592 3593
3593 3594 Examples
3594 3595 --------
3595 3596 In this case, where the MPL default is TkAgg:
3596 3597 In [2]: %pylab
3597 3598
3598 3599 Welcome to pylab, a matplotlib-based Python environment.
3599 3600 Backend in use: TkAgg
3600 3601 For more information, type 'help(pylab)'.
3601 3602
3602 3603 But you can explicitly request a different backend:
3603 3604 In [3]: %pylab qt
3604 3605
3605 3606 Welcome to pylab, a matplotlib-based Python environment.
3606 3607 Backend in use: Qt4Agg
3607 3608 For more information, type 'help(pylab)'.
3608 3609 """
3609 3610 self.shell.enable_pylab(s)
3610 3611
3611 3612 # end Magic
@@ -1,994 +1,994 b''
1 1 #!/usr/bin/env python
2 2 # encoding: utf-8
3 3 """
4 4 Prefiltering components.
5 5
6 6 Prefilters transform user input before it is exec'd by Python. These
7 7 transforms are used to implement additional syntax such as !ls and %magic.
8 8
9 9 Authors:
10 10
11 11 * Brian Granger
12 12 * Fernando Perez
13 13 * Dan Milstein
14 14 * Ville Vainio
15 15 """
16 16
17 17 #-----------------------------------------------------------------------------
18 18 # Copyright (C) 2008-2009 The IPython Development Team
19 19 #
20 20 # Distributed under the terms of the BSD License. The full license is in
21 21 # the file COPYING, distributed as part of this software.
22 22 #-----------------------------------------------------------------------------
23 23
24 24 #-----------------------------------------------------------------------------
25 25 # Imports
26 26 #-----------------------------------------------------------------------------
27 27
28 28 import __builtin__
29 29 import codeop
30 30 import keyword
31 31 import os
32 32 import re
33 33 import sys
34 34
35 35 from IPython.core.alias import AliasManager
36 36 from IPython.core.autocall import IPyAutocall
37 37 from IPython.core.component import Component
38 38 from IPython.core.splitinput import split_user_input
39 39 from IPython.core.page import page
40 40
41 41 from IPython.utils.traitlets import List, Int, Any, Str, CBool, Bool
42 42 from IPython.utils.genutils import make_quoted_expr, Term
43 43 from IPython.utils.autoattr import auto_attr
44 44
45 45 #-----------------------------------------------------------------------------
46 46 # Global utilities, errors and constants
47 47 #-----------------------------------------------------------------------------
48 48
49 49 # Warning, these cannot be changed unless various regular expressions
50 50 # are updated in a number of places. Not great, but at least we told you.
51 51 ESC_SHELL = '!'
52 52 ESC_SH_CAP = '!!'
53 53 ESC_HELP = '?'
54 54 ESC_MAGIC = '%'
55 55 ESC_QUOTE = ','
56 56 ESC_QUOTE2 = ';'
57 57 ESC_PAREN = '/'
58 58
59 59
60 60 class PrefilterError(Exception):
61 61 pass
62 62
63 63
64 64 # RegExp to identify potential function names
65 65 re_fun_name = re.compile(r'[a-zA-Z_]([a-zA-Z0-9_.]*) *$')
66 66
67 67 # RegExp to exclude strings with this start from autocalling. In
68 68 # particular, all binary operators should be excluded, so that if foo is
69 69 # callable, foo OP bar doesn't become foo(OP bar), which is invalid. The
70 70 # characters '!=()' don't need to be checked for, as the checkPythonChars
71 71 # routine explicitely does so, to catch direct calls and rebindings of
72 72 # existing names.
73 73
74 74 # Warning: the '-' HAS TO BE AT THE END of the first group, otherwise
75 75 # it affects the rest of the group in square brackets.
76 76 re_exclude_auto = re.compile(r'^[,&^\|\*/\+-]'
77 77 r'|^is |^not |^in |^and |^or ')
78 78
79 79 # try to catch also methods for stuff in lists/tuples/dicts: off
80 80 # (experimental). For this to work, the line_split regexp would need
81 81 # to be modified so it wouldn't break things at '['. That line is
82 82 # nasty enough that I shouldn't change it until I can test it _well_.
83 83 #self.re_fun_name = re.compile (r'[a-zA-Z_]([a-zA-Z0-9_.\[\]]*) ?$')
84 84
85 85
86 86 # Handler Check Utilities
87 87 def is_shadowed(identifier, ip):
88 88 """Is the given identifier defined in one of the namespaces which shadow
89 89 the alias and magic namespaces? Note that an identifier is different
90 90 than ifun, because it can not contain a '.' character."""
91 91 # This is much safer than calling ofind, which can change state
92 92 return (identifier in ip.user_ns \
93 93 or identifier in ip.internal_ns \
94 94 or identifier in ip.ns_table['builtin'])
95 95
96 96
97 97 #-----------------------------------------------------------------------------
98 98 # The LineInfo class used throughout
99 99 #-----------------------------------------------------------------------------
100 100
101 101
102 102 class LineInfo(object):
103 103 """A single line of input and associated info.
104 104
105 105 Includes the following as properties:
106 106
107 107 line
108 108 The original, raw line
109 109
110 110 continue_prompt
111 111 Is this line a continuation in a sequence of multiline input?
112 112
113 113 pre
114 114 The initial esc character or whitespace.
115 115
116 116 pre_char
117 117 The escape character(s) in pre or the empty string if there isn't one.
118 118 Note that '!!' is a possible value for pre_char. Otherwise it will
119 119 always be a single character.
120 120
121 121 pre_whitespace
122 122 The leading whitespace from pre if it exists. If there is a pre_char,
123 123 this is just ''.
124 124
125 125 ifun
126 126 The 'function part', which is basically the maximal initial sequence
127 127 of valid python identifiers and the '.' character. This is what is
128 128 checked for alias and magic transformations, used for auto-calling,
129 129 etc.
130 130
131 131 the_rest
132 132 Everything else on the line.
133 133 """
134 134 def __init__(self, line, continue_prompt):
135 135 self.line = line
136 136 self.continue_prompt = continue_prompt
137 137 self.pre, self.ifun, self.the_rest = split_user_input(line)
138 138
139 139 self.pre_char = self.pre.strip()
140 140 if self.pre_char:
141 141 self.pre_whitespace = '' # No whitespace allowd before esc chars
142 142 else:
143 143 self.pre_whitespace = self.pre
144 144
145 145 self._oinfo = None
146 146
147 147 def ofind(self, ip):
148 148 """Do a full, attribute-walking lookup of the ifun in the various
149 149 namespaces for the given IPython InteractiveShell instance.
150 150
151 151 Return a dict with keys: found,obj,ospace,ismagic
152 152
153 153 Note: can cause state changes because of calling getattr, but should
154 154 only be run if autocall is on and if the line hasn't matched any
155 155 other, less dangerous handlers.
156 156
157 157 Does cache the results of the call, so can be called multiple times
158 158 without worrying about *further* damaging state.
159 159 """
160 160 if not self._oinfo:
161 161 self._oinfo = ip.shell._ofind(self.ifun)
162 162 return self._oinfo
163 163
164 164 def __str__(self):
165 165 return "Lineinfo [%s|%s|%s]" %(self.pre,self.ifun,self.the_rest)
166 166
167 167
168 168 #-----------------------------------------------------------------------------
169 169 # Main Prefilter manager
170 170 #-----------------------------------------------------------------------------
171 171
172 172
173 173 class PrefilterManager(Component):
174 174 """Main prefilter component.
175 175
176 176 The IPython prefilter is run on all user input before it is run. The
177 177 prefilter consumes lines of input and produces transformed lines of
178 178 input.
179 179
180 180 The iplementation consists of two phases:
181 181
182 182 1. Transformers
183 183 2. Checkers and handlers
184 184
185 185 Over time, we plan on deprecating the checkers and handlers and doing
186 186 everything in the transformers.
187 187
188 188 The transformers are instances of :class:`PrefilterTransformer` and have
189 189 a single method :meth:`transform` that takes a line and returns a
190 190 transformed line. The transformation can be accomplished using any
191 191 tool, but our current ones use regular expressions for speed. We also
192 192 ship :mod:`pyparsing` in :mod:`IPython.external` for use in transformers.
193 193
194 194 After all the transformers have been run, the line is fed to the checkers,
195 195 which are instances of :class:`PrefilterChecker`. The line is passed to
196 196 the :meth:`check` method, which either returns `None` or a
197 197 :class:`PrefilterHandler` instance. If `None` is returned, the other
198 198 checkers are tried. If an :class:`PrefilterHandler` instance is returned,
199 199 the line is passed to the :meth:`handle` method of the returned
200 200 handler and no further checkers are tried.
201 201
202 202 Both transformers and checkers have a `priority` attribute, that determines
203 203 the order in which they are called. Smaller priorities are tried first.
204 204
205 205 Both transformers and checkers also have `enabled` attribute, which is
206 206 a boolean that determines if the instance is used.
207 207
208 208 Users or developers can change the priority or enabled attribute of
209 209 transformers or checkers, but they must call the :meth:`sort_checkers`
210 210 or :meth:`sort_transformers` method after changing the priority.
211 211 """
212 212
213 213 multi_line_specials = CBool(True, config=True)
214 214
215 215 def __init__(self, parent, config=None):
216 216 super(PrefilterManager, self).__init__(parent, config=config)
217 217 self.init_transformers()
218 218 self.init_handlers()
219 219 self.init_checkers()
220 220
221 221 @auto_attr
222 222 def shell(self):
223 223 return Component.get_instances(
224 224 root=self.root,
225 225 klass='IPython.core.iplib.InteractiveShell')[0]
226 226
227 227 #-------------------------------------------------------------------------
228 228 # API for managing transformers
229 229 #-------------------------------------------------------------------------
230 230
231 231 def init_transformers(self):
232 232 """Create the default transformers."""
233 233 self._transformers = []
234 234 for transformer_cls in _default_transformers:
235 235 transformer_cls(self, config=self.config)
236 236
237 237 def sort_transformers(self):
238 238 """Sort the transformers by priority.
239 239
240 240 This must be called after the priority of a transformer is changed.
241 241 The :meth:`register_transformer` method calls this automatically.
242 242 """
243 243 self._transformers.sort(cmp=lambda x,y: x.priority-y.priority)
244 244
245 245 @property
246 246 def transformers(self):
247 247 """Return a list of checkers, sorted by priority."""
248 248 return self._transformers
249 249
250 250 def register_transformer(self, transformer):
251 251 """Register a transformer instance."""
252 252 if transformer not in self._transformers:
253 253 self._transformers.append(transformer)
254 254 self.sort_transformers()
255 255
256 256 def unregister_transformer(self, transformer):
257 257 """Unregister a transformer instance."""
258 258 if transformer in self._transformers:
259 259 self._transformers.remove(transformer)
260 260
261 261 #-------------------------------------------------------------------------
262 262 # API for managing checkers
263 263 #-------------------------------------------------------------------------
264 264
265 265 def init_checkers(self):
266 266 """Create the default checkers."""
267 267 self._checkers = []
268 268 for checker in _default_checkers:
269 269 checker(self, config=self.config)
270 270
271 271 def sort_checkers(self):
272 272 """Sort the checkers by priority.
273 273
274 274 This must be called after the priority of a checker is changed.
275 275 The :meth:`register_checker` method calls this automatically.
276 276 """
277 277 self._checkers.sort(cmp=lambda x,y: x.priority-y.priority)
278 278
279 279 @property
280 280 def checkers(self):
281 281 """Return a list of checkers, sorted by priority."""
282 282 return self._checkers
283 283
284 284 def register_checker(self, checker):
285 285 """Register a checker instance."""
286 286 if checker not in self._checkers:
287 287 self._checkers.append(checker)
288 288 self.sort_checkers()
289 289
290 290 def unregister_checker(self, checker):
291 291 """Unregister a checker instance."""
292 292 if checker in self._checkers:
293 293 self._checkers.remove(checker)
294 294
295 295 #-------------------------------------------------------------------------
296 296 # API for managing checkers
297 297 #-------------------------------------------------------------------------
298 298
299 299 def init_handlers(self):
300 300 """Create the default handlers."""
301 301 self._handlers = {}
302 302 self._esc_handlers = {}
303 303 for handler in _default_handlers:
304 304 handler(self, config=self.config)
305 305
306 306 @property
307 307 def handlers(self):
308 308 """Return a dict of all the handlers."""
309 309 return self._handlers
310 310
311 311 def register_handler(self, name, handler, esc_strings):
312 312 """Register a handler instance by name with esc_strings."""
313 313 self._handlers[name] = handler
314 314 for esc_str in esc_strings:
315 315 self._esc_handlers[esc_str] = handler
316 316
317 317 def unregister_handler(self, name, handler, esc_strings):
318 318 """Unregister a handler instance by name with esc_strings."""
319 319 try:
320 320 del self._handlers[name]
321 321 except KeyError:
322 322 pass
323 323 for esc_str in esc_strings:
324 324 h = self._esc_handlers.get(esc_str)
325 325 if h is handler:
326 326 del self._esc_handlers[esc_str]
327 327
328 328 def get_handler_by_name(self, name):
329 329 """Get a handler by its name."""
330 330 return self._handlers.get(name)
331 331
332 332 def get_handler_by_esc(self, esc_str):
333 333 """Get a handler by its escape string."""
334 334 return self._esc_handlers.get(esc_str)
335 335
336 336 #-------------------------------------------------------------------------
337 337 # Main prefiltering API
338 338 #-------------------------------------------------------------------------
339 339
340 340 def prefilter_line_info(self, line_info):
341 341 """Prefilter a line that has been converted to a LineInfo object.
342 342
343 343 This implements the checker/handler part of the prefilter pipe.
344 344 """
345 345 # print "prefilter_line_info: ", line_info
346 346 handler = self.find_handler(line_info)
347 347 return handler.handle(line_info)
348 348
349 349 def find_handler(self, line_info):
350 350 """Find a handler for the line_info by trying checkers."""
351 351 for checker in self.checkers:
352 352 if checker.enabled:
353 353 handler = checker.check(line_info)
354 354 if handler:
355 355 return handler
356 356 return self.get_handler_by_name('normal')
357 357
358 358 def transform_line(self, line, continue_prompt):
359 359 """Calls the enabled transformers in order of increasing priority."""
360 360 for transformer in self.transformers:
361 361 if transformer.enabled:
362 362 line = transformer.transform(line, continue_prompt)
363 363 return line
364 364
365 365 def prefilter_line(self, line, continue_prompt):
366 366 """Prefilter a single input line as text.
367 367
368 368 This method prefilters a single line of text by calling the
369 369 transformers and then the checkers/handlers.
370 370 """
371 371
372 372 # print "prefilter_line: ", line, continue_prompt
373 373 # All handlers *must* return a value, even if it's blank ('').
374 374
375 375 # Lines are NOT logged here. Handlers should process the line as
376 376 # needed, update the cache AND log it (so that the input cache array
377 377 # stays synced).
378 378
379 379 # save the line away in case we crash, so the post-mortem handler can
380 380 # record it
381 381 self.shell._last_input_line = line
382 382
383 383 if not line:
384 384 # Return immediately on purely empty lines, so that if the user
385 385 # previously typed some whitespace that started a continuation
386 386 # prompt, he can break out of that loop with just an empty line.
387 387 # This is how the default python prompt works.
388 388
389 389 # Only return if the accumulated input buffer was just whitespace!
390 390 if ''.join(self.shell.buffer).isspace():
391 391 self.shell.buffer[:] = []
392 392 return ''
393 393
394 394 # At this point, we invoke our transformers.
395 395 if not continue_prompt or (continue_prompt and self.multi_line_specials):
396 396 line = self.transform_line(line, continue_prompt)
397 397
398 398 # Now we compute line_info for the checkers and handlers
399 399 line_info = LineInfo(line, continue_prompt)
400 400
401 401 # the input history needs to track even empty lines
402 402 stripped = line.strip()
403 403
404 404 normal_handler = self.get_handler_by_name('normal')
405 405 if not stripped:
406 406 if not continue_prompt:
407 407 self.shell.outputcache.prompt_count -= 1
408 408
409 409 return normal_handler.handle(line_info)
410 410
411 411 # special handlers are only allowed for single line statements
412 412 if continue_prompt and not self.multi_line_specials:
413 413 return normal_handler.handle(line_info)
414 414
415 415 prefiltered = self.prefilter_line_info(line_info)
416 416 # print "prefiltered line: %r" % prefiltered
417 417 return prefiltered
418 418
419 def prefilter_lines(self, lines, continue_prompt):
419 def prefilter_lines(self, lines, continue_prompt=False):
420 420 """Prefilter multiple input lines of text.
421 421
422 422 This is the main entry point for prefiltering multiple lines of
423 423 input. This simply calls :meth:`prefilter_line` for each line of
424 424 input.
425 425
426 426 This covers cases where there are multiple lines in the user entry,
427 427 which is the case when the user goes back to a multiline history
428 428 entry and presses enter.
429 429 """
430 430 out = []
431 431 for line in lines.rstrip('\n').split('\n'):
432 432 out.append(self.prefilter_line(line, continue_prompt))
433 433 return '\n'.join(out)
434 434
435 435
436 436 #-----------------------------------------------------------------------------
437 437 # Prefilter transformers
438 438 #-----------------------------------------------------------------------------
439 439
440 440
441 441 class PrefilterTransformer(Component):
442 442 """Transform a line of user input."""
443 443
444 444 priority = Int(100, config=True)
445 445 shell = Any
446 446 prefilter_manager = Any
447 447 enabled = Bool(True, config=True)
448 448
449 449 def __init__(self, parent, config=None):
450 450 super(PrefilterTransformer, self).__init__(parent, config=config)
451 451 self.prefilter_manager.register_transformer(self)
452 452
453 453 @auto_attr
454 454 def shell(self):
455 455 return Component.get_instances(
456 456 root=self.root,
457 457 klass='IPython.core.iplib.InteractiveShell')[0]
458 458
459 459 @auto_attr
460 460 def prefilter_manager(self):
461 461 return PrefilterManager.get_instances(root=self.root)[0]
462 462
463 463 def transform(self, line, continue_prompt):
464 464 """Transform a line, returning the new one."""
465 465 return None
466 466
467 467 def __repr__(self):
468 468 return "<%s(priority=%r, enabled=%r)>" % (
469 469 self.__class__.__name__, self.priority, self.enabled)
470 470
471 471
472 472 _assign_system_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
473 473 r'\s*=\s*!(?P<cmd>.*)')
474 474
475 475
476 476 class AssignSystemTransformer(PrefilterTransformer):
477 477 """Handle the `files = !ls` syntax."""
478 478
479 479 priority = Int(100, config=True)
480 480
481 481 def transform(self, line, continue_prompt):
482 482 m = _assign_system_re.match(line)
483 483 if m is not None:
484 484 cmd = m.group('cmd')
485 485 lhs = m.group('lhs')
486 486 expr = make_quoted_expr("sc -l =%s" % cmd)
487 487 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
488 488 return new_line
489 489 return line
490 490
491 491
492 492 _assign_magic_re = re.compile(r'(?P<lhs>(\s*)([\w\.]+)((\s*,\s*[\w\.]+)*))'
493 493 r'\s*=\s*%(?P<cmd>.*)')
494 494
495 495 class AssignMagicTransformer(PrefilterTransformer):
496 496 """Handle the `a = %who` syntax."""
497 497
498 498 priority = Int(200, config=True)
499 499
500 500 def transform(self, line, continue_prompt):
501 501 m = _assign_magic_re.match(line)
502 502 if m is not None:
503 503 cmd = m.group('cmd')
504 504 lhs = m.group('lhs')
505 505 expr = make_quoted_expr(cmd)
506 506 new_line = '%s = get_ipython().magic(%s)' % (lhs, expr)
507 507 return new_line
508 508 return line
509 509
510 510
511 511 #-----------------------------------------------------------------------------
512 512 # Prefilter checkers
513 513 #-----------------------------------------------------------------------------
514 514
515 515
516 516 class PrefilterChecker(Component):
517 517 """Inspect an input line and return a handler for that line."""
518 518
519 519 priority = Int(100, config=True)
520 520 shell = Any
521 521 prefilter_manager = Any
522 522 enabled = Bool(True, config=True)
523 523
524 524 def __init__(self, parent, config=None):
525 525 super(PrefilterChecker, self).__init__(parent, config=config)
526 526 self.prefilter_manager.register_checker(self)
527 527
528 528 @auto_attr
529 529 def shell(self):
530 530 return Component.get_instances(
531 531 root=self.root,
532 532 klass='IPython.core.iplib.InteractiveShell')[0]
533 533
534 534 @auto_attr
535 535 def prefilter_manager(self):
536 536 return PrefilterManager.get_instances(root=self.root)[0]
537 537
538 538 def check(self, line_info):
539 539 """Inspect line_info and return a handler instance or None."""
540 540 return None
541 541
542 542 def __repr__(self):
543 543 return "<%s(priority=%r, enabled=%r)>" % (
544 544 self.__class__.__name__, self.priority, self.enabled)
545 545
546 546
547 547 class EmacsChecker(PrefilterChecker):
548 548
549 549 priority = Int(100, config=True)
550 550 enabled = Bool(False, config=True)
551 551
552 552 def check(self, line_info):
553 553 "Emacs ipython-mode tags certain input lines."
554 554 if line_info.line.endswith('# PYTHON-MODE'):
555 555 return self.prefilter_manager.get_handler_by_name('emacs')
556 556 else:
557 557 return None
558 558
559 559
560 560 class ShellEscapeChecker(PrefilterChecker):
561 561
562 562 priority = Int(200, config=True)
563 563
564 564 def check(self, line_info):
565 565 if line_info.line.lstrip().startswith(ESC_SHELL):
566 566 return self.prefilter_manager.get_handler_by_name('shell')
567 567
568 568
569 569 class IPyAutocallChecker(PrefilterChecker):
570 570
571 571 priority = Int(300, config=True)
572 572
573 573 def check(self, line_info):
574 574 "Instances of IPyAutocall in user_ns get autocalled immediately"
575 575 obj = self.shell.user_ns.get(line_info.ifun, None)
576 576 if isinstance(obj, IPyAutocall):
577 577 obj.set_ip(self.shell)
578 578 return self.prefilter_manager.get_handler_by_name('auto')
579 579 else:
580 580 return None
581 581
582 582
583 583 class MultiLineMagicChecker(PrefilterChecker):
584 584
585 585 priority = Int(400, config=True)
586 586
587 587 def check(self, line_info):
588 588 "Allow ! and !! in multi-line statements if multi_line_specials is on"
589 589 # Note that this one of the only places we check the first character of
590 590 # ifun and *not* the pre_char. Also note that the below test matches
591 591 # both ! and !!.
592 592 if line_info.continue_prompt \
593 593 and self.prefilter_manager.multi_line_specials:
594 594 if line_info.ifun.startswith(ESC_MAGIC):
595 595 return self.prefilter_manager.get_handler_by_name('magic')
596 596 else:
597 597 return None
598 598
599 599
600 600 class EscCharsChecker(PrefilterChecker):
601 601
602 602 priority = Int(500, config=True)
603 603
604 604 def check(self, line_info):
605 605 """Check for escape character and return either a handler to handle it,
606 606 or None if there is no escape char."""
607 607 if line_info.line[-1] == ESC_HELP \
608 608 and line_info.pre_char != ESC_SHELL \
609 609 and line_info.pre_char != ESC_SH_CAP:
610 610 # the ? can be at the end, but *not* for either kind of shell escape,
611 611 # because a ? can be a vaild final char in a shell cmd
612 612 return self.prefilter_manager.get_handler_by_name('help')
613 613 else:
614 614 # This returns None like it should if no handler exists
615 615 return self.prefilter_manager.get_handler_by_esc(line_info.pre_char)
616 616
617 617
618 618 class AssignmentChecker(PrefilterChecker):
619 619
620 620 priority = Int(600, config=True)
621 621
622 622 def check(self, line_info):
623 623 """Check to see if user is assigning to a var for the first time, in
624 624 which case we want to avoid any sort of automagic / autocall games.
625 625
626 626 This allows users to assign to either alias or magic names true python
627 627 variables (the magic/alias systems always take second seat to true
628 628 python code). E.g. ls='hi', or ls,that=1,2"""
629 629 if line_info.the_rest:
630 630 if line_info.the_rest[0] in '=,':
631 631 return self.prefilter_manager.get_handler_by_name('normal')
632 632 else:
633 633 return None
634 634
635 635
636 636 class AutoMagicChecker(PrefilterChecker):
637 637
638 638 priority = Int(700, config=True)
639 639
640 640 def check(self, line_info):
641 641 """If the ifun is magic, and automagic is on, run it. Note: normal,
642 642 non-auto magic would already have been triggered via '%' in
643 643 check_esc_chars. This just checks for automagic. Also, before
644 644 triggering the magic handler, make sure that there is nothing in the
645 645 user namespace which could shadow it."""
646 646 if not self.shell.automagic or not hasattr(self.shell,'magic_'+line_info.ifun):
647 647 return None
648 648
649 649 # We have a likely magic method. Make sure we should actually call it.
650 650 if line_info.continue_prompt and not self.shell.multi_line_specials:
651 651 return None
652 652
653 653 head = line_info.ifun.split('.',1)[0]
654 654 if is_shadowed(head, self.shell):
655 655 return None
656 656
657 657 return self.prefilter_manager.get_handler_by_name('magic')
658 658
659 659
660 660 class AliasChecker(PrefilterChecker):
661 661
662 662 priority = Int(800, config=True)
663 663
664 664 @auto_attr
665 665 def alias_manager(self):
666 666 return AliasManager.get_instances(root=self.root)[0]
667 667
668 668 def check(self, line_info):
669 669 "Check if the initital identifier on the line is an alias."
670 670 # Note: aliases can not contain '.'
671 671 head = line_info.ifun.split('.',1)[0]
672 672 if line_info.ifun not in self.alias_manager \
673 673 or head not in self.alias_manager \
674 674 or is_shadowed(head, self.shell):
675 675 return None
676 676
677 677 return self.prefilter_manager.get_handler_by_name('alias')
678 678
679 679
680 680 class PythonOpsChecker(PrefilterChecker):
681 681
682 682 priority = Int(900, config=True)
683 683
684 684 def check(self, line_info):
685 685 """If the 'rest' of the line begins with a function call or pretty much
686 686 any python operator, we should simply execute the line (regardless of
687 687 whether or not there's a possible autocall expansion). This avoids
688 688 spurious (and very confusing) geattr() accesses."""
689 689 if line_info.the_rest and line_info.the_rest[0] in '!=()<>,+*/%^&|':
690 690 return self.prefilter_manager.get_handler_by_name('normal')
691 691 else:
692 692 return None
693 693
694 694
695 695 class AutocallChecker(PrefilterChecker):
696 696
697 697 priority = Int(1000, config=True)
698 698
699 699 def check(self, line_info):
700 700 "Check if the initial word/function is callable and autocall is on."
701 701 if not self.shell.autocall:
702 702 return None
703 703
704 704 oinfo = line_info.ofind(self.shell) # This can mutate state via getattr
705 705 if not oinfo['found']:
706 706 return None
707 707
708 708 if callable(oinfo['obj']) \
709 709 and (not re_exclude_auto.match(line_info.the_rest)) \
710 710 and re_fun_name.match(line_info.ifun):
711 711 return self.prefilter_manager.get_handler_by_name('auto')
712 712 else:
713 713 return None
714 714
715 715
716 716 #-----------------------------------------------------------------------------
717 717 # Prefilter handlers
718 718 #-----------------------------------------------------------------------------
719 719
720 720
721 721 class PrefilterHandler(Component):
722 722
723 723 handler_name = Str('normal')
724 724 esc_strings = List([])
725 725 shell = Any
726 726 prefilter_manager = Any
727 727
728 728 def __init__(self, parent, config=None):
729 729 super(PrefilterHandler, self).__init__(parent, config=config)
730 730 self.prefilter_manager.register_handler(
731 731 self.handler_name,
732 732 self,
733 733 self.esc_strings
734 734 )
735 735
736 736 @auto_attr
737 737 def shell(self):
738 738 return Component.get_instances(
739 739 root=self.root,
740 740 klass='IPython.core.iplib.InteractiveShell')[0]
741 741
742 742 @auto_attr
743 743 def prefilter_manager(self):
744 744 return PrefilterManager.get_instances(root=self.root)[0]
745 745
746 746 def handle(self, line_info):
747 747 # print "normal: ", line_info
748 748 """Handle normal input lines. Use as a template for handlers."""
749 749
750 750 # With autoindent on, we need some way to exit the input loop, and I
751 751 # don't want to force the user to have to backspace all the way to
752 752 # clear the line. The rule will be in this case, that either two
753 753 # lines of pure whitespace in a row, or a line of pure whitespace but
754 754 # of a size different to the indent level, will exit the input loop.
755 755 line = line_info.line
756 756 continue_prompt = line_info.continue_prompt
757 757
758 758 if (continue_prompt and self.shell.autoindent and line.isspace() and
759 759 (0 < abs(len(line) - self.shell.indent_current_nsp) <= 2 or
760 760 (self.shell.buffer[-1]).isspace() )):
761 761 line = ''
762 762
763 763 self.shell.log(line, line, continue_prompt)
764 764 return line
765 765
766 766 def __str__(self):
767 767 return "<%s(name=%s)>" % (self.__class__.__name__, self.handler_name)
768 768
769 769
770 770 class AliasHandler(PrefilterHandler):
771 771
772 772 handler_name = Str('alias')
773 773
774 774 @auto_attr
775 775 def alias_manager(self):
776 776 return AliasManager.get_instances(root=self.root)[0]
777 777
778 778 def handle(self, line_info):
779 779 """Handle alias input lines. """
780 780 transformed = self.alias_manager.expand_aliases(line_info.ifun,line_info.the_rest)
781 781 # pre is needed, because it carries the leading whitespace. Otherwise
782 782 # aliases won't work in indented sections.
783 783 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
784 784 make_quoted_expr(transformed))
785 785
786 786 self.shell.log(line_info.line, line_out, line_info.continue_prompt)
787 787 return line_out
788 788
789 789
790 790 class ShellEscapeHandler(PrefilterHandler):
791 791
792 792 handler_name = Str('shell')
793 793 esc_strings = List([ESC_SHELL, ESC_SH_CAP])
794 794
795 795 def handle(self, line_info):
796 796 """Execute the line in a shell, empty return value"""
797 797 magic_handler = self.prefilter_manager.get_handler_by_name('magic')
798 798
799 799 line = line_info.line
800 800 if line.lstrip().startswith(ESC_SH_CAP):
801 801 # rewrite LineInfo's line, ifun and the_rest to properly hold the
802 802 # call to %sx and the actual command to be executed, so
803 803 # handle_magic can work correctly. Note that this works even if
804 804 # the line is indented, so it handles multi_line_specials
805 805 # properly.
806 806 new_rest = line.lstrip()[2:]
807 807 line_info.line = '%ssx %s' % (ESC_MAGIC, new_rest)
808 808 line_info.ifun = 'sx'
809 809 line_info.the_rest = new_rest
810 810 return magic_handler.handle(line_info)
811 811 else:
812 812 cmd = line.lstrip().lstrip(ESC_SHELL)
813 813 line_out = '%sget_ipython().system(%s)' % (line_info.pre_whitespace,
814 814 make_quoted_expr(cmd))
815 815 # update cache/log and return
816 816 self.shell.log(line, line_out, line_info.continue_prompt)
817 817 return line_out
818 818
819 819
820 820 class MagicHandler(PrefilterHandler):
821 821
822 822 handler_name = Str('magic')
823 823 esc_strings = List([ESC_MAGIC])
824 824
825 825 def handle(self, line_info):
826 826 """Execute magic functions."""
827 827 ifun = line_info.ifun
828 828 the_rest = line_info.the_rest
829 829 cmd = '%sget_ipython().magic(%s)' % (line_info.pre_whitespace,
830 830 make_quoted_expr(ifun + " " + the_rest))
831 831 self.shell.log(line_info.line, cmd, line_info.continue_prompt)
832 832 return cmd
833 833
834 834
835 835 class AutoHandler(PrefilterHandler):
836 836
837 837 handler_name = Str('auto')
838 838 esc_strings = List([ESC_PAREN, ESC_QUOTE, ESC_QUOTE2])
839 839
840 840 def handle(self, line_info):
841 841 """Hande lines which can be auto-executed, quoting if requested."""
842 842 line = line_info.line
843 843 ifun = line_info.ifun
844 844 the_rest = line_info.the_rest
845 845 pre = line_info.pre
846 846 continue_prompt = line_info.continue_prompt
847 847 obj = line_info.ofind(self)['obj']
848 848 #print 'pre <%s> ifun <%s> rest <%s>' % (pre,ifun,the_rest) # dbg
849 849
850 850 # This should only be active for single-line input!
851 851 if continue_prompt:
852 852 self.shell.log(line,line,continue_prompt)
853 853 return line
854 854
855 855 force_auto = isinstance(obj, IPyAutocall)
856 856 auto_rewrite = True
857 857
858 858 if pre == ESC_QUOTE:
859 859 # Auto-quote splitting on whitespace
860 860 newcmd = '%s("%s")' % (ifun,'", "'.join(the_rest.split()) )
861 861 elif pre == ESC_QUOTE2:
862 862 # Auto-quote whole string
863 863 newcmd = '%s("%s")' % (ifun,the_rest)
864 864 elif pre == ESC_PAREN:
865 865 newcmd = '%s(%s)' % (ifun,",".join(the_rest.split()))
866 866 else:
867 867 # Auto-paren.
868 868 # We only apply it to argument-less calls if the autocall
869 869 # parameter is set to 2. We only need to check that autocall is <
870 870 # 2, since this function isn't called unless it's at least 1.
871 871 if not the_rest and (self.shell.autocall < 2) and not force_auto:
872 872 newcmd = '%s %s' % (ifun,the_rest)
873 873 auto_rewrite = False
874 874 else:
875 875 if not force_auto and the_rest.startswith('['):
876 876 if hasattr(obj,'__getitem__'):
877 877 # Don't autocall in this case: item access for an object
878 878 # which is BOTH callable and implements __getitem__.
879 879 newcmd = '%s %s' % (ifun,the_rest)
880 880 auto_rewrite = False
881 881 else:
882 882 # if the object doesn't support [] access, go ahead and
883 883 # autocall
884 884 newcmd = '%s(%s)' % (ifun.rstrip(),the_rest)
885 885 elif the_rest.endswith(';'):
886 886 newcmd = '%s(%s);' % (ifun.rstrip(),the_rest[:-1])
887 887 else:
888 888 newcmd = '%s(%s)' % (ifun.rstrip(), the_rest)
889 889
890 890 if auto_rewrite:
891 891 rw = self.shell.outputcache.prompt1.auto_rewrite() + newcmd
892 892
893 893 try:
894 894 # plain ascii works better w/ pyreadline, on some machines, so
895 895 # we use it and only print uncolored rewrite if we have unicode
896 896 rw = str(rw)
897 897 print >>Term.cout, rw
898 898 except UnicodeEncodeError:
899 899 print "-------------->" + newcmd
900 900
901 901 # log what is now valid Python, not the actual user input (without the
902 902 # final newline)
903 903 self.shell.log(line,newcmd,continue_prompt)
904 904 return newcmd
905 905
906 906
907 907 class HelpHandler(PrefilterHandler):
908 908
909 909 handler_name = Str('help')
910 910 esc_strings = List([ESC_HELP])
911 911
912 912 def handle(self, line_info):
913 913 """Try to get some help for the object.
914 914
915 915 obj? or ?obj -> basic information.
916 916 obj?? or ??obj -> more details.
917 917 """
918 918 normal_handler = self.prefilter_manager.get_handler_by_name('normal')
919 919 line = line_info.line
920 920 # We need to make sure that we don't process lines which would be
921 921 # otherwise valid python, such as "x=1 # what?"
922 922 try:
923 923 codeop.compile_command(line)
924 924 except SyntaxError:
925 925 # We should only handle as help stuff which is NOT valid syntax
926 926 if line[0]==ESC_HELP:
927 927 line = line[1:]
928 928 elif line[-1]==ESC_HELP:
929 929 line = line[:-1]
930 930 self.shell.log(line, '#?'+line, line_info.continue_prompt)
931 931 if line:
932 932 #print 'line:<%r>' % line # dbg
933 933 self.shell.magic_pinfo(line)
934 934 else:
935 935 page(self.shell.usage, screen_lines=self.shell.usable_screen_length)
936 936 return '' # Empty string is needed here!
937 937 except:
938 938 raise
939 939 # Pass any other exceptions through to the normal handler
940 940 return normal_handler.handle(line_info)
941 941 else:
942 942 raise
943 943 # If the code compiles ok, we should handle it normally
944 944 return normal_handler.handle(line_info)
945 945
946 946
947 947 class EmacsHandler(PrefilterHandler):
948 948
949 949 handler_name = Str('emacs')
950 950 esc_strings = List([])
951 951
952 952 def handle(self, line_info):
953 953 """Handle input lines marked by python-mode."""
954 954
955 955 # Currently, nothing is done. Later more functionality can be added
956 956 # here if needed.
957 957
958 958 # The input cache shouldn't be updated
959 959 return line_info.line
960 960
961 961
962 962 #-----------------------------------------------------------------------------
963 963 # Defaults
964 964 #-----------------------------------------------------------------------------
965 965
966 966
967 967 _default_transformers = [
968 968 AssignSystemTransformer,
969 969 AssignMagicTransformer
970 970 ]
971 971
972 972 _default_checkers = [
973 973 EmacsChecker,
974 974 ShellEscapeChecker,
975 975 IPyAutocallChecker,
976 976 MultiLineMagicChecker,
977 977 EscCharsChecker,
978 978 AssignmentChecker,
979 979 AutoMagicChecker,
980 980 AliasChecker,
981 981 PythonOpsChecker,
982 982 AutocallChecker
983 983 ]
984 984
985 985 _default_handlers = [
986 986 PrefilterHandler,
987 987 AliasHandler,
988 988 ShellEscapeHandler,
989 989 MagicHandler,
990 990 AutoHandler,
991 991 HelpHandler,
992 992 EmacsHandler
993 993 ]
994 994
@@ -1,27 +1,29 b''
1 """Simple script to instantiate a class for testing %run"""
1 """Simple script to be run *twice*, to check reference counting bugs.
2 2
3 import sys
4
5 # An external test will check that calls to f() work after %run
6 class foo: pass
3 See test_run for details."""
7 4
8 def f():
9 return foo()
5 import sys
10 6
11 # We also want to ensure that while objects remain available for immediate
12 # access, objects from *previous* runs of the same script get collected, to
13 # avoid accumulating massive amounts of old references.
7 # We want to ensure that while objects remain available for immediate access,
8 # objects from *previous* runs of the same script get collected, to avoid
9 # accumulating massive amounts of old references.
14 10 class C(object):
15 11 def __init__(self,name):
16 12 self.name = name
17 13
18 14 def __del__(self):
19 15 print 'tclass.py: deleting object:',self.name
20 16
17
21 18 try:
22 19 name = sys.argv[1]
23 20 except IndexError:
24 21 pass
25 22 else:
26 23 if name.startswith('C'):
27 24 c = C(name)
25
26 #print >> sys.stderr, "ARGV:", sys.argv # dbg
27 # This print statement is NOT debugging, we're making the check on a completely
28 # separate process so we verify by capturing stdout.
29 print 'ARGV 1-:', sys.argv[1:]
@@ -1,347 +1,191 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 from __future__ import absolute_import
5 6
7 #-----------------------------------------------------------------------------
8 # Imports
9 #-----------------------------------------------------------------------------
10
11 # stdlib
6 12 import os
7 13 import sys
8 14 import tempfile
9 15 import types
10 16 from cStringIO import StringIO
11 17
18 # third-party
12 19 import nose.tools as nt
13 20
21 # our own
22 from IPython.utils import genutils
14 23 from IPython.utils.platutils import find_cmd, get_long_path_name
15 24 from IPython.testing import decorators as dec
16 25 from IPython.testing import tools as tt
17 26
18 27 #-----------------------------------------------------------------------------
19 28 # Test functions begin
29 #-----------------------------------------------------------------------------
20 30
21 31 def test_rehashx():
22 32 # clear up everything
23 33 _ip = get_ipython()
24 34 _ip.alias_manager.alias_table.clear()
25 35 del _ip.db['syscmdlist']
26 36
27 37 _ip.magic('rehashx')
28 38 # Practically ALL ipython development systems will have more than 10 aliases
29 39
30 40 yield (nt.assert_true, len(_ip.alias_manager.alias_table) > 10)
31 41 for key, val in _ip.alias_manager.alias_table.items():
32 42 # we must strip dots from alias names
33 43 nt.assert_true('.' not in key)
34 44
35 45 # rehashx must fill up syscmdlist
36 46 scoms = _ip.db['syscmdlist']
37 47 yield (nt.assert_true, len(scoms) > 10)
38 48
39 49
40 50 def doctest_hist_f():
41 51 """Test %hist -f with temporary filename.
42 52
43 53 In [9]: import tempfile
44 54
45 55 In [10]: tfile = tempfile.mktemp('.py','tmp-ipython-')
46 56
47 57 In [11]: %hist -n -f $tfile 3
48 58 """
49 59
50 60
51 61 def doctest_hist_r():
52 62 """Test %hist -r
53 63
54 64 XXX - This test is not recording the output correctly. Not sure why...
55 65
56 66 In [20]: 'hist' in _ip.lsmagic()
57 67 Out[20]: True
58 68
59 69 In [6]: x=1
60 70
61 71 In [7]: %hist -n -r 2
62 72 x=1 # random
63 73 hist -n -r 2 # random
64 74 """
65 75
66 # This test is known to fail on win32.
67 # See ticket https://bugs.launchpad.net/bugs/366334
68 def test_obj_del():
69 _ip = get_ipython()
70 """Test that object's __del__ methods are called on exit."""
71 test_dir = os.path.dirname(__file__)
72 del_file = os.path.join(test_dir,'obj_del.py')
73 ipython_cmd = find_cmd('ipython')
74 out = _ip.getoutput('%s %s' % (ipython_cmd, del_file))
75 nt.assert_equals(out,'obj_del.py: object A deleted')
76
77 76
78 77 def test_shist():
79 78 # Simple tests of ShadowHist class - test generator.
80 79 import os, shutil, tempfile
81 80
82 81 from IPython.utils import pickleshare
83 82 from IPython.core.history import ShadowHist
84 83
85 84 tfile = tempfile.mktemp('','tmp-ipython-')
86 85
87 86 db = pickleshare.PickleShareDB(tfile)
88 87 s = ShadowHist(db)
89 88 s.add('hello')
90 89 s.add('world')
91 90 s.add('hello')
92 91 s.add('hello')
93 92 s.add('karhu')
94 93
95 94 yield nt.assert_equals,s.all(),[(1, 'hello'), (2, 'world'), (3, 'karhu')]
96 95
97 96 yield nt.assert_equal,s.get(2),'world'
98 97
99 98 shutil.rmtree(tfile)
100 99
101 100
102 101 # XXX failing for now, until we get clearcmd out of quarantine. But we should
103 102 # fix this and revert the skip to happen only if numpy is not around.
104 103 #@dec.skipif_not_numpy
105 104 @dec.skipknownfailure
106 105 def test_numpy_clear_array_undec():
107 106 from IPython.extensions import clearcmd
108 107
109 108 _ip.ex('import numpy as np')
110 109 _ip.ex('a = np.empty(2)')
111 110 yield (nt.assert_true, 'a' in _ip.user_ns)
112 111 _ip.magic('clear array')
113 112 yield (nt.assert_false, 'a' in _ip.user_ns)
114 113
115 114
116 @dec.skip()
117 def test_fail_dec(*a,**k):
118 yield nt.assert_true, False
119
120 @dec.skip('This one shouldn not run')
121 def test_fail_dec2(*a,**k):
122 yield nt.assert_true, False
123
124 @dec.skipknownfailure
125 def test_fail_dec3(*a,**k):
126 yield nt.assert_true, False
127
128
129 def doctest_refbug():
130 """Very nasty problem with references held by multiple runs of a script.
131 See: https://bugs.launchpad.net/ipython/+bug/269966
132
133 In [1]: _ip.clear_main_mod_cache()
134
135 In [2]: run refbug
136
137 In [3]: call_f()
138 lowercased: hello
139
140 In [4]: run refbug
141
142 In [5]: call_f()
143 lowercased: hello
144 lowercased: hello
145 """
146
147 #-----------------------------------------------------------------------------
148 # Tests for %run
149 #-----------------------------------------------------------------------------
150
151 # %run is critical enough that it's a good idea to have a solid collection of
152 # tests for it, some as doctests and some as normal tests.
153
154 def doctest_run_ns():
155 """Classes declared %run scripts must be instantiable afterwards.
156
157 In [11]: run tclass foo
158
159 In [12]: isinstance(f(),foo)
160 Out[12]: True
161 """
162
163
164 def doctest_run_ns2():
165 """Classes declared %run scripts must be instantiable afterwards.
166
167 In [4]: run tclass C-first_pass
168
169 In [5]: run tclass C-second_pass
170 tclass.py: deleting object: C-first_pass
171 """
172
173 def doctest_run_builtins():
174 """Check that %run doesn't damage __builtins__ via a doctest.
175
176 This is similar to the test_run_builtins, but I want *both* forms of the
177 test to catch any possible glitches in our testing machinery, since that
178 modifies %run somewhat. So for this, we have both a normal test (below)
179 and a doctest (this one).
180
181 In [1]: import tempfile
182
183 In [2]: bid1 = id(__builtins__)
184
185 In [3]: fname = tempfile.mkstemp()[1]
186
187 In [3]: f = open(fname,'w')
188
189 In [4]: f.write('pass\\n')
190
191 In [5]: f.flush()
192
193 In [6]: print type(__builtins__)
194 <type 'module'>
195
196 In [7]: %run "$fname"
197
198 In [7]: f.close()
199
200 In [8]: bid2 = id(__builtins__)
201
202 In [9]: print type(__builtins__)
203 <type 'module'>
204
205 In [10]: bid1 == bid2
206 Out[10]: True
207
208 In [12]: try:
209 ....: os.unlink(fname)
210 ....: except:
211 ....: pass
212 ....:
213 """
214
215 # For some tests, it will be handy to organize them in a class with a common
216 # setup that makes a temp file
217
218 class TestMagicRun(object):
219
220 def setup(self):
221 """Make a valid python temp file."""
222 fname = tempfile.mkstemp('.py')[1]
223 f = open(fname,'w')
224 f.write('pass\n')
225 f.flush()
226 self.tmpfile = f
227 self.fname = fname
228
229 def run_tmpfile(self):
230 _ip = get_ipython()
231 # This fails on Windows if self.tmpfile.name has spaces or "~" in it.
232 # See below and ticket https://bugs.launchpad.net/bugs/366353
233 _ip.magic('run "%s"' % self.fname)
234
235 def test_builtins_id(self):
236 """Check that %run doesn't damage __builtins__ """
237 _ip = get_ipython()
238 # Test that the id of __builtins__ is not modified by %run
239 bid1 = id(_ip.user_ns['__builtins__'])
240 self.run_tmpfile()
241 bid2 = id(_ip.user_ns['__builtins__'])
242 tt.assert_equals(bid1, bid2)
243
244 def test_builtins_type(self):
245 """Check that the type of __builtins__ doesn't change with %run.
246
247 However, the above could pass if __builtins__ was already modified to
248 be a dict (it should be a module) by a previous use of %run. So we
249 also check explicitly that it really is a module:
250 """
251 _ip = get_ipython()
252 self.run_tmpfile()
253 tt.assert_equals(type(_ip.user_ns['__builtins__']),type(sys))
254
255 def test_prompts(self):
256 """Test that prompts correctly generate after %run"""
257 self.run_tmpfile()
258 _ip = get_ipython()
259 p2 = str(_ip.outputcache.prompt2).strip()
260 nt.assert_equals(p2[:3], '...')
261
262 def teardown(self):
263 self.tmpfile.close()
264 try:
265 os.unlink(self.fname)
266 except:
267 # On Windows, even though we close the file, we still can't delete
268 # it. I have no clue why
269 pass
270
271 115 # Multiple tests for clipboard pasting
272 116 @dec.parametric
273 117 def test_paste():
274 118 _ip = get_ipython()
275 119 def paste(txt, flags='-q'):
276 120 """Paste input text, by default in quiet mode"""
277 121 hooks.clipboard_get = lambda : txt
278 122 _ip.magic('paste '+flags)
279 123
280 124 # Inject fake clipboard hook but save original so we can restore it later
281 125 hooks = _ip.hooks
282 126 user_ns = _ip.user_ns
283 127 original_clip = hooks.clipboard_get
284 128
285 129 try:
286 130 # This try/except with an emtpy except clause is here only because
287 131 # try/yield/finally is invalid syntax in Python 2.4. This will be
288 132 # removed when we drop 2.4-compatibility, and the emtpy except below
289 133 # will be changed to a finally.
290 134
291 135 # Run tests with fake clipboard function
292 136 user_ns.pop('x', None)
293 137 paste('x=1')
294 138 yield nt.assert_equal(user_ns['x'], 1)
295 139
296 140 user_ns.pop('x', None)
297 141 paste('>>> x=2')
298 142 yield nt.assert_equal(user_ns['x'], 2)
299 143
300 144 paste("""
301 145 >>> x = [1,2,3]
302 146 >>> y = []
303 147 >>> for i in x:
304 148 ... y.append(i**2)
305 149 ...
306 150 """)
307 151 yield nt.assert_equal(user_ns['x'], [1,2,3])
308 152 yield nt.assert_equal(user_ns['y'], [1,4,9])
309 153
310 154 # Now, test that paste -r works
311 155 user_ns.pop('x', None)
312 156 yield nt.assert_false('x' in user_ns)
313 157 _ip.magic('paste -r')
314 158 yield nt.assert_equal(user_ns['x'], [1,2,3])
315 159
316 160 # Also test paste echoing, by temporarily faking the writer
317 161 w = StringIO()
318 162 writer = _ip.write
319 163 _ip.write = w.write
320 164 code = """
321 165 a = 100
322 166 b = 200"""
323 167 try:
324 168 paste(code,'')
325 169 out = w.getvalue()
326 170 finally:
327 171 _ip.write = writer
328 172 yield nt.assert_equal(user_ns['a'], 100)
329 173 yield nt.assert_equal(user_ns['b'], 200)
330 174 yield nt.assert_equal(out, code+"\n## -- End pasted text --\n")
331 175
332 176 finally:
333 177 # This should be in a finally clause, instead of the bare except above.
334 178 # Restore original hook
335 179 hooks.clipboard_get = original_clip
336 180
337 181
338 182 def test_time():
339 183 _ip.magic('time None')
340 184
341 185
342 186 def doctest_time():
343 187 """
344 188 In [10]: %time None
345 189 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
346 190 Wall time: 0.00 s
347 191 """
@@ -1,310 +1,313 b''
1 1 """Decorators for labeling test objects.
2 2
3 3 Decorators that merely return a modified version of the original function
4 4 object are straightforward. Decorators that return a new function object need
5 5 to use nose.tools.make_decorator(original_function)(decorator) in returning the
6 6 decorator, in order to preserve metadata such as function name, setup and
7 7 teardown functions and so on - see nose.tools for more information.
8 8
9 9 This module provides a set of useful decorators meant to be ready to use in
10 10 your own tests. See the bottom of the file for the ready-made ones, and if you
11 11 find yourself writing a new one that may be of generic use, add it here.
12 12
13 13 Included decorators:
14 14
15 15
16 16 Lightweight testing that remains unittest-compatible.
17 17
18 18 - @parametric, for parametric test support that is vastly easier to use than
19 19 nose's for debugging. With ours, if a test fails, the stack under inspection
20 20 is that of the test and not that of the test framework.
21 21
22 22 - An @as_unittest decorator can be used to tag any normal parameter-less
23 23 function as a unittest TestCase. Then, both nose and normal unittest will
24 24 recognize it as such. This will make it easier to migrate away from Nose if
25 25 we ever need/want to while maintaining very lightweight tests.
26 26
27 27 NOTE: This file contains IPython-specific decorators and imports the
28 28 numpy.testing.decorators file, which we've copied verbatim. Any of our own
29 29 code will be added at the bottom if we end up extending this.
30 30
31 31 Authors
32 32 -------
33 33
34 34 - Fernando Perez <Fernando.Perez@berkeley.edu>
35 35 """
36 36
37 37 #-----------------------------------------------------------------------------
38 38 # Copyright (C) 2009-2010 The IPython Development Team
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 #-----------------------------------------------------------------------------
45 45 # Imports
46 46 #-----------------------------------------------------------------------------
47 47
48 48 # Stdlib imports
49 49 import inspect
50 50 import sys
51 51 import unittest
52 52
53 53 # Third-party imports
54 54
55 55 # This is Michele Simionato's decorator module, kept verbatim.
56 56 from IPython.external.decorator import decorator, update_wrapper
57 57
58 58 # Our own modules
59 59 import nosepatch # monkeypatch nose
60 60
61 61 # We already have python3-compliant code for parametric tests
62 62 if sys.version[0]=='2':
63 63 from _paramtestpy2 import parametric
64 64 else:
65 65 from _paramtestpy3 import parametric
66 66
67 # Expose the unittest-driven decorators
68 from ipunittest import ipdoctest, ipdocstring
69
67 70 # Grab the numpy-specific decorators which we keep in a file that we
68 71 # occasionally update from upstream: decorators.py is a copy of
69 72 # numpy.testing.decorators, we expose all of it here.
70 73 from IPython.external.decorators import *
71 74
72 75 #-----------------------------------------------------------------------------
73 76 # Classes and functions
74 77 #-----------------------------------------------------------------------------
75 78
76 79 # Simple example of the basic idea
77 80 def as_unittest(func):
78 81 """Decorator to make a simple function into a normal test via unittest."""
79 82 class Tester(unittest.TestCase):
80 83 def test(self):
81 84 func()
82 85
83 86 Tester.__name__ = func.__name__
84 87
85 88 return Tester
86 89
87 90 # Utility functions
88 91
89 92 def apply_wrapper(wrapper,func):
90 93 """Apply a wrapper to a function for decoration.
91 94
92 95 This mixes Michele Simionato's decorator tool with nose's make_decorator,
93 96 to apply a wrapper in a decorator so that all nose attributes, as well as
94 97 function signature and other properties, survive the decoration cleanly.
95 98 This will ensure that wrapped functions can still be well introspected via
96 99 IPython, for example.
97 100 """
98 101 import nose.tools
99 102
100 103 return decorator(wrapper,nose.tools.make_decorator(func)(wrapper))
101 104
102 105
103 106 def make_label_dec(label,ds=None):
104 107 """Factory function to create a decorator that applies one or more labels.
105 108
106 109 Parameters
107 110 ----------
108 111 label : string or sequence
109 112 One or more labels that will be applied by the decorator to the functions
110 113 it decorates. Labels are attributes of the decorated function with their
111 114 value set to True.
112 115
113 116 ds : string
114 117 An optional docstring for the resulting decorator. If not given, a
115 118 default docstring is auto-generated.
116 119
117 120 Returns
118 121 -------
119 122 A decorator.
120 123
121 124 Examples
122 125 --------
123 126
124 127 A simple labeling decorator:
125 128 >>> slow = make_label_dec('slow')
126 129 >>> print slow.__doc__
127 130 Labels a test as 'slow'.
128 131
129 132 And one that uses multiple labels and a custom docstring:
130 133 >>> rare = make_label_dec(['slow','hard'],
131 134 ... "Mix labels 'slow' and 'hard' for rare tests.")
132 135 >>> print rare.__doc__
133 136 Mix labels 'slow' and 'hard' for rare tests.
134 137
135 138 Now, let's test using this one:
136 139 >>> @rare
137 140 ... def f(): pass
138 141 ...
139 142 >>>
140 143 >>> f.slow
141 144 True
142 145 >>> f.hard
143 146 True
144 147 """
145 148
146 149 if isinstance(label,basestring):
147 150 labels = [label]
148 151 else:
149 152 labels = label
150 153
151 154 # Validate that the given label(s) are OK for use in setattr() by doing a
152 155 # dry run on a dummy function.
153 156 tmp = lambda : None
154 157 for label in labels:
155 158 setattr(tmp,label,True)
156 159
157 160 # This is the actual decorator we'll return
158 161 def decor(f):
159 162 for label in labels:
160 163 setattr(f,label,True)
161 164 return f
162 165
163 166 # Apply the user's docstring, or autogenerate a basic one
164 167 if ds is None:
165 168 ds = "Labels a test as %r." % label
166 169 decor.__doc__ = ds
167 170
168 171 return decor
169 172
170 173
171 174 # Inspired by numpy's skipif, but uses the full apply_wrapper utility to
172 175 # preserve function metadata better and allows the skip condition to be a
173 176 # callable.
174 177 def skipif(skip_condition, msg=None):
175 178 ''' Make function raise SkipTest exception if skip_condition is true
176 179
177 180 Parameters
178 181 ----------
179 182 skip_condition : bool or callable.
180 183 Flag to determine whether to skip test. If the condition is a
181 184 callable, it is used at runtime to dynamically make the decision. This
182 185 is useful for tests that may require costly imports, to delay the cost
183 186 until the test suite is actually executed.
184 187 msg : string
185 188 Message to give on raising a SkipTest exception
186 189
187 190 Returns
188 191 -------
189 192 decorator : function
190 193 Decorator, which, when applied to a function, causes SkipTest
191 194 to be raised when the skip_condition was True, and the function
192 195 to be called normally otherwise.
193 196
194 197 Notes
195 198 -----
196 199 You will see from the code that we had to further decorate the
197 200 decorator with the nose.tools.make_decorator function in order to
198 201 transmit function name, and various other metadata.
199 202 '''
200 203
201 204 def skip_decorator(f):
202 205 # Local import to avoid a hard nose dependency and only incur the
203 206 # import time overhead at actual test-time.
204 207 import nose
205 208
206 209 # Allow for both boolean or callable skip conditions.
207 210 if callable(skip_condition):
208 211 skip_val = lambda : skip_condition()
209 212 else:
210 213 skip_val = lambda : skip_condition
211 214
212 215 def get_msg(func,msg=None):
213 216 """Skip message with information about function being skipped."""
214 217 if msg is None: out = 'Test skipped due to test condition.'
215 218 else: out = msg
216 219 return "Skipping test: %s. %s" % (func.__name__,out)
217 220
218 221 # We need to define *two* skippers because Python doesn't allow both
219 222 # return with value and yield inside the same function.
220 223 def skipper_func(*args, **kwargs):
221 224 """Skipper for normal test functions."""
222 225 if skip_val():
223 226 raise nose.SkipTest(get_msg(f,msg))
224 227 else:
225 228 return f(*args, **kwargs)
226 229
227 230 def skipper_gen(*args, **kwargs):
228 231 """Skipper for test generators."""
229 232 if skip_val():
230 233 raise nose.SkipTest(get_msg(f,msg))
231 234 else:
232 235 for x in f(*args, **kwargs):
233 236 yield x
234 237
235 238 # Choose the right skipper to use when building the actual generator.
236 239 if nose.util.isgenerator(f):
237 240 skipper = skipper_gen
238 241 else:
239 242 skipper = skipper_func
240 243
241 244 return nose.tools.make_decorator(f)(skipper)
242 245
243 246 return skip_decorator
244 247
245 248 # A version with the condition set to true, common case just to attacha message
246 249 # to a skip decorator
247 250 def skip(msg=None):
248 251 """Decorator factory - mark a test function for skipping from test suite.
249 252
250 253 Parameters
251 254 ----------
252 255 msg : string
253 256 Optional message to be added.
254 257
255 258 Returns
256 259 -------
257 260 decorator : function
258 261 Decorator, which, when applied to a function, causes SkipTest
259 262 to be raised, with the optional message added.
260 263 """
261 264
262 265 return skipif(True,msg)
263 266
264 267
265 268 #-----------------------------------------------------------------------------
266 269 # Utility functions for decorators
267 270 def numpy_not_available():
268 271 """Can numpy be imported? Returns true if numpy does NOT import.
269 272
270 273 This is used to make a decorator to skip tests that require numpy to be
271 274 available, but delay the 'import numpy' to test execution time.
272 275 """
273 276 try:
274 277 import numpy
275 278 np_not_avail = False
276 279 except ImportError:
277 280 np_not_avail = True
278 281
279 282 return np_not_avail
280 283
281 284 #-----------------------------------------------------------------------------
282 285 # Decorators for public use
283 286
284 287 skip_doctest = make_label_dec('skip_doctest',
285 288 """Decorator - mark a function or method for skipping its doctest.
286 289
287 290 This decorator allows you to mark a function whose docstring you wish to
288 291 omit from testing, while preserving the docstring for introspection, help,
289 292 etc.""")
290 293
291 294 # Decorators to skip certain tests on specific platforms.
292 295 skip_win32 = skipif(sys.platform == 'win32',
293 296 "This test does not run under Windows")
294 297 skip_linux = skipif(sys.platform == 'linux2',
295 298 "This test does not run under Linux")
296 299 skip_osx = skipif(sys.platform == 'darwin',"This test does not run under OS X")
297 300
298 301
299 302 # Decorators to skip tests if not on specific platforms.
300 303 skip_if_not_win32 = skipif(sys.platform != 'win32',
301 304 "This test only runs under Windows")
302 305 skip_if_not_linux = skipif(sys.platform != 'linux2',
303 306 "This test only runs under Linux")
304 307 skip_if_not_osx = skipif(sys.platform != 'darwin',
305 308 "This test only runs under OSX")
306 309
307 310 # Other skip decorators
308 311 skipif_not_numpy = skipif(numpy_not_available,"This test requires numpy")
309 312
310 313 skipknownfailure = skip('This test is known to fail')
@@ -1,383 +1,393 b''
1 1 # -*- coding: utf-8 -*-
2 2 """IPython Test Suite Runner.
3 3
4 4 This module provides a main entry point to a user script to test IPython
5 5 itself from the command line. There are two ways of running this script:
6 6
7 7 1. With the syntax `iptest all`. This runs our entire test suite by
8 8 calling this script (with different arguments) or trial recursively. This
9 9 causes modules and package to be tested in different processes, using nose
10 10 or trial where appropriate.
11 11 2. With the regular nose syntax, like `iptest -vvs IPython`. In this form
12 12 the script simply calls nose, but with special command line flags and
13 13 plugins loaded.
14 14
15 15 For now, this script requires that both nose and twisted are installed. This
16 16 will change in the future.
17 17 """
18 18
19 from __future__ import absolute_import
20
19 21 #-----------------------------------------------------------------------------
20 22 # Module imports
21 23 #-----------------------------------------------------------------------------
22 24
23 25 import os
24 26 import os.path as path
25 27 import signal
26 28 import sys
27 29 import subprocess
28 30 import tempfile
29 31 import time
30 32 import warnings
31 33
32 34 import nose.plugins.builtin
33 35 from nose.core import TestProgram
34 36
35 37 from IPython.utils import genutils
36 38 from IPython.utils.platutils import find_cmd, FindCmdError
39 from . import globalipapp
40 from .plugin.ipdoctest import IPythonDoctest
37 41
38 42 pjoin = path.join
39 43
40 44 #-----------------------------------------------------------------------------
41 45 # Warnings control
42 46 #-----------------------------------------------------------------------------
43 47 # Twisted generates annoying warnings with Python 2.6, as will do other code
44 48 # that imports 'sets' as of today
45 49 warnings.filterwarnings('ignore', 'the sets module is deprecated',
46 50 DeprecationWarning )
47 51
48 52 #-----------------------------------------------------------------------------
49 53 # Logic for skipping doctests
50 54 #-----------------------------------------------------------------------------
51 55
52 56 def test_for(mod):
53 57 """Test to see if mod is importable."""
54 58 try:
55 59 __import__(mod)
56 60 except ImportError:
57 61 return False
58 62 else:
59 63 return True
60 64
61 65 have_curses = test_for('_curses')
62 66 have_wx = test_for('wx')
63 67 have_wx_aui = test_for('wx.aui')
64 68 have_zi = test_for('zope.interface')
65 69 have_twisted = test_for('twisted')
66 70 have_foolscap = test_for('foolscap')
67 71 have_objc = test_for('objc')
68 72 have_pexpect = test_for('pexpect')
69 73 have_gtk = test_for('gtk')
70 74 have_gobject = test_for('gobject')
71 75
72 76
73 77 def make_exclude():
74 78
75 79 # For the IPythonDoctest plugin, we need to exclude certain patterns that
76 80 # cause testing problems. We should strive to minimize the number of
77 81 # skipped modules, since this means untested code. As the testing
78 82 # machinery solidifies, this list should eventually become empty.
79 EXCLUDE = [pjoin('IPython', 'external'),
83
84 # Note that these exclusions only mean that the docstrings are not analyzed
85 # for examples to be run as tests, if there are other test functions in
86 # those modules, they do get run.
87 exclusions = [pjoin('IPython', 'external'),
80 88 pjoin('IPython', 'frontend', 'process', 'winprocess.py'),
81 89 pjoin('IPython_doctest_plugin'),
82 90 pjoin('IPython', 'quarantine'),
83 91 pjoin('IPython', 'deathrow'),
84 92 pjoin('IPython', 'testing', 'attic'),
85 93 pjoin('IPython', 'testing', 'tools'),
86 94 pjoin('IPython', 'testing', 'mkdoctests'),
87 95 pjoin('IPython', 'lib', 'inputhook')
88 96 ]
89 97
90 98 if not have_wx:
91 EXCLUDE.append(pjoin('IPython', 'gui'))
92 EXCLUDE.append(pjoin('IPython', 'frontend', 'wx'))
93 EXCLUDE.append(pjoin('IPython', 'lib', 'inputhookwx'))
99 exclusions.append(pjoin('IPython', 'gui'))
100 exclusions.append(pjoin('IPython', 'frontend', 'wx'))
101 exclusions.append(pjoin('IPython', 'lib', 'inputhookwx'))
94 102
95 103 if not have_gtk or not have_gobject:
96 EXCLUDE.append(pjoin('IPython', 'lib', 'inputhookgtk'))
104 exclusions.append(pjoin('IPython', 'lib', 'inputhookgtk'))
97 105
98 106 if not have_wx_aui:
99 EXCLUDE.append(pjoin('IPython', 'gui', 'wx', 'wxIPython'))
107 exclusions.append(pjoin('IPython', 'gui', 'wx', 'wxIPython'))
100 108
101 109 if not have_objc:
102 EXCLUDE.append(pjoin('IPython', 'frontend', 'cocoa'))
110 exclusions.append(pjoin('IPython', 'frontend', 'cocoa'))
103 111
104 112 if not sys.platform == 'win32':
105 EXCLUDE.append(pjoin('IPython', 'utils', 'platutils_win32'))
113 exclusions.append(pjoin('IPython', 'utils', 'platutils_win32'))
106 114
107 115 # These have to be skipped on win32 because the use echo, rm, cd, etc.
108 116 # See ticket https://bugs.launchpad.net/bugs/366982
109 117 if sys.platform == 'win32':
110 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
111 EXCLUDE.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
118 exclusions.append(pjoin('IPython', 'testing', 'plugin', 'test_exampleip'))
119 exclusions.append(pjoin('IPython', 'testing', 'plugin', 'dtexample'))
112 120
113 121 if not os.name == 'posix':
114 EXCLUDE.append(pjoin('IPython', 'utils', 'platutils_posix'))
122 exclusions.append(pjoin('IPython', 'utils', 'platutils_posix'))
115 123
116 124 if not have_pexpect:
117 EXCLUDE.append(pjoin('IPython', 'scripts', 'irunner'))
125 exclusions.append(pjoin('IPython', 'scripts', 'irunner'))
118 126
119 127 # This is scary. We still have things in frontend and testing that
120 128 # are being tested by nose that use twisted. We need to rethink
121 129 # how we are isolating dependencies in testing.
122 130 if not (have_twisted and have_zi and have_foolscap):
123 EXCLUDE.append(pjoin('IPython', 'frontend', 'asyncfrontendbase'))
124 EXCLUDE.append(pjoin('IPython', 'frontend', 'prefilterfrontend'))
125 EXCLUDE.append(pjoin('IPython', 'frontend', 'frontendbase'))
126 EXCLUDE.append(pjoin('IPython', 'frontend', 'linefrontendbase'))
127 EXCLUDE.append(pjoin('IPython', 'frontend', 'tests',
131 exclusions.append(pjoin('IPython', 'frontend', 'asyncfrontendbase'))
132 exclusions.append(pjoin('IPython', 'frontend', 'prefilterfrontend'))
133 exclusions.append(pjoin('IPython', 'frontend', 'frontendbase'))
134 exclusions.append(pjoin('IPython', 'frontend', 'linefrontendbase'))
135 exclusions.append(pjoin('IPython', 'frontend', 'tests',
128 136 'test_linefrontend'))
129 EXCLUDE.append(pjoin('IPython', 'frontend', 'tests',
137 exclusions.append(pjoin('IPython', 'frontend', 'tests',
130 138 'test_frontendbase'))
131 EXCLUDE.append(pjoin('IPython', 'frontend', 'tests',
139 exclusions.append(pjoin('IPython', 'frontend', 'tests',
132 140 'test_prefilterfrontend'))
133 EXCLUDE.append(pjoin('IPython', 'frontend', 'tests',
141 exclusions.append(pjoin('IPython', 'frontend', 'tests',
134 142 'test_asyncfrontendbase')),
135 EXCLUDE.append(pjoin('IPython', 'testing', 'parametric'))
136 EXCLUDE.append(pjoin('IPython', 'testing', 'util'))
143 exclusions.append(pjoin('IPython', 'testing', 'parametric'))
144 exclusions.append(pjoin('IPython', 'testing', 'util'))
137 145
138 146 # This is needed for the reg-exp to match on win32 in the ipdoctest plugin.
139 147 if sys.platform == 'win32':
140 EXCLUDE = [s.replace('\\','\\\\') for s in EXCLUDE]
148 exclusions = [s.replace('\\','\\\\') for s in exclusions]
141 149
142 return EXCLUDE
150 return exclusions
143 151
144 152
145 153 #-----------------------------------------------------------------------------
146 154 # Functions and classes
147 155 #-----------------------------------------------------------------------------
148 156
149 157 class IPTester(object):
150 158 """Call that calls iptest or trial in a subprocess.
151 159 """
152 160 #: string, name of test runner that will be called
153 161 runner = None
154 162 #: list, parameters for test runner
155 163 params = None
156 164 #: list, arguments of system call to be made to call test runner
157 165 call_args = None
158 166 #: list, process ids of subprocesses we start (for cleanup)
159 167 pids = None
160 168
161 169 def __init__(self,runner='iptest',params=None):
162 170 """Create new test runner."""
163 171 if runner == 'iptest':
164 172 # Find our own 'iptest' script OS-level entry point
165 173 try:
166 iptest_path = find_cmd('iptest')
174 iptest_path = os.path.abspath(find_cmd('iptest'))
167 175 except FindCmdError:
168 176 # Script not installed (may be the case for testing situations
169 177 # that are running from a source tree only), pull from internal
170 178 # path:
171 179 iptest_path = pjoin(genutils.get_ipython_package_dir(),
172 180 'scripts','iptest')
173 self.runner = [iptest_path,'-v']
181 self.runner = ['python', iptest_path, '-v']
174 182 else:
175 self.runner = [find_cmd('trial')]
183 self.runner = ['python', os.path.abspath(find_cmd('trial'))]
176 184 if params is None:
177 185 params = []
178 186 if isinstance(params,str):
179 187 params = [params]
180 188 self.params = params
181 189
182 190 # Assemble call
183 191 self.call_args = self.runner+self.params
184 192
185 193 # Store pids of anything we start to clean up on deletion, if possible
186 194 # (on posix only, since win32 has no os.kill)
187 195 self.pids = []
188 196
189 197 if sys.platform == 'win32':
190 198 def _run_cmd(self):
191 199 # On Windows, use os.system instead of subprocess.call, because I
192 200 # was having problems with subprocess and I just don't know enough
193 201 # about win32 to debug this reliably. Os.system may be the 'old
194 202 # fashioned' way to do it, but it works just fine. If someone
195 203 # later can clean this up that's fine, as long as the tests run
196 204 # reliably in win32.
197 205 return os.system(' '.join(self.call_args))
198 206 else:
199 207 def _run_cmd(self):
200 208 subp = subprocess.Popen(self.call_args)
201 209 self.pids.append(subp.pid)
202 210 # If this fails, the pid will be left in self.pids and cleaned up
203 211 # later, but if the wait call succeeds, then we can clear the
204 212 # stored pid.
205 213 retcode = subp.wait()
206 214 self.pids.pop()
207 215 return retcode
208 216
209 217 def run(self):
210 218 """Run the stored commands"""
211 219 try:
212 220 return self._run_cmd()
213 221 except:
214 222 import traceback
215 223 traceback.print_exc()
216 224 return 1 # signal failure
217 225
218 226 def __del__(self):
219 227 """Cleanup on exit by killing any leftover processes."""
220 228
221 229 if not hasattr(os, 'kill'):
222 230 return
223 231
224 232 for pid in self.pids:
225 233 try:
226 234 print 'Cleaning stale PID:', pid
227 235 os.kill(pid, signal.SIGKILL)
228 236 except OSError:
229 237 # This is just a best effort, if we fail or the process was
230 238 # really gone, ignore it.
231 239 pass
232 240
233 241
234 242 def make_runners():
235 243 """Define the top-level packages that need to be tested.
236 244 """
237 245
238 246 nose_packages = ['config', 'core', 'extensions', 'frontend', 'lib',
239 247 'scripts', 'testing', 'utils']
240 248 trial_packages = ['kernel']
241 #trial_packages = [] # dbg
242 249
243 250 if have_wx:
244 251 nose_packages.append('gui')
245 252
253 #nose_packages = ['core'] # dbg
254 #trial_packages = [] # dbg
255
246 256 nose_packages = ['IPython.%s' % m for m in nose_packages ]
247 257 trial_packages = ['IPython.%s' % m for m in trial_packages ]
248 258
249 259 # Make runners, most with nose
250 260 nose_testers = [IPTester(params=v) for v in nose_packages]
251 261 runners = dict(zip(nose_packages, nose_testers))
252 262 # And add twisted ones if conditions are met
253 263 if have_zi and have_twisted and have_foolscap:
254 264 trial_testers = [IPTester('trial',params=v) for v in trial_packages]
255 265 runners.update(dict(zip(trial_packages,trial_testers)))
256 266
257 267 return runners
258 268
259 269
260 270 def run_iptest():
261 271 """Run the IPython test suite using nose.
262 272
263 273 This function is called when this script is **not** called with the form
264 274 `iptest all`. It simply calls nose with appropriate command line flags
265 275 and accepts all of the standard nose arguments.
266 276 """
267 277
268 278 warnings.filterwarnings('ignore',
269 279 'This will be removed soon. Use IPython.testing.util instead')
270 280
271 argv = sys.argv + [
272 # Loading ipdoctest causes problems with Twisted.
273 # I am removing this as a temporary fix to get the
274 # test suite back into working shape. Our nose
275 # plugin needs to be gone through with a fine
276 # toothed comb to find what is causing the problem.
277 # '--with-ipdoctest',
278 # '--ipdoctest-tests','--ipdoctest-extension=txt',
279 # '--detailed-errors',
280
281 argv = sys.argv + [ '--detailed-errors',
282 # Loading ipdoctest causes problems with Twisted, but
283 # our test suite runner now separates things and runs
284 # all Twisted tests with trial.
285 '--with-ipdoctest',
286 '--ipdoctest-tests','--ipdoctest-extension=txt',
287
288 #'-x','-s', # dbg
289
281 290 # We add --exe because of setuptools' imbecility (it
282 291 # blindly does chmod +x on ALL files). Nose does the
283 292 # right thing and it tries to avoid executables,
284 293 # setuptools unfortunately forces our hand here. This
285 294 # has been discussed on the distutils list and the
286 295 # setuptools devs refuse to fix this problem!
287 296 '--exe',
288 297 ]
289 298
290 299 # Detect if any tests were required by explicitly calling an IPython
291 300 # submodule or giving a specific path
292 301 has_tests = False
293 302 for arg in sys.argv:
294 303 if 'IPython' in arg or arg.endswith('.py') or \
295 304 (':' in arg and '.py' in arg):
296 305 has_tests = True
297 306 break
298 307
299 308 # If nothing was specifically requested, test full IPython
300 309 if not has_tests:
301 310 argv.append('IPython')
302 311
303 # Construct list of plugins, omitting the existing doctest plugin, which
304 # ours replaces (and extends).
305 EXCLUDE = make_exclude()
306 plugins = []
307 # plugins = [IPythonDoctest(EXCLUDE)]
312 ## # Construct list of plugins, omitting the existing doctest plugin, which
313 ## # ours replaces (and extends).
314 plugins = [IPythonDoctest(make_exclude())]
308 315 for p in nose.plugins.builtin.plugins:
309 316 plug = p()
310 317 if plug.name == 'doctest':
311 318 continue
312 319 plugins.append(plug)
313 320
321 # We need a global ipython running in this process
322 globalipapp.start_ipython()
323 # Now nose can run
314 324 TestProgram(argv=argv,plugins=plugins)
315 325
316 326
317 327 def run_iptestall():
318 328 """Run the entire IPython test suite by calling nose and trial.
319 329
320 330 This function constructs :class:`IPTester` instances for all IPython
321 331 modules and package and then runs each of them. This causes the modules
322 332 and packages of IPython to be tested each in their own subprocess using
323 333 nose or twisted.trial appropriately.
324 334 """
325 335
326 336 runners = make_runners()
327 337
328 338 # Run the test runners in a temporary dir so we can nuke it when finished
329 339 # to clean up any junk files left over by accident. This also makes it
330 340 # robust against being run in non-writeable directories by mistake, as the
331 341 # temp dir will always be user-writeable.
332 342 curdir = os.getcwd()
333 343 testdir = tempfile.gettempdir()
334 344 os.chdir(testdir)
335 345
336 346 # Run all test runners, tracking execution time
337 347 failed = {}
338 348 t_start = time.time()
339 349 try:
340 350 for name,runner in runners.iteritems():
341 351 print '*'*77
342 352 print 'IPython test group:',name
343 353 res = runner.run()
344 354 if res:
345 355 failed[name] = res
346 356 finally:
347 357 os.chdir(curdir)
348 358 t_end = time.time()
349 359 t_tests = t_end - t_start
350 360 nrunners = len(runners)
351 361 nfail = len(failed)
352 362 # summarize results
353 363 print
354 364 print '*'*77
355 365 print 'Ran %s test groups in %.3fs' % (nrunners, t_tests)
356 366 print
357 367 if not failed:
358 368 print 'OK'
359 369 else:
360 370 # If anything went wrong, point out what command to rerun manually to
361 371 # see the actual errors and individual summary
362 372 print 'ERROR - %s out of %s test groups failed.' % (nfail, nrunners)
363 373 for name in failed:
364 374 failed_runner = runners[name]
365 375 print '-'*40
366 376 print 'Runner failed:',name
367 377 print 'You may wish to rerun this one individually, with:'
368 378 print ' '.join(failed_runner.call_args)
369 379 print
370 380
371 381
372 382 def main():
373 383 if len(sys.argv) == 1:
374 384 run_iptestall()
375 385 else:
376 386 if sys.argv[1] == 'all':
377 387 run_iptestall()
378 388 else:
379 389 run_iptest()
380 390
381 391
382 392 if __name__ == '__main__':
383 393 main()
@@ -1,156 +1,188 b''
1 1 """Experimental code for cleaner support of IPython syntax with unittest.
2 2
3 3 In IPython up until 0.10, we've used very hacked up nose machinery for running
4 4 tests with IPython special syntax, and this has proved to be extremely slow.
5 5 This module provides decorators to try a different approach, stemming from a
6 6 conversation Brian and I (FP) had about this problem Sept/09.
7 7
8 8 The goal is to be able to easily write simple functions that can be seen by
9 9 unittest as tests, and ultimately for these to support doctests with full
10 10 IPython syntax. Nose already offers this based on naming conventions and our
11 11 hackish plugins, but we are seeking to move away from nose dependencies if
12 12 possible.
13 13
14 14 This module follows a different approach, based on decorators.
15 15
16 16 - A decorator called @ipdoctest can mark any function as having a docstring
17 17 that should be viewed as a doctest, but after syntax conversion.
18 18
19 19 Authors
20 20 -------
21 21
22 22 - Fernando Perez <Fernando.Perez@berkeley.edu>
23 23 """
24 24
25 from __future__ import absolute_import
26
25 27 #-----------------------------------------------------------------------------
26 28 # Copyright (C) 2009 The IPython Development Team
27 29 #
28 30 # Distributed under the terms of the BSD License. The full license is in
29 31 # the file COPYING, distributed as part of this software.
30 32 #-----------------------------------------------------------------------------
31 33
32 34
33 35 #-----------------------------------------------------------------------------
34 36 # Imports
35 37 #-----------------------------------------------------------------------------
36 38
37 39 # Stdlib
38 40 import re
39 41 import sys
40 42 import unittest
41 43 from doctest import DocTestFinder, DocTestRunner, TestResults
42 44
43 # Our own
44 import nosepatch
45 # Our own, a nose monkeypatch
46 from . import nosepatch
45 47
46 48 # We already have python3-compliant code for parametric tests
47 49 if sys.version[0]=='2':
48 from _paramtestpy2 import ParametricTestCase
50 from ._paramtestpy2 import ParametricTestCase
49 51 else:
50 from _paramtestpy3 import ParametricTestCase
52 from ._paramtestpy3 import ParametricTestCase
53
54 from . import globalipapp
51 55
52 56 #-----------------------------------------------------------------------------
53 57 # Classes and functions
54 58 #-----------------------------------------------------------------------------
55 59
56 60 def count_failures(runner):
57 61 """Count number of failures in a doctest runner.
58 62
59 63 Code modeled after the summarize() method in doctest.
60 64 """
61 65 return [TestResults(f, t) for f, t in runner._name2ft.values() if f > 0 ]
62 66
63 67
64 68 class IPython2PythonConverter(object):
65 69 """Convert IPython 'syntax' to valid Python.
66 70
67 71 Eventually this code may grow to be the full IPython syntax conversion
68 72 implementation, but for now it only does prompt convertion."""
69 73
70 74 def __init__(self):
71 self.ps1 = re.compile(r'In\ \[\d+\]: ')
72 self.ps2 = re.compile(r'\ \ \ \.\.\.+: ')
73 self.out = re.compile(r'Out\[\d+\]: \s*?\n?')
75 self.rps1 = re.compile(r'In\ \[\d+\]: ')
76 self.rps2 = re.compile(r'\ \ \ \.\.\.+: ')
77 self.rout = re.compile(r'Out\[\d+\]: \s*?\n?')
78 self.pyps1 = '>>> '
79 self.pyps2 = '... '
80 self.rpyps1 = re.compile ('(\s*%s)(.*)$' % self.pyps1)
81 self.rpyps2 = re.compile ('(\s*%s)(.*)$' % self.pyps2)
74 82
75 83 def __call__(self, ds):
76 84 """Convert IPython prompts to python ones in a string."""
77 85 pyps1 = '>>> '
78 86 pyps2 = '... '
79 87 pyout = ''
80 88
81 89 dnew = ds
82 dnew = self.ps1.sub(pyps1, dnew)
83 dnew = self.ps2.sub(pyps2, dnew)
84 dnew = self.out.sub(pyout, dnew)
85 return dnew
90 dnew = self.rps1.sub(pyps1, dnew)
91 dnew = self.rps2.sub(pyps2, dnew)
92 dnew = self.rout.sub(pyout, dnew)
93 ip = globalipapp.get_ipython()
94
95 # Convert input IPython source into valid Python.
96 out = []
97 newline = out.append
98 for line in dnew.splitlines():
99
100 mps1 = self.rpyps1.match(line)
101 if mps1 is not None:
102 prompt, text = mps1.groups()
103 newline(prompt+ip.prefilter(text, False))
104 continue
105
106 mps2 = self.rpyps2.match(line)
107 if mps2 is not None:
108 prompt, text = mps2.groups()
109 newline(prompt+ip.prefilter(text, True))
110 continue
111
112 newline(line)
113 newline('') # ensure a closing newline, needed by doctest
114 #print "PYSRC:", '\n'.join(out) # dbg
115 return '\n'.join(out)
116
117 #return dnew
86 118
87 119
88 120 class Doc2UnitTester(object):
89 121 """Class whose instances act as a decorator for docstring testing.
90 122
91 123 In practice we're only likely to need one instance ever, made below (though
92 124 no attempt is made at turning it into a singleton, there is no need for
93 125 that).
94 126 """
95 127 def __init__(self, verbose=False):
96 128 """New decorator.
97 129
98 130 Parameters
99 131 ----------
100 132
101 133 verbose : boolean, optional (False)
102 134 Passed to the doctest finder and runner to control verbosity.
103 135 """
104 136 self.verbose = verbose
105 137 # We can reuse the same finder for all instances
106 138 self.finder = DocTestFinder(verbose=verbose, recurse=False)
107 139
108 140 def __call__(self, func):
109 141 """Use as a decorator: doctest a function's docstring as a unittest.
110 142
111 143 This version runs normal doctests, but the idea is to make it later run
112 144 ipython syntax instead."""
113 145
114 146 # Capture the enclosing instance with a different name, so the new
115 147 # class below can see it without confusion regarding its own 'self'
116 148 # that will point to the test instance at runtime
117 149 d2u = self
118 150
119 151 # Rewrite the function's docstring to have python syntax
120 152 if func.__doc__ is not None:
121 153 func.__doc__ = ip2py(func.__doc__)
122 154
123 155 # Now, create a tester object that is a real unittest instance, so
124 156 # normal unittest machinery (or Nose, or Trial) can find it.
125 157 class Tester(unittest.TestCase):
126 158 def test(self):
127 159 # Make a new runner per function to be tested
128 160 runner = DocTestRunner(verbose=d2u.verbose)
129 161 map(runner.run, d2u.finder.find(func, func.__name__))
130 162 failed = count_failures(runner)
131 163 if failed:
132 164 # Since we only looked at a single function's docstring,
133 165 # failed should contain at most one item. More than that
134 166 # is a case we can't handle and should error out on
135 167 if len(failed) > 1:
136 168 err = "Invalid number of test results:" % failed
137 169 raise ValueError(err)
138 170 # Report a normal failure.
139 171 self.fail('failed doctests: %s' % str(failed[0]))
140 172
141 173 # Rename it so test reports have the original signature.
142 174 Tester.__name__ = func.__name__
143 175 return Tester
144 176
145 177
146 178 def ipdocstring(func):
147 179 """Change the function docstring via ip2py.
148 180 """
149 181 if func.__doc__ is not None:
150 182 func.__doc__ = ip2py(func.__doc__)
151 183 return func
152 184
153 185
154 186 # Make an instance of the classes for public use
155 187 ipdoctest = Doc2UnitTester()
156 188 ip2py = IPython2PythonConverter()
@@ -1,940 +1,779 b''
1 1 """Nose Plugin that supports IPython doctests.
2 2
3 3 Limitations:
4 4
5 5 - When generating examples for use as doctests, make sure that you have
6 6 pretty-printing OFF. This can be done either by starting ipython with the
7 7 flag '--nopprint', by setting pprint to 0 in your ipythonrc file, or by
8 8 interactively disabling it with %Pprint. This is required so that IPython
9 9 output matches that of normal Python, which is used by doctest for internal
10 10 execution.
11 11
12 12 - Do not rely on specific prompt numbers for results (such as using
13 13 '_34==True', for example). For IPython tests run via an external process the
14 14 prompt numbers may be different, and IPython tests run as normal python code
15 15 won't even have these special _NN variables set at all.
16 16 """
17 17
18 18 #-----------------------------------------------------------------------------
19 19 # Module imports
20 20
21 21 # From the standard library
22 22 import __builtin__
23 23 import commands
24 24 import doctest
25 25 import inspect
26 26 import logging
27 27 import os
28 28 import re
29 29 import sys
30 30 import traceback
31 31 import unittest
32 32
33 33 from inspect import getmodule
34 34 from StringIO import StringIO
35 35
36 36 # We are overriding the default doctest runner, so we need to import a few
37 37 # things from doctest directly
38 38 from doctest import (REPORTING_FLAGS, REPORT_ONLY_FIRST_FAILURE,
39 39 _unittest_reportflags, DocTestRunner,
40 40 _extract_future_flags, pdb, _OutputRedirectingPdb,
41 41 _exception_traceback,
42 42 linecache)
43 43
44 44 # Third-party modules
45 45 import nose.core
46 46
47 47 from nose.plugins import doctests, Plugin
48 48 from nose.util import anyp, getpackage, test_address, resolve_name, tolist
49 49
50 50 #-----------------------------------------------------------------------------
51 51 # Module globals and other constants
52 #-----------------------------------------------------------------------------
52 53
53 54 log = logging.getLogger(__name__)
54 55
55 ###########################################################################
56 # *** HACK ***
57 # We must start our own ipython object and heavily muck with it so that all the
58 # modifications IPython makes to system behavior don't send the doctest
59 # machinery into a fit. This code should be considered a gross hack, but it
60 # gets the job done.
61
62 def default_argv():
63 """Return a valid default argv for creating testing instances of ipython"""
64
65 # Get the install directory for the user configuration and tell ipython to
66 # use the default profile from there.
67 from IPython.config import default
68 ipcdir = os.path.dirname(default.__file__)
69 ipconf = os.path.join(ipcdir,'ipython_config.py')
70 #print 'conf:',ipconf # dbg
71 return ['--colors=NoColor', '--no-term-title','--no-banner',
72 '--config-file=%s' % ipconf]
73
74
75 # Hack to modify the %run command so we can sync the user's namespace with the
76 # test globals. Once we move over to a clean magic system, this will be done
77 # with much less ugliness.
78
79 class py_file_finder(object):
80 def __init__(self,test_filename):
81 self.test_filename = test_filename
82
83 def __call__(self,name):
84 from IPython.utils.genutils import get_py_filename
85 try:
86 return get_py_filename(name)
87 except IOError:
88 test_dir = os.path.dirname(self.test_filename)
89 new_path = os.path.join(test_dir,name)
90 return get_py_filename(new_path)
91
92
93 def _run_ns_sync(self,arg_s,runner=None):
94 """Modified version of %run that syncs testing namespaces.
95
96 This is strictly needed for running doctests that call %run.
97 """
98
99 # When tests call %run directly (not via doctest) these function attributes
100 # are not set
101 try:
102 fname = _run_ns_sync.test_filename
103 except AttributeError:
104 fname = arg_s
105
106 finder = py_file_finder(fname)
107 out = _ip.magic_run_ori(arg_s,runner,finder)
108
109 # Simliarly, there is no test_globs when a test is NOT a doctest
110 if hasattr(_run_ns_sync,'test_globs'):
111 _run_ns_sync.test_globs.update(_ip.user_ns)
112 return out
113
114
115 class ipnsdict(dict):
116 """A special subclass of dict for use as an IPython namespace in doctests.
117
118 This subclass adds a simple checkpointing capability so that when testing
119 machinery clears it (we use it as the test execution context), it doesn't
120 get completely destroyed.
121 """
122
123 def __init__(self,*a):
124 dict.__init__(self,*a)
125 self._savedict = {}
126
127 def clear(self):
128 dict.clear(self)
129 self.update(self._savedict)
130
131 def _checkpoint(self):
132 self._savedict.clear()
133 self._savedict.update(self)
134
135 def update(self,other):
136 self._checkpoint()
137 dict.update(self,other)
138
139 # If '_' is in the namespace, python won't set it when executing code,
140 # and we have examples that test it. So we ensure that the namespace
141 # is always 'clean' of it before it's used for test code execution.
142 self.pop('_',None)
143
144 # The builtins namespace must *always* be the real __builtin__ module,
145 # else weird stuff happens. The main ipython code does have provisions
146 # to ensure this after %run, but since in this class we do some
147 # aggressive low-level cleaning of the execution namespace, we need to
148 # correct for that ourselves, to ensure consitency with the 'real'
149 # ipython.
150 self['__builtins__'] = __builtin__
151
152
153 def start_ipython():
154 """Start a global IPython shell, which we need for IPython-specific syntax.
155 """
156
157 # This function should only ever run once!
158 if hasattr(start_ipython,'already_called'):
159 return
160 start_ipython.already_called = True
161
162 # Ok, first time we're called, go ahead
163 import new
164
165 import IPython
166 from IPython.core import ipapp, iplib
167
168 def xsys(cmd):
169 """Execute a command and print its output.
170
171 This is just a convenience function to replace the IPython system call
172 with one that is more doctest-friendly.
173 """
174 cmd = _ip.var_expand(cmd,depth=1)
175 sys.stdout.write(commands.getoutput(cmd))
176 sys.stdout.flush()
177
178 # Store certain global objects that IPython modifies
179 _displayhook = sys.displayhook
180 _excepthook = sys.excepthook
181 _main = sys.modules.get('__main__')
182
183 argv = default_argv()
184
185 # Start IPython instance. We customize it to start with minimal frills.
186 user_ns,global_ns = iplib.make_user_namespaces(ipnsdict(),{})
187 ip = ipapp.IPythonApp(argv, user_ns=user_ns, user_global_ns=global_ns)
188 ip.initialize()
189 ip.shell.builtin_trap.set()
190
191 # Deactivate the various python system hooks added by ipython for
192 # interactive convenience so we don't confuse the doctest system
193 sys.modules['__main__'] = _main
194 sys.displayhook = _displayhook
195 sys.excepthook = _excepthook
196
197 # So that ipython magics and aliases can be doctested (they work by making
198 # a call into a global _ip object)
199 __builtin__._ip = ip.shell
200
201 # Modify the IPython system call with one that uses getoutput, so that we
202 # can capture subcommands and print them to Python's stdout, otherwise the
203 # doctest machinery would miss them.
204 ip.shell.system = xsys
205
206 # Also patch our %run function in.
207 im = new.instancemethod(_run_ns_sync,_ip, _ip.__class__)
208 ip.shell.magic_run_ori = _ip.magic_run
209 ip.shell.magic_run = im
210
211 # XXX - For some very bizarre reason, the loading of %history by default is
212 # failing. This needs to be fixed later, but for now at least this ensures
213 # that tests that use %hist run to completion.
214 from IPython.core import history
215 history.init_ipython(ip.shell)
216 if not hasattr(ip.shell,'magic_history'):
217 raise RuntimeError("Can't load magics, aborting")
218
219
220 # The start call MUST be made here. I'm not sure yet why it doesn't work if
221 # it is made later, at plugin initialization time, but in all my tests, that's
222 # the case.
223 start_ipython()
224
225 # *** END HACK ***
226 ###########################################################################
227 56
57 #-----------------------------------------------------------------------------
228 58 # Classes and functions
59 #-----------------------------------------------------------------------------
229 60
230 61 def is_extension_module(filename):
231 62 """Return whether the given filename is an extension module.
232 63
233 64 This simply checks that the extension is either .so or .pyd.
234 65 """
235 66 return os.path.splitext(filename)[1].lower() in ('.so','.pyd')
236 67
237 68
238 69 class DocTestSkip(object):
239 70 """Object wrapper for doctests to be skipped."""
240 71
241 72 ds_skip = """Doctest to skip.
242 73 >>> 1 #doctest: +SKIP
243 74 """
244 75
245 76 def __init__(self,obj):
246 77 self.obj = obj
247 78
248 79 def __getattribute__(self,key):
249 80 if key == '__doc__':
250 81 return DocTestSkip.ds_skip
251 82 else:
252 83 return getattr(object.__getattribute__(self,'obj'),key)
253 84
254 85 # Modified version of the one in the stdlib, that fixes a python bug (doctests
255 86 # not found in extension modules, http://bugs.python.org/issue3158)
256 87 class DocTestFinder(doctest.DocTestFinder):
257 88
258 89 def _from_module(self, module, object):
259 90 """
260 91 Return true if the given object is defined in the given
261 92 module.
262 93 """
263 94 if module is None:
264 95 return True
265 96 elif inspect.isfunction(object):
266 97 return module.__dict__ is object.func_globals
267 98 elif inspect.isbuiltin(object):
268 99 return module.__name__ == object.__module__
269 100 elif inspect.isclass(object):
270 101 return module.__name__ == object.__module__
271 102 elif inspect.ismethod(object):
272 103 # This one may be a bug in cython that fails to correctly set the
273 104 # __module__ attribute of methods, but since the same error is easy
274 105 # to make by extension code writers, having this safety in place
275 106 # isn't such a bad idea
276 107 return module.__name__ == object.im_class.__module__
277 108 elif inspect.getmodule(object) is not None:
278 109 return module is inspect.getmodule(object)
279 110 elif hasattr(object, '__module__'):
280 111 return module.__name__ == object.__module__
281 112 elif isinstance(object, property):
282 113 return True # [XX] no way not be sure.
283 114 else:
284 115 raise ValueError("object must be a class or function")
285 116
286 117 def _find(self, tests, obj, name, module, source_lines, globs, seen):
287 118 """
288 119 Find tests for the given object and any contained objects, and
289 120 add them to `tests`.
290 121 """
291
122 #print '_find for:', obj, name, module # dbg
292 123 if hasattr(obj,"skip_doctest"):
293 124 #print 'SKIPPING DOCTEST FOR:',obj # dbg
294 125 obj = DocTestSkip(obj)
295 126
296 127 doctest.DocTestFinder._find(self,tests, obj, name, module,
297 128 source_lines, globs, seen)
298 129
299 130 # Below we re-run pieces of the above method with manual modifications,
300 131 # because the original code is buggy and fails to correctly identify
301 132 # doctests in extension modules.
302 133
303 134 # Local shorthands
304 135 from inspect import isroutine, isclass, ismodule
305 136
306 137 # Look for tests in a module's contained objects.
307 138 if inspect.ismodule(obj) and self._recurse:
308 139 for valname, val in obj.__dict__.items():
309 140 valname1 = '%s.%s' % (name, valname)
310 141 if ( (isroutine(val) or isclass(val))
311 142 and self._from_module(module, val) ):
312 143
313 144 self._find(tests, val, valname1, module, source_lines,
314 145 globs, seen)
315 146
316 147 # Look for tests in a class's contained objects.
317 148 if inspect.isclass(obj) and self._recurse:
318 149 #print 'RECURSE into class:',obj # dbg
319 150 for valname, val in obj.__dict__.items():
320 151 # Special handling for staticmethod/classmethod.
321 152 if isinstance(val, staticmethod):
322 153 val = getattr(obj, valname)
323 154 if isinstance(val, classmethod):
324 155 val = getattr(obj, valname).im_func
325 156
326 157 # Recurse to methods, properties, and nested classes.
327 158 if ((inspect.isfunction(val) or inspect.isclass(val) or
328 159 inspect.ismethod(val) or
329 160 isinstance(val, property)) and
330 161 self._from_module(module, val)):
331 162 valname = '%s.%s' % (name, valname)
332 163 self._find(tests, val, valname, module, source_lines,
333 164 globs, seen)
334 165
335 166
336 167 class IPDoctestOutputChecker(doctest.OutputChecker):
337 168 """Second-chance checker with support for random tests.
338 169
339 170 If the default comparison doesn't pass, this checker looks in the expected
340 171 output string for flags that tell us to ignore the output.
341 172 """
342 173
343 174 random_re = re.compile(r'#\s*random\s+')
344 175
345 176 def check_output(self, want, got, optionflags):
346 177 """Check output, accepting special markers embedded in the output.
347 178
348 179 If the output didn't pass the default validation but the special string
349 180 '#random' is included, we accept it."""
350 181
351 182 # Let the original tester verify first, in case people have valid tests
352 183 # that happen to have a comment saying '#random' embedded in.
353 184 ret = doctest.OutputChecker.check_output(self, want, got,
354 185 optionflags)
355 186 if not ret and self.random_re.search(want):
356 187 #print >> sys.stderr, 'RANDOM OK:',want # dbg
357 188 return True
358 189
359 190 return ret
360 191
361 192
362 193 class DocTestCase(doctests.DocTestCase):
363 194 """Proxy for DocTestCase: provides an address() method that
364 195 returns the correct address for the doctest case. Otherwise
365 196 acts as a proxy to the test case. To provide hints for address(),
366 197 an obj may also be passed -- this will be used as the test object
367 198 for purposes of determining the test address, if it is provided.
368 199 """
369 200
370 201 # Note: this method was taken from numpy's nosetester module.
371 202
372 203 # Subclass nose.plugins.doctests.DocTestCase to work around a bug in
373 204 # its constructor that blocks non-default arguments from being passed
374 205 # down into doctest.DocTestCase
375 206
376 207 def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
377 208 checker=None, obj=None, result_var='_'):
378 209 self._result_var = result_var
379 210 doctests.DocTestCase.__init__(self, test,
380 211 optionflags=optionflags,
381 212 setUp=setUp, tearDown=tearDown,
382 213 checker=checker)
383 214 # Now we must actually copy the original constructor from the stdlib
384 215 # doctest class, because we can't call it directly and a bug in nose
385 216 # means it never gets passed the right arguments.
386 217
387 218 self._dt_optionflags = optionflags
388 219 self._dt_checker = checker
389 220 self._dt_test = test
390 221 self._dt_setUp = setUp
391 222 self._dt_tearDown = tearDown
392 223
393 224 # XXX - store this runner once in the object!
394 225 runner = IPDocTestRunner(optionflags=optionflags,
395 226 checker=checker, verbose=False)
396 227 self._dt_runner = runner
397 228
398 229
399 # Each doctest should remember what directory it was loaded from...
400 self._ori_dir = os.getcwd()
230 # Each doctest should remember the directory it was loaded from, so
231 # things like %run work without too many contortions
232 self._ori_dir = os.path.dirname(test.filename)
401 233
402 234 # Modified runTest from the default stdlib
403 235 def runTest(self):
404 236 test = self._dt_test
405 237 runner = self._dt_runner
406 238
407 239 old = sys.stdout
408 240 new = StringIO()
409 241 optionflags = self._dt_optionflags
410 242
411 243 if not (optionflags & REPORTING_FLAGS):
412 244 # The option flags don't include any reporting flags,
413 245 # so add the default reporting flags
414 246 optionflags |= _unittest_reportflags
415 247
416 248 try:
417 249 # Save our current directory and switch out to the one where the
418 250 # test was originally created, in case another doctest did a
419 251 # directory change. We'll restore this in the finally clause.
420 252 curdir = os.getcwd()
253 #print 'runTest in dir:', self._ori_dir # dbg
421 254 os.chdir(self._ori_dir)
422 255
423 256 runner.DIVIDER = "-"*70
424 257 failures, tries = runner.run(test,out=new.write,
425 258 clear_globs=False)
426 259 finally:
427 260 sys.stdout = old
428 261 os.chdir(curdir)
429 262
430 263 if failures:
431 264 raise self.failureException(self.format_failure(new.getvalue()))
432 265
433 266 def setUp(self):
434 267 """Modified test setup that syncs with ipython namespace"""
435
268 #print "setUp test", self._dt_test.examples # dbg
436 269 if isinstance(self._dt_test.examples[0],IPExample):
437 270 # for IPython examples *only*, we swap the globals with the ipython
438 271 # namespace, after updating it with the globals (which doctest
439 272 # fills with the necessary info from the module being tested).
440 273 _ip.user_ns.update(self._dt_test.globs)
441 274 self._dt_test.globs = _ip.user_ns
442 275
443 276 super(DocTestCase, self).setUp()
444 277
445 278 def tearDown(self):
446 279 # XXX - fperez: I am not sure if this is truly a bug in nose 0.11, but
447 280 # it does look like one to me: its tearDown method tries to run
448 281 #
449 282 # delattr(__builtin__, self._result_var)
450 283 #
451 284 # without checking that the attribute really is there; it implicitly
452 285 # assumes it should have been set via displayhook. But if the
453 286 # displayhook was never called, this doesn't necessarily happen. I
454 287 # haven't been able to find a little self-contained example outside of
455 288 # ipython that would show the problem so I can report it to the nose
456 289 # team, but it does happen a lot in our code.
457 290 #
458 291 # So here, we just protect as narrowly as possible by trapping an
459 292 # attribute error whose message would be the name of self._result_var,
460 293 # and letting any other error propagate.
461 294 try:
462 295 super(DocTestCase, self).tearDown()
463 296 except AttributeError, exc:
464 297 if exc.args[0] != self._result_var:
465 298 raise
466 299
467 300
468 301 # A simple subclassing of the original with a different class name, so we can
469 302 # distinguish and treat differently IPython examples from pure python ones.
470 303 class IPExample(doctest.Example): pass
471 304
472 305
473 306 class IPExternalExample(doctest.Example):
474 307 """Doctest examples to be run in an external process."""
475 308
476 309 def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
477 310 options=None):
478 311 # Parent constructor
479 312 doctest.Example.__init__(self,source,want,exc_msg,lineno,indent,options)
480 313
481 314 # An EXTRA newline is needed to prevent pexpect hangs
482 315 self.source += '\n'
483 316
484 317
485 318 class IPDocTestParser(doctest.DocTestParser):
486 319 """
487 320 A class used to parse strings containing doctest examples.
488 321
489 322 Note: This is a version modified to properly recognize IPython input and
490 323 convert any IPython examples into valid Python ones.
491 324 """
492 325 # This regular expression is used to find doctest examples in a
493 326 # string. It defines three groups: `source` is the source code
494 327 # (including leading indentation and prompts); `indent` is the
495 328 # indentation of the first (PS1) line of the source code; and
496 329 # `want` is the expected output (including leading indentation).
497 330
498 331 # Classic Python prompts or default IPython ones
499 332 _PS1_PY = r'>>>'
500 333 _PS2_PY = r'\.\.\.'
501 334
502 335 _PS1_IP = r'In\ \[\d+\]:'
503 336 _PS2_IP = r'\ \ \ \.\.\.+:'
504 337
505 338 _RE_TPL = r'''
506 339 # Source consists of a PS1 line followed by zero or more PS2 lines.
507 340 (?P<source>
508 341 (?:^(?P<indent> [ ]*) (?P<ps1> %s) .*) # PS1 line
509 342 (?:\n [ ]* (?P<ps2> %s) .*)*) # PS2 lines
510 343 \n? # a newline
511 344 # Want consists of any non-blank lines that do not start with PS1.
512 345 (?P<want> (?:(?![ ]*$) # Not a blank line
513 346 (?![ ]*%s) # Not a line starting with PS1
514 347 (?![ ]*%s) # Not a line starting with PS2
515 348 .*$\n? # But any other line
516 349 )*)
517 350 '''
518 351
519 352 _EXAMPLE_RE_PY = re.compile( _RE_TPL % (_PS1_PY,_PS2_PY,_PS1_PY,_PS2_PY),
520 353 re.MULTILINE | re.VERBOSE)
521 354
522 355 _EXAMPLE_RE_IP = re.compile( _RE_TPL % (_PS1_IP,_PS2_IP,_PS1_IP,_PS2_IP),
523 356 re.MULTILINE | re.VERBOSE)
524 357
525 358 # Mark a test as being fully random. In this case, we simply append the
526 359 # random marker ('#random') to each individual example's output. This way
527 360 # we don't need to modify any other code.
528 361 _RANDOM_TEST = re.compile(r'#\s*all-random\s+')
529 362
530 363 # Mark tests to be executed in an external process - currently unsupported.
531 364 _EXTERNAL_IP = re.compile(r'#\s*ipdoctest:\s*EXTERNAL')
532 365
533 366 def ip2py(self,source):
534 367 """Convert input IPython source into valid Python."""
535 368 out = []
536 369 newline = out.append
537 370 #print 'IPSRC:\n',source,'\n###' # dbg
538 371 # The input source must be first stripped of all bracketing whitespace
539 372 # and turned into lines, so it looks to the parser like regular user
540 373 # input
541 374 for lnum,line in enumerate(source.strip().splitlines()):
542 375 newline(_ip.prefilter(line,lnum>0))
543 376 newline('') # ensure a closing newline, needed by doctest
544 377 #print "PYSRC:", '\n'.join(out) # dbg
545 378 return '\n'.join(out)
546 379
547 380 def parse(self, string, name='<string>'):
548 381 """
549 382 Divide the given string into examples and intervening text,
550 383 and return them as a list of alternating Examples and strings.
551 384 Line numbers for the Examples are 0-based. The optional
552 385 argument `name` is a name identifying this string, and is only
553 386 used for error messages.
554 387 """
555 388
556 389 #print 'Parse string:\n',string # dbg
557 390
558 391 string = string.expandtabs()
559 392 # If all lines begin with the same indentation, then strip it.
560 393 min_indent = self._min_indent(string)
561 394 if min_indent > 0:
562 395 string = '\n'.join([l[min_indent:] for l in string.split('\n')])
563 396
564 397 output = []
565 398 charno, lineno = 0, 0
566 399
567 400 # We make 'all random' tests by adding the '# random' mark to every
568 401 # block of output in the test.
569 402 if self._RANDOM_TEST.search(string):
570 403 random_marker = '\n# random'
571 404 else:
572 405 random_marker = ''
573 406
574 407 # Whether to convert the input from ipython to python syntax
575 408 ip2py = False
576 409 # Find all doctest examples in the string. First, try them as Python
577 410 # examples, then as IPython ones
578 411 terms = list(self._EXAMPLE_RE_PY.finditer(string))
579 412 if terms:
580 413 # Normal Python example
581 414 #print '-'*70 # dbg
582 415 #print 'PyExample, Source:\n',string # dbg
583 416 #print '-'*70 # dbg
584 417 Example = doctest.Example
585 418 else:
586 419 # It's an ipython example. Note that IPExamples are run
587 420 # in-process, so their syntax must be turned into valid python.
588 421 # IPExternalExamples are run out-of-process (via pexpect) so they
589 422 # don't need any filtering (a real ipython will be executing them).
590 423 terms = list(self._EXAMPLE_RE_IP.finditer(string))
591 424 if self._EXTERNAL_IP.search(string):
592 425 #print '-'*70 # dbg
593 426 #print 'IPExternalExample, Source:\n',string # dbg
594 427 #print '-'*70 # dbg
595 428 Example = IPExternalExample
596 429 else:
597 430 #print '-'*70 # dbg
598 431 #print 'IPExample, Source:\n',string # dbg
599 432 #print '-'*70 # dbg
600 433 Example = IPExample
601 434 ip2py = True
602 435
603 436 for m in terms:
604 437 # Add the pre-example text to `output`.
605 438 output.append(string[charno:m.start()])
606 439 # Update lineno (lines before this example)
607 440 lineno += string.count('\n', charno, m.start())
608 441 # Extract info from the regexp match.
609 442 (source, options, want, exc_msg) = \
610 443 self._parse_example(m, name, lineno,ip2py)
611 444
612 445 # Append the random-output marker (it defaults to empty in most
613 446 # cases, it's only non-empty for 'all-random' tests):
614 447 want += random_marker
615 448
616 449 if Example is IPExternalExample:
617 450 options[doctest.NORMALIZE_WHITESPACE] = True
618 451 want += '\n'
619 452
620 453 # Create an Example, and add it to the list.
621 454 if not self._IS_BLANK_OR_COMMENT(source):
622 455 output.append(Example(source, want, exc_msg,
623 456 lineno=lineno,
624 457 indent=min_indent+len(m.group('indent')),
625 458 options=options))
626 459 # Update lineno (lines inside this example)
627 460 lineno += string.count('\n', m.start(), m.end())
628 461 # Update charno.
629 462 charno = m.end()
630 463 # Add any remaining post-example text to `output`.
631 464 output.append(string[charno:])
632 465 return output
633 466
634 467 def _parse_example(self, m, name, lineno,ip2py=False):
635 468 """
636 469 Given a regular expression match from `_EXAMPLE_RE` (`m`),
637 470 return a pair `(source, want)`, where `source` is the matched
638 471 example's source code (with prompts and indentation stripped);
639 472 and `want` is the example's expected output (with indentation
640 473 stripped).
641 474
642 475 `name` is the string's name, and `lineno` is the line number
643 476 where the example starts; both are used for error messages.
644 477
645 478 Optional:
646 479 `ip2py`: if true, filter the input via IPython to convert the syntax
647 480 into valid python.
648 481 """
649 482
650 483 # Get the example's indentation level.
651 484 indent = len(m.group('indent'))
652 485
653 486 # Divide source into lines; check that they're properly
654 487 # indented; and then strip their indentation & prompts.
655 488 source_lines = m.group('source').split('\n')
656 489
657 490 # We're using variable-length input prompts
658 491 ps1 = m.group('ps1')
659 492 ps2 = m.group('ps2')
660 493 ps1_len = len(ps1)
661 494
662 495 self._check_prompt_blank(source_lines, indent, name, lineno,ps1_len)
663 496 if ps2:
664 497 self._check_prefix(source_lines[1:], ' '*indent + ps2, name, lineno)
665 498
666 499 source = '\n'.join([sl[indent+ps1_len+1:] for sl in source_lines])
667 500
668 501 if ip2py:
669 502 # Convert source input from IPython into valid Python syntax
670 503 source = self.ip2py(source)
671 504
672 505 # Divide want into lines; check that it's properly indented; and
673 506 # then strip the indentation. Spaces before the last newline should
674 507 # be preserved, so plain rstrip() isn't good enough.
675 508 want = m.group('want')
676 509 want_lines = want.split('\n')
677 510 if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
678 511 del want_lines[-1] # forget final newline & spaces after it
679 512 self._check_prefix(want_lines, ' '*indent, name,
680 513 lineno + len(source_lines))
681 514
682 515 # Remove ipython output prompt that might be present in the first line
683 516 want_lines[0] = re.sub(r'Out\[\d+\]: \s*?\n?','',want_lines[0])
684 517
685 518 want = '\n'.join([wl[indent:] for wl in want_lines])
686 519
687 520 # If `want` contains a traceback message, then extract it.
688 521 m = self._EXCEPTION_RE.match(want)
689 522 if m:
690 523 exc_msg = m.group('msg')
691 524 else:
692 525 exc_msg = None
693 526
694 527 # Extract options from the source.
695 528 options = self._find_options(source, name, lineno)
696 529
697 530 return source, options, want, exc_msg
698 531
699 532 def _check_prompt_blank(self, lines, indent, name, lineno, ps1_len):
700 533 """
701 534 Given the lines of a source string (including prompts and
702 535 leading indentation), check to make sure that every prompt is
703 536 followed by a space character. If any line is not followed by
704 537 a space character, then raise ValueError.
705 538
706 539 Note: IPython-modified version which takes the input prompt length as a
707 540 parameter, so that prompts of variable length can be dealt with.
708 541 """
709 542 space_idx = indent+ps1_len
710 543 min_len = space_idx+1
711 544 for i, line in enumerate(lines):
712 545 if len(line) >= min_len and line[space_idx] != ' ':
713 546 raise ValueError('line %r of the docstring for %s '
714 547 'lacks blank after %s: %r' %
715 548 (lineno+i+1, name,
716 549 line[indent:space_idx], line))
717 550
718 551
719 552 SKIP = doctest.register_optionflag('SKIP')
720 553
721 554
722 555 class IPDocTestRunner(doctest.DocTestRunner,object):
723 556 """Test runner that synchronizes the IPython namespace with test globals.
724 557 """
725 558
726 559 def run(self, test, compileflags=None, out=None, clear_globs=True):
727 560
728 561 # Hack: ipython needs access to the execution context of the example,
729 562 # so that it can propagate user variables loaded by %run into
730 563 # test.globs. We put them here into our modified %run as a function
731 564 # attribute. Our new %run will then only make the namespace update
732 565 # when called (rather than unconconditionally updating test.globs here
733 566 # for all examples, most of which won't be calling %run anyway).
734 _run_ns_sync.test_globs = test.globs
735 _run_ns_sync.test_filename = test.filename
567 #_ip._ipdoctest_test_globs = test.globs
568 #_ip._ipdoctest_test_filename = test.filename
569
570 test.globs.update(_ip.user_ns)
736 571
737 572 return super(IPDocTestRunner,self).run(test,
738 573 compileflags,out,clear_globs)
739 574
740 575
741 576 class DocFileCase(doctest.DocFileCase):
742 577 """Overrides to provide filename
743 578 """
744 579 def address(self):
745 580 return (self._dt_test.filename, None, None)
746 581
747 582
748 583 class ExtensionDoctest(doctests.Doctest):
749 584 """Nose Plugin that supports doctests in extension modules.
750 585 """
751 586 name = 'extdoctest' # call nosetests with --with-extdoctest
752 587 enabled = True
753 588
754 589 def __init__(self,exclude_patterns=None):
755 590 """Create a new ExtensionDoctest plugin.
756 591
757 592 Parameters
758 593 ----------
759 594
760 595 exclude_patterns : sequence of strings, optional
761 596 These patterns are compiled as regular expressions, subsequently used
762 597 to exclude any filename which matches them from inclusion in the test
763 598 suite (using pattern.search(), NOT pattern.match() ).
764 599 """
765 600
766 601 if exclude_patterns is None:
767 602 exclude_patterns = []
768 603 self.exclude_patterns = map(re.compile,exclude_patterns)
769 604 doctests.Doctest.__init__(self)
770 605
771 606 def options(self, parser, env=os.environ):
772 607 Plugin.options(self, parser, env)
773 608 parser.add_option('--doctest-tests', action='store_true',
774 609 dest='doctest_tests',
775 610 default=env.get('NOSE_DOCTEST_TESTS',True),
776 611 help="Also look for doctests in test modules. "
777 612 "Note that classes, methods and functions should "
778 613 "have either doctests or non-doctest tests, "
779 614 "not both. [NOSE_DOCTEST_TESTS]")
780 615 parser.add_option('--doctest-extension', action="append",
781 616 dest="doctestExtension",
782 617 help="Also look for doctests in files with "
783 618 "this extension [NOSE_DOCTEST_EXTENSION]")
784 619 # Set the default as a list, if given in env; otherwise
785 620 # an additional value set on the command line will cause
786 621 # an error.
787 622 env_setting = env.get('NOSE_DOCTEST_EXTENSION')
788 623 if env_setting is not None:
789 624 parser.set_defaults(doctestExtension=tolist(env_setting))
790 625
791 626
792 627 def configure(self, options, config):
793 628 Plugin.configure(self, options, config)
794 629 self.doctest_tests = options.doctest_tests
795 630 self.extension = tolist(options.doctestExtension)
796 631
797 632 self.parser = doctest.DocTestParser()
798 633 self.finder = DocTestFinder()
799 634 self.checker = IPDoctestOutputChecker()
800 635 self.globs = None
801 636 self.extraglobs = None
802 637
803 638
804 639 def loadTestsFromExtensionModule(self,filename):
805 640 bpath,mod = os.path.split(filename)
806 641 modname = os.path.splitext(mod)[0]
807 642 try:
808 643 sys.path.append(bpath)
809 644 module = __import__(modname)
810 645 tests = list(self.loadTestsFromModule(module))
811 646 finally:
812 647 sys.path.pop()
813 648 return tests
814 649
815 650 # NOTE: the method below is almost a copy of the original one in nose, with
816 651 # a few modifications to control output checking.
817 652
818 653 def loadTestsFromModule(self, module):
819 654 #print '*** ipdoctest - lTM',module # dbg
820 655
821 656 if not self.matches(module.__name__):
822 657 log.debug("Doctest doesn't want module %s", module)
823 658 return
824 659
825 660 tests = self.finder.find(module,globs=self.globs,
826 661 extraglobs=self.extraglobs)
827 662 if not tests:
828 663 return
829 664
830 665 # always use whitespace and ellipsis options
831 666 optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
832 667
833 668 tests.sort()
834 669 module_file = module.__file__
835 670 if module_file[-4:] in ('.pyc', '.pyo'):
836 671 module_file = module_file[:-1]
837 672 for test in tests:
838 673 if not test.examples:
839 674 continue
840 675 if not test.filename:
841 676 test.filename = module_file
842 677
843 678 yield DocTestCase(test,
844 679 optionflags=optionflags,
845 680 checker=self.checker)
846 681
847 682
848 683 def loadTestsFromFile(self, filename):
684 #print "ipdoctest - from file", filename # dbg
849 685 if is_extension_module(filename):
850 686 for t in self.loadTestsFromExtensionModule(filename):
851 687 yield t
852 688 else:
853 689 if self.extension and anyp(filename.endswith, self.extension):
854 690 name = os.path.basename(filename)
855 691 dh = open(filename)
856 692 try:
857 693 doc = dh.read()
858 694 finally:
859 695 dh.close()
860 696 test = self.parser.get_doctest(
861 697 doc, globs={'__file__': filename}, name=name,
862 698 filename=filename, lineno=0)
863 699 if test.examples:
864 700 #print 'FileCase:',test.examples # dbg
865 701 yield DocFileCase(test)
866 702 else:
867 703 yield False # no tests to load
868 704
869 705 def wantFile(self,filename):
870 706 """Return whether the given filename should be scanned for tests.
871 707
872 708 Modified version that accepts extension modules as valid containers for
873 709 doctests.
874 710 """
875 # print '*** ipdoctest- wantFile:',filename # dbg
711 #print '*** ipdoctest- wantFile:',filename # dbg
876 712
877 713 for pat in self.exclude_patterns:
878 714 if pat.search(filename):
879 715 # print '###>>> SKIP:',filename # dbg
880 716 return False
881 717
882 718 if is_extension_module(filename):
883 719 return True
884 720 else:
885 721 return doctests.Doctest.wantFile(self,filename)
886 722
887 723
888 724 class IPythonDoctest(ExtensionDoctest):
889 725 """Nose Plugin that supports doctests in extension modules.
890 726 """
891 727 name = 'ipdoctest' # call nosetests with --with-ipdoctest
892 728 enabled = True
893
729
894 730 def makeTest(self, obj, parent):
895 731 """Look for doctests in the given object, which will be a
896 732 function, method or class.
897 733 """
734 #print 'Plugin analyzing:', obj, parent # dbg
898 735 # always use whitespace and ellipsis options
899 736 optionflags = doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS
900 737
901 738 doctests = self.finder.find(obj, module=getmodule(parent))
902 739 if doctests:
903 740 for test in doctests:
904 741 if len(test.examples) == 0:
905 742 continue
906 743
907 744 yield DocTestCase(test, obj=obj,
908 745 optionflags=optionflags,
909 746 checker=self.checker)
910 747
911 748 def options(self, parser, env=os.environ):
749 #print "Options for nose plugin:", self.name # dbg
912 750 Plugin.options(self, parser, env)
913 751 parser.add_option('--ipdoctest-tests', action='store_true',
914 752 dest='ipdoctest_tests',
915 753 default=env.get('NOSE_IPDOCTEST_TESTS',True),
916 754 help="Also look for doctests in test modules. "
917 755 "Note that classes, methods and functions should "
918 756 "have either doctests or non-doctest tests, "
919 757 "not both. [NOSE_IPDOCTEST_TESTS]")
920 758 parser.add_option('--ipdoctest-extension', action="append",
921 759 dest="ipdoctest_extension",
922 760 help="Also look for doctests in files with "
923 761 "this extension [NOSE_IPDOCTEST_EXTENSION]")
924 762 # Set the default as a list, if given in env; otherwise
925 763 # an additional value set on the command line will cause
926 764 # an error.
927 765 env_setting = env.get('NOSE_IPDOCTEST_EXTENSION')
928 766 if env_setting is not None:
929 767 parser.set_defaults(ipdoctest_extension=tolist(env_setting))
930 768
931 769 def configure(self, options, config):
770 #print "Configuring nose plugin:", self.name # dbg
932 771 Plugin.configure(self, options, config)
933 772 self.doctest_tests = options.ipdoctest_tests
934 773 self.extension = tolist(options.ipdoctest_extension)
935 774
936 775 self.parser = IPDocTestParser()
937 776 self.finder = DocTestFinder(parser=self.parser)
938 777 self.checker = IPDoctestOutputChecker()
939 778 self.globs = None
940 779 self.extraglobs = None
@@ -1,132 +1,221 b''
1 1 """Generic testing tools that do NOT depend on Twisted.
2 2
3 3 In particular, this module exposes a set of top-level assert* functions that
4 4 can be used in place of nose.tools.assert* in method generators (the ones in
5 5 nose can not, at least as of nose 0.10.4).
6 6
7 7 Note: our testing package contains testing.util, which does depend on Twisted
8 8 and provides utilities for tests that manage Deferreds. All testing support
9 9 tools that only depend on nose, IPython or the standard library should go here
10 10 instead.
11 11
12 12
13 13 Authors
14 14 -------
15 15 - Fernando Perez <Fernando.Perez@berkeley.edu>
16 16 """
17 17
18 18 #*****************************************************************************
19 19 # Copyright (C) 2009 The IPython Development Team
20 20 #
21 21 # Distributed under the terms of the BSD License. The full license is in
22 22 # the file COPYING, distributed as part of this software.
23 23 #*****************************************************************************
24 24
25 25 #-----------------------------------------------------------------------------
26 26 # Required modules and packages
27 27 #-----------------------------------------------------------------------------
28 28
29 29 import os
30 30 import re
31 31 import sys
32 import tempfile
32 33
33 34 import nose.tools as nt
34 35
35 from IPython.utils import genutils
36 from IPython.utils import genutils, platutils
36 37
37 38 #-----------------------------------------------------------------------------
38 39 # Globals
39 40 #-----------------------------------------------------------------------------
40 41
41 42 # Make a bunch of nose.tools assert wrappers that can be used in test
42 43 # generators. This will expose an assert* function for each one in nose.tools.
43 44
44 45 _tpl = """
45 46 def %(name)s(*a,**kw):
46 47 return nt.%(name)s(*a,**kw)
47 48 """
48 49
49 50 for _x in [a for a in dir(nt) if a.startswith('assert')]:
50 51 exec _tpl % dict(name=_x)
51 52
52 53 #-----------------------------------------------------------------------------
53 54 # Functions and classes
54 55 #-----------------------------------------------------------------------------
55 56
56 57
57 58 def full_path(startPath,files):
58 59 """Make full paths for all the listed files, based on startPath.
59 60
60 61 Only the base part of startPath is kept, since this routine is typically
61 62 used with a script's __file__ variable as startPath. The base of startPath
62 63 is then prepended to all the listed files, forming the output list.
63 64
64 65 Parameters
65 66 ----------
66 67 startPath : string
67 68 Initial path to use as the base for the results. This path is split
68 69 using os.path.split() and only its first component is kept.
69 70
70 71 files : string or list
71 72 One or more files.
72 73
73 74 Examples
74 75 --------
75 76
76 77 >>> full_path('/foo/bar.py',['a.txt','b.txt'])
77 78 ['/foo/a.txt', '/foo/b.txt']
78 79
79 80 >>> full_path('/foo',['a.txt','b.txt'])
80 81 ['/a.txt', '/b.txt']
81 82
82 83 If a single file is given, the output is still a list:
83 84 >>> full_path('/foo','a.txt')
84 85 ['/a.txt']
85 86 """
86 87
87 88 files = genutils.list_strings(files)
88 89 base = os.path.split(startPath)[0]
89 90 return [ os.path.join(base,f) for f in files ]
90 91
91 92
92 93 def parse_test_output(txt):
93 94 """Parse the output of a test run and return errors, failures.
94 95
95 96 Parameters
96 97 ----------
97 98 txt : str
98 99 Text output of a test run, assumed to contain a line of one of the
99 100 following forms::
100 101 'FAILED (errors=1)'
101 102 'FAILED (failures=1)'
102 103 'FAILED (errors=1, failures=1)'
103 104
104 105 Returns
105 106 -------
106 107 nerr, nfail: number of errors and failures.
107 108 """
108 109
109 110 err_m = re.search(r'^FAILED \(errors=(\d+)\)', txt, re.MULTILINE)
110 111 if err_m:
111 112 nerr = int(err_m.group(1))
112 113 nfail = 0
113 114 return nerr, nfail
114 115
115 116 fail_m = re.search(r'^FAILED \(failures=(\d+)\)', txt, re.MULTILINE)
116 117 if fail_m:
117 118 nerr = 0
118 119 nfail = int(fail_m.group(1))
119 120 return nerr, nfail
120 121
121 122 both_m = re.search(r'^FAILED \(errors=(\d+), failures=(\d+)\)', txt,
122 123 re.MULTILINE)
123 124 if both_m:
124 125 nerr = int(both_m.group(1))
125 126 nfail = int(both_m.group(2))
126 127 return nerr, nfail
127 128
128 129 # If the input didn't match any of these forms, assume no error/failures
129 130 return 0, 0
130 131
132
131 133 # So nose doesn't think this is a test
132 134 parse_test_output.__test__ = False
135
136
137 def temp_pyfile(src, ext='.py'):
138 """Make a temporary python file, return filename and filehandle.
139
140 Parameters
141 ----------
142 src : string or list of strings (no need for ending newlines if list)
143 Source code to be written to the file.
144
145 ext : optional, string
146 Extension for the generated file.
147
148 Returns
149 -------
150 (filename, open filehandle)
151 It is the caller's responsibility to close the open file and unlink it.
152 """
153 fname = tempfile.mkstemp(ext)[1]
154 f = open(fname,'w')
155 f.write(src)
156 f.flush()
157 return fname, f
158
159
160 def default_argv():
161 """Return a valid default argv for creating testing instances of ipython"""
162
163 # Get the install directory for the user configuration and tell ipython to
164 # use the default profile from there.
165 from IPython.config import default
166 ipcdir = os.path.dirname(default.__file__)
167 ipconf = os.path.join(ipcdir,'ipython_config.py')
168 #print 'conf:',ipconf # dbg
169 return ['--colors=NoColor', '--no-term-title','--no-banner',
170 '--config-file=%s' % ipconf, '--autocall=0', '--quick']
171
172
173 def ipexec(fname):
174 """Utility to call 'ipython filename'.
175
176 Starts IPython witha minimal and safe configuration to make startup as fast
177 as possible.
178
179 Note that this starts IPython in a subprocess!
180
181 Parameters
182 ----------
183 fname : str
184 Name of file to be executed (should have .py or .ipy extension).
185
186 Returns
187 -------
188 (stdout, stderr) of ipython subprocess.
189 """
190 _ip = get_ipython()
191 test_dir = os.path.dirname(__file__)
192 full_fname = os.path.join(test_dir, fname)
193 ipython_cmd = platutils.find_cmd('ipython')
194 cmdargs = ' '.join(default_argv())
195 return genutils.getoutputerror('%s %s' % (ipython_cmd, full_fname))
196
197
198 def ipexec_validate(fname, expected_out, expected_err=None):
199 """Utility to call 'ipython filename' and validate output/error.
200
201 This function raises an AssertionError if the validation fails.
202
203 Note that this starts IPython in a subprocess!
204
205 Parameters
206 ----------
207 fname : str
208 Name of the file to be executed (should have .py or .ipy extension).
209
210 expected_out : str
211 Expected stdout of the process.
212
213 Returns
214 -------
215 None
216 """
217
218 out, err = ipexec(fname)
219 nt.assert_equals(out.strip(), expected_out.strip())
220 if expected_err:
221 nt.assert_equals(err.strip(), expected_err.strip())
General Comments 0
You need to be logged in to leave comments. Login now