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