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