Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/IPython/core/interactiveshell.py: 21%

1"""Main IPython class."""

3#-----------------------------------------------------------------------------

8# Distributed under the terms of the BSD License. The full license is in

9# the file COPYING, distributed as part of this software.

10#-----------------------------------------------------------------------------

13import abc

14import ast

15import atexit

16import bdb

17import builtins as builtin_mod

18import functools

19import inspect

20import os

21import re

22import runpy

23import shutil

24import subprocess

25from subprocess import CalledProcessError

26import sys

27import tempfile

28import traceback

29import types

30import warnings

31from ast import stmt

32from contextlib import contextmanager

33from io import open as io_open

34from logging import error

35from pathlib import Path

36from collections.abc import Callable

37from typing import List as ListType, Any as AnyType

38from typing import Literal, Optional, Tuple

39from collections.abc import Sequence

40from warnings import warn

41import textwrap

43from IPython.external.pickleshare import PickleShareDB

45from tempfile import TemporaryDirectory

46from traitlets import (

47 Any,

48 Bool,

49 CaselessStrEnum,

50 Dict,

51 Enum,

52 Instance,

53 Integer,

54 List,

55 Type,

56 Unicode,

57 default,

58 observe,

59 validate,

60)

61from traitlets.config.configurable import SingletonConfigurable

62from traitlets.utils.importstring import import_item

64import IPython.core.hooks

65from IPython.core import magic, oinspect, page, prefilter, ultratb

66from IPython.core.alias import Alias, AliasManager

67from IPython.core.autocall import ExitAutocall

68from IPython.core.builtin_trap import BuiltinTrap

69from IPython.core.compilerop import CachingCompiler

70from IPython.core.debugger import InterruptiblePdb

71from IPython.core.display_trap import DisplayTrap

72from IPython.core.displayhook import DisplayHook

73from IPython.core.displaypub import DisplayPublisher

74from IPython.core.error import InputRejected, UsageError

75from IPython.core.events import EventManager, available_events

76from IPython.core.extensions import ExtensionManager

77from IPython.core.formatters import DisplayFormatter

78from IPython.core.history import HistoryManager, HistoryOutput

79from IPython.core.inputtransformer2 import ESC_MAGIC, ESC_MAGIC2

80from IPython.core.logger import Logger

81from IPython.core.macro import Macro

82from IPython.core.payload import PayloadManager

83from IPython.core.prefilter import PrefilterManager

84from IPython.core.profiledir import ProfileDir

85from IPython.core.tips import pick_tip

86from IPython.core.usage import default_banner

87from IPython.display import display

88from IPython.paths import get_ipython_dir

89from IPython.testing.skipdoctest import skip_doctest

90from IPython.utils import PyColorize, io, openpy, py3compat

91from IPython.utils.decorators import undoc

92from IPython.utils.io import ask_yes_no

93from IPython.utils.ipstruct import Struct

94from IPython.utils.path import ensure_dir_exists, get_home_dir, get_py_filename

95from IPython.utils.process import get_output_error_code, getoutput, system

96from IPython.utils.strdispatch import StrDispatch

97from IPython.utils.syspathcontext import prepended_to_syspath

98from IPython.utils.text import DollarFormatter, LSString, SList, format_screen

99from IPython.core.oinspect import OInfo

100

101

102sphinxify: Optional[Callable]

103

104try:

105 import docrepr.sphinxify as sphx

106

107 def sphinxify(oinfo):

108 wrapped_docstring = sphx.wrap_main_docstring(oinfo)

109

110 def sphinxify_docstring(docstring):

111 with TemporaryDirectory() as dirname:

112 return {

113 "text/html": sphx.sphinxify(wrapped_docstring, dirname),

114 "text/plain": docstring,

115 }

116

117 return sphinxify_docstring

118except ImportError:

119 sphinxify = None

120

121

122class ProvisionalWarning(DeprecationWarning):

123 """

124 Warning class for unstable features

125 """

126 pass

127

128from ast import Module

129

130_assign_nodes = (ast.AugAssign, ast.AnnAssign, ast.Assign)

131_single_targets_nodes = (ast.AugAssign, ast.AnnAssign)

132

133#-----------------------------------------------------------------------------

134# Await Helpers

135#-----------------------------------------------------------------------------

136

137# we still need to run things using the asyncio eventloop, but there is no

138# async integration

139from .async_helpers import (

140 _asyncio_runner,

141 _curio_runner,

142 _pseudo_sync_runner,

143 _should_be_async,

144 _trio_runner,

145)

146

147#-----------------------------------------------------------------------------

148# Globals

149#-----------------------------------------------------------------------------

150

151# compiled regexps for autoindent management

152dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')

153

154#-----------------------------------------------------------------------------

155# Utilities

156#-----------------------------------------------------------------------------

157

158

159def is_integer_string(s: str):

160 """

161 Variant of "str.isnumeric()" that allow negative values and other ints.

162 """

163 try:

164 int(s)

165 return True

166 except ValueError:

167 return False

168 raise ValueError("Unexpected error")

169

170

171@undoc

172def softspace(file, newvalue):

173 """Copied from code.py, to remove the dependency"""

174

175 oldvalue = 0

176 try:

177 oldvalue = file.softspace

178 except AttributeError:

179 pass

180 try:

181 file.softspace = newvalue

182 except (AttributeError, TypeError):

183 # "attribute-less object" or "read-only attributes"

184 pass

185 return oldvalue

186

187@undoc

188def no_op(*a, **kw):

189 pass

190

191

192class SpaceInInput(Exception): pass

193

194

195class SeparateUnicode(Unicode):

196 r"""A Unicode subclass to validate separate_in, separate_out, etc.

197

198 This is a Unicode based trait that converts '0'->'' and ``'\\n'->'\n'``.

199 """

200

201 def validate(self, obj, value):

202 if value == '0': value = ''

203 value = value.replace('\\n','\n')

204 return super(SeparateUnicode, self).validate(obj, value)

205

206

207class _IPythonMainModuleBase(types.ModuleType):

208 def __init__(self) -> None:

209 super().__init__(

210 "__main__",

211 doc="Automatically created module for the IPython interactive environment",

212 )

213

214

215def make_main_module_type(user_ns: dict[str, Any]) -> type[_IPythonMainModuleBase]:

216 @undoc

217 class IPythonMainModule(_IPythonMainModuleBase):

218 """

219 ModuleType that supports passing in a custom user namespace dictionary,

220 to be used for the module's __dict__. This is enabled by shadowing the

221 underlying __dict__ attribute of the module, and overriding getters and

222 setters to point to the custom user namespace dictionary.

223 The reason to do this is to allow the __main__ module to be an instance

224 of ModuleType, while still allowing the user namespace to be custom.

225 """

226

227 @property

228 def __dict__(self) -> dict[str, Any]: # type: ignore[override]

229 return user_ns

230

231 def __setattr__(self, item: str, value: Any) -> None:

232 if item == "__dict__":

233 # Ignore this when IPython tries to set it, since we already provide it

234 return

235 user_ns[item] = value

236

237 def __getattr__(self, item: str) -> Any:

238 try:

239 return user_ns[item]

240 except KeyError:

241 raise AttributeError(f"module {self.__name__} has no attribute {item}")

242

243 def __delattr__(self, item: str) -> None:

244 try:

245 del user_ns[item]

246 except KeyError:

247 raise AttributeError(f"module {self.__name__} has no attribute {item}")

248

249 return IPythonMainModule

250

251

252class ExecutionInfo:

253 """The arguments used for a call to :meth:`InteractiveShell.run_cell`

254

255 Stores information about what is going to happen.

256 """

257 raw_cell = None

258 transformed_cell = None

259 store_history = False

260 silent = False

261 shell_futures = True

262 cell_id = None

263

264 def __init__(

265 self,

266 raw_cell,

267 store_history,

268 silent,

269 shell_futures,

270 cell_id,

271 transformed_cell=None,

272 ):

273 self.raw_cell = raw_cell

274 self.transformed_cell = transformed_cell

275 self.store_history = store_history

276 self.silent = silent

277 self.shell_futures = shell_futures

278 self.cell_id = cell_id

279

280 def __repr__(self):

281 name = self.__class__.__qualname__

282 raw_cell = (

283 (self.raw_cell[:50] + "..") if len(self.raw_cell) > 50 else self.raw_cell

284 )

285 transformed_cell = (

286 (self.transformed_cell[:50] + "..")

287 if self.transformed_cell and len(self.transformed_cell) > 50

288 else self.transformed_cell

289 )

290 return (

291 '<%s object at %x, raw_cell="%s" transformed_cell="%s" store_history=%s silent=%s shell_futures=%s cell_id=%s>'

292 % (

293 name,

294 id(self),

295 raw_cell,

296 transformed_cell,

297 self.store_history,

298 self.silent,

299 self.shell_futures,

300 self.cell_id,

301 )

302 )

303

304

305class ExecutionResult:

306 """The result of a call to :meth:`InteractiveShell.run_cell`

307

308 Stores information about what took place.

309 """

310

311 execution_count: Optional[int] = None

312 error_before_exec: Optional[BaseException] = None

313 error_in_exec: Optional[BaseException] = None

314 info = None

315 result = None

316

317 def __init__(self, info):

318 self.info = info

319

320 @property

321 def success(self):

322 return (self.error_before_exec is None) and (self.error_in_exec is None)

323

324 def raise_error(self):

325 """Reraises error if `success` is `False`, otherwise does nothing"""

326 if self.error_before_exec is not None:

327 raise self.error_before_exec

328 if self.error_in_exec is not None:

329 raise self.error_in_exec

330

331 def __repr__(self):

332 name = self.__class__.__qualname__

333 return '<%s object at %x, execution_count=%s error_before_exec=%s error_in_exec=%s info=%s result=%s>' %\

334 (name, id(self), self.execution_count, self.error_before_exec, self.error_in_exec, repr(self.info), repr(self.result))

335

336

337@functools.wraps(io_open)

338def _modified_open(file, *args, **kwargs):

339 if file in {0, 1, 2}:

340 raise ValueError(

341 f"IPython won't let you open fd={file} by default "

342 "as it is likely to crash IPython. If you know what you are doing, "

343 "you can use builtins' open."

344 )

345

346 return io_open(file, *args, **kwargs)

347

348

349class InteractiveShell(SingletonConfigurable):

350 """An enhanced, interactive shell for Python."""

351

352 _instance = None

353 _user_ns: dict

354 _sys_modules_keys: set[str]

355

356 inspector: oinspect.Inspector

357

358 ast_transformers: List[ast.NodeTransformer] = List(

359 [],

360 help="""

361 A list of ast.NodeTransformer subclass instances, which will be applied

362 to user input before code is run.

363 """,

364 ).tag(config=True)

365

366 autocall = Enum((0,1,2), default_value=0, help=

367 """

368 Make IPython automatically call any callable object even if you didn't

369 type explicit parentheses. For example, 'str 43' becomes 'str(43)'

370 automatically. The value can be '0' to disable the feature, '1' for

371 'smart' autocall, where it is not applied if there are no more

372 arguments on the line, and '2' for 'full' autocall, where all callable

373 objects are automatically called (even if no arguments are present).

374 """

375 ).tag(config=True)

376

377 autoindent = Bool(True, help=

378 """

379 Autoindent IPython code entered interactively.

380 """

381 ).tag(config=True)

382

383 autoawait = Bool(True, help=

384 """

385 Automatically run await statement in the top level repl.

386 """

387 ).tag(config=True)

388

389 loop_runner_map ={

390 'asyncio':(_asyncio_runner, True),

391 'curio':(_curio_runner, True),

392 'trio':(_trio_runner, True),

393 'sync': (_pseudo_sync_runner, False)

394 }

395

396 loop_runner = Any(default_value="IPython.core.interactiveshell._asyncio_runner",

397 allow_none=True,

398 help="""Select the loop runner that will be used to execute top-level asynchronous code"""

399 ).tag(config=True)

400

401 @default('loop_runner')

402 def _default_loop_runner(self):

403 return import_item("IPython.core.interactiveshell._asyncio_runner")

404

405 @validate('loop_runner')

406 def _import_runner(self, proposal):

407 if isinstance(proposal.value, str):

408 if proposal.value in self.loop_runner_map:

409 runner, autoawait = self.loop_runner_map[proposal.value]

410 self.autoawait = autoawait

411 return runner

412 runner = import_item(proposal.value)

413 if not callable(runner):

414 raise ValueError('loop_runner must be callable')

415 return runner

416 if not callable(proposal.value):

417 raise ValueError('loop_runner must be callable')

418 return proposal.value

419

420 automagic = Bool(True, help=

421 """

422 Enable magic commands to be called without the leading %.

423 """

424 ).tag(config=True)

425

426 enable_tip = Bool(

427 True,

428 help="""

429 Set to show a tip when IPython starts.""",

430 ).tag(config=True)

431

432 banner1 = Unicode(default_banner,

433 help="""The part of the banner to be printed before the profile"""

434 ).tag(config=True)

435 banner2 = Unicode('',

436 help="""The part of the banner to be printed after the profile"""

437 ).tag(config=True)

438

439 cache_size = Integer(

440 1000,

441 help="""

442 Set the size of the output cache. The default is 1000, you can

443 change it permanently in your config file. Setting it to 0 completely

444 disables the caching system, and the minimum value accepted is 3 (if

445 you provide a value less than 3, it is reset to 0 and a warning is

446 issued). This limit is defined because otherwise you'll spend more

447 time re-flushing a too small cache than working

448 """,

449 ).tag(config=True)

450 debug = Bool(False).tag(config=True)

451 display_formatter = Instance(DisplayFormatter, allow_none=True)

452 displayhook_class = Type(DisplayHook)

453 display_pub_class = Type(DisplayPublisher)

454 compiler_class = Type(CachingCompiler)

455 inspector_class = Type(

456 oinspect.Inspector, help="Class to use to instantiate the shell inspector"

457 ).tag(config=True)

458

459 sphinxify_docstring = Bool(False, help=

460 """

461 Enables rich html representation of docstrings. (This requires the

462 docrepr module).

463 """).tag(config=True)

464

465 @observe("sphinxify_docstring")

466 def _sphinxify_docstring_changed(self, change):

467 if change['new']:

468 warn("`sphinxify_docstring` is provisional since IPython 5.0 and might change in future versions." , ProvisionalWarning)

469

470 enable_html_pager = Bool(False, help=

471 """

472 (Provisional API) enables html representation in mime bundles sent

473 to pagers.

474 """).tag(config=True)

475

476 @observe("enable_html_pager")

477 def _enable_html_pager_changed(self, change):

478 if change['new']:

479 warn("`enable_html_pager` is provisional since IPython 5.0 and might change in future versions.", ProvisionalWarning)

480

481 data_pub_class = None

482

483 exit_now = Bool(False)

484 exiter = Instance(ExitAutocall)

485 @default('exiter')

486 def _exiter_default(self):

487 return ExitAutocall(self)

488 # Monotonically increasing execution counter

489 execution_count = Integer(1)

490 filename = Unicode("<ipython console>")

491 ipython_dir = Unicode("").tag(config=True) # Set to get_ipython_dir() in __init__

492

493 # Used to transform cells before running them, and check whether code is complete

494 input_transformer_manager = Instance('IPython.core.inputtransformer2.TransformerManager',

495 ())

496

497 @property

498 def input_transformers_cleanup(self):

499 return self.input_transformer_manager.cleanup_transforms

500

501 input_transformers_post: List = List(

502 [],

503 help="A list of string input transformers, to be applied after IPython's "

504 "own input transformations."

505 )

506

507 logstart = Bool(False, help=

508 """

509 Start logging to the default log file in overwrite mode.

510 Use `logappend` to specify a log file to **append** logs to.

511 """

512 ).tag(config=True)

513 logfile = Unicode('', help=

514 """

515 The name of the logfile to use.

516 """

517 ).tag(config=True)

518 logappend = Unicode('', help=

519 """

520 Start logging to the given file in append mode.

521 Use `logfile` to specify a log file to **overwrite** logs to.

522 """

523 ).tag(config=True)

524 object_info_string_level = Enum((0,1,2), default_value=0,

525 ).tag(config=True)

526 pdb = Bool(False, help=

527 """

528 Automatically call the pdb debugger after every exception.

529 """

530 ).tag(config=True)

531 display_page = Bool(False,

532 help="""If True, anything that would be passed to the pager

533 will be displayed as regular output instead."""

534 ).tag(config=True)

535

536

537 show_rewritten_input = Bool(True,

538 help="Show rewritten input, e.g. for autocall."

539 ).tag(config=True)

540

541 quiet = Bool(False).tag(config=True)

542

543 system_raise_on_error = Bool(False, help=

544 """

545 Raise an exception on non-zero exit status from shell commands executed

546 via the `!` operator. When set to True, shell commands that fail will raise

547 CalledProcessError, similar to the behavior of %%script magics.

548 """

549 ).tag(config=True)

550

551 history_length = Integer(10000,

552 help='Total length of command history'

553 ).tag(config=True)

554

555 history_load_length = Integer(1000, help=

556 """

557 The number of saved history entries to be loaded

558 into the history buffer at startup.

559 """

560 ).tag(config=True)

561

562 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none', 'last_expr_or_assign'],

563 default_value='last_expr',

564 help="""

565 'all', 'last', 'last_expr' or 'none', 'last_expr_or_assign' specifying

566 which nodes should be run interactively (displaying output from expressions).

567 """

568 ).tag(config=True)

569

570 warn_venv = Bool(

571 True,

572 help="Warn if running in a virtual environment with no IPython installed (so IPython from the global environment is used).",

573 ).tag(config=True)

574

575 # TODO: this part of prompt management should be moved to the frontends.

576 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'

577 separate_in = SeparateUnicode('\n').tag(config=True)

578 separate_out = SeparateUnicode('').tag(config=True)

