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