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 Any as AnyType

38from typing import Literal

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

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: Callable | None

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().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 cell_meta = None

264

265 def __init__(

266 self,

267 raw_cell,

268 store_history,

269 silent,

270 shell_futures,

271 cell_id,

272 cell_meta=None,

273 transformed_cell=None,

274 ):

275 self.raw_cell = raw_cell

276 self.transformed_cell = transformed_cell

277 self.store_history = store_history

278 self.silent = silent

279 self.shell_futures = shell_futures

280 self.cell_id = cell_id

281 self.cell_meta = cell_meta

282

283 def __repr__(self):

284 name = self.__class__.__qualname__

285 raw_cell = (

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

287 )

288 transformed_cell = (

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

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

291 else self.transformed_cell

292 )

293 return (

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

295 % (

296 name,

297 id(self),

298 raw_cell,

299 transformed_cell,

300 self.store_history,

301 self.silent,

302 self.shell_futures,

303 self.cell_id,

304 self.cell_meta,

305 )

306 )

307

308

309class ExecutionResult:

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

311

312 Stores information about what took place.

313 """

314

315 execution_count: int | None = None

316 error_before_exec: BaseException | None = None

317 error_in_exec: BaseException | None = None

318 info = None

319 result = None

320

321 def __init__(self, info):

322 self.info = info

323

324 @property

325 def success(self):

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

327

328 def raise_error(self):

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

330 if self.error_before_exec is not None:

331 raise self.error_before_exec

332 if self.error_in_exec is not None:

333 raise self.error_in_exec

334

335 def __repr__(self):

336 name = self.__class__.__qualname__

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

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

339

340

341@functools.wraps(io_open)

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

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

344 raise ValueError(

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

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

347 "you can use builtins' open."

348 )

349

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

351

352

353_dollar_formatter = DollarFormatter()

354

355

356class InteractiveShell(SingletonConfigurable):

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

358

359 _instance = None

360 _user_ns: dict

361 _sys_modules_keys: set[str]

362

363 inspector: oinspect.Inspector

364

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

366 [],

367 help="""

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

369 to user input before code is run.

370 """,

371 ).tag(config=True)

372

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

374 """

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

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

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

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

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

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

381 """

382 ).tag(config=True)

383

384 autoindent = Bool(True, help=

385 """

386 Autoindent IPython code entered interactively.

387 """

388 ).tag(config=True)

389

390 autoawait = Bool(True, help=

391 """

392 Automatically run await statement in the top level repl.

393 """

394 ).tag(config=True)

395

396 loop_runner_map ={

397 'asyncio':(_asyncio_runner, True),

398 'curio':(_curio_runner, True),

399 'trio':(_trio_runner, True),

400 'sync': (_pseudo_sync_runner, False)

401 }

402

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

404 allow_none=True,

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

406 ).tag(config=True)

407

408 @default('loop_runner')

409 def _default_loop_runner(self):

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

411

412 @validate('loop_runner')

413 def _import_runner(self, proposal):

414 if isinstance(proposal.value, str):

415 if proposal.value in self.loop_runner_map:

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

417 self.autoawait = autoawait

418 return runner

419 runner = import_item(proposal.value)

420 if not callable(runner):

421 raise ValueError('loop_runner must be callable')

422 return runner

423 if not callable(proposal.value):

424 raise ValueError('loop_runner must be callable')

425 return proposal.value

426

427 automagic = Bool(True, help=

428 """

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

430 """

431 ).tag(config=True)

432

433 enable_tip = Bool(

434 True,

435 help="""

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

437 ).tag(config=True)

438

439 banner1 = Unicode(default_banner,

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

441 ).tag(config=True)

442 banner2 = Unicode('',

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

444 ).tag(config=True)

445

446 cache_size = Integer(

447 1000,

448 help="""

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

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

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

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

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

454 time re-flushing a too small cache than working

455 """,

456 ).tag(config=True)

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

458 display_formatter = Instance(DisplayFormatter, allow_none=True)

459 displayhook_class = Type(DisplayHook)

460 display_pub_class = Type(DisplayPublisher)

461 compiler_class = Type(CachingCompiler)

462 inspector_class = Type(

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

464 ).tag(config=True)

465

466 sphinxify_docstring = Bool(False, help=

467 """

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

469 docrepr module).

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

471

472 @observe("sphinxify_docstring")

473 def _sphinxify_docstring_changed(self, change):

474 if change['new']:

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

476

477 enable_html_pager = Bool(False, help=

478 """

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

480 to pagers.

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

482

483 @observe("enable_html_pager")

484 def _enable_html_pager_changed(self, change):

485 if change['new']:

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

487

488 # Not a traitlets trait: a plain class-attribute override point for

489 # subclasses that want to set a data_pub class.

490 data_pub_class: type | None = None

491

492 exit_now = Bool(False)

493 exiter = Instance(ExitAutocall)

494 @default('exiter')

495 def _exiter_default(self):

496 return ExitAutocall(self)

497 # Monotonically increasing execution counter

498 execution_count = Integer(1)

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

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

501

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

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

504 ())

505

506 @property

507 def input_transformers_cleanup(self):

508 return self.input_transformer_manager.cleanup_transforms

509

510 input_transformers_post: List = List(

511 [],

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

513 "own input transformations."

514 )

515

516 logstart = Bool(False, help=

517 """

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

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

520 """

521 ).tag(config=True)

522 logfile = Unicode('', help=

523 """

524 The name of the logfile to use.

525 """

526 ).tag(config=True)

527 logappend = Unicode('', help=

528 """

529 Start logging to the given file in append mode.

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

531 """

532 ).tag(config=True)

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

534 ).tag(config=True)

535 pdb = Bool(False, help=

536 """

537 Automatically call the pdb debugger after every exception.

538 """

539 ).tag(config=True)

540 display_page = Bool(False,

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

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

543 ).tag(config=True)

544

545

546 show_rewritten_input = Bool(True,

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

548 ).tag(config=True)

549

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

551

552 system_raise_on_error = Bool(False, help=

553 """

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

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

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

557 """

558 ).tag(config=True)

559

560 history_length = Integer(10000,

561 help='Total length of command history'

562 ).tag(config=True)

563

564 history_load_length = Integer(1000, help=

565 """

566 The number of saved history entries to be loaded

567 into the history buffer at startup.

568 """

569 ).tag(config=True)

570

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

572 default_value='last_expr',

573 help="""

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

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

576 """

577 ).tag(config=True)

578

579 warn_venv = Bool(

580 True,

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

582 ).tag(config=True)

583

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

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

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

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

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

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

590 xmode = CaselessStrEnum(

591 ("Context", "Plain", "Verbose", "Minimal", "Docs", "Doctest"),

592 default_value="Context",

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

594 ).tag(config=True)

595

596 # Subcomponents of InteractiveShell

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

598 prefilter_manager = Instance(

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

600 )

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

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

603 extension_manager = Instance(

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

605 )

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

607 history_manager = Instance(

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

609 )

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

611

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

613 @property

614 def profile(self):

615 if self.profile_dir is not None:

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

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

618

619

620 # Private interface

621 _post_execute = Dict()

622

623 # Tracks any GUI loop loaded for pylab

624 pylab_gui_select: str | None = None

625

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

627

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

629

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

631 user_module=None, user_ns=None,

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

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

634 # from the values on config.

635 super().__init__(**kwargs)

636 self.configurables = [self]

637

638 # These are relatively independent and stateless

639 self.init_ipython_dir(ipython_dir)

640 self.init_profile_dir(profile_dir)

641 self.init_instance_attrs()

642 self.init_environment()

643

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

645 self.init_virtualenv()

646

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

648 self.init_create_namespaces(user_module, user_ns)

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

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

651 # is the first thing to modify sys.

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

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

654 # is what we want to do.

655 self.save_sys_module_state()

656 self.init_sys_modules()

657

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

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

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

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

662

663 self.init_history()

664 self.init_encoding()

665 self.init_prefilter()

666

667 self.init_syntax_highlighting()

668 self.init_hooks()

669 self.init_events()

670 self.init_pushd_popd_magic()

671 self.init_user_ns()

672 self.init_logger()

673 self.init_builtins()

674

675 # The following was in post_config_initialization

676 self.raw_input_original = input

677 self.init_completer()

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

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

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

681 self.init_io()

682 self.init_traceback_handlers(custom_exceptions)

683 self.init_prompts()

684 self.init_display_formatter()

685 self.init_display_pub()

686 self.init_data_pub()

687 self.init_displayhook()

688 self.init_magics()

689 self.init_alias()

690 self.init_logstart()

691 self.init_pdb()

692 self.init_extension_manager()

693 self.init_payload()

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

695 atexit.register(self.atexit_operations)

696

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

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

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

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

701 # `ipykernel.kernelapp`.

702 self.trio_runner = None

703 self.showing_traceback = False

704

705 @property

706 def user_ns(self):

707 return self._user_ns

708

709 @user_ns.setter

710 def user_ns(self, ns: dict):

711 assert hasattr(ns, "clear")

712 assert isinstance(ns, dict)

713 self._user_ns = ns

714

715 def get_ipython(self):

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

717 return self

718

719 #-------------------------------------------------------------------------

720 # Trait changed handlers

721 #-------------------------------------------------------------------------

722 @observe('ipython_dir')

723 def _ipython_dir_changed(self, change):

724 ensure_dir_exists(change['new'])

725

726 def set_autoindent(self,value=None):

727 """Set the autoindent flag.

728

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

730 if value is None:

731 self.autoindent = not self.autoindent

732 else:

733 self.autoindent = value

734

735 def set_trio_runner(self, tr):

736 self.trio_runner = tr

737

738 #-------------------------------------------------------------------------

739 # init_* methods called by __init__

740 #-------------------------------------------------------------------------

741

742 def init_ipython_dir(self, ipython_dir):

743 if ipython_dir is not None:

744 self.ipython_dir = ipython_dir

745 return

746

747 self.ipython_dir = get_ipython_dir()

748

749 def init_profile_dir(self, profile_dir):

750 if profile_dir is not None:

751 self.profile_dir = profile_dir

752 return

753 self.profile_dir = ProfileDir.create_profile_dir_by_name(

754 self.ipython_dir, "default"

755 )

756

757 def init_instance_attrs(self):

758 self.more = False

759

760 # command compiler

761 self.compile = self.compiler_class()

762

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

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

765 # convenient location for storing additional information and state

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

767 # ipython names that may develop later.

768 self.meta = Struct()

769

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

771 # The files here are stored with Path from Pathlib

772 self.tempfiles = []

773 self.tempdirs = []

774

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

776 # This is not being used anywhere currently.

777 self.starting_dir = os.getcwd()

778

779 # Indentation management

780 self.indent_current_nsp = 0

781

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

783 self._post_execute = {}

784

785 def init_environment(self):

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

787 pass

788

789 def init_encoding(self):

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

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

792 # encoding to use in the raw_input() method

793 try:

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

795 except AttributeError:

796 self.stdin_encoding = 'ascii'

797

798 colors = Unicode(

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

800 ).tag(config=True)

801

802 @validate("colors")

803 def _check_colors(self, proposal):

804 new = proposal["value"]

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

806 warn(

807 f"`TerminalInteractiveShell.colors` is now lowercase since IPython 9.0: `{new.lower()}`,"

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

809 DeprecationWarning,

810 stacklevel=2,

811 )

812 return new.lower()

813

814 @observe("colors")

815 def init_syntax_highlighting(self, changes=None):

816 # Python source parser/formatter for syntax highlighting

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

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

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

820 self.inspector = self.inspector_class(

821 theme_name=self.colors,

822 str_detail_level=self.object_info_string_level,

823 parent=self,

824 )

825

826 try:

827 # Deprecation in 9.0, colors should always be lower

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

829 except Exception:

830 warn(

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

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

833 stacklevel=2,

834 )

835 if hasattr(self, "InteractiveTB"):

836 self.InteractiveTB.set_theme_name(self.colors)

837 if hasattr(self, "SyntaxTB"):

838 self.SyntaxTB.set_theme_name(self.colors)

839 self.refresh_style()

840

841 def refresh_style(self):

842 # No-op here, used in subclass

843 pass

844

845 def init_pushd_popd_magic(self):

846 # for pushd/popd management

847 self.home_dir = get_home_dir()

848

849 self.dir_stack = []

850

851 def init_logger(self) -> None:

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

853 logmode='rotate')

854

855 def init_logstart(self) -> None:

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

857 """