579 separate_out2 = SeparateUnicode('').tag(config=True)

580 wildcards_case_sensitive = Bool(True).tag(config=True)

581 xmode = CaselessStrEnum(

582 ("Context", "Plain", "Verbose", "Minimal", "Docs"),

583 default_value="Context",

584 help="Switch modes for the IPython exception handlers.",

585 ).tag(config=True)

586

587 # Subcomponents of InteractiveShell

588 alias_manager = Instance("IPython.core.alias.AliasManager", allow_none=True)

589 prefilter_manager = Instance(

590 "IPython.core.prefilter.PrefilterManager", allow_none=True

591 )

592 builtin_trap = Instance("IPython.core.builtin_trap.BuiltinTrap")

593 display_trap = Instance("IPython.core.display_trap.DisplayTrap")

594 extension_manager = Instance(

595 "IPython.core.extensions.ExtensionManager", allow_none=True

596 )

597 payload_manager = Instance("IPython.core.payload.PayloadManager", allow_none=True)

598 history_manager = Instance(

599 "IPython.core.history.HistoryAccessorBase", allow_none=True

600 )

601 magics_manager = Instance("IPython.core.magic.MagicsManager")

602

603 profile_dir = Instance('IPython.core.application.ProfileDir', allow_none=True)

604 @property

605 def profile(self):

606 if self.profile_dir is not None:

607 name = os.path.basename(self.profile_dir.location)

608 return name.replace('profile_','')

609

610

611 # Private interface

612 _post_execute = Dict()

613

614 # Tracks any GUI loop loaded for pylab

615 pylab_gui_select = None

616

617 last_execution_succeeded = Bool(True, help='Did last executed command succeeded')

618

619 last_execution_result = Instance('IPython.core.interactiveshell.ExecutionResult', help='Result of executing the last command', allow_none=True)

620

621 def __init__(self, ipython_dir=None, profile_dir=None,

622 user_module=None, user_ns=None,

623 custom_exceptions=((), None), **kwargs):

624 # This is where traits with a config_key argument are updated

625 # from the values on config.

626 super(InteractiveShell, self).__init__(**kwargs)

627 self.configurables = [self]

628

629 # These are relatively independent and stateless

630 self.init_ipython_dir(ipython_dir)

631 self.init_profile_dir(profile_dir)

632 self.init_instance_attrs()

633 self.init_environment()

634

635 # Check if we're in a virtualenv, and set up sys.path.

636 self.init_virtualenv()

637

638 # Create namespaces (user_ns, user_global_ns, etc.)

639 self.init_create_namespaces(user_module, user_ns)

640 # This has to be done after init_create_namespaces because it uses

641 # something in self.user_ns, but before init_sys_modules, which

642 # is the first thing to modify sys.

643 # TODO: When we override sys.stdout and sys.stderr before this class

644 # is created, we are saving the overridden ones here. Not sure if this

645 # is what we want to do.

646 self.save_sys_module_state()

647 self.init_sys_modules()

648

649 # While we're trying to have each part of the code directly access what

650 # it needs without keeping redundant references to objects, we have too

651 # much legacy code that expects ip.db to exist.

652 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))

653

654 self.init_history()

655 self.init_encoding()

656 self.init_prefilter()

657

658 self.init_syntax_highlighting()

659 self.init_hooks()

660 self.init_events()

661 self.init_pushd_popd_magic()

662 self.init_user_ns()

663 self.init_logger()

664 self.init_builtins()

665

666 # The following was in post_config_initialization

667 self.raw_input_original = input

668 self.init_completer()

669 # TODO: init_io() needs to happen before init_traceback handlers

670 # because the traceback handlers hardcode the stdout/stderr streams.

671 # This logic in in debugger.Pdb and should eventually be changed.

672 self.init_io()

673 self.init_traceback_handlers(custom_exceptions)

674 self.init_prompts()

675 self.init_display_formatter()

676 self.init_display_pub()

677 self.init_data_pub()

678 self.init_displayhook()

679 self.init_magics()

680 self.init_alias()

681 self.init_logstart()

682 self.init_pdb()

683 self.init_extension_manager()

684 self.init_payload()

685 self.events.trigger('shell_initialized', self)

686 atexit.register(self.atexit_operations)

687

688 # The trio runner is used for running Trio in the foreground thread. It

689 # is different from `_trio_runner(async_fn)` in `async_helpers.py`

690 # which calls `trio.run()` for every cell. This runner runs all cells

691 # inside a single Trio event loop. If used, it is set from

692 # `ipykernel.kernelapp`.

693 self.trio_runner = None

694 self.showing_traceback = False

695

696 @property

697 def user_ns(self):

698 return self._user_ns

699

700 @user_ns.setter

701 def user_ns(self, ns: dict):

702 assert hasattr(ns, "clear")

703 assert isinstance(ns, dict)

704 self._user_ns = ns

705

706 def get_ipython(self):

707 """Return the currently running IPython instance."""

708 return self

709

710 #-------------------------------------------------------------------------

711 # Trait changed handlers

712 #-------------------------------------------------------------------------

713 @observe('ipython_dir')

714 def _ipython_dir_changed(self, change):

715 ensure_dir_exists(change['new'])

716

717 def set_autoindent(self,value=None):

718 """Set the autoindent flag.

719

720 If called with no arguments, it acts as a toggle."""

721 if value is None:

722 self.autoindent = not self.autoindent

723 else:

724 self.autoindent = value

725

726 def set_trio_runner(self, tr):

727 self.trio_runner = tr

728

729 #-------------------------------------------------------------------------

730 # init_* methods called by __init__

731 #-------------------------------------------------------------------------

732

733 def init_ipython_dir(self, ipython_dir):

734 if ipython_dir is not None:

735 self.ipython_dir = ipython_dir

736 return

737

738 self.ipython_dir = get_ipython_dir()

739

740 def init_profile_dir(self, profile_dir):

741 if profile_dir is not None:

742 self.profile_dir = profile_dir

743 return

744 self.profile_dir = ProfileDir.create_profile_dir_by_name(

745 self.ipython_dir, "default"

746 )

747

748 def init_instance_attrs(self):

749 self.more = False

750

751 # command compiler

752 self.compile = self.compiler_class()

753

754 # Make an empty namespace, which extension writers can rely on both

755 # existing and NEVER being used by ipython itself. This gives them a

756 # convenient location for storing additional information and state

757 # their extensions may require, without fear of collisions with other

758 # ipython names that may develop later.

759 self.meta = Struct()

760

761 # Temporary files used for various purposes. Deleted at exit.

762 # The files here are stored with Path from Pathlib

763 self.tempfiles = []

764 self.tempdirs = []

765

766 # keep track of where we started running (mainly for crash post-mortem)

767 # This is not being used anywhere currently.

768 self.starting_dir = os.getcwd()

769

770 # Indentation management

771 self.indent_current_nsp = 0

772

773 # Dict to track post-execution functions that have been registered

774 self._post_execute = {}

775

776 def init_environment(self):

777 """Any changes we need to make to the user's environment."""

778 pass

779

780 def init_encoding(self):

781 # Get system encoding at startup time. Certain terminals (like Emacs

782 # under Win32 have it set to None, and we need to have a known valid

783 # encoding to use in the raw_input() method

784 try:

785 self.stdin_encoding = sys.stdin.encoding or 'ascii'

786 except AttributeError:

787 self.stdin_encoding = 'ascii'

788

789 colors = Unicode(

790 "neutral", help="Set the color scheme (nocolor, neutral, linux, lightbg)."

791 ).tag(config=True)

792

793 @validate("colors")

794 def _check_colors(self, proposal):

795 new = proposal["value"]

796 if not new == new.lower():

797 warn(

798 f"`TerminalInteractiveShell.colors` is now lowercase: `{new.lower()}`,"

799 " non lowercase, may be invalid in the future.",

800 DeprecationWarning,

801 stacklevel=2,

802 )

803 return new.lower()

804

805 @observe("colors")

806 def init_syntax_highlighting(self, changes=None):

807 # Python source parser/formatter for syntax highlighting

808 pyformat = PyColorize.Parser(theme_name=self.colors).format

809 self.pycolorize = lambda src: pyformat(src, "str")

810 if not hasattr(self, "inspector"):

811 self.inspector = self.inspector_class(

812 theme_name=self.colors,

813 str_detail_level=self.object_info_string_level,

814 parent=self,

815 )

816

817 try:

818 # Deprecation in 9.0, colors should always be lower

819 self.inspector.set_theme_name(self.colors.lower())

820 except Exception:

821 warn(

822 "Error changing object inspector color schemes.\n%s"

823 % (sys.exc_info()[1]),

824 stacklevel=2,

825 )

826 if hasattr(self, "InteractiveTB"):

827 self.InteractiveTB.set_theme_name(self.colors)

828 if hasattr(self, "SyntaxTB"):

829 self.SyntaxTB.set_theme_name(self.colors)

830 self.refresh_style()

831

832 def refresh_style(self):

833 # No-op here, used in subclass

834 pass

835

836 def init_pushd_popd_magic(self):

837 # for pushd/popd management

838 self.home_dir = get_home_dir()

839

840 self.dir_stack = []

841

842 def init_logger(self) -> None:

843 self.logger = Logger(self.home_dir, logfname='ipython_log.py',

844 logmode='rotate')

845

846 def init_logstart(self) -> None:

847 """Initialize logging in case it was requested at the command line.

848 """

849 if self.logappend:

850 self.run_line_magic("logstart", f"{self.logappend} append")

851 elif self.logfile:

852 self.run_line_magic("logstart", self.logfile)

853 elif self.logstart:

854 self.run_line_magic("logstart", "")

855

856 def init_builtins(self):

857 # A single, static flag that we set to True. Its presence indicates

858 # that an IPython shell has been created, and we make no attempts at

859 # removing on exit or representing the existence of more than one

860 # IPython at a time.

861 builtin_mod.__dict__['__IPYTHON__'] = True

862 builtin_mod.__dict__['display'] = display

863

864 self.builtin_trap = BuiltinTrap(shell=self)

865

866

867 def init_io(self):

868 # implemented in subclasses, TerminalInteractiveShell does call

869 # colorama.init().

870 pass

871

872 def init_prompts(self):

873 # Set system prompts, so that scripts can decide if they are running

874 # interactively.

875 sys.ps1 = 'In : '

876 sys.ps2 = '...: '

877 sys.ps3 = 'Out: '

878

879 def init_display_formatter(self):

880 self.display_formatter = DisplayFormatter(parent=self)

881 self.configurables.append(self.display_formatter)

882

883 def init_display_pub(self):

884 self.display_pub = self.display_pub_class(parent=self, shell=self)

885 self.configurables.append(self.display_pub)

886

887 def init_data_pub(self):

888 if not self.data_pub_class:

889 self.data_pub = None

890 return

891 self.data_pub = self.data_pub_class(parent=self)

892 self.configurables.append(self.data_pub)

893

894 def init_displayhook(self):

895 # Initialize displayhook, set in/out prompts and printing system

896 self.displayhook = self.displayhook_class(

897 parent=self,

898 shell=self,

899 cache_size=self.cache_size,

900 )

901 self.configurables.append(self.displayhook)

902 # This is a context manager that installs/removes the displayhook at

903 # the appropriate time.

904 self.display_trap = DisplayTrap(hook=self.displayhook)

905

906 @staticmethod

907 def get_path_links(p: Path):

908 """Gets path links including all symlinks

909

910 Examples

911 --------

912 In [1]: from IPython.core.interactiveshell import InteractiveShell

913

914 In [2]: import sys, pathlib

915

916 In [3]: paths = InteractiveShell.get_path_links(pathlib.Path(sys.executable))

917

918 In [4]: len(paths) == len(set(paths))

919 Out[4]: True

920

921 In [5]: bool(paths)

922 Out[5]: True

923 """

924 paths = [p]

925 while p.is_symlink():

926 new_path = Path(os.readlink(p))

927 if not new_path.is_absolute():

928 new_path = p.parent / new_path

929 p = new_path

930 paths.append(p)

931 return paths

932

933 def init_virtualenv(self):

934 """Add the current virtualenv to sys.path so the user can import modules from it.

935 This isn't perfect: it doesn't use the Python interpreter with which the

936 virtualenv was built, and it ignores the --no-site-packages option. A

937 warning will appear suggesting the user installs IPython in the

938 virtualenv, but for many cases, it probably works well enough.

939

940 Adapted from code snippets online.

941

942 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv

943 """

944 if 'VIRTUAL_ENV' not in os.environ:

945 # Not in a virtualenv

946 return

947 elif os.environ["VIRTUAL_ENV"] == "":

948 warn("Virtual env path set to '', please check if this is intended.")

949 return

950

951 p = Path(sys.executable)

952 p_venv = Path(os.environ["VIRTUAL_ENV"]).resolve()

953

954 # fallback venv detection:

955 # stdlib venv may symlink sys.executable, so we can't use realpath.

956 # but others can symlink *to* the venv Python, so we can't just use sys.executable.

957 # So we just check every item in the symlink tree (generally <= 3)

958 paths = self.get_path_links(p)

959

960 # In Cygwin paths like "c:\..." and '\cygdrive\c\...' are possible

961 if len(p_venv.parts) > 2 and p_venv.parts[1] == "cygdrive":

962 drive_name = p_venv.parts[2]

963 p_venv = (drive_name + ":/") / Path(*p_venv.parts[3:])

964

965 if any(p_venv == p.parents[1].resolve() for p in paths):

966 # Our exe is inside or has access to the virtualenv, don't need to do anything.

967 return

968

969 if sys.platform == "win32":

970 virtual_env = str(Path(os.environ["VIRTUAL_ENV"], "Lib", "site-packages"))

971 else:

972 virtual_env_path = Path(

973 os.environ["VIRTUAL_ENV"], "lib", "python{}.{}", "site-packages"

974 )

975 p_ver = sys.version_info[:2]

976

977 # Predict version from py[thon]-x.x in the $VIRTUAL_ENV

978 re_m = re.search(r"\bpy(?:thon)?([23])\.(\d+)\b", os.environ["VIRTUAL_ENV"])

979 if re_m:

980 predicted_path = Path(str(virtual_env_path).format(*re_m.groups()))

981 if predicted_path.exists():

982 p_ver = re_m.groups()

983

984 virtual_env = str(virtual_env_path).format(*p_ver)

985 if self.warn_venv:

986 warn(

987 "Attempting to work in a virtualenv. If you encounter problems, "

988 "please install IPython inside the virtualenv."

989 )

990 import site

991 sys.path.insert(0, virtual_env)

992 site.addsitedir(virtual_env)

993

994 #-------------------------------------------------------------------------

995 # Things related to injections into the sys module

996 #-------------------------------------------------------------------------

997

998 def save_sys_module_state(self):

999 """Save the state of hooks in the sys module.

1000

1001 This has to be called after self.user_module is created.

1002 """

1003 self._orig_sys_module_state = {'stdin': sys.stdin,

1004 'stdout': sys.stdout,

1005 'stderr': sys.stderr,

1006 'excepthook': sys.excepthook}

1007 self._orig_sys_modules_main_name = self.user_module.__name__

1008 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)

1009

1010 def restore_sys_module_state(self):

1011 """Restore the state of the sys module."""

1012 try:

1013 for k, v in self._orig_sys_module_state.items():

1014 setattr(sys, k, v)

1015 except AttributeError:

1016 pass

1017 # Reset what what done in self.init_sys_modules

1018 if self._orig_sys_modules_main_mod is not None:

1019 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod

1020

1021 #-------------------------------------------------------------------------

1022 # Things related to the banner

1023 #-------------------------------------------------------------------------

1024

1025 @property

1026 def banner(self):

1027 if (when := os.environ.get("SOURCE_DATE_EPOCH", None)) is not None:

1028 from datetime import datetime

1029

1030 date = datetime.fromtimestamp(int(when))

1031 return textwrap.dedent(

1032 f"""

1033 Python 3.y.z | Packaged with love | (main, {date.strftime("%A, %d %B %Y")}) [Compiler]

1034 Type 'copyright', 'credits' or 'license' for more information

1035 IPython 9.y.z -- An enhanced Interactive Python. Type '?' for help.

1036 Tip: unset SOURCE_DATE_EPOCH to restore dynamic banner.

1037 """

1038 ).lstrip()

1039 banner = self.banner1

1040 if self.profile and self.profile != 'default':

1041 banner += '\nIPython profile: %s\n' % self.profile

1042 if self.banner2:

1043 banner += '\n' + self.banner2

1044 elif self.enable_tip:

1045 banner += "Tip: {tip}\n".format(tip=pick_tip())

1046 return banner

1047

1048 def show_banner(self, banner=None):

1049 if banner is None:

1050 banner = self.banner

1051 print(banner, end="")

1052

1053 #-------------------------------------------------------------------------

1054 # Things related to hooks

1055 #-------------------------------------------------------------------------

1056

1057 def init_hooks(self):

1058 # hooks holds pointers used for user-side customizations

1059 self.hooks = Struct()

1060

1061 self.strdispatchers = {}

1062

1063 # Set all default hooks, defined in the IPython.hooks module.

1064 hooks = IPython.core.hooks

1065 for hook_name in hooks.__all__:

1066 # default hooks have priority 100, i.e. low; user hooks should have

1067 # 0-100 priority

1068 self.set_hook(hook_name, getattr(hooks, hook_name), 100)

1069

1070 if self.display_page:

1071 self.set_hook('show_in_pager', page.as_hook(page.display_page), 90)

1072

1073 def set_hook(self, name, hook, priority=50, str_key=None, re_key=None):

1074 """set_hook(name,hook) -> sets an internal IPython hook.

1075

1076 IPython exposes some of its internal API as user-modifiable hooks. By

1077 adding your function to one of these hooks, you can modify IPython's

1078 behavior to call at runtime your own routines."""

