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