858 if self.logappend:

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

860 elif self.logfile:

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

862 elif self.logstart:

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

864

865 def init_builtins(self):

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

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

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

869 # IPython at a time.

870 builtin_mod.__dict__['__IPYTHON__'] = True

871 builtin_mod.__dict__['display'] = display

872

873 self.builtin_trap = BuiltinTrap(shell=self)

874

875

876 def init_io(self):

877 # implemented in subclasses, TerminalInteractiveShell does call

878 # colorama.init().

879 pass

880

881 def init_prompts(self):

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

883 # interactively.

884 sys.ps1 = 'In : '

885 sys.ps2 = '...: '

886 sys.ps3 = 'Out: '

887

888 def init_display_formatter(self):

889 self.display_formatter = DisplayFormatter(parent=self)

890 self.configurables.append(self.display_formatter)

891

892 def init_display_pub(self):

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

894 self.configurables.append(self.display_pub)

895

896 def init_data_pub(self):

897 if not self.data_pub_class:

898 self.data_pub = None

899 return

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

901 self.configurables.append(self.data_pub)

902

903 def init_displayhook(self):

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

905 self.displayhook = self.displayhook_class(

906 parent=self,

907 shell=self,

908 cache_size=self.cache_size,

909 )

910 self.configurables.append(self.displayhook)

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

912 # the appropriate time.

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

914

915 @staticmethod

916 def get_path_links(p: Path):

917 """Gets path links including all symlinks

918

919 Examples

920 --------

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

922

923 In [2]: import sys, pathlib

924

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

926

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

928 Out[4]: True

929

930 In [5]: bool(paths)

931 Out[5]: True

932 """

933 paths = [p]

934 while p.is_symlink():

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

936 if not new_path.is_absolute():

937 new_path = p.parent / new_path

938 p = new_path

939 paths.append(p)

940 return paths

941

942 def init_virtualenv(self):

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

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

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

946 warning will appear suggesting the user installs IPython in the

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

948

949 Adapted from code snippets online.

950

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

952 """

953 if 'VIRTUAL_ENV' not in os.environ:

954 # Not in a virtualenv

955 return

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

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

958 return

959

960 p = Path(sys.executable)

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

962

963 # fallback venv detection:

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

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

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

967 paths = self.get_path_links(p)

968

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

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

971 drive_name = p_venv.parts[2]

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

973

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

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

976 return

977

978 if sys.platform == "win32":

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

980 else:

981 virtual_env_path = Path(

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

983 )

984 p_ver = sys.version_info[:2]

985

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

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

988 if re_m:

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

990 if predicted_path.exists():

991 p_ver = re_m.groups()

992

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

994 if self.warn_venv:

995 warn(

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

997 "please install IPython inside the virtualenv."

998 )

999 import site

1000 sys.path.insert(0, virtual_env)

1001 site.addsitedir(virtual_env)

1002

1003 #-------------------------------------------------------------------------

1004 # Things related to injections into the sys module

1005 #-------------------------------------------------------------------------

1006

1007 def save_sys_module_state(self):

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

1009

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

1011 """

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

1013 'stdout': sys.stdout,

1014 'stderr': sys.stderr,

1015 'excepthook': sys.excepthook}

1016 self._orig_sys_modules_main_name = self.user_module.__name__

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

1018

1019 def restore_sys_module_state(self):

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

1021 try:

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

1023 setattr(sys, k, v)

1024 except AttributeError:

1025 pass

1026 # Reset what what done in self.init_sys_modules

1027 if self._orig_sys_modules_main_mod is not None:

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

1029

1030 #-------------------------------------------------------------------------

1031 # Things related to the banner

1032 #-------------------------------------------------------------------------

1033

1034 @property

1035 def banner(self):

1036 banner = self.banner1

1037 # Only use SOURCE_DATE_EPOCH if the user hasn't set a custom banner

1038 if (

1039 banner is default_banner

1040 and (when := os.environ.get("SOURCE_DATE_EPOCH", None)) is not None

1041 ):

1042 from datetime import datetime

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

1044 banner = textwrap.dedent(

1045 f"""

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

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

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

1049 Tip: unset SOURCE_DATE_EPOCH to restore dynamic banner.

1050 """

1051 ).lstrip()

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

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

1054 if self.banner2:

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

1056 elif self.enable_tip:

1057 banner += f"Tip: {pick_tip()}\n"

1058 return banner

1059

1060 def show_banner(self, banner=None):

1061 if banner is None:

1062 banner = self.banner

1063 print(banner, end="")

1064

1065 #-------------------------------------------------------------------------

1066 # Things related to hooks

1067 #-------------------------------------------------------------------------

1068

1069 def init_hooks(self):

1070 # hooks holds pointers used for user-side customizations

1071 self.hooks = Struct()

1072

1073 self.strdispatchers = {}

1074

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

1076 hooks = IPython.core.hooks

1077 for hook_name in hooks.__all__:

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

1079 # 0-100 priority

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

1081

1082 if self.display_page:

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

1084

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

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

1087

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

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

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

1091

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

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

1094 # of args it's supposed to.

1095

1096 f = types.MethodType(hook,self)

1097

1098 # check if the hook is for strdispatcher first

1099 if str_key is not None:

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

1101 sdp.add_s(str_key, f, priority )

1102 self.strdispatchers[name] = sdp

1103 return

1104 if re_key is not None:

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

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

1107 self.strdispatchers[name] = sdp

1108 return

1109

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

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

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

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

1114

1115 if not dp:

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

1117

1118 try:

1119 dp.add(f,priority)

1120 except AttributeError:

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

1122 dp = f

1123

1124 setattr(self.hooks,name, dp)

1125

1126 #-------------------------------------------------------------------------

1127 # Things related to events

1128 #-------------------------------------------------------------------------

1129

1130 def init_events(self):

1131 self.events = EventManager(self, available_events)

1132

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

1134

1135 def _clear_warning_registry(self):

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

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

1138 # warnings (see gh-6611 for details)

1139 if "__warningregistry__" in self.user_global_ns:

1140 del self.user_global_ns["__warningregistry__"]

1141

1142 #-------------------------------------------------------------------------

1143 # Things related to the "main" module

1144 #-------------------------------------------------------------------------

1145

1146 def new_main_mod(self, filename, modname):

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

1148

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

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

1151 its namespace cleared.

1152

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

1154 the basename of the file without the extension.

1155

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

1157 __main__ module around so that Python doesn't

1158 clear it, rendering references to module globals useless.

1159

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

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

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

1163 thus preventing memory leaks from old references while allowing the

1164 objects from the last execution to be accessible.

1165 """

1166 filename = os.path.abspath(filename)

1167 try:

1168 main_mod = self._main_mod_cache[filename]

1169 except KeyError:

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

1171 modname,

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

1173 else:

1174 main_mod.__dict__.clear()

1175 main_mod.__name__ = modname

1176

1177 main_mod.__file__ = filename

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

1179 # implement a __nonzero__ method

1180 main_mod.__nonzero__ = lambda : True

1181

1182 return main_mod

1183

1184 def clear_main_mod_cache(self):

1185 """Clear the cache of main modules.

1186

1187 Mainly for use by utilities like %reset.

1188

1189 Examples

1190 --------

1191 In [15]: import IPython

1192

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

1194

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

1196 Out[17]: True

1197

1198 In [18]: _ip.clear_main_mod_cache()

1199

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

1201 Out[19]: True

1202 """

1203 self._main_mod_cache.clear()

1204

1205 #-------------------------------------------------------------------------

1206 # Things related to debugging

1207 #-------------------------------------------------------------------------

1208

1209 def init_pdb(self):

1210 # Set calling of pdb on exceptions

1211 # self.call_pdb is a property

1212 self.call_pdb = self.pdb

1213

1214 def _get_call_pdb(self):

1215 return self._call_pdb

1216

1217 def _set_call_pdb(self,val):

1218

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

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

1221

1222 # store value in instance

1223 self._call_pdb = val

1224

1225 # notify the actual exception handlers

1226 self.InteractiveTB.call_pdb = val

1227

1228 call_pdb = property(_get_call_pdb,_set_call_pdb,None,

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

1230

1231 def debugger(self,force=False):

1232 """Call the pdb debugger.

1233

1234 Keywords:

1235

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

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

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

1239 is false.

1240 """

1241

1242 if not (force or self.call_pdb):

1243 return

1244

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

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

1247 return

1248

1249 self.InteractiveTB.debugger(force=True)

1250

1251 #-------------------------------------------------------------------------

1252 # Things related to IPython's various namespaces

1253 #-------------------------------------------------------------------------

1254 default_user_namespaces = True

1255

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

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

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

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

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

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

1262 # distinction between locals and globals is meaningful. For

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

1264

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

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

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

1268 # Schmolck reported this problem first.

1269

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

1271 # Re: inconsistent value from __builtins__

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

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

1274 # Gruppen: comp.lang.python

1275

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

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

1278 # > <type 'dict'>

1279 # > >>> print type(__builtins__)

1280 # > <type 'module'>

1281 # > Is this difference in return value intentional?

1282

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

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

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

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

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

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

1289

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

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

1292 # generate properly initialized namespaces.

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

1294 self.default_user_namespaces = False

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

1296

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

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

1299 self.user_ns_hidden = {}

1300

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

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

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

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

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

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

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

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

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

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

1311 # these modules from deletion by keeping a cache.

1312 #

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

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

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

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

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

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

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

1320 #

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

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

1323

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

1325 self._main_mod_cache = {}

1326

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

1328 # introspection facilities can search easily.

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

1330 'user_local':self.user_ns,

1331 'builtin':builtin_mod.__dict__

1332 }

1333

1334 @property

1335 def user_global_ns(self):

1336 return self.user_module.__dict__

1337

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

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

1340

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

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

1343

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

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

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

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

1348 provides the global namespace.

1349

1350 Parameters

1351 ----------

1352 user_module : module, optional

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

1354 a clean module will be created.

1355 user_ns : dict, optional

1356 A namespace in which to run interactive commands.

1357

1358 Returns

1359 -------

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

1361 """

1362 if user_module is None and user_ns is not None:

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

1364 user_module = make_main_module_type(user_ns)()

1365

1366 if user_module is None:

1367 user_module = types.ModuleType("__main__",

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

1369

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

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

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

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

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

1375

1376 if user_ns is None:

1377 user_ns = user_module.__dict__

1378 return user_module, user_ns

1379

1380 def init_sys_modules(self):

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

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

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

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

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

1386 # everything into __main__.

1387

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

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

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

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

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

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

1394 # embedded in).

1395

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

1397 main_name = self.user_module.__name__

1398 sys.modules[main_name] = self.user_module

1399

1400 def init_user_ns(self):

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

1402

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

1404 act as user namespaces.

1405

1406 Notes

1407 -----

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

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

1410 them.

1411 """

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

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

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

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

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

1417

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

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

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

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

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

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

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

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

1426

1427 # For more details:

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

1429 ns = {}

1430

1431 # make global variables for user access to the histories

1432 if self.history_manager is not None:

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

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

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

1436

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

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

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

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

1441

1442 # Store myself as the public api!!!

1443 ns['get_ipython'] = self.get_ipython

1444

1445 ns['exit'] = self.exiter

1446 ns['quit'] = self.exiter

1447 ns["open"] = _modified_open

1448

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

1450 # by %who

1451 self.user_ns_hidden.update(ns)

1452

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

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

1455 # stuff, not our variables.

1456

1457 # Finally, update the real user's namespace

1458 self.user_ns.update(ns)

1459

1460 @property

1461 def all_ns_refs(self):

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

1463 IPython might store a user-created object.

1464

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

1466 objects from the output."""

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

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

1469

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

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

1472 user objects.

1473

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

1475 """

1476 # Clear histories

1477 if self.history_manager is not None:

1478 self.history_manager.reset(new_session)

1479 # Reset counter used to index all histories

1480 if new_session:

1481 self.execution_count = 1

1482

1483 # Reset last execution result

1484 self.last_execution_succeeded = True

1485 self.last_execution_result = None

1486

1487 # Flush cached output items

1488 if self.displayhook.do_full_cache:

1489 self.displayhook.flush()

1490

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

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

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

1494 if self.user_ns is not self.user_global_ns:

1495 self.user_ns.clear()

1496 ns = self.user_global_ns

1497 drop_keys = set(ns.keys())

1498 drop_keys.discard('__builtin__')

1499 drop_keys.discard('__builtins__')

1500 drop_keys.discard('__name__')

1501 for k in drop_keys:

1502 del ns[k]

1503

1504 self.user_ns_hidden.clear()

1505

1506 # Restore the user namespaces to minimal usability

1507 self.init_user_ns()

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

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

1510 elif aggressive:

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

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

1513 for k in current_keys - self._sys_modules_keys:

1514 if k.startswith("multiprocessing"):

1515 continue

1516 del sys.modules[k]

1517

1518 # Restore the default and user aliases

1519 self.alias_manager.clear_aliases()

1520 self.alias_manager.init_aliases()

1521

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

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

1524 # GUI or web frontend

1525 if os.name == 'posix':

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

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

1528 self.alias_manager.soft_define_alias(cmd, cmd)

1529

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

1531 # execution protection

1532 self.clear_main_mod_cache()

1533

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

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

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

1537

1538 Parameters

1539 ----------

1540 varname : str

1541 The name of the variable to delete.

1542 by_name : bool

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

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

1545 namespace, and delete references to it.

1546 """

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

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

1549

1550 ns_refs = self.all_ns_refs

1551

1552 if by_name: # Delete by name

1553 for ns in ns_refs:

1554 try:

1555 del ns[varname]

1556 except KeyError:

1557 pass

1558 else: # Delete by object

1559 try:

1560 obj = self.user_ns[varname]

1561 except KeyError as e:

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

1563 # Also check in output history

1564 assert self.history_manager is not None

1565 ns_refs.append(self.history_manager.output_hist)

1566 for ns in ns_refs:

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

1568 for name in to_delete:

1569 del ns[name]

1570

1571 # Ensure it is removed from the last execution result

1572 if self.last_execution_result.result is obj:

1573 self.last_execution_result = None

1574

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

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

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

1578 setattr(self.displayhook, name, None)

1579

1580 def reset_selective(self, regex=None):

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

1582 specified regular expression.

1583

1584 Parameters

1585 ----------

1586 regex : string or compiled pattern, optional

1587 A regular expression pattern that will be used in searching

1588 variable names in the users namespaces.

1589 """

1590 if regex is not None:

1591 try:

1592 m = re.compile(regex)

1593 except TypeError as e:

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

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

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

1597 for ns in self.all_ns_refs:

1598 for var in ns:

1599 if m.search(var):

1600 del ns[var]

1601

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

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

1604

1605 Parameters

1606 ----------

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

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

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

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

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

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

1613 callers frame.

1614 interactive : bool

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

1616 magic.

1617 """

1618 vdict = None

1619

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

1621 if isinstance(variables, dict):

1622 vdict = variables

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

1624 if isinstance(variables, str):

1625 vlist = variables.split()

1626 else:

1627 vlist = list(variables)

1628 vdict = {}

1629 cf = sys._getframe(1)

1630 for name in vlist:

1631 try:

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

1633 except Exception:

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

1635 (name,cf.f_code.co_name))

1636 else:

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

1638

1639 # Propagate variables to user namespace

1640 self.user_ns.update(vdict)

1641

1642 # And configure interactive visibility

1643 user_ns_hidden = self.user_ns_hidden

1644 if interactive:

1645 for name in vdict:

1646 user_ns_hidden.pop(name, None)

1647 else:

1648 user_ns_hidden.update(vdict)

1649

1650 def drop_by_id(self, variables):

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

1652 same as the values in the dictionary.

1653

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

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

1656 user has overwritten.

1657

1658 Parameters

1659 ----------

1660 variables : dict

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

1662 """

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

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

1665 del self.user_ns[name]

1666 self.user_ns_hidden.pop(name, None)

1667

1668 #-------------------------------------------------------------------------

1669 # Things related to object introspection

1670 #-------------------------------------------------------------------------

1671 @staticmethod

1672 def _find_parts(oname: str) -> tuple[bool, list[str]]:

1673 """

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

1675

1676 Basically split on docs when using attribute access,

1677 and extract the value when using square bracket.

1678

1679

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

1681

1682

1683 Returns

1684 -------

1685 parts_ok: bool

1686 whether we were properly able to parse parts.

1687 parts: list of str

1688 extracted parts

1689

1690

1691

1692 """

1693 raw_parts = oname.split(".")

1694 parts = []

1695 parts_ok = True

1696 for p in raw_parts:

1697 if p.endswith("]"):

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

1699 if not var.isidentifier():

1700 parts_ok = False

1701 break

1702 parts.append(var)

1703 for ind in indices:

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

1705 parts_ok = False

1706 break

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

1708 continue

1709

1710 if not p.isidentifier():

1711 parts_ok = False

1712 parts.append(p)

1713

1714 return parts_ok, parts

1715

1716 def _ofind(

1717 self, oname: str, namespaces: Sequence[tuple[str, AnyType]] | None = None

1718 ) -> OInfo:

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

1720

1721

1722 Returns

1723 -------

1724 OInfo with fields:

1725 - ismagic

1726 - isalias

1727 - found

1728 - obj

1729 - namespac

1730 - parent

1731

1732 Has special code to detect magic functions.

1733 """

1734 oname = oname.strip()

1735 parts_ok, parts = self._find_parts(oname)

1736

1737 if (

1738 not oname.startswith(ESC_MAGIC)

1739 and not oname.startswith(ESC_MAGIC2)

1740 and not parts_ok

1741 ):

1742 return OInfo(

1743 ismagic=False,

1744 isalias=False,

1745 found=False,

1746 obj=None,

1747 namespace=None,

1748 parent=None,

1749 )

1750

1751 if namespaces is None:

1752 # Namespaces to search in:

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

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

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

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

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

1758 ]

1759

1760 ismagic = False

1761 isalias = False

1762 found = False

1763 ospace = None

1764 parent = None

1765 obj = None

1766

1767

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

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

1770 # declare success if we can find them all.

1771 oname_parts = parts

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

1773 for nsname,ns in namespaces:

1774 try:

1775 obj = ns[oname_head]

1776 except KeyError:

1777 continue

1778 else:

1779 for idx, part in enumerate(oname_rest):

1780 try:

1781 parent = obj

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

1783 # descriptor invocation as it may raise or have side

1784 # effects.

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

1786 obj = self._getattr_property(obj, part)

1787 else:

1788 if is_integer_string(part):

1789 obj = obj[int(part)]

1790 else:

1791 obj = getattr(obj, part)

1792 except:

1793 # Blanket except b/c some badly implemented objects

1794 # allow __getattr__ to raise exceptions other than

1795 # AttributeError, which then crashes IPython.

1796 break

1797 else:

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

1799 found = True

1800 ospace = nsname

1801 break # namespace loop

1802

1803 # Try to see if it's magic

1804 if not found:

1805 obj = None

1806 if oname.startswith(ESC_MAGIC2):

1807 oname = oname.lstrip(ESC_MAGIC2)

1808 obj = self.find_cell_magic(oname)

1809 elif oname.startswith(ESC_MAGIC):

1810 oname = oname.lstrip(ESC_MAGIC)

1811 obj = self.find_line_magic(oname)

1812 else:

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

1814 obj = self.find_line_magic(oname)

1815 if obj is None:

1816 obj = self.find_cell_magic(oname)

1817 if obj is not None:

1818 found = True

1819 ospace = 'IPython internal'

1820 ismagic = True

1821 isalias = isinstance(obj, Alias)

1822

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

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

1825 obj = eval(oname_head)

1826 found = True

1827 ospace = 'Interactive'

1828

1829 return OInfo(

1830 obj=obj,

1831 found=found,

1832 parent=parent,

1833 ismagic=ismagic,

1834 isalias=isalias,

1835 namespace=ospace,

1836 )

1837

1838 @staticmethod

1839 def _getattr_property(obj, attrname):

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

1841

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

1843 side effects or raises an error.

1844

1845 """

1846 if not isinstance(obj, type):

1847 try:

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

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

1850 #

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

1852 #

1853 # The universal alternative is to traverse the mro manually

1854 # searching for attrname in class dicts.

1855 if is_integer_string(attrname):

1856 return obj[int(attrname)]

1857 else:

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

1859 except AttributeError:

1860 pass

1861 else:

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

1863 # __get__ & __set__ magic methods) take precedence over

1864 # instance-level attributes:

1865 #

1866 # class A(object):

1867 # @property

1868 # def foobar(self): return 123

1869 # a = A()

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

1871 # a.foobar # == 123

1872 #

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

1874 if isinstance(attr, property):

1875 return attr

1876

1877 # Nothing helped, fall back.

1878 return getattr(obj, attrname)

1879

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

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

1882 return self._ofind(oname, namespaces)

1883

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

1885 """Generic interface to the inspector system.

1886

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

1888 """

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

1890 if self.sphinxify_docstring:

1891 if sphinxify is None:

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

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

1894 else:

1895 docformat = None

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

1897 pmethod = getattr(self.inspector, meth)

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

1899 # bundle.

1900 formatter = format_screen if info.ismagic else docformat

1901 if meth == 'pdoc':

1902 pmethod(info.obj, oname, formatter)

1903 elif meth == 'pinfo':

1904 pmethod(

1905 info.obj,

1906 oname,

1907 formatter,

1908 info,

1909 enable_html_pager=self.enable_html_pager,

1910 **kw,

1911 )

1912 else:

1913 pmethod(info.obj, oname)

1914 else:

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

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

1917

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

1919 """Get object info about oname"""

1920 with self.builtin_trap:

1921 info = self._object_find(oname)

1922 if info.found:

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

1924 detail_level=detail_level

1925 )

1926 else:

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

1928

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

1930 """Get object info as formatted text"""

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

1932

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

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

1935

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

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

1938 """

1939 with self.builtin_trap:

1940 info = self._object_find(oname)

1941 if info.found:

1942 if self.sphinxify_docstring:

1943 if sphinxify is None:

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

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

1946 else:

1947 docformat = None

1948 return self.inspector._get_info(

1949 info.obj,

1950 oname,

1951 info=info,

1952 detail_level=detail_level,

1953 formatter=docformat,

1954 omit_sections=omit_sections,

1955 )

1956 else:

1957 raise KeyError(oname)

1958

1959 #-------------------------------------------------------------------------

1960 # Things related to history management

1961 #-------------------------------------------------------------------------

1962

1963 def init_history(self):

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

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

1966 self.configurables.append(self.history_manager)

1967

1968 #-------------------------------------------------------------------------

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

1970 #-------------------------------------------------------------------------

1971

1972 debugger_cls = InterruptiblePdb

1973

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

1975 # Syntax error handler.

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

1977

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

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

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

1981 self.InteractiveTB = ultratb.AutoFormattedTB(

1982 mode=self.xmode,

1983 theme_name=self.colors,

1984 tb_offset=1,

1985 debugger_cls=self.debugger_cls,

1986 )

1987

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

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

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

1991 self.sys_excepthook = sys.excepthook

1992

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

1994 self.set_custom_exc(*custom_exceptions)

1995

1996 # Set the exception mode

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

1998

1999 def set_custom_exc(self, exc_tuple, handler):

2000 """set_custom_exc(exc_tuple, handler)

2001

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

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

2004 run_code() method).

2005

2006 Parameters

2007 ----------

2008 exc_tuple : tuple of exception classes

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

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

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

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

2013

2014 exc_tuple == (MyCustomException,)

2015

2016 handler : callable

2017 handler must have the following signature::

2018

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

2020 ...

2021 return structured_traceback

2022

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

2024 or None.

2025

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

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

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

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

2030

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

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

2033 disabled.

2034

2035 Notes

2036 -----

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

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

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

2040 """

2041

2042 if not isinstance(exc_tuple, tuple):

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

2044

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

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

2047 print('Exception type :', etype)

2048 print('Exception value:', value)

2049 print('Traceback :', tb)

2050

2051 def validate_stb(stb):

2052 """validate structured traceback return type

2053

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

2055 single strings or None, which are harmless.

2056

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

2058 and will raise a TypeError if stb is inappropriate.

2059 """

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

2061 if stb is None:

2062 return []

2063 elif isinstance(stb, str):

2064 return [stb]

2065 elif not isinstance(stb, list):

2066 raise TypeError(msg)

2067 # it's a list

2068 for line in stb:

2069 # check every element

2070 if not isinstance(line, str):

2071 raise TypeError(msg)

2072 return stb

2073

2074 if handler is None:

2075 wrapped = dummy_handler