1079

1080 # At some point in the future, this should validate the hook before it

1081 # accepts it. Probably at least check that the hook takes the number

1082 # of args it's supposed to.

1083

1084 f = types.MethodType(hook,self)

1085

1086 # check if the hook is for strdispatcher first

1087 if str_key is not None:

1088 sdp = self.strdispatchers.get(name, StrDispatch())

1089 sdp.add_s(str_key, f, priority )

1090 self.strdispatchers[name] = sdp

1091 return

1092 if re_key is not None:

1093 sdp = self.strdispatchers.get(name, StrDispatch())

1094 sdp.add_re(re.compile(re_key), f, priority )

1095 self.strdispatchers[name] = sdp

1096 return

1097

1098 dp = getattr(self.hooks, name, None)

1099 if name not in IPython.core.hooks.__all__:

1100 print("Warning! Hook '%s' is not one of %s" % \

1101 (name, IPython.core.hooks.__all__ ))

1102

1103 if not dp:

1104 dp = IPython.core.hooks.CommandChainDispatcher()

1105

1106 try:

1107 dp.add(f,priority)

1108 except AttributeError:

1109 # it was not commandchain, plain old func - replace

1110 dp = f

1111

1112 setattr(self.hooks,name, dp)

1113

1114 #-------------------------------------------------------------------------

1115 # Things related to events

1116 #-------------------------------------------------------------------------

1117

1118 def init_events(self):

1119 self.events = EventManager(self, available_events)

1120

1121 self.events.register("pre_execute", self._clear_warning_registry)

1122

1123 def _clear_warning_registry(self):

1124 # clear the warning registry, so that different code blocks with

1125 # overlapping line number ranges don't cause spurious suppression of

1126 # warnings (see gh-6611 for details)

1127 if "__warningregistry__" in self.user_global_ns:

1128 del self.user_global_ns["__warningregistry__"]

1129

1130 #-------------------------------------------------------------------------

1131 # Things related to the "main" module

1132 #-------------------------------------------------------------------------

1133

1134 def new_main_mod(self, filename, modname):

1135 """Return a new 'main' module object for user code execution.

1136

1137 ``filename`` should be the path of the script which will be run in the

1138 module. Requests with the same filename will get the same module, with

1139 its namespace cleared.

1140

1141 ``modname`` should be the module name - normally either '__main__' or

1142 the basename of the file without the extension.

1143

1144 When scripts are executed via %run, we must keep a reference to their

1145 __main__ module around so that Python doesn't

1146 clear it, rendering references to module globals useless.

1147

1148 This method keeps said reference in a private dict, keyed by the

1149 absolute path of the script. This way, for multiple executions of the

1150 same script we only keep one copy of the namespace (the last one),

1151 thus preventing memory leaks from old references while allowing the

1152 objects from the last execution to be accessible.

1153 """

1154 filename = os.path.abspath(filename)

1155 try:

1156 main_mod = self._main_mod_cache[filename]

1157 except KeyError:

1158 main_mod = self._main_mod_cache[filename] = types.ModuleType(

1159 modname,

1160 doc="Module created for script run in IPython")

1161 else:

1162 main_mod.__dict__.clear()

1163 main_mod.__name__ = modname

1164

1165 main_mod.__file__ = filename

1166 # It seems pydoc (and perhaps others) needs any module instance to

1167 # implement a __nonzero__ method

1168 main_mod.__nonzero__ = lambda : True

1169

1170 return main_mod

1171

1172 def clear_main_mod_cache(self):

1173 """Clear the cache of main modules.

1174

1175 Mainly for use by utilities like %reset.

1176

1177 Examples

1178 --------

1179 In [15]: import IPython

1180

1181 In [16]: m = _ip.new_main_mod(IPython.__file__, 'IPython')

1182

1183 In [17]: len(_ip._main_mod_cache) > 0

1184 Out[17]: True

1185

1186 In [18]: _ip.clear_main_mod_cache()

1187

1188 In [19]: len(_ip._main_mod_cache) == 0

1189 Out[19]: True

1190 """

1191 self._main_mod_cache.clear()

1192

1193 #-------------------------------------------------------------------------

1194 # Things related to debugging

1195 #-------------------------------------------------------------------------

1196

1197 def init_pdb(self):

1198 # Set calling of pdb on exceptions

1199 # self.call_pdb is a property

1200 self.call_pdb = self.pdb

1201

1202 def _get_call_pdb(self):

1203 return self._call_pdb

1204

1205 def _set_call_pdb(self,val):

1206

1207 if val not in (0,1,False,True):

1208 raise ValueError('new call_pdb value must be boolean')

1209

1210 # store value in instance

1211 self._call_pdb = val

1212

1213 # notify the actual exception handlers

1214 self.InteractiveTB.call_pdb = val

1215

1216 call_pdb = property(_get_call_pdb,_set_call_pdb,None,

1217 'Control auto-activation of pdb at exceptions')

1218

1219 def debugger(self,force=False):

1220 """Call the pdb debugger.

1221

1222 Keywords:

1223

1224 - force(False): by default, this routine checks the instance call_pdb

1225 flag and does not actually invoke the debugger if the flag is false.

1226 The 'force' option forces the debugger to activate even if the flag

1227 is false.

1228 """

1229

1230 if not (force or self.call_pdb):

1231 return

1232

1233 if not hasattr(sys,'last_traceback'):

1234 error('No traceback has been produced, nothing to debug.')

1235 return

1236

1237 self.InteractiveTB.debugger(force=True)

1238

1239 #-------------------------------------------------------------------------

1240 # Things related to IPython's various namespaces

1241 #-------------------------------------------------------------------------

1242 default_user_namespaces = True

1243

1244 def init_create_namespaces(self, user_module=None, user_ns=None):

1245 # Create the namespace where the user will operate. user_ns is

1246 # normally the only one used, and it is passed to the exec calls as

1247 # the locals argument. But we do carry a user_global_ns namespace

1248 # given as the exec 'globals' argument, This is useful in embedding

1249 # situations where the ipython shell opens in a context where the

1250 # distinction between locals and globals is meaningful. For

1251 # non-embedded contexts, it is just the same object as the user_ns dict.

1252

1253 # FIXME. For some strange reason, __builtins__ is showing up at user

1254 # level as a dict instead of a module. This is a manual fix, but I

1255 # should really track down where the problem is coming from. Alex

1256 # Schmolck reported this problem first.

1257

1258 # A useful post by Alex Martelli on this topic:

1259 # Re: inconsistent value from __builtins__

1260 # Von: Alex Martelli <aleaxit@yahoo.com>

1261 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends

1262 # Gruppen: comp.lang.python

1263

1264 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:

1265 # > >>> print type(builtin_check.get_global_binding('__builtins__'))

1266 # > <type 'dict'>

1267 # > >>> print type(__builtins__)

1268 # > <type 'module'>

1269 # > Is this difference in return value intentional?

1270

1271 # Well, it's documented that '__builtins__' can be either a dictionary

1272 # or a module, and it's been that way for a long time. Whether it's

1273 # intentional (or sensible), I don't know. In any case, the idea is

1274 # that if you need to access the built-in namespace directly, you

1275 # should start with "import __builtin__" (note, no 's') which will

1276 # definitely give you a module. Yeah, it's somewhat confusing:-(.

1277

1278 # These routines return a properly built module and dict as needed by

1279 # the rest of the code, and can also be used by extension writers to

1280 # generate properly initialized namespaces.

1281 if (user_ns is not None) or (user_module is not None):

1282 self.default_user_namespaces = False

1283 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)

1284

1285 # A record of hidden variables we have added to the user namespace, so

1286 # we can list later only variables defined in actual interactive use.

1287 self.user_ns_hidden = {}

1288

1289 # Now that FakeModule produces a real module, we've run into a nasty

1290 # problem: after script execution (via %run), the module where the user

1291 # code ran is deleted. Now that this object is a true module (needed

1292 # so doctest and other tools work correctly), the Python module

1293 # teardown mechanism runs over it, and sets to None every variable

1294 # present in that module. Top-level references to objects from the

1295 # script survive, because the user_ns is updated with them. However,

1296 # calling functions defined in the script that use other things from

1297 # the script will fail, because the function's closure had references

1298 # to the original objects, which are now all None. So we must protect

1299 # these modules from deletion by keeping a cache.

1300 #

1301 # To avoid keeping stale modules around (we only need the one from the

1302 # last run), we use a dict keyed with the full path to the script, so

1303 # only the last version of the module is held in the cache. Note,

1304 # however, that we must cache the module *namespace contents* (their

1305 # __dict__). Because if we try to cache the actual modules, old ones

1306 # (uncached) could be destroyed while still holding references (such as

1307 # those held by GUI objects that tend to be long-lived)>

1308 #

1309 # The %reset command will flush this cache. See the cache_main_mod()

1310 # and clear_main_mod_cache() methods for details on use.

1311

1312 # This is the cache used for 'main' namespaces

1313 self._main_mod_cache = {}

1314

1315 # A table holding all the namespaces IPython deals with, so that

1316 # introspection facilities can search easily.

1317 self.ns_table = {'user_global':self.user_module.__dict__,

1318 'user_local':self.user_ns,

1319 'builtin':builtin_mod.__dict__

1320 }

1321

1322 @property

1323 def user_global_ns(self):

1324 return self.user_module.__dict__

1325

1326 def prepare_user_module(self, user_module=None, user_ns=None):

1327 """Prepare the module and namespace in which user code will be run.

1328

1329 When IPython is started normally, both parameters are None: a new module

1330 is created automatically, and its __dict__ used as the namespace.

1331

1332 If only user_module is provided, its __dict__ is used as the namespace.

1333 If only user_ns is provided, a dummy module is created, and user_ns

1334 becomes the global namespace. If both are provided (as they may be

1335 when embedding), user_ns is the local namespace, and user_module

1336 provides the global namespace.

1337

1338 Parameters

1339 ----------

1340 user_module : module, optional

1341 The current user module in which IPython is being run. If None,

1342 a clean module will be created.

1343 user_ns : dict, optional

1344 A namespace in which to run interactive commands.

1345

1346 Returns

1347 -------

1348 A tuple of user_module and user_ns, each properly initialised.

1349 """

1350 if user_module is None and user_ns is not None:

1351 user_ns.setdefault("__name__", "__main__")

1352 user_module = make_main_module_type(user_ns)()

1353

1354 if user_module is None:

1355 user_module = types.ModuleType("__main__",

1356 doc="Automatically created module for IPython interactive environment")

1357

1358 # We must ensure that __builtin__ (without the final 's') is always

1359 # available and pointing to the __builtin__ *module*. For more details:

1360 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html

1361 user_module.__dict__.setdefault('__builtin__', builtin_mod)

1362 user_module.__dict__.setdefault('__builtins__', builtin_mod)

1363

1364 if user_ns is None:

1365 user_ns = user_module.__dict__

1366 return user_module, user_ns

1367

1368 def init_sys_modules(self):

1369 # We need to insert into sys.modules something that looks like a

1370 # module but which accesses the IPython namespace, for shelve and

1371 # pickle to work interactively. Normally they rely on getting

1372 # everything out of __main__, but for embedding purposes each IPython

1373 # instance has its own private namespace, so we can't go shoving

1374 # everything into __main__.

1375

1376 # note, however, that we should only do this for non-embedded

1377 # ipythons, which really mimic the __main__.__dict__ with their own

1378 # namespace. Embedded instances, on the other hand, should not do

1379 # this because they need to manage the user local/global namespaces

1380 # only, but they live within a 'normal' __main__ (meaning, they

1381 # shouldn't overtake the execution environment of the script they're

1382 # embedded in).

1383

1384 # This is overridden in the InteractiveShellEmbed subclass to a no-op.

1385 main_name = self.user_module.__name__

1386 sys.modules[main_name] = self.user_module

1387

1388 def init_user_ns(self):

1389 """Initialize all user-visible namespaces to their minimum defaults.

1390

1391 Certain history lists are also initialized here, as they effectively

1392 act as user namespaces.

1393

1394 Notes

1395 -----

1396 All data structures here are only filled in, they are NOT reset by this

1397 method. If they were not empty before, data will simply be added to

1398 them.

1399 """

1400 # This function works in two parts: first we put a few things in

1401 # user_ns, and we sync that contents into user_ns_hidden so that these

1402 # initial variables aren't shown by %who. After the sync, we add the

1403 # rest of what we *do* want the user to see with %who even on a new

1404 # session (probably nothing, so they really only see their own stuff)

1405

1406 # The user dict must *always* have a __builtin__ reference to the

1407 # Python standard __builtin__ namespace, which must be imported.

1408 # This is so that certain operations in prompt evaluation can be

1409 # reliably executed with builtins. Note that we can NOT use

1410 # __builtins__ (note the 's'), because that can either be a dict or a

1411 # module, and can even mutate at runtime, depending on the context

1412 # (Python makes no guarantees on it). In contrast, __builtin__ is

1413 # always a module object, though it must be explicitly imported.

1414

1415 # For more details:

1416 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html

1417 ns = {}

1418

1419 # make global variables for user access to the histories

1420 if self.history_manager is not None:

1421 ns["_ih"] = self.history_manager.input_hist_parsed

1422 ns["_oh"] = self.history_manager.output_hist

1423 ns["_dh"] = self.history_manager.dir_hist

1424

1425 # user aliases to input and output histories. These shouldn't show up

1426 # in %who, as they can have very large reprs.

1427 ns["In"] = self.history_manager.input_hist_parsed

1428 ns["Out"] = self.history_manager.output_hist

1429

1430 # Store myself as the public api!!!

1431 ns['get_ipython'] = self.get_ipython

1432

1433 ns['exit'] = self.exiter

1434 ns['quit'] = self.exiter

1435 ns["open"] = _modified_open

1436

1437 # Sync what we've added so far to user_ns_hidden so these aren't seen

1438 # by %who

1439 self.user_ns_hidden.update(ns)

1440

1441 # Anything put into ns now would show up in %who. Think twice before

1442 # putting anything here, as we really want %who to show the user their

1443 # stuff, not our variables.

1444

1445 # Finally, update the real user's namespace

1446 self.user_ns.update(ns)

1447

1448 @property

1449 def all_ns_refs(self):

1450 """Get a list of references to all the namespace dictionaries in which

1451 IPython might store a user-created object.

1452

1453 Note that this does not include the displayhook, which also caches

1454 objects from the output."""

1455 return [self.user_ns, self.user_global_ns, self.user_ns_hidden] + \

1456 [m.__dict__ for m in self._main_mod_cache.values()]

1457

1458 def reset(self, new_session=True, aggressive=False):

1459 """Clear all internal namespaces, and attempt to release references to

1460 user objects.

1461

1462 If new_session is True, a new history session will be opened.

1463 """

1464 # Clear histories

1465 if self.history_manager is not None:

1466 self.history_manager.reset(new_session)

1467 # Reset counter used to index all histories

1468 if new_session:

1469 self.execution_count = 1

1470

1471 # Reset last execution result

1472 self.last_execution_succeeded = True

1473 self.last_execution_result = None

1474

1475 # Flush cached output items

1476 if self.displayhook.do_full_cache:

1477 self.displayhook.flush()

1478

1479 # The main execution namespaces must be cleared very carefully,

1480 # skipping the deletion of the builtin-related keys, because doing so

1481 # would cause errors in many object's __del__ methods.

1482 if self.user_ns is not self.user_global_ns:

1483 self.user_ns.clear()

1484 ns = self.user_global_ns

1485 drop_keys = set(ns.keys())

1486 drop_keys.discard('__builtin__')

1487 drop_keys.discard('__builtins__')

1488 drop_keys.discard('__name__')

1489 for k in drop_keys:

1490 del ns[k]

1491

1492 self.user_ns_hidden.clear()

1493

1494 # Restore the user namespaces to minimal usability

1495 self.init_user_ns()

1496 if aggressive and not hasattr(self, "_sys_modules_keys"):

1497 print("Cannot restore sys.module, no snapshot")

1498 elif aggressive:

1499 print("culling sys module...")

1500 current_keys = set(sys.modules.keys())

1501 for k in current_keys - self._sys_modules_keys:

1502 if k.startswith("multiprocessing"):

1503 continue

1504 del sys.modules[k]

1505

1506 # Restore the default and user aliases

1507 self.alias_manager.clear_aliases()

1508 self.alias_manager.init_aliases()

1509

1510 # Now define aliases that only make sense on the terminal, because they

1511 # need direct access to the console in a way that we can't emulate in

1512 # GUI or web frontend

1513 if os.name == 'posix':

1514 for cmd in ('clear', 'more', 'less', 'man'):

1515 if cmd not in self.magics_manager.magics['line']:

1516 self.alias_manager.soft_define_alias(cmd, cmd)

1517

1518 # Flush the private list of module references kept for script

1519 # execution protection

1520 self.clear_main_mod_cache()

1521

1522 def del_var(self, varname, by_name=False):

1523 """Delete a variable from the various namespaces, so that, as

1524 far as possible, we're not keeping any hidden references to it.

1525

1526 Parameters

1527 ----------

1528 varname : str

1529 The name of the variable to delete.

1530 by_name : bool

1531 If True, delete variables with the given name in each

1532 namespace. If False (default), find the variable in the user

1533 namespace, and delete references to it.

1534 """

1535 if varname in ('__builtin__', '__builtins__'):

1536 raise ValueError("Refusing to delete %s" % varname)

1537

1538 ns_refs = self.all_ns_refs

1539

1540 if by_name: # Delete by name

1541 for ns in ns_refs:

1542 try:

1543 del ns[varname]

1544 except KeyError:

1545 pass

1546 else: # Delete by object

1547 try:

1548 obj = self.user_ns[varname]

1549 except KeyError as e:

1550 raise NameError("name '%s' is not defined" % varname) from e

