##// END OF EJS Templates
Implement object info protocol....
Fernando Perez -
Show More
@@ -1,2336 +1,2340 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 codeop
23 import codeop
24 import exceptions
24 import exceptions
25 import new
25 import new
26 import os
26 import os
27 import re
27 import re
28 import string
28 import string
29 import sys
29 import sys
30 import tempfile
30 import tempfile
31 from contextlib import nested
31 from contextlib import nested
32
32
33 from IPython.config.configurable import Configurable
33 from IPython.config.configurable import Configurable
34 from IPython.core import debugger, oinspect
34 from IPython.core import debugger, oinspect
35 from IPython.core import history as ipcorehist
35 from IPython.core import history as ipcorehist
36 from IPython.core import page
36 from IPython.core import page
37 from IPython.core import prefilter
37 from IPython.core import prefilter
38 from IPython.core import shadowns
38 from IPython.core import shadowns
39 from IPython.core import ultratb
39 from IPython.core import ultratb
40 from IPython.core.alias import AliasManager
40 from IPython.core.alias import AliasManager
41 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.builtin_trap import BuiltinTrap
42 from IPython.core.display_trap import DisplayTrap
42 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.displayhook import DisplayHook
43 from IPython.core.displayhook import DisplayHook
44 from IPython.core.error import TryNext, UsageError
44 from IPython.core.error import TryNext, UsageError
45 from IPython.core.extensions import ExtensionManager
45 from IPython.core.extensions import ExtensionManager
46 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
46 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
47 from IPython.core.inputlist import InputList
47 from IPython.core.inputlist import InputList
48 from IPython.core.logger import Logger
48 from IPython.core.logger import Logger
49 from IPython.core.magic import Magic
49 from IPython.core.magic import Magic
50 from IPython.core.payload import PayloadManager
50 from IPython.core.payload import PayloadManager
51 from IPython.core.plugin import PluginManager
51 from IPython.core.plugin import PluginManager
52 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
52 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
53 from IPython.external.Itpl import ItplNS
53 from IPython.external.Itpl import ItplNS
54 from IPython.utils import PyColorize
54 from IPython.utils import PyColorize
55 from IPython.utils import io
55 from IPython.utils import io
56 from IPython.utils import pickleshare
56 from IPython.utils import pickleshare
57 from IPython.utils.doctestreload import doctest_reload
57 from IPython.utils.doctestreload import doctest_reload
58 from IPython.utils.io import ask_yes_no, rprint
58 from IPython.utils.io import ask_yes_no, rprint
59 from IPython.utils.ipstruct import Struct
59 from IPython.utils.ipstruct import Struct
60 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
60 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
61 from IPython.utils.process import system, getoutput
61 from IPython.utils.process import system, getoutput
62 from IPython.utils.strdispatch import StrDispatch
62 from IPython.utils.strdispatch import StrDispatch
63 from IPython.utils.syspathcontext import prepended_to_syspath
63 from IPython.utils.syspathcontext import prepended_to_syspath
64 from IPython.utils.text import num_ini_spaces, format_screen
64 from IPython.utils.text import num_ini_spaces, format_screen
65 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
65 from IPython.utils.traitlets import (Int, Str, CBool, CaselessStrEnum, Enum,
66 List, Unicode, Instance, Type)
66 List, Unicode, Instance, Type)
67 from IPython.utils.warn import warn, error, fatal
67 from IPython.utils.warn import warn, error, fatal
68 import IPython.core.hooks
68 import IPython.core.hooks
69
69
70 # from IPython.utils import growl
70 # from IPython.utils import growl
71 # growl.start("IPython")
71 # growl.start("IPython")
72
72
73 #-----------------------------------------------------------------------------
73 #-----------------------------------------------------------------------------
74 # Globals
74 # Globals
75 #-----------------------------------------------------------------------------
75 #-----------------------------------------------------------------------------
76
76
77 # compiled regexps for autoindent management
77 # compiled regexps for autoindent management
78 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
78 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
79
79
80 #-----------------------------------------------------------------------------
80 #-----------------------------------------------------------------------------
81 # Utilities
81 # Utilities
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83
83
84 # store the builtin raw_input globally, and use this always, in case user code
84 # store the builtin raw_input globally, and use this always, in case user code
85 # overwrites it (like wx.py.PyShell does)
85 # overwrites it (like wx.py.PyShell does)
86 raw_input_original = raw_input
86 raw_input_original = raw_input
87
87
88 def softspace(file, newvalue):
88 def softspace(file, newvalue):
89 """Copied from code.py, to remove the dependency"""
89 """Copied from code.py, to remove the dependency"""
90
90
91 oldvalue = 0
91 oldvalue = 0
92 try:
92 try:
93 oldvalue = file.softspace
93 oldvalue = file.softspace
94 except AttributeError:
94 except AttributeError:
95 pass
95 pass
96 try:
96 try:
97 file.softspace = newvalue
97 file.softspace = newvalue
98 except (AttributeError, TypeError):
98 except (AttributeError, TypeError):
99 # "attribute-less object" or "read-only attributes"
99 # "attribute-less object" or "read-only attributes"
100 pass
100 pass
101 return oldvalue
101 return oldvalue
102
102
103
103
104 def no_op(*a, **kw): pass
104 def no_op(*a, **kw): pass
105
105
106 class SpaceInInput(exceptions.Exception): pass
106 class SpaceInInput(exceptions.Exception): pass
107
107
108 class Bunch: pass
108 class Bunch: pass
109
109
110
110
111 def get_default_colors():
111 def get_default_colors():
112 if sys.platform=='darwin':
112 if sys.platform=='darwin':
113 return "LightBG"
113 return "LightBG"
114 elif os.name=='nt':
114 elif os.name=='nt':
115 return 'Linux'
115 return 'Linux'
116 else:
116 else:
117 return 'Linux'
117 return 'Linux'
118
118
119
119
120 class SeparateStr(Str):
120 class SeparateStr(Str):
121 """A Str subclass to validate separate_in, separate_out, etc.
121 """A Str subclass to validate separate_in, separate_out, etc.
122
122
123 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
123 This is a Str based trait that converts '0'->'' and '\\n'->'\n'.
124 """
124 """
125
125
126 def validate(self, obj, value):
126 def validate(self, obj, value):
127 if value == '0': value = ''
127 if value == '0': value = ''
128 value = value.replace('\\n','\n')
128 value = value.replace('\\n','\n')
129 return super(SeparateStr, self).validate(obj, value)
129 return super(SeparateStr, self).validate(obj, value)
130
130
131 class MultipleInstanceError(Exception):
131 class MultipleInstanceError(Exception):
132 pass
132 pass
133
133
134
134
135 #-----------------------------------------------------------------------------
135 #-----------------------------------------------------------------------------
136 # Main IPython class
136 # Main IPython class
137 #-----------------------------------------------------------------------------
137 #-----------------------------------------------------------------------------
138
138
139
139
140 class InteractiveShell(Configurable, Magic):
140 class InteractiveShell(Configurable, Magic):
141 """An enhanced, interactive shell for Python."""
141 """An enhanced, interactive shell for Python."""
142
142
143 _instance = None
143 _instance = None
144 autocall = Enum((0,1,2), default_value=1, config=True)
144 autocall = Enum((0,1,2), default_value=1, config=True)
145 # TODO: remove all autoindent logic and put into frontends.
145 # TODO: remove all autoindent logic and put into frontends.
146 # We can't do this yet because even runlines uses the autoindent.
146 # We can't do this yet because even runlines uses the autoindent.
147 autoindent = CBool(True, config=True)
147 autoindent = CBool(True, config=True)
148 automagic = CBool(True, config=True)
148 automagic = CBool(True, config=True)
149 cache_size = Int(1000, config=True)
149 cache_size = Int(1000, config=True)
150 color_info = CBool(True, config=True)
150 color_info = CBool(True, config=True)
151 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
151 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
152 default_value=get_default_colors(), config=True)
152 default_value=get_default_colors(), config=True)
153 debug = CBool(False, config=True)
153 debug = CBool(False, config=True)
154 deep_reload = CBool(False, config=True)
154 deep_reload = CBool(False, config=True)
155 displayhook_class = Type(DisplayHook)
155 displayhook_class = Type(DisplayHook)
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 logstart = CBool(False, config=True)
158 logstart = CBool(False, config=True)
159 logfile = Str('', config=True)
159 logfile = Str('', config=True)
160 logappend = Str('', config=True)
160 logappend = Str('', config=True)
161 object_info_string_level = Enum((0,1,2), default_value=0,
161 object_info_string_level = Enum((0,1,2), default_value=0,
162 config=True)
162 config=True)
163 pdb = CBool(False, config=True)
163 pdb = CBool(False, config=True)
164 pprint = CBool(True, config=True)
164 pprint = CBool(True, config=True)
165 profile = Str('', config=True)
165 profile = Str('', config=True)
166 prompt_in1 = Str('In [\\#]: ', config=True)
166 prompt_in1 = Str('In [\\#]: ', config=True)
167 prompt_in2 = Str(' .\\D.: ', config=True)
167 prompt_in2 = Str(' .\\D.: ', config=True)
168 prompt_out = Str('Out[\\#]: ', config=True)
168 prompt_out = Str('Out[\\#]: ', config=True)
169 prompts_pad_left = CBool(True, config=True)
169 prompts_pad_left = CBool(True, config=True)
170 quiet = CBool(False, config=True)
170 quiet = CBool(False, config=True)
171
171
172 # The readline stuff will eventually be moved to the terminal subclass
172 # The readline stuff will eventually be moved to the terminal subclass
173 # but for now, we can't do that as readline is welded in everywhere.
173 # but for now, we can't do that as readline is welded in everywhere.
174 readline_use = CBool(True, config=True)
174 readline_use = CBool(True, config=True)
175 readline_merge_completions = CBool(True, config=True)
175 readline_merge_completions = CBool(True, config=True)
176 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
176 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
177 readline_remove_delims = Str('-/~', config=True)
177 readline_remove_delims = Str('-/~', config=True)
178 readline_parse_and_bind = List([
178 readline_parse_and_bind = List([
179 'tab: complete',
179 'tab: complete',
180 '"\C-l": clear-screen',
180 '"\C-l": clear-screen',
181 'set show-all-if-ambiguous on',
181 'set show-all-if-ambiguous on',
182 '"\C-o": tab-insert',
182 '"\C-o": tab-insert',
183 '"\M-i": " "',
183 '"\M-i": " "',
184 '"\M-o": "\d\d\d\d"',
184 '"\M-o": "\d\d\d\d"',
185 '"\M-I": "\d\d\d\d"',
185 '"\M-I": "\d\d\d\d"',
186 '"\C-r": reverse-search-history',
186 '"\C-r": reverse-search-history',
187 '"\C-s": forward-search-history',
187 '"\C-s": forward-search-history',
188 '"\C-p": history-search-backward',
188 '"\C-p": history-search-backward',
189 '"\C-n": history-search-forward',
189 '"\C-n": history-search-forward',
190 '"\e[A": history-search-backward',
190 '"\e[A": history-search-backward',
191 '"\e[B": history-search-forward',
191 '"\e[B": history-search-forward',
192 '"\C-k": kill-line',
192 '"\C-k": kill-line',
193 '"\C-u": unix-line-discard',
193 '"\C-u": unix-line-discard',
194 ], allow_none=False, config=True)
194 ], allow_none=False, config=True)
195
195
196 # TODO: this part of prompt management should be moved to the frontends.
196 # TODO: this part of prompt management should be moved to the frontends.
197 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
197 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
198 separate_in = SeparateStr('\n', config=True)
198 separate_in = SeparateStr('\n', config=True)
199 separate_out = SeparateStr('', config=True)
199 separate_out = SeparateStr('', config=True)
200 separate_out2 = SeparateStr('', config=True)
200 separate_out2 = SeparateStr('', config=True)
201 wildcards_case_sensitive = CBool(True, config=True)
201 wildcards_case_sensitive = CBool(True, config=True)
202 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
202 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
203 default_value='Context', config=True)
203 default_value='Context', config=True)
204
204
205 # Subcomponents of InteractiveShell
205 # Subcomponents of InteractiveShell
206 alias_manager = Instance('IPython.core.alias.AliasManager')
206 alias_manager = Instance('IPython.core.alias.AliasManager')
207 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
207 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
208 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
208 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
209 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
209 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
210 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
210 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
211 plugin_manager = Instance('IPython.core.plugin.PluginManager')
211 plugin_manager = Instance('IPython.core.plugin.PluginManager')
212 payload_manager = Instance('IPython.core.payload.PayloadManager')
212 payload_manager = Instance('IPython.core.payload.PayloadManager')
213
213
214 def __init__(self, config=None, ipython_dir=None,
214 def __init__(self, config=None, ipython_dir=None,
215 user_ns=None, user_global_ns=None,
215 user_ns=None, user_global_ns=None,
216 custom_exceptions=((),None)):
216 custom_exceptions=((),None)):
217
217
218 # This is where traits with a config_key argument are updated
218 # This is where traits with a config_key argument are updated
219 # from the values on config.
219 # from the values on config.
220 super(InteractiveShell, self).__init__(config=config)
220 super(InteractiveShell, self).__init__(config=config)
221
221
222 # These are relatively independent and stateless
222 # These are relatively independent and stateless
223 self.init_ipython_dir(ipython_dir)
223 self.init_ipython_dir(ipython_dir)
224 self.init_instance_attrs()
224 self.init_instance_attrs()
225
225
226 # Create namespaces (user_ns, user_global_ns, etc.)
226 # Create namespaces (user_ns, user_global_ns, etc.)
227 self.init_create_namespaces(user_ns, user_global_ns)
227 self.init_create_namespaces(user_ns, user_global_ns)
228 # This has to be done after init_create_namespaces because it uses
228 # This has to be done after init_create_namespaces because it uses
229 # something in self.user_ns, but before init_sys_modules, which
229 # something in self.user_ns, but before init_sys_modules, which
230 # is the first thing to modify sys.
230 # is the first thing to modify sys.
231 # TODO: When we override sys.stdout and sys.stderr before this class
231 # TODO: When we override sys.stdout and sys.stderr before this class
232 # is created, we are saving the overridden ones here. Not sure if this
232 # is created, we are saving the overridden ones here. Not sure if this
233 # is what we want to do.
233 # is what we want to do.
234 self.save_sys_module_state()
234 self.save_sys_module_state()
235 self.init_sys_modules()
235 self.init_sys_modules()
236
236
237 self.init_history()
237 self.init_history()
238 self.init_encoding()
238 self.init_encoding()
239 self.init_prefilter()
239 self.init_prefilter()
240
240
241 Magic.__init__(self, self)
241 Magic.__init__(self, self)
242
242
243 self.init_syntax_highlighting()
243 self.init_syntax_highlighting()
244 self.init_hooks()
244 self.init_hooks()
245 self.init_pushd_popd_magic()
245 self.init_pushd_popd_magic()
246 # self.init_traceback_handlers use to be here, but we moved it below
246 # self.init_traceback_handlers use to be here, but we moved it below
247 # because it and init_io have to come after init_readline.
247 # because it and init_io have to come after init_readline.
248 self.init_user_ns()
248 self.init_user_ns()
249 self.init_logger()
249 self.init_logger()
250 self.init_alias()
250 self.init_alias()
251 self.init_builtins()
251 self.init_builtins()
252
252
253 # pre_config_initialization
253 # pre_config_initialization
254 self.init_shadow_hist()
254 self.init_shadow_hist()
255
255
256 # The next section should contain averything that was in ipmaker.
256 # The next section should contain averything that was in ipmaker.
257 self.init_logstart()
257 self.init_logstart()
258
258
259 # The following was in post_config_initialization
259 # The following was in post_config_initialization
260 self.init_inspector()
260 self.init_inspector()
261 # init_readline() must come before init_io(), because init_io uses
261 # init_readline() must come before init_io(), because init_io uses
262 # readline related things.
262 # readline related things.
263 self.init_readline()
263 self.init_readline()
264 # TODO: init_io() needs to happen before init_traceback handlers
264 # TODO: init_io() needs to happen before init_traceback handlers
265 # because the traceback handlers hardcode the stdout/stderr streams.
265 # because the traceback handlers hardcode the stdout/stderr streams.
266 # This logic in in debugger.Pdb and should eventually be changed.
266 # This logic in in debugger.Pdb and should eventually be changed.
267 self.init_io()
267 self.init_io()
268 self.init_traceback_handlers(custom_exceptions)
268 self.init_traceback_handlers(custom_exceptions)
269 self.init_prompts()
269 self.init_prompts()
270 self.init_displayhook()
270 self.init_displayhook()
271 self.init_reload_doctest()
271 self.init_reload_doctest()
272 self.init_magics()
272 self.init_magics()
273 self.init_pdb()
273 self.init_pdb()
274 self.init_extension_manager()
274 self.init_extension_manager()
275 self.init_plugin_manager()
275 self.init_plugin_manager()
276 self.init_payload()
276 self.init_payload()
277 self.hooks.late_startup_hook()
277 self.hooks.late_startup_hook()
278
278
279 @classmethod
279 @classmethod
280 def instance(cls, *args, **kwargs):
280 def instance(cls, *args, **kwargs):
281 """Returns a global InteractiveShell instance."""
281 """Returns a global InteractiveShell instance."""
282 if cls._instance is None:
282 if cls._instance is None:
283 inst = cls(*args, **kwargs)
283 inst = cls(*args, **kwargs)
284 # Now make sure that the instance will also be returned by
284 # Now make sure that the instance will also be returned by
285 # the subclasses instance attribute.
285 # the subclasses instance attribute.
286 for subclass in cls.mro():
286 for subclass in cls.mro():
287 if issubclass(cls, subclass) and issubclass(subclass, InteractiveShell):
287 if issubclass(cls, subclass) and issubclass(subclass, InteractiveShell):
288 subclass._instance = inst
288 subclass._instance = inst
289 else:
289 else:
290 break
290 break
291 if isinstance(cls._instance, cls):
291 if isinstance(cls._instance, cls):
292 return cls._instance
292 return cls._instance
293 else:
293 else:
294 raise MultipleInstanceError(
294 raise MultipleInstanceError(
295 'Multiple incompatible subclass instances of '
295 'Multiple incompatible subclass instances of '
296 'InteractiveShell are being created.'
296 'InteractiveShell are being created.'
297 )
297 )
298
298
299 @classmethod
299 @classmethod
300 def initialized(cls):
300 def initialized(cls):
301 return hasattr(cls, "_instance")
301 return hasattr(cls, "_instance")
302
302
303 def get_ipython(self):
303 def get_ipython(self):
304 """Return the currently running IPython instance."""
304 """Return the currently running IPython instance."""
305 return self
305 return self
306
306
307 #-------------------------------------------------------------------------
307 #-------------------------------------------------------------------------
308 # Trait changed handlers
308 # Trait changed handlers
309 #-------------------------------------------------------------------------
309 #-------------------------------------------------------------------------
310
310
311 def _ipython_dir_changed(self, name, new):
311 def _ipython_dir_changed(self, name, new):
312 if not os.path.isdir(new):
312 if not os.path.isdir(new):
313 os.makedirs(new, mode = 0777)
313 os.makedirs(new, mode = 0777)
314
314
315 def set_autoindent(self,value=None):
315 def set_autoindent(self,value=None):
316 """Set the autoindent flag, checking for readline support.
316 """Set the autoindent flag, checking for readline support.
317
317
318 If called with no arguments, it acts as a toggle."""
318 If called with no arguments, it acts as a toggle."""
319
319
320 if not self.has_readline:
320 if not self.has_readline:
321 if os.name == 'posix':
321 if os.name == 'posix':
322 warn("The auto-indent feature requires the readline library")
322 warn("The auto-indent feature requires the readline library")
323 self.autoindent = 0
323 self.autoindent = 0
324 return
324 return
325 if value is None:
325 if value is None:
326 self.autoindent = not self.autoindent
326 self.autoindent = not self.autoindent
327 else:
327 else:
328 self.autoindent = value
328 self.autoindent = value
329
329
330 #-------------------------------------------------------------------------
330 #-------------------------------------------------------------------------
331 # init_* methods called by __init__
331 # init_* methods called by __init__
332 #-------------------------------------------------------------------------
332 #-------------------------------------------------------------------------
333
333
334 def init_ipython_dir(self, ipython_dir):
334 def init_ipython_dir(self, ipython_dir):
335 if ipython_dir is not None:
335 if ipython_dir is not None:
336 self.ipython_dir = ipython_dir
336 self.ipython_dir = ipython_dir
337 self.config.Global.ipython_dir = self.ipython_dir
337 self.config.Global.ipython_dir = self.ipython_dir
338 return
338 return
339
339
340 if hasattr(self.config.Global, 'ipython_dir'):
340 if hasattr(self.config.Global, 'ipython_dir'):
341 self.ipython_dir = self.config.Global.ipython_dir
341 self.ipython_dir = self.config.Global.ipython_dir
342 else:
342 else:
343 self.ipython_dir = get_ipython_dir()
343 self.ipython_dir = get_ipython_dir()
344
344
345 # All children can just read this
345 # All children can just read this
346 self.config.Global.ipython_dir = self.ipython_dir
346 self.config.Global.ipython_dir = self.ipython_dir
347
347
348 def init_instance_attrs(self):
348 def init_instance_attrs(self):
349 self.more = False
349 self.more = False
350
350
351 # command compiler
351 # command compiler
352 self.compile = codeop.CommandCompiler()
352 self.compile = codeop.CommandCompiler()
353
353
354 # User input buffer
354 # User input buffer
355 self.buffer = []
355 self.buffer = []
356
356
357 # Make an empty namespace, which extension writers can rely on both
357 # Make an empty namespace, which extension writers can rely on both
358 # existing and NEVER being used by ipython itself. This gives them a
358 # existing and NEVER being used by ipython itself. This gives them a
359 # convenient location for storing additional information and state
359 # convenient location for storing additional information and state
360 # their extensions may require, without fear of collisions with other
360 # their extensions may require, without fear of collisions with other
361 # ipython names that may develop later.
361 # ipython names that may develop later.
362 self.meta = Struct()
362 self.meta = Struct()
363
363
364 # Object variable to store code object waiting execution. This is
364 # Object variable to store code object waiting execution. This is
365 # used mainly by the multithreaded shells, but it can come in handy in
365 # used mainly by the multithreaded shells, but it can come in handy in
366 # other situations. No need to use a Queue here, since it's a single
366 # other situations. No need to use a Queue here, since it's a single
367 # item which gets cleared once run.
367 # item which gets cleared once run.
368 self.code_to_run = None
368 self.code_to_run = None
369
369
370 # Temporary files used for various purposes. Deleted at exit.
370 # Temporary files used for various purposes. Deleted at exit.
371 self.tempfiles = []
371 self.tempfiles = []
372
372
373 # Keep track of readline usage (later set by init_readline)
373 # Keep track of readline usage (later set by init_readline)
374 self.has_readline = False
374 self.has_readline = False
375
375
376 # keep track of where we started running (mainly for crash post-mortem)
376 # keep track of where we started running (mainly for crash post-mortem)
377 # This is not being used anywhere currently.
377 # This is not being used anywhere currently.
378 self.starting_dir = os.getcwd()
378 self.starting_dir = os.getcwd()
379
379
380 # Indentation management
380 # Indentation management
381 self.indent_current_nsp = 0
381 self.indent_current_nsp = 0
382
382
383 def init_encoding(self):
383 def init_encoding(self):
384 # Get system encoding at startup time. Certain terminals (like Emacs
384 # Get system encoding at startup time. Certain terminals (like Emacs
385 # under Win32 have it set to None, and we need to have a known valid
385 # under Win32 have it set to None, and we need to have a known valid
386 # encoding to use in the raw_input() method
386 # encoding to use in the raw_input() method
387 try:
387 try:
388 self.stdin_encoding = sys.stdin.encoding or 'ascii'
388 self.stdin_encoding = sys.stdin.encoding or 'ascii'
389 except AttributeError:
389 except AttributeError:
390 self.stdin_encoding = 'ascii'
390 self.stdin_encoding = 'ascii'
391
391
392 def init_syntax_highlighting(self):
392 def init_syntax_highlighting(self):
393 # Python source parser/formatter for syntax highlighting
393 # Python source parser/formatter for syntax highlighting
394 pyformat = PyColorize.Parser().format
394 pyformat = PyColorize.Parser().format
395 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
395 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
396
396
397 def init_pushd_popd_magic(self):
397 def init_pushd_popd_magic(self):
398 # for pushd/popd management
398 # for pushd/popd management
399 try:
399 try:
400 self.home_dir = get_home_dir()
400 self.home_dir = get_home_dir()
401 except HomeDirError, msg:
401 except HomeDirError, msg:
402 fatal(msg)
402 fatal(msg)
403
403
404 self.dir_stack = []
404 self.dir_stack = []
405
405
406 def init_logger(self):
406 def init_logger(self):
407 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
407 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
408 # local shortcut, this is used a LOT
408 # local shortcut, this is used a LOT
409 self.log = self.logger.log
409 self.log = self.logger.log
410
410
411 def init_logstart(self):
411 def init_logstart(self):
412 if self.logappend:
412 if self.logappend:
413 self.magic_logstart(self.logappend + ' append')
413 self.magic_logstart(self.logappend + ' append')
414 elif self.logfile:
414 elif self.logfile:
415 self.magic_logstart(self.logfile)
415 self.magic_logstart(self.logfile)
416 elif self.logstart:
416 elif self.logstart:
417 self.magic_logstart()
417 self.magic_logstart()
418
418
419 def init_builtins(self):
419 def init_builtins(self):
420 self.builtin_trap = BuiltinTrap(shell=self)
420 self.builtin_trap = BuiltinTrap(shell=self)
421
421
422 def init_inspector(self):
422 def init_inspector(self):
423 # Object inspector
423 # Object inspector
424 self.inspector = oinspect.Inspector(oinspect.InspectColors,
424 self.inspector = oinspect.Inspector(oinspect.InspectColors,
425 PyColorize.ANSICodeColors,
425 PyColorize.ANSICodeColors,
426 'NoColor',
426 'NoColor',
427 self.object_info_string_level)
427 self.object_info_string_level)
428
428
429 def init_io(self):
429 def init_io(self):
430 import IPython.utils.io
430 import IPython.utils.io
431 if sys.platform == 'win32' and self.has_readline:
431 if sys.platform == 'win32' and self.has_readline:
432 Term = io.IOTerm(
432 Term = io.IOTerm(
433 cout=self.readline._outputfile,cerr=self.readline._outputfile
433 cout=self.readline._outputfile,cerr=self.readline._outputfile
434 )
434 )
435 else:
435 else:
436 Term = io.IOTerm()
436 Term = io.IOTerm()
437 io.Term = Term
437 io.Term = Term
438
438
439 def init_prompts(self):
439 def init_prompts(self):
440 # TODO: This is a pass for now because the prompts are managed inside
440 # TODO: This is a pass for now because the prompts are managed inside
441 # the DisplayHook. Once there is a separate prompt manager, this
441 # the DisplayHook. Once there is a separate prompt manager, this
442 # will initialize that object and all prompt related information.
442 # will initialize that object and all prompt related information.
443 pass
443 pass
444
444
445 def init_displayhook(self):
445 def init_displayhook(self):
446 # Initialize displayhook, set in/out prompts and printing system
446 # Initialize displayhook, set in/out prompts and printing system
447 self.displayhook = self.displayhook_class(
447 self.displayhook = self.displayhook_class(
448 shell=self,
448 shell=self,
449 cache_size=self.cache_size,
449 cache_size=self.cache_size,
450 input_sep = self.separate_in,
450 input_sep = self.separate_in,
451 output_sep = self.separate_out,
451 output_sep = self.separate_out,
452 output_sep2 = self.separate_out2,
452 output_sep2 = self.separate_out2,
453 ps1 = self.prompt_in1,
453 ps1 = self.prompt_in1,
454 ps2 = self.prompt_in2,
454 ps2 = self.prompt_in2,
455 ps_out = self.prompt_out,
455 ps_out = self.prompt_out,
456 pad_left = self.prompts_pad_left
456 pad_left = self.prompts_pad_left
457 )
457 )
458 # This is a context manager that installs/revmoes the displayhook at
458 # This is a context manager that installs/revmoes the displayhook at
459 # the appropriate time.
459 # the appropriate time.
460 self.display_trap = DisplayTrap(hook=self.displayhook)
460 self.display_trap = DisplayTrap(hook=self.displayhook)
461
461
462 def init_reload_doctest(self):
462 def init_reload_doctest(self):
463 # Do a proper resetting of doctest, including the necessary displayhook
463 # Do a proper resetting of doctest, including the necessary displayhook
464 # monkeypatching
464 # monkeypatching
465 try:
465 try:
466 doctest_reload()
466 doctest_reload()
467 except ImportError:
467 except ImportError:
468 warn("doctest module does not exist.")
468 warn("doctest module does not exist.")
469
469
470 #-------------------------------------------------------------------------
470 #-------------------------------------------------------------------------
471 # Things related to injections into the sys module
471 # Things related to injections into the sys module
472 #-------------------------------------------------------------------------
472 #-------------------------------------------------------------------------
473
473
474 def save_sys_module_state(self):
474 def save_sys_module_state(self):
475 """Save the state of hooks in the sys module.
475 """Save the state of hooks in the sys module.
476
476
477 This has to be called after self.user_ns is created.
477 This has to be called after self.user_ns is created.
478 """
478 """
479 self._orig_sys_module_state = {}
479 self._orig_sys_module_state = {}
480 self._orig_sys_module_state['stdin'] = sys.stdin
480 self._orig_sys_module_state['stdin'] = sys.stdin
481 self._orig_sys_module_state['stdout'] = sys.stdout
481 self._orig_sys_module_state['stdout'] = sys.stdout
482 self._orig_sys_module_state['stderr'] = sys.stderr
482 self._orig_sys_module_state['stderr'] = sys.stderr
483 self._orig_sys_module_state['excepthook'] = sys.excepthook
483 self._orig_sys_module_state['excepthook'] = sys.excepthook
484 try:
484 try:
485 self._orig_sys_modules_main_name = self.user_ns['__name__']
485 self._orig_sys_modules_main_name = self.user_ns['__name__']
486 except KeyError:
486 except KeyError:
487 pass
487 pass
488
488
489 def restore_sys_module_state(self):
489 def restore_sys_module_state(self):
490 """Restore the state of the sys module."""
490 """Restore the state of the sys module."""
491 try:
491 try:
492 for k, v in self._orig_sys_module_state.items():
492 for k, v in self._orig_sys_module_state.items():
493 setattr(sys, k, v)
493 setattr(sys, k, v)
494 except AttributeError:
494 except AttributeError:
495 pass
495 pass
496 try:
496 try:
497 delattr(sys, 'ipcompleter')
497 delattr(sys, 'ipcompleter')
498 except AttributeError:
498 except AttributeError:
499 pass
499 pass
500 # Reset what what done in self.init_sys_modules
500 # Reset what what done in self.init_sys_modules
501 try:
501 try:
502 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
502 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
503 except (AttributeError, KeyError):
503 except (AttributeError, KeyError):
504 pass
504 pass
505
505
506 #-------------------------------------------------------------------------
506 #-------------------------------------------------------------------------
507 # Things related to hooks
507 # Things related to hooks
508 #-------------------------------------------------------------------------
508 #-------------------------------------------------------------------------
509
509
510 def init_hooks(self):
510 def init_hooks(self):
511 # hooks holds pointers used for user-side customizations
511 # hooks holds pointers used for user-side customizations
512 self.hooks = Struct()
512 self.hooks = Struct()
513
513
514 self.strdispatchers = {}
514 self.strdispatchers = {}
515
515
516 # Set all default hooks, defined in the IPython.hooks module.
516 # Set all default hooks, defined in the IPython.hooks module.
517 hooks = IPython.core.hooks
517 hooks = IPython.core.hooks
518 for hook_name in hooks.__all__:
518 for hook_name in hooks.__all__:
519 # default hooks have priority 100, i.e. low; user hooks should have
519 # default hooks have priority 100, i.e. low; user hooks should have
520 # 0-100 priority
520 # 0-100 priority
521 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
521 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
522
522
523 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
523 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
524 """set_hook(name,hook) -> sets an internal IPython hook.
524 """set_hook(name,hook) -> sets an internal IPython hook.
525
525
526 IPython exposes some of its internal API as user-modifiable hooks. By
526 IPython exposes some of its internal API as user-modifiable hooks. By
527 adding your function to one of these hooks, you can modify IPython's
527 adding your function to one of these hooks, you can modify IPython's
528 behavior to call at runtime your own routines."""
528 behavior to call at runtime your own routines."""
529
529
530 # At some point in the future, this should validate the hook before it
530 # At some point in the future, this should validate the hook before it
531 # accepts it. Probably at least check that the hook takes the number
531 # accepts it. Probably at least check that the hook takes the number
532 # of args it's supposed to.
532 # of args it's supposed to.
533
533
534 f = new.instancemethod(hook,self,self.__class__)
534 f = new.instancemethod(hook,self,self.__class__)
535
535
536 # check if the hook is for strdispatcher first
536 # check if the hook is for strdispatcher first
537 if str_key is not None:
537 if str_key is not None:
538 sdp = self.strdispatchers.get(name, StrDispatch())
538 sdp = self.strdispatchers.get(name, StrDispatch())
539 sdp.add_s(str_key, f, priority )
539 sdp.add_s(str_key, f, priority )
540 self.strdispatchers[name] = sdp
540 self.strdispatchers[name] = sdp
541 return
541 return
542 if re_key is not None:
542 if re_key is not None:
543 sdp = self.strdispatchers.get(name, StrDispatch())
543 sdp = self.strdispatchers.get(name, StrDispatch())
544 sdp.add_re(re.compile(re_key), f, priority )
544 sdp.add_re(re.compile(re_key), f, priority )
545 self.strdispatchers[name] = sdp
545 self.strdispatchers[name] = sdp
546 return
546 return
547
547
548 dp = getattr(self.hooks, name, None)
548 dp = getattr(self.hooks, name, None)
549 if name not in IPython.core.hooks.__all__:
549 if name not in IPython.core.hooks.__all__:
550 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
550 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
551 if not dp:
551 if not dp:
552 dp = IPython.core.hooks.CommandChainDispatcher()
552 dp = IPython.core.hooks.CommandChainDispatcher()
553
553
554 try:
554 try:
555 dp.add(f,priority)
555 dp.add(f,priority)
556 except AttributeError:
556 except AttributeError:
557 # it was not commandchain, plain old func - replace
557 # it was not commandchain, plain old func - replace
558 dp = f
558 dp = f
559
559
560 setattr(self.hooks,name, dp)
560 setattr(self.hooks,name, dp)
561
561
562 #-------------------------------------------------------------------------
562 #-------------------------------------------------------------------------
563 # Things related to the "main" module
563 # Things related to the "main" module
564 #-------------------------------------------------------------------------
564 #-------------------------------------------------------------------------
565
565
566 def new_main_mod(self,ns=None):
566 def new_main_mod(self,ns=None):
567 """Return a new 'main' module object for user code execution.
567 """Return a new 'main' module object for user code execution.
568 """
568 """
569 main_mod = self._user_main_module
569 main_mod = self._user_main_module
570 init_fakemod_dict(main_mod,ns)
570 init_fakemod_dict(main_mod,ns)
571 return main_mod
571 return main_mod
572
572
573 def cache_main_mod(self,ns,fname):
573 def cache_main_mod(self,ns,fname):
574 """Cache a main module's namespace.
574 """Cache a main module's namespace.
575
575
576 When scripts are executed via %run, we must keep a reference to the
576 When scripts are executed via %run, we must keep a reference to the
577 namespace of their __main__ module (a FakeModule instance) around so
577 namespace of their __main__ module (a FakeModule instance) around so
578 that Python doesn't clear it, rendering objects defined therein
578 that Python doesn't clear it, rendering objects defined therein
579 useless.
579 useless.
580
580
581 This method keeps said reference in a private dict, keyed by the
581 This method keeps said reference in a private dict, keyed by the
582 absolute path of the module object (which corresponds to the script
582 absolute path of the module object (which corresponds to the script
583 path). This way, for multiple executions of the same script we only
583 path). This way, for multiple executions of the same script we only
584 keep one copy of the namespace (the last one), thus preventing memory
584 keep one copy of the namespace (the last one), thus preventing memory
585 leaks from old references while allowing the objects from the last
585 leaks from old references while allowing the objects from the last
586 execution to be accessible.
586 execution to be accessible.
587
587
588 Note: we can not allow the actual FakeModule instances to be deleted,
588 Note: we can not allow the actual FakeModule instances to be deleted,
589 because of how Python tears down modules (it hard-sets all their
589 because of how Python tears down modules (it hard-sets all their
590 references to None without regard for reference counts). This method
590 references to None without regard for reference counts). This method
591 must therefore make a *copy* of the given namespace, to allow the
591 must therefore make a *copy* of the given namespace, to allow the
592 original module's __dict__ to be cleared and reused.
592 original module's __dict__ to be cleared and reused.
593
593
594
594
595 Parameters
595 Parameters
596 ----------
596 ----------
597 ns : a namespace (a dict, typically)
597 ns : a namespace (a dict, typically)
598
598
599 fname : str
599 fname : str
600 Filename associated with the namespace.
600 Filename associated with the namespace.
601
601
602 Examples
602 Examples
603 --------
603 --------
604
604
605 In [10]: import IPython
605 In [10]: import IPython
606
606
607 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
607 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
608
608
609 In [12]: IPython.__file__ in _ip._main_ns_cache
609 In [12]: IPython.__file__ in _ip._main_ns_cache
610 Out[12]: True
610 Out[12]: True
611 """
611 """
612 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
612 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
613
613
614 def clear_main_mod_cache(self):
614 def clear_main_mod_cache(self):
615 """Clear the cache of main modules.
615 """Clear the cache of main modules.
616
616
617 Mainly for use by utilities like %reset.
617 Mainly for use by utilities like %reset.
618
618
619 Examples
619 Examples
620 --------
620 --------
621
621
622 In [15]: import IPython
622 In [15]: import IPython
623
623
624 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
624 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
625
625
626 In [17]: len(_ip._main_ns_cache) > 0
626 In [17]: len(_ip._main_ns_cache) > 0
627 Out[17]: True
627 Out[17]: True
628
628
629 In [18]: _ip.clear_main_mod_cache()
629 In [18]: _ip.clear_main_mod_cache()
630
630
631 In [19]: len(_ip._main_ns_cache) == 0
631 In [19]: len(_ip._main_ns_cache) == 0
632 Out[19]: True
632 Out[19]: True
633 """
633 """
634 self._main_ns_cache.clear()
634 self._main_ns_cache.clear()
635
635
636 #-------------------------------------------------------------------------
636 #-------------------------------------------------------------------------
637 # Things related to debugging
637 # Things related to debugging
638 #-------------------------------------------------------------------------
638 #-------------------------------------------------------------------------
639
639
640 def init_pdb(self):
640 def init_pdb(self):
641 # Set calling of pdb on exceptions
641 # Set calling of pdb on exceptions
642 # self.call_pdb is a property
642 # self.call_pdb is a property
643 self.call_pdb = self.pdb
643 self.call_pdb = self.pdb
644
644
645 def _get_call_pdb(self):
645 def _get_call_pdb(self):
646 return self._call_pdb
646 return self._call_pdb
647
647
648 def _set_call_pdb(self,val):
648 def _set_call_pdb(self,val):
649
649
650 if val not in (0,1,False,True):
650 if val not in (0,1,False,True):
651 raise ValueError,'new call_pdb value must be boolean'
651 raise ValueError,'new call_pdb value must be boolean'
652
652
653 # store value in instance
653 # store value in instance
654 self._call_pdb = val
654 self._call_pdb = val
655
655
656 # notify the actual exception handlers
656 # notify the actual exception handlers
657 self.InteractiveTB.call_pdb = val
657 self.InteractiveTB.call_pdb = val
658
658
659 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
659 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
660 'Control auto-activation of pdb at exceptions')
660 'Control auto-activation of pdb at exceptions')
661
661
662 def debugger(self,force=False):
662 def debugger(self,force=False):
663 """Call the pydb/pdb debugger.
663 """Call the pydb/pdb debugger.
664
664
665 Keywords:
665 Keywords:
666
666
667 - force(False): by default, this routine checks the instance call_pdb
667 - force(False): by default, this routine checks the instance call_pdb
668 flag and does not actually invoke the debugger if the flag is false.
668 flag and does not actually invoke the debugger if the flag is false.
669 The 'force' option forces the debugger to activate even if the flag
669 The 'force' option forces the debugger to activate even if the flag
670 is false.
670 is false.
671 """
671 """
672
672
673 if not (force or self.call_pdb):
673 if not (force or self.call_pdb):
674 return
674 return
675
675
676 if not hasattr(sys,'last_traceback'):
676 if not hasattr(sys,'last_traceback'):
677 error('No traceback has been produced, nothing to debug.')
677 error('No traceback has been produced, nothing to debug.')
678 return
678 return
679
679
680 # use pydb if available
680 # use pydb if available
681 if debugger.has_pydb:
681 if debugger.has_pydb:
682 from pydb import pm
682 from pydb import pm
683 else:
683 else:
684 # fallback to our internal debugger
684 # fallback to our internal debugger
685 pm = lambda : self.InteractiveTB.debugger(force=True)
685 pm = lambda : self.InteractiveTB.debugger(force=True)
686 self.history_saving_wrapper(pm)()
686 self.history_saving_wrapper(pm)()
687
687
688 #-------------------------------------------------------------------------
688 #-------------------------------------------------------------------------
689 # Things related to IPython's various namespaces
689 # Things related to IPython's various namespaces
690 #-------------------------------------------------------------------------
690 #-------------------------------------------------------------------------
691
691
692 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
692 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
693 # Create the namespace where the user will operate. user_ns is
693 # Create the namespace where the user will operate. user_ns is
694 # normally the only one used, and it is passed to the exec calls as
694 # normally the only one used, and it is passed to the exec calls as
695 # the locals argument. But we do carry a user_global_ns namespace
695 # the locals argument. But we do carry a user_global_ns namespace
696 # given as the exec 'globals' argument, This is useful in embedding
696 # given as the exec 'globals' argument, This is useful in embedding
697 # situations where the ipython shell opens in a context where the
697 # situations where the ipython shell opens in a context where the
698 # distinction between locals and globals is meaningful. For
698 # distinction between locals and globals is meaningful. For
699 # non-embedded contexts, it is just the same object as the user_ns dict.
699 # non-embedded contexts, it is just the same object as the user_ns dict.
700
700
701 # FIXME. For some strange reason, __builtins__ is showing up at user
701 # FIXME. For some strange reason, __builtins__ is showing up at user
702 # level as a dict instead of a module. This is a manual fix, but I
702 # level as a dict instead of a module. This is a manual fix, but I
703 # should really track down where the problem is coming from. Alex
703 # should really track down where the problem is coming from. Alex
704 # Schmolck reported this problem first.
704 # Schmolck reported this problem first.
705
705
706 # A useful post by Alex Martelli on this topic:
706 # A useful post by Alex Martelli on this topic:
707 # Re: inconsistent value from __builtins__
707 # Re: inconsistent value from __builtins__
708 # Von: Alex Martelli <aleaxit@yahoo.com>
708 # Von: Alex Martelli <aleaxit@yahoo.com>
709 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
709 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
710 # Gruppen: comp.lang.python
710 # Gruppen: comp.lang.python
711
711
712 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
712 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
713 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
713 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
714 # > <type 'dict'>
714 # > <type 'dict'>
715 # > >>> print type(__builtins__)
715 # > >>> print type(__builtins__)
716 # > <type 'module'>
716 # > <type 'module'>
717 # > Is this difference in return value intentional?
717 # > Is this difference in return value intentional?
718
718
719 # Well, it's documented that '__builtins__' can be either a dictionary
719 # Well, it's documented that '__builtins__' can be either a dictionary
720 # or a module, and it's been that way for a long time. Whether it's
720 # or a module, and it's been that way for a long time. Whether it's
721 # intentional (or sensible), I don't know. In any case, the idea is
721 # intentional (or sensible), I don't know. In any case, the idea is
722 # that if you need to access the built-in namespace directly, you
722 # that if you need to access the built-in namespace directly, you
723 # should start with "import __builtin__" (note, no 's') which will
723 # should start with "import __builtin__" (note, no 's') which will
724 # definitely give you a module. Yeah, it's somewhat confusing:-(.
724 # definitely give you a module. Yeah, it's somewhat confusing:-(.
725
725
726 # These routines return properly built dicts as needed by the rest of
726 # These routines return properly built dicts as needed by the rest of
727 # the code, and can also be used by extension writers to generate
727 # the code, and can also be used by extension writers to generate
728 # properly initialized namespaces.
728 # properly initialized namespaces.
729 user_ns, user_global_ns = self.make_user_namespaces(user_ns, user_global_ns)
729 user_ns, user_global_ns = self.make_user_namespaces(user_ns, user_global_ns)
730
730
731 # Assign namespaces
731 # Assign namespaces
732 # This is the namespace where all normal user variables live
732 # This is the namespace where all normal user variables live
733 self.user_ns = user_ns
733 self.user_ns = user_ns
734 self.user_global_ns = user_global_ns
734 self.user_global_ns = user_global_ns
735
735
736 # An auxiliary namespace that checks what parts of the user_ns were
736 # An auxiliary namespace that checks what parts of the user_ns were
737 # loaded at startup, so we can list later only variables defined in
737 # loaded at startup, so we can list later only variables defined in
738 # actual interactive use. Since it is always a subset of user_ns, it
738 # actual interactive use. Since it is always a subset of user_ns, it
739 # doesn't need to be separately tracked in the ns_table.
739 # doesn't need to be separately tracked in the ns_table.
740 self.user_ns_hidden = {}
740 self.user_ns_hidden = {}
741
741
742 # A namespace to keep track of internal data structures to prevent
742 # A namespace to keep track of internal data structures to prevent
743 # them from cluttering user-visible stuff. Will be updated later
743 # them from cluttering user-visible stuff. Will be updated later
744 self.internal_ns = {}
744 self.internal_ns = {}
745
745
746 # Now that FakeModule produces a real module, we've run into a nasty
746 # Now that FakeModule produces a real module, we've run into a nasty
747 # problem: after script execution (via %run), the module where the user
747 # problem: after script execution (via %run), the module where the user
748 # code ran is deleted. Now that this object is a true module (needed
748 # code ran is deleted. Now that this object is a true module (needed
749 # so docetst and other tools work correctly), the Python module
749 # so docetst and other tools work correctly), the Python module
750 # teardown mechanism runs over it, and sets to None every variable
750 # teardown mechanism runs over it, and sets to None every variable
751 # present in that module. Top-level references to objects from the
751 # present in that module. Top-level references to objects from the
752 # script survive, because the user_ns is updated with them. However,
752 # script survive, because the user_ns is updated with them. However,
753 # calling functions defined in the script that use other things from
753 # calling functions defined in the script that use other things from
754 # the script will fail, because the function's closure had references
754 # the script will fail, because the function's closure had references
755 # to the original objects, which are now all None. So we must protect
755 # to the original objects, which are now all None. So we must protect
756 # these modules from deletion by keeping a cache.
756 # these modules from deletion by keeping a cache.
757 #
757 #
758 # To avoid keeping stale modules around (we only need the one from the
758 # To avoid keeping stale modules around (we only need the one from the
759 # last run), we use a dict keyed with the full path to the script, so
759 # last run), we use a dict keyed with the full path to the script, so
760 # only the last version of the module is held in the cache. Note,
760 # only the last version of the module is held in the cache. Note,
761 # however, that we must cache the module *namespace contents* (their
761 # however, that we must cache the module *namespace contents* (their
762 # __dict__). Because if we try to cache the actual modules, old ones
762 # __dict__). Because if we try to cache the actual modules, old ones
763 # (uncached) could be destroyed while still holding references (such as
763 # (uncached) could be destroyed while still holding references (such as
764 # those held by GUI objects that tend to be long-lived)>
764 # those held by GUI objects that tend to be long-lived)>
765 #
765 #
766 # The %reset command will flush this cache. See the cache_main_mod()
766 # The %reset command will flush this cache. See the cache_main_mod()
767 # and clear_main_mod_cache() methods for details on use.
767 # and clear_main_mod_cache() methods for details on use.
768
768
769 # This is the cache used for 'main' namespaces
769 # This is the cache used for 'main' namespaces
770 self._main_ns_cache = {}
770 self._main_ns_cache = {}
771 # And this is the single instance of FakeModule whose __dict__ we keep
771 # And this is the single instance of FakeModule whose __dict__ we keep
772 # copying and clearing for reuse on each %run
772 # copying and clearing for reuse on each %run
773 self._user_main_module = FakeModule()
773 self._user_main_module = FakeModule()
774
774
775 # A table holding all the namespaces IPython deals with, so that
775 # A table holding all the namespaces IPython deals with, so that
776 # introspection facilities can search easily.
776 # introspection facilities can search easily.
777 self.ns_table = {'user':user_ns,
777 self.ns_table = {'user':user_ns,
778 'user_global':user_global_ns,
778 'user_global':user_global_ns,
779 'internal':self.internal_ns,
779 'internal':self.internal_ns,
780 'builtin':__builtin__.__dict__
780 'builtin':__builtin__.__dict__
781 }
781 }
782
782
783 # Similarly, track all namespaces where references can be held and that
783 # Similarly, track all namespaces where references can be held and that
784 # we can safely clear (so it can NOT include builtin). This one can be
784 # we can safely clear (so it can NOT include builtin). This one can be
785 # a simple list.
785 # a simple list.
786 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
786 self.ns_refs_table = [ user_ns, user_global_ns, self.user_ns_hidden,
787 self.internal_ns, self._main_ns_cache ]
787 self.internal_ns, self._main_ns_cache ]
788
788
789 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
789 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
790 """Return a valid local and global user interactive namespaces.
790 """Return a valid local and global user interactive namespaces.
791
791
792 This builds a dict with the minimal information needed to operate as a
792 This builds a dict with the minimal information needed to operate as a
793 valid IPython user namespace, which you can pass to the various
793 valid IPython user namespace, which you can pass to the various
794 embedding classes in ipython. The default implementation returns the
794 embedding classes in ipython. The default implementation returns the
795 same dict for both the locals and the globals to allow functions to
795 same dict for both the locals and the globals to allow functions to
796 refer to variables in the namespace. Customized implementations can
796 refer to variables in the namespace. Customized implementations can
797 return different dicts. The locals dictionary can actually be anything
797 return different dicts. The locals dictionary can actually be anything
798 following the basic mapping protocol of a dict, but the globals dict
798 following the basic mapping protocol of a dict, but the globals dict
799 must be a true dict, not even a subclass. It is recommended that any
799 must be a true dict, not even a subclass. It is recommended that any
800 custom object for the locals namespace synchronize with the globals
800 custom object for the locals namespace synchronize with the globals
801 dict somehow.
801 dict somehow.
802
802
803 Raises TypeError if the provided globals namespace is not a true dict.
803 Raises TypeError if the provided globals namespace is not a true dict.
804
804
805 Parameters
805 Parameters
806 ----------
806 ----------
807 user_ns : dict-like, optional
807 user_ns : dict-like, optional
808 The current user namespace. The items in this namespace should
808 The current user namespace. The items in this namespace should
809 be included in the output. If None, an appropriate blank
809 be included in the output. If None, an appropriate blank
810 namespace should be created.
810 namespace should be created.
811 user_global_ns : dict, optional
811 user_global_ns : dict, optional
812 The current user global namespace. The items in this namespace
812 The current user global namespace. The items in this namespace
813 should be included in the output. If None, an appropriate
813 should be included in the output. If None, an appropriate
814 blank namespace should be created.
814 blank namespace should be created.
815
815
816 Returns
816 Returns
817 -------
817 -------
818 A pair of dictionary-like object to be used as the local namespace
818 A pair of dictionary-like object to be used as the local namespace
819 of the interpreter and a dict to be used as the global namespace.
819 of the interpreter and a dict to be used as the global namespace.
820 """
820 """
821
821
822
822
823 # We must ensure that __builtin__ (without the final 's') is always
823 # We must ensure that __builtin__ (without the final 's') is always
824 # available and pointing to the __builtin__ *module*. For more details:
824 # available and pointing to the __builtin__ *module*. For more details:
825 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
825 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
826
826
827 if user_ns is None:
827 if user_ns is None:
828 # Set __name__ to __main__ to better match the behavior of the
828 # Set __name__ to __main__ to better match the behavior of the
829 # normal interpreter.
829 # normal interpreter.
830 user_ns = {'__name__' :'__main__',
830 user_ns = {'__name__' :'__main__',
831 '__builtin__' : __builtin__,
831 '__builtin__' : __builtin__,
832 '__builtins__' : __builtin__,
832 '__builtins__' : __builtin__,
833 }
833 }
834 else:
834 else:
835 user_ns.setdefault('__name__','__main__')
835 user_ns.setdefault('__name__','__main__')
836 user_ns.setdefault('__builtin__',__builtin__)
836 user_ns.setdefault('__builtin__',__builtin__)
837 user_ns.setdefault('__builtins__',__builtin__)
837 user_ns.setdefault('__builtins__',__builtin__)
838
838
839 if user_global_ns is None:
839 if user_global_ns is None:
840 user_global_ns = user_ns
840 user_global_ns = user_ns
841 if type(user_global_ns) is not dict:
841 if type(user_global_ns) is not dict:
842 raise TypeError("user_global_ns must be a true dict; got %r"
842 raise TypeError("user_global_ns must be a true dict; got %r"
843 % type(user_global_ns))
843 % type(user_global_ns))
844
844
845 return user_ns, user_global_ns
845 return user_ns, user_global_ns
846
846
847 def init_sys_modules(self):
847 def init_sys_modules(self):
848 # We need to insert into sys.modules something that looks like a
848 # We need to insert into sys.modules something that looks like a
849 # module but which accesses the IPython namespace, for shelve and
849 # module but which accesses the IPython namespace, for shelve and
850 # pickle to work interactively. Normally they rely on getting
850 # pickle to work interactively. Normally they rely on getting
851 # everything out of __main__, but for embedding purposes each IPython
851 # everything out of __main__, but for embedding purposes each IPython
852 # instance has its own private namespace, so we can't go shoving
852 # instance has its own private namespace, so we can't go shoving
853 # everything into __main__.
853 # everything into __main__.
854
854
855 # note, however, that we should only do this for non-embedded
855 # note, however, that we should only do this for non-embedded
856 # ipythons, which really mimic the __main__.__dict__ with their own
856 # ipythons, which really mimic the __main__.__dict__ with their own
857 # namespace. Embedded instances, on the other hand, should not do
857 # namespace. Embedded instances, on the other hand, should not do
858 # this because they need to manage the user local/global namespaces
858 # this because they need to manage the user local/global namespaces
859 # only, but they live within a 'normal' __main__ (meaning, they
859 # only, but they live within a 'normal' __main__ (meaning, they
860 # shouldn't overtake the execution environment of the script they're
860 # shouldn't overtake the execution environment of the script they're
861 # embedded in).
861 # embedded in).
862
862
863 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
863 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
864
864
865 try:
865 try:
866 main_name = self.user_ns['__name__']
866 main_name = self.user_ns['__name__']
867 except KeyError:
867 except KeyError:
868 raise KeyError('user_ns dictionary MUST have a "__name__" key')
868 raise KeyError('user_ns dictionary MUST have a "__name__" key')
869 else:
869 else:
870 sys.modules[main_name] = FakeModule(self.user_ns)
870 sys.modules[main_name] = FakeModule(self.user_ns)
871
871
872 def init_user_ns(self):
872 def init_user_ns(self):
873 """Initialize all user-visible namespaces to their minimum defaults.
873 """Initialize all user-visible namespaces to their minimum defaults.
874
874
875 Certain history lists are also initialized here, as they effectively
875 Certain history lists are also initialized here, as they effectively
876 act as user namespaces.
876 act as user namespaces.
877
877
878 Notes
878 Notes
879 -----
879 -----
880 All data structures here are only filled in, they are NOT reset by this
880 All data structures here are only filled in, they are NOT reset by this
881 method. If they were not empty before, data will simply be added to
881 method. If they were not empty before, data will simply be added to
882 therm.
882 therm.
883 """
883 """
884 # This function works in two parts: first we put a few things in
884 # This function works in two parts: first we put a few things in
885 # user_ns, and we sync that contents into user_ns_hidden so that these
885 # user_ns, and we sync that contents into user_ns_hidden so that these
886 # initial variables aren't shown by %who. After the sync, we add the
886 # initial variables aren't shown by %who. After the sync, we add the
887 # rest of what we *do* want the user to see with %who even on a new
887 # rest of what we *do* want the user to see with %who even on a new
888 # session (probably nothing, so theye really only see their own stuff)
888 # session (probably nothing, so theye really only see their own stuff)
889
889
890 # The user dict must *always* have a __builtin__ reference to the
890 # The user dict must *always* have a __builtin__ reference to the
891 # Python standard __builtin__ namespace, which must be imported.
891 # Python standard __builtin__ namespace, which must be imported.
892 # This is so that certain operations in prompt evaluation can be
892 # This is so that certain operations in prompt evaluation can be
893 # reliably executed with builtins. Note that we can NOT use
893 # reliably executed with builtins. Note that we can NOT use
894 # __builtins__ (note the 's'), because that can either be a dict or a
894 # __builtins__ (note the 's'), because that can either be a dict or a
895 # module, and can even mutate at runtime, depending on the context
895 # module, and can even mutate at runtime, depending on the context
896 # (Python makes no guarantees on it). In contrast, __builtin__ is
896 # (Python makes no guarantees on it). In contrast, __builtin__ is
897 # always a module object, though it must be explicitly imported.
897 # always a module object, though it must be explicitly imported.
898
898
899 # For more details:
899 # For more details:
900 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
900 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
901 ns = dict(__builtin__ = __builtin__)
901 ns = dict(__builtin__ = __builtin__)
902
902
903 # Put 'help' in the user namespace
903 # Put 'help' in the user namespace
904 try:
904 try:
905 from site import _Helper
905 from site import _Helper
906 ns['help'] = _Helper()
906 ns['help'] = _Helper()
907 except ImportError:
907 except ImportError:
908 warn('help() not available - check site.py')
908 warn('help() not available - check site.py')
909
909
910 # make global variables for user access to the histories
910 # make global variables for user access to the histories
911 ns['_ih'] = self.input_hist
911 ns['_ih'] = self.input_hist
912 ns['_oh'] = self.output_hist
912 ns['_oh'] = self.output_hist
913 ns['_dh'] = self.dir_hist
913 ns['_dh'] = self.dir_hist
914
914
915 ns['_sh'] = shadowns
915 ns['_sh'] = shadowns
916
916
917 # user aliases to input and output histories. These shouldn't show up
917 # user aliases to input and output histories. These shouldn't show up
918 # in %who, as they can have very large reprs.
918 # in %who, as they can have very large reprs.
919 ns['In'] = self.input_hist
919 ns['In'] = self.input_hist
920 ns['Out'] = self.output_hist
920 ns['Out'] = self.output_hist
921
921
922 # Store myself as the public api!!!
922 # Store myself as the public api!!!
923 ns['get_ipython'] = self.get_ipython
923 ns['get_ipython'] = self.get_ipython
924
924
925 # Sync what we've added so far to user_ns_hidden so these aren't seen
925 # Sync what we've added so far to user_ns_hidden so these aren't seen
926 # by %who
926 # by %who
927 self.user_ns_hidden.update(ns)
927 self.user_ns_hidden.update(ns)
928
928
929 # Anything put into ns now would show up in %who. Think twice before
929 # Anything put into ns now would show up in %who. Think twice before
930 # putting anything here, as we really want %who to show the user their
930 # putting anything here, as we really want %who to show the user their
931 # stuff, not our variables.
931 # stuff, not our variables.
932
932
933 # Finally, update the real user's namespace
933 # Finally, update the real user's namespace
934 self.user_ns.update(ns)
934 self.user_ns.update(ns)
935
935
936
936
937 def reset(self):
937 def reset(self):
938 """Clear all internal namespaces.
938 """Clear all internal namespaces.
939
939
940 Note that this is much more aggressive than %reset, since it clears
940 Note that this is much more aggressive than %reset, since it clears
941 fully all namespaces, as well as all input/output lists.
941 fully all namespaces, as well as all input/output lists.
942 """
942 """
943 for ns in self.ns_refs_table:
943 for ns in self.ns_refs_table:
944 ns.clear()
944 ns.clear()
945
945
946 self.alias_manager.clear_aliases()
946 self.alias_manager.clear_aliases()
947
947
948 # Clear input and output histories
948 # Clear input and output histories
949 self.input_hist[:] = []
949 self.input_hist[:] = []
950 self.input_hist_raw[:] = []
950 self.input_hist_raw[:] = []
951 self.output_hist.clear()
951 self.output_hist.clear()
952
952
953 # Restore the user namespaces to minimal usability
953 # Restore the user namespaces to minimal usability
954 self.init_user_ns()
954 self.init_user_ns()
955
955
956 # Restore the default and user aliases
956 # Restore the default and user aliases
957 self.alias_manager.init_aliases()
957 self.alias_manager.init_aliases()
958
958
959 def reset_selective(self, regex=None):
959 def reset_selective(self, regex=None):
960 """Clear selective variables from internal namespaces based on a specified regular expression.
960 """Clear selective variables from internal namespaces based on a specified regular expression.
961
961
962 Parameters
962 Parameters
963 ----------
963 ----------
964 regex : string or compiled pattern, optional
964 regex : string or compiled pattern, optional
965 A regular expression pattern that will be used in searching variable names in the users
965 A regular expression pattern that will be used in searching variable names in the users
966 namespaces.
966 namespaces.
967 """
967 """
968 if regex is not None:
968 if regex is not None:
969 try:
969 try:
970 m = re.compile(regex)
970 m = re.compile(regex)
971 except TypeError:
971 except TypeError:
972 raise TypeError('regex must be a string or compiled pattern')
972 raise TypeError('regex must be a string or compiled pattern')
973 # Search for keys in each namespace that match the given regex
973 # Search for keys in each namespace that match the given regex
974 # If a match is found, delete the key/value pair.
974 # If a match is found, delete the key/value pair.
975 for ns in self.ns_refs_table:
975 for ns in self.ns_refs_table:
976 for var in ns:
976 for var in ns:
977 if m.search(var):
977 if m.search(var):
978 del ns[var]
978 del ns[var]
979
979
980 def push(self, variables, interactive=True):
980 def push(self, variables, interactive=True):
981 """Inject a group of variables into the IPython user namespace.
981 """Inject a group of variables into the IPython user namespace.
982
982
983 Parameters
983 Parameters
984 ----------
984 ----------
985 variables : dict, str or list/tuple of str
985 variables : dict, str or list/tuple of str
986 The variables to inject into the user's namespace. If a dict,
986 The variables to inject into the user's namespace. If a dict,
987 a simple update is done. If a str, the string is assumed to
987 a simple update is done. If a str, the string is assumed to
988 have variable names separated by spaces. A list/tuple of str
988 have variable names separated by spaces. A list/tuple of str
989 can also be used to give the variable names. If just the variable
989 can also be used to give the variable names. If just the variable
990 names are give (list/tuple/str) then the variable values looked
990 names are give (list/tuple/str) then the variable values looked
991 up in the callers frame.
991 up in the callers frame.
992 interactive : bool
992 interactive : bool
993 If True (default), the variables will be listed with the ``who``
993 If True (default), the variables will be listed with the ``who``
994 magic.
994 magic.
995 """
995 """
996 vdict = None
996 vdict = None
997
997
998 # We need a dict of name/value pairs to do namespace updates.
998 # We need a dict of name/value pairs to do namespace updates.
999 if isinstance(variables, dict):
999 if isinstance(variables, dict):
1000 vdict = variables
1000 vdict = variables
1001 elif isinstance(variables, (basestring, list, tuple)):
1001 elif isinstance(variables, (basestring, list, tuple)):
1002 if isinstance(variables, basestring):
1002 if isinstance(variables, basestring):
1003 vlist = variables.split()
1003 vlist = variables.split()
1004 else:
1004 else:
1005 vlist = variables
1005 vlist = variables
1006 vdict = {}
1006 vdict = {}
1007 cf = sys._getframe(1)
1007 cf = sys._getframe(1)
1008 for name in vlist:
1008 for name in vlist:
1009 try:
1009 try:
1010 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1010 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1011 except:
1011 except:
1012 print ('Could not get variable %s from %s' %
1012 print ('Could not get variable %s from %s' %
1013 (name,cf.f_code.co_name))
1013 (name,cf.f_code.co_name))
1014 else:
1014 else:
1015 raise ValueError('variables must be a dict/str/list/tuple')
1015 raise ValueError('variables must be a dict/str/list/tuple')
1016
1016
1017 # Propagate variables to user namespace
1017 # Propagate variables to user namespace
1018 self.user_ns.update(vdict)
1018 self.user_ns.update(vdict)
1019
1019
1020 # And configure interactive visibility
1020 # And configure interactive visibility
1021 config_ns = self.user_ns_hidden
1021 config_ns = self.user_ns_hidden
1022 if interactive:
1022 if interactive:
1023 for name, val in vdict.iteritems():
1023 for name, val in vdict.iteritems():
1024 config_ns.pop(name, None)
1024 config_ns.pop(name, None)
1025 else:
1025 else:
1026 for name,val in vdict.iteritems():
1026 for name,val in vdict.iteritems():
1027 config_ns[name] = val
1027 config_ns[name] = val
1028
1028
1029 #-------------------------------------------------------------------------
1029 #-------------------------------------------------------------------------
1030 # Things related to object introspection
1030 # Things related to object introspection
1031 #-------------------------------------------------------------------------
1031 #-------------------------------------------------------------------------
1032 def _ofind(self, oname, namespaces=None):
1032 def _ofind(self, oname, namespaces=None):
1033 """Find an object in the available namespaces.
1033 """Find an object in the available namespaces.
1034
1034
1035 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1035 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1036
1036
1037 Has special code to detect magic functions.
1037 Has special code to detect magic functions.
1038 """
1038 """
1039 #oname = oname.strip()
1039 #oname = oname.strip()
1040 #print '1- oname: <%r>' % oname # dbg
1040 #print '1- oname: <%r>' % oname # dbg
1041 try:
1041 try:
1042 oname = oname.strip().encode('ascii')
1042 oname = oname.strip().encode('ascii')
1043 #print '2- oname: <%r>' % oname # dbg
1043 #print '2- oname: <%r>' % oname # dbg
1044 except UnicodeEncodeError:
1044 except UnicodeEncodeError:
1045 print 'Python identifiers can only contain ascii characters.'
1045 print 'Python identifiers can only contain ascii characters.'
1046 return dict(found=False)
1046 return dict(found=False)
1047
1047
1048 alias_ns = None
1048 alias_ns = None
1049 if namespaces is None:
1049 if namespaces is None:
1050 # Namespaces to search in:
1050 # Namespaces to search in:
1051 # Put them in a list. The order is important so that we
1051 # Put them in a list. The order is important so that we
1052 # find things in the same order that Python finds them.
1052 # find things in the same order that Python finds them.
1053 namespaces = [ ('Interactive', self.user_ns),
1053 namespaces = [ ('Interactive', self.user_ns),
1054 ('IPython internal', self.internal_ns),
1054 ('IPython internal', self.internal_ns),
1055 ('Python builtin', __builtin__.__dict__),
1055 ('Python builtin', __builtin__.__dict__),
1056 ('Alias', self.alias_manager.alias_table),
1056 ('Alias', self.alias_manager.alias_table),
1057 ]
1057 ]
1058 alias_ns = self.alias_manager.alias_table
1058 alias_ns = self.alias_manager.alias_table
1059
1059
1060 # initialize results to 'null'
1060 # initialize results to 'null'
1061 found = False; obj = None; ospace = None; ds = None;
1061 found = False; obj = None; ospace = None; ds = None;
1062 ismagic = False; isalias = False; parent = None
1062 ismagic = False; isalias = False; parent = None
1063
1063
1064 # We need to special-case 'print', which as of python2.6 registers as a
1064 # We need to special-case 'print', which as of python2.6 registers as a
1065 # function but should only be treated as one if print_function was
1065 # function but should only be treated as one if print_function was
1066 # loaded with a future import. In this case, just bail.
1066 # loaded with a future import. In this case, just bail.
1067 if (oname == 'print' and not (self.compile.compiler.flags &
1067 if (oname == 'print' and not (self.compile.compiler.flags &
1068 __future__.CO_FUTURE_PRINT_FUNCTION)):
1068 __future__.CO_FUTURE_PRINT_FUNCTION)):
1069 return {'found':found, 'obj':obj, 'namespace':ospace,
1069 return {'found':found, 'obj':obj, 'namespace':ospace,
1070 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1070 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1071
1071
1072 # Look for the given name by splitting it in parts. If the head is
1072 # Look for the given name by splitting it in parts. If the head is
1073 # found, then we look for all the remaining parts as members, and only
1073 # found, then we look for all the remaining parts as members, and only
1074 # declare success if we can find them all.
1074 # declare success if we can find them all.
1075 oname_parts = oname.split('.')
1075 oname_parts = oname.split('.')
1076 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1076 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1077 for nsname,ns in namespaces:
1077 for nsname,ns in namespaces:
1078 try:
1078 try:
1079 obj = ns[oname_head]
1079 obj = ns[oname_head]
1080 except KeyError:
1080 except KeyError:
1081 continue
1081 continue
1082 else:
1082 else:
1083 #print 'oname_rest:', oname_rest # dbg
1083 #print 'oname_rest:', oname_rest # dbg
1084 for part in oname_rest:
1084 for part in oname_rest:
1085 try:
1085 try:
1086 parent = obj
1086 parent = obj
1087 obj = getattr(obj,part)
1087 obj = getattr(obj,part)
1088 except:
1088 except:
1089 # Blanket except b/c some badly implemented objects
1089 # Blanket except b/c some badly implemented objects
1090 # allow __getattr__ to raise exceptions other than
1090 # allow __getattr__ to raise exceptions other than
1091 # AttributeError, which then crashes IPython.
1091 # AttributeError, which then crashes IPython.
1092 break
1092 break
1093 else:
1093 else:
1094 # If we finish the for loop (no break), we got all members
1094 # If we finish the for loop (no break), we got all members
1095 found = True
1095 found = True
1096 ospace = nsname
1096 ospace = nsname
1097 if ns == alias_ns:
1097 if ns == alias_ns:
1098 isalias = True
1098 isalias = True
1099 break # namespace loop
1099 break # namespace loop
1100
1100
1101 # Try to see if it's magic
1101 # Try to see if it's magic
1102 if not found:
1102 if not found:
1103 if oname.startswith(ESC_MAGIC):
1103 if oname.startswith(ESC_MAGIC):
1104 oname = oname[1:]
1104 oname = oname[1:]
1105 obj = getattr(self,'magic_'+oname,None)
1105 obj = getattr(self,'magic_'+oname,None)
1106 if obj is not None:
1106 if obj is not None:
1107 found = True
1107 found = True
1108 ospace = 'IPython internal'
1108 ospace = 'IPython internal'
1109 ismagic = True
1109 ismagic = True
1110
1110
1111 # Last try: special-case some literals like '', [], {}, etc:
1111 # Last try: special-case some literals like '', [], {}, etc:
1112 if not found and oname_head in ["''",'""','[]','{}','()']:
1112 if not found and oname_head in ["''",'""','[]','{}','()']:
1113 obj = eval(oname_head)
1113 obj = eval(oname_head)
1114 found = True
1114 found = True
1115 ospace = 'Interactive'
1115 ospace = 'Interactive'
1116
1116
1117 return {'found':found, 'obj':obj, 'namespace':ospace,
1117 return {'found':found, 'obj':obj, 'namespace':ospace,
1118 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1118 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1119
1119
1120 def _ofind_property(self, oname, info):
1120 def _ofind_property(self, oname, info):
1121 """Second part of object finding, to look for property details."""
1121 """Second part of object finding, to look for property details."""
1122 if info.found:
1122 if info.found:
1123 # Get the docstring of the class property if it exists.
1123 # Get the docstring of the class property if it exists.
1124 path = oname.split('.')
1124 path = oname.split('.')
1125 root = '.'.join(path[:-1])
1125 root = '.'.join(path[:-1])
1126 if info.parent is not None:
1126 if info.parent is not None:
1127 try:
1127 try:
1128 target = getattr(info.parent, '__class__')
1128 target = getattr(info.parent, '__class__')
1129 # The object belongs to a class instance.
1129 # The object belongs to a class instance.
1130 try:
1130 try:
1131 target = getattr(target, path[-1])
1131 target = getattr(target, path[-1])
1132 # The class defines the object.
1132 # The class defines the object.
1133 if isinstance(target, property):
1133 if isinstance(target, property):
1134 oname = root + '.__class__.' + path[-1]
1134 oname = root + '.__class__.' + path[-1]
1135 info = Struct(self._ofind(oname))
1135 info = Struct(self._ofind(oname))
1136 except AttributeError: pass
1136 except AttributeError: pass
1137 except AttributeError: pass
1137 except AttributeError: pass
1138
1138
1139 # We return either the new info or the unmodified input if the object
1139 # We return either the new info or the unmodified input if the object
1140 # hadn't been found
1140 # hadn't been found
1141 return info
1141 return info
1142
1142
1143 def _object_find(self, oname, namespaces=None):
1143 def _object_find(self, oname, namespaces=None):
1144 """Find an object and return a struct with info about it."""
1144 """Find an object and return a struct with info about it."""
1145 inf = Struct(self._ofind(oname, namespaces))
1145 inf = Struct(self._ofind(oname, namespaces))
1146 return Struct(self._ofind_property(oname, inf))
1146 return Struct(self._ofind_property(oname, inf))
1147
1147
1148 def _inspect(self, meth, oname, namespaces=None, **kw):
1148 def _inspect(self, meth, oname, namespaces=None, **kw):
1149 """Generic interface to the inspector system.
1149 """Generic interface to the inspector system.
1150
1150
1151 This function is meant to be called by pdef, pdoc & friends."""
1151 This function is meant to be called by pdef, pdoc & friends."""
1152 info = self._object_find(oname)
1152 info = self._object_find(oname)
1153 if info.found:
1153 if info.found:
1154 pmethod = getattr(self.inspector, meth)
1154 pmethod = getattr(self.inspector, meth)
1155 formatter = format_screen if info.ismagic else None
1155 formatter = format_screen if info.ismagic else None
1156 if meth == 'pdoc':
1156 if meth == 'pdoc':
1157 pmethod(info.obj, oname, formatter)
1157 pmethod(info.obj, oname, formatter)
1158 elif meth == 'pinfo':
1158 elif meth == 'pinfo':
1159 pmethod(info.obj, oname, formatter, info, **kw)
1159 pmethod(info.obj, oname, formatter, info, **kw)
1160 else:
1160 else:
1161 pmethod(info.obj, oname)
1161 pmethod(info.obj, oname)
1162 else:
1162 else:
1163 print 'Object `%s` not found.' % oname
1163 print 'Object `%s` not found.' % oname
1164 return 'not found' # so callers can take other action
1164 return 'not found' # so callers can take other action
1165
1165
1166 def object_inspect(self, oname):
1166 def object_inspect(self, oname):
1167 info = self._object_find(oname)
1167 info = self._object_find(oname)
1168 if info.found:
1169 return self.inspector.info(info.obj, info=info)
1170 else:
1171 return {}
1168
1172
1169 #-------------------------------------------------------------------------
1173 #-------------------------------------------------------------------------
1170 # Things related to history management
1174 # Things related to history management
1171 #-------------------------------------------------------------------------
1175 #-------------------------------------------------------------------------
1172
1176
1173 def init_history(self):
1177 def init_history(self):
1174 # List of input with multi-line handling.
1178 # List of input with multi-line handling.
1175 self.input_hist = InputList()
1179 self.input_hist = InputList()
1176 # This one will hold the 'raw' input history, without any
1180 # This one will hold the 'raw' input history, without any
1177 # pre-processing. This will allow users to retrieve the input just as
1181 # pre-processing. This will allow users to retrieve the input just as
1178 # it was exactly typed in by the user, with %hist -r.
1182 # it was exactly typed in by the user, with %hist -r.
1179 self.input_hist_raw = InputList()
1183 self.input_hist_raw = InputList()
1180
1184
1181 # list of visited directories
1185 # list of visited directories
1182 try:
1186 try:
1183 self.dir_hist = [os.getcwd()]
1187 self.dir_hist = [os.getcwd()]
1184 except OSError:
1188 except OSError:
1185 self.dir_hist = []
1189 self.dir_hist = []
1186
1190
1187 # dict of output history
1191 # dict of output history
1188 self.output_hist = {}
1192 self.output_hist = {}
1189
1193
1190 # Now the history file
1194 # Now the history file
1191 if self.profile:
1195 if self.profile:
1192 histfname = 'history-%s' % self.profile
1196 histfname = 'history-%s' % self.profile
1193 else:
1197 else:
1194 histfname = 'history'
1198 histfname = 'history'
1195 self.histfile = os.path.join(self.ipython_dir, histfname)
1199 self.histfile = os.path.join(self.ipython_dir, histfname)
1196
1200
1197 # Fill the history zero entry, user counter starts at 1
1201 # Fill the history zero entry, user counter starts at 1
1198 self.input_hist.append('\n')
1202 self.input_hist.append('\n')
1199 self.input_hist_raw.append('\n')
1203 self.input_hist_raw.append('\n')
1200
1204
1201 def init_shadow_hist(self):
1205 def init_shadow_hist(self):
1202 try:
1206 try:
1203 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1207 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1204 except exceptions.UnicodeDecodeError:
1208 except exceptions.UnicodeDecodeError:
1205 print "Your ipython_dir can't be decoded to unicode!"
1209 print "Your ipython_dir can't be decoded to unicode!"
1206 print "Please set HOME environment variable to something that"
1210 print "Please set HOME environment variable to something that"
1207 print r"only has ASCII characters, e.g. c:\home"
1211 print r"only has ASCII characters, e.g. c:\home"
1208 print "Now it is", self.ipython_dir
1212 print "Now it is", self.ipython_dir
1209 sys.exit()
1213 sys.exit()
1210 self.shadowhist = ipcorehist.ShadowHist(self.db)
1214 self.shadowhist = ipcorehist.ShadowHist(self.db)
1211
1215
1212 def savehist(self):
1216 def savehist(self):
1213 """Save input history to a file (via readline library)."""
1217 """Save input history to a file (via readline library)."""
1214
1218
1215 try:
1219 try:
1216 self.readline.write_history_file(self.histfile)
1220 self.readline.write_history_file(self.histfile)
1217 except:
1221 except:
1218 print 'Unable to save IPython command history to file: ' + \
1222 print 'Unable to save IPython command history to file: ' + \
1219 `self.histfile`
1223 `self.histfile`
1220
1224
1221 def reloadhist(self):
1225 def reloadhist(self):
1222 """Reload the input history from disk file."""
1226 """Reload the input history from disk file."""
1223
1227
1224 try:
1228 try:
1225 self.readline.clear_history()
1229 self.readline.clear_history()
1226 self.readline.read_history_file(self.shell.histfile)
1230 self.readline.read_history_file(self.shell.histfile)
1227 except AttributeError:
1231 except AttributeError:
1228 pass
1232 pass
1229
1233
1230 def history_saving_wrapper(self, func):
1234 def history_saving_wrapper(self, func):
1231 """ Wrap func for readline history saving
1235 """ Wrap func for readline history saving
1232
1236
1233 Convert func into callable that saves & restores
1237 Convert func into callable that saves & restores
1234 history around the call """
1238 history around the call """
1235
1239
1236 if self.has_readline:
1240 if self.has_readline:
1237 from IPython.utils import rlineimpl as readline
1241 from IPython.utils import rlineimpl as readline
1238 else:
1242 else:
1239 return func
1243 return func
1240
1244
1241 def wrapper():
1245 def wrapper():
1242 self.savehist()
1246 self.savehist()
1243 try:
1247 try:
1244 func()
1248 func()
1245 finally:
1249 finally:
1246 readline.read_history_file(self.histfile)
1250 readline.read_history_file(self.histfile)
1247 return wrapper
1251 return wrapper
1248
1252
1249 def get_history(self, index=None, raw=False, output=True):
1253 def get_history(self, index=None, raw=False, output=True):
1250 """Get the history list.
1254 """Get the history list.
1251
1255
1252 Get the input and output history.
1256 Get the input and output history.
1253
1257
1254 Parameters
1258 Parameters
1255 ----------
1259 ----------
1256 index : n or (n1, n2) or None
1260 index : n or (n1, n2) or None
1257 If n, then the last entries. If a tuple, then all in
1261 If n, then the last entries. If a tuple, then all in
1258 range(n1, n2). If None, then all entries. Raises IndexError if
1262 range(n1, n2). If None, then all entries. Raises IndexError if
1259 the format of index is incorrect.
1263 the format of index is incorrect.
1260 raw : bool
1264 raw : bool
1261 If True, return the raw input.
1265 If True, return the raw input.
1262 output : bool
1266 output : bool
1263 If True, then return the output as well.
1267 If True, then return the output as well.
1264
1268
1265 Returns
1269 Returns
1266 -------
1270 -------
1267 If output is True, then return a dict of tuples, keyed by the prompt
1271 If output is True, then return a dict of tuples, keyed by the prompt
1268 numbers and with values of (input, output). If output is False, then
1272 numbers and with values of (input, output). If output is False, then
1269 a dict, keyed by the prompt number with the values of input. Raises
1273 a dict, keyed by the prompt number with the values of input. Raises
1270 IndexError if no history is found.
1274 IndexError if no history is found.
1271 """
1275 """
1272 if raw:
1276 if raw:
1273 input_hist = self.input_hist_raw
1277 input_hist = self.input_hist_raw
1274 else:
1278 else:
1275 input_hist = self.input_hist
1279 input_hist = self.input_hist
1276 if output:
1280 if output:
1277 output_hist = self.user_ns['Out']
1281 output_hist = self.user_ns['Out']
1278 n = len(input_hist)
1282 n = len(input_hist)
1279 if index is None:
1283 if index is None:
1280 start=0; stop=n
1284 start=0; stop=n
1281 elif isinstance(index, int):
1285 elif isinstance(index, int):
1282 start=n-index; stop=n
1286 start=n-index; stop=n
1283 elif isinstance(index, tuple) and len(index) == 2:
1287 elif isinstance(index, tuple) and len(index) == 2:
1284 start=index[0]; stop=index[1]
1288 start=index[0]; stop=index[1]
1285 else:
1289 else:
1286 raise IndexError('Not a valid index for the input history: %r' % index)
1290 raise IndexError('Not a valid index for the input history: %r' % index)
1287 hist = {}
1291 hist = {}
1288 for i in range(start, stop):
1292 for i in range(start, stop):
1289 if output:
1293 if output:
1290 hist[i] = (input_hist[i], output_hist.get(i))
1294 hist[i] = (input_hist[i], output_hist.get(i))
1291 else:
1295 else:
1292 hist[i] = input_hist[i]
1296 hist[i] = input_hist[i]
1293 if len(hist)==0:
1297 if len(hist)==0:
1294 raise IndexError('No history for range of indices: %r' % index)
1298 raise IndexError('No history for range of indices: %r' % index)
1295 return hist
1299 return hist
1296
1300
1297 #-------------------------------------------------------------------------
1301 #-------------------------------------------------------------------------
1298 # Things related to exception handling and tracebacks (not debugging)
1302 # Things related to exception handling and tracebacks (not debugging)
1299 #-------------------------------------------------------------------------
1303 #-------------------------------------------------------------------------
1300
1304
1301 def init_traceback_handlers(self, custom_exceptions):
1305 def init_traceback_handlers(self, custom_exceptions):
1302 # Syntax error handler.
1306 # Syntax error handler.
1303 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1307 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1304
1308
1305 # The interactive one is initialized with an offset, meaning we always
1309 # The interactive one is initialized with an offset, meaning we always
1306 # want to remove the topmost item in the traceback, which is our own
1310 # want to remove the topmost item in the traceback, which is our own
1307 # internal code. Valid modes: ['Plain','Context','Verbose']
1311 # internal code. Valid modes: ['Plain','Context','Verbose']
1308 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1312 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1309 color_scheme='NoColor',
1313 color_scheme='NoColor',
1310 tb_offset = 1)
1314 tb_offset = 1)
1311
1315
1312 # The instance will store a pointer to the system-wide exception hook,
1316 # The instance will store a pointer to the system-wide exception hook,
1313 # so that runtime code (such as magics) can access it. This is because
1317 # so that runtime code (such as magics) can access it. This is because
1314 # during the read-eval loop, it may get temporarily overwritten.
1318 # during the read-eval loop, it may get temporarily overwritten.
1315 self.sys_excepthook = sys.excepthook
1319 self.sys_excepthook = sys.excepthook
1316
1320
1317 # and add any custom exception handlers the user may have specified
1321 # and add any custom exception handlers the user may have specified
1318 self.set_custom_exc(*custom_exceptions)
1322 self.set_custom_exc(*custom_exceptions)
1319
1323
1320 # Set the exception mode
1324 # Set the exception mode
1321 self.InteractiveTB.set_mode(mode=self.xmode)
1325 self.InteractiveTB.set_mode(mode=self.xmode)
1322
1326
1323 def set_custom_exc(self, exc_tuple, handler):
1327 def set_custom_exc(self, exc_tuple, handler):
1324 """set_custom_exc(exc_tuple,handler)
1328 """set_custom_exc(exc_tuple,handler)
1325
1329
1326 Set a custom exception handler, which will be called if any of the
1330 Set a custom exception handler, which will be called if any of the
1327 exceptions in exc_tuple occur in the mainloop (specifically, in the
1331 exceptions in exc_tuple occur in the mainloop (specifically, in the
1328 runcode() method.
1332 runcode() method.
1329
1333
1330 Inputs:
1334 Inputs:
1331
1335
1332 - exc_tuple: a *tuple* of valid exceptions to call the defined
1336 - exc_tuple: a *tuple* of valid exceptions to call the defined
1333 handler for. It is very important that you use a tuple, and NOT A
1337 handler for. It is very important that you use a tuple, and NOT A
1334 LIST here, because of the way Python's except statement works. If
1338 LIST here, because of the way Python's except statement works. If
1335 you only want to trap a single exception, use a singleton tuple:
1339 you only want to trap a single exception, use a singleton tuple:
1336
1340
1337 exc_tuple == (MyCustomException,)
1341 exc_tuple == (MyCustomException,)
1338
1342
1339 - handler: this must be defined as a function with the following
1343 - handler: this must be defined as a function with the following
1340 basic interface::
1344 basic interface::
1341
1345
1342 def my_handler(self, etype, value, tb, tb_offset=None)
1346 def my_handler(self, etype, value, tb, tb_offset=None)
1343 ...
1347 ...
1344 # The return value must be
1348 # The return value must be
1345 return structured_traceback
1349 return structured_traceback
1346
1350
1347 This will be made into an instance method (via new.instancemethod)
1351 This will be made into an instance method (via new.instancemethod)
1348 of IPython itself, and it will be called if any of the exceptions
1352 of IPython itself, and it will be called if any of the exceptions
1349 listed in the exc_tuple are caught. If the handler is None, an
1353 listed in the exc_tuple are caught. If the handler is None, an
1350 internal basic one is used, which just prints basic info.
1354 internal basic one is used, which just prints basic info.
1351
1355
1352 WARNING: by putting in your own exception handler into IPython's main
1356 WARNING: by putting in your own exception handler into IPython's main
1353 execution loop, you run a very good chance of nasty crashes. This
1357 execution loop, you run a very good chance of nasty crashes. This
1354 facility should only be used if you really know what you are doing."""
1358 facility should only be used if you really know what you are doing."""
1355
1359
1356 assert type(exc_tuple)==type(()) , \
1360 assert type(exc_tuple)==type(()) , \
1357 "The custom exceptions must be given AS A TUPLE."
1361 "The custom exceptions must be given AS A TUPLE."
1358
1362
1359 def dummy_handler(self,etype,value,tb):
1363 def dummy_handler(self,etype,value,tb):
1360 print '*** Simple custom exception handler ***'
1364 print '*** Simple custom exception handler ***'
1361 print 'Exception type :',etype
1365 print 'Exception type :',etype
1362 print 'Exception value:',value
1366 print 'Exception value:',value
1363 print 'Traceback :',tb
1367 print 'Traceback :',tb
1364 print 'Source code :','\n'.join(self.buffer)
1368 print 'Source code :','\n'.join(self.buffer)
1365
1369
1366 if handler is None: handler = dummy_handler
1370 if handler is None: handler = dummy_handler
1367
1371
1368 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1372 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1369 self.custom_exceptions = exc_tuple
1373 self.custom_exceptions = exc_tuple
1370
1374
1371 def excepthook(self, etype, value, tb):
1375 def excepthook(self, etype, value, tb):
1372 """One more defense for GUI apps that call sys.excepthook.
1376 """One more defense for GUI apps that call sys.excepthook.
1373
1377
1374 GUI frameworks like wxPython trap exceptions and call
1378 GUI frameworks like wxPython trap exceptions and call
1375 sys.excepthook themselves. I guess this is a feature that
1379 sys.excepthook themselves. I guess this is a feature that
1376 enables them to keep running after exceptions that would
1380 enables them to keep running after exceptions that would
1377 otherwise kill their mainloop. This is a bother for IPython
1381 otherwise kill their mainloop. This is a bother for IPython
1378 which excepts to catch all of the program exceptions with a try:
1382 which excepts to catch all of the program exceptions with a try:
1379 except: statement.
1383 except: statement.
1380
1384
1381 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1385 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1382 any app directly invokes sys.excepthook, it will look to the user like
1386 any app directly invokes sys.excepthook, it will look to the user like
1383 IPython crashed. In order to work around this, we can disable the
1387 IPython crashed. In order to work around this, we can disable the
1384 CrashHandler and replace it with this excepthook instead, which prints a
1388 CrashHandler and replace it with this excepthook instead, which prints a
1385 regular traceback using our InteractiveTB. In this fashion, apps which
1389 regular traceback using our InteractiveTB. In this fashion, apps which
1386 call sys.excepthook will generate a regular-looking exception from
1390 call sys.excepthook will generate a regular-looking exception from
1387 IPython, and the CrashHandler will only be triggered by real IPython
1391 IPython, and the CrashHandler will only be triggered by real IPython
1388 crashes.
1392 crashes.
1389
1393
1390 This hook should be used sparingly, only in places which are not likely
1394 This hook should be used sparingly, only in places which are not likely
1391 to be true IPython errors.
1395 to be true IPython errors.
1392 """
1396 """
1393 self.showtraceback((etype,value,tb),tb_offset=0)
1397 self.showtraceback((etype,value,tb),tb_offset=0)
1394
1398
1395 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1399 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1396 exception_only=False):
1400 exception_only=False):
1397 """Display the exception that just occurred.
1401 """Display the exception that just occurred.
1398
1402
1399 If nothing is known about the exception, this is the method which
1403 If nothing is known about the exception, this is the method which
1400 should be used throughout the code for presenting user tracebacks,
1404 should be used throughout the code for presenting user tracebacks,
1401 rather than directly invoking the InteractiveTB object.
1405 rather than directly invoking the InteractiveTB object.
1402
1406
1403 A specific showsyntaxerror() also exists, but this method can take
1407 A specific showsyntaxerror() also exists, but this method can take
1404 care of calling it if needed, so unless you are explicitly catching a
1408 care of calling it if needed, so unless you are explicitly catching a
1405 SyntaxError exception, don't try to analyze the stack manually and
1409 SyntaxError exception, don't try to analyze the stack manually and
1406 simply call this method."""
1410 simply call this method."""
1407
1411
1408 try:
1412 try:
1409 if exc_tuple is None:
1413 if exc_tuple is None:
1410 etype, value, tb = sys.exc_info()
1414 etype, value, tb = sys.exc_info()
1411 else:
1415 else:
1412 etype, value, tb = exc_tuple
1416 etype, value, tb = exc_tuple
1413
1417
1414 if etype is None:
1418 if etype is None:
1415 if hasattr(sys, 'last_type'):
1419 if hasattr(sys, 'last_type'):
1416 etype, value, tb = sys.last_type, sys.last_value, \
1420 etype, value, tb = sys.last_type, sys.last_value, \
1417 sys.last_traceback
1421 sys.last_traceback
1418 else:
1422 else:
1419 self.write_err('No traceback available to show.\n')
1423 self.write_err('No traceback available to show.\n')
1420 return
1424 return
1421
1425
1422 if etype is SyntaxError:
1426 if etype is SyntaxError:
1423 # Though this won't be called by syntax errors in the input
1427 # Though this won't be called by syntax errors in the input
1424 # line, there may be SyntaxError cases whith imported code.
1428 # line, there may be SyntaxError cases whith imported code.
1425 self.showsyntaxerror(filename)
1429 self.showsyntaxerror(filename)
1426 elif etype is UsageError:
1430 elif etype is UsageError:
1427 print "UsageError:", value
1431 print "UsageError:", value
1428 else:
1432 else:
1429 # WARNING: these variables are somewhat deprecated and not
1433 # WARNING: these variables are somewhat deprecated and not
1430 # necessarily safe to use in a threaded environment, but tools
1434 # necessarily safe to use in a threaded environment, but tools
1431 # like pdb depend on their existence, so let's set them. If we
1435 # like pdb depend on their existence, so let's set them. If we
1432 # find problems in the field, we'll need to revisit their use.
1436 # find problems in the field, we'll need to revisit their use.
1433 sys.last_type = etype
1437 sys.last_type = etype
1434 sys.last_value = value
1438 sys.last_value = value
1435 sys.last_traceback = tb
1439 sys.last_traceback = tb
1436
1440
1437 if etype in self.custom_exceptions:
1441 if etype in self.custom_exceptions:
1438 # FIXME: Old custom traceback objects may just return a
1442 # FIXME: Old custom traceback objects may just return a
1439 # string, in that case we just put it into a list
1443 # string, in that case we just put it into a list
1440 stb = self.CustomTB(etype, value, tb, tb_offset)
1444 stb = self.CustomTB(etype, value, tb, tb_offset)
1441 if isinstance(ctb, basestring):
1445 if isinstance(ctb, basestring):
1442 stb = [stb]
1446 stb = [stb]
1443 else:
1447 else:
1444 if exception_only:
1448 if exception_only:
1445 stb = ['An exception has occurred, use %tb to see '
1449 stb = ['An exception has occurred, use %tb to see '
1446 'the full traceback.\n']
1450 'the full traceback.\n']
1447 stb.extend(self.InteractiveTB.get_exception_only(etype,
1451 stb.extend(self.InteractiveTB.get_exception_only(etype,
1448 value))
1452 value))
1449 else:
1453 else:
1450 stb = self.InteractiveTB.structured_traceback(etype,
1454 stb = self.InteractiveTB.structured_traceback(etype,
1451 value, tb, tb_offset=tb_offset)
1455 value, tb, tb_offset=tb_offset)
1452 # FIXME: the pdb calling should be done by us, not by
1456 # FIXME: the pdb calling should be done by us, not by
1453 # the code computing the traceback.
1457 # the code computing the traceback.
1454 if self.InteractiveTB.call_pdb:
1458 if self.InteractiveTB.call_pdb:
1455 # pdb mucks up readline, fix it back
1459 # pdb mucks up readline, fix it back
1456 self.set_completer()
1460 self.set_completer()
1457
1461
1458 # Actually show the traceback
1462 # Actually show the traceback
1459 self._showtraceback(etype, value, stb)
1463 self._showtraceback(etype, value, stb)
1460
1464
1461 except KeyboardInterrupt:
1465 except KeyboardInterrupt:
1462 self.write_err("\nKeyboardInterrupt\n")
1466 self.write_err("\nKeyboardInterrupt\n")
1463
1467
1464 def _showtraceback(self, etype, evalue, stb):
1468 def _showtraceback(self, etype, evalue, stb):
1465 """Actually show a traceback.
1469 """Actually show a traceback.
1466
1470
1467 Subclasses may override this method to put the traceback on a different
1471 Subclasses may override this method to put the traceback on a different
1468 place, like a side channel.
1472 place, like a side channel.
1469 """
1473 """
1470 # FIXME: this should use the proper write channels, but our test suite
1474 # FIXME: this should use the proper write channels, but our test suite
1471 # relies on it coming out of stdout...
1475 # relies on it coming out of stdout...
1472 print >> sys.stdout, self.InteractiveTB.stb2text(stb)
1476 print >> sys.stdout, self.InteractiveTB.stb2text(stb)
1473
1477
1474 def showsyntaxerror(self, filename=None):
1478 def showsyntaxerror(self, filename=None):
1475 """Display the syntax error that just occurred.
1479 """Display the syntax error that just occurred.
1476
1480
1477 This doesn't display a stack trace because there isn't one.
1481 This doesn't display a stack trace because there isn't one.
1478
1482
1479 If a filename is given, it is stuffed in the exception instead
1483 If a filename is given, it is stuffed in the exception instead
1480 of what was there before (because Python's parser always uses
1484 of what was there before (because Python's parser always uses
1481 "<string>" when reading from a string).
1485 "<string>" when reading from a string).
1482 """
1486 """
1483 etype, value, last_traceback = sys.exc_info()
1487 etype, value, last_traceback = sys.exc_info()
1484
1488
1485 # See note about these variables in showtraceback() above
1489 # See note about these variables in showtraceback() above
1486 sys.last_type = etype
1490 sys.last_type = etype
1487 sys.last_value = value
1491 sys.last_value = value
1488 sys.last_traceback = last_traceback
1492 sys.last_traceback = last_traceback
1489
1493
1490 if filename and etype is SyntaxError:
1494 if filename and etype is SyntaxError:
1491 # Work hard to stuff the correct filename in the exception
1495 # Work hard to stuff the correct filename in the exception
1492 try:
1496 try:
1493 msg, (dummy_filename, lineno, offset, line) = value
1497 msg, (dummy_filename, lineno, offset, line) = value
1494 except:
1498 except:
1495 # Not the format we expect; leave it alone
1499 # Not the format we expect; leave it alone
1496 pass
1500 pass
1497 else:
1501 else:
1498 # Stuff in the right filename
1502 # Stuff in the right filename
1499 try:
1503 try:
1500 # Assume SyntaxError is a class exception
1504 # Assume SyntaxError is a class exception
1501 value = SyntaxError(msg, (filename, lineno, offset, line))
1505 value = SyntaxError(msg, (filename, lineno, offset, line))
1502 except:
1506 except:
1503 # If that failed, assume SyntaxError is a string
1507 # If that failed, assume SyntaxError is a string
1504 value = msg, (filename, lineno, offset, line)
1508 value = msg, (filename, lineno, offset, line)
1505 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1509 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1506 self._showtraceback(etype, value, stb)
1510 self._showtraceback(etype, value, stb)
1507
1511
1508 #-------------------------------------------------------------------------
1512 #-------------------------------------------------------------------------
1509 # Things related to tab completion
1513 # Things related to tab completion
1510 #-------------------------------------------------------------------------
1514 #-------------------------------------------------------------------------
1511
1515
1512 def complete(self, text, line=None, cursor_pos=None):
1516 def complete(self, text, line=None, cursor_pos=None):
1513 """Return the completed text and a list of completions.
1517 """Return the completed text and a list of completions.
1514
1518
1515 Parameters
1519 Parameters
1516 ----------
1520 ----------
1517
1521
1518 text : string
1522 text : string
1519 A string of text to be completed on. It can be given as empty and
1523 A string of text to be completed on. It can be given as empty and
1520 instead a line/position pair are given. In this case, the
1524 instead a line/position pair are given. In this case, the
1521 completer itself will split the line like readline does.
1525 completer itself will split the line like readline does.
1522
1526
1523 line : string, optional
1527 line : string, optional
1524 The complete line that text is part of.
1528 The complete line that text is part of.
1525
1529
1526 cursor_pos : int, optional
1530 cursor_pos : int, optional
1527 The position of the cursor on the input line.
1531 The position of the cursor on the input line.
1528
1532
1529 Returns
1533 Returns
1530 -------
1534 -------
1531 text : string
1535 text : string
1532 The actual text that was completed.
1536 The actual text that was completed.
1533
1537
1534 matches : list
1538 matches : list
1535 A sorted list with all possible completions.
1539 A sorted list with all possible completions.
1536
1540
1537 The optional arguments allow the completion to take more context into
1541 The optional arguments allow the completion to take more context into
1538 account, and are part of the low-level completion API.
1542 account, and are part of the low-level completion API.
1539
1543
1540 This is a wrapper around the completion mechanism, similar to what
1544 This is a wrapper around the completion mechanism, similar to what
1541 readline does at the command line when the TAB key is hit. By
1545 readline does at the command line when the TAB key is hit. By
1542 exposing it as a method, it can be used by other non-readline
1546 exposing it as a method, it can be used by other non-readline
1543 environments (such as GUIs) for text completion.
1547 environments (such as GUIs) for text completion.
1544
1548
1545 Simple usage example:
1549 Simple usage example:
1546
1550
1547 In [1]: x = 'hello'
1551 In [1]: x = 'hello'
1548
1552
1549 In [2]: _ip.complete('x.l')
1553 In [2]: _ip.complete('x.l')
1550 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1554 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1551 """
1555 """
1552
1556
1553 # Inject names into __builtin__ so we can complete on the added names.
1557 # Inject names into __builtin__ so we can complete on the added names.
1554 with self.builtin_trap:
1558 with self.builtin_trap:
1555 return self.Completer.complete(text, line, cursor_pos)
1559 return self.Completer.complete(text, line, cursor_pos)
1556
1560
1557 def set_custom_completer(self, completer, pos=0):
1561 def set_custom_completer(self, completer, pos=0):
1558 """Adds a new custom completer function.
1562 """Adds a new custom completer function.
1559
1563
1560 The position argument (defaults to 0) is the index in the completers
1564 The position argument (defaults to 0) is the index in the completers
1561 list where you want the completer to be inserted."""
1565 list where you want the completer to be inserted."""
1562
1566
1563 newcomp = new.instancemethod(completer,self.Completer,
1567 newcomp = new.instancemethod(completer,self.Completer,
1564 self.Completer.__class__)
1568 self.Completer.__class__)
1565 self.Completer.matchers.insert(pos,newcomp)
1569 self.Completer.matchers.insert(pos,newcomp)
1566
1570
1567 def set_completer(self):
1571 def set_completer(self):
1568 """Reset readline's completer to be our own."""
1572 """Reset readline's completer to be our own."""
1569 self.readline.set_completer(self.Completer.rlcomplete)
1573 self.readline.set_completer(self.Completer.rlcomplete)
1570
1574
1571 def set_completer_frame(self, frame=None):
1575 def set_completer_frame(self, frame=None):
1572 """Set the frame of the completer."""
1576 """Set the frame of the completer."""
1573 if frame:
1577 if frame:
1574 self.Completer.namespace = frame.f_locals
1578 self.Completer.namespace = frame.f_locals
1575 self.Completer.global_namespace = frame.f_globals
1579 self.Completer.global_namespace = frame.f_globals
1576 else:
1580 else:
1577 self.Completer.namespace = self.user_ns
1581 self.Completer.namespace = self.user_ns
1578 self.Completer.global_namespace = self.user_global_ns
1582 self.Completer.global_namespace = self.user_global_ns
1579
1583
1580 #-------------------------------------------------------------------------
1584 #-------------------------------------------------------------------------
1581 # Things related to readline
1585 # Things related to readline
1582 #-------------------------------------------------------------------------
1586 #-------------------------------------------------------------------------
1583
1587
1584 def init_readline(self):
1588 def init_readline(self):
1585 """Command history completion/saving/reloading."""
1589 """Command history completion/saving/reloading."""
1586
1590
1587 if self.readline_use:
1591 if self.readline_use:
1588 import IPython.utils.rlineimpl as readline
1592 import IPython.utils.rlineimpl as readline
1589
1593
1590 self.rl_next_input = None
1594 self.rl_next_input = None
1591 self.rl_do_indent = False
1595 self.rl_do_indent = False
1592
1596
1593 if not self.readline_use or not readline.have_readline:
1597 if not self.readline_use or not readline.have_readline:
1594 self.has_readline = False
1598 self.has_readline = False
1595 self.readline = None
1599 self.readline = None
1596 # Set a number of methods that depend on readline to be no-op
1600 # Set a number of methods that depend on readline to be no-op
1597 self.savehist = no_op
1601 self.savehist = no_op
1598 self.reloadhist = no_op
1602 self.reloadhist = no_op
1599 self.set_completer = no_op
1603 self.set_completer = no_op
1600 self.set_custom_completer = no_op
1604 self.set_custom_completer = no_op
1601 self.set_completer_frame = no_op
1605 self.set_completer_frame = no_op
1602 warn('Readline services not available or not loaded.')
1606 warn('Readline services not available or not loaded.')
1603 else:
1607 else:
1604 self.has_readline = True
1608 self.has_readline = True
1605 self.readline = readline
1609 self.readline = readline
1606 sys.modules['readline'] = readline
1610 sys.modules['readline'] = readline
1607 import atexit
1611 import atexit
1608 from IPython.core.completer import IPCompleter
1612 from IPython.core.completer import IPCompleter
1609 self.Completer = IPCompleter(self,
1613 self.Completer = IPCompleter(self,
1610 self.user_ns,
1614 self.user_ns,
1611 self.user_global_ns,
1615 self.user_global_ns,
1612 self.readline_omit__names,
1616 self.readline_omit__names,
1613 self.alias_manager.alias_table)
1617 self.alias_manager.alias_table)
1614 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1618 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1615 self.strdispatchers['complete_command'] = sdisp
1619 self.strdispatchers['complete_command'] = sdisp
1616 self.Completer.custom_completers = sdisp
1620 self.Completer.custom_completers = sdisp
1617 # Platform-specific configuration
1621 # Platform-specific configuration
1618 if os.name == 'nt':
1622 if os.name == 'nt':
1619 self.readline_startup_hook = readline.set_pre_input_hook
1623 self.readline_startup_hook = readline.set_pre_input_hook
1620 else:
1624 else:
1621 self.readline_startup_hook = readline.set_startup_hook
1625 self.readline_startup_hook = readline.set_startup_hook
1622
1626
1623 # Load user's initrc file (readline config)
1627 # Load user's initrc file (readline config)
1624 # Or if libedit is used, load editrc.
1628 # Or if libedit is used, load editrc.
1625 inputrc_name = os.environ.get('INPUTRC')
1629 inputrc_name = os.environ.get('INPUTRC')
1626 if inputrc_name is None:
1630 if inputrc_name is None:
1627 home_dir = get_home_dir()
1631 home_dir = get_home_dir()
1628 if home_dir is not None:
1632 if home_dir is not None:
1629 inputrc_name = '.inputrc'
1633 inputrc_name = '.inputrc'
1630 if readline.uses_libedit:
1634 if readline.uses_libedit:
1631 inputrc_name = '.editrc'
1635 inputrc_name = '.editrc'
1632 inputrc_name = os.path.join(home_dir, inputrc_name)
1636 inputrc_name = os.path.join(home_dir, inputrc_name)
1633 if os.path.isfile(inputrc_name):
1637 if os.path.isfile(inputrc_name):
1634 try:
1638 try:
1635 readline.read_init_file(inputrc_name)
1639 readline.read_init_file(inputrc_name)
1636 except:
1640 except:
1637 warn('Problems reading readline initialization file <%s>'
1641 warn('Problems reading readline initialization file <%s>'
1638 % inputrc_name)
1642 % inputrc_name)
1639
1643
1640 # save this in sys so embedded copies can restore it properly
1644 # save this in sys so embedded copies can restore it properly
1641 sys.ipcompleter = self.Completer.rlcomplete
1645 sys.ipcompleter = self.Completer.rlcomplete
1642 self.set_completer()
1646 self.set_completer()
1643
1647
1644 # Configure readline according to user's prefs
1648 # Configure readline according to user's prefs
1645 # This is only done if GNU readline is being used. If libedit
1649 # This is only done if GNU readline is being used. If libedit
1646 # is being used (as on Leopard) the readline config is
1650 # is being used (as on Leopard) the readline config is
1647 # not run as the syntax for libedit is different.
1651 # not run as the syntax for libedit is different.
1648 if not readline.uses_libedit:
1652 if not readline.uses_libedit:
1649 for rlcommand in self.readline_parse_and_bind:
1653 for rlcommand in self.readline_parse_and_bind:
1650 #print "loading rl:",rlcommand # dbg
1654 #print "loading rl:",rlcommand # dbg
1651 readline.parse_and_bind(rlcommand)
1655 readline.parse_and_bind(rlcommand)
1652
1656
1653 # Remove some chars from the delimiters list. If we encounter
1657 # Remove some chars from the delimiters list. If we encounter
1654 # unicode chars, discard them.
1658 # unicode chars, discard them.
1655 delims = readline.get_completer_delims().encode("ascii", "ignore")
1659 delims = readline.get_completer_delims().encode("ascii", "ignore")
1656 delims = delims.translate(string._idmap,
1660 delims = delims.translate(string._idmap,
1657 self.readline_remove_delims)
1661 self.readline_remove_delims)
1658 readline.set_completer_delims(delims)
1662 readline.set_completer_delims(delims)
1659 # otherwise we end up with a monster history after a while:
1663 # otherwise we end up with a monster history after a while:
1660 readline.set_history_length(1000)
1664 readline.set_history_length(1000)
1661 try:
1665 try:
1662 #print '*** Reading readline history' # dbg
1666 #print '*** Reading readline history' # dbg
1663 readline.read_history_file(self.histfile)
1667 readline.read_history_file(self.histfile)
1664 except IOError:
1668 except IOError:
1665 pass # It doesn't exist yet.
1669 pass # It doesn't exist yet.
1666
1670
1667 atexit.register(self.atexit_operations)
1671 atexit.register(self.atexit_operations)
1668 del atexit
1672 del atexit
1669
1673
1670 # Configure auto-indent for all platforms
1674 # Configure auto-indent for all platforms
1671 self.set_autoindent(self.autoindent)
1675 self.set_autoindent(self.autoindent)
1672
1676
1673 def set_next_input(self, s):
1677 def set_next_input(self, s):
1674 """ Sets the 'default' input string for the next command line.
1678 """ Sets the 'default' input string for the next command line.
1675
1679
1676 Requires readline.
1680 Requires readline.
1677
1681
1678 Example:
1682 Example:
1679
1683
1680 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1684 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1681 [D:\ipython]|2> Hello Word_ # cursor is here
1685 [D:\ipython]|2> Hello Word_ # cursor is here
1682 """
1686 """
1683
1687
1684 self.rl_next_input = s
1688 self.rl_next_input = s
1685
1689
1686 # Maybe move this to the terminal subclass?
1690 # Maybe move this to the terminal subclass?
1687 def pre_readline(self):
1691 def pre_readline(self):
1688 """readline hook to be used at the start of each line.
1692 """readline hook to be used at the start of each line.
1689
1693
1690 Currently it handles auto-indent only."""
1694 Currently it handles auto-indent only."""
1691
1695
1692 if self.rl_do_indent:
1696 if self.rl_do_indent:
1693 self.readline.insert_text(self._indent_current_str())
1697 self.readline.insert_text(self._indent_current_str())
1694 if self.rl_next_input is not None:
1698 if self.rl_next_input is not None:
1695 self.readline.insert_text(self.rl_next_input)
1699 self.readline.insert_text(self.rl_next_input)
1696 self.rl_next_input = None
1700 self.rl_next_input = None
1697
1701
1698 def _indent_current_str(self):
1702 def _indent_current_str(self):
1699 """return the current level of indentation as a string"""
1703 """return the current level of indentation as a string"""
1700 return self.indent_current_nsp * ' '
1704 return self.indent_current_nsp * ' '
1701
1705
1702 #-------------------------------------------------------------------------
1706 #-------------------------------------------------------------------------
1703 # Things related to magics
1707 # Things related to magics
1704 #-------------------------------------------------------------------------
1708 #-------------------------------------------------------------------------
1705
1709
1706 def init_magics(self):
1710 def init_magics(self):
1707 # FIXME: Move the color initialization to the DisplayHook, which
1711 # FIXME: Move the color initialization to the DisplayHook, which
1708 # should be split into a prompt manager and displayhook. We probably
1712 # should be split into a prompt manager and displayhook. We probably
1709 # even need a centralize colors management object.
1713 # even need a centralize colors management object.
1710 self.magic_colors(self.colors)
1714 self.magic_colors(self.colors)
1711 # History was moved to a separate module
1715 # History was moved to a separate module
1712 from . import history
1716 from . import history
1713 history.init_ipython(self)
1717 history.init_ipython(self)
1714
1718
1715 def magic(self,arg_s):
1719 def magic(self,arg_s):
1716 """Call a magic function by name.
1720 """Call a magic function by name.
1717
1721
1718 Input: a string containing the name of the magic function to call and any
1722 Input: a string containing the name of the magic function to call and any
1719 additional arguments to be passed to the magic.
1723 additional arguments to be passed to the magic.
1720
1724
1721 magic('name -opt foo bar') is equivalent to typing at the ipython
1725 magic('name -opt foo bar') is equivalent to typing at the ipython
1722 prompt:
1726 prompt:
1723
1727
1724 In[1]: %name -opt foo bar
1728 In[1]: %name -opt foo bar
1725
1729
1726 To call a magic without arguments, simply use magic('name').
1730 To call a magic without arguments, simply use magic('name').
1727
1731
1728 This provides a proper Python function to call IPython's magics in any
1732 This provides a proper Python function to call IPython's magics in any
1729 valid Python code you can type at the interpreter, including loops and
1733 valid Python code you can type at the interpreter, including loops and
1730 compound statements.
1734 compound statements.
1731 """
1735 """
1732 args = arg_s.split(' ',1)
1736 args = arg_s.split(' ',1)
1733 magic_name = args[0]
1737 magic_name = args[0]
1734 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1738 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1735
1739
1736 try:
1740 try:
1737 magic_args = args[1]
1741 magic_args = args[1]
1738 except IndexError:
1742 except IndexError:
1739 magic_args = ''
1743 magic_args = ''
1740 fn = getattr(self,'magic_'+magic_name,None)
1744 fn = getattr(self,'magic_'+magic_name,None)
1741 if fn is None:
1745 if fn is None:
1742 error("Magic function `%s` not found." % magic_name)
1746 error("Magic function `%s` not found." % magic_name)
1743 else:
1747 else:
1744 magic_args = self.var_expand(magic_args,1)
1748 magic_args = self.var_expand(magic_args,1)
1745 with nested(self.builtin_trap,):
1749 with nested(self.builtin_trap,):
1746 result = fn(magic_args)
1750 result = fn(magic_args)
1747 return result
1751 return result
1748
1752
1749 def define_magic(self, magicname, func):
1753 def define_magic(self, magicname, func):
1750 """Expose own function as magic function for ipython
1754 """Expose own function as magic function for ipython
1751
1755
1752 def foo_impl(self,parameter_s=''):
1756 def foo_impl(self,parameter_s=''):
1753 'My very own magic!. (Use docstrings, IPython reads them).'
1757 'My very own magic!. (Use docstrings, IPython reads them).'
1754 print 'Magic function. Passed parameter is between < >:'
1758 print 'Magic function. Passed parameter is between < >:'
1755 print '<%s>' % parameter_s
1759 print '<%s>' % parameter_s
1756 print 'The self object is:',self
1760 print 'The self object is:',self
1757
1761
1758 self.define_magic('foo',foo_impl)
1762 self.define_magic('foo',foo_impl)
1759 """
1763 """
1760
1764
1761 import new
1765 import new
1762 im = new.instancemethod(func,self, self.__class__)
1766 im = new.instancemethod(func,self, self.__class__)
1763 old = getattr(self, "magic_" + magicname, None)
1767 old = getattr(self, "magic_" + magicname, None)
1764 setattr(self, "magic_" + magicname, im)
1768 setattr(self, "magic_" + magicname, im)
1765 return old
1769 return old
1766
1770
1767 #-------------------------------------------------------------------------
1771 #-------------------------------------------------------------------------
1768 # Things related to macros
1772 # Things related to macros
1769 #-------------------------------------------------------------------------
1773 #-------------------------------------------------------------------------
1770
1774
1771 def define_macro(self, name, themacro):
1775 def define_macro(self, name, themacro):
1772 """Define a new macro
1776 """Define a new macro
1773
1777
1774 Parameters
1778 Parameters
1775 ----------
1779 ----------
1776 name : str
1780 name : str
1777 The name of the macro.
1781 The name of the macro.
1778 themacro : str or Macro
1782 themacro : str or Macro
1779 The action to do upon invoking the macro. If a string, a new
1783 The action to do upon invoking the macro. If a string, a new
1780 Macro object is created by passing the string to it.
1784 Macro object is created by passing the string to it.
1781 """
1785 """
1782
1786
1783 from IPython.core import macro
1787 from IPython.core import macro
1784
1788
1785 if isinstance(themacro, basestring):
1789 if isinstance(themacro, basestring):
1786 themacro = macro.Macro(themacro)
1790 themacro = macro.Macro(themacro)
1787 if not isinstance(themacro, macro.Macro):
1791 if not isinstance(themacro, macro.Macro):
1788 raise ValueError('A macro must be a string or a Macro instance.')
1792 raise ValueError('A macro must be a string or a Macro instance.')
1789 self.user_ns[name] = themacro
1793 self.user_ns[name] = themacro
1790
1794
1791 #-------------------------------------------------------------------------
1795 #-------------------------------------------------------------------------
1792 # Things related to the running of system commands
1796 # Things related to the running of system commands
1793 #-------------------------------------------------------------------------
1797 #-------------------------------------------------------------------------
1794
1798
1795 def system(self, cmd):
1799 def system(self, cmd):
1796 """Call the given cmd in a subprocess."""
1800 """Call the given cmd in a subprocess."""
1797 # We do not support backgrounding processes because we either use
1801 # We do not support backgrounding processes because we either use
1798 # pexpect or pipes to read from. Users can always just call
1802 # pexpect or pipes to read from. Users can always just call
1799 # os.system() if they really want a background process.
1803 # os.system() if they really want a background process.
1800 if cmd.endswith('&'):
1804 if cmd.endswith('&'):
1801 raise OSError("Background processes not supported.")
1805 raise OSError("Background processes not supported.")
1802
1806
1803 return system(self.var_expand(cmd, depth=2))
1807 return system(self.var_expand(cmd, depth=2))
1804
1808
1805 def getoutput(self, cmd):
1809 def getoutput(self, cmd):
1806 """Get output (possibly including stderr) from a subprocess."""
1810 """Get output (possibly including stderr) from a subprocess."""
1807 if cmd.endswith('&'):
1811 if cmd.endswith('&'):
1808 raise OSError("Background processes not supported.")
1812 raise OSError("Background processes not supported.")
1809 return getoutput(self.var_expand(cmd, depth=2))
1813 return getoutput(self.var_expand(cmd, depth=2))
1810
1814
1811 #-------------------------------------------------------------------------
1815 #-------------------------------------------------------------------------
1812 # Things related to aliases
1816 # Things related to aliases
1813 #-------------------------------------------------------------------------
1817 #-------------------------------------------------------------------------
1814
1818
1815 def init_alias(self):
1819 def init_alias(self):
1816 self.alias_manager = AliasManager(shell=self, config=self.config)
1820 self.alias_manager = AliasManager(shell=self, config=self.config)
1817 self.ns_table['alias'] = self.alias_manager.alias_table,
1821 self.ns_table['alias'] = self.alias_manager.alias_table,
1818
1822
1819 #-------------------------------------------------------------------------
1823 #-------------------------------------------------------------------------
1820 # Things related to extensions and plugins
1824 # Things related to extensions and plugins
1821 #-------------------------------------------------------------------------
1825 #-------------------------------------------------------------------------
1822
1826
1823 def init_extension_manager(self):
1827 def init_extension_manager(self):
1824 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1828 self.extension_manager = ExtensionManager(shell=self, config=self.config)
1825
1829
1826 def init_plugin_manager(self):
1830 def init_plugin_manager(self):
1827 self.plugin_manager = PluginManager(config=self.config)
1831 self.plugin_manager = PluginManager(config=self.config)
1828
1832
1829 #-------------------------------------------------------------------------
1833 #-------------------------------------------------------------------------
1830 # Things related to payloads
1834 # Things related to payloads
1831 #-------------------------------------------------------------------------
1835 #-------------------------------------------------------------------------
1832
1836
1833 def init_payload(self):
1837 def init_payload(self):
1834 self.payload_manager = PayloadManager(config=self.config)
1838 self.payload_manager = PayloadManager(config=self.config)
1835
1839
1836 #-------------------------------------------------------------------------
1840 #-------------------------------------------------------------------------
1837 # Things related to the prefilter
1841 # Things related to the prefilter
1838 #-------------------------------------------------------------------------
1842 #-------------------------------------------------------------------------
1839
1843
1840 def init_prefilter(self):
1844 def init_prefilter(self):
1841 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1845 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
1842 # Ultimately this will be refactored in the new interpreter code, but
1846 # Ultimately this will be refactored in the new interpreter code, but
1843 # for now, we should expose the main prefilter method (there's legacy
1847 # for now, we should expose the main prefilter method (there's legacy
1844 # code out there that may rely on this).
1848 # code out there that may rely on this).
1845 self.prefilter = self.prefilter_manager.prefilter_lines
1849 self.prefilter = self.prefilter_manager.prefilter_lines
1846
1850
1847 #-------------------------------------------------------------------------
1851 #-------------------------------------------------------------------------
1848 # Things related to extracting values/expressions from kernel and user_ns
1852 # Things related to extracting values/expressions from kernel and user_ns
1849 #-------------------------------------------------------------------------
1853 #-------------------------------------------------------------------------
1850
1854
1851 def _simple_error(self):
1855 def _simple_error(self):
1852 etype, value = sys.exc_info()[:2]
1856 etype, value = sys.exc_info()[:2]
1853 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1857 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
1854
1858
1855 def get_user_variables(self, names):
1859 def get_user_variables(self, names):
1856 """Get a list of variable names from the user's namespace.
1860 """Get a list of variable names from the user's namespace.
1857
1861
1858 The return value is a dict with the repr() of each value.
1862 The return value is a dict with the repr() of each value.
1859 """
1863 """
1860 out = {}
1864 out = {}
1861 user_ns = self.user_ns
1865 user_ns = self.user_ns
1862 for varname in names:
1866 for varname in names:
1863 try:
1867 try:
1864 value = repr(user_ns[varname])
1868 value = repr(user_ns[varname])
1865 except:
1869 except:
1866 value = self._simple_error()
1870 value = self._simple_error()
1867 out[varname] = value
1871 out[varname] = value
1868 return out
1872 return out
1869
1873
1870 def eval_expressions(self, expressions):
1874 def eval_expressions(self, expressions):
1871 """Evaluate a dict of expressions in the user's namespace.
1875 """Evaluate a dict of expressions in the user's namespace.
1872
1876
1873 The return value is a dict with the repr() of each value.
1877 The return value is a dict with the repr() of each value.
1874 """
1878 """
1875 out = {}
1879 out = {}
1876 user_ns = self.user_ns
1880 user_ns = self.user_ns
1877 global_ns = self.user_global_ns
1881 global_ns = self.user_global_ns
1878 for key, expr in expressions.iteritems():
1882 for key, expr in expressions.iteritems():
1879 try:
1883 try:
1880 value = repr(eval(expr, global_ns, user_ns))
1884 value = repr(eval(expr, global_ns, user_ns))
1881 except:
1885 except:
1882 value = self._simple_error()
1886 value = self._simple_error()
1883 out[key] = value
1887 out[key] = value
1884 return out
1888 return out
1885
1889
1886 #-------------------------------------------------------------------------
1890 #-------------------------------------------------------------------------
1887 # Things related to the running of code
1891 # Things related to the running of code
1888 #-------------------------------------------------------------------------
1892 #-------------------------------------------------------------------------
1889
1893
1890 def ex(self, cmd):
1894 def ex(self, cmd):
1891 """Execute a normal python statement in user namespace."""
1895 """Execute a normal python statement in user namespace."""
1892 with nested(self.builtin_trap,):
1896 with nested(self.builtin_trap,):
1893 exec cmd in self.user_global_ns, self.user_ns
1897 exec cmd in self.user_global_ns, self.user_ns
1894
1898
1895 def ev(self, expr):
1899 def ev(self, expr):
1896 """Evaluate python expression expr in user namespace.
1900 """Evaluate python expression expr in user namespace.
1897
1901
1898 Returns the result of evaluation
1902 Returns the result of evaluation
1899 """
1903 """
1900 with nested(self.builtin_trap,):
1904 with nested(self.builtin_trap,):
1901 return eval(expr, self.user_global_ns, self.user_ns)
1905 return eval(expr, self.user_global_ns, self.user_ns)
1902
1906
1903 def safe_execfile(self, fname, *where, **kw):
1907 def safe_execfile(self, fname, *where, **kw):
1904 """A safe version of the builtin execfile().
1908 """A safe version of the builtin execfile().
1905
1909
1906 This version will never throw an exception, but instead print
1910 This version will never throw an exception, but instead print
1907 helpful error messages to the screen. This only works on pure
1911 helpful error messages to the screen. This only works on pure
1908 Python files with the .py extension.
1912 Python files with the .py extension.
1909
1913
1910 Parameters
1914 Parameters
1911 ----------
1915 ----------
1912 fname : string
1916 fname : string
1913 The name of the file to be executed.
1917 The name of the file to be executed.
1914 where : tuple
1918 where : tuple
1915 One or two namespaces, passed to execfile() as (globals,locals).
1919 One or two namespaces, passed to execfile() as (globals,locals).
1916 If only one is given, it is passed as both.
1920 If only one is given, it is passed as both.
1917 exit_ignore : bool (False)
1921 exit_ignore : bool (False)
1918 If True, then silence SystemExit for non-zero status (it is always
1922 If True, then silence SystemExit for non-zero status (it is always
1919 silenced for zero status, as it is so common).
1923 silenced for zero status, as it is so common).
1920 """
1924 """
1921 kw.setdefault('exit_ignore', False)
1925 kw.setdefault('exit_ignore', False)
1922
1926
1923 fname = os.path.abspath(os.path.expanduser(fname))
1927 fname = os.path.abspath(os.path.expanduser(fname))
1924
1928
1925 # Make sure we have a .py file
1929 # Make sure we have a .py file
1926 if not fname.endswith('.py'):
1930 if not fname.endswith('.py'):
1927 warn('File must end with .py to be run using execfile: <%s>' % fname)
1931 warn('File must end with .py to be run using execfile: <%s>' % fname)
1928
1932
1929 # Make sure we can open the file
1933 # Make sure we can open the file
1930 try:
1934 try:
1931 with open(fname) as thefile:
1935 with open(fname) as thefile:
1932 pass
1936 pass
1933 except:
1937 except:
1934 warn('Could not open file <%s> for safe execution.' % fname)
1938 warn('Could not open file <%s> for safe execution.' % fname)
1935 return
1939 return
1936
1940
1937 # Find things also in current directory. This is needed to mimic the
1941 # Find things also in current directory. This is needed to mimic the
1938 # behavior of running a script from the system command line, where
1942 # behavior of running a script from the system command line, where
1939 # Python inserts the script's directory into sys.path
1943 # Python inserts the script's directory into sys.path
1940 dname = os.path.dirname(fname)
1944 dname = os.path.dirname(fname)
1941
1945
1942 with prepended_to_syspath(dname):
1946 with prepended_to_syspath(dname):
1943 try:
1947 try:
1944 execfile(fname,*where)
1948 execfile(fname,*where)
1945 except SystemExit, status:
1949 except SystemExit, status:
1946 # If the call was made with 0 or None exit status (sys.exit(0)
1950 # If the call was made with 0 or None exit status (sys.exit(0)
1947 # or sys.exit() ), don't bother showing a traceback, as both of
1951 # or sys.exit() ), don't bother showing a traceback, as both of
1948 # these are considered normal by the OS:
1952 # these are considered normal by the OS:
1949 # > python -c'import sys;sys.exit(0)'; echo $?
1953 # > python -c'import sys;sys.exit(0)'; echo $?
1950 # 0
1954 # 0
1951 # > python -c'import sys;sys.exit()'; echo $?
1955 # > python -c'import sys;sys.exit()'; echo $?
1952 # 0
1956 # 0
1953 # For other exit status, we show the exception unless
1957 # For other exit status, we show the exception unless
1954 # explicitly silenced, but only in short form.
1958 # explicitly silenced, but only in short form.
1955 if status.code not in (0, None) and not kw['exit_ignore']:
1959 if status.code not in (0, None) and not kw['exit_ignore']:
1956 self.showtraceback(exception_only=True)
1960 self.showtraceback(exception_only=True)
1957 except:
1961 except:
1958 self.showtraceback()
1962 self.showtraceback()
1959
1963
1960 def safe_execfile_ipy(self, fname):
1964 def safe_execfile_ipy(self, fname):
1961 """Like safe_execfile, but for .ipy files with IPython syntax.
1965 """Like safe_execfile, but for .ipy files with IPython syntax.
1962
1966
1963 Parameters
1967 Parameters
1964 ----------
1968 ----------
1965 fname : str
1969 fname : str
1966 The name of the file to execute. The filename must have a
1970 The name of the file to execute. The filename must have a
1967 .ipy extension.
1971 .ipy extension.
1968 """
1972 """
1969 fname = os.path.abspath(os.path.expanduser(fname))
1973 fname = os.path.abspath(os.path.expanduser(fname))
1970
1974
1971 # Make sure we have a .py file
1975 # Make sure we have a .py file
1972 if not fname.endswith('.ipy'):
1976 if not fname.endswith('.ipy'):
1973 warn('File must end with .py to be run using execfile: <%s>' % fname)
1977 warn('File must end with .py to be run using execfile: <%s>' % fname)
1974
1978
1975 # Make sure we can open the file
1979 # Make sure we can open the file
1976 try:
1980 try:
1977 with open(fname) as thefile:
1981 with open(fname) as thefile:
1978 pass
1982 pass
1979 except:
1983 except:
1980 warn('Could not open file <%s> for safe execution.' % fname)
1984 warn('Could not open file <%s> for safe execution.' % fname)
1981 return
1985 return
1982
1986
1983 # Find things also in current directory. This is needed to mimic the
1987 # Find things also in current directory. This is needed to mimic the
1984 # behavior of running a script from the system command line, where
1988 # behavior of running a script from the system command line, where
1985 # Python inserts the script's directory into sys.path
1989 # Python inserts the script's directory into sys.path
1986 dname = os.path.dirname(fname)
1990 dname = os.path.dirname(fname)
1987
1991
1988 with prepended_to_syspath(dname):
1992 with prepended_to_syspath(dname):
1989 try:
1993 try:
1990 with open(fname) as thefile:
1994 with open(fname) as thefile:
1991 script = thefile.read()
1995 script = thefile.read()
1992 # self.runlines currently captures all exceptions
1996 # self.runlines currently captures all exceptions
1993 # raise in user code. It would be nice if there were
1997 # raise in user code. It would be nice if there were
1994 # versions of runlines, execfile that did raise, so
1998 # versions of runlines, execfile that did raise, so
1995 # we could catch the errors.
1999 # we could catch the errors.
1996 self.runlines(script, clean=True)
2000 self.runlines(script, clean=True)
1997 except:
2001 except:
1998 self.showtraceback()
2002 self.showtraceback()
1999 warn('Unknown failure executing file: <%s>' % fname)
2003 warn('Unknown failure executing file: <%s>' % fname)
2000
2004
2001 def runlines(self, lines, clean=False):
2005 def runlines(self, lines, clean=False):
2002 """Run a string of one or more lines of source.
2006 """Run a string of one or more lines of source.
2003
2007
2004 This method is capable of running a string containing multiple source
2008 This method is capable of running a string containing multiple source
2005 lines, as if they had been entered at the IPython prompt. Since it
2009 lines, as if they had been entered at the IPython prompt. Since it
2006 exposes IPython's processing machinery, the given strings can contain
2010 exposes IPython's processing machinery, the given strings can contain
2007 magic calls (%magic), special shell access (!cmd), etc.
2011 magic calls (%magic), special shell access (!cmd), etc.
2008 """
2012 """
2009
2013
2010 if isinstance(lines, (list, tuple)):
2014 if isinstance(lines, (list, tuple)):
2011 lines = '\n'.join(lines)
2015 lines = '\n'.join(lines)
2012
2016
2013 if clean:
2017 if clean:
2014 lines = self._cleanup_ipy_script(lines)
2018 lines = self._cleanup_ipy_script(lines)
2015
2019
2016 # We must start with a clean buffer, in case this is run from an
2020 # We must start with a clean buffer, in case this is run from an
2017 # interactive IPython session (via a magic, for example).
2021 # interactive IPython session (via a magic, for example).
2018 self.resetbuffer()
2022 self.resetbuffer()
2019 lines = lines.splitlines()
2023 lines = lines.splitlines()
2020 more = 0
2024 more = 0
2021 with nested(self.builtin_trap, self.display_trap):
2025 with nested(self.builtin_trap, self.display_trap):
2022 for line in lines:
2026 for line in lines:
2023 # skip blank lines so we don't mess up the prompt counter, but do
2027 # skip blank lines so we don't mess up the prompt counter, but do
2024 # NOT skip even a blank line if we are in a code block (more is
2028 # NOT skip even a blank line if we are in a code block (more is
2025 # true)
2029 # true)
2026
2030
2027 if line or more:
2031 if line or more:
2028 # push to raw history, so hist line numbers stay in sync
2032 # push to raw history, so hist line numbers stay in sync
2029 self.input_hist_raw.append(line + '\n')
2033 self.input_hist_raw.append(line + '\n')
2030 prefiltered = self.prefilter_manager.prefilter_lines(line,
2034 prefiltered = self.prefilter_manager.prefilter_lines(line,
2031 more)
2035 more)
2032 more = self.push_line(prefiltered)
2036 more = self.push_line(prefiltered)
2033 # IPython's runsource returns None if there was an error
2037 # IPython's runsource returns None if there was an error
2034 # compiling the code. This allows us to stop processing right
2038 # compiling the code. This allows us to stop processing right
2035 # away, so the user gets the error message at the right place.
2039 # away, so the user gets the error message at the right place.
2036 if more is None:
2040 if more is None:
2037 break
2041 break
2038 else:
2042 else:
2039 self.input_hist_raw.append("\n")
2043 self.input_hist_raw.append("\n")
2040 # final newline in case the input didn't have it, so that the code
2044 # final newline in case the input didn't have it, so that the code
2041 # actually does get executed
2045 # actually does get executed
2042 if more:
2046 if more:
2043 self.push_line('\n')
2047 self.push_line('\n')
2044
2048
2045 def runsource(self, source, filename='<input>', symbol='single'):
2049 def runsource(self, source, filename='<input>', symbol='single'):
2046 """Compile and run some source in the interpreter.
2050 """Compile and run some source in the interpreter.
2047
2051
2048 Arguments are as for compile_command().
2052 Arguments are as for compile_command().
2049
2053
2050 One several things can happen:
2054 One several things can happen:
2051
2055
2052 1) The input is incorrect; compile_command() raised an
2056 1) The input is incorrect; compile_command() raised an
2053 exception (SyntaxError or OverflowError). A syntax traceback
2057 exception (SyntaxError or OverflowError). A syntax traceback
2054 will be printed by calling the showsyntaxerror() method.
2058 will be printed by calling the showsyntaxerror() method.
2055
2059
2056 2) The input is incomplete, and more input is required;
2060 2) The input is incomplete, and more input is required;
2057 compile_command() returned None. Nothing happens.
2061 compile_command() returned None. Nothing happens.
2058
2062
2059 3) The input is complete; compile_command() returned a code
2063 3) The input is complete; compile_command() returned a code
2060 object. The code is executed by calling self.runcode() (which
2064 object. The code is executed by calling self.runcode() (which
2061 also handles run-time exceptions, except for SystemExit).
2065 also handles run-time exceptions, except for SystemExit).
2062
2066
2063 The return value is:
2067 The return value is:
2064
2068
2065 - True in case 2
2069 - True in case 2
2066
2070
2067 - False in the other cases, unless an exception is raised, where
2071 - False in the other cases, unless an exception is raised, where
2068 None is returned instead. This can be used by external callers to
2072 None is returned instead. This can be used by external callers to
2069 know whether to continue feeding input or not.
2073 know whether to continue feeding input or not.
2070
2074
2071 The return value can be used to decide whether to use sys.ps1 or
2075 The return value can be used to decide whether to use sys.ps1 or
2072 sys.ps2 to prompt the next line."""
2076 sys.ps2 to prompt the next line."""
2073
2077
2074 # if the source code has leading blanks, add 'if 1:\n' to it
2078 # if the source code has leading blanks, add 'if 1:\n' to it
2075 # this allows execution of indented pasted code. It is tempting
2079 # this allows execution of indented pasted code. It is tempting
2076 # to add '\n' at the end of source to run commands like ' a=1'
2080 # to add '\n' at the end of source to run commands like ' a=1'
2077 # directly, but this fails for more complicated scenarios
2081 # directly, but this fails for more complicated scenarios
2078 source=source.encode(self.stdin_encoding)
2082 source=source.encode(self.stdin_encoding)
2079 if source[:1] in [' ', '\t']:
2083 if source[:1] in [' ', '\t']:
2080 source = 'if 1:\n%s' % source
2084 source = 'if 1:\n%s' % source
2081
2085
2082 try:
2086 try:
2083 code = self.compile(source,filename,symbol)
2087 code = self.compile(source,filename,symbol)
2084 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2088 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2085 # Case 1
2089 # Case 1
2086 self.showsyntaxerror(filename)
2090 self.showsyntaxerror(filename)
2087 return None
2091 return None
2088
2092
2089 if code is None:
2093 if code is None:
2090 # Case 2
2094 # Case 2
2091 return True
2095 return True
2092
2096
2093 # Case 3
2097 # Case 3
2094 # We store the code object so that threaded shells and
2098 # We store the code object so that threaded shells and
2095 # custom exception handlers can access all this info if needed.
2099 # custom exception handlers can access all this info if needed.
2096 # The source corresponding to this can be obtained from the
2100 # The source corresponding to this can be obtained from the
2097 # buffer attribute as '\n'.join(self.buffer).
2101 # buffer attribute as '\n'.join(self.buffer).
2098 self.code_to_run = code
2102 self.code_to_run = code
2099 # now actually execute the code object
2103 # now actually execute the code object
2100 if self.runcode(code) == 0:
2104 if self.runcode(code) == 0:
2101 return False
2105 return False
2102 else:
2106 else:
2103 return None
2107 return None
2104
2108
2105 def runcode(self,code_obj):
2109 def runcode(self,code_obj):
2106 """Execute a code object.
2110 """Execute a code object.
2107
2111
2108 When an exception occurs, self.showtraceback() is called to display a
2112 When an exception occurs, self.showtraceback() is called to display a
2109 traceback.
2113 traceback.
2110
2114
2111 Return value: a flag indicating whether the code to be run completed
2115 Return value: a flag indicating whether the code to be run completed
2112 successfully:
2116 successfully:
2113
2117
2114 - 0: successful execution.
2118 - 0: successful execution.
2115 - 1: an error occurred.
2119 - 1: an error occurred.
2116 """
2120 """
2117
2121
2118 # Set our own excepthook in case the user code tries to call it
2122 # Set our own excepthook in case the user code tries to call it
2119 # directly, so that the IPython crash handler doesn't get triggered
2123 # directly, so that the IPython crash handler doesn't get triggered
2120 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2124 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2121
2125
2122 # we save the original sys.excepthook in the instance, in case config
2126 # we save the original sys.excepthook in the instance, in case config
2123 # code (such as magics) needs access to it.
2127 # code (such as magics) needs access to it.
2124 self.sys_excepthook = old_excepthook
2128 self.sys_excepthook = old_excepthook
2125 outflag = 1 # happens in more places, so it's easier as default
2129 outflag = 1 # happens in more places, so it's easier as default
2126 try:
2130 try:
2127 try:
2131 try:
2128 self.hooks.pre_runcode_hook()
2132 self.hooks.pre_runcode_hook()
2129 #rprint('Running code') # dbg
2133 #rprint('Running code') # dbg
2130 exec code_obj in self.user_global_ns, self.user_ns
2134 exec code_obj in self.user_global_ns, self.user_ns
2131 finally:
2135 finally:
2132 # Reset our crash handler in place
2136 # Reset our crash handler in place
2133 sys.excepthook = old_excepthook
2137 sys.excepthook = old_excepthook
2134 except SystemExit:
2138 except SystemExit:
2135 self.resetbuffer()
2139 self.resetbuffer()
2136 self.showtraceback(exception_only=True)
2140 self.showtraceback(exception_only=True)
2137 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2141 warn("To exit: use any of 'exit', 'quit', %Exit or Ctrl-D.", level=1)
2138 except self.custom_exceptions:
2142 except self.custom_exceptions:
2139 etype,value,tb = sys.exc_info()
2143 etype,value,tb = sys.exc_info()
2140 self.CustomTB(etype,value,tb)
2144 self.CustomTB(etype,value,tb)
2141 except:
2145 except:
2142 self.showtraceback()
2146 self.showtraceback()
2143 else:
2147 else:
2144 outflag = 0
2148 outflag = 0
2145 if softspace(sys.stdout, 0):
2149 if softspace(sys.stdout, 0):
2146 print
2150 print
2147 # Flush out code object which has been run (and source)
2151 # Flush out code object which has been run (and source)
2148 self.code_to_run = None
2152 self.code_to_run = None
2149 return outflag
2153 return outflag
2150
2154
2151 def push_line(self, line):
2155 def push_line(self, line):
2152 """Push a line to the interpreter.
2156 """Push a line to the interpreter.
2153
2157
2154 The line should not have a trailing newline; it may have
2158 The line should not have a trailing newline; it may have
2155 internal newlines. The line is appended to a buffer and the
2159 internal newlines. The line is appended to a buffer and the
2156 interpreter's runsource() method is called with the
2160 interpreter's runsource() method is called with the
2157 concatenated contents of the buffer as source. If this
2161 concatenated contents of the buffer as source. If this
2158 indicates that the command was executed or invalid, the buffer
2162 indicates that the command was executed or invalid, the buffer
2159 is reset; otherwise, the command is incomplete, and the buffer
2163 is reset; otherwise, the command is incomplete, and the buffer
2160 is left as it was after the line was appended. The return
2164 is left as it was after the line was appended. The return
2161 value is 1 if more input is required, 0 if the line was dealt
2165 value is 1 if more input is required, 0 if the line was dealt
2162 with in some way (this is the same as runsource()).
2166 with in some way (this is the same as runsource()).
2163 """
2167 """
2164
2168
2165 # autoindent management should be done here, and not in the
2169 # autoindent management should be done here, and not in the
2166 # interactive loop, since that one is only seen by keyboard input. We
2170 # interactive loop, since that one is only seen by keyboard input. We
2167 # need this done correctly even for code run via runlines (which uses
2171 # need this done correctly even for code run via runlines (which uses
2168 # push).
2172 # push).
2169
2173
2170 #print 'push line: <%s>' % line # dbg
2174 #print 'push line: <%s>' % line # dbg
2171 for subline in line.splitlines():
2175 for subline in line.splitlines():
2172 self._autoindent_update(subline)
2176 self._autoindent_update(subline)
2173 self.buffer.append(line)
2177 self.buffer.append(line)
2174 more = self.runsource('\n'.join(self.buffer), self.filename)
2178 more = self.runsource('\n'.join(self.buffer), self.filename)
2175 if not more:
2179 if not more:
2176 self.resetbuffer()
2180 self.resetbuffer()
2177 return more
2181 return more
2178
2182
2179 def resetbuffer(self):
2183 def resetbuffer(self):
2180 """Reset the input buffer."""
2184 """Reset the input buffer."""
2181 self.buffer[:] = []
2185 self.buffer[:] = []
2182
2186
2183 def _is_secondary_block_start(self, s):
2187 def _is_secondary_block_start(self, s):
2184 if not s.endswith(':'):
2188 if not s.endswith(':'):
2185 return False
2189 return False
2186 if (s.startswith('elif') or
2190 if (s.startswith('elif') or
2187 s.startswith('else') or
2191 s.startswith('else') or
2188 s.startswith('except') or
2192 s.startswith('except') or
2189 s.startswith('finally')):
2193 s.startswith('finally')):
2190 return True
2194 return True
2191
2195
2192 def _cleanup_ipy_script(self, script):
2196 def _cleanup_ipy_script(self, script):
2193 """Make a script safe for self.runlines()
2197 """Make a script safe for self.runlines()
2194
2198
2195 Currently, IPython is lines based, with blocks being detected by
2199 Currently, IPython is lines based, with blocks being detected by
2196 empty lines. This is a problem for block based scripts that may
2200 empty lines. This is a problem for block based scripts that may
2197 not have empty lines after blocks. This script adds those empty
2201 not have empty lines after blocks. This script adds those empty
2198 lines to make scripts safe for running in the current line based
2202 lines to make scripts safe for running in the current line based
2199 IPython.
2203 IPython.
2200 """
2204 """
2201 res = []
2205 res = []
2202 lines = script.splitlines()
2206 lines = script.splitlines()
2203 level = 0
2207 level = 0
2204
2208
2205 for l in lines:
2209 for l in lines:
2206 lstripped = l.lstrip()
2210 lstripped = l.lstrip()
2207 stripped = l.strip()
2211 stripped = l.strip()
2208 if not stripped:
2212 if not stripped:
2209 continue
2213 continue
2210 newlevel = len(l) - len(lstripped)
2214 newlevel = len(l) - len(lstripped)
2211 if level > 0 and newlevel == 0 and \
2215 if level > 0 and newlevel == 0 and \
2212 not self._is_secondary_block_start(stripped):
2216 not self._is_secondary_block_start(stripped):
2213 # add empty line
2217 # add empty line
2214 res.append('')
2218 res.append('')
2215 res.append(l)
2219 res.append(l)
2216 level = newlevel
2220 level = newlevel
2217
2221
2218 return '\n'.join(res) + '\n'
2222 return '\n'.join(res) + '\n'
2219
2223
2220 def _autoindent_update(self,line):
2224 def _autoindent_update(self,line):
2221 """Keep track of the indent level."""
2225 """Keep track of the indent level."""
2222
2226
2223 #debugx('line')
2227 #debugx('line')
2224 #debugx('self.indent_current_nsp')
2228 #debugx('self.indent_current_nsp')
2225 if self.autoindent:
2229 if self.autoindent:
2226 if line:
2230 if line:
2227 inisp = num_ini_spaces(line)
2231 inisp = num_ini_spaces(line)
2228 if inisp < self.indent_current_nsp:
2232 if inisp < self.indent_current_nsp:
2229 self.indent_current_nsp = inisp
2233 self.indent_current_nsp = inisp
2230
2234
2231 if line[-1] == ':':
2235 if line[-1] == ':':
2232 self.indent_current_nsp += 4
2236 self.indent_current_nsp += 4
2233 elif dedent_re.match(line):
2237 elif dedent_re.match(line):
2234 self.indent_current_nsp -= 4
2238 self.indent_current_nsp -= 4
2235 else:
2239 else:
2236 self.indent_current_nsp = 0
2240 self.indent_current_nsp = 0
2237
2241
2238 #-------------------------------------------------------------------------
2242 #-------------------------------------------------------------------------
2239 # Things related to GUI support and pylab
2243 # Things related to GUI support and pylab
2240 #-------------------------------------------------------------------------
2244 #-------------------------------------------------------------------------
2241
2245
2242 def enable_pylab(self, gui=None):
2246 def enable_pylab(self, gui=None):
2243 raise NotImplementedError('Implement enable_pylab in a subclass')
2247 raise NotImplementedError('Implement enable_pylab in a subclass')
2244
2248
2245 #-------------------------------------------------------------------------
2249 #-------------------------------------------------------------------------
2246 # Utilities
2250 # Utilities
2247 #-------------------------------------------------------------------------
2251 #-------------------------------------------------------------------------
2248
2252
2249 def var_expand(self,cmd,depth=0):
2253 def var_expand(self,cmd,depth=0):
2250 """Expand python variables in a string.
2254 """Expand python variables in a string.
2251
2255
2252 The depth argument indicates how many frames above the caller should
2256 The depth argument indicates how many frames above the caller should
2253 be walked to look for the local namespace where to expand variables.
2257 be walked to look for the local namespace where to expand variables.
2254
2258
2255 The global namespace for expansion is always the user's interactive
2259 The global namespace for expansion is always the user's interactive
2256 namespace.
2260 namespace.
2257 """
2261 """
2258
2262
2259 return str(ItplNS(cmd,
2263 return str(ItplNS(cmd,
2260 self.user_ns, # globals
2264 self.user_ns, # globals
2261 # Skip our own frame in searching for locals:
2265 # Skip our own frame in searching for locals:
2262 sys._getframe(depth+1).f_locals # locals
2266 sys._getframe(depth+1).f_locals # locals
2263 ))
2267 ))
2264
2268
2265 def mktempfile(self,data=None):
2269 def mktempfile(self,data=None):
2266 """Make a new tempfile and return its filename.
2270 """Make a new tempfile and return its filename.
2267
2271
2268 This makes a call to tempfile.mktemp, but it registers the created
2272 This makes a call to tempfile.mktemp, but it registers the created
2269 filename internally so ipython cleans it up at exit time.
2273 filename internally so ipython cleans it up at exit time.
2270
2274
2271 Optional inputs:
2275 Optional inputs:
2272
2276
2273 - data(None): if data is given, it gets written out to the temp file
2277 - data(None): if data is given, it gets written out to the temp file
2274 immediately, and the file is closed again."""
2278 immediately, and the file is closed again."""
2275
2279
2276 filename = tempfile.mktemp('.py','ipython_edit_')
2280 filename = tempfile.mktemp('.py','ipython_edit_')
2277 self.tempfiles.append(filename)
2281 self.tempfiles.append(filename)
2278
2282
2279 if data:
2283 if data:
2280 tmp_file = open(filename,'w')
2284 tmp_file = open(filename,'w')
2281 tmp_file.write(data)
2285 tmp_file.write(data)
2282 tmp_file.close()
2286 tmp_file.close()
2283 return filename
2287 return filename
2284
2288
2285 # TODO: This should be removed when Term is refactored.
2289 # TODO: This should be removed when Term is refactored.
2286 def write(self,data):
2290 def write(self,data):
2287 """Write a string to the default output"""
2291 """Write a string to the default output"""
2288 io.Term.cout.write(data)
2292 io.Term.cout.write(data)
2289
2293
2290 # TODO: This should be removed when Term is refactored.
2294 # TODO: This should be removed when Term is refactored.
2291 def write_err(self,data):
2295 def write_err(self,data):
2292 """Write a string to the default error output"""
2296 """Write a string to the default error output"""
2293 io.Term.cerr.write(data)
2297 io.Term.cerr.write(data)
2294
2298
2295 def ask_yes_no(self,prompt,default=True):
2299 def ask_yes_no(self,prompt,default=True):
2296 if self.quiet:
2300 if self.quiet:
2297 return True
2301 return True
2298 return ask_yes_no(prompt,default)
2302 return ask_yes_no(prompt,default)
2299
2303
2300 def show_usage(self):
2304 def show_usage(self):
2301 """Show a usage message"""
2305 """Show a usage message"""
2302 page.page(IPython.core.usage.interactive_usage)
2306 page.page(IPython.core.usage.interactive_usage)
2303
2307
2304 #-------------------------------------------------------------------------
2308 #-------------------------------------------------------------------------
2305 # Things related to IPython exiting
2309 # Things related to IPython exiting
2306 #-------------------------------------------------------------------------
2310 #-------------------------------------------------------------------------
2307
2311
2308 def atexit_operations(self):
2312 def atexit_operations(self):
2309 """This will be executed at the time of exit.
2313 """This will be executed at the time of exit.
2310
2314
2311 Saving of persistent data should be performed here.
2315 Saving of persistent data should be performed here.
2312 """
2316 """
2313 self.savehist()
2317 self.savehist()
2314
2318
2315 # Cleanup all tempfiles left around
2319 # Cleanup all tempfiles left around
2316 for tfile in self.tempfiles:
2320 for tfile in self.tempfiles:
2317 try:
2321 try:
2318 os.unlink(tfile)
2322 os.unlink(tfile)
2319 except OSError:
2323 except OSError:
2320 pass
2324 pass
2321
2325
2322 # Clear all user namespaces to release all references cleanly.
2326 # Clear all user namespaces to release all references cleanly.
2323 self.reset()
2327 self.reset()
2324
2328
2325 # Run user hooks
2329 # Run user hooks
2326 self.hooks.shutdown_hook()
2330 self.hooks.shutdown_hook()
2327
2331
2328 def cleanup(self):
2332 def cleanup(self):
2329 self.restore_sys_module_state()
2333 self.restore_sys_module_state()
2330
2334
2331
2335
2332 class InteractiveShellABC(object):
2336 class InteractiveShellABC(object):
2333 """An abstract base class for InteractiveShell."""
2337 """An abstract base class for InteractiveShell."""
2334 __metaclass__ = abc.ABCMeta
2338 __metaclass__ = abc.ABCMeta
2335
2339
2336 InteractiveShellABC.register(InteractiveShell)
2340 InteractiveShellABC.register(InteractiveShell)
@@ -1,611 +1,806 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
29 from itertools import izip_longest
28
30
29 # IPython's own
31 # IPython's own
30 from IPython.core import page
32 from IPython.core import page
31 from IPython.external.Itpl import itpl
33 from IPython.external.Itpl import itpl
32 from IPython.utils import PyColorize
34 from IPython.utils import PyColorize
33 import IPython.utils.io
35 import IPython.utils.io
34 from IPython.utils.text import indent
36 from IPython.utils.text import indent
35 from IPython.utils.wildcard import list_namespace
37 from IPython.utils.wildcard import list_namespace
36 from IPython.utils.coloransi import *
38 from IPython.utils.coloransi import *
37
39
38 #****************************************************************************
40 #****************************************************************************
39 # HACK!!! This is a crude fix for bugs in python 2.3's inspect module. We
40 # simply monkeypatch inspect with code copied from python 2.4.
41 if sys.version_info[:2] == (2,3):
42 from inspect import ismodule, getabsfile, modulesbyfile
43 def getmodule(object):
44 """Return the module an object was defined in, or None if not found."""
45 if ismodule(object):
46 return object
47 if hasattr(object, '__module__'):
48 return sys.modules.get(object.__module__)
49 try:
50 file = getabsfile(object)
51 except TypeError:
52 return None
53 if file in modulesbyfile:
54 return sys.modules.get(modulesbyfile[file])
55 for module in sys.modules.values():
56 if hasattr(module, '__file__'):
57 modulesbyfile[
58 os.path.realpath(
59 getabsfile(module))] = module.__name__
60 if file in modulesbyfile:
61 return sys.modules.get(modulesbyfile[file])
62 main = sys.modules['__main__']
63 if not hasattr(object, '__name__'):
64 return None
65 if hasattr(main, object.__name__):
66 mainobject = getattr(main, object.__name__)
67 if mainobject is object:
68 return main
69 builtin = sys.modules['__builtin__']
70 if hasattr(builtin, object.__name__):
71 builtinobject = getattr(builtin, object.__name__)
72 if builtinobject is object:
73 return builtin
74
75 inspect.getmodule = getmodule
76
77 #****************************************************************************
78 # Builtin color schemes
41 # Builtin color schemes
79
42
80 Colors = TermColors # just a shorthand
43 Colors = TermColors # just a shorthand
81
44
82 # Build a few color schemes
45 # Build a few color schemes
83 NoColor = ColorScheme(
46 NoColor = ColorScheme(
84 'NoColor',{
47 'NoColor',{
85 'header' : Colors.NoColor,
48 'header' : Colors.NoColor,
86 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
49 'normal' : Colors.NoColor # color off (usu. Colors.Normal)
87 } )
50 } )
88
51
89 LinuxColors = ColorScheme(
52 LinuxColors = ColorScheme(
90 'Linux',{
53 'Linux',{
91 'header' : Colors.LightRed,
54 'header' : Colors.LightRed,
92 'normal' : Colors.Normal # color off (usu. Colors.Normal)
55 'normal' : Colors.Normal # color off (usu. Colors.Normal)
93 } )
56 } )
94
57
95 LightBGColors = ColorScheme(
58 LightBGColors = ColorScheme(
96 'LightBG',{
59 'LightBG',{
97 'header' : Colors.Red,
60 'header' : Colors.Red,
98 'normal' : Colors.Normal # color off (usu. Colors.Normal)
61 'normal' : Colors.Normal # color off (usu. Colors.Normal)
99 } )
62 } )
100
63
101 # Build table of color schemes (needed by the parser)
64 # Build table of color schemes (needed by the parser)
102 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
65 InspectColors = ColorSchemeTable([NoColor,LinuxColors,LightBGColors],
103 'Linux')
66 'Linux')
104
67
105 #****************************************************************************
68 #****************************************************************************
106 # Auxiliary functions
69 # Auxiliary functions and objects
70
71 # See the messaging spec for the definition of all these fields. This list
72 # effectively defines the order of display
73 info_fields = ['type_name', 'base_class', 'string_form', 'namespace',
74 'length', 'file', 'definition', 'docstring', 'source',
75 'init_definition', 'class_docstring', 'init_docstring',
76 'call_def', 'call_docstring',
77 # These won't be printed but will be used to determine how to
78 # format the object
79 'ismagic', 'isalias',
80 ]
81
82
83 ObjectInfo = namedtuple('ObjectInfo', info_fields)
84
85
86 def mk_object_info(kw):
87 """Make a f"""
88 infodict = dict(izip_longest(info_fields, [None]))
89 infodict.update(kw)
90 return ObjectInfo(**infodict)
91
92
107 def getdoc(obj):
93 def getdoc(obj):
108 """Stable wrapper around inspect.getdoc.
94 """Stable wrapper around inspect.getdoc.
109
95
110 This can't crash because of attribute problems.
96 This can't crash because of attribute problems.
111
97
112 It also attempts to call a getdoc() method on the given object. This
98 It also attempts to call a getdoc() method on the given object. This
113 allows objects which provide their docstrings via non-standard mechanisms
99 allows objects which provide their docstrings via non-standard mechanisms
114 (like Pyro proxies) to still be inspected by ipython's ? system."""
100 (like Pyro proxies) to still be inspected by ipython's ? system."""
115
101
116 ds = None # default return value
102 ds = None # default return value
117 try:
103 try:
118 ds = inspect.getdoc(obj)
104 ds = inspect.getdoc(obj)
119 except:
105 except:
120 # Harden against an inspect failure, which can occur with
106 # Harden against an inspect failure, which can occur with
121 # SWIG-wrapped extensions.
107 # SWIG-wrapped extensions.
122 pass
108 pass
123 # Allow objects to offer customized documentation via a getdoc method:
109 # Allow objects to offer customized documentation via a getdoc method:
124 try:
110 try:
125 ds2 = obj.getdoc()
111 ds2 = obj.getdoc()
126 except:
112 except:
127 pass
113 pass
128 else:
114 else:
129 # if we get extra info, we add it to the normal docstring.
115 # if we get extra info, we add it to the normal docstring.
130 if ds is None:
116 if ds is None:
131 ds = ds2
117 ds = ds2
132 else:
118 else:
133 ds = '%s\n%s' % (ds,ds2)
119 ds = '%s\n%s' % (ds,ds2)
134 return ds
120 return ds
135
121
136
122
137 def getsource(obj,is_binary=False):
123 def getsource(obj,is_binary=False):
138 """Wrapper around inspect.getsource.
124 """Wrapper around inspect.getsource.
139
125
140 This can be modified by other projects to provide customized source
126 This can be modified by other projects to provide customized source
141 extraction.
127 extraction.
142
128
143 Inputs:
129 Inputs:
144
130
145 - obj: an object whose source code we will attempt to extract.
131 - obj: an object whose source code we will attempt to extract.
146
132
147 Optional inputs:
133 Optional inputs:
148
134
149 - is_binary: whether the object is known to come from a binary source.
135 - is_binary: whether the object is known to come from a binary source.
150 This implementation will skip returning any output for binary objects, but
136 This implementation will skip returning any output for binary objects, but
151 custom extractors may know how to meaningfully process them."""
137 custom extractors may know how to meaningfully process them."""
152
138
153 if is_binary:
139 if is_binary:
154 return None
140 return None
155 else:
141 else:
156 try:
142 try:
157 src = inspect.getsource(obj)
143 src = inspect.getsource(obj)
158 except TypeError:
144 except TypeError:
159 if hasattr(obj,'__class__'):
145 if hasattr(obj,'__class__'):
160 src = inspect.getsource(obj.__class__)
146 src = inspect.getsource(obj.__class__)
161 return src
147 return src
162
148
163 def getargspec(obj):
149 def getargspec(obj):
164 """Get the names and default values of a function's arguments.
150 """Get the names and default values of a function's arguments.
165
151
166 A tuple of four things is returned: (args, varargs, varkw, defaults).
152 A tuple of four things is returned: (args, varargs, varkw, defaults).
167 'args' is a list of the argument names (it may contain nested lists).
153 'args' is a list of the argument names (it may contain nested lists).
168 'varargs' and 'varkw' are the names of the * and ** arguments or None.
154 'varargs' and 'varkw' are the names of the * and ** arguments or None.
169 'defaults' is an n-tuple of the default values of the last n arguments.
155 'defaults' is an n-tuple of the default values of the last n arguments.
170
156
171 Modified version of inspect.getargspec from the Python Standard
157 Modified version of inspect.getargspec from the Python Standard
172 Library."""
158 Library."""
173
159
174 if inspect.isfunction(obj):
160 if inspect.isfunction(obj):
175 func_obj = obj
161 func_obj = obj
176 elif inspect.ismethod(obj):
162 elif inspect.ismethod(obj):
177 func_obj = obj.im_func
163 func_obj = obj.im_func
178 else:
164 else:
179 raise TypeError, 'arg is not a Python function'
165 raise TypeError, 'arg is not a Python function'
180 args, varargs, varkw = inspect.getargs(func_obj.func_code)
166 args, varargs, varkw = inspect.getargs(func_obj.func_code)
181 return args, varargs, varkw, func_obj.func_defaults
167 return args, varargs, varkw, func_obj.func_defaults
182
168
183 #****************************************************************************
169 #****************************************************************************
184 # Class definitions
170 # Class definitions
185
171
186 class myStringIO(StringIO.StringIO):
172 class myStringIO(StringIO.StringIO):
187 """Adds a writeln method to normal StringIO."""
173 """Adds a writeln method to normal StringIO."""
188 def writeln(self,*arg,**kw):
174 def writeln(self,*arg,**kw):
189 """Does a write() and then a write('\n')"""
175 """Does a write() and then a write('\n')"""
190 self.write(*arg,**kw)
176 self.write(*arg,**kw)
191 self.write('\n')
177 self.write('\n')
192
178
193
179
194 class Inspector:
180 class Inspector:
195 def __init__(self,color_table,code_color_table,scheme,
181 def __init__(self,color_table,code_color_table,scheme,
196 str_detail_level=0):
182 str_detail_level=0):
197 self.color_table = color_table
183 self.color_table = color_table
198 self.parser = PyColorize.Parser(code_color_table,out='str')
184 self.parser = PyColorize.Parser(code_color_table,out='str')
199 self.format = self.parser.format
185 self.format = self.parser.format
200 self.str_detail_level = str_detail_level
186 self.str_detail_level = str_detail_level
201 self.set_active_scheme(scheme)
187 self.set_active_scheme(scheme)
202
188
203 def _getdef(self,obj,oname=''):
189 def _getdef(self,obj,oname=''):
204 """Return the definition header for any callable object.
190 """Return the definition header for any callable object.
205
191
206 If any exception is generated, None is returned instead and the
192 If any exception is generated, None is returned instead and the
207 exception is suppressed."""
193 exception is suppressed."""
208
194
209 try:
195 try:
210 # We need a plain string here, NOT unicode!
196 # We need a plain string here, NOT unicode!
211 hdef = oname + inspect.formatargspec(*getargspec(obj))
197 hdef = oname + inspect.formatargspec(*getargspec(obj))
212 return hdef.encode('ascii')
198 return hdef.encode('ascii')
213 except:
199 except:
214 return None
200 return None
215
201
216 def __head(self,h):
202 def __head(self,h):
217 """Return a header string with proper colors."""
203 """Return a header string with proper colors."""
218 return '%s%s%s' % (self.color_table.active_colors.header,h,
204 return '%s%s%s' % (self.color_table.active_colors.header,h,
219 self.color_table.active_colors.normal)
205 self.color_table.active_colors.normal)
220
206
221 def set_active_scheme(self,scheme):
207 def set_active_scheme(self,scheme):
222 self.color_table.set_active_scheme(scheme)
208 self.color_table.set_active_scheme(scheme)
223 self.parser.color_table.set_active_scheme(scheme)
209 self.parser.color_table.set_active_scheme(scheme)
224
210
225 def noinfo(self,msg,oname):
211 def noinfo(self,msg,oname):
226 """Generic message when no information is found."""
212 """Generic message when no information is found."""
227 print 'No %s found' % msg,
213 print 'No %s found' % msg,
228 if oname:
214 if oname:
229 print 'for %s' % oname
215 print 'for %s' % oname
230 else:
216 else:
231 print
217 print
232
218
233 def pdef(self,obj,oname=''):
219 def pdef(self,obj,oname=''):
234 """Print the definition header for any callable object.
220 """Print the definition header for any callable object.
235
221
236 If the object is a class, print the constructor information."""
222 If the object is a class, print the constructor information."""
237
223
238 if not callable(obj):
224 if not callable(obj):
239 print 'Object is not callable.'
225 print 'Object is not callable.'
240 return
226 return
241
227
242 header = ''
228 header = ''
243
229
244 if inspect.isclass(obj):
230 if inspect.isclass(obj):
245 header = self.__head('Class constructor information:\n')
231 header = self.__head('Class constructor information:\n')
246 obj = obj.__init__
232 obj = obj.__init__
247 elif type(obj) is types.InstanceType:
233 elif type(obj) is types.InstanceType:
248 obj = obj.__call__
234 obj = obj.__call__
249
235
250 output = self._getdef(obj,oname)
236 output = self._getdef(obj,oname)
251 if output is None:
237 if output is None:
252 self.noinfo('definition header',oname)
238 self.noinfo('definition header',oname)
253 else:
239 else:
254 print >>IPython.utils.io.Term.cout, header,self.format(output),
240 print >>IPython.utils.io.Term.cout, header,self.format(output),
255
241
256 def pdoc(self,obj,oname='',formatter = None):
242 def pdoc(self,obj,oname='',formatter = None):
257 """Print the docstring for any object.
243 """Print the docstring for any object.
258
244
259 Optional:
245 Optional:
260 -formatter: a function to run the docstring through for specially
246 -formatter: a function to run the docstring through for specially
261 formatted docstrings."""
247 formatted docstrings."""
262
248
263 head = self.__head # so that itpl can find it even if private
249 head = self.__head # so that itpl can find it even if private
264 ds = getdoc(obj)
250 ds = getdoc(obj)
265 if formatter:
251 if formatter:
266 ds = formatter(ds)
252 ds = formatter(ds)
267 if inspect.isclass(obj):
253 if inspect.isclass(obj):
268 init_ds = getdoc(obj.__init__)
254 init_ds = getdoc(obj.__init__)
269 output = itpl('$head("Class Docstring:")\n'
255 output = itpl('$head("Class Docstring:")\n'
270 '$indent(ds)\n'
256 '$indent(ds)\n'
271 '$head("Constructor Docstring"):\n'
257 '$head("Constructor Docstring"):\n'
272 '$indent(init_ds)')
258 '$indent(init_ds)')
273 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
259 elif (type(obj) is types.InstanceType or isinstance(obj,object)) \
274 and hasattr(obj,'__call__'):
260 and hasattr(obj,'__call__'):
275 call_ds = getdoc(obj.__call__)
261 call_ds = getdoc(obj.__call__)
276 if call_ds:
262 if call_ds:
277 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
263 output = itpl('$head("Class Docstring:")\n$indent(ds)\n'
278 '$head("Calling Docstring:")\n$indent(call_ds)')
264 '$head("Calling Docstring:")\n$indent(call_ds)')
279 else:
265 else:
280 output = ds
266 output = ds
281 else:
267 else:
282 output = ds
268 output = ds
283 if output is None:
269 if output is None:
284 self.noinfo('documentation',oname)
270 self.noinfo('documentation',oname)
285 return
271 return
286 page.page(output)
272 page.page(output)
287
273
288 def psource(self,obj,oname=''):
274 def psource(self,obj,oname=''):
289 """Print the source code for an object."""
275 """Print the source code for an object."""
290
276
291 # Flush the source cache because inspect can return out-of-date source
277 # Flush the source cache because inspect can return out-of-date source
292 linecache.checkcache()
278 linecache.checkcache()
293 try:
279 try:
294 src = getsource(obj)
280 src = getsource(obj)
295 except:
281 except:
296 self.noinfo('source',oname)
282 self.noinfo('source',oname)
297 else:
283 else:
298 page.page(self.format(src))
284 page.page(self.format(src))
299
285
300 def pfile(self,obj,oname=''):
286 def pfile(self,obj,oname=''):
301 """Show the whole file where an object was defined."""
287 """Show the whole file where an object was defined."""
302
288
303 try:
289 try:
304 try:
290 try:
305 lineno = inspect.getsourcelines(obj)[1]
291 lineno = inspect.getsourcelines(obj)[1]
306 except TypeError:
292 except TypeError:
307 # For instances, try the class object like getsource() does
293 # For instances, try the class object like getsource() does
308 if hasattr(obj,'__class__'):
294 if hasattr(obj,'__class__'):
309 lineno = inspect.getsourcelines(obj.__class__)[1]
295 lineno = inspect.getsourcelines(obj.__class__)[1]
310 # Adjust the inspected object so getabsfile() below works
296 # Adjust the inspected object so getabsfile() below works
311 obj = obj.__class__
297 obj = obj.__class__
312 except:
298 except:
313 self.noinfo('file',oname)
299 self.noinfo('file',oname)
314 return
300 return
315
301
316 # We only reach this point if object was successfully queried
302 # We only reach this point if object was successfully queried
317
303
318 # run contents of file through pager starting at line
304 # run contents of file through pager starting at line
319 # where the object is defined
305 # where the object is defined
320 ofile = inspect.getabsfile(obj)
306 ofile = inspect.getabsfile(obj)
321
307
322 if (ofile.endswith('.so') or ofile.endswith('.dll')):
308 if (ofile.endswith('.so') or ofile.endswith('.dll')):
323 print 'File %r is binary, not printing.' % ofile
309 print 'File %r is binary, not printing.' % ofile
324 elif not os.path.isfile(ofile):
310 elif not os.path.isfile(ofile):
325 print 'File %r does not exist, not printing.' % ofile
311 print 'File %r does not exist, not printing.' % ofile
326 else:
312 else:
327 # Print only text files, not extension binaries. Note that
313 # Print only text files, not extension binaries. Note that
328 # getsourcelines returns lineno with 1-offset and page() uses
314 # getsourcelines returns lineno with 1-offset and page() uses
329 # 0-offset, so we must adjust.
315 # 0-offset, so we must adjust.
330 page.page(self.format(open(ofile).read()),lineno-1)
316 page.page(self.format(open(ofile).read()),lineno-1)
331
317
332 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
318 def pinfo(self,obj,oname='',formatter=None,info=None,detail_level=0):
333 """Show detailed information about an object.
319 """Show detailed information about an object.
334
320
335 Optional arguments:
321 Optional arguments:
336
322
337 - oname: name of the variable pointing to the object.
323 - oname: name of the variable pointing to the object.
338
324
339 - formatter: special formatter for docstrings (see pdoc)
325 - formatter: special formatter for docstrings (see pdoc)
340
326
341 - info: a structure with some information fields which may have been
327 - info: a structure with some information fields which may have been
342 precomputed already.
328 precomputed already.
343
329
344 - detail_level: if set to 1, more information is given.
330 - detail_level: if set to 1, more information is given.
345 """
331 """
346
332
347 obj_type = type(obj)
333 obj_type = type(obj)
348
334
349 header = self.__head
335 header = self.__head
350 if info is None:
336 if info is None:
351 ismagic = 0
337 ismagic = 0
352 isalias = 0
338 isalias = 0
353 ospace = ''
339 ospace = ''
354 else:
340 else:
355 ismagic = info.ismagic
341 ismagic = info.ismagic
356 isalias = info.isalias
342 isalias = info.isalias
357 ospace = info.namespace
343 ospace = info.namespace
358 # Get docstring, special-casing aliases:
344 # Get docstring, special-casing aliases:
359 if isalias:
345 if isalias:
360 if not callable(obj):
346 if not callable(obj):
361 try:
347 try:
362 ds = "Alias to the system command:\n %s" % obj[1]
348 ds = "Alias to the system command:\n %s" % obj[1]
363 except:
349 except:
364 ds = "Alias: " + str(obj)
350 ds = "Alias: " + str(obj)
365 else:
351 else:
366 ds = "Alias to " + str(obj)
352 ds = "Alias to " + str(obj)
367 if obj.__doc__:
353 if obj.__doc__:
368 ds += "\nDocstring:\n" + obj.__doc__
354 ds += "\nDocstring:\n" + obj.__doc__
369 else:
355 else:
370 ds = getdoc(obj)
356 ds = getdoc(obj)
371 if ds is None:
357 if ds is None:
372 ds = '<no docstring>'
358 ds = '<no docstring>'
373 if formatter is not None:
359 if formatter is not None:
374 ds = formatter(ds)
360 ds = formatter(ds)
375
361
376 # store output in a list which gets joined with \n at the end.
362 # store output in a list which gets joined with \n at the end.
377 out = myStringIO()
363 out = myStringIO()
378
364
379 string_max = 200 # max size of strings to show (snipped if longer)
365 string_max = 200 # max size of strings to show (snipped if longer)
380 shalf = int((string_max -5)/2)
366 shalf = int((string_max -5)/2)
381
367
382 if ismagic:
368 if ismagic:
383 obj_type_name = 'Magic function'
369 obj_type_name = 'Magic function'
384 elif isalias:
370 elif isalias:
385 obj_type_name = 'System alias'
371 obj_type_name = 'System alias'
386 else:
372 else:
387 obj_type_name = obj_type.__name__
373 obj_type_name = obj_type.__name__
388 out.writeln(header('Type:\t\t')+obj_type_name)
374 out.writeln(header('Type:\t\t')+obj_type_name)
389
375
390 try:
376 try:
391 bclass = obj.__class__
377 bclass = obj.__class__
392 out.writeln(header('Base Class:\t')+str(bclass))
378 out.writeln(header('Base Class:\t')+str(bclass))
393 except: pass
379 except: pass
394
380
395 # String form, but snip if too long in ? form (full in ??)
381 # String form, but snip if too long in ? form (full in ??)
396 if detail_level >= self.str_detail_level:
382 if detail_level >= self.str_detail_level:
397 try:
383 try:
398 ostr = str(obj)
384 ostr = str(obj)
399 str_head = 'String Form:'
385 str_head = 'String Form:'
400 if not detail_level and len(ostr)>string_max:
386 if not detail_level and len(ostr)>string_max:
401 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
387 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
402 ostr = ("\n" + " " * len(str_head.expandtabs())).\
388 ostr = ("\n" + " " * len(str_head.expandtabs())).\
403 join(map(string.strip,ostr.split("\n")))
389 join(map(string.strip,ostr.split("\n")))
404 if ostr.find('\n') > -1:
390 if ostr.find('\n') > -1:
405 # Print multi-line strings starting at the next line.
391 # Print multi-line strings starting at the next line.
406 str_sep = '\n'
392 str_sep = '\n'
407 else:
393 else:
408 str_sep = '\t'
394 str_sep = '\t'
409 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
395 out.writeln("%s%s%s" % (header(str_head),str_sep,ostr))
410 except:
396 except:
411 pass
397 pass
412
398
413 if ospace:
399 if ospace:
414 out.writeln(header('Namespace:\t')+ospace)
400 out.writeln(header('Namespace:\t')+ospace)
415
401
416 # Length (for strings and lists)
402 # Length (for strings and lists)
417 try:
403 try:
418 length = str(len(obj))
404 length = str(len(obj))
419 out.writeln(header('Length:\t\t')+length)
405 out.writeln(header('Length:\t\t')+length)
420 except: pass
406 except: pass
421
407
422 # Filename where object was defined
408 # Filename where object was defined
423 binary_file = False
409 binary_file = False
424 try:
410 try:
425 try:
411 try:
426 fname = inspect.getabsfile(obj)
412 fname = inspect.getabsfile(obj)
427 except TypeError:
413 except TypeError:
428 # For an instance, the file that matters is where its class was
414 # For an instance, the file that matters is where its class was
429 # declared.
415 # declared.
430 if hasattr(obj,'__class__'):
416 if hasattr(obj,'__class__'):
431 fname = inspect.getabsfile(obj.__class__)
417 fname = inspect.getabsfile(obj.__class__)
432 if fname.endswith('<string>'):
418 if fname.endswith('<string>'):
433 fname = 'Dynamically generated function. No source code available.'
419 fname = 'Dynamically generated function. No source code available.'
434 if (fname.endswith('.so') or fname.endswith('.dll')):
420 if (fname.endswith('.so') or fname.endswith('.dll')):
435 binary_file = True
421 binary_file = True
436 out.writeln(header('File:\t\t')+fname)
422 out.writeln(header('File:\t\t')+fname)
437 except:
423 except:
438 # if anything goes wrong, we don't want to show source, so it's as
424 # if anything goes wrong, we don't want to show source, so it's as
439 # if the file was binary
425 # if the file was binary
440 binary_file = True
426 binary_file = True
441
427
442 # reconstruct the function definition and print it:
428 # reconstruct the function definition and print it:
443 defln = self._getdef(obj,oname)
429 defln = self._getdef(obj,oname)
444 if defln:
430 if defln:
445 out.write(header('Definition:\t')+self.format(defln))
431 out.write(header('Definition:\t')+self.format(defln))
446
432
447 # Docstrings only in detail 0 mode, since source contains them (we
433 # Docstrings only in detail 0 mode, since source contains them (we
448 # avoid repetitions). If source fails, we add them back, see below.
434 # avoid repetitions). If source fails, we add them back, see below.
449 if ds and detail_level == 0:
435 if ds and detail_level == 0:
450 out.writeln(header('Docstring:\n') + indent(ds))
436 out.writeln(header('Docstring:\n') + indent(ds))
451
437
452 # Original source code for any callable
438 # Original source code for any callable
453 if detail_level:
439 if detail_level:
454 # Flush the source cache because inspect can return out-of-date
440 # Flush the source cache because inspect can return out-of-date
455 # source
441 # source
456 linecache.checkcache()
442 linecache.checkcache()
457 source_success = False
443 source_success = False
458 try:
444 try:
459 try:
445 try:
460 src = getsource(obj,binary_file)
446 src = getsource(obj,binary_file)
461 except TypeError:
447 except TypeError:
462 if hasattr(obj,'__class__'):
448 if hasattr(obj,'__class__'):
463 src = getsource(obj.__class__,binary_file)
449 src = getsource(obj.__class__,binary_file)
464 if src is not None:
450 if src is not None:
465 source = self.format(src)
451 source = self.format(src)
466 out.write(header('Source:\n')+source.rstrip())
452 out.write(header('Source:\n')+source.rstrip())
467 source_success = True
453 source_success = True
468 except Exception, msg:
454 except Exception, msg:
469 pass
455 pass
470
456
471 if ds and not source_success:
457 if ds and not source_success:
472 out.writeln(header('Docstring [source file open failed]:\n')
458 out.writeln(header('Docstring [source file open failed]:\n')
473 + indent(ds))
459 + indent(ds))
474
460
475 # Constructor docstring for classes
461 # Constructor docstring for classes
476 if inspect.isclass(obj):
462 if inspect.isclass(obj):
477 # reconstruct the function definition and print it:
463 # reconstruct the function definition and print it:
478 try:
464 try:
479 obj_init = obj.__init__
465 obj_init = obj.__init__
480 except AttributeError:
466 except AttributeError:
481 init_def = init_ds = None
467 init_def = init_ds = None
482 else:
468 else:
483 init_def = self._getdef(obj_init,oname)
469 init_def = self._getdef(obj_init,oname)
484 init_ds = getdoc(obj_init)
470 init_ds = getdoc(obj_init)
485 # Skip Python's auto-generated docstrings
471 # Skip Python's auto-generated docstrings
486 if init_ds and \
472 if init_ds and \
487 init_ds.startswith('x.__init__(...) initializes'):
473 init_ds.startswith('x.__init__(...) initializes'):
488 init_ds = None
474 init_ds = None
489
475
490 if init_def or init_ds:
476 if init_def or init_ds:
491 out.writeln(header('\nConstructor information:'))
477 out.writeln(header('\nConstructor information:'))
492 if init_def:
478 if init_def:
493 out.write(header('Definition:\t')+ self.format(init_def))
479 out.write(header('Definition:\t')+ self.format(init_def))
494 if init_ds:
480 if init_ds:
495 out.writeln(header('Docstring:\n') + indent(init_ds))
481 out.writeln(header('Docstring:\n') + indent(init_ds))
496 # and class docstring for instances:
482 # and class docstring for instances:
497 elif obj_type is types.InstanceType or \
483 elif obj_type is types.InstanceType or \
498 isinstance(obj,object):
484 isinstance(obj,object):
499
485
500 # First, check whether the instance docstring is identical to the
486 # First, check whether the instance docstring is identical to the
501 # class one, and print it separately if they don't coincide. In
487 # class one, and print it separately if they don't coincide. In
502 # most cases they will, but it's nice to print all the info for
488 # most cases they will, but it's nice to print all the info for
503 # objects which use instance-customized docstrings.
489 # objects which use instance-customized docstrings.
504 if ds:
490 if ds:
505 try:
491 try:
506 cls = getattr(obj,'__class__')
492 cls = getattr(obj,'__class__')
507 except:
493 except:
508 class_ds = None
494 class_ds = None
509 else:
495 else:
510 class_ds = getdoc(cls)
496 class_ds = getdoc(cls)
511 # Skip Python's auto-generated docstrings
497 # Skip Python's auto-generated docstrings
512 if class_ds and \
498 if class_ds and \
513 (class_ds.startswith('function(code, globals[,') or \
499 (class_ds.startswith('function(code, globals[,') or \
514 class_ds.startswith('instancemethod(function, instance,') or \
500 class_ds.startswith('instancemethod(function, instance,') or \
515 class_ds.startswith('module(name[,') ):
501 class_ds.startswith('module(name[,') ):
516 class_ds = None
502 class_ds = None
517 if class_ds and ds != class_ds:
503 if class_ds and ds != class_ds:
518 out.writeln(header('Class Docstring:\n') +
504 out.writeln(header('Class Docstring:\n') +
519 indent(class_ds))
505 indent(class_ds))
520
506
521 # Next, try to show constructor docstrings
507 # Next, try to show constructor docstrings
522 try:
508 try:
523 init_ds = getdoc(obj.__init__)
509 init_ds = getdoc(obj.__init__)
524 # Skip Python's auto-generated docstrings
510 # Skip Python's auto-generated docstrings
525 if init_ds and \
511 if init_ds and \
526 init_ds.startswith('x.__init__(...) initializes'):
512 init_ds.startswith('x.__init__(...) initializes'):
527 init_ds = None
513 init_ds = None
528 except AttributeError:
514 except AttributeError:
529 init_ds = None
515 init_ds = None
530 if init_ds:
516 if init_ds:
531 out.writeln(header('Constructor Docstring:\n') +
517 out.writeln(header('Constructor Docstring:\n') +
532 indent(init_ds))
518 indent(init_ds))
533
519
534 # Call form docstring for callable instances
520 # Call form docstring for callable instances
535 if hasattr(obj,'__call__'):
521 if hasattr(obj,'__call__'):
536 #out.writeln(header('Callable:\t')+'Yes')
522 #out.writeln(header('Callable:\t')+'Yes')
537 call_def = self._getdef(obj.__call__,oname)
523 call_def = self._getdef(obj.__call__,oname)
538 #if call_def is None:
524 #if call_def is None:
539 # out.writeln(header('Call def:\t')+
525 # out.writeln(header('Call def:\t')+
540 # 'Calling definition not available.')
526 # 'Calling definition not available.')
541 if call_def is not None:
527 if call_def is not None:
542 out.writeln(header('Call def:\t')+self.format(call_def))
528 out.writeln(header('Call def:\t')+self.format(call_def))
543 call_ds = getdoc(obj.__call__)
529 call_ds = getdoc(obj.__call__)
544 # Skip Python's auto-generated docstrings
530 # Skip Python's auto-generated docstrings
545 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
531 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
546 call_ds = None
532 call_ds = None
547 if call_ds:
533 if call_ds:
548 out.writeln(header('Call docstring:\n') + indent(call_ds))
534 out.writeln(header('Call docstring:\n') + indent(call_ds))
549
535
550 # Finally send to printer/pager
536 # Finally send to printer/pager
551 output = out.getvalue()
537 output = out.getvalue()
552 if output:
538 if output:
553 page.page(output)
539 page.page(output)
554 # end pinfo
540 # end pinfo
555
541
542 def info(self, obj, oname='', formatter=None, info=None, detail_level=0):
543 """Compute a dict with detailed information about an object.
544
545 Optional arguments:
546
547 - oname: name of the variable pointing to the object.
548
549 - formatter: special formatter for docstrings (see pdoc)
550
551 - info: a structure with some information fields which may have been
552 precomputed already.
553
554 - detail_level: if set to 1, more information is given.
555 """
556
557 obj_type = type(obj)
558
559 header = self.__head
560 if info is None:
561 ismagic = 0
562 isalias = 0
563 ospace = ''
564 else:
565 ismagic = info.ismagic
566 isalias = info.isalias
567 ospace = info.namespace
568 # Get docstring, special-casing aliases:
569 if isalias:
570 if not callable(obj):
571 try:
572 ds = "Alias to the system command:\n %s" % obj[1]
573 except:
574 ds = "Alias: " + str(obj)
575 else:
576 ds = "Alias to " + str(obj)
577 if obj.__doc__:
578 ds += "\nDocstring:\n" + obj.__doc__
579 else:
580 ds = getdoc(obj)
581 if ds is None:
582 ds = '<no docstring>'
583 if formatter is not None:
584 ds = formatter(ds)
585
586 # store output in a dict, we'll later convert it to an ObjectInfo
587 out = {}
588
589 string_max = 200 # max size of strings to show (snipped if longer)
590 shalf = int((string_max -5)/2)
591
592 if ismagic:
593 obj_type_name = 'Magic function'
594 elif isalias:
595 obj_type_name = 'System alias'
596 else:
597 obj_type_name = obj_type.__name__
598 out['type_name'] = obj_type_name
599
600 try:
601 bclass = obj.__class__
602 out['base_class'] = str(bclass)
603 except: pass
604
605 # String form, but snip if too long in ? form (full in ??)
606 if detail_level >= self.str_detail_level:
607 try:
608 ostr = str(obj)
609 str_head = 'string_form'
610 if not detail_level and len(ostr)>string_max:
611 ostr = ostr[:shalf] + ' <...> ' + ostr[-shalf:]
612 ostr = ("\n" + " " * len(str_head.expandtabs())).\
613 join(map(string.strip,ostr.split("\n")))
614 if ostr.find('\n') > -1:
615 # Print multi-line strings starting at the next line.
616 str_sep = '\n'
617 else:
618 str_sep = '\t'
619 out[str_head] = ostr
620 except:
621 pass
622
623 if ospace:
624 out['namespace'] = ospace
625
626 # Length (for strings and lists)
627 try:
628 out['length'] = str(len(obj))
629 except: pass
630
631 # Filename where object was defined
632 binary_file = False
633 try:
634 try:
635 fname = inspect.getabsfile(obj)
636 except TypeError:
637 # For an instance, the file that matters is where its class was
638 # declared.
639 if hasattr(obj,'__class__'):
640 fname = inspect.getabsfile(obj.__class__)
641 if fname.endswith('<string>'):
642 fname = 'Dynamically generated function. No source code available.'
643 if (fname.endswith('.so') or fname.endswith('.dll')):
644 binary_file = True
645 out['file'] = fname
646 except:
647 # if anything goes wrong, we don't want to show source, so it's as
648 # if the file was binary
649 binary_file = True
650
651 # reconstruct the function definition and print it:
652 defln = self._getdef(obj,oname)
653 if defln:
654 out['definition'] = self.format(defln)
655
656 # Docstrings only in detail 0 mode, since source contains them (we
657 # avoid repetitions). If source fails, we add them back, see below.
658 if ds and detail_level == 0:
659 out['docstring'] = indent(ds)
660
661 # Original source code for any callable
662 if detail_level:
663 # Flush the source cache because inspect can return out-of-date
664 # source
665 linecache.checkcache()
666 source_success = False
667 try:
668 try:
669 src = getsource(obj,binary_file)
670 except TypeError:
671 if hasattr(obj,'__class__'):
672 src = getsource(obj.__class__,binary_file)
673 if src is not None:
674 source = self.format(src)
675 out['source'] = source.rstrip()
676 source_success = True
677 except Exception, msg:
678 pass
679
680 # Constructor docstring for classes
681 if inspect.isclass(obj):
682 # reconstruct the function definition and print it:
683 try:
684 obj_init = obj.__init__
685 except AttributeError:
686 init_def = init_ds = None
687 else:
688 init_def = self._getdef(obj_init,oname)
689 init_ds = getdoc(obj_init)
690 # Skip Python's auto-generated docstrings
691 if init_ds and \
692 init_ds.startswith('x.__init__(...) initializes'):
693 init_ds = None
694
695 if init_def or init_ds:
696 if init_def:
697 out['init_definition'] = self.format(init_def)
698 if init_ds:
699 out['init_docstring'] = indent(init_ds)
700 # and class docstring for instances:
701 elif obj_type is types.InstanceType or \
702 isinstance(obj,object):
703
704 # First, check whether the instance docstring is identical to the
705 # class one, and print it separately if they don't coincide. In
706 # most cases they will, but it's nice to print all the info for
707 # objects which use instance-customized docstrings.
708 if ds:
709 try:
710 cls = getattr(obj,'__class__')
711 except:
712 class_ds = None
713 else:
714 class_ds = getdoc(cls)
715 # Skip Python's auto-generated docstrings
716 if class_ds and \
717 (class_ds.startswith('function(code, globals[,') or \
718 class_ds.startswith('instancemethod(function, instance,') or \
719 class_ds.startswith('module(name[,') ):
720 class_ds = None
721 if class_ds and ds != class_ds:
722 out['class_docstring'] = indent(class_ds)
723
724 # Next, try to show constructor docstrings
725 try:
726 init_ds = getdoc(obj.__init__)
727 # Skip Python's auto-generated docstrings
728 if init_ds and \
729 init_ds.startswith('x.__init__(...) initializes'):
730 init_ds = None
731 except AttributeError:
732 init_ds = None
733 if init_ds:
734 out['init_docstring'] = indent(init_ds)
735
736 # Call form docstring for callable instances
737 if hasattr(obj,'__call__'):
738 call_def = self._getdef(obj.__call__,oname)
739 if call_def is not None:
740 out['call_def'] = self.format(call_def)
741 call_ds = getdoc(obj.__call__)
742 # Skip Python's auto-generated docstrings
743 if call_ds and call_ds.startswith('x.__call__(...) <==> x(...)'):
744 call_ds = None
745 if call_ds:
746 out['call_docstring'] = indent(call_ds)
747
748 return mk_object_info(out)
749
750
556 def psearch(self,pattern,ns_table,ns_search=[],
751 def psearch(self,pattern,ns_table,ns_search=[],
557 ignore_case=False,show_all=False):
752 ignore_case=False,show_all=False):
558 """Search namespaces with wildcards for objects.
753 """Search namespaces with wildcards for objects.
559
754
560 Arguments:
755 Arguments:
561
756
562 - pattern: string containing shell-like wildcards to use in namespace
757 - pattern: string containing shell-like wildcards to use in namespace
563 searches and optionally a type specification to narrow the search to
758 searches and optionally a type specification to narrow the search to
564 objects of that type.
759 objects of that type.
565
760
566 - ns_table: dict of name->namespaces for search.
761 - ns_table: dict of name->namespaces for search.
567
762
568 Optional arguments:
763 Optional arguments:
569
764
570 - ns_search: list of namespace names to include in search.
765 - ns_search: list of namespace names to include in search.
571
766
572 - ignore_case(False): make the search case-insensitive.
767 - ignore_case(False): make the search case-insensitive.
573
768
574 - show_all(False): show all names, including those starting with
769 - show_all(False): show all names, including those starting with
575 underscores.
770 underscores.
576 """
771 """
577 #print 'ps pattern:<%r>' % pattern # dbg
772 #print 'ps pattern:<%r>' % pattern # dbg
578
773
579 # defaults
774 # defaults
580 type_pattern = 'all'
775 type_pattern = 'all'
581 filter = ''
776 filter = ''
582
777
583 cmds = pattern.split()
778 cmds = pattern.split()
584 len_cmds = len(cmds)
779 len_cmds = len(cmds)
585 if len_cmds == 1:
780 if len_cmds == 1:
586 # Only filter pattern given
781 # Only filter pattern given
587 filter = cmds[0]
782 filter = cmds[0]
588 elif len_cmds == 2:
783 elif len_cmds == 2:
589 # Both filter and type specified
784 # Both filter and type specified
590 filter,type_pattern = cmds
785 filter,type_pattern = cmds
591 else:
786 else:
592 raise ValueError('invalid argument string for psearch: <%s>' %
787 raise ValueError('invalid argument string for psearch: <%s>' %
593 pattern)
788 pattern)
594
789
595 # filter search namespaces
790 # filter search namespaces
596 for name in ns_search:
791 for name in ns_search:
597 if name not in ns_table:
792 if name not in ns_table:
598 raise ValueError('invalid namespace <%s>. Valid names: %s' %
793 raise ValueError('invalid namespace <%s>. Valid names: %s' %
599 (name,ns_table.keys()))
794 (name,ns_table.keys()))
600
795
601 #print 'type_pattern:',type_pattern # dbg
796 #print 'type_pattern:',type_pattern # dbg
602 search_result = []
797 search_result = []
603 for ns_name in ns_search:
798 for ns_name in ns_search:
604 ns = ns_table[ns_name]
799 ns = ns_table[ns_name]
605 tmp_res = list(list_namespace(ns,type_pattern,filter,
800 tmp_res = list(list_namespace(ns,type_pattern,filter,
606 ignore_case=ignore_case,
801 ignore_case=ignore_case,
607 show_all=show_all))
802 show_all=show_all))
608 search_result.extend(tmp_res)
803 search_result.extend(tmp_res)
609 search_result.sort()
804 search_result.sort()
610
805
611 page.page('\n'.join(search_result))
806 page.page('\n'.join(search_result))
@@ -1,486 +1,487 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 sys
20 import sys
21 import time
21 import time
22 import traceback
22 import traceback
23
23
24 # System library imports.
24 # System library imports.
25 import zmq
25 import zmq
26
26
27 # Local imports.
27 # Local imports.
28 from IPython.config.configurable import Configurable
28 from IPython.config.configurable import Configurable
29 from IPython.utils import io
29 from IPython.utils import io
30 from IPython.lib import pylabtools
30 from IPython.lib import pylabtools
31 from IPython.utils.traitlets import Instance
31 from IPython.utils.traitlets import Instance
32 from entry_point import base_launch_kernel, make_argument_parser, make_kernel, \
32 from entry_point import base_launch_kernel, make_argument_parser, make_kernel, \
33 start_kernel
33 start_kernel
34 from iostream import OutStream
34 from iostream import OutStream
35 from session import Session, Message
35 from session import Session, Message
36 from zmqshell import ZMQInteractiveShell
36 from zmqshell import ZMQInteractiveShell
37
37
38
38
39 #-----------------------------------------------------------------------------
39 #-----------------------------------------------------------------------------
40 # Main kernel class
40 # Main kernel class
41 #-----------------------------------------------------------------------------
41 #-----------------------------------------------------------------------------
42
42
43 class Kernel(Configurable):
43 class Kernel(Configurable):
44
44
45 #---------------------------------------------------------------------------
45 #---------------------------------------------------------------------------
46 # Kernel interface
46 # Kernel interface
47 #---------------------------------------------------------------------------
47 #---------------------------------------------------------------------------
48
48
49 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
49 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
50 session = Instance(Session)
50 session = Instance(Session)
51 reply_socket = Instance('zmq.Socket')
51 reply_socket = Instance('zmq.Socket')
52 pub_socket = Instance('zmq.Socket')
52 pub_socket = Instance('zmq.Socket')
53 req_socket = Instance('zmq.Socket')
53 req_socket = Instance('zmq.Socket')
54
54
55 def __init__(self, **kwargs):
55 def __init__(self, **kwargs):
56 super(Kernel, self).__init__(**kwargs)
56 super(Kernel, self).__init__(**kwargs)
57
57
58 # Initialize the InteractiveShell subclass
58 # Initialize the InteractiveShell subclass
59 self.shell = ZMQInteractiveShell.instance()
59 self.shell = ZMQInteractiveShell.instance()
60 self.shell.displayhook.session = self.session
60 self.shell.displayhook.session = self.session
61 self.shell.displayhook.pub_socket = self.pub_socket
61 self.shell.displayhook.pub_socket = self.pub_socket
62
62
63 # TMP - hack while developing
63 # TMP - hack while developing
64 self.shell._reply_content = None
64 self.shell._reply_content = None
65
65
66 # Build dict of handlers for message types
66 # Build dict of handlers for message types
67 msg_types = [ 'execute_request', 'complete_request',
67 msg_types = [ 'execute_request', 'complete_request',
68 'object_info_request', 'history_request' ]
68 'object_info_request', 'history_request' ]
69 self.handlers = {}
69 self.handlers = {}
70 for msg_type in msg_types:
70 for msg_type in msg_types:
71 self.handlers[msg_type] = getattr(self, msg_type)
71 self.handlers[msg_type] = getattr(self, msg_type)
72
72
73 def do_one_iteration(self):
73 def do_one_iteration(self):
74 try:
74 try:
75 ident = self.reply_socket.recv(zmq.NOBLOCK)
75 ident = self.reply_socket.recv(zmq.NOBLOCK)
76 except zmq.ZMQError, e:
76 except zmq.ZMQError, e:
77 if e.errno == zmq.EAGAIN:
77 if e.errno == zmq.EAGAIN:
78 return
78 return
79 else:
79 else:
80 raise
80 raise
81 # FIXME: Bug in pyzmq/zmq?
81 # FIXME: Bug in pyzmq/zmq?
82 # assert self.reply_socket.rcvmore(), "Missing message part."
82 # assert self.reply_socket.rcvmore(), "Missing message part."
83 msg = self.reply_socket.recv_json()
83 msg = self.reply_socket.recv_json()
84
84
85 # Print some info about this message and leave a '--->' marker, so it's
85 # Print some info about this message and leave a '--->' marker, so it's
86 # easier to trace visually the message chain when debugging. Each
86 # easier to trace visually the message chain when debugging. Each
87 # handler prints its message at the end.
87 # handler prints its message at the end.
88 # Eventually we'll move these from stdout to a logger.
88 # Eventually we'll move these from stdout to a logger.
89 io.raw_print('\n*** MESSAGE TYPE:', msg['msg_type'], '***')
89 io.raw_print('\n*** MESSAGE TYPE:', msg['msg_type'], '***')
90 io.raw_print(' Content: ', msg['content'],
90 io.raw_print(' Content: ', msg['content'],
91 '\n --->\n ', sep='', end='')
91 '\n --->\n ', sep='', end='')
92
92
93 # Find and call actual handler for message
93 # Find and call actual handler for message
94 handler = self.handlers.get(msg['msg_type'], None)
94 handler = self.handlers.get(msg['msg_type'], None)
95 if handler is None:
95 if handler is None:
96 io.raw_print_err("UNKNOWN MESSAGE TYPE:", msg)
96 io.raw_print_err("UNKNOWN MESSAGE TYPE:", msg)
97 else:
97 else:
98 handler(ident, msg)
98 handler(ident, msg)
99
99
100 def start(self):
100 def start(self):
101 """ Start the kernel main loop.
101 """ Start the kernel main loop.
102 """
102 """
103 while True:
103 while True:
104 time.sleep(0.05)
104 time.sleep(0.05)
105 self.do_one_iteration()
105 self.do_one_iteration()
106
106
107 #---------------------------------------------------------------------------
107 #---------------------------------------------------------------------------
108 # Kernel request handlers
108 # Kernel request handlers
109 #---------------------------------------------------------------------------
109 #---------------------------------------------------------------------------
110
110
111 def _publish_pyin(self, code, parent):
111 def _publish_pyin(self, code, parent):
112 """Publish the code request on the pyin stream."""
112 """Publish the code request on the pyin stream."""
113
113
114 pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
114 pyin_msg = self.session.msg(u'pyin',{u'code':code}, parent=parent)
115 self.pub_socket.send_json(pyin_msg)
115 self.pub_socket.send_json(pyin_msg)
116
116
117 def execute_request(self, ident, parent):
117 def execute_request(self, ident, parent):
118 try:
118 try:
119 content = parent[u'content']
119 content = parent[u'content']
120 code = content[u'code']
120 code = content[u'code']
121 silent = content[u'silent']
121 silent = content[u'silent']
122 except:
122 except:
123 io.raw_print_err("Got bad msg: ")
123 io.raw_print_err("Got bad msg: ")
124 io.raw_print_err(Message(parent))
124 io.raw_print_err(Message(parent))
125 return
125 return
126
126
127 shell = self.shell # we'll need this a lot here
127 shell = self.shell # we'll need this a lot here
128
128
129 # Replace raw_input. Note that is not sufficient to replace
129 # Replace raw_input. Note that is not sufficient to replace
130 # raw_input in the user namespace.
130 # raw_input in the user namespace.
131 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
131 raw_input = lambda prompt='': self._raw_input(prompt, ident, parent)
132 __builtin__.raw_input = raw_input
132 __builtin__.raw_input = raw_input
133
133
134 # Set the parent message of the display hook and out streams.
134 # Set the parent message of the display hook and out streams.
135 shell.displayhook.set_parent(parent)
135 shell.displayhook.set_parent(parent)
136 sys.stdout.set_parent(parent)
136 sys.stdout.set_parent(parent)
137 sys.stderr.set_parent(parent)
137 sys.stderr.set_parent(parent)
138
138
139 # Re-broadcast our input for the benefit of listening clients, and
139 # Re-broadcast our input for the benefit of listening clients, and
140 # start computing output
140 # start computing output
141 if not silent:
141 if not silent:
142 self._publish_pyin(code, parent)
142 self._publish_pyin(code, parent)
143
143
144 reply_content = {}
144 reply_content = {}
145 try:
145 try:
146 if silent:
146 if silent:
147 # runcode uses 'exec' mode, so no displayhook will fire, and it
147 # runcode uses 'exec' mode, so no displayhook will fire, and it
148 # doesn't call logging or history manipulations. Print
148 # doesn't call logging or history manipulations. Print
149 # statements in that code will obviously still execute.
149 # statements in that code will obviously still execute.
150 shell.runcode(code)
150 shell.runcode(code)
151 else:
151 else:
152 # FIXME: runlines calls the exception handler itself.
152 # FIXME: runlines calls the exception handler itself.
153 shell._reply_content = None
153 shell._reply_content = None
154 shell.runlines(code)
154 shell.runlines(code)
155 except:
155 except:
156 status = u'error'
156 status = u'error'
157 # FIXME: this code right now isn't being used yet by default,
157 # FIXME: this code right now isn't being used yet by default,
158 # because the runlines() call above directly fires off exception
158 # because the runlines() call above directly fires off exception
159 # reporting. This code, therefore, is only active in the scenario
159 # reporting. This code, therefore, is only active in the scenario
160 # where runlines itself has an unhandled exception. We need to
160 # where runlines itself has an unhandled exception. We need to
161 # uniformize this, for all exception construction to come from a
161 # uniformize this, for all exception construction to come from a
162 # single location in the codbase.
162 # single location in the codbase.
163 etype, evalue, tb = sys.exc_info()
163 etype, evalue, tb = sys.exc_info()
164 tb_list = traceback.format_exception(etype, evalue, tb)
164 tb_list = traceback.format_exception(etype, evalue, tb)
165 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
165 reply_content.update(shell._showtraceback(etype, evalue, tb_list))
166 else:
166 else:
167 status = u'ok'
167 status = u'ok'
168 reply_content[u'payload'] = shell.payload_manager.read_payload()
168 reply_content[u'payload'] = shell.payload_manager.read_payload()
169 # Be agressive about clearing the payload because we don't want
169 # Be agressive about clearing the payload because we don't want
170 # it to sit in memory until the next execute_request comes in.
170 # it to sit in memory until the next execute_request comes in.
171 shell.payload_manager.clear_payload()
171 shell.payload_manager.clear_payload()
172
172
173 reply_content[u'status'] = status
173 reply_content[u'status'] = status
174 # Compute the execution counter so clients can display prompts
174 # Compute the execution counter so clients can display prompts
175 reply_content['execution_count'] = shell.displayhook.prompt_count
175 reply_content['execution_count'] = shell.displayhook.prompt_count
176
176
177 # FIXME - fish exception info out of shell, possibly left there by
177 # FIXME - fish exception info out of shell, possibly left there by
178 # runlines. We'll need to clean up this logic later.
178 # runlines. We'll need to clean up this logic later.
179 if shell._reply_content is not None:
179 if shell._reply_content is not None:
180 reply_content.update(shell._reply_content)
180 reply_content.update(shell._reply_content)
181
181
182 # At this point, we can tell whether the main code execution succeeded
182 # At this point, we can tell whether the main code execution succeeded
183 # or not. If it did, we proceed to evaluate user_variables/expressions
183 # or not. If it did, we proceed to evaluate user_variables/expressions
184 if reply_content['status'] == 'ok':
184 if reply_content['status'] == 'ok':
185 reply_content[u'user_variables'] = \
185 reply_content[u'user_variables'] = \
186 shell.get_user_variables(content[u'user_variables'])
186 shell.get_user_variables(content[u'user_variables'])
187 reply_content[u'user_expressions'] = \
187 reply_content[u'user_expressions'] = \
188 shell.eval_expressions(content[u'user_expressions'])
188 shell.eval_expressions(content[u'user_expressions'])
189 else:
189 else:
190 # If there was an error, don't even try to compute variables or
190 # If there was an error, don't even try to compute variables or
191 # expressions
191 # expressions
192 reply_content[u'user_variables'] = {}
192 reply_content[u'user_variables'] = {}
193 reply_content[u'user_expressions'] = {}
193 reply_content[u'user_expressions'] = {}
194
194
195 # Send the reply.
195 # Send the reply.
196 reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
196 reply_msg = self.session.msg(u'execute_reply', reply_content, parent)
197 io.raw_print(reply_msg)
197 io.raw_print(reply_msg)
198 self.reply_socket.send(ident, zmq.SNDMORE)
198 self.reply_socket.send(ident, zmq.SNDMORE)
199 self.reply_socket.send_json(reply_msg)
199 self.reply_socket.send_json(reply_msg)
200 if reply_msg['content']['status'] == u'error':
200 if reply_msg['content']['status'] == u'error':
201 self._abort_queue()
201 self._abort_queue()
202
202
203 def complete_request(self, ident, parent):
203 def complete_request(self, ident, parent):
204 txt, matches = self._complete(parent)
204 txt, matches = self._complete(parent)
205 matches = {'matches' : matches,
205 matches = {'matches' : matches,
206 'matched_text' : txt,
206 'matched_text' : txt,
207 'status' : 'ok'}
207 'status' : 'ok'}
208 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
208 completion_msg = self.session.send(self.reply_socket, 'complete_reply',
209 matches, parent, ident)
209 matches, parent, ident)
210 io.raw_print(completion_msg)
210 io.raw_print(completion_msg)
211
211
212 def object_info_request(self, ident, parent):
212 def object_info_request(self, ident, parent):
213 context = parent['content']['oname'].split('.')
213 ##context = parent['content']['oname'].split('.')
214 object_info = self._object_info(context)
214 ##object_info = self._object_info(context)
215 object_info = self.shell.object_inspect(parent['content']['oname'])
215 msg = self.session.send(self.reply_socket, 'object_info_reply',
216 msg = self.session.send(self.reply_socket, 'object_info_reply',
216 object_info, parent, ident)
217 object_info._asdict(), parent, ident)
217 io.raw_print(msg)
218 io.raw_print(msg)
218
219
219 def history_request(self, ident, parent):
220 def history_request(self, ident, parent):
220 output = parent['content']['output']
221 output = parent['content']['output']
221 index = parent['content']['index']
222 index = parent['content']['index']
222 raw = parent['content']['raw']
223 raw = parent['content']['raw']
223 hist = self.shell.get_history(index=index, raw=raw, output=output)
224 hist = self.shell.get_history(index=index, raw=raw, output=output)
224 content = {'history' : hist}
225 content = {'history' : hist}
225 msg = self.session.send(self.reply_socket, 'history_reply',
226 msg = self.session.send(self.reply_socket, 'history_reply',
226 content, parent, ident)
227 content, parent, ident)
227 io.raw_print(msg)
228 io.raw_print(msg)
228
229
229 #---------------------------------------------------------------------------
230 #---------------------------------------------------------------------------
230 # Protected interface
231 # Protected interface
231 #---------------------------------------------------------------------------
232 #---------------------------------------------------------------------------
232
233
233 def _abort_queue(self):
234 def _abort_queue(self):
234 while True:
235 while True:
235 try:
236 try:
236 ident = self.reply_socket.recv(zmq.NOBLOCK)
237 ident = self.reply_socket.recv(zmq.NOBLOCK)
237 except zmq.ZMQError, e:
238 except zmq.ZMQError, e:
238 if e.errno == zmq.EAGAIN:
239 if e.errno == zmq.EAGAIN:
239 break
240 break
240 else:
241 else:
241 assert self.reply_socket.rcvmore(), \
242 assert self.reply_socket.rcvmore(), \
242 "Unexpected missing message part."
243 "Unexpected missing message part."
243 msg = self.reply_socket.recv_json()
244 msg = self.reply_socket.recv_json()
244 io.raw_print("Aborting:\n", Message(msg))
245 io.raw_print("Aborting:\n", Message(msg))
245 msg_type = msg['msg_type']
246 msg_type = msg['msg_type']
246 reply_type = msg_type.split('_')[0] + '_reply'
247 reply_type = msg_type.split('_')[0] + '_reply'
247 reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
248 reply_msg = self.session.msg(reply_type, {'status' : 'aborted'}, msg)
248 io.raw_print(reply_msg)
249 io.raw_print(reply_msg)
249 self.reply_socket.send(ident,zmq.SNDMORE)
250 self.reply_socket.send(ident,zmq.SNDMORE)
250 self.reply_socket.send_json(reply_msg)
251 self.reply_socket.send_json(reply_msg)
251 # We need to wait a bit for requests to come in. This can probably
252 # We need to wait a bit for requests to come in. This can probably
252 # be set shorter for true asynchronous clients.
253 # be set shorter for true asynchronous clients.
253 time.sleep(0.1)
254 time.sleep(0.1)
254
255
255 def _raw_input(self, prompt, ident, parent):
256 def _raw_input(self, prompt, ident, parent):
256 # Flush output before making the request.
257 # Flush output before making the request.
257 sys.stderr.flush()
258 sys.stderr.flush()
258 sys.stdout.flush()
259 sys.stdout.flush()
259
260
260 # Send the input request.
261 # Send the input request.
261 content = dict(prompt=prompt)
262 content = dict(prompt=prompt)
262 msg = self.session.msg(u'input_request', content, parent)
263 msg = self.session.msg(u'input_request', content, parent)
263 self.req_socket.send_json(msg)
264 self.req_socket.send_json(msg)
264
265
265 # Await a response.
266 # Await a response.
266 reply = self.req_socket.recv_json()
267 reply = self.req_socket.recv_json()
267 try:
268 try:
268 value = reply['content']['value']
269 value = reply['content']['value']
269 except:
270 except:
270 io.raw_print_err("Got bad raw_input reply: ")
271 io.raw_print_err("Got bad raw_input reply: ")
271 io.raw_print_err(Message(parent))
272 io.raw_print_err(Message(parent))
272 value = ''
273 value = ''
273 return value
274 return value
274
275
275 def _complete(self, msg):
276 def _complete(self, msg):
276 c = msg['content']
277 c = msg['content']
277 try:
278 try:
278 cpos = int(c['cursor_pos'])
279 cpos = int(c['cursor_pos'])
279 except:
280 except:
280 # If we don't get something that we can convert to an integer, at
281 # If we don't get something that we can convert to an integer, at
281 # least attempt the completion guessing the cursor is at the end of
282 # least attempt the completion guessing the cursor is at the end of
282 # the text, if there's any, and otherwise of the line
283 # the text, if there's any, and otherwise of the line
283 cpos = len(c['text'])
284 cpos = len(c['text'])
284 if cpos==0:
285 if cpos==0:
285 cpos = len(c['line'])
286 cpos = len(c['line'])
286 return self.shell.complete(c['text'], c['line'], cpos)
287 return self.shell.complete(c['text'], c['line'], cpos)
287
288
288 def _object_info(self, context):
289 def _object_info(self, context):
289 symbol, leftover = self._symbol_from_context(context)
290 symbol, leftover = self._symbol_from_context(context)
290 if symbol is not None and not leftover:
291 if symbol is not None and not leftover:
291 doc = getattr(symbol, '__doc__', '')
292 doc = getattr(symbol, '__doc__', '')
292 else:
293 else:
293 doc = ''
294 doc = ''
294 object_info = dict(docstring = doc)
295 object_info = dict(docstring = doc)
295 return object_info
296 return object_info
296
297
297 def _symbol_from_context(self, context):
298 def _symbol_from_context(self, context):
298 if not context:
299 if not context:
299 return None, context
300 return None, context
300
301
301 base_symbol_string = context[0]
302 base_symbol_string = context[0]
302 symbol = self.shell.user_ns.get(base_symbol_string, None)
303 symbol = self.shell.user_ns.get(base_symbol_string, None)
303 if symbol is None:
304 if symbol is None:
304 symbol = __builtin__.__dict__.get(base_symbol_string, None)
305 symbol = __builtin__.__dict__.get(base_symbol_string, None)
305 if symbol is None:
306 if symbol is None:
306 return None, context
307 return None, context
307
308
308 context = context[1:]
309 context = context[1:]
309 for i, name in enumerate(context):
310 for i, name in enumerate(context):
310 new_symbol = getattr(symbol, name, None)
311 new_symbol = getattr(symbol, name, None)
311 if new_symbol is None:
312 if new_symbol is None:
312 return symbol, context[i:]
313 return symbol, context[i:]
313 else:
314 else:
314 symbol = new_symbol
315 symbol = new_symbol
315
316
316 return symbol, []
317 return symbol, []
317
318
318
319
319 class QtKernel(Kernel):
320 class QtKernel(Kernel):
320 """A Kernel subclass with Qt support."""
321 """A Kernel subclass with Qt support."""
321
322
322 def start(self):
323 def start(self):
323 """Start a kernel with QtPy4 event loop integration."""
324 """Start a kernel with QtPy4 event loop integration."""
324
325
325 from PyQt4 import QtGui, QtCore
326 from PyQt4 import QtGui, QtCore
326 from IPython.lib.guisupport import (
327 from IPython.lib.guisupport import (
327 get_app_qt4, start_event_loop_qt4
328 get_app_qt4, start_event_loop_qt4
328 )
329 )
329 self.app = get_app_qt4([" "])
330 self.app = get_app_qt4([" "])
330 self.app.setQuitOnLastWindowClosed(False)
331 self.app.setQuitOnLastWindowClosed(False)
331 self.timer = QtCore.QTimer()
332 self.timer = QtCore.QTimer()
332 self.timer.timeout.connect(self.do_one_iteration)
333 self.timer.timeout.connect(self.do_one_iteration)
333 self.timer.start(50)
334 self.timer.start(50)
334 start_event_loop_qt4(self.app)
335 start_event_loop_qt4(self.app)
335
336
336
337
337 class WxKernel(Kernel):
338 class WxKernel(Kernel):
338 """A Kernel subclass with Wx support."""
339 """A Kernel subclass with Wx support."""
339
340
340 def start(self):
341 def start(self):
341 """Start a kernel with wx event loop support."""
342 """Start a kernel with wx event loop support."""
342
343
343 import wx
344 import wx
344 from IPython.lib.guisupport import start_event_loop_wx
345 from IPython.lib.guisupport import start_event_loop_wx
345 doi = self.do_one_iteration
346 doi = self.do_one_iteration
346
347
347 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
348 # We have to put the wx.Timer in a wx.Frame for it to fire properly.
348 # We make the Frame hidden when we create it in the main app below.
349 # We make the Frame hidden when we create it in the main app below.
349 class TimerFrame(wx.Frame):
350 class TimerFrame(wx.Frame):
350 def __init__(self, func):
351 def __init__(self, func):
351 wx.Frame.__init__(self, None, -1)
352 wx.Frame.__init__(self, None, -1)
352 self.timer = wx.Timer(self)
353 self.timer = wx.Timer(self)
353 self.timer.Start(50)
354 self.timer.Start(50)
354 self.Bind(wx.EVT_TIMER, self.on_timer)
355 self.Bind(wx.EVT_TIMER, self.on_timer)
355 self.func = func
356 self.func = func
356 def on_timer(self, event):
357 def on_timer(self, event):
357 self.func()
358 self.func()
358
359
359 # We need a custom wx.App to create our Frame subclass that has the
360 # We need a custom wx.App to create our Frame subclass that has the
360 # wx.Timer to drive the ZMQ event loop.
361 # wx.Timer to drive the ZMQ event loop.
361 class IPWxApp(wx.App):
362 class IPWxApp(wx.App):
362 def OnInit(self):
363 def OnInit(self):
363 self.frame = TimerFrame(doi)
364 self.frame = TimerFrame(doi)
364 self.frame.Show(False)
365 self.frame.Show(False)
365 return True
366 return True
366
367
367 # The redirect=False here makes sure that wx doesn't replace
368 # The redirect=False here makes sure that wx doesn't replace
368 # sys.stdout/stderr with its own classes.
369 # sys.stdout/stderr with its own classes.
369 self.app = IPWxApp(redirect=False)
370 self.app = IPWxApp(redirect=False)
370 start_event_loop_wx(self.app)
371 start_event_loop_wx(self.app)
371
372
372
373
373 class TkKernel(Kernel):
374 class TkKernel(Kernel):
374 """A Kernel subclass with Tk support."""
375 """A Kernel subclass with Tk support."""
375
376
376 def start(self):
377 def start(self):
377 """Start a Tk enabled event loop."""
378 """Start a Tk enabled event loop."""
378
379
379 import Tkinter
380 import Tkinter
380 doi = self.do_one_iteration
381 doi = self.do_one_iteration
381
382
382 # For Tkinter, we create a Tk object and call its withdraw method.
383 # For Tkinter, we create a Tk object and call its withdraw method.
383 class Timer(object):
384 class Timer(object):
384 def __init__(self, func):
385 def __init__(self, func):
385 self.app = Tkinter.Tk()
386 self.app = Tkinter.Tk()
386 self.app.withdraw()
387 self.app.withdraw()
387 self.func = func
388 self.func = func
388 def on_timer(self):
389 def on_timer(self):
389 self.func()
390 self.func()
390 self.app.after(50, self.on_timer)
391 self.app.after(50, self.on_timer)
391 def start(self):
392 def start(self):
392 self.on_timer() # Call it once to get things going.
393 self.on_timer() # Call it once to get things going.
393 self.app.mainloop()
394 self.app.mainloop()
394
395
395 self.timer = Timer(doi)
396 self.timer = Timer(doi)
396 self.timer.start()
397 self.timer.start()
397
398
398 #-----------------------------------------------------------------------------
399 #-----------------------------------------------------------------------------
399 # Kernel main and launch functions
400 # Kernel main and launch functions
400 #-----------------------------------------------------------------------------
401 #-----------------------------------------------------------------------------
401
402
402 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
403 def launch_kernel(xrep_port=0, pub_port=0, req_port=0, hb_port=0,
403 independent=False, pylab=False):
404 independent=False, pylab=False):
404 """ Launches a localhost kernel, binding to the specified ports.
405 """ Launches a localhost kernel, binding to the specified ports.
405
406
406 Parameters
407 Parameters
407 ----------
408 ----------
408 xrep_port : int, optional
409 xrep_port : int, optional
409 The port to use for XREP channel.
410 The port to use for XREP channel.
410
411
411 pub_port : int, optional
412 pub_port : int, optional
412 The port to use for the SUB channel.
413 The port to use for the SUB channel.
413
414
414 req_port : int, optional
415 req_port : int, optional
415 The port to use for the REQ (raw input) channel.
416 The port to use for the REQ (raw input) channel.
416
417
417 hb_port : int, optional
418 hb_port : int, optional
418 The port to use for the hearbeat REP channel.
419 The port to use for the hearbeat REP channel.
419
420
420 independent : bool, optional (default False)
421 independent : bool, optional (default False)
421 If set, the kernel process is guaranteed to survive if this process
422 If set, the kernel process is guaranteed to survive if this process
422 dies. If not set, an effort is made to ensure that the kernel is killed
423 dies. If not set, an effort is made to ensure that the kernel is killed
423 when this process dies. Note that in this case it is still good practice
424 when this process dies. Note that in this case it is still good practice
424 to kill kernels manually before exiting.
425 to kill kernels manually before exiting.
425
426
426 pylab : bool or string, optional (default False)
427 pylab : bool or string, optional (default False)
427 If not False, the kernel will be launched with pylab enabled. If a
428 If not False, the kernel will be launched with pylab enabled. If a
428 string is passed, matplotlib will use the specified backend. Otherwise,
429 string is passed, matplotlib will use the specified backend. Otherwise,
429 matplotlib's default backend will be used.
430 matplotlib's default backend will be used.
430
431
431 Returns
432 Returns
432 -------
433 -------
433 A tuple of form:
434 A tuple of form:
434 (kernel_process, xrep_port, pub_port, req_port)
435 (kernel_process, xrep_port, pub_port, req_port)
435 where kernel_process is a Popen object and the ports are integers.
436 where kernel_process is a Popen object and the ports are integers.
436 """
437 """
437 extra_arguments = []
438 extra_arguments = []
438 if pylab:
439 if pylab:
439 extra_arguments.append('--pylab')
440 extra_arguments.append('--pylab')
440 if isinstance(pylab, basestring):
441 if isinstance(pylab, basestring):
441 extra_arguments.append(pylab)
442 extra_arguments.append(pylab)
442 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
443 return base_launch_kernel('from IPython.zmq.ipkernel import main; main()',
443 xrep_port, pub_port, req_port, hb_port,
444 xrep_port, pub_port, req_port, hb_port,
444 independent, extra_arguments)
445 independent, extra_arguments)
445
446
446
447
447 def main():
448 def main():
448 """ The IPython kernel main entry point.
449 """ The IPython kernel main entry point.
449 """
450 """
450 parser = make_argument_parser()
451 parser = make_argument_parser()
451 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
452 parser.add_argument('--pylab', type=str, metavar='GUI', nargs='?',
452 const='auto', help = \
453 const='auto', help = \
453 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
454 "Pre-load matplotlib and numpy for interactive use. If GUI is not \
454 given, the GUI backend is matplotlib's, otherwise use one of: \
455 given, the GUI backend is matplotlib's, otherwise use one of: \
455 ['tk', 'gtk', 'qt', 'wx', 'payload-svg'].")
456 ['tk', 'gtk', 'qt', 'wx', 'payload-svg'].")
456 namespace = parser.parse_args()
457 namespace = parser.parse_args()
457
458
458 kernel_class = Kernel
459 kernel_class = Kernel
459
460
460 _kernel_classes = {
461 _kernel_classes = {
461 'qt' : QtKernel,
462 'qt' : QtKernel,
462 'qt4' : QtKernel,
463 'qt4' : QtKernel,
463 'payload-svg': Kernel,
464 'payload-svg': Kernel,
464 'wx' : WxKernel,
465 'wx' : WxKernel,
465 'tk' : TkKernel
466 'tk' : TkKernel
466 }
467 }
467 if namespace.pylab:
468 if namespace.pylab:
468 if namespace.pylab == 'auto':
469 if namespace.pylab == 'auto':
469 gui, backend = pylabtools.find_gui_and_backend()
470 gui, backend = pylabtools.find_gui_and_backend()
470 else:
471 else:
471 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
472 gui, backend = pylabtools.find_gui_and_backend(namespace.pylab)
472 kernel_class = _kernel_classes.get(gui)
473 kernel_class = _kernel_classes.get(gui)
473 if kernel_class is None:
474 if kernel_class is None:
474 raise ValueError('GUI is not supported: %r' % gui)
475 raise ValueError('GUI is not supported: %r' % gui)
475 pylabtools.activate_matplotlib(backend)
476 pylabtools.activate_matplotlib(backend)
476
477
477 kernel = make_kernel(namespace, kernel_class, OutStream)
478 kernel = make_kernel(namespace, kernel_class, OutStream)
478
479
479 if namespace.pylab:
480 if namespace.pylab:
480 pylabtools.import_pylab(kernel.shell.user_ns)
481 pylabtools.import_pylab(kernel.shell.user_ns)
481
482
482 start_kernel(namespace, kernel)
483 start_kernel(namespace, kernel)
483
484
484
485
485 if __name__ == '__main__':
486 if __name__ == '__main__':
486 main()
487 main()
@@ -1,707 +1,712 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, but this may be a multiline
163 The ``code`` field contains a single string, but this may be a multiline
164 string. The kernel is responsible for splitting this into possibly more than
164 string. The kernel is responsible for splitting this into possibly more than
165 one block and deciding whether to compile these in 'single' or 'exec' mode.
165 one block and deciding whether to compile these in 'single' or 'exec' mode.
166 We're still sorting out this policy. The current inputsplitter is capable of
166 We're still sorting out this policy. The current inputsplitter is capable of
167 splitting the input for blocks that can all be run as 'single', but in the long
167 splitting the input for blocks that can all be run as 'single', but in the long
168 run it may prove cleaner to only use 'single' mode for truly single-line
168 run it may prove cleaner to only use 'single' mode for truly single-line
169 inputs, and run all multiline input in 'exec' mode. This would preserve the
169 inputs, and run all multiline input in 'exec' mode. This would preserve the
170 natural behavior of single-line inputs while allowing long cells to behave more
170 natural behavior of single-line inputs while allowing long cells to behave more
171 likea a script. This design will be refined as we complete the implementation.
171 likea a script. This design will be refined as we complete the implementation.
172
172
173 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
173 The ``user_`` fields deserve a detailed explanation. In the past, IPython had
174 the notion of a prompt string that allowed arbitrary code to be evaluated, and
174 the notion of a prompt string that allowed arbitrary code to be evaluated, and
175 this was put to good use by many in creating prompts that displayed system
175 this was put to good use by many in creating prompts that displayed system
176 status, path information, and even more esoteric uses like remote instrument
176 status, path information, and even more esoteric uses like remote instrument
177 status aqcuired over the network. But now that IPython has a clean separation
177 status aqcuired over the network. But now that IPython has a clean separation
178 between the kernel and the clients, the notion of embedding 'prompt'
178 between the kernel and the clients, the notion of embedding 'prompt'
179 maninpulations into the kernel itself feels awkward. Prompts should be a
179 maninpulations into the kernel itself feels awkward. Prompts should be a
180 frontend-side feature, and it should be even possible for different frontends
180 frontend-side feature, and it should be even possible for different frontends
181 to display different prompts while interacting with the same kernel.
181 to display different prompts while interacting with the same kernel.
182
182
183 We have therefore abandoned the idea of a 'prompt string' to be evaluated by
183 We have therefore abandoned the idea of a 'prompt string' to be evaluated by
184 the kernel, and instead provide the ability to retrieve from the user's
184 the kernel, and instead provide the ability to retrieve from the user's
185 namespace information after the execution of the main ``code``, with two fields
185 namespace information after the execution of the main ``code``, with two fields
186 of the execution request:
186 of the execution request:
187
187
188 - ``user_variables``: If only variables from the user's namespace are needed, a
188 - ``user_variables``: If only variables from the user's namespace are needed, a
189 list of variable names can be passed and a dict with these names as keys and
189 list of variable names can be passed and a dict with these names as keys and
190 their :func:`repr()` as values will be returned.
190 their :func:`repr()` as values will be returned.
191
191
192 - ``user_expressions``: For more complex expressions that require function
192 - ``user_expressions``: For more complex expressions that require function
193 evaluations, a dict can be provided with string keys and arbitrary python
193 evaluations, a dict can be provided with string keys and arbitrary python
194 expressions as values. The return message will contain also a dict with the
194 expressions as values. The return message will contain also a dict with the
195 same keys and the :func:`repr()` of the evaluated expressions as value.
195 same keys and the :func:`repr()` of the evaluated expressions as value.
196
196
197 With this information, frontends can display any status information they wish
197 With this information, frontends can display any status information they wish
198 in the form that best suits each frontend (a status line, a popup, inline for a
198 in the form that best suits each frontend (a status line, a popup, inline for a
199 terminal, etc).
199 terminal, etc).
200
200
201 .. Note::
201 .. Note::
202
202
203 In order to obtain the current execution counter for the purposes of
203 In order to obtain the current execution counter for the purposes of
204 displaying input prompts, frontends simply make an execution request with an
204 displaying input prompts, frontends simply make an execution request with an
205 empty code string and ``silent=True``.
205 empty code string and ``silent=True``.
206
206
207 Execution semantics
207 Execution semantics
208 Upon completion of the execution request, the kernel *always* sends a
208 Upon completion of the execution request, the kernel *always* sends a
209 reply, with a status code indicating what happened and additional data
209 reply, with a status code indicating what happened and additional data
210 depending on the outcome.
210 depending on the outcome.
211
211
212 The ``code`` field is executed first, and then the ``user_variables`` and
212 The ``code`` field is executed first, and then the ``user_variables`` and
213 ``user_expressions`` are computed. This ensures that any error in the
213 ``user_expressions`` are computed. This ensures that any error in the
214 latter don't harm the main code execution.
214 latter don't harm the main code execution.
215
215
216 Any error in retrieving the ``user_variables`` or evaluating the
216 Any error in retrieving the ``user_variables`` or evaluating the
217 ``user_expressions`` will result in a simple error message in the return
217 ``user_expressions`` will result in a simple error message in the return
218 fields of the form::
218 fields of the form::
219
219
220 [ERROR] ExceptionType: Exception message
220 [ERROR] ExceptionType: Exception message
221
221
222 The user can simply send the same variable name or expression for
222 The user can simply send the same variable name or expression for
223 evaluation to see a regular traceback.
223 evaluation to see a regular traceback.
224
224
225 Execution counter (old prompt number)
225 Execution counter (old prompt number)
226 The kernel has a single, monotonically increasing counter of all execution
226 The kernel has a single, monotonically increasing counter of all execution
227 requests that are made with ``silent=False``. This counter is used to
227 requests that are made with ``silent=False``. This counter is used to
228 populate the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will
228 populate the ``In[n]``, ``Out[n]`` and ``_n`` variables, so clients will
229 likely want to display it in some form to the user, which will typically
229 likely want to display it in some form to the user, which will typically
230 (but not necessarily) be done in the prompts. The value of this counter
230 (but not necessarily) be done in the prompts. The value of this counter
231 will be returned as the ``execution_count`` field of all ``execute_reply```
231 will be returned as the ``execution_count`` field of all ``execute_reply```
232 messages.
232 messages.
233
233
234 Message type: ``execute_reply``::
234 Message type: ``execute_reply``::
235
235
236 content = {
236 content = {
237 # One of: 'ok' OR 'error' OR 'abort'
237 # One of: 'ok' OR 'error' OR 'abort'
238 'status' : str,
238 'status' : str,
239
239
240 # The global kernel counter that increases by one with each non-silent
240 # The global kernel counter that increases by one with each non-silent
241 # executed request. This will typically be used by clients to display
241 # executed request. This will typically be used by clients to display
242 # prompt numbers to the user. If the request was a silent one, this will
242 # prompt numbers to the user. If the request was a silent one, this will
243 # be the current value of the counter in the kernel.
243 # be the current value of the counter in the kernel.
244 'execution_count' : int,
244 'execution_count' : int,
245 }
245 }
246
246
247 When status is 'ok', the following extra fields are present::
247 When status is 'ok', the following extra fields are present::
248
248
249 {
249 {
250 # The execution payload is a dict with string keys that may have been
250 # The execution payload is a dict with string keys that may have been
251 # produced by the code being executed. It is retrieved by the kernel at
251 # produced by the code being executed. It is retrieved by the kernel at
252 # the end of the execution and sent back to the front end, which can take
252 # the end of the execution and sent back to the front end, which can take
253 # action on it as needed. See main text for further details.
253 # action on it as needed. See main text for further details.
254 'payload' : dict,
254 'payload' : dict,
255
255
256 # Results for the user_variables and user_expressions.
256 # Results for the user_variables and user_expressions.
257 'user_variables' : dict,
257 'user_variables' : dict,
258 'user_expressions' : dict,
258 'user_expressions' : dict,
259
259
260 # The kernel will often transform the input provided to it. If the
260 # The kernel will often transform the input provided to it. If the
261 # '---->' transform had been applied, this is filled, otherwise it's the
261 # '---->' transform had been applied, this is filled, otherwise it's the
262 # empty string. So transformations like magics don't appear here, only
262 # empty string. So transformations like magics don't appear here, only
263 # autocall ones.
263 # autocall ones.
264 'transformed_code' : str,
264 'transformed_code' : str,
265 }
265 }
266
266
267 .. admonition:: Execution payloads
267 .. admonition:: Execution payloads
268
268
269 The notion of an 'execution payload' is different from a return value of a
269 The notion of an 'execution payload' is different from a return value of a
270 given set of code, which normally is just displayed on the pyout stream
270 given set of code, which normally is just displayed on the pyout stream
271 through the PUB socket. The idea of a payload is to allow special types of
271 through the PUB socket. The idea of a payload is to allow special types of
272 code, typically magics, to populate a data container in the IPython kernel
272 code, typically magics, to populate a data container in the IPython kernel
273 that will be shipped back to the caller via this channel. The kernel will
273 that will be shipped back to the caller via this channel. The kernel will
274 have an API for this, probably something along the lines of::
274 have an API for this, probably something along the lines of::
275
275
276 ip.exec_payload_add(key, value)
276 ip.exec_payload_add(key, value)
277
277
278 though this API is still in the design stages. The data returned in this
278 though this API is still in the design stages. The data returned in this
279 payload will allow frontends to present special views of what just happened.
279 payload will allow frontends to present special views of what just happened.
280
280
281
281
282 When status is 'error', the following extra fields are present::
282 When status is 'error', the following extra fields are present::
283
283
284 {
284 {
285 'exc_name' : str, # Exception name, as a string
285 'exc_name' : str, # Exception name, as a string
286 'exc_value' : str, # Exception value, as a string
286 'exc_value' : str, # Exception value, as a string
287
287
288 # The traceback will contain a list of frames, represented each as a
288 # The traceback will contain a list of frames, represented each as a
289 # string. For now we'll stick to the existing design of ultraTB, which
289 # string. For now we'll stick to the existing design of ultraTB, which
290 # controls exception level of detail statefully. But eventually we'll
290 # controls exception level of detail statefully. But eventually we'll
291 # want to grow into a model where more information is collected and
291 # want to grow into a model where more information is collected and
292 # packed into the traceback object, with clients deciding how little or
292 # packed into the traceback object, with clients deciding how little or
293 # how much of it to unpack. But for now, let's start with a simple list
293 # how much of it to unpack. But for now, let's start with a simple list
294 # of strings, since that requires only minimal changes to ultratb as
294 # of strings, since that requires only minimal changes to ultratb as
295 # written.
295 # written.
296 'traceback' : list,
296 'traceback' : list,
297 }
297 }
298
298
299
299
300 When status is 'abort', there are for now no additional data fields. This
300 When status is 'abort', there are for now no additional data fields. This
301 happens when the kernel was interrupted by a signal.
301 happens when the kernel was interrupted by a signal.
302
302
303 Kernel attribute access
303 Kernel attribute access
304 -----------------------
304 -----------------------
305
305
306 While this protocol does not specify full RPC access to arbitrary methods of
306 While this protocol does not specify full RPC access to arbitrary methods of
307 the kernel object, the kernel does allow read (and in some cases write) access
307 the kernel object, the kernel does allow read (and in some cases write) access
308 to certain attributes.
308 to certain attributes.
309
309
310 The policy for which attributes can be read is: any attribute of the kernel, or
310 The policy for which attributes can be read is: any attribute of the kernel, or
311 its sub-objects, that belongs to a :class:`Configurable` object and has been
311 its sub-objects, that belongs to a :class:`Configurable` object and has been
312 declared at the class-level with Traits validation, is in principle accessible
312 declared at the class-level with Traits validation, is in principle accessible
313 as long as its name does not begin with a leading underscore. The attribute
313 as long as its name does not begin with a leading underscore. The attribute
314 itself will have metadata indicating whether it allows remote read and/or write
314 itself will have metadata indicating whether it allows remote read and/or write
315 access. The message spec follows for attribute read and write requests.
315 access. The message spec follows for attribute read and write requests.
316
316
317 Message type: ``getattr_request``::
317 Message type: ``getattr_request``::
318
318
319 content = {
319 content = {
320 # The (possibly dotted) name of the attribute
320 # The (possibly dotted) name of the attribute
321 'name' : str,
321 'name' : str,
322 }
322 }
323
323
324 When a ``getattr_request`` fails, there are two possible error types:
324 When a ``getattr_request`` fails, there are two possible error types:
325
325
326 - AttributeError: this type of error was raised when trying to access the
326 - AttributeError: this type of error was raised when trying to access the
327 given name by the kernel itself. This means that the attribute likely
327 given name by the kernel itself. This means that the attribute likely
328 doesn't exist.
328 doesn't exist.
329
329
330 - AccessError: the attribute exists but its value is not readable remotely.
330 - AccessError: the attribute exists but its value is not readable remotely.
331
331
332
332
333 Message type: ``getattr_reply``::
333 Message type: ``getattr_reply``::
334
334
335 content = {
335 content = {
336 # One of ['ok', 'AttributeError', 'AccessError'].
336 # One of ['ok', 'AttributeError', 'AccessError'].
337 'status' : str,
337 'status' : str,
338 # If status is 'ok', a JSON object.
338 # If status is 'ok', a JSON object.
339 'value' : object,
339 'value' : object,
340 }
340 }
341
341
342 Message type: ``setattr_request``::
342 Message type: ``setattr_request``::
343
343
344 content = {
344 content = {
345 # The (possibly dotted) name of the attribute
345 # The (possibly dotted) name of the attribute
346 'name' : str,
346 'name' : str,
347
347
348 # A JSON-encoded object, that will be validated by the Traits
348 # A JSON-encoded object, that will be validated by the Traits
349 # information in the kernel
349 # information in the kernel
350 'value' : object,
350 'value' : object,
351 }
351 }
352
352
353 When a ``setattr_request`` fails, there are also two possible error types with
353 When a ``setattr_request`` fails, there are also two possible error types with
354 similar meanings as those of the ``getattr_request`` case, but for writing.
354 similar meanings as those of the ``getattr_request`` case, but for writing.
355
355
356 Message type: ``setattr_reply``::
356 Message type: ``setattr_reply``::
357
357
358 content = {
358 content = {
359 # One of ['ok', 'AttributeError', 'AccessError'].
359 # One of ['ok', 'AttributeError', 'AccessError'].
360 'status' : str,
360 'status' : str,
361 }
361 }
362
362
363
363
364 Object information
364 Object information
365 ------------------
365 ------------------
366
366
367 One of IPython's most used capabilities is the introspection of Python objects
367 One of IPython's most used capabilities is the introspection of Python objects
368 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
368 in the user's namespace, typically invoked via the ``?`` and ``??`` characters
369 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
369 (which in reality are shorthands for the ``%pinfo`` magic). This is used often
370 enough that it warrants an explicit message type, especially because frontends
370 enough that it warrants an explicit message type, especially because frontends
371 may want to get object information in response to user keystrokes (like Tab or
371 may want to get object information in response to user keystrokes (like Tab or
372 F1) besides from the user explicitly typing code like ``x??``.
372 F1) besides from the user explicitly typing code like ``x??``.
373
373
374 Message type: ``object_info_request``::
374 Message type: ``object_info_request``::
375
375
376 content = {
376 content = {
377 # The (possibly dotted) name of the object to be searched in all
377 # The (possibly dotted) name of the object to be searched in all
378 # relevant namespaces
378 # relevant namespaces
379 'name' : str,
379 'name' : str,
380
380
381 # The level of detail desired. The default (0) is equivalent to typing
381 # The level of detail desired. The default (0) is equivalent to typing
382 # 'x?' at the prompt, 1 is equivalent to 'x??'.
382 # 'x?' at the prompt, 1 is equivalent to 'x??'.
383 'detail_level' : int,
383 'detail_level' : int,
384 }
384 }
385
385
386 The returned information will be a dictionary with keys very similar to the
386 The returned information will be a dictionary with keys very similar to the
387 field names that IPython prints at the terminal.
387 field names that IPython prints at the terminal.
388
388
389 Message type: ``object_info_reply``::
389 Message type: ``object_info_reply``::
390
390
391 content = {
391 content = {
392 # Flags for magics and system aliases
392 # Flags for magics and system aliases
393 'ismagic' : bool,
393 'ismagic' : bool,
394 'isalias' : bool,
394 'isalias' : bool,
395
395
396 # The name of the namespace where the object was found ('builtin',
396 # The name of the namespace where the object was found ('builtin',
397 # 'magics', 'alias', 'interactive', etc.)
397 # 'magics', 'alias', 'interactive', etc.)
398 'namespace' : str,
398 'namespace' : str,
399
399
400 # The type name will be type.__name__ for normal Python objects, but it
400 # The type name will be type.__name__ for normal Python objects, but it
401 # can also be a string like 'Magic function' or 'System alias'
401 # can also be a string like 'Magic function' or 'System alias'
402 'type_name' : str,
402 'type_name' : str,
403
403
404 'string_form' : str,
404 'string_form' : str,
405
405
406 # For objects with a __class__ attribute this will be set
406 # For objects with a __class__ attribute this will be set
407 'base_class' : str,
407 'base_class' : str,
408
408
409 # For objects with a __len__ attribute this will be set
409 # For objects with a __len__ attribute this will be set
410 'length' : int,
410 'length' : int,
411
411
412 # If the object is a function, class or method whose file we can find,
412 # If the object is a function, class or method whose file we can find,
413 # we give its full path
413 # we give its full path
414 'file' : str,
414 'file' : str,
415
415
416 # For pure Python callable objects, we can reconstruct the object
416 # For pure Python callable objects, we can reconstruct the object
417 # definition line which provides its call signature. For convenience this
417 # definition line which provides its call signature. For convenience this
418 # is returned as a single 'definition' field, but below the raw parts that
418 # is returned as a single 'definition' field, but below the raw parts that
419 # compose it are also returned as the argspec field.
419 # compose it are also returned as the argspec field.
420 'definition' : str,
420 'definition' : str,
421
421
422 # The individual parts that together form the definition string. Clients
422 # The individual parts that together form the definition string. Clients
423 # with rich display capabilities may use this to provide a richer and more
423 # with rich display capabilities may use this to provide a richer and more
424 # precise representation of the definition line (e.g. by highlighting
424 # precise representation of the definition line (e.g. by highlighting
425 # arguments based on the user's cursor position). For non-callable
425 # arguments based on the user's cursor position). For non-callable
426 # objects, this field is empty.
426 # objects, this field is empty.
427 'argspec' : { # The names of all the arguments
427 'argspec' : { # The names of all the arguments
428 args : list,
428 args : list,
429 # The name of the varargs (*args), if any
429 # The name of the varargs (*args), if any
430 varargs : str,
430 varargs : str,
431 # The name of the varkw (**kw), if any
431 # The name of the varkw (**kw), if any
432 varkw : str,
432 varkw : str,
433 # The values (as strings) of all default arguments. Note
433 # The values (as strings) of all default arguments. Note
434 # that these must be matched *in reverse* with the 'args'
434 # that these must be matched *in reverse* with the 'args'
435 # list above, since the first positional args have no default
435 # list above, since the first positional args have no default
436 # value at all.
436 # value at all.
437 func_defaults : list,
437 func_defaults : list,
438 },
438 },
439
439
440 # For instances, provide the constructor signature (the definition of
440 # For instances, provide the constructor signature (the definition of
441 # the __init__ method):
441 # the __init__ method):
442 'init_definition' : str,
442 'init_definition' : str,
443
443
444 # Docstrings: for any object (function, method, module, package) with a
444 # Docstrings: for any object (function, method, module, package) with a
445 # docstring, we show it. But in addition, we may provide additional
445 # docstring, we show it. But in addition, we may provide additional
446 # docstrings. For example, for instances we will show the constructor
446 # docstrings. For example, for instances we will show the constructor
447 # and class docstrings as well, if available.
447 # and class docstrings as well, if available.
448 'docstring' : str,
448 'docstring' : str,
449
449
450 # For instances, provide the constructor and class docstrings
450 # For instances, provide the constructor and class docstrings
451 'init_docstring' : str,
451 'init_docstring' : str,
452 'class_docstring' : str,
452 'class_docstring' : str,
453
453
454 # If it's a callable object whose call method has a separate docstring and
455 # definition line:
456 'call_def' : str,
457 'call_docstring' : str,
458
454 # If detail_level was 1, we also try to find the source code that
459 # If detail_level was 1, we also try to find the source code that
455 # defines the object, if possible. The string 'None' will indicate
460 # defines the object, if possible. The string 'None' will indicate
456 # that no source was found.
461 # that no source was found.
457 'source' : str,
462 'source' : str,
458 }
463 }
459
464 '
460
465
461 Complete
466 Complete
462 --------
467 --------
463
468
464 Message type: ``complete_request``::
469 Message type: ``complete_request``::
465
470
466 content = {
471 content = {
467 # The text to be completed, such as 'a.is'
472 # The text to be completed, such as 'a.is'
468 'text' : str,
473 'text' : str,
469
474
470 # The full line, such as 'print a.is'. This allows completers to
475 # The full line, such as 'print a.is'. This allows completers to
471 # make decisions that may require information about more than just the
476 # make decisions that may require information about more than just the
472 # current word.
477 # current word.
473 'line' : str,
478 'line' : str,
474
479
475 # The entire block of text where the line is. This may be useful in the
480 # The entire block of text where the line is. This may be useful in the
476 # case of multiline completions where more context may be needed. Note: if
481 # case of multiline completions where more context may be needed. Note: if
477 # in practice this field proves unnecessary, remove it to lighten the
482 # in practice this field proves unnecessary, remove it to lighten the
478 # messages.
483 # messages.
479
484
480 'block' : str,
485 'block' : str,
481
486
482 # The position of the cursor where the user hit 'TAB' on the line.
487 # The position of the cursor where the user hit 'TAB' on the line.
483 'cursor_pos' : int,
488 'cursor_pos' : int,
484 }
489 }
485
490
486 Message type: ``complete_reply``::
491 Message type: ``complete_reply``::
487
492
488 content = {
493 content = {
489 # The list of all matches to the completion request, such as
494 # The list of all matches to the completion request, such as
490 # ['a.isalnum', 'a.isalpha'] for the above example.
495 # ['a.isalnum', 'a.isalpha'] for the above example.
491 'matches' : list
496 'matches' : list
492 }
497 }
493
498
494
499
495 History
500 History
496 -------
501 -------
497
502
498 For clients to explicitly request history from a kernel. The kernel has all
503 For clients to explicitly request history from a kernel. The kernel has all
499 the actual execution history stored in a single location, so clients can
504 the actual execution history stored in a single location, so clients can
500 request it from the kernel when needed.
505 request it from the kernel when needed.
501
506
502 Message type: ``history_request``::
507 Message type: ``history_request``::
503
508
504 content = {
509 content = {
505
510
506 # If True, also return output history in the resulting dict.
511 # If True, also return output history in the resulting dict.
507 'output' : bool,
512 'output' : bool,
508
513
509 # If True, return the raw input history, else the transformed input.
514 # If True, return the raw input history, else the transformed input.
510 'raw' : bool,
515 'raw' : bool,
511
516
512 # This parameter can be one of: A number, a pair of numbers, None
517 # This parameter can be one of: A number, a pair of numbers, None
513 # If not given, last 40 are returned.
518 # If not given, last 40 are returned.
514 # - number n: return the last n entries.
519 # - number n: return the last n entries.
515 # - pair n1, n2: return entries in the range(n1, n2).
520 # - pair n1, n2: return entries in the range(n1, n2).
516 # - None: return all history
521 # - None: return all history
517 'index' : n or (n1, n2) or None,
522 'index' : n or (n1, n2) or None,
518 }
523 }
519
524
520 Message type: ``history_reply``::
525 Message type: ``history_reply``::
521
526
522 content = {
527 content = {
523 # A dict with prompt numbers as keys and either (input, output) or input
528 # A dict with prompt numbers as keys and either (input, output) or input
524 # as the value depending on whether output was True or False,
529 # as the value depending on whether output was True or False,
525 # respectively.
530 # respectively.
526 'history' : dict,
531 'history' : dict,
527 }
532 }
528
533
529 Messages on the PUB/SUB socket
534 Messages on the PUB/SUB socket
530 ==============================
535 ==============================
531
536
532 Streams (stdout, stderr, etc)
537 Streams (stdout, stderr, etc)
533 ------------------------------
538 ------------------------------
534
539
535 Message type: ``stream``::
540 Message type: ``stream``::
536
541
537 content = {
542 content = {
538 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
543 # The name of the stream is one of 'stdin', 'stdout', 'stderr'
539 'name' : str,
544 'name' : str,
540
545
541 # The data is an arbitrary string to be written to that stream
546 # The data is an arbitrary string to be written to that stream
542 'data' : str,
547 'data' : str,
543 }
548 }
544
549
545 When a kernel receives a raw_input call, it should also broadcast it on the pub
550 When a kernel receives a raw_input call, it should also broadcast it on the pub
546 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
551 socket with the names 'stdin' and 'stdin_reply'. This will allow other clients
547 to monitor/display kernel interactions and possibly replay them to their user
552 to monitor/display kernel interactions and possibly replay them to their user
548 or otherwise expose them.
553 or otherwise expose them.
549
554
550 Python inputs
555 Python inputs
551 -------------
556 -------------
552
557
553 These messages are the re-broadcast of the ``execute_request``.
558 These messages are the re-broadcast of the ``execute_request``.
554
559
555 Message type: ``pyin``::
560 Message type: ``pyin``::
556
561
557 content = {
562 content = {
558 # Source code to be executed, one or more lines
563 # Source code to be executed, one or more lines
559 'code' : str
564 'code' : str
560 }
565 }
561
566
562 Python outputs
567 Python outputs
563 --------------
568 --------------
564
569
565 When Python produces output from code that has been compiled in with the
570 When Python produces output from code that has been compiled in with the
566 'single' flag to :func:`compile`, any expression that produces a value (such as
571 'single' flag to :func:`compile`, any expression that produces a value (such as
567 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
572 ``1+1``) is passed to ``sys.displayhook``, which is a callable that can do with
568 this value whatever it wants. The default behavior of ``sys.displayhook`` in
573 this value whatever it wants. The default behavior of ``sys.displayhook`` in
569 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
574 the Python interactive prompt is to print to ``sys.stdout`` the :func:`repr` of
570 the value as long as it is not ``None`` (which isn't printed at all). In our
575 the value as long as it is not ``None`` (which isn't printed at all). In our
571 case, the kernel instantiates as ``sys.displayhook`` an object which has
576 case, the kernel instantiates as ``sys.displayhook`` an object which has
572 similar behavior, but which instead of printing to stdout, broadcasts these
577 similar behavior, but which instead of printing to stdout, broadcasts these
573 values as ``pyout`` messages for clients to display appropriately.
578 values as ``pyout`` messages for clients to display appropriately.
574
579
575 Message type: ``pyout``::
580 Message type: ``pyout``::
576
581
577 content = {
582 content = {
578 # The data is typically the repr() of the object.
583 # The data is typically the repr() of the object.
579 'data' : str,
584 'data' : str,
580
585
581 # The counter for this execution is also provided so that clients can
586 # The counter for this execution is also provided so that clients can
582 # display it, since IPython automatically creates variables called _N (for
587 # display it, since IPython automatically creates variables called _N (for
583 # prompt N).
588 # prompt N).
584 'execution_count' : int,
589 'execution_count' : int,
585 }
590 }
586
591
587 Python errors
592 Python errors
588 -------------
593 -------------
589
594
590 When an error occurs during code execution
595 When an error occurs during code execution
591
596
592 Message type: ``pyerr``::
597 Message type: ``pyerr``::
593
598
594 content = {
599 content = {
595 # Similar content to the execute_reply messages for the 'error' case,
600 # Similar content to the execute_reply messages for the 'error' case,
596 # except the 'status' field is omitted.
601 # except the 'status' field is omitted.
597 }
602 }
598
603
599 Kernel crashes
604 Kernel crashes
600 --------------
605 --------------
601
606
602 When the kernel has an unexpected exception, caught by the last-resort
607 When the kernel has an unexpected exception, caught by the last-resort
603 sys.excepthook, we should broadcast the crash handler's output before exiting.
608 sys.excepthook, we should broadcast the crash handler's output before exiting.
604 This will allow clients to notice that a kernel died, inform the user and
609 This will allow clients to notice that a kernel died, inform the user and
605 propose further actions.
610 propose further actions.
606
611
607 Message type: ``crash``::
612 Message type: ``crash``::
608
613
609 content = {
614 content = {
610 # Similarly to the 'error' case for execute_reply messages, this will
615 # Similarly to the 'error' case for execute_reply messages, this will
611 # contain exc_name, exc_type and traceback fields.
616 # contain exc_name, exc_type and traceback fields.
612
617
613 # An additional field with supplementary information such as where to
618 # An additional field with supplementary information such as where to
614 # send the crash message
619 # send the crash message
615 'info' : str,
620 'info' : str,
616 }
621 }
617
622
618
623
619 Future ideas
624 Future ideas
620 ------------
625 ------------
621
626
622 Other potential message types, currently unimplemented, listed below as ideas.
627 Other potential message types, currently unimplemented, listed below as ideas.
623
628
624 Message type: ``file``::
629 Message type: ``file``::
625
630
626 content = {
631 content = {
627 'path' : 'cool.jpg',
632 'path' : 'cool.jpg',
628 'mimetype' : str,
633 'mimetype' : str,
629 'data' : str,
634 'data' : str,
630 }
635 }
631
636
632
637
633 Messages on the REQ/REP socket
638 Messages on the REQ/REP socket
634 ==============================
639 ==============================
635
640
636 This is a socket that goes in the opposite direction: from the kernel to a
641 This is a socket that goes in the opposite direction: from the kernel to a
637 *single* frontend, and its purpose is to allow ``raw_input`` and similar
642 *single* frontend, and its purpose is to allow ``raw_input`` and similar
638 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
643 operations that read from ``sys.stdin`` on the kernel to be fulfilled by the
639 client. For now we will keep these messages as simple as possible, since they
644 client. For now we will keep these messages as simple as possible, since they
640 basically only mean to convey the ``raw_input(prompt)`` call.
645 basically only mean to convey the ``raw_input(prompt)`` call.
641
646
642 Message type: ``input_request``::
647 Message type: ``input_request``::
643
648
644 content = { 'prompt' : str }
649 content = { 'prompt' : str }
645
650
646 Message type: ``input_reply``::
651 Message type: ``input_reply``::
647
652
648 content = { 'value' : str }
653 content = { 'value' : str }
649
654
650 .. Note::
655 .. Note::
651
656
652 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
657 We do not explicitly try to forward the raw ``sys.stdin`` object, because in
653 practice the kernel should behave like an interactive program. When a
658 practice the kernel should behave like an interactive program. When a
654 program is opened on the console, the keyboard effectively takes over the
659 program is opened on the console, the keyboard effectively takes over the
655 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
660 ``stdin`` file descriptor, and it can't be used for raw reading anymore.
656 Since the IPython kernel effectively behaves like a console program (albeit
661 Since the IPython kernel effectively behaves like a console program (albeit
657 one whose "keyboard" is actually living in a separate process and
662 one whose "keyboard" is actually living in a separate process and
658 transported over the zmq connection), raw ``stdin`` isn't expected to be
663 transported over the zmq connection), raw ``stdin`` isn't expected to be
659 available.
664 available.
660
665
661
666
662 Heartbeat for kernels
667 Heartbeat for kernels
663 =====================
668 =====================
664
669
665 Initially we had considered using messages like those above over ZMQ for a
670 Initially we had considered using messages like those above over ZMQ for a
666 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
671 kernel 'heartbeat' (a way to detect quickly and reliably whether a kernel is
667 alive at all, even if it may be busy executing user code). But this has the
672 alive at all, even if it may be busy executing user code). But this has the
668 problem that if the kernel is locked inside extension code, it wouldn't execute
673 problem that if the kernel is locked inside extension code, it wouldn't execute
669 the python heartbeat code. But it turns out that we can implement a basic
674 the python heartbeat code. But it turns out that we can implement a basic
670 heartbeat with pure ZMQ, without using any Python messaging at all.
675 heartbeat with pure ZMQ, without using any Python messaging at all.
671
676
672 The monitor sends out a single zmq message (right now, it is a str of the
677 The monitor sends out a single zmq message (right now, it is a str of the
673 monitor's lifetime in seconds), and gets the same message right back, prefixed
678 monitor's lifetime in seconds), and gets the same message right back, prefixed
674 with the zmq identity of the XREQ socket in the heartbeat process. This can be
679 with the zmq identity of the XREQ socket in the heartbeat process. This can be
675 a uuid, or even a full message, but there doesn't seem to be a need for packing
680 a uuid, or even a full message, but there doesn't seem to be a need for packing
676 up a message when the sender and receiver are the exact same Python object.
681 up a message when the sender and receiver are the exact same Python object.
677
682
678 The model is this::
683 The model is this::
679
684
680 monitor.send(str(self.lifetime)) # '1.2345678910'
685 monitor.send(str(self.lifetime)) # '1.2345678910'
681
686
682 and the monitor receives some number of messages of the form::
687 and the monitor receives some number of messages of the form::
683
688
684 ['uuid-abcd-dead-beef', '1.2345678910']
689 ['uuid-abcd-dead-beef', '1.2345678910']
685
690
686 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
691 where the first part is the zmq.IDENTITY of the heart's XREQ on the engine, and
687 the rest is the message sent by the monitor. No Python code ever has any
692 the rest is the message sent by the monitor. No Python code ever has any
688 access to the message between the monitor's send, and the monitor's recv.
693 access to the message between the monitor's send, and the monitor's recv.
689
694
690
695
691 ToDo
696 ToDo
692 ====
697 ====
693
698
694 Missing things include:
699 Missing things include:
695
700
696 * Important: finish thinking through the payload concept and API.
701 * Important: finish thinking through the payload concept and API.
697
702
698 * Important: ensure that we have a good solution for magics like %edit. It's
703 * Important: ensure that we have a good solution for magics like %edit. It's
699 likely that with the payload concept we can build a full solution, but not
704 likely that with the payload concept we can build a full solution, but not
700 100% clear yet.
705 100% clear yet.
701
706
702 * Finishing the details of the heartbeat protocol.
707 * Finishing the details of the heartbeat protocol.
703
708
704 * Signal handling: specify what kind of information kernel should broadcast (or
709 * Signal handling: specify what kind of information kernel should broadcast (or
705 not) when it receives signals.
710 not) when it receives signals.
706
711
707 .. include:: ../links.rst
712 .. include:: ../links.rst
General Comments 0
You need to be logged in to leave comments. Login now