##// END OF EJS Templates
Merge pull request #2184 from jasongrout/store-history...
Thomas Kluyver -
r8236:f56e91cd merge
parent child Browse files
Show More
@@ -1,3029 +1,3029 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19 from __future__ import print_function
19 from __future__ import print_function
20
20
21 import __builtin__ as builtin_mod
21 import __builtin__ as builtin_mod
22 import __future__
22 import __future__
23 import abc
23 import abc
24 import ast
24 import ast
25 import atexit
25 import atexit
26 import os
26 import os
27 import re
27 import re
28 import runpy
28 import runpy
29 import sys
29 import sys
30 import tempfile
30 import tempfile
31 import types
31 import types
32
32
33 # We need to use nested to support python 2.6, once we move to >=2.7, we can
33 # We need to use nested to support python 2.6, once we move to >=2.7, we can
34 # use the with keyword's new builtin support for nested managers
34 # use the with keyword's new builtin support for nested managers
35 try:
35 try:
36 from contextlib import nested
36 from contextlib import nested
37 except:
37 except:
38 from IPython.utils.nested_context import nested
38 from IPython.utils.nested_context import nested
39
39
40 from IPython.config.configurable import SingletonConfigurable
40 from IPython.config.configurable import SingletonConfigurable
41 from IPython.core import debugger, oinspect
41 from IPython.core import debugger, oinspect
42 from IPython.core import history as ipcorehist
42 from IPython.core import history as ipcorehist
43 from IPython.core import magic
43 from IPython.core import magic
44 from IPython.core import page
44 from IPython.core import page
45 from IPython.core import prefilter
45 from IPython.core import prefilter
46 from IPython.core import shadowns
46 from IPython.core import shadowns
47 from IPython.core import ultratb
47 from IPython.core import ultratb
48 from IPython.core.alias import AliasManager, AliasError
48 from IPython.core.alias import AliasManager, AliasError
49 from IPython.core.autocall import ExitAutocall
49 from IPython.core.autocall import ExitAutocall
50 from IPython.core.builtin_trap import BuiltinTrap
50 from IPython.core.builtin_trap import BuiltinTrap
51 from IPython.core.compilerop import CachingCompiler
51 from IPython.core.compilerop import CachingCompiler
52 from IPython.core.display_trap import DisplayTrap
52 from IPython.core.display_trap import DisplayTrap
53 from IPython.core.displayhook import DisplayHook
53 from IPython.core.displayhook import DisplayHook
54 from IPython.core.displaypub import DisplayPublisher
54 from IPython.core.displaypub import DisplayPublisher
55 from IPython.core.error import UsageError
55 from IPython.core.error import UsageError
56 from IPython.core.extensions import ExtensionManager
56 from IPython.core.extensions import ExtensionManager
57 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
57 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
58 from IPython.core.formatters import DisplayFormatter
58 from IPython.core.formatters import DisplayFormatter
59 from IPython.core.history import HistoryManager
59 from IPython.core.history import HistoryManager
60 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
60 from IPython.core.inputsplitter import IPythonInputSplitter, ESC_MAGIC, ESC_MAGIC2
61 from IPython.core.logger import Logger
61 from IPython.core.logger import Logger
62 from IPython.core.macro import Macro
62 from IPython.core.macro import Macro
63 from IPython.core.payload import PayloadManager
63 from IPython.core.payload import PayloadManager
64 from IPython.core.plugin import PluginManager
64 from IPython.core.plugin import PluginManager
65 from IPython.core.prefilter import PrefilterManager
65 from IPython.core.prefilter import PrefilterManager
66 from IPython.core.profiledir import ProfileDir
66 from IPython.core.profiledir import ProfileDir
67 from IPython.core.pylabtools import pylab_activate
67 from IPython.core.pylabtools import pylab_activate
68 from IPython.core.prompts import PromptManager
68 from IPython.core.prompts import PromptManager
69 from IPython.lib.latextools import LaTeXTool
69 from IPython.lib.latextools import LaTeXTool
70 from IPython.utils import PyColorize
70 from IPython.utils import PyColorize
71 from IPython.utils import io
71 from IPython.utils import io
72 from IPython.utils import py3compat
72 from IPython.utils import py3compat
73 from IPython.utils import openpy
73 from IPython.utils import openpy
74 from IPython.utils.doctestreload import doctest_reload
74 from IPython.utils.doctestreload import doctest_reload
75 from IPython.utils.io import ask_yes_no
75 from IPython.utils.io import ask_yes_no
76 from IPython.utils.ipstruct import Struct
76 from IPython.utils.ipstruct import Struct
77 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
77 from IPython.utils.path import get_home_dir, get_ipython_dir, get_py_filename, unquote_filename
78 from IPython.utils.pickleshare import PickleShareDB
78 from IPython.utils.pickleshare import PickleShareDB
79 from IPython.utils.process import system, getoutput
79 from IPython.utils.process import system, getoutput
80 from IPython.utils.strdispatch import StrDispatch
80 from IPython.utils.strdispatch import StrDispatch
81 from IPython.utils.syspathcontext import prepended_to_syspath
81 from IPython.utils.syspathcontext import prepended_to_syspath
82 from IPython.utils.text import (format_screen, LSString, SList,
82 from IPython.utils.text import (format_screen, LSString, SList,
83 DollarFormatter)
83 DollarFormatter)
84 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
84 from IPython.utils.traitlets import (Integer, CBool, CaselessStrEnum, Enum,
85 List, Unicode, Instance, Type)
85 List, Unicode, Instance, Type)
86 from IPython.utils.warn import warn, error
86 from IPython.utils.warn import warn, error
87 import IPython.core.hooks
87 import IPython.core.hooks
88
88
89 #-----------------------------------------------------------------------------
89 #-----------------------------------------------------------------------------
90 # Globals
90 # Globals
91 #-----------------------------------------------------------------------------
91 #-----------------------------------------------------------------------------
92
92
93 # compiled regexps for autoindent management
93 # compiled regexps for autoindent management
94 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
94 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
95
95
96 #-----------------------------------------------------------------------------
96 #-----------------------------------------------------------------------------
97 # Utilities
97 # Utilities
98 #-----------------------------------------------------------------------------
98 #-----------------------------------------------------------------------------
99
99
100 def softspace(file, newvalue):
100 def softspace(file, newvalue):
101 """Copied from code.py, to remove the dependency"""
101 """Copied from code.py, to remove the dependency"""
102
102
103 oldvalue = 0
103 oldvalue = 0
104 try:
104 try:
105 oldvalue = file.softspace
105 oldvalue = file.softspace
106 except AttributeError:
106 except AttributeError:
107 pass
107 pass
108 try:
108 try:
109 file.softspace = newvalue
109 file.softspace = newvalue
110 except (AttributeError, TypeError):
110 except (AttributeError, TypeError):
111 # "attribute-less object" or "read-only attributes"
111 # "attribute-less object" or "read-only attributes"
112 pass
112 pass
113 return oldvalue
113 return oldvalue
114
114
115
115
116 def no_op(*a, **kw): pass
116 def no_op(*a, **kw): pass
117
117
118 class NoOpContext(object):
118 class NoOpContext(object):
119 def __enter__(self): pass
119 def __enter__(self): pass
120 def __exit__(self, type, value, traceback): pass
120 def __exit__(self, type, value, traceback): pass
121 no_op_context = NoOpContext()
121 no_op_context = NoOpContext()
122
122
123 class SpaceInInput(Exception): pass
123 class SpaceInInput(Exception): pass
124
124
125 class Bunch: pass
125 class Bunch: pass
126
126
127
127
128 def get_default_colors():
128 def get_default_colors():
129 if sys.platform=='darwin':
129 if sys.platform=='darwin':
130 return "LightBG"
130 return "LightBG"
131 elif os.name=='nt':
131 elif os.name=='nt':
132 return 'Linux'
132 return 'Linux'
133 else:
133 else:
134 return 'Linux'
134 return 'Linux'
135
135
136
136
137 class SeparateUnicode(Unicode):
137 class SeparateUnicode(Unicode):
138 """A Unicode subclass to validate separate_in, separate_out, etc.
138 """A Unicode subclass to validate separate_in, separate_out, etc.
139
139
140 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
140 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
141 """
141 """
142
142
143 def validate(self, obj, value):
143 def validate(self, obj, value):
144 if value == '0': value = ''
144 if value == '0': value = ''
145 value = value.replace('\\n','\n')
145 value = value.replace('\\n','\n')
146 return super(SeparateUnicode, self).validate(obj, value)
146 return super(SeparateUnicode, self).validate(obj, value)
147
147
148
148
149 class ReadlineNoRecord(object):
149 class ReadlineNoRecord(object):
150 """Context manager to execute some code, then reload readline history
150 """Context manager to execute some code, then reload readline history
151 so that interactive input to the code doesn't appear when pressing up."""
151 so that interactive input to the code doesn't appear when pressing up."""
152 def __init__(self, shell):
152 def __init__(self, shell):
153 self.shell = shell
153 self.shell = shell
154 self._nested_level = 0
154 self._nested_level = 0
155
155
156 def __enter__(self):
156 def __enter__(self):
157 if self._nested_level == 0:
157 if self._nested_level == 0:
158 try:
158 try:
159 self.orig_length = self.current_length()
159 self.orig_length = self.current_length()
160 self.readline_tail = self.get_readline_tail()
160 self.readline_tail = self.get_readline_tail()
161 except (AttributeError, IndexError): # Can fail with pyreadline
161 except (AttributeError, IndexError): # Can fail with pyreadline
162 self.orig_length, self.readline_tail = 999999, []
162 self.orig_length, self.readline_tail = 999999, []
163 self._nested_level += 1
163 self._nested_level += 1
164
164
165 def __exit__(self, type, value, traceback):
165 def __exit__(self, type, value, traceback):
166 self._nested_level -= 1
166 self._nested_level -= 1
167 if self._nested_level == 0:
167 if self._nested_level == 0:
168 # Try clipping the end if it's got longer
168 # Try clipping the end if it's got longer
169 try:
169 try:
170 e = self.current_length() - self.orig_length
170 e = self.current_length() - self.orig_length
171 if e > 0:
171 if e > 0:
172 for _ in range(e):
172 for _ in range(e):
173 self.shell.readline.remove_history_item(self.orig_length)
173 self.shell.readline.remove_history_item(self.orig_length)
174
174
175 # If it still doesn't match, just reload readline history.
175 # If it still doesn't match, just reload readline history.
176 if self.current_length() != self.orig_length \
176 if self.current_length() != self.orig_length \
177 or self.get_readline_tail() != self.readline_tail:
177 or self.get_readline_tail() != self.readline_tail:
178 self.shell.refill_readline_hist()
178 self.shell.refill_readline_hist()
179 except (AttributeError, IndexError):
179 except (AttributeError, IndexError):
180 pass
180 pass
181 # Returning False will cause exceptions to propagate
181 # Returning False will cause exceptions to propagate
182 return False
182 return False
183
183
184 def current_length(self):
184 def current_length(self):
185 return self.shell.readline.get_current_history_length()
185 return self.shell.readline.get_current_history_length()
186
186
187 def get_readline_tail(self, n=10):
187 def get_readline_tail(self, n=10):
188 """Get the last n items in readline history."""
188 """Get the last n items in readline history."""
189 end = self.shell.readline.get_current_history_length() + 1
189 end = self.shell.readline.get_current_history_length() + 1
190 start = max(end-n, 1)
190 start = max(end-n, 1)
191 ghi = self.shell.readline.get_history_item
191 ghi = self.shell.readline.get_history_item
192 return [ghi(x) for x in range(start, end)]
192 return [ghi(x) for x in range(start, end)]
193
193
194 #-----------------------------------------------------------------------------
194 #-----------------------------------------------------------------------------
195 # Main IPython class
195 # Main IPython class
196 #-----------------------------------------------------------------------------
196 #-----------------------------------------------------------------------------
197
197
198 class InteractiveShell(SingletonConfigurable):
198 class InteractiveShell(SingletonConfigurable):
199 """An enhanced, interactive shell for Python."""
199 """An enhanced, interactive shell for Python."""
200
200
201 _instance = None
201 _instance = None
202
202
203 autocall = Enum((0,1,2), default_value=0, config=True, help=
203 autocall = Enum((0,1,2), default_value=0, config=True, help=
204 """
204 """
205 Make IPython automatically call any callable object even if you didn't
205 Make IPython automatically call any callable object even if you didn't
206 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
206 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
207 automatically. The value can be '0' to disable the feature, '1' for
207 automatically. The value can be '0' to disable the feature, '1' for
208 'smart' autocall, where it is not applied if there are no more
208 'smart' autocall, where it is not applied if there are no more
209 arguments on the line, and '2' for 'full' autocall, where all callable
209 arguments on the line, and '2' for 'full' autocall, where all callable
210 objects are automatically called (even if no arguments are present).
210 objects are automatically called (even if no arguments are present).
211 """
211 """
212 )
212 )
213 # TODO: remove all autoindent logic and put into frontends.
213 # TODO: remove all autoindent logic and put into frontends.
214 # We can't do this yet because even runlines uses the autoindent.
214 # We can't do this yet because even runlines uses the autoindent.
215 autoindent = CBool(True, config=True, help=
215 autoindent = CBool(True, config=True, help=
216 """
216 """
217 Autoindent IPython code entered interactively.
217 Autoindent IPython code entered interactively.
218 """
218 """
219 )
219 )
220 automagic = CBool(True, config=True, help=
220 automagic = CBool(True, config=True, help=
221 """
221 """
222 Enable magic commands to be called without the leading %.
222 Enable magic commands to be called without the leading %.
223 """
223 """
224 )
224 )
225 cache_size = Integer(1000, config=True, help=
225 cache_size = Integer(1000, config=True, help=
226 """
226 """
227 Set the size of the output cache. The default is 1000, you can
227 Set the size of the output cache. The default is 1000, you can
228 change it permanently in your config file. Setting it to 0 completely
228 change it permanently in your config file. Setting it to 0 completely
229 disables the caching system, and the minimum value accepted is 20 (if
229 disables the caching system, and the minimum value accepted is 20 (if
230 you provide a value less than 20, it is reset to 0 and a warning is
230 you provide a value less than 20, it is reset to 0 and a warning is
231 issued). This limit is defined because otherwise you'll spend more
231 issued). This limit is defined because otherwise you'll spend more
232 time re-flushing a too small cache than working
232 time re-flushing a too small cache than working
233 """
233 """
234 )
234 )
235 color_info = CBool(True, config=True, help=
235 color_info = CBool(True, config=True, help=
236 """
236 """
237 Use colors for displaying information about objects. Because this
237 Use colors for displaying information about objects. Because this
238 information is passed through a pager (like 'less'), and some pagers
238 information is passed through a pager (like 'less'), and some pagers
239 get confused with color codes, this capability can be turned off.
239 get confused with color codes, this capability can be turned off.
240 """
240 """
241 )
241 )
242 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
242 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
243 default_value=get_default_colors(), config=True,
243 default_value=get_default_colors(), config=True,
244 help="Set the color scheme (NoColor, Linux, or LightBG)."
244 help="Set the color scheme (NoColor, Linux, or LightBG)."
245 )
245 )
246 colors_force = CBool(False, help=
246 colors_force = CBool(False, help=
247 """
247 """
248 Force use of ANSI color codes, regardless of OS and readline
248 Force use of ANSI color codes, regardless of OS and readline
249 availability.
249 availability.
250 """
250 """
251 # FIXME: This is essentially a hack to allow ZMQShell to show colors
251 # FIXME: This is essentially a hack to allow ZMQShell to show colors
252 # without readline on Win32. When the ZMQ formatting system is
252 # without readline on Win32. When the ZMQ formatting system is
253 # refactored, this should be removed.
253 # refactored, this should be removed.
254 )
254 )
255 debug = CBool(False, config=True)
255 debug = CBool(False, config=True)
256 deep_reload = CBool(False, config=True, help=
256 deep_reload = CBool(False, config=True, help=
257 """
257 """
258 Enable deep (recursive) reloading by default. IPython can use the
258 Enable deep (recursive) reloading by default. IPython can use the
259 deep_reload module which reloads changes in modules recursively (it
259 deep_reload module which reloads changes in modules recursively (it
260 replaces the reload() function, so you don't need to change anything to
260 replaces the reload() function, so you don't need to change anything to
261 use it). deep_reload() forces a full reload of modules whose code may
261 use it). deep_reload() forces a full reload of modules whose code may
262 have changed, which the default reload() function does not. When
262 have changed, which the default reload() function does not. When
263 deep_reload is off, IPython will use the normal reload(), but
263 deep_reload is off, IPython will use the normal reload(), but
264 deep_reload will still be available as dreload().
264 deep_reload will still be available as dreload().
265 """
265 """
266 )
266 )
267 disable_failing_post_execute = CBool(False, config=True,
267 disable_failing_post_execute = CBool(False, config=True,
268 help="Don't call post-execute functions that have failed in the past."
268 help="Don't call post-execute functions that have failed in the past."
269 )
269 )
270 display_formatter = Instance(DisplayFormatter)
270 display_formatter = Instance(DisplayFormatter)
271 displayhook_class = Type(DisplayHook)
271 displayhook_class = Type(DisplayHook)
272 display_pub_class = Type(DisplayPublisher)
272 display_pub_class = Type(DisplayPublisher)
273 data_pub_class = None
273 data_pub_class = None
274
274
275 exit_now = CBool(False)
275 exit_now = CBool(False)
276 exiter = Instance(ExitAutocall)
276 exiter = Instance(ExitAutocall)
277 def _exiter_default(self):
277 def _exiter_default(self):
278 return ExitAutocall(self)
278 return ExitAutocall(self)
279 # Monotonically increasing execution counter
279 # Monotonically increasing execution counter
280 execution_count = Integer(1)
280 execution_count = Integer(1)
281 filename = Unicode("<ipython console>")
281 filename = Unicode("<ipython console>")
282 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
282 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
283
283
284 # Input splitter, to split entire cells of input into either individual
284 # Input splitter, to split entire cells of input into either individual
285 # interactive statements or whole blocks.
285 # interactive statements or whole blocks.
286 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
286 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
287 (), {})
287 (), {})
288 logstart = CBool(False, config=True, help=
288 logstart = CBool(False, config=True, help=
289 """
289 """
290 Start logging to the default log file.
290 Start logging to the default log file.
291 """
291 """
292 )
292 )
293 logfile = Unicode('', config=True, help=
293 logfile = Unicode('', config=True, help=
294 """
294 """
295 The name of the logfile to use.
295 The name of the logfile to use.
296 """
296 """
297 )
297 )
298 logappend = Unicode('', config=True, help=
298 logappend = Unicode('', config=True, help=
299 """
299 """
300 Start logging to the given file in append mode.
300 Start logging to the given file in append mode.
301 """
301 """
302 )
302 )
303 object_info_string_level = Enum((0,1,2), default_value=0,
303 object_info_string_level = Enum((0,1,2), default_value=0,
304 config=True)
304 config=True)
305 pdb = CBool(False, config=True, help=
305 pdb = CBool(False, config=True, help=
306 """
306 """
307 Automatically call the pdb debugger after every exception.
307 Automatically call the pdb debugger after every exception.
308 """
308 """
309 )
309 )
310 multiline_history = CBool(sys.platform != 'win32', config=True,
310 multiline_history = CBool(sys.platform != 'win32', config=True,
311 help="Save multi-line entries as one entry in readline history"
311 help="Save multi-line entries as one entry in readline history"
312 )
312 )
313
313
314 # deprecated prompt traits:
314 # deprecated prompt traits:
315
315
316 prompt_in1 = Unicode('In [\\#]: ', config=True,
316 prompt_in1 = Unicode('In [\\#]: ', config=True,
317 help="Deprecated, use PromptManager.in_template")
317 help="Deprecated, use PromptManager.in_template")
318 prompt_in2 = Unicode(' .\\D.: ', config=True,
318 prompt_in2 = Unicode(' .\\D.: ', config=True,
319 help="Deprecated, use PromptManager.in2_template")
319 help="Deprecated, use PromptManager.in2_template")
320 prompt_out = Unicode('Out[\\#]: ', config=True,
320 prompt_out = Unicode('Out[\\#]: ', config=True,
321 help="Deprecated, use PromptManager.out_template")
321 help="Deprecated, use PromptManager.out_template")
322 prompts_pad_left = CBool(True, config=True,
322 prompts_pad_left = CBool(True, config=True,
323 help="Deprecated, use PromptManager.justify")
323 help="Deprecated, use PromptManager.justify")
324
324
325 def _prompt_trait_changed(self, name, old, new):
325 def _prompt_trait_changed(self, name, old, new):
326 table = {
326 table = {
327 'prompt_in1' : 'in_template',
327 'prompt_in1' : 'in_template',
328 'prompt_in2' : 'in2_template',
328 'prompt_in2' : 'in2_template',
329 'prompt_out' : 'out_template',
329 'prompt_out' : 'out_template',
330 'prompts_pad_left' : 'justify',
330 'prompts_pad_left' : 'justify',
331 }
331 }
332 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}\n".format(
332 warn("InteractiveShell.{name} is deprecated, use PromptManager.{newname}\n".format(
333 name=name, newname=table[name])
333 name=name, newname=table[name])
334 )
334 )
335 # protect against weird cases where self.config may not exist:
335 # protect against weird cases where self.config may not exist:
336 if self.config is not None:
336 if self.config is not None:
337 # propagate to corresponding PromptManager trait
337 # propagate to corresponding PromptManager trait
338 setattr(self.config.PromptManager, table[name], new)
338 setattr(self.config.PromptManager, table[name], new)
339
339
340 _prompt_in1_changed = _prompt_trait_changed
340 _prompt_in1_changed = _prompt_trait_changed
341 _prompt_in2_changed = _prompt_trait_changed
341 _prompt_in2_changed = _prompt_trait_changed
342 _prompt_out_changed = _prompt_trait_changed
342 _prompt_out_changed = _prompt_trait_changed
343 _prompt_pad_left_changed = _prompt_trait_changed
343 _prompt_pad_left_changed = _prompt_trait_changed
344
344
345 show_rewritten_input = CBool(True, config=True,
345 show_rewritten_input = CBool(True, config=True,
346 help="Show rewritten input, e.g. for autocall."
346 help="Show rewritten input, e.g. for autocall."
347 )
347 )
348
348
349 quiet = CBool(False, config=True)
349 quiet = CBool(False, config=True)
350
350
351 history_length = Integer(10000, config=True)
351 history_length = Integer(10000, config=True)
352
352
353 # The readline stuff will eventually be moved to the terminal subclass
353 # The readline stuff will eventually be moved to the terminal subclass
354 # but for now, we can't do that as readline is welded in everywhere.
354 # but for now, we can't do that as readline is welded in everywhere.
355 readline_use = CBool(True, config=True)
355 readline_use = CBool(True, config=True)
356 readline_remove_delims = Unicode('-/~', config=True)
356 readline_remove_delims = Unicode('-/~', config=True)
357 # don't use \M- bindings by default, because they
357 # don't use \M- bindings by default, because they
358 # conflict with 8-bit encodings. See gh-58,gh-88
358 # conflict with 8-bit encodings. See gh-58,gh-88
359 readline_parse_and_bind = List([
359 readline_parse_and_bind = List([
360 'tab: complete',
360 'tab: complete',
361 '"\C-l": clear-screen',
361 '"\C-l": clear-screen',
362 'set show-all-if-ambiguous on',
362 'set show-all-if-ambiguous on',
363 '"\C-o": tab-insert',
363 '"\C-o": tab-insert',
364 '"\C-r": reverse-search-history',
364 '"\C-r": reverse-search-history',
365 '"\C-s": forward-search-history',
365 '"\C-s": forward-search-history',
366 '"\C-p": history-search-backward',
366 '"\C-p": history-search-backward',
367 '"\C-n": history-search-forward',
367 '"\C-n": history-search-forward',
368 '"\e[A": history-search-backward',
368 '"\e[A": history-search-backward',
369 '"\e[B": history-search-forward',
369 '"\e[B": history-search-forward',
370 '"\C-k": kill-line',
370 '"\C-k": kill-line',
371 '"\C-u": unix-line-discard',
371 '"\C-u": unix-line-discard',
372 ], allow_none=False, config=True)
372 ], allow_none=False, config=True)
373
373
374 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
374 ast_node_interactivity = Enum(['all', 'last', 'last_expr', 'none'],
375 default_value='last_expr', config=True,
375 default_value='last_expr', config=True,
376 help="""
376 help="""
377 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
377 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
378 run interactively (displaying output from expressions).""")
378 run interactively (displaying output from expressions).""")
379
379
380 # TODO: this part of prompt management should be moved to the frontends.
380 # TODO: this part of prompt management should be moved to the frontends.
381 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
381 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
382 separate_in = SeparateUnicode('\n', config=True)
382 separate_in = SeparateUnicode('\n', config=True)
383 separate_out = SeparateUnicode('', config=True)
383 separate_out = SeparateUnicode('', config=True)
384 separate_out2 = SeparateUnicode('', config=True)
384 separate_out2 = SeparateUnicode('', config=True)
385 wildcards_case_sensitive = CBool(True, config=True)
385 wildcards_case_sensitive = CBool(True, config=True)
386 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
386 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
387 default_value='Context', config=True)
387 default_value='Context', config=True)
388
388
389 # Subcomponents of InteractiveShell
389 # Subcomponents of InteractiveShell
390 alias_manager = Instance('IPython.core.alias.AliasManager')
390 alias_manager = Instance('IPython.core.alias.AliasManager')
391 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
391 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
392 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
392 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
393 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
393 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
394 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
394 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
395 plugin_manager = Instance('IPython.core.plugin.PluginManager')
395 plugin_manager = Instance('IPython.core.plugin.PluginManager')
396 payload_manager = Instance('IPython.core.payload.PayloadManager')
396 payload_manager = Instance('IPython.core.payload.PayloadManager')
397 history_manager = Instance('IPython.core.history.HistoryManager')
397 history_manager = Instance('IPython.core.history.HistoryManager')
398 magics_manager = Instance('IPython.core.magic.MagicsManager')
398 magics_manager = Instance('IPython.core.magic.MagicsManager')
399
399
400 profile_dir = Instance('IPython.core.application.ProfileDir')
400 profile_dir = Instance('IPython.core.application.ProfileDir')
401 @property
401 @property
402 def profile(self):
402 def profile(self):
403 if self.profile_dir is not None:
403 if self.profile_dir is not None:
404 name = os.path.basename(self.profile_dir.location)
404 name = os.path.basename(self.profile_dir.location)
405 return name.replace('profile_','')
405 return name.replace('profile_','')
406
406
407
407
408 # Private interface
408 # Private interface
409 _post_execute = Instance(dict)
409 _post_execute = Instance(dict)
410
410
411 # Tracks any GUI loop loaded for pylab
411 # Tracks any GUI loop loaded for pylab
412 pylab_gui_select = None
412 pylab_gui_select = None
413
413
414 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
414 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
415 user_module=None, user_ns=None,
415 user_module=None, user_ns=None,
416 custom_exceptions=((), None)):
416 custom_exceptions=((), None)):
417
417
418 # This is where traits with a config_key argument are updated
418 # This is where traits with a config_key argument are updated
419 # from the values on config.
419 # from the values on config.
420 super(InteractiveShell, self).__init__(config=config)
420 super(InteractiveShell, self).__init__(config=config)
421 self.configurables = [self]
421 self.configurables = [self]
422
422
423 # These are relatively independent and stateless
423 # These are relatively independent and stateless
424 self.init_ipython_dir(ipython_dir)
424 self.init_ipython_dir(ipython_dir)
425 self.init_profile_dir(profile_dir)
425 self.init_profile_dir(profile_dir)
426 self.init_instance_attrs()
426 self.init_instance_attrs()
427 self.init_environment()
427 self.init_environment()
428
428
429 # Check if we're in a virtualenv, and set up sys.path.
429 # Check if we're in a virtualenv, and set up sys.path.
430 self.init_virtualenv()
430 self.init_virtualenv()
431
431
432 # Create namespaces (user_ns, user_global_ns, etc.)
432 # Create namespaces (user_ns, user_global_ns, etc.)
433 self.init_create_namespaces(user_module, user_ns)
433 self.init_create_namespaces(user_module, user_ns)
434 # This has to be done after init_create_namespaces because it uses
434 # This has to be done after init_create_namespaces because it uses
435 # something in self.user_ns, but before init_sys_modules, which
435 # something in self.user_ns, but before init_sys_modules, which
436 # is the first thing to modify sys.
436 # is the first thing to modify sys.
437 # TODO: When we override sys.stdout and sys.stderr before this class
437 # TODO: When we override sys.stdout and sys.stderr before this class
438 # is created, we are saving the overridden ones here. Not sure if this
438 # is created, we are saving the overridden ones here. Not sure if this
439 # is what we want to do.
439 # is what we want to do.
440 self.save_sys_module_state()
440 self.save_sys_module_state()
441 self.init_sys_modules()
441 self.init_sys_modules()
442
442
443 # While we're trying to have each part of the code directly access what
443 # While we're trying to have each part of the code directly access what
444 # it needs without keeping redundant references to objects, we have too
444 # it needs without keeping redundant references to objects, we have too
445 # much legacy code that expects ip.db to exist.
445 # much legacy code that expects ip.db to exist.
446 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
446 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
447
447
448 self.init_history()
448 self.init_history()
449 self.init_encoding()
449 self.init_encoding()
450 self.init_prefilter()
450 self.init_prefilter()
451
451
452 self.init_syntax_highlighting()
452 self.init_syntax_highlighting()
453 self.init_hooks()
453 self.init_hooks()
454 self.init_pushd_popd_magic()
454 self.init_pushd_popd_magic()
455 # self.init_traceback_handlers use to be here, but we moved it below
455 # self.init_traceback_handlers use to be here, but we moved it below
456 # because it and init_io have to come after init_readline.
456 # because it and init_io have to come after init_readline.
457 self.init_user_ns()
457 self.init_user_ns()
458 self.init_logger()
458 self.init_logger()
459 self.init_alias()
459 self.init_alias()
460 self.init_builtins()
460 self.init_builtins()
461
461
462 # The following was in post_config_initialization
462 # The following was in post_config_initialization
463 self.init_inspector()
463 self.init_inspector()
464 # init_readline() must come before init_io(), because init_io uses
464 # init_readline() must come before init_io(), because init_io uses
465 # readline related things.
465 # readline related things.
466 self.init_readline()
466 self.init_readline()
467 # We save this here in case user code replaces raw_input, but it needs
467 # We save this here in case user code replaces raw_input, but it needs
468 # to be after init_readline(), because PyPy's readline works by replacing
468 # to be after init_readline(), because PyPy's readline works by replacing
469 # raw_input.
469 # raw_input.
470 if py3compat.PY3:
470 if py3compat.PY3:
471 self.raw_input_original = input
471 self.raw_input_original = input
472 else:
472 else:
473 self.raw_input_original = raw_input
473 self.raw_input_original = raw_input
474 # init_completer must come after init_readline, because it needs to
474 # init_completer must come after init_readline, because it needs to
475 # know whether readline is present or not system-wide to configure the
475 # know whether readline is present or not system-wide to configure the
476 # completers, since the completion machinery can now operate
476 # completers, since the completion machinery can now operate
477 # independently of readline (e.g. over the network)
477 # independently of readline (e.g. over the network)
478 self.init_completer()
478 self.init_completer()
479 # TODO: init_io() needs to happen before init_traceback handlers
479 # TODO: init_io() needs to happen before init_traceback handlers
480 # because the traceback handlers hardcode the stdout/stderr streams.
480 # because the traceback handlers hardcode the stdout/stderr streams.
481 # This logic in in debugger.Pdb and should eventually be changed.
481 # This logic in in debugger.Pdb and should eventually be changed.
482 self.init_io()
482 self.init_io()
483 self.init_traceback_handlers(custom_exceptions)
483 self.init_traceback_handlers(custom_exceptions)
484 self.init_prompts()
484 self.init_prompts()
485 self.init_display_formatter()
485 self.init_display_formatter()
486 self.init_display_pub()
486 self.init_display_pub()
487 self.init_data_pub()
487 self.init_data_pub()
488 self.init_displayhook()
488 self.init_displayhook()
489 self.init_reload_doctest()
489 self.init_reload_doctest()
490 self.init_latextool()
490 self.init_latextool()
491 self.init_magics()
491 self.init_magics()
492 self.init_logstart()
492 self.init_logstart()
493 self.init_pdb()
493 self.init_pdb()
494 self.init_extension_manager()
494 self.init_extension_manager()
495 self.init_plugin_manager()
495 self.init_plugin_manager()
496 self.init_payload()
496 self.init_payload()
497 self.hooks.late_startup_hook()
497 self.hooks.late_startup_hook()
498 atexit.register(self.atexit_operations)
498 atexit.register(self.atexit_operations)
499
499
500 def get_ipython(self):
500 def get_ipython(self):
501 """Return the currently running IPython instance."""
501 """Return the currently running IPython instance."""
502 return self
502 return self
503
503
504 #-------------------------------------------------------------------------
504 #-------------------------------------------------------------------------
505 # Trait changed handlers
505 # Trait changed handlers
506 #-------------------------------------------------------------------------
506 #-------------------------------------------------------------------------
507
507
508 def _ipython_dir_changed(self, name, new):
508 def _ipython_dir_changed(self, name, new):
509 if not os.path.isdir(new):
509 if not os.path.isdir(new):
510 os.makedirs(new, mode = 0777)
510 os.makedirs(new, mode = 0777)
511
511
512 def set_autoindent(self,value=None):
512 def set_autoindent(self,value=None):
513 """Set the autoindent flag, checking for readline support.
513 """Set the autoindent flag, checking for readline support.
514
514
515 If called with no arguments, it acts as a toggle."""
515 If called with no arguments, it acts as a toggle."""
516
516
517 if value != 0 and not self.has_readline:
517 if value != 0 and not self.has_readline:
518 if os.name == 'posix':
518 if os.name == 'posix':
519 warn("The auto-indent feature requires the readline library")
519 warn("The auto-indent feature requires the readline library")
520 self.autoindent = 0
520 self.autoindent = 0
521 return
521 return
522 if value is None:
522 if value is None:
523 self.autoindent = not self.autoindent
523 self.autoindent = not self.autoindent
524 else:
524 else:
525 self.autoindent = value
525 self.autoindent = value
526
526
527 #-------------------------------------------------------------------------
527 #-------------------------------------------------------------------------
528 # init_* methods called by __init__
528 # init_* methods called by __init__
529 #-------------------------------------------------------------------------
529 #-------------------------------------------------------------------------
530
530
531 def init_ipython_dir(self, ipython_dir):
531 def init_ipython_dir(self, ipython_dir):
532 if ipython_dir is not None:
532 if ipython_dir is not None:
533 self.ipython_dir = ipython_dir
533 self.ipython_dir = ipython_dir
534 return
534 return
535
535
536 self.ipython_dir = get_ipython_dir()
536 self.ipython_dir = get_ipython_dir()
537
537
538 def init_profile_dir(self, profile_dir):
538 def init_profile_dir(self, profile_dir):
539 if profile_dir is not None:
539 if profile_dir is not None:
540 self.profile_dir = profile_dir
540 self.profile_dir = profile_dir
541 return
541 return
542 self.profile_dir =\
542 self.profile_dir =\
543 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
543 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
544
544
545 def init_instance_attrs(self):
545 def init_instance_attrs(self):
546 self.more = False
546 self.more = False
547
547
548 # command compiler
548 # command compiler
549 self.compile = CachingCompiler()
549 self.compile = CachingCompiler()
550
550
551 # Make an empty namespace, which extension writers can rely on both
551 # Make an empty namespace, which extension writers can rely on both
552 # existing and NEVER being used by ipython itself. This gives them a
552 # existing and NEVER being used by ipython itself. This gives them a
553 # convenient location for storing additional information and state
553 # convenient location for storing additional information and state
554 # their extensions may require, without fear of collisions with other
554 # their extensions may require, without fear of collisions with other
555 # ipython names that may develop later.
555 # ipython names that may develop later.
556 self.meta = Struct()
556 self.meta = Struct()
557
557
558 # Temporary files used for various purposes. Deleted at exit.
558 # Temporary files used for various purposes. Deleted at exit.
559 self.tempfiles = []
559 self.tempfiles = []
560
560
561 # Keep track of readline usage (later set by init_readline)
561 # Keep track of readline usage (later set by init_readline)
562 self.has_readline = False
562 self.has_readline = False
563
563
564 # keep track of where we started running (mainly for crash post-mortem)
564 # keep track of where we started running (mainly for crash post-mortem)
565 # This is not being used anywhere currently.
565 # This is not being used anywhere currently.
566 self.starting_dir = os.getcwdu()
566 self.starting_dir = os.getcwdu()
567
567
568 # Indentation management
568 # Indentation management
569 self.indent_current_nsp = 0
569 self.indent_current_nsp = 0
570
570
571 # Dict to track post-execution functions that have been registered
571 # Dict to track post-execution functions that have been registered
572 self._post_execute = {}
572 self._post_execute = {}
573
573
574 def init_environment(self):
574 def init_environment(self):
575 """Any changes we need to make to the user's environment."""
575 """Any changes we need to make to the user's environment."""
576 pass
576 pass
577
577
578 def init_encoding(self):
578 def init_encoding(self):
579 # Get system encoding at startup time. Certain terminals (like Emacs
579 # Get system encoding at startup time. Certain terminals (like Emacs
580 # under Win32 have it set to None, and we need to have a known valid
580 # under Win32 have it set to None, and we need to have a known valid
581 # encoding to use in the raw_input() method
581 # encoding to use in the raw_input() method
582 try:
582 try:
583 self.stdin_encoding = sys.stdin.encoding or 'ascii'
583 self.stdin_encoding = sys.stdin.encoding or 'ascii'
584 except AttributeError:
584 except AttributeError:
585 self.stdin_encoding = 'ascii'
585 self.stdin_encoding = 'ascii'
586
586
587 def init_syntax_highlighting(self):
587 def init_syntax_highlighting(self):
588 # Python source parser/formatter for syntax highlighting
588 # Python source parser/formatter for syntax highlighting
589 pyformat = PyColorize.Parser().format
589 pyformat = PyColorize.Parser().format
590 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
590 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
591
591
592 def init_pushd_popd_magic(self):
592 def init_pushd_popd_magic(self):
593 # for pushd/popd management
593 # for pushd/popd management
594 self.home_dir = get_home_dir()
594 self.home_dir = get_home_dir()
595
595
596 self.dir_stack = []
596 self.dir_stack = []
597
597
598 def init_logger(self):
598 def init_logger(self):
599 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
599 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
600 logmode='rotate')
600 logmode='rotate')
601
601
602 def init_logstart(self):
602 def init_logstart(self):
603 """Initialize logging in case it was requested at the command line.
603 """Initialize logging in case it was requested at the command line.
604 """
604 """
605 if self.logappend:
605 if self.logappend:
606 self.magic('logstart %s append' % self.logappend)
606 self.magic('logstart %s append' % self.logappend)
607 elif self.logfile:
607 elif self.logfile:
608 self.magic('logstart %s' % self.logfile)
608 self.magic('logstart %s' % self.logfile)
609 elif self.logstart:
609 elif self.logstart:
610 self.magic('logstart')
610 self.magic('logstart')
611
611
612 def init_builtins(self):
612 def init_builtins(self):
613 # A single, static flag that we set to True. Its presence indicates
613 # A single, static flag that we set to True. Its presence indicates
614 # that an IPython shell has been created, and we make no attempts at
614 # that an IPython shell has been created, and we make no attempts at
615 # removing on exit or representing the existence of more than one
615 # removing on exit or representing the existence of more than one
616 # IPython at a time.
616 # IPython at a time.
617 builtin_mod.__dict__['__IPYTHON__'] = True
617 builtin_mod.__dict__['__IPYTHON__'] = True
618
618
619 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
619 # In 0.11 we introduced '__IPYTHON__active' as an integer we'd try to
620 # manage on enter/exit, but with all our shells it's virtually
620 # manage on enter/exit, but with all our shells it's virtually
621 # impossible to get all the cases right. We're leaving the name in for
621 # impossible to get all the cases right. We're leaving the name in for
622 # those who adapted their codes to check for this flag, but will
622 # those who adapted their codes to check for this flag, but will
623 # eventually remove it after a few more releases.
623 # eventually remove it after a few more releases.
624 builtin_mod.__dict__['__IPYTHON__active'] = \
624 builtin_mod.__dict__['__IPYTHON__active'] = \
625 'Deprecated, check for __IPYTHON__'
625 'Deprecated, check for __IPYTHON__'
626
626
627 self.builtin_trap = BuiltinTrap(shell=self)
627 self.builtin_trap = BuiltinTrap(shell=self)
628
628
629 def init_inspector(self):
629 def init_inspector(self):
630 # Object inspector
630 # Object inspector
631 self.inspector = oinspect.Inspector(oinspect.InspectColors,
631 self.inspector = oinspect.Inspector(oinspect.InspectColors,
632 PyColorize.ANSICodeColors,
632 PyColorize.ANSICodeColors,
633 'NoColor',
633 'NoColor',
634 self.object_info_string_level)
634 self.object_info_string_level)
635
635
636 def init_io(self):
636 def init_io(self):
637 # This will just use sys.stdout and sys.stderr. If you want to
637 # This will just use sys.stdout and sys.stderr. If you want to
638 # override sys.stdout and sys.stderr themselves, you need to do that
638 # override sys.stdout and sys.stderr themselves, you need to do that
639 # *before* instantiating this class, because io holds onto
639 # *before* instantiating this class, because io holds onto
640 # references to the underlying streams.
640 # references to the underlying streams.
641 if sys.platform == 'win32' and self.has_readline:
641 if sys.platform == 'win32' and self.has_readline:
642 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
642 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
643 else:
643 else:
644 io.stdout = io.IOStream(sys.stdout)
644 io.stdout = io.IOStream(sys.stdout)
645 io.stderr = io.IOStream(sys.stderr)
645 io.stderr = io.IOStream(sys.stderr)
646
646
647 def init_prompts(self):
647 def init_prompts(self):
648 self.prompt_manager = PromptManager(shell=self, config=self.config)
648 self.prompt_manager = PromptManager(shell=self, config=self.config)
649 self.configurables.append(self.prompt_manager)
649 self.configurables.append(self.prompt_manager)
650 # Set system prompts, so that scripts can decide if they are running
650 # Set system prompts, so that scripts can decide if they are running
651 # interactively.
651 # interactively.
652 sys.ps1 = 'In : '
652 sys.ps1 = 'In : '
653 sys.ps2 = '...: '
653 sys.ps2 = '...: '
654 sys.ps3 = 'Out: '
654 sys.ps3 = 'Out: '
655
655
656 def init_display_formatter(self):
656 def init_display_formatter(self):
657 self.display_formatter = DisplayFormatter(config=self.config)
657 self.display_formatter = DisplayFormatter(config=self.config)
658 self.configurables.append(self.display_formatter)
658 self.configurables.append(self.display_formatter)
659
659
660 def init_display_pub(self):
660 def init_display_pub(self):
661 self.display_pub = self.display_pub_class(config=self.config)
661 self.display_pub = self.display_pub_class(config=self.config)
662 self.configurables.append(self.display_pub)
662 self.configurables.append(self.display_pub)
663
663
664 def init_data_pub(self):
664 def init_data_pub(self):
665 if not self.data_pub_class:
665 if not self.data_pub_class:
666 self.data_pub = None
666 self.data_pub = None
667 return
667 return
668 self.data_pub = self.data_pub_class(config=self.config)
668 self.data_pub = self.data_pub_class(config=self.config)
669 self.configurables.append(self.data_pub)
669 self.configurables.append(self.data_pub)
670
670
671 def init_displayhook(self):
671 def init_displayhook(self):
672 # Initialize displayhook, set in/out prompts and printing system
672 # Initialize displayhook, set in/out prompts and printing system
673 self.displayhook = self.displayhook_class(
673 self.displayhook = self.displayhook_class(
674 config=self.config,
674 config=self.config,
675 shell=self,
675 shell=self,
676 cache_size=self.cache_size,
676 cache_size=self.cache_size,
677 )
677 )
678 self.configurables.append(self.displayhook)
678 self.configurables.append(self.displayhook)
679 # This is a context manager that installs/revmoes the displayhook at
679 # This is a context manager that installs/revmoes the displayhook at
680 # the appropriate time.
680 # the appropriate time.
681 self.display_trap = DisplayTrap(hook=self.displayhook)
681 self.display_trap = DisplayTrap(hook=self.displayhook)
682
682
683 def init_reload_doctest(self):
683 def init_reload_doctest(self):
684 # Do a proper resetting of doctest, including the necessary displayhook
684 # Do a proper resetting of doctest, including the necessary displayhook
685 # monkeypatching
685 # monkeypatching
686 try:
686 try:
687 doctest_reload()
687 doctest_reload()
688 except ImportError:
688 except ImportError:
689 warn("doctest module does not exist.")
689 warn("doctest module does not exist.")
690
690
691 def init_latextool(self):
691 def init_latextool(self):
692 """Configure LaTeXTool."""
692 """Configure LaTeXTool."""
693 cfg = LaTeXTool.instance(config=self.config)
693 cfg = LaTeXTool.instance(config=self.config)
694 if cfg not in self.configurables:
694 if cfg not in self.configurables:
695 self.configurables.append(cfg)
695 self.configurables.append(cfg)
696
696
697 def init_virtualenv(self):
697 def init_virtualenv(self):
698 """Add a virtualenv to sys.path so the user can import modules from it.
698 """Add a virtualenv to sys.path so the user can import modules from it.
699 This isn't perfect: it doesn't use the Python interpreter with which the
699 This isn't perfect: it doesn't use the Python interpreter with which the
700 virtualenv was built, and it ignores the --no-site-packages option. A
700 virtualenv was built, and it ignores the --no-site-packages option. A
701 warning will appear suggesting the user installs IPython in the
701 warning will appear suggesting the user installs IPython in the
702 virtualenv, but for many cases, it probably works well enough.
702 virtualenv, but for many cases, it probably works well enough.
703
703
704 Adapted from code snippets online.
704 Adapted from code snippets online.
705
705
706 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
706 http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv
707 """
707 """
708 if 'VIRTUAL_ENV' not in os.environ:
708 if 'VIRTUAL_ENV' not in os.environ:
709 # Not in a virtualenv
709 # Not in a virtualenv
710 return
710 return
711
711
712 if sys.executable.startswith(os.environ['VIRTUAL_ENV']):
712 if sys.executable.startswith(os.environ['VIRTUAL_ENV']):
713 # Running properly in the virtualenv, don't need to do anything
713 # Running properly in the virtualenv, don't need to do anything
714 return
714 return
715
715
716 warn("Attempting to work in a virtualenv. If you encounter problems, please "
716 warn("Attempting to work in a virtualenv. If you encounter problems, please "
717 "install IPython inside the virtualenv.\n")
717 "install IPython inside the virtualenv.\n")
718 if sys.platform == "win32":
718 if sys.platform == "win32":
719 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
719 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'Lib', 'site-packages')
720 else:
720 else:
721 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
721 virtual_env = os.path.join(os.environ['VIRTUAL_ENV'], 'lib',
722 'python%d.%d' % sys.version_info[:2], 'site-packages')
722 'python%d.%d' % sys.version_info[:2], 'site-packages')
723
723
724 import site
724 import site
725 sys.path.insert(0, virtual_env)
725 sys.path.insert(0, virtual_env)
726 site.addsitedir(virtual_env)
726 site.addsitedir(virtual_env)
727
727
728 #-------------------------------------------------------------------------
728 #-------------------------------------------------------------------------
729 # Things related to injections into the sys module
729 # Things related to injections into the sys module
730 #-------------------------------------------------------------------------
730 #-------------------------------------------------------------------------
731
731
732 def save_sys_module_state(self):
732 def save_sys_module_state(self):
733 """Save the state of hooks in the sys module.
733 """Save the state of hooks in the sys module.
734
734
735 This has to be called after self.user_module is created.
735 This has to be called after self.user_module is created.
736 """
736 """
737 self._orig_sys_module_state = {}
737 self._orig_sys_module_state = {}
738 self._orig_sys_module_state['stdin'] = sys.stdin
738 self._orig_sys_module_state['stdin'] = sys.stdin
739 self._orig_sys_module_state['stdout'] = sys.stdout
739 self._orig_sys_module_state['stdout'] = sys.stdout
740 self._orig_sys_module_state['stderr'] = sys.stderr
740 self._orig_sys_module_state['stderr'] = sys.stderr
741 self._orig_sys_module_state['excepthook'] = sys.excepthook
741 self._orig_sys_module_state['excepthook'] = sys.excepthook
742 self._orig_sys_modules_main_name = self.user_module.__name__
742 self._orig_sys_modules_main_name = self.user_module.__name__
743 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
743 self._orig_sys_modules_main_mod = sys.modules.get(self.user_module.__name__)
744
744
745 def restore_sys_module_state(self):
745 def restore_sys_module_state(self):
746 """Restore the state of the sys module."""
746 """Restore the state of the sys module."""
747 try:
747 try:
748 for k, v in self._orig_sys_module_state.iteritems():
748 for k, v in self._orig_sys_module_state.iteritems():
749 setattr(sys, k, v)
749 setattr(sys, k, v)
750 except AttributeError:
750 except AttributeError:
751 pass
751 pass
752 # Reset what what done in self.init_sys_modules
752 # Reset what what done in self.init_sys_modules
753 if self._orig_sys_modules_main_mod is not None:
753 if self._orig_sys_modules_main_mod is not None:
754 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
754 sys.modules[self._orig_sys_modules_main_name] = self._orig_sys_modules_main_mod
755
755
756 #-------------------------------------------------------------------------
756 #-------------------------------------------------------------------------
757 # Things related to hooks
757 # Things related to hooks
758 #-------------------------------------------------------------------------
758 #-------------------------------------------------------------------------
759
759
760 def init_hooks(self):
760 def init_hooks(self):
761 # hooks holds pointers used for user-side customizations
761 # hooks holds pointers used for user-side customizations
762 self.hooks = Struct()
762 self.hooks = Struct()
763
763
764 self.strdispatchers = {}
764 self.strdispatchers = {}
765
765
766 # Set all default hooks, defined in the IPython.hooks module.
766 # Set all default hooks, defined in the IPython.hooks module.
767 hooks = IPython.core.hooks
767 hooks = IPython.core.hooks
768 for hook_name in hooks.__all__:
768 for hook_name in hooks.__all__:
769 # default hooks have priority 100, i.e. low; user hooks should have
769 # default hooks have priority 100, i.e. low; user hooks should have
770 # 0-100 priority
770 # 0-100 priority
771 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
771 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
772
772
773 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
773 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
774 """set_hook(name,hook) -> sets an internal IPython hook.
774 """set_hook(name,hook) -> sets an internal IPython hook.
775
775
776 IPython exposes some of its internal API as user-modifiable hooks. By
776 IPython exposes some of its internal API as user-modifiable hooks. By
777 adding your function to one of these hooks, you can modify IPython's
777 adding your function to one of these hooks, you can modify IPython's
778 behavior to call at runtime your own routines."""
778 behavior to call at runtime your own routines."""
779
779
780 # At some point in the future, this should validate the hook before it
780 # At some point in the future, this should validate the hook before it
781 # accepts it. Probably at least check that the hook takes the number
781 # accepts it. Probably at least check that the hook takes the number
782 # of args it's supposed to.
782 # of args it's supposed to.
783
783
784 f = types.MethodType(hook,self)
784 f = types.MethodType(hook,self)
785
785
786 # check if the hook is for strdispatcher first
786 # check if the hook is for strdispatcher first
787 if str_key is not None:
787 if str_key is not None:
788 sdp = self.strdispatchers.get(name, StrDispatch())
788 sdp = self.strdispatchers.get(name, StrDispatch())
789 sdp.add_s(str_key, f, priority )
789 sdp.add_s(str_key, f, priority )
790 self.strdispatchers[name] = sdp
790 self.strdispatchers[name] = sdp
791 return
791 return
792 if re_key is not None:
792 if re_key is not None:
793 sdp = self.strdispatchers.get(name, StrDispatch())
793 sdp = self.strdispatchers.get(name, StrDispatch())
794 sdp.add_re(re.compile(re_key), f, priority )
794 sdp.add_re(re.compile(re_key), f, priority )
795 self.strdispatchers[name] = sdp
795 self.strdispatchers[name] = sdp
796 return
796 return
797
797
798 dp = getattr(self.hooks, name, None)
798 dp = getattr(self.hooks, name, None)
799 if name not in IPython.core.hooks.__all__:
799 if name not in IPython.core.hooks.__all__:
800 print("Warning! Hook '%s' is not one of %s" % \
800 print("Warning! Hook '%s' is not one of %s" % \
801 (name, IPython.core.hooks.__all__ ))
801 (name, IPython.core.hooks.__all__ ))
802 if not dp:
802 if not dp:
803 dp = IPython.core.hooks.CommandChainDispatcher()
803 dp = IPython.core.hooks.CommandChainDispatcher()
804
804
805 try:
805 try:
806 dp.add(f,priority)
806 dp.add(f,priority)
807 except AttributeError:
807 except AttributeError:
808 # it was not commandchain, plain old func - replace
808 # it was not commandchain, plain old func - replace
809 dp = f
809 dp = f
810
810
811 setattr(self.hooks,name, dp)
811 setattr(self.hooks,name, dp)
812
812
813 def register_post_execute(self, func):
813 def register_post_execute(self, func):
814 """Register a function for calling after code execution.
814 """Register a function for calling after code execution.
815 """
815 """
816 if not callable(func):
816 if not callable(func):
817 raise ValueError('argument %s must be callable' % func)
817 raise ValueError('argument %s must be callable' % func)
818 self._post_execute[func] = True
818 self._post_execute[func] = True
819
819
820 #-------------------------------------------------------------------------
820 #-------------------------------------------------------------------------
821 # Things related to the "main" module
821 # Things related to the "main" module
822 #-------------------------------------------------------------------------
822 #-------------------------------------------------------------------------
823
823
824 def new_main_mod(self,ns=None):
824 def new_main_mod(self,ns=None):
825 """Return a new 'main' module object for user code execution.
825 """Return a new 'main' module object for user code execution.
826 """
826 """
827 main_mod = self._user_main_module
827 main_mod = self._user_main_module
828 init_fakemod_dict(main_mod,ns)
828 init_fakemod_dict(main_mod,ns)
829 return main_mod
829 return main_mod
830
830
831 def cache_main_mod(self,ns,fname):
831 def cache_main_mod(self,ns,fname):
832 """Cache a main module's namespace.
832 """Cache a main module's namespace.
833
833
834 When scripts are executed via %run, we must keep a reference to the
834 When scripts are executed via %run, we must keep a reference to the
835 namespace of their __main__ module (a FakeModule instance) around so
835 namespace of their __main__ module (a FakeModule instance) around so
836 that Python doesn't clear it, rendering objects defined therein
836 that Python doesn't clear it, rendering objects defined therein
837 useless.
837 useless.
838
838
839 This method keeps said reference in a private dict, keyed by the
839 This method keeps said reference in a private dict, keyed by the
840 absolute path of the module object (which corresponds to the script
840 absolute path of the module object (which corresponds to the script
841 path). This way, for multiple executions of the same script we only
841 path). This way, for multiple executions of the same script we only
842 keep one copy of the namespace (the last one), thus preventing memory
842 keep one copy of the namespace (the last one), thus preventing memory
843 leaks from old references while allowing the objects from the last
843 leaks from old references while allowing the objects from the last
844 execution to be accessible.
844 execution to be accessible.
845
845
846 Note: we can not allow the actual FakeModule instances to be deleted,
846 Note: we can not allow the actual FakeModule instances to be deleted,
847 because of how Python tears down modules (it hard-sets all their
847 because of how Python tears down modules (it hard-sets all their
848 references to None without regard for reference counts). This method
848 references to None without regard for reference counts). This method
849 must therefore make a *copy* of the given namespace, to allow the
849 must therefore make a *copy* of the given namespace, to allow the
850 original module's __dict__ to be cleared and reused.
850 original module's __dict__ to be cleared and reused.
851
851
852
852
853 Parameters
853 Parameters
854 ----------
854 ----------
855 ns : a namespace (a dict, typically)
855 ns : a namespace (a dict, typically)
856
856
857 fname : str
857 fname : str
858 Filename associated with the namespace.
858 Filename associated with the namespace.
859
859
860 Examples
860 Examples
861 --------
861 --------
862
862
863 In [10]: import IPython
863 In [10]: import IPython
864
864
865 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
865 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
866
866
867 In [12]: IPython.__file__ in _ip._main_ns_cache
867 In [12]: IPython.__file__ in _ip._main_ns_cache
868 Out[12]: True
868 Out[12]: True
869 """
869 """
870 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
870 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
871
871
872 def clear_main_mod_cache(self):
872 def clear_main_mod_cache(self):
873 """Clear the cache of main modules.
873 """Clear the cache of main modules.
874
874
875 Mainly for use by utilities like %reset.
875 Mainly for use by utilities like %reset.
876
876
877 Examples
877 Examples
878 --------
878 --------
879
879
880 In [15]: import IPython
880 In [15]: import IPython
881
881
882 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
882 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
883
883
884 In [17]: len(_ip._main_ns_cache) > 0
884 In [17]: len(_ip._main_ns_cache) > 0
885 Out[17]: True
885 Out[17]: True
886
886
887 In [18]: _ip.clear_main_mod_cache()
887 In [18]: _ip.clear_main_mod_cache()
888
888
889 In [19]: len(_ip._main_ns_cache) == 0
889 In [19]: len(_ip._main_ns_cache) == 0
890 Out[19]: True
890 Out[19]: True
891 """
891 """
892 self._main_ns_cache.clear()
892 self._main_ns_cache.clear()
893
893
894 #-------------------------------------------------------------------------
894 #-------------------------------------------------------------------------
895 # Things related to debugging
895 # Things related to debugging
896 #-------------------------------------------------------------------------
896 #-------------------------------------------------------------------------
897
897
898 def init_pdb(self):
898 def init_pdb(self):
899 # Set calling of pdb on exceptions
899 # Set calling of pdb on exceptions
900 # self.call_pdb is a property
900 # self.call_pdb is a property
901 self.call_pdb = self.pdb
901 self.call_pdb = self.pdb
902
902
903 def _get_call_pdb(self):
903 def _get_call_pdb(self):
904 return self._call_pdb
904 return self._call_pdb
905
905
906 def _set_call_pdb(self,val):
906 def _set_call_pdb(self,val):
907
907
908 if val not in (0,1,False,True):
908 if val not in (0,1,False,True):
909 raise ValueError('new call_pdb value must be boolean')
909 raise ValueError('new call_pdb value must be boolean')
910
910
911 # store value in instance
911 # store value in instance
912 self._call_pdb = val
912 self._call_pdb = val
913
913
914 # notify the actual exception handlers
914 # notify the actual exception handlers
915 self.InteractiveTB.call_pdb = val
915 self.InteractiveTB.call_pdb = val
916
916
917 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
917 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
918 'Control auto-activation of pdb at exceptions')
918 'Control auto-activation of pdb at exceptions')
919
919
920 def debugger(self,force=False):
920 def debugger(self,force=False):
921 """Call the pydb/pdb debugger.
921 """Call the pydb/pdb debugger.
922
922
923 Keywords:
923 Keywords:
924
924
925 - force(False): by default, this routine checks the instance call_pdb
925 - force(False): by default, this routine checks the instance call_pdb
926 flag and does not actually invoke the debugger if the flag is false.
926 flag and does not actually invoke the debugger if the flag is false.
927 The 'force' option forces the debugger to activate even if the flag
927 The 'force' option forces the debugger to activate even if the flag
928 is false.
928 is false.
929 """
929 """
930
930
931 if not (force or self.call_pdb):
931 if not (force or self.call_pdb):
932 return
932 return
933
933
934 if not hasattr(sys,'last_traceback'):
934 if not hasattr(sys,'last_traceback'):
935 error('No traceback has been produced, nothing to debug.')
935 error('No traceback has been produced, nothing to debug.')
936 return
936 return
937
937
938 # use pydb if available
938 # use pydb if available
939 if debugger.has_pydb:
939 if debugger.has_pydb:
940 from pydb import pm
940 from pydb import pm
941 else:
941 else:
942 # fallback to our internal debugger
942 # fallback to our internal debugger
943 pm = lambda : self.InteractiveTB.debugger(force=True)
943 pm = lambda : self.InteractiveTB.debugger(force=True)
944
944
945 with self.readline_no_record:
945 with self.readline_no_record:
946 pm()
946 pm()
947
947
948 #-------------------------------------------------------------------------
948 #-------------------------------------------------------------------------
949 # Things related to IPython's various namespaces
949 # Things related to IPython's various namespaces
950 #-------------------------------------------------------------------------
950 #-------------------------------------------------------------------------
951 default_user_namespaces = True
951 default_user_namespaces = True
952
952
953 def init_create_namespaces(self, user_module=None, user_ns=None):
953 def init_create_namespaces(self, user_module=None, user_ns=None):
954 # Create the namespace where the user will operate. user_ns is
954 # Create the namespace where the user will operate. user_ns is
955 # normally the only one used, and it is passed to the exec calls as
955 # normally the only one used, and it is passed to the exec calls as
956 # the locals argument. But we do carry a user_global_ns namespace
956 # the locals argument. But we do carry a user_global_ns namespace
957 # given as the exec 'globals' argument, This is useful in embedding
957 # given as the exec 'globals' argument, This is useful in embedding
958 # situations where the ipython shell opens in a context where the
958 # situations where the ipython shell opens in a context where the
959 # distinction between locals and globals is meaningful. For
959 # distinction between locals and globals is meaningful. For
960 # non-embedded contexts, it is just the same object as the user_ns dict.
960 # non-embedded contexts, it is just the same object as the user_ns dict.
961
961
962 # FIXME. For some strange reason, __builtins__ is showing up at user
962 # FIXME. For some strange reason, __builtins__ is showing up at user
963 # level as a dict instead of a module. This is a manual fix, but I
963 # level as a dict instead of a module. This is a manual fix, but I
964 # should really track down where the problem is coming from. Alex
964 # should really track down where the problem is coming from. Alex
965 # Schmolck reported this problem first.
965 # Schmolck reported this problem first.
966
966
967 # A useful post by Alex Martelli on this topic:
967 # A useful post by Alex Martelli on this topic:
968 # Re: inconsistent value from __builtins__
968 # Re: inconsistent value from __builtins__
969 # Von: Alex Martelli <aleaxit@yahoo.com>
969 # Von: Alex Martelli <aleaxit@yahoo.com>
970 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
970 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
971 # Gruppen: comp.lang.python
971 # Gruppen: comp.lang.python
972
972
973 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
973 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
974 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
974 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
975 # > <type 'dict'>
975 # > <type 'dict'>
976 # > >>> print type(__builtins__)
976 # > >>> print type(__builtins__)
977 # > <type 'module'>
977 # > <type 'module'>
978 # > Is this difference in return value intentional?
978 # > Is this difference in return value intentional?
979
979
980 # Well, it's documented that '__builtins__' can be either a dictionary
980 # Well, it's documented that '__builtins__' can be either a dictionary
981 # or a module, and it's been that way for a long time. Whether it's
981 # or a module, and it's been that way for a long time. Whether it's
982 # intentional (or sensible), I don't know. In any case, the idea is
982 # intentional (or sensible), I don't know. In any case, the idea is
983 # that if you need to access the built-in namespace directly, you
983 # that if you need to access the built-in namespace directly, you
984 # should start with "import __builtin__" (note, no 's') which will
984 # should start with "import __builtin__" (note, no 's') which will
985 # definitely give you a module. Yeah, it's somewhat confusing:-(.
985 # definitely give you a module. Yeah, it's somewhat confusing:-(.
986
986
987 # These routines return a properly built module and dict as needed by
987 # These routines return a properly built module and dict as needed by
988 # the rest of the code, and can also be used by extension writers to
988 # the rest of the code, and can also be used by extension writers to
989 # generate properly initialized namespaces.
989 # generate properly initialized namespaces.
990 if (user_ns is not None) or (user_module is not None):
990 if (user_ns is not None) or (user_module is not None):
991 self.default_user_namespaces = False
991 self.default_user_namespaces = False
992 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
992 self.user_module, self.user_ns = self.prepare_user_module(user_module, user_ns)
993
993
994 # A record of hidden variables we have added to the user namespace, so
994 # A record of hidden variables we have added to the user namespace, so
995 # we can list later only variables defined in actual interactive use.
995 # we can list later only variables defined in actual interactive use.
996 self.user_ns_hidden = set()
996 self.user_ns_hidden = set()
997
997
998 # Now that FakeModule produces a real module, we've run into a nasty
998 # Now that FakeModule produces a real module, we've run into a nasty
999 # problem: after script execution (via %run), the module where the user
999 # problem: after script execution (via %run), the module where the user
1000 # code ran is deleted. Now that this object is a true module (needed
1000 # code ran is deleted. Now that this object is a true module (needed
1001 # so docetst and other tools work correctly), the Python module
1001 # so docetst and other tools work correctly), the Python module
1002 # teardown mechanism runs over it, and sets to None every variable
1002 # teardown mechanism runs over it, and sets to None every variable
1003 # present in that module. Top-level references to objects from the
1003 # present in that module. Top-level references to objects from the
1004 # script survive, because the user_ns is updated with them. However,
1004 # script survive, because the user_ns is updated with them. However,
1005 # calling functions defined in the script that use other things from
1005 # calling functions defined in the script that use other things from
1006 # the script will fail, because the function's closure had references
1006 # the script will fail, because the function's closure had references
1007 # to the original objects, which are now all None. So we must protect
1007 # to the original objects, which are now all None. So we must protect
1008 # these modules from deletion by keeping a cache.
1008 # these modules from deletion by keeping a cache.
1009 #
1009 #
1010 # To avoid keeping stale modules around (we only need the one from the
1010 # To avoid keeping stale modules around (we only need the one from the
1011 # last run), we use a dict keyed with the full path to the script, so
1011 # last run), we use a dict keyed with the full path to the script, so
1012 # only the last version of the module is held in the cache. Note,
1012 # only the last version of the module is held in the cache. Note,
1013 # however, that we must cache the module *namespace contents* (their
1013 # however, that we must cache the module *namespace contents* (their
1014 # __dict__). Because if we try to cache the actual modules, old ones
1014 # __dict__). Because if we try to cache the actual modules, old ones
1015 # (uncached) could be destroyed while still holding references (such as
1015 # (uncached) could be destroyed while still holding references (such as
1016 # those held by GUI objects that tend to be long-lived)>
1016 # those held by GUI objects that tend to be long-lived)>
1017 #
1017 #
1018 # The %reset command will flush this cache. See the cache_main_mod()
1018 # The %reset command will flush this cache. See the cache_main_mod()
1019 # and clear_main_mod_cache() methods for details on use.
1019 # and clear_main_mod_cache() methods for details on use.
1020
1020
1021 # This is the cache used for 'main' namespaces
1021 # This is the cache used for 'main' namespaces
1022 self._main_ns_cache = {}
1022 self._main_ns_cache = {}
1023 # And this is the single instance of FakeModule whose __dict__ we keep
1023 # And this is the single instance of FakeModule whose __dict__ we keep
1024 # copying and clearing for reuse on each %run
1024 # copying and clearing for reuse on each %run
1025 self._user_main_module = FakeModule()
1025 self._user_main_module = FakeModule()
1026
1026
1027 # A table holding all the namespaces IPython deals with, so that
1027 # A table holding all the namespaces IPython deals with, so that
1028 # introspection facilities can search easily.
1028 # introspection facilities can search easily.
1029 self.ns_table = {'user_global':self.user_module.__dict__,
1029 self.ns_table = {'user_global':self.user_module.__dict__,
1030 'user_local':self.user_ns,
1030 'user_local':self.user_ns,
1031 'builtin':builtin_mod.__dict__
1031 'builtin':builtin_mod.__dict__
1032 }
1032 }
1033
1033
1034 @property
1034 @property
1035 def user_global_ns(self):
1035 def user_global_ns(self):
1036 return self.user_module.__dict__
1036 return self.user_module.__dict__
1037
1037
1038 def prepare_user_module(self, user_module=None, user_ns=None):
1038 def prepare_user_module(self, user_module=None, user_ns=None):
1039 """Prepare the module and namespace in which user code will be run.
1039 """Prepare the module and namespace in which user code will be run.
1040
1040
1041 When IPython is started normally, both parameters are None: a new module
1041 When IPython is started normally, both parameters are None: a new module
1042 is created automatically, and its __dict__ used as the namespace.
1042 is created automatically, and its __dict__ used as the namespace.
1043
1043
1044 If only user_module is provided, its __dict__ is used as the namespace.
1044 If only user_module is provided, its __dict__ is used as the namespace.
1045 If only user_ns is provided, a dummy module is created, and user_ns
1045 If only user_ns is provided, a dummy module is created, and user_ns
1046 becomes the global namespace. If both are provided (as they may be
1046 becomes the global namespace. If both are provided (as they may be
1047 when embedding), user_ns is the local namespace, and user_module
1047 when embedding), user_ns is the local namespace, and user_module
1048 provides the global namespace.
1048 provides the global namespace.
1049
1049
1050 Parameters
1050 Parameters
1051 ----------
1051 ----------
1052 user_module : module, optional
1052 user_module : module, optional
1053 The current user module in which IPython is being run. If None,
1053 The current user module in which IPython is being run. If None,
1054 a clean module will be created.
1054 a clean module will be created.
1055 user_ns : dict, optional
1055 user_ns : dict, optional
1056 A namespace in which to run interactive commands.
1056 A namespace in which to run interactive commands.
1057
1057
1058 Returns
1058 Returns
1059 -------
1059 -------
1060 A tuple of user_module and user_ns, each properly initialised.
1060 A tuple of user_module and user_ns, each properly initialised.
1061 """
1061 """
1062 if user_module is None and user_ns is not None:
1062 if user_module is None and user_ns is not None:
1063 user_ns.setdefault("__name__", "__main__")
1063 user_ns.setdefault("__name__", "__main__")
1064 class DummyMod(object):
1064 class DummyMod(object):
1065 "A dummy module used for IPython's interactive namespace."
1065 "A dummy module used for IPython's interactive namespace."
1066 pass
1066 pass
1067 user_module = DummyMod()
1067 user_module = DummyMod()
1068 user_module.__dict__ = user_ns
1068 user_module.__dict__ = user_ns
1069
1069
1070 if user_module is None:
1070 if user_module is None:
1071 user_module = types.ModuleType("__main__",
1071 user_module = types.ModuleType("__main__",
1072 doc="Automatically created module for IPython interactive environment")
1072 doc="Automatically created module for IPython interactive environment")
1073
1073
1074 # We must ensure that __builtin__ (without the final 's') is always
1074 # We must ensure that __builtin__ (without the final 's') is always
1075 # available and pointing to the __builtin__ *module*. For more details:
1075 # available and pointing to the __builtin__ *module*. For more details:
1076 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1076 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1077 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1077 user_module.__dict__.setdefault('__builtin__', builtin_mod)
1078 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1078 user_module.__dict__.setdefault('__builtins__', builtin_mod)
1079
1079
1080 if user_ns is None:
1080 if user_ns is None:
1081 user_ns = user_module.__dict__
1081 user_ns = user_module.__dict__
1082
1082
1083 return user_module, user_ns
1083 return user_module, user_ns
1084
1084
1085 def init_sys_modules(self):
1085 def init_sys_modules(self):
1086 # We need to insert into sys.modules something that looks like a
1086 # We need to insert into sys.modules something that looks like a
1087 # module but which accesses the IPython namespace, for shelve and
1087 # module but which accesses the IPython namespace, for shelve and
1088 # pickle to work interactively. Normally they rely on getting
1088 # pickle to work interactively. Normally they rely on getting
1089 # everything out of __main__, but for embedding purposes each IPython
1089 # everything out of __main__, but for embedding purposes each IPython
1090 # instance has its own private namespace, so we can't go shoving
1090 # instance has its own private namespace, so we can't go shoving
1091 # everything into __main__.
1091 # everything into __main__.
1092
1092
1093 # note, however, that we should only do this for non-embedded
1093 # note, however, that we should only do this for non-embedded
1094 # ipythons, which really mimic the __main__.__dict__ with their own
1094 # ipythons, which really mimic the __main__.__dict__ with their own
1095 # namespace. Embedded instances, on the other hand, should not do
1095 # namespace. Embedded instances, on the other hand, should not do
1096 # this because they need to manage the user local/global namespaces
1096 # this because they need to manage the user local/global namespaces
1097 # only, but they live within a 'normal' __main__ (meaning, they
1097 # only, but they live within a 'normal' __main__ (meaning, they
1098 # shouldn't overtake the execution environment of the script they're
1098 # shouldn't overtake the execution environment of the script they're
1099 # embedded in).
1099 # embedded in).
1100
1100
1101 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1101 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1102 main_name = self.user_module.__name__
1102 main_name = self.user_module.__name__
1103 sys.modules[main_name] = self.user_module
1103 sys.modules[main_name] = self.user_module
1104
1104
1105 def init_user_ns(self):
1105 def init_user_ns(self):
1106 """Initialize all user-visible namespaces to their minimum defaults.
1106 """Initialize all user-visible namespaces to their minimum defaults.
1107
1107
1108 Certain history lists are also initialized here, as they effectively
1108 Certain history lists are also initialized here, as they effectively
1109 act as user namespaces.
1109 act as user namespaces.
1110
1110
1111 Notes
1111 Notes
1112 -----
1112 -----
1113 All data structures here are only filled in, they are NOT reset by this
1113 All data structures here are only filled in, they are NOT reset by this
1114 method. If they were not empty before, data will simply be added to
1114 method. If they were not empty before, data will simply be added to
1115 therm.
1115 therm.
1116 """
1116 """
1117 # This function works in two parts: first we put a few things in
1117 # This function works in two parts: first we put a few things in
1118 # user_ns, and we sync that contents into user_ns_hidden so that these
1118 # user_ns, and we sync that contents into user_ns_hidden so that these
1119 # initial variables aren't shown by %who. After the sync, we add the
1119 # initial variables aren't shown by %who. After the sync, we add the
1120 # rest of what we *do* want the user to see with %who even on a new
1120 # rest of what we *do* want the user to see with %who even on a new
1121 # session (probably nothing, so theye really only see their own stuff)
1121 # session (probably nothing, so theye really only see their own stuff)
1122
1122
1123 # The user dict must *always* have a __builtin__ reference to the
1123 # The user dict must *always* have a __builtin__ reference to the
1124 # Python standard __builtin__ namespace, which must be imported.
1124 # Python standard __builtin__ namespace, which must be imported.
1125 # This is so that certain operations in prompt evaluation can be
1125 # This is so that certain operations in prompt evaluation can be
1126 # reliably executed with builtins. Note that we can NOT use
1126 # reliably executed with builtins. Note that we can NOT use
1127 # __builtins__ (note the 's'), because that can either be a dict or a
1127 # __builtins__ (note the 's'), because that can either be a dict or a
1128 # module, and can even mutate at runtime, depending on the context
1128 # module, and can even mutate at runtime, depending on the context
1129 # (Python makes no guarantees on it). In contrast, __builtin__ is
1129 # (Python makes no guarantees on it). In contrast, __builtin__ is
1130 # always a module object, though it must be explicitly imported.
1130 # always a module object, though it must be explicitly imported.
1131
1131
1132 # For more details:
1132 # For more details:
1133 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1133 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1134 ns = dict()
1134 ns = dict()
1135
1135
1136 # Put 'help' in the user namespace
1136 # Put 'help' in the user namespace
1137 try:
1137 try:
1138 from site import _Helper
1138 from site import _Helper
1139 ns['help'] = _Helper()
1139 ns['help'] = _Helper()
1140 except ImportError:
1140 except ImportError:
1141 warn('help() not available - check site.py')
1141 warn('help() not available - check site.py')
1142
1142
1143 # make global variables for user access to the histories
1143 # make global variables for user access to the histories
1144 ns['_ih'] = self.history_manager.input_hist_parsed
1144 ns['_ih'] = self.history_manager.input_hist_parsed
1145 ns['_oh'] = self.history_manager.output_hist
1145 ns['_oh'] = self.history_manager.output_hist
1146 ns['_dh'] = self.history_manager.dir_hist
1146 ns['_dh'] = self.history_manager.dir_hist
1147
1147
1148 ns['_sh'] = shadowns
1148 ns['_sh'] = shadowns
1149
1149
1150 # user aliases to input and output histories. These shouldn't show up
1150 # user aliases to input and output histories. These shouldn't show up
1151 # in %who, as they can have very large reprs.
1151 # in %who, as they can have very large reprs.
1152 ns['In'] = self.history_manager.input_hist_parsed
1152 ns['In'] = self.history_manager.input_hist_parsed
1153 ns['Out'] = self.history_manager.output_hist
1153 ns['Out'] = self.history_manager.output_hist
1154
1154
1155 # Store myself as the public api!!!
1155 # Store myself as the public api!!!
1156 ns['get_ipython'] = self.get_ipython
1156 ns['get_ipython'] = self.get_ipython
1157
1157
1158 ns['exit'] = self.exiter
1158 ns['exit'] = self.exiter
1159 ns['quit'] = self.exiter
1159 ns['quit'] = self.exiter
1160
1160
1161 # Sync what we've added so far to user_ns_hidden so these aren't seen
1161 # Sync what we've added so far to user_ns_hidden so these aren't seen
1162 # by %who
1162 # by %who
1163 self.user_ns_hidden.update(ns)
1163 self.user_ns_hidden.update(ns)
1164
1164
1165 # Anything put into ns now would show up in %who. Think twice before
1165 # Anything put into ns now would show up in %who. Think twice before
1166 # putting anything here, as we really want %who to show the user their
1166 # putting anything here, as we really want %who to show the user their
1167 # stuff, not our variables.
1167 # stuff, not our variables.
1168
1168
1169 # Finally, update the real user's namespace
1169 # Finally, update the real user's namespace
1170 self.user_ns.update(ns)
1170 self.user_ns.update(ns)
1171
1171
1172 @property
1172 @property
1173 def all_ns_refs(self):
1173 def all_ns_refs(self):
1174 """Get a list of references to all the namespace dictionaries in which
1174 """Get a list of references to all the namespace dictionaries in which
1175 IPython might store a user-created object.
1175 IPython might store a user-created object.
1176
1176
1177 Note that this does not include the displayhook, which also caches
1177 Note that this does not include the displayhook, which also caches
1178 objects from the output."""
1178 objects from the output."""
1179 return [self.user_ns, self.user_global_ns,
1179 return [self.user_ns, self.user_global_ns,
1180 self._user_main_module.__dict__] + self._main_ns_cache.values()
1180 self._user_main_module.__dict__] + self._main_ns_cache.values()
1181
1181
1182 def reset(self, new_session=True):
1182 def reset(self, new_session=True):
1183 """Clear all internal namespaces, and attempt to release references to
1183 """Clear all internal namespaces, and attempt to release references to
1184 user objects.
1184 user objects.
1185
1185
1186 If new_session is True, a new history session will be opened.
1186 If new_session is True, a new history session will be opened.
1187 """
1187 """
1188 # Clear histories
1188 # Clear histories
1189 self.history_manager.reset(new_session)
1189 self.history_manager.reset(new_session)
1190 # Reset counter used to index all histories
1190 # Reset counter used to index all histories
1191 if new_session:
1191 if new_session:
1192 self.execution_count = 1
1192 self.execution_count = 1
1193
1193
1194 # Flush cached output items
1194 # Flush cached output items
1195 if self.displayhook.do_full_cache:
1195 if self.displayhook.do_full_cache:
1196 self.displayhook.flush()
1196 self.displayhook.flush()
1197
1197
1198 # The main execution namespaces must be cleared very carefully,
1198 # The main execution namespaces must be cleared very carefully,
1199 # skipping the deletion of the builtin-related keys, because doing so
1199 # skipping the deletion of the builtin-related keys, because doing so
1200 # would cause errors in many object's __del__ methods.
1200 # would cause errors in many object's __del__ methods.
1201 if self.user_ns is not self.user_global_ns:
1201 if self.user_ns is not self.user_global_ns:
1202 self.user_ns.clear()
1202 self.user_ns.clear()
1203 ns = self.user_global_ns
1203 ns = self.user_global_ns
1204 drop_keys = set(ns.keys())
1204 drop_keys = set(ns.keys())
1205 drop_keys.discard('__builtin__')
1205 drop_keys.discard('__builtin__')
1206 drop_keys.discard('__builtins__')
1206 drop_keys.discard('__builtins__')
1207 drop_keys.discard('__name__')
1207 drop_keys.discard('__name__')
1208 for k in drop_keys:
1208 for k in drop_keys:
1209 del ns[k]
1209 del ns[k]
1210
1210
1211 self.user_ns_hidden.clear()
1211 self.user_ns_hidden.clear()
1212
1212
1213 # Restore the user namespaces to minimal usability
1213 # Restore the user namespaces to minimal usability
1214 self.init_user_ns()
1214 self.init_user_ns()
1215
1215
1216 # Restore the default and user aliases
1216 # Restore the default and user aliases
1217 self.alias_manager.clear_aliases()
1217 self.alias_manager.clear_aliases()
1218 self.alias_manager.init_aliases()
1218 self.alias_manager.init_aliases()
1219
1219
1220 # Flush the private list of module references kept for script
1220 # Flush the private list of module references kept for script
1221 # execution protection
1221 # execution protection
1222 self.clear_main_mod_cache()
1222 self.clear_main_mod_cache()
1223
1223
1224 # Clear out the namespace from the last %run
1224 # Clear out the namespace from the last %run
1225 self.new_main_mod()
1225 self.new_main_mod()
1226
1226
1227 def del_var(self, varname, by_name=False):
1227 def del_var(self, varname, by_name=False):
1228 """Delete a variable from the various namespaces, so that, as
1228 """Delete a variable from the various namespaces, so that, as
1229 far as possible, we're not keeping any hidden references to it.
1229 far as possible, we're not keeping any hidden references to it.
1230
1230
1231 Parameters
1231 Parameters
1232 ----------
1232 ----------
1233 varname : str
1233 varname : str
1234 The name of the variable to delete.
1234 The name of the variable to delete.
1235 by_name : bool
1235 by_name : bool
1236 If True, delete variables with the given name in each
1236 If True, delete variables with the given name in each
1237 namespace. If False (default), find the variable in the user
1237 namespace. If False (default), find the variable in the user
1238 namespace, and delete references to it.
1238 namespace, and delete references to it.
1239 """
1239 """
1240 if varname in ('__builtin__', '__builtins__'):
1240 if varname in ('__builtin__', '__builtins__'):
1241 raise ValueError("Refusing to delete %s" % varname)
1241 raise ValueError("Refusing to delete %s" % varname)
1242
1242
1243 ns_refs = self.all_ns_refs
1243 ns_refs = self.all_ns_refs
1244
1244
1245 if by_name: # Delete by name
1245 if by_name: # Delete by name
1246 for ns in ns_refs:
1246 for ns in ns_refs:
1247 try:
1247 try:
1248 del ns[varname]
1248 del ns[varname]
1249 except KeyError:
1249 except KeyError:
1250 pass
1250 pass
1251 else: # Delete by object
1251 else: # Delete by object
1252 try:
1252 try:
1253 obj = self.user_ns[varname]
1253 obj = self.user_ns[varname]
1254 except KeyError:
1254 except KeyError:
1255 raise NameError("name '%s' is not defined" % varname)
1255 raise NameError("name '%s' is not defined" % varname)
1256 # Also check in output history
1256 # Also check in output history
1257 ns_refs.append(self.history_manager.output_hist)
1257 ns_refs.append(self.history_manager.output_hist)
1258 for ns in ns_refs:
1258 for ns in ns_refs:
1259 to_delete = [n for n, o in ns.iteritems() if o is obj]
1259 to_delete = [n for n, o in ns.iteritems() if o is obj]
1260 for name in to_delete:
1260 for name in to_delete:
1261 del ns[name]
1261 del ns[name]
1262
1262
1263 # displayhook keeps extra references, but not in a dictionary
1263 # displayhook keeps extra references, but not in a dictionary
1264 for name in ('_', '__', '___'):
1264 for name in ('_', '__', '___'):
1265 if getattr(self.displayhook, name) is obj:
1265 if getattr(self.displayhook, name) is obj:
1266 setattr(self.displayhook, name, None)
1266 setattr(self.displayhook, name, None)
1267
1267
1268 def reset_selective(self, regex=None):
1268 def reset_selective(self, regex=None):
1269 """Clear selective variables from internal namespaces based on a
1269 """Clear selective variables from internal namespaces based on a
1270 specified regular expression.
1270 specified regular expression.
1271
1271
1272 Parameters
1272 Parameters
1273 ----------
1273 ----------
1274 regex : string or compiled pattern, optional
1274 regex : string or compiled pattern, optional
1275 A regular expression pattern that will be used in searching
1275 A regular expression pattern that will be used in searching
1276 variable names in the users namespaces.
1276 variable names in the users namespaces.
1277 """
1277 """
1278 if regex is not None:
1278 if regex is not None:
1279 try:
1279 try:
1280 m = re.compile(regex)
1280 m = re.compile(regex)
1281 except TypeError:
1281 except TypeError:
1282 raise TypeError('regex must be a string or compiled pattern')
1282 raise TypeError('regex must be a string or compiled pattern')
1283 # Search for keys in each namespace that match the given regex
1283 # Search for keys in each namespace that match the given regex
1284 # If a match is found, delete the key/value pair.
1284 # If a match is found, delete the key/value pair.
1285 for ns in self.all_ns_refs:
1285 for ns in self.all_ns_refs:
1286 for var in ns:
1286 for var in ns:
1287 if m.search(var):
1287 if m.search(var):
1288 del ns[var]
1288 del ns[var]
1289
1289
1290 def push(self, variables, interactive=True):
1290 def push(self, variables, interactive=True):
1291 """Inject a group of variables into the IPython user namespace.
1291 """Inject a group of variables into the IPython user namespace.
1292
1292
1293 Parameters
1293 Parameters
1294 ----------
1294 ----------
1295 variables : dict, str or list/tuple of str
1295 variables : dict, str or list/tuple of str
1296 The variables to inject into the user's namespace. If a dict, a
1296 The variables to inject into the user's namespace. If a dict, a
1297 simple update is done. If a str, the string is assumed to have
1297 simple update is done. If a str, the string is assumed to have
1298 variable names separated by spaces. A list/tuple of str can also
1298 variable names separated by spaces. A list/tuple of str can also
1299 be used to give the variable names. If just the variable names are
1299 be used to give the variable names. If just the variable names are
1300 give (list/tuple/str) then the variable values looked up in the
1300 give (list/tuple/str) then the variable values looked up in the
1301 callers frame.
1301 callers frame.
1302 interactive : bool
1302 interactive : bool
1303 If True (default), the variables will be listed with the ``who``
1303 If True (default), the variables will be listed with the ``who``
1304 magic.
1304 magic.
1305 """
1305 """
1306 vdict = None
1306 vdict = None
1307
1307
1308 # We need a dict of name/value pairs to do namespace updates.
1308 # We need a dict of name/value pairs to do namespace updates.
1309 if isinstance(variables, dict):
1309 if isinstance(variables, dict):
1310 vdict = variables
1310 vdict = variables
1311 elif isinstance(variables, (basestring, list, tuple)):
1311 elif isinstance(variables, (basestring, list, tuple)):
1312 if isinstance(variables, basestring):
1312 if isinstance(variables, basestring):
1313 vlist = variables.split()
1313 vlist = variables.split()
1314 else:
1314 else:
1315 vlist = variables
1315 vlist = variables
1316 vdict = {}
1316 vdict = {}
1317 cf = sys._getframe(1)
1317 cf = sys._getframe(1)
1318 for name in vlist:
1318 for name in vlist:
1319 try:
1319 try:
1320 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1320 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1321 except:
1321 except:
1322 print('Could not get variable %s from %s' %
1322 print('Could not get variable %s from %s' %
1323 (name,cf.f_code.co_name))
1323 (name,cf.f_code.co_name))
1324 else:
1324 else:
1325 raise ValueError('variables must be a dict/str/list/tuple')
1325 raise ValueError('variables must be a dict/str/list/tuple')
1326
1326
1327 # Propagate variables to user namespace
1327 # Propagate variables to user namespace
1328 self.user_ns.update(vdict)
1328 self.user_ns.update(vdict)
1329
1329
1330 # And configure interactive visibility
1330 # And configure interactive visibility
1331 user_ns_hidden = self.user_ns_hidden
1331 user_ns_hidden = self.user_ns_hidden
1332 if interactive:
1332 if interactive:
1333 user_ns_hidden.difference_update(vdict)
1333 user_ns_hidden.difference_update(vdict)
1334 else:
1334 else:
1335 user_ns_hidden.update(vdict)
1335 user_ns_hidden.update(vdict)
1336
1336
1337 def drop_by_id(self, variables):
1337 def drop_by_id(self, variables):
1338 """Remove a dict of variables from the user namespace, if they are the
1338 """Remove a dict of variables from the user namespace, if they are the
1339 same as the values in the dictionary.
1339 same as the values in the dictionary.
1340
1340
1341 This is intended for use by extensions: variables that they've added can
1341 This is intended for use by extensions: variables that they've added can
1342 be taken back out if they are unloaded, without removing any that the
1342 be taken back out if they are unloaded, without removing any that the
1343 user has overwritten.
1343 user has overwritten.
1344
1344
1345 Parameters
1345 Parameters
1346 ----------
1346 ----------
1347 variables : dict
1347 variables : dict
1348 A dictionary mapping object names (as strings) to the objects.
1348 A dictionary mapping object names (as strings) to the objects.
1349 """
1349 """
1350 for name, obj in variables.iteritems():
1350 for name, obj in variables.iteritems():
1351 if name in self.user_ns and self.user_ns[name] is obj:
1351 if name in self.user_ns and self.user_ns[name] is obj:
1352 del self.user_ns[name]
1352 del self.user_ns[name]
1353 self.user_ns_hidden.discard(name)
1353 self.user_ns_hidden.discard(name)
1354
1354
1355 #-------------------------------------------------------------------------
1355 #-------------------------------------------------------------------------
1356 # Things related to object introspection
1356 # Things related to object introspection
1357 #-------------------------------------------------------------------------
1357 #-------------------------------------------------------------------------
1358
1358
1359 def _ofind(self, oname, namespaces=None):
1359 def _ofind(self, oname, namespaces=None):
1360 """Find an object in the available namespaces.
1360 """Find an object in the available namespaces.
1361
1361
1362 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1362 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1363
1363
1364 Has special code to detect magic functions.
1364 Has special code to detect magic functions.
1365 """
1365 """
1366 oname = oname.strip()
1366 oname = oname.strip()
1367 #print '1- oname: <%r>' % oname # dbg
1367 #print '1- oname: <%r>' % oname # dbg
1368 if not oname.startswith(ESC_MAGIC) and \
1368 if not oname.startswith(ESC_MAGIC) and \
1369 not oname.startswith(ESC_MAGIC2) and \
1369 not oname.startswith(ESC_MAGIC2) and \
1370 not py3compat.isidentifier(oname, dotted=True):
1370 not py3compat.isidentifier(oname, dotted=True):
1371 return dict(found=False)
1371 return dict(found=False)
1372
1372
1373 alias_ns = None
1373 alias_ns = None
1374 if namespaces is None:
1374 if namespaces is None:
1375 # Namespaces to search in:
1375 # Namespaces to search in:
1376 # Put them in a list. The order is important so that we
1376 # Put them in a list. The order is important so that we
1377 # find things in the same order that Python finds them.
1377 # find things in the same order that Python finds them.
1378 namespaces = [ ('Interactive', self.user_ns),
1378 namespaces = [ ('Interactive', self.user_ns),
1379 ('Interactive (global)', self.user_global_ns),
1379 ('Interactive (global)', self.user_global_ns),
1380 ('Python builtin', builtin_mod.__dict__),
1380 ('Python builtin', builtin_mod.__dict__),
1381 ('Alias', self.alias_manager.alias_table),
1381 ('Alias', self.alias_manager.alias_table),
1382 ]
1382 ]
1383 alias_ns = self.alias_manager.alias_table
1383 alias_ns = self.alias_manager.alias_table
1384
1384
1385 # initialize results to 'null'
1385 # initialize results to 'null'
1386 found = False; obj = None; ospace = None; ds = None;
1386 found = False; obj = None; ospace = None; ds = None;
1387 ismagic = False; isalias = False; parent = None
1387 ismagic = False; isalias = False; parent = None
1388
1388
1389 # We need to special-case 'print', which as of python2.6 registers as a
1389 # We need to special-case 'print', which as of python2.6 registers as a
1390 # function but should only be treated as one if print_function was
1390 # function but should only be treated as one if print_function was
1391 # loaded with a future import. In this case, just bail.
1391 # loaded with a future import. In this case, just bail.
1392 if (oname == 'print' and not py3compat.PY3 and not \
1392 if (oname == 'print' and not py3compat.PY3 and not \
1393 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1393 (self.compile.compiler_flags & __future__.CO_FUTURE_PRINT_FUNCTION)):
1394 return {'found':found, 'obj':obj, 'namespace':ospace,
1394 return {'found':found, 'obj':obj, 'namespace':ospace,
1395 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1395 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1396
1396
1397 # Look for the given name by splitting it in parts. If the head is
1397 # Look for the given name by splitting it in parts. If the head is
1398 # found, then we look for all the remaining parts as members, and only
1398 # found, then we look for all the remaining parts as members, and only
1399 # declare success if we can find them all.
1399 # declare success if we can find them all.
1400 oname_parts = oname.split('.')
1400 oname_parts = oname.split('.')
1401 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1401 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1402 for nsname,ns in namespaces:
1402 for nsname,ns in namespaces:
1403 try:
1403 try:
1404 obj = ns[oname_head]
1404 obj = ns[oname_head]
1405 except KeyError:
1405 except KeyError:
1406 continue
1406 continue
1407 else:
1407 else:
1408 #print 'oname_rest:', oname_rest # dbg
1408 #print 'oname_rest:', oname_rest # dbg
1409 for part in oname_rest:
1409 for part in oname_rest:
1410 try:
1410 try:
1411 parent = obj
1411 parent = obj
1412 obj = getattr(obj,part)
1412 obj = getattr(obj,part)
1413 except:
1413 except:
1414 # Blanket except b/c some badly implemented objects
1414 # Blanket except b/c some badly implemented objects
1415 # allow __getattr__ to raise exceptions other than
1415 # allow __getattr__ to raise exceptions other than
1416 # AttributeError, which then crashes IPython.
1416 # AttributeError, which then crashes IPython.
1417 break
1417 break
1418 else:
1418 else:
1419 # If we finish the for loop (no break), we got all members
1419 # If we finish the for loop (no break), we got all members
1420 found = True
1420 found = True
1421 ospace = nsname
1421 ospace = nsname
1422 if ns == alias_ns:
1422 if ns == alias_ns:
1423 isalias = True
1423 isalias = True
1424 break # namespace loop
1424 break # namespace loop
1425
1425
1426 # Try to see if it's magic
1426 # Try to see if it's magic
1427 if not found:
1427 if not found:
1428 obj = None
1428 obj = None
1429 if oname.startswith(ESC_MAGIC2):
1429 if oname.startswith(ESC_MAGIC2):
1430 oname = oname.lstrip(ESC_MAGIC2)
1430 oname = oname.lstrip(ESC_MAGIC2)
1431 obj = self.find_cell_magic(oname)
1431 obj = self.find_cell_magic(oname)
1432 elif oname.startswith(ESC_MAGIC):
1432 elif oname.startswith(ESC_MAGIC):
1433 oname = oname.lstrip(ESC_MAGIC)
1433 oname = oname.lstrip(ESC_MAGIC)
1434 obj = self.find_line_magic(oname)
1434 obj = self.find_line_magic(oname)
1435 else:
1435 else:
1436 # search without prefix, so run? will find %run?
1436 # search without prefix, so run? will find %run?
1437 obj = self.find_line_magic(oname)
1437 obj = self.find_line_magic(oname)
1438 if obj is None:
1438 if obj is None:
1439 obj = self.find_cell_magic(oname)
1439 obj = self.find_cell_magic(oname)
1440 if obj is not None:
1440 if obj is not None:
1441 found = True
1441 found = True
1442 ospace = 'IPython internal'
1442 ospace = 'IPython internal'
1443 ismagic = True
1443 ismagic = True
1444
1444
1445 # Last try: special-case some literals like '', [], {}, etc:
1445 # Last try: special-case some literals like '', [], {}, etc:
1446 if not found and oname_head in ["''",'""','[]','{}','()']:
1446 if not found and oname_head in ["''",'""','[]','{}','()']:
1447 obj = eval(oname_head)
1447 obj = eval(oname_head)
1448 found = True
1448 found = True
1449 ospace = 'Interactive'
1449 ospace = 'Interactive'
1450
1450
1451 return {'found':found, 'obj':obj, 'namespace':ospace,
1451 return {'found':found, 'obj':obj, 'namespace':ospace,
1452 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1452 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1453
1453
1454 def _ofind_property(self, oname, info):
1454 def _ofind_property(self, oname, info):
1455 """Second part of object finding, to look for property details."""
1455 """Second part of object finding, to look for property details."""
1456 if info.found:
1456 if info.found:
1457 # Get the docstring of the class property if it exists.
1457 # Get the docstring of the class property if it exists.
1458 path = oname.split('.')
1458 path = oname.split('.')
1459 root = '.'.join(path[:-1])
1459 root = '.'.join(path[:-1])
1460 if info.parent is not None:
1460 if info.parent is not None:
1461 try:
1461 try:
1462 target = getattr(info.parent, '__class__')
1462 target = getattr(info.parent, '__class__')
1463 # The object belongs to a class instance.
1463 # The object belongs to a class instance.
1464 try:
1464 try:
1465 target = getattr(target, path[-1])
1465 target = getattr(target, path[-1])
1466 # The class defines the object.
1466 # The class defines the object.
1467 if isinstance(target, property):
1467 if isinstance(target, property):
1468 oname = root + '.__class__.' + path[-1]
1468 oname = root + '.__class__.' + path[-1]
1469 info = Struct(self._ofind(oname))
1469 info = Struct(self._ofind(oname))
1470 except AttributeError: pass
1470 except AttributeError: pass
1471 except AttributeError: pass
1471 except AttributeError: pass
1472
1472
1473 # We return either the new info or the unmodified input if the object
1473 # We return either the new info or the unmodified input if the object
1474 # hadn't been found
1474 # hadn't been found
1475 return info
1475 return info
1476
1476
1477 def _object_find(self, oname, namespaces=None):
1477 def _object_find(self, oname, namespaces=None):
1478 """Find an object and return a struct with info about it."""
1478 """Find an object and return a struct with info about it."""
1479 inf = Struct(self._ofind(oname, namespaces))
1479 inf = Struct(self._ofind(oname, namespaces))
1480 return Struct(self._ofind_property(oname, inf))
1480 return Struct(self._ofind_property(oname, inf))
1481
1481
1482 def _inspect(self, meth, oname, namespaces=None, **kw):
1482 def _inspect(self, meth, oname, namespaces=None, **kw):
1483 """Generic interface to the inspector system.
1483 """Generic interface to the inspector system.
1484
1484
1485 This function is meant to be called by pdef, pdoc & friends."""
1485 This function is meant to be called by pdef, pdoc & friends."""
1486 info = self._object_find(oname, namespaces)
1486 info = self._object_find(oname, namespaces)
1487 if info.found:
1487 if info.found:
1488 pmethod = getattr(self.inspector, meth)
1488 pmethod = getattr(self.inspector, meth)
1489 formatter = format_screen if info.ismagic else None
1489 formatter = format_screen if info.ismagic else None
1490 if meth == 'pdoc':
1490 if meth == 'pdoc':
1491 pmethod(info.obj, oname, formatter)
1491 pmethod(info.obj, oname, formatter)
1492 elif meth == 'pinfo':
1492 elif meth == 'pinfo':
1493 pmethod(info.obj, oname, formatter, info, **kw)
1493 pmethod(info.obj, oname, formatter, info, **kw)
1494 else:
1494 else:
1495 pmethod(info.obj, oname)
1495 pmethod(info.obj, oname)
1496 else:
1496 else:
1497 print('Object `%s` not found.' % oname)
1497 print('Object `%s` not found.' % oname)
1498 return 'not found' # so callers can take other action
1498 return 'not found' # so callers can take other action
1499
1499
1500 def object_inspect(self, oname, detail_level=0):
1500 def object_inspect(self, oname, detail_level=0):
1501 with self.builtin_trap:
1501 with self.builtin_trap:
1502 info = self._object_find(oname)
1502 info = self._object_find(oname)
1503 if info.found:
1503 if info.found:
1504 return self.inspector.info(info.obj, oname, info=info,
1504 return self.inspector.info(info.obj, oname, info=info,
1505 detail_level=detail_level
1505 detail_level=detail_level
1506 )
1506 )
1507 else:
1507 else:
1508 return oinspect.object_info(name=oname, found=False)
1508 return oinspect.object_info(name=oname, found=False)
1509
1509
1510 #-------------------------------------------------------------------------
1510 #-------------------------------------------------------------------------
1511 # Things related to history management
1511 # Things related to history management
1512 #-------------------------------------------------------------------------
1512 #-------------------------------------------------------------------------
1513
1513
1514 def init_history(self):
1514 def init_history(self):
1515 """Sets up the command history, and starts regular autosaves."""
1515 """Sets up the command history, and starts regular autosaves."""
1516 self.history_manager = HistoryManager(shell=self, config=self.config)
1516 self.history_manager = HistoryManager(shell=self, config=self.config)
1517 self.configurables.append(self.history_manager)
1517 self.configurables.append(self.history_manager)
1518
1518
1519 #-------------------------------------------------------------------------
1519 #-------------------------------------------------------------------------
1520 # Things related to exception handling and tracebacks (not debugging)
1520 # Things related to exception handling and tracebacks (not debugging)
1521 #-------------------------------------------------------------------------
1521 #-------------------------------------------------------------------------
1522
1522
1523 def init_traceback_handlers(self, custom_exceptions):
1523 def init_traceback_handlers(self, custom_exceptions):
1524 # Syntax error handler.
1524 # Syntax error handler.
1525 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1525 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1526
1526
1527 # The interactive one is initialized with an offset, meaning we always
1527 # The interactive one is initialized with an offset, meaning we always
1528 # want to remove the topmost item in the traceback, which is our own
1528 # want to remove the topmost item in the traceback, which is our own
1529 # internal code. Valid modes: ['Plain','Context','Verbose']
1529 # internal code. Valid modes: ['Plain','Context','Verbose']
1530 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1530 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1531 color_scheme='NoColor',
1531 color_scheme='NoColor',
1532 tb_offset = 1,
1532 tb_offset = 1,
1533 check_cache=self.compile.check_cache)
1533 check_cache=self.compile.check_cache)
1534
1534
1535 # The instance will store a pointer to the system-wide exception hook,
1535 # The instance will store a pointer to the system-wide exception hook,
1536 # so that runtime code (such as magics) can access it. This is because
1536 # so that runtime code (such as magics) can access it. This is because
1537 # during the read-eval loop, it may get temporarily overwritten.
1537 # during the read-eval loop, it may get temporarily overwritten.
1538 self.sys_excepthook = sys.excepthook
1538 self.sys_excepthook = sys.excepthook
1539
1539
1540 # and add any custom exception handlers the user may have specified
1540 # and add any custom exception handlers the user may have specified
1541 self.set_custom_exc(*custom_exceptions)
1541 self.set_custom_exc(*custom_exceptions)
1542
1542
1543 # Set the exception mode
1543 # Set the exception mode
1544 self.InteractiveTB.set_mode(mode=self.xmode)
1544 self.InteractiveTB.set_mode(mode=self.xmode)
1545
1545
1546 def set_custom_exc(self, exc_tuple, handler):
1546 def set_custom_exc(self, exc_tuple, handler):
1547 """set_custom_exc(exc_tuple,handler)
1547 """set_custom_exc(exc_tuple,handler)
1548
1548
1549 Set a custom exception handler, which will be called if any of the
1549 Set a custom exception handler, which will be called if any of the
1550 exceptions in exc_tuple occur in the mainloop (specifically, in the
1550 exceptions in exc_tuple occur in the mainloop (specifically, in the
1551 run_code() method).
1551 run_code() method).
1552
1552
1553 Parameters
1553 Parameters
1554 ----------
1554 ----------
1555
1555
1556 exc_tuple : tuple of exception classes
1556 exc_tuple : tuple of exception classes
1557 A *tuple* of exception classes, for which to call the defined
1557 A *tuple* of exception classes, for which to call the defined
1558 handler. It is very important that you use a tuple, and NOT A
1558 handler. It is very important that you use a tuple, and NOT A
1559 LIST here, because of the way Python's except statement works. If
1559 LIST here, because of the way Python's except statement works. If
1560 you only want to trap a single exception, use a singleton tuple::
1560 you only want to trap a single exception, use a singleton tuple::
1561
1561
1562 exc_tuple == (MyCustomException,)
1562 exc_tuple == (MyCustomException,)
1563
1563
1564 handler : callable
1564 handler : callable
1565 handler must have the following signature::
1565 handler must have the following signature::
1566
1566
1567 def my_handler(self, etype, value, tb, tb_offset=None):
1567 def my_handler(self, etype, value, tb, tb_offset=None):
1568 ...
1568 ...
1569 return structured_traceback
1569 return structured_traceback
1570
1570
1571 Your handler must return a structured traceback (a list of strings),
1571 Your handler must return a structured traceback (a list of strings),
1572 or None.
1572 or None.
1573
1573
1574 This will be made into an instance method (via types.MethodType)
1574 This will be made into an instance method (via types.MethodType)
1575 of IPython itself, and it will be called if any of the exceptions
1575 of IPython itself, and it will be called if any of the exceptions
1576 listed in the exc_tuple are caught. If the handler is None, an
1576 listed in the exc_tuple are caught. If the handler is None, an
1577 internal basic one is used, which just prints basic info.
1577 internal basic one is used, which just prints basic info.
1578
1578
1579 To protect IPython from crashes, if your handler ever raises an
1579 To protect IPython from crashes, if your handler ever raises an
1580 exception or returns an invalid result, it will be immediately
1580 exception or returns an invalid result, it will be immediately
1581 disabled.
1581 disabled.
1582
1582
1583 WARNING: by putting in your own exception handler into IPython's main
1583 WARNING: by putting in your own exception handler into IPython's main
1584 execution loop, you run a very good chance of nasty crashes. This
1584 execution loop, you run a very good chance of nasty crashes. This
1585 facility should only be used if you really know what you are doing."""
1585 facility should only be used if you really know what you are doing."""
1586
1586
1587 assert type(exc_tuple)==type(()) , \
1587 assert type(exc_tuple)==type(()) , \
1588 "The custom exceptions must be given AS A TUPLE."
1588 "The custom exceptions must be given AS A TUPLE."
1589
1589
1590 def dummy_handler(self,etype,value,tb,tb_offset=None):
1590 def dummy_handler(self,etype,value,tb,tb_offset=None):
1591 print('*** Simple custom exception handler ***')
1591 print('*** Simple custom exception handler ***')
1592 print('Exception type :',etype)
1592 print('Exception type :',etype)
1593 print('Exception value:',value)
1593 print('Exception value:',value)
1594 print('Traceback :',tb)
1594 print('Traceback :',tb)
1595 #print 'Source code :','\n'.join(self.buffer)
1595 #print 'Source code :','\n'.join(self.buffer)
1596
1596
1597 def validate_stb(stb):
1597 def validate_stb(stb):
1598 """validate structured traceback return type
1598 """validate structured traceback return type
1599
1599
1600 return type of CustomTB *should* be a list of strings, but allow
1600 return type of CustomTB *should* be a list of strings, but allow
1601 single strings or None, which are harmless.
1601 single strings or None, which are harmless.
1602
1602
1603 This function will *always* return a list of strings,
1603 This function will *always* return a list of strings,
1604 and will raise a TypeError if stb is inappropriate.
1604 and will raise a TypeError if stb is inappropriate.
1605 """
1605 """
1606 msg = "CustomTB must return list of strings, not %r" % stb
1606 msg = "CustomTB must return list of strings, not %r" % stb
1607 if stb is None:
1607 if stb is None:
1608 return []
1608 return []
1609 elif isinstance(stb, basestring):
1609 elif isinstance(stb, basestring):
1610 return [stb]
1610 return [stb]
1611 elif not isinstance(stb, list):
1611 elif not isinstance(stb, list):
1612 raise TypeError(msg)
1612 raise TypeError(msg)
1613 # it's a list
1613 # it's a list
1614 for line in stb:
1614 for line in stb:
1615 # check every element
1615 # check every element
1616 if not isinstance(line, basestring):
1616 if not isinstance(line, basestring):
1617 raise TypeError(msg)
1617 raise TypeError(msg)
1618 return stb
1618 return stb
1619
1619
1620 if handler is None:
1620 if handler is None:
1621 wrapped = dummy_handler
1621 wrapped = dummy_handler
1622 else:
1622 else:
1623 def wrapped(self,etype,value,tb,tb_offset=None):
1623 def wrapped(self,etype,value,tb,tb_offset=None):
1624 """wrap CustomTB handler, to protect IPython from user code
1624 """wrap CustomTB handler, to protect IPython from user code
1625
1625
1626 This makes it harder (but not impossible) for custom exception
1626 This makes it harder (but not impossible) for custom exception
1627 handlers to crash IPython.
1627 handlers to crash IPython.
1628 """
1628 """
1629 try:
1629 try:
1630 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1630 stb = handler(self,etype,value,tb,tb_offset=tb_offset)
1631 return validate_stb(stb)
1631 return validate_stb(stb)
1632 except:
1632 except:
1633 # clear custom handler immediately
1633 # clear custom handler immediately
1634 self.set_custom_exc((), None)
1634 self.set_custom_exc((), None)
1635 print("Custom TB Handler failed, unregistering", file=io.stderr)
1635 print("Custom TB Handler failed, unregistering", file=io.stderr)
1636 # show the exception in handler first
1636 # show the exception in handler first
1637 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1637 stb = self.InteractiveTB.structured_traceback(*sys.exc_info())
1638 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1638 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1639 print("The original exception:", file=io.stdout)
1639 print("The original exception:", file=io.stdout)
1640 stb = self.InteractiveTB.structured_traceback(
1640 stb = self.InteractiveTB.structured_traceback(
1641 (etype,value,tb), tb_offset=tb_offset
1641 (etype,value,tb), tb_offset=tb_offset
1642 )
1642 )
1643 return stb
1643 return stb
1644
1644
1645 self.CustomTB = types.MethodType(wrapped,self)
1645 self.CustomTB = types.MethodType(wrapped,self)
1646 self.custom_exceptions = exc_tuple
1646 self.custom_exceptions = exc_tuple
1647
1647
1648 def excepthook(self, etype, value, tb):
1648 def excepthook(self, etype, value, tb):
1649 """One more defense for GUI apps that call sys.excepthook.
1649 """One more defense for GUI apps that call sys.excepthook.
1650
1650
1651 GUI frameworks like wxPython trap exceptions and call
1651 GUI frameworks like wxPython trap exceptions and call
1652 sys.excepthook themselves. I guess this is a feature that
1652 sys.excepthook themselves. I guess this is a feature that
1653 enables them to keep running after exceptions that would
1653 enables them to keep running after exceptions that would
1654 otherwise kill their mainloop. This is a bother for IPython
1654 otherwise kill their mainloop. This is a bother for IPython
1655 which excepts to catch all of the program exceptions with a try:
1655 which excepts to catch all of the program exceptions with a try:
1656 except: statement.
1656 except: statement.
1657
1657
1658 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1658 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1659 any app directly invokes sys.excepthook, it will look to the user like
1659 any app directly invokes sys.excepthook, it will look to the user like
1660 IPython crashed. In order to work around this, we can disable the
1660 IPython crashed. In order to work around this, we can disable the
1661 CrashHandler and replace it with this excepthook instead, which prints a
1661 CrashHandler and replace it with this excepthook instead, which prints a
1662 regular traceback using our InteractiveTB. In this fashion, apps which
1662 regular traceback using our InteractiveTB. In this fashion, apps which
1663 call sys.excepthook will generate a regular-looking exception from
1663 call sys.excepthook will generate a regular-looking exception from
1664 IPython, and the CrashHandler will only be triggered by real IPython
1664 IPython, and the CrashHandler will only be triggered by real IPython
1665 crashes.
1665 crashes.
1666
1666
1667 This hook should be used sparingly, only in places which are not likely
1667 This hook should be used sparingly, only in places which are not likely
1668 to be true IPython errors.
1668 to be true IPython errors.
1669 """
1669 """
1670 self.showtraceback((etype,value,tb),tb_offset=0)
1670 self.showtraceback((etype,value,tb),tb_offset=0)
1671
1671
1672 def _get_exc_info(self, exc_tuple=None):
1672 def _get_exc_info(self, exc_tuple=None):
1673 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1673 """get exc_info from a given tuple, sys.exc_info() or sys.last_type etc.
1674
1674
1675 Ensures sys.last_type,value,traceback hold the exc_info we found,
1675 Ensures sys.last_type,value,traceback hold the exc_info we found,
1676 from whichever source.
1676 from whichever source.
1677
1677
1678 raises ValueError if none of these contain any information
1678 raises ValueError if none of these contain any information
1679 """
1679 """
1680 if exc_tuple is None:
1680 if exc_tuple is None:
1681 etype, value, tb = sys.exc_info()
1681 etype, value, tb = sys.exc_info()
1682 else:
1682 else:
1683 etype, value, tb = exc_tuple
1683 etype, value, tb = exc_tuple
1684
1684
1685 if etype is None:
1685 if etype is None:
1686 if hasattr(sys, 'last_type'):
1686 if hasattr(sys, 'last_type'):
1687 etype, value, tb = sys.last_type, sys.last_value, \
1687 etype, value, tb = sys.last_type, sys.last_value, \
1688 sys.last_traceback
1688 sys.last_traceback
1689
1689
1690 if etype is None:
1690 if etype is None:
1691 raise ValueError("No exception to find")
1691 raise ValueError("No exception to find")
1692
1692
1693 # Now store the exception info in sys.last_type etc.
1693 # Now store the exception info in sys.last_type etc.
1694 # WARNING: these variables are somewhat deprecated and not
1694 # WARNING: these variables are somewhat deprecated and not
1695 # necessarily safe to use in a threaded environment, but tools
1695 # necessarily safe to use in a threaded environment, but tools
1696 # like pdb depend on their existence, so let's set them. If we
1696 # like pdb depend on their existence, so let's set them. If we
1697 # find problems in the field, we'll need to revisit their use.
1697 # find problems in the field, we'll need to revisit their use.
1698 sys.last_type = etype
1698 sys.last_type = etype
1699 sys.last_value = value
1699 sys.last_value = value
1700 sys.last_traceback = tb
1700 sys.last_traceback = tb
1701
1701
1702 return etype, value, tb
1702 return etype, value, tb
1703
1703
1704
1704
1705 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1705 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1706 exception_only=False):
1706 exception_only=False):
1707 """Display the exception that just occurred.
1707 """Display the exception that just occurred.
1708
1708
1709 If nothing is known about the exception, this is the method which
1709 If nothing is known about the exception, this is the method which
1710 should be used throughout the code for presenting user tracebacks,
1710 should be used throughout the code for presenting user tracebacks,
1711 rather than directly invoking the InteractiveTB object.
1711 rather than directly invoking the InteractiveTB object.
1712
1712
1713 A specific showsyntaxerror() also exists, but this method can take
1713 A specific showsyntaxerror() also exists, but this method can take
1714 care of calling it if needed, so unless you are explicitly catching a
1714 care of calling it if needed, so unless you are explicitly catching a
1715 SyntaxError exception, don't try to analyze the stack manually and
1715 SyntaxError exception, don't try to analyze the stack manually and
1716 simply call this method."""
1716 simply call this method."""
1717
1717
1718 try:
1718 try:
1719 try:
1719 try:
1720 etype, value, tb = self._get_exc_info(exc_tuple)
1720 etype, value, tb = self._get_exc_info(exc_tuple)
1721 except ValueError:
1721 except ValueError:
1722 self.write_err('No traceback available to show.\n')
1722 self.write_err('No traceback available to show.\n')
1723 return
1723 return
1724
1724
1725 if etype is SyntaxError:
1725 if etype is SyntaxError:
1726 # Though this won't be called by syntax errors in the input
1726 # Though this won't be called by syntax errors in the input
1727 # line, there may be SyntaxError cases with imported code.
1727 # line, there may be SyntaxError cases with imported code.
1728 self.showsyntaxerror(filename)
1728 self.showsyntaxerror(filename)
1729 elif etype is UsageError:
1729 elif etype is UsageError:
1730 self.write_err("UsageError: %s" % value)
1730 self.write_err("UsageError: %s" % value)
1731 else:
1731 else:
1732 if exception_only:
1732 if exception_only:
1733 stb = ['An exception has occurred, use %tb to see '
1733 stb = ['An exception has occurred, use %tb to see '
1734 'the full traceback.\n']
1734 'the full traceback.\n']
1735 stb.extend(self.InteractiveTB.get_exception_only(etype,
1735 stb.extend(self.InteractiveTB.get_exception_only(etype,
1736 value))
1736 value))
1737 else:
1737 else:
1738 try:
1738 try:
1739 # Exception classes can customise their traceback - we
1739 # Exception classes can customise their traceback - we
1740 # use this in IPython.parallel for exceptions occurring
1740 # use this in IPython.parallel for exceptions occurring
1741 # in the engines. This should return a list of strings.
1741 # in the engines. This should return a list of strings.
1742 stb = value._render_traceback_()
1742 stb = value._render_traceback_()
1743 except Exception:
1743 except Exception:
1744 stb = self.InteractiveTB.structured_traceback(etype,
1744 stb = self.InteractiveTB.structured_traceback(etype,
1745 value, tb, tb_offset=tb_offset)
1745 value, tb, tb_offset=tb_offset)
1746
1746
1747 self._showtraceback(etype, value, stb)
1747 self._showtraceback(etype, value, stb)
1748 if self.call_pdb:
1748 if self.call_pdb:
1749 # drop into debugger
1749 # drop into debugger
1750 self.debugger(force=True)
1750 self.debugger(force=True)
1751 return
1751 return
1752
1752
1753 # Actually show the traceback
1753 # Actually show the traceback
1754 self._showtraceback(etype, value, stb)
1754 self._showtraceback(etype, value, stb)
1755
1755
1756 except KeyboardInterrupt:
1756 except KeyboardInterrupt:
1757 self.write_err("\nKeyboardInterrupt\n")
1757 self.write_err("\nKeyboardInterrupt\n")
1758
1758
1759 def _showtraceback(self, etype, evalue, stb):
1759 def _showtraceback(self, etype, evalue, stb):
1760 """Actually show a traceback.
1760 """Actually show a traceback.
1761
1761
1762 Subclasses may override this method to put the traceback on a different
1762 Subclasses may override this method to put the traceback on a different
1763 place, like a side channel.
1763 place, like a side channel.
1764 """
1764 """
1765 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1765 print(self.InteractiveTB.stb2text(stb), file=io.stdout)
1766
1766
1767 def showsyntaxerror(self, filename=None):
1767 def showsyntaxerror(self, filename=None):
1768 """Display the syntax error that just occurred.
1768 """Display the syntax error that just occurred.
1769
1769
1770 This doesn't display a stack trace because there isn't one.
1770 This doesn't display a stack trace because there isn't one.
1771
1771
1772 If a filename is given, it is stuffed in the exception instead
1772 If a filename is given, it is stuffed in the exception instead
1773 of what was there before (because Python's parser always uses
1773 of what was there before (because Python's parser always uses
1774 "<string>" when reading from a string).
1774 "<string>" when reading from a string).
1775 """
1775 """
1776 etype, value, last_traceback = self._get_exc_info()
1776 etype, value, last_traceback = self._get_exc_info()
1777
1777
1778 if filename and etype is SyntaxError:
1778 if filename and etype is SyntaxError:
1779 try:
1779 try:
1780 value.filename = filename
1780 value.filename = filename
1781 except:
1781 except:
1782 # Not the format we expect; leave it alone
1782 # Not the format we expect; leave it alone
1783 pass
1783 pass
1784
1784
1785 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1785 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1786 self._showtraceback(etype, value, stb)
1786 self._showtraceback(etype, value, stb)
1787
1787
1788 # This is overridden in TerminalInteractiveShell to show a message about
1788 # This is overridden in TerminalInteractiveShell to show a message about
1789 # the %paste magic.
1789 # the %paste magic.
1790 def showindentationerror(self):
1790 def showindentationerror(self):
1791 """Called by run_cell when there's an IndentationError in code entered
1791 """Called by run_cell when there's an IndentationError in code entered
1792 at the prompt.
1792 at the prompt.
1793
1793
1794 This is overridden in TerminalInteractiveShell to show a message about
1794 This is overridden in TerminalInteractiveShell to show a message about
1795 the %paste magic."""
1795 the %paste magic."""
1796 self.showsyntaxerror()
1796 self.showsyntaxerror()
1797
1797
1798 #-------------------------------------------------------------------------
1798 #-------------------------------------------------------------------------
1799 # Things related to readline
1799 # Things related to readline
1800 #-------------------------------------------------------------------------
1800 #-------------------------------------------------------------------------
1801
1801
1802 def init_readline(self):
1802 def init_readline(self):
1803 """Command history completion/saving/reloading."""
1803 """Command history completion/saving/reloading."""
1804
1804
1805 if self.readline_use:
1805 if self.readline_use:
1806 import IPython.utils.rlineimpl as readline
1806 import IPython.utils.rlineimpl as readline
1807
1807
1808 self.rl_next_input = None
1808 self.rl_next_input = None
1809 self.rl_do_indent = False
1809 self.rl_do_indent = False
1810
1810
1811 if not self.readline_use or not readline.have_readline:
1811 if not self.readline_use or not readline.have_readline:
1812 self.has_readline = False
1812 self.has_readline = False
1813 self.readline = None
1813 self.readline = None
1814 # Set a number of methods that depend on readline to be no-op
1814 # Set a number of methods that depend on readline to be no-op
1815 self.readline_no_record = no_op_context
1815 self.readline_no_record = no_op_context
1816 self.set_readline_completer = no_op
1816 self.set_readline_completer = no_op
1817 self.set_custom_completer = no_op
1817 self.set_custom_completer = no_op
1818 if self.readline_use:
1818 if self.readline_use:
1819 warn('Readline services not available or not loaded.')
1819 warn('Readline services not available or not loaded.')
1820 else:
1820 else:
1821 self.has_readline = True
1821 self.has_readline = True
1822 self.readline = readline
1822 self.readline = readline
1823 sys.modules['readline'] = readline
1823 sys.modules['readline'] = readline
1824
1824
1825 # Platform-specific configuration
1825 # Platform-specific configuration
1826 if os.name == 'nt':
1826 if os.name == 'nt':
1827 # FIXME - check with Frederick to see if we can harmonize
1827 # FIXME - check with Frederick to see if we can harmonize
1828 # naming conventions with pyreadline to avoid this
1828 # naming conventions with pyreadline to avoid this
1829 # platform-dependent check
1829 # platform-dependent check
1830 self.readline_startup_hook = readline.set_pre_input_hook
1830 self.readline_startup_hook = readline.set_pre_input_hook
1831 else:
1831 else:
1832 self.readline_startup_hook = readline.set_startup_hook
1832 self.readline_startup_hook = readline.set_startup_hook
1833
1833
1834 # Load user's initrc file (readline config)
1834 # Load user's initrc file (readline config)
1835 # Or if libedit is used, load editrc.
1835 # Or if libedit is used, load editrc.
1836 inputrc_name = os.environ.get('INPUTRC')
1836 inputrc_name = os.environ.get('INPUTRC')
1837 if inputrc_name is None:
1837 if inputrc_name is None:
1838 inputrc_name = '.inputrc'
1838 inputrc_name = '.inputrc'
1839 if readline.uses_libedit:
1839 if readline.uses_libedit:
1840 inputrc_name = '.editrc'
1840 inputrc_name = '.editrc'
1841 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1841 inputrc_name = os.path.join(self.home_dir, inputrc_name)
1842 if os.path.isfile(inputrc_name):
1842 if os.path.isfile(inputrc_name):
1843 try:
1843 try:
1844 readline.read_init_file(inputrc_name)
1844 readline.read_init_file(inputrc_name)
1845 except:
1845 except:
1846 warn('Problems reading readline initialization file <%s>'
1846 warn('Problems reading readline initialization file <%s>'
1847 % inputrc_name)
1847 % inputrc_name)
1848
1848
1849 # Configure readline according to user's prefs
1849 # Configure readline according to user's prefs
1850 # This is only done if GNU readline is being used. If libedit
1850 # This is only done if GNU readline is being used. If libedit
1851 # is being used (as on Leopard) the readline config is
1851 # is being used (as on Leopard) the readline config is
1852 # not run as the syntax for libedit is different.
1852 # not run as the syntax for libedit is different.
1853 if not readline.uses_libedit:
1853 if not readline.uses_libedit:
1854 for rlcommand in self.readline_parse_and_bind:
1854 for rlcommand in self.readline_parse_and_bind:
1855 #print "loading rl:",rlcommand # dbg
1855 #print "loading rl:",rlcommand # dbg
1856 readline.parse_and_bind(rlcommand)
1856 readline.parse_and_bind(rlcommand)
1857
1857
1858 # Remove some chars from the delimiters list. If we encounter
1858 # Remove some chars from the delimiters list. If we encounter
1859 # unicode chars, discard them.
1859 # unicode chars, discard them.
1860 delims = readline.get_completer_delims()
1860 delims = readline.get_completer_delims()
1861 if not py3compat.PY3:
1861 if not py3compat.PY3:
1862 delims = delims.encode("ascii", "ignore")
1862 delims = delims.encode("ascii", "ignore")
1863 for d in self.readline_remove_delims:
1863 for d in self.readline_remove_delims:
1864 delims = delims.replace(d, "")
1864 delims = delims.replace(d, "")
1865 delims = delims.replace(ESC_MAGIC, '')
1865 delims = delims.replace(ESC_MAGIC, '')
1866 readline.set_completer_delims(delims)
1866 readline.set_completer_delims(delims)
1867 # otherwise we end up with a monster history after a while:
1867 # otherwise we end up with a monster history after a while:
1868 readline.set_history_length(self.history_length)
1868 readline.set_history_length(self.history_length)
1869
1869
1870 self.refill_readline_hist()
1870 self.refill_readline_hist()
1871 self.readline_no_record = ReadlineNoRecord(self)
1871 self.readline_no_record = ReadlineNoRecord(self)
1872
1872
1873 # Configure auto-indent for all platforms
1873 # Configure auto-indent for all platforms
1874 self.set_autoindent(self.autoindent)
1874 self.set_autoindent(self.autoindent)
1875
1875
1876 def refill_readline_hist(self):
1876 def refill_readline_hist(self):
1877 # Load the last 1000 lines from history
1877 # Load the last 1000 lines from history
1878 self.readline.clear_history()
1878 self.readline.clear_history()
1879 stdin_encoding = sys.stdin.encoding or "utf-8"
1879 stdin_encoding = sys.stdin.encoding or "utf-8"
1880 last_cell = u""
1880 last_cell = u""
1881 for _, _, cell in self.history_manager.get_tail(1000,
1881 for _, _, cell in self.history_manager.get_tail(1000,
1882 include_latest=True):
1882 include_latest=True):
1883 # Ignore blank lines and consecutive duplicates
1883 # Ignore blank lines and consecutive duplicates
1884 cell = cell.rstrip()
1884 cell = cell.rstrip()
1885 if cell and (cell != last_cell):
1885 if cell and (cell != last_cell):
1886 if self.multiline_history:
1886 if self.multiline_history:
1887 self.readline.add_history(py3compat.unicode_to_str(cell,
1887 self.readline.add_history(py3compat.unicode_to_str(cell,
1888 stdin_encoding))
1888 stdin_encoding))
1889 else:
1889 else:
1890 for line in cell.splitlines():
1890 for line in cell.splitlines():
1891 self.readline.add_history(py3compat.unicode_to_str(line,
1891 self.readline.add_history(py3compat.unicode_to_str(line,
1892 stdin_encoding))
1892 stdin_encoding))
1893 last_cell = cell
1893 last_cell = cell
1894
1894
1895 def set_next_input(self, s):
1895 def set_next_input(self, s):
1896 """ Sets the 'default' input string for the next command line.
1896 """ Sets the 'default' input string for the next command line.
1897
1897
1898 Requires readline.
1898 Requires readline.
1899
1899
1900 Example:
1900 Example:
1901
1901
1902 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1902 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1903 [D:\ipython]|2> Hello Word_ # cursor is here
1903 [D:\ipython]|2> Hello Word_ # cursor is here
1904 """
1904 """
1905 self.rl_next_input = py3compat.cast_bytes_py2(s)
1905 self.rl_next_input = py3compat.cast_bytes_py2(s)
1906
1906
1907 # Maybe move this to the terminal subclass?
1907 # Maybe move this to the terminal subclass?
1908 def pre_readline(self):
1908 def pre_readline(self):
1909 """readline hook to be used at the start of each line.
1909 """readline hook to be used at the start of each line.
1910
1910
1911 Currently it handles auto-indent only."""
1911 Currently it handles auto-indent only."""
1912
1912
1913 if self.rl_do_indent:
1913 if self.rl_do_indent:
1914 self.readline.insert_text(self._indent_current_str())
1914 self.readline.insert_text(self._indent_current_str())
1915 if self.rl_next_input is not None:
1915 if self.rl_next_input is not None:
1916 self.readline.insert_text(self.rl_next_input)
1916 self.readline.insert_text(self.rl_next_input)
1917 self.rl_next_input = None
1917 self.rl_next_input = None
1918
1918
1919 def _indent_current_str(self):
1919 def _indent_current_str(self):
1920 """return the current level of indentation as a string"""
1920 """return the current level of indentation as a string"""
1921 return self.input_splitter.indent_spaces * ' '
1921 return self.input_splitter.indent_spaces * ' '
1922
1922
1923 #-------------------------------------------------------------------------
1923 #-------------------------------------------------------------------------
1924 # Things related to text completion
1924 # Things related to text completion
1925 #-------------------------------------------------------------------------
1925 #-------------------------------------------------------------------------
1926
1926
1927 def init_completer(self):
1927 def init_completer(self):
1928 """Initialize the completion machinery.
1928 """Initialize the completion machinery.
1929
1929
1930 This creates completion machinery that can be used by client code,
1930 This creates completion machinery that can be used by client code,
1931 either interactively in-process (typically triggered by the readline
1931 either interactively in-process (typically triggered by the readline
1932 library), programatically (such as in test suites) or out-of-prcess
1932 library), programatically (such as in test suites) or out-of-prcess
1933 (typically over the network by remote frontends).
1933 (typically over the network by remote frontends).
1934 """
1934 """
1935 from IPython.core.completer import IPCompleter
1935 from IPython.core.completer import IPCompleter
1936 from IPython.core.completerlib import (module_completer,
1936 from IPython.core.completerlib import (module_completer,
1937 magic_run_completer, cd_completer, reset_completer)
1937 magic_run_completer, cd_completer, reset_completer)
1938
1938
1939 self.Completer = IPCompleter(shell=self,
1939 self.Completer = IPCompleter(shell=self,
1940 namespace=self.user_ns,
1940 namespace=self.user_ns,
1941 global_namespace=self.user_global_ns,
1941 global_namespace=self.user_global_ns,
1942 alias_table=self.alias_manager.alias_table,
1942 alias_table=self.alias_manager.alias_table,
1943 use_readline=self.has_readline,
1943 use_readline=self.has_readline,
1944 config=self.config,
1944 config=self.config,
1945 )
1945 )
1946 self.configurables.append(self.Completer)
1946 self.configurables.append(self.Completer)
1947
1947
1948 # Add custom completers to the basic ones built into IPCompleter
1948 # Add custom completers to the basic ones built into IPCompleter
1949 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1949 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1950 self.strdispatchers['complete_command'] = sdisp
1950 self.strdispatchers['complete_command'] = sdisp
1951 self.Completer.custom_completers = sdisp
1951 self.Completer.custom_completers = sdisp
1952
1952
1953 self.set_hook('complete_command', module_completer, str_key = 'import')
1953 self.set_hook('complete_command', module_completer, str_key = 'import')
1954 self.set_hook('complete_command', module_completer, str_key = 'from')
1954 self.set_hook('complete_command', module_completer, str_key = 'from')
1955 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1955 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1956 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1956 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1957 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1957 self.set_hook('complete_command', reset_completer, str_key = '%reset')
1958
1958
1959 # Only configure readline if we truly are using readline. IPython can
1959 # Only configure readline if we truly are using readline. IPython can
1960 # do tab-completion over the network, in GUIs, etc, where readline
1960 # do tab-completion over the network, in GUIs, etc, where readline
1961 # itself may be absent
1961 # itself may be absent
1962 if self.has_readline:
1962 if self.has_readline:
1963 self.set_readline_completer()
1963 self.set_readline_completer()
1964
1964
1965 def complete(self, text, line=None, cursor_pos=None):
1965 def complete(self, text, line=None, cursor_pos=None):
1966 """Return the completed text and a list of completions.
1966 """Return the completed text and a list of completions.
1967
1967
1968 Parameters
1968 Parameters
1969 ----------
1969 ----------
1970
1970
1971 text : string
1971 text : string
1972 A string of text to be completed on. It can be given as empty and
1972 A string of text to be completed on. It can be given as empty and
1973 instead a line/position pair are given. In this case, the
1973 instead a line/position pair are given. In this case, the
1974 completer itself will split the line like readline does.
1974 completer itself will split the line like readline does.
1975
1975
1976 line : string, optional
1976 line : string, optional
1977 The complete line that text is part of.
1977 The complete line that text is part of.
1978
1978
1979 cursor_pos : int, optional
1979 cursor_pos : int, optional
1980 The position of the cursor on the input line.
1980 The position of the cursor on the input line.
1981
1981
1982 Returns
1982 Returns
1983 -------
1983 -------
1984 text : string
1984 text : string
1985 The actual text that was completed.
1985 The actual text that was completed.
1986
1986
1987 matches : list
1987 matches : list
1988 A sorted list with all possible completions.
1988 A sorted list with all possible completions.
1989
1989
1990 The optional arguments allow the completion to take more context into
1990 The optional arguments allow the completion to take more context into
1991 account, and are part of the low-level completion API.
1991 account, and are part of the low-level completion API.
1992
1992
1993 This is a wrapper around the completion mechanism, similar to what
1993 This is a wrapper around the completion mechanism, similar to what
1994 readline does at the command line when the TAB key is hit. By
1994 readline does at the command line when the TAB key is hit. By
1995 exposing it as a method, it can be used by other non-readline
1995 exposing it as a method, it can be used by other non-readline
1996 environments (such as GUIs) for text completion.
1996 environments (such as GUIs) for text completion.
1997
1997
1998 Simple usage example:
1998 Simple usage example:
1999
1999
2000 In [1]: x = 'hello'
2000 In [1]: x = 'hello'
2001
2001
2002 In [2]: _ip.complete('x.l')
2002 In [2]: _ip.complete('x.l')
2003 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2003 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
2004 """
2004 """
2005
2005
2006 # Inject names into __builtin__ so we can complete on the added names.
2006 # Inject names into __builtin__ so we can complete on the added names.
2007 with self.builtin_trap:
2007 with self.builtin_trap:
2008 return self.Completer.complete(text, line, cursor_pos)
2008 return self.Completer.complete(text, line, cursor_pos)
2009
2009
2010 def set_custom_completer(self, completer, pos=0):
2010 def set_custom_completer(self, completer, pos=0):
2011 """Adds a new custom completer function.
2011 """Adds a new custom completer function.
2012
2012
2013 The position argument (defaults to 0) is the index in the completers
2013 The position argument (defaults to 0) is the index in the completers
2014 list where you want the completer to be inserted."""
2014 list where you want the completer to be inserted."""
2015
2015
2016 newcomp = types.MethodType(completer,self.Completer)
2016 newcomp = types.MethodType(completer,self.Completer)
2017 self.Completer.matchers.insert(pos,newcomp)
2017 self.Completer.matchers.insert(pos,newcomp)
2018
2018
2019 def set_readline_completer(self):
2019 def set_readline_completer(self):
2020 """Reset readline's completer to be our own."""
2020 """Reset readline's completer to be our own."""
2021 self.readline.set_completer(self.Completer.rlcomplete)
2021 self.readline.set_completer(self.Completer.rlcomplete)
2022
2022
2023 def set_completer_frame(self, frame=None):
2023 def set_completer_frame(self, frame=None):
2024 """Set the frame of the completer."""
2024 """Set the frame of the completer."""
2025 if frame:
2025 if frame:
2026 self.Completer.namespace = frame.f_locals
2026 self.Completer.namespace = frame.f_locals
2027 self.Completer.global_namespace = frame.f_globals
2027 self.Completer.global_namespace = frame.f_globals
2028 else:
2028 else:
2029 self.Completer.namespace = self.user_ns
2029 self.Completer.namespace = self.user_ns
2030 self.Completer.global_namespace = self.user_global_ns
2030 self.Completer.global_namespace = self.user_global_ns
2031
2031
2032 #-------------------------------------------------------------------------
2032 #-------------------------------------------------------------------------
2033 # Things related to magics
2033 # Things related to magics
2034 #-------------------------------------------------------------------------
2034 #-------------------------------------------------------------------------
2035
2035
2036 def init_magics(self):
2036 def init_magics(self):
2037 from IPython.core import magics as m
2037 from IPython.core import magics as m
2038 self.magics_manager = magic.MagicsManager(shell=self,
2038 self.magics_manager = magic.MagicsManager(shell=self,
2039 confg=self.config,
2039 confg=self.config,
2040 user_magics=m.UserMagics(self))
2040 user_magics=m.UserMagics(self))
2041 self.configurables.append(self.magics_manager)
2041 self.configurables.append(self.magics_manager)
2042
2042
2043 # Expose as public API from the magics manager
2043 # Expose as public API from the magics manager
2044 self.register_magics = self.magics_manager.register
2044 self.register_magics = self.magics_manager.register
2045 self.register_magic_function = self.magics_manager.register_function
2045 self.register_magic_function = self.magics_manager.register_function
2046 self.define_magic = self.magics_manager.define_magic
2046 self.define_magic = self.magics_manager.define_magic
2047
2047
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2048 self.register_magics(m.AutoMagics, m.BasicMagics, m.CodeMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2049 m.ConfigMagics, m.DeprecatedMagics, m.DisplayMagics, m.ExecutionMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2050 m.ExtensionMagics, m.HistoryMagics, m.LoggingMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2051 m.NamespaceMagics, m.OSMagics, m.PylabMagics, m.ScriptMagics,
2052 )
2052 )
2053
2053
2054 # Register Magic Aliases
2054 # Register Magic Aliases
2055 mman = self.magics_manager
2055 mman = self.magics_manager
2056 mman.register_alias('ed', 'edit')
2056 mman.register_alias('ed', 'edit')
2057 mman.register_alias('hist', 'history')
2057 mman.register_alias('hist', 'history')
2058 mman.register_alias('rep', 'recall')
2058 mman.register_alias('rep', 'recall')
2059
2059
2060 # FIXME: Move the color initialization to the DisplayHook, which
2060 # FIXME: Move the color initialization to the DisplayHook, which
2061 # should be split into a prompt manager and displayhook. We probably
2061 # should be split into a prompt manager and displayhook. We probably
2062 # even need a centralize colors management object.
2062 # even need a centralize colors management object.
2063 self.magic('colors %s' % self.colors)
2063 self.magic('colors %s' % self.colors)
2064
2064
2065 def run_line_magic(self, magic_name, line):
2065 def run_line_magic(self, magic_name, line):
2066 """Execute the given line magic.
2066 """Execute the given line magic.
2067
2067
2068 Parameters
2068 Parameters
2069 ----------
2069 ----------
2070 magic_name : str
2070 magic_name : str
2071 Name of the desired magic function, without '%' prefix.
2071 Name of the desired magic function, without '%' prefix.
2072
2072
2073 line : str
2073 line : str
2074 The rest of the input line as a single string.
2074 The rest of the input line as a single string.
2075 """
2075 """
2076 fn = self.find_line_magic(magic_name)
2076 fn = self.find_line_magic(magic_name)
2077 if fn is None:
2077 if fn is None:
2078 cm = self.find_cell_magic(magic_name)
2078 cm = self.find_cell_magic(magic_name)
2079 etpl = "Line magic function `%%%s` not found%s."
2079 etpl = "Line magic function `%%%s` not found%s."
2080 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2080 extra = '' if cm is None else (' (But cell magic `%%%%%s` exists, '
2081 'did you mean that instead?)' % magic_name )
2081 'did you mean that instead?)' % magic_name )
2082 error(etpl % (magic_name, extra))
2082 error(etpl % (magic_name, extra))
2083 else:
2083 else:
2084 # Note: this is the distance in the stack to the user's frame.
2084 # Note: this is the distance in the stack to the user's frame.
2085 # This will need to be updated if the internal calling logic gets
2085 # This will need to be updated if the internal calling logic gets
2086 # refactored, or else we'll be expanding the wrong variables.
2086 # refactored, or else we'll be expanding the wrong variables.
2087 stack_depth = 2
2087 stack_depth = 2
2088 magic_arg_s = self.var_expand(line, stack_depth)
2088 magic_arg_s = self.var_expand(line, stack_depth)
2089 # Put magic args in a list so we can call with f(*a) syntax
2089 # Put magic args in a list so we can call with f(*a) syntax
2090 args = [magic_arg_s]
2090 args = [magic_arg_s]
2091 # Grab local namespace if we need it:
2091 # Grab local namespace if we need it:
2092 if getattr(fn, "needs_local_scope", False):
2092 if getattr(fn, "needs_local_scope", False):
2093 args.append(sys._getframe(stack_depth).f_locals)
2093 args.append(sys._getframe(stack_depth).f_locals)
2094 with self.builtin_trap:
2094 with self.builtin_trap:
2095 result = fn(*args)
2095 result = fn(*args)
2096 return result
2096 return result
2097
2097
2098 def run_cell_magic(self, magic_name, line, cell):
2098 def run_cell_magic(self, magic_name, line, cell):
2099 """Execute the given cell magic.
2099 """Execute the given cell magic.
2100
2100
2101 Parameters
2101 Parameters
2102 ----------
2102 ----------
2103 magic_name : str
2103 magic_name : str
2104 Name of the desired magic function, without '%' prefix.
2104 Name of the desired magic function, without '%' prefix.
2105
2105
2106 line : str
2106 line : str
2107 The rest of the first input line as a single string.
2107 The rest of the first input line as a single string.
2108
2108
2109 cell : str
2109 cell : str
2110 The body of the cell as a (possibly multiline) string.
2110 The body of the cell as a (possibly multiline) string.
2111 """
2111 """
2112 fn = self.find_cell_magic(magic_name)
2112 fn = self.find_cell_magic(magic_name)
2113 if fn is None:
2113 if fn is None:
2114 lm = self.find_line_magic(magic_name)
2114 lm = self.find_line_magic(magic_name)
2115 etpl = "Cell magic function `%%%%%s` not found%s."
2115 etpl = "Cell magic function `%%%%%s` not found%s."
2116 extra = '' if lm is None else (' (But line magic `%%%s` exists, '
2116 extra = '' if lm is None else (' (But line magic `%%%s` exists, '
2117 'did you mean that instead?)' % magic_name )
2117 'did you mean that instead?)' % magic_name )
2118 error(etpl % (magic_name, extra))
2118 error(etpl % (magic_name, extra))
2119 else:
2119 else:
2120 # Note: this is the distance in the stack to the user's frame.
2120 # Note: this is the distance in the stack to the user's frame.
2121 # This will need to be updated if the internal calling logic gets
2121 # This will need to be updated if the internal calling logic gets
2122 # refactored, or else we'll be expanding the wrong variables.
2122 # refactored, or else we'll be expanding the wrong variables.
2123 stack_depth = 2
2123 stack_depth = 2
2124 magic_arg_s = self.var_expand(line, stack_depth)
2124 magic_arg_s = self.var_expand(line, stack_depth)
2125 with self.builtin_trap:
2125 with self.builtin_trap:
2126 result = fn(magic_arg_s, cell)
2126 result = fn(magic_arg_s, cell)
2127 return result
2127 return result
2128
2128
2129 def find_line_magic(self, magic_name):
2129 def find_line_magic(self, magic_name):
2130 """Find and return a line magic by name.
2130 """Find and return a line magic by name.
2131
2131
2132 Returns None if the magic isn't found."""
2132 Returns None if the magic isn't found."""
2133 return self.magics_manager.magics['line'].get(magic_name)
2133 return self.magics_manager.magics['line'].get(magic_name)
2134
2134
2135 def find_cell_magic(self, magic_name):
2135 def find_cell_magic(self, magic_name):
2136 """Find and return a cell magic by name.
2136 """Find and return a cell magic by name.
2137
2137
2138 Returns None if the magic isn't found."""
2138 Returns None if the magic isn't found."""
2139 return self.magics_manager.magics['cell'].get(magic_name)
2139 return self.magics_manager.magics['cell'].get(magic_name)
2140
2140
2141 def find_magic(self, magic_name, magic_kind='line'):
2141 def find_magic(self, magic_name, magic_kind='line'):
2142 """Find and return a magic of the given type by name.
2142 """Find and return a magic of the given type by name.
2143
2143
2144 Returns None if the magic isn't found."""
2144 Returns None if the magic isn't found."""
2145 return self.magics_manager.magics[magic_kind].get(magic_name)
2145 return self.magics_manager.magics[magic_kind].get(magic_name)
2146
2146
2147 def magic(self, arg_s):
2147 def magic(self, arg_s):
2148 """DEPRECATED. Use run_line_magic() instead.
2148 """DEPRECATED. Use run_line_magic() instead.
2149
2149
2150 Call a magic function by name.
2150 Call a magic function by name.
2151
2151
2152 Input: a string containing the name of the magic function to call and
2152 Input: a string containing the name of the magic function to call and
2153 any additional arguments to be passed to the magic.
2153 any additional arguments to be passed to the magic.
2154
2154
2155 magic('name -opt foo bar') is equivalent to typing at the ipython
2155 magic('name -opt foo bar') is equivalent to typing at the ipython
2156 prompt:
2156 prompt:
2157
2157
2158 In[1]: %name -opt foo bar
2158 In[1]: %name -opt foo bar
2159
2159
2160 To call a magic without arguments, simply use magic('name').
2160 To call a magic without arguments, simply use magic('name').
2161
2161
2162 This provides a proper Python function to call IPython's magics in any
2162 This provides a proper Python function to call IPython's magics in any
2163 valid Python code you can type at the interpreter, including loops and
2163 valid Python code you can type at the interpreter, including loops and
2164 compound statements.
2164 compound statements.
2165 """
2165 """
2166 # TODO: should we issue a loud deprecation warning here?
2166 # TODO: should we issue a loud deprecation warning here?
2167 magic_name, _, magic_arg_s = arg_s.partition(' ')
2167 magic_name, _, magic_arg_s = arg_s.partition(' ')
2168 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2168 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
2169 return self.run_line_magic(magic_name, magic_arg_s)
2169 return self.run_line_magic(magic_name, magic_arg_s)
2170
2170
2171 #-------------------------------------------------------------------------
2171 #-------------------------------------------------------------------------
2172 # Things related to macros
2172 # Things related to macros
2173 #-------------------------------------------------------------------------
2173 #-------------------------------------------------------------------------
2174
2174
2175 def define_macro(self, name, themacro):
2175 def define_macro(self, name, themacro):
2176 """Define a new macro
2176 """Define a new macro
2177
2177
2178 Parameters
2178 Parameters
2179 ----------
2179 ----------
2180 name : str
2180 name : str
2181 The name of the macro.
2181 The name of the macro.
2182 themacro : str or Macro
2182 themacro : str or Macro
2183 The action to do upon invoking the macro. If a string, a new
2183 The action to do upon invoking the macro. If a string, a new
2184 Macro object is created by passing the string to it.
2184 Macro object is created by passing the string to it.
2185 """
2185 """
2186
2186
2187 from IPython.core import macro
2187 from IPython.core import macro
2188
2188
2189 if isinstance(themacro, basestring):
2189 if isinstance(themacro, basestring):
2190 themacro = macro.Macro(themacro)
2190 themacro = macro.Macro(themacro)
2191 if not isinstance(themacro, macro.Macro):
2191 if not isinstance(themacro, macro.Macro):
2192 raise ValueError('A macro must be a string or a Macro instance.')
2192 raise ValueError('A macro must be a string or a Macro instance.')
2193 self.user_ns[name] = themacro
2193 self.user_ns[name] = themacro
2194
2194
2195 #-------------------------------------------------------------------------
2195 #-------------------------------------------------------------------------
2196 # Things related to the running of system commands
2196 # Things related to the running of system commands
2197 #-------------------------------------------------------------------------
2197 #-------------------------------------------------------------------------
2198
2198
2199 def system_piped(self, cmd):
2199 def system_piped(self, cmd):
2200 """Call the given cmd in a subprocess, piping stdout/err
2200 """Call the given cmd in a subprocess, piping stdout/err
2201
2201
2202 Parameters
2202 Parameters
2203 ----------
2203 ----------
2204 cmd : str
2204 cmd : str
2205 Command to execute (can not end in '&', as background processes are
2205 Command to execute (can not end in '&', as background processes are
2206 not supported. Should not be a command that expects input
2206 not supported. Should not be a command that expects input
2207 other than simple text.
2207 other than simple text.
2208 """
2208 """
2209 if cmd.rstrip().endswith('&'):
2209 if cmd.rstrip().endswith('&'):
2210 # this is *far* from a rigorous test
2210 # this is *far* from a rigorous test
2211 # We do not support backgrounding processes because we either use
2211 # We do not support backgrounding processes because we either use
2212 # pexpect or pipes to read from. Users can always just call
2212 # pexpect or pipes to read from. Users can always just call
2213 # os.system() or use ip.system=ip.system_raw
2213 # os.system() or use ip.system=ip.system_raw
2214 # if they really want a background process.
2214 # if they really want a background process.
2215 raise OSError("Background processes not supported.")
2215 raise OSError("Background processes not supported.")
2216
2216
2217 # we explicitly do NOT return the subprocess status code, because
2217 # we explicitly do NOT return the subprocess status code, because
2218 # a non-None value would trigger :func:`sys.displayhook` calls.
2218 # a non-None value would trigger :func:`sys.displayhook` calls.
2219 # Instead, we store the exit_code in user_ns.
2219 # Instead, we store the exit_code in user_ns.
2220 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2220 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=1))
2221
2221
2222 def system_raw(self, cmd):
2222 def system_raw(self, cmd):
2223 """Call the given cmd in a subprocess using os.system
2223 """Call the given cmd in a subprocess using os.system
2224
2224
2225 Parameters
2225 Parameters
2226 ----------
2226 ----------
2227 cmd : str
2227 cmd : str
2228 Command to execute.
2228 Command to execute.
2229 """
2229 """
2230 cmd = self.var_expand(cmd, depth=1)
2230 cmd = self.var_expand(cmd, depth=1)
2231 # protect os.system from UNC paths on Windows, which it can't handle:
2231 # protect os.system from UNC paths on Windows, which it can't handle:
2232 if sys.platform == 'win32':
2232 if sys.platform == 'win32':
2233 from IPython.utils._process_win32 import AvoidUNCPath
2233 from IPython.utils._process_win32 import AvoidUNCPath
2234 with AvoidUNCPath() as path:
2234 with AvoidUNCPath() as path:
2235 if path is not None:
2235 if path is not None:
2236 cmd = '"pushd %s &&"%s' % (path, cmd)
2236 cmd = '"pushd %s &&"%s' % (path, cmd)
2237 cmd = py3compat.unicode_to_str(cmd)
2237 cmd = py3compat.unicode_to_str(cmd)
2238 ec = os.system(cmd)
2238 ec = os.system(cmd)
2239 else:
2239 else:
2240 cmd = py3compat.unicode_to_str(cmd)
2240 cmd = py3compat.unicode_to_str(cmd)
2241 ec = os.system(cmd)
2241 ec = os.system(cmd)
2242
2242
2243 # We explicitly do NOT return the subprocess status code, because
2243 # We explicitly do NOT return the subprocess status code, because
2244 # a non-None value would trigger :func:`sys.displayhook` calls.
2244 # a non-None value would trigger :func:`sys.displayhook` calls.
2245 # Instead, we store the exit_code in user_ns.
2245 # Instead, we store the exit_code in user_ns.
2246 self.user_ns['_exit_code'] = ec
2246 self.user_ns['_exit_code'] = ec
2247
2247
2248 # use piped system by default, because it is better behaved
2248 # use piped system by default, because it is better behaved
2249 system = system_piped
2249 system = system_piped
2250
2250
2251 def getoutput(self, cmd, split=True, depth=0):
2251 def getoutput(self, cmd, split=True, depth=0):
2252 """Get output (possibly including stderr) from a subprocess.
2252 """Get output (possibly including stderr) from a subprocess.
2253
2253
2254 Parameters
2254 Parameters
2255 ----------
2255 ----------
2256 cmd : str
2256 cmd : str
2257 Command to execute (can not end in '&', as background processes are
2257 Command to execute (can not end in '&', as background processes are
2258 not supported.
2258 not supported.
2259 split : bool, optional
2259 split : bool, optional
2260 If True, split the output into an IPython SList. Otherwise, an
2260 If True, split the output into an IPython SList. Otherwise, an
2261 IPython LSString is returned. These are objects similar to normal
2261 IPython LSString is returned. These are objects similar to normal
2262 lists and strings, with a few convenience attributes for easier
2262 lists and strings, with a few convenience attributes for easier
2263 manipulation of line-based output. You can use '?' on them for
2263 manipulation of line-based output. You can use '?' on them for
2264 details.
2264 details.
2265 depth : int, optional
2265 depth : int, optional
2266 How many frames above the caller are the local variables which should
2266 How many frames above the caller are the local variables which should
2267 be expanded in the command string? The default (0) assumes that the
2267 be expanded in the command string? The default (0) assumes that the
2268 expansion variables are in the stack frame calling this function.
2268 expansion variables are in the stack frame calling this function.
2269 """
2269 """
2270 if cmd.rstrip().endswith('&'):
2270 if cmd.rstrip().endswith('&'):
2271 # this is *far* from a rigorous test
2271 # this is *far* from a rigorous test
2272 raise OSError("Background processes not supported.")
2272 raise OSError("Background processes not supported.")
2273 out = getoutput(self.var_expand(cmd, depth=depth+1))
2273 out = getoutput(self.var_expand(cmd, depth=depth+1))
2274 if split:
2274 if split:
2275 out = SList(out.splitlines())
2275 out = SList(out.splitlines())
2276 else:
2276 else:
2277 out = LSString(out)
2277 out = LSString(out)
2278 return out
2278 return out
2279
2279
2280 #-------------------------------------------------------------------------
2280 #-------------------------------------------------------------------------
2281 # Things related to aliases
2281 # Things related to aliases
2282 #-------------------------------------------------------------------------
2282 #-------------------------------------------------------------------------
2283
2283
2284 def init_alias(self):
2284 def init_alias(self):
2285 self.alias_manager = AliasManager(shell=self, config=self.config)
2285 self.alias_manager = AliasManager(shell=self, config=self.config)
2286 self.configurables.append(self.alias_manager)
2286 self.configurables.append(self.alias_manager)
2287 self.ns_table['alias'] = self.alias_manager.alias_table,
2287 self.ns_table['alias'] = self.alias_manager.alias_table,
2288
2288
2289 #-------------------------------------------------------------------------
2289 #-------------------------------------------------------------------------
2290 # Things related to extensions and plugins
2290 # Things related to extensions and plugins
2291 #-------------------------------------------------------------------------
2291 #-------------------------------------------------------------------------
2292
2292
2293 def init_extension_manager(self):
2293 def init_extension_manager(self):
2294 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2294 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2295 self.configurables.append(self.extension_manager)
2295 self.configurables.append(self.extension_manager)
2296
2296
2297 def init_plugin_manager(self):
2297 def init_plugin_manager(self):
2298 self.plugin_manager = PluginManager(config=self.config)
2298 self.plugin_manager = PluginManager(config=self.config)
2299 self.configurables.append(self.plugin_manager)
2299 self.configurables.append(self.plugin_manager)
2300
2300
2301
2301
2302 #-------------------------------------------------------------------------
2302 #-------------------------------------------------------------------------
2303 # Things related to payloads
2303 # Things related to payloads
2304 #-------------------------------------------------------------------------
2304 #-------------------------------------------------------------------------
2305
2305
2306 def init_payload(self):
2306 def init_payload(self):
2307 self.payload_manager = PayloadManager(config=self.config)
2307 self.payload_manager = PayloadManager(config=self.config)
2308 self.configurables.append(self.payload_manager)
2308 self.configurables.append(self.payload_manager)
2309
2309
2310 #-------------------------------------------------------------------------
2310 #-------------------------------------------------------------------------
2311 # Things related to the prefilter
2311 # Things related to the prefilter
2312 #-------------------------------------------------------------------------
2312 #-------------------------------------------------------------------------
2313
2313
2314 def init_prefilter(self):
2314 def init_prefilter(self):
2315 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2315 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2316 self.configurables.append(self.prefilter_manager)
2316 self.configurables.append(self.prefilter_manager)
2317 # Ultimately this will be refactored in the new interpreter code, but
2317 # Ultimately this will be refactored in the new interpreter code, but
2318 # for now, we should expose the main prefilter method (there's legacy
2318 # for now, we should expose the main prefilter method (there's legacy
2319 # code out there that may rely on this).
2319 # code out there that may rely on this).
2320 self.prefilter = self.prefilter_manager.prefilter_lines
2320 self.prefilter = self.prefilter_manager.prefilter_lines
2321
2321
2322 def auto_rewrite_input(self, cmd):
2322 def auto_rewrite_input(self, cmd):
2323 """Print to the screen the rewritten form of the user's command.
2323 """Print to the screen the rewritten form of the user's command.
2324
2324
2325 This shows visual feedback by rewriting input lines that cause
2325 This shows visual feedback by rewriting input lines that cause
2326 automatic calling to kick in, like::
2326 automatic calling to kick in, like::
2327
2327
2328 /f x
2328 /f x
2329
2329
2330 into::
2330 into::
2331
2331
2332 ------> f(x)
2332 ------> f(x)
2333
2333
2334 after the user's input prompt. This helps the user understand that the
2334 after the user's input prompt. This helps the user understand that the
2335 input line was transformed automatically by IPython.
2335 input line was transformed automatically by IPython.
2336 """
2336 """
2337 if not self.show_rewritten_input:
2337 if not self.show_rewritten_input:
2338 return
2338 return
2339
2339
2340 rw = self.prompt_manager.render('rewrite') + cmd
2340 rw = self.prompt_manager.render('rewrite') + cmd
2341
2341
2342 try:
2342 try:
2343 # plain ascii works better w/ pyreadline, on some machines, so
2343 # plain ascii works better w/ pyreadline, on some machines, so
2344 # we use it and only print uncolored rewrite if we have unicode
2344 # we use it and only print uncolored rewrite if we have unicode
2345 rw = str(rw)
2345 rw = str(rw)
2346 print(rw, file=io.stdout)
2346 print(rw, file=io.stdout)
2347 except UnicodeEncodeError:
2347 except UnicodeEncodeError:
2348 print("------> " + cmd)
2348 print("------> " + cmd)
2349
2349
2350 #-------------------------------------------------------------------------
2350 #-------------------------------------------------------------------------
2351 # Things related to extracting values/expressions from kernel and user_ns
2351 # Things related to extracting values/expressions from kernel and user_ns
2352 #-------------------------------------------------------------------------
2352 #-------------------------------------------------------------------------
2353
2353
2354 def _simple_error(self):
2354 def _simple_error(self):
2355 etype, value = sys.exc_info()[:2]
2355 etype, value = sys.exc_info()[:2]
2356 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2356 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2357
2357
2358 def user_variables(self, names):
2358 def user_variables(self, names):
2359 """Get a list of variable names from the user's namespace.
2359 """Get a list of variable names from the user's namespace.
2360
2360
2361 Parameters
2361 Parameters
2362 ----------
2362 ----------
2363 names : list of strings
2363 names : list of strings
2364 A list of names of variables to be read from the user namespace.
2364 A list of names of variables to be read from the user namespace.
2365
2365
2366 Returns
2366 Returns
2367 -------
2367 -------
2368 A dict, keyed by the input names and with the repr() of each value.
2368 A dict, keyed by the input names and with the repr() of each value.
2369 """
2369 """
2370 out = {}
2370 out = {}
2371 user_ns = self.user_ns
2371 user_ns = self.user_ns
2372 for varname in names:
2372 for varname in names:
2373 try:
2373 try:
2374 value = repr(user_ns[varname])
2374 value = repr(user_ns[varname])
2375 except:
2375 except:
2376 value = self._simple_error()
2376 value = self._simple_error()
2377 out[varname] = value
2377 out[varname] = value
2378 return out
2378 return out
2379
2379
2380 def user_expressions(self, expressions):
2380 def user_expressions(self, expressions):
2381 """Evaluate a dict of expressions in the user's namespace.
2381 """Evaluate a dict of expressions in the user's namespace.
2382
2382
2383 Parameters
2383 Parameters
2384 ----------
2384 ----------
2385 expressions : dict
2385 expressions : dict
2386 A dict with string keys and string values. The expression values
2386 A dict with string keys and string values. The expression values
2387 should be valid Python expressions, each of which will be evaluated
2387 should be valid Python expressions, each of which will be evaluated
2388 in the user namespace.
2388 in the user namespace.
2389
2389
2390 Returns
2390 Returns
2391 -------
2391 -------
2392 A dict, keyed like the input expressions dict, with the repr() of each
2392 A dict, keyed like the input expressions dict, with the repr() of each
2393 value.
2393 value.
2394 """
2394 """
2395 out = {}
2395 out = {}
2396 user_ns = self.user_ns
2396 user_ns = self.user_ns
2397 global_ns = self.user_global_ns
2397 global_ns = self.user_global_ns
2398 for key, expr in expressions.iteritems():
2398 for key, expr in expressions.iteritems():
2399 try:
2399 try:
2400 value = repr(eval(expr, global_ns, user_ns))
2400 value = repr(eval(expr, global_ns, user_ns))
2401 except:
2401 except:
2402 value = self._simple_error()
2402 value = self._simple_error()
2403 out[key] = value
2403 out[key] = value
2404 return out
2404 return out
2405
2405
2406 #-------------------------------------------------------------------------
2406 #-------------------------------------------------------------------------
2407 # Things related to the running of code
2407 # Things related to the running of code
2408 #-------------------------------------------------------------------------
2408 #-------------------------------------------------------------------------
2409
2409
2410 def ex(self, cmd):
2410 def ex(self, cmd):
2411 """Execute a normal python statement in user namespace."""
2411 """Execute a normal python statement in user namespace."""
2412 with self.builtin_trap:
2412 with self.builtin_trap:
2413 exec cmd in self.user_global_ns, self.user_ns
2413 exec cmd in self.user_global_ns, self.user_ns
2414
2414
2415 def ev(self, expr):
2415 def ev(self, expr):
2416 """Evaluate python expression expr in user namespace.
2416 """Evaluate python expression expr in user namespace.
2417
2417
2418 Returns the result of evaluation
2418 Returns the result of evaluation
2419 """
2419 """
2420 with self.builtin_trap:
2420 with self.builtin_trap:
2421 return eval(expr, self.user_global_ns, self.user_ns)
2421 return eval(expr, self.user_global_ns, self.user_ns)
2422
2422
2423 def safe_execfile(self, fname, *where, **kw):
2423 def safe_execfile(self, fname, *where, **kw):
2424 """A safe version of the builtin execfile().
2424 """A safe version of the builtin execfile().
2425
2425
2426 This version will never throw an exception, but instead print
2426 This version will never throw an exception, but instead print
2427 helpful error messages to the screen. This only works on pure
2427 helpful error messages to the screen. This only works on pure
2428 Python files with the .py extension.
2428 Python files with the .py extension.
2429
2429
2430 Parameters
2430 Parameters
2431 ----------
2431 ----------
2432 fname : string
2432 fname : string
2433 The name of the file to be executed.
2433 The name of the file to be executed.
2434 where : tuple
2434 where : tuple
2435 One or two namespaces, passed to execfile() as (globals,locals).
2435 One or two namespaces, passed to execfile() as (globals,locals).
2436 If only one is given, it is passed as both.
2436 If only one is given, it is passed as both.
2437 exit_ignore : bool (False)
2437 exit_ignore : bool (False)
2438 If True, then silence SystemExit for non-zero status (it is always
2438 If True, then silence SystemExit for non-zero status (it is always
2439 silenced for zero status, as it is so common).
2439 silenced for zero status, as it is so common).
2440 raise_exceptions : bool (False)
2440 raise_exceptions : bool (False)
2441 If True raise exceptions everywhere. Meant for testing.
2441 If True raise exceptions everywhere. Meant for testing.
2442
2442
2443 """
2443 """
2444 kw.setdefault('exit_ignore', False)
2444 kw.setdefault('exit_ignore', False)
2445 kw.setdefault('raise_exceptions', False)
2445 kw.setdefault('raise_exceptions', False)
2446
2446
2447 fname = os.path.abspath(os.path.expanduser(fname))
2447 fname = os.path.abspath(os.path.expanduser(fname))
2448
2448
2449 # Make sure we can open the file
2449 # Make sure we can open the file
2450 try:
2450 try:
2451 with open(fname) as thefile:
2451 with open(fname) as thefile:
2452 pass
2452 pass
2453 except:
2453 except:
2454 warn('Could not open file <%s> for safe execution.' % fname)
2454 warn('Could not open file <%s> for safe execution.' % fname)
2455 return
2455 return
2456
2456
2457 # Find things also in current directory. This is needed to mimic the
2457 # Find things also in current directory. This is needed to mimic the
2458 # behavior of running a script from the system command line, where
2458 # behavior of running a script from the system command line, where
2459 # Python inserts the script's directory into sys.path
2459 # Python inserts the script's directory into sys.path
2460 dname = os.path.dirname(fname)
2460 dname = os.path.dirname(fname)
2461
2461
2462 with prepended_to_syspath(dname):
2462 with prepended_to_syspath(dname):
2463 # Ensure that __file__ is always defined to match Python behavior
2463 # Ensure that __file__ is always defined to match Python behavior
2464 save_fname = self.user_ns.get('__file__',None)
2464 save_fname = self.user_ns.get('__file__',None)
2465 self.user_ns['__file__'] = fname
2465 self.user_ns['__file__'] = fname
2466 try:
2466 try:
2467 py3compat.execfile(fname,*where)
2467 py3compat.execfile(fname,*where)
2468 except SystemExit as status:
2468 except SystemExit as status:
2469 # If the call was made with 0 or None exit status (sys.exit(0)
2469 # If the call was made with 0 or None exit status (sys.exit(0)
2470 # or sys.exit() ), don't bother showing a traceback, as both of
2470 # or sys.exit() ), don't bother showing a traceback, as both of
2471 # these are considered normal by the OS:
2471 # these are considered normal by the OS:
2472 # > python -c'import sys;sys.exit(0)'; echo $?
2472 # > python -c'import sys;sys.exit(0)'; echo $?
2473 # 0
2473 # 0
2474 # > python -c'import sys;sys.exit()'; echo $?
2474 # > python -c'import sys;sys.exit()'; echo $?
2475 # 0
2475 # 0
2476 # For other exit status, we show the exception unless
2476 # For other exit status, we show the exception unless
2477 # explicitly silenced, but only in short form.
2477 # explicitly silenced, but only in short form.
2478 if kw['raise_exceptions']:
2478 if kw['raise_exceptions']:
2479 raise
2479 raise
2480 if status.code not in (0, None) and not kw['exit_ignore']:
2480 if status.code not in (0, None) and not kw['exit_ignore']:
2481 self.showtraceback(exception_only=True)
2481 self.showtraceback(exception_only=True)
2482 except:
2482 except:
2483 if kw['raise_exceptions']:
2483 if kw['raise_exceptions']:
2484 raise
2484 raise
2485 self.showtraceback()
2485 self.showtraceback()
2486 finally:
2486 finally:
2487 self.user_ns['__file__'] = save_fname
2487 self.user_ns['__file__'] = save_fname
2488
2488
2489 def safe_execfile_ipy(self, fname):
2489 def safe_execfile_ipy(self, fname):
2490 """Like safe_execfile, but for .ipy files with IPython syntax.
2490 """Like safe_execfile, but for .ipy files with IPython syntax.
2491
2491
2492 Parameters
2492 Parameters
2493 ----------
2493 ----------
2494 fname : str
2494 fname : str
2495 The name of the file to execute. The filename must have a
2495 The name of the file to execute. The filename must have a
2496 .ipy extension.
2496 .ipy extension.
2497 """
2497 """
2498 fname = os.path.abspath(os.path.expanduser(fname))
2498 fname = os.path.abspath(os.path.expanduser(fname))
2499
2499
2500 # Make sure we can open the file
2500 # Make sure we can open the file
2501 try:
2501 try:
2502 with open(fname) as thefile:
2502 with open(fname) as thefile:
2503 pass
2503 pass
2504 except:
2504 except:
2505 warn('Could not open file <%s> for safe execution.' % fname)
2505 warn('Could not open file <%s> for safe execution.' % fname)
2506 return
2506 return
2507
2507
2508 # Find things also in current directory. This is needed to mimic the
2508 # Find things also in current directory. This is needed to mimic the
2509 # behavior of running a script from the system command line, where
2509 # behavior of running a script from the system command line, where
2510 # Python inserts the script's directory into sys.path
2510 # Python inserts the script's directory into sys.path
2511 dname = os.path.dirname(fname)
2511 dname = os.path.dirname(fname)
2512
2512
2513 with prepended_to_syspath(dname):
2513 with prepended_to_syspath(dname):
2514 # Ensure that __file__ is always defined to match Python behavior
2514 # Ensure that __file__ is always defined to match Python behavior
2515 save_fname = self.user_ns.get('__file__',None)
2515 save_fname = self.user_ns.get('__file__',None)
2516 self.user_ns['__file__'] = fname
2516 self.user_ns['__file__'] = fname
2517 try:
2517 try:
2518 with open(fname) as thefile:
2518 with open(fname) as thefile:
2519 # self.run_cell currently captures all exceptions
2519 # self.run_cell currently captures all exceptions
2520 # raised in user code. It would be nice if there were
2520 # raised in user code. It would be nice if there were
2521 # versions of runlines, execfile that did raise, so
2521 # versions of runlines, execfile that did raise, so
2522 # we could catch the errors.
2522 # we could catch the errors.
2523 self.run_cell(thefile.read(), store_history=False)
2523 self.run_cell(thefile.read(), store_history=False)
2524 except:
2524 except:
2525 self.showtraceback()
2525 self.showtraceback()
2526 warn('Unknown failure executing file: <%s>' % fname)
2526 warn('Unknown failure executing file: <%s>' % fname)
2527 finally:
2527 finally:
2528 self.user_ns['__file__'] = save_fname
2528 self.user_ns['__file__'] = save_fname
2529
2529
2530 def safe_run_module(self, mod_name, where):
2530 def safe_run_module(self, mod_name, where):
2531 """A safe version of runpy.run_module().
2531 """A safe version of runpy.run_module().
2532
2532
2533 This version will never throw an exception, but instead print
2533 This version will never throw an exception, but instead print
2534 helpful error messages to the screen.
2534 helpful error messages to the screen.
2535
2535
2536 Parameters
2536 Parameters
2537 ----------
2537 ----------
2538 mod_name : string
2538 mod_name : string
2539 The name of the module to be executed.
2539 The name of the module to be executed.
2540 where : dict
2540 where : dict
2541 The globals namespace.
2541 The globals namespace.
2542 """
2542 """
2543 try:
2543 try:
2544 where.update(
2544 where.update(
2545 runpy.run_module(str(mod_name), run_name="__main__",
2545 runpy.run_module(str(mod_name), run_name="__main__",
2546 alter_sys=True)
2546 alter_sys=True)
2547 )
2547 )
2548 except:
2548 except:
2549 self.showtraceback()
2549 self.showtraceback()
2550 warn('Unknown failure executing module: <%s>' % mod_name)
2550 warn('Unknown failure executing module: <%s>' % mod_name)
2551
2551
2552 def _run_cached_cell_magic(self, magic_name, line):
2552 def _run_cached_cell_magic(self, magic_name, line):
2553 """Special method to call a cell magic with the data stored in self.
2553 """Special method to call a cell magic with the data stored in self.
2554 """
2554 """
2555 cell = self._current_cell_magic_body
2555 cell = self._current_cell_magic_body
2556 self._current_cell_magic_body = None
2556 self._current_cell_magic_body = None
2557 return self.run_cell_magic(magic_name, line, cell)
2557 return self.run_cell_magic(magic_name, line, cell)
2558
2558
2559 def run_cell(self, raw_cell, store_history=False, silent=False):
2559 def run_cell(self, raw_cell, store_history=False, silent=False):
2560 """Run a complete IPython cell.
2560 """Run a complete IPython cell.
2561
2561
2562 Parameters
2562 Parameters
2563 ----------
2563 ----------
2564 raw_cell : str
2564 raw_cell : str
2565 The code (including IPython code such as %magic functions) to run.
2565 The code (including IPython code such as %magic functions) to run.
2566 store_history : bool
2566 store_history : bool
2567 If True, the raw and translated cell will be stored in IPython's
2567 If True, the raw and translated cell will be stored in IPython's
2568 history. For user code calling back into IPython's machinery, this
2568 history. For user code calling back into IPython's machinery, this
2569 should be set to False.
2569 should be set to False.
2570 silent : bool
2570 silent : bool
2571 If True, avoid side-effets, such as implicit displayhooks, history,
2571 If True, avoid side-effects, such as implicit displayhooks and
2572 and logging. silent=True forces store_history=False.
2572 and logging. silent=True forces store_history=False.
2573 """
2573 """
2574 if (not raw_cell) or raw_cell.isspace():
2574 if (not raw_cell) or raw_cell.isspace():
2575 return
2575 return
2576
2576
2577 if silent:
2577 if silent:
2578 store_history = False
2578 store_history = False
2579
2579
2580 self.input_splitter.push(raw_cell)
2580 self.input_splitter.push(raw_cell)
2581
2581
2582 # Check for cell magics, which leave state behind. This interface is
2582 # Check for cell magics, which leave state behind. This interface is
2583 # ugly, we need to do something cleaner later... Now the logic is
2583 # ugly, we need to do something cleaner later... Now the logic is
2584 # simply that the input_splitter remembers if there was a cell magic,
2584 # simply that the input_splitter remembers if there was a cell magic,
2585 # and in that case we grab the cell body.
2585 # and in that case we grab the cell body.
2586 if self.input_splitter.cell_magic_parts:
2586 if self.input_splitter.cell_magic_parts:
2587 self._current_cell_magic_body = \
2587 self._current_cell_magic_body = \
2588 ''.join(self.input_splitter.cell_magic_parts)
2588 ''.join(self.input_splitter.cell_magic_parts)
2589 cell = self.input_splitter.source_reset()
2589 cell = self.input_splitter.source_reset()
2590
2590
2591 with self.builtin_trap:
2591 with self.builtin_trap:
2592 prefilter_failed = False
2592 prefilter_failed = False
2593 if len(cell.splitlines()) == 1:
2593 if len(cell.splitlines()) == 1:
2594 try:
2594 try:
2595 # use prefilter_lines to handle trailing newlines
2595 # use prefilter_lines to handle trailing newlines
2596 # restore trailing newline for ast.parse
2596 # restore trailing newline for ast.parse
2597 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2597 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2598 except AliasError as e:
2598 except AliasError as e:
2599 error(e)
2599 error(e)
2600 prefilter_failed = True
2600 prefilter_failed = True
2601 except Exception:
2601 except Exception:
2602 # don't allow prefilter errors to crash IPython
2602 # don't allow prefilter errors to crash IPython
2603 self.showtraceback()
2603 self.showtraceback()
2604 prefilter_failed = True
2604 prefilter_failed = True
2605
2605
2606 # Store raw and processed history
2606 # Store raw and processed history
2607 if store_history:
2607 if store_history:
2608 self.history_manager.store_inputs(self.execution_count,
2608 self.history_manager.store_inputs(self.execution_count,
2609 cell, raw_cell)
2609 cell, raw_cell)
2610 if not silent:
2610 if not silent:
2611 self.logger.log(cell, raw_cell)
2611 self.logger.log(cell, raw_cell)
2612
2612
2613 if not prefilter_failed:
2613 if not prefilter_failed:
2614 # don't run if prefilter failed
2614 # don't run if prefilter failed
2615 cell_name = self.compile.cache(cell, self.execution_count)
2615 cell_name = self.compile.cache(cell, self.execution_count)
2616
2616
2617 with self.display_trap:
2617 with self.display_trap:
2618 try:
2618 try:
2619 code_ast = self.compile.ast_parse(cell,
2619 code_ast = self.compile.ast_parse(cell,
2620 filename=cell_name)
2620 filename=cell_name)
2621 except IndentationError:
2621 except IndentationError:
2622 self.showindentationerror()
2622 self.showindentationerror()
2623 if store_history:
2623 if store_history:
2624 self.execution_count += 1
2624 self.execution_count += 1
2625 return None
2625 return None
2626 except (OverflowError, SyntaxError, ValueError, TypeError,
2626 except (OverflowError, SyntaxError, ValueError, TypeError,
2627 MemoryError):
2627 MemoryError):
2628 self.showsyntaxerror()
2628 self.showsyntaxerror()
2629 if store_history:
2629 if store_history:
2630 self.execution_count += 1
2630 self.execution_count += 1
2631 return None
2631 return None
2632
2632
2633 interactivity = "none" if silent else self.ast_node_interactivity
2633 interactivity = "none" if silent else self.ast_node_interactivity
2634 self.run_ast_nodes(code_ast.body, cell_name,
2634 self.run_ast_nodes(code_ast.body, cell_name,
2635 interactivity=interactivity)
2635 interactivity=interactivity)
2636
2636
2637 # Execute any registered post-execution functions.
2637 # Execute any registered post-execution functions.
2638 # unless we are silent
2638 # unless we are silent
2639 post_exec = [] if silent else self._post_execute.iteritems()
2639 post_exec = [] if silent else self._post_execute.iteritems()
2640
2640
2641 for func, status in post_exec:
2641 for func, status in post_exec:
2642 if self.disable_failing_post_execute and not status:
2642 if self.disable_failing_post_execute and not status:
2643 continue
2643 continue
2644 try:
2644 try:
2645 func()
2645 func()
2646 except KeyboardInterrupt:
2646 except KeyboardInterrupt:
2647 print("\nKeyboardInterrupt", file=io.stderr)
2647 print("\nKeyboardInterrupt", file=io.stderr)
2648 except Exception:
2648 except Exception:
2649 # register as failing:
2649 # register as failing:
2650 self._post_execute[func] = False
2650 self._post_execute[func] = False
2651 self.showtraceback()
2651 self.showtraceback()
2652 print('\n'.join([
2652 print('\n'.join([
2653 "post-execution function %r produced an error." % func,
2653 "post-execution function %r produced an error." % func,
2654 "If this problem persists, you can disable failing post-exec functions with:",
2654 "If this problem persists, you can disable failing post-exec functions with:",
2655 "",
2655 "",
2656 " get_ipython().disable_failing_post_execute = True"
2656 " get_ipython().disable_failing_post_execute = True"
2657 ]), file=io.stderr)
2657 ]), file=io.stderr)
2658
2658
2659 if store_history:
2659 if store_history:
2660 # Write output to the database. Does nothing unless
2660 # Write output to the database. Does nothing unless
2661 # history output logging is enabled.
2661 # history output logging is enabled.
2662 self.history_manager.store_output(self.execution_count)
2662 self.history_manager.store_output(self.execution_count)
2663 # Each cell is a *single* input, regardless of how many lines it has
2663 # Each cell is a *single* input, regardless of how many lines it has
2664 self.execution_count += 1
2664 self.execution_count += 1
2665
2665
2666 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2666 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2667 """Run a sequence of AST nodes. The execution mode depends on the
2667 """Run a sequence of AST nodes. The execution mode depends on the
2668 interactivity parameter.
2668 interactivity parameter.
2669
2669
2670 Parameters
2670 Parameters
2671 ----------
2671 ----------
2672 nodelist : list
2672 nodelist : list
2673 A sequence of AST nodes to run.
2673 A sequence of AST nodes to run.
2674 cell_name : str
2674 cell_name : str
2675 Will be passed to the compiler as the filename of the cell. Typically
2675 Will be passed to the compiler as the filename of the cell. Typically
2676 the value returned by ip.compile.cache(cell).
2676 the value returned by ip.compile.cache(cell).
2677 interactivity : str
2677 interactivity : str
2678 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2678 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2679 run interactively (displaying output from expressions). 'last_expr'
2679 run interactively (displaying output from expressions). 'last_expr'
2680 will run the last node interactively only if it is an expression (i.e.
2680 will run the last node interactively only if it is an expression (i.e.
2681 expressions in loops or other blocks are not displayed. Other values
2681 expressions in loops or other blocks are not displayed. Other values
2682 for this parameter will raise a ValueError.
2682 for this parameter will raise a ValueError.
2683 """
2683 """
2684 if not nodelist:
2684 if not nodelist:
2685 return
2685 return
2686
2686
2687 if interactivity == 'last_expr':
2687 if interactivity == 'last_expr':
2688 if isinstance(nodelist[-1], ast.Expr):
2688 if isinstance(nodelist[-1], ast.Expr):
2689 interactivity = "last"
2689 interactivity = "last"
2690 else:
2690 else:
2691 interactivity = "none"
2691 interactivity = "none"
2692
2692
2693 if interactivity == 'none':
2693 if interactivity == 'none':
2694 to_run_exec, to_run_interactive = nodelist, []
2694 to_run_exec, to_run_interactive = nodelist, []
2695 elif interactivity == 'last':
2695 elif interactivity == 'last':
2696 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2696 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2697 elif interactivity == 'all':
2697 elif interactivity == 'all':
2698 to_run_exec, to_run_interactive = [], nodelist
2698 to_run_exec, to_run_interactive = [], nodelist
2699 else:
2699 else:
2700 raise ValueError("Interactivity was %r" % interactivity)
2700 raise ValueError("Interactivity was %r" % interactivity)
2701
2701
2702 exec_count = self.execution_count
2702 exec_count = self.execution_count
2703
2703
2704 try:
2704 try:
2705 for i, node in enumerate(to_run_exec):
2705 for i, node in enumerate(to_run_exec):
2706 mod = ast.Module([node])
2706 mod = ast.Module([node])
2707 code = self.compile(mod, cell_name, "exec")
2707 code = self.compile(mod, cell_name, "exec")
2708 if self.run_code(code):
2708 if self.run_code(code):
2709 return True
2709 return True
2710
2710
2711 for i, node in enumerate(to_run_interactive):
2711 for i, node in enumerate(to_run_interactive):
2712 mod = ast.Interactive([node])
2712 mod = ast.Interactive([node])
2713 code = self.compile(mod, cell_name, "single")
2713 code = self.compile(mod, cell_name, "single")
2714 if self.run_code(code):
2714 if self.run_code(code):
2715 return True
2715 return True
2716
2716
2717 # Flush softspace
2717 # Flush softspace
2718 if softspace(sys.stdout, 0):
2718 if softspace(sys.stdout, 0):
2719 print()
2719 print()
2720
2720
2721 except:
2721 except:
2722 # It's possible to have exceptions raised here, typically by
2722 # It's possible to have exceptions raised here, typically by
2723 # compilation of odd code (such as a naked 'return' outside a
2723 # compilation of odd code (such as a naked 'return' outside a
2724 # function) that did parse but isn't valid. Typically the exception
2724 # function) that did parse but isn't valid. Typically the exception
2725 # is a SyntaxError, but it's safest just to catch anything and show
2725 # is a SyntaxError, but it's safest just to catch anything and show
2726 # the user a traceback.
2726 # the user a traceback.
2727
2727
2728 # We do only one try/except outside the loop to minimize the impact
2728 # We do only one try/except outside the loop to minimize the impact
2729 # on runtime, and also because if any node in the node list is
2729 # on runtime, and also because if any node in the node list is
2730 # broken, we should stop execution completely.
2730 # broken, we should stop execution completely.
2731 self.showtraceback()
2731 self.showtraceback()
2732
2732
2733 return False
2733 return False
2734
2734
2735 def run_code(self, code_obj):
2735 def run_code(self, code_obj):
2736 """Execute a code object.
2736 """Execute a code object.
2737
2737
2738 When an exception occurs, self.showtraceback() is called to display a
2738 When an exception occurs, self.showtraceback() is called to display a
2739 traceback.
2739 traceback.
2740
2740
2741 Parameters
2741 Parameters
2742 ----------
2742 ----------
2743 code_obj : code object
2743 code_obj : code object
2744 A compiled code object, to be executed
2744 A compiled code object, to be executed
2745
2745
2746 Returns
2746 Returns
2747 -------
2747 -------
2748 False : successful execution.
2748 False : successful execution.
2749 True : an error occurred.
2749 True : an error occurred.
2750 """
2750 """
2751
2751
2752 # Set our own excepthook in case the user code tries to call it
2752 # Set our own excepthook in case the user code tries to call it
2753 # directly, so that the IPython crash handler doesn't get triggered
2753 # directly, so that the IPython crash handler doesn't get triggered
2754 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2754 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2755
2755
2756 # we save the original sys.excepthook in the instance, in case config
2756 # we save the original sys.excepthook in the instance, in case config
2757 # code (such as magics) needs access to it.
2757 # code (such as magics) needs access to it.
2758 self.sys_excepthook = old_excepthook
2758 self.sys_excepthook = old_excepthook
2759 outflag = 1 # happens in more places, so it's easier as default
2759 outflag = 1 # happens in more places, so it's easier as default
2760 try:
2760 try:
2761 try:
2761 try:
2762 self.hooks.pre_run_code_hook()
2762 self.hooks.pre_run_code_hook()
2763 #rprint('Running code', repr(code_obj)) # dbg
2763 #rprint('Running code', repr(code_obj)) # dbg
2764 exec code_obj in self.user_global_ns, self.user_ns
2764 exec code_obj in self.user_global_ns, self.user_ns
2765 finally:
2765 finally:
2766 # Reset our crash handler in place
2766 # Reset our crash handler in place
2767 sys.excepthook = old_excepthook
2767 sys.excepthook = old_excepthook
2768 except SystemExit:
2768 except SystemExit:
2769 self.showtraceback(exception_only=True)
2769 self.showtraceback(exception_only=True)
2770 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2770 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2771 except self.custom_exceptions:
2771 except self.custom_exceptions:
2772 etype,value,tb = sys.exc_info()
2772 etype,value,tb = sys.exc_info()
2773 self.CustomTB(etype,value,tb)
2773 self.CustomTB(etype,value,tb)
2774 except:
2774 except:
2775 self.showtraceback()
2775 self.showtraceback()
2776 else:
2776 else:
2777 outflag = 0
2777 outflag = 0
2778 return outflag
2778 return outflag
2779
2779
2780 # For backwards compatibility
2780 # For backwards compatibility
2781 runcode = run_code
2781 runcode = run_code
2782
2782
2783 #-------------------------------------------------------------------------
2783 #-------------------------------------------------------------------------
2784 # Things related to GUI support and pylab
2784 # Things related to GUI support and pylab
2785 #-------------------------------------------------------------------------
2785 #-------------------------------------------------------------------------
2786
2786
2787 def enable_gui(self, gui=None):
2787 def enable_gui(self, gui=None):
2788 raise NotImplementedError('Implement enable_gui in a subclass')
2788 raise NotImplementedError('Implement enable_gui in a subclass')
2789
2789
2790 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2790 def enable_pylab(self, gui=None, import_all=True, welcome_message=False):
2791 """Activate pylab support at runtime.
2791 """Activate pylab support at runtime.
2792
2792
2793 This turns on support for matplotlib, preloads into the interactive
2793 This turns on support for matplotlib, preloads into the interactive
2794 namespace all of numpy and pylab, and configures IPython to correctly
2794 namespace all of numpy and pylab, and configures IPython to correctly
2795 interact with the GUI event loop. The GUI backend to be used can be
2795 interact with the GUI event loop. The GUI backend to be used can be
2796 optionally selected with the optional :param:`gui` argument.
2796 optionally selected with the optional :param:`gui` argument.
2797
2797
2798 Parameters
2798 Parameters
2799 ----------
2799 ----------
2800 gui : optional, string
2800 gui : optional, string
2801
2801
2802 If given, dictates the choice of matplotlib GUI backend to use
2802 If given, dictates the choice of matplotlib GUI backend to use
2803 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2803 (should be one of IPython's supported backends, 'qt', 'osx', 'tk',
2804 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2804 'gtk', 'wx' or 'inline'), otherwise we use the default chosen by
2805 matplotlib (as dictated by the matplotlib build-time options plus the
2805 matplotlib (as dictated by the matplotlib build-time options plus the
2806 user's matplotlibrc configuration file). Note that not all backends
2806 user's matplotlibrc configuration file). Note that not all backends
2807 make sense in all contexts, for example a terminal ipython can't
2807 make sense in all contexts, for example a terminal ipython can't
2808 display figures inline.
2808 display figures inline.
2809 """
2809 """
2810 from IPython.core.pylabtools import mpl_runner
2810 from IPython.core.pylabtools import mpl_runner
2811 # We want to prevent the loading of pylab to pollute the user's
2811 # We want to prevent the loading of pylab to pollute the user's
2812 # namespace as shown by the %who* magics, so we execute the activation
2812 # namespace as shown by the %who* magics, so we execute the activation
2813 # code in an empty namespace, and we update *both* user_ns and
2813 # code in an empty namespace, and we update *both* user_ns and
2814 # user_ns_hidden with this information.
2814 # user_ns_hidden with this information.
2815 ns = {}
2815 ns = {}
2816 try:
2816 try:
2817 gui = pylab_activate(ns, gui, import_all, self, welcome_message=welcome_message)
2817 gui = pylab_activate(ns, gui, import_all, self, welcome_message=welcome_message)
2818 except KeyError:
2818 except KeyError:
2819 error("Backend %r not supported" % gui)
2819 error("Backend %r not supported" % gui)
2820 return
2820 return
2821 self.user_ns.update(ns)
2821 self.user_ns.update(ns)
2822 self.user_ns_hidden.update(ns)
2822 self.user_ns_hidden.update(ns)
2823 # Now we must activate the gui pylab wants to use, and fix %run to take
2823 # Now we must activate the gui pylab wants to use, and fix %run to take
2824 # plot updates into account
2824 # plot updates into account
2825 self.enable_gui(gui)
2825 self.enable_gui(gui)
2826 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2826 self.magics_manager.registry['ExecutionMagics'].default_runner = \
2827 mpl_runner(self.safe_execfile)
2827 mpl_runner(self.safe_execfile)
2828
2828
2829 #-------------------------------------------------------------------------
2829 #-------------------------------------------------------------------------
2830 # Utilities
2830 # Utilities
2831 #-------------------------------------------------------------------------
2831 #-------------------------------------------------------------------------
2832
2832
2833 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2833 def var_expand(self, cmd, depth=0, formatter=DollarFormatter()):
2834 """Expand python variables in a string.
2834 """Expand python variables in a string.
2835
2835
2836 The depth argument indicates how many frames above the caller should
2836 The depth argument indicates how many frames above the caller should
2837 be walked to look for the local namespace where to expand variables.
2837 be walked to look for the local namespace where to expand variables.
2838
2838
2839 The global namespace for expansion is always the user's interactive
2839 The global namespace for expansion is always the user's interactive
2840 namespace.
2840 namespace.
2841 """
2841 """
2842 ns = self.user_ns.copy()
2842 ns = self.user_ns.copy()
2843 ns.update(sys._getframe(depth+1).f_locals)
2843 ns.update(sys._getframe(depth+1).f_locals)
2844 try:
2844 try:
2845 # We have to use .vformat() here, because 'self' is a valid and common
2845 # We have to use .vformat() here, because 'self' is a valid and common
2846 # name, and expanding **ns for .format() would make it collide with
2846 # name, and expanding **ns for .format() would make it collide with
2847 # the 'self' argument of the method.
2847 # the 'self' argument of the method.
2848 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2848 cmd = formatter.vformat(cmd, args=[], kwargs=ns)
2849 except Exception:
2849 except Exception:
2850 # if formatter couldn't format, just let it go untransformed
2850 # if formatter couldn't format, just let it go untransformed
2851 pass
2851 pass
2852 return cmd
2852 return cmd
2853
2853
2854 def mktempfile(self, data=None, prefix='ipython_edit_'):
2854 def mktempfile(self, data=None, prefix='ipython_edit_'):
2855 """Make a new tempfile and return its filename.
2855 """Make a new tempfile and return its filename.
2856
2856
2857 This makes a call to tempfile.mktemp, but it registers the created
2857 This makes a call to tempfile.mktemp, but it registers the created
2858 filename internally so ipython cleans it up at exit time.
2858 filename internally so ipython cleans it up at exit time.
2859
2859
2860 Optional inputs:
2860 Optional inputs:
2861
2861
2862 - data(None): if data is given, it gets written out to the temp file
2862 - data(None): if data is given, it gets written out to the temp file
2863 immediately, and the file is closed again."""
2863 immediately, and the file is closed again."""
2864
2864
2865 filename = tempfile.mktemp('.py', prefix)
2865 filename = tempfile.mktemp('.py', prefix)
2866 self.tempfiles.append(filename)
2866 self.tempfiles.append(filename)
2867
2867
2868 if data:
2868 if data:
2869 tmp_file = open(filename,'w')
2869 tmp_file = open(filename,'w')
2870 tmp_file.write(data)
2870 tmp_file.write(data)
2871 tmp_file.close()
2871 tmp_file.close()
2872 return filename
2872 return filename
2873
2873
2874 # TODO: This should be removed when Term is refactored.
2874 # TODO: This should be removed when Term is refactored.
2875 def write(self,data):
2875 def write(self,data):
2876 """Write a string to the default output"""
2876 """Write a string to the default output"""
2877 io.stdout.write(data)
2877 io.stdout.write(data)
2878
2878
2879 # TODO: This should be removed when Term is refactored.
2879 # TODO: This should be removed when Term is refactored.
2880 def write_err(self,data):
2880 def write_err(self,data):
2881 """Write a string to the default error output"""
2881 """Write a string to the default error output"""
2882 io.stderr.write(data)
2882 io.stderr.write(data)
2883
2883
2884 def ask_yes_no(self, prompt, default=None):
2884 def ask_yes_no(self, prompt, default=None):
2885 if self.quiet:
2885 if self.quiet:
2886 return True
2886 return True
2887 return ask_yes_no(prompt,default)
2887 return ask_yes_no(prompt,default)
2888
2888
2889 def show_usage(self):
2889 def show_usage(self):
2890 """Show a usage message"""
2890 """Show a usage message"""
2891 page.page(IPython.core.usage.interactive_usage)
2891 page.page(IPython.core.usage.interactive_usage)
2892
2892
2893 def extract_input_lines(self, range_str, raw=False):
2893 def extract_input_lines(self, range_str, raw=False):
2894 """Return as a string a set of input history slices.
2894 """Return as a string a set of input history slices.
2895
2895
2896 Parameters
2896 Parameters
2897 ----------
2897 ----------
2898 range_str : string
2898 range_str : string
2899 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
2899 The set of slices is given as a string, like "~5/6-~4/2 4:8 9",
2900 since this function is for use by magic functions which get their
2900 since this function is for use by magic functions which get their
2901 arguments as strings. The number before the / is the session
2901 arguments as strings. The number before the / is the session
2902 number: ~n goes n back from the current session.
2902 number: ~n goes n back from the current session.
2903
2903
2904 Optional Parameters:
2904 Optional Parameters:
2905 - raw(False): by default, the processed input is used. If this is
2905 - raw(False): by default, the processed input is used. If this is
2906 true, the raw input history is used instead.
2906 true, the raw input history is used instead.
2907
2907
2908 Note that slices can be called with two notations:
2908 Note that slices can be called with two notations:
2909
2909
2910 N:M -> standard python form, means including items N...(M-1).
2910 N:M -> standard python form, means including items N...(M-1).
2911
2911
2912 N-M -> include items N..M (closed endpoint)."""
2912 N-M -> include items N..M (closed endpoint)."""
2913 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
2913 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
2914 return "\n".join(x for _, _, x in lines)
2914 return "\n".join(x for _, _, x in lines)
2915
2915
2916 def find_user_code(self, target, raw=True, py_only=False):
2916 def find_user_code(self, target, raw=True, py_only=False):
2917 """Get a code string from history, file, url, or a string or macro.
2917 """Get a code string from history, file, url, or a string or macro.
2918
2918
2919 This is mainly used by magic functions.
2919 This is mainly used by magic functions.
2920
2920
2921 Parameters
2921 Parameters
2922 ----------
2922 ----------
2923
2923
2924 target : str
2924 target : str
2925
2925
2926 A string specifying code to retrieve. This will be tried respectively
2926 A string specifying code to retrieve. This will be tried respectively
2927 as: ranges of input history (see %history for syntax), url,
2927 as: ranges of input history (see %history for syntax), url,
2928 correspnding .py file, filename, or an expression evaluating to a
2928 correspnding .py file, filename, or an expression evaluating to a
2929 string or Macro in the user namespace.
2929 string or Macro in the user namespace.
2930
2930
2931 raw : bool
2931 raw : bool
2932 If true (default), retrieve raw history. Has no effect on the other
2932 If true (default), retrieve raw history. Has no effect on the other
2933 retrieval mechanisms.
2933 retrieval mechanisms.
2934
2934
2935 py_only : bool (default False)
2935 py_only : bool (default False)
2936 Only try to fetch python code, do not try alternative methods to decode file
2936 Only try to fetch python code, do not try alternative methods to decode file
2937 if unicode fails.
2937 if unicode fails.
2938
2938
2939 Returns
2939 Returns
2940 -------
2940 -------
2941 A string of code.
2941 A string of code.
2942
2942
2943 ValueError is raised if nothing is found, and TypeError if it evaluates
2943 ValueError is raised if nothing is found, and TypeError if it evaluates
2944 to an object of another type. In each case, .args[0] is a printable
2944 to an object of another type. In each case, .args[0] is a printable
2945 message.
2945 message.
2946 """
2946 """
2947 code = self.extract_input_lines(target, raw=raw) # Grab history
2947 code = self.extract_input_lines(target, raw=raw) # Grab history
2948 if code:
2948 if code:
2949 return code
2949 return code
2950 utarget = unquote_filename(target)
2950 utarget = unquote_filename(target)
2951 try:
2951 try:
2952 if utarget.startswith(('http://', 'https://')):
2952 if utarget.startswith(('http://', 'https://')):
2953 return openpy.read_py_url(utarget, skip_encoding_cookie=True)
2953 return openpy.read_py_url(utarget, skip_encoding_cookie=True)
2954 except UnicodeDecodeError:
2954 except UnicodeDecodeError:
2955 if not py_only :
2955 if not py_only :
2956 response = urllib.urlopen(target)
2956 response = urllib.urlopen(target)
2957 return response.read().decode('latin1')
2957 return response.read().decode('latin1')
2958 raise ValueError(("'%s' seem to be unreadable.") % utarget)
2958 raise ValueError(("'%s' seem to be unreadable.") % utarget)
2959
2959
2960 potential_target = [target]
2960 potential_target = [target]
2961 try :
2961 try :
2962 potential_target.insert(0,get_py_filename(target))
2962 potential_target.insert(0,get_py_filename(target))
2963 except IOError:
2963 except IOError:
2964 pass
2964 pass
2965
2965
2966 for tgt in potential_target :
2966 for tgt in potential_target :
2967 if os.path.isfile(tgt): # Read file
2967 if os.path.isfile(tgt): # Read file
2968 try :
2968 try :
2969 return openpy.read_py_file(tgt, skip_encoding_cookie=True)
2969 return openpy.read_py_file(tgt, skip_encoding_cookie=True)
2970 except UnicodeDecodeError :
2970 except UnicodeDecodeError :
2971 if not py_only :
2971 if not py_only :
2972 with io_open(tgt,'r', encoding='latin1') as f :
2972 with io_open(tgt,'r', encoding='latin1') as f :
2973 return f.read()
2973 return f.read()
2974 raise ValueError(("'%s' seem to be unreadable.") % target)
2974 raise ValueError(("'%s' seem to be unreadable.") % target)
2975
2975
2976 try: # User namespace
2976 try: # User namespace
2977 codeobj = eval(target, self.user_ns)
2977 codeobj = eval(target, self.user_ns)
2978 except Exception:
2978 except Exception:
2979 raise ValueError(("'%s' was not found in history, as a file, url, "
2979 raise ValueError(("'%s' was not found in history, as a file, url, "
2980 "nor in the user namespace.") % target)
2980 "nor in the user namespace.") % target)
2981 if isinstance(codeobj, basestring):
2981 if isinstance(codeobj, basestring):
2982 return codeobj
2982 return codeobj
2983 elif isinstance(codeobj, Macro):
2983 elif isinstance(codeobj, Macro):
2984 return codeobj.value
2984 return codeobj.value
2985
2985
2986 raise TypeError("%s is neither a string nor a macro." % target,
2986 raise TypeError("%s is neither a string nor a macro." % target,
2987 codeobj)
2987 codeobj)
2988
2988
2989 #-------------------------------------------------------------------------
2989 #-------------------------------------------------------------------------
2990 # Things related to IPython exiting
2990 # Things related to IPython exiting
2991 #-------------------------------------------------------------------------
2991 #-------------------------------------------------------------------------
2992 def atexit_operations(self):
2992 def atexit_operations(self):
2993 """This will be executed at the time of exit.
2993 """This will be executed at the time of exit.
2994
2994
2995 Cleanup operations and saving of persistent data that is done
2995 Cleanup operations and saving of persistent data that is done
2996 unconditionally by IPython should be performed here.
2996 unconditionally by IPython should be performed here.
2997
2997
2998 For things that may depend on startup flags or platform specifics (such
2998 For things that may depend on startup flags or platform specifics (such
2999 as having readline or not), register a separate atexit function in the
2999 as having readline or not), register a separate atexit function in the
3000 code that has the appropriate information, rather than trying to
3000 code that has the appropriate information, rather than trying to
3001 clutter
3001 clutter
3002 """
3002 """
3003 # Close the history session (this stores the end time and line count)
3003 # Close the history session (this stores the end time and line count)
3004 # this must be *before* the tempfile cleanup, in case of temporary
3004 # this must be *before* the tempfile cleanup, in case of temporary
3005 # history db
3005 # history db
3006 self.history_manager.end_session()
3006 self.history_manager.end_session()
3007
3007
3008 # Cleanup all tempfiles left around
3008 # Cleanup all tempfiles left around
3009 for tfile in self.tempfiles:
3009 for tfile in self.tempfiles:
3010 try:
3010 try:
3011 os.unlink(tfile)
3011 os.unlink(tfile)
3012 except OSError:
3012 except OSError:
3013 pass
3013 pass
3014
3014
3015 # Clear all user namespaces to release all references cleanly.
3015 # Clear all user namespaces to release all references cleanly.
3016 self.reset(new_session=False)
3016 self.reset(new_session=False)
3017
3017
3018 # Run user hooks
3018 # Run user hooks
3019 self.hooks.shutdown_hook()
3019 self.hooks.shutdown_hook()
3020
3020
3021 def cleanup(self):
3021 def cleanup(self):
3022 self.restore_sys_module_state()
3022 self.restore_sys_module_state()
3023
3023
3024
3024
3025 class InteractiveShellABC(object):
3025 class InteractiveShellABC(object):
3026 """An abstract base class for InteractiveShell."""
3026 """An abstract base class for InteractiveShell."""
3027 __metaclass__ = abc.ABCMeta
3027 __metaclass__ = abc.ABCMeta
3028
3028
3029 InteractiveShellABC.register(InteractiveShell)
3029 InteractiveShellABC.register(InteractiveShell)
@@ -1,930 +1,931 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 """A simple interactive kernel that talks to a frontend over 0MQ.
2 """A simple interactive kernel that talks to a frontend over 0MQ.
3
3
4 Things to do:
4 Things to do:
5
5
6 * Implement `set_parent` logic. Right before doing exec, the Kernel should
6 * Implement `set_parent` logic. Right before doing exec, the Kernel should
7 call set_parent on all the PUB objects with the message about to be executed.
7 call set_parent on all the PUB objects with the message about to be executed.
8 * Implement random port and security key logic.
8 * Implement random port and security key logic.
9 * Implement control messages.
9 * Implement control messages.
10 * Implement event loop and poll version.
10 * Implement event loop and poll version.
11 """
11 """
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 from __future__ import print_function
16 from __future__ import print_function
17
17
18 # Standard library imports
18 # Standard library imports
19 import __builtin__
19 import __builtin__
20 import atexit
20 import atexit
21 import sys
21 import sys
22 import time
22 import time
23 import traceback
23 import traceback
24 import logging
24 import logging
25 import uuid
25 import uuid
26
26
27 from datetime import datetime
27 from datetime import datetime
28 from signal import (
28 from signal import (
29 signal, getsignal, default_int_handler, SIGINT, SIG_IGN
29 signal, getsignal, default_int_handler, SIGINT, SIG_IGN
30 )
30 )
31
31
32 # System library imports
32 # System library imports
33 import zmq
33 import zmq
34 from zmq.eventloop import ioloop
34 from zmq.eventloop import ioloop
35 from zmq.eventloop.zmqstream import ZMQStream
35 from zmq.eventloop.zmqstream import ZMQStream
36
36
37 # Local imports
37 # Local imports
38 from IPython.config.configurable import Configurable
38 from IPython.config.configurable import Configurable
39 from IPython.config.application import boolean_flag, catch_config_error
39 from IPython.config.application import boolean_flag, catch_config_error
40 from IPython.core.application import ProfileDir
40 from IPython.core.application import ProfileDir
41 from IPython.core.error import StdinNotImplementedError
41 from IPython.core.error import StdinNotImplementedError
42 from IPython.core.shellapp import (
42 from IPython.core.shellapp import (
43 InteractiveShellApp, shell_flags, shell_aliases
43 InteractiveShellApp, shell_flags, shell_aliases
44 )
44 )
45 from IPython.utils import io
45 from IPython.utils import io
46 from IPython.utils import py3compat
46 from IPython.utils import py3compat
47 from IPython.utils.frame import extract_module_locals
47 from IPython.utils.frame import extract_module_locals
48 from IPython.utils.jsonutil import json_clean
48 from IPython.utils.jsonutil import json_clean
49 from IPython.utils.traitlets import (
49 from IPython.utils.traitlets import (
50 Any, Instance, Float, Dict, CaselessStrEnum, List, Set, Integer, Unicode
50 Any, Instance, Float, Dict, CaselessStrEnum, List, Set, Integer, Unicode
51 )
51 )
52
52
53 from entry_point import base_launch_kernel
53 from entry_point import base_launch_kernel
54 from kernelapp import KernelApp, kernel_flags, kernel_aliases
54 from kernelapp import KernelApp, kernel_flags, kernel_aliases
55 from serialize import serialize_object, unpack_apply_message
55 from serialize import serialize_object, unpack_apply_message
56 from session import Session, Message
56 from session import Session, Message
57 from zmqshell import ZMQInteractiveShell
57 from zmqshell import ZMQInteractiveShell
58
58
59
59
60 #-----------------------------------------------------------------------------
60 #-----------------------------------------------------------------------------
61 # Main kernel class
61 # Main kernel class
62 #-----------------------------------------------------------------------------
62 #-----------------------------------------------------------------------------
63
63
64 class Kernel(Configurable):
64 class Kernel(Configurable):
65
65
66 #---------------------------------------------------------------------------
66 #---------------------------------------------------------------------------
67 # Kernel interface
67 # Kernel interface
68 #---------------------------------------------------------------------------
68 #---------------------------------------------------------------------------
69
69
70 # attribute to override with a GUI
70 # attribute to override with a GUI
71 eventloop = Any(None)
71 eventloop = Any(None)
72 def _eventloop_changed(self, name, old, new):
72 def _eventloop_changed(self, name, old, new):
73 """schedule call to eventloop from IOLoop"""
73 """schedule call to eventloop from IOLoop"""
74 loop = ioloop.IOLoop.instance()
74 loop = ioloop.IOLoop.instance()
75 loop.add_timeout(time.time()+0.1, self.enter_eventloop)
75 loop.add_timeout(time.time()+0.1, self.enter_eventloop)
76
76
77 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
77 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
78 session = Instance(Session)
78 session = Instance(Session)
79 profile_dir = Instance('IPython.core.profiledir.ProfileDir')
79 profile_dir = Instance('IPython.core.profiledir.ProfileDir')
80 shell_streams = List()
80 shell_streams = List()
81 control_stream = Instance(ZMQStream)
81 control_stream = Instance(ZMQStream)
82 iopub_socket = Instance(zmq.Socket)
82 iopub_socket = Instance(zmq.Socket)
83 stdin_socket = Instance(zmq.Socket)
83 stdin_socket = Instance(zmq.Socket)
84 log = Instance(logging.Logger)
84 log = Instance(logging.Logger)
85
85
86 user_module = Any()
86 user_module = Any()
87 def _user_module_changed(self, name, old, new):
87 def _user_module_changed(self, name, old, new):
88 if self.shell is not None:
88 if self.shell is not None:
89 self.shell.user_module = new
89 self.shell.user_module = new
90
90
91 user_ns = Dict(default_value=None)
91 user_ns = Dict(default_value=None)
92 def _user_ns_changed(self, name, old, new):
92 def _user_ns_changed(self, name, old, new):
93 if self.shell is not None:
93 if self.shell is not None:
94 self.shell.user_ns = new
94 self.shell.user_ns = new
95 self.shell.init_user_ns()
95 self.shell.init_user_ns()
96
96
97 # identities:
97 # identities:
98 int_id = Integer(-1)
98 int_id = Integer(-1)
99 ident = Unicode()
99 ident = Unicode()
100
100
101 def _ident_default(self):
101 def _ident_default(self):
102 return unicode(uuid.uuid4())
102 return unicode(uuid.uuid4())
103
103
104
104
105 # Private interface
105 # Private interface
106
106
107 # Time to sleep after flushing the stdout/err buffers in each execute
107 # Time to sleep after flushing the stdout/err buffers in each execute
108 # cycle. While this introduces a hard limit on the minimal latency of the
108 # cycle. While this introduces a hard limit on the minimal latency of the
109 # execute cycle, it helps prevent output synchronization problems for
109 # execute cycle, it helps prevent output synchronization problems for
110 # clients.
110 # clients.
111 # Units are in seconds. The minimum zmq latency on local host is probably
111 # Units are in seconds. The minimum zmq latency on local host is probably
112 # ~150 microseconds, set this to 500us for now. We may need to increase it
112 # ~150 microseconds, set this to 500us for now. We may need to increase it
113 # a little if it's not enough after more interactive testing.
113 # a little if it's not enough after more interactive testing.
114 _execute_sleep = Float(0.0005, config=True)
114 _execute_sleep = Float(0.0005, config=True)
115
115
116 # Frequency of the kernel's event loop.
116 # Frequency of the kernel's event loop.
117 # Units are in seconds, kernel subclasses for GUI toolkits may need to
117 # Units are in seconds, kernel subclasses for GUI toolkits may need to
118 # adapt to milliseconds.
118 # adapt to milliseconds.
119 _poll_interval = Float(0.05, config=True)
119 _poll_interval = Float(0.05, config=True)
120
120
121 # If the shutdown was requested over the network, we leave here the
121 # If the shutdown was requested over the network, we leave here the
122 # necessary reply message so it can be sent by our registered atexit
122 # necessary reply message so it can be sent by our registered atexit
123 # handler. This ensures that the reply is only sent to clients truly at
123 # handler. This ensures that the reply is only sent to clients truly at
124 # the end of our shutdown process (which happens after the underlying
124 # the end of our shutdown process (which happens after the underlying
125 # IPython shell's own shutdown).
125 # IPython shell's own shutdown).
126 _shutdown_message = None
126 _shutdown_message = None
127
127
128 # This is a dict of port number that the kernel is listening on. It is set
128 # This is a dict of port number that the kernel is listening on. It is set
129 # by record_ports and used by connect_request.
129 # by record_ports and used by connect_request.
130 _recorded_ports = Dict()
130 _recorded_ports = Dict()
131
131
132 # set of aborted msg_ids
132 # set of aborted msg_ids
133 aborted = Set()
133 aborted = Set()
134
134
135
135
136 def __init__(self, **kwargs):
136 def __init__(self, **kwargs):
137 super(Kernel, self).__init__(**kwargs)
137 super(Kernel, self).__init__(**kwargs)
138
138
139 # Initialize the InteractiveShell subclass
139 # Initialize the InteractiveShell subclass
140 self.shell = ZMQInteractiveShell.instance(config=self.config,
140 self.shell = ZMQInteractiveShell.instance(config=self.config,
141 profile_dir = self.profile_dir,
141 profile_dir = self.profile_dir,
142 user_module = self.user_module,
142 user_module = self.user_module,
143 user_ns = self.user_ns,
143 user_ns = self.user_ns,
144 )
144 )
145 self.shell.displayhook.session = self.session
145 self.shell.displayhook.session = self.session
146 self.shell.displayhook.pub_socket = self.iopub_socket
146 self.shell.displayhook.pub_socket = self.iopub_socket
147 self.shell.displayhook.topic = self._topic('pyout')
147 self.shell.displayhook.topic = self._topic('pyout')
148 self.shell.display_pub.session = self.session
148 self.shell.display_pub.session = self.session
149 self.shell.display_pub.pub_socket = self.iopub_socket
149 self.shell.display_pub.pub_socket = self.iopub_socket
150 self.shell.data_pub.session = self.session
150 self.shell.data_pub.session = self.session
151 self.shell.data_pub.pub_socket = self.iopub_socket
151 self.shell.data_pub.pub_socket = self.iopub_socket
152
152
153 # TMP - hack while developing
153 # TMP - hack while developing
154 self.shell._reply_content = None
154 self.shell._reply_content = None
155
155
156 # Build dict of handlers for message types
156 # Build dict of handlers for message types
157 msg_types = [ 'execute_request', 'complete_request',
157 msg_types = [ 'execute_request', 'complete_request',
158 'object_info_request', 'history_request',
158 'object_info_request', 'history_request',
159 'connect_request', 'shutdown_request',
159 'connect_request', 'shutdown_request',
160 'apply_request',
160 'apply_request',
161 ]
161 ]
162 self.shell_handlers = {}
162 self.shell_handlers = {}
163 for msg_type in msg_types:
163 for msg_type in msg_types:
164 self.shell_handlers[msg_type] = getattr(self, msg_type)
164 self.shell_handlers[msg_type] = getattr(self, msg_type)
165
165
166 control_msg_types = msg_types + [ 'clear_request', 'abort_request' ]
166 control_msg_types = msg_types + [ 'clear_request', 'abort_request' ]
167 self.control_handlers = {}
167 self.control_handlers = {}
168 for msg_type in control_msg_types:
168 for msg_type in control_msg_types:
169 self.control_handlers[msg_type] = getattr(self, msg_type)
169 self.control_handlers[msg_type] = getattr(self, msg_type)
170
170
171 def dispatch_control(self, msg):
171 def dispatch_control(self, msg):
172 """dispatch control requests"""
172 """dispatch control requests"""
173 idents,msg = self.session.feed_identities(msg, copy=False)
173 idents,msg = self.session.feed_identities(msg, copy=False)
174 try:
174 try:
175 msg = self.session.unserialize(msg, content=True, copy=False)
175 msg = self.session.unserialize(msg, content=True, copy=False)
176 except:
176 except:
177 self.log.error("Invalid Control Message", exc_info=True)
177 self.log.error("Invalid Control Message", exc_info=True)
178 return
178 return
179
179
180 self.log.debug("Control received: %s", msg)
180 self.log.debug("Control received: %s", msg)
181
181
182 header = msg['header']
182 header = msg['header']
183 msg_id = header['msg_id']
183 msg_id = header['msg_id']
184 msg_type = header['msg_type']
184 msg_type = header['msg_type']
185
185
186 handler = self.control_handlers.get(msg_type, None)
186 handler = self.control_handlers.get(msg_type, None)
187 if handler is None:
187 if handler is None:
188 self.log.error("UNKNOWN CONTROL MESSAGE TYPE: %r", msg_type)
188 self.log.error("UNKNOWN CONTROL MESSAGE TYPE: %r", msg_type)
189 else:
189 else:
190 try:
190 try:
191 handler(self.control_stream, idents, msg)
191 handler(self.control_stream, idents, msg)
192 except Exception:
192 except Exception:
193 self.log.error("Exception in control handler:", exc_info=True)
193 self.log.error("Exception in control handler:", exc_info=True)
194
194
195 def dispatch_shell(self, stream, msg):
195 def dispatch_shell(self, stream, msg):
196 """dispatch shell requests"""
196 """dispatch shell requests"""
197 # flush control requests first
197 # flush control requests first
198 if self.control_stream:
198 if self.control_stream:
199 self.control_stream.flush()
199 self.control_stream.flush()
200
200
201 idents,msg = self.session.feed_identities(msg, copy=False)
201 idents,msg = self.session.feed_identities(msg, copy=False)
202 try:
202 try:
203 msg = self.session.unserialize(msg, content=True, copy=False)
203 msg = self.session.unserialize(msg, content=True, copy=False)
204 except:
204 except:
205 self.log.error("Invalid Message", exc_info=True)
205 self.log.error("Invalid Message", exc_info=True)
206 return
206 return
207
207
208 header = msg['header']
208 header = msg['header']
209 msg_id = header['msg_id']
209 msg_id = header['msg_id']
210 msg_type = msg['header']['msg_type']
210 msg_type = msg['header']['msg_type']
211
211
212 # Print some info about this message and leave a '--->' marker, so it's
212 # Print some info about this message and leave a '--->' marker, so it's
213 # easier to trace visually the message chain when debugging. Each
213 # easier to trace visually the message chain when debugging. Each
214 # handler prints its message at the end.
214 # handler prints its message at the end.
215 self.log.debug('\n*** MESSAGE TYPE:%s***', msg_type)
215 self.log.debug('\n*** MESSAGE TYPE:%s***', msg_type)
216 self.log.debug(' Content: %s\n --->\n ', msg['content'])
216 self.log.debug(' Content: %s\n --->\n ', msg['content'])
217
217
218 if msg_id in self.aborted:
218 if msg_id in self.aborted:
219 self.aborted.remove(msg_id)
219 self.aborted.remove(msg_id)
220 # is it safe to assume a msg_id will not be resubmitted?
220 # is it safe to assume a msg_id will not be resubmitted?
221 reply_type = msg_type.split('_')[0] + '_reply'
221 reply_type = msg_type.split('_')[0] + '_reply'
222 status = {'status' : 'aborted'}
222 status = {'status' : 'aborted'}
223 md = {'engine' : self.ident}
223 md = {'engine' : self.ident}
224 md.update(status)
224 md.update(status)
225 reply_msg = self.session.send(stream, reply_type, metadata=md,
225 reply_msg = self.session.send(stream, reply_type, metadata=md,
226 content=status, parent=msg, ident=idents)
226 content=status, parent=msg, ident=idents)
227 return
227 return
228
228
229 handler = self.shell_handlers.get(msg_type, None)
229 handler = self.shell_handlers.get(msg_type, None)
230 if handler is None:
230 if handler is None:
231 self.log.error("UNKNOWN MESSAGE TYPE: %r", msg_type)
231 self.log.error("UNKNOWN MESSAGE TYPE: %r", msg_type)
232 else:
232 else:
233 # ensure default_int_handler during handler call
233 # ensure default_int_handler during handler call
234 sig = signal(SIGINT, default_int_handler)
234 sig = signal(SIGINT, default_int_handler)
235 try:
235 try:
236 handler(stream, idents, msg)
236 handler(stream, idents, msg)
237 except Exception:
237 except Exception:
238 self.log.error("Exception in message handler:", exc_info=True)
238 self.log.error("Exception in message handler:", exc_info=True)
239 finally:
239 finally:
240 signal(SIGINT, sig)
240 signal(SIGINT, sig)
241
241
242 def enter_eventloop(self):
242 def enter_eventloop(self):
243 """enter eventloop"""
243 """enter eventloop"""
244 self.log.info("entering eventloop")
244 self.log.info("entering eventloop")
245 # restore default_int_handler
245 # restore default_int_handler
246 signal(SIGINT, default_int_handler)
246 signal(SIGINT, default_int_handler)
247 while self.eventloop is not None:
247 while self.eventloop is not None:
248 try:
248 try:
249 self.eventloop(self)
249 self.eventloop(self)
250 except KeyboardInterrupt:
250 except KeyboardInterrupt:
251 # Ctrl-C shouldn't crash the kernel
251 # Ctrl-C shouldn't crash the kernel
252 self.log.error("KeyboardInterrupt caught in kernel")
252 self.log.error("KeyboardInterrupt caught in kernel")
253 continue
253 continue
254 else:
254 else:
255 # eventloop exited cleanly, this means we should stop (right?)
255 # eventloop exited cleanly, this means we should stop (right?)
256 self.eventloop = None
256 self.eventloop = None
257 break
257 break
258 self.log.info("exiting eventloop")
258 self.log.info("exiting eventloop")
259
259
260 def start(self):
260 def start(self):
261 """register dispatchers for streams"""
261 """register dispatchers for streams"""
262 self.shell.exit_now = False
262 self.shell.exit_now = False
263 if self.control_stream:
263 if self.control_stream:
264 self.control_stream.on_recv(self.dispatch_control, copy=False)
264 self.control_stream.on_recv(self.dispatch_control, copy=False)
265
265
266 def make_dispatcher(stream):
266 def make_dispatcher(stream):
267 def dispatcher(msg):
267 def dispatcher(msg):
268 return self.dispatch_shell(stream, msg)
268 return self.dispatch_shell(stream, msg)
269 return dispatcher
269 return dispatcher
270
270
271 for s in self.shell_streams:
271 for s in self.shell_streams:
272 s.on_recv(make_dispatcher(s), copy=False)
272 s.on_recv(make_dispatcher(s), copy=False)
273
273
274 def do_one_iteration(self):
274 def do_one_iteration(self):
275 """step eventloop just once"""
275 """step eventloop just once"""
276 if self.control_stream:
276 if self.control_stream:
277 self.control_stream.flush()
277 self.control_stream.flush()
278 for stream in self.shell_streams:
278 for stream in self.shell_streams:
279 # handle at most one request per iteration
279 # handle at most one request per iteration
280 stream.flush(zmq.POLLIN, 1)
280 stream.flush(zmq.POLLIN, 1)
281 stream.flush(zmq.POLLOUT)
281 stream.flush(zmq.POLLOUT)
282
282
283
283
284 def record_ports(self, ports):
284 def record_ports(self, ports):
285 """Record the ports that this kernel is using.
285 """Record the ports that this kernel is using.
286
286
287 The creator of the Kernel instance must call this methods if they
287 The creator of the Kernel instance must call this methods if they
288 want the :meth:`connect_request` method to return the port numbers.
288 want the :meth:`connect_request` method to return the port numbers.
289 """
289 """
290 self._recorded_ports = ports
290 self._recorded_ports = ports
291
291
292 #---------------------------------------------------------------------------
292 #---------------------------------------------------------------------------
293 # Kernel request handlers
293 # Kernel request handlers
294 #---------------------------------------------------------------------------
294 #---------------------------------------------------------------------------
295
295
296 def _make_metadata(self, other=None):
296 def _make_metadata(self, other=None):
297 """init metadata dict, for execute/apply_reply"""
297 """init metadata dict, for execute/apply_reply"""
298 new_md = {
298 new_md = {
299 'dependencies_met' : True,
299 'dependencies_met' : True,
300 'engine' : self.ident,
300 'engine' : self.ident,
301 'started': datetime.now(),
301 'started': datetime.now(),
302 }
302 }
303 if other:
303 if other:
304 new_md.update(other)
304 new_md.update(other)
305 return new_md
305 return new_md
306
306
307 def _publish_pyin(self, code, parent, execution_count):
307 def _publish_pyin(self, code, parent, execution_count):
308 """Publish the code request on the pyin stream."""
308 """Publish the code request on the pyin stream."""
309
309
310 self.session.send(self.iopub_socket, u'pyin',
310 self.session.send(self.iopub_socket, u'pyin',
311 {u'code':code, u'execution_count': execution_count},
311 {u'code':code, u'execution_count': execution_count},
312 parent=parent, ident=self._topic('pyin')
312 parent=parent, ident=self._topic('pyin')
313 )
313 )
314
314
315 def _publish_status(self, status, parent=None):
315 def _publish_status(self, status, parent=None):
316 """send status (busy/idle) on IOPub"""
316 """send status (busy/idle) on IOPub"""
317 self.session.send(self.iopub_socket,
317 self.session.send(self.iopub_socket,
318 u'status',
318 u'status',
319 {u'execution_state': status},
319 {u'execution_state': status},
320 parent=parent,
320 parent=parent,
321 ident=self._topic('status'),
321 ident=self._topic('status'),
322 )
322 )
323
323
324
324
325 def execute_request(self, stream, ident, parent):
325 def execute_request(self, stream, ident, parent):
326 """handle an execute_request"""
326 """handle an execute_request"""
327
327
328 self._publish_status(u'busy', parent)
328 self._publish_status(u'busy', parent)
329
329
330 try:
330 try:
331 content = parent[u'content']
331 content = parent[u'content']
332 code = content[u'code']
332 code = content[u'code']
333 silent = content[u'silent']
333 silent = content[u'silent']
334 store_history = content.get(u'store_history', not silent)
334 except:
335 except:
335 self.log.error("Got bad msg: ")
336 self.log.error("Got bad msg: ")
336 self.log.error("%s", parent)
337 self.log.error("%s", parent)
337 return
338 return
338
339
339 md = self._make_metadata(parent['metadata'])
340 md = self._make_metadata(parent['metadata'])
340
341
341 shell = self.shell # we'll need this a lot here
342 shell = self.shell # we'll need this a lot here
342
343
343 # Replace raw_input. Note that is not sufficient to replace
344 # Replace raw_input. Note that is not sufficient to replace
344 # raw_input in the user namespace.
345 # raw_input in the user namespace.
345 if content.get('allow_stdin', False):
346 if content.get('allow_stdin', False):
346 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
347 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
347 else:
348 else:
348 raw_input = lambda prompt='' : self._no_raw_input()
349 raw_input = lambda prompt='' : self._no_raw_input()
349
350
350 if py3compat.PY3:
351 if py3compat.PY3:
351 __builtin__.input = raw_input
352 __builtin__.input = raw_input
352 else:
353 else:
353 __builtin__.raw_input = raw_input
354 __builtin__.raw_input = raw_input
354
355
355 # Set the parent message of the display hook and out streams.
356 # Set the parent message of the display hook and out streams.
356 shell.displayhook.set_parent(parent)
357 shell.displayhook.set_parent(parent)
357 shell.display_pub.set_parent(parent)
358 shell.display_pub.set_parent(parent)
358 shell.data_pub.set_parent(parent)
359 shell.data_pub.set_parent(parent)
359 sys.stdout.set_parent(parent)
360 sys.stdout.set_parent(parent)
360 sys.stderr.set_parent(parent)
361 sys.stderr.set_parent(parent)
361
362
362 # Re-broadcast our input for the benefit of listening clients, and
363 # Re-broadcast our input for the benefit of listening clients, and
363 # start computing output
364 # start computing output
364 if not silent:
365 if not silent:
365 self._publish_pyin(code, parent, shell.execution_count)
366 self._publish_pyin(code, parent, shell.execution_count)
366
367
367 reply_content = {}
368 reply_content = {}
368 try:
369 try:
369 # FIXME: the shell calls the exception handler itself.
370 # FIXME: the shell calls the exception handler itself.
370 shell.run_cell(code, store_history=not silent, silent=silent)
371 shell.run_cell(code, store_history=store_history, silent=silent)
371 except:
372 except:
372 status = u'error'
373 status = u'error'
373 # FIXME: this code right now isn't being used yet by default,
374 # FIXME: this code right now isn't being used yet by default,
374 # because the run_cell() call above directly fires off exception
375 # because the run_cell() call above directly fires off exception
375 # reporting. This code, therefore, is only active in the scenario
376 # reporting. This code, therefore, is only active in the scenario
376 # where runlines itself has an unhandled exception. We need to
377 # where runlines itself has an unhandled exception. We need to
377 # uniformize this, for all exception construction to come from a
378 # uniformize this, for all exception construction to come from a
378 # single location in the codbase.
379 # single location in the codbase.
379 etype, evalue, tb = sys.exc_info()
380 etype, evalue, tb = sys.exc_info()
380 tb_list = traceback.format_exception(etype, evalue, tb)
381 tb_list = traceback.format_exception(etype, evalue, tb)
381 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
382 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
382 else:
383 else:
383 status = u'ok'
384 status = u'ok'
384
385
385 reply_content[u'status'] = status
386 reply_content[u'status'] = status
386
387
387 # Return the execution counter so clients can display prompts
388 # Return the execution counter so clients can display prompts
388 reply_content['execution_count'] = shell.execution_count - 1
389 reply_content['execution_count'] = shell.execution_count - 1
389
390
390 # FIXME - fish exception info out of shell, possibly left there by
391 # FIXME - fish exception info out of shell, possibly left there by
391 # runlines. We'll need to clean up this logic later.
392 # runlines. We'll need to clean up this logic later.
392 if shell._reply_content is not None:
393 if shell._reply_content is not None:
393 reply_content.update(shell._reply_content)
394 reply_content.update(shell._reply_content)
394 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='execute')
395 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='execute')
395 reply_content['engine_info'] = e_info
396 reply_content['engine_info'] = e_info
396 # reset after use
397 # reset after use
397 shell._reply_content = None
398 shell._reply_content = None
398
399
399 # At this point, we can tell whether the main code execution succeeded
400 # At this point, we can tell whether the main code execution succeeded
400 # or not. If it did, we proceed to evaluate user_variables/expressions
401 # or not. If it did, we proceed to evaluate user_variables/expressions
401 if reply_content['status'] == 'ok':
402 if reply_content['status'] == 'ok':
402 reply_content[u'user_variables'] = \
403 reply_content[u'user_variables'] = \
403 shell.user_variables(content.get(u'user_variables', []))
404 shell.user_variables(content.get(u'user_variables', []))
404 reply_content[u'user_expressions'] = \
405 reply_content[u'user_expressions'] = \
405 shell.user_expressions(content.get(u'user_expressions', {}))
406 shell.user_expressions(content.get(u'user_expressions', {}))
406 else:
407 else:
407 # If there was an error, don't even try to compute variables or
408 # If there was an error, don't even try to compute variables or
408 # expressions
409 # expressions
409 reply_content[u'user_variables'] = {}
410 reply_content[u'user_variables'] = {}
410 reply_content[u'user_expressions'] = {}
411 reply_content[u'user_expressions'] = {}
411
412
412 # Payloads should be retrieved regardless of outcome, so we can both
413 # Payloads should be retrieved regardless of outcome, so we can both
413 # recover partial output (that could have been generated early in a
414 # recover partial output (that could have been generated early in a
414 # block, before an error) and clear the payload system always.
415 # block, before an error) and clear the payload system always.
415 reply_content[u'payload'] = shell.payload_manager.read_payload()
416 reply_content[u'payload'] = shell.payload_manager.read_payload()
416 # Be agressive about clearing the payload because we don't want
417 # Be agressive about clearing the payload because we don't want
417 # it to sit in memory until the next execute_request comes in.
418 # it to sit in memory until the next execute_request comes in.
418 shell.payload_manager.clear_payload()
419 shell.payload_manager.clear_payload()
419
420
420 # Flush output before sending the reply.
421 # Flush output before sending the reply.
421 sys.stdout.flush()
422 sys.stdout.flush()
422 sys.stderr.flush()
423 sys.stderr.flush()
423 # FIXME: on rare occasions, the flush doesn't seem to make it to the
424 # FIXME: on rare occasions, the flush doesn't seem to make it to the
424 # clients... This seems to mitigate the problem, but we definitely need
425 # clients... This seems to mitigate the problem, but we definitely need
425 # to better understand what's going on.
426 # to better understand what's going on.
426 if self._execute_sleep:
427 if self._execute_sleep:
427 time.sleep(self._execute_sleep)
428 time.sleep(self._execute_sleep)
428
429
429 # Send the reply.
430 # Send the reply.
430 reply_content = json_clean(reply_content)
431 reply_content = json_clean(reply_content)
431
432
432 md['status'] = reply_content['status']
433 md['status'] = reply_content['status']
433 if reply_content['status'] == 'error' and \
434 if reply_content['status'] == 'error' and \
434 reply_content['ename'] == 'UnmetDependency':
435 reply_content['ename'] == 'UnmetDependency':
435 md['dependencies_met'] = False
436 md['dependencies_met'] = False
436
437
437 reply_msg = self.session.send(stream, u'execute_reply',
438 reply_msg = self.session.send(stream, u'execute_reply',
438 reply_content, parent, metadata=md,
439 reply_content, parent, metadata=md,
439 ident=ident)
440 ident=ident)
440
441
441 self.log.debug("%s", reply_msg)
442 self.log.debug("%s", reply_msg)
442
443
443 if not silent and reply_msg['content']['status'] == u'error':
444 if not silent and reply_msg['content']['status'] == u'error':
444 self._abort_queues()
445 self._abort_queues()
445
446
446 self._publish_status(u'idle', parent)
447 self._publish_status(u'idle', parent)
447
448
448 def complete_request(self, stream, ident, parent):
449 def complete_request(self, stream, ident, parent):
449 txt, matches = self._complete(parent)
450 txt, matches = self._complete(parent)
450 matches = {'matches' : matches,
451 matches = {'matches' : matches,
451 'matched_text' : txt,
452 'matched_text' : txt,
452 'status' : 'ok'}
453 'status' : 'ok'}
453 matches = json_clean(matches)
454 matches = json_clean(matches)
454 completion_msg = self.session.send(stream, 'complete_reply',
455 completion_msg = self.session.send(stream, 'complete_reply',
455 matches, parent, ident)
456 matches, parent, ident)
456 self.log.debug("%s", completion_msg)
457 self.log.debug("%s", completion_msg)
457
458
458 def object_info_request(self, stream, ident, parent):
459 def object_info_request(self, stream, ident, parent):
459 content = parent['content']
460 content = parent['content']
460 object_info = self.shell.object_inspect(content['oname'],
461 object_info = self.shell.object_inspect(content['oname'],
461 detail_level = content.get('detail_level', 0)
462 detail_level = content.get('detail_level', 0)
462 )
463 )
463 # Before we send this object over, we scrub it for JSON usage
464 # Before we send this object over, we scrub it for JSON usage
464 oinfo = json_clean(object_info)
465 oinfo = json_clean(object_info)
465 msg = self.session.send(stream, 'object_info_reply',
466 msg = self.session.send(stream, 'object_info_reply',
466 oinfo, parent, ident)
467 oinfo, parent, ident)
467 self.log.debug("%s", msg)
468 self.log.debug("%s", msg)
468
469
469 def history_request(self, stream, ident, parent):
470 def history_request(self, stream, ident, parent):
470 # We need to pull these out, as passing **kwargs doesn't work with
471 # We need to pull these out, as passing **kwargs doesn't work with
471 # unicode keys before Python 2.6.5.
472 # unicode keys before Python 2.6.5.
472 hist_access_type = parent['content']['hist_access_type']
473 hist_access_type = parent['content']['hist_access_type']
473 raw = parent['content']['raw']
474 raw = parent['content']['raw']
474 output = parent['content']['output']
475 output = parent['content']['output']
475 if hist_access_type == 'tail':
476 if hist_access_type == 'tail':
476 n = parent['content']['n']
477 n = parent['content']['n']
477 hist = self.shell.history_manager.get_tail(n, raw=raw, output=output,
478 hist = self.shell.history_manager.get_tail(n, raw=raw, output=output,
478 include_latest=True)
479 include_latest=True)
479
480
480 elif hist_access_type == 'range':
481 elif hist_access_type == 'range':
481 session = parent['content']['session']
482 session = parent['content']['session']
482 start = parent['content']['start']
483 start = parent['content']['start']
483 stop = parent['content']['stop']
484 stop = parent['content']['stop']
484 hist = self.shell.history_manager.get_range(session, start, stop,
485 hist = self.shell.history_manager.get_range(session, start, stop,
485 raw=raw, output=output)
486 raw=raw, output=output)
486
487
487 elif hist_access_type == 'search':
488 elif hist_access_type == 'search':
488 pattern = parent['content']['pattern']
489 pattern = parent['content']['pattern']
489 hist = self.shell.history_manager.search(pattern, raw=raw,
490 hist = self.shell.history_manager.search(pattern, raw=raw,
490 output=output)
491 output=output)
491
492
492 else:
493 else:
493 hist = []
494 hist = []
494 hist = list(hist)
495 hist = list(hist)
495 content = {'history' : hist}
496 content = {'history' : hist}
496 content = json_clean(content)
497 content = json_clean(content)
497 msg = self.session.send(stream, 'history_reply',
498 msg = self.session.send(stream, 'history_reply',
498 content, parent, ident)
499 content, parent, ident)
499 self.log.debug("Sending history reply with %i entries", len(hist))
500 self.log.debug("Sending history reply with %i entries", len(hist))
500
501
501 def connect_request(self, stream, ident, parent):
502 def connect_request(self, stream, ident, parent):
502 if self._recorded_ports is not None:
503 if self._recorded_ports is not None:
503 content = self._recorded_ports.copy()
504 content = self._recorded_ports.copy()
504 else:
505 else:
505 content = {}
506 content = {}
506 msg = self.session.send(stream, 'connect_reply',
507 msg = self.session.send(stream, 'connect_reply',
507 content, parent, ident)
508 content, parent, ident)
508 self.log.debug("%s", msg)
509 self.log.debug("%s", msg)
509
510
510 def shutdown_request(self, stream, ident, parent):
511 def shutdown_request(self, stream, ident, parent):
511 self.shell.exit_now = True
512 self.shell.exit_now = True
512 content = dict(status='ok')
513 content = dict(status='ok')
513 content.update(parent['content'])
514 content.update(parent['content'])
514 self.session.send(stream, u'shutdown_reply', content, parent, ident=ident)
515 self.session.send(stream, u'shutdown_reply', content, parent, ident=ident)
515 # same content, but different msg_id for broadcasting on IOPub
516 # same content, but different msg_id for broadcasting on IOPub
516 self._shutdown_message = self.session.msg(u'shutdown_reply',
517 self._shutdown_message = self.session.msg(u'shutdown_reply',
517 content, parent
518 content, parent
518 )
519 )
519
520
520 self._at_shutdown()
521 self._at_shutdown()
521 # call sys.exit after a short delay
522 # call sys.exit after a short delay
522 loop = ioloop.IOLoop.instance()
523 loop = ioloop.IOLoop.instance()
523 loop.add_timeout(time.time()+0.1, loop.stop)
524 loop.add_timeout(time.time()+0.1, loop.stop)
524
525
525 #---------------------------------------------------------------------------
526 #---------------------------------------------------------------------------
526 # Engine methods
527 # Engine methods
527 #---------------------------------------------------------------------------
528 #---------------------------------------------------------------------------
528
529
529 def apply_request(self, stream, ident, parent):
530 def apply_request(self, stream, ident, parent):
530 try:
531 try:
531 content = parent[u'content']
532 content = parent[u'content']
532 bufs = parent[u'buffers']
533 bufs = parent[u'buffers']
533 msg_id = parent['header']['msg_id']
534 msg_id = parent['header']['msg_id']
534 except:
535 except:
535 self.log.error("Got bad msg: %s", parent, exc_info=True)
536 self.log.error("Got bad msg: %s", parent, exc_info=True)
536 return
537 return
537
538
538 self._publish_status(u'busy', parent)
539 self._publish_status(u'busy', parent)
539
540
540 # Set the parent message of the display hook and out streams.
541 # Set the parent message of the display hook and out streams.
541 shell = self.shell
542 shell = self.shell
542 shell.displayhook.set_parent(parent)
543 shell.displayhook.set_parent(parent)
543 shell.display_pub.set_parent(parent)
544 shell.display_pub.set_parent(parent)
544 shell.data_pub.set_parent(parent)
545 shell.data_pub.set_parent(parent)
545 sys.stdout.set_parent(parent)
546 sys.stdout.set_parent(parent)
546 sys.stderr.set_parent(parent)
547 sys.stderr.set_parent(parent)
547
548
548 # pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
549 # pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
549 # self.iopub_socket.send(pyin_msg)
550 # self.iopub_socket.send(pyin_msg)
550 # self.session.send(self.iopub_socket, u'pyin', {u'code':code},parent=parent)
551 # self.session.send(self.iopub_socket, u'pyin', {u'code':code},parent=parent)
551 md = self._make_metadata(parent['metadata'])
552 md = self._make_metadata(parent['metadata'])
552 try:
553 try:
553 working = shell.user_ns
554 working = shell.user_ns
554
555
555 prefix = "_"+str(msg_id).replace("-","")+"_"
556 prefix = "_"+str(msg_id).replace("-","")+"_"
556
557
557 f,args,kwargs = unpack_apply_message(bufs, working, copy=False)
558 f,args,kwargs = unpack_apply_message(bufs, working, copy=False)
558
559
559 fname = getattr(f, '__name__', 'f')
560 fname = getattr(f, '__name__', 'f')
560
561
561 fname = prefix+"f"
562 fname = prefix+"f"
562 argname = prefix+"args"
563 argname = prefix+"args"
563 kwargname = prefix+"kwargs"
564 kwargname = prefix+"kwargs"
564 resultname = prefix+"result"
565 resultname = prefix+"result"
565
566
566 ns = { fname : f, argname : args, kwargname : kwargs , resultname : None }
567 ns = { fname : f, argname : args, kwargname : kwargs , resultname : None }
567 # print ns
568 # print ns
568 working.update(ns)
569 working.update(ns)
569 code = "%s = %s(*%s,**%s)" % (resultname, fname, argname, kwargname)
570 code = "%s = %s(*%s,**%s)" % (resultname, fname, argname, kwargname)
570 try:
571 try:
571 exec code in shell.user_global_ns, shell.user_ns
572 exec code in shell.user_global_ns, shell.user_ns
572 result = working.get(resultname)
573 result = working.get(resultname)
573 finally:
574 finally:
574 for key in ns.iterkeys():
575 for key in ns.iterkeys():
575 working.pop(key)
576 working.pop(key)
576
577
577 result_buf = serialize_object(result,
578 result_buf = serialize_object(result,
578 buffer_threshold=self.session.buffer_threshold,
579 buffer_threshold=self.session.buffer_threshold,
579 item_threshold=self.session.item_threshold,
580 item_threshold=self.session.item_threshold,
580 )
581 )
581
582
582 except:
583 except:
583 # invoke IPython traceback formatting
584 # invoke IPython traceback formatting
584 shell.showtraceback()
585 shell.showtraceback()
585 # FIXME - fish exception info out of shell, possibly left there by
586 # FIXME - fish exception info out of shell, possibly left there by
586 # run_code. We'll need to clean up this logic later.
587 # run_code. We'll need to clean up this logic later.
587 reply_content = {}
588 reply_content = {}
588 if shell._reply_content is not None:
589 if shell._reply_content is not None:
589 reply_content.update(shell._reply_content)
590 reply_content.update(shell._reply_content)
590 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='apply')
591 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method='apply')
591 reply_content['engine_info'] = e_info
592 reply_content['engine_info'] = e_info
592 # reset after use
593 # reset after use
593 shell._reply_content = None
594 shell._reply_content = None
594
595
595 self.session.send(self.iopub_socket, u'pyerr', reply_content, parent=parent,
596 self.session.send(self.iopub_socket, u'pyerr', reply_content, parent=parent,
596 ident=self._topic('pyerr'))
597 ident=self._topic('pyerr'))
597 result_buf = []
598 result_buf = []
598
599
599 if reply_content['ename'] == 'UnmetDependency':
600 if reply_content['ename'] == 'UnmetDependency':
600 md['dependencies_met'] = False
601 md['dependencies_met'] = False
601 else:
602 else:
602 reply_content = {'status' : 'ok'}
603 reply_content = {'status' : 'ok'}
603
604
604 # put 'ok'/'error' status in header, for scheduler introspection:
605 # put 'ok'/'error' status in header, for scheduler introspection:
605 md['status'] = reply_content['status']
606 md['status'] = reply_content['status']
606
607
607 # flush i/o
608 # flush i/o
608 sys.stdout.flush()
609 sys.stdout.flush()
609 sys.stderr.flush()
610 sys.stderr.flush()
610
611
611 reply_msg = self.session.send(stream, u'apply_reply', reply_content,
612 reply_msg = self.session.send(stream, u'apply_reply', reply_content,
612 parent=parent, ident=ident,buffers=result_buf, metadata=md)
613 parent=parent, ident=ident,buffers=result_buf, metadata=md)
613
614
614 self._publish_status(u'idle', parent)
615 self._publish_status(u'idle', parent)
615
616
616 #---------------------------------------------------------------------------
617 #---------------------------------------------------------------------------
617 # Control messages
618 # Control messages
618 #---------------------------------------------------------------------------
619 #---------------------------------------------------------------------------
619
620
620 def abort_request(self, stream, ident, parent):
621 def abort_request(self, stream, ident, parent):
621 """abort a specifig msg by id"""
622 """abort a specifig msg by id"""
622 msg_ids = parent['content'].get('msg_ids', None)
623 msg_ids = parent['content'].get('msg_ids', None)
623 if isinstance(msg_ids, basestring):
624 if isinstance(msg_ids, basestring):
624 msg_ids = [msg_ids]
625 msg_ids = [msg_ids]
625 if not msg_ids:
626 if not msg_ids:
626 self.abort_queues()
627 self.abort_queues()
627 for mid in msg_ids:
628 for mid in msg_ids:
628 self.aborted.add(str(mid))
629 self.aborted.add(str(mid))
629
630
630 content = dict(status='ok')
631 content = dict(status='ok')
631 reply_msg = self.session.send(stream, 'abort_reply', content=content,
632 reply_msg = self.session.send(stream, 'abort_reply', content=content,
632 parent=parent, ident=ident)
633 parent=parent, ident=ident)
633 self.log.debug("%s", reply_msg)
634 self.log.debug("%s", reply_msg)
634
635
635 def clear_request(self, stream, idents, parent):
636 def clear_request(self, stream, idents, parent):
636 """Clear our namespace."""
637 """Clear our namespace."""
637 self.shell.reset(False)
638 self.shell.reset(False)
638 msg = self.session.send(stream, 'clear_reply', ident=idents, parent=parent,
639 msg = self.session.send(stream, 'clear_reply', ident=idents, parent=parent,
639 content = dict(status='ok'))
640 content = dict(status='ok'))
640
641
641
642
642 #---------------------------------------------------------------------------
643 #---------------------------------------------------------------------------
643 # Protected interface
644 # Protected interface
644 #---------------------------------------------------------------------------
645 #---------------------------------------------------------------------------
645
646
646
647
647 def _wrap_exception(self, method=None):
648 def _wrap_exception(self, method=None):
648 # import here, because _wrap_exception is only used in parallel,
649 # import here, because _wrap_exception is only used in parallel,
649 # and parallel has higher min pyzmq version
650 # and parallel has higher min pyzmq version
650 from IPython.parallel.error import wrap_exception
651 from IPython.parallel.error import wrap_exception
651 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method=method)
652 e_info = dict(engine_uuid=self.ident, engine_id=self.int_id, method=method)
652 content = wrap_exception(e_info)
653 content = wrap_exception(e_info)
653 return content
654 return content
654
655
655 def _topic(self, topic):
656 def _topic(self, topic):
656 """prefixed topic for IOPub messages"""
657 """prefixed topic for IOPub messages"""
657 if self.int_id >= 0:
658 if self.int_id >= 0:
658 base = "engine.%i" % self.int_id
659 base = "engine.%i" % self.int_id
659 else:
660 else:
660 base = "kernel.%s" % self.ident
661 base = "kernel.%s" % self.ident
661
662
662 return py3compat.cast_bytes("%s.%s" % (base, topic))
663 return py3compat.cast_bytes("%s.%s" % (base, topic))
663
664
664 def _abort_queues(self):
665 def _abort_queues(self):
665 for stream in self.shell_streams:
666 for stream in self.shell_streams:
666 if stream:
667 if stream:
667 self._abort_queue(stream)
668 self._abort_queue(stream)
668
669
669 def _abort_queue(self, stream):
670 def _abort_queue(self, stream):
670 poller = zmq.Poller()
671 poller = zmq.Poller()
671 poller.register(stream.socket, zmq.POLLIN)
672 poller.register(stream.socket, zmq.POLLIN)
672 while True:
673 while True:
673 idents,msg = self.session.recv(stream, zmq.NOBLOCK, content=True)
674 idents,msg = self.session.recv(stream, zmq.NOBLOCK, content=True)
674 if msg is None:
675 if msg is None:
675 return
676 return
676
677
677 self.log.info("Aborting:")
678 self.log.info("Aborting:")
678 self.log.info("%s", msg)
679 self.log.info("%s", msg)
679 msg_type = msg['header']['msg_type']
680 msg_type = msg['header']['msg_type']
680 reply_type = msg_type.split('_')[0] + '_reply'
681 reply_type = msg_type.split('_')[0] + '_reply'
681
682
682 status = {'status' : 'aborted'}
683 status = {'status' : 'aborted'}
683 md = {'engine' : self.ident}
684 md = {'engine' : self.ident}
684 md.update(status)
685 md.update(status)
685 reply_msg = self.session.send(stream, reply_type, metadata=md,
686 reply_msg = self.session.send(stream, reply_type, metadata=md,
686 content=status, parent=msg, ident=idents)
687 content=status, parent=msg, ident=idents)
687 self.log.debug("%s", reply_msg)
688 self.log.debug("%s", reply_msg)
688 # We need to wait a bit for requests to come in. This can probably
689 # We need to wait a bit for requests to come in. This can probably
689 # be set shorter for true asynchronous clients.
690 # be set shorter for true asynchronous clients.
690 poller.poll(50)
691 poller.poll(50)
691
692
692
693
693 def _no_raw_input(self):
694 def _no_raw_input(self):
694 """Raise StdinNotImplentedError if active frontend doesn't support
695 """Raise StdinNotImplentedError if active frontend doesn't support
695 stdin."""
696 stdin."""
696 raise StdinNotImplementedError("raw_input was called, but this "
697 raise StdinNotImplementedError("raw_input was called, but this "
697 "frontend does not support stdin.")
698 "frontend does not support stdin.")
698
699
699 def _raw_input(self, prompt, ident, parent):
700 def _raw_input(self, prompt, ident, parent):
700 # Flush output before making the request.
701 # Flush output before making the request.
701 sys.stderr.flush()
702 sys.stderr.flush()
702 sys.stdout.flush()
703 sys.stdout.flush()
703
704
704 # Send the input request.
705 # Send the input request.
705 content = json_clean(dict(prompt=prompt))
706 content = json_clean(dict(prompt=prompt))
706 self.session.send(self.stdin_socket, u'input_request', content, parent,
707 self.session.send(self.stdin_socket, u'input_request', content, parent,
707 ident=ident)
708 ident=ident)
708
709
709 # Await a response.
710 # Await a response.
710 while True:
711 while True:
711 try:
712 try:
712 ident, reply = self.session.recv(self.stdin_socket, 0)
713 ident, reply = self.session.recv(self.stdin_socket, 0)
713 except Exception:
714 except Exception:
714 self.log.warn("Invalid Message:", exc_info=True)
715 self.log.warn("Invalid Message:", exc_info=True)
715 else:
716 else:
716 break
717 break
717 try:
718 try:
718 value = reply['content']['value']
719 value = reply['content']['value']
719 except:
720 except:
720 self.log.error("Got bad raw_input reply: ")
721 self.log.error("Got bad raw_input reply: ")
721 self.log.error("%s", parent)
722 self.log.error("%s", parent)
722 value = ''
723 value = ''
723 if value == '\x04':
724 if value == '\x04':
724 # EOF
725 # EOF
725 raise EOFError
726 raise EOFError
726 return value
727 return value
727
728
728 def _complete(self, msg):
729 def _complete(self, msg):
729 c = msg['content']
730 c = msg['content']
730 try:
731 try:
731 cpos = int(c['cursor_pos'])
732 cpos = int(c['cursor_pos'])
732 except:
733 except:
733 # If we don't get something that we can convert to an integer, at
734 # If we don't get something that we can convert to an integer, at
734 # least attempt the completion guessing the cursor is at the end of
735 # least attempt the completion guessing the cursor is at the end of
735 # the text, if there's any, and otherwise of the line
736 # the text, if there's any, and otherwise of the line
736 cpos = len(c['text'])
737 cpos = len(c['text'])
737 if cpos==0:
738 if cpos==0:
738 cpos = len(c['line'])
739 cpos = len(c['line'])
739 return self.shell.complete(c['text'], c['line'], cpos)
740 return self.shell.complete(c['text'], c['line'], cpos)
740
741
741 def _object_info(self, context):
742 def _object_info(self, context):
742 symbol, leftover = self._symbol_from_context(context)
743 symbol, leftover = self._symbol_from_context(context)
743 if symbol is not None and not leftover:
744 if symbol is not None and not leftover:
744 doc = getattr(symbol, '__doc__', '')
745 doc = getattr(symbol, '__doc__', '')
745 else:
746 else:
746 doc = ''
747 doc = ''
747 object_info = dict(docstring = doc)
748 object_info = dict(docstring = doc)
748 return object_info
749 return object_info
749
750
750 def _symbol_from_context(self, context):
751 def _symbol_from_context(self, context):
751 if not context:
752 if not context:
752 return None, context
753 return None, context
753
754
754 base_symbol_string = context[0]
755 base_symbol_string = context[0]
755 symbol = self.shell.user_ns.get(base_symbol_string, None)
756 symbol = self.shell.user_ns.get(base_symbol_string, None)
756 if symbol is None:
757 if symbol is None:
757 symbol = __builtin__.__dict__.get(base_symbol_string, None)
758 symbol = __builtin__.__dict__.get(base_symbol_string, None)
758 if symbol is None:
759 if symbol is None:
759 return None, context
760 return None, context
760
761
761 context = context[1:]
762 context = context[1:]
762 for i, name in enumerate(context):
763 for i, name in enumerate(context):
763 new_symbol = getattr(symbol, name, None)
764 new_symbol = getattr(symbol, name, None)
764 if new_symbol is None:
765 if new_symbol is None:
765 return symbol, context[i:]
766 return symbol, context[i:]
766 else:
767 else:
767 symbol = new_symbol
768 symbol = new_symbol
768
769
769 return symbol, []
770 return symbol, []
770
771
771 def _at_shutdown(self):
772 def _at_shutdown(self):
772 """Actions taken at shutdown by the kernel, called by python's atexit.
773 """Actions taken at shutdown by the kernel, called by python's atexit.
773 """
774 """
774 # io.rprint("Kernel at_shutdown") # dbg
775 # io.rprint("Kernel at_shutdown") # dbg
775 if self._shutdown_message is not None:
776 if self._shutdown_message is not None:
776 self.session.send(self.iopub_socket, self._shutdown_message, ident=self._topic('shutdown'))
777 self.session.send(self.iopub_socket, self._shutdown_message, ident=self._topic('shutdown'))
777 self.log.debug("%s", self._shutdown_message)
778 self.log.debug("%s", self._shutdown_message)
778 [ s.flush(zmq.POLLOUT) for s in self.shell_streams ]
779 [ s.flush(zmq.POLLOUT) for s in self.shell_streams ]
779
780
780 #-----------------------------------------------------------------------------
781 #-----------------------------------------------------------------------------
781 # Aliases and Flags for the IPKernelApp
782 # Aliases and Flags for the IPKernelApp
782 #-----------------------------------------------------------------------------
783 #-----------------------------------------------------------------------------
783
784
784 flags = dict(kernel_flags)
785 flags = dict(kernel_flags)
785 flags.update(shell_flags)
786 flags.update(shell_flags)
786
787
787 addflag = lambda *args: flags.update(boolean_flag(*args))
788 addflag = lambda *args: flags.update(boolean_flag(*args))
788
789
789 flags['pylab'] = (
790 flags['pylab'] = (
790 {'IPKernelApp' : {'pylab' : 'auto'}},
791 {'IPKernelApp' : {'pylab' : 'auto'}},
791 """Pre-load matplotlib and numpy for interactive use with
792 """Pre-load matplotlib and numpy for interactive use with
792 the default matplotlib backend."""
793 the default matplotlib backend."""
793 )
794 )
794
795
795 aliases = dict(kernel_aliases)
796 aliases = dict(kernel_aliases)
796 aliases.update(shell_aliases)
797 aliases.update(shell_aliases)
797
798
798 #-----------------------------------------------------------------------------
799 #-----------------------------------------------------------------------------
799 # The IPKernelApp class
800 # The IPKernelApp class
800 #-----------------------------------------------------------------------------
801 #-----------------------------------------------------------------------------
801
802
802 class IPKernelApp(KernelApp, InteractiveShellApp):
803 class IPKernelApp(KernelApp, InteractiveShellApp):
803 name = 'ipkernel'
804 name = 'ipkernel'
804
805
805 aliases = Dict(aliases)
806 aliases = Dict(aliases)
806 flags = Dict(flags)
807 flags = Dict(flags)
807 classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session]
808 classes = [Kernel, ZMQInteractiveShell, ProfileDir, Session]
808
809
809 @catch_config_error
810 @catch_config_error
810 def initialize(self, argv=None):
811 def initialize(self, argv=None):
811 super(IPKernelApp, self).initialize(argv)
812 super(IPKernelApp, self).initialize(argv)
812 self.init_path()
813 self.init_path()
813 self.init_shell()
814 self.init_shell()
814 self.init_gui_pylab()
815 self.init_gui_pylab()
815 self.init_extensions()
816 self.init_extensions()
816 self.init_code()
817 self.init_code()
817
818
818 def init_kernel(self):
819 def init_kernel(self):
819
820
820 shell_stream = ZMQStream(self.shell_socket)
821 shell_stream = ZMQStream(self.shell_socket)
821
822
822 kernel = Kernel(config=self.config, session=self.session,
823 kernel = Kernel(config=self.config, session=self.session,
823 shell_streams=[shell_stream],
824 shell_streams=[shell_stream],
824 iopub_socket=self.iopub_socket,
825 iopub_socket=self.iopub_socket,
825 stdin_socket=self.stdin_socket,
826 stdin_socket=self.stdin_socket,
826 log=self.log,
827 log=self.log,
827 profile_dir=self.profile_dir,
828 profile_dir=self.profile_dir,
828 )
829 )
829 self.kernel = kernel
830 self.kernel = kernel
830 kernel.record_ports(self.ports)
831 kernel.record_ports(self.ports)
831 shell = kernel.shell
832 shell = kernel.shell
832
833
833 def init_gui_pylab(self):
834 def init_gui_pylab(self):
834 """Enable GUI event loop integration, taking pylab into account."""
835 """Enable GUI event loop integration, taking pylab into account."""
835
836
836 # Provide a wrapper for :meth:`InteractiveShellApp.init_gui_pylab`
837 # Provide a wrapper for :meth:`InteractiveShellApp.init_gui_pylab`
837 # to ensure that any exception is printed straight to stderr.
838 # to ensure that any exception is printed straight to stderr.
838 # Normally _showtraceback associates the reply with an execution,
839 # Normally _showtraceback associates the reply with an execution,
839 # which means frontends will never draw it, as this exception
840 # which means frontends will never draw it, as this exception
840 # is not associated with any execute request.
841 # is not associated with any execute request.
841
842
842 shell = self.shell
843 shell = self.shell
843 _showtraceback = shell._showtraceback
844 _showtraceback = shell._showtraceback
844 try:
845 try:
845 # replace pyerr-sending traceback with stderr
846 # replace pyerr-sending traceback with stderr
846 def print_tb(etype, evalue, stb):
847 def print_tb(etype, evalue, stb):
847 print ("GUI event loop or pylab initialization failed",
848 print ("GUI event loop or pylab initialization failed",
848 file=io.stderr)
849 file=io.stderr)
849 print (shell.InteractiveTB.stb2text(stb), file=io.stderr)
850 print (shell.InteractiveTB.stb2text(stb), file=io.stderr)
850 shell._showtraceback = print_tb
851 shell._showtraceback = print_tb
851 InteractiveShellApp.init_gui_pylab(self)
852 InteractiveShellApp.init_gui_pylab(self)
852 finally:
853 finally:
853 shell._showtraceback = _showtraceback
854 shell._showtraceback = _showtraceback
854
855
855 def init_shell(self):
856 def init_shell(self):
856 self.shell = self.kernel.shell
857 self.shell = self.kernel.shell
857 self.shell.configurables.append(self)
858 self.shell.configurables.append(self)
858
859
859
860
860 #-----------------------------------------------------------------------------
861 #-----------------------------------------------------------------------------
861 # Kernel main and launch functions
862 # Kernel main and launch functions
862 #-----------------------------------------------------------------------------
863 #-----------------------------------------------------------------------------
863
864
864 def launch_kernel(*args, **kwargs):
865 def launch_kernel(*args, **kwargs):
865 """Launches a localhost IPython kernel, binding to the specified ports.
866 """Launches a localhost IPython kernel, binding to the specified ports.
866
867
867 This function simply calls entry_point.base_launch_kernel with the right
868 This function simply calls entry_point.base_launch_kernel with the right
868 first command to start an ipkernel. See base_launch_kernel for arguments.
869 first command to start an ipkernel. See base_launch_kernel for arguments.
869
870
870 Returns
871 Returns
871 -------
872 -------
872 A tuple of form:
873 A tuple of form:
873 (kernel_process, shell_port, iopub_port, stdin_port, hb_port)
874 (kernel_process, shell_port, iopub_port, stdin_port, hb_port)
874 where kernel_process is a Popen object and the ports are integers.
875 where kernel_process is a Popen object and the ports are integers.
875 """
876 """
876 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
877 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
877 *args, **kwargs)
878 *args, **kwargs)
878
879
879
880
880 def embed_kernel(module=None, local_ns=None, **kwargs):
881 def embed_kernel(module=None, local_ns=None, **kwargs):
881 """Embed and start an IPython kernel in a given scope.
882 """Embed and start an IPython kernel in a given scope.
882
883
883 Parameters
884 Parameters
884 ----------
885 ----------
885 module : ModuleType, optional
886 module : ModuleType, optional
886 The module to load into IPython globals (default: caller)
887 The module to load into IPython globals (default: caller)
887 local_ns : dict, optional
888 local_ns : dict, optional
888 The namespace to load into IPython user namespace (default: caller)
889 The namespace to load into IPython user namespace (default: caller)
889
890
890 kwargs : various, optional
891 kwargs : various, optional
891 Further keyword args are relayed to the KernelApp constructor,
892 Further keyword args are relayed to the KernelApp constructor,
892 allowing configuration of the Kernel. Will only have an effect
893 allowing configuration of the Kernel. Will only have an effect
893 on the first embed_kernel call for a given process.
894 on the first embed_kernel call for a given process.
894
895
895 """
896 """
896 # get the app if it exists, or set it up if it doesn't
897 # get the app if it exists, or set it up if it doesn't
897 if IPKernelApp.initialized():
898 if IPKernelApp.initialized():
898 app = IPKernelApp.instance()
899 app = IPKernelApp.instance()
899 else:
900 else:
900 app = IPKernelApp.instance(**kwargs)
901 app = IPKernelApp.instance(**kwargs)
901 app.initialize([])
902 app.initialize([])
902 # Undo unnecessary sys module mangling from init_sys_modules.
903 # Undo unnecessary sys module mangling from init_sys_modules.
903 # This would not be necessary if we could prevent it
904 # This would not be necessary if we could prevent it
904 # in the first place by using a different InteractiveShell
905 # in the first place by using a different InteractiveShell
905 # subclass, as in the regular embed case.
906 # subclass, as in the regular embed case.
906 main = app.kernel.shell._orig_sys_modules_main_mod
907 main = app.kernel.shell._orig_sys_modules_main_mod
907 if main is not None:
908 if main is not None:
908 sys.modules[app.kernel.shell._orig_sys_modules_main_name] = main
909 sys.modules[app.kernel.shell._orig_sys_modules_main_name] = main
909
910
910 # load the calling scope if not given
911 # load the calling scope if not given
911 (caller_module, caller_locals) = extract_module_locals(1)
912 (caller_module, caller_locals) = extract_module_locals(1)
912 if module is None:
913 if module is None:
913 module = caller_module
914 module = caller_module
914 if local_ns is None:
915 if local_ns is None:
915 local_ns = caller_locals
916 local_ns = caller_locals
916
917
917 app.kernel.user_module = module
918 app.kernel.user_module = module
918 app.kernel.user_ns = local_ns
919 app.kernel.user_ns = local_ns
919 app.shell.set_completer_frame()
920 app.shell.set_completer_frame()
920 app.start()
921 app.start()
921
922
922 def main():
923 def main():
923 """Run an IPKernel as an application"""
924 """Run an IPKernel as an application"""
924 app = IPKernelApp.instance()
925 app = IPKernelApp.instance()
925 app.initialize()
926 app.initialize()
926 app.start()
927 app.start()
927
928
928
929
929 if __name__ == '__main__':
930 if __name__ == '__main__':
930 main()
931 main()
@@ -1,994 +1,999 b''
1 """Base classes to manage the interaction with a running kernel.
1 """Base classes to manage the interaction with a running kernel.
2
2
3 TODO
3 TODO
4 * Create logger to handle debugging and console messages.
4 * Create logger to handle debugging and console messages.
5 """
5 """
6
6
7 #-----------------------------------------------------------------------------
7 #-----------------------------------------------------------------------------
8 # Copyright (C) 2008-2011 The IPython Development Team
8 # Copyright (C) 2008-2011 The IPython Development Team
9 #
9 #
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 # Standard library imports.
18 # Standard library imports.
19 import atexit
19 import atexit
20 import errno
20 import errno
21 import json
21 import json
22 from subprocess import Popen
22 from subprocess import Popen
23 import os
23 import os
24 import signal
24 import signal
25 import sys
25 import sys
26 from threading import Thread
26 from threading import Thread
27 import time
27 import time
28
28
29 # System library imports.
29 # System library imports.
30 import zmq
30 import zmq
31 # import ZMQError in top-level namespace, to avoid ugly attribute-error messages
31 # import ZMQError in top-level namespace, to avoid ugly attribute-error messages
32 # during garbage collection of threads at exit:
32 # during garbage collection of threads at exit:
33 from zmq import ZMQError
33 from zmq import ZMQError
34 from zmq.eventloop import ioloop, zmqstream
34 from zmq.eventloop import ioloop, zmqstream
35
35
36 # Local imports.
36 # Local imports.
37 from IPython.config.loader import Config
37 from IPython.config.loader import Config
38 from IPython.utils.localinterfaces import LOCALHOST, LOCAL_IPS
38 from IPython.utils.localinterfaces import LOCALHOST, LOCAL_IPS
39 from IPython.utils.traitlets import (
39 from IPython.utils.traitlets import (
40 HasTraits, Any, Instance, Type, Unicode, Integer, Bool
40 HasTraits, Any, Instance, Type, Unicode, Integer, Bool
41 )
41 )
42 from IPython.utils.py3compat import str_to_bytes
42 from IPython.utils.py3compat import str_to_bytes
43 from IPython.zmq.entry_point import write_connection_file
43 from IPython.zmq.entry_point import write_connection_file
44 from session import Session
44 from session import Session
45
45
46 #-----------------------------------------------------------------------------
46 #-----------------------------------------------------------------------------
47 # Constants and exceptions
47 # Constants and exceptions
48 #-----------------------------------------------------------------------------
48 #-----------------------------------------------------------------------------
49
49
50 class InvalidPortNumber(Exception):
50 class InvalidPortNumber(Exception):
51 pass
51 pass
52
52
53 #-----------------------------------------------------------------------------
53 #-----------------------------------------------------------------------------
54 # Utility functions
54 # Utility functions
55 #-----------------------------------------------------------------------------
55 #-----------------------------------------------------------------------------
56
56
57 # some utilities to validate message structure, these might get moved elsewhere
57 # some utilities to validate message structure, these might get moved elsewhere
58 # if they prove to have more generic utility
58 # if they prove to have more generic utility
59
59
60 def validate_string_list(lst):
60 def validate_string_list(lst):
61 """Validate that the input is a list of strings.
61 """Validate that the input is a list of strings.
62
62
63 Raises ValueError if not."""
63 Raises ValueError if not."""
64 if not isinstance(lst, list):
64 if not isinstance(lst, list):
65 raise ValueError('input %r must be a list' % lst)
65 raise ValueError('input %r must be a list' % lst)
66 for x in lst:
66 for x in lst:
67 if not isinstance(x, basestring):
67 if not isinstance(x, basestring):
68 raise ValueError('element %r in list must be a string' % x)
68 raise ValueError('element %r in list must be a string' % x)
69
69
70
70
71 def validate_string_dict(dct):
71 def validate_string_dict(dct):
72 """Validate that the input is a dict with string keys and values.
72 """Validate that the input is a dict with string keys and values.
73
73
74 Raises ValueError if not."""
74 Raises ValueError if not."""
75 for k,v in dct.iteritems():
75 for k,v in dct.iteritems():
76 if not isinstance(k, basestring):
76 if not isinstance(k, basestring):
77 raise ValueError('key %r in dict must be a string' % k)
77 raise ValueError('key %r in dict must be a string' % k)
78 if not isinstance(v, basestring):
78 if not isinstance(v, basestring):
79 raise ValueError('value %r in dict must be a string' % v)
79 raise ValueError('value %r in dict must be a string' % v)
80
80
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # ZMQ Socket Channel classes
83 # ZMQ Socket Channel classes
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86 class ZMQSocketChannel(Thread):
86 class ZMQSocketChannel(Thread):
87 """The base class for the channels that use ZMQ sockets.
87 """The base class for the channels that use ZMQ sockets.
88 """
88 """
89 context = None
89 context = None
90 session = None
90 session = None
91 socket = None
91 socket = None
92 ioloop = None
92 ioloop = None
93 stream = None
93 stream = None
94 _address = None
94 _address = None
95 _exiting = False
95 _exiting = False
96
96
97 def __init__(self, context, session, address):
97 def __init__(self, context, session, address):
98 """Create a channel
98 """Create a channel
99
99
100 Parameters
100 Parameters
101 ----------
101 ----------
102 context : :class:`zmq.Context`
102 context : :class:`zmq.Context`
103 The ZMQ context to use.
103 The ZMQ context to use.
104 session : :class:`session.Session`
104 session : :class:`session.Session`
105 The session to use.
105 The session to use.
106 address : tuple
106 address : tuple
107 Standard (ip, port) tuple that the kernel is listening on.
107 Standard (ip, port) tuple that the kernel is listening on.
108 """
108 """
109 super(ZMQSocketChannel, self).__init__()
109 super(ZMQSocketChannel, self).__init__()
110 self.daemon = True
110 self.daemon = True
111
111
112 self.context = context
112 self.context = context
113 self.session = session
113 self.session = session
114 if address[1] == 0:
114 if address[1] == 0:
115 message = 'The port number for a channel cannot be 0.'
115 message = 'The port number for a channel cannot be 0.'
116 raise InvalidPortNumber(message)
116 raise InvalidPortNumber(message)
117 self._address = address
117 self._address = address
118 atexit.register(self._notice_exit)
118 atexit.register(self._notice_exit)
119
119
120 def _notice_exit(self):
120 def _notice_exit(self):
121 self._exiting = True
121 self._exiting = True
122
122
123 def _run_loop(self):
123 def _run_loop(self):
124 """Run my loop, ignoring EINTR events in the poller"""
124 """Run my loop, ignoring EINTR events in the poller"""
125 while True:
125 while True:
126 try:
126 try:
127 self.ioloop.start()
127 self.ioloop.start()
128 except ZMQError as e:
128 except ZMQError as e:
129 if e.errno == errno.EINTR:
129 if e.errno == errno.EINTR:
130 continue
130 continue
131 else:
131 else:
132 raise
132 raise
133 except Exception:
133 except Exception:
134 if self._exiting:
134 if self._exiting:
135 break
135 break
136 else:
136 else:
137 raise
137 raise
138 else:
138 else:
139 break
139 break
140
140
141 def stop(self):
141 def stop(self):
142 """Stop the channel's activity.
142 """Stop the channel's activity.
143
143
144 This calls :method:`Thread.join` and returns when the thread
144 This calls :method:`Thread.join` and returns when the thread
145 terminates. :class:`RuntimeError` will be raised if
145 terminates. :class:`RuntimeError` will be raised if
146 :method:`self.start` is called again.
146 :method:`self.start` is called again.
147 """
147 """
148 self.join()
148 self.join()
149
149
150 @property
150 @property
151 def address(self):
151 def address(self):
152 """Get the channel's address as an (ip, port) tuple.
152 """Get the channel's address as an (ip, port) tuple.
153
153
154 By the default, the address is (localhost, 0), where 0 means a random
154 By the default, the address is (localhost, 0), where 0 means a random
155 port.
155 port.
156 """
156 """
157 return self._address
157 return self._address
158
158
159 def _queue_send(self, msg):
159 def _queue_send(self, msg):
160 """Queue a message to be sent from the IOLoop's thread.
160 """Queue a message to be sent from the IOLoop's thread.
161
161
162 Parameters
162 Parameters
163 ----------
163 ----------
164 msg : message to send
164 msg : message to send
165
165
166 This is threadsafe, as it uses IOLoop.add_callback to give the loop's
166 This is threadsafe, as it uses IOLoop.add_callback to give the loop's
167 thread control of the action.
167 thread control of the action.
168 """
168 """
169 def thread_send():
169 def thread_send():
170 self.session.send(self.stream, msg)
170 self.session.send(self.stream, msg)
171 self.ioloop.add_callback(thread_send)
171 self.ioloop.add_callback(thread_send)
172
172
173 def _handle_recv(self, msg):
173 def _handle_recv(self, msg):
174 """callback for stream.on_recv
174 """callback for stream.on_recv
175
175
176 unpacks message, and calls handlers with it.
176 unpacks message, and calls handlers with it.
177 """
177 """
178 ident,smsg = self.session.feed_identities(msg)
178 ident,smsg = self.session.feed_identities(msg)
179 self.call_handlers(self.session.unserialize(smsg))
179 self.call_handlers(self.session.unserialize(smsg))
180
180
181
181
182
182
183 class ShellSocketChannel(ZMQSocketChannel):
183 class ShellSocketChannel(ZMQSocketChannel):
184 """The DEALER channel for issues request/replies to the kernel.
184 """The DEALER channel for issues request/replies to the kernel.
185 """
185 """
186
186
187 command_queue = None
187 command_queue = None
188 # flag for whether execute requests should be allowed to call raw_input:
188 # flag for whether execute requests should be allowed to call raw_input:
189 allow_stdin = True
189 allow_stdin = True
190
190
191 def __init__(self, context, session, address):
191 def __init__(self, context, session, address):
192 super(ShellSocketChannel, self).__init__(context, session, address)
192 super(ShellSocketChannel, self).__init__(context, session, address)
193 self.ioloop = ioloop.IOLoop()
193 self.ioloop = ioloop.IOLoop()
194
194
195 def run(self):
195 def run(self):
196 """The thread's main activity. Call start() instead."""
196 """The thread's main activity. Call start() instead."""
197 self.socket = self.context.socket(zmq.DEALER)
197 self.socket = self.context.socket(zmq.DEALER)
198 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
198 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
199 self.socket.connect('tcp://%s:%i' % self.address)
199 self.socket.connect('tcp://%s:%i' % self.address)
200 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
200 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
201 self.stream.on_recv(self._handle_recv)
201 self.stream.on_recv(self._handle_recv)
202 self._run_loop()
202 self._run_loop()
203 try:
203 try:
204 self.socket.close()
204 self.socket.close()
205 except:
205 except:
206 pass
206 pass
207
207
208 def stop(self):
208 def stop(self):
209 self.ioloop.stop()
209 self.ioloop.stop()
210 super(ShellSocketChannel, self).stop()
210 super(ShellSocketChannel, self).stop()
211
211
212 def call_handlers(self, msg):
212 def call_handlers(self, msg):
213 """This method is called in the ioloop thread when a message arrives.
213 """This method is called in the ioloop thread when a message arrives.
214
214
215 Subclasses should override this method to handle incoming messages.
215 Subclasses should override this method to handle incoming messages.
216 It is important to remember that this method is called in the thread
216 It is important to remember that this method is called in the thread
217 so that some logic must be done to ensure that the application leve
217 so that some logic must be done to ensure that the application leve
218 handlers are called in the application thread.
218 handlers are called in the application thread.
219 """
219 """
220 raise NotImplementedError('call_handlers must be defined in a subclass.')
220 raise NotImplementedError('call_handlers must be defined in a subclass.')
221
221
222 def execute(self, code, silent=False,
222 def execute(self, code, silent=False, store_history=True,
223 user_variables=None, user_expressions=None, allow_stdin=None):
223 user_variables=None, user_expressions=None, allow_stdin=None):
224 """Execute code in the kernel.
224 """Execute code in the kernel.
225
225
226 Parameters
226 Parameters
227 ----------
227 ----------
228 code : str
228 code : str
229 A string of Python code.
229 A string of Python code.
230
230
231 silent : bool, optional (default False)
231 silent : bool, optional (default False)
232 If set, the kernel will execute the code as quietly possible.
232 If set, the kernel will execute the code as quietly possible, and
233 will force store_history to be False.
234
235 store_history : bool, optional (default True)
236 If set, the kernel will store command history. This is forced
237 to be False if silent is True.
233
238
234 user_variables : list, optional
239 user_variables : list, optional
235 A list of variable names to pull from the user's namespace. They
240 A list of variable names to pull from the user's namespace. They
236 will come back as a dict with these names as keys and their
241 will come back as a dict with these names as keys and their
237 :func:`repr` as values.
242 :func:`repr` as values.
238
243
239 user_expressions : dict, optional
244 user_expressions : dict, optional
240 A dict with string keys and to pull from the user's
245 A dict with string keys and to pull from the user's
241 namespace. They will come back as a dict with these names as keys
246 namespace. They will come back as a dict with these names as keys
242 and their :func:`repr` as values.
247 and their :func:`repr` as values.
243
248
244 allow_stdin : bool, optional
249 allow_stdin : bool, optional
245 Flag for
250 Flag for
246 A dict with string keys and to pull from the user's
251 A dict with string keys and to pull from the user's
247 namespace. They will come back as a dict with these names as keys
252 namespace. They will come back as a dict with these names as keys
248 and their :func:`repr` as values.
253 and their :func:`repr` as values.
249
254
250 Returns
255 Returns
251 -------
256 -------
252 The msg_id of the message sent.
257 The msg_id of the message sent.
253 """
258 """
254 if user_variables is None:
259 if user_variables is None:
255 user_variables = []
260 user_variables = []
256 if user_expressions is None:
261 if user_expressions is None:
257 user_expressions = {}
262 user_expressions = {}
258 if allow_stdin is None:
263 if allow_stdin is None:
259 allow_stdin = self.allow_stdin
264 allow_stdin = self.allow_stdin
260
265
261
266
262 # Don't waste network traffic if inputs are invalid
267 # Don't waste network traffic if inputs are invalid
263 if not isinstance(code, basestring):
268 if not isinstance(code, basestring):
264 raise ValueError('code %r must be a string' % code)
269 raise ValueError('code %r must be a string' % code)
265 validate_string_list(user_variables)
270 validate_string_list(user_variables)
266 validate_string_dict(user_expressions)
271 validate_string_dict(user_expressions)
267
272
268 # Create class for content/msg creation. Related to, but possibly
273 # Create class for content/msg creation. Related to, but possibly
269 # not in Session.
274 # not in Session.
270 content = dict(code=code, silent=silent,
275 content = dict(code=code, silent=silent, store_history=store_history,
271 user_variables=user_variables,
276 user_variables=user_variables,
272 user_expressions=user_expressions,
277 user_expressions=user_expressions,
273 allow_stdin=allow_stdin,
278 allow_stdin=allow_stdin,
274 )
279 )
275 msg = self.session.msg('execute_request', content)
280 msg = self.session.msg('execute_request', content)
276 self._queue_send(msg)
281 self._queue_send(msg)
277 return msg['header']['msg_id']
282 return msg['header']['msg_id']
278
283
279 def complete(self, text, line, cursor_pos, block=None):
284 def complete(self, text, line, cursor_pos, block=None):
280 """Tab complete text in the kernel's namespace.
285 """Tab complete text in the kernel's namespace.
281
286
282 Parameters
287 Parameters
283 ----------
288 ----------
284 text : str
289 text : str
285 The text to complete.
290 The text to complete.
286 line : str
291 line : str
287 The full line of text that is the surrounding context for the
292 The full line of text that is the surrounding context for the
288 text to complete.
293 text to complete.
289 cursor_pos : int
294 cursor_pos : int
290 The position of the cursor in the line where the completion was
295 The position of the cursor in the line where the completion was
291 requested.
296 requested.
292 block : str, optional
297 block : str, optional
293 The full block of code in which the completion is being requested.
298 The full block of code in which the completion is being requested.
294
299
295 Returns
300 Returns
296 -------
301 -------
297 The msg_id of the message sent.
302 The msg_id of the message sent.
298 """
303 """
299 content = dict(text=text, line=line, block=block, cursor_pos=cursor_pos)
304 content = dict(text=text, line=line, block=block, cursor_pos=cursor_pos)
300 msg = self.session.msg('complete_request', content)
305 msg = self.session.msg('complete_request', content)
301 self._queue_send(msg)
306 self._queue_send(msg)
302 return msg['header']['msg_id']
307 return msg['header']['msg_id']
303
308
304 def object_info(self, oname, detail_level=0):
309 def object_info(self, oname, detail_level=0):
305 """Get metadata information about an object.
310 """Get metadata information about an object.
306
311
307 Parameters
312 Parameters
308 ----------
313 ----------
309 oname : str
314 oname : str
310 A string specifying the object name.
315 A string specifying the object name.
311 detail_level : int, optional
316 detail_level : int, optional
312 The level of detail for the introspection (0-2)
317 The level of detail for the introspection (0-2)
313
318
314 Returns
319 Returns
315 -------
320 -------
316 The msg_id of the message sent.
321 The msg_id of the message sent.
317 """
322 """
318 content = dict(oname=oname, detail_level=detail_level)
323 content = dict(oname=oname, detail_level=detail_level)
319 msg = self.session.msg('object_info_request', content)
324 msg = self.session.msg('object_info_request', content)
320 self._queue_send(msg)
325 self._queue_send(msg)
321 return msg['header']['msg_id']
326 return msg['header']['msg_id']
322
327
323 def history(self, raw=True, output=False, hist_access_type='range', **kwargs):
328 def history(self, raw=True, output=False, hist_access_type='range', **kwargs):
324 """Get entries from the history list.
329 """Get entries from the history list.
325
330
326 Parameters
331 Parameters
327 ----------
332 ----------
328 raw : bool
333 raw : bool
329 If True, return the raw input.
334 If True, return the raw input.
330 output : bool
335 output : bool
331 If True, then return the output as well.
336 If True, then return the output as well.
332 hist_access_type : str
337 hist_access_type : str
333 'range' (fill in session, start and stop params), 'tail' (fill in n)
338 'range' (fill in session, start and stop params), 'tail' (fill in n)
334 or 'search' (fill in pattern param).
339 or 'search' (fill in pattern param).
335
340
336 session : int
341 session : int
337 For a range request, the session from which to get lines. Session
342 For a range request, the session from which to get lines. Session
338 numbers are positive integers; negative ones count back from the
343 numbers are positive integers; negative ones count back from the
339 current session.
344 current session.
340 start : int
345 start : int
341 The first line number of a history range.
346 The first line number of a history range.
342 stop : int
347 stop : int
343 The final (excluded) line number of a history range.
348 The final (excluded) line number of a history range.
344
349
345 n : int
350 n : int
346 The number of lines of history to get for a tail request.
351 The number of lines of history to get for a tail request.
347
352
348 pattern : str
353 pattern : str
349 The glob-syntax pattern for a search request.
354 The glob-syntax pattern for a search request.
350
355
351 Returns
356 Returns
352 -------
357 -------
353 The msg_id of the message sent.
358 The msg_id of the message sent.
354 """
359 """
355 content = dict(raw=raw, output=output, hist_access_type=hist_access_type,
360 content = dict(raw=raw, output=output, hist_access_type=hist_access_type,
356 **kwargs)
361 **kwargs)
357 msg = self.session.msg('history_request', content)
362 msg = self.session.msg('history_request', content)
358 self._queue_send(msg)
363 self._queue_send(msg)
359 return msg['header']['msg_id']
364 return msg['header']['msg_id']
360
365
361 def shutdown(self, restart=False):
366 def shutdown(self, restart=False):
362 """Request an immediate kernel shutdown.
367 """Request an immediate kernel shutdown.
363
368
364 Upon receipt of the (empty) reply, client code can safely assume that
369 Upon receipt of the (empty) reply, client code can safely assume that
365 the kernel has shut down and it's safe to forcefully terminate it if
370 the kernel has shut down and it's safe to forcefully terminate it if
366 it's still alive.
371 it's still alive.
367
372
368 The kernel will send the reply via a function registered with Python's
373 The kernel will send the reply via a function registered with Python's
369 atexit module, ensuring it's truly done as the kernel is done with all
374 atexit module, ensuring it's truly done as the kernel is done with all
370 normal operation.
375 normal operation.
371 """
376 """
372 # Send quit message to kernel. Once we implement kernel-side setattr,
377 # Send quit message to kernel. Once we implement kernel-side setattr,
373 # this should probably be done that way, but for now this will do.
378 # this should probably be done that way, but for now this will do.
374 msg = self.session.msg('shutdown_request', {'restart':restart})
379 msg = self.session.msg('shutdown_request', {'restart':restart})
375 self._queue_send(msg)
380 self._queue_send(msg)
376 return msg['header']['msg_id']
381 return msg['header']['msg_id']
377
382
378
383
379
384
380 class SubSocketChannel(ZMQSocketChannel):
385 class SubSocketChannel(ZMQSocketChannel):
381 """The SUB channel which listens for messages that the kernel publishes.
386 """The SUB channel which listens for messages that the kernel publishes.
382 """
387 """
383
388
384 def __init__(self, context, session, address):
389 def __init__(self, context, session, address):
385 super(SubSocketChannel, self).__init__(context, session, address)
390 super(SubSocketChannel, self).__init__(context, session, address)
386 self.ioloop = ioloop.IOLoop()
391 self.ioloop = ioloop.IOLoop()
387
392
388 def run(self):
393 def run(self):
389 """The thread's main activity. Call start() instead."""
394 """The thread's main activity. Call start() instead."""
390 self.socket = self.context.socket(zmq.SUB)
395 self.socket = self.context.socket(zmq.SUB)
391 self.socket.setsockopt(zmq.SUBSCRIBE,b'')
396 self.socket.setsockopt(zmq.SUBSCRIBE,b'')
392 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
397 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
393 self.socket.connect('tcp://%s:%i' % self.address)
398 self.socket.connect('tcp://%s:%i' % self.address)
394 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
399 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
395 self.stream.on_recv(self._handle_recv)
400 self.stream.on_recv(self._handle_recv)
396 self._run_loop()
401 self._run_loop()
397 try:
402 try:
398 self.socket.close()
403 self.socket.close()
399 except:
404 except:
400 pass
405 pass
401
406
402 def stop(self):
407 def stop(self):
403 self.ioloop.stop()
408 self.ioloop.stop()
404 super(SubSocketChannel, self).stop()
409 super(SubSocketChannel, self).stop()
405
410
406 def call_handlers(self, msg):
411 def call_handlers(self, msg):
407 """This method is called in the ioloop thread when a message arrives.
412 """This method is called in the ioloop thread when a message arrives.
408
413
409 Subclasses should override this method to handle incoming messages.
414 Subclasses should override this method to handle incoming messages.
410 It is important to remember that this method is called in the thread
415 It is important to remember that this method is called in the thread
411 so that some logic must be done to ensure that the application leve
416 so that some logic must be done to ensure that the application leve
412 handlers are called in the application thread.
417 handlers are called in the application thread.
413 """
418 """
414 raise NotImplementedError('call_handlers must be defined in a subclass.')
419 raise NotImplementedError('call_handlers must be defined in a subclass.')
415
420
416 def flush(self, timeout=1.0):
421 def flush(self, timeout=1.0):
417 """Immediately processes all pending messages on the SUB channel.
422 """Immediately processes all pending messages on the SUB channel.
418
423
419 Callers should use this method to ensure that :method:`call_handlers`
424 Callers should use this method to ensure that :method:`call_handlers`
420 has been called for all messages that have been received on the
425 has been called for all messages that have been received on the
421 0MQ SUB socket of this channel.
426 0MQ SUB socket of this channel.
422
427
423 This method is thread safe.
428 This method is thread safe.
424
429
425 Parameters
430 Parameters
426 ----------
431 ----------
427 timeout : float, optional
432 timeout : float, optional
428 The maximum amount of time to spend flushing, in seconds. The
433 The maximum amount of time to spend flushing, in seconds. The
429 default is one second.
434 default is one second.
430 """
435 """
431 # We do the IOLoop callback process twice to ensure that the IOLoop
436 # We do the IOLoop callback process twice to ensure that the IOLoop
432 # gets to perform at least one full poll.
437 # gets to perform at least one full poll.
433 stop_time = time.time() + timeout
438 stop_time = time.time() + timeout
434 for i in xrange(2):
439 for i in xrange(2):
435 self._flushed = False
440 self._flushed = False
436 self.ioloop.add_callback(self._flush)
441 self.ioloop.add_callback(self._flush)
437 while not self._flushed and time.time() < stop_time:
442 while not self._flushed and time.time() < stop_time:
438 time.sleep(0.01)
443 time.sleep(0.01)
439
444
440 def _flush(self):
445 def _flush(self):
441 """Callback for :method:`self.flush`."""
446 """Callback for :method:`self.flush`."""
442 self.stream.flush()
447 self.stream.flush()
443 self._flushed = True
448 self._flushed = True
444
449
445
450
446 class StdInSocketChannel(ZMQSocketChannel):
451 class StdInSocketChannel(ZMQSocketChannel):
447 """A reply channel to handle raw_input requests that the kernel makes."""
452 """A reply channel to handle raw_input requests that the kernel makes."""
448
453
449 msg_queue = None
454 msg_queue = None
450
455
451 def __init__(self, context, session, address):
456 def __init__(self, context, session, address):
452 super(StdInSocketChannel, self).__init__(context, session, address)
457 super(StdInSocketChannel, self).__init__(context, session, address)
453 self.ioloop = ioloop.IOLoop()
458 self.ioloop = ioloop.IOLoop()
454
459
455 def run(self):
460 def run(self):
456 """The thread's main activity. Call start() instead."""
461 """The thread's main activity. Call start() instead."""
457 self.socket = self.context.socket(zmq.DEALER)
462 self.socket = self.context.socket(zmq.DEALER)
458 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
463 self.socket.setsockopt(zmq.IDENTITY, self.session.bsession)
459 self.socket.connect('tcp://%s:%i' % self.address)
464 self.socket.connect('tcp://%s:%i' % self.address)
460 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
465 self.stream = zmqstream.ZMQStream(self.socket, self.ioloop)
461 self.stream.on_recv(self._handle_recv)
466 self.stream.on_recv(self._handle_recv)
462 self._run_loop()
467 self._run_loop()
463 try:
468 try:
464 self.socket.close()
469 self.socket.close()
465 except:
470 except:
466 pass
471 pass
467
472
468
473
469 def stop(self):
474 def stop(self):
470 self.ioloop.stop()
475 self.ioloop.stop()
471 super(StdInSocketChannel, self).stop()
476 super(StdInSocketChannel, self).stop()
472
477
473 def call_handlers(self, msg):
478 def call_handlers(self, msg):
474 """This method is called in the ioloop thread when a message arrives.
479 """This method is called in the ioloop thread when a message arrives.
475
480
476 Subclasses should override this method to handle incoming messages.
481 Subclasses should override this method to handle incoming messages.
477 It is important to remember that this method is called in the thread
482 It is important to remember that this method is called in the thread
478 so that some logic must be done to ensure that the application leve
483 so that some logic must be done to ensure that the application leve
479 handlers are called in the application thread.
484 handlers are called in the application thread.
480 """
485 """
481 raise NotImplementedError('call_handlers must be defined in a subclass.')
486 raise NotImplementedError('call_handlers must be defined in a subclass.')
482
487
483 def input(self, string):
488 def input(self, string):
484 """Send a string of raw input to the kernel."""
489 """Send a string of raw input to the kernel."""
485 content = dict(value=string)
490 content = dict(value=string)
486 msg = self.session.msg('input_reply', content)
491 msg = self.session.msg('input_reply', content)
487 self._queue_send(msg)
492 self._queue_send(msg)
488
493
489
494
490 class HBSocketChannel(ZMQSocketChannel):
495 class HBSocketChannel(ZMQSocketChannel):
491 """The heartbeat channel which monitors the kernel heartbeat.
496 """The heartbeat channel which monitors the kernel heartbeat.
492
497
493 Note that the heartbeat channel is paused by default. As long as you start
498 Note that the heartbeat channel is paused by default. As long as you start
494 this channel, the kernel manager will ensure that it is paused and un-paused
499 this channel, the kernel manager will ensure that it is paused and un-paused
495 as appropriate.
500 as appropriate.
496 """
501 """
497
502
498 time_to_dead = 3.0
503 time_to_dead = 3.0
499 socket = None
504 socket = None
500 poller = None
505 poller = None
501 _running = None
506 _running = None
502 _pause = None
507 _pause = None
503 _beating = None
508 _beating = None
504
509
505 def __init__(self, context, session, address):
510 def __init__(self, context, session, address):
506 super(HBSocketChannel, self).__init__(context, session, address)
511 super(HBSocketChannel, self).__init__(context, session, address)
507 self._running = False
512 self._running = False
508 self._pause =True
513 self._pause =True
509 self.poller = zmq.Poller()
514 self.poller = zmq.Poller()
510
515
511 def _create_socket(self):
516 def _create_socket(self):
512 if self.socket is not None:
517 if self.socket is not None:
513 # close previous socket, before opening a new one
518 # close previous socket, before opening a new one
514 self.poller.unregister(self.socket)
519 self.poller.unregister(self.socket)
515 self.socket.close()
520 self.socket.close()
516 self.socket = self.context.socket(zmq.REQ)
521 self.socket = self.context.socket(zmq.REQ)
517 self.socket.setsockopt(zmq.LINGER, 0)
522 self.socket.setsockopt(zmq.LINGER, 0)
518 self.socket.connect('tcp://%s:%i' % self.address)
523 self.socket.connect('tcp://%s:%i' % self.address)
519
524
520 self.poller.register(self.socket, zmq.POLLIN)
525 self.poller.register(self.socket, zmq.POLLIN)
521
526
522 def _poll(self, start_time):
527 def _poll(self, start_time):
523 """poll for heartbeat replies until we reach self.time_to_dead
528 """poll for heartbeat replies until we reach self.time_to_dead
524
529
525 Ignores interrupts, and returns the result of poll(), which
530 Ignores interrupts, and returns the result of poll(), which
526 will be an empty list if no messages arrived before the timeout,
531 will be an empty list if no messages arrived before the timeout,
527 or the event tuple if there is a message to receive.
532 or the event tuple if there is a message to receive.
528 """
533 """
529
534
530 until_dead = self.time_to_dead - (time.time() - start_time)
535 until_dead = self.time_to_dead - (time.time() - start_time)
531 # ensure poll at least once
536 # ensure poll at least once
532 until_dead = max(until_dead, 1e-3)
537 until_dead = max(until_dead, 1e-3)
533 events = []
538 events = []
534 while True:
539 while True:
535 try:
540 try:
536 events = self.poller.poll(1000 * until_dead)
541 events = self.poller.poll(1000 * until_dead)
537 except ZMQError as e:
542 except ZMQError as e:
538 if e.errno == errno.EINTR:
543 if e.errno == errno.EINTR:
539 # ignore interrupts during heartbeat
544 # ignore interrupts during heartbeat
540 # this may never actually happen
545 # this may never actually happen
541 until_dead = self.time_to_dead - (time.time() - start_time)
546 until_dead = self.time_to_dead - (time.time() - start_time)
542 until_dead = max(until_dead, 1e-3)
547 until_dead = max(until_dead, 1e-3)
543 pass
548 pass
544 else:
549 else:
545 raise
550 raise
546 except Exception:
551 except Exception:
547 if self._exiting:
552 if self._exiting:
548 break
553 break
549 else:
554 else:
550 raise
555 raise
551 else:
556 else:
552 break
557 break
553 return events
558 return events
554
559
555 def run(self):
560 def run(self):
556 """The thread's main activity. Call start() instead."""
561 """The thread's main activity. Call start() instead."""
557 self._create_socket()
562 self._create_socket()
558 self._running = True
563 self._running = True
559 self._beating = True
564 self._beating = True
560
565
561 while self._running:
566 while self._running:
562 if self._pause:
567 if self._pause:
563 # just sleep, and skip the rest of the loop
568 # just sleep, and skip the rest of the loop
564 time.sleep(self.time_to_dead)
569 time.sleep(self.time_to_dead)
565 continue
570 continue
566
571
567 since_last_heartbeat = 0.0
572 since_last_heartbeat = 0.0
568 # io.rprint('Ping from HB channel') # dbg
573 # io.rprint('Ping from HB channel') # dbg
569 # no need to catch EFSM here, because the previous event was
574 # no need to catch EFSM here, because the previous event was
570 # either a recv or connect, which cannot be followed by EFSM
575 # either a recv or connect, which cannot be followed by EFSM
571 self.socket.send(b'ping')
576 self.socket.send(b'ping')
572 request_time = time.time()
577 request_time = time.time()
573 ready = self._poll(request_time)
578 ready = self._poll(request_time)
574 if ready:
579 if ready:
575 self._beating = True
580 self._beating = True
576 # the poll above guarantees we have something to recv
581 # the poll above guarantees we have something to recv
577 self.socket.recv()
582 self.socket.recv()
578 # sleep the remainder of the cycle
583 # sleep the remainder of the cycle
579 remainder = self.time_to_dead - (time.time() - request_time)
584 remainder = self.time_to_dead - (time.time() - request_time)
580 if remainder > 0:
585 if remainder > 0:
581 time.sleep(remainder)
586 time.sleep(remainder)
582 continue
587 continue
583 else:
588 else:
584 # nothing was received within the time limit, signal heart failure
589 # nothing was received within the time limit, signal heart failure
585 self._beating = False
590 self._beating = False
586 since_last_heartbeat = time.time() - request_time
591 since_last_heartbeat = time.time() - request_time
587 self.call_handlers(since_last_heartbeat)
592 self.call_handlers(since_last_heartbeat)
588 # and close/reopen the socket, because the REQ/REP cycle has been broken
593 # and close/reopen the socket, because the REQ/REP cycle has been broken
589 self._create_socket()
594 self._create_socket()
590 continue
595 continue
591 try:
596 try:
592 self.socket.close()
597 self.socket.close()
593 except:
598 except:
594 pass
599 pass
595
600
596 def pause(self):
601 def pause(self):
597 """Pause the heartbeat."""
602 """Pause the heartbeat."""
598 self._pause = True
603 self._pause = True
599
604
600 def unpause(self):
605 def unpause(self):
601 """Unpause the heartbeat."""
606 """Unpause the heartbeat."""
602 self._pause = False
607 self._pause = False
603
608
604 def is_beating(self):
609 def is_beating(self):
605 """Is the heartbeat running and responsive (and not paused)."""
610 """Is the heartbeat running and responsive (and not paused)."""
606 if self.is_alive() and not self._pause and self._beating:
611 if self.is_alive() and not self._pause and self._beating:
607 return True
612 return True
608 else:
613 else:
609 return False
614 return False
610
615
611 def stop(self):
616 def stop(self):
612 self._running = False
617 self._running = False
613 super(HBSocketChannel, self).stop()
618 super(HBSocketChannel, self).stop()
614
619
615 def call_handlers(self, since_last_heartbeat):
620 def call_handlers(self, since_last_heartbeat):
616 """This method is called in the ioloop thread when a message arrives.
621 """This method is called in the ioloop thread when a message arrives.
617
622
618 Subclasses should override this method to handle incoming messages.
623 Subclasses should override this method to handle incoming messages.
619 It is important to remember that this method is called in the thread
624 It is important to remember that this method is called in the thread
620 so that some logic must be done to ensure that the application level
625 so that some logic must be done to ensure that the application level
621 handlers are called in the application thread.
626 handlers are called in the application thread.
622 """
627 """
623 raise NotImplementedError('call_handlers must be defined in a subclass.')
628 raise NotImplementedError('call_handlers must be defined in a subclass.')
624
629
625
630
626 #-----------------------------------------------------------------------------
631 #-----------------------------------------------------------------------------
627 # Main kernel manager class
632 # Main kernel manager class
628 #-----------------------------------------------------------------------------
633 #-----------------------------------------------------------------------------
629
634
630 class KernelManager(HasTraits):
635 class KernelManager(HasTraits):
631 """ Manages a kernel for a frontend.
636 """ Manages a kernel for a frontend.
632
637
633 The SUB channel is for the frontend to receive messages published by the
638 The SUB channel is for the frontend to receive messages published by the
634 kernel.
639 kernel.
635
640
636 The REQ channel is for the frontend to make requests of the kernel.
641 The REQ channel is for the frontend to make requests of the kernel.
637
642
638 The REP channel is for the kernel to request stdin (raw_input) from the
643 The REP channel is for the kernel to request stdin (raw_input) from the
639 frontend.
644 frontend.
640 """
645 """
641 # config object for passing to child configurables
646 # config object for passing to child configurables
642 config = Instance(Config)
647 config = Instance(Config)
643
648
644 # The PyZMQ Context to use for communication with the kernel.
649 # The PyZMQ Context to use for communication with the kernel.
645 context = Instance(zmq.Context)
650 context = Instance(zmq.Context)
646 def _context_default(self):
651 def _context_default(self):
647 return zmq.Context.instance()
652 return zmq.Context.instance()
648
653
649 # The Session to use for communication with the kernel.
654 # The Session to use for communication with the kernel.
650 session = Instance(Session)
655 session = Instance(Session)
651
656
652 # The kernel process with which the KernelManager is communicating.
657 # The kernel process with which the KernelManager is communicating.
653 kernel = Instance(Popen)
658 kernel = Instance(Popen)
654
659
655 # The addresses for the communication channels.
660 # The addresses for the communication channels.
656 connection_file = Unicode('')
661 connection_file = Unicode('')
657 ip = Unicode(LOCALHOST)
662 ip = Unicode(LOCALHOST)
658 def _ip_changed(self, name, old, new):
663 def _ip_changed(self, name, old, new):
659 if new == '*':
664 if new == '*':
660 self.ip = '0.0.0.0'
665 self.ip = '0.0.0.0'
661 shell_port = Integer(0)
666 shell_port = Integer(0)
662 iopub_port = Integer(0)
667 iopub_port = Integer(0)
663 stdin_port = Integer(0)
668 stdin_port = Integer(0)
664 hb_port = Integer(0)
669 hb_port = Integer(0)
665
670
666 # The classes to use for the various channels.
671 # The classes to use for the various channels.
667 shell_channel_class = Type(ShellSocketChannel)
672 shell_channel_class = Type(ShellSocketChannel)
668 sub_channel_class = Type(SubSocketChannel)
673 sub_channel_class = Type(SubSocketChannel)
669 stdin_channel_class = Type(StdInSocketChannel)
674 stdin_channel_class = Type(StdInSocketChannel)
670 hb_channel_class = Type(HBSocketChannel)
675 hb_channel_class = Type(HBSocketChannel)
671
676
672 # Protected traits.
677 # Protected traits.
673 _launch_args = Any
678 _launch_args = Any
674 _shell_channel = Any
679 _shell_channel = Any
675 _sub_channel = Any
680 _sub_channel = Any
676 _stdin_channel = Any
681 _stdin_channel = Any
677 _hb_channel = Any
682 _hb_channel = Any
678 _connection_file_written=Bool(False)
683 _connection_file_written=Bool(False)
679
684
680 def __init__(self, **kwargs):
685 def __init__(self, **kwargs):
681 super(KernelManager, self).__init__(**kwargs)
686 super(KernelManager, self).__init__(**kwargs)
682 if self.session is None:
687 if self.session is None:
683 self.session = Session(config=self.config)
688 self.session = Session(config=self.config)
684
689
685 def __del__(self):
690 def __del__(self):
686 self.cleanup_connection_file()
691 self.cleanup_connection_file()
687
692
688
693
689 #--------------------------------------------------------------------------
694 #--------------------------------------------------------------------------
690 # Channel management methods:
695 # Channel management methods:
691 #--------------------------------------------------------------------------
696 #--------------------------------------------------------------------------
692
697
693 def start_channels(self, shell=True, sub=True, stdin=True, hb=True):
698 def start_channels(self, shell=True, sub=True, stdin=True, hb=True):
694 """Starts the channels for this kernel.
699 """Starts the channels for this kernel.
695
700
696 This will create the channels if they do not exist and then start
701 This will create the channels if they do not exist and then start
697 them. If port numbers of 0 are being used (random ports) then you
702 them. If port numbers of 0 are being used (random ports) then you
698 must first call :method:`start_kernel`. If the channels have been
703 must first call :method:`start_kernel`. If the channels have been
699 stopped and you call this, :class:`RuntimeError` will be raised.
704 stopped and you call this, :class:`RuntimeError` will be raised.
700 """
705 """
701 if shell:
706 if shell:
702 self.shell_channel.start()
707 self.shell_channel.start()
703 if sub:
708 if sub:
704 self.sub_channel.start()
709 self.sub_channel.start()
705 if stdin:
710 if stdin:
706 self.stdin_channel.start()
711 self.stdin_channel.start()
707 self.shell_channel.allow_stdin = True
712 self.shell_channel.allow_stdin = True
708 else:
713 else:
709 self.shell_channel.allow_stdin = False
714 self.shell_channel.allow_stdin = False
710 if hb:
715 if hb:
711 self.hb_channel.start()
716 self.hb_channel.start()
712
717
713 def stop_channels(self):
718 def stop_channels(self):
714 """Stops all the running channels for this kernel.
719 """Stops all the running channels for this kernel.
715 """
720 """
716 if self.shell_channel.is_alive():
721 if self.shell_channel.is_alive():
717 self.shell_channel.stop()
722 self.shell_channel.stop()
718 if self.sub_channel.is_alive():
723 if self.sub_channel.is_alive():
719 self.sub_channel.stop()
724 self.sub_channel.stop()
720 if self.stdin_channel.is_alive():
725 if self.stdin_channel.is_alive():
721 self.stdin_channel.stop()
726 self.stdin_channel.stop()
722 if self.hb_channel.is_alive():
727 if self.hb_channel.is_alive():
723 self.hb_channel.stop()
728 self.hb_channel.stop()
724
729
725 @property
730 @property
726 def channels_running(self):
731 def channels_running(self):
727 """Are any of the channels created and running?"""
732 """Are any of the channels created and running?"""
728 return (self.shell_channel.is_alive() or self.sub_channel.is_alive() or
733 return (self.shell_channel.is_alive() or self.sub_channel.is_alive() or
729 self.stdin_channel.is_alive() or self.hb_channel.is_alive())
734 self.stdin_channel.is_alive() or self.hb_channel.is_alive())
730
735
731 #--------------------------------------------------------------------------
736 #--------------------------------------------------------------------------
732 # Kernel process management methods:
737 # Kernel process management methods:
733 #--------------------------------------------------------------------------
738 #--------------------------------------------------------------------------
734
739
735 def cleanup_connection_file(self):
740 def cleanup_connection_file(self):
736 """cleanup connection file *if we wrote it*
741 """cleanup connection file *if we wrote it*
737
742
738 Will not raise if the connection file was already removed somehow.
743 Will not raise if the connection file was already removed somehow.
739 """
744 """
740 if self._connection_file_written:
745 if self._connection_file_written:
741 # cleanup connection files on full shutdown of kernel we started
746 # cleanup connection files on full shutdown of kernel we started
742 self._connection_file_written = False
747 self._connection_file_written = False
743 try:
748 try:
744 os.remove(self.connection_file)
749 os.remove(self.connection_file)
745 except OSError:
750 except OSError:
746 pass
751 pass
747
752
748 def load_connection_file(self):
753 def load_connection_file(self):
749 """load connection info from JSON dict in self.connection_file"""
754 """load connection info from JSON dict in self.connection_file"""
750 with open(self.connection_file) as f:
755 with open(self.connection_file) as f:
751 cfg = json.loads(f.read())
756 cfg = json.loads(f.read())
752
757
753 self.ip = cfg['ip']
758 self.ip = cfg['ip']
754 self.shell_port = cfg['shell_port']
759 self.shell_port = cfg['shell_port']
755 self.stdin_port = cfg['stdin_port']
760 self.stdin_port = cfg['stdin_port']
756 self.iopub_port = cfg['iopub_port']
761 self.iopub_port = cfg['iopub_port']
757 self.hb_port = cfg['hb_port']
762 self.hb_port = cfg['hb_port']
758 self.session.key = str_to_bytes(cfg['key'])
763 self.session.key = str_to_bytes(cfg['key'])
759
764
760 def write_connection_file(self):
765 def write_connection_file(self):
761 """write connection info to JSON dict in self.connection_file"""
766 """write connection info to JSON dict in self.connection_file"""
762 if self._connection_file_written:
767 if self._connection_file_written:
763 return
768 return
764 self.connection_file,cfg = write_connection_file(self.connection_file,
769 self.connection_file,cfg = write_connection_file(self.connection_file,
765 ip=self.ip, key=self.session.key,
770 ip=self.ip, key=self.session.key,
766 stdin_port=self.stdin_port, iopub_port=self.iopub_port,
771 stdin_port=self.stdin_port, iopub_port=self.iopub_port,
767 shell_port=self.shell_port, hb_port=self.hb_port)
772 shell_port=self.shell_port, hb_port=self.hb_port)
768 # write_connection_file also sets default ports:
773 # write_connection_file also sets default ports:
769 self.shell_port = cfg['shell_port']
774 self.shell_port = cfg['shell_port']
770 self.stdin_port = cfg['stdin_port']
775 self.stdin_port = cfg['stdin_port']
771 self.iopub_port = cfg['iopub_port']
776 self.iopub_port = cfg['iopub_port']
772 self.hb_port = cfg['hb_port']
777 self.hb_port = cfg['hb_port']
773
778
774 self._connection_file_written = True
779 self._connection_file_written = True
775
780
776 def start_kernel(self, **kw):
781 def start_kernel(self, **kw):
777 """Starts a kernel process and configures the manager to use it.
782 """Starts a kernel process and configures the manager to use it.
778
783
779 If random ports (port=0) are being used, this method must be called
784 If random ports (port=0) are being used, this method must be called
780 before the channels are created.
785 before the channels are created.
781
786
782 Parameters:
787 Parameters:
783 -----------
788 -----------
784 launcher : callable, optional (default None)
789 launcher : callable, optional (default None)
785 A custom function for launching the kernel process (generally a
790 A custom function for launching the kernel process (generally a
786 wrapper around ``entry_point.base_launch_kernel``). In most cases,
791 wrapper around ``entry_point.base_launch_kernel``). In most cases,
787 it should not be necessary to use this parameter.
792 it should not be necessary to use this parameter.
788
793
789 **kw : optional
794 **kw : optional
790 See respective options for IPython and Python kernels.
795 See respective options for IPython and Python kernels.
791 """
796 """
792 if self.ip not in LOCAL_IPS:
797 if self.ip not in LOCAL_IPS:
793 raise RuntimeError("Can only launch a kernel on a local interface. "
798 raise RuntimeError("Can only launch a kernel on a local interface. "
794 "Make sure that the '*_address' attributes are "
799 "Make sure that the '*_address' attributes are "
795 "configured properly. "
800 "configured properly. "
796 "Currently valid addresses are: %s"%LOCAL_IPS
801 "Currently valid addresses are: %s"%LOCAL_IPS
797 )
802 )
798
803
799 # write connection file / get default ports
804 # write connection file / get default ports
800 self.write_connection_file()
805 self.write_connection_file()
801
806
802 self._launch_args = kw.copy()
807 self._launch_args = kw.copy()
803 launch_kernel = kw.pop('launcher', None)
808 launch_kernel = kw.pop('launcher', None)
804 if launch_kernel is None:
809 if launch_kernel is None:
805 from ipkernel import launch_kernel
810 from ipkernel import launch_kernel
806 self.kernel = launch_kernel(fname=self.connection_file, **kw)
811 self.kernel = launch_kernel(fname=self.connection_file, **kw)
807
812
808 def shutdown_kernel(self, restart=False):
813 def shutdown_kernel(self, restart=False):
809 """ Attempts to the stop the kernel process cleanly. If the kernel
814 """ Attempts to the stop the kernel process cleanly. If the kernel
810 cannot be stopped, it is killed, if possible.
815 cannot be stopped, it is killed, if possible.
811 """
816 """
812 # FIXME: Shutdown does not work on Windows due to ZMQ errors!
817 # FIXME: Shutdown does not work on Windows due to ZMQ errors!
813 if sys.platform == 'win32':
818 if sys.platform == 'win32':
814 self.kill_kernel()
819 self.kill_kernel()
815 return
820 return
816
821
817 # Pause the heart beat channel if it exists.
822 # Pause the heart beat channel if it exists.
818 if self._hb_channel is not None:
823 if self._hb_channel is not None:
819 self._hb_channel.pause()
824 self._hb_channel.pause()
820
825
821 # Don't send any additional kernel kill messages immediately, to give
826 # Don't send any additional kernel kill messages immediately, to give
822 # the kernel a chance to properly execute shutdown actions. Wait for at
827 # the kernel a chance to properly execute shutdown actions. Wait for at
823 # most 1s, checking every 0.1s.
828 # most 1s, checking every 0.1s.
824 self.shell_channel.shutdown(restart=restart)
829 self.shell_channel.shutdown(restart=restart)
825 for i in range(10):
830 for i in range(10):
826 if self.is_alive:
831 if self.is_alive:
827 time.sleep(0.1)
832 time.sleep(0.1)
828 else:
833 else:
829 break
834 break
830 else:
835 else:
831 # OK, we've waited long enough.
836 # OK, we've waited long enough.
832 if self.has_kernel:
837 if self.has_kernel:
833 self.kill_kernel()
838 self.kill_kernel()
834
839
835 if not restart and self._connection_file_written:
840 if not restart and self._connection_file_written:
836 # cleanup connection files on full shutdown of kernel we started
841 # cleanup connection files on full shutdown of kernel we started
837 self._connection_file_written = False
842 self._connection_file_written = False
838 try:
843 try:
839 os.remove(self.connection_file)
844 os.remove(self.connection_file)
840 except IOError:
845 except IOError:
841 pass
846 pass
842
847
843 def restart_kernel(self, now=False, **kw):
848 def restart_kernel(self, now=False, **kw):
844 """Restarts a kernel with the arguments that were used to launch it.
849 """Restarts a kernel with the arguments that were used to launch it.
845
850
846 If the old kernel was launched with random ports, the same ports will be
851 If the old kernel was launched with random ports, the same ports will be
847 used for the new kernel.
852 used for the new kernel.
848
853
849 Parameters
854 Parameters
850 ----------
855 ----------
851 now : bool, optional
856 now : bool, optional
852 If True, the kernel is forcefully restarted *immediately*, without
857 If True, the kernel is forcefully restarted *immediately*, without
853 having a chance to do any cleanup action. Otherwise the kernel is
858 having a chance to do any cleanup action. Otherwise the kernel is
854 given 1s to clean up before a forceful restart is issued.
859 given 1s to clean up before a forceful restart is issued.
855
860
856 In all cases the kernel is restarted, the only difference is whether
861 In all cases the kernel is restarted, the only difference is whether
857 it is given a chance to perform a clean shutdown or not.
862 it is given a chance to perform a clean shutdown or not.
858
863
859 **kw : optional
864 **kw : optional
860 Any options specified here will replace those used to launch the
865 Any options specified here will replace those used to launch the
861 kernel.
866 kernel.
862 """
867 """
863 if self._launch_args is None:
868 if self._launch_args is None:
864 raise RuntimeError("Cannot restart the kernel. "
869 raise RuntimeError("Cannot restart the kernel. "
865 "No previous call to 'start_kernel'.")
870 "No previous call to 'start_kernel'.")
866 else:
871 else:
867 # Stop currently running kernel.
872 # Stop currently running kernel.
868 if self.has_kernel:
873 if self.has_kernel:
869 if now:
874 if now:
870 self.kill_kernel()
875 self.kill_kernel()
871 else:
876 else:
872 self.shutdown_kernel(restart=True)
877 self.shutdown_kernel(restart=True)
873
878
874 # Start new kernel.
879 # Start new kernel.
875 self._launch_args.update(kw)
880 self._launch_args.update(kw)
876 self.start_kernel(**self._launch_args)
881 self.start_kernel(**self._launch_args)
877
882
878 # FIXME: Messages get dropped in Windows due to probable ZMQ bug
883 # FIXME: Messages get dropped in Windows due to probable ZMQ bug
879 # unless there is some delay here.
884 # unless there is some delay here.
880 if sys.platform == 'win32':
885 if sys.platform == 'win32':
881 time.sleep(0.2)
886 time.sleep(0.2)
882
887
883 @property
888 @property
884 def has_kernel(self):
889 def has_kernel(self):
885 """Returns whether a kernel process has been specified for the kernel
890 """Returns whether a kernel process has been specified for the kernel
886 manager.
891 manager.
887 """
892 """
888 return self.kernel is not None
893 return self.kernel is not None
889
894
890 def kill_kernel(self):
895 def kill_kernel(self):
891 """ Kill the running kernel. """
896 """ Kill the running kernel. """
892 if self.has_kernel:
897 if self.has_kernel:
893 # Pause the heart beat channel if it exists.
898 # Pause the heart beat channel if it exists.
894 if self._hb_channel is not None:
899 if self._hb_channel is not None:
895 self._hb_channel.pause()
900 self._hb_channel.pause()
896
901
897 # Attempt to kill the kernel.
902 # Attempt to kill the kernel.
898 try:
903 try:
899 self.kernel.kill()
904 self.kernel.kill()
900 except OSError as e:
905 except OSError as e:
901 # In Windows, we will get an Access Denied error if the process
906 # In Windows, we will get an Access Denied error if the process
902 # has already terminated. Ignore it.
907 # has already terminated. Ignore it.
903 if sys.platform == 'win32':
908 if sys.platform == 'win32':
904 if e.winerror != 5:
909 if e.winerror != 5:
905 raise
910 raise
906 # On Unix, we may get an ESRCH error if the process has already
911 # On Unix, we may get an ESRCH error if the process has already
907 # terminated. Ignore it.
912 # terminated. Ignore it.
908 else:
913 else:
909 from errno import ESRCH
914 from errno import ESRCH
910 if e.errno != ESRCH:
915 if e.errno != ESRCH:
911 raise
916 raise
912 self.kernel = None
917 self.kernel = None
913 else:
918 else:
914 raise RuntimeError("Cannot kill kernel. No kernel is running!")
919 raise RuntimeError("Cannot kill kernel. No kernel is running!")
915
920
916 def interrupt_kernel(self):
921 def interrupt_kernel(self):
917 """ Interrupts the kernel. Unlike ``signal_kernel``, this operation is
922 """ Interrupts the kernel. Unlike ``signal_kernel``, this operation is
918 well supported on all platforms.
923 well supported on all platforms.
919 """
924 """
920 if self.has_kernel:
925 if self.has_kernel:
921 if sys.platform == 'win32':
926 if sys.platform == 'win32':
922 from parentpoller import ParentPollerWindows as Poller
927 from parentpoller import ParentPollerWindows as Poller
923 Poller.send_interrupt(self.kernel.win32_interrupt_event)
928 Poller.send_interrupt(self.kernel.win32_interrupt_event)
924 else:
929 else:
925 self.kernel.send_signal(signal.SIGINT)
930 self.kernel.send_signal(signal.SIGINT)
926 else:
931 else:
927 raise RuntimeError("Cannot interrupt kernel. No kernel is running!")
932 raise RuntimeError("Cannot interrupt kernel. No kernel is running!")
928
933
929 def signal_kernel(self, signum):
934 def signal_kernel(self, signum):
930 """ Sends a signal to the kernel. Note that since only SIGTERM is
935 """ Sends a signal to the kernel. Note that since only SIGTERM is
931 supported on Windows, this function is only useful on Unix systems.
936 supported on Windows, this function is only useful on Unix systems.
932 """
937 """
933 if self.has_kernel:
938 if self.has_kernel:
934 self.kernel.send_signal(signum)
939 self.kernel.send_signal(signum)
935 else:
940 else:
936 raise RuntimeError("Cannot signal kernel. No kernel is running!")
941 raise RuntimeError("Cannot signal kernel. No kernel is running!")
937
942
938 @property
943 @property
939 def is_alive(self):
944 def is_alive(self):
940 """Is the kernel process still running?"""
945 """Is the kernel process still running?"""
941 if self.has_kernel:
946 if self.has_kernel:
942 if self.kernel.poll() is None:
947 if self.kernel.poll() is None:
943 return True
948 return True
944 else:
949 else:
945 return False
950 return False
946 elif self._hb_channel is not None:
951 elif self._hb_channel is not None:
947 # We didn't start the kernel with this KernelManager so we
952 # We didn't start the kernel with this KernelManager so we
948 # use the heartbeat.
953 # use the heartbeat.
949 return self._hb_channel.is_beating()
954 return self._hb_channel.is_beating()
950 else:
955 else:
951 # no heartbeat and not local, we can't tell if it's running,
956 # no heartbeat and not local, we can't tell if it's running,
952 # so naively return True
957 # so naively return True
953 return True
958 return True
954
959
955 #--------------------------------------------------------------------------
960 #--------------------------------------------------------------------------
956 # Channels used for communication with the kernel:
961 # Channels used for communication with the kernel:
957 #--------------------------------------------------------------------------
962 #--------------------------------------------------------------------------
958
963
959 @property
964 @property
960 def shell_channel(self):
965 def shell_channel(self):
961 """Get the REQ socket channel object to make requests of the kernel."""
966 """Get the REQ socket channel object to make requests of the kernel."""
962 if self._shell_channel is None:
967 if self._shell_channel is None:
963 self._shell_channel = self.shell_channel_class(self.context,
968 self._shell_channel = self.shell_channel_class(self.context,
964 self.session,
969 self.session,
965 (self.ip, self.shell_port))
970 (self.ip, self.shell_port))
966 return self._shell_channel
971 return self._shell_channel
967
972
968 @property
973 @property
969 def sub_channel(self):
974 def sub_channel(self):
970 """Get the SUB socket channel object."""
975 """Get the SUB socket channel object."""
971 if self._sub_channel is None:
976 if self._sub_channel is None:
972 self._sub_channel = self.sub_channel_class(self.context,
977 self._sub_channel = self.sub_channel_class(self.context,
973 self.session,
978 self.session,
974 (self.ip, self.iopub_port))
979 (self.ip, self.iopub_port))
975 return self._sub_channel
980 return self._sub_channel
976
981
977 @property
982 @property
978 def stdin_channel(self):
983 def stdin_channel(self):
979 """Get the REP socket channel object to handle stdin (raw_input)."""
984 """Get the REP socket channel object to handle stdin (raw_input)."""
980 if self._stdin_channel is None:
985 if self._stdin_channel is None:
981 self._stdin_channel = self.stdin_channel_class(self.context,
986 self._stdin_channel = self.stdin_channel_class(self.context,
982 self.session,
987 self.session,
983 (self.ip, self.stdin_port))
988 (self.ip, self.stdin_port))
984 return self._stdin_channel
989 return self._stdin_channel
985
990
986 @property
991 @property
987 def hb_channel(self):
992 def hb_channel(self):
988 """Get the heartbeat socket channel object to check that the
993 """Get the heartbeat socket channel object to check that the
989 kernel is alive."""
994 kernel is alive."""
990 if self._hb_channel is None:
995 if self._hb_channel is None:
991 self._hb_channel = self.hb_channel_class(self.context,
996 self._hb_channel = self.hb_channel_class(self.context,
992 self.session,
997 self.session,
993 (self.ip, self.hb_port))
998 (self.ip, self.hb_port))
994 return self._hb_channel
999 return self._hb_channel
@@ -1,997 +1,1002 b''
1 .. _messaging:
1 .. _messaging:
2
2
3 ======================
3 ======================
4 Messaging in IPython
4 Messaging in IPython
5 ======================
5 ======================
6
6
7
7
8 Introduction
8 Introduction
9 ============
9 ============
10
10
11 This document explains the basic communications design and messaging
11 This document explains the basic communications design and messaging
12 specification for how the various IPython objects interact over a network
12 specification for how the various IPython objects interact over a network
13 transport. The current implementation uses the ZeroMQ_ library for messaging
13 transport. The current implementation uses the ZeroMQ_ library for messaging
14 within and between hosts.
14 within and between hosts.
15
15
16 .. Note::
16 .. Note::
17
17
18 This document should be considered the authoritative description of the
18 This document should be considered the authoritative description of the
19 IPython messaging protocol, and all developers are strongly encouraged to
19 IPython messaging protocol, and all developers are strongly encouraged to
20 keep it updated as the implementation evolves, so that we have a single
20 keep it updated as the implementation evolves, so that we have a single
21 common reference for all protocol details.
21 common reference for all protocol details.
22
22
23 The basic design is explained in the following diagram:
23 The basic design is explained in the following diagram:
24
24
25 .. image:: figs/frontend-kernel.png
25 .. image:: figs/frontend-kernel.png
26 :width: 450px
26 :width: 450px
27 :alt: IPython kernel/frontend messaging architecture.
27 :alt: IPython kernel/frontend messaging architecture.
28 :align: center
28 :align: center
29 :target: ../_images/frontend-kernel.png
29 :target: ../_images/frontend-kernel.png
30
30
31 A single kernel can be simultaneously connected to one or more frontends. The
31 A single kernel can be simultaneously connected to one or more frontends. The
32 kernel has three sockets that serve the following functions:
32 kernel has three sockets that serve the following functions:
33
33
34 1. stdin: this ROUTER socket is connected to all frontends, and it allows
34 1. stdin: this ROUTER socket is connected to all frontends, and it allows
35 the kernel to request input from the active frontend when :func:`raw_input` is called.
35 the kernel to request input from the active frontend when :func:`raw_input` is called.
36 The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
36 The frontend that executed the code has a DEALER socket that acts as a 'virtual keyboard'
37 for the kernel while this communication is happening (illustrated in the
37 for the kernel while this communication is happening (illustrated in the
38 figure by the black outline around the central keyboard). In practice,
38 figure by the black outline around the central keyboard). In practice,
39 frontends may display such kernel requests using a special input widget or
39 frontends may display such kernel requests using a special input widget or
40 otherwise indicating that the user is to type input for the kernel instead
40 otherwise indicating that the user is to type input for the kernel instead
41 of normal commands in the frontend.
41 of normal commands in the frontend.
42
42
43 2. Shell: this single ROUTER socket allows multiple incoming connections from
43 2. Shell: this single ROUTER socket allows multiple incoming connections from
44 frontends, and this is the socket where requests for code execution, object
44 frontends, and this is the socket where requests for code execution, object
45 information, prompts, etc. are made to the kernel by any frontend. The
45 information, prompts, etc. are made to the kernel by any frontend. The
46 communication on this socket is a sequence of request/reply actions from
46 communication on this socket is a sequence of request/reply actions from
47 each frontend and the kernel.
47 each frontend and the kernel.
48
48
49 3. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
49 3. IOPub: this socket is the 'broadcast channel' where the kernel publishes all
50 side effects (stdout, stderr, etc.) as well as the requests coming from any
50 side effects (stdout, stderr, etc.) as well as the requests coming from any
51 client over the shell socket and its own requests on the stdin socket. There
51 client over the shell socket and its own requests on the stdin socket. There
52 are a number of actions in Python which generate side effects: :func:`print`
52 are a number of actions in Python which generate side effects: :func:`print`
53 writes to ``sys.stdout``, errors generate tracebacks, etc. Additionally, in
53 writes to ``sys.stdout``, errors generate tracebacks, etc. Additionally, in
54 a multi-client scenario, we want all frontends to be able to know what each
54 a multi-client scenario, we want all frontends to be able to know what each
55 other has sent to the kernel (this can be useful in collaborative scenarios,
55 other has sent to the kernel (this can be useful in collaborative scenarios,
56 for example). This socket allows both side effects and the information
56 for example). This socket allows both side effects and the information
57 about communications taking place with one client over the shell channel
57 about communications taking place with one client over the shell channel
58 to be made available to all clients in a uniform manner.
58 to be made available to all clients in a uniform manner.
59
59
60 All messages are tagged with enough information (details below) for clients
60 All messages are tagged with enough information (details below) for clients
61 to know which messages come from their own interaction with the kernel and
61 to know which messages come from their own interaction with the kernel and
62 which ones are from other clients, so they can display each type
62 which ones are from other clients, so they can display each type
63 appropriately.
63 appropriately.
64
64
65 The actual format of the messages allowed on each of these channels is
65 The actual format of the messages allowed on each of these channels is
66 specified below. Messages are dicts of dicts with string keys and values that
66 specified below. Messages are dicts of dicts with string keys and values that
67 are reasonably representable in JSON. Our current implementation uses JSON
67 are reasonably representable in JSON. Our current implementation uses JSON
68 explicitly as its message format, but this shouldn't be considered a permanent
68 explicitly as its message format, but this shouldn't be considered a permanent
69 feature. As we've discovered that JSON has non-trivial performance issues due
69 feature. As we've discovered that JSON has non-trivial performance issues due
70 to excessive copying, we may in the future move to a pure pickle-based raw
70 to excessive copying, we may in the future move to a pure pickle-based raw
71 message format. However, it should be possible to easily convert from the raw
71 message format. However, it should be possible to easily convert from the raw
72 objects to JSON, since we may have non-python clients (e.g. a web frontend).
72 objects to JSON, since we may have non-python clients (e.g. a web frontend).
73 As long as it's easy to make a JSON version of the objects that is a faithful
73 As long as it's easy to make a JSON version of the objects that is a faithful
74 representation of all the data, we can communicate with such clients.
74 representation of all the data, we can communicate with such clients.
75
75
76 .. Note::
76 .. Note::
77
77
78 Not all of these have yet been fully fleshed out, but the key ones are, see
78 Not all of these have yet been fully fleshed out, but the key ones are, see
79 kernel and frontend files for actual implementation details.
79 kernel and frontend files for actual implementation details.
80
80
81 General Message Format
81 General Message Format
82 ======================
82 ======================
83
83
84 A message is defined by the following four-dictionary structure::
84 A message is defined by the following four-dictionary structure::
85
85
86 {
86 {
87 # The message header contains a pair of unique identifiers for the
87 # The message header contains a pair of unique identifiers for the
88 # originating session and the actual message id, in addition to the
88 # originating session and the actual message id, in addition to the
89 # username for the process that generated the message. This is useful in
89 # username for the process that generated the message. This is useful in
90 # collaborative settings where multiple users may be interacting with the
90 # collaborative settings where multiple users may be interacting with the
91 # same kernel simultaneously, so that frontends can label the various
91 # same kernel simultaneously, so that frontends can label the various
92 # messages in a meaningful way.
92 # messages in a meaningful way.
93 'header' : {
93 'header' : {
94 'msg_id' : uuid,
94 'msg_id' : uuid,
95 'username' : str,
95 'username' : str,
96 'session' : uuid
96 'session' : uuid
97 # All recognized message type strings are listed below.
97 # All recognized message type strings are listed below.
98 'msg_type' : str,
98 'msg_type' : str,
99 },
99 },
100
100
101 # In a chain of messages, the header from the parent is copied so that
101 # In a chain of messages, the header from the parent is copied so that
102 # clients can track where messages come from.
102 # clients can track where messages come from.
103 'parent_header' : dict,
103 'parent_header' : dict,
104
104
105 # The actual content of the message must be a dict, whose structure
105 # The actual content of the message must be a dict, whose structure
106 # depends on the message type.
106 # depends on the message type.
107 'content' : dict,
107 'content' : dict,
108
108
109 # Any metadata associated with the message.
109 # Any metadata associated with the message.
110 'metadata' : dict,
110 'metadata' : dict,
111 }
111 }
112
112
113
113
114 Python functional API
114 Python functional API
115 =====================
115 =====================
116
116
117 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
117 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
118 should develop, at a few key points, functional forms of all the requests that
118 should develop, at a few key points, functional forms of all the requests that
119 take arguments in this manner and automatically construct the necessary dict
119 take arguments in this manner and automatically construct the necessary dict
120 for sending.
120 for sending.
121
121
122 In addition, the Python implementation of the message specification extends
122 In addition, the Python implementation of the message specification extends
123 messages upon deserialization to the following form for convenience::
123 messages upon deserialization to the following form for convenience::
124
124
125 {
125 {
126 'header' : dict,
126 'header' : dict,
127 # The msg's unique identifier and type are always stored in the header,
127 # The msg's unique identifier and type are always stored in the header,
128 # but the Python implementation copies them to the top level.
128 # but the Python implementation copies them to the top level.
129 'msg_id' : uuid,
129 'msg_id' : uuid,
130 'msg_type' : str,
130 'msg_type' : str,
131 'parent_header' : dict,
131 'parent_header' : dict,
132 'content' : dict,
132 'content' : dict,
133 'metadata' : dict,
133 'metadata' : dict,
134 }
134 }
135
135
136 All messages sent to or received by any IPython process should have this
136 All messages sent to or received by any IPython process should have this
137 extended structure.
137 extended structure.
138
138
139
139
140 Messages on the shell ROUTER/DEALER sockets
140 Messages on the shell ROUTER/DEALER sockets
141 ===========================================
141 ===========================================
142
142
143 .. _execute:
143 .. _execute:
144
144
145 Execute
145 Execute
146 -------
146 -------
147
147
148 This message type is used by frontends to ask the kernel to execute code on
148 This message type is used by frontends to ask the kernel to execute code on
149 behalf of the user, in a namespace reserved to the user's variables (and thus
149 behalf of the user, in a namespace reserved to the user's variables (and thus
150 separate from the kernel's own internal code and variables).
150 separate from the kernel's own internal code and variables).
151
151
152 Message type: ``execute_request``::
152 Message type: ``execute_request``::
153
153
154 content = {
154 content = {
155 # Source code to be executed by the kernel, one or more lines.
155 # Source code to be executed by the kernel, one or more lines.
156 'code' : str,
156 'code' : str,
157
157
158 # A boolean flag which, if True, signals the kernel to execute
158 # A boolean flag which, if True, signals the kernel to execute
159 # this code as quietly as possible. This means that the kernel
159 # this code as quietly as possible. This means that the kernel
160 # will compile the code with 'exec' instead of 'single' (so
160 # will compile the code with 'exec' instead of 'single' (so
161 # sys.displayhook will not fire), and will *not*:
161 # sys.displayhook will not fire), forces store_history to be False,
162 # and will *not*:
162 # - broadcast exceptions on the PUB socket
163 # - broadcast exceptions on the PUB socket
163 # - do any logging
164 # - do any logging
164 # - populate any history
165 #
165 #
166 # The default is False.
166 # The default is False.
167 'silent' : bool,
167 'silent' : bool,
168
168
169 # A boolean flag which, if True, signals the kernel to populate history
170 # The default is True if silent is False. If silent is True, store_history
171 # is forced to be False.
172 'store_history' : bool,
173
169 # A list of variable names from the user's namespace to be retrieved. What
174 # A list of variable names from the user's namespace to be retrieved. What
170 # returns is a JSON string of the variable's repr(), not a python object.
175 # returns is a JSON string of the variable's repr(), not a python object.
171 'user_variables' : list,
176 'user_variables' : list,
172
177
173 # Similarly, a dict mapping names to expressions to be evaluated in the
178 # Similarly, a dict mapping names to expressions to be evaluated in the
174 # user's dict.
179 # user's dict.
175 'user_expressions' : dict,
180 'user_expressions' : dict,
176
181
177 # Some frontends (e.g. the Notebook) do not support stdin requests. If
182 # Some frontends (e.g. the Notebook) do not support stdin requests. If
178 # raw_input is called from code executed from such a frontend, a
183 # raw_input is called from code executed from such a frontend, a
179 # StdinNotImplementedError will be raised.
184 # StdinNotImplementedError will be raised.
180 'allow_stdin' : True,
185 'allow_stdin' : True,
181
186
182 }
187 }
183
188
184 The ``code`` field contains a single string (possibly multiline). The kernel
189 The ``code`` field contains a single string (possibly multiline). The kernel
185 is responsible for splitting this into one or more independent execution blocks
190 is responsible for splitting this into one or more independent execution blocks
186 and deciding whether to compile these in 'single' or 'exec' mode (see below for
191 and deciding whether to compile these in 'single' or 'exec' mode (see below for
187 detailed execution semantics).
192 detailed execution semantics).
188
193
189 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
194 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
190 the notion of a prompt string that allowed arbitrary code to be evaluated, and
195 the notion of a prompt string that allowed arbitrary code to be evaluated, and
191 this was put to good use by many in creating prompts that displayed system
196 this was put to good use by many in creating prompts that displayed system
192 status, path information, and even more esoteric uses like remote instrument
197 status, path information, and even more esoteric uses like remote instrument
193 status aqcuired over the network. But now that IPython has a clean separation
198 status aqcuired over the network. But now that IPython has a clean separation
194 between the kernel and the clients, the kernel has no prompt knowledge; prompts
199 between the kernel and the clients, the kernel has no prompt knowledge; prompts
195 are a frontend-side feature, and it should be even possible for different
200 are a frontend-side feature, and it should be even possible for different
196 frontends to display different prompts while interacting with the same kernel.
201 frontends to display different prompts while interacting with the same kernel.
197
202
198 The kernel now provides the ability to retrieve data from the user's namespace
203 The kernel now provides the ability to retrieve data from the user's namespace
199 after the execution of the main ``code``, thanks to two fields in the
204 after the execution of the main ``code``, thanks to two fields in the
200 ``execute_request`` message:
205 ``execute_request`` message:
201
206
202 - ``user_variables``: If only variables from the user's namespace are needed, a
207 - ``user_variables``: If only variables from the user's namespace are needed, a
203 list of variable names can be passed and a dict with these names as keys and
208 list of variable names can be passed and a dict with these names as keys and
204 their :func:`repr()` as values will be returned.
209 their :func:`repr()` as values will be returned.
205
210
206 - ``user_expressions``: For more complex expressions that require function
211 - ``user_expressions``: For more complex expressions that require function
207 evaluations, a dict can be provided with string keys and arbitrary python
212 evaluations, a dict can be provided with string keys and arbitrary python
208 expressions as values. The return message will contain also a dict with the
213 expressions as values. The return message will contain also a dict with the
209 same keys and the :func:`repr()` of the evaluated expressions as value.
214 same keys and the :func:`repr()` of the evaluated expressions as value.
210
215
211 With this information, frontends can display any status information they wish
216 With this information, frontends can display any status information they wish
212 in the form that best suits each frontend (a status line, a popup, inline for a
217 in the form that best suits each frontend (a status line, a popup, inline for a
213 terminal, etc).
218 terminal, etc).
214
219
215 .. Note::
220 .. Note::
216
221
217 In order to obtain the current execution counter for the purposes of
222 In order to obtain the current execution counter for the purposes of
218 displaying input prompts, frontends simply make an execution request with an
223 displaying input prompts, frontends simply make an execution request with an
219 empty code string and ``silent=True``.
224 empty code string and ``silent=True``.
220
225
221 Execution semantics
226 Execution semantics
222 ~~~~~~~~~~~~~~~~~~~
227 ~~~~~~~~~~~~~~~~~~~
223
228
224 When the silent flag is false, the execution of use code consists of the
229 When the silent flag is false, the execution of use code consists of the
225 following phases (in silent mode, only the ``code`` field is executed):
230 following phases (in silent mode, only the ``code`` field is executed):
226
231
227 1. Run the ``pre_runcode_hook``.
232 1. Run the ``pre_runcode_hook``.
228
233
229 2. Execute the ``code`` field, see below for details.
234 2. Execute the ``code`` field, see below for details.
230
235
231 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
236 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
232 computed. This ensures that any error in the latter don't harm the main
237 computed. This ensures that any error in the latter don't harm the main
233 code execution.
238 code execution.
234
239
235 4. Call any method registered with :meth:`register_post_execute`.
240 4. Call any method registered with :meth:`register_post_execute`.
236
241
237 .. warning::
242 .. warning::
238
243
239 The API for running code before/after the main code block is likely to
244 The API for running code before/after the main code block is likely to
240 change soon. Both the ``pre_runcode_hook`` and the
245 change soon. Both the ``pre_runcode_hook`` and the
241 :meth:`register_post_execute` are susceptible to modification, as we find a
246 :meth:`register_post_execute` are susceptible to modification, as we find a
242 consistent model for both.
247 consistent model for both.
243
248
244 To understand how the ``code`` field is executed, one must know that Python
249 To understand how the ``code`` field is executed, one must know that Python
245 code can be compiled in one of three modes (controlled by the ``mode`` argument
250 code can be compiled in one of three modes (controlled by the ``mode`` argument
246 to the :func:`compile` builtin):
251 to the :func:`compile` builtin):
247
252
248 *single*
253 *single*
249 Valid for a single interactive statement (though the source can contain
254 Valid for a single interactive statement (though the source can contain
250 multiple lines, such as a for loop). When compiled in this mode, the
255 multiple lines, such as a for loop). When compiled in this mode, the
251 generated bytecode contains special instructions that trigger the calling of
256 generated bytecode contains special instructions that trigger the calling of
252 :func:`sys.displayhook` for any expression in the block that returns a value.
257 :func:`sys.displayhook` for any expression in the block that returns a value.
253 This means that a single statement can actually produce multiple calls to
258 This means that a single statement can actually produce multiple calls to
254 :func:`sys.displayhook`, if for example it contains a loop where each
259 :func:`sys.displayhook`, if for example it contains a loop where each
255 iteration computes an unassigned expression would generate 10 calls::
260 iteration computes an unassigned expression would generate 10 calls::
256
261
257 for i in range(10):
262 for i in range(10):
258 i**2
263 i**2
259
264
260 *exec*
265 *exec*
261 An arbitrary amount of source code, this is how modules are compiled.
266 An arbitrary amount of source code, this is how modules are compiled.
262 :func:`sys.displayhook` is *never* implicitly called.
267 :func:`sys.displayhook` is *never* implicitly called.
263
268
264 *eval*
269 *eval*
265 A single expression that returns a value. :func:`sys.displayhook` is *never*
270 A single expression that returns a value. :func:`sys.displayhook` is *never*
266 implicitly called.
271 implicitly called.
267
272
268
273
269 The ``code`` field is split into individual blocks each of which is valid for
274 The ``code`` field is split into individual blocks each of which is valid for
270 execution in 'single' mode, and then:
275 execution in 'single' mode, and then:
271
276
272 - If there is only a single block: it is executed in 'single' mode.
277 - If there is only a single block: it is executed in 'single' mode.
273
278
274 - If there is more than one block:
279 - If there is more than one block:
275
280
276 * if the last one is a single line long, run all but the last in 'exec' mode
281 * if the last one is a single line long, run all but the last in 'exec' mode
277 and the very last one in 'single' mode. This makes it easy to type simple
282 and the very last one in 'single' mode. This makes it easy to type simple
278 expressions at the end to see computed values.
283 expressions at the end to see computed values.
279
284
280 * if the last one is no more than two lines long, run all but the last in
285 * if the last one is no more than two lines long, run all but the last in
281 'exec' mode and the very last one in 'single' mode. This makes it easy to
286 'exec' mode and the very last one in 'single' mode. This makes it easy to
282 type simple expressions at the end to see computed values. - otherwise
287 type simple expressions at the end to see computed values. - otherwise
283 (last one is also multiline), run all in 'exec' mode
288 (last one is also multiline), run all in 'exec' mode
284
289
285 * otherwise (last one is also multiline), run all in 'exec' mode as a single
290 * otherwise (last one is also multiline), run all in 'exec' mode as a single
286 unit.
291 unit.
287
292
288 Any error in retrieving the ``user_variables`` or evaluating the
293 Any error in retrieving the ``user_variables`` or evaluating the
289 ``user_expressions`` will result in a simple error message in the return fields
294 ``user_expressions`` will result in a simple error message in the return fields
290 of the form::
295 of the form::
291
296
292 [ERROR] ExceptionType: Exception message
297 [ERROR] ExceptionType: Exception message
293
298
294 The user can simply send the same variable name or expression for evaluation to
299 The user can simply send the same variable name or expression for evaluation to
295 see a regular traceback.
300 see a regular traceback.
296
301
297 Errors in any registered post_execute functions are also reported similarly,
302 Errors in any registered post_execute functions are also reported similarly,
298 and the failing function is removed from the post_execution set so that it does
303 and the failing function is removed from the post_execution set so that it does
299 not continue triggering failures.
304 not continue triggering failures.
300
305
301 Upon completion of the execution request, the kernel *always* sends a reply,
306 Upon completion of the execution request, the kernel *always* sends a reply,
302 with a status code indicating what happened and additional data depending on
307 with a status code indicating what happened and additional data depending on
303 the outcome. See :ref:`below <execution_results>` for the possible return
308 the outcome. See :ref:`below <execution_results>` for the possible return
304 codes and associated data.
309 codes and associated data.
305
310
306
311
307 Execution counter (old prompt number)
312 Execution counter (old prompt number)
308 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
309
314
310 The kernel has a single, monotonically increasing counter of all execution
315 The kernel has a single, monotonically increasing counter of all execution
311 requests that are made with ``silent=False``. This counter is used to populate
316 requests that are made with ``store_history=True``. This counter is used to populate
312 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
317 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
313 display it in some form to the user, which will typically (but not necessarily)
318 display it in some form to the user, which will typically (but not necessarily)
314 be done in the prompts. The value of this counter will be returned as the
319 be done in the prompts. The value of this counter will be returned as the
315 ``execution_count`` field of all ``execute_reply`` messages.
320 ``execution_count`` field of all ``execute_reply`` messages.
316
321
317 .. _execution_results:
322 .. _execution_results:
318
323
319 Execution results
324 Execution results
320 ~~~~~~~~~~~~~~~~~
325 ~~~~~~~~~~~~~~~~~
321
326
322 Message type: ``execute_reply``::
327 Message type: ``execute_reply``::
323
328
324 content = {
329 content = {
325 # One of: 'ok' OR 'error' OR 'abort'
330 # One of: 'ok' OR 'error' OR 'abort'
326 'status' : str,
331 'status' : str,
327
332
328 # The global kernel counter that increases by one with each non-silent
333 # The global kernel counter that increases by one with each request that
329 # executed request. This will typically be used by clients to display
334 # stores history. This will typically be used by clients to display
330 # prompt numbers to the user. If the request was a silent one, this will
335 # prompt numbers to the user. If the request did not store history, this will
331 # be the current value of the counter in the kernel.
336 # be the current value of the counter in the kernel.
332 'execution_count' : int,
337 'execution_count' : int,
333 }
338 }
334
339
335 When status is 'ok', the following extra fields are present::
340 When status is 'ok', the following extra fields are present::
336
341
337 {
342 {
338 # 'payload' will be a list of payload dicts.
343 # 'payload' will be a list of payload dicts.
339 # Each execution payload is a dict with string keys that may have been
344 # Each execution payload is a dict with string keys that may have been
340 # produced by the code being executed. It is retrieved by the kernel at
345 # produced by the code being executed. It is retrieved by the kernel at
341 # the end of the execution and sent back to the front end, which can take
346 # the end of the execution and sent back to the front end, which can take
342 # action on it as needed. See main text for further details.
347 # action on it as needed. See main text for further details.
343 'payload' : list(dict),
348 'payload' : list(dict),
344
349
345 # Results for the user_variables and user_expressions.
350 # Results for the user_variables and user_expressions.
346 'user_variables' : dict,
351 'user_variables' : dict,
347 'user_expressions' : dict,
352 'user_expressions' : dict,
348 }
353 }
349
354
350 .. admonition:: Execution payloads
355 .. admonition:: Execution payloads
351
356
352 The notion of an 'execution payload' is different from a return value of a
357 The notion of an 'execution payload' is different from a return value of a
353 given set of code, which normally is just displayed on the pyout stream
358 given set of code, which normally is just displayed on the pyout stream
354 through the PUB socket. The idea of a payload is to allow special types of
359 through the PUB socket. The idea of a payload is to allow special types of
355 code, typically magics, to populate a data container in the IPython kernel
360 code, typically magics, to populate a data container in the IPython kernel
356 that will be shipped back to the caller via this channel. The kernel
361 that will be shipped back to the caller via this channel. The kernel
357 has an API for this in the PayloadManager::
362 has an API for this in the PayloadManager::
358
363
359 ip.payload_manager.write_payload(payload_dict)
364 ip.payload_manager.write_payload(payload_dict)
360
365
361 which appends a dictionary to the list of payloads.
366 which appends a dictionary to the list of payloads.
362
367
363
368
364 When status is 'error', the following extra fields are present::
369 When status is 'error', the following extra fields are present::
365
370
366 {
371 {
367 'ename' : str, # Exception name, as a string
372 'ename' : str, # Exception name, as a string
368 'evalue' : str, # Exception value, as a string
373 'evalue' : str, # Exception value, as a string
369
374
370 # The traceback will contain a list of frames, represented each as a
375 # The traceback will contain a list of frames, represented each as a
371 # string. For now we'll stick to the existing design of ultraTB, which
376 # string. For now we'll stick to the existing design of ultraTB, which
372 # controls exception level of detail statefully. But eventually we'll
377 # controls exception level of detail statefully. But eventually we'll
373 # want to grow into a model where more information is collected and
378 # want to grow into a model where more information is collected and
374 # packed into the traceback object, with clients deciding how little or
379 # packed into the traceback object, with clients deciding how little or
375 # how much of it to unpack. But for now, let's start with a simple list
380 # how much of it to unpack. But for now, let's start with a simple list
376 # of strings, since that requires only minimal changes to ultratb as
381 # of strings, since that requires only minimal changes to ultratb as
377 # written.
382 # written.
378 'traceback' : list,
383 'traceback' : list,
379 }
384 }
380
385
381
386
382 When status is 'abort', there are for now no additional data fields. This
387 When status is 'abort', there are for now no additional data fields. This
383 happens when the kernel was interrupted by a signal.
388 happens when the kernel was interrupted by a signal.
384
389
385 Kernel attribute access
390 Kernel attribute access
386 -----------------------
391 -----------------------
387
392
388 .. warning::
393 .. warning::
389
394
390 This part of the messaging spec is not actually implemented in the kernel
395 This part of the messaging spec is not actually implemented in the kernel
391 yet.
396 yet.
392
397
393 While this protocol does not specify full RPC access to arbitrary methods of
398 While this protocol does not specify full RPC access to arbitrary methods of
394 the kernel object, the kernel does allow read (and in some cases write) access
399 the kernel object, the kernel does allow read (and in some cases write) access
395 to certain attributes.
400 to certain attributes.
396
401
397 The policy for which attributes can be read is: any attribute of the kernel, or
402 The policy for which attributes can be read is: any attribute of the kernel, or
398 its sub-objects, that belongs to a :class:`Configurable` object and has been
403 its sub-objects, that belongs to a :class:`Configurable` object and has been
399 declared at the class-level with Traits validation, is in principle accessible
404 declared at the class-level with Traits validation, is in principle accessible
400 as long as its name does not begin with a leading underscore. The attribute
405 as long as its name does not begin with a leading underscore. The attribute
401 itself will have metadata indicating whether it allows remote read and/or write
406 itself will have metadata indicating whether it allows remote read and/or write
402 access. The message spec follows for attribute read and write requests.
407 access. The message spec follows for attribute read and write requests.
403
408
404 Message type: ``getattr_request``::
409 Message type: ``getattr_request``::
405
410
406 content = {
411 content = {
407 # The (possibly dotted) name of the attribute
412 # The (possibly dotted) name of the attribute
408 'name' : str,
413 'name' : str,
409 }
414 }
410
415
411 When a ``getattr_request`` fails, there are two possible error types:
416 When a ``getattr_request`` fails, there are two possible error types:
412
417
413 - AttributeError: this type of error was raised when trying to access the
418 - AttributeError: this type of error was raised when trying to access the
414 given name by the kernel itself. This means that the attribute likely
419 given name by the kernel itself. This means that the attribute likely
415 doesn't exist.
420 doesn't exist.
416
421
417 - AccessError: the attribute exists but its value is not readable remotely.
422 - AccessError: the attribute exists but its value is not readable remotely.
418
423
419
424
420 Message type: ``getattr_reply``::
425 Message type: ``getattr_reply``::
421
426
422 content = {
427 content = {
423 # One of ['ok', 'AttributeError', 'AccessError'].
428 # One of ['ok', 'AttributeError', 'AccessError'].
424 'status' : str,
429 'status' : str,
425 # If status is 'ok', a JSON object.
430 # If status is 'ok', a JSON object.
426 'value' : object,
431 'value' : object,
427 }
432 }
428
433
429 Message type: ``setattr_request``::
434 Message type: ``setattr_request``::
430
435
431 content = {
436 content = {
432 # The (possibly dotted) name of the attribute
437 # The (possibly dotted) name of the attribute
433 'name' : str,
438 'name' : str,
434
439
435 # A JSON-encoded object, that will be validated by the Traits
440 # A JSON-encoded object, that will be validated by the Traits
436 # information in the kernel
441 # information in the kernel
437 'value' : object,
442 'value' : object,
438 }
443 }
439
444
440 When a ``setattr_request`` fails, there are also two possible error types with
445 When a ``setattr_request`` fails, there are also two possible error types with
441 similar meanings as those of the ``getattr_request`` case, but for writing.
446 similar meanings as those of the ``getattr_request`` case, but for writing.
442
447
443 Message type: ``setattr_reply``::
448 Message type: ``setattr_reply``::
444
449
445 content = {
450 content = {
446 # One of ['ok', 'AttributeError', 'AccessError'].
451 # One of ['ok', 'AttributeError', 'AccessError'].
447 'status' : str,
452 'status' : str,
448 }
453 }
449
454
450
455
451
456
452 Object information
457 Object information
453 ------------------
458 ------------------
454
459
455 One of IPython's most used capabilities is the introspection of Python objects
460 One of IPython's most used capabilities is the introspection of Python objects
456 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
461 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
457 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
462 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
458 enough that it warrants an explicit message type, especially because frontends
463 enough that it warrants an explicit message type, especially because frontends
459 may want to get object information in response to user keystrokes (like Tab or
464 may want to get object information in response to user keystrokes (like Tab or
460 F1) besides from the user explicitly typing code like ``x??``.
465 F1) besides from the user explicitly typing code like ``x??``.
461
466
462 Message type: ``object_info_request``::
467 Message type: ``object_info_request``::
463
468
464 content = {
469 content = {
465 # The (possibly dotted) name of the object to be searched in all
470 # The (possibly dotted) name of the object to be searched in all
466 # relevant namespaces
471 # relevant namespaces
467 'name' : str,
472 'name' : str,
468
473
469 # The level of detail desired. The default (0) is equivalent to typing
474 # The level of detail desired. The default (0) is equivalent to typing
470 # 'x?' at the prompt, 1 is equivalent to 'x??'.
475 # 'x?' at the prompt, 1 is equivalent to 'x??'.
471 'detail_level' : int,
476 'detail_level' : int,
472 }
477 }
473
478
474 The returned information will be a dictionary with keys very similar to the
479 The returned information will be a dictionary with keys very similar to the
475 field names that IPython prints at the terminal.
480 field names that IPython prints at the terminal.
476
481
477 Message type: ``object_info_reply``::
482 Message type: ``object_info_reply``::
478
483
479 content = {
484 content = {
480 # The name the object was requested under
485 # The name the object was requested under
481 'name' : str,
486 'name' : str,
482
487
483 # Boolean flag indicating whether the named object was found or not. If
488 # Boolean flag indicating whether the named object was found or not. If
484 # it's false, all other fields will be empty.
489 # it's false, all other fields will be empty.
485 'found' : bool,
490 'found' : bool,
486
491
487 # Flags for magics and system aliases
492 # Flags for magics and system aliases
488 'ismagic' : bool,
493 'ismagic' : bool,
489 'isalias' : bool,
494 'isalias' : bool,
490
495
491 # The name of the namespace where the object was found ('builtin',
496 # The name of the namespace where the object was found ('builtin',
492 # 'magics', 'alias', 'interactive', etc.)
497 # 'magics', 'alias', 'interactive', etc.)
493 'namespace' : str,
498 'namespace' : str,
494
499
495 # The type name will be type.__name__ for normal Python objects, but it
500 # The type name will be type.__name__ for normal Python objects, but it
496 # can also be a string like 'Magic function' or 'System alias'
501 # can also be a string like 'Magic function' or 'System alias'
497 'type_name' : str,
502 'type_name' : str,
498
503
499 # The string form of the object, possibly truncated for length if
504 # The string form of the object, possibly truncated for length if
500 # detail_level is 0
505 # detail_level is 0
501 'string_form' : str,
506 'string_form' : str,
502
507
503 # For objects with a __class__ attribute this will be set
508 # For objects with a __class__ attribute this will be set
504 'base_class' : str,
509 'base_class' : str,
505
510
506 # For objects with a __len__ attribute this will be set
511 # For objects with a __len__ attribute this will be set
507 'length' : int,
512 'length' : int,
508
513
509 # If the object is a function, class or method whose file we can find,
514 # If the object is a function, class or method whose file we can find,
510 # we give its full path
515 # we give its full path
511 'file' : str,
516 'file' : str,
512
517
513 # For pure Python callable objects, we can reconstruct the object
518 # For pure Python callable objects, we can reconstruct the object
514 # definition line which provides its call signature. For convenience this
519 # definition line which provides its call signature. For convenience this
515 # is returned as a single 'definition' field, but below the raw parts that
520 # is returned as a single 'definition' field, but below the raw parts that
516 # compose it are also returned as the argspec field.
521 # compose it are also returned as the argspec field.
517 'definition' : str,
522 'definition' : str,
518
523
519 # The individual parts that together form the definition string. Clients
524 # The individual parts that together form the definition string. Clients
520 # with rich display capabilities may use this to provide a richer and more
525 # with rich display capabilities may use this to provide a richer and more
521 # precise representation of the definition line (e.g. by highlighting
526 # precise representation of the definition line (e.g. by highlighting
522 # arguments based on the user's cursor position). For non-callable
527 # arguments based on the user's cursor position). For non-callable
523 # objects, this field is empty.
528 # objects, this field is empty.
524 'argspec' : { # The names of all the arguments
529 'argspec' : { # The names of all the arguments
525 args : list,
530 args : list,
526 # The name of the varargs (*args), if any
531 # The name of the varargs (*args), if any
527 varargs : str,
532 varargs : str,
528 # The name of the varkw (**kw), if any
533 # The name of the varkw (**kw), if any
529 varkw : str,
534 varkw : str,
530 # The values (as strings) of all default arguments. Note
535 # The values (as strings) of all default arguments. Note
531 # that these must be matched *in reverse* with the 'args'
536 # that these must be matched *in reverse* with the 'args'
532 # list above, since the first positional args have no default
537 # list above, since the first positional args have no default
533 # value at all.
538 # value at all.
534 defaults : list,
539 defaults : list,
535 },
540 },
536
541
537 # For instances, provide the constructor signature (the definition of
542 # For instances, provide the constructor signature (the definition of
538 # the __init__ method):
543 # the __init__ method):
539 'init_definition' : str,
544 'init_definition' : str,
540
545
541 # Docstrings: for any object (function, method, module, package) with a
546 # Docstrings: for any object (function, method, module, package) with a
542 # docstring, we show it. But in addition, we may provide additional
547 # docstring, we show it. But in addition, we may provide additional
543 # docstrings. For example, for instances we will show the constructor
548 # docstrings. For example, for instances we will show the constructor
544 # and class docstrings as well, if available.
549 # and class docstrings as well, if available.
545 'docstring' : str,
550 'docstring' : str,
546
551
547 # For instances, provide the constructor and class docstrings
552 # For instances, provide the constructor and class docstrings
548 'init_docstring' : str,
553 'init_docstring' : str,
549 'class_docstring' : str,
554 'class_docstring' : str,
550
555
551 # If it's a callable object whose call method has a separate docstring and
556 # If it's a callable object whose call method has a separate docstring and
552 # definition line:
557 # definition line:
553 'call_def' : str,
558 'call_def' : str,
554 'call_docstring' : str,
559 'call_docstring' : str,
555
560
556 # If detail_level was 1, we also try to find the source code that
561 # If detail_level was 1, we also try to find the source code that
557 # defines the object, if possible. The string 'None' will indicate
562 # defines the object, if possible. The string 'None' will indicate
558 # that no source was found.
563 # that no source was found.
559 'source' : str,
564 'source' : str,
560 }
565 }
561
566
562
567
563 Complete
568 Complete
564 --------
569 --------
565
570
566 Message type: ``complete_request``::
571 Message type: ``complete_request``::
567
572
568 content = {
573 content = {
569 # The text to be completed, such as 'a.is'
574 # The text to be completed, such as 'a.is'
570 'text' : str,
575 'text' : str,
571
576
572 # The full line, such as 'print a.is'. This allows completers to
577 # The full line, such as 'print a.is'. This allows completers to
573 # make decisions that may require information about more than just the
578 # make decisions that may require information about more than just the
574 # current word.
579 # current word.
575 'line' : str,
580 'line' : str,
576
581
577 # The entire block of text where the line is. This may be useful in the
582 # The entire block of text where the line is. This may be useful in the
578 # case of multiline completions where more context may be needed. Note: if
583 # case of multiline completions where more context may be needed. Note: if
579 # in practice this field proves unnecessary, remove it to lighten the
584 # in practice this field proves unnecessary, remove it to lighten the
580 # messages.
585 # messages.
581
586
582 'block' : str,
587 'block' : str,
583
588
584 # The position of the cursor where the user hit 'TAB' on the line.
589 # The position of the cursor where the user hit 'TAB' on the line.
585 'cursor_pos' : int,
590 'cursor_pos' : int,
586 }
591 }
587
592
588 Message type: ``complete_reply``::
593 Message type: ``complete_reply``::
589
594
590 content = {
595 content = {
591 # The list of all matches to the completion request, such as
596 # The list of all matches to the completion request, such as
592 # ['a.isalnum', 'a.isalpha'] for the above example.
597 # ['a.isalnum', 'a.isalpha'] for the above example.
593 'matches' : list
598 'matches' : list
594 }
599 }
595
600
596
601
597 History
602 History
598 -------
603 -------
599
604
600 For clients to explicitly request history from a kernel. The kernel has all
605 For clients to explicitly request history from a kernel. The kernel has all
601 the actual execution history stored in a single location, so clients can
606 the actual execution history stored in a single location, so clients can
602 request it from the kernel when needed.
607 request it from the kernel when needed.
603
608
604 Message type: ``history_request``::
609 Message type: ``history_request``::
605
610
606 content = {
611 content = {
607
612
608 # If True, also return output history in the resulting dict.
613 # If True, also return output history in the resulting dict.
609 'output' : bool,
614 'output' : bool,
610
615
611 # If True, return the raw input history, else the transformed input.
616 # If True, return the raw input history, else the transformed input.
612 'raw' : bool,
617 'raw' : bool,
613
618
614 # So far, this can be 'range', 'tail' or 'search'.
619 # So far, this can be 'range', 'tail' or 'search'.
615 'hist_access_type' : str,
620 'hist_access_type' : str,
616
621
617 # If hist_access_type is 'range', get a range of input cells. session can
622 # If hist_access_type is 'range', get a range of input cells. session can
618 # be a positive session number, or a negative number to count back from
623 # be a positive session number, or a negative number to count back from
619 # the current session.
624 # the current session.
620 'session' : int,
625 'session' : int,
621 # start and stop are line numbers within that session.
626 # start and stop are line numbers within that session.
622 'start' : int,
627 'start' : int,
623 'stop' : int,
628 'stop' : int,
624
629
625 # If hist_access_type is 'tail', get the last n cells.
630 # If hist_access_type is 'tail', get the last n cells.
626 'n' : int,
631 'n' : int,
627
632
628 # If hist_access_type is 'search', get cells matching the specified glob
633 # If hist_access_type is 'search', get cells matching the specified glob
629 # pattern (with * and ? as wildcards).
634 # pattern (with * and ? as wildcards).
630 'pattern' : str,
635 'pattern' : str,
631
636
632 }
637 }
633
638
634 Message type: ``history_reply``::
639 Message type: ``history_reply``::
635
640
636 content = {
641 content = {
637 # A list of 3 tuples, either:
642 # A list of 3 tuples, either:
638 # (session, line_number, input) or
643 # (session, line_number, input) or
639 # (session, line_number, (input, output)),
644 # (session, line_number, (input, output)),
640 # depending on whether output was False or True, respectively.
645 # depending on whether output was False or True, respectively.
641 'history' : list,
646 'history' : list,
642 }
647 }
643
648
644
649
645 Connect
650 Connect
646 -------
651 -------
647
652
648 When a client connects to the request/reply socket of the kernel, it can issue
653 When a client connects to the request/reply socket of the kernel, it can issue
649 a connect request to get basic information about the kernel, such as the ports
654 a connect request to get basic information about the kernel, such as the ports
650 the other ZeroMQ sockets are listening on. This allows clients to only have
655 the other ZeroMQ sockets are listening on. This allows clients to only have
651 to know about a single port (the shell channel) to connect to a kernel.
656 to know about a single port (the shell channel) to connect to a kernel.
652
657
653 Message type: ``connect_request``::
658 Message type: ``connect_request``::
654
659
655 content = {
660 content = {
656 }
661 }
657
662
658 Message type: ``connect_reply``::
663 Message type: ``connect_reply``::
659
664
660 content = {
665 content = {
661 'shell_port' : int # The port the shell ROUTER socket is listening on.
666 'shell_port' : int # The port the shell ROUTER socket is listening on.
662 'iopub_port' : int # The port the PUB socket is listening on.
667 'iopub_port' : int # The port the PUB socket is listening on.
663 'stdin_port' : int # The port the stdin ROUTER socket is listening on.
668 'stdin_port' : int # The port the stdin ROUTER socket is listening on.
664 'hb_port' : int # The port the heartbeat socket is listening on.
669 'hb_port' : int # The port the heartbeat socket is listening on.
665 }
670 }
666
671
667
672
668
673
669 Kernel shutdown
674 Kernel shutdown
670 ---------------
675 ---------------
671
676
672 The clients can request the kernel to shut itself down; this is used in
677 The clients can request the kernel to shut itself down; this is used in
673 multiple cases:
678 multiple cases:
674
679
675 - when the user chooses to close the client application via a menu or window
680 - when the user chooses to close the client application via a menu or window
676 control.
681 control.
677 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
682 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
678 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
683 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
679 IPythonQt client) to force a kernel restart to get a clean kernel without
684 IPythonQt client) to force a kernel restart to get a clean kernel without
680 losing client-side state like history or inlined figures.
685 losing client-side state like history or inlined figures.
681
686
682 The client sends a shutdown request to the kernel, and once it receives the
687 The client sends a shutdown request to the kernel, and once it receives the
683 reply message (which is otherwise empty), it can assume that the kernel has
688 reply message (which is otherwise empty), it can assume that the kernel has
684 completed shutdown safely.
689 completed shutdown safely.
685
690
686 Upon their own shutdown, client applications will typically execute a last
691 Upon their own shutdown, client applications will typically execute a last
687 minute sanity check and forcefully terminate any kernel that is still alive, to
692 minute sanity check and forcefully terminate any kernel that is still alive, to
688 avoid leaving stray processes in the user's machine.
693 avoid leaving stray processes in the user's machine.
689
694
690 For both shutdown request and reply, there is no actual content that needs to
695 For both shutdown request and reply, there is no actual content that needs to
691 be sent, so the content dict is empty.
696 be sent, so the content dict is empty.
692
697
693 Message type: ``shutdown_request``::
698 Message type: ``shutdown_request``::
694
699
695 content = {
700 content = {
696 'restart' : bool # whether the shutdown is final, or precedes a restart
701 'restart' : bool # whether the shutdown is final, or precedes a restart
697 }
702 }
698
703
699 Message type: ``shutdown_reply``::
704 Message type: ``shutdown_reply``::
700
705
701 content = {
706 content = {
702 'restart' : bool # whether the shutdown is final, or precedes a restart
707 'restart' : bool # whether the shutdown is final, or precedes a restart
703 }
708 }
704
709
705 .. Note::
710 .. Note::
706
711
707 When the clients detect a dead kernel thanks to inactivity on the heartbeat
712 When the clients detect a dead kernel thanks to inactivity on the heartbeat
708 socket, they simply send a forceful process termination signal, since a dead
713 socket, they simply send a forceful process termination signal, since a dead
709 process is unlikely to respond in any useful way to messages.
714 process is unlikely to respond in any useful way to messages.
710
715
711
716
712 Messages on the PUB/SUB socket
717 Messages on the PUB/SUB socket
713 ==============================
718 ==============================
714
719
715 Streams (stdout, stderr, etc)
720 Streams (stdout, stderr, etc)
716 ------------------------------
721 ------------------------------
717
722
718 Message type: ``stream``::
723 Message type: ``stream``::
719
724
720 content = {
725 content = {
721 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
726 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
722 'name' : str,
727 'name' : str,
723
728
724 # The data is an arbitrary string to be written to that stream
729 # The data is an arbitrary string to be written to that stream
725 'data' : str,
730 'data' : str,
726 }
731 }
727
732
728 When a kernel receives a raw_input call, it should also broadcast it on the pub
733 When a kernel receives a raw_input call, it should also broadcast it on the pub
729 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
734 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
730 to monitor/display kernel interactions and possibly replay them to their user
735 to monitor/display kernel interactions and possibly replay them to their user
731 or otherwise expose them.
736 or otherwise expose them.
732
737
733 Display Data
738 Display Data
734 ------------
739 ------------
735
740
736 This type of message is used to bring back data that should be diplayed (text,
741 This type of message is used to bring back data that should be diplayed (text,
737 html, svg, etc.) in the frontends. This data is published to all frontends.
742 html, svg, etc.) in the frontends. This data is published to all frontends.
738 Each message can have multiple representations of the data; it is up to the
743 Each message can have multiple representations of the data; it is up to the
739 frontend to decide which to use and how. A single message should contain all
744 frontend to decide which to use and how. A single message should contain all
740 possible representations of the same information. Each representation should
745 possible representations of the same information. Each representation should
741 be a JSON'able data structure, and should be a valid MIME type.
746 be a JSON'able data structure, and should be a valid MIME type.
742
747
743 Some questions remain about this design:
748 Some questions remain about this design:
744
749
745 * Do we use this message type for pyout/displayhook? Probably not, because
750 * Do we use this message type for pyout/displayhook? Probably not, because
746 the displayhook also has to handle the Out prompt display. On the other hand
751 the displayhook also has to handle the Out prompt display. On the other hand
747 we could put that information into the metadata secion.
752 we could put that information into the metadata secion.
748
753
749 Message type: ``display_data``::
754 Message type: ``display_data``::
750
755
751 content = {
756 content = {
752
757
753 # Who create the data
758 # Who create the data
754 'source' : str,
759 'source' : str,
755
760
756 # The data dict contains key/value pairs, where the kids are MIME
761 # The data dict contains key/value pairs, where the kids are MIME
757 # types and the values are the raw data of the representation in that
762 # types and the values are the raw data of the representation in that
758 # format. The data dict must minimally contain the ``text/plain``
763 # format. The data dict must minimally contain the ``text/plain``
759 # MIME type which is used as a backup representation.
764 # MIME type which is used as a backup representation.
760 'data' : dict,
765 'data' : dict,
761
766
762 # Any metadata that describes the data
767 # Any metadata that describes the data
763 'metadata' : dict
768 'metadata' : dict
764 }
769 }
765
770
766
771
767 Raw Data Publication
772 Raw Data Publication
768 --------------------
773 --------------------
769
774
770 ``display_data`` lets you publish *representations* of data, such as images and html.
775 ``display_data`` lets you publish *representations* of data, such as images and html.
771 This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers.
776 This ``data_pub`` message lets you publish *actual raw data*, sent via message buffers.
772
777
773 data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function:
778 data_pub messages are constructed via the :func:`IPython.lib.datapub.publish_data` function:
774
779
775 .. sourcecode:: python
780 .. sourcecode:: python
776
781
777 from IPython.zmq.datapub import publish_data
782 from IPython.zmq.datapub import publish_data
778 ns = dict(x=my_array)
783 ns = dict(x=my_array)
779 publish_data(ns)
784 publish_data(ns)
780
785
781
786
782 Message type: ``data_pub``::
787 Message type: ``data_pub``::
783
788
784 content = {
789 content = {
785 # the keys of the data dict, after it has been unserialized
790 # the keys of the data dict, after it has been unserialized
786 keys = ['a', 'b']
791 keys = ['a', 'b']
787 }
792 }
788 # the namespace dict will be serialized in the message buffers,
793 # the namespace dict will be serialized in the message buffers,
789 # which will have a length of at least one
794 # which will have a length of at least one
790 buffers = ['pdict', ...]
795 buffers = ['pdict', ...]
791
796
792
797
793 The interpretation of a sequence of data_pub messages for a given parent request should be
798 The interpretation of a sequence of data_pub messages for a given parent request should be
794 to update a single namespace with subsequent results.
799 to update a single namespace with subsequent results.
795
800
796 .. note::
801 .. note::
797
802
798 No frontends directly handle data_pub messages at this time.
803 No frontends directly handle data_pub messages at this time.
799 It is currently only used by the client/engines in :mod:`IPython.parallel`,
804 It is currently only used by the client/engines in :mod:`IPython.parallel`,
800 where engines may publish *data* to the Client,
805 where engines may publish *data* to the Client,
801 of which the Client can then publish *representations* via ``display_data``
806 of which the Client can then publish *representations* via ``display_data``
802 to various frontends.
807 to various frontends.
803
808
804 Python inputs
809 Python inputs
805 -------------
810 -------------
806
811
807 These messages are the re-broadcast of the ``execute_request``.
812 These messages are the re-broadcast of the ``execute_request``.
808
813
809 Message type: ``pyin``::
814 Message type: ``pyin``::
810
815
811 content = {
816 content = {
812 'code' : str, # Source code to be executed, one or more lines
817 'code' : str, # Source code to be executed, one or more lines
813
818
814 # The counter for this execution is also provided so that clients can
819 # The counter for this execution is also provided so that clients can
815 # display it, since IPython automatically creates variables called _iN
820 # display it, since IPython automatically creates variables called _iN
816 # (for input prompt In[N]).
821 # (for input prompt In[N]).
817 'execution_count' : int
822 'execution_count' : int
818 }
823 }
819
824
820 Python outputs
825 Python outputs
821 --------------
826 --------------
822
827
823 When Python produces output from code that has been compiled in with the
828 When Python produces output from code that has been compiled in with the
824 'single' flag to :func:`compile`, any expression that produces a value (such as
829 'single' flag to :func:`compile`, any expression that produces a value (such as
825 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
830 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
826 this value whatever it wants. The default behavior of ``sys.displayhook`` in
831 this value whatever it wants. The default behavior of ``sys.displayhook`` in
827 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
832 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
828 the value as long as it is not ``None`` (which isn't printed at all). In our
833 the value as long as it is not ``None`` (which isn't printed at all). In our
829 case, the kernel instantiates as ``sys.displayhook`` an object which has
834 case, the kernel instantiates as ``sys.displayhook`` an object which has
830 similar behavior, but which instead of printing to stdout, broadcasts these
835 similar behavior, but which instead of printing to stdout, broadcasts these
831 values as ``pyout`` messages for clients to display appropriately.
836 values as ``pyout`` messages for clients to display appropriately.
832
837
833 IPython's displayhook can handle multiple simultaneous formats depending on its
838 IPython's displayhook can handle multiple simultaneous formats depending on its
834 configuration. The default pretty-printed repr text is always given with the
839 configuration. The default pretty-printed repr text is always given with the
835 ``data`` entry in this message. Any other formats are provided in the
840 ``data`` entry in this message. Any other formats are provided in the
836 ``extra_formats`` list. Frontends are free to display any or all of these
841 ``extra_formats`` list. Frontends are free to display any or all of these
837 according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
842 according to its capabilities. ``extra_formats`` list contains 3-tuples of an ID
838 string, a type string, and the data. The ID is unique to the formatter
843 string, a type string, and the data. The ID is unique to the formatter
839 implementation that created the data. Frontends will typically ignore the ID
844 implementation that created the data. Frontends will typically ignore the ID
840 unless if it has requested a particular formatter. The type string tells the
845 unless if it has requested a particular formatter. The type string tells the
841 frontend how to interpret the data. It is often, but not always a MIME type.
846 frontend how to interpret the data. It is often, but not always a MIME type.
842 Frontends should ignore types that it does not understand. The data itself is
847 Frontends should ignore types that it does not understand. The data itself is
843 any JSON object and depends on the format. It is often, but not always a string.
848 any JSON object and depends on the format. It is often, but not always a string.
844
849
845 Message type: ``pyout``::
850 Message type: ``pyout``::
846
851
847 content = {
852 content = {
848
853
849 # The counter for this execution is also provided so that clients can
854 # The counter for this execution is also provided so that clients can
850 # display it, since IPython automatically creates variables called _N
855 # display it, since IPython automatically creates variables called _N
851 # (for prompt N).
856 # (for prompt N).
852 'execution_count' : int,
857 'execution_count' : int,
853
858
854 # The data dict contains key/value pairs, where the kids are MIME
859 # The data dict contains key/value pairs, where the kids are MIME
855 # types and the values are the raw data of the representation in that
860 # types and the values are the raw data of the representation in that
856 # format. The data dict must minimally contain the ``text/plain``
861 # format. The data dict must minimally contain the ``text/plain``
857 # MIME type which is used as a backup representation.
862 # MIME type which is used as a backup representation.
858 'data' : dict,
863 'data' : dict,
859
864
860 }
865 }
861
866
862 Python errors
867 Python errors
863 -------------
868 -------------
864
869
865 When an error occurs during code execution
870 When an error occurs during code execution
866
871
867 Message type: ``pyerr``::
872 Message type: ``pyerr``::
868
873
869 content = {
874 content = {
870 # Similar content to the execute_reply messages for the 'error' case,
875 # Similar content to the execute_reply messages for the 'error' case,
871 # except the 'status' field is omitted.
876 # except the 'status' field is omitted.
872 }
877 }
873
878
874 Kernel status
879 Kernel status
875 -------------
880 -------------
876
881
877 This message type is used by frontends to monitor the status of the kernel.
882 This message type is used by frontends to monitor the status of the kernel.
878
883
879 Message type: ``status``::
884 Message type: ``status``::
880
885
881 content = {
886 content = {
882 # When the kernel starts to execute code, it will enter the 'busy'
887 # When the kernel starts to execute code, it will enter the 'busy'
883 # state and when it finishes, it will enter the 'idle' state.
888 # state and when it finishes, it will enter the 'idle' state.
884 execution_state : ('busy', 'idle')
889 execution_state : ('busy', 'idle')
885 }
890 }
886
891
887 Kernel crashes
892 Kernel crashes
888 --------------
893 --------------
889
894
890 When the kernel has an unexpected exception, caught by the last-resort
895 When the kernel has an unexpected exception, caught by the last-resort
891 sys.excepthook, we should broadcast the crash handler's output before exiting.
896 sys.excepthook, we should broadcast the crash handler's output before exiting.
892 This will allow clients to notice that a kernel died, inform the user and
897 This will allow clients to notice that a kernel died, inform the user and
893 propose further actions.
898 propose further actions.
894
899
895 Message type: ``crash``::
900 Message type: ``crash``::
896
901
897 content = {
902 content = {
898 # Similarly to the 'error' case for execute_reply messages, this will
903 # Similarly to the 'error' case for execute_reply messages, this will
899 # contain ename, etype and traceback fields.
904 # contain ename, etype and traceback fields.
900
905
901 # An additional field with supplementary information such as where to
906 # An additional field with supplementary information such as where to
902 # send the crash message
907 # send the crash message
903 'info' : str,
908 'info' : str,
904 }
909 }
905
910
906
911
907 Future ideas
912 Future ideas
908 ------------
913 ------------
909
914
910 Other potential message types, currently unimplemented, listed below as ideas.
915 Other potential message types, currently unimplemented, listed below as ideas.
911
916
912 Message type: ``file``::
917 Message type: ``file``::
913
918
914 content = {
919 content = {
915 'path' : 'cool.jpg',
920 'path' : 'cool.jpg',
916 'mimetype' : str,
921 'mimetype' : str,
917 'data' : str,
922 'data' : str,
918 }
923 }
919
924
920
925
921 Messages on the stdin ROUTER/DEALER sockets
926 Messages on the stdin ROUTER/DEALER sockets
922 ===========================================
927 ===========================================
923
928
924 This is a socket where the request/reply pattern goes in the opposite direction:
929 This is a socket where the request/reply pattern goes in the opposite direction:
925 from the kernel to a *single* frontend, and its purpose is to allow
930 from the kernel to a *single* frontend, and its purpose is to allow
926 ``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel
931 ``raw_input`` and similar operations that read from ``sys.stdin`` on the kernel
927 to be fulfilled by the client. The request should be made to the frontend that
932 to be fulfilled by the client. The request should be made to the frontend that
928 made the execution request that prompted ``raw_input`` to be called. For now we
933 made the execution request that prompted ``raw_input`` to be called. For now we
929 will keep these messages as simple as possible, since they only mean to convey
934 will keep these messages as simple as possible, since they only mean to convey
930 the ``raw_input(prompt)`` call.
935 the ``raw_input(prompt)`` call.
931
936
932 Message type: ``input_request``::
937 Message type: ``input_request``::
933
938
934 content = { 'prompt' : str }
939 content = { 'prompt' : str }
935
940
936 Message type: ``input_reply``::
941 Message type: ``input_reply``::
937
942
938 content = { 'value' : str }
943 content = { 'value' : str }
939
944
940 .. Note::
945 .. Note::
941
946
942 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
947 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
943 practice the kernel should behave like an interactive program. When a
948 practice the kernel should behave like an interactive program. When a
944 program is opened on the console, the keyboard effectively takes over the
949 program is opened on the console, the keyboard effectively takes over the
945 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
950 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
946 Since the IPython kernel effectively behaves like a console program (albeit
951 Since the IPython kernel effectively behaves like a console program (albeit
947 one whose "keyboard" is actually living in a separate process and
952 one whose "keyboard" is actually living in a separate process and
948 transported over the zmq connection), raw ``stdin`` isn't expected to be
953 transported over the zmq connection), raw ``stdin`` isn't expected to be
949 available.
954 available.
950
955
951
956
952 Heartbeat for kernels
957 Heartbeat for kernels
953 =====================
958 =====================
954
959
955 Initially we had considered using messages like those above over ZMQ for a
960 Initially we had considered using messages like those above over ZMQ for a
956 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
961 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
957 alive at all, even if it may be busy executing user code). But this has the
962 alive at all, even if it may be busy executing user code). But this has the
958 problem that if the kernel is locked inside extension code, it wouldn't execute
963 problem that if the kernel is locked inside extension code, it wouldn't execute
959 the python heartbeat code. But it turns out that we can implement a basic
964 the python heartbeat code. But it turns out that we can implement a basic
960 heartbeat with pure ZMQ, without using any Python messaging at all.
965 heartbeat with pure ZMQ, without using any Python messaging at all.
961
966
962 The monitor sends out a single zmq message (right now, it is a str of the
967 The monitor sends out a single zmq message (right now, it is a str of the
963 monitor's lifetime in seconds), and gets the same message right back, prefixed
968 monitor's lifetime in seconds), and gets the same message right back, prefixed
964 with the zmq identity of the DEALER socket in the heartbeat process. This can be
969 with the zmq identity of the DEALER socket in the heartbeat process. This can be
965 a uuid, or even a full message, but there doesn't seem to be a need for packing
970 a uuid, or even a full message, but there doesn't seem to be a need for packing
966 up a message when the sender and receiver are the exact same Python object.
971 up a message when the sender and receiver are the exact same Python object.
967
972
968 The model is this::
973 The model is this::
969
974
970 monitor.send(str(self.lifetime)) # '1.2345678910'
975 monitor.send(str(self.lifetime)) # '1.2345678910'
971
976
972 and the monitor receives some number of messages of the form::
977 and the monitor receives some number of messages of the form::
973
978
974 ['uuid-abcd-dead-beef', '1.2345678910']
979 ['uuid-abcd-dead-beef', '1.2345678910']
975
980
976 where the first part is the zmq.IDENTITY of the heart's DEALER on the engine, and
981 where the first part is the zmq.IDENTITY of the heart's DEALER on the engine, and
977 the rest is the message sent by the monitor. No Python code ever has any
982 the rest is the message sent by the monitor. No Python code ever has any
978 access to the message between the monitor's send, and the monitor's recv.
983 access to the message between the monitor's send, and the monitor's recv.
979
984
980
985
981 ToDo
986 ToDo
982 ====
987 ====
983
988
984 Missing things include:
989 Missing things include:
985
990
986 * Important: finish thinking through the payload concept and API.
991 * Important: finish thinking through the payload concept and API.
987
992
988 * Important: ensure that we have a good solution for magics like %edit. It's
993 * Important: ensure that we have a good solution for magics like %edit. It's
989 likely that with the payload concept we can build a full solution, but not
994 likely that with the payload concept we can build a full solution, but not
990 100% clear yet.
995 100% clear yet.
991
996
992 * Finishing the details of the heartbeat protocol.
997 * Finishing the details of the heartbeat protocol.
993
998
994 * Signal handling: specify what kind of information kernel should broadcast (or
999 * Signal handling: specify what kind of information kernel should broadcast (or
995 not) when it receives signals.
1000 not) when it receives signals.
996
1001
997 .. include:: ../links.rst
1002 .. include:: ../links.rst
General Comments 0
You need to be logged in to leave comments. Login now