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