##// END OF EJS Templates
install_extension always returns the path to the installed file.
Thomas Kluyver -
Show More
@@ -1,154 +1,157 b''
1 1 # encoding: utf-8
2 2 """A class for managing IPython extensions.
3 3
4 4 Authors:
5 5
6 6 * Brian Granger
7 7 """
8 8
9 9 #-----------------------------------------------------------------------------
10 10 # Copyright (C) 2010-2011 The IPython Development Team
11 11 #
12 12 # Distributed under the terms of the BSD License. The full license is in
13 13 # the file COPYING, distributed as part of this software.
14 14 #-----------------------------------------------------------------------------
15 15
16 16 #-----------------------------------------------------------------------------
17 17 # Imports
18 18 #-----------------------------------------------------------------------------
19 19
20 20 import os
21 21 from shutil import copyfile
22 22 import sys
23 23 from urllib import urlretrieve
24 24 from urlparse import urlparse
25 25
26 26 from IPython.config.configurable import Configurable
27 27 from IPython.utils.traitlets import Instance
28 28
29 29 #-----------------------------------------------------------------------------
30 30 # Main class
31 31 #-----------------------------------------------------------------------------
32 32
33 33 class ExtensionManager(Configurable):
34 34 """A class to manage IPython extensions.
35 35
36 36 An IPython extension is an importable Python module that has
37 37 a function with the signature::
38 38
39 39 def load_ipython_extension(ipython):
40 40 # Do things with ipython
41 41
42 42 This function is called after your extension is imported and the
43 43 currently active :class:`InteractiveShell` instance is passed as
44 44 the only argument. You can do anything you want with IPython at
45 45 that point, including defining new magic and aliases, adding new
46 46 components, etc.
47 47
48 48 The :func:`load_ipython_extension` will be called again is you
49 49 load or reload the extension again. It is up to the extension
50 50 author to add code to manage that.
51 51
52 52 You can put your extension modules anywhere you want, as long as
53 53 they can be imported by Python's standard import mechanism. However,
54 54 to make it easy to write extensions, you can also put your extensions
55 55 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
56 56 is added to ``sys.path`` automatically.
57 57 """
58 58
59 59 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
60 60
61 61 def __init__(self, shell=None, config=None):
62 62 super(ExtensionManager, self).__init__(shell=shell, config=config)
63 63 self.shell.on_trait_change(
64 64 self._on_ipython_dir_changed, 'ipython_dir'
65 65 )
66 66
67 67 def __del__(self):
68 68 self.shell.on_trait_change(
69 69 self._on_ipython_dir_changed, 'ipython_dir', remove=True
70 70 )
71 71
72 72 @property
73 73 def ipython_extension_dir(self):
74 74 return os.path.join(self.shell.ipython_dir, u'extensions')
75 75
76 76 def _on_ipython_dir_changed(self):
77 77 if not os.path.isdir(self.ipython_extension_dir):
78 78 os.makedirs(self.ipython_extension_dir, mode = 0777)
79 79
80 80 def load_extension(self, module_str):
81 81 """Load an IPython extension by its module name.
82 82
83 83 If :func:`load_ipython_extension` returns anything, this function
84 84 will return that object.
85 85 """
86 86 from IPython.utils.syspathcontext import prepended_to_syspath
87 87
88 88 if module_str not in sys.modules:
89 89 with prepended_to_syspath(self.ipython_extension_dir):
90 90 __import__(module_str)
91 91 mod = sys.modules[module_str]
92 92 return self._call_load_ipython_extension(mod)
93 93
94 94 def unload_extension(self, module_str):
95 95 """Unload an IPython extension by its module name.
96 96
97 97 This function looks up the extension's name in ``sys.modules`` and
98 98 simply calls ``mod.unload_ipython_extension(self)``.
99 99 """
100 100 if module_str in sys.modules:
101 101 mod = sys.modules[module_str]
102 102 self._call_unload_ipython_extension(mod)
103 103
104 104 def reload_extension(self, module_str):
105 105 """Reload an IPython extension by calling reload.
106 106
107 107 If the module has not been loaded before,
108 108 :meth:`InteractiveShell.load_extension` is called. Otherwise
109 109 :func:`reload` is called and then the :func:`load_ipython_extension`
110 110 function of the module, if it exists is called.
111 111 """
112 112 from IPython.utils.syspathcontext import prepended_to_syspath
113 113
114 114 with prepended_to_syspath(self.ipython_extension_dir):
115 115 if module_str in sys.modules:
116 116 mod = sys.modules[module_str]
117 117 reload(mod)
118 118 self._call_load_ipython_extension(mod)
119 119 else:
120 120 self.load_extension(module_str)
121 121
122 122 def _call_load_ipython_extension(self, mod):
123 123 if hasattr(mod, 'load_ipython_extension'):
124 124 return mod.load_ipython_extension(self.shell)
125 125
126 126 def _call_unload_ipython_extension(self, mod):
127 127 if hasattr(mod, 'unload_ipython_extension'):
128 128 return mod.unload_ipython_extension(self.shell)
129 129
130 130 def install_extension(self, url, filename=None):
131 131 """Download and install an IPython extension.
132 132
133 133 If filename is given, the file will be so named (inside the extension
134 134 directory). Otherwise, the name from the URL will be used. The file must
135 135 have a .py or .zip extension; otherwise, a ValueError will be raised.
136
137 Returns the full path to the installed file.
136 138 """
137 139 # Ensure the extension directory exists
138 140 if not os.path.isdir(self.ipython_extension_dir):
139 141 os.makedirs(self.ipython_extension_dir, mode = 0777)
140 142
141 143 if os.path.isfile(url):
142 144 src_filename = os.path.basename(url)
143 145 copy = copyfile
144 146 else:
145 147 src_filename = urlparse(url).path.split('/')[-1]
146 148 copy = urlretrieve
147 149
148 150 if filename is None:
149 151 filename = src_filename
150 152 if os.path.splitext(filename)[1] not in ('.py', '.zip'):
151 153 raise ValueError("The file must have a .py or .zip extension", filename)
152 154
153 155 filename = os.path.join(self.ipython_extension_dir, filename)
154 return copy(url, filename)
156 copy(url, filename)
157 return filename
@@ -1,3798 +1,3798 b''
1 1 # encoding: 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-2007 Fernando Perez <fperez@colorado.edu>
8 8 # Copyright (C) 2008-2011 The IPython Development Team
9 9
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 #-----------------------------------------------------------------------------
15 15 # Imports
16 16 #-----------------------------------------------------------------------------
17 17
18 18 import __builtin__ as builtin_mod
19 19 import __future__
20 20 import bdb
21 21 import inspect
22 22 import imp
23 23 import io
24 24 import os
25 25 import sys
26 26 import shutil
27 27 import re
28 28 import time
29 29 import gc
30 30 from StringIO import StringIO
31 31 from getopt import getopt,GetoptError
32 32 from pprint import pformat
33 33 from xmlrpclib import ServerProxy
34 34
35 35 # cProfile was added in Python2.5
36 36 try:
37 37 import cProfile as profile
38 38 import pstats
39 39 except ImportError:
40 40 # profile isn't bundled by default in Debian for license reasons
41 41 try:
42 42 import profile,pstats
43 43 except ImportError:
44 44 profile = pstats = None
45 45
46 46 import IPython
47 47 from IPython.core import debugger, oinspect
48 48 from IPython.core.error import TryNext
49 49 from IPython.core.error import UsageError
50 50 from IPython.core.error import StdinNotImplementedError
51 51 from IPython.core.fakemodule import FakeModule
52 52 from IPython.core.profiledir import ProfileDir
53 53 from IPython.core.macro import Macro
54 54 from IPython.core import magic_arguments, page
55 55 from IPython.core.prefilter import ESC_MAGIC
56 56 from IPython.core.pylabtools import mpl_runner
57 57 from IPython.testing.skipdoctest import skip_doctest
58 58 from IPython.utils import py3compat
59 59 from IPython.utils import openpy
60 60 from IPython.utils.io import file_read, nlprint
61 61 from IPython.utils.module_paths import find_mod
62 62 from IPython.utils.path import get_py_filename, unquote_filename
63 63 from IPython.utils.process import arg_split, abbrev_cwd
64 64 from IPython.utils.terminal import set_term_title
65 65 from IPython.utils.text import LSString, SList, format_screen
66 66 from IPython.utils.timing import clock, clock2
67 67 from IPython.utils.warn import warn, error
68 68 from IPython.utils.ipstruct import Struct
69 69 from IPython.config.application import Application
70 70
71 71 #-----------------------------------------------------------------------------
72 72 # Utility functions
73 73 #-----------------------------------------------------------------------------
74 74
75 75 def on_off(tag):
76 76 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
77 77 return ['OFF','ON'][tag]
78 78
79 79 class Bunch: pass
80 80
81 81 def compress_dhist(dh):
82 82 head, tail = dh[:-10], dh[-10:]
83 83
84 84 newhead = []
85 85 done = set()
86 86 for h in head:
87 87 if h in done:
88 88 continue
89 89 newhead.append(h)
90 90 done.add(h)
91 91
92 92 return newhead + tail
93 93
94 94 def needs_local_scope(func):
95 95 """Decorator to mark magic functions which need to local scope to run."""
96 96 func.needs_local_scope = True
97 97 return func
98 98
99 99
100 100 # Used for exception handling in magic_edit
101 101 class MacroToEdit(ValueError): pass
102 102
103 103 #***************************************************************************
104 104 # Main class implementing Magic functionality
105 105
106 106 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
107 107 # on construction of the main InteractiveShell object. Something odd is going
108 108 # on with super() calls, Configurable and the MRO... For now leave it as-is, but
109 109 # eventually this needs to be clarified.
110 110 # BG: This is because InteractiveShell inherits from this, but is itself a
111 111 # Configurable. This messes up the MRO in some way. The fix is that we need to
112 112 # make Magic a configurable that InteractiveShell does not subclass.
113 113
114 114 class Magic:
115 115 """Magic functions for InteractiveShell.
116 116
117 117 Shell functions which can be reached as %function_name. All magic
118 118 functions should accept a string, which they can parse for their own
119 119 needs. This can make some functions easier to type, eg `%cd ../`
120 120 vs. `%cd("../")`
121 121
122 122 ALL definitions MUST begin with the prefix magic_. The user won't need it
123 123 at the command line, but it is is needed in the definition. """
124 124
125 125 # class globals
126 126 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
127 127 'Automagic is ON, % prefix NOT needed for magic functions.']
128 128
129 129
130 130 configurables = None
131 131 #......................................................................
132 132 # some utility functions
133 133
134 134 def __init__(self,shell):
135 135
136 136 self.options_table = {}
137 137 if profile is None:
138 138 self.magic_prun = self.profile_missing_notice
139 139 self.shell = shell
140 140 if self.configurables is None:
141 141 self.configurables = []
142 142
143 143 # namespace for holding state we may need
144 144 self._magic_state = Bunch()
145 145
146 146 def profile_missing_notice(self, *args, **kwargs):
147 147 error("""\
148 148 The profile module could not be found. It has been removed from the standard
149 149 python packages because of its non-free license. To use profiling, install the
150 150 python-profiler package from non-free.""")
151 151
152 152 def default_option(self,fn,optstr):
153 153 """Make an entry in the options_table for fn, with value optstr"""
154 154
155 155 if fn not in self.lsmagic():
156 156 error("%s is not a magic function" % fn)
157 157 self.options_table[fn] = optstr
158 158
159 159 def lsmagic(self):
160 160 """Return a list of currently available magic functions.
161 161
162 162 Gives a list of the bare names after mangling (['ls','cd', ...], not
163 163 ['magic_ls','magic_cd',...]"""
164 164
165 165 # FIXME. This needs a cleanup, in the way the magics list is built.
166 166
167 167 # magics in class definition
168 168 class_magic = lambda fn: fn.startswith('magic_') and \
169 169 callable(Magic.__dict__[fn])
170 170 # in instance namespace (run-time user additions)
171 171 inst_magic = lambda fn: fn.startswith('magic_') and \
172 172 callable(self.__dict__[fn])
173 173 # and bound magics by user (so they can access self):
174 174 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
175 175 callable(self.__class__.__dict__[fn])
176 176 magics = filter(class_magic,Magic.__dict__.keys()) + \
177 177 filter(inst_magic,self.__dict__.keys()) + \
178 178 filter(inst_bound_magic,self.__class__.__dict__.keys())
179 179 out = []
180 180 for fn in set(magics):
181 181 out.append(fn.replace('magic_','',1))
182 182 out.sort()
183 183 return out
184 184
185 185 def extract_input_lines(self, range_str, raw=False):
186 186 """Return as a string a set of input history slices.
187 187
188 188 Parameters
189 189 ----------
190 190 range_str : string
191 191 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
192 192 since this function is for use by magic functions which get their
193 193 arguments as strings. The number before the / is the session
194 194 number: ~n goes n back from the current session.
195 195
196 196 Optional Parameters:
197 197 - raw(False): by default, the processed input is used. If this is
198 198 true, the raw input history is used instead.
199 199
200 200 Note that slices can be called with two notations:
201 201
202 202 N:M -> standard python form, means including items N...(M-1).
203 203
204 204 N-M -> include items N..M (closed endpoint)."""
205 205 lines = self.shell.history_manager.\
206 206 get_range_by_str(range_str, raw=raw)
207 207 return "\n".join(x for _, _, x in lines)
208 208
209 209 def arg_err(self,func):
210 210 """Print docstring if incorrect arguments were passed"""
211 211 print 'Error in arguments:'
212 212 print oinspect.getdoc(func)
213 213
214 214 def format_latex(self,strng):
215 215 """Format a string for latex inclusion."""
216 216
217 217 # Characters that need to be escaped for latex:
218 218 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
219 219 # Magic command names as headers:
220 220 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
221 221 re.MULTILINE)
222 222 # Magic commands
223 223 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
224 224 re.MULTILINE)
225 225 # Paragraph continue
226 226 par_re = re.compile(r'\\$',re.MULTILINE)
227 227
228 228 # The "\n" symbol
229 229 newline_re = re.compile(r'\\n')
230 230
231 231 # Now build the string for output:
232 232 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
233 233 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
234 234 strng)
235 235 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
236 236 strng = par_re.sub(r'\\\\',strng)
237 237 strng = escape_re.sub(r'\\\1',strng)
238 238 strng = newline_re.sub(r'\\textbackslash{}n',strng)
239 239 return strng
240 240
241 241 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
242 242 """Parse options passed to an argument string.
243 243
244 244 The interface is similar to that of getopt(), but it returns back a
245 245 Struct with the options as keys and the stripped argument string still
246 246 as a string.
247 247
248 248 arg_str is quoted as a true sys.argv vector by using shlex.split.
249 249 This allows us to easily expand variables, glob files, quote
250 250 arguments, etc.
251 251
252 252 Options:
253 253 -mode: default 'string'. If given as 'list', the argument string is
254 254 returned as a list (split on whitespace) instead of a string.
255 255
256 256 -list_all: put all option values in lists. Normally only options
257 257 appearing more than once are put in a list.
258 258
259 259 -posix (True): whether to split the input line in POSIX mode or not,
260 260 as per the conventions outlined in the shlex module from the
261 261 standard library."""
262 262
263 263 # inject default options at the beginning of the input line
264 264 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
265 265 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
266 266
267 267 mode = kw.get('mode','string')
268 268 if mode not in ['string','list']:
269 269 raise ValueError,'incorrect mode given: %s' % mode
270 270 # Get options
271 271 list_all = kw.get('list_all',0)
272 272 posix = kw.get('posix', os.name == 'posix')
273 273 strict = kw.get('strict', True)
274 274
275 275 # Check if we have more than one argument to warrant extra processing:
276 276 odict = {} # Dictionary with options
277 277 args = arg_str.split()
278 278 if len(args) >= 1:
279 279 # If the list of inputs only has 0 or 1 thing in it, there's no
280 280 # need to look for options
281 281 argv = arg_split(arg_str, posix, strict)
282 282 # Do regular option processing
283 283 try:
284 284 opts,args = getopt(argv,opt_str,*long_opts)
285 285 except GetoptError,e:
286 286 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
287 287 " ".join(long_opts)))
288 288 for o,a in opts:
289 289 if o.startswith('--'):
290 290 o = o[2:]
291 291 else:
292 292 o = o[1:]
293 293 try:
294 294 odict[o].append(a)
295 295 except AttributeError:
296 296 odict[o] = [odict[o],a]
297 297 except KeyError:
298 298 if list_all:
299 299 odict[o] = [a]
300 300 else:
301 301 odict[o] = a
302 302
303 303 # Prepare opts,args for return
304 304 opts = Struct(odict)
305 305 if mode == 'string':
306 306 args = ' '.join(args)
307 307
308 308 return opts,args
309 309
310 310 #......................................................................
311 311 # And now the actual magic functions
312 312
313 313 # Functions for IPython shell work (vars,funcs, config, etc)
314 314 def magic_lsmagic(self, parameter_s = ''):
315 315 """List currently available magic functions."""
316 316 mesc = ESC_MAGIC
317 317 print 'Available magic functions:\n'+mesc+\
318 318 (' '+mesc).join(self.lsmagic())
319 319 print '\n' + Magic.auto_status[self.shell.automagic]
320 320 return None
321 321
322 322 def magic_magic(self, parameter_s = ''):
323 323 """Print information about the magic function system.
324 324
325 325 Supported formats: -latex, -brief, -rest
326 326 """
327 327
328 328 mode = ''
329 329 try:
330 330 if parameter_s.split()[0] == '-latex':
331 331 mode = 'latex'
332 332 if parameter_s.split()[0] == '-brief':
333 333 mode = 'brief'
334 334 if parameter_s.split()[0] == '-rest':
335 335 mode = 'rest'
336 336 rest_docs = []
337 337 except:
338 338 pass
339 339
340 340 magic_docs = []
341 341 for fname in self.lsmagic():
342 342 mname = 'magic_' + fname
343 343 for space in (Magic,self,self.__class__):
344 344 try:
345 345 fn = space.__dict__[mname]
346 346 except KeyError:
347 347 pass
348 348 else:
349 349 break
350 350 if mode == 'brief':
351 351 # only first line
352 352 if fn.__doc__:
353 353 fndoc = fn.__doc__.split('\n',1)[0]
354 354 else:
355 355 fndoc = 'No documentation'
356 356 else:
357 357 if fn.__doc__:
358 358 fndoc = fn.__doc__.rstrip()
359 359 else:
360 360 fndoc = 'No documentation'
361 361
362 362
363 363 if mode == 'rest':
364 364 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
365 365 fname,fndoc))
366 366
367 367 else:
368 368 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
369 369 fname,fndoc))
370 370
371 371 magic_docs = ''.join(magic_docs)
372 372
373 373 if mode == 'rest':
374 374 return "".join(rest_docs)
375 375
376 376 if mode == 'latex':
377 377 print self.format_latex(magic_docs)
378 378 return
379 379 else:
380 380 magic_docs = format_screen(magic_docs)
381 381 if mode == 'brief':
382 382 return magic_docs
383 383
384 384 outmsg = """
385 385 IPython's 'magic' functions
386 386 ===========================
387 387
388 388 The magic function system provides a series of functions which allow you to
389 389 control the behavior of IPython itself, plus a lot of system-type
390 390 features. All these functions are prefixed with a % character, but parameters
391 391 are given without parentheses or quotes.
392 392
393 393 NOTE: If you have 'automagic' enabled (via the command line option or with the
394 394 %automagic function), you don't need to type in the % explicitly. By default,
395 395 IPython ships with automagic on, so you should only rarely need the % escape.
396 396
397 397 Example: typing '%cd mydir' (without the quotes) changes you working directory
398 398 to 'mydir', if it exists.
399 399
400 400 For a list of the available magic functions, use %lsmagic. For a description
401 401 of any of them, type %magic_name?, e.g. '%cd?'.
402 402
403 403 Currently the magic system has the following functions:\n"""
404 404
405 405 mesc = ESC_MAGIC
406 406 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
407 407 "\n\n%s%s\n\n%s" % (outmsg,
408 408 magic_docs,mesc,mesc,
409 409 (' '+mesc).join(self.lsmagic()),
410 410 Magic.auto_status[self.shell.automagic] ) )
411 411 page.page(outmsg)
412 412
413 413 def magic_automagic(self, parameter_s = ''):
414 414 """Make magic functions callable without having to type the initial %.
415 415
416 416 Without argumentsl toggles on/off (when off, you must call it as
417 417 %automagic, of course). With arguments it sets the value, and you can
418 418 use any of (case insensitive):
419 419
420 420 - on,1,True: to activate
421 421
422 422 - off,0,False: to deactivate.
423 423
424 424 Note that magic functions have lowest priority, so if there's a
425 425 variable whose name collides with that of a magic fn, automagic won't
426 426 work for that function (you get the variable instead). However, if you
427 427 delete the variable (del var), the previously shadowed magic function
428 428 becomes visible to automagic again."""
429 429
430 430 arg = parameter_s.lower()
431 431 if parameter_s in ('on','1','true'):
432 432 self.shell.automagic = True
433 433 elif parameter_s in ('off','0','false'):
434 434 self.shell.automagic = False
435 435 else:
436 436 self.shell.automagic = not self.shell.automagic
437 437 print '\n' + Magic.auto_status[self.shell.automagic]
438 438
439 439 @skip_doctest
440 440 def magic_autocall(self, parameter_s = ''):
441 441 """Make functions callable without having to type parentheses.
442 442
443 443 Usage:
444 444
445 445 %autocall [mode]
446 446
447 447 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
448 448 value is toggled on and off (remembering the previous state).
449 449
450 450 In more detail, these values mean:
451 451
452 452 0 -> fully disabled
453 453
454 454 1 -> active, but do not apply if there are no arguments on the line.
455 455
456 456 In this mode, you get::
457 457
458 458 In [1]: callable
459 459 Out[1]: <built-in function callable>
460 460
461 461 In [2]: callable 'hello'
462 462 ------> callable('hello')
463 463 Out[2]: False
464 464
465 465 2 -> Active always. Even if no arguments are present, the callable
466 466 object is called::
467 467
468 468 In [2]: float
469 469 ------> float()
470 470 Out[2]: 0.0
471 471
472 472 Note that even with autocall off, you can still use '/' at the start of
473 473 a line to treat the first argument on the command line as a function
474 474 and add parentheses to it::
475 475
476 476 In [8]: /str 43
477 477 ------> str(43)
478 478 Out[8]: '43'
479 479
480 480 # all-random (note for auto-testing)
481 481 """
482 482
483 483 if parameter_s:
484 484 arg = int(parameter_s)
485 485 else:
486 486 arg = 'toggle'
487 487
488 488 if not arg in (0,1,2,'toggle'):
489 489 error('Valid modes: (0->Off, 1->Smart, 2->Full')
490 490 return
491 491
492 492 if arg in (0,1,2):
493 493 self.shell.autocall = arg
494 494 else: # toggle
495 495 if self.shell.autocall:
496 496 self._magic_state.autocall_save = self.shell.autocall
497 497 self.shell.autocall = 0
498 498 else:
499 499 try:
500 500 self.shell.autocall = self._magic_state.autocall_save
501 501 except AttributeError:
502 502 self.shell.autocall = self._magic_state.autocall_save = 1
503 503
504 504 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
505 505
506 506
507 507 def magic_page(self, parameter_s=''):
508 508 """Pretty print the object and display it through a pager.
509 509
510 510 %page [options] OBJECT
511 511
512 512 If no object is given, use _ (last output).
513 513
514 514 Options:
515 515
516 516 -r: page str(object), don't pretty-print it."""
517 517
518 518 # After a function contributed by Olivier Aubert, slightly modified.
519 519
520 520 # Process options/args
521 521 opts,args = self.parse_options(parameter_s,'r')
522 522 raw = 'r' in opts
523 523
524 524 oname = args and args or '_'
525 525 info = self._ofind(oname)
526 526 if info['found']:
527 527 txt = (raw and str or pformat)( info['obj'] )
528 528 page.page(txt)
529 529 else:
530 530 print 'Object `%s` not found' % oname
531 531
532 532 def magic_profile(self, parameter_s=''):
533 533 """Print your currently active IPython profile."""
534 534 from IPython.core.application import BaseIPythonApplication
535 535 if BaseIPythonApplication.initialized():
536 536 print BaseIPythonApplication.instance().profile
537 537 else:
538 538 error("profile is an application-level value, but you don't appear to be in an IPython application")
539 539
540 540 def magic_pinfo(self, parameter_s='', namespaces=None):
541 541 """Provide detailed information about an object.
542 542
543 543 '%pinfo object' is just a synonym for object? or ?object."""
544 544
545 545 #print 'pinfo par: <%s>' % parameter_s # dbg
546 546
547 547
548 548 # detail_level: 0 -> obj? , 1 -> obj??
549 549 detail_level = 0
550 550 # We need to detect if we got called as 'pinfo pinfo foo', which can
551 551 # happen if the user types 'pinfo foo?' at the cmd line.
552 552 pinfo,qmark1,oname,qmark2 = \
553 553 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
554 554 if pinfo or qmark1 or qmark2:
555 555 detail_level = 1
556 556 if "*" in oname:
557 557 self.magic_psearch(oname)
558 558 else:
559 559 self.shell._inspect('pinfo', oname, detail_level=detail_level,
560 560 namespaces=namespaces)
561 561
562 562 def magic_pinfo2(self, parameter_s='', namespaces=None):
563 563 """Provide extra detailed information about an object.
564 564
565 565 '%pinfo2 object' is just a synonym for object?? or ??object."""
566 566 self.shell._inspect('pinfo', parameter_s, detail_level=1,
567 567 namespaces=namespaces)
568 568
569 569 @skip_doctest
570 570 def magic_pdef(self, parameter_s='', namespaces=None):
571 571 """Print the definition header for any callable object.
572 572
573 573 If the object is a class, print the constructor information.
574 574
575 575 Examples
576 576 --------
577 577 ::
578 578
579 579 In [3]: %pdef urllib.urlopen
580 580 urllib.urlopen(url, data=None, proxies=None)
581 581 """
582 582 self._inspect('pdef',parameter_s, namespaces)
583 583
584 584 def magic_pdoc(self, parameter_s='', namespaces=None):
585 585 """Print the docstring for an object.
586 586
587 587 If the given object is a class, it will print both the class and the
588 588 constructor docstrings."""
589 589 self._inspect('pdoc',parameter_s, namespaces)
590 590
591 591 def magic_psource(self, parameter_s='', namespaces=None):
592 592 """Print (or run through pager) the source code for an object."""
593 593 self._inspect('psource',parameter_s, namespaces)
594 594
595 595 def magic_pfile(self, parameter_s=''):
596 596 """Print (or run through pager) the file where an object is defined.
597 597
598 598 The file opens at the line where the object definition begins. IPython
599 599 will honor the environment variable PAGER if set, and otherwise will
600 600 do its best to print the file in a convenient form.
601 601
602 602 If the given argument is not an object currently defined, IPython will
603 603 try to interpret it as a filename (automatically adding a .py extension
604 604 if needed). You can thus use %pfile as a syntax highlighting code
605 605 viewer."""
606 606
607 607 # first interpret argument as an object name
608 608 out = self._inspect('pfile',parameter_s)
609 609 # if not, try the input as a filename
610 610 if out == 'not found':
611 611 try:
612 612 filename = get_py_filename(parameter_s)
613 613 except IOError,msg:
614 614 print msg
615 615 return
616 616 page.page(self.shell.inspector.format(file(filename).read()))
617 617
618 618 def magic_psearch(self, parameter_s=''):
619 619 """Search for object in namespaces by wildcard.
620 620
621 621 %psearch [options] PATTERN [OBJECT TYPE]
622 622
623 623 Note: ? can be used as a synonym for %psearch, at the beginning or at
624 624 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
625 625 rest of the command line must be unchanged (options come first), so
626 626 for example the following forms are equivalent
627 627
628 628 %psearch -i a* function
629 629 -i a* function?
630 630 ?-i a* function
631 631
632 632 Arguments:
633 633
634 634 PATTERN
635 635
636 636 where PATTERN is a string containing * as a wildcard similar to its
637 637 use in a shell. The pattern is matched in all namespaces on the
638 638 search path. By default objects starting with a single _ are not
639 639 matched, many IPython generated objects have a single
640 640 underscore. The default is case insensitive matching. Matching is
641 641 also done on the attributes of objects and not only on the objects
642 642 in a module.
643 643
644 644 [OBJECT TYPE]
645 645
646 646 Is the name of a python type from the types module. The name is
647 647 given in lowercase without the ending type, ex. StringType is
648 648 written string. By adding a type here only objects matching the
649 649 given type are matched. Using all here makes the pattern match all
650 650 types (this is the default).
651 651
652 652 Options:
653 653
654 654 -a: makes the pattern match even objects whose names start with a
655 655 single underscore. These names are normally omitted from the
656 656 search.
657 657
658 658 -i/-c: make the pattern case insensitive/sensitive. If neither of
659 659 these options are given, the default is read from your configuration
660 660 file, with the option ``InteractiveShell.wildcards_case_sensitive``.
661 661 If this option is not specified in your configuration file, IPython's
662 662 internal default is to do a case sensitive search.
663 663
664 664 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
665 665 specify can be searched in any of the following namespaces:
666 666 'builtin', 'user', 'user_global','internal', 'alias', where
667 667 'builtin' and 'user' are the search defaults. Note that you should
668 668 not use quotes when specifying namespaces.
669 669
670 670 'Builtin' contains the python module builtin, 'user' contains all
671 671 user data, 'alias' only contain the shell aliases and no python
672 672 objects, 'internal' contains objects used by IPython. The
673 673 'user_global' namespace is only used by embedded IPython instances,
674 674 and it contains module-level globals. You can add namespaces to the
675 675 search with -s or exclude them with -e (these options can be given
676 676 more than once).
677 677
678 678 Examples
679 679 --------
680 680 ::
681 681
682 682 %psearch a* -> objects beginning with an a
683 683 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
684 684 %psearch a* function -> all functions beginning with an a
685 685 %psearch re.e* -> objects beginning with an e in module re
686 686 %psearch r*.e* -> objects that start with e in modules starting in r
687 687 %psearch r*.* string -> all strings in modules beginning with r
688 688
689 689 Case sensitive search::
690 690
691 691 %psearch -c a* list all object beginning with lower case a
692 692
693 693 Show objects beginning with a single _::
694 694
695 695 %psearch -a _* list objects beginning with a single underscore"""
696 696 try:
697 697 parameter_s.encode('ascii')
698 698 except UnicodeEncodeError:
699 699 print 'Python identifiers can only contain ascii characters.'
700 700 return
701 701
702 702 # default namespaces to be searched
703 703 def_search = ['user_local', 'user_global', 'builtin']
704 704
705 705 # Process options/args
706 706 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
707 707 opt = opts.get
708 708 shell = self.shell
709 709 psearch = shell.inspector.psearch
710 710
711 711 # select case options
712 712 if opts.has_key('i'):
713 713 ignore_case = True
714 714 elif opts.has_key('c'):
715 715 ignore_case = False
716 716 else:
717 717 ignore_case = not shell.wildcards_case_sensitive
718 718
719 719 # Build list of namespaces to search from user options
720 720 def_search.extend(opt('s',[]))
721 721 ns_exclude = ns_exclude=opt('e',[])
722 722 ns_search = [nm for nm in def_search if nm not in ns_exclude]
723 723
724 724 # Call the actual search
725 725 try:
726 726 psearch(args,shell.ns_table,ns_search,
727 727 show_all=opt('a'),ignore_case=ignore_case)
728 728 except:
729 729 shell.showtraceback()
730 730
731 731 @skip_doctest
732 732 def magic_who_ls(self, parameter_s=''):
733 733 """Return a sorted list of all interactive variables.
734 734
735 735 If arguments are given, only variables of types matching these
736 736 arguments are returned.
737 737
738 738 Examples
739 739 --------
740 740
741 741 Define two variables and list them with who_ls::
742 742
743 743 In [1]: alpha = 123
744 744
745 745 In [2]: beta = 'test'
746 746
747 747 In [3]: %who_ls
748 748 Out[3]: ['alpha', 'beta']
749 749
750 750 In [4]: %who_ls int
751 751 Out[4]: ['alpha']
752 752
753 753 In [5]: %who_ls str
754 754 Out[5]: ['beta']
755 755 """
756 756
757 757 user_ns = self.shell.user_ns
758 758 user_ns_hidden = self.shell.user_ns_hidden
759 759 out = [ i for i in user_ns
760 760 if not i.startswith('_') \
761 761 and not i in user_ns_hidden ]
762 762
763 763 typelist = parameter_s.split()
764 764 if typelist:
765 765 typeset = set(typelist)
766 766 out = [i for i in out if type(user_ns[i]).__name__ in typeset]
767 767
768 768 out.sort()
769 769 return out
770 770
771 771 @skip_doctest
772 772 def magic_who(self, parameter_s=''):
773 773 """Print all interactive variables, with some minimal formatting.
774 774
775 775 If any arguments are given, only variables whose type matches one of
776 776 these are printed. For example::
777 777
778 778 %who function str
779 779
780 780 will only list functions and strings, excluding all other types of
781 781 variables. To find the proper type names, simply use type(var) at a
782 782 command line to see how python prints type names. For example:
783 783
784 784 ::
785 785
786 786 In [1]: type('hello')\\
787 787 Out[1]: <type 'str'>
788 788
789 789 indicates that the type name for strings is 'str'.
790 790
791 791 ``%who`` always excludes executed names loaded through your configuration
792 792 file and things which are internal to IPython.
793 793
794 794 This is deliberate, as typically you may load many modules and the
795 795 purpose of %who is to show you only what you've manually defined.
796 796
797 797 Examples
798 798 --------
799 799
800 800 Define two variables and list them with who::
801 801
802 802 In [1]: alpha = 123
803 803
804 804 In [2]: beta = 'test'
805 805
806 806 In [3]: %who
807 807 alpha beta
808 808
809 809 In [4]: %who int
810 810 alpha
811 811
812 812 In [5]: %who str
813 813 beta
814 814 """
815 815
816 816 varlist = self.magic_who_ls(parameter_s)
817 817 if not varlist:
818 818 if parameter_s:
819 819 print 'No variables match your requested type.'
820 820 else:
821 821 print 'Interactive namespace is empty.'
822 822 return
823 823
824 824 # if we have variables, move on...
825 825 count = 0
826 826 for i in varlist:
827 827 print i+'\t',
828 828 count += 1
829 829 if count > 8:
830 830 count = 0
831 831 print
832 832 print
833 833
834 834 @skip_doctest
835 835 def magic_whos(self, parameter_s=''):
836 836 """Like %who, but gives some extra information about each variable.
837 837
838 838 The same type filtering of %who can be applied here.
839 839
840 840 For all variables, the type is printed. Additionally it prints:
841 841
842 842 - For {},[],(): their length.
843 843
844 844 - For numpy arrays, a summary with shape, number of
845 845 elements, typecode and size in memory.
846 846
847 847 - Everything else: a string representation, snipping their middle if
848 848 too long.
849 849
850 850 Examples
851 851 --------
852 852
853 853 Define two variables and list them with whos::
854 854
855 855 In [1]: alpha = 123
856 856
857 857 In [2]: beta = 'test'
858 858
859 859 In [3]: %whos
860 860 Variable Type Data/Info
861 861 --------------------------------
862 862 alpha int 123
863 863 beta str test
864 864 """
865 865
866 866 varnames = self.magic_who_ls(parameter_s)
867 867 if not varnames:
868 868 if parameter_s:
869 869 print 'No variables match your requested type.'
870 870 else:
871 871 print 'Interactive namespace is empty.'
872 872 return
873 873
874 874 # if we have variables, move on...
875 875
876 876 # for these types, show len() instead of data:
877 877 seq_types = ['dict', 'list', 'tuple']
878 878
879 879 # for numpy arrays, display summary info
880 880 ndarray_type = None
881 881 if 'numpy' in sys.modules:
882 882 try:
883 883 from numpy import ndarray
884 884 except ImportError:
885 885 pass
886 886 else:
887 887 ndarray_type = ndarray.__name__
888 888
889 889 # Find all variable names and types so we can figure out column sizes
890 890 def get_vars(i):
891 891 return self.shell.user_ns[i]
892 892
893 893 # some types are well known and can be shorter
894 894 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
895 895 def type_name(v):
896 896 tn = type(v).__name__
897 897 return abbrevs.get(tn,tn)
898 898
899 899 varlist = map(get_vars,varnames)
900 900
901 901 typelist = []
902 902 for vv in varlist:
903 903 tt = type_name(vv)
904 904
905 905 if tt=='instance':
906 906 typelist.append( abbrevs.get(str(vv.__class__),
907 907 str(vv.__class__)))
908 908 else:
909 909 typelist.append(tt)
910 910
911 911 # column labels and # of spaces as separator
912 912 varlabel = 'Variable'
913 913 typelabel = 'Type'
914 914 datalabel = 'Data/Info'
915 915 colsep = 3
916 916 # variable format strings
917 917 vformat = "{0:<{varwidth}}{1:<{typewidth}}"
918 918 aformat = "%s: %s elems, type `%s`, %s bytes"
919 919 # find the size of the columns to format the output nicely
920 920 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
921 921 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
922 922 # table header
923 923 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
924 924 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
925 925 # and the table itself
926 926 kb = 1024
927 927 Mb = 1048576 # kb**2
928 928 for vname,var,vtype in zip(varnames,varlist,typelist):
929 929 print vformat.format(vname, vtype, varwidth=varwidth, typewidth=typewidth),
930 930 if vtype in seq_types:
931 931 print "n="+str(len(var))
932 932 elif vtype == ndarray_type:
933 933 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
934 934 if vtype==ndarray_type:
935 935 # numpy
936 936 vsize = var.size
937 937 vbytes = vsize*var.itemsize
938 938 vdtype = var.dtype
939 939
940 940 if vbytes < 100000:
941 941 print aformat % (vshape,vsize,vdtype,vbytes)
942 942 else:
943 943 print aformat % (vshape,vsize,vdtype,vbytes),
944 944 if vbytes < Mb:
945 945 print '(%s kb)' % (vbytes/kb,)
946 946 else:
947 947 print '(%s Mb)' % (vbytes/Mb,)
948 948 else:
949 949 try:
950 950 vstr = str(var)
951 951 except UnicodeEncodeError:
952 952 vstr = unicode(var).encode(sys.getdefaultencoding(),
953 953 'backslashreplace')
954 954 vstr = vstr.replace('\n','\\n')
955 955 if len(vstr) < 50:
956 956 print vstr
957 957 else:
958 958 print vstr[:25] + "<...>" + vstr[-25:]
959 959
960 960 def magic_reset(self, parameter_s=''):
961 961 """Resets the namespace by removing all names defined by the user, if
962 962 called without arguments, or by removing some types of objects, such
963 963 as everything currently in IPython's In[] and Out[] containers (see
964 964 the parameters for details).
965 965
966 966 Parameters
967 967 ----------
968 968 -f : force reset without asking for confirmation.
969 969
970 970 -s : 'Soft' reset: Only clears your namespace, leaving history intact.
971 971 References to objects may be kept. By default (without this option),
972 972 we do a 'hard' reset, giving you a new session and removing all
973 973 references to objects from the current session.
974 974
975 975 in : reset input history
976 976
977 977 out : reset output history
978 978
979 979 dhist : reset directory history
980 980
981 981 array : reset only variables that are NumPy arrays
982 982
983 983 See Also
984 984 --------
985 985 magic_reset_selective : invoked as ``%reset_selective``
986 986
987 987 Examples
988 988 --------
989 989 ::
990 990
991 991 In [6]: a = 1
992 992
993 993 In [7]: a
994 994 Out[7]: 1
995 995
996 996 In [8]: 'a' in _ip.user_ns
997 997 Out[8]: True
998 998
999 999 In [9]: %reset -f
1000 1000
1001 1001 In [1]: 'a' in _ip.user_ns
1002 1002 Out[1]: False
1003 1003
1004 1004 In [2]: %reset -f in
1005 1005 Flushing input history
1006 1006
1007 1007 In [3]: %reset -f dhist in
1008 1008 Flushing directory history
1009 1009 Flushing input history
1010 1010
1011 1011 Notes
1012 1012 -----
1013 1013 Calling this magic from clients that do not implement standard input,
1014 1014 such as the ipython notebook interface, will reset the namespace
1015 1015 without confirmation.
1016 1016 """
1017 1017 opts, args = self.parse_options(parameter_s,'sf', mode='list')
1018 1018 if 'f' in opts:
1019 1019 ans = True
1020 1020 else:
1021 1021 try:
1022 1022 ans = self.shell.ask_yes_no(
1023 1023 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ", default='n')
1024 1024 except StdinNotImplementedError:
1025 1025 ans = True
1026 1026 if not ans:
1027 1027 print 'Nothing done.'
1028 1028 return
1029 1029
1030 1030 if 's' in opts: # Soft reset
1031 1031 user_ns = self.shell.user_ns
1032 1032 for i in self.magic_who_ls():
1033 1033 del(user_ns[i])
1034 1034 elif len(args) == 0: # Hard reset
1035 1035 self.shell.reset(new_session = False)
1036 1036
1037 1037 # reset in/out/dhist/array: previously extensinions/clearcmd.py
1038 1038 ip = self.shell
1039 1039 user_ns = self.user_ns # local lookup, heavily used
1040 1040
1041 1041 for target in args:
1042 1042 target = target.lower() # make matches case insensitive
1043 1043 if target == 'out':
1044 1044 print "Flushing output cache (%d entries)" % len(user_ns['_oh'])
1045 1045 self.displayhook.flush()
1046 1046
1047 1047 elif target == 'in':
1048 1048 print "Flushing input history"
1049 1049 pc = self.displayhook.prompt_count + 1
1050 1050 for n in range(1, pc):
1051 1051 key = '_i'+repr(n)
1052 1052 user_ns.pop(key,None)
1053 1053 user_ns.update(dict(_i=u'',_ii=u'',_iii=u''))
1054 1054 hm = ip.history_manager
1055 1055 # don't delete these, as %save and %macro depending on the length
1056 1056 # of these lists to be preserved
1057 1057 hm.input_hist_parsed[:] = [''] * pc
1058 1058 hm.input_hist_raw[:] = [''] * pc
1059 1059 # hm has internal machinery for _i,_ii,_iii, clear it out
1060 1060 hm._i = hm._ii = hm._iii = hm._i00 = u''
1061 1061
1062 1062 elif target == 'array':
1063 1063 # Support cleaning up numpy arrays
1064 1064 try:
1065 1065 from numpy import ndarray
1066 1066 # This must be done with items and not iteritems because we're
1067 1067 # going to modify the dict in-place.
1068 1068 for x,val in user_ns.items():
1069 1069 if isinstance(val,ndarray):
1070 1070 del user_ns[x]
1071 1071 except ImportError:
1072 1072 print "reset array only works if Numpy is available."
1073 1073
1074 1074 elif target == 'dhist':
1075 1075 print "Flushing directory history"
1076 1076 del user_ns['_dh'][:]
1077 1077
1078 1078 else:
1079 1079 print "Don't know how to reset ",
1080 1080 print target + ", please run `%reset?` for details"
1081 1081
1082 1082 gc.collect()
1083 1083
1084 1084 def magic_reset_selective(self, parameter_s=''):
1085 1085 """Resets the namespace by removing names defined by the user.
1086 1086
1087 1087 Input/Output history are left around in case you need them.
1088 1088
1089 1089 %reset_selective [-f] regex
1090 1090
1091 1091 No action is taken if regex is not included
1092 1092
1093 1093 Options
1094 1094 -f : force reset without asking for confirmation.
1095 1095
1096 1096 See Also
1097 1097 --------
1098 1098 magic_reset : invoked as ``%reset``
1099 1099
1100 1100 Examples
1101 1101 --------
1102 1102
1103 1103 We first fully reset the namespace so your output looks identical to
1104 1104 this example for pedagogical reasons; in practice you do not need a
1105 1105 full reset::
1106 1106
1107 1107 In [1]: %reset -f
1108 1108
1109 1109 Now, with a clean namespace we can make a few variables and use
1110 1110 ``%reset_selective`` to only delete names that match our regexp::
1111 1111
1112 1112 In [2]: a=1; b=2; c=3; b1m=4; b2m=5; b3m=6; b4m=7; b2s=8
1113 1113
1114 1114 In [3]: who_ls
1115 1115 Out[3]: ['a', 'b', 'b1m', 'b2m', 'b2s', 'b3m', 'b4m', 'c']
1116 1116
1117 1117 In [4]: %reset_selective -f b[2-3]m
1118 1118
1119 1119 In [5]: who_ls
1120 1120 Out[5]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1121 1121
1122 1122 In [6]: %reset_selective -f d
1123 1123
1124 1124 In [7]: who_ls
1125 1125 Out[7]: ['a', 'b', 'b1m', 'b2s', 'b4m', 'c']
1126 1126
1127 1127 In [8]: %reset_selective -f c
1128 1128
1129 1129 In [9]: who_ls
1130 1130 Out[9]: ['a', 'b', 'b1m', 'b2s', 'b4m']
1131 1131
1132 1132 In [10]: %reset_selective -f b
1133 1133
1134 1134 In [11]: who_ls
1135 1135 Out[11]: ['a']
1136 1136
1137 1137 Notes
1138 1138 -----
1139 1139 Calling this magic from clients that do not implement standard input,
1140 1140 such as the ipython notebook interface, will reset the namespace
1141 1141 without confirmation.
1142 1142 """
1143 1143
1144 1144 opts, regex = self.parse_options(parameter_s,'f')
1145 1145
1146 1146 if opts.has_key('f'):
1147 1147 ans = True
1148 1148 else:
1149 1149 try:
1150 1150 ans = self.shell.ask_yes_no(
1151 1151 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ",
1152 1152 default='n')
1153 1153 except StdinNotImplementedError:
1154 1154 ans = True
1155 1155 if not ans:
1156 1156 print 'Nothing done.'
1157 1157 return
1158 1158 user_ns = self.shell.user_ns
1159 1159 if not regex:
1160 1160 print 'No regex pattern specified. Nothing done.'
1161 1161 return
1162 1162 else:
1163 1163 try:
1164 1164 m = re.compile(regex)
1165 1165 except TypeError:
1166 1166 raise TypeError('regex must be a string or compiled pattern')
1167 1167 for i in self.magic_who_ls():
1168 1168 if m.search(i):
1169 1169 del(user_ns[i])
1170 1170
1171 1171 def magic_xdel(self, parameter_s=''):
1172 1172 """Delete a variable, trying to clear it from anywhere that
1173 1173 IPython's machinery has references to it. By default, this uses
1174 1174 the identity of the named object in the user namespace to remove
1175 1175 references held under other names. The object is also removed
1176 1176 from the output history.
1177 1177
1178 1178 Options
1179 1179 -n : Delete the specified name from all namespaces, without
1180 1180 checking their identity.
1181 1181 """
1182 1182 opts, varname = self.parse_options(parameter_s,'n')
1183 1183 try:
1184 1184 self.shell.del_var(varname, ('n' in opts))
1185 1185 except (NameError, ValueError) as e:
1186 1186 print type(e).__name__ +": "+ str(e)
1187 1187
1188 1188 def magic_logstart(self,parameter_s=''):
1189 1189 """Start logging anywhere in a session.
1190 1190
1191 1191 %logstart [-o|-r|-t] [log_name [log_mode]]
1192 1192
1193 1193 If no name is given, it defaults to a file named 'ipython_log.py' in your
1194 1194 current directory, in 'rotate' mode (see below).
1195 1195
1196 1196 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1197 1197 history up to that point and then continues logging.
1198 1198
1199 1199 %logstart takes a second optional parameter: logging mode. This can be one
1200 1200 of (note that the modes are given unquoted):\\
1201 1201 append: well, that says it.\\
1202 1202 backup: rename (if exists) to name~ and start name.\\
1203 1203 global: single logfile in your home dir, appended to.\\
1204 1204 over : overwrite existing log.\\
1205 1205 rotate: create rotating logs name.1~, name.2~, etc.
1206 1206
1207 1207 Options:
1208 1208
1209 1209 -o: log also IPython's output. In this mode, all commands which
1210 1210 generate an Out[NN] prompt are recorded to the logfile, right after
1211 1211 their corresponding input line. The output lines are always
1212 1212 prepended with a '#[Out]# ' marker, so that the log remains valid
1213 1213 Python code.
1214 1214
1215 1215 Since this marker is always the same, filtering only the output from
1216 1216 a log is very easy, using for example a simple awk call::
1217 1217
1218 1218 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1219 1219
1220 1220 -r: log 'raw' input. Normally, IPython's logs contain the processed
1221 1221 input, so that user lines are logged in their final form, converted
1222 1222 into valid Python. For example, %Exit is logged as
1223 1223 _ip.magic("Exit"). If the -r flag is given, all input is logged
1224 1224 exactly as typed, with no transformations applied.
1225 1225
1226 1226 -t: put timestamps before each input line logged (these are put in
1227 1227 comments)."""
1228 1228
1229 1229 opts,par = self.parse_options(parameter_s,'ort')
1230 1230 log_output = 'o' in opts
1231 1231 log_raw_input = 'r' in opts
1232 1232 timestamp = 't' in opts
1233 1233
1234 1234 logger = self.shell.logger
1235 1235
1236 1236 # if no args are given, the defaults set in the logger constructor by
1237 1237 # ipython remain valid
1238 1238 if par:
1239 1239 try:
1240 1240 logfname,logmode = par.split()
1241 1241 except:
1242 1242 logfname = par
1243 1243 logmode = 'backup'
1244 1244 else:
1245 1245 logfname = logger.logfname
1246 1246 logmode = logger.logmode
1247 1247 # put logfname into rc struct as if it had been called on the command
1248 1248 # line, so it ends up saved in the log header Save it in case we need
1249 1249 # to restore it...
1250 1250 old_logfile = self.shell.logfile
1251 1251 if logfname:
1252 1252 logfname = os.path.expanduser(logfname)
1253 1253 self.shell.logfile = logfname
1254 1254
1255 1255 loghead = '# IPython log file\n\n'
1256 1256 try:
1257 1257 started = logger.logstart(logfname,loghead,logmode,
1258 1258 log_output,timestamp,log_raw_input)
1259 1259 except:
1260 1260 self.shell.logfile = old_logfile
1261 1261 warn("Couldn't start log: %s" % sys.exc_info()[1])
1262 1262 else:
1263 1263 # log input history up to this point, optionally interleaving
1264 1264 # output if requested
1265 1265
1266 1266 if timestamp:
1267 1267 # disable timestamping for the previous history, since we've
1268 1268 # lost those already (no time machine here).
1269 1269 logger.timestamp = False
1270 1270
1271 1271 if log_raw_input:
1272 1272 input_hist = self.shell.history_manager.input_hist_raw
1273 1273 else:
1274 1274 input_hist = self.shell.history_manager.input_hist_parsed
1275 1275
1276 1276 if log_output:
1277 1277 log_write = logger.log_write
1278 1278 output_hist = self.shell.history_manager.output_hist
1279 1279 for n in range(1,len(input_hist)-1):
1280 1280 log_write(input_hist[n].rstrip() + '\n')
1281 1281 if n in output_hist:
1282 1282 log_write(repr(output_hist[n]),'output')
1283 1283 else:
1284 1284 logger.log_write('\n'.join(input_hist[1:]))
1285 1285 logger.log_write('\n')
1286 1286 if timestamp:
1287 1287 # re-enable timestamping
1288 1288 logger.timestamp = True
1289 1289
1290 1290 print ('Activating auto-logging. '
1291 1291 'Current session state plus future input saved.')
1292 1292 logger.logstate()
1293 1293
1294 1294 def magic_logstop(self,parameter_s=''):
1295 1295 """Fully stop logging and close log file.
1296 1296
1297 1297 In order to start logging again, a new %logstart call needs to be made,
1298 1298 possibly (though not necessarily) with a new filename, mode and other
1299 1299 options."""
1300 1300 self.logger.logstop()
1301 1301
1302 1302 def magic_logoff(self,parameter_s=''):
1303 1303 """Temporarily stop logging.
1304 1304
1305 1305 You must have previously started logging."""
1306 1306 self.shell.logger.switch_log(0)
1307 1307
1308 1308 def magic_logon(self,parameter_s=''):
1309 1309 """Restart logging.
1310 1310
1311 1311 This function is for restarting logging which you've temporarily
1312 1312 stopped with %logoff. For starting logging for the first time, you
1313 1313 must use the %logstart function, which allows you to specify an
1314 1314 optional log filename."""
1315 1315
1316 1316 self.shell.logger.switch_log(1)
1317 1317
1318 1318 def magic_logstate(self,parameter_s=''):
1319 1319 """Print the status of the logging system."""
1320 1320
1321 1321 self.shell.logger.logstate()
1322 1322
1323 1323 def magic_pdb(self, parameter_s=''):
1324 1324 """Control the automatic calling of the pdb interactive debugger.
1325 1325
1326 1326 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1327 1327 argument it works as a toggle.
1328 1328
1329 1329 When an exception is triggered, IPython can optionally call the
1330 1330 interactive pdb debugger after the traceback printout. %pdb toggles
1331 1331 this feature on and off.
1332 1332
1333 1333 The initial state of this feature is set in your configuration
1334 1334 file (the option is ``InteractiveShell.pdb``).
1335 1335
1336 1336 If you want to just activate the debugger AFTER an exception has fired,
1337 1337 without having to type '%pdb on' and rerunning your code, you can use
1338 1338 the %debug magic."""
1339 1339
1340 1340 par = parameter_s.strip().lower()
1341 1341
1342 1342 if par:
1343 1343 try:
1344 1344 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1345 1345 except KeyError:
1346 1346 print ('Incorrect argument. Use on/1, off/0, '
1347 1347 'or nothing for a toggle.')
1348 1348 return
1349 1349 else:
1350 1350 # toggle
1351 1351 new_pdb = not self.shell.call_pdb
1352 1352
1353 1353 # set on the shell
1354 1354 self.shell.call_pdb = new_pdb
1355 1355 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1356 1356
1357 1357 def magic_debug(self, parameter_s=''):
1358 1358 """Activate the interactive debugger in post-mortem mode.
1359 1359
1360 1360 If an exception has just occurred, this lets you inspect its stack
1361 1361 frames interactively. Note that this will always work only on the last
1362 1362 traceback that occurred, so you must call this quickly after an
1363 1363 exception that you wish to inspect has fired, because if another one
1364 1364 occurs, it clobbers the previous one.
1365 1365
1366 1366 If you want IPython to automatically do this on every exception, see
1367 1367 the %pdb magic for more details.
1368 1368 """
1369 1369 self.shell.debugger(force=True)
1370 1370
1371 1371 @skip_doctest
1372 1372 def magic_prun(self, parameter_s ='',user_mode=1,
1373 1373 opts=None,arg_lst=None,prog_ns=None):
1374 1374
1375 1375 """Run a statement through the python code profiler.
1376 1376
1377 1377 Usage:
1378 1378 %prun [options] statement
1379 1379
1380 1380 The given statement (which doesn't require quote marks) is run via the
1381 1381 python profiler in a manner similar to the profile.run() function.
1382 1382 Namespaces are internally managed to work correctly; profile.run
1383 1383 cannot be used in IPython because it makes certain assumptions about
1384 1384 namespaces which do not hold under IPython.
1385 1385
1386 1386 Options:
1387 1387
1388 1388 -l <limit>: you can place restrictions on what or how much of the
1389 1389 profile gets printed. The limit value can be:
1390 1390
1391 1391 * A string: only information for function names containing this string
1392 1392 is printed.
1393 1393
1394 1394 * An integer: only these many lines are printed.
1395 1395
1396 1396 * A float (between 0 and 1): this fraction of the report is printed
1397 1397 (for example, use a limit of 0.4 to see the topmost 40% only).
1398 1398
1399 1399 You can combine several limits with repeated use of the option. For
1400 1400 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1401 1401 information about class constructors.
1402 1402
1403 1403 -r: return the pstats.Stats object generated by the profiling. This
1404 1404 object has all the information about the profile in it, and you can
1405 1405 later use it for further analysis or in other functions.
1406 1406
1407 1407 -s <key>: sort profile by given key. You can provide more than one key
1408 1408 by using the option several times: '-s key1 -s key2 -s key3...'. The
1409 1409 default sorting key is 'time'.
1410 1410
1411 1411 The following is copied verbatim from the profile documentation
1412 1412 referenced below:
1413 1413
1414 1414 When more than one key is provided, additional keys are used as
1415 1415 secondary criteria when the there is equality in all keys selected
1416 1416 before them.
1417 1417
1418 1418 Abbreviations can be used for any key names, as long as the
1419 1419 abbreviation is unambiguous. The following are the keys currently
1420 1420 defined:
1421 1421
1422 1422 Valid Arg Meaning
1423 1423 "calls" call count
1424 1424 "cumulative" cumulative time
1425 1425 "file" file name
1426 1426 "module" file name
1427 1427 "pcalls" primitive call count
1428 1428 "line" line number
1429 1429 "name" function name
1430 1430 "nfl" name/file/line
1431 1431 "stdname" standard name
1432 1432 "time" internal time
1433 1433
1434 1434 Note that all sorts on statistics are in descending order (placing
1435 1435 most time consuming items first), where as name, file, and line number
1436 1436 searches are in ascending order (i.e., alphabetical). The subtle
1437 1437 distinction between "nfl" and "stdname" is that the standard name is a
1438 1438 sort of the name as printed, which means that the embedded line
1439 1439 numbers get compared in an odd way. For example, lines 3, 20, and 40
1440 1440 would (if the file names were the same) appear in the string order
1441 1441 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1442 1442 line numbers. In fact, sort_stats("nfl") is the same as
1443 1443 sort_stats("name", "file", "line").
1444 1444
1445 1445 -T <filename>: save profile results as shown on screen to a text
1446 1446 file. The profile is still shown on screen.
1447 1447
1448 1448 -D <filename>: save (via dump_stats) profile statistics to given
1449 1449 filename. This data is in a format understood by the pstats module, and
1450 1450 is generated by a call to the dump_stats() method of profile
1451 1451 objects. The profile is still shown on screen.
1452 1452
1453 1453 -q: suppress output to the pager. Best used with -T and/or -D above.
1454 1454
1455 1455 If you want to run complete programs under the profiler's control, use
1456 1456 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1457 1457 contains profiler specific options as described here.
1458 1458
1459 1459 You can read the complete documentation for the profile module with::
1460 1460
1461 1461 In [1]: import profile; profile.help()
1462 1462 """
1463 1463
1464 1464 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1465 1465
1466 1466 if user_mode: # regular user call
1467 1467 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
1468 1468 list_all=1, posix=False)
1469 1469 namespace = self.shell.user_ns
1470 1470 else: # called to run a program by %run -p
1471 1471 try:
1472 1472 filename = get_py_filename(arg_lst[0])
1473 1473 except IOError as e:
1474 1474 try:
1475 1475 msg = str(e)
1476 1476 except UnicodeError:
1477 1477 msg = e.message
1478 1478 error(msg)
1479 1479 return
1480 1480
1481 1481 arg_str = 'execfile(filename,prog_ns)'
1482 1482 namespace = {
1483 1483 'execfile': self.shell.safe_execfile,
1484 1484 'prog_ns': prog_ns,
1485 1485 'filename': filename
1486 1486 }
1487 1487
1488 1488 opts.merge(opts_def)
1489 1489
1490 1490 prof = profile.Profile()
1491 1491 try:
1492 1492 prof = prof.runctx(arg_str,namespace,namespace)
1493 1493 sys_exit = ''
1494 1494 except SystemExit:
1495 1495 sys_exit = """*** SystemExit exception caught in code being profiled."""
1496 1496
1497 1497 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1498 1498
1499 1499 lims = opts.l
1500 1500 if lims:
1501 1501 lims = [] # rebuild lims with ints/floats/strings
1502 1502 for lim in opts.l:
1503 1503 try:
1504 1504 lims.append(int(lim))
1505 1505 except ValueError:
1506 1506 try:
1507 1507 lims.append(float(lim))
1508 1508 except ValueError:
1509 1509 lims.append(lim)
1510 1510
1511 1511 # Trap output.
1512 1512 stdout_trap = StringIO()
1513 1513
1514 1514 if hasattr(stats,'stream'):
1515 1515 # In newer versions of python, the stats object has a 'stream'
1516 1516 # attribute to write into.
1517 1517 stats.stream = stdout_trap
1518 1518 stats.print_stats(*lims)
1519 1519 else:
1520 1520 # For older versions, we manually redirect stdout during printing
1521 1521 sys_stdout = sys.stdout
1522 1522 try:
1523 1523 sys.stdout = stdout_trap
1524 1524 stats.print_stats(*lims)
1525 1525 finally:
1526 1526 sys.stdout = sys_stdout
1527 1527
1528 1528 output = stdout_trap.getvalue()
1529 1529 output = output.rstrip()
1530 1530
1531 1531 if 'q' not in opts:
1532 1532 page.page(output)
1533 1533 print sys_exit,
1534 1534
1535 1535 dump_file = opts.D[0]
1536 1536 text_file = opts.T[0]
1537 1537 if dump_file:
1538 1538 dump_file = unquote_filename(dump_file)
1539 1539 prof.dump_stats(dump_file)
1540 1540 print '\n*** Profile stats marshalled to file',\
1541 1541 `dump_file`+'.',sys_exit
1542 1542 if text_file:
1543 1543 text_file = unquote_filename(text_file)
1544 1544 pfile = file(text_file,'w')
1545 1545 pfile.write(output)
1546 1546 pfile.close()
1547 1547 print '\n*** Profile printout saved to text file',\
1548 1548 `text_file`+'.',sys_exit
1549 1549
1550 1550 if opts.has_key('r'):
1551 1551 return stats
1552 1552 else:
1553 1553 return None
1554 1554
1555 1555 @skip_doctest
1556 1556 def magic_run(self, parameter_s ='', runner=None,
1557 1557 file_finder=get_py_filename):
1558 1558 """Run the named file inside IPython as a program.
1559 1559
1560 1560 Usage:\\
1561 1561 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1562 1562
1563 1563 Parameters after the filename are passed as command-line arguments to
1564 1564 the program (put in sys.argv). Then, control returns to IPython's
1565 1565 prompt.
1566 1566
1567 1567 This is similar to running at a system prompt:\\
1568 1568 $ python file args\\
1569 1569 but with the advantage of giving you IPython's tracebacks, and of
1570 1570 loading all variables into your interactive namespace for further use
1571 1571 (unless -p is used, see below).
1572 1572
1573 1573 The file is executed in a namespace initially consisting only of
1574 1574 __name__=='__main__' and sys.argv constructed as indicated. It thus
1575 1575 sees its environment as if it were being run as a stand-alone program
1576 1576 (except for sharing global objects such as previously imported
1577 1577 modules). But after execution, the IPython interactive namespace gets
1578 1578 updated with all variables defined in the program (except for __name__
1579 1579 and sys.argv). This allows for very convenient loading of code for
1580 1580 interactive work, while giving each program a 'clean sheet' to run in.
1581 1581
1582 1582 Options:
1583 1583
1584 1584 -n: __name__ is NOT set to '__main__', but to the running file's name
1585 1585 without extension (as python does under import). This allows running
1586 1586 scripts and reloading the definitions in them without calling code
1587 1587 protected by an ' if __name__ == "__main__" ' clause.
1588 1588
1589 1589 -i: run the file in IPython's namespace instead of an empty one. This
1590 1590 is useful if you are experimenting with code written in a text editor
1591 1591 which depends on variables defined interactively.
1592 1592
1593 1593 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1594 1594 being run. This is particularly useful if IPython is being used to
1595 1595 run unittests, which always exit with a sys.exit() call. In such
1596 1596 cases you are interested in the output of the test results, not in
1597 1597 seeing a traceback of the unittest module.
1598 1598
1599 1599 -t: print timing information at the end of the run. IPython will give
1600 1600 you an estimated CPU time consumption for your script, which under
1601 1601 Unix uses the resource module to avoid the wraparound problems of
1602 1602 time.clock(). Under Unix, an estimate of time spent on system tasks
1603 1603 is also given (for Windows platforms this is reported as 0.0).
1604 1604
1605 1605 If -t is given, an additional -N<N> option can be given, where <N>
1606 1606 must be an integer indicating how many times you want the script to
1607 1607 run. The final timing report will include total and per run results.
1608 1608
1609 1609 For example (testing the script uniq_stable.py)::
1610 1610
1611 1611 In [1]: run -t uniq_stable
1612 1612
1613 1613 IPython CPU timings (estimated):\\
1614 1614 User : 0.19597 s.\\
1615 1615 System: 0.0 s.\\
1616 1616
1617 1617 In [2]: run -t -N5 uniq_stable
1618 1618
1619 1619 IPython CPU timings (estimated):\\
1620 1620 Total runs performed: 5\\
1621 1621 Times : Total Per run\\
1622 1622 User : 0.910862 s, 0.1821724 s.\\
1623 1623 System: 0.0 s, 0.0 s.
1624 1624
1625 1625 -d: run your program under the control of pdb, the Python debugger.
1626 1626 This allows you to execute your program step by step, watch variables,
1627 1627 etc. Internally, what IPython does is similar to calling:
1628 1628
1629 1629 pdb.run('execfile("YOURFILENAME")')
1630 1630
1631 1631 with a breakpoint set on line 1 of your file. You can change the line
1632 1632 number for this automatic breakpoint to be <N> by using the -bN option
1633 1633 (where N must be an integer). For example::
1634 1634
1635 1635 %run -d -b40 myscript
1636 1636
1637 1637 will set the first breakpoint at line 40 in myscript.py. Note that
1638 1638 the first breakpoint must be set on a line which actually does
1639 1639 something (not a comment or docstring) for it to stop execution.
1640 1640
1641 1641 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1642 1642 first enter 'c' (without quotes) to start execution up to the first
1643 1643 breakpoint.
1644 1644
1645 1645 Entering 'help' gives information about the use of the debugger. You
1646 1646 can easily see pdb's full documentation with "import pdb;pdb.help()"
1647 1647 at a prompt.
1648 1648
1649 1649 -p: run program under the control of the Python profiler module (which
1650 1650 prints a detailed report of execution times, function calls, etc).
1651 1651
1652 1652 You can pass other options after -p which affect the behavior of the
1653 1653 profiler itself. See the docs for %prun for details.
1654 1654
1655 1655 In this mode, the program's variables do NOT propagate back to the
1656 1656 IPython interactive namespace (because they remain in the namespace
1657 1657 where the profiler executes them).
1658 1658
1659 1659 Internally this triggers a call to %prun, see its documentation for
1660 1660 details on the options available specifically for profiling.
1661 1661
1662 1662 There is one special usage for which the text above doesn't apply:
1663 1663 if the filename ends with .ipy, the file is run as ipython script,
1664 1664 just as if the commands were written on IPython prompt.
1665 1665
1666 1666 -m: specify module name to load instead of script path. Similar to
1667 1667 the -m option for the python interpreter. Use this option last if you
1668 1668 want to combine with other %run options. Unlike the python interpreter
1669 1669 only source modules are allowed no .pyc or .pyo files.
1670 1670 For example::
1671 1671
1672 1672 %run -m example
1673 1673
1674 1674 will run the example module.
1675 1675
1676 1676 """
1677 1677
1678 1678 # get arguments and set sys.argv for program to be run.
1679 1679 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
1680 1680 mode='list', list_all=1)
1681 1681 if "m" in opts:
1682 1682 modulename = opts["m"][0]
1683 1683 modpath = find_mod(modulename)
1684 1684 if modpath is None:
1685 1685 warn('%r is not a valid modulename on sys.path'%modulename)
1686 1686 return
1687 1687 arg_lst = [modpath] + arg_lst
1688 1688 try:
1689 1689 filename = file_finder(arg_lst[0])
1690 1690 except IndexError:
1691 1691 warn('you must provide at least a filename.')
1692 1692 print '\n%run:\n', oinspect.getdoc(self.magic_run)
1693 1693 return
1694 1694 except IOError as e:
1695 1695 try:
1696 1696 msg = str(e)
1697 1697 except UnicodeError:
1698 1698 msg = e.message
1699 1699 error(msg)
1700 1700 return
1701 1701
1702 1702 if filename.lower().endswith('.ipy'):
1703 1703 self.shell.safe_execfile_ipy(filename)
1704 1704 return
1705 1705
1706 1706 # Control the response to exit() calls made by the script being run
1707 1707 exit_ignore = 'e' in opts
1708 1708
1709 1709 # Make sure that the running script gets a proper sys.argv as if it
1710 1710 # were run from a system shell.
1711 1711 save_argv = sys.argv # save it for later restoring
1712 1712
1713 1713 # simulate shell expansion on arguments, at least tilde expansion
1714 1714 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
1715 1715
1716 1716 sys.argv = [filename] + args # put in the proper filename
1717 1717 # protect sys.argv from potential unicode strings on Python 2:
1718 1718 if not py3compat.PY3:
1719 1719 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
1720 1720
1721 1721 if 'i' in opts:
1722 1722 # Run in user's interactive namespace
1723 1723 prog_ns = self.shell.user_ns
1724 1724 __name__save = self.shell.user_ns['__name__']
1725 1725 prog_ns['__name__'] = '__main__'
1726 1726 main_mod = self.shell.new_main_mod(prog_ns)
1727 1727 else:
1728 1728 # Run in a fresh, empty namespace
1729 1729 if 'n' in opts:
1730 1730 name = os.path.splitext(os.path.basename(filename))[0]
1731 1731 else:
1732 1732 name = '__main__'
1733 1733
1734 1734 main_mod = self.shell.new_main_mod()
1735 1735 prog_ns = main_mod.__dict__
1736 1736 prog_ns['__name__'] = name
1737 1737
1738 1738 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1739 1739 # set the __file__ global in the script's namespace
1740 1740 prog_ns['__file__'] = filename
1741 1741
1742 1742 # pickle fix. See interactiveshell for an explanation. But we need to make sure
1743 1743 # that, if we overwrite __main__, we replace it at the end
1744 1744 main_mod_name = prog_ns['__name__']
1745 1745
1746 1746 if main_mod_name == '__main__':
1747 1747 restore_main = sys.modules['__main__']
1748 1748 else:
1749 1749 restore_main = False
1750 1750
1751 1751 # This needs to be undone at the end to prevent holding references to
1752 1752 # every single object ever created.
1753 1753 sys.modules[main_mod_name] = main_mod
1754 1754
1755 1755 try:
1756 1756 stats = None
1757 1757 with self.readline_no_record:
1758 1758 if 'p' in opts:
1759 1759 stats = self.magic_prun('', 0, opts, arg_lst, prog_ns)
1760 1760 else:
1761 1761 if 'd' in opts:
1762 1762 deb = debugger.Pdb(self.shell.colors)
1763 1763 # reset Breakpoint state, which is moronically kept
1764 1764 # in a class
1765 1765 bdb.Breakpoint.next = 1
1766 1766 bdb.Breakpoint.bplist = {}
1767 1767 bdb.Breakpoint.bpbynumber = [None]
1768 1768 # Set an initial breakpoint to stop execution
1769 1769 maxtries = 10
1770 1770 bp = int(opts.get('b', [1])[0])
1771 1771 checkline = deb.checkline(filename, bp)
1772 1772 if not checkline:
1773 1773 for bp in range(bp + 1, bp + maxtries + 1):
1774 1774 if deb.checkline(filename, bp):
1775 1775 break
1776 1776 else:
1777 1777 msg = ("\nI failed to find a valid line to set "
1778 1778 "a breakpoint\n"
1779 1779 "after trying up to line: %s.\n"
1780 1780 "Please set a valid breakpoint manually "
1781 1781 "with the -b option." % bp)
1782 1782 error(msg)
1783 1783 return
1784 1784 # if we find a good linenumber, set the breakpoint
1785 1785 deb.do_break('%s:%s' % (filename, bp))
1786 1786 # Start file run
1787 1787 print "NOTE: Enter 'c' at the",
1788 1788 print "%s prompt to start your script." % deb.prompt
1789 1789 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
1790 1790 try:
1791 1791 deb.run('execfile("%s", prog_ns)' % filename, ns)
1792 1792
1793 1793 except:
1794 1794 etype, value, tb = sys.exc_info()
1795 1795 # Skip three frames in the traceback: the %run one,
1796 1796 # one inside bdb.py, and the command-line typed by the
1797 1797 # user (run by exec in pdb itself).
1798 1798 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
1799 1799 else:
1800 1800 if runner is None:
1801 1801 runner = self.shell.safe_execfile
1802 1802 if 't' in opts:
1803 1803 # timed execution
1804 1804 try:
1805 1805 nruns = int(opts['N'][0])
1806 1806 if nruns < 1:
1807 1807 error('Number of runs must be >=1')
1808 1808 return
1809 1809 except (KeyError):
1810 1810 nruns = 1
1811 1811 twall0 = time.time()
1812 1812 if nruns == 1:
1813 1813 t0 = clock2()
1814 1814 runner(filename, prog_ns, prog_ns,
1815 1815 exit_ignore=exit_ignore)
1816 1816 t1 = clock2()
1817 1817 t_usr = t1[0] - t0[0]
1818 1818 t_sys = t1[1] - t0[1]
1819 1819 print "\nIPython CPU timings (estimated):"
1820 1820 print " User : %10.2f s." % t_usr
1821 1821 print " System : %10.2f s." % t_sys
1822 1822 else:
1823 1823 runs = range(nruns)
1824 1824 t0 = clock2()
1825 1825 for nr in runs:
1826 1826 runner(filename, prog_ns, prog_ns,
1827 1827 exit_ignore=exit_ignore)
1828 1828 t1 = clock2()
1829 1829 t_usr = t1[0] - t0[0]
1830 1830 t_sys = t1[1] - t0[1]
1831 1831 print "\nIPython CPU timings (estimated):"
1832 1832 print "Total runs performed:", nruns
1833 1833 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
1834 1834 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
1835 1835 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
1836 1836 twall1 = time.time()
1837 1837 print "Wall time: %10.2f s." % (twall1 - twall0)
1838 1838
1839 1839 else:
1840 1840 # regular execution
1841 1841 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
1842 1842
1843 1843 if 'i' in opts:
1844 1844 self.shell.user_ns['__name__'] = __name__save
1845 1845 else:
1846 1846 # The shell MUST hold a reference to prog_ns so after %run
1847 1847 # exits, the python deletion mechanism doesn't zero it out
1848 1848 # (leaving dangling references).
1849 1849 self.shell.cache_main_mod(prog_ns, filename)
1850 1850 # update IPython interactive namespace
1851 1851
1852 1852 # Some forms of read errors on the file may mean the
1853 1853 # __name__ key was never set; using pop we don't have to
1854 1854 # worry about a possible KeyError.
1855 1855 prog_ns.pop('__name__', None)
1856 1856
1857 1857 self.shell.user_ns.update(prog_ns)
1858 1858 finally:
1859 1859 # It's a bit of a mystery why, but __builtins__ can change from
1860 1860 # being a module to becoming a dict missing some key data after
1861 1861 # %run. As best I can see, this is NOT something IPython is doing
1862 1862 # at all, and similar problems have been reported before:
1863 1863 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1864 1864 # Since this seems to be done by the interpreter itself, the best
1865 1865 # we can do is to at least restore __builtins__ for the user on
1866 1866 # exit.
1867 1867 self.shell.user_ns['__builtins__'] = builtin_mod
1868 1868
1869 1869 # Ensure key global structures are restored
1870 1870 sys.argv = save_argv
1871 1871 if restore_main:
1872 1872 sys.modules['__main__'] = restore_main
1873 1873 else:
1874 1874 # Remove from sys.modules the reference to main_mod we'd
1875 1875 # added. Otherwise it will trap references to objects
1876 1876 # contained therein.
1877 1877 del sys.modules[main_mod_name]
1878 1878
1879 1879 return stats
1880 1880
1881 1881 @skip_doctest
1882 1882 def magic_timeit(self, parameter_s =''):
1883 1883 """Time execution of a Python statement or expression
1884 1884
1885 1885 Usage:\\
1886 1886 %timeit [-n<N> -r<R> [-t|-c]] statement
1887 1887
1888 1888 Time execution of a Python statement or expression using the timeit
1889 1889 module.
1890 1890
1891 1891 Options:
1892 1892 -n<N>: execute the given statement <N> times in a loop. If this value
1893 1893 is not given, a fitting value is chosen.
1894 1894
1895 1895 -r<R>: repeat the loop iteration <R> times and take the best result.
1896 1896 Default: 3
1897 1897
1898 1898 -t: use time.time to measure the time, which is the default on Unix.
1899 1899 This function measures wall time.
1900 1900
1901 1901 -c: use time.clock to measure the time, which is the default on
1902 1902 Windows and measures wall time. On Unix, resource.getrusage is used
1903 1903 instead and returns the CPU user time.
1904 1904
1905 1905 -p<P>: use a precision of <P> digits to display the timing result.
1906 1906 Default: 3
1907 1907
1908 1908
1909 1909 Examples
1910 1910 --------
1911 1911 ::
1912 1912
1913 1913 In [1]: %timeit pass
1914 1914 10000000 loops, best of 3: 53.3 ns per loop
1915 1915
1916 1916 In [2]: u = None
1917 1917
1918 1918 In [3]: %timeit u is None
1919 1919 10000000 loops, best of 3: 184 ns per loop
1920 1920
1921 1921 In [4]: %timeit -r 4 u == None
1922 1922 1000000 loops, best of 4: 242 ns per loop
1923 1923
1924 1924 In [5]: import time
1925 1925
1926 1926 In [6]: %timeit -n1 time.sleep(2)
1927 1927 1 loops, best of 3: 2 s per loop
1928 1928
1929 1929
1930 1930 The times reported by %timeit will be slightly higher than those
1931 1931 reported by the timeit.py script when variables are accessed. This is
1932 1932 due to the fact that %timeit executes the statement in the namespace
1933 1933 of the shell, compared with timeit.py, which uses a single setup
1934 1934 statement to import function or create variables. Generally, the bias
1935 1935 does not matter as long as results from timeit.py are not mixed with
1936 1936 those from %timeit."""
1937 1937
1938 1938 import timeit
1939 1939 import math
1940 1940
1941 1941 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1942 1942 # certain terminals. Until we figure out a robust way of
1943 1943 # auto-detecting if the terminal can deal with it, use plain 'us' for
1944 1944 # microseconds. I am really NOT happy about disabling the proper
1945 1945 # 'micro' prefix, but crashing is worse... If anyone knows what the
1946 1946 # right solution for this is, I'm all ears...
1947 1947 #
1948 1948 # Note: using
1949 1949 #
1950 1950 # s = u'\xb5'
1951 1951 # s.encode(sys.getdefaultencoding())
1952 1952 #
1953 1953 # is not sufficient, as I've seen terminals where that fails but
1954 1954 # print s
1955 1955 #
1956 1956 # succeeds
1957 1957 #
1958 1958 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1959 1959
1960 1960 #units = [u"s", u"ms",u'\xb5',"ns"]
1961 1961 units = [u"s", u"ms",u'us',"ns"]
1962 1962
1963 1963 scaling = [1, 1e3, 1e6, 1e9]
1964 1964
1965 1965 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1966 1966 posix=False, strict=False)
1967 1967 if stmt == "":
1968 1968 return
1969 1969 timefunc = timeit.default_timer
1970 1970 number = int(getattr(opts, "n", 0))
1971 1971 repeat = int(getattr(opts, "r", timeit.default_repeat))
1972 1972 precision = int(getattr(opts, "p", 3))
1973 1973 if hasattr(opts, "t"):
1974 1974 timefunc = time.time
1975 1975 if hasattr(opts, "c"):
1976 1976 timefunc = clock
1977 1977
1978 1978 timer = timeit.Timer(timer=timefunc)
1979 1979 # this code has tight coupling to the inner workings of timeit.Timer,
1980 1980 # but is there a better way to achieve that the code stmt has access
1981 1981 # to the shell namespace?
1982 1982
1983 1983 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1984 1984 'setup': "pass"}
1985 1985 # Track compilation time so it can be reported if too long
1986 1986 # Minimum time above which compilation time will be reported
1987 1987 tc_min = 0.1
1988 1988
1989 1989 t0 = clock()
1990 1990 code = compile(src, "<magic-timeit>", "exec")
1991 1991 tc = clock()-t0
1992 1992
1993 1993 ns = {}
1994 1994 exec code in self.shell.user_ns, ns
1995 1995 timer.inner = ns["inner"]
1996 1996
1997 1997 if number == 0:
1998 1998 # determine number so that 0.2 <= total time < 2.0
1999 1999 number = 1
2000 2000 for i in range(1, 10):
2001 2001 if timer.timeit(number) >= 0.2:
2002 2002 break
2003 2003 number *= 10
2004 2004
2005 2005 best = min(timer.repeat(repeat, number)) / number
2006 2006
2007 2007 if best > 0.0 and best < 1000.0:
2008 2008 order = min(-int(math.floor(math.log10(best)) // 3), 3)
2009 2009 elif best >= 1000.0:
2010 2010 order = 0
2011 2011 else:
2012 2012 order = 3
2013 2013 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
2014 2014 precision,
2015 2015 best * scaling[order],
2016 2016 units[order])
2017 2017 if tc > tc_min:
2018 2018 print "Compiler time: %.2f s" % tc
2019 2019
2020 2020 @skip_doctest
2021 2021 @needs_local_scope
2022 2022 def magic_time(self,parameter_s = ''):
2023 2023 """Time execution of a Python statement or expression.
2024 2024
2025 2025 The CPU and wall clock times are printed, and the value of the
2026 2026 expression (if any) is returned. Note that under Win32, system time
2027 2027 is always reported as 0, since it can not be measured.
2028 2028
2029 2029 This function provides very basic timing functionality. In Python
2030 2030 2.3, the timeit module offers more control and sophistication, so this
2031 2031 could be rewritten to use it (patches welcome).
2032 2032
2033 2033 Examples
2034 2034 --------
2035 2035 ::
2036 2036
2037 2037 In [1]: time 2**128
2038 2038 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2039 2039 Wall time: 0.00
2040 2040 Out[1]: 340282366920938463463374607431768211456L
2041 2041
2042 2042 In [2]: n = 1000000
2043 2043
2044 2044 In [3]: time sum(range(n))
2045 2045 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2046 2046 Wall time: 1.37
2047 2047 Out[3]: 499999500000L
2048 2048
2049 2049 In [4]: time print 'hello world'
2050 2050 hello world
2051 2051 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2052 2052 Wall time: 0.00
2053 2053
2054 2054 Note that the time needed by Python to compile the given expression
2055 2055 will be reported if it is more than 0.1s. In this example, the
2056 2056 actual exponentiation is done by Python at compilation time, so while
2057 2057 the expression can take a noticeable amount of time to compute, that
2058 2058 time is purely due to the compilation:
2059 2059
2060 2060 In [5]: time 3**9999;
2061 2061 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2062 2062 Wall time: 0.00 s
2063 2063
2064 2064 In [6]: time 3**999999;
2065 2065 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2066 2066 Wall time: 0.00 s
2067 2067 Compiler : 0.78 s
2068 2068 """
2069 2069
2070 2070 # fail immediately if the given expression can't be compiled
2071 2071
2072 2072 expr = self.shell.prefilter(parameter_s,False)
2073 2073
2074 2074 # Minimum time above which compilation time will be reported
2075 2075 tc_min = 0.1
2076 2076
2077 2077 try:
2078 2078 mode = 'eval'
2079 2079 t0 = clock()
2080 2080 code = compile(expr,'<timed eval>',mode)
2081 2081 tc = clock()-t0
2082 2082 except SyntaxError:
2083 2083 mode = 'exec'
2084 2084 t0 = clock()
2085 2085 code = compile(expr,'<timed exec>',mode)
2086 2086 tc = clock()-t0
2087 2087 # skew measurement as little as possible
2088 2088 glob = self.shell.user_ns
2089 2089 locs = self._magic_locals
2090 2090 clk = clock2
2091 2091 wtime = time.time
2092 2092 # time execution
2093 2093 wall_st = wtime()
2094 2094 if mode=='eval':
2095 2095 st = clk()
2096 2096 out = eval(code, glob, locs)
2097 2097 end = clk()
2098 2098 else:
2099 2099 st = clk()
2100 2100 exec code in glob, locs
2101 2101 end = clk()
2102 2102 out = None
2103 2103 wall_end = wtime()
2104 2104 # Compute actual times and report
2105 2105 wall_time = wall_end-wall_st
2106 2106 cpu_user = end[0]-st[0]
2107 2107 cpu_sys = end[1]-st[1]
2108 2108 cpu_tot = cpu_user+cpu_sys
2109 2109 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2110 2110 (cpu_user,cpu_sys,cpu_tot)
2111 2111 print "Wall time: %.2f s" % wall_time
2112 2112 if tc > tc_min:
2113 2113 print "Compiler : %.2f s" % tc
2114 2114 return out
2115 2115
2116 2116 @skip_doctest
2117 2117 def magic_macro(self,parameter_s = ''):
2118 2118 """Define a macro for future re-execution. It accepts ranges of history,
2119 2119 filenames or string objects.
2120 2120
2121 2121 Usage:\\
2122 2122 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2123 2123
2124 2124 Options:
2125 2125
2126 2126 -r: use 'raw' input. By default, the 'processed' history is used,
2127 2127 so that magics are loaded in their transformed version to valid
2128 2128 Python. If this option is given, the raw input as typed as the
2129 2129 command line is used instead.
2130 2130
2131 2131 This will define a global variable called `name` which is a string
2132 2132 made of joining the slices and lines you specify (n1,n2,... numbers
2133 2133 above) from your input history into a single string. This variable
2134 2134 acts like an automatic function which re-executes those lines as if
2135 2135 you had typed them. You just type 'name' at the prompt and the code
2136 2136 executes.
2137 2137
2138 2138 The syntax for indicating input ranges is described in %history.
2139 2139
2140 2140 Note: as a 'hidden' feature, you can also use traditional python slice
2141 2141 notation, where N:M means numbers N through M-1.
2142 2142
2143 2143 For example, if your history contains (%hist prints it)::
2144 2144
2145 2145 44: x=1
2146 2146 45: y=3
2147 2147 46: z=x+y
2148 2148 47: print x
2149 2149 48: a=5
2150 2150 49: print 'x',x,'y',y
2151 2151
2152 2152 you can create a macro with lines 44 through 47 (included) and line 49
2153 2153 called my_macro with::
2154 2154
2155 2155 In [55]: %macro my_macro 44-47 49
2156 2156
2157 2157 Now, typing `my_macro` (without quotes) will re-execute all this code
2158 2158 in one pass.
2159 2159
2160 2160 You don't need to give the line-numbers in order, and any given line
2161 2161 number can appear multiple times. You can assemble macros with any
2162 2162 lines from your input history in any order.
2163 2163
2164 2164 The macro is a simple object which holds its value in an attribute,
2165 2165 but IPython's display system checks for macros and executes them as
2166 2166 code instead of printing them when you type their name.
2167 2167
2168 2168 You can view a macro's contents by explicitly printing it with::
2169 2169
2170 2170 print macro_name
2171 2171
2172 2172 """
2173 2173 opts,args = self.parse_options(parameter_s,'r',mode='list')
2174 2174 if not args: # List existing macros
2175 2175 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
2176 2176 isinstance(v, Macro))
2177 2177 if len(args) == 1:
2178 2178 raise UsageError(
2179 2179 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2180 2180 name, codefrom = args[0], " ".join(args[1:])
2181 2181
2182 2182 #print 'rng',ranges # dbg
2183 2183 try:
2184 2184 lines = self.shell.find_user_code(codefrom, 'r' in opts)
2185 2185 except (ValueError, TypeError) as e:
2186 2186 print e.args[0]
2187 2187 return
2188 2188 macro = Macro(lines)
2189 2189 self.shell.define_macro(name, macro)
2190 2190 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2191 2191 print '=== Macro contents: ==='
2192 2192 print macro,
2193 2193
2194 2194 def magic_save(self,parameter_s = ''):
2195 2195 """Save a set of lines or a macro to a given filename.
2196 2196
2197 2197 Usage:\\
2198 2198 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2199 2199
2200 2200 Options:
2201 2201
2202 2202 -r: use 'raw' input. By default, the 'processed' history is used,
2203 2203 so that magics are loaded in their transformed version to valid
2204 2204 Python. If this option is given, the raw input as typed as the
2205 2205 command line is used instead.
2206 2206
2207 2207 This function uses the same syntax as %history for input ranges,
2208 2208 then saves the lines to the filename you specify.
2209 2209
2210 2210 It adds a '.py' extension to the file if you don't do so yourself, and
2211 2211 it asks for confirmation before overwriting existing files."""
2212 2212
2213 2213 opts,args = self.parse_options(parameter_s,'r',mode='list')
2214 2214 fname, codefrom = unquote_filename(args[0]), " ".join(args[1:])
2215 2215 if not fname.endswith('.py'):
2216 2216 fname += '.py'
2217 2217 if os.path.isfile(fname):
2218 2218 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2219 2219 if ans.lower() not in ['y','yes']:
2220 2220 print 'Operation cancelled.'
2221 2221 return
2222 2222 try:
2223 2223 cmds = self.shell.find_user_code(codefrom, 'r' in opts)
2224 2224 except (TypeError, ValueError) as e:
2225 2225 print e.args[0]
2226 2226 return
2227 2227 with io.open(fname,'w', encoding="utf-8") as f:
2228 2228 f.write(u"# coding: utf-8\n")
2229 2229 f.write(py3compat.cast_unicode(cmds))
2230 2230 print 'The following commands were written to file `%s`:' % fname
2231 2231 print cmds
2232 2232
2233 2233 def magic_pastebin(self, parameter_s = ''):
2234 2234 """Upload code to the 'Lodge it' paste bin, returning the URL."""
2235 2235 try:
2236 2236 code = self.shell.find_user_code(parameter_s)
2237 2237 except (ValueError, TypeError) as e:
2238 2238 print e.args[0]
2239 2239 return
2240 2240 pbserver = ServerProxy('http://paste.pocoo.org/xmlrpc/')
2241 2241 id = pbserver.pastes.newPaste("python", code)
2242 2242 return "http://paste.pocoo.org/show/" + id
2243 2243
2244 2244 def magic_loadpy(self, arg_s):
2245 2245 """Load a .py python script into the GUI console.
2246 2246
2247 2247 This magic command can either take a local filename or a url::
2248 2248
2249 2249 %loadpy myscript.py
2250 2250 %loadpy http://www.example.com/myscript.py
2251 2251 """
2252 2252 arg_s = unquote_filename(arg_s)
2253 2253 remote_url = arg_s.startswith(('http://', 'https://'))
2254 2254 local_url = not remote_url
2255 2255 if local_url and not arg_s.endswith('.py'):
2256 2256 # Local files must be .py; for remote URLs it's possible that the
2257 2257 # fetch URL doesn't have a .py in it (many servers have an opaque
2258 2258 # URL, such as scipy-central.org).
2259 2259 raise ValueError('%%loadpy only works with .py files: %s' % arg_s)
2260 2260
2261 2261 # openpy takes care of finding the source encoding (per PEP 263)
2262 2262 if remote_url:
2263 2263 contents = openpy.read_py_url(arg_s, skip_encoding_cookie=True)
2264 2264 else:
2265 2265 contents = openpy.read_py_file(arg_s, skip_encoding_cookie=True)
2266 2266
2267 2267 self.set_next_input(contents)
2268 2268
2269 2269 def _find_edit_target(self, args, opts, last_call):
2270 2270 """Utility method used by magic_edit to find what to edit."""
2271 2271
2272 2272 def make_filename(arg):
2273 2273 "Make a filename from the given args"
2274 2274 arg = unquote_filename(arg)
2275 2275 try:
2276 2276 filename = get_py_filename(arg)
2277 2277 except IOError:
2278 2278 # If it ends with .py but doesn't already exist, assume we want
2279 2279 # a new file.
2280 2280 if arg.endswith('.py'):
2281 2281 filename = arg
2282 2282 else:
2283 2283 filename = None
2284 2284 return filename
2285 2285
2286 2286 # Set a few locals from the options for convenience:
2287 2287 opts_prev = 'p' in opts
2288 2288 opts_raw = 'r' in opts
2289 2289
2290 2290 # custom exceptions
2291 2291 class DataIsObject(Exception): pass
2292 2292
2293 2293 # Default line number value
2294 2294 lineno = opts.get('n',None)
2295 2295
2296 2296 if opts_prev:
2297 2297 args = '_%s' % last_call[0]
2298 2298 if not self.shell.user_ns.has_key(args):
2299 2299 args = last_call[1]
2300 2300
2301 2301 # use last_call to remember the state of the previous call, but don't
2302 2302 # let it be clobbered by successive '-p' calls.
2303 2303 try:
2304 2304 last_call[0] = self.shell.displayhook.prompt_count
2305 2305 if not opts_prev:
2306 2306 last_call[1] = args
2307 2307 except:
2308 2308 pass
2309 2309
2310 2310 # by default this is done with temp files, except when the given
2311 2311 # arg is a filename
2312 2312 use_temp = True
2313 2313
2314 2314 data = ''
2315 2315
2316 2316 # First, see if the arguments should be a filename.
2317 2317 filename = make_filename(args)
2318 2318 if filename:
2319 2319 use_temp = False
2320 2320 elif args:
2321 2321 # Mode where user specifies ranges of lines, like in %macro.
2322 2322 data = self.extract_input_lines(args, opts_raw)
2323 2323 if not data:
2324 2324 try:
2325 2325 # Load the parameter given as a variable. If not a string,
2326 2326 # process it as an object instead (below)
2327 2327
2328 2328 #print '*** args',args,'type',type(args) # dbg
2329 2329 data = eval(args, self.shell.user_ns)
2330 2330 if not isinstance(data, basestring):
2331 2331 raise DataIsObject
2332 2332
2333 2333 except (NameError,SyntaxError):
2334 2334 # given argument is not a variable, try as a filename
2335 2335 filename = make_filename(args)
2336 2336 if filename is None:
2337 2337 warn("Argument given (%s) can't be found as a variable "
2338 2338 "or as a filename." % args)
2339 2339 return
2340 2340 use_temp = False
2341 2341
2342 2342 except DataIsObject:
2343 2343 # macros have a special edit function
2344 2344 if isinstance(data, Macro):
2345 2345 raise MacroToEdit(data)
2346 2346
2347 2347 # For objects, try to edit the file where they are defined
2348 2348 try:
2349 2349 filename = inspect.getabsfile(data)
2350 2350 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2351 2351 # class created by %edit? Try to find source
2352 2352 # by looking for method definitions instead, the
2353 2353 # __module__ in those classes is FakeModule.
2354 2354 attrs = [getattr(data, aname) for aname in dir(data)]
2355 2355 for attr in attrs:
2356 2356 if not inspect.ismethod(attr):
2357 2357 continue
2358 2358 filename = inspect.getabsfile(attr)
2359 2359 if filename and 'fakemodule' not in filename.lower():
2360 2360 # change the attribute to be the edit target instead
2361 2361 data = attr
2362 2362 break
2363 2363
2364 2364 datafile = 1
2365 2365 except TypeError:
2366 2366 filename = make_filename(args)
2367 2367 datafile = 1
2368 2368 warn('Could not find file where `%s` is defined.\n'
2369 2369 'Opening a file named `%s`' % (args,filename))
2370 2370 # Now, make sure we can actually read the source (if it was in
2371 2371 # a temp file it's gone by now).
2372 2372 if datafile:
2373 2373 try:
2374 2374 if lineno is None:
2375 2375 lineno = inspect.getsourcelines(data)[1]
2376 2376 except IOError:
2377 2377 filename = make_filename(args)
2378 2378 if filename is None:
2379 2379 warn('The file `%s` where `%s` was defined cannot '
2380 2380 'be read.' % (filename,data))
2381 2381 return
2382 2382 use_temp = False
2383 2383
2384 2384 if use_temp:
2385 2385 filename = self.shell.mktempfile(data)
2386 2386 print 'IPython will make a temporary file named:',filename
2387 2387
2388 2388 return filename, lineno, use_temp
2389 2389
2390 2390 def _edit_macro(self,mname,macro):
2391 2391 """open an editor with the macro data in a file"""
2392 2392 filename = self.shell.mktempfile(macro.value)
2393 2393 self.shell.hooks.editor(filename)
2394 2394
2395 2395 # and make a new macro object, to replace the old one
2396 2396 mfile = open(filename)
2397 2397 mvalue = mfile.read()
2398 2398 mfile.close()
2399 2399 self.shell.user_ns[mname] = Macro(mvalue)
2400 2400
2401 2401 def magic_ed(self,parameter_s=''):
2402 2402 """Alias to %edit."""
2403 2403 return self.magic_edit(parameter_s)
2404 2404
2405 2405 @skip_doctest
2406 2406 def magic_edit(self,parameter_s='',last_call=['','']):
2407 2407 """Bring up an editor and execute the resulting code.
2408 2408
2409 2409 Usage:
2410 2410 %edit [options] [args]
2411 2411
2412 2412 %edit runs IPython's editor hook. The default version of this hook is
2413 2413 set to call the editor specified by your $EDITOR environment variable.
2414 2414 If this isn't found, it will default to vi under Linux/Unix and to
2415 2415 notepad under Windows. See the end of this docstring for how to change
2416 2416 the editor hook.
2417 2417
2418 2418 You can also set the value of this editor via the
2419 2419 ``TerminalInteractiveShell.editor`` option in your configuration file.
2420 2420 This is useful if you wish to use a different editor from your typical
2421 2421 default with IPython (and for Windows users who typically don't set
2422 2422 environment variables).
2423 2423
2424 2424 This command allows you to conveniently edit multi-line code right in
2425 2425 your IPython session.
2426 2426
2427 2427 If called without arguments, %edit opens up an empty editor with a
2428 2428 temporary file and will execute the contents of this file when you
2429 2429 close it (don't forget to save it!).
2430 2430
2431 2431
2432 2432 Options:
2433 2433
2434 2434 -n <number>: open the editor at a specified line number. By default,
2435 2435 the IPython editor hook uses the unix syntax 'editor +N filename', but
2436 2436 you can configure this by providing your own modified hook if your
2437 2437 favorite editor supports line-number specifications with a different
2438 2438 syntax.
2439 2439
2440 2440 -p: this will call the editor with the same data as the previous time
2441 2441 it was used, regardless of how long ago (in your current session) it
2442 2442 was.
2443 2443
2444 2444 -r: use 'raw' input. This option only applies to input taken from the
2445 2445 user's history. By default, the 'processed' history is used, so that
2446 2446 magics are loaded in their transformed version to valid Python. If
2447 2447 this option is given, the raw input as typed as the command line is
2448 2448 used instead. When you exit the editor, it will be executed by
2449 2449 IPython's own processor.
2450 2450
2451 2451 -x: do not execute the edited code immediately upon exit. This is
2452 2452 mainly useful if you are editing programs which need to be called with
2453 2453 command line arguments, which you can then do using %run.
2454 2454
2455 2455
2456 2456 Arguments:
2457 2457
2458 2458 If arguments are given, the following possibilities exist:
2459 2459
2460 2460 - If the argument is a filename, IPython will load that into the
2461 2461 editor. It will execute its contents with execfile() when you exit,
2462 2462 loading any code in the file into your interactive namespace.
2463 2463
2464 2464 - The arguments are ranges of input history, e.g. "7 ~1/4-6".
2465 2465 The syntax is the same as in the %history magic.
2466 2466
2467 2467 - If the argument is a string variable, its contents are loaded
2468 2468 into the editor. You can thus edit any string which contains
2469 2469 python code (including the result of previous edits).
2470 2470
2471 2471 - If the argument is the name of an object (other than a string),
2472 2472 IPython will try to locate the file where it was defined and open the
2473 2473 editor at the point where it is defined. You can use `%edit function`
2474 2474 to load an editor exactly at the point where 'function' is defined,
2475 2475 edit it and have the file be executed automatically.
2476 2476
2477 2477 - If the object is a macro (see %macro for details), this opens up your
2478 2478 specified editor with a temporary file containing the macro's data.
2479 2479 Upon exit, the macro is reloaded with the contents of the file.
2480 2480
2481 2481 Note: opening at an exact line is only supported under Unix, and some
2482 2482 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2483 2483 '+NUMBER' parameter necessary for this feature. Good editors like
2484 2484 (X)Emacs, vi, jed, pico and joe all do.
2485 2485
2486 2486 After executing your code, %edit will return as output the code you
2487 2487 typed in the editor (except when it was an existing file). This way
2488 2488 you can reload the code in further invocations of %edit as a variable,
2489 2489 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2490 2490 the output.
2491 2491
2492 2492 Note that %edit is also available through the alias %ed.
2493 2493
2494 2494 This is an example of creating a simple function inside the editor and
2495 2495 then modifying it. First, start up the editor::
2496 2496
2497 2497 In [1]: ed
2498 2498 Editing... done. Executing edited code...
2499 2499 Out[1]: 'def foo():\\n print "foo() was defined in an editing
2500 2500 session"\\n'
2501 2501
2502 2502 We can then call the function foo()::
2503 2503
2504 2504 In [2]: foo()
2505 2505 foo() was defined in an editing session
2506 2506
2507 2507 Now we edit foo. IPython automatically loads the editor with the
2508 2508 (temporary) file where foo() was previously defined::
2509 2509
2510 2510 In [3]: ed foo
2511 2511 Editing... done. Executing edited code...
2512 2512
2513 2513 And if we call foo() again we get the modified version::
2514 2514
2515 2515 In [4]: foo()
2516 2516 foo() has now been changed!
2517 2517
2518 2518 Here is an example of how to edit a code snippet successive
2519 2519 times. First we call the editor::
2520 2520
2521 2521 In [5]: ed
2522 2522 Editing... done. Executing edited code...
2523 2523 hello
2524 2524 Out[5]: "print 'hello'\\n"
2525 2525
2526 2526 Now we call it again with the previous output (stored in _)::
2527 2527
2528 2528 In [6]: ed _
2529 2529 Editing... done. Executing edited code...
2530 2530 hello world
2531 2531 Out[6]: "print 'hello world'\\n"
2532 2532
2533 2533 Now we call it with the output #8 (stored in _8, also as Out[8])::
2534 2534
2535 2535 In [7]: ed _8
2536 2536 Editing... done. Executing edited code...
2537 2537 hello again
2538 2538 Out[7]: "print 'hello again'\\n"
2539 2539
2540 2540
2541 2541 Changing the default editor hook:
2542 2542
2543 2543 If you wish to write your own editor hook, you can put it in a
2544 2544 configuration file which you load at startup time. The default hook
2545 2545 is defined in the IPython.core.hooks module, and you can use that as a
2546 2546 starting example for further modifications. That file also has
2547 2547 general instructions on how to set a new hook for use once you've
2548 2548 defined it."""
2549 2549 opts,args = self.parse_options(parameter_s,'prxn:')
2550 2550
2551 2551 try:
2552 2552 filename, lineno, is_temp = self._find_edit_target(args, opts, last_call)
2553 2553 except MacroToEdit as e:
2554 2554 self._edit_macro(args, e.args[0])
2555 2555 return
2556 2556
2557 2557 # do actual editing here
2558 2558 print 'Editing...',
2559 2559 sys.stdout.flush()
2560 2560 try:
2561 2561 # Quote filenames that may have spaces in them
2562 2562 if ' ' in filename:
2563 2563 filename = "'%s'" % filename
2564 2564 self.shell.hooks.editor(filename,lineno)
2565 2565 except TryNext:
2566 2566 warn('Could not open editor')
2567 2567 return
2568 2568
2569 2569 # XXX TODO: should this be generalized for all string vars?
2570 2570 # For now, this is special-cased to blocks created by cpaste
2571 2571 if args.strip() == 'pasted_block':
2572 2572 self.shell.user_ns['pasted_block'] = file_read(filename)
2573 2573
2574 2574 if 'x' in opts: # -x prevents actual execution
2575 2575 print
2576 2576 else:
2577 2577 print 'done. Executing edited code...'
2578 2578 if 'r' in opts: # Untranslated IPython code
2579 2579 self.shell.run_cell(file_read(filename),
2580 2580 store_history=False)
2581 2581 else:
2582 2582 self.shell.safe_execfile(filename,self.shell.user_ns,
2583 2583 self.shell.user_ns)
2584 2584
2585 2585 if is_temp:
2586 2586 try:
2587 2587 return open(filename).read()
2588 2588 except IOError,msg:
2589 2589 if msg.filename == filename:
2590 2590 warn('File not found. Did you forget to save?')
2591 2591 return
2592 2592 else:
2593 2593 self.shell.showtraceback()
2594 2594
2595 2595 def magic_xmode(self,parameter_s = ''):
2596 2596 """Switch modes for the exception handlers.
2597 2597
2598 2598 Valid modes: Plain, Context and Verbose.
2599 2599
2600 2600 If called without arguments, acts as a toggle."""
2601 2601
2602 2602 def xmode_switch_err(name):
2603 2603 warn('Error changing %s exception modes.\n%s' %
2604 2604 (name,sys.exc_info()[1]))
2605 2605
2606 2606 shell = self.shell
2607 2607 new_mode = parameter_s.strip().capitalize()
2608 2608 try:
2609 2609 shell.InteractiveTB.set_mode(mode=new_mode)
2610 2610 print 'Exception reporting mode:',shell.InteractiveTB.mode
2611 2611 except:
2612 2612 xmode_switch_err('user')
2613 2613
2614 2614 def magic_colors(self,parameter_s = ''):
2615 2615 """Switch color scheme for prompts, info system and exception handlers.
2616 2616
2617 2617 Currently implemented schemes: NoColor, Linux, LightBG.
2618 2618
2619 2619 Color scheme names are not case-sensitive.
2620 2620
2621 2621 Examples
2622 2622 --------
2623 2623 To get a plain black and white terminal::
2624 2624
2625 2625 %colors nocolor
2626 2626 """
2627 2627
2628 2628 def color_switch_err(name):
2629 2629 warn('Error changing %s color schemes.\n%s' %
2630 2630 (name,sys.exc_info()[1]))
2631 2631
2632 2632
2633 2633 new_scheme = parameter_s.strip()
2634 2634 if not new_scheme:
2635 2635 raise UsageError(
2636 2636 "%colors: you must specify a color scheme. See '%colors?'")
2637 2637 return
2638 2638 # local shortcut
2639 2639 shell = self.shell
2640 2640
2641 2641 import IPython.utils.rlineimpl as readline
2642 2642
2643 2643 if not shell.colors_force and \
2644 2644 not readline.have_readline and sys.platform == "win32":
2645 2645 msg = """\
2646 2646 Proper color support under MS Windows requires the pyreadline library.
2647 2647 You can find it at:
2648 2648 http://ipython.org/pyreadline.html
2649 2649 Gary's readline needs the ctypes module, from:
2650 2650 http://starship.python.net/crew/theller/ctypes
2651 2651 (Note that ctypes is already part of Python versions 2.5 and newer).
2652 2652
2653 2653 Defaulting color scheme to 'NoColor'"""
2654 2654 new_scheme = 'NoColor'
2655 2655 warn(msg)
2656 2656
2657 2657 # readline option is 0
2658 2658 if not shell.colors_force and not shell.has_readline:
2659 2659 new_scheme = 'NoColor'
2660 2660
2661 2661 # Set prompt colors
2662 2662 try:
2663 2663 shell.prompt_manager.color_scheme = new_scheme
2664 2664 except:
2665 2665 color_switch_err('prompt')
2666 2666 else:
2667 2667 shell.colors = \
2668 2668 shell.prompt_manager.color_scheme_table.active_scheme_name
2669 2669 # Set exception colors
2670 2670 try:
2671 2671 shell.InteractiveTB.set_colors(scheme = new_scheme)
2672 2672 shell.SyntaxTB.set_colors(scheme = new_scheme)
2673 2673 except:
2674 2674 color_switch_err('exception')
2675 2675
2676 2676 # Set info (for 'object?') colors
2677 2677 if shell.color_info:
2678 2678 try:
2679 2679 shell.inspector.set_active_scheme(new_scheme)
2680 2680 except:
2681 2681 color_switch_err('object inspector')
2682 2682 else:
2683 2683 shell.inspector.set_active_scheme('NoColor')
2684 2684
2685 2685 def magic_pprint(self, parameter_s=''):
2686 2686 """Toggle pretty printing on/off."""
2687 2687 ptformatter = self.shell.display_formatter.formatters['text/plain']
2688 2688 ptformatter.pprint = bool(1 - ptformatter.pprint)
2689 2689 print 'Pretty printing has been turned', \
2690 2690 ['OFF','ON'][ptformatter.pprint]
2691 2691
2692 2692 #......................................................................
2693 2693 # Functions to implement unix shell-type things
2694 2694
2695 2695 @skip_doctest
2696 2696 def magic_alias(self, parameter_s = ''):
2697 2697 """Define an alias for a system command.
2698 2698
2699 2699 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2700 2700
2701 2701 Then, typing 'alias_name params' will execute the system command 'cmd
2702 2702 params' (from your underlying operating system).
2703 2703
2704 2704 Aliases have lower precedence than magic functions and Python normal
2705 2705 variables, so if 'foo' is both a Python variable and an alias, the
2706 2706 alias can not be executed until 'del foo' removes the Python variable.
2707 2707
2708 2708 You can use the %l specifier in an alias definition to represent the
2709 2709 whole line when the alias is called. For example::
2710 2710
2711 2711 In [2]: alias bracket echo "Input in brackets: <%l>"
2712 2712 In [3]: bracket hello world
2713 2713 Input in brackets: <hello world>
2714 2714
2715 2715 You can also define aliases with parameters using %s specifiers (one
2716 2716 per parameter)::
2717 2717
2718 2718 In [1]: alias parts echo first %s second %s
2719 2719 In [2]: %parts A B
2720 2720 first A second B
2721 2721 In [3]: %parts A
2722 2722 Incorrect number of arguments: 2 expected.
2723 2723 parts is an alias to: 'echo first %s second %s'
2724 2724
2725 2725 Note that %l and %s are mutually exclusive. You can only use one or
2726 2726 the other in your aliases.
2727 2727
2728 2728 Aliases expand Python variables just like system calls using ! or !!
2729 2729 do: all expressions prefixed with '$' get expanded. For details of
2730 2730 the semantic rules, see PEP-215:
2731 2731 http://www.python.org/peps/pep-0215.html. This is the library used by
2732 2732 IPython for variable expansion. If you want to access a true shell
2733 2733 variable, an extra $ is necessary to prevent its expansion by
2734 2734 IPython::
2735 2735
2736 2736 In [6]: alias show echo
2737 2737 In [7]: PATH='A Python string'
2738 2738 In [8]: show $PATH
2739 2739 A Python string
2740 2740 In [9]: show $$PATH
2741 2741 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2742 2742
2743 2743 You can use the alias facility to acess all of $PATH. See the %rehash
2744 2744 and %rehashx functions, which automatically create aliases for the
2745 2745 contents of your $PATH.
2746 2746
2747 2747 If called with no parameters, %alias prints the current alias table."""
2748 2748
2749 2749 par = parameter_s.strip()
2750 2750 if not par:
2751 2751 stored = self.db.get('stored_aliases', {} )
2752 2752 aliases = sorted(self.shell.alias_manager.aliases)
2753 2753 # for k, v in stored:
2754 2754 # atab.append(k, v[0])
2755 2755
2756 2756 print "Total number of aliases:", len(aliases)
2757 2757 sys.stdout.flush()
2758 2758 return aliases
2759 2759
2760 2760 # Now try to define a new one
2761 2761 try:
2762 2762 alias,cmd = par.split(None, 1)
2763 2763 except:
2764 2764 print oinspect.getdoc(self.magic_alias)
2765 2765 else:
2766 2766 self.shell.alias_manager.soft_define_alias(alias, cmd)
2767 2767 # end magic_alias
2768 2768
2769 2769 def magic_unalias(self, parameter_s = ''):
2770 2770 """Remove an alias"""
2771 2771
2772 2772 aname = parameter_s.strip()
2773 2773 self.shell.alias_manager.undefine_alias(aname)
2774 2774 stored = self.db.get('stored_aliases', {} )
2775 2775 if aname in stored:
2776 2776 print "Removing %stored alias",aname
2777 2777 del stored[aname]
2778 2778 self.db['stored_aliases'] = stored
2779 2779
2780 2780 def magic_rehashx(self, parameter_s = ''):
2781 2781 """Update the alias table with all executable files in $PATH.
2782 2782
2783 2783 This version explicitly checks that every entry in $PATH is a file
2784 2784 with execute access (os.X_OK), so it is much slower than %rehash.
2785 2785
2786 2786 Under Windows, it checks executability as a match against a
2787 2787 '|'-separated string of extensions, stored in the IPython config
2788 2788 variable win_exec_ext. This defaults to 'exe|com|bat'.
2789 2789
2790 2790 This function also resets the root module cache of module completer,
2791 2791 used on slow filesystems.
2792 2792 """
2793 2793 from IPython.core.alias import InvalidAliasError
2794 2794
2795 2795 # for the benefit of module completer in ipy_completers.py
2796 2796 del self.shell.db['rootmodules']
2797 2797
2798 2798 path = [os.path.abspath(os.path.expanduser(p)) for p in
2799 2799 os.environ.get('PATH','').split(os.pathsep)]
2800 2800 path = filter(os.path.isdir,path)
2801 2801
2802 2802 syscmdlist = []
2803 2803 # Now define isexec in a cross platform manner.
2804 2804 if os.name == 'posix':
2805 2805 isexec = lambda fname:os.path.isfile(fname) and \
2806 2806 os.access(fname,os.X_OK)
2807 2807 else:
2808 2808 try:
2809 2809 winext = os.environ['pathext'].replace(';','|').replace('.','')
2810 2810 except KeyError:
2811 2811 winext = 'exe|com|bat|py'
2812 2812 if 'py' not in winext:
2813 2813 winext += '|py'
2814 2814 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2815 2815 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2816 2816 savedir = os.getcwdu()
2817 2817
2818 2818 # Now walk the paths looking for executables to alias.
2819 2819 try:
2820 2820 # write the whole loop for posix/Windows so we don't have an if in
2821 2821 # the innermost part
2822 2822 if os.name == 'posix':
2823 2823 for pdir in path:
2824 2824 os.chdir(pdir)
2825 2825 for ff in os.listdir(pdir):
2826 2826 if isexec(ff):
2827 2827 try:
2828 2828 # Removes dots from the name since ipython
2829 2829 # will assume names with dots to be python.
2830 2830 self.shell.alias_manager.define_alias(
2831 2831 ff.replace('.',''), ff)
2832 2832 except InvalidAliasError:
2833 2833 pass
2834 2834 else:
2835 2835 syscmdlist.append(ff)
2836 2836 else:
2837 2837 no_alias = self.shell.alias_manager.no_alias
2838 2838 for pdir in path:
2839 2839 os.chdir(pdir)
2840 2840 for ff in os.listdir(pdir):
2841 2841 base, ext = os.path.splitext(ff)
2842 2842 if isexec(ff) and base.lower() not in no_alias:
2843 2843 if ext.lower() == '.exe':
2844 2844 ff = base
2845 2845 try:
2846 2846 # Removes dots from the name since ipython
2847 2847 # will assume names with dots to be python.
2848 2848 self.shell.alias_manager.define_alias(
2849 2849 base.lower().replace('.',''), ff)
2850 2850 except InvalidAliasError:
2851 2851 pass
2852 2852 syscmdlist.append(ff)
2853 2853 self.shell.db['syscmdlist'] = syscmdlist
2854 2854 finally:
2855 2855 os.chdir(savedir)
2856 2856
2857 2857 @skip_doctest
2858 2858 def magic_pwd(self, parameter_s = ''):
2859 2859 """Return the current working directory path.
2860 2860
2861 2861 Examples
2862 2862 --------
2863 2863 ::
2864 2864
2865 2865 In [9]: pwd
2866 2866 Out[9]: '/home/tsuser/sprint/ipython'
2867 2867 """
2868 2868 return os.getcwdu()
2869 2869
2870 2870 @skip_doctest
2871 2871 def magic_cd(self, parameter_s=''):
2872 2872 """Change the current working directory.
2873 2873
2874 2874 This command automatically maintains an internal list of directories
2875 2875 you visit during your IPython session, in the variable _dh. The
2876 2876 command %dhist shows this history nicely formatted. You can also
2877 2877 do 'cd -<tab>' to see directory history conveniently.
2878 2878
2879 2879 Usage:
2880 2880
2881 2881 cd 'dir': changes to directory 'dir'.
2882 2882
2883 2883 cd -: changes to the last visited directory.
2884 2884
2885 2885 cd -<n>: changes to the n-th directory in the directory history.
2886 2886
2887 2887 cd --foo: change to directory that matches 'foo' in history
2888 2888
2889 2889 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2890 2890 (note: cd <bookmark_name> is enough if there is no
2891 2891 directory <bookmark_name>, but a bookmark with the name exists.)
2892 2892 'cd -b <tab>' allows you to tab-complete bookmark names.
2893 2893
2894 2894 Options:
2895 2895
2896 2896 -q: quiet. Do not print the working directory after the cd command is
2897 2897 executed. By default IPython's cd command does print this directory,
2898 2898 since the default prompts do not display path information.
2899 2899
2900 2900 Note that !cd doesn't work for this purpose because the shell where
2901 2901 !command runs is immediately discarded after executing 'command'.
2902 2902
2903 2903 Examples
2904 2904 --------
2905 2905 ::
2906 2906
2907 2907 In [10]: cd parent/child
2908 2908 /home/tsuser/parent/child
2909 2909 """
2910 2910
2911 2911 parameter_s = parameter_s.strip()
2912 2912 #bkms = self.shell.persist.get("bookmarks",{})
2913 2913
2914 2914 oldcwd = os.getcwdu()
2915 2915 numcd = re.match(r'(-)(\d+)$',parameter_s)
2916 2916 # jump in directory history by number
2917 2917 if numcd:
2918 2918 nn = int(numcd.group(2))
2919 2919 try:
2920 2920 ps = self.shell.user_ns['_dh'][nn]
2921 2921 except IndexError:
2922 2922 print 'The requested directory does not exist in history.'
2923 2923 return
2924 2924 else:
2925 2925 opts = {}
2926 2926 elif parameter_s.startswith('--'):
2927 2927 ps = None
2928 2928 fallback = None
2929 2929 pat = parameter_s[2:]
2930 2930 dh = self.shell.user_ns['_dh']
2931 2931 # first search only by basename (last component)
2932 2932 for ent in reversed(dh):
2933 2933 if pat in os.path.basename(ent) and os.path.isdir(ent):
2934 2934 ps = ent
2935 2935 break
2936 2936
2937 2937 if fallback is None and pat in ent and os.path.isdir(ent):
2938 2938 fallback = ent
2939 2939
2940 2940 # if we have no last part match, pick the first full path match
2941 2941 if ps is None:
2942 2942 ps = fallback
2943 2943
2944 2944 if ps is None:
2945 2945 print "No matching entry in directory history"
2946 2946 return
2947 2947 else:
2948 2948 opts = {}
2949 2949
2950 2950
2951 2951 else:
2952 2952 #turn all non-space-escaping backslashes to slashes,
2953 2953 # for c:\windows\directory\names\
2954 2954 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2955 2955 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2956 2956 # jump to previous
2957 2957 if ps == '-':
2958 2958 try:
2959 2959 ps = self.shell.user_ns['_dh'][-2]
2960 2960 except IndexError:
2961 2961 raise UsageError('%cd -: No previous directory to change to.')
2962 2962 # jump to bookmark if needed
2963 2963 else:
2964 2964 if not os.path.isdir(ps) or opts.has_key('b'):
2965 2965 bkms = self.db.get('bookmarks', {})
2966 2966
2967 2967 if bkms.has_key(ps):
2968 2968 target = bkms[ps]
2969 2969 print '(bookmark:%s) -> %s' % (ps,target)
2970 2970 ps = target
2971 2971 else:
2972 2972 if opts.has_key('b'):
2973 2973 raise UsageError("Bookmark '%s' not found. "
2974 2974 "Use '%%bookmark -l' to see your bookmarks." % ps)
2975 2975
2976 2976 # strip extra quotes on Windows, because os.chdir doesn't like them
2977 2977 ps = unquote_filename(ps)
2978 2978 # at this point ps should point to the target dir
2979 2979 if ps:
2980 2980 try:
2981 2981 os.chdir(os.path.expanduser(ps))
2982 2982 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2983 2983 set_term_title('IPython: ' + abbrev_cwd())
2984 2984 except OSError:
2985 2985 print sys.exc_info()[1]
2986 2986 else:
2987 2987 cwd = os.getcwdu()
2988 2988 dhist = self.shell.user_ns['_dh']
2989 2989 if oldcwd != cwd:
2990 2990 dhist.append(cwd)
2991 2991 self.db['dhist'] = compress_dhist(dhist)[-100:]
2992 2992
2993 2993 else:
2994 2994 os.chdir(self.shell.home_dir)
2995 2995 if hasattr(self.shell, 'term_title') and self.shell.term_title:
2996 2996 set_term_title('IPython: ' + '~')
2997 2997 cwd = os.getcwdu()
2998 2998 dhist = self.shell.user_ns['_dh']
2999 2999
3000 3000 if oldcwd != cwd:
3001 3001 dhist.append(cwd)
3002 3002 self.db['dhist'] = compress_dhist(dhist)[-100:]
3003 3003 if not 'q' in opts and self.shell.user_ns['_dh']:
3004 3004 print self.shell.user_ns['_dh'][-1]
3005 3005
3006 3006
3007 3007 def magic_env(self, parameter_s=''):
3008 3008 """List environment variables."""
3009 3009
3010 3010 return dict(os.environ)
3011 3011
3012 3012 def magic_pushd(self, parameter_s=''):
3013 3013 """Place the current dir on stack and change directory.
3014 3014
3015 3015 Usage:\\
3016 3016 %pushd ['dirname']
3017 3017 """
3018 3018
3019 3019 dir_s = self.shell.dir_stack
3020 3020 tgt = os.path.expanduser(unquote_filename(parameter_s))
3021 3021 cwd = os.getcwdu().replace(self.home_dir,'~')
3022 3022 if tgt:
3023 3023 self.magic_cd(parameter_s)
3024 3024 dir_s.insert(0,cwd)
3025 3025 return self.magic_dirs()
3026 3026
3027 3027 def magic_popd(self, parameter_s=''):
3028 3028 """Change to directory popped off the top of the stack.
3029 3029 """
3030 3030 if not self.shell.dir_stack:
3031 3031 raise UsageError("%popd on empty stack")
3032 3032 top = self.shell.dir_stack.pop(0)
3033 3033 self.magic_cd(top)
3034 3034 print "popd ->",top
3035 3035
3036 3036 def magic_dirs(self, parameter_s=''):
3037 3037 """Return the current directory stack."""
3038 3038
3039 3039 return self.shell.dir_stack
3040 3040
3041 3041 def magic_dhist(self, parameter_s=''):
3042 3042 """Print your history of visited directories.
3043 3043
3044 3044 %dhist -> print full history\\
3045 3045 %dhist n -> print last n entries only\\
3046 3046 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
3047 3047
3048 3048 This history is automatically maintained by the %cd command, and
3049 3049 always available as the global list variable _dh. You can use %cd -<n>
3050 3050 to go to directory number <n>.
3051 3051
3052 3052 Note that most of time, you should view directory history by entering
3053 3053 cd -<TAB>.
3054 3054
3055 3055 """
3056 3056
3057 3057 dh = self.shell.user_ns['_dh']
3058 3058 if parameter_s:
3059 3059 try:
3060 3060 args = map(int,parameter_s.split())
3061 3061 except:
3062 3062 self.arg_err(Magic.magic_dhist)
3063 3063 return
3064 3064 if len(args) == 1:
3065 3065 ini,fin = max(len(dh)-(args[0]),0),len(dh)
3066 3066 elif len(args) == 2:
3067 3067 ini,fin = args
3068 3068 else:
3069 3069 self.arg_err(Magic.magic_dhist)
3070 3070 return
3071 3071 else:
3072 3072 ini,fin = 0,len(dh)
3073 3073 nlprint(dh,
3074 3074 header = 'Directory history (kept in _dh)',
3075 3075 start=ini,stop=fin)
3076 3076
3077 3077 @skip_doctest
3078 3078 def magic_sc(self, parameter_s=''):
3079 3079 """Shell capture - execute a shell command and capture its output.
3080 3080
3081 3081 DEPRECATED. Suboptimal, retained for backwards compatibility.
3082 3082
3083 3083 You should use the form 'var = !command' instead. Example:
3084 3084
3085 3085 "%sc -l myfiles = ls ~" should now be written as
3086 3086
3087 3087 "myfiles = !ls ~"
3088 3088
3089 3089 myfiles.s, myfiles.l and myfiles.n still apply as documented
3090 3090 below.
3091 3091
3092 3092 --
3093 3093 %sc [options] varname=command
3094 3094
3095 3095 IPython will run the given command using commands.getoutput(), and
3096 3096 will then update the user's interactive namespace with a variable
3097 3097 called varname, containing the value of the call. Your command can
3098 3098 contain shell wildcards, pipes, etc.
3099 3099
3100 3100 The '=' sign in the syntax is mandatory, and the variable name you
3101 3101 supply must follow Python's standard conventions for valid names.
3102 3102
3103 3103 (A special format without variable name exists for internal use)
3104 3104
3105 3105 Options:
3106 3106
3107 3107 -l: list output. Split the output on newlines into a list before
3108 3108 assigning it to the given variable. By default the output is stored
3109 3109 as a single string.
3110 3110
3111 3111 -v: verbose. Print the contents of the variable.
3112 3112
3113 3113 In most cases you should not need to split as a list, because the
3114 3114 returned value is a special type of string which can automatically
3115 3115 provide its contents either as a list (split on newlines) or as a
3116 3116 space-separated string. These are convenient, respectively, either
3117 3117 for sequential processing or to be passed to a shell command.
3118 3118
3119 3119 For example::
3120 3120
3121 3121 # Capture into variable a
3122 3122 In [1]: sc a=ls *py
3123 3123
3124 3124 # a is a string with embedded newlines
3125 3125 In [2]: a
3126 3126 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3127 3127
3128 3128 # which can be seen as a list:
3129 3129 In [3]: a.l
3130 3130 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3131 3131
3132 3132 # or as a whitespace-separated string:
3133 3133 In [4]: a.s
3134 3134 Out[4]: 'setup.py win32_manual_post_install.py'
3135 3135
3136 3136 # a.s is useful to pass as a single command line:
3137 3137 In [5]: !wc -l $a.s
3138 3138 146 setup.py
3139 3139 130 win32_manual_post_install.py
3140 3140 276 total
3141 3141
3142 3142 # while the list form is useful to loop over:
3143 3143 In [6]: for f in a.l:
3144 3144 ...: !wc -l $f
3145 3145 ...:
3146 3146 146 setup.py
3147 3147 130 win32_manual_post_install.py
3148 3148
3149 3149 Similarly, the lists returned by the -l option are also special, in
3150 3150 the sense that you can equally invoke the .s attribute on them to
3151 3151 automatically get a whitespace-separated string from their contents::
3152 3152
3153 3153 In [7]: sc -l b=ls *py
3154 3154
3155 3155 In [8]: b
3156 3156 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3157 3157
3158 3158 In [9]: b.s
3159 3159 Out[9]: 'setup.py win32_manual_post_install.py'
3160 3160
3161 3161 In summary, both the lists and strings used for output capture have
3162 3162 the following special attributes::
3163 3163
3164 3164 .l (or .list) : value as list.
3165 3165 .n (or .nlstr): value as newline-separated string.
3166 3166 .s (or .spstr): value as space-separated string.
3167 3167 """
3168 3168
3169 3169 opts,args = self.parse_options(parameter_s,'lv')
3170 3170 # Try to get a variable name and command to run
3171 3171 try:
3172 3172 # the variable name must be obtained from the parse_options
3173 3173 # output, which uses shlex.split to strip options out.
3174 3174 var,_ = args.split('=',1)
3175 3175 var = var.strip()
3176 3176 # But the command has to be extracted from the original input
3177 3177 # parameter_s, not on what parse_options returns, to avoid the
3178 3178 # quote stripping which shlex.split performs on it.
3179 3179 _,cmd = parameter_s.split('=',1)
3180 3180 except ValueError:
3181 3181 var,cmd = '',''
3182 3182 # If all looks ok, proceed
3183 3183 split = 'l' in opts
3184 3184 out = self.shell.getoutput(cmd, split=split)
3185 3185 if opts.has_key('v'):
3186 3186 print '%s ==\n%s' % (var,pformat(out))
3187 3187 if var:
3188 3188 self.shell.user_ns.update({var:out})
3189 3189 else:
3190 3190 return out
3191 3191
3192 3192 def magic_sx(self, parameter_s=''):
3193 3193 """Shell execute - run a shell command and capture its output.
3194 3194
3195 3195 %sx command
3196 3196
3197 3197 IPython will run the given command using commands.getoutput(), and
3198 3198 return the result formatted as a list (split on '\\n'). Since the
3199 3199 output is _returned_, it will be stored in ipython's regular output
3200 3200 cache Out[N] and in the '_N' automatic variables.
3201 3201
3202 3202 Notes:
3203 3203
3204 3204 1) If an input line begins with '!!', then %sx is automatically
3205 3205 invoked. That is, while::
3206 3206
3207 3207 !ls
3208 3208
3209 3209 causes ipython to simply issue system('ls'), typing::
3210 3210
3211 3211 !!ls
3212 3212
3213 3213 is a shorthand equivalent to::
3214 3214
3215 3215 %sx ls
3216 3216
3217 3217 2) %sx differs from %sc in that %sx automatically splits into a list,
3218 3218 like '%sc -l'. The reason for this is to make it as easy as possible
3219 3219 to process line-oriented shell output via further python commands.
3220 3220 %sc is meant to provide much finer control, but requires more
3221 3221 typing.
3222 3222
3223 3223 3) Just like %sc -l, this is a list with special attributes:
3224 3224 ::
3225 3225
3226 3226 .l (or .list) : value as list.
3227 3227 .n (or .nlstr): value as newline-separated string.
3228 3228 .s (or .spstr): value as whitespace-separated string.
3229 3229
3230 3230 This is very useful when trying to use such lists as arguments to
3231 3231 system commands."""
3232 3232
3233 3233 if parameter_s:
3234 3234 return self.shell.getoutput(parameter_s)
3235 3235
3236 3236
3237 3237 def magic_bookmark(self, parameter_s=''):
3238 3238 """Manage IPython's bookmark system.
3239 3239
3240 3240 %bookmark <name> - set bookmark to current dir
3241 3241 %bookmark <name> <dir> - set bookmark to <dir>
3242 3242 %bookmark -l - list all bookmarks
3243 3243 %bookmark -d <name> - remove bookmark
3244 3244 %bookmark -r - remove all bookmarks
3245 3245
3246 3246 You can later on access a bookmarked folder with::
3247 3247
3248 3248 %cd -b <name>
3249 3249
3250 3250 or simply '%cd <name>' if there is no directory called <name> AND
3251 3251 there is such a bookmark defined.
3252 3252
3253 3253 Your bookmarks persist through IPython sessions, but they are
3254 3254 associated with each profile."""
3255 3255
3256 3256 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3257 3257 if len(args) > 2:
3258 3258 raise UsageError("%bookmark: too many arguments")
3259 3259
3260 3260 bkms = self.db.get('bookmarks',{})
3261 3261
3262 3262 if opts.has_key('d'):
3263 3263 try:
3264 3264 todel = args[0]
3265 3265 except IndexError:
3266 3266 raise UsageError(
3267 3267 "%bookmark -d: must provide a bookmark to delete")
3268 3268 else:
3269 3269 try:
3270 3270 del bkms[todel]
3271 3271 except KeyError:
3272 3272 raise UsageError(
3273 3273 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3274 3274
3275 3275 elif opts.has_key('r'):
3276 3276 bkms = {}
3277 3277 elif opts.has_key('l'):
3278 3278 bks = bkms.keys()
3279 3279 bks.sort()
3280 3280 if bks:
3281 3281 size = max(map(len,bks))
3282 3282 else:
3283 3283 size = 0
3284 3284 fmt = '%-'+str(size)+'s -> %s'
3285 3285 print 'Current bookmarks:'
3286 3286 for bk in bks:
3287 3287 print fmt % (bk,bkms[bk])
3288 3288 else:
3289 3289 if not args:
3290 3290 raise UsageError("%bookmark: You must specify the bookmark name")
3291 3291 elif len(args)==1:
3292 3292 bkms[args[0]] = os.getcwdu()
3293 3293 elif len(args)==2:
3294 3294 bkms[args[0]] = args[1]
3295 3295 self.db['bookmarks'] = bkms
3296 3296
3297 3297 def magic_pycat(self, parameter_s=''):
3298 3298 """Show a syntax-highlighted file through a pager.
3299 3299
3300 3300 This magic is similar to the cat utility, but it will assume the file
3301 3301 to be Python source and will show it with syntax highlighting. """
3302 3302
3303 3303 try:
3304 3304 filename = get_py_filename(parameter_s)
3305 3305 cont = file_read(filename)
3306 3306 except IOError:
3307 3307 try:
3308 3308 cont = eval(parameter_s,self.user_ns)
3309 3309 except NameError:
3310 3310 cont = None
3311 3311 if cont is None:
3312 3312 print "Error: no such file or variable"
3313 3313 return
3314 3314
3315 3315 page.page(self.shell.pycolorize(cont))
3316 3316
3317 3317 def magic_quickref(self,arg):
3318 3318 """ Show a quick reference sheet """
3319 3319 import IPython.core.usage
3320 3320 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3321 3321
3322 3322 page.page(qr)
3323 3323
3324 3324 def magic_doctest_mode(self,parameter_s=''):
3325 3325 """Toggle doctest mode on and off.
3326 3326
3327 3327 This mode is intended to make IPython behave as much as possible like a
3328 3328 plain Python shell, from the perspective of how its prompts, exceptions
3329 3329 and output look. This makes it easy to copy and paste parts of a
3330 3330 session into doctests. It does so by:
3331 3331
3332 3332 - Changing the prompts to the classic ``>>>`` ones.
3333 3333 - Changing the exception reporting mode to 'Plain'.
3334 3334 - Disabling pretty-printing of output.
3335 3335
3336 3336 Note that IPython also supports the pasting of code snippets that have
3337 3337 leading '>>>' and '...' prompts in them. This means that you can paste
3338 3338 doctests from files or docstrings (even if they have leading
3339 3339 whitespace), and the code will execute correctly. You can then use
3340 3340 '%history -t' to see the translated history; this will give you the
3341 3341 input after removal of all the leading prompts and whitespace, which
3342 3342 can be pasted back into an editor.
3343 3343
3344 3344 With these features, you can switch into this mode easily whenever you
3345 3345 need to do testing and changes to doctests, without having to leave
3346 3346 your existing IPython session.
3347 3347 """
3348 3348
3349 3349 from IPython.utils.ipstruct import Struct
3350 3350
3351 3351 # Shorthands
3352 3352 shell = self.shell
3353 3353 pm = shell.prompt_manager
3354 3354 meta = shell.meta
3355 3355 disp_formatter = self.shell.display_formatter
3356 3356 ptformatter = disp_formatter.formatters['text/plain']
3357 3357 # dstore is a data store kept in the instance metadata bag to track any
3358 3358 # changes we make, so we can undo them later.
3359 3359 dstore = meta.setdefault('doctest_mode',Struct())
3360 3360 save_dstore = dstore.setdefault
3361 3361
3362 3362 # save a few values we'll need to recover later
3363 3363 mode = save_dstore('mode',False)
3364 3364 save_dstore('rc_pprint',ptformatter.pprint)
3365 3365 save_dstore('xmode',shell.InteractiveTB.mode)
3366 3366 save_dstore('rc_separate_out',shell.separate_out)
3367 3367 save_dstore('rc_separate_out2',shell.separate_out2)
3368 3368 save_dstore('rc_prompts_pad_left',pm.justify)
3369 3369 save_dstore('rc_separate_in',shell.separate_in)
3370 3370 save_dstore('rc_plain_text_only',disp_formatter.plain_text_only)
3371 3371 save_dstore('prompt_templates',(pm.in_template, pm.in2_template, pm.out_template))
3372 3372
3373 3373 if mode == False:
3374 3374 # turn on
3375 3375 pm.in_template = '>>> '
3376 3376 pm.in2_template = '... '
3377 3377 pm.out_template = ''
3378 3378
3379 3379 # Prompt separators like plain python
3380 3380 shell.separate_in = ''
3381 3381 shell.separate_out = ''
3382 3382 shell.separate_out2 = ''
3383 3383
3384 3384 pm.justify = False
3385 3385
3386 3386 ptformatter.pprint = False
3387 3387 disp_formatter.plain_text_only = True
3388 3388
3389 3389 shell.magic_xmode('Plain')
3390 3390 else:
3391 3391 # turn off
3392 3392 pm.in_template, pm.in2_template, pm.out_template = dstore.prompt_templates
3393 3393
3394 3394 shell.separate_in = dstore.rc_separate_in
3395 3395
3396 3396 shell.separate_out = dstore.rc_separate_out
3397 3397 shell.separate_out2 = dstore.rc_separate_out2
3398 3398
3399 3399 pm.justify = dstore.rc_prompts_pad_left
3400 3400
3401 3401 ptformatter.pprint = dstore.rc_pprint
3402 3402 disp_formatter.plain_text_only = dstore.rc_plain_text_only
3403 3403
3404 3404 shell.magic_xmode(dstore.xmode)
3405 3405
3406 3406 # Store new mode and inform
3407 3407 dstore.mode = bool(1-int(mode))
3408 3408 mode_label = ['OFF','ON'][dstore.mode]
3409 3409 print 'Doctest mode is:', mode_label
3410 3410
3411 3411 def magic_gui(self, parameter_s=''):
3412 3412 """Enable or disable IPython GUI event loop integration.
3413 3413
3414 3414 %gui [GUINAME]
3415 3415
3416 3416 This magic replaces IPython's threaded shells that were activated
3417 3417 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3418 3418 can now be enabled at runtime and keyboard
3419 3419 interrupts should work without any problems. The following toolkits
3420 3420 are supported: wxPython, PyQt4, PyGTK, Tk and Cocoa (OSX)::
3421 3421
3422 3422 %gui wx # enable wxPython event loop integration
3423 3423 %gui qt4|qt # enable PyQt4 event loop integration
3424 3424 %gui gtk # enable PyGTK event loop integration
3425 3425 %gui gtk3 # enable Gtk3 event loop integration
3426 3426 %gui tk # enable Tk event loop integration
3427 3427 %gui OSX # enable Cocoa event loop integration
3428 3428 # (requires %matplotlib 1.1)
3429 3429 %gui # disable all event loop integration
3430 3430
3431 3431 WARNING: after any of these has been called you can simply create
3432 3432 an application object, but DO NOT start the event loop yourself, as
3433 3433 we have already handled that.
3434 3434 """
3435 3435 opts, arg = self.parse_options(parameter_s, '')
3436 3436 if arg=='': arg = None
3437 3437 try:
3438 3438 return self.enable_gui(arg)
3439 3439 except Exception as e:
3440 3440 # print simple error message, rather than traceback if we can't
3441 3441 # hook up the GUI
3442 3442 error(str(e))
3443 3443
3444 3444 def magic_install_ext(self, parameter_s):
3445 3445 """Download and install an extension from a URL, e.g.::
3446 3446
3447 3447 %install_ext https://bitbucket.org/birkenfeld/ipython-physics/raw/d1310a2ab15d/physics.py
3448 3448
3449 3449 The URL should point to an importable Python module - either a .py file
3450 3450 or a .zip file.
3451 3451
3452 3452 Parameters:
3453 3453
3454 3454 -n filename : Specify a name for the file, rather than taking it from
3455 3455 the URL.
3456 3456 """
3457 3457 opts, args = self.parse_options(parameter_s, 'n:')
3458 3458 try:
3459 filename, headers = self.extension_manager.install_extension(args, opts.get('n'))
3459 filename = self.extension_manager.install_extension(args, opts.get('n'))
3460 3460 except ValueError as e:
3461 3461 print e
3462 3462 return
3463 3463
3464 3464 filename = os.path.basename(filename)
3465 3465 print "Installed %s. To use it, type:" % filename
3466 3466 print " %%load_ext %s" % os.path.splitext(filename)[0]
3467 3467
3468 3468
3469 3469 def magic_load_ext(self, module_str):
3470 3470 """Load an IPython extension by its module name."""
3471 3471 return self.extension_manager.load_extension(module_str)
3472 3472
3473 3473 def magic_unload_ext(self, module_str):
3474 3474 """Unload an IPython extension by its module name."""
3475 3475 self.extension_manager.unload_extension(module_str)
3476 3476
3477 3477 def magic_reload_ext(self, module_str):
3478 3478 """Reload an IPython extension by its module name."""
3479 3479 self.extension_manager.reload_extension(module_str)
3480 3480
3481 3481 def magic_install_profiles(self, s):
3482 3482 """%install_profiles has been deprecated."""
3483 3483 print '\n'.join([
3484 3484 "%install_profiles has been deprecated.",
3485 3485 "Use `ipython profile list` to view available profiles.",
3486 3486 "Requesting a profile with `ipython profile create <name>`",
3487 3487 "or `ipython --profile=<name>` will start with the bundled",
3488 3488 "profile of that name if it exists."
3489 3489 ])
3490 3490
3491 3491 def magic_install_default_config(self, s):
3492 3492 """%install_default_config has been deprecated."""
3493 3493 print '\n'.join([
3494 3494 "%install_default_config has been deprecated.",
3495 3495 "Use `ipython profile create <name>` to initialize a profile",
3496 3496 "with the default config files.",
3497 3497 "Add `--reset` to overwrite already existing config files with defaults."
3498 3498 ])
3499 3499
3500 3500 # Pylab support: simple wrappers that activate pylab, load gui input
3501 3501 # handling and modify slightly %run
3502 3502
3503 3503 @skip_doctest
3504 3504 def _pylab_magic_run(self, parameter_s=''):
3505 3505 Magic.magic_run(self, parameter_s,
3506 3506 runner=mpl_runner(self.shell.safe_execfile))
3507 3507
3508 3508 _pylab_magic_run.__doc__ = magic_run.__doc__
3509 3509
3510 3510 @skip_doctest
3511 3511 def magic_pylab(self, s):
3512 3512 """Load numpy and matplotlib to work interactively.
3513 3513
3514 3514 %pylab [GUINAME]
3515 3515
3516 3516 This function lets you activate pylab (matplotlib, numpy and
3517 3517 interactive support) at any point during an IPython session.
3518 3518
3519 3519 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3520 3520 pylab and mlab, as well as all names from numpy and pylab.
3521 3521
3522 3522 If you are using the inline matplotlib backend for embedded figures,
3523 3523 you can adjust its behavior via the %config magic::
3524 3524
3525 3525 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
3526 3526 In [1]: %config InlineBackend.figure_format = 'svg'
3527 3527
3528 3528 # change the behavior of closing all figures at the end of each
3529 3529 # execution (cell), or allowing reuse of active figures across
3530 3530 # cells:
3531 3531 In [2]: %config InlineBackend.close_figures = False
3532 3532
3533 3533 Parameters
3534 3534 ----------
3535 3535 guiname : optional
3536 3536 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
3537 3537 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
3538 3538 used, otherwise matplotlib's default (which you can override in your
3539 3539 matplotlib config file) is used.
3540 3540
3541 3541 Examples
3542 3542 --------
3543 3543 In this case, where the MPL default is TkAgg::
3544 3544
3545 3545 In [2]: %pylab
3546 3546
3547 3547 Welcome to pylab, a matplotlib-based Python environment.
3548 3548 Backend in use: TkAgg
3549 3549 For more information, type 'help(pylab)'.
3550 3550
3551 3551 But you can explicitly request a different backend::
3552 3552
3553 3553 In [3]: %pylab qt
3554 3554
3555 3555 Welcome to pylab, a matplotlib-based Python environment.
3556 3556 Backend in use: Qt4Agg
3557 3557 For more information, type 'help(pylab)'.
3558 3558 """
3559 3559
3560 3560 if Application.initialized():
3561 3561 app = Application.instance()
3562 3562 try:
3563 3563 import_all_status = app.pylab_import_all
3564 3564 except AttributeError:
3565 3565 import_all_status = True
3566 3566 else:
3567 3567 import_all_status = True
3568 3568
3569 3569 self.shell.enable_pylab(s, import_all=import_all_status)
3570 3570
3571 3571 def magic_tb(self, s):
3572 3572 """Print the last traceback with the currently active exception mode.
3573 3573
3574 3574 See %xmode for changing exception reporting modes."""
3575 3575 self.shell.showtraceback()
3576 3576
3577 3577 @skip_doctest
3578 3578 def magic_precision(self, s=''):
3579 3579 """Set floating point precision for pretty printing.
3580 3580
3581 3581 Can set either integer precision or a format string.
3582 3582
3583 3583 If numpy has been imported and precision is an int,
3584 3584 numpy display precision will also be set, via ``numpy.set_printoptions``.
3585 3585
3586 3586 If no argument is given, defaults will be restored.
3587 3587
3588 3588 Examples
3589 3589 --------
3590 3590 ::
3591 3591
3592 3592 In [1]: from math import pi
3593 3593
3594 3594 In [2]: %precision 3
3595 3595 Out[2]: u'%.3f'
3596 3596
3597 3597 In [3]: pi
3598 3598 Out[3]: 3.142
3599 3599
3600 3600 In [4]: %precision %i
3601 3601 Out[4]: u'%i'
3602 3602
3603 3603 In [5]: pi
3604 3604 Out[5]: 3
3605 3605
3606 3606 In [6]: %precision %e
3607 3607 Out[6]: u'%e'
3608 3608
3609 3609 In [7]: pi**10
3610 3610 Out[7]: 9.364805e+04
3611 3611
3612 3612 In [8]: %precision
3613 3613 Out[8]: u'%r'
3614 3614
3615 3615 In [9]: pi**10
3616 3616 Out[9]: 93648.047476082982
3617 3617
3618 3618 """
3619 3619
3620 3620 ptformatter = self.shell.display_formatter.formatters['text/plain']
3621 3621 ptformatter.float_precision = s
3622 3622 return ptformatter.float_format
3623 3623
3624 3624
3625 3625 @magic_arguments.magic_arguments()
3626 3626 @magic_arguments.argument(
3627 3627 '-e', '--export', action='store_true', default=False,
3628 3628 help='Export IPython history as a notebook. The filename argument '
3629 3629 'is used to specify the notebook name and format. For example '
3630 3630 'a filename of notebook.ipynb will result in a notebook name '
3631 3631 'of "notebook" and a format of "xml". Likewise using a ".json" '
3632 3632 'or ".py" file extension will write the notebook in the json '
3633 3633 'or py formats.'
3634 3634 )
3635 3635 @magic_arguments.argument(
3636 3636 '-f', '--format',
3637 3637 help='Convert an existing IPython notebook to a new format. This option '
3638 3638 'specifies the new format and can have the values: xml, json, py. '
3639 3639 'The target filename is chosen automatically based on the new '
3640 3640 'format. The filename argument gives the name of the source file.'
3641 3641 )
3642 3642 @magic_arguments.argument(
3643 3643 'filename', type=unicode,
3644 3644 help='Notebook name or filename'
3645 3645 )
3646 3646 def magic_notebook(self, s):
3647 3647 """Export and convert IPython notebooks.
3648 3648
3649 3649 This function can export the current IPython history to a notebook file
3650 3650 or can convert an existing notebook file into a different format. For
3651 3651 example, to export the history to "foo.ipynb" do "%notebook -e foo.ipynb".
3652 3652 To export the history to "foo.py" do "%notebook -e foo.py". To convert
3653 3653 "foo.ipynb" to "foo.json" do "%notebook -f json foo.ipynb". Possible
3654 3654 formats include (json/ipynb, py).
3655 3655 """
3656 3656 args = magic_arguments.parse_argstring(self.magic_notebook, s)
3657 3657
3658 3658 from IPython.nbformat import current
3659 3659 args.filename = unquote_filename(args.filename)
3660 3660 if args.export:
3661 3661 fname, name, format = current.parse_filename(args.filename)
3662 3662 cells = []
3663 3663 hist = list(self.history_manager.get_range())
3664 3664 for session, prompt_number, input in hist[:-1]:
3665 3665 cells.append(current.new_code_cell(prompt_number=prompt_number, input=input))
3666 3666 worksheet = current.new_worksheet(cells=cells)
3667 3667 nb = current.new_notebook(name=name,worksheets=[worksheet])
3668 3668 with io.open(fname, 'w', encoding='utf-8') as f:
3669 3669 current.write(nb, f, format);
3670 3670 elif args.format is not None:
3671 3671 old_fname, old_name, old_format = current.parse_filename(args.filename)
3672 3672 new_format = args.format
3673 3673 if new_format == u'xml':
3674 3674 raise ValueError('Notebooks cannot be written as xml.')
3675 3675 elif new_format == u'ipynb' or new_format == u'json':
3676 3676 new_fname = old_name + u'.ipynb'
3677 3677 new_format = u'json'
3678 3678 elif new_format == u'py':
3679 3679 new_fname = old_name + u'.py'
3680 3680 else:
3681 3681 raise ValueError('Invalid notebook format: %s' % new_format)
3682 3682 with io.open(old_fname, 'r', encoding='utf-8') as f:
3683 3683 nb = current.read(f, old_format)
3684 3684 with io.open(new_fname, 'w', encoding='utf-8') as f:
3685 3685 current.write(nb, f, new_format)
3686 3686
3687 3687 def magic_config(self, s):
3688 3688 """configure IPython
3689 3689
3690 3690 %config Class[.trait=value]
3691 3691
3692 3692 This magic exposes most of the IPython config system. Any
3693 3693 Configurable class should be able to be configured with the simple
3694 3694 line::
3695 3695
3696 3696 %config Class.trait=value
3697 3697
3698 3698 Where `value` will be resolved in the user's namespace, if it is an
3699 3699 expression or variable name.
3700 3700
3701 3701 Examples
3702 3702 --------
3703 3703
3704 3704 To see what classes are available for config, pass no arguments::
3705 3705
3706 3706 In [1]: %config
3707 3707 Available objects for config:
3708 3708 TerminalInteractiveShell
3709 3709 HistoryManager
3710 3710 PrefilterManager
3711 3711 AliasManager
3712 3712 IPCompleter
3713 3713 PromptManager
3714 3714 DisplayFormatter
3715 3715
3716 3716 To view what is configurable on a given class, just pass the class
3717 3717 name::
3718 3718
3719 3719 In [2]: %config IPCompleter
3720 3720 IPCompleter options
3721 3721 -----------------
3722 3722 IPCompleter.omit__names=<Enum>
3723 3723 Current: 2
3724 3724 Choices: (0, 1, 2)
3725 3725 Instruct the completer to omit private method names
3726 3726 Specifically, when completing on ``object.<tab>``.
3727 3727 When 2 [default]: all names that start with '_' will be excluded.
3728 3728 When 1: all 'magic' names (``__foo__``) will be excluded.
3729 3729 When 0: nothing will be excluded.
3730 3730 IPCompleter.merge_completions=<CBool>
3731 3731 Current: True
3732 3732 Whether to merge completion results into a single list
3733 3733 If False, only the completion results from the first non-empty completer
3734 3734 will be returned.
3735 3735 IPCompleter.limit_to__all__=<CBool>
3736 3736 Current: False
3737 3737 Instruct the completer to use __all__ for the completion
3738 3738 Specifically, when completing on ``object.<tab>``.
3739 3739 When True: only those names in obj.__all__ will be included.
3740 3740 When False [default]: the __all__ attribute is ignored
3741 3741 IPCompleter.greedy=<CBool>
3742 3742 Current: False
3743 3743 Activate greedy completion
3744 3744 This will enable completion on elements of lists, results of function calls,
3745 3745 etc., but can be unsafe because the code is actually evaluated on TAB.
3746 3746
3747 3747 but the real use is in setting values::
3748 3748
3749 3749 In [3]: %config IPCompleter.greedy = True
3750 3750
3751 3751 and these values are read from the user_ns if they are variables::
3752 3752
3753 3753 In [4]: feeling_greedy=False
3754 3754
3755 3755 In [5]: %config IPCompleter.greedy = feeling_greedy
3756 3756
3757 3757 """
3758 3758 from IPython.config.loader import Config
3759 3759 # some IPython objects are Configurable, but do not yet have
3760 3760 # any configurable traits. Exclude them from the effects of
3761 3761 # this magic, as their presence is just noise:
3762 3762 configurables = [ c for c in self.configurables if c.__class__.class_traits(config=True) ]
3763 3763 classnames = [ c.__class__.__name__ for c in configurables ]
3764 3764
3765 3765 line = s.strip()
3766 3766 if not line:
3767 3767 # print available configurable names
3768 3768 print "Available objects for config:"
3769 3769 for name in classnames:
3770 3770 print " ", name
3771 3771 return
3772 3772 elif line in classnames:
3773 3773 # `%config TerminalInteractiveShell` will print trait info for
3774 3774 # TerminalInteractiveShell
3775 3775 c = configurables[classnames.index(line)]
3776 3776 cls = c.__class__
3777 3777 help = cls.class_get_help(c)
3778 3778 # strip leading '--' from cl-args:
3779 3779 help = re.sub(re.compile(r'^--', re.MULTILINE), '', help)
3780 3780 print help
3781 3781 return
3782 3782 elif '=' not in line:
3783 3783 raise UsageError("Invalid config statement: %r, should be Class.trait = value" % line)
3784 3784
3785 3785
3786 3786 # otherwise, assume we are setting configurables.
3787 3787 # leave quotes on args when splitting, because we want
3788 3788 # unquoted args to eval in user_ns
3789 3789 cfg = Config()
3790 3790 exec "cfg."+line in locals(), self.user_ns
3791 3791
3792 3792 for configurable in configurables:
3793 3793 try:
3794 3794 configurable.update_config(cfg)
3795 3795 except Exception as e:
3796 3796 error(e)
3797 3797
3798 3798 # end Magic
General Comments 0
You need to be logged in to leave comments. Login now