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