1551 # Also check in output history

1552 assert self.history_manager is not None

1553 ns_refs.append(self.history_manager.output_hist)

1554 for ns in ns_refs:

1555 to_delete = [n for n, o in ns.items() if o is obj]

1556 for name in to_delete:

1557 del ns[name]

1558

1559 # Ensure it is removed from the last execution result

1560 if self.last_execution_result.result is obj:

1561 self.last_execution_result = None

1562

1563 # displayhook keeps extra references, but not in a dictionary

1564 for name in ('_', '__', '___'):

1565 if getattr(self.displayhook, name) is obj:

1566 setattr(self.displayhook, name, None)

1567

1568 def reset_selective(self, regex=None):

1569 """Clear selective variables from internal namespaces based on a

1570 specified regular expression.

1571

1572 Parameters

1573 ----------

1574 regex : string or compiled pattern, optional

1575 A regular expression pattern that will be used in searching

1576 variable names in the users namespaces.

1577 """

1578 if regex is not None:

1579 try:

1580 m = re.compile(regex)

1581 except TypeError as e:

1582 raise TypeError('regex must be a string or compiled pattern') from e

1583 # Search for keys in each namespace that match the given regex

1584 # If a match is found, delete the key/value pair.

1585 for ns in self.all_ns_refs:

1586 for var in ns:

1587 if m.search(var):

1588 del ns[var]

1589

1590 def push(self, variables, interactive=True):

1591 """Inject a group of variables into the IPython user namespace.

1592

1593 Parameters

1594 ----------

1595 variables : dict, str or list/tuple of str

1596 The variables to inject into the user's namespace. If a dict, a

1597 simple update is done. If a str, the string is assumed to have

1598 variable names separated by spaces. A list/tuple of str can also

1599 be used to give the variable names. If just the variable names are

1600 give (list/tuple/str) then the variable values looked up in the

1601 callers frame.

1602 interactive : bool

1603 If True (default), the variables will be listed with the ``who``

1604 magic.

1605 """

1606 vdict = None

1607

1608 # We need a dict of name/value pairs to do namespace updates.

1609 if isinstance(variables, dict):

1610 vdict = variables

1611 elif isinstance(variables, (str, list, tuple)):

1612 if isinstance(variables, str):

1613 vlist = variables.split()

1614 else:

1615 vlist = list(variables)

1616 vdict = {}

1617 cf = sys._getframe(1)

1618 for name in vlist:

1619 try:

1620 vdict[name] = eval(name, cf.f_globals, cf.f_locals)

1621 except:

1622 print('Could not get variable %s from %s' %

1623 (name,cf.f_code.co_name))

1624 else:

1625 raise ValueError('variables must be a dict/str/list/tuple')

1626

1627 # Propagate variables to user namespace

1628 self.user_ns.update(vdict)

1629

1630 # And configure interactive visibility

1631 user_ns_hidden = self.user_ns_hidden

1632 if interactive:

1633 for name in vdict:

1634 user_ns_hidden.pop(name, None)

1635 else:

1636 user_ns_hidden.update(vdict)

1637

1638 def drop_by_id(self, variables):

1639 """Remove a dict of variables from the user namespace, if they are the

1640 same as the values in the dictionary.

1641

1642 This is intended for use by extensions: variables that they've added can

1643 be taken back out if they are unloaded, without removing any that the

1644 user has overwritten.

1645

1646 Parameters

1647 ----------

1648 variables : dict

1649 A dictionary mapping object names (as strings) to the objects.

1650 """

1651 for name, obj in variables.items():

1652 if name in self.user_ns and self.user_ns[name] is obj:

1653 del self.user_ns[name]

1654 self.user_ns_hidden.pop(name, None)

1655

1656 #-------------------------------------------------------------------------

1657 # Things related to object introspection

1658 #-------------------------------------------------------------------------

1659 @staticmethod

1660 def _find_parts(oname: str) -> Tuple[bool, ListType[str]]:

1661 """

1662 Given an object name, return a list of parts of this object name.

1663

1664 Basically split on docs when using attribute access,

1665 and extract the value when using square bracket.

1666

1667

1668 For example foo.bar[3].baz[x] -> foo, bar, 3, baz, x

1669

1670

1671 Returns

1672 -------

1673 parts_ok: bool

1674 whether we were properly able to parse parts.

1675 parts: list of str

1676 extracted parts

1677

1678

1679

1680 """

1681 raw_parts = oname.split(".")

1682 parts = []

1683 parts_ok = True

1684 for p in raw_parts:

1685 if p.endswith("]"):

1686 var, *indices = p.split("[")

1687 if not var.isidentifier():

1688 parts_ok = False

1689 break

1690 parts.append(var)

1691 for ind in indices:

1692 if ind[-1] != "]" and not is_integer_string(ind[:-1]):

1693 parts_ok = False

1694 break

1695 parts.append(ind[:-1])

1696 continue

1697

1698 if not p.isidentifier():

1699 parts_ok = False

1700 parts.append(p)

1701

1702 return parts_ok, parts

1703

1704 def _ofind(

1705 self, oname: str, namespaces: Optional[Sequence[Tuple[str, AnyType]]] = None

1706 ) -> OInfo:

1707 """Find an object in the available namespaces.

1708

1709

1710 Returns

1711 -------

1712 OInfo with fields:

1713 - ismagic

1714 - isalias

1715 - found

1716 - obj

1717 - namespac

1718 - parent

1719

1720 Has special code to detect magic functions.

1721 """

1722 oname = oname.strip()

1723 parts_ok, parts = self._find_parts(oname)

1724

1725 if (

1726 not oname.startswith(ESC_MAGIC)

1727 and not oname.startswith(ESC_MAGIC2)

1728 and not parts_ok

1729 ):

1730 return OInfo(

1731 ismagic=False,

1732 isalias=False,

1733 found=False,

1734 obj=None,

1735 namespace=None,

1736 parent=None,

1737 )

1738

1739 if namespaces is None:

1740 # Namespaces to search in:

1741 # Put them in a list. The order is important so that we

1742 # find things in the same order that Python finds them.

1743 namespaces = [ ('Interactive', self.user_ns),

1744 ('Interactive (global)', self.user_global_ns),

1745 ('Python builtin', builtin_mod.__dict__),

1746 ]

1747

1748 ismagic = False

1749 isalias = False

1750 found = False

1751 ospace = None

1752 parent = None

1753 obj = None

1754

1755

1756 # Look for the given name by splitting it in parts. If the head is

1757 # found, then we look for all the remaining parts as members, and only

1758 # declare success if we can find them all.

1759 oname_parts = parts

1760 oname_head, oname_rest = oname_parts[0],oname_parts[1:]

1761 for nsname,ns in namespaces:

1762 try:

1763 obj = ns[oname_head]

1764 except KeyError:

1765 continue

1766 else:

1767 for idx, part in enumerate(oname_rest):

1768 try:

1769 parent = obj

1770 # The last part is looked up in a special way to avoid

1771 # descriptor invocation as it may raise or have side

1772 # effects.

1773 if idx == len(oname_rest) - 1:

1774 obj = self._getattr_property(obj, part)

1775 else:

1776 if is_integer_string(part):

1777 obj = obj[int(part)]

1778 else:

1779 obj = getattr(obj, part)

1780 except:

1781 # Blanket except b/c some badly implemented objects

1782 # allow __getattr__ to raise exceptions other than

1783 # AttributeError, which then crashes IPython.

1784 break

1785 else:

1786 # If we finish the for loop (no break), we got all members

1787 found = True

1788 ospace = nsname

1789 break # namespace loop

1790

1791 # Try to see if it's magic

1792 if not found:

1793 obj = None

1794 if oname.startswith(ESC_MAGIC2):

1795 oname = oname.lstrip(ESC_MAGIC2)

1796 obj = self.find_cell_magic(oname)

1797 elif oname.startswith(ESC_MAGIC):

1798 oname = oname.lstrip(ESC_MAGIC)

1799 obj = self.find_line_magic(oname)

1800 else:

1801 # search without prefix, so run? will find %run?

1802 obj = self.find_line_magic(oname)

1803 if obj is None:

1804 obj = self.find_cell_magic(oname)

1805 if obj is not None:

1806 found = True

1807 ospace = 'IPython internal'

1808 ismagic = True

1809 isalias = isinstance(obj, Alias)

1810

1811 # Last try: special-case some literals like '', [], {}, etc:

1812 if not found and oname_head in ["''",'""','[]','{}','()']:

1813 obj = eval(oname_head)

1814 found = True

1815 ospace = 'Interactive'

1816

1817 return OInfo(

1818 obj=obj,

1819 found=found,

1820 parent=parent,

1821 ismagic=ismagic,

1822 isalias=isalias,

1823 namespace=ospace,

1824 )

1825

1826 @staticmethod

1827 def _getattr_property(obj, attrname):

1828 """Property-aware getattr to use in object finding.

1829

1830 If attrname represents a property, return it unevaluated (in case it has

1831 side effects or raises an error.

1832

1833 """

1834 if not isinstance(obj, type):

1835 try:

1836 # `getattr(type(obj), attrname)` is not guaranteed to return

1837 # `obj`, but does so for property:

1838 #

1839 # property.__get__(self, None, cls) -> self

1840 #

1841 # The universal alternative is to traverse the mro manually

1842 # searching for attrname in class dicts.

1843 if is_integer_string(attrname):

1844 return obj[int(attrname)]

1845 else:

1846 attr = getattr(type(obj), attrname)

1847 except AttributeError:

1848 pass

1849 else:

1850 # This relies on the fact that data descriptors (with both

1851 # __get__ & __set__ magic methods) take precedence over

1852 # instance-level attributes:

1853 #

1854 # class A(object):

1855 # @property

1856 # def foobar(self): return 123

1857 # a = A()

1858 # a.__dict__['foobar'] = 345

1859 # a.foobar # == 123

1860 #

1861 # So, a property may be returned right away.

1862 if isinstance(attr, property):

1863 return attr

1864

1865 # Nothing helped, fall back.

1866 return getattr(obj, attrname)

1867

1868 def _object_find(self, oname, namespaces=None) -> OInfo:

1869 """Find an object and return a struct with info about it."""

1870 return self._ofind(oname, namespaces)

1871

1872 def _inspect(self, meth, oname: str, namespaces=None, **kw):

1873 """Generic interface to the inspector system.

1874

1875 This function is meant to be called by pdef, pdoc & friends.

1876 """

1877 info: OInfo = self._object_find(oname, namespaces)

1878 if self.sphinxify_docstring:

1879 if sphinxify is None:

1880 raise ImportError("Module ``docrepr`` required but missing")

1881 docformat = sphinxify(self.object_inspect(oname))

1882 else:

1883 docformat = None

1884 if info.found or hasattr(info.parent, oinspect.HOOK_NAME):

1885 pmethod = getattr(self.inspector, meth)

1886 # TODO: only apply format_screen to the plain/text repr of the mime

1887 # bundle.

1888 formatter = format_screen if info.ismagic else docformat

1889 if meth == 'pdoc':

1890 pmethod(info.obj, oname, formatter)

1891 elif meth == 'pinfo':

1892 pmethod(

1893 info.obj,

1894 oname,

1895 formatter,

1896 info,

1897 enable_html_pager=self.enable_html_pager,

1898 **kw,

1899 )

1900 else:

1901 pmethod(info.obj, oname)

1902 else:

1903 print('Object `%s` not found.' % oname)

1904 return 'not found' # so callers can take other action

1905

1906 def object_inspect(self, oname, detail_level=0):

1907 """Get object info about oname"""

1908 with self.builtin_trap:

1909 info = self._object_find(oname)

1910 if info.found:

1911 return self.inspector.info(info.obj, oname, info=info,

1912 detail_level=detail_level

1913 )

1914 else:

1915 return oinspect.object_info(name=oname, found=False)

1916

1917 def object_inspect_text(self, oname, detail_level=0):

1918 """Get object info as formatted text"""

1919 return self.object_inspect_mime(oname, detail_level)['text/plain']

1920

1921 def object_inspect_mime(self, oname, detail_level=0, omit_sections=()):

1922 """Get object info as a mimebundle of formatted representations.

1923

1924 A mimebundle is a dictionary, keyed by mime-type.

1925 It must always have the key `'text/plain'`.

1926 """

1927 with self.builtin_trap:

1928 info = self._object_find(oname)

1929 if info.found:

1930 if self.sphinxify_docstring:

1931 if sphinxify is None:

1932 raise ImportError("Module ``docrepr`` required but missing")

1933 docformat = sphinxify(self.object_inspect(oname))

1934 else:

1935 docformat = None

1936 return self.inspector._get_info(

1937 info.obj,

1938 oname,

1939 info=info,

1940 detail_level=detail_level,

1941 formatter=docformat,

1942 omit_sections=omit_sections,

1943 )

1944 else:

1945 raise KeyError(oname)

1946

1947 #-------------------------------------------------------------------------

1948 # Things related to history management

1949 #-------------------------------------------------------------------------

1950

1951 def init_history(self):

1952 """Sets up the command history, and starts regular autosaves."""

1953 self.history_manager = HistoryManager(shell=self, parent=self)

1954 self.configurables.append(self.history_manager)

1955

1956 #-------------------------------------------------------------------------

1957 # Things related to exception handling and tracebacks (not debugging)

1958 #-------------------------------------------------------------------------

1959

1960 debugger_cls = InterruptiblePdb

1961

1962 def init_traceback_handlers(self, custom_exceptions) -> None:

1963 # Syntax error handler.

1964 self.SyntaxTB = ultratb.SyntaxTB(theme_name=self.colors)

1965

1966 # The interactive one is initialized with an offset, meaning we always

1967 # want to remove the topmost item in the traceback, which is our own

1968 # internal code. Valid modes: ['Plain','Context','Verbose','Minimal']

1969 self.InteractiveTB = ultratb.AutoFormattedTB(

1970 mode=self.xmode,

1971 theme_name=self.colors,

1972 tb_offset=1,

1973 debugger_cls=self.debugger_cls,

1974 )

1975

1976 # The instance will store a pointer to the system-wide exception hook,

1977 # so that runtime code (such as magics) can access it. This is because

1978 # during the read-eval loop, it may get temporarily overwritten.

1979 self.sys_excepthook = sys.excepthook

1980

1981 # and add any custom exception handlers the user may have specified

1982 self.set_custom_exc(*custom_exceptions)

1983

1984 # Set the exception mode

1985 self.InteractiveTB.set_mode(mode=self.xmode)

1986

1987 def set_custom_exc(self, exc_tuple, handler):

1988 """set_custom_exc(exc_tuple, handler)

1989

1990 Set a custom exception handler, which will be called if any of the

1991 exceptions in exc_tuple occur in the mainloop (specifically, in the

1992 run_code() method).

1993

1994 Parameters

1995 ----------

1996 exc_tuple : tuple of exception classes

1997 A *tuple* of exception classes, for which to call the defined

1998 handler. It is very important that you use a tuple, and NOT A

1999 LIST here, because of the way Python's except statement works. If

2000 you only want to trap a single exception, use a singleton tuple::

2001

2002 exc_tuple == (MyCustomException,)

2003

2004 handler : callable

2005 handler must have the following signature::

2006

2007 def my_handler(self, etype, value, tb, tb_offset=None):

2008 ...

2009 return structured_traceback

2010

2011 Your handler must return a structured traceback (a list of strings),

2012 or None.

2013

2014 This will be made into an instance method (via types.MethodType)

2015 of IPython itself, and it will be called if any of the exceptions

2016 listed in the exc_tuple are caught. If the handler is None, an

2017 internal basic one is used, which just prints basic info.

2018

2019 To protect IPython from crashes, if your handler ever raises an

2020 exception or returns an invalid result, it will be immediately

2021 disabled.

2022

2023 Notes

2024 -----

2025 WARNING: by putting in your own exception handler into IPython's main

2026 execution loop, you run a very good chance of nasty crashes. This

2027 facility should only be used if you really know what you are doing.

2028 """

2029

2030 if not isinstance(exc_tuple, tuple):

2031 raise TypeError("The custom exceptions must be given as a tuple.")

2032

2033 def dummy_handler(self, etype, value, tb, tb_offset=None):

2034 print('*** Simple custom exception handler ***')

2035 print('Exception type :', etype)

2036 print('Exception value:', value)

2037 print('Traceback :', tb)

2038

2039 def validate_stb(stb):

2040 """validate structured traceback return type

2041

2042 return type of CustomTB *should* be a list of strings, but allow

2043 single strings or None, which are harmless.

2044

2045 This function will *always* return a list of strings,

2046 and will raise a TypeError if stb is inappropriate.

2047 """

2048 msg = "CustomTB must return list of strings, not %r" % stb

2049 if stb is None:

2050 return []

2051 elif isinstance(stb, str):

2052 return [stb]

2053 elif not isinstance(stb, list):

2054 raise TypeError(msg)

2055 # it's a list

2056 for line in stb:

2057 # check every element

2058 if not isinstance(line, str):

2059 raise TypeError(msg)

2060 return stb

2061

2062 if handler is None:

2063 wrapped = dummy_handler

2064 else:

2065 def wrapped(self,etype,value,tb,tb_offset=None):

2066 """wrap CustomTB handler, to protect IPython from user code

2067

2068 This makes it harder (but not impossible) for custom exception

2069 handlers to crash IPython.

2070 """

2071 try:

2072 stb = handler(self,etype,value,tb,tb_offset=tb_offset)

2073 return validate_stb(stb)

2074 except:

2075 # clear custom handler immediately

2076 self.set_custom_exc((), None)

2077 print("Custom TB Handler failed, unregistering", file=sys.stderr)

2078 # show the exception in handler first

2079 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())

2080 print(self.InteractiveTB.stb2text(stb))

2081 print("The original exception:")