2076 else:

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

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

2079

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

2081 handlers to crash IPython.

2082 """

2083 try:

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

2085 return validate_stb(stb)

2086 except:

2087 # clear custom handler immediately

2088 self.set_custom_exc((), None)

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

2090 # show the exception in handler first

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

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

2093 print("The original exception:")

2094 stb = self.InteractiveTB.structured_traceback(

2095 etype, value, tb, tb_offset=tb_offset

2096 )

2097 return stb

2098

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

2100 self.custom_exceptions = exc_tuple

2101

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

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

2104

2105 GUI frameworks like wxPython trap exceptions and call

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

2107 enables them to keep running after exceptions that would

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

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

2110 except: statement.

2111

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

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

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

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

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

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

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

2119 crashes.

2120

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

2122 to be true IPython errors.

2123 """

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

2125

2126 def _get_exc_info(self, exc_tuple=None):

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

2128

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

2130 from whichever source.

2131

2132 raises ValueError if none of these contain any information

2133 """

2134 if exc_tuple is None:

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

2136 else:

2137 etype, value, tb = exc_tuple

2138

2139 if etype is None:

2140 if hasattr(sys, 'last_type'):

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

2142 sys.last_traceback

2143

2144 if etype is None:

2145 raise ValueError("No exception to find")

2146

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

2148 # WARNING: these variables are somewhat deprecated and not

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

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

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

2152 sys.last_type = etype

2153 sys.last_value = value

2154 sys.last_traceback = tb

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

2156 sys.last_exc = value

2157

2158 return etype, value, tb

2159

2160 def show_usage_error(self, exc):

2161 """Show a short message for UsageErrors

2162

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

2164 """

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

2166

2167 def get_exception_only(self, exc_tuple=None):

2168 """

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

2170 just occurred, without any traceback.

2171 """

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

2173 msg = traceback.format_exception_only(etype, value)

2174 return ''.join(msg)

2175

2176 def showtraceback(

2177 self,

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

2179 filename: str | None = None,

2180 tb_offset: int | None = None,

2181 exception_only: bool = False,

2182 running_compiled_code: bool = False,

2183 ) -> None:

2184 """Display the exception that just occurred.

2185

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

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

2188 rather than directly invoking the InteractiveTB object.

2189

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

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

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

2193 simply call this method."""

2194

2195 try:

2196 try:

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

2198 except ValueError:

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

2200 return

2201

2202 if issubclass(etype, SyntaxError):

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

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

2205 self.showsyntaxerror(filename, running_compiled_code)

2206 elif etype is UsageError:

2207 self.show_usage_error(value)

2208 else:

2209 if exception_only:

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

2211 'the full traceback.\n']

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

2213 value))

2214 else:

2215

2216 def contains_exceptiongroup(val):

2217 if val is None:

2218 return False

2219 return isinstance(

2220 val, BaseExceptionGroup

2221 ) or contains_exceptiongroup(val.__context__)

2222

2223 if contains_exceptiongroup(value):

2224 # fall back to native exception formatting until ultratb

2225 # supports exception groups

2226 traceback.print_exc()

2227 else:

2228 try:

2229 # Exception classes can customise their traceback - we

2230 # use this in IPython.parallel for exceptions occurring

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

2232 if hasattr(value, "_render_traceback_"):

2233 stb = value._render_traceback_()

2234 else:

2235 stb = self.InteractiveTB.structured_traceback(

2236 etype, value, tb, tb_offset=tb_offset

2237 )

2238

2239 except Exception:

2240 print(

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

2242 )

2243 traceback.print_exc()

2244 return None

2245

2246 self._showtraceback(etype, value, stb)

2247 if self.call_pdb:

2248 # drop into debugger

2249 self.debugger(force=True)

2250 return

2251

2252 # Actually show the traceback

2253 self._showtraceback(etype, value, stb)

2254

2255 except KeyboardInterrupt:

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

2257

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

2259 """Actually show a traceback.

2260

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

2262 place, like a side channel.

2263 """

2264 val = self.InteractiveTB.stb2text(stb)

2265 self.showing_traceback = True

2266 try:

2267 print(val)

2268 except UnicodeEncodeError:

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

2270 self.showing_traceback = False

2271

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

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

2274

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

2276

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

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

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

2280

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

2282 longer stack trace will be displayed.

2283 """

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

2285

2286 if filename and issubclass(etype, SyntaxError):

2287 try:

2288 value.filename = filename

2289 except AttributeError:

2290 # Not the format we expect; leave it alone

2291 pass

2292

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

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

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

2296 self._showtraceback(etype, value, stb)

2297

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

2299 # the %paste magic.

2300 def showindentationerror(self):

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

2302 at the prompt.

2303

2304 This is overridden in TerminalInteractiveShell to show a message about

2305 the %paste magic."""

2306 self.showsyntaxerror()

2307

2308 @skip_doctest

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

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

2311

2312 Example::

2313

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

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

2316 """

2317 self.rl_next_input = s

2318

2319 #-------------------------------------------------------------------------

2320 # Things related to text completion

2321 #-------------------------------------------------------------------------

2322

2323 def init_completer(self):

2324 """Initialize the completion machinery.

2325

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

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

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

2329 (typically over the network by remote frontends).

2330 """

2331 from IPython.core.completer import IPCompleter

2332 from IPython.core.completerlib import (

2333 cd_completer,

2334 magic_run_completer,

2335 module_completer,

2336 reset_completer,

2337 )

2338

2339 self.Completer = IPCompleter(shell=self,

2340 namespace=self.user_ns,

2341 global_namespace=self.user_global_ns,

2342 parent=self,

2343 )

2344 self.configurables.append(self.Completer)

2345

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

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

2348 self.strdispatchers['complete_command'] = sdisp

2349 self.Completer.custom_completers = sdisp

2350

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

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

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

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

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

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

2357

2358 @skip_doctest

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

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

2361

2362 Parameters

2363 ----------

2364 text : string

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

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

2367 completer itself will split the line like readline does.

2368 line : string, optional

2369 The complete line that text is part of.

2370 cursor_pos : int, optional

2371 The position of the cursor on the input line.

2372

2373 Returns

2374 -------

2375 text : string

2376 The actual text that was completed.

2377 matches : list

2378 A sorted list with all possible completions.

2379

2380 Notes

2381 -----

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

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

2384

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

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

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

2388 environments (such as GUIs) for text completion.

2389

2390 Examples

2391 --------

2392 In [1]: x = 'hello'

2393

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

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

2396 """

2397

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

2399 with self.builtin_trap:

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

2401

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

2403 """Adds a new custom completer function.

2404

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

2406 list where you want the completer to be inserted.

2407

2408 `completer` should have the following signature::

2409

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

2411 raise NotImplementedError

2412

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

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

2415 """

2416

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

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

2419

2420 def set_completer_frame(self, frame=None):

2421 """Set the frame of the completer."""

2422 if frame:

2423 self.Completer.namespace = frame.f_locals

2424 self.Completer.global_namespace = frame.f_globals

2425 else:

2426 self.Completer.namespace = self.user_ns

2427 self.Completer.global_namespace = self.user_global_ns

2428

2429 #-------------------------------------------------------------------------

2430 # Things related to magics

2431 #-------------------------------------------------------------------------

2432

2433 def init_magics(self):

2434 from IPython.core import magics as m

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

2436 parent=self,

2437 user_magics=m.UserMagics(self))

2438 self.configurables.append(self.magics_manager)

2439

2440 # Expose as public API from the magics manager

2441 self.register_magics = self.magics_manager.register

2442

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

2444 m.ConfigMagics, m.DisplayMagics, m.ExecutionMagics,

2445 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,

2446 m.NamespaceMagics, m.OSMagics, m.PackagingMagics,

2447 m.PylabMagics, m.ScriptMagics,

2448 )

2449 self.register_magics(m.AsyncMagics)

2450

2451 # Register Magic Aliases

2452 mman = self.magics_manager

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

2454 # or in MagicsManager, not here

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

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

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

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

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

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

2461

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

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

2464 # even need a centralize colors management object.

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

2466

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

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

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

2470 self.magics_manager.register_function(

2471 func, magic_kind=magic_kind, magic_name=magic_name

2472 )

2473

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

2475 """

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

2477

2478 Parameters

2479 ----------

2480

2481 type_: "line"|"cell"

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

2483 magic_name: str

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

2485

2486

2487 Note that this may have any side effects

2488 """

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

2490 fn = finder(magic_name)

2491 if fn is not None:

2492 return fn

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

2494 if lazy is None:

2495 return None

2496

2497 self.run_line_magic("load_ext", lazy)

2498 res = finder(magic_name)

2499 return res

2500

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

2502 """Execute the given line magic.

2503

2504 Parameters

2505 ----------

2506 magic_name : str

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

2508 line : str

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

2510 _stack_depth : int

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

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

2513 """

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

2515 if fn is None:

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

2517 if lazy:

2518 self.run_line_magic("load_ext", lazy)

2519 fn = self.find_line_magic(magic_name)

2520 if fn is None:

2521 cm = self.find_cell_magic(magic_name)

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

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

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

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

2526 else:

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

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

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

2530

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

2532 stack_depth = _stack_depth

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

2534 # magic has opted out of var_expand

2535 magic_arg_s = line

2536 else:

2537 magic_arg_s = self.var_expand(line, stack_depth)

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

2539 args = [magic_arg_s]

2540 kwargs = {}

2541 # Grab local namespace if we need it:

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

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

2544 with self.builtin_trap:

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

2546

2547 # The code below prevents the output from being displayed

2548 # when using magics with decorator @output_can_be_silenced

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

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

2551 if DisplayHook.semicolon_at_end_of_expression(magic_arg_s):

2552 return None

2553

2554 return result

2555

2556 def get_local_scope(self, stack_depth):

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

2558

2559 Parameters

2560 ----------

2561 stack_depth : int

2562 Depth relative to calling frame

2563 """

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

2565

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

2567 """Execute the given cell magic.

2568

2569 Parameters

2570 ----------

2571 magic_name : str

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

2573 line : str

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

2575 cell : str

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

2577 """

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

2579 if fn is None:

2580 lm = self.find_line_magic(magic_name)

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

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

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

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

2585 elif cell == '':

2586 message = f'%%{magic_name} is a cell magic, but the cell body is empty.'

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

2588 message += f' Did you mean the line magic %{magic_name} (single %)?'

2589 raise UsageError(message)

2590 else:

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

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

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

2594 stack_depth = 2

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

2596 # magic has opted out of var_expand

2597 magic_arg_s = line

2598 else:

2599 magic_arg_s = self.var_expand(line, stack_depth)

2600 kwargs = {}

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

2602 kwargs['local_ns'] = self.user_ns

2603

2604 with self.builtin_trap:

2605 args = (magic_arg_s, cell)

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

2607

2608 # The code below prevents the output from being displayed

2609 # when using magics with decorator @output_can_be_silenced

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

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

2612 if DisplayHook.semicolon_at_end_of_expression(cell):

2613 return None

2614

2615 return result

2616

2617 def find_line_magic(self, magic_name):

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

2619

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

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

2622

2623 def find_cell_magic(self, magic_name):

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

2625

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

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

2628

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

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

2631

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

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

2634

2635 #-------------------------------------------------------------------------

2636 # Things related to macros

2637 #-------------------------------------------------------------------------

2638

2639 def define_macro(self, name, themacro):

2640 """Define a new macro

2641

2642 Parameters

2643 ----------

2644 name : str

2645 The name of the macro.

2646 themacro : str or Macro

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

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

2649 """

2650

2651 from IPython.core import macro

2652

2653 if isinstance(themacro, str):

2654 themacro = macro.Macro(themacro)

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

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

2657 self.user_ns[name] = themacro

2658

2659 #-------------------------------------------------------------------------

2660 # Things related to the running of system commands

2661 #-------------------------------------------------------------------------

2662

2663 def system_piped(self, cmd):

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

2665

2666 Parameters

2667 ----------

2668 cmd : str

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

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

2671 other than simple text.

2672 """

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

2674 # this is *far* from a rigorous test

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

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

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

2678 # if they really want a background process.

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

2680

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

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

2683 # Instead, we store the exit_code in user_ns.

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

2685 self.user_ns['_exit_code'] = exit_code

2686

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

2688 if self.system_raise_on_error and exit_code != 0:

2689 raise CalledProcessError(exit_code, cmd)

2690

2691 def system_raw(self, cmd):

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

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

2694

2695 Parameters

2696 ----------

2697 cmd : str

2698 Command to execute.

2699 """

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

