##// END OF EJS Templates
Add function signature info to calltips....
Fernando Perez -
Show More
@@ -0,0 +1,89 b''
1 """Tests for the object inspection functionality.
2 """
3 #-----------------------------------------------------------------------------
4 # Copyright (C) 2010 The IPython Development Team.
5 #
6 # Distributed under the terms of the BSD License.
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
10
11 #-----------------------------------------------------------------------------
12 # Imports
13 #-----------------------------------------------------------------------------
14 from __future__ import print_function
15
16 # Stdlib imports
17
18 # Third-party imports
19 import nose.tools as nt
20
21 # Our own imports
22 from .. import oinspect
23
24 #-----------------------------------------------------------------------------
25 # Globals and constants
26 #-----------------------------------------------------------------------------
27
28 inspector = oinspect.Inspector()
29
30 #-----------------------------------------------------------------------------
31 # Local utilities
32 #-----------------------------------------------------------------------------
33
34 # A few generic objects we can then inspect in the tests below
35
36 class Call(object):
37 """This is the class docstring."""
38
39 def __init__(self, x, y=1):
40 """This is the constructor docstring."""
41
42 def __call__(self, *a, **kw):
43 """This is the call docstring."""
44
45 def method(self, x, z=2):
46 """Some method's docstring"""
47
48 def f(x, y=2, *a, **kw):
49 """A simple function."""
50
51 def g(y, z=3, *a, **kw):
52 pass # no docstring
53
54
55 def check_calltip(obj, name, call, docstring):
56 """Generic check pattern all calltip tests will use"""
57 info = inspector.info(obj, name)
58 call_line, ds = oinspect.call_tip(info)
59 nt.assert_equal(call_line, call)
60 nt.assert_equal(ds, docstring)
61
62 #-----------------------------------------------------------------------------
63 # Tests
64 #-----------------------------------------------------------------------------
65
66 def test_calltip_class():
67 check_calltip(Call, 'Call', 'Call(x, y=1)', Call.__init__.__doc__)
68
69
70 def test_calltip_instance():
71 c = Call(1)
72 check_calltip(c, 'c', 'c(*a, **kw)', c.__call__.__doc__)
73
74
75 def test_calltip_method():
76 c = Call(1)
77 check_calltip(c.method, 'c.method', 'c.method(x, z=2)', c.method.__doc__)
78
79
80 def test_calltip_function():
81 check_calltip(f, 'f', 'f(x, y=2, *a, **kw)', f.__doc__)
82
83
84 def test_calltip_function2():
85 check_calltip(g, 'g', 'g(y, z=3, *a, **kw)', '<no docstring>')
86
87
88 def test_calltip_builtin():
89 check_calltip(sum, 'sum', None, sum.__doc__)
@@ -1,2572 +1,2573 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-2010 The IPython Development Team
7 # Copyright (C) 2008-2010 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
19
20 import __builtin__
20 import __builtin__
21 import __future__
21 import __future__
22 import abc
22 import abc
23 import atexit
23 import atexit
24 import codeop
24 import codeop
25 import exceptions
25 import exceptions
26 import new
26 import new
27 import os
27 import os
28 import re
28 import re
29 import string
29 import string
30 import sys
30 import sys
31 import tempfile
31 import tempfile
32 from contextlib import nested
32 from contextlib import nested
33
33
34 from IPython.config.configurable import Configurable
34 from IPython.config.configurable import Configurable
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import history as ipcorehist
36 from IPython.core import history as ipcorehist
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core import prefilter
38 from IPython.core import prefilter
39 from IPython.core import shadowns
39 from IPython.core import shadowns
40 from IPython.core import ultratb
40 from IPython.core import ultratb
41 from IPython.core.alias import AliasManager
41 from IPython.core.alias import AliasManager
42 from IPython.core.builtin_trap import BuiltinTrap
42 from IPython.core.builtin_trap import BuiltinTrap
43 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.display_trap import DisplayTrap
44 from IPython.core.displayhook import DisplayHook
44 from IPython.core.displayhook import DisplayHook
45 from IPython.core.error import TryNext, UsageError
45 from IPython.core.error import TryNext, UsageError
46 from IPython.core.extensions import ExtensionManager
46 from IPython.core.extensions import ExtensionManager
47 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
47 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
48 from IPython.core.inputlist import InputList
48 from IPython.core.inputlist import InputList
49 from IPython.core.inputsplitter import IPythonInputSplitter
49 from IPython.core.inputsplitter import IPythonInputSplitter
50 from IPython.core.logger import Logger
50 from IPython.core.logger import Logger
51 from IPython.core.magic import Magic
51 from IPython.core.magic import Magic
52 from IPython.core.payload import PayloadManager
52 from IPython.core.payload import PayloadManager
53 from IPython.core.plugin import PluginManager
53 from IPython.core.plugin import PluginManager
54 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
54 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
55 from IPython.external.Itpl import ItplNS
55 from IPython.external.Itpl import ItplNS
56 from IPython.utils import PyColorize
56 from IPython.utils import PyColorize
57 from IPython.utils import io
57 from IPython.utils import io
58 from IPython.utils import pickleshare
58 from IPython.utils import pickleshare
59 from IPython.utils.doctestreload import doctest_reload
59 from IPython.utils.doctestreload import doctest_reload
60 from IPython.utils.io import ask_yes_no, rprint
60 from IPython.utils.io import ask_yes_no, rprint
61 from IPython.utils.ipstruct import Struct
61 from IPython.utils.ipstruct import Struct
62 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
62 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
63 from IPython.utils.process import system, getoutput
63 from IPython.utils.process import system, getoutput
64 from IPython.utils.strdispatch import StrDispatch
64 from IPython.utils.strdispatch import StrDispatch
65 from IPython.utils.syspathcontext import prepended_to_syspath
65 from IPython.utils.syspathcontext import prepended_to_syspath
66 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
66 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
67 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
67 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
68 List, Unicode, Instance, Type)
68 List, Unicode, Instance, Type)
69 from IPython.utils.warn import warn, error, fatal
69 from IPython.utils.warn import warn, error, fatal
70 import IPython.core.hooks
70 import IPython.core.hooks
71
71
72 #-----------------------------------------------------------------------------
72 #-----------------------------------------------------------------------------
73 # Globals
73 # Globals
74 #-----------------------------------------------------------------------------
74 #-----------------------------------------------------------------------------
75
75
76 # compiled regexps for autoindent management
76 # compiled regexps for autoindent management
77 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
77 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
78
78
79 #-----------------------------------------------------------------------------
79 #-----------------------------------------------------------------------------
80 # Utilities
80 # Utilities
81 #-----------------------------------------------------------------------------
81 #-----------------------------------------------------------------------------
82
82
83 # store the builtin raw_input globally, and use this always, in case user code
83 # store the builtin raw_input globally, and use this always, in case user code
84 # overwrites it (like wx.py.PyShell does)
84 # overwrites it (like wx.py.PyShell does)
85 raw_input_original = raw_input
85 raw_input_original = raw_input
86
86
87 def softspace(file, newvalue):
87 def softspace(file, newvalue):
88 """Copied from code.py, to remove the dependency"""
88 """Copied from code.py, to remove the dependency"""
89
89
90 oldvalue = 0
90 oldvalue = 0
91 try:
91 try:
92 oldvalue = file.softspace
92 oldvalue = file.softspace
93 except AttributeError:
93 except AttributeError:
94 pass
94 pass
95 try:
95 try:
96 file.softspace = newvalue
96 file.softspace = newvalue
97 except (AttributeError, TypeError):
97 except (AttributeError, TypeError):
98 # "attribute-less object" or "read-only attributes"
98 # "attribute-less object" or "read-only attributes"
99 pass
99 pass
100 return oldvalue
100 return oldvalue
101
101
102
102
103 def no_op(*a, **kw): pass
103 def no_op(*a, **kw): pass
104
104
105 class SpaceInInput(exceptions.Exception): pass
105 class SpaceInInput(exceptions.Exception): pass
106
106
107 class Bunch: pass
107 class Bunch: pass
108
108
109
109
110 def get_default_colors():
110 def get_default_colors():
111 if sys.platform=='darwin':
111 if sys.platform=='darwin':
112 return "LightBG"
112 return "LightBG"
113 elif os.name=='nt':
113 elif os.name=='nt':
114 return 'Linux'
114 return 'Linux'
115 else:
115 else:
116 return 'Linux'
116 return 'Linux'
117
117
118
118
119 class SeparateStr(Str):
119 class SeparateStr(Str):
120 """A Str subclass to validate separate_in, separate_out, etc.
120 """A Str subclass to validate separate_in, separate_out, etc.
121
121
122 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
122 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
123 """
123 """
124
124
125 def validate(self, obj, value):
125 def validate(self, obj, value):
126 if value == '0': value = ''
126 if value == '0': value = ''
127 value = value.replace('\\n','\n')
127 value = value.replace('\\n','\n')
128 return super(SeparateStr, self).validate(obj, value)
128 return super(SeparateStr, self).validate(obj, value)
129
129
130 class MultipleInstanceError(Exception):
130 class MultipleInstanceError(Exception):
131 pass
131 pass
132
132
133
133
134 #-----------------------------------------------------------------------------
134 #-----------------------------------------------------------------------------
135 # Main IPython class
135 # Main IPython class
136 #-----------------------------------------------------------------------------
136 #-----------------------------------------------------------------------------
137
137
138
138
139 class InteractiveShell(Configurable, Magic):
139 class InteractiveShell(Configurable, Magic):
140 """An enhanced, interactive shell for Python."""
140 """An enhanced, interactive shell for Python."""
141
141
142 _instance = None
142 _instance = None
143 autocall = Enum((0,1,2), default_value=1, config=True)
143 autocall = Enum((0,1,2), default_value=1, config=True)
144 # TODO: remove all autoindent logic and put into frontends.
144 # TODO: remove all autoindent logic and put into frontends.
145 # We can't do this yet because even runlines uses the autoindent.
145 # We can't do this yet because even runlines uses the autoindent.
146 autoindent = CBool(True, config=True)
146 autoindent = CBool(True, config=True)
147 automagic = CBool(True, config=True)
147 automagic = CBool(True, config=True)
148 cache_size = Int(1000, config=True)
148 cache_size = Int(1000, config=True)
149 color_info = CBool(True, config=True)
149 color_info = CBool(True, config=True)
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
150 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
151 default_value=get_default_colors(), config=True)
151 default_value=get_default_colors(), config=True)
152 debug = CBool(False, config=True)
152 debug = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
153 deep_reload = CBool(False, config=True)
154 displayhook_class = Type(DisplayHook)
154 displayhook_class = Type(DisplayHook)
155 exit_now = CBool(False)
155 exit_now = CBool(False)
156 filename = Str("<ipython console>")
156 filename = Str("<ipython console>")
157 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
157 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
158
158
159 # Input splitter, to split entire cells of input into either individual
159 # Input splitter, to split entire cells of input into either individual
160 # interactive statements or whole blocks.
160 # interactive statements or whole blocks.
161 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
161 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
162 (), {})
162 (), {})
163 logstart = CBool(False, config=True)
163 logstart = CBool(False, config=True)
164 logfile = Str('', config=True)
164 logfile = Str('', config=True)
165 logappend = Str('', config=True)
165 logappend = Str('', config=True)
166 object_info_string_level = Enum((0,1,2), default_value=0,
166 object_info_string_level = Enum((0,1,2), default_value=0,
167 config=True)
167 config=True)
168 pdb = CBool(False, config=True)
168 pdb = CBool(False, config=True)
169
169
170 pprint = CBool(True, config=True)
170 pprint = CBool(True, config=True)
171 profile = Str('', config=True)
171 profile = Str('', config=True)
172 prompt_in1 = Str('In [\\#]: ', config=True)
172 prompt_in1 = Str('In [\\#]: ', config=True)
173 prompt_in2 = Str(' .\\D.: ', config=True)
173 prompt_in2 = Str(' .\\D.: ', config=True)
174 prompt_out = Str('Out[\\#]: ', config=True)
174 prompt_out = Str('Out[\\#]: ', config=True)
175 prompts_pad_left = CBool(True, config=True)
175 prompts_pad_left = CBool(True, config=True)
176 quiet = CBool(False, config=True)
176 quiet = CBool(False, config=True)
177
177
178 # The readline stuff will eventually be moved to the terminal subclass
178 # The readline stuff will eventually be moved to the terminal subclass
179 # but for now, we can't do that as readline is welded in everywhere.
179 # but for now, we can't do that as readline is welded in everywhere.
180 readline_use = CBool(True, config=True)
180 readline_use = CBool(True, config=True)
181 readline_merge_completions = CBool(True, config=True)
181 readline_merge_completions = CBool(True, config=True)
182 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
182 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
183 readline_remove_delims = Str('-/~', config=True)
183 readline_remove_delims = Str('-/~', config=True)
184 readline_parse_and_bind = List([
184 readline_parse_and_bind = List([
185 'tab: complete',
185 'tab: complete',
186 '"\C-l": clear-screen',
186 '"\C-l": clear-screen',
187 'set show-all-if-ambiguous on',
187 'set show-all-if-ambiguous on',
188 '"\C-o": tab-insert',
188 '"\C-o": tab-insert',
189 '"\M-i": " "',
189 '"\M-i": " "',
190 '"\M-o": "\d\d\d\d"',
190 '"\M-o": "\d\d\d\d"',
191 '"\M-I": "\d\d\d\d"',
191 '"\M-I": "\d\d\d\d"',
192 '"\C-r": reverse-search-history',
192 '"\C-r": reverse-search-history',
193 '"\C-s": forward-search-history',
193 '"\C-s": forward-search-history',
194 '"\C-p": history-search-backward',
194 '"\C-p": history-search-backward',
195 '"\C-n": history-search-forward',
195 '"\C-n": history-search-forward',
196 '"\e[A": history-search-backward',
196 '"\e[A": history-search-backward',
197 '"\e[B": history-search-forward',
197 '"\e[B": history-search-forward',
198 '"\C-k": kill-line',
198 '"\C-k": kill-line',
199 '"\C-u": unix-line-discard',
199 '"\C-u": unix-line-discard',
200 ], allow_none=False, config=True)
200 ], allow_none=False, config=True)
201
201
202 # TODO: this part of prompt management should be moved to the frontends.
202 # TODO: this part of prompt management should be moved to the frontends.
203 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
203 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
204 separate_in = SeparateStr('\n', config=True)
204 separate_in = SeparateStr('\n', config=True)
205 separate_out = SeparateStr('', config=True)
205 separate_out = SeparateStr('', config=True)
206 separate_out2 = SeparateStr('', config=True)
206 separate_out2 = SeparateStr('', config=True)
207 wildcards_case_sensitive = CBool(True, config=True)
207 wildcards_case_sensitive = CBool(True, config=True)
208 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
208 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
209 default_value='Context', config=True)
209 default_value='Context', config=True)
210
210
211 # Subcomponents of InteractiveShell
211 # Subcomponents of InteractiveShell
212 alias_manager = Instance('IPython.core.alias.AliasManager')
212 alias_manager = Instance('IPython.core.alias.AliasManager')
213 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
213 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
214 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
214 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
215 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
215 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
216 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
216 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
217 plugin_manager = Instance('IPython.core.plugin.PluginManager')
217 plugin_manager = Instance('IPython.core.plugin.PluginManager')
218 payload_manager = Instance('IPython.core.payload.PayloadManager')
218 payload_manager = Instance('IPython.core.payload.PayloadManager')
219
219
220 # Private interface
220 # Private interface
221 _post_execute = set()
221 _post_execute = set()
222
222
223 def __init__(self, config=None, ipython_dir=None,
223 def __init__(self, config=None, ipython_dir=None,
224 user_ns=None, user_global_ns=None,
224 user_ns=None, user_global_ns=None,
225 custom_exceptions=((), None)):
225 custom_exceptions=((), None)):
226
226
227 # This is where traits with a config_key argument are updated
227 # This is where traits with a config_key argument are updated
228 # from the values on config.
228 # from the values on config.
229 super(InteractiveShell, self).__init__(config=config)
229 super(InteractiveShell, self).__init__(config=config)
230
230
231 # These are relatively independent and stateless
231 # These are relatively independent and stateless
232 self.init_ipython_dir(ipython_dir)
232 self.init_ipython_dir(ipython_dir)
233 self.init_instance_attrs()
233 self.init_instance_attrs()
234 self.init_environment()
234 self.init_environment()
235
235
236 # Create namespaces (user_ns, user_global_ns, etc.)
236 # Create namespaces (user_ns, user_global_ns, etc.)
237 self.init_create_namespaces(user_ns, user_global_ns)
237 self.init_create_namespaces(user_ns, user_global_ns)
238 # This has to be done after init_create_namespaces because it uses
238 # This has to be done after init_create_namespaces because it uses
239 # something in self.user_ns, but before init_sys_modules, which
239 # something in self.user_ns, but before init_sys_modules, which
240 # is the first thing to modify sys.
240 # is the first thing to modify sys.
241 # TODO: When we override sys.stdout and sys.stderr before this class
241 # TODO: When we override sys.stdout and sys.stderr before this class
242 # is created, we are saving the overridden ones here. Not sure if this
242 # is created, we are saving the overridden ones here. Not sure if this
243 # is what we want to do.
243 # is what we want to do.
244 self.save_sys_module_state()
244 self.save_sys_module_state()
245 self.init_sys_modules()
245 self.init_sys_modules()
246
246
247 self.init_history()
247 self.init_history()
248 self.init_encoding()
248 self.init_encoding()
249 self.init_prefilter()
249 self.init_prefilter()
250
250
251 Magic.__init__(self, self)
251 Magic.__init__(self, self)
252
252
253 self.init_syntax_highlighting()
253 self.init_syntax_highlighting()
254 self.init_hooks()
254 self.init_hooks()
255 self.init_pushd_popd_magic()
255 self.init_pushd_popd_magic()
256 # self.init_traceback_handlers use to be here, but we moved it below
256 # self.init_traceback_handlers use to be here, but we moved it below
257 # because it and init_io have to come after init_readline.
257 # because it and init_io have to come after init_readline.
258 self.init_user_ns()
258 self.init_user_ns()
259 self.init_logger()
259 self.init_logger()
260 self.init_alias()
260 self.init_alias()
261 self.init_builtins()
261 self.init_builtins()
262
262
263 # pre_config_initialization
263 # pre_config_initialization
264 self.init_shadow_hist()
264 self.init_shadow_hist()
265
265
266 # The next section should contain everything that was in ipmaker.
266 # The next section should contain everything that was in ipmaker.
267 self.init_logstart()
267 self.init_logstart()
268
268
269 # The following was in post_config_initialization
269 # The following was in post_config_initialization
270 self.init_inspector()
270 self.init_inspector()
271 # init_readline() must come before init_io(), because init_io uses
271 # init_readline() must come before init_io(), because init_io uses
272 # readline related things.
272 # readline related things.
273 self.init_readline()
273 self.init_readline()
274 # init_completer must come after init_readline, because it needs to
274 # init_completer must come after init_readline, because it needs to
275 # know whether readline is present or not system-wide to configure the
275 # know whether readline is present or not system-wide to configure the
276 # completers, since the completion machinery can now operate
276 # completers, since the completion machinery can now operate
277 # independently of readline (e.g. over the network)
277 # independently of readline (e.g. over the network)
278 self.init_completer()
278 self.init_completer()
279 # TODO: init_io() needs to happen before init_traceback handlers
279 # TODO: init_io() needs to happen before init_traceback handlers
280 # because the traceback handlers hardcode the stdout/stderr streams.
280 # because the traceback handlers hardcode the stdout/stderr streams.
281 # This logic in in debugger.Pdb and should eventually be changed.
281 # This logic in in debugger.Pdb and should eventually be changed.
282 self.init_io()
282 self.init_io()
283 self.init_traceback_handlers(custom_exceptions)
283 self.init_traceback_handlers(custom_exceptions)
284 self.init_prompts()
284 self.init_prompts()
285 self.init_displayhook()
285 self.init_displayhook()
286 self.init_reload_doctest()
286 self.init_reload_doctest()
287 self.init_magics()
287 self.init_magics()
288 self.init_pdb()
288 self.init_pdb()
289 self.init_extension_manager()
289 self.init_extension_manager()
290 self.init_plugin_manager()
290 self.init_plugin_manager()
291 self.init_payload()
291 self.init_payload()
292 self.hooks.late_startup_hook()
292 self.hooks.late_startup_hook()
293 atexit.register(self.atexit_operations)
293 atexit.register(self.atexit_operations)
294
294
295 @classmethod
295 @classmethod
296 def instance(cls, *args, **kwargs):
296 def instance(cls, *args, **kwargs):
297 """Returns a global InteractiveShell instance."""
297 """Returns a global InteractiveShell instance."""
298 if cls._instance is None:
298 if cls._instance is None:
299 inst = cls(*args, **kwargs)
299 inst = cls(*args, **kwargs)
300 # Now make sure that the instance will also be returned by
300 # Now make sure that the instance will also be returned by
301 # the subclasses instance attribute.
301 # the subclasses instance attribute.
302 for subclass in cls.mro():
302 for subclass in cls.mro():
303 if issubclass(cls, subclass) and \
303 if issubclass(cls, subclass) and \
304 issubclass(subclass, InteractiveShell):
304 issubclass(subclass, InteractiveShell):
305 subclass._instance = inst
305 subclass._instance = inst
306 else:
306 else:
307 break
307 break
308 if isinstance(cls._instance, cls):
308 if isinstance(cls._instance, cls):
309 return cls._instance
309 return cls._instance
310 else:
310 else:
311 raise MultipleInstanceError(
311 raise MultipleInstanceError(
312 'Multiple incompatible subclass instances of '
312 'Multiple incompatible subclass instances of '
313 'InteractiveShell are being created.'
313 'InteractiveShell are being created.'
314 )
314 )
315
315
316 @classmethod
316 @classmethod
317 def initialized(cls):
317 def initialized(cls):
318 return hasattr(cls, "_instance")
318 return hasattr(cls, "_instance")
319
319
320 def get_ipython(self):
320 def get_ipython(self):
321 """Return the currently running IPython instance."""
321 """Return the currently running IPython instance."""
322 return self
322 return self
323
323
324 #-------------------------------------------------------------------------
324 #-------------------------------------------------------------------------
325 # Trait changed handlers
325 # Trait changed handlers
326 #-------------------------------------------------------------------------
326 #-------------------------------------------------------------------------
327
327
328 def _ipython_dir_changed(self, name, new):
328 def _ipython_dir_changed(self, name, new):
329 if not os.path.isdir(new):
329 if not os.path.isdir(new):
330 os.makedirs(new, mode = 0777)
330 os.makedirs(new, mode = 0777)
331
331
332 def set_autoindent(self,value=None):
332 def set_autoindent(self,value=None):
333 """Set the autoindent flag, checking for readline support.
333 """Set the autoindent flag, checking for readline support.
334
334
335 If called with no arguments, it acts as a toggle."""
335 If called with no arguments, it acts as a toggle."""
336
336
337 if not self.has_readline:
337 if not self.has_readline:
338 if os.name == 'posix':
338 if os.name == 'posix':
339 warn("The auto-indent feature requires the readline library")
339 warn("The auto-indent feature requires the readline library")
340 self.autoindent = 0
340 self.autoindent = 0
341 return
341 return
342 if value is None:
342 if value is None:
343 self.autoindent = not self.autoindent
343 self.autoindent = not self.autoindent
344 else:
344 else:
345 self.autoindent = value
345 self.autoindent = value
346
346
347 #-------------------------------------------------------------------------
347 #-------------------------------------------------------------------------
348 # init_* methods called by __init__
348 # init_* methods called by __init__
349 #-------------------------------------------------------------------------
349 #-------------------------------------------------------------------------
350
350
351 def init_ipython_dir(self, ipython_dir):
351 def init_ipython_dir(self, ipython_dir):
352 if ipython_dir is not None:
352 if ipython_dir is not None:
353 self.ipython_dir = ipython_dir
353 self.ipython_dir = ipython_dir
354 self.config.Global.ipython_dir = self.ipython_dir
354 self.config.Global.ipython_dir = self.ipython_dir
355 return
355 return
356
356
357 if hasattr(self.config.Global, 'ipython_dir'):
357 if hasattr(self.config.Global, 'ipython_dir'):
358 self.ipython_dir = self.config.Global.ipython_dir
358 self.ipython_dir = self.config.Global.ipython_dir
359 else:
359 else:
360 self.ipython_dir = get_ipython_dir()
360 self.ipython_dir = get_ipython_dir()
361
361
362 # All children can just read this
362 # All children can just read this
363 self.config.Global.ipython_dir = self.ipython_dir
363 self.config.Global.ipython_dir = self.ipython_dir
364
364
365 def init_instance_attrs(self):
365 def init_instance_attrs(self):
366 self.more = False
366 self.more = False
367
367
368 # command compiler
368 # command compiler
369 self.compile = codeop.CommandCompiler()
369 self.compile = codeop.CommandCompiler()
370
370
371 # User input buffer
371 # User input buffer
372 self.buffer = []
372 self.buffer = []
373
373
374 # Make an empty namespace, which extension writers can rely on both
374 # Make an empty namespace, which extension writers can rely on both
375 # existing and NEVER being used by ipython itself. This gives them a
375 # existing and NEVER being used by ipython itself. This gives them a
376 # convenient location for storing additional information and state
376 # convenient location for storing additional information and state
377 # their extensions may require, without fear of collisions with other
377 # their extensions may require, without fear of collisions with other
378 # ipython names that may develop later.
378 # ipython names that may develop later.
379 self.meta = Struct()
379 self.meta = Struct()
380
380
381 # Object variable to store code object waiting execution. This is
381 # Object variable to store code object waiting execution. This is
382 # used mainly by the multithreaded shells, but it can come in handy in
382 # used mainly by the multithreaded shells, but it can come in handy in
383 # other situations. No need to use a Queue here, since it's a single
383 # other situations. No need to use a Queue here, since it's a single
384 # item which gets cleared once run.
384 # item which gets cleared once run.
385 self.code_to_run = None
385 self.code_to_run = None
386
386
387 # Temporary files used for various purposes. Deleted at exit.
387 # Temporary files used for various purposes. Deleted at exit.
388 self.tempfiles = []
388 self.tempfiles = []
389
389
390 # Keep track of readline usage (later set by init_readline)
390 # Keep track of readline usage (later set by init_readline)
391 self.has_readline = False
391 self.has_readline = False
392
392
393 # keep track of where we started running (mainly for crash post-mortem)
393 # keep track of where we started running (mainly for crash post-mortem)
394 # This is not being used anywhere currently.
394 # This is not being used anywhere currently.
395 self.starting_dir = os.getcwd()
395 self.starting_dir = os.getcwd()
396
396
397 # Indentation management
397 # Indentation management
398 self.indent_current_nsp = 0
398 self.indent_current_nsp = 0
399
399
400 def init_environment(self):
400 def init_environment(self):
401 """Any changes we need to make to the user's environment."""
401 """Any changes we need to make to the user's environment."""
402 pass
402 pass
403
403
404 def init_encoding(self):
404 def init_encoding(self):
405 # Get system encoding at startup time. Certain terminals (like Emacs
405 # Get system encoding at startup time. Certain terminals (like Emacs
406 # under Win32 have it set to None, and we need to have a known valid
406 # under Win32 have it set to None, and we need to have a known valid
407 # encoding to use in the raw_input() method
407 # encoding to use in the raw_input() method
408 try:
408 try:
409 self.stdin_encoding = sys.stdin.encoding or 'ascii'
409 self.stdin_encoding = sys.stdin.encoding or 'ascii'
410 except AttributeError:
410 except AttributeError:
411 self.stdin_encoding = 'ascii'
411 self.stdin_encoding = 'ascii'
412
412
413 def init_syntax_highlighting(self):
413 def init_syntax_highlighting(self):
414 # Python source parser/formatter for syntax highlighting
414 # Python source parser/formatter for syntax highlighting
415 pyformat = PyColorize.Parser().format
415 pyformat = PyColorize.Parser().format
416 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
416 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
417
417
418 def init_pushd_popd_magic(self):
418 def init_pushd_popd_magic(self):
419 # for pushd/popd management
419 # for pushd/popd management
420 try:
420 try:
421 self.home_dir = get_home_dir()
421 self.home_dir = get_home_dir()
422 except HomeDirError, msg:
422 except HomeDirError, msg:
423 fatal(msg)
423 fatal(msg)
424
424
425 self.dir_stack = []
425 self.dir_stack = []
426
426
427 def init_logger(self):
427 def init_logger(self):
428 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
428 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
429 # local shortcut, this is used a LOT
429 # local shortcut, this is used a LOT
430 self.log = self.logger.log
430 self.log = self.logger.log
431
431
432 def init_logstart(self):
432 def init_logstart(self):
433 if self.logappend:
433 if self.logappend:
434 self.magic_logstart(self.logappend + ' append')
434 self.magic_logstart(self.logappend + ' append')
435 elif self.logfile:
435 elif self.logfile:
436 self.magic_logstart(self.logfile)
436 self.magic_logstart(self.logfile)
437 elif self.logstart:
437 elif self.logstart:
438 self.magic_logstart()
438 self.magic_logstart()
439
439
440 def init_builtins(self):
440 def init_builtins(self):
441 self.builtin_trap = BuiltinTrap(shell=self)
441 self.builtin_trap = BuiltinTrap(shell=self)
442
442
443 def init_inspector(self):
443 def init_inspector(self):
444 # Object inspector
444 # Object inspector
445 self.inspector = oinspect.Inspector(oinspect.InspectColors,
445 self.inspector = oinspect.Inspector(oinspect.InspectColors,
446 PyColorize.ANSICodeColors,
446 PyColorize.ANSICodeColors,
447 'NoColor',
447 'NoColor',
448 self.object_info_string_level)
448 self.object_info_string_level)
449
449
450 def init_io(self):
450 def init_io(self):
451 # This will just use sys.stdout and sys.stderr. If you want to
451 # This will just use sys.stdout and sys.stderr. If you want to
452 # override sys.stdout and sys.stderr themselves, you need to do that
452 # override sys.stdout and sys.stderr themselves, you need to do that
453 # *before* instantiating this class, because Term holds onto
453 # *before* instantiating this class, because Term holds onto
454 # references to the underlying streams.
454 # references to the underlying streams.
455 if sys.platform == 'win32' and self.has_readline:
455 if sys.platform == 'win32' and self.has_readline:
456 Term = io.IOTerm(cout=self.readline._outputfile,
456 Term = io.IOTerm(cout=self.readline._outputfile,
457 cerr=self.readline._outputfile)
457 cerr=self.readline._outputfile)
458 else:
458 else:
459 Term = io.IOTerm()
459 Term = io.IOTerm()
460 io.Term = Term
460 io.Term = Term
461
461
462 def init_prompts(self):
462 def init_prompts(self):
463 # TODO: This is a pass for now because the prompts are managed inside
463 # TODO: This is a pass for now because the prompts are managed inside
464 # the DisplayHook. Once there is a separate prompt manager, this
464 # the DisplayHook. Once there is a separate prompt manager, this
465 # will initialize that object and all prompt related information.
465 # will initialize that object and all prompt related information.
466 pass
466 pass
467
467
468 def init_displayhook(self):
468 def init_displayhook(self):
469 # Initialize displayhook, set in/out prompts and printing system
469 # Initialize displayhook, set in/out prompts and printing system
470 self.displayhook = self.displayhook_class(
470 self.displayhook = self.displayhook_class(
471 shell=self,
471 shell=self,
472 cache_size=self.cache_size,
472 cache_size=self.cache_size,
473 input_sep = self.separate_in,
473 input_sep = self.separate_in,
474 output_sep = self.separate_out,
474 output_sep = self.separate_out,
475 output_sep2 = self.separate_out2,
475 output_sep2 = self.separate_out2,
476 ps1 = self.prompt_in1,
476 ps1 = self.prompt_in1,
477 ps2 = self.prompt_in2,
477 ps2 = self.prompt_in2,
478 ps_out = self.prompt_out,
478 ps_out = self.prompt_out,
479 pad_left = self.prompts_pad_left
479 pad_left = self.prompts_pad_left
480 )
480 )
481 # This is a context manager that installs/revmoes the displayhook at
481 # This is a context manager that installs/revmoes the displayhook at
482 # the appropriate time.
482 # the appropriate time.
483 self.display_trap = DisplayTrap(hook=self.displayhook)
483 self.display_trap = DisplayTrap(hook=self.displayhook)
484
484
485 def init_reload_doctest(self):
485 def init_reload_doctest(self):
486 # Do a proper resetting of doctest, including the necessary displayhook
486 # Do a proper resetting of doctest, including the necessary displayhook
487 # monkeypatching
487 # monkeypatching
488 try:
488 try:
489 doctest_reload()
489 doctest_reload()
490 except ImportError:
490 except ImportError:
491 warn("doctest module does not exist.")
491 warn("doctest module does not exist.")
492
492
493 #-------------------------------------------------------------------------
493 #-------------------------------------------------------------------------
494 # Things related to injections into the sys module
494 # Things related to injections into the sys module
495 #-------------------------------------------------------------------------
495 #-------------------------------------------------------------------------
496
496
497 def save_sys_module_state(self):
497 def save_sys_module_state(self):
498 """Save the state of hooks in the sys module.
498 """Save the state of hooks in the sys module.
499
499
500 This has to be called after self.user_ns is created.
500 This has to be called after self.user_ns is created.
501 """
501 """
502 self._orig_sys_module_state = {}
502 self._orig_sys_module_state = {}
503 self._orig_sys_module_state['stdin'] = sys.stdin
503 self._orig_sys_module_state['stdin'] = sys.stdin
504 self._orig_sys_module_state['stdout'] = sys.stdout
504 self._orig_sys_module_state['stdout'] = sys.stdout
505 self._orig_sys_module_state['stderr'] = sys.stderr
505 self._orig_sys_module_state['stderr'] = sys.stderr
506 self._orig_sys_module_state['excepthook'] = sys.excepthook
506 self._orig_sys_module_state['excepthook'] = sys.excepthook
507 try:
507 try:
508 self._orig_sys_modules_main_name = self.user_ns['__name__']
508 self._orig_sys_modules_main_name = self.user_ns['__name__']
509 except KeyError:
509 except KeyError:
510 pass
510 pass
511
511
512 def restore_sys_module_state(self):
512 def restore_sys_module_state(self):
513 """Restore the state of the sys module."""
513 """Restore the state of the sys module."""
514 try:
514 try:
515 for k, v in self._orig_sys_module_state.items():
515 for k, v in self._orig_sys_module_state.items():
516 setattr(sys, k, v)
516 setattr(sys, k, v)
517 except AttributeError:
517 except AttributeError:
518 pass
518 pass
519 # Reset what what done in self.init_sys_modules
519 # Reset what what done in self.init_sys_modules
520 try:
520 try:
521 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
521 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
522 except (AttributeError, KeyError):
522 except (AttributeError, KeyError):
523 pass
523 pass
524
524
525 #-------------------------------------------------------------------------
525 #-------------------------------------------------------------------------
526 # Things related to hooks
526 # Things related to hooks
527 #-------------------------------------------------------------------------
527 #-------------------------------------------------------------------------
528
528
529 def init_hooks(self):
529 def init_hooks(self):
530 # hooks holds pointers used for user-side customizations
530 # hooks holds pointers used for user-side customizations
531 self.hooks = Struct()
531 self.hooks = Struct()
532
532
533 self.strdispatchers = {}
533 self.strdispatchers = {}
534
534
535 # Set all default hooks, defined in the IPython.hooks module.
535 # Set all default hooks, defined in the IPython.hooks module.
536 hooks = IPython.core.hooks
536 hooks = IPython.core.hooks
537 for hook_name in hooks.__all__:
537 for hook_name in hooks.__all__:
538 # default hooks have priority 100, i.e. low; user hooks should have
538 # default hooks have priority 100, i.e. low; user hooks should have
539 # 0-100 priority
539 # 0-100 priority
540 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
540 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
541
541
542 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
542 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
543 """set_hook(name,hook) -> sets an internal IPython hook.
543 """set_hook(name,hook) -> sets an internal IPython hook.
544
544
545 IPython exposes some of its internal API as user-modifiable hooks. By
545 IPython exposes some of its internal API as user-modifiable hooks. By
546 adding your function to one of these hooks, you can modify IPython's
546 adding your function to one of these hooks, you can modify IPython's
547 behavior to call at runtime your own routines."""
547 behavior to call at runtime your own routines."""
548
548
549 # At some point in the future, this should validate the hook before it
549 # At some point in the future, this should validate the hook before it
550 # accepts it. Probably at least check that the hook takes the number
550 # accepts it. Probably at least check that the hook takes the number
551 # of args it's supposed to.
551 # of args it's supposed to.
552
552
553 f = new.instancemethod(hook,self,self.__class__)
553 f = new.instancemethod(hook,self,self.__class__)
554
554
555 # check if the hook is for strdispatcher first
555 # check if the hook is for strdispatcher first
556 if str_key is not None:
556 if str_key is not None:
557 sdp = self.strdispatchers.get(name, StrDispatch())
557 sdp = self.strdispatchers.get(name, StrDispatch())
558 sdp.add_s(str_key, f, priority )
558 sdp.add_s(str_key, f, priority )
559 self.strdispatchers[name] = sdp
559 self.strdispatchers[name] = sdp
560 return
560 return
561 if re_key is not None:
561 if re_key is not None:
562 sdp = self.strdispatchers.get(name, StrDispatch())
562 sdp = self.strdispatchers.get(name, StrDispatch())
563 sdp.add_re(re.compile(re_key), f, priority )
563 sdp.add_re(re.compile(re_key), f, priority )
564 self.strdispatchers[name] = sdp
564 self.strdispatchers[name] = sdp
565 return
565 return
566
566
567 dp = getattr(self.hooks, name, None)
567 dp = getattr(self.hooks, name, None)
568 if name not in IPython.core.hooks.__all__:
568 if name not in IPython.core.hooks.__all__:
569 print "Warning! Hook '%s' is not one of %s" % \
569 print "Warning! Hook '%s' is not one of %s" % \
570 (name, IPython.core.hooks.__all__ )
570 (name, IPython.core.hooks.__all__ )
571 if not dp:
571 if not dp:
572 dp = IPython.core.hooks.CommandChainDispatcher()
572 dp = IPython.core.hooks.CommandChainDispatcher()
573
573
574 try:
574 try:
575 dp.add(f,priority)
575 dp.add(f,priority)
576 except AttributeError:
576 except AttributeError:
577 # it was not commandchain, plain old func - replace
577 # it was not commandchain, plain old func - replace
578 dp = f
578 dp = f
579
579
580 setattr(self.hooks,name, dp)
580 setattr(self.hooks,name, dp)
581
581
582 def register_post_execute(self, func):
582 def register_post_execute(self, func):
583 """Register a function for calling after code execution.
583 """Register a function for calling after code execution.
584 """
584 """
585 if not callable(func):
585 if not callable(func):
586 raise ValueError('argument %s must be callable' % func)
586 raise ValueError('argument %s must be callable' % func)
587 self._post_execute.add(func)
587 self._post_execute.add(func)
588
588
589 #-------------------------------------------------------------------------
589 #-------------------------------------------------------------------------
590 # Things related to the "main" module
590 # Things related to the "main" module
591 #-------------------------------------------------------------------------
591 #-------------------------------------------------------------------------
592
592
593 def new_main_mod(self,ns=None):
593 def new_main_mod(self,ns=None):
594 """Return a new 'main' module object for user code execution.
594 """Return a new 'main' module object for user code execution.
595 """
595 """
596 main_mod = self._user_main_module
596 main_mod = self._user_main_module
597 init_fakemod_dict(main_mod,ns)
597 init_fakemod_dict(main_mod,ns)
598 return main_mod
598 return main_mod
599
599
600 def cache_main_mod(self,ns,fname):
600 def cache_main_mod(self,ns,fname):
601 """Cache a main module's namespace.
601 """Cache a main module's namespace.
602
602
603 When scripts are executed via %run, we must keep a reference to the
603 When scripts are executed via %run, we must keep a reference to the
604 namespace of their __main__ module (a FakeModule instance) around so
604 namespace of their __main__ module (a FakeModule instance) around so
605 that Python doesn't clear it, rendering objects defined therein
605 that Python doesn't clear it, rendering objects defined therein
606 useless.
606 useless.
607
607
608 This method keeps said reference in a private dict, keyed by the
608 This method keeps said reference in a private dict, keyed by the
609 absolute path of the module object (which corresponds to the script
609 absolute path of the module object (which corresponds to the script
610 path). This way, for multiple executions of the same script we only
610 path). This way, for multiple executions of the same script we only
611 keep one copy of the namespace (the last one), thus preventing memory
611 keep one copy of the namespace (the last one), thus preventing memory
612 leaks from old references while allowing the objects from the last
612 leaks from old references while allowing the objects from the last
613 execution to be accessible.
613 execution to be accessible.
614
614
615 Note: we can not allow the actual FakeModule instances to be deleted,
615 Note: we can not allow the actual FakeModule instances to be deleted,
616 because of how Python tears down modules (it hard-sets all their
616 because of how Python tears down modules (it hard-sets all their
617 references to None without regard for reference counts). This method
617 references to None without regard for reference counts). This method
618 must therefore make a *copy* of the given namespace, to allow the
618 must therefore make a *copy* of the given namespace, to allow the
619 original module's __dict__ to be cleared and reused.
619 original module's __dict__ to be cleared and reused.
620
620
621
621
622 Parameters
622 Parameters
623 ----------
623 ----------
624 ns : a namespace (a dict, typically)
624 ns : a namespace (a dict, typically)
625
625
626 fname : str
626 fname : str
627 Filename associated with the namespace.
627 Filename associated with the namespace.
628
628
629 Examples
629 Examples
630 --------
630 --------
631
631
632 In [10]: import IPython
632 In [10]: import IPython
633
633
634 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
634 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
635
635
636 In [12]: IPython.__file__ in _ip._main_ns_cache
636 In [12]: IPython.__file__ in _ip._main_ns_cache
637 Out[12]: True
637 Out[12]: True
638 """
638 """
639 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
639 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
640
640
641 def clear_main_mod_cache(self):
641 def clear_main_mod_cache(self):
642 """Clear the cache of main modules.
642 """Clear the cache of main modules.
643
643
644 Mainly for use by utilities like %reset.
644 Mainly for use by utilities like %reset.
645
645
646 Examples
646 Examples
647 --------
647 --------
648
648
649 In [15]: import IPython
649 In [15]: import IPython
650
650
651 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
651 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
652
652
653 In [17]: len(_ip._main_ns_cache) > 0
653 In [17]: len(_ip._main_ns_cache) > 0
654 Out[17]: True
654 Out[17]: True
655
655
656 In [18]: _ip.clear_main_mod_cache()
656 In [18]: _ip.clear_main_mod_cache()
657
657
658 In [19]: len(_ip._main_ns_cache) == 0
658 In [19]: len(_ip._main_ns_cache) == 0
659 Out[19]: True
659 Out[19]: True
660 """
660 """
661 self._main_ns_cache.clear()
661 self._main_ns_cache.clear()
662
662
663 #-------------------------------------------------------------------------
663 #-------------------------------------------------------------------------
664 # Things related to debugging
664 # Things related to debugging
665 #-------------------------------------------------------------------------
665 #-------------------------------------------------------------------------
666
666
667 def init_pdb(self):
667 def init_pdb(self):
668 # Set calling of pdb on exceptions
668 # Set calling of pdb on exceptions
669 # self.call_pdb is a property
669 # self.call_pdb is a property
670 self.call_pdb = self.pdb
670 self.call_pdb = self.pdb
671
671
672 def _get_call_pdb(self):
672 def _get_call_pdb(self):
673 return self._call_pdb
673 return self._call_pdb
674
674
675 def _set_call_pdb(self,val):
675 def _set_call_pdb(self,val):
676
676
677 if val not in (0,1,False,True):
677 if val not in (0,1,False,True):
678 raise ValueError,'new call_pdb value must be boolean'
678 raise ValueError,'new call_pdb value must be boolean'
679
679
680 # store value in instance
680 # store value in instance
681 self._call_pdb = val
681 self._call_pdb = val
682
682
683 # notify the actual exception handlers
683 # notify the actual exception handlers
684 self.InteractiveTB.call_pdb = val
684 self.InteractiveTB.call_pdb = val
685
685
686 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
686 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
687 'Control auto-activation of pdb at exceptions')
687 'Control auto-activation of pdb at exceptions')
688
688
689 def debugger(self,force=False):
689 def debugger(self,force=False):
690 """Call the pydb/pdb debugger.
690 """Call the pydb/pdb debugger.
691
691
692 Keywords:
692 Keywords:
693
693
694 - force(False): by default, this routine checks the instance call_pdb
694 - force(False): by default, this routine checks the instance call_pdb
695 flag and does not actually invoke the debugger if the flag is false.
695 flag and does not actually invoke the debugger if the flag is false.
696 The 'force' option forces the debugger to activate even if the flag
696 The 'force' option forces the debugger to activate even if the flag
697 is false.
697 is false.
698 """
698 """
699
699
700 if not (force or self.call_pdb):
700 if not (force or self.call_pdb):
701 return
701 return
702
702
703 if not hasattr(sys,'last_traceback'):
703 if not hasattr(sys,'last_traceback'):
704 error('No traceback has been produced, nothing to debug.')
704 error('No traceback has been produced, nothing to debug.')
705 return
705 return
706
706
707 # use pydb if available
707 # use pydb if available
708 if debugger.has_pydb:
708 if debugger.has_pydb:
709 from pydb import pm
709 from pydb import pm
710 else:
710 else:
711 # fallback to our internal debugger
711 # fallback to our internal debugger
712 pm = lambda : self.InteractiveTB.debugger(force=True)
712 pm = lambda : self.InteractiveTB.debugger(force=True)
713 self.history_saving_wrapper(pm)()
713 self.history_saving_wrapper(pm)()
714
714
715 #-------------------------------------------------------------------------
715 #-------------------------------------------------------------------------
716 # Things related to IPython's various namespaces
716 # Things related to IPython's various namespaces
717 #-------------------------------------------------------------------------
717 #-------------------------------------------------------------------------
718
718
719 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
719 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
720 # Create the namespace where the user will operate. user_ns is
720 # Create the namespace where the user will operate. user_ns is
721 # normally the only one used, and it is passed to the exec calls as
721 # normally the only one used, and it is passed to the exec calls as
722 # the locals argument. But we do carry a user_global_ns namespace
722 # the locals argument. But we do carry a user_global_ns namespace
723 # given as the exec 'globals' argument, This is useful in embedding
723 # given as the exec 'globals' argument, This is useful in embedding
724 # situations where the ipython shell opens in a context where the
724 # situations where the ipython shell opens in a context where the
725 # distinction between locals and globals is meaningful. For
725 # distinction between locals and globals is meaningful. For
726 # non-embedded contexts, it is just the same object as the user_ns dict.
726 # non-embedded contexts, it is just the same object as the user_ns dict.
727
727
728 # FIXME. For some strange reason, __builtins__ is showing up at user
728 # FIXME. For some strange reason, __builtins__ is showing up at user
729 # level as a dict instead of a module. This is a manual fix, but I
729 # level as a dict instead of a module. This is a manual fix, but I
730 # should really track down where the problem is coming from. Alex
730 # should really track down where the problem is coming from. Alex
731 # Schmolck reported this problem first.
731 # Schmolck reported this problem first.
732
732
733 # A useful post by Alex Martelli on this topic:
733 # A useful post by Alex Martelli on this topic:
734 # Re: inconsistent value from __builtins__
734 # Re: inconsistent value from __builtins__
735 # Von: Alex Martelli <aleaxit@yahoo.com>
735 # Von: Alex Martelli <aleaxit@yahoo.com>
736 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
736 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
737 # Gruppen: comp.lang.python
737 # Gruppen: comp.lang.python
738
738
739 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
739 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
740 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
740 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
741 # > <type 'dict'>
741 # > <type 'dict'>
742 # > >>> print type(__builtins__)
742 # > >>> print type(__builtins__)
743 # > <type 'module'>
743 # > <type 'module'>
744 # > Is this difference in return value intentional?
744 # > Is this difference in return value intentional?
745
745
746 # Well, it's documented that '__builtins__' can be either a dictionary
746 # Well, it's documented that '__builtins__' can be either a dictionary
747 # or a module, and it's been that way for a long time. Whether it's
747 # or a module, and it's been that way for a long time. Whether it's
748 # intentional (or sensible), I don't know. In any case, the idea is
748 # intentional (or sensible), I don't know. In any case, the idea is
749 # that if you need to access the built-in namespace directly, you
749 # that if you need to access the built-in namespace directly, you
750 # should start with "import __builtin__" (note, no 's') which will
750 # should start with "import __builtin__" (note, no 's') which will
751 # definitely give you a module. Yeah, it's somewhat confusing:-(.
751 # definitely give you a module. Yeah, it's somewhat confusing:-(.
752
752
753 # These routines return properly built dicts as needed by the rest of
753 # These routines return properly built dicts as needed by the rest of
754 # the code, and can also be used by extension writers to generate
754 # the code, and can also be used by extension writers to generate
755 # properly initialized namespaces.
755 # properly initialized namespaces.
756 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
756 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
757 user_global_ns)
757 user_global_ns)
758
758
759 # Assign namespaces
759 # Assign namespaces
760 # This is the namespace where all normal user variables live
760 # This is the namespace where all normal user variables live
761 self.user_ns = user_ns
761 self.user_ns = user_ns
762 self.user_global_ns = user_global_ns
762 self.user_global_ns = user_global_ns
763
763
764 # An auxiliary namespace that checks what parts of the user_ns were
764 # An auxiliary namespace that checks what parts of the user_ns were
765 # loaded at startup, so we can list later only variables defined in
765 # loaded at startup, so we can list later only variables defined in
766 # actual interactive use. Since it is always a subset of user_ns, it
766 # actual interactive use. Since it is always a subset of user_ns, it
767 # doesn't need to be separately tracked in the ns_table.
767 # doesn't need to be separately tracked in the ns_table.
768 self.user_ns_hidden = {}
768 self.user_ns_hidden = {}
769
769
770 # A namespace to keep track of internal data structures to prevent
770 # A namespace to keep track of internal data structures to prevent
771 # them from cluttering user-visible stuff. Will be updated later
771 # them from cluttering user-visible stuff. Will be updated later
772 self.internal_ns = {}
772 self.internal_ns = {}
773
773
774 # Now that FakeModule produces a real module, we've run into a nasty
774 # Now that FakeModule produces a real module, we've run into a nasty
775 # problem: after script execution (via %run), the module where the user
775 # problem: after script execution (via %run), the module where the user
776 # code ran is deleted. Now that this object is a true module (needed
776 # code ran is deleted. Now that this object is a true module (needed
777 # so docetst and other tools work correctly), the Python module
777 # so docetst and other tools work correctly), the Python module
778 # teardown mechanism runs over it, and sets to None every variable
778 # teardown mechanism runs over it, and sets to None every variable
779 # present in that module. Top-level references to objects from the
779 # present in that module. Top-level references to objects from the
780 # script survive, because the user_ns is updated with them. However,
780 # script survive, because the user_ns is updated with them. However,
781 # calling functions defined in the script that use other things from
781 # calling functions defined in the script that use other things from
782 # the script will fail, because the function's closure had references
782 # the script will fail, because the function's closure had references
783 # to the original objects, which are now all None. So we must protect
783 # to the original objects, which are now all None. So we must protect
784 # these modules from deletion by keeping a cache.
784 # these modules from deletion by keeping a cache.
785 #
785 #
786 # To avoid keeping stale modules around (we only need the one from the
786 # To avoid keeping stale modules around (we only need the one from the
787 # last run), we use a dict keyed with the full path to the script, so
787 # last run), we use a dict keyed with the full path to the script, so
788 # only the last version of the module is held in the cache. Note,
788 # only the last version of the module is held in the cache. Note,
789 # however, that we must cache the module *namespace contents* (their
789 # however, that we must cache the module *namespace contents* (their
790 # __dict__). Because if we try to cache the actual modules, old ones
790 # __dict__). Because if we try to cache the actual modules, old ones
791 # (uncached) could be destroyed while still holding references (such as
791 # (uncached) could be destroyed while still holding references (such as
792 # those held by GUI objects that tend to be long-lived)>
792 # those held by GUI objects that tend to be long-lived)>
793 #
793 #
794 # The %reset command will flush this cache. See the cache_main_mod()
794 # The %reset command will flush this cache. See the cache_main_mod()
795 # and clear_main_mod_cache() methods for details on use.
795 # and clear_main_mod_cache() methods for details on use.
796
796
797 # This is the cache used for 'main' namespaces
797 # This is the cache used for 'main' namespaces
798 self._main_ns_cache = {}
798 self._main_ns_cache = {}
799 # And this is the single instance of FakeModule whose __dict__ we keep
799 # And this is the single instance of FakeModule whose __dict__ we keep
800 # copying and clearing for reuse on each %run
800 # copying and clearing for reuse on each %run
801 self._user_main_module = FakeModule()
801 self._user_main_module = FakeModule()
802
802
803 # A table holding all the namespaces IPython deals with, so that
803 # A table holding all the namespaces IPython deals with, so that
804 # introspection facilities can search easily.
804 # introspection facilities can search easily.
805 self.ns_table = {'user':user_ns,
805 self.ns_table = {'user':user_ns,
806 'user_global':user_global_ns,
806 'user_global':user_global_ns,
807 'internal':self.internal_ns,
807 'internal':self.internal_ns,
808 'builtin':__builtin__.__dict__
808 'builtin':__builtin__.__dict__
809 }
809 }
810
810
811 # Similarly, track all namespaces where references can be held and that
811 # Similarly, track all namespaces where references can be held and that
812 # we can safely clear (so it can NOT include builtin). This one can be
812 # we can safely clear (so it can NOT include builtin). This one can be
813 # a simple list.
813 # a simple list.
814 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
814 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
815 self.internal_ns, self._main_ns_cache ]
815 self.internal_ns, self._main_ns_cache ]
816
816
817 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
817 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
818 """Return a valid local and global user interactive namespaces.
818 """Return a valid local and global user interactive namespaces.
819
819
820 This builds a dict with the minimal information needed to operate as a
820 This builds a dict with the minimal information needed to operate as a
821 valid IPython user namespace, which you can pass to the various
821 valid IPython user namespace, which you can pass to the various
822 embedding classes in ipython. The default implementation returns the
822 embedding classes in ipython. The default implementation returns the
823 same dict for both the locals and the globals to allow functions to
823 same dict for both the locals and the globals to allow functions to
824 refer to variables in the namespace. Customized implementations can
824 refer to variables in the namespace. Customized implementations can
825 return different dicts. The locals dictionary can actually be anything
825 return different dicts. The locals dictionary can actually be anything
826 following the basic mapping protocol of a dict, but the globals dict
826 following the basic mapping protocol of a dict, but the globals dict
827 must be a true dict, not even a subclass. It is recommended that any
827 must be a true dict, not even a subclass. It is recommended that any
828 custom object for the locals namespace synchronize with the globals
828 custom object for the locals namespace synchronize with the globals
829 dict somehow.
829 dict somehow.
830
830
831 Raises TypeError if the provided globals namespace is not a true dict.
831 Raises TypeError if the provided globals namespace is not a true dict.
832
832
833 Parameters
833 Parameters
834 ----------
834 ----------
835 user_ns : dict-like, optional
835 user_ns : dict-like, optional
836 The current user namespace. The items in this namespace should
836 The current user namespace. The items in this namespace should
837 be included in the output. If None, an appropriate blank
837 be included in the output. If None, an appropriate blank
838 namespace should be created.
838 namespace should be created.
839 user_global_ns : dict, optional
839 user_global_ns : dict, optional
840 The current user global namespace. The items in this namespace
840 The current user global namespace. The items in this namespace
841 should be included in the output. If None, an appropriate
841 should be included in the output. If None, an appropriate
842 blank namespace should be created.
842 blank namespace should be created.
843
843
844 Returns
844 Returns
845 -------
845 -------
846 A pair of dictionary-like object to be used as the local namespace
846 A pair of dictionary-like object to be used as the local namespace
847 of the interpreter and a dict to be used as the global namespace.
847 of the interpreter and a dict to be used as the global namespace.
848 """
848 """
849
849
850
850
851 # We must ensure that __builtin__ (without the final 's') is always
851 # We must ensure that __builtin__ (without the final 's') is always
852 # available and pointing to the __builtin__ *module*. For more details:
852 # available and pointing to the __builtin__ *module*. For more details:
853 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
853 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
854
854
855 if user_ns is None:
855 if user_ns is None:
856 # Set __name__ to __main__ to better match the behavior of the
856 # Set __name__ to __main__ to better match the behavior of the
857 # normal interpreter.
857 # normal interpreter.
858 user_ns = {'__name__' :'__main__',
858 user_ns = {'__name__' :'__main__',
859 '__builtin__' : __builtin__,
859 '__builtin__' : __builtin__,
860 '__builtins__' : __builtin__,
860 '__builtins__' : __builtin__,
861 }
861 }
862 else:
862 else:
863 user_ns.setdefault('__name__','__main__')
863 user_ns.setdefault('__name__','__main__')
864 user_ns.setdefault('__builtin__',__builtin__)
864 user_ns.setdefault('__builtin__',__builtin__)
865 user_ns.setdefault('__builtins__',__builtin__)
865 user_ns.setdefault('__builtins__',__builtin__)
866
866
867 if user_global_ns is None:
867 if user_global_ns is None:
868 user_global_ns = user_ns
868 user_global_ns = user_ns
869 if type(user_global_ns) is not dict:
869 if type(user_global_ns) is not dict:
870 raise TypeError("user_global_ns must be a true dict; got %r"
870 raise TypeError("user_global_ns must be a true dict; got %r"
871 % type(user_global_ns))
871 % type(user_global_ns))
872
872
873 return user_ns, user_global_ns
873 return user_ns, user_global_ns
874
874
875 def init_sys_modules(self):
875 def init_sys_modules(self):
876 # We need to insert into sys.modules something that looks like a
876 # We need to insert into sys.modules something that looks like a
877 # module but which accesses the IPython namespace, for shelve and
877 # module but which accesses the IPython namespace, for shelve and
878 # pickle to work interactively. Normally they rely on getting
878 # pickle to work interactively. Normally they rely on getting
879 # everything out of __main__, but for embedding purposes each IPython
879 # everything out of __main__, but for embedding purposes each IPython
880 # instance has its own private namespace, so we can't go shoving
880 # instance has its own private namespace, so we can't go shoving
881 # everything into __main__.
881 # everything into __main__.
882
882
883 # note, however, that we should only do this for non-embedded
883 # note, however, that we should only do this for non-embedded
884 # ipythons, which really mimic the __main__.__dict__ with their own
884 # ipythons, which really mimic the __main__.__dict__ with their own
885 # namespace. Embedded instances, on the other hand, should not do
885 # namespace. Embedded instances, on the other hand, should not do
886 # this because they need to manage the user local/global namespaces
886 # this because they need to manage the user local/global namespaces
887 # only, but they live within a 'normal' __main__ (meaning, they
887 # only, but they live within a 'normal' __main__ (meaning, they
888 # shouldn't overtake the execution environment of the script they're
888 # shouldn't overtake the execution environment of the script they're
889 # embedded in).
889 # embedded in).
890
890
891 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
891 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
892
892
893 try:
893 try:
894 main_name = self.user_ns['__name__']
894 main_name = self.user_ns['__name__']
895 except KeyError:
895 except KeyError:
896 raise KeyError('user_ns dictionary MUST have a "__name__" key')
896 raise KeyError('user_ns dictionary MUST have a "__name__" key')
897 else:
897 else:
898 sys.modules[main_name] = FakeModule(self.user_ns)
898 sys.modules[main_name] = FakeModule(self.user_ns)
899
899
900 def init_user_ns(self):
900 def init_user_ns(self):
901 """Initialize all user-visible namespaces to their minimum defaults.
901 """Initialize all user-visible namespaces to their minimum defaults.
902
902
903 Certain history lists are also initialized here, as they effectively
903 Certain history lists are also initialized here, as they effectively
904 act as user namespaces.
904 act as user namespaces.
905
905
906 Notes
906 Notes
907 -----
907 -----
908 All data structures here are only filled in, they are NOT reset by this
908 All data structures here are only filled in, they are NOT reset by this
909 method. If they were not empty before, data will simply be added to
909 method. If they were not empty before, data will simply be added to
910 therm.
910 therm.
911 """
911 """
912 # This function works in two parts: first we put a few things in
912 # This function works in two parts: first we put a few things in
913 # user_ns, and we sync that contents into user_ns_hidden so that these
913 # user_ns, and we sync that contents into user_ns_hidden so that these
914 # initial variables aren't shown by %who. After the sync, we add the
914 # initial variables aren't shown by %who. After the sync, we add the
915 # rest of what we *do* want the user to see with %who even on a new
915 # rest of what we *do* want the user to see with %who even on a new
916 # session (probably nothing, so theye really only see their own stuff)
916 # session (probably nothing, so theye really only see their own stuff)
917
917
918 # The user dict must *always* have a __builtin__ reference to the
918 # The user dict must *always* have a __builtin__ reference to the
919 # Python standard __builtin__ namespace, which must be imported.
919 # Python standard __builtin__ namespace, which must be imported.
920 # This is so that certain operations in prompt evaluation can be
920 # This is so that certain operations in prompt evaluation can be
921 # reliably executed with builtins. Note that we can NOT use
921 # reliably executed with builtins. Note that we can NOT use
922 # __builtins__ (note the 's'), because that can either be a dict or a
922 # __builtins__ (note the 's'), because that can either be a dict or a
923 # module, and can even mutate at runtime, depending on the context
923 # module, and can even mutate at runtime, depending on the context
924 # (Python makes no guarantees on it). In contrast, __builtin__ is
924 # (Python makes no guarantees on it). In contrast, __builtin__ is
925 # always a module object, though it must be explicitly imported.
925 # always a module object, though it must be explicitly imported.
926
926
927 # For more details:
927 # For more details:
928 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
928 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
929 ns = dict(__builtin__ = __builtin__)
929 ns = dict(__builtin__ = __builtin__)
930
930
931 # Put 'help' in the user namespace
931 # Put 'help' in the user namespace
932 try:
932 try:
933 from site import _Helper
933 from site import _Helper
934 ns['help'] = _Helper()
934 ns['help'] = _Helper()
935 except ImportError:
935 except ImportError:
936 warn('help() not available - check site.py')
936 warn('help() not available - check site.py')
937
937
938 # make global variables for user access to the histories
938 # make global variables for user access to the histories
939 ns['_ih'] = self.input_hist
939 ns['_ih'] = self.input_hist
940 ns['_oh'] = self.output_hist
940 ns['_oh'] = self.output_hist
941 ns['_dh'] = self.dir_hist
941 ns['_dh'] = self.dir_hist
942
942
943 ns['_sh'] = shadowns
943 ns['_sh'] = shadowns
944
944
945 # user aliases to input and output histories. These shouldn't show up
945 # user aliases to input and output histories. These shouldn't show up
946 # in %who, as they can have very large reprs.
946 # in %who, as they can have very large reprs.
947 ns['In'] = self.input_hist
947 ns['In'] = self.input_hist
948 ns['Out'] = self.output_hist
948 ns['Out'] = self.output_hist
949
949
950 # Store myself as the public api!!!
950 # Store myself as the public api!!!
951 ns['get_ipython'] = self.get_ipython
951 ns['get_ipython'] = self.get_ipython
952
952
953 # Sync what we've added so far to user_ns_hidden so these aren't seen
953 # Sync what we've added so far to user_ns_hidden so these aren't seen
954 # by %who
954 # by %who
955 self.user_ns_hidden.update(ns)
955 self.user_ns_hidden.update(ns)
956
956
957 # Anything put into ns now would show up in %who. Think twice before
957 # Anything put into ns now would show up in %who. Think twice before
958 # putting anything here, as we really want %who to show the user their
958 # putting anything here, as we really want %who to show the user their
959 # stuff, not our variables.
959 # stuff, not our variables.
960
960
961 # Finally, update the real user's namespace
961 # Finally, update the real user's namespace
962 self.user_ns.update(ns)
962 self.user_ns.update(ns)
963
963
964
964
965 def reset(self):
965 def reset(self):
966 """Clear all internal namespaces.
966 """Clear all internal namespaces.
967
967
968 Note that this is much more aggressive than %reset, since it clears
968 Note that this is much more aggressive than %reset, since it clears
969 fully all namespaces, as well as all input/output lists.
969 fully all namespaces, as well as all input/output lists.
970 """
970 """
971 for ns in self.ns_refs_table:
971 for ns in self.ns_refs_table:
972 ns.clear()
972 ns.clear()
973
973
974 self.alias_manager.clear_aliases()
974 self.alias_manager.clear_aliases()
975
975
976 # Clear input and output histories
976 # Clear input and output histories
977 self.input_hist[:] = []
977 self.input_hist[:] = []
978 self.input_hist_raw[:] = []
978 self.input_hist_raw[:] = []
979 self.output_hist.clear()
979 self.output_hist.clear()
980
980
981 # Restore the user namespaces to minimal usability
981 # Restore the user namespaces to minimal usability
982 self.init_user_ns()
982 self.init_user_ns()
983
983
984 # Restore the default and user aliases
984 # Restore the default and user aliases
985 self.alias_manager.init_aliases()
985 self.alias_manager.init_aliases()
986
986
987 def reset_selective(self, regex=None):
987 def reset_selective(self, regex=None):
988 """Clear selective variables from internal namespaces based on a
988 """Clear selective variables from internal namespaces based on a
989 specified regular expression.
989 specified regular expression.
990
990
991 Parameters
991 Parameters
992 ----------
992 ----------
993 regex : string or compiled pattern, optional
993 regex : string or compiled pattern, optional
994 A regular expression pattern that will be used in searching
994 A regular expression pattern that will be used in searching
995 variable names in the users namespaces.
995 variable names in the users namespaces.
996 """
996 """
997 if regex is not None:
997 if regex is not None:
998 try:
998 try:
999 m = re.compile(regex)
999 m = re.compile(regex)
1000 except TypeError:
1000 except TypeError:
1001 raise TypeError('regex must be a string or compiled pattern')
1001 raise TypeError('regex must be a string or compiled pattern')
1002 # Search for keys in each namespace that match the given regex
1002 # Search for keys in each namespace that match the given regex
1003 # If a match is found, delete the key/value pair.
1003 # If a match is found, delete the key/value pair.
1004 for ns in self.ns_refs_table:
1004 for ns in self.ns_refs_table:
1005 for var in ns:
1005 for var in ns:
1006 if m.search(var):
1006 if m.search(var):
1007 del ns[var]
1007 del ns[var]
1008
1008
1009 def push(self, variables, interactive=True):
1009 def push(self, variables, interactive=True):
1010 """Inject a group of variables into the IPython user namespace.
1010 """Inject a group of variables into the IPython user namespace.
1011
1011
1012 Parameters
1012 Parameters
1013 ----------
1013 ----------
1014 variables : dict, str or list/tuple of str
1014 variables : dict, str or list/tuple of str
1015 The variables to inject into the user's namespace. If a dict, a
1015 The variables to inject into the user's namespace. If a dict, a
1016 simple update is done. If a str, the string is assumed to have
1016 simple update is done. If a str, the string is assumed to have
1017 variable names separated by spaces. A list/tuple of str can also
1017 variable names separated by spaces. A list/tuple of str can also
1018 be used to give the variable names. If just the variable names are
1018 be used to give the variable names. If just the variable names are
1019 give (list/tuple/str) then the variable values looked up in the
1019 give (list/tuple/str) then the variable values looked up in the
1020 callers frame.
1020 callers frame.
1021 interactive : bool
1021 interactive : bool
1022 If True (default), the variables will be listed with the ``who``
1022 If True (default), the variables will be listed with the ``who``
1023 magic.
1023 magic.
1024 """
1024 """
1025 vdict = None
1025 vdict = None
1026
1026
1027 # We need a dict of name/value pairs to do namespace updates.
1027 # We need a dict of name/value pairs to do namespace updates.
1028 if isinstance(variables, dict):
1028 if isinstance(variables, dict):
1029 vdict = variables
1029 vdict = variables
1030 elif isinstance(variables, (basestring, list, tuple)):
1030 elif isinstance(variables, (basestring, list, tuple)):
1031 if isinstance(variables, basestring):
1031 if isinstance(variables, basestring):
1032 vlist = variables.split()
1032 vlist = variables.split()
1033 else:
1033 else:
1034 vlist = variables
1034 vlist = variables
1035 vdict = {}
1035 vdict = {}
1036 cf = sys._getframe(1)
1036 cf = sys._getframe(1)
1037 for name in vlist:
1037 for name in vlist:
1038 try:
1038 try:
1039 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1039 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1040 except:
1040 except:
1041 print ('Could not get variable %s from %s' %
1041 print ('Could not get variable %s from %s' %
1042 (name,cf.f_code.co_name))
1042 (name,cf.f_code.co_name))
1043 else:
1043 else:
1044 raise ValueError('variables must be a dict/str/list/tuple')
1044 raise ValueError('variables must be a dict/str/list/tuple')
1045
1045
1046 # Propagate variables to user namespace
1046 # Propagate variables to user namespace
1047 self.user_ns.update(vdict)
1047 self.user_ns.update(vdict)
1048
1048
1049 # And configure interactive visibility
1049 # And configure interactive visibility
1050 config_ns = self.user_ns_hidden
1050 config_ns = self.user_ns_hidden
1051 if interactive:
1051 if interactive:
1052 for name, val in vdict.iteritems():
1052 for name, val in vdict.iteritems():
1053 config_ns.pop(name, None)
1053 config_ns.pop(name, None)
1054 else:
1054 else:
1055 for name,val in vdict.iteritems():
1055 for name,val in vdict.iteritems():
1056 config_ns[name] = val
1056 config_ns[name] = val
1057
1057
1058 #-------------------------------------------------------------------------
1058 #-------------------------------------------------------------------------
1059 # Things related to object introspection
1059 # Things related to object introspection
1060 #-------------------------------------------------------------------------
1060 #-------------------------------------------------------------------------
1061
1061
1062 def _ofind(self, oname, namespaces=None):
1062 def _ofind(self, oname, namespaces=None):
1063 """Find an object in the available namespaces.
1063 """Find an object in the available namespaces.
1064
1064
1065 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1065 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1066
1066
1067 Has special code to detect magic functions.
1067 Has special code to detect magic functions.
1068 """
1068 """
1069 #oname = oname.strip()
1069 #oname = oname.strip()
1070 #print '1- oname: <%r>' % oname # dbg
1070 #print '1- oname: <%r>' % oname # dbg
1071 try:
1071 try:
1072 oname = oname.strip().encode('ascii')
1072 oname = oname.strip().encode('ascii')
1073 #print '2- oname: <%r>' % oname # dbg
1073 #print '2- oname: <%r>' % oname # dbg
1074 except UnicodeEncodeError:
1074 except UnicodeEncodeError:
1075 print 'Python identifiers can only contain ascii characters.'
1075 print 'Python identifiers can only contain ascii characters.'
1076 return dict(found=False)
1076 return dict(found=False)
1077
1077
1078 alias_ns = None
1078 alias_ns = None
1079 if namespaces is None:
1079 if namespaces is None:
1080 # Namespaces to search in:
1080 # Namespaces to search in:
1081 # Put them in a list. The order is important so that we
1081 # Put them in a list. The order is important so that we
1082 # find things in the same order that Python finds them.
1082 # find things in the same order that Python finds them.
1083 namespaces = [ ('Interactive', self.user_ns),
1083 namespaces = [ ('Interactive', self.user_ns),
1084 ('IPython internal', self.internal_ns),
1084 ('IPython internal', self.internal_ns),
1085 ('Python builtin', __builtin__.__dict__),
1085 ('Python builtin', __builtin__.__dict__),
1086 ('Alias', self.alias_manager.alias_table),
1086 ('Alias', self.alias_manager.alias_table),
1087 ]
1087 ]
1088 alias_ns = self.alias_manager.alias_table
1088 alias_ns = self.alias_manager.alias_table
1089
1089
1090 # initialize results to 'null'
1090 # initialize results to 'null'
1091 found = False; obj = None; ospace = None; ds = None;
1091 found = False; obj = None; ospace = None; ds = None;
1092 ismagic = False; isalias = False; parent = None
1092 ismagic = False; isalias = False; parent = None
1093
1093
1094 # We need to special-case 'print', which as of python2.6 registers as a
1094 # We need to special-case 'print', which as of python2.6 registers as a
1095 # function but should only be treated as one if print_function was
1095 # function but should only be treated as one if print_function was
1096 # loaded with a future import. In this case, just bail.
1096 # loaded with a future import. In this case, just bail.
1097 if (oname == 'print' and not (self.compile.compiler.flags &
1097 if (oname == 'print' and not (self.compile.compiler.flags &
1098 __future__.CO_FUTURE_PRINT_FUNCTION)):
1098 __future__.CO_FUTURE_PRINT_FUNCTION)):
1099 return {'found':found, 'obj':obj, 'namespace':ospace,
1099 return {'found':found, 'obj':obj, 'namespace':ospace,
1100 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1100 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1101
1101
1102 # Look for the given name by splitting it in parts. If the head is
1102 # Look for the given name by splitting it in parts. If the head is
1103 # found, then we look for all the remaining parts as members, and only
1103 # found, then we look for all the remaining parts as members, and only
1104 # declare success if we can find them all.
1104 # declare success if we can find them all.
1105 oname_parts = oname.split('.')
1105 oname_parts = oname.split('.')
1106 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1106 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1107 for nsname,ns in namespaces:
1107 for nsname,ns in namespaces:
1108 try:
1108 try:
1109 obj = ns[oname_head]
1109 obj = ns[oname_head]
1110 except KeyError:
1110 except KeyError:
1111 continue
1111 continue
1112 else:
1112 else:
1113 #print 'oname_rest:', oname_rest # dbg
1113 #print 'oname_rest:', oname_rest # dbg
1114 for part in oname_rest:
1114 for part in oname_rest:
1115 try:
1115 try:
1116 parent = obj
1116 parent = obj
1117 obj = getattr(obj,part)
1117 obj = getattr(obj,part)
1118 except:
1118 except:
1119 # Blanket except b/c some badly implemented objects
1119 # Blanket except b/c some badly implemented objects
1120 # allow __getattr__ to raise exceptions other than
1120 # allow __getattr__ to raise exceptions other than
1121 # AttributeError, which then crashes IPython.
1121 # AttributeError, which then crashes IPython.
1122 break
1122 break
1123 else:
1123 else:
1124 # If we finish the for loop (no break), we got all members
1124 # If we finish the for loop (no break), we got all members
1125 found = True
1125 found = True
1126 ospace = nsname
1126 ospace = nsname
1127 if ns == alias_ns:
1127 if ns == alias_ns:
1128 isalias = True
1128 isalias = True
1129 break # namespace loop
1129 break # namespace loop
1130
1130
1131 # Try to see if it's magic
1131 # Try to see if it's magic
1132 if not found:
1132 if not found:
1133 if oname.startswith(ESC_MAGIC):
1133 if oname.startswith(ESC_MAGIC):
1134 oname = oname[1:]
1134 oname = oname[1:]
1135 obj = getattr(self,'magic_'+oname,None)
1135 obj = getattr(self,'magic_'+oname,None)
1136 if obj is not None:
1136 if obj is not None:
1137 found = True
1137 found = True
1138 ospace = 'IPython internal'
1138 ospace = 'IPython internal'
1139 ismagic = True
1139 ismagic = True
1140
1140
1141 # Last try: special-case some literals like '', [], {}, etc:
1141 # Last try: special-case some literals like '', [], {}, etc:
1142 if not found and oname_head in ["''",'""','[]','{}','()']:
1142 if not found and oname_head in ["''",'""','[]','{}','()']:
1143 obj = eval(oname_head)
1143 obj = eval(oname_head)
1144 found = True
1144 found = True
1145 ospace = 'Interactive'
1145 ospace = 'Interactive'
1146
1146
1147 return {'found':found, 'obj':obj, 'namespace':ospace,
1147 return {'found':found, 'obj':obj, 'namespace':ospace,
1148 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1148 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1149
1149
1150 def _ofind_property(self, oname, info):
1150 def _ofind_property(self, oname, info):
1151 """Second part of object finding, to look for property details."""
1151 """Second part of object finding, to look for property details."""
1152 if info.found:
1152 if info.found:
1153 # Get the docstring of the class property if it exists.
1153 # Get the docstring of the class property if it exists.
1154 path = oname.split('.')
1154 path = oname.split('.')
1155 root = '.'.join(path[:-1])
1155 root = '.'.join(path[:-1])
1156 if info.parent is not None:
1156 if info.parent is not None:
1157 try:
1157 try:
1158 target = getattr(info.parent, '__class__')
1158 target = getattr(info.parent, '__class__')
1159 # The object belongs to a class instance.
1159 # The object belongs to a class instance.
1160 try:
1160 try:
1161 target = getattr(target, path[-1])
1161 target = getattr(target, path[-1])
1162 # The class defines the object.
1162 # The class defines the object.
1163 if isinstance(target, property):
1163 if isinstance(target, property):
1164 oname = root + '.__class__.' + path[-1]
1164 oname = root + '.__class__.' + path[-1]
1165 info = Struct(self._ofind(oname))
1165 info = Struct(self._ofind(oname))
1166 except AttributeError: pass
1166 except AttributeError: pass
1167 except AttributeError: pass
1167 except AttributeError: pass
1168
1168
1169 # We return either the new info or the unmodified input if the object
1169 # We return either the new info or the unmodified input if the object
1170 # hadn't been found
1170 # hadn't been found
1171 return info
1171 return info
1172
1172
1173 def _object_find(self, oname, namespaces=None):
1173 def _object_find(self, oname, namespaces=None):
1174 """Find an object and return a struct with info about it."""
1174 """Find an object and return a struct with info about it."""
1175 inf = Struct(self._ofind(oname, namespaces))
1175 inf = Struct(self._ofind(oname, namespaces))
1176 return Struct(self._ofind_property(oname, inf))
1176 return Struct(self._ofind_property(oname, inf))
1177
1177
1178 def _inspect(self, meth, oname, namespaces=None, **kw):
1178 def _inspect(self, meth, oname, namespaces=None, **kw):
1179 """Generic interface to the inspector system.
1179 """Generic interface to the inspector system.
1180
1180
1181 This function is meant to be called by pdef, pdoc & friends."""
1181 This function is meant to be called by pdef, pdoc & friends."""
1182 info = self._object_find(oname)
1182 info = self._object_find(oname)
1183 if info.found:
1183 if info.found:
1184 pmethod = getattr(self.inspector, meth)
1184 pmethod = getattr(self.inspector, meth)
1185 formatter = format_screen if info.ismagic else None
1185 formatter = format_screen if info.ismagic else None
1186 if meth == 'pdoc':
1186 if meth == 'pdoc':
1187 pmethod(info.obj, oname, formatter)
1187 pmethod(info.obj, oname, formatter)
1188 elif meth == 'pinfo':
1188 elif meth == 'pinfo':
1189 pmethod(info.obj, oname, formatter, info, **kw)
1189 pmethod(info.obj, oname, formatter, info, **kw)
1190 else:
1190 else:
1191 pmethod(info.obj, oname)
1191 pmethod(info.obj, oname)
1192 else:
1192 else:
1193 print 'Object `%s` not found.' % oname
1193 print 'Object `%s` not found.' % oname
1194 return 'not found' # so callers can take other action
1194 return 'not found' # so callers can take other action
1195
1195
1196 def object_inspect(self, oname):
1196 def object_inspect(self, oname):
1197 info = self._object_find(oname)
1197 info = self._object_find(oname)
1198 if info.found:
1198 if info.found:
1199 return self.inspector.info(info.obj, info=info)
1199 return self.inspector.info(info.obj, oname, info=info)
1200 else:
1200 else:
1201 return oinspect.mk_object_info({'found' : False})
1201 return oinspect.mk_object_info({'name' : oname,
1202 'found' : False})
1202
1203
1203 #-------------------------------------------------------------------------
1204 #-------------------------------------------------------------------------
1204 # Things related to history management
1205 # Things related to history management
1205 #-------------------------------------------------------------------------
1206 #-------------------------------------------------------------------------
1206
1207
1207 def init_history(self):
1208 def init_history(self):
1208 # List of input with multi-line handling.
1209 # List of input with multi-line handling.
1209 self.input_hist = InputList()
1210 self.input_hist = InputList()
1210 # This one will hold the 'raw' input history, without any
1211 # This one will hold the 'raw' input history, without any
1211 # pre-processing. This will allow users to retrieve the input just as
1212 # pre-processing. This will allow users to retrieve the input just as
1212 # it was exactly typed in by the user, with %hist -r.
1213 # it was exactly typed in by the user, with %hist -r.
1213 self.input_hist_raw = InputList()
1214 self.input_hist_raw = InputList()
1214
1215
1215 # list of visited directories
1216 # list of visited directories
1216 try:
1217 try:
1217 self.dir_hist = [os.getcwd()]
1218 self.dir_hist = [os.getcwd()]
1218 except OSError:
1219 except OSError:
1219 self.dir_hist = []
1220 self.dir_hist = []
1220
1221
1221 # dict of output history
1222 # dict of output history
1222 self.output_hist = {}
1223 self.output_hist = {}
1223
1224
1224 # Now the history file
1225 # Now the history file
1225 if self.profile:
1226 if self.profile:
1226 histfname = 'history-%s' % self.profile
1227 histfname = 'history-%s' % self.profile
1227 else:
1228 else:
1228 histfname = 'history'
1229 histfname = 'history'
1229 self.histfile = os.path.join(self.ipython_dir, histfname)
1230 self.histfile = os.path.join(self.ipython_dir, histfname)
1230
1231
1231 # Fill the history zero entry, user counter starts at 1
1232 # Fill the history zero entry, user counter starts at 1
1232 self.input_hist.append('\n')
1233 self.input_hist.append('\n')
1233 self.input_hist_raw.append('\n')
1234 self.input_hist_raw.append('\n')
1234
1235
1235 def init_shadow_hist(self):
1236 def init_shadow_hist(self):
1236 try:
1237 try:
1237 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1238 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1238 except exceptions.UnicodeDecodeError:
1239 except exceptions.UnicodeDecodeError:
1239 print "Your ipython_dir can't be decoded to unicode!"
1240 print "Your ipython_dir can't be decoded to unicode!"
1240 print "Please set HOME environment variable to something that"
1241 print "Please set HOME environment variable to something that"
1241 print r"only has ASCII characters, e.g. c:\home"
1242 print r"only has ASCII characters, e.g. c:\home"
1242 print "Now it is", self.ipython_dir
1243 print "Now it is", self.ipython_dir
1243 sys.exit()
1244 sys.exit()
1244 self.shadowhist = ipcorehist.ShadowHist(self.db)
1245 self.shadowhist = ipcorehist.ShadowHist(self.db)
1245
1246
1246 def savehist(self):
1247 def savehist(self):
1247 """Save input history to a file (via readline library)."""
1248 """Save input history to a file (via readline library)."""
1248
1249
1249 try:
1250 try:
1250 self.readline.write_history_file(self.histfile)
1251 self.readline.write_history_file(self.histfile)
1251 except:
1252 except:
1252 print 'Unable to save IPython command history to file: ' + \
1253 print 'Unable to save IPython command history to file: ' + \
1253 `self.histfile`
1254 `self.histfile`
1254
1255
1255 def reloadhist(self):
1256 def reloadhist(self):
1256 """Reload the input history from disk file."""
1257 """Reload the input history from disk file."""
1257
1258
1258 try:
1259 try:
1259 self.readline.clear_history()
1260 self.readline.clear_history()
1260 self.readline.read_history_file(self.shell.histfile)
1261 self.readline.read_history_file(self.shell.histfile)
1261 except AttributeError:
1262 except AttributeError:
1262 pass
1263 pass
1263
1264
1264 def history_saving_wrapper(self, func):
1265 def history_saving_wrapper(self, func):
1265 """ Wrap func for readline history saving
1266 """ Wrap func for readline history saving
1266
1267
1267 Convert func into callable that saves & restores
1268 Convert func into callable that saves & restores
1268 history around the call """
1269 history around the call """
1269
1270
1270 if self.has_readline:
1271 if self.has_readline:
1271 from IPython.utils import rlineimpl as readline
1272 from IPython.utils import rlineimpl as readline
1272 else:
1273 else:
1273 return func
1274 return func
1274
1275
1275 def wrapper():
1276 def wrapper():
1276 self.savehist()
1277 self.savehist()
1277 try:
1278 try:
1278 func()
1279 func()
1279 finally:
1280 finally:
1280 readline.read_history_file(self.histfile)
1281 readline.read_history_file(self.histfile)
1281 return wrapper
1282 return wrapper
1282
1283
1283 def get_history(self, index=None, raw=False, output=True):
1284 def get_history(self, index=None, raw=False, output=True):
1284 """Get the history list.
1285 """Get the history list.
1285
1286
1286 Get the input and output history.
1287 Get the input and output history.
1287
1288
1288 Parameters
1289 Parameters
1289 ----------
1290 ----------
1290 index : n or (n1, n2) or None
1291 index : n or (n1, n2) or None
1291 If n, then the last entries. If a tuple, then all in
1292 If n, then the last entries. If a tuple, then all in
1292 range(n1, n2). If None, then all entries. Raises IndexError if
1293 range(n1, n2). If None, then all entries. Raises IndexError if
1293 the format of index is incorrect.
1294 the format of index is incorrect.
1294 raw : bool
1295 raw : bool
1295 If True, return the raw input.
1296 If True, return the raw input.
1296 output : bool
1297 output : bool
1297 If True, then return the output as well.
1298 If True, then return the output as well.
1298
1299
1299 Returns
1300 Returns
1300 -------
1301 -------
1301 If output is True, then return a dict of tuples, keyed by the prompt
1302 If output is True, then return a dict of tuples, keyed by the prompt
1302 numbers and with values of (input, output). If output is False, then
1303 numbers and with values of (input, output). If output is False, then
1303 a dict, keyed by the prompt number with the values of input. Raises
1304 a dict, keyed by the prompt number with the values of input. Raises
1304 IndexError if no history is found.
1305 IndexError if no history is found.
1305 """
1306 """
1306 if raw:
1307 if raw:
1307 input_hist = self.input_hist_raw
1308 input_hist = self.input_hist_raw
1308 else:
1309 else:
1309 input_hist = self.input_hist
1310 input_hist = self.input_hist
1310 if output:
1311 if output:
1311 output_hist = self.user_ns['Out']
1312 output_hist = self.user_ns['Out']
1312 n = len(input_hist)
1313 n = len(input_hist)
1313 if index is None:
1314 if index is None:
1314 start=0; stop=n
1315 start=0; stop=n
1315 elif isinstance(index, int):
1316 elif isinstance(index, int):
1316 start=n-index; stop=n
1317 start=n-index; stop=n
1317 elif isinstance(index, tuple) and len(index) == 2:
1318 elif isinstance(index, tuple) and len(index) == 2:
1318 start=index[0]; stop=index[1]
1319 start=index[0]; stop=index[1]
1319 else:
1320 else:
1320 raise IndexError('Not a valid index for the input history: %r'
1321 raise IndexError('Not a valid index for the input history: %r'
1321 % index)
1322 % index)
1322 hist = {}
1323 hist = {}
1323 for i in range(start, stop):
1324 for i in range(start, stop):
1324 if output:
1325 if output:
1325 hist[i] = (input_hist[i], output_hist.get(i))
1326 hist[i] = (input_hist[i], output_hist.get(i))
1326 else:
1327 else:
1327 hist[i] = input_hist[i]
1328 hist[i] = input_hist[i]
1328 if len(hist)==0:
1329 if len(hist)==0:
1329 raise IndexError('No history for range of indices: %r' % index)
1330 raise IndexError('No history for range of indices: %r' % index)
1330 return hist
1331 return hist
1331
1332
1332 #-------------------------------------------------------------------------
1333 #-------------------------------------------------------------------------
1333 # Things related to exception handling and tracebacks (not debugging)
1334 # Things related to exception handling and tracebacks (not debugging)
1334 #-------------------------------------------------------------------------
1335 #-------------------------------------------------------------------------
1335
1336
1336 def init_traceback_handlers(self, custom_exceptions):
1337 def init_traceback_handlers(self, custom_exceptions):
1337 # Syntax error handler.
1338 # Syntax error handler.
1338 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1339 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1339
1340
1340 # The interactive one is initialized with an offset, meaning we always
1341 # The interactive one is initialized with an offset, meaning we always
1341 # want to remove the topmost item in the traceback, which is our own
1342 # want to remove the topmost item in the traceback, which is our own
1342 # internal code. Valid modes: ['Plain','Context','Verbose']
1343 # internal code. Valid modes: ['Plain','Context','Verbose']
1343 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1344 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1344 color_scheme='NoColor',
1345 color_scheme='NoColor',
1345 tb_offset = 1)
1346 tb_offset = 1)
1346
1347
1347 # The instance will store a pointer to the system-wide exception hook,
1348 # The instance will store a pointer to the system-wide exception hook,
1348 # so that runtime code (such as magics) can access it. This is because
1349 # so that runtime code (such as magics) can access it. This is because
1349 # during the read-eval loop, it may get temporarily overwritten.
1350 # during the read-eval loop, it may get temporarily overwritten.
1350 self.sys_excepthook = sys.excepthook
1351 self.sys_excepthook = sys.excepthook
1351
1352
1352 # and add any custom exception handlers the user may have specified
1353 # and add any custom exception handlers the user may have specified
1353 self.set_custom_exc(*custom_exceptions)
1354 self.set_custom_exc(*custom_exceptions)
1354
1355
1355 # Set the exception mode
1356 # Set the exception mode
1356 self.InteractiveTB.set_mode(mode=self.xmode)
1357 self.InteractiveTB.set_mode(mode=self.xmode)
1357
1358
1358 def set_custom_exc(self, exc_tuple, handler):
1359 def set_custom_exc(self, exc_tuple, handler):
1359 """set_custom_exc(exc_tuple,handler)
1360 """set_custom_exc(exc_tuple,handler)
1360
1361
1361 Set a custom exception handler, which will be called if any of the
1362 Set a custom exception handler, which will be called if any of the
1362 exceptions in exc_tuple occur in the mainloop (specifically, in the
1363 exceptions in exc_tuple occur in the mainloop (specifically, in the
1363 runcode() method.
1364 runcode() method.
1364
1365
1365 Inputs:
1366 Inputs:
1366
1367
1367 - exc_tuple: a *tuple* of valid exceptions to call the defined
1368 - exc_tuple: a *tuple* of valid exceptions to call the defined
1368 handler for. It is very important that you use a tuple, and NOT A
1369 handler for. It is very important that you use a tuple, and NOT A
1369 LIST here, because of the way Python's except statement works. If
1370 LIST here, because of the way Python's except statement works. If
1370 you only want to trap a single exception, use a singleton tuple:
1371 you only want to trap a single exception, use a singleton tuple:
1371
1372
1372 exc_tuple == (MyCustomException,)
1373 exc_tuple == (MyCustomException,)
1373
1374
1374 - handler: this must be defined as a function with the following
1375 - handler: this must be defined as a function with the following
1375 basic interface::
1376 basic interface::
1376
1377
1377 def my_handler(self, etype, value, tb, tb_offset=None)
1378 def my_handler(self, etype, value, tb, tb_offset=None)
1378 ...
1379 ...
1379 # The return value must be
1380 # The return value must be
1380 return structured_traceback
1381 return structured_traceback
1381
1382
1382 This will be made into an instance method (via new.instancemethod)
1383 This will be made into an instance method (via new.instancemethod)
1383 of IPython itself, and it will be called if any of the exceptions
1384 of IPython itself, and it will be called if any of the exceptions
1384 listed in the exc_tuple are caught. If the handler is None, an
1385 listed in the exc_tuple are caught. If the handler is None, an
1385 internal basic one is used, which just prints basic info.
1386 internal basic one is used, which just prints basic info.
1386
1387
1387 WARNING: by putting in your own exception handler into IPython's main
1388 WARNING: by putting in your own exception handler into IPython's main
1388 execution loop, you run a very good chance of nasty crashes. This
1389 execution loop, you run a very good chance of nasty crashes. This
1389 facility should only be used if you really know what you are doing."""
1390 facility should only be used if you really know what you are doing."""
1390
1391
1391 assert type(exc_tuple)==type(()) , \
1392 assert type(exc_tuple)==type(()) , \
1392 "The custom exceptions must be given AS A TUPLE."
1393 "The custom exceptions must be given AS A TUPLE."
1393
1394
1394 def dummy_handler(self,etype,value,tb):
1395 def dummy_handler(self,etype,value,tb):
1395 print '*** Simple custom exception handler ***'
1396 print '*** Simple custom exception handler ***'
1396 print 'Exception type :',etype
1397 print 'Exception type :',etype
1397 print 'Exception value:',value
1398 print 'Exception value:',value
1398 print 'Traceback :',tb
1399 print 'Traceback :',tb
1399 print 'Source code :','\n'.join(self.buffer)
1400 print 'Source code :','\n'.join(self.buffer)
1400
1401
1401 if handler is None: handler = dummy_handler
1402 if handler is None: handler = dummy_handler
1402
1403
1403 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1404 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1404 self.custom_exceptions = exc_tuple
1405 self.custom_exceptions = exc_tuple
1405
1406
1406 def excepthook(self, etype, value, tb):
1407 def excepthook(self, etype, value, tb):
1407 """One more defense for GUI apps that call sys.excepthook.
1408 """One more defense for GUI apps that call sys.excepthook.
1408
1409
1409 GUI frameworks like wxPython trap exceptions and call
1410 GUI frameworks like wxPython trap exceptions and call
1410 sys.excepthook themselves. I guess this is a feature that
1411 sys.excepthook themselves. I guess this is a feature that
1411 enables them to keep running after exceptions that would
1412 enables them to keep running after exceptions that would
1412 otherwise kill their mainloop. This is a bother for IPython
1413 otherwise kill their mainloop. This is a bother for IPython
1413 which excepts to catch all of the program exceptions with a try:
1414 which excepts to catch all of the program exceptions with a try:
1414 except: statement.
1415 except: statement.
1415
1416
1416 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1417 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1417 any app directly invokes sys.excepthook, it will look to the user like
1418 any app directly invokes sys.excepthook, it will look to the user like
1418 IPython crashed. In order to work around this, we can disable the
1419 IPython crashed. In order to work around this, we can disable the
1419 CrashHandler and replace it with this excepthook instead, which prints a
1420 CrashHandler and replace it with this excepthook instead, which prints a
1420 regular traceback using our InteractiveTB. In this fashion, apps which
1421 regular traceback using our InteractiveTB. In this fashion, apps which
1421 call sys.excepthook will generate a regular-looking exception from
1422 call sys.excepthook will generate a regular-looking exception from
1422 IPython, and the CrashHandler will only be triggered by real IPython
1423 IPython, and the CrashHandler will only be triggered by real IPython
1423 crashes.
1424 crashes.
1424
1425
1425 This hook should be used sparingly, only in places which are not likely
1426 This hook should be used sparingly, only in places which are not likely
1426 to be true IPython errors.
1427 to be true IPython errors.
1427 """
1428 """
1428 self.showtraceback((etype,value,tb),tb_offset=0)
1429 self.showtraceback((etype,value,tb),tb_offset=0)
1429
1430
1430 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1431 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1431 exception_only=False):
1432 exception_only=False):
1432 """Display the exception that just occurred.
1433 """Display the exception that just occurred.
1433
1434
1434 If nothing is known about the exception, this is the method which
1435 If nothing is known about the exception, this is the method which
1435 should be used throughout the code for presenting user tracebacks,
1436 should be used throughout the code for presenting user tracebacks,
1436 rather than directly invoking the InteractiveTB object.
1437 rather than directly invoking the InteractiveTB object.
1437
1438
1438 A specific showsyntaxerror() also exists, but this method can take
1439 A specific showsyntaxerror() also exists, but this method can take
1439 care of calling it if needed, so unless you are explicitly catching a
1440 care of calling it if needed, so unless you are explicitly catching a
1440 SyntaxError exception, don't try to analyze the stack manually and
1441 SyntaxError exception, don't try to analyze the stack manually and
1441 simply call this method."""
1442 simply call this method."""
1442
1443
1443 try:
1444 try:
1444 if exc_tuple is None:
1445 if exc_tuple is None:
1445 etype, value, tb = sys.exc_info()
1446 etype, value, tb = sys.exc_info()
1446 else:
1447 else:
1447 etype, value, tb = exc_tuple
1448 etype, value, tb = exc_tuple
1448
1449
1449 if etype is None:
1450 if etype is None:
1450 if hasattr(sys, 'last_type'):
1451 if hasattr(sys, 'last_type'):
1451 etype, value, tb = sys.last_type, sys.last_value, \
1452 etype, value, tb = sys.last_type, sys.last_value, \
1452 sys.last_traceback
1453 sys.last_traceback
1453 else:
1454 else:
1454 self.write_err('No traceback available to show.\n')
1455 self.write_err('No traceback available to show.\n')
1455 return
1456 return
1456
1457
1457 if etype is SyntaxError:
1458 if etype is SyntaxError:
1458 # Though this won't be called by syntax errors in the input
1459 # Though this won't be called by syntax errors in the input
1459 # line, there may be SyntaxError cases whith imported code.
1460 # line, there may be SyntaxError cases whith imported code.
1460 self.showsyntaxerror(filename)
1461 self.showsyntaxerror(filename)
1461 elif etype is UsageError:
1462 elif etype is UsageError:
1462 print "UsageError:", value
1463 print "UsageError:", value
1463 else:
1464 else:
1464 # WARNING: these variables are somewhat deprecated and not
1465 # WARNING: these variables are somewhat deprecated and not
1465 # necessarily safe to use in a threaded environment, but tools
1466 # necessarily safe to use in a threaded environment, but tools
1466 # like pdb depend on their existence, so let's set them. If we
1467 # like pdb depend on their existence, so let's set them. If we
1467 # find problems in the field, we'll need to revisit their use.
1468 # find problems in the field, we'll need to revisit their use.
1468 sys.last_type = etype
1469 sys.last_type = etype
1469 sys.last_value = value
1470 sys.last_value = value
1470 sys.last_traceback = tb
1471 sys.last_traceback = tb
1471
1472
1472 if etype in self.custom_exceptions:
1473 if etype in self.custom_exceptions:
1473 # FIXME: Old custom traceback objects may just return a
1474 # FIXME: Old custom traceback objects may just return a
1474 # string, in that case we just put it into a list
1475 # string, in that case we just put it into a list
1475 stb = self.CustomTB(etype, value, tb, tb_offset)
1476 stb = self.CustomTB(etype, value, tb, tb_offset)
1476 if isinstance(ctb, basestring):
1477 if isinstance(ctb, basestring):
1477 stb = [stb]
1478 stb = [stb]
1478 else:
1479 else:
1479 if exception_only:
1480 if exception_only:
1480 stb = ['An exception has occurred, use %tb to see '
1481 stb = ['An exception has occurred, use %tb to see '
1481 'the full traceback.\n']
1482 'the full traceback.\n']
1482 stb.extend(self.InteractiveTB.get_exception_only(etype,
1483 stb.extend(self.InteractiveTB.get_exception_only(etype,
1483 value))
1484 value))
1484 else:
1485 else:
1485 stb = self.InteractiveTB.structured_traceback(etype,
1486 stb = self.InteractiveTB.structured_traceback(etype,
1486 value, tb, tb_offset=tb_offset)
1487 value, tb, tb_offset=tb_offset)
1487 # FIXME: the pdb calling should be done by us, not by
1488 # FIXME: the pdb calling should be done by us, not by
1488 # the code computing the traceback.
1489 # the code computing the traceback.
1489 if self.InteractiveTB.call_pdb:
1490 if self.InteractiveTB.call_pdb:
1490 # pdb mucks up readline, fix it back
1491 # pdb mucks up readline, fix it back
1491 self.set_readline_completer()
1492 self.set_readline_completer()
1492
1493
1493 # Actually show the traceback
1494 # Actually show the traceback
1494 self._showtraceback(etype, value, stb)
1495 self._showtraceback(etype, value, stb)
1495
1496
1496 except KeyboardInterrupt:
1497 except KeyboardInterrupt:
1497 self.write_err("\nKeyboardInterrupt\n")
1498 self.write_err("\nKeyboardInterrupt\n")
1498
1499
1499 def _showtraceback(self, etype, evalue, stb):
1500 def _showtraceback(self, etype, evalue, stb):
1500 """Actually show a traceback.
1501 """Actually show a traceback.
1501
1502
1502 Subclasses may override this method to put the traceback on a different
1503 Subclasses may override this method to put the traceback on a different
1503 place, like a side channel.
1504 place, like a side channel.
1504 """
1505 """
1505 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1506 print >> io.Term.cout, self.InteractiveTB.stb2text(stb)
1506
1507
1507 def showsyntaxerror(self, filename=None):
1508 def showsyntaxerror(self, filename=None):
1508 """Display the syntax error that just occurred.
1509 """Display the syntax error that just occurred.
1509
1510
1510 This doesn't display a stack trace because there isn't one.
1511 This doesn't display a stack trace because there isn't one.
1511
1512
1512 If a filename is given, it is stuffed in the exception instead
1513 If a filename is given, it is stuffed in the exception instead
1513 of what was there before (because Python's parser always uses
1514 of what was there before (because Python's parser always uses
1514 "<string>" when reading from a string).
1515 "<string>" when reading from a string).
1515 """
1516 """
1516 etype, value, last_traceback = sys.exc_info()
1517 etype, value, last_traceback = sys.exc_info()
1517
1518
1518 # See note about these variables in showtraceback() above
1519 # See note about these variables in showtraceback() above
1519 sys.last_type = etype
1520 sys.last_type = etype
1520 sys.last_value = value
1521 sys.last_value = value
1521 sys.last_traceback = last_traceback
1522 sys.last_traceback = last_traceback
1522
1523
1523 if filename and etype is SyntaxError:
1524 if filename and etype is SyntaxError:
1524 # Work hard to stuff the correct filename in the exception
1525 # Work hard to stuff the correct filename in the exception
1525 try:
1526 try:
1526 msg, (dummy_filename, lineno, offset, line) = value
1527 msg, (dummy_filename, lineno, offset, line) = value
1527 except:
1528 except:
1528 # Not the format we expect; leave it alone
1529 # Not the format we expect; leave it alone
1529 pass
1530 pass
1530 else:
1531 else:
1531 # Stuff in the right filename
1532 # Stuff in the right filename
1532 try:
1533 try:
1533 # Assume SyntaxError is a class exception
1534 # Assume SyntaxError is a class exception
1534 value = SyntaxError(msg, (filename, lineno, offset, line))
1535 value = SyntaxError(msg, (filename, lineno, offset, line))
1535 except:
1536 except:
1536 # If that failed, assume SyntaxError is a string
1537 # If that failed, assume SyntaxError is a string
1537 value = msg, (filename, lineno, offset, line)
1538 value = msg, (filename, lineno, offset, line)
1538 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1539 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1539 self._showtraceback(etype, value, stb)
1540 self._showtraceback(etype, value, stb)
1540
1541
1541 #-------------------------------------------------------------------------
1542 #-------------------------------------------------------------------------
1542 # Things related to readline
1543 # Things related to readline
1543 #-------------------------------------------------------------------------
1544 #-------------------------------------------------------------------------
1544
1545
1545 def init_readline(self):
1546 def init_readline(self):
1546 """Command history completion/saving/reloading."""
1547 """Command history completion/saving/reloading."""
1547
1548
1548 if self.readline_use:
1549 if self.readline_use:
1549 import IPython.utils.rlineimpl as readline
1550 import IPython.utils.rlineimpl as readline
1550
1551
1551 self.rl_next_input = None
1552 self.rl_next_input = None
1552 self.rl_do_indent = False
1553 self.rl_do_indent = False
1553
1554
1554 if not self.readline_use or not readline.have_readline:
1555 if not self.readline_use or not readline.have_readline:
1555 self.has_readline = False
1556 self.has_readline = False
1556 self.readline = None
1557 self.readline = None
1557 # Set a number of methods that depend on readline to be no-op
1558 # Set a number of methods that depend on readline to be no-op
1558 self.savehist = no_op
1559 self.savehist = no_op
1559 self.reloadhist = no_op
1560 self.reloadhist = no_op
1560 self.set_readline_completer = no_op
1561 self.set_readline_completer = no_op
1561 self.set_custom_completer = no_op
1562 self.set_custom_completer = no_op
1562 self.set_completer_frame = no_op
1563 self.set_completer_frame = no_op
1563 warn('Readline services not available or not loaded.')
1564 warn('Readline services not available or not loaded.')
1564 else:
1565 else:
1565 self.has_readline = True
1566 self.has_readline = True
1566 self.readline = readline
1567 self.readline = readline
1567 sys.modules['readline'] = readline
1568 sys.modules['readline'] = readline
1568
1569
1569 # Platform-specific configuration
1570 # Platform-specific configuration
1570 if os.name == 'nt':
1571 if os.name == 'nt':
1571 # FIXME - check with Frederick to see if we can harmonize
1572 # FIXME - check with Frederick to see if we can harmonize
1572 # naming conventions with pyreadline to avoid this
1573 # naming conventions with pyreadline to avoid this
1573 # platform-dependent check
1574 # platform-dependent check
1574 self.readline_startup_hook = readline.set_pre_input_hook
1575 self.readline_startup_hook = readline.set_pre_input_hook
1575 else:
1576 else:
1576 self.readline_startup_hook = readline.set_startup_hook
1577 self.readline_startup_hook = readline.set_startup_hook
1577
1578
1578 # Load user's initrc file (readline config)
1579 # Load user's initrc file (readline config)
1579 # Or if libedit is used, load editrc.
1580 # Or if libedit is used, load editrc.
1580 inputrc_name = os.environ.get('INPUTRC')
1581 inputrc_name = os.environ.get('INPUTRC')
1581 if inputrc_name is None:
1582 if inputrc_name is None:
1582 home_dir = get_home_dir()
1583 home_dir = get_home_dir()
1583 if home_dir is not None:
1584 if home_dir is not None:
1584 inputrc_name = '.inputrc'
1585 inputrc_name = '.inputrc'
1585 if readline.uses_libedit:
1586 if readline.uses_libedit:
1586 inputrc_name = '.editrc'
1587 inputrc_name = '.editrc'
1587 inputrc_name = os.path.join(home_dir, inputrc_name)
1588 inputrc_name = os.path.join(home_dir, inputrc_name)
1588 if os.path.isfile(inputrc_name):
1589 if os.path.isfile(inputrc_name):
1589 try:
1590 try:
1590 readline.read_init_file(inputrc_name)
1591 readline.read_init_file(inputrc_name)
1591 except:
1592 except:
1592 warn('Problems reading readline initialization file <%s>'
1593 warn('Problems reading readline initialization file <%s>'
1593 % inputrc_name)
1594 % inputrc_name)
1594
1595
1595 # Configure readline according to user's prefs
1596 # Configure readline according to user's prefs
1596 # This is only done if GNU readline is being used. If libedit
1597 # This is only done if GNU readline is being used. If libedit
1597 # is being used (as on Leopard) the readline config is
1598 # is being used (as on Leopard) the readline config is
1598 # not run as the syntax for libedit is different.
1599 # not run as the syntax for libedit is different.
1599 if not readline.uses_libedit:
1600 if not readline.uses_libedit:
1600 for rlcommand in self.readline_parse_and_bind:
1601 for rlcommand in self.readline_parse_and_bind:
1601 #print "loading rl:",rlcommand # dbg
1602 #print "loading rl:",rlcommand # dbg
1602 readline.parse_and_bind(rlcommand)
1603 readline.parse_and_bind(rlcommand)
1603
1604
1604 # Remove some chars from the delimiters list. If we encounter
1605 # Remove some chars from the delimiters list. If we encounter
1605 # unicode chars, discard them.
1606 # unicode chars, discard them.
1606 delims = readline.get_completer_delims().encode("ascii", "ignore")
1607 delims = readline.get_completer_delims().encode("ascii", "ignore")
1607 delims = delims.translate(string._idmap,
1608 delims = delims.translate(string._idmap,
1608 self.readline_remove_delims)
1609 self.readline_remove_delims)
1609 delims = delims.replace(ESC_MAGIC, '')
1610 delims = delims.replace(ESC_MAGIC, '')
1610 readline.set_completer_delims(delims)
1611 readline.set_completer_delims(delims)
1611 # otherwise we end up with a monster history after a while:
1612 # otherwise we end up with a monster history after a while:
1612 readline.set_history_length(1000)
1613 readline.set_history_length(1000)
1613 try:
1614 try:
1614 #print '*** Reading readline history' # dbg
1615 #print '*** Reading readline history' # dbg
1615 readline.read_history_file(self.histfile)
1616 readline.read_history_file(self.histfile)
1616 except IOError:
1617 except IOError:
1617 pass # It doesn't exist yet.
1618 pass # It doesn't exist yet.
1618
1619
1619 # If we have readline, we want our history saved upon ipython
1620 # If we have readline, we want our history saved upon ipython
1620 # exiting.
1621 # exiting.
1621 atexit.register(self.savehist)
1622 atexit.register(self.savehist)
1622
1623
1623 # Configure auto-indent for all platforms
1624 # Configure auto-indent for all platforms
1624 self.set_autoindent(self.autoindent)
1625 self.set_autoindent(self.autoindent)
1625
1626
1626 def set_next_input(self, s):
1627 def set_next_input(self, s):
1627 """ Sets the 'default' input string for the next command line.
1628 """ Sets the 'default' input string for the next command line.
1628
1629
1629 Requires readline.
1630 Requires readline.
1630
1631
1631 Example:
1632 Example:
1632
1633
1633 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1634 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1634 [D:\ipython]|2> Hello Word_ # cursor is here
1635 [D:\ipython]|2> Hello Word_ # cursor is here
1635 """
1636 """
1636
1637
1637 self.rl_next_input = s
1638 self.rl_next_input = s
1638
1639
1639 # Maybe move this to the terminal subclass?
1640 # Maybe move this to the terminal subclass?
1640 def pre_readline(self):
1641 def pre_readline(self):
1641 """readline hook to be used at the start of each line.
1642 """readline hook to be used at the start of each line.
1642
1643
1643 Currently it handles auto-indent only."""
1644 Currently it handles auto-indent only."""
1644
1645
1645 if self.rl_do_indent:
1646 if self.rl_do_indent:
1646 self.readline.insert_text(self._indent_current_str())
1647 self.readline.insert_text(self._indent_current_str())
1647 if self.rl_next_input is not None:
1648 if self.rl_next_input is not None:
1648 self.readline.insert_text(self.rl_next_input)
1649 self.readline.insert_text(self.rl_next_input)
1649 self.rl_next_input = None
1650 self.rl_next_input = None
1650
1651
1651 def _indent_current_str(self):
1652 def _indent_current_str(self):
1652 """return the current level of indentation as a string"""
1653 """return the current level of indentation as a string"""
1653 return self.indent_current_nsp * ' '
1654 return self.indent_current_nsp * ' '
1654
1655
1655 #-------------------------------------------------------------------------
1656 #-------------------------------------------------------------------------
1656 # Things related to text completion
1657 # Things related to text completion
1657 #-------------------------------------------------------------------------
1658 #-------------------------------------------------------------------------
1658
1659
1659 def init_completer(self):
1660 def init_completer(self):
1660 """Initialize the completion machinery.
1661 """Initialize the completion machinery.
1661
1662
1662 This creates completion machinery that can be used by client code,
1663 This creates completion machinery that can be used by client code,
1663 either interactively in-process (typically triggered by the readline
1664 either interactively in-process (typically triggered by the readline
1664 library), programatically (such as in test suites) or out-of-prcess
1665 library), programatically (such as in test suites) or out-of-prcess
1665 (typically over the network by remote frontends).
1666 (typically over the network by remote frontends).
1666 """
1667 """
1667 from IPython.core.completer import IPCompleter
1668 from IPython.core.completer import IPCompleter
1668 from IPython.core.completerlib import (module_completer,
1669 from IPython.core.completerlib import (module_completer,
1669 magic_run_completer, cd_completer)
1670 magic_run_completer, cd_completer)
1670
1671
1671 self.Completer = IPCompleter(self,
1672 self.Completer = IPCompleter(self,
1672 self.user_ns,
1673 self.user_ns,
1673 self.user_global_ns,
1674 self.user_global_ns,
1674 self.readline_omit__names,
1675 self.readline_omit__names,
1675 self.alias_manager.alias_table,
1676 self.alias_manager.alias_table,
1676 self.has_readline)
1677 self.has_readline)
1677
1678
1678 # Add custom completers to the basic ones built into IPCompleter
1679 # Add custom completers to the basic ones built into IPCompleter
1679 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1680 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1680 self.strdispatchers['complete_command'] = sdisp
1681 self.strdispatchers['complete_command'] = sdisp
1681 self.Completer.custom_completers = sdisp
1682 self.Completer.custom_completers = sdisp
1682
1683
1683 self.set_hook('complete_command', module_completer, str_key = 'import')
1684 self.set_hook('complete_command', module_completer, str_key = 'import')
1684 self.set_hook('complete_command', module_completer, str_key = 'from')
1685 self.set_hook('complete_command', module_completer, str_key = 'from')
1685 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1686 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1686 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1687 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1687
1688
1688 # Only configure readline if we truly are using readline. IPython can
1689 # Only configure readline if we truly are using readline. IPython can
1689 # do tab-completion over the network, in GUIs, etc, where readline
1690 # do tab-completion over the network, in GUIs, etc, where readline
1690 # itself may be absent
1691 # itself may be absent
1691 if self.has_readline:
1692 if self.has_readline:
1692 self.set_readline_completer()
1693 self.set_readline_completer()
1693
1694
1694 def complete(self, text, line=None, cursor_pos=None):
1695 def complete(self, text, line=None, cursor_pos=None):
1695 """Return the completed text and a list of completions.
1696 """Return the completed text and a list of completions.
1696
1697
1697 Parameters
1698 Parameters
1698 ----------
1699 ----------
1699
1700
1700 text : string
1701 text : string
1701 A string of text to be completed on. It can be given as empty and
1702 A string of text to be completed on. It can be given as empty and
1702 instead a line/position pair are given. In this case, the
1703 instead a line/position pair are given. In this case, the
1703 completer itself will split the line like readline does.
1704 completer itself will split the line like readline does.
1704
1705
1705 line : string, optional
1706 line : string, optional
1706 The complete line that text is part of.
1707 The complete line that text is part of.
1707
1708
1708 cursor_pos : int, optional
1709 cursor_pos : int, optional
1709 The position of the cursor on the input line.
1710 The position of the cursor on the input line.
1710
1711
1711 Returns
1712 Returns
1712 -------
1713 -------
1713 text : string
1714 text : string
1714 The actual text that was completed.
1715 The actual text that was completed.
1715
1716
1716 matches : list
1717 matches : list
1717 A sorted list with all possible completions.
1718 A sorted list with all possible completions.
1718
1719
1719 The optional arguments allow the completion to take more context into
1720 The optional arguments allow the completion to take more context into
1720 account, and are part of the low-level completion API.
1721 account, and are part of the low-level completion API.
1721
1722
1722 This is a wrapper around the completion mechanism, similar to what
1723 This is a wrapper around the completion mechanism, similar to what
1723 readline does at the command line when the TAB key is hit. By
1724 readline does at the command line when the TAB key is hit. By
1724 exposing it as a method, it can be used by other non-readline
1725 exposing it as a method, it can be used by other non-readline
1725 environments (such as GUIs) for text completion.
1726 environments (such as GUIs) for text completion.
1726
1727
1727 Simple usage example:
1728 Simple usage example:
1728
1729
1729 In [1]: x = 'hello'
1730 In [1]: x = 'hello'
1730
1731
1731 In [2]: _ip.complete('x.l')
1732 In [2]: _ip.complete('x.l')
1732 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1733 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1733 """
1734 """
1734
1735
1735 # Inject names into __builtin__ so we can complete on the added names.
1736 # Inject names into __builtin__ so we can complete on the added names.
1736 with self.builtin_trap:
1737 with self.builtin_trap:
1737 return self.Completer.complete(text, line, cursor_pos)
1738 return self.Completer.complete(text, line, cursor_pos)
1738
1739
1739 def set_custom_completer(self, completer, pos=0):
1740 def set_custom_completer(self, completer, pos=0):
1740 """Adds a new custom completer function.
1741 """Adds a new custom completer function.
1741
1742
1742 The position argument (defaults to 0) is the index in the completers
1743 The position argument (defaults to 0) is the index in the completers
1743 list where you want the completer to be inserted."""
1744 list where you want the completer to be inserted."""
1744
1745
1745 newcomp = new.instancemethod(completer,self.Completer,
1746 newcomp = new.instancemethod(completer,self.Completer,
1746 self.Completer.__class__)
1747 self.Completer.__class__)
1747 self.Completer.matchers.insert(pos,newcomp)
1748 self.Completer.matchers.insert(pos,newcomp)
1748
1749
1749 def set_readline_completer(self):
1750 def set_readline_completer(self):
1750 """Reset readline's completer to be our own."""
1751 """Reset readline's completer to be our own."""
1751 self.readline.set_completer(self.Completer.rlcomplete)
1752 self.readline.set_completer(self.Completer.rlcomplete)
1752
1753
1753 def set_completer_frame(self, frame=None):
1754 def set_completer_frame(self, frame=None):
1754 """Set the frame of the completer."""
1755 """Set the frame of the completer."""
1755 if frame:
1756 if frame:
1756 self.Completer.namespace = frame.f_locals
1757 self.Completer.namespace = frame.f_locals
1757 self.Completer.global_namespace = frame.f_globals
1758 self.Completer.global_namespace = frame.f_globals
1758 else:
1759 else:
1759 self.Completer.namespace = self.user_ns
1760 self.Completer.namespace = self.user_ns
1760 self.Completer.global_namespace = self.user_global_ns
1761 self.Completer.global_namespace = self.user_global_ns
1761
1762
1762 #-------------------------------------------------------------------------
1763 #-------------------------------------------------------------------------
1763 # Things related to magics
1764 # Things related to magics
1764 #-------------------------------------------------------------------------
1765 #-------------------------------------------------------------------------
1765
1766
1766 def init_magics(self):
1767 def init_magics(self):
1767 # FIXME: Move the color initialization to the DisplayHook, which
1768 # FIXME: Move the color initialization to the DisplayHook, which
1768 # should be split into a prompt manager and displayhook. We probably
1769 # should be split into a prompt manager and displayhook. We probably
1769 # even need a centralize colors management object.
1770 # even need a centralize colors management object.
1770 self.magic_colors(self.colors)
1771 self.magic_colors(self.colors)
1771 # History was moved to a separate module
1772 # History was moved to a separate module
1772 from . import history
1773 from . import history
1773 history.init_ipython(self)
1774 history.init_ipython(self)
1774
1775
1775 def magic(self,arg_s):
1776 def magic(self,arg_s):
1776 """Call a magic function by name.
1777 """Call a magic function by name.
1777
1778
1778 Input: a string containing the name of the magic function to call and
1779 Input: a string containing the name of the magic function to call and
1779 any additional arguments to be passed to the magic.
1780 any additional arguments to be passed to the magic.
1780
1781
1781 magic('name -opt foo bar') is equivalent to typing at the ipython
1782 magic('name -opt foo bar') is equivalent to typing at the ipython
1782 prompt:
1783 prompt:
1783
1784
1784 In[1]: %name -opt foo bar
1785 In[1]: %name -opt foo bar
1785
1786
1786 To call a magic without arguments, simply use magic('name').
1787 To call a magic without arguments, simply use magic('name').
1787
1788
1788 This provides a proper Python function to call IPython's magics in any
1789 This provides a proper Python function to call IPython's magics in any
1789 valid Python code you can type at the interpreter, including loops and
1790 valid Python code you can type at the interpreter, including loops and
1790 compound statements.
1791 compound statements.
1791 """
1792 """
1792 args = arg_s.split(' ',1)
1793 args = arg_s.split(' ',1)
1793 magic_name = args[0]
1794 magic_name = args[0]
1794 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1795 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1795
1796
1796 try:
1797 try:
1797 magic_args = args[1]
1798 magic_args = args[1]
1798 except IndexError:
1799 except IndexError:
1799 magic_args = ''
1800 magic_args = ''
1800 fn = getattr(self,'magic_'+magic_name,None)
1801 fn = getattr(self,'magic_'+magic_name,None)
1801 if fn is None:
1802 if fn is None:
1802 error("Magic function `%s` not found." % magic_name)
1803 error("Magic function `%s` not found." % magic_name)
1803 else:
1804 else:
1804 magic_args = self.var_expand(magic_args,1)
1805 magic_args = self.var_expand(magic_args,1)
1805 with nested(self.builtin_trap,):
1806 with nested(self.builtin_trap,):
1806 result = fn(magic_args)
1807 result = fn(magic_args)
1807 return result
1808 return result
1808
1809
1809 def define_magic(self, magicname, func):
1810 def define_magic(self, magicname, func):
1810 """Expose own function as magic function for ipython
1811 """Expose own function as magic function for ipython
1811
1812
1812 def foo_impl(self,parameter_s=''):
1813 def foo_impl(self,parameter_s=''):
1813 'My very own magic!. (Use docstrings, IPython reads them).'
1814 'My very own magic!. (Use docstrings, IPython reads them).'
1814 print 'Magic function. Passed parameter is between < >:'
1815 print 'Magic function. Passed parameter is between < >:'
1815 print '<%s>' % parameter_s
1816 print '<%s>' % parameter_s
1816 print 'The self object is:',self
1817 print 'The self object is:',self
1817
1818
1818 self.define_magic('foo',foo_impl)
1819 self.define_magic('foo',foo_impl)
1819 """
1820 """
1820
1821
1821 import new
1822 import new
1822 im = new.instancemethod(func,self, self.__class__)
1823 im = new.instancemethod(func,self, self.__class__)
1823 old = getattr(self, "magic_" + magicname, None)
1824 old = getattr(self, "magic_" + magicname, None)
1824 setattr(self, "magic_" + magicname, im)
1825 setattr(self, "magic_" + magicname, im)
1825 return old
1826 return old
1826
1827
1827 #-------------------------------------------------------------------------
1828 #-------------------------------------------------------------------------
1828 # Things related to macros
1829 # Things related to macros
1829 #-------------------------------------------------------------------------
1830 #-------------------------------------------------------------------------
1830
1831
1831 def define_macro(self, name, themacro):
1832 def define_macro(self, name, themacro):
1832 """Define a new macro
1833 """Define a new macro
1833
1834
1834 Parameters
1835 Parameters
1835 ----------
1836 ----------
1836 name : str
1837 name : str
1837 The name of the macro.
1838 The name of the macro.
1838 themacro : str or Macro
1839 themacro : str or Macro
1839 The action to do upon invoking the macro. If a string, a new
1840 The action to do upon invoking the macro. If a string, a new
1840 Macro object is created by passing the string to it.
1841 Macro object is created by passing the string to it.
1841 """
1842 """
1842
1843
1843 from IPython.core import macro
1844 from IPython.core import macro
1844
1845
1845 if isinstance(themacro, basestring):
1846 if isinstance(themacro, basestring):
1846 themacro = macro.Macro(themacro)
1847 themacro = macro.Macro(themacro)
1847 if not isinstance(themacro, macro.Macro):
1848 if not isinstance(themacro, macro.Macro):
1848 raise ValueError('A macro must be a string or a Macro instance.')
1849 raise ValueError('A macro must be a string or a Macro instance.')
1849 self.user_ns[name] = themacro
1850 self.user_ns[name] = themacro
1850
1851
1851 #-------------------------------------------------------------------------
1852 #-------------------------------------------------------------------------
1852 # Things related to the running of system commands
1853 # Things related to the running of system commands
1853 #-------------------------------------------------------------------------
1854 #-------------------------------------------------------------------------
1854
1855
1855 def system(self, cmd):
1856 def system(self, cmd):
1856 """Call the given cmd in a subprocess.
1857 """Call the given cmd in a subprocess.
1857
1858
1858 Parameters
1859 Parameters
1859 ----------
1860 ----------
1860 cmd : str
1861 cmd : str
1861 Command to execute (can not end in '&', as bacground processes are
1862 Command to execute (can not end in '&', as bacground processes are
1862 not supported.
1863 not supported.
1863 """
1864 """
1864 # We do not support backgrounding processes because we either use
1865 # We do not support backgrounding processes because we either use
1865 # pexpect or pipes to read from. Users can always just call
1866 # pexpect or pipes to read from. Users can always just call
1866 # os.system() if they really want a background process.
1867 # os.system() if they really want a background process.
1867 if cmd.endswith('&'):
1868 if cmd.endswith('&'):
1868 raise OSError("Background processes not supported.")
1869 raise OSError("Background processes not supported.")
1869
1870
1870 return system(self.var_expand(cmd, depth=2))
1871 return system(self.var_expand(cmd, depth=2))
1871
1872
1872 def getoutput(self, cmd, split=True):
1873 def getoutput(self, cmd, split=True):
1873 """Get output (possibly including stderr) from a subprocess.
1874 """Get output (possibly including stderr) from a subprocess.
1874
1875
1875 Parameters
1876 Parameters
1876 ----------
1877 ----------
1877 cmd : str
1878 cmd : str
1878 Command to execute (can not end in '&', as background processes are
1879 Command to execute (can not end in '&', as background processes are
1879 not supported.
1880 not supported.
1880 split : bool, optional
1881 split : bool, optional
1881
1882
1882 If True, split the output into an IPython SList. Otherwise, an
1883 If True, split the output into an IPython SList. Otherwise, an
1883 IPython LSString is returned. These are objects similar to normal
1884 IPython LSString is returned. These are objects similar to normal
1884 lists and strings, with a few convenience attributes for easier
1885 lists and strings, with a few convenience attributes for easier
1885 manipulation of line-based output. You can use '?' on them for
1886 manipulation of line-based output. You can use '?' on them for
1886 details.
1887 details.
1887 """
1888 """
1888 if cmd.endswith('&'):
1889 if cmd.endswith('&'):
1889 raise OSError("Background processes not supported.")
1890 raise OSError("Background processes not supported.")
1890 out = getoutput(self.var_expand(cmd, depth=2))
1891 out = getoutput(self.var_expand(cmd, depth=2))
1891 if split:
1892 if split:
1892 out = SList(out.splitlines())
1893 out = SList(out.splitlines())
1893 else:
1894 else:
1894 out = LSString(out)
1895 out = LSString(out)
1895 return out
1896 return out
1896
1897
1897 #-------------------------------------------------------------------------
1898 #-------------------------------------------------------------------------
1898 # Things related to aliases
1899 # Things related to aliases
1899 #-------------------------------------------------------------------------
1900 #-------------------------------------------------------------------------
1900
1901
1901 def init_alias(self):
1902 def init_alias(self):
1902 self.alias_manager = AliasManager(shell=self, config=self.config)
1903 self.alias_manager = AliasManager(shell=self, config=self.config)
1903 self.ns_table['alias'] = self.alias_manager.alias_table,
1904 self.ns_table['alias'] = self.alias_manager.alias_table,
1904
1905
1905 #-------------------------------------------------------------------------
1906 #-------------------------------------------------------------------------
1906 # Things related to extensions and plugins
1907 # Things related to extensions and plugins
1907 #-------------------------------------------------------------------------
1908 #-------------------------------------------------------------------------
1908
1909
1909 def init_extension_manager(self):
1910 def init_extension_manager(self):
1910 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1911 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1911
1912
1912 def init_plugin_manager(self):
1913 def init_plugin_manager(self):
1913 self.plugin_manager = PluginManager(config=self.config)
1914 self.plugin_manager = PluginManager(config=self.config)
1914
1915
1915 #-------------------------------------------------------------------------
1916 #-------------------------------------------------------------------------
1916 # Things related to payloads
1917 # Things related to payloads
1917 #-------------------------------------------------------------------------
1918 #-------------------------------------------------------------------------
1918
1919
1919 def init_payload(self):
1920 def init_payload(self):
1920 self.payload_manager = PayloadManager(config=self.config)
1921 self.payload_manager = PayloadManager(config=self.config)
1921
1922
1922 #-------------------------------------------------------------------------
1923 #-------------------------------------------------------------------------
1923 # Things related to the prefilter
1924 # Things related to the prefilter
1924 #-------------------------------------------------------------------------
1925 #-------------------------------------------------------------------------
1925
1926
1926 def init_prefilter(self):
1927 def init_prefilter(self):
1927 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1928 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1928 # Ultimately this will be refactored in the new interpreter code, but
1929 # Ultimately this will be refactored in the new interpreter code, but
1929 # for now, we should expose the main prefilter method (there's legacy
1930 # for now, we should expose the main prefilter method (there's legacy
1930 # code out there that may rely on this).
1931 # code out there that may rely on this).
1931 self.prefilter = self.prefilter_manager.prefilter_lines
1932 self.prefilter = self.prefilter_manager.prefilter_lines
1932
1933
1933
1934
1934 def auto_rewrite_input(self, cmd):
1935 def auto_rewrite_input(self, cmd):
1935 """Print to the screen the rewritten form of the user's command.
1936 """Print to the screen the rewritten form of the user's command.
1936
1937
1937 This shows visual feedback by rewriting input lines that cause
1938 This shows visual feedback by rewriting input lines that cause
1938 automatic calling to kick in, like::
1939 automatic calling to kick in, like::
1939
1940
1940 /f x
1941 /f x
1941
1942
1942 into::
1943 into::
1943
1944
1944 ------> f(x)
1945 ------> f(x)
1945
1946
1946 after the user's input prompt. This helps the user understand that the
1947 after the user's input prompt. This helps the user understand that the
1947 input line was transformed automatically by IPython.
1948 input line was transformed automatically by IPython.
1948 """
1949 """
1949 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1950 rw = self.displayhook.prompt1.auto_rewrite() + cmd
1950
1951
1951 try:
1952 try:
1952 # plain ascii works better w/ pyreadline, on some machines, so
1953 # plain ascii works better w/ pyreadline, on some machines, so
1953 # we use it and only print uncolored rewrite if we have unicode
1954 # we use it and only print uncolored rewrite if we have unicode
1954 rw = str(rw)
1955 rw = str(rw)
1955 print >> IPython.utils.io.Term.cout, rw
1956 print >> IPython.utils.io.Term.cout, rw
1956 except UnicodeEncodeError:
1957 except UnicodeEncodeError:
1957 print "------> " + cmd
1958 print "------> " + cmd
1958
1959
1959 #-------------------------------------------------------------------------
1960 #-------------------------------------------------------------------------
1960 # Things related to extracting values/expressions from kernel and user_ns
1961 # Things related to extracting values/expressions from kernel and user_ns
1961 #-------------------------------------------------------------------------
1962 #-------------------------------------------------------------------------
1962
1963
1963 def _simple_error(self):
1964 def _simple_error(self):
1964 etype, value = sys.exc_info()[:2]
1965 etype, value = sys.exc_info()[:2]
1965 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1966 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1966
1967
1967 def user_variables(self, names):
1968 def user_variables(self, names):
1968 """Get a list of variable names from the user's namespace.
1969 """Get a list of variable names from the user's namespace.
1969
1970
1970 Parameters
1971 Parameters
1971 ----------
1972 ----------
1972 names : list of strings
1973 names : list of strings
1973 A list of names of variables to be read from the user namespace.
1974 A list of names of variables to be read from the user namespace.
1974
1975
1975 Returns
1976 Returns
1976 -------
1977 -------
1977 A dict, keyed by the input names and with the repr() of each value.
1978 A dict, keyed by the input names and with the repr() of each value.
1978 """
1979 """
1979 out = {}
1980 out = {}
1980 user_ns = self.user_ns
1981 user_ns = self.user_ns
1981 for varname in names:
1982 for varname in names:
1982 try:
1983 try:
1983 value = repr(user_ns[varname])
1984 value = repr(user_ns[varname])
1984 except:
1985 except:
1985 value = self._simple_error()
1986 value = self._simple_error()
1986 out[varname] = value
1987 out[varname] = value
1987 return out
1988 return out
1988
1989
1989 def user_expressions(self, expressions):
1990 def user_expressions(self, expressions):
1990 """Evaluate a dict of expressions in the user's namespace.
1991 """Evaluate a dict of expressions in the user's namespace.
1991
1992
1992 Parameters
1993 Parameters
1993 ----------
1994 ----------
1994 expressions : dict
1995 expressions : dict
1995 A dict with string keys and string values. The expression values
1996 A dict with string keys and string values. The expression values
1996 should be valid Python expressions, each of which will be evaluated
1997 should be valid Python expressions, each of which will be evaluated
1997 in the user namespace.
1998 in the user namespace.
1998
1999
1999 Returns
2000 Returns
2000 -------
2001 -------
2001 A dict, keyed like the input expressions dict, with the repr() of each
2002 A dict, keyed like the input expressions dict, with the repr() of each
2002 value.
2003 value.
2003 """
2004 """
2004 out = {}
2005 out = {}
2005 user_ns = self.user_ns
2006 user_ns = self.user_ns
2006 global_ns = self.user_global_ns
2007 global_ns = self.user_global_ns
2007 for key, expr in expressions.iteritems():
2008 for key, expr in expressions.iteritems():
2008 try:
2009 try:
2009 value = repr(eval(expr, global_ns, user_ns))
2010 value = repr(eval(expr, global_ns, user_ns))
2010 except:
2011 except:
2011 value = self._simple_error()
2012 value = self._simple_error()
2012 out[key] = value
2013 out[key] = value
2013 return out
2014 return out
2014
2015
2015 #-------------------------------------------------------------------------
2016 #-------------------------------------------------------------------------
2016 # Things related to the running of code
2017 # Things related to the running of code
2017 #-------------------------------------------------------------------------
2018 #-------------------------------------------------------------------------
2018
2019
2019 def ex(self, cmd):
2020 def ex(self, cmd):
2020 """Execute a normal python statement in user namespace."""
2021 """Execute a normal python statement in user namespace."""
2021 with nested(self.builtin_trap,):
2022 with nested(self.builtin_trap,):
2022 exec cmd in self.user_global_ns, self.user_ns
2023 exec cmd in self.user_global_ns, self.user_ns
2023
2024
2024 def ev(self, expr):
2025 def ev(self, expr):
2025 """Evaluate python expression expr in user namespace.
2026 """Evaluate python expression expr in user namespace.
2026
2027
2027 Returns the result of evaluation
2028 Returns the result of evaluation
2028 """
2029 """
2029 with nested(self.builtin_trap,):
2030 with nested(self.builtin_trap,):
2030 return eval(expr, self.user_global_ns, self.user_ns)
2031 return eval(expr, self.user_global_ns, self.user_ns)
2031
2032
2032 def safe_execfile(self, fname, *where, **kw):
2033 def safe_execfile(self, fname, *where, **kw):
2033 """A safe version of the builtin execfile().
2034 """A safe version of the builtin execfile().
2034
2035
2035 This version will never throw an exception, but instead print
2036 This version will never throw an exception, but instead print
2036 helpful error messages to the screen. This only works on pure
2037 helpful error messages to the screen. This only works on pure
2037 Python files with the .py extension.
2038 Python files with the .py extension.
2038
2039
2039 Parameters
2040 Parameters
2040 ----------
2041 ----------
2041 fname : string
2042 fname : string
2042 The name of the file to be executed.
2043 The name of the file to be executed.
2043 where : tuple
2044 where : tuple
2044 One or two namespaces, passed to execfile() as (globals,locals).
2045 One or two namespaces, passed to execfile() as (globals,locals).
2045 If only one is given, it is passed as both.
2046 If only one is given, it is passed as both.
2046 exit_ignore : bool (False)
2047 exit_ignore : bool (False)
2047 If True, then silence SystemExit for non-zero status (it is always
2048 If True, then silence SystemExit for non-zero status (it is always
2048 silenced for zero status, as it is so common).
2049 silenced for zero status, as it is so common).
2049 """
2050 """
2050 kw.setdefault('exit_ignore', False)
2051 kw.setdefault('exit_ignore', False)
2051
2052
2052 fname = os.path.abspath(os.path.expanduser(fname))
2053 fname = os.path.abspath(os.path.expanduser(fname))
2053
2054
2054 # Make sure we have a .py file
2055 # Make sure we have a .py file
2055 if not fname.endswith('.py'):
2056 if not fname.endswith('.py'):
2056 warn('File must end with .py to be run using execfile: <%s>' % fname)
2057 warn('File must end with .py to be run using execfile: <%s>' % fname)
2057
2058
2058 # Make sure we can open the file
2059 # Make sure we can open the file
2059 try:
2060 try:
2060 with open(fname) as thefile:
2061 with open(fname) as thefile:
2061 pass
2062 pass
2062 except:
2063 except:
2063 warn('Could not open file <%s> for safe execution.' % fname)
2064 warn('Could not open file <%s> for safe execution.' % fname)
2064 return
2065 return
2065
2066
2066 # Find things also in current directory. This is needed to mimic the
2067 # Find things also in current directory. This is needed to mimic the
2067 # behavior of running a script from the system command line, where
2068 # behavior of running a script from the system command line, where
2068 # Python inserts the script's directory into sys.path
2069 # Python inserts the script's directory into sys.path
2069 dname = os.path.dirname(fname)
2070 dname = os.path.dirname(fname)
2070
2071
2071 with prepended_to_syspath(dname):
2072 with prepended_to_syspath(dname):
2072 try:
2073 try:
2073 execfile(fname,*where)
2074 execfile(fname,*where)
2074 except SystemExit, status:
2075 except SystemExit, status:
2075 # If the call was made with 0 or None exit status (sys.exit(0)
2076 # If the call was made with 0 or None exit status (sys.exit(0)
2076 # or sys.exit() ), don't bother showing a traceback, as both of
2077 # or sys.exit() ), don't bother showing a traceback, as both of
2077 # these are considered normal by the OS:
2078 # these are considered normal by the OS:
2078 # > python -c'import sys;sys.exit(0)'; echo $?
2079 # > python -c'import sys;sys.exit(0)'; echo $?
2079 # 0
2080 # 0
2080 # > python -c'import sys;sys.exit()'; echo $?
2081 # > python -c'import sys;sys.exit()'; echo $?
2081 # 0
2082 # 0
2082 # For other exit status, we show the exception unless
2083 # For other exit status, we show the exception unless
2083 # explicitly silenced, but only in short form.
2084 # explicitly silenced, but only in short form.
2084 if status.code not in (0, None) and not kw['exit_ignore']:
2085 if status.code not in (0, None) and not kw['exit_ignore']:
2085 self.showtraceback(exception_only=True)
2086 self.showtraceback(exception_only=True)
2086 except:
2087 except:
2087 self.showtraceback()
2088 self.showtraceback()
2088
2089
2089 def safe_execfile_ipy(self, fname):
2090 def safe_execfile_ipy(self, fname):
2090 """Like safe_execfile, but for .ipy files with IPython syntax.
2091 """Like safe_execfile, but for .ipy files with IPython syntax.
2091
2092
2092 Parameters
2093 Parameters
2093 ----------
2094 ----------
2094 fname : str
2095 fname : str
2095 The name of the file to execute. The filename must have a
2096 The name of the file to execute. The filename must have a
2096 .ipy extension.
2097 .ipy extension.
2097 """
2098 """
2098 fname = os.path.abspath(os.path.expanduser(fname))
2099 fname = os.path.abspath(os.path.expanduser(fname))
2099
2100
2100 # Make sure we have a .py file
2101 # Make sure we have a .py file
2101 if not fname.endswith('.ipy'):
2102 if not fname.endswith('.ipy'):
2102 warn('File must end with .py to be run using execfile: <%s>' % fname)
2103 warn('File must end with .py to be run using execfile: <%s>' % fname)
2103
2104
2104 # Make sure we can open the file
2105 # Make sure we can open the file
2105 try:
2106 try:
2106 with open(fname) as thefile:
2107 with open(fname) as thefile:
2107 pass
2108 pass
2108 except:
2109 except:
2109 warn('Could not open file <%s> for safe execution.' % fname)
2110 warn('Could not open file <%s> for safe execution.' % fname)
2110 return
2111 return
2111
2112
2112 # Find things also in current directory. This is needed to mimic the
2113 # Find things also in current directory. This is needed to mimic the
2113 # behavior of running a script from the system command line, where
2114 # behavior of running a script from the system command line, where
2114 # Python inserts the script's directory into sys.path
2115 # Python inserts the script's directory into sys.path
2115 dname = os.path.dirname(fname)
2116 dname = os.path.dirname(fname)
2116
2117
2117 with prepended_to_syspath(dname):
2118 with prepended_to_syspath(dname):
2118 try:
2119 try:
2119 with open(fname) as thefile:
2120 with open(fname) as thefile:
2120 script = thefile.read()
2121 script = thefile.read()
2121 # self.runlines currently captures all exceptions
2122 # self.runlines currently captures all exceptions
2122 # raise in user code. It would be nice if there were
2123 # raise in user code. It would be nice if there were
2123 # versions of runlines, execfile that did raise, so
2124 # versions of runlines, execfile that did raise, so
2124 # we could catch the errors.
2125 # we could catch the errors.
2125 self.runlines(script, clean=True)
2126 self.runlines(script, clean=True)
2126 except:
2127 except:
2127 self.showtraceback()
2128 self.showtraceback()
2128 warn('Unknown failure executing file: <%s>' % fname)
2129 warn('Unknown failure executing file: <%s>' % fname)
2129
2130
2130 def run_cell(self, cell):
2131 def run_cell(self, cell):
2131 """Run the contents of an entire multiline 'cell' of code.
2132 """Run the contents of an entire multiline 'cell' of code.
2132
2133
2133 The cell is split into separate blocks which can be executed
2134 The cell is split into separate blocks which can be executed
2134 individually. Then, based on how many blocks there are, they are
2135 individually. Then, based on how many blocks there are, they are
2135 executed as follows:
2136 executed as follows:
2136
2137
2137 - A single block: 'single' mode.
2138 - A single block: 'single' mode.
2138
2139
2139 If there's more than one block, it depends:
2140 If there's more than one block, it depends:
2140
2141
2141 - if the last one is no more than two lines long, run all but the last
2142 - if the last one is no more than two lines long, run all but the last
2142 in 'exec' mode and the very last one in 'single' mode. This makes it
2143 in 'exec' mode and the very last one in 'single' mode. This makes it
2143 easy to type simple expressions at the end to see computed values. -
2144 easy to type simple expressions at the end to see computed values. -
2144 otherwise (last one is also multiline), run all in 'exec' mode
2145 otherwise (last one is also multiline), run all in 'exec' mode
2145
2146
2146 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2147 When code is executed in 'single' mode, :func:`sys.displayhook` fires,
2147 results are displayed and output prompts are computed. In 'exec' mode,
2148 results are displayed and output prompts are computed. In 'exec' mode,
2148 no results are displayed unless :func:`print` is called explicitly;
2149 no results are displayed unless :func:`print` is called explicitly;
2149 this mode is more akin to running a script.
2150 this mode is more akin to running a script.
2150
2151
2151 Parameters
2152 Parameters
2152 ----------
2153 ----------
2153 cell : str
2154 cell : str
2154 A single or multiline string.
2155 A single or multiline string.
2155 """
2156 """
2156 #################################################################
2157 #################################################################
2157 # FIXME
2158 # FIXME
2158 # =====
2159 # =====
2159 # This execution logic should stop calling runlines altogether, and
2160 # This execution logic should stop calling runlines altogether, and
2160 # instead we should do what runlines does, in a controlled manner, here
2161 # instead we should do what runlines does, in a controlled manner, here
2161 # (runlines mutates lots of state as it goes calling sub-methods that
2162 # (runlines mutates lots of state as it goes calling sub-methods that
2162 # also mutate state). Basically we should:
2163 # also mutate state). Basically we should:
2163 # - apply dynamic transforms for single-line input (the ones that
2164 # - apply dynamic transforms for single-line input (the ones that
2164 # split_blocks won't apply since they need context).
2165 # split_blocks won't apply since they need context).
2165 # - increment the global execution counter (we need to pull that out
2166 # - increment the global execution counter (we need to pull that out
2166 # from outputcache's control; outputcache should instead read it from
2167 # from outputcache's control; outputcache should instead read it from
2167 # the main object).
2168 # the main object).
2168 # - do any logging of input
2169 # - do any logging of input
2169 # - update histories (raw/translated)
2170 # - update histories (raw/translated)
2170 # - then, call plain runsource (for single blocks, so displayhook is
2171 # - then, call plain runsource (for single blocks, so displayhook is
2171 # triggered) or runcode (for multiline blocks in exec mode).
2172 # triggered) or runcode (for multiline blocks in exec mode).
2172 #
2173 #
2173 # Once this is done, we'll be able to stop using runlines and we'll
2174 # Once this is done, we'll be able to stop using runlines and we'll
2174 # also have a much cleaner separation of logging, input history and
2175 # also have a much cleaner separation of logging, input history and
2175 # output cache management.
2176 # output cache management.
2176 #################################################################
2177 #################################################################
2177
2178
2178 # We need to break up the input into executable blocks that can be run
2179 # We need to break up the input into executable blocks that can be run
2179 # in 'single' mode, to provide comfortable user behavior.
2180 # in 'single' mode, to provide comfortable user behavior.
2180 blocks = self.input_splitter.split_blocks(cell)
2181 blocks = self.input_splitter.split_blocks(cell)
2181
2182
2182 if not blocks:
2183 if not blocks:
2183 return
2184 return
2184
2185
2185 # Single-block input should behave like an interactive prompt
2186 # Single-block input should behave like an interactive prompt
2186 if len(blocks) == 1:
2187 if len(blocks) == 1:
2187 self.runlines(blocks[0])
2188 self.runlines(blocks[0])
2188 return
2189 return
2189
2190
2190 # In multi-block input, if the last block is a simple (one-two lines)
2191 # In multi-block input, if the last block is a simple (one-two lines)
2191 # expression, run it in single mode so it produces output. Otherwise
2192 # expression, run it in single mode so it produces output. Otherwise
2192 # just feed the whole thing to runcode.
2193 # just feed the whole thing to runcode.
2193 # This seems like a reasonable usability design.
2194 # This seems like a reasonable usability design.
2194 last = blocks[-1]
2195 last = blocks[-1]
2195
2196
2196 # Note: below, whenever we call runcode, we must sync history
2197 # Note: below, whenever we call runcode, we must sync history
2197 # ourselves, because runcode is NOT meant to manage history at all.
2198 # ourselves, because runcode is NOT meant to manage history at all.
2198 if len(last.splitlines()) < 2:
2199 if len(last.splitlines()) < 2:
2199 # Get the main body to run as a cell
2200 # Get the main body to run as a cell
2200 body = ''.join(blocks[:-1])
2201 body = ''.join(blocks[:-1])
2201 self.input_hist.append(body)
2202 self.input_hist.append(body)
2202 self.input_hist_raw.append(body)
2203 self.input_hist_raw.append(body)
2203 self.runcode(body, post_execute=False)
2204 self.runcode(body, post_execute=False)
2204 # And the last expression via runlines so it produces output
2205 # And the last expression via runlines so it produces output
2205 self.runlines(last)
2206 self.runlines(last)
2206 else:
2207 else:
2207 # Run the whole cell as one entity
2208 # Run the whole cell as one entity
2208 self.input_hist.append(cell)
2209 self.input_hist.append(cell)
2209 self.input_hist_raw.append(cell)
2210 self.input_hist_raw.append(cell)
2210 self.runcode(cell)
2211 self.runcode(cell)
2211
2212
2212 def runlines(self, lines, clean=False):
2213 def runlines(self, lines, clean=False):
2213 """Run a string of one or more lines of source.
2214 """Run a string of one or more lines of source.
2214
2215
2215 This method is capable of running a string containing multiple source
2216 This method is capable of running a string containing multiple source
2216 lines, as if they had been entered at the IPython prompt. Since it
2217 lines, as if they had been entered at the IPython prompt. Since it
2217 exposes IPython's processing machinery, the given strings can contain
2218 exposes IPython's processing machinery, the given strings can contain
2218 magic calls (%magic), special shell access (!cmd), etc.
2219 magic calls (%magic), special shell access (!cmd), etc.
2219 """
2220 """
2220
2221
2221 if isinstance(lines, (list, tuple)):
2222 if isinstance(lines, (list, tuple)):
2222 lines = '\n'.join(lines)
2223 lines = '\n'.join(lines)
2223
2224
2224 if clean:
2225 if clean:
2225 lines = self._cleanup_ipy_script(lines)
2226 lines = self._cleanup_ipy_script(lines)
2226
2227
2227 # We must start with a clean buffer, in case this is run from an
2228 # We must start with a clean buffer, in case this is run from an
2228 # interactive IPython session (via a magic, for example).
2229 # interactive IPython session (via a magic, for example).
2229 self.resetbuffer()
2230 self.resetbuffer()
2230 lines = lines.splitlines()
2231 lines = lines.splitlines()
2231 more = 0
2232 more = 0
2232 with nested(self.builtin_trap, self.display_trap):
2233 with nested(self.builtin_trap, self.display_trap):
2233 for line in lines:
2234 for line in lines:
2234 # skip blank lines so we don't mess up the prompt counter, but
2235 # skip blank lines so we don't mess up the prompt counter, but
2235 # do NOT skip even a blank line if we are in a code block (more
2236 # do NOT skip even a blank line if we are in a code block (more
2236 # is true)
2237 # is true)
2237
2238
2238 if line or more:
2239 if line or more:
2239 # push to raw history, so hist line numbers stay in sync
2240 # push to raw history, so hist line numbers stay in sync
2240 self.input_hist_raw.append(line + '\n')
2241 self.input_hist_raw.append(line + '\n')
2241 prefiltered = self.prefilter_manager.prefilter_lines(line,
2242 prefiltered = self.prefilter_manager.prefilter_lines(line,
2242 more)
2243 more)
2243 more = self.push_line(prefiltered)
2244 more = self.push_line(prefiltered)
2244 # IPython's runsource returns None if there was an error
2245 # IPython's runsource returns None if there was an error
2245 # compiling the code. This allows us to stop processing
2246 # compiling the code. This allows us to stop processing
2246 # right away, so the user gets the error message at the
2247 # right away, so the user gets the error message at the
2247 # right place.
2248 # right place.
2248 if more is None:
2249 if more is None:
2249 break
2250 break
2250 else:
2251 else:
2251 self.input_hist_raw.append("\n")
2252 self.input_hist_raw.append("\n")
2252 # final newline in case the input didn't have it, so that the code
2253 # final newline in case the input didn't have it, so that the code
2253 # actually does get executed
2254 # actually does get executed
2254 if more:
2255 if more:
2255 self.push_line('\n')
2256 self.push_line('\n')
2256
2257
2257 def runsource(self, source, filename='<input>', symbol='single'):
2258 def runsource(self, source, filename='<input>', symbol='single'):
2258 """Compile and run some source in the interpreter.
2259 """Compile and run some source in the interpreter.
2259
2260
2260 Arguments are as for compile_command().
2261 Arguments are as for compile_command().
2261
2262
2262 One several things can happen:
2263 One several things can happen:
2263
2264
2264 1) The input is incorrect; compile_command() raised an
2265 1) The input is incorrect; compile_command() raised an
2265 exception (SyntaxError or OverflowError). A syntax traceback
2266 exception (SyntaxError or OverflowError). A syntax traceback
2266 will be printed by calling the showsyntaxerror() method.
2267 will be printed by calling the showsyntaxerror() method.
2267
2268
2268 2) The input is incomplete, and more input is required;
2269 2) The input is incomplete, and more input is required;
2269 compile_command() returned None. Nothing happens.
2270 compile_command() returned None. Nothing happens.
2270
2271
2271 3) The input is complete; compile_command() returned a code
2272 3) The input is complete; compile_command() returned a code
2272 object. The code is executed by calling self.runcode() (which
2273 object. The code is executed by calling self.runcode() (which
2273 also handles run-time exceptions, except for SystemExit).
2274 also handles run-time exceptions, except for SystemExit).
2274
2275
2275 The return value is:
2276 The return value is:
2276
2277
2277 - True in case 2
2278 - True in case 2
2278
2279
2279 - False in the other cases, unless an exception is raised, where
2280 - False in the other cases, unless an exception is raised, where
2280 None is returned instead. This can be used by external callers to
2281 None is returned instead. This can be used by external callers to
2281 know whether to continue feeding input or not.
2282 know whether to continue feeding input or not.
2282
2283
2283 The return value can be used to decide whether to use sys.ps1 or
2284 The return value can be used to decide whether to use sys.ps1 or
2284 sys.ps2 to prompt the next line."""
2285 sys.ps2 to prompt the next line."""
2285
2286
2286 # We need to ensure that the source is unicode from here on.
2287 # We need to ensure that the source is unicode from here on.
2287 if type(source)==str:
2288 if type(source)==str:
2288 source = source.decode(self.stdin_encoding)
2289 source = source.decode(self.stdin_encoding)
2289
2290
2290 # if the source code has leading blanks, add 'if 1:\n' to it
2291 # if the source code has leading blanks, add 'if 1:\n' to it
2291 # this allows execution of indented pasted code. It is tempting
2292 # this allows execution of indented pasted code. It is tempting
2292 # to add '\n' at the end of source to run commands like ' a=1'
2293 # to add '\n' at the end of source to run commands like ' a=1'
2293 # directly, but this fails for more complicated scenarios
2294 # directly, but this fails for more complicated scenarios
2294
2295
2295 if source[:1] in [' ', '\t']:
2296 if source[:1] in [' ', '\t']:
2296 source = u'if 1:\n%s' % source
2297 source = u'if 1:\n%s' % source
2297
2298
2298 try:
2299 try:
2299 code = self.compile(source,filename,symbol)
2300 code = self.compile(source,filename,symbol)
2300 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2301 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2301 # Case 1
2302 # Case 1
2302 self.showsyntaxerror(filename)
2303 self.showsyntaxerror(filename)
2303 return None
2304 return None
2304
2305
2305 if code is None:
2306 if code is None:
2306 # Case 2
2307 # Case 2
2307 return True
2308 return True
2308
2309
2309 # Case 3
2310 # Case 3
2310 # We store the code object so that threaded shells and
2311 # We store the code object so that threaded shells and
2311 # custom exception handlers can access all this info if needed.
2312 # custom exception handlers can access all this info if needed.
2312 # The source corresponding to this can be obtained from the
2313 # The source corresponding to this can be obtained from the
2313 # buffer attribute as '\n'.join(self.buffer).
2314 # buffer attribute as '\n'.join(self.buffer).
2314 self.code_to_run = code
2315 self.code_to_run = code
2315 # now actually execute the code object
2316 # now actually execute the code object
2316 if self.runcode(code) == 0:
2317 if self.runcode(code) == 0:
2317 return False
2318 return False
2318 else:
2319 else:
2319 return None
2320 return None
2320
2321
2321 def runcode(self, code_obj, post_execute=True):
2322 def runcode(self, code_obj, post_execute=True):
2322 """Execute a code object.
2323 """Execute a code object.
2323
2324
2324 When an exception occurs, self.showtraceback() is called to display a
2325 When an exception occurs, self.showtraceback() is called to display a
2325 traceback.
2326 traceback.
2326
2327
2327 Return value: a flag indicating whether the code to be run completed
2328 Return value: a flag indicating whether the code to be run completed
2328 successfully:
2329 successfully:
2329
2330
2330 - 0: successful execution.
2331 - 0: successful execution.
2331 - 1: an error occurred.
2332 - 1: an error occurred.
2332 """
2333 """
2333
2334
2334 # Set our own excepthook in case the user code tries to call it
2335 # Set our own excepthook in case the user code tries to call it
2335 # directly, so that the IPython crash handler doesn't get triggered
2336 # directly, so that the IPython crash handler doesn't get triggered
2336 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2337 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2337
2338
2338 # we save the original sys.excepthook in the instance, in case config
2339 # we save the original sys.excepthook in the instance, in case config
2339 # code (such as magics) needs access to it.
2340 # code (such as magics) needs access to it.
2340 self.sys_excepthook = old_excepthook
2341 self.sys_excepthook = old_excepthook
2341 outflag = 1 # happens in more places, so it's easier as default
2342 outflag = 1 # happens in more places, so it's easier as default
2342 try:
2343 try:
2343 try:
2344 try:
2344 self.hooks.pre_runcode_hook()
2345 self.hooks.pre_runcode_hook()
2345 #rprint('Running code') # dbg
2346 #rprint('Running code') # dbg
2346 exec code_obj in self.user_global_ns, self.user_ns
2347 exec code_obj in self.user_global_ns, self.user_ns
2347 finally:
2348 finally:
2348 # Reset our crash handler in place
2349 # Reset our crash handler in place
2349 sys.excepthook = old_excepthook
2350 sys.excepthook = old_excepthook
2350 except SystemExit:
2351 except SystemExit:
2351 self.resetbuffer()
2352 self.resetbuffer()
2352 self.showtraceback(exception_only=True)
2353 self.showtraceback(exception_only=True)
2353 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2354 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2354 except self.custom_exceptions:
2355 except self.custom_exceptions:
2355 etype,value,tb = sys.exc_info()
2356 etype,value,tb = sys.exc_info()
2356 self.CustomTB(etype,value,tb)
2357 self.CustomTB(etype,value,tb)
2357 except:
2358 except:
2358 self.showtraceback()
2359 self.showtraceback()
2359 else:
2360 else:
2360 outflag = 0
2361 outflag = 0
2361 if softspace(sys.stdout, 0):
2362 if softspace(sys.stdout, 0):
2362 print
2363 print
2363
2364
2364 # Execute any registered post-execution functions. Here, any errors
2365 # Execute any registered post-execution functions. Here, any errors
2365 # are reported only minimally and just on the terminal, because the
2366 # are reported only minimally and just on the terminal, because the
2366 # main exception channel may be occupied with a user traceback.
2367 # main exception channel may be occupied with a user traceback.
2367 # FIXME: we need to think this mechanism a little more carefully.
2368 # FIXME: we need to think this mechanism a little more carefully.
2368 if post_execute:
2369 if post_execute:
2369 for func in self._post_execute:
2370 for func in self._post_execute:
2370 try:
2371 try:
2371 func()
2372 func()
2372 except:
2373 except:
2373 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2374 head = '[ ERROR ] Evaluating post_execute function: %s' % \
2374 func
2375 func
2375 print >> io.Term.cout, head
2376 print >> io.Term.cout, head
2376 print >> io.Term.cout, self._simple_error()
2377 print >> io.Term.cout, self._simple_error()
2377 print >> io.Term.cout, 'Removing from post_execute'
2378 print >> io.Term.cout, 'Removing from post_execute'
2378 self._post_execute.remove(func)
2379 self._post_execute.remove(func)
2379
2380
2380 # Flush out code object which has been run (and source)
2381 # Flush out code object which has been run (and source)
2381 self.code_to_run = None
2382 self.code_to_run = None
2382 return outflag
2383 return outflag
2383
2384
2384 def push_line(self, line):
2385 def push_line(self, line):
2385 """Push a line to the interpreter.
2386 """Push a line to the interpreter.
2386
2387
2387 The line should not have a trailing newline; it may have
2388 The line should not have a trailing newline; it may have
2388 internal newlines. The line is appended to a buffer and the
2389 internal newlines. The line is appended to a buffer and the
2389 interpreter's runsource() method is called with the
2390 interpreter's runsource() method is called with the
2390 concatenated contents of the buffer as source. If this
2391 concatenated contents of the buffer as source. If this
2391 indicates that the command was executed or invalid, the buffer
2392 indicates that the command was executed or invalid, the buffer
2392 is reset; otherwise, the command is incomplete, and the buffer
2393 is reset; otherwise, the command is incomplete, and the buffer
2393 is left as it was after the line was appended. The return
2394 is left as it was after the line was appended. The return
2394 value is 1 if more input is required, 0 if the line was dealt
2395 value is 1 if more input is required, 0 if the line was dealt
2395 with in some way (this is the same as runsource()).
2396 with in some way (this is the same as runsource()).
2396 """
2397 """
2397
2398
2398 # autoindent management should be done here, and not in the
2399 # autoindent management should be done here, and not in the
2399 # interactive loop, since that one is only seen by keyboard input. We
2400 # interactive loop, since that one is only seen by keyboard input. We
2400 # need this done correctly even for code run via runlines (which uses
2401 # need this done correctly even for code run via runlines (which uses
2401 # push).
2402 # push).
2402
2403
2403 #print 'push line: <%s>' % line # dbg
2404 #print 'push line: <%s>' % line # dbg
2404 for subline in line.splitlines():
2405 for subline in line.splitlines():
2405 self._autoindent_update(subline)
2406 self._autoindent_update(subline)
2406 self.buffer.append(line)
2407 self.buffer.append(line)
2407 more = self.runsource('\n'.join(self.buffer), self.filename)
2408 more = self.runsource('\n'.join(self.buffer), self.filename)
2408 if not more:
2409 if not more:
2409 self.resetbuffer()
2410 self.resetbuffer()
2410 return more
2411 return more
2411
2412
2412 def resetbuffer(self):
2413 def resetbuffer(self):
2413 """Reset the input buffer."""
2414 """Reset the input buffer."""
2414 self.buffer[:] = []
2415 self.buffer[:] = []
2415
2416
2416 def _is_secondary_block_start(self, s):
2417 def _is_secondary_block_start(self, s):
2417 if not s.endswith(':'):
2418 if not s.endswith(':'):
2418 return False
2419 return False
2419 if (s.startswith('elif') or
2420 if (s.startswith('elif') or
2420 s.startswith('else') or
2421 s.startswith('else') or
2421 s.startswith('except') or
2422 s.startswith('except') or
2422 s.startswith('finally')):
2423 s.startswith('finally')):
2423 return True
2424 return True
2424
2425
2425 def _cleanup_ipy_script(self, script):
2426 def _cleanup_ipy_script(self, script):
2426 """Make a script safe for self.runlines()
2427 """Make a script safe for self.runlines()
2427
2428
2428 Currently, IPython is lines based, with blocks being detected by
2429 Currently, IPython is lines based, with blocks being detected by
2429 empty lines. This is a problem for block based scripts that may
2430 empty lines. This is a problem for block based scripts that may
2430 not have empty lines after blocks. This script adds those empty
2431 not have empty lines after blocks. This script adds those empty
2431 lines to make scripts safe for running in the current line based
2432 lines to make scripts safe for running in the current line based
2432 IPython.
2433 IPython.
2433 """
2434 """
2434 res = []
2435 res = []
2435 lines = script.splitlines()
2436 lines = script.splitlines()
2436 level = 0
2437 level = 0
2437
2438
2438 for l in lines:
2439 for l in lines:
2439 lstripped = l.lstrip()
2440 lstripped = l.lstrip()
2440 stripped = l.strip()
2441 stripped = l.strip()
2441 if not stripped:
2442 if not stripped:
2442 continue
2443 continue
2443 newlevel = len(l) - len(lstripped)
2444 newlevel = len(l) - len(lstripped)
2444 if level > 0 and newlevel == 0 and \
2445 if level > 0 and newlevel == 0 and \
2445 not self._is_secondary_block_start(stripped):
2446 not self._is_secondary_block_start(stripped):
2446 # add empty line
2447 # add empty line
2447 res.append('')
2448 res.append('')
2448 res.append(l)
2449 res.append(l)
2449 level = newlevel
2450 level = newlevel
2450
2451
2451 return '\n'.join(res) + '\n'
2452 return '\n'.join(res) + '\n'
2452
2453
2453 def _autoindent_update(self,line):
2454 def _autoindent_update(self,line):
2454 """Keep track of the indent level."""
2455 """Keep track of the indent level."""
2455
2456
2456 #debugx('line')
2457 #debugx('line')
2457 #debugx('self.indent_current_nsp')
2458 #debugx('self.indent_current_nsp')
2458 if self.autoindent:
2459 if self.autoindent:
2459 if line:
2460 if line:
2460 inisp = num_ini_spaces(line)
2461 inisp = num_ini_spaces(line)
2461 if inisp < self.indent_current_nsp:
2462 if inisp < self.indent_current_nsp:
2462 self.indent_current_nsp = inisp
2463 self.indent_current_nsp = inisp
2463
2464
2464 if line[-1] == ':':
2465 if line[-1] == ':':
2465 self.indent_current_nsp += 4
2466 self.indent_current_nsp += 4
2466 elif dedent_re.match(line):
2467 elif dedent_re.match(line):
2467 self.indent_current_nsp -= 4
2468 self.indent_current_nsp -= 4
2468 else:
2469 else:
2469 self.indent_current_nsp = 0
2470 self.indent_current_nsp = 0
2470
2471
2471 #-------------------------------------------------------------------------
2472 #-------------------------------------------------------------------------
2472 # Things related to GUI support and pylab
2473 # Things related to GUI support and pylab
2473 #-------------------------------------------------------------------------
2474 #-------------------------------------------------------------------------
2474
2475
2475 def enable_pylab(self, gui=None):
2476 def enable_pylab(self, gui=None):
2476 raise NotImplementedError('Implement enable_pylab in a subclass')
2477 raise NotImplementedError('Implement enable_pylab in a subclass')
2477
2478
2478 #-------------------------------------------------------------------------
2479 #-------------------------------------------------------------------------
2479 # Utilities
2480 # Utilities
2480 #-------------------------------------------------------------------------
2481 #-------------------------------------------------------------------------
2481
2482
2482 def var_expand(self,cmd,depth=0):
2483 def var_expand(self,cmd,depth=0):
2483 """Expand python variables in a string.
2484 """Expand python variables in a string.
2484
2485
2485 The depth argument indicates how many frames above the caller should
2486 The depth argument indicates how many frames above the caller should
2486 be walked to look for the local namespace where to expand variables.
2487 be walked to look for the local namespace where to expand variables.
2487
2488
2488 The global namespace for expansion is always the user's interactive
2489 The global namespace for expansion is always the user's interactive
2489 namespace.
2490 namespace.
2490 """
2491 """
2491
2492
2492 return str(ItplNS(cmd,
2493 return str(ItplNS(cmd,
2493 self.user_ns, # globals
2494 self.user_ns, # globals
2494 # Skip our own frame in searching for locals:
2495 # Skip our own frame in searching for locals:
2495 sys._getframe(depth+1).f_locals # locals
2496 sys._getframe(depth+1).f_locals # locals
2496 ))
2497 ))
2497
2498
2498 def mktempfile(self,data=None):
2499 def mktempfile(self,data=None):
2499 """Make a new tempfile and return its filename.
2500 """Make a new tempfile and return its filename.
2500
2501
2501 This makes a call to tempfile.mktemp, but it registers the created
2502 This makes a call to tempfile.mktemp, but it registers the created
2502 filename internally so ipython cleans it up at exit time.
2503 filename internally so ipython cleans it up at exit time.
2503
2504
2504 Optional inputs:
2505 Optional inputs:
2505
2506
2506 - data(None): if data is given, it gets written out to the temp file
2507 - data(None): if data is given, it gets written out to the temp file
2507 immediately, and the file is closed again."""
2508 immediately, and the file is closed again."""
2508
2509
2509 filename = tempfile.mktemp('.py','ipython_edit_')
2510 filename = tempfile.mktemp('.py','ipython_edit_')
2510 self.tempfiles.append(filename)
2511 self.tempfiles.append(filename)
2511
2512
2512 if data:
2513 if data:
2513 tmp_file = open(filename,'w')
2514 tmp_file = open(filename,'w')
2514 tmp_file.write(data)
2515 tmp_file.write(data)
2515 tmp_file.close()
2516 tmp_file.close()
2516 return filename
2517 return filename
2517
2518
2518 # TODO: This should be removed when Term is refactored.
2519 # TODO: This should be removed when Term is refactored.
2519 def write(self,data):
2520 def write(self,data):
2520 """Write a string to the default output"""
2521 """Write a string to the default output"""
2521 io.Term.cout.write(data)
2522 io.Term.cout.write(data)
2522
2523
2523 # TODO: This should be removed when Term is refactored.
2524 # TODO: This should be removed when Term is refactored.
2524 def write_err(self,data):
2525 def write_err(self,data):
2525 """Write a string to the default error output"""
2526 """Write a string to the default error output"""
2526 io.Term.cerr.write(data)
2527 io.Term.cerr.write(data)
2527
2528
2528 def ask_yes_no(self,prompt,default=True):
2529 def ask_yes_no(self,prompt,default=True):
2529 if self.quiet:
2530 if self.quiet:
2530 return True
2531 return True
2531 return ask_yes_no(prompt,default)
2532 return ask_yes_no(prompt,default)
2532
2533
2533 def show_usage(self):
2534 def show_usage(self):
2534 """Show a usage message"""
2535 """Show a usage message"""
2535 page.page(IPython.core.usage.interactive_usage)
2536 page.page(IPython.core.usage.interactive_usage)
2536
2537
2537 #-------------------------------------------------------------------------
2538 #-------------------------------------------------------------------------
2538 # Things related to IPython exiting
2539 # Things related to IPython exiting
2539 #-------------------------------------------------------------------------
2540 #-------------------------------------------------------------------------
2540 def atexit_operations(self):
2541 def atexit_operations(self):
2541 """This will be executed at the time of exit.
2542 """This will be executed at the time of exit.
2542
2543
2543 Cleanup operations and saving of persistent data that is done
2544 Cleanup operations and saving of persistent data that is done
2544 unconditionally by IPython should be performed here.
2545 unconditionally by IPython should be performed here.
2545
2546
2546 For things that may depend on startup flags or platform specifics (such
2547 For things that may depend on startup flags or platform specifics (such
2547 as having readline or not), register a separate atexit function in the
2548 as having readline or not), register a separate atexit function in the
2548 code that has the appropriate information, rather than trying to
2549 code that has the appropriate information, rather than trying to
2549 clutter
2550 clutter
2550 """
2551 """
2551 # Cleanup all tempfiles left around
2552 # Cleanup all tempfiles left around
2552 for tfile in self.tempfiles:
2553 for tfile in self.tempfiles:
2553 try:
2554 try:
2554 os.unlink(tfile)
2555 os.unlink(tfile)
2555 except OSError:
2556 except OSError:
2556 pass
2557 pass
2557
2558
2558 # Clear all user namespaces to release all references cleanly.
2559 # Clear all user namespaces to release all references cleanly.
2559 self.reset()
2560 self.reset()
2560
2561
2561 # Run user hooks
2562 # Run user hooks
2562 self.hooks.shutdown_hook()
2563 self.hooks.shutdown_hook()
2563
2564
2564 def cleanup(self):
2565 def cleanup(self):
2565 self.restore_sys_module_state()
2566 self.restore_sys_module_state()
2566
2567
2567
2568
2568 class InteractiveShellABC(object):
2569 class InteractiveShellABC(object):
2569 """An abstract base class for InteractiveShell."""
2570 """An abstract base class for InteractiveShell."""
2570 __metaclass__ = abc.ABCMeta
2571 __metaclass__ = abc.ABCMeta
2571
2572
2572 InteractiveShellABC.register(InteractiveShell)
2573 InteractiveShellABC.register(InteractiveShell)
@@ -1,810 +1,892 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Tools for inspecting Python objects.
2 """Tools for inspecting Python objects.
3
3
4 Uses syntax highlighting for presenting the various information elements.
4 Uses syntax highlighting for presenting the various information elements.
5
5
6 Similar in spirit to the inspect module, but all calls take a name argument to
6 Similar in spirit to the inspect module, but all calls take a name argument to
7 reference the name under which an object is being read.
7 reference the name under which an object is being read.
8 """
8 """
9
9
10 #*****************************************************************************
10 #*****************************************************************************
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
11 # Copyright (C) 2001-2004 Fernando Perez <fperez@colorado.edu>
12 #
12 #
13 # Distributed under the terms of the BSD License. The full license is in
13 # Distributed under the terms of the BSD License. The full license is in
14 # the file COPYING, distributed as part of this software.
14 # the file COPYING, distributed as part of this software.
15 #*****************************************************************************
15 #*****************************************************************************
16
16
17 __all__ = ['Inspector','InspectColors']
17 __all__ = ['Inspector','InspectColors']
18
18
19 # stdlib modules
19 # stdlib modules
20 import __builtin__
20 import __builtin__
21 import StringIO
21 import StringIO
22 import inspect
22 import inspect
23 import linecache
23 import linecache
24 import os
24 import os
25 import string
25 import string
26 import sys
26 import sys
27 import types
27 import types
28 from collections import namedtuple
28 from collections import namedtuple
29 from itertools import izip_longest
29 from itertools import izip_longest
30
30
31 # IPython's own
31 # IPython's own
32 from IPython.core import page
32 from IPython.core import page
33 from IPython.external.Itpl import itpl
33 from IPython.external.Itpl import itpl
34 from IPython.utils import PyColorize
34 from IPython.utils import PyColorize
35 import IPython.utils.io
35 import IPython.utils.io
36 from IPython.utils.text import indent
36 from IPython.utils.text import indent
37 from IPython.utils.wildcard import list_namespace
37 from IPython.utils.wildcard import list_namespace
38 from IPython.utils.coloransi import *
38 from IPython.utils.coloransi import *
39
39
40 #****************************************************************************
40 #****************************************************************************
41 # Builtin color schemes
41 # Builtin color schemes
42
42
43 Colors = TermColors # just a shorthand
43 Colors = TermColors # just a shorthand
44
44
45 # Build a few color schemes
45 # Build a few color schemes
46 NoColor = ColorScheme(
46 NoColor = ColorScheme(
47 'NoColor',{
47 'NoColor',{
48 'header' : Colors.NoColor,
48 'header' : Colors.NoColor,
49 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
49 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
50 } )
50 } )
51
51
52 LinuxColors = ColorScheme(
52 LinuxColors = ColorScheme(
53 'Linux',{
53 'Linux',{
54 'header' : Colors.LightRed,
54 'header' : Colors.LightRed,
55 'normal' : Colors.Normal # color off (usu. Colors.Normal)
55 'normal' : Colors.Normal # color off (usu. Colors.Normal)
56 } )
56 } )
57
57
58 LightBGColors = ColorScheme(
58 LightBGColors = ColorScheme(
59 'LightBG',{
59 'LightBG',{
60 'header' : Colors.Red,
60 'header' : Colors.Red,
61 'normal' : Colors.Normal # color off (usu. Colors.Normal)
61 'normal' : Colors.Normal # color off (usu. Colors.Normal)
62 } )
62 } )
63
63
64 # Build table of color schemes (needed by the parser)
64 # Build table of color schemes (needed by the parser)
65 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
65 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
66 'Linux')
66 'Linux')
67
67
68 #****************************************************************************
68 #****************************************************************************
69 # Auxiliary functions and objects
69 # Auxiliary functions and objects
70
70
71 # See the messaging spec for the definition of all these fields. This list
71 # See the messaging spec for the definition of all these fields. This list
72 # effectively defines the order of display
72 # effectively defines the order of display
73 info_fields = ['type_name', 'base_class', 'string_form', 'namespace',
73 info_fields = ['type_name', 'base_class', 'string_form', 'namespace',
74 'length', 'file', 'definition', 'docstring', 'source',
74 'length', 'file', 'definition', 'docstring', 'source',
75 'init_definition', 'class_docstring', 'init_docstring',
75 'init_definition', 'class_docstring', 'init_docstring',
76 'call_def', 'call_docstring',
76 'call_def', 'call_docstring',
77 # These won't be printed but will be used to determine how to
77 # These won't be printed but will be used to determine how to
78 # format the object
78 # format the object
79 'ismagic', 'isalias', 'argspec', 'found',
79 'ismagic', 'isalias', 'argspec', 'found', 'name',
80 ]
80 ]
81
81
82
82
83 ObjectInfo = namedtuple('ObjectInfo', info_fields)
83 def object_info(**kw):
84
84 """Make an object info dict with all fields present."""
85
86 def mk_object_info(kw):
87 """Make a f"""
88 infodict = dict(izip_longest(info_fields, [None]))
85 infodict = dict(izip_longest(info_fields, [None]))
89 infodict.update(kw)
86 infodict.update(kw)
90 return ObjectInfo(**infodict)
87 return infodict
91
88
92
89
93 def getdoc(obj):
90 def getdoc(obj):
94 """Stable wrapper around inspect.getdoc.
91 """Stable wrapper around inspect.getdoc.
95
92
96 This can't crash because of attribute problems.
93 This can't crash because of attribute problems.
97
94
98 It also attempts to call a getdoc() method on the given object. This
95 It also attempts to call a getdoc() method on the given object. This
99 allows objects which provide their docstrings via non-standard mechanisms
96 allows objects which provide their docstrings via non-standard mechanisms
100 (like Pyro proxies) to still be inspected by ipython's ? system."""
97 (like Pyro proxies) to still be inspected by ipython's ? system."""
101
98
102 ds = None # default return value
99 ds = None # default return value
103 try:
100 try:
104 ds = inspect.getdoc(obj)
101 ds = inspect.getdoc(obj)
105 except:
102 except:
106 # Harden against an inspect failure, which can occur with
103 # Harden against an inspect failure, which can occur with
107 # SWIG-wrapped extensions.
104 # SWIG-wrapped extensions.
108 pass
105 pass
109 # Allow objects to offer customized documentation via a getdoc method:
106 # Allow objects to offer customized documentation via a getdoc method:
110 try:
107 try:
111 ds2 = obj.getdoc()
108 ds2 = obj.getdoc()
112 except:
109 except:
113 pass
110 pass
114 else:
111 else:
115 # if we get extra info, we add it to the normal docstring.
112 # if we get extra info, we add it to the normal docstring.
116 if ds is None:
113 if ds is None:
117 ds = ds2
114 ds = ds2
118 else:
115 else:
119 ds = '%s\n%s' % (ds,ds2)
116 ds = '%s\n%s' % (ds,ds2)
120 return ds
117 return ds
121
118
122
119
123 def getsource(obj,is_binary=False):
120 def getsource(obj,is_binary=False):
124 """Wrapper around inspect.getsource.
121 """Wrapper around inspect.getsource.
125
122
126 This can be modified by other projects to provide customized source
123 This can be modified by other projects to provide customized source
127 extraction.
124 extraction.
128
125
129 Inputs:
126 Inputs:
130
127
131 - obj: an object whose source code we will attempt to extract.
128 - obj: an object whose source code we will attempt to extract.
132
129
133 Optional inputs:
130 Optional inputs:
134
131
135 - is_binary: whether the object is known to come from a binary source.
132 - is_binary: whether the object is known to come from a binary source.
136 This implementation will skip returning any output for binary objects, but
133 This implementation will skip returning any output for binary objects, but
137 custom extractors may know how to meaningfully process them."""
134 custom extractors may know how to meaningfully process them."""
138
135
139 if is_binary:
136 if is_binary:
140 return None
137 return None
141 else:
138 else:
142 try:
139 try:
143 src = inspect.getsource(obj)
140 src = inspect.getsource(obj)
144 except TypeError:
141 except TypeError:
145 if hasattr(obj,'__class__'):
142 if hasattr(obj,'__class__'):
146 src = inspect.getsource(obj.__class__)
143 src = inspect.getsource(obj.__class__)
147 return src
144 return src
148
145
149 def getargspec(obj):
146 def getargspec(obj):
150 """Get the names and default values of a function's arguments.
147 """Get the names and default values of a function's arguments.
151
148
152 A tuple of four things is returned: (args, varargs, varkw, defaults).
149 A tuple of four things is returned: (args, varargs, varkw, defaults).
153 'args' is a list of the argument names (it may contain nested lists).
150 'args' is a list of the argument names (it may contain nested lists).
154 'varargs' and 'varkw' are the names of the * and ** arguments or None.
151 'varargs' and 'varkw' are the names of the * and ** arguments or None.
155 'defaults' is an n-tuple of the default values of the last n arguments.
152 'defaults' is an n-tuple of the default values of the last n arguments.
156
153
157 Modified version of inspect.getargspec from the Python Standard
154 Modified version of inspect.getargspec from the Python Standard
158 Library."""
155 Library."""
159
156
160 if inspect.isfunction(obj):
157 if inspect.isfunction(obj):
161 func_obj = obj
158 func_obj = obj
162 elif inspect.ismethod(obj):
159 elif inspect.ismethod(obj):
163 func_obj = obj.im_func
160 func_obj = obj.im_func
161 elif hasattr(obj, '__call__'):
162 func_obj = obj.__call__
164 else:
163 else:
165 raise TypeError('arg is not a Python function')
164 raise TypeError('arg is not a Python function')
166 args, varargs, varkw = inspect.getargs(func_obj.func_code)
165 args, varargs, varkw = inspect.getargs(func_obj.func_code)
167 return args, varargs, varkw, func_obj.func_defaults
166 return args, varargs, varkw, func_obj.func_defaults
168
167
168
169 def format_argspec(argspec):
170 """Format argspect, convenience wrapper around inspect's.
171
172 This takes a dict instead of ordered arguments and calls
173 inspect.format_argspec with the arguments in the necessary order.
174 """
175 return inspect.formatargspec(argspec['args'], argspec['varargs'],
176 argspec['varkw'], argspec['defaults'])
177
178
179 def call_tip(oinfo, format_call=True):
180 """Extract call tip data from an oinfo dict.
181
182 Parameters
183 ----------
184 oinfo : dict
185
186 format_call : bool, optional
187 If True, the call line is formatted and returned as a string. If not, a
188 tuple of (name, argspec) is returned.
189
190 Returns
191 -------
192 call_info : None, str or (str, dict) tuple.
193 When format_call is True, the whole call information is formattted as a
194 single string. Otherwise, the object's name and its argspec dict are
195 returned. If no call information is available, None is returned.
196
197 docstring : str or None
198 The most relevant docstring for calling purposes is returned, if
199 available. The priority is: call docstring for callable instances, then
200 constructor docstring for classes, then main object's docstring otherwise
201 (regular functions).
202 """
203 # Get call definition
204 argspec = oinfo['argspec']
205 if argspec is None:
206 call_line = None
207 else:
208 # Callable objects will have 'self' as their first argument, prune
209 # it out if it's there for clarity (since users do *not* pass an
210 # extra first argument explicitly).
211 try:
212 has_self = argspec['args'][0] == 'self'
213 except (KeyError, IndexError):
214 pass
215 else:
216 if has_self:
217 argspec['args'] = argspec['args'][1:]
218
219 call_line = oinfo['name']+format_argspec(argspec)
220
221 # Now get docstring.
222 # The priority is: call docstring, constructor docstring, main one.
223 doc = oinfo['call_docstring']
224 if doc is None:
225 doc = oinfo['init_docstring']
226 if doc is None:
227 doc = oinfo['docstring']
228
229 return call_line, doc
230
169 #****************************************************************************
231 #****************************************************************************
170 # Class definitions
232 # Class definitions
171
233
172 class myStringIO(StringIO.StringIO):
234 class myStringIO(StringIO.StringIO):
173 """Adds a writeln method to normal StringIO."""
235 """Adds a writeln method to normal StringIO."""
174 def writeln(self,*arg,**kw):
236 def writeln(self,*arg,**kw):
175 """Does a write() and then a write('\n')"""
237 """Does a write() and then a write('\n')"""
176 self.write(*arg,**kw)
238 self.write(*arg,**kw)
177 self.write('\n')
239 self.write('\n')
178
240
179
241
180 class Inspector:
242 class Inspector:
181 def __init__(self,color_table,code_color_table,scheme,
243 def __init__(self, color_table=InspectColors,
244 code_color_table=PyColorize.ANSICodeColors,
245 scheme='NoColor',
182 str_detail_level=0):
246 str_detail_level=0):
183 self.color_table = color_table
247 self.color_table = color_table
184 self.parser = PyColorize.Parser(code_color_table,out='str')
248 self.parser = PyColorize.Parser(code_color_table,out='str')
185 self.format = self.parser.format
249 self.format = self.parser.format
186 self.str_detail_level = str_detail_level
250 self.str_detail_level = str_detail_level
187 self.set_active_scheme(scheme)
251 self.set_active_scheme(scheme)
188
252
189 def _getdef(self,obj,oname=''):
253 def _getdef(self,obj,oname=''):
190 """Return the definition header for any callable object.
254 """Return the definition header for any callable object.
191
255
192 If any exception is generated, None is returned instead and the
256 If any exception is generated, None is returned instead and the
193 exception is suppressed."""
257 exception is suppressed."""
194
258
195 try:
259 try:
196 # We need a plain string here, NOT unicode!
260 # We need a plain string here, NOT unicode!
197 hdef = oname + inspect.formatargspec(*getargspec(obj))
261 hdef = oname + inspect.formatargspec(*getargspec(obj))
198 return hdef.encode('ascii')
262 return hdef.encode('ascii')
199 except:
263 except:
200 return None
264 return None
201
265
202 def __head(self,h):
266 def __head(self,h):
203 """Return a header string with proper colors."""
267 """Return a header string with proper colors."""
204 return '%s%s%s' % (self.color_table.active_colors.header,h,
268 return '%s%s%s' % (self.color_table.active_colors.header,h,
205 self.color_table.active_colors.normal)
269 self.color_table.active_colors.normal)
206
270
207 def set_active_scheme(self,scheme):
271 def set_active_scheme(self,scheme):
208 self.color_table.set_active_scheme(scheme)
272 self.color_table.set_active_scheme(scheme)
209 self.parser.color_table.set_active_scheme(scheme)
273 self.parser.color_table.set_active_scheme(scheme)
210
274
211 def noinfo(self,msg,oname):
275 def noinfo(self,msg,oname):
212 """Generic message when no information is found."""
276 """Generic message when no information is found."""
213 print 'No %s found' % msg,
277 print 'No %s found' % msg,
214 if oname:
278 if oname:
215 print 'for %s' % oname
279 print 'for %s' % oname
216 else:
280 else:
217 print
281 print
218
282
219 def pdef(self,obj,oname=''):
283 def pdef(self,obj,oname=''):
220 """Print the definition header for any callable object.
284 """Print the definition header for any callable object.
221
285
222 If the object is a class, print the constructor information."""
286 If the object is a class, print the constructor information."""
223
287
224 if not callable(obj):
288 if not callable(obj):
225 print 'Object is not callable.'
289 print 'Object is not callable.'
226 return
290 return
227
291
228 header = ''
292 header = ''
229
293
230 if inspect.isclass(obj):
294 if inspect.isclass(obj):
231 header = self.__head('Class constructor information:\n')
295 header = self.__head('Class constructor information:\n')
232 obj = obj.__init__
296 obj = obj.__init__
233 elif type(obj) is types.InstanceType:
297 elif type(obj) is types.InstanceType:
234 obj = obj.__call__
298 obj = obj.__call__
235
299
236 output = self._getdef(obj,oname)
300 output = self._getdef(obj,oname)
237 if output is None:
301 if output is None:
238 self.noinfo('definition header',oname)
302 self.noinfo('definition header',oname)
239 else:
303 else:
240 print >>IPython.utils.io.Term.cout, header,self.format(output),
304 print >>IPython.utils.io.Term.cout, header,self.format(output),
241
305
242 def pdoc(self,obj,oname='',formatter = None):
306 def pdoc(self,obj,oname='',formatter = None):
243 """Print the docstring for any object.
307 """Print the docstring for any object.
244
308
245 Optional:
309 Optional:
246 -formatter: a function to run the docstring through for specially
310 -formatter: a function to run the docstring through for specially
247 formatted docstrings."""
311 formatted docstrings."""
248
312
249 head = self.__head # so that itpl can find it even if private
313 head = self.__head # so that itpl can find it even if private
250 ds = getdoc(obj)
314 ds = getdoc(obj)
251 if formatter:
315 if formatter:
252 ds = formatter(ds)
316 ds = formatter(ds)
253 if inspect.isclass(obj):
317 if inspect.isclass(obj):
254 init_ds = getdoc(obj.__init__)
318 init_ds = getdoc(obj.__init__)
255 output = itpl('$head("Class Docstring:")\n'
319 output = itpl('$head("Class Docstring:")\n'
256 '$indent(ds)\n'
320 '$indent(ds)\n'
257 '$head("Constructor Docstring"):\n'
321 '$head("Constructor Docstring"):\n'
258 '$indent(init_ds)')
322 '$indent(init_ds)')
259 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
323 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
260 and hasattr(obj,'__call__'):
324 and hasattr(obj,'__call__'):
261 call_ds = getdoc(obj.__call__)
325 call_ds = getdoc(obj.__call__)
262 if call_ds:
326 if call_ds:
263 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
327 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
264 '$head("Calling Docstring:")\n$indent(call_ds)')
328 '$head("Calling Docstring:")\n$indent(call_ds)')
265 else:
329 else:
266 output = ds
330 output = ds
267 else:
331 else:
268 output = ds
332 output = ds
269 if output is None:
333 if output is None:
270 self.noinfo('documentation',oname)
334 self.noinfo('documentation',oname)
271 return
335 return
272 page.page(output)
336 page.page(output)
273
337
274 def psource(self,obj,oname=''):
338 def psource(self,obj,oname=''):
275 """Print the source code for an object."""
339 """Print the source code for an object."""
276
340
277 # Flush the source cache because inspect can return out-of-date source
341 # Flush the source cache because inspect can return out-of-date source
278 linecache.checkcache()
342 linecache.checkcache()
279 try:
343 try:
280 src = getsource(obj)
344 src = getsource(obj)
281 except:
345 except:
282 self.noinfo('source',oname)
346 self.noinfo('source',oname)
283 else:
347 else:
284 page.page(self.format(src))
348 page.page(self.format(src))
285
349
286 def pfile(self,obj,oname=''):
350 def pfile(self,obj,oname=''):
287 """Show the whole file where an object was defined."""
351 """Show the whole file where an object was defined."""
288
352
289 try:
353 try:
290 try:
354 try:
291 lineno = inspect.getsourcelines(obj)[1]
355 lineno = inspect.getsourcelines(obj)[1]
292 except TypeError:
356 except TypeError:
293 # For instances, try the class object like getsource() does
357 # For instances, try the class object like getsource() does
294 if hasattr(obj,'__class__'):
358 if hasattr(obj,'__class__'):
295 lineno = inspect.getsourcelines(obj.__class__)[1]
359 lineno = inspect.getsourcelines(obj.__class__)[1]
296 # Adjust the inspected object so getabsfile() below works
360 # Adjust the inspected object so getabsfile() below works
297 obj = obj.__class__
361 obj = obj.__class__
298 except:
362 except:
299 self.noinfo('file',oname)
363 self.noinfo('file',oname)
300 return
364 return
301
365
302 # We only reach this point if object was successfully queried
366 # We only reach this point if object was successfully queried
303
367
304 # run contents of file through pager starting at line
368 # run contents of file through pager starting at line
305 # where the object is defined
369 # where the object is defined
306 ofile = inspect.getabsfile(obj)
370 ofile = inspect.getabsfile(obj)
307
371
308 if (ofile.endswith('.so') or ofile.endswith('.dll')):
372 if (ofile.endswith('.so') or ofile.endswith('.dll')):
309 print 'File %r is binary, not printing.' % ofile
373 print 'File %r is binary, not printing.' % ofile
310 elif not os.path.isfile(ofile):
374 elif not os.path.isfile(ofile):
311 print 'File %r does not exist, not printing.' % ofile
375 print 'File %r does not exist, not printing.' % ofile
312 else:
376 else:
313 # Print only text files, not extension binaries. Note that
377 # Print only text files, not extension binaries. Note that
314 # getsourcelines returns lineno with 1-offset and page() uses
378 # getsourcelines returns lineno with 1-offset and page() uses
315 # 0-offset, so we must adjust.
379 # 0-offset, so we must adjust.
316 page.page(self.format(open(ofile).read()),lineno-1)
380 page.page(self.format(open(ofile).read()),lineno-1)
317
381
318 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
382 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
319 """Show detailed information about an object.
383 """Show detailed information about an object.
320
384
321 Optional arguments:
385 Optional arguments:
322
386
323 - oname: name of the variable pointing to the object.
387 - oname: name of the variable pointing to the object.
324
388
325 - formatter: special formatter for docstrings (see pdoc)
389 - formatter: special formatter for docstrings (see pdoc)
326
390
327 - info: a structure with some information fields which may have been
391 - info: a structure with some information fields which may have been
328 precomputed already.
392 precomputed already.
329
393
330 - detail_level: if set to 1, more information is given.
394 - detail_level: if set to 1, more information is given.
331 """
395 """
332
396
333 obj_type = type(obj)
397 obj_type = type(obj)
334
398
335 header = self.__head
399 header = self.__head
336 if info is None:
400 if info is None:
337 ismagic = 0
401 ismagic = 0
338 isalias = 0
402 isalias = 0
339 ospace = ''
403 ospace = ''
340 else:
404 else:
341 ismagic = info.ismagic
405 ismagic = info.ismagic
342 isalias = info.isalias
406 isalias = info.isalias
343 ospace = info.namespace
407 ospace = info.namespace
344 # Get docstring, special-casing aliases:
408 # Get docstring, special-casing aliases:
345 if isalias:
409 if isalias:
346 if not callable(obj):
410 if not callable(obj):
347 try:
411 try:
348 ds = "Alias to the system command:\n %s" % obj[1]
412 ds = "Alias to the system command:\n %s" % obj[1]
349 except:
413 except:
350 ds = "Alias: " + str(obj)
414 ds = "Alias: " + str(obj)
351 else:
415 else:
352 ds = "Alias to " + str(obj)
416 ds = "Alias to " + str(obj)
353 if obj.__doc__:
417 if obj.__doc__:
354 ds += "\nDocstring:\n" + obj.__doc__
418 ds += "\nDocstring:\n" + obj.__doc__
355 else:
419 else:
356 ds = getdoc(obj)
420 ds = getdoc(obj)
357 if ds is None:
421 if ds is None:
358 ds = '<no docstring>'
422 ds = '<no docstring>'
359 if formatter is not None:
423 if formatter is not None:
360 ds = formatter(ds)
424 ds = formatter(ds)
361
425
362 # store output in a list which gets joined with \n at the end.
426 # store output in a list which gets joined with \n at the end.
363 out = myStringIO()
427 out = myStringIO()
364
428
365 string_max = 200 # max size of strings to show (snipped if longer)
429 string_max = 200 # max size of strings to show (snipped if longer)
366 shalf = int((string_max -5)/2)
430 shalf = int((string_max -5)/2)
367
431
368 if ismagic:
432 if ismagic:
369 obj_type_name = 'Magic function'
433 obj_type_name = 'Magic function'
370 elif isalias:
434 elif isalias:
371 obj_type_name = 'System alias'
435 obj_type_name = 'System alias'
372 else:
436 else:
373 obj_type_name = obj_type.__name__
437 obj_type_name = obj_type.__name__
374 out.writeln(header('Type:\t\t')+obj_type_name)
438 out.writeln(header('Type:\t\t')+obj_type_name)
375
439
376 try:
440 try:
377 bclass = obj.__class__
441 bclass = obj.__class__
378 out.writeln(header('Base Class:\t')+str(bclass))
442 out.writeln(header('Base Class:\t')+str(bclass))
379 except: pass
443 except: pass
380
444
381 # String form, but snip if too long in ? form (full in ??)
445 # String form, but snip if too long in ? form (full in ??)
382 if detail_level >= self.str_detail_level:
446 if detail_level >= self.str_detail_level:
383 try:
447 try:
384 ostr = str(obj)
448 ostr = str(obj)
385 str_head = 'String Form:'
449 str_head = 'String Form:'
386 if not detail_level and len(ostr)>string_max:
450 if not detail_level and len(ostr)>string_max:
387 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
451 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
388 ostr = ("\n" + " " * len(str_head.expandtabs())).\
452 ostr = ("\n" + " " * len(str_head.expandtabs())).\
389 join(map(string.strip,ostr.split("\n")))
453 join(map(string.strip,ostr.split("\n")))
390 if ostr.find('\n') > -1:
454 if ostr.find('\n') > -1:
391 # Print multi-line strings starting at the next line.
455 # Print multi-line strings starting at the next line.
392 str_sep = '\n'
456 str_sep = '\n'
393 else:
457 else:
394 str_sep = '\t'
458 str_sep = '\t'
395 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
459 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
396 except:
460 except:
397 pass
461 pass
398
462
399 if ospace:
463 if ospace:
400 out.writeln(header('Namespace:\t')+ospace)
464 out.writeln(header('Namespace:\t')+ospace)
401
465
402 # Length (for strings and lists)
466 # Length (for strings and lists)
403 try:
467 try:
404 length = str(len(obj))
468 length = str(len(obj))
405 out.writeln(header('Length:\t\t')+length)
469 out.writeln(header('Length:\t\t')+length)
406 except: pass
470 except: pass
407
471
408 # Filename where object was defined
472 # Filename where object was defined
409 binary_file = False
473 binary_file = False
410 try:
474 try:
411 try:
475 try:
412 fname = inspect.getabsfile(obj)
476 fname = inspect.getabsfile(obj)
413 except TypeError:
477 except TypeError:
414 # For an instance, the file that matters is where its class was
478 # For an instance, the file that matters is where its class was
415 # declared.
479 # declared.
416 if hasattr(obj,'__class__'):
480 if hasattr(obj,'__class__'):
417 fname = inspect.getabsfile(obj.__class__)
481 fname = inspect.getabsfile(obj.__class__)
418 if fname.endswith('<string>'):
482 if fname.endswith('<string>'):
419 fname = 'Dynamically generated function. No source code available.'
483 fname = 'Dynamically generated function. No source code available.'
420 if (fname.endswith('.so') or fname.endswith('.dll')):
484 if (fname.endswith('.so') or fname.endswith('.dll')):
421 binary_file = True
485 binary_file = True
422 out.writeln(header('File:\t\t')+fname)
486 out.writeln(header('File:\t\t')+fname)
423 except:
487 except:
424 # if anything goes wrong, we don't want to show source, so it's as
488 # if anything goes wrong, we don't want to show source, so it's as
425 # if the file was binary
489 # if the file was binary
426 binary_file = True
490 binary_file = True
427
491
428 # reconstruct the function definition and print it:
492 # reconstruct the function definition and print it:
429 defln = self._getdef(obj,oname)
493 defln = self._getdef(obj,oname)
430 if defln:
494 if defln:
431 out.write(header('Definition:\t')+self.format(defln))
495 out.write(header('Definition:\t')+self.format(defln))
432
496
433 # Docstrings only in detail 0 mode, since source contains them (we
497 # Docstrings only in detail 0 mode, since source contains them (we
434 # avoid repetitions). If source fails, we add them back, see below.
498 # avoid repetitions). If source fails, we add them back, see below.
435 if ds and detail_level == 0:
499 if ds and detail_level == 0:
436 out.writeln(header('Docstring:\n') + indent(ds))
500 out.writeln(header('Docstring:\n') + indent(ds))
437
501
438 # Original source code for any callable
502 # Original source code for any callable
439 if detail_level:
503 if detail_level:
440 # Flush the source cache because inspect can return out-of-date
504 # Flush the source cache because inspect can return out-of-date
441 # source
505 # source
442 linecache.checkcache()
506 linecache.checkcache()
443 source_success = False
507 source_success = False
444 try:
508 try:
445 try:
509 try:
446 src = getsource(obj,binary_file)
510 src = getsource(obj,binary_file)
447 except TypeError:
511 except TypeError:
448 if hasattr(obj,'__class__'):
512 if hasattr(obj,'__class__'):
449 src = getsource(obj.__class__,binary_file)
513 src = getsource(obj.__class__,binary_file)
450 if src is not None:
514 if src is not None:
451 source = self.format(src)
515 source = self.format(src)
452 out.write(header('Source:\n')+source.rstrip())
516 out.write(header('Source:\n')+source.rstrip())
453 source_success = True
517 source_success = True
454 except Exception, msg:
518 except Exception, msg:
455 pass
519 pass
456
520
457 if ds and not source_success:
521 if ds and not source_success:
458 out.writeln(header('Docstring [source file open failed]:\n')
522 out.writeln(header('Docstring [source file open failed]:\n')
459 + indent(ds))
523 + indent(ds))
460
524
461 # Constructor docstring for classes
525 # Constructor docstring for classes
462 if inspect.isclass(obj):
526 if inspect.isclass(obj):
463 # reconstruct the function definition and print it:
527 # reconstruct the function definition and print it:
464 try:
528 try:
465 obj_init = obj.__init__
529 obj_init = obj.__init__
466 except AttributeError:
530 except AttributeError:
467 init_def = init_ds = None
531 init_def = init_ds = None
468 else:
532 else:
469 init_def = self._getdef(obj_init,oname)
533 init_def = self._getdef(obj_init,oname)
470 init_ds = getdoc(obj_init)
534 init_ds = getdoc(obj_init)
471 # Skip Python's auto-generated docstrings
535 # Skip Python's auto-generated docstrings
472 if init_ds and \
536 if init_ds and \
473 init_ds.startswith('x.__init__(...) initializes'):
537 init_ds.startswith('x.__init__(...) initializes'):
474 init_ds = None
538 init_ds = None
475
539
476 if init_def or init_ds:
540 if init_def or init_ds:
477 out.writeln(header('\nConstructor information:'))
541 out.writeln(header('\nConstructor information:'))
478 if init_def:
542 if init_def:
479 out.write(header('Definition:\t')+ self.format(init_def))
543 out.write(header('Definition:\t')+ self.format(init_def))
480 if init_ds:
544 if init_ds:
481 out.writeln(header('Docstring:\n') + indent(init_ds))
545 out.writeln(header('Docstring:\n') + indent(init_ds))
482 # and class docstring for instances:
546 # and class docstring for instances:
483 elif obj_type is types.InstanceType or \
547 elif obj_type is types.InstanceType or \
484 isinstance(obj,object):
548 isinstance(obj,object):
485
549
486 # First, check whether the instance docstring is identical to the
550 # First, check whether the instance docstring is identical to the
487 # class one, and print it separately if they don't coincide. In
551 # class one, and print it separately if they don't coincide. In
488 # most cases they will, but it's nice to print all the info for
552 # most cases they will, but it's nice to print all the info for
489 # objects which use instance-customized docstrings.
553 # objects which use instance-customized docstrings.
490 if ds:
554 if ds:
491 try:
555 try:
492 cls = getattr(obj,'__class__')
556 cls = getattr(obj,'__class__')
493 except:
557 except:
494 class_ds = None
558 class_ds = None
495 else:
559 else:
496 class_ds = getdoc(cls)
560 class_ds = getdoc(cls)
497 # Skip Python's auto-generated docstrings
561 # Skip Python's auto-generated docstrings
498 if class_ds and \
562 if class_ds and \
499 (class_ds.startswith('function(code, globals[,') or \
563 (class_ds.startswith('function(code, globals[,') or \
500 class_ds.startswith('instancemethod(function, instance,') or \
564 class_ds.startswith('instancemethod(function, instance,') or \
501 class_ds.startswith('module(name[,') ):
565 class_ds.startswith('module(name[,') ):
502 class_ds = None
566 class_ds = None
503 if class_ds and ds != class_ds:
567 if class_ds and ds != class_ds:
504 out.writeln(header('Class Docstring:\n') +
568 out.writeln(header('Class Docstring:\n') +
505 indent(class_ds))
569 indent(class_ds))
506
570
507 # Next, try to show constructor docstrings
571 # Next, try to show constructor docstrings
508 try:
572 try:
509 init_ds = getdoc(obj.__init__)
573 init_ds = getdoc(obj.__init__)
510 # Skip Python's auto-generated docstrings
574 # Skip Python's auto-generated docstrings
511 if init_ds and \
575 if init_ds and \
512 init_ds.startswith('x.__init__(...) initializes'):
576 init_ds.startswith('x.__init__(...) initializes'):
513 init_ds = None
577 init_ds = None
514 except AttributeError:
578 except AttributeError:
515 init_ds = None
579 init_ds = None
516 if init_ds:
580 if init_ds:
517 out.writeln(header('Constructor Docstring:\n') +
581 out.writeln(header('Constructor Docstring:\n') +
518 indent(init_ds))
582 indent(init_ds))
519
583
520 # Call form docstring for callable instances
584 # Call form docstring for callable instances
521 if hasattr(obj,'__call__'):
585 if hasattr(obj,'__call__'):
522 #out.writeln(header('Callable:\t')+'Yes')
586 #out.writeln(header('Callable:\t')+'Yes')
523 call_def = self._getdef(obj.__call__,oname)
587 call_def = self._getdef(obj.__call__,oname)
524 #if call_def is None:
588 #if call_def is None:
525 # out.writeln(header('Call def:\t')+
589 # out.writeln(header('Call def:\t')+
526 # 'Calling definition not available.')
590 # 'Calling definition not available.')
527 if call_def is not None:
591 if call_def is not None:
528 out.writeln(header('Call def:\t')+self.format(call_def))
592 out.writeln(header('Call def:\t')+self.format(call_def))
529 call_ds = getdoc(obj.__call__)
593 call_ds = getdoc(obj.__call__)
530 # Skip Python's auto-generated docstrings
594 # Skip Python's auto-generated docstrings
531 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
595 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
532 call_ds = None
596 call_ds = None
533 if call_ds:
597 if call_ds:
534 out.writeln(header('Call docstring:\n') + indent(call_ds))
598 out.writeln(header('Call docstring:\n') + indent(call_ds))
535
599
536 # Finally send to printer/pager
600 # Finally send to printer/pager
537 output = out.getvalue()
601 output = out.getvalue()
538 if output:
602 if output:
539 page.page(output)
603 page.page(output)
540 # end pinfo
604 # end pinfo
541
605
542 def info(self, obj, oname='', formatter=None, info=None, detail_level=0):
606 def info(self, obj, oname='', formatter=None, info=None, detail_level=0):
543 """Compute a dict with detailed information about an object.
607 """Compute a dict with detailed information about an object.
544
608
545 Optional arguments:
609 Optional arguments:
546
610
547 - oname: name of the variable pointing to the object.
611 - oname: name of the variable pointing to the object.
548
612
549 - formatter: special formatter for docstrings (see pdoc)
613 - formatter: special formatter for docstrings (see pdoc)
550
614
551 - info: a structure with some information fields which may have been
615 - info: a structure with some information fields which may have been
552 precomputed already.
616 precomputed already.
553
617
554 - detail_level: if set to 1, more information is given.
618 - detail_level: if set to 1, more information is given.
555 """
619 """
556
620
557 obj_type = type(obj)
621 obj_type = type(obj)
558
622
559 header = self.__head
623 header = self.__head
560 if info is None:
624 if info is None:
561 ismagic = 0
625 ismagic = 0
562 isalias = 0
626 isalias = 0
563 ospace = ''
627 ospace = ''
564 else:
628 else:
565 ismagic = info.ismagic
629 ismagic = info.ismagic
566 isalias = info.isalias
630 isalias = info.isalias
567 ospace = info.namespace
631 ospace = info.namespace
632
568 # Get docstring, special-casing aliases:
633 # Get docstring, special-casing aliases:
569 if isalias:
634 if isalias:
570 if not callable(obj):
635 if not callable(obj):
571 try:
636 try:
572 ds = "Alias to the system command:\n %s" % obj[1]
637 ds = "Alias to the system command:\n %s" % obj[1]
573 except:
638 except:
574 ds = "Alias: " + str(obj)
639 ds = "Alias: " + str(obj)
575 else:
640 else:
576 ds = "Alias to " + str(obj)
641 ds = "Alias to " + str(obj)
577 if obj.__doc__:
642 if obj.__doc__:
578 ds += "\nDocstring:\n" + obj.__doc__
643 ds += "\nDocstring:\n" + obj.__doc__
579 else:
644 else:
580 ds = getdoc(obj)
645 ds = getdoc(obj)
581 if ds is None:
646 if ds is None:
582 ds = '<no docstring>'
647 ds = '<no docstring>'
583 if formatter is not None:
648 if formatter is not None:
584 ds = formatter(ds)
649 ds = formatter(ds)
585
650
586 # store output in a dict, we'll later convert it to an ObjectInfo. We
651 # store output in a dict, we initialize it here and fill it as we go
587 # initialize it here and fill it as we go
652 out = dict(name=oname, found=True, isalias=isalias, ismagic=ismagic)
588 out = dict(found=True, isalias=isalias, ismagic=ismagic)
589
653
590 string_max = 200 # max size of strings to show (snipped if longer)
654 string_max = 200 # max size of strings to show (snipped if longer)
591 shalf = int((string_max -5)/2)
655 shalf = int((string_max -5)/2)
592
656
593 if ismagic:
657 if ismagic:
594 obj_type_name = 'Magic function'
658 obj_type_name = 'Magic function'
595 elif isalias:
659 elif isalias:
596 obj_type_name = 'System alias'
660 obj_type_name = 'System alias'
597 else:
661 else:
598 obj_type_name = obj_type.__name__
662 obj_type_name = obj_type.__name__
599 out['type_name'] = obj_type_name
663 out['type_name'] = obj_type_name
600
664
601 try:
665 try:
602 bclass = obj.__class__
666 bclass = obj.__class__
603 out['base_class'] = str(bclass)
667 out['base_class'] = str(bclass)
604 except: pass
668 except: pass
605
669
606 # String form, but snip if too long in ? form (full in ??)
670 # String form, but snip if too long in ? form (full in ??)
607 if detail_level >= self.str_detail_level:
671 if detail_level >= self.str_detail_level:
608 try:
672 try:
609 ostr = str(obj)
673 ostr = str(obj)
610 str_head = 'string_form'
674 str_head = 'string_form'
611 if not detail_level and len(ostr)>string_max:
675 if not detail_level and len(ostr)>string_max:
612 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
676 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
613 ostr = ("\n" + " " * len(str_head.expandtabs())).\
677 ostr = ("\n" + " " * len(str_head.expandtabs())).\
614 join(map(string.strip,ostr.split("\n")))
678 join(map(string.strip,ostr.split("\n")))
615 if ostr.find('\n') > -1:
679 if ostr.find('\n') > -1:
616 # Print multi-line strings starting at the next line.
680 # Print multi-line strings starting at the next line.
617 str_sep = '\n'
681 str_sep = '\n'
618 else:
682 else:
619 str_sep = '\t'
683 str_sep = '\t'
620 out[str_head] = ostr
684 out[str_head] = ostr
621 except:
685 except:
622 pass
686 pass
623
687
624 if ospace:
688 if ospace:
625 out['namespace'] = ospace
689 out['namespace'] = ospace
626
690
627 # Length (for strings and lists)
691 # Length (for strings and lists)
628 try:
692 try:
629 out['length'] = str(len(obj))
693 out['length'] = str(len(obj))
630 except: pass
694 except: pass
631
695
632 # Filename where object was defined
696 # Filename where object was defined
633 binary_file = False
697 binary_file = False
634 try:
698 try:
635 try:
699 try:
636 fname = inspect.getabsfile(obj)
700 fname = inspect.getabsfile(obj)
637 except TypeError:
701 except TypeError:
638 # For an instance, the file that matters is where its class was
702 # For an instance, the file that matters is where its class was
639 # declared.
703 # declared.
640 if hasattr(obj,'__class__'):
704 if hasattr(obj,'__class__'):
641 fname = inspect.getabsfile(obj.__class__)
705 fname = inspect.getabsfile(obj.__class__)
642 if fname.endswith('<string>'):
706 if fname.endswith('<string>'):
643 fname = 'Dynamically generated function. No source code available.'
707 fname = 'Dynamically generated function. No source code available.'
644 if (fname.endswith('.so') or fname.endswith('.dll')):
708 if (fname.endswith('.so') or fname.endswith('.dll')):
645 binary_file = True
709 binary_file = True
646 out['file'] = fname
710 out['file'] = fname
647 except:
711 except:
648 # if anything goes wrong, we don't want to show source, so it's as
712 # if anything goes wrong, we don't want to show source, so it's as
649 # if the file was binary
713 # if the file was binary
650 binary_file = True
714 binary_file = True
651
715
652 # reconstruct the function definition and print it:
716 # reconstruct the function definition and print it:
653 defln = self._getdef(obj,oname)
717 defln = self._getdef(obj, oname)
654 if defln:
718 if defln:
655 out['definition'] = self.format(defln)
719 out['definition'] = self.format(defln)
656 args, varargs, varkw, func_defaults = getargspec(obj)
657 out['argspec'] = dict(args=args, varargs=varargs,
658 varkw=varkw, func_defaults=func_defaults)
659
720
660 # Docstrings only in detail 0 mode, since source contains them (we
721 # Docstrings only in detail 0 mode, since source contains them (we
661 # avoid repetitions). If source fails, we add them back, see below.
722 # avoid repetitions). If source fails, we add them back, see below.
662 if ds and detail_level == 0:
723 if ds and detail_level == 0:
663 out['docstring'] = indent(ds)
724 out['docstring'] = ds
664
725
665 # Original source code for any callable
726 # Original source code for any callable
666 if detail_level:
727 if detail_level:
667 # Flush the source cache because inspect can return out-of-date
728 # Flush the source cache because inspect can return out-of-date
668 # source
729 # source
669 linecache.checkcache()
730 linecache.checkcache()
670 source_success = False
731 source_success = False
671 try:
732 try:
672 try:
733 try:
673 src = getsource(obj,binary_file)
734 src = getsource(obj,binary_file)
674 except TypeError:
735 except TypeError:
675 if hasattr(obj,'__class__'):
736 if hasattr(obj,'__class__'):
676 src = getsource(obj.__class__,binary_file)
737 src = getsource(obj.__class__,binary_file)
677 if src is not None:
738 if src is not None:
678 source = self.format(src)
739 source = self.format(src)
679 out['source'] = source.rstrip()
740 out['source'] = source.rstrip()
680 source_success = True
741 source_success = True
681 except Exception, msg:
742 except Exception, msg:
682 pass
743 pass
683
744
684 # Constructor docstring for classes
745 # Constructor docstring for classes
685 if inspect.isclass(obj):
746 if inspect.isclass(obj):
686 # reconstruct the function definition and print it:
747 # reconstruct the function definition and print it:
687 try:
748 try:
688 obj_init = obj.__init__
749 obj_init = obj.__init__
689 except AttributeError:
750 except AttributeError:
690 init_def = init_ds = None
751 init_def = init_ds = None
691 else:
752 else:
692 init_def = self._getdef(obj_init,oname)
753 init_def = self._getdef(obj_init,oname)
693 init_ds = getdoc(obj_init)
754 init_ds = getdoc(obj_init)
694 # Skip Python's auto-generated docstrings
755 # Skip Python's auto-generated docstrings
695 if init_ds and \
756 if init_ds and \
696 init_ds.startswith('x.__init__(...) initializes'):
757 init_ds.startswith('x.__init__(...) initializes'):
697 init_ds = None
758 init_ds = None
698
759
699 if init_def or init_ds:
760 if init_def or init_ds:
700 if init_def:
761 if init_def:
701 out['init_definition'] = self.format(init_def)
762 out['init_definition'] = self.format(init_def)
702 if init_ds:
763 if init_ds:
703 out['init_docstring'] = indent(init_ds)
764 out['init_docstring'] = init_ds
765
704 # and class docstring for instances:
766 # and class docstring for instances:
705 elif obj_type is types.InstanceType or \
767 elif obj_type is types.InstanceType or \
706 isinstance(obj,object):
768 isinstance(obj, object):
707
708 # First, check whether the instance docstring is identical to the
769 # First, check whether the instance docstring is identical to the
709 # class one, and print it separately if they don't coincide. In
770 # class one, and print it separately if they don't coincide. In
710 # most cases they will, but it's nice to print all the info for
771 # most cases they will, but it's nice to print all the info for
711 # objects which use instance-customized docstrings.
772 # objects which use instance-customized docstrings.
712 if ds:
773 if ds:
713 try:
774 try:
714 cls = getattr(obj,'__class__')
775 cls = getattr(obj,'__class__')
715 except:
776 except:
716 class_ds = None
777 class_ds = None
717 else:
778 else:
718 class_ds = getdoc(cls)
779 class_ds = getdoc(cls)
719 # Skip Python's auto-generated docstrings
780 # Skip Python's auto-generated docstrings
720 if class_ds and \
781 if class_ds and \
721 (class_ds.startswith('function(code, globals[,') or \
782 (class_ds.startswith('function(code, globals[,') or \
722 class_ds.startswith('instancemethod(function, instance,') or \
783 class_ds.startswith('instancemethod(function, instance,') or \
723 class_ds.startswith('module(name[,') ):
784 class_ds.startswith('module(name[,') ):
724 class_ds = None
785 class_ds = None
725 if class_ds and ds != class_ds:
786 if class_ds and ds != class_ds:
726 out['class_docstring'] = indent(class_ds)
787 out['class_docstring'] = class_ds
727
788
728 # Next, try to show constructor docstrings
789 # Next, try to show constructor docstrings
729 try:
790 try:
730 init_ds = getdoc(obj.__init__)
791 init_ds = getdoc(obj.__init__)
731 # Skip Python's auto-generated docstrings
792 # Skip Python's auto-generated docstrings
732 if init_ds and \
793 if init_ds and \
733 init_ds.startswith('x.__init__(...) initializes'):
794 init_ds.startswith('x.__init__(...) initializes'):
734 init_ds = None
795 init_ds = None
735 except AttributeError:
796 except AttributeError:
736 init_ds = None
797 init_ds = None
737 if init_ds:
798 if init_ds:
738 out['init_docstring'] = indent(init_ds)
799 out['init_docstring'] = init_ds
739
800
740 # Call form docstring for callable instances
801 # Call form docstring for callable instances
741 if hasattr(obj,'__call__'):
802 if hasattr(obj, '__call__'):
742 call_def = self._getdef(obj.__call__,oname)
803 call_def = self._getdef(obj.__call__, oname)
743 if call_def is not None:
804 if call_def is not None:
744 out['call_def'] = self.format(call_def)
805 out['call_def'] = self.format(call_def)
745 call_ds = getdoc(obj.__call__)
806 call_ds = getdoc(obj.__call__)
746 # Skip Python's auto-generated docstrings
807 # Skip Python's auto-generated docstrings
747 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
808 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
748 call_ds = None
809 call_ds = None
749 if call_ds:
810 if call_ds:
750 out['call_docstring'] = indent(call_ds)
811 out['call_docstring'] = call_ds
812
813 # Compute the object's argspec as a callable. The key is to decide
814 # whether to pull it from the object itself, from its __init__ or
815 # from its __call__ method.
816
817 if inspect.isclass(obj):
818 callable_obj = obj.__init__
819 elif callable(obj):
820 callable_obj = obj
821 else:
822 callable_obj = None
823
824 if callable_obj:
825 try:
826 args, varargs, varkw, defaults = getargspec(callable_obj)
827 except (TypeError, AttributeError):
828 # For extensions/builtins we can't retrieve the argspec
829 pass
830 else:
831 out['argspec'] = dict(args=args, varargs=varargs,
832 varkw=varkw, defaults=defaults)
751
833
752 return mk_object_info(out)
834 return object_info(**out)
753
835
754
836
755 def psearch(self,pattern,ns_table,ns_search=[],
837 def psearch(self,pattern,ns_table,ns_search=[],
756 ignore_case=False,show_all=False):
838 ignore_case=False,show_all=False):
757 """Search namespaces with wildcards for objects.
839 """Search namespaces with wildcards for objects.
758
840
759 Arguments:
841 Arguments:
760
842
761 - pattern: string containing shell-like wildcards to use in namespace
843 - pattern: string containing shell-like wildcards to use in namespace
762 searches and optionally a type specification to narrow the search to
844 searches and optionally a type specification to narrow the search to
763 objects of that type.
845 objects of that type.
764
846
765 - ns_table: dict of name->namespaces for search.
847 - ns_table: dict of name->namespaces for search.
766
848
767 Optional arguments:
849 Optional arguments:
768
850
769 - ns_search: list of namespace names to include in search.
851 - ns_search: list of namespace names to include in search.
770
852
771 - ignore_case(False): make the search case-insensitive.
853 - ignore_case(False): make the search case-insensitive.
772
854
773 - show_all(False): show all names, including those starting with
855 - show_all(False): show all names, including those starting with
774 underscores.
856 underscores.
775 """
857 """
776 #print 'ps pattern:<%r>' % pattern # dbg
858 #print 'ps pattern:<%r>' % pattern # dbg
777
859
778 # defaults
860 # defaults
779 type_pattern = 'all'
861 type_pattern = 'all'
780 filter = ''
862 filter = ''
781
863
782 cmds = pattern.split()
864 cmds = pattern.split()
783 len_cmds = len(cmds)
865 len_cmds = len(cmds)
784 if len_cmds == 1:
866 if len_cmds == 1:
785 # Only filter pattern given
867 # Only filter pattern given
786 filter = cmds[0]
868 filter = cmds[0]
787 elif len_cmds == 2:
869 elif len_cmds == 2:
788 # Both filter and type specified
870 # Both filter and type specified
789 filter,type_pattern = cmds
871 filter,type_pattern = cmds
790 else:
872 else:
791 raise ValueError('invalid argument string for psearch: <%s>' %
873 raise ValueError('invalid argument string for psearch: <%s>' %
792 pattern)
874 pattern)
793
875
794 # filter search namespaces
876 # filter search namespaces
795 for name in ns_search:
877 for name in ns_search:
796 if name not in ns_table:
878 if name not in ns_table:
797 raise ValueError('invalid namespace <%s>. Valid names: %s' %
879 raise ValueError('invalid namespace <%s>. Valid names: %s' %
798 (name,ns_table.keys()))
880 (name,ns_table.keys()))
799
881
800 #print 'type_pattern:',type_pattern # dbg
882 #print 'type_pattern:',type_pattern # dbg
801 search_result = []
883 search_result = []
802 for ns_name in ns_search:
884 for ns_name in ns_search:
803 ns = ns_table[ns_name]
885 ns = ns_table[ns_name]
804 tmp_res = list(list_namespace(ns,type_pattern,filter,
886 tmp_res = list(list_namespace(ns,type_pattern,filter,
805 ignore_case=ignore_case,
887 ignore_case=ignore_case,
806 show_all=show_all))
888 show_all=show_all))
807 search_result.extend(tmp_res)
889 search_result.extend(tmp_res)
808 search_result.sort()
890 search_result.sort()
809
891
810 page.page('\n'.join(search_result))
892 page.page('\n'.join(search_result))
@@ -1,220 +1,225 b''
1 # Standard library imports
1 # Standard library imports
2 import re
2 import re
3 from textwrap import dedent
3 from textwrap import dedent
4
4
5 # System library imports
5 # System library imports
6 from PyQt4 import QtCore, QtGui
6 from PyQt4 import QtCore, QtGui
7
7
8
8
9 class CallTipWidget(QtGui.QLabel):
9 class CallTipWidget(QtGui.QLabel):
10 """ Shows call tips by parsing the current text of Q[Plain]TextEdit.
10 """ Shows call tips by parsing the current text of Q[Plain]TextEdit.
11 """
11 """
12
12
13 #--------------------------------------------------------------------------
13 #--------------------------------------------------------------------------
14 # 'QObject' interface
14 # 'QObject' interface
15 #--------------------------------------------------------------------------
15 #--------------------------------------------------------------------------
16
16
17 def __init__(self, text_edit):
17 def __init__(self, text_edit):
18 """ Create a call tip manager that is attached to the specified Qt
18 """ Create a call tip manager that is attached to the specified Qt
19 text edit widget.
19 text edit widget.
20 """
20 """
21 assert isinstance(text_edit, (QtGui.QTextEdit, QtGui.QPlainTextEdit))
21 assert isinstance(text_edit, (QtGui.QTextEdit, QtGui.QPlainTextEdit))
22 super(CallTipWidget, self).__init__(None, QtCore.Qt.ToolTip)
22 super(CallTipWidget, self).__init__(None, QtCore.Qt.ToolTip)
23
23
24 self._hide_timer = QtCore.QBasicTimer()
24 self._hide_timer = QtCore.QBasicTimer()
25 self._text_edit = text_edit
25 self._text_edit = text_edit
26
26
27 self.setFont(text_edit.document().defaultFont())
27 self.setFont(text_edit.document().defaultFont())
28 self.setForegroundRole(QtGui.QPalette.ToolTipText)
28 self.setForegroundRole(QtGui.QPalette.ToolTipText)
29 self.setBackgroundRole(QtGui.QPalette.ToolTipBase)
29 self.setBackgroundRole(QtGui.QPalette.ToolTipBase)
30 self.setPalette(QtGui.QToolTip.palette())
30 self.setPalette(QtGui.QToolTip.palette())
31
31
32 self.setAlignment(QtCore.Qt.AlignLeft)
32 self.setAlignment(QtCore.Qt.AlignLeft)
33 self.setIndent(1)
33 self.setIndent(1)
34 self.setFrameStyle(QtGui.QFrame.NoFrame)
34 self.setFrameStyle(QtGui.QFrame.NoFrame)
35 self.setMargin(1 + self.style().pixelMetric(
35 self.setMargin(1 + self.style().pixelMetric(
36 QtGui.QStyle.PM_ToolTipLabelFrameWidth, None, self))
36 QtGui.QStyle.PM_ToolTipLabelFrameWidth, None, self))
37 self.setWindowOpacity(self.style().styleHint(
37 self.setWindowOpacity(self.style().styleHint(
38 QtGui.QStyle.SH_ToolTipLabel_Opacity, None, self) / 255.0)
38 QtGui.QStyle.SH_ToolTipLabel_Opacity, None, self) / 255.0)
39
39
40 def eventFilter(self, obj, event):
40 def eventFilter(self, obj, event):
41 """ Reimplemented to hide on certain key presses and on text edit focus
41 """ Reimplemented to hide on certain key presses and on text edit focus
42 changes.
42 changes.
43 """
43 """
44 if obj == self._text_edit:
44 if obj == self._text_edit:
45 etype = event.type()
45 etype = event.type()
46
46
47 if etype == QtCore.QEvent.KeyPress:
47 if etype == QtCore.QEvent.KeyPress:
48 key = event.key()
48 key = event.key()
49 if key in (QtCore.Qt.Key_Enter, QtCore.Qt.Key_Return):
49 if key in (QtCore.Qt.Key_Enter, QtCore.Qt.Key_Return):
50 self.hide()
50 self.hide()
51 elif key == QtCore.Qt.Key_Escape:
51 elif key == QtCore.Qt.Key_Escape:
52 self.hide()
52 self.hide()
53 return True
53 return True
54
54
55 elif etype == QtCore.QEvent.FocusOut:
55 elif etype == QtCore.QEvent.FocusOut:
56 self.hide()
56 self.hide()
57
57
58 elif etype == QtCore.QEvent.Enter:
58 elif etype == QtCore.QEvent.Enter:
59 self._hide_timer.stop()
59 self._hide_timer.stop()
60
60
61 elif etype == QtCore.QEvent.Leave:
61 elif etype == QtCore.QEvent.Leave:
62 self._hide_later()
62 self._hide_later()
63
63
64 return super(CallTipWidget, self).eventFilter(obj, event)
64 return super(CallTipWidget, self).eventFilter(obj, event)
65
65
66 def timerEvent(self, event):
66 def timerEvent(self, event):
67 """ Reimplemented to hide the widget when the hide timer fires.
67 """ Reimplemented to hide the widget when the hide timer fires.
68 """
68 """
69 if event.timerId() == self._hide_timer.timerId():
69 if event.timerId() == self._hide_timer.timerId():
70 self._hide_timer.stop()
70 self._hide_timer.stop()
71 self.hide()
71 self.hide()
72
72
73 #--------------------------------------------------------------------------
73 #--------------------------------------------------------------------------
74 # 'QWidget' interface
74 # 'QWidget' interface
75 #--------------------------------------------------------------------------
75 #--------------------------------------------------------------------------
76
76
77 def enterEvent(self, event):
77 def enterEvent(self, event):
78 """ Reimplemented to cancel the hide timer.
78 """ Reimplemented to cancel the hide timer.
79 """
79 """
80 super(CallTipWidget, self).enterEvent(event)
80 super(CallTipWidget, self).enterEvent(event)
81 self._hide_timer.stop()
81 self._hide_timer.stop()
82
82
83 def hideEvent(self, event):
83 def hideEvent(self, event):
84 """ Reimplemented to disconnect signal handlers and event filter.
84 """ Reimplemented to disconnect signal handlers and event filter.
85 """
85 """
86 super(CallTipWidget, self).hideEvent(event)
86 super(CallTipWidget, self).hideEvent(event)
87 self._text_edit.cursorPositionChanged.disconnect(
87 self._text_edit.cursorPositionChanged.disconnect(
88 self._cursor_position_changed)
88 self._cursor_position_changed)
89 self._text_edit.removeEventFilter(self)
89 self._text_edit.removeEventFilter(self)
90
90
91 def leaveEvent(self, event):
91 def leaveEvent(self, event):
92 """ Reimplemented to start the hide timer.
92 """ Reimplemented to start the hide timer.
93 """
93 """
94 super(CallTipWidget, self).leaveEvent(event)
94 super(CallTipWidget, self).leaveEvent(event)
95 self._hide_later()
95 self._hide_later()
96
96
97 def paintEvent(self, event):
97 def paintEvent(self, event):
98 """ Reimplemented to paint the background panel.
98 """ Reimplemented to paint the background panel.
99 """
99 """
100 painter = QtGui.QStylePainter(self)
100 painter = QtGui.QStylePainter(self)
101 option = QtGui.QStyleOptionFrame()
101 option = QtGui.QStyleOptionFrame()
102 option.init(self)
102 option.init(self)
103 painter.drawPrimitive(QtGui.QStyle.PE_PanelTipLabel, option)
103 painter.drawPrimitive(QtGui.QStyle.PE_PanelTipLabel, option)
104 painter.end()
104 painter.end()
105
105
106 super(CallTipWidget, self).paintEvent(event)
106 super(CallTipWidget, self).paintEvent(event)
107
107
108 def setFont(self, font):
108 def setFont(self, font):
109 """ Reimplemented to allow use of this method as a slot.
109 """ Reimplemented to allow use of this method as a slot.
110 """
110 """
111 super(CallTipWidget, self).setFont(font)
111 super(CallTipWidget, self).setFont(font)
112
112
113 def showEvent(self, event):
113 def showEvent(self, event):
114 """ Reimplemented to connect signal handlers and event filter.
114 """ Reimplemented to connect signal handlers and event filter.
115 """
115 """
116 super(CallTipWidget, self).showEvent(event)
116 super(CallTipWidget, self).showEvent(event)
117 self._text_edit.cursorPositionChanged.connect(
117 self._text_edit.cursorPositionChanged.connect(
118 self._cursor_position_changed)
118 self._cursor_position_changed)
119 self._text_edit.installEventFilter(self)
119 self._text_edit.installEventFilter(self)
120
120
121 #--------------------------------------------------------------------------
121 #--------------------------------------------------------------------------
122 # 'CallTipWidget' interface
122 # 'CallTipWidget' interface
123 #--------------------------------------------------------------------------
123 #--------------------------------------------------------------------------
124
124
125 def show_docstring(self, doc, maxlines=20):
125 def show_call_info(self, call_line=None, doc=None, maxlines=20):
126 """ Attempts to show the specified docstring at the current cursor
126 """ Attempts to show the specified call line and docstring at the
127 location. The docstring is dedented and possibly truncated for
127 current cursor location. The docstring is possibly truncated for
128 length.
128 length.
129 """
129 """
130 doc = dedent(doc.rstrip()).lstrip()
130 if doc:
131 match = re.match("(?:[^\n]*\n){%i}" % maxlines, doc)
131 match = re.match("(?:[^\n]*\n){%i}" % maxlines, doc)
132 if match:
132 if match:
133 doc = doc[:match.end()] + '\n[Documentation continues...]'
133 doc = doc[:match.end()] + '\n[Documentation continues...]'
134 else:
135 doc = ''
136
137 if call_line:
138 doc = '\n\n'.join([call_line, doc])
134 return self.show_tip(doc)
139 return self.show_tip(doc)
135
140
136 def show_tip(self, tip):
141 def show_tip(self, tip):
137 """ Attempts to show the specified tip at the current cursor location.
142 """ Attempts to show the specified tip at the current cursor location.
138 """
143 """
139 # Attempt to find the cursor position at which to show the call tip.
144 # Attempt to find the cursor position at which to show the call tip.
140 text_edit = self._text_edit
145 text_edit = self._text_edit
141 document = text_edit.document()
146 document = text_edit.document()
142 cursor = text_edit.textCursor()
147 cursor = text_edit.textCursor()
143 search_pos = cursor.position() - 1
148 search_pos = cursor.position() - 1
144 self._start_position, _ = self._find_parenthesis(search_pos,
149 self._start_position, _ = self._find_parenthesis(search_pos,
145 forward=False)
150 forward=False)
146 if self._start_position == -1:
151 if self._start_position == -1:
147 return False
152 return False
148
153
149 # Set the text and resize the widget accordingly.
154 # Set the text and resize the widget accordingly.
150 self.setText(tip)
155 self.setText(tip)
151 self.resize(self.sizeHint())
156 self.resize(self.sizeHint())
152
157
153 # Locate and show the widget. Place the tip below the current line
158 # Locate and show the widget. Place the tip below the current line
154 # unless it would be off the screen. In that case, place it above
159 # unless it would be off the screen. In that case, place it above
155 # the current line.
160 # the current line.
156 padding = 3 # Distance in pixels between cursor bounds and tip box.
161 padding = 3 # Distance in pixels between cursor bounds and tip box.
157 cursor_rect = text_edit.cursorRect(cursor)
162 cursor_rect = text_edit.cursorRect(cursor)
158 screen_rect = QtGui.qApp.desktop().screenGeometry(text_edit)
163 screen_rect = QtGui.qApp.desktop().screenGeometry(text_edit)
159 point = text_edit.mapToGlobal(cursor_rect.bottomRight())
164 point = text_edit.mapToGlobal(cursor_rect.bottomRight())
160 point.setY(point.y() + padding)
165 point.setY(point.y() + padding)
161 tip_height = self.size().height()
166 tip_height = self.size().height()
162 if point.y() + tip_height > screen_rect.height():
167 if point.y() + tip_height > screen_rect.height():
163 point = text_edit.mapToGlobal(cursor_rect.topRight())
168 point = text_edit.mapToGlobal(cursor_rect.topRight())
164 point.setY(point.y() - tip_height - padding)
169 point.setY(point.y() - tip_height - padding)
165 self.move(point)
170 self.move(point)
166 self.show()
171 self.show()
167 return True
172 return True
168
173
169 #--------------------------------------------------------------------------
174 #--------------------------------------------------------------------------
170 # Protected interface
175 # Protected interface
171 #--------------------------------------------------------------------------
176 #--------------------------------------------------------------------------
172
177
173 def _find_parenthesis(self, position, forward=True):
178 def _find_parenthesis(self, position, forward=True):
174 """ If 'forward' is True (resp. False), proceed forwards
179 """ If 'forward' is True (resp. False), proceed forwards
175 (resp. backwards) through the line that contains 'position' until an
180 (resp. backwards) through the line that contains 'position' until an
176 unmatched closing (resp. opening) parenthesis is found. Returns a
181 unmatched closing (resp. opening) parenthesis is found. Returns a
177 tuple containing the position of this parenthesis (or -1 if it is
182 tuple containing the position of this parenthesis (or -1 if it is
178 not found) and the number commas (at depth 0) found along the way.
183 not found) and the number commas (at depth 0) found along the way.
179 """
184 """
180 commas = depth = 0
185 commas = depth = 0
181 document = self._text_edit.document()
186 document = self._text_edit.document()
182 qchar = document.characterAt(position)
187 qchar = document.characterAt(position)
183 while (position > 0 and qchar.isPrint() and
188 while (position > 0 and qchar.isPrint() and
184 # Need to check explicitly for line/paragraph separators:
189 # Need to check explicitly for line/paragraph separators:
185 qchar.unicode() not in (0x2028, 0x2029)):
190 qchar.unicode() not in (0x2028, 0x2029)):
186 char = qchar.toAscii()
191 char = qchar.toAscii()
187 if char == ',' and depth == 0:
192 if char == ',' and depth == 0:
188 commas += 1
193 commas += 1
189 elif char == ')':
194 elif char == ')':
190 if forward and depth == 0:
195 if forward and depth == 0:
191 break
196 break
192 depth += 1
197 depth += 1
193 elif char == '(':
198 elif char == '(':
194 if not forward and depth == 0:
199 if not forward and depth == 0:
195 break
200 break
196 depth -= 1
201 depth -= 1
197 position += 1 if forward else -1
202 position += 1 if forward else -1
198 qchar = document.characterAt(position)
203 qchar = document.characterAt(position)
199 else:
204 else:
200 position = -1
205 position = -1
201 return position, commas
206 return position, commas
202
207
203 def _hide_later(self):
208 def _hide_later(self):
204 """ Hides the tooltip after some time has passed.
209 """ Hides the tooltip after some time has passed.
205 """
210 """
206 if not self._hide_timer.isActive():
211 if not self._hide_timer.isActive():
207 self._hide_timer.start(300, self)
212 self._hide_timer.start(300, self)
208
213
209 #------ Signal handlers ----------------------------------------------------
214 #------ Signal handlers ----------------------------------------------------
210
215
211 def _cursor_position_changed(self):
216 def _cursor_position_changed(self):
212 """ Updates the tip based on user cursor movement.
217 """ Updates the tip based on user cursor movement.
213 """
218 """
214 cursor = self._text_edit.textCursor()
219 cursor = self._text_edit.textCursor()
215 if cursor.position() <= self._start_position:
220 if cursor.position() <= self._start_position:
216 self.hide()
221 self.hide()
217 else:
222 else:
218 position, commas = self._find_parenthesis(self._start_position + 1)
223 position, commas = self._find_parenthesis(self._start_position + 1)
219 if position != -1:
224 if position != -1:
220 self.hide()
225 self.hide()
@@ -1,549 +1,554 b''
1 from __future__ import print_function
1 from __future__ import print_function
2
2
3 # Standard library imports
3 # Standard library imports
4 from collections import namedtuple
4 from collections import namedtuple
5 import sys
5 import sys
6
6
7 # System library imports
7 # System library imports
8 from pygments.lexers import PythonLexer
8 from pygments.lexers import PythonLexer
9 from PyQt4 import QtCore, QtGui
9 from PyQt4 import QtCore, QtGui
10
10
11 # Local imports
11 # Local imports
12 from IPython.core.inputsplitter import InputSplitter, transform_classic_prompt
12 from IPython.core.inputsplitter import InputSplitter, transform_classic_prompt
13 from IPython.core.oinspect import call_tip
13 from IPython.frontend.qt.base_frontend_mixin import BaseFrontendMixin
14 from IPython.frontend.qt.base_frontend_mixin import BaseFrontendMixin
14 from IPython.utils.traitlets import Bool
15 from IPython.utils.traitlets import Bool
15 from bracket_matcher import BracketMatcher
16 from bracket_matcher import BracketMatcher
16 from call_tip_widget import CallTipWidget
17 from call_tip_widget import CallTipWidget
17 from completion_lexer import CompletionLexer
18 from completion_lexer import CompletionLexer
18 from history_console_widget import HistoryConsoleWidget
19 from history_console_widget import HistoryConsoleWidget
19 from pygments_highlighter import PygmentsHighlighter
20 from pygments_highlighter import PygmentsHighlighter
20
21
21
22
22 class FrontendHighlighter(PygmentsHighlighter):
23 class FrontendHighlighter(PygmentsHighlighter):
23 """ A PygmentsHighlighter that can be turned on and off and that ignores
24 """ A PygmentsHighlighter that can be turned on and off and that ignores
24 prompts.
25 prompts.
25 """
26 """
26
27
27 def __init__(self, frontend):
28 def __init__(self, frontend):
28 super(FrontendHighlighter, self).__init__(frontend._control.document())
29 super(FrontendHighlighter, self).__init__(frontend._control.document())
29 self._current_offset = 0
30 self._current_offset = 0
30 self._frontend = frontend
31 self._frontend = frontend
31 self.highlighting_on = False
32 self.highlighting_on = False
32
33
33 def highlightBlock(self, qstring):
34 def highlightBlock(self, qstring):
34 """ Highlight a block of text. Reimplemented to highlight selectively.
35 """ Highlight a block of text. Reimplemented to highlight selectively.
35 """
36 """
36 if not self.highlighting_on:
37 if not self.highlighting_on:
37 return
38 return
38
39
39 # The input to this function is unicode string that may contain
40 # The input to this function is unicode string that may contain
40 # paragraph break characters, non-breaking spaces, etc. Here we acquire
41 # paragraph break characters, non-breaking spaces, etc. Here we acquire
41 # the string as plain text so we can compare it.
42 # the string as plain text so we can compare it.
42 current_block = self.currentBlock()
43 current_block = self.currentBlock()
43 string = self._frontend._get_block_plain_text(current_block)
44 string = self._frontend._get_block_plain_text(current_block)
44
45
45 # Decide whether to check for the regular or continuation prompt.
46 # Decide whether to check for the regular or continuation prompt.
46 if current_block.contains(self._frontend._prompt_pos):
47 if current_block.contains(self._frontend._prompt_pos):
47 prompt = self._frontend._prompt
48 prompt = self._frontend._prompt
48 else:
49 else:
49 prompt = self._frontend._continuation_prompt
50 prompt = self._frontend._continuation_prompt
50
51
51 # Don't highlight the part of the string that contains the prompt.
52 # Don't highlight the part of the string that contains the prompt.
52 if string.startswith(prompt):
53 if string.startswith(prompt):
53 self._current_offset = len(prompt)
54 self._current_offset = len(prompt)
54 qstring.remove(0, len(prompt))
55 qstring.remove(0, len(prompt))
55 else:
56 else:
56 self._current_offset = 0
57 self._current_offset = 0
57
58
58 PygmentsHighlighter.highlightBlock(self, qstring)
59 PygmentsHighlighter.highlightBlock(self, qstring)
59
60
60 def rehighlightBlock(self, block):
61 def rehighlightBlock(self, block):
61 """ Reimplemented to temporarily enable highlighting if disabled.
62 """ Reimplemented to temporarily enable highlighting if disabled.
62 """
63 """
63 old = self.highlighting_on
64 old = self.highlighting_on
64 self.highlighting_on = True
65 self.highlighting_on = True
65 super(FrontendHighlighter, self).rehighlightBlock(block)
66 super(FrontendHighlighter, self).rehighlightBlock(block)
66 self.highlighting_on = old
67 self.highlighting_on = old
67
68
68 def setFormat(self, start, count, format):
69 def setFormat(self, start, count, format):
69 """ Reimplemented to highlight selectively.
70 """ Reimplemented to highlight selectively.
70 """
71 """
71 start += self._current_offset
72 start += self._current_offset
72 PygmentsHighlighter.setFormat(self, start, count, format)
73 PygmentsHighlighter.setFormat(self, start, count, format)
73
74
74
75
75 class FrontendWidget(HistoryConsoleWidget, BaseFrontendMixin):
76 class FrontendWidget(HistoryConsoleWidget, BaseFrontendMixin):
76 """ A Qt frontend for a generic Python kernel.
77 """ A Qt frontend for a generic Python kernel.
77 """
78 """
78
79
79 # An option and corresponding signal for overriding the default kernel
80 # An option and corresponding signal for overriding the default kernel
80 # interrupt behavior.
81 # interrupt behavior.
81 custom_interrupt = Bool(False)
82 custom_interrupt = Bool(False)
82 custom_interrupt_requested = QtCore.pyqtSignal()
83 custom_interrupt_requested = QtCore.pyqtSignal()
83
84
84 # An option and corresponding signals for overriding the default kernel
85 # An option and corresponding signals for overriding the default kernel
85 # restart behavior.
86 # restart behavior.
86 custom_restart = Bool(False)
87 custom_restart = Bool(False)
87 custom_restart_kernel_died = QtCore.pyqtSignal(float)
88 custom_restart_kernel_died = QtCore.pyqtSignal(float)
88 custom_restart_requested = QtCore.pyqtSignal()
89 custom_restart_requested = QtCore.pyqtSignal()
89
90
90 # Emitted when an 'execute_reply' has been received from the kernel and
91 # Emitted when an 'execute_reply' has been received from the kernel and
91 # processed by the FrontendWidget.
92 # processed by the FrontendWidget.
92 executed = QtCore.pyqtSignal(object)
93 executed = QtCore.pyqtSignal(object)
93
94
94 # Emitted when an exit request has been received from the kernel.
95 # Emitted when an exit request has been received from the kernel.
95 exit_requested = QtCore.pyqtSignal()
96 exit_requested = QtCore.pyqtSignal()
96
97
97 # Protected class variables.
98 # Protected class variables.
98 _CallTipRequest = namedtuple('_CallTipRequest', ['id', 'pos'])
99 _CallTipRequest = namedtuple('_CallTipRequest', ['id', 'pos'])
99 _CompletionRequest = namedtuple('_CompletionRequest', ['id', 'pos'])
100 _CompletionRequest = namedtuple('_CompletionRequest', ['id', 'pos'])
100 _ExecutionRequest = namedtuple('_ExecutionRequest', ['id', 'kind'])
101 _ExecutionRequest = namedtuple('_ExecutionRequest', ['id', 'kind'])
101 _input_splitter_class = InputSplitter
102 _input_splitter_class = InputSplitter
102
103
103 #---------------------------------------------------------------------------
104 #---------------------------------------------------------------------------
104 # 'object' interface
105 # 'object' interface
105 #---------------------------------------------------------------------------
106 #---------------------------------------------------------------------------
106
107
107 def __init__(self, *args, **kw):
108 def __init__(self, *args, **kw):
108 super(FrontendWidget, self).__init__(*args, **kw)
109 super(FrontendWidget, self).__init__(*args, **kw)
109
110
110 # FrontendWidget protected variables.
111 # FrontendWidget protected variables.
111 self._bracket_matcher = BracketMatcher(self._control)
112 self._bracket_matcher = BracketMatcher(self._control)
112 self._call_tip_widget = CallTipWidget(self._control)
113 self._call_tip_widget = CallTipWidget(self._control)
113 self._completion_lexer = CompletionLexer(PythonLexer())
114 self._completion_lexer = CompletionLexer(PythonLexer())
114 self._copy_raw_action = QtGui.QAction('Copy (Raw Text)', None)
115 self._copy_raw_action = QtGui.QAction('Copy (Raw Text)', None)
115 self._hidden = False
116 self._hidden = False
116 self._highlighter = FrontendHighlighter(self)
117 self._highlighter = FrontendHighlighter(self)
117 self._input_splitter = self._input_splitter_class(input_mode='cell')
118 self._input_splitter = self._input_splitter_class(input_mode='cell')
118 self._kernel_manager = None
119 self._kernel_manager = None
119 self._request_info = {}
120 self._request_info = {}
120
121
121 # Configure the ConsoleWidget.
122 # Configure the ConsoleWidget.
122 self.tab_width = 4
123 self.tab_width = 4
123 self._set_continuation_prompt('... ')
124 self._set_continuation_prompt('... ')
124
125
125 # Configure the CallTipWidget.
126 # Configure the CallTipWidget.
126 self._call_tip_widget.setFont(self.font)
127 self._call_tip_widget.setFont(self.font)
127 self.font_changed.connect(self._call_tip_widget.setFont)
128 self.font_changed.connect(self._call_tip_widget.setFont)
128
129
129 # Configure actions.
130 # Configure actions.
130 action = self._copy_raw_action
131 action = self._copy_raw_action
131 key = QtCore.Qt.CTRL | QtCore.Qt.SHIFT | QtCore.Qt.Key_C
132 key = QtCore.Qt.CTRL | QtCore.Qt.SHIFT | QtCore.Qt.Key_C
132 action.setEnabled(False)
133 action.setEnabled(False)
133 action.setShortcut(QtGui.QKeySequence(key))
134 action.setShortcut(QtGui.QKeySequence(key))
134 action.setShortcutContext(QtCore.Qt.WidgetWithChildrenShortcut)
135 action.setShortcutContext(QtCore.Qt.WidgetWithChildrenShortcut)
135 action.triggered.connect(self.copy_raw)
136 action.triggered.connect(self.copy_raw)
136 self.copy_available.connect(action.setEnabled)
137 self.copy_available.connect(action.setEnabled)
137 self.addAction(action)
138 self.addAction(action)
138
139
139 # Connect signal handlers.
140 # Connect signal handlers.
140 document = self._control.document()
141 document = self._control.document()
141 document.contentsChange.connect(self._document_contents_change)
142 document.contentsChange.connect(self._document_contents_change)
142
143
143 #---------------------------------------------------------------------------
144 #---------------------------------------------------------------------------
144 # 'ConsoleWidget' public interface
145 # 'ConsoleWidget' public interface
145 #---------------------------------------------------------------------------
146 #---------------------------------------------------------------------------
146
147
147 def copy(self):
148 def copy(self):
148 """ Copy the currently selected text to the clipboard, removing prompts.
149 """ Copy the currently selected text to the clipboard, removing prompts.
149 """
150 """
150 text = unicode(self._control.textCursor().selection().toPlainText())
151 text = unicode(self._control.textCursor().selection().toPlainText())
151 if text:
152 if text:
152 lines = map(transform_classic_prompt, text.splitlines())
153 lines = map(transform_classic_prompt, text.splitlines())
153 text = '\n'.join(lines)
154 text = '\n'.join(lines)
154 QtGui.QApplication.clipboard().setText(text)
155 QtGui.QApplication.clipboard().setText(text)
155
156
156 #---------------------------------------------------------------------------
157 #---------------------------------------------------------------------------
157 # 'ConsoleWidget' abstract interface
158 # 'ConsoleWidget' abstract interface
158 #---------------------------------------------------------------------------
159 #---------------------------------------------------------------------------
159
160
160 def _is_complete(self, source, interactive):
161 def _is_complete(self, source, interactive):
161 """ Returns whether 'source' can be completely processed and a new
162 """ Returns whether 'source' can be completely processed and a new
162 prompt created. When triggered by an Enter/Return key press,
163 prompt created. When triggered by an Enter/Return key press,
163 'interactive' is True; otherwise, it is False.
164 'interactive' is True; otherwise, it is False.
164 """
165 """
165 complete = self._input_splitter.push(source)
166 complete = self._input_splitter.push(source)
166 if interactive:
167 if interactive:
167 complete = not self._input_splitter.push_accepts_more()
168 complete = not self._input_splitter.push_accepts_more()
168 return complete
169 return complete
169
170
170 def _execute(self, source, hidden):
171 def _execute(self, source, hidden):
171 """ Execute 'source'. If 'hidden', do not show any output.
172 """ Execute 'source'. If 'hidden', do not show any output.
172
173
173 See parent class :meth:`execute` docstring for full details.
174 See parent class :meth:`execute` docstring for full details.
174 """
175 """
175 msg_id = self.kernel_manager.xreq_channel.execute(source, hidden)
176 msg_id = self.kernel_manager.xreq_channel.execute(source, hidden)
176 self._request_info['execute'] = self._ExecutionRequest(msg_id, 'user')
177 self._request_info['execute'] = self._ExecutionRequest(msg_id, 'user')
177 self._hidden = hidden
178 self._hidden = hidden
178
179
179 def _prompt_started_hook(self):
180 def _prompt_started_hook(self):
180 """ Called immediately after a new prompt is displayed.
181 """ Called immediately after a new prompt is displayed.
181 """
182 """
182 if not self._reading:
183 if not self._reading:
183 self._highlighter.highlighting_on = True
184 self._highlighter.highlighting_on = True
184
185
185 def _prompt_finished_hook(self):
186 def _prompt_finished_hook(self):
186 """ Called immediately after a prompt is finished, i.e. when some input
187 """ Called immediately after a prompt is finished, i.e. when some input
187 will be processed and a new prompt displayed.
188 will be processed and a new prompt displayed.
188 """
189 """
189 if not self._reading:
190 if not self._reading:
190 self._highlighter.highlighting_on = False
191 self._highlighter.highlighting_on = False
191
192
192 def _tab_pressed(self):
193 def _tab_pressed(self):
193 """ Called when the tab key is pressed. Returns whether to continue
194 """ Called when the tab key is pressed. Returns whether to continue
194 processing the event.
195 processing the event.
195 """
196 """
196 # Perform tab completion if:
197 # Perform tab completion if:
197 # 1) The cursor is in the input buffer.
198 # 1) The cursor is in the input buffer.
198 # 2) There is a non-whitespace character before the cursor.
199 # 2) There is a non-whitespace character before the cursor.
199 text = self._get_input_buffer_cursor_line()
200 text = self._get_input_buffer_cursor_line()
200 if text is None:
201 if text is None:
201 return False
202 return False
202 complete = bool(text[:self._get_input_buffer_cursor_column()].strip())
203 complete = bool(text[:self._get_input_buffer_cursor_column()].strip())
203 if complete:
204 if complete:
204 self._complete()
205 self._complete()
205 return not complete
206 return not complete
206
207
207 #---------------------------------------------------------------------------
208 #---------------------------------------------------------------------------
208 # 'ConsoleWidget' protected interface
209 # 'ConsoleWidget' protected interface
209 #---------------------------------------------------------------------------
210 #---------------------------------------------------------------------------
210
211
211 def _context_menu_make(self, pos):
212 def _context_menu_make(self, pos):
212 """ Reimplemented to add an action for raw copy.
213 """ Reimplemented to add an action for raw copy.
213 """
214 """
214 menu = super(FrontendWidget, self)._context_menu_make(pos)
215 menu = super(FrontendWidget, self)._context_menu_make(pos)
215 for before_action in menu.actions():
216 for before_action in menu.actions():
216 if before_action.shortcut().matches(QtGui.QKeySequence.Paste) == \
217 if before_action.shortcut().matches(QtGui.QKeySequence.Paste) == \
217 QtGui.QKeySequence.ExactMatch:
218 QtGui.QKeySequence.ExactMatch:
218 menu.insertAction(before_action, self._copy_raw_action)
219 menu.insertAction(before_action, self._copy_raw_action)
219 break
220 break
220 return menu
221 return menu
221
222
222 def _event_filter_console_keypress(self, event):
223 def _event_filter_console_keypress(self, event):
223 """ Reimplemented for execution interruption and smart backspace.
224 """ Reimplemented for execution interruption and smart backspace.
224 """
225 """
225 key = event.key()
226 key = event.key()
226 if self._control_key_down(event.modifiers(), include_command=False):
227 if self._control_key_down(event.modifiers(), include_command=False):
227
228
228 if key == QtCore.Qt.Key_C and self._executing:
229 if key == QtCore.Qt.Key_C and self._executing:
229 self.interrupt_kernel()
230 self.interrupt_kernel()
230 return True
231 return True
231
232
232 elif key == QtCore.Qt.Key_Period:
233 elif key == QtCore.Qt.Key_Period:
233 message = 'Are you sure you want to restart the kernel?'
234 message = 'Are you sure you want to restart the kernel?'
234 self.restart_kernel(message, now=False)
235 self.restart_kernel(message, now=False)
235 return True
236 return True
236
237
237 elif not event.modifiers() & QtCore.Qt.AltModifier:
238 elif not event.modifiers() & QtCore.Qt.AltModifier:
238
239
239 # Smart backspace: remove four characters in one backspace if:
240 # Smart backspace: remove four characters in one backspace if:
240 # 1) everything left of the cursor is whitespace
241 # 1) everything left of the cursor is whitespace
241 # 2) the four characters immediately left of the cursor are spaces
242 # 2) the four characters immediately left of the cursor are spaces
242 if key == QtCore.Qt.Key_Backspace:
243 if key == QtCore.Qt.Key_Backspace:
243 col = self._get_input_buffer_cursor_column()
244 col = self._get_input_buffer_cursor_column()
244 cursor = self._control.textCursor()
245 cursor = self._control.textCursor()
245 if col > 3 and not cursor.hasSelection():
246 if col > 3 and not cursor.hasSelection():
246 text = self._get_input_buffer_cursor_line()[:col]
247 text = self._get_input_buffer_cursor_line()[:col]
247 if text.endswith(' ') and not text.strip():
248 if text.endswith(' ') and not text.strip():
248 cursor.movePosition(QtGui.QTextCursor.Left,
249 cursor.movePosition(QtGui.QTextCursor.Left,
249 QtGui.QTextCursor.KeepAnchor, 4)
250 QtGui.QTextCursor.KeepAnchor, 4)
250 cursor.removeSelectedText()
251 cursor.removeSelectedText()
251 return True
252 return True
252
253
253 return super(FrontendWidget, self)._event_filter_console_keypress(event)
254 return super(FrontendWidget, self)._event_filter_console_keypress(event)
254
255
255 def _insert_continuation_prompt(self, cursor):
256 def _insert_continuation_prompt(self, cursor):
256 """ Reimplemented for auto-indentation.
257 """ Reimplemented for auto-indentation.
257 """
258 """
258 super(FrontendWidget, self)._insert_continuation_prompt(cursor)
259 super(FrontendWidget, self)._insert_continuation_prompt(cursor)
259 cursor.insertText(' ' * self._input_splitter.indent_spaces)
260 cursor.insertText(' ' * self._input_splitter.indent_spaces)
260
261
261 #---------------------------------------------------------------------------
262 #---------------------------------------------------------------------------
262 # 'BaseFrontendMixin' abstract interface
263 # 'BaseFrontendMixin' abstract interface
263 #---------------------------------------------------------------------------
264 #---------------------------------------------------------------------------
264
265
265 def _handle_complete_reply(self, rep):
266 def _handle_complete_reply(self, rep):
266 """ Handle replies for tab completion.
267 """ Handle replies for tab completion.
267 """
268 """
268 cursor = self._get_cursor()
269 cursor = self._get_cursor()
269 info = self._request_info.get('complete')
270 info = self._request_info.get('complete')
270 if info and info.id == rep['parent_header']['msg_id'] and \
271 if info and info.id == rep['parent_header']['msg_id'] and \
271 info.pos == cursor.position():
272 info.pos == cursor.position():
272 text = '.'.join(self._get_context())
273 text = '.'.join(self._get_context())
273 cursor.movePosition(QtGui.QTextCursor.Left, n=len(text))
274 cursor.movePosition(QtGui.QTextCursor.Left, n=len(text))
274 self._complete_with_items(cursor, rep['content']['matches'])
275 self._complete_with_items(cursor, rep['content']['matches'])
275
276
276 def _handle_execute_reply(self, msg):
277 def _handle_execute_reply(self, msg):
277 """ Handles replies for code execution.
278 """ Handles replies for code execution.
278 """
279 """
279 info = self._request_info.get('execute')
280 info = self._request_info.get('execute')
280 if info and info.id == msg['parent_header']['msg_id'] and \
281 if info and info.id == msg['parent_header']['msg_id'] and \
281 info.kind == 'user' and not self._hidden:
282 info.kind == 'user' and not self._hidden:
282 # Make sure that all output from the SUB channel has been processed
283 # Make sure that all output from the SUB channel has been processed
283 # before writing a new prompt.
284 # before writing a new prompt.
284 self.kernel_manager.sub_channel.flush()
285 self.kernel_manager.sub_channel.flush()
285
286
286 # Reset the ANSI style information to prevent bad text in stdout
287 # Reset the ANSI style information to prevent bad text in stdout
287 # from messing up our colors. We're not a true terminal so we're
288 # from messing up our colors. We're not a true terminal so we're
288 # allowed to do this.
289 # allowed to do this.
289 if self.ansi_codes:
290 if self.ansi_codes:
290 self._ansi_processor.reset_sgr()
291 self._ansi_processor.reset_sgr()
291
292
292 content = msg['content']
293 content = msg['content']
293 status = content['status']
294 status = content['status']
294 if status == 'ok':
295 if status == 'ok':
295 self._process_execute_ok(msg)
296 self._process_execute_ok(msg)
296 elif status == 'error':
297 elif status == 'error':
297 self._process_execute_error(msg)
298 self._process_execute_error(msg)
298 elif status == 'abort':
299 elif status == 'abort':
299 self._process_execute_abort(msg)
300 self._process_execute_abort(msg)
300
301
301 self._show_interpreter_prompt_for_reply(msg)
302 self._show_interpreter_prompt_for_reply(msg)
302 self.executed.emit(msg)
303 self.executed.emit(msg)
303
304
304 def _handle_input_request(self, msg):
305 def _handle_input_request(self, msg):
305 """ Handle requests for raw_input.
306 """ Handle requests for raw_input.
306 """
307 """
307 if self._hidden:
308 if self._hidden:
308 raise RuntimeError('Request for raw input during hidden execution.')
309 raise RuntimeError('Request for raw input during hidden execution.')
309
310
310 # Make sure that all output from the SUB channel has been processed
311 # Make sure that all output from the SUB channel has been processed
311 # before entering readline mode.
312 # before entering readline mode.
312 self.kernel_manager.sub_channel.flush()
313 self.kernel_manager.sub_channel.flush()
313
314
314 def callback(line):
315 def callback(line):
315 self.kernel_manager.rep_channel.input(line)
316 self.kernel_manager.rep_channel.input(line)
316 self._readline(msg['content']['prompt'], callback=callback)
317 self._readline(msg['content']['prompt'], callback=callback)
317
318
318 def _handle_kernel_died(self, since_last_heartbeat):
319 def _handle_kernel_died(self, since_last_heartbeat):
319 """ Handle the kernel's death by asking if the user wants to restart.
320 """ Handle the kernel's death by asking if the user wants to restart.
320 """
321 """
321 if self.custom_restart:
322 if self.custom_restart:
322 self.custom_restart_kernel_died.emit(since_last_heartbeat)
323 self.custom_restart_kernel_died.emit(since_last_heartbeat)
323 else:
324 else:
324 message = 'The kernel heartbeat has been inactive for %.2f ' \
325 message = 'The kernel heartbeat has been inactive for %.2f ' \
325 'seconds. Do you want to restart the kernel? You may ' \
326 'seconds. Do you want to restart the kernel? You may ' \
326 'first want to check the network connection.' % \
327 'first want to check the network connection.' % \
327 since_last_heartbeat
328 since_last_heartbeat
328 self.restart_kernel(message, now=True)
329 self.restart_kernel(message, now=True)
329
330
330 def _handle_object_info_reply(self, rep):
331 def _handle_object_info_reply(self, rep):
331 """ Handle replies for call tips.
332 """ Handle replies for call tips.
332 """
333 """
333 cursor = self._get_cursor()
334 cursor = self._get_cursor()
334 info = self._request_info.get('call_tip')
335 info = self._request_info.get('call_tip')
335 if info and info.id == rep['parent_header']['msg_id'] and \
336 if info and info.id == rep['parent_header']['msg_id'] and \
336 info.pos == cursor.position():
337 info.pos == cursor.position():
337 doc = rep['content']['docstring']
338 # Get the information for a call tip. For now we format the call
338 if doc:
339 # line as string, later we can pass False to format_call and
339 self._call_tip_widget.show_docstring(doc)
340 # syntax-highlight it ourselves for nicer formatting in the
341 # calltip.
342 call_info, doc = call_tip(rep['content'], format_call=True)
343 if call_info or doc:
344 self._call_tip_widget.show_call_info(call_info, doc)
340
345
341 def _handle_pyout(self, msg):
346 def _handle_pyout(self, msg):
342 """ Handle display hook output.
347 """ Handle display hook output.
343 """
348 """
344 if not self._hidden and self._is_from_this_session(msg):
349 if not self._hidden and self._is_from_this_session(msg):
345 self._append_plain_text(msg['content']['data'] + '\n')
350 self._append_plain_text(msg['content']['data'] + '\n')
346
351
347 def _handle_stream(self, msg):
352 def _handle_stream(self, msg):
348 """ Handle stdout, stderr, and stdin.
353 """ Handle stdout, stderr, and stdin.
349 """
354 """
350 if not self._hidden and self._is_from_this_session(msg):
355 if not self._hidden and self._is_from_this_session(msg):
351 # Most consoles treat tabs as being 8 space characters. Convert tabs
356 # Most consoles treat tabs as being 8 space characters. Convert tabs
352 # to spaces so that output looks as expected regardless of this
357 # to spaces so that output looks as expected regardless of this
353 # widget's tab width.
358 # widget's tab width.
354 text = msg['content']['data'].expandtabs(8)
359 text = msg['content']['data'].expandtabs(8)
355
360
356 self._append_plain_text(text)
361 self._append_plain_text(text)
357 self._control.moveCursor(QtGui.QTextCursor.End)
362 self._control.moveCursor(QtGui.QTextCursor.End)
358
363
359 def _started_channels(self):
364 def _started_channels(self):
360 """ Called when the KernelManager channels have started listening or
365 """ Called when the KernelManager channels have started listening or
361 when the frontend is assigned an already listening KernelManager.
366 when the frontend is assigned an already listening KernelManager.
362 """
367 """
363 self.reset()
368 self.reset()
364
369
365 #---------------------------------------------------------------------------
370 #---------------------------------------------------------------------------
366 # 'FrontendWidget' public interface
371 # 'FrontendWidget' public interface
367 #---------------------------------------------------------------------------
372 #---------------------------------------------------------------------------
368
373
369 def copy_raw(self):
374 def copy_raw(self):
370 """ Copy the currently selected text to the clipboard without attempting
375 """ Copy the currently selected text to the clipboard without attempting
371 to remove prompts or otherwise alter the text.
376 to remove prompts or otherwise alter the text.
372 """
377 """
373 self._control.copy()
378 self._control.copy()
374
379
375 def execute_file(self, path, hidden=False):
380 def execute_file(self, path, hidden=False):
376 """ Attempts to execute file with 'path'. If 'hidden', no output is
381 """ Attempts to execute file with 'path'. If 'hidden', no output is
377 shown.
382 shown.
378 """
383 """
379 self.execute('execfile("%s")' % path, hidden=hidden)
384 self.execute('execfile("%s")' % path, hidden=hidden)
380
385
381 def interrupt_kernel(self):
386 def interrupt_kernel(self):
382 """ Attempts to interrupt the running kernel.
387 """ Attempts to interrupt the running kernel.
383 """
388 """
384 if self.custom_interrupt:
389 if self.custom_interrupt:
385 self.custom_interrupt_requested.emit()
390 self.custom_interrupt_requested.emit()
386 elif self.kernel_manager.has_kernel:
391 elif self.kernel_manager.has_kernel:
387 self.kernel_manager.interrupt_kernel()
392 self.kernel_manager.interrupt_kernel()
388 else:
393 else:
389 self._append_plain_text('Kernel process is either remote or '
394 self._append_plain_text('Kernel process is either remote or '
390 'unspecified. Cannot interrupt.\n')
395 'unspecified. Cannot interrupt.\n')
391
396
392 def reset(self):
397 def reset(self):
393 """ Resets the widget to its initial state. Similar to ``clear``, but
398 """ Resets the widget to its initial state. Similar to ``clear``, but
394 also re-writes the banner and aborts execution if necessary.
399 also re-writes the banner and aborts execution if necessary.
395 """
400 """
396 if self._executing:
401 if self._executing:
397 self._executing = False
402 self._executing = False
398 self._request_info['execute'] = None
403 self._request_info['execute'] = None
399 self._reading = False
404 self._reading = False
400 self._highlighter.highlighting_on = False
405 self._highlighter.highlighting_on = False
401
406
402 self._control.clear()
407 self._control.clear()
403 self._append_plain_text(self._get_banner())
408 self._append_plain_text(self._get_banner())
404 self._show_interpreter_prompt()
409 self._show_interpreter_prompt()
405
410
406 def restart_kernel(self, message, now=False):
411 def restart_kernel(self, message, now=False):
407 """ Attempts to restart the running kernel.
412 """ Attempts to restart the running kernel.
408 """
413 """
409 # FIXME: now should be configurable via a checkbox in the dialog. Right
414 # FIXME: now should be configurable via a checkbox in the dialog. Right
410 # now at least the heartbeat path sets it to True and the manual restart
415 # now at least the heartbeat path sets it to True and the manual restart
411 # to False. But those should just be the pre-selected states of a
416 # to False. But those should just be the pre-selected states of a
412 # checkbox that the user could override if so desired. But I don't know
417 # checkbox that the user could override if so desired. But I don't know
413 # enough Qt to go implementing the checkbox now.
418 # enough Qt to go implementing the checkbox now.
414
419
415 if self.custom_restart:
420 if self.custom_restart:
416 self.custom_restart_requested.emit()
421 self.custom_restart_requested.emit()
417
422
418 elif self.kernel_manager.has_kernel:
423 elif self.kernel_manager.has_kernel:
419 # Pause the heart beat channel to prevent further warnings.
424 # Pause the heart beat channel to prevent further warnings.
420 self.kernel_manager.hb_channel.pause()
425 self.kernel_manager.hb_channel.pause()
421
426
422 # Prompt the user to restart the kernel. Un-pause the heartbeat if
427 # Prompt the user to restart the kernel. Un-pause the heartbeat if
423 # they decline. (If they accept, the heartbeat will be un-paused
428 # they decline. (If they accept, the heartbeat will be un-paused
424 # automatically when the kernel is restarted.)
429 # automatically when the kernel is restarted.)
425 buttons = QtGui.QMessageBox.Yes | QtGui.QMessageBox.No
430 buttons = QtGui.QMessageBox.Yes | QtGui.QMessageBox.No
426 result = QtGui.QMessageBox.question(self, 'Restart kernel?',
431 result = QtGui.QMessageBox.question(self, 'Restart kernel?',
427 message, buttons)
432 message, buttons)
428 if result == QtGui.QMessageBox.Yes:
433 if result == QtGui.QMessageBox.Yes:
429 try:
434 try:
430 self.kernel_manager.restart_kernel(now=now)
435 self.kernel_manager.restart_kernel(now=now)
431 except RuntimeError:
436 except RuntimeError:
432 self._append_plain_text('Kernel started externally. '
437 self._append_plain_text('Kernel started externally. '
433 'Cannot restart.\n')
438 'Cannot restart.\n')
434 else:
439 else:
435 self.reset()
440 self.reset()
436 else:
441 else:
437 self.kernel_manager.hb_channel.unpause()
442 self.kernel_manager.hb_channel.unpause()
438
443
439 else:
444 else:
440 self._append_plain_text('Kernel process is either remote or '
445 self._append_plain_text('Kernel process is either remote or '
441 'unspecified. Cannot restart.\n')
446 'unspecified. Cannot restart.\n')
442
447
443 #---------------------------------------------------------------------------
448 #---------------------------------------------------------------------------
444 # 'FrontendWidget' protected interface
449 # 'FrontendWidget' protected interface
445 #---------------------------------------------------------------------------
450 #---------------------------------------------------------------------------
446
451
447 def _call_tip(self):
452 def _call_tip(self):
448 """ Shows a call tip, if appropriate, at the current cursor location.
453 """ Shows a call tip, if appropriate, at the current cursor location.
449 """
454 """
450 # Decide if it makes sense to show a call tip
455 # Decide if it makes sense to show a call tip
451 cursor = self._get_cursor()
456 cursor = self._get_cursor()
452 cursor.movePosition(QtGui.QTextCursor.Left)
457 cursor.movePosition(QtGui.QTextCursor.Left)
453 if cursor.document().characterAt(cursor.position()).toAscii() != '(':
458 if cursor.document().characterAt(cursor.position()).toAscii() != '(':
454 return False
459 return False
455 context = self._get_context(cursor)
460 context = self._get_context(cursor)
456 if not context:
461 if not context:
457 return False
462 return False
458
463
459 # Send the metadata request to the kernel
464 # Send the metadata request to the kernel
460 name = '.'.join(context)
465 name = '.'.join(context)
461 msg_id = self.kernel_manager.xreq_channel.object_info(name)
466 msg_id = self.kernel_manager.xreq_channel.object_info(name)
462 pos = self._get_cursor().position()
467 pos = self._get_cursor().position()
463 self._request_info['call_tip'] = self._CallTipRequest(msg_id, pos)
468 self._request_info['call_tip'] = self._CallTipRequest(msg_id, pos)
464 return True
469 return True
465
470
466 def _complete(self):
471 def _complete(self):
467 """ Performs completion at the current cursor location.
472 """ Performs completion at the current cursor location.
468 """
473 """
469 context = self._get_context()
474 context = self._get_context()
470 if context:
475 if context:
471 # Send the completion request to the kernel
476 # Send the completion request to the kernel
472 msg_id = self.kernel_manager.xreq_channel.complete(
477 msg_id = self.kernel_manager.xreq_channel.complete(
473 '.'.join(context), # text
478 '.'.join(context), # text
474 self._get_input_buffer_cursor_line(), # line
479 self._get_input_buffer_cursor_line(), # line
475 self._get_input_buffer_cursor_column(), # cursor_pos
480 self._get_input_buffer_cursor_column(), # cursor_pos
476 self.input_buffer) # block
481 self.input_buffer) # block
477 pos = self._get_cursor().position()
482 pos = self._get_cursor().position()
478 info = self._CompletionRequest(msg_id, pos)
483 info = self._CompletionRequest(msg_id, pos)
479 self._request_info['complete'] = info
484 self._request_info['complete'] = info
480
485
481 def _get_banner(self):
486 def _get_banner(self):
482 """ Gets a banner to display at the beginning of a session.
487 """ Gets a banner to display at the beginning of a session.
483 """
488 """
484 banner = 'Python %s on %s\nType "help", "copyright", "credits" or ' \
489 banner = 'Python %s on %s\nType "help", "copyright", "credits" or ' \
485 '"license" for more information.'
490 '"license" for more information.'
486 return banner % (sys.version, sys.platform)
491 return banner % (sys.version, sys.platform)
487
492
488 def _get_context(self, cursor=None):
493 def _get_context(self, cursor=None):
489 """ Gets the context for the specified cursor (or the current cursor
494 """ Gets the context for the specified cursor (or the current cursor
490 if none is specified).
495 if none is specified).
491 """
496 """
492 if cursor is None:
497 if cursor is None:
493 cursor = self._get_cursor()
498 cursor = self._get_cursor()
494 cursor.movePosition(QtGui.QTextCursor.StartOfBlock,
499 cursor.movePosition(QtGui.QTextCursor.StartOfBlock,
495 QtGui.QTextCursor.KeepAnchor)
500 QtGui.QTextCursor.KeepAnchor)
496 text = unicode(cursor.selection().toPlainText())
501 text = unicode(cursor.selection().toPlainText())
497 return self._completion_lexer.get_context(text)
502 return self._completion_lexer.get_context(text)
498
503
499 def _process_execute_abort(self, msg):
504 def _process_execute_abort(self, msg):
500 """ Process a reply for an aborted execution request.
505 """ Process a reply for an aborted execution request.
501 """
506 """
502 self._append_plain_text("ERROR: execution aborted\n")
507 self._append_plain_text("ERROR: execution aborted\n")
503
508
504 def _process_execute_error(self, msg):
509 def _process_execute_error(self, msg):
505 """ Process a reply for an execution request that resulted in an error.
510 """ Process a reply for an execution request that resulted in an error.
506 """
511 """
507 content = msg['content']
512 content = msg['content']
508 traceback = ''.join(content['traceback'])
513 traceback = ''.join(content['traceback'])
509 self._append_plain_text(traceback)
514 self._append_plain_text(traceback)
510
515
511 def _process_execute_ok(self, msg):
516 def _process_execute_ok(self, msg):
512 """ Process a reply for a successful execution equest.
517 """ Process a reply for a successful execution equest.
513 """
518 """
514 payload = msg['content']['payload']
519 payload = msg['content']['payload']
515 for item in payload:
520 for item in payload:
516 if not self._process_execute_payload(item):
521 if not self._process_execute_payload(item):
517 warning = 'Warning: received unknown payload of type %s'
522 warning = 'Warning: received unknown payload of type %s'
518 print(warning % repr(item['source']))
523 print(warning % repr(item['source']))
519
524
520 def _process_execute_payload(self, item):
525 def _process_execute_payload(self, item):
521 """ Process a single payload item from the list of payload items in an
526 """ Process a single payload item from the list of payload items in an
522 execution reply. Returns whether the payload was handled.
527 execution reply. Returns whether the payload was handled.
523 """
528 """
524 # The basic FrontendWidget doesn't handle payloads, as they are a
529 # The basic FrontendWidget doesn't handle payloads, as they are a
525 # mechanism for going beyond the standard Python interpreter model.
530 # mechanism for going beyond the standard Python interpreter model.
526 return False
531 return False
527
532
528 def _show_interpreter_prompt(self):
533 def _show_interpreter_prompt(self):
529 """ Shows a prompt for the interpreter.
534 """ Shows a prompt for the interpreter.
530 """
535 """
531 self._show_prompt('>>> ')
536 self._show_prompt('>>> ')
532
537
533 def _show_interpreter_prompt_for_reply(self, msg):
538 def _show_interpreter_prompt_for_reply(self, msg):
534 """ Shows a prompt for the interpreter given an 'execute_reply' message.
539 """ Shows a prompt for the interpreter given an 'execute_reply' message.
535 """
540 """
536 self._show_interpreter_prompt()
541 self._show_interpreter_prompt()
537
542
538 #------ Signal handlers ----------------------------------------------------
543 #------ Signal handlers ----------------------------------------------------
539
544
540 def _document_contents_change(self, position, removed, added):
545 def _document_contents_change(self, position, removed, added):
541 """ Called whenever the document's content changes. Display a call tip
546 """ Called whenever the document's content changes. Display a call tip
542 if appropriate.
547 if appropriate.
543 """
548 """
544 # Calculate where the cursor should be *after* the change:
549 # Calculate where the cursor should be *after* the change:
545 position += added
550 position += added
546
551
547 document = self._control.document()
552 document = self._control.document()
548 if position == self._get_cursor().position():
553 if position == self._get_cursor().position():
549 self._call_tip()
554 self._call_tip()
@@ -1,627 +1,626 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
24
25 # System library imports.
25 # System library imports.
26 import zmq
26 import zmq
27
27
28 # Local imports.
28 # Local imports.
29 from IPython.config.configurable import Configurable
29 from IPython.config.configurable import Configurable
30 from IPython.utils import io
30 from IPython.utils import io
31 from IPython.utils.jsonutil import json_clean
31 from IPython.utils.jsonutil import json_clean
32 from IPython.lib import pylabtools
32 from IPython.lib import pylabtools
33 from IPython.utils.traitlets import Instance, Float
33 from IPython.utils.traitlets import Instance, Float
34 from entry_point import (base_launch_kernel, make_argument_parser, make_kernel,
34 from entry_point import (base_launch_kernel, make_argument_parser, make_kernel,
35 start_kernel)
35 start_kernel)
36 from iostream import OutStream
36 from iostream import OutStream
37 from session import Session, Message
37 from session import Session, Message
38 from zmqshell import ZMQInteractiveShell
38 from zmqshell import ZMQInteractiveShell
39
39
40 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
41 # Main kernel class
41 # Main kernel class
42 #-----------------------------------------------------------------------------
42 #-----------------------------------------------------------------------------
43
43
44 class Kernel(Configurable):
44 class Kernel(Configurable):
45
45
46 #---------------------------------------------------------------------------
46 #---------------------------------------------------------------------------
47 # Kernel interface
47 # Kernel interface
48 #---------------------------------------------------------------------------
48 #---------------------------------------------------------------------------
49
49
50 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
50 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
51 session = Instance(Session)
51 session = Instance(Session)
52 reply_socket = Instance('zmq.Socket')
52 reply_socket = Instance('zmq.Socket')
53 pub_socket = Instance('zmq.Socket')
53 pub_socket = Instance('zmq.Socket')
54 req_socket = Instance('zmq.Socket')
54 req_socket = Instance('zmq.Socket')
55
55
56 # Private interface
56 # Private interface
57
57
58 # Time to sleep after flushing the stdout/err buffers in each execute
58 # Time to sleep after flushing the stdout/err buffers in each execute
59 # cycle. While this introduces a hard limit on the minimal latency of the
59 # cycle. While this introduces a hard limit on the minimal latency of the
60 # execute cycle, it helps prevent output synchronization problems for
60 # execute cycle, it helps prevent output synchronization problems for
61 # clients.
61 # clients.
62 # Units are in seconds. The minimum zmq latency on local host is probably
62 # Units are in seconds. The minimum zmq latency on local host is probably
63 # ~150 microseconds, set this to 500us for now. We may need to increase it
63 # ~150 microseconds, set this to 500us for now. We may need to increase it
64 # a little if it's not enough after more interactive testing.
64 # a little if it's not enough after more interactive testing.
65 _execute_sleep = Float(0.0005, config=True)
65 _execute_sleep = Float(0.0005, config=True)
66
66
67 # Frequency of the kernel's event loop.
67 # Frequency of the kernel's event loop.
68 # Units are in seconds, kernel subclasses for GUI toolkits may need to
68 # Units are in seconds, kernel subclasses for GUI toolkits may need to
69 # adapt to milliseconds.
69 # adapt to milliseconds.
70 _poll_interval = Float(0.05, config=True)
70 _poll_interval = Float(0.05, config=True)
71
71
72 # If the shutdown was requested over the network, we leave here the
72 # If the shutdown was requested over the network, we leave here the
73 # necessary reply message so it can be sent by our registered atexit
73 # necessary reply message so it can be sent by our registered atexit
74 # handler. This ensures that the reply is only sent to clients truly at
74 # handler. This ensures that the reply is only sent to clients truly at
75 # the end of our shutdown process (which happens after the underlying
75 # the end of our shutdown process (which happens after the underlying
76 # IPython shell's own shutdown).
76 # IPython shell's own shutdown).
77 _shutdown_message = None
77 _shutdown_message = None
78
78
79 # This is a dict of port number that the kernel is listening on. It is set
79 # This is a dict of port number that the kernel is listening on. It is set
80 # by record_ports and used by connect_request.
80 # by record_ports and used by connect_request.
81 _recorded_ports = None
81 _recorded_ports = None
82
82
83 def __init__(self, **kwargs):
83 def __init__(self, **kwargs):
84 super(Kernel, self).__init__(**kwargs)
84 super(Kernel, self).__init__(**kwargs)
85
85
86 # Before we even start up the shell, register *first* our exit handlers
86 # Before we even start up the shell, register *first* our exit handlers
87 # so they come before the shell's
87 # so they come before the shell's
88 atexit.register(self._at_shutdown)
88 atexit.register(self._at_shutdown)
89
89
90 # Initialize the InteractiveShell subclass
90 # Initialize the InteractiveShell subclass
91 self.shell = ZMQInteractiveShell.instance()
91 self.shell = ZMQInteractiveShell.instance()
92 self.shell.displayhook.session = self.session
92 self.shell.displayhook.session = self.session
93 self.shell.displayhook.pub_socket = self.pub_socket
93 self.shell.displayhook.pub_socket = self.pub_socket
94
94
95 # TMP - hack while developing
95 # TMP - hack while developing
96 self.shell._reply_content = None
96 self.shell._reply_content = None
97
97
98 # Build dict of handlers for message types
98 # Build dict of handlers for message types
99 msg_types = [ 'execute_request', 'complete_request',
99 msg_types = [ 'execute_request', 'complete_request',
100 'object_info_request', 'history_request',
100 'object_info_request', 'history_request',
101 'connect_request', 'shutdown_request']
101 'connect_request', 'shutdown_request']
102 self.handlers = {}
102 self.handlers = {}
103 for msg_type in msg_types:
103 for msg_type in msg_types:
104 self.handlers[msg_type] = getattr(self, msg_type)
104 self.handlers[msg_type] = getattr(self, msg_type)
105
105
106 def do_one_iteration(self):
106 def do_one_iteration(self):
107 """Do one iteration of the kernel's evaluation loop.
107 """Do one iteration of the kernel's evaluation loop.
108 """
108 """
109 try:
109 try:
110 ident = self.reply_socket.recv(zmq.NOBLOCK)
110 ident = self.reply_socket.recv(zmq.NOBLOCK)
111 except zmq.ZMQError, e:
111 except zmq.ZMQError, e:
112 if e.errno == zmq.EAGAIN:
112 if e.errno == zmq.EAGAIN:
113 return
113 return
114 else:
114 else:
115 raise
115 raise
116 # FIXME: Bug in pyzmq/zmq?
116 # FIXME: Bug in pyzmq/zmq?
117 # assert self.reply_socket.rcvmore(), "Missing message part."
117 # assert self.reply_socket.rcvmore(), "Missing message part."
118 msg = self.reply_socket.recv_json()
118 msg = self.reply_socket.recv_json()
119
119
120 # Print some info about this message and leave a '--->' marker, so it's
120 # Print some info about this message and leave a '--->' marker, so it's
121 # easier to trace visually the message chain when debugging. Each
121 # easier to trace visually the message chain when debugging. Each
122 # handler prints its message at the end.
122 # handler prints its message at the end.
123 # Eventually we'll move these from stdout to a logger.
123 # Eventually we'll move these from stdout to a logger.
124 io.raw_print('\n*** MESSAGE TYPE:', msg['msg_type'], '***')
124 io.raw_print('\n*** MESSAGE TYPE:', msg['msg_type'], '***')
125 io.raw_print(' Content: ', msg['content'],
125 io.raw_print(' Content: ', msg['content'],
126 '\n --->\n ', sep='', end='')
126 '\n --->\n ', sep='', end='')
127
127
128 # Find and call actual handler for message
128 # Find and call actual handler for message
129 handler = self.handlers.get(msg['msg_type'], None)
129 handler = self.handlers.get(msg['msg_type'], None)
130 if handler is None:
130 if handler is None:
131 io.raw_print_err("UNKNOWN MESSAGE TYPE:", msg)
131 io.raw_print_err("UNKNOWN MESSAGE TYPE:", msg)
132 else:
132 else:
133 handler(ident, msg)
133 handler(ident, msg)
134
134
135 # Check whether we should exit, in case the incoming message set the
135 # Check whether we should exit, in case the incoming message set the
136 # exit flag on
136 # exit flag on
137 if self.shell.exit_now:
137 if self.shell.exit_now:
138 io.raw_print('\nExiting IPython kernel...')
138 io.raw_print('\nExiting IPython kernel...')
139 # We do a normal, clean exit, which allows any actions registered
139 # We do a normal, clean exit, which allows any actions registered
140 # via atexit (such as history saving) to take place.
140 # via atexit (such as history saving) to take place.
141 sys.exit(0)
141 sys.exit(0)
142
142
143
143
144 def start(self):
144 def start(self):
145 """ Start the kernel main loop.
145 """ Start the kernel main loop.
146 """
146 """
147 while True:
147 while True:
148 time.sleep(self._poll_interval)
148 time.sleep(self._poll_interval)
149 self.do_one_iteration()
149 self.do_one_iteration()
150
150
151 def record_ports(self, xrep_port, pub_port, req_port, hb_port):
151 def record_ports(self, xrep_port, pub_port, req_port, hb_port):
152 """Record the ports that this kernel is using.
152 """Record the ports that this kernel is using.
153
153
154 The creator of the Kernel instance must call this methods if they
154 The creator of the Kernel instance must call this methods if they
155 want the :meth:`connect_request` method to return the port numbers.
155 want the :meth:`connect_request` method to return the port numbers.
156 """
156 """
157 self._recorded_ports = {
157 self._recorded_ports = {
158 'xrep_port' : xrep_port,
158 'xrep_port' : xrep_port,
159 'pub_port' : pub_port,
159 'pub_port' : pub_port,
160 'req_port' : req_port,
160 'req_port' : req_port,
161 'hb_port' : hb_port
161 'hb_port' : hb_port
162 }
162 }
163
163
164 #---------------------------------------------------------------------------
164 #---------------------------------------------------------------------------
165 # Kernel request handlers
165 # Kernel request handlers
166 #---------------------------------------------------------------------------
166 #---------------------------------------------------------------------------
167
167
168 def _publish_pyin(self, code, parent):
168 def _publish_pyin(self, code, parent):
169 """Publish the code request on the pyin stream."""
169 """Publish the code request on the pyin stream."""
170
170
171 pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
171 pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
172 self.pub_socket.send_json(pyin_msg)
172 self.pub_socket.send_json(pyin_msg)
173
173
174 def execute_request(self, ident, parent):
174 def execute_request(self, ident, parent):
175
175
176 status_msg = self.session.msg(
176 status_msg = self.session.msg(
177 u'status',
177 u'status',
178 {u'execution_state':u'busy'},
178 {u'execution_state':u'busy'},
179 parent=parent
179 parent=parent
180 )
180 )
181 self.pub_socket.send_json(status_msg)
181 self.pub_socket.send_json(status_msg)
182
182
183 try:
183 try:
184 content = parent[u'content']
184 content = parent[u'content']
185 code = content[u'code']
185 code = content[u'code']
186 silent = content[u'silent']
186 silent = content[u'silent']
187 except:
187 except:
188 io.raw_print_err("Got bad msg: ")
188 io.raw_print_err("Got bad msg: ")
189 io.raw_print_err(Message(parent))
189 io.raw_print_err(Message(parent))
190 return
190 return
191
191
192 shell = self.shell # we'll need this a lot here
192 shell = self.shell # we'll need this a lot here
193
193
194 # Replace raw_input. Note that is not sufficient to replace
194 # Replace raw_input. Note that is not sufficient to replace
195 # raw_input in the user namespace.
195 # raw_input in the user namespace.
196 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
196 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
197 __builtin__.raw_input = raw_input
197 __builtin__.raw_input = raw_input
198
198
199 # Set the parent message of the display hook and out streams.
199 # Set the parent message of the display hook and out streams.
200 shell.displayhook.set_parent(parent)
200 shell.displayhook.set_parent(parent)
201 sys.stdout.set_parent(parent)
201 sys.stdout.set_parent(parent)
202 sys.stderr.set_parent(parent)
202 sys.stderr.set_parent(parent)
203
203
204 # Re-broadcast our input for the benefit of listening clients, and
204 # Re-broadcast our input for the benefit of listening clients, and
205 # start computing output
205 # start computing output
206 if not silent:
206 if not silent:
207 self._publish_pyin(code, parent)
207 self._publish_pyin(code, parent)
208
208
209 reply_content = {}
209 reply_content = {}
210 try:
210 try:
211 if silent:
211 if silent:
212 # runcode uses 'exec' mode, so no displayhook will fire, and it
212 # runcode uses 'exec' mode, so no displayhook will fire, and it
213 # doesn't call logging or history manipulations. Print
213 # doesn't call logging or history manipulations. Print
214 # statements in that code will obviously still execute.
214 # statements in that code will obviously still execute.
215 shell.runcode(code)
215 shell.runcode(code)
216 else:
216 else:
217 # FIXME: runlines calls the exception handler itself.
217 # FIXME: runlines calls the exception handler itself.
218 shell._reply_content = None
218 shell._reply_content = None
219
219
220 # For now leave this here until we're sure we can stop using it
220 # For now leave this here until we're sure we can stop using it
221 #shell.runlines(code)
221 #shell.runlines(code)
222
222
223 # Experimental: cell mode! Test more before turning into
223 # Experimental: cell mode! Test more before turning into
224 # default and removing the hacks around runlines.
224 # default and removing the hacks around runlines.
225 shell.run_cell(code)
225 shell.run_cell(code)
226 except:
226 except:
227 status = u'error'
227 status = u'error'
228 # FIXME: this code right now isn't being used yet by default,
228 # FIXME: this code right now isn't being used yet by default,
229 # because the runlines() call above directly fires off exception
229 # because the runlines() call above directly fires off exception
230 # reporting. This code, therefore, is only active in the scenario
230 # reporting. This code, therefore, is only active in the scenario
231 # where runlines itself has an unhandled exception. We need to
231 # where runlines itself has an unhandled exception. We need to
232 # uniformize this, for all exception construction to come from a
232 # uniformize this, for all exception construction to come from a
233 # single location in the codbase.
233 # single location in the codbase.
234 etype, evalue, tb = sys.exc_info()
234 etype, evalue, tb = sys.exc_info()
235 tb_list = traceback.format_exception(etype, evalue, tb)
235 tb_list = traceback.format_exception(etype, evalue, tb)
236 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
236 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
237 else:
237 else:
238 status = u'ok'
238 status = u'ok'
239
239
240 reply_content[u'status'] = status
240 reply_content[u'status'] = status
241 # Compute the execution counter so clients can display prompts
241 # Compute the execution counter so clients can display prompts
242 reply_content['execution_count'] = shell.displayhook.prompt_count
242 reply_content['execution_count'] = shell.displayhook.prompt_count
243
243
244 # FIXME - fish exception info out of shell, possibly left there by
244 # FIXME - fish exception info out of shell, possibly left there by
245 # runlines. We'll need to clean up this logic later.
245 # runlines. We'll need to clean up this logic later.
246 if shell._reply_content is not None:
246 if shell._reply_content is not None:
247 reply_content.update(shell._reply_content)
247 reply_content.update(shell._reply_content)
248
248
249 # At this point, we can tell whether the main code execution succeeded
249 # At this point, we can tell whether the main code execution succeeded
250 # or not. If it did, we proceed to evaluate user_variables/expressions
250 # or not. If it did, we proceed to evaluate user_variables/expressions
251 if reply_content['status'] == 'ok':
251 if reply_content['status'] == 'ok':
252 reply_content[u'user_variables'] = \
252 reply_content[u'user_variables'] = \
253 shell.user_variables(content[u'user_variables'])
253 shell.user_variables(content[u'user_variables'])
254 reply_content[u'user_expressions'] = \
254 reply_content[u'user_expressions'] = \
255 shell.user_expressions(content[u'user_expressions'])
255 shell.user_expressions(content[u'user_expressions'])
256 else:
256 else:
257 # If there was an error, don't even try to compute variables or
257 # If there was an error, don't even try to compute variables or
258 # expressions
258 # expressions
259 reply_content[u'user_variables'] = {}
259 reply_content[u'user_variables'] = {}
260 reply_content[u'user_expressions'] = {}
260 reply_content[u'user_expressions'] = {}
261
261
262 # Payloads should be retrieved regardless of outcome, so we can both
262 # Payloads should be retrieved regardless of outcome, so we can both
263 # recover partial output (that could have been generated early in a
263 # recover partial output (that could have been generated early in a
264 # block, before an error) and clear the payload system always.
264 # block, before an error) and clear the payload system always.
265 reply_content[u'payload'] = shell.payload_manager.read_payload()
265 reply_content[u'payload'] = shell.payload_manager.read_payload()
266 # Be agressive about clearing the payload because we don't want
266 # Be agressive about clearing the payload because we don't want
267 # it to sit in memory until the next execute_request comes in.
267 # it to sit in memory until the next execute_request comes in.
268 shell.payload_manager.clear_payload()
268 shell.payload_manager.clear_payload()
269
269
270 # Send the reply.
270 # Send the reply.
271 reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
271 reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
272 io.raw_print(reply_msg)
272 io.raw_print(reply_msg)
273
273
274 # Flush output before sending the reply.
274 # Flush output before sending the reply.
275 sys.stdout.flush()
275 sys.stdout.flush()
276 sys.stderr.flush()
276 sys.stderr.flush()
277 # FIXME: on rare occasions, the flush doesn't seem to make it to the
277 # FIXME: on rare occasions, the flush doesn't seem to make it to the
278 # clients... This seems to mitigate the problem, but we definitely need
278 # clients... This seems to mitigate the problem, but we definitely need
279 # to better understand what's going on.
279 # to better understand what's going on.
280 if self._execute_sleep:
280 if self._execute_sleep:
281 time.sleep(self._execute_sleep)
281 time.sleep(self._execute_sleep)
282
282
283 self.reply_socket.send(ident, zmq.SNDMORE)
283 self.reply_socket.send(ident, zmq.SNDMORE)
284 self.reply_socket.send_json(reply_msg)
284 self.reply_socket.send_json(reply_msg)
285 if reply_msg['content']['status'] == u'error':
285 if reply_msg['content']['status'] == u'error':
286 self._abort_queue()
286 self._abort_queue()
287
287
288 status_msg = self.session.msg(
288 status_msg = self.session.msg(
289 u'status',
289 u'status',
290 {u'execution_state':u'idle'},
290 {u'execution_state':u'idle'},
291 parent=parent
291 parent=parent
292 )
292 )
293 self.pub_socket.send_json(status_msg)
293 self.pub_socket.send_json(status_msg)
294
294
295 def complete_request(self, ident, parent):
295 def complete_request(self, ident, parent):
296 txt, matches = self._complete(parent)
296 txt, matches = self._complete(parent)
297 matches = {'matches' : matches,
297 matches = {'matches' : matches,
298 'matched_text' : txt,
298 'matched_text' : txt,
299 'status' : 'ok'}
299 'status' : 'ok'}
300 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
300 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
301 matches, parent, ident)
301 matches, parent, ident)
302 io.raw_print(completion_msg)
302 io.raw_print(completion_msg)
303
303
304 def object_info_request(self, ident, parent):
304 def object_info_request(self, ident, parent):
305 object_info = self.shell.object_inspect(parent['content']['oname'])
305 object_info = self.shell.object_inspect(parent['content']['oname'])
306 # Before we send this object over, we turn it into a dict and we scrub
306 # Before we send this object over, we scrub it for JSON usage
307 # it for JSON usage
307 oinfo = json_clean(object_info)
308 oinfo = json_clean(object_info._asdict())
309 msg = self.session.send(self.reply_socket, 'object_info_reply',
308 msg = self.session.send(self.reply_socket, 'object_info_reply',
310 oinfo, parent, ident)
309 oinfo, parent, ident)
311 io.raw_print(msg)
310 io.raw_print(msg)
312
311
313 def history_request(self, ident, parent):
312 def history_request(self, ident, parent):
314 output = parent['content']['output']
313 output = parent['content']['output']
315 index = parent['content']['index']
314 index = parent['content']['index']
316 raw = parent['content']['raw']
315 raw = parent['content']['raw']
317 hist = self.shell.get_history(index=index, raw=raw, output=output)
316 hist = self.shell.get_history(index=index, raw=raw, output=output)
318 content = {'history' : hist}
317 content = {'history' : hist}
319 msg = self.session.send(self.reply_socket, 'history_reply',
318 msg = self.session.send(self.reply_socket, 'history_reply',
320 content, parent, ident)
319 content, parent, ident)
321 io.raw_print(msg)
320 io.raw_print(msg)
322
321
323 def connect_request(self, ident, parent):
322 def connect_request(self, ident, parent):
324 if self._recorded_ports is not None:
323 if self._recorded_ports is not None:
325 content = self._recorded_ports.copy()
324 content = self._recorded_ports.copy()
326 else:
325 else:
327 content = {}
326 content = {}
328 msg = self.session.send(self.reply_socket, 'connect_reply',
327 msg = self.session.send(self.reply_socket, 'connect_reply',
329 content, parent, ident)
328 content, parent, ident)
330 io.raw_print(msg)
329 io.raw_print(msg)
331
330
332 def shutdown_request(self, ident, parent):
331 def shutdown_request(self, ident, parent):
333 self.shell.exit_now = True
332 self.shell.exit_now = True
334 self._shutdown_message = self.session.msg(u'shutdown_reply', {}, parent)
333 self._shutdown_message = self.session.msg(u'shutdown_reply', {}, parent)
335 sys.exit(0)
334 sys.exit(0)
336
335
337 #---------------------------------------------------------------------------
336 #---------------------------------------------------------------------------
338 # Protected interface
337 # Protected interface
339 #---------------------------------------------------------------------------
338 #---------------------------------------------------------------------------
340
339
341 def _abort_queue(self):
340 def _abort_queue(self):
342 while True:
341 while True:
343 try:
342 try:
344 ident = self.reply_socket.recv(zmq.NOBLOCK)
343 ident = self.reply_socket.recv(zmq.NOBLOCK)
345 except zmq.ZMQError, e:
344 except zmq.ZMQError, e:
346 if e.errno == zmq.EAGAIN:
345 if e.errno == zmq.EAGAIN:
347 break
346 break
348 else:
347 else:
349 assert self.reply_socket.rcvmore(), \
348 assert self.reply_socket.rcvmore(), \
350 "Unexpected missing message part."
349 "Unexpected missing message part."
351 msg = self.reply_socket.recv_json()
350 msg = self.reply_socket.recv_json()
352 io.raw_print("Aborting:\n", Message(msg))
351 io.raw_print("Aborting:\n", Message(msg))
353 msg_type = msg['msg_type']
352 msg_type = msg['msg_type']
354 reply_type = msg_type.split('_')[0] + '_reply'
353 reply_type = msg_type.split('_')[0] + '_reply'
355 reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
354 reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
356 io.raw_print(reply_msg)
355 io.raw_print(reply_msg)
357 self.reply_socket.send(ident,zmq.SNDMORE)
356 self.reply_socket.send(ident,zmq.SNDMORE)
358 self.reply_socket.send_json(reply_msg)
357 self.reply_socket.send_json(reply_msg)
359 # We need to wait a bit for requests to come in. This can probably
358 # We need to wait a bit for requests to come in. This can probably
360 # be set shorter for true asynchronous clients.
359 # be set shorter for true asynchronous clients.
361 time.sleep(0.1)
360 time.sleep(0.1)
362
361
363 def _raw_input(self, prompt, ident, parent):
362 def _raw_input(self, prompt, ident, parent):
364 # Flush output before making the request.
363 # Flush output before making the request.
365 sys.stderr.flush()
364 sys.stderr.flush()
366 sys.stdout.flush()
365 sys.stdout.flush()
367
366
368 # Send the input request.
367 # Send the input request.
369 content = dict(prompt=prompt)
368 content = dict(prompt=prompt)
370 msg = self.session.msg(u'input_request', content, parent)
369 msg = self.session.msg(u'input_request', content, parent)
371 self.req_socket.send_json(msg)
370 self.req_socket.send_json(msg)
372
371
373 # Await a response.
372 # Await a response.
374 reply = self.req_socket.recv_json()
373 reply = self.req_socket.recv_json()
375 try:
374 try:
376 value = reply['content']['value']
375 value = reply['content']['value']
377 except:
376 except:
378 io.raw_print_err("Got bad raw_input reply: ")
377 io.raw_print_err("Got bad raw_input reply: ")
379 io.raw_print_err(Message(parent))
378 io.raw_print_err(Message(parent))
380 value = ''
379 value = ''
381 return value
380 return value
382
381
383 def _complete(self, msg):
382 def _complete(self, msg):
384 c = msg['content']
383 c = msg['content']
385 try:
384 try:
386 cpos = int(c['cursor_pos'])
385 cpos = int(c['cursor_pos'])
387 except:
386 except:
388 # If we don't get something that we can convert to an integer, at
387 # If we don't get something that we can convert to an integer, at
389 # least attempt the completion guessing the cursor is at the end of
388 # least attempt the completion guessing the cursor is at the end of
390 # the text, if there's any, and otherwise of the line
389 # the text, if there's any, and otherwise of the line
391 cpos = len(c['text'])
390 cpos = len(c['text'])
392 if cpos==0:
391 if cpos==0:
393 cpos = len(c['line'])
392 cpos = len(c['line'])
394 return self.shell.complete(c['text'], c['line'], cpos)
393 return self.shell.complete(c['text'], c['line'], cpos)
395
394
396 def _object_info(self, context):
395 def _object_info(self, context):
397 symbol, leftover = self._symbol_from_context(context)
396 symbol, leftover = self._symbol_from_context(context)
398 if symbol is not None and not leftover:
397 if symbol is not None and not leftover:
399 doc = getattr(symbol, '__doc__', '')
398 doc = getattr(symbol, '__doc__', '')
400 else:
399 else:
401 doc = ''
400 doc = ''
402 object_info = dict(docstring = doc)
401 object_info = dict(docstring = doc)
403 return object_info
402 return object_info
404
403
405 def _symbol_from_context(self, context):
404 def _symbol_from_context(self, context):
406 if not context:
405 if not context:
407 return None, context
406 return None, context
408
407
409 base_symbol_string = context[0]
408 base_symbol_string = context[0]
410 symbol = self.shell.user_ns.get(base_symbol_string, None)
409 symbol = self.shell.user_ns.get(base_symbol_string, None)
411 if symbol is None:
410 if symbol is None:
412 symbol = __builtin__.__dict__.get(base_symbol_string, None)
411 symbol = __builtin__.__dict__.get(base_symbol_string, None)
413 if symbol is None:
412 if symbol is None:
414 return None, context
413 return None, context
415
414
416 context = context[1:]
415 context = context[1:]
417 for i, name in enumerate(context):
416 for i, name in enumerate(context):
418 new_symbol = getattr(symbol, name, None)
417 new_symbol = getattr(symbol, name, None)
419 if new_symbol is None:
418 if new_symbol is None:
420 return symbol, context[i:]
419 return symbol, context[i:]
421 else:
420 else:
422 symbol = new_symbol
421 symbol = new_symbol
423
422
424 return symbol, []
423 return symbol, []
425
424
426 def _at_shutdown(self):
425 def _at_shutdown(self):
427 """Actions taken at shutdown by the kernel, called by python's atexit.
426 """Actions taken at shutdown by the kernel, called by python's atexit.
428 """
427 """
429 # io.rprint("Kernel at_shutdown") # dbg
428 # io.rprint("Kernel at_shutdown") # dbg
430 if self._shutdown_message is not None:
429 if self._shutdown_message is not None:
431 self.reply_socket.send_json(self._shutdown_message)
430 self.reply_socket.send_json(self._shutdown_message)
432 io.raw_print(self._shutdown_message)
431 io.raw_print(self._shutdown_message)
433 # A very short sleep to give zmq time to flush its message buffers
432 # A very short sleep to give zmq time to flush its message buffers
434 # before Python truly shuts down.
433 # before Python truly shuts down.
435 time.sleep(0.01)
434 time.sleep(0.01)
436
435
437
436
438 class QtKernel(Kernel):
437 class QtKernel(Kernel):
439 """A Kernel subclass with Qt support."""
438 """A Kernel subclass with Qt support."""
440
439
441 def start(self):
440 def start(self):
442 """Start a kernel with QtPy4 event loop integration."""
441 """Start a kernel with QtPy4 event loop integration."""
443
442
444 from PyQt4 import QtCore
443 from PyQt4 import QtCore
445 from IPython.lib.guisupport import get_app_qt4, start_event_loop_qt4
444 from IPython.lib.guisupport import get_app_qt4, start_event_loop_qt4
446
445
447 self.app = get_app_qt4([" "])
446 self.app = get_app_qt4([" "])
448 self.app.setQuitOnLastWindowClosed(False)
447 self.app.setQuitOnLastWindowClosed(False)
449 self.timer = QtCore.QTimer()
448 self.timer = QtCore.QTimer()
450 self.timer.timeout.connect(self.do_one_iteration)
449 self.timer.timeout.connect(self.do_one_iteration)
451 # Units for the timer are in milliseconds
450 # Units for the timer are in milliseconds
452 self.timer.start(1000*self._poll_interval)
451 self.timer.start(1000*self._poll_interval)
453 start_event_loop_qt4(self.app)
452 start_event_loop_qt4(self.app)
454
453
455
454
456 class WxKernel(Kernel):
455 class WxKernel(Kernel):
457 """A Kernel subclass with Wx support."""
456 """A Kernel subclass with Wx support."""
458
457
459 def start(self):
458 def start(self):
460 """Start a kernel with wx event loop support."""
459 """Start a kernel with wx event loop support."""
461
460
462 import wx
461 import wx
463 from IPython.lib.guisupport import start_event_loop_wx
462 from IPython.lib.guisupport import start_event_loop_wx
464
463
465 doi = self.do_one_iteration
464 doi = self.do_one_iteration
466 # Wx uses milliseconds
465 # Wx uses milliseconds
467 poll_interval = int(1000*self._poll_interval)
466 poll_interval = int(1000*self._poll_interval)
468
467
469 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
468 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
470 # We make the Frame hidden when we create it in the main app below.
469 # We make the Frame hidden when we create it in the main app below.
471 class TimerFrame(wx.Frame):
470 class TimerFrame(wx.Frame):
472 def __init__(self, func):
471 def __init__(self, func):
473 wx.Frame.__init__(self, None, -1)
472 wx.Frame.__init__(self, None, -1)
474 self.timer = wx.Timer(self)
473 self.timer = wx.Timer(self)
475 # Units for the timer are in milliseconds
474 # Units for the timer are in milliseconds
476 self.timer.Start(poll_interval)
475 self.timer.Start(poll_interval)
477 self.Bind(wx.EVT_TIMER, self.on_timer)
476 self.Bind(wx.EVT_TIMER, self.on_timer)
478 self.func = func
477 self.func = func
479
478
480 def on_timer(self, event):
479 def on_timer(self, event):
481 self.func()
480 self.func()
482
481
483 # We need a custom wx.App to create our Frame subclass that has the
482 # We need a custom wx.App to create our Frame subclass that has the
484 # wx.Timer to drive the ZMQ event loop.
483 # wx.Timer to drive the ZMQ event loop.
485 class IPWxApp(wx.App):
484 class IPWxApp(wx.App):
486 def OnInit(self):
485 def OnInit(self):
487 self.frame = TimerFrame(doi)
486 self.frame = TimerFrame(doi)
488 self.frame.Show(False)
487 self.frame.Show(False)
489 return True
488 return True
490
489
491 # The redirect=False here makes sure that wx doesn't replace
490 # The redirect=False here makes sure that wx doesn't replace
492 # sys.stdout/stderr with its own classes.
491 # sys.stdout/stderr with its own classes.
493 self.app = IPWxApp(redirect=False)
492 self.app = IPWxApp(redirect=False)
494 start_event_loop_wx(self.app)
493 start_event_loop_wx(self.app)
495
494
496
495
497 class TkKernel(Kernel):
496 class TkKernel(Kernel):
498 """A Kernel subclass with Tk support."""
497 """A Kernel subclass with Tk support."""
499
498
500 def start(self):
499 def start(self):
501 """Start a Tk enabled event loop."""
500 """Start a Tk enabled event loop."""
502
501
503 import Tkinter
502 import Tkinter
504 doi = self.do_one_iteration
503 doi = self.do_one_iteration
505 # Tk uses milliseconds
504 # Tk uses milliseconds
506 poll_interval = int(1000*self._poll_interval)
505 poll_interval = int(1000*self._poll_interval)
507 # For Tkinter, we create a Tk object and call its withdraw method.
506 # For Tkinter, we create a Tk object and call its withdraw method.
508 class Timer(object):
507 class Timer(object):
509 def __init__(self, func):
508 def __init__(self, func):
510 self.app = Tkinter.Tk()
509 self.app = Tkinter.Tk()
511 self.app.withdraw()
510 self.app.withdraw()
512 self.func = func
511 self.func = func
513
512
514 def on_timer(self):
513 def on_timer(self):
515 self.func()
514 self.func()
516 self.app.after(poll_interval, self.on_timer)
515 self.app.after(poll_interval, self.on_timer)
517
516
518 def start(self):
517 def start(self):
519 self.on_timer() # Call it once to get things going.
518 self.on_timer() # Call it once to get things going.
520 self.app.mainloop()
519 self.app.mainloop()
521
520
522 self.timer = Timer(doi)
521 self.timer = Timer(doi)
523 self.timer.start()
522 self.timer.start()
524
523
525
524
526 class GTKKernel(Kernel):
525 class GTKKernel(Kernel):
527 """A Kernel subclass with GTK support."""
526 """A Kernel subclass with GTK support."""
528
527
529 def start(self):
528 def start(self):
530 """Start the kernel, coordinating with the GTK event loop"""
529 """Start the kernel, coordinating with the GTK event loop"""
531 from .gui.gtkembed import GTKEmbed
530 from .gui.gtkembed import GTKEmbed
532
531
533 gtk_kernel = GTKEmbed(self)
532 gtk_kernel = GTKEmbed(self)
534 gtk_kernel.start()
533 gtk_kernel.start()
535
534
536
535
537 #-----------------------------------------------------------------------------
536 #-----------------------------------------------------------------------------
538 # Kernel main and launch functions
537 # Kernel main and launch functions
539 #-----------------------------------------------------------------------------
538 #-----------------------------------------------------------------------------
540
539
541 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
540 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
542 independent=False, pylab=False):
541 independent=False, pylab=False):
543 """Launches a localhost kernel, binding to the specified ports.
542 """Launches a localhost kernel, binding to the specified ports.
544
543
545 Parameters
544 Parameters
546 ----------
545 ----------
547 xrep_port : int, optional
546 xrep_port : int, optional
548 The port to use for XREP channel.
547 The port to use for XREP channel.
549
548
550 pub_port : int, optional
549 pub_port : int, optional
551 The port to use for the SUB channel.
550 The port to use for the SUB channel.
552
551
553 req_port : int, optional
552 req_port : int, optional
554 The port to use for the REQ (raw input) channel.
553 The port to use for the REQ (raw input) channel.
555
554
556 hb_port : int, optional
555 hb_port : int, optional
557 The port to use for the hearbeat REP channel.
556 The port to use for the hearbeat REP channel.
558
557
559 independent : bool, optional (default False)
558 independent : bool, optional (default False)
560 If set, the kernel process is guaranteed to survive if this process
559 If set, the kernel process is guaranteed to survive if this process
561 dies. If not set, an effort is made to ensure that the kernel is killed
560 dies. If not set, an effort is made to ensure that the kernel is killed
562 when this process dies. Note that in this case it is still good practice
561 when this process dies. Note that in this case it is still good practice
563 to kill kernels manually before exiting.
562 to kill kernels manually before exiting.
564
563
565 pylab : bool or string, optional (default False)
564 pylab : bool or string, optional (default False)
566 If not False, the kernel will be launched with pylab enabled. If a
565 If not False, the kernel will be launched with pylab enabled. If a
567 string is passed, matplotlib will use the specified backend. Otherwise,
566 string is passed, matplotlib will use the specified backend. Otherwise,
568 matplotlib's default backend will be used.
567 matplotlib's default backend will be used.
569
568
570 Returns
569 Returns
571 -------
570 -------
572 A tuple of form:
571 A tuple of form:
573 (kernel_process, xrep_port, pub_port, req_port)
572 (kernel_process, xrep_port, pub_port, req_port)
574 where kernel_process is a Popen object and the ports are integers.
573 where kernel_process is a Popen object and the ports are integers.
575 """
574 """
576 extra_arguments = []
575 extra_arguments = []
577 if pylab:
576 if pylab:
578 extra_arguments.append('--pylab')
577 extra_arguments.append('--pylab')
579 if isinstance(pylab, basestring):
578 if isinstance(pylab, basestring):
580 extra_arguments.append(pylab)
579 extra_arguments.append(pylab)
581 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
580 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
582 xrep_port, pub_port, req_port, hb_port,
581 xrep_port, pub_port, req_port, hb_port,
583 independent, extra_arguments)
582 independent, extra_arguments)
584
583
585
584
586 def main():
585 def main():
587 """ The IPython kernel main entry point.
586 """ The IPython kernel main entry point.
588 """
587 """
589 parser = make_argument_parser()
588 parser = make_argument_parser()
590 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
589 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
591 const='auto', help = \
590 const='auto', help = \
592 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
591 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
593 given, the GUI backend is matplotlib's, otherwise use one of: \
592 given, the GUI backend is matplotlib's, otherwise use one of: \
594 ['tk', 'gtk', 'qt', 'wx', 'inline'].")
593 ['tk', 'gtk', 'qt', 'wx', 'inline'].")
595 namespace = parser.parse_args()
594 namespace = parser.parse_args()
596
595
597 kernel_class = Kernel
596 kernel_class = Kernel
598
597
599 kernel_classes = {
598 kernel_classes = {
600 'qt' : QtKernel,
599 'qt' : QtKernel,
601 'qt4': QtKernel,
600 'qt4': QtKernel,
602 'inline': Kernel,
601 'inline': Kernel,
603 'wx' : WxKernel,
602 'wx' : WxKernel,
604 'tk' : TkKernel,
603 'tk' : TkKernel,
605 'gtk': GTKKernel,
604 'gtk': GTKKernel,
606 }
605 }
607 if namespace.pylab:
606 if namespace.pylab:
608 if namespace.pylab == 'auto':
607 if namespace.pylab == 'auto':
609 gui, backend = pylabtools.find_gui_and_backend()
608 gui, backend = pylabtools.find_gui_and_backend()
610 else:
609 else:
611 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
610 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
612 kernel_class = kernel_classes.get(gui)
611 kernel_class = kernel_classes.get(gui)
613 if kernel_class is None:
612 if kernel_class is None:
614 raise ValueError('GUI is not supported: %r' % gui)
613 raise ValueError('GUI is not supported: %r' % gui)
615 pylabtools.activate_matplotlib(backend)
614 pylabtools.activate_matplotlib(backend)
616
615
617 kernel = make_kernel(namespace, kernel_class, OutStream)
616 kernel = make_kernel(namespace, kernel_class, OutStream)
618
617
619 if namespace.pylab:
618 if namespace.pylab:
620 pylabtools.import_pylab(kernel.shell.user_ns, backend,
619 pylabtools.import_pylab(kernel.shell.user_ns, backend,
621 shell=kernel.shell)
620 shell=kernel.shell)
622
621
623 start_kernel(namespace, kernel)
622 start_kernel(namespace, kernel)
624
623
625
624
626 if __name__ == '__main__':
625 if __name__ == '__main__':
627 main()
626 main()
@@ -1,868 +1,871 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:: frontend-kernel.png
25 .. image:: 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. REQ: this socket is connected to a *single* frontend at a time, and it allows
34 1. REQ: this socket is connected to a *single* frontend at a time, and it allows
35 the kernel to request input from a frontend when :func:`raw_input` is called.
35 the kernel to request input from a frontend when :func:`raw_input` is called.
36 The frontend holding the matching REP socket acts as a 'virtual keyboard'
36 The frontend holding the matching REP socket 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. XREP: this single sockets allows multiple incoming connections from
43 2. XREP: this single sockets 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. PUB: this socket is the 'broadcast channel' where the kernel publishes all
49 3. PUB: 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 XREP socket and its own requests on the REP socket. There
51 client over the XREP socket and its own requests on the REP 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 XREQ/XREP channel
57 about communications taking place with one client over the XREQ/XREP 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
81
82 Python functional API
82 Python functional API
83 =====================
83 =====================
84
84
85 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
85 As messages are dicts, they map naturally to a ``func(**kw)`` call form. We
86 should develop, at a few key points, functional forms of all the requests that
86 should develop, at a few key points, functional forms of all the requests that
87 take arguments in this manner and automatically construct the necessary dict
87 take arguments in this manner and automatically construct the necessary dict
88 for sending.
88 for sending.
89
89
90
90
91 General Message Format
91 General Message Format
92 ======================
92 ======================
93
93
94 All messages send or received by any IPython process should have the following
94 All messages send or received by any IPython process should have the following
95 generic structure::
95 generic structure::
96
96
97 {
97 {
98 # The message header contains a pair of unique identifiers for the
98 # The message header contains a pair of unique identifiers for the
99 # originating session and the actual message id, in addition to the
99 # originating session and the actual message id, in addition to the
100 # username for the process that generated the message. This is useful in
100 # username for the process that generated the message. This is useful in
101 # collaborative settings where multiple users may be interacting with the
101 # collaborative settings where multiple users may be interacting with the
102 # same kernel simultaneously, so that frontends can label the various
102 # same kernel simultaneously, so that frontends can label the various
103 # messages in a meaningful way.
103 # messages in a meaningful way.
104 'header' : { 'msg_id' : uuid,
104 'header' : { 'msg_id' : uuid,
105 'username' : str,
105 'username' : str,
106 'session' : uuid
106 'session' : uuid
107 },
107 },
108
108
109 # In a chain of messages, the header from the parent is copied so that
109 # In a chain of messages, the header from the parent is copied so that
110 # clients can track where messages come from.
110 # clients can track where messages come from.
111 'parent_header' : dict,
111 'parent_header' : dict,
112
112
113 # All recognized message type strings are listed below.
113 # All recognized message type strings are listed below.
114 'msg_type' : str,
114 'msg_type' : str,
115
115
116 # The actual content of the message must be a dict, whose structure
116 # The actual content of the message must be a dict, whose structure
117 # depends on the message type.x
117 # depends on the message type.x
118 'content' : dict,
118 'content' : dict,
119 }
119 }
120
120
121 For each message type, the actual content will differ and all existing message
121 For each message type, the actual content will differ and all existing message
122 types are specified in what follows of this document.
122 types are specified in what follows of this document.
123
123
124
124
125 Messages on the XREP/XREQ socket
125 Messages on the XREP/XREQ socket
126 ================================
126 ================================
127
127
128 .. _execute:
128 .. _execute:
129
129
130 Execute
130 Execute
131 -------
131 -------
132
132
133 This message type is used by frontends to ask the kernel to execute code on
133 This message type is used by frontends to ask the kernel to execute code on
134 behalf of the user, in a namespace reserved to the user's variables (and thus
134 behalf of the user, in a namespace reserved to the user's variables (and thus
135 separate from the kernel's own internal code and variables).
135 separate from the kernel's own internal code and variables).
136
136
137 Message type: ``execute_request``::
137 Message type: ``execute_request``::
138
138
139 content = {
139 content = {
140 # Source code to be executed by the kernel, one or more lines.
140 # Source code to be executed by the kernel, one or more lines.
141 'code' : str,
141 'code' : str,
142
142
143 # A boolean flag which, if True, signals the kernel to execute this
143 # A boolean flag which, if True, signals the kernel to execute this
144 # code as quietly as possible. This means that the kernel will compile
144 # code as quietly as possible. This means that the kernel will compile
145 # the code witIPython/core/tests/h 'exec' instead of 'single' (so
145 # the code witIPython/core/tests/h 'exec' instead of 'single' (so
146 # sys.displayhook will not fire), and will *not*:
146 # sys.displayhook will not fire), and will *not*:
147 # - broadcast exceptions on the PUB socket
147 # - broadcast exceptions on the PUB socket
148 # - do any logging
148 # - do any logging
149 # - populate any history
149 # - populate any history
150 #
150 #
151 # The default is False.
151 # The default is False.
152 'silent' : bool,
152 'silent' : bool,
153
153
154 # A list of variable names from the user's namespace to be retrieved. What
154 # A list of variable names from the user's namespace to be retrieved. What
155 # returns is a JSON string of the variable's repr(), not a python object.
155 # returns is a JSON string of the variable's repr(), not a python object.
156 'user_variables' : list,
156 'user_variables' : list,
157
157
158 # Similarly, a dict mapping names to expressions to be evaluated in the
158 # Similarly, a dict mapping names to expressions to be evaluated in the
159 # user's dict.
159 # user's dict.
160 'user_expressions' : dict,
160 'user_expressions' : dict,
161 }
161 }
162
162
163 The ``code`` field contains a single string (possibly multiline). The kernel
163 The ``code`` field contains a single string (possibly multiline). The kernel
164 is responsible for splitting this into one or more independent execution blocks
164 is responsible for splitting this into one or more independent execution blocks
165 and deciding whether to compile these in 'single' or 'exec' mode (see below for
165 and deciding whether to compile these in 'single' or 'exec' mode (see below for
166 detailed execution semantics).
166 detailed execution semantics).
167
167
168 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
168 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
169 the notion of a prompt string that allowed arbitrary code to be evaluated, and
169 the notion of a prompt string that allowed arbitrary code to be evaluated, and
170 this was put to good use by many in creating prompts that displayed system
170 this was put to good use by many in creating prompts that displayed system
171 status, path information, and even more esoteric uses like remote instrument
171 status, path information, and even more esoteric uses like remote instrument
172 status aqcuired over the network. But now that IPython has a clean separation
172 status aqcuired over the network. But now that IPython has a clean separation
173 between the kernel and the clients, the kernel has no prompt knowledge; prompts
173 between the kernel and the clients, the kernel has no prompt knowledge; prompts
174 are a frontend-side feature, and it should be even possible for different
174 are a frontend-side feature, and it should be even possible for different
175 frontends to display different prompts while interacting with the same kernel.
175 frontends to display different prompts while interacting with the same kernel.
176
176
177 The kernel now provides the ability to retrieve data from the user's namespace
177 The kernel now provides the ability to retrieve data from the user's namespace
178 after the execution of the main ``code``, thanks to two fields in the
178 after the execution of the main ``code``, thanks to two fields in the
179 ``execute_request`` message:
179 ``execute_request`` message:
180
180
181 - ``user_variables``: If only variables from the user's namespace are needed, a
181 - ``user_variables``: If only variables from the user's namespace are needed, a
182 list of variable names can be passed and a dict with these names as keys and
182 list of variable names can be passed and a dict with these names as keys and
183 their :func:`repr()` as values will be returned.
183 their :func:`repr()` as values will be returned.
184
184
185 - ``user_expressions``: For more complex expressions that require function
185 - ``user_expressions``: For more complex expressions that require function
186 evaluations, a dict can be provided with string keys and arbitrary python
186 evaluations, a dict can be provided with string keys and arbitrary python
187 expressions as values. The return message will contain also a dict with the
187 expressions as values. The return message will contain also a dict with the
188 same keys and the :func:`repr()` of the evaluated expressions as value.
188 same keys and the :func:`repr()` of the evaluated expressions as value.
189
189
190 With this information, frontends can display any status information they wish
190 With this information, frontends can display any status information they wish
191 in the form that best suits each frontend (a status line, a popup, inline for a
191 in the form that best suits each frontend (a status line, a popup, inline for a
192 terminal, etc).
192 terminal, etc).
193
193
194 .. Note::
194 .. Note::
195
195
196 In order to obtain the current execution counter for the purposes of
196 In order to obtain the current execution counter for the purposes of
197 displaying input prompts, frontends simply make an execution request with an
197 displaying input prompts, frontends simply make an execution request with an
198 empty code string and ``silent=True``.
198 empty code string and ``silent=True``.
199
199
200 Execution semantics
200 Execution semantics
201 ~~~~~~~~~~~~~~~~~~~
201 ~~~~~~~~~~~~~~~~~~~
202
202
203 When the silent flag is false, the execution of use code consists of the
203 When the silent flag is false, the execution of use code consists of the
204 following phases (in silent mode, only the ``code`` field is executed):
204 following phases (in silent mode, only the ``code`` field is executed):
205
205
206 1. Run the ``pre_runcode_hook``.
206 1. Run the ``pre_runcode_hook``.
207
207
208 2. Execute the ``code`` field, see below for details.
208 2. Execute the ``code`` field, see below for details.
209
209
210 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
210 3. If #2 succeeds, compute ``user_variables`` and ``user_expressions`` are
211 computed. This ensures that any error in the latter don't harm the main
211 computed. This ensures that any error in the latter don't harm the main
212 code execution.
212 code execution.
213
213
214 4. Call any method registered with :meth:`register_post_execute`.
214 4. Call any method registered with :meth:`register_post_execute`.
215
215
216 .. warning::
216 .. warning::
217
217
218 The API for running code before/after the main code block is likely to
218 The API for running code before/after the main code block is likely to
219 change soon. Both the ``pre_runcode_hook`` and the
219 change soon. Both the ``pre_runcode_hook`` and the
220 :meth:`register_post_execute` are susceptible to modification, as we find a
220 :meth:`register_post_execute` are susceptible to modification, as we find a
221 consistent model for both.
221 consistent model for both.
222
222
223 To understand how the ``code`` field is executed, one must know that Python
223 To understand how the ``code`` field is executed, one must know that Python
224 code can be compiled in one of three modes (controlled by the ``mode`` argument
224 code can be compiled in one of three modes (controlled by the ``mode`` argument
225 to the :func:`compile` builtin):
225 to the :func:`compile` builtin):
226
226
227 *single*
227 *single*
228 Valid for a single interactive statement (though the source can contain
228 Valid for a single interactive statement (though the source can contain
229 multiple lines, such as a for loop). When compiled in this mode, the
229 multiple lines, such as a for loop). When compiled in this mode, the
230 generated bytecode contains special instructions that trigger the calling of
230 generated bytecode contains special instructions that trigger the calling of
231 :func:`sys.displayhook` for any expression in the block that returns a value.
231 :func:`sys.displayhook` for any expression in the block that returns a value.
232 This means that a single statement can actually produce multiple calls to
232 This means that a single statement can actually produce multiple calls to
233 :func:`sys.displayhook`, if for example it contains a loop where each
233 :func:`sys.displayhook`, if for example it contains a loop where each
234 iteration computes an unassigned expression would generate 10 calls::
234 iteration computes an unassigned expression would generate 10 calls::
235
235
236 for i in range(10):
236 for i in range(10):
237 i**2
237 i**2
238
238
239 *exec*
239 *exec*
240 An arbitrary amount of source code, this is how modules are compiled.
240 An arbitrary amount of source code, this is how modules are compiled.
241 :func:`sys.displayhook` is *never* implicitly called.
241 :func:`sys.displayhook` is *never* implicitly called.
242
242
243 *eval*
243 *eval*
244 A single expression that returns a value. :func:`sys.displayhook` is *never*
244 A single expression that returns a value. :func:`sys.displayhook` is *never*
245 implicitly called.
245 implicitly called.
246
246
247
247
248 The ``code`` field is split into individual blocks each of which is valid for
248 The ``code`` field is split into individual blocks each of which is valid for
249 execution in 'single' mode, and then:
249 execution in 'single' mode, and then:
250
250
251 - If there is only a single block: it is executed in 'single' mode.
251 - If there is only a single block: it is executed in 'single' mode.
252
252
253 - If there is more than one block:
253 - If there is more than one block:
254
254
255 * if the last one is a single line long, run all but the last in 'exec' mode
255 * if the last one is a single line long, run all but the last in 'exec' mode
256 and the very last one in 'single' mode. This makes it easy to type simple
256 and the very last one in 'single' mode. This makes it easy to type simple
257 expressions at the end to see computed values.
257 expressions at the end to see computed values.
258
258
259 * if the last one is no more than two lines long, run all but the last in
259 * if the last one is no more than two lines long, run all but the last in
260 'exec' mode and the very last one in 'single' mode. This makes it easy to
260 'exec' mode and the very last one in 'single' mode. This makes it easy to
261 type simple expressions at the end to see computed values. - otherwise
261 type simple expressions at the end to see computed values. - otherwise
262 (last one is also multiline), run all in 'exec' mode
262 (last one is also multiline), run all in 'exec' mode
263
263
264 * otherwise (last one is also multiline), run all in 'exec' mode as a single
264 * otherwise (last one is also multiline), run all in 'exec' mode as a single
265 unit.
265 unit.
266
266
267 Any error in retrieving the ``user_variables`` or evaluating the
267 Any error in retrieving the ``user_variables`` or evaluating the
268 ``user_expressions`` will result in a simple error message in the return fields
268 ``user_expressions`` will result in a simple error message in the return fields
269 of the form::
269 of the form::
270
270
271 [ERROR] ExceptionType: Exception message
271 [ERROR] ExceptionType: Exception message
272
272
273 The user can simply send the same variable name or expression for evaluation to
273 The user can simply send the same variable name or expression for evaluation to
274 see a regular traceback.
274 see a regular traceback.
275
275
276 Errors in any registered post_execute functions are also reported similarly,
276 Errors in any registered post_execute functions are also reported similarly,
277 and the failing function is removed from the post_execution set so that it does
277 and the failing function is removed from the post_execution set so that it does
278 not continue triggering failures.
278 not continue triggering failures.
279
279
280 Upon completion of the execution request, the kernel *always* sends a reply,
280 Upon completion of the execution request, the kernel *always* sends a reply,
281 with a status code indicating what happened and additional data depending on
281 with a status code indicating what happened and additional data depending on
282 the outcome. See :ref:`below <execution_results>` for the possible return
282 the outcome. See :ref:`below <execution_results>` for the possible return
283 codes and associated data.
283 codes and associated data.
284
284
285
285
286 Execution counter (old prompt number)
286 Execution counter (old prompt number)
287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
288
288
289 The kernel has a single, monotonically increasing counter of all execution
289 The kernel has a single, monotonically increasing counter of all execution
290 requests that are made with ``silent=False``. This counter is used to populate
290 requests that are made with ``silent=False``. This counter is used to populate
291 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
291 the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will likely want to
292 display it in some form to the user, which will typically (but not necessarily)
292 display it in some form to the user, which will typically (but not necessarily)
293 be done in the prompts. The value of this counter will be returned as the
293 be done in the prompts. The value of this counter will be returned as the
294 ``execution_count`` field of all ``execute_reply`` messages.
294 ``execution_count`` field of all ``execute_reply`` messages.
295
295
296 .. _execution_results:
296 .. _execution_results:
297
297
298 Execution results
298 Execution results
299 ~~~~~~~~~~~~~~~~~
299 ~~~~~~~~~~~~~~~~~
300
300
301 Message type: ``execute_reply``::
301 Message type: ``execute_reply``::
302
302
303 content = {
303 content = {
304 # One of: 'ok' OR 'error' OR 'abort'
304 # One of: 'ok' OR 'error' OR 'abort'
305 'status' : str,
305 'status' : str,
306
306
307 # The global kernel counter that increases by one with each non-silent
307 # The global kernel counter that increases by one with each non-silent
308 # executed request. This will typically be used by clients to display
308 # executed request. This will typically be used by clients to display
309 # prompt numbers to the user. If the request was a silent one, this will
309 # prompt numbers to the user. If the request was a silent one, this will
310 # be the current value of the counter in the kernel.
310 # be the current value of the counter in the kernel.
311 'execution_count' : int,
311 'execution_count' : int,
312 }
312 }
313
313
314 When status is 'ok', the following extra fields are present::
314 When status is 'ok', the following extra fields are present::
315
315
316 {
316 {
317 # The execution payload is a dict with string keys that may have been
317 # The execution payload is a dict with string keys that may have been
318 # produced by the code being executed. It is retrieved by the kernel at
318 # produced by the code being executed. It is retrieved by the kernel at
319 # the end of the execution and sent back to the front end, which can take
319 # the end of the execution and sent back to the front end, which can take
320 # action on it as needed. See main text for further details.
320 # action on it as needed. See main text for further details.
321 'payload' : dict,
321 'payload' : dict,
322
322
323 # Results for the user_variables and user_expressions.
323 # Results for the user_variables and user_expressions.
324 'user_variables' : dict,
324 'user_variables' : dict,
325 'user_expressions' : dict,
325 'user_expressions' : dict,
326
326
327 # The kernel will often transform the input provided to it. If the
327 # The kernel will often transform the input provided to it. If the
328 # '---->' transform had been applied, this is filled, otherwise it's the
328 # '---->' transform had been applied, this is filled, otherwise it's the
329 # empty string. So transformations like magics don't appear here, only
329 # empty string. So transformations like magics don't appear here, only
330 # autocall ones.
330 # autocall ones.
331 'transformed_code' : str,
331 'transformed_code' : str,
332 }
332 }
333
333
334 .. admonition:: Execution payloads
334 .. admonition:: Execution payloads
335
335
336 The notion of an 'execution payload' is different from a return value of a
336 The notion of an 'execution payload' is different from a return value of a
337 given set of code, which normally is just displayed on the pyout stream
337 given set of code, which normally is just displayed on the pyout stream
338 through the PUB socket. The idea of a payload is to allow special types of
338 through the PUB socket. The idea of a payload is to allow special types of
339 code, typically magics, to populate a data container in the IPython kernel
339 code, typically magics, to populate a data container in the IPython kernel
340 that will be shipped back to the caller via this channel. The kernel will
340 that will be shipped back to the caller via this channel. The kernel will
341 have an API for this, probably something along the lines of::
341 have an API for this, probably something along the lines of::
342
342
343 ip.exec_payload_add(key, value)
343 ip.exec_payload_add(key, value)
344
344
345 though this API is still in the design stages. The data returned in this
345 though this API is still in the design stages. The data returned in this
346 payload will allow frontends to present special views of what just happened.
346 payload will allow frontends to present special views of what just happened.
347
347
348
348
349 When status is 'error', the following extra fields are present::
349 When status is 'error', the following extra fields are present::
350
350
351 {
351 {
352 'exc_name' : str, # Exception name, as a string
352 'exc_name' : str, # Exception name, as a string
353 'exc_value' : str, # Exception value, as a string
353 'exc_value' : str, # Exception value, as a string
354
354
355 # The traceback will contain a list of frames, represented each as a
355 # The traceback will contain a list of frames, represented each as a
356 # string. For now we'll stick to the existing design of ultraTB, which
356 # string. For now we'll stick to the existing design of ultraTB, which
357 # controls exception level of detail statefully. But eventually we'll
357 # controls exception level of detail statefully. But eventually we'll
358 # want to grow into a model where more information is collected and
358 # want to grow into a model where more information is collected and
359 # packed into the traceback object, with clients deciding how little or
359 # packed into the traceback object, with clients deciding how little or
360 # how much of it to unpack. But for now, let's start with a simple list
360 # how much of it to unpack. But for now, let's start with a simple list
361 # of strings, since that requires only minimal changes to ultratb as
361 # of strings, since that requires only minimal changes to ultratb as
362 # written.
362 # written.
363 'traceback' : list,
363 'traceback' : list,
364 }
364 }
365
365
366
366
367 When status is 'abort', there are for now no additional data fields. This
367 When status is 'abort', there are for now no additional data fields. This
368 happens when the kernel was interrupted by a signal.
368 happens when the kernel was interrupted by a signal.
369
369
370 Kernel attribute access
370 Kernel attribute access
371 -----------------------
371 -----------------------
372
372
373 .. warning::
373 .. warning::
374
374
375 This part of the messaging spec is not actually implemented in the kernel
375 This part of the messaging spec is not actually implemented in the kernel
376 yet.
376 yet.
377
377
378 While this protocol does not specify full RPC access to arbitrary methods of
378 While this protocol does not specify full RPC access to arbitrary methods of
379 the kernel object, the kernel does allow read (and in some cases write) access
379 the kernel object, the kernel does allow read (and in some cases write) access
380 to certain attributes.
380 to certain attributes.
381
381
382 The policy for which attributes can be read is: any attribute of the kernel, or
382 The policy for which attributes can be read is: any attribute of the kernel, or
383 its sub-objects, that belongs to a :class:`Configurable` object and has been
383 its sub-objects, that belongs to a :class:`Configurable` object and has been
384 declared at the class-level with Traits validation, is in principle accessible
384 declared at the class-level with Traits validation, is in principle accessible
385 as long as its name does not begin with a leading underscore. The attribute
385 as long as its name does not begin with a leading underscore. The attribute
386 itself will have metadata indicating whether it allows remote read and/or write
386 itself will have metadata indicating whether it allows remote read and/or write
387 access. The message spec follows for attribute read and write requests.
387 access. The message spec follows for attribute read and write requests.
388
388
389 Message type: ``getattr_request``::
389 Message type: ``getattr_request``::
390
390
391 content = {
391 content = {
392 # The (possibly dotted) name of the attribute
392 # The (possibly dotted) name of the attribute
393 'name' : str,
393 'name' : str,
394 }
394 }
395
395
396 When a ``getattr_request`` fails, there are two possible error types:
396 When a ``getattr_request`` fails, there are two possible error types:
397
397
398 - AttributeError: this type of error was raised when trying to access the
398 - AttributeError: this type of error was raised when trying to access the
399 given name by the kernel itself. This means that the attribute likely
399 given name by the kernel itself. This means that the attribute likely
400 doesn't exist.
400 doesn't exist.
401
401
402 - AccessError: the attribute exists but its value is not readable remotely.
402 - AccessError: the attribute exists but its value is not readable remotely.
403
403
404
404
405 Message type: ``getattr_reply``::
405 Message type: ``getattr_reply``::
406
406
407 content = {
407 content = {
408 # One of ['ok', 'AttributeError', 'AccessError'].
408 # One of ['ok', 'AttributeError', 'AccessError'].
409 'status' : str,
409 'status' : str,
410 # If status is 'ok', a JSON object.
410 # If status is 'ok', a JSON object.
411 'value' : object,
411 'value' : object,
412 }
412 }
413
413
414 Message type: ``setattr_request``::
414 Message type: ``setattr_request``::
415
415
416 content = {
416 content = {
417 # The (possibly dotted) name of the attribute
417 # The (possibly dotted) name of the attribute
418 'name' : str,
418 'name' : str,
419
419
420 # A JSON-encoded object, that will be validated by the Traits
420 # A JSON-encoded object, that will be validated by the Traits
421 # information in the kernel
421 # information in the kernel
422 'value' : object,
422 'value' : object,
423 }
423 }
424
424
425 When a ``setattr_request`` fails, there are also two possible error types with
425 When a ``setattr_request`` fails, there are also two possible error types with
426 similar meanings as those of the ``getattr_request`` case, but for writing.
426 similar meanings as those of the ``getattr_request`` case, but for writing.
427
427
428 Message type: ``setattr_reply``::
428 Message type: ``setattr_reply``::
429
429
430 content = {
430 content = {
431 # One of ['ok', 'AttributeError', 'AccessError'].
431 # One of ['ok', 'AttributeError', 'AccessError'].
432 'status' : str,
432 'status' : str,
433 }
433 }
434
434
435
435
436
436
437 Object information
437 Object information
438 ------------------
438 ------------------
439
439
440 One of IPython's most used capabilities is the introspection of Python objects
440 One of IPython's most used capabilities is the introspection of Python objects
441 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
441 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
442 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
442 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
443 enough that it warrants an explicit message type, especially because frontends
443 enough that it warrants an explicit message type, especially because frontends
444 may want to get object information in response to user keystrokes (like Tab or
444 may want to get object information in response to user keystrokes (like Tab or
445 F1) besides from the user explicitly typing code like ``x??``.
445 F1) besides from the user explicitly typing code like ``x??``.
446
446
447 Message type: ``object_info_request``::
447 Message type: ``object_info_request``::
448
448
449 content = {
449 content = {
450 # The (possibly dotted) name of the object to be searched in all
450 # The (possibly dotted) name of the object to be searched in all
451 # relevant namespaces
451 # relevant namespaces
452 'name' : str,
452 'name' : str,
453
453
454 # The level of detail desired. The default (0) is equivalent to typing
454 # The level of detail desired. The default (0) is equivalent to typing
455 # 'x?' at the prompt, 1 is equivalent to 'x??'.
455 # 'x?' at the prompt, 1 is equivalent to 'x??'.
456 'detail_level' : int,
456 'detail_level' : int,
457 }
457 }
458
458
459 The returned information will be a dictionary with keys very similar to the
459 The returned information will be a dictionary with keys very similar to the
460 field names that IPython prints at the terminal.
460 field names that IPython prints at the terminal.
461
461
462 Message type: ``object_info_reply``::
462 Message type: ``object_info_reply``::
463
463
464 content = {
464 content = {
465 # The name the object was requested under
466 'name' : str,
467
465 # Boolean flag indicating whether the named object was found or not. If
468 # Boolean flag indicating whether the named object was found or not. If
466 # it's false, all other fields will be empty.
469 # it's false, all other fields will be empty.
467 'found' : bool,
470 'found' : bool,
468
471
469 # Flags for magics and system aliases
472 # Flags for magics and system aliases
470 'ismagic' : bool,
473 'ismagic' : bool,
471 'isalias' : bool,
474 'isalias' : bool,
472
475
473 # The name of the namespace where the object was found ('builtin',
476 # The name of the namespace where the object was found ('builtin',
474 # 'magics', 'alias', 'interactive', etc.)
477 # 'magics', 'alias', 'interactive', etc.)
475 'namespace' : str,
478 'namespace' : str,
476
479
477 # The type name will be type.__name__ for normal Python objects, but it
480 # The type name will be type.__name__ for normal Python objects, but it
478 # can also be a string like 'Magic function' or 'System alias'
481 # can also be a string like 'Magic function' or 'System alias'
479 'type_name' : str,
482 'type_name' : str,
480
483
481 'string_form' : str,
484 'string_form' : str,
482
485
483 # For objects with a __class__ attribute this will be set
486 # For objects with a __class__ attribute this will be set
484 'base_class' : str,
487 'base_class' : str,
485
488
486 # For objects with a __len__ attribute this will be set
489 # For objects with a __len__ attribute this will be set
487 'length' : int,
490 'length' : int,
488
491
489 # If the object is a function, class or method whose file we can find,
492 # If the object is a function, class or method whose file we can find,
490 # we give its full path
493 # we give its full path
491 'file' : str,
494 'file' : str,
492
495
493 # For pure Python callable objects, we can reconstruct the object
496 # For pure Python callable objects, we can reconstruct the object
494 # definition line which provides its call signature. For convenience this
497 # definition line which provides its call signature. For convenience this
495 # is returned as a single 'definition' field, but below the raw parts that
498 # is returned as a single 'definition' field, but below the raw parts that
496 # compose it are also returned as the argspec field.
499 # compose it are also returned as the argspec field.
497 'definition' : str,
500 'definition' : str,
498
501
499 # The individual parts that together form the definition string. Clients
502 # The individual parts that together form the definition string. Clients
500 # with rich display capabilities may use this to provide a richer and more
503 # with rich display capabilities may use this to provide a richer and more
501 # precise representation of the definition line (e.g. by highlighting
504 # precise representation of the definition line (e.g. by highlighting
502 # arguments based on the user's cursor position). For non-callable
505 # arguments based on the user's cursor position). For non-callable
503 # objects, this field is empty.
506 # objects, this field is empty.
504 'argspec' : { # The names of all the arguments
507 'argspec' : { # The names of all the arguments
505 args : list,
508 args : list,
506 # The name of the varargs (*args), if any
509 # The name of the varargs (*args), if any
507 varargs : str,
510 varargs : str,
508 # The name of the varkw (**kw), if any
511 # The name of the varkw (**kw), if any
509 varkw : str,
512 varkw : str,
510 # The values (as strings) of all default arguments. Note
513 # The values (as strings) of all default arguments. Note
511 # that these must be matched *in reverse* with the 'args'
514 # that these must be matched *in reverse* with the 'args'
512 # list above, since the first positional args have no default
515 # list above, since the first positional args have no default
513 # value at all.
516 # value at all.
514 func_defaults : list,
517 defaults : list,
515 },
518 },
516
519
517 # For instances, provide the constructor signature (the definition of
520 # For instances, provide the constructor signature (the definition of
518 # the __init__ method):
521 # the __init__ method):
519 'init_definition' : str,
522 'init_definition' : str,
520
523
521 # Docstrings: for any object (function, method, module, package) with a
524 # Docstrings: for any object (function, method, module, package) with a
522 # docstring, we show it. But in addition, we may provide additional
525 # docstring, we show it. But in addition, we may provide additional
523 # docstrings. For example, for instances we will show the constructor
526 # docstrings. For example, for instances we will show the constructor
524 # and class docstrings as well, if available.
527 # and class docstrings as well, if available.
525 'docstring' : str,
528 'docstring' : str,
526
529
527 # For instances, provide the constructor and class docstrings
530 # For instances, provide the constructor and class docstrings
528 'init_docstring' : str,
531 'init_docstring' : str,
529 'class_docstring' : str,
532 'class_docstring' : str,
530
533
531 # If it's a callable object whose call method has a separate docstring and
534 # If it's a callable object whose call method has a separate docstring and
532 # definition line:
535 # definition line:
533 'call_def' : str,
536 'call_def' : str,
534 'call_docstring' : str,
537 'call_docstring' : str,
535
538
536 # If detail_level was 1, we also try to find the source code that
539 # If detail_level was 1, we also try to find the source code that
537 # defines the object, if possible. The string 'None' will indicate
540 # defines the object, if possible. The string 'None' will indicate
538 # that no source was found.
541 # that no source was found.
539 'source' : str,
542 'source' : str,
540 }
543 }
541 '
544 '
542
545
543 Complete
546 Complete
544 --------
547 --------
545
548
546 Message type: ``complete_request``::
549 Message type: ``complete_request``::
547
550
548 content = {
551 content = {
549 # The text to be completed, such as 'a.is'
552 # The text to be completed, such as 'a.is'
550 'text' : str,
553 'text' : str,
551
554
552 # The full line, such as 'print a.is'. This allows completers to
555 # The full line, such as 'print a.is'. This allows completers to
553 # make decisions that may require information about more than just the
556 # make decisions that may require information about more than just the
554 # current word.
557 # current word.
555 'line' : str,
558 'line' : str,
556
559
557 # The entire block of text where the line is. This may be useful in the
560 # The entire block of text where the line is. This may be useful in the
558 # case of multiline completions where more context may be needed. Note: if
561 # case of multiline completions where more context may be needed. Note: if
559 # in practice this field proves unnecessary, remove it to lighten the
562 # in practice this field proves unnecessary, remove it to lighten the
560 # messages.
563 # messages.
561
564
562 'block' : str,
565 'block' : str,
563
566
564 # The position of the cursor where the user hit 'TAB' on the line.
567 # The position of the cursor where the user hit 'TAB' on the line.
565 'cursor_pos' : int,
568 'cursor_pos' : int,
566 }
569 }
567
570
568 Message type: ``complete_reply``::
571 Message type: ``complete_reply``::
569
572
570 content = {
573 content = {
571 # The list of all matches to the completion request, such as
574 # The list of all matches to the completion request, such as
572 # ['a.isalnum', 'a.isalpha'] for the above example.
575 # ['a.isalnum', 'a.isalpha'] for the above example.
573 'matches' : list
576 'matches' : list
574 }
577 }
575
578
576
579
577 History
580 History
578 -------
581 -------
579
582
580 For clients to explicitly request history from a kernel. The kernel has all
583 For clients to explicitly request history from a kernel. The kernel has all
581 the actual execution history stored in a single location, so clients can
584 the actual execution history stored in a single location, so clients can
582 request it from the kernel when needed.
585 request it from the kernel when needed.
583
586
584 Message type: ``history_request``::
587 Message type: ``history_request``::
585
588
586 content = {
589 content = {
587
590
588 # If True, also return output history in the resulting dict.
591 # If True, also return output history in the resulting dict.
589 'output' : bool,
592 'output' : bool,
590
593
591 # If True, return the raw input history, else the transformed input.
594 # If True, return the raw input history, else the transformed input.
592 'raw' : bool,
595 'raw' : bool,
593
596
594 # This parameter can be one of: A number, a pair of numbers, None
597 # This parameter can be one of: A number, a pair of numbers, None
595 # If not given, last 40 are returned.
598 # If not given, last 40 are returned.
596 # - number n: return the last n entries.
599 # - number n: return the last n entries.
597 # - pair n1, n2: return entries in the range(n1, n2).
600 # - pair n1, n2: return entries in the range(n1, n2).
598 # - None: return all history
601 # - None: return all history
599 'index' : n or (n1, n2) or None,
602 'index' : n or (n1, n2) or None,
600 }
603 }
601
604
602 Message type: ``history_reply``::
605 Message type: ``history_reply``::
603
606
604 content = {
607 content = {
605 # A dict with prompt numbers as keys and either (input, output) or input
608 # A dict with prompt numbers as keys and either (input, output) or input
606 # as the value depending on whether output was True or False,
609 # as the value depending on whether output was True or False,
607 # respectively.
610 # respectively.
608 'history' : dict,
611 'history' : dict,
609 }
612 }
610
613
611
614
612 Connect
615 Connect
613 -------
616 -------
614
617
615 When a client connects to the request/reply socket of the kernel, it can issue
618 When a client connects to the request/reply socket of the kernel, it can issue
616 a connect request to get basic information about the kernel, such as the ports
619 a connect request to get basic information about the kernel, such as the ports
617 the other ZeroMQ sockets are listening on. This allows clients to only have
620 the other ZeroMQ sockets are listening on. This allows clients to only have
618 to know about a single port (the XREQ/XREP channel) to connect to a kernel.
621 to know about a single port (the XREQ/XREP channel) to connect to a kernel.
619
622
620 Message type: ``connect_request``::
623 Message type: ``connect_request``::
621
624
622 content = {
625 content = {
623 }
626 }
624
627
625 Message type: ``connect_reply``::
628 Message type: ``connect_reply``::
626
629
627 content = {
630 content = {
628 'xrep_port' : int # The port the XREP socket is listening on.
631 'xrep_port' : int # The port the XREP socket is listening on.
629 'pub_port' : int # The port the PUB socket is listening on.
632 'pub_port' : int # The port the PUB socket is listening on.
630 'req_port' : int # The port the REQ socket is listening on.
633 'req_port' : int # The port the REQ socket is listening on.
631 'hb_port' : int # The port the heartbeat socket is listening on.
634 'hb_port' : int # The port the heartbeat socket is listening on.
632 }
635 }
633
636
634
637
635
638
636 Kernel shutdown
639 Kernel shutdown
637 ---------------
640 ---------------
638
641
639 The clients can request the kernel to shut itself down; this is used in
642 The clients can request the kernel to shut itself down; this is used in
640 multiple cases:
643 multiple cases:
641
644
642 - when the user chooses to close the client application via a menu or window
645 - when the user chooses to close the client application via a menu or window
643 control.
646 control.
644 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
647 - when the user types 'exit' or 'quit' (or their uppercase magic equivalents).
645 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
648 - when the user chooses a GUI method (like the 'Ctrl-C' shortcut in the
646 IPythonQt client) to force a kernel restart to get a clean kernel without
649 IPythonQt client) to force a kernel restart to get a clean kernel without
647 losing client-side state like history or inlined figures.
650 losing client-side state like history or inlined figures.
648
651
649 The client sends a shutdown request to the kernel, and once it receives the
652 The client sends a shutdown request to the kernel, and once it receives the
650 reply message (which is otherwise empty), it can assume that the kernel has
653 reply message (which is otherwise empty), it can assume that the kernel has
651 completed shutdown safely.
654 completed shutdown safely.
652
655
653 Upon their own shutdown, client applications will typically execute a last
656 Upon their own shutdown, client applications will typically execute a last
654 minute sanity check and forcefully terminate any kernel that is still alive, to
657 minute sanity check and forcefully terminate any kernel that is still alive, to
655 avoid leaving stray processes in the user's machine.
658 avoid leaving stray processes in the user's machine.
656
659
657 For both shutdown request and reply, there is no actual content that needs to
660 For both shutdown request and reply, there is no actual content that needs to
658 be sent, so the content dict is empty.
661 be sent, so the content dict is empty.
659
662
660 Message type: ``shutdown_request``::
663 Message type: ``shutdown_request``::
661
664
662 content = {
665 content = {
663 }
666 }
664
667
665 Message type: ``shutdown_reply``::
668 Message type: ``shutdown_reply``::
666
669
667 content = {
670 content = {
668 }
671 }
669
672
670 .. Note::
673 .. Note::
671
674
672 When the clients detect a dead kernel thanks to inactivity on the heartbeat
675 When the clients detect a dead kernel thanks to inactivity on the heartbeat
673 socket, they simply send a forceful process termination signal, since a dead
676 socket, they simply send a forceful process termination signal, since a dead
674 process is unlikely to respond in any useful way to messages.
677 process is unlikely to respond in any useful way to messages.
675
678
676
679
677 Messages on the PUB/SUB socket
680 Messages on the PUB/SUB socket
678 ==============================
681 ==============================
679
682
680 Streams (stdout, stderr, etc)
683 Streams (stdout, stderr, etc)
681 ------------------------------
684 ------------------------------
682
685
683 Message type: ``stream``::
686 Message type: ``stream``::
684
687
685 content = {
688 content = {
686 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
689 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
687 'name' : str,
690 'name' : str,
688
691
689 # The data is an arbitrary string to be written to that stream
692 # The data is an arbitrary string to be written to that stream
690 'data' : str,
693 'data' : str,
691 }
694 }
692
695
693 When a kernel receives a raw_input call, it should also broadcast it on the pub
696 When a kernel receives a raw_input call, it should also broadcast it on the pub
694 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
697 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
695 to monitor/display kernel interactions and possibly replay them to their user
698 to monitor/display kernel interactions and possibly replay them to their user
696 or otherwise expose them.
699 or otherwise expose them.
697
700
698 Python inputs
701 Python inputs
699 -------------
702 -------------
700
703
701 These messages are the re-broadcast of the ``execute_request``.
704 These messages are the re-broadcast of the ``execute_request``.
702
705
703 Message type: ``pyin``::
706 Message type: ``pyin``::
704
707
705 content = {
708 content = {
706 # Source code to be executed, one or more lines
709 # Source code to be executed, one or more lines
707 'code' : str
710 'code' : str
708 }
711 }
709
712
710 Python outputs
713 Python outputs
711 --------------
714 --------------
712
715
713 When Python produces output from code that has been compiled in with the
716 When Python produces output from code that has been compiled in with the
714 'single' flag to :func:`compile`, any expression that produces a value (such as
717 'single' flag to :func:`compile`, any expression that produces a value (such as
715 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
718 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
716 this value whatever it wants. The default behavior of ``sys.displayhook`` in
719 this value whatever it wants. The default behavior of ``sys.displayhook`` in
717 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
720 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
718 the value as long as it is not ``None`` (which isn't printed at all). In our
721 the value as long as it is not ``None`` (which isn't printed at all). In our
719 case, the kernel instantiates as ``sys.displayhook`` an object which has
722 case, the kernel instantiates as ``sys.displayhook`` an object which has
720 similar behavior, but which instead of printing to stdout, broadcasts these
723 similar behavior, but which instead of printing to stdout, broadcasts these
721 values as ``pyout`` messages for clients to display appropriately.
724 values as ``pyout`` messages for clients to display appropriately.
722
725
723 Message type: ``pyout``::
726 Message type: ``pyout``::
724
727
725 content = {
728 content = {
726 # The data is typically the repr() of the object.
729 # The data is typically the repr() of the object.
727 'data' : str,
730 'data' : str,
728
731
729 # The counter for this execution is also provided so that clients can
732 # The counter for this execution is also provided so that clients can
730 # display it, since IPython automatically creates variables called _N (for
733 # display it, since IPython automatically creates variables called _N (for
731 # prompt N).
734 # prompt N).
732 'execution_count' : int,
735 'execution_count' : int,
733 }
736 }
734
737
735 Python errors
738 Python errors
736 -------------
739 -------------
737
740
738 When an error occurs during code execution
741 When an error occurs during code execution
739
742
740 Message type: ``pyerr``::
743 Message type: ``pyerr``::
741
744
742 content = {
745 content = {
743 # Similar content to the execute_reply messages for the 'error' case,
746 # Similar content to the execute_reply messages for the 'error' case,
744 # except the 'status' field is omitted.
747 # except the 'status' field is omitted.
745 }
748 }
746
749
747 Kernel status
750 Kernel status
748 -------------
751 -------------
749
752
750 This message type is used by frontends to monitor the status of the kernel.
753 This message type is used by frontends to monitor the status of the kernel.
751
754
752 Message type: ``status``::
755 Message type: ``status``::
753
756
754 content = {
757 content = {
755 # When the kernel starts to execute code, it will enter the 'busy'
758 # When the kernel starts to execute code, it will enter the 'busy'
756 # state and when it finishes, it will enter the 'idle' state.
759 # state and when it finishes, it will enter the 'idle' state.
757 execution_state : ('busy', 'idle')
760 execution_state : ('busy', 'idle')
758 }
761 }
759
762
760 Kernel crashes
763 Kernel crashes
761 --------------
764 --------------
762
765
763 When the kernel has an unexpected exception, caught by the last-resort
766 When the kernel has an unexpected exception, caught by the last-resort
764 sys.excepthook, we should broadcast the crash handler's output before exiting.
767 sys.excepthook, we should broadcast the crash handler's output before exiting.
765 This will allow clients to notice that a kernel died, inform the user and
768 This will allow clients to notice that a kernel died, inform the user and
766 propose further actions.
769 propose further actions.
767
770
768 Message type: ``crash``::
771 Message type: ``crash``::
769
772
770 content = {
773 content = {
771 # Similarly to the 'error' case for execute_reply messages, this will
774 # Similarly to the 'error' case for execute_reply messages, this will
772 # contain exc_name, exc_type and traceback fields.
775 # contain exc_name, exc_type and traceback fields.
773
776
774 # An additional field with supplementary information such as where to
777 # An additional field with supplementary information such as where to
775 # send the crash message
778 # send the crash message
776 'info' : str,
779 'info' : str,
777 }
780 }
778
781
779
782
780 Future ideas
783 Future ideas
781 ------------
784 ------------
782
785
783 Other potential message types, currently unimplemented, listed below as ideas.
786 Other potential message types, currently unimplemented, listed below as ideas.
784
787
785 Message type: ``file``::
788 Message type: ``file``::
786
789
787 content = {
790 content = {
788 'path' : 'cool.jpg',
791 'path' : 'cool.jpg',
789 'mimetype' : str,
792 'mimetype' : str,
790 'data' : str,
793 'data' : str,
791 }
794 }
792
795
793
796
794 Messages on the REQ/REP socket
797 Messages on the REQ/REP socket
795 ==============================
798 ==============================
796
799
797 This is a socket that goes in the opposite direction: from the kernel to a
800 This is a socket that goes in the opposite direction: from the kernel to a
798 *single* frontend, and its purpose is to allow ``raw_input`` and similar
801 *single* frontend, and its purpose is to allow ``raw_input`` and similar
799 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
802 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
800 client. For now we will keep these messages as simple as possible, since they
803 client. For now we will keep these messages as simple as possible, since they
801 basically only mean to convey the ``raw_input(prompt)`` call.
804 basically only mean to convey the ``raw_input(prompt)`` call.
802
805
803 Message type: ``input_request``::
806 Message type: ``input_request``::
804
807
805 content = { 'prompt' : str }
808 content = { 'prompt' : str }
806
809
807 Message type: ``input_reply``::
810 Message type: ``input_reply``::
808
811
809 content = { 'value' : str }
812 content = { 'value' : str }
810
813
811 .. Note::
814 .. Note::
812
815
813 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
816 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
814 practice the kernel should behave like an interactive program. When a
817 practice the kernel should behave like an interactive program. When a
815 program is opened on the console, the keyboard effectively takes over the
818 program is opened on the console, the keyboard effectively takes over the
816 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
819 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
817 Since the IPython kernel effectively behaves like a console program (albeit
820 Since the IPython kernel effectively behaves like a console program (albeit
818 one whose "keyboard" is actually living in a separate process and
821 one whose "keyboard" is actually living in a separate process and
819 transported over the zmq connection), raw ``stdin`` isn't expected to be
822 transported over the zmq connection), raw ``stdin`` isn't expected to be
820 available.
823 available.
821
824
822
825
823 Heartbeat for kernels
826 Heartbeat for kernels
824 =====================
827 =====================
825
828
826 Initially we had considered using messages like those above over ZMQ for a
829 Initially we had considered using messages like those above over ZMQ for a
827 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
830 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
828 alive at all, even if it may be busy executing user code). But this has the
831 alive at all, even if it may be busy executing user code). But this has the
829 problem that if the kernel is locked inside extension code, it wouldn't execute
832 problem that if the kernel is locked inside extension code, it wouldn't execute
830 the python heartbeat code. But it turns out that we can implement a basic
833 the python heartbeat code. But it turns out that we can implement a basic
831 heartbeat with pure ZMQ, without using any Python messaging at all.
834 heartbeat with pure ZMQ, without using any Python messaging at all.
832
835
833 The monitor sends out a single zmq message (right now, it is a str of the
836 The monitor sends out a single zmq message (right now, it is a str of the
834 monitor's lifetime in seconds), and gets the same message right back, prefixed
837 monitor's lifetime in seconds), and gets the same message right back, prefixed
835 with the zmq identity of the XREQ socket in the heartbeat process. This can be
838 with the zmq identity of the XREQ socket in the heartbeat process. This can be
836 a uuid, or even a full message, but there doesn't seem to be a need for packing
839 a uuid, or even a full message, but there doesn't seem to be a need for packing
837 up a message when the sender and receiver are the exact same Python object.
840 up a message when the sender and receiver are the exact same Python object.
838
841
839 The model is this::
842 The model is this::
840
843
841 monitor.send(str(self.lifetime)) # '1.2345678910'
844 monitor.send(str(self.lifetime)) # '1.2345678910'
842
845
843 and the monitor receives some number of messages of the form::
846 and the monitor receives some number of messages of the form::
844
847
845 ['uuid-abcd-dead-beef', '1.2345678910']
848 ['uuid-abcd-dead-beef', '1.2345678910']
846
849
847 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
850 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
848 the rest is the message sent by the monitor. No Python code ever has any
851 the rest is the message sent by the monitor. No Python code ever has any
849 access to the message between the monitor's send, and the monitor's recv.
852 access to the message between the monitor's send, and the monitor's recv.
850
853
851
854
852 ToDo
855 ToDo
853 ====
856 ====
854
857
855 Missing things include:
858 Missing things include:
856
859
857 * Important: finish thinking through the payload concept and API.
860 * Important: finish thinking through the payload concept and API.
858
861
859 * Important: ensure that we have a good solution for magics like %edit. It's
862 * Important: ensure that we have a good solution for magics like %edit. It's
860 likely that with the payload concept we can build a full solution, but not
863 likely that with the payload concept we can build a full solution, but not
861 100% clear yet.
864 100% clear yet.
862
865
863 * Finishing the details of the heartbeat protocol.
866 * Finishing the details of the heartbeat protocol.
864
867
865 * Signal handling: specify what kind of information kernel should broadcast (or
868 * Signal handling: specify what kind of information kernel should broadcast (or
866 not) when it receives signals.
869 not) when it receives signals.
867
870
868 .. include:: ../links.rst
871 .. include:: ../links.rst
General Comments 0
You need to be logged in to leave comments. Login now