2082 stb = self.InteractiveTB.structured_traceback(

2083 etype, value, tb, tb_offset=tb_offset

2084 )

2085 return stb

2086

2087 self.CustomTB = types.MethodType(wrapped,self)

2088 self.custom_exceptions = exc_tuple

2089

2090 def excepthook(self, etype, value, tb):

2091 """One more defense for GUI apps that call sys.excepthook.

2092

2093 GUI frameworks like wxPython trap exceptions and call

2094 sys.excepthook themselves. I guess this is a feature that

2095 enables them to keep running after exceptions that would

2096 otherwise kill their mainloop. This is a bother for IPython

2097 which expects to catch all of the program exceptions with a try:

2098 except: statement.

2099

2100 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if

2101 any app directly invokes sys.excepthook, it will look to the user like

2102 IPython crashed. In order to work around this, we can disable the

2103 CrashHandler and replace it with this excepthook instead, which prints a

2104 regular traceback using our InteractiveTB. In this fashion, apps which

2105 call sys.excepthook will generate a regular-looking exception from

2106 IPython, and the CrashHandler will only be triggered by real IPython

2107 crashes.

2108

2109 This hook should be used sparingly, only in places which are not likely

2110 to be true IPython errors.

2111 """

2112 self.showtraceback((etype, value, tb), tb_offset=0)

2113

2114 def _get_exc_info(self, exc_tuple=None):

2115 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.

2116

2117 Ensures sys.last_type,value,traceback hold the exc_info we found,

2118 from whichever source.

2119

2120 raises ValueError if none of these contain any information

2121 """

2122 if exc_tuple is None:

2123 etype, value, tb = sys.exc_info()

2124 else:

2125 etype, value, tb = exc_tuple

2126

2127 if etype is None:

2128 if hasattr(sys, 'last_type'):

2129 etype, value, tb = sys.last_type, sys.last_value, \

2130 sys.last_traceback

2131

2132 if etype is None:

2133 raise ValueError("No exception to find")

2134

2135 # Now store the exception info in sys.last_type etc.

2136 # WARNING: these variables are somewhat deprecated and not

2137 # necessarily safe to use in a threaded environment, but tools

2138 # like pdb depend on their existence, so let's set them. If we

2139 # find problems in the field, we'll need to revisit their use.

2140 sys.last_type = etype

2141 sys.last_value = value

2142 sys.last_traceback = tb

2143 if sys.version_info >= (3, 12):

2144 sys.last_exc = value

2145

2146 return etype, value, tb

2147

2148 def show_usage_error(self, exc):

2149 """Show a short message for UsageErrors

2150

2151 These are special exceptions that shouldn't show a traceback.

2152 """

2153 print("UsageError: %s" % exc, file=sys.stderr)

2154

2155 def get_exception_only(self, exc_tuple=None):

2156 """

2157 Return as a string (ending with a newline) the exception that

2158 just occurred, without any traceback.

2159 """

2160 etype, value, tb = self._get_exc_info(exc_tuple)

2161 msg = traceback.format_exception_only(etype, value)

2162 return ''.join(msg)

2163

2164 def showtraceback(

2165 self,

2166 exc_tuple: tuple[type[BaseException], BaseException, AnyType] | None = None,

2167 filename: str | None = None,

2168 tb_offset: int | None = None,

2169 exception_only: bool = False,

2170 running_compiled_code: bool = False,

2171 ) -> None:

2172 """Display the exception that just occurred.

2173

2174 If nothing is known about the exception, this is the method which

2175 should be used throughout the code for presenting user tracebacks,

2176 rather than directly invoking the InteractiveTB object.

2177

2178 A specific showsyntaxerror() also exists, but this method can take

2179 care of calling it if needed, so unless you are explicitly catching a

2180 SyntaxError exception, don't try to analyze the stack manually and

2181 simply call this method."""

2182

2183 try:

2184 try:

2185 etype, value, tb = self._get_exc_info(exc_tuple)

2186 except ValueError:

2187 print('No traceback available to show.', file=sys.stderr)

2188 return

2189

2190 if issubclass(etype, SyntaxError):

2191 # Though this won't be called by syntax errors in the input

2192 # line, there may be SyntaxError cases with imported code.

2193 self.showsyntaxerror(filename, running_compiled_code)

2194 elif etype is UsageError:

2195 self.show_usage_error(value)

2196 else:

2197 if exception_only:

2198 stb = ['An exception has occurred, use %tb to see '

2199 'the full traceback.\n']

2200 stb.extend(self.InteractiveTB.get_exception_only(etype,

2201 value))

2202 else:

2203

2204 def contains_exceptiongroup(val):

2205 if val is None:

2206 return False

2207 return isinstance(

2208 val, BaseExceptionGroup

2209 ) or contains_exceptiongroup(val.__context__)

2210

2211 if contains_exceptiongroup(value):

2212 # fall back to native exception formatting until ultratb

2213 # supports exception groups

2214 traceback.print_exc()

2215 else:

2216 try:

2217 # Exception classes can customise their traceback - we

2218 # use this in IPython.parallel for exceptions occurring

2219 # in the engines. This should return a list of strings.

2220 if hasattr(value, "_render_traceback_"):

2221 stb = value._render_traceback_()

2222 else:

2223 stb = self.InteractiveTB.structured_traceback(

2224 etype, value, tb, tb_offset=tb_offset

2225 )

2226

2227 except Exception:

2228 print(

2229 "Unexpected exception formatting exception. Falling back to standard exception"

2230 )

2231 traceback.print_exc()

2232 return None

2233

2234 self._showtraceback(etype, value, stb)

2235 if self.call_pdb:

2236 # drop into debugger

2237 self.debugger(force=True)

2238 return

2239

2240 # Actually show the traceback

2241 self._showtraceback(etype, value, stb)

2242

2243 except KeyboardInterrupt:

2244 print('\n' + self.get_exception_only(), file=sys.stderr)

2245

2246 def _showtraceback(self, etype, evalue, stb: list[str]):

2247 """Actually show a traceback.

2248

2249 Subclasses may override this method to put the traceback on a different

2250 place, like a side channel.

2251 """

2252 val = self.InteractiveTB.stb2text(stb)

2253 self.showing_traceback = True

2254 try:

2255 print(val)

2256 except UnicodeEncodeError:

2257 print(val.encode("utf-8", "backslashreplace").decode())

2258 self.showing_traceback = False

2259

2260 def showsyntaxerror(self, filename=None, running_compiled_code=False):

2261 """Display the syntax error that just occurred.

2262

2263 This doesn't display a stack trace because there isn't one.

2264

2265 If a filename is given, it is stuffed in the exception instead

2266 of what was there before (because Python's parser always uses

2267 "<string>" when reading from a string).

2268

2269 If the syntax error occurred when running a compiled code (i.e. running_compile_code=True),

2270 longer stack trace will be displayed.

2271 """

2272 etype, value, last_traceback = self._get_exc_info()

2273

2274 if filename and issubclass(etype, SyntaxError):

2275 try:

2276 value.filename = filename

2277 except:

2278 # Not the format we expect; leave it alone

2279 pass

2280

2281 # If the error occurred when executing compiled code, we should provide full stacktrace.

2282 elist = traceback.extract_tb(last_traceback) if running_compiled_code else []

2283 stb = self.SyntaxTB.structured_traceback(etype, value, elist)

2284 self._showtraceback(etype, value, stb)

2285

2286 # This is overridden in TerminalInteractiveShell to show a message about

2287 # the %paste magic.

2288 def showindentationerror(self):

2289 """Called by _run_cell when there's an IndentationError in code entered

2290 at the prompt.

2291

2292 This is overridden in TerminalInteractiveShell to show a message about

2293 the %paste magic."""

2294 self.showsyntaxerror()

2295

2296 @skip_doctest

2297 def set_next_input(self, s, replace=False):

2298 """ Sets the 'default' input string for the next command line.

2299

2300 Example::

2301

2302 In [1]: _ip.set_next_input("Hello Word")

2303 In [2]: Hello Word_ # cursor is here

2304 """

2305 self.rl_next_input = s

2306

2307 #-------------------------------------------------------------------------

2308 # Things related to text completion

2309 #-------------------------------------------------------------------------

2310

2311 def init_completer(self):

2312 """Initialize the completion machinery.

2313

2314 This creates completion machinery that can be used by client code,

2315 either interactively in-process (typically triggered by the readline

2316 library), programmatically (such as in test suites) or out-of-process

2317 (typically over the network by remote frontends).

2318 """

2319 from IPython.core.completer import IPCompleter

2320 from IPython.core.completerlib import (

2321 cd_completer,

2322 magic_run_completer,

2323 module_completer,

2324 reset_completer,

2325 )

2326

2327 self.Completer = IPCompleter(shell=self,

2328 namespace=self.user_ns,

2329 global_namespace=self.user_global_ns,

2330 parent=self,

2331 )

2332 self.configurables.append(self.Completer)

2333

2334 # Add custom completers to the basic ones built into IPCompleter

2335 sdisp = self.strdispatchers.get('complete_command', StrDispatch())

2336 self.strdispatchers['complete_command'] = sdisp

2337 self.Completer.custom_completers = sdisp

2338

2339 self.set_hook('complete_command', module_completer, str_key = 'import')

2340 self.set_hook('complete_command', module_completer, str_key = 'from')

2341 self.set_hook('complete_command', module_completer, str_key = '%aimport')

2342 self.set_hook('complete_command', magic_run_completer, str_key = '%run')

2343 self.set_hook('complete_command', cd_completer, str_key = '%cd')

2344 self.set_hook('complete_command', reset_completer, str_key = '%reset')

2345

2346 @skip_doctest

2347 def complete(self, text, line=None, cursor_pos=None):

2348 """Return the completed text and a list of completions.

2349

2350 Parameters

2351 ----------

2352 text : string

2353 A string of text to be completed on. It can be given as empty and

2354 instead a line/position pair are given. In this case, the

2355 completer itself will split the line like readline does.

2356 line : string, optional

2357 The complete line that text is part of.

2358 cursor_pos : int, optional

2359 The position of the cursor on the input line.

2360

2361 Returns

2362 -------

2363 text : string

2364 The actual text that was completed.

2365 matches : list

2366 A sorted list with all possible completions.

2367

2368 Notes

2369 -----

2370 The optional arguments allow the completion to take more context into

2371 account, and are part of the low-level completion API.

2372

2373 This is a wrapper around the completion mechanism, similar to what

2374 readline does at the command line when the TAB key is hit. By

2375 exposing it as a method, it can be used by other non-readline

2376 environments (such as GUIs) for text completion.

2377

2378 Examples

2379 --------

2380 In [1]: x = 'hello'

2381

2382 In [2]: _ip.complete('x.l')

2383 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])

2384 """

2385

2386 # Inject names into __builtin__ so we can complete on the added names.

2387 with self.builtin_trap:

2388 return self.Completer.complete(text, line, cursor_pos)

2389

2390 def set_custom_completer(self, completer, pos=0) -> None:

2391 """Adds a new custom completer function.

2392

2393 The position argument (defaults to 0) is the index in the completers

2394 list where you want the completer to be inserted.

2395

2396 `completer` should have the following signature::

2397

2398 def completion(self: Completer, text: string) -> List[str]:

2399 raise NotImplementedError

2400

2401 It will be bound to the current Completer instance and pass some text

2402 and return a list with current completions to suggest to the user.

2403 """

2404

2405 newcomp = types.MethodType(completer, self.Completer)

2406 self.Completer.custom_matchers.insert(pos,newcomp)

2407

2408 def set_completer_frame(self, frame=None):

2409 """Set the frame of the completer."""

2410 if frame:

2411 self.Completer.namespace = frame.f_locals

2412 self.Completer.global_namespace = frame.f_globals

2413 else:

2414 self.Completer.namespace = self.user_ns

2415 self.Completer.global_namespace = self.user_global_ns

2416

2417 #-------------------------------------------------------------------------

2418 # Things related to magics

2419 #-------------------------------------------------------------------------

2420

2421 def init_magics(self):

2422 from IPython.core import magics as m

2423 self.magics_manager = magic.MagicsManager(shell=self,

2424 parent=self,

2425 user_magics=m.UserMagics(self))

2426 self.configurables.append(self.magics_manager)

2427

2428 # Expose as public API from the magics manager

2429 self.register_magics = self.magics_manager.register

2430

2431 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,

2432 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,

2433 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,

2434 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,

2435 m.PylabMagics, m.ScriptMagics,

2436 )

2437 self.register_magics(m.AsyncMagics)

2438

2439 # Register Magic Aliases

2440 mman = self.magics_manager

2441 # FIXME: magic aliases should be defined by the Magics classes

2442 # or in MagicsManager, not here

2443 mman.register_alias('ed', 'edit')

2444 mman.register_alias('hist', 'history')

2445 mman.register_alias('rep', 'recall')

2446 mman.register_alias('SVG', 'svg', 'cell')

2447 mman.register_alias('HTML', 'html', 'cell')

2448 mman.register_alias('file', 'writefile', 'cell')

2449

2450 # FIXME: Move the color initialization to the DisplayHook, which

2451 # should be split into a prompt manager and displayhook. We probably

2452 # even need a centralize colors management object.

2453 self.run_line_magic('colors', self.colors)

2454

2455 # Defined here so that it's included in the documentation

2456 @functools.wraps(magic.MagicsManager.register_function)

2457 def register_magic_function(self, func, magic_kind='line', magic_name=None):

2458 self.magics_manager.register_function(

2459 func, magic_kind=magic_kind, magic_name=magic_name

2460 )

2461

2462 def _find_with_lazy_load(self, /, type_, magic_name: str):

2463 """

2464 Try to find a magic potentially lazy-loading it.

2465

2466 Parameters

2467 ----------

2468

2469 type_: "line"|"cell"

2470 the type of magics we are trying to find/lazy load.

2471 magic_name: str

2472 The name of the magic we are trying to find/lazy load

2473

2474

2475 Note that this may have any side effects

2476 """

2477 finder = {"line": self.find_line_magic, "cell": self.find_cell_magic}[type_]

2478 fn = finder(magic_name)

2479 if fn is not None:

2480 return fn

2481 lazy = self.magics_manager.lazy_magics.get(magic_name)

2482 if lazy is None:

2483 return None

2484

2485 self.run_line_magic("load_ext", lazy)

2486 res = finder(magic_name)

2487 return res

2488

2489 def run_line_magic(self, magic_name: str, line: str, _stack_depth=1):

2490 """Execute the given line magic.

2491

2492 Parameters

2493 ----------

2494 magic_name : str

2495 Name of the desired magic function, without '%' prefix.

2496 line : str

2497 The rest of the input line as a single string.

2498 _stack_depth : int

2499 If run_line_magic() is called from magic() then _stack_depth=2.

2500 This is added to ensure backward compatibility for use of 'get_ipython().magic()'

2501 """

2502 fn = self._find_with_lazy_load("line", magic_name)

2503 if fn is None:

2504 lazy = self.magics_manager.lazy_magics.get(magic_name)

2505 if lazy:

2506 self.run_line_magic("load_ext", lazy)

2507 fn = self.find_line_magic(magic_name)

2508 if fn is None:

2509 cm = self.find_cell_magic(magic_name)

2510 etpl = "Line magic function `%%%s` not found%s."

2511 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '

2512 'did you mean that instead?)' % magic_name )

2513 raise UsageError(etpl % (magic_name, extra))

2514 else:

2515 # Note: this is the distance in the stack to the user's frame.

2516 # This will need to be updated if the internal calling logic gets

2517 # refactored, or else we'll be expanding the wrong variables.

2518

2519 # Determine stack_depth depending on where run_line_magic() has been called

2520 stack_depth = _stack_depth

2521 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):

2522 # magic has opted out of var_expand

2523 magic_arg_s = line

2524 else:

2525 magic_arg_s = self.var_expand(line, stack_depth)

2526 # Put magic args in a list so we can call with f(*a) syntax

2527 args = [magic_arg_s]

2528 kwargs = {}

2529 # Grab local namespace if we need it:

2530 if getattr(fn, "needs_local_scope", False):

2531 kwargs['local_ns'] = self.get_local_scope(stack_depth)

2532 with self.builtin_trap:

2533 result = fn(*args, **kwargs)

2534

2535 # The code below prevents the output from being displayed

2536 # when using magics with decorator @output_can_be_silenced

2537 # when the last Python token in the expression is a ';'.

2538 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_SILENCED, False):

2539 if DisplayHook.semicolon_at_end_of_expression(magic_arg_s):

2540 return None

2541

2542 return result

2543

2544 def get_local_scope(self, stack_depth):

2545 """Get local scope at given stack depth.

2546

2547 Parameters

2548 ----------

2549 stack_depth : int

2550 Depth relative to calling frame

2551 """

2552 return sys._getframe(stack_depth + 1).f_locals

2553

2554 def run_cell_magic(self, magic_name, line, cell):

2555 """Execute the given cell magic.

2556

2557 Parameters

2558 ----------

2559 magic_name : str

2560 Name of the desired magic function, without '%' prefix.

2561 line : str

2562 The rest of the first input line as a single string.

2563 cell : str

2564 The body of the cell as a (possibly multiline) string.

