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