##// END OF EJS Templates
Create core.magics.auto according to new API.
Fernando Perez -
Show More
@@ -0,0 +1,128 b''
1 """Implementation of execution-related magic functions.
2 """
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
5 #
6 # Distributed under the terms of the Modified BSD License.
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
10
11 #-----------------------------------------------------------------------------
12 # Imports
13 #-----------------------------------------------------------------------------
14
15 # Our own packages
16 from IPython.core.magic import Bunch, Magics, register_magics, line_magic
17 from IPython.testing.skipdoctest import skip_doctest
18 from IPython.utils.warn import error
19
20 #-----------------------------------------------------------------------------
21 # Magic implementation classes
22 #-----------------------------------------------------------------------------
23
24 @register_magics
25 class AutoMagics(Magics):
26 """Magics that control various autoX behaviors."""
27
28 def __init__(self, shell):
29 super(AutoMagics, self).__init__(shell)
30 # namespace for holding state we may need
31 self._magic_state = Bunch()
32
33 @line_magic
34 def automagic(self, parameter_s=''):
35 """Make magic functions callable without having to type the initial %.
36
37 Without argumentsl toggles on/off (when off, you must call it as
38 %automagic, of course). With arguments it sets the value, and you can
39 use any of (case insensitive):
40
41 - on, 1, True: to activate
42
43 - off, 0, False: to deactivate.
44
45 Note that magic functions have lowest priority, so if there's a
46 variable whose name collides with that of a magic fn, automagic won't
47 work for that function (you get the variable instead). However, if you
48 delete the variable (del var), the previously shadowed magic function
49 becomes visible to automagic again."""
50
51 arg = parameter_s.lower()
52 mman = self.shell.magics_manager
53 if arg in ('on', '1', 'true'):
54 val = True
55 elif arg in ('off', '0', 'false'):
56 val = False
57 else:
58 val = not mman.auto_magic
59 mman.auto_magic = val
60 print '\n' + self.shell.magics_manager.auto_status()
61
62 @skip_doctest
63 @line_magic
64 def autocall(self, parameter_s=''):
65 """Make functions callable without having to type parentheses.
66
67 Usage:
68
69 %autocall [mode]
70
71 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
72 value is toggled on and off (remembering the previous state).
73
74 In more detail, these values mean:
75
76 0 -> fully disabled
77
78 1 -> active, but do not apply if there are no arguments on the line.
79
80 In this mode, you get::
81
82 In [1]: callable
83 Out[1]: <built-in function callable>
84
85 In [2]: callable 'hello'
86 ------> callable('hello')
87 Out[2]: False
88
89 2 -> Active always. Even if no arguments are present, the callable
90 object is called::
91
92 In [2]: float
93 ------> float()
94 Out[2]: 0.0
95
96 Note that even with autocall off, you can still use '/' at the start of
97 a line to treat the first argument on the command line as a function
98 and add parentheses to it::
99
100 In [8]: /str 43
101 ------> str(43)
102 Out[8]: '43'
103
104 # all-random (note for auto-testing)
105 """
106
107 if parameter_s:
108 arg = int(parameter_s)
109 else:
110 arg = 'toggle'
111
112 if not arg in (0, 1, 2,'toggle'):
113 error('Valid modes: (0->Off, 1->Smart, 2->Full')
114 return
115
116 if arg in (0, 1, 2):
117 self.shell.autocall = arg
118 else: # toggle
119 if self.shell.autocall:
120 self._magic_state.autocall_save = self.shell.autocall
121 self.shell.autocall = 0
122 else:
123 try:
124 self.shell.autocall = self._magic_state.autocall_save
125 except AttributeError:
126 self.shell.autocall = self._magic_state.autocall_save = 1
127
128 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
@@ -1,2951 +1,2951 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Main IPython class."""
3 3
4 4 #-----------------------------------------------------------------------------
5 5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 7 # Copyright (C) 2008-2011 The IPython Development Team
8 8 #
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #-----------------------------------------------------------------------------
12 12
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16
17 17 from __future__ import with_statement
18 18 from __future__ import absolute_import
19 19
20 20 import __builtin__ as builtin_mod
21 21 import __future__
22 22 import abc
23 23 import ast
24 24 import atexit
25 25 import os
26 26 import re
27 27 import runpy
28 28 import sys
29 29 import tempfile
30 30 import types
31 31 import urllib
32 32 from io import open as io_open
33 33
34 34 from IPython.config.configurable import SingletonConfigurable
35 35 from IPython.core import debugger, oinspect
36 36 from IPython.core import history as ipcorehist
37 37 from IPython.core import magic
38 38 from IPython.core import page
39 39 from IPython.core import prefilter
40 40 from IPython.core import shadowns
41 41 from IPython.core import ultratb
42 42 from IPython.core.alias import AliasManager, AliasError
43 43 from IPython.core.autocall import ExitAutocall
44 44 from IPython.core.builtin_trap import BuiltinTrap
45 45 from IPython.core.compilerop import CachingCompiler
46 46 from IPython.core.display_trap import DisplayTrap
47 47 from IPython.core.displayhook import DisplayHook
48 48 from IPython.core.displaypub import DisplayPublisher
49 49 from IPython.core.error import UsageError
50 50 from IPython.core.extensions import ExtensionManager
51 51 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
52 52 from IPython.core.formatters import DisplayFormatter
53 53 from IPython.core.history import HistoryManager
54 54 from IPython.core.inputsplitter import IPythonInputSplitter
55 55 from IPython.core.logger import Logger
56 56 from IPython.core.macro import Macro
57 57 from IPython.core.payload import PayloadManager
58 58 from IPython.core.plugin import PluginManager
59 59 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
60 60 from IPython.core.profiledir import ProfileDir
61 61 from IPython.core.pylabtools import pylab_activate
62 62 from IPython.core.prompts import PromptManager
63 63 from IPython.utils import PyColorize
64 64 from IPython.utils import io
65 65 from IPython.utils import py3compat
66 66 from IPython.utils import openpy
67 67 from IPython.utils.doctestreload import doctest_reload
68 68 from IPython.utils.io import ask_yes_no
69 69 from IPython.utils.ipstruct import Struct
70 70 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
71 71 from IPython.utils.pickleshare import PickleShareDB
72 72 from IPython.utils.process import system, getoutput
73 73 from IPython.utils.strdispatch import StrDispatch
74 74 from IPython.utils.syspathcontext import prepended_to_syspath
75 75 from IPython.utils.text import (format_screen, LSString, SList,
76 76 DollarFormatter)
77 77 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
78 78 List, Unicode, Instance, Type)
79 79 from IPython.utils.warn import warn, error
80 80 import IPython.core.hooks
81 81
82 82 #-----------------------------------------------------------------------------
83 83 # Globals
84 84 #-----------------------------------------------------------------------------
85 85
86 86 # compiled regexps for autoindent management
87 87 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
88 88
89 89 #-----------------------------------------------------------------------------
90 90 # Utilities
91 91 #-----------------------------------------------------------------------------
92 92
93 93 def softspace(file, newvalue):
94 94 """Copied from code.py, to remove the dependency"""
95 95
96 96 oldvalue = 0
97 97 try:
98 98 oldvalue = file.softspace
99 99 except AttributeError:
100 100 pass
101 101 try:
102 102 file.softspace = newvalue
103 103 except (AttributeError, TypeError):
104 104 # "attribute-less object" or "read-only attributes"
105 105 pass
106 106 return oldvalue
107 107
108 108
109 109 def no_op(*a, **kw): pass
110 110
111 111 class NoOpContext(object):
112 112 def __enter__(self): pass
113 113 def __exit__(self, type, value, traceback): pass
114 114 no_op_context = NoOpContext()
115 115
116 116 class SpaceInInput(Exception): pass
117 117
118 118 class Bunch: pass
119 119
120 120
121 121 def get_default_colors():
122 122 if sys.platform=='darwin':
123 123 return "LightBG"
124 124 elif os.name=='nt':
125 125 return 'Linux'
126 126 else:
127 127 return 'Linux'
128 128
129 129
130 130 class SeparateUnicode(Unicode):
131 131 """A Unicode subclass to validate separate_in, separate_out, etc.
132 132
133 133 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
134 134 """
135 135
136 136 def validate(self, obj, value):
137 137 if value == '0': value = ''
138 138 value = value.replace('\\n','\n')
139 139 return super(SeparateUnicode, self).validate(obj, value)
140 140
141 141
142 142 class ReadlineNoRecord(object):
143 143 """Context manager to execute some code, then reload readline history
144 144 so that interactive input to the code doesn't appear when pressing up."""
145 145 def __init__(self, shell):
146 146 self.shell = shell
147 147 self._nested_level = 0
148 148
149 149 def __enter__(self):
150 150 if self._nested_level == 0:
151 151 try:
152 152 self.orig_length = self.current_length()
153 153 self.readline_tail = self.get_readline_tail()
154 154 except (AttributeError, IndexError): # Can fail with pyreadline
155 155 self.orig_length, self.readline_tail = 999999, []
156 156 self._nested_level += 1
157 157
158 158 def __exit__(self, type, value, traceback):
159 159 self._nested_level -= 1
160 160 if self._nested_level == 0:
161 161 # Try clipping the end if it's got longer
162 162 try:
163 163 e = self.current_length() - self.orig_length
164 164 if e > 0:
165 165 for _ in range(e):
166 166 self.shell.readline.remove_history_item(self.orig_length)
167 167
168 168 # If it still doesn't match, just reload readline history.
169 169 if self.current_length() != self.orig_length \
170 170 or self.get_readline_tail() != self.readline_tail:
171 171 self.shell.refill_readline_hist()
172 172 except (AttributeError, IndexError):
173 173 pass
174 174 # Returning False will cause exceptions to propagate
175 175 return False
176 176
177 177 def current_length(self):
178 178 return self.shell.readline.get_current_history_length()
179 179
180 180 def get_readline_tail(self, n=10):
181 181 """Get the last n items in readline history."""
182 182 end = self.shell.readline.get_current_history_length() + 1
183 183 start = max(end-n, 1)
184 184 ghi = self.shell.readline.get_history_item
185 185 return [ghi(x) for x in range(start, end)]
186 186
187 187 #-----------------------------------------------------------------------------
188 188 # Main IPython class
189 189 #-----------------------------------------------------------------------------
190 190
191 191 class InteractiveShell(SingletonConfigurable):
192 192 """An enhanced, interactive shell for Python."""
193 193
194 194 _instance = None
195 195
196 196 autocall = Enum((0,1,2), default_value=0, config=True, help=
197 197 """
198 198 Make IPython automatically call any callable object even if you didn't
199 199 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
200 200 automatically. The value can be '0' to disable the feature, '1' for
201 201 'smart' autocall, where it is not applied if there are no more
202 202 arguments on the line, and '2' for 'full' autocall, where all callable
203 203 objects are automatically called (even if no arguments are present).
204 204 """
205 205 )
206 206 # TODO: remove all autoindent logic and put into frontends.
207 207 # We can't do this yet because even runlines uses the autoindent.
208 208 autoindent = CBool(True, config=True, help=
209 209 """
210 210 Autoindent IPython code entered interactively.
211 211 """
212 212 )
213 213 automagic = CBool(True, config=True, help=
214 214 """
215 215 Enable magic commands to be called without the leading %.
216 216 """
217 217 )
218 218 cache_size = Integer(1000, config=True, help=
219 219 """
220 220 Set the size of the output cache. The default is 1000, you can
221 221 change it permanently in your config file. Setting it to 0 completely
222 222 disables the caching system, and the minimum value accepted is 20 (if
223 223 you provide a value less than 20, it is reset to 0 and a warning is
224 224 issued). This limit is defined because otherwise you'll spend more
225 225 time re-flushing a too small cache than working
226 226 """
227 227 )
228 228 color_info = CBool(True, config=True, help=
229 229 """
230 230 Use colors for displaying information about objects. Because this
231 231 information is passed through a pager (like 'less'), and some pagers
232 232 get confused with color codes, this capability can be turned off.
233 233 """
234 234 )
235 235 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
236 236 default_value=get_default_colors(), config=True,
237 237 help="Set the color scheme (NoColor, Linux, or LightBG)."
238 238 )
239 239 colors_force = CBool(False, help=
240 240 """
241 241 Force use of ANSI color codes, regardless of OS and readline
242 242 availability.
243 243 """
244 244 # FIXME: This is essentially a hack to allow ZMQShell to show colors
245 245 # without readline on Win32. When the ZMQ formatting system is
246 246 # refactored, this should be removed.
247 247 )
248 248 debug = CBool(False, config=True)
249 249 deep_reload = CBool(False, config=True, help=
250 250 """
251 251 Enable deep (recursive) reloading by default. IPython can use the
252 252 deep_reload module which reloads changes in modules recursively (it
253 253 replaces the reload() function, so you don't need to change anything to
254 254 use it). deep_reload() forces a full reload of modules whose code may
255 255 have changed, which the default reload() function does not. When
256 256 deep_reload is off, IPython will use the normal reload(), but
257 257 deep_reload will still be available as dreload().
258 258 """
259 259 )
260 260 disable_failing_post_execute = CBool(False, config=True,
261 261 help="Don't call post-execute functions that have failed in the past."""
262 262 )
263 263 display_formatter = Instance(DisplayFormatter)
264 264 displayhook_class = Type(DisplayHook)
265 265 display_pub_class = Type(DisplayPublisher)
266 266
267 267 exit_now = CBool(False)
268 268 exiter = Instance(ExitAutocall)
269 269 def _exiter_default(self):
270 270 return ExitAutocall(self)
271 271 # Monotonically increasing execution counter
272 272 execution_count = Integer(1)
273 273 filename = Unicode("<ipython console>")
274 274 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
275 275
276 276 # Input splitter, to split entire cells of input into either individual
277 277 # interactive statements or whole blocks.
278 278 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
279 279 (), {})
280 280 logstart = CBool(False, config=True, help=
281 281 """
282 282 Start logging to the default log file.
283 283 """
284 284 )
285 285 logfile = Unicode('', config=True, help=
286 286 """
287 287 The name of the logfile to use.
288 288 """
289 289 )
290 290 logappend = Unicode('', config=True, help=
291 291 """
292 292 Start logging to the given file in append mode.
293 293 """
294 294 )
295 295 object_info_string_level = Enum((0,1,2), default_value=0,
296 296 config=True)
297 297 pdb = CBool(False, config=True, help=
298 298 """
299 299 Automatically call the pdb debugger after every exception.
300 300 """
301 301 )
302 302 multiline_history = CBool(sys.platform != 'win32', config=True,
303 303 help="Save multi-line entries as one entry in readline history"
304 304 )
305 305
306 306 # deprecated prompt traits:
307 307
308 308 prompt_in1 = Unicode('In [\\#]: ', config=True,
309 309 help="Deprecated, use PromptManager.in_template")
310 310 prompt_in2 = Unicode(' .\\D.: ', config=True,
311 311 help="Deprecated, use PromptManager.in2_template")
312 312 prompt_out = Unicode('Out[\\#]: ', config=True,
313 313 help="Deprecated, use PromptManager.out_template")
314 314 prompts_pad_left = CBool(True, config=True,
315 315 help="Deprecated, use PromptManager.justify")
316 316
317 317 def _prompt_trait_changed(self, name, old, new):
318 318 table = {
319 319 'prompt_in1' : 'in_template',
320 320 'prompt_in2' : 'in2_template',
321 321 'prompt_out' : 'out_template',
322 322 'prompts_pad_left' : 'justify',
323 323 }
324 324 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}\n".format(
325 325 name=name, newname=table[name])
326 326 )
327 327 # protect against weird cases where self.config may not exist:
328 328 if self.config is not None:
329 329 # propagate to corresponding PromptManager trait
330 330 setattr(self.config.PromptManager, table[name], new)
331 331
332 332 _prompt_in1_changed = _prompt_trait_changed
333 333 _prompt_in2_changed = _prompt_trait_changed
334 334 _prompt_out_changed = _prompt_trait_changed
335 335 _prompt_pad_left_changed = _prompt_trait_changed
336 336
337 337 show_rewritten_input = CBool(True, config=True,
338 338 help="Show rewritten input, e.g. for autocall."
339 339 )
340 340
341 341 quiet = CBool(False, config=True)
342 342
343 343 history_length = Integer(10000, config=True)
344 344
345 345 # The readline stuff will eventually be moved to the terminal subclass
346 346 # but for now, we can't do that as readline is welded in everywhere.
347 347 readline_use = CBool(True, config=True)
348 348 readline_remove_delims = Unicode('-/~', config=True)
349 349 # don't use \M- bindings by default, because they
350 350 # conflict with 8-bit encodings. See gh-58,gh-88
351 351 readline_parse_and_bind = List([
352 352 'tab: complete',
353 353 '"\C-l": clear-screen',
354 354 'set show-all-if-ambiguous on',
355 355 '"\C-o": tab-insert',
356 356 '"\C-r": reverse-search-history',
357 357 '"\C-s": forward-search-history',
358 358 '"\C-p": history-search-backward',
359 359 '"\C-n": history-search-forward',
360 360 '"\e[A": history-search-backward',
361 361 '"\e[B": history-search-forward',
362 362 '"\C-k": kill-line',
363 363 '"\C-u": unix-line-discard',
364 364 ], allow_none=False, config=True)
365 365
366 366 # TODO: this part of prompt management should be moved to the frontends.
367 367 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
368 368 separate_in = SeparateUnicode('\n', config=True)
369 369 separate_out = SeparateUnicode('', config=True)
370 370 separate_out2 = SeparateUnicode('', config=True)
371 371 wildcards_case_sensitive = CBool(True, config=True)
372 372 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
373 373 default_value='Context', config=True)
374 374
375 375 # Subcomponents of InteractiveShell
376 376 alias_manager = Instance('IPython.core.alias.AliasManager')
377 377 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
378 378 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
379 379 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
380 380 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
381 381 plugin_manager = Instance('IPython.core.plugin.PluginManager')
382 382 payload_manager = Instance('IPython.core.payload.PayloadManager')
383 383 history_manager = Instance('IPython.core.history.HistoryManager')
384 384 magics_manager = Instance('IPython.core.magic.MagicsManager')
385 385
386 386 profile_dir = Instance('IPython.core.application.ProfileDir')
387 387 @property
388 388 def profile(self):
389 389 if self.profile_dir is not None:
390 390 name = os.path.basename(self.profile_dir.location)
391 391 return name.replace('profile_','')
392 392
393 393
394 394 # Private interface
395 395 _post_execute = Instance(dict)
396 396
397 397 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
398 398 user_module=None, user_ns=None,
399 399 custom_exceptions=((), None)):
400 400
401 401 # This is where traits with a config_key argument are updated
402 402 # from the values on config.
403 403 super(InteractiveShell, self).__init__(config=config)
404 404 self.configurables = [self]
405 405
406 406 # These are relatively independent and stateless
407 407 self.init_ipython_dir(ipython_dir)
408 408 self.init_profile_dir(profile_dir)
409 409 self.init_instance_attrs()
410 410 self.init_environment()
411 411
412 412 # Check if we're in a virtualenv, and set up sys.path.
413 413 self.init_virtualenv()
414 414
415 415 # Create namespaces (user_ns, user_global_ns, etc.)
416 416 self.init_create_namespaces(user_module, user_ns)
417 417 # This has to be done after init_create_namespaces because it uses
418 418 # something in self.user_ns, but before init_sys_modules, which
419 419 # is the first thing to modify sys.
420 420 # TODO: When we override sys.stdout and sys.stderr before this class
421 421 # is created, we are saving the overridden ones here. Not sure if this
422 422 # is what we want to do.
423 423 self.save_sys_module_state()
424 424 self.init_sys_modules()
425 425
426 426 # While we're trying to have each part of the code directly access what
427 427 # it needs without keeping redundant references to objects, we have too
428 428 # much legacy code that expects ip.db to exist.
429 429 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
430 430
431 431 self.init_history()
432 432 self.init_encoding()
433 433 self.init_prefilter()
434 434
435 435 self.init_syntax_highlighting()
436 436 self.init_hooks()
437 437 self.init_pushd_popd_magic()
438 438 # self.init_traceback_handlers use to be here, but we moved it below
439 439 # because it and init_io have to come after init_readline.
440 440 self.init_user_ns()
441 441 self.init_logger()
442 442 self.init_alias()
443 443 self.init_builtins()
444 444
445 445 # pre_config_initialization
446 446
447 447 # The next section should contain everything that was in ipmaker.
448 448 self.init_logstart()
449 449
450 450 # The following was in post_config_initialization
451 451 self.init_inspector()
452 452 # init_readline() must come before init_io(), because init_io uses
453 453 # readline related things.
454 454 self.init_readline()
455 455 # We save this here in case user code replaces raw_input, but it needs
456 456 # to be after init_readline(), because PyPy's readline works by replacing
457 457 # raw_input.
458 458 if py3compat.PY3:
459 459 self.raw_input_original = input
460 460 else:
461 461 self.raw_input_original = raw_input
462 462 # init_completer must come after init_readline, because it needs to
463 463 # know whether readline is present or not system-wide to configure the
464 464 # completers, since the completion machinery can now operate
465 465 # independently of readline (e.g. over the network)
466 466 self.init_completer()
467 467 # TODO: init_io() needs to happen before init_traceback handlers
468 468 # because the traceback handlers hardcode the stdout/stderr streams.
469 469 # This logic in in debugger.Pdb and should eventually be changed.
470 470 self.init_io()
471 471 self.init_traceback_handlers(custom_exceptions)
472 472 self.init_prompts()
473 473 self.init_display_formatter()
474 474 self.init_display_pub()
475 475 self.init_displayhook()
476 476 self.init_reload_doctest()
477 477 self.init_magics()
478 478 self.init_pdb()
479 479 self.init_extension_manager()
480 480 self.init_plugin_manager()
481 481 self.init_payload()
482 482 self.hooks.late_startup_hook()
483 483 atexit.register(self.atexit_operations)
484 484
485 485 def get_ipython(self):
486 486 """Return the currently running IPython instance."""
487 487 return self
488 488
489 489 #-------------------------------------------------------------------------
490 490 # Trait changed handlers
491 491 #-------------------------------------------------------------------------
492 492
493 493 def _ipython_dir_changed(self, name, new):
494 494 if not os.path.isdir(new):
495 495 os.makedirs(new, mode = 0777)
496 496
497 497 def set_autoindent(self,value=None):
498 498 """Set the autoindent flag, checking for readline support.
499 499
500 500 If called with no arguments, it acts as a toggle."""
501 501
502 502 if value != 0 and not self.has_readline:
503 503 if os.name == 'posix':
504 504 warn("The auto-indent feature requires the readline library")
505 505 self.autoindent = 0
506 506 return
507 507 if value is None:
508 508 self.autoindent = not self.autoindent
509 509 else:
510 510 self.autoindent = value
511 511
512 512 #-------------------------------------------------------------------------
513 513 # init_* methods called by __init__
514 514 #-------------------------------------------------------------------------
515 515
516 516 def init_ipython_dir(self, ipython_dir):
517 517 if ipython_dir is not None:
518 518 self.ipython_dir = ipython_dir
519 519 return
520 520
521 521 self.ipython_dir = get_ipython_dir()
522 522
523 523 def init_profile_dir(self, profile_dir):
524 524 if profile_dir is not None:
525 525 self.profile_dir = profile_dir
526 526 return
527 527 self.profile_dir =\
528 528 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
529 529
530 530 def init_instance_attrs(self):
531 531 self.more = False
532 532
533 533 # command compiler
534 534 self.compile = CachingCompiler()
535 535
536 536 # Make an empty namespace, which extension writers can rely on both
537 537 # existing and NEVER being used by ipython itself. This gives them a
538 538 # convenient location for storing additional information and state
539 539 # their extensions may require, without fear of collisions with other
540 540 # ipython names that may develop later.
541 541 self.meta = Struct()
542 542
543 543 # Temporary files used for various purposes. Deleted at exit.
544 544 self.tempfiles = []
545 545
546 546 # Keep track of readline usage (later set by init_readline)
547 547 self.has_readline = False
548 548
549 549 # keep track of where we started running (mainly for crash post-mortem)
550 550 # This is not being used anywhere currently.
551 551 self.starting_dir = os.getcwdu()
552 552
553 553 # Indentation management
554 554 self.indent_current_nsp = 0
555 555
556 556 # Dict to track post-execution functions that have been registered
557 557 self._post_execute = {}
558 558
559 559 def init_environment(self):
560 560 """Any changes we need to make to the user's environment."""
561 561 pass
562 562
563 563 def init_encoding(self):
564 564 # Get system encoding at startup time. Certain terminals (like Emacs
565 565 # under Win32 have it set to None, and we need to have a known valid
566 566 # encoding to use in the raw_input() method
567 567 try:
568 568 self.stdin_encoding = sys.stdin.encoding or 'ascii'
569 569 except AttributeError:
570 570 self.stdin_encoding = 'ascii'
571 571
572 572 def init_syntax_highlighting(self):
573 573 # Python source parser/formatter for syntax highlighting
574 574 pyformat = PyColorize.Parser().format
575 575 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
576 576
577 577 def init_pushd_popd_magic(self):
578 578 # for pushd/popd management
579 579 self.home_dir = get_home_dir()
580 580
581 581 self.dir_stack = []
582 582
583 583 def init_logger(self):
584 584 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
585 585 logmode='rotate')
586 586
587 587 def init_logstart(self):
588 588 """Initialize logging in case it was requested at the command line.
589 589 """
590 590 if self.logappend:
591 591 self.magic('logstart %s append' % self.logappend)
592 592 elif self.logfile:
593 593 self.magic('logstart %' % self.logfile)
594 594 elif self.logstart:
595 595 self.magic('logstart')
596 596
597 597 def init_builtins(self):
598 598 # A single, static flag that we set to True. Its presence indicates
599 599 # that an IPython shell has been created, and we make no attempts at
600 600 # removing on exit or representing the existence of more than one
601 601 # IPython at a time.
602 602 builtin_mod.__dict__['__IPYTHON__'] = True
603 603
604 604 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
605 605 # manage on enter/exit, but with all our shells it's virtually
606 606 # impossible to get all the cases right. We're leaving the name in for
607 607 # those who adapted their codes to check for this flag, but will
608 608 # eventually remove it after a few more releases.
609 609 builtin_mod.__dict__['__IPYTHON__active'] = \
610 610 'Deprecated, check for __IPYTHON__'
611 611
612 612 self.builtin_trap = BuiltinTrap(shell=self)
613 613
614 614 def init_inspector(self):
615 615 # Object inspector
616 616 self.inspector = oinspect.Inspector(oinspect.InspectColors,
617 617 PyColorize.ANSICodeColors,
618 618 'NoColor',
619 619 self.object_info_string_level)
620 620
621 621 def init_io(self):
622 622 # This will just use sys.stdout and sys.stderr. If you want to
623 623 # override sys.stdout and sys.stderr themselves, you need to do that
624 624 # *before* instantiating this class, because io holds onto
625 625 # references to the underlying streams.
626 626 if sys.platform == 'win32' and self.has_readline:
627 627 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
628 628 else:
629 629 io.stdout = io.IOStream(sys.stdout)
630 630 io.stderr = io.IOStream(sys.stderr)
631 631
632 632 def init_prompts(self):
633 633 self.prompt_manager = PromptManager(shell=self, config=self.config)
634 634 self.configurables.append(self.prompt_manager)
635 635 # Set system prompts, so that scripts can decide if they are running
636 636 # interactively.
637 637 sys.ps1 = 'In : '
638 638 sys.ps2 = '...: '
639 639 sys.ps3 = 'Out: '
640 640
641 641 def init_display_formatter(self):
642 642 self.display_formatter = DisplayFormatter(config=self.config)
643 643 self.configurables.append(self.display_formatter)
644 644
645 645 def init_display_pub(self):
646 646 self.display_pub = self.display_pub_class(config=self.config)
647 647 self.configurables.append(self.display_pub)
648 648
649 649 def init_displayhook(self):
650 650 # Initialize displayhook, set in/out prompts and printing system
651 651 self.displayhook = self.displayhook_class(
652 652 config=self.config,
653 653 shell=self,
654 654 cache_size=self.cache_size,
655 655 )
656 656 self.configurables.append(self.displayhook)
657 657 # This is a context manager that installs/revmoes the displayhook at
658 658 # the appropriate time.
659 659 self.display_trap = DisplayTrap(hook=self.displayhook)
660 660
661 661 def init_reload_doctest(self):
662 662 # Do a proper resetting of doctest, including the necessary displayhook
663 663 # monkeypatching
664 664 try:
665 665 doctest_reload()
666 666 except ImportError:
667 667 warn("doctest module does not exist.")
668 668
669 669 def init_virtualenv(self):
670 670 """Add a virtualenv to sys.path so the user can import modules from it.
671 671 This isn't perfect: it doesn't use the Python interpreter with which the
672 672 virtualenv was built, and it ignores the --no-site-packages option. A
673 673 warning will appear suggesting the user installs IPython in the
674 674 virtualenv, but for many cases, it probably works well enough.
675 675
676 676 Adapted from code snippets online.
677 677
678 678 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
679 679 """
680 680 if 'VIRTUAL_ENV' not in os.environ:
681 681 # Not in a virtualenv
682 682 return
683 683
684 684 if sys.executable.startswith(os.environ['VIRTUAL_ENV']):
685 685 # Running properly in the virtualenv, don't need to do anything
686 686 return
687 687
688 688 warn("Attempting to work in a virtualenv. If you encounter problems, please "
689 689 "install IPython inside the virtualenv.\n")
690 690 if sys.platform == "win32":
691 691 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
692 692 else:
693 693 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
694 694 'python%d.%d' % sys.version_info[:2], 'site-packages')
695 695
696 696 import site
697 697 sys.path.insert(0, virtual_env)
698 698 site.addsitedir(virtual_env)
699 699
700 700 #-------------------------------------------------------------------------
701 701 # Things related to injections into the sys module
702 702 #-------------------------------------------------------------------------
703 703
704 704 def save_sys_module_state(self):
705 705 """Save the state of hooks in the sys module.
706 706
707 707 This has to be called after self.user_module is created.
708 708 """
709 709 self._orig_sys_module_state = {}
710 710 self._orig_sys_module_state['stdin'] = sys.stdin
711 711 self._orig_sys_module_state['stdout'] = sys.stdout
712 712 self._orig_sys_module_state['stderr'] = sys.stderr
713 713 self._orig_sys_module_state['excepthook'] = sys.excepthook
714 714 self._orig_sys_modules_main_name = self.user_module.__name__
715 715 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
716 716
717 717 def restore_sys_module_state(self):
718 718 """Restore the state of the sys module."""
719 719 try:
720 720 for k, v in self._orig_sys_module_state.iteritems():
721 721 setattr(sys, k, v)
722 722 except AttributeError:
723 723 pass
724 724 # Reset what what done in self.init_sys_modules
725 725 if self._orig_sys_modules_main_mod is not None:
726 726 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
727 727
728 728 #-------------------------------------------------------------------------
729 729 # Things related to hooks
730 730 #-------------------------------------------------------------------------
731 731
732 732 def init_hooks(self):
733 733 # hooks holds pointers used for user-side customizations
734 734 self.hooks = Struct()
735 735
736 736 self.strdispatchers = {}
737 737
738 738 # Set all default hooks, defined in the IPython.hooks module.
739 739 hooks = IPython.core.hooks
740 740 for hook_name in hooks.__all__:
741 741 # default hooks have priority 100, i.e. low; user hooks should have
742 742 # 0-100 priority
743 743 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
744 744
745 745 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
746 746 """set_hook(name,hook) -> sets an internal IPython hook.
747 747
748 748 IPython exposes some of its internal API as user-modifiable hooks. By
749 749 adding your function to one of these hooks, you can modify IPython's
750 750 behavior to call at runtime your own routines."""
751 751
752 752 # At some point in the future, this should validate the hook before it
753 753 # accepts it. Probably at least check that the hook takes the number
754 754 # of args it's supposed to.
755 755
756 756 f = types.MethodType(hook,self)
757 757
758 758 # check if the hook is for strdispatcher first
759 759 if str_key is not None:
760 760 sdp = self.strdispatchers.get(name, StrDispatch())
761 761 sdp.add_s(str_key, f, priority )
762 762 self.strdispatchers[name] = sdp
763 763 return
764 764 if re_key is not None:
765 765 sdp = self.strdispatchers.get(name, StrDispatch())
766 766 sdp.add_re(re.compile(re_key), f, priority )
767 767 self.strdispatchers[name] = sdp
768 768 return
769 769
770 770 dp = getattr(self.hooks, name, None)
771 771 if name not in IPython.core.hooks.__all__:
772 772 print "Warning! Hook '%s' is not one of %s" % \
773 773 (name, IPython.core.hooks.__all__ )
774 774 if not dp:
775 775 dp = IPython.core.hooks.CommandChainDispatcher()
776 776
777 777 try:
778 778 dp.add(f,priority)
779 779 except AttributeError:
780 780 # it was not commandchain, plain old func - replace
781 781 dp = f
782 782
783 783 setattr(self.hooks,name, dp)
784 784
785 785 def register_post_execute(self, func):
786 786 """Register a function for calling after code execution.
787 787 """
788 788 if not callable(func):
789 789 raise ValueError('argument %s must be callable' % func)
790 790 self._post_execute[func] = True
791 791
792 792 #-------------------------------------------------------------------------
793 793 # Things related to the "main" module
794 794 #-------------------------------------------------------------------------
795 795
796 796 def new_main_mod(self,ns=None):
797 797 """Return a new 'main' module object for user code execution.
798 798 """
799 799 main_mod = self._user_main_module
800 800 init_fakemod_dict(main_mod,ns)
801 801 return main_mod
802 802
803 803 def cache_main_mod(self,ns,fname):
804 804 """Cache a main module's namespace.
805 805
806 806 When scripts are executed via %run, we must keep a reference to the
807 807 namespace of their __main__ module (a FakeModule instance) around so
808 808 that Python doesn't clear it, rendering objects defined therein
809 809 useless.
810 810
811 811 This method keeps said reference in a private dict, keyed by the
812 812 absolute path of the module object (which corresponds to the script
813 813 path). This way, for multiple executions of the same script we only
814 814 keep one copy of the namespace (the last one), thus preventing memory
815 815 leaks from old references while allowing the objects from the last
816 816 execution to be accessible.
817 817
818 818 Note: we can not allow the actual FakeModule instances to be deleted,
819 819 because of how Python tears down modules (it hard-sets all their
820 820 references to None without regard for reference counts). This method
821 821 must therefore make a *copy* of the given namespace, to allow the
822 822 original module's __dict__ to be cleared and reused.
823 823
824 824
825 825 Parameters
826 826 ----------
827 827 ns : a namespace (a dict, typically)
828 828
829 829 fname : str
830 830 Filename associated with the namespace.
831 831
832 832 Examples
833 833 --------
834 834
835 835 In [10]: import IPython
836 836
837 837 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
838 838
839 839 In [12]: IPython.__file__ in _ip._main_ns_cache
840 840 Out[12]: True
841 841 """
842 842 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
843 843
844 844 def clear_main_mod_cache(self):
845 845 """Clear the cache of main modules.
846 846
847 847 Mainly for use by utilities like %reset.
848 848
849 849 Examples
850 850 --------
851 851
852 852 In [15]: import IPython
853 853
854 854 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
855 855
856 856 In [17]: len(_ip._main_ns_cache) > 0
857 857 Out[17]: True
858 858
859 859 In [18]: _ip.clear_main_mod_cache()
860 860
861 861 In [19]: len(_ip._main_ns_cache) == 0
862 862 Out[19]: True
863 863 """
864 864 self._main_ns_cache.clear()
865 865
866 866 #-------------------------------------------------------------------------
867 867 # Things related to debugging
868 868 #-------------------------------------------------------------------------
869 869
870 870 def init_pdb(self):
871 871 # Set calling of pdb on exceptions
872 872 # self.call_pdb is a property
873 873 self.call_pdb = self.pdb
874 874
875 875 def _get_call_pdb(self):
876 876 return self._call_pdb
877 877
878 878 def _set_call_pdb(self,val):
879 879
880 880 if val not in (0,1,False,True):
881 881 raise ValueError,'new call_pdb value must be boolean'
882 882
883 883 # store value in instance
884 884 self._call_pdb = val
885 885
886 886 # notify the actual exception handlers
887 887 self.InteractiveTB.call_pdb = val
888 888
889 889 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
890 890 'Control auto-activation of pdb at exceptions')
891 891
892 892 def debugger(self,force=False):
893 893 """Call the pydb/pdb debugger.
894 894
895 895 Keywords:
896 896
897 897 - force(False): by default, this routine checks the instance call_pdb
898 898 flag and does not actually invoke the debugger if the flag is false.
899 899 The 'force' option forces the debugger to activate even if the flag
900 900 is false.
901 901 """
902 902
903 903 if not (force or self.call_pdb):
904 904 return
905 905
906 906 if not hasattr(sys,'last_traceback'):
907 907 error('No traceback has been produced, nothing to debug.')
908 908 return
909 909
910 910 # use pydb if available
911 911 if debugger.has_pydb:
912 912 from pydb import pm
913 913 else:
914 914 # fallback to our internal debugger
915 915 pm = lambda : self.InteractiveTB.debugger(force=True)
916 916
917 917 with self.readline_no_record:
918 918 pm()
919 919
920 920 #-------------------------------------------------------------------------
921 921 # Things related to IPython's various namespaces
922 922 #-------------------------------------------------------------------------
923 923 default_user_namespaces = True
924 924
925 925 def init_create_namespaces(self, user_module=None, user_ns=None):
926 926 # Create the namespace where the user will operate. user_ns is
927 927 # normally the only one used, and it is passed to the exec calls as
928 928 # the locals argument. But we do carry a user_global_ns namespace
929 929 # given as the exec 'globals' argument, This is useful in embedding
930 930 # situations where the ipython shell opens in a context where the
931 931 # distinction between locals and globals is meaningful. For
932 932 # non-embedded contexts, it is just the same object as the user_ns dict.
933 933
934 934 # FIXME. For some strange reason, __builtins__ is showing up at user
935 935 # level as a dict instead of a module. This is a manual fix, but I
936 936 # should really track down where the problem is coming from. Alex
937 937 # Schmolck reported this problem first.
938 938
939 939 # A useful post by Alex Martelli on this topic:
940 940 # Re: inconsistent value from __builtins__
941 941 # Von: Alex Martelli <aleaxit@yahoo.com>
942 942 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
943 943 # Gruppen: comp.lang.python
944 944
945 945 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
946 946 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
947 947 # > <type 'dict'>
948 948 # > >>> print type(__builtins__)
949 949 # > <type 'module'>
950 950 # > Is this difference in return value intentional?
951 951
952 952 # Well, it's documented that '__builtins__' can be either a dictionary
953 953 # or a module, and it's been that way for a long time. Whether it's
954 954 # intentional (or sensible), I don't know. In any case, the idea is
955 955 # that if you need to access the built-in namespace directly, you
956 956 # should start with "import __builtin__" (note, no 's') which will
957 957 # definitely give you a module. Yeah, it's somewhat confusing:-(.
958 958
959 959 # These routines return a properly built module and dict as needed by
960 960 # the rest of the code, and can also be used by extension writers to
961 961 # generate properly initialized namespaces.
962 962 if (user_ns is not None) or (user_module is not None):
963 963 self.default_user_namespaces = False
964 964 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
965 965
966 966 # A record of hidden variables we have added to the user namespace, so
967 967 # we can list later only variables defined in actual interactive use.
968 968 self.user_ns_hidden = set()
969 969
970 970 # Now that FakeModule produces a real module, we've run into a nasty
971 971 # problem: after script execution (via %run), the module where the user
972 972 # code ran is deleted. Now that this object is a true module (needed
973 973 # so docetst and other tools work correctly), the Python module
974 974 # teardown mechanism runs over it, and sets to None every variable
975 975 # present in that module. Top-level references to objects from the
976 976 # script survive, because the user_ns is updated with them. However,
977 977 # calling functions defined in the script that use other things from
978 978 # the script will fail, because the function's closure had references
979 979 # to the original objects, which are now all None. So we must protect
980 980 # these modules from deletion by keeping a cache.
981 981 #
982 982 # To avoid keeping stale modules around (we only need the one from the
983 983 # last run), we use a dict keyed with the full path to the script, so
984 984 # only the last version of the module is held in the cache. Note,
985 985 # however, that we must cache the module *namespace contents* (their
986 986 # __dict__). Because if we try to cache the actual modules, old ones
987 987 # (uncached) could be destroyed while still holding references (such as
988 988 # those held by GUI objects that tend to be long-lived)>
989 989 #
990 990 # The %reset command will flush this cache. See the cache_main_mod()
991 991 # and clear_main_mod_cache() methods for details on use.
992 992
993 993 # This is the cache used for 'main' namespaces
994 994 self._main_ns_cache = {}
995 995 # And this is the single instance of FakeModule whose __dict__ we keep
996 996 # copying and clearing for reuse on each %run
997 997 self._user_main_module = FakeModule()
998 998
999 999 # A table holding all the namespaces IPython deals with, so that
1000 1000 # introspection facilities can search easily.
1001 1001 self.ns_table = {'user_global':self.user_module.__dict__,
1002 1002 'user_local':self.user_ns,
1003 1003 'builtin':builtin_mod.__dict__
1004 1004 }
1005 1005
1006 1006 @property
1007 1007 def user_global_ns(self):
1008 1008 return self.user_module.__dict__
1009 1009
1010 1010 def prepare_user_module(self, user_module=None, user_ns=None):
1011 1011 """Prepare the module and namespace in which user code will be run.
1012 1012
1013 1013 When IPython is started normally, both parameters are None: a new module
1014 1014 is created automatically, and its __dict__ used as the namespace.
1015 1015
1016 1016 If only user_module is provided, its __dict__ is used as the namespace.
1017 1017 If only user_ns is provided, a dummy module is created, and user_ns
1018 1018 becomes the global namespace. If both are provided (as they may be
1019 1019 when embedding), user_ns is the local namespace, and user_module
1020 1020 provides the global namespace.
1021 1021
1022 1022 Parameters
1023 1023 ----------
1024 1024 user_module : module, optional
1025 1025 The current user module in which IPython is being run. If None,
1026 1026 a clean module will be created.
1027 1027 user_ns : dict, optional
1028 1028 A namespace in which to run interactive commands.
1029 1029
1030 1030 Returns
1031 1031 -------
1032 1032 A tuple of user_module and user_ns, each properly initialised.
1033 1033 """
1034 1034 if user_module is None and user_ns is not None:
1035 1035 user_ns.setdefault("__name__", "__main__")
1036 1036 class DummyMod(object):
1037 1037 "A dummy module used for IPython's interactive namespace."
1038 1038 pass
1039 1039 user_module = DummyMod()
1040 1040 user_module.__dict__ = user_ns
1041 1041
1042 1042 if user_module is None:
1043 1043 user_module = types.ModuleType("__main__",
1044 1044 doc="Automatically created module for IPython interactive environment")
1045 1045
1046 1046 # We must ensure that __builtin__ (without the final 's') is always
1047 1047 # available and pointing to the __builtin__ *module*. For more details:
1048 1048 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1049 1049 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1050 1050 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1051 1051
1052 1052 if user_ns is None:
1053 1053 user_ns = user_module.__dict__
1054 1054
1055 1055 return user_module, user_ns
1056 1056
1057 1057 def init_sys_modules(self):
1058 1058 # We need to insert into sys.modules something that looks like a
1059 1059 # module but which accesses the IPython namespace, for shelve and
1060 1060 # pickle to work interactively. Normally they rely on getting
1061 1061 # everything out of __main__, but for embedding purposes each IPython
1062 1062 # instance has its own private namespace, so we can't go shoving
1063 1063 # everything into __main__.
1064 1064
1065 1065 # note, however, that we should only do this for non-embedded
1066 1066 # ipythons, which really mimic the __main__.__dict__ with their own
1067 1067 # namespace. Embedded instances, on the other hand, should not do
1068 1068 # this because they need to manage the user local/global namespaces
1069 1069 # only, but they live within a 'normal' __main__ (meaning, they
1070 1070 # shouldn't overtake the execution environment of the script they're
1071 1071 # embedded in).
1072 1072
1073 1073 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1074 1074 main_name = self.user_module.__name__
1075 1075 sys.modules[main_name] = self.user_module
1076 1076
1077 1077 def init_user_ns(self):
1078 1078 """Initialize all user-visible namespaces to their minimum defaults.
1079 1079
1080 1080 Certain history lists are also initialized here, as they effectively
1081 1081 act as user namespaces.
1082 1082
1083 1083 Notes
1084 1084 -----
1085 1085 All data structures here are only filled in, they are NOT reset by this
1086 1086 method. If they were not empty before, data will simply be added to
1087 1087 therm.
1088 1088 """
1089 1089 # This function works in two parts: first we put a few things in
1090 1090 # user_ns, and we sync that contents into user_ns_hidden so that these
1091 1091 # initial variables aren't shown by %who. After the sync, we add the
1092 1092 # rest of what we *do* want the user to see with %who even on a new
1093 1093 # session (probably nothing, so theye really only see their own stuff)
1094 1094
1095 1095 # The user dict must *always* have a __builtin__ reference to the
1096 1096 # Python standard __builtin__ namespace, which must be imported.
1097 1097 # This is so that certain operations in prompt evaluation can be
1098 1098 # reliably executed with builtins. Note that we can NOT use
1099 1099 # __builtins__ (note the 's'), because that can either be a dict or a
1100 1100 # module, and can even mutate at runtime, depending on the context
1101 1101 # (Python makes no guarantees on it). In contrast, __builtin__ is
1102 1102 # always a module object, though it must be explicitly imported.
1103 1103
1104 1104 # For more details:
1105 1105 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1106 1106 ns = dict()
1107 1107
1108 1108 # Put 'help' in the user namespace
1109 1109 try:
1110 1110 from site import _Helper
1111 1111 ns['help'] = _Helper()
1112 1112 except ImportError:
1113 1113 warn('help() not available - check site.py')
1114 1114
1115 1115 # make global variables for user access to the histories
1116 1116 ns['_ih'] = self.history_manager.input_hist_parsed
1117 1117 ns['_oh'] = self.history_manager.output_hist
1118 1118 ns['_dh'] = self.history_manager.dir_hist
1119 1119
1120 1120 ns['_sh'] = shadowns
1121 1121
1122 1122 # user aliases to input and output histories. These shouldn't show up
1123 1123 # in %who, as they can have very large reprs.
1124 1124 ns['In'] = self.history_manager.input_hist_parsed
1125 1125 ns['Out'] = self.history_manager.output_hist
1126 1126
1127 1127 # Store myself as the public api!!!
1128 1128 ns['get_ipython'] = self.get_ipython
1129 1129
1130 1130 ns['exit'] = self.exiter
1131 1131 ns['quit'] = self.exiter
1132 1132
1133 1133 # Sync what we've added so far to user_ns_hidden so these aren't seen
1134 1134 # by %who
1135 1135 self.user_ns_hidden.update(ns)
1136 1136
1137 1137 # Anything put into ns now would show up in %who. Think twice before
1138 1138 # putting anything here, as we really want %who to show the user their
1139 1139 # stuff, not our variables.
1140 1140
1141 1141 # Finally, update the real user's namespace
1142 1142 self.user_ns.update(ns)
1143 1143
1144 1144 @property
1145 1145 def all_ns_refs(self):
1146 1146 """Get a list of references to all the namespace dictionaries in which
1147 1147 IPython might store a user-created object.
1148 1148
1149 1149 Note that this does not include the displayhook, which also caches
1150 1150 objects from the output."""
1151 1151 return [self.user_ns, self.user_global_ns,
1152 1152 self._user_main_module.__dict__] + self._main_ns_cache.values()
1153 1153
1154 1154 def reset(self, new_session=True):
1155 1155 """Clear all internal namespaces, and attempt to release references to
1156 1156 user objects.
1157 1157
1158 1158 If new_session is True, a new history session will be opened.
1159 1159 """
1160 1160 # Clear histories
1161 1161 self.history_manager.reset(new_session)
1162 1162 # Reset counter used to index all histories
1163 1163 if new_session:
1164 1164 self.execution_count = 1
1165 1165
1166 1166 # Flush cached output items
1167 1167 if self.displayhook.do_full_cache:
1168 1168 self.displayhook.flush()
1169 1169
1170 1170 # The main execution namespaces must be cleared very carefully,
1171 1171 # skipping the deletion of the builtin-related keys, because doing so
1172 1172 # would cause errors in many object's __del__ methods.
1173 1173 if self.user_ns is not self.user_global_ns:
1174 1174 self.user_ns.clear()
1175 1175 ns = self.user_global_ns
1176 1176 drop_keys = set(ns.keys())
1177 1177 drop_keys.discard('__builtin__')
1178 1178 drop_keys.discard('__builtins__')
1179 1179 drop_keys.discard('__name__')
1180 1180 for k in drop_keys:
1181 1181 del ns[k]
1182 1182
1183 1183 self.user_ns_hidden.clear()
1184 1184
1185 1185 # Restore the user namespaces to minimal usability
1186 1186 self.init_user_ns()
1187 1187
1188 1188 # Restore the default and user aliases
1189 1189 self.alias_manager.clear_aliases()
1190 1190 self.alias_manager.init_aliases()
1191 1191
1192 1192 # Flush the private list of module references kept for script
1193 1193 # execution protection
1194 1194 self.clear_main_mod_cache()
1195 1195
1196 1196 # Clear out the namespace from the last %run
1197 1197 self.new_main_mod()
1198 1198
1199 1199 def del_var(self, varname, by_name=False):
1200 1200 """Delete a variable from the various namespaces, so that, as
1201 1201 far as possible, we're not keeping any hidden references to it.
1202 1202
1203 1203 Parameters
1204 1204 ----------
1205 1205 varname : str
1206 1206 The name of the variable to delete.
1207 1207 by_name : bool
1208 1208 If True, delete variables with the given name in each
1209 1209 namespace. If False (default), find the variable in the user
1210 1210 namespace, and delete references to it.
1211 1211 """
1212 1212 if varname in ('__builtin__', '__builtins__'):
1213 1213 raise ValueError("Refusing to delete %s" % varname)
1214 1214
1215 1215 ns_refs = self.all_ns_refs
1216 1216
1217 1217 if by_name: # Delete by name
1218 1218 for ns in ns_refs:
1219 1219 try:
1220 1220 del ns[varname]
1221 1221 except KeyError:
1222 1222 pass
1223 1223 else: # Delete by object
1224 1224 try:
1225 1225 obj = self.user_ns[varname]
1226 1226 except KeyError:
1227 1227 raise NameError("name '%s' is not defined" % varname)
1228 1228 # Also check in output history
1229 1229 ns_refs.append(self.history_manager.output_hist)
1230 1230 for ns in ns_refs:
1231 1231 to_delete = [n for n, o in ns.iteritems() if o is obj]
1232 1232 for name in to_delete:
1233 1233 del ns[name]
1234 1234
1235 1235 # displayhook keeps extra references, but not in a dictionary
1236 1236 for name in ('_', '__', '___'):
1237 1237 if getattr(self.displayhook, name) is obj:
1238 1238 setattr(self.displayhook, name, None)
1239 1239
1240 1240 def reset_selective(self, regex=None):
1241 1241 """Clear selective variables from internal namespaces based on a
1242 1242 specified regular expression.
1243 1243
1244 1244 Parameters
1245 1245 ----------
1246 1246 regex : string or compiled pattern, optional
1247 1247 A regular expression pattern that will be used in searching
1248 1248 variable names in the users namespaces.
1249 1249 """
1250 1250 if regex is not None:
1251 1251 try:
1252 1252 m = re.compile(regex)
1253 1253 except TypeError:
1254 1254 raise TypeError('regex must be a string or compiled pattern')
1255 1255 # Search for keys in each namespace that match the given regex
1256 1256 # If a match is found, delete the key/value pair.
1257 1257 for ns in self.all_ns_refs:
1258 1258 for var in ns:
1259 1259 if m.search(var):
1260 1260 del ns[var]
1261 1261
1262 1262 def push(self, variables, interactive=True):
1263 1263 """Inject a group of variables into the IPython user namespace.
1264 1264
1265 1265 Parameters
1266 1266 ----------
1267 1267 variables : dict, str or list/tuple of str
1268 1268 The variables to inject into the user's namespace. If a dict, a
1269 1269 simple update is done. If a str, the string is assumed to have
1270 1270 variable names separated by spaces. A list/tuple of str can also
1271 1271 be used to give the variable names. If just the variable names are
1272 1272 give (list/tuple/str) then the variable values looked up in the
1273 1273 callers frame.
1274 1274 interactive : bool
1275 1275 If True (default), the variables will be listed with the ``who``
1276 1276 magic.
1277 1277 """
1278 1278 vdict = None
1279 1279
1280 1280 # We need a dict of name/value pairs to do namespace updates.
1281 1281 if isinstance(variables, dict):
1282 1282 vdict = variables
1283 1283 elif isinstance(variables, (basestring, list, tuple)):
1284 1284 if isinstance(variables, basestring):
1285 1285 vlist = variables.split()
1286 1286 else:
1287 1287 vlist = variables
1288 1288 vdict = {}
1289 1289 cf = sys._getframe(1)
1290 1290 for name in vlist:
1291 1291 try:
1292 1292 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1293 1293 except:
1294 1294 print ('Could not get variable %s from %s' %
1295 1295 (name,cf.f_code.co_name))
1296 1296 else:
1297 1297 raise ValueError('variables must be a dict/str/list/tuple')
1298 1298
1299 1299 # Propagate variables to user namespace
1300 1300 self.user_ns.update(vdict)
1301 1301
1302 1302 # And configure interactive visibility
1303 1303 user_ns_hidden = self.user_ns_hidden
1304 1304 if interactive:
1305 1305 user_ns_hidden.difference_update(vdict)
1306 1306 else:
1307 1307 user_ns_hidden.update(vdict)
1308 1308
1309 1309 def drop_by_id(self, variables):
1310 1310 """Remove a dict of variables from the user namespace, if they are the
1311 1311 same as the values in the dictionary.
1312 1312
1313 1313 This is intended for use by extensions: variables that they've added can
1314 1314 be taken back out if they are unloaded, without removing any that the
1315 1315 user has overwritten.
1316 1316
1317 1317 Parameters
1318 1318 ----------
1319 1319 variables : dict
1320 1320 A dictionary mapping object names (as strings) to the objects.
1321 1321 """
1322 1322 for name, obj in variables.iteritems():
1323 1323 if name in self.user_ns and self.user_ns[name] is obj:
1324 1324 del self.user_ns[name]
1325 1325 self.user_ns_hidden.discard(name)
1326 1326
1327 1327 #-------------------------------------------------------------------------
1328 1328 # Things related to object introspection
1329 1329 #-------------------------------------------------------------------------
1330 1330
1331 1331 def _ofind(self, oname, namespaces=None):
1332 1332 """Find an object in the available namespaces.
1333 1333
1334 1334 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1335 1335
1336 1336 Has special code to detect magic functions.
1337 1337 """
1338 1338 oname = oname.strip()
1339 1339 #print '1- oname: <%r>' % oname # dbg
1340 1340 if not py3compat.isidentifier(oname.lstrip(ESC_MAGIC), dotted=True):
1341 1341 return dict(found=False)
1342 1342
1343 1343 alias_ns = None
1344 1344 if namespaces is None:
1345 1345 # Namespaces to search in:
1346 1346 # Put them in a list. The order is important so that we
1347 1347 # find things in the same order that Python finds them.
1348 1348 namespaces = [ ('Interactive', self.user_ns),
1349 1349 ('Interactive (global)', self.user_global_ns),
1350 1350 ('Python builtin', builtin_mod.__dict__),
1351 1351 ('Alias', self.alias_manager.alias_table),
1352 1352 ]
1353 1353 alias_ns = self.alias_manager.alias_table
1354 1354
1355 1355 # initialize results to 'null'
1356 1356 found = False; obj = None; ospace = None; ds = None;
1357 1357 ismagic = False; isalias = False; parent = None
1358 1358
1359 1359 # We need to special-case 'print', which as of python2.6 registers as a
1360 1360 # function but should only be treated as one if print_function was
1361 1361 # loaded with a future import. In this case, just bail.
1362 1362 if (oname == 'print' and not py3compat.PY3 and not \
1363 1363 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1364 1364 return {'found':found, 'obj':obj, 'namespace':ospace,
1365 1365 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1366 1366
1367 1367 # Look for the given name by splitting it in parts. If the head is
1368 1368 # found, then we look for all the remaining parts as members, and only
1369 1369 # declare success if we can find them all.
1370 1370 oname_parts = oname.split('.')
1371 1371 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1372 1372 for nsname,ns in namespaces:
1373 1373 try:
1374 1374 obj = ns[oname_head]
1375 1375 except KeyError:
1376 1376 continue
1377 1377 else:
1378 1378 #print 'oname_rest:', oname_rest # dbg
1379 1379 for part in oname_rest:
1380 1380 try:
1381 1381 parent = obj
1382 1382 obj = getattr(obj,part)
1383 1383 except:
1384 1384 # Blanket except b/c some badly implemented objects
1385 1385 # allow __getattr__ to raise exceptions other than
1386 1386 # AttributeError, which then crashes IPython.
1387 1387 break
1388 1388 else:
1389 1389 # If we finish the for loop (no break), we got all members
1390 1390 found = True
1391 1391 ospace = nsname
1392 1392 if ns == alias_ns:
1393 1393 isalias = True
1394 1394 break # namespace loop
1395 1395
1396 1396 # Try to see if it's magic
1397 1397 if not found:
1398 1398 if oname.startswith(ESC_MAGIC):
1399 1399 oname = oname[1:]
1400 1400 obj = self.find_magic(oname)
1401 1401 if obj is not None:
1402 1402 found = True
1403 1403 ospace = 'IPython internal'
1404 1404 ismagic = True
1405 1405
1406 1406 # Last try: special-case some literals like '', [], {}, etc:
1407 1407 if not found and oname_head in ["''",'""','[]','{}','()']:
1408 1408 obj = eval(oname_head)
1409 1409 found = True
1410 1410 ospace = 'Interactive'
1411 1411
1412 1412 return {'found':found, 'obj':obj, 'namespace':ospace,
1413 1413 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1414 1414
1415 1415 def _ofind_property(self, oname, info):
1416 1416 """Second part of object finding, to look for property details."""
1417 1417 if info.found:
1418 1418 # Get the docstring of the class property if it exists.
1419 1419 path = oname.split('.')
1420 1420 root = '.'.join(path[:-1])
1421 1421 if info.parent is not None:
1422 1422 try:
1423 1423 target = getattr(info.parent, '__class__')
1424 1424 # The object belongs to a class instance.
1425 1425 try:
1426 1426 target = getattr(target, path[-1])
1427 1427 # The class defines the object.
1428 1428 if isinstance(target, property):
1429 1429 oname = root + '.__class__.' + path[-1]
1430 1430 info = Struct(self._ofind(oname))
1431 1431 except AttributeError: pass
1432 1432 except AttributeError: pass
1433 1433
1434 1434 # We return either the new info or the unmodified input if the object
1435 1435 # hadn't been found
1436 1436 return info
1437 1437
1438 1438 def _object_find(self, oname, namespaces=None):
1439 1439 """Find an object and return a struct with info about it."""
1440 1440 inf = Struct(self._ofind(oname, namespaces))
1441 1441 return Struct(self._ofind_property(oname, inf))
1442 1442
1443 1443 def _inspect(self, meth, oname, namespaces=None, **kw):
1444 1444 """Generic interface to the inspector system.
1445 1445
1446 1446 This function is meant to be called by pdef, pdoc & friends."""
1447 1447 info = self._object_find(oname)
1448 1448 if info.found:
1449 1449 pmethod = getattr(self.inspector, meth)
1450 1450 formatter = format_screen if info.ismagic else None
1451 1451 if meth == 'pdoc':
1452 1452 pmethod(info.obj, oname, formatter)
1453 1453 elif meth == 'pinfo':
1454 1454 pmethod(info.obj, oname, formatter, info, **kw)
1455 1455 else:
1456 1456 pmethod(info.obj, oname)
1457 1457 else:
1458 1458 print 'Object `%s` not found.' % oname
1459 1459 return 'not found' # so callers can take other action
1460 1460
1461 1461 def object_inspect(self, oname, detail_level=0):
1462 1462 with self.builtin_trap:
1463 1463 info = self._object_find(oname)
1464 1464 if info.found:
1465 1465 return self.inspector.info(info.obj, oname, info=info,
1466 1466 detail_level=detail_level
1467 1467 )
1468 1468 else:
1469 1469 return oinspect.object_info(name=oname, found=False)
1470 1470
1471 1471 #-------------------------------------------------------------------------
1472 1472 # Things related to history management
1473 1473 #-------------------------------------------------------------------------
1474 1474
1475 1475 def init_history(self):
1476 1476 """Sets up the command history, and starts regular autosaves."""
1477 1477 self.history_manager = HistoryManager(shell=self, config=self.config)
1478 1478 self.configurables.append(self.history_manager)
1479 1479
1480 1480 #-------------------------------------------------------------------------
1481 1481 # Things related to exception handling and tracebacks (not debugging)
1482 1482 #-------------------------------------------------------------------------
1483 1483
1484 1484 def init_traceback_handlers(self, custom_exceptions):
1485 1485 # Syntax error handler.
1486 1486 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1487 1487
1488 1488 # The interactive one is initialized with an offset, meaning we always
1489 1489 # want to remove the topmost item in the traceback, which is our own
1490 1490 # internal code. Valid modes: ['Plain','Context','Verbose']
1491 1491 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1492 1492 color_scheme='NoColor',
1493 1493 tb_offset = 1,
1494 1494 check_cache=self.compile.check_cache)
1495 1495
1496 1496 # The instance will store a pointer to the system-wide exception hook,
1497 1497 # so that runtime code (such as magics) can access it. This is because
1498 1498 # during the read-eval loop, it may get temporarily overwritten.
1499 1499 self.sys_excepthook = sys.excepthook
1500 1500
1501 1501 # and add any custom exception handlers the user may have specified
1502 1502 self.set_custom_exc(*custom_exceptions)
1503 1503
1504 1504 # Set the exception mode
1505 1505 self.InteractiveTB.set_mode(mode=self.xmode)
1506 1506
1507 1507 def set_custom_exc(self, exc_tuple, handler):
1508 1508 """set_custom_exc(exc_tuple,handler)
1509 1509
1510 1510 Set a custom exception handler, which will be called if any of the
1511 1511 exceptions in exc_tuple occur in the mainloop (specifically, in the
1512 1512 run_code() method).
1513 1513
1514 1514 Parameters
1515 1515 ----------
1516 1516
1517 1517 exc_tuple : tuple of exception classes
1518 1518 A *tuple* of exception classes, for which to call the defined
1519 1519 handler. It is very important that you use a tuple, and NOT A
1520 1520 LIST here, because of the way Python's except statement works. If
1521 1521 you only want to trap a single exception, use a singleton tuple::
1522 1522
1523 1523 exc_tuple == (MyCustomException,)
1524 1524
1525 1525 handler : callable
1526 1526 handler must have the following signature::
1527 1527
1528 1528 def my_handler(self, etype, value, tb, tb_offset=None):
1529 1529 ...
1530 1530 return structured_traceback
1531 1531
1532 1532 Your handler must return a structured traceback (a list of strings),
1533 1533 or None.
1534 1534
1535 1535 This will be made into an instance method (via types.MethodType)
1536 1536 of IPython itself, and it will be called if any of the exceptions
1537 1537 listed in the exc_tuple are caught. If the handler is None, an
1538 1538 internal basic one is used, which just prints basic info.
1539 1539
1540 1540 To protect IPython from crashes, if your handler ever raises an
1541 1541 exception or returns an invalid result, it will be immediately
1542 1542 disabled.
1543 1543
1544 1544 WARNING: by putting in your own exception handler into IPython's main
1545 1545 execution loop, you run a very good chance of nasty crashes. This
1546 1546 facility should only be used if you really know what you are doing."""
1547 1547
1548 1548 assert type(exc_tuple)==type(()) , \
1549 1549 "The custom exceptions must be given AS A TUPLE."
1550 1550
1551 1551 def dummy_handler(self,etype,value,tb,tb_offset=None):
1552 1552 print '*** Simple custom exception handler ***'
1553 1553 print 'Exception type :',etype
1554 1554 print 'Exception value:',value
1555 1555 print 'Traceback :',tb
1556 1556 #print 'Source code :','\n'.join(self.buffer)
1557 1557
1558 1558 def validate_stb(stb):
1559 1559 """validate structured traceback return type
1560 1560
1561 1561 return type of CustomTB *should* be a list of strings, but allow
1562 1562 single strings or None, which are harmless.
1563 1563
1564 1564 This function will *always* return a list of strings,
1565 1565 and will raise a TypeError if stb is inappropriate.
1566 1566 """
1567 1567 msg = "CustomTB must return list of strings, not %r" % stb
1568 1568 if stb is None:
1569 1569 return []
1570 1570 elif isinstance(stb, basestring):
1571 1571 return [stb]
1572 1572 elif not isinstance(stb, list):
1573 1573 raise TypeError(msg)
1574 1574 # it's a list
1575 1575 for line in stb:
1576 1576 # check every element
1577 1577 if not isinstance(line, basestring):
1578 1578 raise TypeError(msg)
1579 1579 return stb
1580 1580
1581 1581 if handler is None:
1582 1582 wrapped = dummy_handler
1583 1583 else:
1584 1584 def wrapped(self,etype,value,tb,tb_offset=None):
1585 1585 """wrap CustomTB handler, to protect IPython from user code
1586 1586
1587 1587 This makes it harder (but not impossible) for custom exception
1588 1588 handlers to crash IPython.
1589 1589 """
1590 1590 try:
1591 1591 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1592 1592 return validate_stb(stb)
1593 1593 except:
1594 1594 # clear custom handler immediately
1595 1595 self.set_custom_exc((), None)
1596 1596 print >> io.stderr, "Custom TB Handler failed, unregistering"
1597 1597 # show the exception in handler first
1598 1598 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1599 1599 print >> io.stdout, self.InteractiveTB.stb2text(stb)
1600 1600 print >> io.stdout, "The original exception:"
1601 1601 stb = self.InteractiveTB.structured_traceback(
1602 1602 (etype,value,tb), tb_offset=tb_offset
1603 1603 )
1604 1604 return stb
1605 1605
1606 1606 self.CustomTB = types.MethodType(wrapped,self)
1607 1607 self.custom_exceptions = exc_tuple
1608 1608
1609 1609 def excepthook(self, etype, value, tb):
1610 1610 """One more defense for GUI apps that call sys.excepthook.
1611 1611
1612 1612 GUI frameworks like wxPython trap exceptions and call
1613 1613 sys.excepthook themselves. I guess this is a feature that
1614 1614 enables them to keep running after exceptions that would
1615 1615 otherwise kill their mainloop. This is a bother for IPython
1616 1616 which excepts to catch all of the program exceptions with a try:
1617 1617 except: statement.
1618 1618
1619 1619 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1620 1620 any app directly invokes sys.excepthook, it will look to the user like
1621 1621 IPython crashed. In order to work around this, we can disable the
1622 1622 CrashHandler and replace it with this excepthook instead, which prints a
1623 1623 regular traceback using our InteractiveTB. In this fashion, apps which
1624 1624 call sys.excepthook will generate a regular-looking exception from
1625 1625 IPython, and the CrashHandler will only be triggered by real IPython
1626 1626 crashes.
1627 1627
1628 1628 This hook should be used sparingly, only in places which are not likely
1629 1629 to be true IPython errors.
1630 1630 """
1631 1631 self.showtraceback((etype,value,tb),tb_offset=0)
1632 1632
1633 1633 def _get_exc_info(self, exc_tuple=None):
1634 1634 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1635 1635
1636 1636 Ensures sys.last_type,value,traceback hold the exc_info we found,
1637 1637 from whichever source.
1638 1638
1639 1639 raises ValueError if none of these contain any information
1640 1640 """
1641 1641 if exc_tuple is None:
1642 1642 etype, value, tb = sys.exc_info()
1643 1643 else:
1644 1644 etype, value, tb = exc_tuple
1645 1645
1646 1646 if etype is None:
1647 1647 if hasattr(sys, 'last_type'):
1648 1648 etype, value, tb = sys.last_type, sys.last_value, \
1649 1649 sys.last_traceback
1650 1650
1651 1651 if etype is None:
1652 1652 raise ValueError("No exception to find")
1653 1653
1654 1654 # Now store the exception info in sys.last_type etc.
1655 1655 # WARNING: these variables are somewhat deprecated and not
1656 1656 # necessarily safe to use in a threaded environment, but tools
1657 1657 # like pdb depend on their existence, so let's set them. If we
1658 1658 # find problems in the field, we'll need to revisit their use.
1659 1659 sys.last_type = etype
1660 1660 sys.last_value = value
1661 1661 sys.last_traceback = tb
1662 1662
1663 1663 return etype, value, tb
1664 1664
1665 1665
1666 1666 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1667 1667 exception_only=False):
1668 1668 """Display the exception that just occurred.
1669 1669
1670 1670 If nothing is known about the exception, this is the method which
1671 1671 should be used throughout the code for presenting user tracebacks,
1672 1672 rather than directly invoking the InteractiveTB object.
1673 1673
1674 1674 A specific showsyntaxerror() also exists, but this method can take
1675 1675 care of calling it if needed, so unless you are explicitly catching a
1676 1676 SyntaxError exception, don't try to analyze the stack manually and
1677 1677 simply call this method."""
1678 1678
1679 1679 try:
1680 1680 try:
1681 1681 etype, value, tb = self._get_exc_info(exc_tuple)
1682 1682 except ValueError:
1683 1683 self.write_err('No traceback available to show.\n')
1684 1684 return
1685 1685
1686 1686 if etype is SyntaxError:
1687 1687 # Though this won't be called by syntax errors in the input
1688 1688 # line, there may be SyntaxError cases with imported code.
1689 1689 self.showsyntaxerror(filename)
1690 1690 elif etype is UsageError:
1691 1691 self.write_err("UsageError: %s" % value)
1692 1692 else:
1693 1693 if etype in self.custom_exceptions:
1694 1694 stb = self.CustomTB(etype, value, tb, tb_offset)
1695 1695 else:
1696 1696 if exception_only:
1697 1697 stb = ['An exception has occurred, use %tb to see '
1698 1698 'the full traceback.\n']
1699 1699 stb.extend(self.InteractiveTB.get_exception_only(etype,
1700 1700 value))
1701 1701 else:
1702 1702 stb = self.InteractiveTB.structured_traceback(etype,
1703 1703 value, tb, tb_offset=tb_offset)
1704 1704
1705 1705 self._showtraceback(etype, value, stb)
1706 1706 if self.call_pdb:
1707 1707 # drop into debugger
1708 1708 self.debugger(force=True)
1709 1709 return
1710 1710
1711 1711 # Actually show the traceback
1712 1712 self._showtraceback(etype, value, stb)
1713 1713
1714 1714 except KeyboardInterrupt:
1715 1715 self.write_err("\nKeyboardInterrupt\n")
1716 1716
1717 1717 def _showtraceback(self, etype, evalue, stb):
1718 1718 """Actually show a traceback.
1719 1719
1720 1720 Subclasses may override this method to put the traceback on a different
1721 1721 place, like a side channel.
1722 1722 """
1723 1723 print >> io.stdout, self.InteractiveTB.stb2text(stb)
1724 1724
1725 1725 def showsyntaxerror(self, filename=None):
1726 1726 """Display the syntax error that just occurred.
1727 1727
1728 1728 This doesn't display a stack trace because there isn't one.
1729 1729
1730 1730 If a filename is given, it is stuffed in the exception instead
1731 1731 of what was there before (because Python's parser always uses
1732 1732 "<string>" when reading from a string).
1733 1733 """
1734 1734 etype, value, last_traceback = self._get_exc_info()
1735 1735
1736 1736 if filename and etype is SyntaxError:
1737 1737 try:
1738 1738 value.filename = filename
1739 1739 except:
1740 1740 # Not the format we expect; leave it alone
1741 1741 pass
1742 1742
1743 1743 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1744 1744 self._showtraceback(etype, value, stb)
1745 1745
1746 1746 # This is overridden in TerminalInteractiveShell to show a message about
1747 1747 # the %paste magic.
1748 1748 def showindentationerror(self):
1749 1749 """Called by run_cell when there's an IndentationError in code entered
1750 1750 at the prompt.
1751 1751
1752 1752 This is overridden in TerminalInteractiveShell to show a message about
1753 1753 the %paste magic."""
1754 1754 self.showsyntaxerror()
1755 1755
1756 1756 #-------------------------------------------------------------------------
1757 1757 # Things related to readline
1758 1758 #-------------------------------------------------------------------------
1759 1759
1760 1760 def init_readline(self):
1761 1761 """Command history completion/saving/reloading."""
1762 1762
1763 1763 if self.readline_use:
1764 1764 import IPython.utils.rlineimpl as readline
1765 1765
1766 1766 self.rl_next_input = None
1767 1767 self.rl_do_indent = False
1768 1768
1769 1769 if not self.readline_use or not readline.have_readline:
1770 1770 self.has_readline = False
1771 1771 self.readline = None
1772 1772 # Set a number of methods that depend on readline to be no-op
1773 1773 self.readline_no_record = no_op_context
1774 1774 self.set_readline_completer = no_op
1775 1775 self.set_custom_completer = no_op
1776 1776 self.set_completer_frame = no_op
1777 1777 if self.readline_use:
1778 1778 warn('Readline services not available or not loaded.')
1779 1779 else:
1780 1780 self.has_readline = True
1781 1781 self.readline = readline
1782 1782 sys.modules['readline'] = readline
1783 1783
1784 1784 # Platform-specific configuration
1785 1785 if os.name == 'nt':
1786 1786 # FIXME - check with Frederick to see if we can harmonize
1787 1787 # naming conventions with pyreadline to avoid this
1788 1788 # platform-dependent check
1789 1789 self.readline_startup_hook = readline.set_pre_input_hook
1790 1790 else:
1791 1791 self.readline_startup_hook = readline.set_startup_hook
1792 1792
1793 1793 # Load user's initrc file (readline config)
1794 1794 # Or if libedit is used, load editrc.
1795 1795 inputrc_name = os.environ.get('INPUTRC')
1796 1796 if inputrc_name is None:
1797 1797 inputrc_name = '.inputrc'
1798 1798 if readline.uses_libedit:
1799 1799 inputrc_name = '.editrc'
1800 1800 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1801 1801 if os.path.isfile(inputrc_name):
1802 1802 try:
1803 1803 readline.read_init_file(inputrc_name)
1804 1804 except:
1805 1805 warn('Problems reading readline initialization file <%s>'
1806 1806 % inputrc_name)
1807 1807
1808 1808 # Configure readline according to user's prefs
1809 1809 # This is only done if GNU readline is being used. If libedit
1810 1810 # is being used (as on Leopard) the readline config is
1811 1811 # not run as the syntax for libedit is different.
1812 1812 if not readline.uses_libedit:
1813 1813 for rlcommand in self.readline_parse_and_bind:
1814 1814 #print "loading rl:",rlcommand # dbg
1815 1815 readline.parse_and_bind(rlcommand)
1816 1816
1817 1817 # Remove some chars from the delimiters list. If we encounter
1818 1818 # unicode chars, discard them.
1819 1819 delims = readline.get_completer_delims()
1820 1820 if not py3compat.PY3:
1821 1821 delims = delims.encode("ascii", "ignore")
1822 1822 for d in self.readline_remove_delims:
1823 1823 delims = delims.replace(d, "")
1824 1824 delims = delims.replace(ESC_MAGIC, '')
1825 1825 readline.set_completer_delims(delims)
1826 1826 # otherwise we end up with a monster history after a while:
1827 1827 readline.set_history_length(self.history_length)
1828 1828
1829 1829 self.refill_readline_hist()
1830 1830 self.readline_no_record = ReadlineNoRecord(self)
1831 1831
1832 1832 # Configure auto-indent for all platforms
1833 1833 self.set_autoindent(self.autoindent)
1834 1834
1835 1835 def refill_readline_hist(self):
1836 1836 # Load the last 1000 lines from history
1837 1837 self.readline.clear_history()
1838 1838 stdin_encoding = sys.stdin.encoding or "utf-8"
1839 1839 last_cell = u""
1840 1840 for _, _, cell in self.history_manager.get_tail(1000,
1841 1841 include_latest=True):
1842 1842 # Ignore blank lines and consecutive duplicates
1843 1843 cell = cell.rstrip()
1844 1844 if cell and (cell != last_cell):
1845 1845 if self.multiline_history:
1846 1846 self.readline.add_history(py3compat.unicode_to_str(cell,
1847 1847 stdin_encoding))
1848 1848 else:
1849 1849 for line in cell.splitlines():
1850 1850 self.readline.add_history(py3compat.unicode_to_str(line,
1851 1851 stdin_encoding))
1852 1852 last_cell = cell
1853 1853
1854 1854 def set_next_input(self, s):
1855 1855 """ Sets the 'default' input string for the next command line.
1856 1856
1857 1857 Requires readline.
1858 1858
1859 1859 Example:
1860 1860
1861 1861 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1862 1862 [D:\ipython]|2> Hello Word_ # cursor is here
1863 1863 """
1864 1864 self.rl_next_input = py3compat.cast_bytes_py2(s)
1865 1865
1866 1866 # Maybe move this to the terminal subclass?
1867 1867 def pre_readline(self):
1868 1868 """readline hook to be used at the start of each line.
1869 1869
1870 1870 Currently it handles auto-indent only."""
1871 1871
1872 1872 if self.rl_do_indent:
1873 1873 self.readline.insert_text(self._indent_current_str())
1874 1874 if self.rl_next_input is not None:
1875 1875 self.readline.insert_text(self.rl_next_input)
1876 1876 self.rl_next_input = None
1877 1877
1878 1878 def _indent_current_str(self):
1879 1879 """return the current level of indentation as a string"""
1880 1880 return self.input_splitter.indent_spaces * ' '
1881 1881
1882 1882 #-------------------------------------------------------------------------
1883 1883 # Things related to text completion
1884 1884 #-------------------------------------------------------------------------
1885 1885
1886 1886 def init_completer(self):
1887 1887 """Initialize the completion machinery.
1888 1888
1889 1889 This creates completion machinery that can be used by client code,
1890 1890 either interactively in-process (typically triggered by the readline
1891 1891 library), programatically (such as in test suites) or out-of-prcess
1892 1892 (typically over the network by remote frontends).
1893 1893 """
1894 1894 from IPython.core.completer import IPCompleter
1895 1895 from IPython.core.completerlib import (module_completer,
1896 1896 magic_run_completer, cd_completer, reset_completer)
1897 1897
1898 1898 self.Completer = IPCompleter(shell=self,
1899 1899 namespace=self.user_ns,
1900 1900 global_namespace=self.user_global_ns,
1901 1901 alias_table=self.alias_manager.alias_table,
1902 1902 use_readline=self.has_readline,
1903 1903 config=self.config,
1904 1904 )
1905 1905 self.configurables.append(self.Completer)
1906 1906
1907 1907 # Add custom completers to the basic ones built into IPCompleter
1908 1908 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1909 1909 self.strdispatchers['complete_command'] = sdisp
1910 1910 self.Completer.custom_completers = sdisp
1911 1911
1912 1912 self.set_hook('complete_command', module_completer, str_key = 'import')
1913 1913 self.set_hook('complete_command', module_completer, str_key = 'from')
1914 1914 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1915 1915 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1916 1916 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1917 1917
1918 1918 # Only configure readline if we truly are using readline. IPython can
1919 1919 # do tab-completion over the network, in GUIs, etc, where readline
1920 1920 # itself may be absent
1921 1921 if self.has_readline:
1922 1922 self.set_readline_completer()
1923 1923
1924 1924 def complete(self, text, line=None, cursor_pos=None):
1925 1925 """Return the completed text and a list of completions.
1926 1926
1927 1927 Parameters
1928 1928 ----------
1929 1929
1930 1930 text : string
1931 1931 A string of text to be completed on. It can be given as empty and
1932 1932 instead a line/position pair are given. In this case, the
1933 1933 completer itself will split the line like readline does.
1934 1934
1935 1935 line : string, optional
1936 1936 The complete line that text is part of.
1937 1937
1938 1938 cursor_pos : int, optional
1939 1939 The position of the cursor on the input line.
1940 1940
1941 1941 Returns
1942 1942 -------
1943 1943 text : string
1944 1944 The actual text that was completed.
1945 1945
1946 1946 matches : list
1947 1947 A sorted list with all possible completions.
1948 1948
1949 1949 The optional arguments allow the completion to take more context into
1950 1950 account, and are part of the low-level completion API.
1951 1951
1952 1952 This is a wrapper around the completion mechanism, similar to what
1953 1953 readline does at the command line when the TAB key is hit. By
1954 1954 exposing it as a method, it can be used by other non-readline
1955 1955 environments (such as GUIs) for text completion.
1956 1956
1957 1957 Simple usage example:
1958 1958
1959 1959 In [1]: x = 'hello'
1960 1960
1961 1961 In [2]: _ip.complete('x.l')
1962 1962 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1963 1963 """
1964 1964
1965 1965 # Inject names into __builtin__ so we can complete on the added names.
1966 1966 with self.builtin_trap:
1967 1967 return self.Completer.complete(text, line, cursor_pos)
1968 1968
1969 1969 def set_custom_completer(self, completer, pos=0):
1970 1970 """Adds a new custom completer function.
1971 1971
1972 1972 The position argument (defaults to 0) is the index in the completers
1973 1973 list where you want the completer to be inserted."""
1974 1974
1975 1975 newcomp = types.MethodType(completer,self.Completer)
1976 1976 self.Completer.matchers.insert(pos,newcomp)
1977 1977
1978 1978 def set_readline_completer(self):
1979 1979 """Reset readline's completer to be our own."""
1980 1980 self.readline.set_completer(self.Completer.rlcomplete)
1981 1981
1982 1982 def set_completer_frame(self, frame=None):
1983 1983 """Set the frame of the completer."""
1984 1984 if frame:
1985 1985 self.Completer.namespace = frame.f_locals
1986 1986 self.Completer.global_namespace = frame.f_globals
1987 1987 else:
1988 1988 self.Completer.namespace = self.user_ns
1989 1989 self.Completer.global_namespace = self.user_global_ns
1990 1990
1991 1991 #-------------------------------------------------------------------------
1992 1992 # Things related to magics
1993 1993 #-------------------------------------------------------------------------
1994 1994
1995 1995 def init_magics(self):
1996 1996 from IPython.core import magic_functions as mf
1997 1997 from IPython.core import magics as m
1998 1998 self.magics_manager = magic.MagicsManager(shell=self,
1999 1999 confg=self.config,
2000 2000 user_magics=m.UserMagics(self))
2001 2001 self.configurables.append(self.magics_manager)
2002 2002
2003 2003 # Expose as public API from the magics manager
2004 2004 self.register_magics = self.magics_manager.register
2005 2005 self.register_magic_function = self.magics_manager.register_function
2006 2006 self.define_magic = self.magics_manager.define_magic
2007 2007
2008 self.register_magics(mf.AutoMagics, m.BasicMagics, m.CodeMagics,
2008 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2009 2009 m.ConfigMagics, mf.DeprecatedMagics, m.ExecutionMagics,
2010 2010 mf.ExtensionsMagics, m.HistoryMagics, mf.LoggingMagics,
2011 2011 m.NamespaceMagics, mf.OSMagics, mf.PylabMagics )
2012 2012
2013 2013 # FIXME: Move the color initialization to the DisplayHook, which
2014 2014 # should be split into a prompt manager and displayhook. We probably
2015 2015 # even need a centralize colors management object.
2016 2016 self.magic('colors %s' % self.colors)
2017 2017
2018 2018 def line_magic(self, magic_name, line, next_input=None):
2019 2019 """Execute the given line magic.
2020 2020
2021 2021 Parameters
2022 2022 ----------
2023 2023 magic_name : str
2024 2024 Name of the desired magic function, without '%' prefix.
2025 2025
2026 2026 line : str
2027 2027 The rest of the input line as a single string.
2028 2028
2029 2029 next_input : str, optional
2030 2030 Text to pre-load into the next input line.
2031 2031 """
2032 2032 # Allow setting the next input - this is used if the user does `a=abs?`.
2033 2033 # We do this first so that magic functions can override it.
2034 2034 if next_input:
2035 2035 self.set_next_input(next_input)
2036 2036
2037 2037 fn = self.find_line_magic(magic_name)
2038 2038 if fn is None:
2039 2039 error("Magic function `%s` not found." % magic_name)
2040 2040 else:
2041 2041 # Note: this is the distance in the stack to the user's frame.
2042 2042 # This will need to be updated if the internal calling logic gets
2043 2043 # refactored, or else we'll be expanding the wrong variables.
2044 2044 stack_depth = 2
2045 2045 magic_arg_s = self.var_expand(line, stack_depth)
2046 2046 # Put magic args in a list so we can call with f(*a) syntax
2047 2047 args = [magic_arg_s]
2048 2048 # Grab local namespace if we need it:
2049 2049 if getattr(fn, "needs_local_scope", False):
2050 2050 args.append(sys._getframe(stack_depth).f_locals)
2051 2051 with self.builtin_trap:
2052 2052 result = fn(*args)
2053 2053 return result
2054 2054
2055 2055 def cell_magic(self, magic_name, line, cell):
2056 2056 """Execute the given cell magic.
2057 2057 """
2058 2058 fn = self.find_cell_magic(magic_name)
2059 2059 if fn is None:
2060 2060 error("Magic function `%s` not found." % magic_name)
2061 2061 else:
2062 2062 # Note: this is the distance in the stack to the user's frame.
2063 2063 # This will need to be updated if the internal calling logic gets
2064 2064 # refactored, or else we'll be expanding the wrong variables.
2065 2065 stack_depth = 2
2066 2066 magic_arg_s = self.var_expand(line, stack_depth)
2067 2067 with self.builtin_trap:
2068 2068 result = fn(line, cell)
2069 2069 return result
2070 2070
2071 2071 def find_line_magic(self, magic_name):
2072 2072 """Find and return a line magic by name.
2073 2073
2074 2074 Returns None if the magic isn't found."""
2075 2075 return self.magics_manager.magics['line'].get(magic_name)
2076 2076
2077 2077 def find_cell_magic(self, magic_name):
2078 2078 """Find and return a cell magic by name.
2079 2079
2080 2080 Returns None if the magic isn't found."""
2081 2081 return self.magics_manager.magics['cell'].get(magic_name)
2082 2082
2083 2083 def find_magic(self, magic_name, magic_type='line'):
2084 2084 """Find and return a magic of the given type by name.
2085 2085
2086 2086 Returns None if the magic isn't found."""
2087 2087 return self.magics_manager.magics[magic_type].get(magic_name)
2088 2088
2089 2089 def magic(self, arg_s, next_input=None):
2090 2090 """DEPRECATED. Use line_magic() instead.
2091 2091
2092 2092 Call a magic function by name.
2093 2093
2094 2094 Input: a string containing the name of the magic function to call and
2095 2095 any additional arguments to be passed to the magic.
2096 2096
2097 2097 magic('name -opt foo bar') is equivalent to typing at the ipython
2098 2098 prompt:
2099 2099
2100 2100 In[1]: %name -opt foo bar
2101 2101
2102 2102 To call a magic without arguments, simply use magic('name').
2103 2103
2104 2104 This provides a proper Python function to call IPython's magics in any
2105 2105 valid Python code you can type at the interpreter, including loops and
2106 2106 compound statements.
2107 2107 """
2108 2108 # TODO: should we issue a loud deprecation warning here?
2109 2109 magic_name, _, magic_arg_s = arg_s.partition(' ')
2110 2110 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2111 2111 return self.line_magic(magic_name, magic_arg_s, next_input)
2112 2112
2113 2113 #-------------------------------------------------------------------------
2114 2114 # Things related to macros
2115 2115 #-------------------------------------------------------------------------
2116 2116
2117 2117 def define_macro(self, name, themacro):
2118 2118 """Define a new macro
2119 2119
2120 2120 Parameters
2121 2121 ----------
2122 2122 name : str
2123 2123 The name of the macro.
2124 2124 themacro : str or Macro
2125 2125 The action to do upon invoking the macro. If a string, a new
2126 2126 Macro object is created by passing the string to it.
2127 2127 """
2128 2128
2129 2129 from IPython.core import macro
2130 2130
2131 2131 if isinstance(themacro, basestring):
2132 2132 themacro = macro.Macro(themacro)
2133 2133 if not isinstance(themacro, macro.Macro):
2134 2134 raise ValueError('A macro must be a string or a Macro instance.')
2135 2135 self.user_ns[name] = themacro
2136 2136
2137 2137 #-------------------------------------------------------------------------
2138 2138 # Things related to the running of system commands
2139 2139 #-------------------------------------------------------------------------
2140 2140
2141 2141 def system_piped(self, cmd):
2142 2142 """Call the given cmd in a subprocess, piping stdout/err
2143 2143
2144 2144 Parameters
2145 2145 ----------
2146 2146 cmd : str
2147 2147 Command to execute (can not end in '&', as background processes are
2148 2148 not supported. Should not be a command that expects input
2149 2149 other than simple text.
2150 2150 """
2151 2151 if cmd.rstrip().endswith('&'):
2152 2152 # this is *far* from a rigorous test
2153 2153 # We do not support backgrounding processes because we either use
2154 2154 # pexpect or pipes to read from. Users can always just call
2155 2155 # os.system() or use ip.system=ip.system_raw
2156 2156 # if they really want a background process.
2157 2157 raise OSError("Background processes not supported.")
2158 2158
2159 2159 # we explicitly do NOT return the subprocess status code, because
2160 2160 # a non-None value would trigger :func:`sys.displayhook` calls.
2161 2161 # Instead, we store the exit_code in user_ns.
2162 2162 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=2))
2163 2163
2164 2164 def system_raw(self, cmd):
2165 2165 """Call the given cmd in a subprocess using os.system
2166 2166
2167 2167 Parameters
2168 2168 ----------
2169 2169 cmd : str
2170 2170 Command to execute.
2171 2171 """
2172 2172 cmd = self.var_expand(cmd, depth=2)
2173 2173 # protect os.system from UNC paths on Windows, which it can't handle:
2174 2174 if sys.platform == 'win32':
2175 2175 from IPython.utils._process_win32 import AvoidUNCPath
2176 2176 with AvoidUNCPath() as path:
2177 2177 if path is not None:
2178 2178 cmd = '"pushd %s &&"%s' % (path, cmd)
2179 2179 cmd = py3compat.unicode_to_str(cmd)
2180 2180 ec = os.system(cmd)
2181 2181 else:
2182 2182 cmd = py3compat.unicode_to_str(cmd)
2183 2183 ec = os.system(cmd)
2184 2184
2185 2185 # We explicitly do NOT return the subprocess status code, because
2186 2186 # a non-None value would trigger :func:`sys.displayhook` calls.
2187 2187 # Instead, we store the exit_code in user_ns.
2188 2188 self.user_ns['_exit_code'] = ec
2189 2189
2190 2190 # use piped system by default, because it is better behaved
2191 2191 system = system_piped
2192 2192
2193 2193 def getoutput(self, cmd, split=True):
2194 2194 """Get output (possibly including stderr) from a subprocess.
2195 2195
2196 2196 Parameters
2197 2197 ----------
2198 2198 cmd : str
2199 2199 Command to execute (can not end in '&', as background processes are
2200 2200 not supported.
2201 2201 split : bool, optional
2202 2202
2203 2203 If True, split the output into an IPython SList. Otherwise, an
2204 2204 IPython LSString is returned. These are objects similar to normal
2205 2205 lists and strings, with a few convenience attributes for easier
2206 2206 manipulation of line-based output. You can use '?' on them for
2207 2207 details.
2208 2208 """
2209 2209 if cmd.rstrip().endswith('&'):
2210 2210 # this is *far* from a rigorous test
2211 2211 raise OSError("Background processes not supported.")
2212 2212 out = getoutput(self.var_expand(cmd, depth=2))
2213 2213 if split:
2214 2214 out = SList(out.splitlines())
2215 2215 else:
2216 2216 out = LSString(out)
2217 2217 return out
2218 2218
2219 2219 #-------------------------------------------------------------------------
2220 2220 # Things related to aliases
2221 2221 #-------------------------------------------------------------------------
2222 2222
2223 2223 def init_alias(self):
2224 2224 self.alias_manager = AliasManager(shell=self, config=self.config)
2225 2225 self.configurables.append(self.alias_manager)
2226 2226 self.ns_table['alias'] = self.alias_manager.alias_table,
2227 2227
2228 2228 #-------------------------------------------------------------------------
2229 2229 # Things related to extensions and plugins
2230 2230 #-------------------------------------------------------------------------
2231 2231
2232 2232 def init_extension_manager(self):
2233 2233 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2234 2234 self.configurables.append(self.extension_manager)
2235 2235
2236 2236 def init_plugin_manager(self):
2237 2237 self.plugin_manager = PluginManager(config=self.config)
2238 2238 self.configurables.append(self.plugin_manager)
2239 2239
2240 2240
2241 2241 #-------------------------------------------------------------------------
2242 2242 # Things related to payloads
2243 2243 #-------------------------------------------------------------------------
2244 2244
2245 2245 def init_payload(self):
2246 2246 self.payload_manager = PayloadManager(config=self.config)
2247 2247 self.configurables.append(self.payload_manager)
2248 2248
2249 2249 #-------------------------------------------------------------------------
2250 2250 # Things related to the prefilter
2251 2251 #-------------------------------------------------------------------------
2252 2252
2253 2253 def init_prefilter(self):
2254 2254 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2255 2255 self.configurables.append(self.prefilter_manager)
2256 2256 # Ultimately this will be refactored in the new interpreter code, but
2257 2257 # for now, we should expose the main prefilter method (there's legacy
2258 2258 # code out there that may rely on this).
2259 2259 self.prefilter = self.prefilter_manager.prefilter_lines
2260 2260
2261 2261 def auto_rewrite_input(self, cmd):
2262 2262 """Print to the screen the rewritten form of the user's command.
2263 2263
2264 2264 This shows visual feedback by rewriting input lines that cause
2265 2265 automatic calling to kick in, like::
2266 2266
2267 2267 /f x
2268 2268
2269 2269 into::
2270 2270
2271 2271 ------> f(x)
2272 2272
2273 2273 after the user's input prompt. This helps the user understand that the
2274 2274 input line was transformed automatically by IPython.
2275 2275 """
2276 2276 if not self.show_rewritten_input:
2277 2277 return
2278 2278
2279 2279 rw = self.prompt_manager.render('rewrite') + cmd
2280 2280
2281 2281 try:
2282 2282 # plain ascii works better w/ pyreadline, on some machines, so
2283 2283 # we use it and only print uncolored rewrite if we have unicode
2284 2284 rw = str(rw)
2285 2285 print >> io.stdout, rw
2286 2286 except UnicodeEncodeError:
2287 2287 print "------> " + cmd
2288 2288
2289 2289 #-------------------------------------------------------------------------
2290 2290 # Things related to extracting values/expressions from kernel and user_ns
2291 2291 #-------------------------------------------------------------------------
2292 2292
2293 2293 def _simple_error(self):
2294 2294 etype, value = sys.exc_info()[:2]
2295 2295 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2296 2296
2297 2297 def user_variables(self, names):
2298 2298 """Get a list of variable names from the user's namespace.
2299 2299
2300 2300 Parameters
2301 2301 ----------
2302 2302 names : list of strings
2303 2303 A list of names of variables to be read from the user namespace.
2304 2304
2305 2305 Returns
2306 2306 -------
2307 2307 A dict, keyed by the input names and with the repr() of each value.
2308 2308 """
2309 2309 out = {}
2310 2310 user_ns = self.user_ns
2311 2311 for varname in names:
2312 2312 try:
2313 2313 value = repr(user_ns[varname])
2314 2314 except:
2315 2315 value = self._simple_error()
2316 2316 out[varname] = value
2317 2317 return out
2318 2318
2319 2319 def user_expressions(self, expressions):
2320 2320 """Evaluate a dict of expressions in the user's namespace.
2321 2321
2322 2322 Parameters
2323 2323 ----------
2324 2324 expressions : dict
2325 2325 A dict with string keys and string values. The expression values
2326 2326 should be valid Python expressions, each of which will be evaluated
2327 2327 in the user namespace.
2328 2328
2329 2329 Returns
2330 2330 -------
2331 2331 A dict, keyed like the input expressions dict, with the repr() of each
2332 2332 value.
2333 2333 """
2334 2334 out = {}
2335 2335 user_ns = self.user_ns
2336 2336 global_ns = self.user_global_ns
2337 2337 for key, expr in expressions.iteritems():
2338 2338 try:
2339 2339 value = repr(eval(expr, global_ns, user_ns))
2340 2340 except:
2341 2341 value = self._simple_error()
2342 2342 out[key] = value
2343 2343 return out
2344 2344
2345 2345 #-------------------------------------------------------------------------
2346 2346 # Things related to the running of code
2347 2347 #-------------------------------------------------------------------------
2348 2348
2349 2349 def ex(self, cmd):
2350 2350 """Execute a normal python statement in user namespace."""
2351 2351 with self.builtin_trap:
2352 2352 exec cmd in self.user_global_ns, self.user_ns
2353 2353
2354 2354 def ev(self, expr):
2355 2355 """Evaluate python expression expr in user namespace.
2356 2356
2357 2357 Returns the result of evaluation
2358 2358 """
2359 2359 with self.builtin_trap:
2360 2360 return eval(expr, self.user_global_ns, self.user_ns)
2361 2361
2362 2362 def safe_execfile(self, fname, *where, **kw):
2363 2363 """A safe version of the builtin execfile().
2364 2364
2365 2365 This version will never throw an exception, but instead print
2366 2366 helpful error messages to the screen. This only works on pure
2367 2367 Python files with the .py extension.
2368 2368
2369 2369 Parameters
2370 2370 ----------
2371 2371 fname : string
2372 2372 The name of the file to be executed.
2373 2373 where : tuple
2374 2374 One or two namespaces, passed to execfile() as (globals,locals).
2375 2375 If only one is given, it is passed as both.
2376 2376 exit_ignore : bool (False)
2377 2377 If True, then silence SystemExit for non-zero status (it is always
2378 2378 silenced for zero status, as it is so common).
2379 2379 raise_exceptions : bool (False)
2380 2380 If True raise exceptions everywhere. Meant for testing.
2381 2381
2382 2382 """
2383 2383 kw.setdefault('exit_ignore', False)
2384 2384 kw.setdefault('raise_exceptions', False)
2385 2385
2386 2386 fname = os.path.abspath(os.path.expanduser(fname))
2387 2387
2388 2388 # Make sure we can open the file
2389 2389 try:
2390 2390 with open(fname) as thefile:
2391 2391 pass
2392 2392 except:
2393 2393 warn('Could not open file <%s> for safe execution.' % fname)
2394 2394 return
2395 2395
2396 2396 # Find things also in current directory. This is needed to mimic the
2397 2397 # behavior of running a script from the system command line, where
2398 2398 # Python inserts the script's directory into sys.path
2399 2399 dname = os.path.dirname(fname)
2400 2400
2401 2401 with prepended_to_syspath(dname):
2402 2402 try:
2403 2403 py3compat.execfile(fname,*where)
2404 2404 except SystemExit, status:
2405 2405 # If the call was made with 0 or None exit status (sys.exit(0)
2406 2406 # or sys.exit() ), don't bother showing a traceback, as both of
2407 2407 # these are considered normal by the OS:
2408 2408 # > python -c'import sys;sys.exit(0)'; echo $?
2409 2409 # 0
2410 2410 # > python -c'import sys;sys.exit()'; echo $?
2411 2411 # 0
2412 2412 # For other exit status, we show the exception unless
2413 2413 # explicitly silenced, but only in short form.
2414 2414 if kw['raise_exceptions']:
2415 2415 raise
2416 2416 if status.code not in (0, None) and not kw['exit_ignore']:
2417 2417 self.showtraceback(exception_only=True)
2418 2418 except:
2419 2419 if kw['raise_exceptions']:
2420 2420 raise
2421 2421 self.showtraceback()
2422 2422
2423 2423 def safe_execfile_ipy(self, fname):
2424 2424 """Like safe_execfile, but for .ipy files with IPython syntax.
2425 2425
2426 2426 Parameters
2427 2427 ----------
2428 2428 fname : str
2429 2429 The name of the file to execute. The filename must have a
2430 2430 .ipy extension.
2431 2431 """
2432 2432 fname = os.path.abspath(os.path.expanduser(fname))
2433 2433
2434 2434 # Make sure we can open the file
2435 2435 try:
2436 2436 with open(fname) as thefile:
2437 2437 pass
2438 2438 except:
2439 2439 warn('Could not open file <%s> for safe execution.' % fname)
2440 2440 return
2441 2441
2442 2442 # Find things also in current directory. This is needed to mimic the
2443 2443 # behavior of running a script from the system command line, where
2444 2444 # Python inserts the script's directory into sys.path
2445 2445 dname = os.path.dirname(fname)
2446 2446
2447 2447 with prepended_to_syspath(dname):
2448 2448 try:
2449 2449 with open(fname) as thefile:
2450 2450 # self.run_cell currently captures all exceptions
2451 2451 # raised in user code. It would be nice if there were
2452 2452 # versions of runlines, execfile that did raise, so
2453 2453 # we could catch the errors.
2454 2454 self.run_cell(thefile.read(), store_history=False)
2455 2455 except:
2456 2456 self.showtraceback()
2457 2457 warn('Unknown failure executing file: <%s>' % fname)
2458 2458
2459 2459 def safe_run_module(self, mod_name, where):
2460 2460 """A safe version of runpy.run_module().
2461 2461
2462 2462 This version will never throw an exception, but instead print
2463 2463 helpful error messages to the screen.
2464 2464
2465 2465 Parameters
2466 2466 ----------
2467 2467 mod_name : string
2468 2468 The name of the module to be executed.
2469 2469 where : dict
2470 2470 The globals namespace.
2471 2471 """
2472 2472 try:
2473 2473 where.update(
2474 2474 runpy.run_module(str(mod_name), run_name="__main__",
2475 2475 alter_sys=True)
2476 2476 )
2477 2477 except:
2478 2478 self.showtraceback()
2479 2479 warn('Unknown failure executing module: <%s>' % mod_name)
2480 2480
2481 2481 def call_cell_magic(self, raw_cell, store_history=False):
2482 2482 line, _, cell = raw_cell.partition(os.linesep)
2483 2483 magic_name, _, line = line.partition(' ')
2484 2484 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2485 2485 return self.cell_magic(magic_name, line, cell)
2486 2486
2487 2487 def run_cell(self, raw_cell, store_history=False, silent=False):
2488 2488 """Run a complete IPython cell.
2489 2489
2490 2490 Parameters
2491 2491 ----------
2492 2492 raw_cell : str
2493 2493 The code (including IPython code such as %magic functions) to run.
2494 2494 store_history : bool
2495 2495 If True, the raw and translated cell will be stored in IPython's
2496 2496 history. For user code calling back into IPython's machinery, this
2497 2497 should be set to False.
2498 2498 silent : bool
2499 2499 If True, avoid side-effets, such as implicit displayhooks, history,
2500 2500 and logging. silent=True forces store_history=False.
2501 2501 """
2502 2502 if (not raw_cell) or raw_cell.isspace():
2503 2503 return
2504 2504
2505 2505 if silent:
2506 2506 store_history = False
2507 2507
2508 2508 if raw_cell.startswith('%%'):
2509 2509 return self.call_cell_magic(raw_cell, store_history)
2510 2510
2511 2511 for line in raw_cell.splitlines():
2512 2512 self.input_splitter.push(line)
2513 2513 cell = self.input_splitter.source_reset()
2514 2514
2515 2515 with self.builtin_trap:
2516 2516 prefilter_failed = False
2517 2517 if len(cell.splitlines()) == 1:
2518 2518 try:
2519 2519 # use prefilter_lines to handle trailing newlines
2520 2520 # restore trailing newline for ast.parse
2521 2521 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2522 2522 except AliasError as e:
2523 2523 error(e)
2524 2524 prefilter_failed = True
2525 2525 except Exception:
2526 2526 # don't allow prefilter errors to crash IPython
2527 2527 self.showtraceback()
2528 2528 prefilter_failed = True
2529 2529
2530 2530 # Store raw and processed history
2531 2531 if store_history:
2532 2532 self.history_manager.store_inputs(self.execution_count,
2533 2533 cell, raw_cell)
2534 2534 if not silent:
2535 2535 self.logger.log(cell, raw_cell)
2536 2536
2537 2537 if not prefilter_failed:
2538 2538 # don't run if prefilter failed
2539 2539 cell_name = self.compile.cache(cell, self.execution_count)
2540 2540
2541 2541 with self.display_trap:
2542 2542 try:
2543 2543 code_ast = self.compile.ast_parse(cell,
2544 2544 filename=cell_name)
2545 2545 except IndentationError:
2546 2546 self.showindentationerror()
2547 2547 if store_history:
2548 2548 self.execution_count += 1
2549 2549 return None
2550 2550 except (OverflowError, SyntaxError, ValueError, TypeError,
2551 2551 MemoryError):
2552 2552 self.showsyntaxerror()
2553 2553 if store_history:
2554 2554 self.execution_count += 1
2555 2555 return None
2556 2556
2557 2557 interactivity = "none" if silent else "last_expr"
2558 2558 self.run_ast_nodes(code_ast.body, cell_name,
2559 2559 interactivity=interactivity)
2560 2560
2561 2561 # Execute any registered post-execution functions.
2562 2562 # unless we are silent
2563 2563 post_exec = [] if silent else self._post_execute.iteritems()
2564 2564
2565 2565 for func, status in post_exec:
2566 2566 if self.disable_failing_post_execute and not status:
2567 2567 continue
2568 2568 try:
2569 2569 func()
2570 2570 except KeyboardInterrupt:
2571 2571 print >> io.stderr, "\nKeyboardInterrupt"
2572 2572 except Exception:
2573 2573 # register as failing:
2574 2574 self._post_execute[func] = False
2575 2575 self.showtraceback()
2576 2576 print >> io.stderr, '\n'.join([
2577 2577 "post-execution function %r produced an error." % func,
2578 2578 "If this problem persists, you can disable failing post-exec functions with:",
2579 2579 "",
2580 2580 " get_ipython().disable_failing_post_execute = True"
2581 2581 ])
2582 2582
2583 2583 if store_history:
2584 2584 # Write output to the database. Does nothing unless
2585 2585 # history output logging is enabled.
2586 2586 self.history_manager.store_output(self.execution_count)
2587 2587 # Each cell is a *single* input, regardless of how many lines it has
2588 2588 self.execution_count += 1
2589 2589
2590 2590 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2591 2591 """Run a sequence of AST nodes. The execution mode depends on the
2592 2592 interactivity parameter.
2593 2593
2594 2594 Parameters
2595 2595 ----------
2596 2596 nodelist : list
2597 2597 A sequence of AST nodes to run.
2598 2598 cell_name : str
2599 2599 Will be passed to the compiler as the filename of the cell. Typically
2600 2600 the value returned by ip.compile.cache(cell).
2601 2601 interactivity : str
2602 2602 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2603 2603 run interactively (displaying output from expressions). 'last_expr'
2604 2604 will run the last node interactively only if it is an expression (i.e.
2605 2605 expressions in loops or other blocks are not displayed. Other values
2606 2606 for this parameter will raise a ValueError.
2607 2607 """
2608 2608 if not nodelist:
2609 2609 return
2610 2610
2611 2611 if interactivity == 'last_expr':
2612 2612 if isinstance(nodelist[-1], ast.Expr):
2613 2613 interactivity = "last"
2614 2614 else:
2615 2615 interactivity = "none"
2616 2616
2617 2617 if interactivity == 'none':
2618 2618 to_run_exec, to_run_interactive = nodelist, []
2619 2619 elif interactivity == 'last':
2620 2620 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2621 2621 elif interactivity == 'all':
2622 2622 to_run_exec, to_run_interactive = [], nodelist
2623 2623 else:
2624 2624 raise ValueError("Interactivity was %r" % interactivity)
2625 2625
2626 2626 exec_count = self.execution_count
2627 2627
2628 2628 try:
2629 2629 for i, node in enumerate(to_run_exec):
2630 2630 mod = ast.Module([node])
2631 2631 code = self.compile(mod, cell_name, "exec")
2632 2632 if self.run_code(code):
2633 2633 return True
2634 2634
2635 2635 for i, node in enumerate(to_run_interactive):
2636 2636 mod = ast.Interactive([node])
2637 2637 code = self.compile(mod, cell_name, "single")
2638 2638 if self.run_code(code):
2639 2639 return True
2640 2640
2641 2641 # Flush softspace
2642 2642 if softspace(sys.stdout, 0):
2643 2643 print
2644 2644
2645 2645 except:
2646 2646 # It's possible to have exceptions raised here, typically by
2647 2647 # compilation of odd code (such as a naked 'return' outside a
2648 2648 # function) that did parse but isn't valid. Typically the exception
2649 2649 # is a SyntaxError, but it's safest just to catch anything and show
2650 2650 # the user a traceback.
2651 2651
2652 2652 # We do only one try/except outside the loop to minimize the impact
2653 2653 # on runtime, and also because if any node in the node list is
2654 2654 # broken, we should stop execution completely.
2655 2655 self.showtraceback()
2656 2656
2657 2657 return False
2658 2658
2659 2659 def run_code(self, code_obj):
2660 2660 """Execute a code object.
2661 2661
2662 2662 When an exception occurs, self.showtraceback() is called to display a
2663 2663 traceback.
2664 2664
2665 2665 Parameters
2666 2666 ----------
2667 2667 code_obj : code object
2668 2668 A compiled code object, to be executed
2669 2669
2670 2670 Returns
2671 2671 -------
2672 2672 False : successful execution.
2673 2673 True : an error occurred.
2674 2674 """
2675 2675
2676 2676 # Set our own excepthook in case the user code tries to call it
2677 2677 # directly, so that the IPython crash handler doesn't get triggered
2678 2678 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2679 2679
2680 2680 # we save the original sys.excepthook in the instance, in case config
2681 2681 # code (such as magics) needs access to it.
2682 2682 self.sys_excepthook = old_excepthook
2683 2683 outflag = 1 # happens in more places, so it's easier as default
2684 2684 try:
2685 2685 try:
2686 2686 self.hooks.pre_run_code_hook()
2687 2687 #rprint('Running code', repr(code_obj)) # dbg
2688 2688 exec code_obj in self.user_global_ns, self.user_ns
2689 2689 finally:
2690 2690 # Reset our crash handler in place
2691 2691 sys.excepthook = old_excepthook
2692 2692 except SystemExit:
2693 2693 self.showtraceback(exception_only=True)
2694 2694 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2695 2695 except self.custom_exceptions:
2696 2696 etype,value,tb = sys.exc_info()
2697 2697 self.CustomTB(etype,value,tb)
2698 2698 except:
2699 2699 self.showtraceback()
2700 2700 else:
2701 2701 outflag = 0
2702 2702 return outflag
2703 2703
2704 2704 # For backwards compatibility
2705 2705 runcode = run_code
2706 2706
2707 2707 #-------------------------------------------------------------------------
2708 2708 # Things related to GUI support and pylab
2709 2709 #-------------------------------------------------------------------------
2710 2710
2711 2711 def enable_gui(self, gui=None):
2712 2712 raise NotImplementedError('Implement enable_gui in a subclass')
2713 2713
2714 2714 def enable_pylab(self, gui=None, import_all=True):
2715 2715 """Activate pylab support at runtime.
2716 2716
2717 2717 This turns on support for matplotlib, preloads into the interactive
2718 2718 namespace all of numpy and pylab, and configures IPython to correctly
2719 2719 interact with the GUI event loop. The GUI backend to be used can be
2720 2720 optionally selected with the optional :param:`gui` argument.
2721 2721
2722 2722 Parameters
2723 2723 ----------
2724 2724 gui : optional, string
2725 2725
2726 2726 If given, dictates the choice of matplotlib GUI backend to use
2727 2727 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2728 2728 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2729 2729 matplotlib (as dictated by the matplotlib build-time options plus the
2730 2730 user's matplotlibrc configuration file). Note that not all backends
2731 2731 make sense in all contexts, for example a terminal ipython can't
2732 2732 display figures inline.
2733 2733 """
2734 2734 from IPython.core.pylabtools import mpl_runner
2735 2735 # We want to prevent the loading of pylab to pollute the user's
2736 2736 # namespace as shown by the %who* magics, so we execute the activation
2737 2737 # code in an empty namespace, and we update *both* user_ns and
2738 2738 # user_ns_hidden with this information.
2739 2739 ns = {}
2740 2740 try:
2741 2741 gui = pylab_activate(ns, gui, import_all, self)
2742 2742 except KeyError:
2743 2743 error("Backend %r not supported" % gui)
2744 2744 return
2745 2745 self.user_ns.update(ns)
2746 2746 self.user_ns_hidden.update(ns)
2747 2747 # Now we must activate the gui pylab wants to use, and fix %run to take
2748 2748 # plot updates into account
2749 2749 self.enable_gui(gui)
2750 2750 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2751 2751 mpl_runner(self.safe_execfile)
2752 2752
2753 2753 #-------------------------------------------------------------------------
2754 2754 # Utilities
2755 2755 #-------------------------------------------------------------------------
2756 2756
2757 2757 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2758 2758 """Expand python variables in a string.
2759 2759
2760 2760 The depth argument indicates how many frames above the caller should
2761 2761 be walked to look for the local namespace where to expand variables.
2762 2762
2763 2763 The global namespace for expansion is always the user's interactive
2764 2764 namespace.
2765 2765 """
2766 2766 ns = self.user_ns.copy()
2767 2767 ns.update(sys._getframe(depth+1).f_locals)
2768 2768 ns.pop('self', None)
2769 2769 try:
2770 2770 cmd = formatter.format(cmd, **ns)
2771 2771 except Exception:
2772 2772 # if formatter couldn't format, just let it go untransformed
2773 2773 pass
2774 2774 return cmd
2775 2775
2776 2776 def mktempfile(self, data=None, prefix='ipython_edit_'):
2777 2777 """Make a new tempfile and return its filename.
2778 2778
2779 2779 This makes a call to tempfile.mktemp, but it registers the created
2780 2780 filename internally so ipython cleans it up at exit time.
2781 2781
2782 2782 Optional inputs:
2783 2783
2784 2784 - data(None): if data is given, it gets written out to the temp file
2785 2785 immediately, and the file is closed again."""
2786 2786
2787 2787 filename = tempfile.mktemp('.py', prefix)
2788 2788 self.tempfiles.append(filename)
2789 2789
2790 2790 if data:
2791 2791 tmp_file = open(filename,'w')
2792 2792 tmp_file.write(data)
2793 2793 tmp_file.close()
2794 2794 return filename
2795 2795
2796 2796 # TODO: This should be removed when Term is refactored.
2797 2797 def write(self,data):
2798 2798 """Write a string to the default output"""
2799 2799 io.stdout.write(data)
2800 2800
2801 2801 # TODO: This should be removed when Term is refactored.
2802 2802 def write_err(self,data):
2803 2803 """Write a string to the default error output"""
2804 2804 io.stderr.write(data)
2805 2805
2806 2806 def ask_yes_no(self, prompt, default=None):
2807 2807 if self.quiet:
2808 2808 return True
2809 2809 return ask_yes_no(prompt,default)
2810 2810
2811 2811 def show_usage(self):
2812 2812 """Show a usage message"""
2813 2813 page.page(IPython.core.usage.interactive_usage)
2814 2814
2815 2815 def extract_input_lines(self, range_str, raw=False):
2816 2816 """Return as a string a set of input history slices.
2817 2817
2818 2818 Parameters
2819 2819 ----------
2820 2820 range_str : string
2821 2821 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
2822 2822 since this function is for use by magic functions which get their
2823 2823 arguments as strings. The number before the / is the session
2824 2824 number: ~n goes n back from the current session.
2825 2825
2826 2826 Optional Parameters:
2827 2827 - raw(False): by default, the processed input is used. If this is
2828 2828 true, the raw input history is used instead.
2829 2829
2830 2830 Note that slices can be called with two notations:
2831 2831
2832 2832 N:M -> standard python form, means including items N...(M-1).
2833 2833
2834 2834 N-M -> include items N..M (closed endpoint)."""
2835 2835 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
2836 2836 return "\n".join(x for _, _, x in lines)
2837 2837
2838 2838 def find_user_code(self, target, raw=True, py_only=False):
2839 2839 """Get a code string from history, file, url, or a string or macro.
2840 2840
2841 2841 This is mainly used by magic functions.
2842 2842
2843 2843 Parameters
2844 2844 ----------
2845 2845
2846 2846 target : str
2847 2847
2848 2848 A string specifying code to retrieve. This will be tried respectively
2849 2849 as: ranges of input history (see %history for syntax), url,
2850 2850 correspnding .py file, filename, or an expression evaluating to a
2851 2851 string or Macro in the user namespace.
2852 2852
2853 2853 raw : bool
2854 2854 If true (default), retrieve raw history. Has no effect on the other
2855 2855 retrieval mechanisms.
2856 2856
2857 2857 py_only : bool (default False)
2858 2858 Only try to fetch python code, do not try alternative methods to decode file
2859 2859 if unicode fails.
2860 2860
2861 2861 Returns
2862 2862 -------
2863 2863 A string of code.
2864 2864
2865 2865 ValueError is raised if nothing is found, and TypeError if it evaluates
2866 2866 to an object of another type. In each case, .args[0] is a printable
2867 2867 message.
2868 2868 """
2869 2869 code = self.extract_input_lines(target, raw=raw) # Grab history
2870 2870 if code:
2871 2871 return code
2872 2872 utarget = unquote_filename(target)
2873 2873 try:
2874 2874 if utarget.startswith(('http://', 'https://')):
2875 2875 return openpy.read_py_url(utarget, skip_encoding_cookie=True)
2876 2876 except UnicodeDecodeError:
2877 2877 if not py_only :
2878 2878 response = urllib.urlopen(target)
2879 2879 return response.read().decode('latin1')
2880 2880 raise ValueError(("'%s' seem to be unreadable.") % utarget)
2881 2881
2882 2882 potential_target = [target]
2883 2883 try :
2884 2884 potential_target.insert(0,get_py_filename(target))
2885 2885 except IOError:
2886 2886 pass
2887 2887
2888 2888 for tgt in potential_target :
2889 2889 if os.path.isfile(tgt): # Read file
2890 2890 try :
2891 2891 return openpy.read_py_file(tgt, skip_encoding_cookie=True)
2892 2892 except UnicodeDecodeError :
2893 2893 if not py_only :
2894 2894 with io_open(tgt,'r', encoding='latin1') as f :
2895 2895 return f.read()
2896 2896 raise ValueError(("'%s' seem to be unreadable.") % target)
2897 2897
2898 2898 try: # User namespace
2899 2899 codeobj = eval(target, self.user_ns)
2900 2900 except Exception:
2901 2901 raise ValueError(("'%s' was not found in history, as a file, url, "
2902 2902 "nor in the user namespace.") % target)
2903 2903 if isinstance(codeobj, basestring):
2904 2904 return codeobj
2905 2905 elif isinstance(codeobj, Macro):
2906 2906 return codeobj.value
2907 2907
2908 2908 raise TypeError("%s is neither a string nor a macro." % target,
2909 2909 codeobj)
2910 2910
2911 2911 #-------------------------------------------------------------------------
2912 2912 # Things related to IPython exiting
2913 2913 #-------------------------------------------------------------------------
2914 2914 def atexit_operations(self):
2915 2915 """This will be executed at the time of exit.
2916 2916
2917 2917 Cleanup operations and saving of persistent data that is done
2918 2918 unconditionally by IPython should be performed here.
2919 2919
2920 2920 For things that may depend on startup flags or platform specifics (such
2921 2921 as having readline or not), register a separate atexit function in the
2922 2922 code that has the appropriate information, rather than trying to
2923 2923 clutter
2924 2924 """
2925 2925 # Close the history session (this stores the end time and line count)
2926 2926 # this must be *before* the tempfile cleanup, in case of temporary
2927 2927 # history db
2928 2928 self.history_manager.end_session()
2929 2929
2930 2930 # Cleanup all tempfiles left around
2931 2931 for tfile in self.tempfiles:
2932 2932 try:
2933 2933 os.unlink(tfile)
2934 2934 except OSError:
2935 2935 pass
2936 2936
2937 2937 # Clear all user namespaces to release all references cleanly.
2938 2938 self.reset(new_session=False)
2939 2939
2940 2940 # Run user hooks
2941 2941 self.hooks.shutdown_hook()
2942 2942
2943 2943 def cleanup(self):
2944 2944 self.restore_sys_module_state()
2945 2945
2946 2946
2947 2947 class InteractiveShellABC(object):
2948 2948 """An abstract base class for InteractiveShell."""
2949 2949 __metaclass__ = abc.ABCMeta
2950 2950
2951 2951 InteractiveShellABC.register(InteractiveShell)
@@ -1,1099 +1,992 b''
1 1 """Magic functions for InteractiveShell.
2 2 """
3 3
4 4 #-----------------------------------------------------------------------------
5 5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 6 # Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
7 7 # Copyright (C) 2008 The IPython Development Team
8 8
9 9 # Distributed under the terms of the BSD License. The full license is in
10 10 # the file COPYING, distributed as part of this software.
11 11 #-----------------------------------------------------------------------------
12 12
13 13 #-----------------------------------------------------------------------------
14 14 # Imports
15 15 #-----------------------------------------------------------------------------
16 16
17 17 # Stdlib
18 18 import __builtin__ as builtin_mod
19 19 import bdb
20 20 import gc
21 21 import inspect
22 22 import io
23 23 import json
24 24 import os
25 25 import re
26 26 import sys
27 27 import time
28 28 from StringIO import StringIO
29 29 from pprint import pformat
30 30 from urllib2 import urlopen
31 31
32 32 # cProfile was added in Python2.5
33 33 try:
34 34 import cProfile as profile
35 35 import pstats
36 36 except ImportError:
37 37 # profile isn't bundled by default in Debian for license reasons
38 38 try:
39 39 import profile, pstats
40 40 except ImportError:
41 41 profile = pstats = None
42 42
43 43 # Our own packages
44 44 from IPython.config.application import Application
45 45 from IPython.core import debugger, oinspect
46 46 from IPython.core import page
47 47 from IPython.core.error import UsageError, StdinNotImplementedError, TryNext
48 48 from IPython.core.macro import Macro
49 49 from IPython.core.magic import (Bunch, Magics, compress_dhist,
50 50 on_off, needs_local_scope,
51 51 register_magics, line_magic, cell_magic)
52 52 from IPython.testing.skipdoctest import skip_doctest
53 53 from IPython.utils import openpy
54 54 from IPython.utils import py3compat
55 55 from IPython.utils.encoding import DEFAULT_ENCODING
56 56 from IPython.utils.io import file_read, nlprint
57 57 from IPython.utils.ipstruct import Struct
58 58 from IPython.utils.module_paths import find_mod
59 59 from IPython.utils.path import get_py_filename, unquote_filename
60 60 from IPython.utils.process import abbrev_cwd
61 61 from IPython.utils.terminal import set_term_title
62 62 from IPython.utils.timing import clock, clock2
63 63 from IPython.utils.warn import warn, error
64 64
65 65 #-----------------------------------------------------------------------------
66 66 # Magic implementation classes
67 67 #-----------------------------------------------------------------------------
68 68
69 69 @register_magics
70 class AutoMagics(Magics):
71 """Magics that control various autoX behaviors."""
72
73 def __init__(self, shell):
74 super(AutoMagics, self).__init__(shell)
75 # namespace for holding state we may need
76 self._magic_state = Bunch()
77
78 @line_magic
79 def automagic(self, parameter_s=''):
80 """Make magic functions callable without having to type the initial %.
81
82 Without argumentsl toggles on/off (when off, you must call it as
83 %automagic, of course). With arguments it sets the value, and you can
84 use any of (case insensitive):
85
86 - on, 1, True: to activate
87
88 - off, 0, False: to deactivate.
89
90 Note that magic functions have lowest priority, so if there's a
91 variable whose name collides with that of a magic fn, automagic won't
92 work for that function (you get the variable instead). However, if you
93 delete the variable (del var), the previously shadowed magic function
94 becomes visible to automagic again."""
95
96 arg = parameter_s.lower()
97 mman = self.shell.magics_manager
98 if arg in ('on', '1', 'true'):
99 val = True
100 elif arg in ('off', '0', 'false'):
101 val = False
102 else:
103 val = not mman.auto_magic
104 mman.auto_magic = val
105 print '\n' + self.shell.magics_manager.auto_status()
106
107 @skip_doctest
108 @line_magic
109 def autocall(self, parameter_s=''):
110 """Make functions callable without having to type parentheses.
111
112 Usage:
113
114 %autocall [mode]
115
116 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
117 value is toggled on and off (remembering the previous state).
118
119 In more detail, these values mean:
120
121 0 -> fully disabled
122
123 1 -> active, but do not apply if there are no arguments on the line.
124
125 In this mode, you get::
126
127 In [1]: callable
128 Out[1]: <built-in function callable>
129
130 In [2]: callable 'hello'
131 ------> callable('hello')
132 Out[2]: False
133
134 2 -> Active always. Even if no arguments are present, the callable
135 object is called::
136
137 In [2]: float
138 ------> float()
139 Out[2]: 0.0
140
141 Note that even with autocall off, you can still use '/' at the start of
142 a line to treat the first argument on the command line as a function
143 and add parentheses to it::
144
145 In [8]: /str 43
146 ------> str(43)
147 Out[8]: '43'
148
149 # all-random (note for auto-testing)
150 """
151
152 if parameter_s:
153 arg = int(parameter_s)
154 else:
155 arg = 'toggle'
156
157 if not arg in (0, 1, 2,'toggle'):
158 error('Valid modes: (0->Off, 1->Smart, 2->Full')
159 return
160
161 if arg in (0, 1, 2):
162 self.shell.autocall = arg
163 else: # toggle
164 if self.shell.autocall:
165 self._magic_state.autocall_save = self.shell.autocall
166 self.shell.autocall = 0
167 else:
168 try:
169 self.shell.autocall = self._magic_state.autocall_save
170 except AttributeError:
171 self.shell.autocall = self._magic_state.autocall_save = 1
172
173 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
174
175
176 @register_magics
177 70 class OSMagics(Magics):
178 71 """Magics to interact with the underlying OS (shell-type functionality).
179 72 """
180 73
181 74 @skip_doctest
182 75 @line_magic
183 76 def alias(self, parameter_s=''):
184 77 """Define an alias for a system command.
185 78
186 79 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
187 80
188 81 Then, typing 'alias_name params' will execute the system command 'cmd
189 82 params' (from your underlying operating system).
190 83
191 84 Aliases have lower precedence than magic functions and Python normal
192 85 variables, so if 'foo' is both a Python variable and an alias, the
193 86 alias can not be executed until 'del foo' removes the Python variable.
194 87
195 88 You can use the %l specifier in an alias definition to represent the
196 89 whole line when the alias is called. For example::
197 90
198 91 In [2]: alias bracket echo "Input in brackets: <%l>"
199 92 In [3]: bracket hello world
200 93 Input in brackets: <hello world>
201 94
202 95 You can also define aliases with parameters using %s specifiers (one
203 96 per parameter)::
204 97
205 98 In [1]: alias parts echo first %s second %s
206 99 In [2]: %parts A B
207 100 first A second B
208 101 In [3]: %parts A
209 102 Incorrect number of arguments: 2 expected.
210 103 parts is an alias to: 'echo first %s second %s'
211 104
212 105 Note that %l and %s are mutually exclusive. You can only use one or
213 106 the other in your aliases.
214 107
215 108 Aliases expand Python variables just like system calls using ! or !!
216 109 do: all expressions prefixed with '$' get expanded. For details of
217 110 the semantic rules, see PEP-215:
218 111 http://www.python.org/peps/pep-0215.html. This is the library used by
219 112 IPython for variable expansion. If you want to access a true shell
220 113 variable, an extra $ is necessary to prevent its expansion by
221 114 IPython::
222 115
223 116 In [6]: alias show echo
224 117 In [7]: PATH='A Python string'
225 118 In [8]: show $PATH
226 119 A Python string
227 120 In [9]: show $$PATH
228 121 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
229 122
230 123 You can use the alias facility to acess all of $PATH. See the %rehash
231 124 and %rehashx functions, which automatically create aliases for the
232 125 contents of your $PATH.
233 126
234 127 If called with no parameters, %alias prints the current alias table."""
235 128
236 129 par = parameter_s.strip()
237 130 if not par:
238 131 aliases = sorted(self.shell.alias_manager.aliases)
239 132 # stored = self.shell.db.get('stored_aliases', {} )
240 133 # for k, v in stored:
241 134 # atab.append(k, v[0])
242 135
243 136 print "Total number of aliases:", len(aliases)
244 137 sys.stdout.flush()
245 138 return aliases
246 139
247 140 # Now try to define a new one
248 141 try:
249 142 alias,cmd = par.split(None, 1)
250 143 except:
251 144 print oinspect.getdoc(self.alias)
252 145 else:
253 146 self.shell.alias_manager.soft_define_alias(alias, cmd)
254 147 # end magic_alias
255 148
256 149 @line_magic
257 150 def unalias(self, parameter_s=''):
258 151 """Remove an alias"""
259 152
260 153 aname = parameter_s.strip()
261 154 self.shell.alias_manager.undefine_alias(aname)
262 155 stored = self.shell.db.get('stored_aliases', {} )
263 156 if aname in stored:
264 157 print "Removing %stored alias",aname
265 158 del stored[aname]
266 159 self.shell.db['stored_aliases'] = stored
267 160
268 161 @line_magic
269 162 def rehashx(self, parameter_s=''):
270 163 """Update the alias table with all executable files in $PATH.
271 164
272 165 This version explicitly checks that every entry in $PATH is a file
273 166 with execute access (os.X_OK), so it is much slower than %rehash.
274 167
275 168 Under Windows, it checks executability as a match against a
276 169 '|'-separated string of extensions, stored in the IPython config
277 170 variable win_exec_ext. This defaults to 'exe|com|bat'.
278 171
279 172 This function also resets the root module cache of module completer,
280 173 used on slow filesystems.
281 174 """
282 175 from IPython.core.alias import InvalidAliasError
283 176
284 177 # for the benefit of module completer in ipy_completers.py
285 178 del self.shell.db['rootmodules']
286 179
287 180 path = [os.path.abspath(os.path.expanduser(p)) for p in
288 181 os.environ.get('PATH','').split(os.pathsep)]
289 182 path = filter(os.path.isdir,path)
290 183
291 184 syscmdlist = []
292 185 # Now define isexec in a cross platform manner.
293 186 if os.name == 'posix':
294 187 isexec = lambda fname:os.path.isfile(fname) and \
295 188 os.access(fname,os.X_OK)
296 189 else:
297 190 try:
298 191 winext = os.environ['pathext'].replace(';','|').replace('.','')
299 192 except KeyError:
300 193 winext = 'exe|com|bat|py'
301 194 if 'py' not in winext:
302 195 winext += '|py'
303 196 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
304 197 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
305 198 savedir = os.getcwdu()
306 199
307 200 # Now walk the paths looking for executables to alias.
308 201 try:
309 202 # write the whole loop for posix/Windows so we don't have an if in
310 203 # the innermost part
311 204 if os.name == 'posix':
312 205 for pdir in path:
313 206 os.chdir(pdir)
314 207 for ff in os.listdir(pdir):
315 208 if isexec(ff):
316 209 try:
317 210 # Removes dots from the name since ipython
318 211 # will assume names with dots to be python.
319 212 self.shell.alias_manager.define_alias(
320 213 ff.replace('.',''), ff)
321 214 except InvalidAliasError:
322 215 pass
323 216 else:
324 217 syscmdlist.append(ff)
325 218 else:
326 219 no_alias = self.shell.alias_manager.no_alias
327 220 for pdir in path:
328 221 os.chdir(pdir)
329 222 for ff in os.listdir(pdir):
330 223 base, ext = os.path.splitext(ff)
331 224 if isexec(ff) and base.lower() not in no_alias:
332 225 if ext.lower() == '.exe':
333 226 ff = base
334 227 try:
335 228 # Removes dots from the name since ipython
336 229 # will assume names with dots to be python.
337 230 self.shell.alias_manager.define_alias(
338 231 base.lower().replace('.',''), ff)
339 232 except InvalidAliasError:
340 233 pass
341 234 syscmdlist.append(ff)
342 235 self.shell.db['syscmdlist'] = syscmdlist
343 236 finally:
344 237 os.chdir(savedir)
345 238
346 239 @skip_doctest
347 240 @line_magic
348 241 def pwd(self, parameter_s=''):
349 242 """Return the current working directory path.
350 243
351 244 Examples
352 245 --------
353 246 ::
354 247
355 248 In [9]: pwd
356 249 Out[9]: '/home/tsuser/sprint/ipython'
357 250 """
358 251 return os.getcwdu()
359 252
360 253 @skip_doctest
361 254 @line_magic
362 255 def cd(self, parameter_s=''):
363 256 """Change the current working directory.
364 257
365 258 This command automatically maintains an internal list of directories
366 259 you visit during your IPython session, in the variable _dh. The
367 260 command %dhist shows this history nicely formatted. You can also
368 261 do 'cd -<tab>' to see directory history conveniently.
369 262
370 263 Usage:
371 264
372 265 cd 'dir': changes to directory 'dir'.
373 266
374 267 cd -: changes to the last visited directory.
375 268
376 269 cd -<n>: changes to the n-th directory in the directory history.
377 270
378 271 cd --foo: change to directory that matches 'foo' in history
379 272
380 273 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
381 274 (note: cd <bookmark_name> is enough if there is no
382 275 directory <bookmark_name>, but a bookmark with the name exists.)
383 276 'cd -b <tab>' allows you to tab-complete bookmark names.
384 277
385 278 Options:
386 279
387 280 -q: quiet. Do not print the working directory after the cd command is
388 281 executed. By default IPython's cd command does print this directory,
389 282 since the default prompts do not display path information.
390 283
391 284 Note that !cd doesn't work for this purpose because the shell where
392 285 !command runs is immediately discarded after executing 'command'.
393 286
394 287 Examples
395 288 --------
396 289 ::
397 290
398 291 In [10]: cd parent/child
399 292 /home/tsuser/parent/child
400 293 """
401 294
402 295 #bkms = self.shell.persist.get("bookmarks",{})
403 296
404 297 oldcwd = os.getcwdu()
405 298 numcd = re.match(r'(-)(\d+)$',parameter_s)
406 299 # jump in directory history by number
407 300 if numcd:
408 301 nn = int(numcd.group(2))
409 302 try:
410 303 ps = self.shell.user_ns['_dh'][nn]
411 304 except IndexError:
412 305 print 'The requested directory does not exist in history.'
413 306 return
414 307 else:
415 308 opts = {}
416 309 elif parameter_s.startswith('--'):
417 310 ps = None
418 311 fallback = None
419 312 pat = parameter_s[2:]
420 313 dh = self.shell.user_ns['_dh']
421 314 # first search only by basename (last component)
422 315 for ent in reversed(dh):
423 316 if pat in os.path.basename(ent) and os.path.isdir(ent):
424 317 ps = ent
425 318 break
426 319
427 320 if fallback is None and pat in ent and os.path.isdir(ent):
428 321 fallback = ent
429 322
430 323 # if we have no last part match, pick the first full path match
431 324 if ps is None:
432 325 ps = fallback
433 326
434 327 if ps is None:
435 328 print "No matching entry in directory history"
436 329 return
437 330 else:
438 331 opts = {}
439 332
440 333
441 334 else:
442 335 #turn all non-space-escaping backslashes to slashes,
443 336 # for c:\windows\directory\names\
444 337 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
445 338 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
446 339 # jump to previous
447 340 if ps == '-':
448 341 try:
449 342 ps = self.shell.user_ns['_dh'][-2]
450 343 except IndexError:
451 344 raise UsageError('%cd -: No previous directory to change to.')
452 345 # jump to bookmark if needed
453 346 else:
454 347 if not os.path.isdir(ps) or opts.has_key('b'):
455 348 bkms = self.shell.db.get('bookmarks', {})
456 349
457 350 if bkms.has_key(ps):
458 351 target = bkms[ps]
459 352 print '(bookmark:%s) -> %s' % (ps,target)
460 353 ps = target
461 354 else:
462 355 if opts.has_key('b'):
463 356 raise UsageError("Bookmark '%s' not found. "
464 357 "Use '%%bookmark -l' to see your bookmarks." % ps)
465 358
466 359 # strip extra quotes on Windows, because os.chdir doesn't like them
467 360 ps = unquote_filename(ps)
468 361 # at this point ps should point to the target dir
469 362 if ps:
470 363 try:
471 364 os.chdir(os.path.expanduser(ps))
472 365 if hasattr(self.shell, 'term_title') and self.shell.term_title:
473 366 set_term_title('IPython: ' + abbrev_cwd())
474 367 except OSError:
475 368 print sys.exc_info()[1]
476 369 else:
477 370 cwd = os.getcwdu()
478 371 dhist = self.shell.user_ns['_dh']
479 372 if oldcwd != cwd:
480 373 dhist.append(cwd)
481 374 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
482 375
483 376 else:
484 377 os.chdir(self.shell.home_dir)
485 378 if hasattr(self.shell, 'term_title') and self.shell.term_title:
486 379 set_term_title('IPython: ' + '~')
487 380 cwd = os.getcwdu()
488 381 dhist = self.shell.user_ns['_dh']
489 382
490 383 if oldcwd != cwd:
491 384 dhist.append(cwd)
492 385 self.shell.db['dhist'] = compress_dhist(dhist)[-100:]
493 386 if not 'q' in opts and self.shell.user_ns['_dh']:
494 387 print self.shell.user_ns['_dh'][-1]
495 388
496 389
497 390 @line_magic
498 391 def env(self, parameter_s=''):
499 392 """List environment variables."""
500 393
501 394 return dict(os.environ)
502 395
503 396 @line_magic
504 397 def pushd(self, parameter_s=''):
505 398 """Place the current dir on stack and change directory.
506 399
507 400 Usage:\\
508 401 %pushd ['dirname']
509 402 """
510 403
511 404 dir_s = self.shell.dir_stack
512 405 tgt = os.path.expanduser(unquote_filename(parameter_s))
513 406 cwd = os.getcwdu().replace(self.shell.home_dir,'~')
514 407 if tgt:
515 408 self.cd(parameter_s)
516 409 dir_s.insert(0,cwd)
517 410 return self.shell.magic('dirs')
518 411
519 412 @line_magic
520 413 def popd(self, parameter_s=''):
521 414 """Change to directory popped off the top of the stack.
522 415 """
523 416 if not self.shell.dir_stack:
524 417 raise UsageError("%popd on empty stack")
525 418 top = self.shell.dir_stack.pop(0)
526 419 self.cd(top)
527 420 print "popd ->",top
528 421
529 422 @line_magic
530 423 def dirs(self, parameter_s=''):
531 424 """Return the current directory stack."""
532 425
533 426 return self.shell.dir_stack
534 427
535 428 @line_magic
536 429 def dhist(self, parameter_s=''):
537 430 """Print your history of visited directories.
538 431
539 432 %dhist -> print full history\\
540 433 %dhist n -> print last n entries only\\
541 434 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
542 435
543 436 This history is automatically maintained by the %cd command, and
544 437 always available as the global list variable _dh. You can use %cd -<n>
545 438 to go to directory number <n>.
546 439
547 440 Note that most of time, you should view directory history by entering
548 441 cd -<TAB>.
549 442
550 443 """
551 444
552 445 dh = self.shell.user_ns['_dh']
553 446 if parameter_s:
554 447 try:
555 448 args = map(int,parameter_s.split())
556 449 except:
557 450 self.arg_err(self.dhist)
558 451 return
559 452 if len(args) == 1:
560 453 ini,fin = max(len(dh)-(args[0]),0),len(dh)
561 454 elif len(args) == 2:
562 455 ini,fin = args
563 456 else:
564 457 self.arg_err(self.dhist)
565 458 return
566 459 else:
567 460 ini,fin = 0,len(dh)
568 461 nlprint(dh,
569 462 header = 'Directory history (kept in _dh)',
570 463 start=ini,stop=fin)
571 464
572 465 @skip_doctest
573 466 @line_magic
574 467 def sc(self, parameter_s=''):
575 468 """Shell capture - execute a shell command and capture its output.
576 469
577 470 DEPRECATED. Suboptimal, retained for backwards compatibility.
578 471
579 472 You should use the form 'var = !command' instead. Example:
580 473
581 474 "%sc -l myfiles = ls ~" should now be written as
582 475
583 476 "myfiles = !ls ~"
584 477
585 478 myfiles.s, myfiles.l and myfiles.n still apply as documented
586 479 below.
587 480
588 481 --
589 482 %sc [options] varname=command
590 483
591 484 IPython will run the given command using commands.getoutput(), and
592 485 will then update the user's interactive namespace with a variable
593 486 called varname, containing the value of the call. Your command can
594 487 contain shell wildcards, pipes, etc.
595 488
596 489 The '=' sign in the syntax is mandatory, and the variable name you
597 490 supply must follow Python's standard conventions for valid names.
598 491
599 492 (A special format without variable name exists for internal use)
600 493
601 494 Options:
602 495
603 496 -l: list output. Split the output on newlines into a list before
604 497 assigning it to the given variable. By default the output is stored
605 498 as a single string.
606 499
607 500 -v: verbose. Print the contents of the variable.
608 501
609 502 In most cases you should not need to split as a list, because the
610 503 returned value is a special type of string which can automatically
611 504 provide its contents either as a list (split on newlines) or as a
612 505 space-separated string. These are convenient, respectively, either
613 506 for sequential processing or to be passed to a shell command.
614 507
615 508 For example::
616 509
617 510 # Capture into variable a
618 511 In [1]: sc a=ls *py
619 512
620 513 # a is a string with embedded newlines
621 514 In [2]: a
622 515 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
623 516
624 517 # which can be seen as a list:
625 518 In [3]: a.l
626 519 Out[3]: ['setup.py', 'win32_manual_post_install.py']
627 520
628 521 # or as a whitespace-separated string:
629 522 In [4]: a.s
630 523 Out[4]: 'setup.py win32_manual_post_install.py'
631 524
632 525 # a.s is useful to pass as a single command line:
633 526 In [5]: !wc -l $a.s
634 527 146 setup.py
635 528 130 win32_manual_post_install.py
636 529 276 total
637 530
638 531 # while the list form is useful to loop over:
639 532 In [6]: for f in a.l:
640 533 ...: !wc -l $f
641 534 ...:
642 535 146 setup.py
643 536 130 win32_manual_post_install.py
644 537
645 538 Similarly, the lists returned by the -l option are also special, in
646 539 the sense that you can equally invoke the .s attribute on them to
647 540 automatically get a whitespace-separated string from their contents::
648 541
649 542 In [7]: sc -l b=ls *py
650 543
651 544 In [8]: b
652 545 Out[8]: ['setup.py', 'win32_manual_post_install.py']
653 546
654 547 In [9]: b.s
655 548 Out[9]: 'setup.py win32_manual_post_install.py'
656 549
657 550 In summary, both the lists and strings used for output capture have
658 551 the following special attributes::
659 552
660 553 .l (or .list) : value as list.
661 554 .n (or .nlstr): value as newline-separated string.
662 555 .s (or .spstr): value as space-separated string.
663 556 """
664 557
665 558 opts,args = self.parse_options(parameter_s,'lv')
666 559 # Try to get a variable name and command to run
667 560 try:
668 561 # the variable name must be obtained from the parse_options
669 562 # output, which uses shlex.split to strip options out.
670 563 var,_ = args.split('=',1)
671 564 var = var.strip()
672 565 # But the command has to be extracted from the original input
673 566 # parameter_s, not on what parse_options returns, to avoid the
674 567 # quote stripping which shlex.split performs on it.
675 568 _,cmd = parameter_s.split('=',1)
676 569 except ValueError:
677 570 var,cmd = '',''
678 571 # If all looks ok, proceed
679 572 split = 'l' in opts
680 573 out = self.shell.getoutput(cmd, split=split)
681 574 if opts.has_key('v'):
682 575 print '%s ==\n%s' % (var,pformat(out))
683 576 if var:
684 577 self.shell.user_ns.update({var:out})
685 578 else:
686 579 return out
687 580
688 581 @line_magic
689 582 def sx(self, parameter_s=''):
690 583 """Shell execute - run a shell command and capture its output.
691 584
692 585 %sx command
693 586
694 587 IPython will run the given command using commands.getoutput(), and
695 588 return the result formatted as a list (split on '\\n'). Since the
696 589 output is _returned_, it will be stored in ipython's regular output
697 590 cache Out[N] and in the '_N' automatic variables.
698 591
699 592 Notes:
700 593
701 594 1) If an input line begins with '!!', then %sx is automatically
702 595 invoked. That is, while::
703 596
704 597 !ls
705 598
706 599 causes ipython to simply issue system('ls'), typing::
707 600
708 601 !!ls
709 602
710 603 is a shorthand equivalent to::
711 604
712 605 %sx ls
713 606
714 607 2) %sx differs from %sc in that %sx automatically splits into a list,
715 608 like '%sc -l'. The reason for this is to make it as easy as possible
716 609 to process line-oriented shell output via further python commands.
717 610 %sc is meant to provide much finer control, but requires more
718 611 typing.
719 612
720 613 3) Just like %sc -l, this is a list with special attributes:
721 614 ::
722 615
723 616 .l (or .list) : value as list.
724 617 .n (or .nlstr): value as newline-separated string.
725 618 .s (or .spstr): value as whitespace-separated string.
726 619
727 620 This is very useful when trying to use such lists as arguments to
728 621 system commands."""
729 622
730 623 if parameter_s:
731 624 return self.shell.getoutput(parameter_s)
732 625
733 626
734 627 @line_magic
735 628 def bookmark(self, parameter_s=''):
736 629 """Manage IPython's bookmark system.
737 630
738 631 %bookmark <name> - set bookmark to current dir
739 632 %bookmark <name> <dir> - set bookmark to <dir>
740 633 %bookmark -l - list all bookmarks
741 634 %bookmark -d <name> - remove bookmark
742 635 %bookmark -r - remove all bookmarks
743 636
744 637 You can later on access a bookmarked folder with::
745 638
746 639 %cd -b <name>
747 640
748 641 or simply '%cd <name>' if there is no directory called <name> AND
749 642 there is such a bookmark defined.
750 643
751 644 Your bookmarks persist through IPython sessions, but they are
752 645 associated with each profile."""
753 646
754 647 opts,args = self.parse_options(parameter_s,'drl',mode='list')
755 648 if len(args) > 2:
756 649 raise UsageError("%bookmark: too many arguments")
757 650
758 651 bkms = self.shell.db.get('bookmarks',{})
759 652
760 653 if opts.has_key('d'):
761 654 try:
762 655 todel = args[0]
763 656 except IndexError:
764 657 raise UsageError(
765 658 "%bookmark -d: must provide a bookmark to delete")
766 659 else:
767 660 try:
768 661 del bkms[todel]
769 662 except KeyError:
770 663 raise UsageError(
771 664 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
772 665
773 666 elif opts.has_key('r'):
774 667 bkms = {}
775 668 elif opts.has_key('l'):
776 669 bks = bkms.keys()
777 670 bks.sort()
778 671 if bks:
779 672 size = max(map(len,bks))
780 673 else:
781 674 size = 0
782 675 fmt = '%-'+str(size)+'s -> %s'
783 676 print 'Current bookmarks:'
784 677 for bk in bks:
785 678 print fmt % (bk,bkms[bk])
786 679 else:
787 680 if not args:
788 681 raise UsageError("%bookmark: You must specify the bookmark name")
789 682 elif len(args)==1:
790 683 bkms[args[0]] = os.getcwdu()
791 684 elif len(args)==2:
792 685 bkms[args[0]] = args[1]
793 686 self.shell.db['bookmarks'] = bkms
794 687
795 688 @line_magic
796 689 def pycat(self, parameter_s=''):
797 690 """Show a syntax-highlighted file through a pager.
798 691
799 692 This magic is similar to the cat utility, but it will assume the file
800 693 to be Python source and will show it with syntax highlighting. """
801 694
802 695 try:
803 696 filename = get_py_filename(parameter_s)
804 697 cont = file_read(filename)
805 698 except IOError:
806 699 try:
807 700 cont = eval(parameter_s, self.shell.user_ns)
808 701 except NameError:
809 702 cont = None
810 703 if cont is None:
811 704 print "Error: no such file or variable"
812 705 return
813 706
814 707 page.page(self.shell.pycolorize(cont))
815 708
816 709
817 710 @register_magics
818 711 class LoggingMagics(Magics):
819 712 """Magics related to all logging machinery."""
820 713
821 714 @line_magic
822 715 def logstart(self, parameter_s=''):
823 716 """Start logging anywhere in a session.
824 717
825 718 %logstart [-o|-r|-t] [log_name [log_mode]]
826 719
827 720 If no name is given, it defaults to a file named 'ipython_log.py' in your
828 721 current directory, in 'rotate' mode (see below).
829 722
830 723 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
831 724 history up to that point and then continues logging.
832 725
833 726 %logstart takes a second optional parameter: logging mode. This can be one
834 727 of (note that the modes are given unquoted):\\
835 728 append: well, that says it.\\
836 729 backup: rename (if exists) to name~ and start name.\\
837 730 global: single logfile in your home dir, appended to.\\
838 731 over : overwrite existing log.\\
839 732 rotate: create rotating logs name.1~, name.2~, etc.
840 733
841 734 Options:
842 735
843 736 -o: log also IPython's output. In this mode, all commands which
844 737 generate an Out[NN] prompt are recorded to the logfile, right after
845 738 their corresponding input line. The output lines are always
846 739 prepended with a '#[Out]# ' marker, so that the log remains valid
847 740 Python code.
848 741
849 742 Since this marker is always the same, filtering only the output from
850 743 a log is very easy, using for example a simple awk call::
851 744
852 745 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
853 746
854 747 -r: log 'raw' input. Normally, IPython's logs contain the processed
855 748 input, so that user lines are logged in their final form, converted
856 749 into valid Python. For example, %Exit is logged as
857 750 _ip.magic("Exit"). If the -r flag is given, all input is logged
858 751 exactly as typed, with no transformations applied.
859 752
860 753 -t: put timestamps before each input line logged (these are put in
861 754 comments)."""
862 755
863 756 opts,par = self.parse_options(parameter_s,'ort')
864 757 log_output = 'o' in opts
865 758 log_raw_input = 'r' in opts
866 759 timestamp = 't' in opts
867 760
868 761 logger = self.shell.logger
869 762
870 763 # if no args are given, the defaults set in the logger constructor by
871 764 # ipython remain valid
872 765 if par:
873 766 try:
874 767 logfname,logmode = par.split()
875 768 except:
876 769 logfname = par
877 770 logmode = 'backup'
878 771 else:
879 772 logfname = logger.logfname
880 773 logmode = logger.logmode
881 774 # put logfname into rc struct as if it had been called on the command
882 775 # line, so it ends up saved in the log header Save it in case we need
883 776 # to restore it...
884 777 old_logfile = self.shell.logfile
885 778 if logfname:
886 779 logfname = os.path.expanduser(logfname)
887 780 self.shell.logfile = logfname
888 781
889 782 loghead = '# IPython log file\n\n'
890 783 try:
891 784 logger.logstart(logfname, loghead, logmode, log_output, timestamp,
892 785 log_raw_input)
893 786 except:
894 787 self.shell.logfile = old_logfile
895 788 warn("Couldn't start log: %s" % sys.exc_info()[1])
896 789 else:
897 790 # log input history up to this point, optionally interleaving
898 791 # output if requested
899 792
900 793 if timestamp:
901 794 # disable timestamping for the previous history, since we've
902 795 # lost those already (no time machine here).
903 796 logger.timestamp = False
904 797
905 798 if log_raw_input:
906 799 input_hist = self.shell.history_manager.input_hist_raw
907 800 else:
908 801 input_hist = self.shell.history_manager.input_hist_parsed
909 802
910 803 if log_output:
911 804 log_write = logger.log_write
912 805 output_hist = self.shell.history_manager.output_hist
913 806 for n in range(1,len(input_hist)-1):
914 807 log_write(input_hist[n].rstrip() + '\n')
915 808 if n in output_hist:
916 809 log_write(repr(output_hist[n]),'output')
917 810 else:
918 811 logger.log_write('\n'.join(input_hist[1:]))
919 812 logger.log_write('\n')
920 813 if timestamp:
921 814 # re-enable timestamping
922 815 logger.timestamp = True
923 816
924 817 print ('Activating auto-logging. '
925 818 'Current session state plus future input saved.')
926 819 logger.logstate()
927 820
928 821 @line_magic
929 822 def logstop(self, parameter_s=''):
930 823 """Fully stop logging and close log file.
931 824
932 825 In order to start logging again, a new %logstart call needs to be made,
933 826 possibly (though not necessarily) with a new filename, mode and other
934 827 options."""
935 828 self.logger.logstop()
936 829
937 830 @line_magic
938 831 def logoff(self, parameter_s=''):
939 832 """Temporarily stop logging.
940 833
941 834 You must have previously started logging."""
942 835 self.shell.logger.switch_log(0)
943 836
944 837 @line_magic
945 838 def logon(self, parameter_s=''):
946 839 """Restart logging.
947 840
948 841 This function is for restarting logging which you've temporarily
949 842 stopped with %logoff. For starting logging for the first time, you
950 843 must use the %logstart function, which allows you to specify an
951 844 optional log filename."""
952 845
953 846 self.shell.logger.switch_log(1)
954 847
955 848 @line_magic
956 849 def logstate(self, parameter_s=''):
957 850 """Print the status of the logging system."""
958 851
959 852 self.shell.logger.logstate()
960 853
961 854
962 855 @register_magics
963 856 class ExtensionsMagics(Magics):
964 857 """Magics to manage the IPython extensions system."""
965 858
966 859 @line_magic
967 860 def install_ext(self, parameter_s=''):
968 861 """Download and install an extension from a URL, e.g.::
969 862
970 863 %install_ext https://bitbucket.org/birkenfeld/ipython-physics/raw/d1310a2ab15d/physics.py
971 864
972 865 The URL should point to an importable Python module - either a .py file
973 866 or a .zip file.
974 867
975 868 Parameters:
976 869
977 870 -n filename : Specify a name for the file, rather than taking it from
978 871 the URL.
979 872 """
980 873 opts, args = self.parse_options(parameter_s, 'n:')
981 874 try:
982 875 filename = self.shell.extension_manager.install_extension(args,
983 876 opts.get('n'))
984 877 except ValueError as e:
985 878 print e
986 879 return
987 880
988 881 filename = os.path.basename(filename)
989 882 print "Installed %s. To use it, type:" % filename
990 883 print " %%load_ext %s" % os.path.splitext(filename)[0]
991 884
992 885
993 886 @line_magic
994 887 def load_ext(self, module_str):
995 888 """Load an IPython extension by its module name."""
996 889 return self.shell.extension_manager.load_extension(module_str)
997 890
998 891 @line_magic
999 892 def unload_ext(self, module_str):
1000 893 """Unload an IPython extension by its module name."""
1001 894 self.shell.extension_manager.unload_extension(module_str)
1002 895
1003 896 @line_magic
1004 897 def reload_ext(self, module_str):
1005 898 """Reload an IPython extension by its module name."""
1006 899 self.shell.extension_manager.reload_extension(module_str)
1007 900
1008 901
1009 902 @register_magics
1010 903 class PylabMagics(Magics):
1011 904 """Magics related to matplotlib's pylab support"""
1012 905
1013 906 @skip_doctest
1014 907 @line_magic
1015 908 def pylab(self, parameter_s=''):
1016 909 """Load numpy and matplotlib to work interactively.
1017 910
1018 911 %pylab [GUINAME]
1019 912
1020 913 This function lets you activate pylab (matplotlib, numpy and
1021 914 interactive support) at any point during an IPython session.
1022 915
1023 916 It will import at the top level numpy as np, pyplot as plt, matplotlib,
1024 917 pylab and mlab, as well as all names from numpy and pylab.
1025 918
1026 919 If you are using the inline matplotlib backend for embedded figures,
1027 920 you can adjust its behavior via the %config magic::
1028 921
1029 922 # enable SVG figures, necessary for SVG+XHTML export in the qtconsole
1030 923 In [1]: %config InlineBackend.figure_format = 'svg'
1031 924
1032 925 # change the behavior of closing all figures at the end of each
1033 926 # execution (cell), or allowing reuse of active figures across
1034 927 # cells:
1035 928 In [2]: %config InlineBackend.close_figures = False
1036 929
1037 930 Parameters
1038 931 ----------
1039 932 guiname : optional
1040 933 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk',
1041 934 'osx' or 'tk'). If given, the corresponding Matplotlib backend is
1042 935 used, otherwise matplotlib's default (which you can override in your
1043 936 matplotlib config file) is used.
1044 937
1045 938 Examples
1046 939 --------
1047 940 In this case, where the MPL default is TkAgg::
1048 941
1049 942 In [2]: %pylab
1050 943
1051 944 Welcome to pylab, a matplotlib-based Python environment.
1052 945 Backend in use: TkAgg
1053 946 For more information, type 'help(pylab)'.
1054 947
1055 948 But you can explicitly request a different backend::
1056 949
1057 950 In [3]: %pylab qt
1058 951
1059 952 Welcome to pylab, a matplotlib-based Python environment.
1060 953 Backend in use: Qt4Agg
1061 954 For more information, type 'help(pylab)'.
1062 955 """
1063 956
1064 957 if Application.initialized():
1065 958 app = Application.instance()
1066 959 try:
1067 960 import_all_status = app.pylab_import_all
1068 961 except AttributeError:
1069 962 import_all_status = True
1070 963 else:
1071 964 import_all_status = True
1072 965
1073 966 self.shell.enable_pylab(parameter_s, import_all=import_all_status)
1074 967
1075 968
1076 969 @register_magics
1077 970 class DeprecatedMagics(Magics):
1078 971 """Magics slated for later removal."""
1079 972
1080 973 @line_magic
1081 974 def install_profiles(self, parameter_s=''):
1082 975 """%install_profiles has been deprecated."""
1083 976 print '\n'.join([
1084 977 "%install_profiles has been deprecated.",
1085 978 "Use `ipython profile list` to view available profiles.",
1086 979 "Requesting a profile with `ipython profile create <name>`",
1087 980 "or `ipython --profile=<name>` will start with the bundled",
1088 981 "profile of that name if it exists."
1089 982 ])
1090 983
1091 984 @line_magic
1092 985 def install_default_config(self, parameter_s=''):
1093 986 """%install_default_config has been deprecated."""
1094 987 print '\n'.join([
1095 988 "%install_default_config has been deprecated.",
1096 989 "Use `ipython profile create <name>` to initialize a profile",
1097 990 "with the default config files.",
1098 991 "Add `--reset` to overwrite already existing config files with defaults."
1099 992 ])
@@ -1,34 +1,35 b''
1 1 """Implementation of all the magic functions built into IPython.
2 2 """
3 3 #-----------------------------------------------------------------------------
4 4 # Copyright (c) 2012, IPython Development Team.
5 5 #
6 6 # Distributed under the terms of the Modified BSD License.
7 7 #
8 8 # The full license is in the file COPYING.txt, distributed with this software.
9 9 #-----------------------------------------------------------------------------
10 10
11 11 #-----------------------------------------------------------------------------
12 12 # Imports
13 13 #-----------------------------------------------------------------------------
14 14
15 15 from IPython.core.magic import Magics, register_magics
16 from .auto import AutoMagics
16 17 from .basic import BasicMagics
17 18 from .code import CodeMagics, MacroToEdit
18 19 from .config import ConfigMagics
19 20 from .execution import ExecutionMagics
20 21 from .history import HistoryMagics
21 22 from .namespace import NamespaceMagics
22 23
23 24 #-----------------------------------------------------------------------------
24 25 # Magic implementation classes
25 26 #-----------------------------------------------------------------------------
26 27
27 28 @register_magics
28 29 class UserMagics(Magics):
29 30 """Placeholder for user-defined magics to be added at runtime.
30 31
31 32 All magics are eventually merged into a single namespace at runtime, but we
32 33 use this class to isolate the magics defined dynamically by the user into
33 34 their own class.
34 35 """
General Comments 0
You need to be logged in to leave comments. Login now