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