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