2565 """

2566 fn = self._find_with_lazy_load("cell", magic_name)

2567 if fn is None:

2568 lm = self.find_line_magic(magic_name)

2569 etpl = "Cell magic `%%{0}` not found{1}."

2570 extra = '' if lm is None else (' (But line magic `%{0}` exists, '

2571 'did you mean that instead?)'.format(magic_name))

2572 raise UsageError(etpl.format(magic_name, extra))

2573 elif cell == '':

2574 message = '%%{0} is a cell magic, but the cell body is empty.'.format(magic_name)

2575 if self.find_line_magic(magic_name) is not None:

2576 message += ' Did you mean the line magic %{0} (single %)?'.format(magic_name)

2577 raise UsageError(message)

2578 else:

2579 # Note: this is the distance in the stack to the user's frame.

2580 # This will need to be updated if the internal calling logic gets

2581 # refactored, or else we'll be expanding the wrong variables.

2582 stack_depth = 2

2583 if getattr(fn, magic.MAGIC_NO_VAR_EXPAND_ATTR, False):

2584 # magic has opted out of var_expand

2585 magic_arg_s = line

2586 else:

2587 magic_arg_s = self.var_expand(line, stack_depth)

2588 kwargs = {}

2589 if getattr(fn, "needs_local_scope", False):

2590 kwargs['local_ns'] = self.user_ns

2591

2592 with self.builtin_trap:

2593 args = (magic_arg_s, cell)

2594 result = fn(*args, **kwargs)

2595

2596 # The code below prevents the output from being displayed

2597 # when using magics with decorator @output_can_be_silenced

2598 # when the last Python token in the expression is a ';'.

2599 if getattr(fn, magic.MAGIC_OUTPUT_CAN_BE_SILENCED, False):

2600 if DisplayHook.semicolon_at_end_of_expression(cell):

2601 return None

2602

2603 return result

2604

2605 def find_line_magic(self, magic_name):

2606 """Find and return a line magic by name.

2607

2608 Returns None if the magic isn't found."""

2609 return self.magics_manager.magics['line'].get(magic_name)

2610

2611 def find_cell_magic(self, magic_name):

2612 """Find and return a cell magic by name.

2613

2614 Returns None if the magic isn't found."""

2615 return self.magics_manager.magics['cell'].get(magic_name)

2616

2617 def find_magic(self, magic_name, magic_kind='line'):

2618 """Find and return a magic of the given type by name.

2619

2620 Returns None if the magic isn't found."""

2621 return self.magics_manager.magics[magic_kind].get(magic_name)

2622

2623 #-------------------------------------------------------------------------

2624 # Things related to macros

2625 #-------------------------------------------------------------------------

2626

2627 def define_macro(self, name, themacro):

2628 """Define a new macro

2629

2630 Parameters

2631 ----------

2632 name : str

2633 The name of the macro.

2634 themacro : str or Macro

2635 The action to do upon invoking the macro. If a string, a new

2636 Macro object is created by passing the string to it.

2637 """

2638

2639 from IPython.core import macro

2640

2641 if isinstance(themacro, str):

2642 themacro = macro.Macro(themacro)

2643 if not isinstance(themacro, macro.Macro):

2644 raise ValueError('A macro must be a string or a Macro instance.')

2645 self.user_ns[name] = themacro

2646

2647 #-------------------------------------------------------------------------

2648 # Things related to the running of system commands

2649 #-------------------------------------------------------------------------

2650

2651 def system_piped(self, cmd):

2652 """Call the given cmd in a subprocess, piping stdout/err

2653

2654 Parameters

2655 ----------

2656 cmd : str

2657 Command to execute (can not end in '&', as background processes are

2658 not supported. Should not be a command that expects input

2659 other than simple text.

2660 """

2661 if cmd.rstrip().endswith('&'):

2662 # this is *far* from a rigorous test

2663 # We do not support backgrounding processes because we either use

2664 # pexpect or pipes to read from. Users can always just call

2665 # os.system() or use ip.system=ip.system_raw

2666 # if they really want a background process.

2667 raise OSError("Background processes not supported.")

2668

2669 # we explicitly do NOT return the subprocess status code, because

2670 # a non-None value would trigger :func:`sys.displayhook` calls.

2671 # Instead, we store the exit_code in user_ns.

2672 exit_code = system(self.var_expand(cmd, depth=1))

2673 self.user_ns['_exit_code'] = exit_code

2674

2675 # Raise an exception if the command failed and system_raise_on_error is True

2676 if self.system_raise_on_error and exit_code != 0:

2677 raise CalledProcessError(exit_code, cmd)

2678

2679 def system_raw(self, cmd):

2680 """Call the given cmd in a subprocess using os.system on Windows or

2681 subprocess.call using the system shell on other platforms.

2682

2683 Parameters

2684 ----------

2685 cmd : str

2686 Command to execute.

2687 """

2688 cmd = self.var_expand(cmd, depth=1)

2689 # warn if there is an IPython magic alternative.

2690 if cmd == "":

2691 main_cmd = ""

2692 else:

2693 main_cmd = cmd.split()[0]

2694 has_magic_alternatives = ("pip", "conda", "cd")

2695

2696 if main_cmd in has_magic_alternatives:

2697 warnings.warn(

2698 (

2699 "You executed the system command !{0} which may not work "

2700 "as expected. Try the IPython magic %{0} instead."

2701 ).format(main_cmd)

2702 )

2703

2704 # protect os.system from UNC paths on Windows, which it can't handle:

2705 if sys.platform == 'win32':

2706 from IPython.utils._process_win32 import AvoidUNCPath

2707 with AvoidUNCPath() as path:

2708 if path is not None:

2709 cmd = '"pushd %s &&"%s' % (path, cmd)

2710 try:

2711 ec = os.system(cmd)

2712 except KeyboardInterrupt:

2713 print('\n' + self.get_exception_only(), file=sys.stderr)

2714 ec = -2

2715 else:

2716 # For posix the result of the subprocess.call() below is an exit

2717 # code, which by convention is zero for success, positive for

2718 # program failure. Exit codes above 128 are reserved for signals,

2719 # and the formula for converting a signal to an exit code is usually

2720 # signal_number+128. To more easily differentiate between exit

2721 # codes and signals, ipython uses negative numbers. For instance

2722 # since control-c is signal 2 but exit code 130, ipython's

2723 # _exit_code variable will read -2. Note that some shells like

2724 # csh and fish don't follow sh/bash conventions for exit codes.

2725 executable = os.environ.get('SHELL', None)

2726 try:

2727 # Use env shell instead of default /bin/sh

2728 ec = subprocess.call(cmd, shell=True, executable=executable)

2729 except KeyboardInterrupt:

2730 # intercept control-C; a long traceback is not useful here

2731 print('\n' + self.get_exception_only(), file=sys.stderr)

2732 ec = 130

2733 if ec > 128:

2734 ec = -(ec - 128)

2735

2736 # We explicitly do NOT return the subprocess status code, because

2737 # a non-None value would trigger :func:`sys.displayhook` calls.

2738 # Instead, we store the exit_code in user_ns. Note the semantics

2739 # of _exit_code: for control-c, _exit_code == -signal.SIGNIT,

2740 # but raising SystemExit(_exit_code) will give status 254!

2741 self.user_ns['_exit_code'] = ec

2742

2743 # Raise an exception if the command failed and system_raise_on_error is True

2744 if self.system_raise_on_error and ec != 0:

2745 raise CalledProcessError(ec, cmd)

2746

2747 # use piped system by default, because it is better behaved

2748 system = system_piped

2749

2750 def getoutput(self, cmd, split=True, depth=0):

2751 """Get output (possibly including stderr) from a subprocess.

2752

2753 Parameters

2754 ----------

2755 cmd : str

2756 Command to execute (can not end in '&', as background processes are

2757 not supported.

2758 split : bool, optional

2759 If True, split the output into an IPython SList. Otherwise, an

2760 IPython LSString is returned. These are objects similar to normal

2761 lists and strings, with a few convenience attributes for easier

2762 manipulation of line-based output. You can use '?' on them for

2763 details.

2764 depth : int, optional

2765 How many frames above the caller are the local variables which should

2766 be expanded in the command string? The default (0) assumes that the

2767 expansion variables are in the stack frame calling this function.

2768 """

2769 if cmd.rstrip().endswith('&'):

2770 # this is *far* from a rigorous test

2771 raise OSError("Background processes not supported.")

2772

2773 # Get output and exit code

2774 expanded_cmd = self.var_expand(cmd, depth=depth+1)

2775 if self.system_raise_on_error:

2776 # Use get_output_error_code to get the exit code

2777 out_str, err_str, exit_code = get_output_error_code(expanded_cmd)

2778 # Combine stdout and stderr as getoutput does

2779 out_combined = out_str if not err_str else out_str + err_str

2780 self.user_ns['_exit_code'] = exit_code

2781

2782 # Raise an exception if the command failed

2783 if exit_code != 0:

2784 raise CalledProcessError(exit_code, cmd)

2785 else:

2786 # Use the original getoutput for backward compatibility

2787 out_combined = getoutput(expanded_cmd)

2788

2789 if split:

2790 out = SList(out_combined.splitlines())

2791 else:

2792 out = LSString(out_combined)

2793 return out

2794

2795 #-------------------------------------------------------------------------

2796 # Things related to aliases

2797 #-------------------------------------------------------------------------

2798

2799 def init_alias(self):

2800 self.alias_manager = AliasManager(shell=self, parent=self)

2801 self.configurables.append(self.alias_manager)

2802

2803 #-------------------------------------------------------------------------

2804 # Things related to extensions

2805 #-------------------------------------------------------------------------

2806

2807 def init_extension_manager(self):

2808 self.extension_manager = ExtensionManager(shell=self, parent=self)

2809 self.configurables.append(self.extension_manager)

2810

2811 #-------------------------------------------------------------------------

2812 # Things related to payloads

2813 #-------------------------------------------------------------------------

2814

2815 def init_payload(self):

2816 self.payload_manager = PayloadManager(parent=self)

2817 self.configurables.append(self.payload_manager)

2818

2819 #-------------------------------------------------------------------------

2820 # Things related to the prefilter

2821 #-------------------------------------------------------------------------

2822

2823 def init_prefilter(self):

2824 self.prefilter_manager = PrefilterManager(shell=self, parent=self)

2825 self.configurables.append(self.prefilter_manager)

2826 # Ultimately this will be refactored in the new interpreter code, but

2827 # for now, we should expose the main prefilter method (there's legacy

2828 # code out there that may rely on this).

2829 self.prefilter = self.prefilter_manager.prefilter_lines

2830

2831 def auto_rewrite_input(self, cmd):

2832 """Print to the screen the rewritten form of the user's command.

2833

2834 This shows visual feedback by rewriting input lines that cause

2835 automatic calling to kick in, like::

2837 /f x

2839 into::

2841 ------> f(x)

2843 after the user's input prompt. This helps the user understand that the

2844 input line was transformed automatically by IPython.

2845 """

2846 if not self.show_rewritten_input:

2847 return

2848

2849 # This is overridden in TerminalInteractiveShell to use fancy prompts

2850 print("------> " + cmd)

2851

2852 #-------------------------------------------------------------------------

2853 # Things related to extracting values/expressions from kernel and user_ns

2854 #-------------------------------------------------------------------------

2855

2856 def _user_obj_error(self):

2857 """return simple exception dict

2858

2859 for use in user_expressions

2860 """

2861

2862 etype, evalue, tb = self._get_exc_info()

2863 stb = self.InteractiveTB.get_exception_only(etype, evalue)

2864

2865 exc_info = {

2866 "status": "error",

2867 "traceback": stb,

2868 "ename": etype.__name__,

2869 "evalue": py3compat.safe_unicode(evalue),

2870 }

2871

2872 return exc_info

2873

2874 def _format_user_obj(self, obj):

2875 """format a user object to display dict

2876

2877 for use in user_expressions

2878 """

2879

2880 data, md = self.display_formatter.format(obj)

2881 value = {

2882 'status' : 'ok',

2883 'data' : data,

2884 'metadata' : md,

2885 }

2886 return value

2887

2888 def user_expressions(self, expressions):

2889 """Evaluate a dict of expressions in the user's namespace.

2890

2891 Parameters

2892 ----------

2893 expressions : dict

2894 A dict with string keys and string values. The expression values

2895 should be valid Python expressions, each of which will be evaluated

2896 in the user namespace.

2897

2898 Returns

2899 -------

2900 A dict, keyed like the input expressions dict, with the rich mime-typed

2901 display_data of each value.

2902 """

2903 out = {}

2904 user_ns = self.user_ns

2905 global_ns = self.user_global_ns

2906

2907 for key, expr in expressions.items():

2908 try:

2909 value = self._format_user_obj(eval(expr, global_ns, user_ns))

2910 except:

2911 value = self._user_obj_error()

2912 out[key] = value

2913 return out

2914

2915 #-------------------------------------------------------------------------

2916 # Things related to the running of code

2917 #-------------------------------------------------------------------------

2918

2919 def ex(self, cmd):

2920 """Execute a normal python statement in user namespace."""

2921 with self.builtin_trap:

2922 exec(cmd, self.user_global_ns, self.user_ns)

2923

2924 def ev(self, expr):

2925 """Evaluate python expression expr in user namespace.

2926

2927 Returns the result of evaluation

2928 """

2929 with self.builtin_trap:

2930 return eval(expr, self.user_global_ns, self.user_ns)

2931

2932 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):

2933 """A safe version of the builtin execfile().

2934

2935 This version will never throw an exception, but instead print

2936 helpful error messages to the screen. This only works on pure

2937 Python files with the .py extension.

2938

2939 Parameters

2940 ----------

2941 fname : string

2942 The name of the file to be executed.

2943 *where : tuple

2944 One or two namespaces, passed to execfile() as (globals,locals).

2945 If only one is given, it is passed as both.

2946 exit_ignore : bool (False)

2947 If True, then silence SystemExit for non-zero status (it is always

2948 silenced for zero status, as it is so common).

2949 raise_exceptions : bool (False)

2950 If True raise exceptions everywhere. Meant for testing.

2951 shell_futures : bool (False)

2952 If True, the code will share future statements with the interactive

2953 shell. It will both be affected by previous __future__ imports, and

2954 any __future__ imports in the code will affect the shell. If False,

2955 __future__ imports are not shared in either direction.

2956

2957 """

2958 fname = Path(fname).expanduser().resolve()

2959

2960 # Make sure we can open the file

2961 try:

2962 with fname.open("rb"):

2963 pass

2964 except:

2965 warn('Could not open file <%s> for safe execution.' % fname)

2966 return

2967

2968 # Find things also in current directory. This is needed to mimic the

2969 # behavior of running a script from the system command line, where

2970 # Python inserts the script's directory into sys.path

2971 dname = str(fname.parent)

2972

2973 with prepended_to_syspath(dname), self.builtin_trap:

2974 try:

2975 glob, loc = (where + (None, ))[:2]

2976 py3compat.execfile(

2977 fname, glob, loc,

2978 self.compile if shell_futures else None)

2979 except SystemExit as status:

2980 # If the call was made with 0 or None exit status (sys.exit(0)

2981 # or sys.exit() ), don't bother showing a traceback, as both of

2982 # these are considered normal by the OS:

2983 # > python -c'import sys;sys.exit(0)'; echo $?

2984 # 0

2985 # > python -c'import sys;sys.exit()'; echo $?

2986 # 0

2987 # For other exit status, we show the exception unless

2988 # explicitly silenced, but only in short form.

2989 if status.code:

2990 if raise_exceptions:

2991 raise

2992 if not exit_ignore:

2993 self.showtraceback(exception_only=True)

2994 except:

2995 if raise_exceptions:

2996 raise

2997 # tb offset is 2 because we wrap execfile

2998 self.showtraceback(tb_offset=2)

2999

3000 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):

3001 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.

3002

3003 Parameters

3004 ----------

3005 fname : str

3006 The name of the file to execute. The filename must have a

3007 .ipy or .ipynb extension.

3008 shell_futures : bool (False)

3009 If True, the code will share future statements with the interactive

3010 shell. It will both be affected by previous __future__ imports, and

3011 any __future__ imports in the code will affect the shell. If False,

3012 __future__ imports are not shared in either direction.

3013 raise_exceptions : bool (False)

3014 If True raise exceptions everywhere. Meant for testing.

3015 """

3016 fname = Path(fname).expanduser().resolve()

3017

3018 # Make sure we can open the file

3019 try:

3020 with fname.open("rb"):

3021 pass

3022 except:

3023 warn('Could not open file <%s> for safe execution.' % fname)

3024 return

3025

3026 # Find things also in current directory. This is needed to mimic the

3027 # behavior of running a script from the system command line, where

3028 # Python inserts the script's directory into sys.path

3029 dname = str(fname.parent)

3030

3031 def get_cells():

3032 """generator for sequence of code blocks to run"""

3033 if fname.suffix == ".ipynb":

3034 from nbformat import read

3035 nb = read(fname, as_version=4)

3036 if not nb.cells:

3037 return

3038 for cell in nb.cells:

3039 if cell.cell_type == 'code':

3040 yield cell.source

3041 else:

3042 yield fname.read_text(encoding="utf-8")

3043

3044 with prepended_to_syspath(dname):

3045 try:

3046 for cell in get_cells():

3047 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)

3048 if raise_exceptions:

3049 result.raise_error()

3050 elif not result.success:

3051 break

3052 except:

3053 if raise_exceptions:

3054 raise

3055 self.showtraceback()

3056 warn('Unknown failure executing file: <%s>' % fname)

3057

3058 def safe_run_module(self, mod_name, where):

3059 """A safe version of runpy.run_module().

3060

3061 This version will never throw an exception, but instead print

3062 helpful error messages to the screen.

3063

3064 `SystemExit` exceptions with status code 0 or None are ignored.

3065

3066 Parameters

3067 ----------

3068 mod_name : string

3069 The name of the module to be executed.

3070 where : dict

3071 The globals namespace.

3072 """

3073 try:

3074 try:

3075 where.update(

3076 runpy.run_module(str(mod_name), run_name="__main__",

3077 alter_sys=True)

3078 )

3079 except SystemExit as status:

3080 if status.code:

3081 raise

3082 except:

3083 self.showtraceback()

3084 warn('Unknown failure executing module: <%s>' % mod_name)

3085

3086 @contextmanager

3087 def _tee(self, channel: Literal["stdout", "stderr"]):

3088 """Capture output of a given standard stream and store it in history.

