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