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