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