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