3089

3090 Uses patching of write method for maximal compatibility,

3091 because ipykernel checks for instances of the stream class,

3092 and stream classes in ipykernel implement more complex logic.

3093 """

3094 stream = getattr(sys, channel)

3095 original_write = stream.write

3096 execution_count = self.execution_count

3097

3098 def write(data, *args, **kwargs):

3099 """Write data to both the original destination and the capture dictionary."""

3100 result = original_write(data, *args, **kwargs)

3101 if any(

3102 [

3103 self.display_pub.is_publishing,

3104 self.displayhook.is_active,

3105 self.showing_traceback,

3106 ]

3107 ):

3108 return result

3109 if not data:

3110 return result

3111 output_stream = None

3112 outputs_by_counter = self.history_manager.outputs

3113 output_type = "out_stream" if channel == "stdout" else "err_stream"

3114 if execution_count in outputs_by_counter:

3115 outputs = outputs_by_counter[execution_count]

3116 if outputs[-1].output_type == output_type:

3117 output_stream = outputs[-1]

3118 if output_stream is None:

3119 output_stream = HistoryOutput(

3120 output_type=output_type, bundle={"stream": []}

3121 )

3122 outputs_by_counter[execution_count].append(output_stream)

3123

3124 output_stream.bundle["stream"].append(data) # Append to existing stream

3125 return result

3126

3127 stream.write = write

3128 yield

3129 stream.write = original_write

3130

3131 def run_cell(

3132 self,

3133 raw_cell,

3134 store_history=False,

3135 silent=False,

3136 shell_futures=True,

3137 cell_id=None,

3138 ):

3139 """Run a complete IPython cell.

3140

3141 Parameters

3142 ----------

3143 raw_cell : str

3144 The code (including IPython code such as %magic functions) to run.

3145 store_history : bool

3146 If True, the raw and translated cell will be stored in IPython's

3147 history. For user code calling back into IPython's machinery, this

3148 should be set to False.

3149 silent : bool

3150 If True, avoid side-effects, such as implicit displayhooks and

3151 and logging. silent=True forces store_history=False.

3152 shell_futures : bool

3153 If True, the code will share future statements with the interactive

3154 shell. It will both be affected by previous __future__ imports, and

3155 any __future__ imports in the code will affect the shell. If False,

3156 __future__ imports are not shared in either direction.

3157 cell_id : str, optional

3158 A unique identifier for the cell. This is used in the messaging system

3159 to match output with execution requests and for tracking cell execution

3160 history across kernel restarts. In notebook contexts, this is typically

3161 a UUID generated by the frontend. If None, the kernel may generate an

3162 internal identifier or proceed without cell tracking capabilities.

3163 Returns

3164 -------

3165 result : :class:`ExecutionResult`

3166 """

3167 result = None

3168 with self._tee(channel="stdout"), self._tee(channel="stderr"):

3169 try:

3170 result = self._run_cell(

3171 raw_cell, store_history, silent, shell_futures, cell_id

3172 )

3173 finally:

3174 self.events.trigger("post_execute")

3175 if not silent:

3176 self.events.trigger("post_run_cell", result)

3177 return result

3178

3179 def _run_cell(

3180 self,

3181 raw_cell: str,

3182 store_history: bool,

3183 silent: bool,

3184 shell_futures: bool,

3185 cell_id: str,

3186 ) -> ExecutionResult:

3187 """Internal method to run a complete IPython cell."""

3188

3189 # we need to avoid calling self.transform_cell multiple time on the same thing

3190 # so we need to store some results:

3191 preprocessing_exc_tuple = None

3192 try:

3193 transformed_cell = self.transform_cell(raw_cell)

3194 except Exception:

3195 transformed_cell = raw_cell

3196 preprocessing_exc_tuple = sys.exc_info()

3197

3198 assert transformed_cell is not None

3199 coro = self.run_cell_async(

3200 raw_cell,

3201 store_history=store_history,

3202 silent=silent,

3203 shell_futures=shell_futures,

3204 transformed_cell=transformed_cell,

3205 preprocessing_exc_tuple=preprocessing_exc_tuple,

3206 cell_id=cell_id,

3207 )

3208

3209 # run_cell_async is async, but may not actually need an eventloop.

3210 # when this is the case, we want to run it using the pseudo_sync_runner

3211 # so that code can invoke eventloops (for example via the %run , and

3212 # `%paste` magic.

3213 if self.trio_runner:

3214 runner = self.trio_runner

3215 elif self.should_run_async(

3216 raw_cell,

3217 transformed_cell=transformed_cell,

3218 preprocessing_exc_tuple=preprocessing_exc_tuple,

3219 ):

3220 runner = self.loop_runner

3221 else:

3222 runner = _pseudo_sync_runner

3223

3224 try:

3225 result = runner(coro)

3226 except BaseException as e:

3227 try:

3228 info = ExecutionInfo(

3229 raw_cell,

3230 store_history,

3231 silent,

3232 shell_futures,

3233 cell_id,

3234 transformed_cell=transformed_cell,

3235 )

3236 result = ExecutionResult(info)

3237 result.error_in_exec = e

3238 self.showtraceback(running_compiled_code=True)

3239 except:

3240 pass

3241 return result

3242

3243 def should_run_async(

3244 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None

3245 ) -> bool:

3246 """Return whether a cell should be run asynchronously via a coroutine runner

3247

3248 Parameters

3249 ----------

3250 raw_cell : str

3251 The code to be executed

3252

3253 Returns

3254 -------

3255 result: bool

3256 Whether the code needs to be run with a coroutine runner or not

3257 .. versionadded:: 7.0

3258 """

3259 if not self.autoawait:

3260 return False

3261 if preprocessing_exc_tuple is not None:

3262 return False

3263 assert preprocessing_exc_tuple is None

3264 if transformed_cell is None:

3265 warnings.warn(

3266 "`should_run_async` will not call `transform_cell`"

3267 " automatically in the future. Please pass the result to"

3268 " `transformed_cell` argument and any exception that happen"

3269 " during the"

3270 "transform in `preprocessing_exc_tuple` in"

3271 " IPython 7.17 and above.",

3272 DeprecationWarning,

3273 stacklevel=2,

3274 )

3275 try:

3276 cell = self.transform_cell(raw_cell)

3277 except Exception:

3278 # any exception during transform will be raised

3279 # prior to execution

3280 return False

3281 else:

3282 cell = transformed_cell

3283 return _should_be_async(cell)

3284

3285 async def run_cell_async(

3286 self,

3287 raw_cell: str,

3288 store_history=False,

3289 silent=False,

3290 shell_futures=True,

3291 *,

3292 transformed_cell: Optional[str] = None,

3293 preprocessing_exc_tuple: Optional[AnyType] = None,

3294 cell_id=None,

3295 ) -> ExecutionResult:

3296 """Run a complete IPython cell asynchronously.

3297

3298 Parameters

3299 ----------

3300 raw_cell : str

3301 The code (including IPython code such as %magic functions) to run.

3302 store_history : bool

3303 If True, the raw and translated cell will be stored in IPython's

3304 history. For user code calling back into IPython's machinery, this

3305 should be set to False.

3306 silent : bool

3307 If True, avoid side-effects, such as implicit displayhooks and

3308 and logging. silent=True forces store_history=False.

3309 shell_futures : bool

3310 If True, the code will share future statements with the interactive

3311 shell. It will both be affected by previous __future__ imports, and

3312 any __future__ imports in the code will affect the shell. If False,

3313 __future__ imports are not shared in either direction.

3314 transformed_cell: str

3315 cell that was passed through transformers

3316 preprocessing_exc_tuple:

3317 trace if the transformation failed.

3318

3319 Returns

3320 -------

3321 result : :class:`ExecutionResult`

3322

3323 .. versionadded:: 7.0

3324 """

3325 info = ExecutionInfo(

3326 raw_cell,

3327 store_history,

3328 silent,

3329 shell_futures,

3330 cell_id,

3331 transformed_cell=transformed_cell,

3332 )

3333 result = ExecutionResult(info)

3334

3335 if (not raw_cell) or raw_cell.isspace():

3336 self.last_execution_succeeded = True

3337 self.last_execution_result = result

3338 return result

3339

3340 if silent:

3341 store_history = False

3342

3343 execution_count = result.execution_count = self.execution_count

3344

3345 if store_history:

3346 self.execution_count += 1

3347

3348 def error_before_exec(value):

3349 if store_history:

3350 if self.history_manager:

3351 # Store formatted traceback and error details

3352 self.history_manager.exceptions[

3353 execution_count

3354 ] = self._format_exception_for_storage(value)

3355 result.error_before_exec = value

3356 self.last_execution_succeeded = False

3357 self.last_execution_result = result

3358 return result

3359

3360 self.events.trigger('pre_execute')

3361 if not silent:

3362 self.events.trigger('pre_run_cell', info)

3363

3364 if transformed_cell is None:

3365 warnings.warn(

3366 "`run_cell_async` will not call `transform_cell`"

3367 " automatically in the future. Please pass the result to"

3368 " `transformed_cell` argument and any exception that happen"

3369 " during the"

3370 "transform in `preprocessing_exc_tuple` in"

3371 " IPython 7.17 and above.",

3372 DeprecationWarning,

3373 stacklevel=2,

3374 )

3375 # If any of our input transformation (input_transformer_manager or

3376 # prefilter_manager) raises an exception, we store it in this variable

3377 # so that we can display the error after logging the input and storing

3378 # it in the history.

3379 try:

3380 cell = self.transform_cell(raw_cell)

3381 except Exception:

3382 preprocessing_exc_tuple = sys.exc_info()

3383 cell = raw_cell # cell has to exist so it can be stored/logged

3384 else:

3385 preprocessing_exc_tuple = None

3386 else:

3387 if preprocessing_exc_tuple is None:

3388 cell = transformed_cell

3389 else:

3390 cell = raw_cell

3391

3392 # Do NOT store paste/cpaste magic history

3393 if "get_ipython().run_line_magic(" in cell and "paste" in cell:

3394 store_history = False

3395

3396 # Store raw and processed history

3397 if store_history:

3398 assert self.history_manager is not None

3399 self.history_manager.store_inputs(execution_count, cell, raw_cell)

3400 if not silent:

3401 self.logger.log(cell, raw_cell)

3402

3403 # Display the exception if input processing failed.

3404 if preprocessing_exc_tuple is not None:

3405 self.showtraceback(preprocessing_exc_tuple)

3406 return error_before_exec(preprocessing_exc_tuple[1])

3407

3408 # Our own compiler remembers the __future__ environment. If we want to

3409 # run code with a separate __future__ environment, use the default

3410 # compiler

3411 compiler = self.compile if shell_futures else self.compiler_class()

3412

3413 with self.builtin_trap:

3414 cell_name = compiler.cache(cell, execution_count, raw_code=raw_cell)

3415

3416 with self.display_trap:

3417 # Compile to bytecode

3418 try:

3419 code_ast = compiler.ast_parse(cell, filename=cell_name)

3420 except self.custom_exceptions as e:

3421 etype, value, tb = sys.exc_info()

3422 self.CustomTB(etype, value, tb)

3423 return error_before_exec(e)

3424 except IndentationError as e:

3425 self.showindentationerror()

3426 return error_before_exec(e)

3427 except (OverflowError, SyntaxError, ValueError, TypeError,

3428 MemoryError) as e:

3429 self.showsyntaxerror()

3430 return error_before_exec(e)

3431

3432 # Apply AST transformations

3433 try:

3434 code_ast = self.transform_ast(code_ast)

3435 except InputRejected as e:

3436 self.showtraceback()

3437 return error_before_exec(e)

3438

3439 # Give the displayhook a reference to our ExecutionResult so it

3440 # can fill in the output value.

3441 self.displayhook.exec_result = result

3442

3443 # Execute the user code

3444 interactivity = "none" if silent else self.ast_node_interactivity

3445

3446

3447 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,

3448 interactivity=interactivity, compiler=compiler, result=result)

3449

3450 self.last_execution_succeeded = not has_raised

3451 self.last_execution_result = result

3452

3453 # Reset this so later displayed values do not modify the

3454 # ExecutionResult

3455 self.displayhook.exec_result = None

3456

3457 if store_history:

3458 assert self.history_manager is not None

3459 # Write output to the database. Does nothing unless

3460 # history output logging is enabled.

3461 self.history_manager.store_output(execution_count)

3462 if result.error_in_exec:

3463 # Store formatted traceback and error details

3464 self.history_manager.exceptions[

3465 execution_count

3466 ] = self._format_exception_for_storage(result.error_in_exec)

3467

3468 return result

3469

3470 def _format_exception_for_storage(

3471 self, exception, filename=None, running_compiled_code=False

3472 ):

3473 """

3474 Format an exception's traceback and details for storage, with special handling

3475 for different types of errors.

3476 """

3477 etype = type(exception)

3478 evalue = exception

3479 tb = exception.__traceback__

3480

3481 # Handle SyntaxError and IndentationError with specific formatting

3482 if issubclass(etype, (SyntaxError, IndentationError)):

3483 if filename and isinstance(evalue, SyntaxError):

3484 try:

3485 evalue.filename = filename

3486 except:

3487 pass # Keep the original filename if modification fails

3488

3489 # Extract traceback if the error happened during compiled code execution

3490 elist = traceback.extract_tb(tb) if running_compiled_code else []

3491 stb = self.SyntaxTB.structured_traceback(etype, evalue, elist)

3492

3493 # Handle UsageError with a simple message

3494 elif etype is UsageError:

3495 stb = [f"UsageError: {evalue}"]

3496

3497 else:

3498 # Check if the exception (or its context) is an ExceptionGroup.

3499 def contains_exceptiongroup(val):

3500 if val is None:

3501 return False

3502 return isinstance(val, BaseExceptionGroup) or contains_exceptiongroup(

3503 val.__context__

3504 )

3505

3506 if contains_exceptiongroup(evalue):

3507 # Fallback: use the standard library's formatting for exception groups.

3508 stb = traceback.format_exception(etype, evalue, tb)

3509 else:

3510 try:

3511 # If the exception has a custom traceback renderer, use it.

3512 if hasattr(evalue, "_render_traceback_"):

3513 stb = evalue._render_traceback_()

3514 else:

3515 # Otherwise, use InteractiveTB to format the traceback.

3516 stb = self.InteractiveTB.structured_traceback(

3517 etype, evalue, tb, tb_offset=1

3518 )

3519 except Exception:

3520 # In case formatting fails, fallback to Python's built-in formatting.

3521 stb = traceback.format_exception(etype, evalue, tb)

3522

3523 return {"ename": etype.__name__, "evalue": str(evalue), "traceback": stb}

3524

3525 def transform_cell(self, raw_cell):

3526 """Transform an input cell before parsing it.

3527

3528 Static transformations, implemented in IPython.core.inputtransformer2,

3529 deal with things like ``%magic`` and ``!system`` commands.

3530 These run on all input.

3531 Dynamic transformations, for things like unescaped magics and the exit

3532 autocall, depend on the state of the interpreter.

3533 These only apply to single line inputs.

3534

3535 These string-based transformations are followed by AST transformations;

3536 see :meth:`transform_ast`.

3537 """

3538 # Static input transformations

3539 cell = self.input_transformer_manager.transform_cell(raw_cell)

3540

3541 if len(cell.splitlines()) == 1:

3542 # Dynamic transformations - only applied for single line commands

3543 with self.builtin_trap:

3544 # use prefilter_lines to handle trailing newlines

3545 # restore trailing newline for ast.parse

3546 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'

3547

3548 lines = cell.splitlines(keepends=True)

3549 for transform in self.input_transformers_post:

3550 lines = transform(lines)

3551 cell = ''.join(lines)

3552

3553 return cell

3554

3555 def transform_ast(self, node):

3556 """Apply the AST transformations from self.ast_transformers

3557

3558 Parameters

3559 ----------

3560 node : ast.Node

3561 The root node to be transformed. Typically called with the ast.Module

3562 produced by parsing user input.

3563

3564 Returns

3565 -------

3566 An ast.Node corresponding to the node it was called with. Note that it

3567 may also modify the passed object, so don't rely on references to the

3568 original AST.

3569 """

3570 for transformer in self.ast_transformers:

3571 try:

3572 node = transformer.visit(node)

3573 except InputRejected:

3574 # User-supplied AST transformers can reject an input by raising

3575 # an InputRejected. Short-circuit in this case so that we

3576 # don't unregister the transform.

3577 raise

3578 except Exception as e:

3579 warn(

3580 "AST transformer %r threw an error. It will be unregistered. %s"

3581 % (transformer, e)

3582 )

3583 self.ast_transformers.remove(transformer)

3584

3585 if self.ast_transformers:

3586 ast.fix_missing_locations(node)

3587 return node

3588

3589 async def run_ast_nodes(

3590 self,

3591 nodelist: ListType[stmt],

3592 cell_name: str,

3593 interactivity="last_expr",

3594 compiler=compile,

3595 result=None,

3596 ):

3597 """Run a sequence of AST nodes. The execution mode depends on the

3598 interactivity parameter.

3599

3600 Parameters

3601 ----------

3602 nodelist : list

3603 A sequence of AST nodes to run.

3604 cell_name : str

3605 Will be passed to the compiler as the filename of the cell. Typically

3606 the value returned by ip.compile.cache(cell).

3607 interactivity : str

3608 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',

3609 specifying which nodes should be run interactively (displaying output

3610 from expressions). 'last_expr' will run the last node interactively

3611 only if it is an expression (i.e. expressions in loops or other blocks

3612 are not displayed) 'last_expr_or_assign' will run the last expression

3613 or the last assignment. Other values for this parameter will raise a

3614 ValueError.

3615

3616 compiler : callable

3617 A function with the same interface as the built-in compile(), to turn