2701 # warn if there is an IPython magic alternative.

2702 if cmd == "":

2703 main_cmd = ""

2704 else:

2705 main_cmd = cmd.split()[0]

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

2707

2708 if main_cmd in has_magic_alternatives:

2709 warnings.warn(

2710 (

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

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

2713 ).format(main_cmd)

2714 )

2715

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

2717 if sys.platform == 'win32':

2718 from IPython.utils._process_win32 import AvoidUNCPath

2719 with AvoidUNCPath() as path:

2720 if path is not None:

2721 cmd = '"pushd {} &&"{}'.format(path, cmd)

2722 try:

2723 ec = os.system(cmd)

2724 except KeyboardInterrupt:

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

2726 ec = -2

2727 else:

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

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

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

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

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

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

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

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

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

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

2738 try:

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

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

2741 except KeyboardInterrupt:

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

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

2744 ec = 130

2745 if ec > 128:

2746 ec = -(ec - 128)

2747

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

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

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

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

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

2753 self.user_ns['_exit_code'] = ec

2754

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

2756 if self.system_raise_on_error and ec != 0:

2757 raise CalledProcessError(ec, cmd)

2758

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

2760 system = system_piped

2761

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

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

2764

2765 Parameters

2766 ----------

2767 cmd : str

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

2769 not supported.

2770 split : bool, optional

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

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

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

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

2775 details.

2776 depth : int, optional

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

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

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

2780 """

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

2782 # this is *far* from a rigorous test

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

2784

2785 # Get output and exit code

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

2787 if self.system_raise_on_error:

2788 # Use get_output_error_code to get the exit code

2789 out_str, err_str, exit_code = get_output_error_code(expanded_cmd)

2790 # Combine stdout and stderr as getoutput does

2791 out_combined = out_str if not err_str else out_str + err_str

2792 self.user_ns['_exit_code'] = exit_code

2793

2794 # Raise an exception if the command failed

2795 if exit_code != 0:

2796 raise CalledProcessError(exit_code, cmd)

2797 else:

2798 # Use the original getoutput for backward compatibility

2799 out_combined = getoutput(expanded_cmd)

2800

2801 if split:

2802 out = SList(out_combined.splitlines())

2803 else:

2804 out = LSString(out_combined)

2805 return out

2806

2807 #-------------------------------------------------------------------------

2808 # Things related to aliases

2809 #-------------------------------------------------------------------------

2810

2811 def init_alias(self):

2812 self.alias_manager = AliasManager(shell=self, parent=self)

2813 self.configurables.append(self.alias_manager)

2814

2815 #-------------------------------------------------------------------------

2816 # Things related to extensions

2817 #-------------------------------------------------------------------------

2818

2819 def init_extension_manager(self):

2820 self.extension_manager = ExtensionManager(shell=self, parent=self)

2821 self.configurables.append(self.extension_manager)

2822

2823 #-------------------------------------------------------------------------

2824 # Things related to payloads

2825 #-------------------------------------------------------------------------

2826

2827 def init_payload(self):

2828 self.payload_manager = PayloadManager(parent=self)

2829 self.configurables.append(self.payload_manager)

2830

2831 #-------------------------------------------------------------------------

2832 # Things related to the prefilter

2833 #-------------------------------------------------------------------------

2834

2835 def init_prefilter(self):

2836 self.prefilter_manager = PrefilterManager(shell=self, parent=self)

2837 self.configurables.append(self.prefilter_manager)

2838 # Ultimately this will be refactored in the new interpreter code, but

2839 # for now, we should expose the main prefilter method (there's legacy

2840 # code out there that may rely on this).

2841 self.prefilter = self.prefilter_manager.prefilter_lines

2842

2843 def auto_rewrite_input(self, cmd):

2844 """Print to the screen the rewritten form of the user's command.

2845

2846 This shows visual feedback by rewriting input lines that cause

2847 automatic calling to kick in, like::

2849 /f x

2851 into::

2853 ------> f(x)

2855 after the user's input prompt. This helps the user understand that the

2856 input line was transformed automatically by IPython.

2857 """

2858 if not self.show_rewritten_input:

2859 return

2860

2861 # This is overridden in TerminalInteractiveShell to use fancy prompts

2862 print("------> " + cmd)

2863

2864 #-------------------------------------------------------------------------

2865 # Things related to extracting values/expressions from kernel and user_ns

2866 #-------------------------------------------------------------------------

2867

2868 def _user_obj_error(self):

2869 """return simple exception dict

2870

2871 for use in user_expressions

2872 """

2873

2874 etype, evalue, tb = self._get_exc_info()

2875 stb = self.InteractiveTB.get_exception_only(etype, evalue)

2876

2877 try:

2878 evalue_str = str(evalue)

2879 except UnicodeError:

2880 try:

2881 evalue_str = repr(evalue)

2882 except UnicodeError:

2883 evalue_str = "Unrecoverably corrupt evalue"

2884

2885 exc_info = {

2886 "status": "error",

2887 "traceback": stb,

2888 "ename": etype.__name__,

2889 "evalue": evalue_str,

2890 }

2891

2892 return exc_info

2893

2894 def _format_user_obj(self, obj):

2895 """format a user object to display dict

2896

2897 for use in user_expressions

2898 """

2899

2900 data, md = self.display_formatter.format(obj)

2901 value = {

2902 'status' : 'ok',

2903 'data' : data,

2904 'metadata' : md,

2905 }

2906 return value

2907

2908 def user_expressions(self, expressions):

2909 """Evaluate a dict of expressions in the user's namespace.

2910

2911 Parameters

2912 ----------

2913 expressions : dict

2914 A dict with string keys and string values. The expression values

2915 should be valid Python expressions, each of which will be evaluated

2916 in the user namespace.

2917

2918 Returns

2919 -------

2920 A dict, keyed like the input expressions dict, with the rich mime-typed

2921 display_data of each value.

2922 """

2923 out = {}

2924 user_ns = self.user_ns

2925 global_ns = self.user_global_ns

2926

2927 for key, expr in expressions.items():

2928 try:

2929 value = self._format_user_obj(eval(expr, global_ns, user_ns))

2930 except:

2931 value = self._user_obj_error()

2932 out[key] = value

2933 return out

2934

2935 #-------------------------------------------------------------------------

2936 # Things related to the running of code

2937 #-------------------------------------------------------------------------

2938

2939 def ex(self, cmd):

2940 """Execute a normal python statement in user namespace."""

2941 with self.builtin_trap:

2942 exec(cmd, self.user_global_ns, self.user_ns)

2943

2944 def ev(self, expr):

2945 """Evaluate python expression expr in user namespace.

2946

2947 Returns the result of evaluation

2948 """

2949 with self.builtin_trap:

2950 return eval(expr, self.user_global_ns, self.user_ns)

2951

2952 def safe_execfile(self, fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False):

2953 """A safe version of the builtin execfile().

2954

2955 This version will never throw an exception, but instead print

2956 helpful error messages to the screen. This only works on pure

2957 Python files with the .py extension.

2958

2959 Parameters

2960 ----------

2961 fname : string

2962 The name of the file to be executed.

2963 *where : tuple

2964 One or two namespaces, passed to execfile() as (globals,locals).

2965 If only one is given, it is passed as both.

2966 exit_ignore : bool (False)

2967 If True, then silence SystemExit for non-zero status (it is always

2968 silenced for zero status, as it is so common).

2969 raise_exceptions : bool (False)

2970 If True raise exceptions everywhere. Meant for testing.

2971 shell_futures : bool (False)

2972 If True, the code will share future statements with the interactive

2973 shell. It will both be affected by previous __future__ imports, and

2974 any __future__ imports in the code will affect the shell. If False,

2975 __future__ imports are not shared in either direction.

2976

2977 """

2978 fname = Path(fname).expanduser().resolve()

2979

2980 # Make sure we can open the file

2981 try:

2982 with fname.open("rb"):

2983 pass

2984 except OSError:

2985 warn('Could not open file <%s> for safe execution.' % fname)

2986 return

2987

2988 # Find things also in current directory. This is needed to mimic the

2989 # behavior of running a script from the system command line, where

2990 # Python inserts the script's directory into sys.path

2991 dname = str(fname.parent)

2992

2993 def execfile(fname, glob, loc=None, compiler=None):

2994 __tracebackhide__ = "__ipython_bottom__"

2995 loc = loc if (loc is not None) else glob

2996 with open(fname, "rb") as f:

2997 compiler = compiler or compile

2998 exec(compiler(f.read(), fname, "exec"), glob, loc)

2999

3000 with prepended_to_syspath(dname), self.builtin_trap:

3001 try:

3002 glob, loc = (where + (None, ))[:2]

3003 execfile(

3004 fname, glob, loc,

3005 self.compile if shell_futures else None)

3006 except SystemExit as status:

3007 # If the call was made with 0 or None exit status (sys.exit(0)

3008 # or sys.exit() ), don't bother showing a traceback, as both of

3009 # these are considered normal by the OS:

3010 # > python -c'import sys;sys.exit(0)'; echo $?

3011 # 0

3012 # > python -c'import sys;sys.exit()'; echo $?

3013 # 0

3014 # For other exit status, we show the exception unless

3015 # explicitly silenced, but only in short form.

3016 if status.code:

3017 if raise_exceptions:

3018 raise

3019 if not exit_ignore:

3020 self.showtraceback(exception_only=True)

3021 except:

3022 if raise_exceptions:

3023 raise

3024 # tb offset is 2 because we wrap execfile

3025 self.showtraceback(tb_offset=2)

3026

3027 def safe_execfile_ipy(self, fname, shell_futures=False, raise_exceptions=False):

3028 """Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.

3029

3030 Parameters

3031 ----------

3032 fname : str

3033 The name of the file to execute. The filename must have a

3034 .ipy or .ipynb extension.

3035 shell_futures : bool (False)

3036 If True, the code will share future statements with the interactive

3037 shell. It will both be affected by previous __future__ imports, and

3038 any __future__ imports in the code will affect the shell. If False,

3039 __future__ imports are not shared in either direction.

3040 raise_exceptions : bool (False)

3041 If True raise exceptions everywhere. Meant for testing.

3042 """

3043 fname = Path(fname).expanduser().resolve()

3044

3045 # Make sure we can open the file

3046 try:

3047 with fname.open("rb"):

3048 pass

3049 except OSError:

3050 warn('Could not open file <%s> for safe execution.' % fname)

3051 return

3052

3053 # Find things also in current directory. This is needed to mimic the

3054 # behavior of running a script from the system command line, where

3055 # Python inserts the script's directory into sys.path

3056 dname = str(fname.parent)

3057

3058 def get_cells():

3059 """generator for sequence of code blocks to run"""

3060 if fname.suffix == ".ipynb":

3061 from nbformat import read

3062 nb = read(fname, as_version=4)

3063 if not nb.cells:

3064 return

3065 for cell in nb.cells:

3066 if cell.cell_type == 'code':

3067 yield cell.source

3068 else:

3069 yield fname.read_text(encoding="utf-8")

3070

3071 with prepended_to_syspath(dname):

3072 try:

3073 for cell in get_cells():

3074 result = self.run_cell(cell, silent=True, shell_futures=shell_futures)

3075 if raise_exceptions:

3076 result.raise_error()

3077 elif not result.success:

3078 break

3079 except:

3080 if raise_exceptions:

3081 raise

3082 self.showtraceback()

3083 warn('Unknown failure executing file: <%s>' % fname)

3084

3085 def safe_run_module(self, mod_name, where):

3086 """A safe version of runpy.run_module().

3087

3088 This version will never throw an exception, but instead print

3089 helpful error messages to the screen.

3090

3091 `SystemExit` exceptions with status code 0 or None are ignored.

3092

3093 Parameters

3094 ----------

3095 mod_name : string

3096 The name of the module to be executed.

3097 where : dict

3098 The globals namespace.

3099 """

3100 try:

3101 try:

3102 where.update(

3103 runpy.run_module(str(mod_name), run_name="__main__",

3104 alter_sys=True)

3105 )

3106 except SystemExit as status:

3107 if status.code:

3108 raise

3109 except:

3110 self.showtraceback()

3111 warn('Unknown failure executing module: <%s>' % mod_name)

3112

3113 @contextmanager

3114 def _tee(self, channel: Literal["stdout", "stderr"]):

3115 """Capture output of a given standard stream and store it in history.

