##// END OF EJS Templates
Python 3 compatibility for identifiers.
Thomas Kluyver -
Show More
@@ -1,2577 +1,2573 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Main IPython class."""
2 """Main IPython class."""
3
3
4 #-----------------------------------------------------------------------------
4 #-----------------------------------------------------------------------------
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
5 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
6 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
7 # Copyright (C) 2008-2011 The IPython Development Team
7 # Copyright (C) 2008-2011 The IPython Development Team
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12
12
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14 # Imports
14 # Imports
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16
16
17 from __future__ import with_statement
17 from __future__ import with_statement
18 from __future__ import absolute_import
18 from __future__ import absolute_import
19
19
20 import __builtin__ as builtin_mod
20 import __builtin__ as builtin_mod
21 import __future__
21 import __future__
22 import abc
22 import abc
23 import ast
23 import ast
24 import atexit
24 import atexit
25 import codeop
25 import codeop
26 import inspect
26 import inspect
27 import os
27 import os
28 import re
28 import re
29 import sys
29 import sys
30 import tempfile
30 import tempfile
31 import types
31 import types
32 from contextlib import nested
32 from contextlib import nested
33
33
34 from IPython.config.configurable import SingletonConfigurable
34 from IPython.config.configurable import SingletonConfigurable
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import history as ipcorehist
36 from IPython.core import history as ipcorehist
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core import prefilter
38 from IPython.core import prefilter
39 from IPython.core import shadowns
39 from IPython.core import shadowns
40 from IPython.core import ultratb
40 from IPython.core import ultratb
41 from IPython.core.alias import AliasManager, AliasError
41 from IPython.core.alias import AliasManager, AliasError
42 from IPython.core.autocall import ExitAutocall
42 from IPython.core.autocall import ExitAutocall
43 from IPython.core.builtin_trap import BuiltinTrap
43 from IPython.core.builtin_trap import BuiltinTrap
44 from IPython.core.compilerop import CachingCompiler
44 from IPython.core.compilerop import CachingCompiler
45 from IPython.core.display_trap import DisplayTrap
45 from IPython.core.display_trap import DisplayTrap
46 from IPython.core.displayhook import DisplayHook
46 from IPython.core.displayhook import DisplayHook
47 from IPython.core.displaypub import DisplayPublisher
47 from IPython.core.displaypub import DisplayPublisher
48 from IPython.core.error import TryNext, UsageError
48 from IPython.core.error import TryNext, UsageError
49 from IPython.core.extensions import ExtensionManager
49 from IPython.core.extensions import ExtensionManager
50 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
50 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
51 from IPython.core.formatters import DisplayFormatter
51 from IPython.core.formatters import DisplayFormatter
52 from IPython.core.history import HistoryManager
52 from IPython.core.history import HistoryManager
53 from IPython.core.inputsplitter import IPythonInputSplitter
53 from IPython.core.inputsplitter import IPythonInputSplitter
54 from IPython.core.logger import Logger
54 from IPython.core.logger import Logger
55 from IPython.core.macro import Macro
55 from IPython.core.macro import Macro
56 from IPython.core.magic import Magic
56 from IPython.core.magic import Magic
57 from IPython.core.payload import PayloadManager
57 from IPython.core.payload import PayloadManager
58 from IPython.core.plugin import PluginManager
58 from IPython.core.plugin import PluginManager
59 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
59 from IPython.core.prefilter import PrefilterManager, ESC_MAGIC
60 from IPython.core.profiledir import ProfileDir
60 from IPython.core.profiledir import ProfileDir
61 from IPython.external.Itpl import ItplNS
61 from IPython.external.Itpl import ItplNS
62 from IPython.utils import PyColorize
62 from IPython.utils import PyColorize
63 from IPython.utils import io
63 from IPython.utils import io
64 from IPython.utils import py3compat
64 from IPython.utils import py3compat
65 from IPython.utils.doctestreload import doctest_reload
65 from IPython.utils.doctestreload import doctest_reload
66 from IPython.utils.io import ask_yes_no, rprint
66 from IPython.utils.io import ask_yes_no, rprint
67 from IPython.utils.ipstruct import Struct
67 from IPython.utils.ipstruct import Struct
68 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
68 from IPython.utils.path import get_home_dir, get_ipython_dir, HomeDirError
69 from IPython.utils.pickleshare import PickleShareDB
69 from IPython.utils.pickleshare import PickleShareDB
70 from IPython.utils.process import system, getoutput
70 from IPython.utils.process import system, getoutput
71 from IPython.utils.strdispatch import StrDispatch
71 from IPython.utils.strdispatch import StrDispatch
72 from IPython.utils.syspathcontext import prepended_to_syspath
72 from IPython.utils.syspathcontext import prepended_to_syspath
73 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
73 from IPython.utils.text import num_ini_spaces, format_screen, LSString, SList
74 from IPython.utils.traitlets import (Int, CBool, CaselessStrEnum, Enum,
74 from IPython.utils.traitlets import (Int, CBool, CaselessStrEnum, Enum,
75 List, Unicode, Instance, Type)
75 List, Unicode, Instance, Type)
76 from IPython.utils.warn import warn, error, fatal
76 from IPython.utils.warn import warn, error, fatal
77 import IPython.core.hooks
77 import IPython.core.hooks
78
78
79 #-----------------------------------------------------------------------------
79 #-----------------------------------------------------------------------------
80 # Globals
80 # Globals
81 #-----------------------------------------------------------------------------
81 #-----------------------------------------------------------------------------
82
82
83 # compiled regexps for autoindent management
83 # compiled regexps for autoindent management
84 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
84 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
85
85
86 #-----------------------------------------------------------------------------
86 #-----------------------------------------------------------------------------
87 # Utilities
87 # Utilities
88 #-----------------------------------------------------------------------------
88 #-----------------------------------------------------------------------------
89
89
90 def softspace(file, newvalue):
90 def softspace(file, newvalue):
91 """Copied from code.py, to remove the dependency"""
91 """Copied from code.py, to remove the dependency"""
92
92
93 oldvalue = 0
93 oldvalue = 0
94 try:
94 try:
95 oldvalue = file.softspace
95 oldvalue = file.softspace
96 except AttributeError:
96 except AttributeError:
97 pass
97 pass
98 try:
98 try:
99 file.softspace = newvalue
99 file.softspace = newvalue
100 except (AttributeError, TypeError):
100 except (AttributeError, TypeError):
101 # "attribute-less object" or "read-only attributes"
101 # "attribute-less object" or "read-only attributes"
102 pass
102 pass
103 return oldvalue
103 return oldvalue
104
104
105
105
106 def no_op(*a, **kw): pass
106 def no_op(*a, **kw): pass
107
107
108 class SpaceInInput(Exception): pass
108 class SpaceInInput(Exception): pass
109
109
110 class Bunch: pass
110 class Bunch: pass
111
111
112
112
113 def get_default_colors():
113 def get_default_colors():
114 if sys.platform=='darwin':
114 if sys.platform=='darwin':
115 return "LightBG"
115 return "LightBG"
116 elif os.name=='nt':
116 elif os.name=='nt':
117 return 'Linux'
117 return 'Linux'
118 else:
118 else:
119 return 'Linux'
119 return 'Linux'
120
120
121
121
122 class SeparateUnicode(Unicode):
122 class SeparateUnicode(Unicode):
123 """A Unicode subclass to validate separate_in, separate_out, etc.
123 """A Unicode subclass to validate separate_in, separate_out, etc.
124
124
125 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
125 This is a Unicode based trait that converts '0'->'' and '\\n'->'\n'.
126 """
126 """
127
127
128 def validate(self, obj, value):
128 def validate(self, obj, value):
129 if value == '0': value = ''
129 if value == '0': value = ''
130 value = value.replace('\\n','\n')
130 value = value.replace('\\n','\n')
131 return super(SeparateUnicode, self).validate(obj, value)
131 return super(SeparateUnicode, self).validate(obj, value)
132
132
133
133
134 class ReadlineNoRecord(object):
134 class ReadlineNoRecord(object):
135 """Context manager to execute some code, then reload readline history
135 """Context manager to execute some code, then reload readline history
136 so that interactive input to the code doesn't appear when pressing up."""
136 so that interactive input to the code doesn't appear when pressing up."""
137 def __init__(self, shell):
137 def __init__(self, shell):
138 self.shell = shell
138 self.shell = shell
139 self._nested_level = 0
139 self._nested_level = 0
140
140
141 def __enter__(self):
141 def __enter__(self):
142 if self._nested_level == 0:
142 if self._nested_level == 0:
143 try:
143 try:
144 self.orig_length = self.current_length()
144 self.orig_length = self.current_length()
145 self.readline_tail = self.get_readline_tail()
145 self.readline_tail = self.get_readline_tail()
146 except (AttributeError, IndexError): # Can fail with pyreadline
146 except (AttributeError, IndexError): # Can fail with pyreadline
147 self.orig_length, self.readline_tail = 999999, []
147 self.orig_length, self.readline_tail = 999999, []
148 self._nested_level += 1
148 self._nested_level += 1
149
149
150 def __exit__(self, type, value, traceback):
150 def __exit__(self, type, value, traceback):
151 self._nested_level -= 1
151 self._nested_level -= 1
152 if self._nested_level == 0:
152 if self._nested_level == 0:
153 # Try clipping the end if it's got longer
153 # Try clipping the end if it's got longer
154 try:
154 try:
155 e = self.current_length() - self.orig_length
155 e = self.current_length() - self.orig_length
156 if e > 0:
156 if e > 0:
157 for _ in range(e):
157 for _ in range(e):
158 self.shell.readline.remove_history_item(self.orig_length)
158 self.shell.readline.remove_history_item(self.orig_length)
159
159
160 # If it still doesn't match, just reload readline history.
160 # If it still doesn't match, just reload readline history.
161 if self.current_length() != self.orig_length \
161 if self.current_length() != self.orig_length \
162 or self.get_readline_tail() != self.readline_tail:
162 or self.get_readline_tail() != self.readline_tail:
163 self.shell.refill_readline_hist()
163 self.shell.refill_readline_hist()
164 except (AttributeError, IndexError):
164 except (AttributeError, IndexError):
165 pass
165 pass
166 # Returning False will cause exceptions to propagate
166 # Returning False will cause exceptions to propagate
167 return False
167 return False
168
168
169 def current_length(self):
169 def current_length(self):
170 return self.shell.readline.get_current_history_length()
170 return self.shell.readline.get_current_history_length()
171
171
172 def get_readline_tail(self, n=10):
172 def get_readline_tail(self, n=10):
173 """Get the last n items in readline history."""
173 """Get the last n items in readline history."""
174 end = self.shell.readline.get_current_history_length() + 1
174 end = self.shell.readline.get_current_history_length() + 1
175 start = max(end-n, 1)
175 start = max(end-n, 1)
176 ghi = self.shell.readline.get_history_item
176 ghi = self.shell.readline.get_history_item
177 return [ghi(x) for x in range(start, end)]
177 return [ghi(x) for x in range(start, end)]
178
178
179
179
180 _autocall_help = """
180 _autocall_help = """
181 Make IPython automatically call any callable object even if
181 Make IPython automatically call any callable object even if
182 you didn't type explicit parentheses. For example, 'str 43' becomes 'str(43)'
182 you didn't type explicit parentheses. For example, 'str 43' becomes 'str(43)'
183 automatically. The value can be '0' to disable the feature, '1' for 'smart'
183 automatically. The value can be '0' to disable the feature, '1' for 'smart'
184 autocall, where it is not applied if there are no more arguments on the line,
184 autocall, where it is not applied if there are no more arguments on the line,
185 and '2' for 'full' autocall, where all callable objects are automatically
185 and '2' for 'full' autocall, where all callable objects are automatically
186 called (even if no arguments are present). The default is '1'.
186 called (even if no arguments are present). The default is '1'.
187 """
187 """
188
188
189 #-----------------------------------------------------------------------------
189 #-----------------------------------------------------------------------------
190 # Main IPython class
190 # Main IPython class
191 #-----------------------------------------------------------------------------
191 #-----------------------------------------------------------------------------
192
192
193 class InteractiveShell(SingletonConfigurable, Magic):
193 class InteractiveShell(SingletonConfigurable, Magic):
194 """An enhanced, interactive shell for Python."""
194 """An enhanced, interactive shell for Python."""
195
195
196 _instance = None
196 _instance = None
197
197
198 autocall = Enum((0,1,2), default_value=1, config=True, help=
198 autocall = Enum((0,1,2), default_value=1, config=True, help=
199 """
199 """
200 Make IPython automatically call any callable object even if you didn't
200 Make IPython automatically call any callable object even if you didn't
201 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
201 type explicit parentheses. For example, 'str 43' becomes 'str(43)'
202 automatically. The value can be '0' to disable the feature, '1' for
202 automatically. The value can be '0' to disable the feature, '1' for
203 'smart' autocall, where it is not applied if there are no more
203 'smart' autocall, where it is not applied if there are no more
204 arguments on the line, and '2' for 'full' autocall, where all callable
204 arguments on the line, and '2' for 'full' autocall, where all callable
205 objects are automatically called (even if no arguments are present).
205 objects are automatically called (even if no arguments are present).
206 The default is '1'.
206 The default is '1'.
207 """
207 """
208 )
208 )
209 # TODO: remove all autoindent logic and put into frontends.
209 # TODO: remove all autoindent logic and put into frontends.
210 # We can't do this yet because even runlines uses the autoindent.
210 # We can't do this yet because even runlines uses the autoindent.
211 autoindent = CBool(True, config=True, help=
211 autoindent = CBool(True, config=True, help=
212 """
212 """
213 Autoindent IPython code entered interactively.
213 Autoindent IPython code entered interactively.
214 """
214 """
215 )
215 )
216 automagic = CBool(True, config=True, help=
216 automagic = CBool(True, config=True, help=
217 """
217 """
218 Enable magic commands to be called without the leading %.
218 Enable magic commands to be called without the leading %.
219 """
219 """
220 )
220 )
221 cache_size = Int(1000, config=True, help=
221 cache_size = Int(1000, config=True, help=
222 """
222 """
223 Set the size of the output cache. The default is 1000, you can
223 Set the size of the output cache. The default is 1000, you can
224 change it permanently in your config file. Setting it to 0 completely
224 change it permanently in your config file. Setting it to 0 completely
225 disables the caching system, and the minimum value accepted is 20 (if
225 disables the caching system, and the minimum value accepted is 20 (if
226 you provide a value less than 20, it is reset to 0 and a warning is
226 you provide a value less than 20, it is reset to 0 and a warning is
227 issued). This limit is defined because otherwise you'll spend more
227 issued). This limit is defined because otherwise you'll spend more
228 time re-flushing a too small cache than working
228 time re-flushing a too small cache than working
229 """
229 """
230 )
230 )
231 color_info = CBool(True, config=True, help=
231 color_info = CBool(True, config=True, help=
232 """
232 """
233 Use colors for displaying information about objects. Because this
233 Use colors for displaying information about objects. Because this
234 information is passed through a pager (like 'less'), and some pagers
234 information is passed through a pager (like 'less'), and some pagers
235 get confused with color codes, this capability can be turned off.
235 get confused with color codes, this capability can be turned off.
236 """
236 """
237 )
237 )
238 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
238 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
239 default_value=get_default_colors(), config=True,
239 default_value=get_default_colors(), config=True,
240 help="Set the color scheme (NoColor, Linux, or LightBG)."
240 help="Set the color scheme (NoColor, Linux, or LightBG)."
241 )
241 )
242 debug = CBool(False, config=True)
242 debug = CBool(False, config=True)
243 deep_reload = CBool(False, config=True, help=
243 deep_reload = CBool(False, config=True, help=
244 """
244 """
245 Enable deep (recursive) reloading by default. IPython can use the
245 Enable deep (recursive) reloading by default. IPython can use the
246 deep_reload module which reloads changes in modules recursively (it
246 deep_reload module which reloads changes in modules recursively (it
247 replaces the reload() function, so you don't need to change anything to
247 replaces the reload() function, so you don't need to change anything to
248 use it). deep_reload() forces a full reload of modules whose code may
248 use it). deep_reload() forces a full reload of modules whose code may
249 have changed, which the default reload() function does not. When
249 have changed, which the default reload() function does not. When
250 deep_reload is off, IPython will use the normal reload(), but
250 deep_reload is off, IPython will use the normal reload(), but
251 deep_reload will still be available as dreload().
251 deep_reload will still be available as dreload().
252 """
252 """
253 )
253 )
254 display_formatter = Instance(DisplayFormatter)
254 display_formatter = Instance(DisplayFormatter)
255 displayhook_class = Type(DisplayHook)
255 displayhook_class = Type(DisplayHook)
256 display_pub_class = Type(DisplayPublisher)
256 display_pub_class = Type(DisplayPublisher)
257
257
258 exit_now = CBool(False)
258 exit_now = CBool(False)
259 exiter = Instance(ExitAutocall)
259 exiter = Instance(ExitAutocall)
260 def _exiter_default(self):
260 def _exiter_default(self):
261 return ExitAutocall(self)
261 return ExitAutocall(self)
262 # Monotonically increasing execution counter
262 # Monotonically increasing execution counter
263 execution_count = Int(1)
263 execution_count = Int(1)
264 filename = Unicode("<ipython console>")
264 filename = Unicode("<ipython console>")
265 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
265 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
266
266
267 # Input splitter, to split entire cells of input into either individual
267 # Input splitter, to split entire cells of input into either individual
268 # interactive statements or whole blocks.
268 # interactive statements or whole blocks.
269 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
269 input_splitter = Instance('IPython.core.inputsplitter.IPythonInputSplitter',
270 (), {})
270 (), {})
271 logstart = CBool(False, config=True, help=
271 logstart = CBool(False, config=True, help=
272 """
272 """
273 Start logging to the default log file.
273 Start logging to the default log file.
274 """
274 """
275 )
275 )
276 logfile = Unicode('', config=True, help=
276 logfile = Unicode('', config=True, help=
277 """
277 """
278 The name of the logfile to use.
278 The name of the logfile to use.
279 """
279 """
280 )
280 )
281 logappend = Unicode('', config=True, help=
281 logappend = Unicode('', config=True, help=
282 """
282 """
283 Start logging to the given file in append mode.
283 Start logging to the given file in append mode.
284 """
284 """
285 )
285 )
286 object_info_string_level = Enum((0,1,2), default_value=0,
286 object_info_string_level = Enum((0,1,2), default_value=0,
287 config=True)
287 config=True)
288 pdb = CBool(False, config=True, help=
288 pdb = CBool(False, config=True, help=
289 """
289 """
290 Automatically call the pdb debugger after every exception.
290 Automatically call the pdb debugger after every exception.
291 """
291 """
292 )
292 )
293
293
294 prompt_in1 = Unicode('In [\\#]: ', config=True)
294 prompt_in1 = Unicode('In [\\#]: ', config=True)
295 prompt_in2 = Unicode(' .\\D.: ', config=True)
295 prompt_in2 = Unicode(' .\\D.: ', config=True)
296 prompt_out = Unicode('Out[\\#]: ', config=True)
296 prompt_out = Unicode('Out[\\#]: ', config=True)
297 prompts_pad_left = CBool(True, config=True)
297 prompts_pad_left = CBool(True, config=True)
298 quiet = CBool(False, config=True)
298 quiet = CBool(False, config=True)
299
299
300 history_length = Int(10000, config=True)
300 history_length = Int(10000, config=True)
301
301
302 # The readline stuff will eventually be moved to the terminal subclass
302 # The readline stuff will eventually be moved to the terminal subclass
303 # but for now, we can't do that as readline is welded in everywhere.
303 # but for now, we can't do that as readline is welded in everywhere.
304 readline_use = CBool(True, config=True)
304 readline_use = CBool(True, config=True)
305 readline_merge_completions = CBool(True, config=True)
305 readline_merge_completions = CBool(True, config=True)
306 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
306 readline_omit__names = Enum((0,1,2), default_value=2, config=True)
307 readline_remove_delims = Unicode('-/~', config=True)
307 readline_remove_delims = Unicode('-/~', config=True)
308 # don't use \M- bindings by default, because they
308 # don't use \M- bindings by default, because they
309 # conflict with 8-bit encodings. See gh-58,gh-88
309 # conflict with 8-bit encodings. See gh-58,gh-88
310 readline_parse_and_bind = List([
310 readline_parse_and_bind = List([
311 'tab: complete',
311 'tab: complete',
312 '"\C-l": clear-screen',
312 '"\C-l": clear-screen',
313 'set show-all-if-ambiguous on',
313 'set show-all-if-ambiguous on',
314 '"\C-o": tab-insert',
314 '"\C-o": tab-insert',
315 '"\C-r": reverse-search-history',
315 '"\C-r": reverse-search-history',
316 '"\C-s": forward-search-history',
316 '"\C-s": forward-search-history',
317 '"\C-p": history-search-backward',
317 '"\C-p": history-search-backward',
318 '"\C-n": history-search-forward',
318 '"\C-n": history-search-forward',
319 '"\e[A": history-search-backward',
319 '"\e[A": history-search-backward',
320 '"\e[B": history-search-forward',
320 '"\e[B": history-search-forward',
321 '"\C-k": kill-line',
321 '"\C-k": kill-line',
322 '"\C-u": unix-line-discard',
322 '"\C-u": unix-line-discard',
323 ], allow_none=False, config=True)
323 ], allow_none=False, config=True)
324
324
325 # TODO: this part of prompt management should be moved to the frontends.
325 # TODO: this part of prompt management should be moved to the frontends.
326 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
326 # Use custom TraitTypes that convert '0'->'' and '\\n'->'\n'
327 separate_in = SeparateUnicode('\n', config=True)
327 separate_in = SeparateUnicode('\n', config=True)
328 separate_out = SeparateUnicode('', config=True)
328 separate_out = SeparateUnicode('', config=True)
329 separate_out2 = SeparateUnicode('', config=True)
329 separate_out2 = SeparateUnicode('', config=True)
330 wildcards_case_sensitive = CBool(True, config=True)
330 wildcards_case_sensitive = CBool(True, config=True)
331 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
331 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
332 default_value='Context', config=True)
332 default_value='Context', config=True)
333
333
334 # Subcomponents of InteractiveShell
334 # Subcomponents of InteractiveShell
335 alias_manager = Instance('IPython.core.alias.AliasManager')
335 alias_manager = Instance('IPython.core.alias.AliasManager')
336 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
336 prefilter_manager = Instance('IPython.core.prefilter.PrefilterManager')
337 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
337 builtin_trap = Instance('IPython.core.builtin_trap.BuiltinTrap')
338 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
338 display_trap = Instance('IPython.core.display_trap.DisplayTrap')
339 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
339 extension_manager = Instance('IPython.core.extensions.ExtensionManager')
340 plugin_manager = Instance('IPython.core.plugin.PluginManager')
340 plugin_manager = Instance('IPython.core.plugin.PluginManager')
341 payload_manager = Instance('IPython.core.payload.PayloadManager')
341 payload_manager = Instance('IPython.core.payload.PayloadManager')
342 history_manager = Instance('IPython.core.history.HistoryManager')
342 history_manager = Instance('IPython.core.history.HistoryManager')
343
343
344 profile_dir = Instance('IPython.core.application.ProfileDir')
344 profile_dir = Instance('IPython.core.application.ProfileDir')
345 @property
345 @property
346 def profile(self):
346 def profile(self):
347 if self.profile_dir is not None:
347 if self.profile_dir is not None:
348 name = os.path.basename(self.profile_dir.location)
348 name = os.path.basename(self.profile_dir.location)
349 return name.replace('profile_','')
349 return name.replace('profile_','')
350
350
351
351
352 # Private interface
352 # Private interface
353 _post_execute = Instance(dict)
353 _post_execute = Instance(dict)
354
354
355 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
355 def __init__(self, config=None, ipython_dir=None, profile_dir=None,
356 user_ns=None, user_global_ns=None,
356 user_ns=None, user_global_ns=None,
357 custom_exceptions=((), None)):
357 custom_exceptions=((), None)):
358
358
359 # This is where traits with a config_key argument are updated
359 # This is where traits with a config_key argument are updated
360 # from the values on config.
360 # from the values on config.
361 super(InteractiveShell, self).__init__(config=config)
361 super(InteractiveShell, self).__init__(config=config)
362
362
363 # These are relatively independent and stateless
363 # These are relatively independent and stateless
364 self.init_ipython_dir(ipython_dir)
364 self.init_ipython_dir(ipython_dir)
365 self.init_profile_dir(profile_dir)
365 self.init_profile_dir(profile_dir)
366 self.init_instance_attrs()
366 self.init_instance_attrs()
367 self.init_environment()
367 self.init_environment()
368
368
369 # Create namespaces (user_ns, user_global_ns, etc.)
369 # Create namespaces (user_ns, user_global_ns, etc.)
370 self.init_create_namespaces(user_ns, user_global_ns)
370 self.init_create_namespaces(user_ns, user_global_ns)
371 # This has to be done after init_create_namespaces because it uses
371 # This has to be done after init_create_namespaces because it uses
372 # something in self.user_ns, but before init_sys_modules, which
372 # something in self.user_ns, but before init_sys_modules, which
373 # is the first thing to modify sys.
373 # is the first thing to modify sys.
374 # TODO: When we override sys.stdout and sys.stderr before this class
374 # TODO: When we override sys.stdout and sys.stderr before this class
375 # is created, we are saving the overridden ones here. Not sure if this
375 # is created, we are saving the overridden ones here. Not sure if this
376 # is what we want to do.
376 # is what we want to do.
377 self.save_sys_module_state()
377 self.save_sys_module_state()
378 self.init_sys_modules()
378 self.init_sys_modules()
379
379
380 # While we're trying to have each part of the code directly access what
380 # While we're trying to have each part of the code directly access what
381 # it needs without keeping redundant references to objects, we have too
381 # it needs without keeping redundant references to objects, we have too
382 # much legacy code that expects ip.db to exist.
382 # much legacy code that expects ip.db to exist.
383 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
383 self.db = PickleShareDB(os.path.join(self.profile_dir.location, 'db'))
384
384
385 self.init_history()
385 self.init_history()
386 self.init_encoding()
386 self.init_encoding()
387 self.init_prefilter()
387 self.init_prefilter()
388
388
389 Magic.__init__(self, self)
389 Magic.__init__(self, self)
390
390
391 self.init_syntax_highlighting()
391 self.init_syntax_highlighting()
392 self.init_hooks()
392 self.init_hooks()
393 self.init_pushd_popd_magic()
393 self.init_pushd_popd_magic()
394 # self.init_traceback_handlers use to be here, but we moved it below
394 # self.init_traceback_handlers use to be here, but we moved it below
395 # because it and init_io have to come after init_readline.
395 # because it and init_io have to come after init_readline.
396 self.init_user_ns()
396 self.init_user_ns()
397 self.init_logger()
397 self.init_logger()
398 self.init_alias()
398 self.init_alias()
399 self.init_builtins()
399 self.init_builtins()
400
400
401 # pre_config_initialization
401 # pre_config_initialization
402
402
403 # The next section should contain everything that was in ipmaker.
403 # The next section should contain everything that was in ipmaker.
404 self.init_logstart()
404 self.init_logstart()
405
405
406 # The following was in post_config_initialization
406 # The following was in post_config_initialization
407 self.init_inspector()
407 self.init_inspector()
408 # init_readline() must come before init_io(), because init_io uses
408 # init_readline() must come before init_io(), because init_io uses
409 # readline related things.
409 # readline related things.
410 self.init_readline()
410 self.init_readline()
411 # We save this here in case user code replaces raw_input, but it needs
411 # We save this here in case user code replaces raw_input, but it needs
412 # to be after init_readline(), because PyPy's readline works by replacing
412 # to be after init_readline(), because PyPy's readline works by replacing
413 # raw_input.
413 # raw_input.
414 self.raw_input_original = raw_input
414 self.raw_input_original = raw_input
415 # init_completer must come after init_readline, because it needs to
415 # init_completer must come after init_readline, because it needs to
416 # know whether readline is present or not system-wide to configure the
416 # know whether readline is present or not system-wide to configure the
417 # completers, since the completion machinery can now operate
417 # completers, since the completion machinery can now operate
418 # independently of readline (e.g. over the network)
418 # independently of readline (e.g. over the network)
419 self.init_completer()
419 self.init_completer()
420 # TODO: init_io() needs to happen before init_traceback handlers
420 # TODO: init_io() needs to happen before init_traceback handlers
421 # because the traceback handlers hardcode the stdout/stderr streams.
421 # because the traceback handlers hardcode the stdout/stderr streams.
422 # This logic in in debugger.Pdb and should eventually be changed.
422 # This logic in in debugger.Pdb and should eventually be changed.
423 self.init_io()
423 self.init_io()
424 self.init_traceback_handlers(custom_exceptions)
424 self.init_traceback_handlers(custom_exceptions)
425 self.init_prompts()
425 self.init_prompts()
426 self.init_display_formatter()
426 self.init_display_formatter()
427 self.init_display_pub()
427 self.init_display_pub()
428 self.init_displayhook()
428 self.init_displayhook()
429 self.init_reload_doctest()
429 self.init_reload_doctest()
430 self.init_magics()
430 self.init_magics()
431 self.init_pdb()
431 self.init_pdb()
432 self.init_extension_manager()
432 self.init_extension_manager()
433 self.init_plugin_manager()
433 self.init_plugin_manager()
434 self.init_payload()
434 self.init_payload()
435 self.hooks.late_startup_hook()
435 self.hooks.late_startup_hook()
436 atexit.register(self.atexit_operations)
436 atexit.register(self.atexit_operations)
437
437
438 def get_ipython(self):
438 def get_ipython(self):
439 """Return the currently running IPython instance."""
439 """Return the currently running IPython instance."""
440 return self
440 return self
441
441
442 #-------------------------------------------------------------------------
442 #-------------------------------------------------------------------------
443 # Trait changed handlers
443 # Trait changed handlers
444 #-------------------------------------------------------------------------
444 #-------------------------------------------------------------------------
445
445
446 def _ipython_dir_changed(self, name, new):
446 def _ipython_dir_changed(self, name, new):
447 if not os.path.isdir(new):
447 if not os.path.isdir(new):
448 os.makedirs(new, mode = 0777)
448 os.makedirs(new, mode = 0777)
449
449
450 def set_autoindent(self,value=None):
450 def set_autoindent(self,value=None):
451 """Set the autoindent flag, checking for readline support.
451 """Set the autoindent flag, checking for readline support.
452
452
453 If called with no arguments, it acts as a toggle."""
453 If called with no arguments, it acts as a toggle."""
454
454
455 if not self.has_readline:
455 if not self.has_readline:
456 if os.name == 'posix':
456 if os.name == 'posix':
457 warn("The auto-indent feature requires the readline library")
457 warn("The auto-indent feature requires the readline library")
458 self.autoindent = 0
458 self.autoindent = 0
459 return
459 return
460 if value is None:
460 if value is None:
461 self.autoindent = not self.autoindent
461 self.autoindent = not self.autoindent
462 else:
462 else:
463 self.autoindent = value
463 self.autoindent = value
464
464
465 #-------------------------------------------------------------------------
465 #-------------------------------------------------------------------------
466 # init_* methods called by __init__
466 # init_* methods called by __init__
467 #-------------------------------------------------------------------------
467 #-------------------------------------------------------------------------
468
468
469 def init_ipython_dir(self, ipython_dir):
469 def init_ipython_dir(self, ipython_dir):
470 if ipython_dir is not None:
470 if ipython_dir is not None:
471 self.ipython_dir = ipython_dir
471 self.ipython_dir = ipython_dir
472 return
472 return
473
473
474 self.ipython_dir = get_ipython_dir()
474 self.ipython_dir = get_ipython_dir()
475
475
476 def init_profile_dir(self, profile_dir):
476 def init_profile_dir(self, profile_dir):
477 if profile_dir is not None:
477 if profile_dir is not None:
478 self.profile_dir = profile_dir
478 self.profile_dir = profile_dir
479 return
479 return
480 self.profile_dir =\
480 self.profile_dir =\
481 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
481 ProfileDir.create_profile_dir_by_name(self.ipython_dir, 'default')
482
482
483 def init_instance_attrs(self):
483 def init_instance_attrs(self):
484 self.more = False
484 self.more = False
485
485
486 # command compiler
486 # command compiler
487 self.compile = CachingCompiler()
487 self.compile = CachingCompiler()
488
488
489 # Make an empty namespace, which extension writers can rely on both
489 # Make an empty namespace, which extension writers can rely on both
490 # existing and NEVER being used by ipython itself. This gives them a
490 # existing and NEVER being used by ipython itself. This gives them a
491 # convenient location for storing additional information and state
491 # convenient location for storing additional information and state
492 # their extensions may require, without fear of collisions with other
492 # their extensions may require, without fear of collisions with other
493 # ipython names that may develop later.
493 # ipython names that may develop later.
494 self.meta = Struct()
494 self.meta = Struct()
495
495
496 # Temporary files used for various purposes. Deleted at exit.
496 # Temporary files used for various purposes. Deleted at exit.
497 self.tempfiles = []
497 self.tempfiles = []
498
498
499 # Keep track of readline usage (later set by init_readline)
499 # Keep track of readline usage (later set by init_readline)
500 self.has_readline = False
500 self.has_readline = False
501
501
502 # keep track of where we started running (mainly for crash post-mortem)
502 # keep track of where we started running (mainly for crash post-mortem)
503 # This is not being used anywhere currently.
503 # This is not being used anywhere currently.
504 self.starting_dir = os.getcwdu()
504 self.starting_dir = os.getcwdu()
505
505
506 # Indentation management
506 # Indentation management
507 self.indent_current_nsp = 0
507 self.indent_current_nsp = 0
508
508
509 # Dict to track post-execution functions that have been registered
509 # Dict to track post-execution functions that have been registered
510 self._post_execute = {}
510 self._post_execute = {}
511
511
512 def init_environment(self):
512 def init_environment(self):
513 """Any changes we need to make to the user's environment."""
513 """Any changes we need to make to the user's environment."""
514 pass
514 pass
515
515
516 def init_encoding(self):
516 def init_encoding(self):
517 # Get system encoding at startup time. Certain terminals (like Emacs
517 # Get system encoding at startup time. Certain terminals (like Emacs
518 # under Win32 have it set to None, and we need to have a known valid
518 # under Win32 have it set to None, and we need to have a known valid
519 # encoding to use in the raw_input() method
519 # encoding to use in the raw_input() method
520 try:
520 try:
521 self.stdin_encoding = sys.stdin.encoding or 'ascii'
521 self.stdin_encoding = sys.stdin.encoding or 'ascii'
522 except AttributeError:
522 except AttributeError:
523 self.stdin_encoding = 'ascii'
523 self.stdin_encoding = 'ascii'
524
524
525 def init_syntax_highlighting(self):
525 def init_syntax_highlighting(self):
526 # Python source parser/formatter for syntax highlighting
526 # Python source parser/formatter for syntax highlighting
527 pyformat = PyColorize.Parser().format
527 pyformat = PyColorize.Parser().format
528 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
528 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
529
529
530 def init_pushd_popd_magic(self):
530 def init_pushd_popd_magic(self):
531 # for pushd/popd management
531 # for pushd/popd management
532 try:
532 try:
533 self.home_dir = get_home_dir()
533 self.home_dir = get_home_dir()
534 except HomeDirError, msg:
534 except HomeDirError, msg:
535 fatal(msg)
535 fatal(msg)
536
536
537 self.dir_stack = []
537 self.dir_stack = []
538
538
539 def init_logger(self):
539 def init_logger(self):
540 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
540 self.logger = Logger(self.home_dir, logfname='ipython_log.py',
541 logmode='rotate')
541 logmode='rotate')
542
542
543 def init_logstart(self):
543 def init_logstart(self):
544 """Initialize logging in case it was requested at the command line.
544 """Initialize logging in case it was requested at the command line.
545 """
545 """
546 if self.logappend:
546 if self.logappend:
547 self.magic_logstart(self.logappend + ' append')
547 self.magic_logstart(self.logappend + ' append')
548 elif self.logfile:
548 elif self.logfile:
549 self.magic_logstart(self.logfile)
549 self.magic_logstart(self.logfile)
550 elif self.logstart:
550 elif self.logstart:
551 self.magic_logstart()
551 self.magic_logstart()
552
552
553 def init_builtins(self):
553 def init_builtins(self):
554 self.builtin_trap = BuiltinTrap(shell=self)
554 self.builtin_trap = BuiltinTrap(shell=self)
555
555
556 def init_inspector(self):
556 def init_inspector(self):
557 # Object inspector
557 # Object inspector
558 self.inspector = oinspect.Inspector(oinspect.InspectColors,
558 self.inspector = oinspect.Inspector(oinspect.InspectColors,
559 PyColorize.ANSICodeColors,
559 PyColorize.ANSICodeColors,
560 'NoColor',
560 'NoColor',
561 self.object_info_string_level)
561 self.object_info_string_level)
562
562
563 def init_io(self):
563 def init_io(self):
564 # This will just use sys.stdout and sys.stderr. If you want to
564 # This will just use sys.stdout and sys.stderr. If you want to
565 # override sys.stdout and sys.stderr themselves, you need to do that
565 # override sys.stdout and sys.stderr themselves, you need to do that
566 # *before* instantiating this class, because io holds onto
566 # *before* instantiating this class, because io holds onto
567 # references to the underlying streams.
567 # references to the underlying streams.
568 if sys.platform == 'win32' and self.has_readline:
568 if sys.platform == 'win32' and self.has_readline:
569 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
569 io.stdout = io.stderr = io.IOStream(self.readline._outputfile)
570 else:
570 else:
571 io.stdout = io.IOStream(sys.stdout)
571 io.stdout = io.IOStream(sys.stdout)
572 io.stderr = io.IOStream(sys.stderr)
572 io.stderr = io.IOStream(sys.stderr)
573
573
574 def init_prompts(self):
574 def init_prompts(self):
575 # TODO: This is a pass for now because the prompts are managed inside
575 # TODO: This is a pass for now because the prompts are managed inside
576 # the DisplayHook. Once there is a separate prompt manager, this
576 # the DisplayHook. Once there is a separate prompt manager, this
577 # will initialize that object and all prompt related information.
577 # will initialize that object and all prompt related information.
578 pass
578 pass
579
579
580 def init_display_formatter(self):
580 def init_display_formatter(self):
581 self.display_formatter = DisplayFormatter(config=self.config)
581 self.display_formatter = DisplayFormatter(config=self.config)
582
582
583 def init_display_pub(self):
583 def init_display_pub(self):
584 self.display_pub = self.display_pub_class(config=self.config)
584 self.display_pub = self.display_pub_class(config=self.config)
585
585
586 def init_displayhook(self):
586 def init_displayhook(self):
587 # Initialize displayhook, set in/out prompts and printing system
587 # Initialize displayhook, set in/out prompts and printing system
588 self.displayhook = self.displayhook_class(
588 self.displayhook = self.displayhook_class(
589 config=self.config,
589 config=self.config,
590 shell=self,
590 shell=self,
591 cache_size=self.cache_size,
591 cache_size=self.cache_size,
592 input_sep = self.separate_in,
592 input_sep = self.separate_in,
593 output_sep = self.separate_out,
593 output_sep = self.separate_out,
594 output_sep2 = self.separate_out2,
594 output_sep2 = self.separate_out2,
595 ps1 = self.prompt_in1,
595 ps1 = self.prompt_in1,
596 ps2 = self.prompt_in2,
596 ps2 = self.prompt_in2,
597 ps_out = self.prompt_out,
597 ps_out = self.prompt_out,
598 pad_left = self.prompts_pad_left
598 pad_left = self.prompts_pad_left
599 )
599 )
600 # This is a context manager that installs/revmoes the displayhook at
600 # This is a context manager that installs/revmoes the displayhook at
601 # the appropriate time.
601 # the appropriate time.
602 self.display_trap = DisplayTrap(hook=self.displayhook)
602 self.display_trap = DisplayTrap(hook=self.displayhook)
603
603
604 def init_reload_doctest(self):
604 def init_reload_doctest(self):
605 # Do a proper resetting of doctest, including the necessary displayhook
605 # Do a proper resetting of doctest, including the necessary displayhook
606 # monkeypatching
606 # monkeypatching
607 try:
607 try:
608 doctest_reload()
608 doctest_reload()
609 except ImportError:
609 except ImportError:
610 warn("doctest module does not exist.")
610 warn("doctest module does not exist.")
611
611
612 #-------------------------------------------------------------------------
612 #-------------------------------------------------------------------------
613 # Things related to injections into the sys module
613 # Things related to injections into the sys module
614 #-------------------------------------------------------------------------
614 #-------------------------------------------------------------------------
615
615
616 def save_sys_module_state(self):
616 def save_sys_module_state(self):
617 """Save the state of hooks in the sys module.
617 """Save the state of hooks in the sys module.
618
618
619 This has to be called after self.user_ns is created.
619 This has to be called after self.user_ns is created.
620 """
620 """
621 self._orig_sys_module_state = {}
621 self._orig_sys_module_state = {}
622 self._orig_sys_module_state['stdin'] = sys.stdin
622 self._orig_sys_module_state['stdin'] = sys.stdin
623 self._orig_sys_module_state['stdout'] = sys.stdout
623 self._orig_sys_module_state['stdout'] = sys.stdout
624 self._orig_sys_module_state['stderr'] = sys.stderr
624 self._orig_sys_module_state['stderr'] = sys.stderr
625 self._orig_sys_module_state['excepthook'] = sys.excepthook
625 self._orig_sys_module_state['excepthook'] = sys.excepthook
626 try:
626 try:
627 self._orig_sys_modules_main_name = self.user_ns['__name__']
627 self._orig_sys_modules_main_name = self.user_ns['__name__']
628 except KeyError:
628 except KeyError:
629 pass
629 pass
630
630
631 def restore_sys_module_state(self):
631 def restore_sys_module_state(self):
632 """Restore the state of the sys module."""
632 """Restore the state of the sys module."""
633 try:
633 try:
634 for k, v in self._orig_sys_module_state.iteritems():
634 for k, v in self._orig_sys_module_state.iteritems():
635 setattr(sys, k, v)
635 setattr(sys, k, v)
636 except AttributeError:
636 except AttributeError:
637 pass
637 pass
638 # Reset what what done in self.init_sys_modules
638 # Reset what what done in self.init_sys_modules
639 try:
639 try:
640 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
640 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
641 except (AttributeError, KeyError):
641 except (AttributeError, KeyError):
642 pass
642 pass
643
643
644 #-------------------------------------------------------------------------
644 #-------------------------------------------------------------------------
645 # Things related to hooks
645 # Things related to hooks
646 #-------------------------------------------------------------------------
646 #-------------------------------------------------------------------------
647
647
648 def init_hooks(self):
648 def init_hooks(self):
649 # hooks holds pointers used for user-side customizations
649 # hooks holds pointers used for user-side customizations
650 self.hooks = Struct()
650 self.hooks = Struct()
651
651
652 self.strdispatchers = {}
652 self.strdispatchers = {}
653
653
654 # Set all default hooks, defined in the IPython.hooks module.
654 # Set all default hooks, defined in the IPython.hooks module.
655 hooks = IPython.core.hooks
655 hooks = IPython.core.hooks
656 for hook_name in hooks.__all__:
656 for hook_name in hooks.__all__:
657 # default hooks have priority 100, i.e. low; user hooks should have
657 # default hooks have priority 100, i.e. low; user hooks should have
658 # 0-100 priority
658 # 0-100 priority
659 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
659 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
660
660
661 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
661 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
662 """set_hook(name,hook) -> sets an internal IPython hook.
662 """set_hook(name,hook) -> sets an internal IPython hook.
663
663
664 IPython exposes some of its internal API as user-modifiable hooks. By
664 IPython exposes some of its internal API as user-modifiable hooks. By
665 adding your function to one of these hooks, you can modify IPython's
665 adding your function to one of these hooks, you can modify IPython's
666 behavior to call at runtime your own routines."""
666 behavior to call at runtime your own routines."""
667
667
668 # At some point in the future, this should validate the hook before it
668 # At some point in the future, this should validate the hook before it
669 # accepts it. Probably at least check that the hook takes the number
669 # accepts it. Probably at least check that the hook takes the number
670 # of args it's supposed to.
670 # of args it's supposed to.
671
671
672 f = types.MethodType(hook,self)
672 f = types.MethodType(hook,self)
673
673
674 # check if the hook is for strdispatcher first
674 # check if the hook is for strdispatcher first
675 if str_key is not None:
675 if str_key is not None:
676 sdp = self.strdispatchers.get(name, StrDispatch())
676 sdp = self.strdispatchers.get(name, StrDispatch())
677 sdp.add_s(str_key, f, priority )
677 sdp.add_s(str_key, f, priority )
678 self.strdispatchers[name] = sdp
678 self.strdispatchers[name] = sdp
679 return
679 return
680 if re_key is not None:
680 if re_key is not None:
681 sdp = self.strdispatchers.get(name, StrDispatch())
681 sdp = self.strdispatchers.get(name, StrDispatch())
682 sdp.add_re(re.compile(re_key), f, priority )
682 sdp.add_re(re.compile(re_key), f, priority )
683 self.strdispatchers[name] = sdp
683 self.strdispatchers[name] = sdp
684 return
684 return
685
685
686 dp = getattr(self.hooks, name, None)
686 dp = getattr(self.hooks, name, None)
687 if name not in IPython.core.hooks.__all__:
687 if name not in IPython.core.hooks.__all__:
688 print "Warning! Hook '%s' is not one of %s" % \
688 print "Warning! Hook '%s' is not one of %s" % \
689 (name, IPython.core.hooks.__all__ )
689 (name, IPython.core.hooks.__all__ )
690 if not dp:
690 if not dp:
691 dp = IPython.core.hooks.CommandChainDispatcher()
691 dp = IPython.core.hooks.CommandChainDispatcher()
692
692
693 try:
693 try:
694 dp.add(f,priority)
694 dp.add(f,priority)
695 except AttributeError:
695 except AttributeError:
696 # it was not commandchain, plain old func - replace
696 # it was not commandchain, plain old func - replace
697 dp = f
697 dp = f
698
698
699 setattr(self.hooks,name, dp)
699 setattr(self.hooks,name, dp)
700
700
701 def register_post_execute(self, func):
701 def register_post_execute(self, func):
702 """Register a function for calling after code execution.
702 """Register a function for calling after code execution.
703 """
703 """
704 if not callable(func):
704 if not callable(func):
705 raise ValueError('argument %s must be callable' % func)
705 raise ValueError('argument %s must be callable' % func)
706 self._post_execute[func] = True
706 self._post_execute[func] = True
707
707
708 #-------------------------------------------------------------------------
708 #-------------------------------------------------------------------------
709 # Things related to the "main" module
709 # Things related to the "main" module
710 #-------------------------------------------------------------------------
710 #-------------------------------------------------------------------------
711
711
712 def new_main_mod(self,ns=None):
712 def new_main_mod(self,ns=None):
713 """Return a new 'main' module object for user code execution.
713 """Return a new 'main' module object for user code execution.
714 """
714 """
715 main_mod = self._user_main_module
715 main_mod = self._user_main_module
716 init_fakemod_dict(main_mod,ns)
716 init_fakemod_dict(main_mod,ns)
717 return main_mod
717 return main_mod
718
718
719 def cache_main_mod(self,ns,fname):
719 def cache_main_mod(self,ns,fname):
720 """Cache a main module's namespace.
720 """Cache a main module's namespace.
721
721
722 When scripts are executed via %run, we must keep a reference to the
722 When scripts are executed via %run, we must keep a reference to the
723 namespace of their __main__ module (a FakeModule instance) around so
723 namespace of their __main__ module (a FakeModule instance) around so
724 that Python doesn't clear it, rendering objects defined therein
724 that Python doesn't clear it, rendering objects defined therein
725 useless.
725 useless.
726
726
727 This method keeps said reference in a private dict, keyed by the
727 This method keeps said reference in a private dict, keyed by the
728 absolute path of the module object (which corresponds to the script
728 absolute path of the module object (which corresponds to the script
729 path). This way, for multiple executions of the same script we only
729 path). This way, for multiple executions of the same script we only
730 keep one copy of the namespace (the last one), thus preventing memory
730 keep one copy of the namespace (the last one), thus preventing memory
731 leaks from old references while allowing the objects from the last
731 leaks from old references while allowing the objects from the last
732 execution to be accessible.
732 execution to be accessible.
733
733
734 Note: we can not allow the actual FakeModule instances to be deleted,
734 Note: we can not allow the actual FakeModule instances to be deleted,
735 because of how Python tears down modules (it hard-sets all their
735 because of how Python tears down modules (it hard-sets all their
736 references to None without regard for reference counts). This method
736 references to None without regard for reference counts). This method
737 must therefore make a *copy* of the given namespace, to allow the
737 must therefore make a *copy* of the given namespace, to allow the
738 original module's __dict__ to be cleared and reused.
738 original module's __dict__ to be cleared and reused.
739
739
740
740
741 Parameters
741 Parameters
742 ----------
742 ----------
743 ns : a namespace (a dict, typically)
743 ns : a namespace (a dict, typically)
744
744
745 fname : str
745 fname : str
746 Filename associated with the namespace.
746 Filename associated with the namespace.
747
747
748 Examples
748 Examples
749 --------
749 --------
750
750
751 In [10]: import IPython
751 In [10]: import IPython
752
752
753 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
753 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
754
754
755 In [12]: IPython.__file__ in _ip._main_ns_cache
755 In [12]: IPython.__file__ in _ip._main_ns_cache
756 Out[12]: True
756 Out[12]: True
757 """
757 """
758 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
758 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
759
759
760 def clear_main_mod_cache(self):
760 def clear_main_mod_cache(self):
761 """Clear the cache of main modules.
761 """Clear the cache of main modules.
762
762
763 Mainly for use by utilities like %reset.
763 Mainly for use by utilities like %reset.
764
764
765 Examples
765 Examples
766 --------
766 --------
767
767
768 In [15]: import IPython
768 In [15]: import IPython
769
769
770 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
770 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
771
771
772 In [17]: len(_ip._main_ns_cache) > 0
772 In [17]: len(_ip._main_ns_cache) > 0
773 Out[17]: True
773 Out[17]: True
774
774
775 In [18]: _ip.clear_main_mod_cache()
775 In [18]: _ip.clear_main_mod_cache()
776
776
777 In [19]: len(_ip._main_ns_cache) == 0
777 In [19]: len(_ip._main_ns_cache) == 0
778 Out[19]: True
778 Out[19]: True
779 """
779 """
780 self._main_ns_cache.clear()
780 self._main_ns_cache.clear()
781
781
782 #-------------------------------------------------------------------------
782 #-------------------------------------------------------------------------
783 # Things related to debugging
783 # Things related to debugging
784 #-------------------------------------------------------------------------
784 #-------------------------------------------------------------------------
785
785
786 def init_pdb(self):
786 def init_pdb(self):
787 # Set calling of pdb on exceptions
787 # Set calling of pdb on exceptions
788 # self.call_pdb is a property
788 # self.call_pdb is a property
789 self.call_pdb = self.pdb
789 self.call_pdb = self.pdb
790
790
791 def _get_call_pdb(self):
791 def _get_call_pdb(self):
792 return self._call_pdb
792 return self._call_pdb
793
793
794 def _set_call_pdb(self,val):
794 def _set_call_pdb(self,val):
795
795
796 if val not in (0,1,False,True):
796 if val not in (0,1,False,True):
797 raise ValueError,'new call_pdb value must be boolean'
797 raise ValueError,'new call_pdb value must be boolean'
798
798
799 # store value in instance
799 # store value in instance
800 self._call_pdb = val
800 self._call_pdb = val
801
801
802 # notify the actual exception handlers
802 # notify the actual exception handlers
803 self.InteractiveTB.call_pdb = val
803 self.InteractiveTB.call_pdb = val
804
804
805 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
805 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
806 'Control auto-activation of pdb at exceptions')
806 'Control auto-activation of pdb at exceptions')
807
807
808 def debugger(self,force=False):
808 def debugger(self,force=False):
809 """Call the pydb/pdb debugger.
809 """Call the pydb/pdb debugger.
810
810
811 Keywords:
811 Keywords:
812
812
813 - force(False): by default, this routine checks the instance call_pdb
813 - force(False): by default, this routine checks the instance call_pdb
814 flag and does not actually invoke the debugger if the flag is false.
814 flag and does not actually invoke the debugger if the flag is false.
815 The 'force' option forces the debugger to activate even if the flag
815 The 'force' option forces the debugger to activate even if the flag
816 is false.
816 is false.
817 """
817 """
818
818
819 if not (force or self.call_pdb):
819 if not (force or self.call_pdb):
820 return
820 return
821
821
822 if not hasattr(sys,'last_traceback'):
822 if not hasattr(sys,'last_traceback'):
823 error('No traceback has been produced, nothing to debug.')
823 error('No traceback has been produced, nothing to debug.')
824 return
824 return
825
825
826 # use pydb if available
826 # use pydb if available
827 if debugger.has_pydb:
827 if debugger.has_pydb:
828 from pydb import pm
828 from pydb import pm
829 else:
829 else:
830 # fallback to our internal debugger
830 # fallback to our internal debugger
831 pm = lambda : self.InteractiveTB.debugger(force=True)
831 pm = lambda : self.InteractiveTB.debugger(force=True)
832
832
833 with self.readline_no_record:
833 with self.readline_no_record:
834 pm()
834 pm()
835
835
836 #-------------------------------------------------------------------------
836 #-------------------------------------------------------------------------
837 # Things related to IPython's various namespaces
837 # Things related to IPython's various namespaces
838 #-------------------------------------------------------------------------
838 #-------------------------------------------------------------------------
839
839
840 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
840 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
841 # Create the namespace where the user will operate. user_ns is
841 # Create the namespace where the user will operate. user_ns is
842 # normally the only one used, and it is passed to the exec calls as
842 # normally the only one used, and it is passed to the exec calls as
843 # the locals argument. But we do carry a user_global_ns namespace
843 # the locals argument. But we do carry a user_global_ns namespace
844 # given as the exec 'globals' argument, This is useful in embedding
844 # given as the exec 'globals' argument, This is useful in embedding
845 # situations where the ipython shell opens in a context where the
845 # situations where the ipython shell opens in a context where the
846 # distinction between locals and globals is meaningful. For
846 # distinction between locals and globals is meaningful. For
847 # non-embedded contexts, it is just the same object as the user_ns dict.
847 # non-embedded contexts, it is just the same object as the user_ns dict.
848
848
849 # FIXME. For some strange reason, __builtins__ is showing up at user
849 # FIXME. For some strange reason, __builtins__ is showing up at user
850 # level as a dict instead of a module. This is a manual fix, but I
850 # level as a dict instead of a module. This is a manual fix, but I
851 # should really track down where the problem is coming from. Alex
851 # should really track down where the problem is coming from. Alex
852 # Schmolck reported this problem first.
852 # Schmolck reported this problem first.
853
853
854 # A useful post by Alex Martelli on this topic:
854 # A useful post by Alex Martelli on this topic:
855 # Re: inconsistent value from __builtins__
855 # Re: inconsistent value from __builtins__
856 # Von: Alex Martelli <aleaxit@yahoo.com>
856 # Von: Alex Martelli <aleaxit@yahoo.com>
857 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
857 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
858 # Gruppen: comp.lang.python
858 # Gruppen: comp.lang.python
859
859
860 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
860 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
861 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
861 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
862 # > <type 'dict'>
862 # > <type 'dict'>
863 # > >>> print type(__builtins__)
863 # > >>> print type(__builtins__)
864 # > <type 'module'>
864 # > <type 'module'>
865 # > Is this difference in return value intentional?
865 # > Is this difference in return value intentional?
866
866
867 # Well, it's documented that '__builtins__' can be either a dictionary
867 # Well, it's documented that '__builtins__' can be either a dictionary
868 # or a module, and it's been that way for a long time. Whether it's
868 # or a module, and it's been that way for a long time. Whether it's
869 # intentional (or sensible), I don't know. In any case, the idea is
869 # intentional (or sensible), I don't know. In any case, the idea is
870 # that if you need to access the built-in namespace directly, you
870 # that if you need to access the built-in namespace directly, you
871 # should start with "import __builtin__" (note, no 's') which will
871 # should start with "import __builtin__" (note, no 's') which will
872 # definitely give you a module. Yeah, it's somewhat confusing:-(.
872 # definitely give you a module. Yeah, it's somewhat confusing:-(.
873
873
874 # These routines return properly built dicts as needed by the rest of
874 # These routines return properly built dicts as needed by the rest of
875 # the code, and can also be used by extension writers to generate
875 # the code, and can also be used by extension writers to generate
876 # properly initialized namespaces.
876 # properly initialized namespaces.
877 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
877 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
878 user_global_ns)
878 user_global_ns)
879
879
880 # Assign namespaces
880 # Assign namespaces
881 # This is the namespace where all normal user variables live
881 # This is the namespace where all normal user variables live
882 self.user_ns = user_ns
882 self.user_ns = user_ns
883 self.user_global_ns = user_global_ns
883 self.user_global_ns = user_global_ns
884
884
885 # An auxiliary namespace that checks what parts of the user_ns were
885 # An auxiliary namespace that checks what parts of the user_ns were
886 # loaded at startup, so we can list later only variables defined in
886 # loaded at startup, so we can list later only variables defined in
887 # actual interactive use. Since it is always a subset of user_ns, it
887 # actual interactive use. Since it is always a subset of user_ns, it
888 # doesn't need to be separately tracked in the ns_table.
888 # doesn't need to be separately tracked in the ns_table.
889 self.user_ns_hidden = {}
889 self.user_ns_hidden = {}
890
890
891 # A namespace to keep track of internal data structures to prevent
891 # A namespace to keep track of internal data structures to prevent
892 # them from cluttering user-visible stuff. Will be updated later
892 # them from cluttering user-visible stuff. Will be updated later
893 self.internal_ns = {}
893 self.internal_ns = {}
894
894
895 # Now that FakeModule produces a real module, we've run into a nasty
895 # Now that FakeModule produces a real module, we've run into a nasty
896 # problem: after script execution (via %run), the module where the user
896 # problem: after script execution (via %run), the module where the user
897 # code ran is deleted. Now that this object is a true module (needed
897 # code ran is deleted. Now that this object is a true module (needed
898 # so docetst and other tools work correctly), the Python module
898 # so docetst and other tools work correctly), the Python module
899 # teardown mechanism runs over it, and sets to None every variable
899 # teardown mechanism runs over it, and sets to None every variable
900 # present in that module. Top-level references to objects from the
900 # present in that module. Top-level references to objects from the
901 # script survive, because the user_ns is updated with them. However,
901 # script survive, because the user_ns is updated with them. However,
902 # calling functions defined in the script that use other things from
902 # calling functions defined in the script that use other things from
903 # the script will fail, because the function's closure had references
903 # the script will fail, because the function's closure had references
904 # to the original objects, which are now all None. So we must protect
904 # to the original objects, which are now all None. So we must protect
905 # these modules from deletion by keeping a cache.
905 # these modules from deletion by keeping a cache.
906 #
906 #
907 # To avoid keeping stale modules around (we only need the one from the
907 # To avoid keeping stale modules around (we only need the one from the
908 # last run), we use a dict keyed with the full path to the script, so
908 # last run), we use a dict keyed with the full path to the script, so
909 # only the last version of the module is held in the cache. Note,
909 # only the last version of the module is held in the cache. Note,
910 # however, that we must cache the module *namespace contents* (their
910 # however, that we must cache the module *namespace contents* (their
911 # __dict__). Because if we try to cache the actual modules, old ones
911 # __dict__). Because if we try to cache the actual modules, old ones
912 # (uncached) could be destroyed while still holding references (such as
912 # (uncached) could be destroyed while still holding references (such as
913 # those held by GUI objects that tend to be long-lived)>
913 # those held by GUI objects that tend to be long-lived)>
914 #
914 #
915 # The %reset command will flush this cache. See the cache_main_mod()
915 # The %reset command will flush this cache. See the cache_main_mod()
916 # and clear_main_mod_cache() methods for details on use.
916 # and clear_main_mod_cache() methods for details on use.
917
917
918 # This is the cache used for 'main' namespaces
918 # This is the cache used for 'main' namespaces
919 self._main_ns_cache = {}
919 self._main_ns_cache = {}
920 # And this is the single instance of FakeModule whose __dict__ we keep
920 # And this is the single instance of FakeModule whose __dict__ we keep
921 # copying and clearing for reuse on each %run
921 # copying and clearing for reuse on each %run
922 self._user_main_module = FakeModule()
922 self._user_main_module = FakeModule()
923
923
924 # A table holding all the namespaces IPython deals with, so that
924 # A table holding all the namespaces IPython deals with, so that
925 # introspection facilities can search easily.
925 # introspection facilities can search easily.
926 self.ns_table = {'user':user_ns,
926 self.ns_table = {'user':user_ns,
927 'user_global':user_global_ns,
927 'user_global':user_global_ns,
928 'internal':self.internal_ns,
928 'internal':self.internal_ns,
929 'builtin':builtin_mod.__dict__
929 'builtin':builtin_mod.__dict__
930 }
930 }
931
931
932 # Similarly, track all namespaces where references can be held and that
932 # Similarly, track all namespaces where references can be held and that
933 # we can safely clear (so it can NOT include builtin). This one can be
933 # we can safely clear (so it can NOT include builtin). This one can be
934 # a simple list. Note that the main execution namespaces, user_ns and
934 # a simple list. Note that the main execution namespaces, user_ns and
935 # user_global_ns, can NOT be listed here, as clearing them blindly
935 # user_global_ns, can NOT be listed here, as clearing them blindly
936 # causes errors in object __del__ methods. Instead, the reset() method
936 # causes errors in object __del__ methods. Instead, the reset() method
937 # clears them manually and carefully.
937 # clears them manually and carefully.
938 self.ns_refs_table = [ self.user_ns_hidden,
938 self.ns_refs_table = [ self.user_ns_hidden,
939 self.internal_ns, self._main_ns_cache ]
939 self.internal_ns, self._main_ns_cache ]
940
940
941 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
941 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
942 """Return a valid local and global user interactive namespaces.
942 """Return a valid local and global user interactive namespaces.
943
943
944 This builds a dict with the minimal information needed to operate as a
944 This builds a dict with the minimal information needed to operate as a
945 valid IPython user namespace, which you can pass to the various
945 valid IPython user namespace, which you can pass to the various
946 embedding classes in ipython. The default implementation returns the
946 embedding classes in ipython. The default implementation returns the
947 same dict for both the locals and the globals to allow functions to
947 same dict for both the locals and the globals to allow functions to
948 refer to variables in the namespace. Customized implementations can
948 refer to variables in the namespace. Customized implementations can
949 return different dicts. The locals dictionary can actually be anything
949 return different dicts. The locals dictionary can actually be anything
950 following the basic mapping protocol of a dict, but the globals dict
950 following the basic mapping protocol of a dict, but the globals dict
951 must be a true dict, not even a subclass. It is recommended that any
951 must be a true dict, not even a subclass. It is recommended that any
952 custom object for the locals namespace synchronize with the globals
952 custom object for the locals namespace synchronize with the globals
953 dict somehow.
953 dict somehow.
954
954
955 Raises TypeError if the provided globals namespace is not a true dict.
955 Raises TypeError if the provided globals namespace is not a true dict.
956
956
957 Parameters
957 Parameters
958 ----------
958 ----------
959 user_ns : dict-like, optional
959 user_ns : dict-like, optional
960 The current user namespace. The items in this namespace should
960 The current user namespace. The items in this namespace should
961 be included in the output. If None, an appropriate blank
961 be included in the output. If None, an appropriate blank
962 namespace should be created.
962 namespace should be created.
963 user_global_ns : dict, optional
963 user_global_ns : dict, optional
964 The current user global namespace. The items in this namespace
964 The current user global namespace. The items in this namespace
965 should be included in the output. If None, an appropriate
965 should be included in the output. If None, an appropriate
966 blank namespace should be created.
966 blank namespace should be created.
967
967
968 Returns
968 Returns
969 -------
969 -------
970 A pair of dictionary-like object to be used as the local namespace
970 A pair of dictionary-like object to be used as the local namespace
971 of the interpreter and a dict to be used as the global namespace.
971 of the interpreter and a dict to be used as the global namespace.
972 """
972 """
973
973
974
974
975 # We must ensure that __builtin__ (without the final 's') is always
975 # We must ensure that __builtin__ (without the final 's') is always
976 # available and pointing to the __builtin__ *module*. For more details:
976 # available and pointing to the __builtin__ *module*. For more details:
977 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
977 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
978
978
979 if user_ns is None:
979 if user_ns is None:
980 # Set __name__ to __main__ to better match the behavior of the
980 # Set __name__ to __main__ to better match the behavior of the
981 # normal interpreter.
981 # normal interpreter.
982 user_ns = {'__name__' :'__main__',
982 user_ns = {'__name__' :'__main__',
983 py3compat.builtin_mod_name: builtin_mod,
983 py3compat.builtin_mod_name: builtin_mod,
984 '__builtins__' : builtin_mod,
984 '__builtins__' : builtin_mod,
985 }
985 }
986 else:
986 else:
987 user_ns.setdefault('__name__','__main__')
987 user_ns.setdefault('__name__','__main__')
988 user_ns.setdefault(py3compat.builtin_mod_name,builtin_mod)
988 user_ns.setdefault(py3compat.builtin_mod_name,builtin_mod)
989 user_ns.setdefault('__builtins__',builtin_mod)
989 user_ns.setdefault('__builtins__',builtin_mod)
990
990
991 if user_global_ns is None:
991 if user_global_ns is None:
992 user_global_ns = user_ns
992 user_global_ns = user_ns
993 if type(user_global_ns) is not dict:
993 if type(user_global_ns) is not dict:
994 raise TypeError("user_global_ns must be a true dict; got %r"
994 raise TypeError("user_global_ns must be a true dict; got %r"
995 % type(user_global_ns))
995 % type(user_global_ns))
996
996
997 return user_ns, user_global_ns
997 return user_ns, user_global_ns
998
998
999 def init_sys_modules(self):
999 def init_sys_modules(self):
1000 # We need to insert into sys.modules something that looks like a
1000 # We need to insert into sys.modules something that looks like a
1001 # module but which accesses the IPython namespace, for shelve and
1001 # module but which accesses the IPython namespace, for shelve and
1002 # pickle to work interactively. Normally they rely on getting
1002 # pickle to work interactively. Normally they rely on getting
1003 # everything out of __main__, but for embedding purposes each IPython
1003 # everything out of __main__, but for embedding purposes each IPython
1004 # instance has its own private namespace, so we can't go shoving
1004 # instance has its own private namespace, so we can't go shoving
1005 # everything into __main__.
1005 # everything into __main__.
1006
1006
1007 # note, however, that we should only do this for non-embedded
1007 # note, however, that we should only do this for non-embedded
1008 # ipythons, which really mimic the __main__.__dict__ with their own
1008 # ipythons, which really mimic the __main__.__dict__ with their own
1009 # namespace. Embedded instances, on the other hand, should not do
1009 # namespace. Embedded instances, on the other hand, should not do
1010 # this because they need to manage the user local/global namespaces
1010 # this because they need to manage the user local/global namespaces
1011 # only, but they live within a 'normal' __main__ (meaning, they
1011 # only, but they live within a 'normal' __main__ (meaning, they
1012 # shouldn't overtake the execution environment of the script they're
1012 # shouldn't overtake the execution environment of the script they're
1013 # embedded in).
1013 # embedded in).
1014
1014
1015 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1015 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
1016
1016
1017 try:
1017 try:
1018 main_name = self.user_ns['__name__']
1018 main_name = self.user_ns['__name__']
1019 except KeyError:
1019 except KeyError:
1020 raise KeyError('user_ns dictionary MUST have a "__name__" key')
1020 raise KeyError('user_ns dictionary MUST have a "__name__" key')
1021 else:
1021 else:
1022 sys.modules[main_name] = FakeModule(self.user_ns)
1022 sys.modules[main_name] = FakeModule(self.user_ns)
1023
1023
1024 def init_user_ns(self):
1024 def init_user_ns(self):
1025 """Initialize all user-visible namespaces to their minimum defaults.
1025 """Initialize all user-visible namespaces to their minimum defaults.
1026
1026
1027 Certain history lists are also initialized here, as they effectively
1027 Certain history lists are also initialized here, as they effectively
1028 act as user namespaces.
1028 act as user namespaces.
1029
1029
1030 Notes
1030 Notes
1031 -----
1031 -----
1032 All data structures here are only filled in, they are NOT reset by this
1032 All data structures here are only filled in, they are NOT reset by this
1033 method. If they were not empty before, data will simply be added to
1033 method. If they were not empty before, data will simply be added to
1034 therm.
1034 therm.
1035 """
1035 """
1036 # This function works in two parts: first we put a few things in
1036 # This function works in two parts: first we put a few things in
1037 # user_ns, and we sync that contents into user_ns_hidden so that these
1037 # user_ns, and we sync that contents into user_ns_hidden so that these
1038 # initial variables aren't shown by %who. After the sync, we add the
1038 # initial variables aren't shown by %who. After the sync, we add the
1039 # rest of what we *do* want the user to see with %who even on a new
1039 # rest of what we *do* want the user to see with %who even on a new
1040 # session (probably nothing, so theye really only see their own stuff)
1040 # session (probably nothing, so theye really only see their own stuff)
1041
1041
1042 # The user dict must *always* have a __builtin__ reference to the
1042 # The user dict must *always* have a __builtin__ reference to the
1043 # Python standard __builtin__ namespace, which must be imported.
1043 # Python standard __builtin__ namespace, which must be imported.
1044 # This is so that certain operations in prompt evaluation can be
1044 # This is so that certain operations in prompt evaluation can be
1045 # reliably executed with builtins. Note that we can NOT use
1045 # reliably executed with builtins. Note that we can NOT use
1046 # __builtins__ (note the 's'), because that can either be a dict or a
1046 # __builtins__ (note the 's'), because that can either be a dict or a
1047 # module, and can even mutate at runtime, depending on the context
1047 # module, and can even mutate at runtime, depending on the context
1048 # (Python makes no guarantees on it). In contrast, __builtin__ is
1048 # (Python makes no guarantees on it). In contrast, __builtin__ is
1049 # always a module object, though it must be explicitly imported.
1049 # always a module object, though it must be explicitly imported.
1050
1050
1051 # For more details:
1051 # For more details:
1052 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1052 # http://mail.python.org/pipermail/python-dev/2001-April/014068.html
1053 ns = dict(__builtin__ = builtin_mod)
1053 ns = dict(__builtin__ = builtin_mod)
1054
1054
1055 # Put 'help' in the user namespace
1055 # Put 'help' in the user namespace
1056 try:
1056 try:
1057 from site import _Helper
1057 from site import _Helper
1058 ns['help'] = _Helper()
1058 ns['help'] = _Helper()
1059 except ImportError:
1059 except ImportError:
1060 warn('help() not available - check site.py')
1060 warn('help() not available - check site.py')
1061
1061
1062 # make global variables for user access to the histories
1062 # make global variables for user access to the histories
1063 ns['_ih'] = self.history_manager.input_hist_parsed
1063 ns['_ih'] = self.history_manager.input_hist_parsed
1064 ns['_oh'] = self.history_manager.output_hist
1064 ns['_oh'] = self.history_manager.output_hist
1065 ns['_dh'] = self.history_manager.dir_hist
1065 ns['_dh'] = self.history_manager.dir_hist
1066
1066
1067 ns['_sh'] = shadowns
1067 ns['_sh'] = shadowns
1068
1068
1069 # user aliases to input and output histories. These shouldn't show up
1069 # user aliases to input and output histories. These shouldn't show up
1070 # in %who, as they can have very large reprs.
1070 # in %who, as they can have very large reprs.
1071 ns['In'] = self.history_manager.input_hist_parsed
1071 ns['In'] = self.history_manager.input_hist_parsed
1072 ns['Out'] = self.history_manager.output_hist
1072 ns['Out'] = self.history_manager.output_hist
1073
1073
1074 # Store myself as the public api!!!
1074 # Store myself as the public api!!!
1075 ns['get_ipython'] = self.get_ipython
1075 ns['get_ipython'] = self.get_ipython
1076
1076
1077 ns['exit'] = self.exiter
1077 ns['exit'] = self.exiter
1078 ns['quit'] = self.exiter
1078 ns['quit'] = self.exiter
1079
1079
1080 # Sync what we've added so far to user_ns_hidden so these aren't seen
1080 # Sync what we've added so far to user_ns_hidden so these aren't seen
1081 # by %who
1081 # by %who
1082 self.user_ns_hidden.update(ns)
1082 self.user_ns_hidden.update(ns)
1083
1083
1084 # Anything put into ns now would show up in %who. Think twice before
1084 # Anything put into ns now would show up in %who. Think twice before
1085 # putting anything here, as we really want %who to show the user their
1085 # putting anything here, as we really want %who to show the user their
1086 # stuff, not our variables.
1086 # stuff, not our variables.
1087
1087
1088 # Finally, update the real user's namespace
1088 # Finally, update the real user's namespace
1089 self.user_ns.update(ns)
1089 self.user_ns.update(ns)
1090
1090
1091 def reset(self, new_session=True):
1091 def reset(self, new_session=True):
1092 """Clear all internal namespaces, and attempt to release references to
1092 """Clear all internal namespaces, and attempt to release references to
1093 user objects.
1093 user objects.
1094
1094
1095 If new_session is True, a new history session will be opened.
1095 If new_session is True, a new history session will be opened.
1096 """
1096 """
1097 # Clear histories
1097 # Clear histories
1098 self.history_manager.reset(new_session)
1098 self.history_manager.reset(new_session)
1099 # Reset counter used to index all histories
1099 # Reset counter used to index all histories
1100 if new_session:
1100 if new_session:
1101 self.execution_count = 1
1101 self.execution_count = 1
1102
1102
1103 # Flush cached output items
1103 # Flush cached output items
1104 if self.displayhook.do_full_cache:
1104 if self.displayhook.do_full_cache:
1105 self.displayhook.flush()
1105 self.displayhook.flush()
1106
1106
1107 # Restore the user namespaces to minimal usability
1107 # Restore the user namespaces to minimal usability
1108 for ns in self.ns_refs_table:
1108 for ns in self.ns_refs_table:
1109 ns.clear()
1109 ns.clear()
1110
1110
1111 # The main execution namespaces must be cleared very carefully,
1111 # The main execution namespaces must be cleared very carefully,
1112 # skipping the deletion of the builtin-related keys, because doing so
1112 # skipping the deletion of the builtin-related keys, because doing so
1113 # would cause errors in many object's __del__ methods.
1113 # would cause errors in many object's __del__ methods.
1114 for ns in [self.user_ns, self.user_global_ns]:
1114 for ns in [self.user_ns, self.user_global_ns]:
1115 drop_keys = set(ns.keys())
1115 drop_keys = set(ns.keys())
1116 drop_keys.discard('__builtin__')
1116 drop_keys.discard('__builtin__')
1117 drop_keys.discard('__builtins__')
1117 drop_keys.discard('__builtins__')
1118 for k in drop_keys:
1118 for k in drop_keys:
1119 del ns[k]
1119 del ns[k]
1120
1120
1121 # Restore the user namespaces to minimal usability
1121 # Restore the user namespaces to minimal usability
1122 self.init_user_ns()
1122 self.init_user_ns()
1123
1123
1124 # Restore the default and user aliases
1124 # Restore the default and user aliases
1125 self.alias_manager.clear_aliases()
1125 self.alias_manager.clear_aliases()
1126 self.alias_manager.init_aliases()
1126 self.alias_manager.init_aliases()
1127
1127
1128 # Flush the private list of module references kept for script
1128 # Flush the private list of module references kept for script
1129 # execution protection
1129 # execution protection
1130 self.clear_main_mod_cache()
1130 self.clear_main_mod_cache()
1131
1131
1132 # Clear out the namespace from the last %run
1132 # Clear out the namespace from the last %run
1133 self.new_main_mod()
1133 self.new_main_mod()
1134
1134
1135 def del_var(self, varname, by_name=False):
1135 def del_var(self, varname, by_name=False):
1136 """Delete a variable from the various namespaces, so that, as
1136 """Delete a variable from the various namespaces, so that, as
1137 far as possible, we're not keeping any hidden references to it.
1137 far as possible, we're not keeping any hidden references to it.
1138
1138
1139 Parameters
1139 Parameters
1140 ----------
1140 ----------
1141 varname : str
1141 varname : str
1142 The name of the variable to delete.
1142 The name of the variable to delete.
1143 by_name : bool
1143 by_name : bool
1144 If True, delete variables with the given name in each
1144 If True, delete variables with the given name in each
1145 namespace. If False (default), find the variable in the user
1145 namespace. If False (default), find the variable in the user
1146 namespace, and delete references to it.
1146 namespace, and delete references to it.
1147 """
1147 """
1148 if varname in ('__builtin__', '__builtins__'):
1148 if varname in ('__builtin__', '__builtins__'):
1149 raise ValueError("Refusing to delete %s" % varname)
1149 raise ValueError("Refusing to delete %s" % varname)
1150 ns_refs = self.ns_refs_table + [self.user_ns,
1150 ns_refs = self.ns_refs_table + [self.user_ns,
1151 self.user_global_ns, self._user_main_module.__dict__] +\
1151 self.user_global_ns, self._user_main_module.__dict__] +\
1152 self._main_ns_cache.values()
1152 self._main_ns_cache.values()
1153
1153
1154 if by_name: # Delete by name
1154 if by_name: # Delete by name
1155 for ns in ns_refs:
1155 for ns in ns_refs:
1156 try:
1156 try:
1157 del ns[varname]
1157 del ns[varname]
1158 except KeyError:
1158 except KeyError:
1159 pass
1159 pass
1160 else: # Delete by object
1160 else: # Delete by object
1161 try:
1161 try:
1162 obj = self.user_ns[varname]
1162 obj = self.user_ns[varname]
1163 except KeyError:
1163 except KeyError:
1164 raise NameError("name '%s' is not defined" % varname)
1164 raise NameError("name '%s' is not defined" % varname)
1165 # Also check in output history
1165 # Also check in output history
1166 ns_refs.append(self.history_manager.output_hist)
1166 ns_refs.append(self.history_manager.output_hist)
1167 for ns in ns_refs:
1167 for ns in ns_refs:
1168 to_delete = [n for n, o in ns.iteritems() if o is obj]
1168 to_delete = [n for n, o in ns.iteritems() if o is obj]
1169 for name in to_delete:
1169 for name in to_delete:
1170 del ns[name]
1170 del ns[name]
1171
1171
1172 # displayhook keeps extra references, but not in a dictionary
1172 # displayhook keeps extra references, but not in a dictionary
1173 for name in ('_', '__', '___'):
1173 for name in ('_', '__', '___'):
1174 if getattr(self.displayhook, name) is obj:
1174 if getattr(self.displayhook, name) is obj:
1175 setattr(self.displayhook, name, None)
1175 setattr(self.displayhook, name, None)
1176
1176
1177 def reset_selective(self, regex=None):
1177 def reset_selective(self, regex=None):
1178 """Clear selective variables from internal namespaces based on a
1178 """Clear selective variables from internal namespaces based on a
1179 specified regular expression.
1179 specified regular expression.
1180
1180
1181 Parameters
1181 Parameters
1182 ----------
1182 ----------
1183 regex : string or compiled pattern, optional
1183 regex : string or compiled pattern, optional
1184 A regular expression pattern that will be used in searching
1184 A regular expression pattern that will be used in searching
1185 variable names in the users namespaces.
1185 variable names in the users namespaces.
1186 """
1186 """
1187 if regex is not None:
1187 if regex is not None:
1188 try:
1188 try:
1189 m = re.compile(regex)
1189 m = re.compile(regex)
1190 except TypeError:
1190 except TypeError:
1191 raise TypeError('regex must be a string or compiled pattern')
1191 raise TypeError('regex must be a string or compiled pattern')
1192 # Search for keys in each namespace that match the given regex
1192 # Search for keys in each namespace that match the given regex
1193 # If a match is found, delete the key/value pair.
1193 # If a match is found, delete the key/value pair.
1194 for ns in self.ns_refs_table:
1194 for ns in self.ns_refs_table:
1195 for var in ns:
1195 for var in ns:
1196 if m.search(var):
1196 if m.search(var):
1197 del ns[var]
1197 del ns[var]
1198
1198
1199 def push(self, variables, interactive=True):
1199 def push(self, variables, interactive=True):
1200 """Inject a group of variables into the IPython user namespace.
1200 """Inject a group of variables into the IPython user namespace.
1201
1201
1202 Parameters
1202 Parameters
1203 ----------
1203 ----------
1204 variables : dict, str or list/tuple of str
1204 variables : dict, str or list/tuple of str
1205 The variables to inject into the user's namespace. If a dict, a
1205 The variables to inject into the user's namespace. If a dict, a
1206 simple update is done. If a str, the string is assumed to have
1206 simple update is done. If a str, the string is assumed to have
1207 variable names separated by spaces. A list/tuple of str can also
1207 variable names separated by spaces. A list/tuple of str can also
1208 be used to give the variable names. If just the variable names are
1208 be used to give the variable names. If just the variable names are
1209 give (list/tuple/str) then the variable values looked up in the
1209 give (list/tuple/str) then the variable values looked up in the
1210 callers frame.
1210 callers frame.
1211 interactive : bool
1211 interactive : bool
1212 If True (default), the variables will be listed with the ``who``
1212 If True (default), the variables will be listed with the ``who``
1213 magic.
1213 magic.
1214 """
1214 """
1215 vdict = None
1215 vdict = None
1216
1216
1217 # We need a dict of name/value pairs to do namespace updates.
1217 # We need a dict of name/value pairs to do namespace updates.
1218 if isinstance(variables, dict):
1218 if isinstance(variables, dict):
1219 vdict = variables
1219 vdict = variables
1220 elif isinstance(variables, (basestring, list, tuple)):
1220 elif isinstance(variables, (basestring, list, tuple)):
1221 if isinstance(variables, basestring):
1221 if isinstance(variables, basestring):
1222 vlist = variables.split()
1222 vlist = variables.split()
1223 else:
1223 else:
1224 vlist = variables
1224 vlist = variables
1225 vdict = {}
1225 vdict = {}
1226 cf = sys._getframe(1)
1226 cf = sys._getframe(1)
1227 for name in vlist:
1227 for name in vlist:
1228 try:
1228 try:
1229 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1229 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1230 except:
1230 except:
1231 print ('Could not get variable %s from %s' %
1231 print ('Could not get variable %s from %s' %
1232 (name,cf.f_code.co_name))
1232 (name,cf.f_code.co_name))
1233 else:
1233 else:
1234 raise ValueError('variables must be a dict/str/list/tuple')
1234 raise ValueError('variables must be a dict/str/list/tuple')
1235
1235
1236 # Propagate variables to user namespace
1236 # Propagate variables to user namespace
1237 self.user_ns.update(vdict)
1237 self.user_ns.update(vdict)
1238
1238
1239 # And configure interactive visibility
1239 # And configure interactive visibility
1240 config_ns = self.user_ns_hidden
1240 config_ns = self.user_ns_hidden
1241 if interactive:
1241 if interactive:
1242 for name, val in vdict.iteritems():
1242 for name, val in vdict.iteritems():
1243 config_ns.pop(name, None)
1243 config_ns.pop(name, None)
1244 else:
1244 else:
1245 for name,val in vdict.iteritems():
1245 for name,val in vdict.iteritems():
1246 config_ns[name] = val
1246 config_ns[name] = val
1247
1247
1248 #-------------------------------------------------------------------------
1248 #-------------------------------------------------------------------------
1249 # Things related to object introspection
1249 # Things related to object introspection
1250 #-------------------------------------------------------------------------
1250 #-------------------------------------------------------------------------
1251
1251
1252 def _ofind(self, oname, namespaces=None):
1252 def _ofind(self, oname, namespaces=None):
1253 """Find an object in the available namespaces.
1253 """Find an object in the available namespaces.
1254
1254
1255 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1255 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
1256
1256
1257 Has special code to detect magic functions.
1257 Has special code to detect magic functions.
1258 """
1258 """
1259 oname = oname.strip()
1259 oname = oname.strip()
1260 #print '1- oname: <%r>' % oname # dbg
1260 #print '1- oname: <%r>' % oname # dbg
1261 if not py3compat.PY3:
1261 if not py3compat.isidentifier(oname.lstrip(ESC_MAGIC), dotted=True):
1262 try:
1263 oname = oname.encode('ascii')
1264 #print '2- oname: <%r>' % oname # dbg
1265 except UnicodeError:
1266 print 'Python identifiers can only contain ascii characters.'
1262 print 'Python identifiers can only contain ascii characters.'
1267 return dict(found=False)
1263 return dict(found=False)
1268
1264
1269 alias_ns = None
1265 alias_ns = None
1270 if namespaces is None:
1266 if namespaces is None:
1271 # Namespaces to search in:
1267 # Namespaces to search in:
1272 # Put them in a list. The order is important so that we
1268 # Put them in a list. The order is important so that we
1273 # find things in the same order that Python finds them.
1269 # find things in the same order that Python finds them.
1274 namespaces = [ ('Interactive', self.user_ns),
1270 namespaces = [ ('Interactive', self.user_ns),
1275 ('IPython internal', self.internal_ns),
1271 ('IPython internal', self.internal_ns),
1276 ('Python builtin', builtin_mod.__dict__),
1272 ('Python builtin', builtin_mod.__dict__),
1277 ('Alias', self.alias_manager.alias_table),
1273 ('Alias', self.alias_manager.alias_table),
1278 ]
1274 ]
1279 alias_ns = self.alias_manager.alias_table
1275 alias_ns = self.alias_manager.alias_table
1280
1276
1281 # initialize results to 'null'
1277 # initialize results to 'null'
1282 found = False; obj = None; ospace = None; ds = None;
1278 found = False; obj = None; ospace = None; ds = None;
1283 ismagic = False; isalias = False; parent = None
1279 ismagic = False; isalias = False; parent = None
1284
1280
1285 # We need to special-case 'print', which as of python2.6 registers as a
1281 # We need to special-case 'print', which as of python2.6 registers as a
1286 # function but should only be treated as one if print_function was
1282 # function but should only be treated as one if print_function was
1287 # loaded with a future import. In this case, just bail.
1283 # loaded with a future import. In this case, just bail.
1288 if (oname == 'print' and not (self.compile.compiler_flags &
1284 if (oname == 'print' and not (self.compile.compiler_flags &
1289 __future__.CO_FUTURE_PRINT_FUNCTION)):
1285 __future__.CO_FUTURE_PRINT_FUNCTION)):
1290 return {'found':found, 'obj':obj, 'namespace':ospace,
1286 return {'found':found, 'obj':obj, 'namespace':ospace,
1291 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1287 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1292
1288
1293 # Look for the given name by splitting it in parts. If the head is
1289 # Look for the given name by splitting it in parts. If the head is
1294 # found, then we look for all the remaining parts as members, and only
1290 # found, then we look for all the remaining parts as members, and only
1295 # declare success if we can find them all.
1291 # declare success if we can find them all.
1296 oname_parts = oname.split('.')
1292 oname_parts = oname.split('.')
1297 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1293 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
1298 for nsname,ns in namespaces:
1294 for nsname,ns in namespaces:
1299 try:
1295 try:
1300 obj = ns[oname_head]
1296 obj = ns[oname_head]
1301 except KeyError:
1297 except KeyError:
1302 continue
1298 continue
1303 else:
1299 else:
1304 #print 'oname_rest:', oname_rest # dbg
1300 #print 'oname_rest:', oname_rest # dbg
1305 for part in oname_rest:
1301 for part in oname_rest:
1306 try:
1302 try:
1307 parent = obj
1303 parent = obj
1308 obj = getattr(obj,part)
1304 obj = getattr(obj,part)
1309 except:
1305 except:
1310 # Blanket except b/c some badly implemented objects
1306 # Blanket except b/c some badly implemented objects
1311 # allow __getattr__ to raise exceptions other than
1307 # allow __getattr__ to raise exceptions other than
1312 # AttributeError, which then crashes IPython.
1308 # AttributeError, which then crashes IPython.
1313 break
1309 break
1314 else:
1310 else:
1315 # If we finish the for loop (no break), we got all members
1311 # If we finish the for loop (no break), we got all members
1316 found = True
1312 found = True
1317 ospace = nsname
1313 ospace = nsname
1318 if ns == alias_ns:
1314 if ns == alias_ns:
1319 isalias = True
1315 isalias = True
1320 break # namespace loop
1316 break # namespace loop
1321
1317
1322 # Try to see if it's magic
1318 # Try to see if it's magic
1323 if not found:
1319 if not found:
1324 if oname.startswith(ESC_MAGIC):
1320 if oname.startswith(ESC_MAGIC):
1325 oname = oname[1:]
1321 oname = oname[1:]
1326 obj = getattr(self,'magic_'+oname,None)
1322 obj = getattr(self,'magic_'+oname,None)
1327 if obj is not None:
1323 if obj is not None:
1328 found = True
1324 found = True
1329 ospace = 'IPython internal'
1325 ospace = 'IPython internal'
1330 ismagic = True
1326 ismagic = True
1331
1327
1332 # Last try: special-case some literals like '', [], {}, etc:
1328 # Last try: special-case some literals like '', [], {}, etc:
1333 if not found and oname_head in ["''",'""','[]','{}','()']:
1329 if not found and oname_head in ["''",'""','[]','{}','()']:
1334 obj = eval(oname_head)
1330 obj = eval(oname_head)
1335 found = True
1331 found = True
1336 ospace = 'Interactive'
1332 ospace = 'Interactive'
1337
1333
1338 return {'found':found, 'obj':obj, 'namespace':ospace,
1334 return {'found':found, 'obj':obj, 'namespace':ospace,
1339 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1335 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
1340
1336
1341 def _ofind_property(self, oname, info):
1337 def _ofind_property(self, oname, info):
1342 """Second part of object finding, to look for property details."""
1338 """Second part of object finding, to look for property details."""
1343 if info.found:
1339 if info.found:
1344 # Get the docstring of the class property if it exists.
1340 # Get the docstring of the class property if it exists.
1345 path = oname.split('.')
1341 path = oname.split('.')
1346 root = '.'.join(path[:-1])
1342 root = '.'.join(path[:-1])
1347 if info.parent is not None:
1343 if info.parent is not None:
1348 try:
1344 try:
1349 target = getattr(info.parent, '__class__')
1345 target = getattr(info.parent, '__class__')
1350 # The object belongs to a class instance.
1346 # The object belongs to a class instance.
1351 try:
1347 try:
1352 target = getattr(target, path[-1])
1348 target = getattr(target, path[-1])
1353 # The class defines the object.
1349 # The class defines the object.
1354 if isinstance(target, property):
1350 if isinstance(target, property):
1355 oname = root + '.__class__.' + path[-1]
1351 oname = root + '.__class__.' + path[-1]
1356 info = Struct(self._ofind(oname))
1352 info = Struct(self._ofind(oname))
1357 except AttributeError: pass
1353 except AttributeError: pass
1358 except AttributeError: pass
1354 except AttributeError: pass
1359
1355
1360 # We return either the new info or the unmodified input if the object
1356 # We return either the new info or the unmodified input if the object
1361 # hadn't been found
1357 # hadn't been found
1362 return info
1358 return info
1363
1359
1364 def _object_find(self, oname, namespaces=None):
1360 def _object_find(self, oname, namespaces=None):
1365 """Find an object and return a struct with info about it."""
1361 """Find an object and return a struct with info about it."""
1366 inf = Struct(self._ofind(oname, namespaces))
1362 inf = Struct(self._ofind(oname, namespaces))
1367 return Struct(self._ofind_property(oname, inf))
1363 return Struct(self._ofind_property(oname, inf))
1368
1364
1369 def _inspect(self, meth, oname, namespaces=None, **kw):
1365 def _inspect(self, meth, oname, namespaces=None, **kw):
1370 """Generic interface to the inspector system.
1366 """Generic interface to the inspector system.
1371
1367
1372 This function is meant to be called by pdef, pdoc & friends."""
1368 This function is meant to be called by pdef, pdoc & friends."""
1373 info = self._object_find(oname)
1369 info = self._object_find(oname)
1374 if info.found:
1370 if info.found:
1375 pmethod = getattr(self.inspector, meth)
1371 pmethod = getattr(self.inspector, meth)
1376 formatter = format_screen if info.ismagic else None
1372 formatter = format_screen if info.ismagic else None
1377 if meth == 'pdoc':
1373 if meth == 'pdoc':
1378 pmethod(info.obj, oname, formatter)
1374 pmethod(info.obj, oname, formatter)
1379 elif meth == 'pinfo':
1375 elif meth == 'pinfo':
1380 pmethod(info.obj, oname, formatter, info, **kw)
1376 pmethod(info.obj, oname, formatter, info, **kw)
1381 else:
1377 else:
1382 pmethod(info.obj, oname)
1378 pmethod(info.obj, oname)
1383 else:
1379 else:
1384 print 'Object `%s` not found.' % oname
1380 print 'Object `%s` not found.' % oname
1385 return 'not found' # so callers can take other action
1381 return 'not found' # so callers can take other action
1386
1382
1387 def object_inspect(self, oname):
1383 def object_inspect(self, oname):
1388 with self.builtin_trap:
1384 with self.builtin_trap:
1389 info = self._object_find(oname)
1385 info = self._object_find(oname)
1390 if info.found:
1386 if info.found:
1391 return self.inspector.info(info.obj, oname, info=info)
1387 return self.inspector.info(info.obj, oname, info=info)
1392 else:
1388 else:
1393 return oinspect.object_info(name=oname, found=False)
1389 return oinspect.object_info(name=oname, found=False)
1394
1390
1395 #-------------------------------------------------------------------------
1391 #-------------------------------------------------------------------------
1396 # Things related to history management
1392 # Things related to history management
1397 #-------------------------------------------------------------------------
1393 #-------------------------------------------------------------------------
1398
1394
1399 def init_history(self):
1395 def init_history(self):
1400 """Sets up the command history, and starts regular autosaves."""
1396 """Sets up the command history, and starts regular autosaves."""
1401 self.history_manager = HistoryManager(shell=self, config=self.config)
1397 self.history_manager = HistoryManager(shell=self, config=self.config)
1402
1398
1403 #-------------------------------------------------------------------------
1399 #-------------------------------------------------------------------------
1404 # Things related to exception handling and tracebacks (not debugging)
1400 # Things related to exception handling and tracebacks (not debugging)
1405 #-------------------------------------------------------------------------
1401 #-------------------------------------------------------------------------
1406
1402
1407 def init_traceback_handlers(self, custom_exceptions):
1403 def init_traceback_handlers(self, custom_exceptions):
1408 # Syntax error handler.
1404 # Syntax error handler.
1409 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1405 self.SyntaxTB = ultratb.SyntaxTB(color_scheme='NoColor')
1410
1406
1411 # The interactive one is initialized with an offset, meaning we always
1407 # The interactive one is initialized with an offset, meaning we always
1412 # want to remove the topmost item in the traceback, which is our own
1408 # want to remove the topmost item in the traceback, which is our own
1413 # internal code. Valid modes: ['Plain','Context','Verbose']
1409 # internal code. Valid modes: ['Plain','Context','Verbose']
1414 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1410 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1415 color_scheme='NoColor',
1411 color_scheme='NoColor',
1416 tb_offset = 1,
1412 tb_offset = 1,
1417 check_cache=self.compile.check_cache)
1413 check_cache=self.compile.check_cache)
1418
1414
1419 # The instance will store a pointer to the system-wide exception hook,
1415 # The instance will store a pointer to the system-wide exception hook,
1420 # so that runtime code (such as magics) can access it. This is because
1416 # so that runtime code (such as magics) can access it. This is because
1421 # during the read-eval loop, it may get temporarily overwritten.
1417 # during the read-eval loop, it may get temporarily overwritten.
1422 self.sys_excepthook = sys.excepthook
1418 self.sys_excepthook = sys.excepthook
1423
1419
1424 # and add any custom exception handlers the user may have specified
1420 # and add any custom exception handlers the user may have specified
1425 self.set_custom_exc(*custom_exceptions)
1421 self.set_custom_exc(*custom_exceptions)
1426
1422
1427 # Set the exception mode
1423 # Set the exception mode
1428 self.InteractiveTB.set_mode(mode=self.xmode)
1424 self.InteractiveTB.set_mode(mode=self.xmode)
1429
1425
1430 def set_custom_exc(self, exc_tuple, handler):
1426 def set_custom_exc(self, exc_tuple, handler):
1431 """set_custom_exc(exc_tuple,handler)
1427 """set_custom_exc(exc_tuple,handler)
1432
1428
1433 Set a custom exception handler, which will be called if any of the
1429 Set a custom exception handler, which will be called if any of the
1434 exceptions in exc_tuple occur in the mainloop (specifically, in the
1430 exceptions in exc_tuple occur in the mainloop (specifically, in the
1435 run_code() method.
1431 run_code() method.
1436
1432
1437 Inputs:
1433 Inputs:
1438
1434
1439 - exc_tuple: a *tuple* of valid exceptions to call the defined
1435 - exc_tuple: a *tuple* of valid exceptions to call the defined
1440 handler for. It is very important that you use a tuple, and NOT A
1436 handler for. It is very important that you use a tuple, and NOT A
1441 LIST here, because of the way Python's except statement works. If
1437 LIST here, because of the way Python's except statement works. If
1442 you only want to trap a single exception, use a singleton tuple:
1438 you only want to trap a single exception, use a singleton tuple:
1443
1439
1444 exc_tuple == (MyCustomException,)
1440 exc_tuple == (MyCustomException,)
1445
1441
1446 - handler: this must be defined as a function with the following
1442 - handler: this must be defined as a function with the following
1447 basic interface::
1443 basic interface::
1448
1444
1449 def my_handler(self, etype, value, tb, tb_offset=None)
1445 def my_handler(self, etype, value, tb, tb_offset=None)
1450 ...
1446 ...
1451 # The return value must be
1447 # The return value must be
1452 return structured_traceback
1448 return structured_traceback
1453
1449
1454 This will be made into an instance method (via types.MethodType)
1450 This will be made into an instance method (via types.MethodType)
1455 of IPython itself, and it will be called if any of the exceptions
1451 of IPython itself, and it will be called if any of the exceptions
1456 listed in the exc_tuple are caught. If the handler is None, an
1452 listed in the exc_tuple are caught. If the handler is None, an
1457 internal basic one is used, which just prints basic info.
1453 internal basic one is used, which just prints basic info.
1458
1454
1459 WARNING: by putting in your own exception handler into IPython's main
1455 WARNING: by putting in your own exception handler into IPython's main
1460 execution loop, you run a very good chance of nasty crashes. This
1456 execution loop, you run a very good chance of nasty crashes. This
1461 facility should only be used if you really know what you are doing."""
1457 facility should only be used if you really know what you are doing."""
1462
1458
1463 assert type(exc_tuple)==type(()) , \
1459 assert type(exc_tuple)==type(()) , \
1464 "The custom exceptions must be given AS A TUPLE."
1460 "The custom exceptions must be given AS A TUPLE."
1465
1461
1466 def dummy_handler(self,etype,value,tb):
1462 def dummy_handler(self,etype,value,tb):
1467 print '*** Simple custom exception handler ***'
1463 print '*** Simple custom exception handler ***'
1468 print 'Exception type :',etype
1464 print 'Exception type :',etype
1469 print 'Exception value:',value
1465 print 'Exception value:',value
1470 print 'Traceback :',tb
1466 print 'Traceback :',tb
1471 #print 'Source code :','\n'.join(self.buffer)
1467 #print 'Source code :','\n'.join(self.buffer)
1472
1468
1473 if handler is None: handler = dummy_handler
1469 if handler is None: handler = dummy_handler
1474
1470
1475 self.CustomTB = types.MethodType(handler,self)
1471 self.CustomTB = types.MethodType(handler,self)
1476 self.custom_exceptions = exc_tuple
1472 self.custom_exceptions = exc_tuple
1477
1473
1478 def excepthook(self, etype, value, tb):
1474 def excepthook(self, etype, value, tb):
1479 """One more defense for GUI apps that call sys.excepthook.
1475 """One more defense for GUI apps that call sys.excepthook.
1480
1476
1481 GUI frameworks like wxPython trap exceptions and call
1477 GUI frameworks like wxPython trap exceptions and call
1482 sys.excepthook themselves. I guess this is a feature that
1478 sys.excepthook themselves. I guess this is a feature that
1483 enables them to keep running after exceptions that would
1479 enables them to keep running after exceptions that would
1484 otherwise kill their mainloop. This is a bother for IPython
1480 otherwise kill their mainloop. This is a bother for IPython
1485 which excepts to catch all of the program exceptions with a try:
1481 which excepts to catch all of the program exceptions with a try:
1486 except: statement.
1482 except: statement.
1487
1483
1488 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1484 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1489 any app directly invokes sys.excepthook, it will look to the user like
1485 any app directly invokes sys.excepthook, it will look to the user like
1490 IPython crashed. In order to work around this, we can disable the
1486 IPython crashed. In order to work around this, we can disable the
1491 CrashHandler and replace it with this excepthook instead, which prints a
1487 CrashHandler and replace it with this excepthook instead, which prints a
1492 regular traceback using our InteractiveTB. In this fashion, apps which
1488 regular traceback using our InteractiveTB. In this fashion, apps which
1493 call sys.excepthook will generate a regular-looking exception from
1489 call sys.excepthook will generate a regular-looking exception from
1494 IPython, and the CrashHandler will only be triggered by real IPython
1490 IPython, and the CrashHandler will only be triggered by real IPython
1495 crashes.
1491 crashes.
1496
1492
1497 This hook should be used sparingly, only in places which are not likely
1493 This hook should be used sparingly, only in places which are not likely
1498 to be true IPython errors.
1494 to be true IPython errors.
1499 """
1495 """
1500 self.showtraceback((etype,value,tb),tb_offset=0)
1496 self.showtraceback((etype,value,tb),tb_offset=0)
1501
1497
1502 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1498 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None,
1503 exception_only=False):
1499 exception_only=False):
1504 """Display the exception that just occurred.
1500 """Display the exception that just occurred.
1505
1501
1506 If nothing is known about the exception, this is the method which
1502 If nothing is known about the exception, this is the method which
1507 should be used throughout the code for presenting user tracebacks,
1503 should be used throughout the code for presenting user tracebacks,
1508 rather than directly invoking the InteractiveTB object.
1504 rather than directly invoking the InteractiveTB object.
1509
1505
1510 A specific showsyntaxerror() also exists, but this method can take
1506 A specific showsyntaxerror() also exists, but this method can take
1511 care of calling it if needed, so unless you are explicitly catching a
1507 care of calling it if needed, so unless you are explicitly catching a
1512 SyntaxError exception, don't try to analyze the stack manually and
1508 SyntaxError exception, don't try to analyze the stack manually and
1513 simply call this method."""
1509 simply call this method."""
1514
1510
1515 try:
1511 try:
1516 if exc_tuple is None:
1512 if exc_tuple is None:
1517 etype, value, tb = sys.exc_info()
1513 etype, value, tb = sys.exc_info()
1518 else:
1514 else:
1519 etype, value, tb = exc_tuple
1515 etype, value, tb = exc_tuple
1520
1516
1521 if etype is None:
1517 if etype is None:
1522 if hasattr(sys, 'last_type'):
1518 if hasattr(sys, 'last_type'):
1523 etype, value, tb = sys.last_type, sys.last_value, \
1519 etype, value, tb = sys.last_type, sys.last_value, \
1524 sys.last_traceback
1520 sys.last_traceback
1525 else:
1521 else:
1526 self.write_err('No traceback available to show.\n')
1522 self.write_err('No traceback available to show.\n')
1527 return
1523 return
1528
1524
1529 if etype is SyntaxError:
1525 if etype is SyntaxError:
1530 # Though this won't be called by syntax errors in the input
1526 # Though this won't be called by syntax errors in the input
1531 # line, there may be SyntaxError cases whith imported code.
1527 # line, there may be SyntaxError cases whith imported code.
1532 self.showsyntaxerror(filename)
1528 self.showsyntaxerror(filename)
1533 elif etype is UsageError:
1529 elif etype is UsageError:
1534 print "UsageError:", value
1530 print "UsageError:", value
1535 else:
1531 else:
1536 # WARNING: these variables are somewhat deprecated and not
1532 # WARNING: these variables are somewhat deprecated and not
1537 # necessarily safe to use in a threaded environment, but tools
1533 # necessarily safe to use in a threaded environment, but tools
1538 # like pdb depend on their existence, so let's set them. If we
1534 # like pdb depend on their existence, so let's set them. If we
1539 # find problems in the field, we'll need to revisit their use.
1535 # find problems in the field, we'll need to revisit their use.
1540 sys.last_type = etype
1536 sys.last_type = etype
1541 sys.last_value = value
1537 sys.last_value = value
1542 sys.last_traceback = tb
1538 sys.last_traceback = tb
1543 if etype in self.custom_exceptions:
1539 if etype in self.custom_exceptions:
1544 # FIXME: Old custom traceback objects may just return a
1540 # FIXME: Old custom traceback objects may just return a
1545 # string, in that case we just put it into a list
1541 # string, in that case we just put it into a list
1546 stb = self.CustomTB(etype, value, tb, tb_offset)
1542 stb = self.CustomTB(etype, value, tb, tb_offset)
1547 if isinstance(ctb, basestring):
1543 if isinstance(ctb, basestring):
1548 stb = [stb]
1544 stb = [stb]
1549 else:
1545 else:
1550 if exception_only:
1546 if exception_only:
1551 stb = ['An exception has occurred, use %tb to see '
1547 stb = ['An exception has occurred, use %tb to see '
1552 'the full traceback.\n']
1548 'the full traceback.\n']
1553 stb.extend(self.InteractiveTB.get_exception_only(etype,
1549 stb.extend(self.InteractiveTB.get_exception_only(etype,
1554 value))
1550 value))
1555 else:
1551 else:
1556 stb = self.InteractiveTB.structured_traceback(etype,
1552 stb = self.InteractiveTB.structured_traceback(etype,
1557 value, tb, tb_offset=tb_offset)
1553 value, tb, tb_offset=tb_offset)
1558
1554
1559 if self.call_pdb:
1555 if self.call_pdb:
1560 # drop into debugger
1556 # drop into debugger
1561 self.debugger(force=True)
1557 self.debugger(force=True)
1562
1558
1563 # Actually show the traceback
1559 # Actually show the traceback
1564 self._showtraceback(etype, value, stb)
1560 self._showtraceback(etype, value, stb)
1565
1561
1566 except KeyboardInterrupt:
1562 except KeyboardInterrupt:
1567 self.write_err("\nKeyboardInterrupt\n")
1563 self.write_err("\nKeyboardInterrupt\n")
1568
1564
1569 def _showtraceback(self, etype, evalue, stb):
1565 def _showtraceback(self, etype, evalue, stb):
1570 """Actually show a traceback.
1566 """Actually show a traceback.
1571
1567
1572 Subclasses may override this method to put the traceback on a different
1568 Subclasses may override this method to put the traceback on a different
1573 place, like a side channel.
1569 place, like a side channel.
1574 """
1570 """
1575 print >> io.stdout, self.InteractiveTB.stb2text(stb)
1571 print >> io.stdout, self.InteractiveTB.stb2text(stb)
1576
1572
1577 def showsyntaxerror(self, filename=None):
1573 def showsyntaxerror(self, filename=None):
1578 """Display the syntax error that just occurred.
1574 """Display the syntax error that just occurred.
1579
1575
1580 This doesn't display a stack trace because there isn't one.
1576 This doesn't display a stack trace because there isn't one.
1581
1577
1582 If a filename is given, it is stuffed in the exception instead
1578 If a filename is given, it is stuffed in the exception instead
1583 of what was there before (because Python's parser always uses
1579 of what was there before (because Python's parser always uses
1584 "<string>" when reading from a string).
1580 "<string>" when reading from a string).
1585 """
1581 """
1586 etype, value, last_traceback = sys.exc_info()
1582 etype, value, last_traceback = sys.exc_info()
1587
1583
1588 # See note about these variables in showtraceback() above
1584 # See note about these variables in showtraceback() above
1589 sys.last_type = etype
1585 sys.last_type = etype
1590 sys.last_value = value
1586 sys.last_value = value
1591 sys.last_traceback = last_traceback
1587 sys.last_traceback = last_traceback
1592
1588
1593 if filename and etype is SyntaxError:
1589 if filename and etype is SyntaxError:
1594 # Work hard to stuff the correct filename in the exception
1590 # Work hard to stuff the correct filename in the exception
1595 try:
1591 try:
1596 msg, (dummy_filename, lineno, offset, line) = value
1592 msg, (dummy_filename, lineno, offset, line) = value
1597 except:
1593 except:
1598 # Not the format we expect; leave it alone
1594 # Not the format we expect; leave it alone
1599 pass
1595 pass
1600 else:
1596 else:
1601 # Stuff in the right filename
1597 # Stuff in the right filename
1602 try:
1598 try:
1603 # Assume SyntaxError is a class exception
1599 # Assume SyntaxError is a class exception
1604 value = SyntaxError(msg, (filename, lineno, offset, line))
1600 value = SyntaxError(msg, (filename, lineno, offset, line))
1605 except:
1601 except:
1606 # If that failed, assume SyntaxError is a string
1602 # If that failed, assume SyntaxError is a string
1607 value = msg, (filename, lineno, offset, line)
1603 value = msg, (filename, lineno, offset, line)
1608 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1604 stb = self.SyntaxTB.structured_traceback(etype, value, [])
1609 self._showtraceback(etype, value, stb)
1605 self._showtraceback(etype, value, stb)
1610
1606
1611 # This is overridden in TerminalInteractiveShell to show a message about
1607 # This is overridden in TerminalInteractiveShell to show a message about
1612 # the %paste magic.
1608 # the %paste magic.
1613 def showindentationerror(self):
1609 def showindentationerror(self):
1614 """Called by run_cell when there's an IndentationError in code entered
1610 """Called by run_cell when there's an IndentationError in code entered
1615 at the prompt.
1611 at the prompt.
1616
1612
1617 This is overridden in TerminalInteractiveShell to show a message about
1613 This is overridden in TerminalInteractiveShell to show a message about
1618 the %paste magic."""
1614 the %paste magic."""
1619 self.showsyntaxerror()
1615 self.showsyntaxerror()
1620
1616
1621 #-------------------------------------------------------------------------
1617 #-------------------------------------------------------------------------
1622 # Things related to readline
1618 # Things related to readline
1623 #-------------------------------------------------------------------------
1619 #-------------------------------------------------------------------------
1624
1620
1625 def init_readline(self):
1621 def init_readline(self):
1626 """Command history completion/saving/reloading."""
1622 """Command history completion/saving/reloading."""
1627
1623
1628 if self.readline_use:
1624 if self.readline_use:
1629 import IPython.utils.rlineimpl as readline
1625 import IPython.utils.rlineimpl as readline
1630
1626
1631 self.rl_next_input = None
1627 self.rl_next_input = None
1632 self.rl_do_indent = False
1628 self.rl_do_indent = False
1633
1629
1634 if not self.readline_use or not readline.have_readline:
1630 if not self.readline_use or not readline.have_readline:
1635 self.has_readline = False
1631 self.has_readline = False
1636 self.readline = None
1632 self.readline = None
1637 # Set a number of methods that depend on readline to be no-op
1633 # Set a number of methods that depend on readline to be no-op
1638 self.set_readline_completer = no_op
1634 self.set_readline_completer = no_op
1639 self.set_custom_completer = no_op
1635 self.set_custom_completer = no_op
1640 self.set_completer_frame = no_op
1636 self.set_completer_frame = no_op
1641 warn('Readline services not available or not loaded.')
1637 warn('Readline services not available or not loaded.')
1642 else:
1638 else:
1643 self.has_readline = True
1639 self.has_readline = True
1644 self.readline = readline
1640 self.readline = readline
1645 sys.modules['readline'] = readline
1641 sys.modules['readline'] = readline
1646
1642
1647 # Platform-specific configuration
1643 # Platform-specific configuration
1648 if os.name == 'nt':
1644 if os.name == 'nt':
1649 # FIXME - check with Frederick to see if we can harmonize
1645 # FIXME - check with Frederick to see if we can harmonize
1650 # naming conventions with pyreadline to avoid this
1646 # naming conventions with pyreadline to avoid this
1651 # platform-dependent check
1647 # platform-dependent check
1652 self.readline_startup_hook = readline.set_pre_input_hook
1648 self.readline_startup_hook = readline.set_pre_input_hook
1653 else:
1649 else:
1654 self.readline_startup_hook = readline.set_startup_hook
1650 self.readline_startup_hook = readline.set_startup_hook
1655
1651
1656 # Load user's initrc file (readline config)
1652 # Load user's initrc file (readline config)
1657 # Or if libedit is used, load editrc.
1653 # Or if libedit is used, load editrc.
1658 inputrc_name = os.environ.get('INPUTRC')
1654 inputrc_name = os.environ.get('INPUTRC')
1659 if inputrc_name is None:
1655 if inputrc_name is None:
1660 home_dir = get_home_dir()
1656 home_dir = get_home_dir()
1661 if home_dir is not None:
1657 if home_dir is not None:
1662 inputrc_name = '.inputrc'
1658 inputrc_name = '.inputrc'
1663 if readline.uses_libedit:
1659 if readline.uses_libedit:
1664 inputrc_name = '.editrc'
1660 inputrc_name = '.editrc'
1665 inputrc_name = os.path.join(home_dir, inputrc_name)
1661 inputrc_name = os.path.join(home_dir, inputrc_name)
1666 if os.path.isfile(inputrc_name):
1662 if os.path.isfile(inputrc_name):
1667 try:
1663 try:
1668 readline.read_init_file(inputrc_name)
1664 readline.read_init_file(inputrc_name)
1669 except:
1665 except:
1670 warn('Problems reading readline initialization file <%s>'
1666 warn('Problems reading readline initialization file <%s>'
1671 % inputrc_name)
1667 % inputrc_name)
1672
1668
1673 # Configure readline according to user's prefs
1669 # Configure readline according to user's prefs
1674 # This is only done if GNU readline is being used. If libedit
1670 # This is only done if GNU readline is being used. If libedit
1675 # is being used (as on Leopard) the readline config is
1671 # is being used (as on Leopard) the readline config is
1676 # not run as the syntax for libedit is different.
1672 # not run as the syntax for libedit is different.
1677 if not readline.uses_libedit:
1673 if not readline.uses_libedit:
1678 for rlcommand in self.readline_parse_and_bind:
1674 for rlcommand in self.readline_parse_and_bind:
1679 #print "loading rl:",rlcommand # dbg
1675 #print "loading rl:",rlcommand # dbg
1680 readline.parse_and_bind(rlcommand)
1676 readline.parse_and_bind(rlcommand)
1681
1677
1682 # Remove some chars from the delimiters list. If we encounter
1678 # Remove some chars from the delimiters list. If we encounter
1683 # unicode chars, discard them.
1679 # unicode chars, discard them.
1684 delims = readline.get_completer_delims().encode("ascii", "ignore")
1680 delims = readline.get_completer_delims().encode("ascii", "ignore")
1685 for d in self.readline_remove_delims:
1681 for d in self.readline_remove_delims:
1686 delims = delims.replace(d, "")
1682 delims = delims.replace(d, "")
1687 delims = delims.replace(ESC_MAGIC, '')
1683 delims = delims.replace(ESC_MAGIC, '')
1688 readline.set_completer_delims(delims)
1684 readline.set_completer_delims(delims)
1689 # otherwise we end up with a monster history after a while:
1685 # otherwise we end up with a monster history after a while:
1690 readline.set_history_length(self.history_length)
1686 readline.set_history_length(self.history_length)
1691
1687
1692 self.refill_readline_hist()
1688 self.refill_readline_hist()
1693 self.readline_no_record = ReadlineNoRecord(self)
1689 self.readline_no_record = ReadlineNoRecord(self)
1694
1690
1695 # Configure auto-indent for all platforms
1691 # Configure auto-indent for all platforms
1696 self.set_autoindent(self.autoindent)
1692 self.set_autoindent(self.autoindent)
1697
1693
1698 def refill_readline_hist(self):
1694 def refill_readline_hist(self):
1699 # Load the last 1000 lines from history
1695 # Load the last 1000 lines from history
1700 self.readline.clear_history()
1696 self.readline.clear_history()
1701 stdin_encoding = sys.stdin.encoding or "utf-8"
1697 stdin_encoding = sys.stdin.encoding or "utf-8"
1702 for _, _, cell in self.history_manager.get_tail(1000,
1698 for _, _, cell in self.history_manager.get_tail(1000,
1703 include_latest=True):
1699 include_latest=True):
1704 if cell.strip(): # Ignore blank lines
1700 if cell.strip(): # Ignore blank lines
1705 for line in cell.splitlines():
1701 for line in cell.splitlines():
1706 self.readline.add_history(py3compat.unicode_to_str(line,
1702 self.readline.add_history(py3compat.unicode_to_str(line,
1707 stdin_encoding))
1703 stdin_encoding))
1708
1704
1709 def set_next_input(self, s):
1705 def set_next_input(self, s):
1710 """ Sets the 'default' input string for the next command line.
1706 """ Sets the 'default' input string for the next command line.
1711
1707
1712 Requires readline.
1708 Requires readline.
1713
1709
1714 Example:
1710 Example:
1715
1711
1716 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1712 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1717 [D:\ipython]|2> Hello Word_ # cursor is here
1713 [D:\ipython]|2> Hello Word_ # cursor is here
1718 """
1714 """
1719 if isinstance(s, unicode):
1715 if isinstance(s, unicode):
1720 s = s.encode(self.stdin_encoding, 'replace')
1716 s = s.encode(self.stdin_encoding, 'replace')
1721 self.rl_next_input = s
1717 self.rl_next_input = s
1722
1718
1723 # Maybe move this to the terminal subclass?
1719 # Maybe move this to the terminal subclass?
1724 def pre_readline(self):
1720 def pre_readline(self):
1725 """readline hook to be used at the start of each line.
1721 """readline hook to be used at the start of each line.
1726
1722
1727 Currently it handles auto-indent only."""
1723 Currently it handles auto-indent only."""
1728
1724
1729 if self.rl_do_indent:
1725 if self.rl_do_indent:
1730 self.readline.insert_text(self._indent_current_str())
1726 self.readline.insert_text(self._indent_current_str())
1731 if self.rl_next_input is not None:
1727 if self.rl_next_input is not None:
1732 self.readline.insert_text(self.rl_next_input)
1728 self.readline.insert_text(self.rl_next_input)
1733 self.rl_next_input = None
1729 self.rl_next_input = None
1734
1730
1735 def _indent_current_str(self):
1731 def _indent_current_str(self):
1736 """return the current level of indentation as a string"""
1732 """return the current level of indentation as a string"""
1737 return self.input_splitter.indent_spaces * ' '
1733 return self.input_splitter.indent_spaces * ' '
1738
1734
1739 #-------------------------------------------------------------------------
1735 #-------------------------------------------------------------------------
1740 # Things related to text completion
1736 # Things related to text completion
1741 #-------------------------------------------------------------------------
1737 #-------------------------------------------------------------------------
1742
1738
1743 def init_completer(self):
1739 def init_completer(self):
1744 """Initialize the completion machinery.
1740 """Initialize the completion machinery.
1745
1741
1746 This creates completion machinery that can be used by client code,
1742 This creates completion machinery that can be used by client code,
1747 either interactively in-process (typically triggered by the readline
1743 either interactively in-process (typically triggered by the readline
1748 library), programatically (such as in test suites) or out-of-prcess
1744 library), programatically (such as in test suites) or out-of-prcess
1749 (typically over the network by remote frontends).
1745 (typically over the network by remote frontends).
1750 """
1746 """
1751 from IPython.core.completer import IPCompleter
1747 from IPython.core.completer import IPCompleter
1752 from IPython.core.completerlib import (module_completer,
1748 from IPython.core.completerlib import (module_completer,
1753 magic_run_completer, cd_completer)
1749 magic_run_completer, cd_completer)
1754
1750
1755 self.Completer = IPCompleter(self,
1751 self.Completer = IPCompleter(self,
1756 self.user_ns,
1752 self.user_ns,
1757 self.user_global_ns,
1753 self.user_global_ns,
1758 self.readline_omit__names,
1754 self.readline_omit__names,
1759 self.alias_manager.alias_table,
1755 self.alias_manager.alias_table,
1760 self.has_readline)
1756 self.has_readline)
1761
1757
1762 # Add custom completers to the basic ones built into IPCompleter
1758 # Add custom completers to the basic ones built into IPCompleter
1763 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1759 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1764 self.strdispatchers['complete_command'] = sdisp
1760 self.strdispatchers['complete_command'] = sdisp
1765 self.Completer.custom_completers = sdisp
1761 self.Completer.custom_completers = sdisp
1766
1762
1767 self.set_hook('complete_command', module_completer, str_key = 'import')
1763 self.set_hook('complete_command', module_completer, str_key = 'import')
1768 self.set_hook('complete_command', module_completer, str_key = 'from')
1764 self.set_hook('complete_command', module_completer, str_key = 'from')
1769 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1765 self.set_hook('complete_command', magic_run_completer, str_key = '%run')
1770 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1766 self.set_hook('complete_command', cd_completer, str_key = '%cd')
1771
1767
1772 # Only configure readline if we truly are using readline. IPython can
1768 # Only configure readline if we truly are using readline. IPython can
1773 # do tab-completion over the network, in GUIs, etc, where readline
1769 # do tab-completion over the network, in GUIs, etc, where readline
1774 # itself may be absent
1770 # itself may be absent
1775 if self.has_readline:
1771 if self.has_readline:
1776 self.set_readline_completer()
1772 self.set_readline_completer()
1777
1773
1778 def complete(self, text, line=None, cursor_pos=None):
1774 def complete(self, text, line=None, cursor_pos=None):
1779 """Return the completed text and a list of completions.
1775 """Return the completed text and a list of completions.
1780
1776
1781 Parameters
1777 Parameters
1782 ----------
1778 ----------
1783
1779
1784 text : string
1780 text : string
1785 A string of text to be completed on. It can be given as empty and
1781 A string of text to be completed on. It can be given as empty and
1786 instead a line/position pair are given. In this case, the
1782 instead a line/position pair are given. In this case, the
1787 completer itself will split the line like readline does.
1783 completer itself will split the line like readline does.
1788
1784
1789 line : string, optional
1785 line : string, optional
1790 The complete line that text is part of.
1786 The complete line that text is part of.
1791
1787
1792 cursor_pos : int, optional
1788 cursor_pos : int, optional
1793 The position of the cursor on the input line.
1789 The position of the cursor on the input line.
1794
1790
1795 Returns
1791 Returns
1796 -------
1792 -------
1797 text : string
1793 text : string
1798 The actual text that was completed.
1794 The actual text that was completed.
1799
1795
1800 matches : list
1796 matches : list
1801 A sorted list with all possible completions.
1797 A sorted list with all possible completions.
1802
1798
1803 The optional arguments allow the completion to take more context into
1799 The optional arguments allow the completion to take more context into
1804 account, and are part of the low-level completion API.
1800 account, and are part of the low-level completion API.
1805
1801
1806 This is a wrapper around the completion mechanism, similar to what
1802 This is a wrapper around the completion mechanism, similar to what
1807 readline does at the command line when the TAB key is hit. By
1803 readline does at the command line when the TAB key is hit. By
1808 exposing it as a method, it can be used by other non-readline
1804 exposing it as a method, it can be used by other non-readline
1809 environments (such as GUIs) for text completion.
1805 environments (such as GUIs) for text completion.
1810
1806
1811 Simple usage example:
1807 Simple usage example:
1812
1808
1813 In [1]: x = 'hello'
1809 In [1]: x = 'hello'
1814
1810
1815 In [2]: _ip.complete('x.l')
1811 In [2]: _ip.complete('x.l')
1816 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1812 Out[2]: ('x.l', ['x.ljust', 'x.lower', 'x.lstrip'])
1817 """
1813 """
1818
1814
1819 # Inject names into __builtin__ so we can complete on the added names.
1815 # Inject names into __builtin__ so we can complete on the added names.
1820 with self.builtin_trap:
1816 with self.builtin_trap:
1821 return self.Completer.complete(text, line, cursor_pos)
1817 return self.Completer.complete(text, line, cursor_pos)
1822
1818
1823 def set_custom_completer(self, completer, pos=0):
1819 def set_custom_completer(self, completer, pos=0):
1824 """Adds a new custom completer function.
1820 """Adds a new custom completer function.
1825
1821
1826 The position argument (defaults to 0) is the index in the completers
1822 The position argument (defaults to 0) is the index in the completers
1827 list where you want the completer to be inserted."""
1823 list where you want the completer to be inserted."""
1828
1824
1829 newcomp = types.MethodType(completer,self.Completer)
1825 newcomp = types.MethodType(completer,self.Completer)
1830 self.Completer.matchers.insert(pos,newcomp)
1826 self.Completer.matchers.insert(pos,newcomp)
1831
1827
1832 def set_readline_completer(self):
1828 def set_readline_completer(self):
1833 """Reset readline's completer to be our own."""
1829 """Reset readline's completer to be our own."""
1834 self.readline.set_completer(self.Completer.rlcomplete)
1830 self.readline.set_completer(self.Completer.rlcomplete)
1835
1831
1836 def set_completer_frame(self, frame=None):
1832 def set_completer_frame(self, frame=None):
1837 """Set the frame of the completer."""
1833 """Set the frame of the completer."""
1838 if frame:
1834 if frame:
1839 self.Completer.namespace = frame.f_locals
1835 self.Completer.namespace = frame.f_locals
1840 self.Completer.global_namespace = frame.f_globals
1836 self.Completer.global_namespace = frame.f_globals
1841 else:
1837 else:
1842 self.Completer.namespace = self.user_ns
1838 self.Completer.namespace = self.user_ns
1843 self.Completer.global_namespace = self.user_global_ns
1839 self.Completer.global_namespace = self.user_global_ns
1844
1840
1845 #-------------------------------------------------------------------------
1841 #-------------------------------------------------------------------------
1846 # Things related to magics
1842 # Things related to magics
1847 #-------------------------------------------------------------------------
1843 #-------------------------------------------------------------------------
1848
1844
1849 def init_magics(self):
1845 def init_magics(self):
1850 # FIXME: Move the color initialization to the DisplayHook, which
1846 # FIXME: Move the color initialization to the DisplayHook, which
1851 # should be split into a prompt manager and displayhook. We probably
1847 # should be split into a prompt manager and displayhook. We probably
1852 # even need a centralize colors management object.
1848 # even need a centralize colors management object.
1853 self.magic_colors(self.colors)
1849 self.magic_colors(self.colors)
1854 # History was moved to a separate module
1850 # History was moved to a separate module
1855 from . import history
1851 from . import history
1856 history.init_ipython(self)
1852 history.init_ipython(self)
1857
1853
1858 def magic(self, arg_s, next_input=None):
1854 def magic(self, arg_s, next_input=None):
1859 """Call a magic function by name.
1855 """Call a magic function by name.
1860
1856
1861 Input: a string containing the name of the magic function to call and
1857 Input: a string containing the name of the magic function to call and
1862 any additional arguments to be passed to the magic.
1858 any additional arguments to be passed to the magic.
1863
1859
1864 magic('name -opt foo bar') is equivalent to typing at the ipython
1860 magic('name -opt foo bar') is equivalent to typing at the ipython
1865 prompt:
1861 prompt:
1866
1862
1867 In[1]: %name -opt foo bar
1863 In[1]: %name -opt foo bar
1868
1864
1869 To call a magic without arguments, simply use magic('name').
1865 To call a magic without arguments, simply use magic('name').
1870
1866
1871 This provides a proper Python function to call IPython's magics in any
1867 This provides a proper Python function to call IPython's magics in any
1872 valid Python code you can type at the interpreter, including loops and
1868 valid Python code you can type at the interpreter, including loops and
1873 compound statements.
1869 compound statements.
1874 """
1870 """
1875 # Allow setting the next input - this is used if the user does `a=abs?`.
1871 # Allow setting the next input - this is used if the user does `a=abs?`.
1876 # We do this first so that magic functions can override it.
1872 # We do this first so that magic functions can override it.
1877 if next_input:
1873 if next_input:
1878 self.set_next_input(next_input)
1874 self.set_next_input(next_input)
1879
1875
1880 args = arg_s.split(' ',1)
1876 args = arg_s.split(' ',1)
1881 magic_name = args[0]
1877 magic_name = args[0]
1882 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1878 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1883
1879
1884 try:
1880 try:
1885 magic_args = args[1]
1881 magic_args = args[1]
1886 except IndexError:
1882 except IndexError:
1887 magic_args = ''
1883 magic_args = ''
1888 fn = getattr(self,'magic_'+magic_name,None)
1884 fn = getattr(self,'magic_'+magic_name,None)
1889 if fn is None:
1885 if fn is None:
1890 error("Magic function `%s` not found." % magic_name)
1886 error("Magic function `%s` not found." % magic_name)
1891 else:
1887 else:
1892 magic_args = self.var_expand(magic_args,1)
1888 magic_args = self.var_expand(magic_args,1)
1893 # Grab local namespace if we need it:
1889 # Grab local namespace if we need it:
1894 if getattr(fn, "needs_local_scope", False):
1890 if getattr(fn, "needs_local_scope", False):
1895 self._magic_locals = sys._getframe(1).f_locals
1891 self._magic_locals = sys._getframe(1).f_locals
1896 with self.builtin_trap:
1892 with self.builtin_trap:
1897 result = fn(magic_args)
1893 result = fn(magic_args)
1898 # Ensure we're not keeping object references around:
1894 # Ensure we're not keeping object references around:
1899 self._magic_locals = {}
1895 self._magic_locals = {}
1900 return result
1896 return result
1901
1897
1902 def define_magic(self, magicname, func):
1898 def define_magic(self, magicname, func):
1903 """Expose own function as magic function for ipython
1899 """Expose own function as magic function for ipython
1904
1900
1905 def foo_impl(self,parameter_s=''):
1901 def foo_impl(self,parameter_s=''):
1906 'My very own magic!. (Use docstrings, IPython reads them).'
1902 'My very own magic!. (Use docstrings, IPython reads them).'
1907 print 'Magic function. Passed parameter is between < >:'
1903 print 'Magic function. Passed parameter is between < >:'
1908 print '<%s>' % parameter_s
1904 print '<%s>' % parameter_s
1909 print 'The self object is:',self
1905 print 'The self object is:',self
1910
1906
1911 self.define_magic('foo',foo_impl)
1907 self.define_magic('foo',foo_impl)
1912 """
1908 """
1913 im = types.MethodType(func,self)
1909 im = types.MethodType(func,self)
1914 old = getattr(self, "magic_" + magicname, None)
1910 old = getattr(self, "magic_" + magicname, None)
1915 setattr(self, "magic_" + magicname, im)
1911 setattr(self, "magic_" + magicname, im)
1916 return old
1912 return old
1917
1913
1918 #-------------------------------------------------------------------------
1914 #-------------------------------------------------------------------------
1919 # Things related to macros
1915 # Things related to macros
1920 #-------------------------------------------------------------------------
1916 #-------------------------------------------------------------------------
1921
1917
1922 def define_macro(self, name, themacro):
1918 def define_macro(self, name, themacro):
1923 """Define a new macro
1919 """Define a new macro
1924
1920
1925 Parameters
1921 Parameters
1926 ----------
1922 ----------
1927 name : str
1923 name : str
1928 The name of the macro.
1924 The name of the macro.
1929 themacro : str or Macro
1925 themacro : str or Macro
1930 The action to do upon invoking the macro. If a string, a new
1926 The action to do upon invoking the macro. If a string, a new
1931 Macro object is created by passing the string to it.
1927 Macro object is created by passing the string to it.
1932 """
1928 """
1933
1929
1934 from IPython.core import macro
1930 from IPython.core import macro
1935
1931
1936 if isinstance(themacro, basestring):
1932 if isinstance(themacro, basestring):
1937 themacro = macro.Macro(themacro)
1933 themacro = macro.Macro(themacro)
1938 if not isinstance(themacro, macro.Macro):
1934 if not isinstance(themacro, macro.Macro):
1939 raise ValueError('A macro must be a string or a Macro instance.')
1935 raise ValueError('A macro must be a string or a Macro instance.')
1940 self.user_ns[name] = themacro
1936 self.user_ns[name] = themacro
1941
1937
1942 #-------------------------------------------------------------------------
1938 #-------------------------------------------------------------------------
1943 # Things related to the running of system commands
1939 # Things related to the running of system commands
1944 #-------------------------------------------------------------------------
1940 #-------------------------------------------------------------------------
1945
1941
1946 def system_piped(self, cmd):
1942 def system_piped(self, cmd):
1947 """Call the given cmd in a subprocess, piping stdout/err
1943 """Call the given cmd in a subprocess, piping stdout/err
1948
1944
1949 Parameters
1945 Parameters
1950 ----------
1946 ----------
1951 cmd : str
1947 cmd : str
1952 Command to execute (can not end in '&', as background processes are
1948 Command to execute (can not end in '&', as background processes are
1953 not supported. Should not be a command that expects input
1949 not supported. Should not be a command that expects input
1954 other than simple text.
1950 other than simple text.
1955 """
1951 """
1956 if cmd.rstrip().endswith('&'):
1952 if cmd.rstrip().endswith('&'):
1957 # this is *far* from a rigorous test
1953 # this is *far* from a rigorous test
1958 # We do not support backgrounding processes because we either use
1954 # We do not support backgrounding processes because we either use
1959 # pexpect or pipes to read from. Users can always just call
1955 # pexpect or pipes to read from. Users can always just call
1960 # os.system() or use ip.system=ip.system_raw
1956 # os.system() or use ip.system=ip.system_raw
1961 # if they really want a background process.
1957 # if they really want a background process.
1962 raise OSError("Background processes not supported.")
1958 raise OSError("Background processes not supported.")
1963
1959
1964 # we explicitly do NOT return the subprocess status code, because
1960 # we explicitly do NOT return the subprocess status code, because
1965 # a non-None value would trigger :func:`sys.displayhook` calls.
1961 # a non-None value would trigger :func:`sys.displayhook` calls.
1966 # Instead, we store the exit_code in user_ns.
1962 # Instead, we store the exit_code in user_ns.
1967 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=2))
1963 self.user_ns['_exit_code'] = system(self.var_expand(cmd, depth=2))
1968
1964
1969 def system_raw(self, cmd):
1965 def system_raw(self, cmd):
1970 """Call the given cmd in a subprocess using os.system
1966 """Call the given cmd in a subprocess using os.system
1971
1967
1972 Parameters
1968 Parameters
1973 ----------
1969 ----------
1974 cmd : str
1970 cmd : str
1975 Command to execute.
1971 Command to execute.
1976 """
1972 """
1977 # We explicitly do NOT return the subprocess status code, because
1973 # We explicitly do NOT return the subprocess status code, because
1978 # a non-None value would trigger :func:`sys.displayhook` calls.
1974 # a non-None value would trigger :func:`sys.displayhook` calls.
1979 # Instead, we store the exit_code in user_ns.
1975 # Instead, we store the exit_code in user_ns.
1980 self.user_ns['_exit_code'] = os.system(self.var_expand(cmd, depth=2))
1976 self.user_ns['_exit_code'] = os.system(self.var_expand(cmd, depth=2))
1981
1977
1982 # use piped system by default, because it is better behaved
1978 # use piped system by default, because it is better behaved
1983 system = system_piped
1979 system = system_piped
1984
1980
1985 def getoutput(self, cmd, split=True):
1981 def getoutput(self, cmd, split=True):
1986 """Get output (possibly including stderr) from a subprocess.
1982 """Get output (possibly including stderr) from a subprocess.
1987
1983
1988 Parameters
1984 Parameters
1989 ----------
1985 ----------
1990 cmd : str
1986 cmd : str
1991 Command to execute (can not end in '&', as background processes are
1987 Command to execute (can not end in '&', as background processes are
1992 not supported.
1988 not supported.
1993 split : bool, optional
1989 split : bool, optional
1994
1990
1995 If True, split the output into an IPython SList. Otherwise, an
1991 If True, split the output into an IPython SList. Otherwise, an
1996 IPython LSString is returned. These are objects similar to normal
1992 IPython LSString is returned. These are objects similar to normal
1997 lists and strings, with a few convenience attributes for easier
1993 lists and strings, with a few convenience attributes for easier
1998 manipulation of line-based output. You can use '?' on them for
1994 manipulation of line-based output. You can use '?' on them for
1999 details.
1995 details.
2000 """
1996 """
2001 if cmd.rstrip().endswith('&'):
1997 if cmd.rstrip().endswith('&'):
2002 # this is *far* from a rigorous test
1998 # this is *far* from a rigorous test
2003 raise OSError("Background processes not supported.")
1999 raise OSError("Background processes not supported.")
2004 out = getoutput(self.var_expand(cmd, depth=2))
2000 out = getoutput(self.var_expand(cmd, depth=2))
2005 if split:
2001 if split:
2006 out = SList(out.splitlines())
2002 out = SList(out.splitlines())
2007 else:
2003 else:
2008 out = LSString(out)
2004 out = LSString(out)
2009 return out
2005 return out
2010
2006
2011 #-------------------------------------------------------------------------
2007 #-------------------------------------------------------------------------
2012 # Things related to aliases
2008 # Things related to aliases
2013 #-------------------------------------------------------------------------
2009 #-------------------------------------------------------------------------
2014
2010
2015 def init_alias(self):
2011 def init_alias(self):
2016 self.alias_manager = AliasManager(shell=self, config=self.config)
2012 self.alias_manager = AliasManager(shell=self, config=self.config)
2017 self.ns_table['alias'] = self.alias_manager.alias_table,
2013 self.ns_table['alias'] = self.alias_manager.alias_table,
2018
2014
2019 #-------------------------------------------------------------------------
2015 #-------------------------------------------------------------------------
2020 # Things related to extensions and plugins
2016 # Things related to extensions and plugins
2021 #-------------------------------------------------------------------------
2017 #-------------------------------------------------------------------------
2022
2018
2023 def init_extension_manager(self):
2019 def init_extension_manager(self):
2024 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2020 self.extension_manager = ExtensionManager(shell=self, config=self.config)
2025
2021
2026 def init_plugin_manager(self):
2022 def init_plugin_manager(self):
2027 self.plugin_manager = PluginManager(config=self.config)
2023 self.plugin_manager = PluginManager(config=self.config)
2028
2024
2029 #-------------------------------------------------------------------------
2025 #-------------------------------------------------------------------------
2030 # Things related to payloads
2026 # Things related to payloads
2031 #-------------------------------------------------------------------------
2027 #-------------------------------------------------------------------------
2032
2028
2033 def init_payload(self):
2029 def init_payload(self):
2034 self.payload_manager = PayloadManager(config=self.config)
2030 self.payload_manager = PayloadManager(config=self.config)
2035
2031
2036 #-------------------------------------------------------------------------
2032 #-------------------------------------------------------------------------
2037 # Things related to the prefilter
2033 # Things related to the prefilter
2038 #-------------------------------------------------------------------------
2034 #-------------------------------------------------------------------------
2039
2035
2040 def init_prefilter(self):
2036 def init_prefilter(self):
2041 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2037 self.prefilter_manager = PrefilterManager(shell=self, config=self.config)
2042 # Ultimately this will be refactored in the new interpreter code, but
2038 # Ultimately this will be refactored in the new interpreter code, but
2043 # for now, we should expose the main prefilter method (there's legacy
2039 # for now, we should expose the main prefilter method (there's legacy
2044 # code out there that may rely on this).
2040 # code out there that may rely on this).
2045 self.prefilter = self.prefilter_manager.prefilter_lines
2041 self.prefilter = self.prefilter_manager.prefilter_lines
2046
2042
2047 def auto_rewrite_input(self, cmd):
2043 def auto_rewrite_input(self, cmd):
2048 """Print to the screen the rewritten form of the user's command.
2044 """Print to the screen the rewritten form of the user's command.
2049
2045
2050 This shows visual feedback by rewriting input lines that cause
2046 This shows visual feedback by rewriting input lines that cause
2051 automatic calling to kick in, like::
2047 automatic calling to kick in, like::
2052
2048
2053 /f x
2049 /f x
2054
2050
2055 into::
2051 into::
2056
2052
2057 ------> f(x)
2053 ------> f(x)
2058
2054
2059 after the user's input prompt. This helps the user understand that the
2055 after the user's input prompt. This helps the user understand that the
2060 input line was transformed automatically by IPython.
2056 input line was transformed automatically by IPython.
2061 """
2057 """
2062 rw = self.displayhook.prompt1.auto_rewrite() + cmd
2058 rw = self.displayhook.prompt1.auto_rewrite() + cmd
2063
2059
2064 try:
2060 try:
2065 # plain ascii works better w/ pyreadline, on some machines, so
2061 # plain ascii works better w/ pyreadline, on some machines, so
2066 # we use it and only print uncolored rewrite if we have unicode
2062 # we use it and only print uncolored rewrite if we have unicode
2067 rw = str(rw)
2063 rw = str(rw)
2068 print >> io.stdout, rw
2064 print >> io.stdout, rw
2069 except UnicodeEncodeError:
2065 except UnicodeEncodeError:
2070 print "------> " + cmd
2066 print "------> " + cmd
2071
2067
2072 #-------------------------------------------------------------------------
2068 #-------------------------------------------------------------------------
2073 # Things related to extracting values/expressions from kernel and user_ns
2069 # Things related to extracting values/expressions from kernel and user_ns
2074 #-------------------------------------------------------------------------
2070 #-------------------------------------------------------------------------
2075
2071
2076 def _simple_error(self):
2072 def _simple_error(self):
2077 etype, value = sys.exc_info()[:2]
2073 etype, value = sys.exc_info()[:2]
2078 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2074 return u'[ERROR] {e.__name__}: {v}'.format(e=etype, v=value)
2079
2075
2080 def user_variables(self, names):
2076 def user_variables(self, names):
2081 """Get a list of variable names from the user's namespace.
2077 """Get a list of variable names from the user's namespace.
2082
2078
2083 Parameters
2079 Parameters
2084 ----------
2080 ----------
2085 names : list of strings
2081 names : list of strings
2086 A list of names of variables to be read from the user namespace.
2082 A list of names of variables to be read from the user namespace.
2087
2083
2088 Returns
2084 Returns
2089 -------
2085 -------
2090 A dict, keyed by the input names and with the repr() of each value.
2086 A dict, keyed by the input names and with the repr() of each value.
2091 """
2087 """
2092 out = {}
2088 out = {}
2093 user_ns = self.user_ns
2089 user_ns = self.user_ns
2094 for varname in names:
2090 for varname in names:
2095 try:
2091 try:
2096 value = repr(user_ns[varname])
2092 value = repr(user_ns[varname])
2097 except:
2093 except:
2098 value = self._simple_error()
2094 value = self._simple_error()
2099 out[varname] = value
2095 out[varname] = value
2100 return out
2096 return out
2101
2097
2102 def user_expressions(self, expressions):
2098 def user_expressions(self, expressions):
2103 """Evaluate a dict of expressions in the user's namespace.
2099 """Evaluate a dict of expressions in the user's namespace.
2104
2100
2105 Parameters
2101 Parameters
2106 ----------
2102 ----------
2107 expressions : dict
2103 expressions : dict
2108 A dict with string keys and string values. The expression values
2104 A dict with string keys and string values. The expression values
2109 should be valid Python expressions, each of which will be evaluated
2105 should be valid Python expressions, each of which will be evaluated
2110 in the user namespace.
2106 in the user namespace.
2111
2107
2112 Returns
2108 Returns
2113 -------
2109 -------
2114 A dict, keyed like the input expressions dict, with the repr() of each
2110 A dict, keyed like the input expressions dict, with the repr() of each
2115 value.
2111 value.
2116 """
2112 """
2117 out = {}
2113 out = {}
2118 user_ns = self.user_ns
2114 user_ns = self.user_ns
2119 global_ns = self.user_global_ns
2115 global_ns = self.user_global_ns
2120 for key, expr in expressions.iteritems():
2116 for key, expr in expressions.iteritems():
2121 try:
2117 try:
2122 value = repr(eval(expr, global_ns, user_ns))
2118 value = repr(eval(expr, global_ns, user_ns))
2123 except:
2119 except:
2124 value = self._simple_error()
2120 value = self._simple_error()
2125 out[key] = value
2121 out[key] = value
2126 return out
2122 return out
2127
2123
2128 #-------------------------------------------------------------------------
2124 #-------------------------------------------------------------------------
2129 # Things related to the running of code
2125 # Things related to the running of code
2130 #-------------------------------------------------------------------------
2126 #-------------------------------------------------------------------------
2131
2127
2132 def ex(self, cmd):
2128 def ex(self, cmd):
2133 """Execute a normal python statement in user namespace."""
2129 """Execute a normal python statement in user namespace."""
2134 with self.builtin_trap:
2130 with self.builtin_trap:
2135 exec cmd in self.user_global_ns, self.user_ns
2131 exec cmd in self.user_global_ns, self.user_ns
2136
2132
2137 def ev(self, expr):
2133 def ev(self, expr):
2138 """Evaluate python expression expr in user namespace.
2134 """Evaluate python expression expr in user namespace.
2139
2135
2140 Returns the result of evaluation
2136 Returns the result of evaluation
2141 """
2137 """
2142 with self.builtin_trap:
2138 with self.builtin_trap:
2143 return eval(expr, self.user_global_ns, self.user_ns)
2139 return eval(expr, self.user_global_ns, self.user_ns)
2144
2140
2145 def safe_execfile(self, fname, *where, **kw):
2141 def safe_execfile(self, fname, *where, **kw):
2146 """A safe version of the builtin execfile().
2142 """A safe version of the builtin execfile().
2147
2143
2148 This version will never throw an exception, but instead print
2144 This version will never throw an exception, but instead print
2149 helpful error messages to the screen. This only works on pure
2145 helpful error messages to the screen. This only works on pure
2150 Python files with the .py extension.
2146 Python files with the .py extension.
2151
2147
2152 Parameters
2148 Parameters
2153 ----------
2149 ----------
2154 fname : string
2150 fname : string
2155 The name of the file to be executed.
2151 The name of the file to be executed.
2156 where : tuple
2152 where : tuple
2157 One or two namespaces, passed to execfile() as (globals,locals).
2153 One or two namespaces, passed to execfile() as (globals,locals).
2158 If only one is given, it is passed as both.
2154 If only one is given, it is passed as both.
2159 exit_ignore : bool (False)
2155 exit_ignore : bool (False)
2160 If True, then silence SystemExit for non-zero status (it is always
2156 If True, then silence SystemExit for non-zero status (it is always
2161 silenced for zero status, as it is so common).
2157 silenced for zero status, as it is so common).
2162 """
2158 """
2163 kw.setdefault('exit_ignore', False)
2159 kw.setdefault('exit_ignore', False)
2164
2160
2165 fname = os.path.abspath(os.path.expanduser(fname))
2161 fname = os.path.abspath(os.path.expanduser(fname))
2166
2162
2167 # Make sure we can open the file
2163 # Make sure we can open the file
2168 try:
2164 try:
2169 with open(fname) as thefile:
2165 with open(fname) as thefile:
2170 pass
2166 pass
2171 except:
2167 except:
2172 warn('Could not open file <%s> for safe execution.' % fname)
2168 warn('Could not open file <%s> for safe execution.' % fname)
2173 return
2169 return
2174
2170
2175 # Find things also in current directory. This is needed to mimic the
2171 # Find things also in current directory. This is needed to mimic the
2176 # behavior of running a script from the system command line, where
2172 # behavior of running a script from the system command line, where
2177 # Python inserts the script's directory into sys.path
2173 # Python inserts the script's directory into sys.path
2178 dname = os.path.dirname(fname)
2174 dname = os.path.dirname(fname)
2179
2175
2180 with prepended_to_syspath(dname):
2176 with prepended_to_syspath(dname):
2181 try:
2177 try:
2182 py3compat.execfile(fname,*where)
2178 py3compat.execfile(fname,*where)
2183 except SystemExit, status:
2179 except SystemExit, status:
2184 # If the call was made with 0 or None exit status (sys.exit(0)
2180 # If the call was made with 0 or None exit status (sys.exit(0)
2185 # or sys.exit() ), don't bother showing a traceback, as both of
2181 # or sys.exit() ), don't bother showing a traceback, as both of
2186 # these are considered normal by the OS:
2182 # these are considered normal by the OS:
2187 # > python -c'import sys;sys.exit(0)'; echo $?
2183 # > python -c'import sys;sys.exit(0)'; echo $?
2188 # 0
2184 # 0
2189 # > python -c'import sys;sys.exit()'; echo $?
2185 # > python -c'import sys;sys.exit()'; echo $?
2190 # 0
2186 # 0
2191 # For other exit status, we show the exception unless
2187 # For other exit status, we show the exception unless
2192 # explicitly silenced, but only in short form.
2188 # explicitly silenced, but only in short form.
2193 if status.code not in (0, None) and not kw['exit_ignore']:
2189 if status.code not in (0, None) and not kw['exit_ignore']:
2194 self.showtraceback(exception_only=True)
2190 self.showtraceback(exception_only=True)
2195 except:
2191 except:
2196 self.showtraceback()
2192 self.showtraceback()
2197
2193
2198 def safe_execfile_ipy(self, fname):
2194 def safe_execfile_ipy(self, fname):
2199 """Like safe_execfile, but for .ipy files with IPython syntax.
2195 """Like safe_execfile, but for .ipy files with IPython syntax.
2200
2196
2201 Parameters
2197 Parameters
2202 ----------
2198 ----------
2203 fname : str
2199 fname : str
2204 The name of the file to execute. The filename must have a
2200 The name of the file to execute. The filename must have a
2205 .ipy extension.
2201 .ipy extension.
2206 """
2202 """
2207 fname = os.path.abspath(os.path.expanduser(fname))
2203 fname = os.path.abspath(os.path.expanduser(fname))
2208
2204
2209 # Make sure we can open the file
2205 # Make sure we can open the file
2210 try:
2206 try:
2211 with open(fname) as thefile:
2207 with open(fname) as thefile:
2212 pass
2208 pass
2213 except:
2209 except:
2214 warn('Could not open file <%s> for safe execution.' % fname)
2210 warn('Could not open file <%s> for safe execution.' % fname)
2215 return
2211 return
2216
2212
2217 # Find things also in current directory. This is needed to mimic the
2213 # Find things also in current directory. This is needed to mimic the
2218 # behavior of running a script from the system command line, where
2214 # behavior of running a script from the system command line, where
2219 # Python inserts the script's directory into sys.path
2215 # Python inserts the script's directory into sys.path
2220 dname = os.path.dirname(fname)
2216 dname = os.path.dirname(fname)
2221
2217
2222 with prepended_to_syspath(dname):
2218 with prepended_to_syspath(dname):
2223 try:
2219 try:
2224 with open(fname) as thefile:
2220 with open(fname) as thefile:
2225 # self.run_cell currently captures all exceptions
2221 # self.run_cell currently captures all exceptions
2226 # raised in user code. It would be nice if there were
2222 # raised in user code. It would be nice if there were
2227 # versions of runlines, execfile that did raise, so
2223 # versions of runlines, execfile that did raise, so
2228 # we could catch the errors.
2224 # we could catch the errors.
2229 self.run_cell(thefile.read(), store_history=False)
2225 self.run_cell(thefile.read(), store_history=False)
2230 except:
2226 except:
2231 self.showtraceback()
2227 self.showtraceback()
2232 warn('Unknown failure executing file: <%s>' % fname)
2228 warn('Unknown failure executing file: <%s>' % fname)
2233
2229
2234 def run_cell(self, raw_cell, store_history=True):
2230 def run_cell(self, raw_cell, store_history=True):
2235 """Run a complete IPython cell.
2231 """Run a complete IPython cell.
2236
2232
2237 Parameters
2233 Parameters
2238 ----------
2234 ----------
2239 raw_cell : str
2235 raw_cell : str
2240 The code (including IPython code such as %magic functions) to run.
2236 The code (including IPython code such as %magic functions) to run.
2241 store_history : bool
2237 store_history : bool
2242 If True, the raw and translated cell will be stored in IPython's
2238 If True, the raw and translated cell will be stored in IPython's
2243 history. For user code calling back into IPython's machinery, this
2239 history. For user code calling back into IPython's machinery, this
2244 should be set to False.
2240 should be set to False.
2245 """
2241 """
2246 if (not raw_cell) or raw_cell.isspace():
2242 if (not raw_cell) or raw_cell.isspace():
2247 return
2243 return
2248
2244
2249 for line in raw_cell.splitlines():
2245 for line in raw_cell.splitlines():
2250 self.input_splitter.push(line)
2246 self.input_splitter.push(line)
2251 cell = self.input_splitter.source_reset()
2247 cell = self.input_splitter.source_reset()
2252
2248
2253 with self.builtin_trap:
2249 with self.builtin_trap:
2254 prefilter_failed = False
2250 prefilter_failed = False
2255 if len(cell.splitlines()) == 1:
2251 if len(cell.splitlines()) == 1:
2256 try:
2252 try:
2257 # use prefilter_lines to handle trailing newlines
2253 # use prefilter_lines to handle trailing newlines
2258 # restore trailing newline for ast.parse
2254 # restore trailing newline for ast.parse
2259 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2255 cell = self.prefilter_manager.prefilter_lines(cell) + '\n'
2260 except AliasError as e:
2256 except AliasError as e:
2261 error(e)
2257 error(e)
2262 prefilter_failed = True
2258 prefilter_failed = True
2263 except Exception:
2259 except Exception:
2264 # don't allow prefilter errors to crash IPython
2260 # don't allow prefilter errors to crash IPython
2265 self.showtraceback()
2261 self.showtraceback()
2266 prefilter_failed = True
2262 prefilter_failed = True
2267
2263
2268 # Store raw and processed history
2264 # Store raw and processed history
2269 if store_history:
2265 if store_history:
2270 self.history_manager.store_inputs(self.execution_count,
2266 self.history_manager.store_inputs(self.execution_count,
2271 cell, raw_cell)
2267 cell, raw_cell)
2272
2268
2273 self.logger.log(cell, raw_cell)
2269 self.logger.log(cell, raw_cell)
2274
2270
2275 if not prefilter_failed:
2271 if not prefilter_failed:
2276 # don't run if prefilter failed
2272 # don't run if prefilter failed
2277 cell_name = self.compile.cache(cell, self.execution_count)
2273 cell_name = self.compile.cache(cell, self.execution_count)
2278
2274
2279 with self.display_trap:
2275 with self.display_trap:
2280 try:
2276 try:
2281 code_ast = ast.parse(cell, filename=cell_name)
2277 code_ast = ast.parse(cell, filename=cell_name)
2282 except IndentationError:
2278 except IndentationError:
2283 self.showindentationerror()
2279 self.showindentationerror()
2284 self.execution_count += 1
2280 self.execution_count += 1
2285 return None
2281 return None
2286 except (OverflowError, SyntaxError, ValueError, TypeError,
2282 except (OverflowError, SyntaxError, ValueError, TypeError,
2287 MemoryError):
2283 MemoryError):
2288 self.showsyntaxerror()
2284 self.showsyntaxerror()
2289 self.execution_count += 1
2285 self.execution_count += 1
2290 return None
2286 return None
2291
2287
2292 self.run_ast_nodes(code_ast.body, cell_name,
2288 self.run_ast_nodes(code_ast.body, cell_name,
2293 interactivity="last_expr")
2289 interactivity="last_expr")
2294
2290
2295 # Execute any registered post-execution functions.
2291 # Execute any registered post-execution functions.
2296 for func, status in self._post_execute.iteritems():
2292 for func, status in self._post_execute.iteritems():
2297 if not status:
2293 if not status:
2298 continue
2294 continue
2299 try:
2295 try:
2300 func()
2296 func()
2301 except:
2297 except:
2302 self.showtraceback()
2298 self.showtraceback()
2303 # Deactivate failing function
2299 # Deactivate failing function
2304 self._post_execute[func] = False
2300 self._post_execute[func] = False
2305
2301
2306 if store_history:
2302 if store_history:
2307 # Write output to the database. Does nothing unless
2303 # Write output to the database. Does nothing unless
2308 # history output logging is enabled.
2304 # history output logging is enabled.
2309 self.history_manager.store_output(self.execution_count)
2305 self.history_manager.store_output(self.execution_count)
2310 # Each cell is a *single* input, regardless of how many lines it has
2306 # Each cell is a *single* input, regardless of how many lines it has
2311 self.execution_count += 1
2307 self.execution_count += 1
2312
2308
2313 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2309 def run_ast_nodes(self, nodelist, cell_name, interactivity='last_expr'):
2314 """Run a sequence of AST nodes. The execution mode depends on the
2310 """Run a sequence of AST nodes. The execution mode depends on the
2315 interactivity parameter.
2311 interactivity parameter.
2316
2312
2317 Parameters
2313 Parameters
2318 ----------
2314 ----------
2319 nodelist : list
2315 nodelist : list
2320 A sequence of AST nodes to run.
2316 A sequence of AST nodes to run.
2321 cell_name : str
2317 cell_name : str
2322 Will be passed to the compiler as the filename of the cell. Typically
2318 Will be passed to the compiler as the filename of the cell. Typically
2323 the value returned by ip.compile.cache(cell).
2319 the value returned by ip.compile.cache(cell).
2324 interactivity : str
2320 interactivity : str
2325 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2321 'all', 'last', 'last_expr' or 'none', specifying which nodes should be
2326 run interactively (displaying output from expressions). 'last_expr'
2322 run interactively (displaying output from expressions). 'last_expr'
2327 will run the last node interactively only if it is an expression (i.e.
2323 will run the last node interactively only if it is an expression (i.e.
2328 expressions in loops or other blocks are not displayed. Other values
2324 expressions in loops or other blocks are not displayed. Other values
2329 for this parameter will raise a ValueError.
2325 for this parameter will raise a ValueError.
2330 """
2326 """
2331 if not nodelist:
2327 if not nodelist:
2332 return
2328 return
2333
2329
2334 if interactivity == 'last_expr':
2330 if interactivity == 'last_expr':
2335 if isinstance(nodelist[-1], ast.Expr):
2331 if isinstance(nodelist[-1], ast.Expr):
2336 interactivity = "last"
2332 interactivity = "last"
2337 else:
2333 else:
2338 interactivity = "none"
2334 interactivity = "none"
2339
2335
2340 if interactivity == 'none':
2336 if interactivity == 'none':
2341 to_run_exec, to_run_interactive = nodelist, []
2337 to_run_exec, to_run_interactive = nodelist, []
2342 elif interactivity == 'last':
2338 elif interactivity == 'last':
2343 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2339 to_run_exec, to_run_interactive = nodelist[:-1], nodelist[-1:]
2344 elif interactivity == 'all':
2340 elif interactivity == 'all':
2345 to_run_exec, to_run_interactive = [], nodelist
2341 to_run_exec, to_run_interactive = [], nodelist
2346 else:
2342 else:
2347 raise ValueError("Interactivity was %r" % interactivity)
2343 raise ValueError("Interactivity was %r" % interactivity)
2348
2344
2349 exec_count = self.execution_count
2345 exec_count = self.execution_count
2350
2346
2351 try:
2347 try:
2352 for i, node in enumerate(to_run_exec):
2348 for i, node in enumerate(to_run_exec):
2353 mod = ast.Module([node])
2349 mod = ast.Module([node])
2354 code = self.compile(mod, cell_name, "exec")
2350 code = self.compile(mod, cell_name, "exec")
2355 if self.run_code(code):
2351 if self.run_code(code):
2356 return True
2352 return True
2357
2353
2358 for i, node in enumerate(to_run_interactive):
2354 for i, node in enumerate(to_run_interactive):
2359 mod = ast.Interactive([node])
2355 mod = ast.Interactive([node])
2360 code = self.compile(mod, cell_name, "single")
2356 code = self.compile(mod, cell_name, "single")
2361 if self.run_code(code):
2357 if self.run_code(code):
2362 return True
2358 return True
2363 except:
2359 except:
2364 # It's possible to have exceptions raised here, typically by
2360 # It's possible to have exceptions raised here, typically by
2365 # compilation of odd code (such as a naked 'return' outside a
2361 # compilation of odd code (such as a naked 'return' outside a
2366 # function) that did parse but isn't valid. Typically the exception
2362 # function) that did parse but isn't valid. Typically the exception
2367 # is a SyntaxError, but it's safest just to catch anything and show
2363 # is a SyntaxError, but it's safest just to catch anything and show
2368 # the user a traceback.
2364 # the user a traceback.
2369
2365
2370 # We do only one try/except outside the loop to minimize the impact
2366 # We do only one try/except outside the loop to minimize the impact
2371 # on runtime, and also because if any node in the node list is
2367 # on runtime, and also because if any node in the node list is
2372 # broken, we should stop execution completely.
2368 # broken, we should stop execution completely.
2373 self.showtraceback()
2369 self.showtraceback()
2374
2370
2375 return False
2371 return False
2376
2372
2377 def run_code(self, code_obj):
2373 def run_code(self, code_obj):
2378 """Execute a code object.
2374 """Execute a code object.
2379
2375
2380 When an exception occurs, self.showtraceback() is called to display a
2376 When an exception occurs, self.showtraceback() is called to display a
2381 traceback.
2377 traceback.
2382
2378
2383 Parameters
2379 Parameters
2384 ----------
2380 ----------
2385 code_obj : code object
2381 code_obj : code object
2386 A compiled code object, to be executed
2382 A compiled code object, to be executed
2387 post_execute : bool [default: True]
2383 post_execute : bool [default: True]
2388 whether to call post_execute hooks after this particular execution.
2384 whether to call post_execute hooks after this particular execution.
2389
2385
2390 Returns
2386 Returns
2391 -------
2387 -------
2392 False : successful execution.
2388 False : successful execution.
2393 True : an error occurred.
2389 True : an error occurred.
2394 """
2390 """
2395
2391
2396 # Set our own excepthook in case the user code tries to call it
2392 # Set our own excepthook in case the user code tries to call it
2397 # directly, so that the IPython crash handler doesn't get triggered
2393 # directly, so that the IPython crash handler doesn't get triggered
2398 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2394 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2399
2395
2400 # we save the original sys.excepthook in the instance, in case config
2396 # we save the original sys.excepthook in the instance, in case config
2401 # code (such as magics) needs access to it.
2397 # code (such as magics) needs access to it.
2402 self.sys_excepthook = old_excepthook
2398 self.sys_excepthook = old_excepthook
2403 outflag = 1 # happens in more places, so it's easier as default
2399 outflag = 1 # happens in more places, so it's easier as default
2404 try:
2400 try:
2405 try:
2401 try:
2406 self.hooks.pre_run_code_hook()
2402 self.hooks.pre_run_code_hook()
2407 #rprint('Running code', repr(code_obj)) # dbg
2403 #rprint('Running code', repr(code_obj)) # dbg
2408 exec code_obj in self.user_global_ns, self.user_ns
2404 exec code_obj in self.user_global_ns, self.user_ns
2409 finally:
2405 finally:
2410 # Reset our crash handler in place
2406 # Reset our crash handler in place
2411 sys.excepthook = old_excepthook
2407 sys.excepthook = old_excepthook
2412 except SystemExit:
2408 except SystemExit:
2413 self.showtraceback(exception_only=True)
2409 self.showtraceback(exception_only=True)
2414 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2410 warn("To exit: use 'exit', 'quit', or Ctrl-D.", level=1)
2415 except self.custom_exceptions:
2411 except self.custom_exceptions:
2416 etype,value,tb = sys.exc_info()
2412 etype,value,tb = sys.exc_info()
2417 self.CustomTB(etype,value,tb)
2413 self.CustomTB(etype,value,tb)
2418 except:
2414 except:
2419 self.showtraceback()
2415 self.showtraceback()
2420 else:
2416 else:
2421 outflag = 0
2417 outflag = 0
2422 if softspace(sys.stdout, 0):
2418 if softspace(sys.stdout, 0):
2423 print
2419 print
2424
2420
2425 return outflag
2421 return outflag
2426
2422
2427 # For backwards compatibility
2423 # For backwards compatibility
2428 runcode = run_code
2424 runcode = run_code
2429
2425
2430 #-------------------------------------------------------------------------
2426 #-------------------------------------------------------------------------
2431 # Things related to GUI support and pylab
2427 # Things related to GUI support and pylab
2432 #-------------------------------------------------------------------------
2428 #-------------------------------------------------------------------------
2433
2429
2434 def enable_pylab(self, gui=None, import_all=True):
2430 def enable_pylab(self, gui=None, import_all=True):
2435 raise NotImplementedError('Implement enable_pylab in a subclass')
2431 raise NotImplementedError('Implement enable_pylab in a subclass')
2436
2432
2437 #-------------------------------------------------------------------------
2433 #-------------------------------------------------------------------------
2438 # Utilities
2434 # Utilities
2439 #-------------------------------------------------------------------------
2435 #-------------------------------------------------------------------------
2440
2436
2441 def var_expand(self,cmd,depth=0):
2437 def var_expand(self,cmd,depth=0):
2442 """Expand python variables in a string.
2438 """Expand python variables in a string.
2443
2439
2444 The depth argument indicates how many frames above the caller should
2440 The depth argument indicates how many frames above the caller should
2445 be walked to look for the local namespace where to expand variables.
2441 be walked to look for the local namespace where to expand variables.
2446
2442
2447 The global namespace for expansion is always the user's interactive
2443 The global namespace for expansion is always the user's interactive
2448 namespace.
2444 namespace.
2449 """
2445 """
2450 res = ItplNS(cmd, self.user_ns, # globals
2446 res = ItplNS(cmd, self.user_ns, # globals
2451 # Skip our own frame in searching for locals:
2447 # Skip our own frame in searching for locals:
2452 sys._getframe(depth+1).f_locals # locals
2448 sys._getframe(depth+1).f_locals # locals
2453 )
2449 )
2454 return str(res).decode(res.codec)
2450 return str(res).decode(res.codec)
2455
2451
2456 def mktempfile(self, data=None, prefix='ipython_edit_'):
2452 def mktempfile(self, data=None, prefix='ipython_edit_'):
2457 """Make a new tempfile and return its filename.
2453 """Make a new tempfile and return its filename.
2458
2454
2459 This makes a call to tempfile.mktemp, but it registers the created
2455 This makes a call to tempfile.mktemp, but it registers the created
2460 filename internally so ipython cleans it up at exit time.
2456 filename internally so ipython cleans it up at exit time.
2461
2457
2462 Optional inputs:
2458 Optional inputs:
2463
2459
2464 - data(None): if data is given, it gets written out to the temp file
2460 - data(None): if data is given, it gets written out to the temp file
2465 immediately, and the file is closed again."""
2461 immediately, and the file is closed again."""
2466
2462
2467 filename = tempfile.mktemp('.py', prefix)
2463 filename = tempfile.mktemp('.py', prefix)
2468 self.tempfiles.append(filename)
2464 self.tempfiles.append(filename)
2469
2465
2470 if data:
2466 if data:
2471 tmp_file = open(filename,'w')
2467 tmp_file = open(filename,'w')
2472 tmp_file.write(data)
2468 tmp_file.write(data)
2473 tmp_file.close()
2469 tmp_file.close()
2474 return filename
2470 return filename
2475
2471
2476 # TODO: This should be removed when Term is refactored.
2472 # TODO: This should be removed when Term is refactored.
2477 def write(self,data):
2473 def write(self,data):
2478 """Write a string to the default output"""
2474 """Write a string to the default output"""
2479 io.stdout.write(data)
2475 io.stdout.write(data)
2480
2476
2481 # TODO: This should be removed when Term is refactored.
2477 # TODO: This should be removed when Term is refactored.
2482 def write_err(self,data):
2478 def write_err(self,data):
2483 """Write a string to the default error output"""
2479 """Write a string to the default error output"""
2484 io.stderr.write(data)
2480 io.stderr.write(data)
2485
2481
2486 def ask_yes_no(self,prompt,default=True):
2482 def ask_yes_no(self,prompt,default=True):
2487 if self.quiet:
2483 if self.quiet:
2488 return True
2484 return True
2489 return ask_yes_no(prompt,default)
2485 return ask_yes_no(prompt,default)
2490
2486
2491 def show_usage(self):
2487 def show_usage(self):
2492 """Show a usage message"""
2488 """Show a usage message"""
2493 page.page(IPython.core.usage.interactive_usage)
2489 page.page(IPython.core.usage.interactive_usage)
2494
2490
2495 def find_user_code(self, target, raw=True):
2491 def find_user_code(self, target, raw=True):
2496 """Get a code string from history, file, or a string or macro.
2492 """Get a code string from history, file, or a string or macro.
2497
2493
2498 This is mainly used by magic functions.
2494 This is mainly used by magic functions.
2499
2495
2500 Parameters
2496 Parameters
2501 ----------
2497 ----------
2502 target : str
2498 target : str
2503 A string specifying code to retrieve. This will be tried respectively
2499 A string specifying code to retrieve. This will be tried respectively
2504 as: ranges of input history (see %history for syntax), a filename, or
2500 as: ranges of input history (see %history for syntax), a filename, or
2505 an expression evaluating to a string or Macro in the user namespace.
2501 an expression evaluating to a string or Macro in the user namespace.
2506 raw : bool
2502 raw : bool
2507 If true (default), retrieve raw history. Has no effect on the other
2503 If true (default), retrieve raw history. Has no effect on the other
2508 retrieval mechanisms.
2504 retrieval mechanisms.
2509
2505
2510 Returns
2506 Returns
2511 -------
2507 -------
2512 A string of code.
2508 A string of code.
2513
2509
2514 ValueError is raised if nothing is found, and TypeError if it evaluates
2510 ValueError is raised if nothing is found, and TypeError if it evaluates
2515 to an object of another type. In each case, .args[0] is a printable
2511 to an object of another type. In each case, .args[0] is a printable
2516 message.
2512 message.
2517 """
2513 """
2518 code = self.extract_input_lines(target, raw=raw) # Grab history
2514 code = self.extract_input_lines(target, raw=raw) # Grab history
2519 if code:
2515 if code:
2520 return code
2516 return code
2521 if os.path.isfile(target): # Read file
2517 if os.path.isfile(target): # Read file
2522 return open(target, "r").read()
2518 return open(target, "r").read()
2523
2519
2524 try: # User namespace
2520 try: # User namespace
2525 codeobj = eval(target, self.user_ns)
2521 codeobj = eval(target, self.user_ns)
2526 except Exception:
2522 except Exception:
2527 raise ValueError(("'%s' was not found in history, as a file, nor in"
2523 raise ValueError(("'%s' was not found in history, as a file, nor in"
2528 " the user namespace.") % target)
2524 " the user namespace.") % target)
2529 if isinstance(codeobj, basestring):
2525 if isinstance(codeobj, basestring):
2530 return codeobj
2526 return codeobj
2531 elif isinstance(codeobj, Macro):
2527 elif isinstance(codeobj, Macro):
2532 return codeobj.value
2528 return codeobj.value
2533
2529
2534 raise TypeError("%s is neither a string nor a macro." % target,
2530 raise TypeError("%s is neither a string nor a macro." % target,
2535 codeobj)
2531 codeobj)
2536
2532
2537 #-------------------------------------------------------------------------
2533 #-------------------------------------------------------------------------
2538 # Things related to IPython exiting
2534 # Things related to IPython exiting
2539 #-------------------------------------------------------------------------
2535 #-------------------------------------------------------------------------
2540 def atexit_operations(self):
2536 def atexit_operations(self):
2541 """This will be executed at the time of exit.
2537 """This will be executed at the time of exit.
2542
2538
2543 Cleanup operations and saving of persistent data that is done
2539 Cleanup operations and saving of persistent data that is done
2544 unconditionally by IPython should be performed here.
2540 unconditionally by IPython should be performed here.
2545
2541
2546 For things that may depend on startup flags or platform specifics (such
2542 For things that may depend on startup flags or platform specifics (such
2547 as having readline or not), register a separate atexit function in the
2543 as having readline or not), register a separate atexit function in the
2548 code that has the appropriate information, rather than trying to
2544 code that has the appropriate information, rather than trying to
2549 clutter
2545 clutter
2550 """
2546 """
2551 # Close the history session (this stores the end time and line count)
2547 # Close the history session (this stores the end time and line count)
2552 # this must be *before* the tempfile cleanup, in case of temporary
2548 # this must be *before* the tempfile cleanup, in case of temporary
2553 # history db
2549 # history db
2554 self.history_manager.end_session()
2550 self.history_manager.end_session()
2555
2551
2556 # Cleanup all tempfiles left around
2552 # Cleanup all tempfiles left around
2557 for tfile in self.tempfiles:
2553 for tfile in self.tempfiles:
2558 try:
2554 try:
2559 os.unlink(tfile)
2555 os.unlink(tfile)
2560 except OSError:
2556 except OSError:
2561 pass
2557 pass
2562
2558
2563 # Clear all user namespaces to release all references cleanly.
2559 # Clear all user namespaces to release all references cleanly.
2564 self.reset(new_session=False)
2560 self.reset(new_session=False)
2565
2561
2566 # Run user hooks
2562 # Run user hooks
2567 self.hooks.shutdown_hook()
2563 self.hooks.shutdown_hook()
2568
2564
2569 def cleanup(self):
2565 def cleanup(self):
2570 self.restore_sys_module_state()
2566 self.restore_sys_module_state()
2571
2567
2572
2568
2573 class InteractiveShellABC(object):
2569 class InteractiveShellABC(object):
2574 """An abstract base class for InteractiveShell."""
2570 """An abstract base class for InteractiveShell."""
2575 __metaclass__ = abc.ABCMeta
2571 __metaclass__ = abc.ABCMeta
2576
2572
2577 InteractiveShellABC.register(InteractiveShell)
2573 InteractiveShellABC.register(InteractiveShell)
@@ -1,48 +1,62 b''
1 # coding: utf-8
2 """Compatibility tricks for Python 3. Mainly to do with unicode."""
1 import sys
3 import sys
2
4
3 def no_code(x, encoding=None):
5 def no_code(x, encoding=None):
4 return x
6 return x
5
7
6 def decode(s, encoding=None):
8 def decode(s, encoding=None):
7 encoding = encoding or sys.stdin.encoding or sys.getdefaultencoding()
9 encoding = encoding or sys.stdin.encoding or sys.getdefaultencoding()
8 return s.decode(encoding, "replace")
10 return s.decode(encoding, "replace")
9
11
10 def encode(u, encoding=None):
12 def encode(u, encoding=None):
11 encoding = encoding or sys.stdin.encoding or sys.getdefaultencoding()
13 encoding = encoding or sys.stdin.encoding or sys.getdefaultencoding()
12 return u.encode(encoding, "replace")
14 return u.encode(encoding, "replace")
13
15
14 def cast_unicode(s, encoding=None):
16 def cast_unicode(s, encoding=None):
15 if isinstance(s, bytes):
17 if isinstance(s, bytes):
16 return decode(s, encoding)
18 return decode(s, encoding)
17 return s
19 return s
18
20
19 def cast_bytes(s, encoding=None):
21 def cast_bytes(s, encoding=None):
20 if not isinstance(s, bytes):
22 if not isinstance(s, bytes):
21 return encode(s, encoding)
23 return encode(s, encoding)
22 return s
24 return s
23
25
24 if sys.version_info[0] >= 3:
26 if sys.version_info[0] >= 3:
25 PY3 = True
27 PY3 = True
26
28
27 input = input
29 input = input
28 builtin_mod_name = "builtins"
30 builtin_mod_name = "builtins"
29
31
30 str_to_unicode = no_code
32 str_to_unicode = no_code
31 unicode_to_str = no_code
33 unicode_to_str = no_code
32 str_to_bytes = encode
34 str_to_bytes = encode
33 bytes_to_str = decode
35 bytes_to_str = decode
34
36
37 def isidentifier(s, dotted=False):
38 if dotted:
39 return all(isidentifier(a) for a in s.split("."))
40 return s.isidentifier()
41
35 else:
42 else:
36 PY3 = False
43 PY3 = False
37
44
38 input = raw_input
45 input = raw_input
39 builtin_mod_name = "__builtin__"
46 builtin_mod_name = "__builtin__"
40
47
41 str_to_unicode = decode
48 str_to_unicode = decode
42 unicode_to_str = encode
49 unicode_to_str = encode
43 str_to_bytes = no_code
50 str_to_bytes = no_code
44 bytes_to_str = no_code
51 bytes_to_str = no_code
45
52
53 import re
54 _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$")
55 def isidentifier(s, dotted=False):
56 if dotted:
57 return all(isidentifier(a) for a in s.split("."))
58 return bool(_name_re.match(s))
59
46 def execfile(fname, glob, loc=None):
60 def execfile(fname, glob, loc=None):
47 loc = loc if (loc is not None) else glob
61 loc = loc if (loc is not None) else glob
48 exec compile(open(fname).read(), fname, 'exec') in glob, loc
62 exec compile(open(fname).read(), fname, 'exec') in glob, loc
@@ -1,1398 +1,1392 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 A lightweight Traits like module.
3 A lightweight Traits like module.
4
4
5 This is designed to provide a lightweight, simple, pure Python version of
5 This is designed to provide a lightweight, simple, pure Python version of
6 many of the capabilities of enthought.traits. This includes:
6 many of the capabilities of enthought.traits. This includes:
7
7
8 * Validation
8 * Validation
9 * Type specification with defaults
9 * Type specification with defaults
10 * Static and dynamic notification
10 * Static and dynamic notification
11 * Basic predefined types
11 * Basic predefined types
12 * An API that is similar to enthought.traits
12 * An API that is similar to enthought.traits
13
13
14 We don't support:
14 We don't support:
15
15
16 * Delegation
16 * Delegation
17 * Automatic GUI generation
17 * Automatic GUI generation
18 * A full set of trait types. Most importantly, we don't provide container
18 * A full set of trait types. Most importantly, we don't provide container
19 traits (list, dict, tuple) that can trigger notifications if their
19 traits (list, dict, tuple) that can trigger notifications if their
20 contents change.
20 contents change.
21 * API compatibility with enthought.traits
21 * API compatibility with enthought.traits
22
22
23 There are also some important difference in our design:
23 There are also some important difference in our design:
24
24
25 * enthought.traits does not validate default values. We do.
25 * enthought.traits does not validate default values. We do.
26
26
27 We choose to create this module because we need these capabilities, but
27 We choose to create this module because we need these capabilities, but
28 we need them to be pure Python so they work in all Python implementations,
28 we need them to be pure Python so they work in all Python implementations,
29 including Jython and IronPython.
29 including Jython and IronPython.
30
30
31 Authors:
31 Authors:
32
32
33 * Brian Granger
33 * Brian Granger
34 * Enthought, Inc. Some of the code in this file comes from enthought.traits
34 * Enthought, Inc. Some of the code in this file comes from enthought.traits
35 and is licensed under the BSD license. Also, many of the ideas also come
35 and is licensed under the BSD license. Also, many of the ideas also come
36 from enthought.traits even though our implementation is very different.
36 from enthought.traits even though our implementation is very different.
37 """
37 """
38
38
39 #-----------------------------------------------------------------------------
39 #-----------------------------------------------------------------------------
40 # Copyright (C) 2008-2009 The IPython Development Team
40 # Copyright (C) 2008-2009 The IPython Development Team
41 #
41 #
42 # Distributed under the terms of the BSD License. The full license is in
42 # Distributed under the terms of the BSD License. The full license is in
43 # the file COPYING, distributed as part of this software.
43 # the file COPYING, distributed as part of this software.
44 #-----------------------------------------------------------------------------
44 #-----------------------------------------------------------------------------
45
45
46 #-----------------------------------------------------------------------------
46 #-----------------------------------------------------------------------------
47 # Imports
47 # Imports
48 #-----------------------------------------------------------------------------
48 #-----------------------------------------------------------------------------
49
49
50
50
51 import inspect
51 import inspect
52 import re
52 import re
53 import sys
53 import sys
54 import types
54 import types
55 from types import FunctionType
55 from types import FunctionType
56 try:
56 try:
57 from types import ClassType, InstanceType
57 from types import ClassType, InstanceType
58 ClassTypes = (ClassType, type)
58 ClassTypes = (ClassType, type)
59 except:
59 except:
60 ClassTypes = (type,)
60 ClassTypes = (type,)
61
61
62 from .importstring import import_item
62 from .importstring import import_item
63 from IPython.utils import py3compat
63 from IPython.utils import py3compat
64
64
65 SequenceTypes = (list, tuple, set, frozenset)
65 SequenceTypes = (list, tuple, set, frozenset)
66
66
67 #-----------------------------------------------------------------------------
67 #-----------------------------------------------------------------------------
68 # Basic classes
68 # Basic classes
69 #-----------------------------------------------------------------------------
69 #-----------------------------------------------------------------------------
70
70
71
71
72 class NoDefaultSpecified ( object ): pass
72 class NoDefaultSpecified ( object ): pass
73 NoDefaultSpecified = NoDefaultSpecified()
73 NoDefaultSpecified = NoDefaultSpecified()
74
74
75
75
76 class Undefined ( object ): pass
76 class Undefined ( object ): pass
77 Undefined = Undefined()
77 Undefined = Undefined()
78
78
79 class TraitError(Exception):
79 class TraitError(Exception):
80 pass
80 pass
81
81
82 #-----------------------------------------------------------------------------
82 #-----------------------------------------------------------------------------
83 # Utilities
83 # Utilities
84 #-----------------------------------------------------------------------------
84 #-----------------------------------------------------------------------------
85
85
86
86
87 def class_of ( object ):
87 def class_of ( object ):
88 """ Returns a string containing the class name of an object with the
88 """ Returns a string containing the class name of an object with the
89 correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
89 correct indefinite article ('a' or 'an') preceding it (e.g., 'an Image',
90 'a PlotValue').
90 'a PlotValue').
91 """
91 """
92 if isinstance( object, basestring ):
92 if isinstance( object, basestring ):
93 return add_article( object )
93 return add_article( object )
94
94
95 return add_article( object.__class__.__name__ )
95 return add_article( object.__class__.__name__ )
96
96
97
97
98 def add_article ( name ):
98 def add_article ( name ):
99 """ Returns a string containing the correct indefinite article ('a' or 'an')
99 """ Returns a string containing the correct indefinite article ('a' or 'an')
100 prefixed to the specified string.
100 prefixed to the specified string.
101 """
101 """
102 if name[:1].lower() in 'aeiou':
102 if name[:1].lower() in 'aeiou':
103 return 'an ' + name
103 return 'an ' + name
104
104
105 return 'a ' + name
105 return 'a ' + name
106
106
107
107
108 def repr_type(obj):
108 def repr_type(obj):
109 """ Return a string representation of a value and its type for readable
109 """ Return a string representation of a value and its type for readable
110 error messages.
110 error messages.
111 """
111 """
112 the_type = type(obj)
112 the_type = type(obj)
113 if (not py3compat.PY3) and the_type is InstanceType:
113 if (not py3compat.PY3) and the_type is InstanceType:
114 # Old-style class.
114 # Old-style class.
115 the_type = obj.__class__
115 the_type = obj.__class__
116 msg = '%r %r' % (obj, the_type)
116 msg = '%r %r' % (obj, the_type)
117 return msg
117 return msg
118
118
119
119
120 def parse_notifier_name(name):
120 def parse_notifier_name(name):
121 """Convert the name argument to a list of names.
121 """Convert the name argument to a list of names.
122
122
123 Examples
123 Examples
124 --------
124 --------
125
125
126 >>> parse_notifier_name('a')
126 >>> parse_notifier_name('a')
127 ['a']
127 ['a']
128 >>> parse_notifier_name(['a','b'])
128 >>> parse_notifier_name(['a','b'])
129 ['a', 'b']
129 ['a', 'b']
130 >>> parse_notifier_name(None)
130 >>> parse_notifier_name(None)
131 ['anytrait']
131 ['anytrait']
132 """
132 """
133 if isinstance(name, str):
133 if isinstance(name, str):
134 return [name]
134 return [name]
135 elif name is None:
135 elif name is None:
136 return ['anytrait']
136 return ['anytrait']
137 elif isinstance(name, (list, tuple)):
137 elif isinstance(name, (list, tuple)):
138 for n in name:
138 for n in name:
139 assert isinstance(n, str), "names must be strings"
139 assert isinstance(n, str), "names must be strings"
140 return name
140 return name
141
141
142
142
143 class _SimpleTest:
143 class _SimpleTest:
144 def __init__ ( self, value ): self.value = value
144 def __init__ ( self, value ): self.value = value
145 def __call__ ( self, test ):
145 def __call__ ( self, test ):
146 return test == self.value
146 return test == self.value
147 def __repr__(self):
147 def __repr__(self):
148 return "<SimpleTest(%r)" % self.value
148 return "<SimpleTest(%r)" % self.value
149 def __str__(self):
149 def __str__(self):
150 return self.__repr__()
150 return self.__repr__()
151
151
152
152
153 def getmembers(object, predicate=None):
153 def getmembers(object, predicate=None):
154 """A safe version of inspect.getmembers that handles missing attributes.
154 """A safe version of inspect.getmembers that handles missing attributes.
155
155
156 This is useful when there are descriptor based attributes that for
156 This is useful when there are descriptor based attributes that for
157 some reason raise AttributeError even though they exist. This happens
157 some reason raise AttributeError even though they exist. This happens
158 in zope.inteface with the __provides__ attribute.
158 in zope.inteface with the __provides__ attribute.
159 """
159 """
160 results = []
160 results = []
161 for key in dir(object):
161 for key in dir(object):
162 try:
162 try:
163 value = getattr(object, key)
163 value = getattr(object, key)
164 except AttributeError:
164 except AttributeError:
165 pass
165 pass
166 else:
166 else:
167 if not predicate or predicate(value):
167 if not predicate or predicate(value):
168 results.append((key, value))
168 results.append((key, value))
169 results.sort()
169 results.sort()
170 return results
170 return results
171
171
172
172
173 #-----------------------------------------------------------------------------
173 #-----------------------------------------------------------------------------
174 # Base TraitType for all traits
174 # Base TraitType for all traits
175 #-----------------------------------------------------------------------------
175 #-----------------------------------------------------------------------------
176
176
177
177
178 class TraitType(object):
178 class TraitType(object):
179 """A base class for all trait descriptors.
179 """A base class for all trait descriptors.
180
180
181 Notes
181 Notes
182 -----
182 -----
183 Our implementation of traits is based on Python's descriptor
183 Our implementation of traits is based on Python's descriptor
184 prototol. This class is the base class for all such descriptors. The
184 prototol. This class is the base class for all such descriptors. The
185 only magic we use is a custom metaclass for the main :class:`HasTraits`
185 only magic we use is a custom metaclass for the main :class:`HasTraits`
186 class that does the following:
186 class that does the following:
187
187
188 1. Sets the :attr:`name` attribute of every :class:`TraitType`
188 1. Sets the :attr:`name` attribute of every :class:`TraitType`
189 instance in the class dict to the name of the attribute.
189 instance in the class dict to the name of the attribute.
190 2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
190 2. Sets the :attr:`this_class` attribute of every :class:`TraitType`
191 instance in the class dict to the *class* that declared the trait.
191 instance in the class dict to the *class* that declared the trait.
192 This is used by the :class:`This` trait to allow subclasses to
192 This is used by the :class:`This` trait to allow subclasses to
193 accept superclasses for :class:`This` values.
193 accept superclasses for :class:`This` values.
194 """
194 """
195
195
196
196
197 metadata = {}
197 metadata = {}
198 default_value = Undefined
198 default_value = Undefined
199 info_text = 'any value'
199 info_text = 'any value'
200
200
201 def __init__(self, default_value=NoDefaultSpecified, **metadata):
201 def __init__(self, default_value=NoDefaultSpecified, **metadata):
202 """Create a TraitType.
202 """Create a TraitType.
203 """
203 """
204 if default_value is not NoDefaultSpecified:
204 if default_value is not NoDefaultSpecified:
205 self.default_value = default_value
205 self.default_value = default_value
206
206
207 if len(metadata) > 0:
207 if len(metadata) > 0:
208 if len(self.metadata) > 0:
208 if len(self.metadata) > 0:
209 self._metadata = self.metadata.copy()
209 self._metadata = self.metadata.copy()
210 self._metadata.update(metadata)
210 self._metadata.update(metadata)
211 else:
211 else:
212 self._metadata = metadata
212 self._metadata = metadata
213 else:
213 else:
214 self._metadata = self.metadata
214 self._metadata = self.metadata
215
215
216 self.init()
216 self.init()
217
217
218 def init(self):
218 def init(self):
219 pass
219 pass
220
220
221 def get_default_value(self):
221 def get_default_value(self):
222 """Create a new instance of the default value."""
222 """Create a new instance of the default value."""
223 return self.default_value
223 return self.default_value
224
224
225 def instance_init(self, obj):
225 def instance_init(self, obj):
226 """This is called by :meth:`HasTraits.__new__` to finish init'ing.
226 """This is called by :meth:`HasTraits.__new__` to finish init'ing.
227
227
228 Some stages of initialization must be delayed until the parent
228 Some stages of initialization must be delayed until the parent
229 :class:`HasTraits` instance has been created. This method is
229 :class:`HasTraits` instance has been created. This method is
230 called in :meth:`HasTraits.__new__` after the instance has been
230 called in :meth:`HasTraits.__new__` after the instance has been
231 created.
231 created.
232
232
233 This method trigger the creation and validation of default values
233 This method trigger the creation and validation of default values
234 and also things like the resolution of str given class names in
234 and also things like the resolution of str given class names in
235 :class:`Type` and :class`Instance`.
235 :class:`Type` and :class`Instance`.
236
236
237 Parameters
237 Parameters
238 ----------
238 ----------
239 obj : :class:`HasTraits` instance
239 obj : :class:`HasTraits` instance
240 The parent :class:`HasTraits` instance that has just been
240 The parent :class:`HasTraits` instance that has just been
241 created.
241 created.
242 """
242 """
243 self.set_default_value(obj)
243 self.set_default_value(obj)
244
244
245 def set_default_value(self, obj):
245 def set_default_value(self, obj):
246 """Set the default value on a per instance basis.
246 """Set the default value on a per instance basis.
247
247
248 This method is called by :meth:`instance_init` to create and
248 This method is called by :meth:`instance_init` to create and
249 validate the default value. The creation and validation of
249 validate the default value. The creation and validation of
250 default values must be delayed until the parent :class:`HasTraits`
250 default values must be delayed until the parent :class:`HasTraits`
251 class has been instantiated.
251 class has been instantiated.
252 """
252 """
253 # Check for a deferred initializer defined in the same class as the
253 # Check for a deferred initializer defined in the same class as the
254 # trait declaration or above.
254 # trait declaration or above.
255 mro = type(obj).mro()
255 mro = type(obj).mro()
256 meth_name = '_%s_default' % self.name
256 meth_name = '_%s_default' % self.name
257 for cls in mro[:mro.index(self.this_class)+1]:
257 for cls in mro[:mro.index(self.this_class)+1]:
258 if meth_name in cls.__dict__:
258 if meth_name in cls.__dict__:
259 break
259 break
260 else:
260 else:
261 # We didn't find one. Do static initialization.
261 # We didn't find one. Do static initialization.
262 dv = self.get_default_value()
262 dv = self.get_default_value()
263 newdv = self._validate(obj, dv)
263 newdv = self._validate(obj, dv)
264 obj._trait_values[self.name] = newdv
264 obj._trait_values[self.name] = newdv
265 return
265 return
266 # Complete the dynamic initialization.
266 # Complete the dynamic initialization.
267 obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
267 obj._trait_dyn_inits[self.name] = cls.__dict__[meth_name]
268
268
269 def __get__(self, obj, cls=None):
269 def __get__(self, obj, cls=None):
270 """Get the value of the trait by self.name for the instance.
270 """Get the value of the trait by self.name for the instance.
271
271
272 Default values are instantiated when :meth:`HasTraits.__new__`
272 Default values are instantiated when :meth:`HasTraits.__new__`
273 is called. Thus by the time this method gets called either the
273 is called. Thus by the time this method gets called either the
274 default value or a user defined value (they called :meth:`__set__`)
274 default value or a user defined value (they called :meth:`__set__`)
275 is in the :class:`HasTraits` instance.
275 is in the :class:`HasTraits` instance.
276 """
276 """
277 if obj is None:
277 if obj is None:
278 return self
278 return self
279 else:
279 else:
280 try:
280 try:
281 value = obj._trait_values[self.name]
281 value = obj._trait_values[self.name]
282 except KeyError:
282 except KeyError:
283 # Check for a dynamic initializer.
283 # Check for a dynamic initializer.
284 if self.name in obj._trait_dyn_inits:
284 if self.name in obj._trait_dyn_inits:
285 value = obj._trait_dyn_inits[self.name](obj)
285 value = obj._trait_dyn_inits[self.name](obj)
286 # FIXME: Do we really validate here?
286 # FIXME: Do we really validate here?
287 value = self._validate(obj, value)
287 value = self._validate(obj, value)
288 obj._trait_values[self.name] = value
288 obj._trait_values[self.name] = value
289 return value
289 return value
290 else:
290 else:
291 raise TraitError('Unexpected error in TraitType: '
291 raise TraitError('Unexpected error in TraitType: '
292 'both default value and dynamic initializer are '
292 'both default value and dynamic initializer are '
293 'absent.')
293 'absent.')
294 except Exception:
294 except Exception:
295 # HasTraits should call set_default_value to populate
295 # HasTraits should call set_default_value to populate
296 # this. So this should never be reached.
296 # this. So this should never be reached.
297 raise TraitError('Unexpected error in TraitType: '
297 raise TraitError('Unexpected error in TraitType: '
298 'default value not set properly')
298 'default value not set properly')
299 else:
299 else:
300 return value
300 return value
301
301
302 def __set__(self, obj, value):
302 def __set__(self, obj, value):
303 new_value = self._validate(obj, value)
303 new_value = self._validate(obj, value)
304 old_value = self.__get__(obj)
304 old_value = self.__get__(obj)
305 if old_value != new_value:
305 if old_value != new_value:
306 obj._trait_values[self.name] = new_value
306 obj._trait_values[self.name] = new_value
307 obj._notify_trait(self.name, old_value, new_value)
307 obj._notify_trait(self.name, old_value, new_value)
308
308
309 def _validate(self, obj, value):
309 def _validate(self, obj, value):
310 if hasattr(self, 'validate'):
310 if hasattr(self, 'validate'):
311 return self.validate(obj, value)
311 return self.validate(obj, value)
312 elif hasattr(self, 'is_valid_for'):
312 elif hasattr(self, 'is_valid_for'):
313 valid = self.is_valid_for(value)
313 valid = self.is_valid_for(value)
314 if valid:
314 if valid:
315 return value
315 return value
316 else:
316 else:
317 raise TraitError('invalid value for type: %r' % value)
317 raise TraitError('invalid value for type: %r' % value)
318 elif hasattr(self, 'value_for'):
318 elif hasattr(self, 'value_for'):
319 return self.value_for(value)
319 return self.value_for(value)
320 else:
320 else:
321 return value
321 return value
322
322
323 def info(self):
323 def info(self):
324 return self.info_text
324 return self.info_text
325
325
326 def error(self, obj, value):
326 def error(self, obj, value):
327 if obj is not None:
327 if obj is not None:
328 e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
328 e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
329 % (self.name, class_of(obj),
329 % (self.name, class_of(obj),
330 self.info(), repr_type(value))
330 self.info(), repr_type(value))
331 else:
331 else:
332 e = "The '%s' trait must be %s, but a value of %r was specified." \
332 e = "The '%s' trait must be %s, but a value of %r was specified." \
333 % (self.name, self.info(), repr_type(value))
333 % (self.name, self.info(), repr_type(value))
334 raise TraitError(e)
334 raise TraitError(e)
335
335
336 def get_metadata(self, key):
336 def get_metadata(self, key):
337 return getattr(self, '_metadata', {}).get(key, None)
337 return getattr(self, '_metadata', {}).get(key, None)
338
338
339 def set_metadata(self, key, value):
339 def set_metadata(self, key, value):
340 getattr(self, '_metadata', {})[key] = value
340 getattr(self, '_metadata', {})[key] = value
341
341
342
342
343 #-----------------------------------------------------------------------------
343 #-----------------------------------------------------------------------------
344 # The HasTraits implementation
344 # The HasTraits implementation
345 #-----------------------------------------------------------------------------
345 #-----------------------------------------------------------------------------
346
346
347
347
348 class MetaHasTraits(type):
348 class MetaHasTraits(type):
349 """A metaclass for HasTraits.
349 """A metaclass for HasTraits.
350
350
351 This metaclass makes sure that any TraitType class attributes are
351 This metaclass makes sure that any TraitType class attributes are
352 instantiated and sets their name attribute.
352 instantiated and sets their name attribute.
353 """
353 """
354
354
355 def __new__(mcls, name, bases, classdict):
355 def __new__(mcls, name, bases, classdict):
356 """Create the HasTraits class.
356 """Create the HasTraits class.
357
357
358 This instantiates all TraitTypes in the class dict and sets their
358 This instantiates all TraitTypes in the class dict and sets their
359 :attr:`name` attribute.
359 :attr:`name` attribute.
360 """
360 """
361 # print "MetaHasTraitlets (mcls, name): ", mcls, name
361 # print "MetaHasTraitlets (mcls, name): ", mcls, name
362 # print "MetaHasTraitlets (bases): ", bases
362 # print "MetaHasTraitlets (bases): ", bases
363 # print "MetaHasTraitlets (classdict): ", classdict
363 # print "MetaHasTraitlets (classdict): ", classdict
364 for k,v in classdict.iteritems():
364 for k,v in classdict.iteritems():
365 if isinstance(v, TraitType):
365 if isinstance(v, TraitType):
366 v.name = k
366 v.name = k
367 elif inspect.isclass(v):
367 elif inspect.isclass(v):
368 if issubclass(v, TraitType):
368 if issubclass(v, TraitType):
369 vinst = v()
369 vinst = v()
370 vinst.name = k
370 vinst.name = k
371 classdict[k] = vinst
371 classdict[k] = vinst
372 return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
372 return super(MetaHasTraits, mcls).__new__(mcls, name, bases, classdict)
373
373
374 def __init__(cls, name, bases, classdict):
374 def __init__(cls, name, bases, classdict):
375 """Finish initializing the HasTraits class.
375 """Finish initializing the HasTraits class.
376
376
377 This sets the :attr:`this_class` attribute of each TraitType in the
377 This sets the :attr:`this_class` attribute of each TraitType in the
378 class dict to the newly created class ``cls``.
378 class dict to the newly created class ``cls``.
379 """
379 """
380 for k, v in classdict.iteritems():
380 for k, v in classdict.iteritems():
381 if isinstance(v, TraitType):
381 if isinstance(v, TraitType):
382 v.this_class = cls
382 v.this_class = cls
383 super(MetaHasTraits, cls).__init__(name, bases, classdict)
383 super(MetaHasTraits, cls).__init__(name, bases, classdict)
384
384
385 class HasTraits(object):
385 class HasTraits(object):
386
386
387 __metaclass__ = MetaHasTraits
387 __metaclass__ = MetaHasTraits
388
388
389 def __new__(cls, **kw):
389 def __new__(cls, **kw):
390 # This is needed because in Python 2.6 object.__new__ only accepts
390 # This is needed because in Python 2.6 object.__new__ only accepts
391 # the cls argument.
391 # the cls argument.
392 new_meth = super(HasTraits, cls).__new__
392 new_meth = super(HasTraits, cls).__new__
393 if new_meth is object.__new__:
393 if new_meth is object.__new__:
394 inst = new_meth(cls)
394 inst = new_meth(cls)
395 else:
395 else:
396 inst = new_meth(cls, **kw)
396 inst = new_meth(cls, **kw)
397 inst._trait_values = {}
397 inst._trait_values = {}
398 inst._trait_notifiers = {}
398 inst._trait_notifiers = {}
399 inst._trait_dyn_inits = {}
399 inst._trait_dyn_inits = {}
400 # Here we tell all the TraitType instances to set their default
400 # Here we tell all the TraitType instances to set their default
401 # values on the instance.
401 # values on the instance.
402 for key in dir(cls):
402 for key in dir(cls):
403 # Some descriptors raise AttributeError like zope.interface's
403 # Some descriptors raise AttributeError like zope.interface's
404 # __provides__ attributes even though they exist. This causes
404 # __provides__ attributes even though they exist. This causes
405 # AttributeErrors even though they are listed in dir(cls).
405 # AttributeErrors even though they are listed in dir(cls).
406 try:
406 try:
407 value = getattr(cls, key)
407 value = getattr(cls, key)
408 except AttributeError:
408 except AttributeError:
409 pass
409 pass
410 else:
410 else:
411 if isinstance(value, TraitType):
411 if isinstance(value, TraitType):
412 value.instance_init(inst)
412 value.instance_init(inst)
413
413
414 return inst
414 return inst
415
415
416 def __init__(self, **kw):
416 def __init__(self, **kw):
417 # Allow trait values to be set using keyword arguments.
417 # Allow trait values to be set using keyword arguments.
418 # We need to use setattr for this to trigger validation and
418 # We need to use setattr for this to trigger validation and
419 # notifications.
419 # notifications.
420 for key, value in kw.iteritems():
420 for key, value in kw.iteritems():
421 setattr(self, key, value)
421 setattr(self, key, value)
422
422
423 def _notify_trait(self, name, old_value, new_value):
423 def _notify_trait(self, name, old_value, new_value):
424
424
425 # First dynamic ones
425 # First dynamic ones
426 callables = self._trait_notifiers.get(name,[])
426 callables = self._trait_notifiers.get(name,[])
427 more_callables = self._trait_notifiers.get('anytrait',[])
427 more_callables = self._trait_notifiers.get('anytrait',[])
428 callables.extend(more_callables)
428 callables.extend(more_callables)
429
429
430 # Now static ones
430 # Now static ones
431 try:
431 try:
432 cb = getattr(self, '_%s_changed' % name)
432 cb = getattr(self, '_%s_changed' % name)
433 except:
433 except:
434 pass
434 pass
435 else:
435 else:
436 callables.append(cb)
436 callables.append(cb)
437
437
438 # Call them all now
438 # Call them all now
439 for c in callables:
439 for c in callables:
440 # Traits catches and logs errors here. I allow them to raise
440 # Traits catches and logs errors here. I allow them to raise
441 if callable(c):
441 if callable(c):
442 argspec = inspect.getargspec(c)
442 argspec = inspect.getargspec(c)
443 nargs = len(argspec[0])
443 nargs = len(argspec[0])
444 # Bound methods have an additional 'self' argument
444 # Bound methods have an additional 'self' argument
445 # I don't know how to treat unbound methods, but they
445 # I don't know how to treat unbound methods, but they
446 # can't really be used for callbacks.
446 # can't really be used for callbacks.
447 if isinstance(c, types.MethodType):
447 if isinstance(c, types.MethodType):
448 offset = -1
448 offset = -1
449 else:
449 else:
450 offset = 0
450 offset = 0
451 if nargs + offset == 0:
451 if nargs + offset == 0:
452 c()
452 c()
453 elif nargs + offset == 1:
453 elif nargs + offset == 1:
454 c(name)
454 c(name)
455 elif nargs + offset == 2:
455 elif nargs + offset == 2:
456 c(name, new_value)
456 c(name, new_value)
457 elif nargs + offset == 3:
457 elif nargs + offset == 3:
458 c(name, old_value, new_value)
458 c(name, old_value, new_value)
459 else:
459 else:
460 raise TraitError('a trait changed callback '
460 raise TraitError('a trait changed callback '
461 'must have 0-3 arguments.')
461 'must have 0-3 arguments.')
462 else:
462 else:
463 raise TraitError('a trait changed callback '
463 raise TraitError('a trait changed callback '
464 'must be callable.')
464 'must be callable.')
465
465
466
466
467 def _add_notifiers(self, handler, name):
467 def _add_notifiers(self, handler, name):
468 if not self._trait_notifiers.has_key(name):
468 if not self._trait_notifiers.has_key(name):
469 nlist = []
469 nlist = []
470 self._trait_notifiers[name] = nlist
470 self._trait_notifiers[name] = nlist
471 else:
471 else:
472 nlist = self._trait_notifiers[name]
472 nlist = self._trait_notifiers[name]
473 if handler not in nlist:
473 if handler not in nlist:
474 nlist.append(handler)
474 nlist.append(handler)
475
475
476 def _remove_notifiers(self, handler, name):
476 def _remove_notifiers(self, handler, name):
477 if self._trait_notifiers.has_key(name):
477 if self._trait_notifiers.has_key(name):
478 nlist = self._trait_notifiers[name]
478 nlist = self._trait_notifiers[name]
479 try:
479 try:
480 index = nlist.index(handler)
480 index = nlist.index(handler)
481 except ValueError:
481 except ValueError:
482 pass
482 pass
483 else:
483 else:
484 del nlist[index]
484 del nlist[index]
485
485
486 def on_trait_change(self, handler, name=None, remove=False):
486 def on_trait_change(self, handler, name=None, remove=False):
487 """Setup a handler to be called when a trait changes.
487 """Setup a handler to be called when a trait changes.
488
488
489 This is used to setup dynamic notifications of trait changes.
489 This is used to setup dynamic notifications of trait changes.
490
490
491 Static handlers can be created by creating methods on a HasTraits
491 Static handlers can be created by creating methods on a HasTraits
492 subclass with the naming convention '_[traitname]_changed'. Thus,
492 subclass with the naming convention '_[traitname]_changed'. Thus,
493 to create static handler for the trait 'a', create the method
493 to create static handler for the trait 'a', create the method
494 _a_changed(self, name, old, new) (fewer arguments can be used, see
494 _a_changed(self, name, old, new) (fewer arguments can be used, see
495 below).
495 below).
496
496
497 Parameters
497 Parameters
498 ----------
498 ----------
499 handler : callable
499 handler : callable
500 A callable that is called when a trait changes. Its
500 A callable that is called when a trait changes. Its
501 signature can be handler(), handler(name), handler(name, new)
501 signature can be handler(), handler(name), handler(name, new)
502 or handler(name, old, new).
502 or handler(name, old, new).
503 name : list, str, None
503 name : list, str, None
504 If None, the handler will apply to all traits. If a list
504 If None, the handler will apply to all traits. If a list
505 of str, handler will apply to all names in the list. If a
505 of str, handler will apply to all names in the list. If a
506 str, the handler will apply just to that name.
506 str, the handler will apply just to that name.
507 remove : bool
507 remove : bool
508 If False (the default), then install the handler. If True
508 If False (the default), then install the handler. If True
509 then unintall it.
509 then unintall it.
510 """
510 """
511 if remove:
511 if remove:
512 names = parse_notifier_name(name)
512 names = parse_notifier_name(name)
513 for n in names:
513 for n in names:
514 self._remove_notifiers(handler, n)
514 self._remove_notifiers(handler, n)
515 else:
515 else:
516 names = parse_notifier_name(name)
516 names = parse_notifier_name(name)
517 for n in names:
517 for n in names:
518 self._add_notifiers(handler, n)
518 self._add_notifiers(handler, n)
519
519
520 @classmethod
520 @classmethod
521 def class_trait_names(cls, **metadata):
521 def class_trait_names(cls, **metadata):
522 """Get a list of all the names of this classes traits.
522 """Get a list of all the names of this classes traits.
523
523
524 This method is just like the :meth:`trait_names` method, but is unbound.
524 This method is just like the :meth:`trait_names` method, but is unbound.
525 """
525 """
526 return cls.class_traits(**metadata).keys()
526 return cls.class_traits(**metadata).keys()
527
527
528 @classmethod
528 @classmethod
529 def class_traits(cls, **metadata):
529 def class_traits(cls, **metadata):
530 """Get a list of all the traits of this class.
530 """Get a list of all the traits of this class.
531
531
532 This method is just like the :meth:`traits` method, but is unbound.
532 This method is just like the :meth:`traits` method, but is unbound.
533
533
534 The TraitTypes returned don't know anything about the values
534 The TraitTypes returned don't know anything about the values
535 that the various HasTrait's instances are holding.
535 that the various HasTrait's instances are holding.
536
536
537 This follows the same algorithm as traits does and does not allow
537 This follows the same algorithm as traits does and does not allow
538 for any simple way of specifying merely that a metadata name
538 for any simple way of specifying merely that a metadata name
539 exists, but has any value. This is because get_metadata returns
539 exists, but has any value. This is because get_metadata returns
540 None if a metadata key doesn't exist.
540 None if a metadata key doesn't exist.
541 """
541 """
542 traits = dict([memb for memb in getmembers(cls) if \
542 traits = dict([memb for memb in getmembers(cls) if \
543 isinstance(memb[1], TraitType)])
543 isinstance(memb[1], TraitType)])
544
544
545 if len(metadata) == 0:
545 if len(metadata) == 0:
546 return traits
546 return traits
547
547
548 for meta_name, meta_eval in metadata.items():
548 for meta_name, meta_eval in metadata.items():
549 if type(meta_eval) is not FunctionType:
549 if type(meta_eval) is not FunctionType:
550 metadata[meta_name] = _SimpleTest(meta_eval)
550 metadata[meta_name] = _SimpleTest(meta_eval)
551
551
552 result = {}
552 result = {}
553 for name, trait in traits.items():
553 for name, trait in traits.items():
554 for meta_name, meta_eval in metadata.items():
554 for meta_name, meta_eval in metadata.items():
555 if not meta_eval(trait.get_metadata(meta_name)):
555 if not meta_eval(trait.get_metadata(meta_name)):
556 break
556 break
557 else:
557 else:
558 result[name] = trait
558 result[name] = trait
559
559
560 return result
560 return result
561
561
562 def trait_names(self, **metadata):
562 def trait_names(self, **metadata):
563 """Get a list of all the names of this classes traits."""
563 """Get a list of all the names of this classes traits."""
564 return self.traits(**metadata).keys()
564 return self.traits(**metadata).keys()
565
565
566 def traits(self, **metadata):
566 def traits(self, **metadata):
567 """Get a list of all the traits of this class.
567 """Get a list of all the traits of this class.
568
568
569 The TraitTypes returned don't know anything about the values
569 The TraitTypes returned don't know anything about the values
570 that the various HasTrait's instances are holding.
570 that the various HasTrait's instances are holding.
571
571
572 This follows the same algorithm as traits does and does not allow
572 This follows the same algorithm as traits does and does not allow
573 for any simple way of specifying merely that a metadata name
573 for any simple way of specifying merely that a metadata name
574 exists, but has any value. This is because get_metadata returns
574 exists, but has any value. This is because get_metadata returns
575 None if a metadata key doesn't exist.
575 None if a metadata key doesn't exist.
576 """
576 """
577 traits = dict([memb for memb in getmembers(self.__class__) if \
577 traits = dict([memb for memb in getmembers(self.__class__) if \
578 isinstance(memb[1], TraitType)])
578 isinstance(memb[1], TraitType)])
579
579
580 if len(metadata) == 0:
580 if len(metadata) == 0:
581 return traits
581 return traits
582
582
583 for meta_name, meta_eval in metadata.items():
583 for meta_name, meta_eval in metadata.items():
584 if type(meta_eval) is not FunctionType:
584 if type(meta_eval) is not FunctionType:
585 metadata[meta_name] = _SimpleTest(meta_eval)
585 metadata[meta_name] = _SimpleTest(meta_eval)
586
586
587 result = {}
587 result = {}
588 for name, trait in traits.items():
588 for name, trait in traits.items():
589 for meta_name, meta_eval in metadata.items():
589 for meta_name, meta_eval in metadata.items():
590 if not meta_eval(trait.get_metadata(meta_name)):
590 if not meta_eval(trait.get_metadata(meta_name)):
591 break
591 break
592 else:
592 else:
593 result[name] = trait
593 result[name] = trait
594
594
595 return result
595 return result
596
596
597 def trait_metadata(self, traitname, key):
597 def trait_metadata(self, traitname, key):
598 """Get metadata values for trait by key."""
598 """Get metadata values for trait by key."""
599 try:
599 try:
600 trait = getattr(self.__class__, traitname)
600 trait = getattr(self.__class__, traitname)
601 except AttributeError:
601 except AttributeError:
602 raise TraitError("Class %s does not have a trait named %s" %
602 raise TraitError("Class %s does not have a trait named %s" %
603 (self.__class__.__name__, traitname))
603 (self.__class__.__name__, traitname))
604 else:
604 else:
605 return trait.get_metadata(key)
605 return trait.get_metadata(key)
606
606
607 #-----------------------------------------------------------------------------
607 #-----------------------------------------------------------------------------
608 # Actual TraitTypes implementations/subclasses
608 # Actual TraitTypes implementations/subclasses
609 #-----------------------------------------------------------------------------
609 #-----------------------------------------------------------------------------
610
610
611 #-----------------------------------------------------------------------------
611 #-----------------------------------------------------------------------------
612 # TraitTypes subclasses for handling classes and instances of classes
612 # TraitTypes subclasses for handling classes and instances of classes
613 #-----------------------------------------------------------------------------
613 #-----------------------------------------------------------------------------
614
614
615
615
616 class ClassBasedTraitType(TraitType):
616 class ClassBasedTraitType(TraitType):
617 """A trait with error reporting for Type, Instance and This."""
617 """A trait with error reporting for Type, Instance and This."""
618
618
619 def error(self, obj, value):
619 def error(self, obj, value):
620 kind = type(value)
620 kind = type(value)
621 if (not py3compat.PY3) and kind is InstanceType:
621 if (not py3compat.PY3) and kind is InstanceType:
622 msg = 'class %s' % value.__class__.__name__
622 msg = 'class %s' % value.__class__.__name__
623 else:
623 else:
624 msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
624 msg = '%s (i.e. %s)' % ( str( kind )[1:-1], repr( value ) )
625
625
626 if obj is not None:
626 if obj is not None:
627 e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
627 e = "The '%s' trait of %s instance must be %s, but a value of %s was specified." \
628 % (self.name, class_of(obj),
628 % (self.name, class_of(obj),
629 self.info(), msg)
629 self.info(), msg)
630 else:
630 else:
631 e = "The '%s' trait must be %s, but a value of %r was specified." \
631 e = "The '%s' trait must be %s, but a value of %r was specified." \
632 % (self.name, self.info(), msg)
632 % (self.name, self.info(), msg)
633
633
634 raise TraitError(e)
634 raise TraitError(e)
635
635
636
636
637 class Type(ClassBasedTraitType):
637 class Type(ClassBasedTraitType):
638 """A trait whose value must be a subclass of a specified class."""
638 """A trait whose value must be a subclass of a specified class."""
639
639
640 def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
640 def __init__ (self, default_value=None, klass=None, allow_none=True, **metadata ):
641 """Construct a Type trait
641 """Construct a Type trait
642
642
643 A Type trait specifies that its values must be subclasses of
643 A Type trait specifies that its values must be subclasses of
644 a particular class.
644 a particular class.
645
645
646 If only ``default_value`` is given, it is used for the ``klass`` as
646 If only ``default_value`` is given, it is used for the ``klass`` as
647 well.
647 well.
648
648
649 Parameters
649 Parameters
650 ----------
650 ----------
651 default_value : class, str or None
651 default_value : class, str or None
652 The default value must be a subclass of klass. If an str,
652 The default value must be a subclass of klass. If an str,
653 the str must be a fully specified class name, like 'foo.bar.Bah'.
653 the str must be a fully specified class name, like 'foo.bar.Bah'.
654 The string is resolved into real class, when the parent
654 The string is resolved into real class, when the parent
655 :class:`HasTraits` class is instantiated.
655 :class:`HasTraits` class is instantiated.
656 klass : class, str, None
656 klass : class, str, None
657 Values of this trait must be a subclass of klass. The klass
657 Values of this trait must be a subclass of klass. The klass
658 may be specified in a string like: 'foo.bar.MyClass'.
658 may be specified in a string like: 'foo.bar.MyClass'.
659 The string is resolved into real class, when the parent
659 The string is resolved into real class, when the parent
660 :class:`HasTraits` class is instantiated.
660 :class:`HasTraits` class is instantiated.
661 allow_none : boolean
661 allow_none : boolean
662 Indicates whether None is allowed as an assignable value. Even if
662 Indicates whether None is allowed as an assignable value. Even if
663 ``False``, the default value may be ``None``.
663 ``False``, the default value may be ``None``.
664 """
664 """
665 if default_value is None:
665 if default_value is None:
666 if klass is None:
666 if klass is None:
667 klass = object
667 klass = object
668 elif klass is None:
668 elif klass is None:
669 klass = default_value
669 klass = default_value
670
670
671 if not (inspect.isclass(klass) or isinstance(klass, basestring)):
671 if not (inspect.isclass(klass) or isinstance(klass, basestring)):
672 raise TraitError("A Type trait must specify a class.")
672 raise TraitError("A Type trait must specify a class.")
673
673
674 self.klass = klass
674 self.klass = klass
675 self._allow_none = allow_none
675 self._allow_none = allow_none
676
676
677 super(Type, self).__init__(default_value, **metadata)
677 super(Type, self).__init__(default_value, **metadata)
678
678
679 def validate(self, obj, value):
679 def validate(self, obj, value):
680 """Validates that the value is a valid object instance."""
680 """Validates that the value is a valid object instance."""
681 try:
681 try:
682 if issubclass(value, self.klass):
682 if issubclass(value, self.klass):
683 return value
683 return value
684 except:
684 except:
685 if (value is None) and (self._allow_none):
685 if (value is None) and (self._allow_none):
686 return value
686 return value
687
687
688 self.error(obj, value)
688 self.error(obj, value)
689
689
690 def info(self):
690 def info(self):
691 """ Returns a description of the trait."""
691 """ Returns a description of the trait."""
692 if isinstance(self.klass, basestring):
692 if isinstance(self.klass, basestring):
693 klass = self.klass
693 klass = self.klass
694 else:
694 else:
695 klass = self.klass.__name__
695 klass = self.klass.__name__
696 result = 'a subclass of ' + klass
696 result = 'a subclass of ' + klass
697 if self._allow_none:
697 if self._allow_none:
698 return result + ' or None'
698 return result + ' or None'
699 return result
699 return result
700
700
701 def instance_init(self, obj):
701 def instance_init(self, obj):
702 self._resolve_classes()
702 self._resolve_classes()
703 super(Type, self).instance_init(obj)
703 super(Type, self).instance_init(obj)
704
704
705 def _resolve_classes(self):
705 def _resolve_classes(self):
706 if isinstance(self.klass, basestring):
706 if isinstance(self.klass, basestring):
707 self.klass = import_item(self.klass)
707 self.klass = import_item(self.klass)
708 if isinstance(self.default_value, basestring):
708 if isinstance(self.default_value, basestring):
709 self.default_value = import_item(self.default_value)
709 self.default_value = import_item(self.default_value)
710
710
711 def get_default_value(self):
711 def get_default_value(self):
712 return self.default_value
712 return self.default_value
713
713
714
714
715 class DefaultValueGenerator(object):
715 class DefaultValueGenerator(object):
716 """A class for generating new default value instances."""
716 """A class for generating new default value instances."""
717
717
718 def __init__(self, *args, **kw):
718 def __init__(self, *args, **kw):
719 self.args = args
719 self.args = args
720 self.kw = kw
720 self.kw = kw
721
721
722 def generate(self, klass):
722 def generate(self, klass):
723 return klass(*self.args, **self.kw)
723 return klass(*self.args, **self.kw)
724
724
725
725
726 class Instance(ClassBasedTraitType):
726 class Instance(ClassBasedTraitType):
727 """A trait whose value must be an instance of a specified class.
727 """A trait whose value must be an instance of a specified class.
728
728
729 The value can also be an instance of a subclass of the specified class.
729 The value can also be an instance of a subclass of the specified class.
730 """
730 """
731
731
732 def __init__(self, klass=None, args=None, kw=None,
732 def __init__(self, klass=None, args=None, kw=None,
733 allow_none=True, **metadata ):
733 allow_none=True, **metadata ):
734 """Construct an Instance trait.
734 """Construct an Instance trait.
735
735
736 This trait allows values that are instances of a particular
736 This trait allows values that are instances of a particular
737 class or its sublclasses. Our implementation is quite different
737 class or its sublclasses. Our implementation is quite different
738 from that of enthough.traits as we don't allow instances to be used
738 from that of enthough.traits as we don't allow instances to be used
739 for klass and we handle the ``args`` and ``kw`` arguments differently.
739 for klass and we handle the ``args`` and ``kw`` arguments differently.
740
740
741 Parameters
741 Parameters
742 ----------
742 ----------
743 klass : class, str
743 klass : class, str
744 The class that forms the basis for the trait. Class names
744 The class that forms the basis for the trait. Class names
745 can also be specified as strings, like 'foo.bar.Bar'.
745 can also be specified as strings, like 'foo.bar.Bar'.
746 args : tuple
746 args : tuple
747 Positional arguments for generating the default value.
747 Positional arguments for generating the default value.
748 kw : dict
748 kw : dict
749 Keyword arguments for generating the default value.
749 Keyword arguments for generating the default value.
750 allow_none : bool
750 allow_none : bool
751 Indicates whether None is allowed as a value.
751 Indicates whether None is allowed as a value.
752
752
753 Default Value
753 Default Value
754 -------------
754 -------------
755 If both ``args`` and ``kw`` are None, then the default value is None.
755 If both ``args`` and ``kw`` are None, then the default value is None.
756 If ``args`` is a tuple and ``kw`` is a dict, then the default is
756 If ``args`` is a tuple and ``kw`` is a dict, then the default is
757 created as ``klass(*args, **kw)``. If either ``args`` or ``kw`` is
757 created as ``klass(*args, **kw)``. If either ``args`` or ``kw`` is
758 not (but not both), None is replace by ``()`` or ``{}``.
758 not (but not both), None is replace by ``()`` or ``{}``.
759 """
759 """
760
760
761 self._allow_none = allow_none
761 self._allow_none = allow_none
762
762
763 if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
763 if (klass is None) or (not (inspect.isclass(klass) or isinstance(klass, basestring))):
764 raise TraitError('The klass argument must be a class'
764 raise TraitError('The klass argument must be a class'
765 ' you gave: %r' % klass)
765 ' you gave: %r' % klass)
766 self.klass = klass
766 self.klass = klass
767
767
768 # self.klass is a class, so handle default_value
768 # self.klass is a class, so handle default_value
769 if args is None and kw is None:
769 if args is None and kw is None:
770 default_value = None
770 default_value = None
771 else:
771 else:
772 if args is None:
772 if args is None:
773 # kw is not None
773 # kw is not None
774 args = ()
774 args = ()
775 elif kw is None:
775 elif kw is None:
776 # args is not None
776 # args is not None
777 kw = {}
777 kw = {}
778
778
779 if not isinstance(kw, dict):
779 if not isinstance(kw, dict):
780 raise TraitError("The 'kw' argument must be a dict or None.")
780 raise TraitError("The 'kw' argument must be a dict or None.")
781 if not isinstance(args, tuple):
781 if not isinstance(args, tuple):
782 raise TraitError("The 'args' argument must be a tuple or None.")
782 raise TraitError("The 'args' argument must be a tuple or None.")
783
783
784 default_value = DefaultValueGenerator(*args, **kw)
784 default_value = DefaultValueGenerator(*args, **kw)
785
785
786 super(Instance, self).__init__(default_value, **metadata)
786 super(Instance, self).__init__(default_value, **metadata)
787
787
788 def validate(self, obj, value):
788 def validate(self, obj, value):
789 if value is None:
789 if value is None:
790 if self._allow_none:
790 if self._allow_none:
791 return value
791 return value
792 self.error(obj, value)
792 self.error(obj, value)
793
793
794 if isinstance(value, self.klass):
794 if isinstance(value, self.klass):
795 return value
795 return value
796 else:
796 else:
797 self.error(obj, value)
797 self.error(obj, value)
798
798
799 def info(self):
799 def info(self):
800 if isinstance(self.klass, basestring):
800 if isinstance(self.klass, basestring):
801 klass = self.klass
801 klass = self.klass
802 else:
802 else:
803 klass = self.klass.__name__
803 klass = self.klass.__name__
804 result = class_of(klass)
804 result = class_of(klass)
805 if self._allow_none:
805 if self._allow_none:
806 return result + ' or None'
806 return result + ' or None'
807
807
808 return result
808 return result
809
809
810 def instance_init(self, obj):
810 def instance_init(self, obj):
811 self._resolve_classes()
811 self._resolve_classes()
812 super(Instance, self).instance_init(obj)
812 super(Instance, self).instance_init(obj)
813
813
814 def _resolve_classes(self):
814 def _resolve_classes(self):
815 if isinstance(self.klass, basestring):
815 if isinstance(self.klass, basestring):
816 self.klass = import_item(self.klass)
816 self.klass = import_item(self.klass)
817
817
818 def get_default_value(self):
818 def get_default_value(self):
819 """Instantiate a default value instance.
819 """Instantiate a default value instance.
820
820
821 This is called when the containing HasTraits classes'
821 This is called when the containing HasTraits classes'
822 :meth:`__new__` method is called to ensure that a unique instance
822 :meth:`__new__` method is called to ensure that a unique instance
823 is created for each HasTraits instance.
823 is created for each HasTraits instance.
824 """
824 """
825 dv = self.default_value
825 dv = self.default_value
826 if isinstance(dv, DefaultValueGenerator):
826 if isinstance(dv, DefaultValueGenerator):
827 return dv.generate(self.klass)
827 return dv.generate(self.klass)
828 else:
828 else:
829 return dv
829 return dv
830
830
831
831
832 class This(ClassBasedTraitType):
832 class This(ClassBasedTraitType):
833 """A trait for instances of the class containing this trait.
833 """A trait for instances of the class containing this trait.
834
834
835 Because how how and when class bodies are executed, the ``This``
835 Because how how and when class bodies are executed, the ``This``
836 trait can only have a default value of None. This, and because we
836 trait can only have a default value of None. This, and because we
837 always validate default values, ``allow_none`` is *always* true.
837 always validate default values, ``allow_none`` is *always* true.
838 """
838 """
839
839
840 info_text = 'an instance of the same type as the receiver or None'
840 info_text = 'an instance of the same type as the receiver or None'
841
841
842 def __init__(self, **metadata):
842 def __init__(self, **metadata):
843 super(This, self).__init__(None, **metadata)
843 super(This, self).__init__(None, **metadata)
844
844
845 def validate(self, obj, value):
845 def validate(self, obj, value):
846 # What if value is a superclass of obj.__class__? This is
846 # What if value is a superclass of obj.__class__? This is
847 # complicated if it was the superclass that defined the This
847 # complicated if it was the superclass that defined the This
848 # trait.
848 # trait.
849 if isinstance(value, self.this_class) or (value is None):
849 if isinstance(value, self.this_class) or (value is None):
850 return value
850 return value
851 else:
851 else:
852 self.error(obj, value)
852 self.error(obj, value)
853
853
854
854
855 #-----------------------------------------------------------------------------
855 #-----------------------------------------------------------------------------
856 # Basic TraitTypes implementations/subclasses
856 # Basic TraitTypes implementations/subclasses
857 #-----------------------------------------------------------------------------
857 #-----------------------------------------------------------------------------
858
858
859
859
860 class Any(TraitType):
860 class Any(TraitType):
861 default_value = None
861 default_value = None
862 info_text = 'any value'
862 info_text = 'any value'
863
863
864
864
865 class Int(TraitType):
865 class Int(TraitType):
866 """A integer trait."""
866 """A integer trait."""
867
867
868 default_value = 0
868 default_value = 0
869 info_text = 'an integer'
869 info_text = 'an integer'
870
870
871 def validate(self, obj, value):
871 def validate(self, obj, value):
872 if isinstance(value, int):
872 if isinstance(value, int):
873 return value
873 return value
874 self.error(obj, value)
874 self.error(obj, value)
875
875
876 class CInt(Int):
876 class CInt(Int):
877 """A casting version of the int trait."""
877 """A casting version of the int trait."""
878
878
879 def validate(self, obj, value):
879 def validate(self, obj, value):
880 try:
880 try:
881 return int(value)
881 return int(value)
882 except:
882 except:
883 self.error(obj, value)
883 self.error(obj, value)
884
884
885 if not py3compat.PY3:
885 if not py3compat.PY3:
886 class Long(TraitType):
886 class Long(TraitType):
887 """A long integer trait."""
887 """A long integer trait."""
888
888
889 default_value = 0L
889 default_value = 0L
890 info_text = 'a long'
890 info_text = 'a long'
891
891
892 def validate(self, obj, value):
892 def validate(self, obj, value):
893 if isinstance(value, long):
893 if isinstance(value, long):
894 return value
894 return value
895 if isinstance(value, int):
895 if isinstance(value, int):
896 return long(value)
896 return long(value)
897 self.error(obj, value)
897 self.error(obj, value)
898
898
899
899
900 class CLong(Long):
900 class CLong(Long):
901 """A casting version of the long integer trait."""
901 """A casting version of the long integer trait."""
902
902
903 def validate(self, obj, value):
903 def validate(self, obj, value):
904 try:
904 try:
905 return long(value)
905 return long(value)
906 except:
906 except:
907 self.error(obj, value)
907 self.error(obj, value)
908
908
909
909
910 class Float(TraitType):
910 class Float(TraitType):
911 """A float trait."""
911 """A float trait."""
912
912
913 default_value = 0.0
913 default_value = 0.0
914 info_text = 'a float'
914 info_text = 'a float'
915
915
916 def validate(self, obj, value):
916 def validate(self, obj, value):
917 if isinstance(value, float):
917 if isinstance(value, float):
918 return value
918 return value
919 if isinstance(value, int):
919 if isinstance(value, int):
920 return float(value)
920 return float(value)
921 self.error(obj, value)
921 self.error(obj, value)
922
922
923
923
924 class CFloat(Float):
924 class CFloat(Float):
925 """A casting version of the float trait."""
925 """A casting version of the float trait."""
926
926
927 def validate(self, obj, value):
927 def validate(self, obj, value):
928 try:
928 try:
929 return float(value)
929 return float(value)
930 except:
930 except:
931 self.error(obj, value)
931 self.error(obj, value)
932
932
933 class Complex(TraitType):
933 class Complex(TraitType):
934 """A trait for complex numbers."""
934 """A trait for complex numbers."""
935
935
936 default_value = 0.0 + 0.0j
936 default_value = 0.0 + 0.0j
937 info_text = 'a complex number'
937 info_text = 'a complex number'
938
938
939 def validate(self, obj, value):
939 def validate(self, obj, value):
940 if isinstance(value, complex):
940 if isinstance(value, complex):
941 return value
941 return value
942 if isinstance(value, (float, int)):
942 if isinstance(value, (float, int)):
943 return complex(value)
943 return complex(value)
944 self.error(obj, value)
944 self.error(obj, value)
945
945
946
946
947 class CComplex(Complex):
947 class CComplex(Complex):
948 """A casting version of the complex number trait."""
948 """A casting version of the complex number trait."""
949
949
950 def validate (self, obj, value):
950 def validate (self, obj, value):
951 try:
951 try:
952 return complex(value)
952 return complex(value)
953 except:
953 except:
954 self.error(obj, value)
954 self.error(obj, value)
955
955
956 # We should always be explicit about whether we're using bytes or unicode, both
956 # We should always be explicit about whether we're using bytes or unicode, both
957 # for Python 3 conversion and for reliable unicode behaviour on Python 2. So
957 # for Python 3 conversion and for reliable unicode behaviour on Python 2. So
958 # we don't have a Str type.
958 # we don't have a Str type.
959 class Bytes(TraitType):
959 class Bytes(TraitType):
960 """A trait for byte strings."""
960 """A trait for byte strings."""
961
961
962 default_value = ''
962 default_value = ''
963 info_text = 'a string'
963 info_text = 'a string'
964
964
965 def validate(self, obj, value):
965 def validate(self, obj, value):
966 if isinstance(value, bytes):
966 if isinstance(value, bytes):
967 return value
967 return value
968 self.error(obj, value)
968 self.error(obj, value)
969
969
970
970
971 class CBytes(Bytes):
971 class CBytes(Bytes):
972 """A casting version of the byte string trait."""
972 """A casting version of the byte string trait."""
973
973
974 def validate(self, obj, value):
974 def validate(self, obj, value):
975 try:
975 try:
976 return bytes(value)
976 return bytes(value)
977 except:
977 except:
978 self.error(obj, value)
978 self.error(obj, value)
979
979
980
980
981 class Unicode(TraitType):
981 class Unicode(TraitType):
982 """A trait for unicode strings."""
982 """A trait for unicode strings."""
983
983
984 default_value = u''
984 default_value = u''
985 info_text = 'a unicode string'
985 info_text = 'a unicode string'
986
986
987 def validate(self, obj, value):
987 def validate(self, obj, value):
988 if isinstance(value, unicode):
988 if isinstance(value, unicode):
989 return value
989 return value
990 if isinstance(value, bytes):
990 if isinstance(value, bytes):
991 return unicode(value)
991 return unicode(value)
992 self.error(obj, value)
992 self.error(obj, value)
993
993
994
994
995 class CUnicode(Unicode):
995 class CUnicode(Unicode):
996 """A casting version of the unicode trait."""
996 """A casting version of the unicode trait."""
997
997
998 def validate(self, obj, value):
998 def validate(self, obj, value):
999 try:
999 try:
1000 return unicode(value)
1000 return unicode(value)
1001 except:
1001 except:
1002 self.error(obj, value)
1002 self.error(obj, value)
1003
1003
1004
1004
1005 class ObjectName(TraitType):
1005 class ObjectName(TraitType):
1006 """A string holding a valid object name in this version of Python.
1006 """A string holding a valid object name in this version of Python.
1007
1007
1008 This does not check that the name exists in any scope."""
1008 This does not check that the name exists in any scope."""
1009 info_text = "a valid object identifier in Python"
1009 info_text = "a valid object identifier in Python"
1010
1010
1011 if sys.version_info[0] < 3:
1011 if py3compat.PY3:
1012 # Python 2:
1012 # Python 3:
1013 _name_re = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*$")
1013 coerce_str = staticmethod(lambda _,s: s)
1014 def isidentifier(self, s):
1015 return bool(self._name_re.match(s))
1016
1014
1015 else:
1016 # Python 2:
1017 def coerce_str(self, obj, value):
1017 def coerce_str(self, obj, value):
1018 "In Python 2, coerce ascii-only unicode to str"
1018 "In Python 2, coerce ascii-only unicode to str"
1019 if isinstance(value, unicode):
1019 if isinstance(value, unicode):
1020 try:
1020 try:
1021 return str(value)
1021 return str(value)
1022 except UnicodeEncodeError:
1022 except UnicodeEncodeError:
1023 self.error(obj, value)
1023 self.error(obj, value)
1024 return value
1024 return value
1025
1025
1026 else:
1027 # Python 3:
1028 isidentifier = staticmethod(lambda s: s.isidentifier())
1029 coerce_str = staticmethod(lambda _,s: s)
1030
1031 def validate(self, obj, value):
1026 def validate(self, obj, value):
1032 value = self.coerce_str(obj, value)
1027 value = self.coerce_str(obj, value)
1033
1028
1034 if isinstance(value, str) and self.isidentifier(value):
1029 if isinstance(value, str) and py3compat.isidentifier(value):
1035 return value
1030 return value
1036 self.error(obj, value)
1031 self.error(obj, value)
1037
1032
1038 class DottedObjectName(ObjectName):
1033 class DottedObjectName(ObjectName):
1039 """A string holding a valid dotted object name in Python, such as A.b3._c"""
1034 """A string holding a valid dotted object name in Python, such as A.b3._c"""
1040 def validate(self, obj, value):
1035 def validate(self, obj, value):
1041 value = self.coerce_str(obj, value)
1036 value = self.coerce_str(obj, value)
1042
1037
1043 if isinstance(value, str) and all(self.isidentifier(x) \
1038 if isinstance(value, str) and py3compat.isidentifier(value, dotted=True):
1044 for x in value.split('.')):
1045 return value
1039 return value
1046 self.error(obj, value)
1040 self.error(obj, value)
1047
1041
1048
1042
1049 class Bool(TraitType):
1043 class Bool(TraitType):
1050 """A boolean (True, False) trait."""
1044 """A boolean (True, False) trait."""
1051
1045
1052 default_value = False
1046 default_value = False
1053 info_text = 'a boolean'
1047 info_text = 'a boolean'
1054
1048
1055 def validate(self, obj, value):
1049 def validate(self, obj, value):
1056 if isinstance(value, bool):
1050 if isinstance(value, bool):
1057 return value
1051 return value
1058 self.error(obj, value)
1052 self.error(obj, value)
1059
1053
1060
1054
1061 class CBool(Bool):
1055 class CBool(Bool):
1062 """A casting version of the boolean trait."""
1056 """A casting version of the boolean trait."""
1063
1057
1064 def validate(self, obj, value):
1058 def validate(self, obj, value):
1065 try:
1059 try:
1066 return bool(value)
1060 return bool(value)
1067 except:
1061 except:
1068 self.error(obj, value)
1062 self.error(obj, value)
1069
1063
1070
1064
1071 class Enum(TraitType):
1065 class Enum(TraitType):
1072 """An enum that whose value must be in a given sequence."""
1066 """An enum that whose value must be in a given sequence."""
1073
1067
1074 def __init__(self, values, default_value=None, allow_none=True, **metadata):
1068 def __init__(self, values, default_value=None, allow_none=True, **metadata):
1075 self.values = values
1069 self.values = values
1076 self._allow_none = allow_none
1070 self._allow_none = allow_none
1077 super(Enum, self).__init__(default_value, **metadata)
1071 super(Enum, self).__init__(default_value, **metadata)
1078
1072
1079 def validate(self, obj, value):
1073 def validate(self, obj, value):
1080 if value is None:
1074 if value is None:
1081 if self._allow_none:
1075 if self._allow_none:
1082 return value
1076 return value
1083
1077
1084 if value in self.values:
1078 if value in self.values:
1085 return value
1079 return value
1086 self.error(obj, value)
1080 self.error(obj, value)
1087
1081
1088 def info(self):
1082 def info(self):
1089 """ Returns a description of the trait."""
1083 """ Returns a description of the trait."""
1090 result = 'any of ' + repr(self.values)
1084 result = 'any of ' + repr(self.values)
1091 if self._allow_none:
1085 if self._allow_none:
1092 return result + ' or None'
1086 return result + ' or None'
1093 return result
1087 return result
1094
1088
1095 class CaselessStrEnum(Enum):
1089 class CaselessStrEnum(Enum):
1096 """An enum of strings that are caseless in validate."""
1090 """An enum of strings that are caseless in validate."""
1097
1091
1098 def validate(self, obj, value):
1092 def validate(self, obj, value):
1099 if value is None:
1093 if value is None:
1100 if self._allow_none:
1094 if self._allow_none:
1101 return value
1095 return value
1102
1096
1103 if not isinstance(value, basestring):
1097 if not isinstance(value, basestring):
1104 self.error(obj, value)
1098 self.error(obj, value)
1105
1099
1106 for v in self.values:
1100 for v in self.values:
1107 if v.lower() == value.lower():
1101 if v.lower() == value.lower():
1108 return v
1102 return v
1109 self.error(obj, value)
1103 self.error(obj, value)
1110
1104
1111 class Container(Instance):
1105 class Container(Instance):
1112 """An instance of a container (list, set, etc.)
1106 """An instance of a container (list, set, etc.)
1113
1107
1114 To be subclassed by overriding klass.
1108 To be subclassed by overriding klass.
1115 """
1109 """
1116 klass = None
1110 klass = None
1117 _valid_defaults = SequenceTypes
1111 _valid_defaults = SequenceTypes
1118 _trait = None
1112 _trait = None
1119
1113
1120 def __init__(self, trait=None, default_value=None, allow_none=True,
1114 def __init__(self, trait=None, default_value=None, allow_none=True,
1121 **metadata):
1115 **metadata):
1122 """Create a container trait type from a list, set, or tuple.
1116 """Create a container trait type from a list, set, or tuple.
1123
1117
1124 The default value is created by doing ``List(default_value)``,
1118 The default value is created by doing ``List(default_value)``,
1125 which creates a copy of the ``default_value``.
1119 which creates a copy of the ``default_value``.
1126
1120
1127 ``trait`` can be specified, which restricts the type of elements
1121 ``trait`` can be specified, which restricts the type of elements
1128 in the container to that TraitType.
1122 in the container to that TraitType.
1129
1123
1130 If only one arg is given and it is not a Trait, it is taken as
1124 If only one arg is given and it is not a Trait, it is taken as
1131 ``default_value``:
1125 ``default_value``:
1132
1126
1133 ``c = List([1,2,3])``
1127 ``c = List([1,2,3])``
1134
1128
1135 Parameters
1129 Parameters
1136 ----------
1130 ----------
1137
1131
1138 trait : TraitType [ optional ]
1132 trait : TraitType [ optional ]
1139 the type for restricting the contents of the Container. If unspecified,
1133 the type for restricting the contents of the Container. If unspecified,
1140 types are not checked.
1134 types are not checked.
1141
1135
1142 default_value : SequenceType [ optional ]
1136 default_value : SequenceType [ optional ]
1143 The default value for the Trait. Must be list/tuple/set, and
1137 The default value for the Trait. Must be list/tuple/set, and
1144 will be cast to the container type.
1138 will be cast to the container type.
1145
1139
1146 allow_none : Bool [ default True ]
1140 allow_none : Bool [ default True ]
1147 Whether to allow the value to be None
1141 Whether to allow the value to be None
1148
1142
1149 **metadata : any
1143 **metadata : any
1150 further keys for extensions to the Trait (e.g. config)
1144 further keys for extensions to the Trait (e.g. config)
1151
1145
1152 """
1146 """
1153 istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
1147 istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
1154
1148
1155 # allow List([values]):
1149 # allow List([values]):
1156 if default_value is None and not istrait(trait):
1150 if default_value is None and not istrait(trait):
1157 default_value = trait
1151 default_value = trait
1158 trait = None
1152 trait = None
1159
1153
1160 if default_value is None:
1154 if default_value is None:
1161 args = ()
1155 args = ()
1162 elif isinstance(default_value, self._valid_defaults):
1156 elif isinstance(default_value, self._valid_defaults):
1163 args = (default_value,)
1157 args = (default_value,)
1164 else:
1158 else:
1165 raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
1159 raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
1166
1160
1167 if istrait(trait):
1161 if istrait(trait):
1168 self._trait = trait()
1162 self._trait = trait()
1169 self._trait.name = 'element'
1163 self._trait.name = 'element'
1170 elif trait is not None:
1164 elif trait is not None:
1171 raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait))
1165 raise TypeError("`trait` must be a Trait or None, got %s"%repr_type(trait))
1172
1166
1173 super(Container,self).__init__(klass=self.klass, args=args,
1167 super(Container,self).__init__(klass=self.klass, args=args,
1174 allow_none=allow_none, **metadata)
1168 allow_none=allow_none, **metadata)
1175
1169
1176 def element_error(self, obj, element, validator):
1170 def element_error(self, obj, element, validator):
1177 e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \
1171 e = "Element of the '%s' trait of %s instance must be %s, but a value of %s was specified." \
1178 % (self.name, class_of(obj), validator.info(), repr_type(element))
1172 % (self.name, class_of(obj), validator.info(), repr_type(element))
1179 raise TraitError(e)
1173 raise TraitError(e)
1180
1174
1181 def validate(self, obj, value):
1175 def validate(self, obj, value):
1182 value = super(Container, self).validate(obj, value)
1176 value = super(Container, self).validate(obj, value)
1183 if value is None:
1177 if value is None:
1184 return value
1178 return value
1185
1179
1186 value = self.validate_elements(obj, value)
1180 value = self.validate_elements(obj, value)
1187
1181
1188 return value
1182 return value
1189
1183
1190 def validate_elements(self, obj, value):
1184 def validate_elements(self, obj, value):
1191 validated = []
1185 validated = []
1192 if self._trait is None or isinstance(self._trait, Any):
1186 if self._trait is None or isinstance(self._trait, Any):
1193 return value
1187 return value
1194 for v in value:
1188 for v in value:
1195 try:
1189 try:
1196 v = self._trait.validate(obj, v)
1190 v = self._trait.validate(obj, v)
1197 except TraitError:
1191 except TraitError:
1198 self.element_error(obj, v, self._trait)
1192 self.element_error(obj, v, self._trait)
1199 else:
1193 else:
1200 validated.append(v)
1194 validated.append(v)
1201 return self.klass(validated)
1195 return self.klass(validated)
1202
1196
1203
1197
1204 class List(Container):
1198 class List(Container):
1205 """An instance of a Python list."""
1199 """An instance of a Python list."""
1206 klass = list
1200 klass = list
1207
1201
1208 def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxint,
1202 def __init__(self, trait=None, default_value=None, minlen=0, maxlen=sys.maxint,
1209 allow_none=True, **metadata):
1203 allow_none=True, **metadata):
1210 """Create a List trait type from a list, set, or tuple.
1204 """Create a List trait type from a list, set, or tuple.
1211
1205
1212 The default value is created by doing ``List(default_value)``,
1206 The default value is created by doing ``List(default_value)``,
1213 which creates a copy of the ``default_value``.
1207 which creates a copy of the ``default_value``.
1214
1208
1215 ``trait`` can be specified, which restricts the type of elements
1209 ``trait`` can be specified, which restricts the type of elements
1216 in the container to that TraitType.
1210 in the container to that TraitType.
1217
1211
1218 If only one arg is given and it is not a Trait, it is taken as
1212 If only one arg is given and it is not a Trait, it is taken as
1219 ``default_value``:
1213 ``default_value``:
1220
1214
1221 ``c = List([1,2,3])``
1215 ``c = List([1,2,3])``
1222
1216
1223 Parameters
1217 Parameters
1224 ----------
1218 ----------
1225
1219
1226 trait : TraitType [ optional ]
1220 trait : TraitType [ optional ]
1227 the type for restricting the contents of the Container. If unspecified,
1221 the type for restricting the contents of the Container. If unspecified,
1228 types are not checked.
1222 types are not checked.
1229
1223
1230 default_value : SequenceType [ optional ]
1224 default_value : SequenceType [ optional ]
1231 The default value for the Trait. Must be list/tuple/set, and
1225 The default value for the Trait. Must be list/tuple/set, and
1232 will be cast to the container type.
1226 will be cast to the container type.
1233
1227
1234 minlen : Int [ default 0 ]
1228 minlen : Int [ default 0 ]
1235 The minimum length of the input list
1229 The minimum length of the input list
1236
1230
1237 maxlen : Int [ default sys.maxint ]
1231 maxlen : Int [ default sys.maxint ]
1238 The maximum length of the input list
1232 The maximum length of the input list
1239
1233
1240 allow_none : Bool [ default True ]
1234 allow_none : Bool [ default True ]
1241 Whether to allow the value to be None
1235 Whether to allow the value to be None
1242
1236
1243 **metadata : any
1237 **metadata : any
1244 further keys for extensions to the Trait (e.g. config)
1238 further keys for extensions to the Trait (e.g. config)
1245
1239
1246 """
1240 """
1247 self._minlen = minlen
1241 self._minlen = minlen
1248 self._maxlen = maxlen
1242 self._maxlen = maxlen
1249 super(List, self).__init__(trait=trait, default_value=default_value,
1243 super(List, self).__init__(trait=trait, default_value=default_value,
1250 allow_none=allow_none, **metadata)
1244 allow_none=allow_none, **metadata)
1251
1245
1252 def length_error(self, obj, value):
1246 def length_error(self, obj, value):
1253 e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \
1247 e = "The '%s' trait of %s instance must be of length %i <= L <= %i, but a value of %s was specified." \
1254 % (self.name, class_of(obj), self._minlen, self._maxlen, value)
1248 % (self.name, class_of(obj), self._minlen, self._maxlen, value)
1255 raise TraitError(e)
1249 raise TraitError(e)
1256
1250
1257 def validate_elements(self, obj, value):
1251 def validate_elements(self, obj, value):
1258 length = len(value)
1252 length = len(value)
1259 if length < self._minlen or length > self._maxlen:
1253 if length < self._minlen or length > self._maxlen:
1260 self.length_error(obj, value)
1254 self.length_error(obj, value)
1261
1255
1262 return super(List, self).validate_elements(obj, value)
1256 return super(List, self).validate_elements(obj, value)
1263
1257
1264
1258
1265 class Set(Container):
1259 class Set(Container):
1266 """An instance of a Python set."""
1260 """An instance of a Python set."""
1267 klass = set
1261 klass = set
1268
1262
1269 class Tuple(Container):
1263 class Tuple(Container):
1270 """An instance of a Python tuple."""
1264 """An instance of a Python tuple."""
1271 klass = tuple
1265 klass = tuple
1272
1266
1273 def __init__(self, *traits, **metadata):
1267 def __init__(self, *traits, **metadata):
1274 """Tuple(*traits, default_value=None, allow_none=True, **medatata)
1268 """Tuple(*traits, default_value=None, allow_none=True, **medatata)
1275
1269
1276 Create a tuple from a list, set, or tuple.
1270 Create a tuple from a list, set, or tuple.
1277
1271
1278 Create a fixed-type tuple with Traits:
1272 Create a fixed-type tuple with Traits:
1279
1273
1280 ``t = Tuple(Int, Str, CStr)``
1274 ``t = Tuple(Int, Str, CStr)``
1281
1275
1282 would be length 3, with Int,Str,CStr for each element.
1276 would be length 3, with Int,Str,CStr for each element.
1283
1277
1284 If only one arg is given and it is not a Trait, it is taken as
1278 If only one arg is given and it is not a Trait, it is taken as
1285 default_value:
1279 default_value:
1286
1280
1287 ``t = Tuple((1,2,3))``
1281 ``t = Tuple((1,2,3))``
1288
1282
1289 Otherwise, ``default_value`` *must* be specified by keyword.
1283 Otherwise, ``default_value`` *must* be specified by keyword.
1290
1284
1291 Parameters
1285 Parameters
1292 ----------
1286 ----------
1293
1287
1294 *traits : TraitTypes [ optional ]
1288 *traits : TraitTypes [ optional ]
1295 the tsype for restricting the contents of the Tuple. If unspecified,
1289 the tsype for restricting the contents of the Tuple. If unspecified,
1296 types are not checked. If specified, then each positional argument
1290 types are not checked. If specified, then each positional argument
1297 corresponds to an element of the tuple. Tuples defined with traits
1291 corresponds to an element of the tuple. Tuples defined with traits
1298 are of fixed length.
1292 are of fixed length.
1299
1293
1300 default_value : SequenceType [ optional ]
1294 default_value : SequenceType [ optional ]
1301 The default value for the Tuple. Must be list/tuple/set, and
1295 The default value for the Tuple. Must be list/tuple/set, and
1302 will be cast to a tuple. If `traits` are specified, the
1296 will be cast to a tuple. If `traits` are specified, the
1303 `default_value` must conform to the shape and type they specify.
1297 `default_value` must conform to the shape and type they specify.
1304
1298
1305 allow_none : Bool [ default True ]
1299 allow_none : Bool [ default True ]
1306 Whether to allow the value to be None
1300 Whether to allow the value to be None
1307
1301
1308 **metadata : any
1302 **metadata : any
1309 further keys for extensions to the Trait (e.g. config)
1303 further keys for extensions to the Trait (e.g. config)
1310
1304
1311 """
1305 """
1312 default_value = metadata.pop('default_value', None)
1306 default_value = metadata.pop('default_value', None)
1313 allow_none = metadata.pop('allow_none', True)
1307 allow_none = metadata.pop('allow_none', True)
1314
1308
1315 istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
1309 istrait = lambda t: isinstance(t, type) and issubclass(t, TraitType)
1316
1310
1317 # allow Tuple((values,)):
1311 # allow Tuple((values,)):
1318 if len(traits) == 1 and default_value is None and not istrait(traits[0]):
1312 if len(traits) == 1 and default_value is None and not istrait(traits[0]):
1319 default_value = traits[0]
1313 default_value = traits[0]
1320 traits = ()
1314 traits = ()
1321
1315
1322 if default_value is None:
1316 if default_value is None:
1323 args = ()
1317 args = ()
1324 elif isinstance(default_value, self._valid_defaults):
1318 elif isinstance(default_value, self._valid_defaults):
1325 args = (default_value,)
1319 args = (default_value,)
1326 else:
1320 else:
1327 raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
1321 raise TypeError('default value of %s was %s' %(self.__class__.__name__, default_value))
1328
1322
1329 self._traits = []
1323 self._traits = []
1330 for trait in traits:
1324 for trait in traits:
1331 t = trait()
1325 t = trait()
1332 t.name = 'element'
1326 t.name = 'element'
1333 self._traits.append(t)
1327 self._traits.append(t)
1334
1328
1335 if self._traits and default_value is None:
1329 if self._traits and default_value is None:
1336 # don't allow default to be an empty container if length is specified
1330 # don't allow default to be an empty container if length is specified
1337 args = None
1331 args = None
1338 super(Container,self).__init__(klass=self.klass, args=args,
1332 super(Container,self).__init__(klass=self.klass, args=args,
1339 allow_none=allow_none, **metadata)
1333 allow_none=allow_none, **metadata)
1340
1334
1341 def validate_elements(self, obj, value):
1335 def validate_elements(self, obj, value):
1342 if not self._traits:
1336 if not self._traits:
1343 # nothing to validate
1337 # nothing to validate
1344 return value
1338 return value
1345 if len(value) != len(self._traits):
1339 if len(value) != len(self._traits):
1346 e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \
1340 e = "The '%s' trait of %s instance requires %i elements, but a value of %s was specified." \
1347 % (self.name, class_of(obj), len(self._traits), repr_type(value))
1341 % (self.name, class_of(obj), len(self._traits), repr_type(value))
1348 raise TraitError(e)
1342 raise TraitError(e)
1349
1343
1350 validated = []
1344 validated = []
1351 for t,v in zip(self._traits, value):
1345 for t,v in zip(self._traits, value):
1352 try:
1346 try:
1353 v = t.validate(obj, v)
1347 v = t.validate(obj, v)
1354 except TraitError:
1348 except TraitError:
1355 self.element_error(obj, v, t)
1349 self.element_error(obj, v, t)
1356 else:
1350 else:
1357 validated.append(v)
1351 validated.append(v)
1358 return tuple(validated)
1352 return tuple(validated)
1359
1353
1360
1354
1361 class Dict(Instance):
1355 class Dict(Instance):
1362 """An instance of a Python dict."""
1356 """An instance of a Python dict."""
1363
1357
1364 def __init__(self, default_value=None, allow_none=True, **metadata):
1358 def __init__(self, default_value=None, allow_none=True, **metadata):
1365 """Create a dict trait type from a dict.
1359 """Create a dict trait type from a dict.
1366
1360
1367 The default value is created by doing ``dict(default_value)``,
1361 The default value is created by doing ``dict(default_value)``,
1368 which creates a copy of the ``default_value``.
1362 which creates a copy of the ``default_value``.
1369 """
1363 """
1370 if default_value is None:
1364 if default_value is None:
1371 args = ((),)
1365 args = ((),)
1372 elif isinstance(default_value, dict):
1366 elif isinstance(default_value, dict):
1373 args = (default_value,)
1367 args = (default_value,)
1374 elif isinstance(default_value, SequenceTypes):
1368 elif isinstance(default_value, SequenceTypes):
1375 args = (default_value,)
1369 args = (default_value,)
1376 else:
1370 else:
1377 raise TypeError('default value of Dict was %s' % default_value)
1371 raise TypeError('default value of Dict was %s' % default_value)
1378
1372
1379 super(Dict,self).__init__(klass=dict, args=args,
1373 super(Dict,self).__init__(klass=dict, args=args,
1380 allow_none=allow_none, **metadata)
1374 allow_none=allow_none, **metadata)
1381
1375
1382 class TCPAddress(TraitType):
1376 class TCPAddress(TraitType):
1383 """A trait for an (ip, port) tuple.
1377 """A trait for an (ip, port) tuple.
1384
1378
1385 This allows for both IPv4 IP addresses as well as hostnames.
1379 This allows for both IPv4 IP addresses as well as hostnames.
1386 """
1380 """
1387
1381
1388 default_value = ('127.0.0.1', 0)
1382 default_value = ('127.0.0.1', 0)
1389 info_text = 'an (ip, port) tuple'
1383 info_text = 'an (ip, port) tuple'
1390
1384
1391 def validate(self, obj, value):
1385 def validate(self, obj, value):
1392 if isinstance(value, tuple):
1386 if isinstance(value, tuple):
1393 if len(value) == 2:
1387 if len(value) == 2:
1394 if isinstance(value[0], basestring) and isinstance(value[1], int):
1388 if isinstance(value[0], basestring) and isinstance(value[1], int):
1395 port = value[1]
1389 port = value[1]
1396 if port >= 0 and port <= 65535:
1390 if port >= 0 and port <= 65535:
1397 return value
1391 return value
1398 self.error(obj, value)
1392 self.error(obj, value)
General Comments 0
You need to be logged in to leave comments. Login now