3618 the AST nodes into code objects. Default is the built-in compile().

3619 result : ExecutionResult, optional

3620 An object to store exceptions that occur during execution.

3621

3622 Returns

3623 -------

3624 True if an exception occurred while running code, False if it finished

3625 running.

3626 """

3627 if not nodelist:

3628 return

3629

3630

3631 if interactivity == 'last_expr_or_assign':

3632 if isinstance(nodelist[-1], _assign_nodes):

3633 asg = nodelist[-1]

3634 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:

3635 target = asg.targets[0]

3636 elif isinstance(asg, _single_targets_nodes):

3637 target = asg.target

3638 else:

3639 target = None

3640 if isinstance(target, ast.Name):

3641 nnode = ast.Expr(ast.Name(target.id, ast.Load()))

3642 ast.fix_missing_locations(nnode)

3643 nodelist.append(nnode)

3644 interactivity = 'last_expr'

3645

3646 _async = False

3647 if interactivity == 'last_expr':

3648 if isinstance(nodelist[-1], ast.Expr):

3649 interactivity = "last"

3650 else:

3651 interactivity = "none"

3652

3653 if interactivity == 'none':

3654 to_run_exec, to_run_interactive = nodelist, []

3655 elif interactivity == 'last':

3656 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]

3657 elif interactivity == 'all':

3658 to_run_exec, to_run_interactive = [], nodelist

3659 else:

3660 raise ValueError("Interactivity was %r" % interactivity)

3661

3662 try:

3663

3664 def compare(code):

3665 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE

3666 return is_async

3667

3668 # refactor that to just change the mod constructor.

3669 to_run = []

3670 for node in to_run_exec:

3671 to_run.append((node, "exec"))

3672

3673 for node in to_run_interactive:

3674 to_run.append((node, "single"))

3675

3676 for node, mode in to_run:

3677 if mode == "exec":

3678 mod = Module([node], [])

3679 elif mode == "single":

3680 mod = ast.Interactive([node])

3681 with compiler.extra_flags(

3682 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)

3683 if self.autoawait

3684 else 0x0

3685 ):

3686 code = compiler(mod, cell_name, mode)

3687 asy = compare(code)

3688 if await self.run_code(code, result, async_=asy):

3689 return True

3690

3691 # Flush softspace

3692 if softspace(sys.stdout, 0):

3693 print()

3694

3695 except:

3696 # It's possible to have exceptions raised here, typically by

3697 # compilation of odd code (such as a naked 'return' outside a

3698 # function) that did parse but isn't valid. Typically the exception

3699 # is a SyntaxError, but it's safest just to catch anything and show

3700 # the user a traceback.

3701

3702 # We do only one try/except outside the loop to minimize the impact

3703 # on runtime, and also because if any node in the node list is

3704 # broken, we should stop execution completely.

3705 if result:

3706 result.error_before_exec = sys.exc_info()[1]

3707 self.showtraceback()

3708 return True

3709

3710 return False

3711

3712 async def run_code(self, code_obj, result=None, *, async_=False):

3713 """Execute a code object.

3714

3715 When an exception occurs, self.showtraceback() is called to display a

3716 traceback.

3717

3718 Parameters

3719 ----------

3720 code_obj : code object

3721 A compiled code object, to be executed

3722 result : ExecutionResult, optional

3723 An object to store exceptions that occur during execution.

3724 async_ : Bool (Experimental)

3725 Attempt to run top-level asynchronous code in a default loop.

3726

3727 Returns

3728 -------

3729 False : successful execution.

3730 True : an error occurred.

3731 """

3732 # special value to say that anything above is IPython and should be

3733 # hidden.

3734 __tracebackhide__ = "__ipython_bottom__"

3735 # Set our own excepthook in case the user code tries to call it

3736 # directly, so that the IPython crash handler doesn't get triggered

3737 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook

3738

3739 # we save the original sys.excepthook in the instance, in case config

3740 # code (such as magics) needs access to it.

3741 self.sys_excepthook = old_excepthook

3742 outflag = True # happens in more places, so it's easier as default

3743 try:

3744 try:

3745 if async_:

3746 await eval(code_obj, self.user_global_ns, self.user_ns)

3747 else:

3748 exec(code_obj, self.user_global_ns, self.user_ns)

3749 finally:

3750 # Reset our crash handler in place

3751 sys.excepthook = old_excepthook

3752 except SystemExit as e:

3753 if result is not None:

3754 result.error_in_exec = e

3755 self.showtraceback(exception_only=True)

3756 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)

3757 except bdb.BdbQuit:

3758 etype, value, tb = sys.exc_info()

3759 if result is not None:

3760 result.error_in_exec = value

3761 # the BdbQuit stops here

3762 except self.custom_exceptions:

3763 etype, value, tb = sys.exc_info()

3764 if result is not None:

3765 result.error_in_exec = value

3766 self.CustomTB(etype, value, tb)

3767 except:

3768 if result is not None:

3769 result.error_in_exec = sys.exc_info()[1]

3770 self.showtraceback(running_compiled_code=True)

3771 else:

3772 outflag = False

3773 return outflag

3774

3775 # For backwards compatibility

3776 runcode = run_code

3777

3778 def check_complete(self, code: str) -> Tuple[str, str]:

3779 """Return whether a block of code is ready to execute, or should be continued

3780

3781 Parameters

3782 ----------

3783 code : string

3784 Python input code, which can be multiline.

3785

3786 Returns

3787 -------

3788 status : str

3789 One of 'complete', 'incomplete', or 'invalid' if source is not a

3790 prefix of valid code.

3791 indent : str

3792 When status is 'incomplete', this is some whitespace to insert on

3793 the next line of the prompt.

3794 """

3795 status, nspaces = self.input_transformer_manager.check_complete(code)

3796 return status, ' ' * (nspaces or 0)

3797

3798 #-------------------------------------------------------------------------

3799 # Things related to GUI support and pylab

3800 #-------------------------------------------------------------------------

3801

3802 active_eventloop: Optional[str] = None

3803

3804 def enable_gui(self, gui=None):

3805 raise NotImplementedError('Implement enable_gui in a subclass')

3806

3807 def enable_matplotlib(self, gui=None):

3808 """Enable interactive matplotlib and inline figure support.

3809

3810 This takes the following steps:

3811

3812 1. select the appropriate eventloop and matplotlib backend

3813 2. set up matplotlib for interactive use with that backend

3814 3. configure formatters for inline figure display

3815 4. enable the selected gui eventloop

3816

3817 Parameters

3818 ----------

3819 gui : optional, string

3820 If given, dictates the choice of matplotlib GUI backend to use

3821 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',

3822 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by

3823 matplotlib (as dictated by the matplotlib build-time options plus the

3824 user's matplotlibrc configuration file). Note that not all backends

3825 make sense in all contexts, for example a terminal ipython can't

3826 display figures inline.

3827 """

3828 from .pylabtools import _matplotlib_manages_backends

3829

3830 if not _matplotlib_manages_backends() and gui in (None, "auto"):

3831 # Early import of backend_inline required for its side effect of

3832 # calling _enable_matplotlib_integration()

3833 import matplotlib_inline.backend_inline

3834

3835 from IPython.core import pylabtools as pt

3836 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)

3837

3838 if gui != None:

3839 # If we have our first gui selection, store it

3840 if self.pylab_gui_select is None:

3841 self.pylab_gui_select = gui

3842 # Otherwise if they are different

3843 elif gui != self.pylab_gui_select:

3844 print('Warning: Cannot change to a different GUI toolkit: %s.'

3845 ' Using %s instead.' % (gui, self.pylab_gui_select))

3846 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)

3847

3848 pt.activate_matplotlib(backend)

3849

3850 from matplotlib_inline.backend_inline import configure_inline_support

3851

3852 configure_inline_support(self, backend)

3853

3854 # Now we must activate the gui pylab wants to use, and fix %run to take

3855 # plot updates into account

3856 self.enable_gui(gui)

3857 self.magics_manager.registry['ExecutionMagics'].default_runner = \

3858 pt.mpl_runner(self.safe_execfile)

3859

3860 return gui, backend

3861

3862 def enable_pylab(self, gui=None, import_all=True):

3863 """Activate pylab support at runtime.

3864

3865 This turns on support for matplotlib, preloads into the interactive

3866 namespace all of numpy and pylab, and configures IPython to correctly

3867 interact with the GUI event loop. The GUI backend to be used can be

3868 optionally selected with the optional ``gui`` argument.

3869

3870 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.

3871

3872 Parameters

3873 ----------

3874 gui : optional, string

3875 If given, dictates the choice of matplotlib GUI backend to use

3876 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',

3877 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by

3878 matplotlib (as dictated by the matplotlib build-time options plus the

3879 user's matplotlibrc configuration file). Note that not all backends

3880 make sense in all contexts, for example a terminal ipython can't

3881 display figures inline.

3882 import_all : optional, bool, default: True

3883 Whether to do `from numpy import *` and `from pylab import *`

3884 in addition to module imports.

3885 """

3886 from IPython.core.pylabtools import import_pylab

3887

3888 gui, backend = self.enable_matplotlib(gui)

3889

3890 # We want to prevent the loading of pylab to pollute the user's

3891 # namespace as shown by the %who* magics, so we execute the activation

3892 # code in an empty namespace, and we update *both* user_ns and

3893 # user_ns_hidden with this information.

3894 ns = {}

3895 import_pylab(ns, import_all)

3896 # warn about clobbered names

3897 ignored = {"__builtins__"}

3898 both = set(ns).intersection(self.user_ns).difference(ignored)

3899 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]

3900 self.user_ns.update(ns)

3901 self.user_ns_hidden.update(ns)

3902 return gui, backend, clobbered

3903

3904 #-------------------------------------------------------------------------

3905 # Utilities

3906 #-------------------------------------------------------------------------

3907

3908 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):

3909 """Expand python variables in a string.

3910

3911 The depth argument indicates how many frames above the caller should

3912 be walked to look for the local namespace where to expand variables.

3913

3914 The global namespace for expansion is always the user's interactive

3915 namespace.

3916 """

3917 ns = self.user_ns.copy()

3918 try:

3919 frame = sys._getframe(depth+1)

3920 except ValueError:

3921 # This is thrown if there aren't that many frames on the stack,

3922 # e.g. if a script called run_line_magic() directly.

3923 pass

3924 else:

3925 ns.update(frame.f_locals)

3926

3927 try:

3928 # We have to use .vformat() here, because 'self' is a valid and common

3929 # name, and expanding **ns for .format() would make it collide with

3930 # the 'self' argument of the method.

3931 cmd = formatter.vformat(cmd, args=[], kwargs=ns)

3932 except Exception:

3933 # if formatter couldn't format, just let it go untransformed

3934 pass

3935 return cmd

3936

3937 def mktempfile(self, data=None, prefix='ipython_edit_'):

3938 """Make a new tempfile and return its filename.

3939

3940 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),

3941 but it registers the created filename internally so ipython cleans it up

3942 at exit time.

3943

3944 Optional inputs:

3945

3946 - data(None): if data is given, it gets written out to the temp file

3947 immediately, and the file is closed again."""

3948

3949 dir_path = Path(tempfile.mkdtemp(prefix=prefix))

3950 self.tempdirs.append(dir_path)

3951

3952 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))

3953 os.close(handle) # On Windows, there can only be one open handle on a file

3954

3955 file_path = Path(filename)

3956 self.tempfiles.append(file_path)

3957

3958 if data:

3959 file_path.write_text(data, encoding="utf-8")

3960 return filename

3961

3962 def ask_yes_no(self, prompt, default=None, interrupt=None):

3963 if self.quiet:

3964 return True

3965 return ask_yes_no(prompt,default,interrupt)

3966

3967 def show_usage(self):

3968 """Show a usage message"""

3969 page.page(IPython.core.usage.interactive_usage)

3970

3971 def extract_input_lines(self, range_str, raw=False):

3972 """Return as a string a set of input history slices.

3973

3974 Parameters

3975 ----------

3976 range_str : str

3977 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",

3978 since this function is for use by magic functions which get their

3979 arguments as strings. The number before the / is the session

3980 number: ~n goes n back from the current session.

3981

3982 If empty string is given, returns history of current session

3983 without the last input.

3984

3985 raw : bool, optional

3986 By default, the processed input is used. If this is true, the raw

3987 input history is used instead.

3988

3989 Notes

3990 -----

3991 Slices can be described with two notations:

3992

3993 * ``N:M`` -> standard python form, means including items N...(M-1).

3994 * ``N-M`` -> include items N..M (closed endpoint).

3995 """

3996 lines = self.history_manager.get_range_by_str(range_str, raw=raw)

3997 text = "\n".join(x for _, _, x in lines)

3998

3999 # Skip the last line, as it's probably the magic that called this

4000 if not range_str:

4001 if "\n" not in text:

4002 text = ""

4003 else:

4004 text = text[: text.rfind("\n")]

4005

4006 return text

4007

4008 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):

4009 """Get a code string from history, file, url, or a string or macro.

4010

4011 This is mainly used by magic functions.

4012

4013 Parameters

4014 ----------

4015 target : str

4016 A string specifying code to retrieve. This will be tried respectively

4017 as: ranges of input history (see %history for syntax), url,

4018 corresponding .py file, filename, or an expression evaluating to a

4019 string or Macro in the user namespace.

4020

4021 If empty string is given, returns complete history of current

4022 session, without the last line.

4023

4024 raw : bool

4025 If true (default), retrieve raw history. Has no effect on the other

4026 retrieval mechanisms.

4027

4028 py_only : bool (default False)

4029 Only try to fetch python code, do not try alternative methods to decode file

4030 if unicode fails.

4031

4032 Returns

4033 -------

4034 A string of code.

4035 ValueError is raised if nothing is found, and TypeError if it evaluates

4036 to an object of another type. In each case, .args[0] is a printable

4037 message.

4038 """

4039 code = self.extract_input_lines(target, raw=raw) # Grab history

4040 if code:

4041 return code

4042 try:

4043 if target.startswith(('http://', 'https://')):

4044 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)

4045 except UnicodeDecodeError as e:

4046 if not py_only :

4047 # Deferred import

4048 from urllib.request import urlopen

4049 response = urlopen(target)

4050 return response.read().decode('latin1')

4051 raise ValueError(("'%s' seem to be unreadable.") % target) from e

4052

4053 potential_target = [target]

4054 try :

4055 potential_target.insert(0,get_py_filename(target))

4056 except IOError:

4057 pass

4058

4059 for tgt in potential_target :

4060 if os.path.isfile(tgt): # Read file

4061 try :

4062 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)

4063 except UnicodeDecodeError as e:

4064 if not py_only :

4065 with io_open(tgt,'r', encoding='latin1') as f :

4066 return f.read()

4067 raise ValueError(("'%s' seem to be unreadable.") % target) from e

4068 elif os.path.isdir(os.path.expanduser(tgt)):

4069 raise ValueError("'%s' is a directory, not a regular file." % target)

4070

4071 if search_ns:

4072 # Inspect namespace to load object source

4073 object_info = self.object_inspect(target, detail_level=1)

4074 if object_info['found'] and object_info['source']:

4075 return object_info['source']

4076

4077 try: # User namespace

4078 codeobj = eval(target, self.user_ns)

4079 except Exception as e:

4080 raise ValueError(("'%s' was not found in history, as a file, url, "

4081 "nor in the user namespace.") % target) from e

4082

4083 if isinstance(codeobj, str):

4084 return codeobj

4085 elif isinstance(codeobj, Macro):

4086 return codeobj.value

4087

4088 raise TypeError("%s is neither a string nor a macro." % target,

4089 codeobj)

4090

4091 def _atexit_once(self):

4092 """

4093 At exist operation that need to be called at most once.

4094 Second call to this function per instance will do nothing.

4095 """

4096

4097 if not getattr(self, "_atexit_once_called", False):

4098 self._atexit_once_called = True

4099 # Clear all user namespaces to release all references cleanly.

4100 self.reset(new_session=False)

4101 # Close the history session (this stores the end time and line count)

4102 # this must be *before* the tempfile cleanup, in case of temporary

4103 # history db

4104 if self.history_manager is not None:

4105 self.history_manager.end_session()

4106 self.history_manager = None

4107

4108 #-------------------------------------------------------------------------

4109 # Things related to IPython exiting

4110 #-------------------------------------------------------------------------

4111 def atexit_operations(self):

4112 """This will be executed at the time of exit.

4113

4114 Cleanup operations and saving of persistent data that is done

4115 unconditionally by IPython should be performed here.

4116

4117 For things that may depend on startup flags or platform specifics (such

4118 as having readline or not), register a separate atexit function in the

4119 code that has the appropriate information, rather than trying to

4120 clutter

4121 """

4122 self._atexit_once()

4123

4124 # Cleanup all tempfiles and folders left around

4125 for tfile in self.tempfiles:

4126 try:

4127 tfile.unlink()

4128 self.tempfiles.remove(tfile)

4129 except FileNotFoundError:

4130 pass

4131 del self.tempfiles

4132 for tdir in self.tempdirs:

4133 try:

4134 shutil.rmtree(tdir)

4135 self.tempdirs.remove(tdir)

4136 except FileNotFoundError:

4137 pass

4138 del self.tempdirs

4139

4140 # Restore user's cursor

4141 if hasattr(self, "editing_mode") and self.editing_mode == "vi":

4142 sys.stdout.write("\x1b[0 q")

4143 sys.stdout.flush()

4144

4145 def cleanup(self):

4146 self.restore_sys_module_state()

4147

4148

4149 # Overridden in terminal subclass to change prompts

4150 def switch_doctest_mode(self, mode):

4151 pass

4152

4153

4154class InteractiveShellABC(metaclass=abc.ABCMeta):

4155 """An abstract base class for InteractiveShell."""

4156

4157InteractiveShellABC.register(InteractiveShell)