3116

3117 Uses patching of write method for maximal compatibility,

3118 because ipykernel checks for instances of the stream class,

3119 and stream classes in ipykernel implement more complex logic.

3120 """

3121 stream = getattr(sys, channel)

3122 original_write = stream.write

3123 execution_count = self.execution_count

3124

3125 def write(data, *args, **kwargs):

3126 """Write data to both the original destination and the capture dictionary."""

3127 result = original_write(data, *args, **kwargs)

3128 if any(

3129 [

3130 self.display_pub.is_publishing,

3131 self.displayhook.is_active,

3132 self.showing_traceback,

3133 ]

3134 ):

3135 return result

3136 if not data:

3137 return result

3138 output_stream = None

3139 outputs_by_counter = self.history_manager.outputs

3140 output_type = "out_stream" if channel == "stdout" else "err_stream"

3141 if execution_count in outputs_by_counter:

3142 outputs = outputs_by_counter[execution_count]

3143 if outputs[-1].output_type == output_type:

3144 output_stream = outputs[-1]

3145 if output_stream is None:

3146 output_stream = HistoryOutput(

3147 output_type=output_type, bundle={"stream": []}

3148 )

3149 outputs_by_counter[execution_count].append(output_stream)

3150

3151 output_stream.bundle["stream"].append(data) # Append to existing stream

3152 return result

3153

3154 stream.write = write

3155 yield

3156 stream.write = original_write

3157

3158 def run_cell(

3159 self,

3160 raw_cell,

3161 store_history=False,

3162 silent=False,

3163 shell_futures=True,

3164 cell_id=None,

3165 cell_meta=None,

3166 ):

3167 """Run a complete IPython cell.

3168

3169 Parameters

3170 ----------

3171 raw_cell : str

3172 The code (including IPython code such as %magic functions) to run.

3173 store_history : bool

3174 If True, the raw and translated cell will be stored in IPython's

3175 history. For user code calling back into IPython's machinery, this

3176 should be set to False.

3177 silent : bool

3178 If True, avoid side-effects, such as implicit displayhooks and

3179 and logging. silent=True forces store_history=False.

3180 shell_futures : bool

3181 If True, the code will share future statements with the interactive

3182 shell. It will both be affected by previous __future__ imports, and

3183 any __future__ imports in the code will affect the shell. If False,

3184 __future__ imports are not shared in either direction.

3185 cell_id : str, optional

3186 A unique identifier for the cell. This is used in the messaging system

3187 to match output with execution requests and for tracking cell execution

3188 history across kernel restarts. In notebook contexts, this is typically

3189 a UUID generated by the frontend. If None, the kernel may generate an

3190 internal identifier or proceed without cell tracking capabilities.

3191 cell_meta : dict, optional

3192 Metadata associated with the request. This will be passed to any event

3193 listeners as part of ExecutionInfo, enabling extension authors to append

3194 data to execution requests from a client which can then be read by an IPython

3195 extension. Extension authors are encouraged to place data associated with their extension

3196 under a single string key in the dictionary.

3197 Returns

3198 -------

3199 result : :class:`ExecutionResult`

3200 """

3201 result = None

3202 with self._tee(channel="stdout"), self._tee(channel="stderr"):

3203 try:

3204 result = self._run_cell(

3205 raw_cell, store_history, silent, shell_futures, cell_id, cell_meta

3206 )

3207 finally:

3208 self.events.trigger("post_execute")

3209 if not silent:

3210 self.events.trigger("post_run_cell", result)

3211 return result

3212

3213 def _run_cell(

3214 self,

3215 raw_cell: str,

3216 store_history: bool,

3217 silent: bool,

3218 shell_futures: bool,

3219 cell_id: str,

3220 cell_meta: dict | None,

3221 ) -> ExecutionResult:

3222 """Internal method to run a complete IPython cell."""

3223

3224 # we need to avoid calling self.transform_cell multiple time on the same thing

3225 # so we need to store some results:

3226 preprocessing_exc_tuple = None

3227 try:

3228 transformed_cell = self.transform_cell(raw_cell)

3229 except Exception:

3230 transformed_cell = raw_cell

3231 preprocessing_exc_tuple = sys.exc_info()

3232

3233 assert transformed_cell is not None

3234 coro = self.run_cell_async(

3235 raw_cell,

3236 store_history=store_history,

3237 silent=silent,

3238 shell_futures=shell_futures,

3239 transformed_cell=transformed_cell,

3240 preprocessing_exc_tuple=preprocessing_exc_tuple,

3241 cell_id=cell_id,

3242 cell_meta=cell_meta,

3243 )

3244

3245 # run_cell_async is async, but may not actually need an eventloop.

3246 # when this is the case, we want to run it using the pseudo_sync_runner

3247 # so that code can invoke eventloops (for example via the %run , and

3248 # `%paste` magic.

3249 if self.trio_runner:

3250 runner = self.trio_runner

3251 elif self.should_run_async(

3252 raw_cell,

3253 transformed_cell=transformed_cell,

3254 preprocessing_exc_tuple=preprocessing_exc_tuple,

3255 ):

3256 runner = self.loop_runner

3257 else:

3258 runner = _pseudo_sync_runner

3259

3260 try:

3261 result = runner(coro)

3262 except BaseException as e:

3263 try:

3264 info = ExecutionInfo(

3265 raw_cell,

3266 store_history,

3267 silent,

3268 shell_futures,

3269 cell_id,

3270 cell_meta,

3271 transformed_cell=transformed_cell,

3272 )

3273 result = ExecutionResult(info)

3274 result.error_in_exec = e

3275 self.showtraceback(running_compiled_code=True)

3276 except:

3277 pass

3278 return result

3279

3280 def should_run_async(

3281 self, raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None

3282 ) -> bool:

3283 """Return whether a cell should be run asynchronously via a coroutine runner

3284

3285 Parameters

3286 ----------

3287 raw_cell : str

3288 The code to be executed

3289 transformed_cell: str

3290 cell that was passed through transformers. Required (keyword

3291 only); run ``transform_cell`` yourself and pass the result here.

3292 preprocessing_exc_tuple:

3293 trace if the transformation failed.

3294

3295 Returns

3296 -------

3297 result: bool

3298 Whether the code needs to be run with a coroutine runner or not

3299 .. versionadded:: 7.0

3300

3301 .. versionchanged:: 9.16

3302 ``transformed_cell`` is now required; the deprecated fallback that

3303 called ``transform_cell`` automatically has been removed.

3304 """

3305 if not self.autoawait:

3306 return False

3307 if preprocessing_exc_tuple is not None:

3308 return False

3309 assert preprocessing_exc_tuple is None

3310 if transformed_cell is None:

3311 raise TypeError(

3312 "`should_run_async` no longer calls `transform_cell` "

3313 "automatically (this was deprecated since IPython 7.17). "

3314 "Pass the result of `transform_cell` via the "

3315 "`transformed_cell` argument, and any exception that "

3316 "happened during the transform via `preprocessing_exc_tuple`."

3317 )

3318 return _should_be_async(transformed_cell)

3319

3320 async def run_cell_async(

3321 self,

3322 raw_cell: str,

3323 store_history=False,

3324 silent=False,

3325 shell_futures=True,

3326 *,

3327 transformed_cell: str | None = None,

3328 preprocessing_exc_tuple: AnyType | None = None,

3329 cell_id=None,

3330 cell_meta=None,

3331 ) -> ExecutionResult:

3332 """Run a complete IPython cell asynchronously.

3333

3334 Parameters

3335 ----------

3336 raw_cell : str

3337 The code (including IPython code such as %magic functions) to run.

3338 store_history : bool

3339 If True, the raw and translated cell will be stored in IPython's

3340 history. For user code calling back into IPython's machinery, this

3341 should be set to False.

3342 silent : bool

3343 If True, avoid side-effects, such as implicit displayhooks and

3344 and logging. silent=True forces store_history=False.

3345 shell_futures : bool

3346 If True, the code will share future statements with the interactive

3347 shell. It will both be affected by previous __future__ imports, and

3348 any __future__ imports in the code will affect the shell. If False,

3349 __future__ imports are not shared in either direction.

3350 transformed_cell: str

3351 cell that was passed through transformers. Required (keyword only);

3352 run ``transform_cell`` yourself and pass the result here.

3353 preprocessing_exc_tuple:

3354 trace if the transformation failed.

3355

3356 Returns

3357 -------

3358 result : :class:`ExecutionResult`

3359

3360 .. versionadded:: 7.0

3361

3362 .. versionchanged:: 9.16

3363 ``transformed_cell`` is now required; the deprecated fallback that

3364 called ``transform_cell`` automatically has been removed.

3365 """

3366 if transformed_cell is None:

3367 raise TypeError(

3368 "`run_cell_async` no longer calls `transform_cell` "

3369 "automatically (this was deprecated since IPython 7.17). "

3370 "Pass the result of `transform_cell` via the "

3371 "`transformed_cell` argument, and any exception that "

3372 "happened during the transform via `preprocessing_exc_tuple`."

3373 )

3374 info = ExecutionInfo(

3375 raw_cell,

3376 store_history,

3377 silent,

3378 shell_futures,

3379 cell_id,

3380 cell_meta,

3381 transformed_cell=transformed_cell,

3382 )

3383 result = ExecutionResult(info)

3384

3385 if (not raw_cell) or raw_cell.isspace():

3386 self.last_execution_succeeded = True

3387 self.last_execution_result = result

3388 return result

3389

3390 if silent:

3391 store_history = False

3392

3393 execution_count = result.execution_count = self.execution_count

3394

3395 if store_history:

3396 self.execution_count += 1

3397

3398 def error_before_exec(value):

3399 if store_history:

3400 if self.history_manager:

3401 # Store formatted traceback and error details

3402 self.history_manager.exceptions[

3403 execution_count

3404 ] = self._format_exception_for_storage(value)

3405 result.error_before_exec = value

3406 self.last_execution_succeeded = False

3407 self.last_execution_result = result

3408 return result

3409

3410 self.events.trigger('pre_execute')

3411 if not silent:

3412 self.events.trigger('pre_run_cell', info)

3413

3414 if preprocessing_exc_tuple is None:

3415 cell = transformed_cell

3416 else:

3417 cell = raw_cell

3418

3419 # Do NOT store paste/cpaste magic history

3420 if "get_ipython().run_line_magic(" in cell and "paste" in cell:

3421 store_history = False

3422

3423 # Store raw and processed history

3424 if store_history:

3425 assert self.history_manager is not None

3426 self.history_manager.store_inputs(execution_count, cell, raw_cell)

3427 if not silent:

3428 self.logger.log(cell, raw_cell)

3429

3430 # Display the exception if input processing failed.

3431 if preprocessing_exc_tuple is not None:

3432 self.showtraceback(preprocessing_exc_tuple)

3433 return error_before_exec(preprocessing_exc_tuple[1])

3434

3435 # Our own compiler remembers the __future__ environment. If we want to

3436 # run code with a separate __future__ environment, use the default

3437 # compiler

3438 compiler = self.compile if shell_futures else self.compiler_class()

3439

3440 with self.builtin_trap:

3441 cell_name = compiler.cache(cell, execution_count, raw_code=raw_cell)

3442

3443 with self.display_trap:

3444 # Compile to bytecode

3445 try:

3446 code_ast = compiler.ast_parse(cell, filename=cell_name)

3447 except self.custom_exceptions as e:

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

3449 self.CustomTB(etype, value, tb)

3450 return error_before_exec(e)

3451 except IndentationError as e:

3452 self.showindentationerror()

3453 return error_before_exec(e)

3454 except (OverflowError, SyntaxError, ValueError, TypeError,

3455 MemoryError) as e:

3456 self.showsyntaxerror()

3457 return error_before_exec(e)

3458

3459 # Apply AST transformations

3460 try:

3461 code_ast = self.transform_ast(code_ast)

3462 except InputRejected as e:

3463 self.showtraceback()

3464 return error_before_exec(e)

3465

3466 # Give the displayhook a reference to our ExecutionResult so it

3467 # can fill in the output value.

3468 self.displayhook.exec_result = result

3469

3470 # Execute the user code

3471 interactivity = "none" if silent else self.ast_node_interactivity

3472

3473

3474 has_raised = await self.run_ast_nodes(code_ast.body, cell_name,

3475 interactivity=interactivity, compiler=compiler, result=result)

3476

3477 self.last_execution_succeeded = not has_raised

3478 self.last_execution_result = result

3479

3480 # Reset this so later displayed values do not modify the

3481 # ExecutionResult

3482 self.displayhook.exec_result = None

3483

3484 if store_history:

3485 assert self.history_manager is not None

3486 # Write output to the database. Does nothing unless

3487 # history output logging is enabled.

3488 self.history_manager.store_output(execution_count)

3489 if result.error_in_exec:

3490 # Store formatted traceback and error details

3491 self.history_manager.exceptions[

3492 execution_count

3493 ] = self._format_exception_for_storage(result.error_in_exec)

3494

3495 return result

3496

3497 def _format_exception_for_storage(

3498 self, exception, filename=None, running_compiled_code=False

3499 ):

3500 """

