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