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