3501 Format an exception's traceback and details for storage, with special handling

3502 for different types of errors.

3503 """

3504 etype = type(exception)

3505 evalue = exception

3506 tb = exception.__traceback__

3507

3508 # Handle SyntaxError and IndentationError with specific formatting

3509 if issubclass(etype, (SyntaxError, IndentationError)):

3510 if filename and isinstance(evalue, SyntaxError):

3511 try:

3512 evalue.filename = filename

3513 except AttributeError:

3514 pass # Keep the original filename if modification fails

3515

3516 # Extract traceback if the error happened during compiled code execution

3517 elist = traceback.extract_tb(tb) if running_compiled_code else []

3518 stb = self.SyntaxTB.structured_traceback(etype, evalue, elist)

3519

3520 # Handle UsageError with a simple message

3521 elif etype is UsageError:

3522 stb = [f"UsageError: {evalue}"]

3523

3524 else:

3525 # Check if the exception (or its context) is an ExceptionGroup.

3526 def contains_exceptiongroup(val):

3527 if val is None:

3528 return False

3529 return isinstance(val, BaseExceptionGroup) or contains_exceptiongroup(

3530 val.__context__

3531 )

3532

3533 if contains_exceptiongroup(evalue):

3534 # Fallback: use the standard library's formatting for exception groups.

3535 stb = traceback.format_exception(etype, evalue, tb)

3536 else:

3537 try:

3538 # If the exception has a custom traceback renderer, use it.

3539 if hasattr(evalue, "_render_traceback_"):

3540 stb = evalue._render_traceback_()

3541 else:

3542 # Otherwise, use InteractiveTB to format the traceback.

3543 stb = self.InteractiveTB.structured_traceback(

3544 etype, evalue, tb, tb_offset=1

3545 )

3546 except Exception:

3547 # In case formatting fails, fallback to Python's built-in formatting.

3548 stb = traceback.format_exception(etype, evalue, tb)

3549

3550 return {"ename": etype.__name__, "evalue": str(evalue), "traceback": stb}

3551

3552 def transform_cell(self, raw_cell):

3553 """Transform an input cell before parsing it.

3554

3555 Static transformations, implemented in IPython.core.inputtransformer2,

3556 deal with things like ``%magic`` and ``!system`` commands.

3557 These run on all input.

3558 Dynamic transformations, for things like unescaped magics and the exit

3559 autocall, depend on the state of the interpreter.

3560 These only apply to single line inputs.

3561

3562 These string-based transformations are followed by AST transformations;

3563 see :meth:`transform_ast`.

3564 """

3565 # Static input transformations

3566 cell = self.input_transformer_manager.transform_cell(raw_cell)

3567

3568 if len(cell.splitlines()) == 1:

3569 # Dynamic transformations - only applied for single line commands

3570 with self.builtin_trap:

3571 # use prefilter_lines to handle trailing newlines

3572 # restore trailing newline for ast.parse

3573 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'

3574

3575 lines = cell.splitlines(keepends=True)

3576 for transform in self.input_transformers_post:

3577 lines = transform(lines)

3578 cell = ''.join(lines)

3579

3580 return cell

3581

3582 def transform_ast(self, node):

3583 """Apply the AST transformations from self.ast_transformers

3584

3585 Parameters

3586 ----------

3587 node : ast.Node

3588 The root node to be transformed. Typically called with the ast.Module

3589 produced by parsing user input.

3590

3591 Returns

3592 -------

3593 An ast.Node corresponding to the node it was called with. Note that it

3594 may also modify the passed object, so don't rely on references to the

3595 original AST.

3596 """

3597 for transformer in self.ast_transformers:

3598 try:

3599 node = transformer.visit(node)

3600 except InputRejected:

3601 # User-supplied AST transformers can reject an input by raising

3602 # an InputRejected. Short-circuit in this case so that we

3603 # don't unregister the transform.

3604 raise

3605 except Exception as e:

3606 warn(

3607 "AST transformer %r threw an error. It will be unregistered. %s"

3608 % (transformer, e)

3609 )

3610 self.ast_transformers.remove(transformer)

3611

3612 if self.ast_transformers:

3613 ast.fix_missing_locations(node)

3614 return node

3615

3616 async def run_ast_nodes(

3617 self,

3618 nodelist: list[stmt],

3619 cell_name: str,

3620 interactivity="last_expr",

3621 compiler=compile,

3622 result=None,

3623 ):

3624 """Run a sequence of AST nodes. The execution mode depends on the

3625 interactivity parameter.

3626

3627 Parameters

3628 ----------

3629 nodelist : list

3630 A sequence of AST nodes to run.

3631 cell_name : str

3632 Will be passed to the compiler as the filename of the cell. Typically

3633 the value returned by ip.compile.cache(cell).

3634 interactivity : str

3635 'all', 'last', 'last_expr' , 'last_expr_or_assign' or 'none',

3636 specifying which nodes should be run interactively (displaying output

3637 from expressions). 'last_expr' will run the last node interactively

3638 only if it is an expression (i.e. expressions in loops or other blocks

3639 are not displayed) 'last_expr_or_assign' will run the last expression

3640 or the last assignment. Other values for this parameter will raise a

3641 ValueError.

3642

3643 compiler : callable

3644 A function with the same interface as the built-in compile(), to turn

3645 the AST nodes into code objects. Default is the built-in compile().

3646 result : ExecutionResult, optional

3647 An object to store exceptions that occur during execution.

3648

3649 Returns

3650 -------

3651 True if an exception occurred while running code, False if it finished

3652 running.

3653 """

3654 if not nodelist:

3655 return

3656

3657

3658 if interactivity == 'last_expr_or_assign':

3659 if isinstance(nodelist[-1], _assign_nodes):

3660 asg = nodelist[-1]

3661 if isinstance(asg, ast.Assign) and len(asg.targets) == 1:

3662 target = asg.targets[0]

3663 elif isinstance(asg, _single_targets_nodes):

3664 target = asg.target

3665 else:

3666 target = None

3667 if isinstance(target, ast.Name):

3668 nnode = ast.Expr(ast.Name(target.id, ast.Load()))

3669 ast.fix_missing_locations(nnode)

3670 nodelist.append(nnode)

3671 interactivity = 'last_expr'

3672

3673 _async = False

3674 if interactivity == 'last_expr':

3675 if isinstance(nodelist[-1], ast.Expr):

3676 interactivity = "last"

3677 else:

3678 interactivity = "none"

3679

3680 if interactivity == 'none':

3681 to_run_exec, to_run_interactive = nodelist, []

3682 elif interactivity == 'last':

3683 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]

3684 elif interactivity == 'all':

3685 to_run_exec, to_run_interactive = [], nodelist

3686 else:

3687 raise ValueError("Interactivity was %r" % interactivity)

3688

3689 try:

3690

3691 def compare(code):

3692 is_async = inspect.CO_COROUTINE & code.co_flags == inspect.CO_COROUTINE

3693 return is_async

3694

3695 # refactor that to just change the mod constructor.

3696 to_run = []

3697 for node in to_run_exec:

3698 to_run.append((node, "exec"))

3699

3700 for node in to_run_interactive:

3701 to_run.append((node, "single"))

3702

3703 for node, mode in to_run:

3704 if mode == "exec":

3705 mod = Module([node], [])

3706 elif mode == "single":

3707 mod = ast.Interactive([node])

3708 with compiler.extra_flags(

3709 getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x0)

3710 if self.autoawait

3711 else 0x0

3712 ):

3713 code = compiler(mod, cell_name, mode)

3714 asy = compare(code)

3715 if await self.run_code(code, result, async_=asy):

3716 return True

3717

3718 # Flush softspace

3719 if softspace(sys.stdout, 0):

3720 print()

3721

3722 except:

3723 # It's possible to have exceptions raised here, typically by

3724 # compilation of odd code (such as a naked 'return' outside a

3725 # function) that did parse but isn't valid. Typically the exception

3726 # is a SyntaxError, but it's safest just to catch anything and show

3727 # the user a traceback.

3728

3729 # We do only one try/except outside the loop to minimize the impact

3730 # on runtime, and also because if any node in the node list is

3731 # broken, we should stop execution completely.

3732 if result:

3733 result.error_before_exec = sys.exc_info()[1]

3734 self.showtraceback()

3735 return True

3736

3737 return False

3738

3739 async def run_code(self, code_obj, result=None, *, async_=False):

3740 """Execute a code object.

3741

3742 When an exception occurs, self.showtraceback() is called to display a

3743 traceback.

3744

3745 Parameters

3746 ----------

3747 code_obj : code object

3748 A compiled code object, to be executed

3749 result : ExecutionResult, optional

3750 An object to store exceptions that occur during execution.

3751 async_ : Bool (Experimental)

3752 Attempt to run top-level asynchronous code in a default loop.

3753

3754 Returns

3755 -------

3756 False : successful execution.

3757 True : an error occurred.

3758 """

3759 # special value to say that anything above is IPython and should be

3760 # hidden.

3761 __tracebackhide__ = "__ipython_bottom__"

3762 # Set our own excepthook in case the user code tries to call it

3763 # directly, so that the IPython crash handler doesn't get triggered

3764 old_excepthook, sys.excepthook = sys.excepthook, self.excepthook

3765

3766 # we save the original sys.excepthook in the instance, in case config

3767 # code (such as magics) needs access to it.

3768 self.sys_excepthook = old_excepthook

3769 outflag = True # happens in more places, so it's easier as default

3770 try:

3771 try:

3772 if async_:

3773 await eval(code_obj, self.user_global_ns, self.user_ns)

3774 else:

3775 exec(code_obj, self.user_global_ns, self.user_ns)

3776 finally:

3777 # Reset our crash handler in place

3778 sys.excepthook = old_excepthook

3779 except SystemExit as e:

3780 if result is not None:

3781 result.error_in_exec = e

3782 self.showtraceback(exception_only=True)

3783 warn("To exit: use 'exit', 'quit', or Ctrl-D.", stacklevel=1)

3784 except bdb.BdbQuit:

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

3786 if result is not None:

3787 result.error_in_exec = value

3788 # the BdbQuit stops here

3789 except self.custom_exceptions:

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

3791 if result is not None:

3792 result.error_in_exec = value

3793 self.CustomTB(etype, value, tb)

3794 except:

3795 if result is not None:

3796 result.error_in_exec = sys.exc_info()[1]

3797 self.showtraceback(running_compiled_code=True)

3798 else:

3799 outflag = False

3800 return outflag

3801

3802 # For backwards compatibility

3803 runcode = run_code

3804

3805 def check_complete(self, code: str) -> tuple[str, str]:

3806 """Return whether a block of code is ready to execute, or should be continued

3807

3808 Parameters

3809 ----------

3810 code : string

3811 Python input code, which can be multiline.

3812

3813 Returns

3814 -------

3815 status : str

3816 One of 'complete', 'incomplete', or 'invalid' if source is not a

3817 prefix of valid code.

3818 indent : str

3819 When status is 'incomplete', this is some whitespace to insert on

3820 the next line of the prompt.

3821 """

3822 status, nspaces = self.input_transformer_manager.check_complete(code)

3823 return status, ' ' * (nspaces or 0)

3824

3825 #-------------------------------------------------------------------------

3826 # Things related to GUI support and pylab

3827 #-------------------------------------------------------------------------

3828

3829 active_eventloop: str | None = None

3830

3831 def enable_gui(self, gui=None):

3832 raise NotImplementedError('Implement enable_gui in a subclass')

3833

3834 def enable_matplotlib(self, gui=None):

3835 """Enable interactive matplotlib and inline figure support.

3836

3837 This takes the following steps:

3838

3839 1. select the appropriate eventloop and matplotlib backend

3840 2. set up matplotlib for interactive use with that backend

3841 3. configure formatters for inline figure display

3842 4. enable the selected gui eventloop

3843

3844 Parameters

3845 ----------

3846 gui : optional, string

3847 If given, dictates the choice of matplotlib GUI backend to use

3848 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',

3849 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by

3850 matplotlib (as dictated by the matplotlib build-time options plus the

3851 user's matplotlibrc configuration file). Note that not all backends

3852 make sense in all contexts, for example a terminal ipython can't

3853 display figures inline.

3854 """

3855 from .pylabtools import _matplotlib_manages_backends

3856

3857 if not _matplotlib_manages_backends() and gui in (None, "auto"):

3858 # Early import of backend_inline required for its side effect of

3859 # calling _enable_matplotlib_integration()

3860 import matplotlib_inline.backend_inline

3861

3862 from IPython.core import pylabtools as pt

3863 gui, backend = pt.find_gui_and_backend(gui, self.pylab_gui_select)

3864

3865 if gui != None:

3866 # If we have our first gui selection, store it

3867 if self.pylab_gui_select is None:

3868 self.pylab_gui_select = gui

3869 # Otherwise if they are different

3870 elif gui != self.pylab_gui_select:

3871 print('Warning: Cannot change to a different GUI toolkit: %s.'

3872 ' Using %s instead.' % (gui, self.pylab_gui_select))

3873 gui, backend = pt.find_gui_and_backend(self.pylab_gui_select)

3874

3875 pt.activate_matplotlib(backend)

3876

3877 from matplotlib_inline.backend_inline import configure_inline_support

3878

3879 configure_inline_support(self, backend)

3880

3881 # Now we must activate the gui pylab wants to use, and fix %run to take

3882 # plot updates into account

3883 self.enable_gui(gui)

3884 self.magics_manager.registry['ExecutionMagics'].default_runner = \

3885 pt.mpl_runner(self.safe_execfile)

3886

3887 return gui, backend

3888

3889 def enable_pylab(self, gui=None, import_all=True):

3890 """Activate pylab support at runtime.

3891

3892 This turns on support for matplotlib, preloads into the interactive

3893 namespace all of numpy and pylab, and configures IPython to correctly

3894 interact with the GUI event loop. The GUI backend to be used can be

3895 optionally selected with the optional ``gui`` argument.

3896

3897 This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.

3898

3899 Parameters

3900 ----------

3901 gui : optional, string

3902 If given, dictates the choice of matplotlib GUI backend to use

3903 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',

3904 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by

3905 matplotlib (as dictated by the matplotlib build-time options plus the

3906 user's matplotlibrc configuration file). Note that not all backends

3907 make sense in all contexts, for example a terminal ipython can't

3908 display figures inline.

3909 import_all : optional, bool, default: True

3910 Whether to do `from numpy import *` and `from pylab import *`

3911 in addition to module imports.

3912 """

3913 from IPython.core.pylabtools import import_pylab

3914

3915 gui, backend = self.enable_matplotlib(gui)

3916

3917 # We want to prevent the loading of pylab to pollute the user's

3918 # namespace as shown by the %who* magics, so we execute the activation

3919 # code in an empty namespace, and we update *both* user_ns and

3920 # user_ns_hidden with this information.

3921 ns = {}

3922 import_pylab(ns, import_all)

3923 # warn about clobbered names

3924 ignored = {"__builtins__"}

3925 both = set(ns).intersection(self.user_ns).difference(ignored)

3926 clobbered = [ name for name in both if self.user_ns[name] is not ns[name] ]

3927 self.user_ns.update(ns)

3928 self.user_ns_hidden.update(ns)

3929 return gui, backend, clobbered

3930

3931 #-------------------------------------------------------------------------

3932 # Utilities

3933 #-------------------------------------------------------------------------

3934

3935 def var_expand(self, cmd, depth=0, formatter=_dollar_formatter):

3936 """Expand python variables in a string.

3937

3938 The depth argument indicates how many frames above the caller should

3939 be walked to look for the local namespace where to expand variables.

3940

3941 The global namespace for expansion is always the user's interactive

3942 namespace.

3943 """

3944 ns = self.user_ns.copy()

3945 try:

3946 frame = sys._getframe(depth+1)

3947 except ValueError:

3948 # This is thrown if there aren't that many frames on the stack,

3949 # e.g. if a script called run_line_magic() directly.

3950 pass

3951 else:

3952 ns.update(frame.f_locals)

3953

3954 try:

3955 # We have to use .vformat() here, because 'self' is a valid and common

3956 # name, and expanding **ns for .format() would make it collide with

3957 # the 'self' argument of the method.

3958 cmd = formatter.vformat(cmd, args=[], kwargs=ns)

3959 except Exception:

3960 # if formatter couldn't format, just let it go untransformed

3961 pass

3962 return cmd

3963

3964 def mktempfile(self, data=None, prefix='ipython_edit_'):

3965 """Make a new tempfile and return its filename.

3966

3967 This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp),

3968 but it registers the created filename internally so ipython cleans it up

3969 at exit time.

3970

3971 Optional inputs:

3972

3973 - data(None): if data is given, it gets written out to the temp file

3974 immediately, and the file is closed again."""

3975

3976 dir_path = Path(tempfile.mkdtemp(prefix=prefix))

3977 self.tempdirs.append(dir_path)

3978

3979 handle, filename = tempfile.mkstemp(".py", prefix, dir=str(dir_path))

3980 os.close(handle) # On Windows, there can only be one open handle on a file

3981

3982 file_path = Path(filename)

3983 self.tempfiles.append(file_path)

3984

3985 if data:

3986 file_path.write_text(data, encoding="utf-8")

3987 return filename

3988

3989 def ask_yes_no(self, prompt, default=None, interrupt=None):

3990 if self.quiet:

3991 return True

3992 return ask_yes_no(prompt,default,interrupt)

3993

3994 def show_usage(self):

3995 """Show a usage message"""

3996 page.page(IPython.core.usage.interactive_usage)

3997

3998 def extract_input_lines(self, range_str, raw=False):

3999 """Return as a string a set of input history slices.

4000

4001 Parameters

4002 ----------

4003 range_str : str

4004 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",

4005 since this function is for use by magic functions which get their

4006 arguments as strings. The number before the / is the session

4007 number: ~n goes n back from the current session.

4008

4009 If empty string is given, returns history of current session

4010 without the last input.

4011

4012 raw : bool, optional

4013 By default, the processed input is used. If this is true, the raw

4014 input history is used instead.

4015

4016 Notes

4017 -----

4018 Slices can be described with two notations:

4019

4020 * ``N:M`` -> standard python form, means including items N...(M-1).

4021 * ``N-M`` -> include items N..M (closed endpoint).

4022 """

4023 lines = self.history_manager.get_range_by_str(range_str, raw=raw)

4024 text = "\n".join(x for _, _, x in lines)

4025

4026 # Skip the last line, as it's probably the magic that called this

4027 if not range_str:

4028 if "\n" not in text:

4029 text = ""

4030 else:

4031 text = text[: text.rfind("\n")]

4032

4033 return text

4034

4035 def find_user_code(self, target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False):

4036 """Get a code string from history, file, url, or a string or macro.

4037

4038 This is mainly used by magic functions.

4039

4040 Parameters

4041 ----------

4042 target : str

4043 A string specifying code to retrieve. This will be tried respectively

4044 as: ranges of input history (see %history for syntax), url,

4045 corresponding .py file, filename, or an expression evaluating to a

4046 string or Macro in the user namespace.

4047

4048 If empty string is given, returns complete history of current

4049 session, without the last line.

4050

4051 raw : bool

4052 If true (default), retrieve raw history. Has no effect on the other

4053 retrieval mechanisms.

4054

4055 py_only : bool (default False)

4056 Only try to fetch python code, do not try alternative methods to decode file

4057 if unicode fails.

4058

4059 Returns

4060 -------

4061 A string of code.

4062 ValueError is raised if nothing is found, and TypeError if it evaluates

4063 to an object of another type. In each case, .args[0] is a printable

4064 message.

4065 """

4066 code = self.extract_input_lines(target, raw=raw) # Grab history

4067 if code:

4068 return code

4069 try:

4070 if target.startswith(('http://', 'https://')):

4071 return openpy.read_py_url(target, skip_encoding_cookie=skip_encoding_cookie)

4072 except UnicodeDecodeError as e:

4073 if not py_only :

4074 # Deferred import

4075 from urllib.request import urlopen

4076 response = urlopen(target)

4077 return response.read().decode('latin1')

4078 raise ValueError(("'%s' seem to be unreadable.") % target) from e

4079

4080 potential_target = [target]

4081 try :

4082 potential_target.insert(0,get_py_filename(target))

4083 except OSError:

4084 pass

4085

4086 for tgt in potential_target :

4087 if os.path.isfile(tgt): # Read file

4088 try :

4089 return openpy.read_py_file(tgt, skip_encoding_cookie=skip_encoding_cookie)

4090 except UnicodeDecodeError as e:

4091 if not py_only :

4092 with io_open(tgt,'r', encoding='latin1') as f :

4093 return f.read()

4094 raise ValueError(("'%s' seem to be unreadable.") % target) from e

4095 elif os.path.isdir(os.path.expanduser(tgt)):

4096 raise ValueError("'%s' is a directory, not a regular file." % target)

4097

4098 if search_ns:

4099 # Inspect namespace to load object source

4100 object_info = self.object_inspect(target, detail_level=1)

4101 if object_info['found'] and object_info['source']:

4102 return object_info['source']

4103

4104 try: # User namespace

4105 codeobj = eval(target, self.user_ns)

4106 except Exception as e:

4107 raise ValueError(("'%s' was not found in history, as a file, url, "

4108 "nor in the user namespace.") % target) from e

4109

4110 if isinstance(codeobj, str):

4111 return codeobj

4112 elif isinstance(codeobj, Macro):

4113 return codeobj.value

4114

4115 raise TypeError("%s is neither a string nor a macro." % target,

4116 codeobj)

4117

4118 def _atexit_once(self):

4119 """

4120 At exist operation that need to be called at most once.

4121 Second call to this function per instance will do nothing.

4122 """

4123

4124 if not getattr(self, "_atexit_once_called", False):

4125 self._atexit_once_called = True

4126 # Clear all user namespaces to release all references cleanly.

4127 self.reset(new_session=False)

4128 # Close the history session (this stores the end time and line count)

4129 # this must be *before* the tempfile cleanup, in case of temporary

4130 # history db

4131 if self.history_manager is not None:

4132 self.history_manager.end_session()

4133 # Stop the saving thread and close the database deterministically

4134 self.history_manager.close()

4135 self.history_manager = None

4136 #-------------------------------------------------------------------------

4137 # Things related to IPython exiting

4138 #-------------------------------------------------------------------------

4139 def atexit_operations(self):

4140 """This will be executed at the time of exit.

4141

4142 Cleanup operations and saving of persistent data that is done

4143 unconditionally by IPython should be performed here.

4144

4145 For things that may depend on startup flags or platform specifics (such

4146 as having readline or not), register a separate atexit function in the

4147 code that has the appropriate information, rather than trying to

4148 clutter

4149 """

4150 self._atexit_once()

4151

4152 # Cleanup all tempfiles and folders left around

4153 for tfile in self.tempfiles:

4154 try:

4155 tfile.unlink()

4156 self.tempfiles.remove(tfile)

4157 except FileNotFoundError:

4158 pass

4159 del self.tempfiles

4160 for tdir in self.tempdirs:

4161 try:

4162 shutil.rmtree(tdir)

4163 self.tempdirs.remove(tdir)

4164 except FileNotFoundError:

4165 pass

4166 del self.tempdirs

4167

4168 # Restore user's cursor

4169 if hasattr(self, "editing_mode") and self.editing_mode == "vi":

4170 sys.stdout.write("\x1b[0 q")

4171 sys.stdout.flush()

4172

4173 def cleanup(self):

4174 self.restore_sys_module_state()

4175

4176

4177 # Overridden in terminal subclass to change prompts

4178 def switch_doctest_mode(self, mode):

4179 pass

4180

4181

4182class InteractiveShellABC(metaclass=abc.ABCMeta):

4183 """An abstract base class for InteractiveShell."""

4184

4185InteractiveShellABC.register(InteractiveShell)